@standardbeagle/edit-db 0.4.478 → 0.4.494

package/dist/hooks/useCompositeTableRef.d.ts

@@ -10,10 +10,28 @@ export interface CompositeTableRef {
     loading: boolean;
     error: unknown;
     data: CompositeTableRefValue[];
+    /** True when `search` narrows server-side (String label column, `_contains`);
+     *  false means the caller must filter the fetched window client-side. */
+    serverSearch: boolean;
+}
+export interface CompositeTableRefOptions {
+    /** Free-text search term. Applied server-side when the label column is String. */
+    search?: string;
+    /** Defer the list fetch until the dropdown is opened (fetch-on-open). */
+    enabled?: boolean;
+    /** The currently-selected destination-column values, so the selected parent row
+     *  can be looked up and shown even when it falls outside the fetched window. */
+    currentValues?: Record<string, unknown> | null;
 }
 /**
  * Fetch parent rows for a composite-FK Select widget. Returns one row per parent
  * with its label plus every destination column value so the caller can write
  * each composite-FK source column on the child form when a selection is made.
+ *
+ * Mirrors the single-column FK data source (table-ref.ts / useTableRef +
+ * useTableRefValue): the window is sorted by the label column (deterministic),
+ * narrowed server-side when a search term is given and the label is String-typed,
+ * and the currently-selected row is resolved via a single-row lookup when it lies
+ * outside the fetched window so it stays selectable instead of showing blank.
  */
-export declare function useCompositeTableRef(schema: Schema, destTableName: string, destColumnNames: string[]): CompositeTableRef;
+export declare function useCompositeTableRef(schema: Schema, destTableName: string, destColumnNames: string[], options?: CompositeTableRefOptions): CompositeTableRef;

package/dist/hooks/useCompositeTableRef.test.d.ts

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

package/dist/hooks/useDataTable.d.ts

@@ -7,13 +7,25 @@ interface RowData {
     id?: number | string;
     [key: string]: unknown;
 }
+export declare function getJoinedRowPkValue(row: RowData | undefined, joinSchema: Table | undefined): string;
 /**
  * Clamp a page index into the valid [0, pageCount-1] range. Guards against a
  * stale/out-of-range page (e.g. "page 2 of 1" after switching to a smaller
  * table or when the row count shrinks).
  */
 export declare function clampPageIndex(pageIndex: number, pageCount: number): number;
+/**
+ * Reconcile in-memory column-filter state with the URL `cf` param, which is the
+ * source of truth. Returns `prev` unchanged when it already serializes to the
+ * same string as `cfParam` — this both preserves referential identity (no
+ * needless re-render) and stops the setState → syncFiltersToUrl → cfParam →
+ * effect cycle from looping on our own writes. Otherwise it deserializes the URL
+ * value so browser back/forward and table switches (which drop the query string)
+ * drive the filters instead of leaving stale state behind.
+ */
+export declare function reconcileColumnFiltersFromUrl(prev: ColumnFiltersState, cfParam: string): ColumnFiltersState;
 export declare function getMultiJoinRows(row: RowData, join: Join): RowData[];
+export declare function getMultiJoinTotal(row: RowData, join: Join): number;
 /**
  * Return type for the useDataTable hook.
  * @interface UseDataTableResult
@@ -35,7 +47,7 @@ interface UseDataTableResult {
     pageCount: number;
     /** Current page data rows */
     rows: RowData[];
-    /** Whether data is currently loading */
+    /** Whether data is currently loading (no rows to show yet) */
     loading: boolean;
     /** Error object if the query failed */
     error: Error | null;

package/dist/hooks/usePath.d.ts

@@ -23,10 +23,6 @@ interface SearchParamsResult {
     search: URLSearchParams;
     hash: string;
 }
-interface RouteError {
-    message?: string;
-    status?: number;
-}
 interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
     to: string;
     children?: ReactNode;
@@ -41,7 +37,6 @@ export declare function useNavigate(): (url: string) => void;
 export declare function useNavigation(): NavigationState;
 export declare function useParams<T extends RouteParams = RouteParams>(): T;
 export declare function useSearchParams(): SearchParamsResult;
