create-eziwiki 0.1.0

package/template/lib/navigation/builder.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { extractAllPaths, findActiveItem } from './builder';
+import { NavigationItem } from '../payload/types';
+
+describe('extractAllPaths', () => {
+  it('should extract paths from flat navigation structure', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Home', path: 'home' },
+      { name: 'About', path: 'about' },
+      { name: 'Contact', path: 'contact' },
+    ];
+
+    const paths = extractAllPaths(navigation);
+    expect(paths).toEqual(['home', 'about', 'contact']);
+  });
+
+  it('should extract paths from nested navigation structure', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Home', path: 'home' },
+      {
+        name: 'Guides',
+        children: [
+          { name: 'Quick Start', path: 'guides/quick-start' },
+          { name: 'Configuration', path: 'guides/configuration' },
+        ],
+      },
+    ];
+
+    const paths = extractAllPaths(navigation);
+    expect(paths).toEqual(['home', 'guides/quick-start', 'guides/configuration']);
+  });
+
+  it('should handle deeply nested structures', () => {
+    const navigation: NavigationItem[] = [
+      {
+        name: 'Docs',
+        children: [
+          {
+            name: 'API',
+            children: [
+              { name: 'Authentication', path: 'docs/api/auth' },
+              { name: 'Users', path: 'docs/api/users' },
+            ],
+          },
+        ],
+      },
+    ];
+
+    const paths = extractAllPaths(navigation);
+    expect(paths).toEqual(['docs/api/auth', 'docs/api/users']);
+  });
+
+  it('should handle items without paths', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Section', children: [{ name: 'Page', path: 'page' }] },
+    ];
+
+    const paths = extractAllPaths(navigation);
+    expect(paths).toEqual(['page']);
+  });
+
+  it('should return empty array for empty navigation', () => {
+    const paths = extractAllPaths([]);
+    expect(paths).toEqual([]);
+  });
+});
+
+describe('findActiveItem', () => {
+  it('should find item in flat navigation structure', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Home', path: 'home' },
+      { name: 'About', path: 'about' },
+    ];
+
+    const item = findActiveItem(navigation, 'about');
+    expect(item).toEqual({ name: 'About', path: 'about' });
+  });
+
+  it('should find item in nested navigation structure', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Home', path: 'home' },
+      {
+        name: 'Guides',
+        children: [
+          { name: 'Quick Start', path: 'guides/quick-start' },
+          { name: 'Configuration', path: 'guides/configuration' },
+        ],
+      },
+    ];
+
+    const item = findActiveItem(navigation, 'guides/configuration');
+    expect(item).toEqual({ name: 'Configuration', path: 'guides/configuration' });
+  });
+
+  it('should find item in deeply nested structure', () => {
+    const navigation: NavigationItem[] = [
+      {
+        name: 'Docs',
+        children: [
+          {
+            name: 'API',
+            children: [
+              { name: 'Authentication', path: 'docs/api/auth' },
+              { name: 'Users', path: 'docs/api/users' },
+            ],
+          },
+        ],
+      },
+    ];
+
+    const item = findActiveItem(navigation, 'docs/api/users');
+    expect(item).toEqual({ name: 'Users', path: 'docs/api/users' });
+  });
+
+  it('should return null when path is not found', () => {
+    const navigation: NavigationItem[] = [
+      { name: 'Home', path: 'home' },
+      { name: 'About', path: 'about' },
+    ];
+
+    const item = findActiveItem(navigation, 'nonexistent');
+    expect(item).toBeNull();
+  });
+
+  it('should return null for empty navigation', () => {
+    const item = findActiveItem([], 'any-path');
+    expect(item).toBeNull();
+  });
+});

package/template/lib/navigation/builder.ts

