create-eziwiki 0.1.1 → 0.3.0

package/template/components/markdown/LinkPreview.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * Shows where a wiki link goes before a reader commits to following it.
+ *
+ * The title and summary are already on the anchor as `data-preview-*`,
+ * written there during the build, so the card costs no request and appears
+ * immediately. A single delegated listener covers every link on the page,
+ * including any that arrive with a transcluded block.
+ *
+ * Rendered into `document.body` rather than in place. The card is positioned
+ * against the viewport, and `position: fixed` resolves against the nearest
+ * transformed ancestor instead — which the page-transition wrapper is, so a
+ * card rendered here landed roughly a screenful off the top of the window.
+ *
+ * @example
+ * ```tsx
+ * <article dangerouslySetInnerHTML={{ __html: html }} />
+ * <LinkPreview />
+ * ```
+ */
+
+/** Milliseconds a pointer must rest on a link before the card appears. */
+const OPEN_DELAY_MS = 350;
+
+/** Milliseconds before a card closes, so a pointer may cross a gap. */
+const CLOSE_DELAY_MS = 120;
+
+/** Distance from the link to the card. */
+const OFFSET_PX = 8;
+
+/** Card width, needed here to keep it on screen. */
+const WIDTH_PX = 320;
+
+interface PreviewState {
+  title: string;
+  excerpt: string;
+  top: number;
+  left: number;
+  /** Whether the card sits below its link rather than above */
+  below: boolean;
+}
+
+export function LinkPreview() {
+  const [preview, setPreview] = useState<PreviewState | null>(null);
+  const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    function clearTimers() {
+      if (openTimer.current) clearTimeout(openTimer.current);
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    }
+
+    function place(anchor: HTMLElement): PreviewState | null {
+      const title = anchor.getAttribute('data-preview-title');
+      if (!title) return null;
+
+      const rect = anchor.getBoundingClientRect();
+
+      // Above the link by default, below it when there is no room above —
+      // a card that opens off the top of the viewport shows nothing.
+      const below = rect.top < 160;
+
+      return {
+        title,
+        excerpt: anchor.getAttribute('data-preview') ?? '',
+        top: below ? rect.bottom + OFFSET_PX : rect.top - OFFSET_PX,
+        left: Math.max(8, Math.min(rect.left, document.documentElement.clientWidth - WIDTH_PX - 8)),
+        below,
+      };
+    }
+
+    function open(anchor: HTMLElement, delay: number) {
+      clearTimers();
+      openTimer.current = setTimeout(() => {
+        const next = place(anchor);
+        if (next) setPreview(next);
+      }, delay);
+    }
+
+    function close(delay = CLOSE_DELAY_MS) {
+      clearTimers();
+      closeTimer.current = setTimeout(() => setPreview(null), delay);
+    }
+
+    function anchorFrom(target: EventTarget | null): HTMLElement | null {
+      return (target as HTMLElement | null)?.closest?.<HTMLElement>('a.ezw-wikilink') ?? null;
+    }
+
+    function handleOver(event: MouseEvent) {
+      const anchor = anchorFrom(event.target);
+      if (anchor) open(anchor, OPEN_DELAY_MS);
+    }
+
+    function handleOut(event: MouseEvent) {
+      if (anchorFrom(event.target)) close();
+    }
+
+    // Keyboard users reach the link by tabbing, and get the same card without
+    // the delay a pointer needs to signal intent.
+    function handleFocus(event: FocusEvent) {
+      const anchor = anchorFrom(event.target);
+      if (anchor) open(anchor, 0);
+    }
+
+    function handleBlur(event: FocusEvent) {
+      if (anchorFrom(event.target)) close(0);
+    }
+
+    // Dismissible without moving the pointer, which WCAG asks of anything that
+    // appears on hover.
+    function handleKey(event: KeyboardEvent) {
+      if (event.key === 'Escape') close(0);
+    }
+
+    document.addEventListener('mouseover', handleOver);
+    document.addEventListener('mouseout', handleOut);
+    document.addEventListener('focusin', handleFocus);
+    document.addEventListener('focusout', handleBlur);
+    // Any movement of the page leaves the card pointing at nothing. Named so
+    // that the cleanup below can actually remove it.
+    function handleScroll() {
+      close(0);
+    }
+
+    document.addEventListener('keydown', handleKey);
+    window.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => {
+      clearTimers();
+      document.removeEventListener('mouseover', handleOver);
+      document.removeEventListener('mouseout', handleOut);
+      document.removeEventListener('focusin', handleFocus);
+      document.removeEventListener('focusout', handleBlur);
+      document.removeEventListener('keydown', handleKey);
+      window.removeEventListener('scroll', handleScroll);
+    };
+  }, []);
+
+  if (!preview || typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div
+      // Presentational: the link it describes is already in the accessible
+      // tree, and announcing the summary twice would be noise.
+      aria-hidden="true"
+      className="ezw-link-preview"
+      style={{
+        top: preview.top,
+        left: preview.left,
+        width: WIDTH_PX,
+        transform: preview.below ? undefined : 'translateY(-100%)',
+      }}
+    >
+      <p className="ezw-link-preview__title">{preview.title}</p>
+      {preview.excerpt && <p className="ezw-link-preview__excerpt">{preview.excerpt}</p>}
+    </div>,
+    document.body,
+  );
+}

