pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/core/a11y/keyboard.js

@@ -0,0 +1,42 @@
+"use strict";
+
+/**
+ * Native/default counterpart of `keyboard.web.ts`. Physical-keyboard interaction is a web concern —
+ * on iOS/Android the OS and the screen reader own key handling — so every hook here is a no-op with
+ * an identical signature.
+ *
+ * The `.ts` / `.web.ts` pair (the `renderWebPortal` precedent) is what keeps the DOM code out of the
+ * native dependency graph entirely: Metro resolves `keyboard.web.ts` only for a web bundle, and Jest
+ * (whose `react-native` preset has no `web` platform) always resolves THIS file. A `Platform.OS`
+ * branch would instead ship the DOM code to native.
+ *
+ * Deliberately import-free at runtime — both imports below are type-only and erase at emit, so the
+ * native closure gains one file of empty function bodies and nothing else.
+ */
+
+export function useDismissOnEscape(_active, _onDismiss) {
+  return;
+}
+export function useFocusTrap(_ref, _active) {
+  return;
+}
+export function useRovingKeys(_ref, _active, _options) {
+  return;
+}
+export function useSpaceActivation(_ref, _onActivate, _active) {
+  return;
+}
+
+/**
+ * The roving half of roving-tabindex: exactly one item in a collection is reachable by Tab, and the
+ * arrow keys move which one. Pure and identical on both platforms — `tabIndex` is a real RN
+ * `ViewProps` key (inert on native), so this needs no platform branch and is duplicated verbatim in
+ * `keyboard.web.ts` rather than shared through a third module (a `.web.ts` importing `./keyboard`
+ * would resolve to itself in a web bundle).
+ */
+export function focusItemProps(index, activeIndex) {
+  return {
+    tabIndex: index === activeIndex ? 0 : -1
+  };
+}
+//# sourceMappingURL=keyboard.js.map

package/lib/module/core/a11y/keyboard.web.js

