Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download web/src/sheet/ribbonInsert.tsx from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 34.7 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/sheet/ribbonInsert.tsx
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/web/src/sheet/ribbonInsert.tsx
-
curl -L -o ribbonInsert.tsx https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/sheet/ribbonInsert.tsx
34.7 kB
| // sheet/ribbonInsert.tsx β the INSERT TAB of the Sheet's ribbon (wave 54, base kit part 2a; | |
| // filled and REGISTERED by W54-T10, owner instruction 5, ruling R3). | |
| // | |
| // ββ REGISTERED NOW, AND IT WAS NOT BEFORE ON PURPOSE. The base kit shipped this module exporting | |
| // its descriptor with an EMPTY group list, and `Ribbon.tsx`'s `TABS` carried Home alone, because a | |
| // registered empty tab paints a clickable tab that opens a blank toolbar row. W54-T10 gives the tab | |
| // its groups and adds its descriptor to that array in the same change, which is the whole of | |
| // the wiring this module owes: the shell reads `keys` for the roving order, `groups` for the row, | |
| // and the rest of the descriptor for the tab button. | |
| // | |
| // β WHAT A TAB MODULE OWES THE SHELL is set out in `ribbonHome.tsx`'s header, and this file is the | |
| // same three exports: | |
| // `INSERT_KEYS` the control keys this tab renders, IN ROVING ORDER. Every key here joins the | |
| // shell's `ControlKey` union automatically, which is what makes a control rendered | |
| // under an unlisted name a TYPE ERROR. | |
| // `insertGroups` the groups, as a function of the shell's `RibbonTabContext`. | |
| // `INSERT_TAB` the descriptor. | |
| // | |
| // S70 R14 revokes wave 54 R3's PivotTable exclusion. PivotTable now creates its own worksheet; | |
| // it uses a workbook callback alongside the cell/chart doors, leaving RibbonActionKind stable. | |
| // | |
| // ββ THESE CONTROLS DO NOT ADD A NAMED ACT, AND THAT IS DELIBERATE. `RibbonActionKind` is closed | |
| // by an exhaustive switch in `SheetGrid.tsx`, a file this lane does not own, so a new member would | |
| // be a compile error in every lane at once. A chart, a sparkline, a link and a note are DOCUMENT | |
| // WRITES rather than named acts, and they take the document's own doors instead, handed over as | |
| // `ctx.insert` (`Ribbon.tsx::RibbonInsertDoor`): a chart is a TAB level key and takes the | |
| // replace-the-list door, and the other three are CELL keys and take the same one commit door a | |
| // style patch takes. | |
| // β W54-T11 ADDS ONE CALL TO `act`, AND IT NAMES AN ACT THAT ALREADY EXISTED. The chart dialog's | |
| // database tab writes bound cells, and a bound cell is `stale` until the workbook refreshes, so | |
| // the block would sit empty without `refresh`. The union is untouched. | |
| // | |
| // β NO FAKE AFFORDANCE. `RibbonProps.canImport`'s own comment is the precedent: a control is | |
| // offered only where a door for it exists. When `ctx.insert` is undefined every control below | |
| // renders DISABLED, through a native `<fieldset disabled>` rather than a per-button flag, because | |
| // the shell's shared `control(...)` helper takes no disabled argument and this lane may not widen | |
| // it. In the app after `SheetGrid.tsx` wires the door it is never undefined; the fence is what | |
| // keeps this module honest if the prop is ever dropped. | |
| // | |
| // β A TAB MODULE IS A FUNCTION, NOT A COMPONENT. `Ribbon.tsx` CALLS `activeTab.groups(ctx)` during | |
| // its own render, so a hook here would attach to the shell and its order would change the moment | |
| // somebody switched tabs. That is why the two small forms below are UNCONTROLLED: they read their | |
| // value out of the submitted form rather than out of a `useState` this file cannot have. | |
| // | |
| // β DESIGN CONTRACT (DESIGN.md 2 through 5): inline SVG on `currentColor` and never emoji, token | |
| // only colour and type, Excel's Title Case labels (R41), no em dash or en dash in a string that reaches a | |
| // screen, and the two overlay shapes kept apart: POPOVERS originate at their trigger through | |
| // `AnchoredOverlay` (the link and comment forms) while MODALS REMAIN CENTRED (the chart dialog, | |
| // through `useOverlayLayer` and `BodyPortal`). Never a local keydown listener in either case. | |
| import { useState } from "react"; | |
| import type { FormEvent } from "react"; | |
| import { useCellRefHighlight } from "./refHighlight"; | |
| import type { RibbonTabContext } from "./Ribbon"; | |
| import { | |
| IconChartColumn, IconChartBar, IconChartLine, IconChartArea, | |
| IconChartPie, IconChartDonut, IconChartScatter, IconChartRecommended, | |
| } from "./ribbonIcons"; | |
| // W59-T08 adds shortcuts into the same dialog; chart creation still uses its single commit door. | |
| // ββ W54-T11 (ruling R5) β THE CHART GALLERY IS GONE AND A DIALOG STANDS WHERE IT STOOD. R5 reads | |
| // "A chart reads BOTH. A cell range, exactly like Excel, is the primary path; a database source is | |
| // a second tab in the same dialog. Ship both." A gallery of eight kinds cannot carry a second | |
| // source, so the eight kinds moved INTO the dialog and this tab keeps ONE Charts control that | |
| // opens ONE surface. DESIGN.md 4: modals remain centred, which is what makes this a dialog rather | |
| // than a wider popover. | |
| // β THE HOOKS LIVE IN THE DIALOG, WHICH IS A REAL COMPONENT. `insertGroups` is a function the | |
| // shell calls during its own render, so it still may not hold state of its own; `ChartDialog` may | |
| // hold all it likes, and the shell's popover state is what mounts it. | |
| import ChartDialog from "./ChartDialog"; | |
| import type { ChartRange } from "./ChartDialog"; | |
| // ββ W54-T14 β THE LINK FORM MOVED OUT AND GREW THE OTHER TWO KINDS. W54-T10 shipped an | |
| // uncontrolled one-field form here that could only write `kind: "url"`; a kind picker whose | |
| // refusal has to survive a keystroke needs state, and `insertGroups` is a function the ribbon | |
| // shell calls during its own render and may not hold one. So the Links group mounts a real | |
| // component, exactly as the Charts group mounts `ChartDialog`, and that component owns its own | |
| // anchored overlay. The Comments group's form stays uncontrolled: it has one field and no refusal. | |
| import LinkDialog from "./LinkDialog"; | |
| import type { CellLink } from "./LinkDialog"; | |
| import { MAX_CELL_NOTE } from "./types"; | |
| import type { Cell, SheetChartSpec, SparklineKind } from "./types"; | |
| // β THE DOCUMENT'S OWN ADDRESSER, in SHEET coordinates. The door hands over a sheet-coordinate | |
| // rectangle and a sheet-coordinate reader, so the address a cell edit is keyed by is built with | |
| // the same function `SheetGrid.tsx` builds every other one with. A second spelling of A1 in this | |
| // file would be a second answer to a question the document already answers. | |
| import { addressOf } from "./sheetState"; | |
| // β THE DOCUMENT'S OWN A1 PARSER, and the reason this ticket does not write a second one. A rule's | |
| // range, a chart's range and a sparkline's range are all the same rectangle spelled the same way, | |
| // so `D40:B2` normalises here exactly as it does in the conditional-format dialog. | |
| import { parseRange } from "./rules"; | |
| import type { RuleRect } from "./rules"; | |
| import { AnchoredOverlay } from "../customer-grid/OverlaySurface"; | |
| // β This tab's own stylesheet, a component-owned side-effect import, exactly as `ribbonHome.tsx` | |
| // imports its own. See the stylesheet's header for what it restates and why. | |
| import "../styles/wave54/ribbon-insert.css"; | |
| const CHART_SHORTCUTS = [ | |
| { key: "chart-column", moreKey: "chart-column-choices", kind: "column", label: "Column", Icon: IconChartColumn, kt: "V" }, | |
| { key: "chart-bar", moreKey: "chart-bar-choices", kind: "bar", label: "Bar", Icon: IconChartBar, kt: "B" }, | |
| { key: "chart-line", moreKey: "chart-line-choices", kind: "line", label: "Line", Icon: IconChartLine, kt: "L" }, | |
| { key: "chart-area", moreKey: "chart-area-choices", kind: "area", label: "Area", Icon: IconChartArea, kt: "A" }, | |
| { key: "chart-pie", moreKey: "chart-pie-choices", kind: "pie", label: "Pie", Icon: IconChartPie, kt: "P" }, | |
| { key: "chart-donut", moreKey: "chart-donut-choices", kind: "donut", label: "Donut", Icon: IconChartDonut, kt: "O" }, | |
| { key: "chart-scatter", moreKey: "chart-scatter-choices", kind: "scatter", label: "Scatter", Icon: IconChartScatter, kt: "X" }, | |
| ] as const; | |
| const CHARTS = [ | |
| "chart", ...CHART_SHORTCUTS.flatMap(({ key, moreKey }) => [key, moreKey]), "chart-recommended", | |
| ] as const; | |
| const SPARKLINES = ["sparkline-line", "sparkline-column", "sparkline-winloss"] as const; | |
| const LINKS = ["link"] as const; | |
| const COMMENTS = ["comment"] as const; | |
| const CELL_DATA = ["cell-data"] as const; | |
| const PIVOTS = ["pivot-table"] as const; | |
| /** | |
| * ββ THE INSERT TAB'S ROVING ORDER, WHICH IS ALSO ITS TYPE. The shell spreads this into the union | |
| * every `control(...)` key is checked against, so the arrays above are the single source of both | |
| * the reading order and the vocabulary. | |
| * β THE ARRAY IS THE ROVING SOURCE AND THE JSX IS NOT: a key listed here with no `control(...)` | |
| * call rendering it makes ArrowRight land on nothing, with every gate still green, so the two are | |
| * changed together or not at all. | |
| */ | |
| export const INSERT_KEYS = [...PIVOTS, ...CHARTS, ...SPARKLINES, ...LINKS, ...COMMENTS, ...CELL_DATA] as const; | |
| /** | |
| * β THE EIGHT KINDS AND THE FALLBACK RECTANGLE BOTH MOVED TO `ChartDialog.tsx` (W54-T11), which | |
| * is where they are now chosen and computed. The dialog also SAYS which rectangle it will cover, | |
| * which is what the retired gallery could not do: the range was grown silently, because | |
| * `RibbonTabContext` carries no notice path and there was nowhere honest to say so. | |
| */ | |
| /** A short unique id. No uuid library, and none is needed: this is a key within one document. */ | |
| const chartId = (): string => | |
| `ch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`; | |
| function IconChart() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M2.5 13.5h11" /> | |
| <path d="M4.5 11.5V7M8 11.5V3.5M11.5 11.5V6" /> | |
| </svg> | |
| ); | |
| } | |
| function IconSparkLine() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M2.5 11L5.5 6.5L8.5 9L13.5 4" /> | |
| </svg> | |
| ); | |
| } | |
| function IconSparkColumn() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M3 12V9M6.5 12V5M10 12V7.5M13.5 12V3.5" /> | |
| </svg> | |
| ); | |
| } | |
| function IconSparkWinLoss() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M2 8h12" /> | |
| <path d="M4 8V5M7.5 8v3M11 8V5" /> | |
| </svg> | |
| ); | |
| } | |
| function IconLink() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M6.8 9.2a2.6 2.6 0 0 0 3.7 0l2-2a2.6 2.6 0 0 0-3.7-3.7l-1 1" /> | |
| <path d="M9.2 6.8a2.6 2.6 0 0 0-3.7 0l-2 2a2.6 2.6 0 0 0 3.7 3.7l1-1" /> | |
| </svg> | |
| ); | |
| } | |
| function IconComment() { | |
| return ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M2.5 3.5h11v7h-6l-3 2.5v-2.5h-2z" /> | |
| </svg> | |
| ); | |
| } | |
| /** | |
| * The large Chart opener stays a single command. Chart-kind split controls use a separate | |
| * choices half to open the same dialog at that kind, without inserting before confirmation. | |
| */ | |
| // βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| // ββ W54-T13 β THE TWO RANGES EXCEL ASKS FOR, AND WHY THE SECOND ONE IS NOT A FIELD ON THE SPEC. | |
| // | |
| // Excel's "Create Sparklines" asks for a DATA range and a LOCATION range, and W54-T10 shipped | |
| // neither: it wrote one sparkline onto the cell the selection started on. That was the honest | |
| // minimum for a tab that had to exist; a location range is what makes the group useful, because | |
| // the ordinary case is one sparkline PER ROW of a block, not one sparkline for a block. | |
| // | |
| // β THE LOCATION IS THE CELL THE SPEC IS STORED ON. `CellSparkline` carries a DATA range and | |
| // nothing else, deliberately: a location range of six cells is six cells each carrying their own | |
| // spec over their own slice, which is what makes one of them movable, deletable and undoable on | |
| // its own. Adding a `location` field would have given the document two answers to "where is this | |
| // drawn" and let them disagree. | |
| // | |
| // β THE MAPPING IS STATED ON SCREEN, in one sentence, because it is the one thing a person cannot | |
| // guess: N location cells split the data range into N slices ALONG THE OTHER AXIS. When the counts | |
| // do not divide the form REFUSES rather than truncating, because a silently shortened range is a | |
| // picture of data nobody chose. | |
| // βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| /** Where one sparkline goes, and the slice of the data range it draws. */ | |
| interface SparkPlacement { | |
| col: number; | |
| row: number; | |
| range: RuleRect; | |
| } | |
| /** `B2` for one cell, `B2:E7` for a rectangle. The corners are normalised on the way in. */ | |
| const rangeText = (r: RuleRect): string => { | |
| const a = addressOf(Math.min(r.col0, r.col1), Math.min(r.row0, r.row1)); | |
| const b = addressOf(Math.max(r.col0, r.col1), Math.max(r.row0, r.row1)); | |
| return a === b ? a : `${a}:${b}`; | |
| }; | |
| const many = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`; | |
| const KIND_LABEL: Record<SparklineKind, string> = { | |
| line: "Line Sparkline", | |
| column: "Column Sparkline", | |
| winloss: "Win/Loss Sparkline", | |
| }; | |
| /** | |
| * β A SENSIBLE NEIGHBOUR, RATHER THAN AN EMPTY BOX. Excel leaves the location blank and makes the | |
| * person work it out; the two shapes people actually select have an obvious answer, so it is | |
| * offered and stays editable: | |
| * β’ a single COLUMN of readings gets ONE cell directly under it, because slicing a column of | |
| * numbers into one sparkline per number would draw a picture of one value; | |
| * β’ anything else gets a COLUMN of cells directly to the right, one per row, which is the | |
| * one sparkline per row that the group exists for. A single row is that same rule with one | |
| * row in it, so it lands on the single cell to the right. | |
| */ | |
| const defaultLocation = (r: RuleRect): RuleRect => { | |
| const c0 = Math.min(r.col0, r.col1); | |
| const c1 = Math.max(r.col0, r.col1); | |
| const r0 = Math.min(r.row0, r.row1); | |
| const r1 = Math.max(r.row0, r.row1); | |
| if (c0 === c1 && r1 > r0) return { col0: c0, row0: r1 + 1, col1: c0, row1: r1 + 1 }; | |
| return { col0: c1 + 1, row0: r0, col1: c1 + 1, row1: r1 }; | |
| }; | |
| /** | |
| * THE MAPPING RULE, IN CODE. One cell takes the whole data range; a location COLUMN of N cells | |
| * takes the rows of the data range in N equal slices; a location ROW of N cells takes its columns | |
| * the same way. Anything that does not divide comes back as a refusal in one sentence. | |
| */ | |
| const planSparklines = ( | |
| data: RuleRect, | |
| loc: RuleRect, | |
| ): { items: SparkPlacement[] } | { why: string } => { | |
| const dc0 = Math.min(data.col0, data.col1); | |
| const dc1 = Math.max(data.col0, data.col1); | |
| const dr0 = Math.min(data.row0, data.row1); | |
| const dr1 = Math.max(data.row0, data.row1); | |
| const lc0 = Math.min(loc.col0, loc.col1); | |
| const lc1 = Math.max(loc.col0, loc.col1); | |
| const lr0 = Math.min(loc.row0, loc.row1); | |
| const lr1 = Math.max(loc.row0, loc.row1); | |
| const lCols = lc1 - lc0 + 1; | |
| const lRows = lr1 - lr0 + 1; | |
| const n = lCols * lRows; | |
| if (n === 1) { | |
| return { items: [{ col: lc0, row: lr0, range: { col0: dc0, row0: dr0, col1: dc1, row1: dr1 } }] }; | |
| } | |
| if (lCols > 1 && lRows > 1) { | |
| return { why: "A location range of more than one cell has to be a single row or a single column." }; | |
| } | |
| const items: SparkPlacement[] = []; | |
| if (lCols === 1) { | |
| const rows = dr1 - dr0 + 1; | |
| if (rows % n !== 0) { | |
| return { why: `Those counts do not divide: ${many(rows, "row")} into ${many(n, "cell")}.` }; | |
| } | |
| const step = rows / n; | |
| for (let i = 0; i < n; i += 1) { | |
| items.push({ | |
| col: lc0, | |
| row: lr0 + i, | |
| range: { col0: dc0, col1: dc1, row0: dr0 + i * step, row1: dr0 + i * step + step - 1 }, | |
| }); | |
| } | |
| return { items }; | |
| } | |
| const cols = dc1 - dc0 + 1; | |
| if (cols % n !== 0) { | |
| return { why: `Those counts do not divide: ${many(cols, "column")} into ${many(n, "cell")}.` }; | |
| } | |
| const step = cols / n; | |
| for (let i = 0; i < n; i += 1) { | |
| items.push({ | |
| col: lc0 + i, | |
| row: lr0, | |
| range: { row0: dr0, row1: dr1, col0: dc0 + i * step, col1: dc0 + i * step + step - 1 }, | |
| }); | |
| } | |
| return { items }; | |
| }; | |
| /** | |
| * ββ A REAL COMPONENT, AND THAT IS WHAT BUYS THE STATE. `insertGroups` is a FUNCTION the shell | |
| * calls during its own render, so a `useState` written there would attach to the shell and its | |
| * hook order would change the moment somebody switched tabs. The two older forms in this file | |
| * dodged that by staying uncontrolled; a refusal has to survive a keystroke, so this one is | |
| * mounted as a component instead. The shell's popover state is what mounts and unmounts it, which | |
| * is also what re-seeds the two fields from the current selection each time it opens. | |
| * | |
| * β NO LOCAL KEYDOWN LISTENER. Escape comes from `AnchoredOverlay` and from nowhere else. | |
| */ | |
| function SparklineForm({ | |
| kind, | |
| selection, | |
| onCreate, | |
| }: { | |
| kind: SparklineKind; | |
| selection: RuleRect | null; | |
| onCreate: (kind: SparklineKind, items: SparkPlacement[]) => void; | |
| }) { | |
| const seed: RuleRect = selection ?? { col0: 0, row0: 0, col1: 0, row1: 0 }; | |
| const [data, setData] = useState(() => rangeText(seed)); | |
| const [location, setLocation] = useState(() => rangeText(defaultLocation(seed))); | |
| const [why, setWhy] = useState(""); | |
| // Both ranges are outlined on the grid while the form is open (refHighlight.ts). | |
| useCellRefHighlight([data, location]); | |
| const submit = (event: FormEvent<HTMLFormElement>) => { | |
| event.preventDefault(); | |
| const d = parseRange(data); | |
| if (!d) { | |
| setWhy("That data range is not an address like B2:E2."); | |
| return; | |
| } | |
| const l = parseRange(location); | |
| if (!l) { | |
| setWhy("That location range is not an address like F2."); | |
| return; | |
| } | |
| const plan = planSparklines(d, l); | |
| if ("why" in plan) { | |
| setWhy(plan.why); | |
| return; | |
| } | |
| onCreate(kind, plan.items); | |
| }; | |
| return ( | |
| <form className="sheet-ribbon-insert-fields" onSubmit={submit}> | |
| <p className="sheet-ribbon-insert-title">{KIND_LABEL[kind]}</p> | |
| <label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-spark-data"> | |
| Data range | |
| </label> | |
| <input | |
| id="sheet-insert-spark-data" | |
| name="data" | |
| type="text" | |
| className="sheet-ribbon-insert-input" | |
| value={data} | |
| placeholder="B2:E2" | |
| onChange={(event) => { setData(event.target.value); setWhy(""); }} | |
| /> | |
| <label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-spark-location"> | |
| Location range | |
| </label> | |
| <input | |
| id="sheet-insert-spark-location" | |
| name="location" | |
| type="text" | |
| className="sheet-ribbon-insert-input" | |
| value={location} | |
| placeholder="F2" | |
| onChange={(event) => { setLocation(event.target.value); setWhy(""); }} | |
| /> | |
| <p className="sheet-ribbon-insert-hint"> | |
| A location column of N cells takes N rows of the data range, a location row of N cells | |
| takes N columns, and one cell takes the whole range. | |
| </p> | |
| {why && <p className="sheet-ribbon-insert-refusal" role="alert">{why}</p>} | |
| <button type="submit" className="sheet-ribbon-item">Add sparkline</button> | |
| </form> | |
| ); | |
| } | |
| export const insertGroups = (ctx: RibbonTabContext) => { | |
| // β `item` IS NO LONGER TAKEN OFF THE CONTEXT, and that is W54-T11's doing rather than an | |
| // oversight: the only menu this tab ever painted was the chart gallery, and the eight kinds are | |
| // buttons inside `ChartDialog` now. The shell still offers the helper to every tab. | |
| const { open, anchorEl, openPop, closePop, control, group, word, large, stack, insert, act, openCellData } = ctx; | |
| const chartShortcut = CHART_SHORTCUTS.find(({ key, moreKey }) => open === key || open === moreKey); | |
| const chartOpen = open === "chart" || open === "chart-recommended" || !!chartShortcut; | |
| const chartCaret = ( | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-caret"> | |
| <path d="m4.5 6.5 3.5 3 3.5-3" /> | |
| </svg> | |
| ); | |
| /** | |
| * β THE ANCHOR CELL, IN SHEET COORDINATES. The door hands the selection over already translated | |
| * (`SheetGrid.tsx` maps every view index through `realCol` / `realRow` before it gets here), so | |
| * nothing in this file has to know that a hidden row moves what glide calls row 3. | |
| */ | |
| const anchorAt = (): { col: number; row: number } => { | |
| const sel = insert?.selection; | |
| if (!sel) return { col: 0, row: 0 }; | |
| return { col: Math.min(sel.col0, sel.col1), row: Math.min(sel.row0, sel.row1) }; | |
| }; | |
| /** | |
| * ββ THE ONE DOOR OUT OF THE DIALOG, AND BOTH TABS COME THROUGH IT (W54-T11, R5). | |
| * | |
| * The cell-range tab hands over a kind and a rectangle and nothing else, which is exactly what | |
| * the retired gallery did. The database tab ALSO hands over the cells it wants written, and this | |
| * is where the ordering matters: | |
| * 1. the cells go in ONE call, so the block is ONE history step and ONE save; | |
| * 2. the chart is anchored over the rectangle those cells occupy; | |
| * 3. a refresh runs, because a `stale` cell holds no value until the workbook refreshes. | |
| * | |
| * β RULING R9 SURVIVES THIS INTACT. The chart still READS CELLS: it is handed a rectangle and | |
| * never a database, a binding or a query, so there is still exactly one way to fetch a number in | |
| * this document and it is the binding path a bound cell already uses. | |
| * | |
| * β `refresh` IS AN EXISTING `RibbonActionKind`. Nothing new joins that union here: adding a | |
| * member would be a compile error in `SheetGrid.tsx`'s exhaustive switch, in every lane at once. | |
| */ | |
| const createChart = ( | |
| kind: SheetChartSpec["kind"], | |
| range: ChartRange, | |
| cells?: Record<string, Cell>, | |
| ) => { | |
| if (!insert) return; | |
| if (cells) insert.onCells(cells); | |
| insert.onCharts([...insert.charts, { id: chartId(), range, kind }]); | |
| closePop(); | |
| if (cells) act("refresh"); | |
| }; | |
| /** | |
| * ββ EVERY LOCATION CELL IN ONE CALL, WHICH IS ONE HISTORY STEP AND ONE SAVE. `insert.onCells` | |
| * takes many cells at a time for exactly this: six sparklines written one call each would be six | |
| * undos to take back and six writes to the store for one gesture. | |
| * | |
| * β A CELL WITH NO RECORD BECOMES `empty` / `typed` CARRYING ONLY THE SPARKLINE. That is the | |
| * shape W54-T09 provisioned server side (`platform/core/sheets.py::_clean_sparkline` keeps the | |
| * slot on an empty cell), and it is the ordinary case: a sparkline cell usually holds no text. | |
| * A cell that DOES have a record is amended rather than replaced, so a sparkline never eats a | |
| * formula, a style or a binding, and the renderer draws it as an underlay under that cell's own | |
| * value (`sheet/sparkline.ts`). | |
| */ | |
| const addSparklines = (kind: SparklineKind, items: SparkPlacement[]) => { | |
| if (!insert) return; | |
| const edits: Record<string, Cell> = {}; | |
| for (const item of items) { | |
| const held = insert.cellAt(item.col, item.row); | |
| const sparkline = { kind, range: item.range }; | |
| edits[addressOf(item.col, item.row)] = held | |
| ? { ...held, sparkline } | |
| : { kind: "empty", state: "typed", sparkline }; | |
| } | |
| insert.onCells(edits); | |
| closePop(); | |
| }; | |
| /** | |
| * Which of the three sparkline triggers is showing its form, or `null` when none is. | |
| * β THE KIND IS THE TRIGGER, NOT A CONTROL INSIDE THE FORM. Three buttons stay three | |
| * affordances (the group is Excel's own three, and a menu over three items costs a press without | |
| * buying anything); putting a fourth kind picker in the popover would also let `aria-expanded` on | |
| * the Line button describe a Column form. | |
| */ | |
| const openKind: SparklineKind | null = | |
| open === "sparkline-line" ? "line" | |
| : open === "sparkline-column" ? "column" | |
| : open === "sparkline-winloss" ? "winloss" | |
| : null; | |
| /** | |
| * β W54-T14 β ALL THREE KINDS THROUGH ONE WRITER. The dialog has already decided which kind it | |
| * is and validated the target for that kind; this only amends the anchor cell, so a link never | |
| * eats a value, a formula, a style or a binding. | |
| */ | |
| const addLink = (link: CellLink) => { | |
| if (!insert) return; | |
| const { col, row } = anchorAt(); | |
| const held = insert.cellAt(col, row); | |
| const next: Cell = held ? { ...held, link } : { kind: "empty", state: "typed", link }; | |
| insert.onCells({ [addressOf(col, row)]: next }); | |
| }; | |
| const addNote = (note: string) => { | |
| if (!insert) return; | |
| const { col, row } = anchorAt(); | |
| const held = insert.cellAt(col, row); | |
| const next: Cell = held | |
| ? { ...held, note } | |
| : { kind: "empty", state: "typed", note }; | |
| insert.onCells({ [addressOf(col, row)]: next }); | |
| }; | |
| /** What the anchor cell already carries, so the two forms open on it rather than on blank. */ | |
| const heldAt = (): Cell | null => { | |
| if (!insert) return null; | |
| const { col, row } = anchorAt(); | |
| return insert.cellAt(col, row); | |
| }; | |
| return ( | |
| /* β THE FENCE IS THE DISABLED STATE, AND IT IS NATIVE RATHER THAN PER BUTTON. A | |
| `<fieldset disabled>` disables every descendant form control the browser knows about, so one | |
| attribute covers the six controls and both forms without the shell's `control(...)` helper | |
| growing a ninth argument this lane may not give it. The rules that strip its own box live in | |
| `styles/wave54/ribbon-insert.css`. */ | |
| <fieldset className="sheet-ribbon-insert-fence" disabled={!insert}> | |
| {group("Tables", large(<> | |
| {control("pivot-table", "PivotTable", <> | |
| <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <path d="M2.5 2.5h11v11h-11zM2.5 6h11M6 2.5v11M6 10h7.5" /> | |
| </svg> | |
| {word("PivotTable")} | |
| </>, () => { insert?.onCreatePivot?.(); closePop(); }, | |
| false, undefined, "T", undefined, !insert?.onCreatePivot)} | |
| </>))} | |
| {group("Charts", ( | |
| <> | |
| {large(<> | |
| {control("chart", "Chart", <><IconChart />{word("Chart")}</>, | |
| openPop("chart"), false, open === "chart", "C", "gallery", undefined, "dialog")} | |
| </>)} | |
| <span className="sheet-chart-gallery"> | |
| {CHART_SHORTCUTS.map(({ key, moreKey, label, Icon, kt }) => ( | |
| <span className="sheet-chart-kind" key={key}> | |
| {control(key, `${label} Chart`, <Icon />, | |
| openPop(key), false, open === key, kt, "gallery", undefined, "dialog")} | |
| <span className="sheet-chart-kind-caret"> | |
| {/* Q prefixes chart choices; the overflow trigger already owns Y. */} | |
| {control(moreKey, `${label} Chart Choices`, chartCaret, | |
| openPop(moreKey), false, open === moreKey, `Q${kt}`, "gallery", undefined, "dialog")} | |
| </span> | |
| </span> | |
| ))} | |
| <span className="sheet-chart-kind sheet-chart-kind-recommended"> | |
| {control("chart-recommended", "Recommended Charts", <IconChartRecommended />, | |
| openPop("chart-recommended"), false, open === "chart-recommended", "R", "gallery", undefined, "dialog")} | |
| </span> | |
| </span> | |
| {/* β MOUNTED CONDITIONALLY, never rendered behind an `open` prop: `useOverlayLayer` | |
| claims Escape the moment it runs, so a hidden dialog would hold the key. The | |
| `insert` guard is belt and braces, and it is not the fieldset's job here: the | |
| dialog portals to the body and is therefore OUTSIDE the disabled fence. */} | |
| {chartOpen && insert && ( | |
| <ChartDialog | |
| key={open} | |
| selection={insert.selection} | |
| initialKind={chartShortcut?.kind} | |
| onClose={closePop} | |
| onCreate={createChart} | |
| /> | |
| )} | |
| </> | |
| ))} | |
| {/* β THREE CONTROLS RATHER THAN ONE WITH A GALLERY. Excel's Sparklines group is exactly | |
| three buttons, the choice is small and closed, and a menu over three items costs a press | |
| without buying anything. Each one opens the SAME authoring form, already knowing its kind. | |
| β `data-kt-opens="gallery"` IS WHAT MAKES THE ALT LAYER OPEN THEM. `KeyTips.tsx` fires a | |
| badge with no such attribute as a plain command and never descends; these three now open | |
| a popover, so they have to say so or the key tip would flash and land nowhere. */} | |
| {group("Sparklines", ( | |
| <> | |
| {stack( | |
| <> | |
| {control("sparkline-line", "Line", <IconSparkLine />, | |
| openPop("sparkline-line"), false, open === "sparkline-line", "SL", "gallery")} | |
| </>, | |
| <> | |
| {control("sparkline-column", "Column", <IconSparkColumn />, | |
| openPop("sparkline-column"), false, open === "sparkline-column", "SC", "gallery")} | |
| </>, | |
| <> | |
| {control("sparkline-winloss", "Win/Loss", <IconSparkWinLoss />, | |
| openPop("sparkline-winloss"), false, open === "sparkline-winloss", "SW", "gallery")} | |
| </> | |
| )} | |
| {openKind && insert && ( | |
| /* β `role="dialog"` RATHER THAN `role="menu"`, for the reason the Link form states | |
| one group down: a form is not a list of commands. | |
| β `key` FORCES A REMOUNT PER KIND, which is what re-seeds the two fields from the | |
| current selection when the person moves from Line to Column without closing. */ | |
| <AnchoredOverlay | |
| anchor={anchorEl} | |
| className="sheet-ribbon-pop sheet-ribbon-pop-portal sheet-ribbon-insert-form" | |
| onDismiss={closePop} | |
| role="dialog" | |
| ariaLabel={KIND_LABEL[openKind]} | |
| > | |
| <SparklineForm | |
| key={openKind} | |
| kind={openKind} | |
| selection={insert.selection} | |
| onCreate={addSparklines} | |
| /> | |
| </AnchoredOverlay> | |
| )} | |
| </> | |
| ))} | |
| {group("Links", ( | |
| large(<> | |
| {control("link", "Link", <><IconLink />{word("Link")}</>, | |
| openPop("link"), false, open === "link", "I", "gallery")} | |
| {/* β MOUNTED CONDITIONALLY AND OUTSIDE THE FIELDSET, for the two reasons the Charts | |
| group states: an overlay claims Escape the moment it runs, so a hidden one would | |
| hold the key; and it portals to the body, which puts it outside the disabled fence, | |
| so the `insert` guard is written here rather than inherited. | |
| β `role="dialog"` RATHER THAN `role="menu"` (the component says so): a form is not a | |
| list of commands, and a menu role would promise arrow-key item navigation that is | |
| not there. The shell's `control(...)` still writes `aria-haspopup="menu"` on the | |
| trigger, which it hardcodes for every expandable control; widening that helper is | |
| outside this lane's fence, so the mismatch is recorded here rather than papered | |
| over. */} | |
| {open === "link" && insert && ( | |
| <LinkDialog | |
| anchor={anchorEl} | |
| held={heldAt()?.link} | |
| onClose={closePop} | |
| onSubmit={(link) => { addLink(link); closePop(); }} | |
| /> | |
| )} | |
| </>) | |
| ))} | |
| {group("Comments", ( | |
| large(<> | |
| {control("comment", "Comment", <><IconComment />{word("Comment")}</>, | |
| openPop("comment"), false, open === "comment", "M", "gallery")} | |
| {open === "comment" && ( | |
| <AnchoredOverlay | |
| anchor={anchorEl} | |
| className="sheet-ribbon-pop sheet-ribbon-pop-portal sheet-ribbon-insert-form" | |
| onDismiss={closePop} | |
| role="dialog" | |
| ariaLabel="Comment" | |
| > | |
| <form | |
| className="sheet-ribbon-insert-fields" | |
| onSubmit={(event) => { | |
| event.preventDefault(); | |
| const field = event.currentTarget.elements.namedItem("note"); | |
| const note = field instanceof HTMLTextAreaElement ? field.value.trim() : ""; | |
| if (note) addNote(note.slice(0, MAX_CELL_NOTE)); | |
| closePop(); | |
| }} | |
| > | |
| <label className="sheet-ribbon-insert-caption" htmlFor="sheet-insert-comment"> | |
| Comment | |
| </label> | |
| <textarea | |
| id="sheet-insert-comment" | |
| name="note" | |
| className="sheet-ribbon-insert-area" | |
| rows={3} | |
| maxLength={MAX_CELL_NOTE} | |
| defaultValue={heldAt()?.note ?? ""} | |
| /> | |
| {/* β W54-T14 β IT EDITS RATHER THAN REPLACES, and the label is what says so. The | |
| field is already seeded from the cell's own note above, so a second Insert > | |
| Comment on the same cell opens what is there; the wording is the only part a | |
| person can see before they have typed anything. */} | |
| <button type="submit" className="sheet-ribbon-item"> | |
| {heldAt()?.note ? "Update comment" : "Add comment"} | |
| </button> | |
| </form> | |
| </AnchoredOverlay> | |
| )} | |
| </>) | |
| ))} | |
| {group("Cell Data", large(<> | |
| {control("cell-data", "Cell Database", <> | |
| <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon"> | |
| <ellipse cx="8" cy="3.5" rx="5" ry="2" /> | |
| <path d="M3 3.5v9c0 1.1 2.2 2 5 2s5-.9 5-2v-9M3 8c0 1.1 2.2 2 5 2s5-.9 5-2" /> | |
| </svg> | |
| {word("Cell Database")} | |
| </>, openCellData, undefined, undefined, "D")} | |
| </>))} | |
| </fieldset> | |
| ); | |
| }; | |
| /** | |
| * β THE DESCRIPTOR, REGISTERED IN `Ribbon.tsx::TABS` SINCE W54-T10. | |
| * β `kt` IS THE TAB'S OWN FIRST-LEVEL KEY-TIP BADGE and `N` is what Excel uses for Insert. Tab | |
| * badges are scoped to the tab depth by `KeyTips.tsx`, so this does not collide with the Number | |
| * format control's own `N` one depth down. | |
| */ | |
| export const INSERT_TAB = { | |
| id: "insert", | |
| key: "tab-insert", | |
| kt: "N", | |
| label: "Insert", | |
| bodyClass: "sheet-ribbon-insert", | |
| toolbarLabel: "Insert", | |
| keys: INSERT_KEYS, | |
| groups: insertGroups, | |
| } as const; | |