@hienlh/ppm 0.23.12 → 0.23.14

package/src/web/components/database/grid/master-detail-split.tsx

@@ -0,0 +1,233 @@
+/**
+ * DBGate's master / detail: a table from the References list shown under the grid, holding only
+ * the rows that belong to the rows selected there, and following the selection as it moves. The
+ * header reads the join out — `orders [user_id] = master [id]` — with Close beside it. Below it is
+ * the table grid every other tab has: filter row, sort, editing, its own Save bar (the toolbar
+ * above is the master's), its own "Rows: N". A phone gives it the lower 45% of the screen.
+ */
+import { useCallback, useEffect, useId, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { toast } from "sonner";
+import { Link } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import type { FilterGroup, GridSort } from "../../../../shared/db-grid";
+import { useDatabase, type DbColumnInfo } from "../use-database";
+import { useDbRead } from "../use-db-read";
+import type { DbTabContext } from "../use-db-tab";
+import { GlideDataGrid } from "../glide-data-grid";
+import type { GlideGridHandle, GridFiltering } from "../glide-grid-types";
+import { DbTabState } from "../db-tab-parts";
+import { linkButtonClass } from "../explorer/tree-parts";
+import { openQueryTab, openReferenceTab, openTableTab } from "../explorer/open-db-tabs";
+import { selectTemplate } from "../explorer/sql-templates";
+import { FilterDialogHost, type OpenFilterDialog } from "./filter-dialog-host";
+import { NO_FILTERS, filterableColumns, hasFilters, withColumnFilter, withMultiFilter, type FilterRequest } from "./grid-filters";
+import { referencedRowFilters } from "./reference-filter";
+import { detailKeyFilters, referenceId, referenceJoin, type GridReference } from "./references";
+import { isGridKeyCommand, tableKeyCommand, tableKeyPlace } from "./table-keys";
+import { useFilterPickers } from "./use-filter-pickers";
+import { useTableFilters } from "./use-table-filters";
+
+/** The slot the detail's unsaved rows are counted under in its tab (`unsaved-grid-rows-store.ts`). */
+export const DETAIL_GRID_SLOT = "detail";
+
+export function MasterDetailSplit({ tab, reference, masterRows, shownIn, narrow, onClose }: {
+  tab: DbTabContext;
+  reference: GridReference;
+  /** The rows selected in the grid above, as they were read. */
+  masterRows: readonly Record<string, unknown>[];
+  /** The tab both grids are in. */
+  shownIn?: string;
+  /** A narrow tab's: the Cell data view floats over the grid. */
+  narrow: boolean;
+  onClose: () => void;
+}) {
+  const titleId = useId();
+  const join = referenceJoin(reference);
+  return (
+    <>
+      <div aria-hidden className="h-[5px] shrink-0 border-y border-border bg-panel" />
+      <section aria-labelledby={titleId} className="flex min-h-[150px] shrink-0 grow-0 basis-[42%] flex-col bg-panel-2 max-md:basis-[45%]">
+        <div className="flex h-[30px] shrink-0 items-center gap-1.5 border-b border-border-soft bg-panel px-2.5 text-xs text-text-2 max-md:h-11 max-md:text-[13px]">
+          <Link className="size-3.5 shrink-0 text-info" aria-hidden />
+          <h3 id={titleId} className="min-w-0 truncate font-normal">
+            <b className="font-semibold text-text">{join.table}</b> [{join.detail}] = master [{join.master}]
+            {masterRows.length === 0 && <span className="text-text-3"> · select a row in the grid above</span>}
+          </h3>
+          <span className="flex-1" />
+          <button type="button" onClick={onClose} aria-label={`Close ${join.table}`} className={cn(linkButtonClass, "shrink-0 max-md:min-w-11")}>
+            Close
+          </button>
+        </div>
+        <div className="relative min-h-0 flex-1">
+          <DetailGrid key={referenceId(reference)} tab={tab} reference={reference} masterRows={masterRows} shownIn={shownIn} narrow={narrow} />
+        </div>
+      </section>
+    </>
+  );
+}
+
+const NO_REQUEST: FilterRequest = { filters: [], anyColumn: [] };
+
+function DetailGrid({ tab, reference, masterRows, shownIn, narrow }: {
+  tab: DbTabContext;
+  reference: GridReference;
+  masterRows: readonly Record<string, unknown>[];
+  shownIn?: string;
+  narrow: boolean;
+}) {
+  const db = useDatabase(tab.target);
+  const mobile = useIsMobile();
+  const gridRef = useRef<GlideGridHandle>(null);
+  const schemaName = reference.schema ?? "";
+  const scope = schemaName ? `&schema=${encodeURIComponent(schemaName)}` : "";
+  // Read before any row is: they say how the key is written, and head the grid while no master row is selected.
+  const columnsRead = useDbRead<DbColumnInfo[]>(tab.target, `/schema?table=${encodeURIComponent(reference.table)}${scope}`, shownIn);
+  const schema = db.schema.length ? db.schema : columnsRead.data ?? [];
+  const filterColumns = useMemo(() => filterableColumns(schema, tab.dbType), [schema, tab.dbType]);
+
+  // What the master's selection asks of the rows here; null when no row of this table can belong to it.
+  const keys = useMemo(() => {
+    if (!filterColumns.length) return null;
+    const kindOf = (column: string) => filterColumns.find((c) => c.name === column)?.kind ?? "other";
+    return detailKeyFilters(reference, masterRows, kindOf);
+  }, [reference, masterRows, filterColumns]);
+  const keysKey = keys ? JSON.stringify(keys) : null;
+  const keysRef = useRef<FilterGroup[] | null>(keys);
+  keysRef.current = keys;
+
+  // The rows here are the key's and the filter row's together; the filter row shows only its own.
+  const ownRef = useRef<FilterRequest>(NO_REQUEST);
+  const started = useRef(false);
+  // The latest read failed: the rows still on hand are another selection's, or another filter's.
+  const [failed, setFailed] = useState(false);
+  const readSeq = useRef(0);
+  const read = useCallback(async (keyGroups: readonly FilterGroup[]) => {
+    const own = ownRef.current;
+    const request: FilterRequest = { filters: [...keyGroups, ...own.filters], anyColumn: own.anyColumn };
+    const seq = ++readSeq.current;
+    let e: Error | null;
+    if (started.current) e = await db.applyFilters(request);
+    else {
+      started.current = true;
+      e = await db.selectTable(reference.table, schemaName, () => request);
+    }
+    if (seq === readSeq.current) setFailed(e !== null);
+    return e;
+  }, [db.applyFilters, db.selectTable, reference.table, schemaName]); // eslint-disable-line react-hooks/exhaustive-deps
+  const hadRows = useRef(false);
+  hadRows.current = db.tableData !== null;
+  useEffect(() => {
+    if (!keysKey) return;
+    const shown = hadRows.current;
+    void read(JSON.parse(keysKey) as FilterGroup[]).then((e) => {
+      // A first read that fails says why in the grid's place; later ones would leave it unsaid.
+      if (e && shown) toast.error(`Could not read ${reference.table}`, { description: e.message });
+    });
+  }, [keysKey]); // eslint-disable-line react-hooks/exhaustive-deps
+  const applyOwn = useCallback((request: FilterRequest) => {
+    ownRef.current = request;
+    const keyGroups = keysRef.current;
+    return keyGroups ? read(keyGroups) : Promise.resolve(null);
+  }, [read]);
+  const { filters, setFilters, errors } = useTableFilters(filterColumns, applyOwn);
+
+  const [filterDialog, setFilterDialog] = useState<OpenFilterDialog | null>(null);
+  const pickers = useFilterPickers({
+    target: tab.target, dbType: tab.dbType, table: reference.table, schema: schemaName,
+    columns: filterColumns, tableSchema: schema, filters, fixed: keys ?? undefined,
+  });
+  const filtering = useMemo<GridFiltering>(() => ({
+    filters, columns: filterColumns, onChange: setFilters, errors,
+    onDialog: (column, request, returnFocus) => setFilterDialog({ column, request, returnFocus }),
+    onChooseValues: (column, returnFocus) => setFilterDialog({ column, request: pickers.chooseValues(column), returnFocus }),
+    onLookup: (column, returnFocus) => {
+      const request = pickers.lookup(column);
+      if (request) setFilterDialog({ column, request, returnFocus });
+    },
+  }), [filters, filterColumns, errors, setFilters, pickers]);
+  const lookupFor = useCallback((column: string) => {
+    const request = pickers.lookup(column);
+    return request?.dialog === "lookup" ? { source: request.source, kind: request.kind } : null;
+  }, [pickers]);
+  const submitFilterDialog = useCallback((column: string | null, text: string) => {
+    setFilters((f) => (column === null ? withMultiFilter(f, text) : withColumnFilter(f, column, text)));
+  }, [setFilters]);
+
+  const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});
+  const sortChange = useCallback((next: GridSort[]) => { void db.setSort(next); }, [db.setSort]); // eslint-disable-line react-hooks/exhaustive-deps
+  const openTable = useCallback((name: string) => {
+    if (tab.place) openTableTab(tab.place, { schema: reference.schema, name });
+  }, [tab.place, reference.schema]);
+  const openReference = useCallback((column: string, row: Record<string, unknown>) => {
+    const fk = schema.find((c) => c.name === column)?.fk;
+    const kind = filterColumns.find((c) => c.name === column)?.kind ?? "other";
+    const kept = fk && referencedRowFilters(fk.column, kind, row[column]);
+    if (fk && kept && tab.place) openReferenceTab(tab.place, { schema: reference.schema, name: fk.table }, kept);
+  }, [schema, filterColumns, tab.place, reference.schema]);
+
+  // ── DBGate's keys act on the grid they are pressed in: here, this one ──
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    const place = tableKeyPlace(e.currentTarget, e.target);
+    const command = place && tableKeyCommand(e.nativeEvent, place);
+    // The panel beside both grids is the master's to show or hide; the selection's keys are the
+    // grid's, which runs them itself.
+    if (!command || command === "toggle-panel" || (command !== "swallow" && isGridKeyCommand(command))) return;
+    e.preventDefault();
+    e.stopPropagation();
+    switch (command) {
+      case "refresh": if (keys) void db.reload(); break;
+      case "refresh-structure":
+        void columnsRead.reload();
+        if (keys) void db.reload({ structure: true });
+        break;
+      case "save": if (!tab.readonly) gridRef.current?.save(); break;
+      case "new-row": if (keys) gridRef.current?.newRow(); break;
+      case "delete-rows": gridRef.current?.deleteSelectedRows(); break;
+      case "undo": gridRef.current?.undo(); break;
+      case "redo": gridRef.current?.redo(); break;
+      case "clear-filters": setFilters(NO_FILTERS); break;
+      // No auto refresh, Revert row changes on a button, or form here.
+      default: break;
+    }
+  };
+
+  const data = db.tableData;
+  if (columnsRead.error && !schema.length) return <DbTabState error={columnsRead.error} />;
+  if (db.error && !data) return <DbTabState error={db.error} />;
+  if (!schema.length) return <DbTabState loading />;
+
+  // No master row, or one whose key is NULL: no row here belongs to it, and none is read.
+  const waiting = !keys;
+  const openQuery = tab.place && !waiting && (data?.sql || tab.dbType)
+    ? () => { if (tab.place) openQueryTab(tab.place, data?.sql || selectTemplate({ schema: reference.schema, name: reference.table }, tab.dbType!)); }
+    : undefined;
+
+  return (
+    <div className="absolute inset-0" onKeyDown={onKeyDown}>
+      <GlideDataGrid
+        ref={gridRef}
+        columns={data?.columns ?? schema.map((c) => c.name)} rows={waiting || failed || !data ? [] : data.rows}
+        schema={schema} loading={!waiting && (db.loading || !data)}
+        rowKey={data?.rowKey} onSaveChanges={(changes) => db.saveChanges(changes, tab.place)} readOnly={tab.readonly}
+        // Rows cannot be added for a master row that is not there.
+        editOnly={waiting}
+        sort={db.sort} onSortChange={sortChange} viewKey={waiting ? "waiting" : db.viewKey}
+        hasMore={!waiting && !!data?.hasMore} onLoadMore={db.loadMore} loadingMore={db.loadingMore} fetchingAll={db.fetchingAll}
+        columnWidths={columnWidths} onColumnWidthsChange={setColumnWidths}
+        tabId={shownIn} tabSlot={DETAIL_GRID_SLOT} rowsLabel={waiting ? "Rows: 0" : failed ? undefined : db.rowCount?.text}
+        onResetFilter={!waiting && hasFilters(filters) ? () => setFilters(NO_FILTERS) : undefined}
+        onOpenQuery={openQuery}
+        onOpenTable={tab.place ? openTable : undefined}
+        place={tab.place ?? undefined} selectedTable={reference.table} selectedSchema={schemaName}
+        connectionName={tab.name} dialect={tab.dialect}
+        filtering={mobile ? undefined : filtering}
+        lookupFor={tab.target ? lookupFor : undefined}
+        onOpenReference={tab.place ? openReference : undefined}
+        startCellDownload={db.startCellDownload}
+        floatCellData={narrow}
+      />
+      <FilterDialogHost open={filterDialog} onClose={() => setFilterDialog(null)} onSubmit={submitFilterDialog} />
+    </div>
+  );
+}

