pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/multi-select/MultiSelect.js

@@ -1,32 +1,123 @@
 "use strict";
 
 /**
- * MultiSelect — a trigger styled like Select/Input that opens a checkbox-style option list in React
- * Native's OWN `Modal`. Imported directly from `"react-native"` here on purpose, and built as a
- * standalone sibling of `Select` rather than on top of it: selection semantics differ enough
- * (multiple values, a running "N selected" summary, checkbox-row indicators instead of a single
- * check mark) that importing Select would force awkward prop overloading — and this module must not
- * depend on any sibling module, including the library's own Modal (built in parallel elsewhere).
- *
- * 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 MultiSelect reads the same ones `Modal.tsx`/`Select.tsx` read to stay
- * consistent once a consumer opts in via `ModalPortalProvider` — see `../modal/ModalPortalContext.ts`.
+ * MultiSelect — a trigger styled like Select/Input that opens a checkbox-style option list.
  */
 
-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 { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "../modal/ModalPortalContext.js";
 import { renderWebPortal } from "../modal/renderWebPortal";
-import { MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP, MULTI_SELECT_CLOSE_ICON_SIZE, MULTI_SELECT_ROW_ICON_SIZE, MULTI_SELECT_SIZES, multiSelectCloseButtonStructure, multiSelectHeaderStructure, multiSelectOverlayStructure, multiSelectRowIndicatorStructure, multiSelectRowStructure, multiSelectSheetStructure, multiSelectTriggerStructure, resolveMultiSelectAccessibility, resolveMultiSelectRowColors, resolveMultiSelectTriggerColors } from "./MultiSelect.variants.js";
+import { MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP, MULTI_SELECT_CLOSE_ICON_SIZE, MULTI_SELECT_LISTBOX_ROLE, MULTI_SELECT_ROW_ICON_SIZE, MULTI_SELECT_ROW_MIN_HEIGHT, MULTI_SELECT_SIZES, multiSelectCloseButtonStructure, multiSelectHeaderStructure, multiSelectOverlayStructure, multiSelectRowIndicatorStructure, multiSelectRowLeadingStructure, multiSelectRowStructure, multiSelectSheetStructure, multiSelectTriggerStructure, resolveMultiSelectAccessibility, resolveMultiSelectRowColors, resolveMultiSelectTriggerColors } from "./MultiSelect.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 MultiSelectOptionRow = /*#__PURE__*/memo(function MultiSelectOptionRow({
+  option,
+  checked,
+  tabIndex,
+  theme,
+  rowColors,
+  onToggle,
+  testID
+}) {
+  const motion = useMotion();
+  const press = usePressMotion();
+  const handlePress = useCallback(() => onToggle(option.value), [onToggle, option.value]);
+  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]);
+
+  // `checkbox` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  useSpaceActivation(rowRef, handlePress);
+  const checkOpacity = useRef(new Animated.Value(checked ? 1 : 0)).current;
+  const skipFirst = useRef(true);
+  const running = useRef(null);
+  useEffect(() => {
+    running.current?.stop();
+    // A row scrolled into view already-checked must snap, never fade.
+    if (skipFirst.current) {
+      skipFirst.current = false;
+      checkOpacity.setValue(checked ? 1 : 0);
+      return;
+    }
+    if (!motion.enabled) {
+      checkOpacity.setValue(checked ? 1 : 0);
+      return;
+    }
+    running.current = motion.timing(checkOpacity, checked ? 1 : 0, {
+      duration: "fast"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [checked, motion, checkOpacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const rowStructure = useMemo(() => multiSelectRowStructure(theme), [theme]);
+  const indicatorStructure = useMemo(() => multiSelectRowIndicatorStructure(theme), [theme]);
+  const leadingStructure = useMemo(() => multiSelectRowLeadingStructure(theme), [theme]);
+  const rowStyle = useCallback(({
+    pressed
+  }) => ({
+    backgroundColor: pressed ? rowColors.pressedRow : rowColors.background
+  }), [rowColors]);
+  const indicatorStyle = useMemo(() => [indicatorStructure, {
+    borderColor: checked ? rowColors.indicatorFill : rowColors.indicatorBorder,
+    backgroundColor: checked ? rowColors.indicatorFill : "transparent"
+  }], [indicatorStructure, checked, rowColors]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flex: 1,
+    fontSize: theme.fontSizes.md,
+    color: rowColors.text
+  }], [theme, rowColors]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    ref: rowRef,
+    testID: testID ? `${testID}-option-${option.value}` : undefined,
+    accessibilityRole: "checkbox",
+    "aria-checked": checked,
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    style: rowStyle,
+    children: /*#__PURE__*/_jsxs(Animated.View, {
+      testID: testID ? `${testID}-option-${option.value}-content` : undefined,
+      style: [rowStructure, press.style],
+      children: [/*#__PURE__*/_jsx(View, {
+        style: indicatorStyle,
+        children: checked && /*#__PURE__*/_jsx(Animated.View, {
+          testID: testID ? `${testID}-option-${option.value}-check` : undefined,
+          style: {
+            opacity: checkOpacity
+          },
+          children: /*#__PURE__*/_jsx(Icon, {
+            name: "check",
+            size: MULTI_SELECT_ROW_ICON_SIZE,
+            color: rowColors.indicatorIcon,
+            strokeWidth: ICON_STROKE
+          })
+        })
+      }), option.leading !== undefined && /*#__PURE__*/_jsx(View, {
+        style: leadingStructure,
+        children: option.leading
+      }), /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: labelStyle,
+        children: option.label
+      })]
+    })
+  });
+});
 export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   options,
   values,
