vultus-core 0.4.0 → 0.5.0

package/dist/useStoredField.d.ts

@@ -0,0 +1,61 @@
+import type { UpdateMethod } from './argStore.js';
+import { type FieldCtx } from './FieldContext.js';
+import { type FieldDefinition } from './kinds.js';
+import { type ArgDefinition } from './useArg.js';
+/**
+ * The argument a field's value is stored as: the definition's `id` as key, its kind's value
+ * type, and its initial value, resolved with the field context, as default — a value, so the
+ * argument layer compares against the same default the field starts at. A mixed-boolean field
+ * shows an aggregate of other data and cannot be stored: it throws, naming the field.
+ */
+export declare function argOf(definition: FieldDefinition, ctx: FieldCtx): ArgDefinition<any>;
+/**
+ * A field kept in the nearest ArgStore: its options for the kind's hook, and whether it shows
+ * its default. `options` follows `D` member by member, so options of a definition typed as the
+ * FieldDefinition union still narrow by `kind`.
+ */
+export interface StoredField<D extends FieldDefinition = FieldDefinition> {
+    /** The definition in its outside form, for the kind's hook (`useManyOfField(stored.options)`). */
+    options: D extends any ? Omit<D, 'initialValue'> & {
+        value: any;
+        onChange(value: any): void;
+    } : never;
+    isDefault: boolean;
+    /** Removes the field's key from the store, so it shows its default again. */
+    reset(method?: UpdateMethod): void;
+}
+/**
+ * A field whose value lives in the nearest ArgStore (the URL, localStorage) under its `id`,
+ * with its initial value as the default (see argOf). `options.value` is the stored value made
+ * fit for the definition as it is now (sanitizeStored: choices, nodes and bounds follow the
+ * data); `onChange` writes with `'replace'`.
+ *
+ * A stored value that does not fit warns once per field and raw value: not again when only the
+ * definition or the field context is a new object (a provider given `value={{...}}` makes one
+ * on every render). With the key absent the default is the definer's, not stored input, and is
+ * sanitized silently.
+ *
+ * `options.value` keeps its identity while it stays the same element by element, so a list
+ * does not become a new array on every render (effects keyed on it would re-run), even when
+ * the field context is a new object each time. The default keeps its identity while it is
+ * `isEqual` to the freshly resolved one, so `onChange` and `options` keep theirs too.
+ */
+export declare function useStoredField<D extends FieldDefinition>(definition: D): StoredField<D>;
+/** Several stored fields at once: "more filters (3)" and "clear all". */
+export interface StoredFields {
+    /** Whether the field with this id shows its default; an id not among the fields throws. */
+    isDefault(id: string): boolean;
+    /** How many of the fields do not show their defaults. */
+    changedCount: number;
+    /** Removes every field's key in one store write (one history entry). */
+    resetAll(method?: UpdateMethod): void;
+}
+/**
+ * Whether stored fields show their defaults, by the same rule as useStoredField, with one store
+ * subscription for all of them: its snapshot is their raw values joined into one string, which
+ * changes exactly when one of them does. It is a summary, so it never warns (the fields do).
+ * Each field is re-read only when its raw value, its definition or the field context changes,
+ * so typing into one field does not re-read its siblings.
+ */
+export declare function useStoredFields(definitions: readonly FieldDefinition[]): StoredFields;
+//# sourceMappingURL=useStoredField.d.ts.map

package/dist/useStoredField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStoredField.d.ts","sourceRoot":"","sources":["../src/useStoredField.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAA+C,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGzD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CASpF;AA4BD;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IACtE,kGAAkG;IAClG,OAAO,EAAE,CAAC,SAAS,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,GAAG,KAAK,CAAC;IACtG,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EAAE,UAAU,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAwCvF;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACvC;AAsBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,YAAY,CAwCrF"}

package/dist/useStoredField.js

