@wordpress-gcb/fields 0.2.0

package/README.md

@@ -0,0 +1,49 @@
+# @wordpress-gcb/fields
+
+GCB's typed-field UI as a standalone package: the control components, the
+inspector renderer (`block.fields.json` → settings panel), and the
+conditional-logic / validation helpers — **with no dependency on the GCB
+WordPress plugin's globals or REST endpoints**.
+
+This is the free, open core of GCB. The Lite plugin consumes it; headless setups
+can use it directly. See `~/sites/gcb/README.md` for how this fits the whole
+project, and `gcb-pro/docs/eject-blocks-scope.md` for the architecture rationale.
+
+**Status: skeleton.** The public API surface and the injected-config contract are
+defined (`src/index.js`); the control source is extracted from the plugin in a
+later step — see `EXTRACTION.md`.
+
+## Why it exists
+
+The plugin currently bakes the controls into itself and feeds them via
+`window.gcbLite` + plugin REST. That couples the field UI to the plugin. Pulling
+it into `@wordpress-gcb/fields` means:
+
+- headless editors get the exact same controls without the plugin;
+- "eject" can scaffold a block that uses the SDK and works plugin-free;
+- graceful degradation: static `block.json` is the floor, the SDK restores live UI.
+
+## Host contract (what you inject)
+
+The plugin used to read these off `window.gcbLite`; here they're explicit:
+
+| Inject | Replaces | For |
+| --- | --- | --- |
+| `controls` (arg to `renderInspector`) | `window.gcbLite.blocks[name].controls` | the fields to render |
+| `tokens` | `window.gcbLite.tokens` | token-aware controls (select, range, spacing) |
+| `googleMapsEnabled` | `window.gcbLite.googleMaps.hasApiKey` | the google-map control |
+| `media` adapter | `wp.media` / block-editor `MediaUpload` | image / gallery / file / richtext |
+| `apiFetch` (optional) | `@wordpress/api-fetch` | reference controls — **core `wp/v2` only** |
+| `variant` | `ControlContext` | `'sidebar'` (popovers) vs `'metabox'` (modals) |
+
+## Not included (stays in the plugin)
+
+The `gcb/repeater` **block** + `useRepeaterSeeding` / `useRepeaterValidation`
+(editor-coupled: clientId, block/editor stores, the validation transient), the
+PHP-preview pipeline, focus-field handling, the admin builder. The `repeater`
+**control** (form-of-forms field) IS included — don't confuse the two.
+
+## Peer vs bundled deps
+
+- **peerDependencies:** all `@wordpress/*` — provided by the host editor.
+- **bundled:** `@dnd-kit/*`, `@tiptap/*` — not part of the WP runtime.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@wordpress-gcb/fields",
+  "version": "0.2.0",
+  "description": "GCB typed-field controls, inspector renderer, and schema — decoupled from the WordPress plugin so any Gutenberg/headless editor can use them.",
+  "license": "GPL-2.0-or-later",
+  "//type": "Intentionally NOT \"type\": \"module\" — the source is ESM syntax consumed by the host's bundler (wp-scripts/webpack), which handles extensionless relative imports. Marking it a strict ESM module would force fully-specified .js extensions on every import.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./conditional-logic": "./src/conditional-logic.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "echo \"no tests yet\" && exit 0"
+  },
+  "//": "WordPress packages are provided by the host editor (externalised in wp-scripts builds) — peer deps, not bundled.",
+  "peerDependencies": {
+    "@wordpress/components": ">=27",
+    "@wordpress/element": ">=5",
+    "@wordpress/i18n": ">=4",
+    "@wordpress/block-editor": ">=12",
+    "@wordpress/api-fetch": ">=6",
+    "@wordpress/blocks": ">=12",
+    "@wordpress/data": ">=9",
+    "@wordpress/icons": ">=9"
+  },
+  "//deps": "Bundled because they are NOT part of the WordPress runtime: the rich-control libraries.",
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tiptap/react": "^3.23.6",
+    "@tiptap/starter-kit": "^3.23.6",
+    "@tiptap/extension-link": "^3.23.6",
+    "@tiptap/extension-image": "^3.23.6"
+  }
+}

package/src/conditional-logic.js

