@standardbeagle/edit-db 0.3.229 → 0.4.327

package/dist/hooks/useColumnNav.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+import { ColumnPanel } from '../data-panel';
+interface ColumnNavEntry {
+    panel: ColumnPanel;
+    element: HTMLElement | null;
+}
+interface ColumnNavState {
+    mainTable: string | null;
+    columns: ColumnNavEntry[];
+    focusedIndex: number;
+    focusColumn: (index: number) => void;
+    closeColumn: (index: number) => void;
+}
+interface ColumnNavRegistration {
+    mainTable: string | null;
+    columns: ColumnPanel[];
+    columnRefs: Map<number, HTMLElement | null>;
+    onClose: (index: number) => void;
+}
+export declare function ColumnNavProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useColumnNav(): ColumnNavState;
+export declare function useColumnNavRegister(): {
+    register: (reg: ColumnNavRegistration) => void;
+    unregister: () => void;
+};
+export {};

package/dist/hooks/useDataTable.d.ts

@@ -1,21 +1,72 @@
 import { Table } from '../types/schema';
-import { ColumnDef, SortingState } from '@tanstack/react-table';
+import { ColumnDef, ColumnFiltersState, SortingState } from '@tanstack/react-table';
+import { ColumnPanel } from '../data-panel';
+export { getFilterOperators } from '../lib/query-builder';
+export type { ColumnFilterValue } from '../lib/query-builder';
 interface RowData {
     id?: number | string;
     [key: string]: unknown;
 }
+/**
+ * Return type for the useDataTable hook.
+ * @interface UseDataTableResult
+ */
 interface UseDataTableResult {
+    /** Column definitions for the table */
     columns: ColumnDef<RowData, unknown>[];
+    /** Current sorting state */
     sorting: SortingState;
+    /** Active column filters */
+    columnFilters: ColumnFiltersState;
+    /** Primary-key column names in declaration order (empty when the table has no PK). */
+    primaryKeys: string[];
+    /** Current page index (0-based) */
     pageIndex: number;
+    /** Number of rows per page */
     pageSize: number;
+    /** Total number of pages */
     pageCount: number;
+    /** Current page data rows */
     rows: RowData[];
+    /** Whether data is currently loading */
     loading: boolean;
+    /** Error object if the query failed */
     error: Error | null;
+    /** Update sorting state */
     onSortingChange: (sorting: SortingState) => void;
+    /** Update column filters */
+    onColumnFiltersChange: (filters: ColumnFiltersState) => void;
+    /** Update page index */
     onPageIndexChange: (pageIndex: number) => void;
+    /** Update page size */
     onPageSizeChange: (pageSize: number) => void;
 }
-export declare function useDataTable(table: Table | null, id?: string, filterTable?: string): UseDataTableResult;
-export {};
+/**
+ * Hook for managing data table state including sorting, filtering, and pagination.
+ *
+ * Automatically builds GraphQL queries based on table schema and current state,
+ * handles data fetching via React Query, and provides column definitions with
+ * proper rendering for foreign keys, dates, and content fields.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   columns,
+ *   rows,
+ *   loading,
+ *   pageIndex,
+ *   pageCount,
+ *   onSortingChange,
+ *   onPageIndexChange,
+ * } = useDataTable(table, recordId, parentTable);
+ * ```
+ *
+ * @param table - Table schema definition
+ * @param id - Optional record ID for filtering to a specific row
+ * @param filterTable - Optional parent table name for relationship filtering
+ * @param filterColumn - Optional column name for explicit FK filtering
+ * @param onExpandContent - Callback when content expansion is requested
+ * @param onOpenColumn - Callback when opening a side panel column
+ * @returns Data table state and control functions
+ */
+export declare function useDataTable(table: Table | null, id?: string, filterTable?: string, filterColumn?: string, onExpandContent?: (rowIndex: number, columnName: string) => void, onOpenColumn?: (panel: ColumnPanel) => void): UseDataTableResult;