@@ -0,0 +1,151 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useArgStore } from './ArgStoreContext.js';
+import { useFieldContext } from './FieldContext.js';
+import { initialValueOf, sanitizeStored, valueTypeOf } from './kinds.js';
+import { useArg } from './useArg.js';
+/**
+ * The argument a field's value is stored as: the definition's `id` as key, its kind's value
+ * type, and its initial value, resolved with the field context, as default — a value, so the
+ * argument layer compares against the same default the field starts at. A mixed-boolean field
+ * shows an aggregate of other data and cannot be stored: it throws, naming the field.
+ */
+export function argOf(definition, ctx) {
+    const { id, kind } = definition;
+    let valueType;
+    try {
+        valueType = valueTypeOf(kind);
+    }
+    catch (error) {
+        throw new Error(`Field '${id}': ${error.message}`);
+    }
+    return { key: id, valueType, default: initialValueOf(definition, ctx) };
+}
+function silently(_message) { }
+function warnOnConsole(message) {
+    console.warn(message);
+}
+/**
+ * The same value element by element: a list in the same order, a range with the same ends, a
+ * scalar. Stricter than the value types' `isEqual` (lists as sets), because the order a field
+ * shows (choice order, tree order) matters to the identity kept below.
+ */
+function sameValue(a, b) {
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => v === b[i]);
+    return a === b;
+}
+/**
+ * Whether a field shows its default: its stored value (parsed, or the default where absent or
+ * unreadable) equals it, or fits the definition only as the default (a one-of value no longer
+ * among the choices, a range clamped to bounds that are the default). `shown` is the sanitized
+ * value, asked for only when the first test fails.
+ */
+function showsDefault(arg, stored, shown) {
+    return arg.valueType.isEqual(stored, arg.default) || arg.valueType.isEqual(shown(), arg.default);
+}
+/** A compile-time check: options of a FieldDefinition-typed definition narrow by `kind` (the Omit distributes over the union). */
+function optionsNarrowByKind(stored) {
+    return stored.options.kind === 'manyOf' ? stored.options.choices : undefined;
+}
+/**
+ * A field whose value lives in the nearest ArgStore (the URL, localStorage) under its `id`,
+ * with its initial value as the default (see argOf). `options.value` is the stored value made
+ * fit for the definition as it is now (sanitizeStored: choices, nodes and bounds follow the
+ * data); `onChange` writes with `'replace'`.
+ *
+ * A stored value that does not fit warns once per field and raw value: not again when only the
+ * definition or the field context is a new object (a provider given `value={{...}}` makes one
+ * on every render). With the key absent the default is the definer's, not stored input, and is
+ * sanitized silently.
+ *
+ * `options.value` keeps its identity while it stays the same element by element, so a list
+ * does not become a new array on every render (effects keyed on it would re-run), even when
+ * the field context is a new object each time. The default keeps its identity while it is
+ * `isEqual` to the freshly resolved one, so `onChange` and `options` keep theirs too.
+ */
+export function useStoredField(definition) {
+    const store = useArgStore();
+    const ctx = useFieldContext();
+    const fresh = argOf(definition, ctx);
+    const argRef = useRef(undefined);
+    const previousArg = argRef.current;
+    const arg = previousArg !== undefined && previousArg.key === fresh.key && previousArg.valueType === fresh.valueType
+        && fresh.valueType.isEqual(previousArg.default, fresh.default)
+        ? previousArg
+        : fresh;
+    argRef.current = arg;
+    const { value: stored, set, reset } = useArg(arg);
+    // Called on the store, not passed detached: a store written as a class uses `this`.
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    const read = useCallback(() => store.read(definition.id), [store, definition.id]);
+    const raw = useSyncExternalStore(subscribe, read);
+    const warnedRef = useRef(undefined);
+    const sanitized = useMemo(() => {
+        const input = raw === undefined ? undefined : JSON.stringify([definition.id, raw]);
+        const warn = input !== undefined && input !== warnedRef.current ? warnOnConsole : silently;
+        warnedRef.current = input;
+        return sanitizeStored(definition, stored, ctx, warn);
+    }, [definition, stored, ctx, raw]);
+    const previousRef = useRef(undefined);
+    const value = previousRef.current !== undefined && sameValue(previousRef.current.value, sanitized)
+        ? previousRef.current.value
+        : sanitized;
+    previousRef.current = { value };
+    const onChange = useCallback((next) => set(next, 'replace'), [set]);
+    const options = useMemo(() => {
+        const { initialValue: _inside, ...rest } = definition;
+        return { ...rest, value, onChange };
+    }, [definition, value, onChange]);
+    return { options, isDefault: showsDefault(arg, stored, () => value), reset };
+}
+/** A compile-time check: useStoredFields takes a `readonly` list of definitions (an `as const` module constant). */
+function takesReadonlyDefinitions(definitions) {
+    return definitions;
+}
+/** Whether a field with this raw value shows its default, by useStoredField's rule; silent, as a summary does not warn. */
+function readsAsDefault(definition, raw, ctx) {
+    const arg = argOf(definition, ctx);
+    const stored = (raw === null ? undefined : arg.valueType.parse(raw)) ?? arg.default;
+    return showsDefault(arg, stored, () => sanitizeStored(definition, stored, ctx, silently));
+}
+/**
+ * Whether stored fields show their defaults, by the same rule as useStoredField, with one store
+ * subscription for all of them: its snapshot is their raw values joined into one string, which
+ * changes exactly when one of them does. It is a summary, so it never warns (the fields do).
+ * Each field is re-read only when its raw value, its definition or the field context changes,
+ * so typing into one field does not re-read its siblings.
+ */
+export function useStoredFields(definitions) {
+    const store = useArgStore();
+    const ctx = useFieldContext();
+    // Called on the store, not passed detached: a store written as a class uses `this`.
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    const readAll = useCallback(() => JSON.stringify(definitions.map((d) => store.read(d.id) ?? null)), [store, definitions]);
+    const snapshot = useSyncExternalStore(subscribe, readAll);
+    const readingsRef = useRef(new Map());
+    const changed = useMemo(() => {
+        const raws = JSON.parse(snapshot);
+        const previous = readingsRef.current;
+        const readings = new Map();
+        definitions.forEach((definition, i) => {
+            const raw = raws[i];
+            const before = previous.get(definition.id);
+            const reading = before !== undefined && before.definition === definition && before.raw === raw && before.ctx === ctx
+                ? before
+                : { definition, raw, ctx, isDefault: readsAsDefault(definition, raw, ctx) };
+            readings.set(definition.id, reading);
+        });
+        readingsRef.current = readings;
+        return new Set([...readings.values()].filter((r) => !r.isDefault).map((r) => r.definition.id));
+    }, [snapshot, definitions, ctx]);
+    const isDefault = useCallback((id) => {
+        if (!definitions.some((d) => d.id === id))
+            throw new Error(`Field '${id}': not among the fields given to useStoredFields`);
+        return !changed.has(id);
+    }, [definitions, changed]);
+    const resetAll = useCallback((method = 'replace') => {
+        store.write(definitions.map((d) => ({ key: d.id, raw: undefined })), method);
+    }, [store, definitions]);
+    return { isDefault, changedCount: changed.size, resetAll };
+}
+//# sourceMappingURL=useStoredField.js.map

