pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/stat-tile/StatTile.js

@@ -1,12 +1,20 @@
 "use strict";
 
-import { memo, useCallback } from "react";
-import { Pressable, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+/**
+ * StatTile — a labelled metric. The value fades back in whenever it changes, so a live-updating
+ * dashboard reads as a transition rather than a silent swap; the first render never animates.
+ */
+
+import { memo, useEffect, useMemo, useRef } from "react";
+import { Animated, Pressable, Text as RNText, View } from "react-native";
+import { useAnimatedValue, useMotion, usePressMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { Skeleton } from "../skeleton/index.js";
+import { resolveTextStyle } from "../text/Text.variants.js";
 import { resolveStatTileAccessibility, resolveStatTileColors, statTileBodyStructure, statTileIconStructure, statTileStructure } from "./StatTile.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const VALUE_SKELETON_WIDTH = 72;
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
 export const StatTile = /*#__PURE__*/memo(function StatTile({
   label,
   value,
@@ -18,69 +26,103 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveStatTileColors(theme.colors, tone);
-  const a11y = resolveStatTileAccessibility({
+  const motion = useMotion();
+  const pressable = onPress !== undefined;
+  const press = usePressMotion(!pressable);
+  const valueOpacity = useAnimatedValue(1);
+  const previousValue = useRef(value);
+  const valueAnimation = useRef(null);
+  useEffect(() => {
+    if (previousValue.current === value) return;
+    previousValue.current = value;
+    valueAnimation.current?.stop();
+    if (!motion.enabled) {
+      valueOpacity.setValue(1);
+      return;
+    }
+    valueOpacity.setValue(0);
+    valueAnimation.current = motion.timing(valueOpacity, 1, {
+      duration: "fast",
+      easing: "decelerate"
+    });
+    valueAnimation.current.start();
+  }, [value, motion, valueOpacity]);
+  useEffect(() => () => valueAnimation.current?.stop(), []);
+  const tileColors = useMemo(() => resolveStatTileColors(theme.colors, tone), [theme.colors, tone]);
+  const a11y = useMemo(() => resolveStatTileAccessibility({
     label,
     value,
     loading,
-    pressable: onPress !== undefined
-  });
-  const rootStyle = useCallback(({
-    pressed
-  }) => [statTileStructure(theme), {
-    backgroundColor: pressed ? colors.pressed : colors.background
-  }, theme.elevation.md, style], [theme, colors, style]);
+    pressable
+  }), [label, value, loading, pressable]);
+  const baseStyle = useMemo(() => [statTileStructure(theme), {
+    backgroundColor: tileColors.background
+  }, theme.elevation.md, style], [theme, tileColors, style]);
+  // `style` stays last; the press style holds only opacity/transform, which `LayoutStyle` cannot name.
+  const pressableStyle = useMemo(() => [statTileStructure(theme), {
+    backgroundColor: tileColors.background
+  }, theme.elevation.md, press.style, style], [theme, tileColors, press.style, style]);
+  const iconStyle = useMemo(() => [statTileIconStructure(theme), {
+    backgroundColor: tileColors.iconFill
+  }], [theme, tileColors]);
+  const bodyStyle = useMemo(() => statTileBodyStructure(theme), [theme]);
+  const labelTypography = useMemo(() => resolveTextStyle(theme, "caption", {
+    color: "muted",
+    weight: "medium"
+  }), [theme]);
+  const labelStyle = useMemo(() => [labelTypography, {
+    color: tileColors.label
+  }], [labelTypography, tileColors.label]);
+  const valueTypography = useMemo(() => resolveTextStyle(theme, "title", {
+    weight: "semibold"
+  }), [theme]);
+  const valueStyle = useMemo(() => [valueTypography, {
+    color: tileColors.valueColor,
+    opacity: valueOpacity
+  }], [valueTypography, tileColors.valueColor, valueOpacity]);
   const body = /*#__PURE__*/_jsxs(_Fragment, {
     children: [icon !== undefined && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-icon`,
-      style: [statTileIconStructure(theme), {
-        backgroundColor: colors.iconFill
-      }],
+      style: iconStyle,
       children: icon
     }), /*#__PURE__*/_jsxs(View, {
-      style: statTileBodyStructure(theme),
-      children: [/*#__PURE__*/_jsx(Text, {
+      style: bodyStyle,
+      children: [/*#__PURE__*/_jsx(RNText, {
         numberOfLines: 1,
-        style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
-          fontSize: theme.fontSizes.sm,
-          color: colors.label
-        }],
+        style: labelStyle,
         children: label
       }), loading ? /*#__PURE__*/_jsx(Skeleton, {
         width: VALUE_SKELETON_WIDTH,
         height: theme.fontSizes["2xl"],
         testID: testID === undefined ? undefined : `${testID}-skeleton`
-      }) : /*#__PURE__*/_jsx(Text, {
+      }) : /*#__PURE__*/_jsx(Animated.Text, {
         numberOfLines: 1,
-        style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-          fontSize: theme.fontSizes["2xl"],
-          color: colors.value
-        }],
+        style: valueStyle,
         children: value
       })]
     })]
   });
-  if (onPress === undefined) {
+  if (!pressable) {
     return /*#__PURE__*/_jsx(View, {
       testID: testID,
       accessible: a11y.accessible,
       accessibilityRole: a11y.accessibilityRole,
       accessibilityLabel: a11y.accessibilityLabel,
-      accessibilityState: a11y.accessibilityState,
-      style: [statTileStructure(theme), {
-        backgroundColor: colors.background
-      }, theme.elevation.md, style],
+      "aria-busy": a11y["aria-busy"],
+      style: baseStyle,
       children: body
     });
   }
-  return /*#__PURE__*/_jsx(Pressable, {
+  return /*#__PURE__*/_jsx(AnimatedPressable, {
     testID: testID,
     accessible: a11y.accessible,
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: a11y.accessibilityLabel,
-    accessibilityState: a11y.accessibilityState,
+    "aria-busy": a11y["aria-busy"],
     onPress: onPress,
-    style: rootStyle,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    style: pressableStyle,
     children: body
   });
 });

package/lib/module/modules/stat-tile/StatTile.variants.js

@@ -14,18 +14,20 @@ export function resolveStatTileColors(colors, tone) {
     // `bg.sunken` clears AA everywhere (`StatTile.test.ts`).
     pressed: colors.bg.sunken,
     label: colors.fg.muted,
-    value: colors.fg.default,
+    valueColor: colors.fg.default,
     iconFill
   };
 }
+/**
+ * Flat `aria-busy` rather than `accessibilityState={{ busy }}`: RN's `View`/`Pressable` fold it back
+ * into `accessibilityState`, while react-native-web forwards only the flat form.
+ */
 export function resolveStatTileAccessibility(input) {
   return {
     accessible: true,
     accessibilityRole: input.pressable ? "button" : "text",
     accessibilityLabel: input.loading ? input.label : `${input.label}, ${input.value}`,
-    accessibilityState: {
-      busy: input.loading
-    }
+    "aria-busy": input.loading
   };
 }
 export const statTileStructure = createThemedVariants(theme => ({
@@ -34,6 +36,7 @@ export const statTileStructure = createThemedVariants(theme => ({
     alignItems: "center",
     columnGap: theme.space[3],
     borderRadius: theme.radii.lg,
+    borderCurve: "continuous",
     padding: theme.space[4]
   }
 }));
@@ -42,6 +45,7 @@ export const statTileIconStructure = createThemedVariants(theme => ({
     width: theme.space[10],
     height: theme.space[10],
     borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     alignItems: "center",
     justifyContent: "center"
   }

package/lib/module/modules/state-block/MODULE.md

@@ -0,0 +1,55 @@
+# state-block/ — LoadingState and ErrorState beside empty-state
+
+`LoadingState` and `ErrorState` are centred async-state placeholders, siblings to `empty-state`:
+  - `LoadingState` composes this library's `Spinner` (never a raw `ActivityIndicator`).
+  - `ErrorState` mirrors `EmptyState`'s layout with an optional retry action via `Button`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `StateBlock.tsx` | Exports `LoadingState` and `ErrorState`. Both wrapped in `React.memo`. |
+| `StateBlock.variants.ts` | Pure colour resolvers + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `LoadingState`, `ErrorState`, their props/action types, `SpinnerSize`, `SpinnerTone`, `IconName`. |
+| `__tests__/StateBlock.test.ts` | Pure: WCAG on ErrorState title/icon, loading message mapping. |
+| `__tests__/StateBlock.render.test.tsx` | Render: spinner role, error retry button, consumer `style` last. |
+
+## LoadingState props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | `string` | — | Optional muted caption below the spinner. |
+| `size` | `SpinnerSize` | `"md"` | Forwarded to `Spinner`. |
+| `tone` | `SpinnerTone` | `"accent"` | Forwarded to `Spinner`. |
+| `fill` | `boolean` | `false` | `flex: 1` + centred — fills a list/screen slot without a wrapper. |
+| `visible` | `boolean` | `true` | Fades/slides out when `false`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`. |
+
+## ErrorState props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `icon` | `IconName` | `"circle-alert"` | Decorative — hidden from assistive tech. |
+| `title` | `string` | — | Required. Bold, centred. |
+| `description` | `string` | — | Optional. Muted, centred. |
+| `action` | `{ label; onPress }` | — | Optional retry via `Button` (`tone="accent" variant="solid"`). |
+| `fill` | `boolean` | `false` | `flex: 1` + centred — fills a list/screen slot without a wrapper. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`. |
+
+## Accessibility contract (WCAG)
+
+- **1.3.1 / 2.4.6** — `ErrorState`'s title carries `accessibilityRole="header"`, matching the
+  sibling `EmptyState` (its title is the state's heading, not a plain paragraph).
+- **4.1.3** — both blocks appear WITHOUT moving focus (`Screen` swaps them in for its `children`), so
+  appearing is itself the status message: `useAnnounce` speaks `LoadingState`'s `message` and
+  `ErrorState`'s `title` + `description` once, on arrival (gated on `visible`, mirroring
+  `EmptyState.resolveEmptyStateAnnouncement`'s shape via the new `resolveErrorStateAnnouncement`). No
+  `accessibilityLiveRegion` alongside it — Android-only, would double-announce there.
+- Consuming apps that render `LoadingState`/`ErrorState` directly (not through `Screen`'s default
+  slots) now get this announcement automatically — no prop change needed on their end.
+
+## Performance
+
+Both exports wrapped in `React.memo`.

package/lib/module/modules/state-block/StateBlock.js

@@ -0,0 +1,136 @@
+"use strict";
+
+/**
+ * StateBlock — centred async-state placeholders beside `empty-state`:
+ *  - `LoadingState` composes this library's own `Spinner` (never a raw `ActivityIndicator`).
+ *  - `ErrorState` mirrors `EmptyState`'s layout — optional icon, required title, optional
+ *    description, optional retry action via `Button`.
+ *
+ * No `accessibilityRole` of its own on either export: the composed `Spinner`/`Button` carry their
+ * own semantics, and `ErrorState`'s title is the block's heading (`accessibilityRole="header"`,
+ * WCAG 1.3.1 / 2.4.6) with the description reading after it.
+ *
+ * Both blocks appear WITHOUT moving focus — `Screen` swaps them in for its content — so appearing is
+ * itself the status message (WCAG 4.1.3) and `useAnnounce` speaks it, exactly as the sibling
+ * `EmptyState` does. Neither carries `accessibilityRole="alert"` or `accessibilityLiveRegion`
+ * alongside it: on web `role="alert"` is itself a live region, so the pair announces twice. The
+ * library's split is one or the other — `Banner` takes the role, these take the announcement.
+ *
+ * Both take `visible` (default `true`) and fade/slide through `useEnterExit`, so swapping
+ * loading → error → content is a transition rather than a jump cut. `useEnterExit` skips the enter
+ * for a block that mounts already visible, so the default is behaviourally unchanged.
+ */
+
+import { memo, useMemo } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import Reanimated, { FadeInDown, ReduceMotion } from "react-native-reanimated";
+import { useAnnounce } from "../../core/a11y/index.js";
+import { Icon } from "../../core/icon/index.js";
+import { useEnterExit } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { Spinner } from "../spinner/index.js";
+import { ERROR_STATE_ICON_SIZE, errorStateStructure, loadingStateStructure, resolveErrorStateAnnouncement, resolveErrorStateColors, resolveLoadingStateColors, stateBlockFillStructure } from "./StateBlock.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 1.5;
+const DEFAULT_ERROR_ICON = "circle-alert";
+export const LoadingState = /*#__PURE__*/memo(function LoadingState({
+  message,
+  size = "md",
+  tone = "accent",
+  fill = false,
+  visible = true,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const enterExit = useEnterExit(visible);
+  const colors = useMemo(() => resolveLoadingStateColors(theme.colors), [theme.colors]);
+
+  // Gated on `visible`: a block mounted with `visible={false}` renders nothing, so it must not speak.
+  useAnnounce(visible ? message : undefined);
+
+  // `style` stays last; the enter/exit style holds only opacity/transform, which `LayoutStyle` cannot name.
+  const rootStyle = useMemo(() => [loadingStateStructure(theme), fill && stateBlockFillStructure(theme), enterExit.style, style], [theme, fill, enterExit.style, style]);
+  const messageStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), styles.text, {
+    fontSize: theme.fontSizes.sm,
+    color: colors.message
+  }], [theme, colors]);
+  if (!enterExit.mounted) return null;
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsx(Spinner, {
+      size: size,
+      tone: tone,
+      testID: testID === undefined ? undefined : `${testID}-spinner`
+    }), message !== undefined && /*#__PURE__*/_jsx(Text, {
+      style: messageStyle,
+      children: message
+    })]
+  });
+});
+export const ErrorState = /*#__PURE__*/memo(function ErrorState({
+  icon = DEFAULT_ERROR_ICON,
+  title,
+  description,
+  action,
+  fill = false,
+  visible = true,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const enterExit = useEnterExit(visible);
+  const colors = useMemo(() => resolveErrorStateColors(theme.colors), [theme.colors]);
+
+  // Gated on `visible`: a block mounted with `visible={false}` renders nothing, so it must not speak.
+  useAnnounce(visible ? resolveErrorStateAnnouncement(title, description) : undefined);
+
+  // `style` stays last; the enter/exit style holds only opacity/transform, which `LayoutStyle` cannot name.
+  const rootStyle = useMemo(() => [errorStateStructure(theme), fill && stateBlockFillStructure(theme), enterExit.style, style], [theme, fill, enterExit.style, style]);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.bold), styles.text, {
+    fontSize: theme.fontSizes.lg,
+    color: colors.title
+  }], [theme, colors]);
+  const descriptionStyle = useMemo(() => [styles.text, {
+    fontSize: theme.fontSizes.sm,
+    color: colors.description
+  }], [theme, colors]);
+  if (!enterExit.mounted) return null;
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsx(View, {
+      testID: testID === undefined ? undefined : `${testID}-icon`,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      children: /*#__PURE__*/_jsx(Icon, {
+        name: icon,
+        size: ERROR_STATE_ICON_SIZE,
+        color: colors.icon,
+        strokeWidth: ICON_STROKE
+      })
+    }), /*#__PURE__*/_jsx(Text, {
+      accessibilityRole: "header",
+      style: titleStyle,
+      children: title
+    }), description !== undefined && /*#__PURE__*/_jsx(Text, {
+      style: descriptionStyle,
+      children: description
+    }), action !== undefined && /*#__PURE__*/_jsx(Button, {
+      label: action.label,
+      onPress: action.onPress,
+      tone: "accent",
+      variant: "solid"
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  text: {
+    textAlign: "center"
+  }
+});
+//# sourceMappingURL=StateBlock.js.map

package/lib/module/modules/state-block/StateBlock.variants.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/**
+ * StateBlock's style resolution — `LoadingState` and `ErrorState` share this file as siblings to
+ * `empty-state/EmptyState.variants.ts`:
+ *  - STRUCTURE (centring, padding, vertical rhythm) lives in the themed resolvers below.
+ *  - COLOUR is resolved from the theme's ROLE colours, never a raw ramp and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the WCAG tests import this directly (mocking only `react-native`'s
+ * `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** The error glyph's rendered size, in dp — same focal-point reasoning as `EMPTY_STATE_ICON_SIZE`. */
+export const ERROR_STATE_ICON_SIZE = 48;
+export function resolveLoadingStateColors(colors) {
+  return {
+    message: colors.fg.muted
+  };
+}
+export function resolveErrorStateColors(colors) {
+  return {
+    icon: colors.fg.muted,
+    title: colors.fg.default,
+    description: colors.fg.muted
+  };
+}
+
+/**
+ * What a screen reader hears when the error block appears (WCAG 4.1.3) — the same shape, and the
+ * same reasoning about the recovery step, as `resolveEmptyStateAnnouncement`.
+ */
+export function resolveErrorStateAnnouncement(title, description) {
+  return description === undefined ? title : `${title}. ${description}`;
+}
+export const loadingStateStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: theme.space[6],
+    paddingVertical: theme.space[8],
+    rowGap: theme.space[3]
+  }
+}));
+export const errorStateStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: theme.space[6],
+    paddingVertical: theme.space[8],
+    rowGap: theme.space[3]
+  }
+}));
+export const stateBlockFillStructure = createThemedVariants(_theme => ({
+  base: {
+    flex: 1,
+    alignSelf: "stretch",
+    width: "100%"
+  }
+}));
+//# sourceMappingURL=StateBlock.variants.js.map

