@elaraai/e3-ui-components 1.0.83 → 1.0.85

package/dist/query/plan.d.ts

@@ -0,0 +1,353 @@
+import { CheckJqResult, JqPruning, JqRange, JqSplit, JqSplitCall, JqSplitStages, JqWholeReason } from '@elaraai/east';
+import { ExecuteResult, SplitCallRequest } from '@elaraai/e3-types';
+import { PreparedQuery, QueryOptions, QueryReading, QueryResult, QueryRoot } from './one-shot.js';
+/**
+ * Options for planning a run: a call's limits and runner, as a one-shot call's
+ * ({@link QueryOptions}), and the most a dataset may weigh and still be read
+ * by one call.
+ */
+export interface PlanOptions extends QueryOptions {
+    /**
+     * The most a dataset may weigh, in stored bytes, and still be read by one
+     * call: e3's smallest piece, `PIECE_SIZES.min` (16 MiB), by default. A
+     * test against a server whose pieces are small sets it small too.
+     */
+    readonly pieceBytes?: number;
+}
+/** What a data source weighs, as e3's status says: its stored bytes, and the rows of a stored collection. */
+export interface SourceWeight {
+    /** What its value weighs in the store, in bytes — a collection's segments and its manifest; `undefined` when not known. */
+    readonly bytes: number | undefined;
+    /** How many elements a stored collection holds; `undefined` for a value that is not one, or when not known. */
+    readonly rows: number | undefined;
+}
+/**
+ * The programs a run plans from: the query, and what each kind of call runs
+ * of it.
+ *
+ * @remarks
+ * In the jq view all three are the jq. In the visual view a one-shot call runs
+ * the program that counts every stage's rows, and a split call runs the query
+ * itself — a rows result followed by `{counts: [length], result: .[:1000]}`,
+ * which the split runs once after the rows are joined — since a split run
+ * counts the source and the result only.
+ */
+export interface PlanPrograms {
+    /** The query as its author reads it: what the plan splits and explains. */
+    readonly query: string;
+    /** What a one-shot call runs: the query by default. */
+    readonly oneShot?: string;
+    /** What a split call runs: the query by default. */
+    readonly split?: string;
+}
+/**
+ * Why a run reads its data in one call.
+ *
+ * @remarks
+ * - `whole`: the query runs as one unit, for east's reason (`JqWhole`).
+ * - `small`: it would split over a dataset that weighs no more than one piece.
+ * - `unweighed`: it would split over a dataset whose weight is not known.
+ * - `unsplit`: it would split, and the split call could not be made — what
+ *   went wrong, so it shows rather than hides. `over` is `null` when the split
+ *   itself failed.
+ */
+export type OneCallWhy = {
+    readonly kind: "whole";
+    readonly reason: JqWholeReason;
+} | {
+    readonly kind: "small";
+    readonly over: string;
+    readonly bytes: number;
+    readonly pieceBytes: number;
+} | {
+    readonly kind: "unweighed";
+    readonly over: string;
+} | {
+    readonly kind: "unsplit";
+    readonly over: string | null;
+    readonly message: string;
+};
+/** How a run reads its data, as its explanation says it. */
+export type PlanPath = 
+/** One call, and why. */
+{
+    readonly kind: "one_shot";
+    readonly why: OneCallWhy;
+} | {
+    readonly kind: "split";
+    /** The dataset the pieces work through, by its data source's name. */
+    readonly over: string;
+    /** The dataset e3 cuts the pieces by, the heaviest of those partitioned: `over`, or one cut at the same keys with it. */
+    readonly heaviest: string;
+    /** What it weighs in the store, in bytes. */
+    readonly bytes: number;
+    /** The most a dataset may weigh and still be read by one call. */
+    readonly pieceBytes: number;
+    /** How the pieces' outputs combine: the split call's output kind. */
+    readonly output: JqSplitCall["output"]["kind"];
+    /** What runs where, as ranges of the query's text. */
+    readonly stages: JqSplitStages;
+    /** The data sources every piece reads whole. */
+    readonly broadcast: readonly string[];
+    /** The data sources partitioned with `over`, each piece holding the same keys of them (#942). */
+    readonly copartitioned: readonly string[];
+    /**
+     * A re-keyed join (#942): `over`'s rows re-keyed first by the join key,
+     * the jq of it, then joined with `name` cut at the same keys; `bytes`
+     * what the re-keyed rows are estimated to weigh, from `over`'s manifest.
+     * `null` when the join, if any, reads its other side whole.
+     */
+    readonly rekey: {
+        readonly name: string;
+        readonly key: JqRange;
+        readonly bytes: number;
+    } | null;
+};
+/**
+ * A plan's explanation, as data: the builder's words say it (`planWords`),
+ * beside the run's read-outs.
+ */
+export interface PlanExplanation {
+    /** The query's text: every range of the explanation is of it. */
+    readonly program: string;
+    /** The path, and why. */
+    readonly path: PlanPath;
+    /** The reads that skip what they don't need: a count from the index, a key seek, a stream that stops. */
+    readonly pruning: readonly JqPruning[];
+}
+/** A run's plan: the call it makes, what reading the call's answer needs, and its explanation. */
+export type QueryPlan = 
+/** One one-shot call, which e3-api-client's `oneShotExecute` sends. */
+{
+    readonly kind: "one_shot";
+    readonly prepared: PreparedQuery;
+    readonly explanation: PlanExplanation;
+}
+/** A split call, which e3-api-client's `splitCall` launches and polls; its answer is read as a one-shot call's. */
+ | {
+    readonly kind: "split";
+    readonly request: SplitCallRequest;
+    readonly reading: QueryReading;
+    readonly explanation: PlanExplanation;
+}
+/**
+ * A re-keyed join (#942): two split calls, the second over the first's
+ * output by its hash; the second's answer, with what the first read
+ * ({@link RekeyCalls.answer}), is read as a one-shot call's.
+ */
+ | ({
+    readonly kind: "rekey";
+    readonly reading: QueryReading;
+    readonly explanation: PlanExplanation;
+} & RekeyCalls);
+/** A re-keyed join's two split calls ({@link rekeyCallRequests}), and how their answers make the run's. */
+export interface RekeyCalls {
+    /** The re-key call: the dataset's rows, each under its join key, its output read by its hash, never inline. */
+    readonly first: SplitCallRequest;
+    /**
+     * The join call, over the re-key call's output.
+     *
+     * @param output - the hash of the re-key call's output, as its completed status gives it
+     * @returns the request
+     */
+    join(output: string): SplitCallRequest;
+    /**
+     * The run's answer: the join call's, or the re-key call's when it gave no
+     * output to join, with every dataset the run read — the re-key call's
+     * dataset, pinned as it pinned it, then the join call's — in the order
+     * the reading's entries name them.
+     *
+     * @param first - the re-key call's result
+     * @param join - the join call's result; `undefined` when the re-key call gave no output
+     * @returns the run's answer
+     */
+    answer(first: ExecuteResult, join: ExecuteResult | undefined): ExecuteResult;
+}
+/**
+ * A query checked and split, waiting to be weighed ({@link weighPlan}): the
+ * first half of a plan, which says which data source's weight decides it.
+ */
+export interface PlanDraft {
+    /** The data sources the query reads, in the order it first reads them: what a run says it reads. */
+    readonly reads: readonly string[];
+    /** The data source a split call would cut, whose weight decides the path; `undefined` when the query runs as one unit. */
+    readonly over: string | undefined;
+    /**
+     * The data sources whose weights decide the path: `over`, those cut at the
+     * same keys with it, and the other side of a join it could re-key (#942);
+     * none when the query runs as one unit.
+     */
+    readonly weighs: readonly string[];
+    /** The programs, each given. @internal */
+    readonly programs: Required<PlanPrograms>;
+    /** The root. @internal */
+    readonly root: QueryRoot;
+    /** The options. @internal */
+    readonly options: PlanOptions;
+    /** What the checker made of the query. @internal */
+    readonly checked: CheckJqResult;
+    /** How the query splits, or why it does not; or what went wrong splitting it. @internal */
+    readonly split: JqSplit | {
+        readonly kind: "failed";
+        readonly message: string;
+    };
+}
+/**
+ * Checks and splits a query: the first half of a plan, which says the data
+ * source whose weight decides the path ({@link PlanDraft.over}).
+ *
+ * @param programs - the query, and what each kind of call runs of it; a
+ *   string is all three
+ * @param root - the root its data sources make
+ * @param options - a call's limits and runner, and `pieceBytes`
+ * @returns the draft; or, for a query that does not check, the `error` result
+ *   a run of it gives, as {@link prepareQuery} gives it
+ * @throws {RangeError} When a limit, or `pieceBytes`, is not a whole number.
+ *
+ * @remarks
+ * The query is checked once, against the whole root, as a one-shot call's is.
+ * A `many` query is split with the call's most outputs, so its final function
+ * keeps as many as the one-shot translation does, and one more. A split that
+ * fails — a gap in the splitter, never a mistake in the query — leaves the
+ * query one call, the failure in its explanation.
+ */
+export declare function draftPlan(programs: PlanPrograms | string, root: QueryRoot, options?: PlanOptions): {
+    draft: PlanDraft;
+} | {
+    result: QueryResult;
+};
+/**
+ * Weighs a draft: the path, by what its datasets weigh, and the call it makes.
+ *
+ * @param draft - the query, checked and split ({@link draftPlan})
+ * @param weights - what the data sources whose weights decide the path
+ *   weigh ({@link PlanDraft.weighs}), by name; one not given is not known
+ * @returns the plan; or, for a one-shot program that does not check, the
+ *   `error` result a run of it gives
+ * @throws {TranslationError} When a checked program holds something the
+ *   translator cannot express.
+ *
+ * @remarks
+ * A query that runs as one unit is one call. One that splits is a split call
+ * when the datasets it cuts weigh more than `pieceBytes` — the heaviest of
+ * them, which e3 cuts the pieces by, when others are cut at the same keys —
+ * and one call when they weigh no more, or a weight is not known. A join
+ * whose other side weighs more than `pieceBytes` too is re-keyed (#942),
+ * rather than read whole by every piece: both sides large and unaligned. A
+ * split call's request is built from the split program — in the visual view,
+ * the query wrapped to count its rows — which must split as the query does:
+ * over the same dataset, into the same output kind, cut at the same keys with
+ * the same datasets and re-keying the same join; one that cannot be built is
+ * one call, and its explanation says why.
+ */
+export declare function weighPlan(draft: PlanDraft, weights: ReadonlyMap<string, SourceWeight>): {
+    plan: QueryPlan;
+} | {
+    result: QueryResult;
+};
+/**
+ * Plans a run: checks and splits the query, and weighs it — {@link draftPlan},
+ * then {@link weighPlan} with the weights of the datasets that decide it.
+ *
+ * @param programs - the query, and what each kind of call runs of it; a
+ *   string is all three
+ * @param root - the root its data sources make
+ * @param weights - what each data source weighs, by name; one not given is
+ *   not known
+ * @param options - a call's limits and runner, and `pieceBytes`
+ * @returns the plan: one call, a split call or a re-keyed join's two, what
+ *   reading its answer needs, and its explanation; or, for a query that does
+ *   not check, the `error` result a run of it gives
+ * @throws {RangeError} When a limit, or `pieceBytes`, is not a whole number.
+ *
+ * @example
+ * ```ts
+ * const planned = planQuery(".orders | group_by(.region) | map({region: .[0].region, revenue: map(.total) | add})",
+ *     root, new Map([["orders", { bytes: 1.4e9, rows: 8_000_000 }]]));
+ * if ("result" in planned) return planned.result;           // the checker's problems
+ * const plan = planned.plan;
+ * if (plan.kind === "split") {
+ *     const { result } = await splitCall(url, repo, workspace, plan.request, { token });
+ *     return queryResultOf(plan.reading, result);
+ * }
+ * if (plan.kind === "rekey") {
+ *     const first = await splitCall(url, repo, workspace, plan.first, { token });
+ *     const join = first.output === null ? undefined : (await splitCall(url, repo, workspace, plan.join(first.output), { token })).result;
+ *     return queryResultOf(plan.reading, plan.answer(first.result, join));
+ * }
+ * return queryResultOf(plan.prepared, await oneShotExecute(url, repo, workspace, plan.prepared.request, { token }));
+ * ```
+ */
+export declare function planQuery(programs: PlanPrograms | string, root: QueryRoot, weights: ReadonlyMap<string, SourceWeight>, options?: PlanOptions): {
+    plan: QueryPlan;
+} | {
+    result: QueryResult;
+};
+/**
+ * The split call a query split over a dataset's pieces runs as: the request
+ * e3-api-client's `splitCall` (or `splitCallLaunch`, `splitCallExplain`)
+ * sends, exactly as the builder sends it.
+ *
+ * @param split - the query's split (`splitJq`), over a root's data sources
+ * @param root - the root: each data source the split reads is an argument at
+ *   its path
+ * @param options - the call's limits and its runner, as a one-shot call's
+ * @returns the request
+ * @throws {RangeError} When a limit is not a whole number of at least 1.
+ * @throws {Error} When the split reads a root field no data source of the root is.
+ *
+ * @remarks
+ * - `bodyIr` is the piece program, and `then` the final function, when there
+ *   is one: each `encodeEastIR(fn.toIR())`, as a one-shot call's body is.
+ * - `args` is one `dataset` argument per input of the split, in its order —
+ *   the root fields the query reads, as the translation takes them — at its
+ *   data source's path; the one the pieces are cut from, `over`, is
+ *   partitioned with no `by`, so any key may start a piece, and so is each of
+ *   `copartitioned`, which e3 cuts at the same keys (#942); every other
+ *   argument reaches each piece whole.
+ * - `output` is the split's output kind: a dict's merge and a fold's combine
+ *   encoded as the programs are, and a fold's zero as beast2 at its type.
+ * - `runner` is a one-shot call's (`QueryOptions`): east-c given no platform
+ *   package, and no program calls a platform function, so a caller who may
+ *   read the workspace may launch it.
+ * - `limits` are a one-shot call's: no time limit unless the options set one,
+ *   so e3 gives the job the server's ceiling (ten minutes on a local server),
+ *   as it gives a one-shot call that names none the server's default.
+ *
+ * @example
+ * ```ts
+ * const split = splitJq(checkJq(".orders | map(.total) | add", root.type, { root: true }));
+ * if (split.kind === "split") {
+ *     const { result } = await splitCall(url, repo, workspace, splitCallRequest(split, root), { token });
+ * }
+ * ```
+ */
+export declare function splitCallRequest(split: JqSplitCall, root: QueryRoot, options?: QueryOptions): SplitCallRequest;
+/**
+ * A re-keyed join's two split calls (#942), as the planner sends them when
+ * both sides of a join weigh more than one piece.
+ *
+ * @param split - the query's split, whose `rekey` is the join
+ * @param root - the root
+ * @param options - the calls' limits and their runner, as a one-shot call's
+ * @returns the re-key call, the join call over its output, and how their
+ *   answers make the run's ({@link RekeyCalls})
+ * @throws {Error} When the split re-keys no join, or reads a root field no
+ *   data source of the root is.
+ *
+ * @remarks
+ * - **The re-key call** runs `rekey.piece()` over `over` partitioned, into a
+ *   dict by the join key whose merge concatenates each key's rows in input
+ *   order. Its output is read by its hash, so its answer is asked to be one
+ *   byte at most: e3 answers `too_large` with the output's hash beside it.
+ * - **The join call** runs `rekey.joinPiece()` over the re-key call's output,
+ *   an `object` argument by its hash, and the join's other side, both
+ *   partitioned, so e3 cuts them at the same keys; every other argument
+ *   reaches each piece whole. Its output kind is the split's, and its final
+ *   function `rekey.joinThen()`.
+ * - **The answer** is the join call's, with the re-key call's dataset first in
+ *   what the run read, as the re-key call pinned it; or the re-key call's own
+ *   when it ended without an output.
+ */
+export declare function rekeyCallRequests(split: JqSplitCall, root: QueryRoot, options?: QueryOptions): RekeyCalls;
+//# sourceMappingURL=plan.d.ts.map

