@aicayzer/inkkit 0.0.17 → 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,4 @@
+export { InkKitEditor } from './editor.js';
+export type { EditorEvents, EditorOptions, TextInputPreferences, CommandState, EditingMode, CaretState, Mark, Block, FormatCommand, FormatOptions, KeyInput, ImageInsertion, ShortcutName, Keymap, } from './editor.js';
+export { InkKitError } from './types.js';
+export type { DocumentFormat, EditorLabels, Heading, TableCommand, TableOptions, DocumentContext, DocumentInput, DocumentSnapshot, DocumentVersion, EditorErrorCode, ImageAdapter, WikiLinkReference, WikiLinkAdapter, FileReference, ClientPoint, FileContext, FilePresentation, FileAdapter, CapturedImage, PortableImage, ClipboardInput, ClipboardOutput, ClipboardScope, ClipboardImage, ClipboardDiagram, PrintableDocument, PrintableWarning, TextRange, ReadableTextSnapshot, TextRect, ViewportInsets, ViewportOptions, ViewportSnapshot, } from './types.js';

package/dist/core.js

@@ -0,0 +1,2 @@
+import { r as InkKitError, t as InkKitEditor } from "./chunks/core-vtCr4MBS.js";
+export { InkKitEditor, InkKitError };

package/dist/editor.d.ts

@@ -1,8 +1,7 @@
-import { type EditorLabels } from './labels.js';
-import { type TableCommand, type TableOptions } from './tables.js';
-import { type DocumentInput, type DocumentSnapshot, type ImageAdapter, type FileAdapter, type WikiLinkAdapter, type ClipboardInput, type ClipboardOutput, type PrintableDocument, type TextRange, type ReadableTextSnapshot, type TextRect, type ViewportOptions, type ViewportSnapshot } from './types.js';
-import { type Heading } from './outline.js';
+import { InkKitError, type ClientPoint, type DocumentInput, type DocumentSnapshot, type ImageAdapter, type FileAdapter, type WikiLinkAdapter, type ClipboardInput, type ClipboardOutput, type ClipboardScope, type DocumentVersion, type PrintableDocument, type TextRange, type ReadableTextSnapshot, type TextRect, type ViewportOptions, type ViewportSnapshot, type EditorLabels, type Heading, type TableCommand, type TableOptions } from './types.js';
+/** An inline format that `CaretState` can report. */
 export type Mark = 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'link';
