@lotics/ui 27.17.1 → 28.1.0

package/src/stepper.tsx

@@ -16,8 +16,9 @@ import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { AnimationFadeIn } from "./animation_fade_in";
 import { CheckCircle } from "./check_circle";
+import { CheckboxInput } from "./checkbox_input";
 import { useLoticsLocale } from "./locale";
-import { NODE, STEP_HEAD_TEXT_LINE, STEP_ROW_PAD, markerTopOffset } from "./stepper_layout";
+import { NODE, STEP_HEAD_TEXT_LINE, STEP_MARKER_GAP, STEP_ROW_INSET, STEP_ROW_PAD, STEP_TEXT_COLUMN, markerTopOffset } from "./stepper_layout";
 
 // A node's place in a sequence. `upcoming` = not reached (greyish); `current` =
 // where we are (ring + white centre, pulses when live); `done` = passed (filled);
@@ -28,14 +29,25 @@ export type StepOrientation = "horizontal" | "vertical";
 
 const reached = (s: StepStatus) => s !== "upcoming";
 
+export { STEP_TEXT_COLUMN };
+
+
 interface StepperConfig {
   orientation: StepOrientation;
   color: string;
+  /** What a toggleable marker MEANS — see `StepperProps.mark`. */
+  mark: "ring" | "box";
+  /** Vertical spacing beneath each step; undefined = the default group rhythm. */
+  gap?: number;
+  /** Draw the connecting line between markers. Off for a run whose rows are
+   *  independent, where a line would claim an order the work does not have. */
+  connected: boolean;
   /** Pulse the current node — signals an actively-running sequence (an agent
    *  run streaming its steps). Off for a static wizard/checklist. */
   live: boolean;
 }
