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

package/dist/react/useFilterEditor.d.ts

@@ -0,0 +1,255 @@
+import { FieldDefinition, FieldGroupDefinition, FilterGroupOperator, FilterLeaf, FilterMode, FilterOperatorName, FilterTree, Issue } from '../model/index.js';
+import { EditorDescriptor, FieldKindRegistry, FilterPath, FilterSummaryItem } from '../filter/index.js';
+import { OptionSource, ValueCandidateSource, ViewRuntime } from '../runtime/index.js';
+/**
+ * One view's filter editor: a tree to edit, plus the things that belong to
+ * the view around it — which mode it shows, what is currently applied, and
+ * when to run.
+ */
+export interface FilterEditorController extends FilterTreeController {
+    mode: FilterMode;
+    /**
+     * The view's own conditions the rows on screen were fetched under, for a
+     * summary bar. It reads the config the result carries rather than `applied`,
+     * so the bar always describes the data beside it: applying starts a query,
+     * and until it answers, `applied` has already moved on. Before any result
+     * exists it describes the question on its way, or the one that failed —
+     * there are no rows for it to contradict, and the bar stands in its place
+     * from the first query rather than appearing as the answer lands. Empty
+     * while nothing has been asked (`hasAsked`).
+     *
+     * It describes `result.own`, not `result.config`: under a host scope filter
+     * the two differ, and only the first is addressed by the paths this editor
+     * takes — so `clearValue(item.path)` takes out the condition the badge names
+     * (each of `item.paths`, for a segment). The scope's own conditions are
+     * `scoped`.
+     *
+     * A dashboard has no conditions of its own to describe (D27): a reader
+     * narrows it through its filters, which are a bar of their own, so this
+     * is empty there. What it holds in force besides is `fixed`.
+     *
+     * A draft over the tree budget does not empty it. What the rows came back
+     * under was admitted before it ran, so it is within budget whatever the
+     * draft has since become, and a summary that blanked while the user edited
+     * would stop describing the data it sits beside.
+     */
+    applied: FilterSummaryItem[];
+    /**
+     * The host's own conditions, in force alongside `applied` but not this
+     * editor's to change: `setScopeFilter` injects them, the draft never holds
+     * them, and no path here addresses them. A bar shows them as plain items,
+     * with no remove — `clearValue` cannot reach them, and offering it would
+     * promise a narrowing the user cannot undo. Empty when no scope is injected.
+     */
+    scoped: FilterSummaryItem[];
+    /**
+     * A dashboard's fixed scope (「固定范围」, `DashboardViewConfig.fixed`, D26
+     * Q31): the board's own condition every panel runs under, in force beside
+     * its filters and no reader's to change — so, like `scoped`, a bar shows it
+     * with no remove, and no path here addresses it. Read off `applied`, as a
+     * dashboard's `applied` is. Empty for any other view, and on a board built
+     * since batch C.
+     */
+    fixed: FilterSummaryItem[];
+    /**
+     * Readings in force that nobody wrote: a declared deletion dimension the
+     * view's own conditions and the host's scope both leave unanswered reads
+     * as "not deleted" (D17-2), and a bar that kept quiet about it would be
+     * describing rows it does not show. Like `scoped`, nothing here is the
+     * editor's to remove; unlike it, adding the field is how it changes.
+     */
+    implied: FilterSummaryItem[];
+    count: number;
+    /** False when the tree needs the advanced editor to be shown faithfully. */
+    simple: boolean;
+    /**
+     * True when the draft says something other than what was last applied —
+     * anywhere in the config, not only in the conditions (D17-6). Apply runs
+     * the whole draft, so its dot answers for the whole draft: a sort or a
+     * page size whose apply was refused, an analysis editor's groups waiting
+     * for Run, a filter mode switched and not applied. See `comparePending`.
+     */
+    pending: boolean;
+    /**
+     * How many edits wait for Apply; a badge count. The conditions count node
+     * by node, both ways — a path the draft has and the applied tree does not
+     * is a new condition, and a path only the applied tree has is one removed
+     * since, so a cleared filter counts every condition it dropped — and every
+     * other member of the config that differs counts as one.
+     */
+    pendingCount: number;
+    /**
+     * Whether the conditions themselves differ from the ones applied. This is
+     * what `discard` can put back, so the offer to discard follows it rather
+     * than `pending`: a sort waiting for apply is pending, and discarding the
+     * conditions would not touch it.
+     */
+    conditionsPending: boolean;
+    /**
+     * Whether the node at `path` has been edited since the last apply. Compares
+     * that node alone — a leaf by field, operator and value, a group by its
+     * operator — so one edited condition marks one pill, not its ancestors too.
+     * A node the applied tree has nothing at is pending: it is new. A node only
+     * the applied tree has is pending too: it is gone.
+     */
+    isPending(path: FilterPath): boolean;
+    /**
+     * How many `issues` block apply by addressing a condition of this filter.
+     * Every one of them counts, including the ones the panel can draw no pill
+     * for — a malformed node has nothing to render — because Apply is refused
+     * for those just the same, and a count that left them out would be a
+     * button that stays disabled with nothing to show for it. What has no pill
+     * is said in the strip above the editor (`unmarkedErrors`), so the count
+     * never points at a fix that is nowhere on screen.
+     */
+    blocked: number;
+    /**
+     * The blocking errors the panel can draw on no pill, which is where the
+     * count above points when it points at nothing: a malformed node has
+     * nothing to render, a group wears no marker of its own, and an error
+     * about the rest of the config — a column the definition dropped, a page
+     * size it no longer admits — was never this editor's to mark. A surface
+     * shows these in the strip above the editor.
+     *
+     * The pair of `blocked`: together they account for every error that stops
+     * the view, one on the pills and one in the strip, with neither said twice.
+     */
+    unmarked: Issue[];
+    setMode(mode: FilterMode): void;
+    clear(): void;
+    /** Applies the draft, which is what runs the query. */
+    submit(): void;
+    /**
+     * Puts the draft conditions back to the ones last applied, and runs
+     * nothing.
+     *
+     * It is an `edit` with no `apply` on purpose: the result on screen was
+     * already fetched under `state.applied.filter`, so restoring that tree
+     * leaves the query and the rows exactly as they are — re-running would
+     * spend a request to arrive at the answer already there. `pending` falls
+     * to false because the two trees agree again, which is the whole point.
+     *
+     * It is not `commands.revert`, which is about the *saved* config: revert
+     * throws away every unsaved edit of the view and makes the stored one the
+     * draft again. This throws away the unapplied conditions alone and touches
+     * neither the saved config nor the columns, sort or paging.
+     */
+    discard(): void;
+    /** Auto-refresh pauses between these two, so typing is never interrupted. */
+    focus(): void;
+    blur(): void;
+}
+/**
+ * Editing of the draft filter tree, addressed by path.
+ *
+ * It holds no state of its own: every action is an `edit` on the runtime, so
+ * two editors over one view agree, and undo is just not submitting. Over a
+ * dashboard there is no tree to edit (D27): the tree is empty, and every
+ * edit of it does nothing.
+ */
+export declare function useFilterEditor(runtime: ViewRuntime | null): FilterEditorController;
+/**
+ * The part of the controller that edits a tree, and nothing about the view
+ * around it.
+ *
+ * `useFilterEditor` is one implementation, bound to a runtime's draft. A
+ * condition that holds a condition — an element match — is another, bound to
+ * a leaf's value, and the two render through the same components because the
+ * thing being edited is the same thing.
+ */
+export interface FilterTreeController {
+    tree: FilterTree;
+    fields: readonly FieldDefinition[];
+    /** The picker groups the definition declares; none for a dashboard's or an element's fields. */
+    fieldGroups: readonly FieldGroupDefinition[];
+    /** The registry admission used, so a nested editor admits by the same one. */
+    kinds: FieldKindRegistry | undefined;
+    issues: Issue[];
+    addLeaf(field: string, parent?: FilterPath): void;
+    /**
+     * Fields a new condition may be added on under `parent`: every field not
+     * already a condition of that group, since a group holds one condition per
+     * field, and of a kind the registry knows, since a condition cannot be made
+     * on one it does not. The picker lists these rather than `fields`.
+     */
+    fieldsFor(parent?: FilterPath): FieldDefinition[];
+    /**
+     * Sets a condition back to "nothing said yet": its value becomes the
+     * kind's empty value for its operator, so the row stays and the condition
+     * leaves the query. On a group, every condition in it. This is what the
+     * applied summary's remove does — it takes a condition out of force without
+     * taking the field away from the editor.
+     */
+    clearValue(path: FilterPath): void;
+    updateLeaf(path: FilterPath, patch: Partial<FilterLeaf>): void;
+    addGroup(op: FilterGroupOperator, parent?: FilterPath): void;
+    updateGroup(path: FilterPath, op: FilterGroupOperator): void;
+    /**
+     * Flips the condition at `path` between itself and "not itself": a leaf is
+     * wrapped in a `nor` group of its own, a leaf already alone in one is
+     * unwrapped. `path` is the leaf's, as the pill holds it. This is simple
+     * mode's switch (D18-7); advanced mode has the group operator for it.
+     */
+    negate(path: FilterPath): void;
+    /**
+     * Takes out whatever `path` names — and the negation around it, when the
+     * path is that of a leaf alone in one. A caller holds a condition by its
+     * leaf's path whether or not it is negated, so this is the only removal
+     * either kind of pill needs (`removeConditionAt`).
+     */
+    remove(path: FilterPath): void;
+    operatorsFor(field: string): FilterOperatorName[];
+    editorFor(path: FilterPath): EditorDescriptor | null;
+    /**
+     * The remote candidates behind a `remote` editor's key, from the runtime
+     * this editor is bound to; `null` where the host wired none, and absent
+     * on a controller with no runtime at all. A nested editor over a leaf's
+     * value shares its parent's.
+     */
+    optionSource?(remote: string): OptionSource | null;
+    /**
+     * The values the condition at `path` may be picked from, counted from the
+     * data (`ViewRuntime.valueCandidates`), or `null` where none are offered:
+     * its field is not one the data can list, or its operator takes something
+     * other than one of the field's own values — a substring, a range, no
+     * value at all. Absent on a controller whose fields are not the view's
+     * own: a nested predicate's are an element's, which the view's data does
+     * not count.
+     */
+    valueCandidates?(path: FilterPath): ValueCandidateSource | null;
+}
+export interface TreeControllerInput {
+    tree: FilterTree;
+    fields: readonly FieldDefinition[];
+    fieldGroups?: readonly FieldGroupDefinition[];
+    kinds: FieldKindRegistry | undefined;
+    /** Issues already rebased onto this tree. */
+    issues: Issue[];
+    /**
+     * The tree an action reads at the moment it runs, where that is not the
+     * `tree` it was built over: an editor bound to a runtime reads the draft
+     * the runtime holds at the click, so two edits in one event compose —
+     * adding a group and then a leaf inside it works. Left out, actions read
+     * `tree`, which is what a nested editor over a leaf's value wants.
+     */
+    current?(): FilterTree;
+    onChange(tree: FilterTree): void;
+    /** See `FilterTreeController.optionSource`. */
+    optionSource?(remote: string): OptionSource | null;
+    /** The candidate source of a field by name; see `FilterTreeController.valueCandidates`. */
+    valueCandidates?(field: string): ValueCandidateSource | null;
+    /**
+     * Whether a condition here may be a time since another moment (N3's
+     * `EXPRESSION`). Left out, it may; one entry of an element is asked
+     * nothing of the kind — Wow keeps it out of `ELEMENT_MATCH` — so the
+     * predicate block says `false`.
+     */
+    durations?: boolean;
+}
+/**
+ * A controller over any tree. It holds no state: every action produces the
+ * next tree and hands it to `onChange`, which is what lets a nested one write
+ * straight back into the leaf that carries it.
+ */
+export declare function treeController(input: TreeControllerInput): FilterTreeController;
+//# sourceMappingURL=useFilterEditor.d.ts.map

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

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

