@salsita-ai/sdk 0.50.0-develop.7a3bca8318 → 0.50.0-develop.7c472a27fe

package/dist/react-sdk/domain-context/system-hooks/tab-navigation-hooks.d.ts

@@ -0,0 +1,61 @@
+import { type ReactNode } from 'react';
+import { type DomainEntityId } from '#package/domain';
+/**
+ * The spec component a layout's tabs come from: the `sidebarTabs` of an entity, or the configurator's
+ * `horizontalTabs`.
+ */
+export type TabSource = 'sidebarTabs' | 'horizontalTabs';
+/**
+ * One tab of the spec, ready to render.
+ */
+export interface TabEntry<NAVIGATION_STATE extends string = string> {
+    /** Position of the tab in `tabs`; what `select` takes */
+    readonly index: number;
+    /** The tab's label, resolved for the active locale */
+    readonly label: string;
+    /** A PhxIcon name, when the spec gives the icon as a string */
+    readonly icon: string | undefined;
+    /** A React node, when TypeScript spec code gives the icon as one (`sidebarTabs` only) */
+    readonly iconNode: ReactNode | undefined;
+    /** The tab's navigation states; the tab is active while one of them is */
+    readonly navigationStates: readonly NAVIGATION_STATE[];
+    /** `navigationStates[0]`, the state `select` enters */
+    readonly state: NAVIGATION_STATE;
+    readonly isActive: boolean;
+}
+/**
+ * Which tabs `useTabNavigation` reads.
+ * - `source`: `'auto'` (default) reads the entity's `sidebarTabs` and, without any, the `horizontalTabs`.
+ * - `entityId`: whose `sidebarTabs` are read; the selected entity by default (the root while nothing is selected).
+ */
+export interface UseTabNavigationOptions {
+    readonly source?: 'auto' | TabSource;
+    readonly entityId?: DomainEntityId<string>;
+}
+/**
+ * The tabs of the spec and the means to switch between them.
+ * - `source`: the component the tabs come from, or `null` when no active instance of it exists.
+ * - `tabs`: the tabs in spec order. `activeTab`: the first tab whose navigation states include the active one.
+ * - `select`: enters a tab, given by its index or by any of its navigation states; an unknown tab does nothing.
+ */
+export interface UseTabNavigationResult<NAVIGATION_STATE extends string = string> {
+    readonly source: TabSource | null;
+    readonly tabs: readonly TabEntry<NAVIGATION_STATE>[];
+    readonly activeTab: TabEntry<NAVIGATION_STATE> | null;
+    readonly select: (tab: number | NAVIGATION_STATE) => void;
+}
+export type UseTabNavigation<NAVIGATION_STATE extends string> = (options?: UseTabNavigationOptions) => UseTabNavigationResult<NAVIGATION_STATE>;
+/**
+ * Hook to read the tabs the spec declares, `sidebarTabs` or `horizontalTabs`, and to switch between them, as the
+ * built-in tabs do.
+ * - `sidebarTabs`: every active instance on the entity, flattened in spec order. `horizontalTabs`: the first active
+ *   instance, on any entity.
+ * - With `source: 'auto'` and both kinds active, `sidebarTabs` win; several active `horizontalTabs` use the first.
+ *   Both log a warning in development and never throw.
+ * - A tab without navigation states cannot be entered and is left out, with a warning in development.
+ * - `select` enters the tab's first navigation state. For `horizontalTabs` it pushes the analytics event the
+ *   built-in horizontal tabs push; for `sidebarTabs` none, as the built-in sidebar tabs.
+ *
+ * It does not check read mode: switching tabs is navigation, not editing.
+ */
+export declare const useTabNavigation: (options?: UseTabNavigationOptions) => UseTabNavigationResult;

package/dist/react-sdk/domain-context/system-hooks/tab-navigation-hooks.js

@@ -0,0 +1 @@
+import{useCallback as t,useEffect as a,useMemo as o}from"react";import{horizontalTabsComponent as e,sidebarTabsComponent as i}from"#package/domain";import{FrontendAnalyticsFactory as n,useAnalyticsService as s,useIsDev as r}from"../../application-runtime/index.js";import{useResolveLocalizable as l}from"../../localizable/index.js";import{useDomain as m}from"../common-hooks/index.js";import{useComponents as p}from"../component-hooks/index.js";import{useActiveNavigationState as c}from"./navigation-hooks.js";import{useSelectedDomainEntityId as b}from"./selection-hooks.js";let h=(t,o)=>{let e=r();a(()=>{e&&t&&console.warn(o)},[e,t,o])};export const useTabNavigation=(a={})=>{let{source:r="auto",entityId:v}=a,g=c(),d=b(),f=l(),T=s(),{navigationSystem:u,storeSystem:z}=m(),S=p({componentTypes:[i],entityIds:[v??d]}),j=p({componentTypes:[e]}),N="horizontalTabs"!==r&&S.length>0,k="sidebarTabs"!==r&&j.length>0,x=N?"sidebarTabs":k?"horizontalTabs":null;h(N&&k,"Both sidebarTabs and horizontalTabs are active, so useTabNavigation shows the sidebarTabs. Remove one of them from the spec, or pass `source` to choose."),h("horizontalTabs"===x&&j.length>1,"Several horizontalTabs are active, so useTabNavigation shows the first one. Keep one active, for example with $filter.");let y=o(()=>"sidebarTabs"===x?S.flatMap(t=>t.state.tabs):"horizontalTabs"===x?j[0]?.state.tabs??[]:[],[x,S,j]),w=y.filter(t=>0===t.navigationStates.length);h(w.length>0,`The ${x} tabs ${w.map(t=>`"${f(t.label)}"`).join(", ")} have no navigation states, so useTabNavigation leaves them out. Give each tab at least one navigation state.`);let $=o(()=>y.flatMap(t=>{let a=t.navigationStates[0];return void 0===a?[]:[{tab:t,state:a}]}).map(({tab:t,state:a},o)=>({index:o,label:f(t.label),icon:"string"==typeof t.icon?t.icon:void 0,iconNode:"string"==typeof t.icon||null===t.icon?void 0:t.icon,navigationStates:t.navigationStates,state:a,isActive:t.navigationStates.includes(g)})),[y,g,f]),A=$.find(t=>t.isActive)??null,C=t(t=>{let a="number"==typeof t?$[t]:$.find(a=>a.navigationStates.includes(t));a&&("horizontalTabs"===x&&T.push(n.TopNavigationStepClicked(a.state)),z.stageAndCommit([u.getNavigationUpdate(a.state)]))},[$,x,T,z,u]);return{source:x,tabs:$,activeTab:A,select:C}};

