@takazudo/zudo-doc 0.2.21 → 0.2.22

package/dist/url-helpers/index.js

@@ -0,0 +1,106 @@
+function makeUrlHelpers(settings, i18n) {
+  const { defaultLocale, locales, getLocaleLabel } = i18n;
+  const normalizedBase = settings.base.replace(/\/+$/, "");
+  function applyTrailingSlash(url) {
+    if (!settings.trailingSlash) return url;
+    if (url.endsWith("/")) return url;
+    const suffixIdx = url.search(/[?#]/);
+    const pathPart = suffixIdx >= 0 ? url.slice(0, suffixIdx) : url;
+    const suffix = suffixIdx >= 0 ? url.slice(suffixIdx) : "";
+    if (pathPart.endsWith("/")) return url;
+    const lastSegment = pathPart.split("/").pop() ?? "";
+    if (/\.[a-zA-Z]\w*$/.test(lastSegment)) return url;
+    return pathPart + "/" + suffix;
+  }
+  function withBase(path) {
+    const raw = normalizedBase === "" ? path : `${normalizedBase}${path.startsWith("/") ? path : `/${path}`}`;
+    return applyTrailingSlash(raw);
+  }
+  function stripBase(path) {
+    if (normalizedBase === "") return path;
+    if (path === normalizedBase) return "/";
+    return path.startsWith(`${normalizedBase}/`) ? path.slice(normalizedBase.length) : path;
+  }
+  function absoluteUrl(pageUrl) {
+    return settings.siteUrl ? settings.siteUrl.replace(/\/$/, "") + pageUrl : void 0;
+  }
+  function docsUrl(slug, lang = defaultLocale) {
+    const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
+    return withBase(path);
+  }
+  function isExternal(href) {
+    return href.startsWith("http://") || href.startsWith("https://");
+  }
+  function resolveHref(href) {
+    return isExternal(href) ? href : withBase(href);
+  }
+  function navHref(path, lang, currentVersion) {
+    const isNonDefaultLocale = lang != null && lang !== defaultLocale;
+    const versionPrefix = currentVersion ? `/v/${currentVersion}` : "";
+    return withBase(
+      isNonDefaultLocale ? `${versionPrefix}/${lang}${path}` : `${versionPrefix}${path}`
+    );
+  }
+  function splitVersionPrefix(path) {
+    const m = path.match(/^(\/v\/[^/]+)(\/.*|$)/);
+    return m ? { versionPrefix: m[1] ?? "", rest: m[2] ?? "/" } : { versionPrefix: "", rest: path };
+  }
+  function getPathForLocale(path, currentLang, targetLang) {
+    const { versionPrefix, rest } = splitVersionPrefix(stripBase(path));
+    let relativePath = rest;
+    if (currentLang !== defaultLocale) {
+      relativePath = relativePath.replace(new RegExp(`^/${currentLang}(?:/|$)`), "/");
+    }
+    if (targetLang !== defaultLocale) {
+      relativePath = `/${targetLang}${relativePath}`;
+    }
+    return withBase(`${versionPrefix}${relativePath}`);
+  }
+  function isDefaultLocaleOnlyPath(path) {
+    const stripped = stripBase(path);
+    const normalized = stripped.endsWith("/") ? stripped : `${stripped}/`;
+    return settings.defaultLocaleOnlyPrefixes.some((prefix) => normalized.startsWith(prefix));
+  }
+  function buildLocaleLinks(currentPath, currentLang) {
+    let defaultLocalePath = splitVersionPrefix(stripBase(currentPath)).rest;
+    if (currentLang !== defaultLocale) {
+      defaultLocalePath = defaultLocalePath.replace(new RegExp(`^/${currentLang}(?:/|$)`), "/");
+    }
+    if (isDefaultLocaleOnlyPath(defaultLocalePath)) {
+      return [{
+        code: currentLang,
+        label: getLocaleLabel(currentLang),
+        href: getPathForLocale(currentPath, currentLang, currentLang),
+        active: true
+      }];
+    }
+    return locales.map((code) => ({
+      code,
+      label: getLocaleLabel(code),
+      href: getPathForLocale(currentPath, currentLang, code),
+      active: code === currentLang
+    }));
+  }
+  function versionedDocsUrl(slug, versionSlug, lang = defaultLocale) {
+    const path = lang === defaultLocale ? `/v/${versionSlug}/docs/${slug}` : `/v/${versionSlug}/${lang}/docs/${slug}`;
+    return withBase(path);
+  }
+  return {
+    normalizedBase,
+    applyTrailingSlash,
+    withBase,
+    stripBase,
+    absoluteUrl,
+    docsUrl,
+    isExternal,
+    resolveHref,
+    navHref,
+    getPathForLocale,
+    buildLocaleLinks,
+    isDefaultLocaleOnlyPath,
+    versionedDocsUrl
+  };
+}
+export {
+  makeUrlHelpers
+};

package/dist/url-normalizer/index.d.ts

@@ -1 +1,39 @@
-export { buildUrl, normalizePathname, shouldSkipNormalization } from './normalize.js';
+/**
+ * Public entry for `@takazudo/zudo-doc/url-normalizer`.
+ *
+ * Build-time URL normalizer that ensures every emitted route URL ends with
+ * a trailing slash, matching the `trailingSlash: "always"` policy of the
+ * legacy Astro build.
+ *
+ * ## Why build-time only?
+ *
+ * zfb is a purely static site builder — there is no server or dev middleware.
+ * The Astro `src/middleware-handler.ts` ran at request time; the equivalent
+ * guarantee is now split:
+ *
+ * - **Build time** (this module): `buildUrl()` constructs URLs that always
+ *   end with `/`, and `normalizePathname()` corrects any bare pathname passed
+ *   in from external data.
+ * - **Runtime**: the deployment host (e.g. Cloudflare Pages `_redirects`) is
+ *   responsible for redirecting requests that arrive without a trailing slash.
+ *
+ * See the "Trailing-Slash Policy" concept doc in the showcase docs for the
+ * full design rationale and an example `_redirects` rule.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   buildUrl,
+ *   normalizePathname,
+ *   shouldSkipNormalization,
+ * } from "@takazudo/zudo-doc/url-normalizer";
+ *
+ * // In a paths() implementation:
+ * const url = buildUrl("docs", slug);  // "/docs/my-slug/"
+ *
+ * // In an integration that receives raw pathnames:
+ * const canonical = normalizePathname(rawPathname);
+ * ```
+ */
+export { buildUrl, normalizePathname, shouldSkipNormalization } from "./normalize.js";

package/dist/url-normalizer/normalize.d.ts

@@ -58,7 +58,7 @@
  * buildUrl()                                     // "/"
  * buildUrl("", "docs", "")                       // "/docs/"
  */
-declare function buildUrl(...segments: string[]): string;
+export declare function buildUrl(...segments: string[]): string;
 /**
  * Return `true` when `pathname` should NOT receive a trailing slash.
  *
@@ -78,7 +78,7 @@ declare function buildUrl(...segments: string[]): string;
  * shouldSkipNormalization("/docs/guide")           // false (needs trailing slash)
  * shouldSkipNormalization("/docs/v2.0")            // false (number after dot → not an extension)
  */
-declare function shouldSkipNormalization(pathname: string): boolean;
+export declare function shouldSkipNormalization(pathname: string): boolean;
 /**
  * Return `pathname` with a trailing slash appended if needed.
  *
@@ -99,6 +99,4 @@ declare function shouldSkipNormalization(pathname: string): boolean;
  * normalizePathname("/docs/guide/")  // "/docs/guide/"  (no-op)
  * normalizePathname("/assets/app.js") // "/assets/app.js"  (skipped)
  */
-declare function normalizePathname(pathname: string): string;
-
-export { buildUrl, normalizePathname, shouldSkipNormalization };
+export declare function normalizePathname(pathname: string): string;

package/dist/use-modal-dialog/index.d.ts

@@ -0,0 +1,70 @@
+interface UseModalDialogOptions {
+    /** True when the dialog should be open. */
+    isOpen: boolean;
+    /** Called when the dialog is closed for any reason (Escape, backdrop, navigation). */
+    onClose: () => void;
+    /**
+     * DOM event name that triggers a close-and-reset. Pass the host's SPA
+     * after-navigate event name (e.g. `AFTER_NAVIGATE_EVENT`); pass `undefined`
+     * to skip navigation-close wiring entirely.
+     */
+    navigateEvent?: string;
+    /**
+     * When `true`, enable backdrop-click-to-close. The caller must forward the
+     * click handler returned by this hook to the `<dialog>` element's `onClick`.
+     * Defaults to `false` so opt-in only.
+     */
+    backdropClickClose?: boolean;
+    /**
+     * When `true`, enable focus management:
+     *  - On open: capture `document.activeElement` as the return target (unless
+     *    `returnFocusRef` is provided), then move focus to the first focusable
+     *    element inside the dialog (or the dialog itself as a fallback).
+     *  - On close: restore focus to the captured element.
+     *
+     * When a caller already manages focus internally (e.g. ai-chat-modal focuses
+     * its input in its own effect), pass `restoreFocusOnly: true` instead to get
+     * trigger-capture + restore without the "move into dialog" step.
+     */
+    manageFocus?: boolean;
+    /**
+     * Like `manageFocus` but skips the "focus first element in dialog" step —
+     * use when the caller has its own focus-on-open logic and only needs
+     * trigger-capture + focus restore on close.
+     */
+    restoreFocusOnly?: boolean;
+    /**
+     * Optional ref holding the element to return focus to on close. When
+     * provided and non-null, this takes precedence over the internally captured
+     * `document.activeElement`. Useful when the trigger element is conditionally
+     * rendered and therefore removed from the DOM before the open effect fires
+     * (e.g. the doc-history trigger button, which is unmounted when `isOpen`
+     * is true). The caller should set `returnFocusRef.current` to the trigger
+     * element in its click handler, before calling `setState`.
+     */
+    returnFocusRef?: React.RefObject<HTMLElement | null>;
+}
+interface UseModalDialogResult {
+    dialogRef: React.RefObject<HTMLDialogElement>;
+    /**
+     * Pass this to `<dialog onClick={handleBackdropClick}>`.
+     * Only wired when `backdropClickClose` is true; otherwise a no-op.
+     */
+    handleBackdropClick: (e: React.MouseEvent<HTMLDialogElement>) => void;
+}
+/**
+ * Shared hook for `<dialog>`-based modal components.
+ *
+ * Usage:
+ * ```tsx
+ * const { dialogRef, handleBackdropClick } = useModalDialog({
+ *   isOpen,
+ *   onClose: handleClose,
+ *   navigateEvent: AFTER_NAVIGATE_EVENT,
+ *   backdropClickClose: true,
+ * });
+ * return <dialog ref={dialogRef} onClick={handleBackdropClick} ... />;
+ * ```
+ */
+export declare function useModalDialog({ isOpen, onClose, navigateEvent, backdropClickClose, manageFocus, restoreFocusOnly, returnFocusRef, }: UseModalDialogOptions): UseModalDialogResult;
+export {};

package/dist/use-modal-dialog/index.js

@@ -0,0 +1,73 @@
+"use client";
+import { useEffect, useRef } from "preact/compat";
+function useModalDialog({
+  isOpen,
+  onClose,
+  navigateEvent,
+  backdropClickClose = false,
+  manageFocus = false,
+  restoreFocusOnly = false,
+  returnFocusRef
+}) {
+  const dialogRef = useRef(null);
+  const internalTriggerRef = useRef(null);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (isOpen && !dialog.open) {
+      if ((manageFocus || restoreFocusOnly) && !returnFocusRef) {
+        internalTriggerRef.current = document.activeElement;
+      }
+      dialog.showModal();
+      if (manageFocus && !restoreFocusOnly) {
+        const FOCUSABLE = 'button:not([disabled]),a[href],[tabindex]:not([tabindex="-1"]),input:not([disabled]),select:not([disabled]),textarea:not([disabled])';
+        const first = dialog.querySelector(FOCUSABLE);
+        if (first) {
+          first.focus();
+        } else {
+          dialog.focus();
+        }
+      }
+    } else if (!isOpen && dialog.open) {
+      dialog.close();
+    }
+  }, [isOpen, manageFocus, restoreFocusOnly, returnFocusRef]);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    function onDialogClose() {
+      if (manageFocus || restoreFocusOnly) {
+        const trigger = returnFocusRef ? returnFocusRef.current : internalTriggerRef.current;
+        if (trigger instanceof HTMLElement) {
+          trigger.focus();
+        }
+        internalTriggerRef.current = null;
+      }
+      if (isOpen) onClose();
+    }
+    dialog.addEventListener("close", onDialogClose);
+    return () => dialog.removeEventListener("close", onDialogClose);
+  }, [isOpen, onClose, manageFocus, restoreFocusOnly, returnFocusRef]);
+  useEffect(() => {
+    if (!navigateEvent) return;
+    function handleNavigation() {
+      const dialog = dialogRef.current;
+      if (dialog?.open) {
+        dialog.close();
+        onClose();
+      }
+    }
+    document.addEventListener(navigateEvent, handleNavigation);
+    return () => document.removeEventListener(navigateEvent, handleNavigation);
+  }, [navigateEvent, onClose]);
+  function handleBackdropClick(e) {
+    if (!backdropClickClose) return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (e.target === dialog) dialog.close();
+  }
+  return { dialogRef, handleBackdropClick };
+}
+export {
+  useModalDialog
+};

