pixelize-native-library 1.0.6 → 1.2.0

package/lib/typescript/modules/date-picker/PickerField.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PickerField — the pressable field box shared by `DatePicker` and `DateRangePicker`, styled
+ * byte-for-byte like `Input`'s `md` box (see `dateFieldStructure`'s doc comment) so either sits
+ * beside a real `Input` in a form with no visual seam. NOT part of this module's public surface —
+ * both pickers differ only in what value they format and how "clear" resets it; the field's markup,
+ * a11y wiring and focus/error treatment are otherwise identical.
+ */
+import type { IconName } from "../../core/icon";
+export interface PickerFieldProps {
+    label?: string;
+    placeholder: string;
+    /** The formatted value, or `""` when empty — also what gates the clear button. */
+    displayText: string;
+    error?: string;
+    disabled: boolean;
+    /** Whether the picker sheet is open — folded into the field's focus ring + `expanded` state. */
+    open: boolean;
+    clearable: boolean;
+    clearAccessibilityLabel: string;
+    trailingIcon: IconName;
+    onPress: () => void;
+    onClear: () => void;
+    testID?: string;
+}
+export declare const PickerField: import("react").NamedExoticComponent<PickerFieldProps>;
+//# sourceMappingURL=PickerField.d.ts.map

package/lib/typescript/modules/date-picker/PickerShell.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PickerShell — the modal chrome (backdrop, overlay, sheet, Cancel/Confirm footer) shared by
+ * `DatePicker` and `DateRangePicker`. NOT part of this module's public surface (not re-exported
+ * from `index.ts`): the two pickers differ only in what they render as `children` (Calendar /
+ * TimePicker / a `Tabs` strip) — the sheet's presentation, dismissal and confirm/cancel wiring are
+ * otherwise identical, so this is a plain internal composition helper, the same "compose, don't
+ * reimplement" choice `alert-dialog` makes for its Modal + Button pairing.
+ *
+ * Renders in React Native's OWN `Modal`, imported directly from `"react-native"` — same reasoning
+ * as `Select`/`Menu`: this module owns its sheet's markup outright, never the library's own `Modal`
+ * COMPONENT (a persistent app dialog with a title/children contract is a different shape than a
+ * confirm/cancel picker sheet). The one deliberate exception is the web portal mechanism
+ * (`ModalPortalContext`/`renderWebPortal`), read for the same reason `Select.tsx`/`Menu.tsx` read
+ * it — see `../modal/ModalPortalContext.ts`.
+ */
+import type { ReactNode } from "react";
+export interface PickerShellProps {
+    open: boolean;
+    /** Names the sheet for a screen reader landing on it — it has no visible title to borrow. */
+    accessibilityLabel: string;
+    onCancel: () => void;
+    onConfirm: () => void;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    children: ReactNode;
+    testID?: string;
+}
+export declare const PickerShell: import("react").NamedExoticComponent<PickerShellProps>;
+//# sourceMappingURL=PickerShell.d.ts.map

package/lib/typescript/modules/date-picker/TimePicker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TimePicker — hour / minute (/ AM-PM) selection as independent scrollable columns, never an analog
+ * clock face. Hour and minute are virtualized `FlatList`s (Select's precedent — a minute column can
+ * hold up to 60 rows); the two-item AM/PM column is a plain view, matching Tabs' own choice not to
+ * virtualize a handful of items.
+ *
+ * All arithmetic (12/24-hour conversion, AM/PM flip, option lists) lives in `DatePicker.variants.ts`.
+ */
+import type { LayoutStyle } from "../../core/style";
+export interface TimePickerProps {
+    value?: Date | null;
+    onChange: (date: Date) => void;
+    use24Hour?: boolean;
+    minuteStep?: number;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const TimePicker: import("react").NamedExoticComponent<TimePickerProps>;
+//# sourceMappingURL=TimePicker.d.ts.map

package/lib/typescript/modules/date-picker/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Public surface of `pixelize-native-library/date-picker`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. `PickerField`/`PickerShell` are internal composition helpers (see
+ * their own doc comments) and are deliberately not re-exported — a consumer builds a date/time UI
+ * through `Calendar`, `TimePicker`, `DatePicker`, or `DateRangePicker`, never their internals.
+ */
+export { Calendar } from "./Calendar";
+export type { CalendarProps } from "./Calendar";
+export { TimePicker } from "./TimePicker";
+export type { TimePickerProps } from "./TimePicker";
+export { DatePicker } from "./DatePicker";
+export type { DatePickerProps } from "./DatePicker";
+export { DateRangePicker } from "./DateRangePicker";
+export type { DateRangePickerProps } from "./DateRangePicker";
+export type { CalendarSelectionMode, DatePickerMode, DateRange, FirstDayOfWeek, Meridiem, } from "./DatePicker.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/divider/Divider.variants.d.ts

@@ -8,8 +8,8 @@
  * Free of React, so the colour-resolution test imports this directly (mocking only `react-native`'s
  * `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
-import type { RoleColors } from "../../theme";
-import type { Theme } from "../../theme";
+import type { RoleColors } from "../../theme/hooks";
+import type { Theme } from "../../theme/hooks";
 export type DividerOrientation = "horizontal" | "vertical";
 /**
  * Maps the divider onto the theme's role colours. `colors.border.default` — the decorative rung,

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

@@ -10,7 +10,8 @@
  * transition for the whole native surface and can't keep a custom-Animated backdrop opacity in
  * lockstep with a custom panel slide. `animationType` is therefore always `"none"` here; this module
  * owns the whole transition, so it can collapse to an instant snap under reduced motion (WCAG 2.3.3)
- * without ever showing a frozen half-animated frame.
+ * without ever showing a frozen half-animated frame. Every duration and easing comes from the global
+ * motion system (`core/motion`) — `slow`/`decelerate` entering, `normal`/`accelerate` leaving.
  *
  * Because RN's `<Modal>` only hides its children once native dismissal completes (or the component
  * unmounts) — the same fact Modal.tsx's own top comment documents — the sheet stays internally

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