@wordpress/ui 0.11.0 → 0.12.0

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId, useState } from '@wordpress/element';
 import type { ComponentProps } from 'react';
+import { Stack } from '../../stack';
 import { VisuallyHidden } from '../../visually-hidden';
 import * as Dialog from '../index';
 
@@ -12,6 +13,8 @@ const meta: Meta< typeof Dialog.Root > = {
 		'Dialog.Popup': Dialog.Popup,
 		'Dialog.Header': Dialog.Header,
 		'Dialog.Title': Dialog.Title,
+		'Dialog.Description': Dialog.Description,
+		'Dialog.Content': Dialog.Content,
 		'Dialog.CloseIcon': Dialog.CloseIcon,
 		'Dialog.Action': Dialog.Action,
 		'Dialog.Footer': Dialog.Footer,
@@ -20,25 +23,6 @@ const meta: Meta< typeof Dialog.Root > = {
 		modal: {
 			control: 'inline-radio',
 			options: [ true, false, 'trap-focus' ],
-			table: {
-				defaultValue: { summary: 'true' },
-				type: {
-					summary: 'boolean | "trap-focus"',
-				},
-			},
-		},
-	},
-	parameters: {
-		docs: {
-			description: {
-				component: `
-Dialog is a popup that opens on top of the entire page. Every dialog must include a \`Dialog.Title\` component for accessibility — it serves as both the visible heading and the accessible label for the dialog.
-
-When using the Dialog component, make sure to always include a visible close button, either \`Dialog.CloseIcon\` or a clear dismissing action button. If your dialog has a "Cancel" button in the footer, the close icon may be redundant and create confusion about what clicking "X" means.
-
-Use \`Dialog.CloseIcon\` for informational dialogs where dismissing is safe and expected. For dialogs requiring explicit user choice (especially destructive actions), omit the close icon and rely on footer action buttons like "Cancel" and "Confirm" instead.
-				`,
-			},
 		},
 	},
 };
@@ -60,11 +44,13 @@ export const _Default: Story = {
 						<Dialog.Title>Welcome</Dialog.Title>
 						<Dialog.CloseIcon />
 					</Dialog.Header>
-					<p>
-						This dialog demonstrates best practices for
-						informational dialogs. It includes a close icon because
-						dismissing it is safe and expected.
-					</p>
+					<Dialog.Content>
+						<Dialog.Description>
+							This dialog demonstrates best practices for
+							informational dialogs. It includes a close icon
+							because dismissing it is safe and expected.
+						</Dialog.Description>
+					</Dialog.Content>
 					<Dialog.Footer>
 						<Dialog.Action>Got it</Dialog.Action>
 					</Dialog.Footer>
@@ -85,7 +71,7 @@ function SizeSelector( {
 } ) {
 	const selectId = useId();
 	return (
-		<div style={ { display: 'flex', gap: 8, alignItems: 'center' } }>
+		<Stack direction="row" gap="sm" align="center">
 			<label htmlFor={ selectId }>Dialog size preset</label>
 			<select
 				id={ selectId }
@@ -105,7 +91,7 @@ function SizeSelector( {
 					</option>
 				) ) }
 			</select>
-		</div>
+		</Stack>
 	);
 }
 
