prosemirror-flat-list/dist/prosemirror-flat-list.d.ts

Powerful list support for ProseMirror

import type { Attrs } from 'prosemirror-model';
import { Command } from 'prosemirror-state';
import { DOMOutputSpec } from 'prosemirror-model';
import { DOMSerializer } from 'prosemirror-model';
import { EditorState } from 'prosemirror-state';
import { EditorView } from 'prosemirror-view';
import { Fragment } from 'prosemirror-model';
import { InputRule } from 'prosemirror-inputrules';
import { NodeRange } from 'prosemirror-model';
import { NodeSpec } from 'prosemirror-model';
import { NodeType } from 'prosemirror-model';
import { NodeViewConstructor } from 'prosemirror-view';
import { Plugin as Plugin_2 } from 'prosemirror-state';
import { Node as ProsemirrorNode } from 'prosemirror-model';
import { ResolvedPos } from 'prosemirror-model';
import { Schema } from 'prosemirror-model';
import { Slice } from 'prosemirror-model';
import { TagParseRule } from 'prosemirror-model';
import { Transaction } from 'prosemirror-state';

/**
 * Keybinding for `Backspace`. It's chained with following commands:
 *
 * - {@link protectCollapsed}
 * - [deleteSelection](https://prosemirror.net/docs/ref/#commands.deleteSelection)
 * - {@link joinListUp}
 * - {@link joinCollapsedListBackward}
 * - [joinTextblockBackward](https://prosemirror.net/docs/ref/#commands.joinTextblockBackward)
 * - [selectNodeBackward](https://prosemirror.net/docs/ref/#commands.selectNodeBackward)
 *
 * @public @group Commands
 *
 */
export declare const backspaceCommand: Command;

/**
 * Returns a command function that decreases the indentation of selected list nodes.
 *
 * @public @group Commands
 */
export declare function createDedentListCommand(options?: DedentListOptions): Command;

/**
 * Returns a command function that increases the indentation of selected list
 * nodes.
 *
 * @public @group Commands
 */
export declare function createIndentListCommand(options?: IndentListOptions): Command;

/**
 * Serialize list nodes into native HTML list elements (i.e. `<ul>`, `<ol>`) to
 * clipboard. See {@link ListDOMSerializer}.
 *
 * @public @group Plugins
 */
export declare function createListClipboardPlugin(schema: Schema): Plugin_2;

/**
 * Handle DOM events for list.
 *
 * @public @group Plugins
 */
export declare function createListEventPlugin(): Plugin_2;

/**
 * A simple node view that is used to render the list node. It ensures that the
 * list node get updated when its marker styling should changes.
 *
 * @public @group Plugins
 */
export declare const createListNodeView: NodeViewConstructor;

/**
 * This function returns an array of plugins that are required for list to work.
 *
 * The plugins are shown below. You can pick and choose which plugins you want
 * to use if you want to customize some behavior.
 *
 * - {@link createListEventPlugin}
 * - {@link createListRenderingPlugin}
 * - {@link createListClipboardPlugin}
 * - {@link createSafariInputMethodWorkaroundPlugin}
 *
 * @public @group Plugins
 */
export declare function createListPlugins(options: {
    schema: Schema;
}): Plugin_2[];

/**
 * Handle the list node rendering.
 *
 * @public @group Plugins
 */
export declare function createListRenderingPlugin(): Plugin_2;

/**
 * Return the spec for list node.
 *
 *  @public @group Schema
 */
export declare function createListSpec(): NodeSpec;

/**
 * Returns a command function that moves up or down selected list nodes.
 *
 * @public @group Commands
 *
 */
export declare function createMoveListCommand(direction: 'up' | 'down'): Command;

/**
 * Returns a set of rules for parsing HTML into ProseMirror list nodes.
 *
 * @public @group Schema
 */
export declare function createParseDomRules(): readonly TagParseRule[];

