runloopable / web /src /sheet /LinkDialog.tsx
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
9edd100 verified
Raw History Blame Contribute Delete
25.4 kB
// 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<Cell["link"]>;
// ═══════════════════════════════════════════════════════════════════════════════════════════════
// ⭐⭐ 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<CellLink["kind"], string> = {
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<HTMLElement>('[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 (
<svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-link-kind-icon">
{kind === "url" && (
<>
<circle cx="8" cy="8" r="5.5" />
<path d="M2.5 8h11" />
<path d="M8 2.5c1.6 1.7 2.4 3.6 2.4 5.5S9.6 12.3 8 13.5C6.4 12.3 5.6 10.4 5.6 8S6.4 4.2 8 2.5z" />
</>
)}
{kind === "cell" && (
<>
<path d="M2.5 2.5h11v11h-11z" />
<path d="M2.5 6.5h11M6.5 6.5v7" />
</>
)}
{kind === "sheet" && (
<>
<path d="M2.5 4.5h5l1.2 1.6h4.8v7.4h-11z" />
<path d="M2.5 8.5h11" />
</>
)}
</svg>
);
}
/**
* ⭐⭐ 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<CellLink["kind"]>(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<HTMLFormElement>) => {
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 (
<AnchoredOverlay
anchor={anchor}
className="sheet-ribbon-pop sheet-ribbon-pop-portal sheet-ribbon-insert-form sheet-link-form"
onDismiss={onClose}
role="dialog"
ariaLabel="Link"
restoreFocus={false}
>
<form className="sheet-ribbon-insert-fields" onSubmit={submit}>
<p className="sheet-ribbon-insert-title">Link this cell to</p>
{/* ⭐ 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. */}
<div className="sheet-link-kinds" role="group" aria-label="Link kind">
{(["url", "cell", "sheet"] as const).map((option) => (
<button
key={option}
type="button"
className="sheet-link-kind"
aria-pressed={kind === option}
onClick={() => pick(option)}
>
<IconLinkKind kind={option} />
<span>{KIND_LABEL[option]}</span>
</button>
))}
</div>
{kind === "url" && (
<>
<label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-link">
Web address
</label>
<input
id="sheet-insert-link"
name="href"
type="text"
className="sheet-ribbon-insert-input"
maxLength={MAX_LINK_HREF}
placeholder="https://"
value={href}
onChange={(event) => { setHref(event.target.value); setWhy(""); }}
/>
</>
)}
{kind === "cell" && (
<>
<label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-link-cell">
Cell address
</label>
<input
id="sheet-insert-link-cell"
name="addr"
type="text"
className="sheet-ribbon-insert-input"
maxLength={MAX_LINK_HREF}
placeholder="B7"
value={addr}
onChange={(event) => { setAddr(event.target.value); setWhy(""); }}
/>
<p className="sheet-ribbon-insert-hint">
A cell on this sheet, or Summary!B7 for a cell on another sheet of this workbook.
</p>
</>
)}
{kind === "sheet" && (
<>
<label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-link-sheet">
Sheet
</label>
{/* ⭐ 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 ? (
<select
id="sheet-insert-link-sheet"
name="sheet"
className="sheet-link-select"
value={sheet}
onChange={(event) => { setSheet(event.target.value); setWhy(""); }}
>
{sheets.map((name) => (
<option key={name} value={name}>{name}</option>
))}
</select>
) : (
<input
id="sheet-insert-link-sheet"
name="sheet"
type="text"
className="sheet-ribbon-insert-input"
maxLength={MAX_LINK_HREF}
placeholder="Summary"
value={sheet}
onChange={(event) => { setSheet(event.target.value); setWhy(""); }}
/>
)}
</>
)}
{why && <p className="sheet-ribbon-insert-refusal" role="alert">{why}</p>}
<button type="submit" className="sheet-ribbon-item">
{held ? "Update link" : "Add link"}
</button>
</form>
</AnchoredOverlay>
);
}
// ═══════════════════════════════════════════════════════════════════════════════════════════════
// ⭐⭐ 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 (
<AnchoredOverlay
anchor={anchor}
className="sheet-note-bubble"
onDismiss={onDismiss}
placement="bottom-start"
role="note"
ariaLabel="Cell note"
initialFocus="none"
restoreFocus={false}
>
<p className="sheet-note-bubble-text">{note}</p>
</AnchoredOverlay>
);
}
// ═══════════════════════════════════════════════════════════════════════════════════════════════
// ⭐⭐ 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;
};