@dogsbay/site-files 0.2.0-beta.119 → 0.2.0-beta.121

package/dist/index.d.ts

@@ -12,3 +12,4 @@ export * from "./redirects.js";
 export * from "./canonical.js";
 export * from "./hreflang.js";
 export * from "./translations.js";
+export * from "./namespaces.js";

package/dist/index.js

@@ -12,3 +12,4 @@ export * from "./redirects.js";
 export * from "./canonical.js";
 export * from "./hreflang.js";
 export * from "./translations.js";
+export * from "./namespaces.js";

package/dist/namespaces.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Named sources: one site built from several content sources, where a source
+ * with `name: api` publishes under `/api/` and shows as its own group in the
+ * sidebar. The Astro pipeline (dogsbay CLI, import-content.ts) and dogsbay-ssg
+ * apply the same rule from here, so the two agree on every URL and nav link.
+ *
+ *   sources: [{ path: ./content }, { name: api, path: ./openapi.yaml }]
+ *     ./content pages      → /<slug>              (unnamed: flat, as before)
+ *     ./openapi.yaml pages → /api/<slug>, nav group "Api"
+ *
+ * Naming one source never moves another's URLs: an unnamed source stays flat
+ * beside named siblings. A single source, named or not, gets no segment.
+ */
+/** A content source, as far as the namespace rule reads it. */
+export interface NamespacedSource {
+    name?: string;
+}
+/** A nav entry, as far as prefixing reads it (`@dogsbay/types` NavItem fits). */
+export interface PrefixableNavItem {
+    href?: string;
+    children?: PrefixableNavItem[];
+}
+/** A source's namespace: its `name:`, or undefined (flat URLs). */
+export declare function sourceNamespace(source: NamespacedSource): string | undefined;
+/**
+ * Whether namespaces are in play: two or more distinct namespaces across the
+ * sources, an unnamed source counting as one. So `[unnamed, api]` activates
+ * it (the unnamed one stays flat, `api` gets `/api/`), and `[api]` alone does
+ * not.
+ */
+export declare function isNamespaceAxisActive(sources: readonly NamespacedSource[]): boolean;
+/**
+ * The URL segment a source's pages go under: `[name]` when namespaces are
+ * active and the source has a name, otherwise none. (The Astro pipeline adds
+ * locale and version segments after it: `/<name>/<locale>/<version>/<slug>`.)
+ */
+export declare function namespaceSegments(source: NamespacedSource, sources: readonly NamespacedSource[]): string[];
+/** The sidebar label for a namespace: `api` → "Api", `user-guide` → "User Guide". */
+export declare function namespaceLabel(ns: string): string;
+/** A page slug under prefix segments: (`["api"]`, `pets/list`) → `api/pets/list`; `""` → `api`. */
+export declare function prefixSlug(prefix: readonly string[], slug: string): string;
+/**
+ * Nav hrefs with the prefix segments put after the base path:
+ * `/docs/pets/` → `/docs/api/pets/` for basePath `/docs`. External URLs, and
+ * hrefs not under the base path, are left alone: nothing is rewritten that
+ * the rule does not recognise. Returns new items; the input is not changed.
+ *
+ * @param basePath `""` or `/<seg>` (the site's combined URL prefix), the
+ *   prefix the importer already wrote into each href.
+ */
+export declare function prefixNavHrefs<T extends PrefixableNavItem>(items: readonly T[], prefix: readonly string[], basePath: string): T[];
+/**
+ * A named source's nav as it joins the site's sidebar: one group labelled
+ * with the namespace, holding the source's own nav. An unnamed source's nav
+ * joins flat (`undefined` here means "splice the items in as they are").
+ */
+export declare function namespaceNavGroup<T extends PrefixableNavItem>(ns: string | undefined, nav: T[]): {
+    label: string;
+    children: T[];
+} | undefined;
+/**
+ * Prefix INTERNAL-ABSOLUTE refs in a page tree with the source's URL
+ * segments, matching the slug rewrite — so a versioned/localised page's
+ * links and images resolve under the same `/<segs>/...` prefix as the
+ * pages themselves. Covers page links (`href`) and asset refs (`src`),
+ * in both markdown nodes (`src`/`href` fields) and raw-HTML nodes
+ * (`href="..."`/`src="..."` inside an `html` string).
+ *
+ * Refs at this pipeline stage are ROOT-RELATIVE and carry NO basePath
+ * (importers resolve to `/foo`; basePath is composed downstream), so the
+ * match anchor is `/`, not `<basePath>/`. A ref is prefixed iff it is an
+ * internal absolute path (starts with `/`), and NOT: external
+ * (`scheme:`, `//host`), an anchor (`#`), the site home (`/`), under a
+ * GLOBAL prefix (taxonomy index paths — one `/tags/` for the whole site,
+ * never version-bucketed), or ALREADY carrying this source's full
+ * `/<segs>/` prefix (idempotent). Relative refs are left untouched.
+ *
+ * The idempotency check is a guess: a source under `/api/` whose own folder
+ * is also `api` writes `/api/x`, which reads as already prefixed. An importer
+ * that invents folder names (format-openapi's tags) avoids those segments
+ * (`reservedSlugs`). Changes `tree` in place.
+ *
+ * Used for a named source (`["api"]`) and, in the Astro pipeline, versioned
+ * and localized ones too (`["api", "fr", "v2"]`).
+ */
+export declare function rewriteContentRefs(tree: unknown, prefixSegs: readonly string[], globalPrefixes: ReadonlySet<string>): void;