package/dist/react-sdk/domain-context/system-hooks/undo-redo-hooks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a project layout needs to offer undo and redo.
+ * - `canUndo` and `canRedo`: whether the undo history has a step to go back or forward to; they follow every change.
+ * - `undo`: returns to the previous step and pushes the undo-button analytics event; does nothing while `canUndo`
+ *   is false.
+ * - `redo`: returns to the next step and pushes the redo-button analytics event; does nothing while `canRedo` is
+ *   false.
+ */
+export interface UseUndoRedoResult {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly undo: () => void;
+    readonly redo: () => void;
+}
+export type UseUndoRedo = () => UseUndoRedoResult;
+/**
+ * Hook to undo and redo changes of the configuration, as the built-in toolbar's undo and redo buttons do. It does
+ * not check read mode; a layout hides undo and redo for a viewer.
+ */
+export declare const useUndoRedo: UseUndoRedo;

package/dist/react-sdk/domain-context/system-hooks/undo-redo-hooks.js

@@ -0,0 +1 @@
+import{useCallback as o,useMemo as n}from"react";import{FrontendAnalyticsFactory as e,useAnalyticsService as t}from"../../application-runtime/index.js";import{useDomain as d,useEagerObservableValue as r}from"../common-hooks/index.js";export const useUndoRedo=()=>{let i=t(),{undoSystem:c}=d(),{canUndo:m,canRedo:p}=r(c.can$),u=o(()=>{c.canUndo()&&(i.push(e.UndoButtonClicked()),c.undo())},[i,c]),s=o(()=>{c.canRedo()&&(i.push(e.RedoButtonClicked()),c.redo())},[i,c]);return n(()=>({canUndo:m,canRedo:p,undo:u,redo:s}),[m,p,u,s])};

package/dist/react-sdk/domain-controls/hooks/use-angle-dimension.d.ts

