shelving 1.236.0 → 1.236.2

package/markup/MarkupParser.js

@@ -1,40 +1,65 @@
 import { getLink } from "../util/link.js";
 import { HTTP_SCHEMES } from "../util/uri.js";
 import { MARKUP_RULES } from "./rule/index.js";
+/**
+ * Parses a Markdownish markup string and renders it as a React node using a tiered, masking rule engine.
+ * - The syntax isn't hardcoded — it's defined entirely by the `rules` supplied (defaults to `MARKUP_RULES`).
+ * - Rules are grouped into priority tiers and resolved highest tier first; a claimed region is masked so lower-priority rules can't match into or across it.
+ * - Rules own the recursion into their own children by calling `parse()` again, optionally with a different context.
+ *
+ * @example
+ * const node = new MarkupParser().parse("This is a *bold* string.");
+ * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
+ */
 export class MarkupParser {
     /**
      * The list of parsing rules this parser applies.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/rules
      */
     rules;
     /**
      * Calculated list of priorities to iterate over (extracted from the rules), e.g. [10, 0, -10]
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/priorities
      */
     priorities;
     /**
      * Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`).
      * @example "nofollow ugc"
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/rel
      */
     rel;
     /**
      * 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.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/url
      */
     url;
     /**
      * 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.
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/root
      */
     root;
     /**
      * Valid URI schemes/protocols for URLs and URIs.
      * @example ["http:", "https:"]
      * @default ["http:", "https:"]
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/schemes
      */
     schemes;
     /**
      * Default context to use if one isn't set. Defaults to `"block"`
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/context
      */
     context;
+    /**
+     * Create a new `MarkupParser` from a set of options.
+     *
+     * @param options Options configuring the rules, link resolution, and default context (all optional).
+     * @returns A `MarkupParser` instance.
+     * @example new MarkupParser({ rel: "nofollow ugc" })
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
+     */
     constructor({ rules = MARKUP_RULES, rel, url, root, schemes = HTTP_SCHEMES, context = "block" } = {}) {
         this.rules = rules;
         this.priorities = _getPriorities(rules);
@@ -45,30 +70,40 @@ export class MarkupParser {
         this.context = context;
     }
     /**
-     * Parse a text string as Markdownish markup syntax and render it as elements.
+     * Parse a text string as Markdownish markup syntax and render it as a React node.
      * - 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 input The string content possibly containing markup syntax, e.g. `"This is a *bold* string."`.
      * @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.
+     * @example new MarkupParser().parse("This is a *bold* string.")
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/parse
      */
     parse(input, context = "block") {
         const nodes = _parseNodes(input, this, context);
         return !nodes.length ? null : nodes.length === 1 ? nodes[0] : nodes;
     }
-    /** Yield the rules active in `context` that sit in the given priority tier. */
+    /**
+     * Yield the rules active in `context` that sit in the given priority tier.
+     *
+     * @param context The render context to filter rules by (e.g. `"block"`, `"inline"`).
+     * @param priority The priority tier to filter rules by.
+     * @returns An iterable of the matching `MarkupRule` instances.
+     * @example for (const rule of parser.getRules("block", 0)) { ... }
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/getRules
+     */
     *getRules(context, priority) {
         for (const r of this.rules)
             if (r.priority === priority && r.contexts.includes(context))
                 yield r;
     }
     /**
-     * Get a HREF link with the correct context of our `options.url` and `options.root`
+     * Resolve a link href against this parser's `url` and `root`, returning it only if its scheme is allowed.
      *
-     * @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`
+     * @param href The raw link reference to resolve (relative or absolute), or a nullish value.
+     * @returns An `ImmutableURI` if the link parses and its scheme is in `schemes`, otherwise `undefined`.
+     * @example parser.getLink("/about") // ImmutableURI | undefined
+     * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser/getLink
      */
     getLink(href) {
         const link = getLink(href, this.url, this.root);
@@ -250,5 +285,11 @@ function _mask(text, start, end) {
         blanked += text[i] === "\n" ? "\n" : _MASK_CHAR;
     return `${text.slice(0, start)}${blanked}${text.slice(end)}`;
 }
-/** MarkupParser sentinel with the default markup rules */
+/**
+ * Shared `MarkupParser` instance configured with the default markup rules and behaviour.
+ * - Use this singleton when no custom rules, link resolution, or default context are needed.
+ *
+ * @example MARKUP_PARSER.parse("This is a *bold* string.")
+ * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MARKUP_PARSER
+ */
 export const MARKUP_PARSER = new MarkupParser();

package/markup/MarkupRule.d.ts

@@ -2,7 +2,19 @@ import type { ReactElement } from "react";
 import type { EmptyDictionary } from "../util/dictionary.js";
 import type { NamedRegExp, NamedRegExpData } from "../util/regexp.js";
 import type { MarkupParser } from "./MarkupParser.js";
+/**
+ * One or more named contexts a markup rule renders in (e.g. `["block"]`, `["inline", "list", "link"]`).
+ *
+ * @see https://dhoulb.github.io/shelving/markup/MarkupRule/MarkupContexts
+ */
 export type MarkupContexts = [string, ...string[]];
+/**
+ * A single markup rule: a regular expression that matches a span of input plus a renderer that turns the match into an element.
+ * - Rules are grouped into priority tiers and resolved highest tier first by `MarkupParser`.
+ * - A rule renders only in the contexts it lists, letting the same syntax behave differently in block vs inline vs list context.
+ *
+ * @see https://dhoulb.github.io/shelving/markup/MarkupRule/MarkupRule
+ */
 export interface MarkupRule {
     /** Regular expression used for matching the rule. */
     regexp: RegExp;
@@ -13,7 +25,28 @@ export interface MarkupRule {
     /** Priority for this rule (higher priority rules override lower priority rules). */
     priority: number;
 }
+/**
+ * An immutable list of `MarkupRule` instances applied by a `MarkupParser`.
+ *
+ * @see https://dhoulb.github.io/shelving/markup/MarkupRule/MarkupRules
+ */
 export type MarkupRules = readonly MarkupRule[];
-/** Helper to make it easier to create typed `MarkupRule` instances using `NamedRegExp` regular expressions. */
+/**
+ * Create a typed `MarkupRule` from a `NamedRegExp`, a renderer, its contexts, and an optional priority.
+ *
+ * *Factory for `MarkupRule`.*
+ *
+ * - The overload taking a `NamedRegExp<T>` infers the named capture groups handed to `render`.
+ * - Higher `priority` rules are resolved (and masked) before lower-priority ones.
+ *
+ * @param regexp Regular expression used to match the rule (a `NamedRegExp` to type the render data).
+ * @param render Renderer turning a `key`, the matched `data`, and the active `parser` into a `ReactElement`.
+ * @param contexts One or more contexts this rule renders in (e.g. `["block"]`).
+ * @param priority Tier priority — higher rules override lower ones (defaults to `0`).
+ * @returns A `MarkupRule` ready to add to a `MarkupRules` list.
+ * @example
+ * const HR_RULE = createMarkupRule(/^---$/m, key => <hr key={key} />, ["block"]);
+ * @see https://dhoulb.github.io/shelving/markup/MarkupRule/createMarkupRule
+ */
 export declare function createMarkupRule<T extends NamedRegExpData>(regexp: NamedRegExp<T>, render: (key: string, data: T, parser: MarkupParser) => ReactElement, contexts: MarkupContexts, priority?: number): MarkupRule;
 export declare function createMarkupRule(regexp: RegExp, render: (key: string, data: EmptyDictionary, parser: MarkupParser) => ReactElement, contexts: MarkupContexts, priority?: number): MarkupRule;

package/markup/Parser.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Base class for a parser that converts an input of type `I` into an output of type `O`.
+ * - Subclasses implement `parse()` to define the actual transformation.
+ * - `MarkupParser` is the canonical implementation — it parses a markup string into a React node.
+ *
+ * @example
+ * class UppercaseParser extends Parser<string, string> {
+ * 	parse(input: string): string { return input.toUpperCase(); }
+ * }
+ * @see https://dhoulb.github.io/shelving/markup/Parser/Parser
+ */
 export declare abstract class Parser<I, O> {
+    /**
+     * Parse an input value into an output value.
+     *
+     * @param input The input value to parse.
+     * @returns The parsed output value.
+     * @see https://dhoulb.github.io/shelving/markup/Parser/Parser/parse
+     */
     abstract parse(input: I): O;
 }

package/markup/Parser.js

@@ -1,2 +1,13 @@
+/**
+ * Base class for a parser that converts an input of type `I` into an output of type `O`.
+ * - Subclasses implement `parse()` to define the actual transformation.
+ * - `MarkupParser` is the canonical implementation — it parses a markup string into a React node.
+ *
+ * @example
+ * class UppercaseParser extends Parser<string, string> {
+ * 	parse(input: string): string { return input.toUpperCase(); }
+ * }
+ * @see https://dhoulb.github.io/shelving/markup/Parser/Parser
+ */
 export class Parser {
 }

package/markup/rule/blockquote.d.ts

@@ -3,5 +3,8 @@
  * - `>` quote character followed by zero or more spaces.
  * - No spaces can appear before the `>` quote character.
  * - Quote block is only broken by `\n\n` two newline characters.
+ *
+ * @example new MarkupParser({ rules: [BLOCKQUOTE_RULE] }).parse("> Quoted text")
+ * @see https://dhoulb.github.io/shelving/markup/rule/blockquote/BLOCKQUOTE_RULE
  */
 export declare const BLOCKQUOTE_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/blockquote.js

@@ -8,5 +8,8 @@ const INDENT = new RegExp(`^${PREFIX}`, "gm");
  * - `>` quote character followed by zero or more spaces.
  * - No spaces can appear before the `>` quote character.
  * - Quote block is only broken by `\n\n` two newline characters.
+ *
+ * @example new MarkupParser({ rules: [BLOCKQUOTE_RULE] }).parse("> Quoted text")
+ * @see https://dhoulb.github.io/shelving/markup/rule/blockquote/BLOCKQUOTE_RULE
  */
 export const BLOCKQUOTE_RULE = createMarkupRule(createBlockRegExp(`(?<quote>${PREFIX}${BLOCK_CONTENT_REGEXP})`), (key, { quote }, parser) => _jsx("blockquote", { children: parser.parse(quote.replace(INDENT, ""), "block") }, key), ["block", "list"]);

package/markup/rule/code.d.ts

@@ -5,5 +5,8 @@
  * - Closing characters must exactly match opening characters.
  * - Works inside link text too, e.g. `` [`code`](url) ``.
  * - Same as Markdown syntax.
+ *
+ * @example new MarkupParser({ rules: [CODE_RULE] }).parse("Some `inline code` here")
+ * @see https://dhoulb.github.io/shelving/markup/rule/code/CODE_RULE
  */
 export declare const CODE_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/code.js

@@ -9,6 +9,9 @@ import { BLOCK_CONTENT_REGEXP } from "../util/regexp.js";
  * - Closing characters must exactly match opening characters.
  * - Works inside link text too, e.g. `` [`code`](url) ``.
  * - Same as Markdown syntax.
+ *
+ * @example new MarkupParser({ rules: [CODE_RULE] }).parse("Some `inline code` here")
+ * @see https://dhoulb.github.io/shelving/markup/rule/code/CODE_RULE
  */
 // Priority 10: code is a higher-precedence tier, resolved and masked before links/emphasis, so a
 // code span that straddles a link delimiter wins and the link cannot form across it.

package/markup/rule/fenced.d.ts

@@ -6,5 +6,8 @@
  * - Closing fence must be exactly the same as the opening fence, and can be made of three or more "```" backticks, or three or more `~~~` tildes.
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
+ *
+ * @example new MarkupParser({ rules: [FENCED_RULE] }).parse("```\ncode block\n```")
+ * @see https://dhoulb.github.io/shelving/markup/rule/fenced/FENCED_RULE
  */
 export declare const FENCED_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/fenced.js

@@ -10,6 +10,9 @@ const FENCE = "`{3,}|~{3,}";
  * - Closing fence must be exactly the same as the opening fence, and can be made of three or more "```" backticks, or three or more `~~~` tildes.
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
+ *
+ * @example new MarkupParser({ rules: [FENCED_RULE] }).parse("```\ncode block\n```")
+ * @see https://dhoulb.github.io/shelving/markup/rule/fenced/FENCED_RULE
  */
 export const FENCED_RULE = createMarkupRule(createBlockRegExp(`(?<code>${BLOCK_CONTENT_REGEXP})`, `${BLOCK_START_REGEXP}(?<fence>${FENCE}) *(?<title>${LINE_CONTENT_REGEXP})\n`, // Starts with the fence
 `(?:${LINE_SPACE_REGEXP}*\n\\k<fence>(?:\\s*\\n)?|$)`), (key, { title, code }) => {

package/markup/rule/heading.d.ts

@@ -3,5 +3,8 @@
  * - `#` 1-6 hashes, then one or more spaces, then the title.
  * - `#` must be the first character on the line.
  * - Markdown's underline syntax is not supported (for simplification).
+ *
+ * @example new MarkupParser({ rules: [HEADING_RULE] }).parse("# Title")
+ * @see https://dhoulb.github.io/shelving/markup/rule/heading/HEADING_RULE
  */
 export declare const HEADING_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/heading.js

@@ -6,6 +6,9 @@ import { createLineRegExp, LINE_CONTENT_REGEXP, LINE_SPACE_REGEXP } from "../uti
  * - `#` 1-6 hashes, then one or more spaces, then the title.
  * - `#` must be the first character on the line.
  * - Markdown's underline syntax is not supported (for simplification).
+ *
+ * @example new MarkupParser({ rules: [HEADING_RULE] }).parse("# Title")
+ * @see https://dhoulb.github.io/shelving/markup/rule/heading/HEADING_RULE
  */
 export const HEADING_RULE = createMarkupRule(createLineRegExp(`(?<prefix>#{1,6})(?:${LINE_SPACE_REGEXP}+(?<heading>${LINE_CONTENT_REGEXP}))?`), (key, { prefix, heading = "" }, parser) => {
     // The hash count picks the heading level; cast the dynamic tag to the known `h1`–`h6` set.

package/markup/rule/index.d.ts

@@ -1,15 +1,28 @@
 import type { MarkupRules } from "../MarkupRule.js";
-/** Markup rules that work in a block context. */
+/**
+ * Default markup rules that render in a block context — fenced code, headings, separators, lists, blockquotes, tables, and paragraphs.
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES_BLOCK })
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES_BLOCK
+ */
 export declare const MARKUP_RULES_BLOCK: MarkupRules;
-/** Markup rules that work in an inline context. */
+/**
+ * Default markup rules that render in an inline context — inline code, links, autolinks, emphasis, and hard linebreaks.
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES_INLINE })
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES_INLINE
+ */
 export declare const MARKUP_RULES_INLINE: MarkupRules;
 /**
- * Default markup rules
+ * Default markup rules — the combined block and inline rules `MarkupParser` uses when none are supplied.
  *
  * These rules define a syntax similar to Markdown but with improvements:
  * 1. Syntax is more intuitive (e.g. `*strong*` always uses `*` asterisk and `_em_` always uses `_` underscore, and URLs are always autolinked).
  * 2. More compatible with textboxes that wrap lines by default (e.g. single `\n` linebreaks don't need the trailing double space to, they're always treated as `<br />`).
  * 3. Don't support fussy fragile syntax that lets users make mistakes (e.g. literal HTML tags or `&amp;` character entities).
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES }).parse("This is a *bold* string.")
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES
  */
 export declare const MARKUP_RULES: MarkupRules;
 export * from "./blockquote.js";

package/markup/rule/index.js

@@ -10,7 +10,12 @@ import { PARAGRAPH_RULE } from "./paragraph.js";
 import { SEPARATOR_RULE } from "./separator.js";
 import { TABLE_RULE } from "./table.js";
 import { UNORDERED_RULE } from "./unordered.js";
-/** Markup rules that work in a block context. */
+/**
+ * Default markup rules that render in a block context — fenced code, headings, separators, lists, blockquotes, tables, and paragraphs.
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES_BLOCK })
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES_BLOCK
+ */
 export const MARKUP_RULES_BLOCK = [
     FENCED_RULE,
     HEADING_RULE,
@@ -21,7 +26,12 @@ export const MARKUP_RULES_BLOCK = [
     TABLE_RULE,
     PARAGRAPH_RULE,
 ];
-/** Markup rules that work in an inline context. */
+/**
+ * Default markup rules that render in an inline context — inline code, links, autolinks, emphasis, and hard linebreaks.
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES_INLINE })
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES_INLINE
+ */
 export const MARKUP_RULES_INLINE = [
     CODE_RULE, //
     LINK_RULE,
@@ -30,12 +40,15 @@ export const MARKUP_RULES_INLINE = [
     LINEBREAK_RULE,
 ];
 /**
- * Default markup rules
+ * Default markup rules — the combined block and inline rules `MarkupParser` uses when none are supplied.
  *
  * These rules define a syntax similar to Markdown but with improvements:
  * 1. Syntax is more intuitive (e.g. `*strong*` always uses `*` asterisk and `_em_` always uses `_` underscore, and URLs are always autolinked).
  * 2. More compatible with textboxes that wrap lines by default (e.g. single `\n` linebreaks don't need the trailing double space to, they're always treated as `<br />`).
  * 3. Don't support fussy fragile syntax that lets users make mistakes (e.g. literal HTML tags or `&amp;` character entities).
+ *
+ * @example new MarkupParser({ rules: MARKUP_RULES }).parse("This is a *bold* string.")
+ * @see https://dhoulb.github.io/shelving/markup/rule/MARKUP_RULES
  */
 export const MARKUP_RULES = [
     ...MARKUP_RULES_BLOCK, //

package/markup/rule/inline.d.ts

@@ -3,12 +3,15 @@
  * - Inline strong text wrapped in one or more `*` asterisks.
  * - Inline emphasis text wrapped in one or more `_` underscores.
  * - Inline inserted text wrapped in one or more `+` pluses.
- * - Inline deleted text wrapped in one or more `-` minuses or `~` tildes.
+ * - Inline deleted text wrapped in one or more `~` tildes.
  * - Inline highlighted text wrapped in one or more `=` equals or `:` colons.
  * - Whitespace cannot be the first or last character of the element (e.g. `* abc *` will not work).
  * - Closing chars must match opening characters.
  * - Cannot occur in the middle of a word (e.g. `this*that*this` will not work).
  * - Closing characters must exactly match opening characters.
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
+ *
+ * @example new MarkupParser({ rules: [INLINE_RULE] }).parse("This is *bold* and _italic_")
+ * @see https://dhoulb.github.io/shelving/markup/rule/inline/INLINE_RULE
  */
 export declare const INLINE_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/inline.js

@@ -2,19 +2,22 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createMarkupRule } from "../MarkupRule.js";
 import { createWordRegExp } from "../util/regexp.js";
 /** Map characters, e.g. `*`, to their coresponding HTML tag, e.g. `strong` */
-const INLINE_CHARS = { "-": "del", "~": "del", "+": "ins", "*": "strong", _: "em", "=": "mark" }; // Hyphen must be first so it works when we use the keys as a character class.
+const INLINE_CHARS = { "~": "del", "+": "ins", "*": "strong", _: "em", "=": "mark" };
 /**
  * Inline strong, emphasis, insert, delete, highlight.
  * - Inline strong text wrapped in one or more `*` asterisks.
  * - Inline emphasis text wrapped in one or more `_` underscores.
  * - Inline inserted text wrapped in one or more `+` pluses.
- * - Inline deleted text wrapped in one or more `-` minuses or `~` tildes.
+ * - Inline deleted text wrapped in one or more `~` tildes.
  * - Inline highlighted text wrapped in one or more `=` equals or `:` colons.
  * - Whitespace cannot be the first or last character of the element (e.g. `* abc *` will not work).
  * - Closing chars must match opening characters.
  * - Cannot occur in the middle of a word (e.g. `this*that*this` will not work).
  * - Closing characters must exactly match opening characters.
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
+ *
+ * @example new MarkupParser({ rules: [INLINE_RULE] }).parse("This is *bold* and _italic_")
+ * @see https://dhoulb.github.io/shelving/markup/rule/inline/INLINE_RULE
  */
 export const INLINE_RULE = createMarkupRule(createWordRegExp(`(?<wrap>(?<char>[${Object.keys(INLINE_CHARS).join("")}])+)(?<text>(?!\\k<char>)\\S(?:[\\s\\S]*?(?!\\k<char>)\\S)?)\\k<wrap>`), (key, { char, text }, parser) => {
     const Inline = INLINE_CHARS[char];

package/markup/rule/linebreak.d.ts

@@ -7,5 +7,8 @@
  *   - We just directly convert any `\n` linebreak into a `<br />` tag (lines without two spaces are not joined together).
  *   - This is more intuitive (a linebreak becomes a linebreak is isn't silently ignored).
  *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
+ *
+ * @example new MarkupParser({ rules: [LINEBREAK_RULE] }).parse("Line one\nLine two")
+ * @see https://dhoulb.github.io/shelving/markup/rule/linebreak/LINEBREAK_RULE
  */
 export declare const LINEBREAK_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/linebreak.js

@@ -9,6 +9,9 @@ import { createMarkupRule } from "../MarkupRule.js";
  *   - We just directly convert any `\n` linebreak into a `<br />` tag (lines without two spaces are not joined together).
  *   - This is more intuitive (a linebreak becomes a linebreak is isn't silently ignored).
  *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
+ *
+ * @example new MarkupParser({ rules: [LINEBREAK_RULE] }).parse("Line one\nLine two")
+ * @see https://dhoulb.github.io/shelving/markup/rule/linebreak/LINEBREAK_RULE
  */
 export const LINEBREAK_RULE = createMarkupRule(/[^\n\S]*\n[^\n\S]*/, //
 //

package/markup/rule/link.d.ts

@@ -5,6 +5,9 @@
  * - Does not need space before/after the link.
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `MarkupOptions.schemes` will match (defaults to `http:` and `https:`).
+ *
+ * @example new MarkupParser({ rules: [LINK_RULE] }).parse("[Google Maps](http://google.com/maps)")
+ * @see https://dhoulb.github.io/shelving/markup/rule/link/LINK_RULE
  */
 export declare const LINK_RULE: import("../MarkupRule.js").MarkupRule;
 /**
@@ -13,5 +16,8 @@ export declare const LINK_RULE: import("../MarkupRule.js").MarkupRule;
  * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `MarkupOptions.schemes` will match (defaults to `http:` and `https:`).
+ *
+ * @example new MarkupParser({ rules: [AUTOLINK_RULE] }).parse("http://google.com/maps (Google Maps)")
+ * @see https://dhoulb.github.io/shelving/markup/rule/link/AUTOLINK_RULE
  */
 export declare const AUTOLINK_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/link.js

@@ -14,6 +14,9 @@ function _renderLink(key, { title, href }, parser) {
  * - Does not need space before/after the link.
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `MarkupOptions.schemes` will match (defaults to `http:` and `https:`).
+ *
+ * @example new MarkupParser({ rules: [LINK_RULE] }).parse("[Google Maps](http://google.com/maps)")
+ * @see https://dhoulb.github.io/shelving/markup/rule/link/LINK_RULE
  */
 export const LINK_RULE = createMarkupRule(getRegExp(/\[(?<title>[^\]\n]*?)\]\((?<href>[^)\n]*?)\)/), //
 _renderLink, ["inline", "list"]);
@@ -23,6 +26,9 @@ _renderLink, ["inline", "list"]);
  * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `MarkupOptions.schemes` will match (defaults to `http:` and `https:`).
+ *
+ * @example new MarkupParser({ rules: [AUTOLINK_RULE] }).parse("http://google.com/maps (Google Maps)")
+ * @see https://dhoulb.github.io/shelving/markup/rule/link/AUTOLINK_RULE
  */
 export const AUTOLINK_RULE = createMarkupRule(getRegExp(/(?<href>[a-z]{3,}?:\S+)(?: +(?:\((?<title>[^)\n]*?)\)))?/), //
 _renderLink, ["inline", "list"]);

package/markup/rule/ordered.d.ts

@@ -6,5 +6,8 @@
  * - List block runs until a blank line that is not followed by another item or an indented continuation line.
  * - A list with blank lines between its items (or before a continuation paragraph) is "loose": its items are wrapped in `<p>` tags.
  * - Sparse lists are not supported.
+ *
+ * @example new MarkupParser({ rules: [ORDERED_RULE] }).parse("1. First\n2. Second")
+ * @see https://dhoulb.github.io/shelving/markup/rule/ordered/ORDERED_RULE
  */
 export declare const ORDERED_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/ordered.js

@@ -19,6 +19,9 @@ const _LOOSE = new RegExp(`\\n${LINE_SPACE_REGEXP}*\\n`);
  * - List block runs until a blank line that is not followed by another item or an indented continuation line.
  * - A list with blank lines between its items (or before a continuation paragraph) is "loose": its items are wrapped in `<p>` tags.
  * - Sparse lists are not supported.
+ *
+ * @example new MarkupParser({ rules: [ORDERED_RULE] }).parse("1. First\n2. Second")
+ * @see https://dhoulb.github.io/shelving/markup/rule/ordered/ORDERED_RULE
  */
 export const ORDERED_RULE = createMarkupRule(createBlockRegExp(`(?<list>${_NUMBER}(?:${LINE_SPACE_REGEXP}+${BLOCK_CONTENT_REGEXP})?)`, BLOCK_START_REGEXP, _END), (key, { list }, parser) => _jsx("ol", { children: Array.from(_getOrderedItems(list, parser)) }, key), ["block", "list"]);
 /** Parse a markdown list into a set of items elements. */

package/markup/rule/paragraph.d.ts

@@ -3,5 +3,8 @@
  * - Captures almost anything in a block context.
  * - Any run of non-whitespace.
  * - Leading and trailing whitespace is trimmed.
+ *
+ * @example new MarkupParser({ rules: [PARAGRAPH_RULE] }).parse("Some plain text")
+ * @see https://dhoulb.github.io/shelving/markup/rule/paragraph/PARAGRAPH_RULE
  */
 export declare const PARAGRAPH_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/paragraph.js

@@ -6,5 +6,8 @@ import { BLOCK_SPACE_REGEXP, BLOCK_START_REGEXP, createBlockRegExp } from "../ut
  * - Captures almost anything in a block context.
  * - Any run of non-whitespace.
  * - Leading and trailing whitespace is trimmed.
+ *
+ * @example new MarkupParser({ rules: [PARAGRAPH_RULE] }).parse("Some plain text")
+ * @see https://dhoulb.github.io/shelving/markup/rule/paragraph/PARAGRAPH_RULE
  */
 export const PARAGRAPH_RULE = createMarkupRule(createBlockRegExp("(?<paragraph>(?:(?=\\S)[\\s\\S]*?\\S))", `${BLOCK_START_REGEXP}${BLOCK_SPACE_REGEXP}*`), (key, { paragraph }, parser) => _jsx("p", { children: parser.parse(paragraph, "inline") }, key), ["block"], -10);

package/markup/rule/separator.d.ts

@@ -4,5 +4,8 @@
  * - Character must be repeated three (or more) times.
  * - Character must be the same every time (can't mix)
  * - Might have infinite number of spaces between the characters.
+ *
+ * @example new MarkupParser({ rules: [SEPARATOR_RULE] }).parse("---")
+ * @see https://dhoulb.github.io/shelving/markup/rule/separator/SEPARATOR_RULE
  */
 export declare const SEPARATOR_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/separator.js

@@ -7,6 +7,9 @@ import { createLineRegExp } from "../util/regexp.js";
  * - Character must be repeated three (or more) times.
  * - Character must be the same every time (can't mix)
  * - Might have infinite number of spaces between the characters.
+ *
+ * @example new MarkupParser({ rules: [SEPARATOR_RULE] }).parse("---")
+ * @see https://dhoulb.github.io/shelving/markup/rule/separator/SEPARATOR_RULE
  */
 export const SEPARATOR_RULE = createMarkupRule(createLineRegExp("([-*•+_=])(?: *\\1){2,}"), //
 //

package/markup/rule/table.d.ts

@@ -5,5 +5,8 @@
  * - Extra `|---|` delimiter rows split the table into sections: the first section becomes `<thead>`, the last becomes `<tfoot>` (only when there are three or more sections), and every section in between becomes its own `<tbody>`.
  * - Column count and per-column alignment (`:--` left, `--:` right, `:-:` centered) come from the first delimiter row; ragged rows are padded or truncated to that count.
  * - Cell content is rendered as inline markup; write `\|` for a literal pipe inside a cell.
+ *
+ * @example new MarkupParser({ rules: [TABLE_RULE] }).parse("| A | B |\n|---|---|\n| 1 | 2 |")
+ * @see https://dhoulb.github.io/shelving/markup/rule/table/TABLE_RULE
  */
 export declare const TABLE_RULE: import("../MarkupRule.js").MarkupRule;

package/markup/rule/table.js

@@ -15,6 +15,9 @@ const _SPLIT = /(?<!\\)\|/; // Splits a row into cells on unescaped pipes.
  * - Extra `|---|` delimiter rows split the table into sections: the first section becomes `<thead>`, the last becomes `<tfoot>` (only when there are three or more sections), and every section in between becomes its own `<tbody>`.
  * - Column count and per-column alignment (`:--` left, `--:` right, `:-:` centered) come from the first delimiter row; ragged rows are padded or truncated to that count.
  * - Cell content is rendered as inline markup; write `\|` for a literal pipe inside a cell.
+ *
+ * @example new MarkupParser({ rules: [TABLE_RULE] }).parse("| A | B |\n|---|---|\n| 1 | 2 |")
+ * @see https://dhoulb.github.io/shelving/markup/rule/table/TABLE_RULE
  */
 export const TABLE_RULE = createMarkupRule(createBlockRegExp(`(?<table>${_ROW}\\n${_DELIMITER_SOURCE}(?:\\n${_ROW})*)`), (key, { table }, parser) => {
     const lines = table.split("\n");

package/markup/rule/unordered.d.ts

@@ -9,6 +9,9 @@ import type { MarkupParser } from "../MarkupParser.js";
  * - A list with blank lines between its items (or before a continuation paragraph) is "loose": its items are wrapped in `<p>` tags.
  * - An item starting with `[ ]` or `[x]` (case-insensitive) is a todo item: a checkbox `<input>` plus the content wrapped in a `<label>` so clicking it toggles the checkbox.
  * - Sparse lists are not supported.
+ *
+ * @example new MarkupParser({ rules: [UNORDERED_RULE] }).parse("- First\n- Second")
+ * @see https://dhoulb.github.io/shelving/markup/rule/unordered/UNORDERED_RULE
  */
 export declare const UNORDERED_RULE: import("../MarkupRule.js").MarkupRule;
 /** Parse a markdown list into a set of items elements. */

package/markup/rule/unordered.js

@@ -23,6 +23,9 @@ const _LOOSE = new RegExp(`\\n${LINE_SPACE_REGEXP}*\\n`);
  * - A list with blank lines between its items (or before a continuation paragraph) is "loose": its items are wrapped in `<p>` tags.
  * - An item starting with `[ ]` or `[x]` (case-insensitive) is a todo item: a checkbox `<input>` plus the content wrapped in a `<label>` so clicking it toggles the checkbox.
  * - Sparse lists are not supported.
+ *
+ * @example new MarkupParser({ rules: [UNORDERED_RULE] }).parse("- First\n- Second")
+ * @see https://dhoulb.github.io/shelving/markup/rule/unordered/UNORDERED_RULE
  */
 export const UNORDERED_RULE = createMarkupRule(createBlockRegExp(`(?<list>${_BULLET}(?:${LINE_SPACE_REGEXP}+${BLOCK_CONTENT_REGEXP})?)`, BLOCK_START_REGEXP, _END), (key, { list }, parser) => _jsx("ul", { children: Array.from(_getItems(list, parser)) }, key), ["block", "list"]);
 /** Parse a markdown list into a set of items elements. */