@preset.nz/facets 0.1.3 → 0.3.0

package/README.md

@@ -44,8 +44,44 @@ the conventional shadcn path, and your bundler's `@` alias resolves it:
 | `@/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,
+| `@/components/ui/number-field` | `NumberField` |
+| `@/components/ui/slider` | `Slider` |
+| `@/components/ui/color-field` | `ColorField` |
+| `@/components/ui/path-field` | `PathField` (only for `file` fields) |
+| `@/components/ui/tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
+
+The last three are what make a panel feel like the rest of your app: a number
+you drag, a square slider, your colour picker. They are the **minimum** facets
+reads (typed in `dev/ui/` in this repo):
+
+- `NumberField`: `value: number`, `onValueChange(value, { reason })`, `min`,
+  `max`, `step`, `integer`, `precision`, `label` (the scrub handle: the field
+  draws its own label, so the panel adds none), `disabled`, and
+  `onScrubStart` / `onScrubEnd` / `onScrubCancel`. Facets uses it for `number`
+  and for each slot of `vector`. A vector slot's `suffix` shows in read-only
+  mode only, unless the panel sets `labelLayout` (below). Two **optional** props
+  serve that: `labelPlacement` (`"inside"` default, `"column"`, `"above"`) and
+  `suffix` (a muted unit inside the box). A host that ignores them keeps the
+  label inside the box, so nothing doubles.
+- `Slider`: `value: number`, `onValueChange(value)` (a number or an array, facets
+  takes the first), `onValueCommitted()`, `min`, `max`, `step`, `disabled`,
+  `aria-label`. One thumb.
+- `ColorField`: `value: string | null`, `onChange(value | null)`, `label`,
+  `presets`, `disabled`, `onPickStart` / `onPickEnd`. No `onChange` means
+  read-only.
+
+- `PathField`: `value: string | null`, `onCommit(path | null)` (Return or blur;
+  no `onCommit` means read-only), `recent: string[]`, `onBrowse(): Promise<string | null>`,
+  `status` (`"ok"`, `"missing"`, `"invalid"`), `message`, `id`, `placeholder`,
+  `disabled`, and the props of a `div` (facets passes `onContextMenu` and
+  `onMouseDownCapture`). With ux-kit: `export { PathField } from "@preset.nz/ux-kit"`.
+
+`Tabs` draws a schema's pages. facets uses the shadcn API (`value`,
+`onValueChange` on `Tabs`; `value` on `TabsTrigger` and `TabsContent`) and the
+list's default variant, the segmented control. With ux-kit it is a one-liner:
+`export { Tabs, TabsContent, TabsList, TabsTrigger } from "@preset.nz/ux-kit"`.
+
+So you need an `@/*` alias pointing at your `src/`, those ten modules present,
 and Tailwind with shadcn's theme tokens (`muted-foreground`, `border` and
 friends are used throughout).
 
@@ -61,6 +97,18 @@ package in your CSS. From `src/index.css`:
 Nothing fails when this line is missing. The build succeeds and the panel
 renders unstyled.
 
+Tell Vite to resolve one copy of React and of this package, so the package and
+your app share one registry. In `vite.config.ts`:
+
+```ts
+resolve: {
+  dedupe: ["react", "react-dom", "@preset.nz/facets"],
+},
+```
+
+Without it, a linked or nested install can register renderers in one copy and
+look them up in another.
+
 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.
@@ -122,7 +170,29 @@ 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.
+width. That is the whole layout system, on purpose, with one switch: where the
+labels go.
+
+### Label layout
+
+`labelLayout` on `PropertyPanel` (inspector and card views; collapsed ignores it):
+
+| Value | Labels | Numbers |
+|---|---|---|
+| `"auto"` (default) | Above their control; a checkbox's beside it | The label is the scrub handle, inside the box |
+| `"column"` | One shared column to the left, truncated with the full text as a tooltip; controls start on one edge | Label in the column (still the scrub handle), number right-aligned, `suffix` as a muted unit |
+| `"stacked"` | All above their control | Label above the box, `suffix` as a unit |
+
+In `"column"` the label column's width is one CSS variable on the panel root
+(`--facets-label-w`), set from the longest label (8ch to 16ch) or from the
+`labelWidth` prop. A vector keeps its axis labels inside its slots, so its
+fields share the column the scalars start on. A paired row (`[a, b]`) draws one
+field per row, and a slider shows its value to the right. A custom renderer
+follows the layout by wrapping its control in `FieldShell` (the built-ins'
+shell; `top` aligns the label with the top of a tall control, `above` keeps it
+above in every layout) and a read-only value in `ReadOnlyText`. For anything
+else, `useLabelLayout()` and `COLUMN_ROW` give the parts. A renderer that draws
+its own label ignores the layout.
 
 ---
 
