@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/ribbon.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The ribbon, as data.
+ *
+ * Same shape of decision as SHEET_BINDINGS: a table that can be read in one
+ * screen and tested without mounting anything. `SvSheetRibbon.svelte` is only
+ * a renderer for it.
+ *
+ * Every item that acts on the sheet runs one of the action functions
+ * `shortcuts.ts` exports - the same ones the keymap binds. That is the whole
+ * point of the indirection: Ctrl+B and the Bold button are literally the same
+ * call, so they cannot come to disagree about what "bold the selection" means,
+ * and neither can drift when the format store changes underneath them.
+ *
+ * Items that need chrome the keyboard layer deliberately does not ship (a
+ * function picker, a Goal Seek dialog, Text to Columns options) carry no `run`
+ * and set `emits` instead. The renderer reports those through `onAction` and
+ * the host decides what a dialog looks like, which is the same split
+ * `setFormatDialogHandler` already makes.
+ *
+ * Layout is Excel's, and it is in the data too. A group is a block three
+ * rows high: a LARGE button (icon over label) takes a whole column, SMALL
+ * buttons stack three to a column, and each small item says which row it
+ * sits on. The renderer lays that out on a grid, which is what makes Cut /
+ * Copy / Paste Special line up under each other beside a tall Paste, the
+ * way they do in Excel, without per-group pixel widths.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+export { FONT_SIZES, applyBorders, type BorderPreset } from './shortcuts.js';
+import type { RibbonIconName } from './ribbon-icons.js';
+/** What the host has to render for one control. */
+export type RibbonItemKind = 
+/** Runs and forgets. */
+'button'
+/** Runs, and paints itself on when `isOn` reports true for the selection. */
+ | 'toggle'
+/** A dropdown showing the selection's current value; `run` receives the pick. */
+ | 'select'
+/**
+ * Excel's split button: the face applies the last value picked (or
+ * `initial`), the arrow opens a menu of `options`. A `palette` menu is
+ * the colour picker; otherwise it is a list, with an icon per entry.
+ */
+ | 'menu'
+/**
+ * Excel's plain menu button (Format, Sort & Filter): the face opens the
+ * list and each entry is an action of its own, raised through `emits`
+ * or run through `run(cmd, value)`. Entries with `heading` are the
+ * section labels Excel prints between the groups.
+ */
+ | 'dropdown';
+export type RibbonOption = {
+    value: string;
+    label: string;
+    /** List menus: the glyph beside the label. */
+    icon?: RibbonIconName;
+    /** Dropdowns: the entry raises this action rather than running the item. */
+    emits?: RibbonActionId;
+    /** Dropdowns: printed after the label, the way Excel prints Ctrl+1. */
+    keys?: string;
+    /** Dropdowns: a section label, not an entry. */
+    heading?: boolean;
+    /** Dropdowns: the entry is a toggle, lit while its action is active. */
+    toggle?: boolean;
+};
+export type RibbonItem = {
+    id: string;
+    /** The button face, or the label under a large button. */
+    label: string;
+    /** Long form for the tooltip and the accessible name. */
+    title: string;
+    /** Drawn on the face. Without one the face prints `label`, which is what
+     *  Bold, Italic and the number-format buttons want: B, I, $, %. */
+    icon?: RibbonIconName;
+    /** Shown after the title in the tooltip, the way Excel does it. */
+    keys?: string;
+    kind: RibbonItemKind;
+    /**
+     * Excel's two button sizes. A large button is an icon over a label and
+     * fills the group's height; a small one is a 24px strip. Large is the
+     * command a group exists for (Paste, Sort & Filter, Text to Columns);
+     * everything else is small.
+     */
+    size?: 'large' | 'small';
+    /** Small buttons only: which of the group's three rows this sits on. */
+    row?: 1 | 2 | 3;
+    /** Small buttons only: print the label beside the icon. */
+    wide?: boolean;
+    /** Run the action. Returns false when it declined (nothing selected, no
+     *  store attached), which the renderer uses to avoid claiming it worked. */
+    run?: (cmd: GridCommandContext, value?: string) => boolean;
+    /** Toggles only. */
+    isOn?: (cmd: GridCommandContext) => boolean;
+    /**
+     * Lit while this action is among the shell's active actions, for an item
+     * that runs rather than emits: Merge & Center's face lights while the
+     * active cell is merged, as Excel's does.
+     */
+    lit?: RibbonActionId;
+    /** Defaults to enabled. Reports false when the action has nothing to act
+     *  on, so the button greys out rather than doing nothing on click. */
+    isEnabled?: (cmd: GridCommandContext) => boolean;
+    /** `select` and `menu` only. */
+    options?: ReadonlyArray<RibbonOption>;
+    /** `select` only: the value the selection currently has, so the control
+     *  reads "Calibri" or "General" for the active cell rather than a blank. */
+    current?: (cmd: GridCommandContext) => string;
+    /** `menu` only: render `options` as Excel's colour grid. */
+    palette?: boolean;
+    /** Palette menus: the "No Fill" / "Automatic" entry at the top. */
+    none?: RibbonOption;
+    /** Menus: the value the face applies before anything has been picked.
+     *  Excel starts Fill Colour on yellow and Font Colour on red. */
+    initial?: string;
+    /** Set instead of `run` when the action needs chrome this layer does not
+     *  own. The renderer calls `onAction(emits, cmd)`. */
+    emits?: RibbonActionId;
+    /**
+     * Dropdowns only: Excel's split button. The face runs the item (Paste
+     * pastes) and the arrow opens the entries, each an action of its own;
+     * an entry without `emits` runs the item with its value.
+     */
+    split?: boolean;
+};
+/** Actions the ribbon delegates to the host rather than running itself. */
+export type RibbonActionId = 'file-new' | 'file-open' | 'file-save-xlsx' | 'file-export-csv' | 'file-save-ods' | 'file-save-xls' | 'file-print' | 'page-portrait' | 'page-landscape' | 'paper-a4' | 'paper-a3' | 'paper-a5' | 'paper-letter' | 'paper-legal' | 'paper-tabloid' | 'margins-normal' | 'margins-narrow' | 'margins-wide' | 'print-area-set' | 'print-area-clear' | 'print-titles' | 'page-setup' | 'print-gridlines' | 'print-headings' | 'paste-special' | 'cut' | 'undo' | 'redo' | 'format-cells' | 'find-replace' | 'insert-function' | 'name-manager' | 'text-to-columns' | 'remove-duplicates' | 'goal-seek' | 'insert-chart' | 'insert-picture' | 'chart-setup' | 'delete-object' | 'delete-sheet' | 'sparkline-line' | 'sparkline-column' | 'sparkline-winloss' | 'sparkline-setup' | 'clear-sparklines' | 'insert-pivot' | 'refresh-pivot' | 'insert-link' | 'remove-table' | 'table-style' | 'pivot-details' | 'remove-link' | 'insert-table' | 'recalculate' | 'insert-checkbox' | 'insert-cell-button' | 'clear-cell-type' | 'group-rows' | 'group-cols' | 'auto-outline' | 'ungroup-rows' | 'ungroup-cols' | 'clear-outline' | 'show-detail' | 'hide-detail' | 'calc-options' | 'evaluate-formula' | 'error-checking' | 'toggle-formulas' | 'trace-precedents' | 'trace-dependents' | 'remove-arrows' | 'sort-asc' | 'sort-desc' | 'sort-custom' | 'toggle-filter' | 'freeze-panes' | 'unfreeze-panes' | 'hide-rows' | 'hide-columns' | 'unhide-rows' | 'unhide-columns' | 'row-height' | 'column-width' | 'autofit-rows' | 'autofit-columns' | 'paste-values' | 'paste-formulas' | 'paste-formats' | 'paste-transpose' | 'format-painter' | 'protect-sheet' | 'unprotect-sheet' | 'allow-edit-ranges' | 'toggle-lock' | 'new-comment' | 'edit-comment' | 'delete-comment' | 'prev-comment' | 'next-comment' | 'toggle-comments' | 'data-validation' | 'circle-invalid' | 'clear-circles' | 'open-list' | 'freeze-top-row' | 'freeze-first-column' | 'toggle-gridlines' | 'toggle-formula-bar' | 'toggle-headings' | 'toggle-ribbon' | 'cf-greater' | 'cf-less' | 'cf-between' | 'cf-equal' | 'cf-text' | 'cf-duplicates' | 'cf-top10' | 'cf-bottom10' | 'cf-above-average' | 'cf-below-average' | 'cf-data-bar' | 'cf-color-scale-3' | 'cf-color-scale-2' | 'cf-icon-set' | 'cf-formula' | 'cf-clear-selection' | 'cf-clear-sheet' | 'cf-manage' | 'merge-center' | 'merge-across' | 'merge-cells' | 'unmerge-cells';
+export type RibbonGroup = {
+    id: string;
+    /** Printed under the group, which is what makes a ribbon a ribbon. */
+    label: string;
+    /** What the group's one button shows once the band has folded it. */
+    icon?: RibbonIconName;
+    /**
+     * How the small items are arranged.
+     *
+     * `grid` (the default) is Excel's column model: items on the same row
+     * line up in columns, so a stack of Cut / Copy / Paste Special is one
+     * neat column and AutoSum / Fill / Clear another. `flow` lets each row
+     * run freely, which is what the Font group needs: a wide font box next
+     * to a size box on row one, and a run of narrow B I U buttons under it,
+     * with nothing forcing the two rows into shared columns.
+     */
+    layout?: 'grid' | 'flow';
+    /** Excel's dialog box launcher: the small arrow in the group's corner
+     *  that opens the full dialog for what the group does. */
+    launcher?: RibbonActionId;
+    items: ReadonlyArray<RibbonItem>;
+};
+export type RibbonTab = {
+    id: string;
+    label: string;
+    groups: ReadonlyArray<RibbonGroup>;
+};
+/**
+ * Move the decimal count of a number-format pattern by `delta`.
+ *
+ * Exported because it is the fiddly part and deserves its own tests: the
+ * pattern can have a prefix and a suffix (`$#,##0.00`, `0.0%`), can have no
+ * decimal section at all, and must not go below zero or run away past the 30
+ * places Excel allows.
+ */
+export declare function withDecimals(pattern: string, delta: number): string | null;
+/**
+ * The fonts a spreadsheet user reaches for, with the stacks that make each
+ * render on a machine that lacks it. The empty value is the theme's own
+ * font, which is what "Default" means here and what a fresh cell has.
+ */
+export declare const FONT_FAMILIES: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+export declare const RIBBON_TABS: ReadonlyArray<RibbonTab>;
+/** Every item across every tab, for tests and for a command palette. */
+export declare function ribbonItems(): ReadonlyArray<RibbonItem>;