@wordpress/theme 0.1.0

package/src/stories/index.story.tsx

@@ -0,0 +1,426 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	useEffect,
+	useState,
+	useRef,
+	useId,
+	createPortal,
+} from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ThemeProvider } from '../theme-provider';
+
+const meta: Meta< typeof ThemeProvider > = {
+	title: 'Design System/Theme Provider',
+	component: ThemeProvider,
+	args: {
+		isRoot: true,
+	},
+	argTypes: {
+		children: {
+			control: false,
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+	tags: [ 'status-experimental' ],
+};
+export default meta;
+
+function getCSSCustomPropsFromStylesheets() {
+	const primitiveProps: Record< string, string > = {};
+	const semanticProps: Record< string, string > = {};
+	const legacyProps: Record< string, string > = {};
+
+	for ( const sheet of document.styleSheets ) {
+		try {
+			for ( const rule of sheet.cssRules || [] ) {
+				const ruleStyle = ( rule as CSSStyleRule ).style;
+				if ( ruleStyle ) {
+					for ( const name of ruleStyle ) {
+						if (
+							name.startsWith( '--wp-admin-theme' ) ||
+							name.startsWith( '--wp-components-color' )
+						) {
+							legacyProps[ name ] = ruleStyle
+								.getPropertyValue( name )
+								.trim();
+						}
+						if ( name.startsWith( '--wpds-color' ) ) {
+							if ( name.includes( 'private' ) ) {
+								primitiveProps[ name ] = ruleStyle
+									.getPropertyValue( name )
+									.trim();
+							} else {
+								semanticProps[ name ] = ruleStyle
+									.getPropertyValue( name )
+									.trim();
+							}
+						}
+					}
+				}
+			}
+		} catch ( e ) {
+			// Avoid security errors from cross-origin stylesheets
+			// eslint-disable-next-line no-console
+			console.error( e );
+			continue;
+		}
+	}
+
+	return { primitiveProps, semanticProps, legacyProps };
+}
+
+const ColorTokenTable = ( {
+	tokens,
+}: {
+	tokens: Record< string, string >;
+} ) => {
+	return (
+		<ul
+			style={ {
+				listStyle: 'none',
+				display: 'flex',
+				flexDirection: 'column',
+				gap: '0.5rem',
+			} }
+		>
+			{ Object.entries( tokens ).map( ( [ name ] ) => (
+				<li
+					key={ name }
+					style={ {
+						display: 'grid',
+						gridTemplateColumns: '80px	1fr',
+						alignItems: 'center',
+						gap: '0.5rem',
+					} }
+				>
+					<span
+						style={ {
+							backgroundColor: `var(${ name })`,
+							border: '1px solid var(--wpds-color-stroke-surface-neutral)',
+							width: '100%',
+							aspectRatio: '2/1',
+							display: 'block',
+						} }
+						aria-label={ name }
+					></span>
+					<code>{ name }</code>
+				</li>
+			) ) }
+		</ul>
+	);
+};
+
+const DSTokensList = () => {
+	const [ props, setProps ] = useState< {
+		semanticProps: Record< string, string >;
+		primitiveProps: Record< string, string >;
+		legacyProps: Record< string, string >;
+	} >( {
+		semanticProps: {},
+		primitiveProps: {},
+		legacyProps: {},
+	} );
+
+	useEffect( () => {
+		setProps( getCSSCustomPropsFromStylesheets() );
+	}, [] );
+
+	return (
+		<div style={ { color: 'var( --wpds-color-fg-content-neutral )' } }>
+			<h1>DS Color tokens</h1>
+			<h2>Semantic tokens (can be consumed directly)</h2>
+			<ColorTokenTable tokens={ props.semanticProps } />
+			<h2>Primitive tokens (should not be consumed directly)</h2>
+			<details>
+				<summary>Click to expand</summary>
+				<ColorTokenTable tokens={ props.primitiveProps } />
+			</details>
+			<h2>Legacy tokens (should not be consumed directly)</h2>
+			<details>
+				<summary>Click to expand</summary>
+				<ColorTokenTable tokens={ props.legacyProps } />
+			</details>
+		</div>
+	);
+};
+
+export const Default: StoryObj< typeof ThemeProvider > = {
+	args: {
+		children: <DSTokensList />,
+	},
+};
+
+export const WithPicker: StoryObj< typeof ThemeProvider > = {
+	render: ( args ) => {
+		const id = useId();
+		const [ primary, setPrimary ] = useState< undefined | string >();
+
+		return (
+			<ThemeProvider
+				{ ...args }
+				color={ {
+					primary,
+				} }
+			>
+				<div style={ { position: 'relative' } }>
+					<div
+						style={ {
+							position: 'sticky',
+							top: 0,
+							right: 0,
+							backgroundColor:
+								'var(--wpds-color-bg-surface-neutral)',
+							color: 'var( --wpds-color-fg-content-neutral )',
+							padding: '0.5rem',
+							borderRadius: '0.5rem',
+							boxShadow: '0 0 0.5rem 0 rgba(0, 0, 0, 0.1)',
+						} }
+					>
+						<div>
+							<input
+								type="color"
+								id={ id }
+								name="primary"
+								value={ primary }
+								onChange={ ( e ) =>
+									setPrimary( e.target.value )
+								}
+							/>
+							<label htmlFor={ id }>Pick the primary color</label>
+						</div>
+					</div>
+					{ args.children }
+				</div>
+			</ThemeProvider>
+		);
+	},
+	args: {
+		children: <DSTokensList />,
+	},
+};
+
+const NestingDebug = ( { bg = '', primary = '' } ) => (
+	<div
+		style={ {
+			padding: '0.25rem',
+			color: 'var(--wpds-color-fg-content-neutral)',
+			backgroundColor: 'var(--wpds-color-bg-surface-neutral)',
+			display: 'flex',
+			alignItems: 'center',
+			flexWrap: 'wrap',
+			gap: '1rem',
+		} }
+	>
+		<pre>
+			bg: { bg } | primary: { primary }
+		</pre>
+		<span
+			style={ {
+				display: 'inline-block',
+				padding: '0.25rem',
+				borderRadius: '0.25rem',
+				backgroundColor:
+					'var(--wpds-color-bg-interactive-brand-strong)',
+				color: 'var(--wpds-color-fg-interactive-brand-strong)',
+			} }
+		>
+			primary
+		</span>
+		<span
+			style={ {
+				display: 'inline-block',
+				marginInlineStart: '0.25rem',
+				padding: '0.25rem',
+				borderRadius: '0.25rem',
+				backgroundColor:
+					'var(--wpds-color-bg-interactive-brand-weak-disabled)',
+				color: 'var(--wpds-color-fg-content-neutral)',
+			} }
+		>
+			Neutral
+		</span>
+	</div>
+);
+
+export const NestingAndInheriting: StoryObj< typeof ThemeProvider > = {
+	render: () => {
+		return (
+			<ThemeProvider>
+				<NestingDebug bg="inherit (root)" primary="inherit (root)" />
+				<div style={ { paddingInlineStart: '1rem' } }>
+					<ThemeProvider
+						color={ {
+							bg: '#1e1e1e',
+						} }
+					>
+						<NestingDebug bg="#1e1e1e" primary="inherit (root)" />
+						<div style={ { paddingInlineStart: '1rem' } }>
+							<ThemeProvider>
+								<NestingDebug
+									bg="inherit (#1e1e1e)"
+									primary="inherit (root)"
+								/>
+								<div style={ { paddingInlineStart: '1rem' } }>
+									<ThemeProvider
+										color={ { primary: 'hotpink' } }
+									>
+										<NestingDebug
+											bg="inherit (#1e1e1e)"
+											primary="hotpink"
+										/>
+										<div
+											style={ {
+												paddingInlineStart: '1rem',
+											} }
+										>
+											<ThemeProvider
+												color={ { bg: '#f8f8f8' } }
+											>
+												<NestingDebug
+													bg="#f8f8f8"
+													primary="inherit (hotpink)"
+												/>
+											</ThemeProvider>
+										</div>
+									</ThemeProvider>
+								</div>
+							</ThemeProvider>
+						</div>
+					</ThemeProvider>
+				</div>
+			</ThemeProvider>
+		);
+	},
+};
+
+function IframeWithClonedTokenStyles( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const iframeRef = useRef< HTMLIFrameElement >( null );
+	const [ iframeLoaded, setIframeLoaded ] = useState( false );
+
+	// Copy the stylesheet where the DS tokens are defined to the iframe.
+	// While this technique is a bit hacky, it works well enough for the purpose
+	// of this demo.
+	// Consumers of the DS could instead reference the stylesheet directly.
+	useEffect( () => {
+		const iframe = iframeRef.current;
+		if ( ! iframe || ! iframe.contentDocument ) {
+			return;
+		}
+
+		const head = iframe.contentDocument.head;
+
+		// Filter styles associated with a theme provider
+		const allStyles = Array.from(
+			document.head.querySelectorAll( 'style, link[rel="stylesheet"]' )
+		);
+
+		allStyles.forEach( ( node ) => {
+			if ( node.tagName === 'STYLE' ) {
+				const text = node.textContent || '';
+				if ( text.includes( 'data-wpds-theme-provider-id' ) ) {
+					head.appendChild( node.cloneNode( true ) );
+				}
+			} else if ( node.tagName === 'LINK' ) {
+				// Fetch and inspect the stylesheet content
+				const href = ( node as HTMLLinkElement ).href;
+				fetch( href )
+					.then( ( res ) => res.text() )
+					.then( ( css ) => {
+						if ( css.includes( 'data-wpds-theme-provider-id' ) ) {
+							const linkClone = node.cloneNode( true );
+							head.appendChild( linkClone );
+						}
+					} )
+					.catch( ( err ) => {
+						// eslint-disable-next-line no-console
+						console.warn( 'Failed to load stylesheet:', href, err );
+					} );
+			}
+		} );
+
+		setIframeLoaded( true );
+	}, [] );
+
+	return (
+		<iframe
+			ref={ iframeRef }
+			style={ {
+				width: '100%',
+				height: '400px',
+				border: '1px solid #ccc',
+			} }
+			title="demo"
+		>
+			{ iframeLoaded &&
+				iframeRef.current?.contentDocument?.body &&
+				createPortal(
+					children,
+					iframeRef.current.contentDocument.body
+				) }
+		</iframe>
+	);
+}
+
+export const AcrossIframes: StoryObj< typeof ThemeProvider > = {
+	render: ( args ) => {
+		return (
+			<ThemeProvider { ...args }>
+				{ args.children }
+
+				<IframeWithClonedTokenStyles>
+					<div
+						style={ {
+							color: 'var(--wpds-color-fg-content-neutral)',
+						} }
+					>
+						In the iframe, but outside of `ThemeProvider`
+					</div>
+					<ThemeProvider
+						{ ...args }
+						// Note: the isRoot prop is necessary to apply the DS tokens to any
+						// UI rendered outside of the ThemeProvider (including overlays, etc)
+						isRoot
+					>
+						{ args.children }
+					</ThemeProvider>
+				</IframeWithClonedTokenStyles>
+			</ThemeProvider>
+		);
+	},
+	args: {
+		children: (
+			<div style={ { color: 'var(--wpds-color-fg-content-neutral)' } }>
+				Code is poetry.{ ' ' }
+				<span
+					style={ {
+						display: 'inline-block',
+						padding: '0.25rem',
+						borderRadius: '0.25rem',
+						backgroundColor:
+							'var(--wpds-color-bg-interactive-brand-strong)',
+						color: 'var(--wpds-color-fg-interactive-brand-strong)',
+					} }
+				>
+					primary
+				</span>
+			</div>
+		),
+	},
+};

package/src/style.module.css

@@ -0,0 +1,3 @@
+.root {
+	display: contents;
+}

package/src/theme-provider.tsx

@@ -0,0 +1,87 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useId } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ThemeContext } from './context';
+import { useThemeProviderStyles } from './use-theme-provider-styles';
+import { type ThemeProviderProps } from './types';
+import styles from './style.module.css';
+
+function cssObjectToText( values: CSSProperties ) {
+	return Object.entries( values )
+		.map( ( [ key, value ] ) => `${ key }: ${ value };` )
+		.join( '' );
+}
+
+function generateCSSSelector( {
+	instanceId,
+	isRoot,
+}: {
+	instanceId: string;
+	isRoot: boolean;
+} ) {
+	const rootSel = `[data-wpds-root-provider="true"]`;
+	const instanceIdSel = `[data-wpds-theme-provider-id="${ instanceId }"]`;
+
+	const selectors = [];
+
+	if ( isRoot ) {
+		selectors.push(
+			`:root:has(.${ styles.root }${ rootSel }${ instanceIdSel })`
+		);
+	}
+
+	selectors.push( `.${ styles.root }.${ styles.root }${ instanceIdSel }` );
+
+	return selectors.join( ',' );
+}
+
+export const ThemeProvider = ( {
+	children,
+	color = {},
+	isRoot = false,
+}: ThemeProviderProps ) => {
+	const instanceId = useId();
+
+	const { themeProviderStyles, resolvedSettings } = useThemeProviderStyles( {
+		color,
+	} );
+
+	const contextValue = useMemo(
+		() => ( {
+			resolvedSettings,
+		} ),
+		[ resolvedSettings ]
+	);
+
+	return (
+		<>
+			{ themeProviderStyles ? (
+				<style>
+					{ `${ generateCSSSelector( {
+						instanceId,
+						isRoot,
+					} ) } {${ cssObjectToText( themeProviderStyles ) }}` }
+				</style>
+			) : null }
+			<div
+				data-wpds-theme-provider-id={ instanceId }
+				data-wpds-root-provider={ isRoot }
+				className={ styles.root }
+			>
+				<ThemeContext.Provider value={ contextValue }>
+					{ children }
+				</ThemeContext.Provider>
+			</div>
+		</>
+	);
+};

package/src/types/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+	const classes: { [ key: string ]: string };
+	export default classes;
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+/**
+ * External dependencies
+ */
+import { type ReactNode } from 'react';
+
+export interface ThemeProviderSettings {
+	/**
+	 * The set of color options to apply to the theme.
+	 */
+	color?: {
+		/**
+		 * The primary seed color to use for the theme.
+		 *
+		 * By default, it inherits from parent `ThemeProvider`,
+		 * and fallbacks to statically built CSS.
+		 */
+		primary?: string;
+		/**
+		 * The background seed color to use for the theme.
+		 *
+		 * By default, it inherits from parent `ThemeProvider`,
+		 * and fallbacks to statically built CSS.
+		 */
+		bg?: string;
+	};
+}
+
+export interface ThemeProviderProps extends ThemeProviderSettings {
+	/**
+	 * The children to render.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * When a ThemeProvider is the root provider, it will apply its theming
+	 * settings also to the root document element (e.g. the html element).
+	 * This is useful, for example, to make sure that the `html` element can
+	 * consume the right background color, or that overlays rendered inside a
+	 * portal can inherit the correct color scheme.
+	 *
+	 * @default false
+	 */
+	isRoot?: boolean;
+}