@@ -0,0 +1,229 @@
+"use strict";
+
+/**
+ * Web implementation of the library's keyboard-interaction helpers. Metro only resolves this file
+ * for a web bundle (see `keyboard.ts`), so it is the one place that may assume a DOM.
+ *
+ * **Why the DOM types are hand-written.** `tsconfig.json` sets `"lib": ["ESNext"]` — there is no DOM
+ * lib in this repo, so `document`, `HTMLElement` and `KeyboardEvent` do not exist as types. The
+ * alternatives are worse: `any` is banned by lint, and augmenting `react-native`'s own types would
+ * ship through `lib/typescript/**` and make `onKeyDown` look valid on native for every consumer. A
+ * module-local structural surface plus `declare const document` erases completely at emit and
+ * resolves to the browser's real `document` at runtime, with no cast wider than the one
+ * `renderWebPortal.web.ts` already established at this same boundary.
+ */
+
+import { useEffect, useRef } from "react";
+/** `typeof` rather than a null check: a bare `document` reference throws outside a browser. */
+function getDocument() {
+  return typeof document === "undefined" ? undefined : document;
+}
+
+/**
+ * `react-native-web` forwards a component's ref to the host element it renders, so a
+ * `RefObject<View>` really holds a DOM node here. The double cast is the same "assume a DOM in the
+ * `.web` file only" contract `renderWebPortal.web.ts` uses for its portal container.
+ */
+function domNode(ref) {
+  return ref.current ?? null;
+}
+const TABBABLE_SELECTOR = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),' + 'textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+function tabbablesWithin(node) {
+  return node === null ? [] : Array.from(node.querySelectorAll(TABBABLE_SELECTOR));
+}
+/**
+ * Escape closes the overlay. Listens on `document` in the CAPTURE phase for two reasons: the
+ * outermost open overlay sees the key first (so a dialog inside a dialog closes the inner one only
+ * once it is the outermost listener to `stopPropagation()`), and it survives a focused `TextInput`
+ * whose own handler calls `stopPropagation()` during bubbling.
+ */
+export function useDismissOnEscape(active, onDismiss) {
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+  useEffect(() => {
+    const doc = getDocument();
+    if (!active || doc === undefined) return;
+    const handleKeyDown = event => {
+      // "Esc" is the legacy IE/Edge spelling; still emitted by some embedded webviews.
+      if (event.key !== "Escape" && event.key !== "Esc") return;
+      event.stopPropagation();
+      onDismissRef.current();
+    };
+    doc.addEventListener("keydown", handleKeyDown, true);
+    return () => doc.removeEventListener("keydown", handleKeyDown, true);
+  }, [active]);
+}
+
+/**
+ * Confines Tab to the subtree under `ref` while `active`, and restores focus to whatever had it when
+ * the trap opened. Restore is folded in deliberately — a trap without it drops the user at the top of
+ * the document every time an overlay closes, which is the same bug in a different place.
+ *
+ * The `contains` guard before restoring matches `react-native-web`'s own `ModalFocusTrap`: the
+ * trigger may have unmounted while the overlay was open, and focusing a detached node throws in some
+ * engines. Skipping the restore lets focus fall to `<body>` instead.
+ */
+export function useFocusTrap(ref, active) {
+  useEffect(() => {
+    const doc = getDocument();
+    if (!active || doc === undefined) return;
+    const restoreTo = doc.activeElement;
+    tabbablesWithin(domNode(ref))[0]?.focus();
+    const handleKeyDown = event => {
+      if (event.key !== "Tab") return;
+      const items = tabbablesWithin(domNode(ref));
+      const first = items[0];
+      const last = items[items.length - 1];
+      if (first === undefined || last === undefined) {
+        // Nothing tabbable inside: Tab must still not escape the overlay.
+        event.preventDefault();
+        return;
+      }
+      const current = doc.activeElement;
+      if (event.shiftKey && current === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && current === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    doc.addEventListener("keydown", handleKeyDown, true);
+    return () => {
+      doc.removeEventListener("keydown", handleKeyDown, true);
+      if (restoreTo !== null && doc.contains(restoreTo)) restoreTo.focus();
+    };
+  }, [active, ref]);
+}
+const TYPEAHEAD_RESET_MS = 500;
+
+/**
+ * Arrow/Home/End/Enter/Space navigation for a composite widget (menu, tab list, listbox, toolbar),
+ * paired with `focusItemProps` for the tabindex half. Listens on the CONTAINER node, not `document`,
+ * so two collections on one page never fight over the same arrow key.
+ */
+export function useRovingKeys(ref, active, options) {
+  // Options are a fresh object each render; holding them in a ref keeps the listener subscribed once
+  // instead of detaching and re-attaching on every parent render.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    if (!active) return;
+    const node = domNode(ref);
+    if (node === null) return;
+    let buffer = "";
+    let bufferedAt = 0;
+    const moveTo = next => {
+      const {
+        count,
+        onActiveIndexChange,
+        loop = true
+      } = optionsRef.current;
+      if (count <= 0) return;
+      onActiveIndexChange(loop ? (next % count + count) % count : Math.min(Math.max(next, 0), count - 1));
+    };
+    const handleKeyDown = event => {
+      // Alt+Left is browser Back and Ctrl+Arrow switches Spaces on macOS — a composite widget must
+      // not swallow a shortcut the user aimed at the browser or the OS.
+      if (event.ctrlKey || event.metaKey || event.altKey) return;
+      const opts = optionsRef.current;
+      const orientation = opts.orientation ?? "vertical";
+      const vertical = orientation !== "horizontal";
+      const horizontal = orientation !== "vertical";
+      const {
+        key
+      } = event;
+      if (vertical && key === "ArrowDown" || horizontal && key === "ArrowRight") {
+        event.preventDefault();
+        moveTo(opts.activeIndex + 1);
+        return;
+      }
+      if (vertical && key === "ArrowUp" || horizontal && key === "ArrowLeft") {
+        event.preventDefault();
+        moveTo(opts.activeIndex - 1);
+        return;
+      }
+      if (key === "Home") {
+        event.preventDefault();
+        moveTo(0);
+        return;
+      }
+      if (key === "End") {
+        event.preventDefault();
+        moveTo(opts.count - 1);
+        return;
+      }
+      if (key === "Enter" || key === " " || key === "Spacebar") {
+        event.preventDefault();
+        opts.onActivate?.(opts.activeIndex);
+        return;
+      }
+      const labels = opts.typeaheadLabels;
+      if (labels === undefined) return;
+      if (key.length !== 1) return;
+      const now = Date.now();
+      buffer = now - bufferedAt > TYPEAHEAD_RESET_MS ? key : buffer + key;
+      bufferedAt = now;
+      // Repeating one letter cycles through the items starting with it, rather than searching "aa".
+      const repeatedLetter = buffer.split("").every(char => char === buffer[0]);
+      const needle = (repeatedLetter ? buffer.slice(0, 1) : buffer).toLowerCase();
+      for (let step = 1; step <= labels.length; step += 1) {
+        const index = (opts.activeIndex + step) % labels.length;
+        if (labels[index]?.toLowerCase().startsWith(needle) === true) {
+          event.preventDefault();
+          opts.onActiveIndexChange(index);
+          return;
+        }
+      }
+    };
+    node.addEventListener("keydown", handleKeyDown, true);
+    return () => node.removeEventListener("keydown", handleKeyDown, true);
+  }, [active, ref]);
+}
+
+/**
+ * Makes Space activate a control whose role is not `button`.
+ *
+ * `react-native-web`'s `PressResponder.isValidKeyPress` is `Enter || (Space && isButtonish)`, and
+ * `isButtonish` needs a `button` tag or `role="button"`. `role="checkbox"`, `"radio"`, `"tab"` and
+ * `"menuitem"` all render as a `div`, so today Space neither activates them nor gets
+ * `preventDefault()`ed — it scrolls the page instead. Changing those roles to `button` would fix the
+ * key and break the screen reader, so the fix belongs here.
+ *
+ * Enter is left alone: RNW already presses on Enter for every role.
+ */
+export function useSpaceActivation(ref, onActivate, active = true) {
+  const onActivateRef = useRef(onActivate);
+  onActivateRef.current = onActivate;
+  useEffect(() => {
+    if (!active) return;
+    const node = domNode(ref);
+    if (node === null) return;
+    let held = false;
+    const handleKeyDown = event => {
+      if (event.key !== " " && event.key !== "Spacebar") return;
+      event.preventDefault();
+      // Auto-repeat would otherwise toggle a checkbox dozens of times while the key is held.
+      if (held) return;
+      held = true;
+      onActivateRef.current();
+    };
+    const handleKeyUp = event => {
+      if (event.key === " " || event.key === "Spacebar") held = false;
+    };
+    node.addEventListener("keydown", handleKeyDown, true);
+    node.addEventListener("keyup", handleKeyUp, true);
+    return () => {
+      node.removeEventListener("keydown", handleKeyDown, true);
+      node.removeEventListener("keyup", handleKeyUp, true);
+    };
+  }, [active, ref]);
+}
+
+/** Duplicated verbatim from `keyboard.ts` — see the note there on why it is not shared. */
+export function focusItemProps(index, activeIndex) {
+  return {
+    tabIndex: index === activeIndex ? 0 : -1
+  };
+}
+//# sourceMappingURL=keyboard.web.js.map

