mordoc 0.1.13 → 1.0.0

package/src/app/not-found/NotFound.tsx

@@ -0,0 +1,34 @@
+/**
+ * Fallback route component for paths that don't match any page.
+ *
+ * Mirrors the article-column layout (same max-width, padding, and tokens as
+ * Content.tsx) so the 404 page feels like a natural part of the docs rather
+ * than an unstyled fallback. No TOC column — there's nothing to link to.
+ *
+ * On the client this is purely visual — CSR has no concept of an HTTP status
+ * code. The SSR/SSG steps also respond with an actual 404 status alongside
+ * rendering this component.
+ */
+
+import { Link, useLocation } from 'react-router';
+import { Footer } from '../footer/Footer.js';
+import styles from './NotFound.module.css';
+
+export function NotFound() {
+  const location = useLocation();
+  return (
+    <div className={styles.page}>
+      <div className={styles.articleArea}>
+        <div className={styles.article}>
+          <p className={styles.code404} aria-hidden="true">404</p>
+          <h1 className={styles.title}>Page not found</h1>
+          <p className={styles.description}>
+            No page exists at <code className={styles.path}>{location.pathname}</code>.
+          </p>
+          <Link to="/" className={styles.homeButton}>Go home</Link>
+        </div>
+      </div>
+      <Footer />
+    </div>
+  );
+}

package/src/app/routes.tsx

@@ -0,0 +1,86 @@
+import type { HydrationState, RouteObject } from 'react-router';
+import { createBrowserRouter } from 'react-router';
+import pagesIndex from 'virtual:mordoc/pages-index';
+import loaders from 'virtual:mordoc/page-loaders';
+import { App } from './App.js';
+import { Content } from './content/Content.js';
+import { LandingPage } from './landing/LandingPage.js';
+import { NotFound } from './not-found/NotFound.js';
+
+/**
+ * Builds the React Router route config from Mordoc's eager virtual
+ * modules.
+ *
+ * Shape: one root layout route (`App`) whose children are all known
+ * pages plus a catch-all `*` for 404s. Absolute child paths are used
+ * so each route's `path` matches its `PageMeta.routePath` identity
+ * verbatim — no slice/join tricks, easier to reason about.
+ *
+ * Each route's `loader` resolves the matching lazy
+ * `virtual:mordoc/page/<routePath>` module via the pre-built
+ * `page-loaders` map. The map is what lets Vite statically code-split:
+ * every specifier inside it is a literal `import("...")` string.
+ *
+ * The same loader function runs in three contexts; only the runtime
+ * resolving the dynamic `import('virtual:mordoc/page/...')` differs:
+ *   - Browser (CSR / post-hydration): native `import()` fetches the
+ *     lazy chunk over HTTP (Vite-served virtual in dev, hashed JS in
+ *     prod).
+ *   - Dev SSR: Vite's `ssrLoadModule` resolves it through the plugin's
+ *     `load` hook — the generated JS source is evaluated in Node.
+ *   - SSG (later step): the bundled SSR output's module map resolves
+ *     it at build time.
+ * The component code (`useLoaderData()`) and the data shape (`PageData`)
+ * are identical in all three; only the resolution mechanism changes.
+ *
+ * Kept as its own module so the SSR entry reuses the same route list
+ * against `createStaticHandler`/`createStaticRouter` without duplicating
+ * logic.
+ */
+export function buildRoutes(): RouteObject[] {
+  const pageRoutes: RouteObject[] = pagesIndex.map((pageIndex) => {
+    const pageLoader = loaders[pageIndex.routePath];
+    if (!pageLoader) {
+      // Defensive: the plugin emits `page-loaders` and `pages-index` from the
+      // same pipeline output, so they should always agree. A mismatch
+      // here means the eager modules went out of sync — surface it
+      // loudly at app bootstrap rather than during navigation.
+      throw new Error(
+        `mordoc: no page loader found for routePath "${pageIndex.routePath}". ` +
+          `virtual:mordoc/pages-index and virtual:mordoc/page-loaders are out of sync.`,
+      );
+    }
+    const common = {
+      loader: async () => (await pageLoader()).default,
+      Component: pageIndex.layout === 'landing' ? LandingPage : Content,
+      handle: { language: pageIndex.language, routePath: pageIndex.routePath, layout: pageIndex.layout ?? 'content' },
+    };
+    return pageIndex.routePath === '/'
+      ? { index: true, ...common }
+      : { path: pageIndex.routePath, ...common };
+  });
+
+  return [
+    {
+      path: '/',
+      Component: App,
+      HydrateFallback: () => null,
+      children: [...pageRoutes, { path: '*', Component: NotFound }],
+    },
+  ];
+}
+
+/**
+ * Creates the browser-side data router. Consumed by `main.tsx`.
+ *
+ * `hydrationData` should be passed when SSR has run for the initial
+ * request — `<StaticRouterProvider>` serializes the loaders' results
+ * into a `<script>` tag at render time, exposed on the client as
+ * `window.__staticRouterHydrationData`. Threading it through here lets
+ * the data router skip re-running the initial route's loader (which
+ * would otherwise re-fetch the same lazy chunk that already produced
+ * the SSR HTML).
+ */
+export function createAppRouter(hydrationData?: HydrationState) {
+  return createBrowserRouter(buildRoutes(), { hydrationData });
+}

