pixelize-native-library 1.0.7 → 1.2.0

package/lib/typescript/modules/drawer/Drawer.variants.d.ts

@@ -4,24 +4,15 @@
  *    resolvers below, static per (brand, mode), registered once via `StyleSheet.create`.
  *  - COLOUR is resolved from the theme's ROLE colours by `resolveDrawerPanelColors`, never a raw
  *    ramp and never a hardcoded hex.
- *  - The reduced-motion contract (WCAG 2.3.3) is `resolveDrawerAnimationDuration`, and the
- *    safe-area-less bottom-inset fallback is `resolveDrawerBottomInset` — both kept pure so they are
+ *  - TIMING is not here at all: duration, easing and the reduced-motion contract (WCAG 2.3.3) come
+ *    from the global motion system (`core/motion`), so retuning the library retunes this drawer.
+ *  - The safe-area-less bottom-inset fallback is `resolveDrawerBottomInset` — kept pure so it is
  *    unit-testable without rendering React Native.
  *
  * Free of React and of any `Modal`/`Pressable`/`Animated` import, so the tests import it directly
  * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
  */
-import type { RoleColors, Theme } from "../../theme";
-/** The slide-up + backdrop-fade duration in ms. A component design constant — not on the theme's
- *  numeric scale — same status `PRESS_FADE_MS` (Button) / `ANIMATION_MS` (Toast) have. */
-export declare const DRAWER_ANIMATION_MS = 260;
-/** WCAG 2.3.3 — the slide/fade collapses to an instant snap (never a frozen frame) when the OS has
- *  reduced motion on. Mirrors Modal's `resolveModalAnimationType`, pulled into its own resolver
- *  because Drawer drives the transition with `Animated.timing` (a duration), not RN Modal's
- *  `animationType` (a discrete enum) — Modal's own native transition can't also fade a separately
- *  Animated backdrop in lockstep with a custom slide, which is why this module never sets
- *  `animationType` to anything but `"none"` and does the whole transition itself. */
-export declare function resolveDrawerAnimationDuration(reducedMotion: boolean): number;
+import type { RoleColors, Theme } from "../../theme/hooks";
 /**
  * Static bottom-inset fallback. `react-native-safe-area-context` is listed as an optional peer in
  * `peerDependenciesMeta`, but — same finding `Toast`'s MODULE.md already recorded — it is not

package/lib/typescript/modules/empty-state/EmptyState.d.ts

@@ -5,10 +5,13 @@
  * composition (the same reasoning `AlertDialog` documents for its own footer buttons) — never a
  * hand-rolled `Pressable` that would duplicate Button's press/focus/disabled/hit-target wiring.
  *
- * No `accessibilityRole` of its own: like `Card`, this is a plain grouping container with no
- * interaction beyond the composed Button, so there is nothing here for assistive tech to announce
- * beyond its children — the title and description read as their own `Text` elements, in order,
- * and the icon (redundant with the title) is hidden from the accessibility tree entirely.
+ * No `accessibilityRole` on the container: like `Card`, this is a plain grouping container with no
+ * interaction beyond the composed Button. The title is the state's heading (`accessibilityRole=
+ * "header"` at level 2, WCAG 1.3.1 / 2.4.6), the description reads as its own `Text` after it, and the icon
+ * (redundant with the title) is hidden from the accessibility tree entirely.
+ *
+ * Appearing is itself the status message (WCAG 4.1.3): a screen swapping its content for this block
+ * moves no focus, so `useAnnounce` speaks the title + description once, on arrival and on change.
  */
 import type { IconName } from "../../core/icon";
 import type { LayoutStyle } from "../../core/style";

package/lib/typescript/modules/empty-state/EmptyState.variants.d.ts

@@ -11,7 +11,7 @@
  * Free of React and lucide, so the WCAG test imports this 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";
 /**
  * The icon glyph's rendered size, in dp. A component design constant — same status `Button`'s
  * `ICON_STROKE` / `BUTTON_SIZES.*.iconSize` have — not on the theme's numeric scale: EmptyState
@@ -33,6 +33,12 @@ export interface EmptyStateColors {
  * it inverts light↔dark for free and can never be an off-palette value an app invented.
  */
 export declare function resolveEmptyStateColors(colors: RoleColors): EmptyStateColors;
