@ds-mo/ui 14.7.0 → 14.9.0

package/dist/lib/utils/choice-list.d.ts

@@ -7,6 +7,13 @@ export interface ChoiceOption {
     isInactive?: boolean;
     /** Optional contextual action shown at the trailing edge of this option. */
     action?: ChoiceOptionAction;
+    /** Optional compact actions rendered as supporting content beneath the option label. */
+    subtextActions?: ChoiceOptionSubtextAction[];
+}
+export interface ChoiceOptionSubtextAction {
+    label: string;
+    value: string;
+    tone?: 'action' | 'negative';
 }
 export interface ChoiceOptionAction {
     /** Accessible name for the fixed ellipsis action. */
@@ -26,7 +33,7 @@ export declare function resolveChoiceSections(options: ChoiceOption[], sections:
 export declare function flattenChoiceSections(sections: ChoiceSection[]): ChoiceOption[];
 /** A choice list has one stable row layout: every option has an icon, or none do. */
 export declare function choiceListUsesIcons(options: ChoiceOption[]): boolean;
-/** Once one option needs supporting text, every row keeps the same two-line structure. */
+/** Descriptive subtext gives the complete list one stable two-line row layout. */
 export declare function choiceListUsesSubtext(options: ChoiceOption[]): boolean;
 export declare function filterChoiceSections(sections: ChoiceSection[], searchTerm: string): ChoiceSection[];
 export declare function enabledChoiceIndexes(options: ChoiceOption[]): number[];

package/dist/mcp-data/registry/empty-state.json

@@ -43,6 +43,7 @@
         }
       ],
       "commonlyComposedWith": [
+        "component:ds-table",
         "component:ds-select",
         "component:ds-text",
         "component:ds-icon"

package/dist/mcp-data/registry/registry.json

@@ -3660,6 +3660,7 @@
             }
           ],
           "commonlyComposedWith": [
+            "component:ds-table",
             "component:ds-select",
             "component:ds-text",
             "component:ds-icon"
@@ -7233,6 +7234,7 @@
             "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
             "Option labels and the selected trigger label stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
             "Use an option action only for a contextual menu about that user-managed option. The fixed ellipsis action appears on hover, keyboard activity, focus, and touch; expanded keeps it visible while its controlled menu is open. Activating it emits dsOptionAction without selecting the option or closing the Select popup.",
+            "Use option subtextActions for a compact set of immediate actions that belong to one option. They render beneath only that option's label using the standard supporting-text inset and rhythm, use action or negative semantic color, and emit dsOptionSubtextAction without selecting the option or closing the popup. Unlike descriptive subtext, they do not reserve a blank supporting line on neighboring options.",
             "The optional prefix icon and trailing indicator always use the parent surface's secondary foreground color, including when a selected value promotes the label to primary. The default down indicator communicates disclosure; up-down is reserved for compact value steppers such as pagination page size.",
             "While the popup is open, the trigger holds the pressed interaction wash without changing its resting foreground or selected-value treatment.",
             "The shared popup search control follows the Select density, using the same text, icon, and internal spacing as a borderless trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
@@ -7258,7 +7260,7 @@
               "Assign options, sections, and multiple-mode array values through JavaScript properties because arrays and objects cannot be represented safely as attributes."
             ],
             "react": [
-              "Pass options or sections as wrapper props, set multiple for array values, and handle onDsChange, onDsClear, onDsOpenChange, onDsFooterAction, and onDsOptionAction."
+              "Pass options or sections as wrapper props, set multiple for array values, and handle onDsChange, onDsClear, onDsOpenChange, onDsFooterAction, onDsOptionAction, and onDsOptionSubtextAction."
             ],
             "angular": [
               "Import DsSelect and SelectValueAccessor when integrating with Angular Forms; bind options and sections as properties."
@@ -7445,6 +7447,10 @@
           {
             "name": "dsOptionAction",
             "detail": "SelectOptionActionDetail"
+          },
+          {
+            "name": "dsOptionSubtextAction",
+            "detail": "SelectOptionSubtextActionDetail"
           }
         ],
         "slots": [],