package/dist/query/plan.d.ts.map

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

package/dist/query/query-east.d.ts

@@ -0,0 +1,21 @@
+import { TypeOf, ValueTypeOf } from '@elaraai/east';
+import { Query } from '@elaraai/e3-ui/internal';
+/** The JavaScript function an East function compiles to. */
+type Compiled<F> = ValueTypeOf<TypeOf<F>>;
+/** The query builder's compiled East — see the module docs. */
+export interface QueryEast {
+    /** The patch a save commits: the entries it writes, by name. */
+    save: Compiled<typeof Query.save>;
+    /** What refused a write under a new name, or `none` when it committed. */
+    nameWriteRefusal: Compiled<typeof Query.nameWriteRefusal>;
+    /** Whether a saved query's data sources are bound here, and if not, why not. */
+    rootBound: Compiled<typeof Query.rootBound>;
+}
+/**
+ * The query builder's East, compiled on first use.
+ *
+ * @returns The compiled functions
+ */
+export declare function queryEast(): QueryEast;
+export {};
+//# sourceMappingURL=query-east.d.ts.map

package/dist/query/query-east.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-east.d.ts","sourceRoot":"","sources":["../../src/query/query-east.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEhD,4DAA4D;AAC5D,KAAK,QAAQ,CAAC,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1C,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACtB,gEAAgE;IAChE,IAAI,EAAE,QAAQ,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,0EAA0E;IAC1E,gBAAgB,EAAE,QAAQ,CAAC,OAAO,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC1D,gFAAgF;IAChF,SAAS,EAAE,QAAQ,CAAC,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC;CAC/C;AAaD;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAGrC"}