package/src/web/components/database/grid/pick-table.tsx

@@ -0,0 +1,109 @@
+/**
+ * The list ⋮ and ⋯ pick from: a row a value, ticked by its checkbox or anywhere on the row, under
+ * a header that stays put while the list scrolls. What is in the cells is the dialog's.
+ */
+import type { ReactNode } from "react";
+import { Search } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { inputClass } from "../connection-form/form-controls";
+
+export interface PickRow {
+  key: string;
+  /** Names the row to a screen reader: "Pick <label>". */
+  label: string;
+  cells: ReactNode[];
+}
+
+export interface PickColumn {
+  label: string;
+  /** A Tailwind width, e.g. `w-[38%]`; a column without one takes what is left. */
+  width?: string;
+}
+
+export function PickTable({ headers, rows, picked, onToggle, children }: {
+  headers: readonly PickColumn[];
+  rows: readonly PickRow[];
+  picked: ReadonlySet<string>;
+  onToggle: (key: string) => void;
+  /** Shown under the rows: what the list is still doing, or why it is empty. */
+  children?: ReactNode;
+}) {
+  const head = "sticky top-0 z-10 h-7 border-b border-border-soft bg-panel px-2.5 text-left text-[11px] font-semibold text-text-3";
+  const cell = "h-[30px] border-b border-border-soft px-2.5 max-md:h-11";
+  return (
+    <div className="max-h-80 min-h-24 overflow-auto rounded-md border border-border bg-panel-2 max-md:max-h-[50dvh]">
+      {/* Fixed, so a long value is cut short in its cell rather than widening the list. */}
+      <table className="w-full table-fixed border-collapse text-[12.5px] max-md:text-sm">
+        <thead>
+          <tr>
+            <th className={cn(head, "w-[34px] max-md:w-11")}><span className="sr-only">Picked</span></th>
+            {headers.map((h) => <th key={h.label} className={cn(head, h.width)}>{h.label}</th>)}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => {
+            const on = picked.has(row.key);
+            return (
+              <tr
+                key={row.key}
+                onClick={(e) => { if (!(e.target as HTMLElement).closest("input")) onToggle(row.key); }}
+                className={cn("cursor-pointer select-none [&:last-child>td]:border-b-0", on ? "bg-accent-wash" : "can-hover:hover:bg-surface-hover")}
+              >
+                <td className={cell}>
+                  <input
+                    type="checkbox" checked={on} onChange={() => onToggle(row.key)} aria-label={`Pick ${row.label}`}
+                    className="block size-3.5 accent-primary max-md:size-5"
+                  />
+                </td>
+                {row.cells.map((c, i) => <td key={i} className={cn(cell, "truncate")}>{c}</td>)}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+      {children}
+    </div>
+  );
+}
+
+/** A value in a pick list: NULL and the empty text marked, so neither reads as a blank row. */
+export function PickValue({ text, isNull, mono }: { text: string; isNull?: boolean; mono?: boolean }) {
+  if (isNull) return <span className="font-mono text-text-3 italic">NULL</span>;
+  if (text === "") return <span className="text-text-3 italic">(empty)</span>;
+  return <span className={cn(mono && "font-mono")} title={text}>{text}</span>;
+}
+
+/**
+ * The search over a pick list. Enter searches at once rather than OK-ing the dialog: what has
+ * been ticked is not done with because a search was typed. Focus does not start here on a phone,
+ * where it would put the keyboard over the list.
+ */
+export function PickSearch({ value, onChange, onSearchNow, label }: {
+  value: string;
+  onChange: (value: string) => void;
+  onSearchNow: () => void;
+  label: string;
+}) {
+  return (
+    <span className="relative flex min-w-0">
+      <Search className="pointer-events-none absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-text-subtle" />
+      <input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key !== "Enter" || e.nativeEvent.isComposing) return;
+          e.preventDefault();
+          e.stopPropagation();
+          onSearchNow();
+        }}
+        placeholder="Search"
+        aria-label={label}
+        enterKeyHint="search"
+        autoComplete="off"
+        autoCapitalize="off"
+        spellCheck={false}
+        className={cn(inputClass, "pl-8")}
+      />
+    </span>
+  );
+}

