pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/theme/tokens/brands/meadow/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#2d6a4f";
 const primary = {
@@ -16,8 +17,8 @@ const primary = {
   900: "#0a2016",
   opacity: buildPrimaryOpacity(PRIMARY_500)
 };
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#2d6a4f",
     to: "#14b8a6"
@@ -118,9 +119,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/radiant/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#cf4e3a";
 const primary = {
@@ -18,8 +19,8 @@ const primary = {
 };
 
 // No `tertiary` override — radiant inherits lavender's purple tertiary, as web ships it.
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#cf4e3a",
     to: "#f59e0b"
@@ -117,9 +118,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/rosewood/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#d16a7e";
 const primary = {
@@ -18,8 +19,8 @@ const primary = {
 };
 
 // No `tertiary` override — rosewood inherits lavender's purple tertiary, as web ships it.
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#d16a7e",
     to: "#fb7185"
@@ -117,9 +118,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/skyline/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#1a3a6b";
 const primary = {
@@ -16,8 +17,8 @@ const primary = {
   900: "#071021",
   opacity: buildPrimaryOpacity(PRIMARY_500)
 };
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#1a3a6b",
     to: "#38bdf8"
@@ -118,9 +119,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/slate/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#6b7280";
 const primary = {
@@ -16,8 +17,8 @@ const primary = {
   900: "#111827",
   opacity: buildPrimaryOpacity(PRIMARY_500)
 };
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#6b7280",
     to: "#818cf8"
@@ -88,9 +89,6 @@ const palette = {
     800: "#6a6a6e",
     900: "#4f4f52"
   },
-  // NOTE: table.hover[500] carries a Cyrillic homoglyph (U+0435) inside the hex, copied
-  // verbatim from web's slate palette (a real upstream bug). Do not "fix" here — it must be
-  // corrected on web and re-copied. Flagged for the web chat; see this task's report.
   table: {
     hover: {
       50: "#fefefe",
@@ -98,7 +96,7 @@ const palette = {
       200: "#f1f1f3",
       300: "#ebebed",
       400: "#e5e5e8",
-      500: "#dfdfе2",
+      500: "#dfdfe2",
       600: "#cbcbcf",
       700: "#a0a0a5",
       800: "#787880",
@@ -121,9 +119,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/storefront/palette.light.js

@@ -1,6 +1,7 @@
 "use strict";
 
-import lavenderPalette from "../lavender/palette.light.js";
+import finalizePalette from "../../builders/finalizePalette.js";
+import { source as lavenderSource } from "../lavender/palette.light.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 const PRIMARY_500 = "#004f4b";
 const primary = {
@@ -20,8 +21,8 @@ const primary = {
 // No `tertiary` override — storefront inherits lavender's purple tertiary, as web ships it.
 // Same for `secondary`, `semantic`, the 9 utility hues, `text`/`header`/`placeholder`/`disabled`,
 // and `transparent`/`black`/`white`.
-const palette = {
-  ...lavenderPalette,
+export const source = {
+  ...lavenderSource,
   gradient: {
     from: "#0c7d77",
     to: "#095e90"
@@ -119,9 +120,9 @@ const palette = {
   },
   boxShadow: {
     primary: buildPrimaryShadowTint(PRIMARY_500),
-    error: lavenderPalette.boxShadow.error,
-    default: lavenderPalette.boxShadow.default
+    error: lavenderSource.boxShadow.error,
+    default: lavenderSource.boxShadow.default
   }
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/brands/zinc/palette.dark.js

@@ -2,6 +2,7 @@
 
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 import buildDarkPalette from "../../builders/buildDarkPalette.js";
+import finalizePalette from "../../builders/finalizePalette.js";
 import light from "./palette.light.js";
 
 /**
@@ -190,7 +191,7 @@ const sidebar = {
     900: "#040405"
   }
 };
-const palette = {
+const palette = finalizePalette({
   ...derived,
   gradient: {
     from: PRIMARY_500,
@@ -217,6 +218,6 @@ const palette = {
     error: derived.boxShadow.error,
     default: "#00000080"
   }
-};
+});
 export default palette;
 //# sourceMappingURL=palette.dark.js.map

package/lib/module/theme/tokens/brands/zinc/palette.light.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import finalizePalette from "../../builders/finalizePalette.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 
 /**
@@ -356,7 +357,7 @@ const gradient = {
   from: "#18181b",
   to: "#52525b"
 };
-const palette = {
+export const source = {
   gradient,
   primary,
   secondary,
@@ -389,5 +390,5 @@ const palette = {
   table,
   disabled
 };
-export default palette;
+export default finalizePalette(source);
 //# sourceMappingURL=palette.light.js.map

package/lib/module/theme/tokens/builders/buildDarkPalette.js

@@ -2,6 +2,7 @@
 
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "./buildBrandTokens.js";
 import { contrastRatio, hexToHsl, hslToHex, withLightness } from "./color.js";
+import finalizePalette from "./finalizePalette.js";
 
 /**
  * Derives a brand's dark palette from its light palette. Every value is computed from the brand's
@@ -249,7 +250,7 @@ export function buildDarkPalette(light) {
     s: SURFACE_SAT,
     l
   })]));
-  return {
+  return finalizePalette({
     ...light,
     // Brand identity: hue preserved, accent lifted as far as a light label allows.
     primary: liftBrand(light.primary, label),
@@ -294,7 +295,7 @@ export function buildDarkPalette(light) {
       error: light.boxShadow.error,
       default: "#00000080"
     }
-  };
+  });
 }
 export default buildDarkPalette;
 //# sourceMappingURL=buildDarkPalette.js.map

package/lib/module/theme/tokens/builders/finalizePalette.js

@@ -0,0 +1,34 @@
+"use strict";
+
+import { AA_TEXT } from "./color.js";
+import { liftToContrast } from "./liftToContrast.js";
+import { buildSemanticText } from "./semanticText.js";
+import { liftSemanticText, namedSurfaces, withSurfaceRungs } from "./surfaceRungs.js";
+const withPlaceholderRung = source => ({
+  ...source,
+  placeholder: {
+    ...source.placeholder,
+    500: liftToContrast(source.placeholder[500], source.background[50], AA_TEXT)
+  }
+});
+
+// The hover row is a SURFACE, so it steps away from the ink rather than the ink moving.
+const withTableHoverRung = source => ({
+  ...source,
+  table: {
+    hover: {
+      ...source.table.hover,
+      500: liftToContrast(source.table.hover[500], source.text[500], AA_TEXT)
+    }
+  }
+});
+export function finalizePalette(source) {
+  const resolved = withSurfaceRungs(withTableHoverRung(withPlaceholderRung(source)));
+  const surfaces = namedSurfaces(resolved);
+  return {
+    ...resolved,
+    semanticText: liftSemanticText(buildSemanticText(resolved.semantic, resolved.backgroundColor.main), surfaces)
+  };
+}
+export default finalizePalette;
+//# sourceMappingURL=finalizePalette.js.map

package/lib/module/theme/tokens/builders/liftToContrast.js

@@ -0,0 +1,44 @@
+"use strict";
+
+import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
+export const DARK_CANVAS_LUMINANCE = 0.2;
+export const isDarkCanvas = canvas => relativeLuminance(canvas) < DARK_CANVAS_LUMINANCE;
+
+// Direction comes from the backdrop, so "away from what it sits on" needs no mode argument.
+export function liftToContrast(hex, backdrop, target) {
+  if (contrastRatio(hex, backdrop) >= target) return hex;
+  const {
+    s
+  } = hexToHsl(hex);
+  const step = isDarkCanvas(backdrop) ? 1 : -1;
+  let {
+    l
+  } = hexToHsl(hex);
+  while (l > 0 && l < 100) {
+    l += step;
+    const next = withLightness(hex, l, s);
+    if (contrastRatio(next, backdrop) >= target) return next;
+  }
+  return withLightness(hex, step === 1 ? 100 : 0, s);
+}
+
+/**
+ * Mirror of `liftToContrast`: walks ink TOWARD the backdrop, stopping at the last step that
+ * still clears `target`. For ink that must stay legible without reading as body copy.
+ */
+export function softenToContrast(hex, backdrop, target) {
+  if (contrastRatio(hex, backdrop) <= target) return hex;
+  const {
+    s,
+    l: start
+  } = hexToHsl(hex);
+  const toward = isDarkCanvas(backdrop) ? -1 : 1;
+  let softest = hex;
+  for (let l = start; l > 0 && l < 100; l += toward) {
+    const next = withLightness(hex, l, s);
+    if (contrastRatio(next, backdrop) < target) break;
+    softest = next;
+  }
+  return softest;
+}
+//# sourceMappingURL=liftToContrast.js.map

package/lib/module/theme/tokens/builders/placeholderInk.js

@@ -0,0 +1,22 @@
+"use strict";
+
+import { contrastRatio } from "./color.js";
+import { liftToContrast } from "./liftToContrast.js";
+import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
+
+/** A field always renders on at least one surface — the first is the reference backdrop. */
+
+/**
+ * The hint ink for a field: the rung the brand authored, guaranteed to clear `PLACEHOLDER_TEXT`
+ * on every surface a field can land on. The surface list is the caller's — a field's fill differs
+ * by platform, the resolution does not.
+ *
+ * It does not walk the rung toward AA in either direction. Held to 4.5 the hint stopped reading
+ * as a hint; softening back down again undershot on the next surface.
+ */
+export const placeholderInkOn = (palette, surfaces) => {
+  const rung = palette.placeholder[500];
+  const hardest = surfaces.reduce((worst, s) => contrastRatio(rung, s) < contrastRatio(rung, worst) ? s : worst);
+  return liftToContrast(rung, hardest, PLACEHOLDER_TEXT);
+};
+//# sourceMappingURL=placeholderInk.js.map

package/lib/module/theme/tokens/builders/semanticText.js

@@ -0,0 +1,14 @@
+"use strict";
+
+import { AA_TEXT } from "./color.js";
+import { liftToContrast } from "./liftToContrast.js";
+export const SEMANTIC_TONES = ["success", "error", "warning", "info"];
+
+// `semantic[tone][500]` is a FILL rung; as ink it measures 1.84-3.68:1 on every light canvas.
+export const buildSemanticText = (semantic, canvas) => ({
+  success: liftToContrast(semantic.success[500], canvas, AA_TEXT),
+  error: liftToContrast(semantic.error[500], canvas, AA_TEXT),
+  warning: liftToContrast(semantic.warning[500], canvas, AA_TEXT),
+  info: liftToContrast(semantic.info[500], canvas, AA_TEXT)
+});
+//# sourceMappingURL=semanticText.js.map

package/lib/module/theme/tokens/builders/surfaceRungs.js

@@ -0,0 +1,44 @@
+"use strict";
+
+import { AA_NON_TEXT, AA_TEXT, contrastRatio } from "./color.js";
+import { liftToContrast } from "./liftToContrast.js";
+
+/**
+ * A hint is held to the non-text floor, not the body-text one. Deliberate: at 4.5 an empty field
+ * reads as one already typed into. See THEME-CONTRACT.md.
+ */
+export const PLACEHOLDER_TEXT = AA_NON_TEXT;
+export const namedSurfaces = p => [...Object.values(p.backgroundColor), p.background[50], p.table.hover[500]];
+
+/** The surface an ink is closest to — clearing it clears every other one. */
+export const hardestSurface = (ink, surfaces) => surfaces.reduce((worst, s) => contrastRatio(ink, s) < contrastRatio(ink, worst) ? s : worst);
+
+// Runs after the hover rung: `table.hover` is one of the surfaces being cleared.
+export function withSurfaceRungs(source) {
+  const surfaces = namedSurfaces(source);
+  const lift = (ink, target) => liftToContrast(ink, hardestSurface(ink, surfaces), target);
+  return {
+    ...source,
+    text: {
+      ...source.text,
+      500: lift(source.text[500], AA_TEXT)
+    },
+    header: {
+      ...source.header,
+      500: lift(source.header[500], AA_TEXT)
+    },
+    // `placeholder` is deliberately absent: the brand authors that rung and it ships untouched.
+    // Its floor is enforced in `placeholderInkOn`, against the surfaces a FIELD renders on.
+    boxborder: {
+      ...source.boxborder,
+      500: lift(source.boxborder[500], AA_NON_TEXT)
+    }
+  };
+}
+export const liftSemanticText = (semanticText, surfaces) => ({
+  success: liftToContrast(semanticText.success, hardestSurface(semanticText.success, surfaces), AA_TEXT),
+  error: liftToContrast(semanticText.error, hardestSurface(semanticText.error, surfaces), AA_TEXT),
+  warning: liftToContrast(semanticText.warning, hardestSurface(semanticText.warning, surfaces), AA_TEXT),
+  info: liftToContrast(semanticText.info, hardestSurface(semanticText.info, surfaces), AA_TEXT)
+});
+//# sourceMappingURL=surfaceRungs.js.map

package/lib/module/theme/tokens/index.js

@@ -23,5 +23,10 @@ export * from "./builders/accentText.js";
 export * from "./builders/buildBrandTokens.js";
 export * from "./builders/buildDarkPalette.js";
 export * from "./builders/color.js";
+export * from "./builders/liftToContrast.js";
+export * from "./builders/placeholderInk.js";
+export * from "./builders/semanticText.js";
+export * from "./builders/finalizePalette.js";
 export * from "./roles/index.js";
+export * from "./assertPalette.js";
 //# sourceMappingURL=index.js.map

package/lib/module/theme/tokens/roles/index.js

@@ -17,8 +17,11 @@
  *    `buildDarkPalette`, so `roleColors(darkPalette)` is correct for free.
  */
 
-import { resolveFilledAccent } from "../builders/accentText.js";
+import { pickOnAccent, resolveFilledAccent } from "../builders/accentText.js";
 import { AA_TEXT, contrastRatio, relativeLuminance } from "../builders/color.js";
+import { placeholderInkOn } from "../builders/placeholderInk.js";
+/** Every surface an enabled field renders on. Disabled fills are exempt from 1.4.3 and excluded. */
+const FIELD_SURFACES = p => [p.backgroundColor.main, p.background[50], p.backgroundColor.muted];
 const RAMP_KEYS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 
 /**
@@ -59,10 +62,12 @@ function strongerFill(ramp, solidRung, label, step) {
 }
 function statusColors(ramp) {
   const filled = resolveFilledAccent(ramp);
+  const text = readableOn(ramp, [ramp[50]]);
   return {
     solid: filled.fill,
     onSolid: filled.label,
-    text: readableOn(ramp, [ramp[50]]),
+    text,
+    onText: pickOnAccent(text),
     subtle: ramp[50],
     border: ramp[200]
   };
@@ -90,6 +95,8 @@ export function roleColors(p) {
       // canvas — a flat `gray[600]` cleared the canvas on every brand but fell to ~3.5:1 against
       // `bg.hover` on radiant/emerald/rosewood, the same class of mistake web shipped twice.
       muted: readableOn(p.gray, [p.background[50], p.backgroundColor.muted]),
+      // A hint is not body copy: `fg.muted` made every empty field read as already filled in.
+      placeholder: placeholderInkOn(p, FIELD_SURFACES(p)),
       subtle: p.gray[500],
       disabled: p.disabled[500]
     },
@@ -111,7 +118,11 @@ export function roleColors(p) {
       solidHover: strongerFill(p.primary, accent.rung, accent.label, 1),
       solidPressed: strongerFill(p.primary, accent.rung, accent.label, 2),
       onSolid: accent.label,
-      text: readableOn(p.primary, [p.backgroundColor.main, p.primary[50]]),
+      // Measured against `bg.sunken` too, not just canvas/`subtle` — an accent-toned chip's resting
+      // label sits on `subtle`, but its PRESSED label sits on `bg.sunken` (`resolveChipPressedBackground`),
+      // which cleared on every brand except slate at 4.398:1 before this surface was added — the same
+      // class of gap `fg.muted`'s own comment documents.
+      text: readableOn(p.primary, [p.backgroundColor.main, p.primary[50], p.background[200]]),
       subtle: p.primary[50]
     },
     status: {

package/lib/typescript/core/a11y/announce.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Native/default counterpart of `announce.web.ts`: the one imperative "say this now" primitive
+ * behind `useAnnounce`. On iOS/Android the OS owns the announcement queue, so this is a direct
+ * `AccessibilityInfo.announceForAccessibility` call and nothing else.
+ *
+ * The `.ts` / `.web.ts` pair (the `keyboard.ts` precedent) is what keeps the DOM code out of the
+ * native dependency graph entirely: Metro resolves `announce.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.
+ *
+ * The de-duplication that stops an unchanged message repeating lives one layer up in `useAnnounce`,
+ * deliberately: both platforms then share one set of semantics, and this primitive speaks every
+ * time it is called — exactly what `announceForAccessibility` does.
+ */
+/**
+ * Returns the process-wide announce function. A hook rather than a bare export so the web half can
+ * own a live region's lifetime without changing this signature; here there is nothing to set up.
+ */
+export declare function useAnnouncer(): (message: string) => void;
+//# sourceMappingURL=announce.d.ts.map

package/lib/typescript/core/a11y/announce.web.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Web implementation of the library's screen-reader announcement primitive. Metro only resolves
+ * this file for a web bundle (see `announce.ts`), so it is the one place that may assume a DOM.
+ *
+ * **Why it exists at all.** `react-native-web@0.21.2` ships
+ * `AccessibilityInfo.announceForAccessibility` as an empty function body
+ * (`dist/exports/AccessibilityInfo/index.js`) — every WCAG 4.1.3 status message in the library is
+ * silent on web without this. The web equivalent is an ARIA live region, which the platform reads
+ * out when its text *changes*, so the whole job here is producing a change a screen reader can see.
+ *
+ * **Why the DOM types are hand-written.** `tsconfig.json` sets `"lib": ["ESNext"]` — `document` and
+ * `HTMLElement` do not exist as types in `src/`, `any` is lint-banned, and augmenting
+ * `react-native`'s types would ship DOM-only APIs to every consumer's native build through
+ * `lib/typescript/**`. A module-local structural surface plus `declare const document` erases
+ * completely at emit, the same contract `keyboard.web.ts` established at this boundary.
+ */
+/**
+ * Retains the shared live region for the lifetime of the calling component, and returns the
+ * announce function. Same shape as `useReducedMotion`'s store: process-wide setup opened by the
+ * first consumer and closed by the last, never one per hook instance.
+ *
+ * Teardown is deferred a task because StrictMode (and any remount) runs mount → unmount → mount
+ * back to back: removing the region synchronously on that middle cleanup would invalidate the fill
+ * the first mount just queued, and the second mount does not re-announce.
+ */
+export declare function useAnnouncer(): (message: string) => void;
+//# sourceMappingURL=announce.web.d.ts.map

package/lib/typescript/core/a11y/index.d.ts

@@ -1,7 +1,26 @@
+/** Test-only: drops the process cache so a suite can assert the pre-probe seed. */
+export declare function resetReducedMotionCache(): void;
 /**
  * Tracks the OS reduce-motion setting (WCAG 2.3.3) so a press/transition animation can be
- * suppressed for a user who has it on. Shared across every animated module — press fades,
- * expand/collapse, toasts — so the setting is read once per mount, not re-implemented per module.
+ * suppressed for a user who has it on. Every animated module reads this one store: ten `<Button>`s
+ * cost one native listener and one bridge round-trip, not ten of each.
+ *
+ * Seeds `true` until the async probe answers: a `false` seed makes `motion.enabled` (and on a
+ * high-tier device `motion.decorative`) true for the first commit AND the first effect pass, which
+ * defeats every correctly-written reduce-motion gate in the library at once.
  */
 export declare function useReducedMotion(): boolean;
+/**
+ * Announces a status message to the screen reader when it becomes present, or changes (WCAG 4.1.3).
+ * `accessibilityLiveRegion` is Android-only, so it alone leaves iOS VoiceOver silent; this reaches
+ * VoiceOver, TalkBack and the browser alike.
+ *
+ * A caller must NOT also put `accessibilityLiveRegion` on the message it renders: on Android that
+ * announces twice. Pass `undefined` for "no message"; a message that stays the same is not repeated.
+ *
+ * The transition rule lives here, on both platforms: `useAnnouncer()` supplies only the platform's
+ * "say this now" primitive (`announceForAccessibility` on native, a shared ARIA live region on web,
+ * where that call is an empty function — see `announce.web.ts`).
+ */
+export declare function useAnnounce(message: string | undefined): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/core/a11y/keyboard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import type { RefObject } from "react";
+import type { View } from "react-native";
+export interface RovingKeysOptions {
+    /** Number of items in the collection. */
+    readonly count: number;
+    /** Index that currently owns `tabIndex={0}`. */
+    readonly activeIndex: number;
+    readonly onActiveIndexChange: (index: number) => void;
+    /** Enter / Space on the container. Omit for a collection with no activation (e.g. a listbox). */
+    readonly onActivate?: (index: number) => void;
+    /** Which arrow keys move. Default `"vertical"`. */
+    readonly orientation?: "vertical" | "horizontal" | "both";
+    /** Wrap past the ends. Default `true`. */
+    readonly loop?: boolean;
+    /** Enables type-to-jump when present; index-aligned with the items. */
+    readonly typeaheadLabels?: readonly string[];
+}
+export declare function useDismissOnEscape(_active: boolean, _onDismiss: () => void): void;
+export declare function useFocusTrap(_ref: RefObject<View | null>, _active: boolean): void;
+export declare function useRovingKeys(_ref: RefObject<View | null>, _active: boolean, _options: RovingKeysOptions): void;
+export declare function useSpaceActivation(_ref: RefObject<View | null>, _onActivate: () => void, _active?: boolean): void;
+/**
+ * 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 declare function focusItemProps(index: number, activeIndex: number): {
+    tabIndex: 0 | -1;
+};
+//# sourceMappingURL=keyboard.d.ts.map