@dogsbay/docs-layout 0.2.0-beta.14 → 0.2.0-beta.140

package/src/tag-list-data.ts

@@ -33,6 +33,29 @@ export interface BuildChipsOptions {
    * text. URL still uses the slug.
    */
   labels?: Record<string, string>;
+  /**
+   * Color chips whose prefix has no `color` with a palette color
+   * hashed from the first segment (`autoTagColor`). Default false.
+   */
+  autoColor?: boolean;
+}
+
+/** Palette order for automatic colors. */
+const AUTO_PALETTE: readonly TagPaletteName[] = ["blue", "amber", "emerald", "violet", "rose", "slate"];
+
+/**
+ * A stable palette color for a tag segment: FNV-1a hash of the
+ * lowercased segment, modulo the palette. The same segment gets the
+ * same color on every page and every build; with more distinct tags
+ * than colors, colors repeat.
+ */
+export function autoTagColor(segment: string): TagPaletteName {
+  let hash = 0x811c9dc5;
+  for (const ch of segment.toLowerCase()) {
+    hash ^= ch.codePointAt(0)!;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return AUTO_PALETTE[hash % AUTO_PALETTE.length];
 }
 
 export interface ChipModel {
@@ -164,7 +187,7 @@ export function buildChips(
   options: BuildChipsOptions,
 ): ChipModel[] {
   const safe = filterTags(tags);
-  const { indexPath, prefixes, labels } = options;
+  const { indexPath, prefixes, labels, autoColor = false } = options;
 
   return safe.map((tag): ChipModel => {
     const href = `${indexPath}/${tag}/`;
@@ -182,7 +205,7 @@ export function buildChips(
         href,
         prefixLabel: null,
         leafLabel: overrideLeaf ?? tag,
-        color: null,
+        color: autoColor ? autoTagColor(firstSegment) : null,
       };
     }
 
@@ -196,7 +219,7 @@ export function buildChips(
       href,
       prefixLabel: prefixEntry.label ?? null,
       leafLabel: leafLabel.length > 0 ? leafLabel : tag,
-      color: prefixEntry.color ?? null,
+      color: prefixEntry.color ?? (autoColor ? autoTagColor(firstSegment) : null),
     };
   });
 }

package/src/toc-kind.css

@@ -11,40 +11,40 @@
   line-height: 1.4;
 }
 .toc-kind-class {
-  background-color: oklch(0.55 0.18 265 / 0.15);
-  color: oklch(0.55 0.18 265);
+  background-color: oklch(0.44 0.18 265 / 0.15);
+  color: oklch(0.44 0.18 265);
 }
 .dark .toc-kind-class {
   background-color: oklch(0.7 0.15 265 / 0.2);
   color: oklch(0.7 0.15 265);
 }
 .toc-kind-meth {
-  background-color: oklch(0.55 0.15 155 / 0.15);
-  color: oklch(0.55 0.15 155);
+  background-color: oklch(0.44 0.15 155 / 0.15);
+  color: oklch(0.44 0.15 155);
 }
 .dark .toc-kind-meth {
   background-color: oklch(0.7 0.15 155 / 0.2);
   color: oklch(0.7 0.15 155);
 }
 .toc-kind-attr {
-  background-color: oklch(0.6 0.15 55 / 0.15);
-  color: oklch(0.6 0.15 55);
+  background-color: oklch(0.44 0.15 55 / 0.15);
+  color: oklch(0.44 0.15 55);
 }
 .dark .toc-kind-attr {
   background-color: oklch(0.75 0.15 55 / 0.2);
   color: oklch(0.75 0.15 55);
 }
 .toc-kind-func {
-  background-color: oklch(0.55 0.18 330 / 0.15);
-  color: oklch(0.55 0.18 330);
+  background-color: oklch(0.44 0.18 330 / 0.15);
+  color: oklch(0.44 0.18 330);
 }
 .dark .toc-kind-func {
   background-color: oklch(0.7 0.15 330 / 0.2);
   color: oklch(0.7 0.15 330);
 }
 .toc-kind-module {
-  background-color: oklch(0.5 0.12 200 / 0.15);
-  color: oklch(0.5 0.12 200);
+  background-color: oklch(0.44 0.12 200 / 0.15);
+  color: oklch(0.44 0.12 200);
 }
 .dark .toc-kind-module {
   background-color: oklch(0.65 0.12 200 / 0.2);

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

package/src/version-redirect.ts

@@ -31,6 +31,15 @@ export interface AxisRedirectConfig {
   defaultVersion?: string;
   /** Full set of declared version ids. Empty/undefined → axis inactive. */
   knownVersions?: string[];
+  /**
+   * The version served at the site root (`versions[].path: ""`, the
+   * default version). A URL with no version segment is one of its pages,
+   * so the version is never injected; a URL starting with another known
+   * version's segment is that version's (the longest matching prefix
+   * wins). Only the locale redirect remains. format-astro emits no version
+   * config at all in that case; this keeps the helper right when given one.
+   */
+  rootVersion?: string;
   /** Default locale id; required when locale axis is active. */
   defaultLocale?: string;
   /** Full set of declared locale ids. Empty/undefined → axis inactive. */
@@ -126,7 +135,8 @@ export function shouldRedirectToDefaultVersion(
   if (
     versionAxisActive &&
     cursor < segments.length &&
-    knownVersions.has(segments[cursor])
+    knownVersions.has(segments[cursor]) &&
+    segments[cursor] !== config.rootVersion
   ) {
     presentVersion = segments[cursor];
     cursor += 1;
@@ -134,13 +144,16 @@ export function shouldRedirectToDefaultVersion(
 
   // What's the rest of the path beyond the recognised axis prefixes?
   const tailSegments = segments.slice(cursor);
+  // With a root version, a URL without a version segment is already complete.
+  const versionMissing =
+    versionAxisActive && presentVersion === undefined && !config.rootVersion;
   if (tailSegments.length === 0) {
     // The path is JUST a known axis prefix (e.g. /docs/en/ or
     // /docs/v1/). Treat as the axis's landing page; no redirect
     // needed unless other axes are MISSING from the URL too.
     if (
       (localeAxisActive && presentLocale === undefined) ||
-      (versionAxisActive && presentVersion === undefined)
+      versionMissing
     ) {
       // Some axis still missing — fall through to redirect.
     } else {
@@ -150,7 +163,7 @@ export function shouldRedirectToDefaultVersion(
 
   // If all required-active axes are present, no redirect needed.
   const localeNeeded = localeAxisActive && presentLocale === undefined;
-  const versionNeeded = versionAxisActive && presentVersion === undefined;
+  const versionNeeded = versionMissing;
   if (!localeNeeded && !versionNeeded) return null;
 
   // Compose the redirect target with missing segments injected
@@ -159,7 +172,7 @@ export function shouldRedirectToDefaultVersion(
   if (localeAxisActive) {
     out.push(presentLocale ?? config.defaultLocale!);
   }
-  if (versionAxisActive) {
+  if (versionAxisActive && (presentVersion !== undefined || !config.rootVersion)) {
     out.push(presentVersion ?? config.defaultVersion!);
   }
   out.push(...tailSegments);