@aglyn/shared-ui-jsx 1.0.0-beta.197 → 1.0.0-beta.199

package/src/lib/const/list-query-plan.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ListFilterField, type ListFilterRequest } from './list-filter';
+/**
+ * How the written search fields were normalized, so a typed value becomes the
+ * key the query can match: the lower-cased key (`equals`, `startsWith`), the
+ * one word-prefix token (`contains`, search), and the reversed key
+ * (`endsWith`). `maxPrefix` is the longest token a writer stores.
+ */
+export interface ListQueryNormalizers {
+    key(value: string): string;
+    token(value: string): string;
+    reversed(value: string): string;
+    maxPrefix: number;
+}
+/** A predicate on the query, SDK-free. `path` `__name__` is the document id. */
+export type ListQueryOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'array-contains' | 'array-contains-any';
+export type ListQueryValue = string | number | boolean | null | Date | readonly (string | number)[];
+export interface ListQueryFilter {
+    path: string;
+    op: ListQueryOp;
+    value: ListQueryValue;
+}
+export interface ListQuerySort {
+    path: string;
+    direction: 'asc' | 'desc';
+    /** The grid column this order sorts, when the list lets the grid sort by it. */
+    column?: string;
+}
+/** The document id, as a path. */
+export declare const LIST_QUERY_ID_PATH = "__name__";
+/** Firestore's cap on disjunctions — `in` values times `array-contains-any` values. */
+export declare const LIST_QUERY_DISJUNCTIONS = 30;
+export interface ListQueryDeclaration {
+    /** Every field the Filters panel may name. */
+    fields: readonly ListFilterField[];
+    /**
+     * The orders the list offers, its default FIRST. The query takes no other:
+     * each is a composite the index file carries for every filterable field.
+     */
+    sorts: readonly ListQuerySort[];
+    /**
+     * The quick search: the token array every write stamps (see
+     * `nameSearchTokens`), queried with `array-contains` on one typed word.
+     * Absent, the list offers no search box.
+     */
+    search?: {
+        tokensPath: string;
+        /**
+         * Under a scope clause the search cannot be a SECOND array clause, so a
+         * scoped list writes `<scopeToken><join><prefix>` tokens and the query
+         * asks `array-contains-any` over the scope's tokens joined to the word —
+         * one array clause that answers both.
+         */
+        scoped?: {
+            tokensPath: string;
+            join: string;
+        };
+    };
+    /**
+     * Keys a presence-map field (`keysOf`) is filtered by, for the index
+     * enumeration: `sources.form`, `sources.order`, …
+     */
+    keys?: Readonly<Record<string, readonly string[]>>;
+}
+/** What the list asks this time. */
+export interface ListQueryRequest {
+    clauses: readonly ListFilterRequest[];
+    /** The quick search's words. */
+    search?: readonly string[];
+    /** The order asked for; a sort the declaration does not offer is ignored. */
+    sort?: ListQuerySort | null;
+    /**
+     * Predicates the list always applies — its scope — which count against
+     * the same limits. An `array-contains-any` scope is what a scoped search
+     * folds into (`declaration.search.scoped`).
+     */
+    base?: readonly ListQueryFilter[];
+}
+export interface ListQueryRefusal {
+    /** The clause refused, or `search`. */
+    clause: ListFilterRequest | 'search';
+    reason: string;
+}
+export interface ListQueryPlan {
+    /** Every predicate, base included, in the order the SDK should add them. */
+    filters: ListQueryFilter[];
+    /** The one order: the range field's when there is one, else the sort. */
+    orderBy: ListQuerySort;
+    /** The clauses on the query. */
+    served: ListFilterRequest[];
+    /** The search word on the query, or null. */
+    searched: string | null;
+    /** What was asked and could not be put on the query, with why. */
+    refused: ListQueryRefusal[];
+    /** Said to the reader about what WAS served — e.g. one search word of two. */
+    notices: string[];
+}
+/**
+ * Every clause and the search, as ONE query — or as much of it as one query
+ * can hold, with the rest refused by name.
+ *
+ * Order of claim: the base (the list's scope) first, then the search, then
+ * the clauses in the order they were added. A clause that would be a second
+ * array clause, a second inequality field or push the disjunctions past
+ * thirty is refused, and the list shows the refusal beside its chip; the
+ * clauses before it stand. The search is claimed before the clauses because
+ * it is the thing a reader typed last and looks at.
+ */
+export declare function planListQuery(declaration: ListQueryDeclaration, request: ListQueryRequest, names: ListQueryNormalizers): ListQueryPlan;
+/** A composite the plan's shapes need, in the index file's own terms. */
+export interface ListQueryIndex {
+    fields: Array<{
+        fieldPath: string;
+        order?: 'ASCENDING' | 'DESCENDING';
+        arrayConfig?: 'CONTAINS';
+    }>;
+}
+/**
+ * Every composite a declaration's queries can need, under index merging:
+ * one `(predicate field, order)` index per equality or array field and per
+ * order the list can take — its sorts, and the order each range imposes.
+ *
+ * `base` names the scope predicates the list always applies (their paths
+ * and whether they are array clauses), which need their own index per order
+ * like any other equality. Pinned by each list's spec against
+ * `cloud/firebase-firestore.indexes.json`.
+ */
+export declare function listQueryIndexes(declaration: ListQueryDeclaration, base?: readonly {
+    path: string;
+    array?: boolean;
+}[]): ListQueryIndex[];
+/** An index entry as `cloud/firebase-firestore.indexes.json` stores it. */
+interface IndexFileEntry {
+    collectionGroup: string;
+    queryScope: string;
+    fields: Array<{
+        fieldPath: string;
+        order?: string;
+        arrayConfig?: string;
+    }>;
+}
+/**
+ * The composites a declaration needs that an index file does not hold — what
+ * a list's spec asserts is empty, so a declared filter cannot ship without
+ * the index that serves it.
+ */
+export declare function missingListQueryIndexes(file: {
+    indexes: readonly IndexFileEntry[];
+}, collectionGroup: string, needed: readonly ListQueryIndex[], queryScope?: 'COLLECTION' | 'COLLECTION_GROUP'): ListQueryIndex[];
+export {};