package/dist/versions-page/index.d.ts

@@ -0,0 +1,55 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren, JSX } from "preact";
+/** Minimal version config entry needed by the versions page. */
+export interface VersionsPageVersionEntry {
+    slug: string;
+    label?: string;
+    banner?: "unmaintained" | "unreleased" | false;
+}
+/** Settings subset read by the versions page factory. */
+export interface VersionsPageSettings {
+    noindex?: boolean;
+    dynamicPageTransition?: boolean;
+    versions: VersionsPageVersionEntry[] | false;
+    base: string;
+}
+/** Host-supplied component bindings injected into the versions page factory. */
+export interface VersionsPageComponents {
+    HeadWithDefaults: (props: {
+        title: string;
+    }) => JSX.Element;
+    HeaderWithDefaults: (props: {
+        lang?: string;
+        currentPath?: string;
+    }) => JSX.Element;
+    FooterWithDefaults: (props: {
+        lang?: string;
+    }) => JSX.Element;
+    BodyEndIslands: (props: {
+        basePath: string;
+    }) => JSX.Element;
+}
+/** Injected dependencies for {@link createVersionsPageView}. */
+export interface VersionsPageDeps {
+    settings: VersionsPageSettings;
+    /** Default locale code (e.g. `"en"`). */
+    defaultLocale: string;
+    /** Translate a UI string key for a locale. */
+    t: (key: string, locale: string) => string;
+    /** Prefix a path with the configured base directory. */
+    withBase: (path: string) => string;
+    /** Compose the meta `<title>` value. */
+    composeMetaTitle: (title: string) => string;
+    components: VersionsPageComponents;
+}
+/** Props for the VersionsPageView component. */
+export interface VersionsPageViewProps {
+    locale: string;
+    children?: ComponentChildren;
+}
+/**
+ * Create a `VersionsPageView` component bound to the host's settings and
+ * component dependencies.
+ */
+export declare function createVersionsPageView(deps: VersionsPageDeps): (props: VersionsPageViewProps) => JSX.Element;

