CodeBlock — بلوک کد

بلوک کد TDS سه کار را با هم انجام می‌دهد: زبان را می‌شناسد (از برچسب fence یا از خود کد)، هر توکن را به نقش معنایی (کلیدواژه، رشته، عدد، تابع…) می‌برد، و رنگ هر نقش را از توکن‌های تم می‌گیرد. نتیجه: یک کد در هر تم با همان ساختار، اما با رنگ‌بندی هویت همان تم دیده می‌شود، بی‌آنکه یک هگز در کامپوننت باشد.

وضعیت: beta · لایه: ۳ (@tokapps/tukکپی کد) + موتور زبان @tokapps/codeکپی کد (بدون UI) · توکن‌ها: packages/tokens/src/component/code-block.cssکپی کد

import { CodeBlock } from '@tokapps/tuk';

نمونهٔ زنده در شش تم

هر نمونه با data-themeکپی کد و data-modeکپی کد خودش رنگ می‌گیرد؛ کد یکسان است، هویت متفاوت.

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

// نمونهٔ یکسان برای همهٔ تم‌ها — کامنت فارسی هم جهت خودش را حفظ می‌کندexport const launch = (idea: Idea) => {  const score: number = idea.votes * 2;  return score > 10 ? "پرطرفدار" : 'در انتظار';};

قاب حرفه‌ای: تراشه، شماره خط و پاورقی

قاب بلوک کد سه بخش دارد. سرِ کد تراشهٔ زبان و نام فایل را نشان می‌دهد و دکمهٔ کپی را کنار آن دارد. بدنه شماره خط را با جداکنندهٔ نازک نشان می‌دهد و خط‌های برجسته را علامت می‌زند. پاورقی (footerکپی کد) نوار اختیاری کم‌ارتفاع زیر کد است، برای اطلاعات کمکی مثل تعداد خط یا کدگذاری. سایه، لبهٔ سرِ کد، تراشه و نوار اسکرول فقط از توکن‌های --tds-code-*کپی کد می‌آیند؛ هر تم فقط حرکت تأیید کپی و رنگ خودش را تعیین می‌کند.

export const sum = (a: number, b: number) => a + b;export const avg = (a: number, b: number) => sum(a, b) / 2;

export const sum = (a: number, b: number) => a + b;export const avg = (a: number, b: number) => sum(a, b) / 2;

کد نمونه (قابل کپی)

import { CodeBlock } from '@tokapps/tuk';<CodeBlock  code={'export const sum = (a: number, b: number) => a + b;\nexport const avg = (a: number, b: number) => sum(a, b) / 2;'}  languageId="typescript"  language="TypeScript"  title="math.ts"  lineNumbers  highlight={[2]}  footer="۲ خط · UTF-8"/>

کد درون‌خطی (InlineCodeکپی کد)

کد کوتاه وسط جمله، مثل pnpm add @tokapps/tukکپی کد یا نام کامپوننت Buttonکپی کد، با <code>کپی کد ساده نمی‌ماند: یک کلیک آن را کپی می‌کند و لازم نیست متن را دستی انتخاب کنید. این رفتار در همهٔ بخش‌های سایت برقرار است؛ در پاراگراف، تیتر، جدول و فهرست فرقی ندارد.

• با ماوس روی تراشه کلیک کنید، یا با Tabکپی کد فوکوس کنید و Enterکپی کد یا Spaceکپی کد بزنید.
• با hover یا فوکوس کیبورد، برچسب «کپی کد» ظاهر می‌شود. پس از کپی، تراشه رنگ تأیید می‌گیرد و برچسب «کپی شد» نشان داده می‌شود.
• شکل، رنگ و حرکت هر تم را توکن‌ها و فایل inline-code.cssکپی کد همان تم تعیین می‌کنند؛ رفتار کپی در همه ثابت است.

حالت‌ها

پیکربندی

نمونه‌های زنده و کد هر حالت

هر حالت یک پیش‌نمایش زنده و یک بلوک کد قابل‌کپی دارد. کد از همان شیء نمونهٔ پیش‌نمایش ساخته می‌شود.

import { InlineCode } from '@tokapps/tuk';<InlineCode>pnpm add @tokapps/tuk</InlineCode>

import { InlineCode } from '@tokapps/tuk';<InlineCode tone="brand">InlineCode</InlineCode>

import { InlineCode } from '@tokapps/tuk';<InlineCode copyText="pnpm install">pnpm i</InlineCode>

import { InlineCode } from '@tokapps/tuk';<InlineCode>packages/tuk/src/data-display/inline-code/InlineCode.tsx</InlineCode>

