جعبه جهت‌دار (DirectionalBox)

کانتینر RTL/LTR-aware — content-switch بسته به جهت document، یا override صریح

معرفی

DirectionalBox کانتینر کوچکی است که محتوا را بسته به جهت صفحه (RTL/LTR) سوییچ می‌کند. مثال غالب: لوگو/برند که در RTL باید چپ-تراز و در LTR راست-تراز باشد، یا متن کوتاهی که با ترتیب عناصر در دو جهت باید عوض شود.

سوییچ بر اساس جهت document

اول این، بعد آن

جزیره‌ی LTR در صفحه RTL

git commit -m "init"

جزیره‌ی RTL با dir صریح

این متن مستقل از جهت document همیشه RTL است.

زمین بازی

با تغییر dir می‌توانید سوییچ بین محتوای RTL/LTR را به‌صورت زنده ببینید.

زمین بازی

اول این، بعد آن

تنظیمات

چیدمان

جهت

کد این نمونه به‌صورت خودکار قابل تولید نیست — برای کد آماده‌ی copy/paste به بخش «استفاده» در بالای صفحه مراجعه کنید.

چه زمانی استفاده کنیم:

جای‌گذاری المان‌هایی که logical properties Tailwind برای آن‌ها کافی نیست (مثل ترتیب در یک flex یا یک متن hardcoded که جای کلمات عوض می‌شود)
وقتی نیاز است یک کامپوننت "جزیره‌ی LTR" در یک صفحه‌ی RTL باشد (مثلاً پیش‌نمایش instagram post که برند خود instagram LTR است)
override موقت جهت برای تست بصری

چه زمانی استفاده نکنیم:

95٪ موارد فقط با logical properties (ms-, me-, inset-inline-start-) حل می‌شود — این کامپوننت برای 5٪ باقی‌مانده است

استفاده

import { DirectionalBox } from '@parto-system-design/ui'

// Content-switch بر اساس جهت document
<DirectionalBox
  rtl={<>اول این، بعد آن</>}
  ltr={<>This first, then that</>}
/>

// همان children در هر دو جهت ولی با dir="rtl" قطعی (جزیره‌ی RTL در صفحه‌ی LTR)
<DirectionalBox dir="rtl">
  <p>این متن همیشه RTL است</p>
</DirectionalBox>

// همان children با تشخیص خودکار جهت document
<DirectionalBox>
  <p>این فقط dir document را می‌گیرد</p>
</DirectionalBox>

راهنمای استفاده

بکنید

برای جزیره‌ی LTR در صفحه‌ی RTL از dir="ltr" صریح استفاده کنید (مثلاً preview Instagram یا code block) - وقتی محتوا واقعاً بسته به جهت متفاوت است (نه فقط جای‌گذاری)، propهای rtl و ltr را پاس بدهید — این کامپوننت برای همان use-case طراحی شده است - برای layoutی که با logical properties حل می‌شود (ms-*, me-*, inset-inline-start-*) از Tailwind utilities استفاده کنید نه از این کامپوننت

نکنید

این کامپوننت را برای 95٪ موارد لایه‌بندی استفاده نکنید — logical properties کافی است - dir صریح را بدون دلیل override نکنید — اگر document RTL است، اکثر محتواها هم باید RTL بمانند - کل صفحه را داخل DirectionalBox نپوشانید — جهت document از <html dir> خوانده می‌شود و این کار redundant است

دسترسی‌پذیری

کامپوننت یک <div> ساده با attribute dir={resolvedDir} رندر می‌کند — مرورگر و screen reader جهت متن را به‌درستی تفسیر می‌کنند.
هیچ semantic role یا ARIA اضافه‌ای اعمال نمی‌شود؛ صرفاً یک wrapper جهت‌سنج است که data-slot="directional-box" دارد.
اگر داخل DirectionalBox عناصر تعاملی قرار دادید، مسئولیت accessibility آن‌ها (focus order, aria-label) با خود آن عناصر است.
تشخیص جهت در client-side انجام می‌شود (از useDocumentDirection)؛ در SSR fallback به dir="rtl" می‌شود — برای جلوگیری از hydration flicker، dir صریح بدهید.

نکته‌ی فنی

تشخیص جهت از useDocumentDirection می‌آید که dir attribute روی <html> را watch می‌کند. اگر prop dir پاس بدهید، آن detection را override می‌کند.