+/**
+ * What a screen reader hears when this state appears (WCAG 4.1.3). The description carries the
+ * recovery step ("Try a different search"), so it is announced with the title rather than left to a
+ * swipe the user has no reason to make.
+ */
+export declare function resolveEmptyStateAnnouncement(title: string, description: string | undefined): string;
 /**
  * Structural styles only — centring, padding, and the vertical rhythm between children. No
  * colours (those are resolved separately and applied inline over this) and no closed union to

package/lib/typescript/modules/fab/Fab.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Fab — a floating action button: an absolutely-positioned, safe-area-aware primary-action circle
+ * (or pill, when `label` is given — the EXTENDED variant, icon + text). It renders one small
+ * wrapper View around its own `Pressable` — `position: "absolute"` for every floating `position`,
+ * plain in-flow `position: "relative"` for `"static"` — so `bottom-center` can center a
+ * variable-width extended Fab via `alignItems` rather than a measured `translateX`
+ * (`resolveFabAnchorStyle`'s own comment has the full reasoning).
+ *
+ * `FabProps` is a discriminated union, the same shape `ButtonProps` already establishes: a labelled
+ * (extended) Fab, or an icon-only Fab whose `accessibilityLabel` is REQUIRED at the type level — the
+ * same unlabelled-icon-button trap `Button.tsx`'s own top comment documents; `label?: never` keeps
+ * the two shapes mutually exclusive.
+ *
+ * Press feedback (one motion-system value driving the state-layer overlay + the press scale, with a
+ * brightness-aware scrim direction) and the offset focus ring are Button's own techniques, copied
+ * here rather than imported — `fab/` stays
+ * free of a cross-module dependency on `button/` internals, the same isolation `Toast.variants.ts`
+ * documents for its own duplicated `MIN_TOUCH_TARGET`.
+ */
+import type { GestureResponderEvent, MouseEvent, NativeSyntheticEvent, TargetedEvent } from "react-native";
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { FabPosition, FabSize, FabTone } from "./Fab.variants";
+interface FabBaseProps {
+    onPress: () => void;
+    tone?: FabTone;
+    size?: FabSize;
+    position?: FabPosition;
+    disabled?: boolean;
+    /** Replaces the icon with a spinner and suppresses the press, same contract as `Button`. */
+    loading?: boolean;
+    /** Extra inset on top of the safe-area approximation — see `Fab.variants.ts`'s
+     *  `resolveFabBottomInset`/`resolveFabHorizontalInset`. Ignored when `position` is `"static"`. */
+    offset?: {
+        readonly bottom?: number;
+        readonly horizontal?: number;
+    };
+    /**
+     * The exact set a wrapping `Tooltip` injects via `cloneElement`, same contract `Button` declares.
+     * Explicit because `{...rest}` is banned repo-wide: an undeclared prop is dropped, so without
+     * these a tooltip on a Fab never opens. Chained after the Fab's own press/focus state.
+     */
+    onLongPress?: (event: GestureResponderEvent) => void;
+    onPressOut?: (event: GestureResponderEvent) => void;
+    onHoverIn?: (event: MouseEvent) => void;
+    onHoverOut?: (event: MouseEvent) => void;
+    onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    accessibilityHint?: string;
+    /** react-native-web has no `accessibilityHint`, so a wrapping `Tooltip` describes the control by
+     *  id instead — inert on native, where the hint above is the equivalent. */
+    "aria-describedby"?: string;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+/** A Fab with a visible text label — the EXTENDED variant (a pill, icon + text). */
+interface LabelledFabProps extends FabBaseProps {
+    icon: IconName;
+    label: string;
+    accessibilityLabel?: string;
+}
+/** An icon-only Fab. No visible text, so `accessibilityLabel` is REQUIRED at the type level — the
+ *  same trap `Button`'s icon-only shape closes. `label?: never` keeps the two shapes exclusive. */
+interface IconOnlyFabProps extends FabBaseProps {
+    icon: IconName;
+    label?: never;
+    accessibilityLabel: string;
+}
+export type FabProps = LabelledFabProps | IconOnlyFabProps;
+declare function FabImpl(props: FabProps): import("react").JSX.Element;
+export declare const Fab: import("react").MemoExoticComponent<typeof FabImpl>;
+export {};
+//# sourceMappingURL=Fab.d.ts.map

package/lib/typescript/modules/fab/Fab.variants.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Fab's style + behaviour resolution — same split as Button/Card:
+ *  - STRUCTURE (diameter/padding/radius) lives in the `createThemedVariants` resolvers below, static
+ *    per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is tone-driven and resolved from the theme's ROLE colours by `resolveFabTone` — the same
+ *    three-tone mapping `resolveButtonTone` uses for Button's `solid` variant (a Fab IS a solid
+ *    circular/pill button; there is no outline/ghost/link shape here). Duplicated, not imported —
+ *    modules stay isolated, the same status `Toast.variants.ts` documents for its own duplicated
+ *    `MIN_TOUCH_TARGET`.
+ *  - ACCESSIBILITY prop derivation is `resolveFabAccessibility`, the same disabled/loading→busy,
+ *    gated-onPress contract `resolveButtonAccessibility` establishes.
+ *  - POSITIONING (`resolveFabAnchorStyle`, `resolveFabBottomInset`, `resolveFabHorizontalInset`) is
+ *    pure so the safe-area-less approximation is unit-testable without rendering React Native — the
+ *    same idiom `Drawer.variants.ts`'s `resolveDrawerBottomInset` and `BottomNav.variants.ts`'s
+ *    `resolveBottomNavBottomInset` already establish (see MODULE.md "Known gaps" for why
+ *    `react-native-safe-area-context` isn't imported here either — it is an optional peer, not a
+ *    real dependency of this package).
+ *
+ * Free of React, lucide, and any Pressable/Animated 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";
+export type FabTone = "accent" | "neutral" | "danger";
+export type FabSize = "md" | "lg";
+export type FabPosition = "bottom-right" | "bottom-left" | "bottom-center" | "static";
+/** Both sizes already clear this floor directly (48dp / 56dp) — no `hitSlop` needed, unlike Button's
+ *  shorter sizes (WCAG 2.5.5 AAA / Apple HIG minimum). */
+export declare const MIN_TOUCH_TARGET = 44;
+export interface FabSizeSpec {
+    /** Visual diameter (icon-only) / pill height (extended), in dp. */
+    readonly diameter: number;
+    readonly iconSize: number;
+    /** Extended-variant label size, on the theme's `fontSizes` scale. */
+    readonly fontSize: number;
+    /** Extended-variant horizontal padding. */
+    readonly extendedPaddingHorizontal: number;
+}
+export declare const FAB_SIZES: {
+    readonly md: {
+        readonly diameter: 48;
+        readonly iconSize: 20;
+        readonly fontSize: 14;
+        readonly extendedPaddingHorizontal: 16;
+    };
+    readonly lg: {
+        readonly diameter: 56;
+        readonly iconSize: 24;
+        readonly fontSize: 16;
+        readonly extendedPaddingHorizontal: 20;
+    };
+};
+/** A FabGroup mini action reads at one fixed size, independent of the trigger's own `size` — the
+ *  same "an action list's row size isn't a caller-facing choice" precedent `Menu`'s row size sets. */
+export declare const FAB_ACTION_SIZE = 44;
+export declare const FAB_ACTION_ICON_SIZE = 18;
+export interface FabToneColors {
+    readonly fill: string;
+    readonly onFill: string;
+}
+/**
+ * Maps `tone` onto the theme's role colours — identical to `resolveButtonTone`'s `solid` branch (a
+ * Fab has no outline/ghost/link shape, so only `fill`/`onFill` are needed). The whole reason the
+ * prop is a closed union and not `color?: string`: every colour a Fab can show is one of these role
+ * lookups, so it inverts light↔dark for free and can never be an off-palette value an app invented.
+ */
+export declare function resolveFabTone(colors: RoleColors, tone: FabTone): FabToneColors;
+export interface FabAccessibilityInput {
+    readonly label?: string | undefined;
+    readonly accessibilityLabel?: string | undefined;
+    readonly disabled?: boolean | undefined;
+    readonly loading?: boolean | undefined;
+    readonly onPress: () => void;
+}
+export interface FabAccessibilityProps {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string | undefined;
+    readonly "aria-disabled": boolean;
+    readonly "aria-busy": boolean;
+    readonly disabled: boolean;
+    /** Gated: `undefined` while disabled or loading, so a press can't fire (mirrors Button). */
+    readonly onPress: (() => void) | undefined;
+}
+/**
+ * Same disabled/loading→busy, gated-onPress derivation as `resolveButtonAccessibility` (WCAG 1.4.1
+ * busy announcement / 4.1.2 name-role-value), kept pure so it's testable without rendering RN.
+ *
+ * FLAT `aria-*`, not `accessibilityState={{…}}`: react-native-web 0.21 forwards a purely flat
+ * vocabulary and drops the object entirely, so the web build announced the role with no state at
+ * all. RN's own `Pressable` merges the flat props back INTO `accessibilityState`, so one flat form
+ * is correct on both platforms — the same migration `resolveCheckboxAccessibility` documents.
+ */
+export declare function resolveFabAccessibility(input: FabAccessibilityInput): FabAccessibilityProps;
+/**
+ * iOS home-indicator approximation — same formula and value `Drawer.variants.ts`'s
+ * `DRAWER_IOS_HOME_INDICATOR_INSET` and `BottomNav.variants.ts`'s `BOTTOM_NAV_IOS_HOME_INDICATOR_INSET`
+ * each carry independently. `react-native-safe-area-context` is listed as an optional peer in
+ * `package.json`, but — as both of those modules' own MODULE.md already record — it is not actually
+ * installed as a dependency of THIS package, so importing `useSafeAreaInsets` here would resolve in
+ * this repo's dev sandbox and then fail in a consumer app that hasn't separately installed it. Carried
+ * a third time here rather than imported from a sibling module's `.variants.ts` — cross-module
+ * internals reach-in isn't a dependency this library's modules take on each other.
+ */
+export declare const FAB_IOS_HOME_INDICATOR_INSET = 20;
+/** Adds the static iOS home-indicator approximation, plus any caller-supplied `offset.bottom`, to a
+ *  base padding. Android's gesture/3-button nav already reserves its own space outside the app
+ *  window, so it gets no extra padding beyond the caller's own `offset`. */
+export declare function resolveFabBottomInset(basePadding: number, platformOS: string, extra?: number): number;
+/** Adds any caller-supplied `offset.horizontal` to a base padding — no platform-specific inset on
+ *  this axis (the home-indicator approximation above is bottom-edge only). */
+export declare function resolveFabHorizontalInset(basePadding: number, extra?: number): number;
+export interface FabAnchorStyleInput {
+    readonly position: FabPosition;
+    readonly bottomInset: number;
+    readonly horizontalInset: number;
+    readonly zIndex: number;
+}
+export interface FabAnchorStyle {
+    readonly position: "absolute" | "relative";
+    readonly bottom?: number;
+    readonly left?: number;
+    readonly right?: number;
+    readonly alignItems?: "center" | "flex-start" | "flex-end";
+    readonly zIndex?: number;
+}
+/**
+ * The wrapper Fab/FabGroup render around their own control. `bottom-center` spans the full width
+ * (`left: 0, right: 0`) and centers via `alignItems` rather than a measured `translateX` — the same
+ * idiom `Toast.variants.ts`'s `toastOverlayStructure` already uses for its own centered card, which
+ * works regardless of the (possibly caller-length-driven) rendered width of an extended Fab.
+ * `bottom-right`/`bottom-left` edge-anchor directly; their `alignItems` also right/left-aligns
+ * FabGroup's mini-action rows (which vary in width) flush against the trigger's own edge. `static`
+ * renders no absolute positioning at all — the caller places it exactly like any other in-flow
+ * element, and gets no `zIndex` either (nothing to float above).
+ */
+export declare function resolveFabAnchorStyle(input: FabAnchorStyleInput): FabAnchorStyle;
+/** Whether a FabGroup action row reads label-then-icon or icon-then-label. The label always renders
+ *  toward screen CENTER, away from the edge the group is anchored to, so it can never clip off-screen
+ *  on a narrow device — `bottom-right`/`bottom-center`/`static` all read label-then-icon (nothing to
+ *  clip on the left); only `bottom-left` flips. */
+export declare function resolveFabGroupActionDirection(position: FabPosition): "row" | "row-reverse";
+/** The mini-action stack's own cross-axis alignment — matches `resolveFabAnchorStyle`'s edge for the
+ *  floating positions; `static` defaults to the same trailing edge as `bottom-right` (an arbitrary
+ *  but documented default — see MODULE.md "Design decisions"), since a `static` group's actions have
+ *  no anchor edge of their own to read. */
+export declare function resolveFabGroupStackAlign(position: FabPosition): "center" | "flex-start" | "flex-end";
+/** The speed-dial trigger's accessible name: the caller's own override, else "Open"/"Close actions
+ *  menu" swapping with `expanded` — the same fixed-default-with-override idiom Toast's close button
+ *  uses (`accessibilityLabel="Dismiss notification"`), reflecting the disclosure action itself since
+ *  the trigger has no visible label of its own to fall back to. */
+export declare function resolveFabGroupTriggerAccessibilityLabel(expanded: boolean, override: string | undefined): string;
+/**
+ * The slice of the speed-dial's single `progress` value one action row reveals over. Staggering by
+ * interpolation window rather than per-row animations costs no extra timers or Animated values, and
+ * reverses correctly on close. `staggered` is false whenever the device tier can't afford decorative
+ * motion, which collapses every row onto the same [0, 1] window.
+ */
+export declare function resolveFabGroupActionWindow(index: number, count: number, staggered: boolean): readonly [number, number];
+/** The focus ring sits a small gap OUTSIDE the control, on the canvas, because `border.focus` is the
+ *  role token proven ≥ 3:1 against the canvas (WCAG 2.4.11) — drawn over a solid fill it could fail. */
+export declare const FAB_FOCUS_RING_WIDTH = 2;
+export declare const FAB_FOCUS_RING_GAP = 2;
+export interface FabFocusRingStyle {
+    readonly position: "absolute";
+    readonly top: number;
+    readonly left: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly borderWidth: number;
+    readonly borderColor: string;
+    readonly borderRadius: number;
+}
+/** The offset ring `Fab` and `FabGroup`'s trigger both draw on focus — one definition, since the two
+ *  are the same circular silhouette. Kept a pure function of the two role/scale values it needs, so
+ *  the ring geometry is unit-testable without rendering React Native. */
+export declare function resolveFabFocusRingStyle(borderColor: string, borderRadius: number): FabFocusRingStyle;
+/** The dismiss scrim behind an expanded FabGroup — a design constant, not a role token: decorative,
+ *  same status `BACKDROP_SCRIM` (Menu/Select) and `DRAWER_BACKDROP` already have. */
+export declare const FAB_GROUP_SCRIM = "#00000080";
+/** Structural circle — the icon-only shape. Colour (fill) is tone-driven, applied inline over this. */
+export declare const fabCircleStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        md: {
+            width: 48;
+            height: 48;
+        };
+        lg: {
+            width: 56;
+            height: 56;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** Structural pill — the extended (icon + label) shape. Width hugs its content. */
+export declare const fabExtendedStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        md: {
+            height: 48;
+            paddingHorizontal: 16;
+        };
+        lg: {
+            height: 56;
+            paddingHorizontal: 20;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** The column of mini-action rows above the trigger. `align` mirrors `resolveFabGroupStackAlign` so
+ *  rows size to their own natural width (never stretched to the widest row) and align flush to the
+ *  correct edge — see MODULE.md "Design decisions" for the flexbox reasoning. */
+export declare const fabGroupActionsStackStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    align: {
+        "flex-end": {
+            alignItems: "flex-end";
+        };
+        "flex-start": {
+            alignItems: "flex-start";
+        };
+        center: {
+            alignItems: "center";
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** One FabGroup mini-action row: label chip + icon circle, laid out by `resolveFabGroupActionDirection`. */
+export declare const fabGroupActionRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The mini action's own circular icon backdrop. */
+export declare const fabGroupActionCircleStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The mini action's label chip — a small elevated surface, never the action's own tone fill: labels
+ *  are read against one constant neutral surface regardless of the action's tone, the same
+ *  "selection/emphasis isn't conveyed by a background swap" reasoning `Select`'s row fill documents. */
+export declare const fabGroupActionLabelStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=Fab.variants.d.ts.map

package/lib/typescript/modules/fab/FabGroup.d.ts

@@ -0,0 +1,66 @@
+/**
+ * FabGroup — a speed-dial: a Fab-shaped trigger that expands into a vertical stack of labeled mini
+ * actions above itself, behind a dismiss scrim. Deliberately NOT React Native's own `<Modal>` (unlike
+ * Menu/Select/Drawer) — a speed dial must stay visually anchored exactly where its own trigger sits
+ * on screen, and RN's `<Modal>` can only present a new, unrelated native surface. The scrim and the
+ * trigger+actions anchor are declared as SIBLINGS at this component's own root (no wrapping node of
+ * its own), so both resolve their `position: "absolute"` against the SAME nearest positioned ancestor
+ * — ordinarily the screen's own root container — the scrim covering it edge-to-edge while the anchor
+ * still hugs its own corner/edge. Declaring the scrim first and the anchor second puts the anchor
+ * visibly on top with no `zIndex` needed between the two, the same source-order idiom `Menu.tsx`'s
+ * own backdrop-then-sheet pair already relies on.
+ *
+ * Not being a `<Modal>` costs the one thing a Modal gives for free, though: RN's `<Modal>` presents
+ * its own native surface, so what it covers leaves the accessibility tree by construction. Nothing
+ * does that here, so the anchor declares `accessibilityViewIsModal` (+ `onAccessibilityEscape`) for
+ * itself while the scrim is mounted — otherwise the screen the scrim covers stays swipeable.
+ *
+ * The expand/collapse lifecycle mirrors `Drawer.tsx`'s exactly: `mounted` stays true through the exit
+ * animation (driven by a `useEffect` reacting to the resolved `expanded` value, not to who changed
+ * it) so the fade/slide can actually play before the tree unmounts, using the same plain-`setTimeout`
+ * determinism fix `Drawer`'s own top comment explains (an `Animated.timing` completion callback rides
+ * `requestAnimationFrame`, which doesn't resolve on a predictable jest-fake-timer tick). Driving the
+ * animation from an effect on `expanded` — rather than only inside the trigger's own press handler —
+ * is what makes a CONTROLLED caller flipping `open` externally (not via this trigger) animate too.
+ *
+ * Uncontrolled by default (`open`/`onOpenChange` both omitted → internal state); controlled the
+ * instant a caller passes `open`, the conventional React controlled/uncontrolled split.
+ */
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { FabPosition, FabSize, FabTone } from "./Fab.variants";
+export interface FabGroupAction {
+    readonly icon: IconName;
+    readonly label: string;
+    readonly onPress: () => void;
+    readonly tone?: FabTone;
+}
+export interface FabGroupProps {
+    actions: FabGroupAction[];
+    /** Trigger glyph. Rotates 45° open↔closed (a "+" reads as a close "×"); suppressed under reduced
+     *  motion via the same `progress`-driven duration as the rest of the expand/collapse. */
+    icon?: IconName;
+    /** Controlled the instant this is passed; omit both this and `onOpenChange` for internal state. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    tone?: FabTone;
+    size?: FabSize;
+    position?: FabPosition;
+    disabled?: boolean;
+    /** Overrides the trigger's accessible name whole. Defaults to "Open actions menu" / "Close actions
+     *  menu", swapping with the expanded state. */
+    accessibilityLabel?: string;
+    offset?: {
+        readonly bottom?: number;
+        readonly horizontal?: number;
+    };
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    /** Seeds `${testID}-anchor`, `${testID}-trigger`, `${testID}-trigger-focus-ring`,
+     *  `${testID}-scrim`, `${testID}-action-${index}`. */
+    testID?: string;
+}
+declare function FabGroupImpl({ actions, icon, open, onOpenChange, tone, size, position, disabled, accessibilityLabel, offset, style, testID, }: FabGroupProps): import("react").JSX.Element;
+export declare const FabGroup: import("react").MemoExoticComponent<typeof FabGroupImpl>;
+export {};
+//# sourceMappingURL=FabGroup.d.ts.map

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

@@ -0,0 +1,12 @@
+/**
+ * Public surface of `pixelize-native-library/fab`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures a Fab/FabGroup through
+ * their props, never by importing internals.
+ */
+export { Fab } from "./Fab";
+export type { FabProps } from "./Fab";
+export { FabGroup } from "./FabGroup";
+export type { FabGroupProps, FabGroupAction } from "./FabGroup";
+export type { FabPosition, FabSize, FabTone } from "./Fab.variants";
+export type { IconName } from "../../core/icon";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/file-grid/FileGrid.d.ts

@@ -0,0 +1,26 @@
+/**
+ * FileGrid — thumbnail grid for attachments or folders. Icon + label cells in 2–4 columns.
+ *
+ * Items are chunked into fixed-height rows and rendered through `core/list`'s `VirtualList`, so a
+ * folder with thousands of files mounts a window of rows rather than every cell.
+ */
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { FileGridColumns } from "./FileGrid.variants";
+export interface FileGridItem {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: IconName;
+    /** What the glyph means ("Folder", "PDF") — the icon's text equivalent, WCAG 1.3.1. */
+    readonly typeLabel?: string;
+}
+export interface FileGridProps {
+    items: readonly FileGridItem[];
+    columns?: FileGridColumns;
+    onItemPress?: (id: string) => void;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const FileGrid: import("react").NamedExoticComponent<FileGridProps>;
+//# sourceMappingURL=FileGrid.d.ts.map

package/lib/typescript/modules/file-grid/FileGrid.variants.d.ts

@@ -0,0 +1,26 @@
+import type { Theme } from "../../theme/hooks";
+export type FileGridColumns = 2 | 3 | 4;
+/**
+ * A cell's accessible name. The glyph is the ONLY thing that says whether a cell is a folder, an
+ * image or a document, and a glyph has no text equivalent (WCAG 1.3.1) — `typeLabel` is that
+ * equivalent. It has to come from the consumer: an `IconName` is a drawing, not a file type.
+ */
+export declare function resolveFileGridItemLabel(label: string, typeLabel: string | undefined): string;
+export declare const FILE_GRID_CELL_MIN_HEIGHT = 88;
+/** Fixed row height is what lets `VirtualList` derive `getItemLayout` for the grid. */
+export declare function fileGridRowHeight(gap: number): number;
+export declare const fileGridRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const fileGridCellStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    columns: {
+        2: {
+            width: "48%";
+        };
+        3: {
+            width: "31%";
+        };
+        4: {
+            width: "23%";
+        };
+    };
+}, import("react-native").ViewStyle>;
+//# sourceMappingURL=FileGrid.variants.d.ts.map

package/lib/typescript/modules/file-grid/index.d.ts

@@ -0,0 +1,4 @@
+export { FileGrid } from "./FileGrid";
+export type { FileGridItem, FileGridProps } from "./FileGrid";
+export type { FileGridColumns } from "./FileGrid.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/file-upload/FileUpload.d.ts

@@ -36,6 +36,9 @@ export interface FileUploadProps {
     allowedMimeTypes?: string[];
     /** Image-only — forwarded as `ImagePicker.launchImageLibraryAsync`'s `allowsEditing`. Ignored when `source` is `"document"`. Defaults to `false`, the default (permission-less) picker flow — see `FileUpload.variants.ts`'s `pickImageFile`. */
     allowsEditing?: boolean;
+    /** 0–100. Omitted means "no upload in flight" and renders no track at all — this module still owns
+     *  no upload logic, it only DISPLAYS a number the consumer drives from its own transfer. */
+    progress?: number;
     /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
     style?: LayoutStyle;
     testID?: string;

package/lib/typescript/modules/file-upload/FileUpload.variants.d.ts

@@ -17,9 +17,8 @@
  * Free of React, so this file (and `FileUpload.test.ts`) never needs `@testing-library/react-native`
  * — only `react-native`'s `StyleSheet` is mocked to identity, same as every sibling's pure test.
  */
-import * as DocumentPicker from "expo-document-picker";
-import * as ImagePicker from "expo-image-picker";
-import type { Theme } from "../../theme";
+import type { DocumentPickerModule, ImagePickerModule } from "../../core/media";
+import type { Theme } from "../../theme/hooks";
 export type FileUploadSource = "image" | "document";
 export type FileUploadSize = "sm" | "md" | "lg";
 export interface FileUploadResult {
@@ -45,9 +44,9 @@ export declare function fileNameFromUri(uri: string): string;
  * FileUpload.tsx`) is the one that decides what a `null` MEANS (cancel → leave `value` alone,
  * reject → clear it) by checking `result.canceled` itself; this function only normalizes the shape.
  */
-export declare function resolveImagePickResult(result: ImagePicker.ImagePickerResult): FileUploadResult | null;
+export declare function resolveImagePickResult(result: Awaited<ReturnType<ImagePickerModule['launchImageLibraryAsync']>>): FileUploadResult | null;
 /** Maps `DocumentPicker.getDocumentAsync`'s result onto the public shape — same `canceled`/empty-array handling as `resolveImagePickResult`. `DocumentPickerAsset.name` is always present, so no filename fallback is needed. */
-export declare function resolveDocumentPickResult(result: DocumentPicker.DocumentPickerResult): FileUploadResult | null;
+export declare function resolveDocumentPickResult(result: Awaited<ReturnType<DocumentPickerModule['getDocumentAsync']>>): FileUploadResult | null;
 /**
  * Opens the OS media-library picker and returns the normalized result, or `null` on cancel.
  *
@@ -102,6 +101,24 @@ export declare function resolveFileUploadRemoveLabel(fileName: string): string;
  * key), instead of the result depending on ambient parent layout.
  */
 export declare const fileUploadContainerStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The progress track's accessible name — `accessibilityValue.now` carries the number itself. */
+export declare const FILE_UPLOAD_PROGRESS_LABEL = "Upload progress";
+/** 0–100 (any other input, including `NaN`, reads as 0) → the 0–1 `scaleX` factor of the fill. */
+export declare function resolveFileUploadProgressFraction(progress: number): number;
+/** Rounded 0–100 for `accessibilityValue.now`, which takes an integer. */
+export declare function resolveFileUploadProgressPercent(progress: number): number;
+/**
+ * The upload-progress track. `alignSelf: "stretch"` so it spans the container the trigger `Button`
+ * sizes — the root hugs its content (see `fileUploadContainerStructure`), so a track with no
+ * intrinsic width would otherwise render 0dp wide.
+ */
+export declare const fileUploadProgressTrackStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/**
+ * The fill. Laid out at the track's FULL width and shrunk with an animated `scaleX` — the only way
+ * a determinate fill can run on the native driver (`width` cannot; see `core/motion`'s config
+ * header). `transformOrigin` pins the growth to the left edge instead of the centre.
+ */
+export declare const fileUploadProgressFillStructure: import("../../core/style").VariantResolver<import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
 /**
  * The "selected file" row — a bordered chip below the trigger. `border.interactive`, NOT the
  * decorative `border.default`: `Card.variants.ts` documents `border.default` as measuring

package/lib/typescript/modules/filter-sheet/FilterSheet.variants.d.ts

@@ -14,7 +14,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";
 /** Same touch-target floor as every interactive control in this library (44dp — Apple HIG minimum,
  *  WCAG 2.5.5 AAA). */
 export declare const MIN_TOUCH_TARGET = 44;
@@ -59,10 +59,12 @@ export interface FilterChipAccessibilityProps {
 }
 /**
  * Derives `FilterChip`'s a11y surface once, purely. Removable → `accessibilityRole="button"` with a
- * label that folds in the remove affordance (`"${label}, remove filter"`) so a screen reader
- * announces what the press does — the same "one accessible node reports the whole meaning"
- * contract `Badge` documents for its own chip. Locked (no `onRemove`) → no role at all: the
- * component renders a plain `View`, not a `Pressable`, so there is nothing to press.
+ * label that folds in the remove affordance so a screen reader announces what the press does — the
+ * same "one accessible node reports the whole meaning" contract `Badge` documents for its own chip.
+ * That wording comes from `core/a11y/labels`, shared with `chip` and `file-upload`, because three
+ * different names for one X affordance on one screen is a WCAG 3.2.4 failure. Locked (no
+ * `onRemove`) → no role at all: the component renders a plain `View`, not a `Pressable`, so there
+ * is nothing to press.
  */
 export declare function resolveFilterChipAccessibility(input: FilterChipAccessibilityInput): FilterChipAccessibilityProps;
 /** The one-tap quick-shortcut pill rendered above a dimension's Accordion section (e.g. a "Me"
@@ -83,6 +85,29 @@ export interface QuickChipColors {
  * neutral outlined pill on the sheet's own surface.
  */
 export declare function resolveQuickChipColors(colors: RoleColors, selected: boolean): QuickChipColors;
+export interface QuickChipAccessibilityInput {
+    readonly label: string;
+    readonly selected: boolean;
+}
+export interface QuickChipAccessibilityProps {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string;
+    /** The WEB half. `aria-pressed` is the correct ARIA for a toggle button and has no React Native
+     *  equivalent, so the native half rides `accessibilityState` below. */
+    readonly "aria-pressed": boolean;
+    /** The NATIVE half — discarded by react-native-web, so it never reaches the DOM as an
+     *  `aria-selected` that would be invalid on `role="button"`. */
+    readonly accessibilityState: {
+        readonly selected: boolean;
+    };
+}
+/**
+ * Derives the quick chip's a11y surface purely. The pair is the one `docs/PLATFORM-A11Y-PROPS.md`
+ * prescribes for a toggle button, the one case where the two vocabularies genuinely diverge: each
+ * prop is inert on the platform it isn't aimed at, so neither is belt-and-braces. Unlike `Button`'s
+ * optional `selected`, a quick chip is ALWAYS a toggle, so both halves are always emitted.
+ */
+export declare function resolveQuickChipAccessibility(input: QuickChipAccessibilityInput): QuickChipAccessibilityProps;
 /** The header row hosting the sheet's title. */
 export declare const filterSheetHeaderStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
 /** One dimension's quick-chip row — wraps onto multiple lines rather than scrolling horizontally,