@wordpress/global-styles-ui 1.1.0

package/src/README.md

@@ -0,0 +1,99 @@
+# Global Styles UI
+
+React component for editing global styles with a familiar interface inspired by WordPress Gutenberg.
+
+## Public API
+
+### GlobalStylesUI
+
+The main component for rendering a global styles editing interface.
+
+```typescript
+import { GlobalStylesUI } from '@wordpress/global-styles-ui';
+
+<GlobalStylesUI
+  value={userGlobalStyles}
+  inheritedValue={mergedGlobalStyles}
+  onChange={setGlobalStyles}
+  path="/colors"
+  onPathChange={setPath}
+  onReset={() => resetStyles()}
+  onExportCSS={() => exportCSS()}
+  fontLibraryEnabled={true}
+  serverCSS={serverCSS}
+  serverSettings={serverSettings}
+/>
+```
+
+#### Props
+
+-   **`value`** (`GlobalStylesConfig`): The user global styles object (what gets edited)
+-   **`inheritedValue`** (`GlobalStylesConfig`): The merged global styles object (base + user, for display/inheritance)
+-   **`onChange`** (`(newValue: GlobalStylesConfig) => void`): Callback when styles change
+-   **`path`** (`string`, optional): Current navigation path (e.g., "/colors", "/typography")
+-   **`onPathChange`** (`(newPath: string) => void`, optional): Callback when navigation changes
+-   **`onReset`** (`() => void`, optional): Callback for reset action
+-   **`onExportCSS`** (`() => void`, optional): Callback for CSS export action
+-   **`fontLibraryEnabled`** (`boolean`, optional): Whether font library is enabled (default: false)
+-   **`serverCSS`** (`{ isGlobalStyles?: boolean }[]`, optional): Server CSS styles for BlockEditorProvider
+-   **`serverSettings`** (`{ __unstableResolvedAssets: Record<string, unknown> }`, optional): Server settings for BlockEditorProvider
+
+## Dependencies
+
+This component has the following external dependencies:
+
+### WordPress Dependencies
+
+-   **`@wordpress/core-data`** - Used internally for fetching:
+
+    -   Style variations (`useEntityRecords('root', 'globalStyles')`)
+    -   Font collections and families (`useEntityRecords('postType', 'wp_font_family')`)
+    -   User capabilities (`useSelect(select => select('core').canUser(...))`)
+
+-   **`@wordpress/components`** - UI components (Navigator, Button, Panel, etc.)
+-   **`@wordpress/blocks`** - Block type information and supports
+-   **`@wordpress/element`** - React utilities
+-   **`@wordpress/i18n`** - Internationalization
+
+### Internal Dependencies
+
+-   **`../global-styles-engine`** - Generic global styles utilities (framework-agnostic)
+
+## Architecture
+
+### Internal Structure
+
+The component is internally generic and framework-agnostic, with WordPress dependencies only used for:
+
+1. **Data Fetching**: Font collections, style variations, and user capabilities
+2. **UI Components**: WordPress design system components
+3. **Block Information**: Block type support detection
+
+### Data Flow
+
+1. Parent provides `value` (global styles) and `onChange` callback
+2. Component uses WordPress stores for additional data (fonts, variations, capabilities)
+3. Internal context manages state and provides hooks to child components
+4. Changes flow back through `onChange` callback
+
+## Usage Example
+
+```typescript
+function MyStylesPage() {
+  const [globalStyles, setGlobalStyles] = useState(initialStyles);
+  const [currentPath, setCurrentPath] = useState('/');
+
+  return (
+    <GlobalStylesUI
+      value={globalStyles}
+      onChange={setGlobalStyles}
+      path={currentPath}
+      onPathChange={setCurrentPath}
+      onReset={() => setGlobalStyles(defaultStyles)}
+      onExportCSS={() => downloadCSS(globalStyles)}
+    />
+  );
+}
+```
+
+This component provides a complete global styles editing experience while maintaining a clean, controlled API.

package/src/background-panel.tsx

