@lotics/ui 47.13.0 → 47.14.0

package/src/section_nav.tsx

@@ -0,0 +1,163 @@
+import { useRef, useState, type ReactNode } from "react";
+import { View } from "react-native";
+import { Badge } from "./badge";
+import { Button } from "./button";
+import { colors } from "./colors";
+import { type IconName } from "./icon";
+import { useLoticsLocale } from "./locale";
+import { MenuButton } from "./menu_button";
+import { Popover, PopoverContent } from "./popover";
+
+/** One stop on the outline. `issue` is what makes the nav answer "where is the
+ *  problem" and not merely "where am I" — the section still states the condition
+ *  itself beside the fields it concerns; this only says where to look. */
+export interface SectionNavItem<K extends string = string> {
+  key: K;
+  label: string;
+  icon: IconName;
+  issue?: "warning" | "danger";
+}
+
+export interface SectionNavProps<K extends string = string> {
+  /** In PAGE ORDER — the same order `useSectionNav` spies on. */
+  items: readonly SectionNavItem<K>[];
+  /** From `useSectionNav().activeKey`. */
+  activeKey: K;
+  /** From `useSectionNav().jumpTo`. */
+  onJump: (key: K) => void;
+  /**
+   * Rail when true, pinned bar when false.
+   *
+   * The CALLER decides, from its own measured container — never from the window.
+   * A record surface renders inside a page and inside a drawer, and a window
+   * read gives the drawer the page's answer: the rail appears in a column that
+   * has no gutter to hold it.
+   */
+  wide: boolean;
+  /**
+   * Where this record returns to — a `BackButton`, in both forms.
+   *
+   * The rail's standard opens with it, visually apart from the outline items; the
+   * bar keeps it for the same reason. Omit it where the container already has
+   * one (a drawer's own header), because two exits are two exits.
+   */
+  back?: ReactNode;
+  /** Rail width. The gutter it floats in is the caller's arithmetic. */
+  railWidth?: number;
+  /** The bar's horizontal gutter. A fill-less button shows no box, so its INK is
+   *  what lines up with the section titles below: pass the container's content
+   *  padding and this subtracts the button's own. */
+  barGutter?: number;
+}
+
+/**
+ * The record surface's outline, in its two forms.
+ *
+ * `useSectionNav` is the scroll-spy half — offsets, `activeKey`, `jumpTo`. This
+ * is the CHROME half, and the two are used together: the hook decides which
+ * section the reader is in, this draws the list that says so and jumps.
+ *
+ * ## The two forms are one list
+ *
+ * Where the container affords a gutter, the outline is a RAIL floating in it.
+ * Where it does not, the same list collapses to a pinned bar naming the CURRENT
+ * section, which opens the list as a picker. Both render the same items with the
+ * same `current` item and the same attention dots, because they are one control
+ * — a reader who learns the rail has learned the bar.
+ *
+ * The picker anchors to the bar's own button (`triggerRef`, since the trigger IS
+ * a `Button` and a button must not nest in a pressable), so it is scoped to
+ * whatever container that bar sits in. A `Modal` escapes the container and takes
+ * the window, which inside a drawer covers the register behind it.
+ *
+ * ```tsx
+ * const nav = useSectionNav(["general", "fees"] as const);
+ * const [w, setW] = useState<number | null>(null);
+ * <View onLayout={(e) => setW(e.nativeEvent.layout.width)}>
+ *   <SectionNav
+ *     items={SECTIONS}
+ *     activeKey={nav.activeKey}
+ *     onJump={nav.jumpTo}
+ *     wide={w != null && w >= MY_THRESHOLD}
+ *     back={<BackButton label="Records" onPress={close} />}
+ *   />
+ * ```
+ *
+ * What this does NOT own, and must not grow: the gutter the rail floats in, the
+ * width threshold, and which sections are in trouble. Those read the caller's
+ * layout and the caller's domain — one consumer cannot tell them apart from the
+ * contract, and lifting them along is how a component starts describing one
+ * screen instead of a shape.
+ */
+export function SectionNav<K extends string = string>(props: SectionNavProps<K>) {
+  const { items, activeKey, onJump, wide, back, railWidth = 208, barGutter = 28 } = props;
+  const [open, setOpen] = useState(false);
+  const anchor = useRef<View>(null);
+  const words = useLoticsLocale().sectionNav;
+
+  // A bare dot announces nothing, and here it is the ONLY thing saying a
+  // section needs looking at — so it carries the word a sighted reader infers
+  // from its colour.
+  const dot = (issue: SectionNavItem<K>["issue"]) =>
+    issue ? (
+      <View accessibilityLabel={issue === "danger" ? words.hasProblem : words.needsAttention}>
+        <Badge variant="dot" color={issue === "danger" ? "red" : "amber"} />
+      </View>
+    ) : undefined;
+
+  const rows = (onPick: (key: K) => void) => (
+    <View style={{ gap: 2 }}>
+      {items.map((s) => (
+        <MenuButton
+          key={s.key}
+          icon={s.icon}
+          title={s.label}
+          current={activeKey === s.key}
+          right={dot(s.issue)}
+          onPress={() => onPick(s.key)}
+        />
+      ))}
+    </View>
+  );
+
+  if (wide) {
+    return (
+      <View style={{ width: railWidth, gap: 10 }}>
+        {back}
+        {rows(onJump)}
+      </View>
+    );
+  }
+
+  const current = items.find((s) => s.key === activeKey);
+
+  return (
+    <View
+      style={{
+        borderBottomWidth: 1,
+        borderBottomColor: colors.zinc[200],
+        paddingHorizontal: Math.max(0, barGutter - 10),
+        paddingVertical: 6,
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 8,
+      }}
+    >
+      {back}
+      <Popover open={open} onOpenChange={setOpen} triggerRef={anchor} side="bottom" align="start">
+        <View ref={anchor}>
+          {/* MUTED, not `secondary`: this names WHERE YOU ARE, so it is a
+              position readout that happens to be pressable, and a filled chip
+              competes with the record's own actions for the eye. */}
+          <Button title={current?.label ?? words.sections} color="muted" onPress={() => setOpen(true)} />
+        </View>
+        <PopoverContent style={{ width: 248 }} disableBodyScroll>
+          {rows((key) => {
+            setOpen(false);
+            onJump(key);
+          })}
+        </PopoverContent>
+      </Popover>
+    </View>
+  );
+}

