@mrmeg/expo-ui 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -3,6 +3,156 @@
 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

package/LLM_USAGE.md

@@ -201,7 +201,7 @@ Use this table before creating a new app-local primitive.
 | `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 |
+| `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 |
@@ -238,10 +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 server rendering; reach for `FlatList` when the data set is large or unbounded.
+- 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 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 `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

@@ -302,7 +302,7 @@ All components are exported from `@mrmeg/expo-ui/components`; direct imports suc
 | `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 |
+| `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 |
@@ -384,7 +384,7 @@ 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 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.
+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
 

package/dist/components/Avatar.d.ts

@@ -18,7 +18,11 @@ export type AvatarShape = "circle" | "square";
  */
 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. */
+    /**
+     * 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;
@@ -39,8 +43,9 @@ export interface AvatarProps {
  * 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.
+ * 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
@@ -52,13 +57,19 @@ export interface AvatarProps {
 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. */
+    /**
+     * 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;
-    /** Defaults to `"<n> avatars"`, counting the collapsed overflow. */
+    /**
+     * 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>;
 }
@@ -69,6 +80,9 @@ export interface AvatarGroupProps {
  * 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}>

package/dist/components/Avatar.js

@@ -1,6 +1,6 @@
 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 { Image, StyleSheet, Text, View, } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { Icon } from "./Icon.js";
@@ -29,6 +29,19 @@ function contentSize(px) {
 function overlap(px) {
     return -Math.round(px * 0.3);
 }
+/**
+ * Radius for the inner `Image`.
+ *
+ * The wrapper already clips with `overflow: "hidden"`, but Android drops that
+ * clip on a child image in several cases (elevation, some resize modes), so
+ * the image carries the radius itself as well.
+ */
+function imageRadius(px, shape) {
+    if (shape === "circle")
+        return geometry.imageCircle;
+    const token = SIZE_TOKEN_FOR_PX[px];
+    return token ? geometry[`${token}ImageSquare`] : { borderRadius: squareRadius(px) };
+}
 /**
  * Derive 1–2 initials from a display name.
  *
@@ -59,9 +72,14 @@ export function getAvatarInitials(name) {
 /**
  * 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.
+ * `source={{ uri }}` allocates a new object on every render, so load/failure
+ * flags keyed on object identity would reset immediately and loop
+ * image → error → image.
+ *
+ * `null` means "no source" and nothing else: every shape React Native accepts
+ * gets a key, including the ones that carry no `uri` at all (iOS
+ * `{ bundle, name }`, a resolved asset object). Keying those as "no image"
+ * silently degraded a perfectly good source to initials.
  */
 function getSourceKey(source) {
     if (source == null)
@@ -69,18 +87,28 @@ function getSourceKey(source) {
     if (typeof source === "number")
         return `asset:${source}`;
     if (Array.isArray(source)) {
-        const key = source.map((entry) => entry?.uri ?? "").filter(Boolean).join("|");
-        return key || null;
+        // An empty array carries no image; anything else does.
+        const keys = source.map((entry) => getSourceKey(entry) ?? "").filter(Boolean);
+        return keys.length > 0 ? keys.join("|") : null;
     }
-    return source.uri || null;
+    if (source.uri)
+        return source.uri;
+    // Whatever is left is a descriptor object without a uri. Serialize it, with
+    // keys sorted so two equivalent literals written in a different order still
+    // key the same. `{}` is the one object that carries no image.
+    const fields = Object.keys(source).sort();
+    if (fields.length === 0)
+        return null;
+    return fields.map((field) => `${field}=${JSON.stringify(source[field])}`).join("&");
 }
 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.
+ * 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
@@ -96,13 +124,17 @@ function Avatar({ source, name, icon, size, shape, accessibilityLabel, style: st
     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.
+    // Both flags are keyed on the source's content, so a retry with a new URL
+    // clears them while a re-rendered identical URL keeps them.
     const [failedKey, setFailedKey] = useState(null);
+    const [loadedKey, setLoadedKey] = useState(null);
     const showImage = sourceKey !== null && failedKey !== sourceKey;
+    // The fallback stays mounted under a still-loading image, so a slow network
+    // shows initials rather than an empty muted tile.
+    const showFallback = !showImage || loadedKey !== 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 })) }));
+    return (_jsxs(AvatarSurface, { px: px, shape: resolvedShape, ring: group?.ring ?? false, accessibilityLabel: label, style: [styles.fallback, styleOverride], children: [showFallback ? (initials ? (_jsx(AvatarLabel, { px: px, style: styles.fallbackText, children: initials })) : (_jsx(Icon, { name: icon ?? "user", size: contentSize(px).iconSize, color: "mutedForeground", decorative: true }))) : null, showImage ? (_jsx(Image, { source: source, resizeMode: "cover", style: [geometry.image, imageRadius(px, resolvedShape)], onLoad: () => setLoadedKey(sourceKey), onError: () => setFailedKey(sourceKey) })) : null] }));
 }
 /**
  * Shared chrome for an avatar-shaped tile — used by `Avatar` and by
@@ -143,6 +175,9 @@ function AvatarLabel({ px, style, children, }) {
  * 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}>
@@ -156,20 +191,23 @@ function AvatarGroup({ children, max, size = "md", shape = "circle", accessibili
     // 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;
+    // A whole count, never negative: `slice` would otherwise read a negative max
+    // as "from the end" (rendering every child) and truncate a fractional one.
+    const limit = max != null ? Math.max(0, Math.floor(max)) : null;
+    const visible = limit != null ? items.slice(0, limit) : 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] }) }));
+    return (_jsxs(View, { style: [geometry.group, styleOverride], children: [_jsx(View, { style: geometry.summary, children: _jsx(Text, { style: geometry.summaryText, children: accessibilityLabel ?? `${items.length} avatars` }) }), _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 = {
@@ -178,8 +216,8 @@ const SIZE_TOKEN_FOR_PX = {
     [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.
+// get these rules into the prerendered <head>. Only colors go through
+// createThemedStyles below. See "Enable Server Output" in docs/server-guide.md.
 const geometry = StyleSheet.create({
     base: {
         alignItems: "center",
@@ -187,9 +225,18 @@ const geometry = StyleSheet.create({
         overflow: "hidden",
     },
     image: {
+        // Absolutely positioned so the fallback underneath it keeps the tile's
+        // centered layout while the image is still loading. The explicit 100%
+        // size must stay alongside the inset: react-native-web does not resolve
+        // an Image's size from the inset box and falls back to the asset's
+        // natural pixels, blowing a 1024px image out of a 48px tile.
+        position: "absolute",
+        top: 0,
+        left: 0,
         width: "100%",
         height: "100%",
     },
+    imageCircle: { borderRadius: spacing.radiusFull },
     labelText: {
         // The tile is the touch/visual target; text must not add its own metrics.
         includeFontPadding: false,
@@ -203,6 +250,18 @@ const geometry = StyleSheet.create({
         flexDirection: "row",
         alignItems: "center",
     },
+    // Clipped to 1x1 rather than removed: screen readers skip
+    // display:none/opacity:0 nodes, and there is no visual affordance to show.
+    summary: {
+        position: "absolute",
+        width: 1,
+        height: 1,
+        overflow: "hidden",
+    },
+    summaryText: {
+        fontSize: 1,
+        color: "transparent",
+    },
     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 },
@@ -212,6 +271,9 @@ const geometry = StyleSheet.create({
     smStack: { marginLeft: overlap(SIZE_TOKENS.sm) },
     mdStack: { marginLeft: overlap(SIZE_TOKENS.md) },
     lgStack: { marginLeft: overlap(SIZE_TOKENS.lg) },
+    smImageSquare: { borderRadius: squareRadius(SIZE_TOKENS.sm) },
+    mdImageSquare: { borderRadius: squareRadius(SIZE_TOKENS.md) },
+    lgImageSquare: { borderRadius: squareRadius(SIZE_TOKENS.lg) },
 });
 const createStyles = (theme) => StyleSheet.create({
     fallback: {

package/dist/components/Carousel.d.ts

@@ -7,6 +7,14 @@ export interface CarouselProps {
      * Slide width. Values `<= 1` are a fraction of the carousel's own width —
      * the default `0.85` leaves the next slide peeking. Values `> 1` are
      * absolute pixels.
+     *
+     * Caveat for fractional values: "the carousel's own width" is only known
+     * after the first `onLayout`. Until then it is seeded from the viewport
+     * width, 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* and
+     * corrects on layout. Pass an absolute `itemWidth` (`> 1`) when the parent
+     * is narrower than the viewport and that first frame matters.
      * @default 0.85
      */
     itemWidth?: number;
@@ -14,11 +22,25 @@ export interface CarouselProps {
     gap?: number;
     /** Horizontal inset before the first and after the last slide. @default spacing.lg */
     contentPadding?: number;
-    /** Render the dot indicators. Auto-hidden for a single slide. @default true */
+    /**
+     * Render the dot indicators. Auto-hidden for a single slide. Dots are
+     * pressable and scroll to their slide.
+     * @default true
+     */
     showDots?: boolean;
     /** Slide shown on mount. @default 0 */
     initialIndex?: number;
-    /** Called with the new active index whenever it changes. */
+    /**
+     * Called with the new active index whenever it changes.
+     *
+     * On native this is once per settle: momentum end, or drag end for a release
+     * that stops at rest. On web it is once per page *crossed*, because
+     * react-native-web emits no momentum events and throttled scroll ticks are
+     * the only channel — a wheel scroll spanning three pages reports all three.
+     * Consecutive duplicate indices are always suppressed. Also fires on a dot
+     * press, and when `children` shrink below the active index and it has to be
+     * re-clamped.
+     */
     onIndexChange?: (index: number) => void;
     /** Snap to slide boundaries. @default true */
     snap?: boolean;
@@ -28,7 +50,8 @@ export interface CarouselProps {
     contentContainerStyle?: StyleProp<ViewStyle>;
     /**
      * testID prefix. Emits `<testID>`, `-scroll`, `-item-<i>`, `-dots`,
-     * `-dot-<i>`, and `-status`.
+     * `-dot-<i>` (the pressable), `-dot-<i>-indicator` (the visible dot), and
+     * `-status`.
      * @default "carousel"
      */
     testID?: string;
@@ -54,11 +77,14 @@ export declare function resolveCarouselItemWidth(itemWidth: number, containerWid
  * resolved item width.
  *
  * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
- * in the server-rendered tree, so web SSR ships the real content instead of an
- * empty scroller that only fills in after measurement. Snapping uses the
- * platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
+ * in the prerendered tree, so a web build's HTML shell ships the real content
+ * instead of an empty scroller that only fills in after measurement. Snapping
+ * uses the platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
  * animation library is involved.
  *
+ * Slides sized by a fractional `itemWidth` measure against the viewport until
+ * the first `onLayout` lands — see the `itemWidth` caveat on `CarouselProps`.
+ *
  * @example
  * ```tsx
  * <Carousel itemWidth={0.8} onIndexChange={setPage}>