@@ -0,0 +1,122 @@
+import { NavigationItem } from '../payload/types';
+
+/**
+ * Recursively extracts all paths from a navigation tree structure
+ *
+ * This function traverses the entire navigation hierarchy and collects
+ * all path values, which are used to generate static pages at build time.
+ * Items without a path property are skipped (they act as section headers).
+ * Hidden items are included in the extraction (they're just hidden from UI).
+ *
+ * @param items - Array of navigation items to process
+ * @returns Flat array of all path strings found in the navigation tree
+ *
+ * @example
+ * ```typescript
+ * const navigation = [
+ *   { name: 'Home', path: 'home' },
+ *   {
+ *     name: 'Guides',
+ *     children: [
+ *       { name: 'Quick Start', path: 'guides/quick-start' },
+ *       { name: 'Config', path: 'guides/config' }
+ *     ]
+ *   }
+ * ];
+ *
+ * const paths = extractAllPaths(navigation);
+ * // Returns: ['home', 'guides/quick-start', 'guides/config']
+ * ```
+ */
+export function extractAllPaths(items: NavigationItem[]): string[] {
+  const paths: string[] = [];
+
+  function traverse(items: NavigationItem[]) {
+    for (const item of items) {
+      if (item.path) {
+        paths.push(item.path);
+      }
+      if (item.children) {
+        traverse(item.children);
+      }
+    }
+  }
+
+  traverse(items);
+  return paths;
+}
+
+/**
+ * Filter out hidden navigation items
+ *
+ * Recursively removes items marked as hidden from the navigation tree.
+ * This is used to hide items from the sidebar while keeping them accessible via URL.
+ *
+ * @param items - Array of navigation items to filter
+ * @returns Filtered navigation tree without hidden items
+ *
+ * @example
+ * ```typescript
+ * const navigation = [
+ *   { name: 'Public', path: 'public' },
+ *   { name: 'Secret', path: 'secret', hidden: true }
+ * ];
+ *
+ * const visible = filterHiddenItems(navigation);
+ * // Returns: [{ name: 'Public', path: 'public' }]
+ * ```
+ */
+export function filterHiddenItems(items: NavigationItem[]): NavigationItem[] {
+  return items
+    .filter((item) => !item.hidden)
+    .map((item) => ({
+      ...item,
+      children: item.children ? filterHiddenItems(item.children) : undefined,
+    }));
+}
+
+/**
+ * Recursively searches navigation tree to find the item matching the current path
+ *
+ * This function is used to highlight the active navigation item in the sidebar.
+ * It performs a depth-first search through the navigation hierarchy to find
+ * the item whose path matches the current page path.
+ *
+ * @param items - Array of navigation items to search
+ * @param currentPath - Current page path to match against
+ * @returns The matching NavigationItem if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const navigation = [
+ *   { name: 'Home', path: 'home' },
+ *   {
+ *     name: 'Guides',
+ *     children: [
+ *       { name: 'Quick Start', path: 'guides/quick-start' }
+ *     ]
+ *   }
+ * ];
+ *
+ * const activeItem = findActiveItem(navigation, 'guides/quick-start');
+ * // Returns: { name: 'Quick Start', path: 'guides/quick-start' }
+ *
+ * const notFound = findActiveItem(navigation, 'nonexistent');
+ * // Returns: null
+ * ```
+ */
+export function findActiveItem(
+  items: NavigationItem[],
+  currentPath: string,
+): NavigationItem | null {
+  for (const item of items) {
+    if (item.path === currentPath) {
+      return item;
+    }
+    if (item.children) {
+      const found = findActiveItem(item.children, currentPath);
+      if (found) return found;
+    }
+  }
+  return null;
+}

package/template/lib/navigation/hash.ts

@@ -0,0 +1,32 @@
+import crypto from 'crypto';
+
+/**
+ * Deterministic path hashing for the `hash` URL strategy.
+ *
+ * Node-only: this is used when building the URL map on the server. Client
+ * components consume the finished map through `UrlMapProvider` and never hash
+ * anything themselves, which keeps the digest implementation out of the browser
+ * bundle.
+ */
+
+/**
+ * Generates a stable, URL-safe hash for a content path.
+ *
+ * The same input always produces the same hash, so URLs stay valid across
+ * builds as long as the file does not move.
+ *
+ * @param filePath - Content-relative path (e.g. 'guides/quick-start')
+ * @returns Hash formatted as three 8-character groups
+ *
+ * @example
+ * ```typescript
+ * generatePathHash('guides/quick-start');
+ * // 'a3f2e9d1-4b8c7e6f-9d2a1b3c'
+ * ```
+ */
+export function generatePathHash(filePath: string): string {
+  const hash = crypto.createHash('sha256').update(filePath).digest('hex');
+
+  // Format: 8chars-8chars-8chars for readability
+  return `${hash.slice(0, 8)}-${hash.slice(8, 16)}-${hash.slice(16, 24)}`;
+}

