File size: 25,423 Bytes
82cdb59
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9edd100
82cdb59
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9edd100
 
82cdb59
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
// 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;
};