pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/accordion/MODULE.md

@@ -14,6 +14,7 @@ too. `type="multiple"` lets every section toggle independently.
 | `index.ts` | Public surface: `Accordion`, `AccordionProps`, `AccordionItem`, `AccordionSize`. |
 | `__tests__/Accordion.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
 | `__tests__/Accordion.render.test.tsx` | Render: single/multiple semantics, controlled vs uncontrolled `value`, disabled, reduced-motion chevron, focus ring. |
+| `__tests__/Accordion.motion.test.tsx` | Motion: reduce-motion snap, the real content tween, the device tier's `durationScale` reaching it, and the collapse staying a synchronous unmount. |
 
 ## Props
 
@@ -37,9 +38,10 @@ way so far, because a disclosure list's open state is commonly local UI state, n
 
 ## Accessibility contract (WCAG)
 
-- **4.1.2** — each header carries `accessibilityRole="button"` and
-  `accessibilityState={{ expanded, disabled }}`, so a screen reader announces the disclosure state
-  the visual chevron also shows.
+- **4.1.2** — each header carries `accessibilityRole="button"` and flat `aria-expanded` /
+  `aria-disabled`, so a screen reader announces the disclosure state the visual chevron also shows.
+  Flat, never `accessibilityState={{…}}`: react-native-web discards the object form — see
+  `docs/PLATFORM-A11Y-PROPS.md`.
 - **2.5.x target size** — every size reaches ≥ 44 dp: `sm`'s 40 dp header grows via `hitSlop`;
   `md`/`lg` are already ≥ 44 dp.
 - **1.4.3** — the title is `fg.default`, measured ≥ 4.5:1 against the canvas AND against its own
@@ -52,19 +54,36 @@ way so far, because a disclosure list's open state is commonly local UI state, n
 - **2.4.7 / 2.4.11** — a visible focus ring (`border.focus`) appears on keyboard/AT focus, a small
   gap outside the header on the canvas — same idiom as `Button`/`Checkbox`/`Input`/`Textarea`.
 - **2.3.3** — the chevron's 180° rotation is one `Animated.Value` driven by `expanded`. Under
-  reduced motion it is snapped with `setValue` instead of tweened with `Animated.timing` (verified
-  by spying on `Animated.timing` and asserting it is never called) — the same idiom `Tabs`' indicator
-  uses, not a `duration: 0` timing (which can still tween through intermediate frames).
+  reduced motion it is snapped with `setValue` instead of tweened (verified by spying on
+  `Animated.timing` and asserting it is never called) — the same idiom `Tabs`' indicator uses, not a
+  `duration: 0` timing (which can still tween through intermediate frames). Expanded content
+  fades/slides in on the native driver; collapse unmounts it immediately so heavy subtrees are never
+  kept in the tree — or read by a screen reader — while closed.
 
-## Why content is conditionally rendered, not height-animated
+## Motion
+
+Everything routes through **`useMotion()`** — no module-local timing constant, no raw `Easing.`
+(`ACCORDION_TIMING` and `CONTENT_EASE_IN` are gone). Both consequences are the point: the content
+reveal and the chevron now pick up the device tier's `durationScale` and the global `MOTION_SCALE` /
+`MOTION_ENABLED` switches, which a module-scope read of `MOTION_DURATION.normal` never could. The
+slide distance is `MOTION_TRANSFORM.offsetY`; reduce-motion is `motion.enabled`, never a second
+`useReducedMotion()` call (`core/motion/MODULE.md` rule 6). Header presses use `usePressState`
+(scale + state-layer overlay).
+
+## Why content is not height-animated
 
 React Native has no native height transition without a measure-then-animate hack: mount the content
 off-screen, measure it via `onLayout`, then tween an `Animated.Value` from 0 to the measured height.
 That hack is fragile (a resize invalidates the cached measurement, a wrong first frame is visible)
 and is not meaningfully testable under this repo's test renderer, which never runs real layout (see
-`Tabs`' own documented gap for its indicator's `onLayout` dependency). A conditional mount is an
-honest instant "snap", which is explicitly an accepted alternative for this component — and it means
-there is nothing left to gate for reduced motion on the content itself; only the chevron animates.
+`Tabs`' own documented gap for its indicator's `onLayout` dependency). Instead, expanded content uses
+a native-driver **opacity + translateY** reveal, and unmounts on collapse without an exit
+tween — no layout measurement, no scroll jank. Mounting is derived from `expanded` rather than
+gated on an animation callback: a tween that is interrupted, or never runs, must never be able to
+strand collapsed content in the tree. **The missing exit fade is deliberate and load-bearing**:
+`filter-sheet` asserts a closed section is gone on the very next render, synchronously. Reintroducing
+an exit animation here breaks that — `Accordion.motion.test.tsx` pins the synchronous unmount. Sections that start open (`defaultValue`) snap in with no
+enter animation. Under reduced motion, content snaps instantly the same way the chevron does.
 
 ## Why `disabled` is whole-accordion, not per-item
 
@@ -94,4 +113,10 @@ does not attempt to special-case that; flagged here rather than silently guessed
 
 ## Performance
 
-Both `Accordion` and the internal (non-exported) `AccordionRow` are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`); `colors` is `useMemo`'d, and `emitChange`/`toggle` are `useCallback`'d so the parent hands every row the SAME stable `onToggle` function (the row now calls back with its own `item.value` instead of the parent binding a fresh per-item closure) — without this, `AccordionRow`'s memo would be a no-op.
+Both `Accordion` and the internal (non-exported) `AccordionRow` are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`); `colors` is `useMemo`'d, and `emitChange`/`toggle` are `useCallback`'d so the parent hands every row the SAME stable `onToggle` function (the row calls back with its own `item.value` instead of the parent binding a fresh per-item closure) — without this, `AccordionRow`'s memo would be a no-op. `emitChange` depends on the two `onValueChange` callbacks destructured out of `props`, never on `props` itself: `props` is a fresh object every render, so a raw `[..., props]` dependency (a real regression this module shipped and fixed) recreates `emitChange`/`toggle` — and defeats every row's memo — on every unrelated re-render, even when the caller's own callback didn't change. Regression-guarded in `Accordion.render.test.tsx` (a row's `onPress` reference stays identical across a re-render triggered by an unrelated prop).
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/alert-dialog/AlertDialog.js

@@ -9,10 +9,11 @@
  */
 
 import { memo } from "react";
-import { Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+import { View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
 import { Button } from "../button/index.js";
 import { Modal } from "../modal/index.js";
+import { Text } from "../text/index.js";
 import { alertDialogActionsStructure, resolveAlertDialogConfirmTone } from "./AlertDialog.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export const AlertDialog = /*#__PURE__*/memo(function AlertDialog({
@@ -36,11 +37,11 @@ export const AlertDialog = /*#__PURE__*/memo(function AlertDialog({
     title: title,
     testID: testID,
     children: [description !== undefined && /*#__PURE__*/_jsx(Text, {
-      style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-        fontSize: theme.fontSizes.md,
-        color: theme.colors.fg.muted,
+      variant: "body",
+      color: "muted",
+      style: {
         marginBottom: theme.space[5]
-      }],
+      },
       children: description
     }), /*#__PURE__*/_jsxs(View, {
       style: alertDialogActionsStructure(theme),

package/lib/module/modules/alert-dialog/AlertDialog.variants.js

@@ -15,6 +15,7 @@
  */
 
 import { createThemedVariants } from "../../core/style/index.js";
+import { floatingSurfaceStyle } from "../../theme/platform/floatingSurface.native.js";
 /**
  * Maps AlertDialog's own closed `tone` union onto the confirm action's `ButtonTone`. `"default"`
  * resolves to Button's own default tone (`"accent"`) rather than inventing a fourth tone value;
@@ -41,4 +42,7 @@ export const alertDialogActionsStructure = createThemedVariants(theme => ({
     columnGap: theme.space[3]
   }
 }));
+export function alertDialogPanelDepth(theme) {
+  return floatingSurfaceStyle(theme, "lg");
+}
 //# sourceMappingURL=AlertDialog.variants.js.map

package/lib/module/modules/alert-dialog/MODULE.md

@@ -53,8 +53,11 @@ own measurement, added here rather than assumed. What this module is responsible
   Button and its label `Text`, so a change to Button's tone mapping is caught here too, without this
   module importing Button's internal `resolveButtonTone` resolver.
 - **Dismissal semantics** — every one of Modal's dismissal paths (backdrop press, Android hardware
-  back, iOS VoiceOver escape) still resolves to `onRequestClose`, since `AlertDialog` never
-  intercepts it; only the cancel *action* gets the `onCancel` override.
+  back, iOS VoiceOver escape, and on web Escape) still resolves to `onRequestClose`, since
+  `AlertDialog` never intercepts it; only the cancel *action* gets the `onCancel` override.
+- **2.1.1 keyboard (web only)** — INHERITED whole from `Modal`: Escape, the Tab trap and focus
+  restore on the `ModalPortalProvider` branch. This module deliberately contains no keyboard code;
+  `__tests__/AlertDialog.keyboard.web.test.tsx` asserts the inheritance rather than duplicating it.
 - **Confirm vs. cancel are never confusable** — the confirm action is always `variant="solid"`
   (filled, high-emphasis) and the cancel action is always `variant="outline"` (unfilled), so the
   destructive/primary choice is never the visually quieter one.
@@ -79,3 +82,9 @@ own measurement, added here rather than assumed. What this module is responsible
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No `useCallback`/`useMemo` needed: `cancelPress`/`onConfirm` are forwarded straight through to `Modal`/`Button` as direct prop references, never a freshly-created closure.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/app-bar/AppBar.js

@@ -0,0 +1,181 @@
+"use strict";
+
+/**
+ * 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 { memo, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Text, View } from "react-native";
+import { HEADING_LEVEL, HeadingText } from "../../core/heading/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/index.js";
+import { Button } from "../button/index.js";
+import { appBarActionsRowStructure, appBarSideStructure, appBarSideTrailingStructure, appBarStructure, appBarTitleBoxStructure, resolveAppBarColors } from "./AppBar.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const BACK_LABEL = "Back";
+function normalizeTrailingActions(trailing) {
+  if (trailing === undefined) return [];
+  if (Array.isArray(trailing)) return trailing;
+  return [trailing];
+}
+/**
+ * Dissolves the title box when the title or subtitle changes: fade out, swap the text, fade back
+ * in. Opacity only, native driver. First mount never animates — the navigator already animates a
+ * header appearing, and a second fade there reads as a stutter.
+ */
+function useTitleCrossfade(title, subtitle) {
+  const motion = useMotion();
+  const opacity = useAnimatedValue(1);
+  const running = useRef(null);
+  const fadeInPending = useRef(false);
+  const [displayed, setDisplayed] = useState({
+    title,
+    subtitle
+  });
+  useEffect(() => {
+    if (displayed.title === title && displayed.subtitle === subtitle) {
+      if (!fadeInPending.current) return;
+      fadeInPending.current = false;
+      running.current?.stop();
+      if (!motion.enabled) {
+        opacity.setValue(1);
+        return;
+      }
+      running.current = motion.timing(opacity, 1, {
+        duration: "fast",
+        easing: "decelerate"
+      });
+      running.current.start();
+      return;
+    }
+    running.current?.stop();
+    if (!motion.enabled) {
+      opacity.setValue(1);
+      setDisplayed({
+        title,
+        subtitle
+      });
+      return;
+    }
+    running.current = motion.timing(opacity, 0, {
+      duration: "fast",
+      easing: "accelerate"
+    });
+    running.current.start(({
+      finished
+    }) => {
+      if (!finished) return;
+      fadeInPending.current = true;
+      setDisplayed({
+        title,
+        subtitle
+      });
+    });
+  }, [title, subtitle, displayed, motion, opacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const stale = displayed.title !== title || displayed.subtitle !== subtitle;
+  return {
+    displayed,
+    opacity,
+    stale
+  };
+}
+export const AppBar = /*#__PURE__*/memo(function AppBar({
+  title,
+  subtitle,
+  onBack,
+  leading,
+  trailing,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = resolveAppBarColors(theme.colors);
+  const trailingActions = useMemo(() => normalizeTrailingActions(trailing), [trailing]);
+  const {
+    displayed,
+    opacity,
+    stale
+  } = useTitleCrossfade(title, subtitle);
+  const titleBoxStyle = useMemo(() => [appBarTitleBoxStructure(theme), {
+    opacity
+  }], [theme, opacity]);
+  const barDepth = useMemo(() => ({
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  }), [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [appBarStructure(theme), barDepth, style],
+    children: [/*#__PURE__*/_jsx(View, {
+      style: appBarSideStructure(theme),
+      children: onBack !== undefined ? /*#__PURE__*/_jsx(Button, {
+        icon: "arrow-left",
+        accessibilityLabel: BACK_LABEL,
+        variant: "ghost",
+        tone: "neutral",
+        onPress: onBack,
+        testID: testID === undefined ? undefined : `${testID}-back`
+      }) : leading !== undefined ? /*#__PURE__*/_jsx(Button, {
+        icon: leading.icon,
+        accessibilityLabel: leading.accessibilityLabel,
+        variant: "ghost",
+        tone: "neutral",
+        onPress: leading.onPress,
+        testID: testID === undefined ? undefined : `${testID}-leading`
+      }) : null
+    }), /*#__PURE__*/_jsxs(Animated.View, {
+      style: titleBoxStyle
+      // The outgoing title is still mounted (and still an accessibility element) while it fades,
+      // so without this a screen reader can announce the title of the screen just left.
+      ,
+      accessibilityElementsHidden: stale,
+      importantForAccessibility: stale ? "no-hide-descendants" : "auto",
+      testID: testID === undefined ? undefined : `${testID}-title`,
+      children: [/*#__PURE__*/_jsx(HeadingText, {
+        accessibilityRole: "header",
+        "aria-level": HEADING_LEVEL.screen,
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.bold), {
+          fontSize: theme.fontSizes.lg,
+          color: colors.title
+        }],
+        children: displayed.title
+      }), displayed.subtitle !== undefined && /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          fontSize: theme.fontSizes.xs,
+          color: colors.subtitle
+        }],
+        children: displayed.subtitle
+      })]
+    }), /*#__PURE__*/_jsx(View, {
+      style: appBarSideTrailingStructure(theme),
+      children: trailingActions.length > 0 ? /*#__PURE__*/_jsx(View, {
+        style: appBarActionsRowStructure(theme),
+        children: trailingActions.map((action, index) => /*#__PURE__*/_jsx(Button, {
+          icon: action.icon,
+          accessibilityLabel: action.accessibilityLabel,
+          variant: "ghost",
+          tone: "neutral",
+          onPress: action.onPress,
+          testID: testID === undefined ? undefined : `${testID}-trailing-${index}`
+        }, `${action.icon}-${action.accessibilityLabel}-${index}`))
+      }) : null
+    })]
+  });
+});
+//# sourceMappingURL=AppBar.js.map

package/lib/module/modules/app-bar/AppBar.variants.js

@@ -0,0 +1,71 @@
+"use strict";
+
+/**
+ * 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 { createThemedVariants } from "../../core/style/index.js";
+
+/** Matches `Button`'s `MIN_TOUCH_TARGET` — each side slot reserves at least 44dp for icon actions. */
+export const APP_BAR_SIDE_MIN_WIDTH = 44;
+/**
+ * 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 function resolveAppBarColors(colors) {
+  return {
+    background: colors.bg.surface,
+    border: colors.border.default,
+    title: colors.fg.default,
+    subtitle: colors.fg.muted
+  };
+}
+
+/**
+ * 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 const appBarStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingHorizontal: theme.space[2],
+    paddingVertical: theme.space[2],
+    columnGap: theme.space[1]
+  }
+}));
+export const appBarSideStructure = createThemedVariants(_theme => ({
+  base: {
+    minWidth: APP_BAR_SIDE_MIN_WIDTH,
+    justifyContent: "center"
+  }
+}));
+export const appBarSideTrailingStructure = createThemedVariants(_theme => ({
+  base: {
+    minWidth: APP_BAR_SIDE_MIN_WIDTH,
+    justifyContent: "center",
+    alignItems: "flex-end"
+  }
+}));
+export const appBarTitleBoxStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    paddingHorizontal: theme.space[1]
+  }
+}));
+export const appBarActionsRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[1]
+  }
+}));
+//# sourceMappingURL=AppBar.variants.js.map

package/lib/module/modules/app-bar/MODULE.md

@@ -0,0 +1,68 @@
+# app-bar/ — a themed top bar for screen headers
+
+`AppBar` groups a required title, an optional subtitle, an optional back affordance, and optional
+leading/trailing icon actions into one header row. Every action is a library `Button` (icon-only,
+ghost) driven by a closed `IconName` — never a consumer `ReactNode` slot.
+
+## Files
+
+| File | Role |
+|------|------|
+| `AppBar.tsx` | The component. Composes ghost `Button`s for back/leading/trailing actions; `style` last. |
+| `AppBar.variants.ts` | Pure resolver (`resolveAppBarColors`) + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `AppBar`, `AppBarProps`, `AppBarAction`, `IconName`. |
+| `__tests__/AppBar.test.ts` | Pure: WCAG 1.4.3 on the title, colour-mapping contract, side min-width floor. |
+| `__tests__/AppBar.render.test.tsx` | Render: title/subtitle, heading role + level, back press, trailing action press, title crossfade (including the outgoing title leaving the accessibility tree), consumer `style` last. |
+| `__tests__/AppBar.dom.test.tsx` | Real DOM (`jest.web.config.js`): the title renders a real `<h1>`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | `string` | — | Required. Single-line, bold, `fg.default`. |
+| `subtitle` | `string` | — | Optional. Single-line, `fg.muted`. |
+| `onBack` | `() => void` | — | Renders `arrow-left` ghost button labelled "Back". |
+| `leading` | `AppBarAction` | — | Custom leading action when `onBack` is absent. |
+| `trailing` | `AppBarAction \| AppBarAction[]` | — | One or more trailing icon actions. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`. |
+
+## Accessibility contract (WCAG)
+
+- **1.3.1 / 2.4.6 — the title is a level-1 heading.** It carries `accessibilityRole="header"` and
+  `aria-level={1}` (`HEADING_LEVEL.screen`, `core/heading`) — without a level, `react-native-web`
+  still renders `<h1>` by default, but every OTHER heading on the screen (`Section`, `EmptyState`,
+  `DataTable` headers) would collapse to `<h1>` too. Level 1 is deliberate: the title is the screen's
+  own heading, the one the rest of the screen's outline nests under. AppBar + `Section` are what
+  almost every screen is built from, so without it rotor heading navigation — a primary way
+  screen-reader users move around an app — finds nothing on the screen at all. The subtitle stays
+  plain text: it is supporting copy, not a second heading level.
+- **No `accessibilityRole` on the bar itself** — like `Card`, a plain grouping container; each
+  composed `Button` carries its own role/state.
+- **The outgoing title is hidden while it crossfades.** The old text stays mounted for the whole
+  fade-out, so the title box carries `accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"` (both props, the idiom `Textarea` uses) for
+  exactly that window — otherwise a reader can announce the heading of the screen just left. Under
+  reduced motion there is no fade, so it is never hidden.
+- **4.1.3** — n/a: a title change is a heading change, not a status message, and the navigator
+  already announces the screen change. Nothing here calls `useAnnounce` (that would double-speak).
+
+## Motion
+
+One animation only: a **title crossfade**. When `title` or `subtitle` changes the title box fades
+out, swaps the text, and fades back in — opacity only, native driver, all timing resolved through
+`useMotion()` (`fast` + `accelerate`/`decelerate`). The displayed text therefore lags the prop by
+one fade-out, so the *old* title dissolves rather than the new one flashing.
+
+- **No animation on first mount** — the navigator already animates a header appearing.
+- **Reduce-motion (WCAG 2.3.3)** snaps opacity with `setValue` and swaps the text immediately.
+- In-flight animations are stopped on effect re-run and on unmount.
+- Elevation-on-scroll was considered and rejected: it needs a public scroll-offset prop, and the
+  API contract does not widen props without cause.
+- The title box carries `testID={`${testID}-title`}` for tests.
+
+## Performance
+
+Wrapped in `React.memo`. Trailing actions are normalised through `useMemo` so a stable array
+reference is not required from the caller. The title box's style array is `useMemo`'d so the
+`Animated.View` is not handed a fresh array each render.

