@standardbeagle/edit-db 0.4.484 → 0.4.581

package/dist/lib/content-detect.d.ts

@@ -4,8 +4,25 @@ export type ContentKind = 'json' | 'xml' | 'php-serialized' | 'binary' | 'longte
 export declare function isBinaryDbType(dbType: string): boolean;
 /** Check if a dbType is a native JSON type (json, jsonb). */
 export declare function isJsonDbType(dbType: string): boolean;
+/** Column-level JSON check: native JSON dbType or the JSON GraphQL scalar. */
+export declare function isJsonColumn(col: {
+    dbType: string;
+    paramType?: string;
+}): boolean;
 /** Check if a dbType is a long text type (text, ntext, varchar(max), xml) */
 export declare function isLongTextDbType(dbType: string): boolean;
+/**
+ * Column-level "large value" check for fetch-on-demand decisions (grid SELECT
+ * exclusion, sortability, content-viewer cells). Prefers the server's
+ * dialect-decided `dbColumnSchema.isLargeValue` flag; the dbType-name fallback
+ * exists only for servers that predate the flag. The name heuristic is WRONG on
+ * PostgreSQL and SQLite — `text` is their ordinary string type, not a LOB — which
+ * is exactly why the server flag is authoritative when present.
+ */
+export declare function isLargeValueColumn(col: {
+    dbType: string;
+    isLargeValue?: boolean;
+}): boolean;
 /** Detect content kind from a string value and optional dbType hint */
 export declare function detectContentKind(value: string, dbType?: string): ContentKind;
 /** Max characters to show in a table cell before truncating */
@@ -14,3 +31,25 @@ export declare const CELL_TRUNCATE = 80;
 export declare function truncateForCell(value: string): string;
 /** Format binary data (base64 string) for display */
 export declare function formatBinaryPreview(value: string): string;
+/** What a binary (base64) value actually IS, sniffed from its magic bytes. */
+export type SniffedBinary = {
+    kind: 'image';
+    mime: string;
+    extension: string;
+} | {
+    kind: 'pdf';
+    mime: 'application/pdf';
+    extension: '.pdf';
+} | {
+    kind: 'unknown';
+    mime: 'application/octet-stream';
+    extension: '.bin';
+};
+/**
+ * Sniffs an image/document type from the FIRST BYTES of a base64 value — never
+ * from a column name or a user-supplied mime string, so a mislabeled blob can
+ * only ever downgrade to the generic binary rendering, not upgrade to <img>.
+ */
+export declare function sniffBinaryContent(base64: string): SniffedBinary;
+/** A data: URL for an inline binary preview (only call for sniffed images). */
+export declare function binaryDataUrl(base64: string, mime: string): string;

package/dist/lib/content-detect.sniff.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/date-input.d.ts

@@ -0,0 +1,21 @@
+import { Column } from '../types/schema';
+/** True for any date-ish column (bare date or datetime). */
+export declare function isDateColumn(column: Column): boolean;
+/** True when a date-ish column carries a time-of-day component (datetime, not a bare date). */
+export declare function isDateTimeColumn(column: Column): boolean;
+/**
+ * Normalizes a stored date/datetime string into the value an `<input type="date">`
+ * or `<input type="datetime-local">` expects. For datetime columns the time-of-day
+ * is preserved (fractional seconds and timezone offset are trimmed) so re-saving an
+ * unrelated field does not overwrite the time with midnight. Returns '' for the
+ * SQL "zero" date and unparseable input.
+ */
+export declare function toDateInputValue(raw: string | undefined, withTime: boolean): string;
+/**
+ * Restore the original raw value for every date/datetime field the user did not
+ * edit. The form holds `toDateInputValue` projections; a field whose current form
+ * value still equals the projection of the original raw value is untouched, so
+ * the raw value (offset and fractional seconds intact) is sent instead of the
+ * lossy projection. Fields the user actually changed keep the new form value.
+ */
+export declare function preserveUntouchedDateValues(formValues: Record<string, unknown>, originalRow: Record<string, unknown>, columns: Column[]): Record<string, unknown>;

package/dist/lib/date-input.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/drill-stack.d.ts

