@hienlh/ppm 0.23.12 → 0.23.14

package/src/web/components/database/explorer/open-db-tabs.ts

@@ -0,0 +1,160 @@
+/**
+ * The database tabs, each opened on a place: a table's data, its structure, one object's SQL, and
+ * a new query. A tab records `database` only when it is not the connection's own, so one table
+ * opened from the tree, the command palette, a foreign key or another tab's toolbar lands on the
+ * same tab (see `dbTabId`).
+ */
+import { useTabStore } from "@/stores/tab-store";
+import { usePanelStore } from "@/stores/panel-store";
+import { randomId } from "@/lib/utils";
+import { dbObjectTabTitle, nextQueryNumber, queryTabMetadata, targetFields, type DbTarget } from "@/lib/db-tabs";
+import { newTableTabMetadata, nextTableNumber } from "@/lib/db-table-edit";
+import type { DbObject, DbObjectKind } from "../../../../shared/db-structure";
+import { newTableModel } from "../../../../shared/db-table-model";
+import { withTabFilters, type GridFilters } from "../grid/grid-filters";
+import { DEFAULT_TABLE_VIEW, withTabView } from "../grid/table-view-state";
+import type { DbType } from "../../../../shared/db-types";
+import { tabDatabase, type DbRef, type TreeConnection } from "./explorer-model";
+
+/** Where a tab is, and what it shows of it before the connection list has arrived. */
+export interface DbTabPlace {
+  target: DbTarget;
+  connectionName?: string;
+  dbType?: DbType;
+  connectionColor?: string | null;
+}
+
+/** The place of a tab opened from the tree on `ref`. */
+export function treePlace(conn: TreeConnection, ref: DbRef): DbTabPlace {
+  const database = tabDatabase(ref, conn);
+  return {
+    target: { kind: "connection", connectionId: conn.id, ...(database ? { database } : {}) },
+    connectionName: conn.name, dbType: conn.type, connectionColor: conn.color,
+  };
+}
+
+/** The place a tab's own metadata names, for the tabs it opens in turn. */
+export function placeOf(target: DbTarget, metadata: Record<string, unknown> | undefined): DbTabPlace {
+  const name = metadata?.connectionName;
+  const color = metadata?.connectionColor;
+  return {
+    target,
+    ...(typeof name === "string" ? { connectionName: name } : {}),
+    ...(typeof metadata?.dbType === "string" ? { dbType: metadata.dbType as DbType } : {}),
+    ...(typeof color === "string" ? { connectionColor: color } : {}),
+  };
+}
+
+function placeFields(p: DbTabPlace): Record<string, unknown> {
+  return {
+    ...targetFields(p.target),
+    ...(p.connectionName ? { connectionName: p.connectionName } : {}),
+    ...(p.dbType ? { dbType: p.dbType } : {}),
+    ...(p.connectionColor ? { connectionColor: p.connectionColor } : {}),
+  };
+}
+
+/** A file inside a project is that project's; everything else shows in every project's workspace. */
+function projectOf(p: DbTabPlace): string | null {
+  return p.target.kind === "file" ? p.target.projectName ?? null : null;
+}
+
+/** A table, view or materialized view; `kind` is what the tab asks the SQL tab for, when known. */
+export interface DbRelation {
+  schema: string | null;
+  name: string;
+  kind?: DbObjectKind;
+}
+
+function relationTab(type: "database" | "db-structure", place: DbTabPlace, rel: DbRelation, panelId?: string): string {
+  return usePanelStore.getState().openTab({
+    type,
+    title: dbObjectTabTitle(place.target, place.connectionName, rel.name),
+    projectId: projectOf(place),
+    closable: true,
+    metadata: { ...placeFields(place), schemaName: rel.schema ?? "", tableName: rel.name, ...(rel.kind ? { objectKind: rel.kind } : {}) },
+  }, panelId);
+}
+
+export function openTableTab(place: DbTabPlace, rel: DbRelation): string {
+  return relationTab("database", place, rel);
+}
+
+/**
+ * DBGate's form button on a foreign key: the referenced table as a form, filtered to the rows
+ * `filters` name, in a tab of its own — never one already open, as DBGate forces a new tab.
+ */
+export function openReferenceTab(place: DbTabPlace, rel: DbRelation, filters: GridFilters): string {
+  const metadata = { ...placeFields(place), schemaName: rel.schema ?? "", tableName: rel.name, instance: randomId() };
+  return usePanelStore.getState().openTab({
+    type: "database",
+    title: dbObjectTabTitle(place.target, place.connectionName, rel.name),
+    projectId: projectOf(place),
+    closable: true,
+    metadata: withTabView(withTabFilters(metadata, filters), { ...DEFAULT_TABLE_VIEW, form: true }),
+  });
+}
+
+/** A table's Structure tab, in the focused panel or in `panelId`. */
+export function openStructureTab(place: DbTabPlace, rel: DbRelation, panelId?: string): string {
+  return relationTab("db-structure", place, rel, panelId);
+}
+
+/**
+ * The Structure tab of `rel` where the tab `tabId` is — its panel, its place in the strip — and
+ * that tab closed: a New table becoming the table its Save created.
+ */
+export function openStructureTabInPlaceOf(tabId: string, place: DbTabPlace, rel: DbRelation): string {
+  const panel = usePanelStore.getState().getPanelForTab(tabId);
+  const index = panel ? panel.tabs.findIndex((t) => t.id === tabId) : -1;
+  const id = openStructureTab(place, rel, panel?.id);
+  if (!panel) return id;
+  usePanelStore.getState().closeTab(tabId, panel.id);
+  if (index >= 0) usePanelStore.getState().reorderTab(id, panel.id, index);
+  return id;
+}
+
+/**
+ * DBGate's New table: a Structure tab, "Table #N", on a table that exists only in the tab until
+ * its Save creates it — `new_table` with an `id` column, in `schema` (Postgres).
+ */
+export function openNewTableTab(place: DbTabPlace, schema: string | null): string {
+  const tableNumber = nextTableNumber(Object.values(usePanelStore.getState().panels).flatMap((p) => p.tabs));
+  return useTabStore.getState().openTab({
+    type: "db-structure",
+    title: `Table #${tableNumber}`,
+    projectId: projectOf(place),
+    closable: true,
+    metadata: { ...placeFields(place), ...newTableTabMetadata(newTableModel(schema), tableNumber, randomId()) },
+  });
+}
+
+/** One object's SQL. `args` tells a routine's overloads apart, `table` which table a trigger is on. */
+export function openSqlTab(place: DbTabPlace, o: Pick<DbObject, "schema" | "name" | "kind" | "args" | "table">): string {
+  return useTabStore.getState().openTab({
+    type: "db-sql",
+    title: dbObjectTabTitle(place.target, place.connectionName, o.name),
+    projectId: projectOf(place),
+    closable: true,
+    metadata: {
+      ...placeFields(place), schemaName: o.schema ?? "", objectKind: o.kind, objectName: o.name,
+      ...(o.args !== undefined ? { objectArgs: o.args } : {}), ...(o.table ? { objectTable: o.table } : {}),
+    },
+  });
+}
+
+/**
+ * A new query tab on `place`, its editor holding `sql`. It runs nothing unless `run` says so: a
+ * template or a script is there to be edited first, and only SQL the app wrote itself to read
+ * something — a foreign key followed — is run on the way in.
+ */
+export function openQueryTab(place: DbTabPlace, sql: string, opts: { run?: boolean } = {}): string {
+  const queryNumber = nextQueryNumber(Object.values(usePanelStore.getState().panels).flatMap((p) => p.tabs));
+  return useTabStore.getState().openTab({
+    type: "db-query",
+    title: `Query ${queryNumber}`,
+    projectId: projectOf(place),
+    closable: true,
+    metadata: { ...placeFields(place), ...queryTabMetadata(sql, queryNumber, opts) },
+  });
+}

