@lotics/ui 21.1.0 → 21.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "21.1.0",
+  "version": "21.3.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/locale.tsx

@@ -289,8 +289,11 @@ export const en: LoticsLocale = {
     downloadAll: "Download all",
     downloadSelected: (n: number) => `Download (${n})`,
     delete: "Delete",
-    removeTitle: "Remove attachment?",
-    removeMessage: "This removes the file.",
+    // `FilesEditorRemove` removes the whole SELECTION, so the confirm is phrased for a set —
+    // singular copy under-reports what the button is about to do. And the kit does not know what
+    // the files hang off, so it says what it can see: the files, and that they are selected.
+    removeTitle: "Remove files?",
+    removeMessage: "The selected files will be removed.",
     removeCancel: "Cancel",
     removeConfirm: "Remove",
   },
@@ -438,7 +441,7 @@ export const vi: LoticsLocale = {
     downloadSelected: (n: number) => `Tải ${n} tệp`,
     delete: "Xóa",
     removeTitle: "Xóa tệp?",
-    removeMessage: "Tệp sẽ bị gỡ khỏi bản ghi.",
+    removeMessage: "Các tệp đã chọn sẽ bị xóa.",
     removeCancel: "Hủy",
     removeConfirm: "Xóa",
   },

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/progress_bar.tsx

@@ -16,6 +16,16 @@ export interface ProgressBarProps {
    * "1,250 / 2,500 · 50%" (separators follow the reader's locale). Reports the
    * TRUE ratio — over `max` it reads "105%" while the track stays clamped. */
   format?: ProgressBarFormat;
+  /**
+   * How `value` and `max` render inside the caption. Defaults to the reader's locale grouping.
+   *
+   * The escape hatch for a quantity whose natural precision is not its DISPLAY precision — a
+   * fractional credit balance metered to whole credits, a byte count shown as GB. Still the bar's
+   * job rather than the caller's: pass the true `value`/`max` so the track and the percentage stay
+   * exact, and let this reshape only the text. Pre-rounding the numbers you pass in moves the fill
+   * and the percentage too, which is how a 99.6%-full meter starts claiming it is exactly full.
+   */
+  formatValue?: (n: number) => string;
   color?: string;
   completeColor?: string;
   /** COMPACT: one row — the track (flex) with a plain sm tabular count beside
@@ -37,6 +47,7 @@ export function ProgressBar(props: ProgressBarProps) {
     max,
     title,
     format = "percentage",
+    formatValue,
     color = colors.blue["500"],
     completeColor = colors.green["500"],
     compact = false,
@@ -55,10 +66,11 @@ export function ProgressBar(props: ProgressBarProps) {
   const ratio = max > 0 ? Math.max(0, (value / max) * 100) : 0;
   const percentage = Math.min(100, ratio);
   const isComplete = ratio >= 100;
+  const num = formatValue ?? ((n: number) => n.toLocaleString(localeTag));
 
   if (compact) {
     const label =
-      format === "percentage" ? `${Math.round(ratio)}%` : `${value.toLocaleString(localeTag)}/${max.toLocaleString(localeTag)}`;
+      format === "percentage" ? `${Math.round(ratio)}%` : `${num(value)}/${num(max)}`;
     return (
       <View style={styles.compactRow}>
         <View style={[styles.track, styles.compactTrack]}>
@@ -75,7 +87,7 @@ export function ProgressBar(props: ProgressBarProps) {
 
   const caption =
     format === "fraction"
-      ? `${value.toLocaleString(localeTag)} / ${max.toLocaleString(localeTag)} · ${Math.round(ratio)}%`
+      ? `${num(value)} / ${num(max)} · ${Math.round(ratio)}%`
       : format === "percentage"
         ? `${Math.round(ratio)}%`
         : null;

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>
   );
 }