pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/unread-badge/MODULE.md

@@ -0,0 +1,20 @@
+# unread-badge/ — compact unread count pill
+
+`UnreadBadge` shows a danger-toned count pill, clamped to `9+`. Returns `null` when `count` is 0.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `count` | `number` | — | Required. Hidden when `<= 0`. |
+| `size` | `sm \| md` | `md` | Closed union. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last in array. |
+| `testID` | `string` | — | |
+
+## Files
+
+| File | Role |
+|------|------|
+| `UnreadBadge.tsx` | Component. |
+| `UnreadBadge.variants.ts` | Resolvers + structure. |
+| `index.ts` | Public surface. |

package/lib/module/modules/unread-badge/UnreadBadge.js

@@ -0,0 +1,45 @@
+"use strict";
+
+/**
+ * UnreadBadge — a compact count pill for chat/notification overflow ("9+"). Renders nothing when
+ * `count` is 0. Positioned by the consumer (typically absolute on an icon parent).
+ */
+
+import { memo } from "react";
+import { Text, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { formatUnreadCount, resolveUnreadBadgeAccessibility, resolveUnreadBadgeColors, unreadBadgeStructure, UNREAD_BADGE_SIZES } from "./UnreadBadge.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const UnreadBadge = /*#__PURE__*/memo(function UnreadBadge({
+  count,
+  size = "md",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  if (count <= 0) return null;
+  const colors = resolveUnreadBadgeColors(theme.colors);
+  const a11y = resolveUnreadBadgeAccessibility({
+    count
+  });
+  const spec = UNREAD_BADGE_SIZES[size];
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: a11y.accessible,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    style: [unreadBadgeStructure(theme, {
+      size
+    }), {
+      backgroundColor: colors.fill
+    }, style],
+    children: /*#__PURE__*/_jsx(Text, {
+      style: [theme.fontStyleForWeight(theme.fontWeights.bold), {
+        fontSize: spec.fontSize,
+        color: colors.text
+      }],
+      children: formatUnreadCount(count)
+    })
+  });
+});
+//# sourceMappingURL=UnreadBadge.js.map

package/lib/module/modules/unread-badge/UnreadBadge.variants.js

@@ -0,0 +1,66 @@
+"use strict";
+
+/**
+ * UnreadBadge style resolution — structure in themed resolvers, colour from role tokens.
+ * Free of React so WCAG tests import directly.
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const UNREAD_BADGE_SIZES = {
+  sm: {
+    minWidth: 16,
+    height: 16,
+    fontSize: 10,
+    paddingHorizontal: 3
+  },
+  md: {
+    minWidth: 20,
+    height: 20,
+    fontSize: 11,
+    paddingHorizontal: 4
+  }
+};
+export const UNREAD_BADGE_MAX_DISPLAY = 9;
+export function formatUnreadCount(count) {
+  if (count > UNREAD_BADGE_MAX_DISPLAY) return `${UNREAD_BADGE_MAX_DISPLAY}+`;
+  return String(count);
+}
+export function resolveUnreadBadgeColors(colors) {
+  return {
+    fill: colors.status.danger.solid,
+    text: colors.status.danger.onSolid
+  };
+}
+export function resolveUnreadBadgeAccessibility(input) {
+  const label = input.count > UNREAD_BADGE_MAX_DISPLAY ? `${UNREAD_BADGE_MAX_DISPLAY + 1} or more unread` : `${input.count} unread`;
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: label
+  };
+}
+export const unreadBadgeStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      sm: {
+        minWidth: UNREAD_BADGE_SIZES.sm.minWidth,
+        height: UNREAD_BADGE_SIZES.sm.height,
+        paddingHorizontal: UNREAD_BADGE_SIZES.sm.paddingHorizontal
+      },
+      md: {
+        minWidth: UNREAD_BADGE_SIZES.md.minWidth,
+        height: UNREAD_BADGE_SIZES.md.height,
+        paddingHorizontal: UNREAD_BADGE_SIZES.md.paddingHorizontal
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=UnreadBadge.variants.js.map

package/lib/module/modules/unread-badge/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { UnreadBadge } from "./UnreadBadge.js";
+//# sourceMappingURL=index.js.map

package/lib/module/test/mocks/flashList.js

@@ -0,0 +1,5 @@
+"use strict";
+
+import { FlatList } from 'react-native';
+export const FlashList = FlatList;
+//# sourceMappingURL=flashList.js.map

package/lib/module/test/perfHelpers.js

@@ -0,0 +1,18 @@
+"use strict";
+
+/** Shared helpers for *.perf.test.tsx — mounted-row bounds and render-count guards. */
+
+export const PERF_DATASET_SIZE = 10_000;
+export const PERF_MAX_MOUNTED_ROWS = 200;
+export function makeIndexedDataset(size) {
+  return Array.from({
+    length: size
+  }, (_, index) => ({
+    id: `row-${index}`,
+    label: `Row ${index + 1}`
+  }));
+}
+export function countByTestIdPrefix(queryAllByTestId, prefix) {
+  return queryAllByTestId(new RegExp(`^${prefix}`)).length;
+}
+//# sourceMappingURL=perfHelpers.js.map