package/src/web/components/database/grid/reference-filter.ts

@@ -0,0 +1,48 @@
+/**
+ * A foreign key followed by its values: the filter a table's box would hold to show exactly the
+ * rows the values name, and what that filter asks the server for. Written as ⋮ writes a picked
+ * value (`="5"`) and read back in the column's own syntax, so a number column compares numbers
+ * and a date column that one second — the server is never handed a raw value to compare.
+ */
+import type { ColumnKind } from "../../../../shared/db-column-kind";
+import { parseFilter } from "../../../../shared/db-filter-parser";
+import type { FilterGroup } from "../../../../shared/db-grid";
+import { isBinaryValue } from "./cell-display";
+import { NO_FILTERS, withColumnFilter, type GridFilters } from "./grid-filters";
+import { pickedValuesFilter, valueKey, valueTerm } from "./value-filter-text";
+
+/**
+ * The values a key is filtered by, each once: no NULL, which references nothing, and no bytes,
+ * which no filter can spell.
+ */
+export function keyValues(values: readonly unknown[]): unknown[] {
+  const seen = new Map<string, unknown>();
+  for (const value of values) {
+    if (value === null || value === undefined || isBinaryValue(value)) continue;
+    const key = valueKey(value);
+    if (!seen.has(key)) seen.set(key, value);
+  }
+  return [...seen.values()];
+}
+
+/** `="5",="7"` on `column`, and the group it asks for; null when there is no value to filter by. */
+export function keyValuesFilter(
+  column: string, kind: ColumnKind, values: readonly unknown[],
+): { text: string; group: FilterGroup } | null {
+  const usable = keyValues(values);
+  if (!usable.length) return null;
+  const text = pickedValuesFilter(kind, usable);
+  const read = parseFilter(text, kind);
+  if (!read.ok || read.anyOf.length === 0) return null;
+  return { text, group: { column, anyOf: read.anyOf } };
+}
+
+/**
+ * The filters the form button on a foreign key cell opens the referenced table on: its key column
+ * equal to the cell's value, written in the key's own syntax as ⋮ writes a picked value — the key
+ * and what it refers to share a type. Null when the value refers to nothing.
+ */
+export function referencedRowFilters(keyColumn: string, kind: ColumnKind, value: unknown): GridFilters | null {
+  if (value === null || value === undefined || isBinaryValue(value)) return null;
+  return withColumnFilter(NO_FILTERS, keyColumn, valueTerm(kind, value));
+}