@@ -1,8 +1,25 @@
-import { ColumnPanel } from '../data-panel';
+/**
+ * @module lib/drill-stack
+ *
+ * Pure-logic helpers for the stackable parent/child drill-down used by the
+ * edit-db data panel. Each entry in the stack describes a side column: a
+ * target table plus an optional filter (FK column + parent row id) that
+ * scopes the child rows to those related to a row in the previous level.
+ *
+ * Kept dependency-free so it can be unit-tested without React or the DOM.
+ */
 /**
  * A single frame in the drill navigation chain, visible as one side column.
+ * `filterTable` + `filterId` + `filterColumn` describe the FK scoping applied
+ * to `tableName`'s rows — they're optional so the same shape can also
+ * represent a simple "open table X" panel.
  */
-export type DrillFrame = ColumnPanel;
+export interface DrillFrame {
+    tableName: string;
+    filterTable?: string;
+    filterId?: string;
+    filterColumn?: string;
+}
 /**
  * Is `frame` the same drill target as `other` (same table + same filter)?
  *

package/dist/lib/export.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The single, framework-free result-export utility for the shipped edit-db
+ * chain. Every export surface — the data grid, the raw SQL console result grid,
+ * and any future report runner — serializes through THIS module so there is
+ * exactly one CSV/JSON implementation in the shipped path.
+ *
+ * The serializers are matrix-based (`string[]` headers + `unknown[][]` rows) so
+ * they serve both the grid (record rows projected onto ordered fields) and the
+ * console (already-columnar positional rows) without a second code path.
+ *
+ * Value coercion is deliberate about the type classes that have bitten edit-db
+ * before:
+ *  - NULL vs empty string are distinguishable in CSV (NULL -> empty field,
+ *    "" -> a quoted empty pair, the PostgreSQL CSV convention).
+ *  - bigint is rendered as its exact decimal string, never coerced through
+ *    Number (which silently rounds past 2^53 — a known BigInt-PK bug class).
+ *  - Date is rendered as a stable ISO-8601 string.
+ */
+export type ExportFormat = 'csv' | 'json';
+export type JsonMode = 'array' | 'lines';
+/** The UTF-8 byte-order mark. Prepending it makes Excel open the CSV as UTF-8. */
+export declare const UTF8_BOM = "\uFEFF";
+/**
+ * Render one cell value as an RFC4180 CSV field.
+ *
+ * `null`/`undefined` become a bare empty field; an empty string becomes a
+ * quoted empty pair (`""`) so the two stay distinguishable in the output bytes.
+ * bigint and Date get exact/stable string forms; objects are JSON-encoded.
+ */
+export declare function formatCsvCell(value: unknown): string;
+export interface CsvOptions {
+    /** Prepend the UTF-8 BOM so Excel detects the encoding. Default false. */
+    bom?: boolean;
+}
+/**
+ * Serialize a header row plus data rows into an RFC4180 CSV string. Rows are
+ * joined with CRLF as the RFC specifies. `rows` are positional, aligned to
+ * `headers`.
+ */
+export declare function buildCsv(headers: readonly string[], rows: ReadonlyArray<readonly unknown[]>, options?: CsvOptions): string;
+export interface JsonOptions {
+    /** `array` (default): a single pretty-printed JSON array. `lines`: NDJSON. */
+    mode?: JsonMode;
+}
+/**
+ * Serialize header + rows into JSON, keyed by the header names. `array` mode
+ * emits one pretty-printed array; `lines` mode emits newline-delimited JSON
+ * (one compact object per line). bigint PKs round-trip losslessly as strings.
+ */
+export declare function buildJson(headers: readonly string[], rows: ReadonlyArray<readonly unknown[]>, options?: JsonOptions): string;
+/** One page of the source result set, as returned by the paging fetcher. */
+export interface ExportPage {
+    /** Positional rows, aligned to the export headers. */
+    rows: unknown[][];
+    /** The server's total row count for the current filter (drives the loop). */
+    total: number;
+}
+export interface ExportAllOptions {
+    headers: string[];
+    format: ExportFormat;
+    /**
+     * Pull one page at the given offset. This is the ONLY data seam — the caller
+     * closes over the existing fetcher/query-builder so the current filters and
+     * sort are honored, and no new HTTP client is introduced.
+     */
+    fetchPage: (offset: number, limit: number) => Promise<ExportPage>;
+    /** Page size for each fetch. Default 500. */
+    pageSize?: number;
+    /** Hard stop after this many rows; the result is marked `truncated`. */
+    rowCap?: number;
+    /** Abort mid-export; the promise rejects and no content is assembled. */
+    signal?: AbortSignal;
+    /** Called after each page with the running fetched count and the total. */
+    onProgress?: (fetched: number, total: number) => void;
+    csv?: CsvOptions;
+    json?: JsonOptions;
+}
+export interface ExportResult {
+    content: string;
+    rowCount: number;
+    total: number;
+    truncated: boolean;
+}
+/**
+ * Drain the full result set page by page and serialize it once at the end.
+ *
+ * Cancellation is fail-safe: an aborted signal makes this throw before any
+ * content string is built, so the caller — which only writes a file on a
+ * resolved result — never produces a partial file. The row cap stops paging
+ * early and flags `truncated` so the caller can warn.
+ */
+export declare function exportAllRows(options: ExportAllOptions): Promise<ExportResult>;
+/**
+ * Default confirmation threshold: exporting more than this many rows prompts the
+ * user first, since it means paging the full result set out of the database.
+ */
+export declare const DEFAULT_ROW_CAP = 100000;
+/** Options passed to a bound {@link ExportRunner}. */
+export interface RunExportOptions {
+    format: ExportFormat;
+    signal?: AbortSignal;
+    onProgress?: (fetched: number, total: number) => void;
+    rowCap?: number;
+}
+/**
+ * A surface-bound export runner: closes over the surface's headers + paging
+ * fetcher and drains the full result set. Returns null when the surface has
+ * nothing to export (no active query/table). This is the seam the grid toolbar
+ * and any other paged surface hand to the shared export button.
+ */
+export type ExportRunner = (options: RunExportOptions) => Promise<ExportResult | null>;
+/** MIME type for a downloaded file of the given format. */
+export declare function mimeFor(format: ExportFormat): string;
+/** `<base>-export.<ext>` filename for the given format. */
+export declare function filenameFor(base: string, format: ExportFormat): string;
+/**
+ * Trigger a browser download of `content` as `filename`. Builds a Blob, clicks a
+ * transient `<a download>`, then revokes the object URL. No-ops outside a DOM.
+ */
+export declare function downloadTextFile(content: string, filename: string, mimeType: string): void;
+/** Download a base64-encoded binary value as a file (image, PDF, any blob). */
+export declare function downloadBinaryFile(base64: string, filename: string, mimeType: string): void;