package/dist/hooks/useDeleteMutation.d.ts

@@ -0,0 +1,10 @@
+import { Table } from '../types/schema';
+import { PkFilter } from '../lib/row-id';
+export type DeleteInput = PkFilter | string | number;
+export interface UseDeleteMutationResult {
+    deleteRow: (detail: DeleteInput) => Promise<unknown>;
+    deleteRows: (details: DeleteInput[]) => Promise<unknown>;
+    isPending: boolean;
+    error: Error | null;
+}
+export declare function useDeleteMutation(table: Table): UseDeleteMutationResult;

package/dist/hooks/useSchema.d.ts

@@ -1,6 +1,31 @@
 import { ReactNode } from 'react';
 import { Schema } from '../types/schema';
+/**
+ * Provider component for database schema context.
+ * Fetches schema via GraphQL and makes it available to child components.
+ *
+ * @example
+ * ```tsx
+ * <SchemaProvider>
+ *   <YourApp />
+ * </SchemaProvider>
+ * ```
+ */
 export declare const SchemaProvider: ({ children }: {
     children: ReactNode;
 }) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the database schema context.
+ *
+ * Returns schema loading state, error information, table definitions,
+ * and a utility function to find tables by name.
+ *
+ * @example
+ * ```tsx
+ * const { loading, error, data, findTable } = useSchema();
+ * const userTable = findTable('users');
+ * ```
+ *
+ * @returns Schema context value with tables and metadata
+ */
 export declare function useSchema(): Schema;

package/dist/hooks/useTableStats.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Interface representing statistics for a single table.
+ * @interface TableStats
+ */
+export interface TableStats {
+    /** Number of columns in the table */
+    columnCount: number;
+    /** Number of rows in the table (null if loading/error) */
+    rowCount: number | null;
+    /** Number of foreign key relationships (singleJoins) */
+    fkCount: number;
+    /** Whether row count is currently loading */
+    isLoading: boolean;
+    /** Error message if row count fetch failed */
+    error: string | null;
+}
+/**
+ * Type for table stats record keyed by table name.
+ * @type TableStatsMap
+ */
+export type TableStatsMap = Record<string, TableStats>;
+/**
+ * Result type for the useTableStats hook.
+ * @interface UseTableStatsResult
+ */
+export interface UseTableStatsResult {
+    /** Map of table names to their stats */
+    stats: TableStatsMap;
+    /** Whether any stats are loading */
+    isLoading: boolean;
+    /** Error if schema loading failed */
+    error: {
+        message: string;
+    } | null;
+}
+/**
+ * Hook to fetch table statistics including row counts.
+ *
+ * Automatically fetches row counts for all tables in the schema.
+ * Column counts and FK counts are derived from schema metadata (synchronous).
+ * Row counts are fetched via GraphQL (asynchronous).
+ *
+ * @example
+ * ```tsx
+ * const { stats, isLoading } = useTableStats();
+ * const customerStats = stats['customers'];
+ * // customerStats = { columnCount: 12, rowCount: 1250, fkCount: 3, isLoading: false, error: null }
+ * ```
+ *
+ * @returns Table statistics map and loading state
+ */
+export declare function useTableStats(): UseTableStatsResult;
+/**
+ * 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;
+/**
+ * Calculates a visual bar width (1-10) based on row count.
+ * Used for sparkline visualization.
+ *
+ * @param count - Row count
+ * @param maxCount - Maximum row count across all tables for scaling
+ * @returns Width value from 1-10
+ */
+export declare function calculateBarWidth(count: number | null, maxCount: number): number;

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

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

package/dist/lib/composite-pk-roundtrip.test.d.ts

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

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

