@terra-symposium/docs 0.1.73 → 0.1.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-	"version": "0.1.73",
+  "version": "0.1.75",
   "description": "Terra Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -73,6 +73,7 @@
     "@types/sanitize-html": "^2.16.2",
     "@vitejs/plugin-react": "6.1.2",
     "eslint": "10.13.0",
+    "globals": "^16.5.0",
     "husky": "^9.1.7",
     "postcss": "8.5.31",
     "postcss-import": "15.1.0",

package/site/astro.config.mjs

@@ -13,59 +13,61 @@ const packageRoot = fileURLToPath(new URL('../', import.meta.url));
 const requireFromPackage = createRequire(import.meta.url);
 const projectRoot = process.env.TERRA_DOCS_ROOT ?? process.cwd();
 const publicDir = resolve(projectRoot, '.terra-docs/public');
-const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'docs-dist');
+const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'dist/docs');
 const site = process.env.TERRA_DOCS_SITE;
 const base = process.env.TERRA_DOCS_BASE ?? '/';
 const projectManifest = (() => {
-	try {
-		return JSON.parse(readFileSync(resolve(projectRoot, 'package.json'), 'utf8'));
-	} catch {
-		return {};
-	}
+  try {
+    return JSON.parse(readFileSync(resolve(projectRoot, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
 })();
 
 function packageExportAliases() {
-	if (!projectManifest.name || !projectManifest.exports) return [];
-	const escapeRegex = (value) => value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
-	return Object.entries(projectManifest.exports).flatMap(([key, value]) => {
-		const target = typeof value === 'string' ? value : value?.import ?? value?.default;
-		if (!target?.startsWith('./')) return [];
-		const prefix = projectManifest.name + (key === '.' ? '' : key.slice(1));
-		if (key.includes('*')) {
-			const matcher = new RegExp(`^${escapeRegex(prefix).replace('*', '(.+)')}$`);
-			return [{ find: matcher, replacement: resolve(projectRoot, target.replace('*', '$1')) }];
-		}
-		return [{ find: new RegExp(`^${escapeRegex(prefix)}$`), replacement: resolve(projectRoot, target) }];
-	});
+  if (!projectManifest.name || !projectManifest.exports) return [];
+  const escapeRegex = (value) => value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+  return Object.entries(projectManifest.exports).flatMap(([key, value]) => {
+    const target = typeof value === 'string' ? value : (value?.import ?? value?.default);
+    if (!target?.startsWith('./')) return [];
+    const prefix = projectManifest.name + (key === '.' ? '' : key.slice(1));
+    if (key.includes('*')) {
+      const matcher = new RegExp(`^${escapeRegex(prefix).replace('*', '(.+)')}$`);
+      return [{ find: matcher, replacement: resolve(projectRoot, target.replace('*', '$1')) }];
+    }
+    return [
+      { find: new RegExp(`^${escapeRegex(prefix)}$`), replacement: resolve(projectRoot, target) },
+    ];
+  });
 }
 
 const packageDependencyResolver = {
-	name: 'terra-docs-package-dependencies',
-	enforce: 'pre',
-	resolveId(source) {
-		if (!/^(?:astro|@astrojs\/(?:markdown-remark|mdx|react))(?:\/|$)/.test(source)) return null;
-		try {
-			return requireFromPackage.resolve(source);
-		} catch {
-			return null;
-		}
-	},
+  name: 'terra-docs-package-dependencies',
+  enforce: 'pre',
+  resolveId(source) {
+    if (!/^(?:astro|@astrojs\/(?:markdown-remark|mdx|react))(?:\/|$)/.test(source)) return null;
+    try {
+      return requireFromPackage.resolve(source);
+    } catch {
+      return null;
+    }
+  },
 };
 
 export default defineConfig({
-	root: projectRoot,
-	srcDir: resolve(packageRoot, 'site/src'),
-	publicDir,
-	outDir,
-	...(site ? { site } : {}),
-	base,
-	devToolbar: { enabled: false },
-	build: { format: 'directory' },
-	integrations: [react(), mdx()],
-	markdown: { processor: unified({ remarkPlugins: [[basePathRemarkPlugin, { base }]] }) },
-	vite: {
-		plugins: [packageDependencyResolver, docsContentPlugin({ root: projectRoot, base })],
-		resolve: { alias: packageExportAliases() },
-		server: { fs: { allow: [projectRoot, packageRoot] } },
-	},
+  root: projectRoot,
+  srcDir: resolve(packageRoot, 'site/src'),
+  publicDir,
+  outDir,
+  ...(site ? { site } : {}),
+  base,
+  devToolbar: { enabled: false },
+  build: { format: 'directory' },
+  integrations: [react({ experimentalDisableStreaming: true }), mdx()],
+  markdown: { processor: unified({ remarkPlugins: [[basePathRemarkPlugin, { base }]] }) },
+  vite: {
+    plugins: [packageDependencyResolver, docsContentPlugin({ root: projectRoot, base })],
+    resolve: { alias: packageExportAliases() },
+    server: { fs: { allow: [projectRoot, packageRoot] } },
+  },
 });

package/site/base-path-remark-plugin.mjs

@@ -1,31 +1,38 @@
 function addBasePath(value, base) {
-	if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || base === '/') return value;
-	const basePath = `/${base.replace(/^\/+|\/+$/g, '')}`;
-	if (value === basePath) return `${basePath}/`;
-	if (value.startsWith(`${basePath}/`)) return value;
-	return `${basePath}${value}`;
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || base === '/')
+    return value;
+  const basePath = `/${base.replace(/^\/+|\/+$/g, '')}`;
+  if (value === basePath) return `${basePath}/`;
+  if (value.startsWith(`${basePath}/`)) return value;
+  return `${basePath}${value}`;
 }
 
 function addBaseToHtml(source, base) {
-	return source.replace(/\b(href|src)=(['"])(\/[^'"#?]*)([^'"]*)\2/gi, (_match, attribute, quote, pathname, suffix) =>
-		`${attribute}=${quote}${addBasePath(`${pathname}${suffix}`, base)}${quote}`,
-	);
+  return source.replace(
+    /\b(href|src)=(['"])(\/[^'"#?]*)([^'"]*)\2/gi,
+    (_match, attribute, quote, pathname, suffix) =>
+      `${attribute}=${quote}${addBasePath(`${pathname}${suffix}`, base)}${quote}`,
+  );
 }
 
 export function basePathRemarkPlugin({ base }) {
-	return (tree) => {
-		const visit = (node) => {
-			if (['link', 'image', 'definition'].includes(node.type) && typeof node.url === 'string') {
-				node.url = addBasePath(node.url, base);
-			}
-			if (node.type === 'html' && typeof node.value === 'string') {
-				node.value = addBaseToHtml(node.value, base);
-			}
-			if (node.type === 'mdxJsxAttribute' && ['href', 'src'].includes(node.name) && typeof node.value === 'string') {
-				node.value = addBasePath(node.value, base);
-			}
-			for (const child of node.children ?? []) visit(child);
-		};
-		visit(tree);
-	};
+  return (tree) => {
+    const visit = (node) => {
+      if (['link', 'image', 'definition'].includes(node.type) && typeof node.url === 'string') {
+        node.url = addBasePath(node.url, base);
+      }
+      if (node.type === 'html' && typeof node.value === 'string') {
+        node.value = addBaseToHtml(node.value, base);
+      }
+      if (
+        node.type === 'mdxJsxAttribute' &&
+        ['href', 'src'].includes(node.name) &&
+        typeof node.value === 'string'
+      ) {
+        node.value = addBasePath(node.value, base);
+      }
+      for (const child of node.children ?? []) visit(child);
+    };
+    visit(tree);
+  };
 }

package/site/docs-content-plugin.mjs

@@ -4,70 +4,81 @@ import { extname, relative, resolve, sep } from 'node:path';
 const markdownExtensions = new Set(['.md', '.mdx']);
 
 function publicRoute(file, docsRoot, base) {
-	const path = relative(docsRoot, file).split(sep).join('/').replace(/\.(?:md|mdx)$/i, '');
-	const route = path.replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
-	return `${base}${route ? `${route}/` : ''}`;
+  const path = relative(docsRoot, file)
+    .split(sep)
+    .join('/')
+    .replace(/\.(?:md|mdx)$/i, '');
+  const route = path.replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
+  return `${base}${route ? `${route}/` : ''}`;
 }
 
 function rewriteTarget(rawTarget, sourceFile, docsRoot, base) {
-	const target = rawTarget.trim();
-	if (!target || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(target)) return rawTarget;
-	const match = /^(<[^>]+>|[^\s]+)([\s\S]*)$/.exec(target);
-	if (!match) return rawTarget;
-	const bracketed = match[1].startsWith('<') && match[1].endsWith('>');
-	const pathname = bracketed ? match[1].slice(1, -1) : match[1];
-	const suffix = match[2];
-	const [filePath, ...hashParts] = pathname.split('#');
-	const [cleanPath, ...queryParts] = filePath.split('?');
-	const fragment = hashParts.length ? `#${hashParts.join('#')}` : '';
-	const query = queryParts.length ? `?${queryParts.join('?')}` : '';
-	if (cleanPath.startsWith('/')) {
-		const basePath = base === '/' ? '' : `/${base.replace(/^\/+|\/+$/g, '')}`;
-		const rootBase = `${basePath}/`;
-		const routedPath = base === '/' || cleanPath.startsWith(rootBase)
-			? cleanPath
-			: cleanPath === basePath
-				? rootBase
-				: `${basePath}${cleanPath}`;
-		const rewritten = `${routedPath}${query}${fragment}`;
-		return `${bracketed ? `<${rewritten}>` : rewritten}${suffix}`;
-	}
-	let resolvedPath;
-	try {
-		resolvedPath = resolve(sourceFile, '..', decodeURIComponent(cleanPath));
-	} catch {
-		return rawTarget;
-	}
-	const relativePath = relative(docsRoot, resolvedPath);
-	if (relativePath.startsWith(`..${sep}`) || relativePath === '..' || !existsSync(resolvedPath)) return rawTarget;
-	const extension = extname(resolvedPath).toLowerCase();
-	const rewritten = markdownExtensions.has(extension)
-		? publicRoute(resolvedPath, docsRoot, base)
-		: `${base}_terra-docs/assets/${relativePath.split(sep).join('/')}`;
-	return `${bracketed ? `<${rewritten}${query}${fragment}>` : `${rewritten}${query}${fragment}`}${suffix}`;
+  const target = rawTarget.trim();
+  if (!target || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(target)) return rawTarget;
+  const match = /^(<[^>]+>|[^\s]+)([\s\S]*)$/.exec(target);
+  if (!match) return rawTarget;
+  const bracketed = match[1].startsWith('<') && match[1].endsWith('>');
+  const pathname = bracketed ? match[1].slice(1, -1) : match[1];
+  const suffix = match[2];
+  const [filePath, ...hashParts] = pathname.split('#');
+  const [cleanPath, ...queryParts] = filePath.split('?');
+  const fragment = hashParts.length ? `#${hashParts.join('#')}` : '';
+  const query = queryParts.length ? `?${queryParts.join('?')}` : '';
+  if (cleanPath.startsWith('/')) {
+    const basePath = base === '/' ? '' : `/${base.replace(/^\/+|\/+$/g, '')}`;
+    const rootBase = `${basePath}/`;
+    const routedPath =
+      base === '/' || cleanPath.startsWith(rootBase)
+        ? cleanPath
+        : cleanPath === basePath
+          ? rootBase
+          : `${basePath}${cleanPath}`;
+    const rewritten = `${routedPath}${query}${fragment}`;
+    return `${bracketed ? `<${rewritten}>` : rewritten}${suffix}`;
+  }
+  let resolvedPath;
+  try {
+    resolvedPath = resolve(sourceFile, '..', decodeURIComponent(cleanPath));
+  } catch {
+    return rawTarget;
+  }
+  const relativePath = relative(docsRoot, resolvedPath);
+  if (relativePath.startsWith(`..${sep}`) || relativePath === '..' || !existsSync(resolvedPath))
+    return rawTarget;
+  const extension = extname(resolvedPath).toLowerCase();
+  const rewritten = markdownExtensions.has(extension)
+    ? publicRoute(resolvedPath, docsRoot, base)
+    : `${base}_terra-docs/assets/${relativePath.split(sep).join('/')}`;
+  return `${bracketed ? `<${rewritten}${query}${fragment}>` : `${rewritten}${query}${fragment}`}${suffix}`;
 }
 
 function mapOutsideCode(source, callback) {
-	const sections = source.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~)/g);
-	return sections.map((section, index) => index % 2 ? section : callback(section)).join('');
+  const sections = source.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~)/g);
+  return sections.map((section, index) => (index % 2 ? section : callback(section))).join('');
 }
 
 export function docsContentPlugin({ root, base }) {
-	const docsRoot = resolve(root, 'docs');
-	return {
-		name: 'terra-docs-content-assets',
-		enforce: 'pre',
-		transform(source, id) {
-			if (id.includes('?') || !markdownExtensions.has(extname(id).toLowerCase())) return null;
-			const sourceFile = resolve(id);
-			const relativePath = relative(docsRoot, sourceFile);
-			if (relativePath.startsWith(`..${sep}`) || relativePath === '..') return null;
-			const withMarkdownLinks = source.replace(/(!?\[[^\]]*\]\()([^)]+)(\))/g, (_full, before, target, after) =>
-				`${before}${rewriteTarget(target, sourceFile, docsRoot, base)}${after}`,
-			);
-			return mapOutsideCode(withMarkdownLinks, (section) => section.replace(/\b(src|href)=(['"])(.*?)\2/g, (full, attribute, quote, target) =>
-				`${attribute}=${quote}${rewriteTarget(target, sourceFile, docsRoot, base)}${quote}`,
-			));
-		},
-	};
+  const docsRoot = resolve(root, 'docs');
+  return {
+    name: 'terra-docs-content-assets',
+    enforce: 'pre',
+    transform(source, id) {
+      if (id.includes('?') || !markdownExtensions.has(extname(id).toLowerCase())) return null;
+      const sourceFile = resolve(id);
+      const relativePath = relative(docsRoot, sourceFile);
+      if (relativePath.startsWith(`..${sep}`) || relativePath === '..') return null;
+      const withMarkdownLinks = source.replace(
+        /(!?\[[^\]]*\]\()([^)]+)(\))/g,
+        (_full, before, target, after) =>
+          `${before}${rewriteTarget(target, sourceFile, docsRoot, base)}${after}`,
+      );
+      return mapOutsideCode(withMarkdownLinks, (section) =>
+        section.replace(
+          /\b(src|href)=(['"])(.*?)\2/g,
+          (full, attribute, quote, target) =>
+            `${attribute}=${quote}${rewriteTarget(target, sourceFile, docsRoot, base)}${quote}`,
+        ),
+      );
+    },
+  };
 }

