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

package/dist/react/useRecordTable.d.ts

@@ -0,0 +1,309 @@
+import { FieldGroupDefinition, Issue, RecordCardSpec, RecordKey, RecordLayout, RecordSort, SortDirection, SummaryFunction } from '../model/index.js';
+import { RecordCardView, RecordColumnView, RecordPaging, RecordRow, SummaryRow } from '../record/index.js';
+import { QueryStatus, RecordViewRuntime } from '../runtime/index.js';
+/** How {@link RecordTableController.toggle} treats the rows around one. */
+export interface ToggleSelectionOptions {
+    /**
+     * Extend from the anchor — the row the last plain toggle landed on — to
+     * this one, inclusive and in result order, the way Shift+click does in a
+     * file manager: the range goes the way this row goes. With no anchor
+     * standing among the rows on screen it is a plain toggle, and sets one.
+     */
+    range?: boolean;
+}
+/** How {@link RecordTableController.toggleSort} treats the other columns. */
+export interface ToggleSortOptions {
+    /** Make the cycled field the whole sort rather than joining it. */
+    exclusive?: boolean;
+}
+export interface RecordTableController {
+    /** Columns of the result on screen, which follow the executed config. */
+    columns: RecordColumnView[];
+    /**
+     * The card layout of the same result, projected by the kernel beside the
+     * columns; both halves are saved side by side.
+     */
+    card: RecordCardView;
+    /**
+     * The field that says which record a row is — the definition's row key,
+     * handed on so a control that lists the columns can hold it in place
+     * without reading the definition itself. Absent before a runtime exists.
+     */
+    rowKey?: string;
+    /** The picker groups the definition declares, for the column settings. */
+    fieldGroups: readonly FieldGroupDefinition[];
+    /**
+     * The card half of the draft, as the settings edit it — the draft rather
+     * than the result's config, for the reason `columnFields` reads the
+     * draft: a control shows what the user has said, and the result follows.
+     */
+    cardSpec: RecordCardSpec;
+    /**
+     * Changes the card layout — which field titles it, which make its body,
+     * where its image comes from, how many stand in a row — and applies at
+     * once, as `setColumns` does: the cards follow the config that ran. Like
+     * every write here, only while nothing else waits (see `toggleSort`).
+     */
+    setCard(patch: Partial<RecordCardSpec>): void;
+    rows: RecordRow[];
+    /**
+     * Where the result stands: the page and size that ran, the pages the
+     * pager can reach and whether a window cuts them short of the total
+     * (`record/paging.ts`). The pager reads these and does no arithmetic of
+     * its own.
+     */
+    paging: RecordPaging | null;
+    summaries: SummaryRow | null;
+    status: QueryStatus;
+    error: Issue | null;
+    /** True while a query is in flight and rows are still the previous ones. */
+    loading: boolean;
+    /**
+     * The query failed, and the rows still on screen were fetched under other
+     * conditions than the ones it asked (`ViewQueryState.conditionsChanged`):
+     * the rows of the old conditions, not merely older rows. Left out — a
+     * controller a host builds itself — it is `false`.
+     */
+    conditionsChanged?: boolean;
+    /**
+     * Whether a result ever came back for this view — the last one that did,
+     * however old it is by now.
+     *
+     * It is not `rows.length > 0` and not `status === 'success'`: a failed
+     * refresh keeps the rows it could not replace and turns the status to
+     * `error`, and a result that matched nothing has no rows. What it answers
+     * is the one question a table cannot answer from rows alone — is there a
+     * result underneath this status, or is the frame empty because nothing has
+     * ever been executed here.
+     */
+    hasResult: boolean;
+    /**
+     * The source counts only what a condition narrows and the view has none
+     * (`record.filter.required`, capabilities.md Q3): nothing is sent, and
+     * the table says to add a condition rather than showing nothing.
+     */
+    filterRequired?: boolean;
+    /**
+     * The draft's sort: what the sort editor edits, and what the next header
+     * press cycles from.
+     */
+    sort: RecordSort[];
+    /**
+     * The sort the rows on screen were fetched by — the config that ran, not
+     * the draft. The header's arrows and `aria-sort` say this one: while a
+     * sort waits for Apply, a header pointing down over rows that go up would
+     * be lying about them. Empty before anything has run.
+     */
+    ranSort: RecordSort[];
+    sortOf(field: string): SortDirection | null;
+    /**
+     * Ascending, then descending, then off.
+     *
+     * By default the field joins the sort — a new one at the end, an existing
+     * one in its place — so several columns may order the rows. With
+     * `exclusive` the cycled field is the whole sort: what a plain click on a
+     * header means, where Shift is what adds. Both are one `edit` and at most
+     * one `apply`; imitating exclusivity with the additive form would spend
+     * one query per column being cleared.
+     *
+     * **It runs only when nothing else waits.** A press is about the order of
+     * the rows, so it applies at once as a table does — unless the draft holds
+     * another edit waiting for Apply, a range condition above all. Running
+     * then would apply that edit on the user's behalf; the sort joins it
+     * instead, the pending dot shows, and Apply runs the two together
+     * (`pendingBesides`, the rule the analysis header keeps). Every write here
+     * that edits and runs keeps this rule: the page size, the columns, their
+     * order, pinning and width, the summaries, the card and a layout switch
+     * that moves the page size.
+     */
+    toggleSort(field: string, options?: ToggleSortOptions): void;
+    /**
+     * Replaces the whole sort, in priority order — and runs under the same
+     * rule as `toggleSort`: at once when nothing else waits, otherwise with
+     * the edits waiting for Apply.
+     *
+     * `toggleSort` is one column's answer and can only append; an editor that
+     * shows the sort as a list needs to say which field comes first, flip one
+     * of them and drop one of them, and all three are the same write.
+     */
+    setSort(sort: RecordSort[]): void;
+    /**
+     * How many fields this view may sort on at once.
+     *
+     * A cursor is a position in one total order, and Wow bounds how many
+     * fields that order may be built from, so `validateRecord` refuses a
+     * longer sort and `apply` never runs: the rows keep the order they had and
+     * the view sits in an error the user did not ask for. A control that
+     * offers a field therefore has to stop at the ceiling. A paged source has
+     * no such bound, and answers with the number of fields it could sort on.
+     */
+    maxSortFields: number;
+    layout: RecordLayout;
+    /**
+     * The layouts the definition allows, in its order. A switcher offers these
+     * and nothing else — and renders nothing at all below two.
+     */
+    layouts: RecordLayout[];
+    setLayout(layout: RecordLayout): void;
+    /**
+     * Fields of the draft's table layout, in order — the columns switched
+     * off among them, because a hidden column keeps its place in the order
+     * and a control that lists the table's columns has to list it there.
+     */
+    columnFields: string[];
+    /** Whether the draft has this column switched off. */
+    hiddenOf(field: string): boolean;
+    /**
+     * Which columns the table shows, and applies at once — while nothing else
+     * waits for Apply; otherwise it joins what waits (see `toggleSort`).
+     *
+     * A column the config already knows is switched off **in place** —
+     * `hidden: true`, its entry kept — rather than taken out of the list, so
+     * switching it back on puts it back where it was rather than at the end.
+     * Which is also why this says nothing about the order: that is
+     * {@link setColumnOrder}'s, and a column that is not in the list has no
+     * order to give. A named field the config does not know yet joins at the
+     * end, as a column has to start somewhere.
+     *
+     * A column that goes takes its summary with it: a summary belongs to a
+     * column, so one left behind buys an aggregation query with nowhere to
+     * appear. Each column that stays is reused as it was configured, so its
+     * width and pinning survive being switched off and on again.
+     *
+     * The two entries that have nowhere to come back to leave the list
+     * instead: a column the definition no longer offers, and a second entry
+     * for a column already kept. Both are one row in the settings and both
+     * are configs the kernel refuses (`record.field.unknown`,
+     * `record.column.duplicate`), so switching them off is the repair it has
+     * always been — hiding one would leave the query and the save blocked by
+     * the control that had just run.
+     */
+    setColumns(fields: string[]): void;
+    /**
+     * Puts the draft's columns in this order and applies at once, under the
+     * rule `toggleSort` keeps.
+     *
+     * A name that is not a column is ignored and a column the caller leaves
+     * unnamed keeps its place at the end, so a control that knows about part
+     * of the table — one area of the column settings — cannot drop the rest
+     * of it by saying nothing about it.
+     *
+     * The columns are all of them, the switched-off ones included: a hidden
+     * column has a place in the order, which is what makes switching it back
+     * on put it back where it was, so a caller that means to order the whole
+     * table names it along with the rest.
+     */
+    setColumnOrder(fields: string[]): void;
+    /** Whether the draft holds this column against the table's left edge. */
+    pinnedOf(field: string): boolean;
+    /**
+     * Holds a column against the left edge, or lets it go. Applies at once,
+     * under the rule `toggleSort` keeps.
+     *
+     * There is one end to pin to (D19): the right edge is the host's action
+     * column, which is a render slot rather than anything a config names.
+     */
+    setPinned(field: string, pinned: boolean): void;
+    /**
+     * Sets one column's width in pixels, or `null` to let it size itself
+     * again. Applies at once, like the other column commands, and under the
+     * same rule.
+     *
+     * The number is taken as given: how narrow a column may be dragged is a
+     * question about a grab handle rather than about a config, so the table's
+     * own floor lives with the handle. What the kernel refuses is a width that
+     * is not a positive finite number of pixels.
+     */
+    setColumnWidth(field: string, width: number | null): void;
+    /** The function the draft summarises a column with, if any. */
+    summaryOf(field: string): SummaryFunction | null;
+    /**
+     * Every field the draft's summaries name, in the order they name them and
+     * without a repeat.
+     *
+     * It is not the column list: a config may summarise a field that is not a
+     * column and that the definition no longer declares, and the settings can
+     * only offer the way out of such a summary if they are told it is there.
+     */
+    summaryFields: string[];
+    /**
+     * Replaces whatever a column summarised with one function, or with none.
+     *
+     * A config may carry several functions for one field and the table shows
+     * all of them; this writes one, because a control that offers a column one
+     * summary is the shape the settings have. Setting one therefore drops the
+     * others on that column, and `null` leaves it without a summary. Applies
+     * at once under the rule `toggleSort` keeps.
+     */
+    setSummary(field: string, fn: SummaryFunction | null): void;
+    pageSize: number;
+    /**
+     * Page sizes worth offering: the layout's ladder — `limits.pageSizes` for
+     * a table, `limits.cardPageSizes` for cards, which are whole rows at every
+     * width — cut to what the runtime limits admit and with the current size
+     * folded in. A size above
+     * `maxPageSize` is refused by `validateRecord`, so offering it would be
+     * offering a way to break the view — and the saved size has to be in the
+     * list whatever it is, or a select shows nothing at all.
+     */
+    pageSizes: number[];
+    /** A new size is a new query: runs under the rule `toggleSort` keeps. */
+    setPageSize(size: number): void;
+    /**
+     * The admitted page size nearest the draft's, where the draft's is one
+     * the runtime refuses (`record.pageSize.too-large`, `not-positive`), and
+     * `null` otherwise: the one-press way out of a stored size the limits no
+     * longer admit. Nothing else offers it — a view that will not run has no
+     * result and so no pagination to pick a size in (second review R1-P1-3).
+     */
+    pageSizeFix: number | null;
+    selection: RecordKey[];
+    /**
+     * The selected rows of the current result, in result order. A bulk action
+     * needs the rows and not only their keys — it names what it is about to
+     * act on — and the selection is keys alone.
+     */
+    selectedRows: RecordRow[];
+    isSelected(key: RecordKey): boolean;
+    /**
+     * Selects or unselects one row, or a range with `{ range: true }`. A
+     * plain toggle moves the anchor a range extends from; a range does not,
+     * so a second Shift+click re-draws the range from the same row. The
+     * anchor belongs to the rows on screen: another page, or another
+     * question applied, lets it go — a refresh of the same page keeps it.
+     */
+    toggle(key: RecordKey, options?: ToggleSelectionOptions): void;
+    /** Selects every row of the current result, or clears the selection. */
+    toggleAll(): void;
+    clearSelection(): void;
+    /** Picks exactly these rows, in this order. */
+    select(keys: readonly RecordKey[]): void;
+    /**
+     * Paged sources only; a cursor source has no page numbers to jump to. A
+     * page past the last reachable one lands on that one — past the end, the
+     * reader wants the end, and a page beyond the source's window is one the
+     * source refuses.
+     */
+    goTo(index: number): void;
+    /**
+     * Whether there is a page after this one: the next cursor for a cursor
+     * source; for a paged one, the pages it can reach against the page that
+     * ran. A source that reports no total cannot say, so it is taken as
+     * "there may be" — up to its window, where it declares one.
+     */
+    hasNext: boolean;
+    /** No-op at the end, where there is no next page to ask for. */
+    next(): void;
+    previous(): void;
+    refresh(): void;
+}
+/**
+ * A record view as a table renders it, with no vendor types in sight.
+ *
+ * Rows and columns come from the last successful result rather than the draft,
+ * because the kernel projected them from the config that ran. Changing columns
+ * therefore applies immediately, and so does a sort while nothing else waits
+ * (`toggleSort`); changing a filter waits for submit.
+ */
+export declare function useRecordTable(runtime: RecordViewRuntime | null): RecordTableController;
+//# sourceMappingURL=useRecordTable.d.ts.map

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

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