+/** The kind of block that holds the start of the selection. Any other block reports `paragraph`. */
 export type Block = {
     type: 'paragraph';
 } | {
@@ -17,44 +16,84 @@ export type Block = {
 } | {
     type: 'taskList';
 };
+/** `source` shows the Markdown or literal text in a textarea. A TXT document is always `source`. */
 export type EditingMode = 'source' | 'formatted';
+/** The formatting at the selection, for host toolbars. */
 export interface CaretState {
+    /** At a caret, the marks the next typed text takes. For a range, every mark found in it. */
     marks: Mark[];
     block: Block;
     /** One quote holds the whole selection; the block is what sits inside it. */
     quoted: boolean;
 }
-export type FormatCommand = 'heading' | 'paragraph' | 'bold' | 'italic' | 'strikethrough' | 'highlight' | 'code' | 'codeBlock' | 'quote' | 'bulletList' | 'orderedList' | 'taskList' | 'link';
-/** Host bindings by documented formatting, history or table shortcut name. */
-export type Keymap = Record<string, string[]>;
+declare const formatCommands: readonly ['heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', 'paragraph', 'bold', 'italic', 'strikethrough', 'highlight', 'code', 'codeBlock', 'quote', 'bulletList', 'orderedList', 'taskList', 'link'];
+/** A command for `format`. */
+export type FormatCommand = (typeof formatCommands)[number];
+/** `destination` goes only with `link`, and `language` only with `codeBlock`. */
+export interface FormatOptions {
+    destination?: string;
+    language?: string;
+}
+/** A key press for `keyDown`. An omitted modifier is not held. */
+export interface KeyInput {
+    key: string;
+    code?: string;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+}
+/** An image to insert by the reference its adapter already stored it under. */
+export interface ImageInsertion {
+    reference: string;
+    alt: string;
+    title?: string;
+}
+/** A name in `Keymap`: every format command except `link`, history, and every table command. */
+export type ShortcutName = Exclude<FormatCommand, 'link'> | 'undo' | 'redo' | `table${Capitalize<TableCommand>}`;
+/** Host bindings in ProseMirror key notation, by shortcut name. */
+export type Keymap = Partial<Record<ShortcutName, readonly string[]>>;
+/** Every `ShortcutName`. */
+export declare const shortcutNames: readonly ShortcutName[];
+/** Hints for the browser's input features. A field left out leaves the behavior to the browser. */
 export interface TextInputPreferences {
     spellcheck?: boolean;
     autocorrect?: boolean;
     autocapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
 }
+/** Mount options. Adapters, `labels` and `rendering` are fixed at mount; the rest can change. */
 export interface EditorOptions {
+    /** Shows, imports and exports images. Without it and `files`, image Markdown stays literal. */
     images?: ImageAdapter;
+    /** Resolves path images and `![[name]]` embeds into images, audio, video, PDFs and file cards. */
     files?: FileAdapter;
+    /** Resolves and opens `[[wiki links]]`. Without it they stay literal. */
     wikiLinks?: WikiLinkAdapter;
+    /** Defaults to true. See `setEditable`. */
     editable?: boolean;
     textInput?: TextInputPreferences;
+    /** Replaces built-in text and accessible names. */
     labels?: Partial<EditorLabels>;
+    /** See `setKeymap`. */
     keymap?: Keymap;
     rendering?: {
+        /** Defaults to true. */
         codeHighlighting?: boolean;
+        /** Defaults to true. */
         diagramPreview?: boolean;
     };
 }
-export interface CommandState {
-    documentId: string;
-    generation: number;
-    revision: number;
+/** What the editor can do now. Availability is the state at the time of the call, not a promise. */
+export interface CommandState extends DocumentVersion {
     format: 'md' | 'txt';
     mode: EditingMode;
     editable: boolean;
+    /** Text composition (IME) is in progress. */
     composing: boolean;
+    /** An image import is running. */
     pending: boolean;
     caret: CaretState;
+    /** Present when the selection is in a table. `rows` includes the header row. */
     table?: {
         row: number;
         column: number;
@@ -76,34 +115,48 @@ export interface CommandState {
         table: Record<TableCommand, boolean>;
     };
 }
+/** The host's handlers, passed to `mount`. Only `changed` is required. */
 export interface EditorEvents {
-    changed(markdown: string, generation: number): void;
-    stateChanged(state: CaretState): void;
+    /** The document's text changed. Not sent for a load, a reload or a refused edit. */
+    changed(snapshot: DocumentSnapshot): void;
+    /** Availability or the caret changed, and once after each load. */
     commandStateChanged?(state: CommandState): void;
-    openLink(href: string): void;
-    copy(text: string): void;
-    error?(error: Error): void;
+    /** A primary click with Mod on a link. Without it, links don't open. */
+    openLink?(href: string): void;
+    /** The Copy button on a code block was clicked. Without this handler, no button is drawn. */
+    copy?(text: string): void;
+    /** A failure that no call is waiting for, such as one in an edit the person made. */
+    error?(error: InkKitError): void;
+    /** The person copied or cut a selection that holds an image or a diagram. Resolve after the
+     *  native clipboard write succeeds; a cut removes the selection only then. */
     clipboard?(content: ClipboardOutput): void | Promise<void>;
 }
+/** Every member of `EditorEvents`. The type check below fails to compile when one is left out. */
+export declare const editorEvents: readonly ["changed", "commandStateChanged", "openLink", "copy", "error", "clipboard"];
+/**
+ * The editor. Create it with `InkKitEditor.mount`, load a document, and read it back with
+ * `snapshot`. The reference is https://github.com/aicayzer/inkkit/blob/main/docs/api.md.
+ */
 export declare class InkKitEditor {
-    private readonly events;
     private readonly options;
     private editor;
     private lastMarkdown;
-    private documentId;
     private formatType;
-    private revision;
-    private documentEpoch;
-    private operationSequence;
+    private readonly session;
     private exportControllers;
     private plainComposing;
     private plainSearch;
     private literalMatch?;
     private beforePlainInput?;
+    private pendingSource?;
+    private typedSteps;
+    private undoneSteps;
+    private formattedUndone;
+    private lastSourceInput;
+    private syncingSource;
     private mode;
     private sourcePreservations;
     private sourceTexts;
-    private outlineEpoch;
     private ready;
     private destroyed;
     private preservation?;
@@ -112,67 +165,180 @@ export declare class InkKitEditor {
     private root;
     private ownsRootClass;
     private clickHandler?;
+    private auxClickHandler?;
+    private untrackLinkModifier?;
     private footnoteKeyHandler?;
     private copyHandler?;
     private originalSource;
-    private generation;
     private reportingSuppressed;
     private loading;
     private readonly textIdentity;
+    private call?;
     private textScope?;
     private viewportContainer?;
     private viewportInsets;
     private writable;
     private inputPreferences;
-    private policyEpoch;
     private literalKeys;
     private configuredKeys;
     private readOnlyKeys;
     private changePlugin;
     private keys;
+    private readonly events;
+    /** How many of each state event the host has been sent. */
+    private readonly sentEvents;
     private constructor();
     private context;
+    /** The generation of the loaded document, for the composition check of native input. */
+    private get generation();
+    /** What `changed` reports for the document's new text. */
+    private changeSnapshot;
     private cancelExports;
+    /** Runs asynchronous output work for the document `captured` describes, and throws
+     *  `stale-document` when the document, its revision or the editing mode changed meanwhile. */
     private exportContent;
+    /** Throws unless the document `captured` describes is still current, alive, not composing and
+     *  has no import pending. */
+    private assertCaptured;
+    /** Throws unless a deferred cut can still remove what it copied: the document, its revision,
+     *  the editing mode and editability are as they were when the cut started. */
+    private assertCut;
+    /** What file and wiki-link views capture: the adapter context, and whether the same load is
+     *  still current. Edits do not make their work stale. */
+    private adapterCapture;
     private mediaPolicy;
     private assertAlive;
+    private assertReady;
+    /** Checks, in order, that the editor is alive, that `expectedGeneration` is a generation, and
+     *  that the document is loaded, current, not composing and has no import pending. */
     private assertCurrent;
     private assertMutation;
+    /**
+     * Runs one facade call, so that its failure reaches the caller once and coded, and a failed call
+     * changes nothing and sends nothing. An edit that the preservation check refuses during the call
+     * is thrown, not sent to `events.error`. When the call fails with a refusal or another coded
+     * failure, every step it took is undone: the document, selection and history return to their
+     * state before the call, and the state events it raised are dropped. An `internal` failure keeps
+     * what happened and sends its events, since the editor's state can no longer be trusted to match.
+     * Anything else thrown arrives as an `InkKitError`. A call made inside another runs as part of
+     * it. Promises reject instead of throwing.
+     */
+    private facadeCall;
+    /** Sends a finished call's state events in order. Each event reports the whole of its state, so
+     *  once a call made from one of the host's handlers has sent a newer event of a kind, the call's
+     *  remaining events of that kind are out of date and are dropped. */
+    private deliver;
+    /** What a failed call puts back. */
+    private restorePoint;
+    private finish;
+    /** Reports a refused edit to the facade call that made it, or else to `events.error`. */
+    private refuse;
+    /** Reports a failure no call is waiting for. */
+    private report;
+    /** Runs a facade method for something the person did, such as a shortcut. Its failure goes to
+     *  `events.error`, unless a host call such as `keyDown` is waiting for it. */
+    private forPerson;
     private get composing();
+    /** Whether the person can edit. A read-only editor still permits selection, copying and find. */
     get editable(): boolean;
+    /** Turns editing on or off for both surfaces. Throws `composition` during text composition. */
     setEditable(editable: boolean): void;
+    /** Replaces the input hints. A field left out leaves the browser's behavior. Throws `composition`
+     *  during text composition. */
     setTextInputPreferences(preferences: TextInputPreferences): void;
     private applyInputPolicy;
     private publishCommandState;
+    /** What the editor can do now, for enabling host controls. Unlike `snapshot`, it works during
+     *  composition. */
     commandState(expectedGeneration?: number): CommandState;
+    /** An image adapter shows and exports an inserted reference, and so does a file adapter. */
+    private get canInsertImages();
     private canQuote;
     private policyPlugin;
     private get literalSurface();
+    /** `formatted` or `source`. A TXT document is always `source`. */
     get editingMode(): EditingMode;
     private currentText;
+    /** Switches between formatted and source editing. Returns false when the mode is already set, and
+     *  for TXT. */
     setEditingMode(mode: EditingMode, expectedGeneration?: number): boolean;
     private updateSurface;
+    /** Replaces the complete source as one undo step. Returns false for identical source. */
     replaceSource(text: string, expectedGeneration?: number): boolean;
     private applySource;
+    /**
+     * Takes typed source without parsing it. Parsing, preservation and replacing
+     * the formatted document cost as much as a document load, so they wait for
+     * the next thing that needs them.
+     */
+    private deferSource;
+    private rememberTypedStep;
+    private showTypedSource;
+    /**
+     * Undoes or redoes typed source that the formatted document has not taken
+     * in, on the text alone. Returns whether there was a step to take.
+     */
+    private stepTypedSource;
+    /** Brings the formatted document up to the source that was typed. */
+    private settleSource;
+    private commitSource;
+    /** Returns whether a history step applied. */
     undo(expectedGeneration?: number): boolean;
+    /** Returns whether a history step applied. */
     redo(expectedGeneration?: number): boolean;
     private replaceLiteralSelection;
+    /** The complete current text, which is what a host saves. It throws rather than return partial
+     *  text. */
     snapshot(expectedGeneration?: number): DocumentSnapshot;
+    /** The whole document as standalone HTML for printing. Rejects rather than return partial
+     *  output. */
     printableSnapshot(expectedGeneration?: number): Promise<PrintableDocument>;
-    clipboardSnapshot(all?: boolean): Promise<ClipboardOutput>;
-    paste(input: ClipboardInput): Promise<void>;
+    /**
+     * The document to export. Source typed in the source editor has not reached
+     * the formatted document, which would merge its undo steps, so a document
+     * read from the text stands in without touching history.
+     */
+    private exportDocument;
+    /** Prepares the document or the selection for the native clipboard. Rejects with `stale-document`
+     *  if the document changes first. */
+    clipboardSnapshot(scope?: ClipboardScope, expectedGeneration?: number): Promise<ClipboardOutput>;
+    /** Pastes content the host read from the native clipboard. Capture it once; don't read the
+     *  clipboard again while this runs. */
+    paste(input: ClipboardInput, expectedGeneration?: number): Promise<void>;
+    /** Shows or hides author comments. Presentation only: the revision, history and dirty state don't
+     *  change. */
     setCommentsVisible(visible: boolean): void;
-    pasteAsPlainText(text: string): void;
-    table(command: TableCommand, options?: TableOptions): boolean;
+    /** Inserts `text` literally at the selection and returns whether the document changed. */
+    pasteAsPlainText(text: string, expectedGeneration?: number): boolean;
+    private insertPlainText;
+    /** Runs a table command and returns whether it applied. False in source and TXT modes, outside a
+     *  table for commands that need one, and at a boundary a move can't cross. */
+    table(command: TableCommand, options?: TableOptions, expectedGeneration?: number): boolean;
+    /** Cancels pending work and releases the editor. It never rejects. Afterwards every other member
+     *  throws `destroyed`. */
     destroy(): Promise<void>;
     private keymapPlugin;
     private copySourceSelection;
+    /** Builds the editor in `root`. It has no document until `loadDocument`. Rejects with
+     *  `invalid-argument` for a bad root, handler or option. */
     static mount(root: HTMLElement, events: EditorEvents, options?: EditorOptions): Promise<InkKitEditor>;
+    /** Replaces the document. The generation must be greater than the loaded one. A failed load
+     *  changes nothing. */
     loadDocument(input: DocumentInput): void;
-    reloadDocument(input: DocumentInput): void;
+    /** Moves focus off whichever of InkKit's text surfaces holds it; other focus is left alone. */
+    private releaseFocus;
+    /** Replaces the document with a newer version of it, keeping the selection, focus, scroll
+     *  position and Markdown editing mode. With `expectedGeneration`, the loaded document must be
+     *  that generation. */
+    reloadDocument(input: DocumentInput, expectedGeneration?: number): void;
+    /** Names the scroll container and the host chrome that overlaps the editor. It replaces earlier
+     *  settings. */
     setViewport(options: ViewportOptions): void;
+    /** The visible rectangle, the insets and the scroll offsets. */
     viewport(): ViewportSnapshot;
     private readableScope;
+    /** The readable text and selection. Ranges from it go stale when the document, its revision or
+     *  the mode changes. */
     textSnapshot(expectedGeneration?: number): ReadableTextSnapshot;
     private validateTextRange;
     selectTextRange(range: TextRange, options?: {
@@ -180,48 +346,95 @@ export declare class InkKitEditor {
         reveal?: boolean;
     }): void;
     /** Throws when a document reached by an edit, after every appended normalisation, cannot be
-     *  saved as preserved Markdown. Dispatch and the replacement commands share this check. */
+     *  saved as preserved Markdown. Dispatch and the replacement commands share this check.
+     *  `written` is false for history steps and source replacement, which restore or supply a
+     *  document that may hold comment text the formatted editor would refuse to accept typed. */
     private assertPreserved;
+    /** Replaces `range` with literal text as one undo step. Returns whether the text changed. */
     replaceTextRange(range: TextRange, text: string): boolean;
-    textRangeRects(range: TextRange): readonly TextRect[];
+    /** Measures ranges in client coordinates, with one array of rectangles for each. It measures only
+     *  when called. */
     textRangesRects(ranges: readonly TextRange[]): readonly (readonly TextRect[])[];
+    /** The ranges of the snapshot that are inside the viewport now. */
     visibleTextRanges(snapshotId: string): readonly TextRange[];
+    /** Scrolls `range` into the viewport, unfolding a callout that holds it. */
     revealTextRange(range: TextRange): void;
     private revealRects;
     private revealCurrentSelection;
     private revealLiteralSelection;
     private load;
-    find(text: string, expectedGeneration?: number): void;
+    /** Selects the next match and returns whether there was one. */
+    find(text: string, expectedGeneration?: number): boolean;
+    /** Replaces the selected match, or the next one, and returns whether text changed. */
     replace(search: string, replacement: string, expectedGeneration?: number): boolean;
+    /** Replaces every non-overlapping match once and returns how many. */
     replaceAll(search: string, replacement: string, expectedGeneration?: number): number;
     private replaceMatches;
     private outlineContext;
+    /** The outline in document order. Entries go stale when the document changes. */
     headings(expectedGeneration?: number): readonly Heading[];
+    /** Moves to `heading`. Returns true, or throws `stale-document` for a stale entry. */
     navigateHeading(heading: Heading): boolean;
-    /** Buffered native typing follows the same input rules as direct typing. */
+    /** Buffered native typing: input rules apply as if its last character were typed after the rest. */
     insertText(text: string, generation: number): boolean;
-    /** Let existing keymaps handle buffered editing commands before native fallback. */
-    keyDown(key: string, code: string, metaKey: boolean, ctrlKey: boolean, altKey: boolean, shiftKey: boolean, generation: number): boolean;
-    focus(): void;
-    /** Binds keys, in ProseMirror's names, to the formatting each shortcut runs. Walked in the table's
-     *  order, so a key given to two shortcuts lands the same way every time. */
+    /**
+     * A key the host's native input received, run through InkKit's key handling. Returns whether
+     * InkKit handled it; when it did, the host must not also handle it natively.
+     */
+    keyDown(input: KeyInput, expectedGeneration: number): boolean;
+    focus(expectedGeneration?: number): void;
+    /** Moves focus off InkKit's text surfaces. Focus anywhere else, such as in a host control or a
+     *  control InkKit draws, is left alone. */
+    blur(expectedGeneration?: number): void;
+    /** Replaces every binding. Keys are in ProseMirror's notation. A key given to two shortcuts goes
+     *  to the later one, in the order history, formatting, tables, so it lands the same way every
+     *  time. */
     setKeymap(keymap: Keymap): void;
     /** Dropped files land as one paragraph per path at the drop point: in place of an empty block, after
      *  the top-level block otherwise, so a list or quote is not opened up by them. */
-    insertPaths(paths: string[], x: number, y: number): void;
-    insertImages(images: {
-        path: string;
-        alt: string;
-        title?: string;
-    }[], x?: number, y?: number): void;
+    insertPaths(paths: string[], at: ClientPoint, expectedGeneration?: number): boolean;
+    /** Inserts images by reference, at the selection or the drop point `at`. Returns false when it
+     *  does nothing. */
+    insertImages(images: ImageInsertion[], at?: ClientPoint, expectedGeneration?: number): boolean;
+    private insertInline;
     private insertBlocks;
     private withMarkRunSelected;
     private toggleInlineCode;
     private list;
     private quote;
     private unquote;
-    format(command: FormatCommand, arg?: string | number): void;
-    editReferenceDefinition(label: string, destination: string, title?: string): boolean;
-    insertFootnote(label?: string): void;
-    navigateFootnote(target: 'definition' | 'reference'): boolean;
+    /** Changes the selected textblocks' type, keeping everything they hold. */
+    private textblockType;
+    /**
+     * The authored Markdown of the textblocks at `positions`, found by saving
+     * the document once with each block's content replaced by a numbered mark
+     * no one writes. The saved text between the marks is the current text
+     * between those blocks, so what lies between the same pieces of the current
+     * text is each block's source.
+     */
+    private authoredSources;
+    /** Returns whether the document or the marks the next typed text takes changed. */
+    format(command: FormatCommand, options?: FormatOptions, expectedGeneration?: number): boolean;
+    /**
+     * Refuses a link destination that is empty, that opens anything but a web, mail or phone address,
+     * or that the Markdown writer cannot save so that it reads back the same.
+     */
+    private checkDestination;
+    /**
+     * With a destination, sets the link: on the whole link that holds the caret or the selection,
+     * keeping its title, or else on the selection. A reference link's shared definition is edited
+     * instead. Without one, removes that whole link, or every link in the selection. Marks waiting
+     * for the next typed text stay waiting.
+     */
+    private link;
+    /** Changes the destination, and optionally the title, of the shared definition for `label`.
+     *  Returns false when no definition has that label. */
+    editReferenceDefinition(label: string, destination: string, title?: string, expectedGeneration?: number): boolean;
+    /** Inserts a footnote reference, and a definition when the label has none, and returns whether
+     *  it did: formatted Markdown only. */
+    insertFootnote(label?: string, expectedGeneration?: number): boolean;
+    /** Moves to the definition, or the first reference, of the footnote at the caret. Returns whether
+     *  there was one. */
+    navigateFootnote(target: 'definition' | 'reference', expectedGeneration?: number): boolean;
 }
+export {};

package/dist/index.d.ts

@@ -1,7 +1 @@
-export { InkKitEditor } from './editor.js';
-export type { EditorEvents, EditorOptions, TextInputPreferences, CommandState, EditingMode, CaretState, Mark, Block, FormatCommand, Keymap, } from './editor.js';
-export type { TableCommand, TableOptions } from './tables.js';
-export type { Heading } from './outline.js';
-export { InkKitError } from './types.js';
-export type { DocumentFormat, DocumentContext, DocumentInput, DocumentSnapshot, EditorErrorCode, ImageAdapter, WikiLinkReference, WikiLinkAdapter, FileReference, FileContext, FilePresentation, FileAdapter, CapturedImage, PortableImage, ClipboardInput, ClipboardOutput, ClipboardImage, ClipboardDiagram, PrintableDocument, PrintableWarning, TextRange, ReadableTextSnapshot, TextRect, ViewportInsets, ViewportOptions, ViewportSnapshot, } from './types.js';
-export type { EditorLabels } from './labels.js';
+export * from './core.js';

package/dist/index.js

@@ -1,2 +1,5 @@
-export { InkKitEditor } from './editor.js';
-export { InkKitError } from './types.js';
+import { n as registerMermaid, r as InkKitError, t as InkKitEditor } from "./chunks/core-vtCr4MBS.js";
+//#region src/index.ts
+registerMermaid(async () => (await import("mermaid")).default);
+//#endregion
+export { InkKitEditor, InkKitError };