@thomasfosterau/effect-richtext 0.0.0-stage → 0.1.0

package/dist/model/from_dom.d.ts

@@ -0,0 +1,299 @@
+import { ContentMatch } from "./content.js";
+import { ModelError } from "./errors.js";
+import { Fragment } from "./fragment.js";
+import { Mark } from "./mark.js";
+import { Node } from "./node.js";
+import { Slice } from "./replace.js";
+import { ResolvedPos } from "./resolvedpos.js";
+import { AnySchema, Attrs } from "./schema.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/**
+ * A DOM position whose document position should be recorded while
+ * parsing (see `ParseOptions.findPositions`).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface DOMPosition {
+  readonly node: globalThis.Node;
+  readonly offset: number;
+  pos?: number;
+}
+/**
+ * These are the options recognized by the
+ * [`parse`](#DOMParser.parse) and [`parseSlice`](#DOMParser.parseSlice)
+ * methods.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ParseOptions<Sc extends AnySchema = AnySchema> {
+  /**
+   * By default, whitespace is collapsed as per HTML's rules. Pass
+   * `true` to preserve whitespace, but normalize newlines to spaces
+   * or, if available, line break replacements, and `"full"` to
+   * preserve whitespace entirely.
+   */
+  readonly preserveWhitespace?: boolean | "full" | undefined;
+  /**
+   * When given, the parser will, beside parsing the content, record
+   * the document positions of the given DOM positions. It will do so
+   * by writing to the objects, adding a `pos` property that holds the
+   * document position. DOM positions that are not in the parsed
+   * content will not be written to.
+   */
+  readonly findPositions?: ReadonlyArray<DOMPosition> | undefined;
+  /** The child node index to start parsing from. */
+  readonly from?: number | undefined;
+  /** The child node index to stop parsing at. */
+  readonly to?: number | undefined;
+  /**
+   * By default, the content is parsed into the schema's default top
+   * node type. You can pass this option to use the type and attributes
+   * from a different node as the top container.
+   */
+  readonly topNode?: Node<Sc, any> | undefined;
+  /**
+   * Provide the starting content match that content parsed into the
+   * top node is matched against.
+   */
+  readonly topMatch?: ContentMatch | undefined;
+  /**
+   * A set of additional nodes to count as context when parsing, above
+   * the given top node.
+   */
+  readonly context?: ResolvedPos<Sc> | undefined;
+  /** @internal */
+  readonly ruleFromNode?: ((node: globalThis.Node) => Omit<TagParseRule, "tag"> | null | undefined) | undefined;
+  /** @internal */
+  readonly topOpen?: boolean | undefined;
+}
+/**
+ * Fields that may be present in both tag and style parse rules.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface GenericParseRule {
+  /**
+   * Can be used to change the order in which the parse rules in a
+   * schema are tried. Those with higher priority come first. Rules
+   * without a priority are counted as having priority 50. This
+   * property is only meaningful in a schema—when directly constructing
+   * a parser, the order of the rule array is used.
+   */
+  readonly priority?: number | undefined;
+  /**
+   * By default, when a rule matches an element or style, no further
+   * rules get a chance to match it. By setting this to `false`, you
+   * indicate that even when this rule matches, other rules that come
+   * after it should also run.
+   */
+  readonly consuming?: boolean | undefined;
+  /**
+   * When given, restricts this rule to only match when the current
+   * context—the parent nodes into which the content is being
+   * parsed—matches this expression. Should contain one or more node
+   * names or node group names followed by single or double slashes.
+   * For example `"paragraph/"` means the rule only matches when the
+   * parent node is a paragraph, `"blockquote/paragraph/"` restricts it
+   * to be in a paragraph that is inside a blockquote, and
+   * `"section//"` matches any position inside a section—a double slash
+   * matches any sequence of ancestor nodes. To allow multiple
+   * different contexts, they can be separated by a pipe (`|`)
+   * character, as in `"blockquote/|list_item/"`.
+   */
+  readonly context?: string | undefined;
+  /** The name of the mark type to wrap the matched content in. */
+  readonly mark?: string | undefined;
+  /**
+   * When true, ignore content that matches this rule. Any `<head>`,
+   * `<noscript>`, `<script>`, `<object>`, `<style>`, or `<title>` tags
+   * encountered are automatically ignored when no rules match them.
+   */
+  readonly ignore?: boolean | undefined;
+  /** When true, finding an element that matches this rule will close the current node. */
+  readonly closeParent?: boolean | undefined;
+  /** When true, ignore the node that matches this rule, but do parse its content. */
+  readonly skip?: boolean | undefined;
+  /**
+   * Attributes for the node or mark created by this rule. When
+   * `getAttrs` is provided, it takes precedence.
+   */
+  readonly attrs?: Attrs | undefined;
+}
+/**
+ * Parse rule targeting a DOM element.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface TagParseRule extends GenericParseRule {
+  /** A CSS selector describing the kind of DOM elements to match. */
+  readonly tag: string;
+  /**
+   * The namespace to match. Nodes are only matched when the namespace
+   * matches or this property is undefined.
+   */
+  readonly namespace?: string | null | undefined;
+  /**
+   * The name of the node type to create when this rule matches. Each
+   * rule should have either a `node`, `mark`, or `ignore` property
+   * (except when it appears in a node or mark spec, in which case the
+   * `node` or `mark` property will be derived from its position).
+   */
+  readonly node?: string | undefined;
+  /**
+   * A function used to compute the attributes for the node or mark
+   * created by this rule. Can also be used to describe further
+   * conditions the DOM element must match. When it returns `false`,
+   * the rule won't match. When it returns null or undefined, that is
+   * interpreted as an empty/default set of attributes.
+   */
+  readonly getAttrs?: ((node: HTMLElement) => Attrs | false | null | undefined) | undefined;
+  /**
+   * For rules that produce non-leaf nodes, by default the content of
+   * the DOM element is parsed as content of the node. If the child
+   * nodes are in a descendent node, this may be a CSS selector string
+   * that the parser must use to find the actual content element, or a
+   * function that returns the actual content element to the parser.
+   */
+  readonly contentElement?: string | HTMLElement | ((node: HTMLElement) => HTMLElement) | undefined;
+  /**
+   * Can be used to override the content of a matched node. When
+   * present, instead of parsing the node's child nodes, the result of
+   * this function is used.
+   */
+  readonly getContent?: ((node: globalThis.Node, schema: AnySchema) => Fragment<any, any>) | undefined;
+  /**
+   * Controls whether whitespace should be preserved when parsing the
+   * content inside the matched element. `false` means whitespace may
+   * be collapsed, `true` means that whitespace should be preserved but
+   * newlines normalized to spaces, and `"full"` means that newlines
+   * should also be preserved.
+   */
+  readonly preserveWhitespace?: boolean | "full" | undefined;
+}
+/**
+ * A parse rule targeting a style property.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface StyleParseRule extends GenericParseRule {
+  /**
+   * A CSS property name to match. This rule will match inline styles
+   * that list that property. May also have the form
+   * `"property=value"`, in which case the rule only matches if the
+   * property's value exactly matches the given value. (For more
+   * complicated filters, use `getAttrs` and return false to indicate
+   * that the match failed.) Rules matching styles may only produce
+   * marks, not nodes.
+   */
+  readonly style: string;
+  /** Makes `ParseRule` a discriminated union. */
+  readonly tag?: undefined;
+  /** Style rules can remove marks from the set of active marks. */
+  readonly clearMark?: ((mark: Mark<any, any>) => boolean) | undefined;
+  /**
+   * A function used to compute the attributes for the node or mark
+   * created by this rule. Called with the style's value.
+   */
+  readonly getAttrs?: ((node: string) => Attrs | false | null | undefined) | undefined;
+}
+/**
+ * A value that describes how to parse a given DOM node or inline style
+ * as a node or mark.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type ParseRule = TagParseRule | StyleParseRule;
+/**
+ * The context against which a rule's `context` restriction is
+ * checked. Parsers pass their internal parse state; when matching
+ * rules directly, a context describing the top of a fresh parse is
+ * used by default.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface RuleContext {
+  matchesContext(context: string): boolean;
+}
+/**
+ * A DOM parser represents a strategy for parsing DOM content into a
+ * document conforming to a given schema. Its behavior is defined by an
+ * array of [rules](#ParseRule).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare class DOMParser<Sc extends AnySchema = AnySchema> {
+  /** The schema into which the parser parses. */
+  readonly schema: Sc;
+  /** The set of parse rules that the parser uses, in order of precedence. */
+  readonly rules: ReadonlyArray<ParseRule>;
+  /** The tag rules of this parser, in order of precedence. */
+  readonly tags: ReadonlyArray<TagParseRule>;
+  /** The style rules of this parser, in order of precedence. */
+  readonly styles: ReadonlyArray<StyleParseRule>;
+  /** @internal */
+  readonly matchedStyles: ReadonlyArray<string>;
+  /** @internal */
+  readonly normalizeLists: boolean;
+  /**
+   * Create a parser that targets the given schema, using the given
+   * parsing rules.
+   */
+  constructor(
+  /** The schema into which the parser parses. */
+  schema: Sc,
+  /** The set of parse rules that the parser uses, in order of precedence. */
+  rules: ReadonlyArray<ParseRule>);
+  /** Parse a document from the content of a DOM node. */
+  parse(dom: globalThis.Node, options?: ParseOptions<Sc>): Effect.Effect<Node<Sc>, ModelError>;
+  /** Like `parse`, but throws a `ModelError` on failure. */
+  parseUnsafe(dom: globalThis.Node, options?: ParseOptions<Sc>): Node<Sc>;
+  /**
+   * Parses the content of the given DOM node, like
+   * [`parse`](#DOMParser.parse), and takes the same set of options.
+   * But unlike that method, which produces a whole node, this one
+   * returns a slice that is open at the sides, meaning that the schema
+   * constraints aren't applied to the start of nodes to the left of
+   * the input and the end of nodes at the end.
+   */
+  parseSlice(dom: globalThis.Node, options?: ParseOptions<Sc>): Effect.Effect<Slice<Sc>, ModelError>;
+  /** Like `parseSlice`, but throws a `ModelError` on failure. */
+  parseSliceUnsafe(dom: globalThis.Node, options?: ParseOptions<Sc>): Slice<Sc>;
+  /**
+   * Find the first tag rule (after `after`, when given) that matches
+   * the given DOM node in the given context. When the rule has a
+   * `getAttrs` function, the returned rule is a copy whose `attrs` hold
+   * the computed attributes.
+   */
+  matchTag(dom: globalThis.Node, context?: RuleContext, after?: TagParseRule): Option.Option<TagParseRule>;
+  /** @internal */
+  matchTagOrNull(dom: globalThis.Node, context: RuleContext, after?: TagParseRule): TagParseRule | null;
+  /**
+   * Find the first style rule (after `after`, when given) that matches
+   * the given style property and value in the given context.
+   */
+  matchStyle(prop: string, value: string, context?: RuleContext, after?: StyleParseRule): Option.Option<StyleParseRule>;
+  /** @internal */
+  matchStyleOrNull(prop: string, value: string, context: RuleContext, after?: StyleParseRule): StyleParseRule | null;
+  /**
+   * Gather the parse rules from a schema's node and mark specs,
+   * ordered by priority (and schema order for equal priorities). Rules
+   * without a `node`/`mark` get the name of the type they were defined
+   * on.
+   */
+  static schemaRules(schema: AnySchema): ReadonlyArray<ParseRule>;
+  /**
+   * Construct a DOM parser using the parsing rules listed in a schema's
+   * node specs, reordered by priority. The parser is cached on the
+   * schema.
+   */
+  static fromSchema<Sc extends AnySchema>(schema: Sc): DOMParser<Sc>;
+}