package/dist/react/useReshape.d.ts

@@ -0,0 +1,54 @@
+import { Dropped } from '../analysis/index.js';
+import { AnalysisMetric, AnalysisViewConfig, ChartSpec, ViewConfig } from '../model/index.js';
+import { ViewRuntime } from '../runtime/index.js';
+import { AnalysisFieldOption } from './analysisFields.js';
+import { DropCause, ReshapeProposal } from './analysisEditing.js';
+/**
+ * What the last edit took out of the question besides what it was asked
+ * to — the dimensions and metrics a step of the chain left behind, the
+ * derived metrics that read one removed — and the step it followed (D71).
+ */
+export interface DropNotice extends Dropped {
+    /** The step of the chain it followed; absent after any other edit. */
+    cause?: DropCause;
+    /**
+     * What the dropped ones are named against: the fields and metrics of the
+     * question before the edit, whose scope may no longer hold their fields.
+     */
+    naming: {
+        fields: AnalysisFieldOption[];
+        metrics: AnalysisMetric[];
+    };
+}
+/**
+ * Whether a metric's ✕ may take it out: `last` when it is the only one,
+ * `cascade` when every other metric reads it and would leave with it — the
+ * edit #3777 makes as asked, leaving admission to refuse it.
+ */
+export type MetricRemoval = 'ok' | 'last' | 'cascade';
+export interface ReshapeInput {
+    runtime: ViewRuntime | null;
+    /** The draft on screen: the notice lasts while it is the one an edit made. */
+    draft: ViewConfig | undefined;
+    /** That draft, where it is an analysis. */
+    config: AnalysisViewConfig | undefined;
+    /** Edits the live draft (`useAnalysisEditor`'s `change`). */
+    change(update: (current: AnalysisViewConfig) => Partial<AnalysisViewConfig>): void;
+    /** The chart fitted to a shape (`useAnalysisEditor`'s `fitTo`). */
+    fitTo(chart: ChartSpec, shape: Pick<AnalysisViewConfig, 'groups' | 'metrics' | 'elements'>): ChartSpec;
+}
+/**
+ * The one way the question's shape changes — `reshape` — with what an edit
+ * of it took out beyond what it was asked to kept for the notice that says
+ * so and puts it back (D71), and whether a metric may be removed at all.
+ */
+export declare function useReshape({ runtime, draft, config, change, fitTo, }: ReshapeInput): {
+    reshape: (update: (current: AnalysisViewConfig) => ReshapeProposal | undefined, cause?: DropCause) => void;
+    dropped: DropNotice | null;
+    /** Whether the draft is the one the last undo put back. */
+    undone: boolean;
+    undoDrop: () => void;
+    dismissDrop: () => void;
+    metricRemoval: (index: number) => MetricRemoval;
+};
+//# sourceMappingURL=useReshape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useReshape.d.ts","sourceRoot":"","sources":["../../src/react/useReshape.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,OAAO,EACb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,MAAM,EAAE;QAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,8EAA8E;IAC9E,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9B,2CAA2C;IAC3C,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACvC,6DAA6D;IAC7D,MAAM,CACJ,MAAM,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,CAAC,GACnE,IAAI,CAAC;IACR,mEAAmE;IACnE,KAAK,CACH,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC,GACjE,SAAS,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,MAAM,EACN,MAAM,EACN,KAAK,GACN,EAAE,YAAY;sBA8CD,CAAC,OAAO,EAAE,kBAAkB,KAAK,eAAe,GAAG,SAAS,UAC5D,SAAS;;IAiFnB,2DAA2D;;;;2BAkBjD,MAAM,KAAG,aAAa;EAkBnC"}

