pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/stage-progress/StageProgress.variants.js

@@ -0,0 +1,164 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+/** WCAG 2.5.5 target size, the library-wide floor (`Tabs`/`Pagination`/`Reorder` all pin the same 44). */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+
+/**
+ * Floor for the pill's height. The pill sizes itself from padding + its label's font metrics, so
+ * without a floor there is no number the touch-target maths can be proven against; pinned here at
+ * the value the natural layout already exceeds (2×`space[2]` + a 14dp line + two hairlines ≈ 35dp),
+ * so it changes no pixel and makes the `hitSlop` guarantee below arithmetic rather than a hope.
+ */
+export const STAGE_PILL_MIN_HEIGHT = 32;
+
+/** Stepper circle diameter. Shared by the structure resolver and the touch-target maths. */
+export const STAGE_STEPPER_CIRCLE = 28;
+
+/**
+ * Vertical-only `hitSlop` for the two pressable stage shapes. Both are wider than 44dp already
+ * (`minWidth` 72 / 64), so widening horizontally would only make adjacent stages' targets overlap.
+ * Height is the short axis, so it is padded to the floor the `Tabs`/`CopyButton` `slopFor` idiom
+ * defines. Applied only where a stage is actually pressable — `readOnly` stages render no
+ * `Pressable` and need no target at all.
+ */
+export const STAGE_PILL_HIT_SLOP = {
+  top: slopFor(STAGE_PILL_MIN_HEIGHT),
+  bottom: slopFor(STAGE_PILL_MIN_HEIGHT)
+};
+export const STAGE_STEPPER_HIT_SLOP = {
+  top: slopFor(STAGE_STEPPER_CIRCLE),
+  bottom: slopFor(STAGE_STEPPER_CIRCLE)
+};
+export function resolveStageState(index, activeIndex, markCompleted) {
+  if (index === activeIndex) return "active";
+  if (markCompleted && activeIndex > -1 && index < activeIndex) return "completed";
+  return "upcoming";
+}
+export function resolveActiveStageIndex(stages, value) {
+  return stages.findIndex(s => s.id === value);
+}
+const STATE_SUFFIX = {
+  completed: "completed",
+  active: "current stage",
+  upcoming: "not started"
+};
+
+/**
+ * The stage's spoken name. The suffix is the whole point (WCAG 1.4.1): fill colour is the ONLY
+ * thing that separates a completed stage from an upcoming one on screen, so without it a screen
+ * reader hears four identical labels and learns nothing about progress. The state props alone
+ * cannot carry it — there is no "completed" flag, only `selected`, which is the active stage.
+ */
+export function resolveStageAccessibilityLabel(label, state) {
+  return `${label}, ${STATE_SUFFIX[state]}`;
+}
+/**
+ * Flat `aria-*` rather than `accessibilityState={{…}}`: RN's `View`/`Pressable` fold the flat props
+ * back into that object, while react-native-web forwards only the flat form — the object reaches
+ * nothing at all on web.
+ */
+export function resolveStageAccessibilityState(state, disabled) {
+  return {
+    "aria-selected": state === "active",
+    "aria-disabled": disabled === true
+  };
+}
+/**
+ * ONE summary announcement for the whole track — "Stage 2 of 4: Review" — the same collapsing idiom
+ * (and the same shape) `resolveStepperAccessibility` uses. This is what the `bar` variant depends
+ * on: it renders nothing but coloured rectangles, with no text anywhere, so without a label on the
+ * container a screen-reader user gets literally nothing from the component.
+ */
+export function resolveStageProgressAccessibility(stages, activeIndex) {
+  const activeLabel = stages[activeIndex]?.label;
+  const ordinal = activeIndex < 0 ? 0 : activeIndex + 1;
+  const summary = `Stage ${ordinal} of ${stages.length}` + (activeLabel === undefined ? "" : `: ${activeLabel}`);
+  return {
+    accessibilityRole: "progressbar",
+    "aria-valuemin": 0,
+    "aria-valuemax": Math.max(stages.length - 1, 0),
+    "aria-valuenow": Math.max(activeIndex, 0),
+    accessibilityLabel: summary
+  };
+}
+export function resolveStageProgressColors(colors) {
+  return {
+    activeFill: colors.accent.solid,
+    activeText: colors.accent.onSolid,
+    completedFill: colors.status.success.subtle,
+    completedText: colors.status.success.text,
+    upcomingFill: colors.bg.sunken,
+    upcomingText: colors.fg.muted,
+    track: colors.border.default
+  };
+}
+export const stageProgressRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.space[1],
+    overflow: "hidden"
+  }
+}));
+export const stagePillStructure = createThemedVariants(theme => ({
+  base: {
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderRadius: theme.radii.full,
+    borderWidth: theme.borderWidths.thin,
+    minWidth: 72,
+    minHeight: STAGE_PILL_MIN_HEIGHT,
+    alignItems: "center",
+    justifyContent: "center"
+  }
+}));
+
+/**
+ * The keyboard/AT focus ring for an interactive stage, drawn INSIDE the stage's own bounds:
+ * `stageProgressRowStructure` clips to `overflow: "hidden"` and spaces stages a single space step
+ * apart, so the gap-outside ring `Button`/`CopyButton` use would be cut off on the first and last
+ * stage and overlap its neighbour everywhere else. Its colour is applied inline over this.
+ */
+export const stageFocusRingStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderWidth: theme.borderWidths.thick
+  },
+  variants: {
+    variant: {
+      pill: {
+        borderRadius: theme.radii.full
+      },
+      stepper: {
+        borderRadius: theme.radii.base
+      }
+    }
+  },
+  defaultVariants: {
+    variant: "pill"
+  }
+}));
+export const stageBarStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    height: 8,
+    borderRadius: theme.radii.full
+  }
+}));
+export const stageStepperCircleStructure = createThemedVariants(theme => ({
+  base: {
+    width: STAGE_STEPPER_CIRCLE,
+    height: STAGE_STEPPER_CIRCLE,
+    borderRadius: theme.radii.full,
+    alignItems: "center",
+    justifyContent: "center",
+    borderWidth: theme.borderWidths.thin
+  }
+}));
+//# sourceMappingURL=StageProgress.variants.js.map