package/dist/query/query-tab.d.ts

@@ -0,0 +1,21 @@
+import { PartStyles } from './parts.js';
+import { QueryEditor } from './use-query-editor.js';
+/** Props of {@link QueryTabPanel}. */
+export interface QueryTabPanelProps {
+    /** Editing the open query: what the tab draws, and does. */
+    readonly editor: QueryEditor;
+    /** The parts' styles, and the words. */
+    readonly ps: PartStyles;
+    /** The workspace the data sources are read in, when the builder knows it. */
+    readonly workspace: string | undefined;
+    /** The step an issue the history item went to is on. */
+    readonly focus: string | undefined;
+}
+/**
+ * Renders the Query tab — see the module docs.
+ *
+ * @param props - The editor, the styles, the workspace and the focus ({@link QueryTabPanelProps})
+ * @returns The tab
+ */
+export declare const QueryTabPanel: import('react').NamedExoticComponent<QueryTabPanelProps>;
+//# sourceMappingURL=query-tab.d.ts.map

package/dist/query/query-tab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-tab.d.ts","sourceRoot":"","sources":["../../src/query/query-tab.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,OAAO,KAAK,EAAE,UAAU,EAAU,MAAM,YAAY,CAAC;AAKrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,0DAoDxB,CAAC"}