package/lib/module/core/a11y/labels.js

@@ -0,0 +1,24 @@
+"use strict";
+
+/**
+ * Accessibility label phrasings that MUST read identically wherever the same action appears
+ * (WCAG 3.2.4 Consistent Identification).
+ *
+ * These live in `core/` rather than in each module because the failure mode is invisible from
+ * inside any one module: `chip`, `filter-sheet` and `file-upload` each independently invented a
+ * wording for the same X affordance ("Remove Foo" / "Foo, remove filter" / "Selected file: Foo,
+ * remove"), and a screen-reader user meeting all three on one screen heard three different names
+ * for one action. A module-local constant cannot catch that; a shared one cannot drift.
+ */
+
+/**
+ * The one phrasing for a control that removes `name` from the current selection/list.
+ *
+ * Action-first, because the affordance is a button and its label should say what pressing it does.
+ * Pass the plain user-facing name — never pre-qualify it ("filter Foo", "Selected file: Foo"); the
+ * surrounding row already supplies that context to assistive tech.
+ */
+export function removeAccessibilityLabel(name) {
+  return `Remove ${name}`;
+}
+//# sourceMappingURL=labels.js.map

package/lib/module/core/device/MODULE.md

@@ -0,0 +1,47 @@
+# core/device — the device tier
+
+One probe, once per process, behind a `globalThis` slot. `MOTION_TIER` (`core/motion/config.ts`) and
+`VirtualList`'s windowing both read it. **Internal only** — not a package subpath export.
+
+| Export | Role |
+|--------|------|
+| `probeTier()` | The raw hardware answer, cached per process. |
+| `resolveDeviceTier(reducedMotion)` | `probeTier()` plus the reduce-motion demotion. What `useMotion` calls. |
+| `useDeviceTier()` | The hook form — `resolveDeviceTier` over the reduce-motion store. |
+| `setDeviceTierForTests(tier)` | Overrides (or, with `undefined`, clears) the cached slot. |
+| `getListWindowSize(tier)` | Rows to keep windowed. No current caller. |
+
+## The mapping
+
+| Platform | Signals | Result |
+|----------|---------|--------|
+| Android | `Platform.Version` < 29 (Android 9 and older) | `low` |
+| Android | short edge ≤ 720 physical px (`Dimensions.get('screen')` × `scale`) | `low` |
+| Android | anything else | `mid` |
+| iOS | `Platform.Version` major ≤ 15 | `low` |
+| iOS | major = 16 | `mid` |
+| iOS | major ≥ 17, or unreadable | `high` |
+| anything else | — | `mid` |
+
+**Why these.** API 29 is where Google's security patches stop, and no device below it has post-2018
+silicon. A 720p-or-smaller panel is the entry/Go-edition signature — 1080p has been the mid-range
+floor since ~2017 — and it is the one free signal that catches a *new* 2GB device, which API level
+alone never would. On iOS, Apple's support cutoffs map 1:1 onto SoCs: iOS 15 was the last release
+for the A10 (iPhone 7), iOS 16 the last for the A11 (iPhone 8 / X).
+
+**Android never resolves `high`.** `high` buys blur and decorative motion; neither API level nor
+panel resolution proves the RAM/GPU headroom to spend on them. Promotion needs a memory reading —
+`expo-device`'s `totalMemory` / `deviceYearClass` is the signal, and it is not a dependency of this
+repo. Until it is, Android is `low` or `mid`, so this probe only ever *demotes*.
+
+**iOS demotes only on positive evidence.** An unreadable `Platform.Version` (Jest, a stubbed
+Platform) stays `high`, so a missing signal never silently strips motion from every iOS device.
+
+## What this replaced
+
+The shipped probe read `Platform.constants.reactNativeVersion.minor` — the **bundler's** RN version —
+and compared it to a device year class: `if (Platform.OS === 'android' && yearClass < 74) tier =
+'low'`. RN is 0.86, so the value was always 86 and the branch never fired: **every** Android device
+resolved `mid`, including the 2GB target the tier system exists for, and every iOS device resolved
+`high` unconditionally. It survived because ~15 suites pin the tier with `setDeviceTierForTests` and
+`probeTier` itself had no test. `__tests__/probeTier.test.ts` now covers it, and pre-seeds nothing.

