@mrmeg/expo-ui 0.18.0 → 0.21.0

package/CHANGELOG.md

@@ -3,6 +3,289 @@
 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.21.0]
+
+### Added
+
+- **`Carousel` dots are pressable and scroll to their slide.** Each dot is a
+  `Pressable` that jumps the scroller to its page (animated) and reports the
+  new index through `onIndexChange`. The `tablist`/`tab` roles and `selected`
+  state the dots already carried are now honest: a screen reader that
+  announced N activatable tabs can finally focus and activate them, and on web
+  each dot is a keyboard tab-stop.
+
+  The visible dot stays 8px. The press target is a 24px wrapper plus vertical
+  `hitSlop` (44px total), and the row's `gap` moved into that wrapper so
+  neighboring targets sit flush with no dead strip between them. The slop is
+  vertical-only so a tap can't be ambiguous between two dots.
+
+  The selected dot also sets `aria-selected` explicitly: react-native-web
+  never maps `accessibilityState` to the DOM, so on web the tabs previously
+  exposed no selected state at all. Native maps `aria-selected` back into
+  `accessibilityState`, so the two props agree.
+
+- **`Label` accepts `htmlFor`.** `@rn-primitives/label`'s web build only emits a
+  real `<label for="…">` — the thing that actually associates a label with an
+  input and makes clicking the label focus it — when `htmlFor` is passed, and
+  `Label` never forwarded it. No consumer could produce an associated label.
+  `htmlFor` now reaches the primitive's `Text`, which is where the prop is
+  declared and where the web build consumes it. Native ignores it, matching the
+  primitive.
+
+  Association takes **two distinct ids**:
+
+  ```tsx
+  <Label nativeID="email-label" htmlFor="email-input">Email</Label>
+  <TextInput nativeID="email-input" />
+  ```
+
+  `nativeID` is the label's own id (react-native-web maps it to `id`; on native
+  it's what a control's `accessibilityLabelledBy` points at). `htmlFor` is the
+  input's id.
+
+### Changed
+
+- **`Carousel` re-clamps its active index when `children` shrink.** The index
+  was seeded once, so removing slides while a late page was active left the
+  page announcement reading e.g. "5 of 3" with no active dot until the next
+  scroll. It now clamps to the last slide, reports the clamped value through
+  `onIndexChange`, and scrolls back to that page — the scroller was sitting
+  past the new content width.
+
+- **`Carousel` index tracking is split by platform.** Native subscribes to
+  `onMomentumScrollEnd` — plus a velocity-gated `onScrollEndDrag`, for a drag
+  that releases at rest and so is never followed by a momentum event — and no
+  longer subscribes to `onScroll` at all, so a drag costs no per-frame JS
+  callback to compute a page the settle reports anyway. A drag past a slide
+  midpoint that snaps back to the starting page now reports nothing instead of
+  firing the intermediate page and then the original. Web keeps the throttled
+  `onScroll` path, which remains the only channel there — react-native-web
+  emits no momentum events.
+
+  The `onIndexChange` doc no longer claims "once per settle" unconditionally.
+  That now holds on native; on web (wheel/trackpad) it still fires once per
+  page *crossed*, and only consecutive duplicate indices are suppressed.
+
+- **New `Carousel` testID: `<testID>-dot-<i>-indicator`.** `-dot-<i>` is now
+  the pressable wrapper; the visible dot — and therefore its
+  `backgroundColor` — is the `-indicator` node inside it. Tests asserting on a
+  dot's color need the new suffix.
+
+- **`useDimensions` seeds from a constant, not context.** The first web render
+  uses the new `DEFAULT_VIEWPORT_WIDTH` / `DEFAULT_VIEWPORT_HEIGHT` exports
+  (1280×800, the previous context defaults) and switches to real dimensions
+  after mount. The hook no longer reads a context or writes an `mrmeg-vw`
+  cookie.
+
+- **Theme persistence key is exported as `THEME_STORAGE_KEY`** (value
+  unchanged: `user-theme-preference`), replacing `THEME_COOKIE_NAME` as the
+  name callers reference.
+
+### Removed
+
+- **Server-rendering support surface.** The template that hosts this package
+  no longer server-renders web routes (routes are client-rendered from an
+  HTML shell), so the per-request plumbing that existed only to make a server
+  render and the browser's first render agree is gone:
+
+  - `SsrThemeSeedContext`, `SsrThemeSeed`, `SSR_THEME_SEED_DEFAULT`, and
+    `useSsrThemeSeed` (added in 0.20.0).
+  - `SsrViewportContext`, `SSR_VIEWPORT_DEFAULT_WIDTH`, and
+    `SSR_VIEWPORT_DEFAULT_HEIGHT`.
+  - `THEME_COOKIE_NAME`, and the `document.cookie` write `setTheme` performed
+    alongside its persisted write on web.
+
+  Hosts that server-render can keep doing so, but they now own the seeding
+  themselves; `useTheme` resolves from the store only.
+
+### Fixed
+
+- **`Label`'s documented pairing pattern produced duplicate DOM ids.** The usage
+  docs recommended the *same* `nativeID` on the `Label` and its `TextInput`.
+  react-native-web maps `nativeID` to `id`, so that renders two elements sharing
+  one id — invalid HTML, and no association either way. The docs now show the
+  two-id pattern above.
+
+- **`Avatar` renders image sources that carry no `uri`.** The internal source
+  key — which exists so a failure flag survives the fresh `{ uri }` object that
+  an inline literal allocates every render — returned `null` for any object
+  without a truthy `uri`, and `null` means "no image at all". An iOS
+  `{ bundle }` source, or a resolved asset object, therefore silently degraded
+  to initials and the image was never attempted. Every shape React Native
+  accepts is now keyed (numbers as `asset:<n>`, uri strings as themselves,
+  anything else by a stable serialization of its fields); `null` is reserved
+  for a missing, empty-object, or empty-array source. Retry-on-change and
+  keep-the-failure-on-re-render behavior now applies to those shapes too.
+
+- **`AvatarGroup` members are announceable again (accessibility change).** The
+  group wrapper was `accessible` with `accessibilityRole="image"` and an
+  `"<n> avatars"` label, which is a leaf role on the web and swallows
+  descendants on iOS — so no member's name could be reached inside a group. The
+  wrapper is now a plain container with no accessibility semantics of its own,
+  and the count rides along as a visually clipped text node ahead of the
+  members, so a screen reader reads the summary and then each avatar. Passing
+  `accessibilityLabel` still replaces the count text. Apps that asserted on the
+  group by its accessibility label (`getByLabelText("3 avatars")`) should query
+  the text instead (`getByText("3 avatars")`).
+
+- **`AvatarGroup`'s `max` is clamped to a whole count ≥ 0.** A negative `max`
+  reached `slice(0, max)`, which reads a negative end as an offset from the end
+  — `max={-3}` on three children rendered all of them, silently disabling the
+  clamp — and a fractional `max` truncated arbitrarily. `max` is now
+  `Math.max(0, Math.floor(max))`, so `max={0}` renders only the `+N` tile.
+
+- **`Avatar` shows its initials/icon fallback while the image loads.** A slow
+  or large image left a bare `muted` tile for the whole request. The fallback
+  now stays mounted until the image reports `onLoad`, with the image layered
+  over it, so an avatar is never a blank circle in flight.
+
+- **`Avatar`'s image carries its own corner radius.** Rounding relied solely on
+  the wrapper's `overflow: "hidden"`, which Android drops for a child image in
+  several cases, leaving square corners on a circular avatar.
+
+### Documentation
+
+- **`Carousel`'s `itemWidth` caveat.** A fractional `itemWidth` measures
+  against the viewport until the first `onLayout`, so a carousel inside a
+  horizontally constrained parent (a padded column, a `MaxWidthContainer`, a
+  sidebar pane) renders its first frame — and the exported HTML shell — with
+  slides sized to the window. Documented on the prop, with the workaround:
+  pass an absolute `itemWidth` (`> 1`) when the parent is narrower than the
+  viewport and that first frame matters.
+
+## [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

