@dogsbay/docs-layout 0.2.0-beta.0

package/src/llm-actions.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure helpers for the per-page LLM action cluster ("Copy as
+ * markdown", "Open in Claude / ChatGPT / Perplexity / Gemini").
+ *
+ * The PageActions Astro component composes these helpers with
+ * existing CopyButton + DropdownMenu primitives. Keeping the
+ * pure logic in its own module makes it directly testable and
+ * lets renderers compute deep links at SSR time without any
+ * client-side JS.
+ *
+ * Provider deep-link templates (URL-encoded `?q={prompt}`):
+ *   - claude     → https://claude.ai/new?q=…
+ *   - chatgpt    → https://chatgpt.com/?q=…
+ *   - perplexity → https://www.perplexity.ai/search?q=…
+ *   - gemini     → https://gemini.google.com/app?q=…
+ *
+ * Prompts are URL-only by default ("Read this docs page: <url>"):
+ * passing full markdown via query string hits the ~2KB practical
+ * URL length limit fast, and the page is already served as
+ * `text/markdown` from a stable URL.
+ */
+
+export type LlmProviderName = "claude" | "chatgpt" | "perplexity" | "gemini";
+
+export interface ProviderInfo {
+  name: LlmProviderName;
+  /** Human label for the menu item ("Open in Claude"). */
+  label: string;
+  /** Deep-link template; `{q}` is replaced by the URL-encoded prompt. */
+  urlTemplate: string;
+}
+
+export const DEFAULT_PROMPT_TEMPLATE = "Read this docs page: {url}";
+
+export const DEFAULT_PROVIDERS: LlmProviderName[] = [
+  "claude",
+  "chatgpt",
+  "perplexity",
+  "gemini",
+];
+
+const PROVIDER_REGISTRY: Record<LlmProviderName, ProviderInfo> = {
+  claude: {
+    name: "claude",
+    label: "Open in Claude",
+    urlTemplate: "https://claude.ai/new?q={q}",
+  },
+  chatgpt: {
+    name: "chatgpt",
+    label: "Open in ChatGPT",
+    urlTemplate: "https://chatgpt.com/?q={q}",
+  },
+  perplexity: {
+    name: "perplexity",
+    label: "Open in Perplexity",
+    urlTemplate: "https://www.perplexity.ai/search?q={q}",
+  },
+  gemini: {
+    name: "gemini",
+    label: "Open in Gemini",
+    urlTemplate: "https://gemini.google.com/app?q={q}",
+  },
+};
+
+/** All known provider names — useful for config validation. */
+export function knownProviders(): LlmProviderName[] {
+  return Object.keys(PROVIDER_REGISTRY) as LlmProviderName[];
+}
+
+/**
+ * Substitute `{url}` in the template, then URL-encode the result for
+ * `?q=` placement. Used by `providerDeepLink`. Other placeholders
+ * are left intact so writers can include literal braces if needed.
+ */
+export function buildPrompt(template: string, mdUrl: string): string {
+  return template.replace(/\{url\}/g, mdUrl);
+}
+
+/**
+ * Construct the full deep-link URL for one provider with a given
+ * page MD URL and prompt template.
+ *
+ * Throws when `provider` is not a known provider — config
+ * validation should reject unknown values upstream, but this
+ * keeps the helper honest.
+ */
+export function providerDeepLink(
+  provider: LlmProviderName,
+  mdUrl: string,
+  template: string = DEFAULT_PROMPT_TEMPLATE,
+): string {
+  const info = PROVIDER_REGISTRY[provider];
+  if (!info) {
+    throw new Error(`Unknown LLM provider: ${String(provider)}`);
+  }
+  const prompt = buildPrompt(template, mdUrl);
+  return info.urlTemplate.replace(/\{q\}/g, encodeURIComponent(prompt));
+}
+
+/**
+ * Resolve a configured provider list to ProviderInfo objects, in
+ * order. Drops unknown names rather than throwing — at config-load
+ * time we validate; at render time we want a missing provider not
+ * to crash the page. Empty / undefined input returns an empty
+ * array (caller decides whether to render the dropdown at all).
+ */
+export function resolveProviders(
+  providers: readonly LlmProviderName[] | undefined,
+): ProviderInfo[] {
+  const list = providers && providers.length > 0 ? providers : DEFAULT_PROVIDERS;
+  const out: ProviderInfo[] = [];
+  for (const name of list) {
+    const info = PROVIDER_REGISTRY[name];
+    if (info) out.push(info);
+  }
+  return out;
+}
+
+/**
+ * Get a single provider's metadata. Returns `null` for unknown names.
+ * Used by tests and callers that need just the label or template
+ * without going through deep-link construction.
+ */
+export function getProviderInfo(
+  provider: LlmProviderName,
+): ProviderInfo | null {
+  return PROVIDER_REGISTRY[provider] ?? null;
+}

package/src/markdown-negotiation.ts

@@ -0,0 +1,76 @@
+/**
+ * Decision helper for `Accept: text/markdown` content negotiation.
+ *
+ * Pure function — no Astro dep — so the generated `src/middleware.ts`
+ * can import and use it, and so it's unit-testable on its own.
+ *
+ * Returns the path to rewrite to (the `.md` mirror endpoint) when the
+ * request should be served as markdown; returns `null` when the normal
+ * HTML response should pass through.
+ */
+
+const Q_PARAM_RE = /^\s*q\s*=\s*([0-9.]+)\s*$/i;
+
+/**
+ * Decide whether to rewrite a request to its `.md` mirror.
+ *
+ * The request matches when ALL of the following are true:
+ *   1. The Accept header expresses a non-zero preference for
+ *      `text/markdown` (or `text/*` accepts it implicitly).
+ *   2. The path doesn't already point at a `.md` file.
+ *   3. The path doesn't include a different extension (e.g.
+ *      `/pagefind/pagefind.js`, `/assets/style.css`, `/llms.txt`,
+ *      `/sitemap.xml`) — those have their own content type and must
+ *      pass through unchanged.
+ *
+ * @returns the rewrite target path, or `null` to pass through.
+ */
+export function shouldRewriteToMarkdown(
+  accept: string | null | undefined,
+  pathname: string,
+): string | null {
+  if (!accept) return null;
+  if (!acceptsMarkdown(accept)) return null;
+  if (pathname.endsWith(".md")) return null;
+  if (hasNonHtmlExtension(pathname)) return null;
+
+  const trimmed = pathname.replace(/\/$/, "");
+  const target = trimmed === "" ? "/.md" : `${trimmed}.md`;
+  return target;
+}
+
+function acceptsMarkdown(accept: string): boolean {
+  // Iterate the Accept entries; honor q=0 (explicit reject) for any
+  // matching media type. We accept `text/markdown` and `text/*` as
+  // valid markdown matchers; `*/*` alone is NOT enough — a default
+  // browser sends `*/*` and expects HTML.
+  const parts = accept.split(",").map((p) => p.trim());
+  for (const part of parts) {
+    const [type, ...params] = part.split(";").map((s) => s.trim());
+    if (type !== "text/markdown" && type !== "text/*") continue;
+    let q = 1;
+    for (const param of params) {
+      const m = param.match(Q_PARAM_RE);
+      if (m) q = parseFloat(m[1]);
+    }
+    if (q > 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Path looks like an asset (has a non-`.md` extension on the last
+ * segment). We don't want to rewrite e.g. `/pagefind/pagefind.js`
+ * to `/pagefind/pagefind.js.md` — that file doesn't exist and the
+ * request would 404.
+ */
+function hasNonHtmlExtension(pathname: string): boolean {
+  const lastSlash = pathname.lastIndexOf("/");
+  const tail = lastSlash >= 0 ? pathname.slice(lastSlash + 1) : pathname;
+  const dot = tail.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const ext = tail.slice(dot + 1).toLowerCase();
+  // .html is treated as a regular page suffix — Astro can serve a .md
+  // mirror in that case, so don't bail out. Everything else is an asset.
+  return ext !== "html" && ext !== "htm";
+}

package/src/nav-filter.ts

@@ -0,0 +1,166 @@
+/**
+ * Multi-source nav filtering.
+ *
+ * When a docs site has multiple versions (or, in PR 5, locales)
+ * configured, every page's emitted nav.json contains entries
+ * from EVERY version. Without filtering, the sidebar shows
+ * duplicate sections — once per version — which is confusing
+ * UX (writers see "Glossary" twice).
+ *
+ * The fix: filter the nav tree to entries that match the
+ * current page's version (or, eventually, locale). Pure
+ * function; takes nav + axis filter, returns a pruned copy.
+ *
+ * The axis switchers handle navigation BETWEEN versions; the
+ * sidebar nav reflects only the active axis bucket.
+ */
+
+interface NavItem {
+  label: string;
+  href?: string;
+  children?: NavItem[];
+}
+
+export interface NavFilter {
+  /** Site basePath (e.g. "/docs"). Used to compose the version prefix. */
+  basePath: string;
+  /**
+   * Current page's effective version. When undefined, no
+   * version filtering is applied — single-version sites pass
+   * the full nav through unchanged.
+   */
+  version?: string;
+  /**
+   * Current page's effective locale. When set, nav items are
+   * filtered to those whose href starts with the corresponding
+   * locale segment (`<basePath>/<locale>/`).
+   */
+  locale?: string;
+}
+
+/**
+ * Walk the nav tree and drop entries that don't belong to the
+ * current version + locale. Group nodes (no `href`, with
+ * `children`) survive iff any descendant survives — empty
+ * groups are pruned.
+ *
+ * Items without `href` AND without `children` are unusual but
+ * pass through unchanged (defensive — never silently drop a
+ * node we don't understand).
+ *
+ * Both filters apply concurrently: a multi-version multi-locale
+ * site filters by BOTH simultaneously, so an item must match
+ * /<basePath>/<locale>/.../<version>/... structurally.
+ */
+export function filterNavByAxis(
+  items: NavItem[],
+  filter: NavFilter,
+): NavItem[] {
+  if (!filter.version && !filter.locale) return items;
+
+  // Locale axis prefix is the OUTERMOST per the canonical URL
+  // composition: /<basePath>/<locale>/<version>/<ns>/<slug>.
+  // We check the locale prefix first (basePath/<locale>/), then
+  // (when version is also active) check that <version> is the
+  // immediately-following segment.
+  const localePrefix = filter.locale
+    ? prefixFor(filter.basePath, filter.locale)
+    : null;
+  const versionSegment = filter.version ?? null;
+
+  return items.flatMap((item) =>
+    filterOne(item, localePrefix, versionSegment, filter.basePath),
+  );
+}
+
+function filterOne(
+  item: NavItem,
+  localePrefix: string | null,
+  versionSegment: string | null,
+  basePath: string,
+): NavItem[] {
+  if (item.children && item.children.length > 0) {
+    const kept = item.children.flatMap((c) =>
+      filterOne(c, localePrefix, versionSegment, basePath),
+    );
+    if (kept.length === 0) return [];
+    return [{ ...item, children: kept }];
+  }
+  if (item.href !== undefined) {
+    if (!hrefMatchesAxes(item.href, localePrefix, versionSegment, basePath)) {
+      return [];
+    }
+    return [item];
+  }
+  return [item];
+}
+
+/**
+ * Check that an href belongs to the requested (locale, version)
+ * combination. Either prefix can be null — meaning that axis
+ * isn't being filtered.
+ */
+function hrefMatchesAxes(
+  href: string,
+  localePrefix: string | null,
+  versionSegment: string | null,
+  basePath: string,
+): boolean {
+  // External URLs aren't axis-bucketed.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
+    return false;
+  }
+
+  // Step 1: locale check. If locale axis is active, the href
+  // must be inside /<basePath>/<locale>/.
+  if (localePrefix !== null) {
+    if (!hrefMatchesPrefix(href, localePrefix)) return false;
+  }
+
+  // Step 2: version check. The version segment is positioned
+  // AFTER the locale segment when both are active, otherwise
+  // immediately after basePath.
+  if (versionSegment !== null) {
+    const baseTrimmed = basePath.replace(/\/$/, "");
+    const localeSegStart = localePrefix
+      ? localePrefix.replace(/\/$/, "")
+      : baseTrimmed;
+    const versionPrefix = `${localeSegStart}/${versionSegment}/`;
+    const versionPrefixNoSlash = versionPrefix.replace(/\/$/, "");
+    if (
+      !href.startsWith(versionPrefix) &&
+      href !== versionPrefixNoSlash
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Compose the URL prefix for a given version under the
+ * configured basePath. Always ends in `/` so prefix-matching
+ * doesn't accept partial segments (`/docs/v1` shouldn't match
+ * `/docs/v10/...`).
+ */
+function prefixFor(basePath: string, segment: string): string {
+  const base = basePath.replace(/\/$/, "");
+  return `${base}/${segment}/`;
+}
+
+/**
+ * Whether an href belongs to the given version prefix. Tolerates
+ * trailing slashes and missing-trailing-slash variants — nav
+ * importers don't all canonicalise the same way.
+ */
+function hrefMatchesPrefix(href: string, prefix: string): boolean {
+  // Skip external URLs.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
+    return false;
+  }
+  // Match `/docs/v1/...` AND `/docs/v1` (the version's landing
+  // page itself, if a writer linked to it directly).
+  const trimmedPrefix = prefix.replace(/\/$/, "");
+  return href.startsWith(prefix) || href === trimmedPrefix;
+}

package/src/pagination.ts

@@ -0,0 +1,39 @@
+interface NavItem {
+  label: string;
+  href?: string;
+  children?: NavItem[];
+}
+
+interface PaginationLink {
+  label: string;
+  href: string;
+}
+
+interface PaginationResult {
+  prev: PaginationLink | undefined;
+  next: PaginationLink | undefined;
+}
+
+/**
+ * Flatten a nav tree into an ordered list of pages.
+ * Find prev/next for the given path.
+ */
+export function getPagination(currentPath: string, nav: NavItem[]): PaginationResult {
+  const allPages = flattenNav(nav);
+  const normalized = currentPath.replace(/\/$/, "") || "/";
+  const index = allPages.findIndex(p => p.href.replace(/\/$/, "") === normalized);
+
+  return {
+    prev: index > 0 ? allPages[index - 1] : undefined,
+    next: index < allPages.length - 1 ? allPages[index + 1] : undefined,
+  };
+}
+
+function flattenNav(items: NavItem[]): PaginationLink[] {
+  const result: PaginationLink[] = [];
+  for (const item of items) {
+    if (item.href) result.push({ label: item.label, href: item.href });
+    if (item.children) result.push(...flattenNav(item.children));
+  }
+  return result;
+}

package/src/search-facets.ts

@@ -0,0 +1,232 @@
+/**
+ * Pure helpers for search-facet UI in `<SearchDialog>`. Splitting
+ * the data transforms here lets vitest exercise them without
+ * needing a Pagefind runtime or rendered DOM.
+ *
+ * See plans/search-facets.md.
+ */
+import { resolveTermLabel } from "./tag-list-data.js";
+import type { PrefixDisplay } from "./tag-list-data.js";
+
+/**
+ * Per-taxonomy display config — same shape as
+ * `SiteConfig.taxonomyDisplay[name]`. Keyed locally so this module
+ * has no runtime dependency on `@dogsbay/types`.
+ */
+export interface TaxonomyDisplay {
+  prefixes?: Record<string, PrefixDisplay>;
+  labels?: Record<string, string>;
+}
+
+/** Map of taxonomy name → display config. */
+export type TaxonomyDisplayMap = Record<string, TaxonomyDisplay>;
+
+/** One facet entry — value plus the count of pages tagged with it. */
+export interface FacetEntry {
+  /** The slug as Pagefind indexed it (e.g. `"concept/a11y"`, `"how-to"`). */
+  value: string;
+  /** Page count for this value within the current corpus. */
+  count: number;
+}
+
+/** Map of facet name (taxonomy) → ordered entries. */
+export type FacetMap = Record<string, FacetEntry[]>;
+
+/**
+ * Pagefind's filters API surface — a thin subset of the runtime
+ * shape, kept local so this module stays dependency-free.
+ *
+ * `pagefind.filters()` resolves to a nested map:
+ * `{ <facetName>: { <value>: <count> } }`. We sort + flatten it.
+ */
+export interface PagefindLike {
+  filters(): Promise<Record<string, Record<string, number>>>;
+}
+
+/**
+ * Convert Pagefind's nested filter map into a sorted `FacetMap`.
+ *
+ * Sort order: count descending, then value ascending alphabetically
+ * (stable tie-break). Empty value lists are dropped — a facet with
+ * zero values isn't worth a row in the UI. Returns an empty
+ * `FacetMap` when Pagefind reports no filters at all (Pagefind log
+ * still says "Indexed 0 filters" — usually means the head→body fix
+ * hasn't propagated, not a real "no-tags" site).
+ */
+export function shapeFacets(
+  raw: Record<string, Record<string, number>> | undefined | null,
+): FacetMap {
+  if (!raw) return {};
+  const out: FacetMap = {};
+  for (const [name, valueMap] of Object.entries(raw)) {
+    const entries = sortFacetEntries(
+      Object.entries(valueMap).map(([value, count]) => ({ value, count })),
+    );
+    if (entries.length > 0) out[name] = entries;
+  }
+  return out;
+}
+
+/**
+ * Sort facet entries by count descending, then by value
+ * ascending alphabetically. Stable for equal-count values so
+ * the UI doesn't shuffle between renders.
+ */
+export function sortFacetEntries(entries: FacetEntry[]): FacetEntry[] {
+  return [...entries].sort((a, b) => {
+    if (a.count !== b.count) return b.count - a.count;
+    return a.value.localeCompare(b.value);
+  });
+}
+
+/**
+ * Resolve the human display label for one facet value.
+ *
+ * Maps the slug-form value to the configured display string by
+ * looking up the per-taxonomy display config. For slash-nested
+ * values (`concept/a11y`), the resolution rules match
+ * `<TagList>` chip rendering: explicit label override wins, then
+ * prefix label for top-level segments, then leaf segment as a
+ * final fallback.
+ *
+ * Slug paths are split into segments via `/`, mirroring how
+ * taxonomies indexes terms.
+ */
+export function resolveFacetLabel(
+  facetName: string,
+  value: string,
+  display?: TaxonomyDisplayMap,
+): string {
+  const taxonomy = display?.[facetName];
+  const fullPath = value.split("/").filter((s) => s.length > 0);
+  return resolveTermLabel(fullPath, taxonomy?.prefixes, taxonomy?.labels);
+}
+
+/**
+ * Resolve the display label for a facet name itself (the column
+ * header text). Looks up `prefixes[facetName].label` for built-in
+ * taxonomies (`tags` → "Tags"), falling back to a humanized
+ * version of the facet name (`by-audience` → "By audience").
+ *
+ * Per-taxonomy `prefixes` aren't a perfect fit here (they're keyed
+ * by the segment, not by the taxonomy itself), so this is a
+ * separate humanizer. Future schema work can add an explicit
+ * `taxonomies.<name>.displayName` field if writers want full
+ * control.
+ */
+export function resolveFacetTitle(facetName: string): string {
+  return facetName
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// ── URL persistence ──────────────────────────────────────────────
+
+/**
+ * Active filter state — keyed by facet name, value is the set of
+ * selected slugs (multi-select per facet, AND across facets).
+ */
+export type FilterState = Record<string, string[]>;
+
+/**
+ * Build URLSearchParams from the current filter state. Each
+ * facet:value combination produces one `filter=<name>:<value>`
+ * entry, repeated per selection. The `q` query param is added
+ * only when query is non-empty.
+ *
+ * Resulting URL is shareable — re-loading restores both the
+ * search query AND active filters.
+ */
+export function filterStateToUrlParams(
+  query: string,
+  filters: FilterState,
+): URLSearchParams {
+  const params = new URLSearchParams();
+  if (query.trim().length > 0) params.set("q", query.trim());
+  for (const [name, values] of Object.entries(filters)) {
+    for (const value of values) {
+      params.append("filter", `${name}:${value}`);
+    }
+  }
+  return params;
+}
+
+/**
+ * Parse `URLSearchParams` back into `{ query, filters }`. The
+ * inverse of `filterStateToUrlParams`. Tolerant of malformed
+ * `filter=...` entries — anything missing the `:` separator is
+ * silently dropped (forward-compat with future schema).
+ */
+export function parseFiltersFromUrl(
+  params: URLSearchParams,
+): { query: string; filters: FilterState } {
+  const query = params.get("q") ?? "";
+  const filters: FilterState = {};
+  for (const raw of params.getAll("filter")) {
+    const colonIdx = raw.indexOf(":");
+    if (colonIdx < 1) continue; // need at least 1 char before the colon
+    const name = raw.slice(0, colonIdx);
+    const value = raw.slice(colonIdx + 1);
+    if (!value) continue;
+    if (!filters[name]) filters[name] = [];
+    if (!filters[name].includes(value)) filters[name].push(value);
+  }
+  return { query, filters };
+}
+
+/**
+ * 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.
+ *
+ * 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".
+ */
+export function filterStateToPagefindFilters(
+  filters: FilterState,
+): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [name, values] of Object.entries(filters)) {
+    if (values.length > 0) out[name] = [...values];
+  }
+  return out;
+}
+
+/**
+ * Toggle a single (facetName, value) pair in the filter state.
+ * Returns a new state object — the input is never mutated, so
+ * callers can safely use this with React-style "set state to a
+ * new value" patterns or vanilla state diffing.
+ */
+export function toggleFilter(
+  filters: FilterState,
+  name: string,
+  value: string,
+): FilterState {
+  const next: FilterState = { ...filters };
+  const current = next[name] ?? [];
+  if (current.includes(value)) {
+    const dropped = current.filter((v) => v !== value);
+    if (dropped.length === 0) {
+      delete next[name];
+    } else {
+      next[name] = dropped;
+    }
+  } else {
+    next[name] = [...current, value];
+  }
+  return next;
+}
+
+/**
+ * Count the total number of active filter selections across all
+ * facets. Used to render a "Clear all" button only when there's
+ * something to clear.
+ */
+export function countActiveFilters(filters: FilterState): number {
+  let n = 0;
+  for (const values of Object.values(filters)) n += values.length;
+  return n;
+}