/**
 * Return a plugin as a workaround for a bug in Safari that causes the composition
 * based IME to remove the empty HTML element with CSS `position: relative`.
 *
 * See also https://github.com/ProseMirror/prosemirror/issues/934
 *
 * @public @group Plugins
 */
export declare function createSafariInputMethodWorkaroundPlugin(): Plugin_2;

/**
 * Returns a command that split the current list node.
 *
 * @public @group Commands
 *
 */
export declare function createSplitListCommand(): Command;

/**
 * Return a command function that toggle the `collapsed` attribute of the list node.
 *
 * @public @group Commands
 */
export declare function createToggleCollapsedCommand(options?: ToggleCollapsedOptions): Command;

/**
 * Returns a command function that wraps the selection in a list with the given
 * type and attributes, or change the list kind if the selection is already in
 * another kind of list, or unwrap the selected list if otherwise.
 *
 * @public @group Commands
 */
export declare function createToggleListCommand<T extends ListAttributes = ListAttributes>(
/**
 * The list node attributes to toggle.
 */
attrs: T): Command;

/**
 * Returns a command function that unwraps the list around the selection.
 *
 * @public @group Commands
 */
export declare function createUnwrapListCommand(options?: UnwrapListOptions): Command;

/**
 * Returns a command function that wraps the selection in a list with the given
 * type and attributes.
 *
 * @public @group Commands
 */
export declare function createWrapInListCommand<T extends ListAttributes = ListAttributes>(getAttrs: WrapInListGetAttrs<T>): Command;

/**
 * @public @group Commands
 */
export declare interface DedentListOptions {
    /**
     * A optional from position to indent.
     *
     * @defaultValue `state.selection.from`
     */
    from?: number;
    /**
     * A optional to position to indent.
     *
     * @defaultValue `state.selection.to`
     */
    to?: number;
}

/** @internal */
export declare function defaultAttributesGetter(node: ProsemirrorNode): {
    class: string;
    'data-list-kind': string | undefined;
    'data-list-order': string | undefined;
    'data-list-checked': string | undefined;
    'data-list-collapsed': string | undefined;
    'data-list-collapsable': string | undefined;
    style: string | undefined;
};

/** @internal */
export declare const defaultListClickHandler: ListClickHandler;

/** @internal */
export declare function defaultMarkerGetter(node: ProsemirrorNode): DOMOutputSpec[] | null;

/**
 * Keybinding for `Delete`. It's chained with following commands:
 *
 * - {@link protectCollapsed}
 * - [deleteSelection](https://prosemirror.net/docs/ref/#commands.deleteSelection)
 * - [joinTextblockForward](https://prosemirror.net/docs/ref/#commands.joinTextblockForward)
 * - [selectNodeForward](https://prosemirror.net/docs/ref/#commands.selectNodeForward)
 *
 * @public @group Commands
 *
 */
export declare const deleteCommand: Command;

/**
 * @internal
 */
export declare function doSplitList(state: EditorState, listNode: ProsemirrorNode, dispatch?: (tr: Transaction) => void): boolean;

/**
 * Keybinding for `Enter`. It's chained with following commands:
 *
 * - {@link protectCollapsed}
 * - {@link createSplitListCommand}
 *
 * @public @group Commands
 */
export declare const enterCommand: Command;

/**
 * This command has the same behavior as the `Enter` keybinding from
 * `prosemirror-commands`, but without the `liftEmptyBlock` command.
 *
 * @internal
 */
export declare const enterWithoutLift: Command;

/**
 * Returns a minimal block range that includes the given two positions and
 * represents one or multiple sibling list nodes.
 *
 * @public
 */
export declare function findListsRange($from: ResolvedPos, $to?: ResolvedPos): NodeRange | null;

/**
 * The default group name for list nodes. This is used to find the list node
 * type from the schema.
 *
 * @internal Schema
 */
export declare const flatListGroup = "flatList";

