@mrmeg/expo-ui 0.17.0 → 0.20.0

package/CHANGELOG.md

@@ -3,6 +3,152 @@
 All notable changes to `@mrmeg/expo-ui` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0]
+
+### Added
+
+- **`surfaceSunken` semantic token.** The app-chrome tier below `background`,
+  so sidebars, rails, and side panels read as a layer *beneath* the content
+  pane instead of the same surface. Dark `#050506` (below zinc-950), light
+  `#FAFAFA` (zinc-50). Elevation is now a surface-tier ladder rather than a
+  shadow scale: `surfaceSunken` < `background` < `card`/`popover` < `muted`.
+
+- **`borderStrong` semantic token.** A hairline for elements sitting on a
+  filled surface — chips on `muted`, raised panels — one visible step above
+  the fill, where `border` shares `muted`'s hex and disappears. Dark
+  `#3F3F46` (zinc-700), light `#D4D4D8` (zinc-300). `border` stays the
+  hairline for elements on `background`/`card`.
+
+- **SSR theme seeding (`SsrThemeSeedContext`).** On a server-rendered web app,
+  `useTheme`/`useStyles` had no way to know the visitor's theme during the
+  server render, so every SSR page shipped a fully light-themed tree that
+  recolored after hydration. The store can't carry a per-request value — it's a
+  module singleton shared by concurrent SSR requests — so the new
+  `SsrThemeSeedContext` (with `SsrThemeSeed`, `SSR_THEME_SEED_DEFAULT`, and
+  `useSsrThemeSeed`) is the per-request channel. Provide it from a signal the
+  server and browser read identically (a cookie), and `useTheme` resolves from
+  it on web until persistence has loaded.
+
+  `SSR_THEME_SEED_DEFAULT` is `system`/light, i.e. what the store boots with —
+  so a host that receives no signal renders exactly as it did before the seed
+  existed. Note that this default is a *fallback*, not a reading: a host that
+  also writes the resolved scheme into its served HTML (`<html data-theme>`, a
+  blocking script's early-return, a `prefers-color-scheme` CSS fallback) must
+  distinguish "seed came from the visitor" from "seed is the default" and skip
+  the write in the latter case, or it will pin a dark-OS first-time visitor to
+  light with its own failsafes disabled.
+
+- **`user-theme-preference` cookie mirror.** On web, `setTheme` now dual-writes
+  `localStorage` **and** a `user-theme-preference` cookie (`path=/;
+  max-age≈1y; SameSite=Lax`, exported as `THEME_COOKIE_NAME`), and `loadTheme`
+  backfills/repairs it from `localStorage`, so a server-rendered host can read
+  the visitor's theme off the request. `localStorage` remains the source of
+  truth; the cookie is a render hint only. Native persistence is unchanged.
+
+- **`hasLoadedTheme` on the theme store.** False until `loadTheme()` has read
+  persistence (or `setTheme` was called). While it's false on web, `useTheme`
+  resolves from the SSR seed instead of store state; after that, store state
+  wins for good. Mirrors the `hasLoadedOnboarding` pattern.
+
+### Changed
+
+- **Dim text is more readable in both schemes (visual change).**
+  `textDim`/`mutedForeground` moved from `#A1A1AA` → `#B0B0B8` in dark
+  (~9.2:1 on `background`, ~6.9:1 on `muted`, up from ~7.8:1/~5.9:1) and from
+  zinc-500 `#71717A` → zinc-600 `#52525B` in light (~7.7:1 on white, up from
+  ~4.8:1). Captions, timestamps, meta rows, and neutral `StatCard` changes all
+  render a step brighter (dark) or darker (light) than before; both stay
+  clearly dimmer than `text`, so hierarchy is preserved. A new package test
+  enforces the floors (≥7:1 on `background`/`card`/`popover`, ≥6:1 on
+  `muted`/`secondary`), so these tokens cannot be dimmed back down silently.
+  Apps that hardcoded the old hexes, or asserted them in tests, need to update
+  those literals; apps using the tokens get the change for free.
+
+- **`Drawer` chrome paints `surfaceSunken`.** Both the overlay drawer panel and
+  the in-flow rail switched from `background` to `surfaceSunken`, so navigation
+  chrome is visibly darker than the content it sits beside (dark) or a faint
+  step off white (light). Override via the existing `style` props, or re-skin
+  `surfaceSunken` through `setColors`/`ThemeColorScope`, to restore the old
+  flat look.
+
+- **`syncThemeFromEnvironment()` starts the OS listener before reading
+  persistence.** `loadTheme()` is what flips `hasLoadedTheme` (the moment web
+  renders stop trusting the SSR seed), so the real OS scheme is now read first
+  and a `system` user never sees a frame of the boot-default light.
+
+## [0.19.0]
+
+### Added
+
+- **`Avatar` and `AvatarGroup`.** The package had `SkeletonAvatar` (a loading
+  placeholder) but no real avatar, so consumers hand-rolled circles. `Avatar`
+  renders an image with a graceful fallback chain — image → initials → icon —
+  and downgrades to initials at runtime when the image fails to load, so a
+  dead URL never leaves an empty hole. Accepts `source`, `name` (supplies 1–2
+  initials and the default accessibility label), `icon` (Feather, defaults to
+  `user`), `size` (`"sm" | "md" | "lg"` = 32/40/48, or an explicit pixel
+  diameter), and `shape` (`"circle" | "square"`). Initials derivation is
+  grapheme-aware: a decomposed accented character keeps its mark and an emoji
+  is not sliced into a lone surrogate.
+
+  `AvatarGroup` stacks children with a ring in the theme `background` color so
+  the stack reads on any surface, collapses anything past `max` into a `+N`
+  tile, propagates its `size` and `shape` to children that don't set their own,
+  and announces the total count (including the collapsed overflow) to screen
+  readers.
+
+  Uses React Native's own `Image`, so there is no new peer dependency.
+
+- **`Carousel` — horizontally snapping slide row with dot indicators.**
+  Children-based: each child becomes one slide at the resolved item width.
+
+  ```tsx
+  <Carousel itemWidth={0.8} onIndexChange={setPage}>
+    {testimonials.map((t) => (
+      <Card key={t.name}>
+        <BodyText>{t.quote}</BodyText>
+      </Card>
+    ))}
+  </Carousel>
+  ```
+
+  `itemWidth` (default `0.85`) is a fraction of the carousel's own width when
+  `<= 1` — leaving the next slide peeking — and absolute pixels when `> 1`.
+  `gap`, `contentPadding`, `showDots`, `initialIndex`, `onIndexChange`, and
+  `snap` cover the rest; dots are plain themed views (active uses `accent`)
+  and auto-hide for a single slide. `onIndexChange` fires once per settle.
+
+  Built on `ScrollView`, not a virtualized list, so every slide is in the
+  server-rendered tree — web SSR ships the real slide content instead of an
+  empty scroller that fills in after measurement. No animation library is
+  involved: native snapping uses `snapToInterval`, and because
+  react-native-web drops that prop, web gets equivalent CSS scroll-snap
+  (`scroll-snap-type`/`scroll-snap-align` plus a `scroll-padding-left` that
+  keeps page `i` at `i * (itemWidth + gap)` on both platforms). Wheel and
+  trackpad scrolling keep the dots live via throttled scroll ticks, since RNW
+  emits no momentum events.
+
+  Accessibility: the dot row is a `tablist` of `tab`s carrying
+  `selected` state and per-slide labels, plus a visually clipped
+  `aria-live="polite"` "N of M" page announcement.
+
+  `getCarouselIndex(offsetX, interval, count)` and
+  `resolveCarouselItemWidth(itemWidth, containerWidth)` are exported for hosts
+  building custom controls on the same math.
+
+## [0.18.0]
+
+### Added
+
+- **`BottomSheet.Content` `backgroundStyle` pass-through.** The native sheet
+  surface (web vaul panel, Android `containerColor`, iOS
+  `presentationBackground`) previously hardcoded the themed card color.
+  `BottomSheet.Content` now accepts an optional `backgroundStyle` merged over
+  that default, so hosts can pass `{ backgroundColor: "transparent" }` to let
+  custom chrome (e.g. a Liquid Glass backdrop) show through. Omitting the prop
+  preserves the existing card background. The RN content column still paints
+  its own card fill; clear that via `style` when going transparent.
+
 ## [0.17.0]
 
 ### Added

package/LLM_USAGE.md

@@ -76,6 +76,11 @@ On native, `BottomSheet.Content` avoids the soft keyboard by default with
 React Native keyboard events. Pass `avoidKeyboard={false}` to opt out for a
 specific sheet.
 
+`BottomSheet.Content` themes the native sheet surface with the card color.
+Pass `backgroundStyle={{ backgroundColor: "transparent" }}` (with a `style`
+that clears the content column's card fill) when custom chrome such as a
+glass backdrop should show through; omitting it keeps the card background.
+
 i18n is optional. Do not add app-level i18n setup just to use this package.
 Plain children and `text` props work without `i18next` or `react-i18next`.
 `tx` props render fallback text when provided and otherwise render the key
@@ -102,11 +107,13 @@ configureExpoUiI18n((key, options) => i18n.t(key, options));
 Useful theme tokens include:
 
 ```tsx
+theme.colors.surfaceSunken;
 theme.colors.background;
 theme.colors.foreground;
 theme.colors.card;
 theme.colors.popover;
 theme.colors.border;
+theme.colors.borderStrong;
 theme.colors.input;
 theme.colors.ring;
 theme.colors.primary;
@@ -126,6 +133,13 @@ Token intent:
 - `input`: form-control border color
 - `ring`: focus outline color
 - `popover`: elevated overlay surface
+- `surfaceSunken`: app-chrome surface one tier below `background`
+- `borderStrong`: hairline for elements on filled surfaces, where `border` would blend in
+
+Elevation is a surface-tier ladder, not shadow depth:
+`surfaceSunken` (chrome) < `background` (content) < `card`/`popover` (raised)
+< `muted` (chips, insets). Border a raised or filled element with
+`borderStrong`; `border` is for hairlines on `background`/`card`.
 
 Use `getShadowStyle()` for package surfaces that need elevation. It supports
 `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`,
@@ -182,10 +196,12 @@ Use this table before creating a new app-local primitive.
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections |
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Avatar`, `AvatarGroup` | Profile images with initials/icon fallback | Hand-rolled circles with a nested `Image` and initials `Text` | Account menu, comment authors, assignee pickers, overlapping team stacks |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
 | `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries |
+| `Carousel` | Horizontally snapping slide rows with dot indicators | Hand-rolled snap `ScrollView` plus manual offset math | Testimonial strips, onboarding pages, feature highlights, image galleries |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters |
 | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text |
 | `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user |
@@ -222,8 +238,10 @@ Use this table before creating a new app-local primitive.
 - Use `RadioGroup` for small mutually exclusive choices and `Select` for longer option sets.
 - Use `Dialog` for blocking decisions, `Popover` for contextual controls, `Tooltip` for short explanations, and `DropdownMenu` for action lists.
 - Use `Card` for individual repeated or framed items, not as a wrapper around full page sections.
+- Use `Carousel` for a horizontal snap row of a known, small set of slides. It renders every child (no virtualization), so slides survive server rendering; reach for `FlatList` when the data set is large or unbounded.
 - Use `EmptyState` for no-data or recoverable error regions.
 - Use `Skeleton` for loading content with stable layout.
+- Use `Avatar` with both `source` and `name` whenever both exist: `name` supplies the initials shown when the image is absent or fails, plus the default accessibility label. Never hand-roll a circle with a nested `Image` and initials `Text`. Inside `AvatarGroup`, set `size`/`shape` on the group — children inherit them and gain the ring.
 - Use `Progress` for real progress or indeterminate long-running work.
 - Use `Drawer.Header` with `icon`, `title`, and `action` for a compact app-brand row; place `Drawer.ToggleCollapse` in `action` for a trailing rail control.
 

package/README.md

@@ -101,7 +101,9 @@ const styles = StyleSheet.create({
 });
 ```
 
-`useTheme()` returns the active `theme`, resolved `scheme`, persisted `currentTheme`, `setTheme`, `toggleTheme`, cross-platform shadow helpers, a web focus-ring helper, contrast helpers, and `withAlpha`. `getShadowStyle(type)` supports `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`, `cardHover`, and `cardSubtle`. Use semantic tokens such as `theme.colors.background`, `foreground`, `card`, `popover`, `border`, `input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`, `destructive`, `success`, and `warning`. `primary` is the neutral action color, `secondary` is a neutral secondary surface, `accent` is the teal highlight color, `input` is the default form-control border, and `ring` is the focus outline color.
+`useTheme()` returns the active `theme`, resolved `scheme`, persisted `currentTheme`, `setTheme`, `toggleTheme`, cross-platform shadow helpers, a web focus-ring helper, contrast helpers, and `withAlpha`. `getShadowStyle(type)` supports `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`, `cardHover`, and `cardSubtle`. Use semantic tokens such as `theme.colors.surfaceSunken`, `background`, `foreground`, `card`, `popover`, `border`, `borderStrong`, `input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`, `destructive`, `success`, and `warning`. `primary` is the neutral action color, `secondary` is a neutral secondary surface, `accent` is the teal highlight color, `input` is the default form-control border, and `ring` is the focus outline color.
+
+Surfaces are layered tiers rather than shadow depths: `surfaceSunken` (app chrome, e.g. the Drawer rail) sits below `background` (content), which sits below `card`/`popover` (raised panels), which sit below `muted` (chips and insets). `border` is the hairline for elements on `background`/`card`; use `borderStrong` when the element sits on a filled surface, where `border` would blend into the fill. `textDim`/`mutedForeground` are tuned for readability — at least 7:1 against `background`/`card` and 6:1 against `muted` in both schemes — and a package test enforces those floors.
 
 When `currentTheme` is `"system"`, the package tracks the OS color scheme and
 updates all `useTheme()` and `useStyles()` consumers through the package theme
@@ -295,10 +297,12 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | Multi-section disclosure | Custom FAQ/settings expanders | FAQ lists, grouped settings, help sections, dense detail pages |
 | `Alert` | Cross-platform imperative alerts | Direct `window.alert` or duplicated RN/web branching | Confirm destructive actions, native alert dialogs, simple blocking messages |
 | `AnimatedView` | Entrance and visibility animation | Hand-rolled one-off Animated wrappers | Staggered list rows, revealed panels, animated empty states |
+| `Avatar`, `AvatarGroup` | Profile images with initials/icon fallback | Hand-rolled circles with a nested `Image` and initials `Text` | Account menu, comment authors, assignee pickers, testimonial cards, overlapping team/collaborator stacks |
 | `Badge` | Short status labels | Custom pill `View` + `Text` | Draft/active states, counts, plan labels, role tags |
 | `BottomSheet` | Mobile-first modal sheets | Custom absolute-position sheets | Action pickers, mobile filters, keyboard-aware quick edit forms, contextual details |
 | `Button` | Commands and CTAs | Pressable plus custom text styling | Submit, save, cancel, delete, navigation CTAs, icon-accessory buttons; loading state preserves resting width |
 | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Framed content groups | Ad hoc bordered panels | List items, pricing plans, settings sections, summaries, dashboards |
+| `Carousel` | Horizontally snapping slide rows with dot indicators | Hand-rolled snap `ScrollView` plus manual offset math | Testimonial strips, onboarding pages, feature highlights, image galleries; `itemWidth` below 1 is a fraction of the carousel width so the next slide peeks |
 | `Checkbox` | Boolean selection | Custom checkmark controls | Terms consent, checklist items, multi-select filters, notification opt-ins |
 | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | One-off disclosure | Local animated height wrappers | Advanced settings, hidden helper text, optional details |
 | `Dialog`, `AlertDialog` | Modal decisions and custom modal content | Custom modal overlays | Confirm delete, edit profile, invite user, blocking warnings |
@@ -374,12 +378,14 @@ Use `StyledText` or its aliases instead of raw `Text` whenever the text is part
 />
 ```
 
-Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. On native, `UIProvider` also wraps app content in the package keyboard-avoiding root by default, so ordinary screens and fixed footers stay above the soft keyboard without repeated app-local wrappers; pass `keyboardAvoiding={false}` to opt out, or use `KeyboardAvoidingView` directly for a subtree with custom behavior. Web skips the root keyboard wrapper unless `keyboardAvoiding` is explicitly enabled. `BottomSheet.Content` listens to React Native keyboard events when `avoidKeyboard` is enabled; it defaults to `true` and can be disabled per sheet. Trigger transient feedback with `notify`.
+Mount `UIProvider` once near the root before using `Dialog`, `AlertDialog`, `BottomSheet`, `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, or package notifications. On native, `UIProvider` also wraps app content in the package keyboard-avoiding root by default, so ordinary screens and fixed footers stay above the soft keyboard without repeated app-local wrappers; pass `keyboardAvoiding={false}` to opt out, or use `KeyboardAvoidingView` directly for a subtree with custom behavior. Web skips the root keyboard wrapper unless `keyboardAvoiding` is explicitly enabled. `BottomSheet.Content` listens to React Native keyboard events when `avoidKeyboard` is enabled; it defaults to `true` and can be disabled per sheet. `BottomSheet.Content` also accepts `backgroundStyle`, merged over the themed card default on the native sheet surface (web panel, Android `containerColor`, iOS `presentationBackground`) — pass `{ backgroundColor: "transparent" }`, plus a `style` clearing the content column's card fill, to let custom chrome like a glass backdrop show through. Trigger transient feedback with `notify`.
 
 Use `Skeleton` components for loading content with stable dimensions, `EmptyState` for no-data/recoverable errors, `Alert` for blocking confirm/alert dialogs, and `Notification` for transient global feedback.
 
 Use `Toggle` for one pressed state, `ToggleGroup` for a related set of pressed states, `Switch` for binary settings, `RadioGroup` for small mutually exclusive choices, and `Select` for longer option sets.
 
+Pass `Avatar` both a `source` and a `name` whenever you have them: `name` supplies the initials shown while the image is missing or after it fails, and the default accessibility label. `SkeletonAvatar` is the loading placeholder, not a substitute. Inside `AvatarGroup`, child avatars inherit the group's `size` and `shape` and gain the ring, so set those on the group rather than per child.
+
 ### Quick Examples
 
 Card, badge, and CTA:

package/dist/components/Avatar.d.ts

@@ -0,0 +1,80 @@
+import React from "react";
+import { type ImageSourcePropType, type StyleProp, type ViewStyle } from "react-native";
+import { type IconName } from "./Icon";
+/** Named size tokens, or an explicit pixel diameter. */
+export type AvatarSize = "sm" | "md" | "lg" | number;
+export type AvatarShape = "circle" | "square";
+/**
+ * Derive 1–2 initials from a display name.
+ *
+ * First + last word (middle names are skipped, as in most avatar stacks), one
+ * initial for a single-word name, and `""` when there is nothing to derive —
+ * callers treat that as "fall through to the icon".
+ *
+ * Grapheme-aware by way of `Array.from`, so an accented character written as
+ * base + combining mark keeps its accent and an astral code point (emoji) is
+ * not sliced into a lone surrogate. `toLocaleUpperCase` is deliberate: a
+ * locale-sensitive uppercase is right for names.
+ */
+export declare function getAvatarInitials(name?: string): string;
+export interface AvatarProps {
+    /** Image to display. Falls back to initials (then the icon) if it fails to load. */
+    source?: ImageSourcePropType;
+    /** Display name; supplies the fallback initials and the default accessibility label. */
+    name?: string;
+    /** Feather icon rendered when there is no image and no derivable initials. @default "user" */
+    icon?: IconName;
+    /** Size token or explicit pixel diameter. Inherited from `AvatarGroup` when unset. @default "md" */
+    size?: AvatarSize;
+    /** Inherited from `AvatarGroup` when unset. @default "circle" */
+    shape?: AvatarShape;
+    /**
+     * Accessibility label. Defaults to `name`; when neither is set the avatar is
+     * decorative and stays out of the accessibility tree.
+     */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Avatar Component
+ *
+ * A circular (or rounded-square) profile image with a graceful fallback chain:
+ * image → initials → icon. A broken or slow-failing image downgrades to
+ * initials at runtime, so a dead URL never leaves an empty hole.
+ *
+ * Usage:
+ * ```tsx
+ * <Avatar source={{ uri: user.avatarUrl }} name={user.fullName} />
+ * <Avatar name="Ada Lovelace" size="lg" />
+ * <Avatar icon="camera" shape="square" />
+ * ```
+ */
+declare function Avatar({ source, name, icon, size, shape, accessibilityLabel, style: styleOverride, }: AvatarProps): React.JSX.Element;
+export interface AvatarGroupProps {
+    children?: React.ReactNode;
+    /** Maximum number of avatars to render; the rest collapse into a `+N` tile. */
+    max?: number;
+    /** Size applied to child avatars that don't set their own. @default "md" */
+    size?: AvatarSize;
+    /** Shape applied to child avatars that don't set their own. @default "circle" */
+    shape?: AvatarShape;
+    /** Defaults to `"<n> avatars"`, counting the collapsed overflow. */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * AvatarGroup Component
+ *
+ * Overlapping stack of avatars, each ringed in the theme `background` color so
+ * the stack reads on any surface. Earlier avatars sit on top; anything past
+ * `max` collapses into a `+N` tile.
+ *
+ * Usage:
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   {members.map((m) => <Avatar key={m.id} source={{ uri: m.avatarUrl }} name={m.name} />)}
+ * </AvatarGroup>
+ * ```
+ */
+declare function AvatarGroup({ children, max, size, shape, accessibilityLabel, style: styleOverride, }: AvatarGroupProps): React.JSX.Element;
+export { Avatar, AvatarGroup };

package/dist/components/Avatar.js

@@ -0,0 +1,234 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { use, useState } from "react";
+import { Image, StyleSheet, View, } from "react-native";
+import { useTheme } from "../hooks/useTheme.js";
+import { spacing } from "../constants/spacing.js";
+import { Icon } from "./Icon.js";
+import { StyledText } from "./StyledText.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
+const SIZE_TOKENS = {
+    sm: spacing.iconLg, // 32
+    md: spacing.iconLg + spacing.sm, // 40
+    lg: spacing.iconXl, // 48
+};
+function isSizeToken(size) {
+    return typeof size === "string";
+}
+function resolveSize(size) {
+    return isSizeToken(size) ? SIZE_TOKENS[size] : size;
+}
+/** Rounded-square radius scales with the avatar so 32px and 88px read the same. */
+function squareRadius(px) {
+    return Math.round(px / 4);
+}
+/** Initials/icon scale with the avatar rather than jumping between text tokens. */
+function contentSize(px) {
+    return { fontSize: Math.round(px * 0.4), iconSize: Math.round(px * 0.5) };
+}
+/** Overlap for stacked avatars — 30% keeps ~70% of each face visible. */
+function overlap(px) {
+    return -Math.round(px * 0.3);
+}
+/**
+ * Derive 1–2 initials from a display name.
+ *
+ * First + last word (middle names are skipped, as in most avatar stacks), one
+ * initial for a single-word name, and `""` when there is nothing to derive —
+ * callers treat that as "fall through to the icon".
+ *
+ * Grapheme-aware by way of `Array.from`, so an accented character written as
+ * base + combining mark keeps its accent and an astral code point (emoji) is
+ * not sliced into a lone surrogate. `toLocaleUpperCase` is deliberate: a
+ * locale-sensitive uppercase is right for names.
+ */
+export function getAvatarInitials(name) {
+    if (!name)
+        return "";
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return "";
+    const picked = words.length === 1 ? [words[0]] : [words[0], words[words.length - 1]];
+    return picked
+        .map((word) => {
+        const [first] = Array.from(word.normalize("NFC"));
+        return first ?? "";
+    })
+        .join("")
+        .toLocaleUpperCase();
+}
+/**
+ * Identity of an image source by content, not object identity.
+ *
+ * `source={{ uri }}` allocates a new object on every render, so a failure
+ * flag keyed on object identity would reset immediately and loop
+ * image → error → image. Returns `null` when there is no usable image.
+ */
+function getSourceKey(source) {
+    if (source == null)
+        return null;
+    if (typeof source === "number")
+        return `asset:${source}`;
+    if (Array.isArray(source)) {
+        const key = source.map((entry) => entry?.uri ?? "").filter(Boolean).join("|");
+        return key || null;
+    }
+    return source.uri || null;
+}
+const AvatarGroupContext = React.createContext(null);
+/**
+ * Avatar Component
+ *
+ * A circular (or rounded-square) profile image with a graceful fallback chain:
+ * image → initials → icon. A broken or slow-failing image downgrades to
+ * initials at runtime, so a dead URL never leaves an empty hole.
+ *
+ * Usage:
+ * ```tsx
+ * <Avatar source={{ uri: user.avatarUrl }} name={user.fullName} />
+ * <Avatar name="Ada Lovelace" size="lg" />
+ * <Avatar icon="camera" shape="square" />
+ * ```
+ */
+function Avatar({ source, name, icon, size, shape, accessibilityLabel, style: styleOverride, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const group = use(AvatarGroupContext);
+    const px = resolveSize(size ?? group?.size ?? "md");
+    const resolvedShape = shape ?? group?.shape ?? "circle";
+    const sourceKey = getSourceKey(source);
+    // Keyed on the source's content, so a retry with a new URL clears the
+    // failure while a re-rendered identical URL keeps it.
+    const [failedKey, setFailedKey] = useState(null);
+    const showImage = sourceKey !== null && failedKey !== sourceKey;
+    const initials = getAvatarInitials(name);
+    const label = accessibilityLabel ?? name;
+    return (_jsx(AvatarSurface, { px: px, shape: resolvedShape, ring: group?.ring ?? false, accessibilityLabel: label, style: [styles.fallback, styleOverride], children: showImage ? (_jsx(Image, { source: source, resizeMode: "cover", style: geometry.image, onError: () => setFailedKey(sourceKey) })) : initials ? (_jsx(AvatarLabel, { px: px, style: styles.fallbackText, children: initials })) : (_jsx(Icon, { name: icon ?? "user", size: contentSize(px).iconSize, color: "mutedForeground", decorative: true })) }));
+}
+/**
+ * Shared chrome for an avatar-shaped tile — used by `Avatar` and by
+ * `AvatarGroup`'s `+N` overflow tile so both stay the same size, shape, and
+ * ring without duplicating the geometry rules.
+ */
+function AvatarSurface({ px, shape, ring, accessibilityLabel, style, children, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const token = SIZE_TOKEN_FOR_PX[px];
+    return (_jsx(View
+    // Only join the accessibility tree when there is something to announce;
+    // an unlabeled avatar is decorative next to the name it sits beside.
+    , { 
+        // Only join the accessibility tree when there is something to announce;
+        // an unlabeled avatar is decorative next to the name it sits beside.
+        accessible: accessibilityLabel ? true : undefined, 
+        // RN's role name is "image"; RNW maps it to aria-role "img" on the web.
+        accessibilityRole: accessibilityLabel ? "image" : undefined, accessibilityLabel: accessibilityLabel, style: [
+            geometry.base,
+            // Token sizes hit a pre-registered rule; a custom pixel size falls back
+            // to an inline style (which always ships in the SSR HTML).
+            token
+                ? geometry[shape === "circle" ? `${token}Circle` : `${token}Square`]
+                : { width: px, height: px, borderRadius: shape === "circle" ? spacing.radiusFull : squareRadius(px) },
+            ring && geometry.ring,
+            ring && styles.ring,
+            style,
+        ], children: children }));
+}
+function AvatarLabel({ px, style, children, }) {
+    return (_jsx(StyledText, { accessible: false, selectable: false, fontWeight: "semibold", style: [geometry.labelText, { fontSize: contentSize(px).fontSize }, style], children: children }));
+}
+/**
+ * AvatarGroup Component
+ *
+ * Overlapping stack of avatars, each ringed in the theme `background` color so
+ * the stack reads on any surface. Earlier avatars sit on top; anything past
+ * `max` collapses into a `+N` tile.
+ *
+ * Usage:
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   {members.map((m) => <Avatar key={m.id} source={{ uri: m.avatarUrl }} name={m.name} />)}
+ * </AvatarGroup>
+ * ```
+ */
+function AvatarGroup({ children, max, size = "md", shape = "circle", accessibilityLabel, style: styleOverride, }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    // toArray drops null/undefined/false children so a conditionally rendered
+    // avatar doesn't inflate the count or the overflow tally.
+    const items = React.Children.toArray(children);
+    const visible = max != null && max >= 0 ? items.slice(0, max) : items;
+    const overflowCount = items.length - visible.length;
+    const px = resolveSize(size);
+    const token = SIZE_TOKEN_FOR_PX[px];
+    const stackStyle = token ? geometry[`${token}Stack`] : { marginLeft: overlap(px) };
+    const totalTiles = visible.length + (overflowCount > 0 ? 1 : 0);
+    const contextValue = React.useMemo(() => ({ size, shape, ring: true }), [size, shape]);
+    return (_jsx(View, { accessible: true, accessibilityRole: "image", accessibilityLabel: accessibilityLabel ?? `${items.length} avatars`, style: [geometry.group, styleOverride], children: _jsxs(AvatarGroupContext.Provider, { value: contextValue, children: [visible.map((child, index) => (_jsx(View
+                // toArray assigns every child a stable key, so reordering the list
+                // moves the wrapper with its avatar instead of remounting both.
+                , { 
+                    // Earlier avatars paint over later ones, so the stack reads
+                    // left-to-right instead of the DOM's later-wins order.
+                    style: [index > 0 && stackStyle, { zIndex: totalTiles - index }], children: child }, React.isValidElement(child) ? child.key : index))), overflowCount > 0 ? (_jsx(View, { style: [visible.length > 0 && stackStyle, { zIndex: 0 }], children: _jsx(AvatarSurface, { px: px, shape: shape, ring: true, style: styles.overflow, children: _jsx(AvatarLabel, { px: px, style: styles.overflowText, children: `+${overflowCount}` }) }) })) : null] }) }));
+}
+/** px → token, so a size passed as a raw number still hits the registered rules. */
+const SIZE_TOKEN_FOR_PX = {
+    [SIZE_TOKENS.sm]: "sm",
+    [SIZE_TOKENS.md]: "md",
+    [SIZE_TOKENS.lg]: "lg",
+};
+// Geometry carries no theme values, so a plain module-scope sheet is enough to
+// get these rules into the server-rendered <head>. Only colors go through
+// createThemedStyles below. See docs/ssr-hydration.md.
+const geometry = StyleSheet.create({
+    base: {
+        alignItems: "center",
+        justifyContent: "center",
+        overflow: "hidden",
+    },
+    image: {
+        width: "100%",
+        height: "100%",
+    },
+    labelText: {
+        // The tile is the touch/visual target; text must not add its own metrics.
+        includeFontPadding: false,
+        textAlign: "center",
+        userSelect: "none",
+    },
+    ring: {
+        borderWidth: spacing.xxs,
+    },
+    group: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+    smCircle: { width: SIZE_TOKENS.sm, height: SIZE_TOKENS.sm, borderRadius: spacing.radiusFull },
+    mdCircle: { width: SIZE_TOKENS.md, height: SIZE_TOKENS.md, borderRadius: spacing.radiusFull },
+    lgCircle: { width: SIZE_TOKENS.lg, height: SIZE_TOKENS.lg, borderRadius: spacing.radiusFull },
+    smSquare: { width: SIZE_TOKENS.sm, height: SIZE_TOKENS.sm, borderRadius: squareRadius(SIZE_TOKENS.sm) },
+    mdSquare: { width: SIZE_TOKENS.md, height: SIZE_TOKENS.md, borderRadius: squareRadius(SIZE_TOKENS.md) },
+    lgSquare: { width: SIZE_TOKENS.lg, height: SIZE_TOKENS.lg, borderRadius: squareRadius(SIZE_TOKENS.lg) },
+    smStack: { marginLeft: overlap(SIZE_TOKENS.sm) },
+    mdStack: { marginLeft: overlap(SIZE_TOKENS.md) },
+    lgStack: { marginLeft: overlap(SIZE_TOKENS.lg) },
+});
+const createStyles = (theme) => StyleSheet.create({
+    fallback: {
+        backgroundColor: theme.colors.muted,
+    },
+    fallbackText: {
+        color: theme.colors.mutedForeground,
+    },
+    ring: {
+        borderColor: theme.colors.background,
+    },
+    overflow: {
+        backgroundColor: theme.colors.accent,
+    },
+    overflowText: {
+        color: theme.colors.accentForeground,
+    },
+});
+const themedStyles = createThemedStyles(createStyles);
+export { Avatar, AvatarGroup };

package/dist/components/BottomSheet.d.ts

@@ -117,6 +117,14 @@ interface BottomSheetContentProps extends ViewProps {
     avoidKeyboard?: boolean;
     /** Accepted for call-site ergonomics; ignored (platform owns keyboard). */
     dismissKeyboardOnDrag?: boolean;
+    /**
+     * Style for the native sheet surface behind the RN content — the web (vaul)
+     * panel, Android `containerColor`, iOS `presentationBackground`. Merged over
+     * the themed card default, so `{ backgroundColor: "transparent" }` lets a
+     * custom chrome (e.g. a glass backdrop) show through. The RN content column
+     * paints its own card fill too; clear that via `style`.
+     */
+    backgroundStyle?: StyleProp<ViewStyle>;
     style?: StyleProp<ViewStyle>;
     children: React.ReactNode;
 }
@@ -140,7 +148,7 @@ interface BottomSheetCloseProps {
 declare function useBottomSheetContext(): BottomSheetContextValue;
 declare function BottomSheetRoot({ open: controlledOpen, onOpenChange: controlledOnOpenChange, defaultOpen, snapPoints, closeOnBackdropPress, children, }: BottomSheetProps): React.JSX.Element;
 declare function BottomSheetTrigger({ asChild, children, style: styleOverride }: BottomSheetTriggerProps): React.JSX.Element;
-declare function BottomSheetContent({ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, style: styleOverride, children, }: BottomSheetContentProps): React.JSX.Element;
+declare function BottomSheetContent({ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, children, }: BottomSheetContentProps): React.JSX.Element;
 declare function BottomSheetHandle({ style }: BottomSheetHandleProps): React.JSX.Element;
 declare function BottomSheetHeader({ children, style, ...props }: BottomSheetHeaderProps): React.JSX.Element;
 declare function BottomSheetBody({ children, style, contentContainerStyle, onContentSizeChange, onLayout, ...props }: BottomSheetBodyProps): React.JSX.Element;

package/dist/components/BottomSheet.js

@@ -296,7 +296,7 @@ function BottomSheetTrigger({ asChild, children, style: styleOverride }) {
 // ============================================================================
 function BottomSheetContent({ 
 // Accepted-but-ignored ergonomics props (platform owns these behaviors):
-swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, style: styleOverride, children, }) {
+swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDrag: _dismissKeyboardOnDrag, backgroundStyle: backgroundStyleOverride, style: styleOverride, children, }) {
     const { open, onOpenChange, snapPoints, snapIndex, setSnapIndex, hasHeader } = useBottomSheetContext();
     const { theme } = useTheme();
     const dismissDisabled = useDismissDisabled();
@@ -337,8 +337,13 @@ swipeEnabled: _swipeEnabled, avoidKeyboard: _avoidKeyboard, dismissKeyboardOnDra
             if (open)
                 onOpenChange(false);
         }, 
-        // Themes the scrim/background on web (vaul) and Android (containerColor).
-        backgroundStyle: { backgroundColor: theme.colors.card }, children: _jsx(TextColorContext.Provider, { value: theme.colors.foreground, children: _jsx(TextClassContext.Provider, { value: "", children: _jsxs(View, { style: [
+        // Themes the scrim/background on web (vaul), Android (containerColor),
+        // and iOS (presentationBackground). Flattened so native readers that
+        // expect a plain object (not a style array) keep working.
+        backgroundStyle: StyleSheet.flatten([
+            { backgroundColor: theme.colors.card },
+            backgroundStyleOverride,
+        ]), children: _jsx(TextColorContext.Provider, { value: theme.colors.foreground, children: _jsx(TextClassContext.Provider, { value: "", children: _jsxs(View, { style: [
                         {
                             flex: 1,
                             maxHeight: detentHeight,