@@ -114,27 +100,24 @@ function SizePlaygroundContent() {
 		useState< ComponentProps< typeof Dialog.Popup >[ 'size' ] >( 'medium' );
 	return (
 		<>
-			<div
-				style={ {
-					display: 'flex',
-					flexDirection: 'column',
-					gap: 16,
-					alignItems: 'start',
-				} }
-			>
+			<Stack direction="column" gap="lg" align="start">
 				<SizeSelector value={ size } onChange={ setSize } />
 				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
-			</div>
+			</Stack>
 			<Dialog.Popup size={ size }>
 				<Dialog.Header>
 					<Dialog.Title>Size Playground</Dialog.Title>
 					<Dialog.CloseIcon />
 				</Dialog.Header>
-				<SizeSelector value={ size } onChange={ setSize } />
-				<p>
-					Use the dropdown above (or outside the dialog) to change the
-					popup size. Both controls stay in sync.
-				</p>
+				<Dialog.Content>
+					<Stack direction="column" gap="lg" align="start">
+						<SizeSelector value={ size } onChange={ setSize } />
+						<p style={ { margin: 0 } }>
+							Use the dropdown above (or outside the dialog) to
+							change the popup size. Both controls stay in sync.
+						</p>
+					</Stack>
+				</Dialog.Content>
 				<Dialog.Footer>
 					<Dialog.Action>Got it</Dialog.Action>
 				</Dialog.Footer>
@@ -150,17 +133,175 @@ export const AllSizes: Story = {
 };
 
 /**
- * Popovers in Gutenberg are managed with explicit z-index values, which can create
- * situations where a dialog renders below another popover, when you want it to be rendered above.
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where a dialog renders below another popover when you
+ * want it above.
+ *
+ * The `--wp-ui-dialog-z-index` CSS variable controls the z-index of the
+ * dialog's backdrop and popup. Override it either:
  *
- * The `--wp-ui-dialog-z-index` CSS variable controls the z-index of both the
- * backdrop and the popup. It can be overridden globally by setting the variable
- * on `:root` or `body`. (This story doesn't actually demonstrate the feature
- * because it requires a global CSS rule.)
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   dialog in the page), or
+ * - **Per instance**, by passing a `Dialog.Portal` with a `style` (or
+ *   `className`) to `Dialog.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: Story = {
-	..._Default,
 	name: 'With Custom z-index',
+	args: {
+		children: (
+			<>
+				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+				<Dialog.Popup
+					portal={
+						<Dialog.Portal
+							style={ { '--wp-ui-dialog-z-index': '9999' } }
+						/>
+					}
+				>
+					<Dialog.Header>
+						<Dialog.Title>Custom z-index</Dialog.Title>
+						<Dialog.CloseIcon />
+					</Dialog.Header>
+					<Dialog.Content>
+						<Dialog.Description>
+							The backdrop and popup render at `z-index: 9999` via
+							the `--wp-ui-dialog-z-index` CSS custom property,
+							set on `Dialog.Portal` through the `portal` prop.
+						</Dialog.Description>
+					</Dialog.Content>
+					<Dialog.Footer>
+						<Dialog.Action>Got it</Dialog.Action>
+					</Dialog.Footer>
+				</Dialog.Popup>
+			</>
+		),
+	},
+};
+
+function StickyToggle( {
+	stickyHeader,
+	stickyFooter,
+	onStickyHeaderChange,
+	onStickyFooterChange,
+}: {
+	stickyHeader: boolean;
+	stickyFooter: boolean;
+	onStickyHeaderChange: ( value: boolean ) => void;
+	onStickyFooterChange: ( value: boolean ) => void;
+} ) {
+	const headerId = useId();
+	const footerId = useId();
+	return (
+		<Stack direction="row" gap="md" align="center">
+			<Stack direction="row" gap="xs" align="center">
+				<input
+					id={ headerId }
+					type="checkbox"
+					checked={ stickyHeader }
+					onChange={ ( e ) =>
+						onStickyHeaderChange( e.target.checked )
+					}
+				/>
+				<label htmlFor={ headerId }>Sticky header</label>
+			</Stack>
+			<Stack direction="row" gap="xs" align="center">
+				<input
+					id={ footerId }
+					type="checkbox"
+					checked={ stickyFooter }
+					onChange={ ( e ) =>
+						onStickyFooterChange( e.target.checked )
+					}
+				/>
+				<label htmlFor={ footerId }>Sticky footer</label>
+			</Stack>
+		</Stack>
+	);
+}
+
+function ScrollableContent() {
+	const [ size, setSize ] =
+		useState< ComponentProps< typeof Dialog.Popup >[ 'size' ] >( 'medium' );
+	const [ stickyHeader, setStickyHeader ] = useState( true );
+	const [ stickyFooter, setStickyFooter ] = useState( true );
+
+	const header = (
+		<Dialog.Header>
+			<Dialog.Title>Terms of service</Dialog.Title>
+			<Dialog.CloseIcon />
+		</Dialog.Header>
+	);
+	const footer = (
+		<Dialog.Footer>
+			<Dialog.Action variant="outline">Decline</Dialog.Action>
+			<Dialog.Action>Accept</Dialog.Action>
+		</Dialog.Footer>
+	);
+	const controls = (
+		<Stack direction="column" gap="sm" align="start">
+			<SizeSelector value={ size } onChange={ setSize } />
+			<StickyToggle
+				stickyHeader={ stickyHeader }
+				stickyFooter={ stickyFooter }
+				onStickyHeaderChange={ setStickyHeader }
+				onStickyFooterChange={ setStickyFooter }
+			/>
+		</Stack>
+	);
+
+	return (
+		<>
+			<Stack direction="column" gap="lg" align="start">
+				{ controls }
+				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+			</Stack>
+			<Dialog.Popup size={ size }>
+				{ stickyHeader && header }
+				<Dialog.Content>
+					{ ! stickyHeader && header }
+					<Stack direction="column" gap="lg">
+						{ controls }
+						{ Array.from( { length: 20 } ).map( ( _, index ) => (
+							<p key={ index } style={ { margin: 0 } }>
+								Paragraph { index + 1 }: Lorem ipsum dolor sit
+								amet, consectetur adipiscing elit. Sed do
+								eiusmod tempor incididunt ut labore et dolore
+								magna aliqua. Ut enim ad minim veniam, quis
+								nostrud exercitation ullamco laboris nisi ut
+								aliquip ex ea commodo consequat.
+							</p>
+						) ) }
+					</Stack>
+					{ ! stickyFooter && footer }
+				</Dialog.Content>
+				{ stickyFooter && footer }
+			</Dialog.Popup>
+		</>
+	);
+}
+
+/**
+ * When dialog content overflows the available height, `Dialog.Content`
+ * scrolls while `Dialog.Header` and `Dialog.Footer` stay pinned to the
+ * popup's top and bottom edges. Separator lines appear only when there
+ * is off-screen content above the header or below the footer.
+ *
+ * To let the header or footer scroll with the body instead of staying
+ * pinned, render it *inside* `Dialog.Content` rather than as a sibling.
+ * The inline "Sticky header / Sticky footer" checkboxes toggle exactly
+ * that placement at runtime.
+ *
+ * Use the inline controls to change the popup `size` and the sticky
+ * placement. The same controls render both outside and inside the
+ * dialog and stay in sync.
+ */
+export const Scrollable: Story = {
+	args: {
+		children: <ScrollableContent />,
+	},
 };
 
 /**
@@ -182,10 +323,13 @@ export const WithVisuallyHiddenTitle: Story = {
 						</VisuallyHidden>
 						<Dialog.CloseIcon />
 					</Dialog.Header>
-					<p>
-						This dialog has a visually hidden title. Inspect the DOM
-						or use a screen reader to verify the heading is present.
-					</p>
+					<Dialog.Content>
+						<p style={ { margin: 0 } }>
+							This dialog has a visually hidden title. Inspect the
+							DOM or use a screen reader to verify the heading is
+							present.
+						</p>
+					</Dialog.Content>
 					<Dialog.Footer>
 						<Dialog.Action>Got it</Dialog.Action>
 					</Dialog.Footer>

package/src/dialog/style.module.css

@@ -21,7 +21,15 @@
 		}
 	}
 
+	/*
+	 * The popup is a flex column that lays out three regions — header,
+	 * content, footer — as siblings. The middle `.content` region owns the
+	 * scroll; the popup itself clips to its rounded border. See
+	 * `overlay-chrome.module.css` for the shared chrome/content primitives.
+	 */
 	.popup {
+		--viewport-inset: var(--wpds-dimension-padding-2xl);
+
 		position: fixed;
 		top: 50%;
 		/* stylelint-disable-next-line plugin/use-logical-properties-and-values -- Physical centering technique used with transform: translate(-50%, -50%) */
@@ -29,14 +37,16 @@
 		z-index: var(--wp-ui-dialog-z-index, initial);
 		transform: translate(-50%, -50%);
 		box-sizing: border-box;
+		display: flex;
+		flex-direction: column;
 		min-width: var(--wpds-dimension-surface-width-sm);
-		width: calc(100vw - 2 * var(--wpds-dimension-padding-2xl));
-		max-height: calc(100vh - 2 * var(--wpds-dimension-padding-2xl));
-		padding: var(--wpds-dimension-padding-2xl);
+		width: calc(100vw - 2 * var(--viewport-inset));
+		max-height: calc(100dvh - 2 * var(--viewport-inset));
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
 		border-radius: var(--wpds-border-radius-lg);
+		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		box-shadow: var(--wpds-elevation-lg);
-		overflow: auto;
+		overflow: hidden;
 		font-family: var(--wpds-typography-font-family-body);
 		font-size: var(--wpds-typography-font-size-md);
 		line-height: var(--wpds-typography-line-height-md);
@@ -86,35 +96,75 @@
 			 * Force full height (full width is already in default styles).
 			 * The max-{width,height} properties will make sure some padding is shown.
 			 */
-			height: 100vh;
+			height: 100dvh;
+		}
+	}
+
+	/*
+	 * When a backdrop is rendered alongside the popup (modal mode),
+	 * hide the regular-mode border. The backdrop already provides
+	 * visual containment, so the border becomes redundant noise.
+	 * `transparent` (not `none`) keeps popup geometry identical
+	 * across modal/non-modal — `box-sizing: border-box` absorbs the
+	 * 1px into the existing box.
+	 */
+	.backdrop ~ * .popup {
+		border-color: transparent;
+	}
+
+	/*
+	 * Forced-colors mode strips `box-shadow` and substitutes
+	 * `background-color` with `Canvas` (the page background), so the
+	 * boundary depends entirely on the border. Set `CanvasText`
+	 * explicitly for both modal and non-modal popups: `transparent`
+	 * is not substituted by the UA, and being explicit also removes
+	 * any reliance on UA color-substitution behavior for the
+	 * non-modal case.
+	 */
+	@media (forced-colors: active) {
+		.popup,
+		.backdrop ~ * .popup {
+			border-color: CanvasText;
 		}
 	}
 
+	/*
+	 * Chrome + content primitives are centralized in
+	 * `overlay-chrome.module.css` and shared with `drawer/style.module.css`
+	 * and `alert-dialog/popup.tsx`. Separator coloring and the modal
+	 * overscroll rule live there as well, keyed off the
+	 * `data-wp-ui-overlay-scroll-container` attribute that
+	 * `useOverlayScrollStateAttributes` sets on the scroll container.
+	 */
 	.header {
-		display: flex;
-		align-items: center;
-		gap: var(--wpds-dimension-gap-sm);
-		margin-bottom: var(--wpds-dimension-gap-lg);
+		composes: header from "../utils/css/overlay-chrome.module.css";
+	}
+
+	.footer {
+		composes: footer from "../utils/css/overlay-chrome.module.css";
 	}
 
 	.title {
-		margin-inline-end: auto;
+		composes: title from "../utils/css/overlay-chrome.module.css";
+	}
 
-		/* Workaround: the GCD shorthand `margin` overrides the longhand above.
-		 * Keep both so the layout survives GCD removal. */
-		--_gcd-heading-margin: 0 auto 0 0;
+	.content {
+		composes: content from "../utils/css/overlay-chrome.module.css";
+	}
 
-		&:dir(rtl) {
-			--_gcd-heading-margin: 0 0 0 auto;
-		}
+	/*
+	 * Push the close icon to the inline end even when the title is taken out
+	 * of flow (e.g. wrapped in `VisuallyHidden`, which sets `position:
+	 * absolute`). In that case `.title`'s `margin-inline-end: auto` is a
+	 * no-op because the title no longer participates in the flex layout, so
+	 * we also anchor the close icon itself.
+	 */
+	.header [data-wp-ui-dialog-close-icon] {
+		margin-inline-start: auto;
 	}
 
-	.footer {
-		display: flex;
-		justify-content: flex-end;
-		align-items: center;
-		gap: var(--wpds-dimension-gap-sm);
-		margin-top: var(--wpds-dimension-gap-lg);
-		padding-top: var(--wpds-dimension-padding-lg);
+	.description {
+		margin-bottom: var(--wpds-dimension-gap-lg);
 	}
+
 }