@wordpress-gcb/fields 0.2.0

package/src/inspector.js

@@ -0,0 +1,174 @@
+/**
+ * Render an Inspector panel tree from a block's `gcb.controls` array.
+ *
+ * Controls are flat in the JSON; structure comes from `parentPanelId` references
+ * to `type: "group"` controls. We bucket controls under their group and emit one
+ * <PanelBody> per group, plus a default panel for anything ungrouped.
+ */
+
+import { PanelBody } from '@wordpress/components';
+import { Fragment, useContext } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { controlComponents } from './controls';
+import { ValidationContext } from './validation-context';
+import {
+	STRUCTURAL_TYPES,
+	shouldRender,
+	panelsContainingErrors,
+} from './conditional-logic';
+
+// Re-export so existing callers keep working (post-fields.js imports
+// shouldRender + panelsContainingErrors from './inspector').
+export { shouldRender, panelsContainingErrors };
+
+/**
+ * @param {Array}    controls
+ * @param {Object}   attributes
+ * @param {Function} setAttributes
+ * @param {Object}   [options]
+ * @param {boolean}  [options.flatten] When true and no groups exist, render
+ *   ungrouped controls flat (no outer "Settings" PanelBody). Used by the
+ *   post-fields meta-box where the meta-box itself IS the panel — nesting
+ *   another PanelBody would look like a redundant dropdown.
+ * @param {Set<string>} [options.forceOpenPanelIds] Panel ids to render
+ *   with initialOpen=true. Used by the meta-box to auto-open any panel
+ *   containing a field that just failed validation, so the user can see
+ *   the offending field.
+ */
+export function renderInspector(controls, attributes, setAttributes, options = {}) {
+	const { groups, ungrouped } = bucketControls(controls);
+	const flatten = options.flatten === true && groups.length === 0;
+	const forceOpen = options.forceOpenPanelIds || new Set();
+
+	return (
+		<Fragment>
+			{ungrouped.length > 0 && (
+				flatten ? (
+					ungrouped.map((control) =>
+						renderControl(control, attributes, setAttributes)
+					)
+				) : (
+					<PanelBody title={__('Settings', 'gcblite')} initialOpen={true}>
+						{ungrouped.map((control) =>
+							renderControl(control, attributes, setAttributes)
+						)}
+					</PanelBody>
+				)
+			)}
+			{groups.map(({ group, children }) => (
+				<PanelBody
+					// Remount the panel when its forced-open status changes so
+					// the new initialOpen value is honoured. (PanelBody only
+					// reads initialOpen on mount.)
+					key={`${group.id}:${forceOpen.has(group.id) ? 'open' : 'closed'}`}
+					title={group.label}
+					initialOpen={forceOpen.has(group.id)}
+				>
+					{children.map((control) =>
+						renderControl(control, attributes, setAttributes)
+					)}
+				</PanelBody>
+			))}
+		</Fragment>
+	);
+}
+
+function bucketControls(controls) {
+	const groupsById = new Map();
+	const groupOrder = [];
+	const ungrouped = [];
+
+	// First pass: register structural controls (group / panel / tools-panel)
+	// in declaration order.
+	controls.forEach((control) => {
+		if (STRUCTURAL_TYPES.has(control.type) && control.id) {
+			groupsById.set(control.id, { group: control, children: [] });
+			groupOrder.push(control.id);
+		}
+	});
+
+	// Second pass: assign each non-structural control to a panel or to ungrouped.
+	controls.forEach((control) => {
+		if (STRUCTURAL_TYPES.has(control.type)) return;
+
+		const parentId = control.parentPanelId;
+		if (parentId && groupsById.has(parentId)) {
+			groupsById.get(parentId).children.push(control);
+		} else {
+			ungrouped.push(control);
+		}
+	});
+
+	return {
+		groups: groupOrder.map((id) => groupsById.get(id)),
+		ungrouped,
+	};
+}
+
+function renderControl(control, attributes, setAttributes) {
+	if (!shouldRender(control, attributes)) {
+		return null;
+	}
+
+	const Component = controlComponents[control.type];
+	if (!Component) {
+		return (
+			<div key={control.id} style={{ padding: 8, background: '#fff3cd', border: '1px solid #ffeeba', marginBottom: 8 }}>
+				<strong>{control.label}</strong>: unknown control type <code>{control.type}</code>
+			</div>
+		);
+	}
+
+	const value = attributes[control.attributeKey];
+	const onChange = (next) => setAttributes({ [control.attributeKey]: next });
+
+	// Wrap each rendered control in a ValidationWrapper that overlays the
+	// required `*`, the inline error message, and the data-attribute used
+	// by the meta-box submit interceptor to scroll-into-view. The wrapper
+	// is invisible in surfaces without validation (sidebar default
+	// ValidationContext is { errors:{}, showErrors:false }) so blocks
+	// don't see any change.
+	return (
+		<ValidationWrapper key={control.id} control={control}>
+			<Component
+				control={control}
+				value={value}
+				onChange={onChange}
+				attributes={attributes}
+			/>
+		</ValidationWrapper>
+	);
+}
+
+/**
+ * Per-field decorator: stamps data-gcblite-field for scroll-to-error,
+ * shows the required asterisk, and surfaces the inline error message
+ * once the host has flipped showErrors on.
+ */
+function ValidationWrapper({ control, children }) {
+	const { errors, showErrors } = useContext(ValidationContext);
+	const key = control.attributeKey;
+	const required = !!control.validation?.required;
+	const errorMessage = showErrors && key ? errors[key] : null;
+
+	if (!required && !errorMessage && !key) {
+		return children;
+	}
+
+	return (
+		<div
+			data-gcblite-field={key || undefined}
+			className={[
+				'gcblite-field',
+				required ? 'gcblite-field--required' : '',
+				errorMessage ? 'gcblite-field--has-error' : '',
+			].filter(Boolean).join(' ')}
+		>
+			{children}
+			{errorMessage && (
+				<p className="gcblite-field__error" role="alert">{errorMessage}</p>
+			)}
+		</div>
+	);
+}
+

