Skip to content

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

TypeScript

Improve Popover docs page and block examples (#1599)

Ted McDonaldc7b786a775bf
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverConfirmAction.tsx b/packages/cli/templates/blocks/components/Popover/PopoverConfirmAction.tsx
index e1c3d575da..e7b25cd301 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverConfirmAction.tsx
+++ b/packages/cli/templates/blocks/components/Popover/PopoverConfirmAction.tsx
@@ -5,7 +5,6 @@ import {XDSPopover} from '@xds/core/Popover';
import {XDSButton} from '@xds/core/Button';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
-
export default function PopoverConfirmAction() {
const [isOpen, setIsOpen] = useState(false);
@@ -18,9 +17,7 @@ export default function PopoverConfirmAction() {
onOpenChange={setIsOpen}
content={
<XDSVStack gap={3}>
- <XDSHeading level={4}>
- Delete project?
- </XDSHeading>
+ <XDSHeading level={4}>Delete project?</XDSHeading>
<XDSText type="body">
This will permanently delete the project and all its data. This
action cannot be undone.
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.doc.mjs b/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.doc.mjs
index c56bcf093a..b01b0a2e66 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.doc.mjs
+++ b/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.doc.mjs
@@ -3,7 +3,7 @@ export const doc = {
type: 'block',
name: 'Popover — Filter Panel',
description:
- 'Controlled popover with checkbox filters, apply and reset actions for filtering list data.',
+ 'Popover with checkbox filters and apply/reset actions.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Popover', 'Button', 'Layout', 'Text', 'CheckboxInput', 'Divider'],
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.tsx b/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.tsx
index 61b24f7083..c39ea39add 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.tsx
+++ b/packages/cli/templates/blocks/components/Popover/PopoverFilterPanel.tsx
@@ -7,7 +7,6 @@ import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSHeading} from '@xds/core/Text';
import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
import {XDSDivider} from '@xds/core/Divider';
-
export default function PopoverFilterPanel() {
const [isOpen, setIsOpen] = useState(false);
const [filters, setFilters] = useState({
@@ -29,9 +28,7 @@ export default function PopoverFilterPanel() {
onOpenChange={setIsOpen}
content={
<XDSVStack gap={3}>
- <XDSHeading level={4}>
- Filter by status
- </XDSHeading>
+ <XDSHeading level={4}>Filter by status</XDSHeading>
<XDSDivider />
<XDSCheckboxInput
label="Active"
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverKeyboardShortcuts.tsx b/packages/cli/templates/blocks/components/Popover/PopoverKeyboardShortcuts.tsx
index 34ddc00c23..4e1c2b6580 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverKeyboardShortcuts.tsx
+++ b/packages/cli/templates/blocks/components/Popover/PopoverKeyboardShortcuts.tsx
@@ -5,7 +5,6 @@ import {XDSButton} from '@xds/core/Button';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSDivider} from '@xds/core/Divider';
-
const shortcuts = [
{key: '⌘K', action: 'Command palette'},
{key: '⌘/', action: 'Toggle sidebar'},
@@ -20,9 +19,7 @@ export default function PopoverKeyboardShortcuts() {
width={260}
content={
<XDSVStack gap={2}>
- <XDSHeading level={4}>
- Keyboard shortcuts
- </XDSHeading>
+ <XDSHeading level={4}>Keyboard shortcuts</XDSHeading>
<XDSDivider />
{shortcuts.map(s => (
<XDSHStack key={s.key} gap={3}>
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverSettingsPanel.tsx b/packages/cli/templates/blocks/components/Popover/PopoverSettingsPanel.tsx
index 59c950c842..e46bcb0356 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverSettingsPanel.tsx
+++ b/packages/cli/templates/blocks/components/Popover/PopoverSettingsPanel.tsx
@@ -7,7 +7,6 @@ import {XDSVStack} from '@xds/core/Layout';
import {XDSHeading} from '@xds/core/Text';
import {XDSSwitch} from '@xds/core/Switch';
import {XDSDivider} from '@xds/core/Divider';
-
export default function PopoverSettingsPanel() {
const [notifications, setNotifications] = useState(true);
const [darkMode, setDarkMode] = useState(false);
@@ -20,9 +19,7 @@ export default function PopoverSettingsPanel() {
width={280}
content={
<XDSVStack gap={3}>
- <XDSHeading level={4}>
- Settings
- </XDSHeading>
+ <XDSHeading level={4}>Settings</XDSHeading>
<XDSDivider />
<XDSSwitch
label="Notifications"
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 908d659809..467f3cc380 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -144,12 +144,13 @@ export const docs = {
},
usage: {
description:
- 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ 'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
- { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
- { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -299,12 +300,13 @@ export const docsZh = {
},
usage: {
description:
- 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ 'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
- { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
- { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -320,12 +322,13 @@ export const docsDense = {
'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',
usage: {
description:
- 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ 'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
- { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
- { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},