package/src/web/components/database/grid/references-panel.tsx

@@ -0,0 +1,82 @@
+/**
+ * DBGate's References, in the panel beside a table's grid and in a phone's Columns and filters
+ * sheet: the tables this table's keys point at (References tables) and those whose keys point at
+ * it (Dependent tables), each named by its key's columns. Clicking one shows it under the grid,
+ * following the rows selected there (`master-detail-split.tsx`).
+ */
+import { useState } from "react";
+import { Table } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { EmptyState, Highlight, SearchBox, SectionHeader } from "../explorer/tree-parts";
+import { referenceId, referencesMatching, type GridReference, type TableReferences } from "./references";
+
+export function ReferencesSection({ table, references, open, onOpen, sheet = false, grow = true, collapsed, onCollapsedChange }: {
+  /** The table the references are of, which the list is named after. */
+  table: string;
+  references: TableReferences;
+  /** The reference shown under the grid, lit in the list. */
+  open: GridReference | null;
+  onOpen: (reference: GridReference) => void;
+  /** In a phone's sheet: every row 44px. */
+  sheet?: boolean;
+  /** Scrolls in the height it is given; the sheet scrolls as a whole instead. */
+  grow?: boolean;
+  collapsed: boolean;
+  onCollapsedChange: (collapsed: boolean) => void;
+}) {
+  const [query, setQuery] = useState("");
+  const shown = referencesMatching(references, query);
+  const openId = open ? referenceId(open) : null;
+
+  const group = (title: string, refs: readonly GridReference[]) => refs.length > 0 && (
+    <>
+      <div className={cn(
+        "px-3 pt-1.5 pb-0.5 text-[10.5px] font-semibold tracking-[0.05em] whitespace-nowrap text-text-3 uppercase",
+        sheet && "px-4 pt-2.5 pb-1 text-[11px]",
+      )}>
+        {title} ({refs.length})
+      </div>
+      {refs.map((ref) => {
+        const id = referenceId(ref);
+        const lit = id === openId;
+        return (
+          <div key={id} role="listitem">
+            <button
+              type="button" onClick={() => onOpen(ref)} aria-pressed={lit}
+              title={`Show ${ref.table} below the grid, following the selected row`}
+              className={cn(
+                "mx-1 flex h-[26px] w-[calc(100%-8px)] items-center gap-[5px] rounded-[5px] pr-1.5 pl-0.5 text-left text-xs whitespace-nowrap text-text-2 select-none can-hover:hover:bg-surface-hover can-hover:hover:text-text",
+                sheet && "mx-1.5 h-11 w-[calc(100%-12px)] gap-2.5 px-2.5 text-sm",
+                lit && "bg-accent-wash text-text can-hover:hover:bg-accent-wash",
+              )}
+            >
+              <Table className={cn("shrink-0", sheet ? "size-[18px]" : "size-[15px]", lit ? "text-primary" : "text-text-3")} aria-hidden />
+              <span className="min-w-0 truncate">
+                <Highlight text={ref.table} query={query} />{" "}
+                <span className="font-mono text-[10.5px] text-text-3">({ref.keyColumns.join(", ")})</span>
+              </span>
+            </button>
+          </div>
+        );
+      })}
+    </>
+  );
+
+  return (
+    <section aria-label="References" className={cn("flex min-h-0 flex-col", grow && !collapsed && "flex-1")}>
+      <SectionHeader title="References" collapsed={collapsed} onToggle={() => onCollapsedChange(!collapsed)} />
+      {!collapsed && (
+        <>
+          <div className="flex shrink-0 items-center pr-1.5 pb-1.5 pl-2">
+            <SearchBox value={query} onChange={setQuery} placeholder="Search references" />
+          </div>
+          <div role="list" aria-label={`References of ${table}`} className={cn("min-h-0 pb-2.5", grow && "flex-1 overflow-auto")}>
+            {group("References tables", shown.out)}
+            {group("Dependent tables", shown.in)}
+            {shown.out.length + shown.in.length === 0 && <EmptyState>No reference matches “{query.trim()}”.</EmptyState>}
+          </div>
+        </>
+      )}
+    </section>
+  );
+}

