@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

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

@@ -1,69 +1,11 @@
 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 ProseMirrorKeyMaps from "./keymaps.d.mts";
 import type ProseMirrorPlugin from "./plugin.d.mts";
+import type { AnyObject, Brand, InexactPartial } from "#utils";
+import type ProseMirrorDropDown from "./dropdown.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.
  */
@@ -73,46 +15,49 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
    * @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;
+  constructor(schema: Schema, view: EditorView, options?: ProseMirrorMenu.ConstructionOptions);
 
   /**
    * The editor view.
+   * @remarks `defineProperty`'d in construction, and without the property existing prior, defaults to `writable: false`
    */
-  view: EditorView;
+  readonly view: EditorView;
 
   /**
    * The items configured for this menu.
+   * @remarks `defineProperty`'d in construction, and without the property existing prior, defaults to `writable: false`
    */
-  items: ProseMirrorMenu.Item[];
+  readonly items: ProseMirrorMenu.Item[];
 
   /**
    * The ID of the menu element in the DOM.
+   * @remarks `defineProperty`'d in construction, explicitly `writable: false`
    */
   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";
-  };
+  protected static _MENU_ITEM_SCOPES: ProseMirrorMenu.MenuItemScopes;
 
   /**
    * Additional options to configure the plugin's behaviour.
    */
-  options: ProseMirrorMenu.ProseMirrorMenuOptions;
+  options: ProseMirrorMenu.ConstructionOptions;
 
   /**
    * The dropdowns configured for this menu.
+   * @remarks `defineProperty`'d in {@linkcode _createDropDowns}, which is called during construction,
+   * and without the property existing prior, it defaults to `writable: false`
    */
-  dropdowns: ProseMirrorDropDown.Entry[];
+  readonly dropdowns: ProseMirrorDropDown[];
 
-  static override build(schema: Schema, options?: ProseMirrorMenu.ProseMirrorMenuOptions): Plugin;
+  /**
+   * Track whether we are currently in a state of editing the HTML source.
+   */
+  get editingSource(): boolean;
+
+  static override build(schema: Schema, options?: ProseMirrorMenu.ConstructionOptions): Plugin;
 
   /**
    * Render the menu's HTML.
@@ -129,8 +74,9 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
    * Called whenever the view's state is updated.
    * @param view      - The current editor state.
    * @param prevState - The previous editor state.
+   * @remarks Both parameters are unused
    */
-  update(view: EditorView, prevState: EditorView): void;
+  update(view?: EditorView, prevState?: EditorView): void;
 
   /**
    * Called when the view is destroyed or receives a state with different plugins.
@@ -161,14 +107,14 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
 
   /**
    * Determine whether the given menu item representing a mark is active or not.
-   * @param item - The menu item representing a {@link MarkType}.
+   * @param item - The menu item representing a {@linkcode 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}.
+   * @param item - The menu item representing a {@linkcode 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;
@@ -186,6 +132,7 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
 
   /**
    * Handle requests to save the editor contents
+   * @remarks Returns `this.options.onSave?.()`
    */
   protected _handleSave(): void;
 
@@ -214,14 +161,13 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
    * @param action   - The unique menu button action.
    * @param template - The dialog's template.
    * @param options  - Additional options to configure the dialog's behaviour.
+   * @remarks The above is misleading, there's no behavior to configure,
+   * just a place to pass a handlebars context for the template
    */
   protected _showDialog(
     action: string,
     template: string,
-    options?: {
-      /** Data to pass to the template. (default: `{}`) */
-      data: Record<string, unknown>;
-    },
+    options?: ProseMirrorMenu.ShowDialogOptions,
   ): Promise<HTMLDialogElement>;
 
   /**
@@ -242,8 +188,8 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
    */
   protected _toggleBlock(
     node: NodeType,
-    wrap: MenuToggleBlockWrapCommand,
-    options?: { /** Attributes for the node. */ attrs?: object },
+    wrap: ProseMirrorMenu.ToggleBlockWrapCommand,
+    options?: ProseMirrorMenu.ToggleBlockOptions,
   ): void;
 
   /**
@@ -251,5 +197,98 @@ declare class ProseMirrorMenu extends ProseMirrorPlugin {
    * @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;
+  protected _toggleTextBlock(node: NodeType, options?: ProseMirrorMenu.ToggleTextBlockOptions): void;
+
+  #ProseMirrorMenu: true;
+}
+
+declare namespace ProseMirrorMenu {
+  type MENU_ITEM_SCOPES = Brand<string, "ProseMirrorMenu.MENU_ITEM_SCOPES">;
+
+  interface MenuItemScopes {
+    BOTH: "" & MENU_ITEM_SCOPES;
+    TEXT: "text" & MENU_ITEM_SCOPES;
+    HTML: "html" & MENU_ITEM_SCOPES;
+  }
+
+  /** @internal */
+  type _ConstructionOptions = InexactPartial<{
+    /** 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;
+  }>;
+
+  interface ConstructionOptions extends _ConstructionOptions {}
+
+  /** @internal */
+  type _ShowDialogOptions = InexactPartial<{
+    /**
+     * Data to pass to the template.
+     * @defaultValue `{}`
+     */
+    data: AnyObject;
+  }>;
+
+  interface ShowDialogOptions extends _ShowDialogOptions {}
+
+  /** @internal */
+  type _Attrs = InexactPartial<{
+    /** Attributes for the node. */
+    attrs: Attrs;
+  }>;
+
+  interface ToggleBlockOptions extends _Attrs {}
+
+  interface ToggleTextBlockOptions extends _Attrs {}
+
+  /** @internal */
+  type _Item = InexactPartial<{
+    /** 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;
+
+    /** 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: ProseMirrorKeyMaps.Command;
+
+    /** Whether the current item is active under the given selection or cursor. (default: `false`) */
+    active: boolean;
+  }>;
+
+  interface Item extends _Item {
+    /** A string identifier for this menu item. */
+    action: string;
+
+    /** The description of the menu item. */
+    title: string;
+  }
+
+  /**
+   * @param node  - The node to wrap the selection in.
+   * @param attrs - Attributes for the node.
+   */
+  type ToggleBlockWrapCommand = (node: NodeType, attrs?: Attrs) => ProseMirrorKeyMaps.Command;
 }