@@ -39,55 +130,119 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   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 = MULTI_SELECT_SIZES[size];
   const selectedCount = values.length;
   const isPlaceholder = selectedCount === 0;
-  const singleLabel = selectedCount === 1 ? options.find(option => option.value === values[0])?.label : undefined;
+  const selectedValues = useMemo(() => new Set(values), [values]);
+  const singleLabel = useMemo(() => selectedCount === 1 ? options.find(option => option.value === values[0])?.label : undefined, [selectedCount, options, values]);
   const displayText = isPlaceholder ? placeholder ?? "" : singleLabel ?? `${selectedCount} selected`;
-  const triggerColors = resolveMultiSelectTriggerColors(theme.colors, focused || open);
-  const rowColors = resolveMultiSelectRowColors(theme.colors);
-  const a11y = resolveMultiSelectAccessibility({
+  const triggerColors = useMemo(() => resolveMultiSelectTriggerColors(theme.colors, focused || open), [theme.colors, focused, open]);
+  const rowColors = useMemo(() => resolveMultiSelectRowColors(theme.colors), [theme.colors]);
+  const a11y = useMemo(() => resolveMultiSelectAccessibility({
     disabled,
     open
-  });
+  }), [disabled, open]);
   const accessibleName = label !== undefined ? displayText ? `${label}, ${displayText}` : label : undefined;
