@nerd-bible/wordgard 0.5.3-beta7 → 0.6.2-beta10

package/dist/editor.d.ts

@@ -1,5 +1,5 @@
 import * as wordgard_doc from 'wordgard/doc';
-import { Elt, Node as Node$1, ChangeSet, Plot, Pos } from 'wordgard/doc';
+import { Elt, Node as Node$1, Mark, Shape, ChangeSet, Plot, Pos } from 'wordgard/doc';
 import { GardState, TextblockMap, Transaction, GardSelection } from 'wordgard/state';
 import { PhraseSet } from 'wordgard/phrases';
 import { StyleModule, StyleSpec } from 'style-mod';
@@ -8,6 +8,7 @@ import { PointSet, Set, RangeSet } from 'wordgard/set';
 
 type MakeSelectionStyle = (wg: Wordgard, event: MouseEvent) => Wordgard.MouseSelectionStyle | null;
 
+import Mark_ = Mark;
 /**
 A widget describes a piece of DOM content that can be used to
 render a node, a part of a node, or an extra element added via a
@@ -125,7 +126,7 @@ declare namespace Decoration {
             This function allows you to define a {@link Decoration.Tag.shape
             custom node shape} that depends on the editor state. It will
             automatically track which state slots (see {@link
-            GardState.Facet.compute}) you use, and make sure the nodes
+            GardState.Facet.derive}) you use, and make sure the nodes
             are redrawn when those change.
             
             If your shape function returns a function from a tag, you
@@ -141,8 +142,7 @@ declare namespace Decoration {
             When providing a shape for a plot that changes whether it is
             rendered as an atom, provide the `atom` option.
             */
-            function dynamic<T extends Node$1.Type<any>>(// FIXME find better name?
-            type: T, shape: (state: GardState) => Shape | ((tag: Node$1.Tag.For<T>) => Shape), config?: {
+            function derived<T extends Node$1.Type<any>>(type: T, shape: (state: GardState) => Shape | ((tag: Node$1.Tag.For<T>) => Shape), config?: {
                 atom?: boolean;
             }): GardState.Extension;
         }
@@ -172,9 +172,9 @@ declare namespace Decoration {
             /**
             Define a node widget decoration that depends on some aspect
             of the editor state. See the notes for {@link
-            Decoration.Tag.shape.dynamic}.
+            Decoration.Tag.shape.derived}.
             */
-            function dynamic<T extends Node$1.Type.Ref<any>>(type: T, place: "before" | "after" | "start" | "end", widget: (state: GardState) => Widget | ((tag: Node$1.Tag.For<T>) => Widget)): GardState.Extension;
+            function derived<T extends Node$1.Type.Ref<any>>(type: T, place: "before" | "after" | "start" | "end", widget: (state: GardState) => Widget | ((tag: Node$1.Tag.For<T>) => Widget)): GardState.Extension;
         }
         /**
         Add an attribute to the representation of a given node type.
@@ -190,6 +190,13 @@ declare namespace Decoration {
             target?: string;
         }): GardState.Extension;
     }
+    namespace Mark {
+        /**
+        Override the shape used for a given mark inside the editor.
+        */
+        function shape<V>(type: Mark_.Type<V>, shape: Shape.Element<V> | Shape.Attribute<V> | Shape.Attributes<V>): GardState.Extension;
+        function shape(mark: Mark_<null>, shape: Shape.Element<null> | Shape.Attribute<null> | Shape.Attributes<null>): GardState.Extension;
+    }
     /**
     A point decoration is a decoration that targets a given position
     in the document, or the node after a given position. Sets of
@@ -369,10 +376,11 @@ declare const enum TileFlag {
     Composition = 128,
     Synced = 256,// Node has been synced. DOM content matches child list / text content, child array becomes read-only
     Atom = 512,// Composite tile whose length isn't determined by child length
-    HasContent = 1024,// EltTile whose elt has a content hole
-    AfterContent = 2048,// Tiles that sit after their parent's content position
-    ContentNotLast = 4096,// EltTile that has children with AfterContent flag
-    Dirty = 8192
+    Uneditable = 1024,// Tile's DOM is uneditable
+    HasContent = 2048,// EltTile whose elt has a content hole
+    AfterContent = 4096,// Tiles that sit after their parent's content position
+    ContentNotLast = 8192,// EltTile that has children with AfterContent flag
+    Dirty = 16384
 }
 declare const enum Orientation {
     Row = 0,
@@ -414,14 +422,15 @@ declare abstract class Tile {
     get boundary(): 0 | 1;
     get firstChild(): Tile | null;
     get lastChild(): Tile | null;
-    get nodeParent(): Tile;
     ignoreEvent(event: Event): boolean;
     get ignoreMutations(): boolean;
     toString(): string;
     abstract sync(): void;
     connect(): void;
     disconnect(reused?: Map<Tile, Reused>): void;
-    nearestNode(): Tile;
+    nearestNode(): Tile & {
+        tag: Node$1.Tag;
+    };
     markDirty(): void;
     posAtCoords(state: GardState, x: number, y: number): CoordPos;
     abstract posAtCoordsInner(start: number, state: GardState, x: number, y: number, textblock: TextblockMap | null, orientation: Orientation): CoordPos;
@@ -431,6 +440,7 @@ declare class CompositeTile extends Tile {
     children: Tile[];
     dom: Element;
     addChild(child: Tile): void;
+    putChild(child: Tile, index: number): void;
     sync(): void;
     syncChildren(): void;
     posAtCoordsInner(start: number, state: GardState, x: number, y: number, textblock: TextblockMap | null, orientation: Orientation): CoordPos;
@@ -691,7 +701,7 @@ declare class Wordgard {
     Serializers are tried in order of precedence until one returns
     a string.
     */