/** @internal */
export declare function getListType(schema: Schema): NodeType;

/** @internal */
export declare function handleListMarkerMouseDown({ view, event, onListClick, }: {
    view: EditorView;
    event: MouseEvent;
    onListClick?: ListClickHandler;
}): boolean;

/**
 * @public @group Commands
 */
export declare interface IndentListOptions {
    /**
     * A optional from position to indent.
     *
     * @defaultValue `state.selection.from`
     */
    from?: number;
    /**
     * A optional to position to indent.
     *
     * @defaultValue `state.selection.to`
     */
    to?: number;
}

/**
 * @internal
 */
export declare function isCollapsedListNode(node: ProsemirrorNode): boolean;

/** @public */
export declare function isListNode(node: ProsemirrorNode | null | undefined): boolean;

/** @internal */
export declare function isListsRange(range: NodeRange): boolean;

/** @public */
export declare function isListType(type: NodeType): boolean;

/**
 * If the selection is empty and at the start of a block, and there is a
 * collapsed list node right before the cursor, move current block and append it
 * to the first child of the collapsed list node (i.e. skip the hidden content).
 *
 * @public @group Commands
 */
export declare const joinCollapsedListBackward: Command;

/**
 * Merge adjacent <ul> elements or adjacent <ol> elements into a single list element.
 *
 * @public
 */
export declare function joinListElements<T extends Element | DocumentFragment>(parent: T): T;

/**
 * If the text cursor is at the start of the first child of a list node, lift
 * all content inside the list. If the text cursor is at the start of the last
 * child of a list node, lift this child.
 *
 * @public @group Commands
 */
export declare const joinListUp: Command;

/**
 * @public @group Schema
 */
export declare interface ListAttributes {
    kind?: string;
    order?: number | null;
    checked?: boolean;
    collapsed?: boolean;
}

/** @internal */
export declare type ListClickHandler = (node: ProsemirrorNode) => ListAttributes;

/**
 * A custom DOM serializer class that can serialize flat list nodes into native
 * HTML list elements (i.e. `<ul>` and `<ol>`).
 *
 * @public @group Plugins
 */
export declare class ListDOMSerializer extends DOMSerializer {
    static nodesFromSchema(schema: Schema): {
        [node: string]: (node: ProsemirrorNode) => DOMOutputSpec;
    };
    static fromSchema(schema: Schema): ListDOMSerializer;
    serializeFragment(fragment: Fragment, options?: {
        document?: Document;
    }, target?: HTMLElement | DocumentFragment): HTMLElement | DocumentFragment;
}

/**
 * A callback function to get the attributes for a list input rule.
 *
 * @public @group Input Rules
 */
export declare type ListInputRuleAttributesGetter<T extends ListAttributes = ListAttributes> = (options: {
    /**
     * The match result of the regular expression.
     */
    match: RegExpMatchArray;
    /**
     * The previous attributes of the existing list node, if it exists.
     */
    attributes?: T;
}) => T;

/**
 * All input rules for lists.
 *
 * @public @group Input Rules
 */
export declare const listInputRules: InputRule[];

/**
 * Returns an object containing the keymap for the list commands.
 *
 * - `Enter`: See {@link enterCommand}.
 * - `Backspace`: See {@link backspaceCommand}.
 * - `Delete`: See {@link deleteCommand}.
 * - `Mod-[`: Decrease indentation. See {@link createDedentListCommand}.
 * - `Mod-]`: Increase indentation. See {@link createIndentListCommand}.
 *
 * @public @group Commands
 */
export declare const listKeymap: {
    Enter: Command;
    Backspace: Command;
    Delete: Command;
    'Mod-[': Command;
    'Mod-]': Command;
};

/**
 * All default list node kinds.
 *
 * @public @group Schema
 */
export declare type ListKind = 'bullet' | 'ordered' | 'task' | 'toggle';