package/dist/react/useSaveCommands.d.ts

@@ -0,0 +1,119 @@
+import { Issue, ViewAudience, ViewInstance, ViewScope } from '../model/index.js';
+import { ConflictChoice, ViewEngine, ViewRuntime, WriteState } from '../runtime/index.js';
+import { RecoveredWrite } from './writes.js';
+export type { RecoveredWrite } from './writes.js';
+export interface SaveTargetInput {
+    title: string;
+    /** `system` makes the copy a stored system view; it needs `createSystem`. */
+    scope: ViewScope;
+}
+export interface SaveAbilities {
+    save: boolean;
+    /** True when a copy may be made in at least one scope. */
+    saveAs: boolean;
+    rename: boolean;
+    delete: boolean;
+    /** True when there are edits and a saved baseline to take them back to. */
+    revert: boolean;
+    /**
+     * Which scope a copy may be made in. A dialog that offers a scope the user
+     * cannot create in only lets them press Save to be refused, so it offers
+     * these and defaults to the first of them.
+     */
+    createPersonal: boolean;
+    createShared: boolean;
+    /**
+     * Whether a copy may be made a system view everyone sees: the host grants
+     * `editSystem` (D81), whose silence is a refusal.
+     */
+    createSystem: boolean;
+}
+export interface SaveCommandState {
+    /** A write is in flight; a UI disables its buttons on this alone. */
+    pending: boolean;
+    /** The last refusal or failure, cleared when the next command starts. */
+    error: Issue | null;
+    /** An unresolved outcome: a conflict, a refusal, or an unknown result. */
+    write: WriteState | null;
+    dirty: boolean;
+    /**
+     * Nothing may be written right now: a write is in flight, the draft would
+     * be refused, or the outcome on screen stops a new intent
+     * ({@link blocksNewIntent}). One flag rather than three, because every
+     * button that writes disables on all of them.
+     *
+     * It is deliberately coarse, so a button that has to tell the settled
+     * outcomes apart — a rejection is a new attempt away, a conflict is not —
+     * or that must refuse a *blind* Save while a conflict is on screen, reads
+     * `write` and `hasErrors` themselves rather than this.
+     */
+    blocked: boolean;
+    /**
+     * The draft itself reports something that stops every write. Unlike
+     * `blocked` it says nothing about outcomes, which is what lets a caller
+     * decide for itself which of those it wants to stop on.
+     *
+     * For a dashboard that is an error about the board alone (`stopsSave`): a
+     * panel's own trouble — a view some of its readers cannot open (D22 B), a
+     * binding that no longer holds — is said on the panel and saved with it.
+     */
+    hasErrors: boolean;
+    /**
+     * Who sees the open view as it is saved: `personal` for its author alone,
+     * `shared` for everyone it is shared with (a system view is `shared` too,
+     * and has no save). A save in place over a shared view changes what all
+     * of them see, which is what a UI asks about first; `null` with no view.
+     */
+    audience: ViewAudience | null;
+    /**
+     * The view has never been saved. Its first save is a create, which is why
+     * a UI asks for a title and an audience before it rather than writing the
+     * name the view opened under.
+     */
+    isNew: boolean;
+    /**
+     * When the last write of this view landed, by the engine's clock. A UI
+     * shows a "Saved" moment from it, so it is a timestamp and not a boolean:
+     * the same save twice in a row must read as two distinct moments. It is
+     * cleared when the next write starts, and is `null` until one lands.
+     *
+     * Only a command that saved this view marks a moment. A conflict resolved
+     * by `reload` settles and reloads without writing anything, and a recovered
+     * `rename` or `delete` writes something that is not the config on screen —
+     * both leave this where it was rather than saying "Saved" over edits that
+     * were just discarded, or were never sent at all.
+     */
+    lastSavedAt: number | null;
+}
+export interface SaveCommands {
+    save(): Promise<ViewInstance | null>;
+    saveAs(input: SaveTargetInput): Promise<ViewInstance | null>;
+    rename(title: string): Promise<ViewInstance | null>;
+    delete(): Promise<boolean>;
+    /** Drops the edits and puts the saved config back in force. */
+    revert(): void;
+    /** Replays the pending write and reports what the replay answered. */
+    retry(): Promise<RecoveredWrite>;
+    /**
+     * Gives up on an unsettled outcome. With no argument it is the one the
+     * open view is reporting; a caller that has a `WriteState` in hand passes
+     * it, because a write can outlive the runtime's report of it — the engine
+     * clears a runtime's outcome as it settles whichever write landed last,
+     * and a copy made out of a conflict is a write of its own.
+     */
+    abandon(write?: WriteState): void;
+    /** Resolves a conflict and reports what the choice answered. */
+    resolveConflict(choice: ConflictChoice): Promise<RecoveredWrite>;
+    can: SaveAbilities;
+    state: SaveCommandState;
+}
+/**
+ * The write commands of one open view, with the permissions that decide which
+ * buttons are live.
+ *
+ * Every command resolves rather than rejects: the outcome lands in `state`, so
+ * a click handler needs no try/catch and an unresolved write stays visible
+ * until the user retries, overwrites or abandons it.
+ */
+export declare function useSaveCommands(engine: ViewEngine, runtime: ViewRuntime | null): SaveCommands;
+//# sourceMappingURL=useSaveCommands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSaveCommands.d.ts","sourceRoot":"","sources":["../../src/react/useSaveCommands.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,qBAAqB,CAAC;AAU7B,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;;;;OAUG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACpD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,+DAA+D;IAC/D,MAAM,IAAI,IAAI,CAAC;IACf,sEAAsE;IACtE,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,gEAAgE;IAChE,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,GAAG,EAAE,aAAa,CAAC;IACnB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,GAAG,IAAI,GAC1B,YAAY,CAkQd"}