package/src/state_matrix.tsx

@@ -0,0 +1,265 @@
+import { type ReactNode, useState } from "react";
+import { ScrollView, StyleSheet, View } from "react-native";
+import { LEADING_GAP } from "./cell_stack";
+import { colors, solid, type ColorName } from "./colors";
+import { FocusRingPressable } from "./focus_ring_pressable";
+import { useLoticsLocale } from "./locale";
+import { Text } from "./text";
+
+/** The glyph's geometry. The legend draws the same one, so a cell and its
+ *  legend entry can never disagree. */
+export type StateMatrixShape = "filled" | "hollow" | "dot" | "none";
+
+export interface StateMatrixState {
+  key: string;
+  label: string;
+  /** Palette family — the glyph and the legend swatch derive from it. */
+  color: ColorName;
+  /** Default `filled`. `none` keeps the box and draws nothing — "nothing was
+   *  due here", as distinct from a state worth a glyph. */
+  shape?: StateMatrixShape;
+}
+
+export interface StateMatrixColumn {
+  key: string;
+  /** One or two characters — a day number, an hour. Shown ONCE in the header. */
+  label: string;
+  /** A second header line — the weekday under the day number. */
+  caption?: string;
+  /** The column the reader is standing in. Tinted down the grid, `aria-current`. */
+  current?: boolean;
+}
+
+export interface StateMatrixCell {
+  state: string;
+  /** Replaces the glyph — a count, when one cell holds several. */
+  value?: ReactNode;
+  /** Only a pressable cell is a `button`; the rest announce as marks. */
+  pressable?: boolean;
+  /** What a screen reader says — the row, the column and the state, in words. */
+  name: string;
+}
+
+export interface StateMatrixRow {
+  key: string;
+  label: ReactNode;
+  /** An identity mark before the label. */
+  leading?: ReactNode;
+  /** A pinned figure beside the label — "9/14". */
+  total?: string;
+  /** One per column, in column order. */
+  cells: StateMatrixCell[];
+}
+
+export interface StateMatrixLabels {
+  /** Header of the pinned total column. */
+  total: string;
+}
+
+export interface StateMatrixProps {
+  columns: StateMatrixColumn[];
+  rows: StateMatrixRow[];
+  states: StateMatrixState[];
+  onPressCell?: (rowKey: string, colKey: string) => void;
+  /** Width of the pinned label block. Default 180. */
+  rowLabelWidth?: number;
+  /** Cell edge. Default 28 — thirty-one of them fit a 1024px pane beside the labels. */
+  cellWidth?: number;
+  labels?: Partial<StateMatrixLabels>;
+  testID?: string;
+}
+
+const ROW_HEIGHT = 36;
+const HEADER_HEIGHT = 40;
+const CELL_GAP = 2;
+const TOTAL_WIDTH = 64;
+const MARK = 12;
+
+/**
+ * A CATEGORICAL cross-tab: rows of subjects, a fixed axis of positions across
+ * the top, and in every cell a STATE drawn as a glyph — an attendance sheet,
+ * a fleet's month day by day, a rota. The reader runs an eye down one column
+ * to see who was out on the 14th, or along one row to see a subject's month.
+ *
+ * It is not `Matrix`: nothing here is a number, and a blank cell means
+ * "nothing was due", never zero. It is not `StatusGrid`: that is a pile of
+ * units with no axes. It is not `Timetable`: a timetable's positions are a
+ * pattern with no dates and every mark is its own editor; here the columns are
+ * dated and a cell is read, and opened when it has something to say.
+ *
+ * What the component owns, and why it is not a `View` of `View`s: the label
+ * block is PINNED outside the scroller so the row keeps its name however far
+ * the axis scrolls; the scroll is the grid's own, never the page's; the legend
+ * derives from `states`, so it cannot list a glyph the cells do not draw; the
+ * current column carries `aria-current` and a tint down its whole height; and
+ * every cell has a NAME, because a glyph announces as nothing.
+ */
+export function StateMatrix(props: StateMatrixProps) {
+  const { columns, rows, states, onPressCell, rowLabelWidth = 180, cellWidth = 28, labels, testID } = props;
+  const l = { ...useLoticsLocale().stateMatrix, ...labels };
+  const hasTotal = rows.some((r) => r.total !== undefined);
+  const stateOf = (key: string) => states.find((s) => s.key === key);
+
+  return (
+    <View style={styles.root} testID={testID}>
+      <View style={styles.body}>
+        {/* Pinned: the row's name and its figure stay put while the axis scrolls. */}
+        <View style={{ width: rowLabelWidth + (hasTotal ? TOTAL_WIDTH : 0) }}>
+          <View style={[styles.headRow, { height: HEADER_HEIGHT }]}>
+            <View style={{ flex: 1 }} />
+            {hasTotal ? (
+              <Text size="sm" weight="medium" color="muted" align="right" numberOfLines={1} style={{ width: TOTAL_WIDTH }}>
+                {l.total}
+              </Text>
+            ) : null}
+          </View>
+          {rows.map((r) => (
+            <View key={r.key} style={[styles.labelRow, { height: ROW_HEIGHT }]}>
+              {r.leading}
+              <View style={{ flex: 1, minWidth: 0 }}>
+                {typeof r.label === "string" ? (
+                  <Text size="sm" weight="medium" numberOfLines={1}>
+                    {r.label}
+                  </Text>
+                ) : (
+                  r.label
+                )}
+              </View>
+              {hasTotal ? (
+                <Text size="sm" tabular align="right" numberOfLines={1} style={{ width: TOTAL_WIDTH }}>
+                  {r.total ?? ""}
+                </Text>
+              ) : null}
+            </View>
+          ))}
+        </View>
+
+        <ScrollView horizontal style={{ flex: 1 }} contentContainerStyle={styles.scrollContent}>
+          <View>
+            <View style={[styles.axis, { height: HEADER_HEIGHT }]}>
+              {columns.map((c) => (
+                <View
+                  key={c.key}
+                  aria-current={c.current ? "date" : undefined}
+                  style={[styles.axisCell, { width: cellWidth }, c.current ? styles.currentWash : null]}
+                >
+                  <Text size="sm" weight="medium" color={c.current ? "default" : "muted"} tabular numberOfLines={1}>
+                    {c.label}
+                  </Text>
+                  {c.caption !== undefined ? (
+                    <Text size="xs" color="muted" numberOfLines={1}>
+                      {c.caption}
+                    </Text>
+                  ) : null}
+                </View>
+              ))}
+            </View>
+            {rows.map((r) => (
+              <View key={r.key} style={[styles.cellRow, { height: ROW_HEIGHT }]}>
+                {columns.map((c, i) => {
+                  const cell = r.cells[i];
+                  if (cell === undefined) return <View key={c.key} style={{ width: cellWidth }} />;
+                  const state = stateOf(cell.state);
+                  return (
+                    <Cell
+                      key={c.key}
+                      cell={cell}
+                      width={cellWidth}
+                      current={c.current === true}
+                      color={state?.color ?? "zinc"}
+                      shape={state?.shape ?? "filled"}
+                      onPress={cell.pressable && onPressCell ? () => onPressCell(r.key, c.key) : undefined}
+                    />
+                  );
+                })}
+              </View>
+            ))}
+          </View>
+        </ScrollView>
+      </View>
+
+      <View style={styles.legend}>
+        {states.map((s) => {
+          const count = rows.reduce((n, r) => n + r.cells.filter((c) => c.state === s.key).length, 0);
+          return (
+            <View key={s.key} style={styles.legendItem}>
+              <Mark color={s.color} shape={s.shape ?? "filled"} />
+              <Text size="xs">{s.label}</Text>
+              <Text size="xs" color="muted" tabular>
+                {String(count)}
+              </Text>
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+interface CellProps {
+  cell: StateMatrixCell;
+  width: number;
+  current: boolean;
+  color: ColorName;
+  shape: StateMatrixShape;
+  onPress?: () => void;
+}
+
+function Cell({ cell, width, current, color, shape, onPress }: CellProps) {
+  const [hovered, setHovered] = useState(false);
+  const inner = cell.value !== undefined ? (
+    <Text size="xs" weight="medium" tabular>
+      {cell.value}
+    </Text>
+  ) : (
+    <Mark color={color} shape={shape} />
+  );
+  const wash = current ? styles.currentWash : null;
+  if (onPress === undefined) {
+    return (
+      <View accessibilityRole="image" accessibilityLabel={cell.name} style={[styles.cell, { width }, wash]}>
+        {inner}
+      </View>
+    );
+  }
+  return (
+    <FocusRingPressable
+      accessibilityRole="button"
+      accessibilityLabel={cell.name}
+      onPress={onPress}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      style={[styles.cell, { width }, wash, hovered ? styles.cellHover : null]}
+    >
+      {inner}
+    </FocusRingPressable>
+  );
+}
+
+/** One glyph, drawn the same in a cell and in the legend. */
+function Mark({ color, shape }: { color: ColorName; shape: StateMatrixShape }) {
+  if (shape === "none") return <View style={styles.mark} />;
+  if (shape === "dot") return <View style={[styles.mark, styles.markDotBox]}><View style={[styles.dot, { backgroundColor: solid(color) }]} /></View>;
+  if (shape === "hollow") return <View style={[styles.mark, styles.markHollow, { borderColor: solid(color) }]} />;
+  return <View style={[styles.mark, { backgroundColor: solid(color) }]} />;
+}
+
+const styles = StyleSheet.create({
+  root: { gap: 12 },
+  body: { flexDirection: "row" },
+  headRow: { flexDirection: "row", alignItems: "flex-end", paddingBottom: 6 },
+  labelRow: { flexDirection: "row", alignItems: "center", gap: LEADING_GAP, paddingRight: 8 },
+  scrollContent: { flexGrow: 1 },
+  axis: { flexDirection: "row", gap: CELL_GAP, alignItems: "flex-end", paddingBottom: 2 },
+  axisCell: { alignItems: "center", paddingVertical: 2, borderRadius: 6 },
+  cellRow: { flexDirection: "row", gap: CELL_GAP },
+  cell: { alignItems: "center", justifyContent: "center", borderRadius: 6 },
+  cellHover: { backgroundColor: colors.zinc[200] },
+  currentWash: { backgroundColor: colors.zinc[100] },
+  mark: { width: MARK, height: MARK, borderRadius: 3 },
+  markHollow: { borderWidth: 1.5, backgroundColor: colors.white },
+  markDotBox: { alignItems: "center", justifyContent: "center" },
+  dot: { width: 6, height: 6, borderRadius: 999 },
+  legend: { flexDirection: "row", flexWrap: "wrap", alignItems: "center", columnGap: 14, rowGap: 4 },
+  legendItem: { flexDirection: "row", alignItems: "center", gap: 6, minHeight: 24 },
+});

package/src/table.tsx

@@ -16,9 +16,9 @@ import { colors, solid, type ColorName } from "./colors";
 import { Icon } from "./icon";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { PressableRow } from "./pressable_row";
-import { CONTROL_HEIGHT } from "./control_surface";
+import { CONTROL_HEIGHT, MIN_CONTROL_WIDTH } from "./control_surface";
 import { PressDoor } from "./press_door";
-import { DetailRow } from "./detail_row";
+import { DetailRow, DetailTable } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { COLUMN_GAP, ROW_GUTTER, ROW_HEIGHT, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
 
@@ -40,6 +40,13 @@ export interface TableColumn extends TableFitColumn {
   /** Header label — sentence case, at the BODY size. Omit for a control column.
    *  In stacked mode it renders as the eyebrow over the cell's value. */
   label?: string;
+  /**
+   * A header that is not a WORD — the seven positions a `Timetable` row toggles,
+   * a unit ruler. Rendered in the band in place of `label`; `label` stays the
+   * column's name for the stacked eyebrow and the sort control. Never a way to
+   * restyle a label: a header is chrome, and chrome has one treatment.
+   */
+  header?: ReactNode;
   /** Flex grow when no `width` (default 1). */
   flex?: number;
   align?: "left" | "right";
@@ -81,6 +88,17 @@ interface TableCtx {
 }
 const TableContext = createContext<TableCtx | null>(null);
 
+/**
+ * The label column a STACKED register's field lines take.
+ *
+ * Narrower than `DETAIL_LABEL_WIDTH` (130) because these labels are COLUMN
+ * HEADERS — "Hạn xử lý", "Nhà xe", "Trạng thái" — not field names, and they are
+ * competing for a phone's width with the value beside them. It is one number for
+ * the surface, which is the whole point: the labels wrap inside it rather than
+ * any one of them pushing its own value out of line with the row above.
+ */
+const STACKED_LABEL_WIDTH = 104;
+
 /**
  * The STT gutter — wide enough for four digits at `xs`, which is every register
  * anyone scrolls. Fixed rather than measured: a width that grew with the number
@@ -288,7 +306,9 @@ export function Table(props: TableProps) {
             <LeadGutter ordinal={count}>{selectAll}</LeadGutter>
             {visibleColumns.map((col) => (
               <View key={col.key} style={colStyle(col)}>
-                {col.label ? (
+                {col.header != null ? (
+                  col.header
+                ) : col.label ? (
                   col.sortable && onSort ? (
                     <SortHeader label={col.label} sortKey={col.key} sort={sort ?? null} onSort={onSort} align={col.align} labels={sortLabels} />
                   ) : (
@@ -643,13 +663,37 @@ export function TableRow(props: TableRowProps) {
       {cells.length > 1 ? (
         // The field lines sit on the identity column's text edge — indented
         // past the leading gutter, never wrapping under the checkbox.
+        //
+        // WRAPPED IN A `DetailTable`, which is what gives them the FORM grammar:
+        // one label column, every value on one left edge. Without it each cell's
+        // `DetailRow` fell back to SPREAD — the label takes the slack and the
+        // value is pushed right — and a spread row is right for ONE detail value
+        // and wrong for a register of them. Repeated down twenty-one rows, the
+        // same label string measured seven distinct widths and its value started
+        // at a different x on every row, so the narrow fork had no value column
+        // at all. The `DetailTable` also carries its own floor: below it the rows
+        // stack label-over-value, which is still ONE left edge.
         <View
           style={[
             styles.stackedFields,
             ctx.leading + ctx.ordinal > 0 ? { paddingLeft: ctx.leading + ctx.ordinal + COLUMN_GAP } : null,
           ]}
         >
-          {cells.slice(1)}
+          {/* `MIN_CONTROL_WIDTH`, not the record's `MIN_VALUE_WIDTH`. The two
+              answer different questions and a register's cells are the other
+              case: they hold a badge, a date, a short kind or a control, not the
+              company names and addresses a record's value column carries. Left
+              at 200 the grid stacked label-OVER-value at 375, turning every row
+              into four lines and a twenty-one-row queue into a scroll marathon
+              — correct alignment, wrong density. */}
+          <DetailTable
+            labelWidth={STACKED_LABEL_WIDTH}
+            minValueWidth={MIN_CONTROL_WIDTH}
+            minHeight={0}
+            style={styles.stackedFieldGrid}
+          >
+            {cells.slice(1)}
+          </DetailTable>
         </View>
       ) : null}
       {action != null ? <View style={styles.stackedActionLine}>{action}</View> : null}
@@ -665,7 +709,7 @@ export function TableRow(props: TableRowProps) {
       return <View style={styles.staticStackedRow}>{body}</View>;
     }
     return (
-      <View style={[styles.staticRow, vAlign]}>
+      <View style={topAligned ? [styles.staticRow, { alignItems: "flex-start" as const }] : styles.staticRow}>
         <LeadGutter ordinal={ordinal}>{leading}</LeadGutter>
         <View style={cellsStyle}>{cells}</View>
         {ctx.trailing > 0 ? (
@@ -752,6 +796,18 @@ export function TableCell(props: TableCellProps) {
     if (_primary) {
       return <>{children}</>;
     }
+    // A column whose header is a set of POSITIONS keeps them over its value
+    // when the register stacks: the marks under it are unreadable otherwise.
+    if (_column?.header != null) {
+      return (
+        <View style={styles.stackedBareCell}>
+          <View style={{ gap: 4 }}>
+            {_column.header}
+            {children}
+          </View>
+        </View>
+      );
+    }
     if (!_column?.label) {
       return <View style={styles.stackedBareCell}>{children}</View>;
     }
@@ -903,6 +959,12 @@ const styles = StyleSheet.create({
   stackedFields: {
     gap: 8,
   },
+  // The field grid inside a stacked row. `DetailTable` owns the label column and
+  // the row gap; this only removes the gap it would add on top of
+  // `stackedFields`' own, so the two are not paid twice.
+  stackedFieldGrid: {
+    gap: 8,
+  },
   // The register's trailing gutter composes [action, overflow] on one row —
   // the gap matches the composite the templates previously hand-rolled.
   trailingSlot: {