package/src/provider.js

@@ -0,0 +1,59 @@
+/**
+ * GcbFieldsProvider — the SDK's injected-config boundary.
+ *
+ * The controls used to read host data off `window.gcbLite` directly. To make the
+ * package plugin-independent, that data is now provided via this context:
+ *
+ *   <GcbFieldsProvider value={{ tokens, googleMapsEnabled, media, apiFetch }}>
+ *     ...controls / inspector...
+ *   </GcbFieldsProvider>
+ *
+ * Every field is optional. To keep the *existing plugin* working unchanged when
+ * it adopts the SDK (and to support drop-in headless use), each accessor falls
+ * back to the legacy `window.gcbLite` global when the context doesn't supply a
+ * value. So:
+ *   - plugin (provides nothing yet) → falls back to window.gcbLite, works as before;
+ *   - headless host → wraps the tree in the provider and injects its own values.
+ *
+ * config shape:
+ *   tokens            object  design-token tree (was window.gcbLite.tokens)
+ *   googleMapsEnabled boolean gate for the google-map control (was .googleMaps.hasApiKey)
+ *   media             object  optional media-picker adapter (else block-editor/wp.media)
+ *   apiFetch          fn      optional REST fetcher for reference controls (else @wordpress/api-fetch)
+ */
+
+import { createContext, useContext } from '@wordpress/element';
+
+export const GcbFieldsContext = createContext(null);
+
+export function GcbFieldsProvider({ value, children }) {
+	return (
+		<GcbFieldsContext.Provider value={value || {}}>
+			{children}
+		</GcbFieldsContext.Provider>
+	);
+}
+
+/** Legacy global fallback so the plugin keeps working before it injects config. */
+function legacyGlobal() {
+	return (typeof window !== 'undefined' && window.gcbLite) || {};
+}
+
+/** Full resolved config (context first, window.gcbLite fallback). */
+export function useGcbFieldsConfig() {
+	return useContext(GcbFieldsContext) || {};
+}
+
+/** Design-token tree. */
+export function useTokensConfig() {
+	const cfg = useContext(GcbFieldsContext) || {};
+	if (cfg.tokens !== undefined) return cfg.tokens || {};
+	return legacyGlobal().tokens || {};
+}
+
+/** Whether the google-map control should enable Maps features. */
+export function useGoogleMapsEnabled() {
+	const cfg = useContext(GcbFieldsContext) || {};
+	if (cfg.googleMapsEnabled !== undefined) return !!cfg.googleMapsEnabled;
+	return !!legacyGlobal().googleMaps?.hasApiKey;
+}

package/src/utils/map-utils.js

