@xlcalc/vue 0.0.0-stage → 0.21.2

package/docs/quick-start.md

@@ -0,0 +1,221 @@
+# Quick start
+
+Common uses of the component, each with a single-file Vue component that works as written. Install the package first ([README](../README.md#install)); every example imports the stylesheet once, which an app does in its entry file instead. Each section links to the full documentation.
+
+## A table the page already has
+
+The host's data shown as a sheet: `memorySource` turns it into a workbook in memory, without the calculation engine. A cell displays its `text` when it has one, so the host formats numbers itself; `readOnly` turns editing off, and the frozen first row keeps the titles in view. The sheet's `state` event reports the selection and the active cell's text, as Excel's Name Box and formula bar show them.
+
+```vue
+<script setup lang="ts">
+import { shallowRef } from 'vue'
+import { SheetView, memorySource, type MemoryCell, type SheetViewState } from '@xlcalc/vue'
+import '@xlcalc/vue/style.css'
+
+const orders = [
+  { client: 'Acme', amount: 1250.5, paid: true },
+  { client: 'Globex', amount: 980, paid: false },
+  { client: 'Initech', amount: 15300.75, paid: true },
+]
+const money = new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+
+// The titles in row 1 in bold, each order in a row below them
+const cells: Record<string, MemoryCell> = { A1: { value: 'Client', style: 0 }, B1: { value: 'Amount', style: 0 }, C1: { value: 'Paid', style: 0 } }
+orders.forEach((order, i) => {
+  cells[`A${i + 2}`] = { value: order.client }
+  cells[`B${i + 2}`] = { value: order.amount, text: money.format(order.amount) }
+  cells[`C${i + 2}`] = { value: order.paid }
+})
+
+const source = memorySource({
+  styles: [{ font: { bold: true } }],
+  sheets: [{ name: 'Orders', freeze: { rows: 1, cols: 0 }, widths: { A: 16, B: 12 }, cells }],
+})
+const state = shallowRef<SheetViewState | null>(null)
+</script>
+
+<template>
+  <p>{{ state ? `${state.ref}: ${state.value ?? ''}` : '' }}</p>
+  <SheetView :source="source" read-only hide-lone-tab style="height: 300px" @state="state = $event" />
+</template>
+```
+
+Without `readOnly` the cells can be edited, and `memorySource` keeps what is typed; it does not calculate formulas, so a formula cell displays the `value` given with it. [The `memorySource` reference](api.md#memorysource) lists what a sheet can carry: styles, merged ranges, notes, hyperlinks, data validation, outline.
+
+## A model the user edits
+
+`localSource` from `@xlcalc/vue/local` calculates an xlcalc workbook in the browser, in a Web Worker: the user types into the input cells, and the formulas recalculate as in Excel, with undo, fill, Find and the context menus. The workbook is the library's `BookInput`, formulas without `=`, so it can come from the host's code, its server or an xlsx file. This entry point needs `xlcalc` installed.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted } from 'vue'
+import { SheetView } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+// A loan: the inputs in B1:B3, the payment and the interest calculated from them
+const source = localSource({
+  sheets: [
+    {
+      name: 'Loan',
+      columns: { A: { width: 12 }, B: { width: 14 } },
+      cells: {
+        A1: { value: 'Amount' }, B1: { value: 200000, numberFormat: '#,##0' },
+        A2: { value: 'Rate' }, B2: { value: 0.06, numberFormat: '0.00%' },
+        A3: { value: 'Years' }, B3: { value: 20 },
+        A5: { value: 'Payment' }, B5: { formula: '-PMT(B2/12,B3*12,B1)', numberFormat: '#,##0.00' },
+        A6: { value: 'Interest' }, B6: { formula: 'B5*B3*12-B1', numberFormat: '#,##0.00' },
+      },
+    },
+  ],
+})
+// The worker and the session end with the page's component
+onUnmounted(() => void source.close())
+</script>
+
+<template>
+  <SheetView :source="source" :locale="source.locale" hide-lone-tab style="height: 300px" />
+</template>
+```
+
+`source.book()` returns the workbook with the user's changes, for the host to store. [In-browser calculation](local.md) describes what the local source does and its options, such as `calc: 'inline'` to calculate on the page's main thread.
+
+## Excel files: open, edit, save
+
+`openXlsx` reads a file into a workbook and the values Excel stored in it, and `saveXlsx` writes the workbook back, formulas along with their values. A new source replaces the previous workbook; the previous source is closed.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted, shallowRef } from 'vue'
+import { SheetView } from '@xlcalc/vue'
+import { localSource, openXlsx, saveXlsx, type LocalSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+const source = shallowRef<LocalSource | null>(null)
+
+async function open(event: Event): Promise<void> {
+  const file = (event.target as HTMLInputElement).files?.[0]
+  if (!file) return
+  const { book, cached } = await openXlsx(file)
+  void source.value?.close()
+  source.value = localSource(book, { session: { cached } })
+}
+
+async function save(): Promise<void> {
+  if (!source.value) return
+  const { data } = await saveXlsx(source.value)
+  const link = document.createElement('a')
+  link.href = URL.createObjectURL(new Blob([data as BlobPart], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }))
+  link.download = 'workbook.xlsx'
+  link.click()
+  setTimeout(() => URL.revokeObjectURL(link.href))
+}
+
+onUnmounted(() => void source.value?.close())
+</script>
+
+<template>
+  <input type="file" accept=".xlsx" @change="open" />
+  <button :disabled="!source" @click="save">Save as</button>
+  <SheetView v-if="source" :source="source" :locale="source.locale" style="height: 420px" />
+</template>
+```
+
+`openXlsx` also returns `issues`, what the workbook could not keep from the file (pictures, charts); [Files](local.md#files) shows how to report them, and the [example app](example-app.md) is a complete Excel-like page built this way.
+
+## Excel's formatting toolbar
+
+`SheetToolbar` is Excel's formatting toolbar for the sheet's selection: Bold, colors, borders, alignment, Wrap Text, the Number Format box, Merge & Center, Undo and Redo. It reads the selection from the sheet's `state` event and formats through the sheet's template ref. It is shown for a source with `format`, such as the local one; Ctrl+1 opens Excel's Format Cells dialog on the sheet itself.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted, ref, shallowRef } from 'vue'
+import { SheetToolbar, SheetView, type SheetViewApi, type SheetViewState } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+const source = localSource({
+  sheets: [{ name: 'Sheet1', cells: { A1: { value: 'Region' }, B1: { value: 'Sales' }, A2: { value: 'North' }, B2: { value: 1200 }, A3: { value: 'South' }, B3: { value: 950 } } }],
+})
+onUnmounted(() => void source.close())
+
+const sheet = ref<SheetViewApi | null>(null)
+const state = shallowRef<SheetViewState | null>(null)
+</script>
+
+<template>
+  <SheetToolbar :source="source" :sheet="sheet" :state="state" :locale="source.locale" />
+  <SheetView ref="sheet" :source="source" :locale="source.locale" style="height: 360px" @state="state = $event" />
+</template>
+```
+
+[The formatting toolbar and Format Cells](toolbar.md) describes each button and how a host places its own Format Cells dialog.
+
+## A workbook on your server
+
+The component reads a workbook only through a `SheetSource`, so a workbook that lives on the host's server needs two methods: the list of sheets and a window of cells. Each further method turns on a feature: `edit` makes the sheet editable, `subscribe` brings in changes made elsewhere, `undo`, `find`, `format` and the rest add their commands. The `fallback` slot shows a failure to read the workbook, with a retry.
+
+```vue
+<script setup lang="ts">
+import { SheetView, type SheetInfo, type SheetPending, type SheetSource, type SheetWindow } from '@xlcalc/vue'
+import '@xlcalc/vue/style.css'
+
+const props = defineProps<{ base: string }>()
+
+async function get<T>(path: string, signal?: AbortSignal): Promise<T> {
+  const res = await fetch(props.base + path, { signal })
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
+  return (await res.json()) as T
+}
+
+// The server answers with the contract's types as JSON; without `edit` the sheet is read-only
+const source: SheetSource = {
+  sheets: (signal) => get<SheetInfo[]>('/sheets', signal),
+  window: ({ sheet, row, rows, col, cols }, signal) =>
+    get<SheetWindow | SheetPending>(`/window?${new URLSearchParams({ sheet, row: `${row}`, rows: `${rows}`, col: `${col}`, cols: `${cols}` })}`, signal),
+}
+</script>
+
+<template>
+  <SheetView :source="source" style="height: 420px">
+    <template #fallback="{ failure, retry }">
+      <p>{{ failure.text }} <button @click="retry">Try again</button></p>
+    </template>
+  </SheetView>
+</template>
+```
+
+The server can calculate with xlcalc itself: a session's `getViewport` returns what a window holds. [The source](api.md#the-source-sheetsource) lists every method with the feature it turns on, with a fuller source over GET, POST and server-sent events; a new `source` prop means a new workbook.
+
+## The Russian interface and a Russian workbook
+
+The interface texts are English by default; `ruMessages` is the complete Russian set, and a host overrides single texts by spreading it. A workbook's locale is separate: a ru-RU workbook displays and accepts formulas, numbers and dates as Russian Excel does (`=СУММ(B2:B3)`, `1 234,50`), and the sheet takes it as `locale`.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted } from 'vue'
+import { SheetView, ruMessages } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+const messages = { ...ruMessages, loading: 'Загружаю книгу…' }
+const source = localSource({
+  locale: 'ru-RU',
+  sheets: [{ name: 'Лист1', cells: { A1: { value: 'Выручка' }, B2: { value: 1234.5 }, B3: { value: 800 }, B4: { formula: 'SUM(B2:B3)', numberFormat: '#,##0.00' } } }],
+})
+onUnmounted(() => void source.close())
+</script>
+
+<template>
+  <SheetView :source="source" :locale="source.locale" :messages="messages" style="height: 300px" />
+</template>
+```
+
+[Interface texts](api.md#interface-texts-sheetmessages) lists the keys; the colors and sizes are CSS variables ([CSS variables](api.md#css-variables)).
+
+## Where to go next
+
+- [Cell editing and keyboard shortcuts](editing.md): what each key does and which source method each feature needs.
+- [Rows, columns and sheets](sheets.md), [Clipboard and fill handle](clipboard.md), [Find and Replace](find-replace.md), [Data validation](validation.md).
+- [List mode](list-mode.md): the host's own list shown on the sheet, sorted by the host, with drill-down cells and a totals row.
+- [API reference](api.md): every export, prop, event and method.

package/docs/sheets.md

@@ -0,0 +1,61 @@
+# Rows, columns and sheets
+
+## Context menus
+
+Right-clicking a row number or a column letter, or a long press of half a second on it on a touch screen, opens Excel's context menu for the selected rows or columns (a row or column outside a selection of entire rows or columns is selected first):
+
+- Insert and Delete, as many rows or columns as are selected, through `structure(op)`;
+- Row Height or Column Width in Excel's units (points, up to 409.5; characters of the default font, as Excel for Mac's dialog shows them) with Excel's limits, and Hide and Unhide (always present, as in Excel), through `layout(change)`; a size of 0 hides the rows or columns.
+
+The same on a sheet tab makes that sheet active and offers Insert (before it, with Excel's next default name: `Sheet4`, or `Лист4` with `ruMessages`), Delete (with a confirmation when the sheet has data), Rename (in place on the tab, also by double-clicking it), Move Left and Move Right among the visible tabs, Hide, and Unhide with the list of hidden sheets. If the source rejects a command, its message is displayed (`./local` returns the library's message in the workbook's locale), and after a change the sheet reads its sheets and windows again unless the source has sent `reload`. The sheet displayed afterwards is the one Excel displays: an inserted or unhidden sheet, and after a sheet is deleted or hidden, the next visible sheet, or the previous one if it was the last. Without `structure` or `layout` the corresponding items are absent; without both, the browser's own context menu remains, and a read-only sheet has none. The dialogs for sizes, the delete confirmation, the hidden sheets, and Group and Ungroup are modal: Esc or a click outside closes them, and Tab and Shift+Tab stay inside.
+
+A workbook over `localSource`, which has `structure`, `layout` and `outline`: right-click a row number, a column letter or a sheet tab to open its menu (Unhide on a tab offers the hidden sheet), and click the outline buttons to the left of the rows, where South is collapsed.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted } from 'vue'
+import { SheetView } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+const source = localSource({
+  sheets: [
+    {
+      name: 'Sales',
+      cells: {
+        A1: { value: 'Region' }, B1: { value: 'Sales' },
+        A2: { value: 'North A' }, B2: { value: 10 },
+        A3: { value: 'North B' }, B3: { value: 20 },
+        A4: { value: 'North' }, B4: { formula: 'SUBTOTAL(9,B2:B3)' },
+        A5: { value: 'South A' }, B5: { value: 5 },
+        A6: { value: 'South B' }, B6: { value: 15 },
+        A7: { value: 'South' }, B7: { formula: 'SUBTOTAL(9,B5:B6)' },
+        A8: { value: 'Total' }, B8: { formula: 'SUBTOTAL(9,B2:B7)' },
+      },
+      // Two level-2 groups inside a level-1 group; South's rows are hidden and its summary row keeps the collapsed flag
+      rows: {
+        '2:3': { outlineLevel: 2 },
+        '4': { outlineLevel: 1 },
+        '5:6': { outlineLevel: 2, hidden: true },
+        '7': { outlineLevel: 1, collapsed: true },
+      },
+      columns: { A: { width: 14 } },
+    },
+    { name: 'Archive', hidden: true, cells: { A1: { value: 'Last year' } } },
+  ],
+})
+onUnmounted(() => void source.close())
+</script>
+
+<template>
+  <SheetView :source="source" :locale="source.locale" style="height: 360px" />
+</template>
+```
+
+## Outline
+
+A sheet whose `SheetInfo.outline` has groups gets Excel's outline bars: the row bar to the left of the row numbers and the column bar above the column letters, with a slot for each level plus one. Each expanded group has a thin bracket along its rows or columns with a tick at the end away from its summary row or column, and a − button on the summary row or column (below the group, or above it without `summaryBelow`; to the right of the columns, or to the left without `summaryRight`); a collapsed group has only its + button. The level buttons 1 to N+1 are in the corner: the rows' buttons run across their bar at the height of the column letters, the columns' buttons run down their bar above the row numbers. A group's button calls `outline({ op: 'collapse' | 'expand', sheet, rows: '3:6', level })` (`columns: 'B:D'` for columns), a level button calls `outline({ op: 'showLevel', sheet, axis, level })`, and the sheet reloads afterwards unless the source has sent `reload`. Without `outline`, or on a read-only sheet, the bars are drawn but their buttons do nothing. Under a display filter the row bar is not shown, because the displayed rows are not the sheet's rows in order. On a touch screen the bars' slots are wider, and a tap on a bar presses the nearest button within 22 px, a 44 px target around a button drawn at Excel's size. The context menu of row numbers and column letters has Group and Ungroup for the selected rows or columns, as do Excel's shortcuts Shift+Alt+Right and Shift+Alt+Left (Cmd+Shift+K and Cmd+Shift+J on a Mac); with a range of cells selected, a small dialog asks whether to group rows or columns, rows first, as Excel's does. Commands that Excel does not perform are reported and not sent: a Group beyond the seventh level, an Ungroup of rows or columns that are in no group. The bars' colors and the buttons' size are set by the `--xs-outline-*` variables.
+
+## Tabs and sizes
+
+The sheet tabs are shown even for a single sheet and end with a "+" button, which inserts a sheet at the end and displays it (with `structure`); hidden sheets have no tabs. Double-clicking a column header's edge fits the column to its contents through `layout({ columns, fit: true })`, or every selected entire column when the column is one of them, as Excel does; without `layout` it restores the workbook's width. With `layout`, the bottom edge of a row number drags the row's height with a mouse (on a touch screen, Row Height is in the row menu, since a finger on a row number would snap to the edge); the row is redrawn as it moves, and the release sets the height in points through `layout({ rows, height })`, for every selected entire row when the dragged row is among them, as Excel does. Double-clicking that edge fits the row (and the selected entire rows it belongs to) to its contents through `layout({ rows, fit: true })`, which `./local` passes to xlcalc's row AutoFit. With `./local`, text typed with a line break (Alt+Enter) wraps its cell and fits its row, unless the row height was set manually, as in Excel (xlcalc 0.33). Two `SheetView` props reproduce an older grid's behavior: `hide-lone-tab` (no tabs for a workbook with one sheet) and `edge-restores-width` (double-clicking a column edge restores the workbook's width).

package/docs/toolbar.md

@@ -0,0 +1,72 @@
+# The formatting toolbar and Format Cells
+
+## `SheetToolbar`
+
+`SheetToolbar` is Excel's formatting toolbar over the same source: Undo and Redo, Bold, Italic, Underline, font and fill colors from Excel's palette, borders (All Borders, Outside Borders, Bottom Border, No Border), horizontal alignment, Wrap Text, Excel's Number Format box and, for a host that displays the dialog ([below](#formatdialog)), Format Cells. It formats the selection reported by the sheet's `state` event through `format(sheet, patches)`, as Excel formats a selection: Bold applies on top of each cell's formatting, and Outside Borders is four patches in one call and therefore a single undo step. Its buttons show as pressed according to the active cell's formatting, and clicking a pressed button removes that formatting, as in Excel. The toolbar is shown only when the source has `format`; Undo and Redo appear when the source has `undo` and `redo`, and are disabled while its `history` (the local source's) has no steps.
+
+With `sheet` and the source's `structure`, the toolbar has Excel's Merge & Center: the button merges the selection and centers its contents, and its dropdown has Merge & Center, Merge Across, Merge Cells and Unmerge Cells, each a single undo step through the sheet's `merge(command)`. The button shows as pressed on a merged cell, and clicking it then unmerges, as Excel's does; on a single cell outside a merged range it does nothing, and it is disabled on a read-only sheet and under a display filter. Before a merge that would keep only one of several values in a range (in a row, for Merge Across), the sheet shows Excel's warning "Merging cells only keeps the upper-left value and discards other values.", with OK on Enter and Cancel on Esc; it counts the cells that contain a value or a formula in its loaded windows, or in the source's windows over the range when the loaded ones do not cover it. If the source rejects the merge, its message is displayed.
+
+```vue
+<script setup lang="ts">
+import { onUnmounted, ref } from 'vue'
+import { SheetToolbar, SheetView, type SheetViewApi, type SheetViewState } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+// A source with format, undo and structure: the toolbar is shown only for a source with format
+const source = localSource({
+  sheets: [{ name: 'Sheet1', cells: { A1: { value: 'Region' }, B1: { value: 'Sales' }, A2: { value: 'North' }, B2: { value: 0.125 }, A3: { value: 'South' }, B3: { value: 0.3 } } }],
+})
+onUnmounted(() => void source.close())
+
+const state = ref<SheetViewState | null>(null)
+const sheet = ref<SheetViewApi | null>(null)
+</script>
+
+<template>
+  <SheetToolbar :source="source" :sheet="sheet" :state="state" :locale="source.locale" />
+  <SheetView :source="source" ref="sheet" :locale="source.locale" style="height: 360px" @state="state = $event" />
+</template>
+```
+
+The Number Format box works as Excel's does, as measured by xlcalc (`numberFormatCategory` and `numberFormatChoices` of `xlcalc/text`, without the engine): it shows the category of the active cell's format (General if there is none, Custom where no Excel category matches the code), and its list applies Excel's eleven items (General, Number, Currency, Accounting, Short Date, Long Date, Time, Percentage, Fraction, Scientific, Text), each with the format Excel sets (Percentage is `0.00%`), after which the box shows the new category. `locale` is the workbook's locale, as for `SheetView`: the category names and the Currency item's code follow it, with ru-RU's data loaded as a separate chunk; without it, en-US. With `sheet` (the sheet's template ref), the toolbar formats, undoes and redoes through the sheet's methods ([api.md](api.md#sheetviewapi)), and the sheet sets the selection and displays a rejection itself. Without it, the toolbar calls the source and emits `select` with where the selection goes after an undo or a redo (for the sheet's `focus`) and `error` with the source's rejection. It emits `done` after each call, so the host can return focus to the grid. Its buttons do not take focus from the grid. Below 600 px it keeps Undo, Redo, Bold, Italic and Underline in a row and moves the rest into a menu; in a narrow viewport or on a touch screen every target is 44 × 44 px.
+
+## `FormatDialog`
+
+`SheetView` has its own Excel Format Cells dialog when the source has `format`: Ctrl+1 opens it (on a Mac as well, since the browser reserves Cmd+1), as do the sheet's `formatCells()` and the toolbar's Format Cells… with `sheet`, and OK formats the selection through the sheet's `format`. The dialog is also exported as `FormatDialog`, for a host that places its own. It is Excel's Format Cells for the selection reported by the sheet's `state` event, with the tabs whose settings xlcalc's cell style supports:
+
+- Number is Excel's Number Format box: the category of the code in the input, the list's items (an item puts its format's code in the input) and the code itself, which may be any code.
+- Alignment has the horizontal and vertical alignment, the indent (with Left, Right and Distributed alignment, as in Excel) and text wrapping.
+- Font has the font name, Regular, Italic, Bold or Bold Italic, the size, the underline, strikethrough and the color.
+- Border has the line style and color, the presets None, Outline and Inside, and a button for each edge around a preview, the inside ones for a selection of more than one row or column.
+- Fill has the background color.
+
+Colors come from Excel's palette, as on the toolbar, or can be any `#RRGGBB`. The dialog opens with the active cell's formatting; for a single cell the edges show its own borders, and for a range they show as unknown, grayed out as in Excel. OK emits `apply` with patches for `SheetView.format` covering only what changed: the font, the alignment, the fill and the number format over the selection, and each border edge on its row or column, or on the cells on both sides of an inside line (a single patch over every cell when all edges use the same line), all in one call and therefore a single undo step; then it emits `close`, as Cancel, Esc and a click outside the dialog do. Tab and Shift+Tab stay inside it. An input beyond Excel's limits (a size of 1 to 409 points, an indent of 0 to 250) or an invalid color code blocks OK. On a phone the dialog takes the full screen with 44 px targets.
+
+A host with its own dialog listens to the toolbar's `formatCells` event, which the button then emits instead (a host whose listener the toolbar cannot see, such as a custom element, also sets `hostDialog`):
+
+```vue
+<script setup lang="ts">
+import { onUnmounted, ref } from 'vue'
+import { FormatDialog, SheetToolbar, SheetView, ruMessages, type SheetViewApi, type SheetViewState } from '@xlcalc/vue'
+import { localSource } from '@xlcalc/vue/local'
+import '@xlcalc/vue/style.css'
+
+// A workbook in ru-RU: its locale module loads when the source opens
+const source = localSource({ locale: 'ru-RU', sheets: [{ name: 'Лист1', cells: { A1: { value: 1234.5 }, A2: { value: 0.25 } } }] })
+onUnmounted(() => void source.close())
+
+const state = ref<SheetViewState | null>(null)
+const sheet = ref<SheetViewApi | null>(null)
+const formatOpen = ref(false)
+</script>
+
+<template>
+  <SheetToolbar :source="source" :sheet="sheet" :state="state" :messages="ruMessages" :locale="source.locale" @format-cells="formatOpen = true" />
+  <SheetView :source="source" ref="sheet" :messages="ruMessages" :locale="source.locale" style="height: 360px" @state="state = $event" />
+  <!-- The host's own dialog, placed by the host: OK formats through the sheet -->
+  <FormatDialog :open="formatOpen" :state="state" :messages="ruMessages" :locale="source.locale" @apply="sheet?.format($event)" @close="formatOpen = false" />
+</template>
+```
+
+Fill patterns, diagonal borders, rotated text, shrink to fit, merging, text direction, superscript, subscript and the Protection tab are not available, since xlcalc's cell style does not support them.

package/docs/validation.md

@@ -0,0 +1,41 @@
+# Data validation
+
+A source with `validation(sheet, cell, signal)` returns what Excel displays for a cell under a data validation rule (`SheetValidation`): the items of a list rule's dropdown as text, in order (empty when the list's formula returns none), and the input message with its title and text; null when no rule applies to the cell. An edit or a Ctrl+Enter whose value violates a rule is rejected with `alert` (`SheetValidationAlert`): the rule's style (`stop`, `warning` or `information`), its title (none for Excel's default "Microsoft Excel"), its message and the cell. After Yes on a warning or OK on an information alert, the component sends the same call again with `{ accept: true }`, and the source writes the value without checking the rule again. A paste is not checked, as Excel does not check one. `memorySource` accepts a sheet's `validations` (`MemoryValidation`: a list or whole numbers within bounds, an input message, and the alert's style, title and message), which is enough for an example or a test; `./local` uses the workbook's rules ([local.md](local.md#data-validation)).
+
+A list rule with an input message and a whole-number rule with a warning, over `memorySource`: select a cell in B2:B6 to see its dropdown arrow (Alt+Down opens the list), and type 150 into C2.
+
+```vue
+<script setup lang="ts">
+import { SheetView, memorySource } from '@xlcalc/vue'
+import '@xlcalc/vue/style.css'
+
+const source = memorySource({
+  sheets: [
+    {
+      name: 'Tasks',
+      cells: { A1: 'Task', B1: 'Status', C1: 'Done, %', A2: 'Design', B2: 'Open', C2: 40, A3: 'Build', B3: 'On hold', C3: 0 },
+      validations: [
+        { range: 'B2:B6', list: ['Open', 'On hold', 'Closed'], prompt: { title: 'Status', text: 'Pick one from the list.' } },
+        { range: 'C2:C6', whole: { min: 0, max: 100 }, alert: { severity: 'warning', title: 'Done, %', message: 'A whole number from 0 to 100.' } },
+      ],
+    },
+  ],
+})
+</script>
+
+<template>
+  <SheetView :source="source" style="height: 300px" />
+</template>
+```
+
+## Dropdown, input message and alert
+
+These parts look and behave like Excel's. `useValidation` (`src/core/validation.ts`) requests the rule once the active cell has stayed in place for 60 ms (and after the same pause once a burst of source events ends), aborts the request when the active cell moves away and discards its response, and keeps the list's state:
+
+- Alt+Down opens the list at the item the cell displays and requests the items again, since Excel recalculates them when the list opens;
+- the arrow keys, Page Up and Page Down (eight items, as many as the list displays), Home and End move the highlight;
+- Enter or a click enters the item into the cell, Esc and Alt+Up close the list, and any other key closes it and goes on to the grid.
+
+`ValidationDropdown` is the arrow at the bottom right of the active cell, and the list below the cell, as wide as the cell and its arrow, or above the cell where the viewport has no room below. `ValidationPrompt` is the input message: a pale yellow box below the cell starting from its middle, shifted left or placed over the cell where the viewport ends. `ValidationAlert` is the alert with its style's icon and buttons: Stop has Retry and Cancel; Warning has the rule's message, "Continue?" and Yes, No and Cancel; Information has OK and Cancel. It opens with Excel's default button focused (Retry, No, OK), and Esc means Cancel. Yes and OK keep the value, Retry and No reopen the cell editor with the typed text, and Cancel leaves the cell unchanged. On a touch screen the arrow and the list items are 44 px, and on a phone so are the alert's buttons. Their texts come from `SheetMessages` (`validationList`, `validationTitle`, `retry`, `validationYes`, `validationNo`, `validationContinue`, `validationStyle`, with `ok` and `cancel`), and their colors from the `--xs-prompt-*` and `--xs-alert-*` variables.
+
+`SheetView` mounts these parts: the arrow and the input message next to the active cell when the source has `validation`, and the alert when an edit or a Ctrl+Enter is rejected with `alert`. A chosen item is written through the source's `pick(sheet, cell, item, text)`, by its position in the list and its text, and the source writes it as Excel writes a picked item: the item's value, not parsed as typed text (a list cell containing the text `001` gives `001`, one displaying `50%` gives the number 0.5), keeping the cell's number format and without checking the rule. A source without `pick` (`memorySource`) receives the item's text through `edit` with `accept`. While the alert is open, the edited cell stays active and displays the typed text as pending.

