pixelize-native-library 1.0.6 → 1.2.0

package/lib/typescript/modules/number-input/NumberInput.variants.d.ts

@@ -13,7 +13,7 @@
  * Free of `lucide` and of any React tree, so the WCAG + behaviour tests import it directly (mocking
  * only `react-native`'s `StyleSheet`, as `core/style` does).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export type NumberInputSize = "sm" | "md" | "lg";
 /** A state, not a brand tone — same reasoning as Input's `status`. */
 export type NumberInputStatus = "default" | "error";
@@ -82,21 +82,71 @@ export declare function resolveNumberInputStepperPressColors(colors: RoleColors)
  */
 export declare function resolveNumberInputStatus(colors: RoleColors, status: NumberInputStatus): NumberInputStatusColors;
 export interface NumberInputAccessibilityInput {
+    readonly value: number;
+    readonly min?: number | undefined;
+    readonly max?: number | undefined;
     readonly label?: string | undefined;
     readonly accessibilityLabel?: string | undefined;
     readonly disabled?: boolean | undefined;
+    /**
+     * What the field is actually SHOWING — the uncommitted draft while the user types. Defaults to
+     * `String(value)`, which is only the same string once the draft has been committed and clamped.
+     */
+    readonly displayText?: string | undefined;
+    readonly status?: NumberInputStatus | undefined;
+    readonly errorText?: string | undefined;
+}
+export interface NumberInputAccessibilityValue {
+    /** Omitted entirely when the caller sets no floor — an absent bound is not `min: 0`. */
+    readonly min?: number;
+    /** Omitted entirely when the caller sets no ceiling. */
+    readonly max?: number;
+    readonly now: number;
+    readonly text: string;
 }
 export interface NumberInputAccessibilityProps {
-    /** Falls back to the visible label — a sibling `Text`, not a wrapping element RN can associate. */
+    /**
+     * Falls back to the visible label — a sibling `Text`, not a wrapping element RN can associate —
+     * with `errorText` appended in the error state, the same rule `FormField` states.
+     */
     readonly accessibilityLabel: string | undefined;
-    readonly accessibilityState: {
-        readonly disabled: boolean;
-    };
+    readonly "aria-disabled": boolean;
+    readonly "aria-invalid": boolean;
+    /** The validity message to render below the field — the visible half of WCAG 3.3.1 / 1.4.1. */
+    readonly message: string | undefined;
+    /**
+     * The bounds + current value, so AT announces the range and hears the number change (WCAG 4.1.2).
+     *
+     * Emitted in BOTH forms, unlike `Slider`'s flat-only. The host is a `TextInput`, and RN's
+     * `TextInput.js` never destructures `aria-value*` (only the five `aria-*` state aliases), while
+     * `react-native-web` never reads `accessibilityValue`. Flat-only is silent on native here;
+     * object-only is silent on web. `View`-hosted controls like `Slider` need only the flat form.
+     */
+    readonly accessibilityValue: NumberInputAccessibilityValue;
+    readonly "aria-valuemin": number | undefined;
+    readonly "aria-valuemax": number | undefined;
+    readonly "aria-valuenow": number;
+    readonly "aria-valuetext": string;
+    /** Declared so TalkBack can adjust the value from the FIELD, not only the two stepper stops. */
+    readonly accessibilityActions: ReadonlyArray<{
+        readonly name: "increment" | "decrement";
+    }>;
     /** The `TextInput` `editable` prop — false while disabled, so the field blocks typing. */
     readonly editable: boolean;
 }
-/** Same fallback contract as `resolveInputAccessibility`: an explicit `accessibilityLabel` always
- *  wins over the visible label. */
+/**
+ * Same fallback contract as `resolveInputAccessibility`: an explicit `accessibilityLabel` always wins
+ * over the visible label.
+ *
+ * `now` is the RAW `value`, deliberately NOT clamped the way `resolveSliderAccessibility` clamps its
+ * own — the caller's committed value is what the control's value IS. The announced TEXT is
+ * `displayText` (the draft the field is rendering), not `String(value)`: mid-typing the two diverge
+ * whenever a keystroke doesn't parse or clamps, and a reader speaking a different number from the
+ * one on screen is a 4.1.2 failure in itself. `min`/`max` are omitted rather than defaulted — an
+ * absent bound means "no floor"/"no ceiling" here (see `clampNumberInputValue`), and announcing
+ * `min: 0` would invent one. `accessibilityActions` mirrors `Slider`'s reasoning: iOS surfaces
+ * adjust gestures from the trait, Android TalkBack only surfaces actions declared here (WCAG 2.5.7).
+ */
 export declare function resolveNumberInputAccessibility(input: NumberInputAccessibilityInput): NumberInputAccessibilityProps;
 /** Clamps to [min, max]. Either bound may be absent, meaning "no floor"/"no ceiling" on that side. */
 export declare function clampNumberInputValue(value: number, min?: number, max?: number): number;

package/lib/typescript/modules/org-switcher/OrgSwitcher.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OrgSwitcher — a trigger showing the active org (avatar + name) that opens a sheet of every org
+ * the user belongs to: identity-tinted avatar, org name, the user's role on a second line, and an
+ * accent tint + check on the active one. Renders nothing when there's ≤1 option — a switcher with
+ * a single choice has nothing to switch to.
+ *
+ * It owns its trigger and sheet outright rather than presetting `Select`, mirroring web's
+ * OrgSwitcher (which owns its Popover rather than wrapping a generic select). `Select`'s row
+ * contract is closed at "one label, one optional leading node, a check when active" — a role
+ * subtitle and a tinted active row are org-switching concerns, not things every select should grow.
+ *
+ * Fully controlled and store-agnostic: the host app supplies the org list and owns wherever the
+ * active org actually lives (Redux, context, …) — this module never reads or dispatches app state,
+ * the same contract every other module in this library holds to.
+ *
+ * `Modal` is imported directly from `"react-native"`, and the web-portal branch mirrors `Select`'s
+ * — see that file's header for why both are deliberate.
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { OrgSwitcherSize } from "./OrgSwitcher.variants";
+export interface OrgSwitcherOption {
+    readonly value: string;
+    readonly label: string;
+    /** The user's role in this org, shown as a second line under the name. */
+    readonly role?: string;
+    /** A remote logo/avatar image. Wins over `avatarInitials` when present. */
+    readonly avatarSource?: {
+        uri: string;
+    };
+    /** Falls back to initials derived from `label` when omitted. */
+    readonly avatarInitials?: string;
+}
+export interface OrgSwitcherProps {
+    options: OrgSwitcherOption[];
+    value?: string;
+    onValueChange: (value: string) => void;
+    placeholder?: string;
+    size?: OrgSwitcherSize;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    containerStyle?: LayoutStyle;
+    testID?: string;
+}
+export declare const OrgSwitcher: import("react").NamedExoticComponent<OrgSwitcherProps>;
+//# sourceMappingURL=OrgSwitcher.d.ts.map

package/lib/typescript/modules/org-switcher/OrgSwitcher.variants.d.ts

@@ -0,0 +1,139 @@
+/**
+ * OrgSwitcher's style + behaviour resolution — the same split every sibling module holds to:
+ *  - STRUCTURE (sizing/spacing off the theme scale) lives in the `createThemedVariants` resolvers
+ *    below — static per (brand, mode), registered once.
+ *  - COLOUR is resolved from the theme's ROLE colours (never a raw ramp, never a hardcoded hex) by
+ *    `resolveOrgSwitcherTriggerColors` / `resolveOrgSwitcherRowColors`.
+ *
+ * Why this module resolves its own row colours instead of reusing `Select`'s: `Select` pins every
+ * row to `bg.surface` and conveys selection with a check glyph alone, because `bg.selected` is not
+ * provably readable on every brand. Web's OrgSwitcher tints the active row, and that tint is the
+ * cue a user actually sees when the sheet opens. `accent.subtle` + `accent.text` is the one role
+ * pair the role table already guarantees at 4.5:1 for every brand × mode, so the tint comes from
+ * there rather than from widening `Select`'s deliberately closed row contract.
+ *
+ * Free of React and of any `Modal`/`Pressable` 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/hooks";
+import type { AvatarSize } from "../avatar";
+export type OrgSwitcherSize = "sm" | "md" | "lg";
+/** Same touch-target floor as Button (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export declare const MIN_TOUCH_TARGET = 44;
+export interface OrgSwitcherSizeSpec {
+    /** Visual trigger height in dp. */
+    readonly height: number;
+    /** Org-name text size on the trigger, on the theme's `fontSizes` scale. */
+    readonly fontSize: number;
+    /** Chevron glyph size in dp. */
+    readonly iconSize: number;
+    /** Avatar size used on the trigger AND on every row, as web uses one avatar size for both. */
+    readonly avatarSize: AvatarSize;
+    /** Symmetric touch expansion so `height + 2·hitSlop ≥ 44`. */
+    readonly hitSlop: number;
+}
+export declare const ORG_SWITCHER_SIZES: {
+    readonly sm: {
+        readonly height: 32;
+        readonly fontSize: 14;
+        readonly iconSize: 16;
+        readonly avatarSize: "xs";
+        readonly hitSlop: number;
+    };
+    readonly md: {
+        readonly height: 40;
+        readonly fontSize: 16;
+        readonly iconSize: 18;
+        readonly avatarSize: "sm";
+        readonly hitSlop: number;
+    };
+    readonly lg: {
+        readonly height: 48;
+        readonly fontSize: 18;
+        readonly iconSize: 20;
+        readonly avatarSize: "md";
+        readonly hitSlop: number;
+    };
+};
+/** Minimum height for an org row — a list item is still an interactive target (WCAG 2.5.8). */
+export declare const ORG_SWITCHER_ROW_MIN_HEIGHT = 44;
+/** The "check" glyph beside the active row. Fixed — independent of the trigger's own `size`. */
+export declare const ORG_SWITCHER_ROW_ICON_SIZE = 18;
+export interface OrgSwitcherTriggerColors {
+    readonly background: string;
+    readonly border: string;
+    /** Colour for the active org's name. */
+    readonly text: string;
+    /** Colour for the placeholder (no org selected yet). */
+    readonly placeholder: string;
+    /** Chevron + empty-state building glyph colour. */
+    readonly icon: string;
+}
+/** `pressed` covers the touch-down state; there is no hover on a touch device. */
+export declare function resolveOrgSwitcherTriggerColors(colors: RoleColors, pressed: boolean): OrgSwitcherTriggerColors;
+export interface OrgSwitcherRowColors {
+    /** Row fill: the accent tint while active, the sheet's surface otherwise, and its press
+     *  counterpart under a finger. All three carry `text`, `subtitle` and `icon` legibly. */
+    readonly background: string;
+    /** Org-name colour. */
+    readonly text: string;
+    /** Role subtitle colour. */
+    readonly subtitle: string;
+    /** "check" glyph colour, only rendered when `selected` — a non-text UI component, so 3:1. */
+    readonly icon: string;
+}
+/**
+ * Press moves each row to the OTHER row fill — active loses its tint, inactive gains `bg.sunken` —
+ * rather than both landing on one shared pressed colour: on zinc (the default brand) `accent.subtle`
+ * and `bg.sunken` are the same value, so a shared pressed fill gives the active row no feedback at
+ * all. The ink never changes with the fill, because all three fills clear AA for both text roles.
+ */
+export declare function resolveOrgSwitcherRowColors(colors: RoleColors, selected: boolean, pressed: boolean): OrgSwitcherRowColors;
+export interface OrgSwitcherAccessibilityInput {
+    readonly open: boolean;
+    /** The active org's name, or `undefined` when nothing is selected yet. */
+    readonly selectedLabel: string | undefined;
+    readonly placeholder: string;
+}
+export interface OrgSwitcherAccessibilityProps {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string;
+    /** Flat, not `accessibilityState`: react-native-web discards the object form entirely. */
+    readonly "aria-expanded": boolean;
+}
+/**
+ * The trigger shows only the org name, so the accessible name has to say what the control IS —
+ * "Acme Inc" alone tells a screen-reader user nothing about switching orgs (WCAG 4.1.2, which also
+ * requires the expanded/collapsed state a collapsible control is in).
+ */
+export declare function resolveOrgSwitcherAccessibility(input: OrgSwitcherAccessibilityInput): OrgSwitcherAccessibilityProps;
+/** Initials for the fallback avatar: first letters of the first two words, as `Avatar` clips to two. */
+export declare function orgInitials(label: string): string;
+export declare const orgSwitcherTriggerStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            height: 32;
+            paddingHorizontal: 8;
+        };
+        md: {
+            height: 40;
+            paddingHorizontal: 12;
+        };
+        lg: {
+            height: 48;
+            paddingHorizontal: 16;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** The trigger's animated layer: press motion moves the content, never the fill or the border. */
+export declare const orgSwitcherTriggerContentStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Avatar + org name, in one shrinkable row so the chevron stays pinned right. */
+export declare const orgSwitcherTriggerValueStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const orgSwitcherOverlayStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const orgSwitcherSheetStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const orgSwitcherRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The row's animated layer: press motion moves the content, never the row fill. */
+export declare const orgSwitcherRowContentStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Name over role, taking the row's flexible width so both truncate rather than push the check off. */
+export declare const orgSwitcherRowBodyStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=OrgSwitcher.variants.d.ts.map

package/lib/typescript/modules/org-switcher/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public surface of `pixelize-native-library/org-switcher`. Value exports and type exports are
+ * split for `verbatimModuleSyntax`.
+ */
+export { OrgSwitcher } from "./OrgSwitcher";
+export type { OrgSwitcherProps, OrgSwitcherOption } from "./OrgSwitcher";
+export type { OrgSwitcherSize } from "./OrgSwitcher.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/pagination/Pagination.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pagination — page navigation controls in three shapes, driven entirely by props: `numbered` (a
+ * windowed strip of page numbers), `compact` ("Page 3 of 12" between two arrows — the shape that
+ * actually fits a phone), and `loadMore` (one button, for a cursor/infinite list that has no page
+ * count at all).
+ *
+ * All the interesting logic is pure and lives in `Pagination.variants.ts` — `buildPageRange` is the
+ * whole reason this module exists, since every app that re-derives it gets an edge case wrong.
+ * This file is the wiring: role colours in, `onPageChange` out. It owns no state and makes no
+ * assumption about where the pages come from.
+ *
+ * The one animated surface is `compact`'s summary, which fades in when the page changes
+ * (`core/motion`). The `numbered` strip is deliberately static — it is a row of controls, and
+ * animating each one on every page change is noise, not feedback.
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { PaginationSize, PaginationVariant } from "./Pagination.variants";
+export interface PaginationProps {
+    /** The current page, 1-indexed. Out-of-bounds values clamp — they never throw or blank the strip. */
+    page: number;
+    /** Total pages. `0` renders nothing (there is nothing to paginate). Ignored by `loadMore`. */
+    pageCount: number;
+    onPageChange: (page: number) => void;
+    variant?: PaginationVariant;
+    /** Pages shown either side of the current one. `numbered` only. */
+    siblingCount?: number;
+    /** Adds jump-to-first / jump-to-last controls. `numbered` and `compact`. */
+    showFirstLast?: boolean;
+    disabled?: boolean;
+    /** Blocks every control and announces `busy`; in `loadMore` it also swaps in a spinner. */
+    loading?: boolean;
+    /** Required by `variant="loadMore"`. */
+    onLoadMore?: () => void;
+    /** Required by `variant="loadMore"` — `false` renders nothing once no page is in flight. */
+    hasMore?: boolean;
+    loadMoreLabel?: string;
+    size?: PaginationSize;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+declare function PaginationImpl({ page, pageCount, onPageChange, variant, siblingCount, showFirstLast, disabled, loading, onLoadMore, hasMore, loadMoreLabel, size, style, testID, }: PaginationProps): import("react").JSX.Element | null;
+export declare const Pagination: import("react").MemoExoticComponent<typeof PaginationImpl>;
+export {};
+//# sourceMappingURL=Pagination.d.ts.map

package/lib/typescript/modules/pagination/Pagination.variants.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Pagination's pure logic + style resolution — same split as Button/ButtonGroup:
+ *  - PAGE ARITHMETIC (`buildPageRange`, `clampPage`) is the reason this module exists. It is pure,
+ *    total, and never throws, so the exhaustive edge cases live in `Pagination.test.ts` rather than
+ *    being re-derived (and subtly re-broken) in every consumer app.
+ *  - STRUCTURE (control height/padding/radius) lives in the `createThemedVariants` resolvers below,
+ *    registered once per (theme, size) — never rebuilt per render.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolvePaginationColors`), never a raw hex.
+ *  - ACCESSIBILITY prop derivation is `resolvePaginationStep` / `resolvePaginationPage`, kept pure
+ *    so the "boundary arrow is disabled / current page is selected" contract is unit-testable
+ *    without rendering React Native.
+ *
+ * Free of React, `lucide`, and any native import, so the WCAG + logic tests import it directly
+ * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+import type { RoleColors, Theme } from "../../theme/hooks";
+export type PaginationVariant = "numbered" | "compact" | "loadMore";
+export type PaginationSize = "sm" | "md";
+/** One slot in the numbered strip: a page number, or a gap marker standing in for a run of pages. */
+export type PageItem = number | "ellipsis";
+/** Same touch-target floor as Button/ButtonGroup (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export declare const MIN_TOUCH_TARGET = 44;
+/**
+ * The WIDTH-axis touch floor, met by the rendered node itself rather than by horizontal `hitSlop` —
+ * see `resolvePaginationHitSlop` for why this control can never expand sideways.
+ */
+export declare const PAGINATION_CONTROL_MIN_WIDTH = 44;
+export interface PaginationSizeSpec {
+    /** Visual height in dp (fixed, not a minimum — the hitSlop math depends on it). */
+    readonly height: number;
+    /** Label size, on the theme's `fontSizes` scale. */
+    readonly fontSize: number;
+    /** Icon glyph size in dp. */
+    readonly iconSize: number;
+    /** Vertical touch expansion so `height + 2·hitSlop ≥ 44`. */
+    readonly hitSlop: number;
+}
+/**
+ * Pagination-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
+ * test can assert `height + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.
+ */
+export declare const PAGINATION_SIZES: {
+    readonly sm: {
+        readonly height: 32;
+        readonly fontSize: 14;
+        readonly iconSize: 16;
+        readonly hitSlop: number;
+    };
+    readonly md: {
+        readonly height: 40;
+        readonly fontSize: 16;
+        readonly iconSize: 18;
+        readonly hitSlop: number;
+    };
+};
+/** A page count of 0 means "nothing to paginate"; negatives and garbage normalise to it. */
+export declare function normalizePageCount(pageCount: number): number;
+/**
+ * The current page, forced into `[1, pageCount]`. An out-of-bounds `page` (a stale value after a
+ * filter shrank the result set is the common one) clamps rather than rendering an empty strip or
+ * throwing. With no pages at all this still answers `1`, so a caller that renders anyway shows
+ * "Page 1 of 0" instead of "Page 0 of 0" — `Pagination` itself renders nothing in that state.
+ */
+export declare function clampPage(page: number, pageCount: number): number;
+/**
+ * The page-window resolver — which page numbers the numbered strip shows around `page`, with
+ * `"ellipsis"` standing in for each elided run.
+ *
+ * The strip is a fixed width so it never reflows as the user pages through: first + last + current
+ * + both sibling runs + both gap markers = `2·siblingCount + 5` slots. Below that many pages there
+ * is nothing to elide, so every page is listed. Above it, one or both gaps appear; whichever end
+ * has no gap gets a longer run of consecutive pages (`2·siblingCount + 3`) so the total stays
+ * constant.
+ *
+ * A gap is only drawn once it would hide at least TWO pages: a marker standing in for a single
+ * number is strictly worse than the number (it costs the same slot and navigates nowhere), which
+ * is why the thresholds are `> 3` / `< total - 2` and not the usual off-by-one `> 2` / `< total - 1`.
+ */
+export declare function buildPageRange(page: number, pageCount: number, siblingCount?: number): PageItem[];
+export interface PaginationColors {
+    /** Current-page pill fill. */
+    readonly currentFill: string;
+    /** Label on `currentFill` — the derived on-colour, so it always clears 4.5:1 (never a hard white). */
+    readonly onCurrentFill: string;
+    /** Idle page number, compact summary, load-more label — read on the canvas. */
+    readonly label: string;
+    /**
+     * Every INERT control: a boundary arrow, any control while the whole component is disabled or
+     * loading, and the decorative ellipsis. Deliberately a colour swap and NOT Button's
+     * `opacity: 0.5` dim — see MODULE.md's 1.4.11 note: a disabled arrow is the only thing telling a
+     * user they are at the first/last page, so it has to stay perceivable rather than take the
+     * "disabled controls are exempt from contrast" exemption.
+     */
+    readonly inactiveLabel: string;
+    /** Pressed background for an interactive control; `label` stays ≥ 4.5:1 on it. */
+    readonly pressedFill: string;
+    /** The load-more button's outline (WCAG 1.4.11 ≥ 3:1 on every brand), same token Button uses. */
+    readonly border: string;
+}
+/**
+ * Maps the component's fixed visual roles onto ROLE colours. There is no `tone` union: the current
+ * page is always the accent role and the outline is always the neutral interactive outline, so —
+ * like `ButtonGroup` — this is pure indirection, not a union to resolve.
+ *
+ * `pressedFill` is `bg.sunken`, NOT `bg.hover`: same class of fix Button's "neutral" tone and
+ * RadioGroup/Menu document (the saturated `hover` mid-tone drops a brand-tinted label below 4.5:1).
+ * Unlike ButtonGroup it needs no compositing to clear the selected fill, because controls here are
+ * separated by a `space[1]` gutter — a pressed neighbour never shares an edge with the current-page
+ * pill, so that boundary is always fill-vs-canvas.
+ */
+export declare function resolvePaginationColors(colors: RoleColors): PaginationColors;
+export type PaginationStepKind = "first" | "previous" | "next" | "last";
+export declare const STEP_LABELS: {
+    readonly first: "First page";
+    readonly previous: "Previous page";
+    readonly next: "Next page";
+    readonly last: "Last page";
+};
+export declare const DEFAULT_LOAD_MORE_LABEL = "Load more";
+export declare function formatPageLabel(page: number, pageCount: number): string;
+export interface PaginationStepInput {
+    readonly kind: PaginationStepKind;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly disabled: boolean;
+    readonly loading: boolean;
+}
+export interface PaginationStepA11y {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string;
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted keys so the compiler still checks the prop names. */
+    readonly "aria-disabled": boolean;
+    readonly "aria-busy": boolean;
+    /** The `Pressable` disabled prop — blocks touches without relying on `onPress` gating alone. */
+    readonly disabled: boolean;
+    /** The page a press navigates to; `undefined` whenever the control is inert. */
+    readonly targetPage: number | undefined;
+}
+/**
+ * One step control's accessibility + navigation surface. A step is inert when the whole component
+ * is disabled/loading OR when its target is out of range or already the current page — the
+ * boundary case, which announces `disabled` so a screen reader user learns they are at an end
+ * instead of pressing a silently dead control.
+ */
+export declare function resolvePaginationStep(input: PaginationStepInput): PaginationStepA11y;
+export interface PaginationPageInput {
+    readonly item: number;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly disabled: boolean;
+    readonly loading: boolean;
+}
+export interface PaginationPageA11y {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string;
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted keys so the compiler still checks the prop names. */
+    readonly "aria-disabled": boolean;
+    readonly "aria-busy": boolean;
+    /** The WEB half of "this is the page you are on". `aria-current="page"` is the WAI-ARIA signal
+     *  for exactly this, and unlike `aria-selected` it IS valid on `role="button"`. No React Native
+     *  equivalent exists, so the native half rides `accessibilityState.selected` below. */
+    readonly "aria-current": "page" | undefined;
+    /** The NATIVE half — discarded by react-native-web, so no invalid `aria-selected` on a button. */
+    readonly accessibilityState: {
+        readonly selected: boolean;
+    };
+    readonly disabled: boolean;
+    readonly targetPage: number | undefined;
+    readonly current: boolean;
+}
+/**
+ * One page-number control's accessibility + navigation surface.
+ *
+ * The current page is inert (`targetPage: undefined`) but is NOT reported disabled: it is the
+ * selected item, not an unavailable one, and announcing both would tell assistive tech the user's
+ * own position is broken. `disabled` therefore only ever reflects the component-wide gate.
+ */
+export declare function resolvePaginationPage(input: PaginationPageInput): PaginationPageA11y;
+export interface PaginationHitSlop {
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+}
+/**
+ * Vertical expansion only. Controls sit in a row `space[1]` apart, and React Native never clips
+ * `hitSlop` to a sibling's bounds — it resolves an overlap to whichever sibling renders LATER, not
+ * to whichever is visually closer to the tap, so horizontal slop wide enough to matter would hand a
+ * tap near a gutter to the wrong page (the defect `ButtonGroup` documents fixing the same way).
+ * The width axis is met by `PAGINATION_CONTROL_MIN_WIDTH` on the rendered node instead.
+ */
+export declare function resolvePaginationHitSlop(size: PaginationSize): PaginationHitSlop;
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (those are
+ * resolved from `RoleColors` and applied inline), so these compile once per theme identity via the
+ * `WeakMap`-cached themed resolver and never rebuild per render.
+ */
+export declare const paginationRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/**
+ * The numbered strip's root. A column box on purpose: it stretches the horizontal `ScrollView`
+ * inside it to the root's own width, which is what BOUNDS the scroll view — a horizontal
+ * `ScrollView` sized by its content instead overflows its parent and never scrolls. No theme
+ * dependency, so the untethered resolver — same idiom `drawerOverlayStructure` uses.
+ */
+export declare const paginationStripRootStructure: import("../../core/style").VariantResolver<import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const paginationScrollContentStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const paginationControlStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            height: 32;
+        };
+        md: {
+            height: 40;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** Narrower than a control: the gap marker is decorative, so it owes no touch target. */
+export declare const paginationEllipsisStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            height: 32;
+        };
+        md: {
+            height: 40;
+        };
+    };
+}, import("react-native").ViewStyle>;
+export declare const paginationLoadMoreStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            height: 32;
+        };
+        md: {
+            height: 40;
+        };
+    };
+}, import("react-native").ViewStyle>;
+//# sourceMappingURL=Pagination.variants.d.ts.map

