pixelize-native-library 1.2.0 → 1.3.0

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

@@ -5,15 +5,20 @@
  * 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 { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { Pressable, Text as RNText, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
+import { useReducedMotion } from "../../core/a11y/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { AnimatedText, useAnimatedValue, useMotion, usePressMotion } from "../../core/motion/index.js";
+import { renderNodeSlot } from "../../core/slot/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 { resolveTextStyle } from "../text/Text.variants.js";
+import { resolveStatTileAccessibility, resolveStatTileColors, resolveStatTileDeltaColor, 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);
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
 export const StatTile = /*#__PURE__*/memo(function StatTile({
   label,
   value,
@@ -21,25 +26,37 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
   tone = "accent",
   onPress,
   loading = false,
+  delta,
+  trend = "flat",
+  goodDirection = "up",
   style,
   testID
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const haptics = useHaptics();
+  const reducedMotion = useReducedMotion();
   const pressable = onPress !== undefined;
   const press = usePressMotion(!pressable);
+  const handlePress = useCallback(() => {
+    if (!reducedMotion) haptics.selection();
+    onPress?.();
+  }, [haptics, onPress, reducedMotion]);
   const valueOpacity = useAnimatedValue(1);
   const previousValue = useRef(value);
   const valueAnimation = useRef(null);
+  const valueAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: valueOpacity.value
+  }));
   useEffect(() => {
     if (previousValue.current === value) return;
     previousValue.current = value;
     valueAnimation.current?.stop();
     if (!motion.enabled) {
-      valueOpacity.setValue(1);
+      valueOpacity.value = 1;
       return;
     }
-    valueOpacity.setValue(0);
+    valueOpacity.value = 0;
     valueAnimation.current = motion.timing(valueOpacity, 1, {
       duration: "fast",
       easing: "decelerate"
@@ -65,24 +82,33 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
     backgroundColor: tileColors.iconFill
   }], [theme, tileColors]);
   const bodyStyle = useMemo(() => statTileBodyStructure(theme), [theme]);
-  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
-    fontSize: theme.fontSizes.sm,
+  const labelTypography = useMemo(() => resolveTextStyle(theme, "caption", {
+    color: "muted",
+    weight: "medium"
+  }), [theme]);
+  const labelStyle = useMemo(() => [labelTypography, {
     color: tileColors.label
-  }], [theme, tileColors]);
-  const valueStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-    fontSize: theme.fontSizes["2xl"],
+  }], [labelTypography, tileColors.label]);
+  const valueTypography = useMemo(() => resolveTextStyle(theme, "title", {
+    weight: "semibold"
+  }), [theme]);
+  const valueStyle = useMemo(() => [valueTypography, {
     color: tileColors.valueColor
-  }, {
-    opacity: valueOpacity
-  }], [theme, tileColors, valueOpacity]);
+  }], [valueTypography, tileColors.valueColor]);
+  const deltaColor = useMemo(() => resolveStatTileDeltaColor(theme.colors, trend, goodDirection), [theme.colors, trend, goodDirection]);
+  const deltaStyle = useMemo(() => [resolveTextStyle(theme, "caption", {
+    weight: "medium"
+  }), {
+    color: deltaColor
+  }], [theme, deltaColor]);
   const body = /*#__PURE__*/_jsxs(_Fragment, {
     children: [icon !== undefined && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-icon`,
       style: iconStyle,
-      children: icon
+      children: renderNodeSlot(icon, labelStyle)
     }), /*#__PURE__*/_jsxs(View, {
       style: bodyStyle,
-      children: [/*#__PURE__*/_jsx(Text, {
+      children: [/*#__PURE__*/_jsx(RNText, {
         numberOfLines: 1,
         style: labelStyle,
         children: label
@@ -90,11 +116,15 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
         width: VALUE_SKELETON_WIDTH,
         height: theme.fontSizes["2xl"],
         testID: testID === undefined ? undefined : `${testID}-skeleton`
-      }) : /*#__PURE__*/_jsx(Animated.Text, {
+      }) : /*#__PURE__*/_jsx(AnimatedText, {
         numberOfLines: 1,
-        style: valueStyle,
+        style: [valueStyle, valueAnimatedStyle],
         children: value
-      })]
+      }), delta !== undefined && !loading ? /*#__PURE__*/_jsx(RNText, {
+        numberOfLines: 1,
+        style: deltaStyle,
+        children: delta
+      }) : null]
     })]
   });
   if (!pressable) {
@@ -114,7 +144,7 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: a11y.accessibilityLabel,
     "aria-busy": a11y["aria-busy"],
-    onPress: onPress,
+    onPress: handlePress,
     onPressIn: press.onPressIn,
     onPressOut: press.onPressOut,
     style: pressableStyle,

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

@@ -6,6 +6,11 @@
  */
 
 import { createThemedVariants } from "../../core/style/index.js";
+export function resolveStatTileDeltaColor(colors, trend, goodDirection) {
+  if (trend === "flat") return colors.fg.muted;
+  const good = trend === "up" && goodDirection === "up" || trend === "down" && goodDirection === "down";
+  return good ? colors.status.success.solid : colors.status.danger.solid;
+}
 export function resolveStatTileColors(colors, tone) {
   const iconFill = tone === "accent" ? colors.accent.subtle : tone === "neutral" ? colors.bg.sunken : colors.status[tone].subtle;
   return {
@@ -36,6 +41,7 @@ export const statTileStructure = createThemedVariants(theme => ({
     alignItems: "center",
     columnGap: theme.space[3],
     borderRadius: theme.radii.lg,
+    borderCurve: "continuous",
     padding: theme.space[4]
   }
 }));
@@ -44,6 +50,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/stat-tile/StatTileProps.js

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

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

@@ -21,6 +21,8 @@
 | `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`. |
 
@@ -32,6 +34,8 @@
 | `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. |
+| `visible` | `boolean` | `true` | Fades/slides out when `false`. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
 | `testID` | `string` | — | Forwarded to the outermost `View`. |
 
@@ -42,11 +46,16 @@
 - **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
+  `EmptyState.resolveEmptyStateAnnouncement`'s shape via `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.
+- The announcement is unconditional, so apps rendering these blocks directly (not through `Screen`'s
+  default slots) get it too.
 
 ## Performance
 
 Both exports wrapped in `React.memo`.
+
+## Motion
+
+Both blocks mount/unmount through `useEnterExit(visible)` plus Reanimated `FadeInDown.springify()` /
+`FadeOut`, each carrying `ReduceMotion.System`.

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

@@ -22,14 +22,15 @@
  */
 
 import { memo, useMemo } from "react";
-import { Animated, StyleSheet, Text, View } from "react-native";
+import { StyleSheet, Text, View } from "react-native";
+import Reanimated, { FadeInDown, FadeOut, LinearTransition, 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 } from "./StateBlock.variants.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";
@@ -37,6 +38,7 @@ export const LoadingState = /*#__PURE__*/memo(function LoadingState({
   message,
   size = "md",
   tone = "accent",
+  fill = false,
   visible = true,
   style,
   testID
@@ -49,23 +51,28 @@ export const LoadingState = /*#__PURE__*/memo(function LoadingState({
   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 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(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
-    })]
+  return /*#__PURE__*/_jsx(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    exiting: FadeOut.reduceMotion(ReduceMotion.System),
+    layout: LinearTransition.reduceMotion(ReduceMotion.System),
+    children: /*#__PURE__*/_jsxs(Reanimated.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({
@@ -73,6 +80,7 @@ export const ErrorState = /*#__PURE__*/memo(function ErrorState({
   title,
   description,
   action,
+  fill = false,
   visible = true,
   style,
   testID
@@ -85,7 +93,7 @@ export const ErrorState = /*#__PURE__*/memo(function ErrorState({
   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 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
@@ -95,32 +103,37 @@ export const ErrorState = /*#__PURE__*/memo(function ErrorState({
     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"
-    })]
+  return /*#__PURE__*/_jsx(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    exiting: FadeOut.reduceMotion(ReduceMotion.System),
+    layout: LinearTransition.reduceMotion(ReduceMotion.System),
+    children: /*#__PURE__*/_jsxs(Reanimated.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({

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

@@ -52,4 +52,11 @@ export const errorStateStructure = createThemedVariants(theme => ({
     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/StateBlockProps.js

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

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

@@ -113,3 +113,5 @@ layout lives in `StyleSheet.create`.
 - 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.
+
+A step advance also fires `useHaptics().selection()`, skipped under reduced motion.

package/lib/module/modules/stepper/Stepper.js

@@ -13,13 +13,16 @@
  * label rather than centered between two circles' worth of connector.
  *
  * Advancing `activeStep` settles the newly-active circle with a small scale (`core/motion`). One
- * shared `Animated.Value` drives it — the connectors change colour, which cannot run on the native
- * driver, so they stay static.
+ * shared value drives it — the connectors change colour, which cannot run on the native driver, so
+ * they stay static.
  */
 
 import { memo, useEffect, useMemo, useRef } from "react";
-import { Animated, StyleSheet, Text, View } from "react-native";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { StyleSheet, Text, View } from "react-native";
+import Reanimated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
+import { useReducedMotion } from "../../core/a11y/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { useMotion, useAnimatedValue } from "../../core/motion/index.js";
 import { useTheme } from "../../theme/hooks.js";
 import { resolveStepCircleColors, resolveStepConnectorColor, resolveStepLabelColor, resolveStepState, resolveStepperAccessibility, stepCircleStructure, stepConnectorLineStructure, stepLabelStructure } from "./Stepper.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -42,13 +45,14 @@ const StepColumn = /*#__PURE__*/memo(function StepColumn({
   const trailingStyle = useMemo(() => [stepConnectorLineStructure(), {
     backgroundColor: trailingConnector
   }], [trailingConnector]);
-  const circleStyle = useMemo(() => [stepCircleStructure(theme), {
+  const circleStatic = useMemo(() => [stepCircleStructure(theme), {
     backgroundColor: circleFill
-  }, advance === null ? null : {
+  }], [theme, circleFill]);
+  const circleMotion = useAnimatedStyle(() => advance === null ? {} : {
     transform: [{
-      scale: advance
+      scale: interpolate(advance.value, [0, 1], [ADVANCE_SCALE, 1])
     }]
-  }], [theme, circleFill, advance]);
+  });
   const numberStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
     fontSize: theme.fontSizes.sm,
     color: circleText
@@ -57,13 +61,15 @@ const StepColumn = /*#__PURE__*/memo(function StepColumn({
     fontSize: theme.fontSizes.xs,
     color: labelColor
   }], [theme, labelColor]);
+  const Circle = advance === null ? View : Reanimated.View;
+  const circleStyle = advance === null ? circleStatic : [circleStatic, circleMotion];
   return /*#__PURE__*/_jsxs(View, {
     style: styles.column,
     children: [/*#__PURE__*/_jsxs(View, {
       style: styles.connectorRow,
       children: [/*#__PURE__*/_jsx(View, {
         style: leadingStyle
-      }), /*#__PURE__*/_jsx(Animated.View, {
+      }), /*#__PURE__*/_jsx(Circle, {
         testID: testID,
         style: circleStyle,
         children: /*#__PURE__*/_jsx(Text, {
@@ -88,6 +94,8 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const haptics = useHaptics();
+  const reducedMotion = useReducedMotion();
   const a11y = resolveStepperAccessibility({
     steps,
     activeStep
@@ -100,12 +108,11 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
     running.current?.stop();
     const previous = lastStep.current;
     lastStep.current = activeStep;
-    // `motion` is a dep, so a mid-session reduce-motion change re-runs this — neither that nor the
-    // first render is an advance, and re-pulsing a step the user never left would be a lie.
     if (!motion.enabled || previous === null || previous === activeStep) {
-      advance.setValue(1);
+      advance.value = 1;
     } else {
-      advance.setValue(0);
+      if (!reducedMotion) haptics.selection();
+      advance.value = 0;
       running.current = motion.timing(advance, 1, {
         duration: "fast",
         easing: "decelerate"
@@ -113,12 +120,8 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
       running.current.start();
     }
     return () => running.current?.stop();
-  }, [activeStep, motion, advance]);
+  }, [activeStep, motion, advance, reducedMotion, haptics]);
   useEffect(() => () => running.current?.stop(), []);
-  const advanceScale = useMemo(() => advance.interpolate({
-    inputRange: [0, 1],
-    outputRange: [ADVANCE_SCALE, 1]
-  }), [advance]);
   const rootStyle = useMemo(() => [styles.row, style], [style]);
   return /*#__PURE__*/_jsx(View, {
     testID: testID,
@@ -132,8 +135,6 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
     children: steps.map((step, index) => {
       const state = resolveStepState(index, activeStep);
       const circleColors = resolveStepCircleColors(theme.colors, state);
-      // No segment exists before the first circle or after the last — a transparent spacer keeps
-      // every circle centered in its column via the same left/right flex split as every other one.
       const leadingConnector = index === 0 ? "transparent" : resolveStepConnectorColor(theme.colors, index - 1, activeStep);
       const trailingConnector = index === lastIndex ? "transparent" : resolveStepConnectorColor(theme.colors, index, activeStep);
       return /*#__PURE__*/_jsx(StepColumn, {
@@ -145,7 +146,7 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
         labelColor: resolveStepLabelColor(theme.colors, state),
         leadingConnector: leadingConnector,
         trailingConnector: trailingConnector,
-        advance: index === activeStep ? advanceScale : null,
+        advance: index === activeStep ? advance : null,
         testID: testID === undefined ? undefined : `${testID}-circle-${index}`
       }, index);
     })

package/lib/module/modules/stepper/Stepper.variants.js

@@ -19,7 +19,9 @@
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants, createThemedTextVariants, createVariants } from "../../core/style/index.js";
+export { MIN_TOUCH_TARGET };
 /**
  * Visual diameter of a step's numbered circle, in dp. Not a touch target — Stepper is a v1
  * DISPLAY-only component with no `onPress` (no `onStepPress` either — see `StepperProps`), so the

package/lib/module/modules/stepper/StepperProps.js

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

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

@@ -0,0 +1,57 @@
+# surface/ — the primitive every other container is built on
+
+`Surface` is a themed box: a background role, an optional border role, a radius token, a padding
+token and an elevation rung. It renders no text, takes no press hook, and adds no semantics — where
+`Card` is an opinionated container with variants, `Surface` is the unopinionated one you reach for
+when the composition is yours.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Surface.tsx` | Resolves colours, padding and elevation; `renderNodeSlot` on children; `style` last. |
+| `Surface.variants.ts` | Pure resolvers (`resolveSurfaceColors`, `resolveSurfacePadding`, `resolveSurfaceElevation`) + `surfaceStructure`. No React. |
+| `index.ts` | Public surface: `Surface`, `Box` (an alias for it), `SurfaceProps`, and the role/token aliases. |
+| `__tests__/Surface.test.ts` | Pure: background and border roles map, unset roles are omitted. |
+| `__tests__/Surface.render.test.tsx` | Render: children compose, `testID` forwards, consumer `style` applies last. |
+| `__tests__/SurfaceElevation.test.tsx` | Pure: the `ElevationLevel` → `FloatingLevel` mapping, including the two rungs the platform layer does not implement. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `background` | `BgRole` | — | Any `colors.bg.*` role. Omitted means transparent. |
+| `border` | `BorderRole` | — | Any `colors.border.*` role. Omitted means no border. |
+| `radius` | `RadiusToken` | — | A `theme.radii` key. |
+| `elevation` | `ElevationLevel` | — | See below — the union is wider than the platform layer implements. |
+| `padding` | `SpaceToken` | — | A `theme.space` key. |
+| `children` | `ReactNode` | — | Rendered through `renderNodeSlot`, so bare strings inherit `fg.default`. |
+| `style` | `LayoutStyle` | — | Layout only, applied last, exactly once. |
+| `testID` | `string` | — | Forwarded to the root `View`. |
+
+## `elevation` spans a wider union than the platform implements
+
+`SurfaceProps.elevation` is typed `ElevationLevel` — `none | sm | base | md | lg`, the full primitive
+ladder. `floatingSurface.native.ts` implements `FloatingLevel`, which is only `sm | md | lg`. Two
+rungs therefore have no direct platform equivalent and `resolveSurfaceElevation` maps them
+explicitly through `SURFACE_FLOATING_LEVEL`:
+
+| `elevation` | Renders as |
+|---|---|
+| unset | no shadow, no tonal lift |
+| `none` | no shadow, no tonal lift — the same as unset, stated explicitly |
+| `base` | the `sm` rung — the lightest implemented shadow |
+| `sm` / `md` / `lg` | themselves |
+
+`base` rounds **down** to `sm` rather than up to `md`: it sits between the two on the primitive
+ladder, and under-shadowing a surface is the recoverable error. `SURFACE_FLOATING_LEVEL` is declared
+`satisfies Record<Exclude<ElevationLevel, "none">, FloatingLevel>`, so adding a rung to the primitive
+ladder is a type error here until it is mapped — the mapping cannot silently fall through again.
+
+`__tests__/SurfaceElevation.test.tsx` pins every rung, so a new `ElevationLevel` cannot silently
+fall through to the heaviest shadow.
+
+## Performance
+
+`Surface` is `React.memo`'d and resolves its root style through a `useMemo` keyed on the theme and
+every appearance prop. The resolvers in `Surface.variants.ts` stay pure and hook-free.

package/lib/module/modules/surface/Surface.js

@@ -0,0 +1,47 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveSurfaceColors, resolveSurfaceElevation, resolveSurfacePadding, surfaceStructure } from "./Surface.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function SurfaceImpl({
+  background,
+  border,
+  radius,
+  elevation,
+  padding,
+  children,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const rootStyle = useMemo(() => {
+    const colors = resolveSurfaceColors(theme.colors, background, border);
+    const pad = resolveSurfacePadding(theme, padding);
+    const shadow = resolveSurfaceElevation(theme, elevation);
+    return [surfaceStructure(theme), colors.background !== undefined && {
+      backgroundColor: colors.background
+    }, border !== undefined && {
+      borderColor: colors.border,
+      borderWidth: theme.borderWidths.thin
+    }, radius !== undefined && {
+      borderRadius: theme.radii[radius]
+    }, pad !== undefined && {
+      padding: pad
+    }, shadow, style];
+  }, [theme, background, border, radius, elevation, padding, style]);
+  const childrenSlotStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: rootStyle,
+    children: renderNodeSlot(children, childrenSlotStyle)
+  });
+}
+export const Surface = /*#__PURE__*/memo(SurfaceImpl);
+export const Box = Surface;
+//# sourceMappingURL=Surface.js.map

package/lib/module/modules/surface/Surface.variants.js

@@ -0,0 +1,33 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/floatingSurface.native.js";
+export function resolveSurfaceColors(colors, background, border) {
+  return {
+    background: background === undefined ? undefined : colors.bg[background],
+    border: border === undefined ? undefined : colors.border[border]
+  };
+}
+export function resolveSurfacePadding(theme, padding) {
+  return padding === undefined ? undefined : theme.space[padding];
+}
+const SURFACE_FLOATING_LEVEL = {
+  sm: "sm",
+  base: "sm",
+  md: "md",
+  lg: "lg"
+};
+export function resolveSurfaceElevation(theme, elevation) {
+  if (elevation === undefined || elevation === "none") return undefined;
+  const level = SURFACE_FLOATING_LEVEL[elevation];
+  return {
+    backgroundColor: floatingBackground(theme, level),
+    ...floatingSurfaceStyle(theme, level)
+  };
+}
+export const surfaceStructure = createThemedVariants(_theme => ({
+  base: {
+    borderCurve: "continuous"
+  }
+}));
+//# sourceMappingURL=Surface.variants.js.map