التهيئة

إعدادات عامة لكل مكوّن Zephora — غلّف تطبيقك مرة واحدة بـ ZephoraConfigProvider وهيّئ اللغة، وطبقات z-index للتراكب (overlay)، وحاوية portal، والافتراضي بلا واجهة (headless).

الإعداد

import { ZephoraConfigProvider } from "@zephora/react";

export default function App() {
  return (
    <ZephoraConfigProvider
      locale="tr"
      zIndex={{ modal: 2000, toast: 2100 }}
      appendTo={typeof document !== "undefined" ? document.body : null}
      unstyled={false}
    >
      <YourApp />
    </ZephoraConfigProvider>
  );
}

ZephoraConfigProvider props

الخاصية	النوع	الافتراضي	الوصف
`locale`	`string`	`"en"`	Active locale for component UI strings. Only "en" is embedded; load others from @zephora/theme/locales/* (module or JSON) and register with addLocale().
`zIndex`	`{ dropdown?, overlay?, modal?, popover?, toast?, tooltip?: number }`	—	Overrides the layering of floating elements. Written as --z-index-* CSS variables on the root element.
`appendTo`	`HTMLElement \| null`	`document.body`	Container that Portal-based overlays (Dialog, Select menus, Tooltip…) render into.
`unstyled`	`boolean`	`false`	Makes every component headless by default for Tailwind-first apps. A per-component unstyled prop still wins.

قراءة التهيئة

import { useZephoraConfig, useLocale } from "@zephora/react";

function MyField() {
  const config = useZephoraConfig(); // { locale, zIndex, appendTo, unstyled }
  const { t, messages, locale } = useLocale();
  return <button aria-label={t("close")} />;
}

طبقات z-index

تأخذ المكوّنات ترتيب تراصّها من متغيّرات CSS مع قيم احتياطية مدمجة، بحيث يمكن لكل من الـ provider وCSS العادي إعادة ضبطها:

:root {
  --z-index-dropdown: 1000;
  --z-index-overlay: 1040;
  --z-index-modal: 1050;
  --z-index-popover: 1060;
  --z-index-toast: 1070;
  --z-index-tooltip: 1080;
}

الوضع الداكن

يأتي @zephora/theme بمساعِدات وضع داكن تلقائية. يحلّ hook الـ useColorScheme نظام ألوان (مع mode: "system" يتبع تفضيل نظام التشغيل مباشرة) ويطبّق افتراضيًا السمة المحلولة عالميًا:

import { useColorScheme } from "@zephora/theme";

function App() {
  // mode: "light" | "dark" | "system" (default "system")
  const { scheme, theme } = useColorScheme({ mode: "system" });
  return <span>Active scheme: {scheme}</span>;
}

useColorScheme(options) props

الخاصية	النوع	الافتراضي	الوصف
`mode`	`"light" \| "dark" \| "system"`	`"system"`	"system" follows the OS preference live; "light"/"dark" force a scheme.
`light / dark`	`Theme`	`lightTheme / darkTheme`	Theme objects used for each scheme.
`apply`	`boolean`	`true`	Write the resolved theme to document.documentElement via applyTheme.
`→ returns`	`{ scheme: "light" \| "dark"; theme: Theme }`	—	The resolved scheme and the theme object in effect.

تُصدَّر أيضًا الأوّليات (primitives) الأدنى مستوى:

import { getSystemColorScheme, watchSystemColorScheme } from "@zephora/theme";

// Reads the OS color scheme (SSR-safe; defaults to "light").
const scheme = getSystemColorScheme(); // "light" | "dark"

// Subscribes to OS changes. Returns an unsubscribe function.
const stop = watchSystemColorScheme((next) => console.log(next));
stop();

SSR خالٍ من FOUC

للـ render من الخادم، يبني colorSchemeCss(light?, dark?) ورقة أنماط ثابتة تبدّل السمات وفق تفضيل نظام التشغيل — دون وميض السمة الخاطئة، ودون حاجة إلى JavaScript قبل الرسم. تعيين data-zephora-scheme على <html> يتجاوز استعلام الوسائط (اربطه بمفتاح تبديل للمستخدم):

import { colorSchemeCss } from "@zephora/theme";

// Next.js app router — app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <style dangerouslySetInnerHTML={{ __html: colorSchemeCss() }} />
      </head>
      <body>{children}</body>
    </html>
  );
}

أصناف الفتحات (Slot classNames)

تكشف المكوّنات متعددة الفتحات (Dialog، Sheet، Tabs، Card، Popover، Tooltip…) عقد صنف لكل فتحة: يقبل الجذر classNames مُنمّطة كـ Partial<Record<<Name>Slot, string>> (تُصدَّر اتحادات أسماء الفتحات مثل DialogSlot). تُضاف أصناف الفتحات بعد أصناف الوحدة ولا يحكمها unstyled — فهي تعمل في الوضعين المنسّق وغير المنسّق؛ وفي الوضع غير المنسّق تكون هي الأصناف الوحيدة. يدمج classNames.root جنبًا إلى جنب مع خاصية className الحالية، التي تظل تستهدف الجذر وتُطبَّق أخيرًا. في المكوّنات المركّبة، يُضبط classNames مرة واحدة على الجذر ويُنقَل إلى الأجزاء عبر context.

مكوّنات الخادم

تأتي حزمة @zephora/react المنشورة بتوجيه "use client"، بحيث يمكنك استيراد المكوّنات مباشرة داخل أشجار React Server Component (موجّه تطبيقات Next.js) دون إضافة التوجيه بنفسك — كل مكوّن Zephora هو مكوّن عميل.