pixelize-native-library 1.0.7 → 1.2.1

package/lib/typescript/core/style/sx.d.ts

@@ -0,0 +1,86 @@
+import type { ViewStyle } from "react-native";
+import type { SpaceToken } from "../../theme/tokens/primitives/space";
+/**
+ * Spacing steps sx() accepts for padding/margin/gap — a deliberately short list (0–32dp) covering
+ * real layout spacing, not the full 17-step `SpaceToken` scale. Bigger jumps (36dp+) are almost
+ * always component *sizing* (an avatar, an icon touch target), not spacing between things — that
+ * belongs to `SizeToken`, not here. `Extract` ties this to `SpaceToken` so it can never list a
+ * step the shared scale doesn't actually have.
+ */
+export type SxSpaceToken = Extract<SpaceToken, 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8>;
+/**
+ * Spacing + flex shorthand for building a plain `ViewStyle` inline — scoped deliberately to the
+ * two things app screens hand-write over and over (padding/margin/gap, flex layout), not a
+ * general CSS-in-JS escape hatch. No color, no typography, no borders — those already have a
+ * typed home (`useThemeColors()`, variant resolvers).
+ */
+export interface SxProps {
+    /** Padding on all sides. */
+    p?: SxSpaceToken;
+    /** Padding left and right. */
+    px?: SxSpaceToken;
+    /** Padding top and bottom. */
+    py?: SxSpaceToken;
+    /** Padding top only. */
+    pt?: SxSpaceToken;
+    /** Padding right only. */
+    pr?: SxSpaceToken;
+    /** Padding bottom only. */
+    pb?: SxSpaceToken;
+    /** Padding left only. */
+    pl?: SxSpaceToken;
+    /** Margin on all sides. */
+    m?: SxSpaceToken;
+    /** Margin left and right. */
+    mx?: SxSpaceToken;
+    /** Margin top and bottom. */
+    my?: SxSpaceToken;
+    /** Margin top only. */
+    mt?: SxSpaceToken;
+    /** Margin right only. */
+    mr?: SxSpaceToken;
+    /** Margin bottom only. */
+    mb?: SxSpaceToken;
+    /** Margin left only. */
+    ml?: SxSpaceToken;
+    /** Space between every child, both directions. */
+    gap?: SxSpaceToken;
+    /** Vertical space between rows of children (only differs from `gap` when wrapping). */
+    rowGap?: SxSpaceToken;
+    /** Horizontal space between columns of children (only differs from `gap` when wrapping). */
+    columnGap?: SxSpaceToken;
+    /** Lay children out left-to-right instead of React Native's default top-to-bottom. */
+    row?: boolean;
+    /** Reverse child order — right-to-left with `row`, bottom-to-top otherwise. */
+    reverse?: boolean;
+    /** Let children wrap onto a new line/column instead of overflowing or being squeezed. */
+    wrap?: boolean;
+    /** How children line up on the cross axis, e.g. `"center"` to vertically center a row. */
+    align?: ViewStyle["alignItems"];
+    /** How children are spaced on the main axis, e.g. `"space-between"`. */
+    justify?: ViewStyle["justifyContent"];
+    /** How wrapped lines are spaced when `wrap` is set and there's extra room left over. */
+    alignContent?: ViewStyle["alignContent"];
+    /** Shorthand for `align: "center"` + `justify: "center"` — centers children both ways. */
+    center?: boolean;
+    /** How much of the remaining space this element should take up. */
+    flex?: number;
+    /** Whether/how much this element grows to fill extra space. */
+    grow?: number;
+    /** Whether/how much this element shrinks when space is tight. */
+    shrink?: number;
+    /** This element's starting size before flex grow/shrink apply. */
+    basis?: ViewStyle["flexBasis"];
+    /** Overrides `align` for just this one element. */
+    self?: ViewStyle["alignSelf"];
+}
+/**
+ * Builds a plain `ViewStyle` object — pass it straight to any component's `style` prop.
+ *
+ * Builds a fresh object per call, same as an inline `style={{...}}` (never cached like
+ * `StyleSheet.create` or the themed variant resolver above). Fine for ordinary screen code that
+ * re-renders on user interaction; hoist a `StyleSheet.create` instead inside a list item renderer
+ * or anything re-rendering many times a second, where per-render allocation actually adds up.
+ */
+export declare function sx(props: SxProps): ViewStyle;
+//# sourceMappingURL=sx.d.ts.map