package/template/components/markdown/MarkdownContent.tsx

@@ -1,4 +1,5 @@
 import { CodeCopy } from './CodeCopy';
+import { LinkPreview } from './LinkPreview';
 
 /**
  * Props for the MarkdownContent component
@@ -13,7 +14,7 @@ interface MarkdownContentProps {
  *
  * 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.
+ * client-side code is the copy-button and link-preview listeners.
  *
  * 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
@@ -33,6 +34,7 @@ export function MarkdownContent({ html }: MarkdownContentProps) {
     <>
       <div className="ezw-prose" dangerouslySetInnerHTML={{ __html: html }} />
       <CodeCopy />
+      <LinkPreview />
     </>
   );
 }

package/template/lib/content/aliases.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { getAliasMap, resolveAlias, aliasUrl, resolveAliasUrl } from './aliases';
+import { getContentRegistry } from './registry';
+
+describe('alias parsing', () => {
+  // An author moving one page writes one path; requiring a list would be a
+  // rule to remember for no gain.
+  it('accepts a single alias or a list', () => {
+    const { docs } = getContentRegistry();
+
+    for (const doc of docs) {
+      expect(Array.isArray(doc.aliases)).toBe(true);
+    }
+  });
+
+  it('leaves documents without aliases empty', () => {
+    const { byPath } = getContentRegistry();
+
+    expect(byPath.get('intro')?.aliases).toEqual([]);
+  });
+});
+
+describe('getAliasMap', () => {
+  it('maps a former path to the document that superseded it', () => {
+    const map = getAliasMap();
+
+    for (const [alias, target] of map) {
+      expect(alias).not.toBe(target);
+      expect(getContentRegistry().byPath.has(target)).toBe(true);
+    }
+  });
+
+  // An alias shadowing a live page would make that page unreachable, so it is
+  // a build error rather than something resolved by precedence.
+  it('never claims a path a page occupies', () => {
+    const { byPath } = getContentRegistry();
+
+    for (const alias of getAliasMap().keys()) {
+      expect(byPath.has(alias)).toBe(false);
+    }
+  });
+});
+
+describe('aliasUrl', () => {
+  it('is the path itself under the path strategy', () => {
+    expect(aliasUrl('guides/setup', 'path')).toBe('guides/setup');
+  });
+
+  // The old URL under `hash` was the digest of the old path, so reproducing it
+  // is what makes the address a reader still has keep working.
+  it('is the digest of the path under the hash strategy', () => {
+    const url = aliasUrl('guides/setup', 'hash');
+
+    expect(url).toMatch(/^[0-9a-f]{8}-[0-9a-f]{8}-[0-9a-f]{8}$/);
+    expect(aliasUrl('guides/setup', 'hash')).toBe(url);
+    expect(aliasUrl('guides/other', 'hash')).not.toBe(url);
+  });
+
+  it('tolerates surrounding slashes', () => {
+    expect(aliasUrl('/guides/setup/', 'path')).toBe('guides/setup');
+  });
+});
+
+describe('resolveAliasUrl', () => {
+  it('resolves a former URL back to the current document under both strategies', () => {
+    for (const [alias, target] of getAliasMap()) {
+      expect(resolveAliasUrl(aliasUrl(alias, 'path'), 'path')).toBe(target);
+      expect(resolveAliasUrl(aliasUrl(alias, 'hash'), 'hash')).toBe(target);
+    }
+  });
+
+  it('resolves nothing for an address no page ever had', () => {
+    expect(resolveAliasUrl('never/existed', 'path')).toBeNull();
+    expect(resolveAlias('never/existed')).toBeNull();
+  });
+});

package/template/lib/content/aliases.ts

@@ -0,0 +1,114 @@
+import { getContentRegistry } from './registry';
+import { cached } from '../cache';
+import { normalizeSlug, type UrlStrategy } from '../navigation/url';
+import { generatePathHash } from '../navigation/hash';
+
+/**
+ * Former locations of documents, and where they now live.
+ *
+ * URLs are derived from content paths, so moving `guides/setup.md` to
+ * `getting-started/setup.md` changes the published URL and every link, bookmark
+ * and search result pointing at the old one stops working. Wiki links survive
+ * the move — they resolve by name — but nothing arriving from outside does.
+ * Declaring the old path in frontmatter keeps it answering.
+ *
+ * Server-only: reads the content registry.
+ */
+
+/** Alias content path mapped to the document that superseded it. */
+export type AliasMap = Map<string, string>;
+
+let memo: AliasMap | null = null;
+
+/**
+ * Builds the alias index.
+ *
+ * Two kinds of clash are refused rather than resolved. An alias naming a real
+ * page would shadow it, making a live document unreachable; an alias claimed by
+ * two documents has no answer, and picking either would send readers somewhere
+ * arbitrary. Both are mistakes in the content, and both are cheaper to find at
+ * build time than as a wrong page in production.
+ *
+ * @returns Old path to current path
+ * @throws Error when an alias shadows a page or is claimed twice
+ *
+ * @example
+ * ```typescript
+ * getAliasMap().get('guides/setup'); // 'getting-started/setup'
+ * ```
+ */
+export function getAliasMap(): AliasMap {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const { docs, byPath } = getContentRegistry();
+  const map: AliasMap = new Map();
+
+  for (const doc of docs) {
+    for (const alias of doc.aliases) {
+      if (byPath.has(alias)) {
+        throw new Error(
+          `Alias collision: '${alias}' in content/${doc.path}.md is also a page ` +
+            `(content/${alias}.md). An alias may only name a path no page occupies.`,
+        );
+      }
+
+      const claimed = map.get(alias);
+      if (claimed && claimed !== doc.path) {
+        throw new Error(
+          `Alias collision: '${alias}' is claimed by both content/${claimed}.md ` +
+            `and content/${doc.path}.md. Remove it from one of them.`,
+        );
+      }
+
+      map.set(alias, doc.path);
+    }
+  }
+
+  memo = map;
+  return memo;
+}
+
+/**
+ * Finds the document an old path now points to.
+ *
+ * @param path - Content path as it used to be written
+ * @returns The current content path, or null when nothing claims it
+ */
+export function resolveAlias(path: string): string | null {
+  return getAliasMap().get(path) ?? null;
+}
+
+/**
+ * The URL segment an alias answers on.
+ *
+ * Built with the same rule the live map uses, so the address a reader has
+ * really is the one that is served: under `path` the old content path, under
+ * `hash` the digest of it, which is exactly what the old URL was before the
+ * page moved.
+ *
+ * @param alias - Alias content path
+ * @param strategy - URL strategy in force
+ * @returns The segment, without leading or trailing slashes
+ */
+export function aliasUrl(alias: string, strategy: UrlStrategy): string {
+  const normalized = normalizeSlug(alias);
+  return strategy === 'hash' ? generatePathHash(normalized) : normalized;
+}
+
+/**
+ * Resolves a URL segment to the document that superseded it.
+ *
+ * @param url - URL segment as requested
+ * @param strategy - URL strategy in force
+ * @returns The current content path, or null when the segment is not an alias
+ */
+export function resolveAliasUrl(url: string, strategy: UrlStrategy): string | null {
+  const wanted = normalizeSlug(url);
+
+  for (const [alias, target] of getAliasMap()) {
+    if (aliasUrl(alias, strategy) === wanted) return target;
+  }
+
+  return null;
+}