package/src/web/components/database/explorer/open-new-query.ts

@@ -0,0 +1,22 @@
+/**
+ * A new Query tab from somewhere that has no database of its own to offer, the command palette:
+ * on the database the sidebar shows, else on the first saved connection — its connection box then
+ * picks another. With no connection saved there is nothing to query, so the form for one opens.
+ */
+import { openConnectionForm } from "../open-connection-form";
+import { currentDatabase, loadConnections, useDbExplorer } from "./db-explorer-store";
+import { ownDatabase } from "./explorer-model";
+import { openQueryTab, treePlace } from "./open-db-tabs";
+
+export async function openNewQuery(): Promise<void> {
+  if (!useDbExplorer.getState().loaded) await loadConnections();
+  const { connections } = useDbExplorer.getState();
+  const current = currentDatabase();
+  const conn = connections.find((c) => c.id === current?.conn) ?? connections[0];
+  if (!conn) {
+    openConnectionForm();
+    return;
+  }
+  const ref = current && current.conn === conn.id ? current : { conn: conn.id, database: ownDatabase(conn) };
+  openQueryTab(treePlace(conn, ref), "");
+}

package/src/web/components/database/explorer/open-new-table.ts

@@ -0,0 +1,37 @@
+/**
+ * DBGate's New table, from wherever it is asked for: a database's menu and its Tables "+" in the
+ * tree, the empty database's button, the command palette. Never on a connection that refuses
+ * writes, whose callers leave the entry out.
+ */
+import { useSettingsStore } from "@/stores/settings-store";
+import { currentDatabase, useDbExplorer } from "./db-explorer-store";
+import { dbKey, hasSchemaChoice, initialSchema, schemaOptions, type DbRef, type TreeConnection } from "./explorer-model";
+import { openNewTableTab, treePlace } from "./open-db-tabs";
+
+/** The schema a new table goes in: the one the tree shows for `ref` (Postgres), `public` until it has read them. */
+export function newTableSchema(conn: Pick<TreeConnection, "type">, ref: DbRef): string | null {
+  if (!hasSchemaChoice(conn.type)) return null;
+  const key = dbKey(ref);
+  const remembered = useSettingsStore.getState().dbExplorerView.schemas[key];
+  const list = useDbExplorer.getState().objects[key];
+  if (list?.state !== "ready") return remembered ?? "public";
+  return initialSchema(schemaOptions(list.data), remembered) ?? "public";
+}
+
+export function openNewTable(conn: TreeConnection, ref: DbRef): string {
+  return openNewTableTab(treePlace(conn, ref), newTableSchema(conn, ref));
+}
+
+/** The connection of the database the sidebar shows, when New table can be offered on it. */
+export function newTableConnection(): TreeConnection | null {
+  const current = currentDatabase();
+  const conn = current ? useDbExplorer.getState().connections.find((c) => c.id === current.conn) : undefined;
+  return conn && conn.readonly !== 1 ? conn : null;
+}
+
+/** From the palette: on the database the sidebar shows. */
+export function openNewTableOnCurrentDatabase(): void {
+  const current = currentDatabase();
+  const conn = newTableConnection();
+  if (current && conn) openNewTable(conn, current);
+}

