@cdx-ui/components 0.2.2 → 0.2.4

package/docs/components/full-screen-dialog/content.md

@@ -0,0 +1,881 @@
+# Full Screen Dialog (https://design.candescent.com/docs/components/full-screen-dialog)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-fullscreendialog--default)
+
+A compound modal that presents a task as a full page. It shares the dialog's open state, focus trapping, and dismissal, and adds a back / title / close header. Bottom sheets, menus, selects, and picker popovers opened from it appear on top.
+
+```tsx
+import { Button, FullScreenDialog } from '@cdx-ui/components';
+```
+
+> [!NOTE]
+>
+> **Portal host**
+>
+> `ForgeDesignProvider` mounts the shared portal host automatically. If you do not use the
+> provider, mount one `PortalHost` from `@cdx-ui/primitives` near your app root. On web, to keep
+> the dialog inside an embedded surface such as a device preview, wrap that surface in
+> `PortalProvider` and give its `PortalHost` a `container` element inside it; the fixed overlay
+> stays inside only when an ancestor of the container sets a `transform`.
+
+## Basic
+
+Put a `ScrollView` inside `FullScreenDialog.Content` so the body scrolls under a fixed header. The header's close button closes the dialog unless you pass `onClose`. The popup always covers the viewport; on wide screens, add `w-full max-w-md self-center` to the header and content to keep the page at a phone reading width.
+
+```tsx
+import { useState } from 'react';
+import { Box, Button, FullScreenDialog, ScrollView, Text } from '@cdx-ui/components';
+
+const details = [
+  { label: 'From', value: 'Everyday Checking •••• 4642' },
+  { label: 'To', value: 'High-yield Savings •••• 5541' },
+  { label: 'Amount', value: '$250.00' },
+  { label: 'Frequency', value: 'Monthly on the 1st' },
+];
+
+export default function FullScreenDialogBasicDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={setOpen}>
+      <FullScreenDialog.Trigger asChild>
+        <Button>
+          <Button.Label>View transfer</Button.Label>
+        </Button>
+      </FullScreenDialog.Trigger>
+      <FullScreenDialog.Popup>
+        <FullScreenDialog.Header
+          title="Scheduled transfer"
+          className="w-full max-w-md self-center"
+        />
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <ScrollView className="flex-1" contentContainerClassName="gap-4 p-4">
+            {details.map((detail) => (
+              <Box key={detail.label} className="gap-1">
+                <Text color="secondary" size="sm">
+                  {detail.label}
+                </Text>
+                <Text>{detail.value}</Text>
+              </Box>
+            ))}
+            <Button onPress={() => setOpen(false)}>
+              <Button.Label>Done</Button.Label>
+            </Button>
+          </ScrollView>
+        </FullScreenDialog.Content>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## With footer
+
+`FullScreenDialog.Content` is a flex column, so actions placed after the `ScrollView` stay pinned above the bottom safe area while the body scrolls. Use `subtitle` for secondary context under the title, such as the payee.
+
+```tsx
+import { useState } from 'react';
+import {
+  Avatar,
+  Box,
+  Button,
+  Chip,
+  Divider,
+  FullScreenDialog,
+  Heading,
+  ListItem,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+
+const details = [
+  { label: 'From', value: 'Everyday Checking •••• 4642' },
+  { label: 'Deliver by', value: 'Friday, October 9' },
+  { label: 'Frequency', value: 'Monthly on the 9th' },
+  { label: 'Memo', value: 'Account 0193 — October' },
+];
+
+export default function FullScreenDialogWithFooterDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={setOpen}>
+      <FullScreenDialog.Trigger asChild>
+        <Button>
+          <Button.Label>Review payment</Button.Label>
+        </Button>
+      </FullScreenDialog.Trigger>
+      <FullScreenDialog.Popup>
+        <FullScreenDialog.Header
+          title="Review payment"
+          subtitle="Springfield Electric"
+          className="w-full max-w-md self-center"
+        />
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <ScrollView className="flex-1" contentContainerClassName="gap-6 p-4">
+            <Box className="items-center gap-3 py-4">
+              <Avatar size="2xl" color="brand" accessibilityLabel="Springfield Electric">
+                <Avatar.Text>Springfield Electric</Avatar.Text>
+              </Avatar>
+              <Heading size="xl">$84.12</Heading>
+              <Chip color="warning" size="small">
+                <Chip.Label>Scheduled</Chip.Label>
+              </Chip>
+            </Box>
+            <Box>
+              {details.map((detail, index) => (
+                <ListItem key={detail.label} showSeparator={index < details.length - 1}>
+                  <ListItem.Content>
+                    <ListItem.Description>{detail.label}</ListItem.Description>
+                    <ListItem.Title>{detail.value}</ListItem.Title>
+                  </ListItem.Content>
+                </ListItem>
+              ))}
+            </Box>
+            <Text color="secondary" size="sm">
+              Payments scheduled after 8 PM ET are processed the next business day. You can cancel
+              this payment until it starts processing.
+            </Text>
+          </ScrollView>
+          <Divider />
+          <Box className="gap-3 p-4">
+            <Button onPress={() => setOpen(false)}>
+              <Button.Label>Pay $84.12</Button.Label>
+            </Button>
+            <Button variant="ghost" onPress={() => setOpen(false)}>
+              <Button.Label>Edit payment</Button.Label>
+            </Button>
+          </Box>
+        </FullScreenDialog.Content>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## Custom triggers
+
+Use `asChild` to open the dialog from any pressable, such as a list item or a quick action button. A dialog can have more than one trigger. To open it from a menu item, control `isOpen` and set it from the item's `onPress`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  Button,
+  Card,
+  Chip,
+  FullScreenDialog,
+  Heading,
+  IconButton,
+  ListItem,
+  Menu,
+  QuickActionButton,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+import {
+  ChevronRight,
+  ContentCopy,
+  Download,
+  Info,
+  MoreHoriz,
+  Payments,
+  Send,
+} from '@cdx-ui/icons';
+
+const details = [
+  { label: 'Account number', value: '•••• •••• 4642', copyable: true },
+  { label: 'Routing number', value: '011000015', copyable: true },
+  { label: 'Interest rate', value: '0.01% APY', copyable: false },
+  { label: 'Opened', value: 'March 12, 2019', copyable: false },
+];
+
+export default function FullScreenDialogCustomTriggersDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={setOpen} className="w-full max-w-md gap-4">
+      <Card fullBleed>
+        <Card.Header>
+          <Heading size="sm">Everyday Checking</Heading>
+          <Menu placement="bottom-end">
+            <Menu.Trigger asChild>
+              <IconButton
+                as={MoreHoriz}
+                variant="ghost"
+                size="small"
+                accessibilityLabel="Everyday Checking actions"
+              />
+            </Menu.Trigger>
+            <Menu.Popup>
+              <Menu.Content accessibilityLabel="Everyday Checking actions">
+                <Menu.Item onPress={() => setOpen(true)}>
+                  <Menu.ItemLabel>Account details</Menu.ItemLabel>
+                </Menu.Item>
+                <Menu.Item onPress={() => undefined}>
+                  <Menu.ItemLabel>Manage alerts</Menu.ItemLabel>
+                </Menu.Item>
+              </Menu.Content>
+            </Menu.Popup>
+          </Menu>
+        </Card.Header>
+        <Card.Content>
+          <FullScreenDialog.Trigger asChild>
+            <ListItem showSeparator={false} accessibilityHint="Opens account details">
+              <ListItem.Content>
+                <ListItem.Description>Available balance</ListItem.Description>
+                <ListItem.Title>$2,418.07</ListItem.Title>
+              </ListItem.Content>
+              <ListItem.TrailingSlot>
+                <ChevronRight size={20} />
+              </ListItem.TrailingSlot>
+            </ListItem>
+          </FullScreenDialog.Trigger>
+        </Card.Content>
+      </Card>
+
+      <Box className="flex-row justify-center gap-4">
+        <QuickActionButton>
+          <QuickActionButton.Icon as={Send} />
+          <QuickActionButton.Label>Transfer</QuickActionButton.Label>
+        </QuickActionButton>
+        <QuickActionButton>
+          <QuickActionButton.Icon as={Payments} />
+          <QuickActionButton.Label>Pay</QuickActionButton.Label>
+        </QuickActionButton>
+        <FullScreenDialog.Trigger asChild>
+          <QuickActionButton>
+            <QuickActionButton.Icon as={Info} />
+            <QuickActionButton.Label>Details</QuickActionButton.Label>
+          </QuickActionButton>
+        </FullScreenDialog.Trigger>
+      </Box>
+
+      <FullScreenDialog.Popup>
+        <FullScreenDialog.Header
+          title="Account details"
+          subtitle="Everyday Checking •••• 4642"
+          className="w-full max-w-md self-center"
+        />
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <ScrollView className="flex-1" contentContainerClassName="gap-6 p-4">
+            <Box className="items-center gap-2 py-4">
+              <Text color="secondary" size="sm">
+                Available balance
+              </Text>
+              <Heading size="xl">$2,418.07</Heading>
+              <Chip color="success" size="small">
+                <Chip.Label>Active</Chip.Label>
+              </Chip>
+            </Box>
+            <Box>
+              {details.map((detail, index) => (
+                <ListItem key={detail.label} showSeparator={index < details.length - 1}>
+                  <ListItem.Content>
+                    <ListItem.Description>{detail.label}</ListItem.Description>
+                    <ListItem.Title>{detail.value}</ListItem.Title>
+                  </ListItem.Content>
+                  {detail.copyable ? (
+                    <ListItem.TrailingSlot>
+                      <IconButton
+                        as={ContentCopy}
+                        variant="ghost"
+                        size="small"
+                        accessibilityLabel={`Copy ${detail.label.toLowerCase()}`}
+                        onPress={() => undefined}
+                      />
+                    </ListItem.TrailingSlot>
+                  ) : null}
+                </ListItem>
+              ))}
+            </Box>
+            <Button variant="outline">
+              <Button.Icon as={Download} position="leading" />
+              <Button.Label>Download statements</Button.Label>
+            </Button>
+          </ScrollView>
+        </FullScreenDialog.Content>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## Header content
+
+Pass `children` to `FullScreenDialog.Header` to replace the title, for example with a search field. The back and close buttons stay in place. Without a title, the popup has no accessible name, so set `aria-label` on `FullScreenDialog.Popup`.
+
+```tsx
+import { useState } from 'react';
+import {
+  Avatar,
+  Box,
+  FullScreenDialog,
+  Input,
+  ListItem,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+import { Check, ChevronRight, Search } from '@cdx-ui/icons';
+
+const payees = [
+  { id: 'electric', name: 'Springfield Electric', detail: 'Account •••• 0193' },
+  { id: 'water', name: 'Shelbyville Water', detail: 'Account •••• 7720' },
+  { id: 'mortgage', name: 'Evergreen Mortgage', detail: 'Loan •••• 4410' },
+  { id: 'internet', name: 'Lakeside Fiber', detail: 'Account •••• 3358' },
+  { id: 'insurance', name: 'Harbor Auto Insurance', detail: 'Policy •••• 9021' },
+  { id: 'phone', name: 'Northwind Wireless', detail: 'Account •••• 6634' },
+];
+
+export default function FullScreenDialogHeaderContentDemo() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [payeeId, setPayeeId] = useState('electric');
+  const payee = payees.find((item) => item.id === payeeId);
+  const matches = payees.filter((item) =>
+    item.name.toLowerCase().includes(query.trim().toLowerCase()),
+  );
+
+  const handleOpenChange = (next: boolean) => {
+    if (next) setQuery('');
+    setOpen(next);
+  };
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={handleOpenChange} className="w-full max-w-md">
+      <Text color="secondary" size="sm">
+        Pay to
+      </Text>
+      <FullScreenDialog.Trigger asChild>
+        <ListItem showSeparator={false} accessibilityHint="Opens a searchable list of payees">
+          <ListItem.LeadingSlot>
+            <Avatar size="lg" color="brand" accessibilityLabel={payee?.name ?? 'Payee'}>
+              <Avatar.Text>{payee?.name ?? ''}</Avatar.Text>
+            </Avatar>
+          </ListItem.LeadingSlot>
+          <ListItem.Content>
+            <ListItem.Title>{payee?.name ?? 'Choose a payee'}</ListItem.Title>
+            <ListItem.Description>{payee?.detail}</ListItem.Description>
+          </ListItem.Content>
+          <ListItem.TrailingSlot>
+            <ChevronRight size={20} />
+          </ListItem.TrailingSlot>
+        </ListItem>
+      </FullScreenDialog.Trigger>
+
+      <FullScreenDialog.Popup aria-label="Choose a payee">
+        <FullScreenDialog.Header
+          closeAccessibilityLabel="Cancel"
+          className="w-full max-w-md self-center"
+        >
+          <Box className="px-2">
+            <Input variant="outline">
+              <Input.Slot>
+                <Input.Icon as={Search} />
+              </Input.Slot>
+              <Input.Field
+                accessibilityLabel="Search payees"
+                placeholder="Search payees"
+                value={query}
+                onChangeText={setQuery}
+                autoCorrect={false}
+                returnKeyType="search"
+              />
+            </Input>
+          </Box>
+        </FullScreenDialog.Header>
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <ScrollView
+            className="flex-1"
+            contentContainerClassName="p-4"
+            keyboardShouldPersistTaps="handled"
+            keyboardDismissMode="on-drag"
+          >
+            {matches.map((item, index) => (
+              <ListItem
+                key={item.id}
+                showSeparator={index < matches.length - 1}
+                accessibilityState={{ selected: item.id === payeeId }}
+                onPress={() => {
+                  setPayeeId(item.id);
+                  setOpen(false);
+                }}
+              >
+                <ListItem.LeadingSlot>
+                  <Avatar size="lg" accessibilityLabel={item.name}>
+                    <Avatar.Text>{item.name}</Avatar.Text>
+                  </Avatar>
+                </ListItem.LeadingSlot>
+                <ListItem.Content>
+                  <ListItem.Title>{item.name}</ListItem.Title>
+                  <ListItem.Description>{item.detail}</ListItem.Description>
+                </ListItem.Content>
+                {item.id === payeeId ? (
+                  <ListItem.TrailingSlot>
+                    <Check size={20} />
+                  </ListItem.TrailingSlot>
+                ) : null}
+              </ListItem>
+            ))}
+            {matches.length === 0 ? (
+              <Box className="items-center gap-1 py-8">
+                <Text>No payees found</Text>
+                <Text color="secondary" size="sm">
+                  Try a different name, or add a new payee.
+                </Text>
+              </Box>
+            ) : null}
+          </ScrollView>
+        </FullScreenDialog.Content>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## Multi-step flow
+
+Keep the step index in your own state and render the current step. Set `onBack` on the header only after the first step: it shows the back button and also handles Android system back, so both go back one step. Steps that unmount lose their local state, so keep form values above the steps. A `ProgressSegmented` placed before the `ScrollView` stays fixed under the header.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  Button,
+  Field,
+  FullScreenDialog,
+  Input,
+  ListItem,
+  ProgressSegmented,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+
+const steps = ['Choose account', 'Enter amount', 'Review transfer'];
+
+const accounts = [
+  { id: 'checking', name: 'Everyday Checking •••• 4642', balance: '$2,418.07' },
+  { id: 'savings', name: 'High-yield Savings •••• 5541', balance: '$16,163.04' },
+  { id: 'money-market', name: 'Money Market •••• 2323', balance: '$55,847.23' },
+];
+
+export default function FullScreenDialogMultiStepDemo() {
+  const [open, setOpen] = useState(false);
+  const [step, setStep] = useState(0);
+  const [accountId, setAccountId] = useState<string | undefined>();
+  const [amount, setAmount] = useState('');
+  const account = accounts.find((item) => item.id === accountId);
+
+  const handleOpenChange = (next: boolean) => {
+    if (next) setStep(0);
+    setOpen(next);
+  };
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={handleOpenChange}>
+      <FullScreenDialog.Trigger asChild>
+        <Button>
+          <Button.Label>Start transfer</Button.Label>
+        </Button>
+      </FullScreenDialog.Trigger>
+      <FullScreenDialog.Popup>
+        <FullScreenDialog.Header
+          title={steps[step]}
+          subtitle={`Step ${step + 1} of ${steps.length}`}
+          onBack={step > 0 ? () => setStep((current) => current - 1) : undefined}
+          className="w-full max-w-md self-center"
+        />
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <Box className="px-4 pt-2">
+            <ProgressSegmented
+              step={step + 1}
+              segments={steps.length}
+              accessibilityLabel="Transfer progress"
+            />
+          </Box>
+          <ScrollView
+            className="flex-1"
+            contentContainerClassName="gap-4 p-4"
+            automaticallyAdjustKeyboardInsets
+            keyboardShouldPersistTaps="handled"
+          >
+            {step === 0 ? (
+              <Box>
+                {accounts.map((item, index) => (
+                  <ListItem
+                    key={item.id}
+                    showSeparator={index < accounts.length - 1}
+                    onPress={() => {
+                      setAccountId(item.id);
+                      setStep(1);
+                    }}
+                  >
+                    <ListItem.Content>
+                      <ListItem.Title>{item.name}</ListItem.Title>
+                      <ListItem.Description>{`Available: ${item.balance}`}</ListItem.Description>
+                    </ListItem.Content>
+                  </ListItem>
+                ))}
+              </Box>
+            ) : null}
+            {step === 1 ? (
+              <>
+                <Field>
+                  <Field.Label>Amount</Field.Label>
+                  <Input variant="outline">
+                    <Input.Field
+                      placeholder="$0.00"
+                      keyboardType="decimal-pad"
+                      value={amount}
+                      onChangeText={setAmount}
+                    />
+                  </Input>
+                </Field>
+                <Button onPress={() => setStep(2)} isDisabled={amount === ''}>
+                  <Button.Label>Continue</Button.Label>
+                </Button>
+              </>
+            ) : null}
+            {step === 2 ? (
+              <>
+                <Box className="gap-1">
+                  <Text color="secondary" size="sm">
+                    From
+                  </Text>
+                  <Text>{account?.name ?? '—'}</Text>
+                </Box>
+                <Box className="gap-1">
+                  <Text color="secondary" size="sm">
+                    Amount
+                  </Text>
+                  <Text>{`$${amount}`}</Text>
+                </Box>
+                <Button onPress={() => setOpen(false)}>
+                  <Button.Label>Submit transfer</Button.Label>
+                </Button>
+              </>
+            ) : null}
+          </ScrollView>
+        </FullScreenDialog.Content>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## Discard confirmation
+
+Control the dialog and intercept `onOpenChange(false)`, which fires for the close button, Escape, and Android back when the header has no `onBack`. When there are unsaved changes, open an `AlertDialog` instead of closing. Escape on the alert dialog is consumed by the alert dialog, so the full-screen dialog beneath stays open.
+
+```tsx
+import { useState } from 'react';
+import {
+  AlertDialog,
+  Button,
+  Field,
+  FullScreenDialog,
+  Input,
+  ScrollView,
+  Text,
+} from '@cdx-ui/components';
+
+export default function FullScreenDialogDiscardConfirmationDemo() {
+  const [open, setOpen] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const [savedNickname, setSavedNickname] = useState('Everyday Checking');
+  const [nickname, setNickname] = useState(savedNickname);
+  const isDirty = nickname !== savedNickname;
+
+  const handleOpenChange = (next: boolean) => {
+    if (next) {
+      setNickname(savedNickname);
+      setOpen(true);
+    } else if (isDirty) {
+      setConfirmOpen(true);
+    } else {
+      setOpen(false);
+    }
+  };
+
+  return (
+    <>
+      <FullScreenDialog isOpen={open} onOpenChange={handleOpenChange}>
+        <FullScreenDialog.Trigger asChild>
+          <Button variant="outline">
+            <Button.Label>Rename account</Button.Label>
+          </Button>
+        </FullScreenDialog.Trigger>
+        <FullScreenDialog.Popup>
+          <FullScreenDialog.Header title="Rename account" className="w-full max-w-md self-center" />
+          <FullScreenDialog.Content className="w-full max-w-md self-center">
+            <ScrollView
+              className="flex-1"
+              contentContainerClassName="gap-4 p-4"
+              automaticallyAdjustKeyboardInsets
+              keyboardShouldPersistTaps="handled"
+            >
+              <Field>
+                <Field.Label>Account nickname</Field.Label>
+                <Input variant="outline">
+                  <Input.Field value={nickname} onChangeText={setNickname} />
+                </Input>
+              </Field>
+              <Text color="secondary" size="sm">
+                {isDirty ? 'Unsaved changes' : 'No changes'}
+              </Text>
+              <Button
+                isDisabled={!isDirty}
+                onPress={() => {
+                  setSavedNickname(nickname);
+                  setOpen(false);
+                }}
+              >
+                <Button.Label>Save</Button.Label>
+              </Button>
+            </ScrollView>
+          </FullScreenDialog.Content>
+        </FullScreenDialog.Popup>
+      </FullScreenDialog>
+
+      <AlertDialog isOpen={confirmOpen} onOpenChange={setConfirmOpen}>
+        <AlertDialog.Popup>
+          <AlertDialog.Header>
+            <AlertDialog.Title severity="warning">Discard changes?</AlertDialog.Title>
+          </AlertDialog.Header>
+          <AlertDialog.Content>
+            <AlertDialog.Text>Your new account nickname won&apos;t be saved.</AlertDialog.Text>
+          </AlertDialog.Content>
+          <AlertDialog.Footer>
+            <AlertDialog.Cancel>Keep editing</AlertDialog.Cancel>
+            <AlertDialog.Action
+              color="danger"
+              onPress={() => {
+                setConfirmOpen(false);
+                setOpen(false);
+              }}
+            >
+              Discard
+            </AlertDialog.Action>
+          </AlertDialog.Footer>
+        </AlertDialog.Popup>
+      </AlertDialog>
+    </>
+  );
+}
+```
+
+## With a bottom sheet
+
+Declare the `BottomSheet.Modal` inside `FullScreenDialog.Popup`, which provides its own sheet host, so the sheet presents above the dialog. Android back and Escape close the sheet before the dialog.
+
+```tsx
+import { useState } from 'react';
+import {
+  BottomSheet,
+  Box,
+  Button,
+  FullScreenDialog,
+  ListItem,
+  ScrollView,
+  Text,
+  useBottomSheet,
+} from '@cdx-ui/components';
+import { Check, ChevronRight } from '@cdx-ui/icons';
+
+const accounts = [
+  { id: 'checking', name: 'Everyday Checking •••• 4642', balance: '$2,418.07' },
+  { id: 'savings', name: 'High-yield Savings •••• 5541', balance: '$16,163.04' },
+  { id: 'money-market', name: 'Money Market •••• 2323', balance: '$55,847.23' },
+];
+
+export default function FullScreenDialogBottomSheetDemo() {
+  const [open, setOpen] = useState(false);
+  const [fromId, setFromId] = useState('checking');
+  const { ref, present, dismiss } = useBottomSheet();
+  const from = accounts.find((account) => account.id === fromId);
+
+  return (
+    <FullScreenDialog isOpen={open} onOpenChange={setOpen}>
+      <FullScreenDialog.Trigger asChild>
+        <Button>
+          <Button.Label>Edit transfer</Button.Label>
+        </Button>
+      </FullScreenDialog.Trigger>
+      <FullScreenDialog.Popup>
+        <FullScreenDialog.Header title="Edit transfer" className="w-full max-w-md self-center" />
+        <FullScreenDialog.Content className="w-full max-w-md self-center">
+          <ScrollView className="flex-1" contentContainerClassName="gap-4 p-4">
+            <Box>
+              <ListItem onPress={present} accessibilityHint="Opens a list of accounts">
+                <ListItem.Content>
+                  <ListItem.Description>From</ListItem.Description>
+                  <ListItem.Title>{from?.name ?? 'Choose an account'}</ListItem.Title>
+                </ListItem.Content>
+                <ListItem.TrailingSlot>
+                  <ChevronRight size={20} />
+                </ListItem.TrailingSlot>
+              </ListItem>
+              <ListItem showSeparator={false}>
+                <ListItem.Content>
+                  <ListItem.Description>To</ListItem.Description>
+                  <ListItem.Title>Rent account •••• 8810</ListItem.Title>
+                </ListItem.Content>
+              </ListItem>
+            </Box>
+            <Text color="secondary" size="sm">
+              The account sheet is declared inside the popup, so it presents above the dialog.
+            </Text>
+            <Button onPress={() => setOpen(false)}>
+              <Button.Label>Save changes</Button.Label>
+            </Button>
+          </ScrollView>
+        </FullScreenDialog.Content>
+
+        <BottomSheet.Modal ref={ref}>
+          <BottomSheet.View>
+            <BottomSheet.Header title="Transfer from" onClose={dismiss} />
+            <BottomSheet.Content>
+              {accounts.map((account, index) => (
+                <ListItem
+                  key={account.id}
+                  showSeparator={index < accounts.length - 1}
+                  accessibilityState={{ selected: account.id === fromId }}
+                  onPress={() => {
+                    setFromId(account.id);
+                    dismiss();
+                  }}
+                >
+                  <ListItem.Content>
+                    <ListItem.Title>{account.name}</ListItem.Title>
+                    <ListItem.Description>{`Available: ${account.balance}`}</ListItem.Description>
+                  </ListItem.Content>
+                  {account.id === fromId ? (
+                    <ListItem.TrailingSlot>
+                      <Check size={20} />
+                    </ListItem.TrailingSlot>
+                  ) : null}
+                </ListItem>
+              ))}
+            </BottomSheet.Content>
+          </BottomSheet.View>
+        </BottomSheet.Modal>
+      </FullScreenDialog.Popup>
+    </FullScreenDialog>
+  );
+}
+```
+
+## API
+
+### FullScreenDialog
+
+Controls open state and Escape dismissal. There is no backdrop to press, so `closeOnBackdropPress` is not available, and there is no `size`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Classes for the root wrapper around the trigger. |
+| `children` | `ReactNode` | — | `FullScreenDialog.Trigger` and `FullScreenDialog.Popup`. |
+| `onOpenChange?` | `((open: boolean) => void)` | — | Called with the next open state. Fires `false` for the header close button, Escape, and Android back while the header has no `onBack`. |
+| `defaultOpen?` | `boolean` | `false` | Initial open state when uncontrolled. |
+| `closeOnEscKey?` | `boolean` | `true` | Close when Escape is pressed. Web only. Escape never steps back; Android back is routed by the header's `onBack` independently of this prop. |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `animation?` | `'disable-all'` | — | Pass `'disable-all'` to turn off the popup's enter and exit motion. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props), except `children` and `role`.
+
+## Sub-components
+
+### FullScreenDialog.Trigger
+
+Opens the dialog when pressed. Use `asChild` to merge trigger behavior onto a `Button` or another pressable element.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Classes for the trigger. |
+| `children?` | `ReactNode` | — | Content that opens the dialog when pressed. |
+| `asChild?` | `boolean` | — | Render the single child as the trigger instead of a `Pressable`. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### FullScreenDialog.Popup
+
+The page surface. It covers the viewport with the primary surface color and has no backdrop, corner radius, swipe-to-dismiss, or keyboard-avoiding layer. Bottom sheets declared inside it present above it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Classes for the page surface, merged after the defaults. |
+| `children?` | `ReactNode` | — | `FullScreenDialog.Header` and `FullScreenDialog.Content`. Bottom sheets declared here present above the page. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute    | Value                            | Description                                    |
+| ------------ | -------------------------------- | ---------------------------------------------- |
+| `data-state` | `entering` \| `open` \| `closed` | Web only. Drives the enter and exit transition |
+
+### FullScreenDialog.Header
+
+Back / title / close row that clears the top safe-area inset. It takes the same props as [`BottomSheet.Header`](https://design.candescent.com/docs/components/bottom-sheet/content.md), except that the close button closes the dialog by default. The back button appears only while `onBack` is set. An unused back or close position keeps its space so the title stays centered, but it is not rendered as a button.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title?` | `string` | — | Title text. Labels the dialog. Ignored when `children` is set. |
+| `subtitle?` | `string` | — | Secondary line under the title. Has no effect without `title`, or when `children` is set. |
+| `children?` | `ReactNode` | — | Custom header content. Replaces `title` and `subtitle`. The consumer then owns the dialog's accessible name and focus on step change: focus doesn't move to the header. |
+| `className?` | `string` | — | Classes for the header region, which includes the top safe-area padding. |
+| `onClose?` | `(() => void)` | `Closes the dialog (`onOpenChange(false)`).` | Called by the close button. |
+| `closeAccessibilityLabel?` | `string` | `Close` | Accessible name for the close button. |
+| `onBack?` | `(() => void)` | — | Shows the back button when set. Android system back calls it too, instead of closing the dialog. Escape on web always closes. |
+| `backAccessibilityLabel?` | `string` | `Go back` | Accessible name for the back button. |
+
+### FullScreenDialog.Content
+
+Flex region under the header that clears the bottom safe-area inset. It does not scroll by itself; put a `ScrollView` inside it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Classes for the content region, merged after the defaults. |
+| `children?` | `ReactNode` | — | Page body. Usually a `ScrollView`. |
+| `asChild?` | `boolean` | — | Render the single child as the content region instead of a `View`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`                  | Element                                            |
+| ---------------------------- | -------------------------------------------------- |
+| `full-screen-dialog`         | Root wrapper around the trigger                    |
+| `full-screen-dialog-trigger` | Trigger                                            |
+| `full-screen-dialog-popup`   | Page surface with `role="dialog"`                  |
+| `full-screen-dialog-header`  | Header region, including the top safe-area padding |
+| `full-screen-dialog-content` | Body region under the header                       |
+
+## Accessibility
+
+- The popup receives `role="dialog"`, `aria-modal`, and `aria-labelledby` pointing at the header title.
+- Focus moves into the popup, remains trapped while open, and returns to the trigger after close.
+- When the header `title` changes, or `onBack` switches between set and unset, focus moves to the header title on web and screen-reader focus moves there on native, so the new step is announced. This does not happen when the dialog first opens.
+- When you pass custom `children` to `FullScreenDialog.Header`, the title is not rendered, so you own the dialog's accessible name and moving focus on a step change. Set `aria-label` on `FullScreenDialog.Popup` to name the dialog.
+- Android system back calls the header's `onBack` while it is set, and the dialog stays open. Without `onBack`, it closes the dialog.
+- Escape closes the dialog on web when `closeOnEscKey` is enabled. It never steps back, even while `onBack` is set.
+- Android back and Escape go to the topmost overlay first. A presented bottom sheet, or a dialog or select opened from the full-screen dialog, handles them before the full-screen dialog does.
+- The back and close buttons default to the accessible names "Go back" and "Close".
+
+## Constraints
+
+- A shared `PortalHost` must be mounted once near the app root. `ForgeDesignProvider` includes one.
+- Declare every `BottomSheet.Modal` you open from the dialog inside `FullScreenDialog.Popup`. The popup provides its own sheet host. A sheet declared outside the popup, for example as a sibling of `FullScreenDialog`, presents through the root host and stays beneath the dialog.
+- Sheets opened from the dialog need a `GestureHandlerRootView` at the app root, wrapping `ForgeDesignProvider`. This is the same requirement as any other `BottomSheet`.
+- Launching a full-screen dialog from a React Navigation native modal screen (`modal`, `formSheet`, `fullScreenModal`) is not supported in this version. On iOS the dialog renders underneath the presenting screen.
+- There is no built-in keyboard avoidance. Make a `ScrollView` inside `FullScreenDialog.Content` the scroll container, and set `automaticallyAdjustKeyboardInsets` and `keyboardShouldPersistTaps="handled"` on it, as the multi-step and discard demos do. `automaticallyAdjustKeyboardInsets` applies on iOS. On Android, confirm the behavior on a device; it varies with edge-to-edge configuration. Do not wrap the dialog in a `KeyboardAvoidingView`.
+- The dialog holds no step state and adds no browser history entry. It is a modal, not a navigator screen, so it does not get the iOS edge-swipe back gesture.
+- Pass `animation="disable-all"` on `FullScreenDialog` to turn off the enter and exit motion. Reduced-motion settings are respected on every platform.
+
+## When to use
+
+| Component          | Use for                                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `FullScreenDialog` | A task that needs the whole screen, such as editing a transfer or a multi-step setup, and returns to the same place when done |
+| `Dialog`           | A short confirmation or a small form on a centered card                                                                       |
+| `Drawer`           | Filters, settings, or navigation on a panel attached to an edge of the viewport                                               |
+| `BottomSheet`      | A secondary task at partial height that keeps the page behind it in view                                                      |
+| A navigator screen | A page that needs its own URL or deep link, or a place in the navigation history                                              |