@dogsbay/docs-layout 0.2.0-beta.0

package/src/switcher.ts

@@ -0,0 +1,138 @@
+/**
+ * Shared logic for axis switchers (Version + Locale, with the
+ * same machinery extending to future axes). Pure functions —
+ * the Astro components are thin wrappers around this module.
+ *
+ * The switcherMap data structure is documented in
+ * `format-astro/src/project.ts` (the emitter side).
+ */
+
+export interface AxisEntry {
+  id: string;
+  label?: string;
+  eol?: boolean;
+  default?: boolean;
+}
+
+export interface SwitcherVariant {
+  locale?: string;
+  version?: string;
+  url: string;
+}
+
+export interface SwitcherMap {
+  versions: AxisEntry[];
+  locales: AxisEntry[];
+  byLogicalKey: Record<string, SwitcherVariant[]>;
+}
+
+export interface MultiSourceMeta {
+  namespace?: string;
+  version?: string;
+  locale?: string;
+  originalSlug: string;
+}
+
+/** The axis the switcher is responsible for. */
+export type SwitcherAxis = "version" | "locale";
+
+/**
+ * Compose the logical key the switcher uses to look up the
+ * current page's variants in `switcherMap.byLogicalKey`.
+ */
+export function logicalKeyFor(ms: MultiSourceMeta): string {
+  return `${ms.namespace ?? "docs"}/${ms.originalSlug}`;
+}
+
+/**
+ * Build the full row data the switcher dropdown needs to
+ * render: declared entries (in order) plus, per row, the
+ * resolved URL for that entry (or null if no variant exists
+ * in this dimension for the current page).
+ *
+ * Row resolution algorithm:
+ *
+ *   For each declared entry on this axis:
+ *     - Find a variant whose <axis>-id matches the entry AND
+ *       whose OTHER axis values match the current page (the
+ *       same locale when switching version, etc.).
+ *     - If found: row.url is the variant's url.
+ *     - Otherwise: row.url is null (rendered as "no equivalent"
+ *       in the dropdown; clicking falls back to the axis's
+ *       landing page).
+ */
+export interface SwitcherRow {
+  entry: AxisEntry;
+  url: string | null;
+  isCurrent: boolean;
+}
+
+export interface BuildRowsInput {
+  axis: SwitcherAxis;
+  switcherMap: SwitcherMap;
+  multiSource: MultiSourceMeta;
+}
+
+export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
+  const { axis, switcherMap, multiSource } = input;
+  const entries = axis === "version" ? switcherMap.versions : switcherMap.locales;
+  const currentId =
+    axis === "version" ? multiSource.version : multiSource.locale;
+  const otherAxis: SwitcherAxis = axis === "version" ? "locale" : "version";
+  const otherCurrent =
+    otherAxis === "version" ? multiSource.version : multiSource.locale;
+
+  const variants = switcherMap.byLogicalKey[logicalKeyFor(multiSource)] ?? [];
+
+  return entries.map((entry) => {
+    const match = variants.find((v) => {
+      // Match on this axis.
+      const thisMatch = axis === "version" ? v.version === entry.id : v.locale === entry.id;
+      if (!thisMatch) return false;
+      // And on the other axis (when active for this page).
+      if (otherCurrent === undefined) return true;
+      const otherMatch =
+        otherAxis === "version" ? v.version === otherCurrent : v.locale === otherCurrent;
+      return otherMatch;
+    });
+    return {
+      entry,
+      url: match?.url ?? null,
+      isCurrent: entry.id === currentId,
+    };
+  });
+}
+
+/**
+ * Whether the switcher should render at all. Two gates:
+ *   - the axis has ≥2 declared entries (single-axis sites
+ *     don't need a dropdown);
+ *   - the current page has metadata for that axis (some pages
+ *     in a multi-version site may sit outside the axis, e.g.
+ *     a custom 404 — they should not show the dropdown).
+ */
+export function shouldRenderSwitcher(
+  axis: SwitcherAxis,
+  switcherMap: SwitcherMap,
+  multiSource: MultiSourceMeta | undefined,
+): boolean {
+  if (!multiSource) return false;
+  const entries = axis === "version" ? switcherMap.versions : switcherMap.locales;
+  if (entries.length < 2) return false;
+  const id = axis === "version" ? multiSource.version : multiSource.locale;
+  return id !== undefined;
+}
+
+/**
+ * Fallback URL for a row whose target variant doesn't exist —
+ * lands on the axis's "landing page" (`<basePath>/<id>/`).
+ * Lets the switcher always be clickable even when a page is
+ * untranslated for some axis combo.
+ */
+export function fallbackLandingUrl(
+  basePath: string,
+  axisEntryId: string,
+): string {
+  const trimmed = basePath.replace(/\/$/, "");
+  return `${trimmed}/${axisEntryId}/`;
+}

