@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/src/text/style.module.css

@@ -6,88 +6,88 @@
 	}
 
 	.heading-2xl {
-		--_gcd-heading-font-size: var(--wpds-font-size-2xl);
+		--_gcd-heading-font-size: var(--wpds-typography-font-size-2xl);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-2xl);
-		line-height: var(--wpds-font-line-height-2xl);
-		font-weight: var(--wpds-font-weight-medium);
+		font-family: var(--wpds-typography-font-family-heading);
+		font-size: var(--wpds-typography-font-size-2xl);
+		line-height: var(--wpds-typography-line-height-2xl);
+		font-weight: var(--wpds-typography-font-weight-medium);
 	}
 
 	.heading-xl {
-		--_gcd-heading-font-size: var(--wpds-font-size-xl);
+		--_gcd-heading-font-size: var(--wpds-typography-font-size-xl);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-xl);
-		line-height: var(--wpds-font-line-height-md);
-		font-weight: var(--wpds-font-weight-medium);
+		font-family: var(--wpds-typography-font-family-heading);
+		font-size: var(--wpds-typography-font-size-xl);
+		line-height: var(--wpds-typography-line-height-md);
+		font-weight: var(--wpds-typography-font-weight-medium);
 	}
 
 	.heading-lg {
-		--_gcd-heading-font-size: var(--wpds-font-size-lg);
+		--_gcd-heading-font-size: var(--wpds-typography-font-size-lg);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-lg);
-		line-height: var(--wpds-font-line-height-sm);
-		font-weight: var(--wpds-font-weight-medium);
+		font-family: var(--wpds-typography-font-family-heading);
+		font-size: var(--wpds-typography-font-size-lg);
+		line-height: var(--wpds-typography-line-height-sm);
+		font-weight: var(--wpds-typography-font-weight-medium);
 	}
 
 	.heading-md {
-		--_gcd-heading-font-size: var(--wpds-font-size-md);
+		--_gcd-heading-font-size: var(--wpds-typography-font-size-md);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-md);
-		line-height: var(--wpds-font-line-height-sm);
-		font-weight: var(--wpds-font-weight-medium);
+		font-family: var(--wpds-typography-font-family-heading);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-sm);
+		font-weight: var(--wpds-typography-font-weight-medium);
 	}
 
 	.heading-sm {
-		--_gcd-heading-font-size: var(--wpds-font-size-xs);
+		--_gcd-heading-font-size: var(--wpds-typography-font-size-xs);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-xs);
-		line-height: var(--wpds-font-line-height-xs);
-		font-weight: var(--wpds-font-weight-medium);
+		font-family: var(--wpds-typography-font-family-heading);
+		font-size: var(--wpds-typography-font-size-xs);
+		line-height: var(--wpds-typography-line-height-xs);
+		font-weight: var(--wpds-typography-font-weight-medium);
 		text-transform: uppercase;
 	}
 
 	.body-xl {
-		--_gcd-p-font-size: var(--wpds-font-size-xl);
-		--_gcd-p-line-height: var(--wpds-font-line-height-xl);
+		--_gcd-p-font-size: var(--wpds-typography-font-size-xl);
+		--_gcd-p-line-height: var(--wpds-typography-line-height-xl);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-xl);
-		line-height: var(--wpds-font-line-height-xl);
-		font-weight: var(--wpds-font-weight-regular);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-xl);
+		line-height: var(--wpds-typography-line-height-xl);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 
 	.body-lg {
-		--_gcd-p-font-size: var(--wpds-font-size-lg);
-		--_gcd-p-line-height: var(--wpds-font-line-height-md);
+		--_gcd-p-font-size: var(--wpds-typography-font-size-lg);
+		--_gcd-p-line-height: var(--wpds-typography-line-height-md);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-lg);
-		line-height: var(--wpds-font-line-height-md);
-		font-weight: var(--wpds-font-weight-regular);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-lg);
+		line-height: var(--wpds-typography-line-height-md);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 
 	.body-md {
-		--_gcd-p-font-size: var(--wpds-font-size-md);
-		--_gcd-p-line-height: var(--wpds-font-line-height-sm);
+		--_gcd-p-font-size: var(--wpds-typography-font-size-md);
+		--_gcd-p-line-height: var(--wpds-typography-line-height-sm);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-md);
-		line-height: var(--wpds-font-line-height-sm);
-		font-weight: var(--wpds-font-weight-regular);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-sm);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 
 	.body-sm {
-		--_gcd-p-font-size: var(--wpds-font-size-sm);
-		--_gcd-p-line-height: var(--wpds-font-line-height-xs);
+		--_gcd-p-font-size: var(--wpds-typography-font-size-sm);
+		--_gcd-p-line-height: var(--wpds-typography-line-height-xs);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-sm);
-		line-height: var(--wpds-font-line-height-xs);
-		font-weight: var(--wpds-font-weight-regular);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-sm);
+		line-height: var(--wpds-typography-line-height-xs);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 }

