@lotics/ui 21.0.0 → 21.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "21.0.0",
+  "version": "21.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -204,6 +204,7 @@
     "./card": "./src/card.tsx",
     "./accordion": "./src/accordion.tsx",
     "./stepper": "./src/stepper.tsx",
+    "./pipeline": "./src/pipeline.tsx",
     "./step_progress": "./src/step_progress.tsx",
     "./tabs": "./src/tabs.tsx",
     "./segmented_control": "./src/segmented_control.tsx",

package/src/data_grid.tsx

@@ -11,9 +11,17 @@ export interface DataGridColumn<T> {
   label: string;
   /** Fixed width in px; omit for the flexible primary column (usually the first). */
   width?: number;
+  /** Cell + header alignment. Money and counts read RIGHT so digits line up under
+   *  their heading; text reads left (the default). */
+  align?: "left" | "right";
   sortable?: boolean;
   /** Render the cell for this column — any field: a `Text`, an inline editor, a badge. */
   cell: (item: T) => ReactNode;
+  /** This column's cell in the group's FOOTER row — a subtotal, a resolved measure.
+   *  Declared per COLUMN so the grid lays it out in that column's own box: a total
+   *  can never drift from the values it sums, and no consumer re-implements the row.
+   *  The footer row renders when ANY column defines one. */
+  footer?: (group: DataGridGroup<T>) => ReactNode;
 }
 
 export interface DataGridGroup<T> {
@@ -39,7 +47,9 @@ export interface DataGridProps<T> {
   /** Controlled collapse — the set of collapsed group keys. */
   collapsed?: Set<string>;
   onToggleCollapse?: (key: string) => void;
-  /** Rendered under each group's rows — typically a per-group add row. Align it with `gridRowStyle` + the column widths. */
+  /** Rendered under each group's rows AND under the columns' own footer row —
+   *  for content that does NOT sit in a column, typically a per-group add row.
+   *  For a column-aligned subtotal use `DataGridColumn.footer`. */
   renderGroupFooter?: (group: DataGridGroup<T>) => ReactNode;
 }
 
@@ -57,13 +67,19 @@ export interface DataGridProps<T> {
 export function DataGrid<T>(props: DataGridProps<T>) {
   const { columns, groups, getRowKey, leading, sort, onSort, labels, collapsed, onToggleCollapse, renderGroupFooter } = props;
   const lead = leading?.width ?? 0;
+  const hasFooter = columns.some((c) => c.footer != null);
 
   return (
     <View>
       <View style={[styles.row, styles.head]}>
         {lead > 0 ? <View style={{ width: lead }} /> : null}
+        {/* The header label rides the SAME column box as the cells below it, so a
+            right-aligned column's heading sits over its digits instead of drifting
+            to the column's left edge. */}
         {columns.map((c) => (
-          <SortLabel key={c.key} label={c.label} sortKey={c.key} sortable={c.sortable !== false && !!onSort} sort={sort ?? null} onSort={onSort} labels={labels} style={colStyle(c)} />
+          <View key={c.key} style={colStyle(c)}>
+            <SortLabel label={c.label} sortKey={c.key} sortable={c.sortable !== false && !!onSort} sort={sort ?? null} onSort={onSort} labels={labels} />
+          </View>
         ))}
       </View>
 
@@ -95,6 +111,14 @@ export function DataGrid<T>(props: DataGridProps<T>) {
                     ))}
                   </View>
                 ))}
+                {hasFooter ? (
+                  <View style={styles.row}>
+                    {lead > 0 ? <View style={{ width: lead }} /> : null}
+                    {columns.map((c) => (
+                      <View key={c.key} style={colStyle(c)}>{c.footer?.(g)}</View>
+                    ))}
+                  </View>
+                ) : null}
                 {renderGroupFooter?.(g)}
               </>
             ) : null}
@@ -105,13 +129,20 @@ export function DataGrid<T>(props: DataGridProps<T>) {
   );
 }
 
