@preset.nz/facets 0.1.1 → 0.1.3

package/README.md

@@ -14,6 +14,10 @@ switch statement over your types.
 Built for image and map editors, where the same panel has to render a layer, a
 filter, a document or a tool depending on what is selected.
 
+The playground at [facets.preset.nz](https://facets.preset.nz) shows the field
+kinds, the schema as JSON, and the panel it draws, side by side. Its source is
+in `playground/`.
+
 ---
 
 ## Installing
@@ -159,7 +163,7 @@ keep the mapping inside `read`, where your domain types are still in scope.
 
 ## Field kinds
 
-Nine ship built in.
+Eleven ship built in: nine that hold a value, and two that only show something.
 
 | Kind | Value | Notes |
 |---|---|---|
@@ -172,6 +176,36 @@ Nine ship built in.
 | `color` | hex string | `presets`; shows a swatch |
 | `vector` | number array | N scalars in one row — Houdini's `float3` / `int2`. `components` sets arity and per-slot label, suffix and range |
 | `file` | `{ name }` | display only |
+| `separator` | none | a horizontal rule, with `label` as an optional caption. No `path` |
+| `label` | none | static text: a hint or a sub-heading. The text is `label`. No `path` |
+
+Groups take `collapsible: true` to fold under their title, and
+`defaultCollapsed: true` to start folded. The open or closed state belongs to
+the group, so it resets when the panel remounts.
+
+---
+
+## JSON Schema
+
+A schema for editors and agents is published at
+`https://facets.preset.nz/schema/v0.1.json`, and ships in the package as
+`@preset.nz/facets/schema/v0.1.json`. Point a JSON file at it:
+
+```json
+{
+  "$schema": "https://facets.preset.nz/schema/v0.1.json",
+  "version": 1,
+  "groups": []
+}
+```
+
+Built-in kinds are checked strictly: a misspelt prop or a missing `path` is an
+error. Any other kind passes as a custom kind, so a misspelt *kind* is not
+caught here; the panel logs a warning and skips the field. `optionsProvider` is
+code, so it has no JSON form.
+
+One file covers every 0.1.x release. Patches may add kinds and props to it,
+never remove or tighten them.
 
 ---
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@preset.nz/facets",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Schema-as-data property/inspector panels for React: FieldDef schemas, a scope registry, an open field-renderer registry, and a generic PropertyPanel.",
   "license": "MIT",
+  "homepage": "https://facets.preset.nz",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/preset-nz/facets.git"
@@ -10,10 +11,12 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./schema/v0.1.json": "./schema/v0.1.json"
   },
   "files": [
-    "src"
+    "src",
+    "schema"
   ],
   "publishConfig": {
     "access": "public"
@@ -23,6 +26,7 @@
   },
   "devDependencies": {
     "@types/react": "^19",
+    "ajv": "^8.20.0",
     "typescript": "^5.8.3"
   }
 }

package/schema/v0.1.json

