@dogsbay/docs-layout 0.2.0-beta.9 → 0.2.0-beta.91

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;
+}

package/src/search-facets.ts

@@ -16,6 +16,33 @@ import type { PrefixDisplay } from "./tag-list-data.js";
 export interface TaxonomyDisplay {
   prefixes?: Record<string, PrefixDisplay>;
   labels?: Record<string, string>;
+  /**
+   * Sort weight for the facet column in the search dialog. Lower
+   * numbers appear first. Facets without an `order` sort
+   * alphabetically *after* any pinned ones — so `{ type: { order: 1 } }`
+   * promotes "Type" to the top while everything else stays alpha.
+   */
+  order?: number;
+  /**
+   * Render this facet as a tree instead of a flat checkbox list.
+   * See `buildFacetTree` for the two derivation strategies (slash-
+   * encoded vs nav-driven segment-encoded) and the canonical
+   * @dogsbay/types definition for full semantics.
+   */
+  hierarchical?: boolean;
+}
+
+/**
+ * Minimal nav item shape — mirrors `@dogsbay/types`' `NavItem`
+ * locally so this module has no runtime dependency on the types
+ * package. Used as input to `buildFacetTree` for segment-encoded
+ * facets (the auto-`category` case), where the document tree is
+ * the source of structure and order.
+ */
+export interface NavLike {
+  label: string;
+  href?: string;
+  children?: NavLike[];
 }
 
 /** Map of taxonomy name → display config. */
@@ -120,6 +147,40 @@ export function resolveFacetTitle(facetName: string): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+/**
+ * Return facet names in sidebar render order.
+ *
+ * Pagefind's `filters()` map iterates in index-discovery order
+ * (effectively the first page Pagefind happened to read), so without
+ * sorting the column order is arbitrary and shifts between builds.
+ * Order rule:
+ *  1. Facets with a numeric `order` in their `TaxonomyDisplay`
+ *     come first, ascending — use this to pin "Type" or "Audience"
+ *     to the top regardless of name.
+ *  2. Everything else sorts alphabetically by facet name.
+ * Stable within each tier so ties don't shuffle.
+ */
+export function sortFacetNames(
+  names: string[],
+  display?: TaxonomyDisplayMap,
+): string[] {
+  const withOrder = (name: string): number | undefined => {
+    const o = display?.[name]?.order;
+    return typeof o === "number" ? o : undefined;
+  };
+  return [...names].sort((a, b) => {
+    const oa = withOrder(a);
+    const ob = withOrder(b);
+    if (oa !== undefined && ob !== undefined) {
+      if (oa !== ob) return oa - ob;
+      return a.localeCompare(b);
+    }
+    if (oa !== undefined) return -1;
+    if (ob !== undefined) return 1;
+    return a.localeCompare(b);
+  });
+}
+
 // ── URL persistence ──────────────────────────────────────────────
 
 /**
@@ -175,21 +236,32 @@ export function parseFiltersFromUrl(
 }
 
 /**
- * Pagefind's `search()` accepts filters keyed by facet name with
- * either a single value, an array (OR), or a nested operator
- * object. We always pass the array form so multi-select works
- * within a facet without special-casing single-select.
+ * Build Pagefind's `filters` argument from internal facet state.
+ *
+ * Pagefind's array shape (`{ tag: ["a", "b"] }`) is AND by default —
+ * "page must have BOTH tags" — per
+ * https://pagefind.app/docs/js-api-filtering/ ("All filtering
+ * defaults to AND filtering"). That's the wrong UX for faceted
+ * search: clicking two checkboxes in the same group should widen
+ * the result set, not collapse it to zero. We wrap each facet in
+ * `{ any: [...] }` so multi-select within a facet is OR. Across
+ * different facets Pagefind already ANDs the keys, which matches
+ * the standard "narrow with each additional dimension" UX.
+ *
+ * Single-value selections also go through `{ any: ["x"] }` —
+ * Pagefind treats a one-element `any` identically to a bare string,
+ * so there's no behavioural delta and the code stays branch-free.
  *
  * Empty filter state → `{}` (Pagefind returns the unfiltered
- * result set). A facet with an empty array also drops out so we
- * don't accidentally narrow to "must equal nothing".
+ * result set). A facet with an empty array drops out so we don't
+ * accidentally narrow to "must equal nothing".
  */
 export function filterStateToPagefindFilters(
   filters: FilterState,
-): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+): Record<string, { any: string[] }> {
+  const out: Record<string, { any: string[] }> = {};
   for (const [name, values] of Object.entries(filters)) {
-    if (values.length > 0) out[name] = [...values];
+    if (values.length > 0) out[name] = { any: [...values] };
   }
   return out;
 }
