vultus-core 0.3.0 → 0.5.0

package/README.md

@@ -20,10 +20,22 @@ npm install vultus-core
 
 - `.` — the action model, exporting: the core `types`, `decision`, `resolve`,
   `parseApiError`, `routeApiError`, `ActionErrorContext` / `useActionErrorCtx`,
-  `useAction`, `useActionList`, the fields (`useBoolField`, `useFieldCore` and
-  their types), `InternalLinkContext` / `useInternalLink` /
-  `InternalLinkComponent`, and `MessageSinkContext` / `useMessageSink` /
-  `MessageSink`.
+  `useAction`, `useActionList`; the field context (`FieldContextProvider`,
+  `createFieldContext`, `useFieldContext`, `NO_FIELD_CONTEXT`); every field
+  kind's hook (`useBoolField`, `useMixedBoolField`, `useOneOfField`,
+  `useManyOfField`, `useNumericField`, `useRangeField`, `useTreeField`,
+  `useTextField`, `useFieldCore` and their types) and their shared helpers
+  (`resolveChoice`, `normalizeText`, `clamp`, `resolveNumeric`, the tree
+  helpers `normalizeTreeValue` / `coveredNodes` / `toggleTreeValue` /
+  `expandedTreeKeys` / `filterTree`); definitions as data (`FieldDefinition`,
+  `initialValueOf`, `valueTypeOf`, `sanitizeStored`); the argument layer
+  (the value types, `memoryStore`, `localStorageStore`, `ArgStoreProvider` /
+  `useArgStore`, `useArg`, `useArgWriter`, `setArg` / `resetArg`, `argOf`,
+  `useStoredField` / `useStoredFields`); `InternalLinkContext` /
+  `useInternalLink` / `InternalLinkComponent`, `MessageSinkContext` /
+  `useMessageSink` / `MessageSink`, and `VultusComponentsContext` /
+  `useVultusComponents` / `SpinnerScope` / `useSpinnerKey` /
+  `VultusComponents` / `SpinnerProps` / `SpinnerComponent`.
 - `./link` — `InternalLinkContext`, `useInternalLink`, and the
   `InternalLinkComponent` type on their own, for consumers that only need the
   link-injection seam.
