@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/react/useViewEngine.d.ts

@@ -0,0 +1,93 @@
+import { FilterTree, Issue } from '../model/index.js';
+import { ViewEngine, AnyViewRuntime, OpenOptions, ViewEngineOptions } from '../runtime/index.js';
+/**
+ * Creates one engine for the lifetime of the component and disposes it on
+ * unmount. An application that wants a longer life builds the engine itself
+ * and passes it to the other hooks; they take an engine, never options.
+ *
+ * Options are read once. Changing them later has no effect, because a
+ * definition set and a store are not render-time values.
+ */
+export declare function useViewEngine(options: ViewEngineOptions): ViewEngine;
+/**
+ * Subscribes to a runtime. The runtime commits state before it notifies and
+ * returns the same object while nothing changes, which is exactly what
+ * `useSyncExternalStore` asks of a store.
+ *
+ * The parameter is the store shape rather than `ViewRuntime<C>`, so the
+ * discriminated union `open` returns is accepted as it is and the snapshot
+ * type follows from the runtime that was passed.
+ */
+export declare function useViewRuntime<R extends ViewRuntimeStore<unknown>>(runtime: R | null): SnapshotOf<R> | null;
+/** What `useViewRuntime` needs: any runtime satisfies it. */
+export interface ViewRuntimeStore<S> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): S;
+}
+/**
+ * The snapshot a runtime hands out. It distributes, so passing the union
+ * `open` returns gives back the union of their states rather than one member.
+ */
+export type SnapshotOf<R> = R extends {
+    getSnapshot(): infer S;
+} ? S : never;
+/**
+ * What a dashboard opens with, as a host's address has it: the tab on screen
+ * and what the filters hold (D22 E, F), and what an embedding page holds of
+ * them (`held`). Read as the view opens.
+ */
+export type DashboardOpening = Pick<OpenOptions, 'tab' | 'filters' | 'held'>;
+export interface OpenViewState {
+    runtime: AnyViewRuntime | null;
+    loading: boolean;
+    error: Issue | null;
+    /**
+     * What the view refused of the `scopeFilter` asked for, on the first open
+     * as after it. A host that narrows to a field the definition does not admit
+     * keeps the result it had — un-narrowed on an open — so the refusal has to
+     * reach the screen rather than be dropped here.
+     */
+    scopeIssues: Issue[];
+    /**
+     * Opens the same id again: the way back from a failure that may pass — the
+     * store unreachable, or answering with an error of its own
+     * (`retryableOpen`). Loading again until the new answer lands.
+     */
+    retry(): void;
+}
+/**
+ * Whether a failure to open may go away by itself, so trying again is worth
+ * offering: the store could not be reached or could not answer
+ * (`view.open.failed.unavailable`, `….server`), or what failed said nothing
+ * the engine knows (`view.open.failed`). A view that is gone, refused or of
+ * another kind answers the same the next time.
+ */
+export declare function retryableOpen(issue: Issue | null): boolean;
+/**
+ * Opens an instance and owns the runtime it produced: changing the id or
+ * unmounting disposes the previous one, and a response that arrives after that
+ * is dropped rather than applied to a view nobody is looking at.
+ *
+ * A runtime disposed under it — the engine lets one go when its instance is
+ * deleted — is not handed out either. The id is opened again, and the caller
+ * gets a live runtime for what is still there, or the not-found the engine
+ * answers with, in place of a dead runtime that ignores every command.
+ *
+ * Loading is derived rather than stored. As long as the answer on hand belongs
+ * to a different request, this one is still in flight, so the effect sets
+ * state only when a response arrives.
+ *
+ * A `scopeFilter` is in force from the opening query: the engine admits it
+ * with the config, so a host that scopes a view never lets an unscoped query
+ * leave. It is read when the view opens and then followed, so a caller may
+ * pass a fresh object every render without reopening anything. One the
+ * definition refuses is not in force at all — the view runs un-narrowed and
+ * `scopeIssues` says which condition did not take (D17-5).
+ *
+ * `opening` says which tab a dashboard opens on and what its filters hold
+ * (`OpenOptions.tab`, `OpenOptions.filters`), and which definition the
+ * caller draws (`OpenOptions.definitionId`), asked of the caller as each
+ * view opens — only then does it mean anything.
+ */
+export declare function useOpenView(engine: ViewEngine, instanceId: string | null, scopeFilter?: FilterTree | null, opening?: (instanceId: string) => Omit<OpenOptions, 'scopeFilter'> | undefined): OpenViewState;
+//# sourceMappingURL=useViewEngine.d.ts.map

