@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/ribbon.js

@@ -1,8 +1,8 @@
-import { applyFormat, toggleFormat, preset, autoSum, structural, clearFormats, getFormatTarget, getWorkbook, withFormatUndo, nudgeFontSize, activeEntry, FONT_SIZES, DEFAULT_FONT_SIZE, applyBorders, formatAllowed, raiseRibbonAction, } from './shortcuts.js';
+import { applyFormat, toggleFormat, preset, autoSum, structural, clearFormats, newSheet, getFormatTarget, getWorkbook, withFormatUndo, nudgeFontSize, activeEntry, FONT_SIZES, DEFAULT_FONT_SIZE, applyBorders, formatAllowed, raiseRibbonAction, } from './shortcuts.js';
 export { FONT_SIZES, applyBorders } from './shortcuts.js';
-import { insertRows, deleteRows, getStructureTarget } from './structure.js';
+import { insertRows, deleteRows, insertColumns, deleteColumns, getStructureTarget } from './structure.js';
 import { fillDown, fillRight, targetRect } from './commands.js';
-import { FORMAT_PRESETS, formatCategory } from './number-format.js';
+import { FORMAT_PRESETS, FORMAT_CATEGORY_PATTERNS, formatCategory, accountingParts, accountingPattern, formatWithPattern } from './number-format.js';
 import { ALL_COLOURS } from './palette.js';
 // ---------------------------------------------------------------------------
 // Shared predicates
@@ -87,6 +87,21 @@ function alignItem(align, title) {
         isEnabled: canFormat,
     };
 }