-export declare function useRouteError(): RouteError;
 export declare function PathProvider({ path, children }: {
     path: string;
     children: ReactNode;
@@ -68,4 +63,5 @@ export declare function Route({ path, element }: {
     path: string;
     element: ReactElement;
 }): ReactElement;
+export declare const matchPath: (route: string, path: string) => PathMatch;
 export {};

package/dist/hooks/useTableRef.d.ts

@@ -1,5 +1,4 @@
 import { Schema } from '../types/schema';
-export declare function useTableRef(schema: Schema, tableName: string, columnName: string): TableRef;
 export interface TableRefValue {
     key: string;
     label: string;
@@ -8,4 +7,26 @@ export interface TableRef {
     loading: boolean;
     error: unknown;
     data: TableRefValue[];
+    /** True when `search` narrows server-side (String label column, `_contains`);
+     *  false means the caller must filter the fetched window client-side. */
+    serverSearch: boolean;
 }
+/**
+ * Fetch the option rows for an FK dropdown (key + label per parent row).
+ * When `search` is non-empty and the parent's label column is String-typed the
+ * list is narrowed server-side, so parents beyond the fetch window stay
+ * findable; otherwise one window is fetched and the caller filters it.
+ */
+export declare function useTableRef(schema: Schema, tableName: string, columnName: string, search?: string, enabled?: boolean): TableRef;
+export interface TableRefLookup {
+    loading: boolean;
+    error: unknown;
+    value: TableRefValue | null;
+}
+/**
+ * Resolve key + label for a single parent row by its key value. Used when the
+ * currently stored FK value falls outside the fetched dropdown window, so the
+ * Select can still display the stored value instead of a misleading
+ * placeholder. Pass `key` as null/'' to disable the lookup.
+ */
+export declare function useTableRefValue(schema: Schema, tableName: string, columnName: string, key: unknown): TableRefLookup;

package/dist/hooks/useTableRef.test.d.ts

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

package/dist/hooks/useTableStats.d.ts

@@ -33,6 +33,13 @@ export interface UseTableStatsResult {
         message: string;
     } | null;
 }
+/**
+ * Builds a GraphQL query to fetch row counts for all tables.
+ *
+ * @param tableNames - Array of table GraphQL names
+ * @returns GraphQL query string
+ */
+export declare function buildRowCountQuery(tableNames: string[]): string | null;
 /**
  * Hook to fetch table statistics including row counts.
  *

package/dist/hooks/useToast.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+/**
+ * Minimal dependency-free toast system for transient success/error feedback
+ * after mutations (create, save, delete, inline content edits). Kept small and
+ * self-contained so the published editor pulls in no extra runtime dependency.
+ */
+export type ToastVariant = 'success' | 'error';
+interface ToastApi {
+    toast: (message: string, variant?: ToastVariant) => void;
+}
+export declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useToast(): ToastApi;
+export {};

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

@@ -4,6 +4,11 @@ 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;
 /** Detect content kind from a string value and optional dbType hint */

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

@@ -1,13 +1,21 @@
-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;
 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/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

@@ -32,12 +32,19 @@ export declare function m2mRowsQuery(junction: Table, target: Table, m2m: ManyTo
 export interface M2mTargetPickerPlan {
     query: string;
     idColumn: 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;
 }
 /**
  * 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 +60,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>;

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

@@ -1,5 +1,6 @@
-import { Table, Schema } from '../types/schema';
+import { Table, Join, Schema } from '../types/schema';
 import { ColumnFiltersState } from '@tanstack/react-table';
+import { PkEqFilterResult } from './row-id';
 export interface FilterResult {
     variables: Record<string, unknown>;
     param: string;
@@ -22,10 +23,12 @@ interface RowData {
     id?: number | string | null;
     [key: string]: unknown;
 }
+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): string;
+export declare function getRowPkValue(row: RowData, table: Table, index?: number): string;
 export declare function getGraphQlType(paramType: string): string;
 export declare function buildColumnFilters(columnFilters: ColumnFiltersState, table: Table): ColumnFilterResult;
 export declare function serializeColumnFilters(columnFilters: ColumnFiltersState): string;
@@ -48,13 +51,32 @@ export declare function getPkTypes(table: Table): PkTypeInfo[];
  * it is a route-encoded string produced by {@link encodePkRoute}.
  */
 export declare function buildPkEqVariables(idRoute: string, table: Table): Record<string, unknown>;
+/**
+ * Builds a single-row lookup query keyed by a primary-key equality filter
+ * (produced by {@link buildPkEqFilter}). The row comes back under the `value`
+ * alias: `{ value: { data: [row] } }`. Used by the content panel to re-read a
+ * 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;
 export interface DrillDownTarget {
     /** The parent table whose row owns the child collection. */
     parentTable: Table;
     /** The child collection field name on the parent type. */
     childField: string;
+    /** The parent multi-join that owns the child collection. Lets callers
+     *  decide whether the drill can use a flat FK filter (simple single-column
+     *  FK) or must keep the MODEL B parent traversal (composite/polymorphic). */
+    childJoin: Join;
 }
+/**
+ * A drill can render as a flat root-filtered child grid — `childTable(filter:
+ * { fk: { _eq: $id } })`, i.e. a "parent grid with a filter applied" — only for
+ * a simple single-column, non-polymorphic FK. Composite FKs have no single
+ * filter column and polymorphic links need the server-injected discriminator;
+ * both must keep MODEL B's parent traversal.
+ */
+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`

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

@@ -6,6 +6,7 @@ export interface PkEqFilterResult {
     params: string[];
 }
 type TableLike = Pick<Table, 'primaryKeys'> & Partial<Pick<Table, 'columns'>>;
+export declare function decodePkPart(raw: string): string | null;
 /**
  * Encodes an ordered list of key values into a route string. The single source
  * of truth for composite-key route encoding — every producer (row lists) and
@@ -13,6 +14,14 @@ type TableLike = Pick<Table, 'primaryKeys'> & Partial<Pick<Table, 'columns'>>;
  * never drift apart and silently fail to match.
  */
 export declare function encodeRouteParts(values: readonly unknown[]): string;
+/**
+ * Inverse of {@link encodeRouteParts}: splits a route-encoded id into its ordered
+ * values and percent-decodes each. `expectedCount <= 1` treats the whole string as a
+ * single value (never split, so a value that itself contains the delimiter survives).
+ * Throws when a multi-part id does not carry exactly `expectedCount` parts, so a caller
+ * building a composite filter cannot silently under-constrain it.
+ */
+export declare function decodeRouteParts(raw: string, expectedCount: number): string[];
 export declare function rowIdOf(row: Record<string, unknown> | null | undefined, table: TableLike, index: number): string;
 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;

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

@@ -0,0 +1,45 @@
+import { Table } from '../types/schema';
+export declare const TABLE_REF_LIMIT = 1000;
+export declare const TABLE_REF_SEARCH_LIMIT = 50;
+/**
+ * The column used as the display label for a table's FK dropdown rows.
+ * Falls back to schema-derived names only — never a guessed literal like `id`,
+ * which is a server error on tables without such a column: first primary-key
+ * column, then the first column. (Taking the first PK column here is a label
+ * fallback for display, not a composite-key shortcut — one column is all a
+ * label can show.) `||` (not `??`) so an empty-string labelColumn falls
+ * through instead of emitting `label: ` (a GraphQL syntax error).
+ */
+export declare function refLabelColumn(table: Table): string;
+export interface TableRefPlan {
+    query: string;
+    labelColumn: 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;
+}
+/**
+ * Build the FK-dropdown list query. Sorted by the label column so the fetched
+ * window is deterministic. When `search` is non-empty and the label column is
+ * String-typed, the list is narrowed server-side (`_contains` on the label
+ * column) so parents beyond the fetch limit stay findable; otherwise the caller
+ * filters client-side over the fetched window.
+ */
+export declare function tableRefPlan(table: Table, keyColumn: string, search?: string): TableRefPlan;
+export interface TableRefLookupPlan {
+    query: string;
+    /** GraphQL type of the key column (non-null suffix stripped), for coercion. */
+    keyType: string;
+}
+/**
+ * Build the single-row lookup that resolves the label of the currently stored
+ * FK value when it falls outside the fetched dropdown window, so the Select can
+ * display it instead of a misleading placeholder.
+ */
+export declare function tableRefLookupPlan(table: Table, keyColumn: string): TableRefLookupPlan;
+/**
+ * Coerce a stored/route FK value to what the lookup's `$key` variable expects.
+ * Delegates to the shared coerceForGql so BigInt keys stay strings (Number()
+ * loses precision past 2^53) and Boolean keys stay booleans.
+ */
+export declare function coerceKeyValue(keyType: string, value: unknown): unknown;

package/dist/lib/table-ref.test.d.ts

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

package/dist/types/schema.d.ts

@@ -10,12 +10,9 @@
  */
 export interface TableMetadata {
     /** Lookup configuration for reference tables */
-    type?: {
-        type: 'lookup';
-        id: string;
-        label: string;
-    };
-    [key: string]: any;
+    type?: LookupMetadata;
+    /** Other free-form metadata entries keyed by metadata name (parsed from key/value pairs). */
+    [key: string]: string | LookupMetadata | undefined;
 }
 /**
  * Lookup table metadata defining ID and label columns.
@@ -98,6 +95,15 @@ export interface Join {
     destinationTable: string;
     /** Column names in the target table */
     destinationColumnNames: string[];
+    /** True for a polymorphic child link — the relation carries a server-side
+     *  discriminator predicate (entity_type) rather than a plain FK. Such drills
+     *  must keep the MODEL B parent traversal so the server injects the
+     *  discriminator; a flat FK filter would leak sibling-type rows. */
+    isPolymorphic?: boolean;
+    /** Discriminator column backing a polymorphic link (when isPolymorphic). */
+    polymorphicTypeColumn?: string;
+    /** Discriminator value backing a polymorphic link (when isPolymorphic). */
+    polymorphicTypeValue?: string;
 }
 /**
  * Many-to-many bridge between this entity and a target entity through a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardbeagle/edit-db",
   "private": false,
-  "version": "0.4.478",
+  "version": "0.4.494",
   "type": "module",
   "dependencies": {
     "@radix-ui/react-slot": "^1.2.4",
@@ -14,7 +14,6 @@
     "radix-ui": "^1.4.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "redux-actions": "^3.0.3",
     "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
@@ -27,7 +26,6 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^18.3.29",
     "@types/react-dom": "^18.3.7",
-    "@types/redux-actions": "^2.6.5",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "@vitejs/plugin-react-swc": "^4.3.1",

package/dist/error-panel.d.ts

@@ -1 +0,0 @@
-export default function ErrorPage(): import("react").JSX.Element;