@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

package/src/foundry/common/prosemirror/keymaps.d.mts

@@ -0,0 +1,47 @@
+import type { Schema } from "prosemirror-model";
+import type { EditorState, Plugin, Transaction } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+import type ProseMirrorPlugin from "./plugin.d.mts";
+
+/**
+ * @param state    - The current editor state.
+ * @param dispatch - A function to dispatch a transaction.
+ * @param view     - Escape-hatch for when the command needs to interact directly with the UI.
+ * @returns Whether the command has performed any action and consumed the event.
+ */
+export type ProseMirrorCommand = (
+  state: EditorState,
+  dispatch: (transaction: Transaction) => void,
+  view: EditorView,
+) => boolean;
+export declare namespace ProseMirrorKeyMaps {
+  export interface Options {
+    /** A function to call when Ctrl+S is pressed. */
+    onSave?: () => void;
+  }
+}
+
+export default ProseMirrorKeyMaps;
+/**
+ * A class responsible for building the keyboard commands for the ProseMirror editor.
+ */
+declare class ProseMirrorKeyMaps extends ProseMirrorPlugin {
+  /**
+   * @param schema  - The ProseMirror schema to build keymaps for.
+   * @param options - Additional options to configure the plugin's behaviour.
+   */
+  constructor(schema: Schema, options?: ProseMirrorKeyMaps.Options);
+
+  /**
+   * A function to call when Ctrl+S is pressed.
+   */
+  readonly onSave: () => void;
+
+  static override build(schema: Schema, options?: ProseMirrorKeyMaps.Options): Plugin;
+
+  /**
+   * Build keyboard commands for nodes and marks present in the schema.
+   * @returns An object of keyboard shortcuts to editor functions.
+   */
+  buildMapping(): Record<string, ProseMirrorCommand>;
+}

package/src/foundry/common/prosemirror/menu.d.mts