package/dist/react/useSearchBox.d.ts

@@ -0,0 +1,34 @@
+import { ViewRuntime } from '../runtime/index.js';
+import { DataViewConfig, FieldDefinition } from '../model/index.js';
+/**
+ * A view's search, kept on hand rather than behind the conditions editor.
+ *
+ * Searching an error used to take five steps — open the conditions, add
+ * one, tick the search field, close the list, type — for the one condition
+ * an operator reaches for first. When the definition declares a search
+ * field (`kind: 'search'`), this is its box: the search condition on the
+ * draft's root (`rootSearch`), edited in place (`withRootSearch`), the same
+ * condition the editor shows as a pill and the applied bar reads back.
+ */
+export interface SearchBoxController {
+    /** The definition's search field: its label names the box. */
+    field: FieldDefinition;
+    /** The search in the draft, as typed. */
+    value: string;
+    /** The search in force — what the rows on screen were found by. */
+    applied: string;
+    /**
+     * The definition searches a phrase, and the source matches words only, so
+     * the search is by words (capabilities.md 4.2, `capability.search.as-terms`):
+     * the box says so where a reader looks before typing.
+     */
+    byWords: boolean;
+    /** Edits the draft's search; blank takes the condition away. */
+    set(text: string): void;
+    /** Puts the draft in force — Enter in the box. */
+    submit(): void;
+    /** Takes the search away, and the rows found by it with it. */
+    clear(): void;
+}
+export declare function useSearchBox(runtime: ViewRuntime<DataViewConfig> | null): SearchBoxController | null;
+//# sourceMappingURL=useSearchBox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSearchBox.d.ts","sourceRoot":"","sources":["../../src/react/useSearchBox.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzE;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,EAAE,eAAe,CAAC;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kDAAkD;IAClD,MAAM,IAAI,IAAI,CAAC;IACf,+DAA+D;IAC/D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,GAC1C,mBAAmB,GAAG,IAAI,CA6B5B"}

