@preset.nz/facets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 preset.nz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# @preset.nz/facets
+
+Inspector panels for React, defined as data.
+
+You describe a panel as a plain object — groups of fields, each with a kind and a
+path. `facets` looks up a renderer per kind, reads the values, and draws the
+panel. The panel itself knows nothing about your domain, so it never grows a
+switch statement over your types.
+
+```tsx
+<PropertyPanel scopeKey={selection.kind} selection={selection} ctx={ctx} />
+```
+
+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.
+
+---
+
+## Installing
+
+```sh
+pnpm add @preset.nz/facets
+```
+
+React 19 is a peer dependency.
+
+**This package ships unbuilt TypeScript.** There is no compiled output and no
+build step — your bundler and `tsc` compile it along with your own source. That
+is deliberate, and it is what makes the next section possible.
+
+### You supply the primitives
+
+The built-in renderers do not implement form controls. They import yours, from
+the conventional shadcn path, and your bundler's `@` alias resolves it:
+
+| Import | Must export |
+|---|---|
+| `@/components/ui/input` | `Input` |
+| `@/components/ui/label` | `Label` |
+| `@/components/ui/checkbox` | `Checkbox` |
+| `@/components/ui/separator` | `Separator` |
+| `@/components/ui/select` | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem` |
+
+So you need an `@/*` alias pointing at your `src/`, those five modules present,
+and Tailwind with shadcn's theme tokens (`muted-foreground`, `border` and
+friends are used throughout).
+
+The upside is that `facets` inherits whatever primitive library you already
+chose — Base UI, Radix, or your own — instead of dragging in a second one and
+making your panels look foreign inside your own app.
+
+---
+
+## A worked example
+
+Register the built-in renderers once at startup, then register a scope per kind
+of thing you can select.
+
+```tsx
+import {
+  PropertyPanel,
+  registerBuiltinRenderers,
+  registerScope,
+  type PropertySchema,
+} from "@preset.nz/facets";
+
+registerBuiltinRenderers();
+
+const BLUR: PropertySchema = {
+  version: 1,
+  groups: [
+    {
+      id: "blur",
+      title: "Gaussian blur",
+      rows: [
+        { kind: "slider", id: "radius", label: "Radius", path: "radius", min: 0, max: 64, step: 1 },
+        { kind: "checkbox", id: "clampEdges", label: "Clamp edges", path: "clampEdges" },
+        [
+          { kind: "color", id: "tint", label: "Tint", path: "tint" },
+          { kind: "number", id: "amount", label: "Amount", path: "amount", min: 0, max: 1, step: 0.05 },
+        ],
+      ],
+    },
+  ],
+};
+
+registerScope("blur", {
+  schema: BLUR,
+  read: (sel: { id: string }, ctx) => ctx.getFilter(sel.id).params,
+  write: (path, value, sel, ctx) => ctx.setFilterParam(sel.id, path, value),
+});
+```
+
+Then mount one panel for everything:
+
+```tsx
+<PropertyPanel
+  scopeKey={selection.kind}
+  selection={selection}
+  ctx={appApi}
+  emptyState={<p>Nothing selected</p>}
+/>
+```
+
+Select a blur and the blur panel appears. Add a new filter type later by
+registering another scope — the panel does not change.
+
+A row holding an array renders as a two-column grid. Everything else is full
+width. That is the whole layout system, on purpose.
+
+---
+
+## The four pieces
+
+**`FieldDef`** — one field, as data. `kind` picks the renderer, `path` picks the
+value, `label` defaults to `id`.
+
+**`Scope`** — a schema bundled with its own `read` and, optionally, `write`.
+This is the important one. The panel never learns how to fetch or store your
+values; each scope brings its own. Omit `write` and the scope is read-only.
+
+```ts
+interface Scope<S, V> {
+  schema: PropertySchema;
+  read: (selection: S, ctx: ScopeContext) => V;
+  write?: (path: string, value: unknown, selection: S, ctx: ScopeContext) => void;
+}
+```
+
+**The renderer registry** — `kind` to React component, open for extension.
+Built-ins register through the same call you would use, with no special casing.
+
+**`PropertyPanel`** — looks up the scope, calls `read`, walks the groups, hands
+each field to its renderer. Props: `scopeKey`, `selection`, `ctx`, plus optional
+`readOnly` and `emptyState`.
+
+`ctx` is yours. The package treats it as opaque and passes it through to every
+`read`, `write`, renderer and options provider. Put your app's API in it.
+
+### How `path` resolves
+
+`read()` returns a record, and `path` is a **key into that record** — a flat
+lookup, not a nested traversal. Return a flat object shaped for the panel and
+keep the mapping inside `read`, where your domain types are still in scope.
+
+---
+
+## Field kinds
+
+Nine ship built in.
+
+| Kind | Value | Notes |
+|---|---|---|
+| `text` | string | `placeholder` |
+| `textarea` | string | `placeholder`, `rows` |
+| `number` | number | `min`, `max`, `step` |
+| `slider` | number | same, rendered as a slider |
+| `checkbox` | boolean | |
+| `select` | string | `options`, or `optionsProvider(ctx)` for dynamic lists |
+| `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 |
+
+---
+
+## Read-only
+
+Omit `write`, or pass `readOnly`, and no change handler reaches the renderers.
+They then render the **formatted value as text**, not a disabled input. A
+disabled `<input value="1024">` reads as broken; a plain `1024` reads as
+information. Empty values render as an em dash.
+
+Disabled controls are reserved for `disabledWhen`, which is a condition inside
+an otherwise editable panel:
+
+```ts
+{ kind: "number", id: "radius", path: "radius",
+  disabledWhen: { path: "mode", equals: "auto" } }
+```
+
+The condition reads one other field's value. Set one operator:
+
+- `equals` / `notEquals` — compare against a single value.
+- `in` / `notIn` — compare against a list, e.g. a param only some enum choices
+  use: `disabledWhen: { path: "pattern", notIn: ["dashes", "stipple"] }`.
+
+If several are set, the first in that order wins.
+
+---
+
+## Custom field kinds
+
+Register any `kind` string and the panel will route to it. This is how a panel
+grows a palette strip, a histogram or a segmentation preview without the package
+knowing those exist.
+
+```tsx
+registerFieldRenderer("palette-swatches", ({ field, value, onChange, ctx }) => (
+  <SwatchStrip colours={value as string[]} onPick={onChange} />
+));
+```
+
+A field whose kind is not built in may carry any extra props it likes; the
+renderer reads what it needs. **The type system will not check those props**, so
+document them next to the renderer.
+
+An unregistered kind logs a warning and renders nothing. It does not throw, and
+it does not take the rest of the panel down with it.
+
+---
+
+## Notes
+
+- **Registration is explicit.** `registerBuiltinRenderers()` is a call, not an
+  import side effect, and the package declares `sideEffects: false`. Call it
+  before rendering a panel.
+- **Failures stay local.** A throwing `read` is caught and logged; an unknown
+  scope renders `emptyState`; an unknown kind skips that field.
+- **Schemas are serialisable.** Keep them that way — no closures in a
+  `FieldDef` beyond `optionsProvider`. It keeps schemas versionable and lets them
+  cross a plugin boundary later.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@preset.nz/facets",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/preset-nz/facets.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5.8.3"
+  }
+}

package/src/field-renderers.tsx

@@ -0,0 +1,470 @@
+/* eslint-disable react-refresh/only-export-components --
+ * This module ships the built-in field renderers as small co-located
+ * components plus a single `registerBuiltinRenderers` entry point. Splitting
+ * each renderer into its own file would be over-organisation for code that
+ * never hot-reloads in isolation. */
+import { useMemo } from "react"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+import { Checkbox } from "@/components/ui/checkbox"
+import { registerFieldRenderer } from "./registry"
+import type {
+  CheckboxFieldDef,
+  ColorFieldDef,
+  FieldRenderer,
+  FieldRendererProps,
+  NumberFieldDef,
+  SelectFieldDef,
+  SliderFieldDef,
+  TextFieldDef,
+  TextareaFieldDef,
+  FileFieldDef,
+  VectorFieldDef,
+} from "./types"
+
+function ReadOnlyText({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-8 px-0 py-1 text-xs text-foreground tabular-nums break-all">
+      {children}
+    </div>
+  )
+}
+
+function Empty() {
+  return <span className="text-muted-foreground">—</span>
+}
+
+function FieldShell({
+  label,
+  children,
+}: {
+  label?: string
+  children: React.ReactNode
+}) {
+  return (
+    <div className="flex flex-col gap-1">
+      {label && (
+        <Label className="text-[11px] font-medium text-muted-foreground tracking-wide">
+          {label}
+        </Label>
+      )}
+      {children}
+    </div>
+  )
+}
+
+function formatPrimitive(value: unknown): string {
+  if (value == null || value === "") return ""
+  if (typeof value === "boolean") return value ? "Yes" : "No"
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === "object") return JSON.stringify(value)
+  return String(value)
+}
+
+const TextRenderer: FieldRenderer<TextFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const display = formatPrimitive(value)
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      {onChange ? (
+        <Input
+          aria-label={field.label ?? field.id}
+          value={display}
+          placeholder={field.placeholder}
+          disabled={disabled}
+          onChange={(e) => onChange(e.target.value)}
+        />
+      ) : display ? (
+        <ReadOnlyText>{display}</ReadOnlyText>
+      ) : (
+        <ReadOnlyText>
+          <Empty />
+        </ReadOnlyText>
+      )}
+    </FieldShell>
+  )
+}
+
+const TextareaRenderer: FieldRenderer<TextareaFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const display = formatPrimitive(value)
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      {onChange ? (
+        <textarea
+          aria-label={field.label ?? field.id}
+          value={display}
+          rows={field.rows ?? 3}
+          disabled={disabled}
+          placeholder={field.placeholder}
+          onChange={(e) => onChange(e.target.value)}
+          className="w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-xs outline-none focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:opacity-50"
+        />
+      ) : display ? (
+        <ReadOnlyText>
+          <span className="whitespace-pre-wrap">{display}</span>
+        </ReadOnlyText>
+      ) : (
+        <ReadOnlyText>
+          <Empty />
+        </ReadOnlyText>
+      )}
+    </FieldShell>
+  )
+}
+
+const NumberRenderer: FieldRenderer<NumberFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const num =
+    typeof value === "number"
+      ? value
+      : value != null && value !== ""
+      ? Number(value)
+      : null
+  const display =
+    num != null && Number.isFinite(num) ? num.toLocaleString() : ""
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      {onChange ? (
+        <Input
+          type="number"
+          aria-label={field.label ?? field.id}
+          value={num != null && Number.isFinite(num) ? String(num) : ""}
+          min={field.min}
+          max={field.max}
+          step={field.step ?? 1}
+          disabled={disabled}
+          onChange={(e) => onChange(Number(e.target.value))}
+        />
+      ) : display ? (
+        <ReadOnlyText>{display}</ReadOnlyText>
+      ) : (
+        <ReadOnlyText>
+          <Empty />
+        </ReadOnlyText>
+      )}
+    </FieldShell>
+  )
+}
+
+const SliderRenderer: FieldRenderer<SliderFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const num = typeof value === "number" ? value : Number(value ?? 0)
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      {onChange ? (
+        <input
+          type="range"
+          aria-label={field.label ?? field.id}
+          value={Number.isFinite(num) ? num : (field.min ?? 0)}
+          min={field.min}
+          max={field.max}
+          step={field.step ?? 1}
+          disabled={disabled}
+          onChange={(e) => onChange(Number(e.target.value))}
+          className="w-full"
+        />
+      ) : (
+        <ReadOnlyText>
+          {Number.isFinite(num) ? num.toLocaleString() : <Empty />}
+        </ReadOnlyText>
+      )}
+    </FieldShell>
+  )
+}
+
+const SelectRenderer: FieldRenderer<SelectFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+  ctx,
+}) => {
+  const options = useMemo(
+    () => (field.optionsProvider ? field.optionsProvider(ctx) : (field.options ?? [])),
+    [field, ctx],
+  )
+  const current = value == null ? "" : String(value)
+  const matched = options.find((o) => o.value === current)
+  if (!onChange) {
+    return (
+      <FieldShell label={field.label ?? field.id}>
+        <ReadOnlyText>
+          {matched ? matched.label : current ? current : <Empty />}
+        </ReadOnlyText>
+      </FieldShell>
+    )
+  }
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      <Select
+        value={current}
+        onValueChange={(v) => onChange(v)}
+        disabled={disabled}
+      >
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          {options.map((o) => (
+            <SelectItem key={o.value} value={o.value}>
+              {o.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </FieldShell>
+  )
+}
+
+const ColorRenderer: FieldRenderer<ColorFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const hex = typeof value === "string" && value.length > 0 ? value : null
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      <div className="flex items-center gap-2">
+        {hex ? (
+          <span
+            aria-hidden
+            className="inline-block size-4 shrink-0 border border-border"
+            style={{ backgroundColor: hex }}
+          />
+        ) : (
+          <span className="inline-block size-4 shrink-0 border border-dashed border-border" />
+        )}
+        {onChange ? (
+          <Input
+            type="text"
+            aria-label={field.label ?? field.id}
+            value={hex ?? ""}
+            disabled={disabled}
+            onChange={(e) => onChange(e.target.value)}
+            className="font-mono"
+          />
+        ) : (
+          <ReadOnlyText>
+            <span className="font-mono">{hex ?? <Empty />}</span>
+          </ReadOnlyText>
+        )}
+      </div>
+    </FieldShell>
+  )
+}
+
+const CheckboxRenderer: FieldRenderer<CheckboxFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const checked = Boolean(value)
+  if (!onChange) {
+    return (
+      <FieldShell label={field.label ?? field.id}>
+        <ReadOnlyText>{checked ? "Yes" : "No"}</ReadOnlyText>
+      </FieldShell>
+    )
+  }
+  return (
+    <div className="flex items-center gap-2">
+      <Checkbox
+        checked={checked}
+        disabled={disabled}
+        onCheckedChange={(next) => onChange(Boolean(next))}
+      />
+      {field.label && (
+        <Label className="text-xs text-foreground">{field.label}</Label>
+      )}
+    </div>
+  )
+}
+
+const FileRenderer: FieldRenderer<FileFieldDef> = ({
+  field,
+  value,
+}) => {
+  const asset = value as { name?: string } | null | undefined
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      <ReadOnlyText>
+        {asset?.name ? asset.name : <Empty />}
+      </ReadOnlyText>
+    </FieldShell>
+  )
+}
+
+function toNumberArray(value: unknown, arity: number): Array<number | null> {
+  if (!Array.isArray(value)) return Array.from({ length: arity }, () => null)
+  return Array.from({ length: arity }, (_, i) => {
+    const v = value[i]
+    if (v == null || v === "") return null
+    const n = Number(v)
+    return Number.isFinite(n) ? n : null
+  })
+}
+
+function formatComponent(
+  n: number | null,
+  integer: boolean,
+  precision?: number,
+): string {
+  if (n == null) return ""
+  if (integer) return Math.trunc(n).toLocaleString()
+  if (precision != null) return n.toFixed(precision)
+  return n.toLocaleString()
+}
+
+const VectorRenderer: FieldRenderer<VectorFieldDef> = ({
+  field,
+  value,
+  disabled,
+  onChange,
+}) => {
+  const arity = field.components.length
+  const values = toNumberArray(value, arity)
+  const isInt = Boolean(field.integer)
+
+  if (!onChange) {
+    return (
+      <FieldShell label={field.label ?? field.id}>
+        <div
+          className="grid gap-x-3 gap-y-1"
+          style={{ gridTemplateColumns: `repeat(${arity}, minmax(0, 1fr))` }}
+        >
+          {field.components.map((c, i) => (
+            <div key={i} className="flex flex-col gap-0.5 min-w-0">
+              {c.label && (
+                <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                  {c.label}
+                </span>
+              )}
+              <div className="text-xs text-foreground tabular-nums truncate">
+                {values[i] == null ? (
+                  <Empty />
+                ) : (
+                  <>
+                    {formatComponent(values[i], isInt, field.precision)}
+                    {c.suffix && (
+                      <span className="text-muted-foreground">{c.suffix}</span>
+                    )}
+                  </>
+                )}
+              </div>
+            </div>
+          ))}
+        </div>
+      </FieldShell>
+    )
+  }
+
+  return (
+    <FieldShell label={field.label ?? field.id}>
+      <div
+        className="grid gap-x-2"
+        style={{ gridTemplateColumns: `repeat(${arity}, minmax(0, 1fr))` }}
+      >
+        {field.components.map((c, i) => (
+          <div key={i} className="flex flex-col gap-0.5 min-w-0">
+            {c.label && (
+              <span className="text-[10px] uppercase tracking-wide text-muted-foreground">
+                {c.label}
+              </span>
+            )}
+            <Input
+              type="number"
+              aria-label={c.label ?? `${field.id}[${i}]`}
+              value={values[i] != null ? String(values[i]) : ""}
+              min={c.min}
+              max={c.max}
+              step={c.step ?? (isInt ? 1 : 0.01)}
+              disabled={disabled}
+              onChange={(e) => {
+                const raw = e.target.value
+                const parsed = raw === "" ? null : Number(raw)
+                const next = values.slice()
+                next[i] =
+                  parsed != null && Number.isFinite(parsed)
+                    ? isInt
+                      ? Math.trunc(parsed)
+                      : parsed
+                    : null
+                onChange(next)
+              }}
+            />
+          </div>
+        ))}
+      </div>
+    </FieldShell>
+  )
+}
+
+export function registerBuiltinRenderers(): void {
+  registerFieldRenderer(
+    "text",
+    TextRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "textarea",
+    TextareaRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "number",
+    NumberRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "slider",
+    SliderRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "select",
+    SelectRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "color",
+    ColorRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "checkbox",
+    CheckboxRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "file",
+    FileRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+  registerFieldRenderer(
+    "vector",
+    VectorRenderer as FieldRenderer<import("./types").FieldDef>,
+  )
+}
+
+export type {
+  FieldRenderer,
+  FieldRendererProps,
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./types"
+export {
+  registerScope,
+  unregisterScope,
+  getScope,
+  registerFieldRenderer,
+  getFieldRenderer,
+} from "./registry"
+export { PropertyPanel } from "./panel"
+export { registerBuiltinRenderers } from "./field-renderers"

package/src/panel.tsx

@@ -0,0 +1,152 @@
+import { useMemo } from "react"
+import { Separator } from "@/components/ui/separator"
+import { getFieldRenderer, getScope } from "./registry"
+import type {
+  FieldDef,
+  PropertyGroupDef,
+  ScopeContext,
+} from "./types"
+
+interface PropertyPanelProps {
+  scopeKey: string
+  selection: unknown
+  ctx: ScopeContext
+  readOnly?: boolean
+  emptyState?: React.ReactNode
+}
+
+export function PropertyPanel({
+  scopeKey,
+  selection,
+  ctx,
+  readOnly = false,
+  emptyState,
+}: PropertyPanelProps) {
+  const scope = getScope(scopeKey)
+
+  const values = useMemo(() => {
+    if (!scope) return {} as Record<string, unknown>
+    try {
+      return scope.read(selection, ctx) as Record<string, unknown>
+    } catch (e) {
+      console.error("[properties] scope read failed:", scopeKey, e)
+      return {} as Record<string, unknown>
+    }
+  }, [scope, scopeKey, selection, ctx])
+
+  if (!scope) return <>{emptyState ?? null}</>
+
+  const onChange = readOnly || !scope.write
+    ? undefined
+    : (path: string, val: unknown) => scope.write!(path, val, selection, ctx)
+
+  return (
+    <div className="flex flex-col">
+      {scope.schema.groups.map((group, idx) => (
+        <PropertyGroup
+          key={group.id}
+          group={group}
+          values={values}
+          ctx={ctx}
+          onChange={onChange}
+          isLast={idx === scope.schema.groups.length - 1}
+        />
+      ))}
+    </div>
+  )
+}
+
+function PropertyGroup({
+  group,
+  values,
+  ctx,
+  onChange,
+  isLast,
+}: {
+  group: PropertyGroupDef
+  values: Record<string, unknown>
+  ctx: ScopeContext
+  onChange?: (path: string, val: unknown) => void
+  isLast: boolean
+}) {
+  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 && (
+            <p className="mt-1 text-xs text-muted-foreground">
+              {group.description}
+            </p>
+          )}
+        </header>
+      )}
+      <div className="flex flex-col gap-3">
+        {group.rows.map((row, idx) => {
+          const fields = Array.isArray(row) ? row : [row]
+          return (
+            <div
+              key={idx}
+              className={
+                fields.length > 1 ? "grid grid-cols-2 gap-2" : undefined
+              }
+            >
+              {fields.map((f) => (
+                <FieldSlot
+                  key={f.id}
+                  field={f}
+                  values={values}
+                  ctx={ctx}
+                  onChange={onChange}
+                />
+              ))}
+            </div>
+          )
+        })}
+      </div>
+      {!isLast && <Separator className="mt-1" />}
+    </section>
+  )
+}
+
+function FieldSlot({
+  field,
+  values,
+  ctx,
+  onChange,
+}: {
+  field: FieldDef
+  values: Record<string, unknown>
+  ctx: ScopeContext
+  onChange?: (path: string, val: unknown) => void
+}) {
+  const renderer = getFieldRenderer(field.kind)
+  if (!renderer) {
+    console.warn("[properties] no renderer for kind:", field.kind)
+    return null
+  }
+  const disabled = (() => {
+    const cond = field.disabledWhen
+    if (!cond) return false
+    const v = values[cond.path]
+    if (Object.prototype.hasOwnProperty.call(cond, "equals"))
+      return v === cond.equals
+    if (Object.prototype.hasOwnProperty.call(cond, "notEquals"))
+      return v !== cond.notEquals
+    if (cond.in) return cond.in.includes(v)
+    if (cond.notIn) return !cond.notIn.includes(v)
+    return false
+  })()
+
+  return renderer({
+    field,
+    value: values[field.path],
+    disabled,
+    onChange: onChange ? (val) => onChange(field.path, val) : undefined,
+    ctx,
+  })
+}

