shelving 1.216.2 → 1.217.0

package/extract/MarkdownExtractor.d.ts

@@ -1,10 +1,11 @@
-import type { FileElementProps } from "../util/element.js";
+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. */
@@ -18,3 +19,10 @@ export declare class MarkdownExtractor extends FileExtractor {
  * - 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,15 +1,19 @@
+import { renderMarkup } from "../markup/render.js";
+import { MARKUP_OPTIONS } from "../markup/rule/index.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), content: text };
+        return { name, title: extractMarkdownTitle(text), description: extractMarkdownDescription(text), content: text };
     }
 }
 /**
@@ -20,3 +24,36 @@ 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 = renderMarkup(paragraph.join(" "), MARKUP_OPTIONS);
+    const summary = getElementText(rendered).replace(/\s+/g, " ").trim();
+    return summary || undefined;
+}

package/extract/TypescriptExtractor.d.ts

@@ -6,6 +6,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Top-of-file JSDoc comment becomes the file's `content`.
+ * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, `name` for other kinds.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
  */

package/extract/TypescriptExtractor.js

@@ -1,12 +1,14 @@
 import ts from "typescript";
 import { requireSlug } from "../util/string.js";
 import { FileExtractor } from "./FileExtractor.js";
+import { extractMarkdownDescription } from "./MarkdownExtractor.js";
 /**
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Top-of-file JSDoc comment becomes the file's `content`.
+ * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, `name` for other kinds.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
  */
@@ -25,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, content, children: Array.from(byKey.values()) };
+        return { name, description: extractMarkdownDescription(content ?? ""), content, children: Array.from(byKey.values()) };
     }
 }
 /** Merge a newly-extracted overload into the existing documentation element with the same key. */
@@ -100,6 +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 ?? ""),
             content: _buildJSDocContent(jsDoc?.description, jsDoc?.unhandled),
             signatures: signature ? [signature] : undefined,
             params,
@@ -233,7 +236,14 @@ function _getClassMembers(statement, source) {
                 members.push({
                     type: "tree-documentation",
                     key,
-                    props: { name, title: `${name}()`, content, kind: "method", signatures: [signature] },
+                    props: {
+                        name,
+                        title: `${name}()`,
+                        description: extractMarkdownDescription(memberJSDoc?.description ?? ""),
+                        content,
+                        kind: "method",
+                        signatures: [signature],
+                    },
                 });
             }
         }
@@ -242,7 +252,14 @@ function _getClassMembers(statement, source) {
             members.push({
                 type: "tree-documentation",
                 key: requireSlug(name),
-                props: { name, title: name, content, kind: "property", signatures: type ? [type] : undefined },
+                props: {
+                    name,
+                    title: name,
+                    description: extractMarkdownDescription(memberJSDoc?.description ?? ""),
+                    content,
+                    kind: "property",
+                    signatures: type ? [type] : undefined,
+                },
             });
         }
     }

package/package.json

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

package/ui/app/App.module.css

@@ -14,7 +14,7 @@
 
 	/* Font faces */
 	--font-sans: system-ui;
-	--font-mono: "Courier New", "Courier", monospace;
+	--font-mono: ui-monospace, "SF Mono", "Consolas", "Menlo", monospace;
 	--font-serif: "Palatino", "Garamond", serif;
 
 	/* Semantic font faces */

package/ui/docs/DirectoryCard.d.ts

@@ -4,6 +4,6 @@ import { type AbsolutePath } from "../../util/path.js";
 interface DirectoryCardProps extends DirectoryElementProps {
     path: AbsolutePath;
 }
-/** Card renderer for a `tree-directory` element. */
-export declare function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode;
+/** Card renderer for a `tree-directory` element — a summary card showing the heading and description. */
+export declare function DirectoryCard({ path, name, title, description }: DirectoryCardProps): ReactNode;
 export {};

package/ui/docs/DirectoryCard.js

@@ -1,11 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Prose } from "../block/Prose.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
-import { Markup } from "../misc/Markup.js";
-/** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path, name, title, content }) {
+/** Card renderer for a `tree-directory` element — a summary card showing the heading and description. */
+export function DirectoryCard({ path, name, title, description }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), description && _jsx(Paragraph, { children: description })] }));
 }

package/ui/docs/DirectoryCard.tsx

@@ -2,25 +2,20 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Prose } from "../block/Prose.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
-import { Markup } from "../misc/Markup.js";
 
 interface DirectoryCardProps extends DirectoryElementProps {
 	path: AbsolutePath;
 }
 
-/** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode {
+/** Card renderer for a `tree-directory` element — a summary card showing the heading and description. */
+export function DirectoryCard({ path, name, title, description }: DirectoryCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
 			<Subheading>{title ?? name}</Subheading>
-			{content && (
-				<Prose>
-					<Markup>{content}</Markup>
-				</Prose>
-			)}
+			{description && <Paragraph>{description}</Paragraph>}
 		</Card>
 	);
 }