package/lib/module/core/device/index.js

@@ -0,0 +1,91 @@
+"use strict";
+
+import { useMemo } from 'react';
+import { Dimensions, Platform } from 'react-native';
+import { useReducedMotion } from "../a11y/index.js";
+const TIER_SLOT = '__PIXELIZE_DEVICE_TIER__';
+/** Android 9 and older: pre-2019 silicon, and off Google's security-patch list since 2022. */
+const ANDROID_LOW_API = 29;
+/** 720p-or-smaller panel — the entry/Go-edition signature; 1080p has been the mid-range floor since ~2017. */
+const ANDROID_LOW_SHORT_SIDE_PX = 720;
+/** iOS 15 was the last release for the A10 (iPhone 7) and older. */
+const IOS_LOW_MAX_MAJOR = 15;
+/** iOS 16 was the last release for the A11 (iPhone 8 / X). */
+const IOS_MID_MAJOR = 16;
+
+/** Physical pixels across the display's short edge; 0 when the metrics are unreadable. */
+function shortSidePx() {
+  const {
+    width,
+    height,
+    scale
+  } = Dimensions.get('screen');
+  // Negated comparisons on purpose: a stubbed Dimensions can hand back undefined or NaN.
+  if (!(width > 0) || !(height > 0) || !(scale > 0)) return 0;
+  return Math.round(Math.min(width, height) * scale);
+}
+
+/**
+ * The one real hardware probe. Android is classified by API level (device age) and panel resolution
+ * (hardware class); iOS by the major OS version, since Apple's support cutoffs map 1:1 onto SoCs.
+ *
+ * Android never resolves `high`: neither signal proves the RAM/GPU headroom `high` spends (blur,
+ * decorative motion), so promotion there needs a memory reading this library does not have.
+ * `expo-device` (`totalMemory` / `deviceYearClass`) is the signal that would justify it.
+ */
+function detectTier() {
+  if (Platform.OS === 'android') {
+    if (Platform.Version < ANDROID_LOW_API) return 'low';
+    const shortSide = shortSidePx();
+    if (shortSide > 0 && shortSide <= ANDROID_LOW_SHORT_SIDE_PX) return 'low';
+    return 'mid';
+  }
+  if (Platform.OS === 'ios') {
+    const major = Number.parseInt(Platform.Version, 10);
+    // Unreadable version (Jest, a stubbed Platform) — demote only on positive evidence of old silicon.
+    if (Number.isNaN(major)) return 'high';
+    if (major <= IOS_LOW_MAX_MAJOR) return 'low';
+    if (major === IOS_MID_MAJOR) return 'mid';
+    return 'high';
+  }
+  return 'mid';
+}
+
+/** Probes once per process; the answer cannot change while the app runs. */
+export function probeTier() {
+  const cached = globalThis[TIER_SLOT];
+  if (cached) return cached;
+  const tier = detectTier();
+  globalThis[TIER_SLOT] = tier;
+  return tier;
+}
+
+/** For tests — override the probed tier. */
+export function setDeviceTierForTests(tier) {
+  globalThis[TIER_SLOT] = tier;
+}
+
+/**
+ * The tier a caller should act on. Reduce-motion demotes `high`: the OS asked for less, so the
+ * headroom stays unspent. Split out of the hook so `useMotion` can resolve both from one store read.
+ */
+export function resolveDeviceTier(reducedMotion) {
+  const tier = probeTier();
+  if (reducedMotion && tier === 'high') return 'mid';
+  return tier;
+}
+export function useDeviceTier() {
+  const reducedMotion = useReducedMotion();
+  return useMemo(() => resolveDeviceTier(reducedMotion), [reducedMotion]);
+}
+export function getListWindowSize(tier) {
+  switch (tier) {
+    case 'low':
+      return 5;
+    case 'high':
+      return 15;
+    default:
+      return 10;
+  }
+}
+//# sourceMappingURL=index.js.map