package/src/app/sidenav/Sidenav.module.css

@@ -0,0 +1,239 @@
+/* ============================================================
+   SIDENAV TOKENS
+   ============================================================ */
+:root {
+  --sidebar-bg:             #FAFAFA;
+  --sidebar-fg:             #383838;
+  --sidebar-fg-muted:       #666666;
+  --sidebar-border:         #E5E5E5;
+  --sidebar-accent:         #EFEFEF;
+  --sidebar-accent-fg:      #1C1C1C;
+  --sidebar-group-label-fg: rgba(56, 56, 56, 0.7);
+  --sidebar-gap-y:          4px;
+  --sidebar-item-h:         36px;
+  --sidebar-group-h:        36px;
+  --sidebar-pad-x:          8px;
+  --sidebar-pad-y:          16px;
+  --sidebar-item-pad-x:     8px;
+  --sidebar-item-pad-y:     6px;
+}
+
+:global(.dark) {
+  --sidebar-bg:             #0F0F0F;
+  --sidebar-fg:             #D6D6D6;
+  --sidebar-fg-muted:       #9E9E9E;
+  --sidebar-border:         #292929;
+  --sidebar-accent:         #1F1F1F;
+  --sidebar-accent-fg:      #EBEBEB;
+  --sidebar-group-label-fg: rgba(214, 214, 214, 0.7);
+}
+
+/* ============================================================
+   SIDENAV — inner content only
+   Geometry (position / width / height / overflow) lives in App.module.css
+   ============================================================ */
+
+.sidenav {
+  padding: var(--sidebar-pad-y) var(--sidebar-pad-x);
+}
+
+/* ── Menu list ───────────────────────────────────────────────── */
+
+.menu {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  width: 100%;
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+/* ── Menu item wrapper ───────────────────────────────────────── */
+
+.menuItem {
+  width: 100%;
+}
+
+/* ============================================================
+   GROUP VARIANT 1 — non-linked trigger (no path, toggles whole row)
+   ============================================================ */
+
+.groupLabelTrigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  min-height: var(--sidebar-group-h);
+  padding: var(--sidebar-item-pad-y) var(--sidebar-item-pad-x);
+  margin-top: 10px;
+  border-radius: var(--radius-md);
+  background: none;
+  border: none;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.25;
+  letter-spacing: 0;
+  color: var(--sidebar-group-label-fg);
+  font-family: var(--font-sans);
+  cursor: pointer;
+  text-align: left;
+  transition: color 150ms ease, background-color 150ms ease;
+}
+
+.menuItem:first-child > .groupLabelTrigger {
+  margin-top: 0;
+}
+
+.groupLabelTrigger:hover {
+  background: var(--sidebar-accent);
+}
+
+.groupLabelText {
+  flex: 1;
+}
+
+/* ============================================================
+   GROUP VARIANT 2 — linked group label (whole row is one element)
+   ============================================================ */
+
+.linkedGroupLabel {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  width: 100%;
+  min-height: var(--sidebar-group-h);
+  padding: var(--sidebar-item-pad-y) var(--sidebar-item-pad-x);
+  border-radius: var(--radius-md);
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 1.25;
+  color: var(--sidebar-fg);
+  text-decoration: none;
+  cursor: pointer;
+  margin-top: 10px;
+  transition: color 150ms ease, background-color 150ms ease;
+}
+
+.menuItem:first-child > .linkedGroupLabel {
+  margin-top: 0;
+}
+
+.linkedGroupLabel:hover {
+  background: var(--sidebar-accent);
+}
+
+.linkedGroupLabel.linkActive {
+  color: var(--accent-emphasis);
+  background: var(--accent-subtle);
+}
+
+/* ============================================================
+   TOP-LEVEL LEAF LINK (depth=0, no children)
+   Matches group-label height/weight for visual consistency
+   ============================================================ */
+
+.topLink {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  min-height: var(--sidebar-group-h);
+  padding: var(--sidebar-item-pad-y) var(--sidebar-item-pad-x);
+  border-radius: var(--radius-md);
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 1.25;
+  color: var(--sidebar-fg);
+  text-decoration: none;
+  transition: color 150ms ease, background-color 150ms ease;
+}
+
+.topLink:hover {
+  background: var(--sidebar-accent);
+}
+
+.topLink.topLinkActive {
+  background: var(--accent-subtle);
+  color: var(--accent-emphasis);
+  font-weight: 600;
+}
+
+/* ============================================================
+   NESTED LEAF LINK (depth>0)
+   Indented under a group, lighter weight
+   ============================================================ */
+
+.navLink {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  min-height: var(--sidebar-item-h);
+  padding: var(--sidebar-item-pad-y) 8px var(--sidebar-item-pad-y) 24px;
+  border-radius: var(--radius-md);
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 1.4;
+  color: var(--sidebar-fg);
+  text-decoration: none;
+  transition: color 150ms ease, background-color 150ms ease;
+}
+
+.navLink:hover {
+  background: var(--sidebar-accent);
+}
+
+.navLink.navLinkActive {
+  background: var(--accent-subtle);
+  color: var(--accent-emphasis);
+  font-weight: 500;
+}
+
+/* ============================================================
+   GROUP CONTENT AREA — slight breathing room under label
+   ============================================================ */
+
+.groupContent {
+  padding-top: 4px;
+}
+
+/* ============================================================
+   CHEVRON ICON
+   ============================================================ */
+
+.chevron {
+  flex-shrink: 0;
+  color: var(--sidebar-fg-muted);
+  transition: transform 200ms ease;
+}
+
+.chevronOpen {
+  transform: rotate(180deg);
+}
+
+/* ============================================================
+   FOCUS STATES
+   ============================================================ */
+
+.groupLabelTrigger:focus-visible,
+.linkedGroupLabel:focus-visible,
+.navLink:focus-visible,
+.topLink:focus-visible {
+  outline: 2px solid var(--accent-emphasis);
+  outline-offset: -2px;
+  border-radius: var(--radius-md);
+}
+
+/* ============================================================
+   REDUCED MOTION
+   ============================================================ */
+
+@media (prefers-reduced-motion: reduce) {
+  .groupLabelTrigger,
+  .linkedGroupLabel,
+  .navLink,
+  .topLink,
+  .chevron {
+    transition: none !important;
+  }
+}