package/lib/typescript/core/style/useThemedStyles.d.ts

@@ -0,0 +1,5 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { Theme } from '../../theme/provider/types';
+/** Memoizes themed style arrays at the component boundary. */
+export declare function useThemedStyles<T extends StyleProp<ViewStyle>>(factory: (theme: Theme) => T, theme: Theme, deps?: readonly unknown[]): T;
+//# sourceMappingURL=useThemedStyles.d.ts.map

package/lib/typescript/index.d.ts

@@ -5,7 +5,141 @@
  * only via their subpath — so a lazy barrel import cannot drag a chart engine into an app's
  * bundle, even with every optimizer turned off.
  *
- * Generated re-exports land below; do not add heavy modules by hand.
+ * GENERATED by scripts/gen-index.mjs — do not hand-edit below this comment; run `npm run gen` to
+ * regenerate (CI runs `npm run gen:check` as the drift gate). Adding a light module here is
+ * automatic the next time `npm run gen` runs against its src/modules/<name>/index.ts; nothing here
+ * is ever added "by hand".
  */
-export {};
+export { Accordion } from "./modules/accordion";
+export type { AccordionItem, AccordionProps, AccordionSize } from "./modules/accordion";
+export { AlertDialog } from "./modules/alert-dialog";
+export type { AlertDialogProps, AlertDialogTone } from "./modules/alert-dialog";
+export { AppBar } from "./modules/app-bar";
+export type { AppBarProps, AppBarAction, IconName } from "./modules/app-bar";
+export { Avatar } from "./modules/avatar";
+export type { AvatarProps, AvatarShape, AvatarSize } from "./modules/avatar";
+export { AvatarGroup } from "./modules/avatar-group";
+export type { AvatarGroupProps, AvatarGroupItem } from "./modules/avatar-group";
+export { Badge } from "./modules/badge";
+export type { BadgeProps, BadgeTone, BadgeSize } from "./modules/badge";
+export { Banner } from "./modules/banner";
+export type { BannerProps, BannerAction, BannerTone, BannerVariant } from "./modules/banner";
+export { BottomNav } from "./modules/bottom-nav";
+export type { BottomNavProps, BottomNavActiveState, BottomNavDestination, BottomNavOverflowSection, BottomNavEditConfig, MenuItem } from "./modules/bottom-nav";
+export { BottomSheet } from "./modules/bottom-sheet";
+export type { BottomSheetProps } from "./modules/bottom-sheet";
+export { Button } from "./modules/button";
+export type { ButtonProps, ButtonVariant, ButtonSize, ButtonTone, IconPosition } from "./modules/button";
+export { ButtonGroup } from "./modules/button-group";
+export type { ButtonGroupProps, ButtonGroupOption, ButtonGroupSize } from "./modules/button-group";
+export { Card } from "./modules/card";
+export type { CardProps, CardVariant } from "./modules/card";
+export { Checkbox } from "./modules/checkbox";
+export type { CheckboxProps, CheckboxSize } from "./modules/checkbox";
+export { Chip, ChipGroup } from "./modules/chip";
+export type { ChipProps, ChipGroupProps, ChipGroupGap, ChipSize, ChipTone, ChipVariant, CustomToneColors } from "./modules/chip";
+export { Combobox } from "./modules/combobox";
+export type { ComboboxProps, ComboboxSingleProps, ComboboxMultipleProps, ComboboxOption } from "./modules/combobox";
+export { Composer } from "./modules/composer";
+export type { ComposerProps } from "./modules/composer";
+export { CopyButton } from "./modules/copy-button";
+export type { CopyButtonProps, CopyButtonSize, CopyButtonVariant } from "./modules/copy-button";
+export { Divider } from "./modules/divider";
+export type { DividerProps, DividerOrientation } from "./modules/divider";
+export { Drawer } from "./modules/drawer";
+export type { DrawerProps } from "./modules/drawer";
+export { EmptyState } from "./modules/empty-state";
+export type { EmptyStateProps, EmptyStateAction } from "./modules/empty-state";
+export { Fab, FabGroup } from "./modules/fab";
+export type { FabProps, FabGroupProps, FabGroupAction, FabPosition, FabSize, FabTone } from "./modules/fab";
+export { FileGrid } from "./modules/file-grid";
+export type { FileGridItem, FileGridProps, FileGridColumns } from "./modules/file-grid";
+export { FileUpload } from "./modules/file-upload";
+export type { FileUploadProps, FileUploadResult, FileUploadSize, FileUploadSource } from "./modules/file-upload";
+export { FilterSheet, FilterChip, countActiveFilters } from "./modules/filter-sheet";
+export type { FilterSheetProps, FilterDimension, FilterDimensionKind, FilterOption, FilterValues, FilterChipProps } from "./modules/filter-sheet";
+export { FolderRow } from "./modules/folder-row";
+export type { FolderRowProps } from "./modules/folder-row";
+export { FormField } from "./modules/form-field";
+export type { FormFieldProps, FormFieldStatus, FormFieldControlProps } from "./modules/form-field";
+export { Input } from "./modules/input";
+export type { InputProps, InputSize, InputStatus } from "./modules/input";
+export { LimitReachedModal } from "./modules/limit-reached-modal";
+export type { LimitReachedModalProps, LimitKind } from "./modules/limit-reached-modal";
+export { ListItem } from "./modules/list-item";
+export type { ListItemProps } from "./modules/list-item";
+export { Markdown, parseMarkdown } from "./modules/markdown";
+export type { MarkdownProps, MarkdownBlockNode, MarkdownInlineNode } from "./modules/markdown";
+export { Menu } from "./modules/menu";
+export type { MenuProps, MenuTriggerProps, MenuItemTone } from "./modules/menu";
+export { MessageBubble } from "./modules/message-bubble";
+export type { MessageBubbleProps, MessageBubbleVariant } from "./modules/message-bubble";
+export { Modal, ModalPortalProvider } from "./modules/modal";
+export type { ModalProps, ModalSize, ModalPortalProviderProps } from "./modules/modal";
+export { MoreItems } from "./modules/more-items";
+export type { MoreItemsProps, MoreItemsEntry } from "./modules/more-items";
+export { MultiSelect } from "./modules/multi-select";
+export type { MultiSelectProps, MultiSelectOption, MultiSelectSize } from "./modules/multi-select";
+export { NumberInput } from "./modules/number-input";
+export type { NumberInputProps, NumberInputSize, NumberInputStatus } from "./modules/number-input";
+export { OrgSwitcher } from "./modules/org-switcher";
+export type { OrgSwitcherProps, OrgSwitcherOption, OrgSwitcherSize } from "./modules/org-switcher";
+export { Pagination, buildPageRange, clampPage } from "./modules/pagination";
+export type { PaginationProps, PageItem, PaginationSize, PaginationVariant } from "./modules/pagination";
+export { PinInput } from "./modules/pin-input";
+export type { PinInputProps, PinInputKeyboardType, PinInputSize, PinInputStatus } from "./modules/pin-input";
+export { ProgressBar } from "./modules/progress-bar";
+export type { ProgressBarProps, ProgressBarSize, ProgressBarTone } from "./modules/progress-bar";
+export { RadioGroup } from "./modules/radio-group";
+export type { RadioGroupProps, RadioGroupOption, RadioGroupSize } from "./modules/radio-group";
+export { Reorder } from "./modules/reorder";
+export type { ReorderProps, ReorderItem } from "./modules/reorder";
+export { Screen } from "./modules/screen";
+export type { ScreenProps, ScreenEdge, ScreenState } from "./modules/screen";
+export { SearchBar } from "./modules/search-bar";
+export type { SearchBarProps, SearchBarSize } from "./modules/search-bar";
+export { Section } from "./modules/section";
+export type { SectionProps } from "./modules/section";
+export { SectionList } from "./modules/section-list";
+export type { SectionListProps, SectionListSection } from "./modules/section-list";
+export { SegmentedControl } from "./modules/segmented-control";
+export type { SegmentedControlProps, SegmentedControlOption, SegmentedControlSize } from "./modules/segmented-control";
+export { Select } from "./modules/select";
+export type { SelectProps, SelectOption, SelectOptionCustomColors, SelectOptionTone, SelectSize } from "./modules/select";
+export { Skeleton } from "./modules/skeleton";
+export type { SkeletonProps, SkeletonShape } from "./modules/skeleton";
+export { Slider } from "./modules/slider";
+export type { SliderProps, SliderSize } from "./modules/slider";
+export { Spinner } from "./modules/spinner";
+export type { SpinnerProps, SpinnerSize, SpinnerTone } from "./modules/spinner";
+export { StageProgress } from "./modules/stage-progress";
+export type { StageProgressProps, StageProgressStage, StageProgressVariant, StageState } from "./modules/stage-progress";
+export { StatTile } from "./modules/stat-tile";
+export type { StatTileProps, StatTileTone } from "./modules/stat-tile";
+export { LoadingState, ErrorState } from "./modules/state-block";
+export type { LoadingStateProps, ErrorStateProps, ErrorStateAction } from "./modules/state-block";
+export { Stepper } from "./modules/stepper";
+export type { StepperProps, StepperStep } from "./modules/stepper";
+export { Box, Surface } from "./modules/surface";
+export type { SurfaceProps, BgRole, BorderRole, RadiusToken, SpaceToken } from "./modules/surface";
+export { SwipeableRow } from "./modules/swipeable-row";
+export type { SwipeableRowAction, SwipeableRowProps, SwipeableActionTone } from "./modules/swipeable-row";
+export { Switch } from "./modules/switch";
+export type { SwitchProps } from "./modules/switch";
+export { Tabs } from "./modules/tabs";
+export type { TabsProps, TabItem, TabsSize } from "./modules/tabs";
+export { Text, Heading } from "./modules/text";
+export type { TextProps, HeadingProps, TextVariant, HeadingVariant } from "./modules/text";
+export { Textarea } from "./modules/textarea";
+export type { TextareaProps, TextareaSize, TextareaStatus } from "./modules/textarea";
+export { Timeline } from "./modules/timeline";
+export type { TimelineProps, TimelineItem } from "./modules/timeline";
+export { ToastProvider, useToast } from "./modules/toast";
+export type { ToastContextValue, ToastOptions, ToastProviderProps, ToastDuration, ToastPosition, ToastTone } from "./modules/toast";
+export { Tooltip } from "./modules/tooltip";
+export type { TooltipProps, TooltipTriggerProps, TooltipPlacement } from "./modules/tooltip";
+export { TypingIndicator } from "./modules/typing-indicator";
+export type { TypingIndicatorProps, TypingIndicatorSize } from "./modules/typing-indicator";
+export { UnreadBadge } from "./modules/unread-badge";
+export type { UnreadBadgeProps, UnreadBadgeSize } from "./modules/unread-badge";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/accordion/Accordion.d.ts