-function colStyle(c: { width?: number }): StyleProp<ViewStyle> {
-  return c.width != null ? { width: c.width } : styles.flexCol;
+/** The shared column box — width (or flex) plus alignment. ONE definition, used by
+ *  the header, every cell and every footer cell, so the three cannot drift. */
+function colStyleImpl(c: { width?: number; align?: "left" | "right" }): StyleProp<ViewStyle> {
+  return [
+    c.width != null ? { width: c.width } : styles.flexCol,
+    c.align === "right" ? { alignItems: "flex-end" as const } : null,
+  ];
 }
+const colStyle = colStyleImpl;
 
-// The aligned sortable header label — same 8px inset as the cells, so it lines up
-// with the column content (the kit's `SortHeader` keeps its label flush, which
-// wouldn't match inline-editor cells).
+// The column heading. It sits in the SAME column box as the cells, and its own
+// padding is cancelled by an equal negative margin — so the hover pill has room
+// while the label still starts exactly on its cell's edge. Non-sortable headings
+// render as plain text: no press, no pointer, no button in the a11y tree.
 function SortLabel(props: { label: string; sortKey: string; sortable: boolean; sort: SortState | null; onSort?: (k: string) => void; labels?: SortHeaderLabels; style?: StyleProp<ViewStyle> }) {
   const { label, sortKey, sortable, sort, onSort, labels, style } = props;
   const active = sort?.key === sortKey;
@@ -126,7 +157,7 @@ function SortLabel(props: { label: string; sortKey: string; sortable: boolean; s
   const sortByLabel = (labels?.sortBy ?? ((l: string) => `Sort by ${l}`))(label);
   const dirText = active ? (sort?.dir === "asc" ? (labels?.ascending ?? ", ascending") : (labels?.descending ?? ", descending")) : "";
   return (
-    <FocusRingPressable onPress={() => onSort?.(sortKey)} accessibilityRole="button" accessibilityLabel={`${sortByLabel}${dirText}`} style={({ hovered }: { hovered?: boolean }) => [styles.sortLabel, hovered ? styles.sortLabelHover : null, style]}>
+    <FocusRingPressable onPress={() => onSort?.(sortKey)} accessibilityRole="button" accessibilityLabel={`${sortByLabel}${dirText}`} style={({ hovered }: { hovered?: boolean }) => [styles.sortLabel, styles.sortLabelPressable, hovered ? styles.sortLabelHover : null, style]}>
       <Text size="xs" weight="semibold" color={active ? "default" : "muted"} numberOfLines={1} style={styles.headLabel}>{label}</Text>
       {arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
     </FocusRingPressable>
@@ -139,7 +170,6 @@ export const gridRowStyle: ViewStyle = {
   alignItems: "center",
   gap: 12,
   minHeight: 44,
-  paddingHorizontal: 8,
 };
 
 const styles = StyleSheet.create({
@@ -152,9 +182,12 @@ const styles = StyleSheet.create({
     marginBottom: 4,
   },
   headLabel: { letterSpacing: 0.3, textTransform: "uppercase" },
-  sortLabel: { flexDirection: "row", alignItems: "center", gap: 4, paddingHorizontal: 8, paddingVertical: 2, borderRadius: 6, cursor: "pointer" },
+  // Padded for the hover pill but zero-width in flow (negative margin), so the label
+  // sits on its cell's edge instead of 8px inside it.
+  sortLabel: { flexDirection: "row", alignItems: "center", gap: 4, paddingHorizontal: 6, marginHorizontal: -6, paddingVertical: 2, borderRadius: 6 },
+  sortLabelPressable: { cursor: "pointer" },
   sortLabelHover: { backgroundColor: colors.zinc[50] },
   groupSep: { borderTopWidth: 1, borderTopColor: colors.zinc[100], marginTop: 8, paddingTop: 8 },
-  section: { flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 8, paddingVertical: 7, borderRadius: 8 },
+  section: { flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 8, marginHorizontal: -8, paddingVertical: 7, borderRadius: 8 },
   sectionHover: { backgroundColor: colors.zinc[50] },
 });

package/src/ledger.tsx

@@ -77,7 +77,7 @@ export function LedgerGroup(props: LedgerGroupProps) {
   const { format } = useLedger();
   return (
     <View style={styles.group}>
-      <View style={styles.row}>
+      <View style={styles.groupHead}>
         <Text size="xs" weight="medium" color="muted" style={styles.grow}>
           {label}
         </Text>
@@ -198,8 +198,11 @@ const styles = StyleSheet.create({
   // Outdent by the rows' 8px inset (the ListItem/Timeline technique) so row text +
   // the money column align with the section heading and the container edges;
   // the pressable door's wash bleeds into the gutter instead of squeezing text.
-  ledger: { gap: 12, marginHorizontal: -8 },
-  group: { gap: 4 },
+  // Grouping reads by PROXIMITY: the gap between groups must be decisively larger
+  // than the gap inside one, or the eyebrow floats midway and belongs to neither
+  // the group above nor the rows below. 18 between, 2 within.
+  ledger: { gap: 16, marginHorizontal: -8 },
+  group: { gap: 0 },
   // EVERY line (group header, rows, the total) shares the 8px text inset, so
   // labels and the money column sit on one edge whether a row peeks or not —
   // the pressable door's wash simply fills the same padded box.
@@ -210,6 +213,16 @@ const styles = StyleSheet.create({
     minHeight: 28,
     paddingHorizontal: 8,
   },
+  // The group eyebrow is a CAPTION on the rows beneath it, not a line of its own —
+  // it takes only the height its xs text needs, so it hugs what it labels instead
+  // of sitting in a full 28px row box.
+  groupHead: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+    minHeight: 16,
+    paddingHorizontal: 8,
+  },
   rowPress: {
     borderRadius: 8,
   },

package/src/pipeline.tsx

@@ -0,0 +1,156 @@
+import { type ReactNode } from "react";
+import { View } from "react-native";
+import { Text } from "./text";
+import { Stepper, Step, type StepPositional, type StepStatus } from "./stepper";
+
+export interface PipelineProps {
+  children?: ReactNode;
+  /** Accent for reached nodes + the spine. Defaults to `Stepper`'s neutral ink. */
+  color?: string;
+  accessibilityLabel?: string;
+}
+
+/**
+ * A pipeline an item WALKS — ordered milestones where each one carries its own
+ * controls: the fields that milestone owns, the conditions attached to it, and
+ * the one act that leaves it.
+ *
+ * **Pick this over `TaskList` when the rows are STAGES, not work items.** A task
+ * list models N things you tick in any order, each row structurally identical.
+ * A pipeline models ONE thing moving through N positions, where the position
+ * decides what you can see and do — a dossier at "awaiting review" offers approve
+ * and return; the same dossier two stages on offers neither and shows a portal
+ * account instead. Rendering that as a checklist forces every row to carry every
+ * control, and the reader has to scan all of them to find the one that is theirs.
+ *
+ * **And over a bare `Stepper` when the stages need bodies.** `Stepper` renders
+ * position — done, current, upcoming on a spine. This adds the anatomy that turns
+ * position into a workspace: a title that reads by status, a meta line, per-stage
+ * fields, notes and actions.
+ *
+ * The rules the anatomy encodes:
+ * - **Only the current stage should carry an act.** A control on an unreached
+ *   stage invites acting out of order; on a passed one it re-offers something
+ *   already done. The component does not enforce this — the caller decides what
+ *   each stage renders — but the styling assumes it.
+ * - **A condition belongs to its stage.** Something being wrong at stage 2 is a
+ *   fact about stage 2, so `PipelineNote` sits inside it rather than floating
+ *   above the run where it reads as "something is wrong with this record".
+ * - **A passed stage stays correctable.** Whatever a stage owns should remain
+ *   editable behind you, or the only way to fix a mis-entry is direct table
+ *   access.
+ *
+ * ```tsx
+ * <Pipeline>
+ *   <PipelineStage status="done" title="Submitted">
+ *     <PipelineField label="Date"><InlineDatePicker … /></PipelineField>
+ *   </PipelineStage>
+ *   <PipelineStage status="current" title="In review" meta="Waiting 3d · Ops">
+ *     <PipelineNote tone="warning">Sent back — missing payslips.</PipelineNote>
+ *     <PipelineActions>
+ *       <Button title="Approve" color="primary" />
+ *       <Button title="Return" color="danger-secondary" />
+ *     </PipelineActions>
+ *   </PipelineStage>
+ *   <PipelineStage status="upcoming" title="Filed" />
+ * </Pipeline>
+ * ```
+ */
+export function Pipeline({ children, color, accessibilityLabel }: PipelineProps) {
+  return (
+    <Stepper orientation="vertical" color={color} accessibilityLabel={accessibilityLabel}>
+      {children}
+    </Stepper>
+  );
+}
+
+export interface PipelineStageProps extends StepPositional {
+  status: StepStatus;
+  /** The milestone's name — the one thing every stage shows. */
+  title: string;
+  /** A muted line under the title: how long it has sat here, whose desk it is on.
+   *  Prose, not a value the reader sets. */
+  meta?: string;
+  /** The stage's own body — `PipelineNote`, `PipelineField`, `PipelineActions`,
+   *  or anything else. A stage with no body renders as its title alone, which is
+   *  what an unreached stage should be. */
+  children?: ReactNode;
+  accessibilityLabel?: string;
+}
+
+/** One milestone. Its title reads by STATUS — the current one in full ink and
+ *  medium weight, everything else muted — so the eye lands on the stage that is
+ *  live without reading a word.
+ *
+ *  Deliberately NOT pressable. `Step` can be (a wizard whose steps navigate),
+ *  but a pipeline stage is a workspace, not a destination — its body already
+ *  holds the controls, and a press target wrapping them would swallow their taps. */
+export function PipelineStage(props: PipelineStageProps) {
+  const { status, title, meta, children, accessibilityLabel, ...positional } = props;
+  const isCurrent = status === "current";
+  return (
+    <Step
+      status={status}
+      accessibilityLabel={accessibilityLabel ?? title}
+      {...positional}
+    >
+      <View style={{ gap: 6 }}>
+        <View style={{ gap: 2 }}>
+          <Text size="sm" color={isCurrent ? "default" : "muted"} weight={isCurrent ? "medium" : "regular"}>
+            {title}
+          </Text>
+          {meta ? <Text size="xs" color="muted">{meta}</Text> : null}
+        </View>
+        {children}
+      </View>
+    </Step>
+  );
+}
+
+export interface PipelineNoteProps {
+  children: ReactNode;
+  /** `warning` for something outstanding at this stage, `danger` for a refusal,
+   *  `muted` for a plain remark. */
+  tone?: "muted" | "warning" | "danger";
+}
+
+/**
+ * A CONDITION attached to one stage — "sent back", "rejected", "waiting on the
+ * customer". Prose, never a control: it says what is true, and the controls that
+ * answer it sit under it in the same stage.
+ *
+ * Deliberately not a `Callout`. A callout is a page-level interruption with its
+ * own box and tone fill; inside a stage that box competes with the spine and
+ * reads as an alert about the whole record. A stage's condition is a line of text
+ * in the stage's own column.
+ */
+export function PipelineNote({ children, tone = "muted" }: PipelineNoteProps) {
+  return <Text size="xs" color={tone}>{children}</Text>;
+}
+
+export interface PipelineFieldProps {
+  /** The value's name. Stacked ABOVE the control rather than in a label column:
+   *  a stage's content column is already indented past the spine, and a second
+   *  fixed column inside it leaves nothing for the value. */
+  label?: string;
+  children: ReactNode;
+  /** Cap the control's width so a lone text input does not run the full column. */
+  maxWidth?: number;
+}
+
+/** A value this stage OWNS, editable in place. Render it on a passed stage too —
+ *  a milestone being behind you is not a reason its facts stop being wrong. */
+export function PipelineField({ label, children, maxWidth = 320 }: PipelineFieldProps) {
+  return (
+    <View style={{ gap: 2, maxWidth }}>
+      {label ? <Text size="xs" color="muted">{label}</Text> : null}
+      {children}
+    </View>
+  );
+}
+
+/** The act(s) that leave this stage. Wraps on a narrow column so a stage with two
+ *  verbs never pushes the spine sideways. */
+export function PipelineActions({ children }: { children: ReactNode }) {
+  return <View style={{ flexDirection: "row", gap: 8, flexWrap: "wrap", paddingTop: 2 }}>{children}</View>;
+}

package/src/step_progress.tsx

@@ -59,10 +59,18 @@ export function StepProgress(props: StepProgressProps) {
         : `${Math.max(0, safe + 1)}/${count}${safe >= 0 ? ` · ${names[safe]}` : ""}`
       : undefined);
 
+  // `progressbar` IS right here — the segments are decoration over one quantity,
+  // so nothing is lost to its presentational children — but only once it carries
+  // the quantity. Without valuenow/min/max it announces as an indeterminate
+  // "busy", which is the opposite of a bar whose whole job is "4 of 7". (A
+  // sequence whose steps carry their OWN content is a list — that is `Stepper`.)
   const bar = (
     <View
       accessibilityRole="progressbar"
       accessibilityLabel={accessibilityLabel ?? caption ?? `${Math.max(0, safe + 1)} of ${count}`}
+      aria-valuenow={isComplete ? count : Math.max(0, safe + 1)}
+      aria-valuemin={0}
+      aria-valuemax={count}
       style={{ flexDirection: "row", gap: 3, flex: 1 }}
     >
       {Array.from({ length: count }, (_, i) => (

package/src/stepper.tsx

@@ -47,7 +47,11 @@ export interface StepperProps {
   accessibilityLabel?: string;
 }
 
-interface StepPositional {
+/** The props `Stepper` CLONES onto its direct children. Exported so a component
+ *  that stands where a `Step` would (`PipelineStage`) 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 {
   _last?: boolean;
   _leftFilled?: boolean;
   _rightFilled?: boolean;
@@ -94,6 +98,12 @@ export function Stepper(props: StepperProps) {
   const statuses = items.map((c) => c.props.status);
   const last = items.length - 1;
   const a11y = accessibilityLabel ?? "Progress";
+  // A LIST of named positions, never `progressbar`. `progressbar` is a RANGE
+  // widget — it wants valuenow/min/max, announces as indeterminate without them,
+  // and its children are PRESENTATIONAL, which strips every step's label (and,
+  // in a `Pipeline`, its date pickers, selects and buttons) out of the
+  // accessibility tree. A discrete named sequence is a list whose live entry
+  // carries `aria-current="step"`. The proportional bar is `StepProgress`.
 
   const positioned = items.map((child, i) =>
     cloneElement(child, {
@@ -105,7 +115,7 @@ export function Stepper(props: StepperProps) {
 
   return (
     <StepperContext.Provider value={{ orientation, color, live }}>
-      <View accessibilityRole="progressbar" accessibilityLabel={a11y} style={orientation === "horizontal" ? styles.hRow : undefined}>
+      <View role="list" accessibilityLabel={a11y} style={orientation === "horizontal" ? styles.hRow : undefined}>
         {positioned}
       </View>
     </StepperContext.Provider>
@@ -115,6 +125,11 @@ export function Stepper(props: StepperProps) {
 export function Step(props: StepProps) {
   const { status, children, onPress, active, accessibilityLabel, _last, _leftFilled, _rightFilled } = props;
   const { orientation, color, live } = useContext(StepperContext);
+  // 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
+  // in the sequence, and a reader jumping between list items needs it announced
+  // with the item, not buried in whatever the caller composed inside.
+  const item = { role: "listitem" as const, "aria-current": status === "current" ? ("step" as const) : undefined };
 
   if (orientation === "horizontal") {
     const inner = (
@@ -131,7 +146,7 @@ export function Step(props: StepProps) {
     // target — generous, no dead zones; `active` washes the selected one.
     if (onPress) {
       return (
-        <View style={styles.hStepSlot}>
+        <View {...item} style={styles.hStepSlot}>
           <PressableHighlight
             focusRing
             onPress={onPress}
@@ -144,31 +159,36 @@ export function Step(props: StepProps) {
         </View>
       );
     }
-    return <View style={styles.hStep}>{inner}</View>;
+    return <View {...item} style={styles.hStep}>{inner}</View>;
   }
 
   const body = <View style={[styles.vRowBox, 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.
+  // The listitem wraps the animation rather than sitting inside it: a `list`
+  // owns its `listitem`s DIRECTLY, and the fade's own element between them would
+  // break that ownership. It carries no style, so the layout is unchanged.
   return (
-    <AnimationFadeIn translateY={6}>
-      <View style={styles.vItem}>
-        <View style={styles.vSpineCol}>
-          <Marker status={status} color={color} live={live} />
-          {!_last ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
-        </View>
-        <View style={[styles.vContent, !_last ? styles.vGap : null]}>
-          {onPress ? (
-            <PressableHighlight focusRing onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.vPress}>
-              {body}
-            </PressableHighlight>
-          ) : (
-            body
-          )}
+    <View {...item}>
+      <AnimationFadeIn translateY={6}>
+        <View style={styles.vItem}>
+          <View style={styles.vSpineCol}>
+            <Marker status={status} color={color} live={live} />
+            {!_last ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
+          </View>
+          <View style={[styles.vContent, !_last ? styles.vGap : null]}>
+            {onPress ? (
+              <PressableHighlight focusRing onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.vPress}>
+                {body}
+              </PressableHighlight>
+            ) : (
+              body
+            )}
+          </View>
         </View>
-      </View>
-    </AnimationFadeIn>
+      </AnimationFadeIn>
+    </View>
   );
 }