package/lib/module/modules/app-bar/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * 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.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/avatar/Avatar.js

@@ -1,32 +1,58 @@
 "use strict";
 
 /**
- * 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 { memo } from "react";
-import { Image, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
-import { AVATAR_SIZES, avatarStructure, resolveAvatarAccessibility, resolveAvatarColors } from "./Avatar.variants.js";
+import { memo, useMemo } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { MediaImage } from "../../core/media/index.js";
+import { Icon } from "../../core/icon/index.js";
+import { useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { AVATAR_SIZES, avatarStructure, resolveAvatarAccessibility, resolveAvatarColors, resolveAvatarIdentityColors } from "./Avatar.variants.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 export const Avatar = /*#__PURE__*/memo(function Avatar({
   size = "md",
+  shape = "circle",
   source,
   initials,
+  identity,
+  recyclingKey,
   accessibilityLabel,
   style,
   testID
 }) {
   const theme = useTheme();
+  const motion = useMotion();
   const spec = AVATAR_SIZES[size];
-  const colors = resolveAvatarColors(theme.colors);
   const a11y = resolveAvatarAccessibility({
     accessibilityLabel
   });
+  const colors = useMemo(() => identity === undefined || identity.length === 0 ? resolveAvatarColors(theme.colors) : resolveAvatarIdentityColors(theme.palette, identity), [theme.colors, theme.palette, identity]);
+  const rootStyle = useMemo(() => [avatarStructure(theme, {
+    size,
+    shape
+  }), {
+    backgroundColor: colors.containerBg
+  }, style], [theme, size, shape, colors, style]);
+  const initialsStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: spec.fontSize,
+    color: colors.initialsText
+  }], [theme, spec, colors]);
+  const transition = motion.enabled ? motion.duration("fast") : 0;
   return /*#__PURE__*/_jsx(View, {
     testID: testID,
     accessible: a11y.accessible,
@@ -34,24 +60,24 @@ export const Avatar = /*#__PURE__*/memo(function Avatar({
     accessibilityLabel: a11y.accessibilityLabel,
     accessibilityElementsHidden: a11y.accessibilityElementsHidden,
     importantForAccessibility: a11y.importantForAccessibility,
-    style: [avatarStructure(theme, {
-      size
-    }), {
-      backgroundColor: colors.containerBg
-    }, style],
-    children: source ? /*#__PURE__*/_jsx(Image, {
+    style: rootStyle,
+    children: source ? /*#__PURE__*/_jsx(MediaImage, {
       testID: testID === undefined ? undefined : `${testID}-image`,
       source: source,
-      resizeMode: "cover",
+      contentFit: "cover",
+      transition: transition,
+      recyclingKey: recyclingKey ?? source.uri,
       style: StyleSheet.absoluteFill
     }) : initials ? /*#__PURE__*/_jsx(Text, {
       numberOfLines: 1,
-      style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-        fontSize: spec.fontSize,
-        color: colors.initialsText
-      }],
+      style: initialsStyle,
       children: initials.slice(0, 2)
-    }) : null
+    }) : /*#__PURE__*/_jsx(Icon, {
+      name: "user",
+      size: Math.round(spec.box * 0.45),
+      color: colors.initialsText,
+      strokeWidth: 2
+    })
   });
 });
 //# sourceMappingURL=Avatar.js.map