package/src/web/components/database/explorer/sql-templates.ts

@@ -0,0 +1,110 @@
+/**
+ * The SQL the Database sidebar puts in a new query tab: a table's first SELECT, a routine called
+ * once, and the + menu's CREATE templates. The tab opens with the text in its editor and runs
+ * nothing — a template is there to be edited first.
+ *
+ * Written for each engine's own syntax; none of it is DBGate's text.
+ */
+import { dialectNameOf, type DbType } from "../../../../shared/db-types";
+import { quoteIdentifier } from "../../../../shared/sql-identifiers";
+import type { DbObject } from "../../../../shared/db-structure";
+
+/**
+ * The name to write in a query. A Postgres object carries its schema, which the query names so
+ * it reads the same whatever the search path; a MySQL object's schema is the database the tab
+ * already runs in, and SQLite has none.
+ */
+export function qualifiedName(o: Pick<DbObject, "schema" | "name">, type: DbType): string {
+  const dialect = dialectNameOf(type);
+  const name = quoteIdentifier(o.name, dialect);
+  return dialect === "postgres" && o.schema ? `${quoteIdentifier(o.schema, dialect)}.${name}` : name;
+}
+
+export function selectTemplate(o: Pick<DbObject, "schema" | "name">, type: DbType): string {
+  return `SELECT * FROM ${qualifiedName(o, type)} LIMIT 100`;
+}
+
+/** A routine called once, its arguments left for the user to fill in; null for a kind that cannot be called. */
+export function callTemplate(o: Pick<DbObject, "schema" | "name" | "kind" | "args">, type: DbType): string | null {
+  const args = o.args?.trim() ? `/* ${o.args.trim()} */` : "";
+  if (o.kind === "function") return `SELECT ${qualifiedName(o, type)}(${args})`;
+  if (o.kind === "procedure") return `CALL ${qualifiedName(o, type)}(${args})`;
+  return null;
+}
+
+/** The kind of routine the + menu offers a template for: Postgres writes functions, MySQL procedures, SQLite neither. */
+export function routineTemplateKind(type: DbType): "function" | "procedure" | null {
+  const dialect = dialectNameOf(type);
+  return dialect === "postgres" ? "function" : dialect === "mysql" ? "procedure" : null;
+}
+
+export function createViewTemplate(type: DbType): string {
+  const q = (n: string) => quoteIdentifier(n, dialectNameOf(type));
+  return `CREATE VIEW ${q("view_name")} AS\nSELECT\n  *\nFROM\n  ${q("table_name")};\n`;
+}
+
+export function createRoutineTemplate(type: DbType): string | null {
+  const kind = routineTemplateKind(type);
+  if (kind === "function") {
+    return [
+      "CREATE OR REPLACE FUNCTION function_name(arg integer)",
+      "RETURNS integer",
+      "LANGUAGE sql",
+      "AS $$",
+      "  SELECT arg + 1;",
+      "$$;",
+      "",
+    ].join("\n");
+  }
+  if (kind === "procedure") {
+    // DELIMITER lets the body's own semicolons through; the statement splitter understands it.
+    return [
+      "DELIMITER //",
+      "CREATE PROCEDURE procedure_name(IN arg INT)",
+      "BEGIN",
+      "  SELECT arg + 1;",
+      "END //",
+      "DELIMITER ;",
+      "",
+    ].join("\n");
+  }
+  return null;
+}
+
+export function createTriggerTemplate(type: DbType): string {
+  const dialect = dialectNameOf(type);
+  if (dialect === "postgres") {
+    return [
+      "CREATE OR REPLACE FUNCTION trigger_function_name()",
+      "RETURNS trigger",
+      "LANGUAGE plpgsql",
+      "AS $$",
+      "BEGIN",
+      "  RETURN NEW;",
+      "END;",
+      "$$;",
+      "",
+      "CREATE TRIGGER trigger_name",
+      "BEFORE INSERT ON table_name",
+      "FOR EACH ROW EXECUTE FUNCTION trigger_function_name();",
+      "",
+    ].join("\n");
+  }
+  if (dialect === "mysql") {
+    return [
+      "CREATE TRIGGER trigger_name",
+      "BEFORE INSERT ON table_name",
+      "FOR EACH ROW",
+      "SET NEW.column_name = NEW.column_name;",
+      "",
+    ].join("\n");
+  }
+  return [
+    "CREATE TRIGGER trigger_name",
+    "AFTER INSERT ON table_name",
+    "BEGIN",
+    "  SELECT NEW.rowid;",
+    "END;",
+    "",
+  ].join("\n");
+}