package/LLM_USAGE.md

@@ -107,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;
@@ -131,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`,
@@ -187,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 pressable 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 |
@@ -227,8 +238,11 @@ 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 into the exported HTML shell and the first client frame; reach for `FlatList` when the data set is large or unbounded. Its dots are pressable and jump to their slide. A fractional `itemWidth` measures the viewport until the first layout, so pass absolute pixels (`> 1`) when the parent is narrower than the window and the first frame matters.
 - 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, still loading, or failed, 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; the group's count is a hidden summary node, so each member stays individually announceable and the group needs no `accessible` wrapper.
+- Pair a standalone `Label` with its control using two DISTINCT ids: `nativeID` is the label's own id, `htmlFor` is the input's id (`<Label nativeID="email-label" htmlFor="email-input">` + `<TextInput nativeID="email-input" />`). Putting the same id on both renders duplicate ids on web and associates nothing. Prefer `TextInput`'s own `label` prop when you don't need a separate label element.
 - 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 pressable 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, but that fraction measures the viewport until the first layout — pass absolute pixels (`> 1`) inside a constrained parent |
 | `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 |
@@ -380,6 +384,8 @@ Use `Skeleton` components for loading content with stable dimensions, `EmptyStat
 
 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, still loading, 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. `AvatarGroup` announces its count as a hidden summary and leaves each member individually announceable, so don't wrap it in an `accessible` container of your own.
+
 ### Quick Examples
 
 Card, badge, and CTA:

package/dist/components/Avatar.d.ts

@@ -0,0 +1,94 @@
+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. Any source React Native accepts — a uri object, a
+     * `require()`d asset, a uri-less descriptor, a multi-resolution array. The
+     * initials (then the icon) show while it loads and if it fails.
+     */
+    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. The fallback shows while the image is in flight and
+ * stays put if the image fails, so neither a slow network nor a dead URL ever
+ * 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.
+     * Clamped to a whole count ≥ 0, so `max={0}` renders only the `+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;
+    /**
+     * Summary announced ahead of the members, as a visually hidden text node.
+     * 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.
+ *
+ * The group is not an accessibility element itself — its member avatars each
+ * announce their own name, preceded by a hidden count summary.
+ *
+ * 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 };