@lotics/ui 2.4.1 → 2.5.0

package/src/stacked_progress_bar.tsx

@@ -1,5 +1,6 @@
 import { View, StyleSheet } from "react-native";
 import { colors } from "./colors";
+import { Text } from "./text";
 
 interface Segment {
   /** Identifier for the segment — used as a React key. */
@@ -16,6 +17,11 @@ interface StackedProgressBarProps {
    * states render consistently (an empty array would otherwise look like
    * "data loaded with no values"). */
   total: number;
+  /** What this bar breaks down ("Phễu bán hàng") — the xs muted uppercase
+   * eyebrow above the bar. Omit inside a band that already names it. */
+  title?: string;
+  /** Context above-right of the bar ("97 cơ hội"). xs muted tabular. */
+  caption?: string;
   /** Bar pixel height. Default 14 — the dashboard hero-progress size.
    * Drop to 6-8 for inline status bars in tight rows; bump to 20-24
    * when the bar IS the section's main visualization. */
@@ -30,30 +36,59 @@ interface StackedProgressBarProps {
  * width, and a single dominant value renders as one long segment rather
  * than a "broken" bar chart with five empty stages.
  *
- * Pair with `<LegendItem />` rows below to name the colored segments.
- * Without a legend, the colored bar is decorative — viewers can't map
- * colors back to meaning.
+ * Shares the labeled-meter anatomy with `ProgressBar`/`StepProgress`:
+ * optional title eyebrow left, caption right, bar below. Pair with
+ * `<LegendItem />` rows below to name the colored segments — without a
+ * legend, the colored bar is decorative.
  */
 export function StackedProgressBar(props: StackedProgressBarProps) {
-  const { segments, total, height = 14, loading } = props;
-  if (loading || total === 0) {
-    return <View style={[styles.bar, { height, backgroundColor: colors.zinc[100] }]} />;
-  }
+  const { segments, total, title, caption, height = 14, loading } = props;
+  const bar =
+    loading || total === 0 ? (
+      <View style={[styles.bar, { height, backgroundColor: colors.zinc[100] }]} />
+    ) : (
+      <View style={[styles.bar, styles.barFilled, { height }]}>
+        {segments
+          .filter((s) => s.value > 0)
+          .map((seg) => (
+            <View key={seg.key} style={{ flex: seg.value, backgroundColor: seg.color }} />
+          ))}
+      </View>
+    );
+
+  if (!title && !caption) return bar;
   return (
-    <View style={[styles.bar, styles.barFilled, { height }]}>
-      {segments
-        .filter((s) => s.value > 0)
-        .map((seg) => (
-          <View
-            key={seg.key}
-            style={{ flex: seg.value, backgroundColor: seg.color }}
-          />
-        ))}
+    <View style={styles.container}>
+      <View style={styles.header}>
+        {title ? (
+          <Text size="xs" color="muted" transform="uppercase">
+            {title}
+          </Text>
+        ) : null}
+        <View style={styles.spacer} />
+        {caption ? (
+          <Text size="xs" color="muted" tabular>
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+      {bar}
     </View>
   );
 }
 
 const styles = StyleSheet.create({
+  container: {
+    gap: 6,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "baseline",
+    gap: 12,
+  },
+  spacer: {
+    flex: 1,
+  },
   bar: {
     borderRadius: 999,
     overflow: "hidden",

package/src/status_grid.tsx

@@ -0,0 +1,187 @@
+import { useState } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import { colors, solid, tint, type ColorName } from "./colors";
+import { PressableHighlight } from "./pressable_highlight";
+import { Text } from "./text";
+
+export interface StatusGridState {
+  key: string;
+  label: string;
+  /** Palette family name — the cell fill and legend dot derive their shades
+   * from it (solid for the cell, a tint when dimmed). Pass the name, not a
+   * hex, so one state is one color everywhere. */
+  color: ColorName;
+}
+
+export interface StatusGridItem {
+  key: string;
+  label: string;
+  state: string;
+}
+
+export interface StatusGridProps {
+  items: StatusGridItem[];
+  states: StatusGridState[];
+  /** The drilled-in state (from `StatusLegend`). Cells in other states dim
+   * and stop being pressable — they're outside the current slice. */
+  selectedState?: string | null;
+  onPressItem?: (key: string) => void;
+  /** The open/highlighted item (e.g. the unit in the drawer). */
+  activeKey?: string | null;
+  /** Cell edge in px. Default 16 — readable at hundreds of cells. */
+  cellSize?: number;
+}
+
+/**
+ * Live-state scan for hundreds of units — the wallboard pattern (machine
+ * park, fleet, gate bank, sensor field). Every unit is one color-coded
+ * cell; the job is scanning for red, not reading labels. Pressing a cell
+ * opens the unit; selecting a state in `StatusLegend` dims everything else.
+ * Render one grid per group (zone, site) and share a single legend +
+ * selection in the host — same lifted-state idiom as `Breakdown`.
+ */
+export function StatusGrid(props: StatusGridProps) {
+  const { items, states, selectedState = null, onPressItem, activeKey = null, cellSize = 16 } = props;
+  const stateOf = (key: string) => states.find((s) => s.key === key);
+
+  return (
+    <View style={styles.grid}>
+      {items.map((item) => {
+        const state = stateOf(item.state);
+        const dimmed = selectedState !== null && item.state !== selectedState;
+        const cellColor = state ? (dimmed ? tint(state.color, 0.2) : solid(state.color)) : colors.zinc[300];
+        return (
+          <Cell
+            key={item.key}
+            label={`${item.label} — ${state?.label ?? item.state}`}
+            color={cellColor}
+            size={cellSize}
+            active={activeKey === item.key}
+            onPress={onPressItem && !dimmed ? () => onPressItem(item.key) : undefined}
+          />
+        );
+      })}
+    </View>
+  );
+}
+
+interface CellProps {
+  label: string;
+  color: string;
+  size: number;
+  active: boolean;
+  onPress?: () => void;
+}
+
+function Cell(props: CellProps) {
+  const { label, color, size, active, onPress } = props;
+  const [hovered, setHovered] = useState(false);
+  const base = {
+    width: size,
+    height: size,
+    backgroundColor: color,
+    borderColor: active ? colors.zinc[900] : hovered && onPress ? "rgba(255,255,255,0.75)" : "transparent",
+  };
+  if (!onPress) return <View style={[styles.cell, base]} />;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      onPress={onPress}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      style={[styles.cell, base]}
+    />
+  );
+}
+
+export interface StatusLegendProps {
+  /** ALL items the legend summarizes (across every grid it governs). */
+  items: StatusGridItem[];
+  states: StatusGridState[];
+  selectedKey?: string | null;
+  /** Press a state to drill into it (press again to clear). Omit for an
+   * informational legend. */
+  onSelect?: (key: string | null) => void;
+}
+
+/**
+ * The legend + counts for one or more `StatusGrid`s. Pressable states drill
+ * the grids (host holds the selection); counts are derived here so the
+ * legend can never disagree with the cells.
+ */
+export function StatusLegend(props: StatusLegendProps) {
+  const { items, states, selectedKey = null, onSelect } = props;
+
+  return (
+    <View style={styles.legend}>
+      {states.map((state) => {
+        const count = items.reduce((n, item) => n + (item.state === state.key ? 1 : 0), 0);
+        const selected = selectedKey === state.key;
+        const dimmed = selectedKey !== null && !selected;
+        const row = (
+          <>
+            <View style={[styles.swatch, { backgroundColor: dimmed ? tint(state.color, 0.3) : solid(state.color) }]} />
+            <Text size="xs" color={dimmed ? "muted" : "default"}>{state.label}</Text>
+            <Text size="xs" weight={selected ? "semibold" : "regular"} color={dimmed ? "muted" : "default"} tabular>
+              {count.toLocaleString("en-US")}
+            </Text>
+          </>
+        );
+        return onSelect ? (
+          <PressableHighlight
+            key={state.key}
+            accessibilityRole="button"
+            accessibilityState={{ selected }}
+            accessibilityLabel={`${state.label}: ${count}`}
+            onPress={() => onSelect(selected ? null : state.key)}
+            style={[styles.legendItem, styles.legendPressable, selected ? styles.legendSelected : null]}
+          >
+            {row}
+          </PressableHighlight>
+        ) : (
+          <View key={state.key} style={styles.legendItem}>
+            {row}
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  grid: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: 3,
+  },
+  cell: {
+    borderRadius: 4,
+    borderWidth: 2,
+  },
+  legend: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    columnGap: 8,
+    rowGap: 4,
+  },
+  legendItem: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    minHeight: 28,
+  },
+  legendPressable: {
+    borderRadius: 6,
+    paddingHorizontal: 8,
+  },
+  legendSelected: {
+    backgroundColor: colors.zinc[100],
+  },
+  swatch: {
+    width: 8,
+    height: 8,
+    borderRadius: 999,
+  },
+});

package/src/step_list.tsx

@@ -0,0 +1,128 @@
+import { ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { PressableHighlight } from "./pressable_highlight";
+
+export type StepStatus = "pending" | "current" | "done" | "warning";
+
+export interface StepListItem {
+  id: string;
+  status: StepStatus;
+  /** Primary line — a stage, a code, a name. */
+  title: string;
+  /** Secondary muted line. */
+  subtitle?: string;
+  /** Right-aligned node — a count, a `Badge`, a time. */
+  trailing?: ReactNode;
+}
+
+export interface StepListProps {
+  steps: StepListItem[];
+  /** When set, steps become pressable to navigate; the matching step is held
+   *  highlighted so its panel can be shown elsewhere. */
+  selectedId?: string;
+  onStepPress?: (id: string) => void;
+  accessibilityLabel?: string;
+}
+
+/**
+ * A vertical step sequence on a connecting spine — done · now · up next — for a
+ * guided run, a staged process, a checklist. Every status is the SAME 20px node
+ * (filled once reached, hollow while pending), so the spine reads as one line no
+ * matter which statuses appear or in what order. Unlike `Stepper` (horizontal) or
+ * `StepProgress` (a bar), and unlike `Timeline` (past events only), it models
+ * future/pending steps. Pass `onStepPress` to make the steps NAVIGABLE — the
+ * selected step is held highlighted so the host can show its panel beside the list.
+ */
+export function StepList(props: StepListProps) {
+  const { steps, selectedId, onStepPress, accessibilityLabel } = props;
+  return (
+    <View accessibilityLabel={accessibilityLabel}>
+      {steps.map((s, i) => {
+        // The focused step: the navigated one when navigable, else "now".
+        const active = selectedId != null ? s.id === selectedId : s.status === "current";
+        const past = s.status === "done" || s.status === "warning";
+        const content = (
+          <View style={styles.contentRow}>
+            <View style={{ flex: 1, gap: 1 }}>
+              <Text size="sm" weight={active ? "medium" : "regular"} color={past && !active ? "muted" : "default"}>
+                {s.title}
+              </Text>
+              {s.subtitle ? (
+                <Text size="xs" color="muted" numberOfLines={1}>{s.subtitle}</Text>
+              ) : null}
+            </View>
+            {s.trailing}
+          </View>
+        );
+        return (
+          <View key={s.id} style={styles.item}>
+            <View style={styles.spineCol}>
+              <Marker status={s.status} />
+              {i < steps.length - 1 ? <View style={styles.spine} /> : null}
+            </View>
+            <View style={[styles.contentCol, i < steps.length - 1 ? styles.contentGap : null]}>
+              {onStepPress ? (
+                <PressableHighlight onPress={() => onStepPress(s.id)} style={[styles.rowBox, active ? styles.active : null]}>
+                  {content}
+                </PressableHighlight>
+              ) : (
+                <View style={[styles.rowBox, active ? styles.active : null]}>{content}</View>
+              )}
+            </View>
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
+/** One uniform 20px node; status drives fill, not size or shape. */
+function Marker({ status }: { status: StepStatus }) {
+  if (status === "pending") {
+    return <View style={[styles.disc, styles.discPending]} />;
+  }
+  if (status === "current") {
+    return (
+      <View style={[styles.disc, { backgroundColor: solid("blue") }]}>
+        <View style={styles.currentDot} />
+      </View>
+    );
+  }
+  if (status === "warning") {
+    return (
+      <View style={[styles.disc, { backgroundColor: solid("amber") }]}>
+        <View style={styles.shortBar} />
+      </View>
+    );
+  }
+  return (
+    <View style={[styles.disc, { backgroundColor: solid("emerald") }]}>
+      <Icon name="check" size={12} color={colors.background} />
+    </View>
+  );
+}
+
+const NODE = 20;
+
+const styles = StyleSheet.create({
+  item: { flexDirection: "row", gap: 12 },
+  // paddingTop pairs with rowBox.paddingVertical so the node centres on the
+  // FIRST line of content, not on a multi-line block.
+  spineCol: { width: NODE, alignItems: "center", paddingTop: 4 },
+  disc: { width: NODE, height: NODE, borderRadius: NODE / 2, alignItems: "center", justifyContent: "center" },
+  discPending: { backgroundColor: colors.background, borderWidth: 1.5, borderColor: colors.zinc[300] },
+  currentDot: { width: 7, height: 7, borderRadius: 999, backgroundColor: colors.background },
+  shortBar: { width: 8, height: 2, borderRadius: 1, backgroundColor: colors.background },
+  spine: { width: 1.5, flex: 1, minHeight: 14, borderRadius: 1, backgroundColor: colors.zinc[200], marginTop: 4 },
+  contentCol: { flex: 1 },
+  // The inter-step gap — on every step but the last, so the list ends flush and
+  // a container's own padding isn't doubled at the bottom.
+  contentGap: { paddingBottom: 12 },
+  contentRow: { flexDirection: "row", alignItems: "flex-start", gap: 12, flex: 1 },
+  // press + plain share one box so the active wash looks identical either way.
+  rowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: 4, marginHorizontal: -10, flexDirection: "row", alignItems: "flex-start" },
+  active: { backgroundColor: colors.zinc[100] },
+});

package/src/step_progress.tsx

@@ -0,0 +1,145 @@
+import { View, type ViewStyle } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { useTooltip } from "./tooltip";
+
+export interface StepProgressProps {
+  /** The stages: pass the NAMES (enables the built-in "4/7 · In" caption
+   *  and per-segment hover names) or a bare count (bar only). */
+  steps: number | string[];
+  /** 0-based index of the stage in progress; earlier segments render
+   *  complete. Pass -1 for "not started", `steps.length` for "complete". */
+  current: number;
+  /** Accent for the completed/current segments. Defaults to the neutral
+   *  ink — pass a brand color to theme it. */
+  color?: string;
+  /** What this progress measures ("Production stages") — adds the xs muted
+   *  uppercase eyebrow row above the bar, caption right. Omit at card
+   *  density where the context already names it. */
+  title?: string;
+  /** Caption override for when the current stage needs prose ("In production") instead of the derived "3/6 · SX". */
+  label?: string;
+  /** Tone for the caption — `danger` flags a stalled/overdue stage (a stuck
+   *  production order) in the FIXED caption spot, so the bar stays consistent
+   *  instead of a floating badge shifting it. */
+  captionTone?: "default" | "danger";
+  /** Put the caption on its OWN line below a full-width bar (vs the default
+   *  inline-right, which lets a varying caption shrink the bar). The compact,
+   *  consistent card/drawer layout — no eyebrow, the bar never shifts. */
+  captionBelow?: boolean;
+  /** Segment height. Default 10 — matches ProgressBar's track; thinner reads
+   *  weak. */
+  height?: number;
+  accessibilityLabel?: string;
+}
+
+/**
+ * THE compact stage indicator — N equal segments filled through the current
+ * stage, with a built-in "4/7 · In" caption when stages are named (hovering
+ * a segment names it). For *countable* stages an item walks through (a
+ * production line, a checklist, a pipeline) shown at card/list density.
+ *
+ * Picking a bar: continuous value-vs-max → `ProgressBar`; weighted
+ * composition/funnel → `StackedProgressBar`; a full-width wizard header
+ * where every milestone label must be visible → `Stepper`; everything
+ * stage-countable at card density → this.
+ */
+export function StepProgress(props: StepProgressProps) {
+  const { steps, current, color = colors.zinc[900], title, label, captionTone = "default", captionBelow = false, height = 10, accessibilityLabel } = props;
+  const captionColor = captionTone === "danger" ? "danger" : "muted";
+  const names = typeof steps === "number" ? null : steps;
+  const count = Math.max(1, typeof steps === "number" ? steps : steps.length);
+  const isComplete = current >= count;
+  const safe = Math.min(current, count - 1);
+  const caption =
+    label ??
+    (names
+      ? isComplete
+        ? `${count}/${count} · Complete`
+        : `${Math.max(0, safe + 1)}/${count}${safe >= 0 ? ` · ${names[safe]}` : ""}`
+      : undefined);
+
+  const bar = (
+    <View
+      accessibilityRole="progressbar"
+      accessibilityLabel={accessibilityLabel ?? caption ?? `${Math.max(0, safe + 1)} of ${count}`}
+      style={{ flexDirection: "row", gap: 3, flex: 1 }}
+    >
+      {Array.from({ length: count }, (_, i) => (
+        <Segment
+          key={i}
+          name={names?.[i]}
+          color={color}
+          height={height}
+          // Complete settles ALL segments solid — "finished" reads as
+          // accomplished, not faded.
+          done={i < safe}
+          isCurrent={isComplete || (i === safe && safe >= 0)}
+        />
+      ))}
+    </View>
+  );
+
+  if (title) {
+    return (
+      <View style={{ gap: 6, flex: 1 }}>
+        <View style={{ flexDirection: "row", alignItems: "baseline", gap: 12 }}>
+          <Text size="xs" color="muted" transform="uppercase">
+            {title}
+          </Text>
+          <View style={{ flex: 1 }} />
+          {caption ? (
+            <Text size="xs" color={captionColor} weight={captionTone === "danger" ? "medium" : "regular"} tabular>
+              {caption}
+            </Text>
+          ) : null}
+        </View>
+        {bar}
+      </View>
+    );
+  }
+
+  if (!caption) return bar;
+  if (captionBelow) {
+    return (
+      <View style={{ gap: 6, flex: 1 }}>
+        {bar}
+        <Text size="xs" color={captionColor} weight={captionTone === "danger" ? "medium" : "regular"} tabular>
+          {caption}
+        </Text>
+      </View>
+    );
+  }
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 10, flex: 1 }}>
+      {bar}
+      <Text size="xs" color={captionColor} weight={captionTone === "danger" ? "medium" : "regular"} tabular>
+        {caption}
+      </Text>
+    </View>
+  );
+}
+
+function Segment(props: { name?: string; color: string; height: number; done: boolean; isCurrent: boolean }) {
+  const { name, color, height, done, isCurrent } = props;
+  // Hovering a segment names its stage — the bar stays self-explanatory
+  // even where the caption is elided. No-ops without a TooltipProvider.
+  const tooltip = useTooltip(name);
+  return (
+    <View
+      {...tooltip}
+      style={{
+        flex: 1,
+        height,
+        borderRadius: height / 2,
+        backgroundColor: done || isCurrent ? color : colors.zinc[100],
+        opacity: done && !isCurrent ? 0.4 : 1,
+        ...(done || isCurrent
+          ? null
+          : ({ boxShadow: "inset 0 0 0 1px rgba(38,38,38,0.04)" } as ViewStyle)),
+        // Progress that snaps is dead; progress that moves is alive.
+        ...({ transition: "background-color 200ms ease-out, opacity 200ms ease-out" } as ViewStyle),
+      }}
+    />
+  );
+}

package/src/stepper.tsx

@@ -23,18 +23,23 @@ function statusOf(index: number, current: number): StepStatus {
 }
 
 /**
- * Horizontal step / status tracker — a row of milestones with completed,
- * current, and upcoming states and a connecting track. For a vertical event
- * log use `Timeline` instead.
+ * Full-width wizard/milestone header — a row of labeled milestones with
+ * completed, current, and upcoming states and a connecting track. Every
+ * label is visible; use it where the journey itself is the headline (a
+ * record detail, a checkout). At card/list density use `StepProgress`
+ * (segments + built-in caption) instead. For a vertical event log use
+ * `Timeline`.
  */
 export function Stepper(props: StepperProps) {
   const { steps, current, color = colors.zinc[900], accessibilityLabel } = props;
   const last = steps.length - 1;
   const safe = Math.max(0, Math.min(current, last));
+  const a11y = accessibilityLabel ?? `Step ${safe + 1} of ${steps.length}: ${steps[safe] ?? ""}`;
+
   return (
     <View
       accessibilityRole="progressbar"
-      accessibilityLabel={accessibilityLabel ?? `Step ${safe + 1} of ${steps.length}: ${steps[safe] ?? ""}`}
+      accessibilityLabel={a11y}
       style={{ flexDirection: "row" }}
     >
       {steps.map((label, i) => {