@wordpress/ui 0.2.0

package/README.md

@@ -0,0 +1,82 @@
+# (Experimental) UI
+
+A package that provides React UI components for the WordPress Design System, built on themeable design tokens.
+
+While similar in scope to `@wordpress/components`, there are a few key differences:
+
+-   `@wordpress/components` grew organically as a collection of unrelated UI elements for WordPress screens. In contrast, this package is an implementation of a design system that guarantees user- and developer-facing cohesion between components.
+-   Unlike `@wordpress/components`, this package is not bundled as a WordPress script available on the `window.wp` global and is instead distributed as an npm package that follows [semantic versioning](https://semver.org/) for release changes.
+
+This is a companion to the `@wordpress/theme` package that provides:
+
+-   **Design Tokens**: A comprehensive system of design tokens for colors, spacing, typography, and more
+-   **Theme System**: A flexible theming provider for consistent theming across applications
+
+## Usage
+
+### Basic Component Usage
+
+```tsx
+import { Box } from '@wordpress/ui';
+
+function MyComponent() {
+	return (
+		<Box background="neutral" padding="small">
+			Hello World
+		</Box>
+	);
+}
+```
+
+## Core Design Principles
+
+All components in the design system follow consistent patterns for maximum flexibility and developer experience:
+
+### Custom Rendering
+
+Every component supports the `render` prop for complete control over the underlying HTML element:
+
+```tsx
+import { Box } from '@wordpress/ui';
+
+function MyComponent() {
+	// Render Box as a <span /> instead of the default <div />
+	return <Box render={ <span /> }>{ /* ... */ }</Box>;
+}
+```
+
+### Ref Forwarding
+
+All components forward refs to their underlying DOM elements:
+
+```tsx
+import { useRef } from '@wordpress/element';
+import { Box } from '@wordpress/ui';
+
+function MyComponent() {
+	const boxRef = useRef< HTMLDivElement >( null );
+
+	return <Box ref={ boxRef }>{ /* ... */ }</Box>;
+}
+```
+
+### Automatic `className` Merging
+
+Components merge provided `className` props with their internal styles:
+
+```tsx
+import { Box } from '@wordpress/ui';
+
+function MyComponent() {
+	// Your custom CSS className is merged with component styles
+	return <Box className="my-custom-class">{ /* ... */ }</Box>;
+}
+```
+
+## Contributing to this package
+
+This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
+
+To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

package/build-types/box/box.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal dependencies
+ */
+import { type BoxProps } from './types';
+/**
+ * A low-level visual primitive that provides an interface for applying design
+ * token-based customization for background, text, padding, and more.
+ */
+export declare const Box: import("react").ForwardRefExoticComponent<BoxProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=box.d.ts.map

package/build-types/box/box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/box/box.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAoExC;;;GAGG;AACH,eAAO,MAAM,GAAG,qGAgCb,CAAC"}

package/build-types/box/index.d.ts

@@ -0,0 +1,2 @@
+export { Box } from './box';
+//# sourceMappingURL=index.d.ts.map

package/build-types/box/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/box/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC"}

package/build-types/box/stories/index.story.d.ts

@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import { type Meta, type StoryObj } from '@storybook/react';
+import '@wordpress/theme/design-tokens.css';
+/**
+ * Internal dependencies
+ */
+import { Box } from '../box';
+declare const meta: Meta<typeof Box>;
+export default meta;
+type Story = StoryObj<typeof Box>;
+export declare const Default: Story;
+export declare const DirectionalPadding: Story;
+//# sourceMappingURL=index.story.d.ts.map

package/build-types/box/stories/index.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/box/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAM5D,OAAO,oCAAoC,CAAC;AAE5C;;GAEG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAK7B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,GAAG,CAW3B,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,GAAG,CAAE,CAAC;AAEpC,eAAO,MAAM,OAAO,EAAE,KAiBrB,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,KAWhC,CAAC"}

package/build-types/box/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal dependencies
+ */
+import { type ComponentProps } from '../utils/types';
+type SizeToken = 'x-small' | 'small' | 'medium' | 'large';
+type Size = number | SizeToken;
+type BackgroundColor = 'neutral' | 'neutral-strong' | 'neutral-weak' | 'brand' | 'success' | 'success-weak' | 'info' | 'info-weak' | 'warning' | 'warning-weak' | 'caution' | 'caution-weak' | 'error' | 'error-weak';
+type ForegroundColor = 'neutral' | 'neutral-weak' | 'success' | 'success-weak' | 'info' | 'info-weak' | 'warning' | 'warning-weak' | 'caution' | 'caution-weak' | 'error' | 'error-weak';
+type DimensionVariant<T> = {
+    block?: T;
+    blockStart?: T;
+    blockEnd?: T;
+    inline?: T;
+    inlineStart?: T;
+    inlineEnd?: T;
+};
+export interface BoxProps extends ComponentProps<'div'> {
+    /**
+     * The target rendering element design token grouping to use for the box.
+     */
+    target?: string;
+    /**
+     * The surface background design token for box background color.
+     *
+     * Shorthand for `backgroundColor`.
+     */
+    bg?: BackgroundColor;
+    /**
+     * The surface background design token for box background color.
+     */
+    backgroundColor?: BackgroundColor;
+    /**
+     * The surface foreground design token for box text color.
+     *
+     * Shorthand for `color`.
+     */
+    fg?: ForegroundColor;
+    /**
+     * The surface foreground design token for box text color.
+     */
+    color?: ForegroundColor;
+    /**
+     * The surface spacing design token or base unit multiplier for box padding.
+     *
+     * Shorthand for `padding`.
+     */
+    p?: Size | DimensionVariant<Size>;
+    /**
+     * The surface spacing design token or base unit multiplier for box padding.
+     */
+    padding?: Size | DimensionVariant<Size>;
+    /**
+     * The content to be rendered inside the component.
+     */
+    children?: React.ReactNode;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/build-types/box/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/box/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,KAAK,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,KAAK,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/B,KAAK,eAAe,GACjB,SAAS,GACT,gBAAgB,GAChB,cAAc,GACd,OAAO,GACP,SAAS,GACT,cAAc,GACd,MAAM,GACN,WAAW,GACX,SAAS,GACT,cAAc,GACd,SAAS,GACT,cAAc,GACd,OAAO,GACP,YAAY,CAAC;AAEhB,KAAK,eAAe,GACjB,SAAS,GACT,cAAc,GACd,SAAS,GACT,cAAc,GACd,MAAM,GACN,WAAW,GACX,SAAS,GACT,cAAc,GACd,SAAS,GACT,cAAc,GACd,OAAO,GACP,YAAY,CAAC;AAEhB,KAAK,gBAAgB,CAAE,CAAC,IAAK;IAC5B,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,UAAU,CAAC,EAAE,CAAC,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,CAAC;CACd,CAAC;AAEF,MAAM,WAAW,QAAS,SAAQ,cAAc,CAAE,KAAK,CAAE;IACxD;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,EAAE,CAAC,EAAE,eAAe,CAAC;IAErB;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;;OAIG;IACH,EAAE,CAAC,EAAE,eAAe,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IAExB;;;;OAIG;IACH,CAAC,CAAC,EAAE,IAAI,GAAG,gBAAgB,CAAE,IAAI,CAAE,CAAC;IAEpC;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,gBAAgB,CAAE,IAAI,CAAE,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}

package/build-types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './box';
+//# sourceMappingURL=index.d.ts.map

package/build-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/build-types/lock-unlock.d.ts

@@ -0,0 +1,2 @@
+export declare const lock: (object: unknown, privateData: unknown) => void, unlock: <T = any>(object: unknown) => T;
+//# sourceMappingURL=lock-unlock.d.ts.map

package/build-types/lock-unlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-unlock.d.ts","sourceRoot":"","sources":["../src/lock-unlock.ts"],"names":[],"mappings":"AAKA,eAAO,MAAQ,IAAI,mDAAE,MAAM,iCAIzB,CAAC"}

package/build-types/utils/element.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import type { ComponentProps } from './types';
+type RenderProp<E extends React.ElementType> = NonNullable<ComponentProps<E>['render']>;
+/**
+ * Renders an element from a render prop (a component or an element), with
+ * merged props and ref.
+ *
+ * @param render The render prop (component or element).
+ * @param props  Props to pass to or merge with the element.
+ * @param ref    Optional ref to attach to the element.
+ * @return The rendered element.
+ */
+export declare const renderElement: <E extends React.ElementType>(render: RenderProp<E>, props: Omit<ComponentProps<E>, "render">, ref?: React.Ref<E extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[E] : Element>) => React.ReactElement;
+export {};
+//# sourceMappingURL=element.d.ts.map

package/build-types/utils/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../src/utils/element.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,KAAK,UAAU,CAAE,CAAC,SAAS,KAAK,CAAC,WAAW,IAAK,WAAW,CAC3D,cAAc,CAAE,CAAC,CAAE,CAAE,QAAQ,CAAE,CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAK,CAAC,SAAS,KAAK,CAAC,WAAW,EACzD,QAAQ,UAAU,CAAE,CAAC,CAAE,EACvB,OAAO,IAAI,CAAE,cAAc,CAAE,CAAC,CAAE,EAAE,QAAQ,CAAE,EAC5C,MAAM,KAAK,CAAC,GAAG,CACd,CAAC,SAAS,MAAM,qBAAqB,GAClC,qBAAqB,CAAE,CAAC,CAAE,GAC1B,OAAO,CACV,KACC,KAAK,CAAC,YAMR,CAAC"}

package/build-types/utils/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * External dependencies
+ */
+import { type ElementType, type ComponentPropsWithoutRef, type HTMLAttributes, type Ref } from 'react';
+type HTMLAttributesWithRef<T extends ElementType = any> = HTMLAttributes<T> & {
+    ref?: Ref<T> | undefined;
+};
+type ComponentRenderFn<Props> = (props: Props) => React.ReactElement<unknown>;
+export type ComponentProps<E extends ElementType> = Omit<ComponentPropsWithoutRef<E>, 'className' | 'children' | 'render'> & {
+    /**
+     * CSS class name to apply to the component.
+     */
+    className?: string;
+    /**
+     * Replaces the component's default HTML element using a given React
+     * element, or a function that returns a React element.
+     */
+    render?: ComponentRenderFn<HTMLAttributesWithRef> | React.ReactElement<Record<string, unknown>>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/build-types/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,MAAM,OAAO,CAAC;AAEf,KAAK,qBAAqB,CAAE,CAAC,SAAS,WAAW,GAAG,GAAG,IACtD,cAAc,CAAE,CAAC,CAAE,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAE,CAAC,CAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,KAAK,iBAAiB,CAAE,KAAK,IAAK,CACjC,KAAK,EAAE,KAAK,KACR,KAAK,CAAC,YAAY,CAAE,OAAO,CAAE,CAAC;AAEnC,MAAM,MAAM,cAAc,CAAE,CAAC,SAAS,WAAW,IAAK,IAAI,CACzD,wBAAwB,CAAE,CAAC,CAAE,EAC7B,WAAW,GAAG,UAAU,GAAG,QAAQ,CACnC,GAAG;IACH;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EACJ,iBAAiB,CAAE,qBAAqB,CAAE,GAC1C,KAAK,CAAC,YAAY,CAAE,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAE,CAAC;CACnD,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@wordpress/ui",
+	"version": "0.2.0",
+	"description": "Themeable React UI components for the WordPress Design System.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"components"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/ui/README.md",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/ui"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=20.10.0",
+		"npm": ">=10.2.3"
+	},
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.js",
+			"default": "./build/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"wpScript": false,
+	"sideEffects": false,
+	"dependencies": {
+		"@wordpress/element": "^6.35.0",
+		"@wordpress/private-apis": "^1.35.0"
+	},
+	"devDependencies": {
+		"@wordpress/theme": "^0.2.0"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0",
+		"react-dom": "^18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "77aa1f194edceafe8ac2a1b9438bf84b557e76e3"
+}

package/src/box/box.tsx

@@ -0,0 +1,113 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { type BoxProps } from './types';
+import { renderElement } from '../utils/element';
+
+/**
+ * Default render function that renders a div element with the given props.
+ *
+ * @param props The props to apply to the HTML element.
+ */
+const DEFAULT_RENDER = ( props: React.ComponentPropsWithoutRef< 'div' > ) => (
+	<div { ...props } />
+);
+
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str The string to capitalize.
+ * @return The capitalized string.
+ */
+const capitalize = ( str: string ): string =>
+	str.charAt( 0 ).toUpperCase() + str.slice( 1 );
+
+/**
+ * Converts a size value to a CSS design token property reference (with
+ * fallback) or a calculated value based on the base unit.
+ *
+ * @param property The CSS property name.
+ * @param target   The design system token target.
+ * @param value    The size value, either a number (multiplier of base unit) or a string (token name).
+ * @return A CSS value string with variable references.
+ */
+const getSpacingValue = (
+	property: string,
+	target: string,
+	value: number | string
+): string =>
+	typeof value === 'number'
+		? `calc(var(--wpds-dimension-base) * ${ value })`
+		: `var(--wpds-dimension-${ property }-${ target }-${ value }, var(--wpds-dimension-${ property }-surface-${ value }))`;
+
+/**
+ * Generates CSS styles for properties with optionally directional values,
+ * normalizing single values and objects with directional keys for logical
+ * properties.
+ *
+ * @param property The CSS property name from BoxProps.
+ * @param target   The design system token target.
+ * @param value    The property value (single or object with directional keys).
+ * @return A CSSProperties object with the computed styles.
+ */
+const getDimensionVariantStyles = < T extends keyof BoxProps >(
+	property: T,
+	target: string,
+	value: NonNullable< BoxProps[ T ] >
+): React.CSSProperties =>
+	typeof value !== 'object'
+		? { [ property ]: getSpacingValue( property, target, value ) }
+		: Object.keys( value ).reduce(
+				( result, key ) => ( {
+					...result,
+					[ property + capitalize( key ) ]: getSpacingValue(
+						property,
+						target,
+						value[ key ]
+					),
+				} ),
+				{} as Record< string, string >
+		  );
+
+/**
+ * A low-level visual primitive that provides an interface for applying design
+ * token-based customization for background, text, padding, and more.
+ */
+export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
+	{
+		target = 'surface',
+		backgroundColor,
+		color,
+		padding,
+		bg = backgroundColor,
+		fg = color,
+		p = padding,
+		render = DEFAULT_RENDER,
+		...props
+	},
+	ref
+) {
+	const style: React.CSSProperties = {};
+
+	if ( bg ) {
+		style.backgroundColor = `var(--wpds-color-bg-${ target }-${ bg }, var(--wpds-color-bg-surface-${ bg }))`;
+	}
+
+	if ( fg ) {
+		style.color = `var(--wpds-color-fg-${ target }-${ fg }, var(--wpds-color-fg-content-${ fg }))`;
+	}
+
+	if ( p ) {
+		Object.assign(
+			style,
+			getDimensionVariantStyles( 'padding', target, p )
+		);
+	}
+
+	return renderElement< 'div' >( render, { style, ...props }, ref );
+} );

