create-eziwiki 0.1.0

package/template/components/layout/TabInitializer.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+import { useTabStore } from '@/lib/store/tabStore';
+import { NavigationItem } from '@/lib/payload/types';
+import { useUrlMap } from '@/components/providers/UrlMapProvider';
+
+interface TabInitializerProps {
+  navigation: NavigationItem[];
+}
+
+/**
+ * Helper function to find navigation item by path
+ */
+export function findNavigationItemByPath(
+  items: NavigationItem[],
+  path: string,
+): NavigationItem | null {
+  const normalizedPath = path.replace(/\/$/, '');
+
+  for (const item of items) {
+    if (!item.path) {
+      if (item.children) {
+        const found = findNavigationItemByPath(item.children, path);
+        if (found) return found;
+      }
+      continue;
+    }
+
+    const normalizedItemPath = item.path.replace(/\/$/, '');
+    if (normalizedItemPath === normalizedPath) {
+      return item;
+    }
+
+    if (item.children) {
+      const found = findNavigationItemByPath(item.children, path);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * Initializes tabs on first load and handles URL changes
+ */
+export function TabInitializer({ navigation }: TabInitializerProps) {
+  const pathname = usePathname();
+  const { toPath } = useUrlMap();
+  const { tabs, addTab, activeTabId, updateTabPath, navigateInHistory, hasHydrated } =
+    useTabStore();
+  const isInitialMount = useRef(true);
+  const previousPathname = useRef(pathname);
+
+  useEffect(() => {
+    if (!hasHydrated) return;
+
+    const currentPath = pathname === '/' ? '' : (toPath(pathname) ?? '');
+
+    // Initial mount - set up first tab
+    if (isInitialMount.current) {
+      if (tabs.length === 0) {
+        // No saved tabs - create initial tab based on URL
+        const navItem = findNavigationItemByPath(navigation, currentPath);
+        const title = navItem?.name || 'New Tab';
+        addTab({ title, path: currentPath });
+      } else if (activeTabId) {
+        // Tabs exist - update active tab to match URL
+        const navItem = findNavigationItemByPath(navigation, currentPath);
+        const title = navItem?.name || 'New Tab';
+        updateTabPath(activeTabId, currentPath, title);
+      }
+
+      isInitialMount.current = false;
+      previousPathname.current = pathname;
+      return;
+    }
+
+    // URL changed - add to history
+    if (pathname !== previousPathname.current && activeTabId) {
+      const navItem = findNavigationItemByPath(navigation, currentPath);
+      const title = navItem?.name || 'New Tab';
+      navigateInHistory(activeTabId, currentPath, title);
+      previousPathname.current = pathname;
+    }
+  }, [
+    hasHydrated,
+    tabs.length,
+    pathname,
+    navigation,
+    toPath,
+    addTab,
+    activeTabId,
+    updateTabPath,
+    navigateInHistory,
+  ]);
+
+  return null;
+}

package/template/components/layout/TableOfContents.tsx

@@ -0,0 +1,138 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { Heading } from '@/lib/markdown/rehype-plugins';
+
+/**
+ * On-page table of contents with scroll tracking.
+ *
+ * Headings are collected during the build, so the list is server-rendered and
+ * present in the HTML; the only client-side work is highlighting whichever
+ * section the reader is currently looking at.
+ */
+
+interface TableOfContentsProps {
+  /** Headings for the current document, in order */
+  headings: Heading[];
+}
+
+/**
+ * Top offset used when deciding which heading is "current".
+ *
+ * Matches the sticky header, so a heading counts as active once it reaches the
+ * point where it becomes visible rather than when it touches the viewport edge.
+ */
+const SCROLL_OFFSET = 96;
+
+/**
+ * Tracks which heading the reader is currently under.
+ *
+ * Chosen by position rather than by intersection ratio: a long section whose
+ * heading has scrolled off should stay active, which observer-visibility alone
+ * does not express.
+ *
+ * @param headings - Headings to track
+ * @returns The id of the active heading
+ */
+function useActiveHeading(headings: Heading[]): string | null {
+  const [active, setActive] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (headings.length === 0) return;
+
+    let frame = 0;
+
+    const update = () => {
+      frame = 0;
+
+      const positions = headings
+        .map((heading) => {
+          const element = document.getElementById(heading.id);
+          return element ? { id: heading.id, top: element.getBoundingClientRect().top } : null;
+        })
+        .filter((entry): entry is { id: string; top: number } => entry !== null);
+
+      if (positions.length === 0) return;
+
+      // The last heading at or above the offset line is the one being read.
+      const passed = positions.filter((entry) => entry.top <= SCROLL_OFFSET);
+
+      // Near the bottom of the page the final section may never reach the
+      // offset line, so pin the last heading once the page is scrolled to end.
+      const atBottom =
+        window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+
+      if (atBottom) {
+        setActive(positions[positions.length - 1].id);
+      } else {
+        setActive(passed.length > 0 ? passed[passed.length - 1].id : positions[0].id);
+      }
+    };
+
+    const onScroll = () => {
+      // Scroll fires far more often than the display refreshes; coalescing to
+      // one measurement per frame keeps layout reads off the scroll path.
+      if (frame === 0) frame = requestAnimationFrame(update);
+    };
+
+    update();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll);
+
+    return () => {
+      if (frame) cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+    };
+  }, [headings]);
+
+  return active;
+}
+
+/**
+ * Renders the table of contents rail.
+ *
+ * Returns nothing for documents with fewer than two headings — a contents list
+ * with one entry is noise.
+ *
+ * @param props.headings - Headings for the current document
+ */
+export function TableOfContents({ headings }: TableOfContentsProps) {
+  const active = useActiveHeading(headings);
+
+  if (headings.length < 2) return null;
+
+  // Normalise depth so a document starting at h3 is not indented as if nested.
+  const minDepth = Math.min(...headings.map((heading) => heading.depth));
+
+  return (
+    <nav aria-label="On this page" className="text-sm">
+      <p className="mb-3 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
+        On this page
+      </p>
+
+      <ul className="space-y-1 border-l border-gray-200 dark:border-gray-800">
+        {headings.map((heading) => {
+          const isActive = heading.id === active;
+
+          return (
+            <li key={heading.id}>
+              <a
+                href={`#${heading.id}`}
+                aria-current={isActive ? 'location' : undefined}
+                className={`-ml-px block border-l py-1 pr-2 transition-colors ${
+                  isActive
+                    ? 'border-blue-500 text-blue-600 dark:text-blue-400'
+                    : 'border-transparent text-gray-600 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100'
+                }`}
+                style={{ paddingLeft: `${(heading.depth - minDepth) * 12 + 12}px` }}
+              >
+                {heading.text}
+              </a>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

package/template/components/markdown/CodeCopy.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Wires up copy-to-clipboard for build-time rendered code blocks.
+ *
+ * The buttons themselves are emitted during the build by `rehypeCodeShell`;
+ * this component only attaches behaviour. A single delegated listener on the
+ * document handles every block on the page, which is what lets the syntax
+ * highlighting stack stay out of the client bundle entirely — previously the
+ * whole Prism highlighter shipped just to render a copy button.
+ *
+ * @example
+ * ```tsx
+ * <article dangerouslySetInnerHTML={{ __html: html }} />
+ * <CodeCopy />
+ * ```
+ */
+export function CodeCopy() {
+  useEffect(() => {
+    /** Milliseconds the confirmation label stays visible. */
+    const CONFIRM_MS = 2000;
+    const timers = new Map<HTMLElement, ReturnType<typeof setTimeout>>();
+
+    async function handleClick(event: MouseEvent) {
+      const target = event.target as HTMLElement | null;
+      const button = target?.closest<HTMLElement>('[data-ezw-copy]');
+      if (!button) return;
+
+      const code = button.closest('[data-ezw-code]')?.querySelector('pre');
+      if (!code) return;
+
+      try {
+        await navigator.clipboard.writeText(code.textContent ?? '');
+      } catch {
+        // Clipboard access is denied outside secure contexts; leave the label
+        // unchanged so the failure is visible rather than falsely confirmed.
+        return;
+      }
+
+      button.textContent = '✓ Copied';
+      button.setAttribute('data-copied', '');
+
+      clearTimeout(timers.get(button));
+      timers.set(
+        button,
+        setTimeout(() => {
+          button.textContent = 'Copy';
+          button.removeAttribute('data-copied');
+          timers.delete(button);
+        }, CONFIRM_MS),
+      );
+    }
+
+    document.addEventListener('click', handleClick);
+
+    return () => {
+      document.removeEventListener('click', handleClick);
+      timers.forEach(clearTimeout);
+    };
+  }, []);
+
+  return null;
+}

package/template/components/markdown/MarkdownContent.tsx

@@ -0,0 +1,38 @@
+import { CodeCopy } from './CodeCopy';
+
+/**
+ * Props for the MarkdownContent component
+ */
+interface MarkdownContentProps {
+  /** HTML produced at build time by the Markdown pipeline */
+  html: string;
+}
+
+/**
+ * Renders pre-compiled Markdown HTML.
+ *
+ * The markup arrives already parsed, highlighted, and link-resolved from
+ * `renderDoc()`, so this is a server component that emits static HTML. The only
+ * client-side code is the small copy-button listener.
+ *
+ * Passing build-time output to `dangerouslySetInnerHTML` is safe here in the
+ * sense that matters: the input is the repository's own content files, not user
+ * submissions. Raw HTML in Markdown is intentionally supported.
+ *
+ * @param props - Component props
+ * @param props.html - Rendered HTML for the document body
+ *
+ * @example
+ * ```tsx
+ * const rendered = await renderDoc('guides/quick-start');
+ * <MarkdownContent html={rendered.html} />;
+ * ```
+ */
+export function MarkdownContent({ html }: MarkdownContentProps) {
+  return (
+    <>
+      <div className="ezw-prose" dangerouslySetInnerHTML={{ __html: html }} />
+      <CodeCopy />
+    </>
+  );
+}

package/template/components/markdown/PageTransition.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+import { usePathname } from 'next/navigation';
+
+/**
+ * Props for the PageTransition component
+ */
+interface PageTransitionProps {
+  /** Child content to animate */
+  children: React.ReactNode;
+}
+
+/**
+ * Page transition wrapper that animates content on route changes
+ *
+ * Provides smooth fade-in and slide-up animations when navigating
+ * between pages. The animation is triggered by pathname changes.
+ *
+ * @param props - Component props
+ * @param props.children - Content to wrap with transition effects
+ *
+ * @example
+ * ```tsx
+ * <PageTransition>
+ *   <article>Content here</article>
+ * </PageTransition>
+ * ```
+ */
+export function PageTransition({ children }: PageTransitionProps) {
+  const pathname = usePathname();
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    // Reset animation on route change
+    setIsVisible(false);
+
+    // Trigger animation after a brief delay
+    const timer = setTimeout(() => {
+      setIsVisible(true);
+    }, 50);
+
+    return () => clearTimeout(timer);
+  }, [pathname]);
+
+  return (
+    <div
+      className={`
+        transition-all duration-500 ease-out
+        ${isVisible ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-4'}
+      `}
+    >
+      {children}
+    </div>
+  );
+}

package/template/components/providers/UrlMapProvider.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import React, { createContext, useContext, useMemo } from 'react';
+import {
+  EMPTY_URL_MAP,
+  docPathToUrl,
+  hrefFor,
+  urlToDocPath,
+  type UrlMap,
+} from '@/lib/navigation/url';
+
+/**
+ * Makes the build-time URL mapping available to client components.
+ *
+ * The mapping is computed on the server — under the hash strategy that means
+ * running SHA-256 over every content path — and passed down as plain data.
+ * Client components look URLs up instead of deriving them, so the hashing
+ * implementation never reaches the browser bundle.
+ */
+
+const UrlMapContext = createContext<UrlMap>(EMPTY_URL_MAP);
+
+/** Helpers bound to the current URL map. */
+export interface UrlMapHelpers {
+  /** The raw mapping */
+  map: UrlMap;
+  /** Builds a root-relative href for a content path */
+  href: (docPath: string | undefined) => string;
+  /** Resolves a content path to its URL segment */
+  toUrl: (docPath: string) => string | null;
+  /** Resolves a URL segment back to its content path */
+  toPath: (slug: string) => string | null;
+}
+
+/**
+ * Provides the URL map to the client component tree.
+ *
+ * @param props.value - Mapping produced on the server by `getUrlMap()`
+ * @param props.children - Subtree that may consume the mapping
+ */
+export function UrlMapProvider({ value, children }: { value: UrlMap; children: React.ReactNode }) {
+  return <UrlMapContext.Provider value={value}>{children}</UrlMapContext.Provider>;
+}
+
+/**
+ * Reads the URL map and its bound helpers.
+ *
+ * @returns Helpers for converting between content paths and URLs
+ *
+ * @example
+ * ```tsx
+ * const { href } = useUrlMap();
+ * <Link href={href('guides/quick-start')}>Quick Start</Link>;
+ * ```
+ */
+export function useUrlMap(): UrlMapHelpers {
+  const map = useContext(UrlMapContext);
+
+  return useMemo(
+    () => ({
+      map,
+      href: (docPath: string | undefined) => hrefFor(map, docPath),
+      toUrl: (docPath: string) => docPathToUrl(map, docPath),
+      toPath: (slug: string) => urlToDocPath(map, slug),
+    }),
+    [map],
+  );
+}