package/dist/lib/export.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/field-validation.d.ts

@@ -1,4 +1,10 @@
 import { Column } from '../types/schema';
+/**
+ * The temporal family of a column, from its DATABASE type (mirrors the server's
+ * ValidationRules.TemporalKindOf) — paramType can't carry this, because
+ * temporal mutation inputs are String on the wire.
+ */
+export declare function temporalKindOf(column: Column): 'datetime' | 'date' | 'time' | undefined;
 /**
  * Anchors a pattern the same way the HTML5 `pattern` attribute and the server
  * validator do: wrap as ^(?:...)$ unless the author already anchored it with ^.
@@ -10,3 +16,13 @@ export declare function anchorPattern(pattern: string): string;
  * callers keep their own required policy (forms use !isNullable).
  */
 export declare function validateFieldValue(column: Column, value: unknown, isRequired: boolean): string | undefined;
+/**
+ * Validates every value PRESENT in a mutation payload against its column's
+ * schema rules — the pre-send gate the mutation hooks run so EVERY write path
+ * (forms, programmatic callers, future surfaces) is checked, not only fields a
+ * form happened to attach validators to. Absent/cleared values are skipped:
+ * required-ness is form policy (a NOT NULL column with a DB default is legal to
+ * omit on insert), and this gate must never refuse what the server accepts.
+ * Returns all failures, or an empty array when the payload is clean.
+ */
+export declare function validateRowValues(columns: readonly Column[], detail: Record<string, unknown>): string[];

package/dist/lib/fk.d.ts

@@ -1,13 +1,34 @@
-import { Join, Table } from '../types/schema';
+import { Column, Join, Table } from '../types/schema';
 export interface FkEqFilterResult {
     filterText: string;
     variables: Record<string, unknown>;
     params: string[];
 }