package/dist/react/usePanelFollowUps.d.ts

@@ -0,0 +1,31 @@
+import { DataViewConfig } from '../model/index.js';
+import { HandOver, ViewNavigation, ViewRuntime } from '../runtime/index.js';
+import { WorkbenchController } from './useWorkbench.js';
+/**
+ * The part of a workbench the follow-up menu drives (`useAnalysisResult`):
+ * what a dashboard panel hands it in place of one.
+ */
+export type FollowUpHost = Pick<WorkbenchController, 'state' | 'canDrill' | 'drill' | 'follow'>;
+/**
+ * The follow-ups on a dashboard panel's groups (D22 H): the analysis view's
+ * own menu — the records behind a group, the question split by another
+ * dimension, the question of the group alone — each opened through the
+ * host's route (`navigate`) as a view nobody saved, rather than beside the
+ * panel: a board has no "beside". Without a route there is nothing to open,
+ * and the menu is not offered at all.
+ *
+ * What opens takes what the panel's view takes off the page (`handOver`,
+ * read at the press, D26 Q30): what the page holds as its scope, which
+ * nobody in the workbench takes off; the reader's values as conditions of
+ * its own beside the view's and the group's, which they can — so the
+ * workbench shows what the panel showed. And the board it came from, for
+ * the way back (Q33).
+ */
+export declare function usePanelFollowUps(runtime: ViewRuntime<DataViewConfig> | null, navigate: ((to: ViewNavigation) => void) | undefined, handOver: () => HandOver | null): FollowUpHost;
+/**
+ * An analysis the board owns, opened in the workbench (「在工作台中打开」): it
+ * has no saved view to open, so it goes as a view nobody saved, taking what
+ * its panel takes off the board (`handOver`).
+ */
+export declare function ownedNavigation(runtime: ViewRuntime<DataViewConfig>, title: string, handOver: HandOver | null): ViewNavigation | null;
+//# sourceMappingURL=usePanelFollowUps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePanelFollowUps.d.ts","sourceRoot":"","sources":["../../src/react/usePanelFollowUps.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,cAAc,EAIf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAGV,QAAQ,EACR,cAAc,EACd,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,mBAAmB,EACnB,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAC1C,CAAC;AAKF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,EAC3C,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,SAAS,EACpD,QAAQ,EAAE,MAAM,QAAQ,GAAG,IAAI,GAC9B,YAAY,CAyDd;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,cAAc,GAAG,IAAI,CAIvB"}

