pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/select/Select.js

@@ -1,30 +1,124 @@
 "use strict";
 
 /**
- * Select — a trigger styled like an Input box (same size/border/focus-ring conventions) that opens
- * an option list in React Native's OWN `Modal`. Imported directly from `"react-native"` here on
- * purpose: this module must never depend on the library's own `Modal` COMPONENT (its rendered
- * output/behaviour) — Select still owns its option list's markup outright.
- *
- * The one deliberate exception is the web portal mechanism: `ModalPortalContext`/`renderWebPortal`
- * are a plain context + a stateless helper with no React-tree footprint of their own (not the
- * `Modal` component), so Select reads the same ones `Modal.tsx` reads to stay consistent once a
- * consumer opts in via `ModalPortalProvider` — see `../modal/ModalPortalContext.ts`.
+ * Select — a trigger styled like an Input box that opens an option list in React Native's OWN `Modal`.
  */
 
-import { memo, useContext, useState } from "react";
-import { Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { focusItemProps, useDismissOnEscape, useFocusTrap, useRovingKeys, useSpaceActivation } from "../../core/a11y/keyboard";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { VirtualList } from "../../core/list/index.js";
+import { useMotion, usePressMotion, useReveal } from "../../core/motion/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { withAlpha } from "../../core/gradient/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "../modal/ModalPortalContext.js";
 import { renderWebPortal } from "../modal/renderWebPortal";
-import { resolveSelectAccessibility, resolveSelectRowColors, resolveSelectTriggerColors, SELECT_ROW_ICON_SIZE, SELECT_SIZES, selectOverlayStructure, selectRowStructure, selectSheetStructure, selectTriggerStructure, selectTriggerValueStructure } from "./Select.variants.js";
+import { resolveSelectAccessibility, resolveSelectOptionLabelColor, resolveSelectRowColors, resolveSelectTriggerColors, SELECT_LISTBOX_ROLE, SELECT_OPTION_ROLE, SELECT_ROW_ICON_SIZE, SELECT_ROW_MIN_HEIGHT, SELECT_SIZES, selectOverlayStructure, selectRowLeadingStructure, selectRowStructure, selectSheetStructure, selectTriggerStructure, selectTriggerValueStructure } from "./Select.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const ICON_STROKE = 2;
-// Decorative dismiss scrim behind the sheet — a design constant, not a role token: it is neither
-// text nor an interactive boundary, so WCAG's contrast minimums don't apply to it.
 const BACKDROP_SCRIM = "#00000099";
+const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
+  option,
+  selected,
+  tabIndex,
+  theme,
+  rowColors,
+  onSelect,
+  testID
+}) {
+  const motion = useMotion();
+  const press = usePressMotion();
+  const handlePress = useCallback(() => onSelect(option), [onSelect, option]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
+  const rowRef = useRef(null);
+  const active = tabIndex === 0;
+
+  // The tabindex alone only names the tab stop — focus has to follow the arrows too, or the focus
+  // trap's Tab handler sees a focused row that is no longer tabbable and lets Tab leave the sheet.
+  useEffect(() => {
+    if (!active || Platform.OS !== "web") return;
+    rowRef.current?.focus();
+  }, [active]);
+
+  // `option` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  useSpaceActivation(rowRef, handlePress);
+  const checkOpacity = useRef(new Animated.Value(selected ? 1 : 0)).current;
+  const skipFirst = useRef(true);
+  const running = useRef(null);
+  useEffect(() => {
+    running.current?.stop();
+    // A row scrolled into view already-selected must snap, never fade.
+    if (skipFirst.current) {
+      skipFirst.current = false;
+      checkOpacity.setValue(selected ? 1 : 0);
+      return;
+    }
+    if (!motion.enabled) {
+      checkOpacity.setValue(selected ? 1 : 0);
+      return;
+    }
+    running.current = motion.timing(checkOpacity, selected ? 1 : 0, {
+      duration: "fast"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [selected, motion, checkOpacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const rowStructure = useMemo(() => selectRowStructure(theme), [theme]);
+  const leadingStructure = useMemo(() => selectRowLeadingStructure(theme), [theme]);
+  const rowStyle = useCallback(({
+    pressed
+  }) => ({
+    backgroundColor: pressed ? rowColors.pressedRow : rowColors.background
+  }), [rowColors]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flex: 1,
+    fontSize: theme.fontSizes.md,
+    color: resolveSelectOptionLabelColor(theme.colors, option.tone, option.customColors)
+  }], [theme, option.tone, option.customColors]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    ref: rowRef,
+    testID: testID ? `${testID}-option-${option.value}` : undefined,
+    accessibilityRole: SELECT_OPTION_ROLE,
+    "aria-selected": selected,
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    android_ripple: androidRipple,
+    style: rowStyle,
+    children: /*#__PURE__*/_jsxs(Animated.View, {
+      testID: testID ? `${testID}-option-${option.value}-content` : undefined,
+      style: [rowStructure, press.style],
+      children: [option.leading !== undefined && /*#__PURE__*/_jsx(View, {
+        style: leadingStructure,
+        children: option.leading
+      }), /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: labelStyle,
+        children: option.label
+      }), selected && /*#__PURE__*/_jsx(Animated.View, {
+        testID: testID ? `${testID}-option-${option.value}-check` : undefined,
+        style: {
+          opacity: checkOpacity
+        },
+        children: /*#__PURE__*/_jsx(Icon, {
+          name: "check",
+          size: SELECT_ROW_ICON_SIZE,
+          color: rowColors.icon,
+          strokeWidth: ICON_STROKE
+        })
+      })]
+    })
+  });
+});
 export const Select = /*#__PURE__*/memo(function Select({
   options,
   value,
@@ -37,82 +131,123 @@ export const Select = /*#__PURE__*/memo(function Select({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
   const portalContainer = useContext(ModalPortalContext);
   const [open, setOpen] = useState(false);
   const [focused, setFocused] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const sheetRef = useRef(null);
+  const reveal = useReveal(open);
   const spec = SELECT_SIZES[size];
-  const selectedOption = options.find(option => option.value === value);
+  const selectedIndex = useMemo(() => options.findIndex(option => option.value === value), [options, value]);
+  const selectedOption = selectedIndex === -1 ? undefined : options[selectedIndex];
   const isPlaceholder = selectedOption === undefined;
   const displayText = selectedOption?.label ?? placeholder ?? "";
-  const triggerColors = resolveSelectTriggerColors(theme.colors, focused || open);
-  const rowColors = resolveSelectRowColors(theme.colors);
-  const a11y = resolveSelectAccessibility({
+  const triggerColors = useMemo(() => resolveSelectTriggerColors(theme.colors, focused || open), [theme.colors, focused, open]);
+  const rowColors = useMemo(() => resolveSelectRowColors(theme.colors), [theme.colors]);
+  const a11y = useMemo(() => resolveSelectAccessibility({
     disabled,
     open
-  });
+  }), [disabled, open]);
   const accessibleName = label !== undefined ? displayText ? `${label}, ${displayText}` : label : undefined;
-  const openMenu = () => {
+  const openMenu = useCallback(() => {
     if (disabled) return;
+    // Opening lands the keyboard on the SELECTED option, not the first one (WCAG 2.4.3).
+    setActiveIndex(selectedIndex === -1 ? 0 : selectedIndex);
     setOpen(true);
-  };
-  const closeMenu = () => setOpen(false);
-  const selectOption = option => {
+  }, [disabled, selectedIndex]);
+  const closeMenu = useCallback(() => setOpen(false), []);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const selectOption = useCallback(option => {
     onValueChange(option.value);
-    closeMenu();
-  };
-  const sheet = /*#__PURE__*/_jsxs(_Fragment, {
+    setOpen(false);
+  }, [onValueChange]);
+  const typeaheadLabels = useMemo(() => options.map(option => option.label), [options]);
+
+  // Keyboard (web only — every hook below is a no-op on native, see `core/a11y/keyboard.ts`).
+  // No `onActivate`: RNW already presses on Enter regardless of role, and each row's own
+  // `useSpaceActivation` owns Space — passing it here would select twice.
+  useDismissOnEscape(open, closeMenu);
+  useFocusTrap(sheetRef, open);
+  useRovingKeys(sheetRef, open, {
+    count: options.length,
+    activeIndex,
+    onActiveIndexChange: setActiveIndex,
+    typeaheadLabels
+  });
+  const keyExtractor = useCallback(option => option.value, []);
+  const renderItem = useCallback(({
+    item: option,
+    index
+  }) => /*#__PURE__*/_jsx(SelectOptionRow, {
+    option: option,
+    selected: option.value === value,
+    tabIndex: focusItemProps(index, activeIndex).tabIndex,
+    theme: theme,
+    rowColors: rowColors,
+    onSelect: selectOption,
+    testID: testID
+  }), [value, activeIndex, theme, rowColors, selectOption, testID]);
+  const rootStyle = useMemo(() => [styles.container, containerStyle], [containerStyle]);
+  const triggerStyle = useMemo(() => [selectTriggerStructure(theme, {
+    size
+  }), {
+    backgroundColor: focused || open ? withAlpha(theme.colors.accent.solid, 0.04) : triggerColors.background,
+    borderColor: triggerColors.border,
+    borderWidth: focused || open ? 2 : theme.borderWidths.thin,
+    overflow: "hidden"
+  }, disabled && styles.dimmed], [theme, size, triggerColors, disabled, focused, open]);
+  const valueStructure = useMemo(() => selectTriggerValueStructure(theme), [theme]);
+  const overlayStructure = useMemo(() => selectOverlayStructure(theme), [theme]);
+  const floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.md);
+    void theme.elevatedSurfaces;
+    return {
+      backgroundColor: floatingBackground(theme, "md"),
+      ...floatingSurfaceStyle(theme, "md")
+    };
+  }, [theme]);
+  const sheetStyle = useMemo(() => [selectSheetStructure(theme), floatingStyle, {
+    overflow: "hidden"
+  }], [theme, floatingStyle]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
+  const fieldLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.muted,
+    marginBottom: theme.space[1]
+  }], [theme]);
+  const valueTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flexShrink: 1,
+    fontSize: spec.fontSize,
+    color: isPlaceholder ? triggerColors.placeholder : triggerColors.text
+  }], [theme, spec, isPlaceholder, triggerColors]);
+  const sheet = open ? /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: BACKDROP_SCRIM
-      }],
+      tabIndex: -1,
+      style: styles.backdrop,
       onPress: closeMenu
     }), /*#__PURE__*/_jsx(View, {
-      style: selectOverlayStructure(theme),
+      style: overlayStructure,
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(View, {
-        style: [selectSheetStructure(theme), {
-          backgroundColor: theme.colors.bg.surface
-        }],
-        children: /*#__PURE__*/_jsx(ScrollView, {
-          bounces: false,
-          children: options.map(option => {
-            const selected = option.value === value;
-            return /*#__PURE__*/_jsxs(Pressable, {
-              testID: testID ? `${testID}-option-${option.value}` : undefined,
-              accessibilityRole: "menuitem",
-              accessibilityState: {
-                selected
-              },
-              onPress: () => selectOption(option),
-              style: [selectRowStructure(theme), {
-                backgroundColor: rowColors.background
-              }],
-              children: [option.leading, /*#__PURE__*/_jsx(Text, {
-                numberOfLines: 1,
-                style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-                  flex: 1,
-                  fontSize: theme.fontSizes.md,
-                  color: rowColors.text
-                }],
-                children: option.label
-              }), selected && /*#__PURE__*/_jsx(Icon, {
-                name: "check",
-                size: SELECT_ROW_ICON_SIZE,
-                color: rowColors.icon,
-                strokeWidth: ICON_STROKE
-              })]
-            }, option.value);
-          })
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        ref: sheetRef,
+        style: [sheetStyle, reveal.style],
+        children: /*#__PURE__*/_jsx(VirtualList, {
+          data: options,
+          keyExtractor: keyExtractor,
+          renderItem: renderItem,
+          itemHeight: SELECT_ROW_MIN_HEIGHT,
+          accessibilityRole: SELECT_LISTBOX_ROLE
         })
       })
     })]