@@ -0,0 +1,255 @@
+import type { Attrs, MarkType, NodeType, Schema } from "prosemirror-model";
+import type { Plugin } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+import type { ProseMirrorCommand } from "./keymaps.d.mts";
+import type ProseMirrorPlugin from "./plugin.d.mts";
+
+export declare namespace ProseMirrorMenu {
+  export interface ProseMirrorMenuOptions {
+    /** A function to call when the save button is pressed. */
+    onSave?: () => void;
+    /** Whether this editor instance is intended to be destroyed when saved. */
+    destroyOnSave?: boolean;
+    /** Whether to display a more compact version of the menu. */
+    compact?: boolean;
+  }
+
+  export interface Item {
+    /** A string identifier for this menu item. */
+    action: string;
+    /** The description of the menu item. */
+    title: string;
+    /** An optional class to apply to the menu item. */
+    class?: string;
+    /** An optional style to apply to the title text. */
+    style?: string;
+    /** The menu item's icon HTML. */
+    icon?: string;
+    /** The mark to apply to the selected text. */
+    mark?: MarkType;
+    /** The node to wrap the selected text in. */
+    node?: NodeType;
+    /** An object of attributes for the node or mark. */
+    attrs?: Attrs; //object
+    /** A numeric priority which determines whether this item is displayed as the dropdown title. Lower priority takes precedence. */
+    priority?: number;
+    /** The command to run when the menu item is clicked. */
+    cmd?: ProseMirrorCommand;
+    /** Whether the current item is active under the given selection or cursor. (default: `false`) */
+    active?: boolean;
+  }
+}
+
+// It's here, as defined, but it should probably be put in dropdown.d.ts
+export declare namespace ProseMirrorDropDown {
+  export interface Entry extends ProseMirrorMenu.Item {
+    /** Any child entries. */
+    children?: Entry[];
+  }
+
+  export interface Config {
+    /** The default title of the drop-down. */
+    title: string;
+    /** The menu CSS class. */
+    cssClass: string;
+    /** The drop-down entries. */
+    entries: Entry[];
+  }
+}
+
+/**
+ * @param node  - The node to wrap the selection in.
+ * @param attrs - Attributes for the node.
+ */
+export type MenuToggleBlockWrapCommand = (node: NodeType, attrs?: Attrs) => ProseMirrorCommand;
+
+export default ProseMirrorMenu;
+/**
+ * A class responsible for building a menu for a ProseMirror instance.
+ */
+declare class ProseMirrorMenu extends ProseMirrorPlugin {
+  /**
+   * @param schema  - The ProseMirror schema to build a menu for.
+   * @param view    - The editor view.
+   * @param options - Additional options to configure the plugin's behaviour.
+   */
+  constructor(schema: Schema, view: EditorView, options?: ProseMirrorMenu.ProseMirrorMenuOptions);
+
+  // placeholder private attribute to support subclassing.
+  #proseMirrorMenu: true;
+
+  /**
+   * The editor view.
+   */
+  view: EditorView;
+
+  /**
+   * The items configured for this menu.
+   */
+  items: ProseMirrorMenu.Item[];
+
+  /**
+   * The ID of the menu element in the DOM.
+   */
+  readonly id: `prosemirror-menu-${string}`;
+
+  /**
+   * An enumeration of editor scopes in which a menu item can appear
+   */
+  protected static _MENU_ITEM_SCOPES: {
+    BOTH: "";
+    TEXT: "text";
+    HTML: "html";
+  };
+
+  /**
+   * Additional options to configure the plugin's behaviour.
+   */
+  options: ProseMirrorMenu.ProseMirrorMenuOptions;
+
+  /**
+   * The dropdowns configured for this menu.
+   */
+  dropdowns: ProseMirrorDropDown.Entry[];
+
+  static override build(schema: Schema, options?: ProseMirrorMenu.ProseMirrorMenuOptions): Plugin;
+
+  /**
+   * Render the menu's HTML.
+   */
+  render(): this;
+
+  /**
+   * Attach event listeners.
+   * @param html - The root menu element.
+   */
+  activateListeners(html: HTMLMenuElement): void;
+
+  /**
+   * Called whenever the view's state is updated.
+   * @param view      - The current editor state.
+   * @param prevState - The previous editor state.
+   */
+  update(view: EditorView, prevState: EditorView): void;
+
+  /**
+   * Called when the view is destroyed or receives a state with different plugins.
+   */
+  destroy(): void;
+
+  /**
+   * Instantiate the ProseMirrorDropDown instances and configure them with the defined menu items.
+   */
+  protected _createDropDowns(): void;
+
+  /**
+   * Configure dropdowns for this menu. Each entry in the top-level array corresponds to a separate drop-down.
+   */
+  protected _getDropDownMenus(): Record<string, ProseMirrorDropDown.Config>;
+
+  /**
+   * Configure the items for this menu.
+   */
+  protected _getMenuItems(): ProseMirrorMenu.Item[];
+
+  /**
+   * Determine whether the given menu item is currently active or not.
+   * @param item - The menu item.
+   * @returns Whether the cursor or selection is in a state represented by the given menu item.
+   */
+  protected _isItemActive(item: ProseMirrorMenu.Item): boolean;
+
+  /**
+   * Determine whether the given menu item representing a mark is active or not.
+   * @param item - The menu item representing a {@link MarkType}.
+   * @returns Whether the cursor or selection is in a state represented by the given mark.
+   */
+  protected _isMarkActive(item: ProseMirrorMenu.Item): boolean;
+
+  /**
+   * Determine whether the given menu item representing a node is active or not.
+   * @param item - The menu item representing a {@link NodeType}.
+   * @returns Whether the cursor or selection is currently within a block of this menu item's node type.
+   */
+  protected _isNodeActive(item: ProseMirrorMenu.Item): boolean;
+
+  /**
+   * Handle a button press.
+   * @param event - The click event.
+   */
+  protected _onAction(event: MouseEvent): void;
+
+  /**
+   * Wrap the editor view element and inject our template ready to be rendered into.
+   */
+  protected _wrapEditor(): void;
+
+  /**
+   * Handle requests to save the editor contents
+   */
+  protected _handleSave(): void;
+
+  /**
+   * Global listeners for the drop-down menu.
+   */
+  static eventListeners(): void;
+
+  /**
+   * Display the insert image prompt.
+   */
+  protected _insertImagePrompt(): Promise<void>;
+
+  /**
+   * Display the insert link prompt.
+   */
+  protected _insertLinkPrompt(): Promise<void>;
+
+  /**
+   * Display the insert table prompt.
+   */
+  protected _insertTablePrompt(): Promise<void>;
+
+  /**
+   * Create a dialog for a menu button.
+   * @param action   - The unique menu button action.
+   * @param template - The dialog's template.
+   * @param options  - Additional options to configure the dialog's behaviour.
+   */
+  protected _showDialog(
+    action: string,
+    template: string,
+    options?: {
+      /** Data to pass to the template. (default: `{}`) */
+      data: Record<string, unknown>;
+    },
+  ): Promise<HTMLDialogElement>;
+
+  /**
+   * Clear any marks from the current selection.
+   */
+  protected _clearFormatting(): void;
+
+  /**
+   * Toggle link recommendations
+   */
+  protected _toggleMatches(): Promise<void>;
+
+  /**
+   * Toggle the given selection by wrapping it in a given block or lifting it out of one.
+   * @param node    - The type of node being interacted with.
+   * @param wrap    - The wrap command specific to the given node.
+   * @param options - Additional options to configure behaviour.
+   */
+  protected _toggleBlock(
+    node: NodeType,
+    wrap: MenuToggleBlockWrapCommand,
+    options?: { /** Attributes for the node. */ attrs?: object },
+  ): void;
+
+  /**
+   * Toggle the given selection by wrapping it in a given text block, or reverting to a paragraph block.
+   * @param node    - The type of node being interacted with.
+   * @param options - Additional options to configure behaviour.
+   */
+  protected _toggleTextBlock(node: NodeType, options?: { /** Attributes for the node. */ attrs?: object }): void;
+}

