pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/avatar-group/AvatarGroup.js

@@ -0,0 +1,77 @@
+"use strict";
+
+/**
+ * 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` carries its own optional label; the
+ * overflow pill is hidden from assistive tech as decorative chrome (the visible faces carry identity).
+ */
+
+import { memo, useMemo } from "react";
+import { Text, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { Avatar } from "../avatar/index.js";
+import { AVATAR_GROUP_DEFAULT_MAX, avatarGroupItemStructure, avatarGroupOverflowLabelStructure, avatarGroupOverflowStructure, avatarGroupStructure, resolveAvatarGroupColors, resolveAvatarGroupOverflowCount, resolveAvatarGroupOverlap, resolveAvatarGroupVisibleCount } from "./AvatarGroup.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const AvatarGroup = /*#__PURE__*/memo(function AvatarGroup({
+  avatars,
+  max = AVATAR_GROUP_DEFAULT_MAX,
+  size = "md",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = useMemo(() => resolveAvatarGroupColors(theme.colors), [theme.colors]);
+  const overlap = resolveAvatarGroupOverlap(size);
+  const visibleCount = resolveAvatarGroupVisibleCount(avatars.length, max);
+  const overflowCount = resolveAvatarGroupOverflowCount(avatars.length, visibleCount);
+  const visibleAvatars = useMemo(() => avatars.slice(0, visibleCount), [avatars, visibleCount]);
+  const rootStyle = useMemo(() => [avatarGroupStructure(theme), style], [theme, style]);
+  const faces = useMemo(() => visibleAvatars.map((item, index) => /*#__PURE__*/_jsx(View, {
+    style: [avatarGroupItemStructure(theme), {
+      borderColor: colors.ring,
+      marginLeft: index === 0 ? 0 : overlap,
+      zIndex: visibleAvatars.length - index
+    }],
+    children: /*#__PURE__*/_jsx(Avatar, {
+      size: size,
+      source: item.source,
+      initials: item.initials,
+      identity: item.identity,
+      accessibilityLabel: item.accessibilityLabel,
+      testID: testID === undefined ? undefined : `${testID}-avatar-${index}`
+    })
+  }, `${item.source?.uri ?? item.initials ?? item.identity ?? "avatar"}-${index}`)), [visibleAvatars, theme, colors, overlap, size, testID]);
+  const overflowStyle = useMemo(() => [avatarGroupItemStructure(theme), avatarGroupOverflowStructure(theme, {
+    size
+  }), {
+    borderColor: colors.ring,
+    marginLeft: overlap,
+    backgroundColor: colors.overflowBackground,
+    alignItems: "center",
+    justifyContent: "center",
+    zIndex: 0
+  }], [theme, size, colors, overlap]);
+  const overflowLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), avatarGroupOverflowLabelStructure(theme, {
+    size
+  }), {
+    color: colors.overflowText
+  }], [theme, size, colors]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [faces, overflowCount > 0 ? /*#__PURE__*/_jsx(View, {
+      testID: testID === undefined ? undefined : `${testID}-overflow`,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      style: overflowStyle,
+      children: /*#__PURE__*/_jsx(Text, {
+        style: overflowLabelStyle,
+        children: `+${overflowCount}`
+      })
+    }) : null]
+  });
+});
+//# sourceMappingURL=AvatarGroup.js.map

package/lib/module/modules/avatar-group/AvatarGroup.variants.js

