@kirchdev/duxt 0.3.4 → 0.3.5-dev-main.44-5337cc1

package/app/utils/page-controls.ts

@@ -0,0 +1,215 @@
+/**
+ * What a PAGE gets to say about the docs shell drawn around it.
+ *
+ * A page could already say what it is — `title`, `description`, `icon`, `date`
+ * — and one thing about where it goes. It could say nothing about the shell:
+ * the table of contents, the prev/next pair, the feedback row and the
+ * provenance block all rendered unconditionally, and the only escape was
+ * `layout: landing`, which drops the whole docs shell and leaves the author
+ * rebuilding it by hand. An API reference that wants the full width and a legal
+ * page that wants no "was this helpful?" both ended up there.
+ *
+ * So: a small, flat set of frontmatter fields, each of which turns off one
+ * thing the shell draws. Three rules hold the surface down, and all three were
+ * decided rather than discovered:
+ *
+ * - **Flat fields, not one nested object.** `toc: false` is what an author
+ *   writes in every comparable generator, and gathering them under a single
+ *   key buys a namespace nothing else needs.
+ * - **A page cannot hide the left navigation.** `layout: landing` stays the
+ *   one no-shell escape; `fullWidth` keeps the header and the sidebar, because
+ *   a page that removed the sidebar is a page the reader cannot leave.
+ * - **The controls compose and never imply one another.** `fullWidth` removes
+ *   the reading measure and nothing else; `copyPage` is independent of
+ *   `pageInfo`. A field that silently means three things cannot be combined
+ *   with the two it swallowed.
+ *
+ * Every name here is public API the moment it ships — Content drops an
+ * undeclared field silently, so `pageSchema` in `sources.ts` is the gate, and
+ * `docs/4.reference/3.frontmatter.md` is where an author reads them. Renaming
+ * one is a breaking change.
+ */
+
+/** The deepest heading the contents column draws when nobody says otherwise. */
+export const DUXT_TOC_MAX_DEPTH = 3;
+
+/**
+ * The range a page may ask for, as HTML heading levels rather than as a count.
+ *
+ * `h1` is never in the list — the title is the page's one `h1` — and there is
+ * no `h7`. Stated as levels because that is what an author counts in their own
+ * document; Content's own `toc.depth` is a count from `h2` and is set once, in
+ * the layer's `nuxt.config.ts`, deep enough that every level below is available
+ * to be filtered back down to here.
+ */
+const TOC_DEPTHS = [2, 3, 4, 5, 6];
+
+/** One heading in the contents column, in the shape `DuxtToc` draws. */
+export interface DuxtTocLink {
+  id: string;
+  text: string;
+  depth: number;
+  children?: DuxtTocLink[];
+}
+
+/** The `toc` field's object form: the column, drawn this deep. */
+export interface DuxtTocControl {
+  /** The deepest heading level listed. `2`–`6`; the list always starts at h2. */
+  maxDepth?: number;
+}
+
+/** The frontmatter an author writes. Every field is optional, by definition. */
+export interface DuxtPageControlFields {
+  /** `false` drops the contents column; an object sets how deep it goes. */
+  toc?: boolean | DuxtTocControl;
+  /** `false` hides the trail above the title. Overrides `duxt.breadcrumb`. */
+  breadcrumb?: boolean;
+  /** `false` hides the previous/next pair under the article. */
+  prevNext?: boolean;
+  /** `false` hides the "was this helpful?" row. */
+  feedback?: boolean;
+  /** `false` hides the edit link, the last-updated line and the contributors. */
+  pageInfo?: boolean;
+  /** `false` hides the copy-page and hand-to-a-model control. */
+  copyPage?: boolean;
+  /** `true` removes the reading-width cap. Nothing else. */
+  fullWidth?: boolean;
+  /** `false` removes the page from every duxt-owned discovery surface. */
+  search?: boolean;
+}
+
+/** The same questions, answered — one object the page component reads. */
+export interface DuxtPageControls {
+  toc: boolean;
+  /** The deepest heading level the column lists. Meaningful only when `toc`. */
+  tocMaxDepth: number;
+  breadcrumb: boolean;
+  prevNext: boolean;
+  feedback: boolean;
+  pageInfo: boolean;
+  copyPage: boolean;
+  fullWidth: boolean;
+  search: boolean;
+}
+
+/** What the SITE decided, for the two controls that have a site-wide switch. */
+export interface DuxtPageControlDefaults {
+  /** `duxt.breadcrumb` — the switch that existed before the per-page one. */
+  breadcrumb?: boolean;
+  /** `duxt.toc.depth` — the site's own maximum heading level. */
+  tocMaxDepth?: number;
+}
+
+/**
+ * A control is only ever turned off by a real `false`.
+ *
+ * Frontmatter is YAML a human typed, and Content stores what the schema
+ * declared without asserting the value is the type it declared — so `toc: "no"`
+ * arrives as the string. Anything that is not a boolean is not an answer, and
+ * an unanswered control keeps whatever the site said.
+ */
+const flag = (value: unknown, fallback: boolean): boolean =>
+  typeof value === 'boolean' ? value : fallback;
+
+/** A level inside the decided range, or nothing — a typo is not a depth. */
+const depth = (value: unknown): number | undefined =>
+  typeof value === 'number' && TOC_DEPTHS.includes(value) ? value : undefined;
+
+/**
+ * The eight answers, from the page's frontmatter over the site's config.
+ *
+ * The page wins wherever it speaks. That is what lets a site which hid the
+ * breadcrumb everywhere put it back on the one page whose trail is the point —
+ * a page that could only ever turn things OFF would have no way to say it.
+ */
+export function duxtPageControls(
+  page: unknown,
+  site: DuxtPageControlDefaults = {}
+): DuxtPageControls {
+  const fields = (page ?? {}) as DuxtPageControlFields;
+  const toc = fields.toc;
+  // The object form is the DEPTH, never the switch: `toc: { maxDepth: 4 }` is a
+  // page asking for more of the column, not a page turning it on.
+  const object = toc && typeof toc === 'object' ? toc : undefined;
+
+  return {
+    toc: flag(toc, true),
+    tocMaxDepth:
+      depth(object?.maxDepth) ?? depth(site.tocMaxDepth) ?? DUXT_TOC_MAX_DEPTH,
+    breadcrumb: flag(fields.breadcrumb, site.breadcrumb !== false),
+    prevNext: flag(fields.prevNext, true),
+    feedback: flag(fields.feedback, true),
+    pageInfo: flag(fields.pageInfo, true),
+    copyPage: flag(fields.copyPage, true),
+    // The one control that is OFF until asked for: every other field removes
+    // something the shell draws, this one removes a constraint.
+    fullWidth: flag(fields.fullWidth, false),
+    search: flag(fields.search, true)
+  };
+}
+
+/**
+ * Is this page offered to a reader who is looking for it rather than at it?
+ *
+ * ONE predicate, four surfaces: the client search index, its fuzzy fallback,
+ * the MCP `search_docs` tool and the two llms indexes each have to answer this,
+ * and a rule written four times is a rule three of them eventually disagree
+ * with. It is deliberately NOT a rule about the URL — an excluded page is still
+ * served, still canonical, still in the sitemap and still readable by
+ * `read_page`. It is un-findable, not unpublished.
+ *
+ * IT CAN ONLY EVER BE AS GOOD AS THE COLUMN BEHIND IT. A page arrives here from
+ * the database, and Content casts a boolean column with `Boolean(value)` on the
+ * way out — so a nullable column hands this predicate `false` for a page that
+ * never mentioned `search`, and no comparison written here can tell that apart
+ * from a refusal (#88). The `search` field in `pageSchema` therefore carries a
+ * default, and that is what makes this line mean what it reads as.
+ */
+export const duxtPageSearchable = (page: unknown): boolean =>
+  (page as DuxtPageControlFields | undefined | null)?.search !== false;
+
+/**
+ * Content's outline, cut to the depth this page asked for.
+ *
+ * Content nests headings by RELATIVE depth and as deep as the document goes,
+ * while `DuxtToc` draws exactly two levels. So this does what `generatedToc`
+ * already does for a generated page: read the tree back out in document order,
+ * drop what is deeper than the maximum, and collapse everything that is left
+ * below the first level into it. The written page and the generated one then
+ * cannot draw the same outline two different ways.
+ *
+ * Dropping a heading drops its children with it — they are deeper by
+ * construction, so keeping them would reparent a sub-section under a heading
+ * the reader was not shown.
+ */
+export function duxtTocLinks(
+  links: DuxtTocLink[] | undefined,
+  maxDepth: number = DUXT_TOC_MAX_DEPTH
+): DuxtTocLink[] {
+  const limit = depth(maxDepth) ?? DUXT_TOC_MAX_DEPTH;
+  const flat: DuxtTocLink[] = [];
+
+  const walk = (nodes: DuxtTocLink[]) => {
+    for (const node of nodes) {
+      if (node.depth > limit) continue;
+
+      const { children, ...link } = node;
+      flat.push(link);
+      if (children?.length) walk(children);
+    }
+  };
+
+  walk(links ?? []);
+
+  const nested: DuxtTocLink[] = [];
+
+  for (const link of flat) {
+    const parent = nested.at(-1);
+
+    // A page whose first heading is an `h3` still needs a row to hang under.
+    if (link.depth > 2 && parent) (parent.children ??= []).push(link);
+    else nested.push({ ...link, depth: 2 });
+  }
+
+  return nested;
+}