@@ -0,0 +1,77 @@
+/**
+ * Conditional logic — pure functions, no React, no @wordpress/* deps.
+ *
+ * Kept separate from inspector.js so unit tests can import without
+ * pulling in the whole control library. Keep in sync with PHP mirror:
+ *   includes/PostFields/Conditional.php
+ *
+ * Config shape on a control:
+ *
+ *   {
+ *     conditionalLogic: {
+ *       enabled:  true,
+ *       operator: 'and' | 'or',           // default: 'and'
+ *       rules: [
+ *         { field: 'show_cta', operator: '==', value: true },
+ *         { field: 'count',    operator: '>',  value: 0 },
+ *       ],
+ *     }
+ *   }
+ */
+
+// Structural control types (group, panel, tools-panel) render as panel
+// containers, not as fields. Exported so callers that walk the control
+// list can skip them consistently.
+export const STRUCTURAL_TYPES = new Set(['group', 'panel', 'tools-panel']);
+
+/**
+ * Decide whether a control should render against the current attribute
+ * values. A control with no `conditionalLogic` (or a disabled one) is
+ * always rendered.
+ */
+export function shouldRender(control, attributes) {
+	const cl = control.conditionalLogic;
+	if (!cl?.enabled || !Array.isArray(cl.rules) || cl.rules.length === 0) {
+		return true;
+	}
+	const op = cl.operator === 'or' ? 'or' : 'and';
+	const results = cl.rules.map((rule) => evalRule(rule, attributes));
+	return op === 'or' ? results.some(Boolean) : results.every(Boolean);
+}
+
+function evalRule(rule, attributes) {
+	const actual = attributes[rule.field];
+	switch (rule.operator) {
+		case '==': return actual == rule.value; // eslint-disable-line eqeqeq
+		case '!=': return actual != rule.value; // eslint-disable-line eqeqeq
+		case '>':  return Number.isFinite(Number(actual)) && Number.isFinite(Number(rule.value)) && Number(actual) >  Number(rule.value);
+		case '<':  return Number.isFinite(Number(actual)) && Number.isFinite(Number(rule.value)) && Number(actual) <  Number(rule.value);
+		case '>=': return Number.isFinite(Number(actual)) && Number.isFinite(Number(rule.value)) && Number(actual) >= Number(rule.value);
+		case '<=': return Number.isFinite(Number(actual)) && Number.isFinite(Number(rule.value)) && Number(actual) <= Number(rule.value);
+		case 'contains':
+			return typeof actual === 'string' && actual.includes(rule.value);
+		case 'in':
+			return Array.isArray(rule.value) && rule.value.includes(actual);
+		default:
+			return true;
+	}
+}
+
+/**
+ * Walk controls and return the set of panel ids that contain at least one
+ * control whose attributeKey appears in `errors`. Used by the meta-box to
+ * auto-open panels that have validation errors.
+ */
+export function panelsContainingErrors(controls, errors) {
+	const errorKeys = new Set(Object.keys(errors || {}));
+	if (errorKeys.size === 0) return new Set();
+
+	const ids = new Set();
+	for (const c of controls) {
+		if (STRUCTURAL_TYPES.has(c.type)) continue;
+		if (c.attributeKey && errorKeys.has(c.attributeKey) && c.parentPanelId) {
+			ids.add(c.parentPanelId);
+		}
+	}
+	return ids;
+}

package/src/control-context.js

@@ -0,0 +1,17 @@
+/**
+ * Tells controls *which surface* they're being rendered into so they can
+ * render differently. Set by the host (block edit.js for Inspector, post-
+ * fields App for meta-boxes).
+ *
+ * Values:
+ *   - 'sidebar' (default): the block editor's Inspector — narrow column,
+ *     popovers welcome.
+ *   - 'metabox': a classic add_meta_box panel — wider, popovers feel
+ *     out-of-place, controls should lay out inline.
+ *
+ * Controls that don't care can ignore the context entirely.
+ */
+
+import { createContext } from '@wordpress/element';
+
+export const ControlContext = createContext({ variant: 'sidebar' });

package/src/controls/MediaCapabilityGate.js

