@plaudit/gutenberg-api-extensions 2.80.1 → 2.81.0

package/simple-native-properties.md

@@ -0,0 +1,1100 @@
+# Simple Native Properties (SNP)
+
+SNP allows you to define Inspector (sidebar) controls in `block.json` purely with data, avoiding custom React code for standard use cases.
+
+## 📑 Table of Contents
+
+- [Quick Start Example](#-quick-start-example)
+- [Control Reference](#-control-reference)
+  - [Common Properties](#common-properties-available-on-all-controls)
+- [Control Types](#️-control-types)
+  - [Basic Input Controls](#basic-input-controls)
+    - [`text`](#text)
+    - [`textarea`](#textarea)
+    - [`number`](#number)
+    - [`range`](#range)
+  - [Toggle & Choice Controls](#toggle--choice-controls)
+    - [`toggle`](#toggle)
+    - [`toggleGroup`](#togglegroup)
+    - [`select`](#select)
+    - [`radio`](#radio)
+    - [`colorPalette`](#colorpalette)
+  - [Media & Relational Controls](#media--relational-controls)
+    - [`image`](#image)
+    - [`link`](#link)
+    - [`post`](#post)
+    - [`taxonomy`](#taxonomy)
+    - [`term`](#term)
+    - [`user`](#user)
+  - [Structure & Collection Controls](#structure--collection-controls)
+    - [`group`](#group)
+    - [`list`](#list)
+    - [`date`](#date)
+    - [`constant`](#constant)
+- [Organization & Logic](#️-organization--logic)
+  - [1. Structure (Panels & Tabs)](#1-structure-panels--tabs)
+  - [2. Layout (Rows)](#2-layout-rows)
+  - [3. Conditions (Show/Hide Logic)](#3-conditions-showhide-logic)
+  - [4. Option Sources (Dynamic Options)](#4-option-sources-dynamic-options)
+- [Advanced Features](#-advanced-features)
+  - [Style Properties](#style-properties)
+  - [Validators & Transformers](#validators--transformers)
+- [Tips & Best Practices](#tips--best-practices)
+
+---
+
+## ⚡ Quick Start Example
+
+Copy and adapt this block to cover 90% of your use cases. It demonstrates **Panels**, **Layouts**, **Conditions**, and **Common Controls**.
+
+```json
+"plaudit": {
+  "properties": [
+    {
+      "title": "Main Content",
+      "initialOpen": true,
+      "properties": [
+        { "name": "headline", "label": "Headline", "control": "text", "placeholder": "Enter headline..." },
+        { 
+          "name": "subhead", "label": "Subhead", "control": "textarea", 
+          "condition": [{ "op": "!empty", "property": "headline" }]
+        },
+        [
+           { "name": "amount", "label": "Count", "control": "number", "min": 1, "max": 10 },
+           { "name": "showCount", "label": "Display", "control": "toggle", "switch": "yesNo" }
+        ]
+      ]
+    },
+    {
+      "title": "Media & Links",
+      "group": "settings",
+      "properties": [
+        { "name": "media", "label": "Hero Image", "control": "image", "includeFocalPointPicker": true },
+        { "name": "cta", "label": "Call to Action", "control": "link" },
+        { 
+          "name": "featuredPost", "label": "Featured Article", "control": "post",
+          "postTypes": ["post"], "multiple": false 
+        }
+      ]
+    },
+    {
+      "title": "Design Settings",
+      "group": "styles", 
+      "properties": [
+        { "name": "bgColor", "label": "Background", "control": "colorPalette", "options": "select:theme:colors" },
+        { "name": "opacity", "label": "Opacity", "control": "range", "min": 0, "max": 100, "step": 10 },
+        { 
+          "name": "align", "label": "Alignment", "control": "select",
+          "options": [
+            ["left", "Left"],
+            ["center", "Center"],
+            ["right", "Right"]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 📋 Control Reference
+
+All controls require three properties: `"control"`, `"name"`, and `"label"`.
+
+### Common Properties (Available on All Controls)
+
+| Property        | Type     | Description                                                                                    |
+|:----------------|:---------|:-----------------------------------------------------------------------------------------------|
+| `name`          | string   | **Required.** The attribute key where the value is stored.                                     |
+| `label`         | string   | **Required.** Display label shown in the sidebar.                                              |
+| `control`       | string   | **Required.** The type of control (e.g., `"text"`, `"toggle"`).                                |
+| `default`       | any      | Default value when the attribute is not set.                                                   |
+| `help`          | string   | Help text displayed below the control.                                                         |
+| `required`      | boolean  | Whether the field is required. Default: `false`.                                               |
+| `alwaysStore`   | boolean  | Whether to always store the value even if undefined. Default: `false`.                         |
+| `condition`     | array    | Show/hide logic based on other properties (see Conditions section).                            |
+| `component`     | object   | Additional props passed to the underlying React component.                                     |
+| `styleProperty` | string   | CSS property name to bind this value to (for controls with `string` and `number` value types). |
+| `validator`     | function | Custom validation function (TypeScript/React only).                                            |
+| `transformer`   | object   | Custom value transformation (TypeScript/React only).                                           |
+
+---
+
+## 🎛️ Control Types
+
+### Basic Input Controls
+
+#### `text`
+Single-line text input.
+
+**Value Type:** `string`
+
+##### Additional Properties
+| Property      | Type     | Description                        | Default |
+|:--------------|:---------|:-----------------------------------|:--------|
+| `placeholder` | `string` | Placeholder text shown when empty. | `''`    |
+
+**Example:**
+
+```json
+{ 
+  "name": "headline", 
+  "label": "Headline", 
+  "control": "text",
+  "placeholder": "Enter your headline...",
+  "default": ""
+}
+```
+
+---
+
+#### `textarea`
+Multi-line text input.
+
+**Value Type:** `string`
+
+##### Additional Properties
+| Property         | Type     | Description                 | Default |
+|:-----------------|:---------|:----------------------------|:--------|
+| `component.rows` | `number` | Number of visible text rows | `4`     |
+
+**Example:**
+
+```json
+{ 
+  "name": "description", 
+  "label": "Description", 
+  "control": "textarea",
+  "component": { "rows": 6 },
+  "help": "Enter a detailed description"
+}
+```
+
+---
+
+#### `number`
+Numeric input with optional constraints.
+
+**Value Type:** `number`
+
+##### Additional Properties
+| Property      | Type              | Description                                           | Default |
+|:--------------|:------------------|:------------------------------------------------------|:--------|
+| `min`         | `number`          | Minimum allowed value                                 | `unset` |
+| `max`         | `number`          | Maximum allowed value                                 | `unset` |
+| `step`        | `number \| 'any'` | Increment step. Use `"any"` to switch to decimal mode | `unset` |
+| `float`       | `boolean`         | Force decimal mode                                    | `false` |
+| `placeholder` | `string`          | Placeholder text                                      | `''`    |
+
+**Example:**
+
+```json
+{ 
+  "name": "quantity", 
+  "label": "Quantity", 
+  "control": "number",
+  "min": 1,
+  "max": 100,
+  "step": 1,
+  "default": 10
+}
+```
+
+---
+
+#### `range`
+Slider control for selecting numeric values.
+
+**Value Type:** `number`
+
+##### Additional Properties
+| Property | Type     | Description                         | Default |
+|:---------|:---------|:------------------------------------|:--------|
+| `min`    | `number` | **Required.** Minimum allowed value | `unset` |
+| `max`    | `number` | **Required.** Maximum allowed value | `unset` |
+| `step`   | `number` | Increment step                      | `1`     |
+
+**Example:**
+
+```json
+{ 
+  "name": "opacity", 
+  "label": "Opacity", 
+  "control": "range",
+  "min": 0,
+  "max": 100,
+  "step": 5,
+  "default": 100
+}
+```
+
+---
+
+### Toggle & Choice Controls
+
+#### `toggle`
+Boolean on/off switch.
+
+**Value Type:** `boolean`
+
+##### Additional Properties
+- `switch` (`string | object`): Switch style configuration.
+  - String values: `"yesNo"`, `"showHide"`
+  - Object with properties:
+    - `type` (`string`): `"yesNo"` or `"showHide"`
+    - `small` (`boolean`): Use small toggle style. Default: `false`.
+    - `narrow` (`boolean`): Use narrow layout. Default: `false`.
+    - `onLabel` (`string`): Custom label for "on" state.
+    - `offLabel` (`string`): Custom label for "off" state.
+
+**Example:**
+
+```json
+{ 
+  "name": "showBreadcrumbs", 
+  "label": "Show Breadcrumbs", 
+  "control": "toggle",
+  "switch": "yesNo",
+  "default": true
+}
+```
+
+**Custom Labels:**
+
+```json
+{
+  "name": "enableFeature",
+  "label": "Enable Feature",
+  "control": "toggle",
+  "switch": {
+    "type": "yesNo",
+    "onLabel": "Enabled",
+    "offLabel": "Disabled"
+  }
+}
+```
+
+**Small Toggle:**
+
+```json
+{
+  "name": "compactMode",
+  "label": "Compact Mode",
+  "control": "toggle",
+  "switch": {
+    "small": true
+  }
+}
+```
+
+---
+
+#### `toggleGroup`
+Button group for selecting one value from multiple options.
+
+**Value Type:** `string` or `number`
+
+##### Additional Properties
+| Property    | Type                   | Description                                                                                                                      | Default    |
+|:------------|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------|:-----------|
+| `options`   | `array \| string`      | **Required.** Array of `[value, label]` tuples or option objects or a [dynamic source string](#4-option-sources-dynamic-options) | `unset`    |
+| `clearable` | `boolean`              | Allow deselecting all options                                                                                                    | `false`    |
+| `type`      | `"string" \| "number"` | The value type returned by the toggle group                                                                                      | `"string"` |
+
+**Example:**
+
+```json
+{ 
+  "name": "alignment", 
+  "label": "Text Alignment", 
+  "control": "toggleGroup",
+  "options": [
+    ["left", "Left"],
+    ["center", "Center"],
+    ["right", "Right"]
+  ],
+  "default": "left"
+}
+```
+
+**With Icons:**
+
+```json
+{
+  "name": "layout",
+  "label": "Layout",
+  "control": "toggleGroup",
+  "options": [
+    ["list", { "text": "List", "icon": "list" }],
+    ["grid", { "text": "Grid", "icon": "grid" }]
+  ]
+}
+```
+
+---
+
+#### `select`
+Dropdown selection control.
+
+**Value Type:** `string` (single) or `string[]` (multiple)
+
+##### Additional Properties
+| Property        | Type              | Description                                                                                                                      | Default |
+|:----------------|:------------------|:---------------------------------------------------------------------------------------------------------------------------------|:--------|
+| `options`       | `array \| string` | **Required.** Array of `[value, label]` tuples or option objects or a [dynamic source string](#4-option-sources-dynamic-options) | `unset` |
+| `multiple`      | `boolean`         | Allow selecting multiple values                                                                                                  | `false` |
+| `clearable`     | `boolean`         | Allow clearing the selection (single select only)                                                                                | `false` |
+| `expandOnFocus` | `boolean`         | Auto-expand dropdown on focus (multi-select only)                                                                                | `false` |
+| `maxLength`     | `number`          | Maximum number of selections (multi-select only)                                                                                 | `unset` |
+
+**Example (Single Select):**
+
+```json
+{ 
+  "name": "viewType", 
+  "label": "View Type", 
+  "control": "select",
+  "options": [
+    ["list", "List"],
+    ["gallery", "Gallery"],
+    ["grid", "Grid"]
+  ],
+  "default": "grid"
+}
+```
+
+**Example (Multiple Select):**
+
+```json
+{ 
+  "name": "categories", 
+  "label": "Categories", 
+  "control": "select",
+  "options": [
+    ["tech", "Technology"],
+    ["design", "Design"],
+    ["business", "Business"]
+  ],
+  "multiple": true,
+  "maxLength": 3
+}
+```
+
+---
+
+#### `radio`
+Radio button group for selecting one option.
+
+**Value Type:** `string`
+
+##### Additional Properties
+| Property      | Type              | Description                                                                                                                      | Default |
+|:--------------|:------------------|:---------------------------------------------------------------------------------------------------------------------------------|:--------|
+| `options`     | `array \| string` | **Required.** Array of `[value, label]` tuples or option objects or a [dynamic source string](#4-option-sources-dynamic-options) | `unset` |
+| `allowCustom` | `boolean`         | Allow entering a custom value                                                                                                    | `false` |
+
+**Example:**
+
+```json
+{ 
+  "name": "dateFormat", 
+  "label": "Date Format", 
+  "control": "radio",
+  "options": [
+    ["none", "None"],
+    ["F j, Y", "January 30, 1987"],
+    ["m/d/Y", "01/30/1987"]
+  ],
+  "allowCustom": true,
+  "default": "none"
+}
+```
+
+---
+
+#### `colorPalette`
+Color picker with theme palette integration.
+
+**Value Type:** `string`
+
+##### Additional Properties
+| Property      | Type              | Description                                                                                                                             | Default |
+|:--------------|:------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:--------|
+| `options`     | `array \| string` | **Required.** Array of `[color string, label]` tuples or option objects or a [dynamic source string](#4-option-sources-dynamic-options) | `unset` |
+| `allowCustom` | `boolean`         | Allow custom color input                                                                                                                | `false` |
+| `clearable`   | `boolean`         | Allow clearing the selection                                                                                                            | `false` |
+
+**Example:**
+
+```json
+{ 
+  "name": "backgroundColor", 
+  "label": "Background Color", 
+  "control": "colorPalette",
+  "options": "select:theme:colors",
+  "clearable": true
+}
+```
+
+---
+
+### Media & Relational Controls
+
+#### `image`
+Image selector with media library integration.
+
+**Value Type:** `object` (ImageData)
+
+**Additional Properties:**
+- `includeFocalPointPicker` (boolean): Enable focal point selection. Default: `false`.
+- `storage` (object): Storage configuration for the image control.
+
+**Example:**
+
+```json
+{ 
+  "name": "heroImage", 
+  "label": "Hero Image", 
+  "control": "image",
+  "includeFocalPointPicker": true
+}
+```
+
+---
+
+#### `link`
+Link picker for URLs, pages, posts, etc.
+
+**Value Type:** `object`
+
+**Additional Properties:**
+- `settings` (boolean | array): Enable link settings (opens in new tab, etc.). Default: `false`.
+
+**Example:**
+
+```json
+{ 
+  "name": "ctaLink", 
+  "label": "Call to Action Link", 
+  "control": "link",
+  "settings": true
+}
+```
+
+---
+
+#### `post`
+Post/page selector with search functionality.
+
+**Value Type:** `number` (single) or `number[]` (multiple)
+
+**Additional Properties:**
+- `postTypes` (array): Array of post type slugs to include. Default: `["post", "page"]`.
+- `multiple` (boolean): Allow selecting multiple posts. Default: `false`.
+- `placeholder` (string): Placeholder text.
+- `taxonomyQuery` (object): Filter posts by taxonomy terms.
+
+**Example (Single Post):**
+
+```json
+{ 
+  "name": "featuredPost", 
+  "label": "Featured Article", 
+  "control": "post",
+  "postTypes": ["post"],
+  "multiple": false
+}
+```
+
+**Example (Multiple Products):**
+
+```json
+{ 
+  "name": "relatedProducts", 
+  "label": "Related Products", 
+  "control": "post",
+  "postTypes": ["product"],
+  "multiple": true,
+  "placeholder": "Search for products..."
+}
+```
+
+---
+
+#### `taxonomy`
+Taxonomy selector (categories, tags, custom taxonomies).
+
+**Value Type:** `string` (single) or `string[]` (multiple)
+
+**Additional Properties:**
+- `multiple` (boolean): Allow selecting multiple taxonomies. Default: `true`.
+- `placeholder` (string): Placeholder text.
+- `visibility` (object): Control taxonomy visibility filters.
+  - Properties match WordPress taxonomy visibility settings (e.g., `publicly_queryable`, `show_ui`).
+
+**Example:**
+
+```json
+{ 
+  "name": "targetTaxonomies", 
+  "label": "Target Taxonomies", 
+  "control": "taxonomy",
+  "multiple": true,
+  "visibility": {
+    "publicly_queryable": true
+  }
+}
+```
+
+---
+
+#### `term`
+Taxonomy term selector (specific category/tag picker).
+
+**Value Type:** `string` (single) or `string[]` (multiple)
+
+**Additional Properties:**
+- `taxonomy` (string): **Required.** The taxonomy slug (e.g., `"category"`, `"post_tag"`).
+- `multiple` (boolean): Allow selecting multiple terms. Default: `true`.
+- `placeholder` (string): Placeholder text.
+
+**Example:**
+
+```json
+{ 
+  "name": "productCategories", 
+  "label": "Product Categories", 
+  "control": "term",
+  "taxonomy": "product_cat",
+  "multiple": true
+}
+```
+
+---
+
+#### `user`
+User selector with role filtering.
+
+**Value Type:** `number` (single) or `number[]` (multiple)
+
+**Additional Properties:**
+- `userRoles` (array): Array of role slugs to filter by (e.g., `["editor", "author"]`).
+- `multiple` (boolean): Allow selecting multiple users. Default: `false`.
+- `placeholder` (string): Placeholder text.
+
+**Example (Single User):**
+
+```json
+{ 
+  "name": "author", 
+  "label": "Content Author", 
+  "control": "user",
+  "userRoles": ["author", "editor"],
+  "multiple": false
+}
+```
+
+**Example (Multiple Users):**
+
+```json
+{ 
+  "name": "teamMembers", 
+  "label": "Team Members", 
+  "control": "user",
+  "multiple": true,
+  "placeholder": "Search for users..."
+}
+```
+
+---
+
+### Structure & Collection Controls
+
+#### `group`
+Groups related controls together visually.
+
+**Value Type:** `object`
+
+**Additional Properties:**
+- `fields` (`array`): **Required.** Array of control definitions.
+- `interface` (`string`): UI style: `"default"` or `"toolsPanel"`. Default: `"default"`.
+
+**Example:**
+
+```json
+{ 
+  "name": "spacing", 
+  "label": "Spacing Settings", 
+  "control": "group",
+  "fields": [
+    { "name": "top", "label": "Top", "control": "number", "min": 0 },
+    { "name": "bottom", "label": "Bottom", "control": "number", "min": 0 }
+  ]
+}
+```
+
+**Tools Panel Example:**
+
+```json
+{ 
+  "name": "dimensions", 
+  "label": "Dimensions", 
+  "control": "group",
+  "interface": "toolsPanel",
+  "fields": [
+    { "name": "width", "label": "Width", "control": "number" },
+    { "name": "height", "label": "Height", "control": "number" }
+  ]
+}
+```
+
+---
+
+#### `list`
+Repeatable list of items (simple strings/numbers or complex objects).
+
+**Value Type:** `array`
+
+**Additional Properties:**
+- `itemType` (string | array): **Required.** 
+  - `"string"` for simple string lists
+  - `"int"`, `"integer"`, or `"float"` for number lists
+  - Array of controls for complex object lists
+  - Object with type definitions for flexible items (different item types)
+- `min` (number): Minimum number of items.
+- `max` (number): Maximum number of items.
+- `emptyValue` (any): Value for new items.
+- `sharedProperties` (array): Controls that apply to all flexible items.
+- `listComponent` (object): Props for the list item input component.
+
+**Example (Simple String List):**
+
+```json
+{ 
+  "name": "tags", 
+  "label": "Tags", 
+  "control": "list",
+  "itemType": "string",
+  "max": 5
+}
+```
+
+**Example (Number List):**
+
+```json
+{ 
+  "name": "scores", 
+  "label": "Scores", 
+  "control": "list",
+  "itemType": "float",
+  "min": 1,
+  "max": 10
+}
+```
+
+**Example (Complex Object List):**
+
+```json
+{ 
+  "name": "teamMembers", 
+  "label": "Team Members", 
+  "control": "list",
+  "itemType": [
+    { "name": "name", "label": "Name", "control": "text" },
+    { "name": "role", "label": "Role", "control": "text" },
+    { "name": "photo", "label": "Photo", "control": "image" }
+  ],
+  "min": 1,
+  "max": 10
+}
+```
+
+**Example (Flexible Items - Different Types):**
+
+```json
+{ 
+  "name": "contentBlocks", 
+  "label": "Content Blocks", 
+  "control": "list",
+  "itemType": {
+    "text": {
+      "label": "Text Block",
+      "properties": [
+        { "name": "content", "label": "Content", "control": "textarea" }
+      ]
+    },
+    "image": {
+      "label": "Image Block",
+      "properties": [
+        { "name": "image", "label": "Image", "control": "image" },
+        { "name": "caption", "label": "Caption", "control": "text" }
+      ]
+    }
+  },
+  "sharedProperties": [
+    { "name": "title", "label": "Block Title", "control": "text" }
+  ]
+}
+```
+
+---
+
+#### `date`
+Date and optional time picker.
+
+**Value Type:** `number` (Unix timestamp in milliseconds)
+
+**Additional Properties:**
+- `time` (boolean): Include time selection. Default: `false`.
+
+**Example:**
+
+```json
+{ 
+  "name": "eventDate", 
+  "label": "Event Date", 
+  "control": "date",
+  "time": true
+}
+```
+
+---
+
+#### `constant`
+Hidden field with a constant value (not editable by users).
+
+**Value Type:** Depends on `type` property
+
+**Additional Properties:**
+- `type` (`string`): **Required.** Value type: `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`.
+- `default` (depends): **Required.** The constant value, must be of the specified type
+
+**Example:**
+
+```json
+{ 
+  "name": "blockVersion", 
+  "label": "Block Version", 
+  "control": "constant",
+  "type": "string",
+  "default": "2.0"
+}
+```
+
+---
+
+## 🏗️ Organization & Logic
+
+### 1. Structure (Panels & Tabs)
+
+Wrap your controls in **Panels** to create collapsible sections in the sidebar.
+
+**Panel Properties:**
+- `title` (string): **Required.** Panel heading.
+- `properties` (array): **Required.** Array of controls or control rows.
+- `group` (string): Sidebar tab where panel appears. Options:
+  - `"settings"` (default) - Settings tab
+  - `"styles"` - Styles tab
+  - `"advanced"` - Advanced tab
+  - `"layered-styles"` - Layered Styles tab
+  - Other WordPress panel groups: `"post"`, `"background"`, `"border"`, `"color"`, `"dimensions"`, `"effects"`, `"filter"`, `"list"`, `"position"`, `"typography"`
+- `initialOpen` (boolean): Whether panel starts expanded. Default: `false`.
+- `condition` (array): Show/hide the entire panel conditionally.
+- `position` (number): Panel display order.
+- `raw` (boolean): Render panel without wrapper (advanced).
+- `identifier` (any): Custom identifier for the panel.
+
+**Example:**
+
+```json
+{
+  "title": "Advanced Options",
+  "group": "advanced",
+  "initialOpen": false,
+  "properties": [
+    { "name": "customCSS", "label": "Custom CSS", "control": "textarea" }
+  ]
+}
+```
+
+**Tab Structure:**
+
+Tabs are differentiated from panels by using `items` instead of `properties`
+
+You can also organize panels into tabs:
+
+```json
+{
+  "title": "Content Settings",
+  "group": "settings",
+  "items": [
+    {
+      "title": "Text",
+      "properties": [
+        { "name": "heading", "label": "Heading", "control": "text" }
+      ]
+    },
+    {
+      "title": "Media",
+      "properties": [
+        { "name": "image", "label": "Image", "control": "image" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+### 2. Layout (Rows)
+
+- **Single Control:** One control object per row.
+- **Multiple Controls:** Wrap controls in an array to display them side-by-side.
+
+**Example:**
+
+```json
+[
+  { "name": "width", "label": "Width", "control": "number" },
+  { "name": "height", "label": "Height", "control": "number" }
+]
+```
+
+---
+
+### 3. Conditions (Show/Hide Logic)
+
+Add a `condition` array to any control or panel to show/hide it based on other property values.
+
+**Condition Structure:**
+
+```json
+"condition": [
+  { "op": "==", "property": "fieldName", "value": "someValue" }
+]
+```
+
+**Available Operators:**
+- `==` and `===` - Equals (coercive and non-coercive comparison respectively)
+- `!=` and `!==` - Not equals (coercive and non-coercive comparison respectively)
+- `>`, `<`, `>=`, `<=` - Comparison operators
+- `empty` - Property is empty/undefined/falsy
+- `!empty` - Property has a truthy value
+- `in` - Value is in array or string
+- `!in` - Value is not in array or string
+- `contains` - Array/string contains value
+- `!contains` - Array/string does not contain value
+
+**Combiners:**
+- `and` - All conditions must be true (default when multiple conditions in array)
+- `or` - At least one condition must be true
+- `not` - Inverts the result
+- `nand` - Not all conditions are true
+- `nor` - None of the conditions are true
+
+**Property Path Syntax:**
+- Simple property: `"propertyName"`
+- Nested property: `"parent.child"`
+- Array index: `"items.0.name"`
+- Relative to parent: `"@parent.siblingProperty"`
+- From root: `"@root.topLevelProperty"`
+- Block attributes: `"@block.attributes.anchor"`, `"@block.name"`, `"@block.className"`
+- Parent block: `"@block.name(1)"` (1 = immediate parent, 2 = grandparent, etc.)
+
+**Examples:**
+
+```json
+// Show only if another field is not empty
+"condition": [{ "op": "!empty", "property": "headline" }]
+
+// Show only if layout is "grid"
+"condition": [{ "op": "==", "property": "layout", "value": "grid" }]
+
+// Multiple conditions (AND logic - all must be true)
+"condition": [
+  { "op": "==", "property": "showImage", "value": true },
+  { "op": "!empty", "property": "imageUrl" }
+]
+
+// OR logic (at least one must be true)
+"condition": [
+  { "op": "or", "conditions": [
+    { "op": "==", "property": "type", "value": "featured" },
+    { "op": "==", "property": "type", "value": "highlighted" }
+  ]}
+]
+
+// Complex nested conditions
+"condition": [
+  { "op": "and", "conditions": [
+    { "op": "==", "property": "enableFeature", "value": true },
+    { "op": "or", "conditions": [
+      { "op": "==", "property": "mode", "value": "advanced" },
+      { "op": "==", "property": "userRole", "value": "admin" }
+    ]}
+  ]}
+]
+
+// Check parent block type
+"condition": [
+  { "op": "==", "property": "@block.name(1)", "value": "core/group" }
+]
+```
+
+---
+
+### 4. Option Sources (Dynamic Options)
+
+For `select`, `radio`, `colorPalette`, and `toggleGroup` controls, you can use shorthand strings to load dynamic options:
+
+#### Source Syntax
+- The source syntax is based off of the URI syntax and uses custom protocols. The two built-in protocols are `select` and `settings`; however, new ones can be registered via filters.
+
+##### The `select` Protocol
+**Notes:**
+- This protocol is used to extract values from a Redux data store that has a `get` or `resolve` function that takes a `string` and `Record<string, any>` as its parameters.
+- At present, that means using the `plaudit/simple-gutenberg-apis` store.
+  - The `plaudit/simple-gutenberg-apis` store provides access to js-defined endpoints that can be sent to the server.
+  - While new endpoint definitions can only be registered via JavaScript, they can be referenced from JSON.
+- To reference an endpoint from JSON, use the following syntax: `select://endpoint@store` or, if the endpoint expects the block's attributes, `select://endpoint@store?attributes`
+- To get a list of registered endpoints, open the block editor in your browser and run `wp.data.select('plaudit/simple-gutenberg-apis').registeredEndpoints()` in the browser console
+  - To test one of the registered endpoints, run `(await wp.data.select('plaudit/simple-gutenberg-apis').resolve('endpoint.name.here'))` in the same context
+
+
+##### The `settings` Protocol
+**Notes:**
+- This protocol is used to get values from the theme.json file
+- The returned values are effected by the current block (this is to allow for block-specific values, most-commonly font sizes and colors)
+- The overall structure is: `settings://dot.separated.path.to.value?<optional parameters>`
+  - Example: `settings://plaudit.markerColor`
+- The `value-pattern` parameter can be used to transform the value returned from the theme.json file
+  - The pattern MUST contain `$slug` (`$slug` is used to mark where the value returned from theme.json should be inserted)
+  - For example, `?value-pattern=var(--wp-preset-color-$slug)` can be used to transform a list of preset colors into valid CSS values
+- If desired, a CSS inherit option can be added to the list by adding `with-inherit` to the parameters list (this will only show up if the value source has been defined as supporting it)
+
+**Examples:**
+
+```json
+{ 
+  "name": "textColor", 
+  "label": "Text Color", 
+  "control": "colorPalette",
+  "options": "settings://color.palette"
+}
+```
+
+```json
+{
+	"name": "dimensions",
+	"label": "Aspect Ratio",
+	"control": "select",
+	"options": "settings://dimensions.aspectRatios"
+}
+```
+
+---
+
+## 🔧 Advanced Features
+
+### Style Properties
+
+This feature is intended for setting CSS custom variables based on a block's properties.
+
+You can bind string or number properties directly to CSS properties using the `styleProperty` field. This automatically applies the value as an inline style on the block wrapper.
+
+**Notes:**
+- Only works for root-level properties (not those nested in arrays or objects)
+- The value is not validated for compatibility with the CSS property or CSS syntax in general, so care must be taken to avoid issues
+- A CSS class `has-{kebab-case-property-name}` is automatically added
+
+**Example:**
+
+```json
+{
+  "name": "customPadding",
+  "label": "Custom Padding",
+  "control": "text",
+  "styleProperty": "--custom-padding",
+  "placeholder": "e.g., 20px 40px"
+}
+```
+
+When the user enters `"20px 40px"`, the block wrapper will receive:
+- `style="--custom-padding: 20px 40px"`
+- `class="has-custom-padding"`
+
+---
+
+### Validators & Transformers
+
+**Note:** These features are only available when using TypeScript/React to define properties programmatically.
+
+**Validator Function:**
+
+```typescript
+{
+  name: "email",
+  label: "Email Address",
+  control: "text",
+  validator: (value: string | undefined) => {
+    if (!value) return null;
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) 
+      ? null 
+      : "Please enter a valid email address";
+  }
+}
+```
+
+**Transformer Object:**
+
+```typescript
+{
+  name: "price",
+  label: "Price",
+  control: "number",
+  transformer: {
+    to: (input: unknown) => {
+      // Convert stored value to display value
+      return typeof input === 'number' ? input / 100 : undefined;
+    },
+    from: (value: number | undefined) => {
+      // Convert display value to stored value (cents)
+      return value !== undefined ? Math.round(value * 100) : undefined;
+    }
+  }
+}
+```
+
+---
+
+## Tips & Best Practices
+
+1. **Add Help Text:** Use the `help` property to guide users, especially for complex controls.
+
+2. **Group Related Controls:** Use panels to organize controls logically.
+
+3. **Leverage Conditions:** Hide irrelevant controls to keep the UI clean and focused.
+
+4. **Validate Inputs:** Use `min`, `max`, `required`, and `step` to prevent invalid data.
+
+5. **Use Appropriate Control Types:** Choose the control that best matches your data:
+   - Use `toggle` for boolean flags
+   - Use `toggleGroup` for 2-5 mutually exclusive options
+   - Use `select` for 6+ options or when searchability is needed
+   - Use `radio` when you need to show all options at once
+
+6. **Default Values:** Always provide sensible defaults to improve the user experience.
+
+7. **Required Fields:** Mark critical fields as `required: true` to ensure data completeness.
+
+8. **Placeholder Text:** Use placeholders to show example values or formatting hints.
+
+9. **Nested Properties:** Use `group` controls to create logical hierarchies in your data.
+
+10. **Performance:** For lists with many items, consider setting `max` limits to prevent performance issues.
+
+11. **Accessibility:** Labels are required for all controls to ensure screen reader compatibility.
+
+12. **Testing:** Always test your controls with various data states (empty, partial, complete, invalid).