An open source design system that's fully customizable and agent ready
TypeScript
feat: add defaultOpen prop to XDSTooltip and XDSHoverCard (#1672)
Cindy Zhang5bd741f44ff5
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjsindex 6cf57890ca..f988ac4cbb 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs@@ -5,4 +5,5 @@ export const doc = {isReady: true,aspectRatio: 1,isShowcase: true,+ componentsUsed: ['HoverCard', 'Button', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.tsxindex e2683ae208..f92eb355d8 100644--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.tsx+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.tsx@@ -3,25 +3,21 @@import {XDSHoverCard} from '@xds/core/HoverCard';import {XDSButton} from '@xds/core/Button';import {XDSVStack} from '@xds/core/Layout';+import {XDSText, XDSHeading} from '@xds/core/Text';export default function HoverCardShowcase() {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="above"+ isDefaultOpen+ content={+ <XDSVStack gap={1} style={{width: 200}}>+ <XDSHeading level={5}>Jane Doe</XDSHeading>+ <XDSText type="supporting" color="secondary">Software Engineer</XDSText>+ <XDSText type="body">Building great products with great people.</XDSText>+ </XDSVStack>+ }>+ <XDSButton label="Hover me" />+ </XDSHoverCard>);}diff --git a/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.doc.mjs b/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.doc.mjsindex f285570ab7..bff43af414 100644--- a/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.doc.mjs@@ -5,4 +5,5 @@ export const doc = {isReady: true,aspectRatio: 1,isShowcase: true,+ componentsUsed: ['Tooltip', 'Button'],};diff --git a/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.tsx b/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.tsxindex 57db8ba8bf..413f65cc84 100644--- a/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.tsx+++ b/packages/cli/templates/blocks/components/Tooltip/TooltipShowcase.tsx@@ -5,7 +5,7 @@ import {XDSButton} from '@xds/core/Button';export default function TooltipShowcase() {return (- <XDSTooltip content="This is a helpful tooltip" placement="above">+ <XDSTooltip content="This is a helpful tooltip" placement="above" isDefaultOpen><XDSButton label="Hover me" /></XDSTooltip>);diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex a4cddb264f..1c7a154844 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -78,6 +78,11 @@ export const docs = {description: 'Shows a dashed underline on the trigger element.',default: "'auto'",},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: 'Whether the hover card should be shown on mount. Still dismissible.',+ },],},{@@ -121,6 +126,11 @@ export const docs = {description: 'Enables or disables all hover and focus triggers.',default: 'true',},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: 'Whether the hover card should be shown on mount. Still dismissible.',+ },{name: 'onShow',type: '() => void',@@ -232,6 +242,11 @@ export const docsZh = {description: '在触发元素上显示虚线下划线。',default: "'auto'",},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: '是否在挂载时显示悬浮卡片。仍然可以关闭。',+ },],},{@@ -275,6 +290,11 @@ export const docsZh = {description: '启用或禁用所有悬停和聚焦触发器。',default: 'true',},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: '是否在挂载时显示悬浮卡片。仍然可以关闭。',+ },{name: 'onShow',type: '() => void',@@ -327,6 +347,7 @@ export const docsDense = {isEnabled: 'Enable/disable hover + focus triggers.',onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',hasHoverIndication: 'Dashed underline on trigger element.',+ isDefaultOpen: 'Show hover card on mount. Still dismissible.',},},{@@ -339,6 +360,7 @@ export const docsDense = {hideDelay: 'Hide delay in ms.',focusTrigger: 'Controls when focus events trigger layer.',isEnabled: 'Enable/disable all hover + focus triggers.',+ isDefaultOpen: 'Show hover card on mount. Still dismissible.',onShow: 'Callback when hover card becomes visible.',onHide: 'Callback when hover card hidden.',},diff --git a/packages/core/src/HoverCard/XDSHoverCard.test.tsx b/packages/core/src/HoverCard/XDSHoverCard.test.tsxindex e14117b42f..3216a7d728 100644--- a/packages/core/src/HoverCard/XDSHoverCard.test.tsx+++ b/packages/core/src/HoverCard/XDSHoverCard.test.tsx@@ -134,6 +134,73 @@ describe('XDSHoverCard', () => {expect(wrapper).toHaveAttribute('aria-describedby');});+ describe('isDefaultOpen', () => {+ it('shows hover card on mount when isDefaultOpen is true', async () => {+ vi.mocked(HTMLElement.prototype.showPopover).mockClear();+ render(+ <XDSHoverCard content={<span>Default open card</span>} isDefaultOpen>+ <button>Trigger</button>+ </XDSHoverCard>,+ );++ await waitFor(() => {+ expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();+ });+ });++ it('calls onOpenChange(true) on mount when isDefaultOpen is true', async () => {+ const onOpenChange = vi.fn();+ render(+ <XDSHoverCard+ content={<span>Default open card</span>}+ isDefaultOpen+ onOpenChange={onOpenChange}>+ <button>Trigger</button>+ </XDSHoverCard>,+ );++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });+ });++ it('does not show hover card on mount when isDefaultOpen is not set', async () => {+ vi.mocked(HTMLElement.prototype.showPopover).mockClear();+ render(+ <XDSHoverCard content={<span>Not default open</span>}>+ <button>Trigger</button>+ </XDSHoverCard>,+ );++ await new Promise(resolve => setTimeout(resolve, 50));+ expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();+ });++ it('hover card is still dismissible after isDefaultOpen', async () => {+ const onOpenChange = vi.fn();+ render(+ <XDSHoverCard+ content={<span>Dismissible card</span>}+ isDefaultOpen+ onOpenChange={onOpenChange}+ hideDelay={0}>+ <button>Trigger</button>+ </XDSHoverCard>,+ );++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });++ const trigger = screen.getByRole('button', {name: 'Trigger'});+ fireEvent.mouseLeave(trigger);++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+ });+ });+describe('Escape key behavior', () => {it('hides hover card when Escape is pressed on trigger', async () => {const onOpenChange = vi.fn();diff --git a/packages/core/src/HoverCard/XDSHoverCard.tsx b/packages/core/src/HoverCard/XDSHoverCard.tsxindex 1ffab93e01..8c4fb96c38 100644--- a/packages/core/src/HoverCard/XDSHoverCard.tsx+++ b/packages/core/src/HoverCard/XDSHoverCard.tsx@@ -109,6 +109,12 @@ export interface XDSHoverCardProps {* @default 'auto'*/hasHoverIndication?: 'auto' | boolean;++ /**+ * Whether the hover card should be shown on mount.+ * The hover card is still dismissible — this just opens it initially.+ */+ isDefaultOpen?: boolean;}/**@@ -152,6 +158,7 @@ export function XDSHoverCard({isEnabled = true,onOpenChange,hasHoverIndication = 'auto',+ isDefaultOpen,}: XDSHoverCardProps): ReactElement {const wrapperRef = useRef<HTMLElement>(null);const textOnly = isTextOnly(children);@@ -176,6 +183,7 @@ export function XDSHoverCard({hideDelay,focusTrigger,isEnabled,+ isDefaultOpen,onShow: handleShow,onHide: handleHide,});diff --git a/packages/core/src/HoverCard/useXDSHoverCard.tsx b/packages/core/src/HoverCard/useXDSHoverCard.tsxindex 7ef58ddc59..b76f6f0c06 100644--- a/packages/core/src/HoverCard/useXDSHoverCard.tsx+++ b/packages/core/src/HoverCard/useXDSHoverCard.tsx@@ -111,6 +111,12 @@ export interface XDSHoverCardOptions {*/isEnabled?: boolean;+ /**+ * Whether the hover card should be shown on mount.+ * The hover card is still dismissible — this just opens it initially.+ */+ isDefaultOpen?: boolean;+/*** Callback fired when hover card is shown.* Wrap in useCallback for stable identity.@@ -226,6 +232,7 @@ export function useXDSHoverCard(hideDelay = 200,focusTrigger = 'auto',isEnabled = true,+ isDefaultOpen = false,onShow,onHide,} = options;@@ -395,6 +402,14 @@ export function useXDSHoverCard(};}, [clearTimeouts]);+ // Show on mount when isDefaultOpen is true+ useEffect(() => {+ if (isDefaultOpen) {+ layer.show();+ }+ // Only run on mount — isDefaultOpen is not reactive+ }, []);+// Render function that wraps layer.render with hover card behaviorconst renderHoverCard = useCallback((children: ReactNode, props?: ContextRenderProps) => {diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjsindex bc5001a6dd..c8a692324a 100644--- a/packages/core/src/Tooltip/Tooltip.doc.mjs+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs@@ -71,6 +71,11 @@ export const docs = {description: 'Shows a dashed underline on the trigger element.',default: "'auto'",},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: 'Whether the tooltip should be shown on mount. Still dismissible.',+ },],},{@@ -114,6 +119,11 @@ export const docs = {description: 'Enables or disables all hover and focus triggers.',default: 'true',},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: 'Whether the tooltip should be shown on mount. Still dismissible.',+ },{name: 'onShow',type: '() => void',@@ -216,6 +226,11 @@ export const docsZh = {description: '在触发元素上显示虚线下划线。',default: "'auto'",},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: '是否在挂载时显示工具提示。仍然可以关闭。',+ },],},{@@ -259,6 +274,11 @@ export const docsZh = {description: '启用或禁用所有悬停和聚焦触发器。',default: 'true',},+ {+ name: 'isDefaultOpen',+ type: 'boolean',+ description: '是否在挂载时显示工具提示。仍然可以关闭。',+ },{name: 'onShow',type: '() => void',@@ -318,6 +338,7 @@ export const docsDense = {isEnabled: 'Enables/disables tooltip triggers.',onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',hasHoverIndication: 'Dashed underline on trigger element.',+ isDefaultOpen: 'Show tooltip on mount. Still dismissible.',},},{@@ -330,6 +351,7 @@ export const docsDense = {hideDelay: 'Hide delay in ms.',focusTrigger: 'Controls when focus events trigger tooltip.',isEnabled: 'Enables/disables all hover+focus triggers.',+ isDefaultOpen: 'Show tooltip on mount. Still dismissible.',onShow: 'Fired when tooltip becomes visible.',onHide: 'Fired when tooltip hidden.',},diff --git a/packages/core/src/Tooltip/XDSTooltip.test.tsx b/packages/core/src/Tooltip/XDSTooltip.test.tsxnew file mode 100644index 0000000000..27e2f25a50--- /dev/null+++ b/packages/core/src/Tooltip/XDSTooltip.test.tsx@@ -0,0 +1,137 @@+/**+ * @file XDSTooltip.test.tsx+ * @input Uses vitest, @testing-library/react, XDSTooltip component+ * @output Unit tests for XDSTooltip component behavior+ * @position Testing; validates XDSTooltip.tsx implementation+ *+ * SYNC: When XDSTooltip.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import {XDSTooltip} from './XDSTooltip';++// Store original matches to restore later+const originalMatches = HTMLElement.prototype.matches;++// Track popover open state per element+const popoverOpenState = new WeakMap<HTMLElement, boolean>();++// Mock Popover API for jsdom+beforeAll(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ popoverOpenState.set(this, true);+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ popoverOpenState.set(this, false);+ });++ // Only intercept :popover-open, delegate everything else to original+ HTMLElement.prototype.matches = function (selector: string) {+ if (selector === ':popover-open') {+ return popoverOpenState.get(this) ?? false;+ }+ return originalMatches.call(this, selector);+ };+});++afterAll(() => {+ HTMLElement.prototype.matches = originalMatches;+});++describe('XDSTooltip', () => {+ it('renders trigger element', () => {+ render(+ <XDSTooltip content="Tooltip text">+ <button>Trigger</button>+ </XDSTooltip>,+ );+ expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();+ });++ it('calls onOpenChange(true) when shown via hover', async () => {+ const onOpenChange = vi.fn();+ render(+ <XDSTooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>+ <button>Trigger</button>+ </XDSTooltip>,+ );++ const trigger = screen.getByRole('button', {name: 'Trigger'});+ fireEvent.mouseEnter(trigger);++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });+ });++ describe('isDefaultOpen', () => {+ it('shows tooltip on mount when isDefaultOpen is true', async () => {+ render(+ <XDSTooltip content="Default open tooltip" isDefaultOpen>+ <button>Trigger</button>+ </XDSTooltip>,+ );++ // showPopover should be called on mount+ await waitFor(() => {+ expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();+ });+ });++ it('calls onOpenChange(true) on mount when isDefaultOpen is true', async () => {+ const onOpenChange = vi.fn();+ render(+ <XDSTooltip+ content="Default open tooltip"+ isDefaultOpen+ onOpenChange={onOpenChange}>+ <button>Trigger</button>+ </XDSTooltip>,+ );++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });+ });++ it('does not show tooltip on mount when isDefaultOpen is false', async () => {+ vi.mocked(HTMLElement.prototype.showPopover).mockClear();+ render(+ <XDSTooltip content="Not default open">+ <button>Trigger</button>+ </XDSTooltip>,+ );++ // Give it time to potentially fire+ await new Promise(resolve => setTimeout(resolve, 50));+ expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();+ });++ it('tooltip is still dismissible after isDefaultOpen', async () => {+ const onOpenChange = vi.fn();+ render(+ <XDSTooltip+ content="Dismissible tooltip"+ isDefaultOpen+ onOpenChange={onOpenChange}+ hideDelay={0}>+ <button>Trigger</button>+ </XDSTooltip>,+ );++ // Wait for it to show+ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });++ // Mouse leave should hide it+ const trigger = screen.getByRole('button', {name: 'Trigger'});+ fireEvent.mouseLeave(trigger);++ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+ });+ });+});diff --git a/packages/core/src/Tooltip/XDSTooltip.tsx b/packages/core/src/Tooltip/XDSTooltip.tsxindex 0e9543df15..01a1ce4861 100644--- a/packages/core/src/Tooltip/XDSTooltip.tsx+++ b/packages/core/src/Tooltip/XDSTooltip.tsx@@ -119,6 +119,12 @@ export interface XDSTooltipProps {* @default 'auto'*/hasHoverIndication?: 'auto' | boolean;++ /**+ * Whether the tooltip should be shown on mount.+ * The tooltip is still dismissible — this just opens it initially.+ */+ isDefaultOpen?: boolean;}/**@@ -162,6 +168,7 @@ export function XDSTooltip({isEnabled = true,onOpenChange,hasHoverIndication = 'auto',+ isDefaultOpen,}: XDSTooltipProps): ReactElement {const wrapperRef = useRef<HTMLElement>(null);const textOnly = children != null ? isTextOnly(children) : false;@@ -186,6 +193,7 @@ export function XDSTooltip({hideDelay,focusTrigger,isEnabled,+ isDefaultOpen,onShow: handleShow,onHide: handleHide,});diff --git a/packages/core/src/Tooltip/useXDSTooltip.tsx b/packages/core/src/Tooltip/useXDSTooltip.tsxindex 45a3bc35cf..2295c093ef 100644--- a/packages/core/src/Tooltip/useXDSTooltip.tsx+++ b/packages/core/src/Tooltip/useXDSTooltip.tsx@@ -118,6 +118,12 @@ export interface XDSTooltipOptions {*/isEnabled?: boolean;+ /**+ * Whether the tooltip should be shown on mount.+ * The tooltip is still dismissible — this just opens it initially.+ */+ isDefaultOpen?: boolean;+/*** Callback fired when tooltip is shown.* Wrap in useCallback for stable identity.@@ -226,6 +232,7 @@ export function useXDSTooltip(hideDelay = 0,focusTrigger = 'auto',isEnabled = true,+ isDefaultOpen = false,onShow,onHide,} = options;@@ -370,6 +377,14 @@ export function useXDSTooltip(};}, [clearTimeouts]);+ // Show on mount when isDefaultOpen is true+ useEffect(() => {+ if (isDefaultOpen) {+ layer.show();+ }+ // Only run on mount — isDefaultOpen is not reactive+ }, []);+// Render function that wraps layer.render with tooltip stylingconst renderTooltip = useCallback((children: ReactNode, props?: ContextRenderProps) => {