@dogsbay/docs-layout 0.2.0-beta.84 → 0.2.0-beta.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.84",
+  "version": "0.2.0-beta.86",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.84",
-    "@dogsbay/primitives": "0.2.0-beta.84"
+    "@dogsbay/ui": "0.2.0-beta.86",
+    "@dogsbay/primitives": "0.2.0-beta.86"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro

@@ -35,6 +35,7 @@ import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
+import { resolveTocPlacement, type TocMode } from "./toc-placement.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -404,6 +405,17 @@ interface Props {
    * in per-page.
    */
   wideLayout?: boolean;
+  /**
+   * Table-of-contents placement. Default `"top"`.
+   * - `"top"` — expandable "On this page" disclosure at the top of the
+   *   article, identical on desktop and mobile; frees the right rail for the
+   *   `right-rail` named slot (e.g. an Ask AI panel).
+   * - `"popover"` — an "On this page" dropdown in the header.
+   * - `"rail"` — the classic right-hand TOC sidebar (pre-`toc` behaviour).
+   * - `"off"` — no table of contents.
+   * See plans/ask-branch1-placement-toc.md.
+   */
+  toc?: TocMode;
   class?: string;
 }
 
@@ -414,6 +426,7 @@ const {
   nav,
   navGroups,
   headings = [],
+  toc = "top",
   prev,
   next,
   repoUrl,
@@ -512,6 +525,13 @@ const hasMetaStrip = (
   (typeof pageType === "string" && pageType.length > 0)
 );
 
+// TOC placement: which container(s) + the right-rail plugin region render.
+// Logic lives in toc-placement.ts so it's unit-tested; this file just consumes.
+const tocPlacement = resolveTocPlacement(toc, {
+  hasHeadings: headings.length > 0,
+  wideLayout: !!wideLayout,
+});
+
 const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
 
 // SEO computation
@@ -766,6 +786,16 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
           <span class="text-sm text-muted-foreground" data-page-title>{title}</span>
           <div class="ml-auto flex items-center gap-2">
             <slot name="header" />
+            {tocPlacement.popoverToc && (
+              <details class="dba-toc-popover relative" data-toc-popover>
+                <summary class="cursor-pointer list-none rounded-md px-2 py-1.5 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
+                  On this page
+                </summary>
+                <div class="absolute right-0 z-50 mt-1 max-h-[70vh] w-64 overflow-y-auto rounded-md border bg-background p-3 shadow-md">
+                  <DocsToc headings={headings} title="" />
+                </div>
+              </details>
+            )}
             {switcherMap && multiSource && (
               <LocaleSwitcher
                 switcherMap={switcherMap}
@@ -945,6 +975,17 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 </div>
               )}
 
+              {tocPlacement.topToc && (
+                <details class="dba-toc-top not-prose mb-6 rounded-md border" data-toc-top>
+                  <summary class="cursor-pointer list-none px-3 py-2 text-sm font-medium text-muted-foreground">
+                    On this page
+                  </summary>
+                  <div class="border-t px-3 py-2">
+                    <DocsToc headings={headings} title="" />
+                  </div>
+                </details>
+              )}
+
               <slot />
 
               <DocsFooter
@@ -959,17 +1000,41 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             </div>
           </main>
 
-          {headings.length > 0 && !wideLayout && (
+          {/* Classic right-hand TOC — only in `toc: rail` mode. */}
+          {tocPlacement.railToc && (
             <aside class="sticky top-12 hidden h-[calc(100vh-3rem)] w-56 shrink-0 overflow-y-auto border-l p-4 lg:block">
               <DocsToc headings={headings} />
             </aside>
           )}
+          {/* Right-rail plugin region — host for the `right-rail` named slot
+              (e.g. an Ask AI panel). Rendered in every non-rail mode and not
+              gated on headings, so a plugin can dock on heading-less pages.
+              Hidden when nothing fills it (see the empty-rail style below). */}
+          {tocPlacement.regionRail && (
+            <aside
+              class="dba-right-rail sticky top-12 hidden h-[calc(100vh-3rem)] w-56 shrink-0 overflow-y-auto border-l p-4 lg:block"
+              data-right-rail
+            >
+              <slot name="right-rail" />
+            </aside>
+          )}
         </div>
       </SidebarInset>
     </SidebarProvider>
   </body>
 </html>
 
+<style>
+  /* The right-rail plugin region renders unconditionally in non-rail TOC
+     modes so plugins (e.g. Ask AI) can dock into it. Until something fills
+     the `right-rail` slot it has no element children — hide it so an empty
+     bordered column doesn't show. (:has matches element children only; an
+     unfilled Astro named slot renders none.) */
+  aside[data-right-rail]:not(:has(*)) {
+    display: none;
+  }
+</style>
+
 <script>
   import "@dogsbay/ui/sidebar/sidebar.ts";
 

package/src/DocsToc.astro

@@ -33,7 +33,7 @@ const filtered = headings.filter(h => h.depth >= minDepth && h.depth <= maxDepth
 
 {filtered.length > 0 && (
   <nav class:list={["text-sm", className]} aria-label="Table of contents">
-    <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>
+    {title && <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>}
     <ul class="mt-2 space-y-1">
       {filtered.map(h => (
         <li>

package/src/toc-placement.ts

@@ -0,0 +1,51 @@
+/**
+ * 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;
+}
+
+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,
+  };
+}