@@ -0,0 +1,33 @@
+/**
+ * Surface-aware replacement for @wordpress/block-editor's MediaUploadCheck.
+ *
+ * MediaUploadCheck reads from the `core/editor` store to decide whether to
+ * render its children — but `core/editor` is only bootstrapped on screens
+ * that load the block editor. On a classic meta-box-only screen (which is
+ * what gcb-lite post-fields produces by stripping 'editor' support from
+ * field-only CPTs), the store doesn't exist and MediaUploadCheck silently
+ * renders nothing. Result: image / gallery / file fields appear as a label
+ * only.
+ *
+ * We don't need MediaUploadCheck on the meta-box surface because admin-side
+ * gcb-lite enqueues only happen for users WP already granted screen access
+ * to — anyone editing this post has at minimum `edit_posts`. (Real upload
+ * gating still happens server-side inside wp.media when the user tries to
+ * actually upload a file.)
+ *
+ * On the sidebar (block editor) surface, MediaUploadCheck still matters —
+ * blocks can be rendered in contexts where the editor store exists but the
+ * user can't upload. So we pass through to it there.
+ */
+
+import { useContext } from '@wordpress/element';
+import { MediaUploadCheck } from '@wordpress/block-editor';
+import { ControlContext } from '../control-context';
+
+export default function MediaCapabilityGate({ children }) {
+	const ctx = useContext(ControlContext);
+	if (ctx.variant === 'metabox') {
+		return children;
+	}
+	return <MediaUploadCheck>{children}</MediaUploadCheck>;
+}

package/src/controls/MediaPicker.js

@@ -0,0 +1,139 @@
+/**
+ * MediaPicker — a `MediaUpload`-shaped component that works on any
+ * admin screen.
+ *
+ * `@wordpress/block-editor`'s `MediaUpload` requires the `core/block-editor`
+ * data store, which is only initialised on screens that bootstrap the
+ * block editor itself (post.php, site-editor.php, widgets.php). On
+ * profile.php, term.php, options.php — anywhere we mount our post-fields
+ * bundle on a classic admin page — the store isn't there, so the
+ * MediaUpload modal silently fails to open and the image / gallery /
+ * file controls feel broken.
+ *
+ * This wrapper falls back to the lower-level `wp.media()` JS API on
+ * non-editor screens. wp.media is what WP's own avatar uploader uses
+ * and is loaded by wp_enqueue_media() — available on every admin page
+ * we care about. It's not React; we wrap it in the same render-prop
+ * shape MediaUpload exposes so callers don't need to know which path
+ * they're on.
+ *
+ * Shape:
+ *   <MediaPicker
+ *     onSelect={(media) => …}           // single media object (or array)
+ *     allowedTypes={['image']}
+ *     value={123 | [123,124] | null}
+ *     multiple={false}
+ *     gallery={false}
+ *     render={({ open }) => <button onClick={open}>Pick</button>}
+ *   />
+ */
+
+import { useContext } from '@wordpress/element';
+import { MediaUpload } from '@wordpress/block-editor';
+import { ControlContext } from '../control-context';
+
+/**
+ * Translate a wp.media attachment model into the same plain object
+ * @wordpress/block-editor's MediaUpload onSelect receives.
+ */
+function toPlainAttachment(attachment) {
+	const a = attachment.toJSON ? attachment.toJSON() : attachment;
+	return {
+		id:               a.id,
+		url:              a.url,
+		alt:              a.alt || '',
+		title:            a.title || a.filename || '',
+		filename:         a.filename || '',
+		caption:          a.caption || '',
+		description:      a.description || '',
+		mime:             a.mime || a.type || '',
+		type:             a.type || '',
+		subtype:          a.subtype || '',
+		width:            a.width,
+		height:           a.height,
+		filesizeInBytes:  a.filesizeInBytes,
+		sizes:            a.sizes,
+	};
+}
+
+function openClassicMediaFrame({ allowedTypes, multiple, gallery, value, onSelect }) {
+	if (typeof window === 'undefined' || !window.wp || !window.wp.media) {
+		// eslint-disable-next-line no-console
+		console.warn('gcb-lite: wp.media not loaded — call wp_enqueue_media() on this screen.');
+		return;
+	}
+
+	// IMPORTANT: don't open directly into 'gallery-edit' — WP 7.0's
+	// media-views.js bootstraps menu/router state lazily, and asking for
+	// 'gallery-edit' before the menu state exists throws
+	// `Cannot read properties of undefined (reading 'get')` in
+	// setMenuTabPanelAriaAttributes. The supported gallery flow is to open
+	// the library with `multiple: true`, pre-select the existing images,
+	// and treat the result as a gallery on 'select'.
+	const isMulti = !!(gallery || multiple);
+
+	const frame = window.wp.media({
+		title:    gallery ? 'Edit gallery' : (isMulti ? 'Select media' : 'Select media'),
+		button:   { text: gallery ? 'Update gallery' : 'Use this media' },
+		library:  allowedTypes ? { type: allowedTypes } : undefined,
+		multiple: isMulti,
+	});
+
+	// Pre-select prior value so the user lands on the existing pick.
+	frame.on('open', () => {
+		const selection = frame.state().get('selection');
+		if (!selection) return;
+		const ids = Array.isArray(value) ? value : (value ? [value] : []);
+		ids.forEach((id) => {
+			if (!id) return;
+			const attachment = window.wp.media.attachment(id);
+			if (!attachment) return;
+			attachment.fetch();
+			selection.add([attachment]);
+		});
+	});
+
+	frame.on('select', () => {
+		const selection = frame.state().get('selection');
+		if (!selection) return;
+		const picks = selection.toArray().map(toPlainAttachment);
+		if (isMulti) {
+			onSelect(picks);
+		} else {
+			onSelect(picks[0] || null);
+		}
+	});
+
+	frame.open();
+}
+
+/**
+ * Decide which backend to use based on render surface:
+ *
+ * - Block Inspector ('sidebar' variant): MediaUpload from
+ *   @wordpress/block-editor. That's the right tool inside the block
+ *   editor — it integrates with the editor's upload flow + capability
+ *   store.
+ *
+ * - Post-fields meta-box / Options / Taxonomy / User pages
+ *   ('metabox' variant): wp.media() directly. These screens often DON'T
+ *   bootstrap the block editor (we strip 'editor' support from
+ *   field-only CPTs), and MediaUpload silently renders nothing when the
+ *   editor stores aren't fully initialised. wp.media() is the lower-
+ *   level JS API loaded by wp_enqueue_media() — works on any admin page.
+ *
+ * Surface decision is made via ControlContext, which post-fields.js
+ * sets to 'metabox' and the block Inspector leaves at 'sidebar'.
+ */
+export default function MediaPicker(props) {
+	const ctx = useContext(ControlContext);
+
+	if (ctx.variant !== 'metabox') {
+		return <MediaUpload {...props} />;
+	}
+
+	// Metabox surface — synthesize the same render-prop shape with a
+	// wp.media() backend.
+	const open = () => openClassicMediaFrame(props);
+	return props.render ? props.render({ open }) : null;
+}