-  });
-
-  // Web portal opt-in — see Modal.tsx's identical branch + ModalPortalContext.ts. Every other case
-  // (native, or web with no ModalPortalProvider) renders through RN's own <Modal> below, unchanged.
+  }) : null;
   const menu = Platform.OS === "web" && portalContainer != null ? open ? renderWebPortal(/*#__PURE__*/_jsx(View, {
     style: StyleSheet.absoluteFill,
     pointerEvents: "box-none",
@@ -120,44 +255,35 @@ export const Select = /*#__PURE__*/memo(function Select({
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
-    animationType: reducedMotion ? "none" : "fade",
+    statusBarTranslucent: true,
+    navigationBarTranslucent: true,
+    animationType: "none",
     onRequestClose: closeMenu,
     children: sheet
   });
   return /*#__PURE__*/_jsxs(View, {
-    style: [styles.container, containerStyle],
+    style: rootStyle,
     children: [label !== undefined && /*#__PURE__*/_jsx(Text, {
-      style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
-        fontSize: theme.fontSizes.sm,
-        color: theme.colors.fg.muted,
-        marginBottom: theme.space[1]
-      }],
+      style: fieldLabelStyle,
       children: label
     }), /*#__PURE__*/_jsxs(Pressable, {
       testID: testID,
       accessibilityRole: a11y.accessibilityRole,
       accessibilityLabel: accessibleName,
-      accessibilityState: a11y.accessibilityState,
+      "aria-disabled": a11y["aria-disabled"],
+      "aria-expanded": a11y["aria-expanded"],
       disabled: a11y.disabled,
       onPress: openMenu,
-      onFocus: () => setFocused(true),
-      onBlur: () => setFocused(false),
+      onFocus: handleFocus,
+      onBlur: handleBlur,
       hitSlop: spec.hitSlop,
-      style: [selectTriggerStructure(theme, {
-        size
-      }), {
-        backgroundColor: triggerColors.background,
-        borderColor: triggerColors.border
-      }, disabled && styles.dimmed],
+      android_ripple: androidRipple,
+      style: triggerStyle,
       children: [/*#__PURE__*/_jsxs(View, {
-        style: selectTriggerValueStructure(theme),
+        style: valueStructure,
         children: [selectedOption?.leading, /*#__PURE__*/_jsx(Text, {
           numberOfLines: 1,
-          style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-            flexShrink: 1,
-            fontSize: spec.fontSize,
-            color: isPlaceholder ? triggerColors.placeholder : triggerColors.text
-          }],
+          style: valueTextStyle,
           children: displayText
         })]
       }), /*#__PURE__*/_jsx(Icon, {
@@ -173,9 +299,12 @@ const styles = StyleSheet.create({
   container: {
     alignSelf: "stretch"
   },
-  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
   dimmed: {
     opacity: 0.5
+  },
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BACKDROP_SCRIM
   }
 });
 //# sourceMappingURL=Select.js.map

package/lib/module/modules/select/Select.variants.js

@@ -14,32 +14,49 @@
  */
 
 import { createThemedVariants } from "../../core/style/index.js";
+/**
+ * The option list's container role. RN 0.86's role unions have no `listbox` — both `Role` and
+ * `AccessibilityRole` jump `list` → `listitem` → `log` — so the widening lives on this ONE audited
+ * line instead of a cast at the call site. It is a type gap, not a runtime one: `react-native-web`
+ * emits the string as the DOM `role` verbatim, and native maps roles it doesn't know to nothing.
+ */
+export const SELECT_LISTBOX_ROLE = "listbox";
+
+/**
+ * Each option row's role. `aria-selected` is only valid ARIA on `option`/`row`/`tab`/`gridcell`/
+ * `treeitem` — the row sits inside a `SELECT_LISTBOX_ROLE` container, so `option` is the
+ * textbook-correct pairing (2026-08 sweep fixed the row from the invalid `menuitem`+`aria-selected`
+ * combination). Same type gap as `SELECT_LISTBOX_ROLE`: RN 0.86's `AccessibilityRole` union has no
+ * `option` either.
+ */
+export const SELECT_OPTION_ROLE = "option";
+
 /** Same touch-target floor as Button (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
 export const MIN_TOUCH_TARGET = 44;
 const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
 export const SELECT_SIZES = {
   sm: {
-    height: 32,
+    height: 44,
     fontSize: 14,
     iconSize: 16,
-    hitSlop: slopFor(32)
+    hitSlop: slopFor(44)
   },
   md: {
-    height: 40,
+    height: 52,
     fontSize: 16,
     iconSize: 18,
-    hitSlop: slopFor(40)
+    hitSlop: slopFor(52)
   },
   lg: {
-    height: 48,
+    height: 56,
     fontSize: 18,
     iconSize: 20,
-    hitSlop: slopFor(48)
+    hitSlop: slopFor(56)
   }
 };
 
 /** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). */
-export const SELECT_ROW_MIN_HEIGHT = 44;
+export const SELECT_ROW_MIN_HEIGHT = 48;
 
 /** The "check" glyph beside the active row. Fixed — independent of the trigger's own `size`. */
 export const SELECT_ROW_ICON_SIZE = 18;
@@ -52,7 +69,7 @@ export const SELECT_ROW_ICON_SIZE = 18;
 export function resolveSelectTriggerColors(colors, focused) {
   return {
     background: colors.bg.surface,
-    border: focused ? colors.border.focus : colors.border.interactive,
+    border: focused ? colors.accent.solid : colors.border.interactive,
     text: colors.fg.default,
     placeholder: colors.fg.muted,
     icon: colors.fg.muted
@@ -62,9 +79,24 @@ export function resolveSelectRowColors(colors) {
   return {
     background: colors.bg.surface,
     text: colors.fg.default,
-    icon: colors.fg.default
+    icon: colors.fg.default,
+    pressedRow: colors.bg.sunken
   };
 }
+export function resolveSelectOptionLabelColor(colors, tone, customColors) {
+  if (tone === undefined) {
+    return colors.fg.default;
+  }
+  if (tone === "custom") {
+    if (!customColors) {
+      throw new Error('SelectOption tone="custom" requires customColors={{ bg, fg }}.');
+    }
+    return customColors.fg;
+  }
+  if (tone === "accent") return colors.accent.text;
+  if (tone === "neutral") return colors.fg.default;
+  return colors.status[tone].text;
+}
 /**
  * Derives the trigger's accessibility surface once, purely: `expanded` tracks whether the option
  * list is showing (WCAG 4.1.2 — a collapsible control must expose its expanded/collapsed state),
@@ -74,10 +106,8 @@ export function resolveSelectAccessibility(input) {
   const disabled = input.disabled === true;
   return {
     accessibilityRole: "button",
-    accessibilityState: {
-      disabled,
-      expanded: input.open
-    },
+    "aria-disabled": disabled,
+    "aria-expanded": input.open,
     disabled
   };
 }
@@ -92,7 +122,8 @@ export const selectTriggerStructure = createThemedVariants(theme => ({
     alignItems: "center",
     justifyContent: "space-between",
     columnGap: theme.space[2],
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     borderWidth: theme.borderWidths.thin
   },
   variants: {
@@ -138,10 +169,10 @@ export const selectOverlayStructure = createThemedVariants(theme => ({
 }));
 export const selectSheetStructure = createThemedVariants(theme => ({
   base: {
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.lg,
+    borderCurve: "continuous",
     paddingVertical: theme.space[2],
-    maxHeight: 320,
-    ...theme.elevation.lg
+    maxHeight: 320
   }
 }));
 export const selectRowStructure = createThemedVariants(theme => ({
@@ -154,4 +185,20 @@ export const selectRowStructure = createThemedVariants(theme => ({
     paddingHorizontal: theme.space[4]
   }
 }));
+
+/**
+ * `SelectOption.leading` is an arbitrary consumer node, so an unconstrained one could make a row
+ * taller than `SELECT_ROW_MIN_HEIGHT` and silently falsify the list's `getItemLayout` offsets. This
+ * slot bounds it to the row's own glyph box instead, which is what keeps the uniform-height fast
+ * path true by construction (`core/MODULE.md`: `itemHeight` is for uniform rows only).
+ */
+export const selectRowLeadingStructure = createThemedVariants(() => ({
+  base: {
+    width: SELECT_ROW_ICON_SIZE,
+    height: SELECT_ROW_ICON_SIZE,
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden"
+  }
+}));
 //# sourceMappingURL=Select.variants.js.map

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

@@ -8,11 +8,12 @@ neutral fills. It takes no children and no interaction; it IS its own size, whic
 
 | File | Role |
 |------|------|
-| `Skeleton.tsx` | The component. Resolves size/colour/a11y, drives the `Animated` shimmer loop, `style` last. |
+| `Skeleton.tsx` | Translating highlight-band shimmer via Reanimated; `style` last. |
 | `Skeleton.variants.ts` | Pure resolvers (`resolveSkeletonSize`, `resolveSkeletonColors`, `resolveSkeletonAccessibility`) + the themed structural variant resolver `skeletonStructure`. No React. |
 | `index.ts` | Public surface: `Skeleton`, `SkeletonProps`, `SkeletonShape`. |
 | `__tests__/Skeleton.test.ts` | Pure: colour-role mapping + shimmer-visibility guard (all brands × modes), the size resolver, the a11y contract. |
 | `__tests__/Skeleton.render.test.tsx` | Render: shape scale, sizing, shimmer mounts/skips under reduced motion, decorative-vs-labelled a11y, consumer `style` applies last. |
+| `__tests__/Skeleton.motion.test.tsx` | Motion: linear `withRepeat` shimmer, stagger via `withDelay`, gated on reduce motion only. |
 
 ## Props
 
@@ -21,9 +22,10 @@ neutral fills. It takes no children and no interaction; it IS its own size, whic
 | `shape` | `rect \| circle \| text` | `rect` | Closed union — drives the corner radius only. |
 | `width` | `number` | per-shape fallback | dp. Component-owned sizing, **not** `LayoutStyle` — sizing is the point of this component. |
 | `height` | `number` | per-shape fallback | dp. `circle` mirrors whichever of `width`/`height` is given onto both axes (an unequal pair would render an ellipse). |
+| `staggerIndex` | `number` | `0` | Stagger sibling skeletons by `index × 100ms` (80–120ms band). |
 | `accessibilityLabel` | `string` | — | **Optional** — see Accessibility contract below. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
-| `testID` | `string` | — | The shimmer overlay (when mounted) also gets `${testID}-pulse`. |
+| `testID` | `string` | — | The shimmer band (when mounted) also gets `${testID}-shimmer`. |
 
 No `tone`/`color` prop: a skeleton has exactly one neutral appearance (`resolveSkeletonColors`),
 the same reasoning as `Avatar`'s and `Divider`'s colour resolvers — there is nothing for an app to
@@ -33,20 +35,22 @@ widen.
 
 - **Decorative by default, same "decorative unless labelled" shape as `Avatar`.** A skeleton
   carries no meaning of its own — it is a stand-in, not content — so when `accessibilityLabel` is
-  absent it is hidden from assistive tech via `accessibilityElementsHidden` (iOS) +
-  `importantForAccessibility="no-hide-descendants"` (Android). `resolveSkeletonAccessibility`
+  absent it is hidden from assistive tech via `aria-hidden={true}`. `resolveSkeletonAccessibility`
   derives this purely, so the contract is unit-tested without a renderer.
 - When `accessibilityLabel` **is** given (e.g. `"Loading"`), the placeholder is exposed as one
-  `accessibilityRole="progressbar"` element carrying it, with `accessibilityState={{ busy: true }}`
-  (WCAG 1.4.1 — the loading state is announced, not left to be inferred from a box appearing on
-  screen).
+  `accessibilityRole="progressbar"` element carrying it, with `aria-busy={true}` (WCAG 1.4.1 — the
+  loading state is announced, not left to be inferred from a box appearing on screen).
+- **`aria-hidden`, not `accessibilityElementsHidden`+`importantForAccessibility`** — react-native-web
+  0.21.2 forwards only the flat `aria-*` vocabulary to the DOM; the two native-only hiding props
+  reach nothing there, so an unlabelled skeleton used to stay fully exposed to a screen reader on
+  web. `aria-hidden={true}` covers both platforms: RN's `Animated.View` maps it onto
+  `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` natively.
 - **1.4.3 / 1.4.11** — N/A. A skeleton renders no text and draws no interactive boundary (same
   conclusion `Divider.test.ts` documents for its own decorative colour). What IS measured: `base`
-  and `pulse` must resolve to two genuinely different colours on every brand × mode, or the shimmer
+  and `highlight` must resolve to two genuinely different colours on every brand × mode, or the shimmer
   would be a silent no-op — asserted directly in `Skeleton.test.ts`.
-- **2.3.3 (reduced motion)** — `useReducedMotion()` gates the shimmer loop entirely. When true, the
-  `Animated` overlay is never mounted and the box renders as a static `bg.sunken` fill — never a
-  frame frozen mid-pulse.
+- **2.3.3 (reduced motion)** — `useReducedMotion()` gates the shimmer entirely. When true, only the
+  static neutral base (`palette.background[300]`) renders — no band, no pulse.
 - **Touch target (2.5.x)** — N/A. `Skeleton` has no `onPress`.
 
 ## Patterns copied from `Button`/`Avatar`
@@ -56,15 +60,9 @@ widen.
    overlay clips to it without recomputing the radius on that overlay too — safe here because,
    unlike `Button`, nothing needs to be drawn outside this box). Colour → resolved from role tokens
    (`resolveSkeletonColors`), applied inline.
-2. **Shimmer is one `Animated` opacity pulse over a static base fill** — the same "state layer over
-   a base" technique as `Button`'s press overlay: a `bg.sunken` box with an absolutely-positioned
-   overlay sibling whose opacity loops 0 → 1 → 0. The overlay colour is `base` composited with a
-   fixed-alpha `fg.default` (via `compositeOver`, same precedent as `Button`'s `PRESS_SCRIM_DARK`/
-   `LIGHT`) — **not** a second role lookup like `bg.raised`. Two arbitrary role rungs are not
-   guaranteed to differ enough to read as a shimmer: an earlier version used `bg.raised`, and a
-   contrast-ratio floor added to `Skeleton.test.ts` (`MIN_PULSE_CONTRAST`) caught that pair
-   collapsing to visually-indistinguishable on every brand × mode. Compositing a fixed-alpha overlay
-   makes the luminance delta a controlled constant instead of an incidental one.
+2. **Shimmer is a translating highlight band** — base = neutral ramp step 3 (`background[300]`),
+   highlight = step 5 (`background[500]`), band width 40%, linear 1400ms `withRepeat`, optional
+   `staggerIndex` delay. One `translateX` transform — no opacity pulse.
 3. **Pure, testable resolvers** in `Skeleton.variants.ts` (no React) so the colour, sizing, and a11y
    contracts are unit-tested against real palettes — never eyeballed.
 4. **Closed union only** (`shape`), `style: LayoutStyle` last and once, no `{...rest}`.
@@ -80,8 +78,26 @@ still stays layout-only, outermost, and last, for placement (margin, `alignSelf`
 
 ## Known gaps
 
-None — no icon, no new theme token, no new core helper needed for this component.
+- No `staggerIndex` auto-assignment inside a list — the caller passes it per sibling when needed.
+
+## Why the shimmer duration is NOT a `MOTION_DURATION` key
+
+`SKELETON_SHIMMER_DURATION_MS` (1400ms) and `SKELETON_STAGGER_MS` (100ms) are bespoke constants,
+not `motion.duration("deliberate")` (500ms) like `TypingIndicator`'s dot pulse. Deliberate is the
+library's longest discrete key and is reserved for one-shot UI transitions ("onboarding and
+first-run emphasis only" per `core/motion/config.ts`); a shimmer is a continuous ambient loop, a
+different category, and industry-standard shimmer cadence sits at 1200–1600ms — forcing it onto a
+500ms transition would read as rushed and busy rather than a calm loading cue. The value is still
+gated by `useReducedMotion()` (WCAG 2.3.3), the same OS-level signal `useMotion()` itself reads.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No library child components or lists — nothing to memoize.
+
+## 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.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.