@@ -0,0 +1,51 @@
+/**
+ * Map utilities for fields that translate user-friendly keys to backend tokens.
+ *
+ *   simple:  { sm: 'spacing-sm', md: 'spacing-md' }
+ *   labelled:{ sm: { label: 'Small (16px)', token: 'spacing-sm' } }
+ */
+
+export const parseMap = (map) => {
+	if (!map || typeof map !== 'object') return null;
+	const out = {};
+	Object.entries(map).forEach(([key, value]) => {
+		if (typeof value === 'string') {
+			out[key] = { label: key, token: value };
+		} else if (typeof value === 'object' && value.token) {
+			out[key] = { label: value.label || key, token: value.token };
+		}
+	});
+	return Object.keys(out).length > 0 ? out : null;
+};
+
+export const getTokenFromKey = (m, key) => (m && key ? m[key]?.token || null : null);
+
+export const getKeyFromToken = (m, token) => {
+	if (!m || !token) return null;
+	const entry = Object.entries(m).find(([, v]) => v.token === token);
+	return entry ? entry[0] : null;
+};
+
+export const mapToOptions = (m) => {
+	if (!m) return [];
+	return Object.entries(m).map(([key, v]) => ({ label: v.label, value: key }));
+};
+
+export const getMapKeys = (m) => {
+	if (!m) return [];
+	return Object.keys(m)
+		.map((k) => Number(k))
+		.filter((k) => !Number.isNaN(k))
+		.sort((a, b) => a - b);
+};
+
+export const mapToRangeMarks = (m) => {
+	if (!m) return null;
+	return Object.entries(m).map(([key, v]) => ({ value: Number(key), label: v.label }));
+};
+
+export const isValidMapValue = (m, value) => {
+	if (!m || value === null || value === undefined) return false;
+	if (m[value]) return true;
+	return Object.values(m).some((e) => e.token === value);
+};

package/src/utils/token-helper.js