@@ -0,0 +1,801 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://facets.preset.nz/schema/v0.1.json",
+  "title": "@preset.nz/facets PropertySchema, 0.1",
+  "description": "An inspector panel as data: groups of rows of fields. Valid for every 0.1.x release; later 0.1 patches only add kinds and props. Playground: https://facets.preset.nz",
+  "type": "object",
+  "required": [
+    "version",
+    "groups"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "This file's URL, for editors."
+    },
+    "version": {
+      "type": "number",
+      "description": "The host's own version of this schema. Bump it when the shape changes."
+    },
+    "groups": {
+      "type": "array",
+      "description": "Rendered top to bottom, with a rule between groups.",
+      "items": {
+        "$ref": "#/definitions/group"
+      }
+    }
+  },
+  "definitions": {
+    "group": {
+      "type": "object",
+      "required": [
+        "id",
+        "rows"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema."
+        },
+        "title": {
+          "type": "string",
+          "description": "The heading. Omit it to render the group without one."
+        },
+        "description": {
+          "type": "string",
+          "description": "A line under the title."
+        },
+        "collapsible": {
+          "type": "boolean",
+          "description": "Fold under the title. Needs a title."
+        },
+        "defaultCollapsed": {
+          "type": "boolean",
+          "description": "Start folded."
+        },
+        "rows": {
+          "type": "array",
+          "description": "A field is a full-width row; an array of fields is one row laid out as a grid (usually two).",
+          "items": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/field"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/definitions/field"
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "disabledWhen": {
+      "type": "object",
+      "description": "Greys the field out depending on another field's value. Set one operator; if several are set, the first of equals, notEquals, in, notIn wins.",
+      "required": [
+        "path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "The field value to watch, by path."
+        },
+        "equals": {
+          "description": "Disabled when the value equals this."
+        },
+        "notEquals": {
+          "description": "Disabled unless the value equals this."
+        },
+        "in": {
+          "type": "array",
+          "description": "Disabled when the value is one of these."
+        },
+        "notIn": {
+          "type": "array",
+          "description": "Disabled unless the value is one of these."
+        }
+      }
+    },
+    "selectOption": {
+      "type": "object",
+      "required": [
+        "value",
+        "label"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "string",
+          "description": "Stored in the value record."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown to the user."
+        }
+      }
+    },
+    "vectorComponent": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Shown above the slot."
+        },
+        "suffix": {
+          "type": "string",
+          "description": "Unit after the number, e.g. px or °."
+        },
+        "min": {
+          "type": "number",
+          "description": "Lower bound."
+        },
+        "max": {
+          "type": "number",
+          "description": "Upper bound."
+        },
+        "step": {
+          "type": "number",
+          "description": "Increment. Default 1."
+        }
+      }
+    },
+    "field": {
+      "type": "object",
+      "description": "One field. kind picks the renderer: a built-in kind is checked strictly; any other kind is a custom kind registered by the host, which may carry extra props.",
+      "required": [
+        "kind",
+        "id"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "The renderer to use. Built in: text, textarea, number, slider, select, color, checkbox, file, vector, separator, label. Anything else must be registered by the host with registerFieldRenderer().",
+          "examples": [
+            "text",
+            "textarea",
+            "number",
+            "slider",
+            "select",
+            "color",
+            "checkbox",
+            "file",
+            "vector",
+            "separator",
+            "label"
+          ]
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "text"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/text"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "textarea"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/textarea"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "number"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/number"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "slider"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/slider"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "select"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/select"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "color"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/color"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "checkbox"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/checkbox"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "file"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/file"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "vector"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/vector"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "separator"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/separator"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "const": "label"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/label"
+          }
+        },
+        {
+          "if": {
+            "required": [
+              "kind"
+            ],
+            "properties": {
+              "kind": {
+                "not": {
+                  "enum": [
+                    "text",
+                    "textarea",
+                    "number",
+                    "slider",
+                    "select",
+                    "color",
+                    "checkbox",
+                    "file",
+                    "vector",
+                    "separator",
+                    "label"
+                  ]
+                }
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/custom"
+          }
+        }
+      ]
+    },
+    "text": {
+      "type": "object",
+      "description": "A single line of text. Value: string.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "text"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Shown while empty."
+        }
+      },
+      "additionalProperties": false
+    },
+    "textarea": {
+      "type": "object",
+      "description": "Several lines of text. Value: string.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "textarea"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Shown while empty."
+        },
+        "rows": {
+          "type": "number",
+          "description": "Visible lines. Default 3."
+        }
+      },
+      "additionalProperties": false
+    },
+    "number": {
+      "type": "object",
+      "description": "A number typed into a box. Value: number.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "number"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "min": {
+          "type": "number",
+          "description": "Lower bound."
+        },
+        "max": {
+          "type": "number",
+          "description": "Upper bound."
+        },
+        "step": {
+          "type": "number",
+          "description": "Increment. Default 1."
+        }
+      },
+      "additionalProperties": false
+    },
+    "slider": {
+      "type": "object",
+      "description": "A number dragged along a range. Value: number.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "slider"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "min": {
+          "type": "number",
+          "description": "Lower bound."
+        },
+        "max": {
+          "type": "number",
+          "description": "Upper bound."
+        },
+        "step": {
+          "type": "number",
+          "description": "Increment. Default 1."
+        }
+      },
+      "additionalProperties": false
+    },
+    "select": {
+      "type": "object",
+      "description": "One choice from a list. Value: the chosen option's value (string). Options can also come from optionsProvider(ctx), a function, which is set in code and has no JSON form.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "select"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "options": {
+          "type": "array",
+          "description": "The choices.",
+          "items": {
+            "$ref": "#/definitions/selectOption"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "color": {
+      "type": "object",
+      "description": "A colour as a hex string, e.g. \"#2b7c76\". Value: string.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "color"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "presets": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Hex strings. Declared in 0.1; the built-in renderer does not draw them."
+        }
+      },
+      "additionalProperties": false
+    },
+    "checkbox": {
+      "type": "object",
+      "description": "On or off. Value: boolean.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "checkbox"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        }
+      },
+      "additionalProperties": false
+    },
+    "file": {
+      "type": "object",
+      "description": "Shows a file's name; always read-only. Value: { \"name\": string }.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "const": "file"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "accept": {
+          "type": "string",
+          "description": "File types, as on <input>. Declared in 0.1; the built-in renderer ignores it."
+        },
+        "helperText": {
+          "type": "string",
+          "description": "A hint. Declared in 0.1; the built-in renderer does not draw it."
+        }
+      },
+      "additionalProperties": false
+    },
+    "vector": {
+      "type": "object",
+      "description": "Several numbers in one row: position, size, RGB, LCh. Value: number[], one per component.",
+      "required": [
+        "kind",
+        "id",
+        "path",
+        "components"
+      ],
+      "properties": {
+        "kind": {
+          "const": "vector"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        },
+        "components": {
+          "type": "array",
+          "description": "One entry per slot; sets the arity.",
+          "items": {
+            "$ref": "#/definitions/vectorComponent"
+          }
+        },
+        "integer": {
+          "type": "boolean",
+          "description": "Truncate to whole numbers."
+        },
+        "precision": {
+          "type": "number",
+          "description": "Decimals shown when read-only."
+        }
+      },
+      "additionalProperties": false
+    },
+    "separator": {
+      "type": "object",
+      "description": "A horizontal rule between rows, with label as an optional caption. Holds no value, so it has no path.",
+      "required": [
+        "kind",
+        "id"
+      ],
+      "properties": {
+        "kind": {
+          "const": "separator"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        }
+      },
+      "additionalProperties": false
+    },
+    "label": {
+      "type": "object",
+      "description": "Static text: a hint, a note, a sub-heading. The text is label. Holds no value, so it has no path.",
+      "required": [
+        "kind",
+        "id",
+        "label"
+      ],
+      "properties": {
+        "kind": {
+          "const": "label"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        }
+      },
+      "additionalProperties": false
+    },
+    "custom": {
+      "type": "object",
+      "description": "A custom kind. The host's renderer decides which extra props it reads.",
+      "required": [
+        "kind",
+        "id",
+        "path"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique within the schema. Keys the field in the panel."
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown above the field. Defaults to id."
+        },
+        "path": {
+          "type": "string",
+          "description": "A key into the record the scope's read() returns. A flat lookup, not a nested traversal: \"transform.x\" is one key."
+        },
+        "disabledWhen": {
+          "$ref": "#/definitions/disabledWhen"
+        }
+      }
+    }
+  }
+}

