@krapwoo/ds-viewer 0.1.1 → 0.2.0

package/starter-kit/components/Badge/Badge.types.ts

@@ -0,0 +1,18 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+export type BadgeVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export interface BadgeProps {
+  /** Semantic color scheme. */
+  variant?: BadgeVariant;
+  /** Label text. Omit (with a single icon) for an icon-only chip. */
+  label?: string;
+  /** Icon before the label. */
+  leadingIcon?: IconName;
+  /** Icon after the label. */
+  trailingIcon?: IconName;
+  /** Accessible name — required for an icon-only badge (no `label`) so it can be announced. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Badge/index.ts

@@ -0,0 +1,2 @@
+export { Badge } from './Badge';
+export type { BadgeProps, BadgeVariant } from './Badge.types';

package/starter-kit/components/Banner/Banner.catalog.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Banner } from './Banner';
+
+export default defineCatalogPage({
+  component: 'Banner',
+  group: 'Surfaces',
+  description: 'An inline callout for status/announcements — five semantic variants, optional collapsible body, inline link, and action button.',
+  whenToUse: "Persistent and in-flow, describing a standing condition about the screen's content. For a transient, self-contained event notification, use Toast instead.",
+  a11y: 'When onPress/action is set the header/button are Pressables; the collapsible header toggles the description with a chevron affordance.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Banner variant="neutral" title="Schedule notice" description="Holiday schedule in effect Monday." /> },
+      { key: 'info', name: 'Info', props: { variant: 'info' }, node: <Banner variant="info" title="Weekend service change" description="The 6 runs express in both directions this weekend." /> },
+      { key: 'positive', name: 'Positive', props: { variant: 'positive' }, node: <Banner variant="positive" title="Service restored" description="All lines are running on a normal schedule." /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Banner variant="warning" title="Delays" description="Signal problems near 14 St." /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Banner variant="negative" title="Line suspended" description="No service between 96 St and 137 St until further notice." /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'tappable',
+        name: 'Tappable',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Alert preferences"
+            description="Tap to manage which alerts you receive."
+            onPress={() => {}}
+          />
+        ),
+      },
+      {
+        key: 'collapsible-expanded',
+        name: 'Collapsible (expanded)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+          />
+        ),
+      },
+      {
+        key: 'collapsible-collapsed',
+        name: 'Collapsible (collapsed)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+            defaultExpanded={false}
+          />
+        ),
+      },
+      {
+        key: 'action',
+        name: 'With action',
+        node: (
+          <Banner
+            variant="info"
+            title="App update available"
+            description="Version 4.2 adds live bus tracking."
+            action={{ label: 'Update', onPress: () => {} }}
+          />
+        ),
+      },
+      {
+        key: 'link',
+        name: 'With link',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Fare increase"
+            description="New fares start March 1."
+            link={{ label: 'Learn more', onPress: () => {} }}
+          />
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Banner/Banner.tsx

@@ -0,0 +1,257 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { View, Text, Pressable, Animated, Easing, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { AnimatedChevron } from '../AnimatedChevron';
+import { STATUS_BG, STATUS_FG } from '../statusColors';
+import type { BannerProps, BannerVariant } from './Banner.types';
+
+// Shared with Badge (see ../statusColors) so a banner reads as the same status identity as a
+// badge of the same variant — one map, matched by construction.
+
+const BANNER_ICONS: Record<BannerVariant, IconName> = {
+  neutral: 'info-circle',
+  info: 'info-circle',
+  positive: 'circle-check',
+  warning: 'triangle-alert',
+  negative: 'alert-circle',
+};
+
+const COLLAPSE_ANIM_MS = DS_MOTION_DURATION.base;
+
+/**
+ * A status callout in two layouts, chosen by props:
+ *   • collapsible callout — the whole card toggles the description open/closed;
+ *   • standard callout    — leading icon + title, optional description/link/action.
+ */
+export function Banner({
+  variant = 'warning',
+  title = 'Banner title',
+  description = 'Description text goes here',
+  collapsible = false,
+  defaultExpanded = true,
+  backgroundColor,
+  onPress,
+  trailingIcon,
+  textColor,
+  icon,
+  link,
+  action,
+  style,
+}: BannerProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  // Real layout height + opacity via the core `Animated` API (`useNativeDriver: false`) — not
+  // `LayoutAnimation`, which is unreliable on the New Architecture (Fabric) and a total no-op on
+  // web, so the collapse used to just snap instantly there. Same measure-once-then-animate
+  // technique used elsewhere in this DS: render in normal flow only on the very first pass while
+  // already expanded (shows instantly, no flash, and captures the real height); every other pass —
+  // including the very first while starting collapsed — positions the content absolutely so it can
+  // self-measure without affecting layout, then animates between 0 and that measured height.
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+  const collapseAnim = useRef(new Animated.Value(defaultExpanded ? 1 : 0)).current;
+
+  useEffect(() => {
+    const anim = Animated.timing(collapseAnim, {
+      toValue: expanded ? 1 : 0,
+      duration: COLLAPSE_ANIM_MS,
+      // `standard` — an in-place expand/collapse (a toggle), per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.standard),
+      useNativeDriver: false,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [expanded, collapseAnim]);
+
+  const bg = backgroundColor ?? STATUS_BG[variant];
+  const contentTextColor = textColor ?? STATUS_FG[variant];
+  const iconName = icon ?? BANNER_ICONS[variant];
+
+  // ── Collapsible callout: the whole banner toggles the description ─────────────
+  if (collapsible) {
+    const toggle = () => setExpanded(e => !e);
+    const flowMeasure = measuredHeight === 0 && expanded;
+    const onDescriptionLayout = (e: LayoutChangeEvent) => {
+      const h = e.nativeEvent.layout.height;
+      if (h > 0 && h !== measuredHeight) setMeasuredHeight(h);
+    };
+    return (
+      <Pressable
+        style={[styles.calloutContainer, { backgroundColor: bg }, style]}
+        onPress={toggle}
+        accessibilityRole="button"
+        accessibilityState={{ expanded }}
+      >
+        {({ pressed }) => (
+          <>
+            {pressed && <View style={styles.pressOverlay} pointerEvents="none" />}
+            <View style={styles.headerRow}>
+              <Icon name={iconName} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+              <Text style={[styles.title, styles.titleFlex, { color: contentTextColor, marginBottom: 0 }]}>
+                {title}
+              </Text>
+              <AnimatedChevron expanded={expanded} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+            </View>
+            {!!description && (
+              <Animated.View
+                style={[
+                  styles.collapseClip,
+                  measuredHeight === 0
+                    ? expanded
+                      ? null
+                      : styles.collapseHidden
+                    : { height: Animated.multiply(collapseAnim, measuredHeight), opacity: collapseAnim },
+                ]}
+              >
+                <View style={flowMeasure ? undefined : styles.collapseAbsolute} onLayout={onDescriptionLayout}>
+                  <Text style={[styles.description, styles.descriptionPad, { color: contentTextColor }]}>
+                    {description}
+                  </Text>
+                </View>
+              </Animated.View>
+            )}
+          </>
+        )}
+      </Pressable>
+    );
+  }
+
+  // ── Standard callout (title + description) ────────────────────────────────────
+  const body = (pressed: boolean) => (
+    <>
+      {onPress && pressed && <View style={styles.pressOverlay} pointerEvents="none" />}
+      <View style={styles.headerRow}>
+        <Icon name={iconName} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+        <Text style={[styles.title, styles.titleFlex, { color: contentTextColor, marginBottom: 0 }]}>
+          {title}
+        </Text>
+        {trailingIcon ? <Icon name={trailingIcon} size={DS_ICON_SIZE.xs} color={contentTextColor} /> : null}
+      </View>
+      {description || link ? (
+        <Text style={[styles.description, styles.descriptionPad, { color: contentTextColor }]}>
+          {description ?? ''}
+          {description && link ? ' ' : null}
+          {link ? (
+            <Text style={styles.linkText} onPress={link.onPress} accessibilityRole="link">
+              {link.label}
+            </Text>
+          ) : null}
+        </Text>
+      ) : null}
+      {action ? (
+        <View style={[styles.actionRow, { paddingHorizontal: DS_SPACING[800] }]}>
+          <Pressable
+            style={({ pressed }) => [styles.actionButton, pressed && styles.actionButtonPressed]}
+            // Pads the compact text button's visual ~26px height out to the 44pt touch-target minimum.
+            hitSlop={10}
+            onPress={action.onPress}
+            accessibilityRole="button"
+            accessibilityLabel={action.label}
+          >
+            <Text style={[styles.actionLabel, { color: contentTextColor }]}>{action.label}</Text>
+          </Pressable>
+        </View>
+      ) : null}
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        style={[styles.calloutContainer, { backgroundColor: bg }, style]}
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+      >
+        {({ pressed }) => body(pressed)}
+      </Pressable>
+    );
+  }
+
+  return (
+    <View style={[styles.calloutContainer, { backgroundColor: bg }, style]}>{body(false)}</View>
+  );
+}
+
+const styles = StyleSheet.create({
+  actionRow: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    marginTop: DS_SPACING[400],
+  },
+  actionButton: {
+    borderRadius: DS_RADIUS.xs,
+    paddingVertical: DS_SPACING[200],
+    paddingHorizontal: DS_SPACING[600],
+  },
+  actionButtonPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  actionLabel: {
+    ...DS_TYPOGRAPHY.labelSm,
+  },
+  // Was undistinguished from the surrounding description text (just inherited its color via
+  // nested-Text color inheritance) — underline alone with no color difference is easy to miss at a
+  // glance and gives nothing to fall back on if the underline is ever dropped.
+  linkText: {
+    textDecorationLine: 'underline',
+    color: DS_SEMANTIC.text.link,
+  },
+  // Callout: the header carries the top + horizontal padding so the pressed state fills it; the
+  // bottom padding lives on the container (constant) so nothing jumps when toggling — only the
+  // description mounts/unmounts. overflow:hidden keeps the rounded corners.
+  calloutContainer: {
+    borderRadius: DS_RADIUS.medium,
+    width: '100%',
+    overflow: 'hidden',
+    paddingBottom: DS_SPACING[800],
+  },
+  headerRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: DS_SPACING[400],
+    paddingTop: DS_SPACING[800],
+    paddingHorizontal: DS_SPACING[800],
+  },
+  title: {
+    ...DS_TYPOGRAPHY.labelSm,
+    color: DS_SEMANTIC.text.regular,
+    marginBottom: DS_SPACING[200],
+  },
+  titleFlex: {
+    flex: 1,
+  },
+  description: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.regular,
+  },
+  descriptionPad: {
+    // Start-aligns with the title: headerRow padding (800) + icon + gap (400). Logical start/end
+    // (not left/right) so the indent follows the icon+title when the layout mirrors in RTL.
+    paddingStart: DS_SPACING[800] + DS_ICON_SIZE.xs + DS_SPACING[400],
+    paddingEnd: DS_SPACING[800],
+    paddingTop: DS_SPACING[200],
+  },
+  // Translucent pressed overlay — sits above the banner bg so the tinted bg shows through.
+  pressOverlay: {
+    ...StyleSheet.absoluteFillObject,
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+    borderRadius: DS_RADIUS.medium,
+  },
+  // Collapsible description — clips the animated height; the child is pinned absolute (except on
+  // its very first in-flow measuring pass) so shrinking the parent never re-measures/corrupts it.
+  collapseClip: {
+    overflow: 'hidden',
+    width: '100%',
+  },
+  collapseHidden: {
+    height: 0,
+  },
+  collapseAbsolute: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+  },
+});