package/dist/query/results-table.d.ts

@@ -0,0 +1,153 @@
+import { EastType } from '@elaraai/east';
+import { TableRootValue } from '@elaraai/east-ui-components';
+import { QueryWords } from './model/words.js';
+/**
+ * A run's result, decoded: its East type and its value.
+ *
+ * @remarks
+ * The type is the one the run's self-describing beast2 answer carries: `T`
+ * for a query giving one value, `Option<T>` for none or one, `Array<T>` for
+ * many.
+ *
+ * @property type - The result's East type
+ * @property value - The decoded value, of that type
+ */
+export interface DecodedResult {
+    /** The result's East type: `T`, `Option<T>` or `Array<T>`, as the run gave it. */
+    readonly type: EastType;
+    /** The decoded value, of that type. */
+    readonly value: unknown;
+}
+/**
+ * A column of a result's rows.
+ *
+ * @property key - The key each row holds the column's value under
+ * @property type - The column's East type
+ * @property field - The field the column reads; `undefined` for the one column of a result that is not records
+ */
+export interface ResultColumn {
+    /** The key each row holds the column's value under: a record's field name, or `value`. */
+    readonly key: string;
+    /** The column's East type: the field's, or the type of the values a result that is not records gives. */
+    readonly type: EastType;
+    /**
+     * The field the column reads, whose name names a list's items in it
+     * (`3 lines`); `undefined` for the one `value` column of a result that is
+     * not records, whose lists' items are `items`.
+     */
+    readonly field: string | undefined;
+}
+/**
+ * A result's rows, as the Table shows them and the CSV writes them.
+ *
+ * @property columns - The columns, in order
+ * @property rows - The rows, each a struct value keyed by column key
+ */
+export interface ResultRows {
+    /** The columns, in order: a record's fields, in declared order, or the one `value` column. */
+    readonly columns: readonly ResultColumn[];
+    /** The rows, each a struct value keyed by column key: a record itself, or `{ value }`. */
+    readonly rows: readonly unknown[];
+}
+/**
+ * A result's rows and columns, as the Table shows them (`Query Editor
+ * Spec.md` §4.11).
+ *
+ * @param result - the decoded result: its type, and its value
+ * @returns the columns, in order, and the rows, each a struct value keyed by
+ *   column key
+ *
+ * @remarks
+ * - **Records.** An array or a set of records — a recursive element read as
+ *   its node — is one row per element and one column per field, in declared
+ *   order; a record is one row.
+ * - **An option.** `none` is no rows, with the columns its payload would
+ *   give; `some` is its payload's rows.
+ * - **Anything else.** An array, a set or a vector of other values is one
+ *   row per value — a vector's numbers or booleans, as East reads them out of
+ *   it — and any other value one row, in one `value` column: each row is
+ *   `{ value }`.
+ *
+ * @example
+ * ```ts
+ * const { columns, rows } = resultRows({ type: ArrayType(Order), value: orders });
+ * // columns: customer_id, discount, id, lines, status, total — one row per order
+ *
+ * resultRows({ type: IntegerType, value: 40n });
+ * // columns: value — rows: [{ value: 40n }]
+ * ```
+ */
+export declare function resultRows(result: DecodedResult): ResultRows;
+/**
+ * The words a result's cell shows for a value the Table words rather than
+ * shows as itself (`Query Editor Spec.md` §4.11): a nested value summarised,
+ * and a missing one.
+ *
+ * @param type - the value's East type
+ * @param value - the value
+ * @param words - the words
+ * @param field - the field the value sits in, whose name names a list's
+ *   items: a column's `field`; `undefined` for the one `value` column, whose
+ *   lists' items are `items`
+ * @returns the words; `undefined` for a primitive value — Null, Boolean,
+ *   Integer, Float, String, DateTime, Blob, under any options — which a cell
+ *   holds as itself
+ *
+ * @remarks
+ * - **Missing.** An option's `none` is the missing word, "—"; its `some` is
+ *   its payload's words. A recursive value is its node's.
+ * - **A list** (an array, a set, a vector) is its size and its items, named
+ *   after its field: "1 line", "3 lines"; "3 items" where no field names
+ *   them. **A lookup table** is "1 entry", "8 entries"; **a grid** its shape,
+ *   "3 × 4".
+ * - **A record** is up to its first three fields that are neither a
+ *   collection nor a record, missing ones left out, joined " · ".
+ * - **A case** is its name; with a payload, "{case} · {payload}" — a record
+ *   payload's every field, missing ones left out; a Null payload, the case
+ *   alone. **A calculation** is "function".
+ * - **Inside a summary**, a number prints in the viewer's language through
+ *   the words' formatters, exactly: an ID field's as written, a whole number
+ *   grouped, any other with every digit (§9 — never rounded); a DateTime as
+ *   its date and time, and a Boolean, a Null and a Blob as East prints them.
+ *
+ * @example
+ * ```ts
+ * cellText(ArrayType(Line), lines, words, "lines");            // "3 lines"
+ * cellText(Status, variant("shipped", { date }), words, "status"); // "shipped · Jun 1, 2026, 14:00"
+ * cellText(OptionType(FloatType), none, words, "discount");     // "—"
+ * cellText(FloatType, 1234.5, words, "total");                  // undefined: the cell holds 1234.5
+ * ```
+ */
+export declare function cellText(type: EastType, value: unknown, words: QueryWords, field: string | undefined): string | undefined;
+/**
+ * A run's result as the value east-ui-components' Table renderer shows
+ * (`EastChakraTable`, `Query Editor Spec.md` §4.11): its rows inline,
+ * virtualised, under a sticky header, filling the height of the box it is
+ * placed in.
+ *
+ * @param result - the decoded result: its type, and its value
+ * @param words - the words: the message table, and the viewer's formatters
+ * @returns the Table's value
+ *
+ * @remarks
+ * - **Rows and columns** are {@link resultRows}': one column per field of a
+ *   record, headed by its name as a person reads it (`customer ID`), or one
+ *   `value` column, headed by the message table's word.
+ * - **A cell** holds a primitive value as itself, under its own tag — Null,
+ *   Boolean, Integer, Float, String, DateTime, Blob; an option's present
+ *   value is its payload. Every other value is a String cell of its words
+ *   ({@link cellText}): "—" where it is missing, "3 lines" where it is nested.
+ * - **Printing** is the renderer's: no column declares a format, so a number
+ *   prints every digit, never grouped — an ID as written, a total exact
+ *   (§9) — and a column whose present values are numbers is a number column,
+ *   right-aligned in tabular mono, its missing "—" with them.
+ *
+ * @example
+ * ```tsx
+ * const { type, value } = decodeBeast2(result.outcome.value.result);
+ * const table = resultTable({ type: fromEastTypeValue(type), value }, queryWords(useFormatters()));
+ * return <EastChakraTable value={table} storageKey="query-results" />;
+ * ```
+ */
+export declare function resultTable(result: DecodedResult, words: QueryWords): TableRootValue;
+//# sourceMappingURL=results-table.d.ts.map

package/dist/query/results-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results-table.d.ts","sourceRoot":"","sources":["../../src/query/results-table.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGa,KAAK,QAAQ,EAEhC,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAEpF,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQ5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACvB,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAE5D;AAiFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQzH;AAyHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,GAAG,cAAc,CAqDpF"}