package/src/web/components/database/grid/references.ts

@@ -0,0 +1,104 @@
+/**
+ * DBGate's References: the tables a table's own keys point at (References tables) and the tables
+ * whose keys point at it (Dependent tables), and what one of them shown under the grid — master /
+ * detail — is filtered by. The detail follows the rows selected in the master: each of its key
+ * columns must hold a value one of those rows has in the column it pairs with, column by column,
+ * as DBGate's detail filter is built.
+ */
+import type { ColumnKind } from "../../../../shared/db-column-kind";
+import type { FilterGroup } from "../../../../shared/db-grid";
+import type { DbForeignKey } from "../../../../shared/db-structure";
+import { keyValuesFilter } from "./reference-filter";
+
+export interface GridReference {
+  /** "out": a key this table holds (References tables); "in": a key another table holds (Dependent tables). */
+  direction: "out" | "in";
+  /** The table shown under the grid; a null schema is the connection's own. */
+  schema: string | null;
+  table: string;
+  /** Each column of the table below, with the master's column whose value it holds. */
+  columns: readonly { detail: string; master: string }[];
+  /** The columns the key is made of, which the list names it by: `plans (plan_id)`, `orders (user_id)`. */
+  keyColumns: readonly string[];
+  /** The key's own name, telling apart two keys between the same tables; null where the catalog has none. */
+  name: string | null;
+}
+
+export interface TableReferences {
+  out: GridReference[];
+  in: GridReference[];
+}
+
+/** Pairs a key's columns with the ones it references; null when they do not pair up, so it filters nothing. */
+function pairs(fk: DbForeignKey): { column: string; ref: string }[] | null {
+  if (fk.columns.length === 0 || fk.columns.length !== fk.refColumns.length) return null;
+  return fk.columns.map((column, i) => ({ column, ref: fk.refColumns[i]! }));
+}
+
+/** A table's references, from its structure: `foreignKeys` are the keys it holds, `references` those pointing at it. */
+export function tableReferences(structure: { foreignKeys: readonly DbForeignKey[]; references: readonly DbForeignKey[] }): TableReferences {
+  return {
+    out: structure.foreignKeys.flatMap((fk): GridReference[] => {
+      const keys = pairs(fk);
+      return keys ? [{
+        direction: "out", schema: fk.refSchema, table: fk.refTable, name: fk.name, keyColumns: fk.columns,
+        columns: keys.map((k) => ({ detail: k.ref, master: k.column })),
+      }] : [];
+    }),
+    in: structure.references.flatMap((fk): GridReference[] => {
+      const keys = pairs(fk);
+      return keys ? [{
+        direction: "in", schema: fk.schema, table: fk.table, name: fk.name, keyColumns: fk.columns,
+        columns: keys.map((k) => ({ detail: k.column, master: k.ref })),
+      }] : [];
+    }),
+  };
+}
+
+export function hasReferences(refs: TableReferences | null): refs is TableReferences {
+  return !!refs && refs.out.length + refs.in.length > 0;
+}
+
+/**
+ * Tells references apart: a table can reference another twice, and itself both ways. By the columns
+ * each one joins, not only those of its key: SQLite names no key, and one column can reference two
+ * keys of a table.
+ */
+export function referenceId(ref: GridReference): string {
+  return [ref.direction, ref.schema ?? "", ref.table, ref.name ?? "", ...ref.columns.flatMap((c) => [c.detail, c.master])].join("\u0000");
+}
+
+/** The references whose table or key columns contain the search, in their order. */
+export function referencesMatching(refs: TableReferences, query: string): TableReferences {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return refs;
+  const hit = (ref: GridReference) => ref.table.toLowerCase().includes(needle) || ref.keyColumns.join(", ").toLowerCase().includes(needle);
+  return { out: refs.out.filter(hit), in: refs.in.filter(hit) };
+}
+
+/** DBGate's detail header, the join read out: `orders [user_id] = master [id]`. */
+export function referenceJoin(ref: GridReference): { table: string; detail: string; master: string } {
+  return {
+    table: ref.table,
+    detail: ref.columns.map((c) => c.detail).join(", "),
+    master: ref.columns.map((c) => c.master).join(", "),
+  };
+}
+
+/**
+ * What the detail is filtered by for the master's selected rows: one group per key column, holding
+ * the values those rows have in the master column it pairs with. Null when a column has no value
+ * to filter by — no row selected, a NULL key, a new row — since then no row of the detail belongs
+ * to the selection.
+ */
+export function detailKeyFilters(
+  ref: GridReference, masterRows: readonly Record<string, unknown>[], kindOf: (column: string) => ColumnKind,
+): FilterGroup[] | null {
+  const groups: FilterGroup[] = [];
+  for (const { detail, master } of ref.columns) {
+    const filter = keyValuesFilter(detail, kindOf(detail), masterRows.map((row) => row[master]));
+    if (!filter) return null;
+    groups.push(filter.group);
+  }
+  return groups;
+}