package/dist/react/useViewEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useViewEngine.d.ts","sourceRoot":"","sources":["../../src/react/useViewEngine.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAM7B;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAYpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,gBAAgB,CAAC,OAAO,CAAC,EAChE,OAAO,EAAE,CAAC,GAAG,IAAI,GAChB,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAYtB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,WAAW,IAAI,CAAC,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,WAAW,IAAI,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB;;;;;OAKG;IACH,WAAW,EAAE,KAAK,EAAE,CAAC;IACrB;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAO1D;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,WAAW,GAAE,UAAU,GAAG,IAAW,EACrC,OAAO,CAAC,EAAE,CACR,UAAU,EAAE,MAAM,KACf,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GAAG,SAAS,GAChD,aAAa,CA8Hf"}

package/dist/react/useViewList.d.ts

@@ -0,0 +1,75 @@
+import { Issue, ViewInstanceSummary, ViewKind, ViewPreferences } from '../model/index.js';
+import { ViewEngine } from '../runtime/index.js';
+import { ViewPermissions } from '../store/ViewStore.js';
+export interface ViewListOptions {
+    /**
+     * Narrows the list to these kinds, before it is ordered and before a
+     * default is resolved from it.
+     *
+     * One data definition holds record and analysis instances together, and a
+     * workbench draws the kinds it has parts for — both by default, one when a
+     * host narrows it (D20). Without this the sidebar offers views the body
+     * cannot render, and the effective default may land on one of them — which
+     * is a blank page rather than a view. Left out, every kind is listed, which
+     * is what a dashboard definition wants.
+     */
+    kinds?: readonly ViewKind[];
+}
+/** What a caller already knows about the list it is asking to be read again. */
+export interface ViewListReloadOptions {
+    /**
+     * An instance that is gone: it is dropped from the summaries kept on screen
+     * for the duration of the reload, and `defaultInstanceId` never names it,
+     * before or after the answer lands.
+     *
+     * A reload refreshes rather than blanks, so without this the row deleted a
+     * moment ago goes on being listed — and named as the default — until the
+     * store answers, and a workbench riding on the default reopens a runtime
+     * that has just been disposed.
+     *
+     * A delete through the engine fills this in by itself: the hook hears the
+     * engine say which id went (D15). What is left for a caller is the delete
+     * the engine never saw — a row removed by the host's own backend.
+     */
+    without?: string;
+}
+export interface ViewListState {
+    /** Summaries in the order the workbench shows them. */
+    items: ViewInstanceSummary[];
+    /**
+     * The same summaries before `options.kinds` narrowed them, in the same
+     * order. Equal to `items` when no kinds were asked for.
+     *
+     * A reorder stores one order for the whole definition, and a narrowed
+     * workbench lists only some kinds: submitting the order it can see would
+     * drop every other id from `preferences.order`. So a caller that writes
+     * the order reads it from here and moves the two ids it can see inside it,
+     * leaving the kinds it does not draw where they were.
+     */
+    all: ViewInstanceSummary[];
+    preferences: ViewPreferences | null;
+    permissions: ViewPermissions;
+    /** The view to open when the caller names none; null until preferences settle. */
+    defaultInstanceId: string | null;
+    loading: boolean;
+    error: Issue | null;
+    /** Kept apart: without preferences the list still works, in server order. */
+    preferencesError: Issue | null;
+    /**
+     * Whether the preferences have answered, read or failed. Until then
+     * `preferences` is null for want of an answer, not because there are none,
+     * so nothing the reader set there can be read off it yet.
+     */
+    preferencesSettled: boolean;
+    reload(options?: ViewListReloadOptions): void;
+}
+/**
+ * The list, the preferences and the permissions of one definition.
+ *
+ * They load independently and never block each other: a failed list leaves an
+ * open view alone, and failed preferences only drop back to server order.
+ * Loading is derived from whether the answer on hand belongs to the current
+ * request, so the effect writes state only when a response arrives.
+ */
+export declare function useViewList(engine: ViewEngine, definitionId: string, options?: ViewListOptions): ViewListState;
+//# sourceMappingURL=useViewList.d.ts.map