package/dist/namespaces.js

@@ -0,0 +1,175 @@
+/**
+ * Named sources: one site built from several content sources, where a source
+ * with `name: api` publishes under `/api/` and shows as its own group in the
+ * sidebar. The Astro pipeline (dogsbay CLI, import-content.ts) and dogsbay-ssg
+ * apply the same rule from here, so the two agree on every URL and nav link.
+ *
+ *   sources: [{ path: ./content }, { name: api, path: ./openapi.yaml }]
+ *     ./content pages      → /<slug>              (unnamed: flat, as before)
+ *     ./openapi.yaml pages → /api/<slug>, nav group "Api"
+ *
+ * Naming one source never moves another's URLs: an unnamed source stays flat
+ * beside named siblings. A single source, named or not, gets no segment.
+ */
+/** A source's namespace: its `name:`, or undefined (flat URLs). */
+export function sourceNamespace(source) {
+    return source.name;
+}
+/**
+ * Whether namespaces are in play: two or more distinct namespaces across the
+ * sources, an unnamed source counting as one. So `[unnamed, api]` activates
+ * it (the unnamed one stays flat, `api` gets `/api/`), and `[api]` alone does
+ * not.
+ */
+export function isNamespaceAxisActive(sources) {
+    if (sources.length < 2)
+        return false;
+    return new Set(sources.map(sourceNamespace)).size >= 2;
+}
+/**
+ * The URL segment a source's pages go under: `[name]` when namespaces are
+ * active and the source has a name, otherwise none. (The Astro pipeline adds
+ * locale and version segments after it: `/<name>/<locale>/<version>/<slug>`.)
+ */
+export function namespaceSegments(source, sources) {
+    const ns = isNamespaceAxisActive(sources) ? sourceNamespace(source) : undefined;
+    return ns === undefined ? [] : [ns];
+}
+/** The sidebar label for a namespace: `api` → "Api", `user-guide` → "User Guide". */
+export function namespaceLabel(ns) {
+    return ns
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+/** A page slug under prefix segments: (`["api"]`, `pets/list`) → `api/pets/list`; `""` → `api`. */
+export function prefixSlug(prefix, slug) {
+    if (prefix.length === 0)
+        return slug;
+    if (!slug)
+        return prefix.join("/");
+    return `${prefix.join("/")}/${slug}`;
+}
+/**
+ * Nav hrefs with the prefix segments put after the base path:
+ * `/docs/pets/` → `/docs/api/pets/` for basePath `/docs`. External URLs, and
+ * hrefs not under the base path, are left alone: nothing is rewritten that
+ * the rule does not recognise. Returns new items; the input is not changed.
+ *
+ * @param basePath `""` or `/<seg>` (the site's combined URL prefix), the
+ *   prefix the importer already wrote into each href.
+ */
+export function prefixNavHrefs(items, prefix, basePath) {
+    if (prefix.length === 0)
+        return items.map((item) => ({ ...item }));
+    const match = basePath ? `${basePath}/` : "/";
+    const href = (h) => {
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(h) || h.startsWith("mailto:"))
+            return h;
+        if (!h.startsWith(match))
+            return h;
+        return `${match}${prefix.join("/")}/${h.slice(match.length)}`;
+    };
+    return items.map((item) => {
+        const next = { ...item };
+        if (item.href !== undefined)
+            next.href = href(item.href);
+        if (item.children && item.children.length > 0) {
+            next.children = prefixNavHrefs(item.children, prefix, basePath);
+        }
+        return next;
+    });
+}
+/**
+ * A named source's nav as it joins the site's sidebar: one group labelled
+ * with the namespace, holding the source's own nav. An unnamed source's nav
+ * joins flat (`undefined` here means "splice the items in as they are").
+ */
+export function namespaceNavGroup(ns, nav) {
+    return ns === undefined ? undefined : { label: namespaceLabel(ns), children: nav };
+}
+/**
+ * Prefix INTERNAL-ABSOLUTE refs in a page tree with the source's URL
+ * segments, matching the slug rewrite — so a versioned/localised page's
+ * links and images resolve under the same `/<segs>/...` prefix as the
+ * pages themselves. Covers page links (`href`) and asset refs (`src`),
+ * in both markdown nodes (`src`/`href` fields) and raw-HTML nodes
+ * (`href="..."`/`src="..."` inside an `html` string).
+ *
+ * Refs at this pipeline stage are ROOT-RELATIVE and carry NO basePath
+ * (importers resolve to `/foo`; basePath is composed downstream), so the
+ * match anchor is `/`, not `<basePath>/`. A ref is prefixed iff it is an
+ * internal absolute path (starts with `/`), and NOT: external
+ * (`scheme:`, `//host`), an anchor (`#`), the site home (`/`), under a
+ * GLOBAL prefix (taxonomy index paths — one `/tags/` for the whole site,
+ * never version-bucketed), or ALREADY carrying this source's full
+ * `/<segs>/` prefix (idempotent). Relative refs are left untouched.
+ *
+ * The idempotency check is a guess: a source under `/api/` whose own folder
+ * is also `api` writes `/api/x`, which reads as already prefixed. An importer
+ * that invents folder names (format-openapi's tags) avoids those segments
+ * (`reservedSlugs`). Changes `tree` in place.
+ *
+ * Used for a named source (`["api"]`) and, in the Astro pipeline, versioned
+ * and localized ones too (`["api", "fr", "v2"]`).
+ */
+export function rewriteContentRefs(tree, prefixSegs, globalPrefixes) {
+    if (prefixSegs.length === 0)
+        return;
+    const seg = prefixSegs.join("/");
+    const fullPrefix = `/${seg}/`;
+    const prefix = (u) => {
+        if (!u)
+            return u;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(u))
+            return u; // scheme (http:, mailto:)
+        if (u.startsWith("//") || u.startsWith("#"))
+            return u; // protocol-rel / anchor
+        if (!u.startsWith("/"))
+            return u; // relative
+        if (u === "/" || u === "")
+            return u; // site home — global
+        if (u.startsWith(fullPrefix) || u === `/${seg}`)
+            return u; // already prefixed
+        // Global (taxonomy) prefixes live in one un-bucketed namespace.
+        const firstSeg = u.slice(1).split(/[/#?]/)[0];
+        if (globalPrefixes.has(firstSeg))
+            return u;
+        return `/${seg}${u}`;
+    };
+    // Raw HTML: rewrite the VALUE of each href="..."/src="..." attribute.
+    const rewriteHtml = (html) => html.replace(/\b(href|src)=("|')(.*?)\2/gi, (_m, attr, q, val) => `${attr}=${q}${prefix(val)}${q}`);
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (!node || typeof node !== "object")
+            return;
+        const obj = node;
+        if (typeof obj.src === "string")
+            obj.src = prefix(obj.src);
+        if (typeof obj.href === "string")
+            obj.href = prefix(obj.href);
+        if (typeof obj.html === "string")
+            obj.html = rewriteHtml(obj.html);
+        // `::child-links{folder=…}` is a site path too: on a versioned or
+        // localized site it names a folder in THIS source's namespace.
+        if (obj.type === "child-links" && obj.props && typeof obj.props.folder === "string") {
+            const props = obj.props;
+            props.folder = prefix(`/${String(props.folder).replace(/^\/+/, "")}`);
+        }
+        // `scope=section` has no folder to prefix: record the source namespace,
+        // or the section resolves to the version segment (`/v2/`).
+        if (obj.type === "child-links" && obj.props && obj.props.scope === "section") {
+            obj.props.scopeBase = `/${seg}`;
+        }
+        for (const key of Object.keys(obj)) {
+            const val = obj[key];
+            if (val && typeof val === "object")
+                walk(val);
+        }
+    };
+    walk(tree);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/site-files",
-  "version": "0.2.0-beta.119",
+  "version": "0.2.0-beta.121",
   "description": "robots.txt, _headers, llms.txt, sitemaps, redirects and JSON-LD for docs sites; shared by the dogsbay Astro pipeline and dogsbay-ssg, Worker-safe",
   "type": "module",
   "main": "./dist/index.js",