@lotics/ui 5.3.0 → 5.5.0

package/src/stepper.tsx

@@ -1,88 +1,229 @@
-import { View } from "react-native";
-import { colors } from "./colors";
+import {
+  Children,
+  cloneElement,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { Animated, StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
 import { Icon } from "./icon";
 import { Text } from "./text";
+import { PressableHighlight } from "./pressable_highlight";
+import { AnimationFadeIn } from "./animation_fade_in";
 
-export type StepStatus = "done" | "current" | "upcoming";
+// A node's place in a sequence. `upcoming` = not reached (greyish); `current` =
+// where we are (ring + white centre, pulses when live); `done` = passed (filled);
+// `complete` = the terminal "finished" marker (filled + check); `warning` = an
+// issue at a reached step.
+export type StepStatus = "upcoming" | "current" | "done" | "warning" | "complete";
+export type StepOrientation = "horizontal" | "vertical";
+
+const reached = (s: StepStatus) => s !== "upcoming";
+
+interface StepperConfig {
+  orientation: StepOrientation;
+  color: string;
+  /** 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 });
 
 export interface StepperProps {
-  /** Ordered step labels, left → right. */
-  steps: string[];
-  /** Index of the in-progress step; lower indices render complete. */
-  current: number;
-  /** Accent for the completed track, current ring, and current label.
-   *  Defaults to the neutral ink — pass a brand color to theme it. */
+  /** Compound form: `<Stepper><Step status>…</Step></Stepper>` — swappable content. */
+  children?: ReactNode;
+  /** Data form: ordered labels; `current` derives each step's status. Ignored when `children` is set. */
+  steps?: string[];
+  current?: number;
+  orientation?: StepOrientation;
+  live?: boolean;
+  /** Accent ink for reached nodes + the connecting track. Defaults to neutral ink. */
   color?: string;
   accessibilityLabel?: string;
 }
 
-function statusOf(index: number, current: number): StepStatus {
-  if (index < current) return "done";
-  if (index === current) return "current";
-  return "upcoming";
+interface StepPositional {
+  _last?: boolean;
+  _leftFilled?: boolean;
+  _rightFilled?: boolean;
+}
+
+export interface StepProps extends StepPositional {
+  status: StepStatus;
+  children: ReactNode;
+  /** Make the step navigable; the active one holds a wash so a panel can sit beside it (vertical). */
+  onPress?: () => void;
+  active?: boolean;
+  accessibilityLabel?: string;
 }
 
 /**
- * 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`.
+ * Progress through an ordered sequence — done · current · upcoming on a
+ * connecting track (horizontal) or spine (vertical). The node encodes STATUS,
+ * not identity: a filled dot once reached, a ring with a white centre at the
+ * current step (pulsing when `live`), a faint ring for what's ahead, a check for
+ * the terminal `complete`. Drive it the compound way (`<Step status>` children —
+ * the label is yours to compose) or the data way (`steps` + `current`). For a
+ * heterogeneous event LOG with per-row icons + expandable details use `Timeline`;
+ * for a compact stage bar use `StepProgress`.
  */
 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] ?? ""}`;
+  const { children, steps, current, orientation = "horizontal", live = false, color = colors.zinc[700], accessibilityLabel } = props;
+
+  const content: ReactNode =
+    children ??
+    (steps ?? []).map((label, i) => {
+      const status: StepStatus = current == null ? "upcoming" : i < current ? "done" : i === current ? "current" : "upcoming";
+      const isCurrent = status === "current";
+      return (
+        <Step key={label} status={status}>
+          <Text size="xs" color={isCurrent ? "default" : "muted"} weight={isCurrent ? "semibold" : "regular"} style={isCurrent ? { color } : undefined}>
+            {label}
+          </Text>
+        </Step>
+      );
+    });
+
+  const items = Children.toArray(content).filter((c): c is ReactElement<StepProps> => isValidElement(c));
+  const statuses = items.map((c) => c.props.status);
+  const last = items.length - 1;
+  const a11y = accessibilityLabel ?? "Progress";
+
+  const positioned = items.map((child, i) =>
+    cloneElement(child, {
+      _last: i === last,
+      _leftFilled: i > 0 && reached(statuses[i - 1]),
+      _rightFilled: i < last && reached(statuses[i]),
+    }),
+  );
 
   return (
-    <View
-      accessibilityRole="progressbar"
-      accessibilityLabel={a11y}
-      style={{ flexDirection: "row" }}
-    >
-      {steps.map((label, i) => {
-        const status = statusOf(i, current);
-        const leftFilled = i <= current && i > 0;
-        const rightFilled = i < current && i < last;
-        const isCurrent = status === "current";
-        return (
-          <View key={label} style={{ flex: 1, alignItems: "center", gap: 8 }}>
-            <View style={{ flexDirection: "row", alignItems: "center", width: "100%" }}>
-              <View style={{ flex: 1, height: 2, backgroundColor: leftFilled ? color : colors.zinc[200] }} />
-              <StepDot status={status} color={color} />
-              <View style={{ flex: 1, height: 2, backgroundColor: rightFilled ? color : colors.zinc[200] }} />
-            </View>
-            <Text
-              size="xs"
-              color={isCurrent ? "default" : "muted"}
-              weight={isCurrent ? "semibold" : "regular"}
-              style={isCurrent ? { color } : undefined}
-            >
-              {label}
-            </Text>
-          </View>
-        );
-      })}
-    </View>
+    <StepperContext.Provider value={{ orientation, color, live }}>
+      <View accessibilityRole="progressbar" accessibilityLabel={a11y} style={orientation === "horizontal" ? styles.hRow : undefined}>
+        {positioned}
+      </View>
+    </StepperContext.Provider>
   );
 }
 
-function StepDot({ status, color }: { status: StepStatus; color: string }) {
-  if (status === "done") {
-    return <Icon name="circle-check" size={16} color={color} />;
+export function Step(props: StepProps) {
+  const { status, children, onPress, active, accessibilityLabel, _last, _leftFilled, _rightFilled } = props;
+  const { orientation, color, live } = useContext(StepperContext);
+
+  if (orientation === "horizontal") {
+    return (
+      <View style={styles.hStep}>
+        <View style={styles.hTrackRow}>
+          <View style={[styles.hTrack, { backgroundColor: _leftFilled ? color : colors.zinc[200] }]} />
+          <Marker status={status} color={color} live={live} />
+          <View style={[styles.hTrack, { backgroundColor: _rightFilled ? color : colors.zinc[200] }]} />
+        </View>
+        <View style={styles.hLabel}>{children}</View>
+      </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.
   return (
-    <View
-      style={{
-        width: 16,
-        height: 16,
-        borderRadius: 8,
-        backgroundColor: colors.white,
-        borderWidth: status === "current" ? 3 : 1.5,
-        borderColor: status === "current" ? color : colors.zinc[300],
-      }}
-    />
+    <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 onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.vPress}>
+              {body}
+            </PressableHighlight>
+          ) : (
+            body
+          )}
+        </View>
+      </View>
+    </AnimationFadeIn>
   );
 }
+
+// The node — status drives fill, never size. Monochrome: reached fills with ink,
+// the current step is a ring around white (pulsing when live), what's ahead is a
+// faint grey ring, the terminal is a checked fill.
+function Marker({ status, color, live }: { status: StepStatus; color: string; live: boolean }) {
+  if (status === "done") {
+    // A passed step: filled in the accent ink with a white check.
+    return (
+      <View style={[styles.disc, { backgroundColor: color }]}>
+        <Icon name="check" size={10} color={colors.white} />
+      </View>
+    );
+  }
+  if (status === "complete") {
+    // The terminal "Done" — a blackish ring with a white centre and a black check.
+    return (
+      <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 2, borderColor: colors.zinc[900] }]}>
+        <Icon name="check" size={10} color={colors.zinc[900]} />
+      </View>
+    );
+  }
+  if (status === "warning") {
+    return (
+      <View style={[styles.disc, { backgroundColor: solid("amber") }]}>
+        <View style={styles.shortBar} />
+      </View>
+    );
+  }
+  if (status === "current") {
+    return (
+      <View style={styles.discWrap}>
+        {live ? <Pulse color={color} /> : null}
+        <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 2.5, borderColor: color }]} />
+      </View>
+    );
+  }
+  return <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 1.5, borderColor: colors.zinc[300] }]} />;
+}
+
+// An expanding, fading halo behind the current node — the "live" pulse.
+function Pulse({ color }: { color: string }) {
+  const v = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    const loop = Animated.loop(Animated.timing(v, { toValue: 1, duration: 1500, useNativeDriver: false }));
+    loop.start();
+    return () => loop.stop();
+  }, [v]);
+  const transform = [{ scale: v.interpolate({ inputRange: [0, 1], outputRange: [1, 2.2] }) }];
+  const opacity = v.interpolate({ inputRange: [0, 1], outputRange: [0.35, 0] });
+  return <Animated.View style={[styles.pulse, { borderColor: color, transform, opacity }]} />;
+}
+
+const NODE = 18;
+
+const styles = StyleSheet.create({
+  hRow: { flexDirection: "row" },
+  hStep: { flex: 1, alignItems: "center", gap: 8 },
+  hTrackRow: { flexDirection: "row", alignItems: "center", width: "100%" },
+  hTrack: { flex: 1, height: 2 },
+  hLabel: { alignItems: "center" },
+
+  vItem: { flexDirection: "row", gap: 12 },
+  vSpineCol: { width: NODE, alignItems: "center", paddingTop: 3 },
+  vSpine: { width: 1.5, flex: 1, minHeight: 14, borderRadius: 1, marginTop: 4 },
+  vContent: { flex: 1 },
+  vGap: { paddingBottom: 12 },
+  vPress: { borderRadius: 8, marginHorizontal: -10 },
+  vRowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: 2 },
+  vActive: { backgroundColor: colors.zinc[100] },
+
+  discWrap: { width: NODE, height: NODE, alignItems: "center", justifyContent: "center" },
+  disc: { width: NODE, height: NODE, borderRadius: NODE / 2, alignItems: "center", justifyContent: "center" },
+  pulse: { position: "absolute", width: NODE, height: NODE, borderRadius: NODE / 2, borderWidth: 2, pointerEvents: "none" },
+  shortBar: { width: 8, height: 2, borderRadius: 1, backgroundColor: colors.white },
+});

package/src/step_list.tsx

@@ -1,128 +0,0 @@
-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] },
-});