# Tables Panel

Sidebar list of the app's data tables with create, rename, and column editing.

## Add it to an app

1. Open the app builder and find **Tables Panel** 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 `tables_list`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Enable saved table refresh (requires onRefreshTable) (`allowDataRefresh`) | boolean | No | Not specified | — |
| Backfill run error (`backfillError`) | string | No | Not specified | Supports expression bindings. |
| Backfill run status (`backfillStatus`) | string | No | Not specified | Supports expression bindings. |
| Group creation actions in New table menu (`creationMenu`) | boolean | No | Not specified | — |
| Editor surface ('inline'\|'overlay' — literal) (`editorSurface`) | "inline" / "overlay" | No | Not specified | Literal only; do not use an expression binding. |
| Empty-state text (`emptyText`) | string | No | Not specified | — |
| Header actions (`headerActions`) | list of object | No | Not specified | Supports expression bindings. |
| busy (`headerActions[].busy`) | boolean | No | Not specified | — |
| disabled (`headerActions[].disabled`) | boolean | No | Not specified | — |
| id (`headerActions[].id`) | string | Yes | Not specified | — |
| items (`headerActions[].items`) | list of object | No | Not specified | — |
| label (`headerActions[].label`) | string | Yes | Not specified | — |
| Row id key (`idKey`) | string | No | "id" | Supports expression bindings. The listed default is inserted when adding a new component. |
| Acknowledged upload ingest ID (`initialDraftIngestId`) | string | No | Not specified | Supports expression bindings. |
| Initial draft discovery refresh token (`initialDraftRefreshToken`) | string or null | No | Not specified | Supports expression bindings. |
| Automatic initial draft source ID (`initialDraftSourceId`) | string | No | Not specified | The draft source whose server-created first table review this list recovers. |
| Upload status that rearms initial draft discovery (`initialDraftUploadStatus`) | string | No | Not specified | Supports expression bindings. |
| Row name key (`nameKey`) | string | No | "name" | Supports expression bindings. The listed default is inserted when adding a new component. |
| Update behavior ('run'\|'review') (`refreshMode`) | "run" / "review" | No | Not specified | — |
| Refresh token (`refreshToken`) | string or null | No | Not specified | Supports expression bindings. A new non-empty value refreshes the listing. |
| Explicit document navigation revision (`selectionRevision`) | integer or null | No | Not specified | Supports expression bindings. A new value stops initial-draft discovery from taking over the view. |
| Tables (`tables`) | list of object | No | Not specified | Supports expression bindings. Authored rows, listed before the fetched user tables. |
| Section label (`title`) | string | No | "Tables" | 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 |
| --- | --- | --- | --- |
| `columnRefresh` | object or null | null | The plan to refill a table after a column was added. |
| `headerAction` | object or null | null | The clicked header action {id, revision}. |
| `initialDraftRequest` | object or null | null | The discovered initial draft {draftId, sourceId, sourceKeys, referenceSourceKey, revision}. |
| `lastCreatedId` | string | "" | The table the create form made. |
| `openRequest` | object or null | null | Open this table: {id, label, revision, columns?}, revision strictly increasing. |
| `selectedTableId` | string | "" | The clicked table. |

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

## Events

- `onColumnsUpdated` — A table's columns were saved.

- `onCreateError` — A create failed.

- `onHeaderAction` — A header action was clicked.

- `onInitialDraft` — The initial draft was discovered.

- `onRefreshTable` — A saved table's data refresh was confirmed.

- `onSelectTable` — A table row was clicked.

- `onTableCreated` — The create form made a table.

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 closes the open form

Updates are announced through the component’s live status region.

## Example: Sidebar Tables section

| Setting | Example value |
| --- | --- |
| `refreshToken` | "{{ app.tableRevision }}" |
| `sectionTitle` | "Tables" |
| `title` | "" |

When `onTableCreated` occurs, the example performs:

- `showNotification` with {"message":"Table created","variant":"success"}

## Example: Tables workbench: review mode with a creation menu

| Setting | Example value |
| --- | --- |
| `allowDataRefresh` | true |
| `creationMenu` | true |
| `editorSurface` | "overlay" |
| `headerActions` | [{"id":"generate","label":"From documents"}] |
| `refreshMode` | "review" |
| `sectionTitle` | "Tables" |

When `onRefreshTable` occurs, the example performs:

- `triggerDataSource` with {"dataSourceId":"draft","mode":"run"}

## 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.