+/**
+ * Coerce a raw cell/route value to the JS type matching a GraphQL scalar so the
+ * variable payload agrees with its declared type (e.g. a Boolean FK is sent as
+ * `true`, not `"true"`). Unparseable numerics are passed through untouched so
+ * the server reports the real error instead of receiving `NaN`.
+ */
+export declare function coerceForGql(value: unknown, gqlType: string): unknown;
+/** The base GraphQL scalar of a column (`paramType` minus non-null marker), defaulting to String. */
+export declare function gqlTypeOf(column: Column | undefined): string;
 export declare function isFkMember(join: Join, columnName: string): boolean;
 export declare function isComposite(join: Join): boolean;
+/**
+ * The destination column paired POSITIONALLY with `columnName` on the source side
+ * of `join`, or null when the pairing does not exist.
+ *
+ * Null is the whole point. The previous inline form was
+ * `destinationColumnNames[indexOf(name)] ?? destinationColumnNames[0]`: `indexOf`
+ * returns -1 for a column that is not part of the join, the indexed read is
+ * `undefined`, and `??` then substituted the FIRST destination column — so an
+ * unresolvable pairing silently produced a confident, wrong FK target instead of
+ * an absent one. Callers must handle null by declining the FK behaviour, never by
+ * guessing a column (see .claude/rules/composite-pk-compliance.md).
+ */
+export declare function fkDestinationColumnFor(join: Join, columnName: string): string | null;
 export declare function findJoinBySource(joins: Join[], columnName: string): Join | undefined;
-export declare function findJoinByDestinationTable(joins: Join[], destinationTable: string): Join | undefined;
 /**
  * Build a `{_eq}`-per-column composite filter against the destination side of a join,
  * using values pulled from a source-side row. Single-column joins emit a single

package/dist/lib/form-definition.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Saved-form definition shape consumed by the form runner.
+ *
+ * A {@link FormDefinition} is the builder's output (see the desktop shell's
+ * `forms/form-state.ts`): a bound single-record data-entry form over one table.
+ * The runner binds it to live data. The types are re-declared here — rather than
+ * imported from the shell — to keep this shipped stack self-contained (the same
+ * choice `common/saved-objects.ts` makes for its `SavedObject` contract), and to
+ * give the runner a tolerant parser for the `unknown` `SavedObject.definition`
+ * payload it is handed.
+ */
+/** The data-entry widget a field renders as. Mirrors the builder's FormControlType. */
+export type FormControlType = 'text' | 'textarea' | 'number' | 'checkbox' | 'date' | 'datetime' | 'select';
+export interface FormField {
+    /** Column name within the bound table. */
+    column: string;
+    /** Display label shown beside the control. */
+    label: string;
+    control: FormControlType;
+    /** Read-only controls render disabled. */
+    readOnly: boolean;
+    /** Required marker (runtime enforces via field validation). */
+    required: boolean;
+    /** Whether the field appears on the form. */
+    include: boolean;
+}
+/** A schema-derived related-record section below the parent form. */
+export interface FormSubform {
+    /** Stable relationship id, normally the parent collection field. */
+    relationship: string;
+    childTable: string;
+    /** Parent and child FK columns are parallel; composite links include every pair. */
+    parentColumns: string[];
+    childColumns: string[];
+    label: string;
+    mode: 'grid' | 'stacked';
+}
+export interface FormDefinition {
+    /** Identifier of the bound table (qualified "schema.name" or GraphQL name). */
+    table: string;
+    /** Form caption. */
+    title: string;
+    /** Layout columns (1–4): how many fields sit side-by-side. */
+    columns: number;
+    fields: FormField[];
+    subforms?: FormSubform[];
+}
+/**
+ * Validates an unknown value (e.g. a `SavedObject.definition`) as a
+ * {@link FormDefinition}. Returns null when it cannot be bound — a missing table,
+ * or no parseable fields, means there is nothing to render. Unparseable
+ * individual fields are dropped (tolerant), mirroring the builder's storage
+ * parser, so one bad field never blanks the whole form.
+ */
+export declare function parseFormDefinition(value: unknown): FormDefinition | null;
+/** The included fields, in definition order — what the runner renders. */
+export declare function visibleFields(def: FormDefinition): FormField[];