package/src/box/index.ts

@@ -0,0 +1 @@
+export { Box } from './box';

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

@@ -0,0 +1,66 @@
+/**
+ * External dependencies
+ */
+import { type Meta, type StoryObj } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { privateApis } from '@wordpress/theme';
+import '@wordpress/theme/design-tokens.css'; // eslint-disable-line no-restricted-syntax
+
+/**
+ * Internal dependencies
+ */
+import { Box } from '../box';
+import { unlock } from '../../lock-unlock';
+
+const { ThemeProvider } = unlock( privateApis );
+
+const meta: Meta< typeof Box > = {
+	title: 'Design System/Components/Box',
+	component: Box,
+	decorators: [
+		( Story ) => (
+			<ThemeProvider>
+				<Story />
+			</ThemeProvider>
+		),
+	],
+	tags: [ 'status-experimental' ],
+};
+export default meta;
+
+type Story = StoryObj< typeof Box >;
+
+export const Default: Story = {
+	args: {
+		children: 'Box',
+		backgroundColor: 'info',
+		color: 'info',
+		padding: 4,
+	},
+	argTypes: {
+		p: {
+			control: 'select',
+			options: [ 'x-small', 'small', 'medium', 'large', 1, 2, 3, 4 ],
+		},
+		padding: {
+			control: 'select',
+			options: [ 'x-small', 'small', 'medium', 'large', 1, 2, 3, 4 ],
+		},
+	},
+};
+
+export const DirectionalPadding: Story = {
+	args: {
+		children: 'Box',
+		backgroundColor: 'info',
+		color: 'info',
+		padding: {
+			blockStart: 'small',
+			inline: 'medium',
+			blockEnd: 'large',
+		},
+	},
+};