package/site/src/components/DocsSiteSearch.tsx

@@ -1,108 +1,123 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 
 type SearchDocument = {
-	title: string;
-	description: string;
-	href: string;
-	text: string;
+  title: string;
+  description: string;
+  href: string;
+  text: string;
 };
 
 type Props = { base?: string };
 
 function excerpt(text: string, query: string): string {
-	const normalized = text.replace(/\s+/g, ' ').trim();
-	const offset = normalized.toLowerCase().indexOf(query.toLowerCase());
-	const start = Math.max(0, offset - 72);
-	const end = Math.min(normalized.length, start + 190);
-	return `${start > 0 ? '…' : ''}${normalized.slice(start, end)}${end < normalized.length ? '…' : ''}`;
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  const offset = normalized.toLowerCase().indexOf(query.toLowerCase());
+  const start = Math.max(0, offset - 72);
+  const end = Math.min(normalized.length, start + 190);
+  return `${start > 0 ? '…' : ''}${normalized.slice(start, end)}${end < normalized.length ? '…' : ''}`;
 }
 
 export function DocsSiteSearch({ base = '/' }: Props) {
-	const dialog = useRef<HTMLDialogElement>(null);
-	const input = useRef<HTMLInputElement>(null);
-	const [query, setQuery] = useState('');
-	const [documents, setDocuments] = useState<SearchDocument[]>([]);
-	const [loaded, setLoaded] = useState(false);
-	const [failed, setFailed] = useState(false);
-	const [opened, setOpened] = useState(false);
-	const normalizedBase = base.endsWith('/') ? base : `${base}/`;
+  const dialog = useRef<HTMLDialogElement>(null);
+  const input = useRef<HTMLInputElement>(null);
+  const [query, setQuery] = useState('');
+  const [documents, setDocuments] = useState<SearchDocument[]>([]);
+  const [loaded, setLoaded] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const [opened, setOpened] = useState(false);
+  const normalizedBase = base.endsWith('/') ? base : `${base}/`;
 
-	const open = () => {
-		if (!dialog.current?.open) dialog.current?.showModal();
-		setOpened(true);
-		window.setTimeout(() => input.current?.focus(), 0);
-	};
+  const open = () => {
+    if (!dialog.current?.open) dialog.current?.showModal();
+    setOpened(true);
+    window.setTimeout(() => input.current?.focus(), 0);
+  };
 
-	useEffect(() => {
-		const onKeyDown = (event: KeyboardEvent) => {
-			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
-				event.preventDefault();
-				open();
-			} else if (event.key === '/' && !/input|textarea|select/i.test((event.target as HTMLElement)?.tagName ?? '')) {
-				event.preventDefault();
-				open();
-			}
-		};
-		document.addEventListener('keydown', onKeyDown);
-		return () => document.removeEventListener('keydown', onKeyDown);
-	}, []);
+  useEffect(() => {
+    const onOpenSearch = () => open();
+    const onKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+        event.preventDefault();
+        open();
+      } else if (
+        event.key === '/' &&
+        !/input|textarea|select/i.test((event.target as HTMLElement)?.tagName ?? '')
+      ) {
+        event.preventDefault();
+        open();
+      }
+    };
+    document.addEventListener('docs:open-search', onOpenSearch);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('docs:open-search', onOpenSearch);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, []);
 