package/dist/lib/form-definition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/form-runner-nav.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure record-cursor math for the form runner's first/prev/next/last navigation.
+ *
+ * The runner browses a table one record at a time by absolute offset (a
+ * `limit: 1 offset: <index>` fetch), so the only stateful arithmetic is moving a
+ * bounded index across `[0, total)`. Keeping it here makes it unit-testable
+ * without a fetcher or DOM, and keeps the component thin.
+ */
+export type NavDirection = 'first' | 'prev' | 'next' | 'last';
+/**
+ * Resolves the target absolute index for a navigation step, clamped into the
+ * valid range. `total <= 0` (empty table) always resolves to 0 so callers show
+ * the "no records" state rather than a negative offset.
+ */
+export declare function nextIndex(current: number, total: number, direction: NavDirection): number;
+/** Whether a navigation step from `current` would actually move (false at a bound). */
+export declare function canNavigate(current: number, total: number, direction: NavDirection): boolean;
+/** Human 1-based position label, e.g. "3 of 12". Empty table reads "0 of 0". */
+export declare function positionLabel(index: number, total: number): string;

package/dist/lib/form-runner-nav.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/form-subform.d.ts

@@ -0,0 +1,12 @@
+import { Join, Table } from '../types/schema';
+export interface ChildFilterPlan {
+    params: string[];
+    filter: string;
+    variables: Record<string, unknown>;
+}
+/** True only when every parent-key/FK pair can be safely bound. */
+export declare function relationshipIsUsable(parent: Table, child: Table, join: Join): boolean;
+/** Builds a parameterized child filter; composite relationships bind every pair. */
+export declare function childFilterPlan(parent: Table, child: Table, join: Join, row: Record<string, unknown> | null): ChildFilterPlan | null;
+/** Values supplied to a child create form; callers hide these FK controls. */
+export declare function childPrefill(join: Join, row: Record<string, unknown> | null): Record<string, unknown>;

package/dist/lib/form-subform.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/form-widget.d.ts

@@ -0,0 +1,36 @@
+import { FormControlType, FormField } from './form-definition';
+/** Structural subset of the app-metadata `FieldMetadata` this module reads. */
+export interface FieldWidgetHint {
+    /** Widget hint (e.g. `text`, `select`) — overrides the saved control when recognised. */
+    widget?: string;
+    /** Whether the field is visible. Metadata default is `true`. */
+    visible?: boolean;
+    /** Whether the field is read-only. Metadata default is `false`. */
+    readOnly?: boolean;
+}
+/** The rendered control plus its resolved read-only / visible state. */
+export interface ResolvedWidget {
+    control: FormControlType;
+    readOnly: boolean;
+    visible: boolean;
+}
+/**
+ * Resolves the effective widget for a field. The metadata widget hint (when it
+ * names a known control) wins over the saved control; read-only is the union of
+ * both sources (either can lock a field, neither can unlock what the other
+ * locked); visibility requires the field be included AND not hidden by metadata.
+ */
+export declare function resolveWidget(field: FormField, meta?: FieldWidgetHint): ResolvedWidget;
+/** How a control maps onto a DOM element for rendering. */
+export type ControlRender = {
+    kind: 'input';
+    type: string;
+} | {
+    kind: 'textarea';
+} | {
+    kind: 'checkbox';
+} | {
+    kind: 'select';
+};
+/** Maps a control type to the element the runner should render. */
+export declare function controlRender(control: FormControlType): ControlRender;

package/dist/lib/form-widget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/format-value.d.ts

@@ -51,3 +51,29 @@ export declare function formatRelative(date: Date, now?: Date): string;
  * `title` revealing the exact value), or the plain string otherwise.
  */
 export declare function formatColumnValue(value: unknown, column: Column, options?: FormatOptions): ReactNode;
+/**
+ * Format a raw date/datetime string for grid-cell display via toLocaleString,
+ * blanking sentinel "unset" instants.
+ *
+ * Only exact placeholder/sentinel instants are blanked, not legitimate
+ * historical dates. A broad "before 1973" cutoff hid real dates (e.g. a 1900
+ * birthdate or a 1969 record). The two markers that actually mean "unset":
+ * the Unix epoch (timestamp 0, i.e. 1970-01-01T00:00:00Z) and .NET/SQL
+ * DateTime.MinValue (year 0001-01-01).
+ */
+export declare function formatDateCellValue(value: string): string;
+/**
+ * Formats a number into an abbreviated string representation.
+ *
+ * @example
+ * ```typescript
+ * abbreviateNumber(12)      // "12"
+ * abbreviateNumber(1200)    // "1.2k"
+ * abbreviateNumber(45000)   // "45k"
+ * abbreviateNumber(1200000) // "1.2M"
+ * ```
+ *
+ * @param num - Number to abbreviate
+ * @returns Abbreviated string representation
+ */
+export declare function abbreviateNumber(num: number | null): string;

