@xlcalc/vue 0.21.2 → 0.23.1

package/dist/validation-rules.d.ts

@@ -0,0 +1,95 @@
+import type { CellPosition, CellRect, DataValidation, ScanOptions, ValidationOperator, ValidationType } from 'xlcalc/contract';
+import type { Entry } from './entry.js';
+/** The types in the order of Excel's Allow box, and the comparisons of its Data box. */
+export declare const VALIDATION_TYPES: readonly ValidationType[];
+export declare const VALIDATION_OPERATORS: readonly ValidationOperator[];
+/** Excel's limits on a rule's texts: the input message's title and text, the error alert's title and text. */
+export declare const VALIDATION_LIMITS: {
+    readonly promptTitle: 32;
+    readonly prompt: 255;
+    readonly errorTitle: 32;
+    readonly error: 225;
+};
+/** The boxes of the Settings tab, as Excel names them by the type and the comparison. */
+export type ValidationBox = 'min' | 'max' | 'value' | 'length' | 'start' | 'end' | 'date' | 'startTime' | 'endTime' | 'time' | 'source' | 'formula';
+export type ValidationTab = 'settings' | 'input' | 'error';
+export declare const VALIDATION_TABS: readonly ValidationTab[];
+/** The dialog's inputs; the boxes hold what is typed until OK reads them. */
+export interface ValidationDraft {
+    type: ValidationType;
+    operator: ValidationOperator;
+    /** The first box (Minimum, Value, Source, Formula) and the second (Maximum). */
+    first: string;
+    second: string;
+    allowBlank: boolean;
+    dropdown: boolean;
+    /** Apply these changes to all other cells with the same settings. */
+    applyAll: boolean;
+    showPrompt: boolean;
+    promptTitle: string;
+    prompt: string;
+    showError: boolean;
+    errorStyle: 'stop' | 'warning' | 'information';
+    errorTitle: string;
+    error: string;
+}
+/** How formula text reads and writes in the workbook's locale: its references (`xlcalc/text`), and typed values (`xlcalc/entry`). */
+export interface RuleText {
+    scan: ScanOptions;
+    entry: Entry;
+}
+/** What Excel does before the dialog opens: no rule in the selection, one covering it, one covering part of it ("extend?"), or several ("erase?"). */
+export type ValidationPlan = {
+    kind: 'none';
+} | {
+    kind: 'one' | 'extend';
+    rule: DataValidation;
+} | {
+    kind: 'many';
+};
+/** Why OK is refused: an empty box, a box whose value is not one, or a maximum below the minimum. */
+export type DraftError = {
+    kind: 'empty' | 'invalid';
+    box: ValidationBox;
+} | {
+    kind: 'order';
+    min: ValidationBox;
+    max: ValidationBox;
+};
+/** A rule's settings without its cells, with formulas written for the active cell. */
+export type RuleSettings = Omit<DataValidation, 'range'>;
+export declare const isCompared: (type: ValidationType) => boolean;
+/** The boxes Excel's Settings tab shows for a type and a comparison, first box first. */
+export declare function boxesOf(type: ValidationType, operator: ValidationOperator): ValidationBox[];
+export declare const emptyDraft: () => ValidationDraft;
+/** A rule's ranges (`B2:B9 D2`) as rectangles; a part that is not one is skipped. */
+export declare const rectsOf: (range: string) => CellRect[];
+/**
+ * What Excel finds in the selection when Data Validation opens: no rule; one rule's settings over every cell; the same
+ * settings over some cells only, when Excel asks whether to extend them; rules of more than one kind, when it asks whether to
+ * erase them. The rule shown is the one containing the active cell where it is one of them.
+ */
+export declare function planOf(rules: DataValidation[], sel: CellRect, at: CellPosition, scan: ScanOptions): ValidationPlan;
+/** The dialog's inputs for a rule (Excel's defaults without one), its formulas shown for the active cell `at`, with `=`. */
+export declare function draftOf(rule: DataValidation | null, at: CellPosition, t: RuleText): ValidationDraft;
+/**
+ * The rule OK makes from the dialog's inputs, its formulas for the active cell, or null for none (Any value without a
+ * message: the cells lose their rule); or why Excel refuses it. Only what differs from a new rule's defaults is written.
+ */
+export declare function ruleOf(d: ValidationDraft, t: RuleText): {
+    ok: true;
+    rule: RuleSettings | null;
+} | {
+    ok: false;
+    error: DraftError;
+};
+/**
+ * The sheet's rules after OK: the new rule (`made`, its formulas for the active cell `at`, or null for none) over the
+ * selection, and with `sameAs` (Apply these changes to all other cells with the same settings) over every cell with that
+ * rule's settings too; a rule partly covered keeps its other cells, with its formulas written for its new top-left cell.
+ * Also the ranges whose rules changed.
+ */
+export declare function rulesAfter(rules: DataValidation[], sel: CellRect, at: CellPosition, made: RuleSettings | null, sameAs: DataValidation | null, scan: ScanOptions): {
+    rules: DataValidation[];
+    ranges: string[];
+};

package/docs/api.md