@@ -8842,7 +8848,7 @@
           "summary": "Semantic, controlled data table with durable visual primitives for cell geometry, grouping, sorting, multi-selection, sticky overflow, incremental loading, and top-level pagination.",
           "useWhen": [
             "A structured dataset needs native row and column relationships, optional one-level grouping, or comparable values across records.",
-            "An application needs controlled sorting, loaded-row selection, infinite loading, pagination, or an opted-in table-owned column customizer while retaining ownership of the data query, catalog, and persistence.",
+            "An application needs controlled sorting, loaded-row selection, infinite loading, pagination, or opted-in table-owned data-mode and column controls while retaining ownership of the data query, catalog, and persistence.",
             "A product table needs a token-backed recipe whose individual header, group, row, cell, selection, state, and load-more layers remain easy to restyle."
           ],
           "avoidWhen": [
@@ -8856,6 +8862,8 @@
             "component:ds-skeleton",
             "component:ds-loader",
             "component:ds-pagination",
+            "component:ds-table-toolbar",
+            "component:ds-table-saved-views",
             "component:ds-bar-action",
             "component:ds-button-unfilled",
             "component:ds-menu",
@@ -8868,8 +8876,9 @@
           ],
           "accessibility": [
             "The rendered structure uses a native table, caption, column headers, row groups, and data cells; keep the caption non-empty. The native caption remains visually hidden as the table's accessible name. When caption visibility is enabled, a 48px header bar renders as component chrome outside the horizontal scrollport. It defaults to a presentational caption title that does not duplicate the accessible name. Application-owned labeled controls supplied through the single named header slot replace that fallback and occupy the leading content width inside the component-owned 8px inset. When columnCustomizer is enabled, the table adds a trailing Preferences control named Customize table; otherwise the header slot receives the complete content width.",
+            "The data-mode switcher is the shared Menu of the table's supported infinite and pagination modes. It is the final caption-bar action; when the column customizer is also present, a decorative vertical divider separates the two controls. dataMode remains controlled, and the application responds to change intent by supplying the matching records, pagination state, loading behavior, and query consequences. Escape, dismissal, and selection return focus to the trigger.",
             "The column customizer is the shared Menu of switch rows, not a table-owned dialog. Data columns can be shown, hidden, and reordered. Locked action columns stay visible, inactive, and last. The selection checkbox is not a column and never appears. The last remaining visible data column cannot be hidden, but it stays focusable so it can still be reordered. Escape and outside click restore focus to the trigger. Persistence stays in the application.",
-            "Sorting controls remain buttons inside column headers and expose the table's one controlled member-row sort through aria-sort. Grouping never adds a second sort indicator or header control; the application supplies groups in its fixed product order.",
+            "Sorting controls remain buttons inside column headers and expose the table's one controlled member-row sort through aria-sort. Grouping never adds a second sort indicator or header control; the application supplies groups in its fixed product order. Optional column help underlines the header label with the shared dotted decoration and shows ds-tooltip from that label; it does not add a second header control or replace the column name.",
             "Selection controls expose checkbox semantics and explicit row names; select-all affects selectable loaded rows only and preserves selected identities outside the loaded window. When grouping is active with multi-selection, each group section header also exposes a checkbox that selects or clears that group's selectable loaded rows.",
             "Interactive rows are focusable as native rows, activate with Enter or Space, and do not steal activation from their nested selection, action, overflow-menu, or primary-text link controls.",
             "Scrollable table regions become keyboard focusable and named only when overflow exists.",
@@ -8877,12 +8886,12 @@
             "Static and infinite tables may show an optional result summary footer when displayedCount and totalCount are finite. Pagination mode instead renders a named Pagination control with a compact selected-size total, vertical divider, and page position; range changes are announced independently with complete phrasing. While focus is anywhere inside a paginated table, unmodified Left and Right Arrow request the adjacent page; editable fields, choice controls, sliders, and modified key combinations retain their own keyboard behavior. The footer slot can replace summary copy, while footer-leading and footer-trailing remain available in the same compact-bar anatomy."
           ],
           "states": [
-            "Columns, rows, groups, grouping, sorting, selected row IDs, collapsed group IDs, hiddenColumnIds, columnOrder, dataMode, pagination, displayedCount, totalCount, and incremental-loading state are controlled inputs. Events communicate intent and never mutate those inputs. The optional header is one composable table-local surface: the component owns its 48px chrome, 8px inset on every side, and sticky placement while the application owns the leading slot's internal layout, controls, labels, filtering behavior, and action handling. Opting into columnCustomizer adds a trailing Customize table Menu trigger and requires caption visibility. The footer retains its compact-bar composition: application-owned leading status sits left while a controlled result summary or Pagination aligns right, before any trailing action. Content-sized tables remain natural for sparse or fixed-count results. height bounds the complete header, frame, and footer composition. fitViewport reserves the compact-state composition height in the nearest vertical scrollport while growing the visible table into that reservation as surrounding page chrome collapses.",
+            "Columns, rows, groups, grouping, sorting, selected row IDs, collapsed group IDs, hiddenColumnIds, columnOrder, dataMode, pagination, displayedCount, totalCount, and incremental-loading state are controlled inputs. Events communicate intent and never mutate those inputs. The optional header is one composable table-local surface: the component owns its 48px chrome, 8px inset on every side, and sticky placement while the application owns the leading slot's internal layout, controls, labels, filtering behavior, and action handling. Opting into dataModeSwitcher and columnCustomizer adds their trailing Menu triggers and requires caption visibility. When both are present, Customize table precedes a decorative divider and the data-mode trigger remains the final action. The table closes one trailing Menu before opening the other. The footer retains its compact-bar composition: application-owned leading status sits left while a controlled result summary or Pagination aligns right, before any trailing action. Content-sized tables remain natural for sparse or fixed-count results. height bounds the complete header, frame, and footer composition. fitViewport reserves the compact-state composition height in the nearest vertical scrollport while growing the visible table into that reservation as surrounding page chrome collapses.",
             "Grouping supports one level. The application supplies groups in a fixed product-defined order and supplies ordered member rows independently. Group section headers show an emphasized text-body-medium label followed by a middle dot and plain secondary loaded progress, for example Critical · 50 of 166. The loaded value comes from the supplied member rows and the total comes from totalCount. A localized countLabel total phrase remains available for the complete assistive progress announcement. Groups may declare an optional intent (brand, neutral, negative, warning, caution, positive) that paints an LTR gradient from the faint intent surface at the label edge into faint neutral at the trailing edge, plus a bold intent title color. Neutral groups remain solid faint neutral. Section separators are painted inside that viewport-width surface so translucent border tokens composite with each intent background. Internal sections keep their separators; a collapsed or empty section header yields its separator only when it is the table's final rendered item. A trailing visually neutral icon-only ButtonUnfilled uses the 24px md double-inset action recipe and toggles controlled collapsedGroupIds, showing ChevronUp while expanded and ChevronDown while collapsed. While any group is expanded, a ChevronDownUp action uses the xs sort-control recipe widened to a table-owned 24px lane and collapses every group. It appears at the inline-end edge of the trailing column declared with kind action when one exists; otherwise a button-hugging 24px by 16px medium-elevation surface floats at the visible scrollport's header edge so the action remains reachable while member columns scroll beneath it. With stickyHeader enabled, each contained section uses its one real section row as a native sticky header inside its real row-group boundary. The browser therefore owns pinning, push-off, scrolling, and resize layout in one pass without a duplicated lane, active-section state, transforms, or scroll-time geometry. Shared grid tracks retain exact header and member-cell alignment. The section surface also stays pinned to the visible horizontal scrollport and spans the smaller of the visible viewport or table width.",
             "When columnCustomizer is false, columns render in catalog order. When it is true, columns remains the catalog: hiddenColumnIds and columnOrder control visibility and data-column sequence, action columns stay last and cannot be hidden, and dsColumnsConfigChange reports the next hidden ids and data-column order without mutating those inputs. The customizer Menu live-applies show/hide and data-column reorder. The table does not persist preferences.",
             "An active member sort toggles only between ascending and descending; activating a different sortable label moves the one sorting state to that key. Applications may still clear the controlled sort state explicitly. Grouping does not introduce another interactive direction.",
             "Compound headers can expose multiple related labels with independent sort keys. Each label owns only its content-width interaction target while the active direction remains in the column's alignment-aware sort lane.",
-            "Initial loading defaults to ten row-shaped skeletons and preserves row dividers, column dividers, selection lanes, and sticky boundaries. A selectable table renders a checkbox-sized control skeleton in its selection lane so loading geometry matches the real checkbox instead of a generic icon. Each column may declare representative text, multiline text, image, Tag, icon, icon-and-text, action, or intentionally blank loading geometry; the table applies the matching resolved-cell padding and track anatomy so the placeholder row has the same height and rhythm as its data row. Columns without a declaration use one text line, while action columns infer an icon action placeholder. Empty, initial error, load-more, retry, loading-more, and terminal bands remain fixed to the visible table width while data columns scroll horizontally beneath them. Incremental loading retains existing rows and supports automatic sentinel, manual load-more, retry, and terminal states. When grouping is active, each expanded group owns its load band at the end of its member rows; internal group load bands keep their bottom divider, while a terminal group load band yields it to the table edge or footer. The global bottom-of-table loader is not rendered.",
+            "Initial loading defaults to ten row-shaped skeletons and preserves row dividers, column dividers, selection lanes, and sticky boundaries. A selectable table renders a checkbox-sized control skeleton in its selection lane so loading geometry matches the real checkbox instead of a generic icon. Each column may declare representative text, multiline text, image, Tag, icon, icon-and-text, action, or intentionally blank loading geometry; the table applies the matching resolved-cell padding and track anatomy so the placeholder row has the same height and rhythm as its data row. Columns without a declaration use one text line, while action columns infer an icon action placeholder. Empty and initial error replace only the body with ds-empty-state, using Inbox or ErrorTriangle plus the table heading and body copy. In height-bounded and maxHeight tables that region fills the remaining viewport below the column header; content-sized tables keep a minimum empty-region height. Empty, initial error, load-more, retry, loading-more, and terminal bands remain fixed to the visible table width while data columns scroll horizontally beneath them. Incremental loading retains existing rows and supports automatic sentinel, manual load-more, retry, and terminal states. When grouping is active, each expanded group owns its load band at the end of its member rows; internal group load bands keep their bottom divider, while a terminal group load band yields it to the table edge or footer. The global bottom-of-table loader is not rendered.",
             "dataMode selects the top-level window: infinite appends ungrouped rows through dsLoadMore when hasMore is true, and pagination renders the controlled page supplied by the application and emits dsPaginationChange. Infinite mode also covers fixed result sets by leaving hasMore false. In a grouped paginated table, pagination counts and windows only parent groups; each expanded parent can still append its own members through dsGroupLoadMore. The application owns requests, cancellation, cursors, deduplication, slicing, and query identity.",
             "When pagination enables Fit to page on a bounded table, the table proposes the number of complete top-level rows that fit below its column header. Grouped tables count group headers only; member rows never affect capacity. Selecting Fit captures that numeric snapshot. A changed fitIdentity requests one fresh snapshot for a new query shape, while viewport resizing alone does not change the active controlled page size.",
             "Rows opt into complete-row activation with interactive and emit dsRowActivate without owning navigation. Selection paints through the shared selected ::before layer; interactive hover and press paint through the shared ::after layer.",
@@ -8895,7 +8904,7 @@
             "stickyHeader follows the active vertical scroll owner: a maxHeight, height, or fitViewport table keeps its native header and group sections inside one bounded table scrollport, while a document-flow table retains a semantic native header and renders a sticky control header whose columns follow the body's native inline scroll timeline. Consumers set --ds-table-sticky-header-offset when page chrome occupies an unbounded document scrollport edge. When the 48px table header bar is visible, it sticks at that external offset and the column header stacks immediately below it.",
             "fitViewport uses viewportInsetBlockStart and viewportInsetBlockEnd to describe compact surrounding chrome and page gutters relative to the nearest vertical scroll owner. Before the table reaches that compact position, its host reserves the eventual height while the visible composition grows and vertical input remains owned by the outer page. Once settled, the internal table viewport becomes the vertical scroll owner. Bounded grouped tables use browser-native sticky section rows inside real block row-group boundaries, so scroll and resize do not run component JavaScript or trigger reactive section swaps. Document-flow tables retain the synchronized visual lane required by their separate horizontal scrollport.",
             "Without maxHeight the table grows the document and automatic lazy loading observes the browser viewport. Horizontal scrolling chains vertical wheel and trackpad movement to the page instead of trapping it.",
-            "Explicit column sizes establish the horizontal overflow width; unsized columns share remaining space.",
+            "Explicit column sizes establish the horizontal overflow width; unsized columns share remaining space. Set imageTracks on an image column to derive its fixed width from the matching 1-, 2-, or 3-track 16:9 image geometry plus table cell padding instead of copying a numeric width.",
             "Prefer the named xs through xl column sizes, which resolve through TokoMo's table-column width tokens; numeric pixel sizes remain an escape hatch for exceptional application-owned widths.",
             "Column headers use one 32px geometry. Body rows use a 40px single-track minimum with shared 8px cell padding; additional tracks grow downward. Image previews fill the same content box as their declared track count. The second text track and the third text track share one subdued body-small recipe so line 3 lines up with line 2.",
             "Long content truncates to one line by default. Hover (or keyboard-focus a primary link) shows the omitted value in one table-owned tooltip when that track overflows. maxLines 2 or 3 wrap onto the named 2-track and 3-track row heights, then ellipsize with the same tooltip. wrap: true remains unlimited and does not show a truncation tooltip. Wrapping 1-track primary occupies the named 2-track and 3-track row heights instead of a private line-height scale. Wrapping secondary on a 2-track cell occupies the named 3-track row and a 106px fourth track for three lines."
@@ -8961,6 +8970,18 @@
             "type": "TableDataMode",
             "required": false
           },