package/lib/module/core/heading/MODULE.md

@@ -0,0 +1,38 @@
+# core/heading
+
+The single place that types and documents `aria-level` — the prop `react-native-web` needs to turn
+`accessibilityRole="header"` into the right `<h1>`-`<h6>`, instead of always `<h1>`.
+
+## Why this exists
+
+`react-native-web` (`AccessibilityUtil/propsToAccessibilityComponent.js`) renders any
+`accessibilityRole="header"` element as `<h1>` **unless** `aria-level` is also set — so a screen
+with several headings and no level renders every one of them as `<h1>`, destroying the outline a
+screen reader's rotor navigates (WCAG 1.3.1 / 2.4.6).
+
+React Native 0.86 declares neither `aria-level` nor `accessibilityLevel` on `Text`'s or `View`'s
+`AccessibilityProps`, so passing it doesn't typecheck through the real components. Following
+`select/Select.variants.ts`'s `SELECT_LISTBOX_ROLE` precedent for the same class of gap,
+`HeadingText`/`HeadingView` widen the prop types on these two audited lines — never a cast at a call
+site. It's a type gap, not a runtime one: RNW reads the prop, and native drops props its view config
+doesn't declare, so `aria-level` is a safe no-op there.
+
+## Exports
+
+- `HeadingLevel` — `1 | 2 | 3 | 4 | 5 | 6`.
+- `HeadingText` / `HeadingView` — `Text` / `View` widened to accept `aria-level`.
+- `HEADING_LEVEL` — the library's own fixed outline (`screen: 1`, `section: 2`, `subsection: 3`) for
+  components whose level is a structural decision this library makes, not the caller's
+  (`AppBar`, `Section`, `SectionList`, `EmptyState`, `DataTable` headers). Components whose level is
+  the *caller's* choice — `Heading`'s `variant`, a `Markdown` document's `#`/`##`, `RichText`'s
+  `<h1>`-`<h6>` — derive `aria-level` from that choice instead.
+
+## Not a context-propagated offset
+
+A `Markdown` block embedded under a `Screen` with its own `AppBar` (`<h1>`) does not renumber itself
+relative to that ancestor. This library cannot see the screen its output lands in — an app supplies
+its own chrome around `Screen` — so a context-derived offset would be correct only inside this
+repo's own tree and silently wrong the moment a consumer's structure differs from it. Fixed,
+predictable levels per component are what a consumer can read, test, and reason about; getting the
+overall page outline right (one `<h1>`, headings nesting under it) is the consuming app's job, same
+as it is on web.

