// sheet/LinkDialog.tsx — A CELL WEARING AN ATTACHMENT: its link, its note, and the four surfaces // those two need (wave 54, W54-T14, owner instruction 5, ruling R3). // // ⭐⭐ WHY A LINK AND A NOTE SHARE ONE FILE, AND THE NAME ON THE FILE IS ONLY HALF OF IT. // A link and a note are the two things a cell can carry that are NEITHER VALUE NOR STYLE. Neither // changes what the cell says, neither is read by a formula, and neither is drawn by the value // renderer: both are painted BESIDE the text, on the same canvas, out of the same mark vocabulary // (`paintCellMarks` below is one function drawing both, in one save/restore pair each). Splitting // them would put one line of canvas painting in a file of its own and leave a reader hunting for // the second half of a rule that is stated once here: the top-right corner belongs to the cell's // STATE mark, so an attachment never paints there. // // ⭐ WHAT THIS FILE EXPORTS, and which side of the seam each one lives on: // `LinkDialog` the authoring surface, opened from the Insert tab's Links group. All three // link kinds, validated at the door. // `paintCellMarks` the canvas half, called from `SheetGrid.tsx::paintCell` in BOTH of its // branches. No React, no CSS, no measurement of the cell's own text. // `NoteBubble` what a note shows on hover. // `followLink` resolve and follow, and say so in one sentence when the target is not there. // // ⛔ THE SERVER PARSES NEITHER HALF, AND THAT IS THE CONTRACT THIS FILE IS THE OTHER SIDE OF. // `platform/core/sheets.py::_clean_link` clamps the href and keeps BOTH halves or neither, because // the kind is what decides which door opens the target; it never asks whether a URL is reachable // or whether `Sheet2!B7` exists. Its own note puts that decision "in the door that opens it, which // can say so at the moment somebody clicks". `followLink` is that door. // // ⚠ THIS IS NOT `web_record_comments`. That gate governs the RECORD comment surface in the Data // module, which is a thread of authored comments hanging off a record. A cell note is one string // on one cell, with no author, no thread and no reply. Nothing here borrows its vocabulary. // // ⚠ DESIGN CONTRACT (DESIGN.md 2 through 5): tokens only and type on the scale, sentence case, no // emoji, inline SVG in this app's own glyph style, popovers originate at their trigger, refusals // are one sentence, and no em dash or en dash in any string that reaches a screen. import { useMemo, useState } from "react"; import type { FormEvent } from "react"; import { useCellRefHighlight } from "./refHighlight"; import type { Rectangle } from "@glideapps/glide-data-grid"; import { AnchoredOverlay } from "../customer-grid/OverlaySurface"; import type { AnchorRect } from "../customer-grid/OverlaySurface"; // ⭐ THE DOCUMENT'S OWN A1 PARSER. A cell link's target is spelled exactly the way a formula // reference is, so `Sheet2!B7` is split here by the same grammar that already reads one, rather // than by a second regular expression that would disagree with it on the day a sheet name gains // a space. `parseRef` returns the sheet name unquoted and the column as letters. import { colToIndex, parseRef } from "./a1"; // ⭐ THE PALETTE RESOLVER, IMPORTED AND NEVER REWRITTEN. `cellBorders.ts` owns the one memoised // `--lp-*` reader in this folder; a mark drawn on the canvas cannot be reached by CSS, so this is // how a canvas colour stays a token (DESIGN.md 2). import { tokenColour } from "./cellBorders"; import { MAX_LINK_HREF } from "./types"; import type { Cell } from "./types"; import "../styles/wave54/ribbon-insert.css"; /** The link a cell carries, with both halves present. `Cell["link"]` is the optional form. */ export type CellLink = NonNullable; // ═══════════════════════════════════════════════════════════════════════════════════════════════ // ⭐⭐ THE THREE KINDS, AND THE KIND IS WHAT DECIDES WHICH DOOR OPENS THE TARGET. // // `url` leaves the app entirely, in a new tab. // `cell` is an A1 address inside THIS workbook: bare (`B7`) on the sheet the link sits on, or // sheet qualified (`Summary!B7`) on any other tab of the same workbook. // `sheet` is a tab, by name. // // ⛔ THE HREF IS ONE STRING FOR ALL THREE, because that is the shape the store already keeps // (W54-T09 provisioned it and `verify_sheet.py` proves the round trip at 385/385). Widening it // into a discriminated payload would be a second answer to a question the document has settled. // ═══════════════════════════════════════════════════════════════════════════════════════════════ const KIND_LABEL: Record = { url: "Web address", cell: "Cell", sheet: "Sheet", }; /** Only a web address opens in a browser tab. Anything else is refused before `window.open`. */ const WEB_SCHEME = /^https?:\/\//i; /** Does this look like it already carries a scheme of its own? */ const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i; /** * ⭐ THE TAB NAMES, READ OFF THE TAB BAR, AND THIS IS A REACH RATHER THAN A PROP FOR A REASON. * `Ribbon.tsx::RibbonInsertDoor` carries a selection, the chart list and two cell doors, and it is * a file this ticket may not widen. The workbook's own tab bar is in the document with a stable * label, and `SheetGrid.tsx::switchTab` already reaches it exactly this way for Ctrl+PgUp, so this * is the app's existing door rather than a new one. * * ⛔ `[aria-pressed]` IS WHAT TELLS A SHEET FROM "Add sheet". That bar's trailing button is an * action rather than a tab and carries no pressed state, so filtering on the attribute is what * keeps a sheet list from growing a phantom sheet at the end. An empty answer is honest: the * dialog then asks for a typed name instead of pretending it knows the sheets. */ const sheetNamesOnScreen = (): string[] => { if (typeof document === "undefined") return []; return Array.from(document.querySelectorAll('[aria-label="Sheets"] button[aria-pressed]')) .map((button) => (button.textContent ?? "").trim()) .filter(Boolean); }; /** Case-insensitive, because a person typing `summary` means the tab called `Summary`. */ const matchSheet = (names: readonly string[], want: string): string | null => names.find((name) => name.toLowerCase() === want.trim().toLowerCase()) ?? null; // ═══════════════════════════════════════════════════════════════════════════════════════════════ // ⭐ THE AUTHORING SURFACE. // ═══════════════════════════════════════════════════════════════════════════════════════════════ function IconLinkKind({ kind }: { kind: CellLink["kind"] }) { return ( ); } /** * ⭐⭐ A POPOVER, NOT A MODAL, AND THE FILE NAME IS THE ONLY THING THAT SAYS OTHERWISE. DESIGN.md * 4: "Menus and popovers originate at their trigger; modals remain centered." This surface asks * for one short target and belongs beside the Link button that opened it, exactly as the Comment * form does one group over; the chart dialog is centred because it is a chooser with two tabs and * eight kinds. The overlay is mounted HERE rather than in `ribbonInsert.tsx` for the reason * `ChartDialog` is: a tab module is a function the ribbon shell calls during its own render and * cannot hold a hook, and a kind picker whose refusal survives a keystroke needs state. * * ⚠ NO LOCAL KEYDOWN LISTENER. Escape arrives through `AnchoredOverlay`, which registers with the * one arbiter in `ui/useEscapeClose.ts`, and from nowhere else (DESIGN.md 5). * * ⚠ `restoreFocus={false}` IS LOAD BEARING FROM THE RIBBON. Every ribbon button cancels its own * mouse-down so it never blurs the grid canvas, so the trigger never takes focus and the element * this would restore is THE CANVAS. `Ribbon.tsx::closePop` already returns focus to the trigger * and has to win. */ export default function LinkDialog({ anchor, held, onClose, onSubmit, }: { anchor: HTMLElement | null; /** What the anchor cell already carries, so a second Insert > Link EDITS rather than replaces. */ held?: CellLink; onClose: () => void; onSubmit: (link: CellLink) => void; }) { const sheets = useMemo(sheetNamesOnScreen, []); const [kind, setKind] = useState(held?.kind ?? "url"); const [href, setHref] = useState(() => (held?.kind === "url" ? held.href : "")); const [addr, setAddr] = useState(() => (held?.kind === "cell" ? held.href : "")); const [sheet, setSheet] = useState(() => ( held?.kind === "sheet" ? held.href : (sheets[0] ?? "") )); const [why, setWhy] = useState(""); // A link to a cell outlines that cell on the grid while the dialog is open (refHighlight.ts). useCellRefHighlight([kind === "cell" ? addr : ""]); const pick = (next: CellLink["kind"]) => { setKind(next); setWhy(""); }; /** * ⛔ VALIDATED AT THE DOOR, IN ONE SENTENCE (DESIGN.md 5). The server clamps the length and * stores whatever it is given, so this is the only place a person can be told that `B0` is not * an address before the link is saved and clicked. A web address with no scheme is COMPLETED * rather than refused, because `example.com` is what people type and `https` is what they mean. */ const submit = (event: FormEvent) => { event.preventDefault(); if (kind === "url") { const typed = href.trim(); if (!typed) { setWhy("Type a web address first."); return; } const full = HAS_SCHEME.test(typed) ? typed : `https://${typed}`; if (!WEB_SCHEME.test(full)) { setWhy("A web address has to start with http or https."); return; } onSubmit({ href: full.slice(0, MAX_LINK_HREF), kind: "url" }); return; } if (kind === "cell") { const typed = addr.trim(); const ref = parseRef(typed); if (!ref) { setWhy("That is not a cell address like B7 or Summary!B7."); return; } if (ref.sheet && sheets.length && !matchSheet(sheets, ref.sheet)) { setWhy(`This workbook has no sheet called ${ref.sheet}.`); return; } onSubmit({ href: typed.slice(0, MAX_LINK_HREF), kind: "cell" }); return; } const typed = sheet.trim(); if (!typed) { setWhy("Choose the sheet this cell should open."); return; } if (sheets.length && !matchSheet(sheets, typed)) { setWhy(`This workbook has no sheet called ${typed}.`); return; } onSubmit({ href: typed.slice(0, MAX_LINK_HREF), kind: "sheet" }); }; return (