@@ -0,0 +1,243 @@
+/**
+ * Token helpers — ported from the original GCB.
+ *
+ * Two layers of tokens:
+ *   - Built-in groups (this file): hard-coded design system tokens that ship
+ *     with the plugin. Useful as a fallback when a theme has no theme.json.
+ *   - Theme groups (window.gcbLite.tokens): parsed from theme.json by PHP.
+ *     Always merged in by getTokenGroupTokens() below — theme tokens win on
+ *     a path collision.
+ *
+ * Token path syntax: "category:subKey" or "category:subKey:tokenKey".
+ *   "spacing:scale"   — the group of tokens
+ *   "spacing:scale:30" — a specific token
+ */
+
+const builtInTokenGroups = {
+	color: {
+		label: 'Color',
+		children: {
+			palette: {
+				label: 'Palette',
+				tokens: [
+					{ key: 'primary',   value: 'color-primary',   label: 'Primary' },
+					{ key: 'secondary', value: 'color-secondary', label: 'Secondary' },
+					{ key: 'accent',    value: 'color-accent',    label: 'Accent' },
+					{ key: 'neutral',   value: 'color-neutral',   label: 'Neutral' },
+					{ key: 'dark',      value: 'color-dark',      label: 'Dark' },
+					{ key: 'light',     value: 'color-light',     label: 'Light' },
+				],
+			},
+			duotone: {
+				label: 'Duotone',
+				tokens: [
+					{ key: 'blue',   value: 'duotone-blue',   label: 'Blue Duotone' },
+					{ key: 'purple', value: 'duotone-purple', label: 'Purple Duotone' },
+					{ key: 'green',  value: 'duotone-green',  label: 'Green Duotone' },
+				],
+			},
+		},
+	},
+	spacing: {
+		label: 'Spacing',
+		children: {
+			scale: {
+				label: 'Scale',
+				tokens: [
+					{ key: '0',  value: 'spacing-none', label: 'None (0)',          size: '0' },
+					{ key: '10', value: 'spacing-10',   label: 'Step 1 (0.25rem)', size: '0.25rem' },
+					{ key: '20', value: 'spacing-20',   label: 'Step 2 (0.5rem)',  size: '0.5rem' },
+					{ key: '30', value: 'spacing-30',   label: 'Step 3 (1rem)',    size: '1rem' },
+					{ key: '40', value: 'spacing-40',   label: 'Step 4 (1.5rem)',  size: '1.5rem' },
+					{ key: '50', value: 'spacing-50',   label: 'Step 5 (2rem)',    size: '2rem' },
+					{ key: '60', value: 'spacing-60',   label: 'Step 6 (3rem)',    size: '3rem' },
+					{ key: '70', value: 'spacing-70',   label: 'Step 7 (4rem)',    size: '4rem' },
+					{ key: '80', value: 'spacing-80',   label: 'Step 8 (6rem)',    size: '6rem' },
+				],
+			},
+			presets: {
+				label: 'Presets',
+				tokens: [
+					{ key: 'xs',  value: 'spacing-xs',  label: 'Extra Small (0.5rem)', size: '0.5rem' },
+					{ key: 'sm',  value: 'spacing-sm',  label: 'Small (1rem)',         size: '1rem' },
+					{ key: 'md',  value: 'spacing-md',  label: 'Medium (1.5rem)',      size: '1.5rem' },
+					{ key: 'lg',  value: 'spacing-lg',  label: 'Large (2rem)',         size: '2rem' },
+					{ key: 'xl',  value: 'spacing-xl',  label: 'Extra Large (3rem)',   size: '3rem' },
+					{ key: '2xl', value: 'spacing-2xl', label: '2X Large (4rem)',      size: '4rem' },
+					{ key: '3xl', value: 'spacing-3xl', label: '3X Large (6rem)',      size: '6rem' },
+				],
+			},
+			semantic: {
+				label: 'Semantic',
+				tokens: [
+					{ key: 'content',   value: 'spacing-content',   label: 'Content',   size: 'var(--wp--style--block-gap, 1.5rem)' },
+					{ key: 'section',   value: 'spacing-section',   label: 'Section',   size: 'clamp(2rem, 5vw, 4rem)' },
+					{ key: 'container', value: 'spacing-container', label: 'Container', size: 'clamp(1rem, 3vw, 2rem)' },
+				],
+			},
+		},
+	},
+	typography: {
+		label: 'Typography',
+		children: {
+			fontSize: {
+				label: 'Font Sizes',
+				tokens: [
+					{ key: 'xs',   value: 'text-xs',   label: 'Extra Small (12px)' },
+					{ key: 'sm',   value: 'text-sm',   label: 'Small (14px)' },
+					{ key: 'base', value: 'text-base', label: 'Base (16px)' },
+					{ key: 'lg',   value: 'text-lg',   label: 'Large (18px)' },
+					{ key: 'xl',   value: 'text-xl',   label: 'Extra Large (20px)' },
+					{ key: '2xl',  value: 'text-2xl',  label: '2X Large (24px)' },
+				],
+			},
+			fontWeight: {
+				label: 'Font Weights',
+				tokens: [
+					{ key: 'light',    value: 'font-light',    label: 'Light (300)' },
+					{ key: 'normal',   value: 'font-normal',   label: 'Normal (400)' },
+					{ key: 'medium',   value: 'font-medium',   label: 'Medium (500)' },
+					{ key: 'semibold', value: 'font-semibold', label: 'Semibold (600)' },
+					{ key: 'bold',     value: 'font-bold',     label: 'Bold (700)' },
+				],
+			},
+		},
+	},
+	sizing: {
+		label: 'Sizing',
+		children: {
+			containers: {
+				label: 'Container Widths',
+				tokens: [
+					{ key: 'narrow', value: 'container-narrow', label: 'Narrow (600px)' },
+					{ key: 'normal', value: 'container-normal', label: 'Normal (1200px)' },
+					{ key: 'wide',   value: 'container-wide',   label: 'Wide (1600px)' },
+					{ key: 'full',   value: 'container-full',   label: 'Full Width' },
+				],
+			},
+			borderRadius: {
+				label: 'Border Radius',
+				tokens: [
+					{ key: 'none', value: 'radius-none', label: 'None' },
+					{ key: 'sm',   value: 'radius-sm',   label: 'Small' },
+					{ key: 'md',   value: 'radius-md',   label: 'Medium' },
+					{ key: 'lg',   value: 'radius-lg',   label: 'Large' },
+					{ key: 'full', value: 'radius-full', label: 'Full (Pill)' },
+				],
+			},
+		},
+	},
+};
+
+/**
+ * Get all token groups, merging built-ins with theme.json tokens.
+ * Theme tokens override built-ins on a path collision.
+ *
+ * @param {object} [themeTokens] Theme token tree. Defaults to the legacy
+ *   `window.gcbLite.tokens` global so non-React callers (and the unmigrated
+ *   plugin) keep working; the SDK's useTokens() hook passes the value from
+ *   GcbFieldsProvider instead.
+ */
+export function getAllTokenGroups(themeTokens) {
+	if (themeTokens === undefined) {
+		themeTokens = (typeof window !== 'undefined' && window.gcbLite?.tokens) || {};
+	}
+	const merged = { ...builtInTokenGroups };
+
+	Object.keys(themeTokens).forEach((category) => {
+		if (merged[category]) {
+			merged[category] = {
+				...merged[category],
+				children: {
+					...(merged[category].children || {}),
+					...(themeTokens[category].children || {}),
+				},
+			};
+		} else {
+			merged[category] = themeTokens[category];
+		}
+	});
+
+	return merged;
+}
+
+/**
+ * Resolve a token group path to its token list.
+ *
+ * @param {string} tokenGroup  e.g. "spacing:scale", "custom:gap"
+ * @returns {Array|null}
+ */
+export function getTokenGroupTokens(tokenGroup) {
+	if (!tokenGroup || typeof tokenGroup !== 'string') return null;
+	const [categoryKey, subKey] = tokenGroup.split(':');
+	if (!categoryKey || !subKey) return null;
+
+	const all = getAllTokenGroups();
+	const category = all[categoryKey];
+	if (!category?.children) return null;
+
+	return category.children[subKey]?.tokens || null;
+}
+
+/**
+ * Convert a token list to {label, value} options for a select/radio control.
+ */
+export function tokensToOptions(tokens) {
+	if (!Array.isArray(tokens)) return [];
+	return tokens.map((t) => ({ label: t.label, value: t.key }));
+}
+
+/**
+ * For spacing tokens: resolve the raw size value (e.g. "1rem").
+ * Accepts a full path ("spacing:scale:30"), a partial ("scale:30"),
+ * or just a key ("30") — searches in priority order.
+ */
+export function getSpacingSize(tokenKey) {
+	if (!tokenKey) return null;
+	const parts = tokenKey.split(':');
+	let categoryKey, subKey, key;
+
+	if (parts.length === 3) {
+		[categoryKey, subKey, key] = parts;
+	} else if (parts.length === 2) {
+		categoryKey = 'spacing';
+		[subKey, key] = parts;
+	} else {
+		// Bare key — search every spacing subcategory.
+		const spacing = getAllTokenGroups().spacing;
+		if (spacing?.children) {
+			for (const subCat of Object.values(spacing.children)) {
+				const t = subCat.tokens?.find((tok) => tok.key === tokenKey);
+				if (t?.size) return t.size;
+				if (t?.value) return t.value; // theme.json tokens use `value`
+			}
+		}
+		return null;
+	}
+
+	const cat = getAllTokenGroups()[categoryKey];
+	const tok = cat?.children?.[subKey]?.tokens?.find((t) => t.key === key);
+	return tok?.size || tok?.value || null;
+}
+
+/**
+ * Convert a spacing token to the WP CSS custom property.
+ * Falls back to var(--wp--preset--spacing--{key}) for unknown tokens.
+ */
+export function spacingTokenToCSSVar(tokenKey) {
+	if (!tokenKey) return null;
+	const parts = tokenKey.split(':');
+	const key = parts.length > 1 ? parts[parts.length - 1] : tokenKey;
+	return `var(--wp--preset--spacing--${key})`;
+}
+
+/**
+ * Resolve a token to its cssVar, preferring an explicit cssVar property
+ * (theme.json tokens have one), falling back to the spacing convention.
+ */
+export function tokenToCSSVar(token) {
+	if (!token) return null;
+	if (token.cssVar) return token.cssVar;
+	if (token.slug) return `var(--wp--preset--spacing--${token.slug})`;
+	return null;
+}

package/src/validation-context.js

@@ -0,0 +1,19 @@
+/**
+ * Tells each rendered control whether its value is currently invalid, so it
+ * can show inline error UI without each control type knowing how the host
+ * tracks validation state.
+ *
+ * Provided by the meta-box App (and, in future, the block Inspector) at the
+ * tree root. Controls read it via useContext(ValidationContext).
+ *
+ * Default value is { errors: {}, showErrors: false } — i.e. the sidebar
+ * Inspector, which doesn't yet drive validation, gets a no-op context
+ * so the same controls render fine in both surfaces.
+ */
+
+import { createContext } from '@wordpress/element';
+
+export const ValidationContext = createContext({
+	errors: {},        // { attributeKey: 'human message' }
+	showErrors: false, // becomes true after the first failed save attempt
+});