shelving 1.222.0 → 1.222.2

package/extract/DirectoryExtractor.js

@@ -5,7 +5,7 @@ import { anyMatch, requirePath, splitPath } from "../util/index.js";
 import { requireSlug } from "../util/string.js";
 import { Extractor, mergeTreeElements } from "./Extractor.js";
 import { FileExtractor } from "./FileExtractor.js";
-import { MarkdownExtractor } from "./MarkdownExtractor.js";
+import { MarkupExtractor } from "./MarkupExtractor.js";
 import { TypescriptExtractor } from "./TypescriptExtractor.js";
 /**
  * Default list of filenames patterns treated as the directory's index file.
@@ -15,7 +15,7 @@ import { TypescriptExtractor } from "./TypescriptExtractor.js";
 const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^index\.ts$/i, /^index\.tsx$/i];
 /** Default file extractor dispatch by extension. */
 const DEFAULT_EXTRACTORS = {
-    md: new MarkdownExtractor(),
+    md: new MarkupExtractor(),
     ts: new TypescriptExtractor(),
     tsx: new TypescriptExtractor(),
     txt: new FileExtractor(),

package/extract/Extractor.d.ts

@@ -11,7 +11,7 @@ export declare abstract class Extractor<I, O extends TreeElement = TreeElement>
      * Priority used to resolve same-key collisions when merging elements.
      * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
      * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
-     * - Defaults to `0`; subclasses override (e.g. `MarkdownExtractor` is `10`).
+     * - Defaults to `0`; subclasses override (e.g. `MarkupExtractor` is `10`).
      */
     readonly priority: number;
 }

package/extract/Extractor.js

@@ -9,7 +9,7 @@ export class Extractor {
      * Priority used to resolve same-key collisions when merging elements.
      * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
      * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
-     * - Defaults to `0`; subclasses override (e.g. `MarkdownExtractor` is `10`).
+     * - Defaults to `0`; subclasses override (e.g. `MarkupExtractor` is `10`).
      */
     priority = 0;
 }

package/extract/FileExtractor.d.ts

@@ -7,8 +7,8 @@ import { Extractor } from "./Extractor.js";
  * - Sets `source` to the file's absolute path (`BunFile.name`); throws `RequiredError` if missing or non-absolute.
  * - Sets `name` to the basename without extension, preserving case (e.g. `"OptionalSchema"` from `"OptionalSchema.ts"`); URL paths use `name`.
  * - Sets `key` to the slugified `name` (e.g. `"optionalschema"`) — only used by React for reconciliation and by `DirectoryExtractor` to merge same-key siblings (e.g. `TEMPLATE.md` + `template.ts`).
- * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkdownExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
- * - Subclasses (e.g. `MarkdownExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
+ * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
  */
 export declare class FileExtractor extends Extractor<BunFile, FileElement> {
     extract(file: BunFile): Promise<FileElement>;

package/extract/FileExtractor.js

@@ -9,8 +9,8 @@ import { Extractor } from "./Extractor.js";
  * - Sets `source` to the file's absolute path (`BunFile.name`); throws `RequiredError` if missing or non-absolute.
  * - Sets `name` to the basename without extension, preserving case (e.g. `"OptionalSchema"` from `"OptionalSchema.ts"`); URL paths use `name`.
  * - Sets `key` to the slugified `name` (e.g. `"optionalschema"`) — only used by React for reconciliation and by `DirectoryExtractor` to merge same-key siblings (e.g. `TEMPLATE.md` + `template.ts`).
- * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkdownExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
- * - Subclasses (e.g. `MarkdownExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
+ * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
  */
 export class FileExtractor extends Extractor {
     async extract(file) {

package/extract/MarkupExtractor.d.ts

@@ -0,0 +1,31 @@
+import { type FileElementProps } from "../util/element.js";
+import { FileExtractor } from "./FileExtractor.js";
+/**
+ * File extractor for Markdown files.
+ * - Stores the markdown text as `content`; rendering happens at output time via `<Markup>`.
+ * - Sets `title` from the first `# h1` heading if one is present — otherwise leaves it undefined
+ *   (a confident title only).
+ * - When a `title` is found, strips the leading `# h1` from `content` so renderers (which show
+ *   `title` separately) don't display the heading twice.
+ * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
+ */
+export declare class MarkupExtractor extends FileExtractor {
+    /** Markdown contributes the canonical title/path when merging same-key elements. */
+    readonly priority = 10;
+    extractProps(name: string, text: string): Partial<FileElementProps> & {
+        name: string;
+    };
+}
+/**
+ * Parse a markdown source string once and derive its `title` and `description` in a single pass.
+ * - `title` — plain text of the first `# h1` heading, or `undefined` if there is none.
+ * - `description` — plain-text summary of the first prose paragraph, or `undefined` if there is none.
+ * - Both query the parsed markup tree, so inline syntax (`` `code` ``, `*emphasis*`, links) resolves to clean plain text.
+ *
+ * @param text The markdown source string (a markdown file's text, or a JSDoc description).
+ * @returns An object whose `title` and `description` are each a plain string, or `undefined` when absent.
+ */
+export declare function extractMarkdownProps(text: string): {
+    title: string | undefined;
+    description: string | undefined;
+};

package/extract/MarkupExtractor.js

@@ -0,0 +1,52 @@
+import { MARKUP_PARSER } from "../markup/MarkupParser.js";
+import { getElementText, walkElements } from "../util/element.js";
+import { FileExtractor } from "./FileExtractor.js";
+/**
+ * File extractor for Markdown files.
+ * - Stores the markdown text as `content`; rendering happens at output time via `<Markup>`.
+ * - Sets `title` from the first `# h1` heading if one is present — otherwise leaves it undefined
+ *   (a confident title only).
+ * - When a `title` is found, strips the leading `# h1` from `content` so renderers (which show
+ *   `title` separately) don't display the heading twice.
+ * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
+ */
+export class MarkupExtractor extends FileExtractor {
+    /** Markdown contributes the canonical title/path when merging same-key elements. */
+    priority = 10;
+    extractProps(name, text) {
+        const { title, description } = extractMarkdownProps(text);
+        // The title `# h1` is surfaced separately as `title`, so strip it from the body to avoid rendering it twice.
+        return { name, title, description, content: title ? _stripTitle(text) : text };
+    }
+}
+/**
+ * Parse a markdown source string once and derive its `title` and `description` in a single pass.
+ * - `title` — plain text of the first `# h1` heading, or `undefined` if there is none.
+ * - `description` — plain-text summary of the first prose paragraph, or `undefined` if there is none.
+ * - Both query the parsed markup tree, so inline syntax (`` `code` ``, `*emphasis*`, links) resolves to clean plain text.
+ *
+ * @param text The markdown source string (a markdown file's text, or a JSDoc description).
+ * @returns An object whose `title` and `description` are each a plain string, or `undefined` when absent.
+ */
+export function extractMarkdownProps(text) {
+    let title;
+    let description;
+    // Walk the top-level block elements once, claiming the first `h1` as the title and the first `p` as the description.
+    for (const element of walkElements(MARKUP_PARSER.parse(text))) {
+        if (!title && element.type === "h1")
+            title = _plain(element);
+        else if (!description && element.type === "p")
+            description = _plain(element);
+        if (title && description)
+            break;
+    }
+    return { title, description };
+}
+/** Flatten an element to a single-line plain-text summary, or `undefined` if it has no text. */
+function _plain(element) {
+    return getElementText(element).replace(/\s+/g, " ").trim() || undefined;
+}
+/** Strip a leading `# h1` heading (and any blank lines after it) from markdown text. */
+function _stripTitle(text) {
+    return text.replace(/^\s*#[^\n\S]+\S[^\n]*(?:\n+|$)/, "");
+}

package/extract/TypescriptExtractor.js

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { requireSlug } from "../util/string.js";
 import { FileExtractor } from "./FileExtractor.js";
-import { extractMarkdownDescription } from "./MarkdownExtractor.js";
+import { extractMarkdownProps } from "./MarkupExtractor.js";
 /**
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
@@ -27,7 +27,7 @@ export class TypescriptExtractor extends FileExtractor {
         }
         // The file element itself gets no `title` — a TS source file has no confident title source (the filename isn't one),
         // so renderers fall back to `name`. The `tree-documentation` children each carry their own `title`.
-        return { name, description: extractMarkdownDescription(content ?? ""), content, children: Array.from(byKey.values()) };
+        return { name, description: extractMarkdownProps(content ?? "").description, content, children: Array.from(byKey.values()) };
     }
 }
 /** Merge a newly-extracted overload into the existing documentation element with the same key. */
@@ -102,7 +102,7 @@ function _extractStatement(statement, source) {
             // Functions read as callable with `()`; other kinds use the bare name.
             title: kind === "function" ? `${name}()` : name,
             kind,
-            description: extractMarkdownDescription(jsDoc?.description ?? ""),
+            description: extractMarkdownProps(jsDoc?.description ?? "").description,
             content: _buildJSDocContent(jsDoc?.description, jsDoc?.unhandled),
             signatures: signature ? [signature] : undefined,
             params,
@@ -239,7 +239,7 @@ function _getClassMembers(statement, source) {
                     props: {
                         name,
                         title: `${name}()`,
-                        description: extractMarkdownDescription(memberJSDoc?.description ?? ""),
+                        description: extractMarkdownProps(memberJSDoc?.description ?? "").description,
                         content,
                         kind: "method",
                         signatures: [signature],
@@ -255,7 +255,7 @@ function _getClassMembers(statement, source) {
                 props: {
                     name,
                     title: name,
-                    description: extractMarkdownDescription(memberJSDoc?.description ?? ""),
+                    description: extractMarkdownProps(memberJSDoc?.description ?? "").description,
                     content,
                     kind: "property",
                     signatures: type ? [type] : undefined,

package/extract/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./DirectoryExtractor.js";
 export * from "./Extractor.js";
 export * from "./FileExtractor.js";
-export * from "./MarkdownExtractor.js";
+export * from "./MarkupExtractor.js";
 export * from "./TypescriptExtractor.js";

package/extract/index.js

@@ -1,5 +1,5 @@
 export * from "./DirectoryExtractor.js";
 export * from "./Extractor.js";
 export * from "./FileExtractor.js";
-export * from "./MarkdownExtractor.js";
+export * from "./MarkupExtractor.js";
 export * from "./TypescriptExtractor.js";

package/markup/MarkupParser.js

@@ -238,11 +238,16 @@ function _findFrom(rule, masked, input, from, higher) {
         lo = wallEnd;
     }
 }
-/** Blank the `[start, end)` region of `text` — every character becomes a space, except newlines. */
+// Placeholder a claimed region is blanked to: non-whitespace and non-word, so lower tiers see a
+// masked region as opaque *content* rather than whitespace. Blanking to a space made a leading or
+// trailing code span look like whitespace to inline emphasis (which rejects whitespace at its
+// start/end), so `**`code`**` failed to form. Newlines are kept so block structure survives.
+const _MASK_CHAR = "\u0000";
+/** Blank the `[start, end)` region of `text` — every character becomes `_MASK_CHAR`, except newlines. */
 function _mask(text, start, end) {
     let blanked = "";
     for (let i = start; i < end; i++)
-        blanked += text[i] === "\n" ? "\n" : " ";
+        blanked += text[i] === "\n" ? "\n" : _MASK_CHAR;
     return `${text.slice(0, start)}${blanked}${text.slice(end)}`;
 }
 /** MarkupParser sentinel with the default markup rules */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.222.0",
+	"version": "1.222.2",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/docs/DirectoryPage.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
+import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
@@ -8,5 +9,5 @@ import { TreeCards } from "../tree/TreeCards.js";
 export function DirectoryPage({ title, name, description, content, children }) {
     const { url } = requireMeta();
     const path = url?.pathname ?? "/";
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/DirectoryPage.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { Prose } from "../block/Prose.js";
+import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
@@ -12,6 +13,7 @@ export function DirectoryPage({ title, name, description, content, children }: D
 	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
+			<Title>{title ?? name}</Title>
 			{content && (
 				<Prose>
 					<Markup>{content}</Markup>

package/ui/docs/FilePage.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
+import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
@@ -8,5 +9,5 @@ import { TreeCards } from "../tree/TreeCards.js";
 export function FilePage({ title, name, description, content, children }) {
     const { url } = requireMeta();
     const path = url?.pathname ?? "/";
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/FilePage.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
 import { Prose } from "../block/Prose.js";
+import { Title } from "../block/Title.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
@@ -12,6 +13,7 @@ export function FilePage({ title, name, description, content, children }: FileEl
 	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
+			<Title>{title ?? name}</Title>
 			{content && (
 				<Prose>
 					<Markup>{content}</Markup>

package/util/element.d.ts

@@ -41,7 +41,7 @@ export interface TreeElementProps extends ElementProps {
     /**
      * Markup source string that should be rendered as the element's visible body content.
      * - Rendered via the `<Markup>` component (typically inside a `<Prose>` wrapper).
-     * - For Markdown files this is the file's text; for TypeScript symbols this is the JSDoc description.
+     * - For Markdown files this is the file's body (the title `# h1` is lifted into `title`); for TypeScript symbols this is the JSDoc description.
      */
     readonly content?: string | undefined;
     /** Children of a tree element must be other tree elements. */
@@ -153,6 +153,7 @@ export declare function isElement(value: unknown): value is Element;
 export declare function isElements(value: unknown): value is Elements;
 /**
  * Strip all tags from elements to produce a plain text string.
+ * - A `<br>` element becomes a newline (`\n`) — matching DOM `innerText`, so words either side of a line break don't fuse together.
  *
  * @param elements An element, a plain string, or null/undefined (or an array of those things).
  * @returns The combined string made from the elements.

package/util/element.js

@@ -11,6 +11,7 @@ export function isElements(value) {
 }
 /**
  * Strip all tags from elements to produce a plain text string.
+ * - A `<br>` element becomes a newline (`\n`) — matching DOM `innerText`, so words either side of a line break don't fuse together.
  *
  * @param elements An element, a plain string, or null/undefined (or an array of those things).
  * @returns The combined string made from the elements.
@@ -20,8 +21,12 @@ export function isElements(value) {
 export function getElementText(elements) {
     if (typeof elements === "string")
         return elements;
-    if (isElement(elements))
+    if (isElement(elements)) {
+        // A `<br>` carries no children but renders as a line break — emit `\n` so adjacent words stay separated.
+        if (elements.type === "br")
+            return "\n";
         return getElementText(elements.props.children);
+    }
     // Iterate the collection directly — `walkElements()` skips loose strings, so it would drop text that sits alongside elements.
     if (isIterable(elements)) {
         let text = "";

package/extract/MarkdownExtractor.d.ts

@@ -1,28 +0,0 @@
-import { type FileElementProps } from "../util/element.js";
-import { FileExtractor } from "./FileExtractor.js";
-/**
- * File extractor for Markdown files.
- * - Stores the raw markdown text as `content`; rendering happens at output time via `<Markup>`.
- * - Sets `title` from the first `# h1` heading if one is present — otherwise leaves it undefined
- *   (a confident title only).
- * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
- */
-export declare class MarkdownExtractor extends FileExtractor {
-    /** Markdown contributes the canonical title/path when merging same-key elements. */
-    readonly priority = 10;
-    extractProps(name: string, text: string): Partial<FileElementProps> & {
-        name: string;
-    };
-}
-/**
- * Find the first `# h1` heading in a markdown source string and return its text, or `undefined` if none.
- * - Looks for a line starting with a single `#` followed by whitespace; doesn't match `##`+.
- */
-export declare function extractMarkdownTitle(text: string): string | undefined;
-/**
- * Find the first prose paragraph in a markdown source string and return it as a plain-text summary, or `undefined` if none.
- * - Skips headings, fenced code blocks, and blank lines, then collects the first ordinary paragraph.
- * - Renders that paragraph as markup and strips every tag, so inline syntax (`` `code` ``, `*emphasis*`, links) becomes plain text.
- * - Collapses internal whitespace so the result is a single line suitable for a `description` / `<meta>` summary.
- */
-export declare function extractMarkdownDescription(text: string): string | undefined;

package/extract/MarkdownExtractor.js

@@ -1,58 +0,0 @@
-import { MARKUP_PARSER } from "../markup/MarkupParser.js";
-import { getElementText } from "../util/element.js";
-import { FileExtractor } from "./FileExtractor.js";
-/**
- * File extractor for Markdown files.
- * - Stores the raw markdown text as `content`; rendering happens at output time via `<Markup>`.
- * - Sets `title` from the first `# h1` heading if one is present — otherwise leaves it undefined
- *   (a confident title only).
- * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
- */
-export class MarkdownExtractor extends FileExtractor {
-    /** Markdown contributes the canonical title/path when merging same-key elements. */
-    priority = 10;
-    extractProps(name, text) {
-        return { name, title: extractMarkdownTitle(text), description: extractMarkdownDescription(text), content: text };
-    }
-}
-/**
- * Find the first `# h1` heading in a markdown source string and return its text, or `undefined` if none.
- * - Looks for a line starting with a single `#` followed by whitespace; doesn't match `##`+.
- */
-export function extractMarkdownTitle(text) {
-    const match = text.match(/^#\s+(.+?)\s*$/m);
-    return match?.[1];
-}
-/**
- * Find the first prose paragraph in a markdown source string and return it as a plain-text summary, or `undefined` if none.
- * - Skips headings, fenced code blocks, and blank lines, then collects the first ordinary paragraph.
- * - Renders that paragraph as markup and strips every tag, so inline syntax (`` `code` ``, `*emphasis*`, links) becomes plain text.
- * - Collapses internal whitespace so the result is a single line suitable for a `description` / `<meta>` summary.
- */
-export function extractMarkdownDescription(text) {
-    const paragraph = [];
-    let fenced = false;
-    for (const line of text.split("\n")) {
-        const trimmed = line.trim();
-        // Toggle in/out of fenced code blocks — never treat their contents as the summary.
-        if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
-            fenced = !fenced;
-            continue;
-        }
-        if (fenced)
-            continue;
-        // A blank line or heading ends the first paragraph (or is skipped while still searching for it).
-        if (!trimmed || trimmed.startsWith("#")) {
-            if (paragraph.length)
-                break;
-            continue;
-        }
-        paragraph.push(trimmed);
-    }
-    if (!paragraph.length)
-        return;
-    // Render the paragraph as markup then strip every tag, so inline syntax resolves to clean plain text.
-    const rendered = MARKUP_PARSER.parse(paragraph.join(" "));
-    const summary = getElementText(rendered).replace(/\s+/g, " ").trim();
-    return summary || undefined;
-}