+/** Excel's Top / Middle / Bottom Align. The middle is the sheet's default,
+ *  so its button clears the field rather than storing it, and reads as on
+ *  for a cell that has no vertical alignment of its own. */
+function valignItem(valign, title) {
+    return {
+        id: `valign-${valign}`,
+        label: '≡',
+        icon: `valign-${valign}`,
+        title,
+        kind: 'toggle',
+        run: (cmd) => applyFormat(cmd, { valign: valign === 'center' ? undefined : valign }),
+        isOn: (cmd) => everyCellHas(cmd, (entry) => valign === 'center' ? entry?.valign === undefined || entry?.valign === 'center' : entry?.valign === valign),
+        isEnabled: canFormat,
+    };
+}
 function presetItem(id, label, title, name, keys) {
     const run = preset(name);
     return {
@@ -110,7 +125,10 @@ function fromCommand(command) {
  *
  * Reads the active cell's current pattern rather than assuming one, so
  * pressing it on a currency cell keeps the currency and only moves the point.
- * A cell with no pattern starts from General, which Excel treats as 0 decimals.
+ * A cell with no pattern is General, and Excel moves from the decimals the
+ * value SHOWS there, not from zero: Increase on 3.14159 goes to six places,
+ * not down to one, and Decrease actually trims a place. Only when the cell is
+ * empty, or its value is not a number, does General behave like `0`.
  */
 function nudgeDecimals(delta) {
     return (cmd) => {
@@ -123,10 +141,31 @@ function nudgeDecimals(delta) {
         const current = rowId != null && columnId != null
             ? target.store.get(rowId, columnId)?.numFmt
             : undefined;
-        const next = withDecimals(current ?? '0', delta);
+        let next;
+        if (current) {
+            next = withDecimals(current, delta);
+        }
+        else {
+            // General: start from what the value displays, so the point moves the
+            // way Excel's does rather than resetting to a single place.
+            const count = generalDecimals(active.rowIndex, active.colIndex) + delta;
+            next = count < 0 || count > 30 ? null : count === 0 ? '0' : `0.${'0'.repeat(count)}`;
+        }
         return next === null ? false : applyFormat(cmd, { numFmt: next });
     };
 }
+/** The decimals a General cell currently shows, so Increase/Decrease Decimal
+ *  moves from there. Zero for a blank cell or a non-numeric value. */
+function generalDecimals(row, col) {
+    const wb = getWorkbook();
+    if (!wb)
+        return 0;
+    const value = wb.getValue(wb.active, row, col);
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 0;
+    const dot = formatWithPattern(value, 'General').indexOf('.');
+    return dot < 0 ? 0 : formatWithPattern(value, 'General').length - dot - 1;
+}
 /**
  * Move the decimal count of a number-format pattern by `delta`.
  *
@@ -141,9 +180,17 @@ export function withDecimals(pattern, delta) {
     // first half would leave a sheet where -1234.5 printed to a different
     // precision than 1234.5. Excel moves both, so this does too.
     //
+    // An accounting pattern is rebuilt from its parts rather than edited:
+    // its zero section carries a `"-"??` whose question marks count the
+    // decimals too.
+    const accounting = accountingParts(pattern);
+    if (accounting) {
+        const next = accounting.decimals + delta;
+        return next < 0 || next > 30 ? null : accountingPattern(accounting.symbol, next);
+    }
     // A quoted literal can contain a semicolon, which would make splitting on
     // ';' cut a section in half, so a pattern with quotes declines instead of
-    // being mangled. Nothing in FORMAT_PRESETS has one.
+    // being mangled. Nothing else in FORMAT_PRESETS has one.
     if (pattern.includes('"'))
         return null;
     const sections = pattern.split(';');
@@ -197,6 +244,7 @@ const NUMBER_FORMATS = [
     { value: 'general', label: 'General' },
     { value: 'number', label: 'Number' },
     { value: 'currency', label: 'Currency' },
+    { value: 'accounting', label: 'Accounting' },
     { value: 'percent', label: 'Percentage' },
     { value: 'date', label: 'Date' },
     { value: 'time', label: 'Time' },
@@ -216,6 +264,118 @@ const BORDER_OPTIONS = [
 // The tabs
 // ---------------------------------------------------------------------------
 const small = (row, item) => ({ ...item, row });
+/**
+ * Excel's File tab, the part of it a document in a page can do: New, Open
+ * an .xlsx from disk, Save as .xlsx, and the active sheet as CSV. Every
+ * entry is raised for the shell, and through it for the host, so an app
+ * that keeps its workbooks on a server takes Open and Save over with
+ * `onAction` and the buttons still read as Excel's.
+ */
+const FILE = {
+    id: 'file',
+    label: 'File',
+    groups: [
+        {
+            id: 'file-new',
+            icon: 'file-new',
+            label: 'New',
+            items: [
+                { id: 'file-new', label: 'New', title: 'New: start an empty workbook', icon: 'file-new', kind: 'button', size: 'large', emits: 'file-new' },
+            ],
+        },
+        {
+            id: 'file-open',
+            icon: 'file-open',
+            label: 'Open',
+            items: [
+                { id: 'file-open', label: 'Open', title: 'Open an .xlsx, .xls, .ods or .csv file', keys: 'Ctrl+O', icon: 'file-open', kind: 'button', size: 'large', emits: 'file-open' },
+            ],
+        },
+        {
+            id: 'file-save',
+            icon: 'file-save',
+            label: 'Save',
+            items: [
+                { id: 'file-save-xlsx', label: 'Save As', title: 'Save the workbook as an .xlsx file', keys: 'Ctrl+S', icon: 'file-save', kind: 'button', size: 'large', emits: 'file-save-xlsx' },
+                { id: 'file-save-ods', label: 'Save As ODS', title: 'Save the workbook as an .ods file, which LibreOffice Calc opens', icon: 'file-save', kind: 'button', size: 'large', emits: 'file-save-ods' },
+                { id: 'file-save-xls', label: 'Save As XLS', title: 'Save the workbook as an .xls file, which Excel 97-2003 opens', icon: 'file-save', kind: 'button', size: 'large', emits: 'file-save-xls' },
+                { id: 'file-export-csv', label: 'Export CSV', title: 'Export the active sheet as CSV', icon: 'file-csv', kind: 'button', size: 'large', emits: 'file-export-csv' },
+            ],
+        },
+        {
+            id: 'file-print',
+            icon: 'print',
+            label: 'Print',
+            items: [
+                { id: 'file-print', label: 'Print', title: 'Print the active sheet as its Page Layout says', keys: 'Ctrl+P', icon: 'print', kind: 'button', size: 'large', emits: 'file-print' },
+            ],
+        },
+    ],
+};
+/**
+ * Excel's Page Layout tab, the part with something behind it: Page Setup
+ * (Margins, Orientation, Size, Print Area, Print Titles, with the dialog
+ * on the launcher) and Sheet Options (whether gridlines and headings
+ * print). Raised rather than run here: the shell keeps the setup per
+ * sheet in the document, and File > Print reads it.
+ */
+const PAGE_LAYOUT = {
+    id: 'page-layout',
+    label: 'Page Layout',
+    groups: [
+        {
+            id: 'page-setup',
+            icon: 'page-setup',
+            label: 'Page Setup',
+            launcher: 'page-setup',
+            items: [
+                {
+                    id: 'margins', label: 'Margins', title: 'Margins', icon: 'margins', kind: 'dropdown', size: 'large',
+                    options: [
+                        { value: 'normal', label: 'Normal', emits: 'margins-normal', toggle: true },
+                        { value: 'narrow', label: 'Narrow', emits: 'margins-narrow', toggle: true },
+                        { value: 'wide', label: 'Wide', emits: 'margins-wide', toggle: true },
+                    ],
+                },
+                {
+                    id: 'orientation', label: 'Orientation', title: 'Orientation', icon: 'orientation', kind: 'dropdown', size: 'large',
+                    options: [
+                        { value: 'portrait', label: 'Portrait', emits: 'page-portrait', toggle: true },
+                        { value: 'landscape', label: 'Landscape', emits: 'page-landscape', toggle: true },
+                    ],
+                },
+                {
+                    id: 'paper', label: 'Size', title: 'Page Size', icon: 'paper', kind: 'dropdown', size: 'large',
+                    options: [
+                        { value: 'letter', label: 'Letter', emits: 'paper-letter', toggle: true },
+                        { value: 'legal', label: 'Legal', emits: 'paper-legal', toggle: true },
+                        { value: 'tabloid', label: 'Tabloid', emits: 'paper-tabloid', toggle: true },
+                        { value: 'a3', label: 'A3', emits: 'paper-a3', toggle: true },
+                        { value: 'a4', label: 'A4', emits: 'paper-a4', toggle: true },
+                        { value: 'a5', label: 'A5', emits: 'paper-a5', toggle: true },
+                    ],
+                },
+                {
+                    id: 'print-area', label: 'Print Area', title: 'Print Area', icon: 'print-area', kind: 'dropdown', size: 'large',
+                    options: [
+                        { value: 'set', label: 'Set Print Area', emits: 'print-area-set' },
+                        { value: 'clear', label: 'Clear Print Area', emits: 'print-area-clear' },
+                    ],
+                },
+                { id: 'print-titles', label: 'Print Titles', title: 'Print Titles: rows to repeat at the top of every page', icon: 'print-titles', kind: 'button', size: 'large', emits: 'print-titles' },
+            ],
+        },
+        {
+            id: 'sheet-options',
+            icon: 'gridlines',
+            label: 'Sheet Options',
+            items: [
+                small(1, { id: 'print-gridlines', label: 'Print Gridlines', title: 'Print the gridlines', icon: 'gridlines', kind: 'toggle', wide: true, emits: 'print-gridlines' }),
+                small(2, { id: 'print-headings', label: 'Print Headings', title: 'Print the row numbers and column letters', icon: 'headings', kind: 'toggle', wide: true, emits: 'print-headings' }),
+            ],
+        },
+    ],
+};
 const HOME = {
     id: 'home',
     label: 'Home',
@@ -251,7 +411,15 @@ const HOME = {
                 small(1, {
                     id: 'cut', label: 'Cut', title: 'Cut', keys: 'Ctrl+X', icon: 'cut', kind: 'button',
                     isEnabled: hasTarget,
-                    run: (cmd) => { void cmd.cut(); return true; },
+                    // Raised, so a spreadsheet shell can give it Excel's meaning: the
+                    // cells stay where they are until the paste lands. A host that
+                    // answers nothing falls back to the grid's cut, which clears now.
+                    run: (cmd) => {
+                        if (raiseRibbonAction('cut', cmd))
+                            return true;
+                        void cmd.cut();
+                        return true;
+                    },
                 }),
                 small(2, {
                     id: 'copy', label: 'Copy', title: 'Copy', keys: 'Ctrl+C', icon: 'copy', kind: 'button',
@@ -324,6 +492,9 @@ const HOME = {
             layout: 'flow',
             launcher: 'format-cells',
             items: [
+                small(1, valignItem('top', 'Top Align')),
+                small(1, valignItem('center', 'Middle Align')),
+                small(1, valignItem('bottom', 'Bottom Align')),
                 small(1, {
                     id: 'wrap', label: 'Wrap Text', title: 'Wrap Text', icon: 'wrap', kind: 'toggle', wide: true,
                     run: (cmd) => toggleWrap(cmd),
@@ -367,11 +538,12 @@ const HOME = {
                     current: (cmd) => {
                         const fmt = activeEntry(cmd)?.numFmt;
                         const { category } = formatCategory(fmt);
-                        return category === 'custom' ? fmt ?? 'general' : category;
+                        return category === 'custom' || category === 'special' ? fmt ?? 'general' : category;
                     },
-                    run: (cmd, value) => applyFormat(cmd, { numFmt: FORMAT_PRESETS[value] }),
+                    run: (cmd, value) => applyFormat(cmd, { numFmt: FORMAT_CATEGORY_PATTERNS[value] }),
                 }),
-                small(2, presetItem('fmt-currency', '$', 'Accounting Number Format', 'currency', 'Ctrl+Shift+4')),
+                // Excel's $ button applies Accounting; Ctrl+Shift+4 is Currency.
+                small(2, presetItem('fmt-currency', '$', 'Accounting Number Format', 'accounting')),
                 small(2, presetItem('fmt-percent', '%', 'Percent Style', 'percent', 'Ctrl+Shift+5')),
                 small(2, presetItem('fmt-number', ',', 'Comma Style', 'number', 'Ctrl+Shift+1')),
                 small(2, {
@@ -389,19 +561,36 @@ const HOME = {
             icon: 'table',
             label: 'Cells',
             items: [
+                // Excel's split buttons: the face takes the selection's axis (a
+                // whole column inserts columns, anything else rows, which is what
+                // Excel does with a cell selected), and the arrow spells the axis
+                // out, so a column can be inserted from a cell without selecting
+                // the column first.
                 small(1, {
                     id: 'insert', label: 'Insert', title: 'Insert Cells', keys: 'Ctrl+Shift++',
-                    icon: 'insert-cells', kind: 'button', wide: true,
-                    // A plain cell is ambiguous for the keystroke, which declines; the
-                    // button behaves as Excel's does with a cell selected and inserts
-                    // a row, shifting the sheet down.
-                    run: (cmd) => structural(cmd, 'insert') || insertRows(cmd),
+                    icon: 'insert-cells', kind: 'dropdown', split: true, wide: true,
+                    run: (cmd, value) => value === 'rows' ? insertRows(cmd)
+                        : value === 'columns' ? insertColumns(cmd)
+                            : value === 'sheet' ? newSheet()
+                                : structural(cmd, 'insert') || insertRows(cmd),
+                    options: [
+                        { value: 'rows', label: 'Insert Sheet Rows' },
+                        { value: 'columns', label: 'Insert Sheet Columns' },
+                        { value: 'sheet', label: 'Insert Sheet', keys: 'Shift+F11' },
+                    ],
                     isEnabled: canRestructure,
                 }),
                 small(2, {
                     id: 'delete', label: 'Delete', title: 'Delete Cells', keys: 'Ctrl+-',
-                    icon: 'delete-cells', kind: 'button', wide: true,
-                    run: (cmd) => structural(cmd, 'delete') || deleteRows(cmd),
+                    icon: 'delete-cells', kind: 'dropdown', split: true, wide: true,
+                    run: (cmd, value) => value === 'rows' ? deleteRows(cmd)
+                        : value === 'columns' ? deleteColumns(cmd)
+                            : structural(cmd, 'delete') || deleteRows(cmd),
+                    options: [
+                        { value: 'rows', label: 'Delete Sheet Rows' },
+                        { value: 'columns', label: 'Delete Sheet Columns' },
+                        { value: 'sheet', label: 'Delete Sheet', emits: 'delete-sheet' },
+                    ],
                     isEnabled: canRestructure,
                 }),
                 // Excel's Format menu: Cell Size, Visibility, and Format Cells at
@@ -457,6 +646,8 @@ const HOME = {
                         { value: 'cf-color-scale-3', label: 'Green - Yellow - Red Color Scale', icon: 'cf-scale', emits: 'cf-color-scale-3' },
                         { value: 'cf-color-scale-2', label: 'Green - White Color Scale', icon: 'cf-scale', emits: 'cf-color-scale-2' },
                         { value: 'cf-icon-set', label: 'Icon Set (3 Arrows)', icon: 'cf-icons', emits: 'cf-icon-set' },
+                        { value: 'n', label: 'New Rule', heading: true },
+                        { value: 'cf-formula', label: 'Use a Formula...', icon: 'cf-formula', emits: 'cf-formula' },
                         { value: 'c', label: 'Clear Rules', heading: true },
                         { value: 'cf-clear-selection', label: 'Clear Rules from Selected Cells', emits: 'cf-clear-selection' },
                         { value: 'cf-clear-sheet', label: 'Clear Rules from Entire Sheet', emits: 'cf-clear-sheet' },
@@ -474,15 +665,17 @@ const HOME = {
                 // Undo and Redo open the group as a column of two small icons, the
                 // way Cut and Copy stand beside Paste; the owner wanted them here
                 // rather than in a group of their own.
+                // Raised rather than run: a step made on another sheet is undone
+                // THERE, which means switching sheets first, and only the shell can.
                 small(1, {
                     id: 'undo', label: 'Undo', title: 'Undo', keys: 'Ctrl+Z', icon: 'undo', kind: 'button',
                     isEnabled: (cmd) => cmd.api.canUndo(),
-                    run: (cmd) => cmd.api.undo(),
+                    emits: 'undo',
                 }),
                 small(2, {
                     id: 'redo', label: 'Redo', title: 'Redo', keys: 'Ctrl+Y', icon: 'redo', kind: 'button',
                     isEnabled: (cmd) => cmd.api.canRedo(),
-                    run: (cmd) => cmd.api.redo(),
+                    emits: 'redo',
                 }),
                 small(1, {
                     id: 'autosum', label: 'AutoSum', title: 'AutoSum', keys: 'Alt+=',
@@ -522,7 +715,14 @@ const INSERT = {
             icon: 'table',
             label: 'Tables',
             items: [
+                // Excel's Tables group leads with PivotTable, and Refresh sits beside
+                // the pair for the pivot the cursor is in.
+                { id: 'pivot-table', label: 'PivotTable', title: 'Summarise the selected block', icon: 'pivot', kind: 'button', size: 'large', emits: 'insert-pivot' },
                 { id: 'table', label: 'Table', title: 'Format the selection as a table', keys: 'Ctrl+T', icon: 'table', kind: 'button', size: 'large', emits: 'insert-table' },
+                small(1, { id: 'pivot-refresh', label: 'Refresh', title: 'Rebuild the PivotTable here from its source', icon: 'calculate', kind: 'button', wide: true, emits: 'refresh-pivot' }),
+                small(1, { id: 'pivot-details', label: 'Show Details', title: 'Show Details: the source rows behind the number in this PivotTable cell, on a sheet of their own', icon: 'pivot', kind: 'button', wide: true, emits: 'pivot-details' }),
+                small(2, { id: 'table-remove', label: 'To Range', title: 'Convert the table here back to ordinary cells', icon: 'delete-cells', kind: 'button', wide: true, emits: 'remove-table' }),
+                small(3, { id: 'table-style', label: 'Table Styles', title: 'Pick the look of the table the cursor is in', icon: 'table', kind: 'button', wide: true, emits: 'table-style' }),
             ],
         },
         {
@@ -531,6 +731,54 @@ const INSERT = {
             label: 'Charts',
             items: [
                 { id: 'chart', label: 'Chart', title: 'Chart the selected range', icon: 'chart', kind: 'button', size: 'large', emits: 'insert-chart' },
+                small(1, { id: 'chart-setup', label: 'Setup', title: 'Chart: type, title, labels and series', icon: 'chart-setup', kind: 'button', wide: true, emits: 'chart-setup' }),
+                small(2, { id: 'delete-object', label: 'Delete', title: 'Delete the selected chart or picture', icon: 'delete-cells', kind: 'button', wide: true, emits: 'delete-object' }),
+            ],
+        },
+        {
+            // Excel's Sparklines group: the three kinds, each opening the Create
+            // Sparklines dialog on the selection, and Clear for the group under it.
+            id: 'sparklines',
+            icon: 'sparkline-line',
+            label: 'Sparklines',
+            items: [
+                { id: 'sparkline-line', label: 'Line', title: 'A line sparkline in each cell of a range', icon: 'sparkline-line', kind: 'button', size: 'large', emits: 'sparkline-line' },
+                { id: 'sparkline-column', label: 'Column', title: 'A column sparkline in each cell of a range', icon: 'sparkline-column', kind: 'button', size: 'large', emits: 'sparkline-column' },
+                { id: 'sparkline-winloss', label: 'Win/Loss', title: 'A win/loss sparkline in each cell of a range', icon: 'sparkline-winloss', kind: 'button', size: 'large', emits: 'sparkline-winloss' },
+                small(1, { id: 'sparkline-setup', label: 'Edit', title: 'The sparkline group here: its ranges, kind and colours', icon: 'chart-setup', kind: 'button', wide: true, emits: 'sparkline-setup' }),
+                small(2, { id: 'sparkline-clear', label: 'Clear', title: 'Clear the sparklines in the selection', icon: 'delete-cells', kind: 'button', wide: true, emits: 'clear-sparklines' }),
+            ],
+        },
+        {
+            // Excel's Links group: one dialog for the address, the text and the tip,
+            // and Remove Link beside it.
+            id: 'links',
+            icon: 'link',
+            label: 'Links',
+            items: [
+                { id: 'link', label: 'Link', title: 'Link this cell to a page or an address', keys: 'Ctrl+K', icon: 'link', kind: 'button', size: 'large', emits: 'insert-link' },
+                small(1, { id: 'unlink', label: 'Remove', title: 'Remove the link from the selection', icon: 'unlink', kind: 'button', wide: true, emits: 'remove-link' }),
+            ],
+        },
+        {
+            id: 'illustrations',
+            icon: 'picture',
+            label: 'Illustrations',
+            items: [
+                { id: 'picture', label: 'Picture', title: 'Put a picture on the sheet', icon: 'picture', kind: 'button', size: 'large', emits: 'insert-picture' },
+            ],
+        },
+        {
+            // Excel's Insert > Checkbox, with the two other controls a data-entry
+            // sheet asks for beside it. Each draws the cell as a control; the
+            // cell's own value is still what it means.
+            id: 'controls',
+            icon: 'checkbox',
+            label: 'Controls',
+            items: [
+                { id: 'insert-checkbox', label: 'Checkbox', title: 'Draw the selected cells as checkboxes, over TRUE and FALSE', icon: 'checkbox', kind: 'button', size: 'large', emits: 'insert-checkbox' },
+                small(2, { id: 'insert-cell-button', label: 'Button', title: 'Draw the selected cells as buttons', icon: 'cell-button', kind: 'button', emits: 'insert-cell-button' }),
+                small(2, { id: 'clear-cell-type', label: 'Clear Control', title: 'Draw the selected cells as ordinary cells again', icon: 'clear-formats', kind: 'button', emits: 'clear-cell-type' }),
             ],
         },
         {
@@ -605,7 +853,12 @@ const FORMULAS = {
             icon: 'show-formulas',
             label: 'Formula Auditing',
             items: [
+                small(1, { id: 'trace-precedents', label: 'Trace Precedents', title: 'Trace Precedents: arrows from the cells the active formula reads; again for the next level', icon: 'trace-precedents', kind: 'button', wide: true, emits: 'trace-precedents' }),
+                small(2, { id: 'trace-dependents', label: 'Trace Dependents', title: 'Trace Dependents: arrows to the formulas that read the active cell; again for the next level', icon: 'trace-dependents', kind: 'button', wide: true, emits: 'trace-dependents' }),
+                small(3, { id: 'remove-arrows', label: 'Remove Arrows', title: 'Remove Arrows', icon: 'remove-arrows', kind: 'button', wide: true, emits: 'remove-arrows' }),
                 small(1, { id: 'show-formulas', label: 'Show Formulas', title: 'Show formulas instead of their results', keys: 'Ctrl+`', icon: 'show-formulas', kind: 'toggle', wide: true, emits: 'toggle-formulas' }),
+                small(2, { id: 'evaluate-formula', label: 'Evaluate Formula', title: 'Evaluate Formula: work the active cell out one part at a time', icon: 'evaluate-formula', kind: 'button', wide: true, emits: 'evaluate-formula' }),
+                small(3, { id: 'error-checking', label: 'Error Checking', title: 'Error Checking: walk the cells on this sheet that report an error, and the formulas that break their column\'s pattern', icon: 'error-checking', kind: 'button', wide: true, emits: 'error-checking' }),
             ],
         },
         {
@@ -615,6 +868,7 @@ const FORMULAS = {
             items: [
                 { id: 'recalc', label: 'Calculate Now', title: 'Recalculate the workbook', keys: 'F9', icon: 'calculate', kind: 'button', size: 'large', emits: 'recalculate' },
                 small(1, { id: 'goal-seek-f', label: 'Goal Seek', title: 'Goal Seek', icon: 'goal-seek', kind: 'button', wide: true, emits: 'goal-seek' }),
+                small(2, { id: 'calc-options', label: 'Calculation Options', title: 'Iterative calculation: let a circular reference settle instead of showing #CYCLE!', icon: 'calculate', kind: 'button', wide: true, emits: 'calc-options' }),
             ],
         },
     ],
@@ -630,6 +884,7 @@ const DATA = {
             items: [
                 small(1, { id: 'sort-asc', label: 'Sort A to Z', title: 'Sort A to Z', icon: 'sort-asc', kind: 'button', emits: 'sort-asc' }),
                 small(2, { id: 'sort-desc', label: 'Sort Z to A', title: 'Sort Z to A', icon: 'sort-desc', kind: 'button', emits: 'sort-desc' }),
+                { id: 'sort-custom', label: 'Sort', title: 'Sort: by several columns, each its own way', icon: 'sort', kind: 'button', size: 'large', emits: 'sort-custom' },
                 { id: 'filter-data', label: 'Filter', title: 'Filter', keys: 'Ctrl+Shift+L', icon: 'filter', kind: 'toggle', size: 'large', emits: 'toggle-filter' },
             ],
         },
@@ -640,7 +895,17 @@ const DATA = {
             items: [
                 { id: 'text-to-columns', label: 'Text to Columns', title: 'Split the selected column on a delimiter', icon: 'text-to-columns', kind: 'button', size: 'large', emits: 'text-to-columns' },
                 { id: 'remove-duplicates', label: 'Remove Duplicates', title: 'Remove duplicate rows', icon: 'remove-duplicates', kind: 'button', size: 'large', emits: 'remove-duplicates' },
-                { id: 'data-validation', label: 'Data Validation', title: 'Data Validation: what may be typed into the selected cells', icon: 'validation', kind: 'button', size: 'large', emits: 'data-validation' },
+                // Excel's menu: the dialog, then Circle Invalid Data and Clear
+                // Validation Circles, each raised for the shell.
+                {
+                    id: 'data-validation', label: 'Data Validation', title: 'Data Validation: what may be typed into the selected cells',
+                    icon: 'validation', kind: 'dropdown', size: 'large',
+                    options: [
+                        { value: 'data-validation', label: 'Data Validation...', emits: 'data-validation' },
+                        { value: 'circle-invalid', label: 'Circle Invalid Data', emits: 'circle-invalid' },
+                        { value: 'clear-circles', label: 'Clear Validation Circles', emits: 'clear-circles' },
+                    ],
+                },
             ],
         },
         {
@@ -651,6 +916,36 @@ const DATA = {
                 { id: 'goal-seek', label: 'Goal Seek', title: 'Change one input until a formula hits a target', icon: 'goal-seek', kind: 'button', size: 'large', emits: 'goal-seek' },
             ],
         },
+        {
+            id: 'outline',
+            icon: 'group-rows',
+            label: 'Outline',
+            items: [
+                // Excel's Group and Ungroup are split buttons whose face acts on
+                // rows; the ribbon model forbids a dropdown that emits its own
+                // face, so each is a menu whose first entry is the face's action.
+                {
+                    id: 'group', label: 'Group', title: 'Group the selected rows or columns',
+                    icon: 'group-rows', kind: 'dropdown', size: 'large', wide: true,
+                    options: [
+                        { value: 'group-rows', label: 'Group Rows', keys: 'Alt+Shift+Right', emits: 'group-rows' },
+                        { value: 'group-cols', label: 'Group Columns', emits: 'group-cols' },
+                        { value: 'auto-outline', label: 'Auto Outline', emits: 'auto-outline' },
+                    ],
+                },
+                {
+                    id: 'ungroup', label: 'Ungroup', title: 'Ungroup the selected rows or columns',
+                    icon: 'ungroup-rows', kind: 'dropdown', size: 'large', wide: true,
+                    options: [
+                        { value: 'ungroup-rows', label: 'Ungroup Rows', keys: 'Alt+Shift+Left', emits: 'ungroup-rows' },
+                        { value: 'ungroup-cols', label: 'Ungroup Columns', emits: 'ungroup-cols' },
+                        { value: 'clear-outline', label: 'Clear Outline', emits: 'clear-outline' },
+                    ],
+                },
+                small(2, { id: 'show-detail', label: 'Show Detail', title: 'Expand the group at the selection', icon: 'show-detail', kind: 'button', emits: 'show-detail' }),
+                small(2, { id: 'hide-detail', label: 'Hide Detail', title: 'Collapse the group at the selection', icon: 'hide-detail', kind: 'button', emits: 'hide-detail' }),
+            ],
+        },
     ],
 };
 function toggleWrap(cmd) {
@@ -671,8 +966,10 @@ function toggleWrap(cmd) {
  * the sheet's notes: New Comment opens the editor on the active cell (and
  * edits the one there), Delete, Previous and Next walk them, Show All
  * Comments lists them. Protect Sheet and Unprotect Sheet are one slot, the
- * shell leaving off whichever does not apply. There is no password, as the
- * sheet documents.
+ * shell leaving off whichever does not apply; Protect Sheet opens Excel's
+ * dialog with its "allow all users to" list, and Allow Edit Ranges names
+ * the blocks that stay editable. There is no password, as the sheet
+ * documents.
  */
 const REVIEW = {
     id: 'review',
@@ -703,6 +1000,10 @@ const REVIEW = {
                     id: 'unprotect-sheet', label: 'Unprotect Sheet', title: 'Unprotect Sheet',
                     icon: 'unprotect', kind: 'button', size: 'large', emits: 'unprotect-sheet',
                 },
+                {
+                    id: 'allow-edit-ranges', label: 'Allow Edit Ranges', title: 'Allow Users to Edit Ranges: blocks that take an edit while the sheet is protected',
+                    icon: 'edit-ranges', kind: 'button', size: 'large', emits: 'allow-edit-ranges',
+                },
             ],
         },
     ],
@@ -746,7 +1047,7 @@ const VIEW = {
         },
     ],
 };
-export const RIBBON_TABS = [HOME, INSERT, FORMULAS, DATA, REVIEW, VIEW];
+export const RIBBON_TABS = [FILE, HOME, INSERT, PAGE_LAYOUT, FORMULAS, DATA, REVIEW, VIEW];
 /** Every item across every tab, for tests and for a command palette. */
 export function ribbonItems() {
     return RIBBON_TABS.flatMap((tab) => tab.groups.flatMap((group) => group.items));

package/dist/sheet/sheet-kinds.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What kind of thing a sheet tab is.
+ *
+ * A workbook's tabs have always been cell grids. A `grid` tab is the other
+ * thing a business workbook wants: a data-bound table, backed by records
+ * rather than by cells, sorted and filtered and edited as a grid rather
+ * than as a sheet.
+ *
+ * The trick that makes this cheap rather than a second engine: **a grid
+ * sheet PROJECTS its records into the workbook's cells.** The records are
+ * the truth, and after every change they are written into the same
+ * `string[][]` a cell sheet keeps, header row included. So
+ * `=SUM(Orders!D2:D99)` on a cell sheet reads a grid sheet with no new
+ * machinery at all: the formula engine, the dependency graph, the file
+ * writers and the printer never learn that this tab is different.
+ *
+ * The projection runs through `setRaw`, which ignores a write that changes
+ * nothing, so editing one field of one record rewrites one cell and
+ * recalculates what depended on it, not the sheet.
+ *
+ * What a grid sheet deliberately does NOT do: hold a formula of its own.
+ * Its cells are a rendering of its records, so anything typed into them
+ * would be overwritten by the next projection. A sheet that needs formulas
+ * beside the data is a cell sheet reading the grid one across.
+ */
+import { type SheetField } from './from-rows.js';
+export type SheetKind = 'cells' | 'grid';
+/** One column of a grid sheet, as the sheet describes it. */
+export type GridSheetField = SheetField & {
+    /** Narrow the editor and the alignment, as the grid's own columns do. */
+    type?: 'text' | 'number' | 'date' | 'boolean';
+    width?: number;
+    editable?: boolean;
+};
+export type GridSheetSpec = {
+    fields: GridSheetField[];
+    /** The records. A grid sheet's truth; the cells are made from these. */
+    rows: Array<Record<string, unknown>>;
+    /** Rows may be edited in place. Off by default, as a report would want. */
+    editable?: boolean;
+    /** A totals row under the records, summing every numeric column. */
+    totals?: boolean;
+};
+export declare const emptyGridSheet: () => GridSheetSpec;
+/** The cells a grid sheet stands for: the header, the records, the totals. */
+export declare function projectGridSheet(spec: GridSheetSpec): string[][];
+/**
+ * Where a record sits in the projection.
+ *
+ * Row 0 is the header, so record `i` is at row `i + 1`. Kept as a function
+ * rather than inlined so the offset is named in one place: getting it
+ * wrong reads the header as a record and is silent.
+ */
+export declare const rowOfRecord: (index: number) => number;
+export declare const recordOfRow: (row: number) => number;
+/** Is this row of the projection a record, rather than a header or total? */
+export declare const isRecordRow: (spec: GridSheetSpec, row: number) => boolean;
+/**
+ * A field's column in the projection, or -1.
+ *
+ * Matched on the field name rather than the label, since two columns may
+ * share a label and the name is what the record is keyed by.
+ */
+export declare const columnOfField: (spec: GridSheetSpec, field: string) => number;
+/** A deep-enough copy for a document snapshot. */
+export declare const copyGridSheet: (spec: GridSheetSpec) => GridSheetSpec;
+/**
+ * A value typed into a grid sheet, coerced to the field's type.
+ *
+ * The grid hands back whatever its editor produced, which for a number
+ * column typed into by hand is a string. Storing that would make the
+ * record's shape depend on how it was edited, so it is narrowed here once.
+ */
+export declare function coerceFieldValue(field: GridSheetField, value: unknown): unknown;