mordoc 0.1.13 → 1.0.0

package/src/app/content/Content.tsx

@@ -0,0 +1,212 @@
+import { useEffect } from 'react';
+import { Link, useLoaderData, useLocation } from 'react-router';
+import React from 'react';
+import Markdoc from '@markdoc/markdoc';
+import { useMordocData } from '../data-context.js';
+import { Toc } from '../toc/Toc.js';
+import { Footer } from '../footer/Footer.js';
+import { detectCurrentLang, buildLangPrefix, stripLangPrefix, resolveLabel } from '../lang-utils.js';
+import type { PageData } from '../../types/content.js';
+import type { SidenavConfig } from '../../types/navigation.js';
+import { CodeBlock } from './code-block/CodeBlock.js';
+import { Image } from './image/Image.js';
+import { Callout } from './callout/Callout.js';
+import { Card } from './card/Card.js';
+import { CardGrid } from './card/CardGrid.js';
+import { ContentLink } from './link/ContentLink.js';
+import { Heading } from './heading/Heading.js';
+import { Button } from '../landing/button/Button.js';
+import styles from './Content.module.css';
+
+/**
+ * Renders a single content page.
+ *
+ * The route's `loader` has already resolved the lazy
+ * `virtual:mordoc/page/<routePath>` module, so `useLoaderData()` returns
+ * the full `PageData` synchronously at render time.
+ *
+ * CJS interop: `@markdoc/markdoc` is CommonJS; the default-import shape
+ * is required. Destructured named imports like `{ renderers }` fail at
+ * runtime under Node/Vite's ESM loader even though the `.d.ts` permits
+ * them. Same rule as `markdoc-config.ts` on the Node side.
+ */
+
+interface BreadcrumbEntry {
+  label: string;
+  path?: string;
+}
+
+function findBreadcrumb(
+  items: SidenavConfig,
+  targetPath: string,
+  ancestors: BreadcrumbEntry[],
+): BreadcrumbEntry[] | null {
+  for (const item of items) {
+    const current: BreadcrumbEntry = { label: item.label, path: item.path };
+    if (item.path === targetPath) {
+      return [...ancestors, current];
+    }
+    if (item.children) {
+      const found = findBreadcrumb(item.children, targetPath, [...ancestors, current]);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function resolveActiveSidenavRaw(
+  navigation: ReturnType<typeof useMordocData>['navigation'],
+  contentPath: string,
+): { sectionLabel: string | null; sectionPath: string | null; sidenav: SidenavConfig } {
+  if (navigation.kind === 'sidenav') {
+    return { sectionLabel: null, sectionPath: null, sidenav: 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 {
+    sectionLabel: match?.label ?? null,
+    sectionPath: match?.path ?? null,
+    sidenav: match?.sidenav ?? [],
+  };
+}
+
+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 estimateReadTime(renderable: unknown): number {
+  const text = JSON.stringify(renderable);
+  const wordCount = text.split(/\s+/).length;
+  return Math.max(1, Math.round(wordCount / 200));
+}
+
+function BreadcrumbSep() {
+  return (
+    <span className={styles.breadcrumbSep} aria-hidden="true">
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="m9 18 6-6-6-6" />
+      </svg>
+    </span>
+  );
+}
+
+function Breadcrumb({ entries }: { entries: BreadcrumbEntry[] }) {
+  if (entries.length === 0) return null;
+  const lastIndex = entries.length - 1;
+  return (
+    <nav className={styles.breadcrumb} aria-label="Breadcrumb">
+      {entries.map((entry, i) => {
+        const isCurrent = i === lastIndex;
+        const isLink = !isCurrent && entry.path !== undefined;
+        return (
+          <span key={i} className={styles.breadcrumbItem}>
+            {i > 0 && <BreadcrumbSep />}
+            {isCurrent ? (
+              <span className={styles.breadcrumbCurrent} aria-current="page">
+                {entry.label}
+              </span>
+            ) : isLink ? (
+              <Link to={entry.path!} className={styles.breadcrumbLink}>
+                {entry.label}
+              </Link>
+            ) : (
+              <span className={styles.breadcrumbMuted}>{entry.label}</span>
+            )}
+          </span>
+        );
+      })}
+    </nav>
+  );
+}
+
+export function Content() {
+  const pageData = useLoaderData() as PageData;
+  const { site, navigation, language, translations } = useMordocData();
+  const { pathname } = useLocation();
+
+  const currentLang = detectCurrentLang(pathname, language, site.defaultLanguage);
+  const contentPath = stripLangPrefix(pathname, currentLang, site.defaultLanguage);
+  const prefix = buildLangPrefix(currentLang, site.defaultLanguage);
+
+  const { sectionLabel, sectionPath, sidenav } = resolveActiveSidenavRaw(navigation, contentPath);
+  const processedSidenav = applyLangToSidenav(sidenav, prefix, currentLang, site.defaultLanguage, translations);
+
+  const rawBreadcrumb = findBreadcrumb(processedSidenav, pathname, []) ?? [];
+  const resolvedSectionLabel = sectionLabel
+    ? resolveLabel(sectionLabel, currentLang, site.defaultLanguage, translations)
+    : null;
+  const breadcrumb: BreadcrumbEntry[] = [
+    { label: 'Home', path: prefix || '/' },
+    ...(resolvedSectionLabel && sectionPath
+      ? [{ label: resolvedSectionLabel, path: `${prefix}${sectionPath}` }]
+      : []),
+    ...rawBreadcrumb,
+  ];
+
+  const readTime = estimateReadTime(pageData.renderable);
+
+  useEffect(() => {
+    const pageTitle = pageData.frontmatter.title;
+    document.title = pageTitle ? `${pageTitle} — ${site.name}` : site.name;
+  }, [pageData.frontmatter.title, site.name]);
+
+  const rendered = Markdoc.renderers.react(pageData.renderable, React, {
+    components: { CodeBlock, Image, Callout, Card, CardGrid, ContentLink, Heading, Button },
+  });
+
+  return (
+    <div className={styles.contentAreaGrid}>
+      {/* Article area */}
+      <div className={styles.articleArea}>
+        <article className={styles.article} data-pagefind-body>
+          <div className={styles.articleMeta} data-pagefind-ignore>
+            <Breadcrumb entries={breadcrumb} />
+          </div>
+          <header className={styles.articleHeader}>
+            <h1 className={styles.title} data-pagefind-meta="title">{pageData.frontmatter.title}</h1>
+            {typeof pageData.frontmatter.description === 'string' && (
+              <p className={styles.description}>{pageData.frontmatter.description}</p>
+            )}
+            <div className={styles.metaRow} data-pagefind-ignore>
+              <span className={styles.readTime}>{readTime} MIN READ</span>
+            </div>
+          </header>
+          <div className={styles.prose}>{rendered}</div>
+        </article>
+      </div>
+
+      {/* TOC area */}
+      <aside className={styles.tocArea}>
+        <Toc items={pageData.toc} />
+      </aside>
+
+      {/* Footer area — spans only under article column, not TOC */}
+      <div className={styles.footerArea}>
+        <Footer />
+      </div>
+    </div>
+  );
+}

package/src/app/content/callout/Callout.module.css

@@ -0,0 +1,110 @@
+/* ============================================================
+   CALLOUT TOKENS
+   ============================================================ */
+:root {
+  --callout-note-accent:    #47a3d1;
+  --callout-warning-accent: #e6911a;
+  --callout-danger-accent:  #d22d2d;
+  --callout-tip-accent:     #22a569;
+
+  /* Subtle per-type background tints (light mode) */
+  --callout-note-bg:    color-mix(in oklch, #47a3d1 8%, white);
+  --callout-warning-bg: color-mix(in oklch, #e6911a 8%, white);
+  --callout-danger-bg:  color-mix(in oklch, #d22d2d 8%, white);
+  --callout-tip-bg:     color-mix(in oklch, #22a569 8%, white);
+
+  --callout-title-color:   #0f172a;
+  --callout-body-color:    #475569;
+}
+
+:global(.dark) {
+  /* Subtle per-type background tints (dark mode) */
+  --callout-note-bg:    color-mix(in oklch, #47a3d1 10%, #1a1a1a);
+  --callout-warning-bg: color-mix(in oklch, #e6911a 10%, #1a1a1a);
+  --callout-danger-bg:  color-mix(in oklch, #d22d2d 10%, #1a1a1a);
+  --callout-tip-bg:     color-mix(in oklch, #22a569 10%, #1a1a1a);
+
+  --callout-title-color:   #f1f5f9;
+  --callout-body-color:    #94a3b8;
+}
+
+/* ── Base callout ────────────────────────────────────────────── */
+
+.callout {
+  display: flex;
+  gap: 0.75rem;
+  margin: 1.25rem 0;
+  padding: 1rem 1.25rem;
+  border-radius: var(--radius-md);
+  border-left: 4px solid transparent;
+}
+
+/* ── Type variants ───────────────────────────────────────────── */
+
+.note {
+  background-color: var(--callout-note-bg);
+  border-left-color: var(--callout-note-accent);
+}
+
+.warning {
+  background-color: var(--callout-warning-bg);
+  border-left-color: var(--callout-warning-accent);
+}
+
+.danger {
+  background-color: var(--callout-danger-bg);
+  border-left-color: var(--callout-danger-accent);
+}
+
+.tip {
+  background-color: var(--callout-tip-bg);
+  border-left-color: var(--callout-tip-accent);
+}
+
+/* ── Icon ────────────────────────────────────────────────────── */
+
+.iconWrap {
+  flex-shrink: 0;
+  margin-top: 1px;
+  display: flex;
+}
+
+/* Icon color matches the type accent so the variant is immediately obvious */
+.note    .iconWrap { color: var(--callout-note-accent); }
+.warning .iconWrap { color: var(--callout-warning-accent); }
+.danger  .iconWrap { color: var(--callout-danger-accent); }
+.tip     .iconWrap { color: var(--callout-tip-accent); }
+
+/* ── Body ────────────────────────────────────────────────────── */
+
+.body {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-weight: 600;
+  font-size: 0.9375rem;
+  line-height: 1.4;
+  margin-bottom: 0.25rem;
+  color: var(--callout-title-color);
+}
+
+.content {
+  font-size: 0.9375rem;
+  line-height: 1.625;
+  color: var(--callout-body-color);
+}
+
+/* Markdoc wraps callout body text in <p> tags — remove bottom margin on the
+   last paragraph so the callout padding provides the visual spacing instead */
+.content :global(p) {
+  margin-bottom: 0;
+  color: inherit;
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.content :global(p + p) {
+  margin-top: 0.5rem;
+}

package/src/app/content/callout/Callout.tsx

@@ -0,0 +1,82 @@
+/**
+ * Callout — block-level callout box for note, warning, danger, and tip messages.
+ *
+ * Registered as a Markdoc tag (not a node), so authors use the
+ * {% callout type="note" title="..." %}...{% /callout %} syntax.
+ * Children are rendered Markdoc content (React nodes) passed through
+ * Markdoc.renderers.react — no special handling needed.
+ *
+ * Wired via config.tags in markdoc-config.ts, registered in
+ * Content.tsx's components map.
+ */
+
+import React from 'react';
+import styles from './Callout.module.css';
+
+interface CalloutProps {
+  type?: 'note' | 'warning' | 'danger' | 'tip';
+  title?: string;
+  children: React.ReactNode;
+}
+
+function NoteIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 16v-4" />
+      <path d="M12 8h.01" />
+    </svg>
+  );
+}
+
+function WarningIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
+      <path d="M12 9v4" />
+      <path d="M12 17h.01" />
+    </svg>
+  );
+}
+
+function DangerIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" />
+      <path d="m15 9-6 6" />
+      <path d="m9 9 6 6" />
+    </svg>
+  );
+}
+
+function TipIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M12 2a7 7 0 0 1 7 7c0 2.5-1.3 4.7-3.3 6l-.7 3H9l-.7-3A7 7 0 0 1 5 9a7 7 0 0 1 7-7Z" />
+      <path d="M9 21h6" />
+    </svg>
+  );
+}
+
+const icons = {
+  note:    <NoteIcon />,
+  warning: <WarningIcon />,
+  danger:  <DangerIcon />,
+  tip:     <TipIcon />,
+};
+
+export function Callout({ type = 'note', title, children }: CalloutProps) {
+  return (
+    <div className={`${styles.callout} ${styles[type]}`} data-type={type}>
+      <div className={styles.iconWrap}>
+        {icons[type]}
+      </div>
+      <div className={styles.body}>
+        {title && <div className={styles.title}>{title}</div>}
+        <div className={styles.content}>{children}</div>
+      </div>
+    </div>
+  );
+}
+
+export default Callout;

package/src/app/content/card/Card.module.css

@@ -0,0 +1,146 @@
+/* ============================================================
+   CARD TOKENS
+   ============================================================ */
+:root {
+  --card-bg:           var(--color-bg);
+  --card-border:       var(--color-border);
+  --card-border-hover: var(--accent);
+  --card-shadow:       var(--shadow-sm);
+  --card-shadow-hover: var(--shadow-md);
+  --card-title-color:  var(--color-fg);
+  --card-desc-color:   var(--color-fg-muted);
+  --card-tag-bg:       var(--accent-subtle);
+  --card-tag-color:    var(--accent-emphasis);
+  --card-arrow-color:  var(--color-fg-muted);
+}
+
+/* ── Base card ───────────────────────────────────────────────── */
+
+.card {
+  display: flex;
+  flex-direction: column;
+  background: var(--card-bg);
+  border: 1px solid var(--card-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--card-shadow);
+  overflow: hidden;
+  text-decoration: none;
+  color: inherit;
+}
+
+.linked {
+  cursor: pointer;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease, transform 0.15s ease;
+}
+
+.linked:hover {
+  border-color: var(--card-border-hover);
+  box-shadow: var(--card-shadow-hover);
+  transform: translateY(-1px);
+}
+
+.linked:hover .arrow {
+  color: var(--accent-emphasis);
+  transform: translateX(3px);
+}
+
+/* ── Image variant ───────────────────────────────────────────── */
+
+.imageWrap {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  background: var(--color-surface);
+  flex-shrink: 0;
+}
+
+.cardImage {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+/* ── Body ─────────────────────────────────────────────────────── */
+
+.body {
+  display: flex;
+  flex-direction: column;
+  padding: 1.25rem;
+  flex: 1;
+  gap: 0.5rem;
+}
+
+/* Image cards get slightly less top padding since the image already provides visual separation */
+.imageCard .body {
+  padding-top: 1rem;
+}
+
+/* ── Tag badge ───────────────────────────────────────────────── */
+
+.tag {
+  display: inline-flex;
+  align-self: flex-start;
+  padding: 0.2em 0.6em;
+  border-radius: var(--radius-sm);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  background: var(--card-tag-bg);
+  color: var(--card-tag-color);
+  line-height: 1.5;
+}
+
+/* ── Icon ─────────────────────────────────────────────────────── */
+
+.icon {
+  width: 1.75rem;
+  height: 1.75rem;
+  object-fit: contain;
+  display: block;
+}
+
+/* ── Title row ───────────────────────────────────────────────── */
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.title {
+  font-size: 0.9375rem;
+  font-weight: 600;
+  line-height: 1.4;
+  color: var(--card-title-color);
+}
+
+/* ── Arrow ───────────────────────────────────────────────────── */
+
+.arrow {
+  flex-shrink: 0;
+  color: var(--card-arrow-color);
+  transition: color 0.15s ease, transform 0.15s ease;
+}
+
+/* ── Description ─────────────────────────────────────────────── */
+
+.description {
+  font-size: 0.875rem;
+  line-height: 1.6;
+  color: var(--card-desc-color);
+}
+
+/* Markdoc wraps card body text in <p> tags — reset them so card padding governs spacing */
+.description :global(p) {
+  margin: 0;
+  color: inherit;
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.description :global(p + p) {
+  margin-top: 0.375rem;
+}

package/src/app/content/card/Card.tsx

@@ -0,0 +1,110 @@
+/**
+ * Card — flexible content card supporting icon, image, and plain variants.
+ *
+ * Variant is inferred from props: `image` → image card, `icon` → icon card,
+ * neither → plain. Compact mode activates automatically when no body text is
+ * provided (self-closing tag). When `path` is set the entire card is a link;
+ * internal paths (starting with "/") use React Router Link for SPA navigation,
+ * external URLs open in a new tab.
+ *
+ * Registered as a Markdoc tag (`card`) in markdoc-config.ts and added to
+ * Content.tsx's components map. Intended to be used inside {% cardGrid %}.
+ */
+
+import { Link } from 'react-router';
+import React from 'react';
+import styles from './Card.module.css';
+
+interface CardProps {
+  title: string;
+  path?: string;
+  icon?: string;
+  image?: string;
+  tag?: string;
+  children?: React.ReactNode;
+}
+
+function ArrowIcon() {
+  return (
+    <svg
+      className={styles.arrow}
+      width="15"
+      height="15"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M5 12h14" />
+      <path d="m12 5 7 7-7 7" />
+    </svg>
+  );
+}
+
+function CardInner({ title, path, icon, image, tag, children }: CardProps) {
+  const hasImage = Boolean(image);
+  const hasIcon  = Boolean(icon) && !hasImage;
+  const hasBody  = Boolean(children);
+
+  return (
+    <>
+      {hasImage && (
+        <div className={styles.imageWrap}>
+          <img src={image} alt="" className={styles.cardImage} />
+        </div>
+      )}
+      <div className={styles.body}>
+        {tag && <span className={styles.tag}>{tag}</span>}
+        {hasIcon && (
+          <img src={icon} alt="" className={styles.icon} />
+        )}
+        <div className={styles.titleRow}>
+          <span className={styles.title}>{title}</span>
+          {path && <ArrowIcon />}
+        </div>
+        {hasBody && <div className={styles.description}>{children}</div>}
+      </div>
+    </>
+  );
+}
+
+function isExternal(path: string) {
+  return path.startsWith('http://') || path.startsWith('https://') || path.startsWith('//');
+}
+
+export function Card(props: CardProps) {
+  const { path } = props;
+  const hasImage = Boolean(props.image);
+
+  const className = [
+    styles.card,
+    hasImage ? styles.imageCard : '',
+    path ? styles.linked : '',
+  ].filter(Boolean).join(' ');
+
+  if (path) {
+    if (isExternal(path)) {
+      return (
+        <a href={path} className={className} target="_blank" rel="noopener noreferrer">
+          <CardInner {...props} />
+        </a>
+      );
+    }
+    return (
+      <Link to={path} className={className}>
+        <CardInner {...props} />
+      </Link>
+    );
+  }
+
+  return (
+    <div className={className}>
+      <CardInner {...props} />
+    </div>
+  );
+}
+
+export default Card;

package/src/app/content/card/CardGrid.module.css

@@ -0,0 +1,22 @@
+/* ── CardGrid ─────────────────────────────────────────────────── */
+
+.cardGrid {
+  display: grid;
+  grid-template-columns: repeat(var(--cols, 3), minmax(0, 1fr));
+  gap: 1rem;
+  margin: 1.5rem 0;
+}
+
+/* Collapse to 2 columns on medium viewports */
+@media (max-width: 960px) {
+  .cardGrid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+/* Collapse to single column on small viewports */
+@media (max-width: 600px) {
+  .cardGrid {
+    grid-template-columns: 1fr;
+  }
+}