package/src/controls/MediaTriggerBadges.js

@@ -0,0 +1,31 @@
+/**
+ * MediaTriggerBadges — places an inline clear (×) button to the right of
+ * a media-control toggle. Used by ImageField and FileField on the metabox
+ * surface. Edit affordance isn't needed — clicking the trigger itself
+ * opens the picker/popover.
+ */
+
+import { __ } from '@wordpress/i18n';
+import { Button } from '@wordpress/components';
+
+// Default sizing is content-width (inline-flex). In sidebar / Inspector
+// contexts an external rule promotes it to full-width — see editor.scss
+// "Sidebar / Inspector surface: media trigger fills width".
+export default function MediaTriggerBadges({ children, onClear, hideClear }) {
+	return (
+		<span className="gcb-media-trigger-badges">
+			{children}
+			{!hideClear && (
+				<Button
+					variant="tertiary"
+					isDestructive
+					onClick={(e) => { e.stopPropagation(); e.preventDefault(); onClear?.(); }}
+					aria-label={__('Clear', 'gcblite')}
+					title={__('Clear', 'gcblite')}
+				>
+					✕
+				</Button>
+			)}
+		</span>
+	);
+}

package/src/controls/PopoverOrModal.js

@@ -0,0 +1,83 @@
+/**
+ * Container that hosts a control's "rich settings" UI in the right surface
+ * for the current ControlContext:
+ *   - sidebar  → <Dropdown> (popover anchored to the toggle)
+ *   - metabox  → <Modal> (centered overlay with backdrop)
+ *
+ * Why: popovers feel right in a narrow sidebar where they extend outward,
+ * but in a wide meta-box they're awkward (they can run off-screen, they
+ * obscure adjacent fields, and they don't have the visual weight to read
+ * as "editing this field"). Modals match meta-box context.
+ *
+ * Usage:
+ *   <PopoverOrModal
+ *     renderToggle={({ onToggle, isOpen }) => <Button onClick={onToggle}>Open</Button>}
+ *     renderContent={({ close, variant }) => (
+ *       <div style={variant === 'modal' ? { width: '100%' } : { minWidth: 320, maxWidth: 400 }}>
+ *         <MySettings onDone={close} />
+ *       </div>
+ *     )}
+ *     modalTitle="Image settings"
+ *   />
+ *
+ * renderContent receives `{ close, variant }`:
+ *   - close():        dismiss the popover or modal
+ *   - variant:        'popover' | 'modal' — lets callers branch widths,
+ *                     padding, etc. ('modal' contents typically want to
+ *                     fill the modal width; 'popover' contents want a
+ *                     comfortable popover-sized box.)
+ *
+ * The dropdown render passes the same { onToggle, isOpen } shape as
+ * @wordpress/components Dropdown.renderToggle so the call-site doesn't
+ * have to know which it's getting.
+ */
+
+import { useContext, useState } from '@wordpress/element';
+import { Dropdown, Modal } from '@wordpress/components';
+import { ControlContext } from '../control-context';
+
+export default function PopoverOrModal({
+	renderToggle,
+	renderContent,
+	modalTitle,
+	modalSize = 'medium',
+	dropdownProps = {},
+}) {
+	const ctx = useContext(ControlContext);
+
+	if (ctx.variant === 'metabox') {
+		return (
+			<ModalAffordance
+				renderToggle={renderToggle}
+				renderContent={renderContent}
+				modalTitle={modalTitle}
+				modalSize={modalSize}
+			/>
+		);
+	}
+
+	return (
+		<Dropdown
+			{...dropdownProps}
+			renderToggle={renderToggle}
+			renderContent={({ onClose }) => renderContent({ close: onClose, variant: 'popover' })}
+		/>
+	);
+}
+
+function ModalAffordance({ renderToggle, renderContent, modalTitle, modalSize }) {
+	const [open, setOpen] = useState(false);
+	const onToggle = () => setOpen((v) => !v);
+	const close = () => setOpen(false);
+
+	return (
+		<>
+			{renderToggle({ onToggle, isOpen: open })}
+			{open && (
+				<Modal title={modalTitle} onRequestClose={close} size={modalSize}>
+					{renderContent({ close, variant: 'modal' })}
+				</Modal>
+			)}
+		</>
+	);
+}

