@standardbeagle/edit-db 0.4.494 → 0.4.583

package/dist/lib/query-builder.d.ts

@@ -1,10 +1,17 @@
-import { Table, Join, Schema } from '../types/schema';
+import { Table, Column, Join, SchemaContextValue } from '../types/schema';
 import { ColumnFiltersState } from '@tanstack/react-table';
-import { PkEqFilterResult } from './row-id';
+import { PkEqFilterResult, PkFilter } from './row-id';
 export interface FilterResult {
     variables: Record<string, unknown>;
     param: string;
     filterText: string;
+    /**
+     * Non-null when the filter could not be built. The predicate is NOT part of
+     * the query, so the caller MUST refuse to run it rather than showing rows the
+     * filter was supposed to exclude. `null` with an empty `filterText` means
+     * "no filter requested", which is a different thing entirely.
+     */
+    error: string | null;
 }
 export interface ColumnFilterValue {
     operator: string;
@@ -14,6 +21,12 @@ export interface ColumnFilterResult {
     variables: Record<string, unknown>;
     params: string[];
     filterTexts: string[];
+    /**
+     * One message per column filter that could not be turned into a predicate.
+     * Non-empty means the built predicate is NARROWER than what the UI is showing
+     * as active, so the caller must refuse the query instead of returning rows.
+     */
+    errors: string[];
 }
 export interface PkTypeInfo {
     name: string;
@@ -26,11 +39,62 @@ interface RowData {
 export declare function isGraphQlName(value: unknown): value is string;
 export declare function assertGraphQlName(value: unknown, kind: string): asserts value is string;
 export declare function getFilterOperators(paramType: string): string[];
-export declare function getFilterObj(filterString: string): FilterResult;
-export declare function toLocaleDate(d: string): string;
-export declare function getRowPkValue(row: RowData, table: Table, index?: number): string;
+/**
+ * Parses the header filter (a JSON `[column, operator, value, type]` tuple carried
+ * in the `filter` URL param) into a GraphQL predicate.
+ *
+ * A rejected filter reports an error rather than degrading to "no filter". Silently
+ * dropping it left the grid showing the UNFILTERED table while the filter UI still
+ * advertised the predicate as active — and select-all + Delete then operated over a
+ * result set that was not the one the user believed they had narrowed to.
+ */
+export declare function parseTableFilterString(filterString: string): FilterResult;
+export declare function getRowPkValue(row: RowData, table: Table, rowIndex?: number): string;
+/**
+ * The GraphQL type a filter/lookup VARIABLE must be declared as for a column of
+ * this paramType. It has to be the column's own scalar: the variable is used in a
+ * `FilterType<T>Input` field position, and GraphQL rejects any variable whose
+ * declared type is not that exact scalar — "Variable '$cf_x_0' of type 'String'
+ * used in position expecting type 'DateTime'" fails the WHOLE document, so one
+ * mistyped column empties the grid rather than degrading that one predicate.
+ *
+ * BigInt/Decimal values travel as decimal STRINGS (coerceForGql's default branch
+ * stringifies): a JSON number is a double, which rounds a bigint key past 2^53 and
+ * drops exact-decimal precision. The server's BigInt/Decimal scalars accept the
+ * string form for exactly this reason — see ExactNumericScalars.cs.
+ */
 export declare function getGraphQlType(paramType: string): string;
+/**
+ * Widens a date-only bound ("2024-02-01") to the instant at the requested edge of
+ * that LOCAL day, in the ISO-8601 form the server's DateTime/DateTimeOffset scalars
+ * require.
+ *
+ * The date filter's control is `<input type="date">`, so its value carries no time
+ * — but the column it filters is a timestamp. Sent verbatim the value is not
+ * ISO-8601-complete and the scalar rejects it outright; sent as midnight it silently
+ * means "the first instant of the day", so "on or before 1 Feb" excludes everything
+ * recorded ON 1 Feb. Each operator therefore takes the edge that makes it true for
+ * the whole day.
+ */
+export declare function dayBoundary(date: string, edge: "start" | "end", gqlType: string, offsetMinutes?: number): string;
+/**
+ * The wire form of one column filter: the operator actually emitted and its
+ * value(s). Everything passes through unchanged except a date-only bound on a
+ * timestamp column, where the operator may widen to a day RANGE (`_eq` on a
+ * timestamp column matches nothing otherwise — no row is recorded at exactly
+ * midnight).
+ */
+export declare function toWireFilter(operator: string, value: unknown, gqlType: string, offsetMinutes?: number): {
+    operator: string;
+    value: unknown;
+};
 export declare function buildColumnFilters(columnFilters: ColumnFiltersState, table: Table): ColumnFilterResult;
+/**
+ * Every reason the requested filters could not be fully applied, header filter
+ * first. Empty means the built predicate matches exactly what the filter UI is
+ * advertising, which is the only condition under which the grid query may run.
+ */
+export declare function collectFilterErrors(table: Table, filterString: string, columnFilters: ColumnFiltersState): string[];
 export declare function serializeColumnFilters(columnFilters: ColumnFiltersState): string;
 export declare function deserializeColumnFilters(raw: string): ColumnFiltersState;
 /**
@@ -42,6 +106,17 @@ export declare function getPkType(table: Table): string;
  * Empty array if the table has no primary keys.
  */
 export declare function getPkTypes(table: Table): PkTypeInfo[];
+/**
+ * Picks the best index-served sort column for a table with no usable primary
+ * key: the leading key column of the clustered index if any (it IS the row
+ * order — sorting by it is free), else of a unique index, else of any index.
+ * Only sortable columns qualify — an index leading on a LOB/JSON column can't
+ * drive the grid's ORDER BY. Returns null when no index leads on a sortable,
+ * visible column; the caller falls back to its positional heuristic. Sorting a
+ * large table by an unindexed column re-sorts every row on every page turn, so
+ * this choice is a correctness-of-experience matter, not a micro-optimization.
+ */
+export declare function pickIndexedSortColumn(table: Table, isSortable?: (col: Column) => boolean): string | null;
 /**
  * Builds the variables dict that accompanies a buildQuery result for a single-record lookup.
  * - Single PK: returns `{ id: <coerced value> }` matching the `$id` variable in the query.
@@ -58,7 +133,39 @@ export declare function buildPkEqVariables(idRoute: string, table: Table): Recor
  * row fresh before echoing it back in an update.
  */
 export declare function buildSingleRowQuery(table: Pick<Table, 'name'>, pkEq: Pick<PkEqFilterResult, 'filterText' | 'params'>, fields: readonly string[]): string;
-export declare function buildQuery(table: Table, schema: Schema, filterString: string, columnFilters: ColumnFiltersState, id?: string, tableFilter?: string, filterColumn?: string): string | null;
+/**
+ * Builds ONE query fetching fresh snapshots of several rows by primary key —
+ * `{or: [pkEq, pkEq, ...]}` — so a bulk edit can echo current server state for
+ * every selected row in a single round trip (the multi-row analogue of
+ * {@link buildSingleRowQuery}'s fresh re-read). Rows come back under the `value`
+ * alias. Every key column of every row participates (composite-safe), values
+ * coerce through the same GraphQL-type rules as single-row PK filters (BigInt
+ * keys stay strings), and identifiers are asserted before any text is built.
+ */
+export declare function buildRowsByPkQuery(table: Pick<Table, 'name' | 'primaryKeys' | 'columns'>, pks: readonly PkFilter[], fields: readonly string[]): {
+    query: string;
+    variables: Record<string, unknown>;
+} | null;
+/**
+ * Columns included in a full-data export: every column EXCEPT binary payloads
+ * (non-PK), which have no useful CSV/JSON representation. Long-text columns ARE
+ * included — export means the full data, not the grid's preview projection.
+ * Single source of truth for export headers, fields, and the export query's
+ * SELECT list so the three cannot drift.
+ */
+export declare function exportableColumns(table: Table): Column[];
+export interface BuildQueryOptions {
+    /**
+     * `grid` (default): the on-screen projection — large values excluded, FK label
+     * blocks and multi-join count/preview blocks included.
+     * `export`: the full-data projection — every exportable scalar column (long
+     * text included, binary excluded), and NO join/multi-join blocks: exports
+     * project scalar fields only, so fetching label/preview blocks for every row
+     * would be pure transfer waste.
+     */
+    fields?: 'grid' | 'export';
+}
+export declare function buildQuery(table: Table, schema: SchemaContextValue, filterString: string, columnFilters: ColumnFiltersState, id?: string, filterTable?: string, filterColumn?: string, options?: BuildQueryOptions): string | null;
 export interface DrillDownTarget {
     /** The parent table whose row owns the child collection. */
     parentTable: Table;
@@ -79,8 +186,8 @@ export interface DrillDownTarget {
 export declare function canFlatFilterDrill(childJoin: Join): boolean;
 /**
  * Resolve the parent table + child collection field for a parent→child
- * related-records drill-down. The child is `table`; the parent is `tableFilter`
- * (or the destination of `table`'s single-join named `tableFilter` when the
+ * related-records drill-down. The child is `table`; the parent is `filterTable`
+ * (or the destination of `table`'s single-join named `filterTable` when the
  * relationship is described from the child side). `filterColumn` (the child
  * destination column) disambiguates when the parent has several multi-joins to
  * the same child. Returns `null` when no parent multi-join targets the child —
@@ -100,5 +207,5 @@ export interface PagedResult {
  * parent row was not found (no children / unknown id).
  */
 export declare function unwrapDrillDownPage(response: Record<string, unknown> | null | undefined, parentField: string, childField: string): PagedResult;
-export declare function resolveDrillDown(table: Table, schema: Schema, tableFilter?: string, filterColumn?: string): DrillDownTarget | null;
+export declare function resolveDrillDown(table: Table, schema: SchemaContextValue, filterTable?: string, filterColumn?: string): DrillDownTarget | null;
 export {};

package/dist/lib/row-id.d.ts

@@ -26,5 +26,16 @@ export declare function rowIdOf(row: Record<string, unknown> | null | undefined,
 export declare function pkFilterFor(row: Record<string, unknown> | null | undefined, table: TableLike): PkFilter | null;
 export declare function buildPkEqFilter(row: Record<string, unknown> | null | undefined, table: Pick<Table, 'primaryKeys' | 'columns'>): PkEqFilterResult | null;
 export declare function encodePkRoute(filter: PkFilter, table: TableLike): string;
+/**
+ * Parses a route-encoded id back into a PK filter, or null when the route cannot
+ * key a row.
+ *
+ * An EMPTY segment is a parse failure, not a null key value. Primary-key columns
+ * are non-nullable, so `{line_id: null}` can never match a stored row — but it is
+ * a structurally valid filter, so callers guarding on "did the key resolve?"
+ * (see `pkResolveFailed` in data-edit.tsx) saw success, queried, matched zero
+ * rows, and then wrote an all-columns-blank UPDATE back. Returning null here is
+ * the established failure shape every caller already handles.
+ */
 export declare function parsePkRoute(raw: string, table: TableLike): PkFilter | null;
 export {};

package/dist/lib/rows-by-pk-query.test.d.ts

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

package/dist/lib/scalar-types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One place that classifies a column's GraphQL scalar (`paramType`).
+ *
+ * The type mappers can emit Int, Short, Byte, BigInt, Decimal, Float, Boolean,
+ * DateTime, DateTimeOffset, JSON and String. Every surface that reasoned about
+ * types used to carry its own `['Int', 'Float']` list, so the four less common
+ * numeric scalars and the second timestamp scalar were each handled by whichever
+ * surfaces happened to remember them: a smallint column could not be filtered from
+ * the grid header, was not validated as a number in a form, and was sent as a
+ * string on write (which its `Short!` input rejects). Classifying in one module is
+ * what keeps those surfaces from drifting apart again.
+ */
+/** Strips the non-null marker: `Int!` -> `Int`. */
+export declare function baseParamType(paramType: string | undefined): string;
+/** Whole-number columns — they reject a fractional value. */
+export declare function isIntegerScalar(paramType: string | undefined): boolean;
+/** Any numeric column, whole or fractional. */
+export declare function isNumericScalar(paramType: string | undefined): boolean;
+/** Columns whose value must never be routed through a JS number. */
+export declare function isExactScalar(paramType: string | undefined): boolean;
+/** DateTime and DateTimeOffset — the columns whose bounds are instants. */
+export declare function isTimestampScalar(paramType: string | undefined): boolean;
+export declare function isBooleanScalar(paramType: string | undefined): boolean;
+export declare function isStringScalar(paramType: string | undefined): boolean;
+/**
+ * Validates numeric text and returns the value to send: the digits unchanged for
+ * an exact column, otherwise a number. Null means "not (yet) a complete numeric
+ * literal", which callers read as "no value", never as zero.
+ */
+export declare function parseScalarNumber(raw: string, paramType: string | undefined): number | string | null;

package/dist/lib/scalar-types.test.d.ts

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

package/dist/lib/table-action.d.ts

@@ -0,0 +1,24 @@
+import { ComponentType } from 'react';
+import { Table } from '../types/schema';
+/**
+ * A host-contributed action on a TABLE in the navigation list. The editor renders
+ * every action in each table's kebab menu; what the action does is entirely the
+ * host's business (open a query designer, copy a connection string, …) — edit-db
+ * stays transport- and host-agnostic and just invokes the callback with the
+ * schema table. Built-in actions (Download CSV/JSON) use this same shape, so a
+ * host's contributions and the built-ins render as one uniform menu.
+ */
+export interface TableAction {
+    /** Stable identity, e.g. `edit-as-query`. */
+    id: string;
+    /** Menu item label. */
+    label: string;
+    /** Optional 16px icon component (lucide-style: takes className). */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Hides the action for tables it does not apply to. Absent means always shown. */
+    enabled?: (table: Table) => boolean;
+    /** Invoked with the schema table when the user picks the action. */
+    onSelect: (table: Table) => void | Promise<void>;
+}

package/dist/{tableList.d.ts → table-list.d.ts}

@@ -4,7 +4,7 @@
  * Scales to several hundred tables:
  * - Search filters by label, raw db name, and schema.
  * - Tables group under collapsible schema headers (only when >1 schema exists).
- * - The visible rows (headers + tables) are paged at {@link PAGE_SIZE} so the DOM
+ * - The visible rows (headers + tables) are paged at {@link TABLE_LIST_PAGE_SIZE} so the DOM
  *   stays small regardless of total table count.
  *
  * @component

package/dist/table-view.chart.test.d.ts

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

package/dist/table-view.d.ts

@@ -0,0 +1,22 @@
+import { Table } from './types/schema';
+import { DrillFrame } from './lib/drill-stack';
+import { ColumnFiltersState } from '@tanstack/react-table';
+interface TableViewParams {
+    table: Table;
+    id?: string;
+    filterTable?: string;
+    filterColumn?: string;
+    selectedRowId?: string | null;
+    onRowSelect?: (rowId: string | null) => void;
+    onOpenColumn?: (panel: DrillFrame) => void;
+    /** Current stacking (parent/child drill-down) mode state. */
+    stackingEnabled?: boolean;
+    /** Toggle stacking mode. When supplied, the grid renders the mode toggle. */
+    onToggleStacking?: (next: boolean) => void;
+}
+/** Converts the already schema-validated grid filter state into GraphQL input
+ * variables. No identifier text is accepted from the UI: columns are looked up
+ * in the current schema and operators are validated by the shared builder. */
+export declare function chartFilter(filters: ColumnFiltersState, table: Table): Record<string, unknown> | undefined;
+export declare function TableView({ table, id, filterTable, filterColumn, selectedRowId, onRowSelect, onOpenColumn, stackingEnabled, onToggleStacking }: TableViewParams): JSX.Element;
+export {};

package/dist/types/schema.d.ts

@@ -57,16 +57,31 @@ export interface Column {
     isReadOnly: boolean;
     /** Custom metadata for the column */
     metadata: ColumnMetadata;
+    /**
+     * Dialect-decided LOB semantics from the server: true when the value may be
+     * arbitrarily large and should be fetched on demand. Authoritative over any
+     * dbType-name guess (Postgres text / SQLite TEXT are ordinary strings).
+     * Optional only for servers that predate the field.
+     */
+    isLargeValue?: boolean;
     /** Maximum string length (for validation) */
     maxLength?: number;
     /** Minimum string length (for validation) */
     minLength?: number;
-    /** Minimum numeric value (for validation) */
-    min?: number;
-    /** Maximum numeric value (for validation) */
-    max?: number;
+    /**
+     * Minimum bound (for validation). Numeric for number columns; an ISO date
+     * string for temporal columns — the server fills engine storable windows
+     * (SQL Server datetime >= 1753) when no metadata min is declared.
+     */
+    min?: number | string;
+    /** Maximum bound, same forms as min */
+    max?: number | string;
     /** Step increment for numeric inputs */
     step?: number;
+    /** Declared decimal precision from the database schema (null for non-decimal columns) */
+    precision?: number | null;
+    /** Declared decimal scale paired with precision */
+    scale?: number | null;
     /** Regex pattern for validation */
     pattern?: string;
     /** Error message for pattern validation failures */
@@ -75,10 +90,10 @@ export interface Column {
     inputType?: 'text' | 'email' | 'url' | 'tel' | 'date' | 'datetime-local' | 'number' | 'password' | 'search';
     /** Default value for new records */
     defaultValue?: string;
-    /** Allowed enum values */
-    enumValues?: string[];
-    /** Display labels for enum values */
-    enumLabels?: string[];
+    /** Allowed enum values. The server sends null, not undefined, for non-enum columns. */
+    enumValues?: string[] | null;
+    /** Display labels for enum values. Null for non-enum columns, as `enumValues` is. */
+    enumLabels?: string[] | null;
 }
 /**
  * Relationship join definition between tables.
@@ -161,12 +176,32 @@ export interface Table {
     singleJoins: Join[];
     /** Many-to-many bridges through junction tables (optional; absent on older servers). */
     manyToManyJoins?: ManyToManyJoin[];
+    /** Database indexes (optional; absent on older servers). */
+    indexes?: TableIndex[];
+}
+/**
+ * A database index on a table, key columns in key order (GraphQL names).
+ * Lets the grid pick a default sort an index can serve — sorting a large
+ * table by an unindexed column re-sorts every row on every page.
+ * @interface TableIndex
+ */
+export interface TableIndex {
+    /** Index name in the database catalog. */
+    name: string;
+    /** True when the index enforces uniqueness (includes PK indexes). */
+    isUnique: boolean;
+    /** True when the index defines the physical row order — the cheapest sort. */
+    isClustered: boolean;
+    /** True when the index backs the primary key constraint. */
+    isPrimaryKey: boolean;
+    /** Key column GraphQL names in key order; the leading column can be sorted for free. */
+    columns: string[];
 }
 /**
  * Schema context value containing database metadata and loading state.
- * @interface Schema
+ * @interface SchemaContextValue
  */
-export interface Schema {
+export interface SchemaContextValue {
     /** Whether schema data is currently loading */
     loading: boolean;
     /** Error object if schema loading failed, null otherwise */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardbeagle/edit-db",
   "private": false,
-  "version": "0.4.494",
+  "version": "0.4.583",
   "type": "module",
   "dependencies": {
     "@radix-ui/react-slot": "^1.2.4",
@@ -39,7 +39,7 @@
     "storybook": "^10.4.1",
     "tailwindcss": "^4.3.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.5",
+    "vite": "^7.3.6",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.1.8"
   },

package/dist/common/schema.d.ts

@@ -1,2 +0,0 @@
-export declare const GET_SCHEMA = "{\n    schema: __schema {\n      queryType {\n        fields {\n          name\n          type {\n            fields {\n              name\n              type {\n                ofType {\n                  fields {\n                    name\n                    type {\n                      kind\n                      ofType {\n                        name\n                      }\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n  ";
-export declare const GET_DB_SCHEMA = "\nquery dbSchema {\n  _dbSchema {\n    dbName\n    graphQlName\n    labelColumn\n    primaryKeys\n    isEditable\n    metadata {\n      key\n      value\n    }\n    columns {\n      dbName\n      graphQlName\n      paramType\n      dbType\n      isPrimaryKey\n      isIdentity\n      isNullable\n      isReadOnly\n      maxLength\n      minLength\n      min\n      max\n      step\n      pattern\n      patternMessage\n      inputType\n      defaultValue\n      enumValues\n      enumLabels\n      metadata {\n        key\n        value\n      }\n    }\n    multiJoins {\n      name\n      fieldName\n      sourceColumnNames\n      destinationTable\n      destinationColumnNames\n    }\n    singleJoins {\n      name\n      fieldName\n      sourceColumnNames\n      destinationTable\n      destinationColumnNames\n    }\n    manyToManyJoins {\n      name\n      targetTable\n      junctionTable\n      junctionTargetField\n      sourceColumnNames\n      junctionSourceColumnNames\n      junctionTargetColumnNames\n      targetColumnNames\n      hasPayload\n    }\n  }\n}";

package/dist/data-data-table.d.ts

@@ -1,17 +0,0 @@
-import { Table } from './types/schema';
-import { ColumnPanel } from './data-panel';
-interface DataDataTableParams {
-    table: Table;
-    id?: string;
-    tableFilter?: string;
-    filterColumn?: string;
-    selectedRowId?: string | null;
-    onRowSelect?: (rowId: string | null) => void;
-    onOpenColumn?: (panel: ColumnPanel) => void;
-    /** Current stacking (parent/child drill-down) mode state. */
-    stackingEnabled?: boolean;
-    /** Toggle stacking mode. When supplied, the grid renders the mode toggle. */
-    onToggleStacking?: (next: boolean) => void;
-}
-export declare function DataDataTable({ table, id, tableFilter, filterColumn, selectedRowId, onRowSelect, onOpenColumn, stackingEnabled, onToggleStacking }: DataDataTableParams): JSX.Element;
-export {};