package/lib/module/core/heading/index.js

@@ -0,0 +1,45 @@
+"use strict";
+
+/**
+ * Heading semantics — the ONE place the library types `aria-level` in, and the one place its
+ * heading outline is written down.
+ *
+ * `react-native-web` turns `accessibilityRole="header"` into a real `<h*>` element, taking the
+ * level from `aria-level` and falling back to `<h1>` when it is absent
+ * (`AccessibilityUtil/propsToAccessibilityComponent.js`). So a heading rendered without a level is
+ * not "a heading with an unspecified level" on web — it is an `<h1>`, and a screen whose every
+ * heading is an `<h1>` has no outline for a screen-reader user to navigate (WCAG 1.3.1 / 2.4.6).
+ *
+ * React Native 0.86 declares neither `aria-level` nor `accessibilityLevel` on `AccessibilityProps`,
+ * so `Text` and `View` reject the prop at compile time. Following `SELECT_LISTBOX_ROLE`'s
+ * precedent, the widening lives on the two audited lines below instead of a cast at each of the
+ * nine call sites. It is a type gap, not a runtime one: RNW reads the prop, and native drops props
+ * its view config does not declare.
+ */
+
+import { Text as RNText, View as RNView } from "react-native";
+
+/** The levels the DOM has. */
+
+export const HeadingText = RNText;
+export const HeadingView = RNView;
+
+/**
+ * The library's outline. Levels are FIXED per component, never derived from render context: a
+ * design library cannot see the page its consumer embeds it in (an app renders its own chrome
+ * around `Screen`), so a context-propagated offset would look correct inside this repo's tree and
+ * still be wrong the moment the consumer supplies the outer structure. Fixed levels are what a
+ * consumer can read, predict and test.
+ *
+ * Components whose level is the author's own explicit choice — `Heading`'s `variant`, a `Markdown`
+ * document's `#`/`##`, a `RichText` `<h3>` — carry that choice through instead of these.
+ */
+export const HEADING_LEVEL = {
+  /** The screen's own title (`AppBar`). One per screen. */
+  screen: 1,
+  /** A top-level division of a screen: `Section`, `SectionList` headers, `EmptyState`. */
+  section: 2,
+  /** A heading inside such a division: `DataTable`'s column headers. */
+  subsection: 3
+};
+//# sourceMappingURL=index.js.map

