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>',