package/dist/react/useRecordActions.d.ts

@@ -0,0 +1,126 @@
+import { FieldOption, RecordKey } from '../model/index.js';
+import { RecordRow } from '../record/index.js';
+import { ActionConfirm, ActionInput, ActionPlace, RecordAction, RecordActions, RefusalGroup } from '../runtime/actions.js';
+import { ActionFailureContext, ActionRunner, BulkRun, BulkSelection } from './actionRunner.js';
+/** What of a record table the actions read and act on. */
+export interface RecordActionTable {
+    rows: readonly RecordRow[];
+    selection: readonly RecordKey[];
+    selectedRows: readonly RecordRow[];
+    select(keys: readonly RecordKey[]): void;
+    refresh(): void;
+}
+export interface RecordActionsOptions {
+    /** The declared actions (`actions()`); none leaves only the runner. */
+    actions?: RecordActions;
+    table: RecordActionTable;
+    /**
+     * What reading the view again after a command means here: the table's
+     * own by default; a board's record panel reads the whole board again.
+     */
+    refresh?(): void;
+    /**
+     * Records shown beyond the table's page — the record detail's, opened by
+     * a link — whose actions are drawn and whose availability can change on
+     * its own as well.
+     */
+    also?: readonly RecordRow[];
+    /** How many records are in flight at once; a handful by default. */
+    concurrency?: number;
+    /**
+     * Told of what a command threw on a record, as it was thrown — not of an
+     * action's own refusal, nor of an abort (`ActionRunnerOptions.onError`).
+     */
+    onError?(error: unknown, context: ActionFailureContext): void;
+}
+/** One action as a record's row, menu or detail draws it. */
+export interface RowActionView {
+    action: RecordAction;
+    available: boolean;
+    /** Why not, as the host wrote it (a key stays a key); `null` when able. */
+    reason: string | null;
+    /**
+     * A choice's options, each with whether this record takes it — the value
+     * it already holds is refused by the host's rule and not offered again.
+     * `null` for an action that is not a choice.
+     */
+    choices: readonly {
+        option: FieldOption;
+        available: boolean;
+    }[] | null;
+}
+/** One action as the selection's bar draws it. */
+export interface BulkActionView {
+    action: RecordAction;
+    /** How many records are picked: what the primary action's button counts. */
+    count: number;
+    /**
+     * How many of them take it now, before any input — 「催发货 2/4 条」; the
+     * dialog says which do not and why.
+     */
+    able: number;
+    /**
+     * Why none of them takes it, the commonest reason as the host wrote it;
+     * `null` while one does.
+     */
+    reason: string | null;
+    /** A choice's options, or `null`. */
+    choices: readonly FieldOption[] | null;
+}
+/** An action pressed and waiting on the reader: its question, its form. */
+export interface PendingAction {
+    action: RecordAction;
+    place: ActionPlace;
+    /** What it runs over: the record, or the selection. */
+    keys: readonly RecordKey[];
+    input: ActionInput;
+    /** The declared question for this input, or `null` for the engine's own. */
+    confirm: ActionConfirm | null;
+    /** Whether it has a form to fill (a choice is filled by its option). */
+    form: boolean;
+    /** The records that take it now. */
+    able: readonly RecordKey[];
+    /** The ones that will not be sent, by reason, the commonest first. */
+    refused: readonly RefusalGroup[];
+    /** Required fields still blank, by name. */
+    missing: readonly string[];
+    /** The option a choice picked, as the words `{value}` is said with. */
+    value: string | null;
+}
+/**
+ * The declared actions of one record surface (host-integration.md 5): what
+ * each record and the selection are offered, the press that asks first or
+ * runs, the question or form waiting on the reader, and the one runner every
+ * command on the surface goes through — a few at a time, its progress, its
+ * stop, its outcome, the refresh after.
+ *
+ * Availability is asked at the engine's clock, which moves on by itself when
+ * a record's rule says it will change (`changesAt`): the host keeps no timer.
+ */
+export interface RecordActionsController extends Pick<ActionRunner, 'running' | 'outcome' | 'stop' | 'dismiss'> {
+    /** The time the rules are asked at now. */
+    now: number;
+    /** A command is running: nothing else starts until it settles. */
+    busy: boolean;
+    /** The actions offered on a record at `row` or `detail`, hidden ones left out. */
+    forRow(row: RecordRow, place: 'row' | 'detail'): readonly RowActionView[];
+    /** The actions offered on the selection, left out where hidden on all of it. */
+    forSelection(): readonly BulkActionView[];
+    /**
+     * Presses an action: on `row`, at `row` or `detail`; on the selection at
+     * `bulk`. With a question or a form it waits (`pending`), otherwise it
+     * runs. A choice's option comes as the input.
+     */
+    start(id: string, place: ActionPlace, row?: RecordRow, input?: ActionInput): void;
+    pending: PendingAction | null;
+    setInput(name: string, value: unknown): void;
+    /** Picks only the records that take it — 「只选能做的」. */
+    onlyAble(): void;
+    /** Runs what is pending; the refused are reported, not sent. */
+    confirm(): void;
+    cancel(): void;
+    /** Runs a host's own command (a slot's) on this surface's runner. */
+    runCommand(selection: BulkSelection, command: BulkRun): void;
+}
+export declare function useRecordActions({ actions, table, refresh, also, concurrency, onError, }: RecordActionsOptions): RecordActionsController;
+//# sourceMappingURL=useRecordActions.d.ts.map

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

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