@@ -0,0 +1,56 @@
+/**
+ * WordPress dependencies
+ */
+// @ts-expect-error: Not typed yet.
+import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { useStyle, useSetting } from './hooks';
+import { unlock } from './lock-unlock';
+
+// Initial control values where no block style is set.
+const BACKGROUND_DEFAULT_VALUES = {
+	backgroundSize: 'auto',
+};
+
+const { BackgroundPanel: StylesBackgroundPanel } = unlock(
+	blockEditorPrivateApis
+);
+
+/**
+ * Checks if there is a current value in the background image block support
+ * attributes.
+ *
+ * @param style Style attribute.
+ * @return Whether the block has a background image value set.
+ */
+export function hasBackgroundImageValue( style: any ): boolean {
+	return (
+		!! style?.background?.backgroundImage?.id ||
+		!! style?.background?.backgroundImage?.url ||
+		typeof style?.background?.backgroundImage === 'string'
+	);
+}
+
+export default function BackgroundPanel() {
+	const [ style ] = useStyle( '', undefined, 'user', false );
+	const [ inheritedStyle, setStyle ] = useStyle(
+		'',
+		undefined,
+		'merged',
+		false
+	);
+	const [ settings ] = useSetting( '' );
+
+	return (
+		<StylesBackgroundPanel
+			inheritedValue={ inheritedStyle }
+			value={ style }
+			onChange={ setStyle }
+			settings={ settings }
+			defaultValues={ BACKGROUND_DEFAULT_VALUES }
+		/>
+	);
+}

package/src/block-preview-panel.tsx

@@ -0,0 +1,91 @@
+/**
+ * WordPress dependencies
+ */
+// @ts-expect-error: Not typed yet.
+import { BlockPreview } from '@wordpress/block-editor';
+// @ts-expect-error: Not typed yet.
+import { getBlockType, getBlockFromExample } from '@wordpress/blocks';
+import { __experimentalSpacer as Spacer } from '@wordpress/components';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { getVariationClassName } from './utils';
+
+interface BlockPreviewPanelProps {
+	name: string;
+	variation?: string;
+}
+
+const BlockPreviewPanel = ( {
+	name,
+	variation = '',
+}: BlockPreviewPanelProps ) => {
+	const blockExample = getBlockType( name )?.example;
+	const blocks = useMemo( () => {
+		if ( ! blockExample ) {
+			return null;
+		}
+
+		const example = {
+			...blockExample,
+			attributes: {
+				...blockExample.attributes,
+				style: undefined,
+				className: variation
+					? getVariationClassName( variation )
+					: blockExample.attributes?.className,
+			},
+		};
+
+		return getBlockFromExample( name, example );
+	}, [ name, blockExample, variation ] );
+
+	const viewportWidth = blockExample?.viewportWidth ?? 500;
+	// Same as height of InserterPreviewPanel.
+	const previewHeight = 144;
+	const sidebarWidth = 235;
+	const scale = sidebarWidth / viewportWidth;
+	const minHeight =
+		scale !== 0 && scale < 1 && previewHeight
+			? previewHeight / scale
+			: previewHeight;
+
+	if ( ! blockExample ) {
+		return null;
+	}
+
+	return (
+		<Spacer marginX={ 4 } marginBottom={ 4 }>
+			<div
+				className="global-styles-ui__block-preview-panel"
+				style={ { maxHeight: previewHeight, boxSizing: 'initial' } }
+			>
+				<BlockPreview
+					blocks={ blocks }
+					viewportWidth={ viewportWidth }
+					minHeight={ previewHeight }
+					additionalStyles={
+						//We want this CSS to be in sync with the one in InserterPreviewPanel.
+						[
+							{
+								css: `
+								body{
+									padding: 24px;
+									min-height:${ Math.round( minHeight ) }px;
+									display:flex;
+									align-items:center;
+								}
+								.is-root-container { width: 100%; }
+							`,
+							},
+						]
+					}
+				/>
+			</div>
+		</Spacer>
+	);
+};
+
+export default BlockPreviewPanel;