@@ -148,11 +218,40 @@ 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`.
+`readOnly`, `emptyState`, `view`, `title` (see [Views](#views-inspector-card-collapsed)),
+`labelLayout` and `labelWidth` (see [Label layout](#label-layout)), and `page`,
+`onPageChange`, `advancedOpen` and `onAdvancedOpenChange` (see
+[Pages and advanced groups](#pages-and-advanced-groups)).
 
 `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.
 
+### Drags as one undo step
+
+A scrubbed number, a dragged slider and an open colour picker produce many
+`write`s. Say where they begin and end and your undo stack can fold them into
+one step: add `gesture` to the scope.
+
+```ts
+registerScope("blur", {
+  schema, read, write,
+  gesture: {
+    begin: (path, sel, ctx) => ctx.beginGesture(sel.id, path),
+    end: (path, sel, ctx) => ctx.endGesture(),
+    cancel: (path, sel, ctx) => ctx.cancelGesture(), // optional: Escape during a scrub
+  },
+})
+```
+
+Every `write` between `begin` and `end` belongs to the gesture (apply them
+live, close one undo step at `end`). `cancel` fires instead of `end` when the
+user abandons a scrub; put the value back. Typed values and arrow-key steps are
+single writes outside any gesture. Omit `gesture` and drags are plain repeated
+`write`s, as before. The renderers receive the same hooks as optional
+`onGestureBegin` / `onGestureEnd` / `onGestureCancel` props, set only when the
+scope declares `gesture`; a custom renderer with a continuous control can call
+them too.
+
 ### How `path` resolves
 
 `read()` returns a record, and `path` is a **key into that record** — a flat
@@ -169,19 +268,195 @@ Eleven ship built in: nine that hold a value, and two that only show something.
 |---|---|---|
 | `text` | string | `placeholder` |
 | `textarea` | string | `placeholder`, `rows` |
-| `number` | number | `min`, `max`, `step` |
-| `slider` | number | same, rendered as a slider |
+| `number` | number | `min`, `max`, `step`, `integer`, `suffix` (a unit, with `labelLayout`); drag the label to scrub (host `NumberField`) |
+| `slider` | number | same, drawn by the host's `Slider` |
 | `checkbox` | boolean | |
 | `select` | string | `options`, or `optionsProvider(ctx)` for dynamic lists |