package/template/lib/navigation/url.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { docPathToUrl, hrefFor, normalizeSlug, urlToDocPath, type UrlMap } from './url';
+import { buildUrlMap } from './urlMap';
+
+const PATHS = ['intro', 'guides/quick-start', 'guides/nested/deep'];
+
+describe('normalizeSlug', () => {
+  it('strips leading and trailing slashes', () => {
+    expect(normalizeSlug('/guides/quick-start/')).toBe('guides/quick-start');
+    expect(normalizeSlug('guides/quick-start')).toBe('guides/quick-start');
+    expect(normalizeSlug('/')).toBe('');
+  });
+});
+
+describe('buildUrlMap', () => {
+  it('maps a path to itself under the path strategy', () => {
+    const map = buildUrlMap(PATHS, 'path');
+
+    expect(map.toUrl['guides/quick-start']).toBe('guides/quick-start');
+    expect(map.toPath['guides/quick-start']).toBe('guides/quick-start');
+  });
+
+  it('maps a path to a deterministic hash under the hash strategy', () => {
+    const first = buildUrlMap(PATHS, 'hash');
+    const second = buildUrlMap(PATHS, 'hash');
+
+    expect(first.toUrl['intro']).toMatch(/^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}$/);
+    expect(first.toUrl['intro']).toBe(second.toUrl['intro']);
+  });
+
+  it('round-trips every path through the map under both strategies', () => {
+    for (const strategy of ['path', 'hash'] as const) {
+      const map = buildUrlMap(PATHS, strategy);
+
+      for (const path of PATHS) {
+        const url = docPathToUrl(map, path);
+        expect(url).not.toBeNull();
+        expect(urlToDocPath(map, url!)).toBe(path);
+      }
+    }
+  });
+
+  it('ignores empty paths rather than mapping them to the root', () => {
+    const map = buildUrlMap(['', '/', 'intro'], 'path');
+
+    expect(map.toPath['']).toBeUndefined();
+    expect(Object.keys(map.toUrl)).toEqual(['intro']);
+  });
+
+  it('normalises surrounding slashes before mapping', () => {
+    const map = buildUrlMap(['/intro/'], 'path');
+
+    expect(map.toUrl['intro']).toBe('intro');
+  });
+});
+
+describe('docPathToUrl / urlToDocPath', () => {
+  const map = buildUrlMap(PATHS, 'path');
+
+  it('tolerates surrounding slashes on lookup', () => {
+    expect(docPathToUrl(map, '/intro/')).toBe('intro');
+    expect(urlToDocPath(map, '/guides/quick-start/')).toBe('guides/quick-start');
+  });
+
+  it('returns null for unknown paths', () => {
+    expect(docPathToUrl(map, 'nope')).toBeNull();
+    expect(urlToDocPath(map, 'nope')).toBeNull();
+  });
+});
+
+describe('hrefFor', () => {
+  const map = buildUrlMap(PATHS, 'path');
+
+  it('builds a root-relative href', () => {
+    expect(hrefFor(map, 'guides/quick-start')).toBe('/guides/quick-start');
+  });
+
+  it('falls back to the root for unknown or missing paths', () => {
+    expect(hrefFor(map, undefined)).toBe('/');
+    expect(hrefFor(map, '')).toBe('/');
+    expect(hrefFor(map, 'nope')).toBe('/');
+  });
+
+  it('never emits a literal null segment', () => {
+    const empty: UrlMap = { strategy: 'path', toUrl: {}, toPath: {} };
+    expect(hrefFor(empty, 'anything')).toBe('/');
+  });
+});

package/template/lib/navigation/url.ts