package/app/utils/pill.ts

@@ -0,0 +1,61 @@
+/**
+ * The pill: the one look every "pick one of these" strip on the site shares.
+ *
+ * Code tabs, the request samples' language tabs, the package managers, the
+ * sample clients, the media types, the form/JSON switch and the demo window's
+ * pages are all the same control — choose one spelling of one thing — and they
+ * read as one only if they are drawn alike. Each of them used to carry its own
+ * class string, and no two of the seven agreed on padding, weight or hover.
+ *
+ * Two tones, because the strips sit on two kinds of surface. `raised` lifts
+ * the chosen pill off a muted bar the way a tab does; on the page's own
+ * background that shadow is invisible, so `flat` marks it with the muted fill
+ * instead.
+ *
+ * `active: 'tab'` for a reka-ui trigger, which knows its own state and says so
+ * in `data-state` — the classes key off that rather than off a prop the
+ * component would have to be handed twice.
+ *
+ * Full literal class strings throughout: Tailwind finds classes by reading the
+ * source, and a string assembled from pieces is a class it never generates.
+ */
+const BASE =
+  'inline-flex shrink-0 cursor-pointer items-center gap-1.5 whitespace-nowrap rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring';
+
+const SIZES = {
+  sm: 'px-2 py-0.5 text-xs',
+  md: 'px-2.5 py-1 text-xs',
+  lg: 'px-3 py-1.5 text-sm'
+} as const;
+
+const STATES = {
+  raised: {
+    on: 'bg-background text-foreground shadow-sm',
+    off: 'text-muted-foreground hover:bg-accent hover:text-foreground',
+    tab: 'data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm data-[state=inactive]:text-muted-foreground data-[state=inactive]:hover:bg-accent data-[state=inactive]:hover:text-foreground'
+  },
+  flat: {
+    on: 'bg-muted text-foreground',
+    off: 'text-muted-foreground hover:text-foreground',
+    tab: 'data-[state=active]:bg-muted data-[state=active]:text-foreground data-[state=inactive]:text-muted-foreground data-[state=inactive]:hover:text-foreground'
+  }
+} as const;
+
+export type DuxtPillSize = keyof typeof SIZES;
+export type DuxtPillTone = keyof typeof STATES;
+
+export function duxtPill(
+  active: boolean | 'tab',
+  {
+    size = 'md',
+    tone = 'raised'
+  }: { size?: DuxtPillSize; tone?: DuxtPillTone } = {}
+): string {
+  const state = STATES[tone];
+
+  return [
+    BASE,
+    SIZES[size],
+    active === 'tab' ? state.tab : active ? state.on : state.off
+  ].join(' ');
+}