+
+export default ProseMirrorMenu;

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

@@ -1,22 +1,16 @@
-import type { Schema, Slice } from "prosemirror-model";
+import type { Schema } 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 "fvtt-types/utils";
-
-export default ProseMirrorPasteTransformer;
+import type { AnyObject } from "#utils";
 
 /**
  * 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;
+  /** @remarks `options` is unused */
+  static override build(schema: Schema, options?: AnyObject): 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;
+  #ProseMirrorPasteTransformer: true;
 }
+
+export default ProseMirrorPasteTransformer;

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

@@ -1,24 +1,28 @@
 import type { Schema } from "prosemirror-model";
 import type { Plugin } from "prosemirror-state";
-import type { AnyObject } from "fvtt-types/utils";
 
-export default ProseMirrorPlugin;
 declare abstract class ProseMirrorPlugin {
   /**
    * An abstract class for building a ProseMirror Plugin.
-   * @see Plugin
+   * @see {@linkcode Plugin}
    * @param schema - The schema to build the plugin against.
    */
   constructor(schema: Schema);
 
-  /** The schema to build the plugin against. */
-  schema: Schema;
+  /**
+   * The schema to build the plugin against.
+   * @remarks `defineProperty`'d in construction, and without the property existing prior, it defaults to `writable: false`
+   */
+  readonly 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
+   * @abstract
+   * @remarks Throws if not overridden
    */
-  static build(schema: Schema, options?: AnyObject): Plugin;
+  static build(schema: Schema, options: never): Plugin;
 }
+
+export default ProseMirrorPlugin;

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

@@ -0,0 +1,16 @@
+import type AttributeCapture from "./attribute-capture.d.mts";
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. The names Foundry has chosen
+// also overlaps with other existing names, such as SettingConfig vs. ClientSetting.SettingConfig
+
+export {};
+
+// These types are only used in code that users cannot access under `foundry`
+
+type AllowedAttributeConfiguration = AttributeCapture.AllowedAttributeConfiguration;
+
+type ManagedAttributesSpec = AttributeCapture.ManagedAttributesSpec;

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

@@ -6,34 +6,35 @@ import type { DOMOutputSpec, MarkSpec, NodeSpec } from "prosemirror-model";
 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;
+
+  #AttributeCapture: true;
 }
 
 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[];
-  // }
+  interface AllowedAttributeConfiguration {
+    /** The set of exactly-matching attribute names. */
+    attrs: Set<string>;
+
+    /** A list of wildcard allowed prefixes for attributes. */
+    wildcards: string[];
+  }
+
+  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

@@ -1,51 +1,13 @@
-import { Node } from "prosemirror-model";
+import type { NodeSpec } 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 paragraph: NodeSpec;
 
-export declare const blockquote: {
-  content: string;
-  group: string;
-  defining: boolean;
-  parseDOM: Record<string, unknown>[];
-  toDOM: () => [string, number];
-};
+export declare const blockquote: NodeSpec;
 
-export declare const hr: {
-  group: string;
-  parseDOM: Record<string, unknown>[];
-  toDOM: () => [string];
-};
+export declare const hr: NodeSpec;
 
-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 heading: NodeSpec;
 
-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 pre: NodeSpec;
 
-export declare const br: {
-  inline: boolean;
-  group: string;
-  selectable: boolean;
-  parseDOM: Record<string, unknown>[];
-  toDOM: () => [string];
-};
+export declare const br: NodeSpec;

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