@@ -2,7 +2,7 @@ import { type AnalyticsEvent, type AngleDimensionComponent, AngleUnit, type Comp
 export declare const AngleDimensionSliderUpdateTag = "setAngleDimension";
 export type IsAngleDimensionUpdate<ENTITIES extends DomainEntity<string>> = (update: StateUpdate<ENTITIES, ENTITIES>, types: ReadonlyArray<ENTITIES['type']>, instanceName: string) => update is ComponentModification<AngleDimensionComponent>;
 export declare const isAngleDimensionUpdate: (update: StateUpdate<DomainEntity<string>, DomainEntity<string>>, types: readonly string[], instanceName: string) => update is ComponentModification<AngleDimensionComponent>;
-export declare const useAngleDimension: (entityId: DomainEntityId<string>, instanceName: string, fixableViolations?: string[], createAnalyticsEvent?: (instanceName: string, entityId: DomainEntityId<string>, value: number) => AnalyticsEvent, stageOnUpdate?: boolean) => {
+export declare const useAngleDimension: (entityId: DomainEntityId<string>, instanceName: string, fixableViolations?: readonly string[], createAnalyticsEvent?: (instanceName: string, entityId: DomainEntityId<string>, value: number) => AnalyticsEvent, stageOnUpdate?: boolean) => {
     value: number;
     min: number | undefined;
     max: number | undefined;

package/dist/react-sdk/elements/configurator-error-page-props.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Why the configurator shows its error page:
+ * - `uncaughtError`: rendering the configurator failed with an error nothing else handled;
+ * - `presetCreationFailed`: starting a configuration from a preset failed on a start screen that has
+ *   no preset grid to return to (a single preset).
+ */
+export type ConfiguratorErrorReason = 'uncaughtError' | 'presetCreationFailed';
+/**
+ * The props of the `ConfiguratorErrorPage` element, the page the configurator shows in production
+ * when it cannot go on; a project registers its page with `createConfiguratorErrorPage`. In
+ * development the configurator shows its detailed error pages instead.
+ */
+export interface ConfiguratorErrorPageProps {
+    readonly reason: ConfiguratorErrorReason;
+    /**
+     * Tries again: after an `uncaughtError` it renders the configurator again, after
+     * `presetCreationFailed` it reloads the page.
+     */
+    readonly onRetry: () => void;
+}

package/dist/react-sdk/elements/configurator-error-page-props.js

@@ -0,0 +1 @@
+export{};

package/dist/react-sdk/elements/index.d.ts

@@ -1,2 +1,3 @@
+export type { ConfiguratorErrorPageProps, ConfiguratorErrorReason } from './configurator-error-page-props.js';
 export { PhoenixEntityElement, PhoenixEntityElements, PhoenixEntityElementWithChildren, type PhoenixEntityElementProps, type PhoenixEntityElementsProps, type PhoenixEntityElementWithChildrenProps, } from './PhoenixEntityElement.js';
 export { PhoenixLayoutElement, PhoenixLayoutElements, PhoenixLayoutElementWithChildren, usePhoenixLayoutElementExists, type PhoenixLayoutElementProps, type PhoenixLayoutElementsProps, type PhoenixLayoutElementWithChildrenProps, } from './PhoenixLayoutElement.js';

package/dist/react-sdk/handlers/FinalizeActionRunner.d.ts

@@ -0,0 +1,13 @@
+import type { FinalizeActionsStore } from './finalize-actions-store.js';
+interface FinalizeActionRunnerProps {
+    /** The component key of the `finalizeAction` the runner runs */
+    readonly actionKey: string;
+    readonly handler: string;
+    readonly store: FinalizeActionsStore;
+}
+/**
+ * The hidden runner of one `finalizeAction`. `PhoenixHandlerBoundary` remounts it, its error boundary included,
+ * when the handler's source changes, so an edited or fixed handler takes effect without a reload.
+ */
+export declare const FinalizeActionRunner: (props: FinalizeActionRunnerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/react-sdk/handlers/FinalizeActionRunner.js

@@ -0,0 +1 @@
+import{jsx as r}from"react/jsx-runtime";import{useLayoutEffect as e}from"react";import{ErrorBoundary as n}from"react-error-boundary";import{useLogger as i}from"../application-runtime/index.js";import{PhoenixHandlerBoundary as o}from"./PhoenixHandlerBoundary.js";import{useFinalizeAction as a}from"./use-finalize-action.js";let t=({actionKey:r,handler:n,store:i})=>{let o=a(n);return e(()=>{i.publish(r,{status:"ready",action:o})}),e(()=>()=>i.remove(r),[r,i]),null},l=({actionKey:r,handler:n,store:o,error:a})=>{let t=i();return e(()=>{let e=a instanceof Error?a:Error(String(a??"The finalize handler failed."),{cause:a});return t.error(`The finalize handler "${n}" failed to load, so its finalize action cannot run.`,{error:e.message}),o.publish(r,{status:"failed",error:e}),()=>o.remove(r)},[r,a,n,t,o]),null};export const FinalizeActionRunner=e=>r(o,{name:e.handler,children:r(n,{fallbackRender:({error:n})=>r(l,{...e,error:n}),children:r(t,{...e})})});

package/dist/react-sdk/handlers/FinalizeActionsHost.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runs the spec's finalize actions for `useFinalizeActions()`. For every active `finalizeAction` component it
+ * mounts a hidden runner, which calls `useFinalizeAction` with the component's handler and publishes its state into
+ * the enclosing `FinalizeActionsProvider`. It renders nothing.
+ *
+ * The configurator mounts it once beside the configurator layout, inside its `ModalProvider`, so a handler can use
+ * `useModal`; a project does not mount it. The handlers' hooks run here, outside the layout, so a handler uses only
+ * what the configurator provides above its layout.
+ */
+export declare const FinalizeActionsHost: () => import("react/jsx-runtime").JSX.Element | null;

package/dist/react-sdk/handlers/FinalizeActionsHost.js

@@ -0,0 +1 @@
+import{jsx as n,Fragment as i}from"react/jsx-runtime";import{useContext as t,useEffect as o}from"react";import{finalizeActionComponent as e,getComponentSnapshotKey as r}from"#package/domain";import{useLogger as a}from"../application-runtime/index.js";import{useComponents as s}from"../domain-context/index.js";import{FinalizeActionRunner as m}from"./FinalizeActionRunner.js";import{FinalizeActionsContext as l}from"./finalize-actions-context.js";export const FinalizeActionsHost=()=>{let c=t(l),p=s({componentTypes:[e]}),u=a(),d=null!==c;return(o(()=>{d||u.warn("FinalizeActionsHost is mounted outside a FinalizeActionsProvider, so it runs no finalize actions.")},[d,u]),null===c)?null:n(i,{children:p.map(i=>{let t=r(i);return n(m,{actionKey:t,handler:i.state.handler,store:c},t)})})};

package/dist/react-sdk/handlers/FinalizeActionsProvider.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+/**
+ * Holds the state of the spec's finalize actions for `useFinalizeActions()` in its children; the runners of
+ * `FinalizeActionsHost`, mounted somewhere inside it, publish into it.
+ *
+ * The configurator mounts it once above its `ModalProvider`, so a dialog a layout opens with `useModal` sees the
+ * actions too; a project does not mount it.
+ */
+export declare const FinalizeActionsProvider: ({ children }: {
+    readonly children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/react-sdk/handlers/FinalizeActionsProvider.js

@@ -0,0 +1 @@
+import{jsx as r}from"react/jsx-runtime";import{useState as i}from"react";import{FinalizeActionsContext as o}from"./finalize-actions-context.js";import{createFinalizeActionsStore as t}from"./finalize-actions-store.js";export const FinalizeActionsProvider=({children:e})=>{let[n]=i(t);return r(o.Provider,{value:n,children:e})};

package/dist/react-sdk/handlers/finalize-actions-context.d.ts

@@ -0,0 +1,6 @@
+import type { FinalizeActionsStore } from './finalize-actions-store.js';
+/**
+ * The store of the enclosing `FinalizeActionsProvider`, or `null` outside one. The built-in finalize buttons read
+ * the outcome of a run from it, which outlives the button; a layout uses `useFinalizeActions()` instead.
+ */
+export declare const FinalizeActionsContext: import("react").Context<FinalizeActionsStore | null>;

package/dist/react-sdk/handlers/finalize-actions-context.js

@@ -0,0 +1 @@
+import{createContext as t}from"react";export const FinalizeActionsContext=t(null);

package/dist/react-sdk/handlers/finalize-actions-store.d.ts

@@ -0,0 +1,23 @@
+import type { UseFinalizeActionResult } from './use-finalize-action.js';
+/**
+ * What the hidden runner of one `finalizeAction` publishes: the state of its `useFinalizeAction` call, or the error
+ * its handler threw while it was resolved, in which case the action cannot run.
+ */
+export type FinalizeActionRunnerState = {
+    readonly status: 'ready';
+    readonly action: UseFinalizeActionResult;
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/**
+ * The runner states of the active `finalizeAction` components, by component key. `FinalizeActionsProvider` owns
+ * one; the runners of `FinalizeActionsHost` publish into it and `useFinalizeActions()` reads it.
+ */
+export interface FinalizeActionsStore {
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly getSnapshot: () => ReadonlyMap<string, FinalizeActionRunnerState>;
+    readonly publish: (key: string, state: FinalizeActionRunnerState) => void;
+    readonly remove: (key: string) => void;
+}
+export declare const createFinalizeActionsStore: () => FinalizeActionsStore;

package/dist/react-sdk/handlers/finalize-actions-store.js

@@ -0,0 +1 @@
+export const createFinalizeActionsStore=()=>{let t=new Map,e=new Set,a=a=>{t=a,e.forEach(t=>t())};return{subscribe:t=>(e.add(t),()=>{e.delete(t)}),getSnapshot:()=>t,publish:(e,i)=>{var n;n=t.get(e),(void 0===n||n.status!==i.status||("failed"===n.status||"failed"===i.status?"failed"!==n.status||"failed"!==i.status||n.error!==i.error:n.action.run!==i.action.run||n.action.isPending!==i.action.isPending||n.action.error!==i.action.error||n.action.disabled!==i.action.disabled||n.action.hints!==i.action.hints))&&a(new Map(t).set(e,i))},remove:e=>{if(!t.has(e))return;let i=new Map(t);i.delete(e),a(i)}}};

package/dist/react-sdk/handlers/index.d.ts

@@ -1,2 +1,8 @@
 export { usePhoenixHandler, useSystemPhoenixHandler, useSystemPhoenixAsyncHandler } from './PhoenixHandler.js';
 export { PhoenixHandlerBoundary } from './PhoenixHandlerBoundary.js';
+export { type UseFinalizeAction, type UseFinalizeActionResult, useFinalizeAction } from './use-finalize-action.js';
+export { FinalizeActionsHost } from './FinalizeActionsHost.js';
+export { FinalizeActionsProvider } from './FinalizeActionsProvider.js';
+export { FinalizeActionsContext } from './finalize-actions-context.js';
+export { type FinalizeActionRunnerState, type FinalizeActionsStore } from './finalize-actions-store.js';
+export { type FinalizeActionEntry, type UseFinalizeActions, type UseFinalizeActionsResult, useFinalizeActions, } from './use-finalize-actions.js';

package/dist/react-sdk/handlers/index.js

@@ -1 +1 @@
-export{usePhoenixHandler,useSystemPhoenixHandler,useSystemPhoenixAsyncHandler}from"./PhoenixHandler.js";export{PhoenixHandlerBoundary}from"./PhoenixHandlerBoundary.js";
+export{usePhoenixHandler,useSystemPhoenixHandler,useSystemPhoenixAsyncHandler}from"./PhoenixHandler.js";export{PhoenixHandlerBoundary}from"./PhoenixHandlerBoundary.js";export{useFinalizeAction}from"./use-finalize-action.js";export{FinalizeActionsHost}from"./FinalizeActionsHost.js";export{FinalizeActionsProvider}from"./FinalizeActionsProvider.js";export{FinalizeActionsContext}from"./finalize-actions-context.js";export{useFinalizeActions}from"./use-finalize-actions.js";

package/dist/react-sdk/handlers/use-finalize-action.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a project layout needs to show and run one `finalizeAction` of the spec.
+ * - `run`: pushes the finalize-button analytics event, then runs the action's handler. Does nothing while
+ *   `disabled` or `isPending`. The promise it returns never rejects: it resolves after the handler has settled and
+ *   React has had the chance to render the outcome, or at once when the run does nothing; a failure is `error`.
+ * - `isPending`: the handler is running.
+ * - `error`: what the handler's last run rejected with, `null` after a run that resolved and while a new run is
+ *   pending. A rejection that is not an `Error` is wrapped in one, with the rejected value as its `cause`. No snackbar
+ *   is raised; the layout shows it its own way.
+ * - `disabled` and `hints`: from `useFinalizeViolations()`; the configuration cannot be finalized while it has
+ *   a `warning` or worse, or while it is out of sync with the server, and `hints` says why.
+ *
+ * `isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps
+ * running, and a component mounted afterwards starts with `isPending` false and no `error`.
+ */
+export interface UseFinalizeActionResult {
+    readonly run: () => Promise<void>;
+    readonly isPending: boolean;
+    readonly error: Error | null;
+    readonly disabled: boolean;
+    readonly hints: string | undefined;
+}
+export type UseFinalizeAction = (handler: string) => UseFinalizeActionResult;
+/**
+ * Runs the project handler a `finalizeAction` component names, with the state a finalize button shows.
+ *
+ * It calls `usePhoenixHandler(handler)`, which calls the project's handler factory and the hooks inside it, so:
+ * call it once per component, never in a loop or conditionally, render one component per action, and wrap that
+ * component in `<PhoenixHandlerBoundary name={handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes
+ * effect without a reload. It does not check read mode; a layout hides finalization for a viewer.
+ */
+export declare const useFinalizeAction: UseFinalizeAction;

package/dist/react-sdk/handlers/use-finalize-action.js

@@ -0,0 +1 @@
+import{useMutation as r}from"@tanstack/react-query";import{useCallback as t,useRef as e}from"react";import{FrontendAnalyticsFactory as n,useAnalyticsService as i,useLogger as a}from"../application-runtime/index.js";import{useFinalizeViolations as o}from"../domain-context/index.js";import{usePhoenixHandler as c}from"./PhoenixHandler.js";export const useFinalizeAction=s=>{let{handler:l}=c(s),m=i(),u=a(),{disabled:f,hints:d}=o(),h=e(!1),{mutateAsync:p,isPending:w,error:y}=r({mutationFn:async()=>{try{await l()}catch(r){throw r instanceof Error?r:Error(null==r?"The finalize handler failed without a reason.":String(r),{cause:r})}finally{h.current=!1}},onError:r=>{u.error("Failed to finalize",{error:r.message})}});return{run:t(async()=>{if(!f&&!h.current){h.current=!0,m.push(n.FinalizeButtonClicked());try{await p()}catch{}await new Promise(r=>setTimeout(r,0))}},[m,f,p]),isPending:w,error:y,disabled:f,hints:d}};

package/dist/react-sdk/handlers/use-finalize-actions.d.ts

@@ -0,0 +1,53 @@
+import { type FinalizeActionComponentState } from '#package/domain';
+/**
+ * One active `finalizeAction` of the spec, ready to render and run.
+ * - `key`: the stable key of the component instance, for React's `key`.
+ * - `handler`: the name of the project handler the action runs.
+ * - `variant`, `label`, `title` and `icon`: the component's fields, `label` and `title` resolved to the current
+ *   language; `icon` is a `PhxIcon` name.
+ * - `run`: pushes the finalize-button analytics event and runs the handler, as `useFinalizeAction(handler).run`
+ *   does. It does nothing while `disabled` or `isPending`. The promise it returns never rejects: it resolves once
+ *   the entry shows the outcome of the run, or at once when the run does nothing.
+ * - `isPending`: the handler is running.
+ * - `error`: what the handler's last run rejected with, as an `Error`, or `null`; cleared when the action runs
+ *   again. It is also the error the handler threw while it was loaded, when it could not be loaded at all.
+ * - `disabled`: finalizing is blocked, as in `useFinalizeViolations()`, or the handler could not be loaded.
+ */
+export interface FinalizeActionEntry {
+    readonly key: string;
+    readonly handler: string;
+    readonly variant: FinalizeActionComponentState['variant'];
+    readonly label: string;
+    readonly title: string;
+    readonly icon: string;
+    readonly run: () => Promise<void>;
+    readonly isPending: boolean;
+    readonly error: Error | null;
+    readonly disabled: boolean;
+}
+/**
+ * The spec's finalize actions for a layout.
+ * - `actions`: every active `finalizeAction` component, in spec order.
+ * - `primary`: the first `'primary'` action, else the first action, else `null`; the built-in footer's button.
+ * - `secondary`: the other actions, in spec order; the built-in footer's menu.
+ * - `disabled` and `hints`: those of `useFinalizeViolations()`.
+ */
+export interface UseFinalizeActionsResult {
+    readonly actions: readonly FinalizeActionEntry[];
+    readonly primary: FinalizeActionEntry | null;
+    readonly secondary: readonly FinalizeActionEntry[];
+    readonly disabled: boolean;
+    readonly hints: string | undefined;
+}
+export type UseFinalizeActions = () => UseFinalizeActionsResult;
+/**
+ * The spec's finalize actions, each with its own `run`, for a layout that renders its own finalize buttons. The
+ * configurator runs the handlers itself, so a layout calls this hook anywhere, as often as it likes, and renders
+ * the entries in a loop. To run a single action the layout already knows, `useFinalizeAction(handler)` works too.
+ *
+ * It needs the configurator's `FinalizeActionsProvider` and `FinalizeActionsHost`, which are mounted around and
+ * beside every configurator layout, and also reach the dialogs a layout opens with `useModal`. Outside them it
+ * returns no actions and logs a warning. It does not check read mode; a layout hides finalization for a
+ * viewer.
+ */
+export declare const useFinalizeActions: UseFinalizeActions;

package/dist/react-sdk/handlers/use-finalize-actions.js

@@ -0,0 +1 @@
+import{useContext as e,useEffect as i,useMemo as t,useSyncExternalStore as r}from"react";import{finalizeActionComponent as n,getComponentSnapshotKey as o}from"#package/domain";import{useLogger as a}from"../application-runtime/index.js";import{useComponents as s,useFinalizeViolations as l}from"../domain-context/index.js";import{useResolveLocalizable as u}from"../localizable/index.js";import{FinalizeActionsContext as d}from"./finalize-actions-context.js";let m=()=>Promise.resolve(),p=new Map,c=()=>()=>{},f=()=>p;export const useFinalizeActions=()=>{let p=e(d),g=r(p?.subscribe??c,p?.getSnapshot??f),b=s({componentTypes:[n]}),{disabled:y,hints:x}=l(),z=u(),j=a(),h=null!==p;return i(()=>{h||j.warn("useFinalizeActions() is used outside the configurator layout and its dialogs, so it returns no finalize actions. Call it inside a ConfiguratorLayout element or a dialog it opens.")},[h,j]),t(()=>{if(!h)return{actions:[],primary:null,secondary:[],disabled:y,hints:x};let e=b.map(e=>{let i=o(e),{variant:t,label:r,title:n,icon:a,handler:s}=e.state,l=g.get(i),u={key:i,handler:s,variant:t,label:z(r),title:z(n),icon:a};if(l?.status==="ready"){let{run:e,isPending:i,error:t,disabled:r}=l.action;return{...u,run:e,isPending:i,error:t,disabled:r}}return{...u,run:m,isPending:!1,error:l?.status==="failed"?l.error:null,disabled:!0}}),i=e.find(e=>"primary"===e.variant)??e[0]??null,t=e.filter(e=>e!==i);return{actions:e,primary:i,secondary:t,disabled:y,hints:x}},[b,y,h,x,z,g])};

package/dist/react-sdk/index.d.ts

@@ -9,5 +9,6 @@ export * from './web-component/index.js';
 export * from './localizable/index.js';
 export * from './loading-state/index.js';
 export * from './elements/index.js';
+export * from './scene-control-elements/index.js';
 export * from './handlers/index.js';
 export * from './application-runtime/index.js';

package/dist/react-sdk/index.js

@@ -1 +1 @@
-export*from"./theme/index.js";export*from"./utils/index.js";export*from"./session/index.js";export*from"./domain-context/index.js";export*from"./domain-application-context/index.js";export*from"./domain-controls/index.js";export*from"./invalid-deployment/index.js";export*from"./web-component/index.js";export*from"./localizable/index.js";export*from"./loading-state/index.js";export*from"./elements/index.js";export*from"./handlers/index.js";export*from"./application-runtime/index.js";
+export*from"./theme/index.js";export*from"./utils/index.js";export*from"./session/index.js";export*from"./domain-context/index.js";export*from"./domain-application-context/index.js";export*from"./domain-controls/index.js";export*from"./invalid-deployment/index.js";export*from"./web-component/index.js";export*from"./localizable/index.js";export*from"./loading-state/index.js";export*from"./elements/index.js";export*from"./scene-control-elements/index.js";export*from"./handlers/index.js";export*from"./application-runtime/index.js";

package/dist/react-sdk/loading-state/LoaderHost.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+/**
+ * Hosts the application's loader: the loading hooks below it report to the runtime's `loading`
+ * slice, and the SDK's own UI below it leaves its inline loaders out (`useIsLoaderHosted()`). The
+ * configurator mounts the one host, inside its `ApplicationTypeProvider`, while it is powered on.
+ *
+ * It resets the slice when it mounts and not again while it stays mounted, so the loading state
+ * starts over at power-on and on remount, and only there.
+ *
+ * Its children mount once the reset is done, so their first render and their first phases already
+ * see the host, and the reset cannot wipe phases they started. The host resets in a layout effect
+ * and then sets local state, which React renders synchronously before the browser paints, whatever
+ * the lane of the first render. StrictMode repeats that layout effect before the children mount, so
+ * the second reset wipes nothing either.
+ *
+ * @internal Runtime plumbing for the SDK's own UI.
+ */
+export declare const LoaderHost: ({ children }: {
+    readonly children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element | null;

package/dist/react-sdk/loading-state/LoaderHost.js

@@ -0,0 +1 @@
+import{jsx as o}from"react/jsx-runtime";import{useLayoutEffect as r,useState as i}from"react";import{LoaderHostContext as t,useLoadingApplication as e}from"../application-runtime/index.js";export const LoaderHost=({children:n})=>{let a=e(),[p,d]=i(!1);if(null===a)throw Error("LoaderHost has no application whose loader it could host: it is mounted outside an ApplicationRuntimeProvider or an ApplicationTypeProvider. Render LoaderHost inside both an ApplicationRuntimeProvider and an ApplicationTypeProvider, as ConfiguratorApp does.");return(r(()=>{a.actions.resetSlot(),d(!0)},[a]),p)?o(t.Provider,{value:!0,children:n}):null};

package/dist/react-sdk/loading-state/built-in-loading-phase.d.ts

@@ -0,0 +1,9 @@
+/** The ids of the loading phases the SDK reports itself. A project reports its own under other ids. */
+export declare enum BuiltInLoadingPhase {
+    SessionAuth = "session-auth",
+    PublishedData = "published-data",
+    FrontendData = "frontend-data",
+    BackendData = "backend-data",
+    DataFetch = "data-fetch",
+    SceneAssets = "scene-assets"
+}

package/dist/react-sdk/loading-state/built-in-loading-phase.js

@@ -0,0 +1 @@
+var a;export var BuiltInLoadingPhase=((a={}).SessionAuth="session-auth",a.PublishedData="published-data",a.FrontendData="frontend-data",a.BackendData="backend-data",a.DataFetch="data-fetch",a.SceneAssets="scene-assets",a);

package/dist/react-sdk/loading-state/index.d.ts

@@ -1,2 +1,3 @@
-export { BuiltInLoadingPhase, type LoadingPhase, type LoadingState, LoadingStateManager, } from './loading-state-manager.js';
-export { LoadingStateProvider, useLoadingState, type UseLoadingState, useLoadingStateManager, useLoadingStateValue, useLoadingPhase, useExpectPhase, useLoadingError, } from './LoadingStateProvider.js';
+export { BuiltInLoadingPhase } from './built-in-loading-phase.js';
+export { LoaderHost } from './LoaderHost.js';
+export { useLoadingState, type UseLoadingState, useLoadingStateValue, useLoadingPhase, useExpectPhase, useLoadingError, } from './loading-state-hooks.js';

package/dist/react-sdk/loading-state/index.js

@@ -1 +1 @@
-export{BuiltInLoadingPhase,LoadingStateManager}from"./loading-state-manager.js";export{LoadingStateProvider,useLoadingState,useLoadingStateManager,useLoadingStateValue,useLoadingPhase,useExpectPhase,useLoadingError}from"./LoadingStateProvider.js";
+export{BuiltInLoadingPhase}from"./built-in-loading-phase.js";export{LoaderHost}from"./LoaderHost.js";export{useLoadingState,useLoadingStateValue,useLoadingPhase,useExpectPhase,useLoadingError}from"./loading-state-hooks.js";

package/dist/react-sdk/loading-state/{LoadingStateProvider.d.ts → loading-state-hooks.d.ts}

@@ -1,22 +1,13 @@
-import type { ReactNode } from 'react';
-import { type LoadingPhase, type LoadingState, LoadingStateManager } from './loading-state-manager.js';
-export declare const LoadingStateProvider: ({ children }: {
-    readonly children: ReactNode;
-}) => import("react/jsx-runtime").JSX.Element;
-/**
- * Returns the loading state manager if available.
- * Returns `null` when used outside of `LoadingStateProvider` (e.g. in admin app).
- */
-export declare const useLoadingStateManager: () => LoadingStateManager | null;
+import { type LoadingPhase, type LoadingState } from '../application-runtime/index.js';
 /**
  * Subscribe to the current aggregated loading state.
- * Returns the default (not loading) state when used outside of `LoadingStateProvider`.
+ * Returns the default (not loading) state outside the application's loader host.
  */
 export declare const useLoadingStateValue: () => LoadingState;
 export type UseLoadingState = typeof useLoadingState;
 /**
  * Returns loading phase control functions.
- * Returns `null` when used outside of `LoadingStateProvider`.
+ * Returns `null` outside the application's loader host.
  */
 export declare const useLoadingState: () => {
     startPhase: (phase: LoadingPhase) => void;

package/dist/react-sdk/loading-state/loading-state-hooks.js

@@ -0,0 +1 @@
+import{useEffect as e,useMemo as t,useRef as r,useSyncExternalStore as n}from"react";import{useIsLoaderHosted as s,useLoadingActions as a,useLoadingApplication as o,useOptionalApplicationRuntime as u}from"../application-runtime/index.js";let c={isLoading:!1,hasError:!1,phases:[],expectedPhaseIds:new Set},l=()=>c,i=()=>()=>{};export const useLoadingStateValue=()=>{let e=o(),t=s(),r=u(),a=n(r?.subscribe??i,e?.selectors.getLoadingState??l);return t?a:c};export const useLoadingState=()=>{let e=a();return t(()=>e?{startPhase:e.startPhase,endPhase:e.endPhase}:null,[e])};export const useLoadingPhase=(t,n)=>{let s=a(),o=r(t);o.current=t;let u=r(null);e(()=>{if(s)return n?(u.current=o.current.id,s.startPhase(o.current)):null!==u.current&&(s.endPhase(u.current),u.current=null),()=>{null!==u.current&&(s.endPhase(u.current),u.current=null)}},[s,n,t.id])};export const useExpectPhase=t=>{let r=a();e(()=>{if(r)return r.expectPhase(t),()=>{r.dropExpectation(t)}},[r,t])};export const useLoadingError=t=>{let r=a();e(()=>{r&&t&&r.reportError()},[r,t])};

package/dist/react-sdk/scene-control-elements/AddEntityFabElement.d.ts

@@ -0,0 +1,36 @@
+import type { Localizable } from '@salsita-ai/common/utils';
+import type { DomainEntityId } from '#package/domain';
+import type { SceneControlTooltipVisibility } from './scene-control-tooltip-visibility.js';
+/**
+ * The name of the entity element that renders a `sceneEntityAddFab`. Its default, the built-in
+ * add-entity FAB, is registered in `defaultConfiguratorElements`.
+ */
+export declare const AddEntityFabName = "AddEntityFab";
+/**
+ * Props of the `AddEntityFab` element, rendered for each `sceneEntityAddFab` of an entity, at the
+ * position the component sets. The recipes it can add are not computed up front: the built-in FAB
+ * reads them with `useGroupedRecipeOptions(entityId, instanceNames, fixableViolations)` when it
+ * opens its menu, and a replacement does the same.
+ */
+export interface AddEntityFabElementProps {
+    /** The entity the FAB adds children to. */
+    readonly entityId: DomainEntityId<string>;
+    /** The `childEntityRecipes` instances whose recipes the FAB offers; all of them when not set. */
+    readonly instanceNames?: readonly string[];
+    /** Violations a new entity may cause without disabling its recipe (the component's `hiddenViolations`). */
+    readonly fixableViolations?: readonly string[];
+    /** The name of a Phoenix icon. */
+    readonly icon?: string;
+    /** A visible text label. */
+    readonly label?: Localizable;
+    /** The tooltip text. */
+    readonly title?: Localizable;
+    /** When the tooltip shows: `on-hover` unless the component sets it. */
+    readonly tooltipVisibility: SceneControlTooltipVisibility;
+    /** Add the only recipe directly, without a menu. */
+    readonly skipMenuWhenOnlyOne?: boolean;
+    /** Render nothing when there is no recipe. */
+    readonly hideWhenNone?: boolean;
+}
+/** Renders the `AddEntityFab` element for an entity. */
+export declare const AddEntityFabElement: import("react").MemoExoticComponent<(props: AddEntityFabElementProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/react-sdk/scene-control-elements/AddEntityFabElement.js

@@ -0,0 +1 @@
+import{jsx as t}from"react/jsx-runtime";import{memo as e,useMemo as n}from"react";import{PhoenixEntityElementWithChildren as r}from"../elements/index.js";export const AddEntityFabName="AddEntityFab";export const AddEntityFabElement=e(e=>{let{entityId:d,instanceNames:i,fixableViolations:m,icon:o,label:a,title:s,tooltipVisibility:p,skipMenuWhenOnlyOne:x,hideWhenNone:y}=e,E=n(()=>({instanceNames:i,fixableViolations:m,icon:o,label:a,title:s,tooltipVisibility:p,skipMenuWhenOnlyOne:x,hideWhenNone:y}),[i,m,o,a,s,p,x,y]);return t(r,{kind:"AddEntityFab",entityId:d,elementProps:E})});

package/dist/react-sdk/scene-control-elements/DeleteEntityFabElement.d.ts

@@ -0,0 +1,44 @@
+import { type SyntheticEvent } from 'react';
+import type { Localizable } from '@salsita-ai/common/utils';
+import type { DomainEntityId } from '#package/domain';
+import type { SceneControlTooltipVisibility } from './scene-control-tooltip-visibility.js';
+/**
+ * The name of the entity element that renders a `sceneEntityDeleteFab`. Its default, the built-in
+ * delete-entity FAB, is registered in `defaultConfiguratorElements`.
+ */
+export declare const DeleteEntityFabName = "DeleteEntityFab";
+/**
+ * Props of the `DeleteEntityFab` element, rendered for each `sceneEntityDeleteFab` of an entity, at
+ * the position the component sets.
+ */
+export interface DeleteEntityFabElementProps {
+    /** The entity the FAB deletes. */
+    readonly entityId: DomainEntityId<string>;
+    /** The name of a Phoenix icon. */
+    readonly icon?: string;
+    /** A visible text label. */
+    readonly label?: Localizable;
+    /** The tooltip text. */
+    readonly title?: Localizable;
+    /** When the tooltip shows: `on-hover` unless the component sets it. */
+    readonly tooltipVisibility: SceneControlTooltipVisibility;
+    /**
+     * Deletes the entity and pushes the delete analytics event. Pass it straight to `onClick`: given
+     * an event, it stops the event's propagation so the click does not reach the scene.
+     */
+    readonly onDelete: (event?: SyntheticEvent) => void;
+    /** True when deleting would cause a violation the component does not allow. */
+    readonly disabled: boolean;
+    /** Why deleting is disabled, when it is. */
+    readonly disabledHint: string | undefined;
+    /** Logs the dry run of the deletion to the console, for debugging. */
+    readonly trace: () => void;
+}
+type DeleteEntityFabElementConfig = Omit<DeleteEntityFabElementProps, 'onDelete' | 'disabled' | 'disabledHint' | 'trace'>;
+interface Props extends DeleteEntityFabElementConfig {
+    /** Violations deleting may cause without disabling the FAB (the component's `hiddenViolations`). */
+    readonly fixableViolations?: readonly string[];
+}
+/** Renders the `DeleteEntityFab` element for an entity, with the deletion it performs. */
+export declare const DeleteEntityFabElement: import("react").MemoExoticComponent<(props: Props) => import("react/jsx-runtime").JSX.Element>;
+export {};

package/dist/react-sdk/scene-control-elements/DeleteEntityFabElement.js

@@ -0,0 +1 @@
+import{jsx as t}from"react/jsx-runtime";import{memo as e,useCallback as i,useMemo as o}from"react";import{FrontendAnalyticsFactory as n}from"../application-runtime/index.js";import{useDeletedEntity as r}from"../domain-controls/index.js";import{PhoenixEntityElementWithChildren as m}from"../elements/index.js";export const DeleteEntityFabName="DeleteEntityFab";export const DeleteEntityFabElement=e(e=>{let{entityId:a,fixableViolations:s,icon:l,label:p,title:d,tooltipVisibility:c}=e,x=i(()=>n.EntityDeleteHotspotClicked(a),[a]),{disabled:y,hints:E,remove:b,trace:f}=r(a,s,x),j=i(t=>{t?.stopPropagation(),b()},[b]),D=o(()=>({icon:l,label:p,title:d,tooltipVisibility:c,onDelete:j,disabled:y,disabledHint:E,trace:f}),[l,p,d,c,j,y,E,f]);return t(m,{kind:"DeleteEntityFab",entityId:a,elementProps:D})});

package/dist/react-sdk/scene-control-elements/NavigationHotspotElement.d.ts

@@ -0,0 +1,38 @@
+import { type SyntheticEvent } from 'react';
+import type { Localizable } from '@salsita-ai/common/utils';
+import type { DomainEntityId } from '#package/domain';
+import type { SceneControlTooltipVisibility } from './scene-control-tooltip-visibility.js';
+/**
+ * The name of the entity element that renders a `sceneEntityNavigationHotspot`. Its default, the
+ * built-in navigation hotspot, is registered in `defaultConfiguratorElements`.
+ */
+export declare const NavigationHotspotName = "NavigationHotspot";
+/**
+ * Props of the `NavigationHotspot` element, rendered for each `sceneEntityNavigationHotspot` of an
+ * entity, at the position the component sets.
+ */
+export interface NavigationHotspotElementProps {
+    /** The entity the hotspot is attached to. */
+    readonly entityId: DomainEntityId<string>;
+    /** The navigation state the hotspot goes to. */
+    readonly navigationState: string;
+    /** The tooltip text. */
+    readonly title?: Localizable;
+    /** When the tooltip shows: `on-hover` unless the component sets it. */
+    readonly tooltipVisibility: SceneControlTooltipVisibility;
+    /**
+     * Goes to `navigationState`, pushed onto the navigation stack or replacing the current state as
+     * the component sets. Pass it straight to `onClick`: given an event, it prevents the event's
+     * default and stops its propagation so the click does not reach the scene.
+     */
+    readonly onNavigate: (event?: SyntheticEvent) => void;
+}
+interface Props extends Omit<NavigationHotspotElementProps, 'onNavigate'> {
+    /** Push `navigationState` onto the navigation stack instead of replacing the current state. */
+    readonly pushToStack?: boolean;
+    /** The states `navigationState` can be stacked onto. */
+    readonly canStackOnto?: readonly string[];
+}
+/** Renders the `NavigationHotspot` element for an entity, with the navigation it performs. */
+export declare const NavigationHotspotElement: import("react").MemoExoticComponent<(props: Props) => import("react/jsx-runtime").JSX.Element>;
+export {};

package/dist/react-sdk/scene-control-elements/NavigationHotspotElement.js

@@ -0,0 +1 @@
+import{jsx as t}from"react/jsx-runtime";import{memo as e,useCallback as o,useMemo as a}from"react";import{useDomain as i}from"../domain-context/index.js";import{PhoenixEntityElementWithChildren as n}from"../elements/index.js";export const NavigationHotspotName="NavigationHotspot";export const NavigationHotspotElement=e(e=>{let{entityId:s,navigationState:m,pushToStack:r,canStackOnto:p,title:g,tooltipVisibility:d}=e,{navigationSystem:l,storeSystem:v}=i(),c=o(t=>{t?.preventDefault(),t?.stopPropagation();let e=r?l.getPushNavigationUpdate(m,v.stateSlices.committed.value.state,{canStackOnto:p}):l.getNavigationUpdate(m);v.stageAndCommit([e])},[l,m,r,v,p]);return t(n,{kind:"NavigationHotspot",entityId:s,elementProps:a(()=>({navigationState:m,title:g,tooltipVisibility:d,onNavigate:c}),[m,g,d,c])})});

package/dist/react-sdk/scene-control-elements/SelectionHotspotElement.d.ts

@@ -0,0 +1,30 @@
+import { type SyntheticEvent } from 'react';
+import type { Localizable } from '@salsita-ai/common/utils';
+import type { DomainEntityId } from '#package/domain';
+import type { SceneControlTooltipVisibility } from './scene-control-tooltip-visibility.js';
+/**
+ * The name of the entity element that renders a `sceneEntitySelectHotspot`. Its default, the
+ * built-in selection hotspot, is registered in `defaultConfiguratorElements`.
+ */
+export declare const SelectionHotspotName = "SelectionHotspot";
+/**
+ * Props of the `SelectionHotspot` element, rendered for each `sceneEntitySelectHotspot` of an
+ * entity, at the position the component sets.
+ */
+export interface SelectionHotspotElementProps {
+    /** The entity the hotspot selects. */
+    readonly entityId: DomainEntityId<string>;
+    /** The tooltip text. */
+    readonly title?: Localizable;
+    /** When the tooltip shows: `on-hover` unless the component sets it. */
+    readonly tooltipVisibility: SceneControlTooltipVisibility;
+    /**
+     * Selects the entity and pushes the selection-hotspot analytics event. Pass it straight to
+     * `onClick`: given an event, it stops the event's propagation so the click does not reach the scene.
+     */
+    readonly onSelect: (event?: SyntheticEvent) => void;
+}
+type Props = Omit<SelectionHotspotElementProps, 'onSelect'>;
+/** Renders the `SelectionHotspot` element for an entity, with the selection it performs. */
+export declare const SelectionHotspotElement: import("react").MemoExoticComponent<(props: Props) => import("react/jsx-runtime").JSX.Element>;
+export {};