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

package/dist/types/collaboration/index.d.ts

@@ -0,0 +1,53 @@
+import { collaborationColors } from 'dou-ui';
+import * as Y from 'yjs';
+import type { DashboardCollaboration, DashboardPeer, DashboardPresence } from '../core/collaboration';
+import type { DashboardDocument } from '../core/types';
+/** The part of an `Awareness` (`y-protocols/awareness`) the dashboard uses. */
+export interface AwarenessLike {
+    clientID: number;
+    getLocalState(): Record<string, unknown> | null;
+    setLocalStateField(field: string, value: unknown): void;
+    getStates(): Map<number, Record<string, unknown>>;
+    on(event: 'change', listener: (...args: unknown[]) => void): void;
+    off(event: 'change', listener: (...args: unknown[]) => void): void;
+}
+/** How the people editing together see each other. */
+export interface CollaborationUser {
+    name: string;
+    /** The color of this user's outlines, any CSS color. Picked from the client id when left out. */
+    color?: string;
+}
+export interface CollaborationOptions {
+    /** Where the widgets live, e.g. `ydoc.getMap('widgets')`. */
+    widgets: Y.Map<unknown>;
+    /** Shares which widget each person is at, and what they do there (`y-protocols/awareness`). */
+    awareness?: AwarenessLike;
+    /** This user, shown to the others. Needs `awareness`. */
+    user?: CollaborationUser;
+}
+export { collaborationColors };
+export type { DashboardPeer, DashboardPresence };
+/**
+ * Writes a dashboard into an empty map, e.g. when a dashboard so far saved
+ * as JSON starts being edited together. Do it once, where the shared
+ * document is created; otherwise the first person to open the dashboard
+ * brings theirs.
+ */
+export declare function fillMap(map: Y.Map<unknown>, document: DashboardDocument): void;
+/** The dashboard the map holds: its widgets by their order keys (then ids, the same for everyone). */
+export declare function readMap(map: Y.Map<unknown>): DashboardDocument;
+/**
+ * Edit a dashboard together through a Yjs document: pass the result to
+ * `DouDashboard` as `collaboration`. Each widget lives in `widgets` as its
+ * own `Y.Map`, each key on its own and each breakpoint's place on its own,
+ * so two people changing different widgets, or different settings of one,
+ * both keep their change. When two people move widgets at once, everyone
+ * lays the places out the same way, so the dashboards agree. While a widget
+ * is dragged, changes from others wait until it is let go. The dashboard's
+ * `v-model` only mirrors the shared document: a document set through
+ * `v-model` from outside is not written back. Undo only takes back this
+ * user's own changes. With `awareness`, each person sees which widget the
+ * others are at, outlined in their colors, and whether they are moving,
+ * resizing or changing its settings.
+ */
+export declare function collaboration(options: CollaborationOptions): DashboardCollaboration;

package/dist/types/collaboration/order.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Order keys: strings that sort like the widgets they belong to. A key can
+ * always be made between two others, so inserting a widget only
+ * writes that widget's key, never its neighbours'.
+ */
+/** A key after `a` and before `b`; either may be missing. Needs `a < b`. */
+export declare function keyBetween(a: string | null, b: string | null): string;
+/** `n` keys in order between `a` and `b`, kept short by splitting the range in halves. */
+export declare function keysBetween(a: string | null, b: string | null, n: number): string[];
+/**
+ * Which of `keys` (in their wanted order) can stay: the longest strictly
+ * increasing run. Missing keys (`null`) never stay. Returns the indexes.
+ */
+export declare function keptIndexes(keys: (string | null)[]): Set<number>;
+/**
+ * Order keys for items in their wanted order, given each one's current key
+ * (`null` when it has none). The longest run already in order keeps its
+ * keys; the others get fresh keys between their kept neighbours.
+ */
+export declare function orderKeys(keys: (string | null)[]): string[];

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

