@lotics/ui 11.4.0 → 11.6.0

package/src/table.tsx

@@ -1,6 +1,7 @@
 import {
   createContext,
   useContext,
+  useState,
   Children,
   cloneElement,
   isValidElement,
@@ -12,24 +13,26 @@ import { Text } from "./text";
 import { colors } from "./colors";
 import { PressableRow } from "./pressable_row";
 import { Divider } from "./divider";
+import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
+import { COLUMN_GAP, ROW_GUTTER, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
 
 /**
  * One column of a register — its width/flex/align/label/sortability defined ONCE,
- * here, instead of being re-typed in the header band AND every row.
+ * here, instead of being re-typed in the header band AND every row. The fit
+ * fields (`key`/`width`/`priority`) live on `TableFitColumn` — the pure fit
+ * layer in `table_fit.ts` that decides which columns survive a narrow container.
  */
-export interface TableColumn {
-  /** Stable id — also the `sortKey` when `sortable`. */
-  key: string;
-  /** Header label (uppercase eyebrow). Omit for a control column (a trailing ⋯). */
+export interface TableColumn extends TableFitColumn {
+  /** Header label (uppercase eyebrow). Omit for a control column (a trailing ⋯).
+   *  In stacked mode it renders as the eyebrow over the cell's value. */
   label?: string;
-  /** Fixed width in px; omit for a flexible column. */
-  width?: number;
   /** Flex grow when no `width` (default 1). */
   flex?: number;
   align?: "left" | "right";
+  /** The `key` doubles as the `sortKey`. */
   sortable?: boolean;
 }
 
@@ -37,6 +40,8 @@ interface TableCtx {
   columns: TableColumn[];
   leading: number;
   trailing: number;
+  visibleKeys: ReadonlySet<string>;
+  stacked: boolean;
 }
 const TableContext = createContext<TableCtx | null>(null);
 
@@ -73,34 +78,64 @@ export interface TableProps {
  * sortable column becomes a `SortHeader`) and its `TableRow` children,
  * `Divider`-separated. Compose `TableRow` / `TableCell` for the body. For a
  * non-columnar list (entity piles, card stacks) use `PressableRow` directly.
+ *
+ * The register is container-responsive with no prop: when the measured width
+ * can't fit every column it drops droppable columns by `priority`, and below
+ * the register floor rows stack (label over value, from the column `label`s) —
+ * the header band gives way (sorting rides the columns; a stacked register
+ * keeps its current order). See `computeTableFit`.
  */
 export function Table(props: TableProps) {
   const { columns, sort, onSort, sortLabels, selectAll, leading = 0, trailing = 0, children } = props;
   const rows = Children.toArray(children).filter(isValidElement);
 
+  // Measure-then-REVEAL (the `DetailTable` contract): the unmeasured first
+  // frame renders invisible, so the first PAINT is already in the right mode —
+  // no register→stacked reshuffle as the screen mounts.
+  const [width, setWidth] = useState<number | null>(null);
+  const fit: TableFit =
+    width == null
+      ? { visibleKeys: new Set(columns.map((c) => c.key)), stacked: false }
+      : computeTableFit(columns, leading, trailing, width);
+  const visibleColumns = columns.filter((c) => fit.visibleKeys.has(c.key));
+
   return (
-    <TableContext.Provider value={{ columns, leading, trailing }}>
+    <TableContext.Provider value={{ columns, leading, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
       {/* ONE layout node: without this wrapper the header band + body land as two
           direct flex children of the app's container, and a parent column `gap`
           (the standard section spacing) opens a hole between the header and rows. */}
-      <View>
-        <View style={styles.headerBand}>
-          {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
-          {columns.map((col) => (
-            <View key={col.key} style={colStyle(col)}>
-              {col.label ? (
-                col.sortable && onSort ? (
-                  <SortHeader label={col.label} sortKey={col.key} sort={sort ?? null} onSort={onSort} align={col.align} labels={sortLabels} />
-                ) : (
-                  <Text size="xs" color="muted" transform="uppercase" numberOfLines={1}>
-                    {col.label}
-                  </Text>
-                )
-              ) : null}
+      <View
+        onLayout={(e) => setWidth(e.nativeEvent.layout.width)}
+        style={width == null ? styles.unmeasured : null}
+      >
+        {fit.stacked ? (
+          // Stacked mode has no column band — labels moved into the rows. The
+          // select-all checkbox keeps its band: it's the bulk-select entry point,
+          // aligned over the rows' leading checkboxes.
+          selectAll != null && leading > 0 ? (
+            <View style={styles.headerBand}>
+              <View style={{ width: leading }}>{selectAll}</View>
             </View>
-          ))}
-          {trailing > 0 ? <View style={{ width: trailing }} /> : null}
-        </View>
+          ) : null
+        ) : (
+          <View style={styles.headerBand}>
+            {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
+            {visibleColumns.map((col) => (
+              <View key={col.key} style={colStyle(col)}>
+                {col.label ? (
+                  col.sortable && onSort ? (
+                    <SortHeader label={col.label} sortKey={col.key} sort={sort ?? null} onSort={onSort} align={col.align} labels={sortLabels} />
+                  ) : (
+                    <Text size="xs" color="muted" transform="uppercase" numberOfLines={1}>
+                      {col.label}
+                    </Text>
+                  )
+                ) : null}
+              </View>
+            ))}
+            {trailing > 0 ? <View style={{ width: trailing }} /> : null}
+          </View>
+        )}
         <View style={styles.body}>
           {rows.map((row, i) => (
             <View key={i}>
@@ -120,9 +155,15 @@ export type TableRowProps = {
   marked?: boolean;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
   leading?: ReactNode;
-  /** Outside the door, AFTER the cells (a ⋯ menu / a button) — width = Table `trailing`. */
+  /** Outside the door, AFTER the cells: the row's OVERFLOW chrome (a ⋯ `ActionMenu`).
+   *  Register mode renders it in the trailing gutter beside `action`; stacked mode keeps
+   *  it on the top line. Width = Table `trailing` (shared with `action`). */
   trailing?: ReactNode;
-  /** Min row height. Default 52. */
+  /** The row's primary action (a CTA `Button`). Register mode: in the trailing gutter,
+   *  before `trailing`; stacked mode: the content's bottom line, right-aligned — an action
+   *  reads at content scale, not as row chrome. Reserve Table `trailing` for it. */
+  action?: ReactNode;
+  /** Min row height (register mode; stacked rows size to their content). Default 52. */
   minHeight?: number;
   /** The `TableCell`s, one per column, in column order. */
   children: ReactNode;
@@ -151,34 +192,68 @@ export type TableRowProps = {
  * row, rounded to the register wash); mouse presses ride the `PressableRow`
  * surface, and nested controls claim their own. `leading`/`trailing` slots stay
  * independently pressable. Cells map to `Table`'s columns by position.
+ *
+ * In the Table's STACKED mode (container below the register floor) the same
+ * row renders as a pile: a top line of [leading] [first cell] [trailing], then
+ * the remaining cells as label-over-value blocks — same door, same wash, same
+ * slots, different geometry.
  */
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, trailing, minHeight = 52, children } = props;
+  const { onPress, selected, marked, accessibilityLabel, leading, trailing, action, minHeight = 52, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
 
-  const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[]).map(
-    (cell, i) => cloneElement(cell, { _column: ctx.columns[i] }),
-  );
+  const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[])
+    .map((cell, i) => ({ cell, column: ctx.columns[i] as TableColumn | undefined }))
+    // A dropped column drops its cell (stacked shows everything). Cells beyond
+    // the declared columns stay — same tolerance as the width mapping.
+    .filter(({ column }) => ctx.stacked || column == null || ctx.visibleKeys.has(column.key))
+    .map(({ cell, column }) => cloneElement(cell, { _column: column, _stacked: ctx.stacked }));
   const { focusVisible, focusProps } = useFocusRing();
 
+  const body = ctx.stacked ? (
+    <View style={styles.stackedBody}>
+      <View style={styles.stackedTopLine}>
+        {ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
+        <View style={styles.stackedPrimary}>{cells[0]}</View>
+        {trailing != null ? <View style={styles.slot}>{trailing}</View> : null}
+      </View>
+      {cells.length > 1 ? (
+        // The field lines sit on the identity column's text edge — indented
+        // past the leading gutter, never wrapping under the checkbox.
+        <View style={[styles.stackedFields, ctx.leading > 0 ? { paddingLeft: ctx.leading + COLUMN_GAP } : null]}>
+          {cells.slice(1)}
+        </View>
+      ) : null}
+      {action != null ? <View style={styles.stackedActionLine}>{action}</View> : null}
+    </View>
+  ) : null;
+
   // Read-only row (no `onPress`): a static, non-interactive row — no hover wash,
   // no pointer cursor, no focusable door — so a `Table` can present read-only
   // tabular data (a fee breakdown, a spec sheet) without implying the rows open
   // something. An interactive row (with `onPress`) keeps the full register surface.
   if (!onPress) {
+    if (ctx.stacked) {
+      return <View style={styles.staticStackedRow}>{body}</View>;
+    }
     return (
       <View style={styles.staticRow}>
         {ctx.leading > 0 ? <View style={{ width: ctx.leading }}>{leading}</View> : null}
         <View style={[styles.cells, { minHeight }]}>{cells}</View>
-        {ctx.trailing > 0 ? <View style={{ width: ctx.trailing, alignItems: "flex-end" }}>{trailing}</View> : null}
+        {ctx.trailing > 0 ? (
+          <View style={[styles.trailingSlot, { width: ctx.trailing }]}>
+            {action}
+            {trailing}
+          </View>
+        ) : null}
       </View>
     );
   }
 
   return (
     <PressableRow onPress={onPress} selected={selected} marked={marked} style={styles.row}>
-      {ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
+      {!ctx.stacked && ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
       {/* An absolutely-positioned sibling paints — and hit-tests — above in-flow
           content, which would swallow every cell control's press; the slots lift
           above it via zIndex 1 (z-index applies to flex items), so the door gets
@@ -191,8 +266,19 @@ export function TableRow(props: TableRowProps) {
         {...focusProps}
         style={[styles.door, focusVisible && { boxShadow: FOCUS_RING }]}
       />
-      <View style={[styles.cells, { minHeight }]}>{cells}</View>
-      {ctx.trailing > 0 ? <View style={[styles.slot, { width: ctx.trailing, alignItems: "flex-end" }]}>{trailing}</View> : null}
+      {ctx.stacked ? (
+        body
+      ) : (
+        <>
+          <View style={[styles.cells, { minHeight }]}>{cells}</View>
+          {ctx.trailing > 0 ? (
+            <View style={[styles.slot, styles.trailingSlot, { width: ctx.trailing }]}>
+              {action}
+              {trailing}
+            </View>
+          ) : null}
+        </>
+      )}
     </PressableRow>
   );
 }
@@ -201,11 +287,26 @@ export interface TableCellProps {
   children: ReactNode;
   /** @internal — injected by `TableRow` from the column at this cell's position. */
   _column?: TableColumn;
+  /** @internal — injected by `TableRow`; the Table is in stacked mode. */
+  _stacked?: boolean;
 }
 
-/** One cell — its width/align come from the column `TableRow` injects by position. */
+/** One cell — its width/align come from the column `TableRow` injects by position.
+ *  In stacked mode it IS a `DetailRow` (spread: muted label left, value at the
+ *  right edge) — the drawer's detail-row component, not a lookalike, so a
+ *  stacked register and the record workspace behind its door share one
+ *  vocabulary by construction. `DetailRow` values are arbitrary nodes (the
+ *  drawer renders badges, money stacks, editors, popover triggers in them), so
+ *  register cell content needs no adaptation. A label-less control column has
+ *  no line to spread — its content pins to the right edge. */
 export function TableCell(props: TableCellProps) {
-  const { children, _column } = props;
+  const { children, _column, _stacked } = props;
+  if (_stacked) {
+    if (!_column?.label) {
+      return <View style={styles.stackedBareCell}>{children}</View>;
+    }
+    return <DetailRow label={_column.label}>{children}</DetailRow>;
+  }
   return <View style={_column ? colStyle(_column) : undefined}>{children}</View>;
 }
 
@@ -213,11 +314,11 @@ const styles = StyleSheet.create({
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
   headerBand: {
-    paddingHorizontal: 20,
+    paddingHorizontal: ROW_GUTTER,
     paddingVertical: 10,
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
+    gap: COLUMN_GAP,
     borderBottomWidth: 1,
     borderColor: colors.border,
   },
@@ -226,15 +327,22 @@ const styles = StyleSheet.create({
     gap: 0,
   },
   row: {
-    gap: 14,
+    gap: COLUMN_GAP,
   },
   // Read-only row (a `TableRow` with no `onPress`): the register row's gutter +
   // layout so cells still align with the header, minus the hover/press surface.
   staticRow: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
-    paddingHorizontal: 20,
+    gap: COLUMN_GAP,
+    paddingHorizontal: ROW_GUTTER,
+  },
+  // Row-direction like the pressable path — the body fills the width via
+  // `flex: 1` on the horizontal axis and sizes its own height (a `flex: 1`
+  // child of an auto-height COLUMN parent risks collapsing to zero).
+  staticStackedRow: {
+    flexDirection: "row",
+    paddingHorizontal: ROW_GUTTER,
   },
   // The keyboard door: an empty overlay spanning the row — the tab stop + focus
   // ring live here, the cells are its SIBLINGS (see TableRow's doc). Radius
@@ -251,7 +359,7 @@ const styles = StyleSheet.create({
     flex: 1,
     flexDirection: "row",
     alignItems: "center",
-    gap: 14,
+    gap: COLUMN_GAP,
     zIndex: 1,
   },
   // Leading/trailing gutters carry their own controls — lifted above the door
@@ -259,4 +367,53 @@ const styles = StyleSheet.create({
   slot: {
     zIndex: 1,
   },
+  // Stacked (below the register floor): the row is a pile — top line keeps the
+  // leading/trailing slots on the first cell, the rest are label-over-value
+  // blocks. Vertical padding replaces the register's minHeight centering.
+  stackedBody: {
+    flex: 1,
+    gap: 10,
+    paddingVertical: 12,
+    zIndex: 1,
+  },
+  stackedFields: {
+    gap: 8,
+  },
+  // The register's trailing gutter composes [action, overflow] on one row —
+  // the gap matches the composite the templates previously hand-rolled.
+  trailingSlot: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    gap: 8,
+  },
+  // Stacked mode: the CTA closes the content, right-aligned — content scale,
+  // not row chrome (the overflow ⋯ stays on the top line).
+  stackedActionLine: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+  },
+  stackedTopLine: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: COLUMN_GAP,
+    minHeight: 40,
+  },
+  stackedPrimary: {
+    flex: 1,
+    minWidth: 0,
+  },
+  // A label-less cell in stacked mode: no label to spread against — content
+  // pins right, on the `DetailRow` line rhythm.
+  stackedBareCell: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    alignItems: "center",
+    minHeight: 28,
+  },
+  // Measure-then-reveal: invisible until the container width is known, so the
+  // first visible frame is already register OR stacked — never a reshuffle.
+  unmeasured: {
+    opacity: 0,
+  },
 });

package/src/table_fit.ts

@@ -0,0 +1,88 @@
+/**
+ * The fit layer for `Table` — the pure decision of which columns fit a measured
+ * container width, kept free of any React-Native import so it unit-tests
+ * directly (the register in `table.tsx` renders this result; see `matrix_totals`
+ * for the same split).
+ *
+ * The register degrades in two deterministic tiers instead of overflowing.
+ * Tier 1: everything fits → the columnar register, unchanged. Tier 2: drop
+ * droppable columns by `priority` until the rest fit (the row is a scannable
+ * index — the door opens the record where dropped values live). Tier 3: even
+ * the minimum column set can't fit (a phone) → every row STACKS, label above
+ * value. All of it derives from the container width (onLayout, not the
+ * viewport) so a register inside a half-width panel adapts exactly like one on
+ * a small screen — the same contract as `DetailTable` / `Breakdown`.
+ */
+
+/** The column fields the fit decision reads — `TableColumn` extends this. */
+export interface TableFitColumn {
+  /** Stable id. */
+  key: string;
+  /** Fixed width in px; omit for a flexible column. */
+  width?: number;
+  /** Drop precedence when the container can't fit every column: HIGHER numbers
+   *  drop first, ties drop right-to-left. Default = the column's index (so an
+   *  unannotated register sheds from the right). The FIRST column is the row's
+   *  identity — it never drops. */
+  priority?: number;
+}
+
+/** Gap between the header band's / a row's children — `table.tsx` styles consume
+ *  this, so the fit math and the rendered geometry can't drift. */
+export const COLUMN_GAP = 14;
+/** The register's horizontal gutter — mirrors `PressableRow`'s register variant
+ *  (`paddingHorizontal: 20`), the one geometry this file models but doesn't own.
+ *  `table.tsx` consumes it for the header band and static rows. */
+export const ROW_GUTTER = 20;
+const ROW_H_PADDING = ROW_GUTTER * 2;
+/** Fit-math width a flexible column needs to stay usable — below this the flex
+ *  column is crushed to ellipsis soup, so it counts as this wide when deciding
+ *  what fits. Layout still lets it grow (`flex`) or shrink (`minWidth: 0`). */
+const FLEX_MIN_WIDTH = 120;
+/** Fewer side-by-side columns than this stops being a register — stack instead. */
+const MIN_VISIBLE_COLUMNS = 2;
+
+export interface TableFit {
+  /** Keys of the columns that render side-by-side. All keys when `stacked`. */
+  visibleKeys: ReadonlySet<string>;
+  /** The minimum column set can't fit — rows render as label-over-value stacks. */
+  stacked: boolean;
+}
+
+/**
+ * Pure fit decision for a measured container width: which columns stay
+ * side-by-side, or whether the register stacks.
+ */
+export function computeTableFit(
+  columns: TableFitColumn[],
+  leading: number,
+  trailing: number,
+  width: number,
+): TableFit {
+  const requiredWidth = (cols: TableFitColumn[]): number => {
+    const slots = cols.length + (leading > 0 ? 1 : 0) + (trailing > 0 ? 1 : 0);
+    const gaps = Math.max(0, slots - 1) * COLUMN_GAP;
+    const colsWidth = cols.reduce((sum, c) => sum + (c.width ?? FLEX_MIN_WIDTH), 0);
+    return ROW_H_PADDING + (leading > 0 ? leading : 0) + (trailing > 0 ? trailing : 0) + colsWidth + gaps;
+  };
+
+  const allKeys = new Set(columns.map((c) => c.key));
+  const priorityOf = (c: TableFitColumn) => c.priority ?? columns.indexOf(c);
+  // Column 0 never enters the drop order — it's the row's identity.
+  const dropOrder = columns
+    .slice(1)
+    .sort((a, b) => priorityOf(b) - priorityOf(a) || columns.indexOf(b) - columns.indexOf(a));
+
+  const kept = new Set(allKeys);
+  const floor = Math.min(MIN_VISIBLE_COLUMNS, columns.length);
+  for (const col of dropOrder) {
+    if (kept.size <= floor) break;
+    if (requiredWidth(columns.filter((c) => kept.has(c.key))) <= width) break;
+    kept.delete(col.key);
+  }
+  if (requiredWidth(columns.filter((c) => kept.has(c.key))) > width) {
+    // Below the register floor: stack every column (vertical space is free).
+    return { visibleKeys: allKeys, stacked: true };
+  }
+  return { visibleKeys: kept, stacked: false };
+}