@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/toast/content.md

@@ -0,0 +1,456 @@
+# Toast (https://design.candescent.com/docs/components/toast)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=5170-8043), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-toast--default)
+
+A stacking notification surface shown imperatively through `useToast()`. Toasts auto-dismiss, can be swiped away on native, and are rendered by the provider rather than at the call site.
+
+```tsx
+import { Toast, ToastProvider, useToast } from '@cdx-ui/components';
+```
+
+> [!WARNING]
+>
+> **Provider required**
+>
+> Mount `ToastProvider` once near your app root — `ForgeDesignProvider` includes it automatically.
+> `useToast()` throws when no provider is above it in the tree.
+
+## Basic
+
+The provider owns the toast viewport, so a toast anchors to the edge of the window no matter where `toast.show()` was called from.
+
+```tsx
+import { Button, useToast } from '@cdx-ui/components';
+
+export default function ToastBasicDemo() {
+  const { toast } = useToast();
+
+  return (
+    <Button
+      onPress={() =>
+        toast.show({
+          label: 'Payment scheduled',
+          description: 'Your $250.00 payment will be sent on Friday.',
+        })
+      }
+    >
+      <Button.Label>Show toast</Button.Label>
+    </Button>
+  );
+}
+```
+
+## Colors
+
+`color` sets the surface fill and the title, description, and icon. `neutral` is a dark inverse surface; status values use the matching subtle fill and on-subtle content color.
+
+```tsx
+import { Button, HStack, useToast, type ToastColor } from '@cdx-ui/components';
+
+const scenarios: {
+  color: ToastColor;
+  buttonColor: 'action' | 'danger' | 'warning' | 'success';
+  label: string;
+  description: string;
+}[] = [
+  {
+    color: 'neutral',
+    buttonColor: 'action',
+    label: 'Statement ready',
+    description: 'Your July statement is available to download.',
+  },
+  {
+    color: 'info',
+    buttonColor: 'action',
+    label: 'Scheduled maintenance',
+    description: 'Transfers are unavailable Sunday from 1–3 AM ET.',
+  },
+  {
+    color: 'success',
+    buttonColor: 'success',
+    label: 'Transfer complete',
+    description: '$250.00 was sent to Jordan Ellis.',
+  },
+  {
+    color: 'warning',
+    buttonColor: 'warning',
+    label: 'Low balance',
+    description: 'Everyday Checking is below your $100.00 alert threshold.',
+  },
+  {
+    color: 'danger',
+    buttonColor: 'danger',
+    label: 'Payment failed',
+    description: 'The card ending in 4821 was declined.',
+  },
+];
+
+export default function ToastColorsDemo() {
+  const { toast } = useToast();
+
+  return (
+    <HStack space="sm" className="flex-wrap justify-center">
+      {scenarios.map((scenario) => (
+        <Button
+          key={scenario.color}
+          variant="outline"
+          color={scenario.buttonColor}
+          onPress={() =>
+            toast.show({
+              color: scenario.color,
+              label: scenario.label,
+              description: scenario.description,
+            })
+          }
+        >
+          <Button.Label>{scenario.color}</Button.Label>
+        </Button>
+      ))}
+    </HStack>
+  );
+}
+```
+
+## Placements
+
+On web, `-start` and `-end` pin the toast to that horizontal edge and cap it at 460 px; plain `top` and `bottom` center it. On native every value spans the full width. Each placement maintains an independent stack, so toasts elsewhere do not affect its index, visibility, or animation.
+
+```tsx
+import { Button, HStack, useToast, type ToastPlacement } from '@cdx-ui/components';
+
+const placements: ToastPlacement[] = [
+  'top-start',
+  'top',
+  'top-end',
+  'bottom-start',
+  'bottom',
+  'bottom-end',
+];
+
+export default function ToastPlacementsDemo() {
+  const { toast } = useToast();
+
+  return (
+    <HStack space="sm" className="flex-wrap justify-center">
+      {placements.map((placement) => (
+        <Button
+          key={placement}
+          variant="outline"
+          onPress={() =>
+            toast.show({
+              placement,
+              label: `Placed at ${placement}`,
+            })
+          }
+        >
+          <Button.Label>{placement}</Button.Label>
+        </Button>
+      ))}
+    </HStack>
+  );
+}
+```
+
+## With icon
+
+Pass a Forge icon to `icon`. It renders through `Toast.Icon`, so it picks up the toast's color automatically.
+
+```tsx
+import { CheckCircle } from '@cdx-ui/icons';
+import { Button, useToast } from '@cdx-ui/components';
+
+export default function ToastWithIconDemo() {
+  const { toast } = useToast();
+
+  return (
+    <Button
+      variant="outline"
+      color="success"
+      onPress={() =>
+        toast.show({
+          color: 'success',
+          icon: CheckCircle,
+          label: 'Direct deposit received',
+          description: '$1,200.00 was added to Everyday Checking.',
+        })
+      }
+    >
+      <Button.Label>Show toast with icon</Button.Label>
+    </Button>
+  );
+}
+```
+
+## With action
+
+`onActionPress` receives `{ show, hide }` so an action can dismiss the current toast and confirm the result. Dismissal is not automatic — call `hide()` yourself.
+
+```tsx
+import { Button, useToast } from '@cdx-ui/components';
+
+export default function ToastWithActionDemo() {
+  const { toast } = useToast();
+
+  return (
+    <Button
+      variant="outline"
+      onPress={() =>
+        toast.show({
+          label: 'Payee deleted',
+          description: 'Jordan Ellis was removed from your saved payees.',
+          actionLabel: 'Undo',
+          onActionPress: ({ hide, show }) => {
+            hide();
+            show({ color: 'success', label: 'Payee restored' });
+          },
+        })
+      }
+    >
+      <Button.Label>Delete payee</Button.Label>
+    </Button>
+  );
+}
+```
+
+## Persistent
+
+Set `duration: 'persistent'` for progress that ends on a real event instead of a timer, and pass an explicit `id` so you can dismiss it later. Re-showing an `id` that is already visible is a no-op.
+
+```tsx
+import { Sync } from '@cdx-ui/icons';
+import { Button, HStack, useToast } from '@cdx-ui/components';
+
+const UPLOAD_TOAST_ID = 'check-deposit-upload';
+
+export default function ToastPersistentDemo() {
+  const { toast } = useToast();
+
+  return (
+    <HStack space="sm" className="flex-wrap justify-center">
+      <Button
+        variant="outline"
+        onPress={() =>
+          toast.show({
+            id: UPLOAD_TOAST_ID,
+            color: 'info',
+            icon: Sync,
+            label: 'Uploading check images',
+            description: 'Keep this screen open until the upload finishes.',
+            duration: 'persistent',
+          })
+        }
+      >
+        <Button.Label>Start upload</Button.Label>
+      </Button>
+      <Button variant="ghost" onPress={() => toast.hide(UPLOAD_TOAST_ID)}>
+        <Button.Label>Finish upload</Button.Label>
+      </Button>
+    </HStack>
+  );
+}
+```
+
+## Custom content
+
+Use `component` to compose the toast from its sub-components. Spread the supplied props onto `Toast` — they carry the placement-specific stacking metrics and dismissal wiring that `Toast.Close` depends on. Place the sub-components as direct children; `Toast` lays them out for you, with the icon first, the title and description stacked beside it, and the action and close controls at the end, so no wrapper or layout `className` is needed. Set custom placement on `toast.show({ placement, component })` so the provider can assign the correct stack.
+
+```tsx
+import { CheckCircle } from '@cdx-ui/icons';
+import { Button, Toast, useToast, type ToastComponentProps } from '@cdx-ui/components';
+
+export default function ToastCustomComponentDemo() {
+  const { toast } = useToast();
+
+  return (
+    <Button
+      variant="outline"
+      color="success"
+      onPress={() =>
+        toast.show({
+          duration: 6000,
+          component: (props: ToastComponentProps) => (
+            <Toast {...props} color="success">
+              <Toast.Icon as={CheckCircle} />
+              <Toast.Title>Mobile deposit submitted</Toast.Title>
+              <Toast.Description>
+                $725.00 is under review. Up to $225.00 may be available today.
+              </Toast.Description>
+              <Toast.Close />
+            </Toast>
+          ),
+        })
+      }
+    >
+      <Button.Label>Submit deposit</Button.Label>
+    </Button>
+  );
+}
+```
+
+## API
+
+### Toast
+
+The presentational root, used only inside a `component` render function. Stacking and dismissal props are supplied by the provider.
+
+Whatever the JSX order, the root renders its direct children as a row: the first `Toast.Icon`, then a column holding every other child, then each `Toast.Action` and `Toast.Close` in source order. The column is omitted when it would be empty. A wrapper you place around `Toast.Title` and `Toast.Description` yourself still works; it renders inside the column.
+
+`Toast.Icon`, `Toast.Action`, and `Toast.Close` are matched by component identity. Wrapping one in `memo()`, an HOC, or a custom component moves it into the column. Extra icons are not rendered.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional CSS class for the toast container |
+| `children?` | `ReactNode` | — | Laid out automatically: the first `Toast.Icon` at the start, `Toast.Action` and `Toast.Close` at the end, and everything else in a text column between them. Additional `Toast.Icon` children are dropped. `Toast.Icon`, `Toast.Action`, and `Toast.Close` must be **direct** children — wrapping them in `memo()` or an HOC hides them from the layout, and they render in the text column instead. |
+| `role?` | `'status' \| 'alert'` | `'status'` | ARIA role for the toast element. Use `'alert'` for urgent/danger toasts that require assertive announcements. |
+| `color?` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'default' \| null` | `'neutral'` | Color of the toast |
+| `animation?` | `ToastRootAnimation` | — | Animation configuration for toast - `false` or `"disabled"`: Disable only root animations - `"disable-all"`: Disable all animations including children - `true` or `undefined`: Use default animations - `object`: Custom animation configuration |
+| `isSwipeable?` | `boolean` | `true` | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `isAnimatedStyleActive?` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active When `false`, the animated style is removed and you can implement custom logic This prop should only be used when you want to write custom styling logic instead of the default animated styles |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props), except `role`. `color="default"` is deprecated; use `neutral` instead.
+
+`opacity`, `transform`, and `height` are driven by the stacking animation and cannot be set through `className`. Customize them with `animation`, or set `isAnimatedStyleActive={false}` to take over styling entirely.
+
+### ToastProvider
+
+Mounts the toast viewport and supplies the manager returned by `useToast()`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disableFullWindowOverlay?` | `boolean` | `false` | When true, uses a regular View instead of FullWindowOverlay on iOS for toasts. Enables React Native element inspector but toasts won't appear above native modals. |
+| `unstable_accessibilityContainerViewIsModal?` | `boolean` | `false` | Controls whether VoiceOver treats the toast overlay window as a modal container. When `false`, VoiceOver can still access elements behind the overlay. When `true`, VoiceOver is restricted to elements inside the overlay. |
+| `defaultProps?` | `ToastGlobalConfig` | — | Global toast configuration These values are used as defaults for all toasts unless overridden locally Local configs have precedence over global config |
+| `insets?` | `ToastInsets` | `Platform-specific: - iOS: { top: 0, bottom: 6, left: 12, right: 12 } - Android: { top: 12, bottom: 12, left: 12, right: 12 }` | Insets for spacing from screen edges (added to safe area insets) |
+| `maxVisibleToasts?` | `number` | `3` | Maximum number of visible toasts before opacity starts fading Controls when toast items begin to fade out as they move beyond the visible stack |
+| `contentWrapper?` | `((children: React.ReactNode) => React.ReactElement)` | — | Custom wrapper function to wrap the toast content Receives children and should return a component that wraps them The wrapper should apply flex: 1 (via className or style) to ensure proper layout and `pointerEvents: 'box-none'` so it does not block interaction with the page behind. On web, `box-none` only takes effect from a `StyleSheet.create` style, not an inline object. Can be any component wrapper - KeyboardAvoidingView, View, or any custom component |
+| `announceLabel?` | `string` | `'Notifications'` | Accessible label for the toast notification region on web. Screen readers announce this as the landmark name for the ARIA live region that wraps all visible toasts. |
+| `container?` | `Element \| null` | — | Element that receives the toast viewport instead of `document.body`. Use it to keep toasts inside an embedded surface, such as a device preview. The fixed viewport stays inside the container only when an ancestor of it creates a containing block for fixed descendants, for example through a `transform`. While `null`, such as before a callback ref attaches, no viewport renders. |
+| `children?` | `React.ReactNode` | — | Children to render |
+
+Values in `defaultProps` apply to every toast; per-toast options passed to `toast.show()` win. `insets` are added to the safe-area insets — iOS defaults to `{ top: 0, bottom: 6, left: 12, right: 12 }` and Android to `12` on all edges. On web, pass a `container` element to keep the viewport inside an embedded surface such as a device preview instead of `document.body`.
+
+## Sub-components
+
+### Toast.Title
+
+Headline text, rendered with `role="heading"` and `aria-level={3}` and colored by the parent toast's `color`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `ReactNode` | — | Content to be rendered as title |
+| `className?` | `string` | — | Additional CSS class for the title |
+
+Remaining props are forwarded to the underlying [`Text`](https://design.candescent.com/docs/components/text/content.md).
+
+### Toast.Description
+
+Body text, colored by the parent toast's `color`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children?` | `ReactNode` | — | Content to be rendered as description |
+| `className?` | `string` | — | Additional CSS class for the description |
+
+Remaining props are forwarded to the underlying [`Text`](https://design.candescent.com/docs/components/text/content.md).
+
+### Toast.Icon
+
+Leading glyph. Renders nothing unless `as` or `asChild` is provided.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `ReactNode` | — | Child element to render when `asChild` is set. |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as?` | `ForgeIcon` | — | Forge icon component to render. Required unless `asChild` is set. |
+| `asChild?` | `boolean` | — | — |
+
+### Toast.Action
+
+Action control rendered as a [`Button`](https://design.candescent.com/docs/components/button/content.md) and accepting all of its props. Defaults to `variant="outline"` and `size="small"`, with `color` derived from the toast's `color` (`neutral` maps to `action`). On a `neutral` toast the action label and border use inverse content color so they stay legible on the dark surface; an explicit `color` still wins. Children are wrapped in `Button.Label` automatically.
+
+### Toast.Close
+
+Dismiss control rendered as an [`IconButton`](https://design.candescent.com/docs/components/icon-button/content.md) and accepting all of its props except `as`, which is narrowed to a `ForgeIcon`. Defaults to `variant="ghost"`, `size="small"`, `aria-label="Close"`, and the close glyph. Pressing it hides the parent toast, so no `onPress` is required; a supplied `onPress` runs in addition.
+
+## Hook
+
+### useToast
+
+Returns the toast manager and current visibility:
+
+```tsx
+const { toast, isToastVisible } = useToast();
+```
+
+| Return           | Type           | Description                                              |
+| ---------------- | -------------- | -------------------------------------------------------- |
+| `toast`          | `ToastManager` | Imperative API — `show`, `hide`, `pauseAll`, `resumeAll` |
+| `isToastVisible` | `boolean`      | Whether any toast is currently displayed                 |
+
+### toast.show
+
+Displays a toast and returns its id. Accepts three shapes:
+
+| Argument                                | Result                                                  |
+| --------------------------------------- | ------------------------------------------------------- |
+| `toast.show('Saved')`                   | Default toast using the string as its title             |
+| `toast.show({ label, description, … })` | Default toast, fully configured                         |
+| `toast.show({ component })`             | Custom layout built from `Toast` and its sub-components |
+
+`component` cannot be combined with the styling and content options below.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `duration?` | `number \| "persistent"` | `4000` | Duration in milliseconds before the toast automatically disappears Set to `'persistent'` to prevent auto-hide (toast will remain until manually dismissed) |
+| `id?` | `string` | — | Optional ID for the toast. If omitted, one is generated. If a toast with this id is already in the stack, `show` returns that id and does not add another. |
+| `label?` | `string` | — | Label text for the toast |
+| `description?` | `string` | — | Description text for the toast |
+| `actionLabel?` | `string` | — | Action button label text |
+| `onActionPress?` | `((helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: (string & {}) \| string[] \| "all") => void; }) => void)` | — | Callback function called when the action button is pressed Receives show and hide functions for programmatic toast control |
+| `icon?` | `ForgeIcon` | — | Forge icon component to display in the toast. Rendered via `Toast.Icon` internally — inherits color-aware coloring automatically. |
+| `onShow?` | `(() => void)` | — | Callback function called when the toast is shown |
+| `onHide?` | `(() => void)` | — | Callback function called when the toast is hidden |
+| `color?` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'default' \| null` | `'neutral'` | Color of the toast |
+| `placement?` | `'top-start' \| 'top' \| 'top-end' \| 'bottom-start' \| 'bottom' \| 'bottom-end'` | `'bottom'` | Placement of the toast |
+| `isSwipeable?` | `boolean` | `true` | Whether the toast can be swiped to dismiss and dragged with rubber effect |
+| `animation?` | `ToastRootAnimation` | — | Animation configuration for toast - `false` or `"disabled"`: Disable only root animations - `"disable-all"`: Disable all animations including children - `true` or `undefined`: Use default animations - `object`: Custom animation configuration |
+
+### toast.hide
+
+| Call                   | Behavior                   |
+| ---------------------- | -------------------------- |
+| `toast.hide()`         | Hides the front-most toast |
+| `toast.hide(id)`       | Hides one toast            |
+| `toast.hide([id, id])` | Hides several toasts       |
+| `toast.hide('all')`    | Hides every toast          |
+
+### toast.pauseAll / toast.resumeAll
+
+Pause and resume every auto-dismiss timer; each resumes with only the time it had left. On web these are called for you (see Accessibility). On native they are no-ops unless you call them.
+
+## Anatomy
+
+| `data-slot`  | Element      |
+| ------------ | ------------ |
+| `toast`      | Root surface |
+| `toast-icon` | Leading icon |
+
+## Accessibility
+
+- The viewport is a `role="region"` landmark labelled by `announceLabel`, with `aria-live="polite"` on web so new toasts are announced.
+- `color="danger"` upgrades the toast to `role="alert"` for assertive announcements.
+- Timers pause automatically on web while the pointer is over a toast, while a toast holds focus, or while the tab is hidden (WCAG 2.2.1).
+- Escape dismisses the front-most toast on web.
+- On iOS the viewport is wrapped in `FullWindowOverlay` so toasts sit above native modals.
+
+## Constraints
+
+- `ToastProvider` must be mounted once near the app root; `useToast()` throws without it.
+- Toasts are imperative only. There is no declarative `open` prop and no trigger sub-component.
+- `maxVisibleToasts` is set on the provider, not per toast. Beyond it, older toasts fade rather than unmount.
+- Swipe-to-dismiss is native only and needs a `GestureHandlerRootView` above the provider.
+- `duration: 0` dismisses immediately; `'persistent'`, negative, and non-finite values skip the timer.