docs(empty-state): document the declared empty-state link and the list page's own emptyState; changeset

Claude-Session: https://claude.ai/code/session_01CsyMRsFJBKNEMa4oPY1b5z
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/12270-empty-state-link.md

@@ -0,0 +1,19 @@
+---
+'@object-ui/components': minor
+'@object-ui/plugin-list': minor
+'@object-ui/plugin-grid': minor
+'@object-ui/app-shell': minor
+---
+
+An empty list draws its declared link, and a list page's own empty state wins over its source view's (objectui#12270).
+
+`@objectstack/spec` 18 gives the empty state (`EmptyStateSchema`) one optional `link: { label, url }`, and a list page's `interfaceConfig` an `emptyState` of its own with that shape. Both parsed and neither was drawn:
+
+- a list view's empty state (`ListView`, on its `grid` and `gallery` visualizations) and the `object-grid` block's authored empty state now draw the link, beside the add-record action where the view offers one;
+- a list page's own `interfaceConfig.emptyState` now wins, whole, over the one its source view declares, on every visualization; the source view's is the fallback when the page declares none.
+
+The link is followed as a `type: 'url'` action through the action runner, so it opens what such an action opens: an in-app path in place, an `http(s)://` address as the runner opens an external target, and `mailto:` in place. The runner refuses anything else at the click and reports it. The link's `label` takes a string or an inline locale map.
+
+`@object-ui/components` exports `EmptyStateLink`, the one component every empty state draws the link with.
+
+**Clause-②: yes (widening)** — the renderers start honouring two keys the spec declares (`emptyState.link`, `interfaceConfig.emptyState`), so what they draw widens. No existing key changes.

content/docs/api/schema-reference.md

@@ -827,7 +827,7 @@ the spec's row did not declare until objectstack#20694; it is authorable in the
 | `frozenColumns` | `number` | Number of columns frozen on scroll. |
 | `conditionalFormatting` | `ConditionalFormattingRule[]` | Row styling rules, each `{ condition, style }` — a CEL `condition` over the row's `record.*` and a CSS `style` map, the rule a list view declares; the first matching rule styles the row. The native `{ field, operator, value }` rule, its `expression`, and a colour written beside `condition` (rather than inside `style`) are retired (objectui#11533): `@object-ui/types` refuses them by name on `ObjectGridSchema`, the `object-view` `table` slot and `list-view`. `{ field: 'priority', operator: 'equals', value: 'high', backgroundColor: '#fee2e2' }` is `{ condition: "record.priority == 'high'", style: { backgroundColor: '#fee2e2' } }`. In an authored node's `properties` bag the member is `@objectstack/spec`'s row member, judged by the installed spec. A grid stored with a retired rule still paints it. |
 | `navigation` | `ViewNavigationConfig` | SPA navigation configuration. |
-| `emptyState` | `EmptyState` — `{ title?, message?, icon? }` | Drawn in place of an empty table: a Lucide `icon`, a `title` (default: the table's "No results found") and a `message` (default: none). `title` and `message` are `string \| I18nLabel`, each resolved against the display locale; a map with no usable entry keeps that member's default. Not drawn when a term in the grid's own server-side search box emptied it — the table and its search box stay (objectui#11068). Authored in the `properties` bag: the spec's row declares it as the list view's own `EmptyStateSchema` (objectstack#20694, objectui#11227). |
+| `emptyState` | `EmptyState` — `{ title?, message?, icon?, link? }` | Drawn in place of an empty table: a Lucide `icon`, a `title` (default: the table's "No results found"), a `message` (default: none) and one `link: { label, url }` the user follows (default: none), opened as a `type: 'url'` action opens it, through the action runner (objectui#12270). `title`, `message` and the link's `label` are `string \| I18nLabel`, each resolved against the display locale; a map with no usable entry keeps that member's default. Not drawn when a term in the grid's own server-side search box emptied it — the table and its search box stay (objectui#11068). Authored in the `properties` bag: the spec's row declares it as the list view's own `EmptyStateSchema` (objectstack#20694, objectui#11227). |
 
 > **`name`, `placeholder`, `rowSpecActions` and `bulkSpecActions` are retired on
 > this node (objectui#11068).** Nothing ever read them: `rowSpecActions` /

content/docs/plugins/plugin-grid.mdx

@@ -94,7 +94,7 @@ below for why this plugin deliberately does not claim it.
 | `columns` | `string[] \| ListColumn[]` | Field names or column objects — see below. |
 | `label` | `I18nLabel` | Table caption and export file title. |
 | `description` | `I18nLabel` | One line of help text above the grid — see `description` and `emptyState` below. |
-| `emptyState` | `EmptyState` (`@objectstack/spec/ui`) | `{ title?, message?, icon? }`, drawn in place of an empty table — see below. |
+| `emptyState` | `EmptyState` (`@objectstack/spec/ui`) | `{ title?, message?, icon?, link? }`, drawn in place of an empty table — see below. |
 | `filter` | `ViewFilterRule[]` | Baked into the query, lowered to `$filter`. |
 | `sort` | `[{ field, order }]` | Initial order; a header click replaces it. |
 | `pagination` | `PaginationConfig` | `{ pageSize?, pageSizeOptions? }` — **strict**, and its presence is what enables paging. |
@@ -123,15 +123,21 @@ row declares both (objectstack#20694), so both are bag members and both are in
 
 - `description` — one line of help text drawn above the grid. A string, or an
   inline locale map resolved against the display locale the way `label` is.
-- `emptyState: { title?, message?, icon? }` — the list view's own empty-state
-  shape (`EmptyState`), drawn **in place of** an empty table: a Lucide `icon`, a
-  `title` (default: the table's own "No results found") and a `message`
-  (default: none). `title` and `message` each take a string or an inline locale
-  map, resolved against the display locale; a map with no usable entry keeps
-  that member's default. It is not drawn when a term typed into the grid's own
-  server-side search box is what emptied it — the table and its search box stay,
-  so the term can be cleared. Leave the key out and an empty grid draws the
-  table's own empty row, as before.
+- `emptyState: { title?, message?, icon?, link? }` — the list view's own
+  empty-state shape (`EmptyState`), drawn **in place of** an empty table: a
+  Lucide `icon`, a `title` (default: the table's own "No results found"), a
+  `message` (default: none) and one `link: { label, url }` the user follows
+  (default: none; objectui#12270). `title`, `message` and the link's `label`
+  each take a string or an inline locale map, resolved against the display
+  locale; a map with no usable entry keeps that member's default, and a link
+  whose label resolves to no text is not drawn. The link is followed as a
+  `type: 'url'` action through the action runner, so it opens what such an
+  action opens: an in-app path (`/…` or `./…`) in place, an `http(s)://`
+  address as the runner opens an external target, and `mailto:` in place; the
+  runner refuses anything else at the click and reports it. It is not drawn when
+  a term typed into the grid's own server-side search box is what emptied it —
+  the table and its search box stay, so the term can be cleared. Leave the key
+  out and an empty grid draws the table's own empty row, as before.
 
 ```json
 {
@@ -142,7 +148,8 @@ row declares both (objectstack#20694), so both are bag members and both are in
     "emptyState": {
       "title": { "en": "No contacts yet", "fr": "Aucun contact" },
       "message": "Add one to get started",
-      "icon": "users"
+      "icon": "users",
+      "link": { "label": "How contacts work", "url": "/docs/contacts" }
     }
   }
 }

packages/plugin-grid/README.md

@@ -200,7 +200,7 @@ const grid: ObjectGridBlockNode = {
 | `columns` | `string[] \| ListColumn[]` | Field names or column objects — see below. |
 | `label` | `I18nLabel` | Table caption and export title. |
 | `description` | `I18nLabel` | One line of help text above the grid — see `description` and `emptyState` below. |
-| `emptyState` | `EmptyState` (`@objectstack/spec/ui`) | `{ title?, message?, icon? }`, drawn in place of an empty table — see below. |
+| `emptyState` | `EmptyState` (`@objectstack/spec/ui`) | `{ title?, message?, icon?, link? }`, drawn in place of an empty table — see below. |
 | `filter` | `ViewFilterRule[]` | Lowered to `$filter`. |
 | `sort` | `[{ field, order }]` | Initial order; a header click replaces it. |
 | `pagination` | `PaginationConfig` | `{ pageSize?, pageSizeOptions? }` — **strict**, and its presence is what enables paging. |
@@ -229,15 +229,21 @@ row declares both (objectstack#20694), so both are bag members and both are in
 
 - `description` — one line of help text drawn above the grid. A string, or an
   inline locale map resolved against the display locale the way `label` is.
-- `emptyState: { title?, message?, icon? }` — the list view's own empty-state
-  shape (`EmptyState`), drawn **in place of** an empty table: a Lucide `icon`, a
-  `title` (default: the table's own "No results found") and a `message`
-  (default: none). `title` and `message` each take a string or an inline locale
-  map, resolved against the display locale; a map with no usable entry keeps
-  that member's default. It is not drawn when a term typed into the grid's own
-  server-side search box is what emptied it — the table and its search box stay,
-  so the term can be cleared. Leave the key out and an empty grid draws the
-  table's own empty row, as before.
+- `emptyState: { title?, message?, icon?, link? }` — the list view's own
+  empty-state shape (`EmptyState`), drawn **in place of** an empty table: a
+  Lucide `icon`, a `title` (default: the table's own "No results found"), a
+  `message` (default: none) and one `link: { label, url }` the user follows
+  (default: none; objectui#12270). `title`, `message` and the link's `label`
+  each take a string or an inline locale map, resolved against the display
+  locale; a map with no usable entry keeps that member's default, and a link
+  whose label resolves to no text is not drawn. The link is followed as a
+  `type: 'url'` action through the action runner, so it opens what such an
+  action opens: an in-app path (`/…` or `./…`) in place, an `http(s)://`
+  address as the runner opens an external target, and `mailto:` in place; the
+  runner refuses anything else at the click and reports it. It is not drawn when
+  a term typed into the grid's own server-side search box is what emptied it —
+  the table and its search box stay, so the term can be cleared. Leave the key
+  out and an empty grid draws the table's own empty row, as before.
 
 ```json
 {
@@ -248,7 +254,8 @@ row declares both (objectstack#20694), so both are bag members and both are in
     "emptyState": {
       "title": { "en": "No contacts yet", "fr": "Aucun contact" },
       "message": "Add one to get started",
-      "icon": "users"
+      "icon": "users",
+      "link": { "label": "How contacts work", "url": "/docs/contacts" }
     }
   }
 }

packages/plugin-list/README.md

@@ -246,6 +246,47 @@ const viewTypes: Record<NonNullable<ListViewSchema['viewType']>, string> = {
 export { view, richColumns, viewTypes };
 ```
 
+## Empty state
+
+When the `grid` or `gallery` visualization has no record to show, the view
+draws its `emptyState` (the spec's `EmptyState`): a Lucide `icon`, a `title`, a
+`message` and one `link: { label, url }` the user follows, such as the how-to
+page that explains what belongs in the list (objectui#12270). A member left out
+keeps the localized default copy; `title`, `message` and the link's `label`
+each take a string or an inline locale map, resolved against the display
+locale.
+
+The link is followed as a `type: 'url'` action through the action runner, so it
+opens what such an action opens: an in-app path (`/…` or `./…`) in place, an
+`http(s)://` address as the runner opens an external target, and `mailto:` in
+place. The runner refuses anything else at the click and reports it. The link
+is drawn beside the add-record action when the view's `addRecord` block offers
+one; the two are separate, and either, both or neither may be drawn.
+
+```typescript
+import type { ListViewSchema } from '@object-ui/types';
+
+const emptyTasks: ListViewSchema = {
+  type: 'list-view',
+  objectName: 'tasks',
+  viewType: 'grid',
+  columns: ['title'],
+  emptyState: {
+    title: 'No open tasks',
+    message: 'Tasks assigned to you appear here.',
+    icon: 'inbox',
+    link: { label: 'How tasks are assigned', url: '/docs/tasks' },
+  },
+};
+
+export { emptyTasks };
+```
+
+A list page (`interfaceConfig` of a `type: 'list'` page) may declare its own
+`emptyState` of the same shape. The page's own block wins, whole, over the one
+its source view declares, on every visualization; the source view's is the
+fallback when the page declares none.
+
 ## Page size and fetch batch
 
 A list view asks the server for one window of records. When