pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/data-table/DataTable.variants.js

@@ -0,0 +1,189 @@
+"use strict";
+
+import { StyleSheet } from "react-native";
+/**
+ * DataTable's style + behaviour resolution — the same split every sibling module copies
+ * (see `Select.variants.ts` / `Menu.variants.ts`):
+ *  - STRUCTURE (row/cell layout, padding, border WIDTH) lives in the variant resolvers below —
+ *    static per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveDataTableColors`), never a raw ramp,
+ *    never a hardcoded hex. A table has no per-instance colour choice, so the resolver takes no
+ *    selector argument (same shape as `resolveCheckboxColors`).
+ *  - BEHAVIOUR (sort cycling, selection set maths, the sorted-column accessible name) is pure here
+ *    so the contract is unit-testable without rendering React Native.
+ *
+ * Free of React, of `lucide`, and of any native import, so the WCAG + behaviour tests import it
+ * directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants, createVariants } from "../../core/style/index.js";
+
+/** The three glyphs a header can show. A literal union rather than an `IconName` import, so this
+ *  file stays free of the icon registry (which pulls `lucide` at runtime); `Icon`'s own `name` prop
+ *  still type-checks these against the closed `IconName` set at the call site. */
+
+/** Same touch-target floor as Button/Select (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export const MIN_TOUCH_TARGET = 44;
+
+/** Header cells are sortable buttons, so the header is a direct 44dp target — never slop-expanded. */
+export const DATA_TABLE_HEADER_HEIGHT = MIN_TOUCH_TARGET;
+export const DATA_TABLE_DEFAULT_ROW_HEIGHT = 48;
+export const DATA_TABLE_DEFAULT_COLUMN_WIDTH = 120;
+export const DATA_TABLE_SELECT_COLUMN_WIDTH = 48;
+export const DATA_TABLE_SORT_ICON_SIZE = 14;
+export const DATA_TABLE_SKELETON_ROW_COUNT = 5;
+export const DATA_TABLE_SKELETON_CELL_HEIGHT = 12;
+
+/**
+ * Symmetric touch expansion for a pressable row, so `rowHeight + 2·slop ≥ 44` even when a caller
+ * passes a compact `rowHeight` (same `slopFor` technique `Button`/`Select` use for their short sizes).
+ */
+export function rowTouchSlop(rowHeight) {
+  return Math.max(0, Math.ceil((MIN_TOUCH_TARGET - rowHeight) / 2));
+}
+export function resolveColumnWidth(width) {
+  return width ?? DATA_TABLE_DEFAULT_COLUMN_WIDTH;
+}
+
+/** The row's full width — what the header and every body row are pinned to, so the two stay aligned
+ *  while the shared horizontal `ScrollView` moves them together. */
+export function resolveTotalWidth(widths, selectable) {
+  const columns = widths.reduce((sum, width) => sum + resolveColumnWidth(width), 0);
+  return columns + (selectable ? DATA_TABLE_SELECT_COLUMN_WIDTH : 0);
+}
+export function resolveDataTableColors(colors) {
+  return {
+    headerBackground: colors.bg.sunken,
+    headerText: colors.fg.muted,
+    headerIcon: colors.fg.muted,
+    headerBorder: colors.border.interactive,
+    rowBackground: colors.bg.surface,
+    rowBackgroundAlt: colors.bg.sunken,
+    rowPressed: colors.bg.raised,
+    cellText: colors.fg.default
+  };
+}
+
+/** Zebra striping, or the pressed fill when the row is being touched. */
+export function resolveRowBackground(colors, index, pressed) {
+  if (pressed) return colors.rowPressed;
+  return index % 2 === 0 ? colors.rowBackground : colors.rowBackgroundAlt;
+}
+
+/**
+ * asc → desc → asc on the active column; any other column starts at asc. Pressing a new column
+ * never inherits the previous column's direction — a fresh sort reads ascending.
+ */
+export function nextSortDirection(columnKey, activeKey, activeDirection) {
+  if (columnKey !== activeKey) return "asc";
+  return activeDirection === "asc" ? "desc" : "asc";
+}
+export function resolveSortIcon(columnKey, activeKey, activeDirection) {
+  if (columnKey !== activeKey) return "chevrons-up-down";
+  return activeDirection === "desc" ? "chevron-down" : "chevron-up";
+}
+
+/**
+ * WCAG 1.3.3 / 4.1.2 — the sort glyph is a visual-only cue, so the header's accessible name carries
+ * the same state in words. Without this a screen-reader user hears only the column title and cannot
+ * tell which column the table is sorted by.
+ */
+export function resolveSortAccessibilityLabel(header, columnKey, activeKey, activeDirection) {
+  if (columnKey !== activeKey) return `${header}, not sorted`;
+  return activeDirection === "desc" ? `${header}, sorted descending` : `${header}, sorted ascending`;
+}
+
+/**
+ * Fallback cell text when a column has no `render`. `row` is generic and unconstrained (a table
+ * accepts any shape of data), so reading `column.key` off it is a deliberate, narrow escape from
+ * `T` rather than a real type hole — the alternative is forcing every caller to supply `render`.
+ */
+export function resolveDefaultCellText(row, key) {
+  const value = row[key];
+  return value === undefined || value === null ? "" : String(value);
+}
+export function toggleSelectionKey(selectedKeys, key) {
+  return selectedKeys.includes(key) ? selectedKeys.filter(selected => selected !== key) : [...selectedKeys, key];
+}
+export function resolveSelectAllState(selectedKeys, rowKeys) {
+  const selectedHere = rowKeys.filter(key => selectedKeys.includes(key)).length;
+  const checked = rowKeys.length > 0 && selectedHere === rowKeys.length;
+  return {
+    checked,
+    indeterminate: selectedHere > 0 && !checked
+  };
+}
+
+/**
+ * Select-all only ever adds or removes the rows currently in `data` — a key selected elsewhere
+ * (a previous page, a filtered-out row) survives both directions, so the caller owns the full set.
+ */
+export function resolveSelectAllSelection(selectedKeys, rowKeys) {
+  if (resolveSelectAllState(selectedKeys, rowKeys).checked) {
+    return selectedKeys.filter(key => !rowKeys.includes(key));
+  }
+  return [...selectedKeys, ...rowKeys.filter(key => !selectedKeys.includes(key))];
+}
+export const dataTableRowStructure = createVariants({
+  base: {
+    flexDirection: "row",
+    alignItems: "stretch"
+  }
+});
+export const dataTableHeaderRowStructure = createThemedVariants(_theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "stretch",
+    height: DATA_TABLE_HEADER_HEIGHT,
+    borderBottomWidth: StyleSheet.hairlineWidth
+  }
+}));
+export const dataTableCellStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[1],
+    paddingHorizontal: theme.space[3]
+  },
+  variants: {
+    align: {
+      left: {
+        justifyContent: "flex-start"
+      },
+      center: {
+        justifyContent: "center"
+      },
+      right: {
+        justifyContent: "flex-end"
+      }
+    }
+  },
+  defaultVariants: {
+    align: "left"
+  }
+}));
+
+/**
+ * The keyboard/AT focus ring for a sortable header cell or a pressable row, drawn INSIDE the
+ * element's own bounds. Both are full-bleed: a header cell abuts its neighbours and a row spans the
+ * table's whole width, so the gap-outside ring `Button`/`CopyButton` use would be clipped by the
+ * table's own scroll containers. Square, like the cells it sits in. Colour is applied inline.
+ */
+export const dataTableFocusRingStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderWidth: theme.borderWidths.thick
+  }
+}));
+export const dataTableSelectCellStructure = createVariants({
+  base: {
+    width: DATA_TABLE_SELECT_COLUMN_WIDTH,
+    alignItems: "center",
+    justifyContent: "center"
+  }
+});
+//# sourceMappingURL=DataTable.variants.js.map

