diff --git a/.changeset/bright-tools-align.md b/.changeset/bright-tools-align.md new file mode 100644 index 000000000..3d3000ffe --- /dev/null +++ b/.changeset/bright-tools-align.md @@ -0,0 +1,20 @@ +--- +"@tailor-platform/app-shell": minor +--- + +Add a full-width `Toolbar` with composable rows, grouped controls, separators, and optional edge-to-edge row layout. + +```tsx + + + + + + + + + + +``` + +AppShell Buttons, inputs, selects, comboboxes, and tabs automatically participate in toolbar keyboard navigation. diff --git a/decisions/generic-toolbar.md b/decisions/generic-toolbar.md new file mode 100644 index 000000000..d000d3e03 --- /dev/null +++ b/decisions/generic-toolbar.md @@ -0,0 +1,61 @@ +# Decision: generic `Toolbar` for action-bar layout + +> Status: **Decided — introduce a generic `Toolbar` for layout and compose feature controls inside it. Implemented by PR #559.** +> Scope: toolbar layout, DataTable composition, and the migration direction for `DataTable.Toolbar`. This does not deprecate or remove `DataTable.Toolbar`. + +## Context + +`DataTable.Toolbar` combines two concerns: + +- layout of a full-width action bar; and +- DataTable-specific controls and their placement. + +That fixed composition does not serve other list presentations or the planned ActionBar use case. A second DataTable-specific layout API would duplicate the composition model: consumers would need to decide when to use the wrapper and when to use a general-purpose toolbar. + +A generic toolbar also requires consumers to choose leading/trailing placement explicitly with `justify="between"`. That choice can be missed, producing inconsistent layouts, so the component needs a canonical DataTable scaffold in its documentation and examples. + +## Decision + +### A single generic layout primitive + +Expose `Toolbar` as a layout component with four parts: + +- `Toolbar.Root` stacks rows; +- `Toolbar.Row` is a horizontal action row and supports `justify="start" | "between"`; +- `Toolbar.Group` keeps related controls together; and +- `Toolbar.Separator` separates groups visually. + +`Toolbar` does not own DataTable controls or any other feature-specific controls. It standardizes the layout details that otherwise drift between screens: padding, gaps, wrapping, borders, and row-level keyboard navigation. + +### Feature controls compose directly + +`DataTable.Filters` and `DataTable.ColumnSettings` are controls that can be placed in a generic toolbar alongside buttons, inputs, tabs, and controls from other features. + +```tsx + + + + + + + + + + + + + +``` + +When a generic toolbar is a direct child of `DataTable.Root`, DataTable owns the outer frame while the toolbar supplies the divider below its rows. + +### Keep the existing DataTable wrapper during migration + +`DataTable.Toolbar` remains supported for its existing fixed layout. New custom layouts should use `Toolbar` directly. Deprecating `DataTable.Toolbar` is a separate compatibility and release decision, not part of this change. + +## Consequences + +- DataTable and non-DataTable screens use the same composition model for action-bar layout. +- `justify="between"` remains explicit rather than becoming a DataTable-only placement convention; the documentation and example page provide the canonical leading/trailing layout. +- AppShell buttons, inputs, selects, comboboxes, and tabs participate automatically in a toolbar row's Arrow/Home/End navigation. Composite controls retain their own directional-key behavior. +- There is no new `DataTable.Toolbar` layout API or named wrapper around the generic toolbar. Add one only if a stable, opinionated DataTable layout proves necessary across consumers. diff --git a/docs-manifest.json b/docs-manifest.json index f62141fe7..718997a22 100644 --- a/docs-manifest.json +++ b/docs-manifest.json @@ -443,10 +443,10 @@ "withURLCollectionState" ], "hashes": { - "typeSurface": "199f1cb9d06e3c15", - "outline": "2458512deac6c312", + "typeSurface": "014a9036a3b9b0af", + "outline": "f1bea006bdeb43a4", "snapshot": null, - "outputMd": "d4212ff859cfb879", + "outputMd": "dd2da884d7550daf", "examples": null } }, @@ -1307,6 +1307,23 @@ "examples": null } }, + "toolbar": { + "slug": "toolbar", + "kind": "code-backed", + "outline": "docs-src/components/toolbar.docs.outline.md", + "output": "docs/components/toolbar.md", + "examples": null, + "sources": ["packages/core/src/components/toolbar/**"], + "claims": [], + "symbols": ["Toolbar", "ToolbarProps"], + "hashes": { + "typeSurface": "2d88f0306efcaa77", + "outline": "1257a84ccd91d5c3", + "snapshot": "3b402cab18147ef9", + "outputMd": "91d70b140c7bb747", + "examples": null + } + }, "tooltip": { "slug": "tooltip", "kind": "code-backed", @@ -1588,7 +1605,7 @@ "packages/core/skills/app-shell-patterns/references/components/combobox.md": "dfb775c7c4307409", "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a", "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc", - "packages/core/skills/app-shell-patterns/references/components/data-table.md": "d4212ff859cfb879", + "packages/core/skills/app-shell-patterns/references/components/data-table.md": "dd2da884d7550daf", "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "33902be121ff69db", "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be", "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "3422388a0cc78571", @@ -1612,6 +1629,7 @@ "packages/core/skills/app-shell-patterns/references/components/tabs.md": "30bb32e57fc78bd9", "packages/core/skills/app-shell-patterns/references/components/textarea.md": "c940bc01cd573334", "packages/core/skills/app-shell-patterns/references/components/timeline.md": "699249c9452485ab", + "packages/core/skills/app-shell-patterns/references/components/toolbar.md": "91d70b140c7bb747", "packages/core/skills/app-shell-patterns/references/components/tooltip.md": "113c95b2995917ed", "packages/core/skills/app-shell-patterns/references/components/with-guard.md": "d79aaf40cb97073f", "packages/core/skills/app-shell-patterns/references/api/create-ai-gateway-client.md": "7eaff97521a14ab0", @@ -1650,6 +1668,6 @@ "packages/core/skills/app-shell-patterns/references/patterns/list-dense-scan.md": "8062ea0df9403fbb", "packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "c3fb2588a0699c26", "packages/core/skills/app-shell-patterns/references/migrations.md": "799fd5010635b2c2", - "packages/core/skills/app-shell-patterns/SKILL.md": "165761adda4fbfc0" + "packages/core/skills/app-shell-patterns/SKILL.md": "814325f4ea06ffae" } } diff --git a/docs-src/components/data-table.docs.outline.md b/docs-src/components/data-table.docs.outline.md index ded8b933f..9c10ea07d 100644 --- a/docs-src/components/data-table.docs.outline.md +++ b/docs-src/components/data-table.docs.outline.md @@ -150,14 +150,15 @@ function JournalsPage() { `DataTable` is a namespace object. All sub-components read state from `DataTable.Root` via context. -| Sub-component | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `DataTable.Root` | Context provider. Wraps all other sub-components. Required. | -| `DataTable.Table` | Renders the `` with headers and body. Required. | -| `DataTable.Toolbar` | Container for toolbar content (e.g. filters). Optional. Pass `columnSettings` to render the built-in "Columns" control (show/hide + reorder + pin) at the top-right. See props below. | -| `DataTable.Filters` | Add-filter panel + active filter chips, auto-generated from column filter configs. Requires `control` from `useCollectionVariables`. | -| `DataTable.Footer` | Footer container for pagination and other footer content. Optional. | -| `DataTable.Pagination` | Pre-built pagination controls with optional row count and selection info. Requires `control` from `useCollectionVariables`. Place inside `DataTable.Footer`. | +| Sub-component | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `DataTable.Root` | Context provider. Wraps all other sub-components. Required. | +| `DataTable.Table` | Renders the `
` with headers and body. Required. | +| `DataTable.Toolbar` | DataTable-specific toolbar container. Optional; pass `columnSettings` for the built-in Columns control. | +| `DataTable.ColumnSettings` | The placeable Columns control (show/hide + reorder + pin). Use it in a generic [`Toolbar`](./toolbar.md) for custom layouts. | +| `DataTable.Filters` | Add-filter panel + active filter chips, auto-generated from column filter configs. Requires `control` from `useCollectionVariables`. | +| `DataTable.Footer` | Footer container for pagination and other footer content. Optional. | +| `DataTable.Pagination` | Pre-built pagination controls with optional row count and selection info. Requires `control` from `useCollectionVariables`. Place inside `DataTable.Footer`. | ### `DataTable.Root` Props @@ -169,18 +170,20 @@ function JournalsPage() { ### `DataTable.Toolbar` Props -| Prop | Type | Default | Description | -| ---------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `children` | `ReactNode` | — | Toolbar content (e.g. `DataTable.Filters`), laid out on the left. | -| `columnSettings` | `boolean` | `false` | Render the built-in "Columns" control (show/hide + reorder + pin) anchored to the top-right. Persists per-user when `useDataTable` has a `tableId`. | -| `className` | `string` | — | Additional CSS class for the toolbar container. | +| Prop | Type | Default | Description | +| ---------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `children` | `ReactNode` | — | Toolbar content, stacked on the left. | +| `columnSettings` | `boolean` | `false` | Render the built-in Columns control at the top-right. Use [`Toolbar`](./toolbar.md) with `DataTable.ColumnSettings` for new custom layouts. | +| `className` | `string` | — | Additional CSS class for the toolbar container. | + +For new layouts, use the generic [`Toolbar`](./toolbar.md). ### `DataTable.Filters` Props | Prop | Type | Default | Description | | ------------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------- | | `slot` | `"all" \| "chips" \| "add"` | `"all"` | Which part to render (see below). | -| `addIconOnly` | `boolean` | `false` | Render the **Add filter** trigger as an icon-only button (the label becomes its `aria-label`). | +| `addIconOnly` | `boolean` | `true` | Render the **Add filter** trigger as an icon-only button (the label becomes its `aria-label`). | | `className` | `string` | — | Additional CSS class for the filters container. | By default `DataTable.Filters` renders the active filter chips plus the **Add filter** trigger together. The `slot` prop lets you split them across a custom toolbar layout: @@ -191,13 +194,21 @@ By default `DataTable.Filters` renders the active filter chips plus the **Add fi ```tsx // Add filter in a header row (with tabs, etc.); chips on the row below. - -
- - -
- - + + + + + + + + + + + + + + + ``` ### `DataTable.Pagination` Props @@ -222,7 +233,7 @@ When pagination changes page or page size, `DataTable.Table` resets its own scro ## Column pinning, visibility & ordering - **Pin** a column with `pin: "left" | "right"`. Pinned columns stay visible during horizontal scroll; the selection and expand columns auto-pin left and the row-actions column auto-pins right. A subtle shadow appears at the frozen edge once the table is scrolled under it. Sticky offsets are measured from the rendered layout, so a `width` isn't required — but setting `width` on pinned columns is recommended so their size stays stable as content changes. -- **Column settings.** Pass `columnSettings` to `DataTable.Toolbar` to render a built-in "Columns" control — a popover to show/hide columns, reorder them (drag), and change pinning by dragging a column between the **Fixed left**, **Scrollable**, and **Fixed right** zones. It's a toolbar prop (not a composed sub-component) because the control always sits in the same top-right position. +- **Column settings.** `DataTable.ColumnSettings` renders a popover to show/hide columns, reorder them (drag), and change pinning by dragging a column between the **Fixed left**, **Scrollable**, and **Fixed right** zones. Place it in a generic [`Toolbar`](./toolbar.md), or pass `columnSettings` to `DataTable.Toolbar` for its fixed top-right placement. - **Persistence.** Pass a stable, **unique** `tableId` to persist each user's column layout (visibility, order, pinning) to `localStorage` (key `as:data-table:v1:`). This is a per-user preference — it is deliberately **not** stored in the URL like filters/sort/pagination, so it survives reloads and isn't reset by shared/filtered links. Omit `tableId` for in-memory-only layout (state simply isn't persisted). Two tables mounted with the same `tableId` share one storage key and overwrite each other — use a unique id per table (e.g. `:`); a dev-mode warning fires on duplicates. ```tsx @@ -233,7 +244,16 @@ const table = useDataTable({ }); - + + + + + + + + + + ; ``` @@ -404,7 +424,7 @@ A column definition passed to `useDataTable`. `Column` is a discriminated | `render` | `(row: TRow) => ReactNode` | Renders the cell content. Presentation only. Optional — overrides the built-in `type` renderer when set. Built-in behaviors that need the raw value (truncate tooltip, cell copy/filter context-menu actions) still resolve it from `accessor` first, then `row[col.id]`, and only fall back to the return value of `render(row)` when it is a primitive (`string`, `number`, `boolean`, or `bigint`). | | `id` | `string` | Stable identifier for column visibility, persisted layout state, raw-value fallback (`row[col.id]`), and the React key. Falls back to `label` when omitted. Set this explicitly when `label` is absent, not unique, or when a custom-rendered column should still participate in built-in cell behaviors that need a raw value. | | `width` | `number` | Fixed column width in pixels. Optional. | -| `pin` | `"left" \| "right"` | Freezes the column to that edge so it stays visible during horizontal scroll (the default; the user can override it via the toolbar's `columnSettings` control). Sticky offsets are measured from the rendered layout, so `width` isn't required — but setting `width` on pinned columns is recommended for stable sizing. The selection and expand columns auto-pin left and the row-actions column auto-pins right. | +| `pin` | `"left" \| "right"` | Freezes the column to that edge so it stays visible during horizontal scroll (the default; the user can override it via the toolbar's column-settings control). Sticky offsets are measured from the rendered layout, so `width` isn't required — but setting `width` on pinned columns is recommended for stable sizing. The selection and expand columns auto-pin left and the row-actions column auto-pin right. | | `align` | `"left" \| "right"` | Horizontal alignment. Defaults to `"right"` for `type: "number"` and `type: "money"`; `"left"` otherwise. Pass `"left"` to opt a numeric column out. | | `truncate` | `boolean` | Truncate overflowing text with an ellipsis. Wires up an app-shell `` automatically when the resolved raw cell value is a string or number (`accessor` first, then `row[col.id]`). With `inferColumns`, no explicit `accessor` is needed because `id` is pinned to the field name. Requires another column to anchor the row width (`width` on a neighbor, or a fixed-size column like selection / row actions). | | `accessor` | _(narrowed per `type`)_ | Extracts the raw value. This is the primary source of truth for built-in behaviors that need a value independent of presentation (typed rendering, truncate tooltip, cell copy/filter context-menu actions). The return type is narrowed per `type` branch — returning an array is a compile error on all typed columns except `badge`, and returning a plain object is a compile error on all typed columns. Untyped columns (`type` omitted) retain `unknown`. `null` and `undefined` are always allowed. | diff --git a/docs-src/components/toolbar.docs.outline.md b/docs-src/components/toolbar.docs.outline.md new file mode 100644 index 000000000..2676be61a --- /dev/null +++ b/docs-src/components/toolbar.docs.outline.md @@ -0,0 +1,140 @@ +--- +kind: code-backed +group: toolbar +title: Toolbar +description: Full-width action bars with composable rows, grouped controls, and keyboard navigation +sources: + - packages/core/src/components/toolbar/** +--- + +# Toolbar + +`Toolbar` is a full-width action bar. It is independent of `DataTable`: place any AppShell or application control in it, including buttons, search fields, selects, comboboxes, and tabs. + +```tsx +import { Toolbar } from "@tailor-platform/app-shell"; + + + + + + + + + + +; +``` + +## Structure + +`Toolbar.Root` stacks rows. `Toolbar.Row` is one horizontal, keyboard-navigable action row. Use `Toolbar.Group` to keep related controls together and `Toolbar.Separator` to divide groups. + +```tsx + + + + + + + + + + + + + + + + + + + + +``` + +### Row alignment + +Use `justify="between"` when a row has one leading and one trailing group. The row places those outer groups at opposite edges. The default, `"start"`, keeps every group at the leading edge. + +```tsx + + {/* search and filters */} + {/* export and create actions */} + +``` + +Keep controls that belong to the leading region in the same group. `justify="between"` distributes **direct** groups, so a separator should also stay inside that group. + +### Sizing fields + +`Input` keeps its normal `w-full` behavior inside a toolbar. Give a field an explicit layout box when it shares a group with other controls. + +```tsx + +
+ +
+ +
` with headers and body. Required. | -| `DataTable.Toolbar` | Container for toolbar content (e.g. filters). Optional. Pass `columnSettings` to render the built-in "Columns" control (show/hide + reorder + pin) at the top-right. See props below. | -| `DataTable.Filters` | Add-filter panel + active filter chips, auto-generated from column filter configs. Requires `control` from `useCollectionVariables`. | -| `DataTable.Footer` | Footer container for pagination and other footer content. Optional. | -| `DataTable.Pagination` | Pre-built pagination controls with optional row count and selection info. Requires `control` from `useCollectionVariables`. Place inside `DataTable.Footer`. | +| Sub-component | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `DataTable.Root` | Context provider. Wraps all other sub-components. Required. | +| `DataTable.Table` | Renders the `
` with headers and body. Required. | +| `DataTable.Toolbar` | DataTable-specific toolbar container. Optional; pass `columnSettings` for the built-in Columns control. | +| `DataTable.ColumnSettings` | The placeable Columns control (show/hide + reorder + pin). Use it in a generic [`Toolbar`](./toolbar.md) for custom layouts. | +| `DataTable.Filters` | Add-filter panel + active filter chips, auto-generated from column filter configs. Requires `control` from `useCollectionVariables`. | +| `DataTable.Footer` | Footer container for pagination and other footer content. Optional. | +| `DataTable.Pagination` | Pre-built pagination controls with optional row count and selection info. Requires `control` from `useCollectionVariables`. Place inside `DataTable.Footer`. | ### `DataTable.Root` Props @@ -163,18 +164,20 @@ function JournalsPage() { ### `DataTable.Toolbar` Props -| Prop | Type | Default | Description | -| ---------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `children` | `ReactNode` | — | Toolbar content (e.g. `DataTable.Filters`), laid out on the left. | -| `columnSettings` | `boolean` | `false` | Render the built-in "Columns" control (show/hide + reorder + pin) anchored to the top-right. Persists per-user when `useDataTable` has a `tableId`. | -| `className` | `string` | — | Additional CSS class for the toolbar container. | +| Prop | Type | Default | Description | +| ---------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `children` | `ReactNode` | — | Toolbar content, stacked on the left. | +| `columnSettings` | `boolean` | `false` | Render the built-in Columns control at the top-right. Use [`Toolbar`](./toolbar.md) with `DataTable.ColumnSettings` for new custom layouts. | +| `className` | `string` | — | Additional CSS class for the toolbar container. | + +For new layouts, use the generic [`Toolbar`](./toolbar.md). ### `DataTable.Filters` Props | Prop | Type | Default | Description | | ------------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------- | | `slot` | `"all" \| "chips" \| "add"` | `"all"` | Which part to render (see below). | -| `addIconOnly` | `boolean` | `false` | Render the **Add filter** trigger as an icon-only button (the label becomes its `aria-label`). | +| `addIconOnly` | `boolean` | `true` | Render the **Add filter** trigger as an icon-only button (the label becomes its `aria-label`). | | `className` | `string` | — | Additional CSS class for the filters container. | By default `DataTable.Filters` renders the active filter chips plus the **Add filter** trigger together. The `slot` prop lets you split them across a custom toolbar layout: @@ -185,13 +188,21 @@ By default `DataTable.Filters` renders the active filter chips plus the **Add fi ```tsx // Add filter in a header row (with tabs, etc.); chips on the row below. - -
- - -
- - + + + + + + + + + + + + + + + ``` ### `DataTable.Pagination` Props @@ -216,7 +227,7 @@ When pagination changes page or page size, `DataTable.Table` resets its own scro ## Column pinning, visibility & ordering - **Pin** a column with `pin: "left" | "right"`. Pinned columns stay visible during horizontal scroll; the selection and expand columns auto-pin left and the row-actions column auto-pins right. A subtle shadow appears at the frozen edge once the table is scrolled under it. Sticky offsets are measured from the rendered layout, so a `width` isn't required — but setting `width` on pinned columns is recommended so their size stays stable as content changes. -- **Column settings.** Pass `columnSettings` to `DataTable.Toolbar` to render a built-in "Columns" control — a popover to show/hide columns, reorder them (drag), and change pinning by dragging a column between the **Fixed left**, **Scrollable**, and **Fixed right** zones. It's a toolbar prop (not a composed sub-component) because the control always sits in the same top-right position. +- **Column settings.** `DataTable.ColumnSettings` renders a popover to show/hide columns, reorder them (drag), and change pinning by dragging a column between the **Fixed left**, **Scrollable**, and **Fixed right** zones. Place it in a generic [`Toolbar`](./toolbar.md), or pass `columnSettings` to `DataTable.Toolbar` for its fixed top-right placement. - **Persistence.** Pass a stable, **unique** `tableId` to persist each user's column layout (visibility, order, pinning) to `localStorage` (key `as:data-table:v1:`). This is a per-user preference — it is deliberately **not** stored in the URL like filters/sort/pagination, so it survives reloads and isn't reset by shared/filtered links. Omit `tableId` for in-memory-only layout (state simply isn't persisted). Two tables mounted with the same `tableId` share one storage key and overwrite each other — use a unique id per table (e.g. `:`); a dev-mode warning fires on duplicates. ```tsx @@ -227,7 +238,16 @@ const table = useDataTable({ }); - + + + + + + + + + + ; ``` @@ -398,7 +418,7 @@ A column definition passed to `useDataTable`. `Column` is a discriminated | `render` | `(row: TRow) => ReactNode` | Renders the cell content. Presentation only. Optional — overrides the built-in `type` renderer when set. Built-in behaviors that need the raw value (truncate tooltip, cell copy/filter context-menu actions) still resolve it from `accessor` first, then `row[col.id]`, and only fall back to the return value of `render(row)` when it is a primitive (`string`, `number`, `boolean`, or `bigint`). | | `id` | `string` | Stable identifier for column visibility, persisted layout state, raw-value fallback (`row[col.id]`), and the React key. Falls back to `label` when omitted. Set this explicitly when `label` is absent, not unique, or when a custom-rendered column should still participate in built-in cell behaviors that need a raw value. | | `width` | `number` | Fixed column width in pixels. Optional. | -| `pin` | `"left" \| "right"` | Freezes the column to that edge so it stays visible during horizontal scroll (the default; the user can override it via the toolbar's `columnSettings` control). Sticky offsets are measured from the rendered layout, so `width` isn't required — but setting `width` on pinned columns is recommended for stable sizing. The selection and expand columns auto-pin left and the row-actions column auto-pins right. | +| `pin` | `"left" \| "right"` | Freezes the column to that edge so it stays visible during horizontal scroll (the default; the user can override it via the toolbar's column-settings control). Sticky offsets are measured from the rendered layout, so `width` isn't required — but setting `width` on pinned columns is recommended for stable sizing. The selection and expand columns auto-pin left and the row-actions column auto-pin right. | | `align` | `"left" \| "right"` | Horizontal alignment. Defaults to `"right"` for `type: "number"` and `type: "money"`; `"left"` otherwise. Pass `"left"` to opt a numeric column out. | | `truncate` | `boolean` | Truncate overflowing text with an ellipsis. Wires up an app-shell `` automatically when the resolved raw cell value is a string or number (`accessor` first, then `row[col.id]`). With `inferColumns`, no explicit `accessor` is needed because `id` is pinned to the field name. Requires another column to anchor the row width (`width` on a neighbor, or a fixed-size column like selection / row actions). | | `accessor` | _(narrowed per `type`)_ | Extracts the raw value. This is the primary source of truth for built-in behaviors that need a value independent of presentation (typed rendering, truncate tooltip, cell copy/filter context-menu actions). The return type is narrowed per `type` branch — returning an array is a compile error on all typed columns except `badge`, and returning a plain object is a compile error on all typed columns. Untyped columns (`type` omitted) retain `unknown`. `null` and `undefined` are always allowed. | diff --git a/docs/components/toolbar.md b/docs/components/toolbar.md new file mode 100644 index 000000000..24c2eff83 --- /dev/null +++ b/docs/components/toolbar.md @@ -0,0 +1,138 @@ +--- +title: Toolbar +description: Full-width action bars with composable rows, grouped controls, and keyboard navigation +--- + + + +# Toolbar + +`Toolbar` is a full-width action bar. It is independent of `DataTable`: place any AppShell or application control in it, including buttons, search fields, selects, comboboxes, and tabs. + +```tsx +import { Toolbar } from "@tailor-platform/app-shell"; + + + + + + + + + + +; +``` + +## Structure + +`Toolbar.Root` stacks rows. `Toolbar.Row` is one horizontal, keyboard-navigable action row. Use `Toolbar.Group` to keep related controls together and `Toolbar.Separator` to divide groups. + +```tsx + + + + + + + + + + + + + + + + + + + + +``` + +### Row alignment + +Use `justify="between"` when a row has one leading and one trailing group. The row places those outer groups at opposite edges. The default, `"start"`, keeps every group at the leading edge. + +```tsx + + {/* search and filters */} + {/* export and create actions */} + +``` + +Keep controls that belong to the leading region in the same group. `justify="between"` distributes **direct** groups, so a separator should also stay inside that group. + +### Sizing fields + +`Input` keeps its normal `w-full` behavior inside a toolbar. Give a field an explicit layout box when it shares a group with other controls. + +```tsx + +
+ +
+ + setQuery(event.target.value)} + /> + + +
` with built-in `Headers` and `Body`. * Place inside `DataTable.Root`. diff --git a/packages/core/src/components/input/input.tsx b/packages/core/src/components/input/input.tsx index c3719f1de..1ee7d950f 100644 --- a/packages/core/src/components/input/input.tsx +++ b/packages/core/src/components/input/input.tsx @@ -2,6 +2,7 @@ import * as React from "react"; import { cn } from "@/lib/utils"; import { inputBaseClasses } from "@/lib/input-classes"; +import { mergeRefs, useToolbarItem } from "../toolbar/toolbar"; type InputProps = React.ComponentProps<"input">; @@ -16,9 +17,13 @@ type InputProps = React.ComponentProps<"input">; * * ``` */ -function Input({ className, type, ...props }: InputProps) { +function Input({ className, type, ref: forwardedRef, ...props }: InputProps) { + const ref = React.useRef(null); + useToolbarItem(ref, { handlesDirectionalKeys: true }); + return ( ) { + const ref = React.useRef(null); + useToolbarItem(ref, { handlesDirectionalKeys: true }); + return ( ) { +function Tab({ + className, + children, + ref: forwardedRef, + ...props +}: React.ComponentProps) { const variant = React.useContext(TabsVariantContext); const size = React.useContext(TabsSizeContext); + const ref = React.useRef(null); + useToolbarItem(ref, { handlesDirectionalKeys: true }); + return ( { + cleanup(); +}); + +describe("Toolbar", () => { + it("renders grouped controls and a separator", () => { + const { container } = render( + + + + + + + + + + + + , + ); + + expect(container.innerHTML).toMatchSnapshot(); + expect(screen.getByRole("toolbar", { name: "Document actions" })).toBeTruthy(); + expect(screen.getByRole("separator").getAttribute("aria-orientation")).toBe("vertical"); + }); + + it("moves focus through controls in a horizontal row", () => { + render( + + + + + + + + + , + ); + + const first = screen.getByRole("button", { name: "First" }); + const last = screen.getByRole("button", { name: "Last" }); + + first.focus(); + fireEvent.keyDown(first, { key: "ArrowRight" }); + expect(document.activeElement).toBe(last); + + fireEvent.keyDown(last, { key: "Home" }); + expect(document.activeElement).toBe(first); + }); + + it("registers AppShell controls while leaving composite keys to their owner", () => { + render( + + + + + + + All + Open + + + + + + + + , + ); + + const previous = screen.getByRole("button", { name: "Previous" }); + const all = screen.getByRole("tab", { name: "All" }); + const open = screen.getByRole("tab", { name: "Open" }); + const assignee = screen.getByRole("combobox", { name: "Assignee" }); + const sort = screen.getByRole("combobox", { name: "Sort" }); + const search = screen.getByRole("textbox", { name: "Search" }); + + previous.focus(); + fireEvent.keyDown(previous, { key: "ArrowRight" }); + expect(document.activeElement).toBe(all); + + fireEvent.keyDown(all, { key: "ArrowRight" }); + expect(document.activeElement).toBe(all); + expect(open.getAttribute("aria-selected")).toBe("false"); + + assignee.focus(); + fireEvent.keyDown(assignee, { key: "ArrowRight" }); + expect(document.activeElement).toBe(assignee); + + sort.focus(); + fireEvent.keyDown(sort, { key: "ArrowRight" }); + expect(document.activeElement).toBe(sort); + + search.focus(); + fireEvent.keyDown(search, { key: "ArrowRight" }); + expect(document.activeElement).toBe(search); + }); +}); diff --git a/packages/core/src/components/toolbar/toolbar.tsx b/packages/core/src/components/toolbar/toolbar.tsx new file mode 100644 index 000000000..0fbc1225b --- /dev/null +++ b/packages/core/src/components/toolbar/toolbar.tsx @@ -0,0 +1,201 @@ +import * as React from "react"; + +import { cn } from "@/lib/utils"; +import { Separator as BaseSeparator } from "../internals/separator"; + +type ToolbarItemOptions = { + /** Leave Arrow/Home/End handling to a composite control such as Tabs or Select. */ + handlesDirectionalKeys?: boolean; +}; + +type ToolbarItemContextValue = { + registerItem: (element: HTMLElement, options: ToolbarItemOptions) => void; + unregisterItem: (element: HTMLElement) => void; + updateItem: (element: HTMLElement, options: ToolbarItemOptions) => void; +}; + +// Base UI's Toolbar registers only its own Button/Input/Link parts. Keep the +// registry here so existing AppShell controls can join a Toolbar.Row without +// consumer wrappers while retaining their own ARIA and composite-key behavior. +const ToolbarItemContext = React.createContext(null); +const useIsomorphicLayoutEffect = + typeof document === "undefined" ? React.useEffect : React.useLayoutEffect; + +export function mergeRefs(...refs: Array | undefined>) { + return (element: T | null) => { + for (const ref of refs) { + if (typeof ref === "function") ref(element); + else if (ref) (ref as React.MutableRefObject).current = element; + } + }; +} + +/** + * Registers an AppShell control with its containing `Toolbar.Row`, when any. + * This is internal plumbing: consumers place Button/Input/Select/etc. directly. + */ +export function useToolbarItem( + ref: React.RefObject, + options: ToolbarItemOptions = {}, +) { + const toolbar = React.useContext(ToolbarItemContext); + const { handlesDirectionalKeys = false } = options; + + useIsomorphicLayoutEffect(() => { + const element = ref.current; + if (!toolbar || !element) return; + + toolbar.registerItem(element, { handlesDirectionalKeys }); + return () => toolbar.unregisterItem(element); + }, [toolbar, ref]); + + useIsomorphicLayoutEffect(() => { + const element = ref.current; + if (toolbar && element) toolbar.updateItem(element, { handlesDirectionalKeys }); + }, [toolbar, ref, handlesDirectionalKeys]); +} + +function isFocusable(element: HTMLElement) { + return ( + element.isConnected && + element.tabIndex >= 0 && + !element.matches(":disabled") && + element.getAttribute("aria-disabled") !== "true" + ); +} + +export type ToolbarProps = React.ComponentProps<"div">; + +/** A full-width visual container for one or more rows of related controls. */ +function Root({ className, ...props }: ToolbarProps) { + return ( +
+ ); +} +Root.displayName = "Toolbar.Root"; + +type ToolbarRowProps = Omit, "role" | "onKeyDown"> & { + /** Distribute the row's outer groups between its two edges. */ + justify?: "start" | "between"; + onKeyDown?: React.KeyboardEventHandler; +}; + +/** One independently navigable horizontal row of toolbar controls. */ +function Row({ + className, + justify = "start", + onKeyDown, + ref: forwardedRef, + ...props +}: ToolbarRowProps) { + const rowRef = React.useRef(null); + const items = React.useRef(new Map()); + const registerItem = React.useCallback((element: HTMLElement, options: ToolbarItemOptions) => { + items.current.set(element, options); + }, []); + const unregisterItem = React.useCallback((element: HTMLElement) => { + items.current.delete(element); + }, []); + const updateItem = React.useCallback((element: HTMLElement, options: ToolbarItemOptions) => { + if (items.current.has(element)) items.current.set(element, options); + }, []); + const toolbar = React.useMemo( + () => ({ registerItem, unregisterItem, updateItem }), + [registerItem, unregisterItem, updateItem], + ); + + const handleKeyDown: React.KeyboardEventHandler = (event) => { + onKeyDown?.(event); + if (event.defaultPrevented || !["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) { + return; + } + + // Context crosses React portals, but popup controls outside this row are + // never toolbar items. + const controls = Array.from(items.current) + .filter(([element]) => rowRef.current?.contains(element) && isFocusable(element)) + .toSorted(([a], [b]) => { + const position = a.compareDocumentPosition(b); + return position & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1; + }); + const currentIndex = controls.findIndex(([element]) => element === document.activeElement); + if (currentIndex === -1 || controls[currentIndex][1].handlesDirectionalKeys) return; + + let nextIndex = currentIndex; + if (event.key === "Home") nextIndex = 0; + if (event.key === "End") nextIndex = controls.length - 1; + if (event.key === "ArrowLeft") + nextIndex = (currentIndex - 1 + controls.length) % controls.length; + if (event.key === "ArrowRight") nextIndex = (currentIndex + 1) % controls.length; + + event.preventDefault(); + controls[nextIndex]?.[0].focus(); + }; + + return ( + +
+ + ); +} +Row.displayName = "Toolbar.Row"; + +type ToolbarGroupProps = React.ComponentProps<"div">; + +/** A related group of controls within a toolbar row. */ +function Group({ className, ...props }: ToolbarGroupProps) { + return ( +
+ ); +} +Group.displayName = "Toolbar.Group"; + +type ToolbarSeparatorProps = Omit, "role" | "aria-orientation">; + +/** A vertical separator for groups within a horizontal toolbar row. */ +function Separator({ className, ...props }: ToolbarSeparatorProps) { + return ( + + ); +} +Separator.displayName = "Toolbar.Separator"; + +export const Toolbar = { + Root, + Row, + Group, + Separator, +}; diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 9148a70f1..dd96cbb11 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -206,6 +206,7 @@ export { Menu } from "./components/menu"; export type { PositionProps } from "./lib/position"; export { Sheet } from "./components/sheet"; export { Tabs } from "./components/tabs"; +export { Toolbar, type ToolbarProps } from "./components/toolbar"; export { Tooltip } from "./components/tooltip"; export { Select, type SelectAsyncFetcher } from "./components/select"; export { Combobox, type ComboboxAsyncFetcher } from "./components/combobox";