package/src/color-indicator-wrapper.tsx

@@ -0,0 +1,34 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { Flex } from '@wordpress/components';
+
+interface ColorIndicatorWrapperProps {
+	className?: string;
+	[ key: string ]: any;
+}
+
+function ColorIndicatorWrapper( {
+	className,
+	children,
+	...props
+}: ColorIndicatorWrapperProps ) {
+	return (
+		<Flex
+			className={ clsx(
+				'global-styles-ui__color-indicator-wrapper',
+				className
+			) }
+			{ ...props }
+		>
+			{ children }
+		</Flex>
+	);
+}
+
+export default ColorIndicatorWrapper;

package/src/color-palette-panel.tsx

@@ -0,0 +1,111 @@
+/**
+ * WordPress dependencies
+ */
+import type { Color } from '@wordpress/global-styles-engine';
+import { useViewportMatch } from '@wordpress/compose';
+import {
+	__experimentalPaletteEdit as PaletteEdit,
+	__experimentalVStack as VStack,
+	Button,
+} from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { shuffle } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { useSetting, useColorRandomizer } from './hooks';
+import ColorVariations from './variations/variations-color';
+
+const mobilePopoverProps = { placement: 'bottom-start' as const, offset: 8 };
+
+interface ColorPalettePanelProps {
+	name?: string;
+}
+
+export default function ColorPalettePanel( { name }: ColorPalettePanelProps ) {
+	const [ themeColors, setThemeColors ] = useSetting< Color[] >(
+		'color.palette.theme',
+		name
+	);
+	const [ baseThemeColors ] = useSetting< Color[] >(
+		'color.palette.theme',
+		name,
+		'base'
+	);
+	const [ defaultColors, setDefaultColors ] = useSetting< Color[] >(
+		'color.palette.default',
+		name
+	);
+	const [ baseDefaultColors ] = useSetting< Color[] >(
+		'color.palette.default',
+		name,
+		'base'
+	);
+	const [ customColors, setCustomColors ] = useSetting< Color[] >(
+		'color.palette.custom',
+		name
+	);
+
+	const [ defaultPaletteEnabled ] = useSetting< boolean >(
+		'color.defaultPalette',
+		name
+	);
+
+	const isMobileViewport = useViewportMatch( 'small', '<' );
+	const popoverProps = isMobileViewport ? mobilePopoverProps : undefined;
+
+	const [ randomizeThemeColors ] = useColorRandomizer( name );
+
+	return (
+		<VStack className="global-styles-ui-color-palette-panel" spacing={ 8 }>
+			<VStack spacing={ 4 }>
+				{ !! themeColors && !! themeColors.length && (
+					<PaletteEdit
+						canReset={ themeColors !== baseThemeColors }
+						canOnlyChangeValues
+						colors={ themeColors }
+						onChange={ setThemeColors }
+						paletteLabel={ __( 'Theme' ) }
+						paletteLabelHeadingLevel={ 3 }
+						popoverProps={ popoverProps }
+					/>
+				) }
+				{ ( window as any ).__experimentalEnableColorRandomizer &&
+					themeColors?.length > 0 &&
+					randomizeThemeColors && (
+						<Button
+							__next40pxDefaultSize
+							variant="secondary"
+							icon={ shuffle }
+							onClick={ randomizeThemeColors }
+						>
+							{ __( 'Randomize colors' ) }
+						</Button>
+					) }
+			</VStack>
+			{ !! defaultColors &&
+				!! defaultColors.length &&
+				!! defaultPaletteEnabled && (
+					<PaletteEdit
+						canReset={ defaultColors !== baseDefaultColors }
+						canOnlyChangeValues
+						colors={ defaultColors }
+						onChange={ setDefaultColors }
+						paletteLabel={ __( 'Default' ) }
+						paletteLabelHeadingLevel={ 3 }
+						popoverProps={ popoverProps }
+					/>
+				) }
+			<PaletteEdit
+				colors={ customColors }
+				onChange={ setCustomColors }
+				paletteLabel={ __( 'Custom' ) }
+				paletteLabelHeadingLevel={ 3 }
+				slugPrefix="custom-"
+				popoverProps={ popoverProps }
+			/>
+			<ColorVariations title={ __( 'Palettes' ) } />
+		</VStack>
+	);
+}