package/template/lib/content/assets.ts

@@ -0,0 +1,158 @@
+import fs from 'fs';
+import path from 'path';
+import { cached } from '../cache';
+
+/**
+ * Index of the static files a page can embed.
+ *
+ * `![[diagram.png]]` names a file the way a vault does — by its name, with no
+ * path — because that is what an author remembers and what Obsidian accepts.
+ * Turning that into a URL means knowing every file under `public/`, so they are
+ * scanned once and indexed by both their full path and their bare filename.
+ *
+ * Server-only: reads the filesystem.
+ */
+
+/** Directory whose contents are served from the site root. */
+export const PUBLIC_DIR = path.join(process.cwd(), 'public');
+
+/**
+ * Directories under `public/` that hold generated or structural files rather
+ * than embeddable assets. Indexing them would let `![[search-index.json]]`
+ * resolve, which is never what an author meant.
+ */
+const SKIP_DIRS = new Set(['fonts']);
+
+/** Extensions an embed may point at. */
+const EMBEDDABLE = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.svg',
+  '.bmp',
+  '.ico',
+]);
+
+/** A file under `public/` that a page may embed. */
+export interface Asset {
+  /** Path relative to `public/`, e.g. 'images/docs/sample.jpg' */
+  path: string;
+  /** Root-relative URL, before the deployment base path is applied */
+  url: string;
+}
+
+/** Assets indexed for lookup. */
+export interface AssetRegistry {
+  /** Every embeddable asset found */
+  assets: Asset[];
+  /** By path relative to `public/`, lowercased */
+  byPath: Map<string, Asset>;
+  /** By bare filename, lowercased; several files may share one */
+  byName: Map<string, Asset[]>;
+}
+
+let memo: AssetRegistry | null = null;
+
+/**
+ * Collects embeddable files beneath a directory.
+ *
+ * @param dir - Directory to scan
+ * @param root - Directory that paths are made relative to
+ * @returns Paths relative to `root`, using forward slashes
+ */
+function walkAssets(dir: string, root: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+
+  const found: string[] = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (dir === root && SKIP_DIRS.has(entry.name)) continue;
+      found.push(...walkAssets(full, root));
+      continue;
+    }
+
+    if (!EMBEDDABLE.has(path.extname(entry.name).toLowerCase())) continue;
+
+    found.push(path.relative(root, full).split(path.sep).join('/'));
+  }
+
+  return found;
+}
+
+/**
+ * Scans `public/` and indexes what an embed may point at.
+ *
+ * Memoised for the process, like the content registry, and for the same
+ * reason: the files cannot change during a build.
+ *
+ * @returns The populated registry
+ *
+ * @example
+ * ```typescript
+ * const { byName } = getAssetRegistry();
+ * byName.get('sample.jpg')?.[0].url; // '/images/docs/sample.jpg'
+ * ```
+ */
+export function getAssetRegistry(): AssetRegistry {
+  const hit = cached(memo);
+  if (hit) return hit;
+
+  const assets: Asset[] = walkAssets(PUBLIC_DIR, PUBLIC_DIR).map((relative) => ({
+    path: relative,
+    url: `/${relative}`,
+  }));
+
+  const byPath = new Map(assets.map((asset) => [asset.path.toLowerCase(), asset]));
+  const byName = new Map<string, Asset[]>();
+
+  for (const asset of assets) {
+    const name = path.basename(asset.path).toLowerCase();
+    const existing = byName.get(name);
+    if (existing) existing.push(asset);
+    else byName.set(name, [asset]);
+  }
+
+  memo = { assets, byPath, byName };
+  return memo;
+}
+
+/**
+ * Resolves an embed target to a file under `public/`.
+ *
+ * A full path wins over a bare filename, so `![[icons/logo.svg]]` is
+ * unambiguous even when another `logo.svg` exists elsewhere. A bare name that
+ * matches more than one file resolves to nothing rather than guessing: picking
+ * whichever was scanned first would silently embed the wrong image, and the
+ * author would have no indication of it.
+ *
+ * @param target - Text between the brackets, e.g. 'sample.jpg'
+ * @returns The asset, or null when nothing or too much matches
+ *
+ * @example
+ * ```typescript
+ * resolveAsset('sample.jpg')?.url; // '/images/docs/sample.jpg'
+ * resolveAsset('/images/docs/sample.jpg')?.url; // '/images/docs/sample.jpg'
+ * ```
+ */
+export function resolveAsset(target: string): Asset | null {
+  const key = target.trim().replace(/^\/+/, '').toLowerCase();
+  if (!key) return null;
+
+  const { byPath, byName } = getAssetRegistry();
+
+  const exact = byPath.get(key);
+  if (exact) return exact;
+
+  const matches = byName.get(key);
+  if (matches?.length === 1) return matches[0];
+
+  return null;
+}

