@dogsbay/docs-layout 0.2.0-beta.8 → 0.2.0-beta.81

package/src/docs-nav-client.ts

@@ -0,0 +1,265 @@
+/**
+ * Client-side sidebar nav hydration.
+ *
+ * Fetches `/_dogsbay/nav.json` once per session, renders the tree DOM
+ * to mirror `@dogsbay/ui/sidebar/SidebarNavTree.astro`'s structure,
+ * and re-highlights the current page on each Astro view-transition
+ * page-load.
+ *
+ * Design constraints:
+ *   - DOM output matches SidebarNavTree exactly (same tags, classes,
+ *     data-attributes) so Tailwind's compiled CSS styles us correctly
+ *     and any sidebar-system selectors (e.g. `data-sidebar="nav-tree"`
+ *     hooks) keep working.
+ *   - Filter by `version` / `locale` matches `nav-filter.ts`'s SSR
+ *     filter so a multi-axis site renders the same nav as `ssr-full`
+ *     mode (without the multiplicative HTML cost).
+ *   - One fetch per session. The `nav.json` URL is served with
+ *     `Cache-Control: immutable` by Astro's static build (it lives
+ *     under `public/_dogsbay/`), so the browser cache holds it across
+ *     navigations.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+import { filterNavByAxis } from "./nav-filter.js";
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+
+/**
+ * Module-level cache so multiple page loads in the same SPA session
+ * share the same fetched nav data. Cleared by re-loads (full page
+ * navigations) but Astro's view transitions re-execute the script
+ * module without reloading the page — so on view-transition the
+ * cached promise is reused and no extra fetch fires.
+ */
+let navPromise: Promise<NavItem[]> | null = null;
+
+function fetchNav(url: string): Promise<NavItem[]> {
+  if (!navPromise) {
+    navPromise = fetch(url, { credentials: "same-origin" }).then((r) => {
+      if (!r.ok) throw new Error(`nav.json fetch failed: ${r.status}`);
+      return r.json() as Promise<NavItem[]>;
+    });
+  }
+  return navPromise;
+}
+
+function normalize(path: string): string {
+  return path.replace(/\/$/, "") || "/";
+}
+
+function hasActiveDescendant(item: NavItem, current: string): boolean {
+  if (item.href && normalize(item.href) === current) return true;
+  return item.children?.some((c) => hasActiveDescendant(c, current)) ?? false;
+}
+
+/**
+ * Render a single nav item into a `<li>` DOM node. Matches
+ * SidebarNavTree's per-level class set exactly so styling stays in
+ * sync. Padding is computed from `level` the same way (`8 + level*12`
+ * pixels) so indentation lines up across the same render.
+ */
+function renderItem(item: NavItem, current: string, level: number): HTMLLIElement {
+  const li = document.createElement("li");
+  li.dataset.sidebar = "nav-tree-item";
+
+  const active = item.href ? normalize(item.href) === current : false;
+  const hasChildren = !!item.children && item.children.length > 0;
+  const padLeft = `${8 + level * 12}px`;
+  const heightClass = level === 0 ? "h-8" : "h-7";
+
+  if (hasChildren) {
+    const details = document.createElement("details");
+    if (active || hasActiveDescendant(item, current)) details.open = true;
+
+    const summary = document.createElement("summary");
+    summary.className = [
+      "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    summary.style.paddingLeft = padLeft;
+    if (item.href) summary.dataset.navHref = item.href;
+    if (active) summary.dataset.active = "true";
+
+    // Chevron SVG — matches SidebarNavTree's rotation-on-open via CSS
+    // (`details[open] > summary [data-chevron] { transform: rotate(90deg); }`).
+    summary.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      summary.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    summary.appendChild(label);
+
+    details.appendChild(summary);
+
+    // Recurse — nested `<ul>` mirrors SidebarNavTree's `<Astro.self>`.
+    const childUl = document.createElement("ul");
+    childUl.className = "flex min-w-0 flex-col";
+    childUl.dataset.sidebar = "nav-tree";
+    childUl.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      childUl.appendChild(renderItem(child, current, level + 1));
+    }
+    details.appendChild(childUl);
+
+    li.appendChild(details);
+  } else {
+    const a = document.createElement("a");
+    a.href = item.href || "#";
+    a.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    a.style.paddingLeft = padLeft;
+    if (active) a.dataset.active = "true";
+    if (item.href) a.dataset.navHref = item.href;
+
+    // Spacer to align leaf text with branch text (which has a chevron).
+    const spacer = document.createElement("span");
+    spacer.className = "size-4 shrink-0";
+    a.appendChild(spacer);
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      a.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    a.appendChild(label);
+
+    li.appendChild(a);
+  }
+
+  return li;
+}
+
+function renderTree(items: NavItem[], current: string, root: HTMLElement): void {
+  const ul = document.createElement("ul");
+  ul.className =
+    "flex min-w-0 flex-col w-full group-data-[collapsible=icon]:hidden";
+  ul.dataset.sidebar = "nav-tree";
+  ul.dataset.level = "0";
+  for (const item of items) {
+    ul.appendChild(renderItem(item, current, 0));
+  }
+  // Replace skeleton in one DOM op so there's no flash of partial state.
+  root.replaceChildren(ul);
+  root.removeAttribute("aria-busy");
+}
+
+/**
+ * Re-highlight the active item without rebuilding the whole tree.
+ * Used on `astro:page-load` when view transitions land on a new
+ * route — we re-toggle the `data-active` attribute and re-apply the
+ * active classes, then expand the new active branch's ancestors.
+ *
+ * Cheaper than a full re-render (no fetch, no DOM rebuild). For
+ * the wider hydration loop we still re-render when a brand-new nav
+ * structure is needed (e.g. switching versions), but path-only
+ * navigation just re-highlights.
+ */
+function rehighlight(root: HTMLElement, current: string): void {
+  const ACTIVE_CLASSES = [
+    "bg-sidebar-accent",
+    "font-medium",
+    "text-sidebar-accent-foreground",
+  ];
+  const items = root.querySelectorAll<HTMLElement>("[data-nav-href]");
+  for (const el of Array.from(items)) {
+    const href = el.dataset.navHref;
+    const active = !!href && normalize(href) === current;
+    if (active) {
+      el.dataset.active = "true";
+      el.classList.add(...ACTIVE_CLASSES);
+    } else {
+      delete el.dataset.active;
+      el.classList.remove(...ACTIVE_CLASSES);
+    }
+  }
+  // Expand ancestors of the new active item.
+  const active = root.querySelector<HTMLElement>('[data-active="true"]');
+  if (active) {
+    let parent: HTMLElement | null = active.parentElement;
+    while (parent) {
+      if (parent.tagName === "DETAILS") {
+        (parent as HTMLDetailsElement).open = true;
+      }
+      parent = parent.parentElement;
+    }
+  }
+}
+
+/**
+ * Public entry point. Called once from `<DocsNavClient />`'s inline
+ * script tag. Idempotent — subsequent calls (e.g. from view
+ * transitions) are no-ops once the tree has been rendered; they just
+ * re-highlight against the new pathname.
+ */
+export async function hydrateDocsNav(): Promise<void> {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+
+  const navUrl = root.dataset.navUrl;
+  if (!navUrl) {
+    console.warn("docs-nav: missing data-nav-url");
+    return;
+  }
+  const current = normalize(root.dataset.currentPath || location.pathname);
+  const basePath = root.dataset.basePath || "";
+  const version = root.dataset.version || undefined;
+  const locale = root.dataset.locale || undefined;
+
+  try {
+    const nav = await fetchNav(navUrl);
+    const filtered = filterNavByAxis(nav, {
+      basePath: basePath || "/docs",
+      version: version || undefined,
+      locale: locale || undefined,
+    });
+    renderTree(filtered, current, root);
+  } catch (err) {
+    console.error("docs-nav: hydration failed", err);
+    root.setAttribute("aria-busy", "false");
+    // Keep skeleton so layout doesn't collapse on failure; a real
+    // user will reload or follow the noscript link.
+  }
+}
+
+// Re-run on view transitions. astro:page-load fires both on initial
+// load and after each ClientRouter transition; the module-level
+// `navPromise` cache makes the post-transition path a fast
+// highlight-only pass without re-fetching.
+document.addEventListener("astro:page-load", () => {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  // If tree is already rendered (no aria-busy), just re-highlight.
+  if (root.getAttribute("aria-busy") === null) {
+    const current = normalize(root.dataset.currentPath || location.pathname);
+    rehighlight(root, current);
+  } else {
+    void hydrateDocsNav();
+  }
+});

