dommief 0.1.1 → 0.1.3

package/src/markdown/rehype-api.ts

@@ -0,0 +1,131 @@
+import { visit } from 'unist-util-visit';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { DommiefError } from './errors.js';
+
+// Nạp react-docgen-typescript (kéo theo cả TypeScript) CHỈ khi trang có `<API>`: import ở đầu file
+// làm mọi site crash lúc khởi động nếu typescript cài được không có API JS cũ (TS 7).
+let docgen: typeof import('react-docgen-typescript') | undefined;
+function loadDocgen(): typeof import('react-docgen-typescript') {
+  if (docgen) return docgen;
+  try {
+    docgen = createRequire(import.meta.url)('react-docgen-typescript');
+    return docgen!;
+  } catch (e) {
+    throw new DommiefError(`<API> cần react-docgen-typescript + typescript 5.x: ${(e as Error).message}`, { code: 'api_docgen_unavailable' });
+  }
+}
+
+export interface ApiProp {
+  name: string;
+  type?: string;
+  required?: boolean;
+  description?: string;
+  defaultValue?: any;
+}
+
+export interface ApiEntry {
+  displayName: string;
+  description?: string;
+  props: ApiProp[];
+  src: string;
+  hash: string;
+}
+
+// Cache theo file tuyệt đối (một entry mỗi file, thay bằng bản mới khi hash đổi — map không phình mãi theo #17).
+const apiCache = new Map<string, { hash: string; entries: ApiEntry[] }>();
+
+export function clearApiCache(): void {
+  apiCache.clear();
+}
+
+export function hashFileContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function resolveApiSrc(src: string, filePath: string): string {
+  const base = filePath ? path.dirname(filePath) : process.cwd();
+  return path.isAbsolute(src) ? src : path.resolve(base, src);
+}
+
+export function buildApiTable(src: string, filePath: string = ''): ApiEntry[] | null {
+  const abs = resolveApiSrc(src, filePath);
+  let content: string;
+  try {
+    content = fs.readFileSync(abs, 'utf8');
+  } catch {
+    return null;
+  }
+  const hash = hashFileContent(content);
+  const cached = apiCache.get(abs);
+  if (cached && cached.hash === hash) return cached.entries;
+
+  // loadDocgen() ngoài try: thiếu/sai bản typescript phải báo lỗi, không được nuốt thành "No API data".
+  const parser = loadDocgen().withDefaultConfig({});
+  let docs: any[];
+  try {
+    docs = parser.parse(abs) ?? [];
+  } catch {
+    return null; // file không parse được (cú pháp lỗi) → caller cảnh báo, không nuốt im lặng
+  }
+
+  const entries: ApiEntry[] = (docs || []).map((d: any) => ({
+    displayName: d.displayName,
+    description: d.description || '',
+    src: abs,
+    hash,
+    props: Object.values(d.props || {}).map((p: any) => ({
+      name: p.name,
+      type: p.type?.name ?? p.type?.raw ?? '',
+      required: !!p.required,
+      description: p.description || '',
+      defaultValue: p.defaultValue?.value,
+    })),
+  }));
+
+  apiCache.set(abs, { hash, entries });
+  return entries;
+}
+
+export function rehypeApi() {
+  return (tree: any, file: any) => {
+    // file.data.apiSrcFiles: để caller (vite/plugin.ts) `addWatchFile` từng file — Vite chỉ tự
+    // watch file.md, không biết plugin có đọc thêm .tsx (#17).
+    const apis: any[] = Array.isArray((file?.data as any)?.apis) ? (file.data as any).apis : [];
+    const watched: string[] = Array.isArray((file?.data as any)?.apiSrcFiles) ? (file.data as any).apiSrcFiles : [];
+    const warnings: string[] = Array.isArray((file?.data as any)?.warnings) ? (file.data as any).warnings : [];
+    const filePath = String((file as any)?.path ?? '');
+
+    visit(tree, 'element', (node: any, index: number | undefined, parent: any) => {
+      if (!parent || typeof index !== 'number') return;
+      if (String(node.tagName).toLowerCase() !== 'api') return;
+      const src = String(node.properties?.src ?? '');
+      if (!src) return;
+
+      const abs = resolveApiSrc(src, filePath);
+      const data = buildApiTable(src, filePath);
+      watched.push(abs);
+      if (!data?.length) warnings.push(`<API src="${src}">: ${data ? 'no component found (syntax error or no exported component)' : 'file missing or failed to parse'}: ${abs}`);
+
+      apis.push({ id: hashFileContent(src + filePath).slice(0, 8), src: abs, data });
+
+      parent.children[index] = {
+        type: 'element',
+        tagName: 'DomApi',
+        properties: {
+          src: abs,
+          data: data ? JSON.stringify(data) : undefined,
+        },
+        children: [],
+      };
+    });
+
+    if (file?.data) {
+      (file.data as any).apis = apis;
+      (file.data as any).apiSrcFiles = watched;
+      (file.data as any).warnings = warnings;
+    }
+  };
+}