@@ -230,3 +302,433 @@ export function countActiveFilters(filters: FilterState): number {
   for (const values of Object.values(filters)) n += values.length;
   return n;
 }
+
+// ── Hierarchical facets ──────────────────────────────────────────
+
+/**
+ * One node in a hierarchical facet tree (see `buildFacetTree`).
+ *
+ * `value` is the canonical Pagefind filter value for this node —
+ * for slash-encoded facets the full slash-joined path
+ * (`concept/a11y`); for segment-encoded facets a single segment
+ * (`installing_aws`). `value` matches Pagefind's value key 1:1
+ * for "real" entries; synthetic parents (intermediate trie nodes
+ * that don't correspond to a Pagefind entry) reuse the same
+ * derived value but carry `hasValue: false` and `count: 0`.
+ */
+export interface FacetTreeNode {
+  value: string;
+  label: string;
+  count: number;
+  depth: number;
+  /** True if Pagefind reported this exact value; false for synthetic parents. */
+  hasValue: boolean;
+  children: FacetTreeNode[];
+}
+
+/**
+ * Build a hierarchical facet tree from Pagefind's flat entry list.
+ *
+ * Two strategies depending on the values' shape:
+ *
+ *  - **Slash-encoded.** When at least one entry value contains `/`,
+ *    each value is treated as a path through the tree (`concept/a11y`
+ *    →  `concept → a11y`). Splits on `/`, inserts into a trie.
+ *    Parent entries that don't have a Pagefind value of their own
+ *    (e.g. `concept` standalone is unindexed but `concept/a11y` is)
+ *    appear as synthetic intermediate nodes with `hasValue: false`.
+ *    Within a parent, children sort by count desc then alpha — the
+ *    same rule as flat facets.
+ *
+ *  - **Segment-encoded.** When NO entry contains `/`, each value is
+ *    a single path segment. Hierarchy comes from `nav` — every nav
+ *    leaf's href segments become a chain in the trie. Counts come
+ *    from Pagefind's entry list, attached to nodes whose segment
+ *    name matches an entry value. **Caveat:** Pagefind reports one
+ *    count per distinct segment name regardless of where in the
+ *    tree it lives, so a segment that appears at multiple positions
+ *    (`installing/.../ipi`, `installing_azure/.../ipi`) gets the
+ *    same total count at every position — clicking selects the
+ *    shared value, returning pages from every position. This
+ *    matches the underlying Pagefind filter behaviour and is
+ *    documented in plans/hierarchical-facets.md.
+ *
+ *    Order is nav-document order, NOT count desc. Pagefind entries
+ *    not represented in nav are appended as orphans at the root in
+ *    alpha order.
+ *
+ *    When `nav` is undefined for the segment-encoded case, falls
+ *    back to a flat list (every entry a root-level node with no
+ *    children, in count-desc order) — preserves render-ability
+ *    when nav.json hasn't loaded yet.
+ *
+ * Returns the top-level nodes. Empty `entries` → empty array.
+ */
+export function buildFacetTree(
+  facetName: string,
+  entries: FacetEntry[],
+  options: {
+    nav?: NavLike[];
+    display?: TaxonomyDisplayMap;
+  } = {},
+): FacetTreeNode[] {
+  if (entries.length === 0) return [];
+
+  const slashEncoded = entries.some((e) => e.value.includes("/"));
+  if (slashEncoded) {
+    // When nav is supplied, derive document-order. Otherwise fall
+    // back to count-desc + alpha. The map keys are full cumulative
+    // paths (matching Pagefind entry values 1:1).
+    const navOrder = options.nav
+      ? buildNavOrderMap(
+          options.nav,
+          new Set(entries.map((e) => e.value)),
+        )
+      : undefined;
+    return buildSlashTree(facetName, entries, options.display, navOrder);
+  }
+  return buildSegmentTree(facetName, entries, options.nav, options.display);
+}
+
+/**
+ * Slash-encoded tree builder. Each entry value is a slash-joined
+ * path; split, walk a trie, attach Pagefind counts to terminal
+ * nodes. Synthetic intermediate nodes (a path component used by a
+ * descendant but absent from `entries`) get `hasValue: false` and
+ * `count: 0` so they render but don't contribute to selection.
+ *
+ * Sort order at every depth:
+ *   1. `navOrder` index if present (document order from nav.json).
+ *      Without this, deep API-reference subtrees with high page
+ *      counts would dominate the top of the tree even though they
+ *      sit at the BOTTOM of the rendered nav.
+ *   2. Count desc (more pages → higher).
+ *   3. Alpha (final tiebreak).
+ */
+function buildSlashTree(
+  facetName: string,
+  entries: FacetEntry[],
+  display?: TaxonomyDisplayMap,
+  navOrder?: Map<string, number>,
+): FacetTreeNode[] {
+  // Trie keyed by full slash-path. Children are tracked on each
+  // node's own `children` array (built unsorted in pass 1, sorted
+  // recursively in pass 2).
+  const byPath = new Map<string, FacetTreeNode>();
+  const rootValues: string[] = [];
+
+  for (const entry of entries) {
+    const segments = entry.value.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) continue;
+    let pathSoFar = "";
+    let parent: FacetTreeNode | null = null;
+    for (let i = 0; i < segments.length; i++) {
+      pathSoFar = pathSoFar ? `${pathSoFar}/${segments[i]}` : segments[i];
+      let node = byPath.get(pathSoFar);
+      if (!node) {
+        node = {
+          value: pathSoFar,
+          label: resolveFacetLabel(facetName, pathSoFar, display),
+          count: 0,
+          depth: i,
+          hasValue: false,
+          children: [],
+        };
+        byPath.set(pathSoFar, node);
+        if (parent) parent.children.push(node);
+        else rootValues.push(pathSoFar);
+      }
+      if (i === segments.length - 1) {
+        node.count = entry.count;
+        node.hasValue = true;
+      }
+      parent = node;
+    }
+  }
+
+  // Pass 2: sort children at every depth.
+  const cmp = (a: FacetTreeNode, b: FacetTreeNode): number => {
+    if (navOrder) {
+      const oa = navOrder.get(a.value);
+      const ob = navOrder.get(b.value);
+      if (oa !== undefined && ob !== undefined && oa !== ob) return oa - ob;
+      // Nodes IN the nav sort before nodes not in nav
+      if (oa !== undefined && ob === undefined) return -1;
+      if (oa === undefined && ob !== undefined) return 1;
+    }
+    if (a.count !== b.count) return b.count - a.count;
+    return a.value.localeCompare(b.value);
+  };
+  const sortChildren = (node: FacetTreeNode): void => {
+    if (node.children.length === 0) return;
+    node.children.sort(cmp);
+    for (const c of node.children) sortChildren(c);
+  };
+
+  const rootList = rootValues.map((v) => byPath.get(v)!);
+  rootList.sort(cmp);
+  for (const r of rootList) sortChildren(r);
+  return rootList;
+}
+
+/**
+ * Walk `nav` and assign each cumulative slash-path (matching a
+ * Pagefind facet value in `knownValues`) a sequential index in
+ * first-encounter order. Used by `buildSlashTree` to sort children
+ * in document order rather than count-desc.
+ *
+ * Auto-detects and strips a leading basePath: for each nav leaf, we
+ * try each starting offset of the href's parent segments. The first
+ * offset whose initial cumulative path is in `knownValues` is the
+ * "real" content root; the dropped prefix is the basePath. This way
+ * the helper works on any site without needing the basePath threaded
+ * through explicitly.
+ *
+ * Hrefs whose parents don't match anything in `knownValues` at any
+ * offset are skipped (e.g. top-level pages with no auto-derived
+ * category, or pages outside the indexed corpus).
+ *
+ * Exported for use by `buildFacetTree`. Pure — no I/O.
+ */
+export function buildNavOrderMap(
+  nav: NavLike[],
+  knownValues: Set<string>,
+): Map<string, number> {
+  const order = new Map<string, number>();
+  let n = 0;
+  const walk = (items: NavLike[]): void => {
+    for (const item of items) {
+      if (item.href) {
+        const parents = hrefToCategorySegments(item.href);
+        // Try each starting offset; first one whose initial cumulative
+        // path is in knownValues wins (auto-detects basePath).
+        for (let start = 0; start < parents.length; start++) {
+          const first = parents[start];
+          if (!knownValues.has(first)) continue;
+          // Record all cumulative paths starting from `start` that
+          // exist in knownValues. The check at line below filters out
+          // synthetic intermediates the corpus didn't tag (e.g. a
+          // user-supplied frontmatter category that skipped a level).
+          let cumulative = "";
+          for (let i = start; i < parents.length; i++) {
+            cumulative = cumulative ? `${cumulative}/${parents[i]}` : parents[i];
+            if (knownValues.has(cumulative) && !order.has(cumulative)) {
+              order.set(cumulative, n++);
+            }
+          }
+          break;
+        }
+      }
+      if (item.children && item.children.length > 0) walk(item.children);
+    }
+  };
+  walk(nav);
+  return order;
+}
+
+/**
+ * Segment-encoded tree builder. Walks `nav` to discover the
+ * canonical document hierarchy, then attaches Pagefind counts to
+ * any node whose segment name matches an entry. Pagefind entries
+ * not in nav are appended as alpha-sorted root orphans so they
+ * don't disappear.
+ */
+function buildSegmentTree(
+  facetName: string,
+  entries: FacetEntry[],
+  nav: NavLike[] | undefined,
+  display?: TaxonomyDisplayMap,
+): FacetTreeNode[] {
+  const byValue = new Map<string, FacetEntry>();
+  for (const e of entries) byValue.set(e.value, e);
+
+  if (!nav || nav.length === 0) {
+    // Flat fallback in count-desc order — preserves render-ability
+    // when nav hasn't loaded.
+    return entries.map((e) => ({
+      value: e.value,
+      label: resolveFacetLabel(facetName, e.value, display),
+      count: e.count,
+      depth: 0,
+      hasValue: true,
+      children: [],
+    }));
+  }
+
+  const seenValues = new Set<string>();
+  const roots: FacetTreeNode[] = [];
+  const rootIndex = new Map<string, FacetTreeNode>();
+
+  /** Insert a path's parent segments (excluding the leaf filename) into the trie. */
+  const insertPath = (segments: string[]): void => {
+    if (segments.length === 0) return;
+    let parentList: FacetTreeNode[] = roots;
+    let parentIndex: Map<string, FacetTreeNode> = rootIndex;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      let node = parentIndex.get(seg);
+      if (!node) {
+        const entry = byValue.get(seg);
+        node = {
+          value: seg,
+          label: resolveFacetLabel(facetName, seg, display),
+          count: entry ? entry.count : 0,
+          depth: i,
+          hasValue: entry !== undefined,
+          children: [],
+        };
+        parentList.push(node);
+        parentIndex.set(seg, node);
+        if (entry) seenValues.add(seg);
+      }
+      // Walk into the child list for the next iteration. Each
+      // node carries its own child index lazily via a WeakMap-like
+      // closure; here we use a regular Map keyed off the node.
+      let nextIndex = childIndex.get(node);
+      if (!nextIndex) {
+        nextIndex = new Map();
+        childIndex.set(node, nextIndex);
+      }
+      parentList = node.children;
+      parentIndex = nextIndex;
+    }
+  };
+
+  const childIndex = new Map<FacetTreeNode, Map<string, FacetTreeNode>>();
+
+  // Walk every nav leaf. Use href segments (excluding the leaf
+  // filename) — those are the auto-derived `category` values
+  // emitted by parseMeta's deriveCategoryFromSlug.
+  const walkNav = (items: NavLike[]): void => {
+    for (const item of items) {
+      if (item.href) {
+        const parents = hrefToCategorySegments(item.href);
+        insertPath(parents);
+      }
+      if (item.children && item.children.length > 0) walkNav(item.children);
+    }
+  };
+  walkNav(nav);
+
+  // Pagefind values not represented in nav → root-level orphans in
+  // alpha order. Without this they vanish from the UI silently.
+  const orphans: FacetTreeNode[] = [];
+  for (const e of entries) {
+    if (seenValues.has(e.value)) continue;
+    orphans.push({
+      value: e.value,
+      label: resolveFacetLabel(facetName, e.value, display),
+      count: e.count,
+      depth: 0,
+      hasValue: true,
+      children: [],
+    });
+  }
+  orphans.sort((a, b) => a.value.localeCompare(b.value));
+  return [...roots, ...orphans];
+}
+
+/**
+ * Strip an href down to its parent path segments — the `category`
+ * derivation logic from `parseMeta.deriveCategoryFromSlug`. Drops
+ * leading/trailing slashes, drops the leaf filename segment.
+ */
+function hrefToCategorySegments(href: string): string[] {
+  // Drop scheme/host if absolute (we only treat path segments)
+  let path = href;
+  try {
+    if (/^[a-z]+:\/\//i.test(href)) path = new URL(href).pathname;
+  } catch {
+    // not a URL — treat as-is
+  }
+  // Drop hash + query — facets care about the URL path only
+  path = path.split("#")[0].split("?")[0];
+  const segments = path.split("/").filter((s) => s.length > 0);
+  // Match deriveCategoryFromSlug: parents = everything except the leaf
+  if (segments.length < 2) return [];
+  return segments.slice(0, -1);
+}
+
+/**
+ * Flat list of every "real" Pagefind value at or under `node`
+ * (i.e. every node where `hasValue === true`). Synthetic parents
+ * are excluded since adding them to the filter would be a no-op
+ * (Pagefind has no pages tagged with the synthetic value).
+ *
+ * Used by `toggleTreeNode` when the user ticks a parent — we add
+ * every real descendant value to the selection in one shot.
+ */
+export function collectDescendantValues(node: FacetTreeNode): string[] {
+  const out: string[] = [];
+  const visit = (n: FacetTreeNode): void => {
+    if (n.hasValue) out.push(n.value);
+    for (const c of n.children) visit(c);
+  };
+  visit(node);
+  return out;
+}
+
+/**
+ * Tri-state of a tree node given the current filter state.
+ *
+ *  - `"checked"`     — every real descendant value (and self if
+ *                       self has a value) is in `filters[facetName]`.
+ *  - `"unchecked"`    — none of them are.
+ *  - `"indeterminate"`— at least one is, but not all.
+ *
+ * Synthetic parents with no real-value descendants resolve to
+ * "unchecked" (defensive default — shouldn't occur in valid trees).
+ */
+export function computeTreeState(
+  node: FacetTreeNode,
+  facetName: string,
+  filters: FilterState,
+): "checked" | "unchecked" | "indeterminate" {
+  const descendants = collectDescendantValues(node);
+  if (descendants.length === 0) return "unchecked";
+  const selected = new Set(filters[facetName] ?? []);
+  let hits = 0;
+  for (const v of descendants) if (selected.has(v)) hits++;
+  if (hits === 0) return "unchecked";
+  if (hits === descendants.length) return "checked";
+  return "indeterminate";
+}
+
+/**
+ * Toggle a tree node's selection.
+ *
+ *  - If currently checked → remove self + all descendant values
+ *    from `filters[facetName]`.
+ *  - If unchecked or indeterminate → add self + all descendant
+ *    values (auto-select). Matches the decided UX: parent click
+ *    fans out to children.
+ *
+ * Returns a new `FilterState` — input is not mutated. Same
+ * immutability contract as `toggleFilter`.
+ */
+export function toggleTreeNode(
+  filters: FilterState,
+  facetName: string,
+  node: FacetTreeNode,
+  currentState: "checked" | "unchecked" | "indeterminate",
+): FilterState {
+  const descendants = collectDescendantValues(node);
+  if (descendants.length === 0) return filters;
+  const current = filters[facetName] ?? [];
+  let nextValues: string[];
+  if (currentState === "checked") {
+    const drop = new Set(descendants);
+    nextValues = current.filter((v) => !drop.has(v));
+  } else {
+    const merged = new Set(current);
+    for (const v of descendants) merged.add(v);
+    nextValues = Array.from(merged);
+  }
+  const next: FilterState = { ...filters };
+  if (nextValues.length === 0) {
+    delete next[facetName];
+  } else {
+    next[facetName] = nextValues;
+  }
+  return next;
+}

package/src/toc-placement.ts

@@ -0,0 +1,71 @@
+/**
+ * Decide which TOC container(s) and right-rail region `DocsLayout` renders,
+ * given the `toc` placement mode and per-page facts. Factored out of
+ * `DocsLayout.astro` so the branching logic is unit-testable (the .astro
+ * file just consumes the result) — same pattern as `nav-filter.ts` etc.
+ *
+ * See plans/ask-branch1-placement-toc.md.
+ */
+
+export type TocMode = "top" | "popover" | "rail" | "off";
+
+export interface TocPlacement {
+  /** Classic right-hand TOC sidebar (the pre-`toc`-option layout). */
+  railToc: boolean;
+  /** Expandable "On this page" disclosure at the top of the article. */
+  topToc: boolean;
+  /** "On this page" dropdown in the header. */
+  popoverToc: boolean;
+  /**
+   * The right-rail plugin region (host for the `right-rail` named slot, e.g.
+   * an Ask AI panel). Present whenever the rail isn't the classic TOC's, and
+   * deliberately NOT gated on headings — so a plugin can dock on heading-less
+   * pages. Never shown on wide/API pages (no rail there).
+   */
+  regionRail: boolean;
+}
+
+/**
+ * Whether a page has enough displayable headings to warrant a TOC. The TOC
+ * (`DocsToc`) only lists depth `minDepth`–`maxDepth` (2–3 by default), so the
+ * page H1 never counts; and a TOC of a single entry isn't useful, so require
+ * `min` (2) by default. Pages like a landing/welcome page — H1 + prose, no
+ * sub-sections — therefore get no "On this page".
+ */
+export function hasDisplayableToc(
+  headings: { depth: number }[],
+  opts: { minDepth?: number; maxDepth?: number; min?: number } = {},
+): boolean {
+  const { minDepth = 2, maxDepth = 3, min = 2 } = opts;
+  let count = 0;
+  for (const h of headings) {
+    if (h.depth >= minDepth && h.depth <= maxDepth) count++;
+    if (count >= min) return true;
+  }
+  return false;
+}
+
+export interface TocPlacementInput {
+  /** Page has at least one heading to list. */
+  hasHeadings: boolean;
+  /** Wide/API layout — composes its own columns, so no right rail. */
+  wideLayout: boolean;
+}
+
+/**
+ * Resolve the placement flags. A TOC container only renders when there are
+ * headings to show; the region rail is independent of headings. `rail` and
+ * the region rail are mutually exclusive (they compete for the same column),
+ * and both are suppressed on wide pages.
+ */
+export function resolveTocPlacement(
+  toc: TocMode,
+  { hasHeadings, wideLayout }: TocPlacementInput,
+): TocPlacement {
+  return {
+    railToc: toc === "rail" && hasHeadings && !wideLayout,
+    topToc: toc === "top" && hasHeadings,
+    popoverToc: toc === "popover" && hasHeadings,
+    regionRail: toc !== "rail" && !wideLayout,
+  };
+}