// --------------------------------------------------------------------------- // shell/NavExtras.tsx — C-SCHEMA (wave 2026-08-02): the database list's // three-dots menu, folder heads, and the schema drawer. // // Kept out of Shell.tsx so the shell's frame stays readable: Shell owns the // STATE (prefs, open folders, which schema is open) and the save round-trip; // these components own only their own popover/drawer chrome. Menus are // position:fixed against the trigger — the rail scrolls and clips, so an // absolutely-positioned child could never escape it (the same lesson as the // collapsed-rail tooltip). // --------------------------------------------------------------------------- import { useEffect, useRef, useState } from "react"; import type { ReactNode } from "react"; import { fetchSchema, saveSchemaMap } from "./nav"; import type { NavFolder, SchemaPayload, TableFootprint } from "./nav"; import { WORKSPACE_STALE_EVENT, signal } from "../apiContract"; // W51-T31 — the rail's own overlays join the ONE Escape stack (C8 / DESIGN.md §4). Each // registration is gated on that overlay's OWN open flag: the arbiter preventDefaults a claimed // Escape, and Escape is also the browser's cancel-this-drag key for the folder drag-and-drop. import { useEscapeClose } from "../ui/useEscapeClose"; // ⚠ WAVE 19 R8 / C1 — IMPORTED, NEVER REDEFINED, and the contract says so in as // many words ("Shapes/tones = the grid's existing vocabulary verbatim (12 // shapes, 5 tones); B imports, never redefines"). A second copy of this // vocabulary in the shell is a whitelist that can drift by one member from the // one the host validates against — and a tone the server does not recognise // degrades to the default, so the user's choice disappears on reload with // nothing on screen to say why. These are READ-ONLY imports across the session // fence: `customer-grid/**` is another session's tree this wave (HARD RULE 3). import "./navExtras.css"; // ⭐ W46-T45 / C6 — AFTER `navExtras.css`, DELIBERATELY AND ALWAYS. The wave sheet // re-shapes the schema drawer onto the Settings modal's values, so it must land // LATER in the bundle than the sheet it overrides; a wave sheet is imported by // the component that owns its surface and never added to `index.css`, which // would give a lane-local override a global blast radius. Every selector in it // is additionally anchored on `.shell-schema`, so it wins on specificity too // and does not rest on import order alone. import "../styles/wave46/schema-viewer.css"; /** * WAVE 21 item 12 (ruling R11) — HORIZONTAL, and it is the same three dots turned * 90°, not a different mark. * * The rail and the views list are read as one surface, and they were drawing the * "there is a menu here" affordance two different ways: this glyph stacked its * circles (cx fixed, cy walking) while `ViewSidebar`'s row buttons have always * rendered three MIDDLE DOTs on the baseline. Same promise, two pictures — the * thing R11 names. Only the axis moves: radius, viewBox and the 14px box in * `navExtras.css` are untouched, so the hit target and the optical weight are * exactly what shipped. */ function DotsIcon() { return ( ); } /** * W46-T45 (owner instruction 23) — the mark on "View schema". * * ⛔ LOCAL, NOT `customer-grid/iconShapes.ts`. That module is the GRID's shape * vocabulary (the 12 shapes a database icon may take) and belongs to another * session's tree; DESIGN.md §4 counts shell glyphs as part of the same * vocabulary but the shell draws its own, exactly as `DotsIcon`, `PlusIcon` and * `FixedFolderMark` above already do. Same grammar as `PlusIcon`: a 16-square * viewBox, `aria-hidden` because the row's own words are the label, no fill, * `currentColor` for the stroke, and every dimension in CSS rather than an * inline style. * * ⚠ A TABLE GRID, NOT A FOLDER. The folder mark already means "a folder in the * rail" here, and a second meaning on the same picture is the drift a shared * vocabulary exists to prevent. Header rule plus one column divider reads as * "the shape of the data", which is what the panel behind it shows. */ function SchemaIcon() { return ( ); } function FixedFolderMark() { return ( ); } /** A fixed-position popover anchored to a trigger rect, closed on outside * click or Escape. Small on purpose — the shell does not import the grid's * Popover, so the two chrome trees stay independently deletable. */ function useMenu() { const [at, setAt] = useState<{ x: number; y: number } | null>(null); const ref = useRef(null); // W51-T31 — Escape resolves through the shared stack, so a menu opened while a dialog is // already up no longer races it on listener registration order. Outside-click stays local: // this popover is not portalled and has no anchor to hand the grid's primitive. useEscapeClose(at !== null, () => setAt(null), { container: () => ref.current }); useEffect(() => { if (!at) return; const onDown = (e: MouseEvent) => { if (ref.current && !ref.current.contains(e.target as Node)) setAt(null); }; document.addEventListener("mousedown", onDown, true); return () => document.removeEventListener("mousedown", onDown, true); }, [at]); const openFrom = (el: HTMLElement) => { const r = el.getBoundingClientRect(); setAt({ x: Math.round(r.right + 4), y: Math.round(r.top) }); }; return { at, ref, openFrom, close: () => setAt(null) }; } function MenuShell({ at, menuRef, wide, children, }: { at: { x: number; y: number }; menuRef: React.RefObject; /** WAVE 21 item 6 — the delete confirm needs prose width; a menu of one-line * actions does not. The CLAMP moves with the class, because a wider panel * clamped at the narrow width spills off the right edge on exactly the rows * furthest from it. */ wide?: boolean; children: ReactNode; }) { // Clamp to the viewport so a row near the bottom does not spill the menu off it. const width = wide ? 320 : 248; const style = { left: Math.min(at.x, Math.max(8, window.innerWidth - width)), top: Math.min(at.y, Math.max(8, window.innerHeight - 260)), }; return (
{children}
); } export function RowMenu({ entryLabel, canSchema, onSchema, canRename, onRename, onShare, canDelete, onLoadFootprint, onDelete, }: { entryLabel: string; canSchema: boolean; onSchema: () => void; /** * WAVE 19 R8 — rename is `ut_*` (custom) DATABASES ONLY, and this flag is how * the row says so. A built-in label is a compiled registry literal: renaming * `customer_data` would mean the nav and every other reader of * `core/registry.py` disagreeing about what the module is called. The SERVER * refuses a `name` for a non-`ut_` key regardless (C1, fail-closed) — this * only spares the user a control whose write would bounce. */ canRename?: boolean; onRename?: (name: string) => void; /** WAVE 20 item 18 (C-SHARE) — open the access editor for THIS database. * Absent = the row does not offer sharing (a group head has nothing to share). */ onShare?: () => void; /** * ⭐ WAVE 21 item 6 (ruling R3, contract C3, wiring W-5) — may this session * DELETE this database? * * ⛔ REQUIRED, NOT OPTIONAL, and that is the wave-20 lesson written into a type. * Four features shipped dead behind 43 green gates because the prop that carried * them across an ownership fence was `?`-marked: an unmounted optional prop is * `undefined`, which reads as "the feature is off" and is indistinguishable from * "the feature was never built". A required prop makes the unmounted case a * COMPILE ERROR. The value is the server's (`NavPage.canDelete`), narrower than * `manage` on purpose — see the note there. */ canDelete: boolean; /** What deleting would destroy. Resolves null when the server would not say — * the face then asks WITHOUT counts rather than inventing zeros. */ onLoadFootprint: () => Promise; /** Do it. Resolves the server's own words on refusal, which the face shows in * place of the confirmation — a delete that failed must never look like one * that worked. */ onDelete: () => Promise<{ ok: boolean; error?: string }>; }) { const { at, ref, openFrom, close } = useMenu(); // Which face the popover is showing. Reset on every open, so a menu that was // left mid-rename does not reopen into somebody else's half-typed name. const [mode, setMode] = useState<"menu" | "rename" | "delete">("menu"); const [name, setName] = useState(entryLabel); /** * WAVE 21 item 6 — the delete face's own state. `footprint: undefined` means * "still asking", `null` means "the server would not say" — two different * things the face words differently, which is why it is not a plain object. */ const [del, setDel] = useState<{ footprint?: TableFootprint | null; busy: boolean; error: string; }>({ busy: false, error: "" }); const renameOn = !!canRename && !!onRename; if (!canSchema && !renameOn && !onShare && !canDelete) return null; const submitRename = () => { const clean = name.trim().replace(/\s+/g, " "); if (clean && clean !== entryLabel) onRename?.(clean); close(); }; /** * ⚠ THE FOOTPRINT IS FETCHED WHEN THE FACE OPENS, NOT WHEN THE MENU DOES. * Same reasoning as `PermsEditor.prepareCopy` ("the targets are fetched BEFORE * the confirm"): the question has to name what is being destroyed, and a * confirm written from the rail's own knowledge can only name the table. The * cost is paid by the person who clicked Delete, never by everyone who opened * a menu. */ const openDelete = () => { setDel({ busy: false, error: "" }); setMode("delete"); void onLoadFootprint().then((f) => setDel((cur) => ({ ...cur, footprint: f }))); }; const runDelete = () => { setDel((cur) => ({ ...cur, busy: true, error: "" })); void onDelete().then((r) => { if (r.ok) { close(); setDel({ busy: false, error: "" }); return; } // ⛔ THE MENU STAYS OPEN ON A REFUSAL. Closing it would leave a rail whose // row is still there and no statement anywhere about why — which reads as // "the click did nothing" and invites a second one. setDel((cur) => ({ ...cur, busy: false, error: r.error || "It could not be deleted." })); }); }; return ( <> {at && ( {mode === "delete" && canDelete ? ( setMode("menu")} onConfirm={runDelete} /> ) : mode === "rename" && renameOn ? (
{ e.preventDefault(); submitRename(); }} > setName(e.target.value)} // W51-T31 — no Escape branch here. The menu that contains this form owns the // key through `useEscapeClose`, which claims it in the capture phase, so a // handler on the input could never run and would read as the live one. />
) : ( <> {renameOn ? ( ) : null} {canSchema ? ( ) : null} {/* WAVE 20 item 18 (R10, C-SHARE) — a DATABASE shares with the same two roles a view does. Gated on `onShare`, which the Shell passes only for a real database row, so a family head or a hand-off link never offers to share something that has no id on the server. */} {onShare ? ( ) : null} {/* ⭐ WAVE 21 item 6 (R3) — LAST, and the only destructive row in this menu. Gated on the server's `canDelete` alone: R3 scopes the verb to the CREATOR or an admin and refuses it outright for connector-backed databases, so a row that may not be deleted does not say so — it simply has nothing here to click. (An entry that explains why it is disabled is the right pattern for a thing you could earn; this one you cannot.) */} {canDelete ? ( ) : null} )}
)} ); } /** One footprint line: "12 records", "1 view". Singular/plural is the whole of * the formatting, because a count with the wrong noun reads as a bug in the * count. */ function countLine(n: number, one: string, many: string): string { return `${n.toLocaleString()} ${n === 1 ? one : many}`; } /** * ⭐ WAVE 21 item 6 (R3, contract C3) — the confirm face: what deleting this * database destroys, stated before the button that does it. * * Shaped after `PermsEditor`'s confirm (`.set-confirm`, the strongest one this * codebase has) and not after a `window.confirm`: the browser dialog cannot say * anything specific, and a destructive question whose answer depends on facts * the asker has not been given is not really being asked. * * THREE STATES, worded differently on purpose: * · footprint undefined — still asking the server. The button is disabled; * confirming against numbers that have not arrived is confirming against * nothing. * · footprint null — the server would not say. The question is put * WITHOUT counts and says so. Inventing zeros here would be a specific, * checkable claim about the user's data that nobody verified * ([[no-unverifiable-aggregates]]). * · footprint present — every family it names, listed. * * ⚠ The automations line is the one that is NOT about destruction: C3 pauses * bound automations and stamps them "target deleted" rather than removing them, * so it names them (they will still be there afterwards, switched off) instead * of counting them away. */ function DeleteFace({ entryLabel, state, onCancel, onConfirm, }: { entryLabel: string; state: { footprint?: TableFootprint | null; busy: boolean; error: string }; onCancel: () => void; onConfirm: () => void; }) { const f = state.footprint; const asking = f === undefined; return (

Delete “{entryLabel}”?

{asking ? (

Checking what this database holds…

) : f === null ? (

The server did not say what this database holds. Deleting it removes its records, columns, views, comments, documents and sharing, permanently.

) : ( <>

This cannot be undone. It permanently removes:

  • {countLine(f.rows, "record", "records")}
  • {countLine(f.fields, "column", "columns")}
  • {countLine(f.views, "view", "views")}
  • {countLine(f.sharedUsers, "person it is shared with", "people it is shared with")}
{f.automations.length ? (

{/* The VERB agrees too. "1 automation write here" was on screen before the first screenshot was read — the kind of thing every assertion passes. */} {countLine(f.automations.length, "automation", "automations")}{" "} {f.automations.length === 1 ? "writes" : "write"} here ( {f.automations.map((a) => a.name).join(", ")}) — {f.automations.length === 1 ? "it is" : "they are"}{" "} switched off, not deleted.

) : null} )} {state.error ?

{state.error}

: null}
); } function PlusIcon() { return ( ); } /** * Wave 14 C-NAVFOLD gave the list's bottom a quiet "+ New folder" (the Views-rail * precedent). WAVE 19 R11 made it "+ Create new…" with Folder | Database behind it. * * ⭐ WAVE 24 items 1 + 15a (ruling R9) — IT LEAVES THE RAIL AND BECOMES THE DATABASE * FLYOUT'S FOOTER, and it now carries the creatable things: New database · * From a template · New folder. The flyout's three standalone `.shell-dbfly-make` * buttons are deleted; this one control replaces them. * * ⭐ WAVE 25 item 5a (ruling R8) — "AUTOMATED DATABASE" IS DELETED FROM THIS MENU, * so it carries THREE rows rather than four. R8: creating a database is one act and * pointing an automation at it is another, so the automation door lives on the * automation surface (its rail button and its empty state) and this menu stops * offering a database that is really an automation. * ⚠ `From a template` and `New folder` are UNTOUCHED — neither was ever an automated * database, and R9 keeps the template door working here (see the Home card's own note * on why exactly one of the two template doors is boarded). * * ⭐ WAVE 14's item 1 WAS ALSO A TYPOGRAPHY FIX, and it is worth keeping the * measurement because wave 47 finished the job from the other end. MEASURED on * staging v12: the six rail rows all rendered 13.8125px / w500 / Inter / * rgb(32,36,51) — identical, `` and ` ); } if (!naming) { return ( <> {/* THE LABEL NO LONGER FOLLOWS `canFolder`. In the rail it had to: with one real branch, "+ Create new…" beside an `aria-haspopup` was a control promising a choice it was not about to offer. In the footer there are always at least two (database / template), so the menu is real whatever the tenant has and the label can simply be true. ⚠ TWO, NOT THREE, since R8 took the automated row (wave 25) — still a genuine choice, which is the property the label depends on. If a future ruling takes the template row as well, this reasoning inverts and the control has to become a plain button again. */} {/* ⭐ WAVE 47 T10 (owner instruction 1) — THIS ROW WEARS THE VIEW LAYER'S REGISTER, not its own. Owner, verbatim: *"The '+ Create new...' format for the Database and when we get to the folder path in the database is different visually. I like the one that is formatted under the database, with the lighter color, fix it so it visually doesn't jump"*. `cg-link-btn cg-create-btn` + the `cg-create-icon` / `cg-create-label` spans are LITERALLY the markup `ViewSidebar.tsx`'s own create door renders, and `index.css` is the app-global sheet, so this is one class set read by two call sites rather than two class sets kept in step by hand. That second shape is what drifted: see the register comparison in this component's own doc block. ⛔ `aria-expanded` is not decoration here. `.cg-create-btn[aria-expanded="true"]` is what paints the HELD state while the menu is open, so the visual state is driven off the accessible one and there is no second source of truth to forget. */} {at && ( {canFolder ? ( ) : null} )} ); } return (
{ e.preventDefault(); submit(); }} > setName(e.target.value)} onKeyDown={(e) => { if (e.key === "Escape") { setName(""); setNaming(false); } }} />
); } export function FolderHead({ folder, count, open, collapsed, onToggle, onRename, onDelete, isDrop, dropProps, }: { folder: NavFolder; count: number; /* ⛔ WAVE 35 · T07 (owner item 9) — the `important?: NavImportant` prop is DELETED. It carried wave-34 R1's per-folder SUM of mark-important numbers; item 9 retires that badge, and `tsc`'s unused-locals check is what named this prop the moment its only reader went. */ open: boolean; collapsed: boolean; onToggle: () => void; onRename: (name: string) => void; onDelete: () => void; /** Wave 14 C-NAVFOLD — a database row is being dragged over this folder. */ isDrop?: boolean; /** dragover/drop handlers, owned by the Shell (it holds the placement writer). */ dropProps?: React.HTMLAttributes; }) { const { at, ref, openFrom, close } = useMenu(); const [renaming, setRenaming] = useState(false); const [name, setName] = useState(folder.name); const submit = () => { const clean = name.trim().replace(/\s+/g, " "); if (clean && clean !== folder.name) onRename(clean); setRenaming(false); close(); }; if (collapsed) { // The folded rail has no room for folder chrome; members render flat and the // folder simply waits for the rail to open again. return null; } return (
{/* R3: no chevron — the Views-rail folder look. Open state reads from the members below it (and aria-expanded says it aloud); the mark + bold label ARE the row. */} {at && ( {renaming ? (
{ e.preventDefault(); submit(); }} > setName(e.target.value)} />
) : ( )}
)}
); } export function SchemaDrawer({ schemaKey, onClose, }: { schemaKey: string; onClose: () => void; }) { const [state, setState] = useState< { phase: "loading" } | { phase: "ready"; schema: SchemaPayload } | { phase: "error" } >({ phase: "loading" }); const [mapSaving, setMapSaving] = useState(false); const [mapError, setMapError] = useState(""); const [mapDraft, setMapDraft] = useState({ latField: "", lonField: "" }); useEffect(() => { let cancelled = false; setState({ phase: "loading" }); setMapSaving(false); setMapError(""); setMapDraft({ latField: "", lonField: "" }); fetchSchema(schemaKey).then((schema) => { if (cancelled) return; setState(schema ? { phase: "ready", schema } : { phase: "error" }); if (schema) { setMapDraft({ latField: schema.map.latField ?? "", lonField: schema.map.lonField ?? "", }); } }); return () => { cancelled = true; }; }, [schemaKey]); // W51-T31 — the schema drawer is only ever rendered while it is open, so its entry is // unconditionally active; the stack still resolves Escape to whichever overlay is on top. useEscapeClose(true, onClose); const mapPairIncomplete = Boolean(mapDraft.latField) !== Boolean(mapDraft.lonField); const saveMap = async () => { if (state.phase !== "ready" || !state.schema.map.canConfigure || mapSaving) return; if (mapPairIncomplete) { setMapError("Choose both a latitude and a longitude field, or leave both on Built-in."); return; } setMapSaving(true); setMapError(""); const map = await saveSchemaMap( schemaKey, mapDraft.latField || undefined, mapDraft.lonField || undefined, ); setMapSaving(false); if (!map) { setMapError("The Map setup was not saved. Try again."); return; } setState((current) => current.phase === "ready" ? { ...current, schema: { ...current.schema, map } } : current); setMapDraft({ latField: map.latField ?? "", lonField: map.lonField ?? "" }); // Map consumes this database-owned setting from its workspace envelope. Reuse the existing // refresh signal so an open Map changes immediately without coupling the shell to grid state. signal(WORKSPACE_STALE_EVENT); }; return (
); }