create-zudo-doc 0.1.0

package/templates/features/imageEnlarge/files/src/components/image-enlarge.tsx

@@ -0,0 +1,248 @@
+import { useState, useEffect, useRef } from "preact/compat";
+import type { JSX } from "preact";
+
+interface ImageData {
+  src: string;
+  currentSrc: string;
+  srcset?: string;
+  sizes?: string;
+  alt: string;
+  naturalWidth: number;
+  naturalHeight: number;
+}
+
+// Shared shell for the enlarge `<dialog>`. The hydrated component and the
+// SSR fallback (below) render into the same Island container, so they MUST
+// agree on class string and inline style — otherwise the dist HTML and the
+// post-hydration DOM disagree on size / position and the first interaction
+// flashes. Sourcing both from the same constants closes the drift gap.
+const DIALOG_CLASS =
+  "zd-enlarge-dialog mx-auto max-h-[90vh] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0";
+const DIALOG_STYLE = {
+  position: "fixed",
+  top: "50%",
+  left: "50%",
+  transform: "translate(-50%, -50%)",
+} as const;
+
+export default function ImageEnlarge() {
+  const [imgData, setImgData] = useState<ImageData | null>(null);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  // Eligibility detection: toggle .zd-enlarge-btn[hidden] per image
+  useEffect(() => {
+    const resizeObservers = new Map<HTMLImageElement, ResizeObserver>();
+    let mutationObserver: MutationObserver | null = null;
+    let resizeTimer = 0;
+
+    function evaluateEligibility(img: HTMLImageElement) {
+      const container = img.closest(".zd-enlargeable");
+      if (!container) return;
+      const btn = container.querySelector(".zd-enlarge-btn") as HTMLElement | null;
+      if (!btn) return;
+      const eligible = img.naturalWidth > img.clientWidth * window.devicePixelRatio;
+      if (eligible) {
+        btn.removeAttribute("hidden");
+      } else {
+        btn.setAttribute("hidden", "");
+      }
+    }
+
+    function observeImage(img: HTMLImageElement) {
+      if (resizeObservers.has(img)) return;
+      const ro = new ResizeObserver(() => evaluateEligibility(img));
+      ro.observe(img);
+      resizeObservers.set(img, ro);
+      if (img.complete) {
+        evaluateEligibility(img);
+      } else {
+        img.addEventListener("load", () => evaluateEligibility(img), { once: true });
+      }
+    }
+
+    function scanContent() {
+      const scope = document.querySelector("main .zd-content");
+      if (!scope) return;
+      scope.querySelectorAll<HTMLImageElement>(".zd-enlargeable img").forEach(observeImage);
+    }
+
+    function startObserving() {
+      const scope = document.querySelector("main .zd-content");
+      if (scope) {
+        mutationObserver = new MutationObserver((mutations) => {
+          for (const mutation of mutations) {
+            for (const node of mutation.addedNodes) {
+              if (!(node instanceof Element)) continue;
+              if (node.matches(".zd-enlargeable")) {
+                node.querySelectorAll<HTMLImageElement>("img").forEach(observeImage);
+              }
+              node.querySelectorAll<HTMLImageElement>(".zd-enlargeable img").forEach(observeImage);
+            }
+          }
+        });
+        mutationObserver.observe(scope, { childList: true, subtree: true });
+      }
+      scanContent();
+    }
+
+    function handleWindowResize() {
+      clearTimeout(resizeTimer);
+      resizeTimer = window.setTimeout(() => {
+        resizeObservers.forEach((_, img) => evaluateEligibility(img));
+      }, 150);
+    }
+
+    function handleAfterSwap() {
+      resizeObservers.forEach((ro) => ro.disconnect());
+      resizeObservers.clear();
+      mutationObserver?.disconnect();
+      mutationObserver = null;
+      startObserving();
+    }
+
+    startObserving();
+    window.addEventListener("resize", handleWindowResize);
+    document.addEventListener("DOMContentLoaded", handleAfterSwap);
+
+    return () => {
+      resizeObservers.forEach((ro) => ro.disconnect());
+      resizeObservers.clear();
+      mutationObserver?.disconnect();
+      window.removeEventListener("resize", handleWindowResize);
+      document.removeEventListener("DOMContentLoaded", handleAfterSwap);
+      clearTimeout(resizeTimer);
+    };
+  }, []);
+
+  useEffect(() => {
+    function handleDocumentClick(e: MouseEvent) {
+      const target = e.target as Element;
+      const container = target.closest(".zd-enlargeable");
+      if (!container) return;
+      const btn = container.querySelector(".zd-enlarge-btn") as HTMLElement | null;
+      // Eligibility gate: only open when the expand button is visible (image is large enough).
+      if (!btn || btn.hasAttribute("hidden")) return;
+      const img = container.querySelector("img") as HTMLImageElement | null;
+      if (!img) return;
+      setImgData({
+        src: img.src,
+        currentSrc: img.currentSrc,
+        srcset: img.srcset || undefined,
+        sizes: img.sizes || undefined,
+        alt: img.alt,
+        naturalWidth: img.naturalWidth,
+        naturalHeight: img.naturalHeight,
+      });
+    }
+    document.addEventListener("click", handleDocumentClick);
+    return () => document.removeEventListener("click", handleDocumentClick);
+  }, []);
+
+  // Open dialog when imgData is set
+  useEffect(() => {
+    if (!imgData) return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    dialog.showModal();
+  }, [imgData]);
+
+  // Handle cancel event (ESC key)
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    function handleCancel() {
+      setImgData(null);
+    }
+    dialog.addEventListener("cancel", handleCancel);
+    return () => dialog.removeEventListener("cancel", handleCancel);
+  }, []);
+
+  // Reset state when dialog closes
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    function handleClose() {
+      setImgData(null);
+    }
+    dialog.addEventListener("close", handleClose);
+    return () => dialog.removeEventListener("close", handleClose);
+  }, []);
+
+  // Close and reset on ClientRouter navigation
+  useEffect(() => {
+    function handleAfterSwap() {
+      const dialog = dialogRef.current;
+      if (dialog?.open) dialog.close();
+      setImgData(null);
+    }
+    document.addEventListener("DOMContentLoaded", handleAfterSwap);
+    return () => document.removeEventListener("DOMContentLoaded", handleAfterSwap);
+  }, []);
+
+  function handleBackdropClick(e: JSX.TargetedMouseEvent<HTMLDialogElement>) {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    const rect = dialog.getBoundingClientRect();
+    if (
+      e.clientX < rect.left ||
+      e.clientX > rect.right ||
+      e.clientY < rect.top ||
+      e.clientY > rect.bottom
+    ) {
+      dialog.close();
+    }
+  }
+
+  return (
+    <dialog
+      ref={dialogRef}
+      onClick={handleBackdropClick}
+      className={DIALOG_CLASS}
+      style={DIALOG_STYLE}
+    >
+      {imgData && (
+        <>
+          <div className="relative">
+            <img
+              src={imgData.currentSrc || imgData.src}
+              srcSet={imgData.srcset}
+              sizes={imgData.srcset ? "100vw" : undefined}
+              alt={imgData.alt}
+              className="block max-h-[85vh] max-w-[85vw] object-contain"
+            />
+          </div>
+          <button
+            type="button"
+            onClick={() => dialogRef.current?.close()}
+            className="zd-enlarge-dialog-close"
+            aria-label="Close enlarged image"
+          >
+            <svg viewBox="0 0 161.03 161.03" fill="currentColor" aria-hidden="true" focusable="false">
+              <polygon points="161.03 10.27 150.76 0 80.51 70.24 10.27 0 0 10.27 70.24 80.51 0 150.76 10.27 161.03 80.51 90.78 150.76 161.03 161.03 150.76 90.78 80.51 161.03 10.27" />
+            </svg>
+          </button>
+        </>
+      )}
+    </dialog>
+  );
+}
+
+/**
+ * Static SSR fallback for the {@link ImageEnlarge} island.
+ *
+ * Renders an empty, closed `<dialog class="zd-enlarge-dialog ...">` so the
+ * dist HTML carries the dialog shell even before hydration. A `<dialog>`
+ * without `open` is `display:none` per UA stylesheet, so screen readers
+ * and crawlers see the same shape they would post-hydration. Sources its
+ * class and inline style from the shared `DIALOG_CLASS` / `DIALOG_STYLE`
+ * constants above so the SSR shell cannot drift from the hydrated
+ * dialog (a drift would surface as a cosmetic flash on first interaction).
+ */
+export function ImageEnlargeSsrFallback() {
+  return (
+    <dialog
+      className={DIALOG_CLASS}
+      style={DIALOG_STYLE}
+    />
+  );
+}

