shadowzzh

blocks.ts

blocks.ts
// MDX 自訂 block 的**單一真實來源**:`koimsurai_list_blocks`(結構化目錄)、
// `koimsurai_validate_mdx`(未知元件偵測)、撰寫指南第 4 節(由此生成)三者共用。
//
// ⚠️ 前台新增 block 時:在 src/components/mdx/mdx-blocks-registry.ts 的 MDX_BLOCKS 註冊後,這裡也要補一筆
//    (否則 validate 會把它誤報成「未知元件」,agent 也不會知道有這個 block 可用)。

export interface BlockDef {
  /** 標籤名,例如 'Chart' */
  name: string;
  category: 'prose' | 'code' | 'data' | 'media' | 'layout' | 'interactive';
  /** 一句話:這是什麼 */
  summary: string;
  /** 什麼情況該用它(給 agent 選型用,寫得具體) */
  whenToUse: string;
  /** props 說明 */
  props?: string;
  /** 可直接抄的範例 */
  example: string;
  /** 坑 / 注意事項 */
  note?: string;
  /** 這是某個容器的子元件(例如 Tab 之於 Tabs),列表時標示用 */
  childOf?: string;
}

export const BLOCKS: BlockDef[] = [
  // ── prose:文字表達 ───────────────────────────────────────────
  {
    name: 'Note',
    category: 'prose',
    summary: '站長旁白(極簡左側線條 + 引號圖標)',
    whenToUse: '想以作者身分插一段題外話、心境、事後補充;跟彩色 alert 的「提醒」語氣明確區隔。',
    props: 'title(標籤文字,預設「站長註」)',
    example: '<Note title="站長註">這段當初卡很久,後來才想通…</Note>',
  },
  {
    name: 'Annot',
    category: 'prose',
    summary: '行內註解:hover 某個詞冒出小卡',
    whenToUse: '文中出現讀者可能不懂的術語/縮寫時,就地科普,不打斷行文。科普向長文請多用。',
    props: 'note(註解內容,屬性字串)',
    example: '這條走 <Annot note="Server-Side Rendering,伺服器先把 HTML 渲染好再送出">SSR</Annot>。',
    note: '同一段落別塞太多(3 個以上會很吵);程式碼區塊、mermaid、圖片 alt 內不要用。',
  },
  {
    name: 'Spoiler',
    category: 'prose',
    summary: '防劇透:內容模糊,點擊揭開',
    whenToUse: '劇情、答案、結論想讓讀者自己先想一下再看。',
    example: '兇手是 <Spoiler>管家</Spoiler>。',
  },
  {
    name: 'Kbd',
    category: 'prose',
    summary: '鍵盤按鍵樣式',
    whenToUse: '提到快捷鍵時。',
    example: '按 <Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> 複製。',
  },
  {
    name: 'Ruby',
    category: 'prose',
    summary: 'CJK 注音(漢字上方標讀音)',
    whenToUse: '日文文章的難讀漢字/固有名詞;中文極少用。',
    props: 'text(漢字)、reading(讀音)',
    example: '<Ruby text="漢字" reading="かんじ" />',
  },
  {
    name: 'Mention',
    category: 'prose',
    summary: '社群帳號徽章(GitHub / X)',
    whenToUse: '提到某個人的帳號時。',
    props: 'platform(github|x)、user',
    example: '<Mention platform="github" user="innei" />',
  },
  {
    name: 'Math',
    category: 'prose',
    summary: 'KaTeX 數學公式',
    whenToUse: '需要真正的數學排版時。',
    props: 'tex(公式,屬性字串)、display(true = 區塊置中)',
    example: '行內 <Math tex="E=mc^2" />;區塊 <Math tex="\\\\int_0^1 x\\\\,dx" display />',
    note: 'tex 一定用屬性字串傳,否則公式裡的 { } 會被 MDX 當表達式。',
  },

  // ── code:程式碼呈現 ──────────────────────────────────────────
  {
    name: 'Diff',
    category: 'code',
    summary: '程式碼前後對比(+ 綠 / − 紅,仍有語法高亮)',
    whenToUse: '「這行改成那行」的修法對照——除錯文的主力,比貼兩份完整程式碼好讀太多。',
    props: 'code(屬性字串,行首 + 新增、- 刪除)、lang(base 語言)、title',
    example: '<Diff lang="ts" title="修法" code={`-const a = 1\\n+const a = 2`} />',
    note: '多行用範本字面值,\\n 分行。',
  },
  {
    name: 'CodeTabs',
    category: 'code',
    summary: '多檔程式碼分頁(依副檔名帶檔案圖示)',
    whenToUse: '同一份改動牽涉多個檔案時,讓讀者切著看。',
    props: 'files=[{ name, lang, code }]',
    example:
      "<CodeTabs files={[{ name: 'index.ts', lang: 'ts', code: '…' }, { name: 'test.ts', lang: 'ts', code: '…' }]} />",
  },
  {
    name: 'Install',
    category: 'code',
    summary: '套件安裝指令分頁(自動生 npm/pnpm/yarn/bun)',
    whenToUse: '要讀者裝某個套件時,別自己手打四種指令。',
    props: 'pkg(套件名)、dev(開發依賴)',
    example: '<Install pkg="react-compare-slider" />',
  },
  {
    name: 'FileTree',
    category: 'code',
    summary: '專案結構樹(資料夾/檔案圖示)',
    whenToUse: '介紹專案目錄結構、說明檔案放哪時。',
    props: 'tree(屬性字串;每 2 空格一層,結尾 / 為資料夾)',
    example: '<FileTree tree={`src/\\n  components/\\n    Button.tsx\\n  index.ts\\npackage.json`} />',
  },

  // ── data:數據視覺化 ──────────────────────────────────────────
  {
    name: 'Chart',
    category: 'data',
    summary: '各種圖表(line/area/bar/pie/donut/scatter/radar,色盲安全色盤)',
    whenToUse: '有多筆數據要比較或看趨勢時。',
    props: 'type、data、series(多序列的欄位名)、categoryKey、xKey/yKey(scatter)、stacked、title、unit、height',
    example:
      '<Chart type="line" data={[{ label:\'v1\', A:20, B:12 }]} series={[\'A\',\'B\']} title="吞吐趨勢" unit="tok/s" />',
    note: 'pie/donut 用 data={[{ label, value }]};scatter 用 data={[{ x, y }]} 搭 xKey/yKey。',
  },
  {
    name: 'BarChart',
    category: 'data',
    summary: '單色階長條圖(Chart 的簡化版)',
    whenToUse: '只是幾個數字的單純對比(benchmark),不需要多序列時。',
    props: 'data=[{ label, value }]、title、unit',
    example:
      '<BarChart title="吞吐對比" unit="tok/s" data={[{ label: \'int8\', value: 42 }, { label: \'fp16\', value: 31 }]} />',
  },
  {
    name: 'InteractiveChart',
    category: 'data',
    summary: '互動圖表:讀者拉滑桿即時改值重繪',
    whenToUse: '想讓讀者自己試「如果參數變成 X 會怎樣」。',
    props: 'type(bar|line|area)、data=[{ label, value }]、title、unit、min/max/step',
    example: '<InteractiveChart type="bar" data={[{ label:\'方案A\', value:40 }]} title="延遲估算" unit="ms" />',
  },
  {
    name: 'Stats',
    category: 'data',
    summary: '數字磚容器(一排 KPI)',
    whenToUse: '想把幾個關鍵數字(前後對比、量測結果)做成醒目的一排。',
    example: '<Stats><Stat label="吞吐" value="42" unit="tok/s" trend="up" /></Stats>',
  },
  {
    name: 'Stat',
    category: 'data',
    childOf: 'Stats',
    summary: '單一數字磚',
    whenToUse: '放在 <Stats> 裡。',
    props: 'label、value、unit、trend(up|down|flat)、hint(小字補充)',
    example: '<Stat label="延遲" value="8" unit="ms" trend="down" hint="原 64ms" />',
    note: 'value 儘量短;「A → B」這種長字串改成 value="B" + hint="原 A"。',
  },

  // ── media:圖與影片 ───────────────────────────────────────────
  {
    name: 'ImageCompare',
    category: 'media',
    summary: '前後圖對比滑桿(拖曳分隔線)',
    whenToUse: 'UI 改版、修圖前後、破圖修復——兩張同構圖的對照。',
    props: 'before、after(圖片 URL)、beforeLabel、afterLabel、caption、alt',
    example:
      '<ImageCompare before="/uploads/a.png" after="/uploads/b.png" beforeLabel="修前" afterLabel="修後" caption="…" />',
    note: '圖片先用 koimsurai_upload_image 上傳拿 /uploads/… 網址。',
  },
  {
    name: 'Sketch',
    category: 'media',
    summary: 'Excalidraw 手繪風靜態圖(吃 mermaid 定義)',
    whenToUse: '**概念草圖/比喻/心智模型**——像在白板上隨手畫的示意圖。節點少(≤6)、不需要讀者操作時用它。',
    props: 'chart(mermaid 定義,單行用 ; 分隔)、title',
    example: '<Sketch chart="graph TD; A[想法] --> B[草稿]; B --> C[成品]" title="心智模型" />',
    note: '**精確的技術圖用 ```mermaid 圍籬,不要用這個**:流程/時序/狀態/ER/架構、節點多、讀者可能想放大細看或下載時——mermaid 有工具列(切配色、縮放平移、全螢幕、下載 SVG/PNG),Sketch 是靜態的、寬度上限 440px。手繪風只有 Sketch 有。',
  },
  {
    name: 'Video',
    category: 'media',
    summary: '自架影片播放器',
    whenToUse: '有錄好的操作示範/畫面錄影(先上傳到 /uploads)。',
    props: 'src、poster、caption',
    example: '<Video src="/uploads/demo.mp4" poster="/uploads/cover.png" caption="操作示範" />',
  },
  {
    name: 'YouTube',
    category: 'media',
    summary: 'YouTube 嵌入(點擊才載入,對隱私/CSP 友善)',
    whenToUse: '要引用 YouTube 影片時。',
    props: 'id(影片 ID)、title',
    example: '<YouTube id="dQw4w9WgXcQ" title="示範影片" />',
  },

  // ── layout:結構編排 ──────────────────────────────────────────
  {
    name: 'Steps',
    category: 'layout',
    summary: '編號要點/步驟(數字圈 + 標題 + 內文)',
    whenToUse:
      '**凡是「一、二、三」這種編號清單都用它**——教學流程、三個問題/發現/原因、依序拆解的分析。不要自己在正文打「**一、…**」粗體編號。',
    example: '<Steps><Step title="無樣式閃爍">…</Step><Step title="雙渲染">…</Step></Steps>',
  },
  {
    name: 'Step',
    category: 'layout',
    childOf: 'Steps',
    summary: '單一步驟/要點',
    whenToUse: '放在 <Steps> 裡。',
    props: 'title',
    example: '<Step title="裝依賴">…整段說明,可含 code、其他 block…</Step>',
    note: '內容要頂左寫、前後留空行才會被當 markdown 解析(縮排 4 空格會變程式碼區塊)。',
  },
  {
    name: 'Tabs',
    category: 'layout',
    summary: '內容分頁(藥丸切換,每頁一整段內容)',
    whenToUse: '同一件事的多種做法/取捨對照,讓讀者切著比較。',
    example: '<Tabs><Tab title="做法 A(推薦)">…</Tab><Tab title="做法 B">…</Tab></Tabs>',
  },
  {
    name: 'Tab',
    category: 'layout',
    childOf: 'Tabs',
    summary: '單一分頁',
    whenToUse: '放在 <Tabs> 裡。',
    props: 'title(藥丸標籤)',
    example: '<Tab title="做法 A">…</Tab>',
    note: '內容要頂左寫、前後留空行(同 Step)。',
  },
  {
    name: 'Details',
    category: 'layout',
    summary: '段落級收合(點 summary 展開)',
    whenToUse: '冗長的 log/完整證明/有趣但離題的旁支——想留著又不想打斷主線時。',
    props: 'summary(收合時顯示的標題)、open(預設展開)',
    example: '<Details summary="番外:完整錯誤 log">…</Details>',
  },
  {
    name: 'Refs',
    category: 'layout',
    summary: '文末參考連結區(依網域自動帶品牌 icon)',
    whenToUse: '有參考資料/延伸閱讀清單時。**別用裸網址的 markdown list**(那會每條都彈 hover 卡、很吵)。',
    props: 'items=[{ label, links: [{ text, href }] }]、title',
    example:
      "<Refs items={[{ label: 'TanStack Start', links: [{ text: '官網', href: 'https://tanstack.com/start' }] }]} />",
    note: '站內文章想要「卡片」樣式,改成讓整段只放一個 /blog/ 連結(會自動變站內文章卡)。',
  },

  // ── interactive:讀者互動 ─────────────────────────────────────
  {
    name: 'Poll',
    category: 'interactive',
    summary: '內嵌投票(真投票,票數存後端)',
    whenToUse: '想收集讀者意見/技術選型統計時,例如「你的專案用哪個方案?」。',
    props: 'id(全站唯一)、question、options=[{ key, label }]、showTotal',
    example:
      "<Poll id=\"blog-render\" question=\"你的部落格怎麼渲染?\" options={[{ key: 'ssr', label: '單次 SSR' }, { key: 'isr', label: 'SSG/ISR' }]} />",
    note: '⚠ id 與 option key 一旦發布就不可改(改了等於換一份投票、票數歸零);label 才是顯示文字。同一瀏覽器只能投一次。',
  },
];

