pixelize-native-library 1.0.7 → 1.2.1

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

@@ -11,13 +11,75 @@
  * length; the connector to the NEXT step is drawn as two identically-coloured halves — the trailing
  * half of this column, the leading half of the next — so a circle stays centered under its own
  * 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.
  */
 
-import { memo } from "react";
-import { StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+import { memo, useEffect, useMemo, useRef } from "react";
+import { Animated, StyleSheet, Text, View } from "react-native";
+import { useAnimatedValue, useMotion } 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";
+const ADVANCE_SCALE = 1.12;
+const StepColumn = /*#__PURE__*/memo(function StepColumn({
+  index,
+  label,
+  theme,
+  circleFill,
+  circleText,
+  labelColor,
+  leadingConnector,
+  trailingConnector,
+  advance,
+  testID
+}) {
+  const leadingStyle = useMemo(() => [stepConnectorLineStructure(), {
+    backgroundColor: leadingConnector
+  }], [leadingConnector]);
+  const trailingStyle = useMemo(() => [stepConnectorLineStructure(), {
+    backgroundColor: trailingConnector
+  }], [trailingConnector]);
+  const circleStyle = useMemo(() => [stepCircleStructure(theme), {
+    backgroundColor: circleFill
+  }, advance === null ? null : {
+    transform: [{
+      scale: advance
+    }]
+  }], [theme, circleFill, advance]);
+  const numberStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes.sm,
+    color: circleText
+  }], [theme, circleText]);
+  const labelStyle = useMemo(() => [stepLabelStructure(theme), theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.xs,
+    color: labelColor
+  }], [theme, labelColor]);
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.column,
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: styles.connectorRow,
+      children: [/*#__PURE__*/_jsx(View, {
+        style: leadingStyle
+      }), /*#__PURE__*/_jsx(Animated.View, {
+        testID: testID,
+        style: circleStyle,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: numberStyle,
+          children: index + 1
+        })
+      }), /*#__PURE__*/_jsx(View, {
+        style: trailingStyle
+      })]
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: label
+    })]
+  });
+});
 export const Stepper = /*#__PURE__*/memo(function Stepper({
   steps,
   activeStep,
@@ -25,59 +87,66 @@ export const Stepper = /*#__PURE__*/memo(function Stepper({
   testID
 }) {
   const theme = useTheme();
+  const motion = useMotion();
   const a11y = resolveStepperAccessibility({
     steps,
     activeStep
   });
   const lastIndex = steps.length - 1;
+  const advance = useAnimatedValue(1);
+  const running = useRef(null);
+  const lastStep = useRef(null);
+  useEffect(() => {
+    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);
+    } else {
+      advance.setValue(0);
+      running.current = motion.timing(advance, 1, {
+        duration: "fast",
+        easing: "decelerate"
+      });
+      running.current.start();
+    }
+    return () => running.current?.stop();
+  }, [activeStep, motion, advance]);
+  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,
     accessible: true,
     accessibilityRole: a11y.accessibilityRole,
-    accessibilityValue: a11y.accessibilityValue,
+    "aria-valuemin": a11y["aria-valuemin"],
+    "aria-valuemax": a11y["aria-valuemax"],
+    "aria-valuenow": a11y["aria-valuenow"],
     accessibilityLabel: a11y.accessibilityLabel,
-    style: [styles.row, style],
+    style: rootStyle,
     children: steps.map((step, index) => {
       const state = resolveStepState(index, activeStep);
       const circleColors = resolveStepCircleColors(theme.colors, state);
-      const labelColor = resolveStepLabelColor(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__*/_jsxs(View, {
-        style: styles.column,
-        children: [/*#__PURE__*/_jsxs(View, {
-          style: styles.connectorRow,
-          children: [/*#__PURE__*/_jsx(View, {
-            style: [stepConnectorLineStructure(), {
-              backgroundColor: leadingConnector
-            }]
-          }), /*#__PURE__*/_jsx(View, {
-            testID: testID === undefined ? undefined : `${testID}-circle-${index}`,
-            style: [stepCircleStructure(theme), {
-              backgroundColor: circleColors.fill
-            }],
-            children: /*#__PURE__*/_jsx(Text, {
-              style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-                fontSize: theme.fontSizes.sm,
-                color: circleColors.text
-              }],
-              children: index + 1
-            })
-          }), /*#__PURE__*/_jsx(View, {
-            style: [stepConnectorLineStructure(), {
-              backgroundColor: trailingConnector
-            }]
-          })]
-        }), /*#__PURE__*/_jsx(Text, {
-          numberOfLines: 1,
-          style: [stepLabelStructure(theme), theme.fontStyleForWeight(theme.fontWeights.medium), {
-            fontSize: theme.fontSizes.xs,
-            color: labelColor
-          }],
-          children: step.label
-        })]
+      return /*#__PURE__*/_jsx(StepColumn, {
+        index: index,
+        label: step.label,
+        theme: theme,
+        circleFill: circleColors.fill,
+        circleText: circleColors.text,
+        labelColor: resolveStepLabelColor(theme.colors, state),
+        leadingConnector: leadingConnector,
+        trailingConnector: trailingConnector,
+        advance: index === activeStep ? advanceScale : null,
+        testID: testID === undefined ? undefined : `${testID}-circle-${index}`
       }, index);
     })
   });

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

@@ -87,7 +87,9 @@ export function resolveStepConnectorColor(colors, index, activeStep) {
  * wording is unit-tested without a renderer; `Stepper.tsx` pairs this with `accessible` on the
  * container, the same collapsing idiom `Badge` uses for its icon + label). `activeStep` is
  * 0-indexed internally; the announcement surfaces the natural 1-based ordinal, and
- * `accessibilityValue` surfaces the raw 0-indexed `min`/`max`/`now` progress triple.
+ * the flat `aria-value*` triple surfaces the raw 0-indexed `min`/`max`/`now` progress. Flat rather
+ * than `accessibilityValue={{…}}`: RN's `View` folds 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 resolveStepperAccessibility(input) {
   const {
@@ -98,11 +100,9 @@ export function resolveStepperAccessibility(input) {
   const summary = `Step ${activeStep + 1} of ${steps.length}` + (activeLabel === undefined ? "" : `: ${activeLabel}`);
   return {
     accessibilityRole: "progressbar",
-    accessibilityValue: {
-      min: 0,
-      max: Math.max(steps.length - 1, 0),
-      now: activeStep
-    },
+    "aria-valuemin": 0,
+    "aria-valuemax": Math.max(steps.length - 1, 0),
+    "aria-valuenow": activeStep,
     accessibilityLabel: summary
   };
 }

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

@@ -0,0 +1,129 @@
+# swipeable-row/
+
+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`
+  shared value. Only `transform` is animated — never a layout property.
+- Settle (snap open / snap back) reads the global motion config via `useMotion()`:
+  `spring("snappy")` when the device tier can afford a spring, `withTiming(duration("fast"))` when
+  it cannot.
+- **Reduce motion / motion disabled** — `translateX` is assigned the target directly, no tween.
+- The in-flight settle is cancelled on unmount (`cancelAnimation`). Nothing gates unmount on an
+  animation completing.
+
+## Accessibility
+
+A swipe is invisible to assistive tech, so the actions would otherwise be unreachable (WCAG 2.1.1).
+
+- **The row declares one `accessibilityAction` per action** (`name: action.id`, `label:
+  action.label`, left tray first) plus `onAccessibilityAction` — the platform-native list-row model,
+  where the row is one accessibility element carrying custom actions. Running one settles the row
+  home and fires that action's `onPress`; an unknown `actionName` is a no-op.
+- **`accessible` is set only when the row has actions.** A container that isn't `accessible` reaches
+  neither the iOS trait nor Android's focus, so the custom actions would never surface. A row with
+  no actions gets no `accessible` prop at all — `accessible={false}` would *remove* a plain content
+  row from the tree.
+- **Both trays stay out of the accessibility tree** (`accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"`). They are absolutely positioned *before* the
+  content, so while they were exposed VoiceOver read "Archive, button. Delete, button." ahead of
+  every row's content, on every row, swiped open or not. The custom actions above are the complete
+  AT path; the trays are the sighted-touch affordance for the same set.
+- **Both of those props are native-only** — react-native-web implements neither (zero occurrences in
+  its dist) — so every action button also carries an explicit **`tabIndex={-1}`** (WCAG 2.4.3).
+  Without it RNW's `Pressable` defaults to `tabIndex={0}`: a 20-row list cost three Tab presses per
+  row, two landing on a button the content is painted over, where Enter fired a destructive action
+  the user never saw targeted. The button stays fully operable by press — only the tab stop is gone.
+- **Focus ring** (WCAG 2.4.7): an action draws a `border.focus` ring on focus, drawn *inside* its own
+  bounds — `swipeableRowStructure` clips to `overflow: "hidden"`, so the gap-outside ring
+  `Button`/`CopyButton` use would be cut off. Reachable today from a hardware keyboard on Android
+  only; see the known gaps below.
+
+### Tap affordance (WCAG 2.5.7 dragging movements, 2.5.1 pointer gestures)
+
+`accessibilityActions` is a screen-reader-only API — it does not satisfy 2.5.7, which requires a
+**single-pointer** alternative for a user who can see and tap but cannot perform a direction-dependent
+drag. Whenever the row has any action, it renders an always-visible `more-horizontal` icon `Button`
+(from `../button`), absolutely positioned at the trailing edge, on top of `children` — it never
+reflows consumer content, since `children` is opaque to this component. There is **no opt-out prop**:
+an opt-out would let a consumer silently reintroduce the exact conformance failure this fixes, for
+every row that used it.
+
+- **One action** → the button's `accessibilityLabel` is that action's own `label`, and pressing it
+  calls `runAction(id)` directly — the same function the drag and `accessibilityActions` both call.
+- **More than one** → the button (`accessibilityLabel="More actions"`) is composed as a `Menu`
+  trigger (from `../menu`, its public export only — `Menu.tsx` was not touched), listing every action
+  left-tray-first, each wired to `runAction(id)`. `SwipeableActionTone` doesn't fit `MenuItemTone`'s
+  `"default" | "danger"` union, so only `"danger"` maps through; every other tone reads as `"default"`.
+- **`variant="outline"`, not `"ghost"`** (unlike this same trigger shape in `BottomNav`): `children`'s
+  background is arbitrary and unpredictable, unlike a nav bar's controlled chrome, so the button needs
+  its own border to stay legible over whatever the consumer painted underneath. Known gap: a
+  photographic or otherwise busy background can still make it hard to see — no scrim token exists to
+  fix that without inventing one.
+- **Hidden from the accessibility tree** (`accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"` on its wrapper) — deliberately, not an oversight.
+  `accessibilityActions` above already gives AT users the identical set via the rotor/TalkBack menu;
+  exposing this too would be a second, differently-shaped path to the same actions, not a needed one.
+  This does NOT hide the opened `Menu` sheet itself: RN's `<Modal>` presents on its own native
+  surface, so it is a React child of the hidden wrapper but not an accessibility-tree descendant of it.
+- **`pointerEvents="box-none"` on the wrapper** so only the button's own small hit area intercepts
+  touch — the rest of the row's width stays available to the pan gesture underneath. This is the same
+  z-order trick the trays already use (plain `Pressable`s outside `GestureDetector`, resolved by
+  simple hit-testing, not gesture negotiation) — verified safe by that existing, working precedent.
+- **Consumer-visible on every existing `SwipeableRow`** — this renders on top of `children` for any
+  row that already passes `leftActions`/`rightActions`, no code change required to receive it. A
+  consumer whose own content already places something at the trailing edge (a chevron, a timestamp)
+  may see it overlap; there is no automatic reflow to avoid that, since `children` is opaque here.
+
+Known gaps:
+
+- The trays are hidden unconditionally, not only while closed. There is no JS-side open state —
+  `translateX` lives on the UI thread — and adding one would cost a re-render per gesture to
+  duplicate an operable path the custom actions already provide.
+- **On native there is no keyboard path to the actions at all.** `accessibilityActions` surfaces in
+  the VoiceOver rotor and the TalkBack menu, but an iPad Magic Keyboard or an Android hardware
+  keyboard reaches neither — the new tap affordance doesn't close this gap either, since it too is
+  hidden from AT (see above). A hardware-keyboard path would need to be a real tab stop instead.
+- The ring's `border.focus` grey is the token proven ≥ 3:1 against the **canvas**; over a saturated
+  action fill (`status.danger.solid`) that ratio is unmeasured (WCAG 2.4.11).
+
+## Performance
+
+- Action buttons are an extracted `React.memo` component; the row passes one stable `onRun(id)`
+  callback instead of allocating a closure per action.
+- Tone resolution, tray styles and label styles are memoized, so a parent re-render does not rebuild
+  them.
+
+## Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `children` | `ReactNode` | — |
+| `leftActions` | `readonly SwipeableRowAction[]` | `[]` |
+| `rightActions` | `readonly SwipeableRowAction[]` | `[]` |
+| `style` | `LayoutStyle` | — |
+| `testID` | `string` | — |
+
+`testID` seeds `${testID}-action-${action.id}` per action button and `-focus-ring` under that, plus
+`${testID}-more-affordance` (the tap-affordance wrapper), `${testID}-more` (its button) and
+`${testID}-more-menu` (the composed `Menu`, when there is more than one action).
+
+## Tests
+
+- `SwipeableRow.test.ts` — action-tone contrast over all 9 brands × both modes.
+- `SwipeableRow.render.test.tsx` — the accessibility-action contract, the hidden trays, and the tap
+  affordance: hidden-from-AT wrapper + `pointerEvents="box-none"`, the single-action direct-press
+  path, the multi-action `Menu` path (real rendered items, real dispatch to the pressed action's own
+  `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.