-  const openMenu = () => {
+  const firstSelectedIndex = useMemo(() => options.findIndex(option => selectedValues.has(option.value)), [options, selectedValues]);
+  const openMenu = useCallback(() => {
     if (disabled) return;
+    // Opening lands the keyboard on the first SELECTED option, not the first one (WCAG 2.4.3).
+    setActiveIndex(firstSelectedIndex === -1 ? 0 : firstSelectedIndex);
     setOpen(true);
-  };
-  const closeMenu = () => setOpen(false);
-  const toggleValue = value => {
-    const next = values.includes(value) ? values.filter(v => v !== value) : [...values, value];
-    onValuesChange(next);
-  };
-  const sheet = /*#__PURE__*/_jsxs(_Fragment, {
+  }, [disabled, firstSelectedIndex]);
+  const closeMenu = useCallback(() => setOpen(false), []);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+
+  // `values` necessarily changes on every toggle, so reading it through a ref is what keeps
+  // `toggleValue` identity-stable — as a dependency it re-created the callback per toggle and
+  // defeated `React.memo` on every mounted row, not just the one whose `checked` flipped.
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+  const onValuesChangeRef = useRef(onValuesChange);
+  onValuesChangeRef.current = onValuesChange;
+  const toggleValue = useCallback(value => {
+    const current = valuesRef.current;
+    const next = current.includes(value) ? current.filter(v => v !== value) : [...current, value];
+    onValuesChangeRef.current(next);
+  }, []);
+  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 a row on Enter, and each row's own `useSpaceActivation`
+  // owns Space — passing it here would toggle twice, i.e. not at all.
+  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(MultiSelectOptionRow, {
+    option: option,
+    checked: selectedValues.has(option.value),
+    tabIndex: focusItemProps(index, activeIndex).tabIndex,
+    theme: theme,
+    rowColors: rowColors,
+    onToggle: toggleValue,
+    testID: testID
+  }), [selectedValues, activeIndex, theme, rowColors, toggleValue, testID]);
+  const rootStyle = useMemo(() => [styles.container, containerStyle], [containerStyle]);
+  const triggerStyle = useMemo(() => [multiSelectTriggerStructure(theme, {
+    size
+  }), {
+    backgroundColor: triggerColors.background,
+    borderColor: triggerColors.border
+  }, disabled && styles.dimmed], [theme, size, triggerColors, disabled]);
+  const overlayStructure = useMemo(() => multiSelectOverlayStructure(theme), [theme]);
+  const headerStructure = useMemo(() => multiSelectHeaderStructure(theme), [theme]);
+  const closeButtonStructure = useMemo(() => multiSelectCloseButtonStructure(theme), [theme]);
+  const sheetStyle = useMemo(() => [multiSelectSheetStructure(theme), {
+    backgroundColor: theme.colors.bg.surface
+  }], [theme]);
+  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: multiSelectOverlayStructure(theme),
+      style: overlayStructure,
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsxs(View, {
-        style: [multiSelectSheetStructure(theme), {
-          backgroundColor: theme.colors.bg.surface
-        }],
+      children: /*#__PURE__*/_jsxs(Animated.View, {
+        ref: sheetRef,
+        style: [sheetStyle, reveal.style],
         children: [/*#__PURE__*/_jsx(View, {
-          style: multiSelectHeaderStructure(theme),
+          style: headerStructure,
           children: /*#__PURE__*/_jsx(Pressable, {
             testID: testID ? `${testID}-close` : undefined,
             accessibilityRole: "button",
             accessibilityLabel: "Close",
             onPress: closeMenu,
             hitSlop: MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP,
-            style: multiSelectCloseButtonStructure(theme),
+            style: closeButtonStructure,
             children: /*#__PURE__*/_jsx(Icon, {
               name: "x",
               size: MULTI_SELECT_CLOSE_ICON_SIZE,
@@ -95,50 +250,16 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
               strokeWidth: ICON_STROKE
             })
           })
-        }), /*#__PURE__*/_jsx(ScrollView, {
-          bounces: false,
-          children: options.map(option => {
-            const checked = values.includes(option.value);
-            return /*#__PURE__*/_jsxs(Pressable, {
-              testID: testID ? `${testID}-option-${option.value}` : undefined,
-              accessibilityRole: "checkbox",
-              accessibilityState: {
-                checked
-              },
-              onPress: () => toggleValue(option.value),
-              style: [multiSelectRowStructure(theme), {
-                backgroundColor: rowColors.background
-              }],
-              children: [/*#__PURE__*/_jsx(View, {
-                style: [multiSelectRowIndicatorStructure(theme), {
-                  borderColor: checked ? rowColors.indicatorFill : rowColors.indicatorBorder,
-                  backgroundColor: checked ? rowColors.indicatorFill : "transparent"
-                }],
-                children: checked && /*#__PURE__*/_jsx(Icon, {
-                  name: "check",
-                  size: MULTI_SELECT_ROW_ICON_SIZE,
-                  color: rowColors.indicatorIcon,
-                  strokeWidth: ICON_STROKE
-                })
-              }), 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
-              })]
-            }, option.value);
-          })
+        }), /*#__PURE__*/_jsx(VirtualList, {
+          data: options,
+          keyExtractor: keyExtractor,
+          renderItem: renderItem,
+          itemHeight: MULTI_SELECT_ROW_MIN_HEIGHT,
+          accessibilityRole: MULTI_SELECT_LISTBOX_ROLE
         })]
       })
     })]
