@thomasfosterau/effect-richtext 0.0.0-stage → 0.1.0

package/dist/view/decoration.d.ts

@@ -0,0 +1,339 @@
+import { Mark } from "../model/mark.js";
+import { Node } from "../model/node.js";
+import { Fragment } from "../model/fragment.js";
+import "../model.js";
+import { Mappable, Mapping } from "../transform/map.js";
+import "../transform.js";
+import { DOMNode } from "./dom.js";
+import { EditorView } from "./view.js";
+declare class FragmentCursor {
+  readonly frag: Fragment<any, any>;
+  index: number;
+  off: number;
+  constructor(frag: Fragment<any, any>);
+  spansNode(from: number, to: number): boolean;
+}
+/** @internal */
+export interface DecorationType {
+  spec: any;
+  map(mapping: Mappable, span: Decoration, offset: number, oldOffset: number): Decoration | null;
+  valid(node: Node<any, any>, span: Decoration, cursor: FragmentCursor): boolean;
+  eq(other: DecorationType): boolean;
+  destroy(dom: DOMNode): void;
+}
+/**
+ * The DOM content of a widget decoration: either a DOM node, or a
+ * function that renders it (lazily, when the widget is drawn). The
+ * `getPos` argument can be used to find the widget's current document
+ * position (it returns `undefined` when the widget is not in the
+ * document).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type WidgetConstructor = ((view: EditorView<any, any, any>, getPos: () => number | undefined) => DOMNode) | DOMNode;
+/** @internal */
+export declare class WidgetType implements DecorationType {
+  readonly toDOM: WidgetConstructor;
+  spec: any;
+  side: number;
+  constructor(toDOM: WidgetConstructor, spec: any);
+  map(mapping: Mappable, span: Decoration, offset: number, oldOffset: number): Decoration | null;
+  valid(): boolean;
+  eq(other: WidgetType): boolean;
+  destroy(node: DOMNode): void;
+}
+/** @internal */
+export declare class InlineType implements DecorationType {
+  readonly attrs: DecorationAttrs;
+  spec: any;
+  constructor(attrs: DecorationAttrs, spec: any);
+  map(mapping: Mappable, span: Decoration, offset: number, oldOffset: number): Decoration | null;
+  valid(_: Node<any, any>, span: Decoration): boolean;
+  eq(other: DecorationType): boolean;
+  static is(span: Decoration): boolean;
+  destroy(): void;
+}
+/** @internal */
+export declare class NodeType implements DecorationType {
+  readonly attrs: DecorationAttrs;
+  spec: any;
+  constructor(attrs: DecorationAttrs, spec: any);
+  map(mapping: Mappable, span: Decoration, offset: number, oldOffset: number): Decoration | null;
+  valid(_node: Node<any, any>, span: Decoration, cursor: FragmentCursor): boolean;
+  eq(other: DecorationType): boolean;
+  destroy(): void;
+}
+/**
+ * The spec of a widget decoration (see `Decoration.widget`).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface WidgetDecorationSpec {
+  /**
+   * Controls which side of the document position this widget is
+   * associated with. When negative, it is drawn before a cursor at its
+   * position, and content inserted at that position ends up after the
+   * widget. When zero (the default) or positive, the widget is drawn
+   * after the cursor and content inserted there ends up before the
+   * widget.
+   *
+   * When there are multiple widgets at a given position, their `side`
+   * values determine the order in which they appear. Those with lower
+   * values appear first. The ordering of widgets with the same `side`
+   * value is unspecified.
+   *
+   * When `marks` is null, `side` also determines the marks that the
+   * widget is wrapped in—those of the node before when negative, those
+   * of the node after when positive.
+   */
+  readonly side?: number | undefined;
+  /**
+   * By default, the cursor, when at the position of the widget, will be
+   * strictly kept on the side indicated by `side`. Set this to true to
+   * allow the DOM selection to stay on the other side if the client
+   * sets it there.
+   */
+  readonly relaxedSide?: boolean | undefined;
+  /** The precise set of marks to draw around the widget. */
+  readonly marks?: ReadonlyArray<Mark<any, any>> | undefined;
+  /**
+   * Can be used to control which DOM events, when they bubble out of
+   * this widget, the editor view should ignore.
+   */
+  readonly stopEvent?: ((event: Event) => boolean) | undefined;
+  /**
+   * When set (defaults to false), selection changes inside the widget
+   * are ignored, and don't cause the view to try and re-sync the
+   * selection with its selection state.
+   */
+  readonly ignoreSelection?: boolean | undefined;
+  /**
+   * When comparing decorations of this type (in order to decide whether
+   * it needs to be redrawn), the view will by default compare the widget
+   * DOM node by identity. If you pass a key, that key will be compared
+   * instead, which can be useful when you generate decorations on the
+   * fly and don't want to store and reuse DOM nodes. Make sure that any
+   * widgets with the same key are interchangeable.
+   */
+  readonly key?: string | undefined;
+  /** Called when the widget decoration is removed or the editor is destroyed. */
+  readonly destroy?: ((node: DOMNode) => void) | undefined;
+  /** Specs allow arbitrary additional properties. */
+  readonly [key: string]: any;
+}
+/**
+ * The spec of an inline decoration (see `Decoration.inline`).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface InlineDecorationSpec {
+  /**
+   * Determines how the left side of the decoration is mapped when
+   * content is inserted directly at that position. By default, the
+   * decoration won't include the new content, but you can set this to
+   * `true` to make it inclusive.
+   */
+  readonly inclusiveStart?: boolean | undefined;
+  /** Determines how the right side of the decoration is mapped. */
+  readonly inclusiveEnd?: boolean | undefined;
+  /** Specs may have arbitrary additional properties. */
+  readonly [key: string]: any;
+}
+/**
+ * Decoration objects can be provided to the view through the
+ * `decorations` prop. They come in several variants—see the static
+ * members of this class for details.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare class Decoration {
+  /** The start position of the decoration. */
+  readonly from: number;
+  /** The end position. Will be the same as `from` for widget decorations. */
+  readonly to: number;
+  /** @internal */
+  readonly type: DecorationType;
+  /** @internal */
+  constructor(
+  /** The start position of the decoration. */
+  from: number,
+  /** The end position. Will be the same as `from` for widget decorations. */
+  to: number,
+  /** @internal */
+  type: DecorationType);
+  /** @internal */
+  copy(from: number, to: number): Decoration;
+  /** @internal */
+  eq(other: Decoration, offset?: number): boolean;
+  /** @internal */
+  map(mapping: Mappable, offset: number, oldOffset: number): Decoration | null;
+  /**
+   * Creates a widget decoration, which is a DOM node that's shown in
+   * the document at the given position. It is recommended that you
+   * delay rendering the widget by passing a function that will be
+   * called when the widget is actually drawn in a view, but you can
+   * also directly pass a DOM node. `getPos` can be used to find the
+   * widget's current document position.
+   */
+  static widget(pos: number, toDOM: WidgetConstructor, spec?: WidgetDecorationSpec): Decoration;
+  /**
+   * Creates an inline decoration, which adds the given attributes to
+   * each inline node between `from` and `to`.
+   */
+  static inline(from: number, to: number, attrs: DecorationAttrs, spec?: InlineDecorationSpec): Decoration;
+  /**
+   * Creates a node decoration. `from` and `to` should point precisely
+   * before and after a node in the document. That node, and only that
+   * node, will receive the given attributes.
+   */
+  static node(from: number, to: number, attrs: DecorationAttrs, spec?: any): Decoration;
+  /**
+   * The spec provided when creating this decoration. Can be useful if
+   * you've stored extra information in that object.
+   */
+  get spec(): any;
+  /** @internal */
+  get inline(): boolean;
+  /** @internal */
+  get widget(): boolean;
+}
+/**
+ * A set of attributes to add to a decorated node. Most properties
+ * simply directly correspond to DOM attributes of the same name, which
+ * will be set to the property's value. These are exceptions:
+ *
+ * - `nodeName`: when non-null, the target node is wrapped in a DOM
+ *   element of this type (and the other attributes are applied to this
+ *   element).
+ * - `class`: a CSS class name or a space-separated set of class names
+ *   to be _added_ to the classes that the node already had.
+ * - `style`: a string of CSS to be _added_ to the node's existing
+ *   `style` property.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type DecorationAttrs = {
+  readonly nodeName?: string | undefined;
+  readonly class?: string | undefined;
+  readonly style?: string | undefined;
+  readonly [attribute: string]: string | undefined;
+};
+/**
+ * An object that can provide decorations. Implemented by
+ * `DecorationSet`, and passed to node views.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface DecorationSource {
+  /** Map the set of decorations in response to a change in the document. */
+  readonly map: (mapping: Mapping, node: Node<any, any>) => DecorationSource;
+  /** @internal */
+  locals(node: Node<any, any>): ReadonlyArray<Decoration>;
+  /** Extract a DecorationSource containing decorations for the given child node at the given offset. */
+  forChild(offset: number, child: Node<any, any>): DecorationSource;
+  /** @internal */
+  eq(other: DecorationSource): boolean;
+  /** Call the given function for each decoration set in the group. */
+  forEachSet(f: (set: DecorationSet) => void): void;
+}
+/**
+ * Options for `DecorationSet.map`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface DecorationMapOptions {
+  /**
+   * When given, this function will be called for each decoration that
+   * gets dropped as a result of the mapping, passing the spec of that
+   * decoration.
+   */
+  readonly onRemove?: ((decorationSpec: any) => void) | undefined;
+}
+/**
+ * A collection of decorations, organized in such a way that the
+ * drawing algorithm can efficiently use and compare them. This is a
+ * persistent data structure—it is not modified, updates create a new
+ * value.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare class DecorationSet implements DecorationSource {
+  /** @internal */
+  local: ReadonlyArray<Decoration>;
+  /** @internal */
+  children: ReadonlyArray<number | DecorationSet>;
+  /** @internal */
+  constructor(local: ReadonlyArray<Decoration>, children: ReadonlyArray<number | DecorationSet>);
+  /**
+   * Create a set of decorations, using the structure of the given
+   * document. This will consume (modify) the `decorations` array, so you
+   * must make a copy if you want need to preserve that.
+   */
+  static create(doc: Node<any, any>, decorations: Array<Decoration>): DecorationSet;
+  /**
+   * Find all decorations in this set which touch the given range
+   * (including decorations that start or end directly at the
+   * boundaries) and match the given predicate on their spec. When
+   * `start` and `end` are omitted, all decorations in the set are
+   * considered. When `predicate` isn't given, all decorations are
+   * assumed to match.
+   */
+  find(start?: number, end?: number, predicate?: (spec: any) => boolean): Array<Decoration>;
+  private findInner;
+  /** Map the set of decorations in response to a change in the document. */
+  map(mapping: Mapping, doc: Node<any, any>, options?: DecorationMapOptions): DecorationSet;
+  /** @internal */
+  mapInner(mapping: Mapping, node: Node<any, any>, offset: number, oldOffset: number, options: DecorationMapOptions): DecorationSet;
+  /**
+   * Add the given array of decorations to the ones in the set, producing
+   * a new set. Consumes the `decorations` array. Needs access to the
+   * current document to create the appropriate tree structure.
+   */
+  add(doc: Node<any, any>, decorations: Array<Decoration>): DecorationSet;
+  private addInner;
+  /**
+   * Create a new set that contains the decorations in this set, minus
+   * the ones in the given array.
+   */
+  remove(decorations: Array<Decoration>): DecorationSet;
+  private removeInner;
+  forChild(offset: number, node: Node<any, any>): DecorationSource;
+  /** @internal */
+  eq(other: DecorationSource): boolean;
+  /** @internal */
+  locals(node: Node<any, any>): ReadonlyArray<Decoration>;
+  /** @internal */
+  localsInner(node: Node<any, any>): ReadonlyArray<Decoration>;
+  /** The empty set of decorations. */
+  static empty: DecorationSet;
+  /** @internal */
+  static removeOverlap: typeof removeOverlap;
+  forEachSet(f: (set: DecorationSet) => void): void;
+}
+/** @internal */
+export declare class DecorationGroup implements DecorationSource {
+  readonly members: ReadonlyArray<DecorationSet>;
+  constructor(members: ReadonlyArray<DecorationSet>);
+  map(mapping: Mapping, doc: Node<any, any>): DecorationSource;
+  forChild(offset: number, child: Node<any, any>): DecorationSource;
+  eq(other: DecorationSource): boolean;
+  locals(node: Node<any, any>): ReadonlyArray<Decoration>;
+  static from(members: ReadonlyArray<DecorationSource>): DecorationSource;
+  forEachSet(f: (set: DecorationSet) => void): void;
+}
+declare function removeOverlap(spans: ReadonlyArray<Decoration>): Array<Decoration>;
+/**
+ * Get the decorations associated with the current props of a view.
+ *
+ * @internal
+ */
+export declare function viewDecorations(view: EditorView<any, any, any>): DecorationSource;
+export {};