@ai-matrx/summon 0.0.0-stage → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,261 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { Store, Dispatch, UnknownAction } from '@reduxjs/toolkit';
+import { SummonPorts, SummonRootState, InstanceKey, OverlayRawData, AnyOverlayMeta, OverlayDefinitionMeta, OverlayId, OverlayDataOf, ErrorSinkPort } from '@ai-matrx/summon';
+import { ReactReduxContextValue, UseDispatch, UseSelector, UseStore } from 'react-redux';
+
+interface RenderModule<P> {
+    readonly default: ComponentType<P>;
+}
+type RenderLoader<P> = () => Promise<RenderModule<P>>;
+/** The error a stalled import becomes, so the error boundary always fires. */
+declare function chunkTimeoutError(key: string, timeoutMs: number): Error;
+
+declare const SummonStoreContext: react.Context<ReactReduxContextValue<any, _reduxjs_toolkit.UnknownAction> | null>;
+/** What every slot hands to `renderWrapper`, error extras and the fallbacks. */
+interface OverlayRenderContext {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: string;
+    readonly label: string;
+}
+interface OverlayLoadingFallbackProps {
+    readonly overlayId: string;
+    readonly label: string;
+}
+interface OverlayErrorFallbackProps {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly label: string;
+    readonly error: unknown;
+    readonly componentStack: string | null;
+    /** Re-import the render module and mount again. */
+    readonly retry: () => void;
+    /** Close this instance (no reload). */
+    readonly close: () => void;
+    /** Host-provided extras (AI Matrx: "Copy for AI"), already rendered for this error. */
+    readonly extras: ReactNode;
+}
+interface OverlayErrorExtrasContext extends OverlayRenderContext {
+    readonly error: unknown;
+    readonly componentStack: string | null;
+}
+
+declare const DEFAULT_KEEP_ALIVE_LIMIT = 8;
+declare const DEFAULT_IMPORT_TIMEOUT_MS = 12000;
+declare const DEFAULT_STALL_WARN_MS = 10000;
+interface SummonProviderProps {
+    /** The host's Redux store with `summonReducers` mounted at their root keys. Omit for a private store. */
+    readonly store?: Store<unknown>;
+    /** Host ports; anything omitted uses the working default. */
+    readonly ports?: Partial<SummonPorts>;
+    readonly fallbacks?: {
+        readonly loading?: ComponentType<OverlayLoadingFallbackProps>;
+        readonly error?: ComponentType<OverlayErrorFallbackProps>;
+    };
+    /** Extra controls in the default error card's footer (AI Matrx: "Copy for AI"). */
+    readonly errorReportExtras?: (context: OverlayErrorExtrasContext) => ReactNode;
+    /** Wrap every rendered overlay (AI Matrx: its surface layer boundary). */
+    readonly renderWrapper?: (node: ReactNode, context: OverlayRenderContext) => ReactNode;
+    /** Most closed-but-alive (`keepAlive: "hidden"`) instances kept mounted. Default 8. */
+    readonly keepAliveLimit?: number;
+    /** A render-module import that has not settled by then becomes a ChunkLoadError. Default 12 s. */
+    readonly importTimeoutMs?: number;
+    /** When the loading fallback reports a stall to the error port. Default 10 s. */
+    readonly stallWarnMs?: number;
+    readonly children?: ReactNode;
+}
+declare function SummonProvider({ store, ports, fallbacks, errorReportExtras, renderWrapper, keepAliveLimit, importTimeoutMs, stallWarnMs, children, }: SummonProviderProps): react.JSX.Element;
+
+/** Dispatch as the React section uses it: plain actions (thunks are the host's business). */
+type SummonReactDispatch = Dispatch<UnknownAction>;
+/** The store as the React section sees it: the overlays slices at their root keys (a host store has more). */
+type SummonReactStore = Store<SummonRootState>;
+/** Select from the overlays store. */
+declare const useSummonSelector: UseSelector<SummonRootState>;
+/** The overlays store's dispatch. */
+declare const useSummonDispatch: UseDispatch<SummonReactDispatch>;
+/** The overlays store itself (for `getState()` inside callbacks). */
+declare const useSummonStore: UseStore<SummonReactStore>;
+/** The resolved ports of the nearest provider. */
+declare function useSummonPorts(): SummonPorts;
+/**
+ * The provider's ports, or the working defaults when no SummonProvider is above — for
+ * components that are usable page-local without the system (dialogs, sheets).
+ */
+declare function useOptionalSummonPorts(): SummonPorts;
+
+/** Event name → payload, declared once per overlay: `defineOverlay<Data, { uploaded: Result }>()`. */
+type OverlayEventMap = Record<string, unknown>;
+type OverlayHandlers<Events extends OverlayEventMap> = {
+    readonly [K in keyof Events]?: (payload: Events[K]) => void;
+};
+
+/** The props every overlay's render module receives. */
+interface OverlayRenderProps<Data = OverlayRawData> {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    /** The open data: raw (narrow it yourself) unless the definition declares `parse`. */
+    readonly data: Data;
+    readonly isOpen: true;
+    readonly close: () => void;
+    /** True while kept alive behind a close (`keepAlive: "hidden"`). */
+    readonly hidden: boolean;
+}
+/** What the host hands each instance — no data type, by design. */
+interface InstanceBodyProps {
+    readonly instanceId: string;
+    readonly instanceKey: InstanceKey;
+    readonly data: OverlayRawData;
+    readonly hidden: boolean;
+    readonly close: () => void;
+}
+
+/** The open-data key that carries an overlay's event channel id (the old callback-group key). */
+declare const CALLBACK_GROUP_KEY = "callbackGroupId";
+interface OverlayHandle {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    close(): void;
+}
+interface OverlayOpenOptions<Data, Events extends OverlayEventMap> {
+    readonly data?: Data;
+    /** Single-instance overlays ignore it unless given; multi-instance generate one when omitted. */
+    readonly instanceId?: string;
+    /** Plain functions; they reach the caller through an event channel owned by the instance. */
+    readonly handlers?: OverlayHandlers<Events>;
+}
+type OverlayOpener<Data, Events extends OverlayEventMap> = (options?: OverlayOpenOptions<Data, Events>) => OverlayHandle;
+type OverlayControllerProps<Data, Events extends OverlayEventMap> = Data & {
+    readonly instanceId?: string;
+    readonly handlers?: OverlayHandlers<Events>;
+};
+type OverlayEmitter<Events extends OverlayEventMap> = <K extends keyof Events & string>(event: K, payload: Events[K]) => void;
+/** What a definition file passes to `defineOverlay<Data>()(…)`. */
+interface OverlaySpec<Id extends string, Data, Parsed> extends OverlayDefinitionMeta<Id, Data> {
+    /** The lazily loaded render module. Its default export receives `OverlayRenderProps<Parsed>`. */
+    readonly render: () => Promise<RenderModule<OverlayRenderProps<NoInfer<Parsed>>>>;
+    /** Narrow raw open data once. `null` = refuse: the instance is closed with a warning. */
+    readonly parse?: (raw: OverlayRawData) => Parsed | null;
+}
+/** The type-erased half the host renders; no data types cross this line. */
+interface HostableOverlay {
+    readonly id: string;
+    readonly label: string;
+    readonly instance: "single" | "multi";
+    readonly keepAlive: "none" | "hidden" | "restore";
+    /** The metadata the core registry stores (links, window options, defaults…). */
+    readonly meta: AnyOverlayMeta;
+    readonly Body: ComponentType<InstanceBodyProps>;
+}
+interface OverlayDefinition<Id extends string, Data, Parsed, Events extends OverlayEventMap> extends Omit<OverlayDefinitionMeta<Id, Data>, "id" | "instance" | "keepAlive">, HostableOverlay {
+    readonly id: Id;
+    readonly render: () => Promise<RenderModule<OverlayRenderProps<Parsed>>>;
+    /** Imperative opener: `const open = def.useSummon(); open({ data })` → handle. */
+    useSummon(): OverlayOpener<Data, Events>;
+    /** Declarative form: opens on mount, closes on unmount, re-opens when its data changes. */
+    readonly Controller: (props: OverlayControllerProps<Data, Events>) => null;
+    useIsOpen(instanceId?: string): boolean;
+    /** `const close = def.useClose(); close(instanceId?)`. */
+    useClose(): (instanceId?: string) => void;
+    /** Inside the render tree: emit a declared event to the opener's handlers. */
+    useEmit(): OverlayEmitter<Events>;
+}
+/**
+ * Declare an overlay once. Curried so `Data` (and `Events`) are named while the id and the
+ * parsed-data type are inferred:
+ *
+ *   export const notesWindow = defineOverlay<NotesWindowData>()({
+ *     id: "notesWindow", label: "Notes", render: () => import("./notesWindow.render"),
+ *   });
+ */
+declare function defineOverlay<Data extends object = Record<string, never>, Events extends OverlayEventMap = Record<never, never>>(): <const Id extends string, Parsed = OverlayRawData>(spec: OverlaySpec<Id, Data, Parsed>) => OverlayDefinition<Id, Data, Parsed, Events>;
+
+interface SummonHostProps {
+    /** Every overlay this host can render — the app's definition list, passed once. */
+    readonly definitions: readonly HostableOverlay[];
+}
+/** Close-on-navigation: on a pathname change, close every overlay bound to the page. */
+declare function useCloseOnNavigation(): void;
+declare function SummonHost({ definitions }: SummonHostProps): react.JSX.Element;
+
+interface OverlayInstanceContextValue {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: InstanceKey;
+    readonly close: () => void;
+    readonly hidden: boolean;
+    /** The open data as it arrived (pre-parse); event emitters read their channel id from it. */
+    readonly rawData: OverlayRawData;
+}
+/** The open instance this component renders inside. Throws outside an overlay. */
+declare function useOverlayInstance(): OverlayInstanceContextValue;
+/** Same as `useOverlayInstance`, but `null` outside an overlay. */
+declare function useOptionalOverlayInstance(): OverlayInstanceContextValue | null;
+type OverlayStateSetter<T> = (next: T | ((previous: T) => T)) => void;
+/**
+ * Saved state for the current overlay instance — `useState`, but kept in the overlays store under
+ * `overlayId:instanceId` so it survives `keepAlive: "restore"` close/reopen and is persisted when
+ * persistence is on. Any descendant of the overlay may call it; the same `name` reads the same
+ * value. Values must be serialisable.
+ */
+declare function useOverlayState<T>(name: string, initial: T): [T, OverlayStateSetter<T>];
+
+/** True while the instance is open. */
+declare function useIsOverlayOpen(overlayId: OverlayId, instanceId?: string): boolean;
+interface OpenOverlayOptions<Id extends OverlayId> {
+    readonly data?: OverlayDataOf<Id>;
+    readonly instanceId?: string;
+}
+/**
+ * Open an overlay by id. A multi-instance overlay (per its registered definition) gets a fresh
+ * instance id when none is given; a single-instance one opens "default".
+ */
+declare function useOpenOverlay<Id extends OverlayId>(overlayId: Id): (options?: OpenOverlayOptions<Id>) => OverlayHandle;
+/** A stable close function for one instance (pass straight to an `onClose` prop). */
+declare function useCloseOverlay(overlayId: OverlayId, instanceId?: string): () => void;
+
+interface OverlayErrorBoundaryProps {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: string;
+    readonly label: string;
+    readonly errors: ErrorSinkPort;
+    readonly fallback: ComponentType<OverlayErrorFallbackProps>;
+    readonly extras: ((context: OverlayErrorExtrasContext) => ReactNode) | null;
+    /** Swap in a fresh loader BEFORE the boundary clears, so the remount re-imports. */
+    readonly onRetry: () => void;
+    readonly onClose: () => void;
+    readonly children: ReactNode;
+}
+interface OverlayErrorBoundaryState {
+    readonly error: unknown;
+    readonly hasError: boolean;
+    readonly componentStack: string | null;
+}
+declare class OverlayErrorBoundary extends Component<OverlayErrorBoundaryProps, OverlayErrorBoundaryState> {
+    state: OverlayErrorBoundaryState;
+    static getDerivedStateFromError(error: unknown): Partial<OverlayErrorBoundaryState>;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    private readonly retry;
+    render(): ReactNode;
+}
+
+interface NormalizedOverlayError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack: string | null;
+    readonly isChunkLoadError: boolean;
+}
+declare function normalizeOverlayError(error: unknown): NormalizedOverlayError;
+/**
+ * Spinner while the render module is in flight. Never blank. At the stall threshold it reports
+ * once through the error port; the loader's import timeout (later) turns a hung import into a
+ * real error so the error fallback takes over.
+ */
+declare function OverlayLoadingFallback({ overlayId, label }: OverlayLoadingFallbackProps): react.JSX.Element;
+/** The error card: what failed, and a way out that never needs a page reload. */
+declare function OverlayErrorFallback({ label, error, retry, close, extras }: OverlayErrorFallbackProps): react.JSX.Element;
+
+export { CALLBACK_GROUP_KEY, DEFAULT_IMPORT_TIMEOUT_MS, DEFAULT_KEEP_ALIVE_LIMIT, DEFAULT_STALL_WARN_MS, type HostableOverlay, type NormalizedOverlayError, type OpenOverlayOptions, type OverlayControllerProps, type OverlayDefinition, type OverlayEmitter, OverlayErrorBoundary, type OverlayErrorBoundaryProps, type OverlayErrorExtrasContext, OverlayErrorFallback, type OverlayErrorFallbackProps, type OverlayEventMap, type OverlayHandle, type OverlayHandlers, type OverlayInstanceContextValue, OverlayLoadingFallback, type OverlayLoadingFallbackProps, type OverlayOpenOptions, type OverlayOpener, type OverlayRenderContext, type OverlayRenderProps, type OverlaySpec, type OverlayStateSetter, type RenderLoader, type RenderModule, SummonHost, type SummonHostProps, SummonProvider, type SummonProviderProps, type SummonReactDispatch, type SummonReactStore, SummonStoreContext, chunkTimeoutError, defineOverlay, normalizeOverlayError, useCloseOnNavigation, useCloseOverlay, useIsOverlayOpen, useOpenOverlay, useOptionalOverlayInstance, useOptionalSummonPorts, useOverlayInstance, useOverlayState, useSummonDispatch, useSummonPorts, useSummonSelector, useSummonStore };