@pythia-software/query-table-react 0.9.5 → 0.9.7

package/README.md

@@ -85,6 +85,72 @@ Update only when `api.saved.canUpdate` is true. Optional last/default storage re
 failures fall back to table defaults; explicit broken URL links still block
 execution. A single empty `?q=` is treated as an absent query.
 
+### Host query state
+
+A host that adds its own clauses to the builder (for example a keyword
+condition rendered through the `whereRow` slot) can register their state so
+the native Save, Update, Saved, Default, Share, Reset and Undo/Redo controls
+treat it and the table query as one definition:
+
+```ts
+const api = useQueryTable({
+  schema, transport, syncUrl: true,
+  hostQuery: {
+    ownedParameters: ["record_tool_calls"],          // mirrored in the URL
+    defaults: { version: 1, params: {} },             // legacy saves and Reset
+    normalize: normalizeKeywordState,                 // validate, migrate; throw to reject
+  },
+});
+api.definition;                                       // { query, hostState }
+api.setDefinition(previous => ({ query: { ...previous.query, offset: 0 }, hostState: next }));
+```
+
+`hostState` is `{ version, params: Record<string, string[]> }`. It rides in
+`QueryState.hostState`, so history, saves, `encodeQuery` links and durable
+`@…` snapshots carry it with the query, within the existing size budgets.
+Every request the table sends carries the `hostState` it runs with
+(`ServerQuery`, `ServerQueryV2`, `QueryRequestV3`, `MetricQuery`,
+`AggregationRequest` and distinct-value requests), so the host's transport
+never sees one definition's table query with another's host state; the Go
+request types accept and expose it without interpreting it.
+
+- One `setDefinition` is one history entry and one execution. Edits through
+  `setQuery` keep the current host state unless they set one.
+- A save without host state, including every existing save, restores the
+  host `defaults`. Saved items compare as the definitions they load.
+- `normalize` rejecting a state, or unreadable host state, fails the whole
+  restore or load: the live definition and URL stay as they were, and
+  `saved.load` throws. A table without `hostQuery` rejects a save that carries
+  host state rather than drop it.
+- URL writes replace exactly `ownedParameters` and keep other parameters. A
+  table-only link restores host state from those parameters, and a URL with
+  only those parameters opens the default table query with that host state
+  (an explicit link: a rejected state is a restoration error).
+- Grouping, HAVING and column edits keep the host state; it stays on the
+  grouped query, and leaving grouping or following a Records drill-down
+  carries it back to the source query.
+- Storage must set `storesHostState: true` (the built-in adapters do) to save
+  or persist last-used definitions; otherwise Save reports that it cannot,
+  instead of storing a table-only query.
+
+### Last-used query and execution receipts
+
+By default the last-used query is saved 400 ms after every change, even if it
+never loads. `persistLast: "succeeded"` saves it only once rows and every
+metric of that exact query have loaded, so a bare reload never restores a
+query that failed, timed out or was cancelled; the failed query stays on
+screen to retry or reset. Explicit links, named saves and the default saved
+query are separate choices and are unaffected.
+
+`api.execution` reports the current query's execution apart from
+`api.restoration`: the exact `query`, an execution `key` and increasing
+`generation`, an overall `status` (`running`, `succeeded`, `failed`) and
+separate `rows` and `metrics` statuses with the `error`. An empty result,
+including a page past the end, is a success; a metric that fails while rows
+load is not. A slower earlier execution never updates a later receipt, and
+the receipt is `null` while restoring or inactive. Hosts can use it to build
+their own persistence, retry or reset policies.
+
 Item-detail property views hydrate independently, but synchronize into the
 collection query only after URL/saved-query restoration settles. Detail layouts
 encoded in the restored query take precedence over stored property views.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FieldSchema, WhereClause, QueryState, GroupedRow, GroupingModel, GroupingView, SummaryOp, RepresentativeRow, SummaryColumn, SelectColumn, PropertyViewState, SavedPropertyView, PropertyViewStorage, QueryLink, QuerySnapshot, ItemPropertyMode, ItemPageOptions, ItemDetailMode, ItemDetailsState, RelationshipAdapter, RowId, FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedExecution, ComputedColumnStore, QueryLinkOptions, ObjectReference, ResolvedObjectReference } from '@pythia-software/query-table-core';
