@tayacrystals/lore 0.1.2 → 1.0.0

package/src/icons.ts

@@ -0,0 +1,59 @@
+import * as lucide from "lucide";
+
+type IconData = [string, Record<string, string>][];
+
+function iconDataToSvg(data: IconData): string {
+  const children = data
+    .map(([tag, attrs]) => {
+      const attrStr = Object.entries(attrs)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(" ");
+      return `<${tag} ${attrStr}/>`;
+    })
+    .join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${children}</svg>`;
+}
+
+/** kebab-case → PascalCase, e.g. "message-circle" → "MessageCircle" */
+function toPascalCase(name: string): string {
+  return name
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/** Render a named Lucide icon (kebab-case) to an SVG string, or null if not found. */
+export function lucideIcon(name: string): string | null {
+  const key = toPascalCase(name);
+  const data = (lucide as Record<string, unknown>)[key];
+  if (!Array.isArray(data)) return null;
+  return iconDataToSvg(data as IconData);
+}
+
+const fallback = () => lucideIcon("external-link") ?? "";
+
+// Brand icons not in Lucide
+const DISCORD_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03z"/></svg>`;
+
+/** Pick an icon SVG for a URL based on its domain. */
+export function serviceIcon(url: string): string {
+  if (url.includes("github.com")) return lucideIcon("github") ?? fallback();
+  if (url.includes("npmjs.com")) return lucideIcon("package") ?? fallback();
+  if (url.includes("twitter.com") || url.includes("x.com")) return lucideIcon("twitter") ?? fallback();
+  if (url.includes("discord.com") || url.includes("discord.gg")) return DISCORD_SVG;
+  if (url.includes("slack.com")) return lucideIcon("slack") ?? fallback();
+  if (url.includes("youtube.com") || url.includes("youtu.be")) return lucideIcon("youtube") ?? fallback();
+  if (url.includes("linkedin.com")) return lucideIcon("linkedin") ?? fallback();
+  return fallback();
+}
+
+/** Get icon SVG for a link config entry. */
+export function linkIcon(link: string | { url: string; icon: string }): string {
+  if (typeof link === "string") return serviceIcon(link);
+  return lucideIcon(link.icon) ?? serviceIcon(link.url);
+}
+
+/** Get the href for a link config entry. */
+export function linkHref(link: string | { url: string; icon: string }): string {
+  return typeof link === "string" ? link : link.url;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { build } from "./build.ts";
+import { dev } from "./dev.ts";
+import { serve } from "./serve.ts";
+
+// Parse: lore [build|dev|serve] [dir]
+const args = process.argv.slice(2);
+
+let command: "build" | "dev" | "serve" = "build";
+let dirArg: string | undefined;
+
+if (args[0] === "dev" || args[0] === "build" || args[0] === "serve") {
+  command = args[0] as "build" | "dev" | "serve";
+  dirArg = args[1];
+} else {
+  dirArg = args[0];
+}
+
+const docsDir = dirArg ? path.resolve(dirArg) : process.cwd();
+const outDir = path.join(process.cwd(), "build");
+
+if (command === "dev") {
+  await dev(docsDir, outDir);
+} else if (command === "serve") {
+  await serve(docsDir, outDir);
+} else {
+  await build(docsDir, outDir);
+}

package/src/mdx.ts

@@ -0,0 +1,281 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeStringify from "rehype-stringify";
+import { codeToHtml } from "shiki";
+import { lucideIcon } from "./icons.ts";
+import { buildUrl } from "./routing.ts";
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function addLinkPrefix(html: string, locale?: string, version?: string): string {
+  if (!locale && !version) return html;
+
+  const prefix = buildUrl("", { locale, version });
+
+  return html.replace(
+    /(href|src)=(["'])([^"']+)["']/g,
+    (match, attr, quote, url) => {
+      const trimmed = url.trim();
+
+      if (trimmed.startsWith("/") && !trimmed.startsWith("//")) {
+        return `${attr}=${quote}${prefix}${trimmed}${quote}`;
+      }
+      if (!trimmed.startsWith("/") &&
+          !trimmed.startsWith("http://") &&
+          !trimmed.startsWith("https://") &&
+          !trimmed.startsWith("mailto:") &&
+          !trimmed.startsWith("tel:") &&
+          !trimmed.startsWith("#")) {
+        const cleanUrl = trimmed.replace(/^\.?\//, "");
+        return `${attr}=${quote}${prefix}/${cleanUrl}${quote}`;
+      }
+      return match;
+    }
+  );
+}
+
+function parseAttrs(attrStr: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const m of attrStr.matchAll(/(\w[\w-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+)))?/g)) {
+    attrs[m[1]!] = m[2] ?? m[3] ?? m[4] ?? "true";
+  }
+  return attrs;
+}
+
+/** Find all non-self-nesting occurrences of <TagName attrs>inner</TagName>. */
+function findAll(content: string, tag: string): { full: string; attrs: string; inner: string }[] {
+  const re = new RegExp(`<${tag}((?:\\s+[^>]*)?)>([\\s\\S]*?)<\\/${tag}>`, "g");
+  return [...content.matchAll(re)].map((m) => ({ full: m[0], attrs: m[1]?.trim() ?? "", inner: m[2]! }));
+}
+
+// ── Code blocks ─────────────────────────────────────────────────────────────
+
+const LANG_ALIASES: Record<string, string> = {
+  sh: "bash", shell: "bash", zsh: "bash",
+  js: "javascript", ts: "typescript",
+  mdx: "markdown",
+};
+
+async function renderCode(lang: string, meta: string, code: string): Promise<string> {
+  const attrs = parseAttrs(meta);
+  const title = attrs["title"];
+  const isTerminal = attrs["frame"] === "terminal";
+  const noFrame = attrs["frame"] === "none";
+  const wrap = "wrap" in attrs;
+
+  const normalLang = LANG_ALIASES[lang] ?? lang;
+  let pre: string;
+  if (normalLang) {
+    try {
+      pre = await codeToHtml(code, {
+        lang: normalLang,
+        themes: { light: "github-light", dark: "github-dark" },
+        defaultColor: false,
+      });
+    } catch {
+      pre = `<pre><code>${esc(code)}</code></pre>`;
+    }
+  } else {
+    pre = `<pre><code>${esc(code)}</code></pre>`;
+  }
+
+  if (wrap) pre = pre.replace("<pre ", `<pre style="white-space:pre-wrap" `);
+
+  const hasFrame = (isTerminal || title) && !noFrame;
+  if (!hasFrame) return `<div class="code-block">${pre}</div>`;
+
+  const frameKind = isTerminal ? "terminal" : "editor";
+  const titleBar = `<div class="code-frame code-frame-${frameKind}">${title ? `<span>${esc(title)}</span>` : ""}</div>`;
+  return `<div class="code-block">${titleBar}${pre}</div>`;
+}
+
+// ── Callouts ─────────────────────────────────────────────────────────────────
+
+const CALLOUT_ICONS: Record<string, string> = {
+  note: lucideIcon("info") ?? "",
+  tip: lucideIcon("lightbulb") ?? "",
+  warning: lucideIcon("triangle-alert") ?? "",
+  danger: lucideIcon("circle-x") ?? "",
+};
+
+async function processCallouts(
+  content: string,
+  codeBlocks: Map<string, { lang: string; meta: string; code: string }>,
+): Promise<string> {
+  for (const { full, attrs, inner } of findAll(content, "Callout")) {
+    const type = parseAttrs(attrs)["type"] ?? "note";
+    const innerHtml = await renderInner(inner.trim(), codeBlocks);
+    const icon = CALLOUT_ICONS[type] ?? CALLOUT_ICONS["note"]!;
+    content = content.replace(full,
+      `<div class="callout callout-${esc(type)}"><span class="callout-icon">${icon}</span><div class="callout-body">${innerHtml}</div></div>`
+    );
+  }
+  return content;
+}
+
+// ── File tree ─────────────────────────────────────────────────────────────────
+
+type TreeNode = { name: string; isDir: boolean; children: TreeNode[] };
+
+function parseTree(lines: string[]): TreeNode[] {
+  const root: TreeNode[] = [];
+  const stack: { nodes: TreeNode[]; indent: number }[] = [{ nodes: root, indent: -1 }];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const indent = line.length - line.trimStart().length;
+    const name = line.trim();
+    const isDir = name.endsWith("/");
+    while (stack.length > 1 && stack[stack.length - 1]!.indent >= indent) stack.pop();
+    const node: TreeNode = { name, isDir, children: [] };
+    stack[stack.length - 1]!.nodes.push(node);
+    if (isDir) stack.push({ nodes: node.children, indent });
+  }
+  return root;
+}
+
+const FOLDER_ICON = lucideIcon("folder") ?? "📁";
+const FILE_ICON = lucideIcon("file") ?? "📄";
+
+function renderTree(nodes: TreeNode[]): string {
+  return nodes.map((n) => {
+    const icon = `<span class="tree-icon${n.isDir ? " tree-dir-icon" : ""}">${n.isDir ? FOLDER_ICON : FILE_ICON}</span>`;
+    const kids = n.isDir && n.children.length > 0 ? `<ul>${renderTree(n.children)}</ul>` : "";
+    return `<li class="${n.isDir ? "tree-dir" : "tree-file"}"><div class="tree-row">${icon}<span>${esc(n.name)}</span></div>${kids}</li>`;
+  }).join("");
+}
+
+function processFileTrees(content: string): string {
+  for (const { full, inner } of findAll(content, "FileTree")) {
+    const tree = parseTree(inner.split("\n"));
+    content = content.replace(full, `<div class="file-tree"><ul>${renderTree(tree)}</ul></div>`);
+  }
+  return content;
+}
+
+// ── Steps ─────────────────────────────────────────────────────────────────────
+
+async function processSteps(
+  content: string,
+  codeBlocks: Map<string, { lang: string; meta: string; code: string }>,
+): Promise<string> {
+  for (const { full, inner } of findAll(content, "Steps")) {
+    const lines = inner.split("\n");
+    const steps: { title: string; body: string[] }[] = [];
+    for (const line of lines) {
+      const m = line.match(/^\s*#{1,6}\s+(.+)$/);
+      if (m) {
+        steps.push({ title: m[1]!, body: [] });
+      } else if (steps.length > 0) {
+        steps[steps.length - 1]!.body.push(line);
+      }
+    }
+    const items = await Promise.all(steps.map(async (s, i) => {
+      const bodyHtml = s.body.length ? await renderInner(s.body.join("\n").trim(), codeBlocks) : "";
+      return `<div class="step"><div class="step-num">${i + 1}</div><div class="step-body"><div class="step-title">${esc(s.title)}</div>${bodyHtml}</div></div>`;
+    }));
+    content = content.replace(full, `<div class="steps">${items.join("")}</div>`);
+  }
+  return content;
+}
+
+// ── Tabs ──────────────────────────────────────────────────────────────────────
+
+async function processTabs(
+  content: string,
+  codeBlocks: Map<string, { lang: string; meta: string; code: string }>,
+): Promise<string> {
+  for (const { full, attrs, inner } of findAll(content, "Tabs")) {
+    const group = parseAttrs(attrs)["group"];
+    const tabs: { label: string; html: string }[] = [];
+    for (const { attrs: ta, inner: ti } of findAll(inner, "Tab")) {
+      const label = parseAttrs(ta)["label"] ?? "Tab";
+      tabs.push({ label, html: await renderInner(ti.trim(), codeBlocks) });
+    }
+    const groupAttr = group ? ` data-group="${esc(group)}"` : "";
+    const btns = tabs.map((t, i) =>
+      `<button class="tab-btn${i === 0 ? " active" : ""}" data-index="${i}">${esc(t.label)}</button>`
+    ).join("");
+    const panels = tabs.map((t, i) =>
+      `<div class="tab-panel${i === 0 ? " active" : ""}" data-index="${i}">${t.html}</div>`
+    ).join("");
+    content = content.replace(full,
+      `<div class="tabs"${groupAttr}><div class="tab-list">${btns}</div><div class="tab-panels">${panels}</div></div>`
+    );
+  }
+  return content;
+}
+
+// ── Main renderer ─────────────────────────────────────────────────────────────
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkGfm)
+  .use(remarkRehype, { allowDangerousHtml: true })
+  .use(rehypeSlug)
+  .use(rehypeAutolinkHeadings, {
+    behavior: "append",
+    content: { type: "text", value: "#" },
+    properties: { class: "heading-anchor", ariaHidden: "true", tabIndex: -1 },
+  })
+  .use(rehypeStringify, { allowDangerousHtml: true });
+
+async function renderInner(
+  content: string,
+  codeBlocks: Map<string, { lang: string; meta: string; code: string }>,
+): Promise<string> {
+  let html = String(await processor.process(content));
+  for (const [id, entry] of codeBlocks) {
+    const codeHtml = await renderCode(entry.lang, entry.meta, entry.code);
+    html = html.replace(new RegExp(`<p>\\s*${id}\\s*</p>`), codeHtml);
+    html = html.replace(id, codeHtml);
+  }
+  return html;
+}
+
+export async function renderMdx(
+  content: string,
+  opts: { locale?: string; version?: string } = {}
+): Promise<string> {
+  const { locale, version } = opts;
+
+  // 1. Extract fenced code blocks and inline code spans so component regexes
+  //    don't accidentally match tags inside them.
+  const codeBlocks = new Map<string, { lang: string; meta: string; code: string }>();
+  const inlineSpans = new Map<string, string>();
+  let ci = 0;
+  // Fenced code blocks
+  content = content.replace(/^([ \t]*)(`{3,})(\w*)(.*)\n([\s\S]*?)\n\1\2[ \t]*$/gm, (_, indent, _fence, lang, meta, code) => {
+    const id = `LORECODE${ci++}`;
+    const dedented = indent ? code.replace(new RegExp(`^${indent}`, "gm"), "") : code;
+    codeBlocks.set(id, { lang, meta: meta.trim(), code: dedented });
+    return `\n${id}\n`;
+  });
+  // Inline code spans (single or multi backtick)
+  let ii = 0;
+  content = content.replace(/(`+)([^`]|(?!`\1)[^])*?\1/g, (m) => {
+    const id = `LOREINLINE${ii++}`;
+    inlineSpans.set(id, m);
+    return id;
+  });
+
+  // 2. Process components
+  content = await processCallouts(content, codeBlocks);
+  content = processFileTrees(content);
+  content = await processSteps(content, codeBlocks);
+  content = await processTabs(content, codeBlocks);
+
+  // 3. Restore inline spans, render markdown, restore code blocks
+  for (const [id, raw] of inlineSpans) content = content.replace(id, raw);
+  let html = await renderInner(content, codeBlocks);
+
+  // 4. Add locale/version prefix to relative links
+  html = addLinkPrefix(html, locale, version);
+
+  return html;
+}

package/src/parse.ts

@@ -0,0 +1,53 @@
+import yaml from "js-yaml";
+
+export interface ParsedPage {
+  frontmatter: Record<string, unknown>;
+  content: string;
+  h1Title?: string;
+  description?: string;
+}
+
+/**
+ * Parse an MDX file: extract frontmatter and content.
+ */
+export function parsePage(raw: string): ParsedPage {
+  let content = raw;
+  let frontmatter: Record<string, unknown> = {};
+
+  // Strip frontmatter
+  if (content.startsWith("---")) {
+    const end = content.indexOf("\n---", 3);
+    if (end !== -1) {
+      const fmText = content.slice(3, end).trim();
+      if (fmText) {
+        frontmatter = (yaml.load(fmText) as Record<string, unknown>) ?? {};
+      }
+      content = content.slice(end + 4).trimStart();
+    }
+  }
+
+  // Extract leading H1 if present
+  let h1Title: string | undefined;
+  const h1Match = content.match(/^#\s+(.+)$/m);
+  if (h1Match && content.trimStart().startsWith("#")) {
+    h1Title = h1Match[1]?.trim();
+  }
+
+  const description =
+    typeof frontmatter["description"] === "string"
+      ? frontmatter["description"]
+      : undefined;
+
+  return { frontmatter, content, h1Title, description };
+}
+
+/**
+ * Derive a title from a filename (without extension, without numeric prefix).
+ * e.g. "01-quick-start" → "Quick Start"
+ */
+export function filenameToTitle(name: string): string {
+  return name
+    .replace(/^\d+-/, "")
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}

package/src/routing.ts

@@ -0,0 +1,46 @@
+import type { Config } from "./types.ts";
+
+export interface RouteContext {
+  version?: string;
+  locale?: string;
+  path: string;
+}
+
+export function parseUrl(url: string, config: Config): RouteContext {
+  const parts = url.split("/").filter(Boolean);
+
+  const ctx: RouteContext = { path: "" };
+
+  if (config.internationalization && parts.length > 0) {
+    const localeMatch = parts[0]!.match(/^[a-z]{2}(-[a-z]{2})?$/);
+    if (localeMatch) {
+      ctx.locale = parts.shift();
+    }
+  }
+
+  if (config.versioning && parts.length > 0) {
+    const versionMatch = parts[0]!.match(/^v\d+/);
+    if (versionMatch) {
+      ctx.version = parts.shift();
+    }
+  }
+
+  ctx.path = parts.length > 0 ? "/" + parts.join("/") : "/";
+  return ctx;
+}
+
+export function buildUrl(
+  path: string,
+  opts: { locale?: string; version?: string }
+): string {
+  const parts: string[] = [];
+
+  if (opts.locale) parts.push(opts.locale);
+  if (opts.version) parts.push(opts.version);
+
+  const cleanPath = path.replace(/^\//, "").replace(/\/$/, "");
+  if (cleanPath) parts.push(cleanPath);
+
+  const result = "/" + parts.join("/");
+  return result.replace(/\/+/g, "/");
+}

package/src/serve.ts

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import { build } from "./build.ts";
+import { loadConfig } from "./config.ts";
+import { getDefaultVersion } from "./version.ts";
+import { getDefaultLocale } from "./i18n.ts";
+
+const STATIC_EXTS = new Set([".svg", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2"]);
+
+export async function serve(docsDir: string, outDir: string, port = 3000): Promise<void> {
+  const config = await loadConfig(docsDir);
+  await build(docsDir, outDir);
+
+  Bun.serve({
+    port,
+    idleTimeout: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      // Redirect from root to default version/locale
+      if (url.pathname === "/") {
+        const defaultLocale = config.internationalization
+          ? getDefaultLocale(config)
+          : undefined;
+        const defaultVersion = config.versioning
+          ? getDefaultVersion(config)
+          : undefined;
+
+        const redirectPathParts: string[] = [];
+        if (defaultLocale) redirectPathParts.push(defaultLocale);
+        if (defaultVersion) redirectPathParts.push(defaultVersion);
+
+        if (redirectPathParts.length > 0) {
+          const redirectPath = "/" + redirectPathParts.join("/") + "/";
+          return Response.redirect(url.origin + redirectPath, 302);
+        }
+      }
+
+      let filePath = path.join(outDir, url.pathname);
+      try {
+        const s = await stat(filePath);
+        if (s.isDirectory()) filePath = path.join(filePath, "index.html");
+      } catch {
+        filePath = path.join(outDir, url.pathname, "index.html");
+      }
+
+      const file = Bun.file(filePath);
+      if (!(await file.exists())) return new Response("Not found", { status: 404 });
+
+      const ext = path.extname(filePath).toLowerCase();
+      const headers: Record<string, string> = {};
+
+      if (STATIC_EXTS.has(ext)) {
+        headers["Cache-Control"] = "public, max-age=31536000, immutable";
+      }
+
+      const type = file.type;
+      const acceptsGzip = req.headers.get("Accept-Encoding")?.includes("gzip") ?? false;
+      if (acceptsGzip && (type.startsWith("text/") || type.includes("javascript"))) {
+        const compressed = Bun.gzipSync(await file.bytes());
+        headers["Content-Encoding"] = "gzip";
+        headers["Content-Type"] = type;
+        headers["Vary"] = "Accept-Encoding";
+        return new Response(compressed, { headers });
+      }
+
+      return new Response(file, { headers });
+    },
+  });
+
+  console.log(`\nServing build at http://localhost:${port}`);
+}