package/src/registry.ts

@@ -0,0 +1,32 @@
+import type { FieldRenderer, Scope } from "./types"
+
+const scopes = new Map<string, Scope<unknown, Record<string, unknown>>>()
+const fieldRenderers = new Map<string, FieldRenderer>()
+
+export function registerScope<S, V extends Record<string, unknown>>(
+  key: string,
+  scope: Scope<S, V>,
+): void {
+  scopes.set(key, scope as Scope<unknown, Record<string, unknown>>)
+}
+
+export function unregisterScope(key: string): void {
+  scopes.delete(key)
+}
+
+export function getScope(
+  key: string,
+): Scope<unknown, Record<string, unknown>> | undefined {
+  return scopes.get(key)
+}
+
+export function registerFieldRenderer(
+  kind: string,
+  Component: FieldRenderer,
+): void {
+  fieldRenderers.set(kind, Component)
+}
+
+export function getFieldRenderer(kind: string): FieldRenderer | undefined {
+  return fieldRenderers.get(kind)
+}

package/src/types.ts

@@ -0,0 +1,167 @@
+// Built-in kinds shipped with the package. Apps may register additional kinds
+// via `registerFieldRenderer(kind, Component)` — the panel looks up by string.
+export type BuiltinFieldKind =
+  | "text"
+  | "textarea"
+  | "number"
+  | "slider"
+  | "select"
+  | "color"
+  | "checkbox"
+  | "file"
+
+export interface BaseField {
+  kind: string
+  id: string
+  label?: string
+  path: string
+  disabledWhen?: DisabledWhen
+}
+
+/**
+ * Disables a field based on one other field's value. Exactly one operator is
+ * meant to be set; if several are, the first present in the order
+ * `equals`, `notEquals`, `in`, `notIn` wins. `in`/`notIn` match a list of
+ * values (e.g. "only these enum choices use this param") and are still a
+ * single-path condition — composable AND/OR belongs in a later DSL.
+ */
+export interface DisabledWhen {
+  path: string
+  equals?: unknown
+  notEquals?: unknown
+  in?: readonly unknown[]
+  notIn?: readonly unknown[]
+}
+
+// A custom field is any BaseField whose `kind` is not one of the built-ins.
+// The host's registered renderer for that kind decides what extra props it reads.
+export type CustomFieldDef = BaseField & {
+  [extra: string]: unknown
+}
+
+export interface SelectOption {
+  value: string
+  label: string
+}
+
+export interface SelectFieldDef extends BaseField {
+  kind: "select"
+  options?: SelectOption[]
+  optionsProvider?: (ctx: ScopeContext) => SelectOption[]
+}
+
+export interface ColorFieldDef extends BaseField {
+  kind: "color"
+  presets?: string[]
+}
+
+export interface TextFieldDef extends BaseField {
+  kind: "text"
+  placeholder?: string
+}
+
+export interface TextareaFieldDef extends BaseField {
+  kind: "textarea"
+  placeholder?: string
+  rows?: number
+}
+
+export interface NumberFieldDef extends BaseField {
+  kind: "number"
+  min?: number
+  max?: number
+  step?: number
+}
+
+export interface SliderFieldDef extends BaseField {
+  kind: "slider"
+  min?: number
+  max?: number
+  step?: number
+}
+
+export interface CheckboxFieldDef extends BaseField {
+  kind: "checkbox"
+}
+
+// A tuple of related scalars sharing one row. Houdini-style float3 / int2 /
+// stringN — variable arity, components share semantic context (LCh, RGB,
+// position, dimensions, …). The path resolves to an array; each component
+// describes one slot.
+export interface VectorComponentDef {
+  label?: string
+  suffix?: string
+  min?: number
+  max?: number
+  step?: number
+}
+
+export interface VectorFieldDef extends BaseField {
+  kind: "vector"
+  components: VectorComponentDef[]
+  integer?: boolean
+  precision?: number
+}
+
+export interface FileFieldDef extends BaseField {
+  kind: "file"
+  accept?: string
+  helperText?: string
+}
+
+export type BuiltinFieldDef =
+  | SelectFieldDef
+  | ColorFieldDef
+  | TextFieldDef
+  | TextareaFieldDef
+  | NumberFieldDef
+  | SliderFieldDef
+  | CheckboxFieldDef
+  | FileFieldDef
+  | VectorFieldDef
+
+export type FieldDef = BuiltinFieldDef | CustomFieldDef
+
+export interface PropertyGroupDef {
+  id: string
+  /** Omit to render the group without a header (e.g. when the host already labels it). */
+  title?: string
+  rows: Array<FieldDef | FieldDef[]>
+  description?: string
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+}
+
+export interface PropertySchema {
+  version: number
+  groups: PropertyGroupDef[]
+}
+
+// Opaque to the package. Each host types its own context.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ScopeContext = any
+
+export interface Scope<S = unknown, V = Record<string, unknown>> {
+  schema: PropertySchema
+  read: (selection: S, ctx: ScopeContext) => V
+  write?: (
+    path: string,
+    value: unknown,
+    selection: S,
+    ctx: ScopeContext,
+  ) => void
+}
+
+export interface FieldRendererProps<F extends FieldDef = FieldDef> {
+  field: F
+  value: unknown
+  disabled: boolean
+  onChange?: (next: unknown) => void
+  ctx: ScopeContext
+}
+
+export type FieldRenderer<F extends FieldDef = FieldDef> = React.FC<
+  FieldRendererProps<F>
+>
+
+import type React from "react"