package/src/markdown/rehype-code.ts

@@ -0,0 +1,147 @@
+import { visit } from 'unist-util-visit';
+import { bundledLanguages, createHighlighter, type Highlighter } from 'shiki';
+
+// Đặc tả: docs/spec/MARKDOWN.md §3.8 (highlight dòng), §3.16 (rehypeCode), §8 (Shiki lúc build);
+// backlog DM-705, DM-706. Highlight MỘT lần lúc transform, gửi HTML tĩnh: không có highlighter
+// trong bundle client. `defaultColor: false` bắt buộc — đẩy cả 2 màu vào biến CSS để
+// `[data-prefers-color='dark']` đổi màu bằng CSS thuần (§8.2 điểm 2).
+
+export interface ShikiOptions {
+  themes: { light: string; dark: string };
+}
+
+export interface RehypeCodeOptions {
+  /** `false` = tắt Shiki (code block giữ `<pre><code>` thô). */
+  shiki?: ShikiOptions | false;
+  lineNumbers?: boolean;
+}
+
+export const DEFAULT_SHIKI: ShikiOptions = { themes: { light: 'github-light', dark: 'github-dark' } };
+
+/** Version của output pipeline code block — cache transform (DM-406) phải đưa vào key. */
+export const CODE_PIPELINE_VERSION = 'shiki4-v1';
+
+const HIGHLIGHT_RE = /\{((?:\d+(?:-\d+)?,?)+)\}/;
+
+/** `{1,3-5}` → [1,3,4,5] (1-based, sort + dedupe), và meta còn lại đã bỏ phần `{…}`. */
+export function parseHighlightLines(meta: string): { lines: number[]; rest: string } {
+  const m = meta.match(HIGHLIGHT_RE);
+  if (!m) return { lines: [], rest: meta.trim() };
+  const set = new Set<number>();
+  for (const part of m[1]!.split(',').filter(Boolean)) {
+    const [a, b] = part.split('-').map(Number) as [number, number | undefined];
+    const end = b ?? a;
+    for (let n = Math.min(a, end); n <= Math.max(a, end); n++) if (n >= 1) set.add(n);
+  }
+  return { lines: [...set].sort((x, y) => x - y), rest: meta.replace(HIGHLIGHT_RE, '').trim() };
+}
+
+/** remark: tách `{1,3-5}` + `[title]` khỏi meta của fence, gắn vào hProperties (sống sót qua rehype-raw). */
+export function remarkCodeMeta() {
+  return (tree: any) => {
+    visit(tree, 'code', (node: any) => {
+      const meta = String(node.meta ?? '');
+      if (!meta) return;
+      const { lines, rest } = parseHighlightLines(meta);
+      const title = rest.match(/\[([^\]]+)\]/)?.[1];
+      const props: Record<string, string> = {};
+      if (lines.length) props['data-highlight-lines'] = lines.join(',');
+      if (title) props['data-title'] = title;
+      if (Object.keys(props).length) node.data = { ...node.data, hProperties: { ...node.data?.hProperties, ...props } };
+      node.meta = rest || null;
+    });
+  };
+}
+
+const highlighters = new Map<string, Promise<Highlighter>>();
+
+/** Một highlighter / bộ theme cho cả tiến trình; grammar nạp dần theo ngôn ngữ thật sự gặp (langs: 'auto'). */
+function getHighlighter(opts: ShikiOptions): Promise<Highlighter> {
+  const key = `${opts.themes.light}|${opts.themes.dark}`;
+  let h = highlighters.get(key);
+  if (!h) {
+    h = createHighlighter({ themes: [opts.themes.light, opts.themes.dark], langs: [] });
+    highlighters.set(key, h);
+  }
+  return h;
+}
+
+function textOf(node: any): string {
+  let out = '';
+  visit(node, 'text', (t: any) => { out += t.value; });
+  return out;
+}
+
+function langOf(code: any): string | undefined {
+  const cls = code.properties?.className;
+  const list: string[] = Array.isArray(cls) ? cls.map(String) : typeof cls === 'string' ? cls.split(/\s+/) : [];
+  return list.map((c) => /^language-(.+)$/.exec(c)?.[1]).find(Boolean);
+}
+
+function markLines(pre: any, highlight: Set<number>, lineNumbers: boolean): void {
+  const code = pre.children?.find((c: any) => c.tagName === 'code');
+  let n = 0;
+  for (const child of code?.children ?? []) {
+    if (child.type !== 'element' || child.tagName !== 'span') continue;
+    const cls = String(child.properties?.class ?? child.properties?.className ?? '');
+    if (!/\bline\b/.test(cls)) continue;
+    n++;
+    const classes = cls.split(/\s+/).filter(Boolean);
+    if (highlight.has(n)) classes.push('highlighted');
+    child.properties = { ...child.properties, class: classes.join(' ') };
+    if (lineNumbers) child.properties['data-line'] = String(n);
+  }
+}
+
+/**
+ * rehype: `pre > code` → `<div class="dommief-code" data-lang>` (+ title) bọc `<pre class="shiki">` của Shiki.
+ * Ngôn ngữ không có grammar (vd `mermaid`) → warning + giữ code thô, KHÔNG fail build (§8.1).
+ * Fence không ghi lang → code thô (Shiki ném lỗi với lang rỗng, §3.16).
+ */
+export function rehypeCode(options: RehypeCodeOptions = {}) {
+  const shiki = options.shiki === undefined ? DEFAULT_SHIKI : options.shiki;
+  const lineNumbers = !!options.lineNumbers;
+  return async (tree: any, file: any) => {
+    const jobs: { parent: any; index: number; pre: any; code: any }[] = [];
+    visit(tree, 'element', (node: any, index: number | undefined, parent: any) => {
+      if (node.tagName !== 'pre' || !parent || typeof index !== 'number') return;
+      const kids = (node.children ?? []).filter((c: any) => !(c.type === 'text' && !c.value.trim()));
+      if (kids.length !== 1 || kids[0].tagName !== 'code') return;
+      jobs.push({ parent, index, pre: node, code: kids[0] });
+    });
+    if (!jobs.length) return;
+    const highlighter = shiki ? await getHighlighter(shiki) : null;
+    for (const { parent, index, pre, code } of jobs) {
+      const lang = langOf(code);
+      const title = code.properties?.dataTitle as string | undefined;
+      const hl = new Set(String(code.properties?.dataHighlightLines ?? '').split(',').filter(Boolean).map(Number));
+      let inner: any = pre;
+      if (highlighter && shiki && lang) {
+        if (lang in bundledLanguages) {
+          if (!highlighter.getLoadedLanguages().includes(lang)) await highlighter.loadLanguage(lang as any);
+          const source = textOf(code).replace(/\n$/, '');
+          const root: any = highlighter.codeToHast(source, { lang, themes: { light: shiki.themes.light, dark: shiki.themes.dark }, defaultColor: false });
+          inner = root.children[0];
+          markLines(inner, hl, lineNumbers);
+        } else {
+          const warnings: string[] = ((file.data ??= {}).warnings ??= []);
+          const pos = pre.position?.start;
+          warnings.push(`${file.path ?? ''}${pos ? `:${pos.line}` : ''} Shiki không có grammar cho "${lang}"; hiển thị code thô`);
+        }
+      }
+      // Code thô vẫn mang highlight dòng được dưới dạng data-attr (theme không-Shiki tự CSS).
+      if (inner === pre && hl.size) pre.properties = { ...pre.properties, 'data-highlight-lines': [...hl].join(',') };
+      delete code.properties?.dataHighlightLines;
+      delete code.properties?.dataTitle;
+      const children: any[] = [];
+      if (title) children.push({ type: 'element', tagName: 'div', properties: { className: ['dommief-code__title'] }, children: [{ type: 'text', value: title }] });
+      children.push(inner);
+      parent.children[index] = {
+        type: 'element',
+        tagName: 'div',
+        properties: { className: ['dommief-code'], ...(lang ? { 'data-lang': lang } : {}) },
+        children,
+      };
+    }
+  };
+}