package/src/box/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Internal dependencies
+ */
+import { type ComponentProps } from '../utils/types';
+
+type SizeToken = 'x-small' | 'small' | 'medium' | 'large';
+
+type Size = number | SizeToken;
+
+type BackgroundColor =
+	| 'neutral'
+	| 'neutral-strong'
+	| 'neutral-weak'
+	| 'brand'
+	| 'success'
+	| 'success-weak'
+	| 'info'
+	| 'info-weak'
+	| 'warning'
+	| 'warning-weak'
+	| 'caution'
+	| 'caution-weak'
+	| 'error'
+	| 'error-weak';
+
+type ForegroundColor =
+	| 'neutral'
+	| 'neutral-weak'
+	| 'success'
+	| 'success-weak'
+	| 'info'
+	| 'info-weak'
+	| 'warning'
+	| 'warning-weak'
+	| 'caution'
+	| 'caution-weak'
+	| 'error'
+	| 'error-weak';
+
+type DimensionVariant< T > = {
+	block?: T;
+	blockStart?: T;
+	blockEnd?: T;
+	inline?: T;
+	inlineStart?: T;
+	inlineEnd?: T;
+};
+
+export interface BoxProps extends ComponentProps< 'div' > {
+	/**
+	 * The target rendering element design token grouping to use for the box.
+	 */
+	target?: string;
+
+	/**
+	 * The surface background design token for box background color.
+	 *
+	 * Shorthand for `backgroundColor`.
+	 */
+	bg?: BackgroundColor;
+
+	/**
+	 * The surface background design token for box background color.
+	 */
+	backgroundColor?: BackgroundColor;
+
+	/**
+	 * The surface foreground design token for box text color.
+	 *
+	 * Shorthand for `color`.
+	 */
+	fg?: ForegroundColor;
+
+	/**
+	 * The surface foreground design token for box text color.
+	 */
+	color?: ForegroundColor;
+
+	/**
+	 * The surface spacing design token or base unit multiplier for box padding.
+	 *
+	 * Shorthand for `padding`.
+	 */
+	p?: Size | DimensionVariant< Size >;
+
+	/**
+	 * The surface spacing design token or base unit multiplier for box padding.
+	 */
+	padding?: Size | DimensionVariant< Size >;
+
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: React.ReactNode;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './box';

package/src/lock-unlock.ts

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
+		'@wordpress/dataviews'
+	);