package/dist/react/useViewList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useViewList.d.ts","sourceRoot":"","sources":["../../src/react/useViewList.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,QAAQ,EACR,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC7B;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B;;;;;;;;;OASG;IACH,GAAG,EAAE,mBAAmB,EAAE,CAAC;IAC3B,WAAW,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,WAAW,EAAE,eAAe,CAAC;IAC7B,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,6EAA6E;IAC7E,gBAAgB,EAAE,KAAK,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC/C;AAkCD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,eAAoB,GAC5B,aAAa,CAyKf"}

package/dist/react/useViewManager.d.ts

@@ -0,0 +1,92 @@
+import { ViewAudience } from '../model/index.js';
+import { ConflictChoice, ViewEngine, WriteState } from '../runtime/index.js';
+import { ViewManagerAbilities } from './manager/abilities.js';
+import { ViewListState } from './useViewList.js';
+export { PREFERENCES_KEY } from './manager/outcomes.js';
+export type { ManagedInstanceAbilities, ViewManagerAbilities, } from './manager/abilities.js';
+export interface ViewManagerController {
+    rename(id: string, title: string): Promise<boolean>;
+    /**
+     * Moves a view to `audience` in place (设为共享／设为个人, D18 item 10);
+     * the list reloads and draws it under that group.
+     */
+    changeAudience(id: string, audience: ViewAudience): Promise<boolean>;
+    delete(id: string): Promise<boolean>;
+    /**
+     * 「发布为系统视图」 (D81): a copy of the saved view, as a stored system
+     * view everyone sees; the view itself stays where it is. The list reloads
+     * and draws the copy among the system views.
+     */
+    publishAsSystem(id: string): Promise<boolean>;
+    setDefault(id: string | null): Promise<boolean>;
+    /**
+     * Puts a view at one place inside its own audience group, counted over the
+     * rows the list shows. The order is one list, but it is read as two —
+     * personal above shared — so a move across that boundary is a write with
+     * nothing to show for it, and there is no index that expresses one.
+     *
+     * It resolves false without writing when there is nothing to do: a row the
+     * list no longer holds, or one already at that place.
+     */
+    moveTo(id: string, index: number): Promise<boolean>;
+    /**
+     * Where a row sits inside its own group, which is the index {@link moveTo}
+     * is expressed in — a drag reads it off the row it was dropped on, the
+     * arrow keys off the row itself. -1 when the list does not hold the row.
+     *
+     * **Ask it as the move is made, not while rendering.** A move that is
+     * queued but has not landed is not in the list yet, and this answers for
+     * the order that move submitted — which is the one the next move has to be
+     * expressed in, and which no render can see.
+     */
+    placeOf(id: string): number;
+    /**
+     * Unresolved outcomes, by instance id or {@link PREFERENCES_KEY}. Empty
+     * again once `definitionId` or `engine` changes: they answer for the rows
+     * of the definition they were raised under, not for whichever list is on
+     * screen now.
+     */
+    outcomes: ReadonlyMap<string, WriteState>;
+    retry(key: string): Promise<boolean>;
+    abandon(key: string): void;
+    resolveConflict(key: string, choice: ConflictChoice): Promise<boolean>;
+    /**
+     * Puts the intent that conflicted to the store once more, as a new write
+     * against the revision just reloaded — the second half of how design/management.md
+     * settles a preference conflict: reload, keep the intent, put it to the
+     * user again. It is not a replay of the old write, which would carry the
+     * revision that lost, nor of the whole record, which would carry the other
+     * half of the preferences as they were read before the reload.
+     */
+    resubmit(key: string): Promise<boolean>;
+    /** Whether {@link resubmit} has an intent to put again under this key. */
+    canResubmit(key: string): boolean;
+    /**
+     * The key of the write in flight, so one row alone shows progress. Commands
+     * run one at a time, so there is never a second write for this one slot to
+     * be wrong about.
+     */
+    pending: string | null;
+    can: ViewManagerAbilities;
+}
+/**
+ * Managing the views a list shows, rather than the one that is open: rename,
+ * move to the other audience, delete, reorder and choose a default, with the recovery actions for writes
+ * that no runtime owns.
+ *
+ * Every command resolves rather than rejects, as `useSaveCommands` does: what
+ * happened lands in `outcomes` under the row it belongs to, so a click handler
+ * needs no try/catch and an unresolved write stays visible until the user
+ * retries, overwrites or abandons it. A write that lands reloads the list,
+ * because it is the list that changed.
+ *
+ * This is the composition alone. The rules the commands are decided by live
+ * beside it: `react/writes.ts` is the one write-outcome vocabulary this hook
+ * and `useSaveCommands` share, `manager/outcomes.ts` holds the map of slots
+ * those rules are asked about,
+ * `manager/queue.ts` serializes, `manager/order.ts` does the arithmetic of a
+ * move, and `manager/useCommandRunner.ts` is the protocol all five commands
+ * and the recovery actions run under.
+ */
+export declare function useViewManager(engine: ViewEngine, definitionId: string, list: ViewListState): ViewManagerController;
+//# sourceMappingURL=useViewManager.d.ts.map

