pixelize-native-library 1.0.6 → 1.2.0

package/lib/typescript/modules/state-block/StateBlock.d.ts

@@ -0,0 +1,51 @@
+/**
+ * StateBlock — centred async-state placeholders beside `empty-state`:
+ *  - `LoadingState` composes this library's own `Spinner` (never a raw `ActivityIndicator`).
+ *  - `ErrorState` mirrors `EmptyState`'s layout — optional icon, required title, optional
+ *    description, optional retry action via `Button`.
+ *
+ * No `accessibilityRole` of its own on either export: the composed `Spinner`/`Button` carry their
+ * own semantics, and `ErrorState`'s title is the block's heading (`accessibilityRole="header"`,
+ * WCAG 1.3.1 / 2.4.6) with the description reading after it.
+ *
+ * Both blocks appear WITHOUT moving focus — `Screen` swaps them in for its content — so appearing is
+ * itself the status message (WCAG 4.1.3) and `useAnnounce` speaks it, exactly as the sibling
+ * `EmptyState` does. Neither carries `accessibilityRole="alert"` or `accessibilityLiveRegion`
+ * alongside it: on web `role="alert"` is itself a live region, so the pair announces twice. The
+ * library's split is one or the other — `Banner` takes the role, these take the announcement.
+ *
+ * Both take `visible` (default `true`) and fade/slide through `useEnterExit`, so swapping
+ * loading → error → content is a transition rather than a jump cut. `useEnterExit` skips the enter
+ * for a block that mounts already visible, so the default is behaviourally unchanged.
+ */
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { SpinnerSize, SpinnerTone } from "../spinner/Spinner.variants";
+export interface LoadingStateProps {
+    message?: string;
+    size?: SpinnerSize;
+    tone?: SpinnerTone;
+    /** Fades and slides the block out when set to `false`, then unmounts it. */
+    visible?: boolean;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export interface ErrorStateAction {
+    readonly label: string;
+    readonly onPress: () => void;
+}
+export interface ErrorStateProps {
+    icon?: IconName;
+    title: string;
+    description?: string;
+    action?: ErrorStateAction;
+    /** Fades and slides the block out when set to `false`, then unmounts it. */
+    visible?: boolean;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const LoadingState: import("react").NamedExoticComponent<LoadingStateProps>;
+export declare const ErrorState: import("react").NamedExoticComponent<ErrorStateProps>;
+//# sourceMappingURL=StateBlock.d.ts.map

package/lib/typescript/modules/state-block/StateBlock.variants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * StateBlock's style resolution — `LoadingState` and `ErrorState` share this file as siblings to
+ * `empty-state/EmptyState.variants.ts`:
+ *  - STRUCTURE (centring, padding, vertical rhythm) lives in the themed resolvers below.
+ *  - COLOUR is resolved from the theme's ROLE colours, never a raw ramp and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the WCAG tests import this directly (mocking only `react-native`'s
+ * `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+import type { RoleColors, Theme } from "../../theme/hooks";
+/** The error glyph's rendered size, in dp — same focal-point reasoning as `EMPTY_STATE_ICON_SIZE`. */
+export declare const ERROR_STATE_ICON_SIZE = 48;
+export interface LoadingStateColors {
+    readonly message: string;
+}
+export interface ErrorStateColors {
+    readonly icon: string;
+    readonly title: string;
+    readonly description: string;
+}
+export declare function resolveLoadingStateColors(colors: RoleColors): LoadingStateColors;
+export declare function resolveErrorStateColors(colors: RoleColors): ErrorStateColors;
+/**
+ * What a screen reader hears when the error block appears (WCAG 4.1.3) — the same shape, and the
+ * same reasoning about the recovery step, as `resolveEmptyStateAnnouncement`.
+ */
+export declare function resolveErrorStateAnnouncement(title: string, description: string | undefined): string;
+export declare const loadingStateStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const errorStateStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=StateBlock.variants.d.ts.map

package/lib/typescript/modules/state-block/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of `pixelize-native-library/state-block`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures these through
+ * their props, never by importing internals.
+ */
+export { LoadingState, ErrorState } from "./StateBlock";
+export type { LoadingStateProps, ErrorStateProps, ErrorStateAction } from "./StateBlock";
+export type { SpinnerSize, SpinnerTone } from "../spinner/Spinner.variants";
+export type { IconName } from "../../core/icon";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/stepper/Stepper.d.ts

@@ -9,6 +9,10 @@
  * length; the connector to the NEXT step is drawn as two identically-coloured halves — the trailing
  * half of this column, the leading half of the next — so a circle stays centered under its own
  * label rather than centered between two circles' worth of connector.
+ *
+ * Advancing `activeStep` settles the newly-active circle with a small scale (`core/motion`). One
+ * shared `Animated.Value` drives it — the connectors change colour, which cannot run on the native
+ * driver, so they stay static.
  */
 import type { LayoutStyle } from "../../core/style";
 export interface StepperStep {

package/lib/typescript/modules/stepper/Stepper.variants.d.ts

@@ -16,7 +16,7 @@
  * Free of React and of any lucide import, so the WCAG + behaviour tests import it directly (mocking
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export type StepState = "completed" | "active" | "upcoming";
 /**
  * Visual diameter of a step's numbered circle, in dp. Not a touch target — Stepper is a v1
@@ -72,11 +72,9 @@ export interface StepperAccessibilityInput {
 }
 export interface StepperAccessibilityProps {
     readonly accessibilityRole: "progressbar";
-    readonly accessibilityValue: {
-        readonly min: 0;
-        readonly max: number;
-        readonly now: number;
-    };
+    readonly "aria-valuemin": 0;
+    readonly "aria-valuemax": number;
+    readonly "aria-valuenow": number;
     readonly accessibilityLabel: string;
 }
 /**
@@ -85,7 +83,9 @@ export interface StepperAccessibilityProps {
  * wording is unit-tested without a renderer; `Stepper.tsx` pairs this with `accessible` on the
  * container, the same collapsing idiom `Badge` uses for its icon + label). `activeStep` is
  * 0-indexed internally; the announcement surfaces the natural 1-based ordinal, and
- * `accessibilityValue` surfaces the raw 0-indexed `min`/`max`/`now` progress triple.
+ * the flat `aria-value*` triple surfaces the raw 0-indexed `min`/`max`/`now` progress. Flat rather
+ * than `accessibilityValue={{…}}`: RN's `View` folds the flat props back into that object, while
+ * react-native-web forwards only the flat form — the object reaches nothing at all on web.
  */
 export declare function resolveStepperAccessibility(input: StepperAccessibilityInput): StepperAccessibilityProps;
 /**

package/lib/typescript/modules/swipeable-row/SwipeableRow.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SwipeableRow — reveals action buttons on horizontal swipe. Built on gesture-handler +
+ * reanimated 4 shared values, so the row follows the finger on the UI thread.
+ *
+ * A swipe is invisible to assistive tech (WCAG 2.1.1), so the same actions are also declared as
+ * `accessibilityActions` on the row itself — the platform-native list-row model, where the row is
+ * one accessibility element carrying custom actions. The trays are the sighted-touch affordance for
+ * that same set, so they stay out of the accessibility tree: they sit behind the content and would
+ * otherwise announce every row's actions ahead of its content, swiped open or not.
+ *
+ * Those two props are native-only — react-native-web implements neither — so each action ALSO
+ * carries an explicit `tabIndex={-1}`: without it a 20-row list costs three Tab presses per row,
+ * two of them landing on a button the content is painted over.
+ */
+import type { ReactNode } from "react";
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { SwipeableActionTone } from "./SwipeableRow.variants";
+export interface SwipeableRowAction {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: IconName;
+    readonly tone?: SwipeableActionTone;
+    readonly onPress: () => void;
+}
+export interface SwipeableRowProps {
+    children: ReactNode;
+    leftActions?: readonly SwipeableRowAction[];
+    rightActions?: readonly SwipeableRowAction[];
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const SwipeableRow: import("react").NamedExoticComponent<SwipeableRowProps>;
+//# sourceMappingURL=SwipeableRow.d.ts.map

package/lib/typescript/modules/swipeable-row/SwipeableRow.variants.d.ts

@@ -0,0 +1,27 @@
+import type { RoleColors, Theme } from "../../theme/hooks";
+import type { StatusRole } from "../../theme/hooks";
+export type SwipeableActionTone = StatusRole | "accent" | "neutral";
+export interface SwipeableActionColors {
+    readonly fill: string;
+    readonly text: string;
+}
+export declare function resolveSwipeableActionTone(colors: RoleColors, tone: SwipeableActionTone): SwipeableActionColors;
+export declare const swipeableRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const swipeableActionsStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const swipeableActionButtonStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/**
+ * The keyboard/AT focus ring for one action button. Drawn INSIDE the button's own bounds, not as the
+ * gap-outside ring `Button`/`CopyButton` use: `swipeableRowStructure` clips to `overflow: "hidden"`,
+ * so an outset ring on the outermost action would be cut off by the row itself. Its colour is
+ * applied inline over this, never hardcoded here.
+ */
+export declare const swipeableActionFocusRingStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const SWIPE_ACTION_WIDTH = 72;
+/**
+ * The always-visible tap affordance (WCAG 2.5.7 / 2.5.1): trailing edge, vertically centered, on
+ * top of `children` — it does not reflow consumer content, since `children` is opaque to this
+ * component. `pointerEvents: "box-none"` on the wrapping node (applied at the component, not here)
+ * keeps the rest of the row's width free for the pan gesture underneath.
+ */
+export declare const swipeableMoreAffordanceStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=SwipeableRow.variants.d.ts.map

package/lib/typescript/modules/swipeable-row/index.d.ts

@@ -0,0 +1,4 @@
+export { SwipeableRow } from "./SwipeableRow";
+export type { SwipeableRowAction, SwipeableRowProps } from "./SwipeableRow";
+export type { SwipeableActionTone } from "./SwipeableRow.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/switch/Switch.variants.d.ts

@@ -3,7 +3,7 @@
  * lucide, same split as `Button.variants.ts`: the WCAG + behaviour tests import these directly,
  * measuring real palettes instead of eyeballing a hex.
  */
-import type { RoleColors } from "../../theme";
+import type { RoleColors } from "../../theme/hooks";
 export interface SwitchColors {
     /** Track fill when `value` is false. */
     readonly trackOff: string;
@@ -39,6 +39,14 @@ export interface SwitchAccessibilityProps {
  * RN's own `<Switch>` defaults `accessibilityRole` to `"switch"` but never sets
  * `accessibilityState.checked` itself (only `disabled` is merged in, on Android) — so this module
  * sets both explicitly, kept pure so the contract is testable without rendering React Native.
+ *
+ * The ONE control in the form family that keeps the OBJECT form. `Switch` is a native primitive, not
+ * a `View`/`Pressable`: RN's `Switch.js` reads `accessibilityState` and spreads everything else
+ * straight onto the platform view, which has no idea what `aria-checked` is — so a flat prop would
+ * announce nothing natively. Web needs nothing either: `react-native-web` renders a real
+ * `<input type="checkbox" role="switch" checked>`, so the DOM already carries the state, and a flat
+ * `aria-checked` would land on the wrapper `<div>` — an element with no role, where the attribute is
+ * not allowed. Object on native, native input on web; no flat form belongs here.
  */
 export declare function resolveSwitchAccessibility(input: SwitchAccessibilityInput): SwitchAccessibilityProps;
 /** WCAG 2.5.5 (AAA) / HIG floor every interactive control is held to — same constant as `Button`. */

package/lib/typescript/modules/tabs/Tabs.d.ts

@@ -3,12 +3,14 @@
  * real design systems split the strip from panel content, and keeps the component simple and
  * composable (no `TabPanel`, no rendering children per tab).
  *
- * The active-tab indicator is two `Animated.Value`s (`x`, `width`) driven off each tab's own
- * `onLayout` measurement, keyed by `value` so reordering `items` doesn't scramble which
- * measurement belongs to which tab. Reduced motion (WCAG 2.3.3) snaps both values with `setValue`
- * instead of animating — same `duration: reducedMotion ? 0 : …` idiom `Button`'s press fade and
- * `Toast`'s slide use, just applied to `setValue` vs `Animated.timing` instead of a duration of 0
- * (a 0-width/0-position change would still tween through intermediate frames otherwise).
+ * The active-tab indicator is a 1dp-wide bar positioned and stretched entirely by transforms
+ * (`translateX` + `scaleX`) off each tab's own `onLayout` measurement, keyed by `value` so
+ * reordering `items` doesn't scramble which measurement belongs to which tab. Transforms are the
+ * only way this can run on the native driver — see `Tabs.variants.ts` for the geometry, and
+ * `core/motion` for the timing every module now shares.
+ *
+ * That indicator marks SELECTION, not focus: a tab holding keyboard/AT focus draws its own inset
+ * ring (WCAG 2.4.7), the same treatment `BottomNavTab` uses.
  */
 import type { IconName } from "../../core/icon";
 import type { LayoutStyle } from "../../core/style";

package/lib/typescript/modules/tabs/Tabs.variants.d.ts

@@ -8,7 +8,7 @@
  *  - `resolveTabAccessibility` derives the per-tab a11y surface purely, so the "selected" contract
  *    is unit-testable without rendering React Native.
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export type TabsSize = "sm" | "md" | "lg";
 /** Same floor as Button/RadioGroup — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules
  * stay isolated. */
@@ -70,9 +70,9 @@ export interface TabAccessibilityInput {
 }
 export interface TabAccessibilityProps {
     readonly accessibilityRole: "tab";
-    readonly accessibilityState: {
-        readonly selected: boolean;
-    };
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted key so the compiler still checks the prop name. */
+    readonly "aria-selected": boolean;
 }
 /**
  * Derives one tab's accessibility surface purely, mirroring `resolveRadioRowAccessibility`: every
@@ -106,9 +106,22 @@ export declare const tabItemStructure: import("../../core/style").ThemedVariantR
     };
 }, import("react-native").ViewStyle>;
 /**
- * The active-tab indicator bar. Thickness is the theme's `border.thick` (2dp); the pill radius is
- * `radii.full`. Position (`left`/`width`, via `transform`/`width`) is driven by `Animated.Value`s
- * in `Tabs.tsx`, not by this static resolver.
+ * The active-tab indicator bar. Thickness is the theme's `border.thick` (2dp). Its width is a fixed
+ * 1dp unit that `Tabs.tsx` stretches with an animated `scaleX` — a transform, so the whole indicator
+ * runs on the native driver (animating `width` cannot, and forces a layout pass per frame).
+ *
+ * No `borderRadius`: a corner radius is applied BEFORE the transform, so `scaleX` would smear a
+ * 0.5dp round end into a lens the full width of the tab. At 2dp thick, square ends are
+ * indistinguishable from the previous `radii.full` pill.
+ */
+export declare const TABS_INDICATOR_UNIT_WIDTH = 1;
+/**
+ * The keyboard/AT focus ring drawn over one tab's own bounds — the same treatment
+ * `bottomNavFocusRingStructure` uses, and inset rather than outset because the strip's `columnGap`
+ * is a single space step: a ring drawn outside a tab would overlap its neighbour. Focus is NOT the
+ * animated indicator below — that bar marks SELECTION, which moves only on press. Its colour is
+ * applied inline over this, never hardcoded here.
  */
+export declare const tabsFocusRingStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
 export declare const tabsIndicatorStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
 //# sourceMappingURL=Tabs.variants.d.ts.map

package/lib/typescript/modules/text/Text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Text — typography primitive with a closed `variant` union. Replaces ad-hoc fontSize literals.
+ */
+import { type TextProps as RNTextProps } from 'react-native';
+import type { LayoutStyle } from '../../core/style';
+import type { HeadingVariant, TextVariant } from './Text.variants';
+export interface TextProps {
+    variant?: TextVariant;
+    children: RNTextProps['children'];
+    numberOfLines?: number;
+    style?: LayoutStyle;
+    testID?: string;
+}
+export interface HeadingProps {
+    variant?: HeadingVariant;
+    children: RNTextProps['children'];
+    numberOfLines?: number;
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const Text: import("react").NamedExoticComponent<TextProps>;
+export declare const Heading: import("react").NamedExoticComponent<HeadingProps>;
+//# sourceMappingURL=Text.d.ts.map

package/lib/typescript/modules/text/Text.variants.d.ts

@@ -0,0 +1,18 @@
+import type { TextStyle } from 'react-native';
+import type { HeadingLevel } from '../../core/heading';
+import type { RoleColors, Theme } from '../../theme/hooks';
+export type TextVariant = 'body' | 'body-sm' | 'caption' | 'label' | 'label-sm' | 'overline';
+export type HeadingVariant = 'h1' | 'h2' | 'h3' | 'h4';
+/**
+ * `variant` is the level as well as the size. Without this, `react-native-web` renders every
+ * heading as `<h1>` (see `core/heading`).
+ */
+export declare const HEADING_LEVELS: Record<HeadingVariant, HeadingLevel>;
+/** Runtime companion to `TextVariant`, so the WCAG test can enumerate every variant a consumer can pass. */
+export declare const TEXT_VARIANTS: readonly ["body", "body-sm", "caption", "label", "label-sm", "overline"];
+export declare const HEADING_VARIANTS: Record<HeadingVariant, TextVariant>;
+/** The role colour a variant resolves to. Pure, so the WCAG test measures it without a `Theme`. */
+export declare function resolveTextColor(colors: RoleColors, variant: TextVariant): string;
+export declare function resolveTextStyle(theme: Theme, variant: TextVariant): TextStyle;
+export declare function resolveHeadingStyle(theme: Theme, variant: HeadingVariant): TextStyle;
+//# sourceMappingURL=Text.variants.d.ts.map

package/lib/typescript/modules/text/index.d.ts

@@ -0,0 +1,4 @@
+export { Text, Heading } from './Text';
+export type { TextProps, HeadingProps } from './Text';
+export type { TextVariant, HeadingVariant } from './Text.variants';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/textarea/Textarea.d.ts

@@ -3,6 +3,9 @@
  * does not depend on it). Same closed-prop shape the rest of the catalogue follows: `size` / `status`
  * are closed unions, colour is resolved from `RoleColors`, and `containerStyle` is the one documented
  * `LayoutStyle` exception for a component wrapping a native `TextInput` (CLAUDE.md).
+ *
+ * Motion comes from `core/motion`: the focus ring crossfades and the helper/error message fades in
+ * and out, both gated by `useMotion()`'s reduce-motion resolution.
  */
 import type { LayoutStyle } from "../../core/style";
 import type { TextareaSize, TextareaStatus } from "./Textarea.variants";
@@ -14,6 +17,8 @@ export interface TextareaProps {
     status?: TextareaStatus;
     disabled?: boolean;
     label?: string;
+    /** Overrides the label→`accessibilityLabel` fallback, for a field whose visible label is elsewhere. */
+    accessibilityLabel?: string;
     helperText?: string;
     errorText?: string;
     maxLength?: number;

package/lib/typescript/modules/textarea/Textarea.variants.d.ts

@@ -11,7 +11,7 @@
  * Free of React and of any lucide import, so the WCAG + behaviour tests import it directly (mocking
  * only `react-native`'s `StyleSheet`, as `core/style` does).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export type TextareaSize = "sm" | "md" | "lg";
 export type TextareaStatus = "default" | "error";
 /**
@@ -56,24 +56,31 @@ export interface TextareaStatusColors {
 export declare function resolveTextareaStatus(colors: RoleColors, status: TextareaStatus): TextareaStatusColors;
 export interface TextareaAccessibilityInput {
     readonly label?: string | undefined;
+    readonly accessibilityLabel?: string | undefined;
     readonly helperText?: string | undefined;
     readonly errorText?: string | undefined;
     readonly status?: TextareaStatus | undefined;
     readonly disabled?: boolean | undefined;
 }
 export interface TextareaAccessibilityProps {
+    /** The visible label (or an explicit override), with `errorText` appended in the error state. */
     readonly accessibilityLabel: string | undefined;
-    /** The message actually shown — `errorText` when in error status (if provided), else `helperText`. */
+    /** ADVISORY supporting text only (`helperText`). Never the validity message. */
     readonly accessibilityHint: string | undefined;
-    readonly accessibilityState: {
-        readonly disabled: boolean;
-    };
+    readonly "aria-invalid": boolean;
+    readonly "aria-disabled": boolean;
+    /** The string the component renders below the field — `errorText` in the error state, else `helperText`. */
+    readonly message: string | undefined;
 }
 /**
  * Derives the accessibility surface once, purely, so the label/hint/disabled contract is testable
- * without a renderer. React Native has no `aria-describedby`; `accessibilityHint` is the platform
- * equivalent, so the SAME string this returns is also what the component renders as the visible
- * helper/error `Text` — one source of truth, never two strings that could drift apart.
+ * without a renderer.
+ *
+ * Same split as `resolveInputAccessibility`, for the same reason: a validity message must not ride
+ * `accessibilityHint`, because a hint is advisory and some readers suppress it (the rule
+ * `resolveFormFieldAccessibility` already states). So `errorText` joins the NAME and sets
+ * `aria-invalid`, while the genuinely advisory `helperText` stays on the hint — which the component
+ * additionally links with `aria-describedby` on web, where `accessibilityHint` does not exist.
  */
 export declare function resolveTextareaAccessibility(input: TextareaAccessibilityInput): TextareaAccessibilityProps;
 /**

package/lib/typescript/modules/timeline/Timeline.d.ts

@@ -1,26 +1,26 @@
 /**
- * Timeline — a vertical list of dated/ordered events. Each row is a marker (a plain dot, or an
- * icon in a filled circle) connected to the next row's marker by a line. Purely informational: no
- * press handling, no per-item emphasis, no animation. The marker + connecting line are decorative
- * (removing them changes spacing, not meaning — same reasoning `Divider` documents for its own
- * hairline), so they are hidden from assistive tech; the title/description/timestamp stay in the
- * normal accessibility tree, read in order, exactly like the plain `View` container `Card.tsx`
- * documents ("nothing here for `accessibilityRole` to announce — children carry their own
- * semantics").
+ * Timeline — a vertical list of dated/ordered events.
+ *
+ * The reveal is ONE animated value on the outer container, never one per row: rows are recycled
+ * cells in a `VirtualList`, so a per-cell animation would fire on every scroll-in. It is gated on
+ * `motion.decorative` (high-tier only) since a reveal is pure decoration.
+ *
+ * A row's title, description and timestamp form ONE accessible node — see
+ * `resolveTimelineItemAccessibility` for why three loose `Text` siblings were a 1.3.1 failure.
  */
+import type { ReactNode } from "react";
 import type { IconName } from "../../core/icon";
 import type { LayoutStyle } from "../../core/style";
 export interface TimelineItem {
+    readonly id?: string;
     readonly title: string;
     readonly description?: string;
     readonly timestamp?: string;
-    /** A NAME, never a `ReactNode`. Always paired with the visible `title` — never the sole label of
-     *  anything, so it carries no `accessibilityLabel` requirement of its own. */
     readonly icon?: IconName;
+    readonly leading?: ReactNode;
 }
 export interface TimelineProps {
     items: TimelineItem[];
-    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
     style?: LayoutStyle;
     testID?: string;
 }

package/lib/typescript/modules/timeline/Timeline.variants.d.ts

@@ -11,7 +11,7 @@
  * Free of React and of any lucide import, so the WCAG + colour-mapping tests import it directly
  * (mocking only `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export interface TimelineMarkerSpec {
     /** Plain-dot diameter, in dp — used when an item carries no `icon`. */
     readonly dot: number;
@@ -82,6 +82,22 @@ export declare const timelineMarkerStructure: import("../../core/style").ThemedV
  * `timelineContentStructure`), so the line never visibly stops short of the next marker.
  */
 export declare const timelineConnectorLineStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export interface TimelineItemAccessibilityInput {
+    readonly title: string;
+    readonly description?: string;
+    readonly timestamp?: string;
+}
+export interface TimelineItemAccessibilityProps {
+    readonly accessible: true;
+    readonly accessibilityRole: "text";
+    readonly accessibilityLabel: string;
+}
+/**
+ * One event's title, description and timestamp collapse into ONE accessible node (WCAG 1.3.1) — as
+ * three loose `Text` siblings, only their visual grouping said which timestamp belonged to which
+ * title. The same composition `resolveBannerAccessibility` does for its title + message.
+ */
+export declare function resolveTimelineItemAccessibility(item: TimelineItemAccessibilityInput): TimelineItemAccessibilityProps;
 /**
  * The text column beside the connector. A `middle` row (one with a following item) reserves the
  * gap to that next row HERE, on the content sibling, not on the shared row wrapper — a row with an

package/lib/typescript/modules/toast/Toast.d.ts

@@ -13,14 +13,24 @@
  * restarts the auto-dismiss timer (and, since a fresh message reads as a new event, restarts the
  * entrance animation) rather than queueing a second one. `dismiss()` always dismisses that one slot,
  * and is a safe no-op when nothing is showing.
+ *
+ * Auto-dismiss is WCAG 2.2.1 (Timing Adjustable) territory: how long a toast lives is decided ONLY
+ * by `resolveAutoDismissDelay` (persistent mode, the screen-reader suppression, the `danger`
+ * default), and the timer is only armed while the user is neither hovering nor focused inside the
+ * card. Hover/focus pause and re-arm, they never dismiss.
  */
 import type { ReactNode } from "react";
-import type { ToastPosition, ToastTone } from "./Toast.variants";
+import type { ToastDuration, ToastPosition, ToastTone } from "./Toast.variants";
 export interface ToastOptions {
     readonly message: string;
     readonly tone?: ToastTone;
-    /** Auto-dismiss delay in ms. Defaults to `DEFAULT_TOAST_DURATION` (~3000ms). */
-    readonly duration?: number;
+    /**
+     * How long the toast stays up: a delay in ms, or `"persistent"` for "until the user dismisses
+     * it". Omitted means `DEFAULT_TOAST_DURATION` (~3000ms) — except `tone: "danger"`, which is
+     * persistent by default. A running screen reader suppresses auto-dismiss for every tone
+     * (WCAG 2.2.1 — `resolveAutoDismissDelay`).
+     */
+    readonly duration?: ToastDuration;
 }
 export interface ToastContextValue {
     show: (options: ToastOptions) => void;

package/lib/typescript/modules/toast/Toast.variants.d.ts

@@ -12,8 +12,8 @@
  * Free of React and of `lucide`, so the WCAG + behaviour tests import it directly (mocking only
  * `react-native`'s `StyleSheet`, as `core/style` does).
  */
-import type { RoleColors } from "../../theme";
-import type { Theme } from "../../theme";
+import type { RoleColors } from "../../theme/hooks";
+import type { Theme } from "../../theme/hooks";
 export type ToastTone = "success" | "warning" | "danger" | "info" | "neutral";
 export type ToastPosition = "top" | "bottom";
 /** Same floor as Button/Input/Checkbox — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules
@@ -24,8 +24,36 @@ export declare const MIN_TOUCH_TARGET = 44;
 export declare const CLOSE_BUTTON_SIZE = 24;
 export declare const CLOSE_ICON_SIZE = 16;
 export declare const CLOSE_HIT_SLOP: number;
-/** `duration?: number` on `ToastOptions` defaults to this when omitted. */
+/** `duration` on `ToastOptions` defaults to this when omitted — except for `danger` (see below). */
 export declare const DEFAULT_TOAST_DURATION = 3000;
+/**
+ * How long a toast stays up. `"persistent"` = until the user dismisses it (or a later `show()`
+ * replaces it) — spelled out rather than encoded as a number, because a bare `0` at a call site
+ * reads as "no delay", not "forever".
+ */
+export type ToastDuration = number | "persistent";
+/** `setTimeout`'s delay is a 32-bit signed int; a larger value wraps and fires almost immediately. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/**
+ * WCAG 2.2.1 (Timing Adjustable) — resolves a requested duration into a real `setTimeout` delay, or
+ * `null` for "never auto-dismiss". `Toast.tsx` branches on `null` BEFORE arming the timer; nothing
+ * else in the module decides how long a toast lives.
+ *
+ * Three rules, in order:
+ *
+ * 1. **`"persistent"`, and every unusable number, mean forever.** `0`, negatives and `NaN` used to
+ *    slip past a `?? DEFAULT_TOAST_DURATION` fallback (only `null`/`undefined` are nullish) and
+ *    became `setTimeout(hide, 0)`; `Infinity` overflowed the 32-bit delay above and fired in ~1ms.
+ *    Both looked like a persistent mode and were an instant-dismiss mode. Failing towards "stays
+ *    up" is the safe direction: the card always has a close button.
+ * 2. **A running screen reader suppresses auto-dismiss entirely.** 3s is not enough to finish
+ *    speaking a message, and there is no way to replay a toast that has gone.
+ * 3. **`danger` with no explicit duration is persistent.** An error the user never finished reading
+ *    is the exact failure 2.2.1 exists to prevent, and this catalogue has no toast history to
+ *    recover it from. An explicit `duration` is still honoured — that is a deliberate caller
+ *    decision, not the default falling on an error message.
+ */
+export declare function resolveAutoDismissDelay(duration: ToastDuration | undefined, tone: ToastTone, screenReaderEnabled: boolean): number | null;
 export interface ToastToneColors {
     /** The card's own background — constant across tones (an elevated, neutral surface). */
     readonly background: string;

package/lib/typescript/modules/toast/index.d.ts

@@ -8,5 +8,5 @@
  */
 export { ToastProvider, useToast } from "./Toast";
 export type { ToastContextValue, ToastOptions, ToastProviderProps } from "./Toast";
-export type { ToastPosition, ToastTone } from "./Toast.variants";
+export type { ToastDuration, ToastPosition, ToastTone } from "./Toast.variants";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/toast/toastScreenReader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tracks whether a screen reader is running, so `ToastProvider` can stop auto-dismissing a message
+ * the reader has not finished speaking (WCAG 2.2.1 — see `resolveAutoDismissDelay`).
+ *
+ * Shaped exactly like `core/a11y`'s `useReducedMotion`: ONE module-level store read through
+ * `useSyncExternalStore`, so the async probe and the native `screenReaderChanged` listener are
+ * opened by the first subscriber and closed when the last one leaves, however many providers mount.
+ * It lives here rather than in `core/a11y` only because that folder is owned by another change in
+ * flight — it is a `core/a11y` concern and should move there (`MODULE.md` → Known gaps).
+ *
+ * **It seeds `false`, unlike `useReducedMotion`'s pessimistic `true`.** The two hooks are read at
+ * different moments: a reduce-motion gate runs in the same commit as the mount that opens the probe,
+ * so it must assume the worst, whereas this is read by `show()` — a user-initiated event, long after
+ * `ToastProvider` mounted at the app root and the probe answered. Seeding `true` would instead make
+ * every toast in the first frames of an app run persistent for a sighted user, which is the more
+ * visible failure and the less likely one to be true.
+ */
+/** Test-only: drops the process cache and re-probes, so a suite can drive both answers. */
+export declare function resetScreenReaderCache(): void;
+/** Live OS screen-reader state (VoiceOver / TalkBack), one probe and one listener per process. */
+export declare function useScreenReaderEnabled(): boolean;
+//# sourceMappingURL=toastScreenReader.d.ts.map