@@ -0,0 +1,51 @@
+import type { DashboardTransaction } from './transaction';
+import type { DashboardDocument } from './types';
+/** What a person is doing to a widget, shared with the others. */
+export type DashboardPresenceAction = 'focus' | 'move' | 'resize' | 'settings';
+/** What this person is doing, shared with the others; `null` when nothing. */
+export interface DashboardPresence {
+    widget: string;
+    action: DashboardPresenceAction;
+}
+/** Another person at a widget. */
+export interface DashboardPeer {
+    /** Their client id, unique among the people editing. */
+    client: number;
+    name: string;
+    /** Any CSS color. */
+    color: string;
+    action: DashboardPresenceAction;
+}
+/** What the dashboard hands a collaboration. */
+export interface DashboardCollaborationHost {
+    /** The document as the dashboard shows it. */
+    document: () => DashboardDocument;
+    /**
+     * Shows a document changed by others (`remote`), or by undo and redo of
+     * the collaboration's own history. While a widget is being dragged here
+     * nothing changes; once it is let go, the dashboard calls `sync`.
+     */
+    apply: (document: DashboardDocument, origin: 'remote' | 'undo' | 'redo') => void;
+}
+/**
+ * Edits a dashboard together with others, given to `DouDashboard` as
+ * `collaboration`; made by `collaboration()` from
+ * `@dou-ui/dashboard/collaboration`. The dashboard hands it its changes and
+ * uses its undo and redo in place of its own.
+ */
+export interface DashboardCollaboration {
+    /** Starts sharing; returns a function that stops. */
+    setup: (host: DashboardCollaborationHost) => () => void;
+    /** A change made here, after the dashboard showed it. */
+    transaction: (tr: DashboardTransaction) => void;
+    /** Hands the dashboard the shared document again (through `apply`), e.g. once a drag ends. */
+    sync: () => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    /** Shares what this person is doing. */
+    presence?: (presence: DashboardPresence | null) => void;
+    /** The others at a widget (reactive). */
+    peers?: (id: string) => readonly DashboardPeer[];
+}

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

@@ -0,0 +1,35 @@
+import type { DashboardWidgetType } from '../widget/define';
+import type { DashboardDocument, DashboardPlace } from './types';
+/** A dashboard with no widgets, the `v-model` when none is bound. */
+export declare const emptyDocument: () => DashboardDocument;
+export interface DocumentProblem {
+    code: 'version' | 'shape' | 'duplicate-id' | 'missing-id' | 'unknown-type' | 'bad-place';
+    /** The widget at fault; none for the document's own problems. */
+    widgetId?: string;
+    /** Where the problem is, e.g. `widgets[2]` or `widgets[2].place.lg`; `version` for the version. */
+    path: string;
+    /** The id, type or breakpoint at fault, for the editor's message. */
+    text: string;
+    /** An English description, for logs. */
+    message: string;
+}
+export interface CheckDocumentOptions {
+    /** The registered widget types; without them, types are not checked. */
+    widgets?: readonly DashboardWidgetType<any>[];
+}
+/** Whether `value` is a place on a grid: whole numbers, the size at least 1. */
+export declare function isDashboardPlace(value: unknown): value is DashboardPlace;
+/**
+ * The problems of a dashboard document, before it is saved or shown: an
+ * unknown version, widgets without an id or sharing one, types nobody
+ * registered, and places that are not whole cells.
+ */
+export declare function checkDocument(document: DashboardDocument, options?: CheckDocumentOptions): DocumentProblem[];
+/**
+ * Brings a saved document up to the current version, and fills what an
+ * older or hand-written one may lack (`version`, `place`). Widgets that are
+ * not objects and places that are not whole cells are dropped; anything
+ * else is kept as it is. Throws for data that is not an object
+ * (an array, `null`, a string) and for a version it does not know.
+ */
+export declare function migrateDocument(input: unknown): DashboardDocument;

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

@@ -0,0 +1,15 @@
+import type { DashboardTransaction } from './transaction';
+import type { DashboardDocument } from './types';
+/** Undo and redo of a dashboard: the steps of each transaction and the steps that undo them. */
+export declare class DashboardHistory {
+    private depth;
+    private done;
+    private undone;
+    constructor(depth?: number);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    record(tr: DashboardTransaction, now?: number): void;
+    undo(document: DashboardDocument): DashboardTransaction | null;
+    redo(document: DashboardDocument): DashboardTransaction | null;
+    clear(): void;
+}

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