package/dist/react/useViewManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useViewManager.d.ts","sourceRoot":"","sources":["../../src/react/useViewManager.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EAEV,UAAU,EACX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAe,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAahF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC1C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,0EAA0E;IAC1E,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,oBAAoB,CAAC;CAC3B;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,GAClB,qBAAqB,CA0SvB"}

package/dist/react/useWorkbench.d.ts

@@ -0,0 +1,334 @@
+import { FilterNode, FilterTree, Issue, RecordViewConfig, ViewConfig, ViewInstance, ViewKind } from '../model/index.js';
+import { AnyViewRuntime, BoardOrigin, GroupNaming, ViewEngine, ViewHandOver, ViewNavigation, ViewRuntimeState, WriteAction } from '../runtime/index.js';
+import { RefreshController } from './useAutoRefresh.js';
+import { FilterEditorController } from './useFilterEditor.js';
+import { SaveCommands } from './useSaveCommands.js';
+import { DashboardOpening, OpenViewState } from './useViewEngine.js';
+import { ViewListState } from './useViewList.js';
+import { ViewManagerController } from './useViewManager.js';
+import { LeaveGuard } from './workbench/leaveGuard.js';
+import { NewViewOptions } from './workbench/newView.js';
+export interface WorkbenchOptions {
+    /**
+     * The kinds this workbench has parts for. They narrow the list — and with
+     * it the effective default — and an instance of any other kind is reported
+     * as unopenable. A data workbench draws record and analysis views in one
+     * list (D20); a host narrows it to one kind by naming only that one (D9).
+     */
+    kinds: readonly ViewKind[];
+    /**
+     * Which view is open, as `value` is on an input: leaving it out is the
+     * uncontrolled form and the workbench owns the open view from the effective
+     * default on; passing it — a string, or `null` for that effective default —
+     * makes the host the one that says which view is open, and every later
+     * change of it opens that view.
+     *
+     * It converges rather than renders, because a view holds an unsaved draft:
+     * a pushed value goes through the same leave guard a click goes through,
+     * and `onInstanceChange` says what is open now. See
+     * `workbench/instanceSync.ts` for the whole of that contract.
+     */
+    instanceId?: string | null;
+    /**
+     * Told which view is open whenever that changes: the user picked another,
+     * a save-as opened its copy, a rename kept it, or a deleted view let the
+     * pin go. `null` means the effective default, exactly as it does in
+     * `instanceId`, so what comes out goes back in unchanged — which is what
+     * makes a workbench addressable by a route.
+     */
+    onInstanceChange?(id: string | null): void;
+    /**
+     * Whether closing the tab is guarded as well as switching views. On by
+     * default; a host that mounts this workbench as one part of a larger page
+     * — or renders it on a server — can say no. See `workbench/leaveGuard.ts`.
+     */
+    guardUnload?: boolean;
+    /**
+     * What a view made from nothing opens as: the name it carries until its
+     * first save, and the config it starts from. Left out, the workbench
+     * offers no new view — the engine refuses a view with no title, and the
+     * title is wording, which this layer does not carry. `/ui` passes its
+     * catalogue's word; a host's own template goes in `templates`. A view
+     * opened out of another is named by whoever opens it (`drill`, `follow`),
+     * so this has no say there.
+     */
+    newView?: NewViewOptions;
+    /**
+     * Takes over drilling (H5): given, the workbench builds the record view a
+     * row would open and hands it here instead of holding it — a host that
+     * wants the records on a page of its own opens them there. `canDrill` is
+     * unchanged by it; the gesture exists exactly when there is something to
+     * drill into.
+     */
+    onDrilldown?(target: DrillTarget): void;
+    /**
+     * What a dashboard opens with (D22 E, F), asked as each view opens: the
+     * tab and the filter values a host's route names. Nothing, and the board
+     * opens where its reader last read it, every filter at its default
+     * (`ViewEngine.open`).
+     */
+    opening?(instanceId: string): DashboardOpening | undefined;
+    /**
+     * A view a dashboard or an embed handed the host's route, to open here
+     * (D22 H, D26 Q30): a saved one (`view`), opened by its id with what the
+     * reader set on the board among its own conditions, or one nobody saved
+     * (`unsaved`) — a follow-up on a group, a board's own analysis — opened as
+     * a view made from nothing. Either runs under what the page holds as its
+     * scope. Each new object opens once, through the leave guard
+     * (`useHandOver`).
+     */
+    handOver?: ViewHandOver | null;
+    /**
+     * The host's route, which the way back to the board a view was handed
+     * from goes by (`board`, D26 Q33). Without it there is no way back drawn.
+     */
+    onNavigate?(to: ViewNavigation): void;
+}
+/**
+ * Where a held view came from: the view it was drilled out of, and the
+ * conditions the drill added. It is the workbench's fact, not the view's —
+ * the "from" line under the title bar reads it, and going back is the
+ * workbench's command — so it lives beside the held view rather than in its
+ * config, which is what a save would keep.
+ */
+export interface ViewOrigin {
+    /** The view drilled from, still open with the result it was drilled on. */
+    runtime: AnyViewRuntime;
+    title: string;
+    /** What the drill added to the origin's conditions: the row's own. */
+    conditions: readonly FilterNode[];
+}
+/** What a drill would open, as offered to a host that takes drilling over. */
+export interface DrillTarget {
+    definitionId: string;
+    origin: ViewOrigin;
+    /** The name the records open under, as the caller of `drill` gave it. */
+    title: string;
+    /** The record view: the origin's filter plus the row's, default columns. */
+    config: RecordViewConfig;
+    /** The origin's injected scope, which the drilled view inherits (H4). */
+    scopeFilter: FilterTree | null;
+}
+/**
+ * A view the workbench holds rather than opens by id: made from nothing, or
+ * drilled out of another. The draft it opened with is kept so the leave
+ * guard can tell an untouched one — which costs nothing to let go — from one
+ * the user has already shaped.
+ */
+export interface HeldView {
+    runtime: AnyViewRuntime;
+    draft: ViewConfig;
+    /** Null for a view made from nothing; a drilled view knows its origin. */
+    origin: ViewOrigin | null;
+    /**
+     * What its title says of the group it was opened from, when it names one
+     * (「订单 · 仓库 是 华南」): while those conditions still narrow it, the
+     * title stands; once the reader takes one off, the workbench calls it by
+     * `subject` (`WorkbenchController.state`).
+     */
+    named?: GroupNaming;
+    /**
+     * The held view the origin itself was, when it was one: drilling out of an
+     * unsaved analysis view — or out of a group already followed — must not
+     * let that view go, so going back puts it back as it was held.
+     */
+    from: HeldView | null;
+    /**
+     * Handed over by a host (`WorkbenchOptions.unsaved`) — a dashboard's
+     * follow-up on a group, a board's own analysis — rather than made here:
+     * like a view opened from another's group, its conditions are what it was
+     * opened with, so the shell opens it with its editor folded.
+     */
+    handed?: true;
+    /** The board it was handed from, for the way back (`WorkbenchController.board`). */
+    board?: BoardOrigin;
+}
+/**
+ * Everything a workbench needs that is not its own markup: which views there
+ * are, which one is open, what it says, and what happens when the user moves
+ * to another.
+ *
+ * The default workbenches differ in their editor and their result and in
+ * nothing else, so the shell around those two is assembled once here. A host
+ * that writes its own markup calls this and loses none of the rules — the
+ * wrong-kind report, the released pin, the leave guard and the header's four
+ * outcomes are all in the controller rather than in the components.
+ */
+export interface WorkbenchController {
+    /** The kinds this workbench draws, as it was given them. */
+    kinds: readonly ViewKind[];
+    /**
+     * 「改了就跑」 (D20): whether an analysis runs again on its own as its
+     * question is edited — the user's preference for this definition, on
+     * when unsaid, pushed onto the open analysis view. The range still waits
+     * for Apply either way.
+     */
+    autoRun: boolean;
+    setAutoRun(on: boolean): Promise<void>;
+    /** The views of this definition, of those kinds, in the user's order. */
+    list: ViewListState;
+    manager: ViewManagerController;
+    /** What is open now: the explicit choice, or the effective default. */
+    openId: string | null;
+    /** Opens another view, through the leave guard. */
+    choose(id: string | null): void;
+    /**
+     * The kinds a new view may be made of here, in the order of `kinds`: the
+     * definition has the kind, the user may create in some audience, and
+     * `newView` gave it a name. Every "new view" control exists on this and
+     * on nothing else (D4) — one kind is a button, several are a menu, none is
+     * no control.
+     */
+    creatable: readonly ViewKind[];
+    /**
+     * Opens a view of that kind made from nothing, through the leave guard;
+     * a kind not in `creatable` does nothing. It is unsaved until its first
+     * save, which is a create: the workbench then opens what the store took,
+     * as it does a copy. An unsaved view has no id, so a host routing the
+     * workbench hears nothing until that save lands.
+     */
+    create(kind: ViewKind): void;
+    /**
+     * The view the workbench holds instead of opening by id, if any: one made
+     * from nothing, or one opened out of another (`drill`, `follow`). Its
+     * `origin` is what the "from" line reads.
+     */
+    held: HeldView | null;
+    /**
+     * Whether a row of the open analysis view can open the records behind it
+     * (H2): the workbench draws record views and the definition has them.
+     * The drill gesture exists on this and on nothing else.
+     */
+    canDrill: boolean;
+    /**
+     * Opens the records behind one row of the open analysis view: an unsaved
+     * record view under the origin's conditions plus `conditions`, held with
+     * its origin so the way back is on screen (D20). The origin stays open
+     * with the result it was drilled on, so going back shows that result
+     * rather than running it again. Nothing is left behind, so the leave guard
+     * is not asked. Does nothing while `canDrill` is false.
+     *
+     * `title` is what the records open under until they are saved — wording,
+     * which this layer does not carry, so the caller says it: `/ui` names them
+     * by what they are, the definition's records of that group (D20 追问).
+     * `subject` is that name without the group, which the view goes by once
+     * `conditions` no longer narrow it (`GroupNaming`); left out, `title`
+     * stands whatever the conditions become.
+     */
+    drill(conditions: readonly FilterNode[], title: string, subject?: string): void;
+    /**
+     * Opens `config` as a view of its own, held with the open view as its
+     * origin: the follow-up that narrows an analysis to one group (D20 追问
+     * 「只显示这一组」) is a new question beside the one it came from, not an
+     * edit that writes over it. The origin stays open with its result, so
+     * `back()` shows that result again without running it; the view opened is
+     * unsaved, named `title`, under the origin's injected scope, and saving it
+     * is a first save like any new view's. `conditions` are what the follow-up
+     * added, kept on the origin for whoever reads it. The origin keeps its
+     * draft, so the leave guard is not asked. `subject` is as `drill`'s.
+     */
+    follow(config: ViewConfig, title: string, conditions: readonly FilterNode[], subject?: string): void;
+    /**
+     * Returns to the held view's origin, through the leave guard: an untouched
+     * view opened out of another goes without a question, one the user shaped
+     * is asked about. Does nothing while nothing held has an origin.
+     */
+    back(): void;
+    /**
+     * The board the open view was handed from (D26 Q33), while it is the view
+     * on screen and a route goes back: the shell draws 「返回〈仪表盘〉」 from
+     * it. `null` under a view opened out of another here, whose own way back
+     * (`back`) is the one on screen.
+     */
+    board: BoardOrigin | null;
+    /** Goes back to `board` through the host's route, past the leave guard. */
+    toBoard(): void;
+    /**
+     * Whether the view on screen is one a board or an embed handed over
+     * (`handOver`, D26 Q30), saved or not: the press that sent it took the
+     * keyboard off the page it was on, so the shell gives it to the title.
+     */
+    handedOver: boolean;
+    opened: OpenViewState;
+    /** Null while the view is unopenable or still loading. */
+    runtime: AnyViewRuntime | null;
+    /**
+     * The open view's state — under the name it goes by now: a held view
+     * named by a group whose conditions it no longer runs under is called by
+     * its `subject` (`HeldView.named`), so the title bar, 「另存为」 and a
+     * follow-up opened from it never name a group it does not show.
+     */
+    state: ViewRuntimeState<ViewConfig> | null;
+    /**
+     * Why there is nothing to draw: the open failed, or it opened and is of
+     * another kind. A host may name any id, so a view this page has no kernel
+     * for is reported where every other failure to open is, rather than left
+     * as a title bar over an empty body.
+     */
+    unopenable: Issue | null;
+    /**
+     * What admission found wrong with the definition itself — a system view
+     * the kernel refuses, a field group naming a field it does not have.
+     * The shell shows them in the status line beside the view's own, since a
+     * definition's error is otherwise reported to `onIssue` alone and the
+     * screen said nothing.
+     */
+    definitionIssues: Issue[];
+    /**
+     * Where the open view sits in the definition's `views`, when it is one
+     * the definition declares in code, else `null`. A definition finding under
+     * `['views', n, …]` with this `n` is about the view on screen — which, for
+     * a board, reports its own panels' findings by name as well (`panels`),
+     * so the status line says each once.
+     */
+    declaredAt: number | null;
+    commands: SaveCommands;
+    /**
+     * How the open view renews its own answer: one refresh now, and the
+     * interval it keeps itself up to date by. It is assembled here rather than
+     * in each workbench because `refresh` lives on `ViewConfigBase` — every
+     * kind has one, and every kind reaches it the same way.
+     */
+    refresh: RefreshController;
+    /**
+     * The open view's filter editor. One per opening, built here because the
+     * shell needs it too — the applied bar describes it, and the error strip
+     * shows exactly the errors it does not mark (`filter.unmarked`).
+     */
+    filter: FilterEditorController;
+    leave: LeaveGuard;
+    /** A saved copy is what the workbench then shows. */
+    onSaved(instance: ViewInstance): void;
+    /**
+     * A rename keeps the view. The pin goes on before the reload: a workbench
+     * riding on the default would otherwise close its runtime and lose the
+     * draft.
+     */
+    onRenamed(instance: ViewInstance): void;
+    /**
+     * A delete moves on. The engine let the runtime go with the instance, and
+     * it has already told the list which id went (D15), so all that is left
+     * here is to let the pin go: the default moves, and the open id follows it
+     * — or empties with the list.
+     */
+    onDeleted(): void;
+    /** A recovered write may have changed the list; read it again. */
+    onRecovered(action: WriteAction): void;
+}
+/**
+ * The shell of one workbench, without any of its look.
+ *
+ * The kinds are a parameter: what differs between record, analysis and
+ * dashboard is the editor and the result they render from `runtime`, not the
+ * way a view is found, opened, left or saved.
+ *
+ * One command is the exception, and it is the follow-up seam rather than an
+ * oversight: `drill` opens the records behind one group of an analysis
+ * result (D20 追问). It names both kinds on purpose — `canDrill` asks the
+ * open view to be an `analysis` and `record` to be among the kinds this
+ * workbench lists, and what it opens is a `RecordViewConfig` built from
+ * `defaultRecordConfig` with `drillFilter` over the conditions that ran.
+ * Nothing else here reads a kind.
+ */
+export declare function useWorkbench(engine: ViewEngine, definitionId: string, options: WorkbenchOptions): WorkbenchController;
+//# sourceMappingURL=useWorkbench.d.ts.map

package/dist/react/useWorkbench.d.ts.map

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