@@ -1,50 +1,39 @@
 /**
  * Accordion — a stack of collapsible sections. `type="single"` (default) keeps at most one section
- * open at a time (opening one closes whichever else was open; pressing the open section's own
- * header closes it too — a single-select disclosure list, not a one-way reveal); `type="multiple"`
- * lets every section toggle independently.
+ * open at a time; `type="multiple"` lets every section toggle independently.
  *
- * Each header is a `Pressable` disclosure control (`accessibilityRole="button"`,
- * `accessibilityState={{ expanded }}`) with a "chevron-down" glyph that rotates 180° open, animated
- * with a single `Animated.Value` exactly like `Tabs`' indicator: under reduced motion (WCAG 2.3.3)
- * the value is snapped with `setValue` instead of tweened with `Animated.timing`, so a duration-0
- * `Animated.timing` can never sneak an intermediate frame through.
- *
- * Content is CONDITIONALLY RENDERED (mounted only while expanded), not height-animated. React
- * Native has no native height transition without a measure-then-animate hack (measure the content
- * once mounted, then tween a `height`/`Animated.Value` from 0 to the measured value) — that hack is
- * fragile (a wrong first measurement, a content resize, and the animation targets a stale height)
- * and untestable in this repo's jsdom-less test renderer, which never runs real layout. A conditional
- * mount is a real instant "snap" open/close, so it also satisfies the reduced-motion requirement for
- * free — there is no tween to gate for that case at all.
+ * Content is conditionally mounted while expanded. Prefer `renderContent` over eager `content` so
+ * collapsed sections never build heavy subtrees.
  */
 import type { ReactNode } from "react";