-	useEffect(() => {
-		if (!opened || loaded) return;
-		fetch(`${normalizedBase}_terra-docs/search-index.json`)
-			.then((response) => {
-				if (!response.ok) throw new Error(`Search index returned ${response.status}`);
-				return response.json() as Promise<SearchDocument[]>;
-			})
-			.then((data) => {
-				setDocuments(data);
-				setLoaded(true);
-			})
-			.catch(() => setFailed(true));
-	}, [loaded, normalizedBase, opened]);
+  useEffect(() => {
+    if (!opened || loaded) return;
+    fetch(`${normalizedBase}_terra-docs/search-index.json`)
+      .then((response) => {
+        if (!response.ok) throw new Error(`Search index returned ${response.status}`);
+        return response.json() as Promise<SearchDocument[]>;
+      })
+      .then((data) => {
+        setDocuments(data);
+        setLoaded(true);
+      })
+      .catch(() => setFailed(true));
+  }, [loaded, normalizedBase, opened]);
 
-	const results = useMemo(() => {
-		const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
-		if (!terms.length) return [];
-		return documents
-			.map((document) => {
-				const title = document.title.toLowerCase();
-				const text = `${document.description} ${document.text}`.toLowerCase();
-				const matches = terms.filter((term) => title.includes(term) || text.includes(term));
-				const score = matches.length * 10 + terms.filter((term) => title.includes(term)).length * 5;
-				return { document, score };
-			})
-			.filter((result) => result.score > 0)
-			.sort((left, right) => right.score - left.score || left.document.title.localeCompare(right.document.title))
-			.slice(0, 10);
-	}, [documents, query]);
+  const results = useMemo(() => {
+    const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+    if (!terms.length) return [];
+    return documents
+      .map((document) => {
+        const title = document.title.toLowerCase();
+        const text = `${document.description} ${document.text}`.toLowerCase();
+        const matches = terms.filter((term) => title.includes(term) || text.includes(term));
+        const score = matches.length * 10 + terms.filter((term) => title.includes(term)).length * 5;
+        return { document, score };
+      })
+      .filter((result) => result.score > 0)
+      .sort(
+        (left, right) =>
+          right.score - left.score || left.document.title.localeCompare(right.document.title),
+      )
+      .slice(0, 10);
+  }, [documents, query]);
 
