pixelize-native-library 1.2.0 → 1.3.0

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

@@ -17,10 +17,12 @@
  */
 
 import { memo, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Text, View } from "react-native";
+import { Text, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
 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";
@@ -44,52 +46,56 @@ function useTitleCrossfade(title, subtitle) {
     title,
     subtitle
   });
+  const [hideFromA11y, setHideFromA11y] = useState(false);
+  const titleBoxMotionStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value
+  }));
   useEffect(() => {
     if (displayed.title === title && displayed.subtitle === subtitle) {
       if (!fadeInPending.current) return;
       fadeInPending.current = false;
       running.current?.stop();
       if (!motion.enabled) {
-        opacity.setValue(1);
+        opacity.value = 1;
+        setHideFromA11y(false);
         return;
       }
       running.current = motion.timing(opacity, 1, {
         duration: "fast",
         easing: "decelerate"
       });
-      running.current.start();
+      running.current.start(() => queueMicrotask(() => setHideFromA11y(false)));
       return;
     }
     running.current?.stop();
+    setHideFromA11y(true);
     if (!motion.enabled) {
-      opacity.setValue(1);
+      opacity.value = 1;
       setDisplayed({
         title,
         subtitle
       });
+      setHideFromA11y(false);
       return;
     }
     running.current = motion.timing(opacity, 0, {
       duration: "fast",
       easing: "accelerate"
     });
-    running.current.start(({
-      finished
-    }) => {
-      if (!finished) return;
+    running.current.start(result => {
+      if (!result?.finished) return;
       fadeInPending.current = true;
-      setDisplayed({
+      queueMicrotask(() => setDisplayed({
         title,
         subtitle
-      });
+      }));
     });
   }, [title, subtitle, displayed, motion, opacity]);
   useEffect(() => () => running.current?.stop(), []);
-  const stale = displayed.title !== title || displayed.subtitle !== subtitle;
   return {
     displayed,
-    opacity,
-    stale
+    titleBoxMotionStyle,
+    stale: hideFromA11y
   };
 }
 export const AppBar = /*#__PURE__*/memo(function AppBar({
@@ -106,18 +112,17 @@ export const AppBar = /*#__PURE__*/memo(function AppBar({
   const trailingActions = useMemo(() => normalizeTrailingActions(trailing), [trailing]);
   const {
     displayed,
-    opacity,
+    titleBoxMotionStyle,
     stale
   } = useTitleCrossfade(title, subtitle);
-  const titleBoxStyle = useMemo(() => [appBarTitleBoxStructure(theme), {
-    opacity
-  }], [theme, opacity]);
+  const titleBoxStyle = useMemo(() => [appBarTitleBoxStructure(theme), titleBoxMotionStyle], [theme, titleBoxMotionStyle]);
+  const barDepth = useMemo(() => ({
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  }), [theme]);
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
-    style: [appBarStructure(theme), {
-      backgroundColor: colors.background,
-      borderBottomColor: colors.border
-    }, style],
+    style: [appBarStructure(theme), barDepth, style],
     children: [/*#__PURE__*/_jsx(View, {
       style: appBarSideStructure(theme),
       children: onBack !== undefined ? /*#__PURE__*/_jsx(Button, {
@@ -135,7 +140,7 @@ export const AppBar = /*#__PURE__*/memo(function AppBar({
         onPress: leading.onPress,
         testID: testID === undefined ? undefined : `${testID}-leading`
       }) : null
-    }), /*#__PURE__*/_jsxs(Animated.View, {
+    }), /*#__PURE__*/_jsxs(Reanimated.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.

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

@@ -11,6 +11,7 @@
  * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
 
 /** Matches `Button`'s `MIN_TOUCH_TARGET` — each side slot reserves at least 44dp for icon actions. */
@@ -19,6 +20,7 @@ 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 { MIN_TOUCH_TARGET };
 export function resolveAppBarColors(colors) {
   return {
     background: colors.bg.surface,
@@ -39,8 +41,7 @@ export const appBarStructure = createThemedVariants(theme => ({
     alignItems: "center",
     paddingHorizontal: theme.space[2],
     paddingVertical: theme.space[2],
-    columnGap: theme.space[1],
-    borderBottomWidth: theme.borderWidths.thin
+    columnGap: theme.space[1]
   }
 }));
 export const appBarSideStructure = createThemedVariants(_theme => ({
@@ -69,4 +70,7 @@ export const appBarActionsRowStructure = createThemedVariants(theme => ({
     columnGap: theme.space[1]
   }
 }));
+
+/** Scroll distance over which a `scrollEffect="collapse*"` AppBar eases subtitle/padding. */
+export const APP_BAR_SCROLL_COLLAPSE_RANGE = 64;
 //# sourceMappingURL=AppBar.variants.js.map

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

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

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

@@ -23,7 +23,7 @@ ghost) driven by a closed `IconName` — never a consumer `ReactNode` slot.
 | `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. |
+| `trailing` | `AppBarAction \| readonly AppBarAction[]` | — | One or more trailing icon actions. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Forwarded to the outermost `View`. |
 

package/lib/module/modules/app-switcher/AppSwitcher.js

@@ -0,0 +1,30 @@
+"use strict";
+
+import { memo, useCallback } from "react";
+import { View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { ListItem } from "../list-item/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const AppSwitcher = /*#__PURE__*/memo(function AppSwitcher({
+  apps,
+  activeAppId,
+  onSelect,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const makePress = useCallback(id => () => onSelect(id), [onSelect]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: [{
+      gap: theme.space[1]
+    }, style],
+    children: apps.map(app => /*#__PURE__*/_jsx(ListItem, {
+      title: app.label,
+      subtitle: app.id === activeAppId ? "Current" : undefined,
+      onPress: makePress(app.id),
+      testID: testID ? `${testID}-${app.id}` : undefined
+    }, app.id))
+  });
+});
+//# sourceMappingURL=AppSwitcher.js.map

package/lib/module/modules/app-switcher/AppSwitcherProps.js

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

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

@@ -0,0 +1,14 @@
+# app-switcher/ — a suite picker list for switching between apps
+
+Suite picker list (no keyboard shortcuts). Subpath-only.
+
+## Exports
+
+- `AppSwitcher` — `apps`, `activeAppId`, `onSelect`, layout-only `style`, `testID`
+- `AppSwitcherApp` — `id`, `label`, `icon`
+
+Each app renders as a `ListItem` whose subtitle is `"Current"` for `activeAppId`.
+
+## Known gaps
+
+- `AppSwitcherApp.icon` is accepted and silently ignored — nothing renders it.

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

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

package/lib/module/modules/appearance-settings/AppearanceSettings.js

@@ -0,0 +1,58 @@
+"use strict";
+
+import { memo, useCallback, useMemo } from "react";
+import { View } from "react-native";
+import { themeNames } from "../../theme/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Chip, ChipGroup } from "../chip/index.js";
+import { SegmentedControl } from "../segmented-control/index.js";
+import { Text } from "../text/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const AppearanceSettings = /*#__PURE__*/memo(function AppearanceSettings({
+  brand,
+  mode,
+  onBrandChange,
+  onModeChange,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const modeOptions = useMemo(() => [{
+    value: "light",
+    label: "Light"
+  }, {
+    value: "dark",
+    label: "Dark"
+  }], []);
+  const handleMode = useCallback(value => onModeChange(value), [onModeChange]);
+  const handleBrand = useCallback(next => () => onBrandChange(next), [onBrandChange]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [{
+      gap: theme.space[4]
+    }, style],
+    children: [/*#__PURE__*/_jsxs(View, {
+      children: [/*#__PURE__*/_jsx(Text, {
+        variant: "body-sm",
+        children: "Colour mode"
+      }), /*#__PURE__*/_jsx(SegmentedControl, {
+        options: modeOptions,
+        value: mode,
+        onChange: handleMode
+      })]
+    }), /*#__PURE__*/_jsxs(View, {
+      children: [/*#__PURE__*/_jsx(Text, {
+        variant: "body-sm",
+        children: "Brand"
+      }), /*#__PURE__*/_jsx(ChipGroup, {
+        wrap: true,
+        children: themeNames.map(name => /*#__PURE__*/_jsx(Chip, {
+          label: name,
+          selected: brand === name,
+          onPress: handleBrand(name)
+        }, name))
+      })]
+    })]
+  });
+});
+//# sourceMappingURL=AppearanceSettings.js.map

package/lib/module/modules/appearance-settings/AppearanceSettingsProps.js

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

package/lib/module/modules/appearance-settings/MODULE.md

@@ -0,0 +1,9 @@
+# appearance-settings/ — a brand and light/dark mode picker
+
+Brand + light/dark picker for a settings screen: a `SegmentedControl` over `AppearanceColorMode`
+(`"light"` | `"dark"`) and a wrapping `ChipGroup` over `themeNames`.
+
+## Exports
+
+- `AppearanceSettings` — `brand`, `mode`, `onBrandChange`, `onModeChange`, layout-only `style`, `testID`
+- `AppearanceColorMode` — `"light" | "dark"`, not the theme's own `ThemeMode` (no `"system"` option here)

package/lib/module/modules/appearance-settings/index.js

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

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

@@ -19,6 +19,7 @@
 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";
@@ -71,7 +72,12 @@ export const Avatar = /*#__PURE__*/memo(function Avatar({
       numberOfLines: 1,
       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

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

@@ -18,8 +18,10 @@
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { resolveFilledAccent } from "../../theme/tokens/builders/accentText.js";
 import { createThemedVariants } from "../../core/style/index.js";
+export { MIN_TOUCH_TARGET };
 
 /** `circle` for a person, `rounded` for an organisation/product, `square` for tiles/thumbnails. */
 
@@ -153,7 +155,7 @@ export const avatarStructure = createThemedVariants(theme => ({
         borderRadius: theme.radii.full
       },
       rounded: {
-        borderRadius: theme.radii.base
+        borderRadius: theme.radii.lg
       },
       square: {
         borderRadius: theme.radii.none

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

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

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

@@ -10,7 +10,7 @@ which is exactly why its accessibility default is the one place it deliberately
 | File | Role |
 |------|------|
 | `Avatar.tsx` | The component. Fallback precedence (image → initials → placeholder), a11y wiring. |
-| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarIdentityColors`, `avatarIdentityRamp`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
+| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarIdentityColors`, `avatarIdentityRamp`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. Re-exports `MIN_TOUCH_TARGET` from `core/a11y/touchTarget` for tests only — this module is not interactive. No React. |
 | `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`, `AvatarShape`. |
 | `__tests__/Avatar.test.ts` | Pure: WCAG contrast for the neutral **and** every identity fill (all brands × modes) + the identity hash + the size scale + the a11y contract. |
 | `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, shape, identity fill, recycling key, decorative-vs-labelled a11y. |
@@ -20,7 +20,7 @@ which is exactly why its accessibility default is the one place it deliberately
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `size` | `xs \| sm \| md \| lg \| xl` | `md` | Diameters 24 / 32 / 40 / 56 / 72 dp. |
-| `shape` | `circle \| rounded` | `circle` | `rounded` (the brand `radii.base`) for an org/product; a person stays circular. |
+| `shape` | `circle \| rounded \| square` | `circle` | `circle` is `radii.full` (a person), `rounded` is `radii.lg` (an org/product), `square` is `radii.none` (a tile/thumbnail). |
 | `source` | `{ uri: string }` | — | A remote image. Wins over `initials` when present. |
 | `initials` | `string` | — | Shown when there is no `source`. Clipped to the first two characters. |
 | `identity` | `string` | — | Seeds a stable hashed fill for the initials/placeholder state. Absent → the neutral fill. |
@@ -72,7 +72,7 @@ fewer place to special-case the optional-peer fallback.
    contract is unit-tested by measuring real palettes — never eyeballed.
 3. **`radii.full` clips a circle for any diameter.** One token (a finite `9999`, not `Infinity` —
    RN rejects non-finite style values) covers every size instead of each variant computing its own
-   `box / 2`; `shape="rounded"` swaps it for `radii.base`.
+   `box / 2`; the other two shapes swap it for `radii.lg` / `radii.none`.
 4. **`style: LayoutStyle` last and once, no `{...rest}`** — internals never receive consumer style.
 
 ## Testing note — hidden elements and React Native Testing Library

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

@@ -5,15 +5,17 @@
  * `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).
+ * 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 { 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 { AVATAR_GROUP_DEFAULT_MAX, avatarGroupItemStructure, avatarGroupOverflowLabelStructure, avatarGroupOverflowStructure, avatarGroupStructure, resolveAvatarGroupColors, resolveAvatarGroupFaceFallbackLabel, resolveAvatarGroupOverflowAccessibility, 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,
@@ -27,6 +29,7 @@ export const AvatarGroup = /*#__PURE__*/memo(function AvatarGroup({
   const overlap = resolveAvatarGroupOverlap(size);
   const visibleCount = resolveAvatarGroupVisibleCount(avatars.length, max);
   const overflowCount = resolveAvatarGroupOverflowCount(avatars.length, visibleCount);
+  const overflowAccessibility = resolveAvatarGroupOverflowAccessibility(overflowCount);
   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, {
@@ -40,7 +43,7 @@ export const AvatarGroup = /*#__PURE__*/memo(function AvatarGroup({
       source: item.source,
       initials: item.initials,
       identity: item.identity,
-      accessibilityLabel: item.accessibilityLabel,
+      accessibilityLabel: item.accessibilityLabel ?? resolveAvatarGroupFaceFallbackLabel(index),
       testID: testID === undefined ? undefined : `${testID}-avatar-${index}`
     })
   }, `${item.source?.uri ?? item.initials ?? item.identity ?? "avatar"}-${index}`)), [visibleAvatars, theme, colors, overlap, size, testID]);
@@ -64,8 +67,9 @@ export const AvatarGroup = /*#__PURE__*/memo(function AvatarGroup({
     style: rootStyle,
     children: [faces, overflowCount > 0 ? /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-overflow`,
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no-hide-descendants",
+      accessible: overflowAccessibility.accessible,
+      accessibilityRole: overflowAccessibility.accessibilityRole,
+      accessibilityLabel: overflowAccessibility.accessibilityLabel,
       style: overflowStyle,
       children: /*#__PURE__*/_jsx(Text, {
         style: overflowLabelStyle,

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

@@ -37,6 +37,29 @@ export function resolveAvatarGroupVisibleCount(total, max) {
 export function resolveAvatarGroupOverflowCount(total, visible) {
   return Math.max(0, total - visible);
 }
+/**
+ * WCAG 2.5.3: the accessible name must CONTAIN the visible "+N" text (same contract as
+ * `MoreItems`'s trigger), so a voice-control user saying what they read still lands on this pill.
+ * `"text"`, not `"button"` — the pill is informational chrome, not interactive (same as `Badge`).
+ */
+export function resolveAvatarGroupOverflowAccessibility(count) {
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: `+${count} more`
+  };
+}
+
+/**
+ * A face's honest-but-generic name when its consumer never set `accessibilityLabel`. Unlike a
+ * standalone `Avatar` (usually sits beside a visible name, so undecorated is a fair default —
+ * see `resolveAvatarAccessibility`), a grouped face has no adjacent name: falling through to
+ * `Avatar`'s decorative default would leave a screen reader user unable to tell how many distinct
+ * people the stack represents.
+ */
+export function resolveAvatarGroupFaceFallbackLabel(index) {
+  return `Avatar ${index + 1}`;
+}
 export const avatarGroupStructure = createThemedVariants(_theme => ({
   base: {
     flexDirection: "row",

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

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

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

@@ -8,6 +8,7 @@ overflow pill when `avatars.length` exceeds `max`.
 | File | Role |
 |------|------|
 | `AvatarGroup.tsx` | The component. Composes `Avatar` + overflow pill; `style` last. |
+| `AvatarGroupProps.ts` | `AvatarGroupProps` + `AvatarGroupItem`, with the per-prop JSDoc consumers see on hover. |
 | `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. |
@@ -23,6 +24,22 @@ overflow pill when `avatars.length` exceeds `max`.
 | `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
 | `testID` | `string` | — | Forwarded to the outermost `View`; faces get `${testID}-avatar-{i}`. |
 
+## Accessibility
+
+- **Overflow pill** carries `accessible` + `accessibilityRole="text"` + an accessibility label
+  (`"+N more"`, containing the visible `"+N"` per WCAG 2.5.3, same contract as `MoreItems`) instead
+  of being hidden from assistive tech — a screen reader user now hears how many faces are hidden.
+- **Per-face labels** fall back to `resolveAvatarGroupFaceFallbackLabel` (`"Avatar {n}"`) when a
+  consumer doesn't set `AvatarGroupItem.accessibilityLabel` — a grouped face has no adjacent visible
+  name to lean on, unlike a standalone `Avatar`, so leaving it unlabeled would leave it silent.
+
+## Borders
+
+The `AVATAR_GROUP_RING_WIDTH` ring (`avatarGroupItemStructure`) is deliberately KEPT, unlike other
+modules' container hairlines: it is drawn in `colors.ring` (`bg.canvas`, not a visible stroke
+colour) purely to cut a gap between overlapping circular faces — a divider BETWEEN adjacent avatars,
+not decorative container chrome. Removing it would let overlapping faces visually merge.
+
 ## Performance
 
 Wrapped in `React.memo`. Visible slice is `useMemo`'d on `avatars` and `max`.

package/lib/module/modules/backdrop/Backdrop.js

@@ -0,0 +1,38 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import { withAlpha } from "../../core/gradient/index.js";
+import { MOTION_TRANSFORM } from "../../core/motion/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const SCRIM = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
+export const Backdrop = /*#__PURE__*/memo(function Backdrop({
+  visible = true,
+  onPress,
+  style,
+  testID
+}) {
+  const rootStyle = useMemo(() => [styles.fill, {
+    backgroundColor: SCRIM
+  }, style], [style]);
+  if (!visible) return null;
+  if (onPress) {
+    return /*#__PURE__*/_jsx(Pressable, {
+      accessibilityRole: "button",
+      accessibilityLabel: "Dismiss",
+      onPress: onPress,
+      style: rootStyle,
+      testID: testID
+    });
+  }
+  return /*#__PURE__*/_jsx(View, {
+    style: [rootStyle, {
+      pointerEvents: 'none'
+    }],
+    testID: testID
+  });
+});
+const styles = StyleSheet.create({
+  fill: StyleSheet.absoluteFill
+});
+//# sourceMappingURL=Backdrop.js.map

package/lib/module/modules/backdrop/BackdropProps.js

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

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

@@ -0,0 +1,11 @@
+# backdrop/ — a full-screen scrim for sheets and overlays
+
+Full-screen scrim using `MOTION_TRANSFORM.scrimOpacity`. Pairs with sheets and overlays; prefer this over hand-rolled `absoluteFill` + hex.
+
+## Exports
+
+- `Backdrop` — `visible` (default `true`; `false` renders nothing), `onPress`, layout-only `style`, `testID`
+
+With `onPress` it is a `Pressable` with `accessibilityRole="button"` and the label `"Dismiss"`;
+without it, a non-interactive `View` with `pointerEvents: "none"`. It never animates — enter/exit
+is the parent's mount/unmount.

package/lib/module/modules/backdrop/index.js

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

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

@@ -9,6 +9,7 @@
 import { memo } from "react";
 import { Text, View } from "react-native";
 import { Icon } from "../../core/icon/index.js";
+import { AccentGradientFill } from "../../core/gradient/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";
@@ -28,6 +29,7 @@ export const Badge = /*#__PURE__*/memo(function Badge({
   const a11y = resolveBadgeAccessibility({
     label
   });
+  const useGradient = tone === "accent";
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
     accessible: a11y.accessible,
@@ -36,19 +38,23 @@ export const Badge = /*#__PURE__*/memo(function Badge({
     style: [badgeStructure(theme, {
       size
     }), {
-      backgroundColor: toneColors.fill,
-      borderColor: toneColors.border
+      borderColor: toneColors.border,
+      overflow: "hidden"
+    }, !useGradient && {
+      backgroundColor: toneColors.fill
     }, style],
-    children: [icon && /*#__PURE__*/_jsx(Icon, {
+    children: [useGradient && /*#__PURE__*/_jsx(AccentGradientFill, {
+      color: theme.colors.accent.solid
+    }), icon && /*#__PURE__*/_jsx(Icon, {
       name: icon,
       size: spec.iconSize,
-      color: toneColors.text,
+      color: useGradient ? theme.colors.accent.onSolid : toneColors.text,
       strokeWidth: ICON_STROKE
     }), /*#__PURE__*/_jsx(Text, {
       numberOfLines: 1,
       style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
         fontSize: spec.fontSize,
-        color: toneColors.text
+        color: useGradient ? theme.colors.accent.onSolid : toneColors.text
       }],
       children: label
     })]

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

@@ -112,7 +112,8 @@ export const badgeStructure = createThemedVariants(theme => ({
     alignItems: "center",
     justifyContent: "center",
     columnGap: theme.space[1],
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     borderWidth: theme.borderWidths.thin
   },
   variants: {

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

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