shelving 1.215.0 → 1.215.2

package/extract/TypescriptExtractor.d.ts

@@ -6,7 +6,8 @@ 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`.
- * - Does not set `title` — TS source files have no confident title source. The renderer falls back to `name`.
+ * - 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`.
  */
 export declare class TypescriptExtractor extends FileExtractor {
     extractProps(name: string, text: string): Partial<FileElementProps> & {

package/extract/TypescriptExtractor.js

@@ -7,7 +7,8 @@ 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`.
- * - Does not set `title` — TS source files have no confident title source. The renderer falls back to `name`.
+ * - 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`.
  */
 export class TypescriptExtractor extends FileExtractor {
     extractProps(name, text) {
@@ -22,8 +23,8 @@ export class TypescriptExtractor extends FileExtractor {
             const existing = byKey.get(element.key);
             byKey.set(element.key, existing ? _mergeOverloads(existing, element) : element);
         }
-        // No `title` — TS source files don't have a confident title source (the filename isn't one).
-        // The renderer falls back to `name` when displaying.
+        // 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()) };
     }
 }
@@ -96,6 +97,8 @@ function _extractStatement(statement, source) {
         key: requireSlug(name),
         props: {
             name,
+            // Functions read as callable with `()`; other kinds use the bare name.
+            title: kind === "function" ? `${name}()` : name,
             kind,
             content: _buildJSDocContent(jsDoc?.description, jsDoc?.unhandled),
             signatures: signature ? [signature] : undefined,
@@ -230,7 +233,7 @@ function _getClassMembers(statement, source) {
                 members.push({
                     type: "tree-documentation",
                     key,
-                    props: { name, content, kind: "method", signatures: [signature] },
+                    props: { name, title: `${name}()`, content, kind: "method", signatures: [signature] },
                 });
             }
         }
@@ -239,7 +242,7 @@ function _getClassMembers(statement, source) {
             members.push({
                 type: "tree-documentation",
                 key: requireSlug(name),
-                props: { name, content, kind: "property", signatures: type ? [type] : undefined },
+                props: { name, title: name, content, kind: "property", signatures: type ? [type] : undefined },
             });
         }
     }

package/package.json

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

package/ui/docs/DirectoryCard.d.ts

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface DirectoryCardProps extends DirectoryElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-directory` element. */
-export declare function DirectoryCard({ path, title, name, content }: DirectoryCardProps): ReactNode;
+export declare function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode;
 export {};

package/ui/docs/DirectoryCard.js

@@ -5,7 +5,7 @@ import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 /** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path = "/", title, name, content }) {
+export function DirectoryCard({ path, name, title, content }) {
     const href = joinPath(path, name);
     return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
 }

package/ui/docs/DirectoryCard.tsx

@@ -7,11 +7,11 @@ import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 
 interface DirectoryCardProps extends DirectoryElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path = "/", title, name, content }: DirectoryCardProps): ReactNode {
+export function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>

package/ui/docs/DirectoryPage.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
+import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
 export function DirectoryPage({ title, name, description, content, children }) {
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { children: 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 })] }));
 }

package/ui/docs/DirectoryPage.tsx

@@ -2,11 +2,14 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
+import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
 export function DirectoryPage({ title, name, description, content, children }: DirectoryElementProps): ReactNode {
+	const { url } = requireMeta();
+	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
 			{content && (
@@ -14,7 +17,7 @@ export function DirectoryPage({ title, name, description, content, children }: D
 					<Markup>{content}</Markup>
 				</Prose>
 			)}
-			<TreeCards>{children}</TreeCards>
+			<TreeCards path={path}>{children}</TreeCards>
 		</Page>
 	);
 }

package/ui/docs/DocumentationCard.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface DocumentationCardProps extends DocumentationElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-documentation` element. */
 export declare function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode;

package/ui/docs/DocumentationCard.js

@@ -9,7 +9,7 @@ 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 }) {
+export function DocumentationCard({ path, title, name, kind, content, signatures }) {
     const href = joinPath(path, name);
     return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", 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 }) }))] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -11,11 +11,11 @@ import { Markup } from "../misc/Markup.js";
 import { DocumentationKind } from "./DocumentationKind.js";
 
 interface DocumentationCardProps extends DocumentationElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ path = "/", title, name, kind, content, signatures }: DocumentationCardProps): ReactNode {
+export function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>

package/ui/docs/FileCard.d.ts

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface FileCardProps extends FileElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-file` element. */
-export declare function FileCard({ path, title, name, content }: FileCardProps): ReactNode;
+export declare function FileCard({ path, name, title, content }: FileCardProps): ReactNode;
 export {};

package/ui/docs/FileCard.js

@@ -5,7 +5,7 @@ import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 /** Card renderer for a `tree-file` element. */
-export function FileCard({ path = "/", title, name, content }) {
+export function FileCard({ path, name, title, content }) {
     const href = joinPath(path, name);
     return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
 }

package/ui/docs/FileCard.tsx

@@ -7,11 +7,11 @@ import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 
 interface FileCardProps extends FileElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-file` element. */
-export function FileCard({ path = "/", title, name, content }: FileCardProps): ReactNode {
+export function FileCard({ path, name, title, content }: FileCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>

package/ui/docs/FilePage.js

@@ -7,6 +7,6 @@ import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
 export function FilePage({ title, name, description, content, children }) {
     const { url } = requireMeta();
-    const path = (url?.pathname ?? "/");
+    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 })] }));
 }