-	return (
-		<div className="terra-docs-search">
-			<button className="terra-docs-search-trigger" type="button" onClick={open} aria-label="Search documentation">
-				<span aria-hidden="true">⌕</span><span>Search docs</span><kbd>⌘ K</kbd>
-			</button>
-			<dialog className="terra-docs-search-dialog" ref={dialog} onClose={() => setQuery('')}>
-				<div className="terra-docs-search-panel">
-					<label className="terra-docs-search-input-row">
-						<span aria-hidden="true">⌕</span>
-						<input ref={input} value={query} onChange={(event) => setQuery(event.currentTarget.value)} placeholder="Search documentation…" />
-						<button type="button" onClick={() => dialog.current?.close()} aria-label="Close search">Esc</button>
-					</label>
-					<div className="terra-docs-search-results" aria-live="polite">
-						{failed ? <p>Search is unavailable right now.</p> : null}
-						{!loaded && !failed ? <p>Loading search…</p> : null}
-						{loaded && query.trim() && results.length === 0 ? <p>No matching pages.</p> : null}
-						{results.map(({ document }) => (
-							<a key={document.href} href={document.href} onClick={() => dialog.current?.close()}>
-								<strong>{document.title}</strong>
-								{document.description ? <span>{document.description}</span> : null}
-								<small>{excerpt(document.text, query.trim().split(/\s+/)[0] ?? query)}</small>
-							</a>
-						))}
-					</div>
-				</div>
-			</dialog>
-		</div>
-	);
+  return (
+    <div className="terra-docs-search">
+      <dialog className="terra-docs-search-dialog" ref={dialog} onClose={() => setQuery('')}>
+        <div className="terra-docs-search-panel">
+          <label className="terra-docs-search-input-row">
+            <span aria-hidden="true">⌕</span>
+            <input
+              ref={input}
+              value={query}
+              onChange={(event) => setQuery(event.currentTarget.value)}
+              placeholder="Search documentation…"
+            />
+            <button type="button" onClick={() => dialog.current?.close()} aria-label="Close search">
+              Esc
+            </button>
+          </label>
+          <div className="terra-docs-search-results" aria-live="polite">
+            {failed ? <p>Search is unavailable right now.</p> : null}
+            {!loaded && !failed ? <p>Loading search…</p> : null}
+            {loaded && query.trim() && results.length === 0 ? <p>No matching pages.</p> : null}
+            {results.map(({ document }) => (
+              <a key={document.href} href={document.href} onClick={() => dialog.current?.close()}>
+                <strong>{document.title}</strong>
+                {document.description ? <span>{document.description}</span> : null}
+                <small>{excerpt(document.text, query.trim().split(/\s+/)[0] ?? query)}</small>
+              </a>
+            ))}
+          </div>
+        </div>
+      </dialog>
+    </div>
+  );
 }