@@ -0,0 +1,86 @@
+import type { DashboardDocument, DashboardWidget } from './types';
+/**
+ * Keys of a widget to set; `undefined` removes the key. `id` and `type`
+ * cannot be set: remove the widget and add another instead.
+ */
+export type DashboardWidgetPatch = {
+    [key: string]: unknown;
+} & {
+    id?: never;
+    type?: never;
+};
+/** One change to a dashboard. `index` is where in `widgets` an added widget goes. */
+export type DashboardStep = {
+    type: 'add';
+    widget: DashboardWidget;
+    index: number;
+} | {
+    type: 'remove';
+    id: string;
+} | {
+    type: 'update';
+    id: string;
+    patch: DashboardWidgetPatch;
+};
+export interface DashboardTransactionMeta {
+    /** `false` keeps the change out of undo, e.g. a change from another person. */
+    history?: boolean;
+    /** Changes of the same group within a second become one undo step, e.g. typing in a setting. */
+    group?: string;
+    /** Where the change came from: `layout`, `menu`, `keyboard`, `settings`, `api`… */
+    origin?: string;
+    [key: string]: unknown;
+}
+/** Deep equality of JSON values; key order doesn't matter. */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * Changes to a dashboard, made step by step and then handed to the
+ * dashboard's `dispatch` as one change (one undo step). A step that changes
+ * nothing (a widget that isn't there, a patch to the same values, an id
+ * already in use) is left out.
+ *
+ * ```ts
+ * const tr = dashboard.value.transaction()
+ * tr.update('orders', { title: '本周订单' }).remove('memo')
+ * dashboard.value.dispatch(tr)
+ * ```
+ */
+export declare class DashboardTransaction {
+    /** The document the transaction starts from. */
+    readonly before: DashboardDocument;
+    /** The document after the steps so far. */
+    doc: DashboardDocument;
+    readonly steps: DashboardStep[];
+    /** The steps that undo the ones so far, last one first. */
+    readonly inverse: DashboardStep[];
+    readonly meta: DashboardTransactionMeta;
+    constructor(
+    /** The document the transaction starts from. */
+    before: DashboardDocument);
+    /** Whether any step was made. */
+    get changed(): boolean;
+    /** Apply a step as it is. */
+    step(step: DashboardStep): this;
+    /** Put a widget into the document at `index` (the end by default). */
+    add(widget: DashboardWidget, index?: number): this;
+    /** Take a widget out. */
+    remove(id: string): this;
+    /** Set keys of a widget, e.g. `{ title }`, `{ props }` or `{ place }`; `undefined` removes a key. */
+    update(id: string, patch: DashboardWidgetPatch): this;
+    setMeta(key: string, value: unknown): this;
+}
+/**
+ * Applies steps to a document in one go, giving the transaction: its `doc`
+ * (unchanged widgets are kept as they are) and the `inverse` steps that
+ * undo it. For the server, tests, or saved steps.
+ */
+export declare function applySteps(document: DashboardDocument, steps: readonly DashboardStep[], meta?: DashboardTransactionMeta): DashboardTransaction;
+/** A deep copy of a JSON value (also of a reactive one). */
+export declare const cloneJson: <T>(value: T) => T;
+/**
+ * Adds the steps that turn the transaction's document into `next`: widgets
+ * that are gone are removed, new ones added, changed keys updated, and the
+ * fewest widgets taken out and put back to match the order. Unchanged
+ * widgets keep their objects.
+ */
+export declare function replaceWidgets(tr: DashboardTransaction, next: DashboardDocument): DashboardTransaction;

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