-| `color` | hex string | `presets`; shows a swatch |
+| `color` | hex string | `presets`; the host's `ColorField` |
 | `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 |
+| `file` | path string, or `null` | `recentKey`, `filters`, `title`, `placeholder`; editable on the host's `PathField`, see [The `file` field](#the-file-field) |
 | `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` |
 
+### The `file` field
+
+`file` is a path to a file, on ux-kit's `PathField`: a text field, a ▾ list of
+recent paths and a browse icon. The value is the path **as written**, relative
+or absolute (facets never rewrites it), or `null`. Typing commits on Return or
+blur through the scope's `write`, never per keystroke; Esc reverts.
+
+```ts
+{ kind: "file", id: "texture", path: "texture", label: "Texture Path",
+  recentKey: "texture", filters: [{ name: "Images", extensions: ["png", "jpg", "webp"] }] }
+```
+
+`recentKey` names the field kind whose last paths the ▾ lists, across documents.
+`filters` and `title` go to the Open dialog. `accept` (as on `<input>`) is
+deprecated: its `.ext` entries become one "Files" filter when `filters` is absent.
+Before 0.3 the value was a read-only `{ name }`; that still draws, read-only.
+
+**Refusing a value.** The host's `write` is the validator. Return `{ error }`
+(or a promise that resolves to it or rejects with a message) and the field is
+marked invalid with the message under it, keeping the typed text. The message
+shows while the field's value stays as it was and clears on the next write. Any
+`write` can refuse this way; fields other than `file` receive the message as
+the `error` prop and ignore it.
+
+**The native parts come from the host.** facets depends on neither Tauri nor
+app-kit. Register the handlers once at startup; every `file` field then works
+the same way. Without them it is a plain editable text field.
+
+```ts
+import { registerFileHandlers } from "@preset.nz/facets"
+import { pathFieldMenu, pathsExist, pickFile, recentPaths, rememberPath, revealPath } from "@preset.nz/app-kit"
+
+registerFileHandlers({
+  recent: recentPaths,      // (key) => Promise<string[]>: the ▾ list
+  remember: rememberPath,   // (key, path): after the host accepted a commit
+  pick: pickFile,           // ({ filters, title }) => Promise<string | null>: the browse icon
+  exists: pathsExist,       // (paths, base?) => Promise<boolean[]>: Missing, and gone recents left out
+  reveal: revealPath,       // (path, base?)
+  contextMenu: pathFieldMenu, // ({ missing, canClear }) => "reveal" | "clear" | null: a native menu
+  base: () => currentDocumentFolder(), // relative paths resolve against it
+})
+```
+
+Every member is optional. A path is remembered when the field's value becomes
+the path that was committed, which is the first moment a host that validates
+asynchronously has accepted it; a refused commit is never remembered. Missing
+and the ▾ list are re-checked when the window regains focus. Right-click opens
+the native menu (Reveal in Finder, Clear) unless the text is being edited, when
+the native text menu stays.
+
+Every field that holds a value takes `help` (from 0.3.0): a sentence or two
+drawn under the control in the inspector, and left out of the card and the
+collapsed view. `file`'s `helperText` is its deprecated name.
+
 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.
+the panel, so it resets when the panel remounts.
+
+---
+
+## Pages and advanced groups
+
+A long panel splits into pages, drawn as tabs. Declare them at the root, in
+order, and name one on every group:
+
+```ts
+const SETTINGS: PropertySchema = {
+  version: 1,
+  pages: [
+    { id: "general", label: "General" },
+    { id: "export", label: "Export" },
+  ],
+  groups: [
+    { id: "appearance", title: "Appearance", page: "general", rows: [/* … */] },
+    { id: "performance", title: "Performance", page: "general", advanced: true, rows: [/* … */] },
+    { id: "format", title: "Format", page: "export", rows: [/* … */] },
+  ],
+};
+```
+
+- **No `pages` is one page and no tab row**, exactly as before. One declared
+  page draws no tab row either.
+- **Pages are presentation only.** A `path` never names a page, so moving a
+  group to another page changes no values.
+- **`advanced: true`** puts a group behind one closed *Advanced* row at the foot
+  of its page, with or without pages. The row folds like a collapsible group.
+- **Every page needs a group that isn't advanced.** With pages, every group
+  names a declared page; without, none does. `schemaProblems(schema)` lists
+  what breaks these rules, and `registerScope` throws on any of them, so a bad
+  schema fails where it is registered, not as an empty tab.
+- **The card and collapsed views ignore pages and `advanced`.** They draw
+  promoted fields, wherever they sit.
+
+The open page and each page's Advanced row are the panel's own state: the first
+page, every row closed. A host that remembers them, as a Settings window does,
+passes them in:
+
+```tsx
+<PropertyPanel
+  scopeKey="settings" selection={prefs} ctx={ctx}
+  page={tab} onPageChange={setTab}
+  advancedOpen={openRows} onAdvancedOpenChange={setOpenRows}
+/>
+```
+
+`advancedOpen` lists the pages whose Advanced row is open. A schema without
+`pages` has one page, whose id is `""`. A `page` the schema doesn't declare
+shows the first page. Group folds and Advanced rows survive switching tabs.
+
+### Changed marks
+
+A scope may say which of its values count as changed (from their defaults,
+say). The panel then marks anything that hides one: a tab other than the open
+one, a closed Advanced row, a closed group. The mark is a dot, read by screen
+readers as "changed".
+
+```ts
+registerScope("settings", {
+  schema: SETTINGS,
+  read: (sel, ctx) => ctx.prefs(),
+  write: (path, value, sel, ctx) => ctx.setPref(path, value),
+  changed: (sel, ctx) => ctx.changedPrefs(), // paths, e.g. ["theme", "cacheSize"]
+});
+```
+
+The field itself carries no mark from facets; a label or renderer does that.
+
+---
+
+## Views: inspector, card, collapsed
+
+One scope draws three ways. `view` on `PropertyPanel` picks one:
+
+- **`"inspector"`**, the default: every group and field.
+- **`"card"`**: the fields promoted to the card, with no group chrome. The
+  schema's `title` heads it. The panel's `title` prop overrides that, for an
+  instance name such as "Filter 2".
+- **`"collapsed"`**: the fields promoted to collapsed, one compact row each.
+  This is a scope folded shut. The host draws the title bar that folds it and
+  holds the open or closed state.
+
+A field lists the views it shows in besides the inspector, the way a Houdini
+asset promotes a parm to its interface:
+
+```ts
+const FILTER: PropertySchema = {
+  version: 1,
+  title: "Filter",
+  groups: [
+    {
+      id: "filter",
+      title: "Filter",
+      collapsible: true,
+      rows: [
+        { kind: "select", id: "type", path: "type", options: TYPES, promote: ["collapsed"] },
+        { kind: "slider", id: "master", path: "master", promote: ["card", "collapsed"] },
+        { kind: "slider", id: "resonance", path: "resonance" },
+        { kind: "slider", id: "pan", path: "pan", promote: ["card"] },
+      ],
+    },
+  ],
+};
+```
+
+```tsx
+<PropertyPanel scopeKey="filter" selection={node} ctx={ctx} view="card" title={node.name} />
+```
+
+The card shows master and pan. Folded, the scope shows type and master.
+Resonance is inspector-only. The views are independent: `["collapsed"]` is not
+on the card.
+
+A closed collapsible group shows its `collapsed` fields under its title, so
+folding a group still leaves its main value in reach.
+
+Renderers receive the view as an optional `view` prop. The built-ins draw a
+compact row in `"collapsed"`. A custom renderer may ignore it.
+`promotedFields(schema, view)` returns the fields a view draws, in schema
+order, for a host that wants to skip an empty card.
 
 ---
 
@@ -207,6 +482,17 @@ 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.
 
+### For agents
+
+`https://facets.preset.nz/llms.txt` is the contract in brief. A Claude Code
+plugin with a skill for writing schemas, scopes and custom renderers lives in
+this repo:
+
+```sh
+claude plugin marketplace add preset-nz/packages
+claude plugin install facets@preset-nz-packages
+```
+
 ---
 
 ## Read-only