package/lib/module/modules/state-block/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/state-block`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures these through
+ * their props, never by importing internals.
+ */
+
+export { LoadingState, ErrorState } from "./StateBlock.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/stepper/MODULE.md

@@ -8,11 +8,12 @@ no `onStepPress` — a small surface per spec, not a step navigator.
 
 | File | Role |
 |------|------|
-| `Stepper.tsx` | The component. Composition + a11y wiring only — no press/focus/animation logic. |
+| `Stepper.tsx` | The component + the private memo'd `StepColumn`. Composition, a11y wiring, and the step-advance settle. No press/focus logic. |
 | `Stepper.variants.ts` | Pure resolvers (`resolveStepState`, `resolveStepCircleColors`, `resolveStepLabelColor`, `resolveStepConnectorColor`, `resolveStepperAccessibility`) + the structural variant resolvers `stepCircleStructure`, `stepLabelStructure`, `stepConnectorLineStructure`. No React, no lucide. |
 | `index.ts` | Public surface: `Stepper`, `StepperProps`, `StepperStep`. |
 | `__tests__/Stepper.test.ts` | Pure: state arithmetic, WCAG contrast (all brands × modes), accessibility-summary contract. |
 | `__tests__/Stepper.render.test.tsx` | Render: labels/numbers render, single collapsed `progressbar` node, per-state circle colour, consumer `style` applies last. |
+| `__tests__/Stepper.motion.test.tsx` | Motion: the reduce-motion snap, the real advance pulse, and the no-replay guard below. |
 
 ## Props
 
@@ -48,8 +49,10 @@ both halves from the same function so they always agree.
 - **4.1.2** — the whole row is ONE accessible node (`accessible` on the container), same collapsing
   idiom `Badge` uses for its icon + label: a screen reader gets a single summary announcement
   instead of reading every circle and label individually.
-- `accessibilityRole="progressbar"`, `accessibilityValue={{ min: 0, max: steps.length - 1, now:
-  activeStep }}` — the raw 0-indexed progress triple (floors `max` at 0 for a single-step stepper).
+- `accessibilityRole="progressbar"`, flat `aria-valuemin={0} aria-valuemax={steps.length - 1}
+  aria-valuenow={activeStep}` — the raw 0-indexed progress triple (floors `max` at 0 for a
+  single-step stepper). Flat, not `accessibilityValue={{…}}` — react-native-web 0.21.2 forwards only
+  the flat form to the DOM; the object reaches nothing there.
 - `accessibilityLabel` is a natural-language summary, e.g. `"Step 2 of 4: Shipping"` — the 1-based
   ordinal plus the active step's label (omits the `: <label>` suffix, never a dangling colon, if
   `activeStep` has no matching step).
@@ -61,8 +64,23 @@ both halves from the same function so they always agree.
   — same reasoning `Divider.variants.ts` documents for its own decorative hairline: it conveys no
   information the numbered circles don't already carry, so WCAG 1.4.11 (which binds only a "User
   Interface Component" or a required "Graphical Object") does not apply to it.
-- No touch target / `hitSlop`, no focus ring, no reduced-motion handling — Stepper is
-  non-interactive (no `Pressable`) and has no animation to suppress, same as `Badge`/`Divider`.
+- No touch target / `hitSlop` and no focus ring — Stepper is non-interactive (no `Pressable`), same
+  as `Badge`/`Divider`.
+- **2.3.3** — the step-advance settle is skipped and the final scale `setValue`'d whenever
+  `useMotion().enabled` is false (reduced motion or the global kill switch).
+
+## Step-advance motion
+
+Advancing `activeStep` settles the newly-active circle from `scale: 1.12` to `1` (`core/motion`,
+`fast` + `decelerate`). ONE shared `Animated.Value` lives on `Stepper` and is handed only to the
+active column — never one value per step. The connectors are deliberately static: they change
+`backgroundColor`, which cannot run on the native driver. Stopped on effect cleanup (both branches
+return the same cleanup) and on unmount.
+
+**Only a real `activeStep` change settles.** `motion` is an effect dep, so the effect also re-runs
+when the OS reduce-motion setting flips mid-session — a `lastStep` ref makes that (and the first
+mount, where arriving on a step is not an advance) a no-op `setValue(1)` instead of replaying a
+settle for a step the user never left.
 
 ## Patterns copied from Button (the reference module) and Badge
 
@@ -85,4 +103,13 @@ both halves from the same function so they always agree.
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The `steps.map()` renders host `View`/`Text` directly, no library child component — nothing to memoize.
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Each step is a
+private, memo'd `StepColumn` fed primitives only, so advancing a step re-renders the two affected
+columns rather than the whole row; every style array it builds is memoized, and the row's static
+layout lives in `StyleSheet.create`.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.