-const StepperContext = createContext<StepperConfig>({ orientation: "horizontal", color: colors.zinc[900], live: false });
+const StepperContext = createContext<StepperConfig>({ orientation: "horizontal", color: colors.zinc[900], live: false, connected: true, mark: "ring" });
+
 
 export interface StepperProps {
   /** Compound form: `<Stepper><Step status>…</Step></Stepper>` — swappable content. */
@@ -47,11 +59,39 @@ export interface StepperProps {
   live?: boolean;
   /** Accent ink for reached nodes + the connecting track. Defaults to neutral ink. */
   color?: string;
+  /**
+   * VERTICAL only. Space beneath each step. The default separates GROUPS — stages
+   * that each carry a body — and is too much for a run of bare rows: the spine
+   * between two one-line steps stretches until it reads as a dash rather than a
+   * line. A run of plain rows passes a tighter number.
+   */
+  gap?: number;
+  /**
+   * What a toggleable marker MEANS, and therefore its SHAPE.
+   *
+   * `ring` (default) is COMPLETION — the row is a thing someone finishes.
+   * `box` is SELECTION — the row is a thing someone PICKS, and finishing never
+   * enters into it (which forms to produce, which records to export).
+   *
+   * The two are 24px either way and share one gutter, so a surface swaps between
+   * them without moving anything. Spending the ring on selection is the failure
+   * this exists to prevent: a reader who has learned that a filled ring means
+   * "done" reads a ticked pick-list as work already carried out.
+   */
+  mark?: "ring" | "box";
+  /**
+   * VERTICAL only. Draw the connecting line between markers (default on).
+   *
+   * The line asserts SEQUENCE. On a set of independent items it claims an order
+   * the work does not have, and the reader infers a first and a next that are not
+   * there.
+   */
+  connected?: boolean;
   accessibilityLabel?: string;
 }
 
 /** The props `Stepper` CLONES onto its direct children. Exported so a component
- *  that stands where a `Step` would (`PipelineStage`) can accept and forward the
+ *  that stands where a `Step` would (a `ChecklistItem`) can accept and forward the
  *  whole set — extend this and spread it through, never re-list the keys, or a
  *  new positional prop is dropped silently by everything but `Step`. */
 export interface StepPositional {
@@ -93,6 +133,18 @@ export interface StepProps extends StepPositional {
    * difference. Ignored horizontally, where the marker sits above the label.
    */
   headHeight?: number;
+  /**
+   * VERTICAL only. Drop the marker COLUMN — no node, no spine, content flush to
+   * the run's left edge.
+   *
+   * For a step that GROUPS others rather than being one. A grouping row has no
+   * completion of its own, so any node it wore would be a control that reports
+   * without responding — and a ring identical to the pressable ones below it
+   * reads as pressable, which is a worse failure than showing nothing: the reader
+   * clicks and the product says nothing back. Its children carry the markers, and
+   * the group is a heading over them.
+   */
+  marker?: boolean;
   accessibilityLabel?: string;
 }
 
@@ -107,7 +159,7 @@ export interface StepProps extends StepPositional {
  * for a compact stage bar use `StepProgress`.
  */
 export function Stepper(props: StepperProps) {
-  const { children, steps, current, orientation = "horizontal", live = false, color = colors.zinc[700], accessibilityLabel } = props;
+  const { children, steps, current, orientation = "horizontal", live = false, color = colors.zinc[700], gap, connected = true, mark = "ring", accessibilityLabel } = props;
   const locale = useLoticsLocale();
 
   const content: ReactNode =
@@ -135,17 +187,24 @@ export function Stepper(props: StepperProps) {
   // accessibility tree. A discrete named sequence is a list whose live entry
   // carries `aria-current="step"`. The proportional bar is `StepProgress`.
 
+  // A row is visually LAST when nothing below it carries a marker to connect to —
+  // the end of the run, or the row before a GROUP heading. Without this the final
+  // row of every phase drew a spine down into the heading's empty column and the
+  // line dangled into blank space, which reads as a rendering fault.
+  const breaksAfter = (i: number) =>
+    i === last || (items[i + 1]?.type as { markerless?: boolean } | undefined)?.markerless === true;
+
   const positioned = items.map((child, i) =>
     cloneElement(child, {
       _first: i === 0,
-      _last: i === last,
+      _last: breaksAfter(i),
       _leftFilled: i > 0 && reached(statuses[i - 1]),
       _rightFilled: i < last && reached(statuses[i]),
     }),
   );
 
   return (
-    <StepperContext.Provider value={{ orientation, color, live }}>
+    <StepperContext.Provider value={{ orientation, color, live, gap, connected, mark }}>
       <View role="list" accessibilityLabel={a11y} style={orientation === "horizontal" ? styles.hRow : undefined}>
         {positioned}
       </View>
@@ -154,8 +213,8 @@ export function Stepper(props: StepperProps) {
 }
 
 export function Step(props: StepProps) {
-  const { status, children, onPress, active, onToggle, headHeight = STEP_HEAD_TEXT_LINE, accessibilityLabel, _first, _last, _leftFilled, _rightFilled } = props;
-  const { orientation, color, live } = useContext(StepperContext);
+  const { status, children, onPress, active, onToggle, headHeight = STEP_HEAD_TEXT_LINE, marker = true, accessibilityLabel, _first, _last, _leftFilled, _rightFilled } = props;
+  const { orientation, color, live, gap, connected, mark } = useContext(StepperContext);
   const locale = useLoticsLocale();
   // Each step is one `listitem`, and the live one says so with `aria-current`.
   // It goes on the ITEM, not the label: "current" is a fact about this position
@@ -194,7 +253,14 @@ export function Step(props: StepProps) {
     return <View {...item} style={styles.hStep}>{inner}</View>;
   }
 
-  const body = <View style={[styles.vRowBox, active ? styles.vActive : null]}>{children}</View>;
+  // The row box's horizontal inset exists for the hover/active WASH, so a
+  // markerless row — a group heading, which shows no wash — pays nothing for it.
+  // Left in, it pushed the heading AND the run nested under it 10px off the
+  // section's own left edge: near enough to read as a mistake, and the kind that
+  // is invisible until something above it is aligned properly.
+  const body = (
+    <View style={[styles.vRowBox, !marker ? styles.vRowFlush : null, active ? styles.vActive : null]}>{children}</View>
+  );
   // Each step rises + fades into place on mount — so a streamed feed reads as
   // steps APPEARING, not popping in. Animates once (on mount); a status change
   // (current → done) re-renders without re-animating.
@@ -205,6 +271,12 @@ export function Step(props: StepProps) {
     <View {...item}>
       <AnimationFadeIn translateY={6}>
         <View style={styles.vItem}>
+          {/* MARKERLESS: no column at all. A group heading owns no completion, so
+              it wears no node — and no line either: a spine drawn THROUGH the row
+              runs straight into the ring below it and reads as a rendering fault
+              rather than a connection. The heading sits flush on the run's left
+              edge, where its steps' rings are, so the column still reads as one. */}
+          {marker ? (
           <View style={styles.vSpineCol}>
             {/* The spine is TWO segments per step, above the marker and below it,
                 because the marker does not sit at the top of its row: it centres
@@ -222,11 +294,22 @@ export function Step(props: StepProps) {
                 styles.vSpineUp,
                 { height: markerTopOffset(headHeight) },
                 // The first step has nothing above it to connect to, so its band
-                // is spacing, not line.
-                _first ? null : { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] },
+                // is spacing, not line — and neither does any step when the run is
+                // unconnected, where a stub above each ring is the line's leftovers.
+                _first || !connected ? null : { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] },
               ]}
             />
-            {onToggle ? (
+            {onToggle && mark === "box" ? (
+              // SELECTION: the square, in the ring's own box so the column and the
+              // spine keep their rhythm whichever mark a surface uses.
+              <View style={{ width: NODE, height: NODE, alignItems: "center", justifyContent: "center" }}>
+                <CheckboxInput
+                  checked={status === "done" || status === "complete"}
+                  onChange={onToggle}
+                  accessibilityLabel={accessibilityLabel ?? locale.stepper.complete}
+                />
+              </View>
+            ) : onToggle ? (
               // Sized to NODE so a toggleable step keeps the spine's rhythm — a
               // ring a couple of pixels wider would bow the column at that row.
               <CheckCircle
@@ -247,9 +330,10 @@ export function Step(props: StepProps) {
             ) : (
               <Marker status={status} color={color} live={live} />
             )}
-            {!_last ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
+            {!_last && connected ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
           </View>
-          <View style={[styles.vContent, !_last ? styles.vGap : null]}>
+          ) : null}
+          <View style={[styles.vContent, !_last ? (gap != null ? { paddingBottom: gap } : styles.vGap) : null]}>
             {onPress ? (
               <PressableHighlight focusRing onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.vPress}>
                 {body}
@@ -326,7 +410,7 @@ const styles = StyleSheet.create({
   hTrack: { flex: 1, height: 2 },
   hLabel: { alignItems: "center" },
 
-  vItem: { flexDirection: "row", gap: 12 },
+  vItem: { flexDirection: "row", gap: STEP_MARKER_GAP },
   vSpineCol: { width: NODE, alignItems: "center" },
   // No top margin: the segment starts AT the marker, or the line detaches from
   // the node it is supposed to leave.
@@ -335,9 +419,14 @@ const styles = StyleSheet.create({
   // read as one line through the node.
   vSpineUp: { width: 1.5 },
   vContent: { flex: 1 },
-  vGap: { paddingBottom: 12 },
-  vPress: { borderRadius: 8, marginHorizontal: -10 },
-  vRowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: STEP_ROW_PAD },
+  // The gap BETWEEN steps of a vertical run. It has to beat the spacing INSIDE a
+  // step, or a stage's own children spread wider than the distance to the next
+  // stage and the groups stop reading as groups — a three-step phase spending 4px
+  // per child needs more than 12 beneath it to look like one thing.
+  vGap: { paddingBottom: 18 },
+  vPress: { borderRadius: 8, marginHorizontal: -STEP_ROW_INSET },
+  vRowBox: { borderRadius: 8, paddingHorizontal: STEP_ROW_INSET, paddingVertical: STEP_ROW_PAD },
+  vRowFlush: { paddingHorizontal: 0 },
   vActive: { backgroundColor: colors.zinc[100] },
 
   discWrap: { width: NODE, height: NODE, alignItems: "center", justifyContent: "center" },

package/src/stepper_layout.ts

@@ -22,7 +22,7 @@
  * size makes the geometry follow the control instead of the other way round.
  *
  * 24 is that size, and it is `Checkbox`'s box as well: a ring and a box are two
- * forms of one act, they share the leading gutter on `Table` and `TaskList`, and
+ * forms of one act, they share the leading gutter on `Table` and `Checklist`, and
  * a gutter whose width depended on which one a surface hosted is a difference no
  * reader could name either.
  *
@@ -34,6 +34,26 @@ export const NODE = 24;
 /** `vRowBox`'s vertical padding — the gap above the content's first row. */
 export const STEP_ROW_PAD = 2;
 
+/**
+ * The gap between a vertical step's marker column and its content.
+ *
+ * Read it with `STEP_ROW_INSET`, which follows it: the two together are what a
+ * reader sees between a ring and the words it belongs to. At 12 + 10 that came to
+ * 22px, which on a checklist row reads as a ring floating away from its label
+ * rather than marking it.
+ */
+export const STEP_MARKER_GAP = 6;
+/** The horizontal inset inside a step's row box (its hover/active wash). */
+export const STEP_ROW_INSET = 10;
+/**
+ * Where a vertical step's TEXT actually begins, from the run's left edge.
+ *
+ * The marker, the gap after it, AND the row box's own inset — all three, because
+ * leaving the last one out puts a heading meant to share that edge 10px off it,
+ * which is precisely near enough to look like a mistake rather than a margin.
+ */
+export const STEP_TEXT_COLUMN = NODE + STEP_MARKER_GAP + STEP_ROW_INSET;
+
 /**
  * A single line of `Text size="sm"` on web (`text.css`), which is what a step's
  * first row is unless it carries a control. NOT the native StyleSheet's 24: the

package/src/table.tsx

@@ -38,12 +38,55 @@ export interface TableColumn extends TableFitColumn {
 interface TableCtx {
   columns: TableColumn[];
   leading: number;
+  /** Width of the ordinal gutter, 0 when the register is not counted. */
+  ordinal: number;
   trailing: number;
   visibleKeys: ReadonlySet<string>;
   stacked: boolean;
 }
 const TableContext = createContext<TableCtx | null>(null);
 
+/**
+ * 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
+ * would step the whole column band left as the reader paged from 99 to 100.
+ */
+const ORDINAL_W = 28;
+
+/**
+ * The row's left chrome: its number, then whatever the caller put in `leading`.
+ *
+ * ONE component for what was the same two lines repeated at five render sites
+ * (two header modes, the static row, the pressable row, the stacked top line).
+ * The ordinal had to reach all five, and five copies is five chances for one of
+ * them to keep the old width and put the column band 28px out of true on exactly
+ * one surface.
+ */
+function LeadGutter({ ordinal, children }: { ordinal?: number; children?: ReactNode }) {
+  const ctx = useContext(TableContext);
+  // THROWS, like `TableRow` does. Returning null here would take the row's
+  // selection checkbox and its number with it and say nothing — the gutter would
+  // simply not be there, which is the failure mode a reader cannot report.
+  if (!ctx) throw new Error("LeadGutter must be used within a Table");
+  return (
+    <>
+      {ctx.ordinal > 0 ? (
+        <View style={[styles.ordinal, { width: ctx.ordinal }]}>
+          {ordinal != null ? (
+            // Muted and small: it orients, it is not data. A row that has no
+            // number (a group band) leaves the box empty rather than collapsing
+            // it, or its cells would sit 28px left of every other row's.
+            <Text size="xs" color="muted" numberOfLines={1}>
+              {ordinal}
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
+      {ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{children}</View> : null}
+    </>
+  );
+}
+
 function colStyle(col: TableColumn): ViewStyle {
   const base: ViewStyle =
     col.width != null ? { width: col.width } : { flex: col.flex ?? 1, minWidth: 0 };
@@ -64,6 +107,20 @@ export interface TableProps {
   selectAll?: ReactNode;
   /** Reserve a leading gutter (px) for rows that render a `leading` slot (a checkbox). */
   leading?: number;
+  /**
+   * Turn the register into a COUNTED one: every row shows its position in a
+   * narrow gutter left of `leading`, and this number — the total — heads it.
+   *
+   * The total is yours to pass because it is rarely the child count: a paged
+   * register renders fifty of it, a filtered one counts what matched, and a
+   * grouped one counts across bands the reader can collapse. The kit would have
+   * to guess which, and would guess wrong on every register that paginates.
+   *
+   * Positions are yours for the same reason — see `TableRowProps.ordinal`. This
+   * prop only says "this register is counted", which is what reserves the gutter
+   * on the header and on every row at once, so they cannot disagree.
+   */
+  count?: number;
   /** Reserve a trailing gutter (px) for rows that render a `trailing` slot (a ⋯ / button). */
   trailing?: number;
   /** The `TableRow`s. */
@@ -85,7 +142,8 @@ export interface TableProps {
  * keeps its current order). See `computeTableFit`.
  */
 export function Table(props: TableProps) {
-  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, trailing = 0, children } = props;
+  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, trailing = 0, children } = props;
+  const ordinal = count != null ? ORDINAL_W : 0;
   const rows = Children.toArray(children).filter(isValidElement);
 
   // Measure-then-REVEAL (the `DetailTable` contract): the unmeasured first
@@ -95,11 +153,14 @@ export function Table(props: TableProps) {
   const fit: TableFit =
     width == null
       ? { visibleKeys: new Set(columns.map((c) => c.key)), stacked: false }
-      : computeTableFit(columns, leading, trailing, width);
+      // The ordinal gutter is reserved space like any other chrome, so the fit
+      // sees it: a counted register that ignored it would keep a column it can
+      // no longer fit and push the last one off the edge.
+      : computeTableFit(columns, leading + ordinal, trailing, width);
   const visibleColumns = columns.filter((c) => fit.visibleKeys.has(c.key));
 
   return (
-    <TableContext.Provider value={{ columns, leading, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
+    <TableContext.Provider value={{ columns, leading, ordinal, 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. */}
@@ -111,14 +172,16 @@ export function Table(props: TableProps) {
           // 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 ? (
+          (selectAll != null && leading > 0) || ordinal > 0 ? (
             <View style={styles.headerBand}>
-              <View style={{ width: leading }}>{selectAll}</View>
+              <LeadGutter ordinal={count}>{selectAll}</LeadGutter>
             </View>
           ) : null
         ) : (
           <View style={styles.headerBand}>
-            {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
+            {/* The TOTAL heads the column of positions — the one number that
+                answers "how many" without the reader scrolling to the last row. */}
+            <LeadGutter ordinal={count}>{selectAll}</LeadGutter>
             {visibleColumns.map((col) => (
               <View key={col.key} style={colStyle(col)}>
                 {col.label ? (
@@ -154,6 +217,21 @@ export type TableRowProps = {
   marked?: boolean;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
   leading?: ReactNode;
+  /**
+   * This row's POSITION, shown left of `leading` when the Table carries `count`.
+   *
+   * Yours to compute, because only you know what the number means here: a paged
+   * register continues (`offset + i + 1`) rather than restarting at 1, and a
+   * grouped one restarts inside each band, where the reader's question is "which
+   * of these" rather than "which of all". Omit it on a row that has no position —
+   * a group band, a total line — and the gutter stays blank so the cells beside
+   * it stay in line.
+   *
+   * It is a POSITION, never an identity: sort or filter the register and row 12
+   * is a different record. Where a stable handle is wanted, that is a column
+   * (the record's key), and it leads the cells.
+   */
+  ordinal?: number;
   /** 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`). */
@@ -219,7 +297,7 @@ export type TableRowProps = {
  * slots, different geometry.
  */
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, trailing, action, minHeight = 52, detail, expanded, children } = props;
+  const { onPress, selected, marked, accessibilityLabel, leading, ordinal, trailing, action, minHeight = 52, detail, expanded, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
   const showDetail = detail != null && expanded === true;
@@ -237,14 +315,19 @@ export function TableRow(props: TableRowProps) {
   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}
+        <LeadGutter ordinal={ordinal}>{leading}</LeadGutter>
         <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]}>
+        <View
+          style={[
+            styles.stackedFields,
+            ctx.leading + ctx.ordinal > 0 ? { paddingLeft: ctx.leading + ctx.ordinal + COLUMN_GAP } : null,
+          ]}
+        >
           {cells.slice(1)}
         </View>
       ) : null}
@@ -262,7 +345,7 @@ export function TableRow(props: TableRowProps) {
     }
     return (
       <View style={styles.staticRow}>
-        {ctx.leading > 0 ? <View style={{ width: ctx.leading }}>{leading}</View> : null}
+        <LeadGutter ordinal={ordinal}>{leading}</LeadGutter>
         <View style={[styles.cells, { minHeight }]}>{cells}</View>
         {ctx.trailing > 0 ? (
           <View style={[styles.trailingSlot, { width: ctx.trailing }]}>
@@ -276,7 +359,7 @@ export function TableRow(props: TableRowProps) {
 
   const rowSurface = (
     <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked} style={styles.row}>
-      {!ctx.stacked && ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
+      {!ctx.stacked ? <LeadGutter ordinal={ordinal}>{leading}</LeadGutter> : null}
       {/* The door hit-tests above in-flow content; the cells/slots lift back above it
           via zIndex 1 (see `PressDoor`), so the door gets only the keyboard. Radius
           matches the register wash. */}
@@ -417,6 +500,13 @@ const styles = StyleSheet.create({
   slot: {
     zIndex: 1,
   },
+  // RIGHT-aligned so the digits line up against the row's content whatever their
+  // length — 9 and 100 share an edge, which is what makes the column scannable.
+  // No `zIndex`, unlike `slot`: the number is text, not a control, so it belongs
+  // UNDER the press door and the whole row stays one click target.
+  ordinal: {
+    alignItems: "flex-end",
+  },
   // 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.