Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve AlertDialog docs page and block examples (#1684)

rubyycheung985e72720d03
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogAsyncAction.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogAsyncAction.doc.mjs
index c853590754..11651b69ba 100644
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogAsyncAction.doc.mjs
+++ b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogAsyncAction.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'AlertDialog — Async Action',
+ name: 'AlertDialog — Loading',
description:
- 'Alert dialog with an async action that shows a loading state while processing.',
+ 'A confirmation dialog that shows a spinner while the action runs.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['AlertDialog', 'Button'],
};
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
index 7777c4c352..8736953e10 100644
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
+++ b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
@@ -1,10 +1,11 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'AlertDialog — Delete Confirmation',
+ name: 'AlertDialog — Delete',
description:
- 'Destructive confirmation dialog triggered by a button, the most common alert dialog pattern.',
+ 'A delete button that asks the user to confirm before deleting.',
isReady: true,
- aspectRatio: 4 / 3,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
componentsUsed: ['AlertDialog', 'Button'],
};
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.doc.mjs
deleted file mode 100644
index 3600d5dd36..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'AlertDialog — Imperative API',
- description:
- 'Alert dialog using the imperative hook API, no state management needed.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['AlertDialog', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.tsx b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.tsx
deleted file mode 100644
index 6700c479c2..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogImperativeAlert.tsx
+++ /dev/null
@@ -1,25 +0,0 @@
-'use client';
-
-import {useXDSImperativeAlertDialog} from '@xds/core/AlertDialog';
-import {XDSButton} from '@xds/core/Button';
-
-export default function AlertDialogImperativeAlert() {
- const alert = useXDSImperativeAlertDialog();
- return (
- <>
- <XDSButton
- label="Delete item"
- variant="destructive"
- onClick={() =>
- alert.show({
- title: 'Delete item?',
- description: 'This action cannot be undone.',
- actionLabel: 'Delete',
- onAction: () => alert.hide(),
- })
- }
- />
- {alert.element}
- </>
- );
-}
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.doc.mjs
deleted file mode 100644
index 34e279e66e..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'AlertDialog — Informational Alert',
- description:
- 'Non-destructive confirmation dialog with a primary action button for informational notices.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['AlertDialog', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.tsx b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.tsx
deleted file mode 100644
index f791029492..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogInformationalAlert.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSAlertDialog} from '@xds/core/AlertDialog';
-import {XDSButton} from '@xds/core/Button';
-
-export default function AlertDialogInformationalAlert() {
- const [isOpen, setIsOpen] = useState(false);
- return (
- <>
- <XDSButton
- label="Show notice"
- variant="secondary"
- onClick={() => setIsOpen(true)}
- />
- <XDSAlertDialog
- isOpen={isOpen}
- onOpenChange={setIsOpen}
- title="Session expired"
- description="Your session has expired. You will be redirected to the login page."
- actionLabel="Sign in"
- actionVariant="primary"
- onAction={() => setIsOpen(false)}
- />
- </>
- );
-}
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.doc.mjs
deleted file mode 100644
index 49cbf217bc..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.doc.mjs
+++ /dev/null
@@ -1,8 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'AlertDialog',
- isReady: true,
- aspectRatio: 4 / 3,
- isShowcase: true,
-};
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.tsx b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.tsx
deleted file mode 100644
index 2af69d2460..0000000000
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogShowcase.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {XDSAlertDialog} from '@xds/core/AlertDialog';
-
-export default function AlertDialogShowcase() {
- return (
- <XDSAlertDialog
- isOpen={true}
- onOpenChange={() => {}}
- title="Delete item?"
- description="This action cannot be undone. The item and all its data will be permanently removed."
- actionLabel="Delete"
- onAction={() => {}}
- />
- );
-}
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index 69b3e0c994..3906c161a8 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -15,11 +15,11 @@ export const docs = {
],
usage: {
description:
- 'AlertDialog is a confirmation dialog for destructive or irreversible actions. Use it to require explicit user confirmation before proceeding with actions like deleting content or discarding changes.',
+ 'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.',
bestPractices: [
- {guidance: true, description: 'Clearly describe the consequences of the action in the description text so users can make an informed decision.'},
- {guidance: true, description: 'Keep the action button label specific and descriptive, such as "Delete project" rather than a generic "OK".'},
- {guidance: false, description: 'Use AlertDialog for non-destructive actions or simple informational messages — use a standard Dialog instead.'},
+ {guidance: true, description: 'Make the action button label specific — "Delete project" is better than "OK" or "Confirm".'},
+ {guidance: true, description: 'Describe what will happen in the description so the user knows the consequences before confirming.'},
+ {guidance: false, description: 'Use AlertDialog for non-destructive actions — use a standard Dialog instead.'},
],
},
props: [