package/dist/react/useUnavailable.d.ts

@@ -0,0 +1,19 @@
+import { Issue, ViewConfig } from '../model/index.js';
+import { ViewRuntime } from '../runtime/index.js';
+/**
+ * What an open view uses that its source no longer admits, and the one
+ * press that takes it out (capabilities.md Q2, `ViewRuntime.unavailable`).
+ */
+export interface UnavailableController {
+    /** The findings, each at the place in the config it is about. */
+    issues: Issue[];
+    /** 「移除不可用的条件」: see `ViewRuntime.removeUnavailable`. */
+    remove(): void;
+}
+/**
+ * The view's unavailable parts, read again whenever its snapshot changes,
+ * or `null` when there are none — so a surface draws its strip only where
+ * there is something to say.
+ */
+export declare function useUnavailable(runtime: ViewRuntime<ViewConfig> | null): UnavailableController | null;
+//# sourceMappingURL=useUnavailable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useUnavailable.d.ts","sourceRoot":"","sources":["../../src/react/useUnavailable.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,uDAAuD;IACvD,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,IAAI,GACtC,qBAAqB,GAAG,IAAI,CAQ9B"}

package/dist/react/useValueCandidates.d.ts

@@ -0,0 +1,41 @@
+import { ValueCandidate } from '../analysis/index.js';
+import { ValueCandidateSource } from '../runtime/index.js';
+/** How long typing may pause before the values holding it are asked for. */
+export declare const VALUE_CANDIDATE_DEBOUNCE_MS = 250;
+export interface ValueCandidatesController {
+    /**
+     * `idle` until the list is first opened; `loading` while an answer is on
+     * its way, with the last one still in `values`; `error` when it failed,
+     * with the last one kept and `reason` saying why.
+     */
+    status: 'idle' | 'loading' | 'success' | 'error';
+    /**
+     * The text `values` answer. While it differs from what is typed now, the
+     * answer to the new text is still on its way, and a control narrows what
+     * it holds in the meantime rather than showing a list the text has left.
+     */
+    query: string;
+    values: readonly ValueCandidate[];
+    /** See `ValueCandidates.complete`; false until an answer says otherwise. */
+    complete: boolean;
+    /** What the source said went wrong, in its own words (`sourceReason`). */
+    reason: string | null;
+    /** Asks the same question again after a failure. */
+    retry(): void;
+}
+/**
+ * A condition's values offered from the data: the list of one
+ * `ValueCandidateSource`, asked for while `active`.
+ *
+ * Nothing is asked until the list opens, because a panel holding a dozen
+ * conditions must not cost a dozen aggregations to draw. The unnarrowed list
+ * is asked for at once; a typed fragment only once typing has paused, and
+ * every change of either aborts the request before it — as does closing the
+ * list, which is what `active` going false means. The runtime keeps what
+ * came back for the life of the view, so reopening the list asks nothing.
+ *
+ * The answer is kept per source: another field is another list, and what
+ * the last one said is not shown under it for a moment.
+ */
+export declare function useValueCandidates(source: ValueCandidateSource | null | undefined, query: string, active: boolean): ValueCandidatesController;
+//# sourceMappingURL=useValueCandidates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useValueCandidates.d.ts","sourceRoot":"","sources":["../../src/react/useValueCandidates.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAAC;CACf;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,EAC/C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,GACd,yBAAyB,CAmD3B"}