@standardbeagle/edit-db 0.4.494 → 0.4.581

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

@@ -15,6 +15,19 @@ export declare function coerceForGql(value: unknown, gqlType: string): unknown;
 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;
 /**
  * Build a `{_eq}`-per-column composite filter against the destination side of a join,

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/m2m.d.ts

@@ -31,11 +31,36 @@ 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.

package/dist/lib/mutation-payload.d.ts

@@ -0,0 +1,37 @@
+import { Column, Table } from '../types/schema';
+import { PkFilter } from './row-id';
+export declare function coerceNumericValue(value: unknown, paramType: string, columnName: string): number;
+export interface ColumnJoin {
+    column: Column;
+}
+/**
+ * Coerces a form/grid detail object into a wire-ready mutation payload: numeric
+ * columns become numbers, BigInt/Decimal stay strings (precision beyond 2^53),
+ * booleans and JSON columns get their scalar shapes, empty values follow the
+ * insert-vs-update semantics (omit so DB defaults apply vs null to clear), and —
+ * for updates — the primary-key columns are overwritten from the resolved
+ * <paramref>pkFilter</paramref> so a payload can never retarget another row.
+ * Shared by the single-row hook and the bulk delta paths.
+ */
+export declare function coerceDetail(detail: Record<string, unknown>, editColumns: ColumnJoin[], idColumns: Column[], pkFilter: PkFilter | null, isInsert: boolean): Record<string, unknown>;
+/**
+ * Builds the `updated:` payload list for a bulk edit: for each FRESH row
+ * snapshot, echo every write-set column from the snapshot (the server's
+ * `Update_<t>` input requires all non-nullable columns), overlay the shared
+ * change set, validate, and coerce — with the primary key taken from the
+ * snapshot itself, composite-safe, so a payload can never retarget another row.
+ * Throws (never silently skips) when a row's key cannot be resolved or a merged
+ * payload fails validation: a bulk edit either stages every selected row or none.
+ */
+export declare function buildBulkUpdatePayloads(table: Pick<Table, 'primaryKeys'>, writeColumns: Column[], idColumns: Column[], freshRows: readonly Record<string, unknown>[], changes: Record<string, unknown>): Record<string, unknown>[];
+/**
+ * Builds the `updated:` payload list for STAGED inline cell edits: unlike the
+ * shared-change bulk edit, each row carries its OWN change map. Per fresh row:
+ * the write set is every non-nullable editable column plus that row's changed
+ * columns (the server's `Update_<t>` input requires the non-nullable echo), the
+ * snapshot fills the echo, the row's changes overlay it, and the primary key
+ * comes from the snapshot itself. Throws — never skips — when a fetched row has
+ * no staged changes or a merged payload fails validation: Save all either
+ * stages every edited row or none.
+ */
+export declare function buildStagedUpdatePayloads(table: Pick<Table, 'primaryKeys'>, editableColumns: Column[], idColumns: Column[], freshRows: readonly Record<string, unknown>[], changesForRow: (row: Record<string, unknown>) => Record<string, unknown> | undefined): Record<string, unknown>[];

package/dist/lib/mutation-payload.test.d.ts

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