@wordpress/components 39.0.0 → 40.1.0

package/src/utils/test/math.js

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { add, subtract, clamp, ensureValidStep } from '../math';
 
 describe( 'add', () => {

package/src/utils/test/rtl.js

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { convertLTRToRTL } from '../rtl';
 
 describe( 'convertLTRToRTL', () => {

package/src/utils/test/space.js

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { space } from '../space';
 
 describe( 'space', () => {

package/src/utils/test/strings.js

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { normalizeTextString } from '../strings';
 
 describe( 'normalizeTextString', () => {

package/src/utils/test/unit-values.js

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { createCSSUnitValue, parseCSSUnitValue } from '../unit-values';
 
 describe( 'unit-values', () => {

package/src/utils/theme-variables.scss

@@ -37,4 +37,3 @@ $components-color-light-gray-placeholder: color-mix(in srgb, $components-color-b
 // Semantic aliases (prefer these over raw gray values when applicable).
 $components-color-border: #{ $components-color-gray-600 };
 $components-color-disabled: #{ $components-color-gray-600 };
-$components-color-focus: var(--wp-components-color-accent, var(--wpds-color-stroke-focus));

package/src/v-stack/test/__snapshots__/{index.tsx.snap → index.jsdom.test.tsx.snap}

@@ -1,6 +1,6 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`props should render alignment 1`] = `
+exports[`props > should render alignment 1`] = `
 <div>
   <div
     class="style-flex style-items-column components-flex components-h-stack components-v-stack"
@@ -14,7 +14,7 @@ exports[`props should render alignment 1`] = `
 </div>
 `;
 
-exports[`props should render correctly 1`] = `
+exports[`props > should render correctly 1`] = `
 <div>
   <div
     class="style-flex style-items-column components-flex components-h-stack components-v-stack"
@@ -28,7 +28,7 @@ exports[`props should render correctly 1`] = `
 </div>
 `;
 
-exports[`props should render spacing 1`] = `
+exports[`props > should render spacing 1`] = `
 <div>
   <div
     class="style-flex style-items-column components-flex components-h-stack components-v-stack"

package/src/v-stack/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,7 +1,10 @@
+import { describe, expect, test } from 'vitest';
 import { render } from '@testing-library/react';
 import { View } from '../../view';
 import { VStack } from '..';
 
+globalThis.wpVitest.mockMatchMedia();
+
 describe( 'props', () => {
 	test( 'should render correctly', () => {
 		const { container } = render(

package/src/validated-form-controls/components/content-editable-control.tsx

@@ -1,6 +1,6 @@
 import clsx from 'clsx';
 import { forwardRef, useRef } from '@wordpress/element';
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import ContentEditableControl from '../../content-editable-control';
 
@@ -34,6 +34,7 @@ const UnforwardedValidatedContentEditableControl = (
 	return (
 		<div className="components-validated-control__wrapper-with-error-delegate">
 			<ControlWithError
+				className="components-validated-control"
 				required={ required }
 				markWhenOptional={ markWhenOptional }
 				customValidity={ customValidity }

package/src/validated-form-controls/components/custom-select-control.tsx

@@ -1,5 +1,5 @@
 import { forwardRef, useRef } from '@wordpress/element';
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import CustomSelectControl from '../../custom-select-control';
 
@@ -21,6 +21,7 @@ const UnforwardedValidatedCustomSelectControl = (
 			ref={ forwardedRef }
 		>
 			<ControlWithError
+				className="components-validated-control"
 				required={ required }
 				markWhenOptional={ markWhenOptional }
 				customValidity={ customValidity }

package/src/validated-form-controls/components/index.ts

@@ -1,9 +1,5 @@
-export * from './combobox-control';
 export * from './custom-select-control';
-export * from './form-token-field';
 export * from './input-control';
 export * from './range-control';
 export * from './content-editable-control';
 export * from './textarea-control';
-export * from './toggle-control';
-export * from './toggle-group-control';

package/src/validated-form-controls/components/input-control.tsx

@@ -1,6 +1,7 @@
 import { forwardRef, useRef } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
-import { ControlWithError } from '../control-with-error';
+import deprecated from '@wordpress/deprecated';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import InputControl from '../../input-control';
 
@@ -13,11 +14,18 @@ const UnforwardedValidatedInputControl = (
 	}: React.ComponentProps< typeof InputControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
+	deprecated( 'wp.components.privateApis.ValidatedInputControl', {
+		since: '7.2',
+		alternative: 'ValidatedInputControl from @wordpress/ui',
+		hint: 'This private API will be completely removed within a few Gutenberg plugin releases.',
+	} );
+
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

package/src/validated-form-controls/components/range-control.tsx

@@ -1,6 +1,6 @@
 import { useMergeRefs } from '@wordpress/compose';
 import { forwardRef, useRef } from '@wordpress/element';
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import RangeControl from '../../range-control';
 
@@ -18,6 +18,7 @@ const UnforwardedValidatedRangeControl = (
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

package/src/validated-form-controls/components/stories/content-editable-control.story.tsx

@@ -4,6 +4,12 @@ import { formDecorator } from './story-utils';
 import { ValidatedContentEditableControl } from '../content-editable-control';
 
 const meta: Meta< typeof ValidatedContentEditableControl > = {
+	parameters: {
+		// FIXME: Contenteditable control is unlabeled (label).
+		// See: https://github.com/WordPress/gutenberg/issues/81596
+		a11y: { test: 'todo' },
+	},
+
 	title: 'Components/Selection & Input/Validated Form Controls/ValidatedContentEditableControl',
 	id: 'components-validatedcontenteditablecontrol',
 	component: ValidatedContentEditableControl,

package/src/validated-form-controls/components/stories/custom-select-control.story.tsx

@@ -4,6 +4,12 @@ import { ValidatedCustomSelectControl } from '../custom-select-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedCustomSelectControl > = {
+	parameters: {
+		// FIXME: Select lacks an accessible name in this story (select-name).
+		// See: https://github.com/WordPress/gutenberg/issues/81596
+		a11y: { test: 'todo' },
+	},
+
 	title: 'Components/Selection & Input/Validated Form Controls/ValidatedCustomSelectControl',
 	id: 'components-validatedcustomselectcontrol',
 	component: ValidatedCustomSelectControl,

package/src/validated-form-controls/components/stories/overview.mdx

@@ -1,52 +1,9 @@
-import { ArgTypes, Meta, Stories } from '@storybook/addon-docs/blocks';
-import * as OverviewStories from './overview.story';
-import { ValidatedInputControl } from '..';
+import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta of={ OverviewStories } title="Components/Selection & Input/Validated Form Controls/Overview" />
+<Meta title="Components/Selection & Input/Validated Form Controls/Overview" />
 
 # Validated Form Controls
 
-This section contains form control components that extend [WordPress components](https://wordpress.github.io/gutenberg/) with additional validation capabilities.
+Documentation for validated form controls has moved to `@wordpress/ui`.
 
-## Status: Beta
-
-We are still gathering feedback and iterating. Please get in touch with `@WordPress/gutenberg-components`  if you are interested in trying them out in the Gutenberg app.
-
-## Usage
-
-Component APIs are the same as the underlying WordPress components, with the addition of some optional props:
-
-<ArgTypes of={ ValidatedInputControl } include={ [ 'required', 'markWhenOptional', 'customValidity' ] } />
-
-## Implementation
-
-These components are designed to work with the native HTML5 [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/API/Constraint_validation). Using this browser API as the "source of truth" for form element errors has these benefits:
-
-- Ability to use CSS selectors like `:invalid`, `:user-invalid`, `:required`, and `:optional`.
-- Ability to use simple HTML attribute-based constraints (e.g. `min`, `max`, `required`, `pattern`, `type`) together with fully custom validation logic (with the `setCustomValidity()` method).
-- Attribute-based constraints will already have localized, user-facing error messages built in.
-- When a user clicks the form submit button, the browser will automatically check the validity states of all enclosed form elements and block the submit when there are errors. It will also automatically scroll and focus to the first erroring element and show a prominent error popover.
-- While not _all_ aspects of the Constraint Validation API are well-supported in all screen readers yet, many aspects are, and will continue to improve. We can supplement any accessibility shortcomings with things like `aria-live` announcements of error messages.
-
-## Current limitations
-
-### No easy access to underlying validation APIs
-
-- The consumer does not have a simple way to show validation messages at an arbitrary point in time, unless the fields are wrapped in a `form` element. Currently, when to show validation messages to the user are handled by the component — any messages are first made visible on `blur` after the field is considered "touched", or if the user tries to submit the enclosing `form`. Messages can also be triggered to show at any time by calling the `reportValidity()` method on the wrapping `<form>` element.
-- The consumer does not have direct access to the [`validity` object](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) of the underlying element.
-
-We don't foresee these being needed much, but it is technically possible by the consumer accessing the target element's validation APIs via `ref`. Better docs or ergonomics can be added when we have actual use cases.
-
-### Delegate elements
-
-The implementations for `ToggleGroupControl`, `CustomSelectControl`, and `FormTokenField` use a "delegate" element for validation, due to upstream limitations that prevent us from using the actual underlying elements for constraint validation. A delegate element in this context is a visually hidden form element that we "delegate" the Constraint Validation API concerns to.
-
-This is not ideal, but lets us maintain a consistent mechanism to scroll to the invalid field when attempting to submit, and block the form from submitting. It is hopefully fine as a stopgap, given the low amount of actual validation that will need happen on these two specific components.
-
-### Controlled mode only
-
-Some of the underlying WordPress components currently do not fully support uncontrolled mode. For now, we recommend sticking to controlled mode to avoid any issues.
-
-## Examples
-
-<Stories />
+See the [Validated Form Controls overview](?path=/docs/design-system-form-with-validation-overview--docs) in the Design System docs.

package/src/validated-form-controls/components/textarea-control.tsx

@@ -1,6 +1,7 @@
 import { forwardRef, useRef } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
-import { ControlWithError } from '../control-with-error';
+import deprecated from '@wordpress/deprecated';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import TextareaControl from '../../textarea-control';
 
@@ -13,11 +14,18 @@ const UnforwardedValidatedTextareaControl = (
 	}: React.ComponentProps< typeof TextareaControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLTextAreaElement >
 ) => {
+	deprecated( 'wp.components.privateApis.ValidatedTextareaControl', {
+		since: '7.2',
+		alternative: 'ValidatedTextareaControl from @wordpress/ui',
+		hint: 'This private API will be completely removed within a few Gutenberg plugin releases.',
+	} );
+
 	const validityTargetRef = useRef< HTMLTextAreaElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

package/src/validated-form-controls/index.ts

@@ -1,2 +1 @@
 export * from './components';
-export * from './control-with-error';

package/src/validated-form-controls/style.scss

@@ -1,27 +1,23 @@
-@use "@wordpress/base-styles/colors" as *;
-@use "@wordpress/base-styles/variables" as *;
-@use "../utils/theme-variables" as *;
+%red-focus-ring {
+	--focus-color: var(--wpds-color-stroke-interactive-error);
+}
+
+%red-error-border {
+	@extend %red-focus-ring;
+
+	border-color: var(--wpds-color-stroke-interactive-error);
+}
 
 .components-validated-control {
 	// For components based on InputBase
 	&:has(:is(input, select):invalid[data-validity-visible])
 	.components-input-control__backdrop {
-		--wp-components-color-accent: #{$alert-red};
-		border-color: $alert-red;
+		@extend %red-error-border;
 	}
 
 	// For TextareaControl
 	textarea:invalid[data-validity-visible] {
-		--wp-admin-theme-color: #{$alert-red};
-		--wp-components-color-accent: #{$alert-red};
-		border-color: $alert-red;
-	}
-
-	// For ComboboxControl
-	.components-combobox-control__suggestions-container:has(
-	input:invalid[data-validity-visible]
-):not(:has([aria-expanded="true"])) {
-		--wp-admin-theme-color: #{$alert-red};
+		@extend %red-error-border;
 	}
 }
 
@@ -30,26 +26,13 @@
 
 	// For CustomSelectControl
 	&:has(select:invalid[data-validity-visible]) .components-input-control__backdrop {
-		--wp-components-color-accent: #{$alert-red};
-		border-color: $alert-red;
-	}
-
-	// For ToggleGroupControl
-	&:has(input[type="radio"]:invalid[data-validity-visible]) {
-		--wp-components-color-accent: #{$alert-red};
-	}
-
-	// For FormTokenField
-	&:has(input:invalid[data-validity-visible]) .components-form-token-field__input-container:not(:has([aria-expanded="true"])) {
-		--wp-admin-theme-color: #{$alert-red};
-		border-color: $alert-red;
+		@extend %red-error-border;
 	}
 
 	// For ContentEditableControl
 	&:has(input:invalid[data-validity-visible])
 	.components-validated-control__content-editable [role="textbox"] {
-		--wp-admin-theme-color: #{$alert-red};
-		border-color: $alert-red;
+		@extend %red-error-border;
 	}
 }
 
@@ -61,46 +44,3 @@
 	opacity: 0;
 	pointer-events: none;
 }
-
-.components-validated-control__indicator {
-	display: flex;
-	align-items: flex-start;
-	gap: 4px;
-	margin: 8px 0 0;
-	font-family: $font-family-body;
-	font-size: $font-size-small;
-	line-height: 16px; // matches the icon size
-	color: $components-color-gray-700;
-	animation:
-		components-validated-control__indicator-jump 0.2s
-		cubic-bezier(0.68, -0.55, 0.27, 1.55);
-
-	&.is-invalid {
-		color: $alert-red;
-	}
-
-	&.is-valid {
-		color: color-mix(in srgb, $black 30%, $alert-green);
-	}
-}
-
-.components-validated-control__indicator-icon {
-	flex-shrink: 0;
-}
-
-.components-validated-control__indicator-spinner {
-	margin: 2px;
-	width: $grid-unit-15;
-	height: $grid-unit-15;
-}
-
-@keyframes components-validated-control__indicator-jump {
-	0% {
-		transform: translateY(-4px);
-		opacity: 0;
-	}
-	100% {
-		transform: translateY(0);
-		opacity: 1;
-	}
-}

package/src/validated-form-controls/test/{content-editable-control.tsx → content-editable-control.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedContentEditableControl } from '../components';
@@ -21,7 +22,6 @@ describe( 'ValidatedContentEditableControl', () => {
 	// not the editable that assistive technology interacts with. This is the
 	// same pre-existing limitation as the other delegate-based controls,
 	// tracked in #76741.
-	// eslint-disable-next-line jest/no-disabled-tests
 	it.skip( 'should append the validation error alongside the help description', async () => {
 		const user = userEvent.setup();
 		render(

package/src/validated-form-controls/test/{custom-select-control.tsx → custom-select-control.jsdom.test.tsx}

@@ -1,7 +1,10 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedCustomSelectControl } from '../components';
 
+globalThis.wpVitest.mockMatchMedia();
+
 describe( 'ValidatedCustomSelectControl', () => {
 	const options = [
 		{ key: 'small', name: 'Small' },

package/src/validated-form-controls/test/{input-control.tsx → input-control.jsdom.test.tsx}

@@ -1,7 +1,22 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedInputControl } from '../components';
 
+globalThis.wpVitest.mockMatchMedia();
+
+describe( 'Shows a deprecation warning', () => {
+	it( 'ValidatedInputControl', () => {
+		render(
+			<ValidatedInputControl label="URL" help="Enter a full URL." />
+		);
+
+		expect( console ).toHaveWarnedWith(
+			'wp.components.privateApis.ValidatedInputControl is deprecated since version 7.2. Please use ValidatedInputControl from @wordpress/ui instead. Note: This private API will be completely removed within a few Gutenberg plugin releases.'
+		);
+	} );
+} );
+
 describe( 'ValidatedInputControl', () => {
 	it( 'should preserve the help description', () => {
 		render(

package/src/validated-form-controls/test/{range-control.tsx → range-control.jsdom.test.tsx}

@@ -1,8 +1,11 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useState, useRef } from '@wordpress/element';
 import { ValidatedRangeControl } from '../components';
 
+globalThis.wpVitest.mockMatchMedia();
+
 describe( 'ValidatedRangeControl', () => {
 	it( 'should preserve the help description', () => {
 		render(

package/src/validated-form-controls/test/{textarea-control.tsx → textarea-control.jsdom.test.tsx}

@@ -1,7 +1,25 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedTextareaControl } from '../components';
 
+describe( 'Shows a deprecation warning', () => {
+	it( 'ValidatedTextareaControl', () => {
+		render(
+			<ValidatedTextareaControl
+				label="Bio"
+				help="A short bio."
+				onChange={ () => {} }
+				value=""
+			/>
+		);
+
+		expect( console ).toHaveWarnedWith(
+			'wp.components.privateApis.ValidatedTextareaControl is deprecated since version 7.2. Please use ValidatedTextareaControl from @wordpress/ui instead. Note: This private API will be completely removed within a few Gutenberg plugin releases.'
+		);
+	} );
+} );
+
 describe( 'ValidatedTextareaControl', () => {
 	it( 'should preserve the help description', () => {
 		render(

package/src/view/test/__snapshots__/{index.js.snap → index.jsdom.test.tsx.snap}

@@ -1,6 +1,6 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`props should ignore legacy css prop styles (array) 1`] = `
+exports[`props > should ignore legacy css prop styles (array) 1`] = `
 <div>
   <p
     data-testid="custom-css-array-view"
@@ -10,7 +10,7 @@ exports[`props should ignore legacy css prop styles (array) 1`] = `
 </div>
 `;
 
-exports[`props should ignore legacy css prop styles (object) 1`] = `
+exports[`props > should ignore legacy css prop styles (object) 1`] = `
 <div>
   <p
     data-testid="custom-css-object-view"
@@ -20,7 +20,7 @@ exports[`props should ignore legacy css prop styles (object) 1`] = `
 </div>
 `;
 
-exports[`props should ignore legacy css prop styles (string) 1`] = `
+exports[`props > should ignore legacy css prop styles (string) 1`] = `
 <div>
   <p
     data-testid="custom-css-string-view"
@@ -30,7 +30,7 @@ exports[`props should ignore legacy css prop styles (string) 1`] = `
 </div>
 `;
 
-exports[`props should render as a custom component 1`] = `
+exports[`props > should render as a custom component 1`] = `
 <div>
   <section
     class="custom-class"
@@ -42,7 +42,7 @@ exports[`props should render as a custom component 1`] = `
 </div>
 `;
 
-exports[`props should render as another element 1`] = `
+exports[`props > should render as another element 1`] = `
 <div>
   <p>
     <span />
@@ -50,7 +50,7 @@ exports[`props should render as another element 1`] = `
 </div>
 `;
 
-exports[`props should render correctly 1`] = `
+exports[`props > should render correctly 1`] = `
 <div>
   <div>
     <span />

package/src/view/test/{index.js → index.jsdom.test.tsx}

@@ -1,4 +1,6 @@
+import { describe, expect, test, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
+import type { ComponentPropsWithoutRef } from 'react';
 import { forwardRef } from '@wordpress/element';
 import { View } from '../index';
 
@@ -22,11 +24,14 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render as a custom component', () => {
-		const CustomComponent = forwardRef( ( props, ref ) => (
+		const CustomComponent = forwardRef<
+			HTMLElement,
+			ComponentPropsWithoutRef< 'section' >
+		>( ( props, ref ) => (
 			<section ref={ ref } data-custom-component { ...props } />
 		) );
 
-		const ref = jest.fn();
+		const ref = vi.fn();
 		const { container } = render(
 			<View
 				as={ CustomComponent }

package/src/z-stack/component.tsx

@@ -1,8 +1,10 @@
+import clsx from 'clsx';
 import type { ForwardedRef } from 'react';
 import { isValidElement } from '@wordpress/element';
 import { getValidChildren } from '../utils/get-valid-children';
 import { contextConnect, useContextSystem } from '../context';
-import { ZStackView, ZStackChildView } from './styles';
+import { PolymorphicElement } from '../utils/polymorphic-element';
+import styles from './style.module.scss';
 import type { ZStackProps } from './types';
 import type { WordPressComponentProps } from '../context';
 
@@ -31,25 +33,31 @@ function UnconnectedZStack(
 		const key = isValidElement( child ) ? child.key : index;
 
 		return (
-			<ZStackChildView
-				offsetAmount={ offsetAmount }
-				zIndex={ zIndex }
+			<div
+				className={ styles.child }
+				style={ {
+					'--z-stack-offset': `${ offsetAmount }px`,
+					'--z-stack-z-index': zIndex,
+				} }
 				key={ key }
 			>
 				{ child }
-			</ZStackChildView>
+			</div>
 		);
 	} );
 
 	return (
-		<ZStackView
+		<PolymorphicElement
 			{ ...otherProps }
-			className={ className }
-			isLayered={ isLayered }
+			className={ clsx(
+				styles[ 'z-stack' ],
+				isLayered && styles.layered,
+				className
+			) }
 			ref={ forwardedRef }
 		>
 			{ clonedChildren }
-		</ZStackView>
+		</PolymorphicElement>
 	);
 }
 

package/src/z-stack/style.module.scss

@@ -0,0 +1,26 @@
+.z-stack {
+	display: inline-grid;
+	grid-auto-flow: column;
+	position: relative;
+
+	> .child {
+		position: relative;
+		justify-self: start;
+	}
+}
+
+// When the ZStack is layered, all items overlap in the same grid cell.
+// Kept at the top level so that the selector retains the same specificity
+// as `.z-stack > .child` above, matching the original Emotion styles.
+.layered > .child {
+	grid-row-start: 1;
+	grid-column-start: 1;
+}
+
+.child {
+	z-index: var(--z-stack-z-index, auto);
+
+	&:not(:first-of-type) {
+		margin-inline-start: var(--z-stack-offset, 0);
+	}
+}