@pythia-software/query-table-react 0.6.0 → 0.7.0

package/README.md

@@ -3,6 +3,20 @@
 Headless React hooks for query-table: query state, fetching, URL/storage sync,
 selection, saved queries, aggregations, and column interactions.
 
+`usePropertyView` controls saved read-only presentations per object type;
+`useObjectReferences` batches cancellable relationship lookups. See
+[object property views](../../docs/object-properties.md).
+
+## Grouped rows
+
+`useQueryTable({ schema, clientRows })` enables one row-producing grouping stage
+for complete local datasets. The standard query builder supplies GROUP BY,
+HAVING, aggregate column editing and representative-row ordering. Use
+`api.schema`, `api.visibleFields` and `api.rowId` for the active result shape;
+set `grouping: false` to opt out. Backend transports currently reject grouped
+row queries. See [grouping integration](../../docs/grouping.md) for the query
+shape, source-stage controls, saved state and execution boundaries.
+
 ## Install
 
 ```bash
@@ -20,6 +34,20 @@ function Orders({ schema, rows }) {
 }
 ```
 
+Row selection supports editable ranges. `selection.toggle(id)` toggles a row
+and starts a range; `selection.toggle(id, true)` grows or shrinks it from that
+fixed anchor, preserving earlier selections. If the anchor was unchecked,
+the range unchecks rows instead, restoring their previous checks when shrunk.
+`selection.toggle(id, true, true)` adds the span to the current selection and
+commits existing checks before subsequent range adjustments. The existing
+one- and two-argument calls remain supported.
+
+Ranges use the current page's complete displayed order, including virtualized
+rows outside the viewport. Changes to that order or page reset the active range
+while retaining selected IDs; refreshing the same ordered IDs retains it.
+Page-wide selection changes, `clear`, `replace`, and `retain` reset the range.
+Shift without a valid anchor behaves like an ordinary toggle.
+
 `table.selection.replace(ids)` atomically makes any iterable of stable row IDs
 the complete selection, including IDs outside the displayed page.
 `table.selection.retain(ids)` atomically intersects the current selection with
@@ -39,6 +67,28 @@ history, referrers, logs, analytics, bookmarks, and screenshots. Pass
 is appropriate; sensitive applications should use an access-controlled server
 `StorageAdapter`.
 