package/dist/useStoredField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStoredField.js","sourceRoot":"","sources":["../src/useStoredField.ts"],"names":[],"mappings":"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"}

package/dist/useTextField.d.ts

@@ -0,0 +1,22 @@
+import { type FieldControls, type FieldOptions } from './field.js';
+import { type FieldCtx } from './FieldContext.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+export type TextOwnOptions = {
+    control?: 'input' | 'textarea';
+};
+export type TextFieldOptions<RouteId extends string = string, Ctx = any> = FieldOptions<string, string, RouteId, Ctx> & TextOwnOptions;
+export interface TextFieldControls extends FieldControls<string, string> {
+    control: 'input' | 'textarea';
+}
+/** The implicit initial value for a text field: `initialValue` resolved, else the empty string. */
+export declare function textInitialValue(opts: {
+    initialValue?: ValueOrFn<string>;
+}, ctx: FieldCtx, id: string): string;
+/**
+ * A field whose value is a string (moxb's Text, TextAnt, TextSearchAnt). `control` says whether
+ * vultus-antd renders an input or a textarea; defaults to `'input'`. A field inside the field or
+ * changed locally requests on every change; one that commits holds requests back until the
+ * widget decides (blur or Enter), as any commit-mode field does.
+ */
+export declare function useTextField<RouteId extends string = string, Ctx = any>(opts: TextFieldOptions<RouteId, Ctx>, registry?: ErrorRoutesRegistry<RouteId>): TextFieldControls;
+//# sourceMappingURL=useTextField.d.ts.map

