shelving 1.50.0 → 1.51.1

package/markup/render.d.ts

@@ -33,8 +33,3 @@ import type { MarkupOptions, MarkupNode } from "./types.js";
  * @returns ReactNode, i.e. either a complete `ReactElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
 export declare function renderMarkup(content: string, options?: Partial<MarkupOptions>): MarkupNode;
-/**
- * Parse a text string as user-generated markup.
- * - Like `renderMarkup()` but only enables a subset of rules and applies `rel="nofollow ugc"` to all links.
- */
-export declare function renderUgcMarkup(content: string, options?: Partial<MarkupOptions>): MarkupNode;

package/markup/render.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-param-reassign */
 import { sanitizeLines } from "../index.js";
-import { MARKUP_RULES, MARKUP_RULES_UGC } from "./rules.js";
+import { MARKUP_RULES } from "./rules.js";
 /** Convert a string into an array of React nodes using a set of rules. */
 function renderString(content, options) {
     // If there's no context return the unmodified string.
@@ -15,12 +15,12 @@ function renderString(content, options) {
         let matchedRule = undefined;
         let matchedResult = undefined;
         for (const rule of options.rules) {
-            const { priority = 0, match, contexts } = rule;
+            const { priority = 0, match, regexp, contexts } = rule;
             // Only apply this rule if both:
             // 1. The priority is equal or higher to the current priority.
             // 2. The rule is allowed in the current context.
             if (priority >= matchedPriority && contexts.includes(options.context)) {
-                const result = match(content, options);
+                const result = match ? match(content, options) : regexp ? content.match(regexp) : null;
                 // If this matched and has an index (it might not if it's a `/g` global RegExp, which would be a mistake).
                 if (result && typeof result.index === "number") {
                     const index = result.index;
@@ -154,15 +154,3 @@ const defaults = {
     rel: undefined,
     schemes: ["http:", "https:"],
 };
-/**
- * Parse a text string as user-generated markup.
- * - Like `renderMarkup()` but only enables a subset of rules and applies `rel="nofollow ugc"` to all links.
- */
-export function renderUgcMarkup(content, options) {
-    return renderString(sanitizeLines(content), { ...defaultsUgc, ...options });
-}
-const defaultsUgc = {
-    ...defaults,
-    rules: MARKUP_RULES_UGC,
-    rel: "nofollow ugc",
-};

package/markup/rules.d.ts

@@ -1,4 +1,111 @@
 import type { MarkupRule } from "./types.js";
+/**
+ * Headings are single line only (don't allow multiline).
+ * - 1-6 hashes then 1+ spaces, then the title.
+ * - Same as Markdown syntax.
+ * - Markdown's underline syntax is not supported (for simplification).
+ */
+export declare const HEADING_RULE: MarkupRule;
+/**
+ * Horizontal rules
+ * - Same as Markdown syntax but also allows `•` bullet character (in addition to `-` dash, `+` plus, `*` asterisk, and `_` underscore).
+ * - 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.
+ */
+export declare const HORIZONTAL_RULE: MarkupRule;
+export declare const UNORDERED_LIST_RULE: MarkupRule;
+export declare const ORDERED_LIST_RULE: MarkupRule;
+/**
+ * Blockquote block.
+ * - Same as Markdown's syntax.
+ * - Block continues until it finds a line that doesn't start with `>`
+ * - Quote indent symbol can be followed by zero or more spaces.
+ */
+export declare const BLOCKQUOTE_RULE: MarkupRule;
+/**
+ * Fenced code blocks
+ * - Same as Markdown syntax.
+ * - Closing fence must be exactly the same as the opening fence, and can be made of at least three "```" backticks or three `~~~` 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 easier to use).
+ */
+export declare const FENCED_CODE_RULE: MarkupRule;
+/**
+ * Paragraph.
+ * - When ordering rules, paragraph should go after other "block" context elements (because it has a very generous capture).
+ */
+export declare const PARAGRAPH_RULE: MarkupRule;
+/**
+ * Markdown-style link.
+ * - Link in standard Markdown format, e.g. `[http://google.com/maps](Google Maps)`
+ * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
+ * - 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 `http://` or `https://` links will work (if invalid the unparsed text will be returned).
+ */
+export declare const LINK_MARKUP: MarkupRule;
+/**
+ * Autolinked URL starts with `http:` or `https:` and matches an unlimited number of non-space characters.
+ * - If followed by space and then text in `()` round or `[]` square brackets that will be used as the title, e.g. `http://google.com/maps (Google Maps)` or `http://google.com/maps [Google Maps]` (this syntax is from Todoist and maybe other things too).
+ * - 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 the `options.schemes` will match (defaults to `http:` and `https:`).
+ */
+export declare const AUTOLINK_RULE: MarkupRule;
+/**
+ * Inline code.
+ * - Text surrounded by one or more "`" backtick tilde characters.
+ * - Unlike strong/emphasis first or last character of the element can be space, (e.g. `- abc -` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Same as Markdown syntax.
+ */
+export declare const CODE_RULE: MarkupRule;
+/**
+ * Inline strong.
+ * - Inline text wrapped in one or more `*` asterisks.
+ * - Must be surrounded by space (e.g. ` *abc* `) — so formatting cannot be applied inside a word (e.g. `a*b*c`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `* abc *` 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').
+ */
+export declare const STRONG_MARKUP: MarkupRule;
+/**
+ * Inline emphasis.
+ * - Inline text wrapped in one or more `_` underscore symbols.
+ * - Works inside words (e.g. `magi_carp_carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `_ abc _` 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').
+ */
+export declare const EMPHASIS_RULE: MarkupRule;
+/**
+ * Inserted text (`<ins>` tag),
+ * - Inline text wrapped in two or more `++` pluses.
+ * - Works inside words (e.g. `magi+karp+carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `+ abc +` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Markdown doesn't have this.
+ */
+export declare const INSERT_RULE: MarkupRule;
+/**
+ * Deleted text (`<del>` tag),
+ * - Inline text wrapped in two or more `--` hyphens or `~~` tildes.
+ * - Works inside words (e.g. `magi--karp--carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `-- abc --` will not work).
+ * - Closing characters must exactly match opening characters.
+ * - Markdown doesn't have this.
+ */
+export declare const DELETE_RULE: MarkupRule;
+/**
+ * Hard linebreak (`<br />` tag).
+ * - Any line break in a paragraph will become a hard `<br />` tag.
+ * - Different to Markdown:
+ *   - Markdown needs two spaces at the end of a line, any line break in a paragraph will be 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).
+ */
+export declare const LINEBREAK_RULE: MarkupRule;
 /**
  * All markup rules.
  * - Syntax parsed by `renderMarkup()` is defined entirely by the list of rules (i.e. not by code).
@@ -9,5 +116,9 @@ import type { MarkupRule } from "./types.js";
  * - HTML tags and character entities are never allowed (our use cases generally require a locked-down subset of syntax).
  */
 export declare const MARKUP_RULES: MarkupRule[];