package/src/controls/SortableItem.js

@@ -0,0 +1,110 @@
+/**
+ * Sortable item — ported from the original GCB SortableItemComponent.
+ *
+ * Used by gallery, post-object (and any other future multi-select reorderable
+ * field) to render a draggable row with handle, title, and remove button.
+ */
+import { useSortable } from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import { __ } from '@wordpress/i18n';
+
+const ICONS = {
+	post: {
+		viewBox: '0 0 24 24',
+		path: (
+			<>
+				<path d="M15.5 7.5h-7V9h7V7.5Zm-7 3.5h7v1.5h-7V11Zm7 3.5h-7V16h7v-1.5Z" />
+				<path d="M17 4H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2ZM7 5.5h10a.5.5 0 0 1 .5.5v12a.5.5 0 0 1-.5.5H7a.5.5 0 0 1-.5-.5V6a.5.5 0 0 1 .5-.5Z" />
+			</>
+		),
+	},
+	tag: {
+		viewBox: '0 0 24 24',
+		path: <path d="M12.5 4.5h-2v7h7v-2l-5-5zm-2.5 8.5v5h2v-5h-2zm5 5h2v-5h-2v5z" />,
+	},
+	image: {
+		viewBox: '0 0 24 24',
+		path: <path d="M19 5v14H5V5h14m0-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-4.86 8.86l-3 3.87L9 13.14 6 17h12l-3.86-5.14z" />,
+	},
+};
+
+export default function SortableItem({ item, onRemove, icon = 'post', getTitle, thumb }) {
+	const {
+		attributes,
+		listeners,
+		setNodeRef,
+		transform,
+		transition,
+		isDragging,
+	} = useSortable({ id: item.id });
+
+	const style = {
+		transform: CSS.Transform.toString(transform),
+		transition,
+		opacity: isDragging ? 0.5 : 1,
+	};
+
+	const selectedIcon = ICONS[icon] || ICONS.post;
+
+	return (
+		<div
+			ref={setNodeRef}
+			style={style}
+			className="gcb-sortable-item"
+			{...attributes}
+			{...listeners}
+		>
+			<div className="gcb-sortable-drag-handle" aria-hidden>
+				<svg viewBox="0 0 20 20" width="12">
+					<path d="M7 2a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 2zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 8zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 14zm6-8a2 2 0 1 0-.001-4.001A2 2 0 0 0 13 6zm0 2a2 2 0 1 0 .001 4.001A2 2 0 0 0 13 8zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 13 14z" />
+				</svg>
+			</div>
+
+			{thumb ? (
+				<img
+					src={thumb}
+					alt=""
+					style={{
+						width: 28, height: 28, borderRadius: 2, objectFit: 'cover',
+						marginRight: 8, flexShrink: 0, border: '1px solid #ddd',
+					}}
+				/>
+			) : (
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					viewBox={selectedIcon.viewBox}
+					width="20"
+					height="20"
+					style={{ marginRight: 8, flexShrink: 0, opacity: 0.6 }}
+				>
+					{selectedIcon.path}
+				</svg>
+			)}
+
+			<span style={{
+				flex: 1,
+				overflow: 'hidden',
+				textOverflow: 'ellipsis',
+				whiteSpace: 'nowrap',
+				userSelect: 'none',
+			}}>
+				{getTitle ? getTitle(item) : (item.title?.rendered || item.name || __('(no title)', 'gcblite'))}
+			</span>
+
+			<button
+				type="button"
+				onClick={(e) => {
+					e.stopPropagation();
+					onRemove(item.id);
+				}}
+				onPointerDown={(e) => e.stopPropagation()}
+				className="gcb-sortable-remove"
+				aria-label={__('Remove', 'gcblite')}
+			>
+				<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20">
+					<path d="M12 13.06l3.712 3.713 1.061-1.06L13.061 12l3.712-3.712-1.06-1.06L12 10.938 8.288 7.227l-1.061 1.06L10.939 12l-3.712 3.712 1.06 1.061L12 13.061z" />
+				</svg>
+			</button>
+		</div>
+	);
+}

