shelving/markup/MarkupParser.d.ts

Toolkit for using data in JavaScript.

import type { ReactNode } from "react";
import type { ImmutableArray } from "../util/array.js";
import { type PossibleLink } from "../util/link.js";
import type { Nullish } from "../util/null.js";
import { type ImmutableURI, type URISchemes } from "../util/uri.js";
import type { ImmutableURL } from "../util/url.js";
import type { MarkupRule, MarkupRules } from "./MarkupRule.js";
import type { Parser } from "./Parser.js";
/** The current parsing options (represents the current state of the parsing). */
export type MarkupOptions = {
    /**
     * The active list of parsing rules.
     * @default MARKUP_RULES The default list of markup rules.
     */
    readonly rules?: MarkupRules | undefined;
    /**
     * Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`).
     * @example "nofollow ugc" // Stop user-generated content ruining our SEO juice.
     */
    readonly rel?: string | undefined;
    /**
     * Current page URL — used as the base for resolving relative refs (`./foo`, `#x`, bare segments) in link hrefs.
     */
    readonly url?: ImmutableURL | undefined;
    /**
     * Site root URL — used as the base for resolving site-absolute path hrefs (`/foo`), honoring its subfolder.
     */
    readonly root?: ImmutableURL | undefined;
    /**
     * Valid URI schemes/protocols for URLs and URIs.
     * @example ["http:", "https:"]
     * @default ["http:", "https:"]
     */
    readonly schemes?: URISchemes | undefined;
    /**
     * Default context to use if one isn't set. Defaults to `"block"`
     */
    readonly context?: string;
};
export declare class MarkupParser implements Parser<string, ReactNode> {
    /**
     * The list of parsing rules this parser applies.
     */
    readonly rules: MarkupRules;
    /**
     * Calculated list of priorities to iterate over (extracted from the rules), e.g. [10, 0, -10]
     */
    readonly priorities: ImmutableArray<number>;
    /**
     * Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`).
     * @example "nofollow ugc"
     */
    readonly rel: string | undefined;
    /**
     * Current page URL — used as the base for resolving relative refs (`./foo`, `#x`, bare segments) in link hrefs.
     * @default Falls back to `root` if not set.
     */
    readonly url: ImmutableURL | undefined;
    /**
     * Site root URL — used as the base for resolving site-absolute path hrefs (`/foo`), honoring its subfolder.
     * @default Falls back to `url` if not set.
     */
    readonly root: ImmutableURL | undefined;
    /**
     * Valid URI schemes/protocols for URLs and URIs.
     * @example ["http:", "https:"]
     * @default ["http:", "https:"]
     */
    readonly schemes: URISchemes;
    /**
     * Default context to use if one isn't set. Defaults to `"block"`
     */
    readonly context: string;
    constructor({ rules, rel, url, root, schemes, context }?: MarkupOptions);
    /**
     * Parse a text string as Markdownish markup syntax and render it as elements.
     * - Syntax is not defined by this code, but by the rules supplied to it.
     *
     * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
     * @param parser A markup parser instance.
     * @param context The context to render in (defaults to `"block"`).
     *
     * @returns A React node — an element, a string, `null`, or an array of zero or more of those.
     */
    parse(input: string, context?: string): ReactNode;
    /** Yield the rules active in `context` that sit in the given priority tier. */
    getRules(context: string, priority: number): Iterable<MarkupRule>;
    /**
     * Get a HREF link with the correct context of our `options.url` and `options.root`
     *
     * @returns `ImmutableURI` a (URL) object if the link matches and is parseable and has an allowed scheme.
     * @returns `undefined` if the link does not amtch the allowed `options.schemes`
     */
    getLink(href: Nullish<PossibleLink>): ImmutableURI | undefined;
}
/** MarkupParser sentinel with the default markup rules */
export declare const MARKUP_PARSER: MarkupParser;