+import type { IconName } from "../../core/icon";
 import type { LayoutStyle } from "../../core/style";
 import type { AccordionSize } from "./Accordion.variants";
 export interface AccordionItem {
     readonly value: string;
     readonly title: string;
-    /** Ordinary composition, rendered directly under a `View` when expanded — same contract as
-     * `Card.children`: a consumer wraps its own raw text in `Text`, this component does not. */
-    readonly content: ReactNode;
+    readonly subtitle?: string;
+    readonly icon?: IconName;
+    readonly badge?: string;
+    readonly disabled?: boolean;
+    /** Eager content — use `renderContent` when sections are heavy. */
+    readonly content?: ReactNode;
+    readonly renderContent?: () => ReactNode;
 }
 interface AccordionBaseProps {
     items: AccordionItem[];
-    /** Blocks every header's toggle at once — there is no per-item `disabled`. */
+    /** Blocks every header that is not individually `disabled`. */
     disabled?: boolean;
     size?: AccordionSize;
-    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
     style?: LayoutStyle;
     testID?: string;
 }
-/** At most one section open at a time. The default shape — `type` may be omitted. */
 interface AccordionSingleProps extends AccordionBaseProps {
     type?: "single";
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
 }
-/** Every section toggles independently. */
 interface AccordionMultipleProps extends AccordionBaseProps {
     type: "multiple";
     value?: string[];

package/lib/typescript/modules/accordion/Accordion.variants.d.ts

@@ -11,7 +11,7 @@
  *    "expanded tracks open state / disabled blocks the toggle" contract is unit-testable without
  *    rendering React Native.
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 export type AccordionSize = "sm" | "md" | "lg";
 /** Same floor as Button/Tabs/Select — 44dp (WCAG 2.5.5 AAA / HIG). Duplicated, not imported: modules
  * stay isolated. */
@@ -55,7 +55,7 @@ export interface AccordionColors {
     readonly title: string;
     /** The chevron glyph — a non-text state indicator, not a label. */
     readonly icon: string;
-    /** The hairline between items — decorative, never the interactive/focus rungs. */
+    /** The StyleSheet.hairlineWidth between items — decorative, never the interactive/focus rungs. */
     readonly divider: string;
     /** A header's background while pressed. */
     readonly pressedHeaderBg: string;
@@ -74,10 +74,10 @@ export interface AccordionHeaderAccessibilityInput {
 }
 export interface AccordionHeaderAccessibilityProps {
     readonly accessibilityRole: "button";
-    readonly accessibilityState: {
-        readonly expanded: boolean;
-        readonly disabled: boolean;
-    };
+    /** 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-expanded": boolean;
+    readonly "aria-disabled": boolean;
     /** The `Pressable disabled` prop — blocks touches without relying on `onPress` gating alone. */
     readonly disabled: boolean;
 }
@@ -89,7 +89,7 @@ export interface AccordionHeaderAccessibilityProps {
  */
 export declare function resolveAccordionHeaderAccessibility(input: AccordionHeaderAccessibilityInput): AccordionHeaderAccessibilityProps;
 /**
- * One item's separator — a hairline on the bottom edge, theme-scaled border WIDTH. Colour
+ * One item's separator — a StyleSheet.hairlineWidth on the bottom edge, theme-scaled border WIDTH. Colour
  * (`divider`) is resolved separately and applied inline over this.
  */
 export declare const accordionItemStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;

package/lib/typescript/modules/alert-dialog/AlertDialog.variants.d.ts

@@ -11,7 +11,7 @@
  * Free of React and of any `Modal`/`Button` RENDER import — only `ButtonTone`'s TYPE is pulled in —
  * so this stays a pure resolver file, exactly like `Button.variants.ts` / `Modal.variants.ts`.
  */
-import type { Theme } from "../../theme";
+import type { Theme } from "../../theme/hooks";
 import type { ButtonTone } from "../button";
 export type AlertDialogTone = "default" | "danger";
 /**
@@ -26,4 +26,5 @@ export declare function resolveAlertDialogConfirmTone(tone: AlertDialogTone): Bu
  * each `Button`'s own tone-resolved fill, applied by Button itself.
  */
 export declare const alertDialogActionsStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare function alertDialogPanelDepth(theme: Theme): import("react-native").ViewStyle;
 //# sourceMappingURL=AlertDialog.variants.d.ts.map

package/lib/typescript/modules/app-bar/AppBar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AppBar — a themed top bar for screen headers: a required title, an optional subtitle, an optional
+ * back affordance, and optional leading/trailing icon actions. Every action is a library `Button`
+ * (icon-only, ghost) driven by a closed `IconName` — never a hand-rolled `Pressable` or a consumer
+ * `ReactNode` slot that would bypass the API contract.
+ *
+ * No `accessibilityRole` on the bar itself: like `Card`, this is a plain grouping container. The
+ * title carries `accessibilityRole="header"` at level 1 (WCAG 1.3.1 / 2.4.6 — it is the screen's
+ * heading, the one the rest of the screen's outline nests under, and
+ * rotor heading navigation is a primary way screen-reader users move around an app); the subtitle
+ * reads as its own `Text`, and each composed `Button` carries its own role/state.
+ *
+ * Its only motion is `useTitleCrossfade` below — opacity on the title box, nothing else. Elevation
+ * on scroll would need a public scroll-offset prop, which the API contract does not justify here.
+ */
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+export interface AppBarAction {
+    readonly icon: IconName;
+    readonly accessibilityLabel: string;
+    readonly onPress: () => void;
+}
+export interface AppBarProps {
+    title: string;
+    subtitle?: string;
+    /** Renders a ghost back button with `arrow-left` and an accessible name of "Back". */
+    onBack?: () => void;
+    /** Custom leading action when `onBack` is absent. */
+    leading?: AppBarAction;
+    /** One or more trailing icon actions. */
+    trailing?: AppBarAction | readonly AppBarAction[];
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const AppBar: import("react").NamedExoticComponent<AppBarProps>;
+//# sourceMappingURL=AppBar.d.ts.map

package/lib/typescript/modules/app-bar/AppBar.variants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AppBar's style + colour resolution — same split as `Button.variants` / `Badge.variants`:
+ *  - STRUCTURE (row layout, title box flex, side min-width for touch targets) lives in the themed
+ *    `appBarStructure` resolver, static per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveAppBarColors`, never a raw ramp
+ *    and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the WCAG + behaviour tests import this directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+import type { RoleColors, Theme } from "../../theme/hooks";
+/** Matches `Button`'s `MIN_TOUCH_TARGET` — each side slot reserves at least 44dp for icon actions. */
+export declare const APP_BAR_SIDE_MIN_WIDTH = 44;
+export interface AppBarColors {
+    readonly background: string;
+    readonly border: string;
+    readonly title: string;
+    readonly subtitle: string;
+}
+/**
+ * Maps AppBar onto the theme's role colours. No `tone`/`color` prop to widen — every colour this
+ * bar can show is one of these role lookups (same reasoning as `Divider`/`Card`).
+ */
+export declare function resolveAppBarColors(colors: RoleColors): AppBarColors;
+/**
+ * Structural styles only — the header row, title box, and side slots. No colours (resolved
+ * separately, applied inline over this), so these compile once per theme identity via the
+ * `WeakMap`-cached themed resolver and never rebuilds per render.
+ */
+export declare const appBarStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const appBarSideStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const appBarSideTrailingStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const appBarTitleBoxStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const appBarActionsRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=AppBar.variants.d.ts.map

package/lib/typescript/modules/app-bar/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of `pixelize-native-library/app-bar`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The style/colour resolvers stay internal — a consumer configures an AppBar
+ * through its props, never by importing its internals.
+ */
+export { AppBar } from "./AppBar";
+export type { AppBarProps, AppBarAction } from "./AppBar";
+export type { IconName } from "../../core/icon";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/avatar/Avatar.d.ts

@@ -1,20 +1,40 @@
 /**
- * Avatar — a circular identity glyph: a remote image, initials, or (with neither) a plain neutral
- * placeholder. No press handling, no loading spinner, no animation — the simplest module in the
+ * Avatar — an identity glyph: a remote image, initials, or (with neither) a plain placeholder,
+ * circular or rounded. No press handling, no loading spinner — one of the simplest modules in the
  * library, which is exactly why its accessibility default differs from every sibling: an avatar
  * usually sits beside a visible name, so `accessibilityLabel` is optional, not a required trap (see
  * `Avatar.variants.ts` → `resolveAvatarAccessibility`).
+ *
+ * The image is `expo-image`, not RN's `Image`, for one reason that matters on a recycled list: RN's
+ * `Image` keeps painting the old bitmap until the new URI resolves, so a FlashList row hands the
+ * next row the previous subject's face. `recyclingKey` blanks it on the spot.
+ *
+ * The image's fade-in is expo-image's own native `transition`, timed from the global motion system —
+ * deliberately not an `Animated.Value`. An avatar renders per list row, so it must add no JS-driven
+ * animation, no mount animation and no loop; the fade is load-triggered and runs entirely natively.
  */
 import type { LayoutStyle } from "../../core/style";
-import type { AvatarSize } from "./Avatar.variants";
+import type { AvatarShape, AvatarSize } from "./Avatar.variants";
 export interface AvatarProps {
     size?: AvatarSize;
+    shape?: AvatarShape;
     /** A remote image. Wins over `initials` when present. */
     source?: {
         uri: string;
     };
     /** Shown when there is no `source`. Longer strings are clipped to the first two characters. */
     initials?: string;
+    /**
+     * Tints the initials/placeholder with a stable colour hashed from this string (an org name, a
+     * user id — whatever identifies the subject). Absent → the neutral placeholder fill.
+     */
+    identity?: string;
+    /**
+     * Blanks the image the instant this changes, so a recycled list row can never show the PREVIOUS
+     * subject's photo while the new one loads. Defaults to `source.uri`, which is the right key
+     * whenever one avatar means one image.
+     */
+    recyclingKey?: string;
     /**
      * Optional, unlike `Button`'s icon-only `accessibilityLabel` — an avatar is usually adjacent to a
      * visible name, so it is not the sole carrier of identity the way an icon-only button's label is.

package/lib/typescript/modules/avatar/Avatar.variants.d.ts

@@ -15,8 +15,10 @@
  * Free of React and of any lucide import, so the WCAG + behaviour tests import it directly (mocking
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { PaletteProps, RoleColors, Theme } from "../../theme/hooks";
 export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+/** `circle` for a person, `rounded` for an organisation/product, `square` for tiles/thumbnails. */
+export type AvatarShape = "circle" | "rounded" | "square";
 export interface AvatarSizeSpec {
     /** Visual diameter, in dp. */
     readonly box: number;
@@ -64,6 +66,24 @@ export interface AvatarColors {
  * never an off-palette value an app invented (same reasoning as `resolveCheckboxColors`).
  */
 export declare function resolveAvatarColors(colors: RoleColors): AvatarColors;
+/** The ramp names an identity seed hashes onto — never the brand ramp, which would make every
+ *  identity look alike. Slot order mirrors web's `AVATAR_COLORS` so a given name lands on the same
+ *  hue on both platforms; `cyan` stands in for web's violet (this palette ships one purple ramp). */
+export declare const AVATAR_IDENTITY_RAMPS: readonly ["purple", "blue", "green", "orange", "red", "pink", "cyan", "teal"];
+export type AvatarIdentityRamp = (typeof AVATAR_IDENTITY_RAMPS)[number];
+/** Web's `avatarColor` hash, character for character, so both platforms agree on the slot. */
+export declare function avatarIdentityRamp(seed: string): AvatarIdentityRamp;
+export interface AvatarIdentityColors {
+    readonly containerBg: string;
+    readonly initialsText: string;
+}
+/**
+ * A stable per-identity fill drawn from the palette's own hue ramps, with its label DERIVED by the
+ * same `resolveFilledAccent` walk every filled surface in this library uses. Web hashes onto eight
+ * fixed hex swatches and inks them with `onFilled`, which is why two of its eight measure ~2:1
+ * against white; walking a real ramp instead clears AA on every brand × mode (`Avatar.test.ts`).
+ */
+export declare function resolveAvatarIdentityColors(palette: PaletteProps, seed: string): AvatarIdentityColors;
 export interface AvatarAccessibilityInput {
     readonly accessibilityLabel?: string | undefined;
 }
@@ -119,5 +139,16 @@ export declare const avatarStructure: import("../../core/style").ThemedVariantRe
             height: 72;
         };
     };
+    shape: {
+        circle: {
+            borderRadius: 9999;
+        };
+        rounded: {
+            borderRadius: 16;
+        };
+        square: {
+            borderRadius: 0;
+        };
+    };
 }, import("react-native").ViewStyle>;
 //# sourceMappingURL=Avatar.variants.d.ts.map

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

@@ -7,5 +7,5 @@
  */
 export { Avatar } from "./Avatar";
 export type { AvatarProps } from "./Avatar";
-export type { AvatarSize } from "./Avatar.variants";
+export type { AvatarShape, AvatarSize } from "./Avatar.variants";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/avatar-group/AvatarGroup.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AvatarGroup — a horizontal stack of `Avatar`s with negative overlap and a `+N` overflow pill when
+ * `avatars.length` exceeds `max`. Each face is this library's own `Avatar` module — never a hand-rolled
+ * image/initials pair — so list recycling, identity hashing, and shape defaults stay consistent.
+ *
+ * No `accessibilityRole` of its own. Each composed `Avatar` gets a label — the consumer's, or (since
+ * a grouped face has no adjacent visible name to lean on, unlike a standalone `Avatar`) a generic
+ * `resolveAvatarGroupFaceFallbackLabel` fallback. The overflow pill carries its own `"text"`-role
+ * label so a screen reader hears how many faces are hidden, not just the ones on screen.
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { AvatarSize } from "../avatar/Avatar.variants";
+export interface AvatarGroupItem {
+    readonly source?: {
+        uri: string;
+    };
+    readonly initials?: string;
+    readonly identity?: string;
+    readonly accessibilityLabel?: string;
+}
+export interface AvatarGroupProps {
+    avatars: readonly AvatarGroupItem[];
+    max?: number;
+    size?: AvatarSize;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const AvatarGroup: import("react").NamedExoticComponent<AvatarGroupProps>;
+//# sourceMappingURL=AvatarGroup.d.ts.map