@wordpress-gcb/fields 0.2.1 → 0.2.3

package/{src → dist}/index.js

@@ -16,13 +16,7 @@
  */
 
 // Injected-config boundary.
-export {
-	GcbFieldsProvider,
-	GcbFieldsContext,
-	useGcbFieldsConfig,
-	useTokensConfig,
-	useGoogleMapsEnabled,
-} from './provider';
+export { GcbFieldsProvider, GcbFieldsContext, useGcbFieldsConfig, useTokensConfig, useGoogleMapsEnabled } from './provider';
 
 // Inspector renderer + the control registry.
 export { renderInspector } from './inspector';
@@ -35,4 +29,4 @@ export { ControlContext } from './control-context';
 
 // Token helpers (for custom token-aware UI outside the standard controls).
 export { useTokens, getTokensByGroup, generateMapFromTokens } from './hooks/useTokens';
-export { getAllTokenGroups } from './utils/token-helper';
+export { getAllTokenGroups } from './utils/token-helper';

package/dist/inspector.js

@@ -0,0 +1,163 @@
+/**
+ * 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').
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 /*#__PURE__*/_jsxs(Fragment, {
+    children: [ungrouped.length > 0 && (flatten ? ungrouped.map(control => renderControl(control, attributes, setAttributes)) : /*#__PURE__*/_jsx(PanelBody, {
+      title: __('Settings', 'gcblite'),
+      initialOpen: true,
+      children: ungrouped.map(control => renderControl(control, attributes, setAttributes))
+    })), groups.map(({
+      group,
+      children
+    }) => /*#__PURE__*/_jsx(PanelBody
+    // Remount the panel when its forced-open status changes so
+    // the new initialOpen value is honoured. (PanelBody only
+    // reads initialOpen on mount.)
+    , {
+      title: group.label,
+      initialOpen: forceOpen.has(group.id),
+      children: children.map(control => renderControl(control, attributes, setAttributes))
+    }, `${group.id}:${forceOpen.has(group.id) ? 'open' : 'closed'}`))]
+  });
+}
+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 /*#__PURE__*/_jsxs("div", {
+      style: {
+        padding: 8,
+        background: '#fff3cd',
+        border: '1px solid #ffeeba',
+        marginBottom: 8
+      },
+      children: [/*#__PURE__*/_jsx("strong", {
+        children: control.label
+      }), ": unknown control type ", /*#__PURE__*/_jsx("code", {
+        children: control.type
+      })]
+    }, control.id);
+  }
+  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 /*#__PURE__*/_jsx(ValidationWrapper, {
+    control: control,
+    children: /*#__PURE__*/_jsx(Component, {
+      control: control,
+      value: value,
+      onChange: onChange,
+      attributes: attributes
+    })
+  }, control.id);
+}
+
+/**
+ * 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 /*#__PURE__*/_jsxs("div", {
+    "data-gcblite-field": key || undefined,
+    className: ['gcblite-field', required ? 'gcblite-field--required' : '', errorMessage ? 'gcblite-field--has-error' : ''].filter(Boolean).join(' '),
+    children: [children, errorMessage && /*#__PURE__*/_jsx("p", {
+      className: "gcblite-field__error",
+      role: "alert",
+      children: errorMessage
+    })]
+  });
+}

package/{src → dist}/provider.js

@@ -23,37 +23,38 @@
  */
 
 import { createContext, useContext } from '@wordpress/element';
-
+import { jsx as _jsx } from "react/jsx-runtime";
 export const GcbFieldsContext = createContext(null);
-
-export function GcbFieldsProvider({ value, children }) {
-	return (
-		<GcbFieldsContext.Provider value={value || {}}>
-			{children}
-		</GcbFieldsContext.Provider>
-	);
+export function GcbFieldsProvider({
+  value,
+  children
+}) {
+  return /*#__PURE__*/_jsx(GcbFieldsContext.Provider, {
+    value: value || {},
+    children: children
+  });
 }
 
 /** Legacy global fallback so the plugin keeps working before it injects config. */
 function legacyGlobal() {
-	return (typeof window !== 'undefined' && window.gcbLite) || {};
+  return typeof window !== 'undefined' && window.gcbLite || {};
 }
 
 /** Full resolved config (context first, window.gcbLite fallback). */
 export function useGcbFieldsConfig() {
-	return useContext(GcbFieldsContext) || {};
+  return useContext(GcbFieldsContext) || {};
 }
 
 /** Design-token tree. */
 export function useTokensConfig() {
-	const cfg = useContext(GcbFieldsContext) || {};
-	if (cfg.tokens !== undefined) return cfg.tokens || {};
-	return legacyGlobal().tokens || {};
+  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;
-}
+  const cfg = useContext(GcbFieldsContext) || {};
+  if (cfg.googleMapsEnabled !== undefined) return !!cfg.googleMapsEnabled;
+  return !!legacyGlobal().googleMaps?.hasApiKey;
+}

package/dist/utils/map-utils.js

@@ -0,0 +1,54 @@
+/**
+ * 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/dist/utils/token-helper.js

@@ -0,0 +1,396 @@
+/**
+ * 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 → dist}/validation-context.js

@@ -12,8 +12,8 @@
  */
 
 import { createContext } from '@wordpress/element';
-
 export const ValidationContext = createContext({
-	errors: {},        // { attributeKey: 'human message' }
-	showErrors: false, // becomes true after the first failed save attempt
-});
+  errors: {},
+  // { attributeKey: 'human message' }
+  showErrors: false // becomes true after the first failed save attempt
+});