package/dist/useTextField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTextField.d.ts","sourceRoot":"","sources":["../src/useTextField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,IACrE,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,cAAc,CAAC;AAE9D,MAAM,WAAW,iBAAkB,SAAQ,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC;IACtE,OAAO,EAAE,OAAO,GAAG,UAAU,CAAC;CAC/B;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,EAC1C,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,MAAM,GACT,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,EACrE,IAAI,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,EACpC,QAAQ,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACtC,iBAAiB,CAMnB"}

package/dist/useTextField.js

@@ -0,0 +1,21 @@
+import { useFieldCore } from './field.js';
+import { useFieldContext } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+/** The implicit initial value for a text field: `initialValue` resolved, else the empty string. */
+export function textInitialValue(opts, ctx, id) {
+    return resolveIn(opts.initialValue, '', ctx, `Field '${id}': option 'initialValue'`);
+}
+/**
+ * A field whose value is a string (moxb's Text, TextAnt, TextSearchAnt). `control` says whether
+ * vultus-antd renders an input or a textarea; defaults to `'input'`. A field inside the field or
+ * changed locally requests on every change; one that commits holds requests back until the
+ * widget decides (blur or Enter), as any commit-mode field does.
+ */
+export function useTextField(opts, registry) {
+    const ctx = useFieldContext();
+    const inside = !opts.onChange && !opts.commit;
+    const initialValue = () => textInitialValue(opts, ctx, opts.id);
+    const field = useFieldCore('text', inside ? { ...opts, initialValue } : opts, registry);
+    return { ...field, control: opts.control ?? 'input' };
+}
+//# sourceMappingURL=useTextField.js.map

package/dist/useTextField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTextField.js","sourceRoot":"","sources":["../src/useTextField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAYzC,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAC9B,IAA0C,EAC1C,GAAa,EACb,EAAU;IAEV,OAAO,SAAS,CAAS,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,0BAA0B,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAoC,EACpC,QAAuC;IAEvC,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9C,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,YAAY,CAA+B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtH,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;AACxD,CAAC"}

package/dist/useTreeField.d.ts