package/lib/typescript/modules/pagination/PaginationControls.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PRIVATE sub-components (not exported from `index.ts`). One control per node, each `React.memo`'d
+ * and fed primitives only, so a page change re-renders the two controls whose state actually
+ * changed instead of the whole strip — and so no `onPress`/`style` closure is rebuilt per control
+ * per render.
+ */
+import type { IconName } from "../../core/icon";
+import type { Theme } from "../../theme/hooks";
+import type { PaginationColors, PaginationHitSlop, PaginationSize, PaginationStepKind } from "./Pagination.variants";
+interface PaginationStepControlProps {
+    readonly kind: PaginationStepKind;
+    readonly icon: IconName;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly disabled: boolean;
+    readonly loading: boolean;
+    readonly size: PaginationSize;
+    readonly iconSize: number;
+    readonly theme: Theme;
+    readonly colors: PaginationColors;
+    readonly hitSlop: PaginationHitSlop;
+    readonly onPageChange: (page: number) => void;
+    readonly testID: string | undefined;
+}
+export declare const PaginationStepControl: import("react").NamedExoticComponent<PaginationStepControlProps>;
+interface PaginationPageControlProps {
+    readonly item: number;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly disabled: boolean;
+    readonly loading: boolean;
+    readonly blocked: boolean;
+    readonly size: PaginationSize;
+    readonly fontSize: number;
+    readonly theme: Theme;
+    readonly colors: PaginationColors;
+    readonly hitSlop: PaginationHitSlop;
+    readonly onPageChange: (page: number) => void;
+    readonly testID: string | undefined;
+}
+export declare const PaginationPageControl: import("react").NamedExoticComponent<PaginationPageControlProps>;
+interface PaginationEllipsisProps {
+    readonly size: PaginationSize;
+    readonly fontSize: number;
+    readonly theme: Theme;
+    readonly color: string;
+}
+export declare const PaginationEllipsis: import("react").NamedExoticComponent<PaginationEllipsisProps>;
+export {};
+//# sourceMappingURL=PaginationControls.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * Public surface of `pixelize-native-library/pagination`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The visual resolvers (`resolvePaginationColors`, `PAGINATION_SIZES`,
+ * …) stay internal — a consumer configures a Pagination through its props.
+ *
+ * `buildPageRange` / `clampPage` are the documented exception: they are pure, dependency-free page
+ * arithmetic, and the whole point of this module is that an app never re-derives them by hand for
+ * a pager it draws itself.
+ */
+export { Pagination } from "./Pagination";
+export type { PaginationProps } from "./Pagination";
+export { buildPageRange, clampPage } from "./Pagination.variants";
+export type { PageItem, PaginationSize, PaginationVariant } from "./Pagination.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/pin-input/PinInput.d.ts

@@ -27,6 +27,12 @@ export interface PinInputProps {
     secureTextEntry?: boolean;
     keyboardType?: PinInputKeyboardType;
     status?: PinInputStatus;
+    /**
+     * The validity message. Shown below the row and folded into the field's accessible name when
+     * `status` is `"error"` — same prop name and same rule as `Input`/`FormField`. Without it an
+     * error is a red border and nothing else, which no screen-reader or colour-blind user can perceive.
+     */
+    errorText?: string;
     disabled?: boolean;
     size?: PinInputSize;
     autoFocus?: boolean;