پیکربندی

تنظیمات سراسری برای هر کامپوننت Zephora — اپلیکیشن خود را یک بار با ZephoraConfigProvider بپیچید و locale، لایه‌های 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 variableهایی با fallback‌های داخلی می‌گیرند، بنابراین هم 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 با کمک‌کننده‌های خودکار حالت تیره عرضه می‌شود. هوک useColorScheme یک scheme را resolve می‌کند (با mode: "system" ترجیح سیستم‌عامل را به‌صورت زنده دنبال می‌کند) و به‌طور پیش‌فرض تم resolve‌شده را به‌صورت سراسری اعمال می‌کند:

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.

primitive‌های سطح پایین‌تر نیز export می‌شوند:

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

برای رندر سمت سرور، colorSchemeCss(light?, dark?) یک شیت استایل استاتیک می‌سازد که تم‌ها را با ترجیح سیستم‌عامل تعویض می‌کند — بدون فلش تم اشتباه، بدون نیاز به JavaScript پیش از paint. تنظیم 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

کامپوننت‌های چند-slot (Dialog، Sheet، Tabs، Card، Popover، Tooltip…) یک قرارداد کلاس به‌ازای هر slot ارائه می‌دهند: root یک classNames با نوع Partial<Record<<Name>Slot, string>> می‌پذیرد (union‌های نام-slot مانند DialogSlot export می‌شوند). کلاس‌های slot پس از کلاس‌های ماژول افزوده می‌شوند و به unstyled مشروط نیستند — هم در حالت استایل‌دار و هم بدون استایل کار می‌کنند؛ در حالت بدون استایل تنها کلاس‌ها همان‌ها هستند. classNames.root در کنار prop موجود className ادغام می‌شود که همچنان root را هدف می‌گیرد و آخر از همه اعمال می‌شود. برای کامپوننت‌های مرکب، classNames یک بار روی root تنظیم می‌شود و از طریق context به بخش‌ها منتقل می‌شود.

کامپوننت‌های سرور

باندل منتشرشده @zephora/react با دستور "use client" عرضه می‌شود، بنابراین می‌توانید کامپوننت‌ها را مستقیماً درون درخت‌های React Server Component (app router در Next.js) بدون افزودن خودِ دستور import کنید — هر کامپوننت Zephora یک client component است.