@@ -16,7 +16,8 @@ Cell and style types come from `xlcalc/contract` (`CellValue`, `CellStyle`, `Sty
 
 ## `SheetView`
 
-The sheet: a virtualized grid with the formula bar, sheet tabs, context menus, Find, the Trace Precedents panel and the dialogs. It reads its data only through `source`.
+The sheet: a virtualized grid with the formula bar, sheet tabs, context menus, Find, the Trace Precedents panel, the Watch Window, the zoom and the dialogs. It reads its data only through `source`.
+The sheet: a virtualized grid with the formula bar, sheet tabs, context menus, Find, the Trace Precedents panel, tracer arrows and the dialogs (Create Table, Spelling and others). It reads its data only through `source`.
 
 ```vue
 <script setup lang="ts">
@@ -65,7 +66,7 @@ const openLink = (link: SheetLinkEvent) => window.open(link.href, '_blank', 'noo
 | --- | --- | --- | --- |
 | `source` | `SheetSource` | required | The sheet's data source. A new source means a new workbook: what the previous source answers afterwards (its sheets, an edit's outcome, a correction) is ignored, even from a source that ignores the abort signal, and its open alert closes. |
 | `messages` | `Partial<SheetMessages>` | English | Interface texts; a partial set overrides the English defaults. |
-| `storageKey` | `string` | none | Key in the browser's storage for the frozen panes display choice, column widths and Insert Function's recently used functions; without it they last as long as the component. |
+| `storageKey` | `string` | none | Key in the browser's storage for the frozen panes display choice, Show Formulas on each sheet, column widths, Insert Function's recently used functions and the Symbol dialog's recently used symbols; without it they last as long as the component. |
 | `focus` | `{ ref: string } \| null` | `null` | A location to show: `Sheet!B12:D15`, `B7`, `Sheet`. Each new object is a new jump. |
 | `cellUrl` | `(ref: string) => string` | none | The host page's address for a location; without it there is no "Link to the cell" button. |
 | `readOnly` | `boolean` | `false` | Disables editing regardless of what the source supports. A source without `edit` is read-only anyway. |
@@ -76,6 +77,9 @@ const openLink = (link: SheetLinkEvent) => window.open(link.href, '_blank', 'noo
 | `sort` | `ListSort \| null` | `null` | List mode: the order the host sorted the list in, shown as an arrow on that column's title. |
 | `openRows` | `boolean` | `false` | List mode: the first column opens its row, and so does Enter on a cell that is not a drill-down. |
 | `hostLinks` | `boolean` | `false` | The host opens links itself through `openLink`, as when it listens: for a host whose listener the sheet cannot see, such as a custom element's. |
+| `zoom` | `Record<string, number>` | none | Excel's zoom by sheet name, in percent (10 to 400), as the host kept it from the `zoom` event; a sheet without one opens at the workbook's saved zoom (`SheetInfo.zoom`), otherwise 100%. A new object applies its changed entries, to the active sheet at once. See [view.md](view.md#zoom). |
+| `watches` | `SheetWatch[]` | none | The Watch Window's list, as the host kept it from the `watches` event; a new array replaces the list. See [view.md](view.md#watch-window). |
+| `noteAuthor` | `string` | none | The author's name for a new note, shown in bold on its first line, as Excel takes the user name from its Options; without it a new note has no author. |
 
 ### Events
 
@@ -86,6 +90,8 @@ const openLink = (link: SheetLinkEvent) => window.open(link.href, '_blank', 'noo
 | `sort` | `ListSort` | List mode: a sortable column's title was clicked. The host sorts the list, sets `sort` and sends `reload`. |
 | `cellDrill` | `{ sheet: string; cell: string }` | List mode: a drill-down cell (`SheetWindow.drill`) was clicked or Enter was pressed on it. |
 | `rowOpen` | `{ sheet: string; row: number }` | List mode, with `openRows`: a row was opened from its first column or by Enter. |
+| `zoom` | `SheetZoomEvent` | The user changed a sheet's zoom: Ctrl+wheel, a pinch (once it ends), the status bar, the Zoom dialog. `SheetZoomEvent` is `{ sheet: string; zoom: number }`, in percent. `setZoom` and the `zoom` prop are not reported. |
+| `watches` | `SheetWatch[]` | The user added or deleted watches in the Watch Window: the whole list. `SheetWatch` is `{ sheet: string; cell: string }`. |
 
 ### Slot
 
@@ -103,14 +109,19 @@ const openLink = (link: SheetLinkEvent) => window.open(link.href, '_blank', 'noo
 | `value` | `string?` | The active cell's displayed text. |
 | `style` | `CellStyle?` | The active cell's style; absent while its window is not loaded. |
 | `numberFormat` | `string?` | The active cell's number format code; absent for General. |
+| `cellValue` | `CellValue?` | The active cell's value from the loaded window, absent for an empty cell; the toolbar's Increase and Decrease Decimal step from it. |
+| `columnWidth` | `number?` | The active cell's column width as the workbook stores it (xlcalc's units), absent for the default. |
 | `merged` | `string?` | The merged range containing the active cell. |
 | `canMerge` | `true?` | The merge commands are available: the source has `structure`, the sheet is editable, and no display filter is on. |
+| `showFormulas` | `true?` | Excel's Show Formulas is on for the displayed sheet, so a ribbon shows its button pressed ([view.md](view.md#show-formulas)). |
+| `zoom` | `number?` | The sheet's zoom in percent; absent at 100%. |
+| `font` | `{ name; size }?` | The workbook's default font (`SheetInfo.font`), which a cell without a font of its own displays; the toolbar's Font and Font Size boxes show it for such a cell. |
 
 `SheetLinkEvent` is a window's hyperlink (`href`, `location`, `tooltip`, `target`) with the `sheet` and `cell` it belongs to. `SheetFailure` is `{ error: unknown; text: string }`.
 
 ### `SheetViewApi`
 
-`SheetView` exposes these methods through a template ref (`ref="sheet"`, `const sheet = ref<SheetViewApi | null>(null)`). Each call goes through the source just as the sheet's own keyboard commands do: the outcome is applied, its selection is set without the flash and the Back history entry that `focus` creates, a rejection is displayed in the sheet's message line, and after `format`, `structure`, `outline` or `freezePanes` the sheet reloads unless the source has sent `reload` (after `format`, also unless it has sent `repaint`, which re-reads the windows over its ranges). A method that returns a promise of `EditOutcome | null` resolves to the source's outcome, or to `null` when nothing was sent (the source lacks the method, the sheet is read-only, or an undo is still pending).
+`SheetView` exposes these methods through a template ref (`ref="sheet"`, `const sheet = ref<SheetViewApi | null>(null)`). Each call goes through the source just as the sheet's own keyboard commands do: the outcome is applied, its selection is set without the flash and the Back history entry that `focus` creates, a rejection is displayed in the sheet's message line, and after `format`, `structure`, `outline`, `freezePanes` or a table command the sheet reloads unless the source has sent `reload` (after `format`, also unless it has sent `repaint`, which re-reads the windows over its ranges). A method that returns a promise of `EditOutcome | null` resolves to the source's outcome, or to `null` when nothing was sent (the source lacks the method, the sheet is read-only, or an undo is still pending).
 
 | Method | Returns | Meaning |
 | --- | --- | --- |
@@ -121,9 +132,37 @@ const openLink = (link: SheetLinkEvent) => window.open(link.href, '_blank', 'noo
 | `outline(change: OutlineChange)` | `Promise<EditOutcome \| null>` | Group, Ungroup, a group's button, a level button. |
 | `freezePanes(mode?: FreezeMode)` | `Promise<EditOutcome \| null>` | Excel's Freeze Panes through the source's `freeze`: `'panes'` (the default, at the active cell), `'unfreeze'`, `'topRow'`, `'firstColumn'`. Nothing is sent when there is nothing to freeze or unfreeze. |
 | `merge(command: MergeCommand)` | `Promise<EditOutcome \| null>` | `'mergeCenter'`, `'mergeAcross'`, `'mergeCells'` or `'unmergeCells'` over the selection through `structure`, with Excel's warning first when values would be lost. `null` also for a single cell outside a merged range, under a display filter, and on Cancel in the warning. |
+| `fillDown()` | `Promise<EditOutcome \| null>` | Excel's Fill Down (Ctrl+D) through `structure`: the selection's top row copied over its other rows, or the row above into a selection one row tall ([editing.md](editing.md)). `null` also under a display filter, for row 1 alone, and when a filled cell is locked. |
+| `fillRight()` | `Promise<EditOutcome \| null>` | Excel's Fill Right (Ctrl+R): the same along the columns, from the selection's left column or the column to its left. |
+| `showFormulas(on?: boolean)` | `boolean` | Turns Excel's Show Formulas on or off on the displayed sheet, or toggles it without `on`, as Ctrl+` does; whether it is on afterwards. A view setting: nothing goes to the source. |
 | `formatCells()` | `boolean` | Opens Excel's Format Cells dialog; `false` when the sheet cannot be formatted. |
 | `reapplyFilter()` | `Promise<boolean>` | Excel's Reapply; `false` when no display filter is on. |
 | `explain()` | `boolean` | Opens the Trace Precedents panel for the active cell; `false` if the source has no `explain`. |
+| `goTo()` | `boolean` | Opens Excel's Go To dialog (F5, Ctrl+G); `false` while no sheet is displayed ([go-to-and-symbol.md](go-to-and-symbol.md#go-to)). |
+| `insertSymbol()` | `boolean` | Opens Excel's Symbol dialog: Insert puts the character at the caret of an open edit, otherwise starts editing the active cell with it; `false` on a read-only sheet or without an active cell ([go-to-and-symbol.md](go-to-and-symbol.md#symbol)). A host button that calls it during an edit keeps the edit open only if it does not take focus (`@mousedown.prevent`). |
+| `defineName()` | `boolean` | Opens Excel's New Name dialog (Define Name) for the selection; `false` when names cannot be defined (no `names` or `setNames`, a read-only sheet) or a cell is being edited. See [names.md](names.md). |
+| `nameManager()` | `boolean` | Opens Excel's Name Manager (Ctrl+F3); `false` without the source's `names` or while a cell is being edited. Without `setNames` or on a read-only sheet it only lists the names. |
+| `setZoom(zoom: number \| 'selection')` | `number` | Excel's zoom of the active sheet: a percentage, rounded and kept within 10 to 400, or `'selection'` for Zoom to Selection. Returns the zoom set; it is not reported by the `zoom` event. |
+| `watchWindow(open?: boolean)` | `boolean` | Opens the Watch Window (`true`, the default) or closes it (`false`); returns whether it is open. |
+| `traceDependents()` | `Promise<boolean>` | Excel's Trace Dependents through the source's `dependents`: arrows from the active cell to its direct dependents, and the next level with each further call; `false` when nothing was added. See [view.md](view.md#trace-dependents). |
+| `removeArrows()` | `boolean` | Excel's Remove Arrows: every tracer arrow; `false` when there were none. |
+| `insertTable()` | `Promise<boolean>` | Excel's Insert Table and Format as Table (Ctrl+T, Ctrl+L): the Create Table dialog for the selection or the active cell's current region; `false` without the source's `table` or on a read-only sheet. See [tables.md](tables.md). |
+| `convertToRange()` | `Promise<EditOutcome \| null>` | Excel's Convert to Range on the table at the active cell, after Excel's question. |
+| `deleteTable()` | `Promise<EditOutcome \| null>` | Delete Table: the table at the active cell with its cells. |
+| `checkSpelling()` | `boolean` | Excel's Spelling (F7) through the source's `spelling`: the dialog from the active cell, within a selection of more than one cell; `false` without `spelling`. See [editing.md](editing.md#spelling). |
+| `autoSum()` | `Promise<boolean>` | Excel's AutoSum (Alt+=) through the source's `autoSum`: the active cell's edit opens with `=SUM(range)`, the range selected, so Enter enters it and typing or the arrows replace it; `false` without `autoSum`, on a read-only sheet, while a cell is being edited or when the source guesses nothing. See [editing.md](editing.md#autosum). |
+| `clear(what: ClearKind)` | `Promise<EditOutcome \| null>` | Excel's Home > Clear > Clear Formats (`'formats'`) or Clear All (`'all'`) over the selection through the source's `clear`, as a single undo step; under a display filter, over its visible rows. `null` also over a locked cell. See [links-notes.md](links-notes.md#clear-formats-and-clear-all). |
+| `insertLink()` | `boolean` | Opens Excel's Insert Hyperlink dialog (Ctrl+K) for the selection, as Edit Hyperlink when the active cell has a link; OK writes the link through the source's `link`. `false` without `link`, on a read-only sheet or over a locked cell. See [links-notes.md](links-notes.md#hyperlinks). |
+| `dataValidation()` | `boolean` | Opens Excel's Data Validation dialog for the selection over the source's `rules` and `setRules`, after Excel's question where the selection holds rules of more than one kind or cells without the rule; `false` when the sheet is read-only or the source lacks either method. See [validation.md](validation.md#the-data-validation-dialog). |
+| `quickRule(kind: QuickRule)` | `boolean` | Opens the dialog of a quick rule from Excel's Highlight Cells Rules or Top/Bottom Rules for the selection; OK adds the rule first in priority. `false` without the source's `rules` and `setRules` or on a read-only sheet, as for the methods below. See [conditional-formatting.md](conditional-formatting.md). |
+| `dataBars(color: DataBarColor, fill?: 'gradient' \| 'solid')` | `Promise<EditOutcome \| null>` | Adds Excel's data bar of that color over the selection. |
+| `colorScale(preset: ColorScalePreset)` | `Promise<EditOutcome \| null>` | Adds a color scale of Excel's gallery over the selection. |
+| `iconSet(icons: IconSetName)` | `Promise<EditOutcome \| null>` | Adds an icon set over the selection, with Excel's thresholds in percent. |
+| `clearRules(from: ClearRulesFrom)` | `Promise<EditOutcome \| null>` | Excel's Clear Rules from Selected Cells (`'selection'`: a rule keeps the rest of its cells) or from Entire Sheet (`'sheet'`); `null` when no rule is there to clear. |
+| `newRule()` | `boolean` | Opens Excel's New Formatting Rule dialog for the selection. |
+| `manageRules()` | `boolean` | Opens Excel's Conditional Formatting Rules Manager. |
+
+`QuickRule` is `'greaterThan' | 'lessThan' | 'between' | 'equalTo' | 'textContains' | 'dateOccurring' | 'duplicateValues' | 'top10' | 'top10Percent' | 'bottom10' | 'bottom10Percent' | 'aboveAverage' | 'belowAverage'`, `DataBarColor` is `'blue' | 'green' | 'red' | 'orange' | 'lightBlue' | 'purple'`, `ColorScalePreset` names a color scale of Excel's gallery from the highest numbers' color to the lowest's (`'greenYellowRed'`, `'redYellowGreen'`, `'greenWhiteRed'`, `'redWhiteGreen'`, `'blueWhiteRed'`, `'redWhiteBlue'`, `'whiteRed'`, `'redWhite'`, `'greenWhite'`, `'whiteGreen'`, `'greenYellow'`, `'yellowGreen'`), and `ClearRulesFrom` is `'selection' | 'sheet'`; `IconSetName` is xlcalc's.
 
 `SheetFormatPatch` is a `FormatPatch` whose `range` is optional. `FreezeMode` is `'panes' | 'unfreeze' | 'topRow' | 'firstColumn'`, `MergeCommand` is `'mergeCenter' | 'mergeAcross' | 'mergeCells' | 'unmergeCells'`. `ListSort` is `{ col: number; dir: 'asc' | 'desc' }`, with a 1-based column.
 
@@ -178,12 +217,13 @@ Excel's formatting toolbar over the same source; shown only when the source has
 | `locale` | `string` | The workbook's locale, in which the Number Format box names its categories and items; en-US without it. |
 | `sheet` | `SheetViewApi \| null` | The sheet's template ref. With it the toolbar formats, undoes, redoes and merges through the sheet; without it, through the source, and it emits `select` and `error`. |
 | `hostDialog` | `boolean` | The host opens its own dialog on `formatCells`, as when it listens: for a host whose listener the toolbar cannot see, such as a custom element's. |
+| `fonts` | `readonly string[]` | The Font box's list, in place of Excel's common fonts (Aptos, Arial, Calibri and others): a browser does not tell which fonts are installed. |
 
 | Event | Payload | When |
 | --- | --- | --- |
 | `select` | `{ sheet: string; range: string }` | Where the selection goes after an undo or a redo, for the sheet's `focus`; not emitted with `sheet`. |
 | `error` | `string` | The source rejected a call or the call failed; not emitted with `sheet`. |
-| `done` | none | A call has completed: the host may return focus to the grid. |
+| `done` | none | A call has completed, or Esc left the Font or Font Size box: the host may return focus to the grid. |
 | `formatCells` | none | Format Cells… was clicked. With a listener or `hostDialog`, the button opens the host's dialog; without one, it opens the sheet's dialog (through `sheet`), and without either there is no button. |
 
 ## `FormatDialog`
@@ -255,7 +295,7 @@ export function serverSource(base: string): SheetSource {
 | `structure(op: SheetOp)` | Structure operations on sheets, rows and columns (insert, delete, rename, move, hide); copying and moving ranges; merging. | No structure menu, no fill handle, and a copy is pasted as text. | [sheets.md](sheets.md), [clipboard.md](clipboard.md) |
 | `layout(change: LayoutChange)` | Column widths and row heights, hiding and fitting rows and columns. | A changed width lasts until the page reloads. | [sheets.md](sheets.md) |
 | `copyText(sheet, range, opts?) => Promise<string>` | Excel's clipboard text for a range. | The sheet copies the displayed text of its windows. | [clipboard.md](clipboard.md) |
-| `format(sheet, patches: FormatPatch[])` | Formatting, the toolbar, Format Cells, Ctrl+B/I/U. | No toolbar. | [toolbar.md](toolbar.md) |
+| `format(sheet, patches: FormatPatch[])` | Formatting, the toolbar, Format Cells, Ctrl+B/I/U, Ctrl+Shift+%. | No toolbar. | [toolbar.md](toolbar.md) |
 | `subscribe(listener: (e: SourceEvent) => void) => () => void` | Changes made elsewhere. Returns the unsubscribe function. | The sheet sees only its own edits. | [editing.md](editing.md) |
 | `validation(sheet, cell, signal?) => Promise<SheetValidation \| null>` | Excel's validation dropdown and input message. | None. | [validation.md](validation.md) |
 | `pick(sheet, cell, item, text)` | A picked list item written as Excel writes it. | The item goes to `edit` with `accept`. | [validation.md](validation.md) |
@@ -270,6 +310,20 @@ export function serverSource(base: string): SheetSource {
 | `outline(change: OutlineChange)` | The outline buttons, Group and Ungroup. | The bars are drawn, but their buttons do nothing. | [sheets.md](sheets.md) |
 | `visibleRows(sheet, filter, signal?) => Promise<{ rows: number[] \| null }>` | The display filter and sort. | No filter. | [view.md](view.md) |
 | `columnValues(sheet, col, filter, signal?) => Promise<{ values: { text; count }[]; more }>` | The filter funnel's list of values. | No list in the funnel. | |
+| `clear(sheet, ranges: string[], what: ClearKind)` | Excel's Clear Formats (`'formats'`: styles, number formats and the conditional formats over the cells) and Clear All (`'all'`: also contents, hyperlinks, notes and data validation rules), as a single undo step. Delete clears contents through `edit`. | Neither is offered. | [links-notes.md](links-notes.md) |
+| `link(sheet, range, link: SheetLink \| null)` | Excel's Insert Link over a range, the cells' contents kept; null is Remove Hyperlinks. | Links can be followed but not edited. | [links-notes.md](links-notes.md) |
+| `note(sheet, cell, note: SheetNote \| null)` | Excel's New Note and Edit Note; null is Delete Note. | Notes are shown but not edited. | [links-notes.md](links-notes.md) |
+| `names(signal?) => Promise<SheetName[]>` | The workbook's defined names for the Name Box, Go To, Formula AutoComplete and the Name Manager. | No names. | [names.md](names.md) |
+| `setNames(names: SheetName[])` | Replaces the workbook's names (the Name Manager, Define Name, a name typed into the Name Box), as a single undo step. | The names are shown but cannot be changed. | [names.md](names.md) |
+| `dependents(sheet, range, signal?) => Promise<SheetDependents>` | Excel's Trace Dependents: the cells whose formulas refer directly to the range. | No arrows. | [view.md](view.md#trace-dependents) |
+| `rules(sheet, signal?) => Promise<SheetRules>` | A sheet's conditional formatting and data validation rules, for their dialogs; with `setRules`, the Data Validation dialog. | The rules are applied but not shown for editing. | [conditional-formatting.md](conditional-formatting.md), [validation.md](validation.md#the-data-validation-dialog) |
+| `setRules(sheet, rules: Partial<SheetRules>)` | Replaces a sheet's conditional formatting rules, its data validation rules, or both, as a single undo step. | The rules cannot be edited. | [conditional-formatting.md](conditional-formatting.md), [validation.md](validation.md#the-data-validation-dialog) |
+| `table(op: TableOp)` | Excel's Format as Table, Insert Table, Rename, Delete Table and Convert to Range. | No table commands. | [tables.md](tables.md) |
+| `spelling(req: SpellingRequest, signal?) => Promise<SpellingHit \| null>` | Excel's Spelling: the next misspelt word from the active cell on, or null when there is none. | No Spelling. | [editing.md](editing.md#spelling) |
+| `learnWord(word) => Promise<void>` | Add to Dictionary in the Spelling dialog: the word is the user's own from then on. | No Add to Dictionary. | [editing.md](editing.md#spelling) |
+| `autoSum(sheet, cell, signal?) => Promise<SheetAutoSum \| null>` | Excel's AutoSum (Alt+=): the range it offers at the cell and its `SUM`; null when the source guesses nothing. | No AutoSum. | [editing.md](editing.md#autosum) |
+
+After `link`, `note`, `clear` and `setRules` succeed, the sheet re-reads the windows over what they changed: their outcome's `changes` carry values, not hyperlinks, notes or formatting. A source need not send a `repaint` for its own sheet, but `./local` does, for other sheets over the same source.
 
 | Property | Type | Meaning |
 | --- | --- | --- |
@@ -318,6 +372,8 @@ A window is a rectangular block of cells that the sheet reads from the source as
 | `rowNumbers` | `boolean?` | Row numbers on the left, shown by default. |
 | `totals` | `(string \| null)[]?` | List mode: a totals row pinned to the bottom of the viewport, the displayed text for each of the sheet's columns. |
 | `outline` | `SheetOutline?` | Excel's outline: `rows` and `columns` as `OutlineGroup[]` (`{ from, to, level, collapsed }`), `summaryBelow`, `summaryRight`. |
+| `font` | `{ name; size }?` | The workbook's default font (its Normal style), in which a cell without a font of its own is drawn; `--xs-font` without it. `./local` gives xlcalc's `BookInput.font`, Calibri 11 without one, the font in which xlcalc measures widths and `####`. |
+| `zoom` | `number?` | The sheet's saved zoom in percent (xlsx `zoomScale`), with which it opens; 100 without it. |
 
 ### Edits and outcomes
 
@@ -336,7 +392,24 @@ A window is a rectangular block of cells that the sheet reads from the source as
 - `{ kind: 'reload'; message? }`: the sheets and windows are read again.
 - `{ kind: 'repaint'; ranges: { sheet; range }[] }`: the windows that overlap the ranges are re-read in place.
 
-`FormatPatch` is `{ range, style?: StylePatch | null, numberFormat?: NumberFormat | null }`; `style: null` removes the cells' own style. `LayoutChange` is `{ sheet, columns, width?, hidden?, fit? }` or `{ sheet, rows, height?, hidden?, fit? }`. `SheetOp` is xlcalc's `StructureOp` without its table operations. `OutlineChange` is `{ op: 'group' | 'ungroup', sheet, rows | columns }`, `{ op: 'collapse' | 'expand', sheet, rows | columns, level }` or `{ op: 'showLevel', sheet, axis, level }`.
+`FormatPatch` is `{ range, style?: StylePatch | null, numberFormat?: NumberFormat | null }`; `style: null` removes the cells' own style. `LayoutChange` is `{ sheet, columns, width?, hidden?, fit? }` or `{ sheet, rows, height?, hidden?, fit? }`. `SheetOp` is xlcalc's `StructureOp` without its table operations, which go to `table`. `OutlineChange` is `{ op: 'group' | 'ungroup', sheet, rows | columns }`, `{ op: 'collapse' | 'expand', sheet, rows | columns, level }` or `{ op: 'showLevel', sheet, axis, level }`.
+
+### Beside cell values: links, notes, names, rules, tables, spelling
+
+Formulas in these types are written as the source displays formulas: in its locale, without `=`.
+
+| Type | Shape |
+| --- | --- |
+| `ClearKind` | `'formats' \| 'all'` |
+| `SheetLink` | `{ href?; location?; tooltip? }`: an address outside the workbook, a place in it (`'Sheet 2'!B12`, a defined name), or both, and the ScreenTip. |
+| `SheetNote` | `{ author?; text }` |
+| `SheetName` | `{ name; ref; scope? }`: what the name refers to as a formula, and the sheet it is visible on (the workbook without `scope`). |
+| `SheetDependent`, `SheetDependents` | `{ sheet; cell }`; `{ cells: SheetDependent[]; more: boolean }`, `more` when the source left some out. |
+| `SheetRules` | `{ conditionalFormats: ConditionalFormat[]; validations: DataValidation[] }`, xlcalc's types, conditional formats in priority order. |
+| `TableOp` | xlcalc's table operations of `StructureOp`: `addTable`, `renameTable`, `deleteTable`, `convertTable`. |
+| `SpellingRequest` | `{ sheet; range?; after?; from?; ignore? }`: from the active cell `after` (at position `from` of its text, after Ignore Once on a word of it) on, by rows, wrapping around, within `range` or the entire sheet, skipping the words of Ignore All. Formulas, words in uppercase and words with digits are not checked, as Excel's defaults. |
+| `SpellingHit` | `{ cell; word; at; suggestions }`: the word, its position in the cell's text, and corrections, best first. |
+| `SpellChecker` | `{ check(word): boolean; suggest(word): string[]; add?(word): void }`: the host's dictionary (hunspell's, for example) and the user's own words, which `memorySource` and `./local` take as `spelling`. |
 
 ### Find, filter, validation
 
@@ -347,31 +420,36 @@ A window is a rectangular block of cells that the sheet reads from the source as
 | `ReplaceOutcome` | `EditOutcome & { replaced: number; refused?: { sheet, cell, message }[] }` |
 | `SheetFilter` | `{ head: number; cols?: Record<number, { values?: string[]; text?: string }>; sort?: { col; dir: 'asc' \| 'desc' } }` |
 | `RangeStats` | `{ cells, numbers, sum, min, max }` |
+| `SheetAutoSum` | `{ range: string \| null; formula: string }`: the range AutoSum offers (the run of numbers above the cell, else to its left, up to a subtotal), null without numbers, and its formula as the source displays formulas, without `=` (`SUM(B2:B9)`, `СУММ(B2:B9)` in ru-RU, `SUM()` without a range). `./local` gives xlcalc's `getAutoSum` (xlcalc 0.59 and later), null with an older one. |
 | `SheetFunctionSignature` | xlcalc's `FunctionSignature` with `description?`, a one-line description of the function in the source's locale, for Insert Function. |
 | `SheetValidation` | `{ list?: string[]; prompt?: { title?; text } }` |
 | `SheetValidationAlert` | `{ severity: 'stop' \| 'warning' \| 'information'; title?; message; sheet; cell }` |
 
 ## Interface texts: `SheetMessages`
 
-`enMessages` (the default) and `ruMessages` are complete sets. A host passes a set, or part of one, as `messages`; the keys and their arguments are declared in `src/contract/messages.ts`.
+`enMessages` (the default) and `ruMessages` are complete sets. A host passes a set, or part of one, as `messages`; the keys and their arguments are declared in `src/contract/messages.ts`, those of the conditional formatting dialogs (`cf…`) in its `ConditionalMessages`, which `SheetMessages` extends.
 
 ```ts
 import { ruMessages } from '@xlcalc/vue'
 const messages = { ...ruMessages, loading: 'Загружаю…' }
 ```
 
+Two types name the arguments of the Symbol dialog's texts: `SymbolSubset`, the Subset list's Unicode blocks (`'basicLatin'`, `'latin1'`, `'cyrillic'`, `'currency'` and so on, as `symbolSubset` names them), and `SymbolSpecial`, the Special Characters tab's characters (`'emDash'`, `'copyright'` and so on, as `symbolSpecial` names them).
+
 ## `memorySource`
 
 `memorySource(book: MemoryBook, options?: MemorySourceOptions): MemorySource` is a source over an in-memory workbook, for an example or a test. It has no engine: a formula's value is whatever the cell's `value` specifies. Find and Replace search a cell's formula, otherwise its value's `entryText` in en-US (`xlcalc/entry`, loaded on the first search).
 
 | Type | Shape |
 | --- | --- |
-| `MemoryBook` | `{ sheets: MemorySheet[]; styles?: CellStyle[]; functions?: string[] }`; `functions` enables `functionNames`. |
+| `MemoryBook` | `{ sheets: MemorySheet[]; styles?: CellStyle[]; functions?: string[]; names?: SheetName[] }`; `functions` enables `functionNames`; `names` are kept as text (there is no engine to calculate them). |
 | `MemorySheet` | `SheetInfo` without `maxRow`, `maxCol` and `outline`, plus `cells: Record<string, MemoryCell \| CellValue>`, `widths?` (keyed by `B`, `B:D` or `C:C`, in xlsx units, 0 hides), `heights?` (keyed by `5`, `5:9` or `5:5`, in points, 0 hides), `defaultRowHeight?`, `merges?`, `tables?`, `notice?`, `outline?: MemoryOutline`, `validations?: MemoryValidation[]`. |
 | `MemoryOutline` | `{ rows?: Record<string, number>; columns?: Record<string, number>; collapsed?: string[]; summaryBelow?: boolean; summaryRight?: boolean }`: outline levels (1 to 7) by row, column or span, keyed as in `widths` and `heights` (`'3:9': 1`, `'C:E': 2`), the summary rows and columns marked collapsed (`'10'`, `'F'`), and where the summaries are (below and to the right by default). |
 | `MemoryCell` | `{ value?, text?, formula?, style?, color?, numberFormat?, link?, note?, appearance?, drill? }`; `numberFormat` is the code the cell is displayed with (`0.0%`, `dd.mm.yyyy`), which the windows return as `numberFormats`, so a percentage or a date opens for editing as in Excel. |
 | `MemoryValidation` | `{ range; list?: string[]; whole?: { min?; max? }; prompt?: { title?; text }; alert?: { severity?; title?; message? } }` |
-| `MemorySourceOptions` | `{ delay?: number; maxCells?: number }`; `delay` makes every response take that many milliseconds. |
+| `MemorySourceOptions` | `{ delay?: number; maxCells?: number; spelling?: SpellChecker }`; `delay` makes every response take that many milliseconds; `spelling` enables `spelling` and `learnWord`. |
+
+`memorySource` also has `clear`, `link`, `note`, `names` and `setNames` (a name is checked as Excel checks one); without an engine it has no `dependents`, `rules`, `setRules` or `table`.
 
 `MemorySource` is a `SheetSource` with four extra methods for tests and examples: `failNext(...outcomes)` makes the next edits fail with these outcomes, `emit(event)` sends an event to the subscribers, `setCells(sheet, entries)` changes cells as another tab would, and `recompute(ms)` makes windows return `pending` for that long.
 
@@ -434,6 +512,7 @@ The options, `LocalSourceOptions`:
 | `session` | `AsyncSessionOptions` | Options for the workbook's session; `{ cached }` from `openXlsx` keeps a file's stored values. |
 | `maxCells` | `number` | The maximum number of cells in one window, 20,000 by default. |
 | `notice` | `string` | A notice included in every window. |
+| `spelling` | `SpellChecker` | The host's word checker; enables `spelling` and `learnWord`. |
 
 ```ts
 import { localSource } from '@xlcalc/vue/local'
@@ -447,7 +526,7 @@ console.log(source.locale, await source.book())
 await source.close() // when the sheet is removed, as in onUnmounted
 ```
 
-`LocalSource` has every method of `SheetSource` (the type marks `copyText` as optional, but the source always has it), plus:
+`LocalSource` has every method of `SheetSource` (the type marks `copyText` as optional, but the source always has it; `spelling` and `learnWord` only with the `spelling` option), plus:
 
 | Member | Type | Meaning |
 | --- | --- | --- |
@@ -508,6 +587,7 @@ await source.close() // when the sheet is removed, as in onUnmounted
 | `--xs-bar-bg` | `#fafafa` | The formula bar, the toolbar and the Trace Precedents panel. |
 | `--xs-message-bg`, `--xs-message-fg` | `#1f2328`, `#ffffff` | The message line. |
 | `--xs-copy-line`, `--xs-fill-frame` | `#1a73e8`, `#5f6368` | The moving border of a copy, the fill handle's outline. |
+| `--xs-trace`, `--xs-trace-error`, `--xs-trace-sheet` | `#1d4ed8`, `#d92d20`, `#1f2328` | Trace Dependents: arrows to dependents, from a cell with an error, to another sheet's icon. |
 | `--xs-shadow-pop`, `--xs-shadow-menu`, `--xs-shadow-modal` | `0 2px 6px rgb(0 0 0 / 0.2)`, `0 6px 20px rgb(0 0 0 / 0.18)`, `0 10px 30px rgb(0 0 0 / 0.25)` | Shadows of a list, a tooltip or a box under a cell; of a menu, the filter funnel's list and the message line; of a dialog or an alert. |
 | `--xs-backdrop` | `rgb(0 0 0 / 0.25)` | The dimmed page under a dialog or an alert. |
 | `--xs-z-menu`, `--xs-z-modal`, `--xs-z-alert` | `40`, `50`, `55` | Stacking layers above the page: a menu or the filter funnel's list, a dialog, an alert (above a dialog). |
@@ -515,6 +595,7 @@ await source.close() // when the sheet is removed, as in onUnmounted
 | `--xs-outline-button`, `--xs-outline-tick` | `13px`, `5px` | The outline button size and the bracket tick length. |
 | `--xs-outline-button-bg`, `--xs-outline-button-fg`, `--xs-outline-button-border` | `var(--xs-bg)`, `#3c4043`, `#9aa0a6` | The outline buttons. |
 | `--xs-explain-w`, `--xs-explain-h` | `340px`, `45%` | The Trace Precedents panel: its width, and its height on a phone. |
+| `--xs-watch-w`, `--xs-watch-h` | `560px`, `200px` | The Watch Window's size when it opens (within the sheet's box); on a phone its height is at most 45 %. |
 | `--xs-prompt-bg`, `--xs-prompt-fg`, `--xs-prompt-line` | `#ffffe1`, `#1f2328`, `#767676` | The data validation input message. |
 | `--xs-alert-stop`, `--xs-alert-warning`, `--xs-alert-information` | `#d13438`, `#ffb900`, `#0f6cbd` | The validation alert's icons. |
 | `--xs-fl-line` | `#7a7a7a` | The border of lists under a cell: Formula AutoComplete and validation lists. |

package/docs/autocomplete.md

@@ -1,15 +1,15 @@
 # Formula AutoComplete
 
-A source with `functionNames(signal)` returns the functions a formula can call, by their names as typed in the source's locale (`СУММ` in ru-RU), in the order the list displays them. While a formula is being typed in the cell editor or the formula bar and the caret is right after the beginning of a name (as `nameAt` from `xlcalc/text` finds it: letters, digits, `.` and `_` after the formula's `=`, an operator, `(`, the workbook's list separator (`,` in en-US and `;` in ru-RU), a space or a line break; not inside a string, a quoted sheet name or a table's brackets, nor after a sheet's `!` or a `$`), Excel's list opens below the editor: the functions whose names begin with what was typed, case-insensitively, eight at a time with a scroll bar, the first one highlighted. Typing further narrows it, and a character that cannot be part of a name, or a name no function begins with, closes it.
+A source with `functionNames(signal)` returns the functions a formula can call, by their names as typed in the source's locale (`СУММ` in ru-RU), in the order the list displays them. While a formula is being typed in the cell editor or the formula bar and the caret is right after the beginning of a name (as `nameAt` from `xlcalc/text` finds it: letters, digits, `.` and `_` after the formula's `=`, an operator, `(`, the workbook's list separator (`,` in en-US and `;` in ru-RU), a space or a line break; not inside a string, a quoted sheet name or a table's brackets, nor after a sheet's `!` or a `$`), Excel's list opens below the editor: the functions whose names begin with what was typed, case-insensitively, eight at a time with a scroll bar, the first one highlighted, each with Excel's fx icon; a source with `names` adds the defined names visible on the sheet among them, with a tag icon ([names.md](names.md)). Typing further narrows it, and a character that cannot be part of a name, or a name nothing begins with, closes it.
 
 - The arrow keys, Page Up and Page Down, Home and End move the highlight.
-- Tab or a double click replaces the typed name with the function and its `(` (keeping a `(` already after the name) and closes the list.
+- Tab or a double click replaces the typed name with the function and its `(` (keeping a `(` already after the name), or with the defined name alone, and closes the list.
 - Esc closes the list and keeps the editor open, and a second Esc cancels the edit as usual.
 - Enter commits the cell as typed, as Excel for Windows does; Excel for Mac also enters the highlighted item on Return.
 - Left and Right move the caret, and the list follows the name before it.
 - On a touch screen the items are 44 px, and a tap enters one.
 
-The sheet requests the names once per source, when an editor first opens, and again for a new source; a failed request is retried when the next editor opens, and without `functionNames` there is no list.
+The sheet requests the function names once per source, when an editor first opens, and again for a new source; a failed request is retried when the next editor opens, and without `functionNames` (and without defined names) there is no list.
 
 `memorySource` takes the list from its workbook's `functions`: type `=SU` into a cell.
 

package/docs/checks.md

@@ -1,6 +1,6 @@
 # Browser tests
 
-The checks build the example app ([example-app.md](example-app.md)) or the local page, drive them in Chromium through Playwright, and save screenshots under `test-results/screens/`. `npm run screens` takes screenshots of the example with every kind of formatting; along the way it checks that the formula bar's layer of colored references lines up with the input's text to the pixel (single-line and expanded, idle and with a long draft, at both widths) and drives the formula bar with the mouse on the desktop: Ctrl+click on a reference, dragging over the text, a click while the cell editor is open, and the reference underlined with a hand pointer while Cmd or Ctrl is held over it (in either order); on the phone, a long press on a reference goes to its range and a tap on it starts editing.
+The checks build the example app ([example-app.md](example-app.md)) or the local page, drive them in Chromium through Playwright, and save screenshots under `test-results/screens/`. `npm run screens` takes screenshots of the example with every kind of formatting; along the way it checks that the formula bar's layer of colored references lines up with the input's text to the pixel (single-line and expanded, idle and with a long draft, at both widths) and drives the formula bar with the mouse on the desktop: Ctrl+click on a reference, dragging over the text, a click while the cell editor is open, and the reference underlined with a hand pointer while Cmd or Ctrl is held over it (in either order); on the phone, a long press on a reference goes to its range and a tap on it starts editing. It also opens Go To with F5 after a jump (the Reference box must offer the location left, and `B2+C1` must bring up the alert) and the Symbol dialog from the example's Ω button (16 characters a row on the desktop; Ж from the Cyrillic subset and an em dash from Special Characters inserted into one edit, which has focus again after Esc), with every target at least 44 px on the phone. It also checks the zoom at 50%, 100% and 200% on the frozen sheet scrolled down and right (`*-70-zoom-*.png`): a click and a tap select the cell under them in the body and in the frozen column, and on the desktop a range dragged in Point mode, the editor over its cell and a column edge dragged by 40 pixels (40 divided by the zoom in the workbook's pixels); Ctrl+wheel's 15% steps on the desktop, a two-finger pinch on the phone (`390-71-pinch.png`), and the Watch Window (`*-72-watch.png`): Add Watch over a range, a formula in its column, a value following another tab's edit, and a double click going to the cell from another sheet.
 
 ## App scenarios: `check:spa`
 

package/docs/clipboard.md

@@ -41,7 +41,7 @@ onUnmounted(() => void source.close())
 
 ## Context menu
 
-Right-clicking a cell, or a long press on it on a touch screen, opens Excel's cell context menu for the selection (a cell outside the selection is selected first): Cut, Copy and Paste (44 px high on a touch screen), followed by the commands from [view.md](view.md) that the source supports. This menu and the context menus of row numbers, column letters and sheet tabs handle the keyboard as Excel's do: the first enabled item has focus, Down and Up cycle through the enabled items, Home and End go to the first and the last, Enter or Space chooses an item, and Esc or Tab closes the menu and returns focus. The menu's Cut, Copy and Paste use the browser's Clipboard API. Paste reads the clipboard, which the browser may ask the user to allow; where it does not allow it, Paste pastes only the sheet's own copy and otherwise tells the user to press Ctrl+V. On a read-only sheet the menu has only Copy and Trace Precedents.
+Right-clicking a cell, or a long press on it on a touch screen, opens Excel's cell context menu for the selection (a cell outside the selection is selected first): Cut, Copy and Paste (44 px high on a touch screen), followed by the commands from [view.md](view.md) that the source supports, then the note and hyperlink items of [links-notes.md](links-notes.md). This menu and the context menus of row numbers, column letters and sheet tabs handle the keyboard as Excel's do: the first enabled item has focus, Down and Up cycle through the enabled items, Home and End go to the first and the last, Enter or Space chooses an item, and Esc or Tab closes the menu and returns focus. The menu's Cut, Copy and Paste use the browser's Clipboard API. Paste reads the clipboard, which the browser may ask the user to allow; where it does not allow it, Paste pastes only the sheet's own copy and otherwise tells the user to press Ctrl+V. On a read-only sheet the menu has only Copy, Trace Precedents and, on a cell with a link, Open Hyperlink.
 
 ## Fill handle
 

package/docs/conditional-formatting.md

@@ -0,0 +1,135 @@
+# Conditional formatting
+
+The sheet draws the effect of a workbook's conditional formatting rules as its windows give it (`appearance`: a rule's fill, font and borders, data bars, icons). With a source that has `rules(sheet)` and `setRules(sheet, rules)`, on an editable sheet, it also creates, edits and clears the rules with Excel's commands from Home > Conditional Formatting. The sheet has no ribbon, and Excel's cell context menu has no conditional formatting commands, so they are `SheetViewApi` methods for a host's ribbon or menu:
+
+| Excel's command | Method |
+| --- | --- |
+| Highlight Cells Rules: Greater Than, Less Than, Between, Equal To, Text that Contains, A Date Occurring, Duplicate Values | `quickRule('greaterThan')` … `quickRule('duplicateValues')` |
+| Top/Bottom Rules: Top 10 Items, Top 10%, Bottom 10 Items, Bottom 10%, Above Average, Below Average | `quickRule('top10')` … `quickRule('belowAverage')` |
+| Data Bars, Gradient Fill and Solid Fill | `dataBars(color, 'gradient' \| 'solid')` |
+| Color Scales | `colorScale(preset)` |
+| Icon Sets | `iconSet(name)` |
+| New Rule… | `newRule()` |
+| Clear Rules from Selected Cells, Clear Rules from Entire Sheet | `clearRules('selection')`, `clearRules('sheet')` |
+| Manage Rules… | `manageRules()` |
+
+Without `rules` or `setRules`, on a read-only sheet or without a selection, the methods that open a dialog return `false` and the others `null`. `@xlcalc/vue/local` has both source methods; `memorySource` has neither.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted, ref } from 'vue'
+import { SheetView, type SheetViewApi } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+const source = localSource({
+  sheets: [{ name: 'Sales', cells: { A1: { value: 120 }, A2: { value: 80 }, A3: { value: 45 }, A4: { value: 160 } } }],
+})
+onUnmounted(() => void source.close())
+const sheet = ref<SheetViewApi | null>(null)
+</script>
+
+<template>
+  <button @click="sheet?.quickRule('greaterThan')">Greater Than…</button>
+  <button @click="sheet?.dataBars('blue')">Blue data bars</button>
+  <button @click="sheet?.colorScale('greenYellowRed')">Green - Yellow - Red</button>
+  <button @click="sheet?.iconSet('3Arrows')">3 Arrows</button>
+  <button @click="sheet?.clearRules('selection')">Clear Rules from Selected Cells</button>
+  <button @click="sheet?.manageRules()">Manage Rules…</button>
+  <SheetView ref="sheet" :source="source" :locale="source.locale" style="height: 300px" />
+</template>
+```
+
+## How a change is written
+
+`setRules` replaces the sheet's list of conditional formats, so each command reads the list with `rules` first and sends the whole new list in one call, a single undo step. A new rule goes first in the list, with the highest priority, as Excel adds one. After a success the sheet reads again the windows over the ranges of the rules before and after the change, as on a `repaint` event, since the outcome carries values only; a source need not send an event for it.
+
+A rule's formulas are in the source's locale, as `rules` returns them (`СУММ($A$1;1)` and `1,5` in ru-RU). The dialogs show them with `=`, as Excel's boxes do, and relative to the active cell: Excel writes a rule's formulas for the top-left cell of its ranges, and so does the sheet, moving the relative references of what was typed from the active cell to that cell. With A2:A3 selected from A3, `=$A3>2` is written as `$A2>2`.
+
+## Quick rules
+
+`quickRule(kind)` opens the small dialog of the command for the selection: a label as Excel's (`Format cells that are GREATER THAN:`), its inputs, and the "with" box of formats. OK writes the rule over the selection and closes the dialog; Cancel and Esc close it.
+
+| Command | Inputs | Rule |
+| --- | --- | --- |
+| Greater Than, Less Than, Equal To | a value box | `cellIs` with `greaterThan`, `lessThan`, `equal` |
+| Between | two value boxes | `cellIs` with `between` |
+| Text that Contains | a text box | `containsText` |
+| A Date Occurring | Yesterday, Today, Tomorrow, In the last 7 days, Last week, This week, Next week, Last month, This month, Next month | `timePeriod` |
+| Duplicate Values | Duplicate or Unique | `duplicateValues` or `uniqueValues` |
+| Top 10 Items, Bottom 10 Items | a rank from 1 to 1,000, 10 at first | `top10`, `bottom` for the lowest |
+| Top 10%, Bottom 10% | a percentage from 1 to 100, 10 at first | `top10` with `percent` |
+| Above Average, Below Average | none | `aboveAverage`, `below` for Below Average |
+
+A value box takes what Excel's takes: a formula after `=` (a reference such as `=$B$1`, checked as a cell's formula and refused with its message), a number, a date, a time or a percentage, stored as its number (`1/1/2020` is 43831, read as a cell reads typed text, `xlcalc/entry`), TRUE or FALSE, or text, stored in quotes (`"done"`). An empty box is refused. A text that begins with `=` is a reference or a formula: the rule gets the formula Excel writes for it (`NOT(ISERROR(SEARCH($A$1,B2)))`); any other text is searched for as typed, by the formula xlcalc gives the rule.
+
+The "with" box offers Excel's formats, the first one chosen:
+
+| Format | Font color | Fill | Border |
+| --- | --- | --- | --- |
+| Light Red Fill with Dark Red Text | `#9C0006` | `#FFC7CE` | |
+| Yellow Fill with Dark Yellow Text | `#9C5700` | `#FFEB9C` | |
+| Green Fill with Dark Green Text | `#006100` | `#C6EFCE` | |
+| Light Red Fill | | `#FFC7CE` | |
+| Red Text | `#9C0006` | | |
+| Red Border | | | thin `#9C0006` around the cell |
+
+Custom Format… opens the rule's Format Cells: the Font tab (font style, underline, strikethrough and color: the font's name and size are not part of a rule), the Border tab over a single cell (its four sides) and the Fill tab, all of them the Format Cells dialog's parts. What is left as it opened is not part of the rule; Clear empties every tab. Cancel there returns the "with" box to the preset chosen before.
+
+## Data bars, color scales, icon sets
+
+The galleries' rules are added without a dialog, over the selection.
+
+A data bar is Excel 2010's, with automatic bounds (`autoMin`, `autoMax`), red negative bars (`#FF0000`) and a black axis. Its colors are those of Excel's gallery, the same for both fills: `blue` `#638EC6`, `green` `#63C384`, `red` `#FF555A`, `orange` `#FFB628`, `lightBlue` `#008AEF`, `purple` `#D6007B`. A gradient bar has a border of its own color and a red one on negative bars; a solid bar has none.
+
+A color scale goes from the lowest number to the highest, through the 50th percentile on a three-color scale. Its name lists the colors from the highest numbers to the lowest, as Excel's gallery names them; green is `#63BE7B`, yellow `#FFEB84`, red `#F8696B`, white `#FCFCFF`, blue `#5A8AC6`, and the yellow of the two-color scales `#FFEF9C`.
+
+| Preset | Lowest | Midpoint | Highest |
+| --- | --- | --- | --- |
+| `greenYellowRed`, `redYellowGreen` | red, green | yellow | green, red |
+| `greenWhiteRed`, `redWhiteGreen` | red, green | white | green, red |
+| `blueWhiteRed`, `redWhiteBlue` | red, blue | white | blue, red |
+| `whiteRed`, `redWhite` | red, white | | white, red |
+| `greenWhite`, `whiteGreen` | white, green | | green, white |
+| `greenYellow`, `yellowGreen` | yellow, green | | green, yellow |
+
+An icon set takes any of xlcalc's twenty `IconSetName`s, with Excel's thresholds: equal shares in percent, 0, 33 and 67 for three icons, 0, 25, 50 and 75 for four, 0, 20, 40, 60 and 80 for five.
+
+## Clear Rules
+
+`clearRules('sheet')` removes every rule of the sheet. `clearRules('selection')` takes the selection out of each rule that applies to one of its cells: what is left of a range becomes the rows above and below the selection across the range, then the parts to its left and right (`A1:A10` without `A3:A5` is `A1:A2 A6:A10`), and a rule with nothing left is removed. A rule whose top-left cell moved has its formulas written for the new one, so each cell left keeps its condition. Both return `null` and send nothing when there is no rule to clear.
+
+## The Rules Manager
+
+`manageRules()` opens Excel's Conditional Formatting Rules Manager over the sheet's rules, read with `rules`:
+
+- Show formatting rules for: Current Selection (the rules that apply to a cell of the selection, as it opens) or This Worksheet;
+- a row for each rule in priority order: its description (`Cell Value > 5`, `Formula: =$A1>5`, `Top 10%`, `Graded Color Scale`), a preview of its format, Applies to as Excel writes it (`=$A$1:$A$10,$C$2`, with the locale's list separator), which can be typed over, and Stop If True, unavailable for data bars, color scales and icon sets;
+- New Rule… and Edit Rule… (also a double click) open the rule dialog below; Delete Rule; Duplicate Rule puts a copy right after the rule; Move Up and Move Down change places with the next rule in the list shown.
+
+Applies to takes ranges on this sheet, with or without `=` and `$`; until it does, it is marked and OK and Apply wait. A rule's formulas stay as written when Applies to changes. OK writes the list and closes, Apply writes it and reads it again, and Close discards what was not applied. Edits in the manager are sent only by OK or Apply, in one call each.
+
+## New Formatting Rule and Edit Formatting Rule
+
+The dialog has Excel's six rule types, each with its description and, except the first, a preview and Format… (the rule's Format Cells above):
+
+- Format all cells based on their values: a 2-Color Scale or a 3-Color Scale (each point's type, value and color; a new rule's two-color scale goes from `#FF7128` to `#FFEF9C`, its three-color scale from red through yellow to green), a Data Bar (its minimum and maximum, gradient or solid fill and its color, border or none and its color, Show Bar Only, bar direction), Icon Sets (the icon style, Reverse Icon Order, Show Icon Only, and each icon's threshold: `>=` or `>`, a value and its type);
+- Format only cells that contain: Cell Value with its operator and one or two value boxes, Specific Text (containing, not containing, beginning with, ending with), Dates Occurring, Blanks, No Blanks, Errors, No Errors;
+- Format only top or bottom ranked values: Top or Bottom, the rank, and % of the selected range;
+- Format only values that are above or below average: above, below, equal or above, equal or below, and 1, 2 or 3 standard deviations above or below;
+- Format only unique or duplicate values;
+- Use a formula to determine which cells to format.
+
+A threshold's value is a number or a formula after `=`; a relative reference there is refused with Excel's message, and a percent or a percentile must be from 0 to 100. An edited rule keeps its Stop If True and what the dialog does not show: a data bar's negative bars, axis and lengths, an icon set's custom icons while its style stays the same.
+
+## Texts and styles
+
+The dialogs' texts are the `cf…` keys of `SheetMessages` (declared in its `ConditionalMessages`), in English and in Russian with Excel's names, and `ok`, `cancel`, `close` and the Format Cells keys (`formatCells`, `fmtTab`, `fmtFontStyle` and the others) for the rule's Format Cells. The dialogs use the sheet's `--xs-*` variables; their classes begin with `xs-cf-`.
+
+## What is left out
+
+- Excel's dialogs show the rule on the cells while it is edited; the sheet shows it after OK.
+- Excel fills a quick dialog's value box from the selection's values; the sheet's boxes open empty.
+- The Rules Manager lists the rules of the selection or of the displayed sheet, not of another sheet; it has no table or PivotTable rules (Clear Rules from This Table and This PivotTable are not offered).
+- The rule's Format Cells has no Number tab: a rule's number format, set elsewhere, is kept.
+- The rule dialog does not edit a data bar's negative bar and axis settings or an icon's own icon; an edited rule keeps them.