Link this cell to

{/* ⭐ THREE BUTTONS RATHER THAN A SELECT, and they share one height and one baseline with each other (DESIGN.md 4). The choice is small, closed and worth seeing at a glance; `aria-pressed` is what a reader with a screen reader hears as the current kind. */}
{(["url", "cell", "sheet"] as const).map((option) => ( ))}
{kind === "url" && ( <> { setHref(event.target.value); setWhy(""); }} /> )} {kind === "cell" && ( <> { setAddr(event.target.value); setWhy(""); }} />

A cell on this sheet, or Summary!B7 for a cell on another sheet of this workbook.

)} {kind === "sheet" && ( <> {/* ⭐ THE TAB NAMES ARE OFFERED RATHER THAN TYPED wherever the tab bar is on screen. Where it is not, the field falls back to a text box and the refusal below is the only check left, which is the honest shape: this surface never claims to know a list it could not read. */} {sheets.length > 0 ? ( ) : ( { setSheet(event.target.value); setWhy(""); }} /> )} )} {why &&

{why}

}
); } // ═══════════════════════════════════════════════════════════════════════════════════════════════ // ⭐⭐ THE CANVAS HALF. ONE FUNCTION, TWO MARKS, AND IT IS CALLED FROM BOTH OF `paintCell`'S // BRANCHES. // // ⛔ IT PAINTS BESIDE THE TEXT AND NEVER RE-RENDERS IT. The unstyled branch has already handed the // cell to glide's own renderer and the styled branch has already laid the value out itself, so // measuring or re-drawing here would be a third answer to "what does this cell say" and a smear // on top of the second. // // ⛔ THE TOP-RIGHT CORNER IS TAKEN, AND THAT IS WHY THE NOTE MARK IS NOT WHERE EXCEL PUTS IT. // `SheetGrid.tsx::MARK_STYLE` owns that corner for the cell's STATE (R19's blue and yellow // triangles, the typed dot, the refused bar) and the validation caret sits on the right edge below // it. Two facts stacked in one corner is neither fact read, so the attachment mark takes the // TOP LEFT corner, which nothing else in this grid paints. The convention Excel is actually // setting is "a corner triangle means this cell carries something the value does not show", and // that survives the move; the exact corner does not. // // ⛔ NO CSS REACHES EITHER MARK. Both colours come from `--lp-*` tokens through `tokenColour`. // ═══════════════════════════════════════════════════════════════════════════════════════════════ /** How far in from a cell edge a mark sits, so the grid's own hairlines survive under it. */ const MARK_INSET = 1; /** The corner triangle's legs. Small enough to clear an ordinary value's first glyph. */ const MARK_LEG = 6; export const paintCellMarks = ( ctx: CanvasRenderingContext2D, rect: Rectangle, cell: Cell | null | undefined, ): void => { if (!cell) return; // ⭐ A LINK IS AN UNDERLINE, because that is the affordance a person recognises without being // told. It spans the cell's own text inset rather than the measured run: the run cannot be // measured here without adopting the font the branch above already chose, and an underline that // is a little wider than its word still reads as a link while a missing one reads as nothing. if (cell.link?.href) { ctx.save(); ctx.fillStyle = tokenColour("--lp-blue-solid", "#5b8fd9"); const y = Math.round(rect.y + rect.height / 2 + 7); ctx.fillRect(rect.x + 8, y, Math.max(0, rect.width - 16), 1); ctx.restore(); } // ⭐ A NOTE IS A CORNER INDICATOR, in the note stratum's own ink (`index.css` declares // `--lp-yellow-deep` as "note + Pre-set tag text", which is exactly this). if (cell.note) { ctx.save(); ctx.fillStyle = tokenColour("--lp-yellow-deep", "#7e6428"); ctx.beginPath(); ctx.moveTo(rect.x + MARK_INSET, rect.y + MARK_INSET); ctx.lineTo(rect.x + MARK_INSET + MARK_LEG, rect.y + MARK_INSET); ctx.lineTo(rect.x + MARK_INSET, rect.y + MARK_INSET + MARK_LEG); ctx.closePath(); ctx.fill(); ctx.restore(); } }; // ═══════════════════════════════════════════════════════════════════════════════════════════════ // ⭐ WHAT A NOTE SHOWS ON HOVER. // ═══════════════════════════════════════════════════════════════════════════════════════════════ /** * ⭐⭐ IT ORIGINATES AT ITS CELL, IT IS NOT MODAL, AND IT DOES NOT TAKE THE KEYBOARD. * * ⛔ `initialFocus="none"` AND `restoreFocus={false}` ARE THE WHOLE OF "does not steal the * keyboard from the grid". A hover surface that focused itself would move the caret off the canvas * every time a pointer crossed a noted cell, and the arrow keys would stop moving the selection. * With nothing inside focused, the kit's own restore has nothing to put back either. * * ⛔ IT IS POINTER TRANSPARENT (see the stylesheet). glide reports hover off the canvas UNDER * this box, so a bubble that took a pointer would hide the cell it is describing from the very * callback that opened it, and it would flicker. * * ⚠ Escape still reaches it, through `AnchoredOverlay` and the one arbiter, because an overlay * that cannot be dismissed by the key every other overlay answers is the defect DESIGN.md 5 names. */ export function NoteBubble({ anchor, note, onDismiss, }: { anchor: AnchorRect | null; note: string; onDismiss: () => void; }) { if (!note) return null; return (