-/** Default markup rules for user-generated-content rendering. */
-export declare const MARKUP_RULES_UGC: MarkupRule[];
+/** Subset of markup rules that work in a block context. */
+export declare const MARKUP_RULES_BLOCK: MarkupRule[];
+/** Subset of markup rules that work in an inline context. */
+export declare const MARKUP_RULES_INLINE: MarkupRule[];
+/** Subset of markup rules that are relevant for collapsed shortform content. */
+export declare const MARKUP_RULES_SHORTFORM: MarkupRule[];

package/markup/rules.js

@@ -1,31 +1,16 @@
-import { formatUrl, toURL } from "../util/index.js";
+import { formatUrl, toURL, getLineRegExp, MATCH_LINE, getBlockRegExp, MATCH_BLOCK, getWrapRegExp } from "../util/index.js";
 // Regular expression partials (`\` slashes must be escaped as `\\`).
-const LINE = "[^\\n]*"; // Match line of content (anything that's not a newline).
-const LINE_START = "^\\n*|\\n+"; // Starts at start of line (one or more linebreak or start of string).
-const LINE_END = "\\n+|$"; // Ends at end of line (one or more linebreak or end of string).
-const BLOCK = "[\\s\\S]*?"; // Match block of content (including newlines so don't be greedy).
-const BLOCK_START = "^\\n*|\\n+"; // Starts at start of a block (one or more linebreak or start of string).
-const BLOCK_END = "\\n*$|\\n\\n+"; // End of a block (two or more linebreaks or end of string).
 const BULLETS = "-*•+"; // Anything that can be a bullet (used for unordered lists and horizontal rules).
-const WORDS = `\\S(?:[\\s\\S]*?\\S)?`; // Run of text that starts and ends with non-space characters (possibly multi-line).
 // Regular expressions.
 const REPLACE_INDENT = /^ {1,2}/gm;
-// Regular expression makers.
-const getMatcher = regexp => content => content.match(regexp);
-const getBlockMatcher = (middle = BLOCK, end = BLOCK_END, start = BLOCK_START) => getMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const getLineMatcher = (middle = LINE, end = LINE_END, start = LINE_START) => getMatcher(new RegExp(`(?:${start})${middle}(?:${end})`));
-const getWrapMatcher = (chars, middle = WORDS) => {
-    const regexp = new RegExp(`(${chars})(${middle})\\1`);
-    return content => content.match(regexp);
-};
 /**
  * Headings are single line only (don't allow multiline).
  * - 1-6 hashes then 1+ spaces, then the title.
  * - Same as Markdown syntax.
  * - Markdown's underline syntax is not supported (for simplification).
  */