package/lib/module/modules/stage-progress/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { StageProgress } from "./StageProgress.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/stat-tile/MODULE.md

@@ -23,14 +23,15 @@ chip. Tappable when `onPress` is set; shows a `Skeleton` in place of the value w
 | `icon` | `ReactNode` | — | Rendered inside a tone-tinted chip. Consumer resolves its color via `useThemeColors()`. |
 | `tone` | `accent \| neutral \| success \| warning \| danger \| info` | `accent` | Tints the icon chip only (subtle fills); label/value stay fixed `fg` roles. |
 | `onPress` | `() => void` | — | Makes the tile a `button`-role Pressable with a `bg.sunken` pressed fill (measured — `fg.default` fails AA on `bg.hover` on 4 light brands). |
-| `loading` | `boolean` | `false` | Skeleton in place of the value; announced via `accessibilityState.busy`. |
+| `loading` | `boolean` | `false` | Skeleton in place of the value; announced via `aria-busy` (flat, not `accessibilityState` — see Accessibility). |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Also derives `-icon` / `-skeleton` sub-ids. |
 
 ## Accessibility
 
 - The tile is ONE accessible node: role `button` (pressable) or `text`, label `"label, value"`
-  (just `label` while loading, with `busy: true`).
+  (just `label` while loading, with `aria-busy={true}`). Flat `aria-busy`, not
+  `accessibilityState={{ busy }}` — react-native-web 0.21.2 forwards only the flat form to the DOM.
 - Label (`fg.muted`) and value (`fg.default`) are measured ≥ 4.5:1 on `bg.raised` for all
   8 brands × both modes (`StatTile.test.ts`).
 
@@ -42,3 +43,9 @@ chip. Tappable when `onPress` is set; shows a `Skeleton` in place of the value w
 ## Performance
 
 Wrapped in `React.memo`; the Pressable style function is `useCallback`'d.
+
+## 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.

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

@@ -1,12 +1,19 @@
 "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, 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 { 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 +25,99 @@ 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 labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: tileColors.label
+  }], [theme, tileColors]);
+  const valueStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes["2xl"],
+    color: tileColors.valueColor
+  }, {
+    opacity: valueOpacity
+  }], [theme, tileColors, 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),
+      style: bodyStyle,
       children: [/*#__PURE__*/_jsx(Text, {
         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 => ({

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

@@ -0,0 +1,52 @@
+# 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`. |
+| `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"`). |
+| `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,131 @@
+"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 { Animated, StyleSheet, Text, View } from "react-native";
+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 } 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",
+  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), enterExit.style, style], [theme, 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(Animated.View, {
+    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,
+  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), enterExit.style, style], [theme, 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(Animated.View, {
+    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,55 @@
+"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]
+  }
+}));
+//# 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