Update UI docs and types (#2854)

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

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.

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
 

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

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

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

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

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

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
 

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

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. 

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
 

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
 <html>

src/docs/src/sidebar.js

@@ -791,6 +791,14 @@ let sidebar = [
                 source: '/UI/on.md',
                 path: '/UI/on',
             },
+            {
+                title: '<code>onItemsOpened()</code>',
+                page_title: '<code>puter.ui.onItemsOpened()</code>',
+                title_tag: 'puter.ui.onItemsOpened()',
+                icon: '/assets/img/function.svg',
+                source: '/UI/onItemsOpened.md',
+                path: '/UI/onItemsOpened',
+            },
             {
                 title: '<code>onLaunchedWithItems()</code>',
                 page_title: '<code>puter.ui.onLaunchedWithItems()</code>',

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<string>;
-    prompt (message?: string, placeholder?: string): Promise<string | null>;
+    alert (message?: string, buttons?: AlertButton[], options?: AlertOptions): Promise<string>;
+    prompt (message?: string, placeholder?: string, options?: PromptOptions): Promise<string | null>;
     notify (options?: NotificationOptions): Promise<string>;
     authenticateWithPuter (): Promise<void>;
     contextMenu (options: ContextMenuOptions): void;
-    createWindow (options?: WindowOptions): void;
+    createWindow (options?: WindowOptions): Promise<WindowHandle>;
     exit (statusCode?: number): void;
     getLanguage (): Promise<string>;
     hideSpinner (): void;
     hideWindow (): void;
-    showSpinner (): void;
+    showSpinner (html?: string): void;
     showWindow (): void;
-    showColorPicker (defaultColor?: string | Record<string, unknown>): Promise<string>;
+    showColorPicker (defaultColor?: string): Promise<string>;
+    showColorPicker (options?: ColorPickerOptions): Promise<string>;
     showDirectoryPicker (options?: DirectoryPickerOptions): Promise<FSItem | FSItem[]>;
-    showFontPicker (defaultFont?: string | Record<string, unknown>): Promise<{ fontFamily: string }>;
+    showFontPicker (defaultFont?: string): Promise<{ fontFamily: string }>;
+    showFontPicker (options?: FontPickerOptions): Promise<{ fontFamily: string }>;
     showOpenFilePicker (options?: FilePickerOptions): CancelAwarePromise<FSItem | FSItem[]>;
-    showSaveFilePicker (data?: unknown, defaultFileName?: string): CancelAwarePromise<FSItem>;
+    showSaveFilePicker (
+        content?: unknown,
+        suggestedName?: string,
+    ): CancelAwarePromise<FSItem>;
     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<string, unknown>): Promise<string>;
-    showSaveFilePicker (data?: unknown, defaultFileName?: string): Promise<FSItem>;
+    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;