package/templates/features/llmsTxt/files/plugins/llms-txt-plugin.mjs

@@ -0,0 +1,74 @@
+// zfb plugin module: llms-txt.
+//
+// Wires two lifecycle hooks for the llms-txt integration:
+//
+//   postBuild — invokes `emitLlmsTxt` to write `dist/llms.txt`,
+//               `dist/llms-full.txt`, and the per-locale variants.
+//               `siteUrl` is normalised to `undefined` when falsy because
+//               the runner switches between absolute and root-relative URLs
+//               based on its presence (matches legacy Astro behaviour).
+//
+//   devMiddleware — serves `/llms.txt`, `/llms-full.txt`, and the per-locale
+//               `/<code>/llms.txt` / `/<code>/llms-full.txt` variants from
+//               the on-the-fly `generateLlmsTxt` generator so dev output
+//               stays in lockstep with the production `emitLlmsTxt`
+//               byte-for-byte.
+//
+// `options` carries `{ siteName, siteDescription, base, siteUrl,
+// defaultLocaleDir, locales }` from the matching entry in `zfb.config.ts`.
+//
+// Inline functions are not supported by zfb's plugin runtime; see the
+// sibling `doc-history-plugin.mjs` for the rationale.
+
+import { emitLlmsTxt, createLlmsTxtDevMiddleware } from "@takazudo/zudo-doc/integrations/llms-txt";
+import { connectToZfbHandler } from "./connect-adapter.mjs";
+
+export default {
+  name: "llms-txt",
+
+  postBuild(ctx) {
+    const {
+      siteName,
+      siteDescription,
+      base,
+      siteUrl,
+      defaultLocaleDir,
+      locales,
+    } = ctx.options;
+    emitLlmsTxt({
+      outDir: ctx.outDir,
+      siteName,
+      siteDescription,
+      base,
+      siteUrl: siteUrl || undefined,
+      defaultLocaleDir,
+      locales,
+      logger: ctx.logger,
+    });
+  },
+
+  devMiddleware(ctx) {
+    const middleware = createLlmsTxtDevMiddleware(ctx.options, ctx.logger);
+    const handler = connectToZfbHandler(middleware);
+
+    // zfb's `register(path, handler)` matches against the FULL request
+    // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
+    // requests arrive as `/my-docs/llms.txt` (etc.), so we register
+    // every route with the base prefix. For base="/", the prefix is
+    // empty and routes are `/llms.txt` etc. as expected. The middleware
+    // accepts base-prefixed URLs via the matcher (see `matchLlmsRoute`
+    // in `dev-middleware.ts`).
+    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    ctx.register(`${basePrefix}/llms.txt`, handler);
+    ctx.register(`${basePrefix}/llms-full.txt`, handler);
+    for (const locale of ctx.options.locales ?? []) {
+      ctx.register(`${basePrefix}/${locale.code}/llms.txt`, handler);
+      ctx.register(`${basePrefix}/${locale.code}/llms-full.txt`, handler);
+    }
+  },
+};
+
+function stripTrailingSlash(s) {
+  if (typeof s !== "string" || s.length === 0) return "";
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}