package/src/json-ld.ts

@@ -53,3 +53,80 @@ export function normalizeCustomJsonLd(
   if (Array.isArray(raw)) return raw;
   return [raw];
 }
+
+export interface BuildArticleJsonLdOptions {
+  /** Already-resolved Schema.org `@type` (output of jsonLdTypeFor). */
+  type: string;
+  title: string;
+  /** Site name — used as the `provider` Organization for Course. */
+  siteName: string;
+  keywords: string[];
+  description?: string;
+  image?: string;
+  url?: string;
+  /**
+   * Page headings — used to synthesize `step[]` for HowTo. Each
+   * H2 (or H3 if no H2s exist) becomes a HowToStep with a deep
+   * link to the heading id.
+   */
+  headings?: ReadonlyArray<{ depth: number; slug: string; text: string }>;
+}
+
+/**
+ * Build the JSON-LD payload for the page's primary structured-data
+ * block, shaped per `@type`. The earlier implementation emitted
+ * Article-shaped fields (`headline`) regardless of @type, which
+ * meant HowTo / Course pages failed Google's Rich Results
+ * requirements (HowTo needs `name` + `step`, Course needs `name` +
+ * `description` + `provider`). See
+ * `packages/cli/src/audit/rules/seo/json-ld-required-fields.ts`
+ * for the validator that catches this.
+ *
+ * Schema.org's `name` is a Thing-level field accepted by every
+ * @type, so we always emit it. `headline` is added on top for
+ * Article-family types (Article, TechArticle) because Google's
+ * Rich Results validator specifically requires it there. HowTo
+ * gets a synthesized `step[]` from the page's H2 headings (each
+ * H2 = one procedure step); Course gets a `provider` Organization
+ * built from `siteName`.
+ */
+export function buildArticleJsonLd(
+  opts: BuildArticleJsonLdOptions,
+): Record<string, unknown> {
+  const { type, title, siteName, keywords, description, image, url, headings } =
+    opts;
+
+  const block: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": type,
+    name: title,
+    keywords: keywords.join(", "),
+  };
+
+  if (type === "Article" || type === "TechArticle") {
+    block.headline = title;
+  }
+
+  if (description) block.description = description;
+  if (image) block.image = image;
+  if (url) block.url = url;
+
+  if (type === "HowTo") {
+    let stepHeadings = (headings ?? []).filter((h) => h.depth === 2);
+    if (stepHeadings.length === 0) {
+      stepHeadings = (headings ?? []).filter((h) => h.depth === 3);
+    }
+    block.step = stepHeadings.map((h) => ({
+      "@type": "HowToStep",
+      name: h.text,
+      url: url ? `${url}#${h.slug}` : `#${h.slug}`,
+    }));
+  }
+
+  if (type === "Course") {
+    block.provider = { "@type": "Organization", name: siteName };
+    if (!block.description) block.description = title;
+  }
+
+  return block;
+}