package/ui/docs/DocumentationCard.d.ts

@@ -4,6 +4,6 @@ import { type AbsolutePath } from "../../util/path.js";
 interface DocumentationCardProps extends DocumentationElementProps {
     path: AbsolutePath;
 }
-/** Card renderer for a `tree-documentation` element. */
-export declare function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode;
+/** Card renderer for a `tree-documentation` element — a summary card showing the heading, signatures, and description. */
+export declare function DocumentationCard({ path, title, name, kind, description, signatures }: DocumentationCardProps): ReactNode;
 export {};

package/ui/docs/DocumentationCard.js

@@ -2,14 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
 import { Flex } from "../block/Flex.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Preformatted } from "../block/Preformatted.js";
-import { Prose } from "../block/Prose.js";
 import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
-import { Markup } from "../misc/Markup.js";
 import { DocumentationKind } from "./DocumentationKind.js";
-/** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ path, title, name, kind, content, signatures }) {
+/** Card renderer for a `tree-documentation` element — a summary card showing the heading, signatures, and description. */
+export function DocumentationCard({ path, title, name, kind, description, signatures }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), description && _jsx(Paragraph, { children: description })] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -3,19 +3,18 @@ import type { DocumentationElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
 import { Flex } from "../block/Flex.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Preformatted } from "../block/Preformatted.js";
-import { Prose } from "../block/Prose.js";
 import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
-import { Markup } from "../misc/Markup.js";
 import { DocumentationKind } from "./DocumentationKind.js";
 
 interface DocumentationCardProps extends DocumentationElementProps {
 	path: AbsolutePath;
 }
 
-/** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode {
+/** Card renderer for a `tree-documentation` element — a summary card showing the heading, signatures, and description. */
+export function DocumentationCard({ path, title, name, kind, description, signatures }: DocumentationCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
@@ -28,11 +27,7 @@ export function DocumentationCard({ path, title, name, kind, content, signatures
 			{signatures?.map(sig => (
 				<Preformatted key={sig}>{sig}</Preformatted>
 			))}
-			{content && (
-				<Prose>
-					<Markup>{content}</Markup>
-				</Prose>
-			)}
+			{description && <Paragraph>{description}</Paragraph>}
 		</Card>
 	);
 }

package/ui/docs/FileCard.d.ts

@@ -4,6 +4,6 @@ import { type AbsolutePath } from "../../util/path.js";
 interface FileCardProps extends FileElementProps {
     path: AbsolutePath;
 }
-/** Card renderer for a `tree-file` element. */
-export declare function FileCard({ path, name, title, content }: FileCardProps): ReactNode;
+/** Card renderer for a `tree-file` element — a summary card showing the heading and description. */
+export declare function FileCard({ path, name, title, description }: FileCardProps): ReactNode;
 export {};

package/ui/docs/FileCard.js

@@ -1,11 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Prose } from "../block/Prose.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
-import { Markup } from "../misc/Markup.js";
-/** Card renderer for a `tree-file` element. */
-export function FileCard({ path, name, title, content }) {
+/** Card renderer for a `tree-file` element — a summary card showing the heading and description. */
+export function FileCard({ path, name, title, description }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), description && _jsx(Paragraph, { children: description })] }));
 }

package/ui/docs/FileCard.tsx

@@ -2,25 +2,20 @@ import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Prose } from "../block/Prose.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
-import { Markup } from "../misc/Markup.js";
 
 interface FileCardProps extends FileElementProps {
 	path: AbsolutePath;
 }
 
-/** Card renderer for a `tree-file` element. */
-export function FileCard({ path, name, title, content }: FileCardProps): ReactNode {
+/** Card renderer for a `tree-file` element — a summary card showing the heading and description. */
+export function FileCard({ path, name, title, description }: FileCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
 			<Subheading>{title ?? name}</Subheading>
-			{content && (
-				<Prose>
-					<Markup>{content}</Markup>
-				</Prose>
-			)}
+			{description && <Paragraph>{description}</Paragraph>}
 		</Card>
 	);
 }

package/ui/inline/Code.module.css

@@ -10,6 +10,6 @@
 	background-color: var(--color-surface);
 
 	/* Typography */
-	font-weight: var(--weight-normal);
+	font-weight: inherit;
 	font-size: var(--size-smaller);
 }

package/util/element.js

@@ -22,7 +22,14 @@ export function getElementText(elements) {
         return elements;
     if (isElement(elements))
         return getElementText(elements.props.children);
-    return Array.from(walkElements(elements)).map(getElementText).join("");
+    // Iterate the collection directly — `walkElements()` skips loose strings, so it would drop text that sits alongside elements.
+    if (isIterable(elements)) {
+        let text = "";
+        for (const child of elements)
+            text += getElementText(child);
+        return text;
+    }
+    return "";
 }
 export function* walkElements(elements) {
     if (isElement(elements))