package/src/web/components/database/explorer/tree-parts.tsx

@@ -0,0 +1,109 @@
+/**
+ * The pieces both sections of the Database sidebar are drawn from: the section header that
+ * collapses it, the search box, the toolbar's icon buttons, a tree row's frame and the highlight
+ * of what a search matched. Sized for a mouse above `md` and for a finger (44px) below it.
+ */
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode, type Ref } from "react";
+import { ChevronDown, Search, X } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { highlightParts } from "./explorer-model";
+
+export const toolbarButtonClass =
+  "flex size-[26px] shrink-0 items-center justify-center rounded text-text-subtle hover:bg-surface-hover hover:text-foreground disabled:opacity-40 max-md:size-11";
+
+export function SectionHeader({ title, collapsed, onToggle, children }: {
+  title: string;
+  collapsed: boolean;
+  onToggle: () => void;
+  /** Shown at the header's end, e.g. the current database. */
+  children?: ReactNode;
+}) {
+  return (
+    <button type="button" onClick={onToggle} aria-expanded={!collapsed}
+      className="flex h-[30px] w-full shrink-0 items-center gap-1.5 pr-2.5 pl-2 text-left text-[11px] font-semibold tracking-[0.06em] whitespace-nowrap text-text-secondary uppercase hover:bg-surface-hover hover:text-foreground max-md:h-11 max-md:pr-3.5 max-md:pl-3 max-md:text-xs">
+      <ChevronDown className={cn("size-3 shrink-0 text-text-subtle transition-transform max-md:size-3.5", collapsed && "-rotate-90")} />
+      {/* The title gives way first: what follows it — the current database — is the part that changes. */}
+      <span className="min-w-0 truncate">{title}</span>
+      {children}
+    </button>
+  );
+}
+
+export function SearchBox({ value, onChange, placeholder, inputRef }: {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder: string;
+  inputRef?: Ref<HTMLInputElement>;
+}) {
+  return (
+    <div className="flex h-7 min-w-0 flex-1 items-center gap-1.5 rounded-[5px] border border-border bg-input pr-[3px] pl-2 text-xs text-text-subtle focus-within:border-primary max-md:h-11 max-md:text-sm">
+      <Search className="size-3.5 shrink-0" />
+      <input ref={inputRef} value={value} onChange={(e) => onChange(e.target.value)} placeholder={placeholder} aria-label={placeholder}
+        autoComplete="off" spellCheck={false}
+        className="h-full min-w-0 flex-1 border-0 bg-transparent text-foreground outline-none placeholder:text-text-subtle" />
+      {value && (
+        <button type="button" onClick={() => onChange("")} aria-label="Clear search" title="Clear search"
+          className="flex size-[22px] shrink-0 items-center justify-center rounded text-text-subtle hover:bg-surface-hover hover:text-foreground max-md:-mr-[3px] max-md:h-[42px] max-md:w-11">
+          <X className="size-3.5" />
+        </button>
+      )}
+    </div>
+  );
+}
+
+/** A search match marked in `text`; `text` as it is when the search did not look at it or found nothing there. */
+export function Highlight({ text, query }: { text: string; query: string }) {
+  const parts = highlightParts(text, query);
+  if (!parts) return <>{text}</>;
+  return <>{parts[0]}<mark className="rounded-[2px] bg-warning/35 text-inherit">{parts[1]}</mark>{parts[2]}</>;
+}
+
+interface TreeRowProps extends HTMLAttributes<HTMLDivElement> {
+  rowKey: string;
+  depth: number;
+  /** The row the list's own state picks: DBGate's focused connection, the table last opened. */
+  selected?: boolean;
+  /** Where the keyboard is. */
+  cursor?: boolean;
+  /** Lit for a moment: the connection just saved from its tab. */
+  flash?: boolean;
+  level: number;
+  expanded?: boolean;
+}
+
+/** One row of a tree: indented by depth, 26px (44px on a phone), text never selected by a long press. */
+export const TreeRow = forwardRef<HTMLDivElement, TreeRowProps>(function TreeRow(
+  { rowKey, depth, selected, cursor, flash, level, expanded, className, style, children, ...rest }, ref,
+) {
+  return (
+    <div ref={ref} role="treeitem" aria-level={level} aria-expanded={expanded} aria-selected={selected ?? false}
+      data-row-key={rowKey} data-cursor={cursor ? "" : undefined} data-flash={flash ? "edit" : undefined}
+      style={{ "--d": depth, ...style } as CSSProperties}
+      className={cn(
+        "mx-1 flex h-[26px] cursor-pointer items-center gap-[5px] rounded-[5px] pr-1.5 pl-[calc(2px+var(--d)*16px)] text-[13px] whitespace-nowrap text-text-secondary select-none",
+        "can-hover:hover:bg-surface-hover can-hover:hover:text-foreground",
+        "max-md:mx-1.5 max-md:h-11 max-md:gap-[7px] max-md:pl-[calc(6px+var(--d)*18px)] max-md:text-sm",
+        selected && "bg-accent-wash text-foreground can-hover:hover:bg-accent-wash",
+        cursor && "group-focus-visible/tree:ring-1 group-focus-visible/tree:ring-primary group-focus-visible/tree:ring-inset",
+        className,
+      )}
+      {...rest}>
+      {children}
+    </div>
+  );
+});
+
+/** The trailing, dimmed part of a row: an engine's name, a count, a type. */
+export function RowTail({ children, className, title }: { children: ReactNode; className?: string; title?: string }) {
+  return (
+    <span title={title} className={cn("ml-auto shrink-0 pl-1.5 text-[11px] text-text-subtle tabular-nums max-md:text-xs", className)}>
+      {children}
+    </span>
+  );
+}
+
+export function EmptyState({ children }: { children: ReactNode }) {
+  return <div className="mx-3.5 my-2.5 grid justify-items-start gap-1.5 text-xs text-text-subtle max-md:text-sm">{children}</div>;
+}
+
+export const linkButtonClass = "text-primary underline-offset-2 hover:underline max-md:min-h-11";