@@ -0,0 +1,14 @@
+/** Detected content type for smart rendering */
+export type ContentKind = 'json' | 'xml' | 'php-serialized' | 'binary' | 'longtext' | 'text';
+/** Check if a dbType is a binary/blob type */
+export declare function isBinaryDbType(dbType: 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 */
+export declare function detectContentKind(value: string, dbType?: string): ContentKind;
+/** Max characters to show in a table cell before truncating */
+export declare const CELL_TRUNCATE = 80;
+/** Truncate text for table cell display */
+export declare function truncateForCell(value: string): string;
+/** Format binary data (base64 string) for display */
+export declare function formatBinaryPreview(value: string): string;

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

@@ -0,0 +1,52 @@
+import { ColumnPanel } from '../data-panel';
+/**
+ * A single frame in the drill navigation chain, visible as one side column.
+ */
+export type DrillFrame = ColumnPanel;
+/**
+ * Is `frame` the same drill target as `other` (same table + same filter)?
+ *
+ * Used for cycle detection — drilling the same (table, filterId, filterColumn)
+ * we already have on the stack is a no-op. Using strict equality on all four
+ * fields is safe because they are primitives.
+ */
+export declare function framesEqual(a: DrillFrame, b: DrillFrame): boolean;
+/**
+ * Push `frame` onto `stack`, guarding against:
+ *   1. Exact duplicates of the top frame (no-op, returns `stack`).
+ *   2. Cycles — if `frame` already appears anywhere in the stack, truncate
+ *      back to that frame instead of re-pushing. This produces the natural
+ *      "breadcrumb jump" behaviour when a user drills back into an ancestor.
+ *
+ * Returns a new array; never mutates the input.
+ */
+export declare function pushDrillFrame(stack: DrillFrame[], frame: DrillFrame): DrillFrame[];
+/**
+ * Pop entries from `stack` down to (and including) `index`.
+ * Popping index 0 yields an empty stack (all side columns closed); popping
+ * an out-of-range index is a no-op.
+ */
+export declare function popDrillFramesTo(stack: DrillFrame[], index: number): DrillFrame[];
+/**
+ * A crumb displayed in the breadcrumb bar above the drill panels.
+ * `index = -1` represents the main (non-stack) view.
+ */
+export interface DrillCrumb {
+    /** -1 for the main view, 0+ for each side-column stack entry. */
+    index: number;
+    /** Display label — usually the table's human label. */
+    label: string;
+    /** Optional secondary label showing filter context (e.g. "from Customers #42"). */
+    detail?: string;
+    /** The underlying frame for index >= 0 (undefined for main view). */
+    frame?: DrillFrame;
+}
+/**
+ * Resolve table labels for a drill stack and produce breadcrumb entries.
+ *
+ * @param mainTable - GraphQL name of the root/main table
+ * @param stack     - Current drill stack
+ * @param lookup    - Function returning a human label for a given GraphQL table name,
+ *                    or `undefined` if not found (caller falls back to the raw name).
+ */
+export declare function buildDrillCrumbs(mainTable: string, stack: DrillFrame[], lookup: (tableName: string) => string | undefined): DrillCrumb[];

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

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

package/dist/lib/humanize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Converts raw database names into human-readable Title Case labels.
+ * Handles snake_case, camelCase, and schema-prefixed names (e.g. dbo.order_details).
+ */
+export declare function humanizeName(name: string): string;

package/dist/lib/pk-hygiene.test.d.ts

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

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

@@ -0,0 +1,52 @@
+import { Table, Schema } from '../types/schema';
+import { ColumnFiltersState } from '@tanstack/react-table';
+export interface FilterResult {
+    variables: Record<string, unknown>;
+    param: string;
+    filterText: string;
+}
+export interface ColumnFilterValue {
+    operator: string;
+    value: unknown;
+}
+export interface ColumnFilterResult {
+    variables: Record<string, unknown>;
+    params: string[];
+    filterTexts: string[];
+}
+export interface PkTypeInfo {
+    name: string;
+    gqlType: string;
+}
+interface RowData {
+    id?: number | string | null;
+    [key: string]: unknown;
+}
+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 getGraphQlType(paramType: string): string;
+export declare function buildColumnFilters(columnFilters: ColumnFiltersState, table: Table): ColumnFilterResult;
+export declare function serializeColumnFilters(columnFilters: ColumnFiltersState): string;
+export declare function deserializeColumnFilters(raw: string): ColumnFiltersState;
+/**
+ * Returns the GraphQL type of the first PK column. For composite PKs use {@link getPkTypes}.
+ */
+export declare function getPkType(table: Table): string;
+/**
+ * Returns one {name, gqlType} per primary-key column in declaration order.
+ * Empty array if the table has no primary keys.
+ */
+export declare function getPkTypes(table: Table): PkTypeInfo[];
+/**
+ * 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.
+ * - Composite PK: returns `{ pk_${col1}: ..., pk_${col2}: ... }` matching the composite form.
+ *
+ * `idRoute` is the same string passed to buildQuery's `id` parameter — for composite PKs
+ * it is a route-encoded string produced by {@link encodePkRoute}.
+ */
+export declare function buildPkEqVariables(idRoute: string, table: Table): Record<string, unknown>;
+export declare function buildQuery(table: Table, schema: Schema, filterString: string, columnFilters: ColumnFiltersState, id?: string, tableFilter?: string, filterColumn?: string): string | null;
+export {};

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

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

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

@@ -0,0 +1,14 @@
+import { Table } from '../types/schema';
+export type PkFilter = Record<string, unknown>;
+export interface PkEqFilterResult {
+    filterText: string;
+    variables: Record<string, unknown>;
+    params: string[];
+}
+type TableLike = Pick<Table, 'primaryKeys'> & Partial<Pick<Table, 'columns'>>;
+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;
+export declare function encodePkRoute(filter: PkFilter, table: TableLike): string;
+export declare function parsePkRoute(raw: string, table: TableLike): PkFilter | null;
+export {};

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

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

package/dist/tableList.d.ts

@@ -1 +1,16 @@
+/**
+ * TableList component that displays database tables in a sidebar.
+ *
+ * Features:
+ * - Lists all tables from the schema
+ * - Shows loading and error states
+ * - Displays table statistics (columns, rows, FKs) as sparklines
+ * - Responsive layout with visual hierarchy
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <TableList />
+ * ```
+ */
 export declare function TableList(): import("react/jsx-runtime").JSX.Element;

package/dist/types/schema.d.ts

@@ -1,4 +1,15 @@
+/**
+ * @module types/schema
+ *
+ * TypeScript type definitions for database schema metadata.
+ * These types represent the structure returned by the _dbSchema GraphQL query.
+ */
+/**
+ * Metadata attached to tables for custom behavior configuration.
+ * @interface TableMetadata
+ */
 export interface TableMetadata {
+    /** Lookup configuration for reference tables */
     type?: {
         type: 'lookup';
         id: string;
@@ -6,50 +17,127 @@ export interface TableMetadata {
     };
     [key: string]: any;
 }
+/**
+ * Lookup table metadata defining ID and label columns.
+ * @interface LookupMetadata
+ */
 export interface LookupMetadata {
     type: 'lookup';
     id: string;
     label: string;
 }
+/**
+ * Column-level metadata for custom configuration.
+ * @interface ColumnMetadata
+ */
 export interface ColumnMetadata {
     [key: string]: string | LookupMetadata | undefined;
 }
+/**
+ * Column definition from database schema introspection.
+ * @interface Column
+ */
 export interface Column {
+    /** Original database column name */
     dbName: string;
+    /** GraphQL field name for the column */
     graphQlName: string;
+    /** Alias for graphQlName */
     name: string;
+    /** Human-readable label for the column */
     label: string;
+    /** GraphQL parameter type (e.g., "String", "Int!") */
     paramType: string;
+    /** Database-specific type (e.g., "nvarchar", "int") */
+    dbType: string;
+    /** Whether this column is part of the primary key */
     isPrimaryKey: boolean;
+    /** Whether this column is auto-generated by the database */
     isIdentity: boolean;
+    /** Whether this column allows NULL values */
     isNullable: boolean;
+    /** Whether this column is read-only (e.g., computed columns) */
     isReadOnly: boolean;
+    /** Custom metadata for the column */
     metadata: ColumnMetadata;
+    /** 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;
+    /** Step increment for numeric inputs */
+    step?: number;
+    /** Regex pattern for validation */
+    pattern?: string;
+    /** Error message for pattern validation failures */
+    patternMessage?: string;
+    /** HTML input type override */
+    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[];
 }
+/**
+ * Relationship join definition between tables.
+ * @interface Join
+ */
 export interface Join {
+    /** Name of the join relationship */
     name: string;
+    /** Column names in the source table */
     sourceColumnNames: string[];
+    /** Target table name */
     destinationTable: string;
+    /** Column names in the target table */
     destinationColumnNames: string[];
 }
+/**
+ * Table definition from database schema introspection.
+ * @interface Table
+ */
 export interface Table {
+    /** Original database table name */
     dbName: string;
+    /** GraphQL type name for the table */
     graphQlName: string;
+    /** Alias for graphQlName */
     name: string;
+    /** Human-readable label for the table */
     label: string;
+    /** Column used as the display label for foreign key references */
     labelColumn: string;
+    /** Primary key column names */
     primaryKeys: string[];
+    /** Whether this table supports mutations */
     isEditable: boolean;
+    /** Custom metadata for the table */
     metadata: TableMetadata;
+    /** Column definitions */
     columns: Column[];
+    /** One-to-many relationship joins */
     multiJoins: Join[];
+    /** Many-to-one relationship joins */
     singleJoins: Join[];
 }
+/**
+ * Schema context value containing database metadata and loading state.
+ * @interface Schema
+ */
 export interface Schema {
+    /** Whether schema data is currently loading */
     loading: boolean;
+    /** Error object if schema loading failed, null otherwise */
     error: {
         message: string;
     } | null;
+    /** Array of table definitions */
     data: Table[];
+    /** Find a table by its GraphQL name */
     findTable: (tableName: string) => Table | undefined;
 }

package/package.json

@@ -1,17 +1,8 @@
 {
   "name": "@standardbeagle/edit-db",
   "private": false,
-  "version": "0.3.229",
+  "version": "0.4.327",
   "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build --mode production",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
-    "preview": "vite preview",
-    "storybook": "storybook dev -p 6006",
-    "storybook-build": "storybook build",
-    "ts": "tsc"
-  },
   "dependencies": {
     "@radix-ui/react-slot": "^1.2.4",
     "@tanstack/react-form": "^1.28.5",
@@ -35,6 +26,8 @@
     "@storybook/react": "^10.2.7",
     "@storybook/react-vite": "^10.2.7",
     "@tailwindcss/vite": "^4.2.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "@types/redux-actions": "^2.6.5",
@@ -47,14 +40,13 @@
     "eslint": "^8.55.0",
     "eslint-plugin-react-hooks": "^4.6.2",
     "eslint-plugin-react-refresh": "^0.4.7",
-    "sass": "^1.97.3",
+    "jsdom": "^25.0.1",
     "storybook": "^10.2.7",
-    "stylelint": "^17.1.1",
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
-    "vite-plugin-browser-sync": "^3.0.2",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0"
@@ -65,6 +57,7 @@
   "main": "./dist/editor.umd.cjs",
   "module": "./dist/editor.es.js",
   "types": "./dist/index.d.ts",
+  "style": "./dist/edit-db.css",
   "exports": {
     ".": {
       "import": {
@@ -75,6 +68,18 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/editor.umd.cjs"
       }
-    }
+    },
+    "./style.css": "./dist/edit-db.css"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build --mode production",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "storybook": "storybook dev -p 6006",
+    "storybook-build": "storybook build",
+    "ts": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}