-  });
-
-  // Web portal opt-in — see Modal.tsx's/Select.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",
@@ -146,42 +267,30 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
-    animationType: reducedMotion ? "none" : "fade",
+    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: [multiSelectTriggerStructure(theme, {
-        size
-      }), {
-        backgroundColor: triggerColors.background,
-        borderColor: triggerColors.border
-      }, disabled && styles.dimmed],
+      style: triggerStyle,
       children: [/*#__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, {
         name: "chevron-down",
@@ -196,9 +305,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=MultiSelect.js.map

package/lib/module/modules/multi-select/MultiSelect.variants.js

@@ -46,6 +46,14 @@ export const MULTI_SELECT_SIZES = {
 /** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). */
 export const MULTI_SELECT_ROW_MIN_HEIGHT = 44;
 
+/**
+ * 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 MULTI_SELECT_LISTBOX_ROLE = "listbox";
+
 /** Row checkbox-style indicator box side, in dp. Fixed — independent of the trigger's own `size`,
  *  same reasoning as `Select`'s row "check" glyph. */
 export const MULTI_SELECT_ROW_INDICATOR_SIZE = 20;
@@ -78,7 +86,8 @@ export function resolveMultiSelectRowColors(colors) {
     text: colors.fg.default,
     indicatorBorder: colors.border.interactive,
     indicatorFill: colors.accent.solid,
-    indicatorIcon: colors.accent.onSolid
+    indicatorIcon: colors.accent.onSolid,
+    pressedRow: colors.bg.sunken
   };
 }
 /**
@@ -90,10 +99,8 @@ export function resolveMultiSelectAccessibility(input) {
   const disabled = input.disabled === true;
   return {
     accessibilityRole: "button",
-    accessibilityState: {
-      disabled,
-      expanded: input.open
-    },
+    "aria-disabled": disabled,
+    "aria-expanded": input.open,
     disabled
   };
 }
@@ -180,6 +187,22 @@ export const multiSelectRowStructure = createThemedVariants(theme => ({
   }
 }));
 
+/**
+ * `MultiSelectOption.leading` is an arbitrary consumer node, so an unconstrained one could make a
+ * row taller than `MULTI_SELECT_ROW_MIN_HEIGHT` and silently falsify the list's `getItemLayout`
+ * offsets. This slot bounds it to the row's own indicator box instead, which is what keeps the
+ * uniform-height fast path true by construction (`core/MODULE.md`: `itemHeight` is uniform-only).
+ */
+export const multiSelectRowLeadingStructure = createThemedVariants(() => ({
+  base: {
+    width: MULTI_SELECT_ROW_INDICATOR_SIZE,
+    height: MULTI_SELECT_ROW_INDICATOR_SIZE,
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden"
+  }
+}));
+
 /** Structural indicator-box styles only — size, radius, border WIDTH. No colours: border/fill
  *  colour is checked-state-driven and applied inline over this, same split as `checkboxBoxStructure`. */
 export const multiSelectRowIndicatorStructure = createThemedVariants(theme => ({

package/lib/module/modules/number-input/MODULE.md

@@ -12,7 +12,7 @@ TWO trailing controls, which doesn't fit Input's single leading/trailing icon sl
 | `NumberInput.variants.ts` | Pure resolvers (`NUMBER_INPUT_SIZES`, `resolveNumberInputStatus`, `resolveNumberInputStepperPressColors`, `resolveNumberInputAccessibility`, `clampNumberInputValue`, `parseNumberInputDraft`, `canDecrementNumberInput`, `canIncrementNumberInput`) + the themed structural resolvers `numberInputStructure` / `numberInputStepperStructure`. No React, no lucide. |
 | `index.ts` | Public surface: `NumberInput`, `NumberInputProps`, the closed unions. No `icon` prop, so `IconName` is not re-exported. |
 | `__tests__/NumberInput.test.ts` | Pure: WCAG contrast (all brands × modes, incl. the stepper pressed-fill) + touch target + clamp/parse/limit + a11y contract. |
-| `__tests__/NumberInput.render.test.tsx` | Render: stepper press, typed input, clamping, disabled/at-limit, the field's and each stepper's own focus ring. |
+| `__tests__/NumberInput.render.test.tsx` | Render: stepper press, typed input, clamping, disabled/at-limit, the field's and each stepper's own focus ring, the rendered `hitSlop`, `accessibilityValue`, and the increment/decrement accessibility actions. |
 
 ## Props
 
@@ -26,6 +26,7 @@ TWO trailing controls, which doesn't fit Input's single leading/trailing icon sl
 | `status` | `default \| error` | `default` | Closed union — a **state**, not a brand `tone` (same reasoning as Input). |
 | `disabled` | `boolean` | `false` | Dims the field; blocks editing and both steppers. |
 | `label` | `string` | — | Rendered above the field; falls back into `accessibilityLabel`. |
+| `errorText` | `string` | — | Shown below the field and folded into the accessible name (`aria-invalid` set) when `status="error"` — same prop name and rule as `Input`/`FormField`. Previously `status="error"` was border-colour only, with no message and no programmatic invalid flag (WCAG 3.3.1 / 1.4.1). |
 | `accessibilityLabel` | `string` | `label` | Overrides the label fallback. |
 | `containerStyle` | `LayoutStyle` | — | The documented exception for a native-primitive wrapper. Outermost, last, once. Never `inputStyle`. |
 | `testID` | `string` | — | Forwarded to the `TextInput`; the steppers get `${testID}-decrement` / `${testID}-increment`. |
@@ -49,8 +50,29 @@ typed values are clamped to range but never snapped to a `step` grid.
   both stepper `Pressable`s. This only holds because every one of the three carries
   `alignSelf: "stretch"` inside the row (`alignItems: "center"` would otherwise shrink each to its
   intrinsic content height) — the same fix Input's `TextInput` needed, carried forward from the
-  start here (see `NumberInput.render.test.tsx`, which asserts the rendered node, not just the
-  `height + 2·hitSlop` arithmetic).
+  start here. `NumberInput.render.test.tsx` asserts BOTH halves on the rendered nodes: the
+  `alignSelf` of all three, and (per size) their real `hitSlop` prop against
+  `NUMBER_INPUT_SIZES[size].hitSlop` — the `height + 2·hitSlop` arithmetic in `NumberInput.test.ts`
+  proves nothing on its own if a refactor drops the prop off a node.
+- **4.1.2 value semantics** — the `TextInput` carries BOTH `accessibilityValue={{…}}` and flat
+  `aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext` from
+  `resolveNumberInputAccessibility` — the one deliberate exception to "flat-only" in this family.
+  Verified: RN's `TextInput.js` never destructures ANY `aria-value*` prop (unlike `View`/`Pressable`,
+  which merge it), so flat-only would be silently dropped on native; `react-native-web` never reads
+  `accessibilityValue`, so object-only would be silently dropped on web. Both forms, one per
+  platform. A bound the caller omitted is **left out**, never defaulted to `0` — absent means "no
+  floor"/"no ceiling" here.
+  **Corrected claim:** this file previously said the announced text is `String(value)` "verbatim" —
+  false. `value` and the field's own visible `draft` state diverge while typing (e.g. a keystroke
+  that doesn't parse yet, or one that clamps), and the announcement used to speak `value` while the
+  screen showed `draft` — a 4.1.2 failure in itself. The announced text is now `draft`, matching what
+  is actually on screen; `now` stays the raw, unclamped `value` (unlike `Slider`'s clamped `now`).
+- **2.5.7 non-pointer alternative** — the field also declares
+  `accessibilityActions: [{name:"increment"},{name:"decrement"}]` + `onAccessibilityAction`, reusing
+  the same `handleIncrement`/`handleDecrement` (so an at-limit or disabled action is a no-op).
+  Same reasoning as `Slider`: iOS offers adjust gestures from the trait, Android TalkBack only
+  surfaces actions declared here — without them the +/- controls are reachable *only* as two extra
+  swipe stops. The list is always declared; the handler, not the list, does the gating.
 - **1.4.3** — value text and stepper icon colour (`fg.default`) are measured ≥ 4.5:1 against the
   canvas at rest, for all 8 brands × both modes.
 - **1.4.11** — the resting/focus border (`border.interactive` / `border.focus`) and the error border
@@ -73,13 +95,19 @@ typed values are clamped to range but never snapped to a `step` grid.
   (whole-row ring), the decrement `Pressable`, and the increment `Pressable` (each stepper gets its
   own ring, rounded only on its outer corner via `stepperFocusRingStyle`). Keyboard/AT focus on a
   stepper no longer relies on a background tint — the ring is the sole focus indicator, exactly the
-  pattern Button/Input/Checkbox use.
+  pattern Button/Input/Checkbox use. Each stepper's ring stays gated on `focused && enabled`, and an
+  at-limit/disabled stepper is therefore made **unfocusable** (`focusable={enabled}`) rather than
+  given a ring: RN's `Pressable` keeps `focusable` true when `disabled`, so on a TV remote it could
+  take focus and show no indicator at all (RNW already excludes it — `tabIndex: -1`). Removing the
+  inert control from the focus order fixes that at the source; painting a ring on a control that does
+  nothing when activated would advertise operability it doesn't have. TalkBack still reaches it (that
+  traversal follows `accessible`, not `focusable`) and still announces its disabled state.
 - **Web** — RNW renders the `TextInput` as a real `<input>`, so `styles.webOutlineReset` (`outlineWidth:
   0`, applied only when `Platform.OS === "web"`, matching Input/Textarea) suppresses the browser's own
   default focus outline on the field, which would otherwise double up visibly with the themed ring
   above. Scoped to the `TextInput` only — the stepper `Pressable`s aren't part of this fix.
 - Decrement/increment each carry `accessibilityRole="button"` and their own
-  `accessibilityLabel` ("Decrease" / "Increase") plus `accessibilityState.disabled`, so a screen
+  `accessibilityLabel` ("Decrease" / "Increase") plus flat `aria-disabled`, so a screen
   reader announces the control and its at-limit state even though it shows no visible text.
 - A disabled field is exempt from the contrast minimum (WCAG 1.4.3) and dims via `opacity: 0.5`, same
   as Input/Button. An at-limit stepper (value already at `min`/`max`) dims the same way *without*
@@ -106,3 +134,9 @@ typed values are clamped to range but never snapped to a `step` grid.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Same shape as `MultiSelect`: `Icon` gets only primitive props, no `.map()` list, every handler goes to host `Pressable`/`TextInput` — 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.