package/src/app/sidenav/Sidenav.tsx

@@ -0,0 +1,182 @@
+import React, { useState } from 'react';
+import { NavLink, useLocation, useNavigate } from 'react-router';
+import { useMordocData } from '../data-context.js';
+import { detectCurrentLang, buildLangPrefix, stripLangPrefix, resolveLabel } from '../lang-utils.js';
+import type { SidenavConfig, SidenavItem } from '../../types/navigation.js';
+import styles from './Sidenav.module.css';
+
+function ChevronIcon({ open }: { open: boolean }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={`${styles.chevron} ${open ? styles.chevronOpen : ''}`}
+    >
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
+function groupContainsActive(items: SidenavConfig, activePath: string): boolean {
+  return items.some(
+    (item) =>
+      (item.path !== undefined && item.path === activePath) ||
+      (item.children !== undefined && groupContainsActive(item.children, activePath)),
+  );
+}
+
+function SidenavList({ items, depth = 0 }: { items: SidenavConfig; depth?: number }) {
+  return (
+    <ul className={styles.menu}>
+      {items.map((item, i) => (
+        <SidenavNode key={i} item={item} depth={depth} />
+      ))}
+    </ul>
+  );
+}
+
+function SidenavNode({ item, depth }: { item: SidenavItem; depth: number }) {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const isGroupActive = item.children
+    ? groupContainsActive(item.children, location.pathname)
+    : false;
+  const isLabelActive = item.path ? location.pathname === item.path : false;
+  const [open, setOpen] = useState(isGroupActive || isLabelActive);
+
+  // Leaf item — path only, no children
+  if (item.path && !item.children) {
+    const isTop = depth === 0;
+    return (
+      <li className={styles.menuItem}>
+        <NavLink
+          to={item.path}
+          end
+          className={({ isActive }) =>
+            isTop
+              ? `${styles.topLink}${isActive ? ` ${styles.topLinkActive}` : ''}`
+              : `${styles.navLink}${isActive ? ` ${styles.navLinkActive}` : ''}`
+          }
+        >
+          {item.label}
+        </NavLink>
+      </li>
+    );
+  }
+
+  // Variant 2 — linked group: whole row navigates + toggles as one unit
+  if (item.path && item.children) {
+    function handleLinkedGroupClick(e: React.MouseEvent<HTMLAnchorElement>) {
+      e.preventDefault();
+      if (isLabelActive && open) {
+        setOpen(false);
+      } else {
+        setOpen(true);
+        if (!isLabelActive) navigate(item.path!);
+      }
+    }
+
+    return (
+      <li className={styles.menuItem}>
+        <a
+          href={item.path}
+          onClick={handleLinkedGroupClick}
+          aria-expanded={open}
+          className={isLabelActive ? `${styles.linkedGroupLabel} ${styles.linkActive}` : styles.linkedGroupLabel}
+        >
+          <span>{item.label}</span>
+          <ChevronIcon open={open} />
+        </a>
+        {open && (
+          <div className={styles.groupContent}>
+            <SidenavList items={item.children} depth={depth + 1} />
+          </div>
+        )}
+      </li>
+    );
+  }
+
+  // Variant 1 — non-linked group label, whole row toggles
+  return (
+    <li className={styles.menuItem}>
+      <button
+        className={styles.groupLabelTrigger}
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+      >
+        <span className={styles.groupLabelText}>{item.label}</span>
+        <ChevronIcon open={open} />
+      </button>
+      {open && item.children && (
+        <div className={styles.groupContent}>
+          <SidenavList items={item.children} depth={depth + 1} />
+        </div>
+      )}
+    </li>
+  );
+}
+
+function applyLangToSidenav(
+  items: SidenavConfig,
+  prefix: string,
+  lang: string,
+  defaultLanguage: string,
+  translations: Record<string, Record<string, string>>,
+): SidenavConfig {
+  return items.map((item) => ({
+    ...item,
+    label: resolveLabel(item.label, lang, defaultLanguage, translations),
+    path: item.path !== undefined ? `${prefix}${item.path}` : undefined,
+    children: item.children
+      ? applyLangToSidenav(item.children, prefix, lang, defaultLanguage, translations)
+      : undefined,
+  }));
+}
+
+function resolveActiveSidenav(
+  navigation: ReturnType<typeof useMordocData>['navigation'],
+  contentPath: string,
+): SidenavConfig {
+  if (navigation.kind === 'sidenav') return navigation.sidenav;
+
+  const match = navigation.topnav
+    .filter((item) => contentPath === item.path || contentPath.startsWith(item.path + '/'))
+    .sort((a, b) => b.path.length - a.path.length)[0];
+
+  return match?.sidenav ?? [];
+}
+
+export function Sidenav() {
+  const { navigation, language, site, translations } = useMordocData();
+  const { pathname } = useLocation();
+
+  const currentLang = detectCurrentLang(pathname, language, site.defaultLanguage);
+  const contentPath = stripLangPrefix(pathname, currentLang, site.defaultLanguage);
+  const sidenav = resolveActiveSidenav(navigation, contentPath);
+
+  if (sidenav.length === 0) {
+    return <nav className={styles.sidenav} aria-label="Side navigation" />;
+  }
+
+  const prefix = buildLangPrefix(currentLang, site.defaultLanguage);
+  const processedSidenav = applyLangToSidenav(
+    sidenav,
+    prefix,
+    currentLang,
+    site.defaultLanguage,
+    translations,
+  );
+
+  return (
+    <nav className={styles.sidenav} aria-label="Side navigation">
+      <SidenavList items={processedSidenav} depth={0} />
+    </nav>
+  );
+}

package/src/app/skeleton/Skeleton.module.css

@@ -0,0 +1,100 @@
+/* ── Shimmer keyframe ────────────────────────────────────────── */
+
+@keyframes shimmer {
+  0%   { background-position: -600px 0; }
+  100% { background-position:  600px 0; }
+}
+
+/* ── Page shell — exact grid match to Content.module.css ────── */
+
+/* Must use the same grid-template-columns as contentAreaGrid so that
+   the 1fr content column is the same width, keeping margin: 0 auto
+   centering identical between skeleton and real article. */
+.page {
+  display: grid;
+  grid-template-columns: 1fr var(--toc-width);
+  grid-template-areas: "content toc";
+  min-height: calc(100svh - var(--header-total));
+}
+
+.articleArea {
+  grid-area: content;
+  min-width: 0;
+}
+
+.article {
+  max-width: var(--content-max-width);
+  width: 100%;
+  margin: 0 auto;
+  padding: 3rem 1.5rem;
+}
+
+@media (min-width: 768px) {
+  .article {
+    padding: 3rem 2rem;
+  }
+}
+
+/* Matches Content.module.css responsive collapse — TOC column disappears
+   below xl, so the content column becomes full width in both cases. */
+@media (max-width: 1279.98px) {
+  .page {
+    grid-template-columns: 1fr;
+    grid-template-areas: "content";
+  }
+}
+
+/* ── Shimmer block — base primitive ─────────────────────────── */
+
+/* Highlight travels from left to right using background-position.
+   background-size is fixed-pixel so the sweep width is constant
+   regardless of the block's rendered width. */
+.block {
+  border-radius: var(--radius-sm);
+  background-image: linear-gradient(
+    90deg,
+    var(--color-surface)  0px,
+    var(--color-border)  80px,
+    var(--color-surface) 160px
+  );
+  background-size: 600px 100%;
+  animation: shimmer 1.6s linear infinite;
+}
+
+/* ── Section layout ──────────────────────────────────────────── */
+
+.breadcrumbRow {
+  margin-bottom: 1.25rem;
+}
+
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  margin-bottom: 2.5rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.headerDesc {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+}
+
+.prose {
+  display: flex;
+  flex-direction: column;
+}
+
+.paraGroup {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin-bottom: 1.25rem;
+}
+
+.heading {
+  margin-bottom: 1rem;
+}