@@ -0,0 +1,108 @@
+/**
+ * URL strategy determining how content paths appear in the address bar.
+ *
+ * - `path` — readable, SEO-friendly URLs mirroring the content tree
+ *   (`/guides/quick-start`)
+ * - `hash` — opaque, deterministic hashes that conceal the content structure
+ *   (`/a3f2e9d1-4b8c7e6f-9d2a1b3c`)
+ */
+export type UrlStrategy = 'path' | 'hash';
+
+/** Strategy applied when the payload does not specify one. */
+export const DEFAULT_URL_STRATEGY: UrlStrategy = 'path';
+
+/**
+ * A precomputed, bidirectional mapping between content paths and URL segments.
+ *
+ * The map is built once on the server and handed to client components as plain
+ * data. Keeping it serialisable is deliberate: it means the browser never needs
+ * the hashing implementation, only the results.
+ */
+export interface UrlMap {
+  /** Strategy this map was built with */
+  strategy: UrlStrategy;
+  /** Content path to URL segment (e.g. 'guides/quick-start' -> 'a3f2e9d1-...') */
+  toUrl: Record<string, string>;
+  /** URL segment back to content path */
+  toPath: Record<string, string>;
+}
+
+/** An empty map, used as a safe default before hydration. */
+export const EMPTY_URL_MAP: UrlMap = {
+  strategy: DEFAULT_URL_STRATEGY,
+  toUrl: {},
+  toPath: {},
+};
+
+/**
+ * Strips leading and trailing slashes from a URL fragment.
+ *
+ * Route params arrive in several shapes depending on `trailingSlash` and on
+ * whether the value came from `usePathname` or from a slug array; normalising
+ * here keeps every caller from repeating the same trimming.
+ *
+ * @param value - Raw path or slug fragment
+ * @returns The fragment without surrounding slashes
+ *
+ * @example
+ * ```typescript
+ * normalizeSlug('/guides/quick-start/'); // 'guides/quick-start'
+ * normalizeSlug('guides/quick-start'); // 'guides/quick-start'
+ * ```
+ */
+export function normalizeSlug(value: string): string {
+  return value.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+/**
+ * Resolves a content path to its URL segment.
+ *
+ * @param map - Precomputed URL mapping
+ * @param docPath - Content-relative path without extension
+ * @returns The URL segment, or null when the path is not part of the site
+ *
+ * @example
+ * ```typescript
+ * docPathToUrl(map, 'guides/quick-start');
+ * // 'guides/quick-start' with the path strategy
+ * // 'a3f2e9d1-4b8c7e6f-9d2a1b3c' with the hash strategy
+ * ```
+ */
+export function docPathToUrl(map: UrlMap, docPath: string): string | null {
+  const normalized = normalizeSlug(docPath);
+  return map.toUrl[normalized] ?? null;
+}
+
+/**
+ * Resolves a URL segment back to its content path.
+ *
+ * @param map - Precomputed URL mapping
+ * @param slug - URL segment, with or without surrounding slashes
+ * @returns The content path, or null when the segment matches no document
+ */
+export function urlToDocPath(map: UrlMap, slug: string): string | null {
+  const normalized = normalizeSlug(slug);
+  return map.toPath[normalized] ?? null;
+}
+
+/**
+ * Builds an `href` for a content path, ready to hand to a link or router.
+ *
+ * Falls back to the root path when the document is unknown, which keeps
+ * navigation from emitting `/null` for a stale or mistyped reference.
+ *
+ * @param map - Precomputed URL mapping
+ * @param docPath - Content-relative path without extension
+ * @returns A root-relative href
+ *
+ * @example
+ * ```typescript
+ * hrefFor(map, 'guides/quick-start'); // '/guides/quick-start'
+ * hrefFor(map, 'does-not-exist'); // '/'
+ * ```
+ */
+export function hrefFor(map: UrlMap, docPath: string | undefined): string {
+  if (!docPath) return '/';
+  const url = docPathToUrl(map, docPath);
+  return url ? `/${url}` : '/';
+}

package/template/lib/navigation/urlMap.ts

@@ -0,0 +1,81 @@
+import { getAllDocPaths } from '../content/registry';
+import { payload } from '@/payload/config';
+import { generatePathHash } from './hash';
+import { DEFAULT_URL_STRATEGY, normalizeSlug, type UrlMap, type UrlStrategy } from './url';
+import { cached } from '../cache';
+
+/**
+ * Server-side construction of the {@link UrlMap}.
+ *
+ * This module reaches into the filesystem and into Node's crypto, so it must
+ * only be imported from server components, route handlers, and build scripts.
+ * Client components receive the finished map through `UrlMapProvider` instead.
+ */
+
+/**
+ * Returns the URL strategy declared by the payload, or the default.
+ */
+export function getUrlStrategy(): UrlStrategy {
+  return payload.global.urlStrategy ?? DEFAULT_URL_STRATEGY;
+}
+
+/**
+ * Builds a bidirectional URL mapping for the given content paths.
+ *
+ * Under the `hash` strategy a collision would make two documents unreachable
+ * through one another's URL, so collisions are surfaced as a build error rather
+ * than silently resolving to whichever document happened to be scanned last.
+ *
+ * @param docPaths - Content-relative paths to include
+ * @param strategy - URL strategy to apply
+ * @returns The populated mapping
+ * @throws Error if two distinct paths produce the same URL segment
+ *
+ * @example
+ * ```typescript
+ * const map = buildUrlMap(['intro', 'guides/quick-start'], 'path');
+ * map.toUrl['guides/quick-start']; // 'guides/quick-start'
+ * map.toPath['intro']; // 'intro'
+ * ```
+ */
+export function buildUrlMap(docPaths: string[], strategy: UrlStrategy): UrlMap {
+  const toUrl: Record<string, string> = {};
+  const toPath: Record<string, string> = {};
+
+  for (const rawPath of docPaths) {
+    const docPath = normalizeSlug(rawPath);
+    if (!docPath) continue;
+
+    const url = strategy === 'hash' ? generatePathHash(docPath) : docPath;
+    const existing = toPath[url];
+
+    if (existing !== undefined && existing !== docPath) {
+      throw new Error(
+        `URL collision under the '${strategy}' strategy: ` +
+          `'${existing}' and '${docPath}' both map to '${url}'.`,
+      );
+    }
+
+    toUrl[docPath] = url;
+    toPath[url] = docPath;
+  }
+
+  return { strategy, toUrl, toPath };
+}
+
+let memo: UrlMap | null = null;
+
+/**
+ * Returns the URL map for the whole content tree, memoised per process.
+ *
+ * Every document is included, not only those reachable from the sidebar, so
+ * hidden pages and documents omitted from navigation still resolve.
+ *
+ * @returns The site-wide URL mapping
+ */
+export function getUrlMap(): UrlMap {
+  const hit = cached(memo);
+  if (hit) return hit;
+  memo = buildUrlMap(getAllDocPaths(), getUrlStrategy());
+  return memo;
+}

package/template/lib/payload/schema.ts

@@ -0,0 +1,81 @@
+/**
+ * JSON Schema definition for payload validation
+ */
+export const payloadSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  type: 'object',
+  required: ['global'],
+  properties: {
+    global: {
+      type: 'object',
+      required: ['title', 'description'],
+      properties: {
+        title: { type: 'string', minLength: 1 },
+        description: { type: 'string', minLength: 1 },
+        favicon: { type: 'string' },
+        baseUrl: { type: 'string', format: 'uri' },
+        urlStrategy: { type: 'string', enum: ['path', 'hash'] },
+        autoNavigation: { type: 'boolean' },
+        seo: {
+          type: 'object',
+          properties: {
+            openGraph: {
+              type: 'object',
+              properties: {
+                title: { type: 'string' },
+                description: { type: 'string' },
+                images: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    required: ['url'],
+                    properties: {
+                      url: { type: 'string' },
+                      width: { type: 'number' },
+                      height: { type: 'number' },
+                      alt: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    navigation: {
+      type: 'array',
+      items: {
+        $ref: '#/definitions/navigationItem',
+      },
+    },
+    theme: {
+      type: 'object',
+      properties: {
+        primary: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+        secondary: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+        background: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+        text: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+        sidebarBg: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+        codeBg: { type: 'string', pattern: '^#[0-9A-Fa-f]{6}$' },
+      },
+    },
+  },
+  definitions: {
+    navigationItem: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', minLength: 1 },
+        path: { type: 'string' },
+        icon: { type: 'string' },
+        color: { type: 'string' },
+        hidden: { type: 'boolean' },
+        children: {
+          type: 'array',
+          items: { $ref: '#/definitions/navigationItem' },
+        },
+      },
+    },
+  },
+};