@@ -0,0 +1,27 @@
+/** Where a widget sits on one breakpoint's grid, in columns and rows. */
+export interface DashboardPlace {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** One widget of a dashboard. Everything in it must survive `JSON.stringify`. */
+export interface DashboardWidget<P extends object = Record<string, unknown>> {
+    id: string;
+    /** The `type` of a widget registered with `defineDashboardWidget`. */
+    type: string;
+    /** Shown in the widget's title bar; without one, the type's label is. */
+    title?: string;
+    /** The widget's own settings, read by its component. */
+    props?: P;
+    /**
+     * Where it sits, by breakpoint name. The widest breakpoint's place is the
+     * main one; a narrower breakpoint without one is laid out from it.
+     */
+    place: Partial<Record<string, DashboardPlace>>;
+}
+/** A dashboard: a JSON document the app saves and loads itself. */
+export interface DashboardDocument {
+    version: 1;
+    widgets: DashboardWidget[];
+}

package/dist/types/dashboard/dashboard.vue.d.ts

@@ -0,0 +1,33 @@
+import { DashboardTransaction } from '../core/transaction';
+import type { DashboardDocument } from '../core/types';
+import type { DashboardFilters } from '../data/types';
+import type { DashboardWidgetType } from '../widget/define';
+import type { DashboardExportErrorEvent, DashboardExpose, DashboardProps } from './types';
+type __VLS_Props = Omit<DashboardProps, 'modelValue' | 'filters'>;
+type __VLS_ModelProps = {
+    modelValue?: DashboardDocument;
+    'filters'?: DashboardFilters;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, DashboardExpose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (transaction: DashboardTransaction) => any;
+    "update:modelValue": (value: DashboardDocument) => any;
+    breakpointChange: (breakpoint: string) => any;
+    "update:filters": (value: DashboardFilters) => any;
+    exportError: (event: DashboardExportErrorEvent) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onChange?: ((transaction: DashboardTransaction) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: DashboardDocument) => any) | undefined;
+    onBreakpointChange?: ((breakpoint: string) => any) | undefined;
+    "onUpdate:filters"?: ((value: DashboardFilters) => any) | undefined;
+    onExportError?: ((event: DashboardExportErrorEvent) => any) | undefined;
+}>, {
+    columns: number | Record<string, number>;
+    breakpoints: Record<string, number>;
+    rowHeight: number;
+    gap: number | [number, number];
+    compact: import("..").GridCompact;
+    widgets: DashboardWidgetType<any>[];
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/dashboard/export.d.ts

@@ -0,0 +1,11 @@
+/** Options of a dashboard's `exportPNG`. */
+export interface DashboardImageOptions {
+    /** Pixels per CSS px. 2 by default, sharp on most screens. */
+    pixelRatio?: number;
+    /** Fill the background with the page's color. On by default; `false` leaves it clear. */
+    background?: boolean;
+    /** Room around the dashboard, in px. 16 by default. */
+    padding?: number;
+}
+/** Draws an element as it is shown into a PNG image. */
+export declare function elementToPNG(el: HTMLElement, options?: DashboardImageOptions): Promise<Blob>;

package/dist/types/dashboard/filter-bar.vue.d.ts

@@ -0,0 +1,19 @@
+import type { DashboardFilterField } from '../data/types';
+import type { DashboardFilterBarProps } from './types';
+type __VLS_Slots = {
+    /** More controls at the end of the bar, e.g. a refresh button. */
+    default?: () => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<DashboardFilterBarProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<DashboardFilterBarProps> & Readonly<{}>, {
+    clearable: boolean;
+    for: import("./types").DashboardExpose | null;
+    fields: DashboardFilterField[];
+}, {}, {}, {}, 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/dashboard/frame-context.d.ts

@@ -0,0 +1,54 @@
+import type { SheetWorkbook } from '@dou-ui/sheet/core';
+import type { Component, InjectionKey } from 'vue';
+import type { DashboardPeer } from '../core/collaboration';
+import type { DashboardWidget } from '../core/types';
+import type { DashboardLinkedFilter } from '../data/types';
+import type { DashboardMessages } from '../locale';
+import type { DashboardWidgetType } from '../widget/define';
+export type WidgetAction = 'settings' | 'fullscreen' | 'duplicate' | 'remove';
+/** An exporter as the export menu lists it. */
+export interface FrameExporter {
+    name: string;
+    label: string;
+    icon?: Component;
+}
+/**
+ * What a widget's frame reads from its dashboard. The frame looks its widget
+ * up by id in a computed of its own, so a change to one widget draws only
+ * that widget's frame again, not every frame on the grid.
+ */
+export interface FrameContext {
+    widget: (id: string) => DashboardWidget | undefined;
+    type: (widget: DashboardWidget) => DashboardWidgetType<any> | undefined;
+    title: (widget: DashboardWidget) => string;
+    editing: () => boolean;
+    messages: () => DashboardMessages;
+    /** Whether a frame mounting now is drawn in full at once. */
+    eager: (id: string) => boolean;
+    /** Whether every widget is drawn in full now, to export or print the dashboard. */
+    all: () => boolean;
+    setProps: (id: string, patch: Record<string, unknown>, options?: {
+        group?: string;
+    }) => void;
+    action: (id: string, action: WidgetAction) => void;
+    rename: (id: string, title: string) => void;
+    /** The filters a widget set, shown in its title bar. */
+    linked: (id: string) => DashboardLinkedFilter[];
+    clearFilter: (key: string) => void;
+    /** The others at a widget, when editing together. */
+    peers: (id: string) => readonly DashboardPeer[];
+    /** How a widget gives its content as a workbook; returns what undoes it. */
+    setWorkbook: (id: string, get: () => SheetWorkbook | undefined) => () => void;
+    /** The exporters a widget's menu lists: none unless it gives a workbook. */
+    exporters: (id: string) => FrameExporter[];
+    /** Writes a widget's content with an exporter, by name, and downloads the file. */
+    exportTo: (id: string, exporter: string) => void;
+    /** Tells whether a widget is drawn in full, not only its title. */
+    setDrawn: (id: string, drawn: boolean) => void;
+    /** Whether a widget's content is being exported now. */
+    exporting: (id: string) => boolean;
+    /** Why the last export from a widget's menu failed. */
+    exportError: (id: string) => string | undefined;
+    clearExportError: (id: string) => void;
+}
+export declare const frameContextKey: InjectionKey<FrameContext>;

package/dist/types/dashboard/observers.d.ts

@@ -0,0 +1,15 @@
+import type { InjectionKey } from 'vue';
+/**
+ * One `ResizeObserver` and one `IntersectionObserver` for all the widgets of
+ * a dashboard, instead of one per widget: with hundreds of widgets, creating
+ * the observers is a large part of mounting them.
+ */
+export interface DashboardObservers {
+    /** Calls `callback` with the element's new size; returns a function that stops. */
+    size: (el: Element, callback: (entry: ResizeObserverEntry) => void) => () => void;
+    /** Calls `callback` once the element comes within two screens of view; returns a function that stops. */
+    near: (el: Element, callback: () => void) => () => void;
+    dispose: () => void;
+}
+export declare const observersKey: InjectionKey<DashboardObservers>;
+export declare function createObservers(): DashboardObservers;

package/dist/types/dashboard/palette.vue.d.ts

@@ -0,0 +1,20 @@
+import type { DashboardWidgetType } from '../widget/define';
+import type { DashboardPaletteProps } from './types';
+type __VLS_Slots = {
+    /** Replaces what a button shows; `type` is the widget type. */
+    default?: (props: {
+        type: DashboardWidgetType<any>;
+    }) => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<DashboardPaletteProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<DashboardPaletteProps> & Readonly<{}>, {
+    direction: "vertical" | "horizontal";
+    for: import("./types").DashboardExpose | null;
+}, {}, {}, {}, 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/dashboard/types.d.ts

@@ -0,0 +1,190 @@
+import type { SheetExporterOptionsOf } from '@dou-ui/sheet';
+import type { SheetExporter } from '@dou-ui/sheet/core';
+import type { DashboardCollaboration } from '../core/collaboration';
+import type { DashboardTransaction } from '../core/transaction';
+import type { DashboardDocument, DashboardPlace } from '../core/types';
+import type { DashboardFilterField, DashboardFilters, DashboardLinkedFilter, DashboardSetFilterOptions, DashboardSources } from '../data/types';
+import type { GridCompact } from '../layout/types';
+import type { DashboardMessagesOverride } from '../locale';
+import type { DashboardWidgetType } from '../widget/define';
+import type { DashboardImageOptions } from './export';
+export interface DashboardProps {
+    /** The dashboard, bound with `v-model`; a new document object after every change. */
+    modelValue?: DashboardDocument;
+    /** The kinds of widget it can hold, made with `defineDashboardWidget`. */
+    widgets?: DashboardWidgetType<any>[];
+    /**
+     * Where widgets get their data, by name; a widget names its source in
+     * `props.source`. Each source loads once for each set of filters, however
+     * many widgets show it. A source replaced by another function (or other
+     * options) loads again; define the functions once, not in the template.
+     */
+    sources?: DashboardSources;
+    /** The filter values, bound with `v-model:filters`; widgets load their sources with them. */
+    filters?: DashboardFilters;
+    /** Whether widgets can be added, moved, resized, changed and removed. */
+    editable?: boolean;
+    /**
+     * How many columns the grid has: one number, or one per breakpoint.
+     * Defaults to `{ lg: 12, md: 6, sm: 1 }`.
+     */
+    columns?: number | Record<string, number>;
+    /** The narrowest width of the dashboard at which each breakpoint applies, in px. Defaults to `{ lg: 1024, md: 640, sm: 0 }`. */
+    breakpoints?: Record<string, number>;
+    /** The height of a row, in px. Defaults to 80. */
+    rowHeight?: number;
+    /** The space between widgets, in px: one number, or `[across, down]`. Defaults to 16. */
+    gap?: number | [number, number];
+    /** `'vertical'` (the default) floats widgets up into gaps; `false` leaves them where they are put. */
+    compact?: GridCompact;
+    /** The dashboard's accessible name. */
+    label?: string;
+    /** Overrides of the built-in texts. */
+    messages?: DashboardMessagesOverride;
+    /** Makes the id of a new widget. Defaults to the type and a few random letters. */
+    createId?: (type: string) => string;
+    /**
+     * Edit together with others: `collaboration()` from
+     * `@dou-ui/dashboard/collaboration`. The document then comes from the
+     * shared one, and undo only takes back this person's own changes.
+     */
+    collaboration?: DashboardCollaboration;
+    /**
+     * The file types a widget's content can be exported as, from the menu in
+     * its title bar: exporters of `@dou-ui/sheet`, such as `csvExporter` or
+     * `xlsxExporter` from `@dou-ui/sheet-xlsx`. Only widgets that give their
+     * content as a workbook (`setWorkbook`) have the menu: the built-in
+     * table, pivot table and chart do. Exporters that draw a sheet's grid,
+     * such as PNG, are left out.
+     */
+    exporters?: readonly SheetExporter[];
+}
+/** Options of a dashboard's `exportWidget`. */
+export interface DashboardExportOptions<Options = any> {
+    /** The exporter's own options, such as `{ bom: false }` for CSV. */
+    options?: Options;
+    /** Calls the export off. */
+    signal?: AbortSignal;
+}
+/** Options of a dashboard's `saveWidget`: `exportWidget`'s, and the file's name. */
+export interface DashboardSaveOptions<Options = any> extends DashboardExportOptions<Options> {
+    /** The file's name, with its extension; the widget's title by default. */
+    fileName?: string;
+}
+/** A widget's export from its menu failed. */
+export interface DashboardExportErrorEvent {
+    /** The widget's id. */
+    widget: string;
+    /** The exporter's name. */
+    exporter: string;
+    error: unknown;
+    /** What the dashboard shows over the widget's content, unless `preventDefault()` is called. */
+    message: string;
+    defaultPrevented: boolean;
+    /** Says the app tells of the failure itself. */
+    preventDefault: () => void;
+}
+export interface DashboardEmits {
+    'update:modelValue': [doc: DashboardDocument];
+    'update:filters': [filters: DashboardFilters];
+    /** After every change, with the steps that made it and those that undo it. */
+    change: [transaction: DashboardTransaction];
+    breakpointChange: [breakpoint: string];
+    /** Exporting a widget from its menu or `saveWidget` failed; the widget tells of it unless prevented. */
+    exportError: [event: DashboardExportErrorEvent];
+}
+export interface DashboardAddOptions {
+    /** Where on the widest breakpoint; defaults to the first spot it fits. */
+    at?: Pick<DashboardPlace, 'x' | 'y'>;
+    title?: string;
+    /** Merged over the type's `defaultProps`. */
+    props?: Record<string, unknown>;
+    /** Moves focus to the new widget. Defaults to `true`. */
+    focus?: boolean;
+}
+export interface DashboardExpose {
+    /** A transaction on the document as it is now: add, remove and update widgets, then `dispatch` it. */
+    transaction: () => DashboardTransaction;
+    /** Makes the changes of a transaction, as one undo step (or part of one, by `meta.group`). */
+    dispatch: (tr: DashboardTransaction) => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** Adds a widget of a registered type; returns its id, or `undefined` for an unknown type. */
+    addWidget: (type: string, options?: DashboardAddOptions) => string | undefined;
+    removeWidget: (id: string) => void;
+    /** Adds a copy of a widget next to it; returns the copy's id. */
+    duplicateWidget: (id: string) => string | undefined;
+    focusWidget: (id: string) => void;
+    /** Opens the settings drawer of a widget (while editing). */
+    openSettings: (id: string) => void;
+    /** Shows a widget full screen. */
+    openFullscreen: (id: string) => void;
+    /**
+     * Starts dragging a new widget of a type in from outside: call it in that
+     * element's `pointerdown`. See `DouGridLayout`'s `startDrop`.
+     */
+    startAdd: (event: PointerEvent, type: string) => void;
+    /** The registered widget types. */
+    readonly types: readonly DashboardWidgetType<any>[];
+    /** The breakpoint in use. */
+    readonly breakpoint: string;
+    readonly editable: boolean;
+    /** The document as it is now. */
+    readonly document: DashboardDocument;
+    /** The filter values in effect. */
+    readonly filters: DashboardFilters;
+    /** The filters set by widgets, e.g. by clicking a chart. */
+    readonly linkedFilters: readonly DashboardLinkedFilter[];
+    /** Sets a filter for every widget; an empty value (`undefined`, `null`, `''`, `[]`) clears it. */
+    setFilter: (key: string, value: unknown, options?: DashboardSetFilterOptions) => void;
+    clearFilters: () => void;
+    /** Loads the sources shown again: one by name, or all of them. */
+    refresh: (source?: string) => void;
+    /**
+     * The dashboard as a PNG image, every widget drawn (also those far from
+     * the view) once their data is in, without menus and buttons.
+     */
+    exportPNG: (options?: DashboardImageOptions) => Promise<Blob>;
+    /**
+     * A widget's content as a file: the workbook it gives, written by an
+     * exporter (its name in `exporters`, or the exporter itself). Waits for
+     * the data, and draws the widget first when it is far from the view.
+     * Fails with a `SheetFileError` (`code: 'empty'`) for a widget that
+     * gives no workbook, such as a chart without its fields.
+     */
+    exportWidget: {
+        <Name extends string>(id: string, exporter: Name, options?: DashboardExportOptions<SheetExporterOptionsOf<Name>>): Promise<Blob>;
+        <Options>(id: string, exporter: SheetExporter<Options>, options?: DashboardExportOptions<Options>): Promise<Blob>;
+    };
+    /**
+     * Exports as `exportWidget` does and saves the file in the downloads, as
+     * the widget's menu does. A failure shows over the widget and comes as
+     * `exportError`, and the promise rejects.
+     */
+    saveWidget: {
+        <Name extends string>(id: string, exporter: Name, options?: DashboardSaveOptions<SheetExporterOptionsOf<Name>>): Promise<void>;
+        <Options>(id: string, exporter: SheetExporter<Options>, options?: DashboardSaveOptions<Options>): Promise<void>;
+    };
+    /** Draws every widget, waits for their data, and opens the print dialog. */
+    print: () => Promise<void>;
+}
+export interface DashboardPaletteProps {
+    /** The dashboard it adds to (its component instance, from a template ref). */
+    for?: DashboardExpose | null;
+    /** Only these types, in this order; defaults to every registered type. */
+    types?: string[];
+    /** How the list runs. Defaults to `vertical`. */
+    direction?: 'vertical' | 'horizontal';
+}
+export interface DashboardFilterBarProps {
+    /** The dashboard whose filters it sets (its component instance, from a template ref). */
+    for?: DashboardExpose | null;
+    /** The controls, in order. Filters set by widgets show after them, each with a button to clear it. */
+    fields?: DashboardFilterField[];
+    /** Shows a button clearing every filter while any is set. Defaults to `true`. */
+    clearable?: boolean;
+    /** Replaces texts of the language pack. */
+    messages?: DashboardMessagesOverride;
+}