pixelize-native-library 1.2.0 → 1.2.1

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

@@ -6,10 +6,66 @@
  */
 
 import { memo, useCallback, useMemo, useState } from "react";
-import { Pressable, Text, View } from "react-native";
+import { Platform, Pressable, Text, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
 import { resolveActiveStageIndex, resolveStageAccessibilityLabel, resolveStageAccessibilityState, resolveStageProgressAccessibility, resolveStageProgressColors, resolveStageState, stageBarStructure, stageFocusRingStructure, stagePillStructure, stageProgressRowStructure, stageStepperCircleStructure, STAGE_PILL_HIT_SLOP, STAGE_STEPPER_HIT_SLOP } from "./StageProgress.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+function fillFor(state, palette) {
+  if (state === "active") return palette.activeFill;
+  return state === "completed" ? palette.completedFill : palette.upcomingFill;
+}
+function textFor(state, palette) {
+  if (state === "active") return palette.activeText;
+  return state === "completed" ? palette.completedText : palette.upcomingText;
+}
+const StagePressable = /*#__PURE__*/memo(function StagePressable({
+  disabled,
+  a11yLabel,
+  a11yState,
+  hitSlop,
+  focusRingStyle,
+  focusRingTestID,
+  focused,
+  onPress,
+  onFocus,
+  onBlur,
+  children
+}) {
+  const theme = useTheme();
+  const press = usePressState(disabled);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android" || disabled) return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: true
+    };
+  }, [theme.mode, disabled]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
+    accessibilityRole: "button",
+    accessibilityLabel: a11yLabel,
+    "aria-current": a11yState["aria-current"],
+    accessibilityState: a11yState.accessibilityState,
+    "aria-disabled": a11yState["aria-disabled"],
+    hitSlop: hitSlop,
+    android_ripple: androidRipple,
+    onPress: onPress,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    onFocus: onFocus,
+    onBlur: onBlur,
+    style: press.animatedStyle,
+    children: [focused && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      testID: focusRingTestID,
+      style: focusRingStyle
+    }), children]
+  });
+});
 export const StageProgress = /*#__PURE__*/memo(function StageProgress({
   stages,
   value,
@@ -22,8 +78,7 @@ export const StageProgress = /*#__PURE__*/memo(function StageProgress({
   const theme = useTheme();
   const palette = resolveStageProgressColors(theme.colors);
   const activeIndex = resolveActiveStageIndex(stages, value);
-  // Which interactive stage holds keyboard/AT focus. One value rather than per-stage state: only one
-  // stage can be focused, and the stages are rendered inline (a hook per stage is not an option).
+  // Which interactive stage holds keyboard/AT focus — one value, since only one stage can be focused.
   const [focusedStageId, setFocusedStageId] = useState(null);
   const handlePress = useCallback((stageId, disabled) => {
     if (readOnly || disabled || onStagePress === undefined) return;
@@ -33,13 +88,12 @@ export const StageProgress = /*#__PURE__*/memo(function StageProgress({
     if (variant === "bar") {
       return stages.map((stage, index) => {
         const state = resolveStageState(index, activeIndex, true);
-        const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
         // No label per segment: the container announces the whole track as one progressbar
         // (`resolveStageProgressAccessibility`), so a per-segment label would read four times over.
         return /*#__PURE__*/_jsx(View, {
           testID: testID ? `${testID}-bar-${stage.id}` : undefined,
           style: [stageBarStructure(theme), {
-            backgroundColor: fill
+            backgroundColor: fillFor(state, palette)
           }]
         }, stage.id);
       });
@@ -47,22 +101,20 @@ export const StageProgress = /*#__PURE__*/memo(function StageProgress({
     if (variant === "stepper") {
       return stages.map((stage, index) => {
         const state = resolveStageState(index, activeIndex, true);
-        const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
-        const text = state === "active" ? palette.activeText : state === "completed" ? palette.completedText : palette.upcomingText;
         const node = /*#__PURE__*/_jsxs(View, {
           style: {
             alignItems: "center",
             minWidth: 64
           },
           children: [/*#__PURE__*/_jsx(View, {
-            style: [stageStepperCircleStructure(theme), {
-              backgroundColor: fill,
-              borderColor: palette.track
+            testID: testID ? `${testID}-stepper-${stage.id}` : undefined,
+            style: [stageStepperCircleStructure(theme), theme.elevation.sm, {
+              backgroundColor: fillFor(state, palette)
             }],
             children: /*#__PURE__*/_jsx(Text, {
               style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
                 fontSize: theme.fontSizes.sm,
-                color: text
+                color: textFor(state, palette)
               }],
               children: index + 1
             })
@@ -81,46 +133,42 @@ export const StageProgress = /*#__PURE__*/memo(function StageProgress({
         if (readOnly || stage.disabled) return /*#__PURE__*/_jsx(View, {
           accessible: true,
           accessibilityLabel: a11yLabel,
-          "aria-selected": a11yState["aria-selected"],
+          "aria-current": a11yState["aria-current"],
+          accessibilityState: a11yState.accessibilityState,
           "aria-disabled": a11yState["aria-disabled"],
           children: node
         }, stage.id);
-        return /*#__PURE__*/_jsxs(Pressable, {
-          accessibilityRole: "button",
-          accessibilityLabel: a11yLabel,
-          "aria-selected": a11yState["aria-selected"],
-          "aria-disabled": a11yState["aria-disabled"],
+        return /*#__PURE__*/_jsx(StagePressable, {
+          disabled: false,
+          a11yLabel: a11yLabel,
+          a11yState: a11yState,
           hitSlop: STAGE_STEPPER_HIT_SLOP,
+          focused: focusedStageId === stage.id,
+          focusRingTestID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
+          focusRingStyle: [stageFocusRingStructure(theme, {
+            variant: "stepper"
+          }), {
+            borderColor: theme.colors.border.focus
+          }],
           onPress: () => handlePress(stage.id, stage.disabled),
           onFocus: () => setFocusedStageId(stage.id),
           onBlur: () => setFocusedStageId(current => current === stage.id ? null : current),
-          children: [focusedStageId === stage.id && /*#__PURE__*/_jsx(View, {
-            pointerEvents: "none",
-            testID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
-            style: [stageFocusRingStructure(theme, {
-              variant: "stepper"
-            }), {
-              borderColor: theme.colors.border.focus
-            }]
-          }), node]
+          children: node
         }, stage.id);
       });
     }
     return stages.map((stage, index) => {
       const state = resolveStageState(index, activeIndex, true);
-      const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
-      const text = state === "active" ? palette.activeText : state === "completed" ? palette.completedText : palette.upcomingText;
       const pill = /*#__PURE__*/_jsx(View, {
         testID: testID ? `${testID}-pill-${stage.id}` : undefined,
-        style: [stagePillStructure(theme), {
-          backgroundColor: fill,
-          borderColor: palette.track
+        style: [stagePillStructure(theme), theme.elevation.sm, {
+          backgroundColor: fillFor(state, palette)
         }],
         children: /*#__PURE__*/_jsx(Text, {
           numberOfLines: 1,
           style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
             fontSize: theme.fontSizes.sm,
-            color: text
+            color: textFor(state, palette)
           }],
           children: stage.label
         })
@@ -130,28 +178,27 @@ export const StageProgress = /*#__PURE__*/memo(function StageProgress({
       if (readOnly || stage.disabled) return /*#__PURE__*/_jsx(View, {
         accessible: true,
         accessibilityLabel: a11yLabel,
-        "aria-selected": a11yState["aria-selected"],
+        "aria-current": a11yState["aria-current"],
+        accessibilityState: a11yState.accessibilityState,
         "aria-disabled": a11yState["aria-disabled"],
         children: pill
       }, stage.id);
-      return /*#__PURE__*/_jsxs(Pressable, {
-        accessibilityRole: "button",
-        accessibilityLabel: a11yLabel,
-        "aria-selected": a11yState["aria-selected"],
-        "aria-disabled": a11yState["aria-disabled"],
+      return /*#__PURE__*/_jsx(StagePressable, {
+        disabled: false,
+        a11yLabel: a11yLabel,
+        a11yState: a11yState,
         hitSlop: STAGE_PILL_HIT_SLOP,
+        focused: focusedStageId === stage.id,
+        focusRingTestID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
+        focusRingStyle: [stageFocusRingStructure(theme, {
+          variant: "pill"
+        }), {
+          borderColor: theme.colors.border.focus
+        }],
         onPress: () => handlePress(stage.id, stage.disabled),
         onFocus: () => setFocusedStageId(stage.id),
         onBlur: () => setFocusedStageId(current => current === stage.id ? null : current),
-        children: [focusedStageId === stage.id && /*#__PURE__*/_jsx(View, {
-          pointerEvents: "none",
-          testID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
-          style: [stageFocusRingStructure(theme, {
-            variant: "pill"
-          }), {
-            borderColor: theme.colors.border.focus
-          }]
-        }), pill]
+        children: pill
       }, stage.id);
     });
   }, [stages, variant, activeIndex, palette, theme, testID, readOnly, handlePress, focusedStageId]);

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

@@ -55,13 +55,16 @@ 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.
+ * Flat `aria-current` for web + explicit `accessibilityState` for native — see the field comments
+ * above for why this pair (not a single flat prop) is required here specifically.
  */
 export function resolveStageAccessibilityState(state, disabled) {
+  const active = state === "active";
   return {
-    "aria-selected": state === "active",
+    "aria-current": active ? "step" : undefined,
+    accessibilityState: {
+      selected: active
+    },
     "aria-disabled": disabled === true
   };
 }
@@ -90,8 +93,7 @@ export function resolveStageProgressColors(colors) {
     completedFill: colors.status.success.subtle,
     completedText: colors.status.success.text,
     upcomingFill: colors.bg.sunken,
-    upcomingText: colors.fg.muted,
-    track: colors.border.default
+    upcomingText: colors.fg.muted
   };
 }
 export const stageProgressRowStructure = createThemedVariants(theme => ({
@@ -107,7 +109,7 @@ export const stagePillStructure = createThemedVariants(theme => ({
     paddingHorizontal: theme.space[3],
     paddingVertical: theme.space[2],
     borderRadius: theme.radii.full,
-    borderWidth: theme.borderWidths.thin,
+    borderCurve: "continuous",
     minWidth: 72,
     minHeight: STAGE_PILL_MIN_HEIGHT,
     alignItems: "center",
@@ -133,10 +135,12 @@ export const stageFocusRingStructure = createThemedVariants(theme => ({
   variants: {
     variant: {
       pill: {
-        borderRadius: theme.radii.full
+        borderRadius: theme.radii.full,
+        borderCurve: "continuous"
       },
       stepper: {
-        borderRadius: theme.radii.base
+        borderRadius: theme.radii.md,
+        borderCurve: "continuous"
       }
     }
   },
@@ -148,7 +152,8 @@ export const stageBarStructure = createThemedVariants(theme => ({
   base: {
     flex: 1,
     height: 8,
-    borderRadius: theme.radii.full
+    borderRadius: theme.radii.full,
+    borderCurve: "continuous"
   }
 }));
 export const stageStepperCircleStructure = createThemedVariants(theme => ({
@@ -156,9 +161,9 @@ export const stageStepperCircleStructure = createThemedVariants(theme => ({
     width: STAGE_STEPPER_CIRCLE,
     height: STAGE_STEPPER_CIRCLE,
     borderRadius: theme.radii.full,
+    borderCurve: "continuous",
     alignItems: "center",
-    justifyContent: "center",
-    borderWidth: theme.borderWidths.thin
+    justifyContent: "center"
   }
 }));
 //# sourceMappingURL=StageProgress.variants.js.map

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

@@ -49,3 +49,5 @@ Wrapped in `React.memo`; the Pressable style function is `useCallback`'d.
 - 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.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.

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

@@ -6,10 +6,11 @@
  */
 
 import { memo, useEffect, useMemo, useRef } from "react";
-import { Animated, Pressable, Text, View } from "react-native";
+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;
@@ -65,16 +66,20 @@ 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"],
-    color: tileColors.valueColor
-  }, {
+  }], [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, valueOpacity]);
   const body = /*#__PURE__*/_jsxs(_Fragment, {
     children: [icon !== undefined && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-icon`,
@@ -82,7 +87,7 @@ export const StatTile = /*#__PURE__*/memo(function StatTile({
       children: icon
     }), /*#__PURE__*/_jsxs(View, {
       style: bodyStyle,
-      children: [/*#__PURE__*/_jsx(Text, {
+      children: [/*#__PURE__*/_jsx(RNText, {
         numberOfLines: 1,
         style: labelStyle,
         children: label

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

@@ -36,6 +36,7 @@ export const statTileStructure = createThemedVariants(theme => ({
     alignItems: "center",
     columnGap: theme.space[3],
     borderRadius: theme.radii.lg,
+    borderCurve: "continuous",
     padding: theme.space[4]
   }
 }));
@@ -44,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

@@ -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,7 @@
 | `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`. |
 

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, 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,13 +51,14 @@ 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, {
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
     testID: testID,
     style: rootStyle,
     children: [/*#__PURE__*/_jsx(Spinner, {
@@ -73,6 +76,7 @@ export const ErrorState = /*#__PURE__*/memo(function ErrorState({
   title,
   description,
   action,
+  fill = false,
   visible = true,
   style,
   testID
@@ -85,7 +89,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,7 +99,8 @@ export const ErrorState = /*#__PURE__*/memo(function ErrorState({
     color: colors.description
   }], [theme, colors]);
   if (!enterExit.mounted) return null;
-  return /*#__PURE__*/_jsxs(Animated.View, {
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
     testID: testID,
     style: rootStyle,
     children: [/*#__PURE__*/_jsx(View, {

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/surface/MODULE.md

@@ -0,0 +1,59 @@
+# 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` | The component. Resolves colours, padding and elevation, applies inline over structure, `style` last. |
+| `Surface.variants.ts` | Pure resolvers (`resolveSurfaceColors`, `resolveSurfacePadding`, `resolveSurfaceElevation`) + `surfaceStructure`. No React. |
+| `index.ts` | Public surface: `Surface`, `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. |
+| `style` | `LayoutStyle` | — | Layout only, applied last, exactly once. |
+
+## `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.
+
+## Known gaps
+
+`elevation="none"` and `elevation="base"` both previously resolved to `lg`, the heaviest shadow in
+the ladder — a ternary whose `else` branch caught every unhandled rung. Asking a surface to be flat
+gave it the most pronounced shadow available. `__tests__/SurfaceElevation.test.tsx` pins each rung so
+the fall-through cannot return.
+
+## 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,42 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+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]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: rootStyle,
+    children: children
+  });
+}
+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

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

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

package/lib/module/modules/swipeable-row/MODULE.md

@@ -2,6 +2,13 @@
 
 Swipe-to-reveal row actions via gesture-handler + reanimated.
 
+## Round 5 tonal
+
+No decorative container border here — `swipeableRowStructure` was already borderless; the only
+border is the real focus ring (kept). Action buttons gained `usePressState`'s scale/opacity + overlay
+feedback and `android_ripple`, matching `Button`/`BottomNavTab` — previously a plain `Pressable` with
+no press feedback at all.
+
 ## Motion contract
 
 - The row follows the finger on the **UI thread**: a single `Gesture.Pan()` writes a `translateX`
@@ -118,3 +125,5 @@ Known gaps:
   `onPress`), and the button's own rendered touch-target size.
 - `SwipeableRow.motion.test.tsx` — both halves of the reduce-motion contract, with
   `withSpring`/`withTiming` mocked (a shared value written as a plain number proves nothing tweened).
+
+Uses `scheduleOnRN` from `react-native-worklets` where JS thread callbacks are required.