create-eziwiki 0.1.0

package/template/components/search/SearchDialog.tsx

@@ -0,0 +1,286 @@
+'use client';
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { FileText, Hash, Loader2, Search as SearchIcon } from 'lucide-react';
+import { useSearchStore } from '@/lib/store/searchStore';
+import { search, type SearchResult } from '@/lib/search/client';
+
+/**
+ * Full-text search dialog, opened with ⌘K or from the sidebar.
+ *
+ * The index is fetched the first time the dialog opens, so search costs nothing
+ * until it is used. All matching happens in the browser against a static JSON
+ * file, which keeps it working on any static host.
+ */
+
+/** Debounce applied to keystrokes before querying. */
+const DEBOUNCE_MS = 120;
+
+/**
+ * Renders text with the query terms highlighted.
+ *
+ * Terms are matched case-insensitively and escaped before being put into a
+ * pattern, so a query containing regex metacharacters cannot break the match.
+ */
+function Highlighted({ text, query }: { text: string; query: string }) {
+  const terms = query
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+
+  if (terms.length === 0) return <>{text}</>;
+
+  const parts = text.split(new RegExp(`(${terms.join('|')})`, 'gi'));
+  const lowered = terms.map((term) => term.toLowerCase());
+
+  return (
+    <>
+      {parts.map((part, index) =>
+        lowered.includes(part.toLowerCase()) ? (
+          <mark
+            key={index}
+            className="bg-yellow-200 dark:bg-yellow-500/30 text-inherit rounded-sm px-0.5"
+          >
+            {part}
+          </mark>
+        ) : (
+          <React.Fragment key={index}>{part}</React.Fragment>
+        ),
+      )}
+    </>
+  );
+}
+
+export function SearchDialog() {
+  const router = useRouter();
+  const { isOpen, close, toggle } = useSearchStore();
+
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [selected, setSelected] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  // Global shortcut. Bound on the document so it works regardless of focus.
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+        event.preventDefault();
+        toggle();
+      }
+    };
+
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [toggle]);
+
+  // Reset and focus each time the dialog opens.
+  useEffect(() => {
+    if (!isOpen) return;
+
+    setQuery('');
+    setResults([]);
+    setSelected(0);
+    setError(null);
+
+    // Focus after paint, or the input is not yet mounted.
+    const raf = requestAnimationFrame(() => inputRef.current?.focus());
+    return () => cancelAnimationFrame(raf);
+  }, [isOpen]);
+
+  // Prevent the page behind the dialog from scrolling.
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const previous = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+
+    return () => {
+      document.body.style.overflow = previous;
+    };
+  }, [isOpen]);
+
+  // Run the query, debounced, discarding responses that arrive out of order.
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const trimmed = query.trim();
+
+    if (!trimmed) {
+      setResults([]);
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsLoading(true);
+
+    const timer = setTimeout(async () => {
+      try {
+        const found = await search(trimmed);
+        if (cancelled) return;
+
+        setResults(found);
+        setSelected(0);
+        setError(null);
+      } catch {
+        if (cancelled) return;
+        setError('Search is unavailable. Try reloading the page.');
+        setResults([]);
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }, DEBOUNCE_MS);
+
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, [query, isOpen]);
+
+  const go = useCallback(
+    (result: SearchResult) => {
+      close();
+      router.push(result.url);
+    },
+    [close, router],
+  );
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      close();
+      return;
+    }
+
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (results.length === 0) return;
+
+      const delta = event.key === 'ArrowDown' ? 1 : -1;
+      const next = (selected + delta + results.length) % results.length;
+
+      setSelected(next);
+      listRef.current?.children[next]?.scrollIntoView({ block: 'nearest' });
+      return;
+    }
+
+    if (event.key === 'Enter' && results[selected]) {
+      event.preventDefault();
+      go(results[selected]);
+    }
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center px-4 pt-[10vh]"
+      role="presentation"
+      onMouseDown={close}
+    >
+      <div className="fixed inset-0 bg-black/40 backdrop-blur-[2px]" aria-hidden="true" />
+
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search documentation"
+        className="relative w-full max-w-2xl overflow-hidden rounded-xl bg-white shadow-2xl ring-1 ring-black/10 dark:bg-gray-900 dark:ring-white/10"
+        onMouseDown={(event) => event.stopPropagation()}
+        onKeyDown={handleKeyDown}
+      >
+        <div className="flex items-center gap-3 border-b border-gray-200 px-4 dark:border-gray-800">
+          <SearchIcon className="h-4 w-4 flex-shrink-0 text-gray-400" />
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder="Search documentation…"
+            aria-label="Search query"
+            aria-controls="search-results"
+            className="flex-1 bg-transparent py-3.5 text-sm text-gray-900 outline-none placeholder:text-gray-400 dark:text-gray-100"
+          />
+          {isLoading && <Loader2 className="h-4 w-4 flex-shrink-0 animate-spin text-gray-400" />}
+          <kbd className="hidden flex-shrink-0 rounded border border-gray-300 px-1.5 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-700 dark:text-gray-400">
+            ESC
+          </kbd>
+        </div>
+
+        <div className="max-h-[60vh] overflow-y-auto">
+          {error && <p className="px-4 py-8 text-center text-sm text-red-600">{error}</p>}
+
+          {!error && query.trim() && !isLoading && results.length === 0 && (
+            <p className="px-4 py-8 text-center text-sm text-gray-500 dark:text-gray-400">
+              No results for “{query.trim()}”
+            </p>
+          )}
+
+          {!error && !query.trim() && (
+            <p className="px-4 py-8 text-center text-sm text-gray-500 dark:text-gray-400">
+              Search titles, headings, and page contents.
+            </p>
+          )}
+
+          {results.length > 0 && (
+            <ul ref={listRef} id="search-results" role="listbox" className="py-2">
+              {results.map((result, index) => (
+                <li key={result.id} role="option" aria-selected={index === selected}>
+                  <button
+                    type="button"
+                    onClick={() => go(result)}
+                    onMouseEnter={() => setSelected(index)}
+                    className={`flex w-full items-start gap-3 px-4 py-2.5 text-left transition-colors ${
+                      index === selected ? 'bg-blue-50 dark:bg-blue-950/40' : ''
+                    }`}
+                  >
+                    {result.section ? (
+                      <Hash className="mt-0.5 h-4 w-4 flex-shrink-0 text-gray-400" />
+                    ) : (
+                      <FileText className="mt-0.5 h-4 w-4 flex-shrink-0 text-gray-400" />
+                    )}
+
+                    <span className="min-w-0 flex-1">
+                      <span className="block truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+                        <Highlighted text={result.section ?? result.title} query={query} />
+                      </span>
+
+                      {result.section && (
+                        <span className="block truncate text-xs text-gray-500 dark:text-gray-400">
+                          {result.title}
+                        </span>
+                      )}
+
+                      {result.excerpt && (
+                        <span className="mt-0.5 block line-clamp-2 text-xs text-gray-600 dark:text-gray-400">
+                          <Highlighted text={result.excerpt} query={query} />
+                        </span>
+                      )}
+                    </span>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+
+        <div className="hidden items-center gap-4 border-t border-gray-200 px-4 py-2 text-[11px] text-gray-500 sm:flex dark:border-gray-800 dark:text-gray-400">
+          <span>
+            <kbd className="font-sans">↑↓</kbd> to navigate
+          </span>
+          <span>
+            <kbd className="font-sans">↵</kbd> to select
+          </span>
+          <span>
+            <kbd className="font-sans">esc</kbd> to close
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/components/search/SearchTrigger.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Search } from 'lucide-react';
+import { useSearchStore } from '@/lib/store/searchStore';
+
+/**
+ * Opens the search dialog.
+ *
+ * Rendered as a fake input rather than a button-looking control because that is
+ * what readers expect to click to search; the real input lives in the dialog.
+ */
+export function SearchTrigger({ className = '' }: { className?: string }) {
+  const open = useSearchStore((state) => state.open);
+  const [shortcut, setShortcut] = useState<string | null>(null);
+
+  // The modifier differs by platform, and the platform is only known in the
+  // browser — rendering a guess on the server would hydrate mismatched.
+  useEffect(() => {
+    const isMac = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+    setShortcut(isMac ? '⌘K' : 'Ctrl K');
+  }, []);
+
+  return (
+    <button
+      type="button"
+      onClick={open}
+      aria-label="Search documentation"
+      aria-keyshortcuts="Meta+K Control+K"
+      className={`flex items-center gap-2 rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-400 transition-colors hover:border-gray-400 dark:border-gray-700 dark:bg-gray-800 dark:hover:border-gray-600 ${className}`}
+    >
+      <Search className="h-4 w-4 flex-shrink-0" />
+      <span className="min-w-0 flex-1 truncate text-left">Search…</span>
+      {shortcut && (
+        <kbd className="hidden flex-shrink-0 rounded border border-gray-300 px-1 py-0.5 text-[10px] text-gray-500 sm:block dark:border-gray-600 dark:text-gray-400">
+          {shortcut}
+        </kbd>
+      )}
+    </button>
+  );
+}

package/template/content/guides/_meta.json

@@ -0,0 +1,4 @@
+{
+  "name": "📖 Guides",
+  "order": 2
+}

package/template/content/guides/writing.md

@@ -0,0 +1,82 @@
+---
+title: Writing Pages
+description: Frontmatter, links, code, and everything else a page can contain
+order: 1
+---
+
+# Writing Pages
+
+## Frontmatter
+
+Every page can start with a frontmatter block. All of it is optional.
+
+```markdown
+---
+title: Writing Pages # Sidebar label; defaults to the file name
+description: What this page covers # Used for SEO and search results
+order: 1 # Sort weight within its folder
+hidden: false # true keeps it out of the sidebar and search
+---
+```
+
+## Organising pages
+
+Folders become sidebar sections. To name or order one, add a `_meta.json`
+beside its pages:
+
+```json
+{ "name": "📖 Guides", "order": 1, "color": "#dbeafe" }
+```
+
+Files and folders starting with `_` or `.` are skipped, so drafts can live in
+`content/_drafts/` without being published.
+
+## Linking
+
+Ordinary Markdown links work with content paths:
+
+```markdown
+[Welcome](/intro)
+```
+
+Wiki links resolve by full path, file name, or page title — so you can link to
+a page without knowing where it sits:
+
+```markdown
+[[intro]] [[Writing Pages]] [[guides/writing|see the guide]] [[intro#next]]
+```
+
+A link that resolves to nothing is shown as visibly broken rather than as a
+dead link. Run `npm run check:links` to list them all.
+
+## Code
+
+Fenced blocks are highlighted at build time and get a copy button:
+
+```typescript
+export function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+```
+
+## Maths
+
+Inline $E = mc^2$ and display maths both render:
+
+$$
+\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
+$$
+
+## Tables and task lists
+
+| Feature | Included |
+| ------- | -------- |
+| Search  | Yes      |
+| Graph   | Yes      |
+
+- [x] Write a page
+- [ ] Publish it
+
+## Back
+
+Return to [[intro]].

package/template/content/intro.md

@@ -0,0 +1,29 @@
+---
+title: Welcome
+description: The starting point of your new wiki
+order: 1
+---
+
+# Welcome 👋
+
+This is your new wiki. Every Markdown file under `content/` becomes a page —
+there is nothing to register anywhere.
+
+## Getting started
+
+1. Edit this file, or drop a new `.md` file into `content/`.
+2. Change the site title in `payload/config.ts`.
+3. Run `npm run dev` and open <http://localhost:3000>.
+
+## What you get
+
+- **Search** — press <kbd>⌘K</kbd> (or <kbd>Ctrl K</kbd>) to search titles, headings, and text
+- **Contents rail** — built automatically from each page's headings
+- **Wiki links** — write [[guides/writing]] and it resolves by path, file name, or title
+- **Backlinks** — every page lists what links to it, at the bottom
+- **Graph** — see how your pages connect on the [Graph](/graph) page
+- **Dark mode**, syntax highlighting, and maths, with no configuration
+
+## Next
+
+Read [[writing]] to see what you can put in a page.

package/template/eslintignore

@@ -0,0 +1,7 @@
+node_modules
+.next
+out
+reference
+*.config.js
+*.config.ts
+packages/*/template

package/template/eslintrc.js

@@ -0,0 +1,40 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'next/core-web-vitals',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+    'prettier',
+  ],
+  plugins: ['@typescript-eslint', 'prettier'],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+    project: './tsconfig.json',
+  },
+  env: {
+    browser: true,
+    node: true,
+    es6: true,
+  },
+  rules: {
+    'no-underscore-dangle': 0,
+    '@typescript-eslint/no-namespace': 0,
+    '@typescript-eslint/explicit-function-return-type': 0,
+    '@typescript-eslint/no-use-before-define': 0,
+    'import/prefer-default-export': 0,
+    'import/extensions': 0,
+    'react/react-in-jsx-scope': 0,
+    quotes: [
+      2,
+      'single',
+      {
+        avoidEscape: true,
+      },
+    ],
+    '@typescript-eslint/no-explicit-any': 'warn',
+  },
+};

package/template/gitignore

@@ -0,0 +1,40 @@
+# Dependencies
+node_modules/
+/.pnp
+.pnp.js
+
+# Testing
+/coverage
+
+# Next.js
+/.next/
+/out/
+
+# Production
+/build
+
+# Misc
+.DS_Store
+*.pem
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env*.local
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+.kiro
+# Generated search index
+/public/search-index.json
+
+# Generated CLI template
+/packages/create-eziwiki/template/

package/template/lib/basePath.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+/**
+ * Loads the module with a given deployment environment.
+ *
+ * The base path and origin are read once at import time — they cannot change
+ * during a build — so exercising a different deployment means re-importing
+ * rather than reassigning.
+ *
+ * @param env - Values for the two deployment variables
+ * @returns The freshly imported module
+ */
+async function load(env: { basePath?: string; siteUrl?: string }) {
+  vi.resetModules();
+  process.env.NEXT_PUBLIC_BASE_PATH = env.basePath ?? '';
+  process.env.NEXT_PUBLIC_SITE_URL = env.siteUrl ?? '';
+  return import('./basePath');
+}
+
+afterEach(() => {
+  delete process.env.NEXT_PUBLIC_BASE_PATH;
+  delete process.env.NEXT_PUBLIC_SITE_URL;
+});
+
+describe('asset', () => {
+  it('leaves public paths alone when served from the root', async () => {
+    const { asset } = await load({});
+    expect(asset('/favicon.svg')).toBe('/favicon.svg');
+  });
+
+  it('prefixes public paths with the base path', async () => {
+    const { asset } = await load({ basePath: '/eziwiki' });
+    expect(asset('/favicon.svg')).toBe('/eziwiki/favicon.svg');
+    expect(asset('/fonts/SUITE/SUITE-Regular.woff2')).toBe(
+      '/eziwiki/fonts/SUITE/SUITE-Regular.woff2',
+    );
+  });
+
+  it('leaves absolute and protocol-relative URLs untouched', async () => {
+    const { asset } = await load({ basePath: '/eziwiki' });
+    expect(asset('https://cdn.example.com/logo.svg')).toBe('https://cdn.example.com/logo.svg');
+    expect(asset('//cdn.example.com/logo.svg')).toBe('//cdn.example.com/logo.svg');
+  });
+});
+
+describe('pageUrl', () => {
+  it('composes origin, base path and a trailing slash', async () => {
+    const { pageUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(pageUrl('getting-started/quick-start')).toBe(
+      'https://user.github.io/eziwiki/getting-started/quick-start/',
+    );
+  });
+
+  it('returns the home page for an empty segment', async () => {
+    const { pageUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(pageUrl('')).toBe('https://user.github.io/eziwiki/');
+  });
+
+  it('falls back to the payload base URL when the deployment declares none', async () => {
+    const { pageUrl } = await load({});
+    expect(pageUrl('intro', 'https://example.com')).toBe('https://example.com/intro/');
+  });
+
+  it('lets the deployment origin override the payload base URL', async () => {
+    const { pageUrl } = await load({ siteUrl: 'https://user.github.io' });
+    expect(pageUrl('intro', 'https://placeholder.dev')).toBe('https://user.github.io/intro/');
+  });
+
+  it('does not double up slashes however the parts are written', async () => {
+    const { pageUrl } = await load({ siteUrl: 'https://user.github.io/' });
+    expect(pageUrl('/intro/', 'https://placeholder.dev/')).toBe('https://user.github.io/intro/');
+  });
+
+  // The sitemap advertises these URLs and the canonical tag names them; if the
+  // two disagree on the slash, the sitemap points at a redirect.
+  it('agrees with the trailing-slash form Next serves', async () => {
+    const { pageUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(pageUrl('intro')).toMatch(/\/$/);
+  });
+
+  // A mirror is served from a subdirectory of its own host while the canonical
+  // site is elsewhere. Combining the two would name a path that exists on
+  // neither: 'https://production.app/eziwiki/intro/'.
+  it('omits the base path when canonicalising to another deployment', async () => {
+    const { pageUrl } = await load({ basePath: '/eziwiki' });
+    expect(pageUrl('intro', 'https://production.app')).toBe('https://production.app/intro/');
+  });
+
+  it('includes the base path when the deployment is itself canonical', async () => {
+    const { pageUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(pageUrl('intro', 'https://production.app')).toBe(
+      'https://user.github.io/eziwiki/intro/',
+    );
+  });
+});
+
+describe('fileUrl', () => {
+  it('composes origin and base path without a trailing slash', async () => {
+    const { fileUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(fileUrl('/sitemap.xml')).toBe('https://user.github.io/eziwiki/sitemap.xml');
+    expect(fileUrl('/og-image.svg')).toBe('https://user.github.io/eziwiki/og-image.svg');
+  });
+
+  it('accepts a path written without a leading slash', async () => {
+    const { fileUrl } = await load({ siteUrl: 'https://user.github.io' });
+    expect(fileUrl('og-image.svg')).toBe('https://user.github.io/og-image.svg');
+  });
+
+  it('leaves an already absolute image alone', async () => {
+    const { fileUrl } = await load({ basePath: '/eziwiki', siteUrl: 'https://user.github.io' });
+    expect(fileUrl('https://cdn.example.com/og.png')).toBe('https://cdn.example.com/og.png');
+  });
+
+  it('omits the base path when canonicalising to another deployment', async () => {
+    const { fileUrl } = await load({ basePath: '/eziwiki' });
+    expect(fileUrl('/og-image.svg', 'https://production.app')).toBe(
+      'https://production.app/og-image.svg',
+    );
+  });
+});