@twip/web 0.1.0-alpha.1 → 0.1.0-pre.1

package/dist/services/accessibility.js

@@ -0,0 +1,71 @@
+import { EditorError } from '../errors.js';
+import { Method } from '../transport/protocol.js';
+/** The accessibility tree over a session. */
+export function createAccessibility(s) {
+    return { tree: () => s.call(Method.AccessibleTree) };
+}
+/** The keys the application owns (the engine's host keys), by their Windows shortcut. */
+const hostKeys = {
+    'Ctrl+S': 'save',
+    F12: 'saveAs',
+    'Ctrl+P': 'print',
+    'Ctrl+O': 'open',
+    'Ctrl+N': 'new',
+    'Ctrl+F': 'find',
+    'Ctrl+H': 'replace',
+    'Ctrl+G': 'goTo',
+    'Ctrl+K': 'insertHyperlink',
+    F7: 'nextMisspelling',
+    'Ctrl+Shift+F': 'focusFont',
+    'Ctrl+Shift+P': 'focusFontSize',
+    F1: 'help',
+};
+/** A shortcut in one spelling: modifiers sorted, case ignored. `'Ctrl+Alt+S'`, `'⌥⌘S'`. */
+function normalize(keys) {
+    const glyphs = /^[⌘⌥⇧⌃]*/u.exec(keys)[0];
+    const parts = glyphs ? [...glyphs, keys.slice(glyphs.length)] : keys.split(/\+(?=.)/);
+    const key = parts.pop().toLowerCase();
+    return [...parts.map((p) => p.toLowerCase()).sort(), key].join('+');
+}
+/**
+ * Shortcuts over a session. Lookups are answered here, from the catalog, the host keys and the registrations, so
+ * they can be synchronous; registrations also go to the engine, which presses them.
+ */
+export function createShortcuts(s) {
+    const registered = new Map();
+    const lookup = (keys) => {
+        const key = normalize(keys);
+        const matches = (k) => normalize(k) === key;
+        for (const [id, k] of registered)
+            if (matches(k.windows) || matches(k.mac))
+                return { kind: 'shortcut', id };
+        for (const c of s.catalog)
+            if ([...c.shortcuts.windows, ...c.shortcuts.mac].some(matches))
+                return { kind: 'command', id: c.id };
+        const host = Object.entries(hostKeys).find(([k]) => matches(k));
+        return host ? { kind: 'host', command: host[1] } : null;
+    };
+    const report = (call) => call.catch((e) => s.emit('error', e instanceof EditorError ? e : new EditorError('internal', String(e), { cause: e })));
+    return {
+        register: ({ id, keys }) => {
+            const both = typeof keys === 'string' ? { windows: keys, mac: keys } : keys;
+            if (s.destroyed)
+                throw new EditorError('destroyed', 'the editor was destroyed');
+            for (const k of new Set([both.windows, both.mac])) {
+                const taken = lookup(k);
+                if (taken)
+                    throw new EditorError('unavailable', `${k} is already ${taken.kind === 'host' ? `the ${taken.command} key` : `bound to ${taken.id}`}`);
+            }
+            registered.set(id, both);
+            report(s.call(Method.ShortcutsRegister, { id, keys }));
+            return () => {
+                if (registered.get(id) !== both)
+                    return;
+                registered.delete(id);
+                if (!s.destroyed)
+                    report(s.call(Method.ShortcutsUnregister, id));
+            };
+        },
+        lookup,
+    };
+}

package/dist/services/dialogs.d.ts

