@preset.nz/facets 0.2.0 → 0.3.0

package/README.md

@@ -47,6 +47,8 @@ the conventional shadcn path, and your bundler's `@` alias resolves it:
 | `@/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
@@ -68,7 +70,18 @@ reads (typed in `dev/ui/` in this repo):
   `presets`, `disabled`, `onPickStart` / `onPickEnd`. No `onChange` means
   read-only.
 
-So you need an `@/*` alias pointing at your `src/`, those eight modules present,
+- `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).
 
@@ -206,7 +219,9 @@ 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`, `emptyState`, `view`, `title` (see [Views](#views-inspector-card-collapsed)),
-`labelLayout` and `labelWidth` (see [Label layout](#label-layout)).
+`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.
@@ -259,13 +274,136 @@ Eleven ship built in: nine that hold a value, and two that only show something.
 | `select` | string | `options`, or `optionsProvider(ctx)` for dynamic lists |
 | `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.
 
 ---
 
@@ -351,8 +489,8 @@ plugin with a skill for writing schemas, scopes and custom renderers lives in
 this repo:
 
 ```sh
-claude plugin marketplace add preset-nz/facets
-claude plugin install facets@preset-nz-facets
+claude plugin marketplace add preset-nz/packages
+claude plugin install facets@preset-nz-packages
 ```
 
 ---
@@ -380,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
@@ -412,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.2.0",
+  "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"
   }
 }