package/dist/lib/grid-grouping.d.ts

@@ -0,0 +1,63 @@
+import { ColumnFiltersState } from '@tanstack/react-table';
+import { Column, Table } from '../types/schema';
+/** URL parameter that owns the selected grouping field. */
+export declare const GRID_GROUP_BY_PARAM = "gb";
+/** Optional, URL-owned numeric measure shown beside every server aggregate. */
+export declare const GRID_GROUP_SUM_PARAM = "gs";
+/**
+ * Resolves the URL value against the current schema.  Keeping this lookup at
+ * the boundary means a stale browser-history value can never become GraphQL
+ * source text for a different table.
+ */
+export declare function groupingColumnFromUrl(value: string | null, table: Table | null): Column | null;
+/** The aggregate result is deliberately server-owned; it is never calculated from page rows. */
+export interface GroupingRow {
+    value: unknown;
+    count: number;
+    sum: unknown;
+}
+/**
+ * Grouped results have their own aggregate-row ordering.  It is intentionally
+ * separate from the flat-grid sort: the latter orders individual records,
+ * while this controls aggregate buckets.  Count ties always use the group key
+ * ascending so pagination remains deterministic.
+ */
+export type GroupingSort = {
+    field: 'key' | 'count';
+    desc: boolean;
+};
+export declare const DEFAULT_GROUPING_SORT: GroupingSort;
+export interface GridGroupingRequest {
+    query: string;
+    variables: Record<string, unknown>;
+    groupBy: Column;
+    sumBy: Column | null;
+    sort: GroupingSort;
+}
+export interface GridGroupMemberRequest {
+    query: string;
+    variables: Record<string, unknown>;
+    /** Response field selected from the current schema, never parsed from query text. */
+    responseKey: string;
+}
+export declare function groupingSumColumnFromUrl(value: string | null, table: Table | null): Column | null;
+/**
+ * Update one of the grouping-owned URL fields without disturbing filters, the
+ * selected profile, or other application-owned state.  The caller receives a
+ * fresh instance so it is safe to use during render/effects as well as event
+ * handlers.
+ */
+export declare function withGroupingUrlParam(search: URLSearchParams, param: typeof GRID_GROUP_BY_PARAM | typeof GRID_GROUP_SUM_PARAM, value: string | null): URLSearchParams;
+/** Remove grouping state when navigation changes the source table. */
+export declare function withoutGroupingUrlParams(search: URLSearchParams): URLSearchParams;
+/** Builds the schema-derived aggregate document used by the grouped grid. */
+export declare function buildGridGroupingRequest(table: Table, groupBy: Column, columnFilters: ColumnFiltersState, headerFilter: string, sumBy?: Column | null, sort?: GroupingSort): GridGroupingRequest;
+export declare function readGroupingRows(data: Record<string, unknown> | undefined, table: Table, groupBy: Column, sort?: GroupingSort): GroupingRow[];
+/** Defined aggregate ordering for the server-grouped replacement surface. */
+export declare function compareGroupingRowsByKey(left: GroupingRow, right: GroupingRow): number;
+/** Sort aggregate buckets by the selected key/count direction with a stable key tie-breaker. */
+export declare function compareGroupingRows(left: GroupingRow, right: GroupingRow, sort?: GroupingSort): number;
+/** Reads a selected configured measure without ever deriving it from page rows. */
+export declare function readGroupingRowsWithSum(data: Record<string, unknown> | undefined, table: Table, groupBy: Column, sumBy: Column | null, sort?: GroupingSort): GroupingRow[];
+/** Schema-derived member query for a single aggregate key. It merges, never replaces, active filters. */
+export declare function buildGridGroupMemberRequest(table: Table, groupBy: Column, value: unknown, columnFilters: ColumnFiltersState, headerFilter: string, sort?: readonly string[]): GridGroupMemberRequest;

package/dist/lib/grid-grouping.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/invalidate.d.ts

@@ -0,0 +1,7 @@
+import { QueryClient } from '@tanstack/react-query';
+/**
+ * Invalidate every query family that can serve rows affected by a write to
+ * `tableName`. Returns the refetch promise for callers that want to await it;
+ * queries are marked invalidated synchronously either way.
+ */
+export declare function invalidateAfterTableWrite(queryClient: QueryClient, tableName: string): Promise<void>;