package/dist/react/useRecordDetail.d.ts

@@ -0,0 +1,76 @@
+import { Issue, RecordData, RecordKey } from '../model/index.js';
+import { DetailSection, RecordRow } from '../record/index.js';
+import { RecordViewRuntime } from '../runtime/index.js';
+/**
+ * Who says which record the detail has open, as `value` and `onChange` say
+ * it on an input.
+ *
+ * Leaving `open` out lets the detail own it: a press on a row opens that
+ * row, the close button closes it. Passing it — a key, or `null` for none —
+ * puts the host in charge: every later value opens what it names, whether or
+ * not that record is on the page, and a press or a close only asks
+ * (`onOpenChange`), so a host that keeps the key in its address (`?id=`)
+ * opens the same record from the link.
+ */
+export interface RecordDetailControl {
+    /**
+     * The record open in the detail, by its row key, or `null` for none. A key
+     * is matched against the page's rows as it is (`===`): hand it over in the
+     * type the rows carry it in.
+     */
+    open?: RecordKey | null;
+    /**
+     * Told whenever the reader opens a record (its key) or closes the detail
+     * (`null`) — in either mode, so a host can follow the detail without owning
+     * it. Not told when `open` itself changes: that is the host's own doing.
+     */
+    onOpenChange?(key: RecordKey | null): void;
+}
+export interface RecordDetailController {
+    /** The record open in the detail, or `null` while none is. */
+    key: RecordKey | null;
+    /**
+     * What the detail shows: the whole record once it has come, and the row
+     * the page already had until then — so the detail opens at once, with what
+     * was on screen, and fills in rather than blinking empty first. `null`
+     * while a record opened by its key alone (a link to one not on the page)
+     * has not been read yet, and after it could not be.
+     */
+    record: RecordData | null;
+    /** Whether `record` is the whole record rather than the page's row. */
+    complete: boolean;
+    /** Reading the whole record. */
+    loading: boolean;
+    /**
+     * Why the whole record could not be read, in the source's words:
+     * `record.detail.forbidden` when the source refused the reader
+     * (HTTP 401 or 403), `record.detail.failed` otherwise.
+     */
+    error: Issue | null;
+    /** The record is no longer there: deleted, or out of the injected scope. */
+    missing: boolean;
+    /** How the detail is laid out: the definition's groups (`detailSections`). */
+    sections: readonly DetailSection[];
+    open(row: RecordRow): void;
+    close(): void;
+    /** Reads the whole record again — the way out of a failed read. */
+    reload(): void;
+}
+/**
+ * One record's detail (production review A2): what an operator opens to
+ * read a failure whole — the message a column clipped, the stack trace no
+ * column holds.
+ *
+ * The record is read on its own (`runtime.fetchRecord`), and read again each
+ * time the view's result lands: a command run from the list or from the
+ * detail refreshes the view, and the detail then says what the record is
+ * now, not what it was when it was opened. A read that a newer one or a
+ * close overtakes is dropped.
+ *
+ * A record may be opened by its key alone (`control.open`, G2): a link to
+ * one the page does not hold. It then starts from the page's row when the
+ * page has it, and from nothing — `loading`, then the record, `missing`, or
+ * `error` — when it does not.
+ */
+export declare function useRecordDetail(runtime: RecordViewRuntime | null, control?: RecordDetailControl): RecordDetailController;
+//# sourceMappingURL=useRecordDetail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useRecordDetail.d.ts","sourceRoot":"","sources":["../../src/react/useRecordDetail.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAK7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,mEAAmE;IACnE,MAAM,IAAI,IAAI,CAAC;CAChB;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,IAAI,EACjC,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,CAmFxB"}