package/ui/docs/FilePage.tsx

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
-import type { AbsolutePath } from "../../util/path.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
@@ -10,7 +9,7 @@ import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
 export function FilePage({ title, name, description, content, children }: FileElementProps): ReactNode {
 	const { url } = requireMeta();
-	const path = (url?.pathname ?? "/") as AbsolutePath;
+	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
 			{content && (

package/ui/tree/TreeCards.d.ts

@@ -3,21 +3,21 @@ import { type TreeElements } from "../../util/element.js";
 import type { AbsolutePath } from "../../util/path.js";
 /** Extras threaded through `TreeCardMapper` to every card — currently just the parent URL path. */
 export interface TreeCardExtras {
-    /** URL path of the parent element. Each card computes its own path as `path + mapped.key`. Defaults to `/`. */
-    readonly path?: AbsolutePath | undefined;
+    /** URL path of the parent element. Each card computes its own path as `path + mapped.name`. Defaults to `/`. */
+    readonly path: AbsolutePath;
 }
 /** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
 export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreeCardExtras>>, TreeCardMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreeCardExtras>>;
 export interface TreeCardsProps {
     /** The children to render as cards. */
     readonly children?: TreeElements;
-    /** URL path of the parent element. Each card appends its own key to compute its href. */
+    /** URL path of the parent element. Each card appends its own name to compute its href. */
     readonly path?: AbsolutePath | undefined;
 }
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export declare function TreeCards({ children, path }: TreeCardsProps): ReactNode;
+export declare function TreeCards({ path, children }: TreeCardsProps): ReactNode;

package/ui/tree/TreeCards.js

@@ -13,9 +13,9 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper({
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export function TreeCards({ children, path }) {
+export function TreeCards({ path = "/", children }) {
     return _jsx(TreeCardMapper, { path: path, children: walkElements(children) });
 }

package/ui/tree/TreeCards.tsx

@@ -8,8 +8,8 @@ import { createMapper } from "../misc/Mapper.js";
 
 /** Extras threaded through `TreeCardMapper` to every card — currently just the parent URL path. */
 export interface TreeCardExtras {
-	/** URL path of the parent element. Each card computes its own path as `path + mapped.key`. Defaults to `/`. */
-	readonly path?: AbsolutePath | undefined;
+	/** URL path of the parent element. Each card computes its own path as `path + mapped.name`. Defaults to `/`. */
+	readonly path: AbsolutePath;
 }
 
 /** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
@@ -22,16 +22,16 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper<TreeCardExtras>({
 export interface TreeCardsProps {
 	/** The children to render as cards. */
 	readonly children?: TreeElements;
-	/** URL path of the parent element. Each card appends its own key to compute its href. */
+	/** URL path of the parent element. Each card appends its own name to compute its href. */
 	readonly path?: AbsolutePath | undefined;
 }
 
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export function TreeCards({ children, path }: TreeCardsProps): ReactNode {
+export function TreeCards({ path = "/", children }: TreeCardsProps): ReactNode {
 	return <TreeCardMapper path={path}>{walkElements(children)}</TreeCardMapper>;
 }

package/ui/tree/TreeMenu.d.ts

@@ -9,7 +9,7 @@ export declare const MENU_QUERY: Query<{
 /** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
 interface TreeMenuExtras {
     /** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-    readonly path?: AbsolutePath | undefined;
+    readonly path: AbsolutePath;
 }
 /**
  * Default menu item renderer for any `tree-*` element.
@@ -31,5 +31,5 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export declare function TreeMenu({ tree, path }: TreeMenuProps): ReactNode;
+export declare function TreeMenu({ path, tree }: TreeMenuProps): ReactNode;
 export {};

package/ui/tree/TreeMenu.js

@@ -27,6 +27,6 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export function TreeMenu({ tree, path = "/" }) {
+export function TreeMenu({ path = "/", tree }) {
     return (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: path, children: queryElements(tree.props.children, MENU_QUERY) }) }));
 }

package/ui/tree/TreeMenu.tsx

@@ -12,7 +12,7 @@ export const MENU_QUERY: Query<{ type: string }> = { type: ["tree-directory", "t
 /** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
 interface TreeMenuExtras {
 	/** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-	readonly path?: AbsolutePath | undefined;
+	readonly path: AbsolutePath;
 }
 
 /**
@@ -54,7 +54,7 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export function TreeMenu({ tree, path = "/" }: TreeMenuProps): ReactNode {
+export function TreeMenu({ path = "/", tree }: TreeMenuProps): ReactNode {
 	return (
 		<Menu>
 			<TreeMenuMapper path={path}>{queryElements(tree.props.children, MENU_QUERY)}</TreeMenuMapper>