Skip to content

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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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 behavior
const renderHoverCard = useCallback(
(children: ReactNode, props?: ContextRenderProps) => {
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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 styling
const renderTooltip = useCallback(
(children: ReactNode, props?: ContextRenderProps) => {