import { InlineCode } from '@tokapps/tuk';<InlineCode tone="brand">dock.slots</InlineCode>

در شش تم

هر تم روشن و تیره. کد هر تم همان دو divکپی کد با data-themeکپی کد و data-modeکپی کد است.

import { InlineCode } from '@tokapps/tuk';<div data-theme="tokapps" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="tokapps" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

import { InlineCode } from '@tokapps/tuk';<div data-theme="ideation" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="ideation" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

import { InlineCode } from '@tokapps/tuk';<div data-theme="funding" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="funding" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

import { InlineCode } from '@tokapps/tuk';<div data-theme="product-hunt" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="product-hunt" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

import { InlineCode } from '@tokapps/tuk';<div data-theme="stories" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="stories" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

import { InlineCode } from '@tokapps/tuk';<div data-theme="enterprise" data-mode="light">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div><div data-theme="enterprise" data-mode="dark">  <InlineCode>pnpm add @tokapps/tuk</InlineCode></div>

کد نمونهٔ استفاده

import { InlineCode } from '@tokapps/tuk';<p>  برای نصب از <InlineCode copyText="pnpm add @tokapps/tuk">pnpm add</InlineCode> استفاده کنید.</p>

قواعد استفاده

• برای کد چندخطی یا شماره‌دار از CodeBlockکپی کد استفاده کنید؛ InlineCodeکپی کد فقط برای یک عبارت کوتاه وسط متن است.
• تراشه خودش دکمه است؛ آن را داخل دکمه یا لینک قرار ندهید.
• در MDX، هر کد درون‌خطی (`…`کپی کد) به‌صورت خودکار InlineCodeکپی کد می‌شود؛ نیازی به نوشتن دستی نیست.

پکیج‌های استفاده‌شده

بررسی‌شده و کنار گذاشته: highlight.jsکپی کد (حدس زبان خوب، ولی گرامرهای regex دقت کمتری دارند و هم‌زمان حدس و رنگ‌بندی را قاطی می‌کند)؛ Prismکپی کد (گرامر TextMate ندارد، رنگ‌بندی سطحی)؛ خود Shiki با تم‌های رنگی (رنگ را داخل HTML می‌نشاند و با قانون «رنگ فقط از توکن» سازگار نیست؛ ما رنگ را به CSS و تم می‌سپاریم).

جریان داده

برچسب fence (ts، bash…) → normalizeLanguage ─┐                                              ├→ highlightCode (Shiki + scope) → نقش هر توکنبدون برچسب → detectLanguage (حدس از محتوا) ─┘                                                          ▼TUK CodeBlock → <span data-kind="keyword"> → color: var(--tds-syntax-keyword) → هویت تم

در MDX این جریان خودکار است: هر بلوک fence روی سرور هایلایت می‌شود (بدون پرش رنگ). در صفحات کلاینتی CodeBlockکپی کد از apps/docs/src/siteکپی کد بعد از hydrate رنگ می‌گیرد.

شناخت زبان برنامه‌نویسی

۱. از برچسب fence. اگر نویسنده زبان را نوشته باشد، همان مرجع است. مستعارها به زبان استاندارد می‌روند:

۲. بدون برچسب: حدس از محتوا. detectLanguageکپی کد قطعی و بدون مدل است: اول اگر کل متن JSON معتبر باشد، JSON است. بعد نشانه‌های هر زبان (مثلاً def …:کپی کد و self.کپی کد برای Python، fn …(کپی کد و let mutکپی کد برای Rust، interface X {کپی کد و : stringکپی کد برای TypeScript، className=کپی کد برای JSX، $ pnpmکپی کد برای Shell) امتیاز می‌گیرند. زبانی که امتیازش به ۳ برسد انتخاب می‌شود؛ وگرنه متن ساده. ترجیح ما بدون رنگ بودن در حدس مشکوک است؛ رنگ اشتباه از بی‌رنگی بدتر است.

مهندسی قلم و جهت

توکن‌های رنگ سینتکس

هر نقش یک توکن --tds-syntax-<نقش>کپی کد دارد. مقدارها از فام (hue) و کروما می‌آیند؛ روشنایی (L) به‌تفکیک روشن/تیره است تا کنتراست AA تضمین شود.

check:tokensکپی کد هر ۲۰ نقش را در هر تم × روشن/تیره × کنتراست عادی/بالا روی سطح کد به AA می‌سنجد؛ تم جدیدی که کنتراست را بشکند، نمی‌تواند منتشر شود.

طرح رنگ بلوک (روشن یا تیره، مستقل از صفحه)

بلوک کد طرح رنگ خودش را دارد و این انتخاب با تم است: هر تم در فراداده‌اش codeSchemeکپی کد (lightکپی کد یا darkکپی کد) دارد. بلوک با schemeکپی کد همان را می‌گیرد، پس یک صفحهٔ روشن می‌تواند بلوک تیرهٔ تم «tokapps» داشته باشد و برعکس. بدون schemeکپی کد، بلوک از حالت صفحه پیروی می‌کند.

import { CodeBlock } from '@tokapps/tuk';import { meta } from '@tokapps/theme-tokapps/meta';<CodeBlock code={source} language="TypeScript" scheme={meta.codeScheme} />

مقدارهای هر طرح صریح‌اند (data-code-scheme="light|dark"کپی کد روی بلوک) و به سطح صفحه وابسته نیستند؛ check:tokensکپی کد هر دو طرح را در هر تم به AA می‌سنجد.

شخصی‌سازی در هر تم

هر تم فقط شش فام و یک کروما را تعیین می‌کند (فایل packages/theme-<id>/src/code-block.cssکپی کد). ساختار و قلم ثابت‌اند.

تم سفارشی برای برند خودتان:

/* تم جدید: فقط توکن؛ بدون دست‌زدن به کامپوننت */[data-theme="my-brand"] {  --tds-code-chroma: 0.14;  --tds-code-hue-keyword: 310;  --tds-code-hue-string: 140;  --tds-code-hue-number: 70;  --tds-code-hue-function: 230;  --tds-code-hue-type: 200;  --tds-code-hue-tag: 15;}

بازنویسی یک نقش به‌تنهایی (مثلاً رشته‌ها باید دقیقاً این رنگ باشند):

[data-theme="my-brand"] {  --tds-syntax-string: oklch(0.45 0.12 150);}[data-theme="my-brand"][data-mode="dark"] {  --tds-syntax-string: oklch(0.82 0.12 150);}

قاعدهٔ کار: هر بازنویسی باید با pnpm check:tokensکپی کد سبز بماند؛ اگر کنتراست پایین بیاید، اسکریپت نقش و نسبت را گزارش می‌کند.

استفاده

در MDX: هیچ کاری لازم نیست؛ هر بلوک fence با برچسب زبان (مثلاً tsکپی کد) خودکار هایلایت و قابل‌کپی است.

در React (با رشتهٔ کد):

import { highlightCode } from '@tokapps/code';import { CodeBlock } from '@tokapps/tuk';export async function Snippet({ source }: { source: string }) {  const { language, lines } = await highlightCode(source, 'tsx');  return (    <CodeBlock      code={source}      lines={lines}      languageId={language?.id}      language={language?.label}      family={language?.family}      ligatures={language?.ligatures}      title="Card.tsx"      lineNumbers      highlight={[3]}    />  );}

بدون هایلایت (فقط متن و کپی): <CodeBlock code="npm i @tokapps/tuk" language="Shell" />کپی کد — سینتکس ندارد و همان ساختار را دارد.

دسترس‌پذیری، چاپ و حالت‌های سیستم

• <pre>کپی کد با tabindex="0"کپی کد و aria-labelکپی کد «کد TypeScript» (یا «بلوک کد») قابل پیمایش با صفحه‌کلید است؛ حلقهٔ فوکوس حذف نمی‌شود.
• دکمهٔ کپی برچسبش را به «کپی شد» تغییر می‌دهد و یک ناحیهٔ role="status"کپی کد همان پیام را اعلام می‌کند.
• رنگ تنها نشانه نیست: خط برجسته لبهٔ ضخیم دارد و diff با +کپی کد/-کپی کد مشخص است.
• forced-colorsکپی کد: رنگ سینتکس به CanvasTextکپی کد برمی‌گردد.
• بدون انیمیشن؛ کپی بدون جابه‌جایی است.
• چاپ: دکمهٔ کپی پنهان و کد با pre-wrapکپی کد چاپ می‌شود.

قرارداد توکن و فراداده

• بنیان بدون رنگ خام: packages/tuk/src/data-display/code-block/code-block.cssکپی کد فقط var(--tds-…)کپی کد مصرف می‌کند (تست CodeBlock.test.tsxکپی کد این را می‌سنجد).
• فراداده: CodeBlock.metadata.jsonکپی کد (برای MCP و مستندات).
• شش تم هر کدام یک فایل code-block.cssکپی کد دارند و در index.tsکپی کد ثبت شده‌اند.

تغییرات مجاز برای توسعه‌دهنده

• خانوادهٔ قلم (familyکپی کد): codeکپی کد (پیش‌فرض)، dataکپی کد، markupکپی کد، shellکپی کد، diffکپی کد.
• لیگاچر (ligaturesکپی کد): پیش‌فرض بر اساس خانواده است (codeکپی کد و markupکپی کد روشن). می‌توان دستی تنظیمش کرد.
• طرح رنگ (schemeکپی کد): lightکپی کد یا darkکپی کد. نبود آن یعنی پیروی از حالت صفحه. تم‌ها با codeSchemeکپی کد پیش‌فرض می‌دهند.
• خط‌های توکن‌شده (linesکپی کد): خروجی @tokapps/codeکپی کد یا هر منبعی با ساختار CodeTokenکپی کد.
• شماره خط و برجسته: lineNumbersکپی کد و highlightکپی کد (شماره از ۱).
• عنوان و زبان: titleکپی کد، languageکپی کد، languageIdکپی کد.
• متن‌ها: copyLabelکپی کد و copiedLabelکپی کد برای ترجمه.
• کلاس ریشه: classNameکپی کد روی figureکپی کد، برای فاصله‌گذاری (نه رنگ).
• توکن سطح کامپوننت: --tds-code-*کپی کد برای بنیان و --tds-syntax-*کپی کد همراه شش فام هویت (--tds-code-hue-*کپی کد) و کروما.

تغییرات ممنوع (بنیان ثابت)

• ساختار DOM: figureکپی کد با figcaptionکپی کد، سپس preکپی کد با tabindex="0"کپی کد و aria-labelکپی کد، سپس codeکپی کد و خط‌ها. تبدیل preکپی کد به divکپی کد بدون tabindexکپی کد ممنوع است.
• کپی: حذف دکمهٔ کپی یا کپی کردن چیزی غیر از codeکپی کد.
• ناحیهٔ اعلام کپی: حذف role="status"کپی کد یا aria-labelکپی کد روی preکپی کد.
• جهت: تغییر dir="ltr"کپی کد روی figureکپی کد.
• رنگ: رنگ خام، هگز یا گرادیان در CSS بنیان. تست CodeBlock.test.tsxکپی کد این را می‌شکند.
• فوکوس: حذف حلقهٔ فوکوس روی preکپی کد یا دکمه.
• هایلایت: هایلایت بدون لبهٔ ضخیم، چون رنگ تنها نشانه نیست.
• دسترس‌پذیری سیستم: حذف قاعدهٔ forced-colorsکپی کد و قاعدهٔ چاپ.

صدا، حرکت، چاپ و کاهش حرکت

• صدا: کامپوننت بی‌صدا است و پراپ صدا در کد تعریف نشده است. معادل بصری کپی، تغییر برچسب و اعلام role="status"کپی کد است.
• حرکت: بلوک انیمیشن ندارد و بنابراین کاهش حرکت برای آن لازم نیست. بازگشت برچسب دکمه پس از حدود ۱٫۴ ثانیه بدون انیمیشن است.
• چاپ: دکمهٔ کپی پنهان است، preکپی کد با pre-wrapکپی کد چاپ می‌شود و بلوک break-inside: avoidکپی کد دارد.

قرارداد ARCH

• آیکون‌های کپی و تأیید فقط با Iconکپی کد و نام معنایی copyکپی کد و checkکپی کد (داخل Button) نمایش داده می‌شوند؛ مسیر فایل آیکون وجود ندارد.
• بنیان بدون رنگ خام است. هویت سینتکس فقط از --tds-syntax-*کپی کد و فام‌های --tds-code-hue-*کپی کد می‌آید.
• تم فقط توکن‌ها را عوض می‌کند؛ DOM و رفتار ثابت‌اند.
• این کامپوننت gesture ندارد. معادل کیبوردی آن Tabکپی کد به preکپی کد و دکمهٔ کپی، و Enterکپی کد یا Spaceکپی کد برای کپی است.

محدودیت‌ها و گام بعد

• ۱۶ زبان فعلی؛ افزودن زبان یعنی یک مدخل در LANGUAGESکپی کد، ALIASESکپی کد، LOADERSکپی کد و RULESکپی کد (تشخیص).
• حدس زبان بر پایهٔ نشانه‌های ساده است؛ برای کدهای خیلی کوتاه (کمتر از یک خط معنادار) ممکن است متن ساده برگردد.
• هایلایت خط‌های +کپی کد و -کپی کد فقط برای زبان diffکپی کد رنگی است.
• دکمهٔ «جمع‌کردن» و «نمایش کامل» برای بلوک‌های بلند در فاز بعد است.