package/lib/module/theme/MODULE.md

@@ -85,3 +85,9 @@ mode's — same adapter, separate key, so a plain-string storage slot never has
 Brand's existing fully-controlled-prop behavior (reactive to a changing `brand` prop, tested since
 before persistence existed) is preserved on top rather than replaced — see the `brand?` prop note
 above.
+
+## 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/theme/hooks.js

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Lightweight theme hooks — no PixelizeProvider, no palette barrels.
+ * Component modules import from here instead of the theme barrel.
+ */
+
+export { useTheme } from "./provider/useTheme.js";
+export { useThemeColors } from "./provider/useThemeColors.js";
+export { useThemeMode } from "./provider/useThemeMode.js";
+//# sourceMappingURL=hooks.js.map

package/lib/module/theme/index.js

@@ -6,10 +6,7 @@
  * this subpath is intentionally the small, runtime-facing layer an app wires once at its root.
  */
 
-export { PixelizeProvider, useTheme, useThemeColors, useThemeMode, createAsyncStorageAdapter } from "./provider/index.js";
-
-// Resolved-colour types, for annotating a value pulled from `useThemeColors()`.
-
-// The brand catalogue, for building a theme picker.
-export { themeNames, DEFAULT_THEME } from "./tokens/brands/index.js";
+export { PixelizeProvider, useTheme, useThemeColors, useThemeMode, createAsyncStorageAdapter, THEME_NAMES, DEFAULT_THEME, loadPalette, loadPaletteSync } from "./provider/index.js";
+/** @deprecated Use THEME_NAMES from this module instead. */
+export { THEME_NAMES as themeNames } from "./provider/index.js";
 //# sourceMappingURL=index.js.map

package/lib/module/theme/platform/MODULE.md

@@ -100,3 +100,9 @@ sunrise/sunset and via `Appearance.setColorScheme()`.
 
 - `spread` unsupported (above).
 - Android shadow tint requires API 28+; below that colour is ignored by the platform.
+
+## 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/theme/platform/motion.native.js

@@ -0,0 +1,15 @@
+"use strict";
+
+export const motionDurations = {
+  instant: 0,
+  fast: 150,
+  normal: 200,
+  slow: 300
+};
+export const motionEasings = {
+  standard: 'ease-in-out',
+  enter: 'ease-out',
+  exit: 'ease-in',
+  snap: 'linear'
+};
+//# sourceMappingURL=motion.native.js.map

package/lib/module/theme/provider/PixelizeProvider.js

@@ -1,24 +1,13 @@
 "use strict";
 
-import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, palettes, roleColors, DEFAULT_THEME } from "../tokens/index.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { space, radii, fontSizes, fontWeights, lineHeights, letterSpacings, borderWidths, breakpoints, zIndices, elevation as elevationTokens, roleColors } from "../tokens/index.js";
 import { elevation as renderElevation, fontStyleForWeight, getSystemColorMode, subscribeToSystemColorMode } from "../platform/index.js";
 import { DEFAULT_BRAND_STORAGE_NAMESPACE, DEFAULT_STORAGE_NAMESPACE, isThemeMode, isThemeName, memoryStorageAdapter } from "./colorModeStorage.js";