package/dist/versions-page/index.js

@@ -0,0 +1,73 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
+import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { VersionsPageContent } from "../nav-indexing/index.js";
+function createVersionsPageView(deps) {
+  const {
+    settings,
+    defaultLocale,
+    t,
+    withBase,
+    composeMetaTitle,
+    components: {
+      HeadWithDefaults,
+      HeaderWithDefaults,
+      FooterWithDefaults,
+      BodyEndIslands
+    }
+  } = deps;
+  function VersionsPageView({ locale }) {
+    const isDefault = locale === defaultLocale;
+    const prefix = isDefault ? "" : `/${locale}`;
+    const pageTitle = t("version.page.title", locale);
+    const labels = {
+      pageTitle,
+      latestTitle: t("version.page.latest.title", locale),
+      latestDescription: t("version.page.latest.description", locale),
+      latestLink: t("version.page.latest.link", locale),
+      pastTitle: t("version.page.past.title", locale),
+      pastDescription: t("version.page.past.description", locale),
+      unmaintained: t("version.page.unmaintained", locale),
+      unreleased: t("version.page.unreleased", locale),
+      versionCol: t("version.switcher.label", locale),
+      statusCol: t("version.page.status", locale),
+      docsCol: t("version.page.docs", locale)
+    };
+    const latestHref = withBase(`${prefix}/docs/getting-started`);
+    const versions = settings.versions ? settings.versions.map((v) => ({
+      slug: v.slug,
+      label: v.label ?? v.slug,
+      // Version prefix comes BEFORE the locale — the only routed shape is
+      // pages/v/[version]/{locale}/docs/...; /{locale}/v/... has no route.
+      docsHref: withBase(`/v/${v.slug}${prefix}/docs/getting-started/`),
+      banner: v.banner
+    })) : [];
+    return /* @__PURE__ */ jsx(
+      DocLayoutWithDefaults,
+      {
+        title: composeMetaTitle(pageTitle),
+        head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
+        lang: locale,
+        noindex: settings.noindex,
+        hideSidebar: true,
+        hideToc: true,
+        sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+        headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`${prefix}/docs/versions`) }),
+        footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+        bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
+        enableClientRouter: settings.dynamicPageTransition,
+        children: /* @__PURE__ */ jsx(
+          VersionsPageContent,
+          {
+            latestHref,
+            versions,
+            labels
+          }
+        )
+      }
+    );
+  }
+  return VersionsPageView;
+}
+export {
+  createVersionsPageView
+};