package/src/foundry/common/prosemirror/paste-transformer.d.mts

@@ -0,0 +1,22 @@
+import type { Schema, Slice } from "prosemirror-model";
+import type ProseMirrorPlugin from "./plugin.d.mts";
+import type { Plugin } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+import type { EmptyObject } from "../../../types/utils.d.mts";
+
+export default ProseMirrorPasteTransformer;
+
+/**
+ * A class responsible for applying transformations to content pasted inside the editor.
+ */
+declare class ProseMirrorPasteTransformer extends ProseMirrorPlugin {
+  static override build(schema: Schema, options?: EmptyObject): Plugin;
+
+  /**
+   * Transform content before it is injected into the ProseMirror document.
+   * @param slice - The content slice.
+   * @param view  - The ProseMirror editor view.
+   * @returns The transformed content.
+   */
+  _onPaste(slice: Slice, view: EditorView): Slice;
+}

package/src/foundry/common/prosemirror/plugin.d.mts

@@ -0,0 +1,24 @@
+import type { Schema } from "prosemirror-model";
+import type { Plugin } from "prosemirror-state";
+import type { AnyObject } from "../../../types/utils.d.mts";
+
+export default ProseMirrorPlugin;
+declare abstract class ProseMirrorPlugin {
+  /**
+   * An abstract class for building a ProseMirror Plugin.
+   * @see Plugin
+   * @param schema - The schema to build the plugin against.
+   */
+  constructor(schema: Schema);
+
+  /** The schema to build the plugin against. */
+  schema: Schema;
+
+  /**
+   * Build the plugin.
+   * @param schema - The ProseMirror schema to build the plugin against.
+   * @param options - Additional options to pass to the plugin.
+   * @virtual
+   */
+  static build(schema: Schema, options?: AnyObject): Plugin;
+}

package/src/foundry/common/prosemirror/schema/attribute-capture.d.mts