package/src/utils/element.ts

@@ -0,0 +1,38 @@
+/**
+ * WordPress dependencies
+ */
+import { cloneElement } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { ComponentProps } from './types';
+
+type RenderProp< E extends React.ElementType > = NonNullable<
+	ComponentProps< E >[ 'render' ]
+>;
+
+/**
+ * Renders an element from a render prop (a component or an element), with
+ * merged props and ref.
+ *
+ * @param render The render prop (component or element).
+ * @param props  Props to pass to or merge with the element.
+ * @param ref    Optional ref to attach to the element.
+ * @return The rendered element.
+ */
+export const renderElement = < E extends React.ElementType >(
+	render: RenderProp< E >,
+	props: Omit< ComponentProps< E >, 'render' >,
+	ref?: React.Ref<
+		E extends keyof HTMLElementTagNameMap
+			? HTMLElementTagNameMap[ E ]
+			: Element
+	>
+): React.ReactElement => {
+	const propsWithRef = ref ? { ...props, ref } : props;
+
+	return typeof render === 'function'
+		? render( propsWithRef )
+		: cloneElement( render, propsWithRef );
+};

package/src/utils/types.ts

@@ -0,0 +1,34 @@
+/**
+ * External dependencies
+ */
+import {
+	type ElementType,
+	type ComponentPropsWithoutRef,
+	type HTMLAttributes,
+	type Ref,
+} from 'react';
+
+type HTMLAttributesWithRef< T extends ElementType = any > =
+	HTMLAttributes< T > & { ref?: Ref< T > | undefined };
+
+type ComponentRenderFn< Props > = (
+	props: Props
+) => React.ReactElement< unknown >;
+
+export type ComponentProps< E extends ElementType > = Omit<
+	ComponentPropsWithoutRef< E >,
+	'className' | 'children' | 'render'
+> & {
+	/**
+	 * CSS class name to apply to the component.
+	 */
+	className?: string;
+
+	/**
+	 * Replaces the component's default HTML element using a given React
+	 * element, or a function that returns a React element.
+	 */
+	render?:
+		| ComponentRenderFn< HTMLAttributesWithRef >
+		| React.ReactElement< Record< string, unknown > >;
+};