package/src/web/components/database/explorer/use-db-explorer-sync.ts

@@ -0,0 +1,25 @@
+/**
+ * What keeps the Database sidebar's tree in step while it is on screen: the connection list read
+ * on mount and again whenever the connections change elsewhere, the object list following the
+ * active tab, and whatever waited for a driver retried once it is installed.
+ */
+import { useEffect } from "react";
+import { useTabStore } from "@/stores/tab-store";
+import { useDbDriverInstalled } from "@/hooks/use-db-driver-installed";
+import { DB_CONNECTIONS_CHANGED, type DbConnectionsChangedDetail } from "../db-sidebar-reveal";
+import { followActiveTab, onConnectionsChanged, retryAfterDriverInstall, startExplorer, useDbExplorer } from "./db-explorer-store";
+
+export function useDbExplorerSync(): void {
+  useEffect(() => {
+    void startExplorer();
+    const onChanged = (e: Event) => { void onConnectionsChanged((e as CustomEvent<DbConnectionsChangedDetail>).detail ?? {}); };
+    window.addEventListener(DB_CONNECTIONS_CHANGED, onChanged);
+    return () => window.removeEventListener(DB_CONNECTIONS_CHANGED, onChanged);
+  }, []);
+
+  const activeTabId = useTabStore((s) => s.activeTabId);
+  const loaded = useDbExplorer((s) => s.loaded);
+  useEffect(() => { followActiveTab(); }, [activeTabId, loaded]);
+
+  useDbDriverInstalled(retryAfterDriverInstall);
+}

