@terra-symposium/docs 0.1.76 → 0.1.78

package/site/src/lib/catalog.ts

@@ -1,14 +1,44 @@
+/**
+ * site/src/lib/catalog.ts
+ */
+
 /// <reference types="vite/client" />
 
-import type { DocsNavNode } from '../../../src/components/navigation.js';
+/*//////////////////////////////////////////////////
+IMPORTS
+//////////////////////////////////////////////////*/
+
+// API
 import { getHue } from '@terra-symposium/styling';
 
-type SidebarFrontmatter = {
-  label?: string;
-  order?: number;
-  hidden?: boolean;
-};
+// TYPES
+import type { DocsNavNode } from '../../../src/components/navigation.js';
 
+/*//////////////////////////////////////////////////
+CONFIG
+//////////////////////////////////////////////////*/
+
+/**
+ * Matches hyphens and underscores that separate words in route labels.
+ *
+ * @return A global regular expression for replacing route word separators.
+ */
+const G_REGEX = () => /[-_]+/g;
+/**
+ * Matches the first Unicode letter after a word boundary for title capitalization.
+ *
+ * @return A global Unicode-aware regular expression for capitalizing word initials.
+ */
+const B_P_L_GU_REGEX = () => /\b\p{L}/gu;
+/**
+ * Matches leading or trailing slashes that should be removed from a path.
+ *
+ * @return A regular expression that matches leading or trailing slashes.
+ */
+const G_CLASS_2 = () => /^\/+|\/+$/g;
+/** Matches a leading YAML frontmatter block in a Markdown or MDX page. */
+const S_N_S_S_N_S_N_REGEX = /^---\s*\n[\s\S]*?\n---\s*\n/;
+type SidebarFrontmatter = { label?: string; order?: number; hidden?: boolean };
 type DocsFrontmatter = {
   title?: string;
   description?: string;
@@ -19,13 +49,10 @@ type DocsFrontmatter = {
   visibility?: 'visible' | 'hidden';
   sidebar?: SidebarFrontmatter;
 };
-
-type ContentModule = {
-  Content?: unknown;
-  default?: unknown;
-  frontmatter?: DocsFrontmatter;
-};
-
+type ContentModule = { Content?: unknown; default?: unknown; frontmatter?: DocsFrontmatter };
+/**
+ * Renderable Docs page metadata derived from its Markdown source and frontmatter.
+ */
 export type SitePage = {
   file: string;
   slug: string;
@@ -38,7 +65,6 @@ export type SitePage = {
   content: unknown;
   markdown: string;
 };
-
 const modules = import.meta.glob<ContentModule>('/docs/**/*.{md,mdx}', { eager: true });
 const sources = import.meta.glob<string>('/docs/**/*.{md,mdx}', {
   query: '?raw',
@@ -46,28 +72,13 @@ const sources = import.meta.glob<string>('/docs/**/*.{md,mdx}', {
   eager: true,
 });
 const base = import.meta.env.BASE_URL;
-
-function titleFromSource(source: string, slug: string): string {
-  const body = source.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, '');
-  const heading = /^#\s+(.+?)\s*#*\s*$/m.exec(body)?.[1]?.trim();
-  if (heading) return heading;
-  const name = slug.split('/').at(-1) || 'Overview';
-  return name.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
-}
-
-function routeForFile(file: string): string {
-  const relative = file.replace(/^\/?docs\//, '').replace(/\.(?:md|mdx)$/i, '');
-  return relative.replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
-}
-
 const routes = new Map<string, string>();
+/** Visible Docs pages sorted by configured sidebar order and source path. */
 export const sitePages: SitePage[] = Object.entries(modules)
   .map(([file, module]) => {
     const slug = routeForFile(file);
     const previous = routes.get(slug);
-    if (previous) {
-      throw new Error(`Duplicate Docs route "${slug || '/'}": ${previous} and ${file}`);
-    }
+    if (previous) throw new Error(`Duplicate Docs route "${slug || '/'}": ${previous} and ${file}`);
     routes.set(slug, file);
     const markdown = sources[file] ?? '';
     const frontmatter = module.frontmatter ?? {};
@@ -84,25 +95,117 @@ export const sitePages: SitePage[] = Object.entries(modules)
         frontmatter.sidebar?.hidden ?? frontmatter.hidden ?? frontmatter.visibility === 'hidden',
       order: frontmatter.sidebar?.order ?? frontmatter.order ?? Number.MAX_SAFE_INTEGER,
       content: module.Content ?? module.default,
-      markdown: markdown.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, ''),
+      markdown: markdown.replace(S_N_S_S_N_S_N_REGEX, ''),
     };
   })
   .sort((left, right) => left.order - right.order || left.file.localeCompare(right.file));
+type MutableNode = Omit<DocsNavNode, 'children'> & { children: Map<string, MutableNode> };
+const rootNodes = new Map<string, MutableNode>();
+export const siteNavigation = materialize(rootNodes);
 
-if (sitePages.length === 0) {
-  throw new Error(
-    'No Markdown files found in docs/. Add docs/index.md to start a Terra Docs site.',
-  );
+/*//////////////////////////////////////////////////
+HELPERS
+//////////////////////////////////////////////////*/
+
+/**
+ * Resolves a page title from its first heading or, when absent, its route slug.
+ *
+ * @param source Markdown source after import, including optional frontmatter.
+ * @param slug Normalized route path used as the title fallback.
+ *
+ * @return The authored heading or a title-cased final route segment.
+ */
+function titleFromSource(source: string, slug: string): string {
+  const body = source.replace(S_N_S_S_N_S_N_REGEX, '');
+  const heading = /^#\s+(.+?)\s*#*\s*$/m.exec(body)?.[1]?.trim();
+  if (heading) return heading;
+  const name = slug.split('/').at(-1) || 'Overview';
+  return name.replace(G_REGEX(), ' ').replace(B_P_L_GU_REGEX(), (letter) => letter.toUpperCase());
 }
 
-type MutableNode = Omit<DocsNavNode, 'children'> & { children: Map<string, MutableNode> };
-const rootNodes = new Map<string, MutableNode>();
+/**
+ * Converts a Markdown or MDX file path into its slash-delimited route slug.
+ *
+ * @param file Vite glob path for the source page.
+ *
+ * @return The page path without its extension or trailing `index` segment.
+ */
+function routeForFile(file: string): string {
+  const relative = file.replace(/^\/?docs\//, '').replace(/\.(?:md|mdx)$/i, '');
+  return relative.replace(/(?:^|\/)index$/i, '').replace(G_CLASS_2(), '');
+}
 
+/**
+ * Creates a display label from a route segment by replacing separators and capitalizing words.
+ *
+ * @param value Route segment to display in navigation.
+ *
+ * @return Human-readable navigation text.
+ */
 function label(value: string): string {
-  return value.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
+  return value.replace(G_REGEX(), ' ').replace(B_P_L_GU_REGEX(), (letter) => letter.toUpperCase());
 }
 
-for (const page of sitePages.filter((item) => !item.hidden && item.slug !== '404')) {
+/**
+ * Builds the navigation fields associated with a page at its public route.
+ *
+ * @param page Page whose title, label, description, and hue supply the navigation metadata.
+ * @param href Public URL for the page.
+ *
+ * @return The metadata fields to merge into its navigation node.
+ */
+function pageMetadata(page: SitePage, href: string): Partial<MutableNode> {
+  return {
+    id: page.slug || 'index',
+    title: page.sidebarLabel ?? page.title,
+    href,
+    ...(page.description ? { description: page.description } : {}),
+    ...(page.hue !== undefined ? { hue: page.hue } : {}),
+  };
+}
+
+/**
+ * Converts the mutable map-based navigation tree into the serializable Docs navigation shape.
+ *
+ * @param nodes Child nodes indexed by their route segment.
+ *
+ * @return Navigation nodes with nested children represented as arrays.
+ */
+function materialize(nodes: Map<string, MutableNode>): DocsNavNode[] {
+  return [...nodes.values()].map(({ children, ...node }) => ({
+    ...node,
+    ...(children.size ? { children: materialize(children) } : {}),
+  }));
+}
+
+/**
+ * Builds the public URL for a page, respecting a configured deployment base path.
+ *
+ * @param slug Page route without a leading or trailing slash.
+ * @param base Public base path, with or without its surrounding slashes.
+ *
+ * @return A route with a trailing slash for the Docs site.
+ */
+export function pageHref(slug: string, base = '/'): string {
+  const prefix = base === '/' ? '' : `/${base.replace(G_CLASS_2(), '')}`;
+  return slug ? `${prefix}/${slug}/` : `${prefix}/`;
+}
+
+/**
+ * Looks up a page by its normalized route slug.
+ *
+ * @param slug Route slug to find.
+ *
+ * @return The matching page, or `undefined` when the catalog has no such route.
+ */
+export function pageForSlug(slug: string): SitePage | undefined {
+  return sitePages.find((page) => page.slug === slug);
+}
+if (sitePages.length === 0)
+  throw new Error(
+    'No Markdown files found in docs/. Add docs/index.md to start a Terra Docs site.',
+  );
+for (const page of sitePages.filter((i) => !i.hidden && i.slug !== '404')) {
   const segments = page.slug.split('/').filter(Boolean);
   let currentNodes = rootNodes;
   let current: MutableNode | undefined;
@@ -135,31 +238,3 @@ for (const page of sitePages.filter((item) => !item.hidden && item.slug !== '404
   }
   if (current) Object.assign(current, pageMetadata(page, pageHref(page.slug, base)));
 }
-
-function pageMetadata(page: SitePage, href: string): Partial<MutableNode> {
-  return {
-    id: page.slug || 'index',
-    title: page.sidebarLabel ?? page.title,
-    href,
-    ...(page.description ? { description: page.description } : {}),
-    ...(page.hue !== undefined ? { hue: page.hue } : {}),
-  };
-}
-
-function materialize(nodes: Map<string, MutableNode>): DocsNavNode[] {
-  return [...nodes.values()].map(({ children, ...node }) => ({
-    ...node,
-    ...(children.size ? { children: materialize(children) } : {}),
-  }));
-}
-
-export const siteNavigation = materialize(rootNodes);
-
-export function pageHref(slug: string, base = '/'): string {
-  const prefix = base === '/' ? '' : `/${base.replace(/^\/+|\/+$/g, '')}`;
-  return slug ? `${prefix}/${slug}/` : `${prefix}/`;
-}
-
-export function pageForSlug(slug: string): SitePage | undefined {
-  return sitePages.find((page) => page.slug === slug);
-}

package/src/components/SiteLayout.astro

@@ -1,7 +1,7 @@
 ---
-import { DocsStaticWorkspace } from '../../lib-dist/components/StaticWorkspace.js';
+import { DocsSiteIsland } from '../../site/src/components/DocsSiteIsland.js';
+import AstroErrorBoundary from '@terra-symposium/standards-error-boundaries/astro-boundary';
 import '../../lib-dist/style.css';
-import { DocsSiteSearch } from '../../site/src/components/DocsSiteSearch.js';
 import '../../site/src/styles/search.css';
 import type { DocsAttachment, DocsSection, DocsNavNode } from '../../lib-dist/lib/index.js';
 
@@ -25,25 +25,27 @@ const { title, homeHref = '/', description, pageTitle, nodes = [], sections, cur
 const staticContent = Astro.slots.has('default');
 ---
 
-<DocsStaticWorkspace
-	client:load
-	title={title}
-	homeHref={homeHref}
-	description={description}
-	pageTitle={pageTitle}
-	nodes={nodes}
-	sections={sections}
-	currentPath={currentPath}
-	rootPath={rootPath}
-	markdown={markdown}
-	content={content}
-	attachments={attachments}
-	updatedAt={updatedAt}
-	staticContent={staticContent}
->
-	<slot />
-</DocsStaticWorkspace>
-<DocsSiteSearch client:load base={searchBase} />
+<AstroErrorBoundary title="Documentation could not load" description="The Docs interface failed to start. The error has been recorded for diagnosis." reloadLabel="Reload Docs">
+	<DocsSiteIsland
+		client:load
+		title={title}
+		homeHref={homeHref}
+		description={description}
+		pageTitle={pageTitle}
+		nodes={nodes}
+		sections={sections}
+		currentPath={currentPath}
+		rootPath={rootPath}
+		markdown={markdown}
+		content={content}
+		attachments={attachments}
+		updatedAt={updatedAt}
+		staticContent={staticContent}
+		searchBase={searchBase}
+	>
+		<slot />
+	</DocsSiteIsland>
+</AstroErrorBoundary>
 
 <style is:global>
 	.terra-docs-page-content { max-width: 100%; }

package/site/src/styles/skills-explorer.css

@@ -1,268 +0,0 @@
-.docs-skills {
-  margin-block: 2rem;
-}
-
-.docs-skills__header {
-  display: flex;
-  align-items: flex-end;
-  justify-content: space-between;
-  gap: 1.5rem;
-  margin-bottom: 1rem;
-}
-
-.docs-skills__header h2,
-.docs-skills__detail h3 {
-  margin: 0;
-}
-
-.docs-skills__header p:not(.docs-skills__eyebrow) {
-  margin: 0.4rem 0 0;
-  color: color-mix(in srgb, currentColor 72%, transparent);
-}
-
-.docs-skills__eyebrow {
-  margin: 0 0 0.35rem;
-  color: color-mix(in srgb, currentColor 64%, transparent);
-  font-size: 0.75rem;
-  font-weight: 700;
-  letter-spacing: 0.07em;
-  text-transform: uppercase;
-}
-
-.docs-skills__summary {
-  display: grid;
-  justify-items: end;
-  color: color-mix(in srgb, currentColor 70%, transparent);
-  font-size: 0.85rem;
-}
-
-.docs-skills__summary strong {
-  color: var(--docs-accent, currentColor);
-  font-size: 1.6rem;
-  line-height: 1;
-}
-
-.docs-skills__layout {
-  display: grid;
-  grid-template-columns: minmax(16rem, 0.8fr) minmax(0, 1.6fr);
-  align-items: start;
-  gap: 1rem;
-}
-
-.docs-skills__index,
-.docs-skills__detail {
-  min-width: 0;
-  overflow: hidden;
-  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
-  border-radius: 0.75rem;
-  background: color-mix(in srgb, currentColor 3%, transparent);
-}
-
-.docs-skills__index {
-  max-height: 78vh;
-  overflow: auto;
-  padding: 0.75rem;
-}
-
-.docs-skills__filter {
-  display: grid;
-  gap: 0.35rem;
-  font-size: 0.8rem;
-  font-weight: 600;
-}
-
-.docs-skills__filter input {
-  box-sizing: border-box;
-  width: 100%;
-  min-height: 2.5rem;
-  border: 1px solid color-mix(in srgb, currentColor 24%, transparent);
-  border-radius: 0.45rem;
-  background: var(--background, transparent);
-  color: inherit;
-  font: inherit;
-  font-weight: 400;
-  padding: 0.45rem 0.6rem;
-}
-
-.docs-skills__filter input:focus-visible,
-.docs-skills__item:focus-visible {
-  outline: 2px solid var(--docs-accent, currentColor);
-  outline-offset: 2px;
-}
-
-.docs-skills__count {
-  margin: 0.65rem 0 1rem;
-  color: color-mix(in srgb, currentColor 65%, transparent);
-  font-size: 0.8rem;
-}
-
-.docs-skills__group + .docs-skills__group {
-  margin-top: 1rem;
-}
-
-.docs-skills__group h3 {
-  margin: 0 0 0.4rem;
-  color: color-mix(in srgb, currentColor 68%, transparent);
-  font-size: 0.75rem;
-  font-weight: 700;
-  overflow-wrap: anywhere;
-  text-transform: uppercase;
-}
-
-.docs-skills__group ul {
-  display: grid;
-  gap: 0.35rem;
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
-.docs-skills__item {
-  display: grid;
-  width: 100%;
-  min-width: 0;
-  gap: 0.2rem;
-  border: 0;
-  border-radius: 0.5rem;
-  background: transparent;
-  color: inherit;
-  cursor: pointer;
-  font: inherit;
-  padding: 0.55rem;
-  text-align: left;
-}
-
-.docs-skills__item:hover,
-.docs-skills__item[aria-current='true'] {
-  background: color-mix(in srgb, var(--docs-accent, currentColor) 12%, transparent);
-}
-
-.docs-skills__item[aria-current='true'] .docs-skills__item-title {
-  color: var(--docs-accent, currentColor);
-  font-weight: 700;
-}
-
-.docs-skills__item-title {
-  font-weight: 600;
-}
-
-.docs-skills__item-description,
-.docs-skills__item-path {
-  color: color-mix(in srgb, currentColor 68%, transparent);
-  font-size: 0.78rem;
-  line-height: 1.4;
-}
-
-.docs-skills__item-path,
-.docs-skills__source-path {
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  overflow-wrap: anywhere;
-}
-
-.docs-skills__detail > header {
-  padding: 1.25rem 1.25rem 0.75rem;
-}
-
-.docs-skills__description {
-  margin: 0.6rem 0;
-  color: color-mix(in srgb, currentColor 74%, transparent);
-}
-
-.docs-skills__source-path {
-  margin: 0;
-  color: color-mix(in srgb, currentColor 60%, transparent);
-  font-size: 0.75rem;
-}
-
-.docs-skills__metadata {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr));
-  gap: 0.6rem;
-  margin: 0;
-  padding: 0.75rem 1.25rem 1.25rem;
-}
-
-.docs-skills__metadata > div {
-  min-width: 0;
-  border: 1px solid color-mix(in srgb, currentColor 15%, transparent);
-  border-radius: 0.5rem;
-  padding: 0.6rem 0.7rem;
-}
-
-.docs-skills__metadata dt {
-  color: color-mix(in srgb, currentColor 62%, transparent);
-  font-size: 0.72rem;
-  font-weight: 700;
-  text-transform: capitalize;
-}
-
-.docs-skills__metadata dd {
-  margin: 0.2rem 0 0;
-  font-size: 0.82rem;
-  overflow-wrap: anywhere;
-}
-
-.docs-skills__metadata-issue {
-  margin: 0 1.25rem 1rem;
-  color: #a12b2b;
-  font-size: 0.85rem;
-}
-
-.docs-skills__source {
-  border-top: 1px solid color-mix(in srgb, currentColor 16%, transparent);
-}
-
-.docs-skills__source summary {
-  cursor: pointer;
-  font-weight: 600;
-  padding: 0.8rem 1.25rem;
-}
-
-.docs-skills__source summary:focus-visible {
-  outline: 2px solid var(--docs-accent, currentColor);
-  outline-offset: -2px;
-}
-
-.docs-skills__source pre {
-  max-height: 60vh;
-  overflow: auto;
-  margin: 0;
-  border-top: 1px solid color-mix(in srgb, currentColor 12%, transparent);
-  background: color-mix(in srgb, currentColor 4%, transparent);
-  padding: 1rem 1.25rem;
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
-  font-size: 0.8rem;
-  line-height: 1.6;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-}
-
-.docs-skills__empty {
-  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
-  border-radius: 0.75rem;
-  padding: 1rem;
-}
-
-@media (max-width: 48rem) {
-  .docs-skills__header {
-    align-items: flex-start;
-  }
-
-  .docs-skills__layout {
-    grid-template-columns: minmax(0, 1fr);
-  }
-
-  .docs-skills__index {
-    max-height: 45vh;
-  }
-}
-
-@media (max-width: 30rem) {
-  .docs-skills__header {
-    flex-direction: column;
-  }
-
-  .docs-skills__summary {
-    justify-items: start;
-  }
-}