+With `syncUrl: true`, oversized queries use a browser-local FIFO cache and a
+temporary short URL. Configure its size/budget with `links: { cache,
+maxUrlBytes }`; the default complete URL budget is 2,000 bytes. Local links
+can expire through cache eviction and do not transfer with browser bookmark sync.
+Configure `storage.snapshots: httpQuerySnapshotStore("/api/query-snapshots")`
+for permanent Save/Share links. `api.links.create()` also supports a host's explicit
+Bookmark action. Normal edits never write snapshots to the server. Missing
+references fail visibly before rows/metrics execute. See the
+[link integration contract](../../docs/url-state-and-saved-search-design.md).
+
+`api.saved.update(id)` persists the current snapshot before replacing the saved
+search through `storage.updateNamed`. The adapter must update atomically and
+retain the saved ID and default selection; failed updates preserve the original.
+Both built-in adapters support updates. For custom adapters, QueryBuilder offers
+Update only when `api.saved.canUpdate` is true. Optional last/default storage read
+failures fall back to table defaults; explicit broken URL links still block
+execution. A single empty `?q=` is treated as an absent query.
+
+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.
+
 See the [repository README](https://github.com/Pythia-Software/query-table#readme)
 for transport and schema examples.
 

package/dist/index.d.ts

@@ -1,4 +1,125 @@
-import { FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, RowId, SelectColumn, QueryState, FieldSchema, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, WhereClause, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedColumnStore, ComputedExecution } from '@pythia-software/query-table-core';
+import { QueryState, GroupedRow, GroupingModel, FieldSchema, 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, WhereClause, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedColumnStore, ComputedExecution, 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">;
+
+/** Source-stage controls. Rows/columns/metrics remain on the active result API. */
+type GroupingSourceApi<Row> = QueryFilterApi<Row> & Pick<QueryTableApi<Row>, "itemDetails" | "rowId"> & {
+    schema: FieldSchema<Row>;
+};
+interface GroupingApi<Row> {
+    inputsReady?: boolean;
+    preview?: (query: QueryState, signal?: AbortSignal) => Promise<{
+        rows: GroupedRow[];
+        sourceTotal: number;
+        total: number;
+    }>;
+    supported: boolean;
+    model: GroupingModel<Row>;
+    api: QueryTableApi<Row>;
+    source: GroupingSourceApi<Row>;
+    grouped: QueryTableApi<Row>;
+    schema: FieldSchema<Row>;
+    view: GroupingView;
+    inputs: Row[];
+    notice: string;
+    setNotice: (notice: string) => void;
+    changeKeys: (keys: string[]) => void;
+    addSummary: (op: SummaryOp, field?: string) => void;
+    changeSummary: (id: string, op: SummaryOp) => void;
+    changeRepresentative: (rule: RepresentativeRow | null) => void;
+    representativeImpact: () => string;
+    applyColumns: (summaries: SummaryColumn[], columns: SelectColumn[]) => void;
+}
+
+interface UsePropertyViewOptions<Row> {
+    schema: FieldSchema<Row>;
+    /** Object type, never object ID. Defaults to schema.name. */
+    key?: string;
+    storage?: PropertyViewStorage;
+    initialView?: PropertyViewState;
+}
+interface PropertyViewApi {
+    view: PropertyViewState;
+    loading: boolean;
+    error: Error | null;
+    saved: SavedPropertyView[];
+    defaultId: string | null;
+    setView(view: PropertyViewState): void;
+    reset(): void;
+    undo(): void;
+    redo(): void;
+    canUndo: boolean;
+    canRedo: boolean;
+    load(id: string): void;
+    save(name: string): Promise<SavedPropertyView>;
+    remove(id: string): Promise<void>;
+    setDefault(id: string | null): Promise<void>;
+}
+/** Owns presentation only. Changing the inspected row never resets this controller. */
+declare function usePropertyView<Row>(options: UsePropertyViewOptions<Row>): PropertyViewApi;
+
+interface QueryLinksApi {
+    maxUrlBytes: number;
+    kind: QueryLink["kind"] | null;
+    busy: boolean;
+    error: Error | null;
+    /** Explicit Share/Bookmark: server snapshot if configured, otherwise a fitting inline link. */
+    create(query?: QueryState, options?: {
+        baseUrl?: string;
+        parameter?: string;
+    }): Promise<QueryLink>;
+    /** Synchronous local-only URL for navigation, never a server write. */
+    local(query: QueryState, baseUrl?: string, parameter?: string): QueryLink;
+    /** Save uses the same immutable snapshot and promotion path as Share. */
+    snapshot(query: QueryState): Promise<QuerySnapshot | null>;
+}
+
+interface ItemDetailRecord<Row> {
+    row: Row;
+    /** Omit for complete records. Supply for a projection to distinguish missing values from NULL. */
+    loadedFields?: readonly string[];
+}
+interface ItemDetailsOptions<Row> {
+    /** Detail catalogue; defaults to the table catalogue. Useful for non-column properties. */
+    schema?: FieldSchema<Row>;
+    /** Legacy collection URL parameter. useQueryTable.queryParameter takes precedence. */
+    queryParameter?: string;
+    /** Creator-approved modalities; users can enable/disable these in Select columns. Defaults to all. */
+    modes?: ItemDetailMode[];
+    /** Initially selected buttons. Defaults to Modal (or the first allowed mode). */
+    defaultModes?: ItemDetailMode[];
+    /** Creator's initial Page link settings; users can override in the column editor. */
+    page?: ItemPageOptions;
+    storage?: PropertyViewStorage;
+    objectType?: string;
+    relationships?: RelationshipAdapter;
+    /** Defaults to complete clientRows or Transport.fetchRow, then the current projected row. */
+    loadRow?: (id: RowId, signal: AbortSignal) => Promise<ItemDetailRecord<Row> | null>;
+}
+interface ItemDetailsApi<Row> {
+    links?: QueryLinksApi;
+    schema: FieldSchema<Row>;
+    /** Collection catalogue used to resolve Page template fields. */
+    pageSchema: FieldSchema<Row>;
+    queryParameter: string;
+    /** Modal controller, retained for standalone cards. */
+    properties: PropertyViewApi;
+    propertiesByMode: Record<ItemPropertyMode, PropertyViewApi>;
+    page: ItemPageOptions;
+    availableModes: ItemDetailMode[];
+    modes: ItemDetailMode[];
+    active: ItemDetailsState["active"] | null;
+    record: ItemDetailRecord<Row> | null;
+    loading: boolean;
+    error: Error | null;
+    relationships?: RelationshipAdapter;
+    setModes(modes: ItemDetailMode[]): void;
+    open(id: RowId, mode: "modal" | "expand"): void;
+    close(): void;
+    retry(): void;
+    loadRow(id: RowId, signal: AbortSignal): Promise<ItemDetailRecord<Row> | null>;
+}
 
 type FormulaWorkerFactory = () => Worker;
 /** Host applications with a restrictive CSP can supply their own worker factory. */
@@ -34,10 +155,11 @@ interface RequestActivityApi {
 interface SelectionApi {
     selected: Set<RowId>;
     isSelected: (id: RowId) => boolean;
-    /** Toggle one row. With `shiftKey`, extend from the last-toggled anchor to `id`
-     *  across the *currently displayed* order (falls back to a plain toggle if the
-     *  anchor row is no longer present). */
-    toggle: (id: RowId, shiftKey?: boolean) => void;
+    /** Toggle one row and start an editable range. With `shiftKey`, resize that
+     *  range in the current page's order, checking or unchecking according to the
+     *  anchor's toggle. `additive` + Shift adds a span to the current selection.
+     *  Missing anchors or changed display order fall back to a plain toggle. */
+    toggle: (id: RowId, shiftKey?: boolean, additive?: boolean) => void;
     /** Select / clear every row currently on the page. */
     setPage: (ids: RowId[], selected: boolean) => void;
     /** Atomically replace the complete selection with arbitrary stable row ids. */
@@ -100,6 +222,10 @@ interface SavedQueriesApi {
     defaultId: string | null;
     /** Persist the current query under a name. Rejects on duplicate names. */
     save: (name: string) => Promise<SavedQuery>;
+    /** Whether the storage adapter supports atomic updates. */
+    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: (id: string) => void;
     /** Mark a saved query as the default view. No-op when storage lacks support. */
@@ -110,17 +236,24 @@ interface SavedQueriesApi {
 }
 declare function useSavedQueries(key: string, currentQuery: QueryState, applyQueryState: (q: QueryState) => void, storage: StorageAdapter, 
 /** Injected clock so saves are deterministic/testable. */
-now: () => number): SavedQueriesApi;
+now: () => number, snapshot?: (query: QueryState) => Promise<QuerySnapshot | null>): SavedQueriesApi;
 
 interface UseQueryTableOptions<Row> {
+    /** Pause execution and URL synchronization while a mounted host view is hidden. */
+    active?: boolean;
+    /** Capture evaluation time for grouped executions and remote query requests. */
+    evaluationNow?: () => number;
     /** Normalize external aliases without storing presentation in query state. Must be pure and not throw. */
     canonicalizeQuery?: (query: QueryState) => QueryState;
     /** Reject an entire query before rows or metrics execute. Errors retain editable query state. */
     validateQuery?: (query: QueryState) => void;
+    /** Disable row-producing grouping for this instance. Enabled for complete client datasets by default. */
+    grouping?: boolean;
     schema: FieldSchema<Row>;
     /** Data access. Omit for a purely client-side table driven by `clientRows`. */
     transport?: Transport<Row>;
-    /** All rows, for client-side mode (applyQuery runs locally over these). */
+    /** Dataset already available in memory. Remote grouping/aggregation belongs
+     * on the server; do not download a population to supply this option. */
     clientRows?: Row[];
     /** Saved/last-query persistence. Defaults to a non-durable in-memory adapter.
      * Pass localStorageAdapter() explicitly only when filter values are safe to
@@ -139,6 +272,13 @@ interface UseQueryTableOptions<Row> {
      * base64url is encoding, not encryption: filters will appear in browser
      * history, referrers, logs, analytics, and screenshots when enabled. */
     syncUrl?: boolean;
+    /** Collection URL parameter, independent of item views. Takes precedence
+     * over the legacy itemDetails.queryParameter; otherwise defaults to q. */
+    queryParameter?: string;
+    /** URL budget and browser-local FIFO cache; remote snapshots come from storage.snapshots. */
+    links?: QueryLinkOptions;
+    /** Enable schema-driven click popovers, item modals and row expansion. */
+    itemDetails?: boolean | ItemDetailsOptions<Row>;
     /** Debounce (ms) between a query change and the fetch it triggers. Default 200. */
     debounceMs?: number;
     /** Injected clock for deterministic saved-query timestamps. Default Date.now. */
@@ -203,6 +343,23 @@ interface AggregationsApi {
     contextKey?: string;
 }
 interface QueryTableApi<Row> {
+    /** Dependent source fetches can use ready without parsing display errors. */
+    restoration: {
+        status: "resolving" | "ready" | "error";
+        ready: boolean;
+        error: Error | null;
+    };
+    /** 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. */
+    restoreLocation: (location: string | URL, signal?: AbortSignal) => Promise<void>;
+    /** Row-producing GROUP BY controls and source stage, when supported. */
+    grouping?: GroupingApi<Row>;
+    /** Current result schema; changes when entering or leaving grouping. */
+    schema?: FieldSchema<Row>;
+    links: QueryLinksApi;
+    /** Built-in item details, enabled by the instance creator. */
+    itemDetails?: ItemDetailsApi<Row>;
     query: QueryState;
     /** Schema defaults used for reset controls. */
     defaults: QueryState;
@@ -211,9 +368,11 @@ interface QueryTableApi<Row> {
     canUndo: boolean;
     /** Can move forward to a previously undone local query state. */
     canRedo: boolean;
-    /** Move backward through local, unsaved query history. */
+    /** Move backward through local, unsaved query history. Empty history leaves
+     * incoming link restoration and errors unchanged. */
     undo: () => void;
-    /** Move forward through local, unsaved query history. */
+    /** Move forward through local, unsaved query history. Empty history leaves
+     * incoming link restoration and errors unchanged. */
     redo: () => void;
     requestActivity: RequestActivityApi;
     rows: Row[];
@@ -270,7 +429,13 @@ interface QueryTableApi<Row> {
 declare function useQueryTable<Row>(opts: UseQueryTableOptions<Row>): QueryTableApi<Row>;
 
 interface MetricExecutionContext<Row> {
+    executeV3?: (query: QueryState, signal?: AbortSignal) => Promise<AggregationResult>;
+    queryContextKey?: string;
     schema: FieldSchema<Row>;
+    /** One clock shared by source grouping, HAVING, rows and local metrics. */
+    now?: number;
+    /** Group projections use typed semantics even for shorthand metric clauses. */
+    strictLocalMetrics?: boolean;
     transport?: Transport<Row> | undefined;
     clientRows?: Row[] | undefined;
     shownRows?: Row[] | undefined;
@@ -290,6 +455,12 @@ interface AggregationsApiState {
     preview: (clauses: AggregationClause[], signal?: AbortSignal) => Promise<AggregationResult>;
 }
 /** Fetch state is keyed by computation and scope, never card presentation. */
-declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number, validateQuery?: (q: QueryState) => void, options?: Omit<MetricExecutionContext<Row>, "schema" | "transport" | "clientRows">): AggregationsApiState;
+declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number, validateQuery?: (q: QueryState) => void, options?: Omit<MetricExecutionContext<Row>, "schema" | "transport" | "clientRows">, enabled?: boolean): AggregationsApiState;
+
+/** One cancellable batch per displayed reference set; rejects unrelated results. */
+declare function useObjectReferences(references: ObjectReference[], adapter?: RelationshipAdapter): {
+    values: Map<string, ResolvedObjectReference>;
+    error: Error | null;
+};
 
-export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type ComputedColumnsApi, type FormulaWorkerFactory, type QueryTableApi, type RequestActivityApi, type RequestActivityEntry, type SavedQueriesApi, type SelectApi, type SelectionApi, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, 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 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, useQueryTable, useSavedQueries, useSelect, useSelection };