package/src/web/components/database/explorer/use-row-menu.ts

@@ -0,0 +1,37 @@
+/**
+ * One context menu for a whole tree, resolved from the row the gesture landed on, as the file
+ * tree does it. A mouse opens it on `contextmenu`; a finger fires `pointerdown` well before the
+ * long-press timer runs out. A row with no menu — a divider, a "loading" line, the empty space
+ * below the rows — opens none at all.
+ */
+import { useState, type SyntheticEvent } from "react";
+
+export function useRowMenu<E>(menuFor: (key: string | null) => E | null, setCursor: (key: string) => void): {
+  /** The menu for the row it last opened on. Not cleared on close: it would swap to nothing during its exit animation. */
+  entries: E | null;
+  /**
+   * Spread on the list inside the menu's trigger. `touchstart` is stopped on a row with no menu,
+   * so the adaptive menu's long-press — which is what handles `touchcancel` — never arms there.
+   */
+  listProps: {
+    onContextMenuCapture: (e: SyntheticEvent) => void;
+    onPointerDownCapture: (e: SyntheticEvent) => void;
+    onTouchStartCapture: (e: SyntheticEvent) => void;
+  };
+} {
+  const [menuKey, setMenuKey] = useState<string | null>(null);
+
+  const remember = (e: SyntheticEvent) => {
+    if (e.type === "pointerdown" && (e.nativeEvent as PointerEvent).pointerType === "mouse") return;
+    const key = (e.target as HTMLElement | null)?.closest?.<HTMLElement>("[data-row-key]")?.dataset.rowKey ?? null;
+    if (!menuFor(key)) {
+      if (e.type === "contextmenu") e.preventDefault();
+      if (e.type === "touchstart") e.stopPropagation();
+      return;
+    }
+    setMenuKey((prev) => (prev === key ? prev : key));
+    if (e.type === "contextmenu" && key) setCursor(key);
+  };
+
+  return { entries: menuFor(menuKey), listProps: { onContextMenuCapture: remember, onPointerDownCapture: remember, onTouchStartCapture: remember } };
+}

package/src/web/components/database/explorer/use-tree-keys.ts