{note}

); } // ═══════════════════════════════════════════════════════════════════════════════════════════════ // ⭐⭐ THE DOOR THAT OPENS THE TARGET, AND THE ONE PLACE THAT CAN SAY IT IS NOT THERE. // ═══════════════════════════════════════════════════════════════════════════════════════════════ /** What `followLink` needs from the grid, and nothing more. */ export interface FollowContext { /** Every tab of this workbook, in the tab bar's own order. */ sheets: readonly { id: string; name: string }[]; /** The tab the grid is showing right now. */ tabId: string; /** Show a tab, by id. */ goToSheet: (sheetId: string) => void; /** Put the selection on a zero-based SHEET cell of that tab, switching tabs first if it must. */ goToCell: (sheetId: string, col: number, row: number) => void; /** One sentence, and only ever one (DESIGN.md 5). */ onNotice: (message: string) => void; } /** * Follow the link this cell carries. `false` means the cell carries none, which is what lets a * click handler ask and fall through to its ordinary behaviour in one line. * * ⛔ EVERY REFUSAL IS ONE SENTENCE AND IS SAID AT THE MOMENT OF THE CLICK, which is where * `platform/core/sheets.py` deliberately left it: the store keeps a target it never checked, so * the check has to be here or it never happens at all. */ export const followLink = (cell: Cell | null | undefined, ctx: FollowContext): boolean => { const link = cell?.link; if (!link?.href) return false; if (link.kind === "url") { if (!WEB_SCHEME.test(link.href)) { ctx.onNotice("This link is not a web address, so it cannot be opened."); return true; } // ⛔ `noopener,noreferrer` IS THE SECURITY HALF, not a preference: without `noopener` the page // that opens keeps a handle on this one through `window.opener` and can navigate it. // // ⛔⛔ AND THE RETURN VALUE IS NOT AN ANSWER. `noopener` severs the handle BY DEFINITION, so // the spec has `window.open` answer `null` on SUCCESS as well as on a blocked pop-up. Driven // headless the day this was written: the tab really opened and the null check said the browser // had blocked it, which is a refusal sentence in front of a person whose link worked. There is // no way to tell the two apart while keeping the security half, so the security half wins and // nothing is claimed about the result. window.open(link.href, "_blank", "noopener,noreferrer"); return true; } if (link.kind === "sheet") { const found = ctx.sheets.find( (sheet) => sheet.name.toLowerCase() === link.href.trim().toLowerCase(), ); if (!found) { ctx.onNotice(`This workbook has no sheet called ${link.href}.`); return true; } ctx.goToSheet(found.id); return true; } const ref = parseRef(link.href); if (!ref) { ctx.onNotice(`${link.href} is not a cell address, so there is nothing to open.`); return true; } // ⚠ A BARE ADDRESS MEANS THE SHEET THE LINK SITS ON, which is the tab the grid is showing: the // link was authored there and it is stored on a cell of that tab. Only a qualified one is looked // up by name, and only that one can fail to find a sheet. const targetId = ref.sheet ? (ctx.sheets.find((sheet) => sheet.name.toLowerCase() === ref.sheet.toLowerCase())?.id ?? null) : ctx.tabId; if (!targetId) { ctx.onNotice(`This workbook has no sheet called ${ref.sheet}.`); return true; } ctx.goToCell(targetId, colToIndex(ref.col) - 1, ref.row - 1); return true; };