// --------------------------------------------------------------------------------------------- // sheet/clipboardOps.ts — WHAT A COPY OUT OF THE SHEET IS MADE OF, LIFTED OUT OF `SheetGrid.tsx`. // // ⭐ WAVE 54 BASE KIT — a SEAM, not a redesign. The body below was moved verbatim out of // `SheetGrid.tsx::heldFor`; the component keeps a one-line `useCallback` around it so both copy // doors (the ribbon's button and glide's own native Ctrl+C) still share ONE builder and both // dependency arrays are unchanged. // // ⭐⭐ AND `copySelection` HAS NOW FOLLOWED IT, WHICH THE NOTE ABOVE THIS ONE USED TO REFUSE. The // refusal was right at the time and is worth keeping, because it names the trap: it closes over // six pieces of component state (`viewRange`, `onNotice`, `heldFor`, `copiedRef`, `setCopyMarquee` // and `clearSelection`), and `verify_grid_ux.py`'s copy-marquee leg asserted its marquee literal // INSIDE `SheetGrid.tsx`, so moving it under a no-behaviour-change brief would have reddened a // gate about a claim that was still true. Wave 54 re-aimed that leg to read THIS file instead: it // asserts where the marquee is set FROM, which is a claim about the code, and the code moved. The // six values are ARGUMENTS now, and the component keeps a `useCallback` whose dependency array is // unchanged, exactly as it already does for `heldFor`. // // ⛔ AND `pasteCells` IS NOT HERE EITHER. It already lives in `sheetState.ts` and is imported from // there by both paste doors; a second home for it would be a second answer to the same question. // --------------------------------------------------------------------------------------------- import type { CellRange } from "./sheetState"; // ⭐⭐ W54-T15: `rememberCopy` is the IN APP CLIPBOARD, and it lives in `sheetState.ts` beside // the one paste engine that reads it. The import direction is this file -> `sheetState.ts`, which // is the direction that already existed for `displayText`; the reverse would be a cycle. import { editableText, pasteOptionsOf, rawDisplayText, rememberCopy, rememberCut } from "./sheetState"; import type { Cell, CellMap } from "./types"; import { formatCellText } from "./types"; import type { WholeAxis } from "./shortcuts"; import { wholeAxisOf } from "./shortcuts"; /** The three clipboard layers a paste command may apply. Normal is the full cell payload. */ export const PASTE_MODES = ["normal", "values", "formatting"] as const; export type PasteMode = (typeof PASTE_MODES)[number]; /** Narrow a ribbon argument at the clipboard boundary; unknown arguments remain normal paste. */ export const pasteModeFrom = (value: unknown): PasteMode => value === "values" || value === "formatting" ? value : "normal"; /** C8: every paste door names its layers through this one option list. */ export const PASTE_WHAT = [ "all", "all-source-theme", "formulas", "all-except-borders", "values", "column-widths", "formats", "formulas-number-formats", "comments", "values-number-formats", "validation", "all-merging-cf", "keep-source-formatting", "values-source-formatting", "no-borders", "keep-source-column-widths", ] as const; export const PASTE_OPERATIONS = ["none", "add", "subtract", "multiply", "divide"] as const; export type PasteWhat = (typeof PASTE_WHAT)[number]; export type PasteOperation = (typeof PASTE_OPERATIONS)[number]; export type PasteOptions = { what: PasteWhat; operation?: PasteOperation; skipBlanks?: boolean; transpose?: boolean; link?: boolean; }; /** Ribbon arguments retain the legacy aliases while accepting every C8 layer name. */ export const pasteOptionsFrom = (value: unknown): PasteOptions => { if (typeof value !== "string") return { what: "all" }; if (PASTE_MODES.includes(value as PasteMode)) return pasteOptionsOf(value as PasteMode); return PASTE_WHAT.includes(value as PasteWhat) ? { what: value as PasteWhat } : { what: "all" }; }; export const MENU_PASTE_OPTIONS = { "paste": { what: "all" }, "paste-values": { what: "values" }, "paste-formulas": { what: "formulas" }, "paste-formatting": { what: "formats" }, "paste-transpose": { what: "all", transpose: true }, "paste-link": { what: "all", link: true }, } satisfies Record; export interface ClipboardPayload { text: string; values: string[][]; } /** Prefer TSV; HTML-only clipboard tables retain their cell boundaries. */ export function parseClipboardPayload(text: string, html = ""): ClipboardPayload { if (!text && html) { const table = new DOMParser().parseFromString(html, "text/html").querySelector("table"); if (table) { const values = Array.from(table.rows, (row) => Array.from(row.cells, (cell) => { // textContent works in the detached document; preserve explicit line breaks in a cell. cell.querySelectorAll("br").forEach((br) => br.replaceWith("\n")); return cell.textContent ?? ""; })); if (values.length > 0) return { text: values.map((row) => row.join("\t")).join("\n"), values }; } } return { text, values: text.replace(/\r\n/g, "\n").replace(/\n+$/, "") .split("\n").map((line) => line.split("\t")), }; } /** The ribbon has no paste event, so read the same two formats from the browser. */ export async function readClipboardPayload(): Promise { if (navigator.clipboard.read) { try { const items = await navigator.clipboard.read(); const plain = items.find((item) => item.types.includes("text/plain")); const text = plain ? await (await plain.getType("text/plain")).text() : ""; if (text) return parseClipboardPayload(text); const rich = items.find((item) => item.types.includes("text/html")); return parseClipboardPayload(text, rich ? await (await rich.getType("text/html")).text() : ""); } catch { // Some browsers expose read() but allow only readText(). } } return parseClipboardPayload(await navigator.clipboard.readText()); } /** * WHAT A COPY OF `range` PUTS ON THE CLIPBOARD, AND WHAT THE COMPONENT REMEMBERS ABOUT IT. * * ⭐ IT WRITES WHAT THE CELL READS, not what it stores: `formatCellText` over `displayText`, so * a currency cell arrives in Excel as the currency somebody chose. That is the same string * `displayData` carries, which is what makes glide's own Ctrl+C agree with the ribbon's button * — and it is why the two copy doors can share one builder at all. * * ⚠ THE FOUR DEPENDENCIES ARE ARGUMENTS RATHER THAN A CLOSURE, which is the whole of what this * extraction did. `cells` is the tab's map, `addrAt` is the ONE door from a view coordinate to an * A1 address, and `realCol`/`realRow` translate a VIEW index back to the sheet's own coordinates * — a hidden column would otherwise move the recorded top-left one column left with no error. * * ⭐⭐ W54-T15 — AND IT IS WHERE THE COPY IS REGISTERED, because it is the ONE builder BOTH copy * doors share. The ribbon's button goes through `runCopySelection`, but a NATIVE Ctrl+C is * answered by glide and reaches this component only as a DOM `copy` event, whose handler calls * this function and nothing else. Registering in `runCopySelection` therefore covered the button * alone, and a native copy pasted back with the destination's own formatting still on it. * * ⭐⭐ TWO KEYS, ONE BLOCK, AND BOTH ARE NEEDED. What goes on the OS clipboard is the FORMATTED * grid, because Excel must receive the currency somebody chose; but glide round trips its own * copy through a `text/html` payload carrying `getCellContent`'s `data`, which is * `editableText`. So the very same copy comes back as `1234.5` where it left as `$1,234.50`, and * a registry findable under only one of those two strings misses on exactly one of the two * doors. The EDITABLE grid is built here beside the formatted one, joined with the same tabs and * newlines, and {@link rememberCopy} files the block under both. * * ⚠ REGISTERING HERE MEANS A COPY IS REGISTERED EVEN IF THE CLIPBOARD WRITE LATER REFUSES. That * is deliberate and it is the native door's requirement: glide's own Ctrl+C hands this component * no promise to observe, so there is no later moment at which to register. The cost of being * wrong is one stale entry in a two entry registry that is only ever consulted by an exact text * match, which no other clipboard content can produce. */ export function buildCopyPayload( range: CellRange, cells: CellMap, addrAt: (col: number, row: number) => string, realCol: (view: number) => number, realRow: (view: number) => number, viewExtent?: { cols: number; rows: number }, ): CopyPayload { const lines: string[] = []; // ⭐ W54-T15: the second key. `editableText` is what glide's own `data` round trip hands back. const editableLines: string[] = []; // ⭐ W51-T19: the CELLS are kept beside the text, so a bound cell pasted back into the sheet // can take its drag rules. See `copiedRef` for why the text alone cannot carry a binding. const block: (Cell | null)[][] = []; for (let r = Math.min(range.row0, range.row1); r <= Math.max(range.row0, range.row1); r += 1) { const line: string[] = []; const editLine: string[] = []; const row: (Cell | null)[] = []; for (let c = Math.min(range.col0, range.col1); c <= Math.max(range.col0, range.col1); c += 1) { const cell = cells[addrAt(c, r)] ?? null; // ⛔⛔ W54-T17: `rawDisplayText`, NEVER `displayText`. The IMPLICIT default number // format is a reading convenience on the canvas, not a value: a plain 1234.5 copied out // to Excel must arrive as 1234.5 and not as the rounded, grouped string a screen shows. // A format somebody EXPLICITLY chose still travels, because `formatCellText` applies it // here exactly as it always has. line.push(formatCellText(cell, rawDisplayText(cell))); editLine.push(editableText(cell)); row.push(cell); } lines.push(line.join("\t")); editableLines.push(editLine.join("\t")); block.push(row); } const payload: CopyPayload = { text: lines.join("\n"), col: realCol(Math.min(range.col0, range.col1)), row: realRow(Math.min(range.row0, range.row1)), cells: block, editable: editableLines.join("\n"), wholeAxis: viewExtent ? wholeAxisOf(range, viewExtent) : null, }; rememberCopy(payload); return payload; } /** What one copy out of the sheet is made of. `buildCopyPayload` returns exactly this shape. */ export interface CopyPayload { text: string; col: number; row: number; cells: (Cell | null)[][]; /** W61-T09: both copy doors record this flag; paste reads it to choose the anchor. * The view extent matters: frozen/hidden bands must not turn a whole axis into a partial copy. */ wholeAxis?: WholeAxis; /** * ⛔ W54-T15 — THE SECOND LOOKUP KEY, NEVER THE CLIPBOARD STRING. `text` stays the FORMATTED * grid: it is what is written to the OS clipboard for Excel, and it is what * `SheetGrid.tsx::copiedBlock` and `::isRecognizedCopy` compare against verbatim. This is the * same block rendered as `editableText`, which is the string glide's own `text/html` round trip * gives back to the paste door. Optional because only {@link buildCopyPayload} can build it. */ editable?: string; } /** The copied rectangle, in the sheet's REAL coordinates: top left plus how many of each. */ export interface CopyMarquee { col: number; row: number; cols: number; rows: number; } /** * COPY, and CUT, which is a copy whose source goes away WHEN THE PASTE LANDS. * * ⛔ THE CLEAR ONLY HAPPENS IF THE COPY SUCCEEDED. A browser that refuses clipboard access on a * cut would otherwise delete a person's cells with nothing on the clipboard to paste back. * * ⭐⭐ W54-T16 — AND IT NO LONGER HAPPENS HERE AT ALL. Clearing at CUT time is the defect the * owner reported from both ends: the source cell was emptied of its value but kept its fill * colour, its borders and its database binding, so it still looked occupied; and a cut abandoned * with Escape had already destroyed the value with nothing pasted anywhere. The successful write * now ARMS the cut through `sheetState.ts::rememberCut`, and `sheetState.ts::pasteCells` removes * the source in the SAME edit set as the paste that completes it - one undo step, one save, and * an identity check on every source cell before a single one is removed. * * ⭐ WHAT IT PUTS ON THE CLIPBOARD IS `heldFor`'s, which glide's own Ctrl+C now records * through the same builder. * * ⚠ THE SIX DEPENDENCIES ARE ARGUMENTS RATHER THAN A CLOSURE, which is the whole of what the * wave-54 extraction did. `viewRange` is the selection as VIEW coordinates, `heldFor` is the one * copy builder both doors share, `copiedRef` is the component's memory of its own last copy, * `setCopyMarquee` paints it, `_clearSelection` used to be the cut's second half, and `onNotice` * is the one door every refusal in this feature speaks through. * * ⛔⛔ W54-T16 KEEPS THE SIXTH PARAMETER AND STOPS USING IT, WHICH IS DELIBERATE AND NOT A * LEFTOVER. `verify_grid_ux.py` pins the CALL SITE in `SheetGrid.tsx` as an exact string, and * that file belongs to another ticket this wave, so dropping the argument would redden a gate leg * from inside a file this one may not touch. `noUnusedParameters` is on, so the name carries a * leading underscore instead; the component keeps handing its selection clearer over, and the * next lane to touch that call site may retire both halves in one move. */ export function runCopySelection( cut: boolean, viewRange: () => CellRange | null, heldFor: (range: CellRange) => CopyPayload, copiedRef: { current: CopyPayload | null }, setCopyMarquee: (rect: CopyMarquee | null) => void, _clearSelection: () => void, onNotice: (message: string) => void, ): void { const range = viewRange(); if (!range) { onNotice(cut ? "Select a cell first, then cut it." : "Select a cell first, then copy it."); return; } // ⭐ W53-T03: the block and its text are built by `heldFor`, the ONE builder both copy doors // share, so a native Ctrl+C and this button can never record different things about the same // selection. const held = heldFor(range); const block = held.cells; const text = held.text; // ⛔ RECORDED ONLY ON A SUCCESSFUL WRITE, so the sheet never believes it holds a block the // clipboard does not. It is a SEPARATE `then` so that the cut stays the one line a // W51-T17 gate leg pins: a cut takes effect only after the copy landed, and folding // the two together would have moved that leg's anchor for no reason at all. navigator.clipboard.writeText(text) .then(() => { copiedRef.current = held; // ⭐⭐ W54-T15 / C2 — THE IN APP CLIPBOARD IS NOT REGISTERED HERE, AND THAT IS THE FIX // RATHER THAN AN OMISSION. `heldFor` is `buildCopyPayload`, which registers the block // itself under both of its keys, so this door is already covered; a second registration // from here would file the same block again through a parameter typed as the narrower // `CopyPayload`, and the de-duplication would then REPLACE the entry that carries the // editable key with one that may not. One registration, at the one shared builder. // // ⭐ W52-T07: a NEW copy/cut is the closest thing to "the clipboard changed" this app can // observe, so it replaces the marquee rather than requiring an Escape first. setCopyMarquee({ col: held.col, row: held.row, cols: block[0]?.length ?? 0, rows: block.length }); }) // ⭐⭐ W54-T16: the cut is ARMED here and performed by the paste that completes it. On a // browser that refuses the write this `then` never runs, so nothing is armed, nothing is // deleted, and the catch below says so out loud. .then(() => { if (cut) rememberCut(held); }) .catch(() => onNotice("This browser did not let the sheet write to the clipboard. " + "Press Ctrl+C instead.")); }