package/starter-kit/components/Banner/Banner.types.ts

@@ -0,0 +1,38 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+export type BannerVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export interface BannerProps {
+  /** Semantic color scheme. */
+  variant?: BannerVariant;
+  /** Header text. */
+  title?: string;
+  /** Body text. */
+  description?: string;
+  /** When true, the header row (title + chevron) toggles the description open/closed. */
+  collapsible?: boolean;
+  /** Initial expanded state when collapsible. Defaults to true (description shown). */
+  defaultExpanded?: boolean;
+  /** Override the variant background color. */
+  backgroundColor?: string;
+  /** Makes the whole banner tappable, with a pressed state — the tap target is the whole card. */
+  onPress?: () => void;
+  /** Trailing icon in the header, right-aligned (e.g. 'chevron-right'). */
+  trailingIcon?: IconName;
+  /** Override the icon/text color (defaults to the variant's emphasis color). */
+  textColor?: string;
+  /** Override the leading icon for the standard callout layout. */
+  icon?: IconName;
+  /** Inline tappable link appended to the description text. */
+  link?: {
+    label: string;
+    onPress: () => void;
+  };
+  /** Action button rendered below the description, right-aligned. */
+  action?: {
+    label: string;
+    onPress: () => void;
+  };
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Banner/index.ts

@@ -0,0 +1,2 @@
+export { Banner } from './Banner';
+export type { BannerProps, BannerVariant } from './Banner.types';

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -0,0 +1,77 @@
+import React, { useState } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { Dock } from '../Dock';
+import { TopNav } from '../TopNav';
+import { BottomSheet } from './BottomSheet';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  // BottomSheet/Dropdown demos render inside the shared `PhoneFrame` (./PhoneFrame.tsx) so their
+  // absolute overlays stay contained instead of covering the whole catalog page. No padding here —
+  // BottomSheet's own content area already supplies the standard 16px.
+  sheetContent: {},
+  cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+  cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
+});
+
+function BottomSheetDemo() {
+  const [visible, setVisible] = useState(false);
+  return (
+    <PhoneFrame>
+      {!visible && <Button label="Open sheet" onPress={() => setVisible(true)} />}
+      <BottomSheet
+        visible={visible}
+        onDismiss={() => setVisible(false)}
+        header={
+          <TopNav
+            title="Trip details"
+            trailing={
+              <Button
+                variant="secondary"
+                size="small"
+                showIcon
+                showLabel={false}
+                iconName="clear"
+                accessibilityLabel="Close"
+                onPress={() => setVisible(false)}
+              />
+            }
+          />
+        }
+        footer={
+          <Dock>
+            <Button label="Confirm" onPress={() => setVisible(false)} />
+          </Dock>
+        }
+      >
+        <View style={styles.sheetContent}>
+          <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+          <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
+          {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
+              `elevated` shadow turning on automatically once this content area actually scrolls. */}
+          <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
+          <Text style={styles.cardBody}>
+            This line runs express between 96 St and 168 St during rush hours, skipping local stops in
+            between. Weekend service runs local along the full route, with some stations closed for
+            planned maintenance.
+          </Text>
+          <Text style={styles.cardBody}>
+            Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
+            entrances before you travel.
+          </Text>
+        </View>
+      </BottomSheet>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'BottomSheet',
+  group: 'Navigation',
+  description: 'A sheet that slides up over a dismissible backdrop. Height is driven by its content (not fixed snap points) up to 90% of the available height, then the content area scrolls. Compose header with TopNav and footer with Dock.',
+  whenToUse: 'For longer, browsable content, or anything that benefits from a TopNav/Dock header-footer structure. For a short, focused decision that interrupts the flow, use Dialog.',
+  a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; header/content/footer carry their own accessibility (e.g. TopNav\'s title as accessibilityRole="header").',
+  render: () => <BottomSheetDemo />,
+});

package/starter-kit/components/BottomSheet/BottomSheet.tsx

@@ -0,0 +1,151 @@
+import React, { createContext, type ReactNode, isValidElement, cloneElement, useContext, useEffect, useRef, useState } from 'react';
+import { View, Pressable, ScrollView, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SHADOW, DS_SPACING, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+import { Dock, type DockProps } from '../Dock';
+
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+const MAX_HEIGHT_PERCENT = '90%';
+
+/** True while rendering inside an already-open BottomSheet's tree (header/children/footer alike).
+ *  Any component that opens its OWN BottomSheet (e.g. Dropdown) reads this via
+ *  `useInsideBottomSheetWarning` to dev-warn against stacking two sheets — a sheet already covers
+ *  the whole screen, so a second one has nowhere sensible to appear and just traps the user between
+ *  two backdrops. Defaults to `false` for anything rendered outside a BottomSheet entirely. */
+const BottomSheetContext = createContext(false);
+
+/** Call this from a component that opens its own BottomSheet (Dropdown, another picker, …) — warns
+ *  once per render if it's currently nested inside a different, already-open BottomSheet. Console
+ *  warning only (never throws), matching this codebase's other dev-time consistency checks (e.g.
+ *  ButtonGroup's `checkConsistency`). */
+export function useInsideBottomSheetWarning(componentName: string): void {
+  const insideBottomSheet = useContext(BottomSheetContext);
+  if (insideBottomSheet) {
+    console.warn(
+      `[${componentName}] is opening a BottomSheet from inside another, already-open BottomSheet. Never stack two sheets — restructure so ${componentName} lives outside the outer sheet (e.g. in the screen that opens it), or replace it with an inline control (e.g. SegmentedToggle/Radio) for use inside a sheet.`,
+    );
+  }
+}
+
+export interface BottomSheetProps {
+  /** Whether the sheet (and its backdrop) are mounted and shown. */
+  visible: boolean;
+  /** Called when the backdrop is tapped — the sheet doesn't close itself; the caller decides. */
+  onDismiss: () => void;
+  /** Top area — typically a TopNav with a close/back action. */
+  header?: ReactNode;
+  /** Middle content area. Grows with its content up to 90% of the available height, then scrolls. */
+  children: ReactNode;
+  /** Bottom area — typically a Dock with the sheet's primary actions. When `footer` is a Dock
+   *  element, its `elevated` prop is driven automatically from whether the content area above it
+   *  actually overflows (needs to scroll) — no need to pass `elevated` yourself. */
+  footer?: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A sheet that slides up from the bottom over a dismissible backdrop. Height is driven by its
+ * content (not a fixed set of snap points) up to a cap, past which the content area scrolls. Not
+ * portaled through RN's `Modal` — it's a plain absolutely-positioned overlay, so it fills whichever
+ * parent View hosts it (RN Views are positioning contexts by default), which also lets the catalog
+ * contain a live demo inside a bounded preview frame instead of covering the whole page.
+ */
+export function BottomSheet({ visible, onDismiss, header, children, footer, style }: BottomSheetProps) {
+  const progress = useRef(new Animated.Value(0)).current;
+  const [mounted, setMounted] = useState(visible);
+  // The sheet's own rendered height, measured via onLayout — its closed position is "translated
+  // down by exactly its own height" (fully below the visible area), not a small fixed nudge, so the
+  // motion genuinely reads as sliding in from off-screen regardless of how tall the content is.
+  // Falls back to a generous guess before the first measurement lands, to avoid a jump on first open.
+  const [sheetHeight, setSheetHeight] = useState(0);
+  // Drives a Dock footer's `elevated` shadow: on only once the content area's actual measured
+  // height exceeds what it's laid out to show, i.e. it's genuinely scrollable — not just "there is
+  // a Dock", so a short sheet stays flat and only a scrolling one gets the separating shadow.
+  const [scrollLayoutHeight, setScrollLayoutHeight] = useState(0);
+  const [scrollContentHeight, setScrollContentHeight] = useState(0);
+  const contentOverflows = scrollContentHeight > scrollLayoutHeight + 1;
+
+  useEffect(() => {
+    if (visible) setMounted(true);
+    // Backdrop opacity still fades (a scrim has no position to slide from); the sheet itself only
+    // ever moves via translateY below — no opacity animation on the sheet, just the slide.
+    const anim = Animated.timing(progress, {
+      toValue: visible ? 1 : 0,
+      duration: visible ? DS_MOTION_DURATION.base : DS_MOTION_DURATION.fast,
+      // `decelerate` — a sheet entering the screen, per DS_MOTION_EASING_USE (previously left on
+      // RN's default in-out ease, the one enter/exit overlay without an explicit curve).
+      easing: Easing.bezier(...DS_MOTION_EASING.decelerate),
+      useNativeDriver: false,
+    });
+    anim.start(({ finished }) => {
+      if (finished && !visible) setMounted(false);
+    });
+    return () => anim.stop();
+  }, [visible, progress]);
+
+  if (!mounted) return null;
+
+  const translateY = progress.interpolate({ inputRange: [0, 1], outputRange: [sheetHeight || 400, 0] });
+
+  const resolvedFooter =
+    isValidElement(footer) && footer.type === Dock
+      ? cloneElement(footer as React.ReactElement<DockProps>, { elevated: contentOverflows })
+      : footer;
+
+  return (
+    <View style={styles.overlay} pointerEvents={visible ? 'auto' : 'none'}>
+      <AnimatedPressable
+        style={[styles.backdrop, { opacity: progress }]}
+        onPress={onDismiss}
+        accessibilityRole="button"
+        accessibilityLabel="Dismiss"
+      />
+      <Animated.View
+        onLayout={(e) => setSheetHeight(e.nativeEvent.layout.height)}
+        style={[styles.sheet, style, { transform: [{ translateY }] }]}
+        // Contain assistive-tech focus while open (iOS) — without this, content behind the scrim
+        // stays reachable by screen readers even though it's visually blocked.
+        accessibilityViewIsModal
+      >
+        <View style={styles.handle} />
+        <BottomSheetContext.Provider value>
+          {header}
+          <ScrollView
+            style={styles.content}
+            contentContainerStyle={styles.contentContainer}
+            bounces={false}
+            onLayout={(e) => setScrollLayoutHeight(e.nativeEvent.layout.height)}
+            onContentSizeChange={(_width, height) => setScrollContentHeight(height)}
+          >
+            {children}
+          </ScrollView>
+          {resolvedFooter}
+        </BottomSheetContext.Provider>
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: { ...StyleSheet.absoluteFillObject, justifyContent: 'flex-end' },
+  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  sheet: {
+    maxHeight: MAX_HEIGHT_PERCENT,
+    backgroundColor: DS_SEMANTIC.surface.white,
+    borderTopLeftRadius: DS_RADIUS.large,
+    borderTopRightRadius: DS_RADIUS.large,
+    ...DS_SHADOW.bottomSheet,
+  },
+  // Purely a visual affordance (this sheet has no drag-to-dismiss gesture wired up) — signals "you
+  // can swipe this" the same way native sheets do, sized to the common ~36×4 grabber convention.
+  handle: {
+    alignSelf: 'center',
+    width: 36,
+    height: 4,
+    borderRadius: DS_RADIUS.round,
+    backgroundColor: DS_SEMANTIC.border.light,
+    marginTop: DS_SPACING[300],
+    marginBottom: DS_SPACING[100],
+  },
+  content: { flexGrow: 0 },
+  contentContainer: { padding: DS_SPACING[800] },
+});

package/starter-kit/components/BottomSheet/index.ts

@@ -0,0 +1,2 @@
+export { BottomSheet, useInsideBottomSheetWarning } from './BottomSheet';
+export type { BottomSheetProps } from './BottomSheet';