@@ -71,6 +83,309 @@ boolean field (inside: `initialValue`, default the first enabled choice); `confi
 depend on the requested choice. vultus-antd's `OneOfSelect` and `OneOfSegmented` take the
 same field.
 
+## Field context
+
+A field's options may depend on something only the app knows — a translation
+function, the data a page is showing. `createFieldContext<Ctx>()` returns a
+typed `Provider` (it's `FieldContextProvider` itself, just typed); the hooks
+read the nearest one. Nested providers merge, the inner value winning, so an
+app can provide `t` near the root and `items` further down the tree.
+
+Every option that takes a `ValueOrFn<T, Ctx>` (`T | ((ctx: Ctx) => T)`) may be
+a plain value or a function of the context. With a provider above, every
+function receives the nearest provider's value, whatever parameters it
+declares — `(ctx = {}) => ...` gets it too. With none, a function with no
+declared parameter (`() => ...`) is called with nothing, so it runs without
+needing a provider at all, while one that declares a parameter (`(ctx) =>
+...`) is a loud failure: an error naming the field, the option, and that no
+`FieldContextProvider` is above it. This goes by the function's declared
+parameter count, so a default parameter (`(ctx = {}) => ...`) escapes that
+check and, with no provider, runs with its default. A function that returns
+`undefined` counts as an absent option too, and falls back to the option's
+own default exactly as leaving it out would (useful for a lookup that
+misses, e.g. `(ctx) => ctx.items[id]`). Numeric's `format(n, ctx)` follows
+the same rule for its second parameter.
+
+The provided value is wrapped so that reading a key no provider gave throws,
+naming the key and the keys that are present, and, when an option's
+function reads it, the field and the option in front (`Field 'sec': option
+'label': Field context: 'items' was never provided (provided: t, lang)`) — a
+forgotten value fails loudly instead of silently becoming `undefined`. A key
+explicitly provided as `undefined` is fine. The wrapper lets test tooling and
+printers probe the object without tripping the guard (`then`, `toJSON`,
+`asymmetricMatch`, `$$typeof`, `nodeType`, `tagName`, `hasAttribute`,
+`_isMockFunction`, any key starting with `@@`, and all symbol keys), so a
+context value can be logged, pattern-matched or passed around during tests
+without the guard misfiring.
+
+```tsx
+const { Provider: ModuleContext } = createFieldContext<{ items: Item[] }>();
+
+function Filters({ items }: { items: Item[] }) {
+  return (
+    <ModuleContext value={{ items }}>
+      <Categories />
+    </ModuleContext>
+  );
+}
+
+function Categories() {
+  const field = useManyOfField({ id: 'categories', choices: (ctx) => categoriesOf(ctx.items) });
+  // ...
+}
+```
+
+## More kinds
+
+Next to `useBoolField` and `useOneOfField`, the other field kinds. Each is
+built the same way (`useFieldCore`, the same inside / local / commit
+storage), so everything the Fields section above says about storage,
+visibility, enabling and commits applies to all of them too.
+
+### many-of (`useManyOfField`)
+
+The value is a list of choices (`OneOfChoice`, as one-of's), kept as a set:
+order and duplicates don't matter to its meaning, and every request (through
+`setValue` or `toggle`) is normalized to choice order without duplicates,
+followed by the values the field already holds that are no longer among the
+choices and that the request keeps, in their current order. `toggle` keeps
+them, so a stored value naming a removed choice isn't silently dropped;
+`setValue([])` clears them along with everything else. Controls add
+`choices` (each with `selected`), `isSelected(value)` and `toggle(value)`. A request naming
+an unknown choice, or flipping a disabled one, is refused with a
+`console.warn` — the hook itself polices this, as `useOneOfField` already
+does for its own `setValue`, not just the widget. Implicit initial value
+(with no `initialValue` and no outside storage): the empty list.
+
+```ts
+const field = useManyOfField({
+  id: 'tags',
+  choices: [{ value: 'urgent' }, { value: 'archived', disabled: true }],
+});
+field.toggle('urgent'); // field.isSelected('urgent') === true
+```
+
+### numeric (`useNumericField`)
+
+The value is a single number. `min`, `max`, `step`, `integer` (moxb's
+`onlyInteger`) and `unit` may each be a context function; `format(n, ctx)`
+overrides the default display (the number followed by the unit, if any).
+The shown value is always clamped into the bounds, then rounded when
+`integer` (a stored `2.5` shows `3`), since a value from outside — a
+passed-in `value`, a stored one — may fall outside them or be fractional
+even though every request the hook itself makes fits; a non-finite request
+(a widget that parsed `''`) is refused with a warning. `valueText` carries
+the formatted value. Implicit initial value: `min` (or `0` if there is
+none), clamped into the bounds.
+
+```ts
+const field = useNumericField({ id: 'count', min: 0, max: 10, unit: 'pcs' });
+field.valueText; // '0pcs'
+```
+
+### range (`useRangeField`)
+
+The value is a `NumberRange`, `[from, to]` with `min <= from <= to <= max`;
+it shares numeric's bounds and formatting, but `min` and `max` are required
+here and `step` defaults to `1`. `valueText` joins the formatted ends with
+an en dash ("2010/11–2025/26"), so a layout can put the whole range in the
+field's label instead of next to it. A value from outside is clamped into
+the bounds end by end, rounded when `integer`, then ordered. Implicit
+initial value: `[min, max]`.
+
+```ts
+const field = useRangeField({ id: 'years', min: 2010, max: 2026 });
+field.valueText; // '2010–2026'
+```
+
+### tree (`useTreeField`)
+
+The value is a list of node ids (`nodes`: `TreeNode`, a choice with
+`children`), kept as a set. `selection` says which of the covered nodes the
+value names: `'topmost'` (default; antd's `SHOW_PARENT`: a checked node
+stands for its whole subtree), `'all'`, `'leaves'` (`SHOW_CHILD`), or
+`'independent'` (`checkStrictly`, moxb's `strictSelect`: nodes are chosen on
+their own, with no cascading). The hook normalizes the value under
+`selection` on every render — with `'topmost'`, a node and all its checked
+children collapse to the node alone — and exposes `expandedKeys` (which
+nodes a widget opens at first, controlled by `expand`: `'top'` (default),
+`'none'`, `'selected'`, `'all'`) and `toggle(value)` (refused, with a
+warning, for an unknown or disabled node, as many-of's does).
+`coveredNodes(nodes, value, selection)` expands a value to every node it
+stands for — what a module matches an item's categories against. Search
+over labels is accent- and case-insensitive (`normalizeText`); the matching
+`filterTree(nodes, query)` follows antd TreeSelect's rule: a node whose own
+label matches stays with its whole subtree, any other node stays if one of
+its descendants matches (with only the children that stay), and the rest
+is trimmed, leaving the nodes given unchanged. Implicit initial value: the
+empty list.
+
+```ts
+const field = useTreeField({
+  id: 'categories',
+  nodes: [{ value: 'a', children: [{ value: 'a1' }, { value: 'a2' }] }],
+});
+field.toggle('a'); // field.value === ['a'] — 'topmost' collapses the subtree to the parent
+```
+
+### text (`useTextField`)
+
+The value is a string. `control: 'input' | 'textarea'` (default `'input'`)
+is a hint for the widget, nothing else. A field inside the field or changed
+locally (`onChange`) requests on every keystroke, as moxb's, sidedao's and
+Taskmaster's text fields do; a field that `commits` holds requests back
+until the widget decides (blur or Enter) — any commit-mode field does this,
+not something specific to text. Highlighting the search words in a result
+list is the app's job (e.g. quaesitor's `WithSearch`), not this hook's.
+Implicit initial value: the empty string.
+
+```ts
+const field = useTextField({ id: 'search', control: 'input' });
+```
+
+## Definitions as data
+
+A `FieldDefinition` is a field's options in their "inside" form (no `value`
+plus `onChange` or `commit`), tagged with a required `kind` — one of
+`'boolean'`, `'mixed-boolean'`, `'oneOf'`, `'manyOf'`, `'numeric'`,
+`'range'`, `'tree'`, `'text'` (the same strings `FieldControls.type` already
+carries). `kind` stays optional on each hook's own options — a hook knows
+its own kind, and throws if a definition names a different one — but is
+required once a field becomes plain data: a module declares its filters as a
+list of `FieldDefinition`s, independent of which hook or widget ends up
+running each one.
+
+A definer who doesn't care where the value lives gives only `initialValue`
+(or nothing, for the kind's implicit default); whoever runs the field — a
+hook directly, or `useStoredField` (see Arguments, below) — chooses the
+storage. `initialValueOf(definition, ctx)` is every kind's default in one
+place, and the entry point for it: what a definition with no `initialValue`
+starts at, what a reset restores, and what "is it changed?" compares
+against — `false`; the first enabled choice; the empty list; `min` (or `0`)
+clamped into the bounds; `[min, max]`; the empty string for text; for a
+tree, the value normalized under its `selection`. (The per-kind helpers it
+is built on — `boolInitialValue`, `oneOfInitialValue`, `rangeInitialValue`
+and the like — are exported too.) A hook computes its kind's default once,
+when the field mounts, not on every render.
+
+The `widget` hint (`WidgetHint = string | { name: string; [option]: unknown
+}`) names which widget renders the field — `'segmented'`, or `{ name:
+'segmented', iconOnly: true }` with its display options — without
+vultus-core knowing what a "segmented control" is; it's vultus-antd that
+turns the name into a component, applying render-site overrides on top.
+Each kind has a default widget when none is given; an unknown widget name
+throws, in vultus-antd.
+
+```ts
+const definitions: FieldDefinition[] = [
+  { kind: 'boolean', id: 'showArchived' },
+  { kind: 'numeric', id: 'count', min: 0, max: 10, widget: 'slider' },
+];
+initialValueOf(definitions[0], {}); // false
+```
+
+## Arguments
+
+Storage outside a field hook — a URL, localStorage — lives in vultus-core as
+its own layer (ported from moxb's `url-arg`, without mobx), independent of
+the field hooks: an argument is `{ key, valueType, default }`, kept in
+whatever `ArgStore` is nearest.
+
+**Value types** (`ValueType<T>`: `parse(raw)`, `format(value)`, `isEqual(a,
+b)`) say how a value is kept as a string and compared; equality is the
+type's own meaning (a list as a set, a range by both ends), used everywhere
+two values of that type are compared — including whether a value is the
+default, so it's left out of the store. `valueTypeOf(kind)` gives each field
+kind's: `booleanType` (`'1'` / `'0'`), `stringType` (one-of, text),
+`stringSetType` (many-of, tree — a sorted comma list; a *present but empty*
+value reads as the empty list, which differs from the key being absent
+altogether), `numberType`, `rangeType` (`from..to`). A mixed-boolean field
+shows an aggregate of other data and has no value type:
+`valueTypeOf('mixed-boolean')` throws, and so does storing one. A choice
+value containing `,`, or an empty one, cannot be written to a list and
+throws — that's the definer's mistake, not outside input. A stored string
+that doesn't parse, or names a choice or node that no longer exists, *is*
+outside input (an edited or stale URL): it never throws, it falls back to
+the default (or is dropped from a list), with a `console.warn`.
+
+**Stores.** `ArgStore` is `read(key)`, `write(changes, method)` (`method`:
+`'push'` or `'replace'`; a store without history ignores it),
+`subscribe(listener)`, and optionally `hrefFor(changes)`. vultus-core ships
+`memoryStore()` (tests, demos) and `localStorageStore(prefix)` (keys
+namespaced as `${prefix}.${key}`, guarded for SSR so creating one outside a
+browser is a safe no-op; where the browser blocks storage or refuses a
+write, a failing read reads as absent and a failing write is skipped, with
+one `console.warn` per store); a URL store comes from a router package.
+Create a store once — outside render, or in `useMemo` — not on every
+render: each store is a new subscription target, so a fresh one per render
+makes every hook below resubscribe.
+`<ArgStoreProvider store={...}>` gives a subtree its store — nest providers
+to put the URL around a page and localStorage around a dialog inside it. A
+hook with no `ArgStoreProvider` above it throws, rather than silently
+reading nothing.
+
+**`useArg(definition)`** reads and writes one argument: `value`,
+`isDefault`, `set(value, method?)`, `reset(method?)` and `hrefFor(value)`
+(where the store supports it). An absent key reads as the default; writing a
+value that equals the default removes the key instead of storing it.
+
+**Batches.** `useArgWriter()` returns `apply(changes, method)` where each
+change is `setArg(definition, value)` or `resetArg(definition)` — several
+arguments change in one store write, one history entry (a "clear all"
+button, a filter chip that also closes a detail view).
+
+**Fields over arguments.** `argOf(definition, ctx)` is the argument a
+definition's value is stored as — key = the definition's `id`, value type
+from its kind, default = its resolved initial value — for a caller that
+wants `useArg` directly instead of a field. `useStoredField(definition)`
+runs a `FieldDefinition` as a stored field the same way: the argument's key
+is the definition's `id`, its value type comes from the kind, its default
+is `initialValueOf`. It returns `{ options, isDefault, reset }` — `options`
+is the definition in its outside form (`value` plus `onChange`, ready for
+the kind's hook), with the stored raw value made to fit the definition as
+it is now (`sanitizeStored`: unknown choices or nodes dropped, numbers and
+ranges clamped). A value that needed fixing up warns once per field and per raw
+value — not again on every render, and not at all when the key is simply
+absent (then the default applies, and an absent key is not outside input).
+`useStoredFields(definitions)` answers for several definitions over one
+store subscription: `isDefault(id)` (throws for an id not among the
+definitions), `changedCount`, and `resetAll(method)` (one write for every
+field). Being a summary, it never warns — only `useStoredField` on the
+field itself does.
+
+```tsx
+const store = memoryStore();
+
+function Filters() {
+  return (
+    <ArgStoreProvider store={store}>
+      <Category />
+    </ArgStoreProvider>
+  );
+}
+
+function Category() {
+  const { options, reset } = useStoredField({ kind: 'manyOf', id: 'tags', choices: [{ value: 'urgent' }] });
+  const field = useManyOfField(options);
+  // ...
+}
+```
+
+## Components
+
+`VultusComponentsContext` (default `{}`) / `useVultusComponents()` is how an app lends its own
+UI to vultus/optio in place of their native indicators — today just `Spinner` (`SpinnerProps`:
+`spinnerKey`, `size?`, `label?`; `VultusComponents.Spinner?: SpinnerComponent`). vultus-antd's
+`VultusProvider` merges a `components` prop into the outer context value; without one, the
+outer value (or this default) applies, as `linkComponent` does today.
+
+Every call site that may render a lent `Spinner` asks for its key through `useSpinnerKey(localKey)`
+rather than hardcoding it, so an app can scope a whole subtree's keys to one instance:
+`<SpinnerScope name="optio:process:p1">` makes every `useSpinnerKey` call inside it return
+`'optio:process:p1/' + localKey`; scopes nest by joining names with `/`, outermost first.
+Library-local keys are namespaced (`vultus:...`, `optio:...`) so they never collide with an
+app's own keys.
+
 ## Distribution
 
 This package ships compiled ESM (`dist/`) with TypeScript declarations to

package/dist/ArgStoreContext.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { ArgStore } from './argStore.js';
+/** Gives the subtree below an ArgStore (Praeceptor: the URL store around the module page, localStorage around the print dialog). */
+export declare function ArgStoreProvider({ store, children }: {
+    store: ArgStore;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The nearest ArgStoreProvider's store; a hook with none above it fails loudly rather than reading nothing. */
+export declare function useArgStore(): ArgStore;
+//# sourceMappingURL=ArgStoreContext.d.ts.map

package/dist/ArgStoreContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgStoreContext.d.ts","sourceRoot":"","sources":["../src/ArgStoreContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C,oIAAoI;AACpI,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAE9F;AAED,gHAAgH;AAChH,wBAAgB,WAAW,IAAI,QAAQ,CAItC"}

package/dist/ArgStoreContext.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+const ArgStoreContext = createContext(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 }) {
+    return _jsx(ArgStoreContext.Provider, { value: store, children: children });
+}
+/** The nearest ArgStoreProvider's store; a hook with none above it fails loudly rather than reading nothing. */
+export function useArgStore() {
+    const store = useContext(ArgStoreContext);
+    if (store === undefined)
+        throw new Error('No ArgStoreProvider is above this component');
+    return store;
+}
+//# sourceMappingURL=ArgStoreContext.js.map

package/dist/ArgStoreContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgStoreContext.js","sourceRoot":"","sources":["../src/ArgStoreContext.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,OAAO,CAAC;AAGlE,MAAM,eAAe,GAAG,aAAa,CAAuB,SAAS,CAAC,CAAC;AAEvE,oIAAoI;AACpI,MAAM,UAAU,gBAAgB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAA6C;IAC7F,OAAO,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA4B,CAAC;AACvF,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,WAAW;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACxF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/Components.d.ts

@@ -0,0 +1,30 @@
+import { type ComponentType, type ReactNode } from 'react';
+/** A spinner an app lends to vultus/optio, rendered in place of their native loading indicators. */
+export interface SpinnerProps {
+    /** The spinner's identity: stable across re-renders and remounts, unique on the page (after scoping). */
+    spinnerKey: string;
+    /** antd's names (the height of antd's Spin indicator) or a height in px. */
+    size?: 'small' | 'default' | 'large' | number;
+    /** Accessible label; the spinner's own default when omitted. */
+    label?: string;
+}
+export type SpinnerComponent = ComponentType<SpinnerProps>;
+/** Components an app lends to the libraries. */
+export interface VultusComponents {
+    Spinner?: SpinnerComponent;
+}
+/**
+ * The components an app lends to vultus/optio in place of their own UI. Default is `{}`
+ * (none lent) so vultus-core stays framework-neutral; vultus-antd's `VultusProvider` merges
+ * in whatever an app passes as `components`.
+ */
+export declare const VultusComponentsContext: import("react").Context<VultusComponents>;
+export declare function useVultusComponents(): VultusComponents;
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export declare function SpinnerScope({ name, children }: {
+    name: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export declare function useSpinnerKey(localKey: string): string;
+//# sourceMappingURL=Components.d.ts.map

package/dist/Components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Components.d.ts","sourceRoot":"","sources":["../src/Components.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/F,oGAAoG;AACpG,MAAM,WAAW,YAAY;IAC3B,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;AAE3D,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,2CAAsC,CAAC;AAE3E,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAKD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAOtF;AAED,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/Components.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+/**
+ * The components an app lends to vultus/optio in place of their own UI. Default is `{}`
+ * (none lent) so vultus-core stays framework-neutral; vultus-antd's `VultusProvider` merges
+ * in whatever an app passes as `components`.
+ */
+export const VultusComponentsContext = createContext({});
+export function useVultusComponents() {
+    return useContext(VultusComponentsContext);
+}
+/** The scope path (segment names, outermost first) that `useSpinnerKey` prefixes onto local keys. */
+const SpinnerScopeContext = createContext([]);
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export function SpinnerScope({ name, children }) {
+    const outer = useContext(SpinnerScopeContext);
+    // Memoized so consumers below (useSpinnerKey, via SpinnerScopeContext) don't re-render
+    // on every SpinnerScope re-render — only when the scope path actually changes. Matters
+    // once whole conversation views sit inside a SpinnerScope.
+    const scope = useMemo(() => [...outer, name], [outer, name]);
+    return _jsx(SpinnerScopeContext.Provider, { value: scope, children: children });
+}
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export function useSpinnerKey(localKey) {
+    const scope = useContext(SpinnerScopeContext);
+    return [...scope, localKey].join('/');
+}
+//# sourceMappingURL=Components.js.map

package/dist/Components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Components.js","sourceRoot":"","sources":["../src/Components.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAsC,MAAM,OAAO,CAAC;AAkB/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,aAAa,CAAmB,EAAE,CAAC,CAAC;AAE3E,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,uBAAuB,CAAC,CAAC;AAC7C,CAAC;AAED,qGAAqG;AACrG,MAAM,mBAAmB,GAAG,aAAa,CAAW,EAAE,CAAC,CAAC;AAExD,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAA0C;IACrF,MAAM,KAAK,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC9C,uFAAuF;IACvF,uFAAuF;IACvF,2DAA2D;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7D,OAAO,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAgC,CAAC;AAC/F,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC"}

package/dist/FieldContext.d.ts

@@ -0,0 +1,38 @@
+import { 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 declare const NO_FIELD_CONTEXT: unique symbol;
+/** 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;
+/**
+ * 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 declare function readingContext<T>(where: string, read: () => T): T;
+/**
+ * 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 declare function FieldContextProvider({ value, children }: {
+    value: object;
+    children?: ReactNode;
+}): JSX.Element;
+/**
+ * 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 declare function createFieldContext<Ctx extends object>(): {
+    Provider: (props: {
+        value: Partial<Ctx>;
+        children?: ReactNode;
+    }) => JSX.Element;
+};
+/** The field context the hooks resolve functions with: the guarded value, or NO_FIELD_CONTEXT. */
+export declare function useFieldContext(): FieldCtx;
+//# sourceMappingURL=FieldContext.d.ts.map

package/dist/FieldContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldContext.d.ts","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAwC,CAAC;AAE/E,iGAAiG;AACjG,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,gBAAgB,CAAC;AA2CxD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,eAShG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,SAAS,MAAM,KAAK;IACxD,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,KAAK,GAAG,CAAC,OAAO,CAAC;CACjF,CAEA;AAED,kGAAkG;AAClG,wBAAgB,eAAe,IAAI,QAAQ,CAE1C"}

package/dist/FieldContext.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } 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 = Symbol('vultus.noFieldContext');
+const FieldContext = createContext(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) {
+    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) {
+    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(where, read) {
+    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 }) {
+    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 _jsx(FieldContext.Provider, { value: provided, children: children });
+}
+/**
+ * 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() {
+    return { Provider: FieldContextProvider };
+}
+/** The field context the hooks resolve functions with: the guarded value, or NO_FIELD_CONTEXT. */
+export function useFieldContext() {
+    return useContext(FieldContext)?.guarded ?? NO_FIELD_CONTEXT;
+}
+//# sourceMappingURL=FieldContext.js.map

package/dist/FieldContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldContext.js","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAA4B,MAAM,OAAO,CAAC;AAErF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAW/E,MAAM,YAAY,GAAG,aAAa,CAAuB,SAAS,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB;CAC1G,CAAC,CAAC;AAEH,SAAS,OAAO,CAAC,GAAW;IAC1B,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,sHAAsH;AACtH,MAAM,eAAgB,SAAQ,KAAK;CAAG;AAEtC;;;;GAIG;AACH,SAAS,KAAK,CAAC,GAAW;IACxB,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE;QACpB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ;YACvB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;gBACjE,MAAM,IAAI,eAAe,CAAC,mBAAmB,GAAG,mCAAmC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxH,CAAC;YACD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAI,KAAa,EAAE,IAAa;IAC5D,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,eAAe;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAA2C;IAC/F,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,4FAA4F;IAC5F,8FAA8F;IAC9F,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE;QAC5B,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;QACxC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IACtC,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACnB,OAAO,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAQ,YAAG,QAAQ,GAAyB,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAGhC,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC;AAC5C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,IAAI,gBAAgB,CAAC;AAC/D,CAAC"}

package/dist/argStore.d.ts

@@ -0,0 +1,26 @@
+/** Whether a write pushes a new history entry or replaces the current one; a store without history ignores it. */
+export type UpdateMethod = 'push' | 'replace';
+/** One key's new raw value, or `undefined` to remove it (the key reads back as its default). */
+export interface RawChange {
+    key: string;
+    raw: string | undefined;
+}
+/**
+ * A store for argument values kept as strings (moxb's url-arg backends, batched): a URL query,
+ * localStorage, or (here) memory. `read` and `write` move raw strings only — parsing, defaults
+ * and equality live in the value type and in useArg, not here. The hooks call its methods on
+ * the store, never detached, so a store may be a class whose methods use `this`.
+ */
+export interface ArgStore {
+    read(key: string): string | undefined;
+    /** Applies every change, then notifies subscribers once — several keys changed together are one history entry. */
+    write(changes: RawChange[], method: UpdateMethod): void;
+    subscribe(listener: () => void): () => void;
+    /** The href a write of `changes` would produce, where the store has one (a URL store); omitted otherwise. */
+    hrefFor?(changes: RawChange[]): string;
+}
+/** An ArgStore over a plain object, for tests and demos. `snapshot()` is a copy, for assertions. */
+export declare function memoryStore(initial?: Record<string, string>): ArgStore & {
+    snapshot(): Record<string, string>;
+};
+//# sourceMappingURL=argStore.d.ts.map

package/dist/argStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argStore.d.ts","sourceRoot":"","sources":["../src/argStore.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9C,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,kHAAkH;IAClH,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACxD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,6GAA6G;IAC7G,OAAO,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;CACxC;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,QAAQ,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAuBnH"}

package/dist/argStore.js

@@ -0,0 +1,27 @@
+/** An ArgStore over a plain object, for tests and demos. `snapshot()` is a copy, for assertions. */
+export function memoryStore(initial = {}) {
+    const data = { ...initial };
+    const listeners = new Set();
+    return {
+        read(key) {
+            return data[key];
+        },
+        write(changes, _method) {
+            for (const { key, raw } of changes) {
+                if (raw === undefined)
+                    delete data[key];
+                else
+                    data[key] = raw;
+            }
+            listeners.forEach((listener) => listener());
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { ...data };
+        },
+    };
+}
+//# sourceMappingURL=argStore.js.map

package/dist/argStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argStore.js","sourceRoot":"","sources":["../src/argStore.ts"],"names":[],"mappings":"AAwBA,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,UAAkC,EAAE;IAC9D,MAAM,IAAI,GAA2B,EAAE,GAAG,OAAO,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,OAAO;QACL,IAAI,CAAC,GAAG;YACN,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,OAAO;YACpB,KAAK,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC;gBACnC,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;;oBACnC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACvB,CAAC;YACD,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,QAAQ;YACN,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}