@dou-ui/sheet 0.0.0-stage → 0.1.0-alpha.1

package/dist/types/components/sheet-menu.vue.d.ts

@@ -0,0 +1,20 @@
+import type { SheetMenuItem } from '../types';
+type __VLS_Props = {
+    items: SheetMenuItem[];
+};
+type __VLS_ModelProps = {
+    'open'?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {
+    open: (x: number, y: number) => void | undefined;
+    close: () => void | undefined;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (key: unknown) => any;
+    "update:open": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onSelect?: ((key: unknown) => any) | undefined;
+    "onUpdate:open"?: ((value: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/components/sheet-name-box.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/components/sheet-note.vue.d.ts

@@ -0,0 +1,22 @@
+import { type VirtualElement } from 'dou-ui';
+import type { SheetNoteMessages } from '../locale';
+type __VLS_Props = {
+    /** The cell the note belongs to. */
+    anchor: VirtualElement;
+    note: string;
+    editing: boolean;
+    messages: SheetNoteMessages;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    focus: () => void | undefined;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    cancel: (leaving: boolean) => any;
+    save: (note: string, leaving: boolean) => any;
+    hover: (inside: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCancel?: ((leaving: boolean) => any) | undefined;
+    onSave?: ((note: string, leaving: boolean) => any) | undefined;
+    onHover?: ((inside: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/components/sheet-outline.vue.d.ts

@@ -0,0 +1,36 @@
+import type { SheetAxis } from '../core/axis';
+import { type SheetGroupAxis, type SheetGroupLines, type SheetGroupSummary } from '../core/group';
+type __VLS_Props = {
+    axis: 'row' | 'col';
+    groups: SheetGroupAxis;
+    /** Which side of a group its button is on. */
+    summary: SheetGroupSummary;
+    lines: SheetAxis;
+    /** Frozen lines, which don't scroll. */
+    frozen: number;
+    /** The header before the first line: the column letters for rows. */
+    head: number;
+    scroll: number;
+    /** The grid's size along the axis. */
+    view: number;
+    /** Whether to show the level buttons by the headers. */
+    levels: boolean;
+    /** The room before the outline along the axis, the other outline's corner, which a finger may reach into. */
+    before: number;
+    /** Labels of the buttons. */
+    label: (group: SheetGroupLines) => string;
+    levelLabel: (level: number) => string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    size: import("vue").ComputedRef<number>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    toggle: (group: SheetGroupLines) => any;
+    wheel: (event: WheelEvent) => any;
+    level: (level: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onToggle?: ((group: SheetGroupLines) => any) | undefined;
+    onWheel?: ((event: WheelEvent) => any) | undefined;
+    onLevel?: ((level: number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/components/sheet-tabs.vue.d.ts

@@ -0,0 +1,9 @@
+type __VLS_Props = {
+    /** Whether to show the button that adds a sheet; `true` by default. */
+    addable?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    addable: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/components/sheet-toolbar.vue.d.ts

@@ -0,0 +1,11 @@
+import type { SheetToolbarProps, SheetToolbarSlots } from '../types';
+type __VLS_Slots = SheetToolbarSlots;
+declare const __VLS_base: import("vue").DefineComponent<SheetToolbarProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<SheetToolbarProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/types/components/validation-dialog.vue.d.ts

@@ -0,0 +1,25 @@
+import type { SheetValidation } from '../core/model';
+import type { SheetMessages } from '../locale';
+type __VLS_Props = {
+    rule: SheetValidation;
+    /** Whether the rule is one the sheet has, which can be removed. */
+    editing: boolean;
+    messages: SheetMessages;
+};
+type __VLS_ModelProps = {
+    'open': boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    remove: () => any;
+    apply: (rule: SheetValidation) => any;
+    "update:open": (value: boolean) => any;
+    closed: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onRemove?: (() => any) | undefined;
+    onApply?: ((rule: SheetValidation) => any) | undefined;
+    "onUpdate:open"?: ((value: boolean) => any) | undefined;
+    onClosed?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/context.d.ts

@@ -0,0 +1,189 @@
+import type { SheetFunction } from './formula/functions';
+import { type ComputedRef, type InjectionKey, type Ref } from 'vue';
+import type { SheetBounds, SheetPoint } from './core/address';
+import type { SheetResolvedType } from './core/cell-type';
+import type { SheetData, SheetSortOrder, SheetStyle, SheetValue, SheetWorkbook } from './core/model';
+import type { SheetResult } from './formula/values';
+import type { SheetExporterInfo, SheetImporterInfo } from './core/file';
+import type { SheetSelection } from './core/selection';
+import type { SheetStylePatch } from './core/transaction';
+import type { SheetMessages } from './locale';
+import type { SheetExpose, SheetToolbarItem } from './types';
+/** A box in the grid, in px from its top left corner, as drawn now (after scrolling). */
+export interface SheetRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where a range shows: its part in view, with the edges the view cuts off. */
+export interface SheetRangeRect extends SheetRect {
+    cut: {
+        top: boolean;
+        right: boolean;
+        bottom: boolean;
+        left: boolean;
+    };
+}
+/** The surrounding sheet, as `useSheet()` and extensions see it. */
+export interface SheetContext {
+    /** The workbook, as of the last change. */
+    doc: Readonly<Ref<SheetWorkbook>>;
+    /** The index of the sheet shown. */
+    sheetIndex: ComputedRef<number>;
+    /** The sheet shown. */
+    sheet: ComputedRef<SheetData>;
+    selection: Readonly<Ref<SheetSelection>>;
+    /** The cell the keyboard is on. */
+    active: ComputedRef<SheetPoint>;
+    readonly: ComputedRef<boolean>;
+    /** Whether the grid or its cell editor has the keyboard focus. */
+    focused: Readonly<Ref<boolean>>;
+    messages: ComputedRef<SheetMessages>;
+    /**
+     * Calls `callback` for each selected cell of the sheet shown, once each,
+     * row by row; a merged cell counts once, at its top left cell.
+     */
+    forEachSelected: (callback: (point: SheetPoint) => void) => void;
+    /** The value in a cell of the sheet shown; for a formula, the formula. */
+    value: (point: SheetPoint) => SheetValue;
+    /** What a cell of the sheet shown comes to: its formula's result, or its value. */
+    result: (point: SheetPoint) => SheetResult;
+    /** A cell's type and its settings, or `undefined` for a plain cell. */
+    cellType: (point: SheetPoint) => SheetResolvedType | undefined;
+    /** Where a cell (or the merged cell it is in) is drawn now; `null` while it is out of view. */
+    cellRect: (point: SheetPoint) => SheetRect | null;
+    /**
+     * Where the part of a range of the sheet shown that is in view is drawn
+     * now, past the frozen rows and columns too; `null` while none of it is.
+     */
+    rangeRect: (bounds: SheetBounds) => SheetRangeRect | null;
+    /**
+     * Makes a change as the person using the grid, like the toolbar does.
+     * Unlike the component's `transact`, a `readonly` grid refuses it:
+     * the transaction comes back with `tr.cancelled` set (and no
+     * `transactionCancel`), unless `meta.history` is `false`. Otherwise as
+     * the component's: returns the transaction, `tr.changed` says whether
+     * it changed anything, and protected cells refuse it unless
+     * `meta.protection` or `meta.history` is `false`.
+     */
+    transact: SheetExpose['transact'];
+    /** Undoes as the person using the grid: does nothing on a `readonly` grid. */
+    undo: SheetExpose['undo'];
+    /** Redoes as the person using the grid: does nothing on a `readonly` grid. */
+    redo: SheetExpose['redo'];
+    canUndo: Readonly<Ref<boolean>>;
+    canRedo: Readonly<Ref<boolean>>;
+    select: SheetExpose['select'];
+    scrollTo: SheetExpose['scrollTo'];
+    edit: SheetExpose['edit'];
+    focus: SheetExpose['focus'];
+    showSheet: SheetExpose['showSheet'];
+    toCSV: SheetExpose['toCSV'];
+    exportSVG: SheetExpose['exportSVG'];
+    exportPNG: SheetExpose['exportPNG'];
+    print: SheetExpose['print'];
+    /** How a cell of the sheet shown looks: its style, or `{}`. A merged cell has its top left cell's. */
+    styleAt: (point: SheetPoint) => SheetStyle;
+    /** A cell's number or date format. */
+    formatAt: (point: SheetPoint) => string | undefined;
+    /**
+     * Changes how the selected cells look, as `tr.styleCells` does; `null`
+     * takes their styles off. Returns whether anything changed.
+     */
+    styleSelection: (patch: SheetStylePatch | null) => boolean;
+    /** Sets the format of the selected cells, or changes each with a function, as `tr.formatCells` does. */
+    formatSelection: (format: string | undefined | ((format: string | undefined, value: SheetValue) => string | undefined)) => boolean;
+    /** Takes the styles and formats off the selected cells. */
+    clearFormatting: () => boolean;
+    /** Whether the selection touches merged cells. */
+    merged: ComputedRef<boolean>;
+    /** Whether the selection can be merged: one range of more than one cell, not one merge already. */
+    canMerge: ComputedRef<boolean>;
+    /** Merges the selection into one cell, telling how many values that cleared. */
+    merge: () => void;
+    /** Splits the merged cells the selection touches. */
+    unmerge: () => void;
+    /**
+     * Sorts by the active cell's column: the selected rows, or the filter's
+     * rows, or the block of cells around it. Returns whether it sorted.
+     */
+    sort: (order: SheetSortOrder) => boolean;
+    /** Whether the sheet shown has a filter. */
+    filtered: ComputedRef<boolean>;
+    /** Puts a filter on the selection (or the block around the active cell), or takes it off. */
+    toggleFilter: () => void;
+    /** Says `text` to screen readers. */
+    announce: (text: string) => void;
+    /** What the sheet can do by name, built in and added by extensions: run them, or read their state. */
+    commands: SheetExpose['commands'];
+    exportFile: SheetExpose['exportFile'];
+    saveFile: SheetExpose['saveFile'];
+    importFile: SheetExpose['importFile'];
+    /** The exporters, labels in the sheet's language: the built-in ones (CSV, PNG, SVG), then the extensions'. */
+    exporters: ComputedRef<SheetExporterInfo[]>;
+    /** The importers, in the order they are asked: the extensions', then the built-in CSV one. */
+    importers: ComputedRef<SheetImporterInfo[]>;
+    /** What a file picker for the importers accepts, such as `.csv,text/csv`. */
+    importAccept: ComputedRef<string>;
+    /** The items extensions add to the toolbar, in priority order. */
+    toolbarItems: ComputedRef<SheetToolbarItem[]>;
+    /** The cell being edited, for inputs outside the grid such as the formula bar. */
+    editor: SheetEditorContext;
+}
+/** How an input outside the grid edits the cell, for `editor.attach`. */
+export interface SheetEditInputOptions {
+    /**
+     * The input shows the text and caret itself, following `editor.text`
+     * and `editor.caret`, and reports its own with `input` and `moveCaret`;
+     * the sheet doesn't write its value. For an input whose element isn't
+     * what holds the text, such as a code editor's.
+     */
+    managed?: boolean;
+    /** What the function list and argument hints go under; the input by default. */
+    anchor?: HTMLElement;
+}
+/** Editing the active cell from outside the grid, as the formula bar does. */
+export interface SheetEditorContext {
+    /** The cell being edited and how: `'enter'` began by typing, so the arrows move on (or point, in a formula). */
+    cell: ComputedRef<{
+        sheet: number;
+        row: number;
+        col: number;
+        mode: 'enter' | 'edit';
+    } | null>;
+    /** The text being edited. */
+    text: Readonly<Ref<string>>;
+    /** Where the caret is in `text`. */
+    caret: Readonly<Ref<number>>;
+    /** The text a cell edits as: its formula, or its value as typed. */
+    textAt: (point: SheetPoint) => string;
+    /** Sets the text being edited, starting an edit of the active cell when none is open. */
+    input: (text: string, caret?: number) => boolean;
+    /** Tells where the input's caret is, after keys or a click moved it. */
+    moveCaret: (caret: number) => void;
+    /** Handles a key the way the cell's editor does (completion, pointing, Enter, Tab, Escape); `true` when it did. */
+    key: (event: KeyboardEvent) => boolean;
+    /** Saves the edit, then moves the way Enter (`'down'`) or Tab (`'right'`) do. */
+    commit: (move?: 'up' | 'down' | 'left' | 'right') => void;
+    /** Drops the edit. */
+    cancel: () => void;
+    /** Lets an input edit the cell: focus moving to it keeps the edit open. Returns a function that undoes it. */
+    attach: (el: HTMLInputElement | HTMLTextAreaElement, options?: SheetEditInputOptions) => () => void;
+    /** The id of the list of functions and argument hints, for `aria-controls`. */
+    helpId: string;
+    /** The functions formulas can call, built in and added, by name. */
+    functions: ComputedRef<readonly SheetFunction[]>;
+}
+export declare const sheetContextKey: InjectionKey<SheetContext>;
+/** Where a range shows: its part in view, with the edges the view cuts off. */
+export interface SheetRangeRect extends SheetRect {
+    cut: {
+        top: boolean;
+        right: boolean;
+        bottom: boolean;
+        left: boolean;
+    };
+}
+/** The surrounding sheet; for overlays, cell types' components and the grid's slots. */
+export declare function useSheet(): SheetContext;

package/dist/types/core/address.d.ts

@@ -0,0 +1,109 @@
+/** A cell, by zero-based row and column. */
+export interface SheetPoint {
+    row: number;
+    col: number;
+}
+/**
+ * A rectangle of cells between two corners. `start` is where the range was
+ * started (the anchor), so it may be below or right of `end`.
+ */
+export interface SheetRange {
+    start: SheetPoint;
+    end: SheetPoint;
+}
+/** A range with its edges in order: `top <= bottom`, `left <= right`. */
+export interface SheetBounds {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+/** A column's letters: 0 is `A`, 25 is `Z`, 26 is `AA`. */
+export declare function columnName(col: number): string;
+/** A column's number from its letters, any case; `-1` when they aren't letters. */
+export declare function columnIndex(name: string): number;
+/** `'B3'` as `{ row: 2, col: 1 }`; `$` marks are allowed. `null` when it isn't a cell name. */
+export declare function parseCell(name: string): SheetPoint | null;
+/** A cell's name, such as `B3`. */
+export declare const formatCell: (point: SheetPoint) => string;
+/** A cell, as a name such as `'B3'` or as a point. */
+export type SheetCellTarget = string | SheetPoint;
+/**
+ * `'A1:C4'` or `'B2'` as a range; also whole columns (`'B:D'`) and whole
+ * rows (`'2:3'`), which run to `Infinity` until kept inside a sheet.
+ * `null` when it isn't one.
+ */
+export declare function parseRange(text: string): SheetRange | null;
+/**
+ * A range's name with its corners in order, such as `A1:C4`; one cell is
+ * just its name. Given the sheet's size, whole columns read `B:D` and
+ * whole rows `2:3`.
+ */
+export declare function formatRange(range: SheetRange, size?: {
+    rows: number;
+    cols: number;
+}): string;
+/**
+ * Splits a reference into the sheet it names and the rest: `'表 2'!A5`
+ * and `表2!A5` both give `表 2` / `表2` and `A5`. Without a `!`, no sheet.
+ */
+export declare function splitSheet(text: string): {
+    sheet?: string;
+    ref: string;
+};
+export declare function boundsOf(range: SheetRange): SheetBounds;
+export declare const inBounds: (b: SheetBounds, row: number, col: number) => boolean;
+/** A range of one cell. */
+export declare const pointRange: (point: SheetPoint) => SheetRange;
+/** One end of a reference: a column, a row or both, each maybe fixed with `$`. */
+export interface RefEnd {
+    col?: number;
+    row?: number;
+    colMark: boolean;
+    rowMark: boolean;
+}
+/** A sheet's name as a reference writes it: quoted unless it is a plain word. */
+export declare function quoteSheet(name: string): string;
+/**
+ * Calls `map` for every reference in a formula, with its sheet (as
+ * written, unquoted) and its two ends, and puts back the text it returns.
+ */
+export declare function eachRef(formula: string, map: (sheet: string | undefined, a: RefEnd, b: RefEnd, text: string) => string): string;
+export declare function writeRef(sheet: string | undefined, a: RefEnd, b: RefEnd, single: boolean, written?: string): string;
+/**
+ * A formula moved by `rows` and `cols`, as copying or filling it does:
+ * references without `$` move along, `$A$1` stays. A reference pushed past
+ * the first row or column becomes `#REF!`.
+ */
+export declare function shiftFormula(formula: string, rows: number, cols: number): string;
+/**
+ * Where the cells of a range are after a change to a sheet: the same
+ * bounds, new bounds, bounds on another sheet, or `null` when they are
+ * gone. Whole columns run from row 0 to `Infinity`, whole rows likewise.
+ */
+export type SheetRefMap = (bounds: SheetBounds) => SheetBounds | {
+    sheet: string;
+    bounds: SheetBounds;
+} | null;
+/**
+ * Rewrites the references in a formula on sheet `here` that point at cells
+ * on sheet `sheet`, by `map`: references to cells that moved follow them,
+ * references to cells that are gone become `#REF!`. Unlike copying, fixed
+ * references (`$A$1`) move too.
+ */
+export declare function moveReferences(formula: string, here: string, sheet: string, map: SheetRefMap): string;
+/**
+ * A formula with its references to sheet `from` naming sheet `to`
+ * instead, as renaming a sheet does. References without a sheet stay as
+ * they are, also in a formula on the renamed sheet itself.
+ */
+export declare function renameReferences(formula: string, from: string, to: string): string;
+/**
+ * A formula with references to several sheets renamed at once, by old
+ * name: `{ 预算: '预算 (2)' }`. Names that swap or chain are each renamed
+ * once. A name mapped to itself has its references written again, quoted
+ * as `quoteSheet` quotes it.
+ */
+export declare function renameReferencesAll(formula: string, names: ReadonlyMap<string, string>): string;
+/** A formula with its references to sheet `sheet`, which is gone, reading `#REF!`. */
+export declare function dropReferences(formula: string, sheet: string): string;

package/dist/types/core/axis.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where each row (or column) starts, for a list of rows that share one
+ * size except for a few. Offsets are summed once, so finding a row's place
+ * and the row at a place are a lookup and a binary search.
+ */
+export declare class SheetAxis {
+    readonly count: number;
+    readonly base: number;
+    readonly sizes: Readonly<Record<number, number>>;
+    /** `offsets[i]` is where item `i` starts; the last entry is the total. */
+    private offsets;
+    constructor(count: number, base: number, sizes?: Readonly<Record<number, number>>);
+    get total(): number;
+    /** Where item `index` starts; past the end, the total. */
+    offset(index: number): number;
+    size(index: number): number;
+    /** Whether item `index` is hidden (its size is 0). */
+    hidden(index: number): boolean;
+    /** The item at `px`, clamped to the first and last; hidden items are skipped. */
+    indexAt(px: number): number;
+    /** The first item from `index` on (going by `step`) that is not hidden; `index` when all are. */
+    visibleFrom(index: number, step: 1 | -1): number;
+}

package/dist/types/core/cell-type.d.ts

@@ -0,0 +1,157 @@
+import type { Component } from 'vue';
+import type { SheetMessages } from '../locale';
+import type { SheetInput } from './format';
+import type { SheetCell, SheetSelectOption, SheetTypeSetup, SheetValue, SheetWorkbook } from './model';
+/** What a type's `render` component gets. */
+export interface SheetCellRenderProps {
+    value: SheetValue;
+    /** The value as text, formatted as the cell would show it. */
+    text: string;
+    setup: SheetTypeSetup;
+    /** Whether the grid is read-only. */
+    readonly: boolean;
+}
+/** What a type's `panel` component gets. */
+export interface SheetCellPanelProps {
+    /** The value in the cell when editing began. */
+    value: SheetValue;
+    /** What is typed in the editor now. */
+    text: string;
+    /** Whether anything was typed since editing began. */
+    typed: boolean;
+    setup: SheetTypeSetup;
+}
+/**
+ * What a type's `panel` may expose: keys the editor passes on first, e.g.
+ * the arrow keys to move through a list. Return `true` when handled.
+ */
+export interface SheetCellPanelExpose {
+    onKey?: (event: KeyboardEvent) => boolean;
+}
+export interface SheetCellType {
+    /** The name cells refer to with `type`. */
+    name: string;
+    /**
+     * Reads typed or pasted text. Return `undefined` to read it as any cell
+     * does (numbers, dates, `TRUE`…).
+     */
+    parse?: (text: string, setup: SheetTypeSetup) => SheetInput | undefined;
+    /**
+     * The text shown for a value; by default the value with the cell's
+     * `format`. Copying and screen readers use it too.
+     */
+    format?: (value: SheetValue, setup: SheetTypeSetup) => string | undefined;
+    /**
+     * The text the editor starts with, which `parse` reads back. By default
+     * the text `format` gives, or the value as typed when there is no `format`.
+     */
+    edit?: (value: SheetValue, setup: SheetTypeSetup) => string | undefined;
+    /**
+     * Whether a value fits the type: `true`, or `false` or a short sentence
+     * saying why not, e.g. text in a date cell. A cell whose value doesn't fit
+     * gets a small mark in its corner; the sentence shows on hover and is read
+     * out. Empty cells always fit.
+     */
+    valid?: (value: SheetValue, setup: SheetTypeSetup, messages: SheetMessages) => boolean | string;
+    /**
+     * Drawn in the cell instead of its text; props are `SheetCellRenderProps`.
+     * Keep it light: it is drawn for every visible cell of the type. An
+     * element in it with `data-sheet-toggle` switches the value on a click.
+     */
+    render?: Component;
+    /**
+     * Shown under the cell while it is edited, such as a calendar. Props are
+     * `SheetCellPanelProps`; emit `pick` with a value to write it and finish.
+     */
+    panel?: Component;
+    /**
+     * Switches the value instead of opening the editor: on `Space`, `F2`, a
+     * double click or a click on a `data-sheet-toggle` element. `Space`
+     * switches every selected cell of the type: all to the same value when
+     * they hold the same, otherwise all to what an empty cell switches to.
+     */
+    toggle?: (value: SheetValue, setup: SheetTypeSetup) => SheetValue;
+    /** Where the content sits when the cell's style doesn't say. */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * The value written into files for other spreadsheet programs, such as a
+     * number for a rating; by default the value itself. Exporters read it as
+     * `source.plain`.
+     */
+    plain?: (value: SheetValue, setup: SheetTypeSetup) => SheetValue;
+    /**
+     * What the cell shows in pictures of the sheet (`png`, `svg` and printing),
+     * as SVG markup in the cell's own coordinates, from its top left corner,
+     * kept to the cell. Text put in the markup must go through `draw.escape`.
+     * Not asked for empty cells or formula errors, which show as text. By
+     * default the cell's text; a type with `render` draws its own content
+     * here, as pictures can't hold components.
+     */
+    draw?: (value: SheetValue, setup: SheetTypeSetup, draw: SheetDrawContext) => string;
+}
+/** A place in a cell's picture, in the cell's own coordinates. */
+export interface SheetDrawRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** How `draw.text` writes text; by default as the cell's look says. */
+export interface SheetDrawTextOptions {
+    align?: 'left' | 'center' | 'right';
+    valign?: 'top' | 'middle' | 'bottom';
+    /** A color as SVG takes it, e.g. from `draw.color`. */
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** In px. */
+    size?: number;
+}
+/** What a cell type's `draw` gets: the cell's size and look, and tools to draw with. */
+export interface SheetDrawContext {
+    /** The cell's size. */
+    width: number;
+    height: number;
+    /** The text the cell shows, as `format` gives it. */
+    formatted: string;
+    /** The cell's look, in colors SVG takes. */
+    look: {
+        color: string;
+        /** The fill, `null` for none. */
+        background: string | null;
+        align: 'left' | 'center' | 'right';
+        valign: 'top' | 'middle' | 'bottom';
+        bold: boolean;
+        italic: boolean;
+        fontFamily: string;
+        /** In px. */
+        fontSize: number;
+    };
+    /** Text on one line in a box (the whole cell by default), escaped, in the cell's look unless `options` say otherwise. */
+    text: (value: string, box?: SheetDrawRect, options?: SheetDrawTextOptions) => string;
+    /** An icon component, e.g. from `@dou-ui/icons`, as SVG. */
+    icon: (icon: Component, box: SheetDrawRect, color: string) => string;
+    /**
+     * A CSS color, also one with variables such as `var(--dou-color-primary)`,
+     * as a color every SVG reader understands, read in the sheet's theme.
+     */
+    color: (value: string) => string;
+    /** Escapes text for SVG markup. */
+    escape: (text: string) => string;
+}
+/** Declares a cell type; only gives it a type. */
+export declare function defineSheetCellType(type: SheetCellType): SheetCellType;
+/** A cell's type, resolved: its name, what defines it and its settings. */
+export interface SheetResolvedType {
+    /** The cell type's name, e.g. `select` for a cell whose `type` is a setup of a list. */
+    name: string;
+    definition: SheetCellType;
+    setup: SheetTypeSetup;
+}
+/** The type of a cell, or `undefined` when it has none or the type isn't known. */
+export declare function resolveCellType(cell: SheetCell | undefined, book: SheetWorkbook, types: ReadonlyMap<string, SheetCellType>): SheetResolvedType | undefined;
+/** A `select` option as a value with an optional tone. */
+export declare function optionOf(option: SheetSelectOption): {
+    value: SheetValue;
+    tone?: import("dou-ui").Tone;
+};

package/dist/types/core/clipboard.d.ts

@@ -0,0 +1,48 @@
+import { type SheetCellInput, type SheetStyle, type SheetValue } from './model';
+import { type SheetResult } from '../formula/values';
+/** A block of cells on the clipboard. */
+export interface SheetClip {
+    /** The cells, row by row. */
+    cells: SheetCellInput[][];
+    /** The named styles the cells use. */
+    styles?: Record<string, SheetStyle>;
+    /** Where the block was copied from, so formulas can move along when pasted. */
+    from?: {
+        row: number;
+        col: number;
+    };
+    /** Set when the block was cut: pasting it moves the cells. */
+    cut?: string;
+}
+/** How `formatClip` writes cells as text. */
+export interface SheetClipFormat {
+    /** The language dates are shown in. */
+    locale?: string;
+    /**
+     * What a formula comes to, by its row and column in the clip, e.g. from
+     * `SheetFormulaEngine.result`; the formula itself by default.
+     */
+    result?: (row: number, col: number) => SheetResult;
+    /**
+     * A cell's text, e.g. as its cell type shows it; `undefined` uses its
+     * format. `value` is its value, or its formula's result.
+     */
+    text?: (input: SheetCellInput, value: SheetValue) => string | undefined;
+}
+/** The clipboard's text and HTML for a block of cells, with the text as the cells show it. */
+export declare function formatClip(clip: SheetClip, options?: SheetClipFormat): {
+    text: string;
+    html: string;
+};
+/** Splits tab-separated text into rows of fields, reading quoted fields. */
+export declare function parseTSV(text: string): string[][];
+/**
+ * Reads what was pasted. Cells copied from a sheet come back as they were;
+ * a table from elsewhere, or tab-separated text, comes back as values read
+ * the way typing them would, with formats such as `0%` they imply.
+ * `null` when there is nothing to paste.
+ */
+export declare function parseClip(data: {
+    html?: string;
+    text?: string;
+}): SheetClip | null;