pixelize-native-library 1.0.6

package/lib/module/modules/number-input/NumberInput.variants.js

@@ -0,0 +1,200 @@
+"use strict";
+
+/**
+ * NumberInput's style + behaviour resolution — same split as Input.variants:
+ *  - STRUCTURE (height, width, border WIDTH) lives in the themed `numberInputStructure` /
+ *    `numberInputStepperStructure` resolvers, static per (brand, mode).
+ *  - COLOUR is `status`-driven (never a free `color` prop), resolved from the theme's ROLE colours by
+ *    `resolveNumberInputStatus` — same border token choice as Input, and for the same reason
+ *    (`status.danger.border` fails 3:1 against the canvas on several brands; `status.danger.solid`
+ *    clears it everywhere).
+ *  - VALUE handling (`clampNumberInputValue`, `parseNumberInputDraft`, `canDecrementNumberInput` /
+ *    `canIncrementNumberInput`) and ACCESSIBILITY prop derivation (`resolveNumberInputAccessibility`)
+ *    are kept pure so the clamping/limit contract is unit-testable without rendering React Native.
+ *
+ * Free of `lucide` and of any React tree, so the WCAG + behaviour tests import it directly (mocking
+ * only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** A state, not a brand tone — same reasoning as Input's `status`. */
+
+/** Same floor as Button/Input/Select — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules
+ *  stay isolated. */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+/** Same numbers as Input's sizes, so a NumberInput lines up beside a plain field. */
+export const NUMBER_INPUT_SIZES = {
+  sm: {
+    height: 32,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(32)
+  },
+  md: {
+    height: 40,
+    fontSize: 16,
+    iconSize: 18,
+    hitSlop: slopFor(40)
+  },
+  lg: {
+    height: 48,
+    fontSize: 18,
+    iconSize: 20,
+    hitSlop: slopFor(48)
+  }
+};
+/**
+ * Pressed-state colours for the stepper buttons. Deliberately NOT `bg.sunken`: a stepper carries no
+ * background at rest, so its fill's only edge is against `bg.canvas` — and `bg.sunken` measures only
+ * ~1.0–1.12:1 there (WCAG 1.4.11 needs ≥ 3:1). This reuses Button's own "neutral" solid recipe
+ * (`fg.default` fill / `bg.canvas` label) instead of inventing a new colour: `fg.default` is already
+ * proven ≥ 4.5:1 against `bg.canvas` by the resting-icon test above, and contrast is symmetric, so the
+ * fill clears the 3:1 non-text minimum AND the inverted icon clears 4.5:1 text contrast on it, on
+ * every brand × mode, for free — see the `it.each` measurement in `NumberInput.test.ts`.
+ *
+ * Keyboard/AT focus is a SEPARATE indicator — the offset `border.focus` ring `NumberInput.tsx` draws
+ * per stepper, same geometry/token as Button/Input/Checkbox. This fill is for the touch press only.
+ */
+export function resolveNumberInputStepperPressColors(colors) {
+  return {
+    fill: colors.fg.default,
+    icon: colors.bg.canvas
+  };
+}
+
+/**
+ * Maps `status` onto the theme's role colours — identical reasoning and token choice to Input's
+ * `resolveInputStatus`: the error border deliberately reads `status.danger.solid`, NOT
+ * `status.danger.border` (the latter is the decorative chip/badge outline and measures below 3:1
+ * against the canvas on several brand × mode combinations).
+ */
+export function resolveNumberInputStatus(colors, status) {
+  if (status === "error") {
+    return {
+      border: colors.status.danger.solid
+    };
+  }
+  return {
+    border: colors.border.interactive
+  };
+}
+/** Same fallback contract as `resolveInputAccessibility`: an explicit `accessibilityLabel` always
+ *  wins over the visible label. */
+export function resolveNumberInputAccessibility(input) {
+  const disabled = input.disabled === true;
+  return {
+    accessibilityLabel: input.accessibilityLabel ?? input.label,
+    accessibilityState: {
+      disabled
+    },
+    editable: !disabled
+  };
+}
+
+/** Clamps to [min, max]. Either bound may be absent, meaning "no floor"/"no ceiling" on that side. */
+export function clampNumberInputValue(value, min, max) {
+  let clamped = value;
+  if (min !== undefined) clamped = Math.max(min, clamped);
+  if (max !== undefined) clamped = Math.min(max, clamped);
+  return clamped;
+}
+
+/**
+ * Parses a typed draft to a finite number, or `null` for anything that isn't a complete number yet
+ * ("", "-", ".", "-.") — so the caller can tell "no value yet" apart from a real `0` and doesn't
+ * commit a bogus `NaN`/clamp on every half-typed keystroke.
+ */
+export function parseNumberInputDraft(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed === "-" || trimmed === "." || trimmed === "-.") return null;
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+/** Decrement is blocked once `value` is already at (or below) `min`, or the field is disabled. */
+export function canDecrementNumberInput(input) {
+  if (input.disabled === true) return false;
+  return input.min === undefined || input.value > input.min;
+}
+
+/** Increment is blocked once `value` is already at (or above) `max`, or the field is disabled. */
+export function canIncrementNumberInput(input) {
+  if (input.disabled === true) return false;
+  return input.max === undefined || input.value < input.max;
+}
+
+/**
+ * Structural styles for the field row — layout, height, border WIDTH. No colours (status-driven,
+ * applied inline over this), so this compiles once per theme identity via the `WeakMap`-cached
+ * themed resolver and never rebuilds per render.
+ */
+export const numberInputStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    borderWidth: theme.borderWidths.thin,
+    borderRadius: theme.radii.base
+  },
+  variants: {
+    size: {
+      sm: {
+        height: NUMBER_INPUT_SIZES.sm.height
+      },
+      md: {
+        height: NUMBER_INPUT_SIZES.md.height
+      },
+      lg: {
+        height: NUMBER_INPUT_SIZES.lg.height
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/**
+ * Structural styles for each stepper button. `alignSelf: "stretch"` is the same fix Input's own
+ * `TextInput` carries: without it, the row's `alignItems: "center"` shrinks the button to its
+ * intrinsic content height instead of the row's full `spec.height`, silently voiding the `hitSlop`
+ * touch-target math (a real Wave-1 bug on Input — not one to repeat here). The corner radii on the
+ * outer edge match the row's own `radii.base` so a pressed/focused fill doesn't square off past the
+ * row's rounded corner.
+ */
+export const numberInputStepperStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    alignSelf: "stretch"
+  },
+  variants: {
+    size: {
+      sm: {
+        width: NUMBER_INPUT_SIZES.sm.height
+      },
+      md: {
+        width: NUMBER_INPUT_SIZES.md.height
+      },
+      lg: {
+        width: NUMBER_INPUT_SIZES.lg.height
+      }
+    },
+    position: {
+      leading: {
+        borderRightWidth: theme.borderWidths.thin,
+        borderTopLeftRadius: theme.radii.base,
+        borderBottomLeftRadius: theme.radii.base
+      },
+      trailing: {
+        borderLeftWidth: theme.borderWidths.thin,
+        borderTopRightRadius: theme.radii.base,
+        borderBottomRightRadius: theme.radii.base
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=NumberInput.variants.js.map

package/lib/module/modules/number-input/NumberInput.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createThemedVariants","MIN_TOUCH_TARGET","slopFor","height","Math","max","ceil","NUMBER_INPUT_SIZES","sm","fontSize","iconSize","hitSlop","md","lg","resolveNumberInputStepperPressColors","colors","fill","fg","default","icon","bg","canvas","resolveNumberInputStatus","status","border","danger","solid","interactive","resolveNumberInputAccessibility","input","disabled","accessibilityLabel","label","accessibilityState","editable","clampNumberInputValue","value","min","clamped","undefined","parseNumberInputDraft","raw","trimmed","trim","parsed","Number","isFinite","canDecrementNumberInput","canIncrementNumberInput","numberInputStructure","theme","base","flexDirection","alignItems","borderWidth","borderWidths","thin","borderRadius","radii","variants","size","defaultVariants","numberInputStepperStructure","justifyContent","alignSelf","width","position","leading","borderRightWidth","borderTopLeftRadius","borderBottomLeftRadius","trailing","borderLeftWidth","borderTopRightRadius","borderBottomRightRadius"],"sourceRoot":"../../../../src","sources":["modules/number-input/NumberInput.variants.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/modules/number-input/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/number-input`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The visual/behaviour resolvers (`resolveNumberInputStatus`,
+ * `NUMBER_INPUT_SIZES`, …) stay internal — a consumer configures a NumberInput through its props,
+ * never by importing its internals. The stepper icons are fixed ("minus"/"plus"), so there is no
+ * `icon` prop and nothing to re-export from `core/icon`.
+ */
+
+export { NumberInput } from "./NumberInput.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/number-input/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NumberInput"],"sourceRoot":"../../../../src","sources":["modules/number-input/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,WAAW,QAAQ,kBAAe","ignoreList":[]}

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

@@ -0,0 +1,134 @@
+# pin-input/ — OTP-style multi-box code entry backed by one real, hidden `TextInput`
+
+`PinInput` renders N visual boxes as a pure PROJECTION of a single controlled `value` string. It
+does NOT manage focus across N separate `TextInput`s — that is fragile (advancing on every
+keystroke breaks on backspace/selection) and defeats OS paste (a pasted code would land in
+whichever box happened to be focused instead of filling the whole field). One hidden field is the
+single source of truth; the boxes only render what it already holds.
+
+## Files
+
+| File | Role |
+|------|------|
+| `PinInput.tsx` | The component. The hidden `TextInput`, the box projection, the row `Pressable` (single touch target), the per-box focus ring. |
+| `PinInput.variants.ts` | Pure resolvers (`PIN_INPUT_SIZES`, `resolvePinInputBoxColors`, `clampPinInputValue`, `resolvePinInputActiveIndex`, `isPinInputComplete`, `resolvePinInputAccessibility`) + the themed structural resolvers `pinInputRowStructure` / `pinInputBoxStructure`. No React. |
+| `index.ts` | Public surface: `PinInput`, `PinInputProps`, the closed unions. |
+| `__tests__/PinInput.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target arithmetic + clamp/active-index/complete + a11y contract (incl. `secureTextEntry` masking the resolved `accessibilityValue`). |
+| `__tests__/PinInput.render.test.tsx` | Render: box projection, masking (visual dots + the real field's `secureTextEntry`/`accessibilityValue`), change/paste clamping, `onComplete` firing-once, disabled, focus ring, real rendered hitSlop/box-size touch target. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `length` | `number` | `6` | Number of boxes / max code length. |
+| `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. |
+| `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. |
+| `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`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last — the row `Pressable` is the outermost node. |
+| `testID` | `string` | — | Roots `${testID}-box-{i}`, `${testID}-dot-{i}`, `${testID}-input`. |
+| `accessibilityLabel` | `string` | — | **Required at the type level** — PinInput has no visible text label of its own (e.g. `"6-digit verification code"`). |
+
+## The keystroke/paste contract
+
+`clampPinInputValue(raw, length, keyboardType)` runs on every `onChangeText`: strips non-digits
+when `keyboardType="number-pad"` (so a pasted code like `"123-456"` or `"123 456"` lands clean),
+then clamps to `length` characters either way. Because the hidden field is controlled and receives
+the FULL new text on every change (not per-keystroke deltas), a paste of any length is handled by
+the same code path as typing — no separate paste handler needed.
+
+## `onComplete` — fires once, ref-guarded against inline callback identity
+
+The completion effect depends only on `[value, length]`; a fresh inline `onComplete` reference on
+every parent render (a common pattern: `onComplete={(v) => ...}`) is read through a ref
+(`onCompleteRef.current = onComplete` on every render body) rather than being an effect
+dependency — so it never becomes a *cause* of a re-fire, only ever the thing that gets called
+when `value`/`length` actually change into a complete state. `PinInput.render.test.tsx` asserts
+both: a value transition into "complete" fires once, and an unrelated re-render (even with a brand
+new `onComplete` closure) does not fire again.
+
+## The hidden `TextInput` — why one field, not N
+
+- **Paste UX**: OS paste/autofill delivers the whole code to whichever input has focus. With N
+  separate fields, a paste only fills one box; with one field, `onChangeText` receives the full
+  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.
+
+## Touch target — the ROW, not per-box
+
+Tapping ANY box focuses the same single underlying field — splitting the touch target per box
+would just be N different ways to trigger the identical action, with no independent affordance
+each box could offer on its own. So the whole row is ONE `Pressable` (wrapping both the boxes and
+the hidden field), and `hitSlop` (via the same `slopFor` formula Button/Input use) is computed
+once against the row/box height, not per box. `PinInput.test.ts` asserts
+`boxSize + 2·hitSlop ≥ 44` arithmetically for every size; `PinInput.render.test.tsx` additionally
+asserts the REAL rendered `hitSlop` prop and box dimensions (not just the constants) reach 44dp,
+same pattern as `Input`/`ButtonGroup`/`Reorder`'s render-level touch-target checks.
+
+## Accessibility contract (WCAG)
+
+- **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
+  actually is.
+- **`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
+  (`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).
+- **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,
+  measured in `PinInput.test.ts`).
+- **1.4.3** — the digit glyph / masked dot (`fg.default`) clears 4.5:1 against the canvas; boxes
+  render no explicit background, so the canvas is what it is actually read against (same reasoning
+  as `Input`'s borderless field).
+- **2.4.7** — a focus ring (`border.focus`, offset outside the box — same geometry/token as
+  Button/Input/NumberInput's ring) appears on the ACTIVE box only while the hidden field is
+  genuinely focused (`onFocus`/`onBlur`), never merely because `value` reached that index — a
+  focus indicator that renders while unfocused would misrepresent real keyboard state.
+- **2.5.5 / 2.5.8** — the row reaches ≥ 44dp via `hitSlop` (see "Touch target" above).
+- A disabled field is exempt from the contrast minimum (WCAG 1.4.3) and dims via `opacity: 0.5`,
+  same convention as every other module.
+
+## Patterns copied from Button/Input
+
+1. **Structure vs colour split** — `pinInputRowStructure` / `pinInputBoxStructure` (via
+   `createThemedVariants`) hold only layout numbers; colour is resolved by
+   `resolvePinInputBoxColors` and applied inline.
+2. **Pure, testable resolvers** in `PinInput.variants.ts` — the WCAG + behaviour contract is
+   unit-tested against the real palettes, never eyeballed.
+3. **Closed unions only** (`size` / `status` / `keyboardType`), `style: LayoutStyle` last and once,
+   no `{...rest}`.
+4. **Offset focus ring** — identical geometry/token to Button's, scoped to one box.
+5. **Type-enforced a11y** — `accessibilityLabel` is required, not optional, because this control
+   has no visible text label of its own (same reasoning as Button's icon-only variant).
+
+## Known gaps
+
+- No per-box entrance/error-shake animation — out of scope for v1; `useReducedMotion()` is not
+  imported because nothing here currently animates. If a shake-on-error is added later it MUST
+  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.
+
+## 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.

package/lib/module/modules/pin-input/PinInput.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * PinInput — OTP-style multi-box code entry. Backed by ONE real (near-invisible) `TextInput` that
+ * captures the actual keyboard input; the N visual boxes are a pure PROJECTION of that single
+ * controlled `value` string, never N separately-focusable fields. This is deliberate, not a
+ * shortcut: managing focus across N `TextInput`s is fragile (advancing on every keystroke breaks
+ * on backspace/selection) and defeats OS paste — a pasted code lands in whichever box happened to
+ * be focused instead of filling the whole field. One field, one source of truth.
+ *
+ * Touch target: the ROW is the single 44dp+ touch target (`hitSlop` on the wrapping `Pressable`),
+ * not per-box targets — tapping ANY box focuses the same underlying field, so splitting the target
+ * per box would just be N ways to trigger the identical action.
+ */
+
+import { memo, useEffect, useRef, useState } from "react";
+import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
+import { useTheme } from "../../theme/index.js";
+import { clampPinInputValue, isPinInputComplete, PIN_INPUT_SIZES, pinInputBoxStructure, pinInputRowStructure, resolvePinInputAccessibility, resolvePinInputActiveIndex, resolvePinInputBoxColors } from "./PinInput.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
+export const PinInput = /*#__PURE__*/memo(function PinInput(props) {
+  const {
+    length = 6,
+    value,
+    onValueChange,
+    onComplete,
+    secureTextEntry = false,
+    keyboardType = "number-pad",
+    status = "default",
+    disabled = false,
+    size = "md",
+    autoFocus = false,
+    style,
+    testID,
+    accessibilityLabel
+  } = props;
+  const theme = useTheme();
+  const inputRef = useRef(null);
+  const [focused, setFocused] = useState(false);
+  const spec = PIN_INPUT_SIZES[size];
+  const boxColors = resolvePinInputBoxColors(theme.colors, status);
+  const a11y = resolvePinInputAccessibility({
+    accessibilityLabel,
+    value,
+    disabled,
+    secureTextEntry
+  });
+  const activeIndex = resolvePinInputActiveIndex(value, length);
+
+  // Always reads the LATEST `onComplete` without making it an effect dependency — a caller passing
+  // a fresh inline arrow every render must not re-fire the completion effect on every render, only
+  // on a genuine `value`/`length` change.
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  // Fires exactly once per completion event: `value` is the effect's only real dependency, so an
+  // unrelated re-render while already full does not re-fire, but backspacing out and retyping the
+  // same code IS a new completion and correctly fires again.
+  useEffect(() => {
+    if (isPinInputComplete(value, length)) onCompleteRef.current?.(value);
+  }, [value, length]);
+  const focusInput = () => inputRef.current?.focus();
+  const handleChangeText = raw => {
+    onValueChange(clampPinInputValue(raw, length, keyboardType));
+  };
+  return /*#__PURE__*/_jsxs(Pressable, {
+    testID: testID,
+    accessible: false,
+    disabled: disabled,
+    onPress: disabled ? undefined : focusInput,
+    hitSlop: spec.hitSlop,
+    style: [pinInputRowStructure(theme, {
+      size
+    }), disabled && styles.dimmed, style],
+    children: [Array.from({
+      length
+    }, (_, index) => {
+      const char = value[index];
+      const isActive = focused && index === activeIndex;
+      return /*#__PURE__*/_jsxs(View, {
+        testID: testID ? `${testID}-box-${index}` : undefined,
+        accessibilityRole: "none",
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants",
+        style: [pinInputBoxStructure(theme, {
+          size
+        }), {
+          borderColor: boxColors.border
+        }],
+        children: [isActive && /*#__PURE__*/_jsx(View, {
+          pointerEvents: "none",
+          testID: "pin-input-focus-ring",
+          style: {
+            position: "absolute",
+            top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+            left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+            right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+            bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+            borderWidth: FOCUS_RING_WIDTH,
+            borderColor: theme.colors.border.focus,
+            borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+          }
+        }), char !== undefined && (secureTextEntry ? /*#__PURE__*/_jsx(View, {
+          testID: testID ? `${testID}-dot-${index}` : undefined,
+          style: {
+            width: spec.dotSize,
+            height: spec.dotSize,
+            borderRadius: spec.dotSize / 2,
+            backgroundColor: boxColors.text
+          }
+        }) : /*#__PURE__*/_jsx(Text, {
+          style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+            fontSize: spec.fontSize,
+            color: boxColors.text
+          }],
+          children: char
+        }))]
+      }, index);
+    }), /*#__PURE__*/_jsx(TextInput, {
+      ref: inputRef,
+      testID: testID ? `${testID}-input` : undefined,
+      value: value,
+      onChangeText: handleChangeText,
+      secureTextEntry: secureTextEntry,
+      keyboardType: keyboardType,
+      maxLength: length,
+      autoFocus: autoFocus,
+      autoCorrect: false,
+      autoCapitalize: "none",
+      spellCheck: false,
+      caretHidden: true,
+      textContentType: keyboardType === "number-pad" ? "oneTimeCode" : undefined,
+      editable: a11y.editable,
+      accessibilityLabel: a11y.accessibilityLabel,
+      accessibilityValue: a11y.accessibilityValue,
+      accessibilityState: a11y.accessibilityState,
+      onFocus: () => setFocused(true),
+      onBlur: () => setFocused(false),
+      pointerEvents: "none",
+      style: [StyleSheet.absoluteFill, styles.hiddenInput]
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
+  dimmed: {
+    opacity: 0.5
+  },
+  // Real, focusable, and editable — just visually suppressed. `opacity: 0` (not `display: none`) so
+  // it stays in the accessibility tree and keeps accepting the OS keyboard / paste / autofill.
+  hiddenInput: {
+    opacity: 0,
+    color: "transparent"
+  }
+});
+//# sourceMappingURL=PinInput.js.map

package/lib/module/modules/pin-input/PinInput.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","useEffect","useRef","useState","Pressable","StyleSheet","Text","TextInput","View","useTheme","clampPinInputValue","isPinInputComplete","PIN_INPUT_SIZES","pinInputBoxStructure","pinInputRowStructure","resolvePinInputAccessibility","resolvePinInputActiveIndex","resolvePinInputBoxColors","jsx","_jsx","jsxs","_jsxs","FOCUS_RING_WIDTH","FOCUS_RING_GAP","PinInput","props","length","value","onValueChange","onComplete","secureTextEntry","keyboardType","status","disabled","size","autoFocus","style","testID","accessibilityLabel","theme","inputRef","focused","setFocused","spec","boxColors","colors","a11y","activeIndex","onCompleteRef","current","focusInput","focus","handleChangeText","raw","accessible","onPress","undefined","hitSlop","styles","dimmed","children","Array","from","_","index","char","isActive","accessibilityRole","accessibilityElementsHidden","importantForAccessibility","borderColor","border","pointerEvents","position","top","left","right","bottom","borderWidth","borderRadius","radii","base","width","dotSize","height","backgroundColor","text","fontStyleForWeight","fontWeights","semibold","fontSize","color","ref","onChangeText","maxLength","autoCorrect","autoCapitalize","spellCheck","caretHidden","textContentType","editable","accessibilityValue","accessibilityState","onFocus","onBlur","absoluteFill","hiddenInput","create","opacity"],"sourceRoot":"../../../../src","sources":["modules/pin-input/PinInput.tsx"],"mappings":"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","ignoreList":[]}