@spark-web/data-table 5.2.0 → 5.2.2

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @spark-web/data-table
 
+## 5.2.2
+
+### Patch Changes
+
+- [#798](https://github.com/brighte-labs/spark-web/pull/798)
+  [`a8425fd`](https://github.com/brighte-labs/spark-web/commit/a8425fd4c279ce5df76467b40aa114c14ef5e069)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  `DataTable` now automatically zeroes the `<td>` padding on cells whose direct
+  child is an `<a>`, so consumers using the row-as-link pattern can let the link
+  itself provide the cell padding. Without this, the cell's 16px padding ring
+  was unclickable. Nested anchors (deeper than direct child) are unaffected. See
+  the package's `CLAUDE.md` for the full pattern.
+
+## 5.2.1
+
+### Patch Changes
+
+- [#782](https://github.com/brighte-labs/spark-web/pull/782)
+  [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  **docs:** add CLAUDE.md AI context files to foundation and form packages;
+  patch data-table with manual sort and spinner overlay patterns
+
+- [#782](https://github.com/brighte-labs/spark-web/pull/782)
+  [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  **data-table:** add `isLoading` and `emptyState` props — renders a spinner +
+  "Loading" text or a custom empty node below the table; table now fills its
+  container width by default (`width: 100%`)
+
+- [#782](https://github.com/brighte-labs/spark-web/pull/782)
+  [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  **data-table:** Fix token gaps in CLAUDE.md (header cell padding, font-family,
+  loading/empty state containers, sort icon margin); add Composition section;
+  clarify row hover only applies to clickable rows and must be suppressed when
+  hovering a button inside the row
+
+  **design-system:** Update internal-admin surface rules with MeatballMenu hover
+  suppression rule; fix list-page.md MultiSelect label pattern (gap and text
+  size were contradicting the rules text); update pattern file code examples to
+  match
+
+  **meatball-menu:** Rewrite CLAUDE.md with full structure — What this is NOT,
+  complete token usage table, Composition section, and Do NOTs
+
+  **status-badge:** Rewrite CLAUDE.md with full structure — What this is NOT,
+  complete token usage table with per-tone background mapping, Composition
+  section, and Do NOTs
+
+- [#782](https://github.com/brighte-labs/spark-web/pull/782)
+  [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  **data-table:** align color tokens with @spark-web/table conventions — use
+  `primarySoft` for selected rows, `inputPressed` for hover, `primaryActive` for
+  header text/border; switch sort icons to `SortAscending/DescendingIcon`; add
+  `aria-sort` accessibility attribute; add CLAUDE.md AI context
+- Updated dependencies
+  [[`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)]:
+  - @spark-web/box@6.0.1
+  - @spark-web/spinner@5.1.1
+  - @spark-web/text@5.3.1
+
 ## 5.2.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -0,0 +1,262 @@
+# @spark-web/data-table — AI Context
+
+## What this package is
+
+A headless data table built on TanStack React Table v8. One component
+(`DataTable`) accepts column definitions and data, and renders a styled table
+with support for row selection, row expansion, column visibility, sorting, and
+infinite scroll.
+
+## What this package is NOT
+
+- Not responsible for data fetching, sorting logic, filtering, or pagination.
+  The parent owns those — `DataTable` surfaces sort state changes via
+  `onSortingChange`.
+- Not composable. `DataTable` is a single monolithic component — there are no
+  composable sub-component alternatives in this design system.
+
+## Component API
+
+`DataTable<T>` accepts:
+
+- `items: Array<T>` **(required)** — data rows
+- `columns: ColumnDef<T>[]` **(required)** — TanStack column definitions
+- `isLoading?: boolean` — controls the loading state row below the table body
+- `emptyState?: ReactNode` — rendered when `isLoading` is false and `items` is
+  empty
+- `state` — optional controlled state: `rowSelection`, `expanded`,
+  `columnVisibility`, `sorting`
+- `onRowSelectionChange` — enables row selection
+- `onRowClick` / `enableClickableRow` — row click behaviour
+- `onSortingChange` + `enableSorting` + `manualSorting` — sorting
+- `onExpandedChange` + `enableExpanding` + `expandedRowComponent` — expansion
+- `showBottomSpinner` + `onBottomSpinnerShown` — infinite scroll trigge
+- `renderRow` — full custom tbody replacement
+- `className` / `headerClassName` / `footerClassName` / `rowClassName` — style
+  overrides
+
+Always provide `isLoading` and `emptyState` in production usage — omitting them
+leaves the table with no loading indicator or empty state feedback.
+
+## Token usage
+
+All values from `useTheme()` from `@spark-web/theme`. Never use raw hex, px, or
+Tailwind.
+
+### Row states
+
+- Default: no background override (inherits surface)
+- Selected/expanded: `theme.color.background.primarySoft`
+- Hover: `theme.color.background.inputPressed` — applied only when
+  `enableClickableRow` is `true`. NEVER apply row hover to a non-clickable row.
+- Hover suppression: when a row contains a `MeatballMenu`, hovering over the
+  meatball button must NOT trigger the row hover. Implement using CSS `:has()`:
+  ```css
+  ':hover:not(:has(button:hover))': {
+    backgroundcolor: theme.color.background.inputPressed;
+  }
+  ```
+  This ensures the row highlight disappears when the cursor moves over any
+  button within the row, including the meatball trigger.
+
+### Header
+
+- Background: `theme.color.background.surface`
+- Border bottom: `theme.color.background.primaryDark` (via inset box-shadow:
+  `inset 0 -2px 0 0 ${theme.color.background.primaryDark}`)
+- Cell padding: `theme.spacing.medium` (via Box `padding="medium"` on `<th>`)
+- Text color: `theme.color.background.primaryDark`
+- Text transform: `capitalize` (inline CSS on `th`)
+- Sort icon stroke: `theme.color.background.primaryDark` (inline CSS on `svg`)
+- Font family: `theme.typography.fontFamily.sans.name`
+- Font weight: `theme.typography.fontWeight.semibold`
+- Sortable header hover: `theme.backgroundInteractions.primaryLowHover`
+
+### Cell
+
+- Padding: `theme.spacing.large` (all sides, via Box `padding="large"` on
+  `<td>`)
+- Border bottom: `theme.border.width.standard` solid
+  `theme.border.color.standard`
+- Vertical align: `middle` (inline CSS)
+- Text align: `left` (inline CSS)
+- **Padding auto-zero for link cells**: when a cell's direct child is an `<a>`
+  (the "row-as-link" pattern), `DataTable` automatically zeroes the `<td>`
+  padding via `&:has(> a)`. The link is expected to provide the visible padding
+  itself, which extends the clickable area over the cell's would-be padding
+  ring. Nested anchors (`<a>` deeper than direct child) do NOT trigger the rule.
+  See "Row-as-link navigation" below.
+
+### Row-as-link navigation
+
+When a row's purpose is to navigate to a URL, `onRowClick` is the wrong tool —
+it gives the row no `href`, so right-click → "Open link in new tab",
+cmd/ctrl-click, and middle-click don't work.
+
+Use anchor semantics instead:
+
+- Wrap each cell's content in your router's `<Link>` component (TanStack Router,
+  React Router, Next.js, etc.) with the row's destination. The `<Link>` must be
+  the **direct child** of the cell so the auto-padding-zero rule (see "Cell")
+  picks it up.
+- Style the link as a block that supplies the cell padding itself:
+  `display: block; padding: {theme.spacing.large}; color: inherit; text-decoration: none;`.
+  With the `<td>`'s built-in padding zeroed out under the `:has(> a)` rule and
+  the link's own padding filling that space, the link covers the entire cell —
+  including what would have been the dead 16px padding ring — so clicks anywhere
+  in the cell hit the anchor. Row height and text wrapping stay identical to the
+  default layout. Do NOT add `width: 100%` / `box-sizing: border-box` / negative
+  margins: any of these alters the cell's effective content width and causes
+  visible row-spacing or wrap differences.
+- Make only the **first** cell's link keyboard-focusable (`tabIndex={0}`); set
+  all other cell links to `tabIndex={-1}` so one row = one tab stop. N cells per
+  row should not produce N tab stops to the same destination.
+- Action-only cells (meatball menus, inline buttons) must NOT be wrapped in the
+  row link. Since they don't render an `<a>` as a direct child, the
+  auto-padding-zero rule won't fire on them and they keep their normal padding
+  (unless you've separately zeroed the action column via a `className` rule).
+- Drop `onRowClick` and `enableClickableRow` for that table — the anchors take
+  over navigation. Replicate the hover affordance with a `rowClassName` that
+  applies `theme.color.background.inputPressed` on hover (mirroring the
+  `:hover:not(:has(button:hover))` rule documented in "Row states").
+
+Reference implementation: `apps/admin-portal/src/components/RowLink` in the
+portal-hub repo (uses TanStack Router).
+
+### Sort icons
+
+Use `SortAscendingIcon` / `SortDescendingIcon` from `@spark-web/icon` at
+`size="xxsmall"` `tone="primaryActive"`. Never `ChevronUpIcon` /
+`ChevronDownIcon` for sort state.
+
+- Icon left margin: `theme.spacing.xsmall` (inline CSS on the `svg` selector)
+
+### Loading state (`isLoading`)
+
+Renders below the table body when `isLoading` is `true`. Does not overlay the
+table — replaces visible data feedback.
+
+- Container padding: `padding="xlarge"` (Box prop)
+- Container gap: `gap="small"` (Box prop)
+- Container alignment: `alignItems="center"`, `justifyContent="center"` (Box
+  props)
+- Text: `<Text tone="muted">Loading</Text>`
+- Spinner: `<Spinner tone="primary" />` — no explicit size; uses Spinner default
+
+### Empty state (`emptyState`)
+
+Renders below the table body when `isLoading` is `false` and `items` is empty.
+
+- Container padding: `padding="xlarge"` (Box prop)
+- Container alignment: `justifyContent="center"` (Box prop)
+- Content: caller-provided `ReactNode` — always pass
+  `<Text tone="muted" size="small">…</Text>`
+
+## Composition
+
+- `Box` from `@spark-web/box` — outer wrapper, `<table>`, `<thead>`, `<tbody>`,
+  `<tfoot>`, `<tr>`, `<th>`, `<td>` elements
+- `SortAscendingIcon` / `SortDescendingIcon` from `@spark-web/icon` — sort state
+  icons in sortable header cells
+- `Spinner` from `@spark-web/spinner` — loading overlay (via `isLoading`) and
+  infinite-scroll bottom spinner (via `showBottomSpinner`)
+- `Text` from `@spark-web/text` — "Loading" label in `isLoading` state
+- `InView` from `react-intersection-observer` — triggers `onBottomSpinnerShown`
+  when the bottom spinner enters the viewport
+
+## Column definitions
+
+Use `createColumnHelper<T>()` from this package for type-safe column defs:
+
+```tsx
+import { createColumnHelper } from '@spark-web/data-table';
+const col = createColumnHelper<MyType>();
+```
+
+Cell renderers receive `info` (`CellContext`) — use `info.getValue()` or
+`info.renderValue()`. Wrap cell content in `<Text size="small">` from
+`@spark-web/text`.
+
+## Manual sort state
+
+When `manualSorting` is `true`, the parent owns sort state and must pass it back
+to `DataTable` via `state.sorting`. Wire it up like this:
+
+```tsx
+const [sorting, setSorting] = useState<SortingState>([]);
+
+<DataTable
+  items={data}
+  columns={columns}
+  enableSorting
+  manualSorting
+  state={{ sorting }}
+  onSortingChange={setSorting}
+/>;
+```
+
+- `enableSorting` — enables the sort UI on column headers
+- `manualSorting` — tells TanStack Table not to sort `items` itself; the parent
+  must re-fetch/re-sort when `onSortingChange` fires
+- `onSortingChange` — receives the new `SortingState`; pass it to your query as
+  an `orderBy` parameter
+- `state.sorting` — controlled sort state, keeps headers in sync with data
+
+To make a specific column sortable, set `enableSorting: true` on its
+`ColumnDef`. To disable sorting on a specific column, set
+`enableSorting: false`.
+
+## Spinner overlay (external loading, before table mounts)
+
+Use `DataTable`'s `isLoading` prop for in-table loading. Only use an external
+Spinner overlay when the table cannot mount yet — e.g. a full-region loading
+state before you have any data at all, or a loading state that covers the entire
+page section including the filter bar:
+
+```tsx
+{
+  isLoading ? (
+    <Box
+      display="flex"
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      gap="small"
+      padding="xlarge"
+    >
+      <Spinner tone="primary" size="xsmall" />
+      <Text tone="muted">Loading</Text>
+    </Box>
+  ) : (
+    <DataTable items={data} columns={columns} isLoading={isFetching} />
+  );
+}
+```
+
+The distinction:
+
+- `isLoading` (initial, no table yet) → external Spinner overlay
+- `isFetching` (refetch while table exists) → pass to `DataTable` `isLoading`
+
+## Do NOTs
+
+- NEVER raw hex values — always use theme color tokens
+- NEVER raw pixel values — always use theme spacing/sizing tokens
+- NEVER Tailwind classes
+- NEVER `ChevronUp/DownIcon` for sort — use `SortAscending/DescendingIcon`
+- NEVER `primaryMuted` for selected rows — use `primarySoft`
+- NEVER `neutralHover` for row hover — use `color.background.inputPressed`
+- NEVER apply row hover to a non-clickable row — only rows with
+  `enableClickableRow` get hover
+- NEVER let row hover fire when the cursor is over a button inside the row — use
+  `:hover:not(:has(button:hover))` to suppress it
+- NEVER use `onRowClick` for URL-destination navigation — it breaks "Open in new
+  tab", cmd/ctrl-click, and middle-click. Wrap cell content in your router's
+  `<Link>` instead. See "Row-as-link navigation".
+- NEVER put pagination inside `DataTable` — caller handles it externally
+- NEVER render an external `<Spinner>` alongside a mounted `DataTable` — use the
+  `isLoading` prop instead. An external Spinner is only correct before the table
+  can mount (initial page load with no data yet).
+- NEVER pass a string class from `@emotion/css` to `className` or
+  `headerClassName` — these props expect `SerializedStyles` from
+  `@emotion/react`'s `css` tagged template

package/dist/declarations/src/data-table.d.ts

@@ -2,13 +2,13 @@ import type { SerializedStyles } from '@emotion/react';
 import { type DataAttributeMap } from '@spark-web/utils/internal';
 import type { ColumnDef, ColumnHelper, ExpandedState, OnChangeFn, Row, SortingState, Table, TableOptions } from '@tanstack/react-table';
 import { createColumnHelper, flexRender } from '@tanstack/react-table';
-import type { ReactElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 /**
  * DataTable
  *
  * @see https://spark.brighte.com.au/package/data-table
  */
-declare function DataTable<T>({ data, items, className, columns, enableExpanding, enableHiding, enableMultiRowSelection, enableClickableRow, headerClassName, footerClassName, showBottomSpinner: showSpinner, rowClassName, expandedRowComponent, onBottomSpinnerShown, onRowClick, onRowSelectionChange, renderRow, ...tableOptions }: DataTableProps<T>): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function DataTable<T>({ data, items, className, columns, enableExpanding, enableHiding, enableMultiRowSelection, enableClickableRow, headerClassName, footerClassName, showBottomSpinner: showSpinner, rowClassName, expandedRowComponent, onBottomSpinnerShown, onRowClick, onRowSelectionChange, renderRow, isLoading, emptyState, ...tableOptions }: DataTableProps<T>): import("@emotion/react/jsx-runtime").JSX.Element;
 type TableSubsetOptions<T> = Pick<TableOptions<T>, 'columns' | 'enableExpanding' | 'enableHiding' | 'enableMultiRowSelection' | 'state' | 'onStateChange' | 'onExpandedChange' | 'onRowSelectionChange' | 'getRowId' | 'enableSorting' | 'manualSorting'>;
 type DataTableProps<T> = TableSubsetOptions<T> & {
     className?: SerializedStyles;
@@ -25,6 +25,10 @@ type DataTableProps<T> = TableSubsetOptions<T> & {
     onRowClick?: (row: Row<T>) => void;
     renderRow?: (table: Table<T>) => ReactElement<T>;
     onSortingChange?: OnChangeFn<SortingState>;
+    /** When true, renders a centered spinner + "Loading" text below the table. */
+    isLoading?: boolean;
+    /** Rendered below the table when not loading and items is empty. */
+    emptyState?: ReactNode;
 };
 export { createColumnHelper, DataTable, flexRender };
 export type { ColumnDef, ColumnHelper, DataTableProps, Row as DataTableRow, ExpandedState, OnChangeFn, };