package/template/lib/content/excerpt.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { buildExcerpt, getExcerpt } from './excerpt';
+
+describe('buildExcerpt', () => {
+  it('prefers the description an author wrote', () => {
+    expect(buildExcerpt('# Title\n\nThe body.', 'A deliberate summary')).toBe(
+      'A deliberate summary',
+    );
+  });
+
+  it('falls back to the opening prose', () => {
+    expect(buildExcerpt('# Title\n\nThe first sentence.')).toBe('The first sentence.');
+  });
+
+  // The card shows the title on its own line, so repeating it as the summary
+  // would waste the space there is.
+  it('skips the title heading', () => {
+    expect(buildExcerpt('# Page Title\n\nBody text.')).not.toContain('Page Title');
+  });
+
+  it('skips code, rules and tables to reach the prose', () => {
+    const markdown = '# T\n\n```bash\nnpm install\n```\n\n---\n\nThe actual sentence.';
+
+    expect(buildExcerpt(markdown)).toBe('The actual sentence.');
+  });
+
+  // A page opening with a figure should preview as the sentence under it, not
+  // as the image's alt text.
+  it('leaves image alt text out', () => {
+    expect(buildExcerpt('# T\n\n![a diagram of the pipeline](/x.png)\n\nReal prose.')).toBe(
+      'Real prose.',
+    );
+  });
+
+  it('flattens inline markup and whitespace', () => {
+    expect(buildExcerpt('# T\n\nSome **bold**\nand `code` here.')).toBe('Some bold and code here.');
+  });
+
+  it('cuts at a word boundary rather than mid-word', () => {
+    const long = `# T\n\n${'alpha '.repeat(80)}`;
+    const excerpt = buildExcerpt(long);
+
+    expect(excerpt.endsWith('…')).toBe(true);
+    expect(excerpt).not.toMatch(/alph…$/);
+    expect(excerpt.length).toBeLessThanOrEqual(181);
+  });
+
+  it('returns nothing for a document with no prose', () => {
+    expect(buildExcerpt('# Only a title\n')).toBe('');
+  });
+});
+
+describe('getExcerpt', () => {
+  // `intro` is the one document both this repository and a freshly scaffolded
+  // project have, so this test travels with the engine rather than having to be
+  // held back from it.
+  it('summarises a document from the registry', () => {
+    expect(getExcerpt('intro').length).toBeGreaterThan(0);
+  });
+
+  it('returns the same summary on a repeat call', () => {
+    expect(getExcerpt('intro')).toBe(getExcerpt('intro'));
+  });
+
+  it('returns an empty summary for an unknown path', () => {
+    expect(getExcerpt('no/such/document')).toBe('');
+  });
+});