@@ -0,0 +1,39 @@
+import { type FieldControls, type FieldOptions } from './field.js';
+import { type FieldCtx } from './FieldContext.js';
+import { type TreeExpand, type TreeNode, type TreeNodeControls, type TreeSelection } from './tree.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+export type TreeOwnOptions<T extends string = string, Ctx = any> = {
+    /** The roots, each with its children; static or derived (a function, of the field context if it declares a parameter). */
+    nodes: ValueOrFn<TreeNode<T>[], Ctx>;
+    /** What the value lists; default `'topmost'` (see TreeSelection). */
+    selection?: TreeSelection;
+    /** Which nodes a widget opens at first; default `'top'` (see TreeExpand). */
+    expand?: TreeExpand;
+};
+export type TreeFieldOptions<T extends string = string, RouteId extends string = string, Ctx = any> = FieldOptions<T[], T[], RouteId, Ctx> & TreeOwnOptions<T, Ctx>;
+export interface TreeFieldControls<T extends string = string> extends FieldControls<T[], T[]> {
+    /** The roots as the widgets get them, each with its children. */
+    nodes: TreeNodeControls<T>[];
+    selection: TreeSelection;
+    /** The nodes a widget opens at first (from `expand`). */
+    expandedKeys: T[];
+    /** Every node, by its value. */
+    byValue: Map<T, TreeNodeControls<T>>;
+    /** Checks or unchecks a node (with its subtree, in the cascading selections); ignored (with a warning) for an unknown or disabled node. */
+    toggle(value: T): void;
+}
+/** The implicit initial value for a tree field: `initialValue` resolved, else the empty list. */
+export declare function treeInitialValue<T extends string>(opts: {
+    initialValue?: ValueOrFn<T[]>;
+}, ctx: FieldCtx, id: string): T[];
+/**
+ * A field whose value is a set of tree nodes (Praeceptor's category filter), with antd
+ * TreeSelect's semantics: in the cascading selections a checked node stands for its subtree,
+ * and `selection` says which nodes the value lists (see TreeSelection). The value is shown
+ * and requested normalized (normalizeTreeValue): in tree pre-order, values that name no
+ * node (a stored value naming a removed node) kept at the end. `setValue` does not police
+ * disabled nodes (the widgets disable them); `toggle` refuses a disabled or unknown node with
+ * a warning, as useManyOfField does.
+ */
+export declare function useTreeField<T extends string = string, RouteId extends string = string, Ctx = any>(opts: TreeFieldOptions<T, RouteId, Ctx>, registry?: ErrorRoutesRegistry<RouteId>): TreeFieldControls<T>;
+//# sourceMappingURL=useTreeField.d.ts.map

package/dist/useTreeField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTreeField.d.ts","sourceRoot":"","sources":["../src/useTreeField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAEL,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAC1E,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,IAAI;IACjE,0HAA0H;IAC1H,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACrC,qEAAqE;IACrE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,IAChG,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAEhE,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IAC3F,iEAAiE;IACjE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,SAAS,EAAE,aAAa,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,CAAC,EAAE,CAAC;IAClB,gCAAgC;IAChC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,2IAA2I;IAC3I,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACxB;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE;IAAE,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAA;CAAE,EACvC,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,MAAM,GACT,CAAC,EAAE,CAEL;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,EAChG,IAAI,EAAE,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,EACvC,QAAQ,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACtC,iBAAiB,CAAC,CAAC,CAAC,CAgDtB"}

package/dist/useTreeField.js