@@ -0,0 +1,92 @@
+/**
+ * Keyboard for the Database sidebar's two trees, the way a tree view reads with the keyboard:
+ * the list holds focus and a cursor row (`aria-activedescendant`) moves with the arrows. Up and
+ * Down step through the rows, Right opens a row or steps into it, Left closes it or steps out to
+ * its parent, Home and End jump, Enter does what a double-click does, Space what a click does,
+ * and the context-menu key (or Shift+F10) opens the row's menu where the row is.
+ */
+import { useEffect, type KeyboardEvent, type RefObject } from "react";
+
+export interface TreeKeysOptions<R extends { key: string }> {
+  rows: readonly R[];
+  cursor: string | null;
+  setCursor: (key: string) => void;
+  listRef: RefObject<HTMLElement | null>;
+  /** Rows the cursor can stop on: not a divider or a "loading" line. */
+  focusable: (row: R) => boolean;
+  depthOf: (row: R) => number;
+  /** Right on a closed row: open it and answer true. False steps into its first child, if it has one. */
+  expand: (row: R) => boolean;
+  /** Left on an open row: close it and answer true. False steps out to its parent. */
+  collapse: (row: R) => boolean;
+  onEnter: (row: R) => void;
+  onSpace: (row: R) => void;
+}
+
+/** The id a row's element carries, for `aria-activedescendant`: row keys can hold spaces. */
+export function treeRowDomId(prefix: string, key: string): string {
+  return `${prefix}-${encodeURIComponent(key)}`;
+}
+
+/** The element of the row `key` in `list`, found by its `data-row-key`. */
+export function treeRowElement(list: HTMLElement | null, key: string): HTMLElement | null {
+  if (!list) return null;
+  for (const el of list.querySelectorAll<HTMLElement>("[data-row-key]")) if (el.dataset.rowKey === key) return el;
+  return null;
+}
+
+export function useTreeKeys<R extends { key: string }>(o: TreeKeysOptions<R>): (e: KeyboardEvent) => void {
+  const { rows, cursor, setCursor, listRef, focusable } = o;
+
+  // The cursor stays on screen as it moves.
+  useEffect(() => {
+    if (cursor !== null) treeRowElement(listRef.current, cursor)?.scrollIntoView?.({ block: "nearest" });
+  }, [cursor, listRef]);
+
+  return (e: KeyboardEvent) => {
+    if (e.target !== e.currentTarget) return; // an input inside the list (a folder being named) keeps its keys
+    const index = rows.findIndex((r) => r.key === cursor);
+    const row = index >= 0 ? rows[index] : undefined;
+    const step = (from: number, dir: 1 | -1): number => {
+      for (let i = from + dir; i >= 0 && i < rows.length; i += dir) if (focusable(rows[i]!)) return i;
+      return -1;
+    };
+    const go = (i: number) => { if (i >= 0) setCursor(rows[i]!.key); };
+    const openMenu = () => {
+      const el = cursor ? treeRowElement(listRef.current, cursor) : null;
+      if (!el) return;
+      const rect = el.getBoundingClientRect();
+      el.dispatchEvent(new MouseEvent("contextmenu", {
+        bubbles: true, cancelable: true, button: 2,
+        clientX: Math.round(rect.left + 24), clientY: Math.round(rect.top + rect.height / 2),
+      }));
+    };
+
+    switch (e.key) {
+      case "ArrowDown": go(step(index, 1)); break;
+      case "ArrowUp": go(index < 0 ? step(rows.length, -1) : step(index, -1)); break;
+      case "Home": go(step(-1, 1)); break;
+      case "End": go(step(rows.length, -1)); break;
+      case "ArrowRight": {
+        if (!row || o.expand(row)) break;
+        const next = step(index, 1);
+        if (next >= 0 && o.depthOf(rows[next]!) > o.depthOf(row)) go(next);
+        break;
+      }
+      case "ArrowLeft": {
+        if (!row || o.collapse(row)) break;
+        const depth = o.depthOf(row);
+        for (let i = index - 1; i >= 0; i--) {
+          if (focusable(rows[i]!) && o.depthOf(rows[i]!) < depth) { go(i); break; }
+        }
+        break;
+      }
+      case "Enter": if (row) o.onEnter(row); break;
+      case " ": if (row) o.onSpace(row); break;
+      case "ContextMenu": openMenu(); break;
+      case "F10": if (e.shiftKey) { openMenu(); break; } return;
+      default: return;
+    }
+    e.preventDefault();
+  };
+}