package/src/text/text.tsx

@@ -20,8 +20,8 @@ export const Text = forwardRef< HTMLSpanElement, TextProps >( function Text(
 		props: mergeProps< 'span' >( props, {
 			className: clsx(
 				styles.text,
-				variant.startsWith( 'heading-' ) && defenseStyles.heading,
-				variant.startsWith( 'body-' ) && defenseStyles.p,
+				defenseStyles.heading,
+				defenseStyles.p,
 				styles[ variant ],
 				className
 			),

package/src/tooltip/index.ts

@@ -1,6 +1,7 @@
 import { Popup } from './popup';
+import { Portal } from './portal';
 import { Trigger } from './trigger';
 import { Root } from './root';
 import { Provider } from './provider';
 
-export { Provider, Root, Trigger, Popup };
+export { Provider, Root, Trigger, Popup, Portal };

package/src/tooltip/popup.tsx

@@ -1,5 +1,5 @@
 import clsx from 'clsx';
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import { forwardRef } from '@wordpress/element';
 import {
 	type ThemeProvider as ThemeProviderType,
@@ -7,6 +7,8 @@ import {
 } from '@wordpress/theme';
 import type { PopupProps } from './types';
 import { unlock } from '../lock-unlock';
+import { Portal } from './portal';
+import { renderPortalWithChildren } from '../utils/render-portal-with-children';
 import resetStyles from '../utils/css/resets.module.css';
 import styles from './style.module.css';
 
@@ -16,29 +18,23 @@ const ThemeProvider: typeof ThemeProviderType =
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
 	{
 		align = 'center',
+		portal,
 		side = 'top',
 		sideOffset = 4,
 		children,
 		className,
-		style,
 		...props
 	},
 	ref
 ) {
-	return (
-		<Tooltip.Portal>
-			<Tooltip.Positioner
-				align={ align }
-				side={ side }
-				sideOffset={ sideOffset }
-				style={ style }
-				className={ clsx(
-					resetStyles[ 'box-sizing' ],
-					className,
-					styles.positioner
-				) }
-			>
-				{ /* This should ideally use whatever dark color makes sense,
+	const portalChildren = (
+		<_Tooltip.Positioner
+			align={ align }
+			side={ side }
+			sideOffset={ sideOffset }
+			className={ clsx( resetStyles[ 'box-sizing' ], styles.positioner ) }
+		>
+			{ /* This should ideally use whatever dark color makes sense,
 				and not be hardcoded to #1e1e1e. The solutions would be to:
 				  - review the design of the tooltip, in case we want to stop
 				    hardcoding it to a dark background
@@ -47,18 +43,19 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
 				    them;
 				  - remove the hardcoded `bg` setting from the `ThemeProvider` below
 					*/ }
-				<ThemeProvider color={ { bg: '#1e1e1e' } }>
-					<Tooltip.Popup
-						ref={ ref }
-						className={ styles.popup }
-						{ ...props }
-					>
-						{ children }
-					</Tooltip.Popup>
-				</ThemeProvider>
-			</Tooltip.Positioner>
-		</Tooltip.Portal>
+			<ThemeProvider color={ { bg: '#1e1e1e' } }>
+				<_Tooltip.Popup
+					ref={ ref }
+					className={ clsx( styles.popup, className ) }
+					{ ...props }
+				>
+					{ children }
+				</_Tooltip.Popup>
+			</ThemeProvider>
+		</_Tooltip.Positioner>
 	);
+
+	return renderPortalWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };

package/src/tooltip/portal.tsx

@@ -0,0 +1,16 @@
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `Tooltip` floating content. Pass to
+ * `Tooltip.Popup`'s `portal` prop. When `portal` is omitted, `Tooltip.Popup`
+ * uses this component with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function TooltipPortal( props, ref ) {
+		return <_Tooltip.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

package/src/tooltip/provider.tsx

@@ -1,8 +1,8 @@
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import type { ProviderProps } from './types';
 
-function Provider( { children, ...props }: ProviderProps ) {
-	return <Tooltip.Provider { ...props }>{ children }</Tooltip.Provider>;
+function Provider( { ...props }: ProviderProps ) {
+	return <_Tooltip.Provider { ...props } />;
 }
 
 export { Provider };

package/src/tooltip/root.tsx

@@ -1,20 +1,21 @@
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import type { RootProps } from './types';
 
 /**
- * `Tooltip` is used to visually show the label of an icon button, or other such interactive controls
- * that don't have a visual text label.
+ * `Tooltip` is used to visually show the label of an icon button, or other such
+ * interactive controls that don't have a visual text label.
  *
- * Tooltips are not available on touch devices, and thus should not be used for infotips,
- * descriptions, or dynamic status messages.
+ * Tooltip popups are visual-only and not exposed to assistive technologies.
+ * The trigger's accessible name (e.g. `aria-label`) is the source of truth
+ * for screen reader users. Tooltips are not available on touch devices,
+ * and thus should not be used for infotips, descriptions, or dynamic status
+ * messages.
  *
- * The tooltip itself does not provide any accessible labeling, so when using the
- * `Tooltip` primitive you must ensure that the trigger is accessibly labeled (e.g. with an `aria-label`).
- *
- * See also: [IconButton](https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-iconbutton--docs)
+ * @see {@link https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-tooltip-usage-guidelines--docs Usage Guidelines}
+ * @see {@link https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-iconbutton--docs IconButton}
  */
 function Root( props: RootProps ) {
-	return <Tooltip.Root { ...props } />;
+	return <_Tooltip.Root { ...props } />;
 }
 
 export { Root };

package/src/tooltip/stories/index.story.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { formatBold, formatItalic } from '@wordpress/icons';
-import { Icon, Tooltip } from '../..';
+import { Icon } from '../../icon';
+import * as Tooltip from '../';
 
 const meta: Meta< typeof Tooltip.Root > = {
 	title: 'Design System/Components/Tooltip',
@@ -9,6 +10,7 @@ const meta: Meta< typeof Tooltip.Root > = {
 		Provider: Tooltip.Provider,
 		Trigger: Tooltip.Trigger,
 		Popup: Tooltip.Popup,
+		Portal: Tooltip.Portal,
 	},
 };
 export default meta;
@@ -74,6 +76,42 @@ export const Positioning: StoryObj< typeof Tooltip.Root > = {
 	),
 };
 
+/**
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where a tooltip renders below another popover when you
+ * want it above.
+ *
+ * The `--wp-ui-tooltip-z-index` CSS variable controls the z-index of the
+ * tooltip's positioner. Override it either:
+ *
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   tooltip in the page), or
+ * - **Per instance**, by passing a `Tooltip.Portal` with a `style` (or
+ *   `className`) to `Tooltip.Popup`'s `portal` prop. The variable cascades
+ *   from the portal wrapper to everything rendered inside it.
+ *
+ * This story demonstrates the per-instance approach.
+ */
+export const WithCustomZIndex: StoryObj< typeof Tooltip.Root > = {
+	name: 'With Custom z-index',
+	args: {
+		children: (
+			<>
+				<Tooltip.Trigger aria-label="Save">💾</Tooltip.Trigger>
+				<Tooltip.Popup
+					portal={
+						<Tooltip.Portal
+							style={ { '--wp-ui-tooltip-z-index': '9999' } }
+						/>
+					}
+				>
+					Save
+				</Tooltip.Popup>
+			</>
+		),
+	},
+};
+
 /**
  * Use `Tooltip.Provider` to control the delay before tooltips appear.
  * This is useful when you have multiple tooltips and want them to share

package/src/tooltip/stories/usage-guidelines.mdx

@@ -0,0 +1,91 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks';
+import * as UsageGuidelinesStories from './usage-guidelines.story';
+
+<Meta of={ UsageGuidelinesStories } />
+
+# Tooltip usage guidelines
+
+## Usage guidelines
+
+-   **Use tooltips as visual labels only.** Tooltips should act as
+    supplementary visual labels for sighted mouse and keyboard users.
+    Tooltip popups are not exposed to assistive technologies — the
+    trigger's accessible name (e.g. `aria-label`) is what provides the
+    label for screen reader users.
+    See [_Alternatives to tooltips_](#alternatives-to-tooltips) below for
+    more details.
+-   **Provide an accessible name for the trigger.** Tooltips are visual-only
+    elements and are not a replacement for labeling the trigger. The
+    tooltip's trigger must have an `aria-label` that matches or is a concise
+    equivalent of the tooltip's content to ensure consistency for screen
+    reader users. If the tooltip also displays a keyboard shortcut, use
+    `aria-keyshortcuts` on the trigger.
+
+<Canvas of={ UsageGuidelinesStories.RecommendedUsage } />
+
+`IconButton` has built-in tooltip support via the `label` prop, making it
+the easiest way to provide a tooltip for icon-only actions.
+
+<Canvas of={ UsageGuidelinesStories.IconButtonWithTooltip } />
+
+## Alternatives to tooltips
+
+Tooltips should be supplementary popups that provide non-essential clarity in
+high-density UIs. A user should not miss critical information if they never
+see a tooltip.
+
+Tooltips don't work well with touch input. Unlike mouse pointers with hover
+capability, there's no easily discoverable way to reveal a tooltip before
+tapping its trigger on a touch device.
+
+iOS doesn't provide a system-standard, touch-friendly tooltip affordance,
+while Android may show a tooltip on long press. However, on the web,
+long press is often used to trigger contextual menus in the browser, which
+can lead to potential conflicts. For this reason, tooltips are disabled on
+touch devices.
+
+### Infotips
+
+Popups that open when hovering an info icon should use
+[Popover](?path=/docs/design-system-components-popover--docs) with the
+`openOnHover` prop on the trigger instead of a tooltip. This way, touch
+users and screen reader users can access the content.
+
+To know when to reach for a popover instead of a tooltip, consider the
+**purpose** of the trigger element: if the trigger's purpose is to open the
+popup itself, it's a popover. If the trigger's purpose is unrelated to
+opening the popup, it's a tooltip.
+
+<Canvas of={ UsageGuidelinesStories.InfotipWithPopover } />
+
+See also the [Popover Infotip story](?path=/story/design-system-components-popover--infotip).
+
+Infotips opened on hover can be dismissed by pressing `Escape`.
+
+### Description text
+
+Tooltips are designed for sighted mouse and keyboard users and are not a reliable way to deliver
+important information to touch users or assistive technologies. If the
+description is important to understanding the element, don't hide it behind a
+tooltip — use inline text or
+[Popover](?path=/docs/design-system-components-popover--docs) if space is
+limited, so the information is accessible to everyone.
+
+Since tooltips serve sighted mouse and keyboard users, iconography should
+clearly communicate the purpose of icon-only triggers, especially on mobile
+where the text label may not be visible.
+
+If the description is not critical, a tooltip can still be used to provide
+extra clarity for sighted mouse or keyboard users.
+
+### Contextual feedback messages
+
+For contextual feedback after an action (e.g. "Copied!"), prefer a pattern
+that ensures the message is announced to screen readers and supports complex
+content, such as a
+[Notice](?path=/docs/design-system-components-notice--docs).
+
+## References
+
+-   [WCAG 1.4.13: Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) — tooltips must be dismissible (Escape), hoverable, and persistent.
+-   [WAI-ARIA APG: Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) — note that this component intentionally diverges from the traditional `role="tooltip"` + `aria-describedby` pattern. The trigger's `aria-label` is the source of truth for assistive technologies, and the tooltip popup is a visual-only supplement.

package/src/tooltip/stories/usage-guidelines.story.tsx

@@ -0,0 +1,123 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+	formatBold,
+	formatItalic,
+	formatUnderline,
+	info,
+} from '@wordpress/icons';
+import * as Tooltip from '../';
+import { Icon } from '../../icon';
+import { IconButton } from '../../icon-button';
+import * as Popover from '../../popover';
+import { VisuallyHidden } from '../../visually-hidden';
+
+const meta: Meta = {
+	title: 'Design System/Components/Tooltip/Usage Guidelines',
+	parameters: {
+		controls: { disable: true },
+	},
+	tags: [ '!dev' ],
+};
+export default meta;
+
+type Story = StoryObj;
+
+/**
+ * Tooltips work best as visual labels for icon-only controls. Each trigger
+ * must have its own accessible name via `aria-label`.
+ */
+export const RecommendedUsage: Story = {
+	render: () => (
+		<Tooltip.Provider delay={ 0 }>
+			<div style={ { display: 'flex', gap: '0.25rem' } }>
+				<Tooltip.Root>
+					<Tooltip.Trigger aria-label="Bold">
+						<Icon icon={ formatBold } />
+					</Tooltip.Trigger>
+					<Tooltip.Popup>Bold</Tooltip.Popup>
+				</Tooltip.Root>
+
+				<Tooltip.Root>
+					<Tooltip.Trigger aria-label="Italic">
+						<Icon icon={ formatItalic } />
+					</Tooltip.Trigger>
+					<Tooltip.Popup>Italic</Tooltip.Popup>
+				</Tooltip.Root>
+
+				<Tooltip.Root>
+					<Tooltip.Trigger aria-label="Underline">
+						<Icon icon={ formatUnderline } />
+					</Tooltip.Trigger>
+					<Tooltip.Popup>Underline</Tooltip.Popup>
+				</Tooltip.Root>
+			</div>
+		</Tooltip.Provider>
+	),
+};
+
+/**
+ * Popups that open when hovering an info icon should use `Popover` with
+ * `openOnHover` instead of a Tooltip. This ensures the content is accessible
+ * to touch and screen reader users.
+ */
+export const InfotipWithPopover: Story = {
+	render: () => (
+		<div
+			style={ {
+				display: 'flex',
+				alignItems: 'center',
+				gap: 'var(--wpds-dimension-gap-xs)',
+			} }
+		>
+			<span>Label</span>
+			<Popover.Root>
+				<Popover.Trigger
+					openOnHover
+					delay={ 200 }
+					closeDelay={ 200 }
+					aria-label="More information"
+					style={ {
+						background: 'none',
+						border: 'none',
+						padding: 0,
+						cursor: 'var(--wpds-cursor-control)',
+						display: 'inline-flex',
+						alignItems: 'center',
+						borderRadius: 'var(--wpds-border-radius-sm)',
+					} }
+				>
+					<Icon icon={ info } size={ 20 } />
+				</Popover.Trigger>
+				<Popover.Popup>
+					<Popover.Arrow />
+					<VisuallyHidden render={ <Popover.Title /> }>
+						More information
+					</VisuallyHidden>
+					<Popover.Description>
+						This is additional context about the label. Unlike
+						tooltips, this content is accessible to touch and screen
+						reader users.
+					</Popover.Description>
+				</Popover.Popup>
+			</Popover.Root>
+		</div>
+	),
+};
+
+/**
+ * `IconButton` has built-in tooltip support via the `label` prop,
+ * making it the easiest way to provide a tooltip for icon-only actions.
+ */
+export const IconButtonWithTooltip: Story = {
+	render: () => (
+		<div style={ { display: 'flex', gap: '0.25rem' } }>
+			<IconButton icon={ formatBold } label="Bold" size="compact" />
+			<IconButton icon={ formatItalic } label="Italic" size="compact" />
+			<IconButton
+				icon={ formatUnderline }
+				label="Underline"
+				size="compact"
+			/>
+		</div>
+	),
+};

package/src/tooltip/style.module.css

@@ -11,10 +11,22 @@
 			var(--wpds-dimension-padding-xs)
 			var(--wpds-dimension-padding-sm);
 		border-radius: var(--wpds-border-radius-sm);
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-sm);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-sm);
 		line-height: 1.4; /* TODO: use DS token for line height */
 		color: var(--wpds-color-fg-content-neutral);
 		box-shadow: var(--wpds-elevation-sm);
+
+		/*
+		 * Forced-colors mode strips `box-shadow` and replaces the
+		 * `background-color` with `Canvas`, so the tooltip would merge
+		 * into the page. A 1px `CanvasText` border restores the edge.
+		 * The popup inherits `box-sizing: border-box` from the
+		 * positioner (via the shared `.box-sizing` reset utility), so
+		 * the 1px is absorbed and non-FC layout is unchanged.
+		 */
+		@media (forced-colors: active) {
+			border: 1px solid CanvasText;
+		}
 	}
 }