pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/pagination/Pagination.variants.js

@@ -0,0 +1,307 @@
+"use strict";
+
+/**
+ * Pagination's pure logic + style resolution — same split as Button/ButtonGroup:
+ *  - PAGE ARITHMETIC (`buildPageRange`, `clampPage`) is the reason this module exists. It is pure,
+ *    total, and never throws, so the exhaustive edge cases live in `Pagination.test.ts` rather than
+ *    being re-derived (and subtly re-broken) in every consumer app.
+ *  - STRUCTURE (control height/padding/radius) lives in the `createThemedVariants` resolvers below,
+ *    registered once per (theme, size) — never rebuilt per render.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolvePaginationColors`), never a raw hex.
+ *  - ACCESSIBILITY prop derivation is `resolvePaginationStep` / `resolvePaginationPage`, kept pure
+ *    so the "boundary arrow is disabled / current page is selected" contract is unit-testable
+ *    without rendering React Native.
+ *
+ * Free of React, `lucide`, and any native import, so the WCAG + logic tests import it directly
+ * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants, createVariants } from "../../core/style/index.js";
+
+/** One slot in the numbered strip: a page number, or a gap marker standing in for a run of pages. */
+
+/** Same touch-target floor as Button/ButtonGroup (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));
+
+/**
+ * The WIDTH-axis touch floor, met by the rendered node itself rather than by horizontal `hitSlop` —
+ * see `resolvePaginationHitSlop` for why this control can never expand sideways.
+ */
+export const PAGINATION_CONTROL_MIN_WIDTH = MIN_TOUCH_TARGET;
+/**
+ * Pagination-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
+ * test can assert `height + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.
+ */
+export const PAGINATION_SIZES = {
+  sm: {
+    height: 32,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(32)
+  },
+  md: {
+    height: 40,
+    fontSize: 16,
+    iconSize: 18,
+    hitSlop: slopFor(40)
+  }
+};
+
+/** Non-finite input (`NaN`, `Infinity`) collapses to `minimum` — this arithmetic never throws. */
+const toWholeNumber = (value, minimum) => Number.isFinite(value) ? Math.max(minimum, Math.floor(value)) : minimum;
+
+/** A page count of 0 means "nothing to paginate"; negatives and garbage normalise to it. */
+export function normalizePageCount(pageCount) {
+  return toWholeNumber(pageCount, 0);
+}
+
+/**
+ * The current page, forced into `[1, pageCount]`. An out-of-bounds `page` (a stale value after a
+ * filter shrank the result set is the common one) clamps rather than rendering an empty strip or
+ * throwing. With no pages at all this still answers `1`, so a caller that renders anyway shows
+ * "Page 1 of 0" instead of "Page 0 of 0" — `Pagination` itself renders nothing in that state.
+ */
+export function clampPage(page, pageCount) {
+  const total = normalizePageCount(pageCount);
+  if (total < 1) return 1;
+  return Math.min(total, toWholeNumber(page, 1));
+}
+const range = (start, end) => {
+  const out = [];
+  for (let value = start; value <= end; value++) out.push(value);
+  return out;
+};
+
+/**
+ * The page-window resolver — which page numbers the numbered strip shows around `page`, with
+ * `"ellipsis"` standing in for each elided run.
+ *
+ * The strip is a fixed width so it never reflows as the user pages through: first + last + current
+ * + both sibling runs + both gap markers = `2·siblingCount + 5` slots. Below that many pages there
+ * is nothing to elide, so every page is listed. Above it, one or both gaps appear; whichever end
+ * has no gap gets a longer run of consecutive pages (`2·siblingCount + 3`) so the total stays
+ * constant.
+ *
+ * A gap is only drawn once it would hide at least TWO pages: a marker standing in for a single
+ * number is strictly worse than the number (it costs the same slot and navigates nowhere), which
+ * is why the thresholds are `> 3` / `< total - 2` and not the usual off-by-one `> 2` / `< total - 1`.
+ */
+export function buildPageRange(page, pageCount, siblingCount = 1) {
+  const total = normalizePageCount(pageCount);
+  if (total < 1) return [];
+  const siblings = toWholeNumber(siblingCount, 0);
+  const current = clampPage(page, total);
+  const windowLength = siblings * 2 + 5;
+  if (total <= windowLength) return range(1, total);
+  const leftSibling = Math.max(current - siblings, 1);
+  const rightSibling = Math.min(current + siblings, total);
+  const gapLeft = leftSibling > 3;
+  const gapRight = rightSibling < total - 2;
+  const edgeRunLength = siblings * 2 + 3;
+  if (!gapLeft && gapRight) return [...range(1, edgeRunLength), "ellipsis", total];
+  if (gapLeft && !gapRight) return [1, "ellipsis", ...range(total - edgeRunLength + 1, total)];
+  return [1, "ellipsis", ...range(leftSibling, rightSibling), "ellipsis", total];
+}
+/**
+ * Maps the component's fixed visual roles onto ROLE colours. There is no `tone` union: the current
+ * page is always the accent role and the outline is always the neutral interactive outline, so —
+ * like `ButtonGroup` — this is pure indirection, not a union to resolve.
+ *
+ * `pressedFill` is `bg.sunken`, NOT `bg.hover`: same class of fix Button's "neutral" tone and
+ * RadioGroup/Menu document (the saturated `hover` mid-tone drops a brand-tinted label below 4.5:1).
+ * Unlike ButtonGroup it needs no compositing to clear the selected fill, because controls here are
+ * separated by a `space[1]` gutter — a pressed neighbour never shares an edge with the current-page
+ * pill, so that boundary is always fill-vs-canvas.
+ */
+export function resolvePaginationColors(colors) {
+  return {
+    currentFill: colors.accent.solid,
+    onCurrentFill: colors.accent.onSolid,
+    label: colors.fg.default,
+    inactiveLabel: colors.fg.muted,
+    pressedFill: colors.bg.sunken,
+    border: colors.border.interactive
+  };
+}
+export const STEP_LABELS = {
+  first: "First page",
+  previous: "Previous page",
+  next: "Next page",
+  last: "Last page"
+};
+export const DEFAULT_LOAD_MORE_LABEL = "Load more";
+export function formatPageLabel(page, pageCount) {
+  return `Page ${page} of ${pageCount}`;
+}
+/**
+ * One step control's accessibility + navigation surface. A step is inert when the whole component
+ * is disabled/loading OR when its target is out of range or already the current page — the
+ * boundary case, which announces `disabled` so a screen reader user learns they are at an end
+ * instead of pressing a silently dead control.
+ */
+export function resolvePaginationStep(input) {
+  const total = normalizePageCount(input.pageCount);
+  const current = clampPage(input.page, total);
+  const target = input.kind === "first" ? 1 : input.kind === "previous" ? current - 1 : input.kind === "next" ? current + 1 : total;
+  const blocked = input.disabled || input.loading;
+  const unreachable = target < 1 || target > total || target === current;
+  const inert = blocked || unreachable;
+  return {
+    accessibilityRole: "button",
+    accessibilityLabel: STEP_LABELS[input.kind],
+    "aria-disabled": inert,
+    "aria-busy": input.loading,
+    disabled: inert,
+    targetPage: inert ? undefined : target
+  };
+}
+/**
+ * One page-number control's accessibility + navigation surface.
+ *
+ * The current page is inert (`targetPage: undefined`) but is NOT reported disabled: it is the
+ * selected item, not an unavailable one, and announcing both would tell assistive tech the user's
+ * own position is broken. `disabled` therefore only ever reflects the component-wide gate.
+ */
+export function resolvePaginationPage(input) {
+  const total = normalizePageCount(input.pageCount);
+  const current = clampPage(input.page, total);
+  const isCurrent = input.item === current;
+  const blocked = input.disabled || input.loading;
+  const label = formatPageLabel(input.item, total);
+  return {
+    accessibilityRole: "button",
+    accessibilityLabel: isCurrent ? `${label}, current page` : label,
+    "aria-disabled": blocked,
+    "aria-busy": input.loading,
+    "aria-current": isCurrent ? "page" : undefined,
+    accessibilityState: {
+      selected: isCurrent
+    },
+    disabled: blocked,
+    targetPage: blocked || isCurrent ? undefined : input.item,
+    current: isCurrent
+  };
+}
+/**
+ * Vertical expansion only. Controls sit in a row `space[1]` apart, and React Native never clips
+ * `hitSlop` to a sibling's bounds — it resolves an overlap to whichever sibling renders LATER, not
+ * to whichever is visually closer to the tap, so horizontal slop wide enough to matter would hand a
+ * tap near a gutter to the wrong page (the defect `ButtonGroup` documents fixing the same way).
+ * The width axis is met by `PAGINATION_CONTROL_MIN_WIDTH` on the rendered node instead.
+ */
+export function resolvePaginationHitSlop(size) {
+  const slop = PAGINATION_SIZES[size].hitSlop;
+  return {
+    top: slop,
+    bottom: slop,
+    left: 0,
+    right: 0
+  };
+}
+
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (those are
+ * resolved from `RoleColors` and applied inline), so these compile once per theme identity via the
+ * `WeakMap`-cached themed resolver and never rebuild per render.
+ */
+export const paginationRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    columnGap: theme.space[1]
+  }
+}));
+
+/**
+ * The numbered strip's root. A column box on purpose: it stretches the horizontal `ScrollView`
+ * inside it to the root's own width, which is what BOUNDS the scroll view — a horizontal
+ * `ScrollView` sized by its content instead overflows its parent and never scrolls. No theme
+ * dependency, so the untethered resolver — same idiom `drawerOverlayStructure` uses.
+ */
+export const paginationStripRootStructure = createVariants({
+  base: {
+    flexDirection: "column",
+    alignItems: "stretch"
+  }
+});
+export const paginationScrollContentStructure = createThemedVariants(theme => ({
+  base: {
+    flexGrow: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    columnGap: theme.space[1]
+  }
+}));
+export const paginationControlStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    minWidth: PAGINATION_CONTROL_MIN_WIDTH,
+    paddingHorizontal: theme.space[1],
+    borderRadius: theme.radii.base
+  },
+  variants: {
+    size: {
+      sm: {
+        height: PAGINATION_SIZES.sm.height
+      },
+      md: {
+        height: PAGINATION_SIZES.md.height
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/** Narrower than a control: the gap marker is decorative, so it owes no touch target. */
+export const paginationEllipsisStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    minWidth: theme.space[6]
+  },
+  variants: {
+    size: {
+      sm: {
+        height: PAGINATION_SIZES.sm.height
+      },
+      md: {
+        height: PAGINATION_SIZES.md.height
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+export const paginationLoadMoreStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    columnGap: theme.space[2],
+    minWidth: PAGINATION_CONTROL_MIN_WIDTH,
+    paddingHorizontal: theme.space[4],
+    borderRadius: theme.radii.base,
+    borderWidth: theme.borderWidths.thin
+  },
+  variants: {
+    size: {
+      sm: {
+        height: PAGINATION_SIZES.sm.height
+      },
+      md: {
+        height: PAGINATION_SIZES.md.height
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=Pagination.variants.js.map

package/lib/module/modules/pagination/PaginationControls.js

@@ -0,0 +1,193 @@
+"use strict";
+
+/**
+ * PRIVATE sub-components (not exported from `index.ts`). One control per node, each `React.memo`'d
+ * and fed primitives only, so a page change re-renders the two controls whose state actually
+ * changed instead of the whole strip — and so no `onPress`/`style` closure is rebuilt per control
+ * per render.
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { paginationControlStructure, paginationEllipsisStructure, resolvePaginationPage, resolvePaginationStep } from "./Pagination.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const ELLIPSIS_GLYPH = "…";
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_INSET = 2;
+
+// Inset, not Button's outside offsets: the strip's ScrollView is one control tall and clips.
+const focusRingStyleFor = theme => ({
+  position: "absolute",
+  pointerEvents: "none",
+  top: FOCUS_RING_INSET,
+  left: FOCUS_RING_INSET,
+  right: FOCUS_RING_INSET,
+  bottom: FOCUS_RING_INSET,
+  borderWidth: FOCUS_RING_WIDTH,
+  borderColor: theme.colors.border.focus,
+  borderRadius: Math.max(0, theme.radii.base - FOCUS_RING_INSET)
+});
+export const PaginationStepControl = /*#__PURE__*/memo(function PaginationStepControl({
+  kind,
+  icon,
+  page,
+  pageCount,
+  disabled,
+  loading,
+  size,
+  iconSize,
+  theme,
+  colors,
+  hitSlop,
+  onPageChange,
+  testID
+}) {
+  const a11y = resolvePaginationStep({
+    kind,
+    page,
+    pageCount,
+    disabled,
+    loading
+  });
+  const target = a11y.targetPage;
+  const handlePress = useCallback(() => {
+    if (target !== undefined) onPageChange(target);
+  }, [target, onPageChange]);
+  const pressedFill = colors.pressedFill;
+  const inert = a11y.disabled;
+  const controlStyle = useCallback(({
+    pressed
+  }) => [paginationControlStructure(theme, {
+    size
+  }), pressed && !inert ? {
+    backgroundColor: pressedFill
+  } : null], [theme, size, inert, pressedFill]);
+  const [focused, setFocused] = useState(false);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const focusRingStyle = useMemo(() => focusRingStyleFor(theme), [theme]);
+  return /*#__PURE__*/_jsxs(Pressable, {
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    "aria-disabled": a11y["aria-disabled"],
+    "aria-busy": a11y["aria-busy"],
+    disabled: inert
+    // RN's Pressable stays `focusable` when disabled, so a TV remote could land on a boundary arrow.
+    ,
+    focusable: !inert,
+    onPress: target === undefined ? undefined : handlePress,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    hitSlop: hitSlop,
+    style: controlStyle,
+    children: [focused && !inert && /*#__PURE__*/_jsx(View, {
+      testID: testID ? `${testID}-focus-ring` : undefined,
+      style: focusRingStyle
+    }), /*#__PURE__*/_jsx(Icon, {
+      name: icon,
+      size: iconSize,
+      color: inert ? colors.inactiveLabel : colors.label,
+      strokeWidth: ICON_STROKE
+    })]
+  });
+});
+export const PaginationPageControl = /*#__PURE__*/memo(function PaginationPageControl({
+  item,
+  page,
+  pageCount,
+  disabled,
+  loading,
+  blocked,
+  size,
+  fontSize,
+  theme,
+  colors,
+  hitSlop,
+  onPageChange,
+  testID
+}) {
+  const a11y = resolvePaginationPage({
+    item,
+    page,
+    pageCount,
+    disabled,
+    loading
+  });
+  const target = a11y.targetPage;
+  const current = a11y.current;
+  const handlePress = useCallback(() => {
+    if (target !== undefined) onPageChange(target);
+  }, [target, onPageChange]);
+  const {
+    currentFill,
+    pressedFill
+  } = colors;
+  const controlStyle = useCallback(({
+    pressed
+  }) => [paginationControlStructure(theme, {
+    size
+  }), current ? {
+    backgroundColor: currentFill
+  } : null, !current && pressed ? {
+    backgroundColor: pressedFill
+  } : null], [theme, size, current, currentFill, pressedFill]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(current ? theme.fontWeights.semibold : theme.fontWeights.regular), {
+    fontSize,
+    color: current ? colors.onCurrentFill : blocked ? colors.inactiveLabel : colors.label
+  }], [theme, current, fontSize, blocked, colors]);
+  const [focused, setFocused] = useState(false);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const focusRingStyle = useMemo(() => focusRingStyleFor(theme), [theme]);
+  return /*#__PURE__*/_jsxs(Pressable, {
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    "aria-disabled": a11y["aria-disabled"],
+    "aria-busy": a11y["aria-busy"],
+    "aria-current": a11y["aria-current"],
+    accessibilityState: a11y.accessibilityState,
+    disabled: a11y.disabled,
+    focusable: !a11y.disabled,
+    onPress: target === undefined ? undefined : handlePress,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    hitSlop: hitSlop,
+    style: controlStyle,
+    children: [focused && !a11y.disabled && /*#__PURE__*/_jsx(View, {
+      testID: testID ? `${testID}-focus-ring` : undefined,
+      style: focusRingStyle
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: String(item)
+    })]
+  });
+});
+export const PaginationEllipsis = /*#__PURE__*/memo(function PaginationEllipsis({
+  size,
+  fontSize,
+  theme,
+  color
+}) {
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize,
+    color
+  }], [theme, fontSize, color]);
+  return /*#__PURE__*/_jsx(View, {
+    accessible: false,
+    accessibilityElementsHidden: true,
+    importantForAccessibility: "no-hide-descendants",
+    style: paginationEllipsisStructure(theme, {
+      size
+    }),
+    children: /*#__PURE__*/_jsx(Text, {
+      style: labelStyle,
+      children: ELLIPSIS_GLYPH
+    })
+  });
+});
+//# sourceMappingURL=PaginationControls.js.map

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

@@ -0,0 +1,15 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/pagination`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The visual resolvers (`resolvePaginationColors`, `PAGINATION_SIZES`,
+ * …) stay internal — a consumer configures a Pagination through its props.
+ *
+ * `buildPageRange` / `clampPage` are the documented exception: they are pure, dependency-free page
+ * arithmetic, and the whole point of this module is that an app never re-derives them by hand for
+ * a pager it draws itself.
+ */
+
+export { Pagination } from "./Pagination.js";
+export { buildPageRange, clampPage } from "./Pagination.variants.js";
+//# sourceMappingURL=index.js.map

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

@@ -24,9 +24,10 @@ single source of truth; the boxes only render what it already holds.
 | `value` | `string` | — | Required — controlled. |
 | `onValueChange` | `(value: string) => void` | — | Required. Receives the CLAMPED value (see below). |
 | `onComplete` | `(value: string) => void` | — | Fires once per completion (`value.length === length` on a genuine change), never on an unrelated re-render while already full — see "Fires once" below. |
-| `secureTextEntry` | `boolean` | `false` | Renders a dot instead of the character per box, forwards to the real hidden `TextInput` (native secure-entry actually engages), and masks the announced `accessibilityValue` to one `•` per digit — same masking concept as `Input`'s prop of the same name, but end-to-end: visual, native, AND assistive tech. |
+| `secureTextEntry` | `boolean` | `false` | Renders a dot instead of the character per box, forwards to the real hidden `TextInput` (native secure-entry actually engages), and masks the announced value to one `•` per digit — same masking concept as `Input`'s prop of the same name, but end-to-end: visual, native, AND assistive tech. |
 | `keyboardType` | `number-pad \| default` | `number-pad` | `number-pad` strips non-digit characters on every change (typed OR pasted). |
 | `status` | `default \| error` | `default` | Closed union — a state, not a brand tone. |
+| `errorText` | `string` | — | Shown below the row and folded into the accessible name (`aria-invalid` set) when `status="error"`, same rule as `Input`/`FormField`. Previously `status="error"` was box-border colour only — no message, no programmatic invalid flag (WCAG 3.3.1 / 1.4.1). |
 | `disabled` | `boolean` | `false` | Dimmed; blocks editing and the row's press-to-focus. |
 | `size` | `sm \| md \| lg` | `md` | Box 40/48/56dp square; short sizes reach 44dp via the ROW's `hitSlop`. |
 | `autoFocus` | `boolean` | `false` | Forwarded to the hidden `TextInput`. |
@@ -59,13 +60,18 @@ new `onComplete` closure) does not fire again.
   pasted string and the existing clamp logic handles it identically to typing.
 - **Focus management**: auto-advancing focus across N fields on every keystroke is a well-known
   source of bugs on backspace, selection, and IME composition. One field sidesteps the whole class.
-- **iOS/Android OTP autofill**: `textContentType="oneTimeCode"` (set when `keyboardType="number-pad"`)
-  lets iOS surface the SMS one-time-code suggestion above the keyboard, same as it would for a
-  normal single-field OTP input.
-- The field is `opacity: 0` (not `display: none`) so it stays real, focusable, and editable —
-  `display: none` risks the OS treating it as unfocusable on some platforms. It is positioned
-  `StyleSheet.absoluteFill` over the boxes with `pointerEvents="none"` so it never intercepts
-  touches; the row's own `Pressable` (see below) calls `inputRef.current.focus()` instead.
+- **iOS/Android OTP autofill**: `textContentType="oneTimeCode"` is now UNCONDITIONAL, not gated on
+  `keyboardType="number-pad"` — an alphanumeric OTP is still an OTP, and the old gate silently lost
+  iOS's SMS-code suggestion whenever a consumer used `keyboardType="default"`. `autoComplete="sms-otp"`
+  is the Android half — genuinely absent before, despite this doc previously claiming it existed.
+- **Corrected: the field was `opacity: 0`, and that is invisible to VoiceOver, not merely "visually
+  suppressed".** iOS `UIAccessibility` excludes any view with `alpha == 0` from the accessibility
+  tree — since this hidden `TextInput` is the control's ONLY accessibility element, the whole
+  control was unreachable by VoiceOver, and there was no node to long-press for the OS paste
+  callout. Fixed by keeping `opacity: 1` and using `color: "transparent"` instead — the node stays
+  real, focusable, and long-press-able; only its glyphs render invisibly (the field paints no
+  background/border of its own). Still `StyleSheet.absoluteFill` with `pointerEvents="none"` so it
+  never intercepts touches; the row's own `Pressable` calls `inputRef.current.focus()` instead.
 
 ## Touch target — the ROW, not per-box
 
@@ -83,15 +89,18 @@ same pattern as `Input`/`ButtonGroup`/`Reorder`'s render-level touch-target chec
 - **1.3.1 / one real field, not N mystery boxes** — every box is `accessibilityRole="none"` +
   `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` (decorative,
   not independently focusable). The hidden `TextInput` alone carries `accessibilityLabel` (the
-  required prop) and `accessibilityValue`, so a screen reader announces this as the single field it
+  required prop) and the announced value, so a screen reader announces this as the single field it
   actually is.
+- **The announced value is emitted in BOTH `accessibilityValue={{…}}` and flat `aria-valuetext`** —
+  the one deliberate dual-emission exception in this family, same reasoning as `NumberInput`: RN's
+  `TextInput.js` never destructures `aria-value*` (flat-only would be silently dropped on native),
+  and `react-native-web` never reads `accessibilityValue` (object-only would be silently dropped on
+  web). Proven on the real DOM by `__tests__/PinInput.dom.test.tsx`.
 - **`secureTextEntry` masking is end-to-end, not cosmetic** — when set, the real hidden `TextInput`
   also receives `secureTextEntry` (so OS-level secure-input behaviour genuinely engages, not just
-  the decorative dots) and `accessibilityValue.text` is masked to one `•` per digit
+  the decorative dots) and the announced value is masked to one `•` per digit
   (`resolvePinInputAccessibility`) instead of the raw value — a screen reader must never speak a
-  masked PIN's digits aloud. Covered by `PinInput.test.ts`'s pure a11y-contract tests and
-  `PinInput.render.test.tsx`'s "secureTextEntry" describe (asserts the real field's
-  `props.secureTextEntry` and `props.accessibilityValue` directly, not just the pure resolver).
+  masked PIN's digits aloud.
 - **1.4.11** — the box border clears 3:1 against the canvas in both `default` (`border.interactive`)
   and `error` (`status.danger.solid` — **not** `status.danger.border`, which `Input.variants.ts`
   already documents as failing 3:1 on several brands in dark mode; same precedent applied here,
@@ -127,8 +136,14 @@ same pattern as `Input`/`ButtonGroup`/`Reorder`'s render-level touch-target chec
   gate on `useReducedMotion()` (WCAG 2.3.3), matching every other animated module.
 - `keyboardType="default"` accepts any pasted/typed character up to `length` with no charset
   validation beyond length — alphanumeric-code validation (if a consuming app needs it) is the
-  caller's responsibility via `status="error"`, same as `Input`'s `errorText` model.
+  caller's responsibility via `status="error"` + `errorText`, same as `Input`'s model.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No library child components at all — the `Array.from({length})` box list renders host `View`/`Text` — 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.