# Storage Browser

Browse connected storage, manage files and folders, and drag snapshots into the App’s Files list.

## Add it to an app

1. Open the app builder and find **Storage Browser** in the component palette.
2. Insert it into the intended region or container.
3. Set its properties in the inspector. Use a literal for a fixed value or a binding for a value supplied by the app.
4. Connect its events where the app should respond to a user gesture.
5. Preview with representative data and save after resolving validation problems.

The type name in the builder’s code view is `storage_browser`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Allowed operations (`allowedOperations`) | list of "create_file" / "create_folder" / "upload" / "rename" / "delete" / "copy" / "move" / "import" | No | ["create_file","create_folder","upload","rename","delete","copy","move","import"] | Literal only; do not use an expression binding. The listed default is inserted when adding a new component. |
| Selected connection IDs (`connectionIds`) | list of string; pattern `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | No | [] | Literal only; do not use an expression binding. Used when connectionMode is 'selected'. The listed default is inserted when adding a new component. |
| Connections: allVisible or selected (`connectionMode`) | "allVisible" / "selected" | No | "allVisible" | Literal only; do not use an expression binding. The listed default is inserted when adding a new component. |
| Target File Upload component ID (`targetFileListId`) | string; pattern `^$\|^[A-Za-z][A-Za-z0-9_]{0,63}$` | No | "" | Literal only; do not use an expression binding. The file_upload that receives dragged snapshots. The listed default is inserted when adding a new component. |

### Layout controls

Additional host-rendered controls: `sectionTitle`. These control the surrounding component region rather than the record values.

## Values available to bindings

| Value | Type | Initial value | Meaning |
| --- | --- | --- | --- |
| `operationId` | string | "" | The last started or finished operation. |
| `selectedItems` | list of object | [] | The dragged items [{item_id, revision, name}]. |
| `status` | string | "idle" | That operation's job status. |

Refer to these values through `components.<component-id>.<value>` in a binding. Use the identifier assigned to this instance of Storage Browser, not the component type name.

## Events

- `onOperationFinished` — A storage operation reached a terminal status.

- `onOperationStarted` — A storage operation was submitted.

Connect only the actions the app needs. An event can fetch results, run an enabled data source, set state, update another component, show a notification, or navigate where supported.

## Keyboard and accessible labels

- Escape cancels a pending action

## Example: Every visible connection, dragging into the Files list

| Setting | Example value |
| --- | --- |
| `connectionMode` | "allVisible" |
| `sectionTitle` | "Storage" |
| `targetFileListId` | "FileDrop" |

## Example: One connection, folders and renames only

| Setting | Example value |
| --- | --- |
| `allowedOperations` | ["create_folder","rename","delete"] |
| `connectionIds` | ["6f1c2b9e-3d4a-4f5b-8c7d-9e0a1b2c3d4e"] |
| `connectionMode` | "selected" |

When `onOperationFinished` occurs, the example performs:

- `showNotification` with {"message":"Storage updated"}

## If it is empty or unavailable

Check the source binding, the selected item, and the app’s access. A hosted document, table, review, or storage component needs the corresponding app capability; an offline preview cannot supply live private data. A source running with no results is different from an invalid binding. Inspect the app’s workflow and data source before changing the presentation.