@dogsbay/docs-layout 0.2.0-beta.11 → 0.2.0-beta.110

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