package/templates/features/sidebarResizer/files/src/scripts/sidebar-resizer.ts

@@ -0,0 +1,185 @@
+export function initSidebarResizer() {
+  const sidebar = document.getElementById("desktop-sidebar");
+  if (!sidebar || sidebar.querySelector("[data-sidebar-resizer]")) return;
+
+  // Resizer allows a wider range (192–448px) than the CSS default
+  // (clamp(14rem, 20vw, 22rem) = 224–352px at 16px base).
+  // CSS provides the responsive initial width; the resizer lets users
+  // go beyond that range when explicitly dragging or using keyboard arrows.
+  const MIN_W = 192;
+  const MAX_W = 448;
+  const STEP = 10;
+  const LS_KEY = "zudo-doc-sidebar-width";
+  const CSS_PROP = "--zd-sidebar-w";
+  const ACCENT_BG = "var(--zd-accent, rgba(128,128,128,0.3))";
+  const ACCENT_OUTLINE = "2px solid var(--zd-accent, rgba(128,128,128,0.5))";
+  const ACCENT_GHOST = "var(--zd-accent, rgba(128,128,128,0.5))";
+
+  function readCurrentWidth(): number {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue(CSS_PROP);
+    return raw ? parseFloat(raw) || MIN_W : MIN_W;
+  }
+
+  let cachedWidth = readCurrentWidth();
+
+  const handle = document.createElement("div");
+  handle.setAttribute("data-sidebar-resizer", "");
+  handle.setAttribute("tabindex", "0");
+  handle.setAttribute("role", "separator");
+  handle.setAttribute("aria-orientation", "vertical");
+  handle.setAttribute("aria-label", "Resize sidebar");
+  handle.setAttribute("aria-valuemin", String(MIN_W));
+  handle.setAttribute("aria-valuemax", String(MAX_W));
+  handle.setAttribute("aria-valuenow", String(Math.round(cachedWidth)));
+  // 20px is wider than every common native y-scrollbar (~12-17px on
+  // Win/Linux classic; 0 on macOS overlay) so a draggable strip always remains
+  // visible to the LEFT of the scrollbar when sidebar content overflows.
+  // zudolab/zudo-doc#1660
+  Object.assign(handle.style, {
+    position: "absolute",
+    top: "0",
+    right: "0",
+    width: "20px",
+    height: "100%",
+    cursor: "col-resize",
+    zIndex: "10",
+    transition: "background 0.15s",
+  });
+
+  let dragging = false;
+
+  function applyWidth(w: number) {
+    cachedWidth = Math.max(MIN_W, Math.min(MAX_W, w));
+    document.documentElement.style.setProperty(CSS_PROP, cachedWidth + "px");
+    try { localStorage.setItem(LS_KEY, String(Math.round(cachedWidth))); } catch {}
+    handle.setAttribute("aria-valuenow", String(Math.round(cachedWidth)));
+  }
+
+  let focused = false;
+
+  function updateHandleVisual() {
+    if (dragging || focused) {
+      handle.style.background = ACCENT_BG;
+    } else {
+      handle.style.background = "";
+    }
+    handle.style.outline = focused && !dragging ? ACCENT_OUTLINE : "";
+    handle.style.outlineOffset = focused && !dragging ? "1px" : "";
+  }
+
+  handle.addEventListener("focus", () => {
+    focused = true;
+    updateHandleVisual();
+  });
+  handle.addEventListener("blur", () => {
+    focused = false;
+    updateHandleVisual();
+  });
+
+  handle.addEventListener("keydown", (e: KeyboardEvent) => {
+    let w = cachedWidth;
+    switch (e.key) {
+      case "ArrowLeft":
+        w = Math.max(MIN_W, w - STEP);
+        break;
+      case "ArrowRight":
+        w = Math.min(MAX_W, w + STEP);
+        break;
+      case "Home":
+        w = MIN_W;
+        break;
+      case "End":
+        w = MAX_W;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    applyWidth(w);
+  });
+
+  handle.addEventListener("mouseenter", () => {
+    if (!dragging && !focused) handle.style.background = ACCENT_BG;
+  });
+  handle.addEventListener("mouseleave", () => {
+    if (!dragging && !focused) handle.style.background = "";
+  });
+
+  handle.addEventListener("pointerdown", (e: PointerEvent) => {
+    e.preventDefault();
+    handle.setPointerCapture(e.pointerId);
+    dragging = true;
+    updateHandleVisual();
+    document.documentElement.style.cursor = "col-resize";
+    document.documentElement.style.userSelect = "none";
+
+    // Ghost line — cheap to move (no reflow), shows target position
+    const ghost = document.createElement("div");
+    Object.assign(ghost.style, {
+      position: "fixed",
+      top: "0",
+      width: "2px",
+      height: "100vh",
+      background: ACCENT_GHOST,
+      pointerEvents: "none",
+      zIndex: "9999",
+    });
+    const sidebarRect = sidebar.getBoundingClientRect();
+    const sidebarLeft = sidebarRect.left;
+    ghost.style.left = (sidebarLeft + sidebarRect.width) + "px";
+    document.body.appendChild(ghost);
+    let targetWidth = 0;
+    let cleaned = false;
+
+    const onMove = (ev: PointerEvent) => {
+      targetWidth = Math.max(MIN_W, Math.min(MAX_W, ev.clientX - sidebarLeft));
+      ghost.style.left = (sidebarLeft + targetWidth) + "px";
+    };
+
+    const cleanup = () => {
+      if (cleaned) return;
+      cleaned = true;
+      dragging = false;
+      updateHandleVisual();
+      document.documentElement.style.cursor = "";
+      document.documentElement.style.userSelect = "";
+      ghost.remove();
+      handle.removeEventListener("pointermove", onMove);
+      handle.removeEventListener("pointerup", onUp);
+      handle.removeEventListener("pointercancel", onCancel);
+      handle.removeEventListener("lostpointercapture", onLost);
+    };
+
+    const commit = () => {
+      if (targetWidth > 0) applyWidth(targetWidth);
+    };
+
+    // pointerup: normal end-of-drag. Commit, then teardown.
+    const onUp = () => {
+      commit();
+      cleanup();
+    };
+
+    // lostpointercapture: per spec fires AFTER pointerup, but browsers reorder
+    // these in edge cases (cursor near y-scrollbar, fast drags, OS handoff).
+    // Commit here too so a real drag still applies if pointerup is dropped.
+    // Idempotent with onUp via the `cleaned` guard.
+    const onLost = () => {
+      commit();
+      cleanup();
+    };
+
+    // pointercancel: actual user/OS cancellation (touch interrupted, etc.).
+    // Do NOT commit — caller intent was to abort.
+    const onCancel = () => {
+      cleanup();
+    };
+
+    handle.addEventListener("pointermove", onMove);
+    handle.addEventListener("pointerup", onUp);
+    handle.addEventListener("pointercancel", onCancel);
+    handle.addEventListener("lostpointercapture", onLost);
+  });
+
+  sidebar.appendChild(handle);
+}

package/templates/features/sidebarToggle/files/src/components/desktop-sidebar-toggle.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { useState, useEffect, useRef } from 'preact/hooks';
+import { BEFORE_NAVIGATE_EVENT, AFTER_NAVIGATE_EVENT } from '@takazudo/zudo-doc/transitions';
+
+export const SIDEBAR_STORAGE_KEY = 'zudo-doc-sidebar-visible';
+
+function readState(): boolean {
+  if (typeof window === 'undefined') return true;
+  try {
+    return localStorage.getItem(SIDEBAR_STORAGE_KEY) !== 'false';
+  } catch {
+    return true;
+  }
+}
+
+function setDataAttribute(isVisible: boolean) {
+  if (isVisible) {
+    document.documentElement.removeAttribute('data-sidebar-hidden');
+  } else {
+    document.documentElement.setAttribute('data-sidebar-hidden', '');
+  }
+}
+
+export default function DesktopSidebarToggle() {
+  // Initial state must match server render (always `true`) to avoid a
+  // hydration mismatch when the persisted preference is "hidden". The
+  // doc-layout's pre-paint inline script applies `data-sidebar-hidden`
+  // to <html> from localStorage *before* this island mounts, so the
+  // visual state stays correct; we only need to sync this island's
+  // React state to the persisted preference after hydration. Same
+  // pattern as src/components/theme-toggle.tsx (commit 9aebd8e).
+  const [visible, setVisible] = useState<boolean>(true);
+  // Tracks whether the hydration sync (below) has run. The persistence
+  // effect below skips the very first mount so we don't overwrite the
+  // user's persisted "hidden" preference with the SSR-safe default
+  // `true` before the hydration sync gets a chance to fire.
+  const hydrated = useRef(false);
+
+  // Persist state changes to localStorage and the <html> data-attribute.
+  // The `hydrated.current` guard is the real protection: it is still
+  // `false` on the very first effect run (the hydration-sync effect
+  // below sets it to `true` only after this one fires, since effects
+  // run in declaration order on mount), so the first run bails out
+  // and we don't clobber the user's persisted "hidden" preference
+  // with the SSR-safe default `true`.
+  useEffect(() => {
+    if (!hydrated.current) return;
+    setDataAttribute(visible);
+    try {
+      localStorage.setItem(SIDEBAR_STORAGE_KEY, String(visible));
+    } catch {
+      // ignore storage errors
+    }
+  }, [visible]);
+
+  // After mount, read the persisted preference and reconcile state
+  // with the SSR default. Sets the ref so subsequent runs of the
+  // persistence effect above start syncing normally.
+  useEffect(() => {
+    hydrated.current = true;
+    const actual = readState();
+    if (actual !== visible) {
+      setVisible(actual);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Re-apply data-sidebar-hidden to <html> after every SPA nav.
+  // zfb's swapRootAttributes wipes all non-preserved <html> attributes on
+  // each navigation (data-sidebar-hidden is not in NON_OVERRIDABLE_ZFB_ATTRS),
+  // and the pre-paint inline script does not re-run on SPA nav. Since this
+  // island is persisted (data-zfb-transition-persist), this listener stays
+  // registered across SPA swaps.
+  //
+  // Strategy: capture the attribute presence just before the swap
+  // (BEFORE_NAVIGATE_EVENT fires before swapRootAttributes runs), then
+  // restore it once the swap completes (AFTER_NAVIGATE_EVENT). This is
+  // authoritative regardless of how the attribute was set (toggle click,
+  // localStorage, or external mutation). (#1551, #1552 B10)
+  useEffect(() => {
+    let wasHidden = false;
+    const capture = () => {
+      wasHidden = document.documentElement.hasAttribute('data-sidebar-hidden');
+    };
+    const restore = () => {
+      if (wasHidden) {
+        document.documentElement.setAttribute('data-sidebar-hidden', '');
+      }
+      // If not hidden, swapRootAttributes already cleared it — nothing to do.
+    };
+    document.addEventListener(BEFORE_NAVIGATE_EVENT, capture);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, restore);
+    return () => {
+      document.removeEventListener(BEFORE_NAVIGATE_EVENT, capture);
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, restore);
+    };
+  }, []);
+
+  return (
+    <button
+      type="button"
+      onClick={() => setVisible((v) => !v)}
+      className="zd-desktop-sidebar-toggle hidden lg:flex fixed bottom-vsp-xl z-40 items-center justify-center w-[1.5rem] h-[3rem] bg-surface border border-muted border-l-0 rounded-r-DEFAULT text-muted cursor-pointer transition-[left,color] duration-200 ease-in-out hover:text-fg"
+      aria-label={visible ? 'Hide sidebar' : 'Show sidebar'}
+      aria-pressed={visible}
+      data-zfb-transition-persist="desktop-sidebar-toggle"
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        className="h-icon-sm w-icon-sm"
+        aria-hidden="true"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke="currentColor"
+        strokeWidth={2}
+      >
+        <path
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          d={visible ? 'M15 19l-7-7 7-7' : 'M9 5l7 7-7 7'}
+        />
+      </svg>
+    </button>
+  );
+}