+          "dataModeMenuLabel": {
+            "type": "string",
+            "required": false
+          },
+          "dataModeSwitcher": {
+            "type": "boolean",
+            "required": false
+          },
+          "dataModeSwitcherLabel": {
+            "type": "string",
+            "required": false
+          },
           "displayedCount": {
             "type": "number | undefined",
             "required": false
@@ -9041,6 +9062,10 @@
             "type": "string[]",
             "required": false
           },
+          "infiniteModeLabel": {
+            "type": "string",
+            "required": false
+          },
           "loadIdentity": {
             "type": "string | number",
             "required": false
@@ -9081,6 +9106,10 @@
             "type": "TablePaginationState | null",
             "required": false
           },
+          "paginationModeLabel": {
+            "type": "string",
+            "required": false
+          },
           "resultSummaryLabel": {
             "type": "string",
             "required": false
@@ -9143,6 +9172,10 @@
             "name": "dsColumnsConfigChange",
             "detail": "TableColumnsConfigChangeDetail"
           },
+          {
+            "name": "dsDataModeChange",
+            "detail": "TableDataModeChangeDetail"
+          },
           {
             "name": "dsGroupCollapseChange",
             "detail": "TableGroupCollapseChangeDetail"
@@ -9187,6 +9220,7 @@
       "registryDependencies": [
         "button-unfilled",
         "checkbox",
+        "divider",
         "empty-state",
         "icon",
         "loader",
@@ -9198,6 +9232,244 @@
         "tooltip"
       ]
     },