package/src/controls/button-group.js

@@ -0,0 +1,49 @@
+/**
+ * ButtonGroup — multi-select shown as a row of toggle buttons. Each option
+ * looks like a pressable button; clicking toggles it on/off.
+ *
+ * Stored shape: array of selected values, same as checkbox-group.
+ *   ['apple', 'cherry']
+ *
+ * Why not alias checkbox-group? Checkbox-group is checkboxes-in-a-column
+ * (vertical, ☑ ☐ ☐). ButtonGroup is buttons-in-a-row (horizontal, compact,
+ * visually weightier). Same data shape, different affordance.
+ *
+ * For single-select segmented controls use `toggle-group` instead.
+ */
+
+import { BaseControl, Button, __experimentalHStack as HStack } from '@wordpress/components';
+
+export default function ButtonGroupField({ control, value, onChange }) {
+	const current = Array.isArray(value) ? value : [];
+
+	return (
+		<BaseControl
+			label={control.label}
+			help={control.helpText}
+			className="gcb-button-group-control components-base-control"
+			__nextHasNoMarginBottom
+		>
+			<HStack spacing={1} justify="flex-start" wrap>
+				{(control.options || []).map((option) => {
+					const isOn = current.includes(option.value);
+					return (
+						<Button
+							key={option.value}
+							variant={isOn ? 'primary' : 'secondary'}
+							onClick={() => {
+								const next = isOn
+									? current.filter((v) => v !== option.value)
+									: [...current, option.value];
+								onChange(next);
+							}}
+							aria-pressed={isOn}
+						>
+							{option.label}
+						</Button>
+					);
+				})}
+			</HStack>
+		</BaseControl>
+	);
+}