Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
13.0 KB
Raw Blame

schema_version: 3 template_version: 7 kind: component id: component:TableSelectionToolbar authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Table/TableSelectionToolbar.test.tsx, apps/storybook/stories/TableSelection.stories.tsx, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:public-component-api, architecture:internationalization, ] contributing: []

system_specs: [spec:AST-085]

TableSelectionToolbar component contract

Contract at a glance

Area Contract
Public contract selection (from useTableSelectionState), startContent, label, renderSelectionLabel, clearLabel, size, variant, and the other Toolbar props except endContent.
Behavior A bulk-actions Toolbar that appears while rows are selected, showing the caller's actions, the selected count, and a command that clears the selection.
End-user impact People act on selected rows together, see how many are selected, and clear the selection in one step.
Builder impact None; the record describes shipped behavior.
Compatibility/readiness Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.
Review checks Reject a toolbar shown without a selection, an unlocalized default label, count, or clear label, or a clear command that leaves rows selected.
Governing rules architecture:internationalization INV1a; spec:AST-085 FR4; architecture:public-component-api.

This table is a review projection; the body below is authoritative.

Intent

TableSelectionToolbar is the bulk-actions bar for a Table with row selection. It owns when the bar shows, the selection status, and the clear command; the caller owns the actions.

Consumer syntax and examples belong in TableSelectionToolbar.doc.mjs.

Compatibility and migration

  • Released default preserved: yes — sm, muted, localized "Bulk actions", "{count} selected", and "Unselect All".
  • Compatibility class: records shipped behavior; no public prop, default, DOM, target, or styling output changes.
  • Controlled/uncontrolled behavior: the selection is the shared state the caller passes.
  • Migration decision: none

Consumer migration instructions belong in consumer docs and release notes.

Current-state impact

  • Focus lost after clearing (FR2). Activating the clear command clears the selection, which removes the toolbar and the focused button with it; focus falls to the page, so keyboard users lose their place, where spec:AST-085 FR4 has a component that removes a focused control name its destination.

Ownership boundary

Owns

  • Showing the toolbar only while rows are selected, the selected-count status, and the clear command.

Does not own / non-goals

  • Toolbar layout, size, and variant — owned by component:Toolbar.
  • The selection state — owned by useTableSelectionState.
  • Bulk actions in startContent — owned by the caller.
  • A selection of every row matching a query across server pages — owned by the app, which passes its own count and label (DEC-1).

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
Selection shared selection state Whether to show and what to count and clear. Always — caller Stable —
Labels label, clearLabel, renderSelectionLabel The toolbar's name, the clear command's label, and the count content. Always localized defaults caller Stable A count renderer may return nothing.
Toolbar options size, variant, other Toolbar props Passed to the Toolbar. Always sm, muted component:Toolbar Stable —

Behavioral and layout contract

ID Invariant Basis
FR1 With no selection, TableSelectionToolbar renders nothing. With a selection, it renders a Toolbar named by label (localized "Bulk actions" by default) holding the caller's startContent, and at its end the selected-count content (localized "{count} selected" by default, or renderSelectionLabel's result) and a ghost button labelled clearLabel (localized "Unselect All"). Default text comes from the catalog (architecture:internationalization INV1a). Current source and tests
FR2 The clear button clears the whole selection through the shared state, which removes the toolbar while the clear button holds focus. spec:AST-085 FR4 has this record name where focus goes; the destination is open (OQ1). Implementation gap: focus is lost when the toolbar unmounts (Current-state impact). Current source and tests
FR3 size defaults to sm and variant to muted; other Toolbar props pass to the Toolbar, and endContent is not accepted. Current source

Allowed variation

  • AV1 — Actions and labels. Any actions and product-specific labels.

Representative states

State Required invariant Allowed variation
No selection Nothing renders. —
Selection Named toolbar, actions, count, clear button. Labels.
Custom empty count The count renderer may render nothing. —

Transformation and precedence order

  • ORD1 — Labels. Caller labels → catalog defaults.

Performance and resources

  • PR1 — No resources. TableSelectionToolbar holds no state of its own.

Accessibility contract

  • AR1 — Named toolbar. The bar is a Toolbar with an accessible name, and the clear command is a native button with its label.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Bulk actions bar Actions, count, and clear command for the selected rows. Current source and docs Supporting FR1–FR3

Theming: TableSelectionToolbar adds no target; the Toolbar and Button it renders carry their own. TableSelectionToolbar.doc.mjs declares no anatomy, so no anatomy-theming block is declared here.

Family and system relationships

  • component:Toolbar owns layout and theming.
  • spec:AST-085 FR4 owns focus after a focused control is removed; FR2 records the gap.
  • architecture:internationalization owns default text; FR1 applies INV1a.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1, ORD1, AR1 TableSelectionToolbar.test.tsx no-selection, actions and status, empty count, and custom-label tests No selection; selection; custom labels A toolbar without a selection, a missing name, count, action, or clear button, or ignored custom labels fail. audit:TableSelectionToolbar/behavior
FR2 TableSelectionToolbar.test.tsx clear test Clear A clear that leaves rows selected fails. Gap: no test covers where focus goes after clearing. audit:TableSelectionToolbar/a11y
FR3, PR1 TableSelectionToolbar.test.tsx defaults test; source review Defaults A toolbar that does not default to sm and muted fails. Gap: no automated check fails if TableSelectionToolbar adds state or a listener. audit:TableSelectionToolbar/api
RTL relation RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on TableSelection / Bulk actions One row selected; LTR and RTL A selected count that is not at the inline start of "Unselect All" fails D2. audit:TableSelectionToolbar/i18n-rtl

Decision log

DEC-1 — A selection of every matching row stays with the app

Reference: component:TableSelectionToolbar/DEC-1 Decider: cixzhang, 2026-11-06

When a person selects every row that matches a query across server pages, the app keeps that selection ("every matching row minus exclusions") and passes the toolbar its own selectedCount and renderSelectionLabel. In this mode selectedKeys holds only the loaded rows, because the full set is not on the client. A Core model for such a selection is decided together with Table's server-pagination contract, since both need a total that is not loaded.

Rejected: an all-matching mode in useTableSelectionState before the server-pagination contract exists.

Open questions

  • OQ1 — Where does focus go when Clear removes the toolbar? (human-api) spec:AST-085 FR4 has this record name the destination; until it does, a keyboard user who clears the selection loses their place.

Content boundary

This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or Table rules. It links to their owners.