+import { FieldSchema, WhereClause, QueryState, GroupedRow, GroupingModel, GroupingView, GroupKey, SummaryOp, RepresentativeRow, SummaryColumn, SelectColumn, PropertyViewState, SavedPropertyView, PropertyViewStorage, QueryLink, QuerySnapshot, ItemPropertyMode, ItemPageOptions, ItemDetailMode, ItemDetailsState, RelationshipAdapter, RowId, FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, HostQueryState, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedExecution, ComputedColumnStore, QueryLinkOptions, ObjectReference, ResolvedObjectReference } from '@pythia-software/query-table-core';
 
 /** Filter controls for either the result query or grouping's source query. */
 type QueryFilterApi<Row> = Pick<QueryTableApi<Row>, "query" | "setQuery" | "loading" | "addFilter" | "updateFilter" | "removeFilter" | "clearFilters" | "updatePredicate" | "removePredicate" | "negatePredicate" | "reorderFilters" | "mergeFilters" | "filterValues" | "fieldStats">;
@@ -40,7 +40,9 @@ interface GroupingApi<Row> {
     inputs: Row[];
     notice: string;
     setNotice: (notice: string) => void;
-    changeKeys: (keys: string[]) => void;
+    /** Field names, or calendar keys (`{ field, interval, timeZone }`) for
+     * datetime fields. */
+    changeKeys: (keys: GroupKey[]) => void;
     addSummary: (op: SummaryOp, field?: string) => void;
     changeSummary: (id: string, op: SummaryOp) => void;
     changeRepresentative: (rule: RepresentativeRow | null) => void;
@@ -114,6 +116,8 @@ interface ItemDetailsOptions<Row> {
     loadRow?: (id: RowId, signal: AbortSignal) => Promise<ItemDetailRecord<Row> | null>;
 }
 interface ItemDetailsApi<Row> {
+    /** "group" details describe grouped result rows, identified by their group identity. */
+    subject?: "item" | "group";
     links?: QueryLinksApi;
     schema: FieldSchema<Row>;
     /** Collection catalogue used to resolve Page template fields. */
@@ -242,7 +246,8 @@ interface SavedQueriesApi {
     canUpdate: boolean;
     /** Replace a saved query with the current state, retaining its id and default. */
     update: (id: string) => Promise<SavedQuery>;
-    /** Load a saved query into the live controller. */
+    /** Load a saved query into the live controller. Throws, changing nothing,
+     * when the table cannot accept it (for example unreadable host state). */
     load: (id: string) => void;
     /** Mark a saved query as the default view. No-op when storage lacks support. */
     setDefault: (id: string) => Promise<void>;
@@ -282,6 +287,16 @@ interface UseQueryTableOptions<Row> {
      * Pass localStorageAdapter() explicitly only when filter values are safe to
      * retain as cleartext JSON on the device. */
     storage?: StorageAdapter;
+    /** When `storage.saveLast` records the last-used query: "always" (default)
+     * 400 ms after every change, or "succeeded" once rows and every metric of
+     * that exact query have loaded. A failure, timeout or cancellation keeps the
+     * previous last-used query; explicit links, named saves and the default are
+     * separate choices and are never touched by it. */
+    persistLast?: "always" | "succeeded";
+    /** Host-owned query state that travels with the table query as one
+     * definition: saved, restored, shared, reset and undone together. The host
+     * keeps rendering and running its own clauses from `api.definition`. */
+    hostQuery?: HostQueryOptions;
     /** Shared reusable definitions, independent of saved-query storage. */
     computedColumnStore?: ComputedColumnStore;
     /** Authoritative host handshake for versioned server SELECT, sorts, and metrics. */
@@ -365,6 +380,42 @@ interface AggregationsApi {
     /** Invalidation token for page, refresh, schema, and definition changes. */
     contextKey?: string;
 }
+/** Registers host-owned query state with `useQueryTable`. */
+interface HostQueryOptions {
+    /** URL parameters that mirror `hostState.params` when `syncUrl` is on. URL
+     * writes replace exactly these, keeping every other parameter. They may not
+     * include the table's own query parameter. */
+    ownedParameters: readonly string[];
+    /** The state a query without host state takes, including every save made
+     * before the host registered, and the state Reset restores. */
+    defaults: HostQueryState;
+    /** Validate, migrate and canonicalize; throw to reject. A rejected state
+     * rejects the whole restore or edit, leaving the live definition as it was. */
+    normalize?: (state: HostQueryState) => HostQueryState;
+}
+/** The committed table query and host state, as one unit. */
+interface QueryDefinition {
+    query: QueryState;
+    hostState: HostQueryState;
+}
+/** The outcome of executing one exact query; see `QueryTableApi.execution`. */
+interface QueryExecutionReceipt {
+    /** The query whose rows and metrics this receipt describes. */
+    query: QueryState;
+    /** Execution identity: changes with every row- or metric-affecting edit and
+     * refresh, but not with presentation such as widths. */
+    key: string;
+    /** Increases with every new execution identity of this table. */
+    generation: number;
+    /** "succeeded" only when rows and every metric loaded; an empty result,
+     * including a page past the end, is a success. */
+    status: "running" | "succeeded" | "failed";
+    rows: "running" | "succeeded" | "failed";
+    /** "none" when the query has no metrics. A metric error fails the receipt. */
+    metrics: "none" | "running" | "succeeded" | "failed";
+    /** The row or metric error behind a failure. */
+    error: Error | null;
+}
 interface QueryTableApi<Row> {
     /** Dependent source fetches can use ready without parsing display errors. */
     restoration: {
@@ -372,6 +423,16 @@ interface QueryTableApi<Row> {
         ready: boolean;
         error: Error | null;
     };
+    /** Execution of the current query, separate from restoration. Null while
+     * restoring, after a restoration error and while the table is inactive, so
+     * a cancelled or hidden table never publishes a stale receipt. */
+    execution: QueryExecutionReceipt | null;
+    /** With `hostQuery`: the committed definition (`query` without its
+     * `hostState`, and the host state). */
+    definition?: QueryDefinition;
+    /** With `hostQuery`: commit a new definition as one history entry and one
+     * execution. Throws, changing nothing, when `hostQuery.normalize` rejects. */
+    setDefinition?: (next: QueryDefinition | ((previous: QueryDefinition) => QueryDefinition)) => void;
     /** Call after a host pushState/router update, with an absolute URL or a location
      * relative to window.location.href. Supersedes prior resolution;
      * abort or an intervening query edit prevents stale publication. */
@@ -415,7 +476,8 @@ interface QueryTableApi<Row> {
     /** Remove the whole term at `index`. */
     removeFilter: (index: number) => void;
     clearFilters: () => void;
-    /** Replace one predicate inside a term (predIndex 0 for a literal term). */
+    /** Replace one predicate inside a term (predIndex 0 for a literal term). In
+     *  an OR of conjunctions, predIndex counts literals in `predicatesOf` order. */
     updatePredicate: (termIndex: number, predIndex: number, clause: WhereClause) => void;
     /** Remove one predicate; a group of one flattens to a literal, an emptied term drops. */
     removePredicate: (termIndex: number, predIndex: number) => void;
@@ -425,8 +487,8 @@ interface QueryTableApi<Row> {
      *  dragged term removed, so a drag preview's slot maps straight to the result). */
     reorderFilters: (fromIndex: number, toIndex: number) => void;
     /** OR-merge the term at `sourceIndex` into the term at `targetIndex`: the
-     *  target becomes (or stays) an OR group holding both terms' predicates, and
-     *  the source term is removed. This is the drag-onto-another-filter gesture. */
+     *  target becomes (or stays) an OR group holding both terms' branches (a
+     *  conjunction stays one AND branch), and the source term is removed. This is the drag-onto-another-filter gesture. */
     mergeFilters: (sourceIndex: number, targetIndex: number) => void;
     /** Reset the complete query state back to schema defaults. */
     resetAll: () => void;
@@ -486,4 +548,4 @@ declare function useObjectReferences(references: ObjectReference[], adapter?: Re
     error: Error | null;
 };
 
-export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type ComputedColumnsApi, type FormulaWorkerFactory, type GroupingApi, type GroupingSourceApi, type ItemDetailRecord, type ItemDetailsApi, type ItemDetailsOptions, type PropertyViewApi, type QueryFilterApi, type QueryLinksApi, type QueryTableApi, type RequestActivityApi, type RequestActivityEntry, type SavedQueriesApi, type SelectApi, type SelectionApi, type UsePropertyViewOptions, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, useObjectReferences, usePropertyView, useQueryFilters, useQueryTable, useSavedQueries, useSelect, useSelection };
+export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type ComputedColumnsApi, type FormulaWorkerFactory, type GroupingApi, type GroupingSourceApi, type HostQueryOptions, type ItemDetailRecord, type ItemDetailsApi, type ItemDetailsOptions, type PropertyViewApi, type QueryDefinition, type QueryExecutionReceipt, type QueryFilterApi, type QueryLinksApi, type QueryTableApi, type RequestActivityApi, type RequestActivityEntry, type SavedQueriesApi, type SelectApi, type SelectionApi, type UsePropertyViewOptions, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, useObjectReferences, usePropertyView, useQueryFilters, useQueryTable, useSavedQueries, useSelect, useSelection };