package/docs/view.md

@@ -0,0 +1,50 @@
+# Freeze Panes, Reapply and Trace Precedents
+
+## Reapply
+
+When a display filter is on, the cell context menu has Excel's Reapply command, also available as Ctrl+Alt+L (on a Mac as well, since the browser reserves Cmd+Option+L) and as a button on the filter's status line at the bottom. Reapply applies the filter conditions and the sort again to the current data through `visibleRows`: rows that no longer match after an edit are hidden, and rows that now match appear. Until then such rows stay as they are, as in Excel. The scroll position is kept, and so is the active cell, unless its row was hidden; the active cell then moves to the row that takes its place.
+
+## Freeze Panes
+
+If the source has `freeze(sheet, panes)` and the sheet is editable, the context menu has Excel's Freeze Panes, Freeze Top Row and Freeze First Column; on a sheet whose workbook has frozen panes, Unfreeze Panes replaces Freeze Panes. Freeze Panes keeps the rows above and the columns to the left of the active cell in view, so with entire columns selected it freezes the columns to the left of the selection, and with entire rows selected the rows above it. With A1 active it freezes the rows and columns above and to the left of the middle of the viewport, where Excel splits the window. Each command is a single undo step in the source, and the sheet reloads afterwards unless the source has sent `reload`.
+
+The lock button on the formula bar only controls how the workbook's frozen panes are displayed: it hides or shows them in this browser and does not change the workbook. By default the sheet does not display frozen panes that take more than half of the viewport. Panes frozen from the menu are displayed regardless of the lock's earlier state and of how much of the viewport they take, and Unfreeze Panes clears the lock's saved choice. Without `freeze` these menu items are absent and the lock works as before. They are also absent under a display filter, because the rows on screen are then not the sheet's rows in order.
+
+The same commands can be run from the host's buttons through the sheet's methods ([api.md](api.md#sheetviewapi)). The example uses `memorySource`, which has `freeze` and `explain`: select C4 and click Trace precedents to see its precedents.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { SheetView, memorySource, type SheetViewApi } from '@xlcalc/vue'
+import '@xlcalc/vue/style.css'
+
+const source = memorySource({
+  sheets: [
+    {
+      name: 'Budget',
+      cells: {
+        A1: 'Item', B1: 'Price', C1: 'Sum',
+        A2: 'Desks', B2: 250, C2: { value: 1000, formula: 'B2*Rates!B1' },
+        A3: 'Chairs', B3: 90, C3: { value: 360, formula: 'B3*Rates!B1' },
+        A4: 'Total', C4: { value: 1360, formula: 'SUM(C2:C3)' },
+      },
+    },
+    { name: 'Rates', cells: { A1: 'Quantity', B1: 4 } },
+  ],
+})
+const sheet = ref<SheetViewApi | null>(null)
+</script>
+
+<template>
+  <button @click="sheet?.freezePanes('topRow')">Freeze the top row</button>
+  <button @click="sheet?.freezePanes('unfreeze')">Unfreeze</button>
+  <button @click="sheet?.explain()">Trace precedents</button>
+  <SheetView ref="sheet" :source="source" style="height: 360px" />
+</template>
+```
+
+## Trace Precedents
+
+If the source has `explain(sheet, cell)`, the context menu has Trace Precedents. Instead of drawing arrows as Excel does, the sheet opens a panel to the right of the grid (below it on a phone) with the source's tree of the active cell's precedents. While open, the panel follows the active cell: it requests the tree again 150 ms after the active cell stops moving or its value changes, and when the source reports changes. Since `explain` takes no abort signal, a response that arrives after a newer request is discarded.
+
+Each line is a node, and each two-space indent is one level deeper, as in the text of xlcalc's `explain` (`'Q 4'!A2 = 60  ← Data!A4*2`). References in it to cells, columns or rows on a single sheet are links; a reference without a sheet name refers to the sheet of its line's node. Clicking a link selects its range, like Ctrl+click on a reference in the formula bar, and the panel then shows the precedents of that cell. The close button (✕) and Esc close the panel. `./local` returns the session's `explain` in the workbook's locale, and `memorySource` builds a tree from the formulas as given, with xlcalc's English wording. The panel's width, and its height on a phone, are `--xs-explain-w` (340 px) and `--xs-explain-h` (45 %).

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@xlcalc/vue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.21.2",
+  "description": "Vue 3 sheet component for xlcalc workbooks: a windowed grid with styles, formulas and editing over a pluggable sheet source",
+  "keywords": [
+    "vue",
+    "vue3",
+    "spreadsheet",
+    "excel",
+    "xlsx",
+    "workbook",
+    "sheet",
+    "grid",
+    "formula",
+    "xlcalc"
+  ],
+  "license": "MIT",
+  "author": "Mikhail Kostryukov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drakosha/xlcalc-vue.git"
+  },
+  "homepage": "https://xlcalc.pridelab.dev/vue",
+  "bugs": {
+    "url": "https://github.com/drakosha/xlcalc-vue/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./local": {
+      "types": "./dist/local/index.d.ts",
+      "default": "./dist/local.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && vite build --config vite.local.config.ts && vue-tsc -p tsconfig.build.json && node scripts/dts-paths.ts",
+    "test": "vitest run",
+    "typecheck": "vue-tsc --noEmit",
+    "pack:release": "npm run build && node -e \"require('fs').mkdirSync('release',{recursive:true})\" && npm pack --pack-destination release",
+    "check:package": "npm run build && publint --strict && attw --pack . --profile esm-only --exclude-entrypoints ./style.css",
+    "dev:example": "vite --config vite.example.config.ts",
+    "build:example": "vite build --config vite.example.config.ts",
+    "build:demo": "vite build --config vite.example.config.ts --mode demo",
+    "screens": "node scripts/screens.ts",
+    "check:local": "node scripts/local-check.ts",
+    "check:spa": "node scripts/spa-check.ts",
+    "check:big": "node scripts/big-check.ts",
+    "check:excel-values": "node scripts/excel-values.ts",
+    "check:compare-values": "node scripts/compare-values.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "xlcalc": ">=0.46.0"
+  },
+  "peerDependenciesMeta": {
+    "xlcalc": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vue/test-utils": "^2.4.6",
+    "happy-dom": "^20.0.0",
+    "playwright": "1.63.0",
+    "publint": "^0.3.25",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.10",
+    "vue": "^3.5.39",
+    "vue-tsc": "^3.3.5",
+    "xlcalc": "^0.54.2"
+  }
+}