@@ -0,0 +1,39 @@
+import type { DOMOutputSpec, MarkSpec, NodeSpec } from "prosemirror-model";
+
+/**
+ * A class responsible for injecting attribute capture logic into the ProseMirror schema.
+ */
+declare class AttributeCapture {
+  constructor();
+
+  // placeholder for subclassing
+  #attributeCapture: true;
+
+  /**
+   * Augments the schema definition to allow each node or mark to capture all the attributes
+   * on an element and preserve them when re-serialized back into the DOM.
+   * @param spec - The schema specification
+   */
+  attributeCapture(spec: NodeSpec | MarkSpec): DOMOutputSpec;
+}
+
+declare namespace AttributeCapture {
+  // only used in truly private methods
+  // interface AllowedAttributeConfiguration {
+  //   /**  The set of exactly-matching attribute names. **/
+  //   attrs: Set<string>;
+  //   /** A list of wildcard allowed prefixes for attributes. **/
+  //   wildcards: string[];
+  // }
+  // only used in truly private methods
+  // interface ManagedAttributesSpec {
+  //   /**  A list of managed attributes. */
+  //   attributes: string[];
+  //   /**  A list of CSS property names that are managed as inline styles. */
+  //   styles: string[];
+  //   /**  A list of managed class names. */
+  //   classes: string[];
+  // }
+}
+
+export default AttributeCapture;

package/src/foundry/common/prosemirror/schema/core.d.mts

@@ -0,0 +1,51 @@
+import { Node } from "prosemirror-model";
+
+export declare const paragraph: {
+  attrs: Record<string, unknown>;
+  managed: Record<string, unknown>;
+  content: string;
+  group: string;
+  parseDOM: Record<string, unknown>[];
+  toDOM: (node: Node) => [string, Record<string, string>, number] | [string, number];
+};
+
+export declare const blockquote: {
+  content: string;
+  group: string;
+  defining: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const hr: {
+  group: string;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string];
+};
+
+export declare const heading: {
+  attrs: Record<string, unknown>;
+  content: string;
+  group: string;
+  defining: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: (node: Node) => [string, number];
+};
+
+export declare const pre: {
+  content: string;
+  marks: string;
+  group: string;
+  code: boolean;
+  defining: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, [string, number]];
+};
+
+export declare const br: {
+  inline: boolean;
+  group: string;
+  selectable: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string];
+};

package/src/foundry/common/prosemirror/schema/image-link-node.d.mts