-    static clipboardTextSerializer: GardState.Facet<(slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[], state: GardState) => string | null, readonly ((slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[], state: GardState) => string | null)[]>;
+    static clipboardTextSerializer: GardState.Facet<(slice: wordgard_doc.Slice, state: GardState) => string | null, readonly ((slice: wordgard_doc.Slice, state: GardState) => string | null)[]>;
     /**
     Filter to run on the plain text representation of content put
     onto the clipboard.
@@ -721,7 +731,13 @@ declare class Wordgard {
     Facet that allows you to register handlers to override paste
     behavior.
     */
-    static pasteHandler: GardState.Facet<(wg: Wordgard, event: ClipboardEvent, slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[]) => boolean, readonly ((wg: Wordgard, event: ClipboardEvent, slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[]) => boolean)[]>;
+    static pasteHandler: GardState.Facet<(wg: Wordgard, event: InputEvent | null, slice: wordgard_doc.Slice, html: string, text: string) => boolean, readonly ((wg: Wordgard, event: InputEvent | null, slice: wordgard_doc.Slice, html: string, text: string) => boolean)[]>;
+    /**
+    Perform a paste with the given content. This will run {@link
+    Wordgard.pasteHandler paste handlers} and, if none handles the
+    paste, fall back to the default handling.
+    */
+    paste(html: string, text?: string): void;
     /**
     Facet for custom drop handlers. When the drop is done inside the
     editor and should move an existing range, the `move` parameter
@@ -730,10 +746,10 @@ declare class Wordgard {
     static dropHandler: GardState.Facet<(wg: Wordgard, event: DragEvent, pos: number, move: {
         from: number;
         to: number;
-    } | null, slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[]) => boolean, readonly ((wg: Wordgard, event: DragEvent, pos: number, move: {
+    } | null, slice: wordgard_doc.Slice) => boolean, readonly ((wg: Wordgard, event: DragEvent, pos: number, move: {
         from: number;
         to: number;
-    } | null, slice: wordgard_doc.Slice, context: readonly wordgard_doc.Plot.Tag[]) => boolean)[]>;
+    } | null, slice: wordgard_doc.Slice) => boolean)[]>;
     /**
     This annotation is added to transactions created because the
     editor's focused status changed. It holds `true` when the editor
@@ -847,7 +863,7 @@ declare class Wordgard {
     the editor's {@link Wordgard.dom wrapper element} (to which the
     scope class will be added) need to be explicitly differentiated
     by adding an `&` to the selector for that element—for example
-    `&:has(wg-content:focus)`.
+    `&.wg-focused`.
     */
     static theme(spec: Record<string, StyleSpec>): GardState.Extension;
     /**
@@ -916,6 +932,11 @@ declare class Wordgard {
     part of the editor (for example a gutter).
     */
     static coveredMargins: GardState.Facet<(wg: Wordgard) => Partial<DOMRect> | null, readonly ((wg: Wordgard) => Partial<DOMRect> | null)[]>;