package/src/markdown/rehype-demo.ts

@@ -0,0 +1,76 @@
+import { visit } from 'unist-util-visit';
+import { createHash } from 'node:crypto';
+
+/**
+ * remark: ```tsx demo → đánh dấu `data-demo` lên <code>. Phải làm ở remark vì `rehype-raw`
+ * dựng lại cây hast và làm mất `node.data.meta`, còn `hProperties` thì sống sót.
+ */
+export function remarkDemoMeta() {
+  return (tree: any) => {
+    visit(tree, 'code', (node: any) => {
+      if (/\bdemo\b/.test(String(node.meta ?? ''))) {
+        node.data = { ...node.data, hProperties: { ...node.data?.hProperties, 'data-demo': 'true' } };
+      }
+    });
+  };
+}
+
+export interface DemoEntry {
+  id: string;
+  source: string;
+  src?: string;
+}
+
+function demoId(source: string, file: string): string {
+  return createHash('sha256').update(file + '\n' + source).digest('hex').slice(0, 8);
+}
+
+function codeText(node: any): string {
+  let out = '';
+  visit(node, 'text', (t: any) => { out += t.value; });
+  return out;
+}
+
+export function rehypeDemo() {
+  return (tree: any, file: any) => {
+    const demos: DemoEntry[] = Array.isArray((file.data as any)?.demos) ? (file.data as any).demos : [];
+    const filePath = String((file as any).path ?? '');
+
+    visit(tree, 'element', (node: any, index: number | undefined, parent: any) => {
+      if (!parent || typeof index !== 'number') return;
+
+      // <code src="./Foo.tsx"> form
+      if (node.tagName === 'code' && node.properties?.src) {
+        const src = String(node.properties.src);
+        const source = codeText(node).trim();
+        const id = demoId(source || src, filePath);
+        demos.push({ id, source, src });
+        parent.children[index] = {
+          type: 'element',
+          tagName: 'DomDemo',
+          properties: { id, src, source },
+          children: [],
+        };
+        return;
+      }
+
+      if (node.tagName !== 'pre') return;
+      const codeNode = Array.isArray(node.children) ? node.children.find((c: any) => c?.tagName === 'code') : null;
+      if (!codeNode) return;
+      // Chỉ block khai báo `demo` trong meta (```tsx demo) mới là demo; ```tsx thường vẫn là code.
+      if (!codeNode.properties?.dataDemo) return;
+
+      const source = codeText(codeNode).replace(/\n$/, '');
+      const id = demoId(source, filePath);
+      demos.push({ id, source });
+      parent.children[index] = {
+        type: 'element',
+        tagName: 'DomDemo',
+        properties: { id, source },
+        children: [],
+      };
+    });
+
+    (file.data as any).demos = demos;
+  };
+}

