feat(spec)!: retire the list view's own tabs key; named presets are listViews entries

.changeset/list-view-tabs-retired.md

@@ -0,0 +1,99 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: retire the list view's own `tabs` key — parsed, stored, and drawn by nothing; named presets are `listViews` entries
+
+**BREAKING** — `tabs` is removed from the list view (`ListViewSchema`,
+`ObjectListViewSchema` — a `defineView` container's `list` / `listViews`, an
+object's `listViews` — a view item record's list `config`, and the flattened
+list overlay the `PUT /api/v1/meta/view` door accepts). ADR-0049
+enforce-or-remove; triage verdict RETIRE, on the rule that a capability the
+mainstream has and this platform already delivers keeps ONE spelling.
+
+The key parsed at every list-view door and was stored, and no renderer ever
+drew it. Measured before removal, each reading beside a lit control: a list
+view's own `tabs` has no reader, and objectui's `TabBar` — the one component
+that would draw it — has zero production mounts at the objectui commit this
+repo pins (every occurrence is in its own two test files), while the saved-view
+switcher (`ViewTabBar`) mounts in the object view and is fed from the object's
+`listViews`. That switcher IS the tab strip above an object's records: one tab
+per named list view. `userFilters.tabs` is a different key with the same
+element type: it is read and rendered as a page list's preset bar, and it
+stays. Zero list views in this repo's examples or platform sources authored the
+key; the one published skill example that taught it is corrected here.
+
+### FROM → TO
+
+| removed | what to write instead |
+| --- | --- |
+| a list view's `tabs: [{ name, label, filter, … }]` | one named list view per tab, under the object's `listViews`: the tab's `name` becomes the entry's key, its `label` the entry's `label`, and its `filter` rules join the view's own `filter` on that entry (copy the view's `columns` too). A tab whose `view` already named a list view needs nothing more. |
+| the tab keys `icon`, `order`, `pinned`, `isDefault`, `visible` | nothing — none of them ever had an effect. |
+
+**The one-line fix: delete `tabs:` from every list view, and add a `listViews`
+entry for each tab you want users to switch to.** `os migrate meta --from 17`
+lists the mechanical edits for existing sources; apply them by hand.
+
+```ts
+// before — parsed clean, drew no tab bar
+defineView({
+  object: 'crm_ticket',
+  list: {
+    type: 'grid', columns: ['subject', 'status'],
+    tabs: [{ name: 'open', label: 'Open', filter: [{ field: 'status', operator: 'equals', value: 'open' }] }],
+  },
+});
+// after — the switcher above the records shows "Open" beside the default view
+defineView({
+  object: 'crm_ticket',
+  list: { type: 'grid', columns: ['subject', 'status'] },
+  listViews: {
+    open: {
+      type: 'grid', label: 'Open', columns: ['subject', 'status'],
+      filter: [{ field: 'status', operator: 'equals', value: 'open' }],
+    },
+  },
+});
+```
+
+⛔ **Untouched: the page-only preset bar.** `userFilters: { element: 'tabs',
+tabs: [...] }` on a page list is a different key, it renders, and
+`ViewTabSchema` stays for it.
+
+### The retirement kit
+
+- **A `retiredKey()` tombstone on the list-view shape**, beside the `pageName`
+  tombstone on the same strict shape. Every door built from it refuses: `tsc`
+  types the key `never`, and the parse raises the prescription (which names the
+  move to `listViews`) instead of a bare unknown-key report.
+- **D2 conversion `view-list-tabs-removed`** (protocol 18, retired from the load
+  path): strips `tabs` from every list payload in `stack.views[]`, in all three
+  persisted spellings, as a lossless delete — nothing ever drew the tabs — so a
+  stored `view` row replays clean through the rehydration seam. An object's own
+  `listViews` is reached by no conversion, so such an object is refused at its
+  door until edited by hand.
+- **D3 entry `list-view-tabs-retired`** beside it, carrying the part no
+  conversion can decide: which tabs deserve a `listViews` entry.
+- **`RETIRED_KEYS_BY_MAJOR[18]`**: `ui/ListView:tabs`, `ui/ObjectListView:tabs`;
+  both `authorable-surface/ui.json` rows become `[RETIRED]`.
+- **The metadata form's `tabs` repeater** leaves with the key, and the
+  extracted form-label bundles are regenerated.
+- **The liveness row stays `dead`**, re-verified, with a REMOVED note — the
+  tombstone keeps the key in the walked shape.
+- **The published `objectstack-ui` skill** no longer teaches the key: its
+  list-view rules example and the "tabs win over dropdowns" rule (which
+  described a tab bar that never rendered) are replaced by the `listViews`
+  pointer.
+- **Pins** (`ui/view-list-tabs-retirement.test.ts`): the refusal, its issue
+  code, path and prescription at seven doors, each with a lit control; the tsc
+  channel; the `userFilters.tabs` boundary; the conversion's reach, boundary and
+  idempotence; the D2/D3 registration; and a tree-scoped absence walk over the
+  declared radius.
+- **No deprecation window**, per the project's startup-stage posture.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec`
+is published, so this is breaking for consumers no telemetry was consulted for.
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered view-list-tabs-removed, list-view-tabs-retired -->

content/docs/protocol/objectui/layout-dsl.mdx

@@ -563,10 +563,10 @@ is a **parse failure** — a loud rejection, not a silent no-op.
 </Callout>
 
 Looking for tabs that carry their own `name`, `icon`, `filter`, `order`,
-`pinned` and `isDefault`? That surface exists, but it belongs to **list** views,
-not forms: `ui/ViewTab` declares exactly nine keys (`filter`, `icon`,
-`isDefault`, `label`, `name`, `order`, `pinned`, `view`, `visible`), and each
-tab points at a named list view. See
+`pinned` and `isDefault`? That surface belongs to a **page list's** preset bar
+(`userFilters.tabs`), not to forms: `ui/ViewTab` declares exactly nine keys (`filter`,
+`icon`, `isDefault`, `label`, `name`, `order`, `pinned`, `view`, `visible`). A list
+view has no `tabs` key — an object's tab strip lists its named `listViews`. See
 [View Reference → ViewTab](/docs/references/ui/view#viewtab).
 
 ## Responsive Layout Modifiers

content/docs/references/api/protocol.mdx

@@ -1699,7 +1699,7 @@ The published metadata item body, opaque by ruling (1C). Shape is the item's own
 | **exportOptions** | `Enum<'csv' \| 'xlsx' \| 'json'>[] \| { formats?: Enum<'csv' \| 'xlsx' \| 'json'>[]; maxRecords?: integer; includeHeaders?: boolean; fileNamePrefix?: string; … }` | optional | Export configuration for the list toolbar export menu: `{ formats?, maxRecords?, includeHeaders?, fileNamePrefix?, streaming? }`. A bare format array is the legacy spelling and lifts to `{ formats: [...] }` at parse. |
 | **userActions** | `{ sort?: boolean; search?: boolean; filter?: boolean; refresh?: boolean; … }` | optional | User action toggles for the view toolbar |
 | **appearance** | `{ showDescription?: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration |
-| **tabs** | `{ name: string; label?: string \| Record<string, string>; icon?: string; view?: string; … }[]` | optional | Tab definitions for multi-tab view interface |
+| **tabs** | `never` | optional | [REMOVED] `view.list.tabs` was removed in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — no renderer ever mounted a tab bar for it, so authoring it drew nothing: the tab strip above an object's records is the saved-view switcher (ViewTabBar), which renders one tab per named list view and never read this key. Delete the key, and move each tab you want to a named list view under the object's `listViews` instead: the tab's `name` becomes the entry's key, its `label` the entry's `label`, and its `filter` rules join the view's own `filter` on that entry (copy the view's `columns` too); a tab whose `view` already named a list view needs nothing more. Every `listViews` entry renders as a tab in the switcher. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
 | **addRecord** | `{ enabled?: boolean; position?: Enum<'top' \| 'bottom' \| 'both'>; mode?: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | optional | Add record entry point configuration |
 | **showRecordCount** | `boolean` | optional | Show record count at the bottom of the list |
 | **allowPrinting** | `boolean` | optional | Allow users to print the view |
@@ -1784,7 +1784,7 @@ The published metadata item body, opaque by ruling (1C). Shape is the item's own
 | **exportOptions** | `Enum<'csv' \| 'xlsx' \| 'json'>[] \| { formats?: Enum<'csv' \| 'xlsx' \| 'json'>[]; maxRecords?: integer; includeHeaders?: boolean; fileNamePrefix?: string; … }` | optional | Export configuration for the list toolbar export menu: `{ formats?, maxRecords?, includeHeaders?, fileNamePrefix?, streaming? }`. A bare format array is the legacy spelling and lifts to `{ formats: [...] }` at parse. |
 | **userActions** | `{ sort?: boolean; search?: boolean; filter?: boolean; refresh?: boolean; … }` | optional | User action toggles for the view toolbar |
 | **appearance** | `{ showDescription?: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration |
-| **tabs** | `{ name: string; label?: string \| Record<string, string>; icon?: string; view?: string; … }[]` | optional | Tab definitions for multi-tab view interface |
+| **tabs** | `never` | optional | [REMOVED] `view.list.tabs` was removed in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — no renderer ever mounted a tab bar for it, so authoring it drew nothing: the tab strip above an object's records is the saved-view switcher (ViewTabBar), which renders one tab per named list view and never read this key. Delete the key, and move each tab you want to a named list view under the object's `listViews` instead: the tab's `name` becomes the entry's key, its `label` the entry's `label`, and its `filter` rules join the view's own `filter` on that entry (copy the view's `columns` too); a tab whose `view` already named a list view needs nothing more. Every `listViews` entry renders as a tab in the switcher. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
 | **addRecord** | `{ enabled?: boolean; position?: Enum<'top' \| 'bottom' \| 'both'>; mode?: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | optional | Add record entry point configuration |
 | **showRecordCount** | `boolean` | optional | Show record count at the bottom of the list |
 | **allowPrinting** | `boolean` | optional | Allow users to print the view |

content/docs/references/data/object.mdx

@@ -398,7 +398,7 @@ const result = ApiMethod.parse(data);
 | **exportOptions** | `Enum<'csv' \| 'xlsx' \| 'json'>[] \| { formats?: Enum<'csv' \| 'xlsx' \| 'json'>[]; maxRecords?: integer; includeHeaders?: boolean; fileNamePrefix?: string; … }` | optional | Export configuration for the list toolbar export menu: `{ formats?, maxRecords?, includeHeaders?, fileNamePrefix?, streaming? }`. A bare format array is the legacy spelling and lifts to `{ formats: [...] }` at parse. |
 | **userActions** | `{ sort?: boolean; search?: boolean; filter?: boolean; refresh?: boolean; … }` | optional | User action toggles for the view toolbar |
 | **appearance** | `{ showDescription?: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration |
-| **tabs** | `{ name: string; label?: string \| Record<string, string>; icon?: string; view?: string; … }[]` | optional | Tab definitions for multi-tab view interface |
+| **tabs** | `never` | optional | [REMOVED] `view.list.tabs` was removed in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — no renderer ever mounted a tab bar for it, so authoring it drew nothing: the tab strip above an object's records is the saved-view switcher (ViewTabBar), which renders one tab per named list view and never read this key. Delete the key, and move each tab you want to a named list view under the object's `listViews` instead: the tab's `name` becomes the entry's key, its `label` the entry's `label`, and its `filter` rules join the view's own `filter` on that entry (copy the view's `columns` too); a tab whose `view` already named a list view needs nothing more. Every `listViews` entry renders as a tab in the switcher. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
 | **addRecord** | `{ enabled?: boolean; position?: Enum<'top' \| 'bottom' \| 'both'>; mode?: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | optional | Add record entry point configuration |
 | **showRecordCount** | `boolean` | optional | Show record count at the bottom of the list |
 | **allowPrinting** | `boolean` | optional | Allow users to print the view |