+    {
+      "name": "table-saved-views",
+      "title": "TableSavedViews",
+      "description": "Controlled saved-views UI for table toolbars, including selection, dirty state, create, save, discard, rename, remove, validation, and focus behavior without owning table configuration or persistence.",
+      "type": "registry:ui",
+      "meta": {
+        "library": "@ds-mo/ui",
+        "distribution": "npm",
+        "storybook": "https://zainadeel.github.io/compomo/?path=/story/table-saved-views",
+        "source": "src/wc/components/TableSavedViews/TableSavedViews.tsx",
+        "intentStatus": "complete",
+        "intent": {
+          "audience": "general",
+          "status": "stable",
+          "summary": "Controlled saved-views UI for table toolbars, including selection, dirty state, create, save, discard, rename, remove, validation, and focus behavior without owning table configuration or persistence.",
+          "useWhen": [
+            "A table workspace lets people recall and manage named combinations of table controls.",
+            "Several products need the same saved-view interaction while retaining different view payloads and storage systems."
+          ],
+          "avoidWhen": [
+            "The choices do not represent restorable table configurations.",
+            "The application expects the component to serialize filters, grouping, sorting, columns, pagination, or product-specific state."
+          ],
+          "commonlyComposedWith": [
+            "component:ds-table-toolbar",
+            "component:ds-table",
+            "component:ds-select",
+            "component:ds-menu",
+            "component:ds-modal"
+          ],
+          "patterns": [
+            "pattern:menu-trigger"
+          ],
+          "accessibility": [
+            "The primary control retains combobox semantics and exposes a direct accessible name.",
+            "Each custom view exposes a separately named options trigger. The options menu supports keyboard navigation and returns focus through the shared Select and Menu behavior.",
+            "The naming dialog traps focus through Modal behavior, associates validation text with the input through Field, and restores focus to the saved-views control after closing."
+          ],
+          "states": [
+            "views, value, and dirty are controlled. Selection, create, save, discard, rename, and remove events communicate intent and never mutate application records.",
+            "The component owns only transient interaction state: the contextual menu, naming dialog, draft name, duplicate-name validation, and focus restoration.",
+            "The default view is a non-editable template. Application-owned custom views appear in a separate section with Rename and Remove actions. New view opens the naming dialog. When an editable selected view is dirty, that view row shows Save and negative Discard supporting actions while the footer remains dedicated to New view. The application decides which table state to capture, restore, and persist."
+          ],
+          "responsiveBehavior": [
+            "The control remains a single toolbar item and relies on Select, Menu, and Modal collision and viewport behavior.",
+            "Place it in the leading region of ds-table-toolbar so narrow table headers preserve the expected control order."
+          ],
+          "frameworkCaveats": {
+            "customElements": [
+              "Assign views through the JavaScript property and update value after handling dsViewChange."
+            ],
+            "react": [
+              "Keep view records and serialized table configuration in application state; update controlled props in response to the component events."
+            ],
+            "angular": [
+              "Import the generated DsTableSavedViews adapter and bind views, value, and dirty; handle event.detail for selection and mutations."
+            ]
+          },
+          "references": [
+            {
+              "label": "Storybook review states",
+              "path": "src/wc/components/TableSavedViews/TableSavedViews.stories.ts"
+            },
+            {
+              "label": "Toolbar composition owner",
+              "path": "src/wc/components/TableToolbar/TableToolbar.agent.json"
+            }
+          ]
+        },
+        "props": {
+          "createLabel": {
+            "type": "string",
+            "required": false
+          },
+          "defaultViewId": {
+            "type": "string",
+            "required": false
+          },
+          "defaultViewLabel": {
+            "type": "string",
+            "required": false
+          },
+          "dirty": {
+            "type": "boolean",
+            "required": false
+          },
+          "label": {
+            "type": "string",
+            "required": false
+          },
+          "triggerLabel": {
+            "type": "string",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          },
+          "views": {
+            "type": "TableSavedView[]",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsViewChange",
+            "detail": "TableSavedViewChangeDetail"
+          },
+          {
+            "name": "dsViewCreate",
+            "detail": "TableSavedViewCreateDetail"
+          },
+          {
+            "name": "dsViewDiscard",
+            "detail": "TableSavedViewDiscardDetail"
+          },
+          {
+            "name": "dsViewRemove",
+            "detail": "TableSavedViewRemoveDetail"
+          },
+          {
+            "name": "dsViewRename",
+            "detail": "TableSavedViewRenameDetail"
+          },
+          {
+            "name": "dsViewSave",
+            "detail": "TableSavedViewSaveDetail"
+          }
+        ],
+        "slots": [],
+        "exports": {
+          "customElement": "ds-table-saved-views",
+          "react": "DsTableSavedViews",
+          "angular": "DsTableSavedViews"
+        }
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "registryDependencies": [
+        "button-filled",
+        "button-unfilled",
+        "field",
+        "input",
+        "menu",
+        "modal",
+        "select"
+      ]
+    },
+    {
+      "name": "table-toolbar",
+      "title": "TableToolbar",
+      "description": "Data-agnostic companion layout for application-owned controls in a table header, with leading and trailing control groups and narrow-width horizontal overflow.",
+      "type": "registry:ui",
+      "meta": {
+        "library": "@ds-mo/ui",
+        "distribution": "npm",
+        "storybook": "https://zainadeel.github.io/compomo/?path=/story/table-toolbar",
+        "source": "src/wc/components/TableToolbar/TableToolbar.tsx",
+        "intentStatus": "complete",
+        "intent": {
+          "audience": "general",
+          "status": "stable",
+          "summary": "Data-agnostic companion layout for application-owned controls in a table header, with leading and trailing control groups and narrow-width horizontal overflow.",
+          "useWhen": [
+            "Several table pages repeat the same leading discovery controls and trailing result-shaping controls.",
+            "A ds-table header slot needs consistent control spacing, alignment, grouping, and narrow-width overflow without moving product behavior into the table."
+          ],
+          "avoidWhen": [
+            "The controls do not operate on a table or structured result set.",
+            "The application expects the toolbar to define filters, saved views, grouping choices, persistence, or data transformations.",
+            "Only one standalone control is present and needs no grouped toolbar semantics."
+          ],
+          "commonlyComposedWith": [
+            "component:ds-table",
+            "component:ds-table-saved-views",
+            "component:ds-input",
+            "component:ds-filter-menu",
+            "component:ds-button-unfilled"
+          ],
+          "patterns": [],
+          "accessibility": [
+            "The component exposes a named toolbar while each slotted control retains its own accessible name and native keyboard behavior.",
+            "Use the leading slot for discovery and context controls such as saved views and search. Use the trailing slot for result-shaping controls such as filters and grouping.",
+            "Tab order follows authored DOM order. The toolbar does not add roving focus because it may contain heterogeneous form and popup controls."
+          ],
+          "states": [
+            "The component owns layout only. Slotted controls, values, menus, loading, persistence, and consequences remain controlled by the application. Use ds-table-saved-views when saved-view interaction needs the shared CompoMo behavior while application storage remains external.",
+            "Either region may be empty. The populated region continues to occupy the available width without adding placeholder chrome."
+          ],
+          "responsiveBehavior": [
+            "The two control groups stay on one line and horizontally scroll when their complete controls no longer fit.",
+            "The scrollbar is visually suppressed without removing touch, trackpad, mouse-wheel, or keyboard scrolling from the overflow container.",
+            "Trailing controls remain grouped after leading controls; the toolbar does not collapse controls into an application-specific overflow menu."
+          ],
+          "frameworkCaveats": {
+            "customElements": [
+              "Project controls through slot=leading or slot=trailing and provide a label that names their table context when Table controls is insufficient."
+            ],
+            "react": [
+              "Set slot=leading or slot=trailing on each child control; keep values and event handlers in the application."
+            ],
+            "angular": [
+              "Set slot=leading or slot=trailing on each child control and import the generated DsTableToolbar adapter alongside those controls."
+            ]
+          },
+          "references": [
+            {
+              "label": "Storybook review states",
+              "path": "src/wc/components/TableToolbar/TableToolbar.stories.ts"
+            },
+            {
+              "label": "Table composition owner",
+              "path": "src/wc/components/Table/Table.agent.json"
+            }
+          ]
+        },
+        "props": {
+          "label": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": [],
+        "exports": {
+          "customElement": "ds-table-toolbar",
+          "react": "DsTableToolbar",
+          "angular": "DsTableToolbar"
+        }
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "registryDependencies": []
+    },
     {
       "name": "tag",
       "title": "Tag",