shelving 1.222.1 → 1.222.3

package/extract/MarkupExtractor.d.ts

@@ -2,9 +2,11 @@ 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>`.
+ * - 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 {

package/extract/MarkupExtractor.js

@@ -3,9 +3,11 @@ import { getElementText, walkElements } 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>`.
+ * - 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 {
@@ -13,7 +15,8 @@ export class MarkupExtractor extends FileExtractor {
     priority = 10;
     extractProps(name, text) {
         const { title, description } = extractMarkdownProps(text);
-        return { name, title, description, content: 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 };
     }
 }
 /**
@@ -43,3 +46,7 @@ export function extractMarkdownProps(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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.222.1",
+	"version": "1.222.3",
 	"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/DocumentationCard.js

@@ -10,5 +10,5 @@ import { DocumentationKind } from "./DocumentationKind.js";
 /** 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))), description && _jsx(Paragraph, { children: description })] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, wrap: 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

@@ -19,7 +19,7 @@ export function DocumentationCard({ path, title, name, kind, description, signat
 	return (
 		<Card href={href}>
 			<Subheading>
-				<Flex left>
+				<Flex left wrap>
 					<Code>{title ?? name}</Code>
 					{kind && <DocumentationKind kind={kind} />}
 				</Flex>

package/ui/docs/DocumentationPage.js

@@ -33,7 +33,7 @@ const KIND_SECTIONS = [
 export function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }) {
     const { url } = requireMeta();
     const path = (url?.pathname ?? "/");
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), KIND_SECTIONS.map(([kind, label]) => {
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), KIND_SECTIONS.map(([kind, label]) => {
                 // Pre-filter the children for this kind; only render the section when it has cards.
                 const group = Array.from(queryElements(children, { "props.kind": kind }));
                 return group.length ? (_jsxs(Section, { children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { path: path, children: group })] }, kind)) : null;

package/ui/docs/DocumentationPage.tsx

@@ -53,7 +53,7 @@ export function DocumentationPage({
 	return (
 		<Page title={title ?? name} description={description}>
 			<Title>
-				<Flex left>
+				<Flex left wrap>
 					{title ?? name}
 					{kind && <DocumentationKind kind={kind} />}
 				</Flex>

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/ui/misc/Tag.module.css

@@ -1,5 +1,11 @@
 .tag {
 	display: inline-block;
+	flex: 0 0 fit-content; /* Content-width; never grow or shrink, like icons. */
+	/* Truncate overlong text instead of overflowing the container. */
+	max-width: 100%;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
 	padding: 0 var(--space-xxsmall);
 	border: 0;
 	border-radius: var(--radius-xxsmall);

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. */