@preset.nz/facets 0.2.0 → 0.3.0

package/src/registry.ts

@@ -1,12 +1,18 @@
+import { schemaProblems } from "./pages"
 import type { FieldRenderer, Scope } from "./types"
 
 const scopes = new Map<string, Scope<unknown, Record<string, unknown>>>()
 const fieldRenderers = new Map<string, FieldRenderer>()
 
+/** Throws when the schema's pages don't add up: see `schemaProblems`. */
 export function registerScope<S, V extends Record<string, unknown>>(
   key: string,
   scope: Scope<S, V>,
 ): void {
+  const problems = schemaProblems(scope.schema)
+  if (problems.length > 0) {
+    throw new Error(`[properties] scope "${key}": ${problems.join("; ")}`)
+  }
   scopes.set(key, scope as Scope<unknown, Record<string, unknown>>)
 }
 
@@ -14,16 +20,11 @@ export function unregisterScope(key: string): void {
   scopes.delete(key)
 }
 
-export function getScope(
-  key: string,
-): Scope<unknown, Record<string, unknown>> | undefined {
+export function getScope(key: string): Scope<unknown, Record<string, unknown>> | undefined {
   return scopes.get(key)
 }
 
-export function registerFieldRenderer(
-  kind: string,
-  Component: FieldRenderer,
-): void {
+export function registerFieldRenderer(kind: string, Component: FieldRenderer): void {
   fieldRenderers.set(kind, Component)
 }
 

package/src/types.ts

@@ -18,7 +18,12 @@ export interface BaseField {
   id: string
   label?: string
   path: string
-  disabledWhen?: DisabledWhen
+  /**
+   * One or two sentences on what the field does, drawn under the control in the
+   * inspector view. The card and collapsed views leave it out.
+   */
+  help?: string
+  disabledWhen?: DisabledWhenAny
   promote?: PromoteView[]
 }
 
@@ -49,10 +54,10 @@ export type LabelLayout = "auto" | "column" | "stacked"
 
 /**
  * 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
+ * meant to be set; if several are set, 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.
+ * values (e.g. "only these enum choices use this param"). A field takes a list
+ * of these to be disabled when any of them holds (`DisabledWhenAny`).
  */
 export interface DisabledWhen {
   path: string
@@ -62,9 +67,15 @@ export interface DisabledWhen {
   notIn?: readonly unknown[]
 }
 
+/** One condition, or a list: disabled when any of them holds. */
+export type DisabledWhenAny = DisabledWhen | readonly DisabledWhen[]
+
 // 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 & {
+// `path` is optional here: a custom field may hold no value (a host section the
+// renderer draws and owns), like the display-only kinds.
+export type CustomFieldDef = Omit<BaseField, "path"> & {
+  path?: string
   [extra: string]: unknown
 }
 
@@ -136,9 +147,36 @@ export interface VectorFieldDef extends BaseField {
   precision?: number
 }
 
+/** One file type in the host's Open dialog. Extensions have no dot: `["png", "jpg"]`. */
+export interface FileFilter {
+  name: string
+  extensions: string[]
+}
+
+/**
+ * A path to a file, edited on ux-kit's `PathField`. The value is the path string as written,
+ * relative or absolute, or `null`/`""` when empty. Typing commits on Return or blur through the
+ * scope's `write`; the host validates there (see `WriteResult`). The ▾ list, the browse icon, the
+ * Missing check and the context menu need the host's `registerFileHandlers`; without them the
+ * field is a plain editable text field.
+ *
+ * Before 0.3 the value was a read-only `{ name }`. That value still draws, read-only.
+ */
 export interface FileFieldDef extends BaseField {
   kind: "file"
+  /** Keys the recent paths: fields with the same key share one ▾ list, across documents (`"texture"`). */
+  recentKey?: string
+  /** File types in the Open dialog. */
+  filters?: FileFilter[]
+  /** The Open dialog's title. */
+  title?: string
+  placeholder?: string
+  /**
+   * @deprecated Use `filters`. File types as on `<input accept>`; the extensions in it (`.png,.jpg`)
+   * become one "Files" filter when `filters` is absent.
+   */
   accept?: string
+  /** @deprecated Use `help`, which every field has. Drawn as `help` when that's absent. */
   helperText?: string
 }
 
@@ -153,7 +191,7 @@ export interface SeparatorFieldDef {
   kind: "separator"
   id: string
   label?: string
-  disabledWhen?: DisabledWhen
+  disabledWhen?: DisabledWhenAny
   promote?: PromoteView[]
 }
 
@@ -162,7 +200,7 @@ export interface LabelFieldDef {
   kind: "label"
   id: string
   label: string
-  disabledWhen?: DisabledWhen
+  disabledWhen?: DisabledWhenAny
   promote?: PromoteView[]
 }
 
@@ -189,12 +227,31 @@ export interface PropertyGroupDef {
   description?: string
   collapsible?: boolean
   defaultCollapsed?: boolean
+  /** The id of the page the group sits on. Required when the schema declares `pages`, absent otherwise. */
+  page?: string
+  /** Sits behind the page's one closed Advanced row, at the foot of the page. */
+  advanced?: boolean
+}
+
+/**
+ * A tab in the inspector. Pages are presentation only: a field's `path` never
+ * names one, so moving a group to another page changes no values.
+ */
+export interface PropertyPageDef {
+  id: string
+  label: string
 }
 
 export interface PropertySchema {
   version: number
   /** What the scope is called, e.g. "Filter". Heads the card; `PropertyPanel`'s `title` overrides it. */
   title?: string
+  /**
+   * Splits the inspector into tabs, in this order. Omit it for one page and no
+   * tab row. Each page needs at least one group that isn't `advanced`; see
+   * `schemaProblems`.
+   */
+  pages?: PropertyPageDef[]
   groups: PropertyGroupDef[]
 }
 
@@ -202,15 +259,20 @@ export interface PropertySchema {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ScopeContext = any
 
+/**
+ * What a scope's `write` may return. Nothing is the usual case: the write was taken. `{ error }`,
+ * or a promise that resolves to it or rejects, refuses the value: the panel hands the message to
+ * the field as `error` for as long as the field's value stays as it was, and a field that can
+ * show it (the `file` field marks itself invalid) does. An accepted write needs no signal: the
+ * host's `read` returns the new value.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: an async write that returns nothing is a Promise<void>
+export type WriteResult = void | { error: string } | Promise<void | { error: string }>
+
 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
+  write?: (path: string, value: unknown, selection: S, ctx: ScopeContext) => WriteResult
   /**
    * One drag as one undo step. A drag is a scrubbed number, a dragged slider
    * thumb or an open colour picker; `begin` fires when it starts, every
@@ -219,6 +281,14 @@ export interface Scope<S = unknown, V = Record<string, unknown>> {
    * the value back. Omit `gesture` and drags are plain repeated `write`s.
    */
   gesture?: ScopeGesture<S>
+  /**
+   * The paths whose values differ from their defaults, or whatever "changed"
+   * means to the host. The panel marks a tab, a closed Advanced row or a
+   * closed group that hides one of them, so a change is never out of sight
+   * without a trace. It doesn't mark the field itself: a renderer or label
+   * does that. Called like `read`, when the selection or ctx changes.
+   */
+  changed?: (selection: S, ctx: ScopeContext) => readonly string[]
 }
 
 export interface ScopeGesture<S = unknown> {
@@ -241,6 +311,8 @@ export interface FieldRendererProps<F extends FieldDef = FieldDef> {
   onGestureBegin?: () => void
   onGestureEnd?: () => void
   onGestureCancel?: () => void
+  /** Why the host refused the field's last written value (see `WriteResult`). Absent once the value changes. */
+  error?: string
   ctx: ScopeContext
   /**
    * The view the field is drawn in. In `"collapsed"` it shares a line with
@@ -249,8 +321,6 @@ export interface FieldRendererProps<F extends FieldDef = FieldDef> {
   view?: PanelView
 }
 
-export type FieldRenderer<F extends FieldDef = FieldDef> = React.FC<
-  FieldRendererProps<F>
->
+export type FieldRenderer<F extends FieldDef = FieldDef> = React.FC<FieldRendererProps<F>>
 
 import type React from "react"