mordoc 0.1.13 → 1.0.0

package/src/app/content/image/Image.tsx

@@ -0,0 +1,98 @@
+/**
+ * Image — inline content image with a lightbox popup.
+ *
+ * Renders a styled <figure> inline; clicking it opens a full-screen overlay
+ * via a React portal mounted on document.body. The portal approach avoids
+ * z-index stacking context fights with the fixed header and sidebar.
+ *
+ * SSR safety: the portal is only rendered when `isOpen` is true, which starts
+ * as false — so document.body is never accessed during server-side rendering.
+ *
+ * Wired via the `image` node override in markdoc-config.ts, registered in
+ * Content.tsx's components map.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+import styles from './Image.module.css';
+
+interface ImageProps {
+  src: string;
+  alt?: string;
+  title?: string;
+}
+
+export function Image({ src, alt = '', title }: ImageProps) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const open = () => setIsOpen(true);
+
+  const close = useCallback(() => setIsOpen(false), []);
+
+  // Escape key closes the lightbox; body scroll is locked while open
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') close();
+    };
+
+    document.body.style.overflow = 'hidden';
+    window.addEventListener('keydown', handleKey);
+
+    return () => {
+      document.body.style.overflow = '';
+      window.removeEventListener('keydown', handleKey);
+    };
+  }, [isOpen, close]);
+
+  const lightbox = (
+    <div
+      className={styles.overlay}
+      onClick={close}
+      role="dialog"
+      aria-modal="true"
+      aria-label={alt || 'Image preview'}
+    >
+      <button
+        className={styles.closeButton}
+        onClick={close}
+        aria-label="Close image preview"
+        type="button"
+      >
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+          <path d="M18 6L6 18M6 6L18 18" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      </button>
+
+      <div
+        className={styles.lightboxImageWrap}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <img
+          src={src}
+          alt={alt}
+          className={styles.lightboxImage}
+        />
+        {title && <p className={styles.lightboxCaption}>{title}</p>}
+      </div>
+    </div>
+  );
+
+  return (
+    <>
+      <figure className={styles.figure} onClick={open}>
+        <img
+          src={src}
+          alt={alt}
+          className={styles.image}
+        />
+        {title && <figcaption className={styles.caption}>{title}</figcaption>}
+      </figure>
+
+      {isOpen && createPortal(lightbox, document.body)}
+    </>
+  );
+}
+
+export default Image;

package/src/app/content/link/ContentLink.tsx

@@ -0,0 +1,46 @@
+/**
+ * ContentLink — SPA-aware link component for Markdoc-rendered prose.
+ *
+ * Replaces Markdoc's default `<a>` output so that internal route links use
+ * React Router's <Link> (client-side navigation, no page reload) while
+ * external URLs open in a new tab. Anchor-only links (#heading) are left as
+ * plain <a> elements — they are in-page scrolls and do not involve routing.
+ *
+ * Registered as a custom Markdoc `link` node in markdoc-config.ts and wired
+ * into the components map in Content.tsx and LandingPage.tsx.
+ */
+
+import { Link } from 'react-router';
+import React from 'react';
+
+interface ContentLinkProps {
+  href: string;
+  title?: string;
+  children?: React.ReactNode;
+}
+
+function isExternal(href: string) {
+  return href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//');
+}
+
+export function ContentLink({ href, title, children }: ContentLinkProps) {
+  if (href.startsWith('#')) {
+    return <a href={href} title={title}>{children}</a>;
+  }
+
+  if (isExternal(href)) {
+    return (
+      <a href={href} title={title} target="_blank" rel="noopener noreferrer">
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <Link to={href} title={title}>
+      {children}
+    </Link>
+  );
+}
+
+export default ContentLink;

package/src/app/data-context.tsx

@@ -0,0 +1,39 @@
+import { createContext, useContext } from 'react';
+import type { ShellData } from '../types/pipeline.js';
+
+/**
+ * React context carrying the site-wide `ShellData` projection.
+ *
+ * This context is the single channel by which shell components read the
+ * configs, navigation, and route index. The browser entry (`main.tsx`)
+ * assembles the value from the eager `virtual:mordoc/*` modules; the
+ * server entry (`entry-server.tsx`) receives it as the `data` parameter
+ * of `render()`. Both then wrap the React tree in this provider, which
+ * is what makes the same component code (`App`, `Page`, future theme
+ * components) work identically under CSR and SSR.
+ *
+ * The default value is `null` so that any component reading the context
+ * outside a provider trips a clear runtime error in `useMordocData()`,
+ * rather than silently rendering against an empty object.
+ */
+export const MordocDataContext = createContext<ShellData | null>(null);
+
+/**
+ * Hook for shell components to read the current `ShellData`.
+ *
+ * Throws if called outside a `<MordocDataContext.Provider>`. Both
+ * entry points (`main.tsx`, `entry-server.tsx`) wrap their entire tree
+ * in the provider, so a missing-provider error means a regression in
+ * the entry wiring — surface it loudly rather than letting components
+ * read `null` and crash deeper.
+ */
+export function useMordocData(): ShellData {
+  const value = useContext(MordocDataContext);
+  if (value === null) {
+    throw new Error(
+      'mordoc: useMordocData() called outside <MordocDataContext.Provider>. ' +
+        'Both main.tsx and entry-server.tsx must wrap the React tree in the provider.',
+    );
+  }
+  return value;
+}

package/src/app/entry-server.tsx

@@ -0,0 +1,58 @@
+import { StrictMode } from 'react';
+import { renderToString } from 'react-dom/server';
+import {
+  createStaticHandler,
+  createStaticRouter,
+  StaticRouterProvider,
+} from 'react-router';
+import type { ShellData } from '../types/pipeline.js';
+import { MordocDataContext } from './data-context.js';
+import { buildRoutes } from './routes.js';
+
+/**
+ * Renders a single route to an HTML string for SSG.
+ *
+ * Called once per route by the SSG runner at build time. Pure function —
+ * no Vite, no I/O. The SSG runner synthesises a `Request` for each route
+ * path, loads this module from the bundled SSR output, and calls `render()`.
+ *
+ * The flow:
+ *   1. Build the route list (shared with the browser entry via `buildRoutes`).
+ *   2. `createStaticHandler.query(request)` runs the matched route's loader,
+ *      which imports the lazy `virtual:mordoc/page/...` module — resolved by
+ *      the Vite plugin and bundled into the SSR output.
+ *   3. `createStaticRouter` + `<StaticRouterProvider>` render the matched
+ *      component tree to a string.
+ *   4. The tree is wrapped in `MordocDataContext.Provider` and `StrictMode`
+ *      to mirror `main.tsx` — divergence here causes hydration mismatches.
+ *
+ * If the static handler returns a `Response` (e.g. a redirect from a loader),
+ * this function throws — redirect handling is not yet supported.
+ */
+export async function render(
+  request: Request,
+  data: ShellData,
+): Promise<{ html: string }> {
+  const routes = buildRoutes();
+  const handler = createStaticHandler(routes);
+  const context = await handler.query(request);
+
+  if (context instanceof Response) {
+    throw new Error(
+      `mordoc render: static handler returned Response (status ${context.status}). ` +
+        'Redirects/responses from loaders are not yet supported in the SSR path.',
+    );
+  }
+
+  const router = createStaticRouter(routes, context);
+
+  const html = renderToString(
+    <StrictMode>
+      <MordocDataContext.Provider value={data}>
+        <StaticRouterProvider router={router} context={context} />
+      </MordocDataContext.Provider>
+    </StrictMode>,
+  );
+
+  return { html };
+}

package/src/app/footer/Footer.module.css

@@ -0,0 +1,36 @@
+.footer {
+  max-width: var(--content-max-width);
+  width: 100%;
+  margin: 0 auto;
+  padding: 0 1.5rem 2rem;
+  background: var(--color-bg);
+  font-size: 0.875rem;
+  color: var(--color-fg-muted);
+}
+
+@media (min-width: 768px) {
+  .footer {
+    padding-left: 2rem;
+    padding-right: 2rem;
+  }
+}
+
+.inner {
+  border-top: 1px solid var(--color-border);
+  padding-top: 2rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.link {
+  color: var(--accent-emphasis);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-color: transparent;
+  transition: text-decoration-color 0.15s;
+}
+
+.link:hover {
+  text-decoration-color: var(--accent-emphasis);
+}

package/src/app/footer/Footer.tsx

@@ -0,0 +1,28 @@
+import { useMordocData } from '../data-context.js';
+import styles from './Footer.module.css';
+
+export function Footer() {
+  const { site } = useMordocData();
+  const year = new Date().getFullYear();
+
+  return (
+    <footer className={styles.footer} data-pagefind-ignore>
+      <div className={styles.inner}>
+        <span className={styles.copy}>
+          © {year} {site.name}
+        </span>
+        <span className={styles.built}>
+          Built with{' '}
+          <a
+            href="https://mordoc.dev"
+            target="_blank"
+            rel="noopener noreferrer"
+            className={styles.link}
+          >
+            Mordoc
+          </a>
+        </span>
+      </div>
+    </footer>
+  );
+}

package/src/app/globals.d.ts

@@ -0,0 +1,40 @@
+// Ambient declarations for browser-side globals. This file must remain a
+// script (no top-level import/export) so that wildcard declare module
+// statements are picked up by the TS language server.
+
+// Dynamic import types are allowed in ambient script files since TS 2.9,
+// so no export {} needed to use import('...') syntax below.
+
+interface Window {
+  __staticRouterHydrationData?: import('react-router').HydrationState;
+}
+
+/** Shape of a single result returned by pagefind.search(). */
+interface PagefindSearchResult {
+  id: string;
+  data: () => Promise<PagefindSearchResultData>;
+}
+
+interface PagefindSearchResultData {
+  url: string;
+  excerpt: string;
+  meta: { title?: string; [key: string]: string | undefined };
+}
+
+/** Shape of the dynamically-imported Pagefind browser bundle (/pagefind[-lang]/pagefind.js). */
+interface PagefindAPI {
+  init?: () => Promise<void>;
+  search: (query: string) => Promise<{ results: PagefindSearchResult[] }>;
+  /** Releases index memory. Call before switching to a different language index. */
+  destroy?: () => Promise<void>;
+}
+
+declare module '*.css' {                                                                                                                                                                 
+  const styles: Record<string, string>;                                                                                                                                                  
+  export default styles;                                                                                                                                                                 
+}    
+
+declare module '*.module.css' {
+  const styles: Record<string, string>;
+  export default styles;
+}

package/src/app/header/Header.module.css

@@ -0,0 +1,205 @@
+/* ============================================================
+   HEADER TOKENS
+   ============================================================ */
+:root {
+  --header-px:        16px;
+  --header-gap:       12px;
+  --actions-gap:      4px;
+  --brand-gap:        8px;
+  --brand-logo-size:  28px;
+  --brand-logo-radius: 6px;
+  --menu-btn-size:    36px;
+  --menu-btn-radius:  6px;
+  --menu-btn-icon:    20px;
+  --toggle-size:      40px;
+  --toggle-radius:    8px;
+  --toggle-icon-size: 20px;
+  --toggle-bg:        #ffffff;
+  --toggle-bg-hover:  #f5f5f5;
+  --toggle-border:    #e5e5e5;
+  --toggle-fg:        #1c1c1c;
+}
+
+:global(.dark) {
+  --toggle-bg:       #1a1a1a;
+  --toggle-bg-hover: #242424;
+  --toggle-border:   #2e2e2e;
+  --toggle-fg:       #ebebeb;
+}
+
+@media (max-width: 479px) {
+  :root {
+    --header-gap:       8px;
+    --actions-gap:      2px;
+    --toggle-size:      36px;
+    --toggle-icon-size: 18px;
+  }
+}
+
+@media (min-width: 768px) {
+  :root {
+    --header-gap: 16px;
+  }
+}
+
+@media (min-width: 1024px) {
+  :root {
+    --header-gap: 20px;
+  }
+}
+
+@media (min-width: 1280px) {
+  :root {
+    --header-gap: 24px;
+  }
+}
+
+/* Aesthetic + internal layout only.
+   Structural placement (position: sticky, z-index, height) lives in App.module.css .headerArea */
+.header {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  background: var(--color-header-bg);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  border-bottom: 1px solid var(--color-border);
+}
+
+/* ── Top bar ────────────────────────────────────────────── */
+.inner {
+  width: 100%;
+  height: var(--header-height);
+  padding: 0 var(--header-px);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--header-gap);
+}
+
+/* Three regions */
+.brand {
+  display: flex;
+  align-items: center;
+  gap: var(--brand-gap);
+  flex-shrink: 0;
+}
+
+.search {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--actions-gap);
+  flex-shrink: 0;
+}
+
+/* ── Logo / brand link ──────────────────────────────────── */
+.logo {
+  display: flex;
+  align-items: center;
+  text-decoration: none;
+  color: inherit;
+  flex-shrink: 0;
+  border-radius: var(--brand-logo-radius);
+}
+
+.logoImage {
+  height: var(--brand-logo-size);
+  width: auto;
+}
+
+.logoText {
+  font-weight: 700;
+  font-size: 1.25rem;
+  white-space: nowrap;
+  letter-spacing: -0.01em;
+}
+
+/* ── Hamburger ──────────────────────────────────────────── */
+.menuBtn {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--menu-btn-size);
+  height: var(--menu-btn-size);
+  border: 0;
+  background: transparent;
+  border-radius: var(--menu-btn-radius);
+  color: inherit;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: background 0.15s;
+}
+
+.menuBtn:hover {
+  background: var(--lang-bg-hover);
+}
+
+.menuBtn:focus-visible {
+  outline: 2px solid var(--accent-emphasis);
+  outline-offset: 2px;
+}
+
+/* ── Theme toggle ───────────────────────────────────────── */
+.themeToggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--toggle-size);
+  height: var(--toggle-size);
+  background: var(--toggle-bg);
+  color: var(--toggle-fg);
+  border: 1px solid var(--toggle-border);
+  border-radius: var(--toggle-radius);
+  cursor: pointer;
+  transition: background 0.2s, border-color 0.2s;
+}
+
+.themeToggle:hover {
+  background: var(--toggle-bg-hover);
+}
+
+.themeToggle:focus-visible {
+  outline: 2px solid var(--accent-emphasis);
+  outline-offset: 2px;
+}
+
+/* ── Topnav second row ──────────────────────────────────── */
+.topnavRow {
+  width: 100%;
+  height: 2.75rem;
+  padding: 0 var(--header-px);
+  display: flex;
+  align-items: stretch;
+}
+
+/* ── Focus ring on logo ─────────────────────────────────── */
+.logo:focus-visible {
+  outline: 2px solid var(--accent-emphasis);
+  outline-offset: 2px;
+}
+
+/* ════════════════════════════════════════════════════════════
+   Responsive
+   ════════════════════════════════════════════════════════════ */
+
+/* < 768px: hamburger visible, search + topnav row hidden */
+@media (max-width: 767.98px) {
+  .menuBtn {
+    display: inline-flex;
+  }
+
+  .search {
+    display: none;
+  }
+
+  .topnavRow {
+    display: none;
+  }
+}