@@ -1,8 +1,8 @@
-import { MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type { AttributeSpec, Node, NodeSpec } from "prosemirror-model";
 import type SchemaDefinition from "./schema-definition.d.mts";
-import { EditorView } from "prosemirror-view";
-
-export default ImageLinkNode;
+import type { EditorView } from "prosemirror-view";
+import type LinkMark from "./link-mark.d.mts";
+import type ImageNode from "./image-node.d.mts";
 
 /**
  * A class responsible for encapsulating logic around image-link nodes in the ProseMirror schema.
@@ -10,13 +10,13 @@ export default ImageLinkNode;
 declare class ImageLinkNode extends SchemaDefinition {
   static override tag: "a";
 
-  static override get attrs(): Record<string, unknown>;
+  static override get attrs(): Record<string, AttributeSpec>;
 
-  static override getAttrs(el: HTMLLinkElement): boolean | Record<string, unknown>;
+  static override getAttrs(el: HTMLLinkElement): SchemaDefinition.GetAttrsReturn;
 
-  static override toDOM(node: Node): [string, unknown];
+  static override toDOM(node: Node): ImageLinkNode.ToDOMReturn;
 
-  static override make(): NodeSpec | MarkSpec;
+  static override make(): NodeSpec;
 
   /**
    * Handle clicking on image links while editing.
@@ -25,5 +25,11 @@ declare class ImageLinkNode extends SchemaDefinition {
    * @param event - The click event.
    * @param node  - The Node instance.
    */
-  static onClick(view: EditorView, pos: number, event: JQuery.ClickEvent, node: Node): boolean;
+  static onClick(view: EditorView, pos: number, event: PointerEvent, node: Node): boolean;
+}
+
+declare namespace ImageLinkNode {
+  type ToDOMReturn = [...LinkMark.ToDOMReturn, ImageNode.ToDOMReturn];
 }
+
+export default ImageLinkNode;

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

@@ -1,19 +1,23 @@
-import { MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type { AttributeSpec, Attrs, 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 get attrs(): Record<string, AttributeSpec>;
+
+  static override getAttrs(el: HTMLImageElement): SchemaDefinition.GetAttrsReturn;
 
-  static override getAttrs(el: HTMLImageElement): boolean | Record<string, unknown>;
+  static override toDOM(node: Node): ImageNode.ToDOMReturn;
 
-  static override toDOM(node: Node): [string, unknown];
+  static override make(): NodeSpec;
+}
 
-  static override make(): NodeSpec | MarkSpec;
+declare namespace ImageNode {
+  type ToDOMReturn = [string, Attrs];
 }
+
+export default ImageNode;

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

@@ -1,8 +1,6 @@
-import { Mark, MarkSpec, Node, NodeSpec } from "prosemirror-model";
+import type { Mark, MarkSpec, Node, AttributeSpec, Attrs } from "prosemirror-model";
+import type { EditorView } from "prosemirror-view";
 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.
@@ -10,21 +8,28 @@ export default LinkMark;
 declare class LinkMark extends SchemaDefinition {
   static override tag: "a";
 
-  static override get attrs(): Record<string, unknown>;
+  static override get attrs(): Record<string, AttributeSpec>;
 
-  static override getAttrs(el: HTMLLinkElement): boolean | Record<string, unknown>;
+  static override getAttrs(el: HTMLLinkElement): SchemaDefinition.GetAttrsReturn;
 
-  static override toDOM(node: Node): [string, unknown];
+  static override toDOM(node: Node): LinkMark.ToDOMReturn;
 
-  static override make(): NodeSpec | MarkSpec;
+  static override make(): 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 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.
+   * @returns Returns true to indicate the click was handled here and should not be propagated to other plugins.
+   * @remarks Really does unconditionally return `true`, return type is per Foundry
    */
-  static onClick(view: EditorView, pos: number, event: JQuery.ClickEvent, mark: Mark): boolean | void;
+  static onClick(view: EditorView, pos: number, event: PointerEvent, mark: Mark): boolean | void;
+}
+
+declare namespace LinkMark {
+  type ToDOMReturn = [string, Attrs];
 }
+
+export default LinkMark;

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

@@ -1,20 +1,8 @@
-import { Node } from "prosemirror-model";
+import type { NodeSpec } from "prosemirror-model";
 
-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 ol: NodeSpec;
 
-export declare const ul: {
-  content: string;
-  group: string;
-  parseDOM: Record<string, unknown>[];
-  toDOM: () => [string, number];
-};
+export declare const ul: NodeSpec;
 
 /**
  * ProseMirror enforces a stricter subset of HTML where block and inline content cannot be mixed. For example, the
@@ -42,16 +30,6 @@ export declare const 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 li: NodeSpec;
 
-export declare const liText: {
-  content: string;
-  defining: boolean;
-  parseDOM: Record<string, unknown>[];
-  toDOM: () => [string, number];
-};
+export declare const liText: NodeSpec;