@ai-matrx/records 0.93.1 → 0.93.2

package/dist/first-page/index.d.cts

@@ -0,0 +1,213 @@
+import { a as AggregateOperation, b as AggregateMeasure, S as StoreFilter } from '../subscription-x61fFv_7.cjs';
+import { F as Field } from '../field-F9BK-aUO.cjs';
+import { k as RecordPageSort, U as Uuid } from '../record-Bo1ahH3_.cjs';
+import { T as Table, D as DrillQuestion } from '../table-kind-C3PlCE9_.cjs';
+import { b as RecordsConfig } from '../ports-BTDZ9ydi.cjs';
+import { R as RecordsClient } from '../client-DJFcYJ8I.cjs';
+import { R as RecordsSeed } from '../seed-CQkIf8UR.cjs';
+import { Q as Query } from '../types-C433sVT-.cjs';
+import { V as ViewPresentationDocument, S as SavedViewSpec, a as ViewPresentationCodec, b as SavedView } from '../views-B156FsIH.cjs';
+import '../rule-G4UQndi-.cjs';
+import '../relation-BTww_Cby.cjs';
+import '../portal-CL2Qtc-G.cjs';
+
+/**
+ * Does this column hold NUMBERS the store keeps — a number, money or percent column, or the record number
+ * (`config.system: autonumber`, worked out once on save and kept)?
+ */
+declare function holdsNumbers(field: Field): boolean;
+/** How the store should compare a column's values when it sorts by it. The record number sorts 1, 2 … 10. */
+declare function sortAsFor(field: Field): NonNullable<RecordPageSort["as"]>;
+/** One column sort, by Field key — the grid's header sort and the table's default sort share it. */
+interface ColumnSort {
+    /** The Field KEY. */
+    id: string;
+    direction: "asc" | "desc";
+}
+/** A header sort in the store's page-order shape. A sort on a column that is gone is no sort. */
+declare function pageSortFor(fields: readonly Field[], sort: ColumnSort | null | undefined): RecordPageSort[];
+/**
+ * THE TABLE'S OWN SORT — or `null`. The store writes `default_sort` as `[{field, direction}]` with `field` a Field
+ * KEY; older rows hold a bare key or `"key desc"`, so all three shapes are read. A sort naming a column the table
+ * no longer has is DROPPED, never guessed at. Only the first sort key is used.
+ */
+declare function defaultSortOf(table: Pick<Table, "default_sort"> | null | undefined, fields: readonly Field[]): ColumnSort | null;
+/** The parts of a grid grouping the reads depend on (records-ui's `GridGrouping` is one). */
+interface GroupingShape {
+    field: string;
+    then?: readonly unknown[] | undefined;
+    across?: unknown;
+    trail?: readonly unknown[] | undefined;
+}
+/**
+ * A grouping the merged grid keeps as ROWS under group headers: one level, no pivot, no drill trail. Anything else
+ * opens the drill, which reads other doors.
+ */
+declare function isPlainGrouping<G extends GroupingShape>(grouping: G | undefined): grouping is G;
+/** The page is asked in group order first, then in the sort the person chose. */
+declare function groupedPageSort(fields: readonly Field[], groupKey: string | null, sort: RecordPageSort[]): RecordPageSort[];
+/** Every summary the store answers (`custom.record_aggregate`); a chosen summary outside it is never sent. */
+declare const SUMMARY_OPERATIONS: readonly AggregateOperation[];
+/** Every group's count and each chosen summary: `record_aggregate`'s measures when grouped by the grouping column. */
+declare function groupFactMeasures(chosen: Record<string, string>): AggregateMeasure[];
+/** The summary bar's measures over the whole table: none when nothing is chosen. */
+declare function summaryBarMeasures(chosen: Record<string, string>): AggregateMeasure[];
+/** The keys of the choice columns, in the table's field order: each has a header filter list with counts. */
+declare function choiceFieldKeys(fields: readonly Field[]): string[];
+/** How many links a grid cell draws of a reverse column (the chips; the rest is "+N"). */
+declare const REVERSE_CELL_CHIPS = 3;
+/**
+ * THE VIEW'S OWN QUESTION, as the grid asks it: its Rule, else its flat filter (an empty flat filter is none).
+ * The grid's column filters are laid over this by records-ui's `storeQuestion`; with none, this is the question.
+ */
+declare function viewFilterOf(shown: {
+    where?: StoreFilter | null | undefined;
+    filters?: StoreFilter | null | undefined;
+} | null, _fields?: readonly Field[]): StoreFilter | undefined;
+
+/** The table page's own page size (100 unless embedded). */
+declare const TABLE_PAGE_SIZE = 100;
+/** How many rows an embedded table reads at a time: its first page, and each "Show more". */
+declare const EMBEDDED_PAGE_SIZE = 50;
+interface FirstGridPageArgs {
+    p_table_id: Uuid;
+    p_filter: StoreFilter | Record<string, never>;
+    p_search: null;
+    p_sort: RecordPageSort[];
+    p_view_id: null;
+    p_limit: number;
+    p_offset: 0;
+}
+/** The request for the plain opening, from what the screen itself reads — or null. Pure. */
+declare function firstGridPageArgs<P = ViewPresentationDocument>(input: {
+    tableId: Uuid;
+    table: Pick<Table, "default_sort"> | null;
+    fields: readonly Field[];
+    /** The view as THIS person sees it (the saved view with her look over it), or null for none. */
+    shown: SavedView<P> | null;
+    pageSize?: number;
+    /**
+     * The host draws the MERGED grid, which keeps a plain grouping as rows under group headers: the page is then
+     * read in group order. The classic grid opens the drill for a grouped view, so a grouped view stays unseeded.
+     */
+    merged?: boolean;
+}): FirstGridPageArgs | null;
+type OpeningOptions<P> = {
+    pageSize?: number;
+    merged?: boolean;
+    view?: SavedViewSpec<P> | undefined;
+    codec?: ViewPresentationCodec<P>;
+};
+/**
+ * Read what the screen reads (through `client`, e.g. one served from `custom.table_page_bundle`) and build the first
+ * page's request. Null when anything it needs is not answered.
+ */
+declare function firstGridPageRequest<P = ViewPresentationDocument>(client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: Omit<OpeningOptions<P>, "view">): Promise<FirstGridPageArgs | null>;
+/**
+ * THE PERSON'S SERVER-ROWS KNOBS, FROM THE TABLE'S BUNDLE: `custom.table_page_bundle` carries a `server_rows` part
+ * (whether the page may wait for the server's rows, and for how long) resolved for the person asking. Null when the
+ * seed holds no such answer (an older store, a refused part): the host treats that as off.
+ */
+declare function serverRowsOf(seed: RecordsSeed | null | undefined): {
+    on: boolean;
+    capMs: number | null;
+} | null;
+/**
+ * A TABLE PAGE'S SEED, ASKED BY THE SERVER AS THE PERSON.
+ *
+ * Asks what the table page opens on — the table's bundle, the grid's first page when it can be predicted, and on a
+ * record page the record's bundle — through a recording data source, and answers every door answer it got as a
+ * `RecordsSeed`. The host hands that to `<RecordsSeedProvider>` (`@ai-matrx/records/react`) above the table page.
+ * `dataSource` is the person's own (a server Supabase client carrying her session). Never throws.
+ */
+declare function askTablePageSeed<P = ViewPresentationDocument>(input: {
+    dataSource: unknown;
+    organizationId: Uuid;
+    tableId: Uuid;
+    actor: RecordsConfig["actor"];
+    /** A record page: its record's bundle (`custom.record_page_bundle`) is asked beside the table's. */
+    recordId?: Uuid | null;
+    /**
+     * Ask the grid's first page (default true). A function decides once the table's bundle has been answered — it is
+     * handed everything asked so far, so a host can read the person's `server_rows` knob (`serverRowsOf`) first.
+     */
+    rows?: boolean | ((asked: RecordsSeed) => boolean);
+    /** The table is drawn EMBEDDED: its page size. */
+    embedded?: boolean;
+    pageSize?: number;
+    /** The host draws the merged grid: a view grouped by one field is seeded too (group counts, summary bar, link words). */
+    merged?: boolean;
+    /** THE VIEW THE HOST HANDS THE GRID, for a table with no saved view behind it. */
+    view?: SavedViewSpec<P> | undefined;
+    /** The host's view codec (records-ui binds its grid look). Left out: the plain document. */
+    codec?: ViewPresentationCodec<P>;
+}): Promise<RecordsSeed>;
+type Base = {
+    dataSource: unknown;
+    organizationId: Uuid;
+    actor: RecordsConfig["actor"];
+};
+/** A standard source's first read: its page size and the viewer's search (an empty search is none). */
+declare function entityTableQuery(options?: {
+    pageSize?: number | undefined;
+    search?: string | null | undefined;
+}): Query;
+/** The block's own props that decide a chart's question. */
+interface EntityChartQuestionInput {
+    /** The Dimension to group by. Absent: one total. */
+    by?: string | undefined;
+    /** What to count: the rows (default) or a number column summed. */
+    measure?: {
+        op: "count";
+    } | {
+        op: "sum" | "avg" | "min" | "max";
+        of: string;
+    } | undefined;
+    where?: Record<string, unknown> | undefined;
+    organization?: string | undefined;
+}
+/** The chart's `platform.drill_ask` question. */
+declare function entityChartQuestion(input: EntityChartQuestionInput): DrillQuestion & {
+    organization?: string;
+};
+/** Several seeds as one: the later answer wins on the same door and arguments; `at` is the oldest. */
+declare function mergeSeeds(...seeds: Array<RecordsSeed | null | undefined>): RecordsSeed;
+/**
+ * AN ENTITY SOURCE'S BLOCK (a table, board or card of "task", "project", "crm_deal"): its columns and first page,
+ * asked through the entity engine's own port with the question the block's `useEntityTable` sends. Never throws.
+ */
+declare function askEntityBlockSeed(input: Base & {
+    token: string;
+    question?: {
+        pageSize?: number | undefined;
+        search?: string | null | undefined;
+    };
+}): Promise<RecordsSeed>;
+/** AN ENTITY SOURCE'S CHART: `platform.drill_ask` with the question the block sends. */
+declare function askChartSeed(input: Base & {
+    source: {
+        kind: "entity";
+        token: string;
+    };
+    question?: EntityChartQuestionInput;
+}): Promise<RecordsSeed>;
+/** One aggregate question of a tile: `client.recordAggregate`'s arguments but the table. */
+type TileSpec = Omit<Parameters<RecordsClient["recordAggregate"]>[0], "table_id">;
+/** A TABLE'S TILE: `custom.record_aggregate` over `tableId` for each `spec`. Read back with `useSeededAggregate`. */
+declare function askTileSeed(input: Base & {
+    tableId: Uuid;
+    spec: TileSpec | TileSpec[];
+}): Promise<RecordsSeed>;
+/**
+ * THE FIRST PAGE WITH A HOST'S VIEW CODEC BOUND ONCE (records-ui binds its grid look): the host re-exports these
+ * under the same names — bindings of the one definition here, never a second body.
+ */
+declare function bindFirstPageCodec<P>(codec: ViewPresentationCodec<P>): {
+    firstGridPageRequest: (client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: {
+        pageSize?: number;
+        merged?: boolean;
+    }) => Promise<FirstGridPageArgs | null>;
+    askTablePageSeed: (input: Omit<Parameters<typeof askTablePageSeed<P>>[0], "codec">) => Promise<RecordsSeed>;
+};
+
+export { type ColumnSort, EMBEDDED_PAGE_SIZE, type EntityChartQuestionInput, type FirstGridPageArgs, type GroupingShape, REVERSE_CELL_CHIPS, SUMMARY_OPERATIONS, TABLE_PAGE_SIZE, type TileSpec, askChartSeed, askEntityBlockSeed, askTablePageSeed, askTileSeed, bindFirstPageCodec, choiceFieldKeys, defaultSortOf, entityChartQuestion, entityTableQuery, firstGridPageArgs, firstGridPageRequest, groupFactMeasures, groupedPageSort, holdsNumbers, isPlainGrouping, mergeSeeds, pageSortFor, serverRowsOf, sortAsFor, summaryBarMeasures, viewFilterOf };