-const HEADING = {
-    match: getLineMatcher(`(#{1,6}) +(${LINE})`),
+export const HEADING_RULE = {
+    regexp: getLineRegExp(`(#{1,6}) +(${MATCH_LINE})`),
     render: ([, prefix = "", children = ""]) => ({ type: `h${prefix.length}`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -37,8 +22,8 @@ const HEADING = {
  * - Character must be the same every time (can't mix)
  * - Might have infinite number of spaces between the characters.
  */
-const HR = {
-    match: getLineMatcher(`([${BULLETS}])(?: *\\1){2,}`),
+export const HORIZONTAL_RULE = {
+    regexp: getLineRegExp(`([${BULLETS}])(?: *\\1){2,}`),
     render: () => ({ type: "hr", key: null, props: {} }),
     contexts: ["block"],
 };
@@ -50,8 +35,8 @@ const HR = {
  * - Second-level list can be indented with 1-2 spaces.
  */
 const UNORDERED = `[${BULLETS}] +`; // Anything that can be a bullet (used for unordered lists and horizontal rules).
-const UL = {
-    match: getBlockMatcher(`${UNORDERED}(${BLOCK})`),
+export const UNORDERED_LIST_RULE = {
+    regexp: getBlockRegExp(`${UNORDERED}(${MATCH_BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_UL_ITEMS).map(mapUnorderedItem);
         return { type: "ul", key: null, props: { children } };
@@ -70,8 +55,8 @@ const mapUnorderedItem = (item, key) => {
  * - Second-level list can be indented with 1-3 spaces.
  */
 const ORDERED = "[0-9]+[.):] +"; // Number for a numbered list (e.g. `1.` or `2)` or `3:`)
-const OL = {
-    match: getBlockMatcher(`(${ORDERED}${BLOCK})`),
+export const ORDERED_LIST_RULE = {
+    regexp: getBlockRegExp(`(${ORDERED}${MATCH_BLOCK})`),
     render: ([, list = ""]) => {
         const children = list.split(SPLIT_OL_ITEMS).map(mapOrderedItem);
         return { type: "ol", key: null, props: { children } };
@@ -95,8 +80,8 @@ const mapOrderedItem = (item, key) => {
  * - Block continues until it finds a line that doesn't start with `>`
  * - Quote indent symbol can be followed by zero or more spaces.
  */
-const BLOCKQUOTE = {
-    match: getLineMatcher(`(>${LINE}(?:\\n>${LINE})*)`),
+export const BLOCKQUOTE_RULE = {
+    regexp: getLineRegExp(`(>${MATCH_LINE}(?:\\n>${MATCH_LINE})*)`),
     render: ([, quote = ""]) => ({
         type: "blockquote",
         key: null,
@@ -113,9 +98,9 @@ const BLOCKQUOTE_LINES = /^>/gm;
  * - 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 easier to use).
  */
-const FENCED = {
+export const FENCED_CODE_RULE = {
     // Matcher has its own end that only stops when it reaches a matching closing fence or the end of the string.
-    match: getBlockMatcher(`(\`{3,}|~{3,}) *(${LINE})\\n(${BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
+    regexp: getBlockRegExp(`(\`{3,}|~{3,}) *(${MATCH_LINE})\\n(${MATCH_BLOCK})`, `\\n\\1\\n+|\\n\\1$|$`),
     render: ([, , file, children]) => ({
         type: "pre",
         key: null,
@@ -133,8 +118,8 @@ const FENCED = {
  * Paragraph.
  * - When ordering rules, paragraph should go after other "block" context elements (because it has a very generous capture).
  */
-const PARAGRAPH = {
-    match: getBlockMatcher(` *(${BLOCK})`),
+export const PARAGRAPH_RULE = {
+    regexp: getBlockRegExp(` *(${MATCH_BLOCK})`),
     render: ([, children]) => ({ type: `p`, key: null, props: { children } }),
     contexts: ["block"],
     childContext: "inline",
@@ -148,10 +133,11 @@ const PARAGRAPH = {
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only `http://` or `https://` links will work (if invalid the unparsed text will be returned).
  */
-const LINK = {
+export const LINK_MARKUP = {
     // Custom matcher to check the URL against the allowed schemes.
+    regexp: /\[([^\]]*?)\]\(([^)]*?)\)/,
     match: (content, { schemes, url: base }) => {
-        const matches = content.match(MATCH_LINK);
+        const matches = content.match(LINK_MARKUP.regexp);
         if (matches && typeof matches.index === "number") {
             const [, title = "", href = ""] = matches;
             const url = toURL(href, base);
@@ -170,7 +156,6 @@ const LINK = {
     contexts: ["inline", "list"],
     childContext: "link",
 };
-const MATCH_LINK = /\[([^\]]*?)\]\(([^)]*?)\)/;
 /**
  * Autolinked URL starts with `http:` or `https:` and matches an unlimited number of non-space characters.
  * - If followed by space and then text in `()` round or `[]` square brackets that will be used as the title, e.g. `http://google.com/maps (Google Maps)` or `http://google.com/maps [Google Maps]` (this syntax is from Todoist and maybe other things too).
@@ -178,10 +163,11 @@ const MATCH_LINK = /\[([^\]]*?)\]\(([^)]*?)\)/;
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in the `options.schemes` will match (defaults to `http:` and `https:`).
  */
-const AUTOLINK = {
+export const AUTOLINK_RULE = {
     // Custom matcher to check the URL against the allowed schemes.
+    regexp: /([a-zA-Z][a-zA-Z0-9-]*[a-zA-Z0-9]:\S+)(?: +(?:\(([^)]*?)\)|\[([^\]]*?)\]))?/,
     match: (content, { schemes, url: base }) => {
-        const matches = content.match(MATCH_AUTOLINK);
+        const matches = content.match(AUTOLINK_RULE.regexp);
         if (matches && typeof matches.index === "number") {
             const [, href = "", title1 = "", title2 = ""] = matches;
             const url = toURL(href, base);
@@ -192,11 +178,10 @@ const AUTOLINK = {
             }
         }
     },
-    render: LINK.render,
+    render: LINK_MARKUP.render,
     contexts: ["inline", "list"],
     childContext: "link",
 };
-const MATCH_AUTOLINK = /([a-z][a-z0-9-]*[a-z0-9]:\S+)(?: +(?:\(([^)]*?)\)|\[([^\]]*?)\]))?/i;
 /**
  * Inline code.
  * - Text surrounded by one or more "`" backtick tilde characters.
@@ -204,8 +189,8 @@ const MATCH_AUTOLINK = /([a-z][a-z0-9-]*[a-z0-9]:\S+)(?: +(?:\(([^)]*?)\)|\[([^\
  * - Closing characters must exactly match opening characters.
  * - Same as Markdown syntax.
  */
-const CODE = {
-    match: getWrapMatcher("`+", BLOCK),
+export const CODE_RULE = {
+    regexp: getWrapRegExp("`+", MATCH_BLOCK),
     render: ([, , children]) => ({ type: "code", key: null, props: { children } }),
     contexts: ["inline", "list"],
     priority: 10, // Higher priority than other inlines so it matches first before e.g. `strong` or `em` (from CommonMark spec: "Code span backticks have higher precedence than any other inline constructs except HTML tags and autolinks.")
@@ -218,8 +203,8 @@ const CODE = {
  * - 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').
  */
-const STRONG = {
-    match: getWrapMatcher("\\*+"),
+export const STRONG_MARKUP = {
+    regexp: getWrapRegExp("\\*+"),
     render: ([, , children]) => ({ type: "strong", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -232,36 +217,36 @@ const STRONG = {
  * - 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').
  */
-const EM = {
-    match: getWrapMatcher("_+"),
+export const EMPHASIS_RULE = {
+    regexp: getWrapRegExp("_+"),
     render: ([, , children]) => ({ type: "em", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
 };
 /**
  * Inserted text (`<ins>` tag),
- * - Inline text wrapped in one or more `+` pluses.
+ * - Inline text wrapped in two or more `++` pluses.
  * - Works inside words (e.g. `magi+karp+carp`).
  * - Whitespace cannot be the first or last character of the element (e.g. `+ abc +` will not work).
  * - Closing characters must exactly match opening characters.
  * - Markdown doesn't have this.
  */
-const INS = {
-    match: getWrapMatcher("\\++"),
+export const INSERT_RULE = {
+    regexp: getWrapRegExp("\\+\\++"),
     render: ([, , children]) => ({ type: "ins", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
 };
 /**
  * Deleted text (`<del>` tag),
- * - Inline text wrapped in one or more `~` tildes.
- * - Works inside words (e.g. `magi~karp~carp`).
- * - Whitespace cannot be the first or last character of the element (e.g. `~ abc ~` will not work).
+ * - Inline text wrapped in two or more `--` hyphens or `~~` tildes.
+ * - Works inside words (e.g. `magi--karp--carp`).
+ * - Whitespace cannot be the first or last character of the element (e.g. `-- abc --` will not work).
  * - Closing characters must exactly match opening characters.
  * - Markdown doesn't have this.
  */
-const DEL = {
-    match: getWrapMatcher("~+"),
+export const DELETE_RULE = {
+    regexp: getWrapRegExp("--+|~~+"),
     render: ([, , children]) => ({ type: "del", key: null, props: { children } }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -274,8 +259,8 @@ const DEL = {
  *   - 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).
  */
-const BR = {
-    match: getMatcher(/\n/),
+export const LINEBREAK_RULE = {
+    regexp: /\n/,
     render: () => ({ type: "br", key: null, props: {} }),
     contexts: ["inline", "list", "link"],
     childContext: "inline",
@@ -289,6 +274,55 @@ const BR = {
  *   3. more aligned with smaller textboxes and editors that have line wrapping
  * - HTML tags and character entities are never allowed (our use cases generally require a locked-down subset of syntax).
  */
-export const MARKUP_RULES = [HEADING, HR, UL, OL, BLOCKQUOTE, FENCED, PARAGRAPH, LINK, AUTOLINK, CODE, STRONG, EM, INS, DEL, BR];
-/** Default markup rules for user-generated-content rendering. */
-export const MARKUP_RULES_UGC = [UL, OL, PARAGRAPH, LINK, AUTOLINK, CODE, STRONG, EM, INS, DEL, BR];
+export const MARKUP_RULES = [
+    HEADING_RULE,
+    HORIZONTAL_RULE,
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    BLOCKQUOTE_RULE,
+    FENCED_CODE_RULE,
+    PARAGRAPH_RULE,
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];
+/** Subset of markup rules that work in a block context. */
+export const MARKUP_RULES_BLOCK = [
+    HEADING_RULE,
+    HORIZONTAL_RULE,
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    BLOCKQUOTE_RULE,
+    FENCED_CODE_RULE,
+    PARAGRAPH_RULE,
+];
+/** Subset of markup rules that work in an inline context. */
+export const MARKUP_RULES_INLINE = [
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];
+/** Subset of markup rules that are relevant for collapsed shortform content. */
+export const MARKUP_RULES_SHORTFORM = [
+    UNORDERED_LIST_RULE,
+    ORDERED_LIST_RULE,
+    PARAGRAPH_RULE,
+    LINK_MARKUP,
+    AUTOLINK_RULE,
+    CODE_RULE,
+    STRONG_MARKUP,
+    EMPHASIS_RULE,
+    INSERT_RULE,
+    DELETE_RULE,
+    LINEBREAK_RULE,
+];

package/markup/types.d.ts

@@ -18,8 +18,10 @@ export declare type MarkupElementProps = {
 export declare type MarkupNode = undefined | null | string | MarkupElement | MarkupNode[];
 /** A single markup parsing rule. */
 export declare type MarkupRule = {
-    /** RegExp that matches this rule. */
-    readonly match: MarkupRuleMatcher;
+    /** RegExp for matching this rule. */
+    readonly regexp: RegExp;
+    /** Custom matching function for this rule (overrides `regexp` if present. */
+    readonly match?: (content: string, options: MarkupOptions) => RegExpMatchArray | null | undefined | void;
     /**
      * Return a corresponding JSX element for the match.
      * @param ...matches The matches from `match` RegExp (without the `0` zeroeth "whole match").
@@ -27,7 +29,7 @@ export declare type MarkupRule = {
      *   - The `key` property is not required (will be set automatically).
      *   - e.g. `{ type: "a", props: { href: "/example.html", className: "strong", children: "Children *can* include _syntax_" } }`
      */
-    readonly render: MarkupRuleRenderer;
+    readonly render: (matches: RegExpMatchArray, options: MarkupOptions) => MarkupElement;
     /** Apply the rule only when in certain contexts, e.g. `["block", "inline", "list"]` */
     readonly contexts: string[];
     /** Context any string children returned from `render()` should be rendered with. */
@@ -42,8 +44,6 @@ export declare type MarkupRule = {
      */
     readonly priority?: number;
 };
-export declare type MarkupRuleMatcher = (content: string, options: MarkupOptions) => RegExpMatchArray | null | undefined | void;
-export declare type MarkupRuleRenderer = (matches: RegExpMatchArray, options: MarkupOptions) => MarkupElement;
 /** A set of parse rules (as an object or array). */
 export declare type MarkupRules = Iterable<MarkupRule>;
 /** The current parsing options (represents the current state of the parsing). */
@@ -59,5 +59,3 @@ export declare type MarkupOptions = {
     /** Valid URL schemes/protocols for links (including trailing commas), defaults to `[`http:`, `https:`]` */
     readonly schemes: string[];
 };
-/** The create element function. */
-export declare type MarkupElementCreator = (type: string, props?: MarkupElementProps | null) => MarkupElement;

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.50.0",
+	"version": "1.51.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -61,16 +61,16 @@
 	"devDependencies": {
 		"@google-cloud/firestore": "^4.15.1",
 		"@types/jest": "^27.4.0",
-		"@types/react": "^17.0.38",
+		"@types/react": "^17.0.39",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.10.1",
-		"@typescript-eslint/parser": "^5.10.1",
+		"@typescript-eslint/eslint-plugin": "^5.10.2",
+		"@typescript-eslint/parser": "^5.10.2",
 		"eslint": "^8.8.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.4",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.5",
-		"jest": "^27.4.7",
+		"firebase": "^9.6.6",
+		"jest": "^27.5.0",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",

package/util/random.d.ts

@@ -2,9 +2,10 @@ import type { ImmutableArray } from "./array.js";
 /** Generate a random integer between two numbers. */
 export declare const getRandom: (min: number, max: number) => number;
 /**
- * Make a random key, e.g. "xs23rsdxe4mrugef"
+ * Make a random key, e.g. `xs23r34hhsdx` or `e4m29klrugef`
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
+ * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
  */
 export declare const getRandomKey: (length?: number) => string;
 /** Get a random character from a string. */

package/util/random.js

@@ -4,11 +4,12 @@ import { getDefined } from "./undefined.js";
 /** Generate a random integer between two numbers. */
 export const getRandom = (min, max) => Math.round(Math.random() * (max - min) + min);
 /**
- * Make a random key, e.g. "xs23rsdxe4mrugef"
+ * Make a random key, e.g. `xs23r34hhsdx` or `e4m29klrugef`
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
+ * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
  */
-export const getRandomKey = (length = 16) => joinStrings(yieldUntilLimit(yieldCall(getRandomCharacter, KEY_CHARS), length));
+export const getRandomKey = (length = 12) => joinStrings(yieldUntilLimit(yieldCall(getRandomCharacter, KEY_CHARS), length));
 const KEY_CHARS = "0123456789abcdefghjkmnpqrstvwxyz";
 /** Get a random character from a string. */
 export const getRandomCharacter = (str) => str[getRandom(0, str.length - 1)];

package/util/search.d.ts

@@ -1,25 +1,37 @@
 import type { ImmutableArray } from "./array.js";
 import { Matchable } from "./filter.js";
 /**
- * Match a string against a regular expression.
+ * Convert a string to a regular expression that matches that string.
  *
- * @param item The item to search for the regexp in.
- * - Item is an array: recurse into each item of the array to look for strings that match.
- * - Item is an object: recurse into each property of the object to look for strings that match.
- * - Item is string: match the string against the regular expression.
- * - Item is anything else: return false (can't be matched).
- *
- * @param regexp The `RegExp` instance to match the
+ * @param str The input string.
+ * @param flags RegExp flags that are passed into the created RegExp.
  */
-export declare function MATCHES(item: unknown, regexp: RegExp): boolean;
+export declare const toRegExp: (str: string, flags?: string) => RegExp;
+/** Escape special characters in a string regular expression. */
+export declare const escapeRegExp: (str: string) => string;
+export declare const MATCH_LINE = "[^\\n]*";
+export declare const MATCH_LINE_START = "^\\n*|\\n+";
+export declare const MATCH_LINE_END = "\\n+|$";
+export declare const MATCH_BLOCK = "[\\s\\S]*?";
+export declare const MATCH_BLOCK_START = "^\\n*|\\n+";
+export declare const MATCH_BLOCK_END = "\\n*$|\\n\\n+";
+export declare const MATCH_WORDS = "\\S(?:[\\s\\S]*?\\S)?";
+/** Create regular expression that matches a block of content. */
+export declare const getBlockRegExp: (middle?: string, end?: string, start?: string) => RegExp;
+/** Create regular expression that matches a line of content. */
+export declare const getLineRegExp: (middle?: string, end?: string, start?: string) => RegExp;
+/** Create regular expression that matches piece of text wrapped by a set of characters. */
+export declare const getWrapRegExp: (chars: string, middle?: string) => RegExp;
 /**
- * Match an item matching all words in a query.
- *
- * @param item The item to search for the query in.
- * @param query The query string to search for.
- * - Supports `"compound queries"` with quotes.
+ * Convert a string query to the corresponding set of case-insensitive regular expressions.
+ * - Splies the query into words (respecting "quoted phrases").
+ * - Return a regex for each word or quoted phrase.
+ * - Unquoted words match partially (starting with a word boundary).
+ * - Quoted phrases match fully (starting and ending with a word boundary).
  */
-export declare function MATCHES_ALL(item: unknown, regexps: ImmutableArray<RegExp>): boolean;
+export declare const toWordRegExps: (query: string) => ImmutableArray<RegExp>;
+/** Convert a string to a regular expression matching the start of a word boundary. */
+export declare const toWordRegExp: (word: string) => RegExp;
 /**
  * Match an item matching all words in a query.
  *
@@ -27,17 +39,14 @@ export declare function MATCHES_ALL(item: unknown, regexps: ImmutableArray<RegEx
  * @param query The query string to search for.
  * - Supports `"compound queries"` with quotes.
  */
-export declare function MATCHES_ANY(item: unknown, regexps: ImmutableArray<RegExp>): boolean;
+export declare function matchesAll(item: unknown, regexps: Iterable<RegExp>): boolean;
 /**
- * Convert a string query to the corresponding set of case-insensitive regular expressions.
- * - Splies the query into words (respecting "quoted phrases").
- * - Return a regex for each word or quoted phrase.
- * - Unquoted words match partially (starting with a word boundary).
- * - Quoted phrases match fully (starting and ending with a word boundary).
+ * Match an item any of several regular expressions.
+ *
+ * @param item The item to search for the query in.
+ * @param regexps An iterable set of regular expressions.
  */
-export declare const toWordRegExps: (query: string) => ImmutableArray<RegExp>;
-/** Convert a string to a regular expression matching the start of a word boundary. */
-export declare const toWordRegExp: (word: string) => RegExp;
+export declare function matchesAny(item: unknown, regexps: Iterable<RegExp>): boolean;
 /** Matcher that matches any words in a string. */
 export declare class MatchAnyWord implements Matchable<unknown, void> {
     private _regexps;

package/util/search.js

@@ -1,18 +1,38 @@
-import { toWords, escapeRegExp, normalizeString } from "./string.js";
+import { toWords, normalizeString } from "./string.js";
 /**
- * Match a string against a regular expression.
+ * Convert a string to a regular expression that matches that string.
  *
- * @param item The item to search for the regexp in.
- * - Item is an array: recurse into each item of the array to look for strings that match.
- * - Item is an object: recurse into each property of the object to look for strings that match.
- * - Item is string: match the string against the regular expression.
- * - Item is anything else: return false (can't be matched).
- *
- * @param regexp The `RegExp` instance to match the
+ * @param str The input string.
+ * @param flags RegExp flags that are passed into the created RegExp.
  */
-export function MATCHES(item, regexp) {
-    return typeof item === "string" && !!item.match(regexp);
-}
+export const toRegExp = (str, flags = "") => new RegExp(escapeRegExp(str), flags);
+/** Escape special characters in a string regular expression. */
+export const escapeRegExp = (str) => str.replace(REPLACE_ESCAPED, "\\$&");
+const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;
+// Regular expression partials (`\` slashes must be escaped as `\\`).
+export const MATCH_LINE = "[^\\n]*"; // Match line of content (anything that's not a newline).
+export const MATCH_LINE_START = "^\\n*|\\n+"; // Starts at start of line (one or more linebreak or start of string).
+export const MATCH_LINE_END = "\\n+|$"; // Ends at end of line (one or more linebreak or end of string).
+export const MATCH_BLOCK = "[\\s\\S]*?"; // Match block of content (including newlines so don't be greedy).
+export const MATCH_BLOCK_START = "^\\n*|\\n+"; // Starts at start of a block (one or more linebreak or start of string).
+export const MATCH_BLOCK_END = "\\n*$|\\n\\n+"; // End of a block (two or more linebreaks or end of string).
+export const MATCH_WORDS = `\\S(?:[\\s\\S]*?\\S)?`; // Run of text that starts and ends with non-space characters (possibly multi-line).
+/** Create regular expression that matches a block of content. */
+export const getBlockRegExp = (middle = MATCH_BLOCK, end = MATCH_BLOCK_END, start = MATCH_BLOCK_START) => new RegExp(`(?:${start})${middle}(?:${end})`);
+/** Create regular expression that matches a line of content. */
+export const getLineRegExp = (middle = MATCH_LINE, end = MATCH_LINE_END, start = MATCH_LINE_START) => new RegExp(`(?:${start})${middle}(?:${end})`);
+/** Create regular expression that matches piece of text wrapped by a set of characters. */
+export const getWrapRegExp = (chars, middle = MATCH_WORDS) => new RegExp(`(${chars})(${middle})\\1`);
+/**
+ * Convert a string query to the corresponding set of case-insensitive regular expressions.
+ * - Splies the query into words (respecting "quoted phrases").
+ * - Return a regex for each word or quoted phrase.
+ * - Unquoted words match partially (starting with a word boundary).
+ * - Quoted phrases match fully (starting and ending with a word boundary).
+ */
+export const toWordRegExps = (query) => toWords(query).map(toWordRegExp);
+/** Convert a string to a regular expression matching the start of a word boundary. */
+export const toWordRegExp = (word) => new RegExp(`\\b${escapeRegExp(normalizeString(word))}`, "i");
 /**
  * Match an item matching all words in a query.
  *
@@ -20,46 +40,37 @@ export function MATCHES(item, regexp) {
  * @param query The query string to search for.
  * - Supports `"compound queries"` with quotes.
  */
-export function MATCHES_ALL(item, regexps) {
-    if (typeof item === "string" && regexps.length) {
-        for (const regexp of regexps)
-            if (!item.match(regexp))
+export function matchesAll(item, regexps) {
+    let count = 0;
+    if (typeof item === "string") {
+        for (const regexp of regexps) {
+            count++;
+            if (!regexp.test(item))
                 return false;
-        return true;
+        }
     }
-    return false;
+    return count ? true : false;
 }
 /**
- * Match an item matching all words in a query.
+ * Match an item any of several regular expressions.
  *
  * @param item The item to search for the query in.
- * @param query The query string to search for.
- * - Supports `"compound queries"` with quotes.
+ * @param regexps An iterable set of regular expressions.
  */
-export function MATCHES_ANY(item, regexps) {
+export function matchesAny(item, regexps) {
     if (typeof item === "string")
         for (const regexp of regexps)
-            if (MATCHES(item, regexp))
+            if (regexp.test(item))
                 return true;
     return false;
 }
-/**
- * Convert a string query to the corresponding set of case-insensitive regular expressions.
- * - Splies the query into words (respecting "quoted phrases").
- * - Return a regex for each word or quoted phrase.
- * - Unquoted words match partially (starting with a word boundary).
- * - Quoted phrases match fully (starting and ending with a word boundary).
- */
-export const toWordRegExps = (query) => toWords(query).map(toWordRegExp);
-/** Convert a string to a regular expression matching the start of a word boundary. */
-export const toWordRegExp = (word) => new RegExp(`\\b${escapeRegExp(normalizeString(word))}`, "i");
 /** Matcher that matches any words in a string. */
 export class MatchAnyWord {
     constructor(words) {
         this._regexps = toWordRegExps(words);
     }
     match(value) {
-        return MATCHES_ANY(value, this._regexps);
+        return matchesAny(value, this._regexps);
     }
 }
 /** Matcher that matches all words in a string. */
@@ -68,7 +79,7 @@ export class MatchAllWords {
         this._regexps = toWordRegExps(words);
     }
     match(value) {
-        return MATCHES_ALL(value, this._regexps);
+        return matchesAll(value, this._regexps);
     }
 }
 /** Matcher that matches an exact phrase. */
@@ -77,6 +88,6 @@ export class MatchWord {
         this._regexp = toWordRegExp(phrase);
     }
     match(value) {
-        return MATCHES(value, this._regexp);
+        return this._regexp.test(value);
     }
 }

package/util/string.d.ts

@@ -77,15 +77,6 @@ export declare const toSlug: (str: string) => string;
 export declare const toWords: (str: string) => ImmutableArray<string>;
 /** Find and iterate over the words in a string. */
 export declare function yieldWords(value: string): Generator<string, void, void>;
-/**
- * Convert a string to a regular expression that matches that string.
- *
- * @param str The input string.
- * @param flags RegExp flags that are passed into the created RegExp.
- */
-export declare const toRegExp: (str: string, flags?: string) => RegExp;
-/** Escape special characters in a string regular expression. */
-export declare const escapeRegExp: (str: string) => string;
 /** Is the first character of a string an uppercase letter? */
 export declare const isUppercaseLetter: (str: string) => boolean;
 /** Is the first character of a string a lowercase letter? */

package/util/string.js

@@ -135,16 +135,6 @@ export function* yieldWords(value) {
     }
 }
 const MATCH_WORD = /[^\s"]+|"([^"]*)"/g; // Runs of characters without spaces, or "quoted phrases"
-/**
- * Convert a string to a regular expression that matches that string.
- *
- * @param str The input string.
- * @param flags RegExp flags that are passed into the created RegExp.
- */
-export const toRegExp = (str, flags = "") => new RegExp(escapeRegExp(str), flags);
-/** Escape special characters in a string regular expression. */
-export const escapeRegExp = (str) => str.replace(REPLACE_ESCAPED, "\\$&");
-const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;
 /** Is the first character of a string an uppercase letter? */
 export const isUppercaseLetter = (str) => isBetween(str.charCodeAt(0), 65, 90);
 /** Is the first character of a string a lowercase letter? */