@@ -0,0 +1,66 @@
+import { useFieldCore } from './field.js';
+import { resolveChoice } from './choices.js';
+import { useFieldContext } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { coveredNodes, expandedTreeKeys, normalizeTreeValue, toggleTreeValue, } from './tree.js';
+/** The implicit initial value for a tree field: `initialValue` resolved, else the empty list. */
+export function treeInitialValue(opts, ctx, id) {
+    return resolveIn(opts.initialValue, [], ctx, `Field '${id}': option 'initialValue'`);
+}
+function sameList(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/**
+ * A field whose value is a set of tree nodes (Praeceptor's category filter), with antd
+ * TreeSelect's semantics: in the cascading selections a checked node stands for its subtree,
+ * and `selection` says which nodes the value lists (see TreeSelection). The value is shown
+ * and requested normalized (normalizeTreeValue): in tree pre-order, values that name no
+ * node (a stored value naming a removed node) kept at the end. `setValue` does not police
+ * disabled nodes (the widgets disable them); `toggle` refuses a disabled or unknown node with
+ * a warning, as useManyOfField does.
+ */
+export function useTreeField(opts, registry) {
+    const ctx = useFieldContext();
+    const nodes = resolveIn(opts.nodes, [], ctx, `Field '${opts.id}': option 'nodes'`);
+    const selection = opts.selection ?? 'topmost';
+    const inside = !opts.onChange && !opts.commit;
+    const initialValue = () => treeInitialValue(opts, ctx, opts.id);
+    const field = useFieldCore('tree', inside ? { ...opts, initialValue } : opts, registry);
+    // The same list object while it is already normalized, so the value is stable across renders.
+    const normalized = normalizeTreeValue(nodes, field.value, selection);
+    const value = sameList(normalized, field.value) ? field.value : normalized;
+    const checked = new Set(coveredNodes(nodes, value, selection));
+    const byValue = new Map();
+    const control = (node) => {
+        const controls = { ...resolveChoice(opts.id, node), children: undefined, checked: checked.has(node.value) };
+        byValue.set(node.value, controls);
+        if (node.children)
+            controls.children = node.children.map(control);
+        return controls;
+    };
+    const nodeControls = nodes.map(control);
+    const setValue = (next) => field.setValue(normalizeTreeValue(nodes, next, selection));
+    const toggle = (v) => {
+        const node = byValue.get(v);
+        if (!node) {
+            console.warn(`Field '${opts.id}': '${v}' is not one of its nodes`);
+            return;
+        }
+        if (!node.enabled) {
+            console.warn(`Field '${opts.id}': node '${v}' is disabled — ${node.whyDisabled ?? '(no reason)'}`);
+            return;
+        }
+        field.setValue(toggleTreeValue(nodes, value, v, selection));
+    };
+    return {
+        ...field,
+        value,
+        setValue,
+        nodes: nodeControls,
+        selection,
+        expandedKeys: expandedTreeKeys(nodes, value, opts.expand ?? 'top'),
+        byValue,
+        toggle,
+    };
+}
+//# sourceMappingURL=useTreeField.js.map

package/dist/useTreeField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTreeField.js","sourceRoot":"","sources":["../src/useTreeField.ts"],"names":[],"mappings":"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"}

package/dist/valueTypes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How a value is kept in a store as a string (moxb's url-arg types): a URL query, localStorage.
+ * A stored string comes from outside (an edited or old URL), so `parse` never throws: a string
+ * that stands for no value gives `undefined`, and the caller falls back to its default.
+ * `isEqual` is the value's meaning (a list as a set, a range by both ends), used everywhere two
+ * values are compared, e.g. to leave a default out of the store.
+ */
+export interface ValueType<T> {
+    parse(raw: string): T | undefined;
+    format(value: T): string;
+    isEqual(a: T, b: T): boolean;
+}
+/** A boolean as `1` / `0`; any other string is no value. */
+export declare const booleanType: ValueType<boolean>;
+/** A string as itself. */
+export declare const stringType: ValueType<string>;
+/**
+ * A set of strings as a sorted comma list; the empty string is the empty list (so a list
+ * present but empty differs from an absent one). Reading drops empty items. An item containing
+ * `,`, or an empty one (it would read back as no item), cannot be stored and throws: that is the
+ * definer's mistake, not outside input.
+ */
+export declare const stringSetType: ValueType<string[]>;
+/** A finite number as its decimal string; an empty or non-numeric string is no value. */
+export declare const numberType: ValueType<number>;
+/** A `[from, to]` range as `from..to`; ends that are not numbers, or out of order, are no value. */
+export declare const rangeType: ValueType<[number, number]>;
+//# sourceMappingURL=valueTypes.d.ts.map

package/dist/valueTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valueTypes.d.ts","sourceRoot":"","sources":["../src/valueTypes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;CAC9B;AAED,4DAA4D;AAC5D,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,OAAO,CAI1C,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,UAAU,EAAE,SAAS,CAAC,MAAM,CAIxC,CAAC;AAOF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,CAa7C,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,EAAE,SAAS,CAAC,MAAM,CAQxC,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAWjD,CAAC"}

package/dist/valueTypes.js

@@ -0,0 +1,65 @@
+/** A boolean as `1` / `0`; any other string is no value. */
+export const booleanType = {
+    parse: (raw) => (raw === '1' ? true : raw === '0' ? false : undefined),
+    format: (value) => (value ? '1' : '0'),
+    isEqual: (a, b) => a === b,
+};
+/** A string as itself. */
+export const stringType = {
+    parse: (raw) => raw,
+    format: (value) => value,
+    isEqual: (a, b) => a === b,
+};
+/** A set's canonical form: sorted, without duplicates. */
+function canonicalSet(items) {
+    return [...new Set(items)].sort();
+}
+/**
+ * A set of strings as a sorted comma list; the empty string is the empty list (so a list
+ * present but empty differs from an absent one). Reading drops empty items. An item containing
+ * `,`, or an empty one (it would read back as no item), cannot be stored and throws: that is the
+ * definer's mistake, not outside input.
+ */
+export const stringSetType = {
+    parse: (raw) => canonicalSet(raw.split(',').filter((item) => item !== '')),
+    format: (value) => {
+        if (value.includes(''))
+            throw new Error(`'' is empty and cannot be stored in a list`);
+        const bad = value.find((item) => item.includes(','));
+        if (bad !== undefined)
+            throw new Error(`'${bad}' contains ',' and cannot be stored in a list`);
+        return canonicalSet(value).join(',');
+    },
+    isEqual: (a, b) => {
+        const x = canonicalSet(a);
+        const y = canonicalSet(b);
+        return x.length === y.length && x.every((item, i) => item === y[i]);
+    },
+};
+/** A finite number as its decimal string; an empty or non-numeric string is no value. */
+export const numberType = {
+    parse: (raw) => {
+        if (raw.trim() === '')
+            return undefined;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : undefined;
+    },
+    format: (value) => String(value),
+    isEqual: (a, b) => a === b,
+};
+/** A `[from, to]` range as `from..to`; ends that are not numbers, or out of order, are no value. */
+export const rangeType = {
+    parse: (raw) => {
+        const ends = raw.split('..');
+        if (ends.length !== 2)
+            return undefined;
+        const from = numberType.parse(ends[0]);
+        const to = numberType.parse(ends[1]);
+        if (from === undefined || to === undefined || from > to)
+            return undefined;
+        return [from, to];
+    },
+    format: ([from, to]) => `${from}..${to}`,
+    isEqual: (a, b) => a[0] === b[0] && a[1] === b[1],
+};
+//# sourceMappingURL=valueTypes.js.map

package/dist/valueTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valueTypes.js","sourceRoot":"","sources":["../src/valueTypes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vultus-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "description": "Framework-neutral action model + hooks for vultus (antd-free by design)",
   "repository": {

package/src/ArgStoreContext.tsx

@@ -0,0 +1,16 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import type { ArgStore } from './argStore.js';
+
+const ArgStoreContext = createContext<ArgStore | undefined>(undefined);
+
+/** Gives the subtree below an ArgStore (Praeceptor: the URL store around the module page, localStorage around the print dialog). */
+export function ArgStoreProvider({ store, children }: { store: ArgStore; children?: ReactNode }) {
+  return <ArgStoreContext.Provider value={store}>{children}</ArgStoreContext.Provider>;
+}
+
+/** The nearest ArgStoreProvider's store; a hook with none above it fails loudly rather than reading nothing. */
+export function useArgStore(): ArgStore {
+  const store = useContext(ArgStoreContext);
+  if (store === undefined) throw new Error('No ArgStoreProvider is above this component');
+  return store;
+}

package/src/FieldContext.tsx

@@ -0,0 +1,98 @@
+import { createContext, useContext, useMemo, type JSX, type ReactNode } from 'react';
+
+/**
+ * What useFieldContext gives when no FieldContextProvider is above: a field's function that
+ * declares a parameter then has nothing to receive, and resolving it throws.
+ */
+export const NO_FIELD_CONTEXT: unique symbol = Symbol('vultus.noFieldContext');
+
+/** The field context as the hooks hold it: the guarded value, or the mark that there is none. */
+export type FieldCtx = object | typeof NO_FIELD_CONTEXT;
+
+/** The merged value of the providers above, and the same value guarded against missing keys. */
+interface Provided {
+  raw: object;
+  guarded: object;
+}
+
+const FieldContext = createContext<Provided | undefined>(undefined);
+
+/**
+ * Keys that libraries read to find out what an object is (a thenable, JSON, a test matcher, a
+ * React element, a DOM node or element, a mock function), and the `@@`-prefixed sentinels
+ * (Immutable's) that printers such as pretty-format test for. Reading them on the context is a
+ * probe, not a mistake.
+ */
+const PROBED_KEYS = new Set([
+  'then', 'toJSON', 'asymmetricMatch', '$$typeof', 'nodeType', 'tagName', 'hasAttribute', '_isMockFunction',
+]);
+
+function isProbe(key: string): boolean {
+  return PROBED_KEYS.has(key) || key.startsWith('@@');
+}
+
+/** What the guard throws for a key no provider gave, so readingContext can tell it from the function's own errors. */
+class MissingKeyError extends Error {}
+
+/**
+ * The context value as the definitions' functions receive it: reading a key that no provider
+ * gave throws, naming it and the keys present, so a forgotten value fails loudly instead of
+ * passing `undefined` along. A key provided with the value `undefined` is fine.
+ */
+function guard(raw: object): object {
+  return new Proxy(raw, {
+    get(target, key, receiver) {
+      if (typeof key === 'string' && !isProbe(key) && !(key in target)) {
+        throw new MissingKeyError(`Field context: '${key}' was never provided (provided: ${Object.keys(target).join(', ')})`);
+      }
+      return Reflect.get(target, key, receiver);
+    },
+  });
+}
+
+/**
+ * Runs `read`, a call of a definition's function with the field context. A key it reads that
+ * no provider gave throws with `where` (`Field '<id>': option '<name>'`) in front of the
+ * guard's message, so the error names the field and the option as well as the key; any other
+ * error passes through unchanged.
+ */
+export function readingContext<T>(where: string, read: () => T): T {
+  try {
+    return read();
+  } catch (error) {
+    if (error instanceof MissingKeyError) throw new Error(`${where}: ${error.message}`, { cause: error });
+    throw error;
+  }
+}
+
+/**
+ * Gives the fields below a context, the argument their definitions' functions receive. Nested
+ * providers merge, the inner value winning: an app can provide `t` near the root and the data
+ * a page shows further down.
+ */
+export function FieldContextProvider({ value, children }: { value: object; children?: ReactNode }) {
+  const outer = useContext(FieldContext);
+  // Memoized on the outer context and `value`: a caller passing a fresh object literal gets a
+  // new context every render anyway; a stable `value` keeps the fields below from re-rendering.
+  const provided = useMemo(() => {
+    const raw = { ...outer?.raw, ...value };
+    return { raw, guarded: guard(raw) };
+  }, [outer, value]);
+  return <FieldContext.Provider value={provided}>{children}</FieldContext.Provider>;
+}
+
+/**
+ * A FieldContextProvider typed for the context `Ctx` an app's definitions are written against.
+ * It is the same provider (one React context), so typed providers nest and merge with each
+ * other and with the untyped one; each gives part of the context.
+ */
+export function createFieldContext<Ctx extends object>(): {
+  Provider: (props: { value: Partial<Ctx>; children?: ReactNode }) => JSX.Element;
+} {
+  return { Provider: FieldContextProvider };
+}
+
+/** The field context the hooks resolve functions with: the guarded value, or NO_FIELD_CONTEXT. */
+export function useFieldContext(): FieldCtx {
+  return useContext(FieldContext)?.guarded ?? NO_FIELD_CONTEXT;
+}