package/lib/module/core/icon/Icon.js

@@ -0,0 +1,37 @@
+"use strict";
+
+import { View } from 'react-native';
+import { resolveIcon } from "./resolve.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * `aria-hidden`, not the `accessibilityElementsHidden` + `importantForAccessibility` pair used
+ * elsewhere in the library: react-native-web forwards neither of those, so on web the pair hides
+ * nothing. RN's `View` translates `aria-hidden` into both on native.
+ */
+export function Icon({
+  name,
+  size,
+  color,
+  strokeWidth = 2,
+  label
+}) {
+  const Glyph = resolveIcon(name);
+  const glyph = /*#__PURE__*/_jsx(Glyph, {
+    size: size,
+    color: color,
+    strokeWidth: strokeWidth
+  });
+  if (label === undefined) {
+    return /*#__PURE__*/_jsx(View, {
+      "aria-hidden": true,
+      children: glyph
+    });
+  }
+  return /*#__PURE__*/_jsx(View, {
+    accessible: true,
+    accessibilityRole: "image",
+    accessibilityLabel: label,
+    children: glyph
+  });
+}
+//# sourceMappingURL=Icon.js.map

package/lib/module/core/icon/MODULE.md

@@ -1,8 +1,8 @@
 # core/icon — shared icon registry
 
 Every module's `icon` prop takes a NAME from `IconName`, never a `ReactNode` — same discipline as
-`tone`/`variant` elsewhere in the contract. Hoisted out of `button/` (where it first landed) so the
-other 16 v1 components import one registry instead of each re-copying its own.
+`tone`/`variant` elsewhere in the contract. Hoisted out of `button/` (where it first landed) so
+every one of the 39 shipped modules imports one registry instead of each re-copying its own.
 
 ## Files
 
@@ -10,6 +10,30 @@ other 16 v1 components import one registry instead of each re-copying its own.
 |------|------|
 | `index.tsx` | `Icon` component + `ICON_COMPONENTS` map + the `IconName` union. |
 