package/src/tag-list-data.ts

@@ -0,0 +1,202 @@
+/**
+ * Pure data transform for `<TagList>`. Splitting it out from the
+ * Astro component lets vitest unit-test the chip-building logic
+ * without needing a render container.
+ *
+ * See plans/tag-display-config.md.
+ */
+
+/** Closed palette of tag-chip colors. Mirror of `@dogsbay/types`. */
+export type TagPaletteName =
+  | "blue"
+  | "amber"
+  | "emerald"
+  | "violet"
+  | "rose"
+  | "slate";
+
+export interface PrefixDisplay {
+  label?: string;
+  color?: TagPaletteName;
+}
+
+export interface BuildChipsOptions {
+  /** Path prefix for term pages, e.g. `/tags`. */
+  indexPath: string;
+  /**
+   * Per-prefix display config. Key = top-level segment of the tag.
+   * Tag's first segment is matched here for two-part rendering.
+   */
+  prefixes?: Record<string, PrefixDisplay>;
+  /**
+   * Per-tag leaf-label overrides. Key = full slug; value = display
+   * text. URL still uses the slug.
+   */
+  labels?: Record<string, string>;
+}
+
+export interface ChipModel {
+  /** Original tag slug; used as `data-tag` and for the URL. */
+  tag: string;
+  /** Built href: `<indexPath>/<tag>/`. */
+  href: string;
+  /**
+   * Prefix label when two-part rendering applies (set when the
+   * tag's first segment matches a `prefixes` entry that supplies
+   * a `label`). `null` for flat chips.
+   */
+  prefixLabel: string | null;
+  /** Display text for the leaf. Used in both rendering modes. */
+  leafLabel: string;
+  /** Palette color name to look up; null = default chip styling. */
+  color: TagPaletteName | null;
+}
+
+/**
+ * Filter empty / non-string entries from a raw tag list. Exported
+ * so the component can keep its render guard simple.
+ */
+export function filterTags(tags: readonly unknown[] | undefined): string[] {
+  return (tags ?? []).filter(
+    (t): t is string => typeof t === "string" && t.length > 0,
+  );
+}
+
+/**
+ * Resolve the human-readable display label for one tag.
+ *
+ * Used by both `<TagList>` chip rendering and HTML meta emission
+ * (`<meta property="article:tag">` / JSON-LD `Article.keywords`).
+ * Slug-based identifiers like `difficulty/1` mean nothing to a
+ * search-engine indexer or social-card preview — the label
+ * override (`Beginner`) is the unit that carries meaning.
+ *
+ * Resolution order:
+ * 1. `labels[fullSlug]` — explicit override wins.
+ * 2. Segment after the first `/` — for hierarchical tags without
+ *    an override, the leaf carries the human-meaningful part.
+ * 3. The bare tag — flat tags / final fallback.
+ *
+ * Always returns a non-empty string; never returns the prefix
+ * label (that's chip-rendering chrome, not a stand-alone keyword).
+ */
+export function resolveTagDisplayLabel(
+  tag: string,
+  labels?: Record<string, string>,
+): string {
+  const override = labels?.[tag];
+  if (override && override.length > 0) return override;
+  const slashIdx = tag.indexOf("/");
+  if (slashIdx === -1) return tag;
+  const remainder = tag.slice(slashIdx + 1);
+  return remainder.length > 0 ? remainder : tag;
+}
+
+/**
+ * Map a list of tag slugs to their human-readable display labels.
+ * Drops empty/non-string inputs (via `filterTags`); returns one
+ * label per tag in original order.
+ *
+ * The resulting array is the natural input for HTML meta tags
+ * (`<meta property="article:tag" content="${kw}">` per entry) and
+ * for JSON-LD `Article.keywords` (joined with `", "`).
+ */
+export function resolveTagKeywords(
+  tags: readonly unknown[] | undefined,
+  labels?: Record<string, string>,
+): string[] {
+  return filterTags(tags).map((tag) => resolveTagDisplayLabel(tag, labels));
+}
+
+/**
+ * Resolve the display label for a term identified by its fullPath
+ * array (e.g. `["concept"]` or `["concept", "a11y"]`).
+ *
+ * Used by `<TaxonomyIndex>` term-cloud chips, `<TaxonomyTerm>`
+ * page headings and breadcrumbs, and sub-tag pills — anywhere a
+ * structural slug needs to render as a human label.
+ *
+ * Resolution order:
+ * 1. `labels[fullSlug]` (joined fullPath) — explicit override
+ *    wins, regardless of depth.
+ * 2. For top-level terms (`fullPath.length === 1`):
+ *    `prefixes[segment].label` — lets a top-level segment
+ *    (`concept`, `difficulty`) render as "Concept", "Difficulty".
+ * 3. The leaf segment of the path — the rendered fallback for
+ *    deeper terms with no override.
+ *
+ * URLs continue to use the slug-form `fullPath`. Display only.
+ */
+export function resolveTermLabel(
+  fullPath: readonly string[],
+  prefixes?: Record<string, PrefixDisplay>,
+  labels?: Record<string, string>,
+): string {
+  if (fullPath.length === 0) return "";
+  const slug = fullPath.join("/");
+  const override = labels?.[slug];
+  if (override && override.length > 0) return override;
+  if (fullPath.length === 1) {
+    const prefixLabel = prefixes?.[fullPath[0]]?.label;
+    if (prefixLabel && prefixLabel.length > 0) return prefixLabel;
+  }
+  return fullPath[fullPath.length - 1];
+}
+
+/**
+ * Map raw tag slugs to render-ready chip models, applying prefix
+ * + label config rules.
+ *
+ * Rules:
+ * - URL is always `<indexPath>/<tag>/` regardless of label
+ *   override — taxonomy term pages live at the slug path.
+ * - Two-part chip path requires both: a `prefixes` entry for the
+ *   first segment AND that entry having `label` or `color` set.
+ *   Without either, falls back to flat rendering (back-compat for
+ *   sites that haven't declared display config).
+ * - Leaf label resolution order: `labels[fullSlug]` override,
+ *   then the segment after the first slash, then the bare tag
+ *   (used when a prefix-only-color entry matches a non-nested tag).
+ * - Color from prefix entry; null when absent (default styling).
+ */
+export function buildChips(
+  tags: readonly unknown[] | undefined,
+  options: BuildChipsOptions,
+): ChipModel[] {
+  const safe = filterTags(tags);
+  const { indexPath, prefixes, labels } = options;
+
+  return safe.map((tag): ChipModel => {
+    const href = `${indexPath}/${tag}/`;
+    const slashIdx = tag.indexOf("/");
+    const firstSegment = slashIdx === -1 ? tag : tag.slice(0, slashIdx);
+    const prefixEntry = prefixes?.[firstSegment];
+    const overrideLeaf = labels?.[tag];
+
+    // Flat chip: preserves the full slug (`#concept/a11y`) when no
+    // prefix entry matches. The slash signals hierarchy visually
+    // even without explicit display config.
+    if (!prefixEntry || (!prefixEntry.label && !prefixEntry.color)) {
+      return {
+        tag,
+        href,
+        prefixLabel: null,
+        leafLabel: overrideLeaf ?? tag,
+        color: null,
+      };
+    }
+
+    // Two-part chip: prefix takes the structural segment, leaf
+    // gets the meaningful name (override or remainder after first
+    // slash). Falls back to the bare tag for non-nested entries.
+    const remainder = slashIdx === -1 ? tag : tag.slice(slashIdx + 1);
+    const leafLabel = overrideLeaf ?? remainder;
+    return {
+      tag,
+      href,
+      prefixLabel: prefixEntry.label ?? null,
+      leafLabel: leafLabel.length > 0 ? leafLabel : tag,
+      color: prefixEntry.color ?? null,
+    };
+  });
+}

