@mrmeg/expo-ui 0.18.0 → 0.21.0

package/dist/components/Avatar.js

@@ -0,0 +1,296 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { use, useState } from "react";
+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";
+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);
+}
+/**
+ * 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.
+ *
+ * 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 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)
+        return null;
+    if (typeof source === "number")
+        return `asset:${source}`;
+    if (Array.isArray(source)) {
+        // 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;
+    }
+    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. 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" />
+ * ```
+ */
+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);
+    // 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 (_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
+ * `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.
+ *
+ * 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>
+ * ```
+ */
+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);
+    // 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 (_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 = {
+    [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 prerendered <head>. Only colors go through
+// createThemedStyles below. See "Enable Server Output" in docs/server-guide.md.
+const geometry = StyleSheet.create({
+    base: {
+        alignItems: "center",
+        justifyContent: "center",
+        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,
+        textAlign: "center",
+        userSelect: "none",
+    },
+    ring: {
+        borderWidth: spacing.xxs,
+    },
+    group: {
+        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 },
+    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) },
+    smImageSquare: { borderRadius: squareRadius(SIZE_TOKENS.sm) },
+    mdImageSquare: { borderRadius: squareRadius(SIZE_TOKENS.md) },
+    lgImageSquare: { borderRadius: squareRadius(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/Carousel.d.ts

@@ -0,0 +1,99 @@
+import React from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+export interface CarouselProps {
+    /** Slides to page through. Each child is wrapped in a fixed-width slide. */
+    children?: React.ReactNode;
+    /**
+     * 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;
+    /** Space between slides. @default spacing.md */
+    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. 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.
+     *
+     * 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;
+    /** Custom style override for the outer container. */
+    style?: StyleProp<ViewStyle>;
+    /** Custom style override for the scroll content row. */
+    contentContainerStyle?: StyleProp<ViewStyle>;
+    /**
+     * testID prefix. Emits `<testID>`, `-scroll`, `-item-<i>`, `-dots`,
+     * `-dot-<i>` (the pressable), `-dot-<i>-indicator` (the visible dot), and
+     * `-status`.
+     * @default "carousel"
+     */
+    testID?: string;
+}
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export declare function getCarouselIndex(offsetX: number, interval: number, count: number): number;
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export declare function resolveCarouselItemWidth(itemWidth: number, containerWidth: number): number;
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * 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}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export declare function Carousel({ children, itemWidth, gap, contentPadding, showDots, initialIndex, onIndexChange, snap, style: styleOverride, contentContainerStyle, testID, }: CarouselProps): React.JSX.Element;

package/dist/components/Carousel.js

@@ -0,0 +1,246 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Platform, Pressable, ScrollView, StyleSheet, Text, View, } from "react-native";
+import { useTheme } from "../hooks/useTheme.js";
+import { useDimensions } from "../hooks/useDimensions.js";
+import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
+// ============================================================================
+// Index math
+// ============================================================================
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export function getCarouselIndex(offsetX, interval, count) {
+    if (!Number.isFinite(offsetX) || !Number.isFinite(interval))
+        return 0;
+    if (interval <= 0 || count <= 0)
+        return 0;
+    const raw = Math.round(offsetX / interval);
+    if (raw < 0)
+        return 0;
+    if (raw > count - 1)
+        return count - 1;
+    return raw;
+}
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export function resolveCarouselItemWidth(itemWidth, containerWidth) {
+    if (!Number.isFinite(itemWidth) || itemWidth <= 0)
+        return 0;
+    if (itemWidth > 1)
+        return Math.round(itemWidth);
+    if (!Number.isFinite(containerWidth) || containerWidth <= 0)
+        return 0;
+    return Math.round(containerWidth * itemWidth);
+}
+function clampIndex(index, count) {
+    if (count <= 0)
+        return 0;
+    return Math.min(count - 1, Math.max(0, Math.trunc(index)));
+}
+// ============================================================================
+// Carousel
+// ============================================================================
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * 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}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export function Carousel({ children, itemWidth = 0.85, gap = spacing.md, contentPadding = spacing.lg, showDots = true, initialIndex = 0, onIndexChange, snap = true, style: styleOverride, contentContainerStyle, testID = "carousel", }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const items = React.Children.toArray(children);
+    const count = items.length;
+    // Width source of truth: the measured container after mount, seeded from the
+    // viewport so a prerendered HTML shell and the client's first render agree.
+    // `useDimensions` seeds from a constant default rather than `window` on that
+    // first render, which is what keeps the seed hydration-safe.
+    const { width: viewportWidth } = useDimensions();
+    const [measuredWidth, setMeasuredWidth] = useState(null);
+    const containerWidth = measuredWidth ?? viewportWidth;
+    const slideWidth = resolveCarouselItemWidth(itemWidth, containerWidth);
+    const interval = slideWidth + gap;
+    const [activeIndex, setActiveIndex] = useState(() => clampIndex(initialIndex, count));
+    // Mirrors activeIndex so the scroll handler can dedupe without re-reading
+    // state: web's throttled ticks report the same page many times over, and
+    // onIndexChange must fire once per page.
+    const activeIndexRef = useRef(activeIndex);
+    const scrollRef = useRef(null);
+    const hasScrolledToInitial = useRef(false);
+    const commitIndex = useCallback((next) => {
+        if (next === activeIndexRef.current)
+            return;
+        activeIndexRef.current = next;
+        setActiveIndex(next);
+        onIndexChange?.(next);
+    }, [onIndexChange]);
+    const isWeb = Platform.OS === "web";
+    const handleScroll = useCallback((event) => {
+        commitIndex(getCarouselIndex(event.nativeEvent.contentOffset.x, interval, count));
+    }, [commitIndex, count, interval]);
+    // Native fallback for a drag that releases with the content at rest: no
+    // momentum follows, so `onMomentumScrollEnd` never arrives and the settle
+    // would go unreported.
+    //
+    // Gated on velocity because an ungated drag-end handler is exactly the
+    // double-fire this replaced: a flick past a slide midpoint that snaps back
+    // reports the midpoint page on release and the original page on settle. A
+    // release that *will* glide reports a non-zero velocity (points/ms on iOS,
+    // density-scaled px/s on Android — either way, orders of magnitude above
+    // this epsilon), and momentum end is left to speak for it. A release at rest
+    // reports 0, and there `getCarouselIndex`'s round-to-nearest already agrees
+    // with where `snapToInterval` would land, so the two paths can't disagree.
+    const handleScrollEndDrag = useCallback((event) => {
+        const velocityX = event.nativeEvent.velocity?.x ?? 0;
+        if (Math.abs(velocityX) > 0.01)
+            return;
+        handleScroll(event);
+    }, [handleScroll]);
+    const handleLayout = useCallback((event) => {
+        const next = event.nativeEvent.layout.width;
+        if (!(next > 0))
+            return;
+        setMeasuredWidth((current) => current !== null && Math.abs(current - next) < 1 ? current : next);
+    }, []);
+    // Jump to initialIndex once, after the first real layout — the seeded
+    // viewport width would put the offset in the wrong place. `contentOffset` is
+    // iOS-only, so drive it imperatively for Android/web parity.
+    const targetIndex = clampIndex(initialIndex, count);
+    useEffect(() => {
+        if (hasScrolledToInitial.current || measuredWidth === null || interval <= 0)
+            return;
+        hasScrolledToInitial.current = true;
+        if (targetIndex === 0)
+            return;
+        scrollRef.current?.scrollTo({ x: targetIndex * interval, animated: false });
+    }, [interval, measuredWidth, targetIndex]);
+    // Re-clamp when children shrink. Without this the status line reads "5 of 3"
+    // with no active dot until the next scroll, because activeIndex is only
+    // seeded once and the scroller — already past the new content width — emits
+    // nothing on its own. Scrolling back is what makes the offset agree with the
+    // reported page again.
+    useEffect(() => {
+        if (count <= 0 || activeIndexRef.current < count)
+            return;
+        const clamped = count - 1;
+        commitIndex(clamped);
+        if (interval > 0) {
+            scrollRef.current?.scrollTo({ x: clamped * interval, animated: false });
+        }
+    }, [commitIndex, count, interval]);
+    const handleDotPress = useCallback((index) => {
+        commitIndex(index);
+        if (interval > 0) {
+            scrollRef.current?.scrollTo({ x: index * interval, animated: true });
+        }
+    }, [commitIndex, interval]);
+    const useCssSnap = isWeb && snap;
+    const dotsVisible = showDots && count > 1;
+    return (_jsxs(View, { style: [styles.container, styleOverride], onLayout: handleLayout, testID: testID, children: [_jsx(ScrollView, { ref: scrollRef, testID: `${testID}-scroll`, horizontal: true, showsHorizontalScrollIndicator: false, 
+                // Native snapping. react-native-web drops these (they aren't in its
+                // forwarded-prop list), so web uses the CSS scroll-snap styles instead.
+                snapToInterval: snap && interval > 0 ? interval : undefined, snapToAlignment: "start", decelerationRate: snap ? "fast" : "normal", ...(isWeb
+                    ? { scrollEventThrottle: 16, onScroll: handleScroll }
+                    : { onMomentumScrollEnd: handleScroll, onScrollEndDrag: handleScrollEndDrag }), style: useCssSnap
+                    ? [webStyles.scroller, { scrollPaddingLeft: contentPadding }]
+                    : undefined, contentContainerStyle: [{ paddingHorizontal: contentPadding, gap }, contentContainerStyle], children: items.map((child, index) => (_jsx(View, { testID: `${testID}-item-${index}`, style: [slideWidth > 0 && { width: slideWidth }, useCssSnap && webStyles.item], children: child }, React.isValidElement(child) && child.key != null ? child.key : index))) }), count > 1 && (_jsx(View, { testID: `${testID}-status`, style: styles.status, "aria-live": "polite", children: _jsx(Text, { style: styles.statusText, children: `${activeIndex + 1} of ${count}` }) })), dotsVisible && (_jsx(View, { testID: `${testID}-dots`, style: styles.dots, accessibilityRole: "tablist", children: items.map((_, index) => (_jsx(Pressable, { testID: `${testID}-dot-${index}`, accessibilityRole: "tab", accessibilityState: { selected: index === activeIndex }, "aria-selected": index === activeIndex, accessibilityLabel: `Slide ${index + 1} of ${count}`, hitSlop: DOT_HIT_SLOP, onPress: () => handleDotPress(index), style: styles.dotButton, children: _jsx(View, { testID: `${testID}-dot-${index}-indicator`, style: [styles.dot, index === activeIndex ? styles.dotActive : styles.dotInactive] }) }, index))) }))] }));
+}
+// ============================================================================
+// Styles
+// ============================================================================
+const DOT_SIZE = 8;
+// Press target around each 8px dot. The square is what separates the dots
+// visually (the row itself has no gap, so neighboring targets are flush — no
+// dead strip between them), and `DOT_HIT_SLOP` extends it vertically to
+// `spacing.touchTarget` (24 + 2 x 10 = 44). The slop is vertical-only on
+// purpose: horizontal slop would overlap the neighboring dot's target and make
+// which dot a tap lands on ambiguous.
+const DOT_HIT_SIZE = 24;
+const DOT_HIT_SLOP = {
+    top: (spacing.touchTarget - DOT_HIT_SIZE) / 2,
+    bottom: (spacing.touchTarget - DOT_HIT_SIZE) / 2,
+    left: 0,
+    right: 0,
+};
+// Web-only CSS scroll-snap. `scrollPaddingLeft` is applied inline at the call
+// site (it tracks the contentPadding prop) so the leading inset survives the
+// browser snapping slide 0 to the scrollport start — which also makes page `i`
+// land on `i * interval`, matching the native snap offsets.
+const webStyles = StyleSheet.create({
+    scroller: { scrollSnapType: "x mandatory" },
+    item: { scrollSnapAlign: "start" },
+});
+const createStyles = (theme) => StyleSheet.create({
+    container: {
+        width: "100%",
+    },
+    // Clipped to 1x1 rather than removed: screen readers skip
+    // display:none/opacity:0 nodes, and there is no visual affordance to show.
+    status: {
+        position: "absolute",
+        width: 1,
+        height: 1,
+        overflow: "hidden",
+    },
+    statusText: {
+        fontSize: 1,
+        color: "transparent",
+    },
+    dots: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "center",
+        // No `gap`: the DOT_HIT_SIZE squares carry the visual spacing, and a gap
+        // would open an unpressable strip between adjacent targets. marginTop
+        // absorbs the wrapper's own vertical padding so the row sits where the
+        // pre-Pressable dots did.
+        marginTop: spacing.md - (DOT_HIT_SIZE - DOT_SIZE) / 2,
+    },
+    dotButton: {
+        width: DOT_HIT_SIZE,
+        height: DOT_HIT_SIZE,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    dot: {
+        width: DOT_SIZE,
+        height: DOT_SIZE,
+        borderRadius: spacing.radiusFull,
+    },
+    dotActive: {
+        backgroundColor: theme.colors.accent,
+    },
+    dotInactive: {
+        backgroundColor: theme.colors.border,
+    },
+});
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/Drawer.js

@@ -395,7 +395,9 @@ function DrawerOverlayContent({ swipeEnabled = true, swipeThreshold = 0.3, veloc
         bottom: 0,
         width,
         [side]: 0,
-        backgroundColor: theme.colors.background,
+        // App chrome sits on the sunken tier so it reads as a layer beneath the
+        // content pane rather than the same surface.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left"
             ? { borderRightWidth: 1 }
@@ -502,7 +504,8 @@ swipeEnabled: _swipeEnabled, swipeThreshold: _swipeThreshold, velocityThreshold:
     const panelStyle = {
         width: Platform.OS === "web" ? targetWidth : widthAnim,
         overflow: "hidden",
-        backgroundColor: theme.colors.background,
+        // Rail chrome sits on the sunken tier, one step below the content pane.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left" ? { borderRightWidth: 1 } : { borderLeftWidth: 1 }),
         paddingTop: insets.top,