package/src/color-preview.tsx

@@ -0,0 +1,78 @@
+/**
+ * WordPress dependencies
+ */
+import { __experimentalHStack as HStack } from '@wordpress/components';
+import { useContext } from '@wordpress/element';
+import { getStyle } from '@wordpress/global-styles-engine';
+import type { Color } from '@wordpress/global-styles-engine';
+
+/**
+ * Internal dependencies
+ */
+import { GlobalStylesContext } from './context';
+
+export function ColorPreview() {
+	const { merged } = useContext( GlobalStylesContext );
+
+	// Extract main colors from the global styles
+	const backgroundColor = getStyle( merged, 'color.background' ) || '#ffffff';
+	const textColor = getStyle( merged, 'color.text' ) || '#000000';
+
+	// Get color palette - handle both array and object formats
+	const palette = merged?.settings?.color?.palette;
+	let paletteColors: Color[] = [];
+
+	if ( Array.isArray( palette ) ) {
+		paletteColors = palette;
+	} else if ( palette && typeof palette === 'object' ) {
+		paletteColors = palette.theme || palette.custom || [];
+	}
+
+	// Get first few colors from palette for preview
+	const previewColors = paletteColors.slice( 0, 4 );
+
+	return (
+		<HStack
+			spacing={ 0 }
+			justify="center"
+			style={ {
+				height: '100%',
+				overflow: 'hidden',
+				minHeight: '40px',
+			} }
+		>
+			{ /* Background color swatch */ }
+			<div
+				style={ {
+					backgroundColor,
+					width: '25%',
+					height: '100%',
+					minHeight: '40px',
+				} }
+			/>
+			{ /* Text color swatch */ }
+			<div
+				style={ {
+					backgroundColor: textColor,
+					width: '25%',
+					height: '100%',
+					minHeight: '40px',
+				} }
+			/>
+			{ /* Palette colors */ }
+			{ previewColors
+				.slice( 0, 2 )
+				.map( ( color: Color, index: number ) => (
+					<div
+						key={ index }
+						style={ {
+							backgroundColor: color.color,
+							width: '25%',
+							height: '100%',
+							minHeight: '40px',
+						} }
+					/>
+				) ) }
+		</HStack>
+	);
+}

package/src/color-variations.tsx

@@ -0,0 +1,35 @@
+/**
+ * WordPress dependencies
+ */
+import type { GlobalStylesConfig } from '@wordpress/global-styles-engine';
+
+/**
+ * Internal dependencies
+ */
+import ColorVariationsInternal from './variations/variations-color';
+import { withGlobalStylesProvider } from './with-global-styles-provider';
+
+export interface ColorVariationsProps {
+	value: GlobalStylesConfig;
+	baseValue: GlobalStylesConfig;
+	onChange: ( config: GlobalStylesConfig ) => void;
+	title?: string;
+	gap?: number;
+}
+
+/**
+ * Render Global Styles Color Variations.
+ *
+ * @example
+ * ```tsx
+ * <ColorVariations
+ *   value={userConfig}
+ *   baseValue={baseConfig}
+ *   onChange={setUserConfig}
+ *   title="Palettes"
+ *   gap={3}
+ * />
+ * ```
+ */
+export const ColorVariations: React.ComponentType< ColorVariationsProps > =
+	withGlobalStylesProvider( ColorVariationsInternal );

package/src/confirm-reset-shadow-dialog.tsx

