An open source design system that's fully customizable and agent ready
TypeScript
Improve HoverCard docs page and block examples (#1584)
rubyycheungffbcef82e471
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjsdeleted file mode 100644index b173ca11ef..0000000000--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'HoverCard — Hook API',- description:- 'Uses the useXDSHoverCard hook for direct control over hover card behavior and placement.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['HoverCard', 'Button', 'VStack'],-};diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsxdeleted file mode 100644index 68c0d52f3c..0000000000--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsx+++ /dev/null@@ -1,34 +0,0 @@-'use client';--import {useXDSHoverCard} from '@xds/core/HoverCard';-import {XDSButton} from '@xds/core/Button';-import {XDSVStack} from '@xds/core/Layout';--export default function HoverCardHookBasedHoverCard() {- const hoverCard = useXDSHoverCard({- placement: 'above',- delay: 200,- });-- return (- <div style={{padding: 80}}>- <XDSButton- label="Using hook directly"- ref={hoverCard.ref}- aria-describedby={hoverCard.describedBy}>- Using hook directly- </XDSButton>- {hoverCard.renderHoverCard(- <div style={{width: 200}}>- <XDSVStack gap={2}>- <div style={{fontWeight: 600}}>Jane Doe</div>- <div style={{fontSize: 14, opacity: 0.7}}>Software Engineer</div>- <div style={{fontSize: 13}}>- Building great products with great people.- </div>- </XDSVStack>- </div>,- )}- </div>- );-}diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjsindex ffaed62b45..5e64b00210 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs@@ -1,10 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'HoverCard — Inline Text',+ name: 'HoverCard — Definition',description:- 'Hover cards wrapping inline text nodes within a paragraph, useful for user mentions or link previews.',+ 'Shows a term definition on hover within a paragraph. Use for technical terms, jargon, or concepts that some readers may not know — like a glossary built into the text.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['HoverCard', 'VStack'],+ aspectRatio: 16 / 9,+ componentsUsed: ['HoverCard', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsxindex 914e88ded4..514d3250d7 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx@@ -1,45 +1,48 @@'use client';+import * as stylex from '@stylexjs/stylex';import {XDSHoverCard} from '@xds/core/HoverCard';import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const styles = stylex.create({+ content: {maxWidth: 200},+});export default function HoverCardInlineTextHoverCard() {return (- <div style={{padding: 80}}>- <p>- The project is maintained by{' '}- <XDSHoverCard- content={- <div style={{width: 200}}>- <XDSVStack gap={2}>- <div style={{fontWeight: 600}}>Jane Doe</div>- <div style={{fontSize: 14, opacity: 0.7}}>- Software Engineer- </div>- <div style={{fontSize: 13}}>- Building great products with great people.- </div>- </XDSVStack>- </div>- }- placement="above">- Jane Doe- </XDSHoverCard>- ,{' '}- <XDSHoverCard- content={- <div style={{width: 200}}>- <XDSVStack gap={2}>- <div style={{fontWeight: 600}}>John Smith</div>- <div style={{fontSize: 14, opacity: 0.7}}>Product Manager</div>- </XDSVStack>- </div>- }- placement="above">- John Smith- </XDSHoverCard>- , and others.- </p>- </div>+ <XDSText type="body">+ The component uses a{' '}+ <XDSHoverCard+ content={+ <XDSVStack gap={1} xstyle={styles.content}>+ <XDSText type="label">Focus trap</XDSText>+ <XDSText type="body" color="secondary">+ A pattern that keeps keyboard focus inside a container, preventing+ it from moving to elements outside. Used in dialogs and modals to+ ensure accessibility.+ </XDSText>+ </XDSVStack>+ }+ placement="above">+ focus trap+ </XDSHoverCard>{' '}+ to keep keyboard navigation inside the{' '}+ <XDSHoverCard+ content={+ <XDSVStack gap={1} xstyle={styles.content}>+ <XDSText type="label">Modal dialog</XDSText>+ <XDSText type="body" color="secondary">+ An overlay that blocks interaction with the rest of the page until+ the user responds. Uses the native HTML dialog element for+ built-in accessibility and backdrop support.+ </XDSText>+ </XDSVStack>+ }+ placement="above">+ modal dialog+ </XDSHoverCard>+ .+ </XDSText>);}diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjsindex ecca483c9c..b66bf69a65 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs@@ -1,10 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'HoverCard — Interactive Content',+ name: 'HoverCard — Link Preview',description:- 'A hover card with interactive buttons inside, allowing users to take actions without navigating away.',+ 'Shows a page summary when hovering a link — title, description, and URL. Use for documentation links, article references, or any URL where a preview helps the user decide whether to click.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['HoverCard', 'Button', 'VStack', 'HStack'],+ aspectRatio: 16 / 9,+ componentsUsed: ['HoverCard', 'Icon', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsxindex 6db699bda5..e382abe4d7 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx@@ -1,29 +1,42 @@'use client';+import * as stylex from '@stylexjs/stylex';import {XDSHoverCard} from '@xds/core/HoverCard';-import {XDSButton} from '@xds/core/Button';+import {XDSIcon} from '@xds/core/Icon';import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {LinkIcon} from '@heroicons/react/24/outline';++const styles = stylex.create({+ content: {maxWidth: 280},+});export default function HoverCardInteractiveContent() {return (- <div style={{padding: 80}}>+ <XDSText type="body">+ Read more in the{' '}<XDSHoverCardplacement="below"content={- <XDSVStack gap={2}>- <div>Interactive hover card content</div>- <XDSHStack gap={2}>- <XDSButton label="Follow" variant="primary">- Follow- </XDSButton>- <XDSButton label="Message">Message</XDSButton>+ <XDSVStack gap={2} xstyle={styles.content}>+ <XDSHStack gap={2} vAlign="start">+ <XDSIcon icon={LinkIcon} size="sm" color="secondary" />+ <XDSVStack gap={1}>+ <XDSText type="label">Getting Started Guide</XDSText>+ <XDSText type="body" color="secondary">+ Learn how to set up your first project, invite team members,+ and configure your workspace.+ </XDSText>+ <XDSText type="supporting" color="secondary">+ docs.example.com/getting-started+ </XDSText>+ </XDSVStack></XDSHStack></XDSVStack>}>- <XDSButton label="Hover for interactive content">- Hover for interactive content- </XDSButton>+ Getting Started Guide</XDSHoverCard>- </div>+ .+ </XDSText>);}diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjsindex 7a3978b697..b39346da72 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs@@ -3,8 +3,8 @@ export const doc = {type: 'block',name: 'HoverCard — Profile Preview',description:- 'A hover card that shows a user profile summary on hover, the most common hover card pattern.',+ 'Shows a user profile summary on hover with name, role, and bio. Use on usernames, avatars, or mentions to let users preview a profile without navigating away.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['HoverCard', 'Button', 'VStack'],+ aspectRatio: 16 / 9,+ componentsUsed: ['HoverCard', 'Button', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsxindex ce2ba135d6..e654c97733 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx@@ -1,27 +1,41 @@'use client';+import * as stylex from '@stylexjs/stylex';import {XDSHoverCard} from '@xds/core/HoverCard';+import {XDSAvatar} from '@xds/core/Avatar';import {XDSButton} from '@xds/core/Button';-import {XDSVStack} from '@xds/core/Layout';+import {XDSIcon} from '@xds/core/Icon';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSText, XDSHeading} from '@xds/core/Text';+import {CalendarIcon} from '@heroicons/react/24/outline';++const styles = stylex.create({+ avatar: {flexShrink: 0},+ content: {maxWidth: 280},+});export default function HoverCardProfileHoverCard() {return (- <div style={{padding: 80}}>- <XDSHoverCard- placement="above"- content={- <div style={{width: 200}}>- <XDSVStack gap={2}>- <div style={{fontWeight: 600}}>Jane Doe</div>- <div style={{fontSize: 14, opacity: 0.7}}>Software Engineer</div>- <div style={{fontSize: 13}}>- Building great products with great people.- </div>- </XDSVStack>- </div>- }>- <XDSButton label="Hover me">Hover me</XDSButton>- </XDSHoverCard>- </div>+ <XDSHoverCard+ placement="below"+ content={+ <XDSHStack gap={3} vAlign="start" xstyle={styles.content}>+ <XDSAvatar name="Jane Doe" size={48} xstyle={styles.avatar} />+ <XDSVStack gap={1}>+ <XDSHeading level={3}>@janedoe</XDSHeading>+ <XDSText type="body" color="secondary">+ Crafting accessible, scalable design systems for modern teams.+ </XDSText>+ <XDSHStack gap={1} vAlign="center">+ <XDSIcon icon={CalendarIcon} size="xsm" color="secondary" />+ <XDSText type="supporting" color="secondary">+ March 2024+ </XDSText>+ </XDSHStack>+ </XDSVStack>+ </XDSHStack>+ }>+ <XDSButton label="@janedoe" variant="ghost" />+ </XDSHoverCard>);}diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 50cd9cf3b4..a4cddb264f 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -135,17 +135,20 @@ export const docs = {},],usage: {- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',+ description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [{ guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },+ { guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },{ guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },+ { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },],anatomy: [- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},+ {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus — a button, link, or inline text.'},+ {name: 'Card', required: true, description: 'The floating overlay with the preview content, anchored to the trigger.'},+ {name: 'Body', required: true, description: 'The main content area — profile info, link summary, or any rich content.'},+ {name: 'Actions', required: false, description: 'Optional buttons inside the card for follow-up actions like Follow or Message.'},],},};@@ -286,17 +289,14 @@ export const docsZh = {},],usage: {- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',+ description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [{ guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },+ { guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },{ guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- ],- anatomy: [- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},+ { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },],},};@@ -306,17 +306,10 @@ export const docsDense = {description:'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',usage: {- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',+ description: 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',bestPractices: [- { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },- { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },- { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- ],- anatomy: [- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},+ { guidance: true, description: 'Supplementary content only. Dashed underline on text triggers. Hook API for custom control.' },+ { guidance: false, description: 'No critical actions — content disappears on cursor leave. Use Tooltip/Popover when simpler.' },],},components: [