-
-// A local declaration of RN's build-time global, so this file typechecks without depending on the
-// react-native ambient types being loaded. In a module scope it shadows nothing; RN replaces it.
-
-/**
- * The fully resolved theme for one (brand, resolvedMode): role colours resolved to plain strings,
- * the unitless numeric scale, and the platform-rendered pieces a token cannot hold (RN shadow props,
- * a font-style resolver). This is what `useTheme()` returns; component modules read it, never the
- * raw palette directly.
- */
+import { DEFAULT_THEME, loadPaletteSync } from "./loadPalette.js";
+import { ThemeContext, ThemeModeContext } from "./ThemeContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEFAULT_MODE = 'system';
-
-// Elevation carries no colour-mode variation at the token layer, so every theme shares one rendered
-// map instead of recomputing five shadow styles per brand/mode.
 const RENDERED_ELEVATION = {
   none: renderElevation(elevationTokens.none),
   sm: renderElevation(elevationTokens.sm),
@@ -26,8 +15,8 @@ const RENDERED_ELEVATION = {
   md: renderElevation(elevationTokens.md),
   lg: renderElevation(elevationTokens.lg)
 };
-function buildTheme(brand, mode, interLoaded) {
-  const palette = palettes[brand][mode];
+function buildTheme(brand, mode, interLoaded, paletteOverride) {
+  const palette = paletteOverride ?? loadPaletteSync(brand, mode);
   return {
     brand,
     mode,
@@ -46,18 +35,6 @@ function buildTheme(brand, mode, interLoaded) {
     fontStyleForWeight: weight => fontStyleForWeight(weight, interLoaded)
   };
 }
-
-/**
- * Two contexts, on purpose. `ThemeContext` holds the heavy resolved `Theme`; `ThemeModeContext` holds
- * the small mode-control triple. Both provider values are memoised on their true inputs, so:
- *  - a mode flip recomputes the theme exactly ONCE and re-renders each consumer once, and
- *  - an OS colour change while the mode is pinned (`resolvedMode` unchanged) keeps BOTH values
- *    reference-stable, so it re-renders nobody.
- * Splitting also means a `useThemeMode()` reader isn't invalidated by unrelated theme-object churn
- * and vice versa.
- */
-export const ThemeContext = /*#__PURE__*/createContext(undefined);
-export const ThemeModeContext = /*#__PURE__*/createContext(undefined);
 export function PixelizeProvider({
   children,
   brand: brandProp = DEFAULT_THEME,
@@ -65,28 +42,16 @@ export function PixelizeProvider({
   storage: storageProp,
   storageKey = DEFAULT_STORAGE_NAMESPACE,
   brandStorageKey = DEFAULT_BRAND_STORAGE_NAMESPACE,
-  interLoaded = false
+  interLoaded = false,
+  palette: paletteProp
 }) {
   const storage = storageProp ?? memoryStorageAdapter;
   const [modeState, setModeState] = useState(mode);
   const [brandState, setBrandState] = useState(brandProp);
-  // Read the real OS value immediately — native has no hydration step to stay deterministic for.
   const [systemMode, setSystemMode] = useState(getSystemColorMode);
-
-  // Once the user has chosen, a late async rehydrate must not clobber that fresh choice. Brand
-  // gets its own ref: touching one must never block the other's rehydrate.
   const userTouched = useRef(false);
   const userTouchedBrand = useRef(false);
   useEffect(() => subscribeToSystemColorMode(setSystemMode), []);
-
-  // `mode` is intentionally initial-only (a controlled screen drives it through `setMode`, never
-  // by re-passing a prop), but `brand` already shipped as a fully-controlled prop before this
-  // provider owned any brand state — existing call sites (this repo's own example app included)
-  // re-render with a new `brand` value and expect the theme to follow. This keeps that contract
-  // alive on top of the new persisted/`setBrand` state: an unrelenting `brandProp` still drives
-  // `brandState`, but the moment `setBrand` is called even once, the provider is considered the
-  // owner and further `brandProp` changes are ignored — the same "explicit choice wins" rule
-  // `storage` rehydration already follows below.
   useEffect(() => {
     if (userTouchedBrand.current) return;
     setBrandState(brandProp);
@@ -116,9 +81,6 @@ export function PixelizeProvider({
       cancelled = true;
     };
   }, [storage, brandStorageKey]);
-
-  // Write on the explicit action, not in an effect: it only ever persists a real user choice, so a
-  // mount default can't be written over the stored value before the rehydrate above has applied it.
   const setMode = useCallback(next => {
     userTouched.current = true;
     setModeState(next);
@@ -130,7 +92,7 @@ export function PixelizeProvider({
     Promise.resolve(storage.setItem(brandStorageKey, next)).catch(() => {});
   }, [storage, brandStorageKey]);
   const resolvedMode = modeState === 'system' ? systemMode : modeState;
-  const theme = useMemo(() => buildTheme(brandState, resolvedMode, interLoaded), [brandState, resolvedMode, interLoaded]);
+  const theme = useMemo(() => buildTheme(brandState, resolvedMode, interLoaded, paletteProp), [brandState, resolvedMode, interLoaded, paletteProp]);
   const modeValue = useMemo(() => ({
     mode: modeState,
     resolvedMode,

package/lib/module/theme/provider/ThemeContext.js

@@ -0,0 +1,6 @@
+"use strict";
+
+import { createContext } from 'react';
+export const ThemeContext = /*#__PURE__*/createContext(undefined);
+export const ThemeModeContext = /*#__PURE__*/createContext(undefined);
+//# sourceMappingURL=ThemeContext.js.map

package/lib/module/theme/provider/colorModeStorage.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { themeNames } from "../tokens/brands/index.js";
+import { THEME_NAMES } from "./loadPalette.js";
 
 /**
  * The user-facing colour-mode selection. `system` follows the OS; `light`/`dark` pin it.
@@ -23,7 +23,7 @@ export function isThemeMode(value) {
 /** Same untrusted-input discipline as `isThemeMode`, checked against the live brand roster so a
  * newly retired/renamed brand can never slip through as a stale stored value. */
 export function isThemeName(value) {
-  return typeof value === 'string' && themeNames.includes(value);
+  return typeof value === 'string' && THEME_NAMES.includes(value);
 }
 
 /**

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

@@ -5,4 +5,5 @@ export { useTheme } from "./useTheme.js";
 export { useThemeColors } from "./useThemeColors.js";
 export { useThemeMode } from "./useThemeMode.js";
 export { createAsyncStorageAdapter, memoryStorageAdapter, isThemeMode, isThemeName, DEFAULT_STORAGE_NAMESPACE, DEFAULT_BRAND_STORAGE_NAMESPACE } from "./colorModeStorage.js";
+export { THEME_NAMES, DEFAULT_THEME, loadPalette, loadPaletteSync } from "./loadPalette.js";
 //# sourceMappingURL=index.js.map

package/lib/module/theme/provider/loadPalette.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/** Brand roster without importing any palette modules. */
+export const THEME_NAMES = ['zinc', 'lavender', 'meadow', 'radiant', 'skyline', 'slate', 'emerald', 'rosewood', 'storefront'];
+export const DEFAULT_THEME = 'zinc';
+const LIGHT_LOADERS = {
+  zinc: () => import('../tokens/brands/zinc/palette.light'),
+  lavender: () => import('../tokens/brands/lavender/palette.light'),
+  meadow: () => import('../tokens/brands/meadow/palette.light'),
+  radiant: () => import('../tokens/brands/radiant/palette.light'),
+  skyline: () => import('../tokens/brands/skyline/palette.light'),
+  slate: () => import('../tokens/brands/slate/palette.light'),
+  emerald: () => import('../tokens/brands/emerald/palette.light'),
+  rosewood: () => import('../tokens/brands/rosewood/palette.light'),
+  storefront: () => import('../tokens/brands/storefront/palette.light')
+};
+const DARK_LOADERS = {
+  zinc: () => import('../tokens/brands/zinc/palette.dark'),
+  lavender: () => import('../tokens/brands/lavender/palette.dark'),
+  meadow: () => import('../tokens/brands/meadow/palette.dark'),
+  radiant: () => import('../tokens/brands/radiant/palette.dark'),
+  skyline: () => import('../tokens/brands/skyline/palette.dark'),
+  slate: () => import('../tokens/brands/slate/palette.dark'),
+  emerald: () => import('../tokens/brands/emerald/palette.dark'),
+  rosewood: () => import('../tokens/brands/rosewood/palette.dark'),
+  storefront: () => import('../tokens/brands/storefront/palette.dark')
+};
+const paletteCache = new Map();
+function cacheKey(brand, mode) {
+  return `${brand}:${mode}`;
+}
+
+/** Loads one brand's palette for the given mode — only that brand's file is fetched. */
+export async function loadPalette(brand, mode) {
+  const key = cacheKey(brand, mode);
+  const cached = paletteCache.get(key);
+  if (cached) return cached;
+  const mod = await (mode === 'light' ? LIGHT_LOADERS[brand]() : DARK_LOADERS[brand]());
+  const palette = mod.default;
+  paletteCache.set(key, palette);
+  return palette;
+}
+const LIGHT_SYNC_LOADERS = {
+  zinc: () => require('../tokens/brands/zinc/palette.light').default,
+  lavender: () => require('../tokens/brands/lavender/palette.light').default,
+  meadow: () => require('../tokens/brands/meadow/palette.light').default,
+  radiant: () => require('../tokens/brands/radiant/palette.light').default,
+  skyline: () => require('../tokens/brands/skyline/palette.light').default,
+  slate: () => require('../tokens/brands/slate/palette.light').default,
+  emerald: () => require('../tokens/brands/emerald/palette.light').default,
+  rosewood: () => require('../tokens/brands/rosewood/palette.light').default,
+  storefront: () => require('../tokens/brands/storefront/palette.light').default
+};
+const DARK_SYNC_LOADERS = {
+  zinc: () => require('../tokens/brands/zinc/palette.dark').default,
+  lavender: () => require('../tokens/brands/lavender/palette.dark').default,
+  meadow: () => require('../tokens/brands/meadow/palette.dark').default,
+  radiant: () => require('../tokens/brands/radiant/palette.dark').default,
+  skyline: () => require('../tokens/brands/skyline/palette.dark').default,
+  slate: () => require('../tokens/brands/slate/palette.dark').default,
+  emerald: () => require('../tokens/brands/emerald/palette.dark').default,
+  rosewood: () => require('../tokens/brands/rosewood/palette.dark').default,
+  storefront: () => require('../tokens/brands/storefront/palette.dark').default
+};
+
+/** Synchronous palette for provider mount — static requires so Metro can bundle the example app. */
+export function loadPaletteSync(brand, mode) {
+  const key = cacheKey(brand, mode);
+  const cached = paletteCache.get(key);
+  if (cached) return cached;
+  const palette = (mode === 'light' ? LIGHT_SYNC_LOADERS[brand] : DARK_SYNC_LOADERS[brand])();
+  paletteCache.set(key, palette);
+  return palette;
+}
+//# sourceMappingURL=loadPalette.js.map

package/lib/module/theme/provider/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/theme/provider/useTheme.js

@@ -1,8 +1,7 @@
 "use strict";
 
 import { useContext } from 'react';
-import { ThemeContext } from "./PixelizeProvider.js";
-/** The full resolved theme: role colours, the numeric scale, and platform-rendered elevation/fonts. */
+import { ThemeContext } from "./ThemeContext.js";
 export function useTheme() {
   const theme = useContext(ThemeContext);
   if (!theme) {

package/lib/module/theme/provider/useThemeMode.js

@@ -1,7 +1,7 @@
 "use strict";
 
 import { useContext } from 'react';
-import { ThemeModeContext } from "./PixelizeProvider.js";
+import { ThemeModeContext } from "./ThemeContext.js";
 /** `{ mode, resolvedMode, setMode }` for a theme switcher. Reads the light mode-control context. */
 export function useThemeMode() {
   const value = useContext(ThemeModeContext);

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

@@ -25,6 +25,15 @@ export function pickOnAccent(fill) {
   return contrastRatio(fill, ON_ACCENT_LIGHT) >= contrastRatio(fill, ON_ACCENT_DARK) ? ON_ACCENT_LIGHT : ON_ACCENT_DARK;
 }
 
+/**
+ * Ink for text drawn ON a filled swatch (button/tag/type-icon fill). `white`/`black` must be the
+ * mode-stable palette absolutes (`palette.white` / `palette.black`), not a mode-adaptive text ramp.
+ * Web exports the same helper from `pixelize-design-library` for consumer surfaces like type icons.
+ */
+export function onFilled(fill, white, black) {
+  return contrastRatio(white, fill) >= AA_TEXT ? white : black;
+}
+
 /**
  * First rung whose better label clears AA, walking 500 → 600 → 700.
  *

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

@@ -17,7 +17,7 @@
  *    `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";
 const RAMP_KEYS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 
@@ -59,10 +59,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]
   };
@@ -111,7 +113,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