npm - @arqel-dev/theme - Versions diffs - 0.8.0 - Mend

@arqel-dev/theme 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Arqel Contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,27 @@
+# @arqel-dev/theme
+> Tokens semânticos + dark-mode + ThemeProvider/ThemeToggle para painéis Arqel.
+## Instalação
+```bash
+pnpm add @arqel-dev/theme
+```
+## Uso rápido
+```tsx
+import { ThemeProvider, ThemeToggle } from '@arqel-dev/theme';
+import '@arqel-dev/theme/tokens.css';
+<ThemeProvider>
+  <App />
+  <ThemeToggle />
+</ThemeProvider>
+```
+Ver `SKILL.md` para documentação completa e `apps/docs/guide/theming.md` para o guia.
+## Licença
+MIT.

package/SKILL.md ADDED Viewed

@@ -0,0 +1,133 @@
+# SKILL.md — arqel-dev/theme
+## Purpose
+Pacote responsável por **dark-mode**, **tokens de design semânticos** e **theming runtime** para painéis Arqel.
+Fornece:
+- `tokens.css` — variáveis CSS canônicas (`--arqel-color-bg`, `--arqel-color-fg`, `--arqel-color-primary`, etc.) em `:root` (light) e `.dark` (dark).
+- `<ThemeProvider>` — Context React que aplica/remove a classe `dark` no `<html>` baseado em preferência do utilizador + `prefers-color-scheme`.
+- `<ThemeToggle>` — botão acessível que cicla `system → light → dark`.
+- `useTheme()` — hook para ler/atualizar tema em qualquer componente.
+- `preventFlashScript()` — snippet inline para evitar FOUC (flash branco antes do React montar).
+## Key Contracts
+### `Theme` (type)
+```ts
+type Theme = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
+```
+`system` segue `prefers-color-scheme` do SO. `resolvedTheme` é sempre concreto.
+### `<ThemeProvider>`
+```tsx
+<ThemeProvider defaultTheme="system" storageKey="arqel-theme" darkClass="dark">
+  {children}
+</ThemeProvider>
+```
+Props:
+| Prop | Default | Descrição |
+| --- | --- | --- |
+| `defaultTheme` | `'system'` | Tema usado quando nada está em localStorage |
+| `storageKey` | `'arqel-theme'` | Chave em localStorage |
+| `darkClass` | `'dark'` | Classe aplicada em `<html>` quando dark |
+| `attribute` | `'class'` | `'class'` ou `'data-theme'` |
+### `useTheme()`
+```ts
+const { theme, resolvedTheme, setTheme } = useTheme();
+```
+Lança erro se chamado fora de `<ThemeProvider>` (fail-fast).
+### `preventFlashScript(options?)`
+Retorna string IIFE para inserir antes dos bundles React:
+```blade
+<script>{!! \Arqel\Theme\preventFlashScript() !!}</script>
+```
+## Conventions
+1. **Tokens semânticos, nunca cores cruas** — componentes Arqel usam `var(--arqel-color-bg)`, nunca `#ffffff`.
+2. **localStorage opt-out** — falhas de `localStorage.setItem/getItem` são silenciadas (Safari private mode, iframes).
+3. **SSR-safe** — todas funções verificam `typeof window === 'undefined'`.
+4. **Sem dependências runtime extras** — apenas `react` (peer).
+5. **Class-based dark mode** (Tailwind v4 syntax: `@variant dark (&:where(.dark, .dark *))`).
+## Examples
+### Setup mínimo num app Inertia
+```tsx
+// resources/js/app.tsx
+import { ThemeProvider } from '@arqel-dev/theme';
+import '@arqel-dev/theme/tokens.css';
+createInertiaApp({
+  setup({ el, App, props }) {
+    createRoot(el).render(
+      <ThemeProvider>
+        <App {...props} />
+      </ThemeProvider>,
+    );
+  },
+});
+```
+### Toggle no header
+```tsx
+import { ThemeToggle } from '@arqel-dev/theme';
+<header className="flex items-center justify-between">
+  <h1>Dashboard</h1>
+  <ThemeToggle className="rounded-md p-2 hover:bg-muted" />
+</header>
+```
+### FOUC prevention (Blade)
+```blade
+<head>
+  {{-- ... --}}
+  <script>(function(){try{var k="arqel-theme",t=null;try{t=localStorage.getItem(k)}catch(e){}if(t!=="light"&&t!=="dark"&&t!=="system")t="system";var r=t==="system"?(window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"):t;if(r==="dark")document.documentElement.classList.add("dark");document.documentElement.style.colorScheme=r;}catch(e){}})();</script>
+  @vite([...])
+</head>
+```
+### Override de tema (custom branding)
+```css
+:root {
+  --arqel-color-primary: #ff6b35;
+  --arqel-color-primary-fg: #ffffff;
+}
+.dark {
+  --arqel-color-primary: #ffa07a;
+}
+```
+## Anti-patterns
+- ❌ Usar `<ThemeToggle>` fora de `<ThemeProvider>` — lança erro em runtime.
+- ❌ Hard-coding `bg-white dark:bg-neutral-900` em components quando há token semântico equivalente. Prefira `bg-[var(--arqel-color-bg)]`.
+- ❌ Múltiplos `<ThemeProvider>` aninhados — o mais interno vence, mas confunde devtools.
+- ❌ Esquecer o snippet `preventFlashScript` no Blade — usuários verão flash branco em dark mode.
+- ❌ Usar `window` ou `document` no top-level de componentes — quebra SSR.
+## Related
+- ADR-001 — Inertia-only (theme não usa fetch)
+- ADR-016 — Sem libs de fetch para CRUD
+- `@arqel-dev/ui` — consome tokens via Tailwind v4 `@theme`
+- `apps/docs/guide/theming.md` — guia completo de theming

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,94 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+interface PreventFlashOptions {
+    storageKey?: string;
+    darkClass?: string;
+    attribute?: 'class' | 'data-theme';
+}
+/**
+ * Retorna um snippet JS (string) para inserir inline no `<head>` do HTML
+ * **antes** dos bundles React. Lê localStorage + system pref e aplica
+ * imediatamente a classe `dark` em `<html>`, evitando flash branco no
+ * carregamento (FOUC).
+ *
+ * Uso (Blade):
+ *   <script>{!! \Arqel\Theme\preventFlashScript() !!}</script>
+ *
+ * Uso direto:
+ *   <script dangerouslySetInnerHTML={{ __html: preventFlashScript() }} />
+ *
+ * O snippet é IIFE que falha silenciosamente — nenhuma corrupção de página
+ * mesmo se localStorage estiver bloqueado.
+ */
+declare function preventFlashScript(options?: PreventFlashOptions): string;
+/**
+ * Theme preference armazenada em localStorage / Context.
+ *
+ * - `light` — força modo claro
+ * - `dark` — força modo escuro
+ * - `system` — segue `prefers-color-scheme` do SO
+ */
+type Theme = 'light' | 'dark' | 'system';
+/**
+ * Tema efetivamente aplicado ao DOM (já resolvido a partir de `Theme`).
+ */
+type ResolvedTheme = 'light' | 'dark';
+interface ThemeContextValue {
+    /** Preferência do utilizador (incluindo `system`). */
+    theme: Theme;
+    /** Tema concreto aplicado no `<html>` (sempre `light` ou `dark`). */
+    resolvedTheme: ResolvedTheme;
+    /** Atualiza preferência (persiste em localStorage). */
+    setTheme: (theme: Theme) => void;
+}
+declare const DEFAULT_STORAGE_KEY = "arqel-theme";
+declare function isTheme(value: unknown): value is Theme;
+/**
+ * Lê preferência do localStorage. SSR-safe: retorna `null` no servidor.
+ */
+declare function readStoredTheme(key?: string): Theme | null;
+/**
+ * Persiste preferência em localStorage. Silencioso em erro.
+ */
+declare function writeStoredTheme(theme: Theme, key?: string): void;
+/**
+ * Detecta system preference. SSR-safe: retorna `light` no servidor.
+ */
+declare function getSystemTheme(): 'light' | 'dark';
+declare const ThemeContext: react.Context<ThemeContextValue | null>;
+interface ThemeProviderProps {
+    children: ReactNode;
+    /** Tema padrão quando nada está armazenado. Default: `system`. */
+    defaultTheme?: Theme;
+    /** Chave usada em localStorage. Default: `arqel-theme`. */
+    storageKey?: string;
+    /** Classe aplicada no `<html>` quando dark. Default: `dark`. */
+    darkClass?: string;
+    /** Atributo opcional usado em vez de classe (`data-theme`). Útil para integrações. */
+    attribute?: 'class' | 'data-theme';
+}
+declare function ThemeProvider({ children, defaultTheme, storageKey, darkClass, attribute, }: ThemeProviderProps): ReactNode;
+interface ThemeToggleProps {
+    className?: string;
+}
+/**
+ * Botão que cicla entre `system → light → dark → system`.
+ * Mostra ícone correspondente ao **tema atualmente selecionado**
+ * (não ao próximo) e usa `aria-label` descritivo para acessibilidade.
+ */
+declare function ThemeToggle({ className }?: ThemeToggleProps): ReactNode;
+/**
+ * Hook para acessar o tema atual e atualizá-lo.
+ *
+ * Lança erro se chamado fora de `<ThemeProvider>` (fail-fast — evita
+ * componentes silenciosamente mostrando defaults errados).
+ */
+declare function useTheme(): ThemeContextValue;
+export { DEFAULT_STORAGE_KEY, type PreventFlashOptions, type ResolvedTheme, type Theme, ThemeContext, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, ThemeToggle, type ThemeToggleProps, getSystemTheme, isTheme, preventFlashScript, readStoredTheme, useTheme, writeStoredTheme };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,209 @@
+import { createContext, useState, useEffect, useCallback, useMemo, useContext } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+// src/storage.ts
+var DEFAULT_STORAGE_KEY = "arqel-theme";
+var VALID_THEMES = ["light", "dark", "system"];
+function isTheme(value) {
+  return typeof value === "string" && VALID_THEMES.includes(value);
+}
+function readStoredTheme(key = DEFAULT_STORAGE_KEY) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return isTheme(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function writeStoredTheme(theme, key = DEFAULT_STORAGE_KEY) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, theme);
+  } catch {
+  }
+}
+function getSystemTheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+// src/preventFlash.ts
+function preventFlashScript(options = {}) {
+  const { storageKey = DEFAULT_STORAGE_KEY, darkClass = "dark", attribute = "class" } = options;
+  const k = JSON.stringify(storageKey);
+  const c = JSON.stringify(darkClass);
+  const a = JSON.stringify(attribute);
+  return [
+    "(function(){try{",
+    "var k=",
+    k,
+    ",c=",
+    c,
+    ",a=",
+    a,
+    ";",
+    "var t=null;try{t=localStorage.getItem(k);}catch(e){}",
+    'if(t!=="light"&&t!=="dark"&&t!=="system")t="system";',
+    "var r=t;",
+    'if(t==="system"){',
+    'r=(window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches)?"dark":"light";',
+    "}",
+    "var el=document.documentElement;",
+    'if(a==="class"){if(r==="dark")el.classList.add(c);else el.classList.remove(c);}',
+    'else{el.setAttribute("data-theme",r);}',
+    "el.style.colorScheme=r;",
+    "}catch(e){}})();"
+  ].join("");
+}
+var ThemeContext = createContext(null);
+function resolve(theme) {
+  return theme === "system" ? getSystemTheme() : theme;
+}
+function applyToDom(resolved, darkClass, attribute) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (attribute === "class") {
+    if (resolved === "dark") root.classList.add(darkClass);
+    else root.classList.remove(darkClass);
+  } else {
+    root.setAttribute("data-theme", resolved);
+  }
+  root.style.colorScheme = resolved;
+}
+function ThemeProvider({
+  children,
+  defaultTheme = "system",
+  storageKey = DEFAULT_STORAGE_KEY,
+  darkClass = "dark",
+  attribute = "class"
+}) {
+  const [theme, setThemeState] = useState(() => readStoredTheme(storageKey) ?? defaultTheme);
+  const [resolvedTheme, setResolvedTheme] = useState(() => resolve(theme));
+  useEffect(() => {
+    const next = resolve(theme);
+    setResolvedTheme(next);
+    applyToDom(next, darkClass, attribute);
+    if (theme !== "system" || typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => {
+      const r = media.matches ? "dark" : "light";
+      setResolvedTheme(r);
+      applyToDom(r, darkClass, attribute);
+    };
+    media.addEventListener("change", onChange);
+    return () => {
+      media.removeEventListener("change", onChange);
+    };
+  }, [theme, darkClass, attribute]);
+  const setTheme = useCallback(
+    (t) => {
+      setThemeState(t);
+      writeStoredTheme(t, storageKey);
+    },
+    [storageKey]
+  );
+  const value = useMemo(
+    () => ({ theme, resolvedTheme, setTheme }),
+    [theme, resolvedTheme, setTheme]
+  );
+  return /* @__PURE__ */ jsx(ThemeContext.Provider, { value, children });
+}
+function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("[arqel-dev/theme] useTheme() deve ser usado dentro de <ThemeProvider>.");
+  }
+  return ctx;
+}
+var CYCLE = ["system", "light", "dark"];
+var LABELS = {
+  system: "Tema: sistema (clique para claro)",
+  light: "Tema: claro (clique para escuro)",
+  dark: "Tema: escuro (clique para sistema)"
+};
+function nextTheme(current) {
+  const idx = CYCLE.indexOf(current);
+  return CYCLE[(idx + 1) % CYCLE.length] ?? "system";
+}
+function SunIcon() {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      "aria-hidden": "true",
+      width: "16",
+      height: "16",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      children: [
+        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "4" }),
+        /* @__PURE__ */ jsx("path", { d: "M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" })
+      ]
+    }
+  );
+}
+function MoonIcon() {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      "aria-hidden": "true",
+      width: "16",
+      height: "16",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      children: /* @__PURE__ */ jsx("path", { d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" })
+    }
+  );
+}
+function MonitorIcon() {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      "aria-hidden": "true",
+      width: "16",
+      height: "16",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      children: [
+        /* @__PURE__ */ jsx("rect", { x: "2", y: "3", width: "20", height: "14", rx: "2" }),
+        /* @__PURE__ */ jsx("path", { d: "M8 21h8M12 17v4" })
+      ]
+    }
+  );
+}
+function ThemeToggle({ className } = {}) {
+  const { theme, setTheme } = useTheme();
+  const icon = theme === "light" ? /* @__PURE__ */ jsx(SunIcon, {}) : theme === "dark" ? /* @__PURE__ */ jsx(MoonIcon, {}) : /* @__PURE__ */ jsx(MonitorIcon, {});
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      onClick: () => setTheme(nextTheme(theme)),
+      "aria-label": LABELS[theme],
+      title: LABELS[theme],
+      "data-theme-current": theme,
+      className,
+      children: icon
+    }
+  );
+}
+export { DEFAULT_STORAGE_KEY, ThemeContext, ThemeProvider, ThemeToggle, getSystemTheme, isTheme, preventFlashScript, readStoredTheme, useTheme, writeStoredTheme };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/storage.ts","../src/preventFlash.ts","../src/ThemeProvider.tsx","../src/useTheme.ts","../src/ThemeToggle.tsx"],"names":["jsx"],"mappings":"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","file":"index.js","sourcesContent":["import type { Theme } from './types';\n\nexport const DEFAULT_STORAGE_KEY = 'arqel-theme';\n\nconst VALID_THEMES: readonly Theme[] = ['light', 'dark', 'system'];\n\nexport function isTheme(value: unknown): value is Theme {\n return typeof value === 'string' && (VALID_THEMES as readonly string[]).includes(value);\n}\n\n/**\n * Lê preferência do localStorage. SSR-safe: retorna `null` no servidor.\n */\nexport function readStoredTheme(key: string = DEFAULT_STORAGE_KEY): Theme | null {\n if (typeof window === 'undefined') return null;\n try {\n const raw = window.localStorage.getItem(key);\n return isTheme(raw) ? raw : null;\n } catch {\n // localStorage pode estar bloqueado (Safari private, iframes, etc).\n return null;\n }\n}\n\n/**\n * Persiste preferência em localStorage. Silencioso em erro.\n */\nexport function writeStoredTheme(theme: Theme, key: string = DEFAULT_STORAGE_KEY): void {\n if (typeof window === 'undefined') return;\n try {\n window.localStorage.setItem(key, theme);\n } catch {\n // ignore\n }\n}\n\n/**\n * Detecta system preference. SSR-safe: retorna `light` no servidor.\n */\nexport function getSystemTheme(): 'light' | 'dark' {\n if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {\n return 'light';\n }\n return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';\n}\n","import { DEFAULT_STORAGE_KEY } from './storage';\n\nexport interface PreventFlashOptions {\n storageKey?: string;\n darkClass?: string;\n attribute?: 'class' | 'data-theme';\n}\n\n/**\n * Retorna um snippet JS (string) para inserir inline no `<head>` do HTML\n * **antes** dos bundles React. Lê localStorage + system pref e aplica\n * imediatamente a classe `dark` em `<html>`, evitando flash branco no\n * carregamento (FOUC).\n *\n * Uso (Blade):\n * <script>{!! \\Arqel\\Theme\\preventFlashScript() !!}</script>\n *\n * Uso direto:\n * <script dangerouslySetInnerHTML={{ __html: preventFlashScript() }} />\n *\n * O snippet é IIFE que falha silenciosamente — nenhuma corrupção de página\n * mesmo se localStorage estiver bloqueado.\n */\nexport function preventFlashScript(options: PreventFlashOptions = {}): string {\n const { storageKey = DEFAULT_STORAGE_KEY, darkClass = 'dark', attribute = 'class' } = options;\n\n // JSON.stringify garante escape correto de aspas e quebras.\n const k = JSON.stringify(storageKey);\n const c = JSON.stringify(darkClass);\n const a = JSON.stringify(attribute);\n\n return [\n '(function(){try{',\n 'var k=',\n k,\n ',c=',\n c,\n ',a=',\n a,\n ';',\n 'var t=null;try{t=localStorage.getItem(k);}catch(e){}',\n 'if(t!==\"light\"&&t!==\"dark\"&&t!==\"system\")t=\"system\";',\n 'var r=t;',\n 'if(t===\"system\"){',\n 'r=(window.matchMedia&&window.matchMedia(\"(prefers-color-scheme: dark)\").matches)?\"dark\":\"light\";',\n '}',\n 'var el=document.documentElement;',\n 'if(a===\"class\"){if(r===\"dark\")el.classList.add(c);else el.classList.remove(c);}',\n 'else{el.setAttribute(\"data-theme\",r);}',\n 'el.style.colorScheme=r;',\n '}catch(e){}})();',\n ].join('');\n}\n","import { createContext, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';\n\nimport { DEFAULT_STORAGE_KEY, getSystemTheme, readStoredTheme, writeStoredTheme } from './storage';\nimport type { ResolvedTheme, Theme, ThemeContextValue } from './types';\n\nexport const ThemeContext = createContext<ThemeContextValue | null>(null);\n\nexport interface ThemeProviderProps {\n children: ReactNode;\n /** Tema padrão quando nada está armazenado. Default: `system`. */\n defaultTheme?: Theme;\n /** Chave usada em localStorage. Default: `arqel-theme`. */\n storageKey?: string;\n /** Classe aplicada no `<html>` quando dark. Default: `dark`. */\n darkClass?: string;\n /** Atributo opcional usado em vez de classe (`data-theme`). Útil para integrações. */\n attribute?: 'class' | 'data-theme';\n}\n\nfunction resolve(theme: Theme): ResolvedTheme {\n return theme === 'system' ? getSystemTheme() : theme;\n}\n\nfunction applyToDom(\n resolved: ResolvedTheme,\n darkClass: string,\n attribute: 'class' | 'data-theme',\n): void {\n if (typeof document === 'undefined') return;\n const root = document.documentElement;\n if (attribute === 'class') {\n if (resolved === 'dark') root.classList.add(darkClass);\n else root.classList.remove(darkClass);\n } else {\n root.setAttribute('data-theme', resolved);\n }\n // colorScheme ajuda nativos (scrollbars, form controls)\n root.style.colorScheme = resolved;\n}\n\nexport function ThemeProvider({\n children,\n defaultTheme = 'system',\n storageKey = DEFAULT_STORAGE_KEY,\n darkClass = 'dark',\n attribute = 'class',\n}: ThemeProviderProps): ReactNode {\n // Inicialização lazy — lê localStorage 1x.\n const [theme, setThemeState] = useState<Theme>(() => readStoredTheme(storageKey) ?? defaultTheme);\n const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() => resolve(theme));\n\n // Aplica no DOM e mantém em sync com matchMedia se theme === 'system'.\n useEffect(() => {\n const next = resolve(theme);\n setResolvedTheme(next);\n applyToDom(next, darkClass, attribute);\n\n if (\n theme !== 'system' ||\n typeof window === 'undefined' ||\n typeof window.matchMedia !== 'function'\n ) {\n return;\n }\n\n const media = window.matchMedia('(prefers-color-scheme: dark)');\n const onChange = (): void => {\n const r: ResolvedTheme = media.matches ? 'dark' : 'light';\n setResolvedTheme(r);\n applyToDom(r, darkClass, attribute);\n };\n media.addEventListener('change', onChange);\n return () => {\n media.removeEventListener('change', onChange);\n };\n }, [theme, darkClass, attribute]);\n\n const setTheme = useCallback(\n (t: Theme) => {\n setThemeState(t);\n writeStoredTheme(t, storageKey);\n },\n [storageKey],\n );\n\n const value = useMemo<ThemeContextValue>(\n () => ({ theme, resolvedTheme, setTheme }),\n [theme, resolvedTheme, setTheme],\n );\n\n return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n","import { useContext } from 'react';\n\nimport { ThemeContext } from './ThemeProvider';\nimport type { ThemeContextValue } from './types';\n\n/**\n * Hook para acessar o tema atual e atualizá-lo.\n *\n * Lança erro se chamado fora de `<ThemeProvider>` (fail-fast — evita\n * componentes silenciosamente mostrando defaults errados).\n */\nexport function useTheme(): ThemeContextValue {\n const ctx = useContext(ThemeContext);\n if (!ctx) {\n throw new Error('[arqel-dev/theme] useTheme() deve ser usado dentro de <ThemeProvider>.');\n }\n return ctx;\n}\n","import type { ReactNode } from 'react';\nimport type { Theme } from './types';\nimport { useTheme } from './useTheme';\n\nconst CYCLE: readonly Theme[] = ['system', 'light', 'dark'];\n\nconst LABELS: Record<Theme, string> = {\n system: 'Tema: sistema (clique para claro)',\n light: 'Tema: claro (clique para escuro)',\n dark: 'Tema: escuro (clique para sistema)',\n};\n\nfunction nextTheme(current: Theme): Theme {\n const idx = CYCLE.indexOf(current);\n return CYCLE[(idx + 1) % CYCLE.length] ?? 'system';\n}\n\nfunction SunIcon(): ReactNode {\n return (\n <svg\n aria-hidden=\"true\"\n width=\"16\"\n height=\"16\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n strokeWidth=\"2\"\n strokeLinecap=\"round\"\n strokeLinejoin=\"round\"\n >\n <circle cx=\"12\" cy=\"12\" r=\"4\" />\n <path d=\"M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41\" />\n </svg>\n );\n}\n\nfunction MoonIcon(): ReactNode {\n return (\n <svg\n aria-hidden=\"true\"\n width=\"16\"\n height=\"16\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n strokeWidth=\"2\"\n strokeLinecap=\"round\"\n strokeLinejoin=\"round\"\n >\n <path d=\"M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z\" />\n </svg>\n );\n}\n\nfunction MonitorIcon(): ReactNode {\n return (\n <svg\n aria-hidden=\"true\"\n width=\"16\"\n height=\"16\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n strokeWidth=\"2\"\n strokeLinecap=\"round\"\n strokeLinejoin=\"round\"\n >\n <rect x=\"2\" y=\"3\" width=\"20\" height=\"14\" rx=\"2\" />\n <path d=\"M8 21h8M12 17v4\" />\n </svg>\n );\n}\n\nexport interface ThemeToggleProps {\n className?: string;\n}\n\n/**\n * Botão que cicla entre `system → light → dark → system`.\n * Mostra ícone correspondente ao **tema atualmente selecionado**\n * (não ao próximo) e usa `aria-label` descritivo para acessibilidade.\n */\nexport function ThemeToggle({ className }: ThemeToggleProps = {}): ReactNode {\n const { theme, setTheme } = useTheme();\n\n const icon = theme === 'light' ? <SunIcon /> : theme === 'dark' ? <MoonIcon /> : <MonitorIcon />;\n\n return (\n <button\n type=\"button\"\n onClick={() => setTheme(nextTheme(theme))}\n aria-label={LABELS[theme]}\n title={LABELS[theme]}\n data-theme-current={theme}\n className={className}\n >\n {icon}\n </button>\n );\n}\n"]}

package/package.json ADDED Viewed

@@ -0,0 +1,64 @@
+{
+  "name": "@arqel-dev/theme",
+  "version": "0.8.0",
+  "description": "Tokens semânticos + dark-mode + ThemeProvider/ThemeToggle para painéis Arqel.",
+  "license": "MIT",
+  "homepage": "https://arqel.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arqel-dev/arqel.git",
+    "directory": "packages-js/theme"
+  },
+  "keywords": [
+    "arqel",
+    "theme",
+    "dark-mode",
+    "tailwind",
+    "tokens",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tokens.css": "./src/tokens.css"
+  },
+  "files": [
+    "dist",
+    "src/tokens.css",
+    "README.md",
+    "SKILL.md"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/tokens.css ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * @arqel/theme — semantic design tokens
+ *
+ * Estes tokens são as variáveis canônicas usadas pelos componentes Arqel.
+ * Eles são "semânticos" (descrevem intenção: bg, fg, primary) e não cores
+ * concretas — o que permite trocar paleta inteira sem refatorar componentes.
+ *
+ * Override:
+ *   :root { --arqel-color-primary: #ff0080; }
+ *
+ * Tailwind v4 usage (via @theme):
+ *   @import 'tailwindcss';
+ *   @import '@arqel/theme/tokens.css';
+ *   @theme {
+ *     --color-primary: var(--arqel-color-primary);
+ *   }
+ */
+:root {
+  /* Surface */
+  --arqel-color-bg: #ffffff;
+  --arqel-color-bg-muted: #f5f5f5;
+  --arqel-color-bg-subtle: #fafafa;
+  /* Foreground */
+  --arqel-color-fg: #0a0a0a;
+  --arqel-color-fg-muted: #525252;
+  --arqel-color-fg-subtle: #737373;
+  /* Borders */
+  --arqel-color-border: #e5e5e5;
+  --arqel-color-border-strong: #d4d4d4;
+  /* Brand / accent */
+  --arqel-color-primary: #6366f1;
+  --arqel-color-primary-fg: #ffffff;
+  --arqel-color-primary-hover: #4f46e5;
+  /* Semantic */
+  --arqel-color-success: #10b981;
+  --arqel-color-success-fg: #ffffff;
+  --arqel-color-warning: #f59e0b;
+  --arqel-color-warning-fg: #0a0a0a;
+  --arqel-color-danger: #ef4444;
+  --arqel-color-danger-fg: #ffffff;
+  --arqel-color-info: #0ea5e9;
+  --arqel-color-info-fg: #ffffff;
+  /* Focus ring */
+  --arqel-color-ring: #6366f1;
+  /* Radii */
+  --arqel-radius-sm: 0.25rem;
+  --arqel-radius-md: 0.375rem;
+  --arqel-radius-lg: 0.5rem;
+}
+.dark {
+  /* Surface */
+  --arqel-color-bg: #0a0a0a;
+  --arqel-color-bg-muted: #171717;
+  --arqel-color-bg-subtle: #1f1f1f;
+  /* Foreground */
+  --arqel-color-fg: #fafafa;
+  --arqel-color-fg-muted: #a3a3a3;
+  --arqel-color-fg-subtle: #737373;
+  /* Borders */
+  --arqel-color-border: #262626;
+  --arqel-color-border-strong: #404040;
+  /* Brand / accent */
+  --arqel-color-primary: #818cf8;
+  --arqel-color-primary-fg: #0a0a0a;
+  --arqel-color-primary-hover: #6366f1;
+  /* Semantic */
+  --arqel-color-success: #34d399;
+  --arqel-color-success-fg: #022c22;
+  --arqel-color-warning: #fbbf24;
+  --arqel-color-warning-fg: #1c1917;
+  --arqel-color-danger: #f87171;
+  --arqel-color-danger-fg: #1f1f1f;
+  --arqel-color-info: #38bdf8;
+  --arqel-color-info-fg: #0c1f2c;
+  /* Focus ring */
+  --arqel-color-ring: #818cf8;
+}