@preset.nz/facets 0.1.3 → 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,15 +18,46 @@ 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[]
 }
 
+/**
+ * A view a field can be promoted to, like a parm promoted to a Houdini
+ * asset's interface. `promote` lists them, each chosen on its own:
+ * `"card"` shows the field on the card; `"collapsed"` in a closed group's
+ * header and in a folded scope. Leave `promote` out and the field is
+ * inspector-only.
+ */
+export type PromoteView = "card" | "collapsed"
+
+/**
+ * How `PropertyPanel` draws a scope. `"inspector"` is every field in its
+ * groups; `"card"` the fields promoted to it, flat; `"collapsed"` the
+ * fields promoted to it, on one line.
+ */
+export type PanelView = "inspector" | "card" | "collapsed"
+
+/**
+ * Where a field's label sits, for the inspector and card views. `"auto"` (the default) is the
+ * original layout: number and vector fields carry their label inside the box as the scrub
+ * handle, other fields stack it above. `"column"` puts every label in one shared column to the
+ * left, so the controls start on one edge. `"stacked"` puts every label above its control.
+ * Paired rows (`[a, b]`) draw one field per row in `"column"`.
+ */
+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
@@ -36,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
 }
 
@@ -74,6 +111,10 @@ export interface NumberFieldDef extends BaseField {
   min?: number
   max?: number
   step?: number
+  /** Whole numbers only: no fractional display, and a fine-step modifier never goes finer than `step`. */
+  integer?: boolean
+  /** A unit after the number, e.g. `px` or `°`. Shown when the panel's `labelLayout` is `"column"` or `"stacked"`. */
+  suffix?: string
 }
 
 export interface SliderFieldDef extends BaseField {
@@ -106,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
 }
 
@@ -123,7 +191,8 @@ export interface SeparatorFieldDef {
   kind: "separator"
   id: string
   label?: string
-  disabledWhen?: DisabledWhen
+  disabledWhen?: DisabledWhenAny
+  promote?: PromoteView[]
 }
 
 /** Static text: a hint, a note, a sub-heading. The text is `label`. */
@@ -131,7 +200,8 @@ export interface LabelFieldDef {
   kind: "label"
   id: string
   label: string
-  disabledWhen?: DisabledWhen
+  disabledWhen?: DisabledWhenAny
+  promote?: PromoteView[]
 }
 
 export type BuiltinFieldDef =
@@ -157,10 +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[]
 }
 
@@ -168,15 +259,42 @@ 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
+   * `write` until `end` is part of it, and `end` closes it. `cancel` fires
+   * instead of `end` when the user abandons it (Escape during a scrub): put
+   * 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> {
+  begin: (path: string, selection: S, ctx: ScopeContext) => void
+  end: (path: string, selection: S, ctx: ScopeContext) => void
+  cancel?: (path: string, selection: S, ctx: ScopeContext) => void
 }
 
 export interface FieldRendererProps<F extends FieldDef = FieldDef> {
@@ -184,11 +302,25 @@ export interface FieldRendererProps<F extends FieldDef = FieldDef> {
   value: unknown
   disabled: boolean
   onChange?: (next: unknown) => void
+  /**
+   * A drag began, ended, or was abandoned: see `Scope.gesture`. Set only when
+   * the scope declares `gesture` and the panel is editable. The built-in
+   * number, vector, slider and colour renderers call them around their drags;
+   * a custom renderer with a continuous control may too.
+   */
+  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
+   * others, so built-ins draw compact. Optional: a renderer may ignore it.
+   */
+  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"