@@ -232,6 +518,16 @@ The condition reads one other field's value. Set one operator:
 
 If several are set, the first in that order wins.
 
+A list of conditions disables the field when any of them holds, e.g. a width
+that a hairline or a non-solid line both make moot:
+
+```ts
+disabledWhen: [
+  { path: "hairline", equals: true },
+  { path: "lineStyle", notEquals: "solid" },
+]
+```
+
 ---
 
 ## Custom field kinds
@@ -246,6 +542,10 @@ registerFieldRenderer("palette-swatches", ({ field, value, onChange, ctx }) => (
 ));
 ```
 
+A renderer receives `field`, `value`, `disabled`, `onChange`, `ctx` and `view`.
+Pick what it uses rather than spreading the props onto a DOM element, where
+React warns about the unknown ones.
+
 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.
@@ -260,8 +560,11 @@ it does not take the rest of the panel down with it.
 - **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.
+- **Failures stay local, except a bad page layout.** A throwing `read` is
+  caught and logged; an unknown scope renders `emptyState`; an unknown kind
+  skips that field. A schema whose pages don't add up throws from
+  `registerScope` (see [Pages](#pages-and-advanced-groups)), so the mistake
+  shows where the schema is registered rather than as an empty tab later.
 - **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.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@preset.nz/facets",
-  "version": "0.1.3",
+  "version": "0.3.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",
   "homepage": "https://facets.preset.nz",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/preset-nz/facets.git"
+    "url": "git+https://github.com/preset-nz/packages.git",
+    "directory": "facets"
   },
   "type": "module",
   "sideEffects": false,
@@ -25,8 +26,10 @@
     "react": "^19"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
     "@types/react": "^19",
     "ajv": "^8.20.0",
-    "typescript": "^5.8.3"
+    "ts5": "npm:typescript@5.9.3",
+    "typescript": "^7.0.2"
   }
 }