package/src/toc-kind.css

@@ -0,0 +1,52 @@
+.toc-kind {
+  display: inline-block;
+  border-radius: 0.25rem;
+  padding: 0 0.3rem;
+  font-size: 0.6rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: lowercase;
+  vertical-align: middle;
+  margin-right: 0.35rem;
+  line-height: 1.4;
+}
+.toc-kind-class {
+  background-color: oklch(0.55 0.18 265 / 0.15);
+  color: oklch(0.55 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);
+}
+.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);
+}
+.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);
+}
+.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);
+}
+.dark .toc-kind-module {
+  background-color: oklch(0.65 0.12 200 / 0.2);
+  color: oklch(0.65 0.12 200);
+}

package/src/version-redirect.ts

@@ -0,0 +1,147 @@
+/**
+ * Default-axis redirect decision helper.
+ *
+ * Combines the default-version redirect (PR 4c) with the
+ * default-locale redirect (PR 5c) into one helper. When a
+ * request URL is missing the locale or version segment that
+ * the site has declared, the helper returns the canonical URL
+ * with the missing segment(s) injected in the correct order
+ * (locale outermost, then version, per the site's URL
+ * convention).
+ *
+ * Pure function — no I/O, no globals. Inlined into the emitted
+ * Astro middleware. The middleware issues a 302 to the returned
+ * URL (302 not 301 — the switchers let readers navigate away
+ * from the default, so we don't want browsers permanently
+ * caching the unprefixed URL as default content).
+ *
+ * The function is exported under the historical name
+ * `shouldRedirectToDefaultVersion` for backward compat but now
+ * also handles locale. New code can import the same name.
+ */
+
+export interface AxisRedirectConfig {
+  /**
+   * URL prefix where docs are served, e.g. "/docs" or "" for
+   * root-served sites. Should be a normalized basePath
+   * (no trailing slash for non-empty values).
+   */
+  basePath: string;
+  /** Default version id; required when version axis is active. */
+  defaultVersion?: string;
+  /** Full set of declared version ids. Empty/undefined → axis inactive. */
+  knownVersions?: string[];
+  /** Default locale id; required when locale axis is active. */
+  defaultLocale?: string;
+  /** Full set of declared locale ids. Empty/undefined → axis inactive. */
+  knownLocales?: string[];
+}
+
+/**
+ * Returns the redirect target when the pathname is missing one
+ * or more axis segments, or `null` when the request should pass
+ * through.
+ *
+ * Behaviour:
+ *   - Skips when neither axis is active (knownVersions <2 AND
+ *     knownLocales <2).
+ *   - Skips paths outside the configured basePath.
+ *   - Skips the bare basePath (root index handles its own
+ *     redirect).
+ *   - Skips asset paths (`_*` prefix, `pagefind`).
+ *   - Determines which segments are PRESENT (locale first,
+ *     version second per canonical order) by greedy matching
+ *     against `knownLocales` then `knownVersions`. Missing
+ *     segments are injected from the corresponding default.
+ */
+export function shouldRedirectToDefaultVersion(
+  pathname: string,
+  config: AxisRedirectConfig,
+): string | null {
+  const versionAxisActive =
+    !!config.defaultVersion && (config.knownVersions ?? []).length >= 2;
+  const localeAxisActive =
+    !!config.defaultLocale && (config.knownLocales ?? []).length >= 2;
+  if (!versionAxisActive && !localeAxisActive) return null;
+
+  const basePath = config.basePath.replace(/\/$/, "");
+
+  // Strip basePath. If not under basePath, pass through.
+  let rest: string;
+  if (basePath === "") {
+    rest = pathname;
+  } else if (pathname === basePath || pathname === `${basePath}/`) {
+    rest = "";
+  } else if (pathname.startsWith(`${basePath}/`)) {
+    rest = pathname.slice(basePath.length);
+  } else {
+    return null;
+  }
+
+  if (!rest.startsWith("/")) rest = `/${rest}`;
+  const trimmed = rest.replace(/\/+$/, "");
+  if (trimmed === "" || trimmed === "/") return null;
+
+  const segments = trimmed.replace(/^\//, "").split("/");
+  if (segments.length === 0) return null;
+
+  // Skip Astro / Pagefind asset paths.
+  if (segments[0].startsWith("_") || segments[0] === "pagefind") return null;
+
+  // Greedy axis detection — locale outermost, version next.
+  const knownLocales = new Set(config.knownLocales ?? []);
+  const knownVersions = new Set(config.knownVersions ?? []);
+
+  let cursor = 0;
+  let presentLocale: string | undefined;
+  let presentVersion: string | undefined;
+
+  if (localeAxisActive && knownLocales.has(segments[0])) {
+    presentLocale = segments[0];
+    cursor = 1;
+  }
+  if (
+    versionAxisActive &&
+    cursor < segments.length &&
+    knownVersions.has(segments[cursor])
+  ) {
+    presentVersion = segments[cursor];
+    cursor += 1;
+  }
+
+  // What's the rest of the path beyond the recognised axis prefixes?
+  const tailSegments = segments.slice(cursor);
+  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)
+    ) {
+      // Some axis still missing — fall through to redirect.
+    } else {
+      return null;
+    }
+  }
+
+  // If all required-active axes are present, no redirect needed.
+  const localeNeeded = localeAxisActive && presentLocale === undefined;
+  const versionNeeded = versionAxisActive && presentVersion === undefined;
+  if (!localeNeeded && !versionNeeded) return null;
+
+  // Compose the redirect target with missing segments injected
+  // in canonical order (<locale>/<version>/<tail>).
+  const out: string[] = [];
+  if (localeAxisActive) {
+    out.push(presentLocale ?? config.defaultLocale!);
+  }
+  if (versionAxisActive) {
+    out.push(presentVersion ?? config.defaultVersion!);
+  }
+  out.push(...tailSegments);
+
+  // Preserve trailing slash from the original pathname.
+  const trailing = pathname.endsWith("/") && !pathname.endsWith(`${basePath}/`);
+  return `${basePath}/${out.join("/")}${trailing ? "/" : ""}`;
+}