package/src/markdown/rehype-desc.ts

@@ -0,0 +1,30 @@
+import { visit } from 'unist-util-visit';
+
+export function rehypeDesc() {
+  return (tree: any, file: any) => {
+    file.data = file.data || {};
+    let desc: string | undefined;
+    visit(tree, 'element', (node: any) => {
+      if (!desc && node.tagName === 'p') {
+        const text = (node.children || []).map((c: any) => c.value || '').join('').trim();
+        if (text) desc = text.slice(0, 160);
+      }
+    });
+    if (desc) {
+      if (!file.data.frontmatter) file.data.frontmatter = {};
+      if (file.data.frontmatter.description == null) file.data.frontmatter.description = desc;
+    }
+  };
+}
+
+export function rehypeStrip() {
+  // strip dangerous raw html? minimal: remove script tags
+  return (tree: any) => {
+    visit(tree, 'element', (node: any, index: number | undefined, parent: any) => {
+      if (node.tagName === 'script' && parent && index !== undefined) {
+        parent.children.splice(index, 1);
+        return index; // restart
+      }
+    });
+  };
+}

package/src/markdown/rehype-img.ts

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { visit } from 'unist-util-visit';
+
+const PLACEHOLDER = '__DOMMIEF_IMG_';
+const SKIP = /^([a-z][a-z0-9+.-]*:|\/\/|#|\/)/i; // http:, data:, //cdn, #x, /public-abs
+
+/**
+ * Ảnh tương đối `./a.png` (theo vị trí file md) được thành `import` để Vite bundle + băm tên + gắn base.
+ * Ở đây chỉ đặt placeholder và ghi `file.data.images`; `toModule` sinh dòng import.
+ */
+export function rehypeImg() {
+  return (tree: any, file: any) => {
+    const images: { name: string; specifier: string }[] = [];
+    visit(tree, 'element', (node: any) => {
+      if (node.tagName !== 'img' || !node.properties?.src) return;
+      const src = String(node.properties.src);
+      if (SKIP.test(src)) return;
+      const clean = src.replace(/[?#].*$/, '');
+      const specifier = clean.startsWith('.') ? clean : './' + path.posix.normalize(clean);
+      const name = `${PLACEHOLDER}${images.length}__`;
+      images.push({ name, specifier });
+      node.properties.src = name;
+    });
+    // DM-410: như rehype-link.ts, gắn dòng nguồn để link-check báo đúng `file:line` cho asset chết.
+    visit(tree, 'element', (node: any) => {
+      if (node.tagName !== 'img' || !node.properties?.src || node.properties['data-src-line']) return;
+      const line = node.position?.start?.line;
+      if (line) node.properties['data-src-line'] = String(line);
+    });
+    file.data = file.data || {};
+    file.data.images = images;
+  };
+}

package/src/markdown/rehype-link.ts

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { visit } from 'unist-util-visit';
+import { winPath } from '../utils/path.js';
+
+export interface RehypeLinkOptions {
+  /** file md tuyệt đối (POSIX) → path của route. Không có ⇒ chỉ bỏ đuôi `.md` (không kiểm tra). */
+  byFile?: Record<string, { path: string }>;
+  /** `config.base` ('/sub/'): `<a>` thường không có basename của router nên phải gắn tiền tố ở đây. */
+  base?: string;
+}
+
+const EXTERNAL = /^([a-z][a-z0-9+.-]*:|\/\/|#|\/)/i; // http:, mailto:, //cdn, #hash, /abs
+
+/**
+ * `[x](./getStarted.md#a)` → path của route thật (`/get-started#a`), tính theo VỊ TRÍ FILE md chứ không theo URL.
+ * Link `.md` không khớp route nào được giữ nguyên và ghi warning vào `file.data.warnings`.
+ */
+export function rehypeLink(options: RehypeLinkOptions = {}) {
+  return (tree: any, file: any) => {
+    const from = winPath(String(file?.path ?? ''));
+    const prefix = (options.base ?? '/').replace(/\/$/, '');
+    const warnings: string[] = Array.isArray(file?.data?.warnings) ? file.data.warnings : [];
+    visit(tree, 'element', (node: any) => {
+      if (node.tagName !== 'a' || !node.properties?.href) return;
+      const href = String(node.properties.href);
+      if (EXTERNAL.test(href)) return;
+      const m = href.match(/^([^#?]*\.md)([?#].*)?$/);
+      if (!m || m[1] === undefined) return;
+      const tail = m[2] ?? '';
+      if (!options.byFile) {
+        node.properties.href = m[1].replace(/\.md$/, '') + tail;
+        return;
+      }
+      const abs = path.posix.resolve(path.posix.dirname(from), m[1]);
+      const route = options.byFile[abs];
+      if (route) node.properties.href = (route.path === '/' ? prefix + '/' : prefix + route.path) + tail;
+      else warnings.push(`link_unresolved: "${href}" trong ${from} không trỏ tới file md nào thuộc docDirs`);
+    });
+    // DM-410: gắn dòng nguồn lên MọI `<a>` nội bộ (kể cả link không đổi ở trên) để link-check
+    // báo đúng `file:line` thay vì chỉ `routeId`. ~20 byte/link, cố ý giữ lại trong HTML để debug.
+    visit(tree, 'element', (node: any) => {
+      if (node.tagName !== 'a' || !node.properties?.href || node.properties['data-src-line']) return;
+      const href = String(node.properties.href);
+      if (EXTERNAL.test(href) && !href.startsWith('/')) return;
+      const line = node.position?.start?.line;
+      if (line) node.properties['data-src-line'] = String(line);
+    });
+    if (file?.data) file.data.warnings = warnings;
+  };
+}

package/src/markdown/rehype-slug.ts

@@ -0,0 +1,41 @@
+import { visit } from 'unist-util-visit';
+import Slugger from 'github-slugger';
+
+export interface TocItem { id: string; depth: number; title: string; }
+
+function textOf(node: any): string {
+  if (node.type === 'text') return node.value || '';
+  if (node.children) return node.children.map(textOf).join('');
+  return '';
+}
+
+export function rehypeSlug() {
+  return (tree: any, file: any) => {
+    file.data = file.data || {};
+    const toc: TocItem[] = [];
+    const slugger = new Slugger();
+    visit(tree, 'element', (node: any) => {
+      if (/^h[1-6]$/.test(node.tagName)) {
+        const text = textOf(node).trim();
+        const depth = Number(node.tagName.slice(1));
+        let id = node.properties?.id;
+        if (!id) id = slugger.slug(text);
+        if (!node.properties) node.properties = {};
+        node.properties.id = id;
+        toc.push({ id, depth, title: text });
+      }
+    });
+    file.data.toc = toc;
+  };
+}
+
+export function rehypeAutolinkHeadings() {
+  return (tree: any) => {
+    visit(tree, 'element', (node: any) => {
+      if (/^h[1-6]$/.test(node.tagName) && node.properties?.id) {
+        const anchor = { type: 'element', tagName: 'a', properties: { href: '#' + node.properties.id, className: ['dommief-heading-anchor'], tabIndex: -1 }, children: [] };
+        node.children = [anchor, ...node.children];
+      }
+    });
+  };
+}

package/src/markdown/rehype-text.ts

@@ -0,0 +1,53 @@
+export function rehypeText() {
+  return (tree: any, file: any) => {
+    file.data = file.data || {};
+    const toc: any[] = file.data.toc || [];
+    const texts: any[] = [];
+    const paraIdOf = new WeakMap<any, number>();
+    let nextParaId = 0;
+    let tocCursor = -1;
+    let currentTocIndex: number | undefined;
+
+    const isContainer = (node: any) => {
+      if (!node || node.type !== 'element') return false;
+      const tag = node.tagName;
+      if (tag === 'p' || tag === 'ul' || tag === 'ol' || tag === 'root') return true;
+      return typeof tag === 'string' && /^[A-Z]/.test(tag);
+    };
+
+    const containerOf = (ancestors: any[]) => {
+      for (let i = ancestors.length - 1; i >= 0; i--) {
+        if (isContainer(ancestors[i])) return ancestors[i];
+      }
+      return tree;
+    };
+
+    const walk = (node: any, ancestors: any[]) => {
+      if (node && node.type === 'element' && /^h[1-6]$/.test(node.tagName)) {
+        tocCursor += 1;
+        if (tocCursor < toc.length) currentTocIndex = tocCursor;
+        for (const c of node.children || []) walk(c, [...ancestors, node]);
+        return;
+      }
+      if (node && node.type === 'text') {
+        const parent = ancestors[ancestors.length - 1];
+        if (parent && /^h[1-6]$/.test(parent.tagName)) return;
+        const v = node.value || '';
+        if (!v.trim()) return;
+        const container = containerOf(ancestors);
+        if (!paraIdOf.has(container)) paraIdOf.set(container, nextParaId++);
+        const paraId = paraIdOf.get(container)!;
+        const frag: any = { type: 'content', value: v, paraId };
+        if (currentTocIndex !== undefined) frag.tocIndex = currentTocIndex;
+        texts.push(frag);
+        return;
+      }
+      if (node && Array.isArray(node.children)) {
+        for (const c of node.children) walk(c, [...ancestors, node]);
+      }
+    };
+
+    walk(tree, []);
+    file.data.texts = texts;
+  };
+}

package/src/markdown/remark-container.ts

@@ -0,0 +1,76 @@
+import { visit } from 'unist-util-visit';
+
+// Đặc tả: docs/spec/MARKDOWN.md §3.4, §5.1, backlog DM-703.
+// `:::info … :::` → <div class="dommief-container dommief-container--info"> (+ title, role).
+// Không render qua component `Container` riêng: HTML thuần đủ cho 4 loại cố định, SSR/JS-off
+// đều đúng, và theme override bằng CSS (`.dommief-container--*`) như mọi phần khác.
+
+export const CONTAINER_TYPES = ['info', 'warning', 'success', 'error'] as const;
+type ContainerType = (typeof CONTAINER_TYPES)[number];
+
+/**
+ * `remark-directive` bật cả 3 cú pháp (`:text`, `::leaf`, `:::container`). Hai cú pháp đầu
+ * nuốt chữ thật trong tài liệu (`10:30`, `ghi chú: xem`). Gỡ `text` và chỉ giữ construct
+ * container trong `flow`, CÓ KIỂM TRA cấu trúc (§3.4) thay vì xoá theo chỉ số mảng như dumi.
+ */
+function restrictToContainerSyntax(extensions: any[]): void {
+  // Chữ ký: `{ text: {58: …}, flow: {58: [container, leaf]} }` — khóa 58 = ':'. remark-gfm cũng có
+  // extension `{text, flow}` nên phải lọc theo tokenizer `…Directive…`, không chỉ theo shape.
+  const isDirective = (e: any) => {
+    const f = e?.flow?.[58];
+    return !!e?.text?.[58] && (Array.isArray(f) ? f : [f]).some((c: any) => /Directive/.test(c?.tokenize?.name ?? ''));
+  };
+  const hit = extensions.filter(isDirective);
+  if (hit.length !== 1) throw new Error('remark-directive đổi cấu trúc nội bộ (không thấy đúng 1 extension directive {text, flow}); cập nhật remarkContainer');
+  const ext = hit[0];
+  const flow = ext.flow[58];
+  const constructs = Array.isArray(flow) ? flow : [flow];
+  const containers = constructs.filter((c: any) => /Container/.test(c?.tokenize?.name ?? ''));
+  if (containers.length !== 1) throw new Error('remark-directive đổi cấu trúc nội bộ (không thấy đúng 1 container construct); cập nhật remarkContainer');
+  delete ext.text;
+  ext.flow = { 58: containers };
+}
+
+export function remarkContainer(this: any) {
+  const data = this.data();
+  restrictToContainerSyntax(data.micromarkExtensions ?? []);
+  return (tree: any, file: any) => {
+    visit(tree, 'containerDirective', (node: any, index: number | undefined, parent: any) => {
+      if (!parent || typeof index !== 'number') return;
+      const name = String(node.name);
+      if (!(CONTAINER_TYPES as readonly string[]).includes(name)) {
+        const warnings: string[] = ((file.data ??= {}).warnings ??= []);
+        const pos = node.position?.start;
+        warnings.push(`${file.path ?? ''}${pos ? `:${pos.line}:${pos.column}` : ''} container ":::${name}" không được hỗ trợ (chỉ ${CONTAINER_TYPES.join('/')}); render thành <div> thường`);
+        node.data = { hName: 'div', hProperties: {} };
+        return;
+      }
+      const type = name as ContainerType;
+      // `:::info[Tiêu đề]` (label) hoặc `:::info{title="…"}` (attribute) đều thành title.
+      const labelIdx = node.children.findIndex((c: any) => c.data?.directiveLabel);
+      const labelNode = labelIdx >= 0 ? node.children.splice(labelIdx, 1)[0] : null;
+      const title = node.attributes?.title ?? (labelNode ? textOf(labelNode) : undefined);
+      const children = [...node.children];
+      if (title) {
+        children.unshift({ type: 'paragraph', data: { hName: 'p', hProperties: { className: ['dommief-container__title'] } }, children: [{ type: 'text', value: title }] });
+      }
+      node.children = children;
+      node.data = {
+        hName: 'div',
+        hProperties: {
+          className: ['dommief-container', `dommief-container--${type}`],
+          // warning/error là thông tin cần chú ý ngay → role="alert" không đúng (nó ngắt screen reader);
+          // dùng role="note" cho mọi loại, kiểu nằm ở class.
+          role: 'note',
+          ...(title ? {} : { 'aria-label': type }),
+        },
+      };
+    });
+  };
+}
+
+function textOf(node: any): string {
+  let out = '';
+  visit(node, 'text', (t: any) => { out += t.value; });
+  return out.trim();
+}