@hanzo/ui

مقدّمة

مكتبة مكوّنات واحدة للويب والتطبيق الأصلي وسطح المكتب، على ركيزة واحدة. استيراد واحد، وجذر واحد، ولا شيء تضبطه.

@hanzo/ui هي مكتبة المكوّنات لدى Hanzo. يُرسم كل مكوّن عبر @hanzo/gui، وهو محرّك أنماط لـ React وReact Native يأخذ الأنماط على هيئة props ويترجمها على الويب إلى CSS ذرّي. ولأن المحرّك يعمل عبر المنصّات، فالمكتبة كذلك: Switch نفسه يُرسم على هيئة div في المتصفح، وعلى هيئة عرض أصلي على الهاتف.

لا بناء لفئات المنفعة هنا. لا Tailwind، ولا إضافة PostCSS، ولا بدائي من Radix تحت المكوّن، ولا سجل، ولا components.json، ولا CLI تنسخ المصدر إلى مستودعك. تثبّت حزمة وتستورد منها.

التثبيت والتصيير

pnpm add @hanzo/ui @hanzo/gui
main.tsx
import { Hanzo, Button } from '@hanzo/ui'

export default function App() {
  return (
    <Hanzo>
      <Button>Ship</Button>
    </Hanzo>
  )
}

هذا كل الإعداد. Hanzo هو الجذر، ويحمل ثلاثة أشياء كانت من قبل عمل كل تطبيق: إعداد gui الذي تُحل الرموز مقابله، وورقة الأنماط، والسمة. لا CSS لتستورده ولا مولّد لتشغّله — الورقة تُنتج حين تُنشر الحزمة، بتصيير كل مكوّن وجمع CSS الذي ينتجه ذلك التصيير، فيصل أول رسم وكل تصيير على الخادم ومعه قواعده.

الشيء الوحيد الذي ما زال المُضيف يفعله هو أن يقول للمُجمِّع إن react-native تعني react-native-web. هذا اسم مستعار واحد، وكل صفحة مُضيف تحت التثبيت تبيّن أين يوضع.

التنسيق props

التنسيق prop على المكوّن، والتنسيق المتجاوب هو الـ prop نفسها تحت مفتاح نقطة انكسار.

import { Button, Text, XStack, YStack } from '@hanzo/ui'

<YStack gap="$4" p="$5" $md={{ p: '$8' }}>
  <Text fontSize="$5" color="$color11">
    Balance
  </Text>
  <XStack gap="$2">
    <Button>Send</Button>
    <Button variant="outline">Receive</Button>
  </XStack>
</YStack>

نقاط الانكسار عروض دنيا، والجوال أولًا: $sm 640 و$md 768 و$lg 1024 و$xl 1280. القيمة التي تبدأ بـ $ رمز — لون، أو مقاس، أو درجة من تدرّج التباعد — وتُحل مقابل السمة، فيكون $background لونًا مختلفًا في الفاتح والداكن من غير أن يعلم موضع الاستدعاء. حجم الخط رمز دائمًا، وليس رقمًا أبدًا: fontSize="$3"، لا fontSize={14}. يستطيع الشخص أن يضع سُلّم خطه، فيتحرّك تدرّج $n معه؛ أما 14 المكتوبة في الشيفرة فلا. السُلّم في السمات.

التخطيط

الـ stack من flex. XStack يصفّ في صف، وYStack في عمود، وكلاهما يأخذ gap وitems وjustify. الشبكة شبكة CSS حقيقية، في @hanzo/ui/grid، ومساراتها تأتي من الحاوية لا من الأبناء — انظر الشبكة.

ما الذي يوجد أين

Importما هو
@hanzo/uiواجهة المكوّنات — كل بدائي، والـ stack، وسُلّم الخط، وHanzo.
@hanzo/ui/productطبقة التطبيق: الرسوم، وإطار الصفحة، ووسوم الحالة، وألواح التفاصيل، ومبدّل السمة.
@hanzo/ui/blocksالمحتوى بوصفه بيانات، والراسمات التي ترسمه.
@hanzo/ui/gridGrid وCell، على الويب فقط.
@hanzo/ui/product/pureالقواعد التي تجري عليها طبقة المنتج، من غير مكوّن ملصق.
@hanzo/ui/csssubstitute، للاختبارات التي لا يجيب عنها DOM بلا تتالٍ.
@hanzo/ui/nextغلاف Next الذي يضع الأسماء المستعارة للويب لدى المُجمِّعين.

صفحات الفهرس في هذا الموقع — المكوّنات والكتل والمنتج — تُقرأ من الحزمة نفسها: كل واحدة تصيّر أمثلة الوحدة إلى جانب مصدرها وتقتبس أنواعها.

أسئلة

هل أحتاج إلى Tailwind؟ لا. المكوّنات تأخذ props للنمط، والهوية خصائص CSS مخصصة. إن وصل تطبيق بسلاسل أصناف، قرأها Box وsx وcss عبر tw وحوّلها إلى الـ props نفسها؛ لا يصل إلى DOM صنف لم تعرّفه الحزمة.

هل هذا نسخ ولصق؟ لا. ثبّت الحزمة واستورد منها. المكوّنات تُرقَّم مع الحزمة، وخريطة exports هي ما يُحل عبره الـ subpath، فيظل الاستيراد العميق يعمل عبر الرقع.

أي أُطُر؟ أي مُصيِّر لـ React 19، ما إن يعرف المُجمِّع الاسم المستعار لـ react-native. هناك صفحات لـ Vite وNext وOne وExpo وTauri.

هل أستخدمه تجاريًا؟ نعم. Apache-2.0 أو MIT، حسب اختيارك.