@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/alert/content.md

@@ -0,0 +1,203 @@
+# Alert (https://design.candescent.com/docs/components/alert)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=6665-19536), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-alert--default)
+
+A compound component with sub-components for the icon, title, description, and trailing actions. Renders into the document flow at the consumer's mount point; not an overlay.
+
+```tsx
+import { Alert } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Alert } from '@cdx-ui/components';
+
+export default function AlertBasicDemo() {
+  return (
+    <Alert>
+      <Alert.Icon />
+      <Alert.Title>Scheduled maintenance</Alert.Title>
+      <Alert.Description>
+        The app will be briefly unavailable on Saturday between 2–4 AM.
+      </Alert.Description>
+    </Alert>
+  );
+}
+```
+
+## Severities
+
+```tsx
+import { Alert, Box } from '@cdx-ui/components';
+
+export default function AlertSeveritiesDemo() {
+  return (
+    <Box className="gap-3">
+      <Alert severity="danger">
+        <Alert.Icon />
+        <Alert.Title>Danger</Alert.Title>
+        <Alert.Description>
+          Your account has been locked due to multiple failed sign-in attempts.
+        </Alert.Description>
+      </Alert>
+      <Alert severity="warning">
+        <Alert.Icon />
+        <Alert.Title>Warning</Alert.Title>
+        <Alert.Description>Your identity verification expires in 3 days.</Alert.Description>
+      </Alert>
+      <Alert severity="success">
+        <Alert.Icon />
+        <Alert.Title>Success</Alert.Title>
+        <Alert.Description>Your direct deposit of $1,200.00 has been received.</Alert.Description>
+      </Alert>
+      <Alert severity="info">
+        <Alert.Icon />
+        <Alert.Title>Info</Alert.Title>
+        <Alert.Description>
+          Scheduled maintenance is planned for this Sunday at midnight.
+        </Alert.Description>
+      </Alert>
+    </Box>
+  );
+}
+```
+
+## Description only
+
+```tsx
+import { Alert } from '@cdx-ui/components';
+
+export default function AlertDescriptionOnlyDemo() {
+  return (
+    <Alert severity="success">
+      <Alert.Icon />
+      <Alert.Description>Your profile has been updated.</Alert.Description>
+    </Alert>
+  );
+}
+```
+
+## With actions
+
+```tsx
+import { Alert, Button, IconButton } from '@cdx-ui/components';
+import { Close } from '@cdx-ui/icons';
+
+export default function AlertWithActionsDemo() {
+  return (
+    <Alert severity="danger">
+      <Alert.Icon />
+      <Alert.Title>Payment failed</Alert.Title>
+      <Alert.Description>We could not charge your card ending in 4242.</Alert.Description>
+      <Alert.Actions>
+        <Button variant="ghost" size="small">
+          <Button.Label>Retry</Button.Label>
+        </Button>
+        <IconButton variant="ghost" size="small" as={Close} accessibilityLabel="Dismiss" />
+      </Alert.Actions>
+    </Alert>
+  );
+}
+```
+
+## Text wrapping
+
+```tsx
+import { Alert, Box, Button, IconButton } from '@cdx-ui/components';
+import { Close } from '@cdx-ui/icons';
+
+export default function AlertTextWrappingDemo() {
+  return (
+    <Box className="max-w-xs">
+      <Alert severity="danger">
+        <Alert.Icon />
+        <Alert.Title>An unexpected error occurred during the payment processing flow</Alert.Title>
+        <Alert.Description>
+          We were unable to complete your transaction because the payment gateway returned an error
+          code. Please review your payment details and try again, or contact support if the issue
+          persists.
+        </Alert.Description>
+        <Alert.Actions>
+          <Button variant="ghost" size="small">
+            <Button.Label>Retry</Button.Label>
+          </Button>
+          <IconButton variant="ghost" size="small" as={Close} accessibilityLabel="Dismiss" />
+        </Alert.Actions>
+      </Alert>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Alert
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | Sub-components (`Alert.Icon`, `Alert.Title`, `Alert.Description`, `Alert.Actions`) must be rendered as **direct** children — wrapping them in HOCs or `memo()` will break the automatic layout splitting. |
+| `severity?` | `'danger' \| 'warning' \| 'success' \| 'info'` | `'info'` | Severity level that controls background colour, icon, and live-region urgency. |
+| `asChild?` | `boolean` | — | Replace the root element with the consumer's child element via `Slot`. When `true`, children are rendered as-is (no automatic icon/text/actions layout splitting). Severity context is still provided so sub-components receive the correct styles. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute                 | danger / warning | success / info |
+| ------------------------- | ---------------- | -------------- |
+| `role`                    | `alert`          | `status`       |
+| `accessibilityLiveRegion` | `assertive`      | `polite`       |
+
+## Sub-components
+
+### Alert.Icon
+
+Severity glyph. Auto-renders the appropriate icon for the current severity; override with the `as` prop.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `React.ReactNode` | — | — |
+| `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` | — | Override the auto-rendered severity icon. Omit to use the default icon for the current severity (EmergencyHome, Warning, CheckCircle, or Info). Not required when `asChild` is set. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+### Alert.Title
+
+Bold headline text rendered in the severity colour.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Alert.Description
+
+Body text rendered in the severity colour.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Alert.Actions
+
+Trailing action slot. Auto-injects `color={severity}` on direct `Button`/`IconButton` children unless the consumer already provides a `color` prop.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Replace the wrapper element with the consumer's child via `Slot`. **Note:** when `true`, automatic `color={severity}` injection on direct `Button`/`IconButton` children is bypassed — the consumer must set `color` explicitly. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).

package/docs/components/alert-dialog/content.md

@@ -0,0 +1,319 @@
+# Alert Dialog (https://design.candescent.com/docs/components/alert-dialog)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4428-496), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-alertdialog--default)
+
+A specialized Dialog with non-dismissible defaults, an `alertdialog` role, and dedicated action and cancel buttons.
+
+```tsx
+import { AlertDialog, Button } 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 alert
+> 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
+
+Use an Alert Dialog when the user must confirm or cancel an important operation before continuing.
+
+```tsx
+import { useState } from 'react';
+import { AlertDialog, Button } from '@cdx-ui/components';
+
+export default function AlertDialogBasicDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <AlertDialog isOpen={open} onOpenChange={setOpen}>
+      <AlertDialog.Trigger asChild>
+        <Button>
+          <Button.Label>Submit wire transfer</Button.Label>
+        </Button>
+      </AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title>Submit wire transfer?</AlertDialog.Title>
+          <AlertDialog.Description>
+            This transfer will be sent for processing immediately.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        <AlertDialog.Content>
+          <AlertDialog.Text>
+            Send $2,500.00 from Business Checking to Acme Supplies ending in 0184.
+          </AlertDialog.Text>
+        </AlertDialog.Content>
+        <AlertDialog.Footer>
+          <AlertDialog.Cancel>Review again</AlertDialog.Cancel>
+          <AlertDialog.Action onPress={() => setOpen(false)}>Submit transfer</AlertDialog.Action>
+        </AlertDialog.Footer>
+      </AlertDialog.Popup>
+    </AlertDialog>
+  );
+}
+```
+
+## Destructive action
+
+Pair a danger title with a danger action when the decision has an irreversible consequence.
+
+```tsx
+import { useState } from 'react';
+import { AlertDialog, Button } from '@cdx-ui/components';
+
+export default function AlertDialogDestructiveDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <AlertDialog isOpen={open} onOpenChange={setOpen}>
+      <AlertDialog.Trigger asChild>
+        <Button color="danger">
+          <Button.Label>Close savings account</Button.Label>
+        </Button>
+      </AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title severity="danger">Close this savings account?</AlertDialog.Title>
+          <AlertDialog.Description>
+            This action cannot be undone after the request is processed.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        <AlertDialog.Content>
+          <AlertDialog.Text>
+            The remaining $186.42 balance will be transferred to Everyday Checking, and future
+            deposits to this account will be returned.
+          </AlertDialog.Text>
+        </AlertDialog.Content>
+        <AlertDialog.Footer>
+          <AlertDialog.Cancel>Keep account</AlertDialog.Cancel>
+          <AlertDialog.Action color="danger" onPress={() => setOpen(false)}>
+            Close account
+          </AlertDialog.Action>
+        </AlertDialog.Footer>
+      </AlertDialog.Popup>
+    </AlertDialog>
+  );
+}
+```
+
+## Error recovery
+
+An Alert Dialog can interrupt a failed workflow with clear recovery and dismissal actions.
+
+```tsx
+import { useState } from 'react';
+import { AlertDialog, Button } from '@cdx-ui/components';
+
+export default function AlertDialogErrorRecoveryDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <AlertDialog isOpen={open} onOpenChange={setOpen}>
+      <AlertDialog.Trigger asChild>
+        <Button variant="outline" color="danger">
+          <Button.Label>Simulate transfer error</Button.Label>
+        </Button>
+      </AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title severity="danger">Transfer could not be completed</AlertDialog.Title>
+          <AlertDialog.Description>No money has left your account.</AlertDialog.Description>
+        </AlertDialog.Header>
+        <AlertDialog.Content>
+          <AlertDialog.Text>
+            We could not connect to the receiving bank. Check your connection and try again.
+          </AlertDialog.Text>
+        </AlertDialog.Content>
+        <AlertDialog.Footer>
+          <AlertDialog.Cancel>Not now</AlertDialog.Cancel>
+          <AlertDialog.Action onPress={() => setOpen(false)}>Try again</AlertDialog.Action>
+        </AlertDialog.Footer>
+      </AlertDialog.Popup>
+    </AlertDialog>
+  );
+}
+```
+
+## Session timeout
+
+Non-dismissible defaults make Alert Dialog appropriate for security decisions that require an explicit response.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { AlertDialog, Button, Text } from '@cdx-ui/components';
+
+const TIMEOUT_SECONDS = 30;
+
+export default function AlertDialogSessionTimeoutDemo() {
+  const [open, setOpen] = useState(false);
+  const [remaining, setRemaining] = useState(TIMEOUT_SECONDS);
+
+  useEffect(() => {
+    if (!open) {
+      setRemaining(TIMEOUT_SECONDS);
+      return;
+    }
+
+    const interval = setInterval(() => {
+      setRemaining((current) => {
+        if (current <= 1) {
+          setOpen(false);
+          return TIMEOUT_SECONDS;
+        }
+        return current - 1;
+      });
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [open]);
+
+  return (
+    <AlertDialog isOpen={open} onOpenChange={setOpen} size="sm">
+      <AlertDialog.Trigger asChild>
+        <Button variant="outline" color="warning">
+          <Button.Label>Simulate session timeout</Button.Label>
+        </Button>
+      </AlertDialog.Trigger>
+      <AlertDialog.Popup>
+        <AlertDialog.Header>
+          <AlertDialog.Title severity="warning">You will be signed out soon</AlertDialog.Title>
+          <AlertDialog.Description>
+            For your security, inactive banking sessions expire automatically.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        <AlertDialog.Content>
+          {/* Interim: `tabular-nums` stops the digits shifting each second. Text has no numeric-figures option yet. */}
+          <Text size="xl" weight="semibold" color="warning" className="text-center tabular-nums">
+            0:{String(remaining).padStart(2, '0')}
+          </Text>
+        </AlertDialog.Content>
+        <AlertDialog.Footer>
+          <AlertDialog.Cancel>Sign out now</AlertDialog.Cancel>
+          <AlertDialog.Action onPress={() => setOpen(false)}>Continue session</AlertDialog.Action>
+        </AlertDialog.Footer>
+      </AlertDialog.Popup>
+    </AlertDialog>
+  );
+}
+```
+
+## API
+
+### AlertDialog
+
+Extends `Dialog` with defaults that require the user to choose an action.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children` | `React.ReactNode` | — | — |
+| `role?` | `'dialog' \| 'alertdialog'` | — | — |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| null` | — | — |
+| `animation?` | `'disable-all'` | — | Pass `'disable-all'` to turn off enter/exit and swipe animations for the popup and overlay. |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `defaultOpen?` | `boolean` | — | — |
+| `closeOnBackdropPress?` | `boolean` | — | — |
+| `closeOnEscKey?` | `boolean` | `true` | Close when Escape is pressed. Web only. When `false`, an open dialog still consumes Escape while topmost, so overlays beneath it stay open. Android's hardware back button dismisses independently of this prop. |
+| `fullBleed?` | `boolean` | `false` | Removes horizontal padding from `Dialog.Content`. |
+
+Inherits all [`Dialog` props](https://design.candescent.com/docs/components/dialog/content.md), with these different defaults:
+
+| Prop                   | Alert Dialog default | Dialog default |
+| ---------------------- | -------------------- | -------------- |
+| `role`                 | `'alertdialog'`      | `'dialog'`     |
+| `closeOnBackdropPress` | `false`              | `true`         |
+| `closeOnEscKey`        | `false`              | `true`         |
+
+### AlertDialog.Popup
+
+Extends `Dialog.Popup` and disables swipe-to-dismiss by default.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `forceMount?` | `boolean` | `false` | Keep the popup mounted while the dialog is closed. |
+| `avoidKeyboard?` | `boolean` | — | Whether the content shifts up to clear the on-screen keyboard (native only). No-op on web. Defaults to `true`. |
+| `keyboardVerticalOffset?` | `number` | — | Distance (in px) between the keyboard and the content when keyboard avoidance is active. Forwarded to the underlying keyboard-avoiding layer on native. Defaults to `0`. |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| null` | — | — |
+| `disableFullWindowOverlay?` | `boolean` | `false` | On iOS, render in a plain `View` instead of `FullWindowOverlay`. Re-enables the element inspector, but the popup no longer layers above native modals. |
+| `isSwipeable?` | `boolean` | `true` | Allow swipe-down to dismiss. Native only; no effect on web. |
+| `zIndex?` | `number` | — | Stacking order for the portal overlay layer (backdrop + popup panel). Defaults to {@link MODAL_OVERLAY_Z_INDEX} (10000). |
+
+Inherits all [`Dialog.Popup` props](https://design.candescent.com/docs/components/dialog/content.md#dialog-popup). `isSwipeable` defaults to `false`.
+
+## Actions
+
+### AlertDialog.Action
+
+Primary confirmation action. Renders a solid Button and **does not close automatically**; close the dialog from `onPress` after the operation succeeds.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the button's own styles. |
+| `children?` | `React.ReactNode` | — | Button content — typically `Button.Label`, `Button.Icon`, and/or `Button.Spinner`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `Pressable` host — merges Button's props onto the child instead of wrapping it (e.g. `<Button asChild><Link /></Button>`). |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'action'` | Color theme applied to the button surface and content. |
+| `size?` | `'default' \| 'small'` | `'default'` | Height and horizontal padding scale. |
+| `fullWidth?` | `boolean` | `false` | Stretch the button to fill the width of its container. |
+| `isDisabled?` | `boolean` | — | If true, the button will be disabled. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) and Forge Button props except `variant`. `color` defaults to `"action"`.
+
+```tsx
+<AlertDialog.Action color="danger" onPress={() => setOpen(false)}>
+  Close account
+</AlertDialog.Action>
+```
+
+### AlertDialog.Cancel
+
+Secondary action. Renders a ghost Button and automatically closes the Alert Dialog after running the supplied `onPress` handler.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the button's own styles. |
+| `children?` | `React.ReactNode` | — | Button content — typically `Button.Label`, `Button.Icon`, and/or `Button.Spinner`. |
+| `asChild?` | `boolean` | — | Render the consumer's child element in place of the default `Pressable` host — merges Button's props onto the child instead of wrapping it (e.g. `<Button asChild><Link /></Button>`). |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | `'action'` | Color theme applied to the button surface and content. |
+| `size?` | `'default' \| 'small'` | `'default'` | Height and horizontal padding scale. |
+| `fullWidth?` | `boolean` | `false` | Stretch the button to fill the width of its container. |
+| `isDisabled?` | `boolean` | — | If true, the button will be disabled. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) and Forge Button props except `variant`.
+
+## Inherited sub-components
+
+Alert Dialog re-exports these Dialog sub-components with the same API:
+
+- `AlertDialog.Trigger`
+- `AlertDialog.Header`
+- `AlertDialog.Title`
+- `AlertDialog.Description`
+- `AlertDialog.Content`
+- `AlertDialog.Text`
+- `AlertDialog.Footer`
+- `AlertDialog.Close`
+
+See the [`Dialog` API](https://design.candescent.com/docs/components/dialog/content.md) for their props. Avoid `AlertDialog.Close` in confirmation flows because it introduces a third dismissal path without an explicit decision.
+
+## Accessibility
+
+- The popup receives `role="alertdialog"`, `aria-modal`, `aria-labelledby`, and `aria-describedby`.
+- Focus moves into the popup, remains trapped while open, and returns to the trigger after close.
+- Backdrop presses, Escape, and native swipe gestures do not dismiss the Alert Dialog by default. Escape is still consumed while the Alert Dialog is topmost, so a dialog or sheet beneath it stays open.
+- Every Alert Dialog should provide both a clear action and a safe cancel choice unless the workflow has no reversible alternative.
+
+## When to use
+
+| Use Dialog when…                                 | Use Alert Dialog when…                             |
+| ------------------------------------------------ | -------------------------------------------------- |
+| Presenting forms, information, or settings       | Confirming a destructive or important decision     |
+| Dismissal without a decision is acceptable       | The user must explicitly confirm or cancel         |
+| Backdrop, Escape, or swipe dismissal is expected | Incidental dismissal could cause confusion or risk |