@@ -0,0 +1,181 @@
+import type { Session } from '../editor.js';
+import type { LineSpacing, Mixed, RowHeight, TableWidth, Tri, UnderlineStyle } from '../state.js';
+import type { Color, Points } from '../types.js';
+import type { TabAlignment, TabLeader } from './ruler.js';
+/** The editor's dialogs as typed models: the application draws them. */
+export interface Dialogs {
+    /** Opens a dialog over the selection's current values. */
+    open<K extends DialogKind>(kind: K): Promise<DialogSessionOf<K>>;
+}
+/** A dialog. */
+export type DialogKind = 'font' | 'paragraph' | 'pageSetup' | 'insertTable' | 'tableProperties' | 'pictureSize' | 'altText' | 'hyperlink' | 'tabs' | 'accessibility';
+/** An open dialog. */
+export interface DialogSession<K extends DialogKind> {
+    /** Which dialog. */
+    readonly kind: K;
+    /** The selection's current values, `'mixed'` where they differ. */
+    readonly values: DialogValues[K];
+    /** Each field's label, kind, range and state, by field name; a field may have no entry. */
+    readonly fields: {
+        readonly [F in keyof DialogValues[K]]?: FieldInfo;
+    };
+    /** Changes some values; dependent values and field states are recomputed. Resolves with the new model. */
+    update(patch: Partial<DialogValues[K]>): Promise<DialogSessionOf<K>>;
+    /** Validates, then applies: one transaction and one undo step. */
+    apply(): Promise<void>;
+    /** Closes the dialog and changes nothing. */
+    cancel(): void;
+}
+/** The accessibility dialog's session: adds selecting an issue's object. */
+export interface AccessibilityDialogSession extends DialogSession<'accessibility'> {
+    /** Selects the issue's object. */
+    select(issueId: string): Promise<void>;
+}
+/**
+ * A dialog kind's session: {@link AccessibilityDialogSession} for `'accessibility'`, else {@link DialogSession}. Over a
+ * kind known only at run time it is a union by `kind`: code that draws any dialog from its fields can update it by
+ * field name, and narrow on `kind` for the accessibility dialog's `select`.
+ */
+export type DialogSessionOf<K extends DialogKind = DialogKind> = K extends 'accessibility' ? AccessibilityDialogSession : DialogSession<K>;
+/** A dialog field's metadata. */
+export interface FieldInfo {
+    /** The English label. */
+    label: string;
+    /** Whether it can be changed now. */
+    enabled: boolean;
+    /** The control it wants. */
+    kind: 'number' | 'length' | 'text' | 'choice' | 'toggle' | 'color' | 'list';
+    /** The minimum. */
+    min?: number;
+    /** The maximum. */
+    max?: number;
+    /** The step. */
+    step?: number;
+    /** A choice's options. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+/** Each dialog's values. */
+export interface DialogValues {
+    /** The Font dialog. */
+    font: {
+        font: Mixed<string>;
+        style: Mixed<'regular' | 'italic' | 'bold' | 'boldItalic'>;
+        size: Mixed<Points>;
+        color: Mixed<Color | 'auto'>;
+        underline: Mixed<UnderlineStyle>;
+        underlineColor: Mixed<Color | 'auto'>;
+        strikethrough: Tri;
+        doubleStrikethrough: Tri;
+        superscript: Tri;
+        subscript: Tri;
+        smallCaps: Tri;
+        allCaps: Tri;
+        hidden: Tri;
+        characterSpacing: Mixed<Points>;
+        position: Mixed<Points>;
+    };
+    /** The Paragraph dialog. */
+    paragraph: {
+        alignment: Mixed<'left' | 'center' | 'right' | 'justify'>;
+        outlineLevel: Mixed<number | 'body'>;
+        left: Mixed<Points>;
+        right: Mixed<Points>;
+        special: Mixed<'none' | 'firstLine' | 'hanging'>;
+        by: Mixed<Points>;
+        before: Mixed<Points | 'auto'>;
+        after: Mixed<Points | 'auto'>;
+        lineSpacing: Mixed<LineSpacing>;
+        keepWithNext: Tri;
+        keepLinesTogether: Tri;
+        pageBreakBefore: Tri;
+        widowControl: Tri;
+    };
+    /** The Page setup dialog. */
+    pageSetup: {
+        top: Points;
+        bottom: Points;
+        left: Points;
+        right: Points;
+        gutter: Points;
+        orientation: 'portrait' | 'landscape';
+        width: Points;
+        height: Points;
+        headerDistance: Points;
+        footerDistance: Points;
+        differentFirstPage: boolean;
+        differentOddEven: boolean;
+        applyTo: 'section' | 'wholeDocument';
+    };
+    /** The Insert table dialog. */
+    insertTable: {
+        rows: number;
+        columns: number;
+    };
+    /** The Table properties dialog. */
+    tableProperties: {
+        width: TableWidth;
+        alignment: 'left' | 'center' | 'right';
+        indent: Points;
+        rowHeight: Mixed<RowHeight>;
+        rowCanBreak: Tri;
+        headerRow: Tri;
+        columnWidth: Mixed<Points>;
+        cellAlignment: Mixed<'top' | 'center' | 'bottom'>;
+        cellMargins: {
+            top: Points;
+            bottom: Points;
+            left: Points;
+            right: Points;
+        };
+    };
+    /** The Picture size dialog. */
+    pictureSize: {
+        width: Points;
+        height: Points;
+        scaleWidth: number;
+        scaleHeight: number;
+        lockAspect: boolean;
+        reset: boolean;
+    };
+    /** The Alt text dialog. */
+    altText: {
+        text: string;
+        decorative: boolean;
+    };
+    /** The Hyperlink dialog. */
+    hyperlink: {
+        text: string;
+        address: string;
+    };
+    /** The Tabs dialog. */
+    tabs: {
+        stops: {
+            position: Points;
+            alignment: TabAlignment;
+            leader: TabLeader;
+            inherited: boolean;
+        }[];
+        defaultStop: Points;
+        /** The stop being edited. */
+        position: Points | null;
+        alignment: TabAlignment;
+        leader: TabLeader;
+        /** Stops to clear on apply. */
+        cleared: Points[];
+        /** The Set, Clear and Clear All buttons, applied by `update`. */
+        action: 'none' | 'set' | 'clear' | 'clearAll';
+    };
+    /** The Accessibility checker (read only). */
+    accessibility: {
+        issues: {
+            id: string;
+            text: string;
+            tip: boolean;
+        }[];
+    };
+}
+/** The dialogs over a session. */
+export declare function createDialogs(s: Session): Dialogs;

package/dist/services/dialogs.js

@@ -0,0 +1,18 @@
+import { Method } from '../transport/protocol.js';
+/** The dialogs over a session. */
+export function createDialogs(s) {
+    const open = (model) => {
+        const { kind, values, fields } = model;
+        const dialog = {
+            kind,
+            values,
+            fields,
+            update: async (patch) => open(await s.call(Method.DialogUpdate, { model, patch: { ...patch, kind } })),
+            apply: () => s.commit(Method.DialogApply, model),
+            cancel: () => { },
+        };
+        const select = (issueId) => s.call(Method.DialogSelectIssue, issueId);
+        return (kind === 'accessibility' ? Object.assign(dialog, { select }) : dialog);
+    };
+    return { open: async (kind) => open(await s.call(Method.DialogOpen, kind)) };
+}

package/dist/services/elements.d.ts

@@ -0,0 +1,146 @@
+import type { Op } from '../commands.js';
+import type { Session } from '../editor.js';
+import type { SelectionSummary } from '../state.js';
+import type { ClientPoint, ElementId } from '../types.js';
+/** A content control's kind. */
+export type ControlKind = 'richText' | 'plainText' | 'picture' | 'checkbox' | 'date' | 'dropDown' | 'comboBox' | 'group' | 'repeatingSection';
+/** The merge designer's elements: fields and content controls. Changing them is done with the commands. */
+export interface Elements {
+    /** The elements, in document order. */
+    list(filter?: {
+        kind?: 'field' | ControlKind;
+        match?: {
+            in: 'code' | 'tag' | 'title';
+            text: string;
+        };
+        story?: SelectionSummary['story'];
+    }): Promise<ElementInfo[]>;
+    /** One element in detail. */
+    get(id: ElementId): Promise<ElementDetail>;
+    /** The body (or an element) as blocks. */
+    structure(options?: {
+        root?: ElementId;
+        depth?: number;
+    }): Promise<Block[]>;
+    /** Selects an element; enters a header or footer when needed. */
+    select(id: ElementId, options?: {
+        reveal?: boolean;
+    }): Promise<void>;
+    /** The unfilled picture placeholders, in document order (the headers and footers after the body). */
+    placeholders(): Promise<PlaceholderInfo[]>;
+}
+/** An unfilled picture placeholder. */
+export interface PlaceholderInfo {
+    /** Its key: what `fillPlaceholder` takes. */
+    key: string;
+    /** The control it is in. */
+    element: ElementId | null;
+}
+/** {@link Elements} on a mounted editor: adds drop targets and hit testing. */
+export interface MountedElements extends Elements {
+    /** What is under a point, without moving the selection. */
+    hitTest(at: ClientPoint): Promise<{
+        element: ElementId | null;
+        editable: boolean;
+    }>;
+    /** An external drag (a field list beside the editor): shows the drop caret. */
+    dragOver(at: ClientPoint): void;
+    /** The external drag left the editor. */
+    dragLeave(): void;
+    /** Drops at the point: runs `op` there, as one transaction. */
+    drop(at: ClientPoint, op: Op): Promise<void>;
+}
+/** An element. */
+export interface ElementInfo {
+    /** The element. */
+    id: ElementId;
+    /** Its kind. */
+    kind: 'field' | ControlKind;
+    /** A field's code. */
+    code?: string;
+    /** A control's tag. */
+    tag?: string;
+    /** A control's title. */
+    title?: string;
+    /** The result or content text, up to 200 characters. */
+    display: string;
+    /** The story it is in. */
+    story: SelectionSummary['story'];
+    /** The element it is in. */
+    parent: ElementId | null;
+    /** Locked against editing. */
+    locked: boolean;
+}
+/** An element in detail. */
+export interface ElementDetail extends ElementInfo {
+    /** A control's lock. */
+    lock: 'none' | 'control' | 'content' | 'both';
+    /** A control's placeholder text. */
+    placeholder?: string;
+    /** A control's data binding. */
+    binding?: DataBinding;
+    /** A control's options. */
+    options?: ControlOptions;
+    /** The elements inside it. */
+    children: ElementId[];
+}
+/** A content control's binding to a custom XML part. */
+export interface DataBinding {
+    /** The XPath of the bound node. */
+    xpath: string;
+    /** The data part's item id. */
+    storeItemId?: string;
+    /** The XPath's namespace prefixes. */
+    prefixMappings?: string;
+}
+/** A content control's options, by kind: checkbox, date, list, or plain text. */
+export type ControlOptions = {
+    checked?: boolean;
+} | {
+    format?: string;
+    locale?: string;
+} | {
+    items: {
+        text: string;
+        value: string;
+    }[];
+} | {
+    multiline?: boolean;
+};
+/** A block of the document structure. */
+export type Block = {
+    kind: 'paragraph';
+    textLength: number;
+    elements: ElementId[];
+} | {
+    kind: 'table';
+    rows: {
+        cells: {
+            span: number;
+            verticalMerge: 'none' | 'start' | 'continue';
+            empty: boolean;
+            blocks: Block[];
+        }[];
+    }[];
+};
+/** The document's custom XML data parts. Writing and removing them is done with commands. */
+export interface DataParts {
+    /** Every data part. */
+    list(): Promise<{
+        namespace: string | null;
+        itemId: string;
+    }[]>;
+    /** The data parts with a namespace or an item id. */
+    get(options: {
+        namespace?: string;
+        itemId?: string;
+    }): Promise<{
+        namespace: string | null;
+        itemId: string;
+        xml: string;
+    }[]>;
+}
+/** The elements over a session. */
+export declare function createElements(s: Session): Elements;
+/** The data parts over a session. */
+export declare function createDataParts(s: Session): DataParts;

package/dist/services/elements.js

@@ -0,0 +1,18 @@
+import { Method } from '../transport/protocol.js';
+/** The elements over a session. */
+export function createElements(s) {
+    return {
+        list: (filter) => s.call(Method.Elements, filter ?? null),
+        get: (id) => s.call(Method.Element, id),
+        structure: (options) => s.call(Method.Structure, options ?? null),
+        select: (id, options) => s.call(Method.SelectElement, { id, reveal: options?.reveal ?? false }),
+        placeholders: () => s.call(Method.Placeholders),
+    };
+}
+/** The data parts over a session. */
+export function createDataParts(s) {
+    return {
+        list: async () => (await s.call(Method.DataParts)).map(({ namespace, itemId }) => ({ namespace, itemId })),
+        get: (options) => s.call(Method.DataParts, options),
+    };
+}

package/dist/services/find.d.ts

@@ -0,0 +1,50 @@
+import type { Session } from '../editor.js';
+import type { MatchId } from '../types.js';
+/** Find and replace, over the text of the current markup view. */
+export interface Find {
+    /** Selects and reveals the next match. */
+    next(query: FindQuery): Promise<FindResult>;
+    /** Selects and reveals the previous match. */
+    previous(query: FindQuery): Promise<FindResult>;
+    /** Every match, for a navigation pane's results list. */
+    all(query: FindQuery): Promise<FindMatch[]>;
+    /** Selects and reveals a match from {@link Find.all}. */
+    select(match: MatchId): Promise<void>;
+    /** Replaces the current match, then finds the next. */
+    replace(query: FindQuery, replacement: string): Promise<FindResult>;
+    /** Replaces every match: one transaction. */
+    replaceAll(query: FindQuery, replacement: string): Promise<{
+        count: number;
+    }>;
+}
+/** What to find. */
+export interface FindQuery {
+    /** The text. */
+    text: string;
+    /** Case-sensitive. Default false. */
+    matchCase?: boolean;
+    /** Whole words only. Default false. */
+    wholeWords?: boolean;
+}
+/** The result of a find step. */
+export interface FindResult {
+    /** A match was found and selected. */
+    found: boolean;
+    /** The search wrapped around the document's end. */
+    wrapped: boolean;
+}
+/** A match in a results list. */
+export interface FindMatch {
+    /** The match, for {@link Find.select}. */
+    id: MatchId;
+    /** Some text before it. */
+    before: string;
+    /** The matched text. */
+    text: string;
+    /** Some text after it. */
+    after: string;
+    /** Its page. */
+    page: number;
+}
+/** Find and replace over a session. */
+export declare function createFind(s: Session): Find;

package/dist/services/find.js

@@ -0,0 +1,12 @@
+import { Method } from '../transport/protocol.js';
+/** Find and replace over a session. */
+export function createFind(s) {
+    return {
+        next: (query) => s.call(Method.Find, { query, direction: 'next' }),
+        previous: (query) => s.call(Method.Find, { query, direction: 'previous' }),
+        all: (query) => s.call(Method.FindAll, query),
+        select: (match) => s.call(Method.SelectMatch, match),
+        replace: (query, replacement) => s.call(Method.Replace, { query, with: replacement }),
+        replaceAll: (query, replacement) => s.call(Method.ReplaceAll, { query, with: replacement }),
+    };
+}

package/dist/services/menus.d.ts

@@ -0,0 +1,82 @@
+import type { CommandId } from '../commands.js';
+import type { Session } from '../editor.js';
+import type { ClientPoint, CommentId, ElementId, RevisionId } from '../types.js';
+/** The context menu as a typed model: the application draws it. */
+export interface Menus {
+    /** The menu for the selection, as the context-menu key would open it. */
+    contextMenu(): Promise<ContextMenu>;
+    /** Runs an item: one transaction. */
+    invoke(action: MenuAction): Promise<void>;
+}
+/** The `contextMenu` event: the user asked for a menu. */
+export interface ContextMenuEvent {
+    /** The menu to show. */
+    menu: ContextMenu;
+    /** Where to show it. */
+    at: ClientPoint;
+    /** A right-click, or the keyboard. */
+    via: 'pointer' | 'keyboard';
+}
+/** A context menu. */
+export interface ContextMenu {
+    /** What the menu is for. */
+    target: MenuTarget;
+    /** The items, in order. */
+    items: MenuItem[];
+}
+/** What a context menu is for. */
+export type MenuTarget = {
+    kind: 'text';
+} | {
+    kind: 'misspelling';
+    word: string;
+    language: string;
+} | {
+    kind: 'link';
+    address: string;
+} | {
+    kind: 'table';
+} | {
+    kind: 'picture';
+} | {
+    kind: 'textBox';
+} | {
+    kind: 'element';
+    id: ElementId;
+} | {
+    kind: 'revision';
+    id: RevisionId;
+} | {
+    kind: 'comment';
+    id: CommentId;
+} | {
+    kind: 'headerFooter';
+};
+/** A context menu item. */
+export type MenuItem = {
+    kind: 'command';
+    command: CommandId;
+    label: string;
+    enabled: boolean;
+    checked?: boolean;
+    shortcut?: string;
+    action: MenuAction;
+} | {
+    kind: 'suggestion';
+    label: string;
+    action: MenuAction;
+} | {
+    kind: 'submenu';
+    label: string;
+    items: MenuItem[];
+} | {
+    kind: 'separator';
+};
+declare const menuAction: unique symbol;
+/** An opaque item action, only passed back to {@link Menus.invoke}. */
+export type MenuAction = {
+    readonly [menuAction]: true;
+};
+/** The menus over a session. */
+export declare function createMenus(s: Session): Menus;
+export {};

package/dist/services/menus.js

@@ -0,0 +1,8 @@
+import { Method } from '../transport/protocol.js';
+/** The menus over a session. */
+export function createMenus(s) {
+    return {
+        contextMenu: () => s.call(Method.ContextMenu),
+        invoke: (action) => s.commit(Method.Invoke, action),
+    };
+}

package/dist/services/navigation.d.ts

@@ -0,0 +1,58 @@
+import type { Session } from '../editor.js';
+import type { Color, HeadingId, Points, StyleId } from '../types.js';
+/** The document's headings, for a navigation pane. */
+export interface Navigation {
+    /** The headings, in document order. */
+    headings(): Promise<Heading[]>;
+    /** Selects and reveals a heading. */
+    select(heading: HeadingId): Promise<void>;
+}
+/** A heading. */
+export interface Heading {
+    /** The heading. */
+    id: HeadingId;
+    /** Its outline level, from 1. */
+    level: number;
+    /** Its text. */
+    text: string;
+    /** Its page. */
+    page: number;
+}
+/** The document's styles, for a style gallery. */
+export interface Styles {
+    /** The styles, optionally of one type. */
+    list(options?: {
+        type?: 'paragraph' | 'character' | 'table';
+    }): Promise<StyleInfo[]>;
+}
+/** A style. */
+export interface StyleInfo {
+    /** The style. */
+    id: StyleId;
+    /** Its display name. */
+    name: string;
+    /** Its type. */
+    type: 'paragraph' | 'character' | 'table';
+    /** Built in. */
+    builtIn: boolean;
+    /** Shown in a style gallery (`w:qFormat`). */
+    quick: boolean;
+    /** The sort priority. */
+    priority: number;
+    /** Hidden from lists. */
+    hidden: boolean;
+    /** The style it is based on. */
+    basedOn: StyleId | null;
+    /** For drawing a gallery tile. */
+    preview: {
+        font: string;
+        size: Points;
+        bold: boolean;
+        italic: boolean;
+        color: Color | 'auto';
+    };
+}
+/** The headings over a session. */
+export declare function createNavigation(s: Session): Navigation;
+/** The styles over a session. */
+export declare function createStyles(s: Session): Styles;

package/dist/services/navigation.js

@@ -0,0 +1,12 @@
+import { Method } from '../transport/protocol.js';
+/** The headings over a session. */
+export function createNavigation(s) {
+    return {
+        headings: () => s.call(Method.Headings),
+        select: (heading) => s.call(Method.SelectHeading, heading),
+    };
+}
+/** The styles over a session. */
+export function createStyles(s) {
+    return { list: (options) => s.call(Method.Styles, options?.type ?? null) };
+}