/**
 * Renders a list node to DOM output spec.
 *
 * @public @group Schema
 */
export declare function listToDOM(options: ListToDOMOptions): DOMOutputSpec;

/**
 * @public @group Schema
 */
export declare interface ListToDOMOptions {
    /**
     * The list node to be rendered.
     */
    node: ProsemirrorNode;
    /**
     * If `true`, the list will be rendered as a native `<ul>` or `<ol>` element.
     * You might want to use {@link joinListElements} to join the list elements
     * afterward.
     *
     * @defaultValue false
     */
    nativeList?: boolean;
    /**
     * An optional function to get elements inside `<div class="list-marker">`.
     * Return `null` to hide the marker.
     */
    getMarkers?: (node: ProsemirrorNode) => DOMOutputSpec[] | null;
    /**
     * An optional function to get the attributes added to HTML element.
     */
    getAttributes?: (node: ProsemirrorNode) => Record<string, string | undefined>;
}

/**
 * Migrate a ProseMirror document JSON object from the old list structure to the
 * new. A new document JSON object is returned if the document is updated,
 * otherwise `null` is returned.
 *
 * @public
 */
export declare function migrateDocJSON(docJSON: ProsemirrorNodeJSON): ProsemirrorNodeJSON | null;

/** @internal */
export declare function parseInteger(attr: string | null | undefined): number | null;

export { ProsemirrorNode }

/**
 * @public @group Schema
 */
export declare interface ProsemirrorNodeJSON {
    type: string;
    marks?: Array<{
        type: string;
        attrs?: Attrs;
    } | string>;
    text?: string;
    content?: ProsemirrorNodeJSON[];
    attrs?: Attrs;
}

/**
 * This command will protect the collapsed items from being deleted.
 *
 * If current selection contains a collapsed item, we don't want the user to
 * delete this selection by pressing Backspace or Delete, because this could
 * be unintentional.
 *
 * In such case, we will stop the delete action and expand the collapsed items
 * instead. Therefore the user can clearly know what content he is trying to
 * delete.
 *
 * @public @group Commands
 *
 */
export declare const protectCollapsed: Command;

/**
 * Return a debugging string that describes this range.
 *
 * @internal
 */
export declare function rangeToString(range: NodeRange): string;

/**
 * If one of the selection's end points is inside a collapsed node, move the selection outside of it
 *
 * @internal
 */
export declare function setSafeSelection(tr: Transaction): Transaction;

/**
 * @public @group Commands
 */
export declare interface ToggleCollapsedOptions {
    /**
     * If this value exists, the command will set the `collapsed` attribute to
     * this value instead of toggle it.
     */
    collapsed?: boolean;
    /**
     * An optional function to accept a list node and return whether or not this
     * node can toggle its `collapsed` attribute.
     */
    isToggleable?: (node: ProsemirrorNode) => boolean;
}

/**
 * @public @group Commands
 */
export declare interface UnwrapListOptions {
    /**
     * If given, only this kind of list will be unwrap.
     */
    kind?: string;
}

/**
 * Reduce the open depth of a slice if it only contains a single list node. When
 * copying some text from a deep nested list node, we don't want to paste the
 * entire list structure into the document later.
 *
 * @internal
 */
export declare function unwrapListSlice(slice: Slice): Slice;

/**
 * The list node attributes or a callback function to take the current
 * selection block range and return list node attributes. If this callback
 * function returns null, the command won't do anything.
 *
 * @public @group Commands
 */
export declare type WrapInListGetAttrs<T extends ListAttributes> = T | ((range: NodeRange) => T | null);

/**
 * Build an input rule for automatically wrapping a textblock into a list node
 * when a given string is typed.
 *
 * @public @group Input Rules
 */
export declare function wrappingListInputRule<T extends ListAttributes = ListAttributes>(regexp: RegExp, getAttrs: T | ListInputRuleAttributesGetter<T>): InputRule;

export { }