@@ -0,0 +1,45 @@
+/**
+ * WordPress dependencies
+ */
+import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+interface ConfirmResetShadowDialogProps {
+	text: string;
+	confirmButtonText: string;
+	isOpen: boolean;
+	toggleOpen: () => void;
+	onConfirm: () => void;
+}
+
+function ConfirmResetShadowDialog( {
+	text,
+	confirmButtonText,
+	isOpen,
+	toggleOpen,
+	onConfirm,
+}: ConfirmResetShadowDialogProps ) {
+	const handleConfirm = async () => {
+		toggleOpen();
+		onConfirm();
+	};
+
+	const handleCancel = () => {
+		toggleOpen();
+	};
+
+	return (
+		<ConfirmDialog
+			isOpen={ isOpen }
+			cancelButtonText={ __( 'Cancel' ) }
+			confirmButtonText={ confirmButtonText }
+			onCancel={ handleCancel }
+			onConfirm={ handleConfirm }
+			size="medium"
+		>
+			{ text }
+		</ConfirmDialog>
+	);
+}
+
+export default ConfirmResetShadowDialog;

package/src/context.ts

@@ -0,0 +1,21 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+import type { GlobalStylesConfig } from '@wordpress/global-styles-engine';
+
+export interface GlobalStylesContextType {
+	user: GlobalStylesConfig;
+	base: GlobalStylesConfig;
+	merged: GlobalStylesConfig;
+	onChange: ( newValue: GlobalStylesConfig ) => void;
+	fontLibraryEnabled?: boolean;
+}
+
+export const GlobalStylesContext = createContext< GlobalStylesContextType >( {
+	user: { styles: {}, settings: {} },
+	base: { styles: {}, settings: {} },
+	merged: { styles: {}, settings: {} },
+	onChange: () => {},
+	fontLibraryEnabled: false,
+} );

package/src/dimensions-panel.tsx

@@ -0,0 +1,85 @@
+/**
+ * WordPress dependencies
+ */
+// @ts-expect-error: Not typed yet.
+import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useStyle, useSetting } from './hooks';
+import { unlock } from './lock-unlock';
+
+const { useSettingsForBlockElement, DimensionsPanel: StylesDimensionsPanel } =
+	unlock( blockEditorPrivateApis );
+
+const DEFAULT_CONTROLS = {
+	contentSize: true,
+	wideSize: true,
+	padding: true,
+	margin: true,
+	blockGap: true,
+	minHeight: true,
+	childLayout: false,
+};
+
+export default function DimensionsPanel() {
+	const [ style ] = useStyle( '', undefined, 'user', false );
+	const [ inheritedStyle, setStyle ] = useStyle(
+		'',
+		undefined,
+		'merged',
+		false
+	);
+	const [ userSettings ] = useSetting( '', undefined, 'user' );
+	const [ rawSettings, setSettings ] = useSetting( '' );
+	const settings = useSettingsForBlockElement( rawSettings );
+
+	// These intermediary objects are needed because the "layout" property is stored
+	// in settings rather than styles.
+	const inheritedStyleWithLayout = useMemo( () => {
+		return {
+			...inheritedStyle,
+			layout: settings.layout,
+		};
+	}, [ inheritedStyle, settings.layout ] );
+
+	const styleWithLayout = useMemo( () => {
+		return {
+			...style,
+			layout: userSettings.layout,
+		};
+	}, [ style, userSettings.layout ] );
+
+	const onChange = ( newStyle: any ) => {
+		const updatedStyle = { ...newStyle };
+		delete updatedStyle.layout;
+		setStyle( updatedStyle );
+
+		if ( newStyle.layout !== userSettings.layout ) {
+			const updatedSettings = {
+				...userSettings,
+				layout: newStyle.layout,
+			};
+
+			// Ensure any changes to layout definitions are not persisted.
+			if ( updatedSettings.layout?.definitions ) {
+				delete updatedSettings.layout.definitions;
+			}
+
+			setSettings( updatedSettings );
+		}
+	};
+
+	return (
+		<StylesDimensionsPanel
+			inheritedValue={ inheritedStyleWithLayout }
+			value={ styleWithLayout }
+			onChange={ onChange }
+			settings={ settings }
+			includeLayoutControls
+			defaultControls={ DEFAULT_CONTROLS }
+		/>
+	);
+}