package/dist/react/useRecordExport.d.ts

@@ -0,0 +1,104 @@
+import { Issue, RecordData } from '../model/index.js';
+import { RecordViewRuntime } from '../runtime/index.js';
+import { RecordTableController } from './useRecordTable.js';
+/**
+ * The two readings of "export": what is picked, and what the conditions
+ * match.
+ *
+ * "This page" used to be a third, and it was an artefact of paging rather
+ * than an intent (D14): on a result that fits one page it is "all" said
+ * twice, and on one that does not it is a slice cut by the sort and the page
+ * size that nobody asked for. A sample is the header's select-all followed
+ * by "selected".
+ */
+export type RecordExportScope = 'selected' | 'all';
+export interface RecordExportScopes {
+    /**
+     * Rows picked, and **absent** while nothing is picked: the dialog offers
+     * what the view can actually do (D4), and "export the 0 selected rows" is
+     * a choice that does nothing.
+     */
+    selected?: number;
+    /**
+     * Rows the applied conditions match, or `null` when nobody can say: a
+     * cursor source reports no total, and neither does a paged one that
+     * withholds it. The export still runs; only the count is unknown.
+     */
+    all: number | null;
+}
+export interface RecordExportProgress {
+    scope: RecordExportScope;
+    /** Rows in hand so far. */
+    fetched: number;
+    /** How many there are in all, where the source says. */
+    total?: number;
+}
+/** What one finished export produced, until the next run or `reset()`. */
+export interface RecordExportOutcome {
+    scope: RecordExportScope;
+    /** Rows the file holds. */
+    rows: number;
+    /** The ceiling stopped the fetch short of everything that matched. */
+    capped: boolean;
+    /** How many rows matched in all, where the source reports a total. */
+    total?: number;
+}
+export interface RecordExportController {
+    scopes: RecordExportScopes;
+    /** The scope being exported, or `null` while nothing runs. */
+    running: RecordExportScope | null;
+    progress: RecordExportProgress | null;
+    /** The export that finished, so the window can report what it produced. */
+    outcome: RecordExportOutcome | null;
+    /**
+     * The failure of the last export, as one Issue. Nothing while an export is
+     * running or has gone well — a file cut short by the ceiling is not a
+     * failure, and says so through `outcome.capped`.
+     */
+    error: Issue | null;
+    /**
+     * Starts one export; a no-op while another is running.
+     *
+     * `fileName` is what the window that starts the run has already promised
+     * the file will be called. It is carried to `deliver` untouched rather
+     * than worked out again when the rows are in hand: the name holds a day,
+     * and the export may outlive one (D14).
+     */
+    run(scope: RecordExportScope, fileName: string): void;
+    /** Stops the run in flight. */
+    cancel(): void;
+    /** Forgets the last outcome or failure; it does not stop a run. */
+    reset(): void;
+}
+export interface RecordExportOptions {
+    /**
+     * What becomes of the rows once they are in hand.
+     *
+     * The hook gathers; `/ui` serialises and hands the file over, because how a
+     * value reads and how a browser saves a file are both its answers. A
+     * failure here is reported exactly like a failed fetch — from the user's
+     * side "the export did not happen" is one outcome, not two.
+     *
+     * `fileName` is the name the run was started under, so the file that is
+     * handed over is the file that was promised.
+     */
+    deliver(rows: readonly RecordData[], scope: RecordExportScope, fileName: string): void | Promise<void>;
+}
+/**
+ * Exporting the result: the rows that are picked, or everything the applied
+ * conditions match.
+ *
+ * The picked rows are already in hand — they are the result on screen — so
+ * they are handed straight over. "All" is a query of its own: `exportRows`
+ * pages the source behind the view without touching it, which is why a long
+ * export leaves the rows, the paging and the selection exactly as they were.
+ *
+ * It asks nothing. The one question there was — "this is more than the cap,
+ * still want it?" — is now part of the window that starts the export (D14):
+ * the count and the ceiling are on screen before the button is pressed, so
+ * pressing it **is** the consent, and a hook that stopped to ask again would
+ * be asking twice. Where no total is known there was never anything to ask,
+ * and `outcome.capped` says afterwards that the ceiling cut the file short.
+ */
+export declare function useRecordExport(runtime: RecordViewRuntime | null, table: RecordTableController, options: RecordExportOptions): RecordExportController;
+//# sourceMappingURL=useRecordExport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useRecordExport.d.ts","sourceRoot":"","sources":["../../src/react/useRecordExport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,KAAK,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,iBAAiB,CAAC;IACzB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8DAA8D;IAC9D,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC;;;;OAIG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB;;;;;;;OAOG;IACH,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAAC;IACf,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,OAAO,CACL,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,MAAM,GACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,IAAI,EACjC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,mBAAmB,GAC3B,sBAAsB,CA4JxB"}