@zodal/dials-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+import { SettingKey, Sensitivity, MergeStrategy, DialsDefinition, EffectiveResult, JsonPatchOp, Layer, ScopedLayer, KeyProvenance, ConstraintResult, SerializedLayer } from '@zodal/dials-core';
+import { RendererTester, RendererRegistry } from '@zodal/ui';
+export { PRIORITY, RendererRegistry, RendererTester, and, createRendererRegistry, editWidgetIs, fieldNameMatches, hasRefinement, metaMatches, or, zodTypeIs } from '@zodal/ui';
+import { z } from 'zod';
+
+/**
+ * Headless output types for the settings UI layer. These are plain configuration objects (never
+ * DOM/React) that any concrete renderer (vanilla, shadcn, …) turns into a settings panel.
+ */
+
+/** The widget kind chosen for a setting's value type. A `secret` setting always maps to `secret`;
+ *  an irreducible nested value maps to `object`/`array`, with `rawJson` as the terminal fallback. */
+type WidgetKind = 'switch' | 'select' | 'radio' | 'slider' | 'number' | 'text' | 'textarea' | 'secret' | 'color' | 'date' | 'path' | 'object' | 'array' | 'rawJson';
+/** A headless field configuration for one setting (the static, value-independent shape). */
+interface SettingFieldConfig {
+    key: SettingKey;
+    label: string;
+    description?: string;
+    widget: WidgetKind;
+    /** The setting's base Zod type ('string'/'number'/'boolean'/'enum'/'object'/'array'/…). */
+    zodType: string;
+    required: boolean;
+    readOnly: boolean;
+    hidden: boolean;
+    sensitivity: Sensitivity;
+    mergeStrategy: MergeStrategy;
+    defaultValue?: unknown;
+    enumValues?: string[];
+    bounds?: {
+        min?: number;
+        max?: number;
+    };
+    /** Facet ids this setting belongs to (multi-membership). */
+    facets: string[];
+    /** Advanced-disclosure flag (membership in the `advanced` facet). */
+    advanced: boolean;
+    order?: number;
+    /** The value is an irreducible nested object/array (use a sub-editor or the rawJson fallback). */
+    isStructured: boolean;
+}
+/** The value-dependent state of a setting field, derived from cascade resolution. */
+interface SettingFieldState {
+    /** The current effective value (a masked `SecretRef` for secrets). */
+    value: unknown;
+    /** The winning scope (provenance). */
+    source?: string;
+    /** True if the effective value comes from a managed/policy scope (lock the control). */
+    managed: boolean;
+    /** True if another scope also set this key (shadowed). */
+    shadowed: boolean;
+    /** True if the active layer overrides the baseline (dirty). */
+    dirty: boolean;
+}
+/** A group projected from a facet (or a computed/"smart" facet). The gesture (open a panel vs.
+ *  expand in place) is NOT encoded here — both are driven by this one model. */
+interface SettingsGroup {
+    id: string;
+    title: string;
+    order: number;
+    settingKeys: SettingKey[];
+    /** True for a computed/"smart" group (e.g. `@modified`, `@secret`) vs. a declared facet. */
+    computed: boolean;
+}
+/** The full headless settings form: field configs + facet-projected groups. */
+interface SettingsForm {
+    fields: SettingFieldConfig[];
+    groups: SettingsGroup[];
+}
+/** The engine-agnostic, indexable projection of a setting for search providers. */
+interface IndexableSetting {
+    key: SettingKey;
+    title: string;
+    description: string;
+    enumLabels: string[];
+    facets: string[];
+    keywords: string[];
+}
+/** A pluggable search provider over the indexable surface. */
+interface SearchProvider {
+    /** Return the matching setting keys for a free-text query (best match first). */
+    search(query: string): SettingKey[];
+}
+
+/**
+ * Type -> widget classification for settings. Pure. Distinguishes a scalar leaf (switch/select/
+ * slider/text/…) from an irreducible nested value (object/array), with `rawJson` as the terminal
+ * fallback for anything unhandled — so coverage is total and degradation is honest. A `secret`
+ * setting always maps to the `secret` widget regardless of its underlying type.
+ */
+
+interface WidgetInput {
+    zodType: string;
+    sensitivity: Sensitivity;
+    bounds?: {
+        min?: number;
+        max?: number;
+    };
+    enumValues?: string[];
+    /** An explicit `.meta({ editWidget })` override (wins over inference). */
+    metaWidget?: unknown;
+}
+/** Choose the widget kind for a setting. */
+declare function widgetKindFor(input: WidgetInput): WidgetKind;
+
+/**
+ * The settings renderer registry — a thin specialization of zodal's capability-ranked
+ * `RendererRegistry`. Concrete renderer packages (vanilla, shadcn, …) register `(tester, renderer)`
+ * entries against the same open-closed API; selection is by PRIORITY band + composable testers, with
+ * a terminal `alwaysMatch` entry (the rawJson fallback) guaranteeing total coverage and honest
+ * degradation. Settings-specific testers read `sensitivity`/`structured` from the render context.
+ */
+
+/** Match a secret setting (its `sensitivity` is supplied via the render context). High priority so a
+ *  secret is always rendered with the masked widget regardless of its underlying type. */
+declare function secretRoleIs(): RendererTester;
+/** Match an irreducible nested value (`structured: true` in context, or an object/array Zod type). */
+declare function isStructuredValue(): RendererTester;
+declare function isBoolean(): RendererTester;
+declare function isEnum(): RendererTester;
+declare function isNumber(): RendererTester;
+declare function isString(): RendererTester;
+/**
+ * Terminal renderer tester: ALWAYS matches, at the given priority (default FALLBACK). Pairing this
+ * with a raw-JSON renderer guarantees every setting resolves to something (the honest-degradation
+ * fallback).
+ */
+declare function alwaysMatch(priority?: number): RendererTester;
+/** Create a settings renderer registry (a zodal `RendererRegistry`). Concrete renderer packages
+ *  populate it; remember to register a terminal `alwaysMatch` rawJson renderer for full coverage. */
+declare function createSettingsRendererRegistry<TComponent = unknown>(): RendererRegistry<TComponent>;
+
+/**
+ * Build the static, value-independent `SettingFieldConfig[]` from a `DialsDefinition`, combining the
+ * schema (via dials-core introspection helpers + `@zodal/core` enum/bounds helpers), the dials
+ * classification (sensitivity, merge strategy, defaults), and `.meta()` annotations + an optional
+ * external facet-assignment map. Pure.
+ */
+
+interface DescribeOptions {
+    /** Extra facet membership, merged with each setting's `.meta({ facets })`: key -> facet ids. */
+    facets?: Record<string, string[]>;
+}
+/** Describe every setting in a dials definition as a headless field config. */
+declare function describeSettings<T extends z.ZodObject<z.ZodRawShape>>(dials: DialsDefinition<T>, options?: DescribeOptions): SettingFieldConfig[];
+
+/**
+ * Faceted organization: project the flat settings surface into groups via a separate grouping layer
+ * (facets are canonical; a tree is one projection). The forward index (facet -> keys) drives panels,
+ * accordions, and bulk-operation scopes — the same model serves both the open-a-panel and the
+ * expand-in-place gesture (the gesture is the renderer's choice, never encoded here). Computed
+ * ("smart") groups are predicates over field config + resolution state. Pure.
+ */
+
+interface FacetDef {
+    id: string;
+    title?: string;
+    order?: number;
+}
+interface GroupingOptions {
+    /** Declared facet titles/order. Facets used by fields but not declared get a humanized default. */
+    facetDefs?: FacetDef[];
+    /** Include computed/"smart" groups (@secret, @advanced, @modified, @managed). Default: true. */
+    computedGroups?: boolean;
+    /** Title for the catch-all group of settings with no facet. Default: 'Other'. */
+    ungroupedTitle?: string;
+}
+/** Project field configs (in their incoming order) into facet groups, sorted by order then title. */
+declare function toGroups(fields: SettingFieldConfig[], result?: EffectiveResult, options?: GroupingOptions): SettingsGroup[];
+
+/**
+ * Search over the settings surface: a declared, engine-agnostic `IndexableSetting[]` projection, a
+ * pluggable `SearchProvider` (zero-dependency substring default; richer engines like MiniSearch or
+ * a semantic provider plug in behind the same interface), and an engine-independent scoped `@`-filter
+ * parser (`@modified`/`@managed`/`@secret`/`@advanced`/`@facet:<id>`/`@scope:<id>`) that narrows by
+ * effective-value/provenance state BEFORE free text reaches the provider. Pure.
+ */
+
+/** Project field configs into the engine-agnostic indexable surface. */
+declare function toIndexableSettings(fields: SettingFieldConfig[]): IndexableSetting[];
+/** Which indexable text fields the substring provider searches (and their relative weight). */
+type IndexField = 'title' | 'description' | 'enumLabels' | 'facets' | 'keywords';
+interface SubstringSearchOptions {
+    /** Which fields to match (default: all). */
+    fields?: IndexField[];
+}
+/**
+ * Zero-dependency substring search provider (the default). Lowercased-substring match over the
+ * selected fields; title/keyword hits rank above description/facet/enum hits. Empty query returns all.
+ */
+declare function createSubstringSearchProvider(settings: IndexableSetting[], options?: SubstringSearchOptions): SearchProvider;
+type ScopeFilter = {
+    type: 'modified';
+} | {
+    type: 'managed';
+} | {
+    type: 'secret';
+} | {
+    type: 'advanced';
+} | {
+    type: 'facet';
+    value: string;
+} | {
+    type: 'scope';
+    value: string;
+};
+interface ParsedQuery {
+    filters: ScopeFilter[];
+    text: string;
+}
+/** Parse a settings query into scoped `@`-filters + the residual free text. Unrecognized `@tokens`
+ *  fall back to free text. */
+declare function parseScopedQuery(query: string): ParsedQuery;
+interface FilterContext {
+    fields: SettingFieldConfig[];
+    result?: EffectiveResult;
+}
+/** Apply scoped filters to a key set (keys must satisfy ALL filters), using field config + state. */
+declare function applyScopedFilters(keys: SettingKey[], filters: ScopeFilter[], context: FilterContext): SettingKey[];
+/** End-to-end: parse a query, apply scoped filters, then free-text search the survivors (keeping the
+ *  provider's ranking order). */
+declare function searchSettings(query: string, provider: SearchProvider, context: FilterContext): SettingKey[];
+
+/**
+ * Change-lifecycle helpers (headless): compute the dirty set, reset a key (remove it so a lower
+ * scope re-wins) or explicitly UNSET it, and record/undo edits as reversible RFC 6902 patches over
+ * the SERIALIZED layer (so the UNSET sentinel survives — `diffJsonPatch` only sees plain JSON). These
+ * are thin wrappers over dials-core; consumers wire them to toasts/guards/undo stacks themselves.
+ */
+
+/** Keys whose value in `current` differs from `baseline` (the dirty set). Absence, UNSET, `undefined`,
+ *  `null`, and a literal value are all distinguished. */
+declare function dirtyKeys(current: Layer, baseline: Layer): SettingKey[];
+/** True if any key is dirty. */
+declare function isDirty(current: Layer, baseline: Layer): boolean;
+/** Reset a key by removing it from the layer (a lower scope re-wins). Returns a new layer. */
+declare function resetToDefault(layer: Layer, key: SettingKey): Layer;
+/** Explicitly UNSET a key (records an intentional reset, distinct from never-set). Returns a new layer. */
+declare function unsetKey(layer: Layer, key: SettingKey): Layer;
+/** A reversible record of an edit (forward + inverse RFC 6902 patches over the serialized layer). */
+interface ChangeRecord {
+    forward: JsonPatchOp[];
+    inverse: JsonPatchOp[];
+}
+/** Record an edit from `before` to `after` as a reversible change over the serialized layers. */
+declare function recordLayerChange(before: Layer, after: Layer): ChangeRecord;
+/** Apply a change's `forward` (redo) or `inverse` (undo) patch to a layer, returning a new layer. */
+declare function applyLayerPatch(layer: Layer, ops: JsonPatchOp[]): Layer;
+
+/**
+ * `toSettingsForm` — the top-level headless generator: describe every (non-hidden) setting as a
+ * field config, order them, and project them into facet groups. `toFieldStates` derives the
+ * value-dependent state (effective value, provenance source, managed/shadowed flags, dirty) from a
+ * cascade resolution — the input to provenance badges, locks, and reset affordances. Pure; emits
+ * configuration objects only (never DOM).
+ */
+
+interface ToSettingsFormOptions extends DescribeOptions, GroupingOptions {
+    /** A resolution result, used for computed groups (@modified/@managed). */
+    result?: EffectiveResult;
+    /** Include hidden settings in the form. Default: false. */
+    includeHidden?: boolean;
+}
+/** Build the full headless settings form (ordered field configs + facet groups). */
+declare function toSettingsForm<T extends z.ZodObject<z.ZodRawShape>>(dials: DialsDefinition<T>, options?: ToSettingsFormOptions): SettingsForm;
+/** Derive value-dependent field state (value, provenance source, managed/shadowed, dirty) for each
+ *  field from a cascade resolution and an optional dirty set. */
+declare function toFieldStates(fields: SettingFieldConfig[], result: EffectiveResult, dirty?: Iterable<SettingKey>): Record<SettingKey, SettingFieldState>;
+
+/**
+ * `createSettingsStore` — a framework-agnostic reactive store of effective settings. It holds the
+ * ordered lower-scope stack + the editable (user) layer; every mutation re-resolves the cascade
+ * (effective + provenance + conflicts), recomputes the dirty set and validation, masks secrets, and
+ * notifies subscribers. No framework dependency: `subscribe`/`getState` plug into React via
+ * `useSyncExternalStore`, or into anything via the listener. Constraints/secret-masking are honored
+ * by reusing dials-core (`resolve`, `validate`, `maskEffectiveResult`).
+ */
+
+interface SettingsState {
+    /** Effective value per key (secrets masked as `SecretRef`). */
+    effective: Record<SettingKey, unknown>;
+    /** Provenance per key (also masked for secrets). */
+    provenance: Record<SettingKey, KeyProvenance>;
+    /** Keys set by multiple layers to differing values. */
+    conflicts: EffectiveResult['conflicts'];
+    /** The editable (user) layer — holds RAW values (including secrets), as the source to persist.
+     *  Split secrets out (dials-core `splitBySensitivity`) before saving to a config store. The
+     *  display surfaces (`effective`/`provenance`) mask secrets; this does not. */
+    layer: Layer;
+    /** The ordered lower-scope stack. */
+    scopes: ScopedLayer[];
+    /** Keys whose editable-layer value differs from the last saved baseline. */
+    dirty: SettingKey[];
+    /** Validation of the (unmasked) effective values. */
+    validation: ConstraintResult;
+}
+interface CreateSettingsStoreOptions {
+    /** Initial lower-scope stack (defaults are prepended by resolve). */
+    scopes?: ScopedLayer[];
+    /** Initial editable layer. */
+    layer?: Layer;
+    /** Scope id of the editable layer. Default: 'user'. */
+    scope?: string;
+    /** Mask secret effective values + provenance. Default: true. */
+    maskSecrets?: boolean;
+    /** Called if a subscriber throws during notification (so one bad listener can't break the others
+     *  or escape a mutation). Default: rethrow asynchronously is avoided — errors are reported here. */
+    onListenerError?: (error: unknown) => void;
+}
+interface SettingsStore {
+    getState(): SettingsState;
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Set a key in the editable layer. */
+    set(key: SettingKey, value: unknown): void;
+    /** Explicitly UNSET a key in the editable layer (re-exposes a lower scope). */
+    unset(key: SettingKey): void;
+    /** Remove a key from the editable layer (reset — a lower scope re-wins). */
+    reset(key: SettingKey): void;
+    /** Replace the whole editable layer. */
+    setLayer(layer: Layer): void;
+    /** Replace the lower-scope stack. */
+    setScopes(scopes: ScopedLayer[]): void;
+    /** Mark the current editable layer as saved (clears the dirty set). */
+    markSaved(): void;
+    /** Current effective value for a key (masked for secrets). */
+    get(key: SettingKey): unknown;
+    /** Provenance for a key. */
+    explain(key: SettingKey): KeyProvenance | undefined;
+}
+/** Create a reactive settings store over a dials definition. */
+declare function createSettingsStore<T extends z.ZodObject<z.ZodRawShape>>(dials: DialsDefinition<T>, options?: CreateSettingsStoreOptions): SettingsStore;
+
+/**
+ * Named profile management — the "save / load / list named settings bundles" capability (an app may
+ * call these "presets", "schemes", or — for thoremin — "instruments"). A profile is a NAME + a
+ * sparse `Layer` (persisted losslessly via `serializeLayer`, so `UNSET` survives) + optional metadata.
+ * Persistence is pluggable (`ProfileStorage`): an in-memory default and a `localStorage` adapter are
+ * provided. To apply a profile, put its layer into the cascade scope stack (e.g.
+ * `store.setScopes([{ scope: 'profile', layer }])`) or replace the editable layer.
+ *
+ * SECURITY: profiles are plaintext at rest. Pass `sensitivityFor` so `secret` keys are REDACTED on
+ * save (never persisted) — fail-closed, mirroring the jsonc store; otherwise split secrets out first.
+ * Mutations are serialized per store so concurrent saves cannot lose updates.
+ */
+
+/** Lightweight profile descriptor (no layer payload) — for listing. */
+interface ProfileMeta {
+    name: string;
+    meta?: Record<string, unknown>;
+}
+/** A persisted named profile (a serialized sparse layer + metadata). */
+interface NamedProfile extends ProfileMeta {
+    layer: SerializedLayer;
+}
+/** Pluggable persistence for the profile collection (reads/writes the whole list as JSON). */
+interface ProfileStorage {
+    read(): Promise<NamedProfile[]>;
+    write(profiles: NamedProfile[]): Promise<void>;
+}
+interface ProfileStoreOptions {
+    /** Classify a setting's sensitivity. When provided, `secret` keys are REDACTED on save. */
+    sensitivityFor?: (key: SettingKey) => Sensitivity;
+}
+/** An in-memory `ProfileStorage` (default; tests / ephemeral use). */
+declare function createMemoryProfileStorage(initial?: NamedProfile[]): ProfileStorage;
+/** A `localStorage`-backed `ProfileStorage` (browser). Throws if `localStorage` is unavailable. A
+ *  corrupt stored value degrades to an empty list rather than throwing on every read. */
+declare function createLocalStorageProfileStorage(storageKey?: string): ProfileStorage;
+interface ProfileStore {
+    /** All saved profiles (name + metadata only). */
+    list(): Promise<ProfileMeta[]>;
+    /** Save (or overwrite) a profile from a sparse layer. Rejects an empty/whitespace name. */
+    save(name: string, layer: Layer, meta?: Record<string, unknown>): Promise<void>;
+    /** Load a profile's layer, or undefined if absent. */
+    load(name: string): Promise<Layer | undefined>;
+    /** Remove a profile. */
+    remove(name: string): Promise<void>;
+    /** Rename a profile (no-op if `from` is absent or equals `to`; throws if `to` already exists). */
+    rename(from: string, to: string): Promise<void>;
+    /** Whether a profile exists. */
+    has(name: string): Promise<boolean>;
+}
+/** Create a profile store over a pluggable storage backend. */
+declare function createProfileStore(storage: ProfileStorage, options?: ProfileStoreOptions): ProfileStore;
+
+export { type ChangeRecord, type CreateSettingsStoreOptions, type DescribeOptions, type FacetDef, type FilterContext, type GroupingOptions, type IndexField, type IndexableSetting, type NamedProfile, type ParsedQuery, type ProfileMeta, type ProfileStorage, type ProfileStore, type ProfileStoreOptions, type ScopeFilter, type SearchProvider, type SettingFieldConfig, type SettingFieldState, type SettingsForm, type SettingsGroup, type SettingsState, type SettingsStore, type SubstringSearchOptions, type ToSettingsFormOptions, type WidgetInput, type WidgetKind, alwaysMatch, applyLayerPatch, applyScopedFilters, createLocalStorageProfileStorage, createMemoryProfileStorage, createProfileStore, createSettingsRendererRegistry, createSettingsStore, createSubstringSearchProvider, describeSettings, dirtyKeys, isBoolean, isDirty, isEnum, isNumber, isString, isStructuredValue, parseScopedQuery, recordLayerChange, resetToDefault, searchSettings, secretRoleIs, toFieldStates, toGroups, toIndexableSettings, toSettingsForm, unsetKey, widgetKindFor };