package/lib/module/modules/data-table/MODULE.md

@@ -0,0 +1,146 @@
+# data-table/ — a horizontally-scrollable, column-configured table
+
+`DataTable` renders column headers + rows for tabular data on a phone screen. Header and body live
+in ONE vertical `FlatList` (header as `ListHeaderComponent`, `stickyHeaderIndices={[0]}` for the
+pin) nested inside a single horizontal `ScrollView` — header and rows are always the same width and
+scroll sideways together with no hand-rolled scroll-offset syncing between two separate lists.
+
+Sort and selection are fully **controlled**, the same contract `Select` uses for `value`: DataTable
+never sorts `data` itself and never owns `selectedKeys` — it reports the next state via
+`onSortChange`/`onSelectionChange` and renders whatever the caller passes back in.
+
+## Files
+
+| File | Role |
+|------|------|
+| `DataTable.tsx` | The component. Header/row/skeleton/empty JSX built inline per render (Select's precedent), one `FlatList` wired with `stickyHeaderIndices`. |
+| `DataTable.variants.ts` | Pure resolvers (`resolveDataTableColors`, `nextSortDirection`, `resolveSortIcon`, `resolveSortAccessibilityLabel`, `toggleSelectionKey`, `resolveSelectAllState`, `resolveSelectAllSelection`, `resolveDefaultCellText`, `resolveRowBackground`, `resolveTotalWidth`) + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `DataTable`, `DataTableProps`, `DataTableColumn`, `DataTableAlign`, `DataTableSortDirection`. |
+| `__tests__/DataTable.test.ts` | Pure: WCAG contrast (all brands × modes) + sort/selection/formatting contracts. |
+| `__tests__/DataTable.render.test.tsx` | Render: headers/cells, header **position** in the rendered order (both `stickyHeader` values, empty and loading), the sticky pin, header-offset row layout, per-cell column naming, row press, sort cycling, select-all/row selection, loading, empty state. |
+| `__tests__/DataTable.perf.test.tsx` | Perf: mounted rows stay bounded for a 10k dataset; an unrelated outer `style` change mounts no extra rows. |
+| `__tests__/DataTable.dom.test.tsx` | Real DOM (`jest.web.config.js`): a non-sortable header renders `<h3>`; a sortable header renders `<h3>` AND its sort control keeps `role="button"`, nested inside it. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `columns` | `DataTableColumn<T>[]` | — | `{ key, header, width?, align?, render?, sortable? }`. `render`'s `ReactNode`, if textual, must be caller-wrapped in `<Text>` — same convention as `ListItem`'s `leading`/`trailing`. |
+| `data` | `T[]` | — | Required. |
+| `keyExtractor` | `(row, index) => string` | — | Required; also seeds each row's `testID`. |
+| `onRowPress` | `(row, index) => void` | — | Absent = rows are plain `View`s, not `Pressable`. |
+| `sortBy` / `sortDirection` | `string` / `asc \| desc` | — | Controlled, like `Select`'s `value`. |
+| `onSortChange` | `(key, direction) => void` | — | Fired on a sortable header press; DataTable never sorts `data` itself. |
+| `selectable` | `boolean` | `false` | Adds a leading `Checkbox` column (select-all in the header). |
+| `selectedKeys` / `onSelectionChange` | `string[]` / `(keys) => void` | — | Controlled, like `sortBy`. |
+| `loading` | `boolean` | `false` | Swaps rows for `DATA_TABLE_SKELETON_ROW_COUNT` (5) `Skeleton` rows; header still renders. |
+| `emptyMessage` | `string` | `"No data"` | Passed to `EmptyState`'s `title` when `data` is empty and not loading. |
+| `stickyHeader` | `boolean` | `true` | `stickyHeaderIndices={[0]}` on the list. Controls the **pin only** — the header is `ListHeaderComponent` either way, so it is always rendered before row 0. |
+| `rowHeight` | `number` | `48` | Short values get `hitSlop`, same technique as `Select`'s compact sizes. Also feeds `getItemLayout`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Seeds `-header`, `-header-<key>` (the sort button on a sortable column, the heading `View` itself on a non-sortable one), `-header-<key>-heading` (the heading wrapper, sortable columns only), `-row-<i>`, `-row-<i>-select`, `-select-all`, `-skeleton-<i>`, `-empty`, `-scroll`, plus `-focus-ring` under a focused header cell or row. |
+
+## Accessibility contract (WCAG)
+
+- **1.4.3** — header text/icon and body cell text are measured ≥ 4.5:1 on every fill they can sit on
+  (header band, even row, odd/zebra row, pressed row) across all brands × both modes.
+- **1.4.11** — the header/body boundary is `border.interactive`, measured ≥ 3:1, not the decorative
+  `border.default` (a ~1.2:1 hairline on every brand — see `DataTable.test.ts`).
+- **1.3.3 / 4.1.2** — the sort glyph is a visual-only cue; a sortable header's accessible name embeds
+  the state in words ("Name, sorted ascending") so it isn't lost to a screen reader.
+- **1.3.1 — every column header keeps `accessibilityRole="header"`, sortable or not**, each with
+  `aria-level={3}` (`HEADING_LEVEL.subsection`, `core/heading`). A sortable column previously LOST
+  the header role entirely — the sort control (`role="button"`) replaced it on the same node instead
+  of sitting alongside it, so a fully-sortable table had no column headers in the accessibility tree
+  at all. Fixed by wrapping: an outer `HeadingView` (`accessibilityRole="header"`,
+  `testID={testID}-header-<key>-heading`) contains the inner sort `Pressable`
+  (`testID={testID}-header-<key>`, `accessibilityRole="button"`) — one node per role, not one node
+  fighting over two.
+- **2.5.8 / 2.5.5 target size** — the header row is a direct 44dp target (no slop needed); a narrow
+  sortable column or a compact `rowHeight` reaches 44dp via `hitSlop`, same `Select`/`Button` technique.
+- Selection reuses `Checkbox`'s own contract wholesale (tri-state `accessibilityState`, required
+  `accessibilityLabel` on every unlabelled box) — select-all announces `"Select all rows"`, a row
+  announces `"Select row <n>"`.
+- Loading and empty states inherit `Skeleton`'s (decorative, `accessibilityElementsHidden`) and
+  `EmptyState`'s own contracts unmodified.
+- **2.1.1 keyboard-reachable scroll region** — the outer horizontal `ScrollView` carries an explicit
+  `tabIndex={0}`. A plain display table (no `onRowPress`, no `sortable` column, `selectable={false}`)
+  has **no** focusable descendant at all, so its off-screen columns were unreachable by keyboard.
+  Explicit, rather than relying on Chrome/Firefox's auto-focusable-scroll-region behaviour, which
+  Safari and native RN do not have. Consequence: every table is one tab stop on web.
+- **2.4.7** — a sortable header cell and a pressable row each draw a `border.focus` ring
+  (`${testID}-header-<key>-focus-ring`, `${testID}-row-<i>-focus-ring`). Both are drawn **inside**
+  their own bounds: they are full-bleed inside two nested scroll containers, where the gap-outside
+  ring `Button`/`CopyButton` use is clipped on the very edges that carry it.
+- **2.4.11** — while `stickyHeader` is on, rows carry `scrollMarginTop: headerOffset` **on web
+  only**. A pinned header renders as `position: sticky`, and the browser scrolls a newly focused row
+  flush to the container's top edge — under the header, hiding the ring above. The margin reuses the
+  same `headerOffset` `getItemLayout` derives, so the two cannot drift.
+- **1.3.1 / 1.3.2 cell↔column association** — rows are read one cell at a time and the header is off
+  to the side or scrolled away, so a bare value is unattributable. Every default-formatted cell's
+  `Text` announces `"<column header>: <value>"`. The list itself inherits
+  `accessibilityRole="list"` from `core/list`.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split** — layout/padding/border-width via `createThemedVariants`; colour
+   resolved from `RoleColors` only, applied inline (`Select`/`Menu`/`Banner`).
+2. **Pure, testable resolvers** in `DataTable.variants.ts` — contrast, sort cycling, and selection
+   set maths are unit-tested directly, never eyeballed or exercised only through a render test.
+3. **Closed unions** — `align`, `sortDirection` are closed unions, never a free-form prop.
+4. **Fully controlled sort/selection** — mirrors `Select`'s `value`/`onValueChange` contract: the
+   component reports intent, the caller owns the state.
+
+## Design decisions specific to this module
+
+- **One `FlatList`, not two scroll views kept in sync.** The header is that FlatList's own
+  `ListHeaderComponent`, pinned via `stickyHeaderIndices={[0]}` — RN's built-in mechanism for
+  exactly this, so there is no manual `onScroll`/`scrollTo` offset-mirroring between a header list
+  and a body list.
+- **`stickyHeader` must never become a position.** When `core/list`'s `VirtualList` had no
+  `ListHeaderComponent` prop, "sticky" was re-expressed here as *where* the header rendered:
+  `stickyHeader={false}` moved it below the list, so a screen reader read all N rows and *then* the
+  column labels naming them (WCAG 1.3.2, meaningful sequence). The header is now always
+  `ListHeaderComponent`; `stickyHeader` toggles `stickyHeaderIndices` and nothing else. The render
+  test asserts the header's **position in the rendered order**, not its presence — presence is what
+  stayed green through the regression.
+- **The empty state is `ListEmptyComponent`**, not a sibling that replaces the list, so the column
+  header survives an empty result set.
+- **`getItemLayout` is passed directly, not derived from `itemHeight`.** Offsets are measured from
+  the top of the scroll content and the header cell sits above row 0, so every row's offset carries
+  a leading `DATA_TABLE_HEADER_HEIGHT + borderWidths.thin`; without it `scrollToIndex` lands one
+  header short.
+- **Needs a bounded ancestor for the sticky header / internal scroll to do anything** — the same
+  requirement RN's own docs state for `ScrollView` ("needs a bounded height… by setting height
+  directly, or by flex"). Place `DataTable` in a `style={{ flex: 1 }}` (or explicit height)
+  container; unbounded, it renders at full content height and the enclosing screen scrolls it —
+  never invisible, just not independently scrollable.
+- **Row press vs. the selection checkbox** — the checkbox is its own nested `Pressable`; RN's
+  responder system lets the innermost element claim a touch, so pressing the checkbox never also
+  fires `onRowPress` (the standard, well-established RN pattern for a checkbox-in-row).
+- **Row press feedback** — `usePressState` (scale + state-layer overlay) when `onRowPress` is set.
+- **Default cell text** reads `row[column.key]` through a narrow, documented `unknown` escape —
+  `T` is intentionally unconstrained so any row shape works without a `render`.
+
+## Known gaps
+
+- No pagination, column resize, or column reorder — v1 is fixed column widths from `columns`.
+- Skeleton is a fixed 5 rows regardless of `rowHeight` or viewport size.
+- `EmptyState` renders inside the same `totalWidth`-bound scroll region as the columns, so a very
+  narrow table gives it a narrow box rather than full screen width.
+- A column with a custom `render` gets no `"<header>: <value>"` label — the cell's content is the
+  caller's `ReactNode` and its text is not knowable here. Such a column should carry its own
+  accessible name inside `render`.
+
+## Performance
+
+Wrapped in `React.memo`; since the component itself is generic (`<T>`), `memo`'s erased type is
+restored with a documented `as typeof DataTableInner` cast. Header/row/skeleton/empty JSX are built
+inline per render, matching `Select`'s own precedent (its `renderItem` isn't extracted or memoized
+either) — real windowing for large datasets still comes from `FlatList` itself.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/data-table/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/data-table`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers (`resolveDataTableColors`, `nextSortDirection`, …) stay
+ * internal — a consumer configures a DataTable through its props, never by importing its internals.
+ */
+
+export { DataTable } from "./DataTable.js";
+//# sourceMappingURL=index.js.map