vultus-core 0.3.0 → 0.4.0

package/README.md

@@ -22,8 +22,10 @@ npm install vultus-core
   `parseApiError`, `routeApiError`, `ActionErrorContext` / `useActionErrorCtx`,
   `useAction`, `useActionList`, the fields (`useBoolField`, `useFieldCore` and
   their types), `InternalLinkContext` / `useInternalLink` /
-  `InternalLinkComponent`, and `MessageSinkContext` / `useMessageSink` /
-  `MessageSink`.
+  `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 +73,21 @@ 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.
 
+## 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/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/index.d.ts

@@ -12,4 +12,5 @@ export { useMixedBoolField, aggregateBool, type MixedBool, type MixedBoolFieldCo
 export { useOneOfField, type OneOfChoice, type OneOfChoiceControls, type OneOfFieldControls, type OneOfFieldOptions, } from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';
+export { VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey, type VultusComponents, type SpinnerProps, type SpinnerComponent, } from './Components.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAClE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,GACjH,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,GAC1G,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,GAC3G,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAClE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,GACjH,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,GAC1G,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,GAC3G,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,uBAAuB,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EACzE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,GAChE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -12,4 +12,5 @@ export { useMixedBoolField, aggregateBool, } from './useMixedBoolField.js';
 export { useOneOfField, } from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink } from './MessageSink.js';
+export { VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey, } from './Components.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,GAEnE,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAiD,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAA8B,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,GAEnE,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAiD,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAA8B,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,uBAAuB,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,GAE1E,MAAM,iBAAiB,CAAC"}

package/package.json

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

package/src/Components.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext, useMemo, 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 const VultusComponentsContext = createContext<VultusComponents>({});
+
+export function useVultusComponents(): VultusComponents {
+  return useContext(VultusComponentsContext);
+}
+
+/** The scope path (segment names, outermost first) that `useSpinnerKey` prefixes onto local keys. */
+const SpinnerScopeContext = createContext<string[]>([]);
+
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export function SpinnerScope({ name, children }: { name: string; children?: ReactNode }) {
+  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 <SpinnerScopeContext.Provider value={scope}>{children}</SpinnerScopeContext.Provider>;
+}
+
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export function useSpinnerKey(localKey: string): string {
+  const scope = useContext(SpinnerScopeContext);
+  return [...scope, localKey].join('/');
+}

package/src/index.ts

@@ -19,3 +19,7 @@ export {
 } from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';
+export {
+  VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey,
+  type VultusComponents, type SpinnerProps, type SpinnerComponent,
+} from './Components.js';