+## Accessibility contract (WCAG 1.3.1 / 1.1.1)
+
+`Icon` is decorative BY DEFAULT — every render wraps the glyph in a `View` carrying `aria-hidden`.
+Pass `label` (optional) for the rare icon that carries information no neighbouring text repeats
+(a glyph-only button, a status dot with no label beside it); that renders `accessible` +
+`accessibilityRole="image"` + `accessibilityLabel={label}` instead.
+
+- **Why `aria-hidden`, not the `accessibilityElementsHidden` + `importantForAccessibility` pair used
+  elsewhere in this library**: `react-native-web` forwards neither of those two props, so on web the
+  pair hides nothing — an icon built on it alone looks correct under the native Jest project and
+  ships silently-wrong on web. RN's own `View` translates `aria-hidden` into both native props
+  itself (`View.js`), so one prop covers both platforms.
+- **Why decorative-by-default, not opt-in-hidden**: every consumer in this catalogue that renders a
+  meaningful glyph already provides a text label beside it (a button's own `accessibilityLabel`, a
+  banner's title/message) — the icon was ALWAYS meant to be redundant, and most call sites already
+  hand-wrapped it in a hidden `View` to say so. The one that didn't (`Banner`'s tone glyph) shipped
+  an exposed, unlabelled glyph to assistive tech — a per-consumer mistake that recurred because the
+  default made it easy to forget, not a `Banner`-specific defect. Flagged prominently: `label` is new
+  public API on `IconProps`/`IconComponent` callers that pass it through `Icon` directly (most
+  modules resolve their own glyph via `resolveIcon` and never touch this prop).
+- `__tests__/Icon.render.test.tsx` pins both states on the native project; `__tests__/Icon.dom.test.tsx`
+  proves the same contract lands as a real DOM `aria-hidden`/`role="img"` attribute under
+  `jest.web.config.js` — the native assertion alone cannot catch a prop RNW silently drops.
+
 ## Pattern (do not deviate)
 
 - Icons are DEEP-IMPORTED from `lucide-react-native/icons/<kebab-name>`, never the barrel
@@ -27,9 +51,19 @@ devDependencies here for local build/typecheck/test only.
 
 ## Known gaps
 
-- Catalogue is a starter set (the icons Button needed). Add names as later components need them.
-  Latest addition: `filter` (`filter-sheet`'s trigger glyph — a consumer composes it into its own
-  Button; `filter-sheet` itself renders no trigger). Deep-imports from lucide's `funnel` module:
-  lucide renamed the `filter` icon to `funnel` and only left a `.d.ts` type alias at the old path
-  (no runtime file there) — confirmed by resolving `lucide-react-native/icons/funnel` before adding
-  this entry, the same trap `more-horizontal` (now `ellipsis`) already hit once in this registry.
+- Catalogue started as a starter set (the icons Button needed) and has grown one batch at a time —
+  69 glyphs as of the 2026-07 addition of `rich-text-editor`'s toolbar set (`bold`, `italic`,
+  `underline`, `strikethrough`, `code`, `square-code`, `heading-1/2/3`, `quote`, `list-ordered`,
+  `list-checks`, `at-sign`), on top of the earlier navigation + ticket-detail names for the
+  tickets-native consumer (`layout-dashboard`, `kanban`, `calendar`, `tag`, `flag`, … — see the
+  inline comment above `ICON_COMPONENTS` for the full list). Add names as later components need them.
+- `filter` deep-imports from lucide's `funnel` module: lucide renamed the `filter` icon to `funnel`
+  and only left a `.d.ts` type alias at the old path (no runtime file there) — confirmed by
+  resolving `lucide-react-native/icons/funnel` before adding this entry, the same trap
+  `more-horizontal` (now `ellipsis`) already hit once in this registry.
+
+## 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.

package/lib/module/core/icon/icons/arrow-down.js

@@ -0,0 +1,10 @@
+"use strict";
+
+import ArrowDown from "lucide-react-native/icons/arrow-down";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function IconArrowDown(props) {
+  return /*#__PURE__*/_jsx(ArrowDown, {
+    ...props
+  });
+}
+//# sourceMappingURL=arrow-down.js.map

package/lib/module/core/icon/icons/arrow-left.js

@@ -0,0 +1,10 @@
+"use strict";
+
+import ArrowLeft from "lucide-react-native/icons/arrow-left";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function IconArrowLeft(props) {
+  return /*#__PURE__*/_jsx(ArrowLeft, {
+    ...props
+  });
+}
+//# sourceMappingURL=arrow-left.js.map

package/lib/module/core/icon/icons/arrow-right.js

@@ -0,0 +1,10 @@
+"use strict";
+
+import ArrowRight from "lucide-react-native/icons/arrow-right";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function IconArrowRight(props) {
+  return /*#__PURE__*/_jsx(ArrowRight, {
+    ...props
+  });
+}
+//# sourceMappingURL=arrow-right.js.map