package/dist/first-page/index.d.ts

@@ -0,0 +1,213 @@
+import { a as AggregateOperation, b as AggregateMeasure, S as StoreFilter } from '../subscription-1ik9orQK.js';
+import { F as Field } from '../field-GR--cya9.js';
+import { k as RecordPageSort, U as Uuid } from '../record-Bo1ahH3_.js';
+import { T as Table, D as DrillQuestion } from '../table-kind-C2bMlOaV.js';
+import { b as RecordsConfig } from '../ports-CCPhsr-V.js';
+import { R as RecordsClient } from '../client-BKhJ6Ezn.js';
+import { R as RecordsSeed } from '../seed-Dz8Hi2LZ.js';
+import { Q as Query } from '../types-BBwIxf_z.js';
+import { V as ViewPresentationDocument, S as SavedViewSpec, a as ViewPresentationCodec, b as SavedView } from '../views-Bny6SBX0.js';
+import '../rule-BojwTDvi.js';
+import '../relation-D8UmOxPh.js';
+import '../portal-o9FhryoU.js';
+
+/**
+ * Does this column hold NUMBERS the store keeps — a number, money or percent column, or the record number
+ * (`config.system: autonumber`, worked out once on save and kept)?
+ */
+declare function holdsNumbers(field: Field): boolean;
+/** How the store should compare a column's values when it sorts by it. The record number sorts 1, 2 … 10. */
+declare function sortAsFor(field: Field): NonNullable<RecordPageSort["as"]>;
+/** One column sort, by Field key — the grid's header sort and the table's default sort share it. */
+interface ColumnSort {
+    /** The Field KEY. */
+    id: string;
+    direction: "asc" | "desc";
+}
+/** A header sort in the store's page-order shape. A sort on a column that is gone is no sort. */
+declare function pageSortFor(fields: readonly Field[], sort: ColumnSort | null | undefined): RecordPageSort[];
+/**
+ * THE TABLE'S OWN SORT — or `null`. The store writes `default_sort` as `[{field, direction}]` with `field` a Field
+ * KEY; older rows hold a bare key or `"key desc"`, so all three shapes are read. A sort naming a column the table
+ * no longer has is DROPPED, never guessed at. Only the first sort key is used.
+ */
+declare function defaultSortOf(table: Pick<Table, "default_sort"> | null | undefined, fields: readonly Field[]): ColumnSort | null;
+/** The parts of a grid grouping the reads depend on (records-ui's `GridGrouping` is one). */
+interface GroupingShape {
+    field: string;
+    then?: readonly unknown[] | undefined;
+    across?: unknown;
+    trail?: readonly unknown[] | undefined;
+}
+/**
+ * A grouping the merged grid keeps as ROWS under group headers: one level, no pivot, no drill trail. Anything else
+ * opens the drill, which reads other doors.
+ */
+declare function isPlainGrouping<G extends GroupingShape>(grouping: G | undefined): grouping is G;
+/** The page is asked in group order first, then in the sort the person chose. */
+declare function groupedPageSort(fields: readonly Field[], groupKey: string | null, sort: RecordPageSort[]): RecordPageSort[];
+/** Every summary the store answers (`custom.record_aggregate`); a chosen summary outside it is never sent. */
+declare const SUMMARY_OPERATIONS: readonly AggregateOperation[];
+/** Every group's count and each chosen summary: `record_aggregate`'s measures when grouped by the grouping column. */
+declare function groupFactMeasures(chosen: Record<string, string>): AggregateMeasure[];
+/** The summary bar's measures over the whole table: none when nothing is chosen. */
+declare function summaryBarMeasures(chosen: Record<string, string>): AggregateMeasure[];
+/** The keys of the choice columns, in the table's field order: each has a header filter list with counts. */
+declare function choiceFieldKeys(fields: readonly Field[]): string[];
+/** How many links a grid cell draws of a reverse column (the chips; the rest is "+N"). */
+declare const REVERSE_CELL_CHIPS = 3;
+/**
+ * THE VIEW'S OWN QUESTION, as the grid asks it: its Rule, else its flat filter (an empty flat filter is none).
+ * The grid's column filters are laid over this by records-ui's `storeQuestion`; with none, this is the question.
+ */
+declare function viewFilterOf(shown: {
+    where?: StoreFilter | null | undefined;
+    filters?: StoreFilter | null | undefined;
+} | null, _fields?: readonly Field[]): StoreFilter | undefined;
+
+/** The table page's own page size (100 unless embedded). */
+declare const TABLE_PAGE_SIZE = 100;
+/** How many rows an embedded table reads at a time: its first page, and each "Show more". */
+declare const EMBEDDED_PAGE_SIZE = 50;
+interface FirstGridPageArgs {
+    p_table_id: Uuid;
+    p_filter: StoreFilter | Record<string, never>;
+    p_search: null;
+    p_sort: RecordPageSort[];
+    p_view_id: null;
+    p_limit: number;
+    p_offset: 0;
+}
+/** The request for the plain opening, from what the screen itself reads — or null. Pure. */
+declare function firstGridPageArgs<P = ViewPresentationDocument>(input: {
+    tableId: Uuid;
+    table: Pick<Table, "default_sort"> | null;
+    fields: readonly Field[];
+    /** The view as THIS person sees it (the saved view with her look over it), or null for none. */
+    shown: SavedView<P> | null;
+    pageSize?: number;
+    /**
+     * The host draws the MERGED grid, which keeps a plain grouping as rows under group headers: the page is then
+     * read in group order. The classic grid opens the drill for a grouped view, so a grouped view stays unseeded.
+     */
+    merged?: boolean;
+}): FirstGridPageArgs | null;
+type OpeningOptions<P> = {
+    pageSize?: number;
+    merged?: boolean;
+    view?: SavedViewSpec<P> | undefined;
+    codec?: ViewPresentationCodec<P>;
+};
+/**
+ * Read what the screen reads (through `client`, e.g. one served from `custom.table_page_bundle`) and build the first
+ * page's request. Null when anything it needs is not answered.
+ */
+declare function firstGridPageRequest<P = ViewPresentationDocument>(client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: Omit<OpeningOptions<P>, "view">): Promise<FirstGridPageArgs | null>;
+/**
+ * THE PERSON'S SERVER-ROWS KNOBS, FROM THE TABLE'S BUNDLE: `custom.table_page_bundle` carries a `server_rows` part
+ * (whether the page may wait for the server's rows, and for how long) resolved for the person asking. Null when the
+ * seed holds no such answer (an older store, a refused part): the host treats that as off.
+ */
+declare function serverRowsOf(seed: RecordsSeed | null | undefined): {
+    on: boolean;
+    capMs: number | null;
+} | null;
+/**
+ * A TABLE PAGE'S SEED, ASKED BY THE SERVER AS THE PERSON.
+ *
+ * Asks what the table page opens on — the table's bundle, the grid's first page when it can be predicted, and on a
+ * record page the record's bundle — through a recording data source, and answers every door answer it got as a
+ * `RecordsSeed`. The host hands that to `<RecordsSeedProvider>` (`@ai-matrx/records/react`) above the table page.
+ * `dataSource` is the person's own (a server Supabase client carrying her session). Never throws.
+ */
+declare function askTablePageSeed<P = ViewPresentationDocument>(input: {
+    dataSource: unknown;
+    organizationId: Uuid;
+    tableId: Uuid;
+    actor: RecordsConfig["actor"];
+    /** A record page: its record's bundle (`custom.record_page_bundle`) is asked beside the table's. */
+    recordId?: Uuid | null;
+    /**
+     * Ask the grid's first page (default true). A function decides once the table's bundle has been answered — it is
+     * handed everything asked so far, so a host can read the person's `server_rows` knob (`serverRowsOf`) first.
+     */
+    rows?: boolean | ((asked: RecordsSeed) => boolean);
+    /** The table is drawn EMBEDDED: its page size. */
+    embedded?: boolean;
+    pageSize?: number;
+    /** The host draws the merged grid: a view grouped by one field is seeded too (group counts, summary bar, link words). */
+    merged?: boolean;
+    /** THE VIEW THE HOST HANDS THE GRID, for a table with no saved view behind it. */
+    view?: SavedViewSpec<P> | undefined;
+    /** The host's view codec (records-ui binds its grid look). Left out: the plain document. */
+    codec?: ViewPresentationCodec<P>;
+}): Promise<RecordsSeed>;
+type Base = {
+    dataSource: unknown;
+    organizationId: Uuid;
+    actor: RecordsConfig["actor"];
+};
+/** A standard source's first read: its page size and the viewer's search (an empty search is none). */
+declare function entityTableQuery(options?: {
+    pageSize?: number | undefined;
+    search?: string | null | undefined;
+}): Query;
+/** The block's own props that decide a chart's question. */
+interface EntityChartQuestionInput {
+    /** The Dimension to group by. Absent: one total. */
+    by?: string | undefined;
+    /** What to count: the rows (default) or a number column summed. */
+    measure?: {
+        op: "count";
+    } | {
+        op: "sum" | "avg" | "min" | "max";
+        of: string;
+    } | undefined;
+    where?: Record<string, unknown> | undefined;
+    organization?: string | undefined;
+}
+/** The chart's `platform.drill_ask` question. */
+declare function entityChartQuestion(input: EntityChartQuestionInput): DrillQuestion & {
+    organization?: string;
+};
+/** Several seeds as one: the later answer wins on the same door and arguments; `at` is the oldest. */
+declare function mergeSeeds(...seeds: Array<RecordsSeed | null | undefined>): RecordsSeed;
+/**
+ * AN ENTITY SOURCE'S BLOCK (a table, board or card of "task", "project", "crm_deal"): its columns and first page,
+ * asked through the entity engine's own port with the question the block's `useEntityTable` sends. Never throws.
+ */
+declare function askEntityBlockSeed(input: Base & {
+    token: string;
+    question?: {
+        pageSize?: number | undefined;
+        search?: string | null | undefined;
+    };
+}): Promise<RecordsSeed>;
+/** AN ENTITY SOURCE'S CHART: `platform.drill_ask` with the question the block sends. */
+declare function askChartSeed(input: Base & {
+    source: {
+        kind: "entity";
+        token: string;
+    };
+    question?: EntityChartQuestionInput;
+}): Promise<RecordsSeed>;
+/** One aggregate question of a tile: `client.recordAggregate`'s arguments but the table. */
+type TileSpec = Omit<Parameters<RecordsClient["recordAggregate"]>[0], "table_id">;
+/** A TABLE'S TILE: `custom.record_aggregate` over `tableId` for each `spec`. Read back with `useSeededAggregate`. */
+declare function askTileSeed(input: Base & {
+    tableId: Uuid;
+    spec: TileSpec | TileSpec[];
+}): Promise<RecordsSeed>;
+/**
+ * THE FIRST PAGE WITH A HOST'S VIEW CODEC BOUND ONCE (records-ui binds its grid look): the host re-exports these
+ * under the same names — bindings of the one definition here, never a second body.
+ */
+declare function bindFirstPageCodec<P>(codec: ViewPresentationCodec<P>): {
+    firstGridPageRequest: (client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: {
+        pageSize?: number;
+        merged?: boolean;
+    }) => Promise<FirstGridPageArgs | null>;
+    askTablePageSeed: (input: Omit<Parameters<typeof askTablePageSeed<P>>[0], "codec">) => Promise<RecordsSeed>;
+};
+
+export { type ColumnSort, EMBEDDED_PAGE_SIZE, type EntityChartQuestionInput, type FirstGridPageArgs, type GroupingShape, REVERSE_CELL_CHIPS, SUMMARY_OPERATIONS, TABLE_PAGE_SIZE, type TileSpec, askChartSeed, askEntityBlockSeed, askTablePageSeed, askTileSeed, bindFirstPageCodec, choiceFieldKeys, defaultSortOf, entityChartQuestion, entityTableQuery, firstGridPageArgs, firstGridPageRequest, groupFactMeasures, groupedPageSort, holdsNumbers, isPlainGrouping, mergeSeeds, pageSortFor, serverRowsOf, sortAsFor, summaryBarMeasures, viewFilterOf };