package/dist/lib/invalidate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/label-match.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module lib/label-match
+ *
+ * Client-side label filter shared by FK dropdowns (`ParentField`) and the
+ * many-to-many `TargetPicker` fallback. Used when the label column is not
+ * String-typed, so the server-side `_contains` search is unavailable and rows
+ * are filtered within the fetched window instead.
+ */
+/**
+ * Case-insensitive substring match against a row's `label`, falling back to its
+ * id field (`idKey`) when no label was fetched.
+ */
+export declare function matchesLabel(row: object, idKey: string, term: string): boolean;

package/dist/lib/label-match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/m2m.d.ts

@@ -31,13 +31,45 @@ export declare function m2mRowsQuery(junction: Table, target: Table, m2m: ManyTo
 };
 export interface M2mTargetPickerPlan {
     query: string;
-    idColumn: string;
+    /**
+     * Columns that together identify a target row — every PK column in declaration
+     * order. Both the picker and the already-linked set must key on ALL of them
+     * (via {@link m2mTargetIdentityColumns}) or two rows sharing their first key
+     * column collapse into one.
+     */
+    identityColumns: string[];
+    /**
+     * The target column the junction FK references — the value written on attach.
+     * Deliberately separate from identity: on a composite-PK target, or a junction
+     * that points at a unique non-PK column, the two are different columns.
+     */
+    linkColumn: string;
+    /** True when the label column is String-typed and thus supports the
+     *  server-side `_contains` search; callers fall back to client filtering. */
+    serverSearch: boolean;
 }
+/**
+ * The columns that identify a target row, in declaration order.
+ *
+ * Single source of truth for BOTH sides of the picker's duplicate check — the
+ * fetched target rows and the already-linked rows read off the junction. Keying
+ * the two independently (or on the first PK column alone) let two distinct composite-PK
+ * rows that share their first key column collapse: one was wrongly marked
+ * "Already linked" and its button disabled, making a real target unpickable.
+ *
+ * Falls back to the junction's target columns when the target declares no primary
+ * key, which is the only identity available in that case.
+ */
+export declare function m2mTargetIdentityColumns(target: Table, m2m: ManyToManyJoin): string[];
 /**
  * Build the target-list query used when adding a many-to-many link.
  * Sort values are BifrostQL enum literals, so they must not be quoted.
+ *
+ * When `search` is non-empty the list is filtered server-side (a `_contains` on
+ * the label column) so a large target table stays findable beyond the fetch
+ * limit, instead of searching only within a client-side window.
  */
-export declare function m2mTargetPickerPlan(target: Table, m2m: ManyToManyJoin): M2mTargetPickerPlan;
+export declare function m2mTargetPickerPlan(target: Table, m2m: ManyToManyJoin, search?: string): M2mTargetPickerPlan;
 /**
  * Read the target row's id and display label from a junction row's nested target
  * selection (emitted by {@link m2mRowsQuery}). Returns null when the link has no
@@ -53,9 +85,16 @@ export declare function targetDisplay(junctionRow: Record<string, unknown>, m2m:
  * the chosen target key on the junction target FK. Any payload columns are left
  * unset so the database applies its defaults; the user edits them afterwards.
  *
- * Single-column junction FKs only. `parentId`/`targetId` are route-encoded
- * strings; for a composite FK they carry multiple values joined by "::", which
- * would be written verbatim into one column — silent data corruption. Rather
- * than guess a decomposition, fail loudly until composite-FK support is built.
+ * Single-column junction FKs only. `parentId` is a route-encoded string
+ * (produced by rowIdOf/encodePkRoute); for a composite FK it carries multiple
+ * values joined by "::", which would be written verbatim into one column —
+ * silent data corruption. Rather than guess a decomposition, fail loudly until
+ * composite-FK support is built.
+ *
+ * The parent value is percent-DECODED before being written: the read side
+ * (m2mRowsQuery) decodes the route id before filtering, so writing the encoded
+ * form (e.g. 'caf%C3%A9' for a 'café' key) would insert a dangling FK that the
+ * panel's filter never matches. `targetId` is NOT route-encoded — it comes raw
+ * from the picker row — so it is written as-is.
  */
 export declare function attachJunctionDetail(m2m: ManyToManyJoin, parentId: string, targetId: string): Record<string, unknown>;