@@ -0,0 +1,109 @@
+"use strict";
+
+/**
+ * AvatarGroup's style resolution — same split as `Avatar.variants`:
+ *  - STRUCTURE (row overlap, overflow pill sizing) lives in the themed resolvers and plain constants.
+ *  - COLOUR is resolved from the theme's ROLE colours, never a raw ramp and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the behaviour tests import this directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedTextVariants, createThemedVariants } from "../../core/style/index.js";
+import { AVATAR_SIZES } from "../avatar/Avatar.variants.js";
+
+/** Default visible faces before collapsing the remainder into a `+N` overflow pill. */
+export const AVATAR_GROUP_DEFAULT_MAX = 4;
+
+/** Ring width separating stacked faces — drawn in the canvas colour so each face reads distinctly. */
+export const AVATAR_GROUP_RING_WIDTH = 2;
+export function resolveAvatarGroupColors(colors) {
+  return {
+    ring: colors.bg.canvas,
+    overflowBackground: colors.bg.sunken,
+    overflowText: colors.fg.muted
+  };
+}
+
+/** Negative overlap as a fraction of the avatar diameter — same visual density as common stacked rows. */
+export function resolveAvatarGroupOverlap(size) {
+  return Math.round(AVATAR_SIZES[size].box * -0.25);
+}
+export function resolveAvatarGroupVisibleCount(total, max) {
+  if (total <= max) return total;
+  // Reserve one slot for the overflow pill when there are hidden faces.
+  return Math.max(1, max - 1);
+}
+export function resolveAvatarGroupOverflowCount(total, visible) {
+  return Math.max(0, total - visible);
+}
+export const avatarGroupStructure = createThemedVariants(_theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center"
+  }
+}));
+export const avatarGroupItemStructure = createThemedVariants(_theme => ({
+  base: {
+    borderWidth: AVATAR_GROUP_RING_WIDTH
+  }
+}));
+export const avatarGroupOverflowStructure = createThemedVariants(theme => ({
+  variants: {
+    size: {
+      xs: {
+        width: AVATAR_SIZES.xs.box,
+        height: AVATAR_SIZES.xs.box,
+        borderRadius: theme.radii.full
+      },
+      sm: {
+        width: AVATAR_SIZES.sm.box,
+        height: AVATAR_SIZES.sm.box,
+        borderRadius: theme.radii.full
+      },
+      md: {
+        width: AVATAR_SIZES.md.box,
+        height: AVATAR_SIZES.md.box,
+        borderRadius: theme.radii.full
+      },
+      lg: {
+        width: AVATAR_SIZES.lg.box,
+        height: AVATAR_SIZES.lg.box,
+        borderRadius: theme.radii.full
+      },
+      xl: {
+        width: AVATAR_SIZES.xl.box,
+        height: AVATAR_SIZES.xl.box,
+        borderRadius: theme.radii.full
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+export const avatarGroupOverflowLabelStructure = createThemedTextVariants(_theme => ({
+  variants: {
+    size: {
+      xs: {
+        fontSize: AVATAR_SIZES.xs.fontSize
+      },
+      sm: {
+        fontSize: AVATAR_SIZES.sm.fontSize
+      },
+      md: {
+        fontSize: AVATAR_SIZES.md.fontSize
+      },
+      lg: {
+        fontSize: AVATAR_SIZES.lg.fontSize
+      },
+      xl: {
+        fontSize: AVATAR_SIZES.xl.fontSize
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=AvatarGroup.variants.js.map

package/lib/module/modules/avatar-group/MODULE.md

@@ -0,0 +1,28 @@
+# avatar-group/ — stacked avatars with overflow count
+
+`AvatarGroup` renders a horizontal stack of library `Avatar`s with negative overlap and a `+N`
+overflow pill when `avatars.length` exceeds `max`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `AvatarGroup.tsx` | The component. Composes `Avatar` + overflow pill; `style` last. |
+| `AvatarGroup.variants.ts` | Pure resolvers (colours, overlap math, overflow counts) + themed structural resolvers. |
+| `index.ts` | Public surface: `AvatarGroup`, `AvatarGroupProps`, `AvatarGroupItem`, `AvatarSize`. |
+| `__tests__/AvatarGroup.test.ts` | Pure: overflow math, WCAG on overflow pill label. |
+| `__tests__/AvatarGroup.render.test.tsx` | Render: visible faces + `+N` pill, consumer `style` last. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `avatars` | `AvatarGroupItem[]` | — | Required. Each item forwards to `Avatar`. |
+| `max` | `number` | `4` | Visible faces before collapsing remainder into `+N`. |
+| `size` | `AvatarSize` | `"md"` | Shared size for every face and the overflow pill. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`; faces get `${testID}-avatar-{i}`. |
+
+## Performance
+
+Wrapped in `React.memo`. Visible slice is `useMemo`'d on `avatars` and `max`.

package/lib/module/modules/avatar-group/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/avatar-group`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures an AvatarGroup
+ * through its props, never by importing its internals.
+ */
+
+export { AvatarGroup } from "./AvatarGroup.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/badge/Badge.js

@@ -9,12 +9,13 @@
 import { memo } from "react";
 import { Text, View } from "react-native";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { BADGE_SIZES, badgeStructure, resolveBadgeAccessibility, resolveBadgeTone } from "./Badge.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const ICON_STROKE = 2;
 export const Badge = /*#__PURE__*/memo(function Badge({
   tone = "accent",
+  customColors,
   size = "md",
   label,
   icon,
@@ -23,7 +24,7 @@ export const Badge = /*#__PURE__*/memo(function Badge({
 }) {
   const theme = useTheme();
   const spec = BADGE_SIZES[size];
-  const toneColors = resolveBadgeTone(theme.colors, tone);
+  const toneColors = resolveBadgeTone(theme.colors, tone, customColors);
   const a11y = resolveBadgeAccessibility({
     label
   });

package/lib/module/modules/badge/Badge.variants.js

@@ -13,7 +13,7 @@
 
 import { createThemedVariants } from "../../core/style/index.js";
 
-/** `accent`/`neutral` are brand-driven emphasis; the rest mirror the theme's status roles. */
+/** `custom` requires `customColors` — server-driven hex escape hatch. */
 
 /**
  * Badge-specific dimensions — a chip is never a touch target (Badge is a `View`, not a
@@ -53,7 +53,17 @@ export const BADGE_SIZES = {
  * and measures ≥ 5.05:1 against the canvas incidentally) — so the border reuses it, giving a
  * coloured outline that always matches the label, never an unreadable hairline.
  */
-export function resolveBadgeTone(colors, tone) {
+export function resolveBadgeTone(colors, tone, customColors) {
+  if (tone === "custom") {
+    if (!customColors) {
+      throw new Error('Badge tone="custom" requires customColors={{ bg, fg }}.');
+    }
+    return {
+      fill: customColors.bg,
+      text: customColors.fg,
+      border: customColors.fg
+    };
+  }
   switch (tone) {
     case "accent":
       return {

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

@@ -80,3 +80,9 @@ brand × mode.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Its one child, `Icon`, only ever receives primitives — nothing to memoize.
+
+## 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/banner/Banner.js

@@ -0,0 +1,135 @@
+"use strict";
+
+/**
+ * Banner — a persistent, INLINE message that sits in the layout and stays until dismissed.
+ * Distinct from the two neighbours it is easy to confuse it with: `toast` is a transient overlay
+ * that disappears on a timer, and `alert-dialog` is a modal that blocks the screen for a decision.
+ *
+ * `visible` drives a fade+slide enter/exit through `useEnterExit`. It defaults to `true`, and
+ * `useEnterExit` deliberately skips the enter for a banner that mounts already visible — so a
+ * consumer that never passes `visible` sees exactly the old, animation-free behaviour.
+ */
+
+import { memo, useCallback, useMemo } from "react";
+import { Animated, Pressable, Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { useEnterExit } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { BANNER_DISMISS_ICON_SIZE, BANNER_ICON_SIZE, BANNER_MIN_TOUCH_TARGET, bannerStructure, resolveBannerAccessibility, resolveBannerIcon, resolveBannerTone } from "./Banner.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const hitSlopFor = size => {
+  const inset = Math.max(0, (BANNER_MIN_TOUCH_TARGET - size) / 2);
+  return {
+    top: inset,
+    bottom: inset,
+    left: inset,
+    right: inset
+  };
+};
+const DISMISS_HIT_SLOP = hitSlopFor(BANNER_DISMISS_ICON_SIZE);
+export const Banner = /*#__PURE__*/memo(function Banner({
+  tone = "info",
+  variant = "subtle",
+  message,
+  title,
+  icon,
+  visible = true,
+  onDismiss,
+  dismissLabel = "Dismiss",
+  action,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const enterExit = useEnterExit(visible);
+  const colors = useMemo(() => resolveBannerTone(theme.colors, tone, variant), [theme.colors, tone, variant]);
+  const a11y = useMemo(() => resolveBannerAccessibility({
+    tone,
+    title,
+    message
+  }), [tone, title, message]);
+  const glyph = icon === null ? undefined : icon ?? resolveBannerIcon(tone);
+  const handleAction = useCallback(() => action?.onPress(), [action]);
+
+  // `style` stays last; the enter/exit style holds only opacity/transform, which `LayoutStyle` cannot name.
+  const rootStyle = useMemo(() => [bannerStructure(theme), {
+    backgroundColor: colors.fill,
+    borderColor: colors.border
+  }, enterExit.style, style], [theme, colors, enterExit.style, style]);
+  const contentStyle = useMemo(() => ({
+    flex: 1,
+    rowGap: theme.space[1]
+  }), [theme]);
+  const textBlockStyle = useMemo(() => ({
+    rowGap: theme.space[1]
+  }), [theme]);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes.md,
+    color: colors.text
+  }], [theme, colors]);
+  const messageStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.text
+  }], [theme, colors]);
+  const actionStyle = useMemo(() => ({
+    alignSelf: "flex-start",
+    paddingVertical: theme.space[1]
+  }), [theme]);
+  const actionLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.text,
+    textDecorationLine: "underline"
+  }], [theme, colors]);
+  const actionHitSlop = useMemo(() => hitSlopFor(theme.fontSizes.sm), [theme]);
+  if (!enterExit.mounted) return null;
+  return /*#__PURE__*/_jsxs(Animated.View, {
+    testID: testID,
+    style: rootStyle,
+    children: [glyph && /*#__PURE__*/_jsx(Icon, {
+      name: glyph,
+      size: BANNER_ICON_SIZE,
+      color: colors.text,
+      strokeWidth: ICON_STROKE
+    }), /*#__PURE__*/_jsxs(View, {
+      style: contentStyle,
+      children: [/*#__PURE__*/_jsxs(View, {
+        accessible: a11y.accessible,
+        accessibilityRole: a11y.accessibilityRole,
+        accessibilityLabel: a11y.accessibilityLabel,
+        style: textBlockStyle,
+        children: [title && /*#__PURE__*/_jsx(Text, {
+          style: titleStyle,
+          children: title
+        }), /*#__PURE__*/_jsx(Text, {
+          style: messageStyle,
+          children: message
+        })]
+      }), action && /*#__PURE__*/_jsx(Pressable, {
+        testID: testID ? `${testID}-action` : undefined,
+        accessibilityRole: "button",
+        accessibilityLabel: action.label,
+        onPress: handleAction,
+        hitSlop: actionHitSlop,
+        style: actionStyle,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: actionLabelStyle,
+          children: action.label
+        })
+      })]
+    }), onDismiss && /*#__PURE__*/_jsx(Pressable, {
+      testID: testID ? `${testID}-dismiss` : undefined,
+      accessibilityRole: "button",
+      accessibilityLabel: dismissLabel,
+      onPress: onDismiss,
+      hitSlop: DISMISS_HIT_SLOP,
+      children: /*#__PURE__*/_jsx(Icon, {
+        name: "x",
+        size: BANNER_DISMISS_ICON_SIZE,
+        color: colors.text,
+        strokeWidth: ICON_STROKE
+      })
+    })]
+  });
+});
+//# sourceMappingURL=Banner.js.map

package/lib/module/modules/banner/Banner.variants.js

@@ -0,0 +1,118 @@
+"use strict";
+
+/**
+ * Banner's style resolution — the same split Badge/Button use:
+ *  - STRUCTURE (padding, radius, gaps, border WIDTH) in the themed `bannerStructure` resolver.
+ *  - COLOUR is `tone` × `variant` driven, resolved from ROLE colours only.
+ *
+ * Free of React and of `lucide`, so the WCAG tests import it directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/**
+ * `subtle` reuses Badge's exact role mapping, which is already measured ≥ 4.5:1 for the label on its
+ * own fill and ≥ 3:1 for `status.text`-as-border against both the canvas and that fill, on every
+ * brand × mode. `solid` inverts onto the designed `solid`/`onSolid` pairing; `neutral` has no solid
+ * rung, so it inverts onto `fg.default` + `bg.surface` — the body-text pairing, high-contrast by
+ * construction.
+ */
+export function resolveBannerTone(colors, tone, variant) {
+  if (variant === "solid") {
+    switch (tone) {
+      case "accent":
+        return {
+          fill: colors.accent.solid,
+          text: colors.accent.onSolid,
+          border: colors.accent.solid
+        };
+      case "neutral":
+        return {
+          fill: colors.fg.default,
+          text: colors.bg.surface,
+          border: colors.fg.default
+        };
+      default:
+        {
+          // `status.solid` is tuned for a compact badge/toast chip, not a page-width surface — it
+          // measures only 1.8-2.6:1 against a near-white canvas for success/warning/info on every
+          // brand. `status.text` (already proven >=3:1 against canvas, via the subtle variant's own
+          // border) doubles as the fill here, paired with its own `onText` label.
+          const status = colors.status[tone];
+          return {
+            fill: status.text,
+            text: status.onText,
+            border: status.text
+          };
+        }
+    }
+  }
+  switch (tone) {
+    case "accent":
+      return {
+        fill: colors.accent.subtle,
+        text: colors.accent.text,
+        border: colors.border.interactive
+      };
+    case "neutral":
+      return {
+        fill: colors.bg.sunken,
+        text: colors.fg.default,
+        border: colors.border.interactive
+      };
+    default:
+      {
+        const status = colors.status[tone];
+        return {
+          fill: status.subtle,
+          text: status.text,
+          border: status.text
+        };
+      }
+  }
+}
+
+/** Leading glyph when the caller passes none. `accent`/`neutral` carry no severity, so they get none. */
+export function resolveBannerIcon(tone) {
+  switch (tone) {
+    case "success":
+      return "circle-check";
+    case "warning":
+      return "triangle-alert";
+    case "danger":
+      return "circle-alert";
+    case "info":
+      return "info";
+    default:
+      return undefined;
+  }
+}
+/**
+ * `danger`/`warning` announce as `alert` so a screen reader interrupts; the rest are passive text.
+ * Title and message collapse into ONE accessible node (WCAG 4.1.2) rather than two stray strings.
+ */
+export function resolveBannerAccessibility(input) {
+  const interrupts = input.tone === "danger" || input.tone === "warning";
+  return {
+    accessible: true,
+    accessibilityRole: interrupts ? "alert" : "text",
+    accessibilityLabel: input.title ? `${input.title}. ${input.message}` : input.message
+  };
+}
+export const BANNER_ICON_SIZE = 20;
+/** Dismiss and action are real touch targets; the visual glyph is smaller than its 44dp hit area. */
+export const BANNER_DISMISS_ICON_SIZE = 16;
+export const BANNER_MIN_TOUCH_TARGET = 44;
+export const bannerStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    columnGap: theme.space[3],
+    padding: theme.space[3],
+    borderRadius: theme.radii.base,
+    borderWidth: theme.borderWidths.thin
+  },
+  variants: {},
+  defaultVariants: {}
+}));
+//# sourceMappingURL=Banner.variants.js.map

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

@@ -0,0 +1,113 @@
+# banner/ — a persistent inline message
+
+`Banner` sits IN the layout and stays until the user (or the app) removes it. It is the third member
+of a family that is easy to confuse:
+
+| Use | Module |
+|-----|--------|
+| Transient, floats over the screen, disappears on a timer | `toast` |
+| Modal, blocks the screen, demands a decision | `alert-dialog` |
+| **Persistent, inline, does not block** | **`banner`** |
+
+## Files
+
+| File | Role |
+|------|------|
+| `Banner.tsx` | The component. Composition + a11y wiring; the dismiss and action affordances are separate `Pressable`s, both siblings of the accessible title+message block rather than descendants of it. |
+| `Banner.variants.ts` | Pure resolvers (`resolveBannerTone`, `resolveBannerIcon`, `resolveBannerAccessibility`) + the themed `bannerStructure`. No React, no lucide. |
+| `index.ts` | Public surface: `Banner`, `BannerProps`, `BannerAction`, the closed unions, `IconName`. |
+| `__tests__/Banner.test.ts` | Pure: WCAG contrast (all brands × modes, both variants) + glyph and a11y contracts. |
+| `__tests__/Banner.render.test.tsx` | Render: tones/variants, dismiss vs action isolation, alert-role announcement, and the structural check that neither control is a descendant of the accessible text block. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | `string` | — | Required. |
+| `title` | `string` | — | Optional heading above the message. |
+| `tone` | `accent \| neutral \| success \| warning \| danger \| info` | `info` | Closed union. |
+| `variant` | `subtle \| solid` | `subtle` | `subtle` tints; `solid` inverts onto a filled surface. |
+| `icon` | `IconName \| null` | per tone | `null` suppresses the glyph entirely. |
+| `onDismiss` | `() => void` | — | Absent = the banner cannot be closed. |
+| `dismissLabel` | `string` | `"Dismiss"` | Screen-reader name for the close control. |
+| `action` | `{ label, onPress }` | — | One inline action; more than one belongs in a dialog. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Seeds `${testID}-dismiss` and `${testID}-action`. |
+
+## Accessibility contract (WCAG)
+
+- **4.1.2 / semantics** — title + message collapse into ONE accessible node, so a screen reader
+  announces the banner as a unit instead of two loose strings. Dismiss and action are their own
+  `button`-role elements with their own labels, so activating either can never be confused with the
+  other (they are also separate code paths — `onDismiss` vs `action.onPress`). Crucially, **both sit
+  OUTSIDE that accessible node**: an accessible node collapses its whole subtree into a single
+  element, so the action — which used to render inside it — could be tapped but never focused or
+  activated by VoiceOver/TalkBack, and its existence was not announced at all (the accessible name
+  is only `"title. message"`). The content column is now a plain layout `View` holding two siblings:
+  the accessible title+message block, and the action. `Banner.render.test.tsx` pins that structure.
+- **4.1.3 status messages** — `danger` and `warning` announce with `accessibilityRole="alert"` so the
+  reader interrupts; the passive tones (`accent`, `neutral`, `success`, `info`) use `text` and are
+  read when focus reaches them. Severity, not styling, decides this.
+- **1.4.3** — text is measured ≥ 4.5:1 against its own fill for every tone × **both** variants,
+  across all brands × both modes. The icon reuses the text colour exactly (never a second lookup), so
+  it inherits that proven ratio and clears its looser 3:1 non-text minimum for free — the same
+  reasoning `menu` and `badge` rely on.
+- **1.4.11** — the `subtle` variant's border is measured ≥ 3:1 against both the page canvas and its
+  own fill; the `solid` variant has no distinct border, so its *fill* is measured ≥ 3:1 against the
+  canvas instead — otherwise a solid banner could be invisible on a same-toned page.
+- **2.5.8 / 2.5.5 target size** — the dismiss glyph (16dp) and the action label are padded to a 44dp
+  touch target via `hitSlop`, so the visual size never dictates the tap size.
+- **2.3.3** — nothing animates; a banner appears and stays. Nothing to suppress.
+- **1.3.1** — the tone icon is redundant with the accessible title/message node right beside it (the
+  glyph repeats what `resolveBannerAccessibility`'s `alert`/`text` role and label already say), so it
+  must not reach assistive tech as a second, unexplained element. `Banner` never wraps it in a hidden
+  container itself — it relies on `core/icon`'s `Icon` defaulting to `aria-hidden` when rendered with
+  no `label`, which is every call site in this file (`Banner` never passes one). Fixed at the `Icon`
+  level rather than here because this exact gap — an un-wrapped `<Icon>` — was a repeated, per-consumer
+  mistake across the library, not a `Banner`-specific one.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split** — padding/radius/border-width via `createThemedVariants`; colour
+   resolved from `RoleColors` per `tone` × `variant`, applied inline.
+2. **Pure, testable resolvers** in `Banner.variants.ts` — contrast is unit-tested against real
+   palettes, never eyeballed.
+3. **Closed `tone` union** — resolved from role colours, never a free-form `color` prop.
+4. **`subtle` reuses `badge`'s exact role mapping**, which is already measured safe on every brand ×
+   mode, rather than deriving a second, unproven tint.
+
+## Design decisions specific to this module
+
+- **`neutral` + `solid` inverts onto `fg.default` / `bg.surface`.** There is no `neutral.solid` rung
+  in the token set; the body-text pairing is high-contrast by construction, so it is the honest
+  inversion rather than inventing a rung.
+- **`accent` and `neutral` get no default glyph.** An icon on a banner communicates *severity*; those
+  two tones carry none, so a glyph would be decoration pretending to be meaning. Callers can still
+  pass one explicitly.
+- **Exactly one `action`.** Two or more competing actions is a decision, and a decision belongs in
+  `alert-dialog` where it can block. Keeping this to one keeps banners non-blocking by design.
+- **No `onPress` on the banner body.** A whole-surface tap target next to a dismiss button produces
+  mis-taps; if the banner should navigate, use the `action`.
+- **The action is a sibling of the accessible text block, not a child of it.** The dismiss control
+  was always shaped that way; the action was not, and that is exactly why it was invisible to
+  assistive tech. The content column carries the layout (`flex: 1` + `rowGap`), the inner block
+  carries `accessible` + the role + the combined name and only the `rowGap` between title and
+  message — so the rendered spacing is unchanged.
+
+## Known gaps
+
+- No auto-dismiss timer — that is `toast`'s job by definition.
+- No stacking/queueing of multiple banners; a caller rendering several owns their order and spacing.
+- No enter/exit animation. Adding one would need `useReducedMotion()` gating (see `2.3.3` above).
+
+## Performance
+
+Wrapped in `React.memo`. `bannerStructure` is a themed resolver, so the structural `StyleSheet`
+compiles once per theme identity rather than per render. The action handler is `useCallback`'d;
+`onDismiss` is passed to the `Pressable` verbatim, since the caller already owns its identity.
+
+## 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/banner/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { Banner } from "./Banner.js";
+//# sourceMappingURL=index.js.map