package/src/field-renderers.tsx

@@ -14,6 +14,7 @@ import {
   SelectValue,
 } from "@/components/ui/select"
 import { Checkbox } from "@/components/ui/checkbox"
+import { Separator } from "@/components/ui/separator"
 import { registerFieldRenderer } from "./registry"
 import type {
   CheckboxFieldDef,
@@ -26,6 +27,8 @@ import type {
   TextFieldDef,
   TextareaFieldDef,
   FileFieldDef,
+  LabelFieldDef,
+  SeparatorFieldDef,
   VectorFieldDef,
 } from "./types"
 
@@ -226,7 +229,9 @@ const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
         disabled={disabled}
       >
         <SelectTrigger>
-          <SelectValue />
+          {/* Children, not the primitive's own lookup: Base UI's Value shows
+              the raw value unless it's told the label. */}
+          <SelectValue>{matched ? matched.label : current}</SelectValue>
         </SelectTrigger>
         <SelectContent>
           {options.map((o) => (
@@ -425,7 +430,39 @@ const VectorRenderer: FieldRenderer<VectorFieldDef> = ({
   )
 }
 
+const SeparatorRenderer: FieldRenderer<SeparatorFieldDef> = ({ field }) =>
+  field.label ? (
+    <div className="my-1 flex items-center gap-2">
+      <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
+        {field.label}
+      </span>
+      <Separator className="flex-1" />
+    </div>
+  ) : (
+    <Separator className="my-1" />
+  )
+
+// The same in every mode: there is nothing to edit. Greys out under
+// disabledWhen so a hint can follow the field it describes.
+const LabelRenderer: FieldRenderer<LabelFieldDef> = ({ field, disabled }) => (
+  <p
+    className={
+      "text-xs text-muted-foreground" + (disabled ? " opacity-50" : "")
+    }
+  >
+    {field.label}
+  </p>
+)
+
 export function registerBuiltinRenderers(): void {
+  registerFieldRenderer(
+    "separator",
+    SeparatorRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "label",
+    LabelRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
   registerFieldRenderer(
     "text",
     TextRenderer as FieldRenderer<import("./types").FieldDef>,

package/src/panel.tsx

@@ -1,4 +1,4 @@
-import { useMemo } from "react"
+import { useId, useMemo, useState } from "react"
 import { Separator } from "@/components/ui/separator"
 import { getFieldRenderer, getScope } from "./registry"
 import type {
@@ -69,23 +69,54 @@ function PropertyGroup({
   onChange?: (path: string, val: unknown) => void
   isLast: boolean
 }) {
+  // Collapsing needs a title to click. Open or closed is the group's own
+  // state; a host that wants it remembered across selections keys the panel.
+  const collapsible = Boolean(group.collapsible && group.title)
+  const [collapsed, setCollapsed] = useState(
+    collapsible && Boolean(group.defaultCollapsed),
+  )
+  const bodyId = useId()
+  const titleClass =
+    "text-[11px] font-semibold uppercase tracking-wider text-muted-foreground"
+
   return (
     <section className="flex flex-col gap-3 px-3 py-3">
       {(group.title || group.description) && (
         <header>
-          {group.title && (
-            <h3 className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
-              {group.title}
-            </h3>
-          )}
-          {group.description && (
+          {group.title &&
+            (collapsible ? (
+              <h3 className={titleClass}>
+                <button
+                  type="button"
+                  aria-expanded={!collapsed}
+                  aria-controls={bodyId}
+                  onClick={() => setCollapsed((c) => !c)}
+                  className="-mx-1 flex w-[calc(100%+0.5rem)] items-center gap-1 px-1 text-left uppercase hover:text-foreground"
+                >
+                  <svg
+                    aria-hidden
+                    viewBox="0 0 16 16"
+                    className={
+                      "size-3 shrink-0 transition-transform " +
+                      (collapsed ? "-rotate-90" : "")
+                    }
+                  >
+                    <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="1.5" />
+                  </svg>
+                  {group.title}
+                </button>
+              </h3>
+            ) : (
+              <h3 className={titleClass}>{group.title}</h3>
+            ))}
+          {group.description && !(collapsible && collapsed) && (
             <p className="mt-1 text-xs text-muted-foreground">
               {group.description}
             </p>
           )}
         </header>
       )}
-      <div className="flex flex-col gap-3">
+      <div id={bodyId} hidden={collapsible && collapsed} className="flex flex-col gap-3">
         {group.rows.map((row, idx) => {
           const fields = Array.isArray(row) ? row : [row]
           return (
@@ -142,11 +173,14 @@ function FieldSlot({
     return false
   })()
 
+  // Display-only kinds (separator, label) have no path: no value, no writes.
+  const path = "path" in field ? field.path : undefined
   return renderer({
     field,
-    value: values[field.path],
+    value: path === undefined ? undefined : values[path],
     disabled,
-    onChange: onChange ? (val) => onChange(field.path, val) : undefined,
+    onChange:
+      onChange && path !== undefined ? (val) => onChange(path, val) : undefined,
     ctx,
   })
 }

package/src/types.ts

@@ -9,6 +9,9 @@ export type BuiltinFieldKind =
   | "color"
   | "checkbox"
   | "file"
+  | "vector"
+  | "separator"
+  | "label"
 
 export interface BaseField {
   kind: string
@@ -109,6 +112,28 @@ export interface FileFieldDef extends BaseField {
   helperText?: string
 }
 
+// Display-only rows: they show something but hold no value, so they have no
+// `path`. Houdini's Separator and Label parameter types.
+
+/**
+ * A horizontal rule between rows, with an optional caption. Every kind keeps
+ * `label` so hosts can read `field.label` on any FieldDef without narrowing.
+ */
+export interface SeparatorFieldDef {
+  kind: "separator"
+  id: string
+  label?: string
+  disabledWhen?: DisabledWhen
+}
+
+/** Static text: a hint, a note, a sub-heading. The text is `label`. */
+export interface LabelFieldDef {
+  kind: "label"
+  id: string
+  label: string
+  disabledWhen?: DisabledWhen
+}
+
 export type BuiltinFieldDef =
   | SelectFieldDef
   | ColorFieldDef
@@ -119,6 +144,8 @@ export type BuiltinFieldDef =
   | CheckboxFieldDef
   | FileFieldDef
   | VectorFieldDef
+  | SeparatorFieldDef
+  | LabelFieldDef
 
 export type FieldDef = BuiltinFieldDef | CustomFieldDef