@wordpress-gcb/fields 0.2.0 → 0.2.1

package/README.md

@@ -1,49 +1,65 @@
 # @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**.
+Typed-field UI for the WordPress block editor: control components, an inspector
+renderer that turns a `block.fields.json` schema into a settings panel, plus
+conditional-logic and validation helpers — **decoupled from any plugin**. Host
+data (design tokens, media picker, etc.) is injected, so the same controls run
+inside the [GCB Lite plugin](https://github.com/wordpress-gcb/gutenberg-control-blocks-lite),
+a meta box, or a headless editor.
 
-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.
+This is the free, open core of **[GCB](https://gutenbergcontrolblocks.com)** —
+[Gutenberg Control Blocks](https://gutenbergcontrolblocks.com).
 
-**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`.
+## Install
 
-## Why it exists
+```bash
+npm install @wordpress-gcb/fields
+```
 
-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:
+`@wordpress/*` are peer dependencies — provided by the WordPress editor runtime
+(or your build's externals). `@dnd-kit/*` and `@tiptap/*` ship bundled.
 
-- 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.
+## Usage
 
-## Host contract (what you inject)
+```jsx
+import { GcbFieldsProvider, renderInspector } from '@wordpress-gcb/fields';
 
-The plugin used to read these off `window.gcbLite`; here they're explicit:
+// controls = the `controls` array from a block.fields.json
+<GcbFieldsProvider value={{ tokens, googleMapsEnabled: true }}>
+  {renderInspector(controls, attributes, setAttributes)}
+</GcbFieldsProvider>
+```
 
-| 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) |
+Each control receives `{ control, value, onChange, attributes }`. The provider
+supplies what the controls need from the host:
 
-## Not included (stays in the plugin)
+| Inject | For |
+| --- | --- |
+| `tokens` | token-aware controls (select, range, spacing) |
+| `googleMapsEnabled` | the google-map control |
+| `media` | media picker adapter (image / gallery / file / richtext) |
+| `apiFetch` | reference controls — calls core `wp/v2` (optional; defaults to `@wordpress/api-fetch`) |
+| `variant` | `'sidebar'` (popovers) vs `'metabox'` (modals) |
 
-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.
+All are optional; with none provided the package falls back to the WordPress
+editor globals.
 
-## Peer vs bundled deps
+## Exports
 
-- **peerDependencies:** all `@wordpress/*` — provided by the host editor.
-- **bundled:** `@dnd-kit/*`, `@tiptap/*` — not part of the WP runtime.
+- `renderInspector(controls, attributes, setAttributes, options?)`
+- `controlComponents` — the control registry (`type` → component)
+- `GcbFieldsProvider`, `useGcbFieldsConfig`
+- `shouldRender`, `panelsContainingErrors`, `STRUCTURAL_TYPES`
+- `ValidationContext`, `ControlContext`
+- token helpers: `useTokens`, `getTokensByGroup`, `getAllTokenGroups`
+
+## Links
+
+- **Website:** <https://gutenbergcontrolblocks.com>
+- **Source:** <https://github.com/wordpress-gcb/gcb-fields>
+- **Issues:** <https://github.com/wordpress-gcb/gcb-fields/issues>
+- **GCB Lite plugin:** <https://github.com/wordpress-gcb/gutenberg-control-blocks-lite>
+
+## License
+
+GPL-2.0-or-later

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "@wordpress-gcb/fields",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
+  "homepage": "https://gutenbergcontrolblocks.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wordpress-gcb/gcb-fields.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wordpress-gcb/gcb-fields/issues"
+  },
+  "keywords": [
+    "wordpress",
+    "gutenberg",
+    "block-editor",
+    "fields",
+    "gcb"
+  ],
   "//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": {