/** 所有合法標籤名(validate 用來偵測未知元件)。 */
export const BLOCK_NAMES = new Set(BLOCKS.map((b) => b.name));

const CATEGORY_LABEL: Record<BlockDef['category'], string> = {
  prose: '文字表達',
  code: '程式碼',
  data: '數據視覺化',
  media: '圖與影片',
  layout: '結構編排',
  interactive: '讀者互動',
};

/** 撰寫指南第 4 節:由 BLOCKS 生成,確保指南與目錄永遠同步。 */
export function renderBlocksForGuide(): string {
  const order: BlockDef['category'][] = ['prose', 'code', 'data', 'media', 'layout', 'interactive'];
  const lines: string[] = [];
  for (const cat of order) {
    const items = BLOCKS.filter((b) => b.category === cat && !b.childOf);
    if (!items.length) continue;
    lines.push(`### ${CATEGORY_LABEL[cat]}`);
    for (const b of items) {
      const children = BLOCKS.filter((c) => c.childOf === b.name);
      lines.push(`- **<${b.name}>** ${b.summary}`);
      lines.push(`  用時機:${b.whenToUse}`);
      if (b.props) lines.push(`  props:${b.props}`);
      lines.push(`  例:${b.example}`);
      if (b.note) lines.push(`  ⚠ ${b.note}`);
      for (const c of children) {
        lines.push(
          `  - **<${c.name}>**(${b.name} 的子元件)${c.summary}|例:${c.example}${c.note ? `|⚠ ${c.note}` : ''}`,
        );
      }
    }
    lines.push('');
  }
  return lines.join('\n').trimEnd();
}