From da0255a805f8628e8fab22cae2c1ede09df2eae0 Mon Sep 17 00:00:00 2001 From: Reynaldi Chernando <12949382+reynaldichernando@users.noreply.github.com> Date: Mon, 4 May 2026 14:43:24 +0700 Subject: [PATCH] Update UI docs and types (#2854) --- src/docs/src/UI.md | 1 + src/docs/src/UI/alert.md | 6 +++ src/docs/src/UI/setMenubar.md | 16 ++++++- src/docs/src/UI/setWindowHeight.md | 4 ++ src/docs/src/UI/setWindowPosition.md | 4 ++ src/docs/src/UI/setWindowSize.md | 4 ++ src/docs/src/UI/setWindowTitle.md | 4 ++ src/docs/src/UI/setWindowWidth.md | 4 ++ src/docs/src/UI/setWindowX.md | 4 ++ src/docs/src/UI/setWindowY.md | 4 ++ src/docs/src/UI/showOpenFilePicker.md | 1 + src/docs/src/UI/showSaveFilePicker.md | 17 +++++-- src/docs/src/UI/showSpinner.md | 6 +++ src/docs/src/sidebar.js | 8 ++++ src/puter-js/types/modules/ui.d.ts | 67 +++++++++++++++++++-------- 15 files changed, 125 insertions(+), 25 deletions(-) diff --git a/src/docs/src/UI.md b/src/docs/src/UI.md index 7b6e4b104..df8ad0c99 100644 --- a/src/docs/src/UI.md +++ b/src/docs/src/UI.md @@ -39,6 +39,7 @@ The UI API provides a comprehensive set of tools for creating rich user interfac ### Event Handling - **[`puter.ui.on()`](/UI/on/)** - Register event handlers +- **[`puter.ui.onItemsOpened()`](/UI/onItemsOpened/)** - Handle items opened by user action - **[`puter.ui.onLaunchedWithItems()`](/UI/onLaunchedWithItems/)** - Handle launch with items - **[`puter.ui.wasLaunchedWithItems()`](/UI/wasLaunchedWithItems/)** - Check if launched with items - **[`puter.ui.onWindowClose()`](/UI/onWindowClose/)** - Handle window close events diff --git a/src/docs/src/UI/alert.md b/src/docs/src/UI/alert.md index c06c1181f..a211c8a39 100755 --- a/src/docs/src/UI/alert.md +++ b/src/docs/src/UI/alert.md @@ -12,6 +12,7 @@ Displays an alert dialog by Puter. Puter improves upon the traditional browser a ```js puter.ui.alert(message) puter.ui.alert(message, buttons) +puter.ui.alert(message, buttons, options) ``` ## Parameters @@ -22,6 +23,11 @@ A string to be displayed in the alert dialog. If not set, the dialog will be emp #### `buttons` (optional) An array of objects that define the buttons to be displayed in the alert dialog. Each object must have a `label` property. The `value` property is optional. If it is not set, the `label` property will be used as the value. The `type` property is optional and can be set to `primary`, `success`, `info`, `warning`, or `danger`. If it is not set, the default type will be used. +#### `options` (optional) +A set of key/value pairs that configure the alert dialog. + +* `type` (String): Visual style of the alert dialog. One of `primary`, `success`, `info`, `warning`, or `danger`. + ## Return value A `Promise` that resolves to the value of the button pressed. If the `value` property of button is set it is returned, otherwise `label` property will be returned. diff --git a/src/docs/src/UI/setMenubar.md b/src/docs/src/UI/setMenubar.md index 3b26900b4..a4b8e7409 100755 --- a/src/docs/src/UI/setMenubar.md +++ b/src/docs/src/UI/setMenubar.md @@ -16,7 +16,7 @@ puter.ui.setMenubar(options) #### `options.items` (Array) -An array of menu items. Each item can be a menu or a menu item. Each menu item can have a label, an action, and a submenu. An item can also be the string `-`, which indicates a separator. +An array of menu items. Each item can be a menu or a menu item. Each menu item can have a label, an action, and a submenu. An item can also be the string `'-'`, which indicates a separator (renders as a horizontal divider between groups of items). #### `options.items.label` (String) @@ -32,7 +32,19 @@ An array of submenu items. #### `options.items.disabled` (Boolean) -Indicates whether the menu item is disabled. +Indicates whether the menu item is disabled. Disabled items are visible but cannot be clicked. + +#### `options.items.checked` (Boolean) + +If `true`, renders a checkmark next to the menu item. Use for toggleable options. + +#### `options.items.icon` (String) + +URL or data URI of an icon shown next to the menu item label. + +#### `options.items.icon_active` (String) + +URL or data URI of an icon shown when the menu item is hovered or active. Falls back to `icon` if not provided. ## Examples diff --git a/src/docs/src/UI/setWindowHeight.md b/src/docs/src/UI/setWindowHeight.md index f0a9ea8de..a4054e70e 100755 --- a/src/docs/src/UI/setWindowHeight.md +++ b/src/docs/src/UI/setWindowHeight.md @@ -9,6 +9,7 @@ Allows the user to dynamically set the height of the window. ## Syntax ```js puter.ui.setWindowHeight(height) +puter.ui.setWindowHeight(height, window_id) ``` ## Parameters @@ -16,6 +17,9 @@ puter.ui.setWindowHeight(height) #### `height` (Float) The new height for this window. Must be a positive number. Minimum height is 200px, if a value less than 200 is provided, the height will be set to 200px. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/setWindowPosition.md b/src/docs/src/UI/setWindowPosition.md index 579d8fb06..8c54aab67 100755 --- a/src/docs/src/UI/setWindowPosition.md +++ b/src/docs/src/UI/setWindowPosition.md @@ -9,6 +9,7 @@ Allows the user to set the position of the window. ## Syntax ```js puter.ui.setWindowPosition(x, y) +puter.ui.setWindowPosition(x, y, window_id) ``` ## Parameters @@ -19,6 +20,9 @@ The new x position for this window. Must be a positive number. #### `y` (Float) The new y position for this window. Must be a positive number. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/setWindowSize.md b/src/docs/src/UI/setWindowSize.md index 1c38d3876..3b661a15d 100755 --- a/src/docs/src/UI/setWindowSize.md +++ b/src/docs/src/UI/setWindowSize.md @@ -9,6 +9,7 @@ Allows the user to dynamically set the width and height of the window. ## Syntax ```js puter.ui.setWindowSize(width, height) +puter.ui.setWindowSize(width, height, window_id) ``` ## Parameters @@ -19,6 +20,9 @@ The new width for this window. Must be a positive number. Minimum width is 200px #### `height` (Float) The new height for this window. Must be a positive number. Minimum height is 200px, if a value less than 200 is provided, the height will be set to 200px. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/setWindowTitle.md b/src/docs/src/UI/setWindowTitle.md index d4c533956..f1048e31e 100755 --- a/src/docs/src/UI/setWindowTitle.md +++ b/src/docs/src/UI/setWindowTitle.md @@ -9,6 +9,7 @@ Allows the user to dynamically set the title of the window. ## Syntax ```js puter.ui.setWindowTitle(title) +puter.ui.setWindowTitle(title, window_id) ``` ## Parameters @@ -16,6 +17,9 @@ puter.ui.setWindowTitle(title) #### `title` (String) The new title for this window. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/setWindowWidth.md b/src/docs/src/UI/setWindowWidth.md index 921c4094a..15f1cda60 100755 --- a/src/docs/src/UI/setWindowWidth.md +++ b/src/docs/src/UI/setWindowWidth.md @@ -9,6 +9,7 @@ Allows the user to dynamically set the width of the window. ## Syntax ```js puter.ui.setWindowWidth(width) +puter.ui.setWindowWidth(width, window_id) ``` ## Parameters @@ -16,6 +17,9 @@ puter.ui.setWindowWidth(width) #### `width` (Float) The new width for this window. Must be a positive number. Minimum width is 200px, if a value less than 200 is provided, the width will be set to 200px. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/setWindowX.md b/src/docs/src/UI/setWindowX.md index cd1aabfb9..bbe653957 100755 --- a/src/docs/src/UI/setWindowX.md +++ b/src/docs/src/UI/setWindowX.md @@ -9,6 +9,7 @@ Sets the X position of the window. ## Syntax ```js puter.ui.setWindowX(x) +puter.ui.setWindowX(x, window_id) ``` ## Parameters @@ -16,6 +17,9 @@ puter.ui.setWindowX(x) #### `x` (Float) (Required) The new x position for this window. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples diff --git a/src/docs/src/UI/setWindowY.md b/src/docs/src/UI/setWindowY.md index cfd8ed827..d63cbe07a 100755 --- a/src/docs/src/UI/setWindowY.md +++ b/src/docs/src/UI/setWindowY.md @@ -9,6 +9,7 @@ Sets the y position of the window. ## Syntax ```js puter.ui.setWindowY(y) +puter.ui.setWindowY(y, window_id) ``` ## Parameters @@ -16,6 +17,9 @@ puter.ui.setWindowY(y) #### `y` (Float) (Required) The new y position for this window. +#### `window_id` (optional) +Targets a specific window other than the app's main window. Accepts either a window id string or a window handle returned by [`puter.ui.createWindow()`](/UI/createWindow/) (an object with an `id` property). When omitted, the app's main window is used. + ## Examples ```html diff --git a/src/docs/src/UI/showOpenFilePicker.md b/src/docs/src/UI/showOpenFilePicker.md index d7bce2bc4..f1534250e 100755 --- a/src/docs/src/UI/showOpenFilePicker.md +++ b/src/docs/src/UI/showOpenFilePicker.md @@ -20,6 +20,7 @@ A set of key/value pairs that configure the file picker dialog. * `accept` (String): The list of MIME types or file extensions that are accepted by the file picker. Default is `*/*`. - Example: `image/*` will allow the user to select any image file. - Example: `['.jpg', '.png']` will allow the user to select files with `.jpg` or `.png` extensions. +* `path` (String): The initial directory to open the file picker in. Default is the user's Desktop. The special prefix `%appdata%` resolves to your app's private appdata directory (for example, `%appdata%/saves` opens that subdirectory inside your appdata). ## Return value A `Promise` that resolves to either one [`FSItem`](/Objects/fsitem) or an array of [`FSItem`](/Objects/fsitem) objects, depending on how many files were selected by the user. diff --git a/src/docs/src/UI/showSaveFilePicker.md b/src/docs/src/UI/showSaveFilePicker.md index 5b717587a..1eab3262c 100755 --- a/src/docs/src/UI/showSaveFilePicker.md +++ b/src/docs/src/UI/showSaveFilePicker.md @@ -7,14 +7,25 @@ platforms: [websites, apps] Presents the user with a file picker dialog allowing them to specify where and with what name to save a file. ## Syntax + ```js puter.ui.showSaveFilePicker() -puter.ui.showSaveFilePicker(data, defaultFileName) +puter.ui.showSaveFilePicker(content, suggestedName) ``` ## Parameters -#### `defaultFileName` (String) -The default file name to use. + +#### `content` (String) (Optional) + +The data to write to the chosen file. + +#### `suggestedName` (String) (Optional) + +The default file name to pre-fill in the dialog. + +## Return value + +A `Promise` that resolves to an [`FSItem`](/Objects/fsitem) describing the saved file. If the user cancels, the promise stays pending. ## Examples diff --git a/src/docs/src/UI/showSpinner.md b/src/docs/src/UI/showSpinner.md index c4930f848..084292633 100644 --- a/src/docs/src/UI/showSpinner.md +++ b/src/docs/src/UI/showSpinner.md @@ -9,8 +9,14 @@ Shows an overlay with a spinner in the center of the screen. If multiple instanc ## Syntax ```js puter.ui.showSpinner() +puter.ui.showSpinner(html) ``` +## Parameters + +#### `html` (String) (optional) +Custom message rendered under the spinner. Accepts plain text or HTML. Defaults to `"Working..."`. + ## Examples ```html;ui-spinner diff --git a/src/docs/src/sidebar.js b/src/docs/src/sidebar.js index c40e132f8..e33a256e1 100755 --- a/src/docs/src/sidebar.js +++ b/src/docs/src/sidebar.js @@ -791,6 +791,14 @@ let sidebar = [ source: '/UI/on.md', path: '/UI/on', }, + { + title: 'onItemsOpened()', + page_title: 'puter.ui.onItemsOpened()', + title_tag: 'puter.ui.onItemsOpened()', + icon: '/assets/img/function.svg', + source: '/UI/onItemsOpened.md', + path: '/UI/onItemsOpened', + }, { title: 'onLaunchedWithItems()', page_title: 'puter.ui.onLaunchedWithItems()', diff --git a/src/puter-js/types/modules/ui.d.ts b/src/puter-js/types/modules/ui.d.ts index 511449b94..addc98147 100644 --- a/src/puter-js/types/modules/ui.d.ts +++ b/src/puter-js/types/modules/ui.d.ts @@ -6,6 +6,14 @@ export interface AlertButton { type?: 'primary' | 'success' | 'info' | 'warning' | 'danger'; } +export interface AlertOptions { + type?: 'primary' | 'success' | 'info' | 'warning' | 'danger'; +} + +export interface PromptOptions { + defaultValue?: string; +} + export interface ContextMenuItem { label: string; action?: () => void; @@ -15,6 +23,12 @@ export interface ContextMenuItem { items?: (ContextMenuItem | '-')[]; } +export interface WindowHandle { + id: string; +} + +export type WindowIdentifier = string | WindowHandle; + export interface ContextMenuOptions { items: (ContextMenuItem | '-')[]; } @@ -29,8 +43,6 @@ export interface WindowOptions { show_in_taskbar?: boolean; title?: string; width?: number; - x?: number; - y?: number; } export interface LaunchAppOptions { @@ -54,20 +66,32 @@ export interface ThemeData { } export interface MenubarOptions { - items: MenuItem[]; + items: (MenuItem | '-')[]; } export interface MenuItem { label: string; + id?: string; action?: () => void; - items?: MenuItem[]; + items?: (MenuItem | '-')[]; icon?: string; + icon_active?: string; checked?: boolean; + disabled?: boolean; } export interface FilePickerOptions { multiple?: boolean; accept?: string | string[]; + path?: string; +} + +export interface ColorPickerOptions { + defaultColor?: string; +} + +export interface FontPickerOptions { + defaultFont?: string; } export interface DirectoryPickerOptions { @@ -121,37 +145,40 @@ export class AppConnection { } export class UI { - alert (message?: string, buttons?: AlertButton[]): Promise; - prompt (message?: string, placeholder?: string): Promise; + alert (message?: string, buttons?: AlertButton[], options?: AlertOptions): Promise; + prompt (message?: string, placeholder?: string, options?: PromptOptions): Promise; notify (options?: NotificationOptions): Promise; authenticateWithPuter (): Promise; contextMenu (options: ContextMenuOptions): void; - createWindow (options?: WindowOptions): void; + createWindow (options?: WindowOptions): Promise; exit (statusCode?: number): void; getLanguage (): Promise; hideSpinner (): void; hideWindow (): void; - showSpinner (): void; + showSpinner (html?: string): void; showWindow (): void; - showColorPicker (defaultColor?: string | Record): Promise; + showColorPicker (defaultColor?: string): Promise; + showColorPicker (options?: ColorPickerOptions): Promise; showDirectoryPicker (options?: DirectoryPickerOptions): Promise; - showFontPicker (defaultFont?: string | Record): Promise<{ fontFamily: string }>; + showFontPicker (defaultFont?: string): Promise<{ fontFamily: string }>; + showFontPicker (options?: FontPickerOptions): Promise<{ fontFamily: string }>; showOpenFilePicker (options?: FilePickerOptions): CancelAwarePromise; - showSaveFilePicker (data?: unknown, defaultFileName?: string): CancelAwarePromise; + showSaveFilePicker ( + content?: unknown, + suggestedName?: string, + ): CancelAwarePromise; socialShare (url: string, message?: string, options?: { left?: number; top?: number }): void; setMenubar (options: MenubarOptions): void; setMenuItemIcon (itemId: string, icon: string): void; setMenuItemIconActive (itemId: string, icon: string): void; setMenuItemChecked (itemId: string, checked: boolean): void; - setWindowHeight (height: number): void; - setWindowPosition (x: number, y: number): void; - setWindowSize (width: number, height: number): void; - setWindowTitle (title: string): void; - setWindowWidth (width: number): void; - setWindowX (x: number): void; - setWindowY (y: number): void; - showColorPicker (options?: Record): Promise; - showSaveFilePicker (data?: unknown, defaultFileName?: string): Promise; + setWindowHeight (height: number, window_id?: WindowIdentifier): void; + setWindowPosition (x: number, y: number, window_id?: WindowIdentifier): void; + setWindowSize (width: number, height: number, window_id?: WindowIdentifier): void; + setWindowTitle (title: string, window_id?: WindowIdentifier): void; + setWindowWidth (width: number, window_id?: WindowIdentifier): void; + setWindowX (x: number, window_id?: WindowIdentifier): void; + setWindowY (y: number, window_id?: WindowIdentifier): void; wasLaunchedWithItems (): boolean; onItemsOpened (handler: (items: FSItem[]) => void): void; onLaunchedWithItems (handler: (items: FSItem[]) => void): void;