@@ -0,0 +1,29 @@
+import { MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type SchemaDefinition from "./schema-definition.d.mts";
+import { EditorView } from "prosemirror-view";
+
+export default ImageLinkNode;
+
+/**
+ * A class responsible for encapsulating logic around image-link nodes in the ProseMirror schema.
+ */
+declare class ImageLinkNode extends SchemaDefinition {
+  static override tag: "a";
+
+  static override get attrs(): Record<string, unknown>;
+
+  static override getAttrs(el: HTMLLinkElement): boolean | Record<string, unknown>;
+
+  static override toDOM(node: Node): [string, unknown];
+
+  static override make(): NodeSpec | MarkSpec;
+
+  /**
+   * Handle clicking on image links while editing.
+   * @param view  - The ProseMirror editor view.
+   * @param pos   - The position in the ProseMirror document that the click occurred at.
+   * @param event - The click event.
+   * @param node  - The Node instance.
+   */
+  static onClick(view: EditorView, pos: number, event: JQuery.ClickEvent, node: Node): boolean;
+}

package/src/foundry/common/prosemirror/schema/image-node.d.mts

@@ -0,0 +1,19 @@
+import { MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type SchemaDefinition from "./schema-definition.d.mts";
+
+export default ImageNode;
+
+/**
+ * A class responsible for encapsulating logic around image nodes in the ProseMirror schema.
+ */
+declare class ImageNode extends SchemaDefinition {
+  static override tag: "img[src]";
+
+  static override get attrs(): Record<string, unknown>;
+
+  static override getAttrs(el: HTMLImageElement): boolean | Record<string, unknown>;
+
+  static override toDOM(node: Node): [string, unknown];
+
+  static override make(): NodeSpec | MarkSpec;
+}

package/src/foundry/common/prosemirror/schema/index.d.mts

@@ -0,0 +1,12 @@
+import "./attribute-capture.d.mts";
+import "./core.d.mts";
+import "./image-link-node.d.mts";
+import "./image-node.d.mts";
+import "./link-mark.d.mts";
+import "./lists.d.mts";
+import "./marks.d.mts";
+import "./other.d.mts";
+import "./schema-definition.d.mts";
+import "./secret-node.d.mts";
+import "./tables.d.mts";
+import "./utils.d.mts";

package/src/foundry/common/prosemirror/schema/link-mark.d.mts

@@ -0,0 +1,30 @@
+import { Mark, MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type SchemaDefinition from "./schema-definition.d.mts";
+import { EditorView } from "prosemirror-view";
+
+export default LinkMark;
+
+/**
+ * A class responsible for encapsulating logic around link marks in the ProseMirror schema.
+ */
+declare class LinkMark extends SchemaDefinition {
+  static override tag: "a";
+
+  static override get attrs(): Record<string, unknown>;
+
+  static override getAttrs(el: HTMLLinkElement): boolean | Record<string, unknown>;
+
+  static override toDOM(node: Node): [string, unknown];
+
+  static override make(): NodeSpec | MarkSpec;
+
+  /**
+   * Handle clicks on link marks while editing.
+   * @param view  - The ProseMirror editor view.
+   * @param pos   - The position in the ProseMirror document that the click occurred at.
+   * @param event - The click event
+   * @param mark  - The Mark instance.
+   * @returns Returns true to indicate the click was handled here and should not be propogated to other plugins.
+   */
+  static onClick(view: EditorView, pos: number, event: JQuery.ClickEvent, mark: Mark): boolean | void;
+}

package/src/foundry/common/prosemirror/schema/lists.d.mts

@@ -0,0 +1,55 @@
+export declare const ol: {
+  content: string;
+  managed: Record<string, unknown>;
+  group: string;
+  attrs: Record<string, unknown>;
+  parseDOM: Record<string, unknown>[];
+  toDOM: (node: Node) => [string, number] | [string, Record<string, unknown>, number];
+};
+
+export declare const ul: {
+  content: string;
+  group: string;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+/**
+ * ProseMirror enforces a stricter subset of HTML where block and inline content cannot be mixed. For example, the
+ * following is valid HTML:
+ * <ul>
+ *   <li>
+ *     The first list item.
+ *     <ul>
+ *       <li>An embedded list.</li>
+ *     </ul>
+ *   </li>
+ * </ul>
+ *
+ * But, since the contents of the <li> would mix inline content (the text), with block content (the inner <ul>), the
+ * schema is defined to only allow block content, and would transform the items to look like this:
+ * <ul>
+ *   <li>
+ *     <p>The first list item.</p>
+ *     <ul>
+ *       <li><p>An embedded list.</p></li>
+ *     </ul>
+ *   </li>
+ * </ul>
+ *
+ * We can address this by hooking into the DOM parsing and 'tagging' the extra paragraph elements inserted this way so
+ * that when the contents are serialized again, they can be removed. This is left as a TODO for now.
+ */
+export declare const li: {
+  content: string;
+  defining: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const liText: {
+  content: string;
+  defining: boolean;
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};

package/src/foundry/common/prosemirror/schema/marks.d.mts

@@ -0,0 +1,44 @@
+export declare const em: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const strong: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const code: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const underline: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, Record<string, string>, number];
+};
+
+export declare const strikethrough: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const superscript: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const subscript: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const span: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, number];
+};
+
+export declare const font: {
+  parseDOM: Record<string, unknown>[];
+  toDOM: () => [string, Record<string, string>];
+};