+    /**
+    Given a DOM element that may be a Wordgard editor, retrieve its
+    editor instance.
+    */
+    static findFromDOM(elt: Element): Wordgard | null;
 }
 declare namespace Wordgard {
     /**
@@ -1160,9 +1181,8 @@ appear in
 Use lowercase letters to refer to letter keys. You can use
 `"Space"` as an alias for the `" "` name.
 
-Modifiers can be given in any order. `Shift-` (or `s-`), `Alt-` (or
-`a-`), `Ctrl-` (or `c-` or `Control-`) and `Cmd-` (or `m-` or
-`Meta-`) are recognized.
+Modifiers can be given in any order. `Shift-`, `Alt-`, `Ctrl-` and
+`Cmd-` (or `Meta-`) are recognized.
 
 You can use `Mod-` as a shorthand for `Cmd-` on Mac and `Ctrl-` on
 other platforms. So `Mod-b` is `Ctrl-b` on Linux but `Cmd-b` on
@@ -1238,28 +1258,28 @@ declare namespace KeyBinding {
         */
         any?: (wg: Wordgard, event: KeyboardEvent) => boolean;
         /**
-        By default, key bindings apply when focus is on the editor
-        content (the `"editor"` scope). Some extensions, mostly those
-        that define their own panels, might want to allow registering
-        bindings local to that panel. Such bindings should use a custom
-        scope name. You may also assign multiple scope names to a
-        binding, separating them by spaces.
-        */
-        scope?: string;
-        /**
         By default, all keys events for which a handler exists have
         their `preventDefault` called, even if no handler returns
         true. You can set this to true to disable that behavior.
         */
         allowDefault?: boolean;
+        /**
+        A textual description of what this key does. Will be used by
+        {@link keyBindingHelp} to create a list of active bindings.
+        */
+        description?: PhraseSet.Ref | string;
+        /**
+        A textual description of what the shifted variant of this key
+        does.
+        */
+        shiftDescription?: PhraseSet.Ref | string;
+        /**
+        The group under which the description of this key should be
+        organized in the list of bindings.
+        */
+        group?: Group;
     }
     /**
-    Run the key handlers registered for a given scope. The event
-    object should be a `"keydown"` event. Returns true if any of the
-    handlers handled it.
-    */
-    function runScopeHandlers(wg: Wordgard, event: KeyboardEvent, scope: string): boolean;
-    /**
     Facet used for registering key bindings. Extension precedence
     determines the order in which bindings that match the same key
     are called. When a handler has returned `true` for a given key,
@@ -1273,6 +1293,38 @@ declare namespace KeyBinding {
     */
     const useDefaultKeymap: GardState.Facet<boolean, boolean>;
     /**
+    Key binding groups are used to {@link KeyBinding.Spec.group
+    organize} key bindings in the user-presented {@link
+    keyBindingHelp list} of bindings.
+    */
+    class Group {
+        /**
+        The description given for this group.
+        */
+        readonly description: PhraseSet.Ref | string;
+        /**
+        A sorting rank.
+        */
+        readonly rank: number;
+        private constructor();
+        /**
+        Define a key binding group.
+        */
+        static define(spec: {
+            description: PhraseSet.Ref | string;
+            rank?: number;
+        }): Group;
+        static Inline: Group;
+        static Block: Group;
+        static History: Group;
+    }
+    /**
+    Look for a key associated with the given description in the
+    state's key bindings, and if found, return its key name as a
+    string.
+    */
+    function lookupByDescription(state: GardState, desc: string | PhraseSet.Ref): string | null;
+    /**
     The editor's set of default key bindings. Binds the following
     keys. Most cursor motion bindings include a `Shift-` variant
     that passes the `extend` flag to the command. Enabled by default
@@ -1326,6 +1378,27 @@ declare namespace KeyBinding {
     const defaultKeymap: readonly KeyBinding[];
 }
 
+/**
+Returns an extension that binds `Mod-?` to {@link
+keyBindingHelp.showKeyBindings}.
+*/
+declare function keyBindingHelp(): GardState.Extension;
+declare namespace keyBindingHelp {
+    /**
+    This command opens a dialog displaying the key bindings that
+    have a description associated with them.
+    */
+    const showKeyBindings: Command;
+    /**
+    A menu button that, when clicked, displays the available key bindings.
+    */
+    const button: Menu.Button;
+    /**
+    Bind `Mod-?` to {@link keyBindingHelp.showKeyBindings `showKeyBindings`}.
+    */
+    const keyBindings: KeyBinding[];
+}
+
 type Config = {
     /**
     The type of plot to decorate.
@@ -1433,81 +1506,6 @@ declare function menuBar(config?: {
     template?: Menu.Template | readonly Menu.Template[];
 }): GardState.Extension;
 
-/**
-Dialogs are {@link Panel panels} opened as a side-effect, and
-closed by user action. This interface is used to describe them.
-*/
-interface Dialog {
-    /**
-    A function to render the content of the dialog. The result
-    should contain at least one `<form>` element. Submit handlers
-    and a handler for the Escape key will be added to the form.
-    
-    If this is not given, the `label`, `input`, and `submitLabel`
-    fields will be used to create a simple form for you.
-    */
-    content?: (wg: Wordgard, close: () => void) => Element;
-    /**
-    When `content` isn't given, this provides the text shown in the
-    dialog.
-    */
-    label?: string;
-    /**
-    The attributes for an input element shown next to the label. If
-    not given, no input element is added.
-    */
-    input?: {
-        [attr: string]: string;
-    };
-    /**
-    The label for the button that submits the form. Defaults to
-    `"OK"`.
-    */
-    submitLabel?: string;
-    /**
-    Extra classes to add to the panel.
-    */
-    class?: string;
-    /**
-    A query selector to find the field that should be focused when
-    the dialog is opened. When set to true, this picks the first
-    `<input>` or `<button>` element in the form. When set to
-    `false`, focus is not moved into the dialog.
-    */
-    focus?: string | boolean;
-    /**
-    By default, dialogs are shown above the editor. Set this to
-    `false` to have it show up at the bottom.
-    */
-    top?: boolean;
-}
-declare namespace Dialog {
-    /**
-    Show a dialog to display a message or prompt the user for input.
-    Returns an effect that can be dispatched to close the dialog,
-    and a promise that resolves when the dialog is closed or a form
-    inside of it is submitted.
-    
-    You are encouraged, if your handling of the result of the promise
-    dispatches a transaction, to include the `close` effect in it. If
-    you don't, this function will automatically dispatch a separate
-    transaction right after.
-    */
-    function show(wg: Wordgard, config: Dialog): {
-        close: Transaction.Effect<unknown>;
-        result: Promise<HTMLFormElement | null>;
-    };
-    /**
-    Find the {@link Panel} for an open dialog, using a class name as
-    identifier.
-    */
-    function get(wg: Wordgard, className: string): Panel | null;
-    /**
-    Close the {@link Panel} for an open dialog, by class name.
-    */
-    function close(wg: Wordgard, className: string): boolean;
-}
-
 /**
 Describes a tooltip. Values of this type, when provided through
 the {@link Tooltip.show} facet, provide the active tooltips on an
@@ -1732,6 +1730,109 @@ hover tooltip source}.
 */
 type HoverTooltipSource = (wg: Wordgard, pos: number, side: -1 | 1) => Tooltip | readonly Tooltip[] | null | Promise<Tooltip | readonly Tooltip[] | null>;
 
+/**
+Dialogs are UI elements opened as a side-effect and closed by user
+action. They may be either placed near some document position (as
+a {@link Tooltip tooltip}), or free-floating.
+*/
+interface Dialog {
+    /**
+    An arbitrary value used to identify this dialog. Used to query
+    for it via {@link Dialog.get}.
+    */
+    key?: any;
+    /**
+    A function to render the content of the dialog. The result
+    should contain at least one `<form>` element. Submit handlers
+    and a handler for the Escape key will be added to the form.
+    
+    If this is not given, the `label`, `input`, and `submitLabel`
+    fields will be used to create a simple form for you.
+    */
+    content?: (wg: Wordgard, close: () => void) => Element | DocumentFragment;
+    /**
+    When `content` isn't given, this provides the text shown in the
+    dialog.
+    */
+    label?: string;
+    /**
+    The attributes for an input element shown next to the label. If
+    not given, no input element is added.
+    */
+    input?: {
+        [attr: string]: string;
+    };
+    /**
+    The label for the button that submits the form. Defaults to
+    `"OK"`.
+    */
+    submitLabel?: string;
+    /**
+    Extra classes to add to the element.
+    */
+    class?: string;
+    /**
+    A query selector to find the field that should be focused when
+    the dialog is opened. When set to true, this picks the first
+    `<input>` or `<button>` element in the form. When set to
+    `false`, focus is not moved into the dialog.
+    */
+    focus?: string | boolean;
+    /**
+    If given, a transaction for which the predicate returns true
+    will automatically close the dialog.
+    */
+    closedBy?: (tr: Transaction) => boolean;
+    /**
+    Provide this option to position this dialog like a tooltip,
+    relative to some document position.
+    */
+    tooltip?: Omit<Tooltip, "create">;
+    /**
+    If given try to align the left top (or right top, in a
+    right-to-left layout) with the corner of this rectangle. If set
+    to `true`, call {@link PositioningHint.get} to try and get a
+    rectangle. When available, this will override the `tooltip`
+    option.
+    */
+    positioningHint?: DOMRect | true;
+}
+declare namespace Dialog {
+    /**
+    Show a dialog to display a message or prompt the user for input.
+    Returns a function that closes the dialog and a promise that
+    resolves when the dialog is closed or a form inside of it is
+    submitted.
+    */
+    function show(wg: Wordgard, config: Dialog): {
+        close: () => void;
+        result: Promise<HTMLFormElement | null>;
+    };
+    /**
+    See whether a dialog with the given key is present in the
+    editor, and if so return its DOM representation and a functionto
+    close it. Note that `dom` may be `null` if the dialog is present
+    but not yet rendered.
+    */
+    function get(wg: Wordgard, key: any): {
+        dom: HTMLElement | null;
+        close: () => void;
+    } | null;
+}
+declare namespace PositioningHint {
+    /**
+    Run function `run` with the positioning hint provided by `hint`
+    available. Until that function returns, {@link
+    PositioningHint.get} will return this rectangle, unless a nested
+    call to `runWith` shadows it.
+    */
+    function runWith<T>(hint: () => DOMRect, run: () => T): T;
+    /**
+    Get the current positioning hint, if available.
+    */
+    function get(): DOMRect | null;
+}
+
 /**
 Objects of this type represent input rules.
 */
@@ -1861,4 +1962,4 @@ being dragged over the editor.
 */
 declare function dropCursor(): GardState.Extension;
 
-export { Decoration, Dialog, InputRule, KeyBinding, Panel, Tooltip, Widget, Wordgard, decoratePlots, dropCursor, menuBar, placeholder };
+export { Decoration, Dialog, InputRule, KeyBinding, Panel, PositioningHint, Tooltip, Widget, Wordgard, decoratePlots, dropCursor, keyBindingHelp, menuBar, placeholder };