package/app/utils/prose-image.ts

@@ -0,0 +1,128 @@
+/**
+ * How wide a documentation image really is, and which files must not be touched.
+ *
+ * THE LAYER OWNS THE COLUMN, NOT THE PROVIDER. `@nuxt/image` already decides
+ * where an image is transformed — ipx on a Node server, nothing at all on a
+ * Worker, a CDN wherever a consumer has configured one — and it already ships a
+ * Tailwind-shaped `screens` map. None of that belongs here: a layer that pins a
+ * provider is a layer every consumer has to undo, and a layer that restates the
+ * breakpoints makes a consumer's own `image.screens` silently ineffective.
+ *
+ * What the layer does know, and `@nuxt/image` cannot, is the width of the box
+ * the theme draws an image into. That is the whole contribution below: two
+ * `sizes` policies, written in the module's own syntax, naming only the screens
+ * it already ships so a consumer that redefines them keeps the redefinition.
+ *
+ * A `sizes` string is what turns a bare `src` into a `srcset`. Without one
+ * `NuxtImg` emits a single file, so a 2400px screenshot is downloaded whole
+ * onto a phone to be drawn into a 48rem column.
+ */
+
+/**
+ * The prose column, in CSS pixels — `max-w-3xl` on the article in every layout
+ * that renders Markdown.
+ *
+ * Stated as a number rather than only inside the policy string because it is
+ * the fact the policy is derived FROM, and the thing that has to change first
+ * if the column ever does.
+ */
+export const PROSE_COLUMN_PX = 768;
+
+/**
+ * The in-page image.
+ *
+ * Below `md` the column is the viewport less the layout's own `px-4` gutters,
+ * and `95vw` is that minus a rounding margin — over-fetching a few pixels,
+ * never under. From `md` up the article is capped at `max-w-3xl` whatever the
+ * screen, so the slot stops growing and the policy says so with a fixed pixel
+ * width instead of a fraction that would keep climbing on a 4K display.
+ *
+ * Two entries, not five: `@nuxt/image` gives the widest entry no media query
+ * and hands every other one the query of the entry above it, so `lg`, `xl` and
+ * `2xl` would each restate `768px` and buy nothing.
+ */
+export const PROSE_IMAGE_SIZES = 'sm:95vw md:768px';
+
+/**
+ * The same image in the zoom dialog, which is a different request on purpose.
+ *
+ * "Full size" used to mean whatever the author happened to upload, because
+ * there was only ever one file. The dialog is `min(96vw, 80rem)` with an 8px
+ * inset, so this policy tracks the viewport up to that cap and then stops —
+ * four rungs rather than two because a dialog spans the width of the screen and
+ * a phone opening one must not be handed a desktop file.
+ *
+ * A page's own `sizes` deliberately does not reach here: it describes where the
+ * image sits in the prose, and the dialog is not in the prose.
+ */
+export const PROSE_IMAGE_ZOOM_SIZES = 'sm:96vw md:96vw lg:96vw xl:1264px';
+
+/**
+ * The policy for one image: the page's own, or the layer's.
+ *
+ * MDC hands every attribute over as a string, so `sizes=""` on a page that
+ * meant to say nothing arrives as an empty string rather than as undefined —
+ * and an empty `sizes` is not "no override", it is a policy with no entries,
+ * which produces no `srcset` at all.
+ */
+export function proseImageSizes(sizes?: string): string {
+  const own = sizes?.trim();
+
+  return own ? own : PROSE_IMAGE_SIZES;
+}
+
+/**
+ * Formats an image provider must be kept away from.
+ *
+ * An SVG has no pixels to resample — asking for a 608px wide one rasterises a
+ * file that was sharp at every size — and a GIF run through a raster pipeline
+ * comes back as its first frame, the animation silently gone. Both are served
+ * as the author committed them, in the page and in the dialog alike.
+ *
+ * Stated by this component rather than assumed of the provider: some pass these
+ * through, some do not, and a documentation layer cannot know which one a
+ * consumer configured.
+ *
+ * The extension is read off the PATH. A query string is where a CDN puts its
+ * own parameters and a fragment is not part of the file at all, so neither may
+ * decide the format — and `/svg/shot.png` is a PNG in a directory, not a
+ * vector.
+ */
+export function proseImagePassThrough(src?: string): boolean {
+  if (!src) return false;
+
+  const path = src.split(/[?#]/)[0] ?? '';
+
+  return /\.(?:svg|gif)$/i.test(path);
+}
+
+/**
+ * The images whose DIALOG variants a static build has to write ahead of time.
+ *
+ * A generated site learns which variants to produce from the URLs a render
+ * emitted — `NuxtImg` appends each one to an `x-nitro-prerender` header and
+ * Nitro's crawler prerenders what that header names. The dialog is not rendered
+ * until someone opens it, so on a generated site its variants were requested by
+ * nobody, written by nobody, and the first click found a 404.
+ *
+ * `ProseImg` therefore asks the provider for the dialog's sizes during
+ * prerender, which registers the URLs without putting them in any markup. This
+ * is the list it asks for, and it is a function rather than a loop in the
+ * component because WHICH images belong on it is the part worth stating:
+ *
+ * - An image that cannot be zoomed has no dialog to open. Registering it writes
+ *   a full set of dialog-sized files nobody can ever request — output inflation
+ *   for a feature that is switched off on that image.
+ * - A pass-through format is served exactly as committed, so there is no
+ *   variant to write and asking for one would rasterise a vector.
+ */
+export function proseImageZoomPrerenderSources(
+  zoomable: boolean,
+  srcs: (string | undefined)[]
+): string[] {
+  if (!zoomable) return [];
+
+  return srcs.filter(
+    (src): src is string => Boolean(src) && !proseImagePassThrough(src)
+  );
+}

package/app/utils/search-context.ts

@@ -0,0 +1,110 @@
+/**
+ * What a Command-K row says about itself beyond its title.
+ *
+ * A title is an identity on a site with one source, one version and one
+ * language. It is not one here: three `Harbour` entries under "Recently viewed"
+ * were three different pages, and the palette gave the reader no way to tell
+ * which was which. The same holds for a search hit — two versions of a page
+ * carry the same heading, and the ranking that put them side by side is exactly
+ * what makes them impossible to tell apart.
+ *
+ * So every row carries one compact line: `section · source/version · route`,
+ * with the parts a site does not have left out. Built from what the page,
+ * section and version models already know — there is no second index here, and
+ * nothing about ranking changes.
+ */
+import { asText } from './duxt-text';
+import { currentSection, sectionsForPath } from './section-scope';
+import { sourceForPath } from './version-paths';
+
+/** Between the parts. A middle dot, not a slash: the route holds slashes. */
+const SEPARATOR = ' · ';
+
+/** The minimum a section entry has to carry to be named. */
+interface Labelled {
+  label?: DuxtText;
+  to?: string;
+}
+
+/** The minimum a source has to carry to place a route and name its edition. */
+interface Edition {
+  prefix: string;
+  repo?: string;
+  version?: string;
+  /** Present on a generated section, which places itself — see `sectionsForPath`. */
+  generated?: unknown;
+  /** Looks the source's display name up in `names` below, where there is one. */
+  collection?: string;
+}
+
+/** How much of the line a caller wants, and what it wants the source called. */
+export interface SearchContextOptions {
+  /**
+   * Display names by collection — see `sourceDisplayNames`.
+   *
+   * With one, the source slot says what a source is CALLED rather than which
+   * URL segment it occupies: the root documentation has no segment and so said
+   * nothing at all, and a source whose segment is an abbreviation said the
+   * abbreviation. Without one the slot keeps its `repo/version` spelling.
+   */
+  names?: ReadonlyMap<string, string>;
+  /**
+   * `false` where something above the row already states where it came from —
+   * the caption at the head of a run of results, in the search list.
+   *
+   * The line then carries only what is the ROW's own, its section and its
+   * route, which are the parts that still differ from its neighbours. Saying
+   * the source again under a caption that just said it is the repetition this
+   * line exists to remove.
+   */
+  source?: boolean;
+}
+
+/**
+ * The section a route belongs to.
+ *
+ * `currentSection`, not a `startsWith` of its own: the longest match wins and
+ * the comparison is segment-aware, so `/harbour/api` is the API rather than the
+ * documentation it hangs under, and `/guides-old` is not inside `/guides`.
+ */
+export function sectionLabelForPath(
+  path: string,
+  sections: readonly Labelled[],
+  sources: readonly Edition[] = []
+): string | undefined {
+  // AT THE ROUTE'S EDITION. The sections are written at the default one, so a
+  // hit on `/v0.2.0/concepts/sources` matched nothing and fell back to the
+  // generic label — see `sectionsForPath`, which the row and the sidebar read
+  // for the same reason.
+  return asText(
+    currentSection(sectionsForPath([...sections], [...sources], path), path)
+      ?.label
+  );
+}
+
+/** `section · source/version · route`, minus whatever the site has not got. */
+export function searchContext(
+  path: string,
+  sections: readonly Labelled[],
+  sources: readonly Edition[],
+  options: SearchContextOptions = {}
+): string {
+  const route = path.split('#')[0] ?? '';
+  const source =
+    options.source === false ? undefined : sourceForPath(route, [...sources]);
+  const named = source?.collection
+    ? options.names?.get(source.collection)
+    : undefined;
+
+  return [
+    sectionLabelForPath(route, sections, sources),
+    // A NAME is prose and takes a part of its own; a segment is an address and
+    // keeps the `repo/version` spelling, which reads as the path it is.
+    ...(named
+      ? [named, source?.version]
+      : [[source?.repo, source?.version].filter(Boolean).join('/')]),
+    route
+  ]
+    .filter((part) => part && part.trim())
+    .join(SEPARATOR);
+}