npm - @fakhrirafiki/theme-engine - Versions diffs - 0.2.5 → 0.4.0 - Mend

@fakhrirafiki/theme-engine 0.2.5 → 0.4.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/README.md +142 -482
package/dist/index.d.mts +57 -9
package/dist/index.d.ts +57 -9
package/dist/index.js +390 -262
package/dist/index.mjs +378 -252
package/dist/styles/animations.css +23 -1
package/dist/styles/components.css +12 -3
package/package.json +8 -5

package/README.md CHANGED Viewed

@@ -1,582 +1,242 @@
-# 🎨 Theme Engine
+# Theme Engine
-Elegant theming system with smooth transitions and custom color presets for modern React applications.
+Theme system for React: **mode** (`light | dark | system`) + **color presets** (CSS variables) with optional View Transition ripple.
-## ✨ Features
-- 🌓 **Unified Theming** - Seamlessly coordinate dark/light mode with custom color presets
-- 🎨 **Beautiful Presets** - 9 curated color themes with smooth animated selection
-- ✨ **Smooth Transitions** - Ripple effects using View Transition API
-- 💾 **Persistent** - localStorage integration with SSR-safe restoration
-- ♿ **Accessible** - Full ARIA support and reduced motion compatibility
-- 🚀 **Zero Config** - Works out of the box with sensible defaults
-- 📦 **Lightweight** - Optimized bundle size and direct source consumption
-## 🚀 Quick Start
+## Install
 ```bash
-# Install from npm
-npm install theme-engine
-# Or with yarn/pnpm
-yarn add theme-engine
-pnpm add theme-engine
-```
-```tsx
-import { ThemeProvider, ThemeScript, ThemeToggle } from 'theme-engine'
-import 'theme-engine/styles'
-function App() {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <ThemeScript
-          presetStorageKey="my-app-theme-preset"
-          defaultPreset="twitter"
-        />
-      </head>
-      <body>
-        <ThemeProvider
-          defaultMode="system"
-          defaultPreset="twitter"
-          modeStorageKey="my-app-mode"
-          presetStorageKey="my-app-theme-preset"
-          enablePresets={true}
-        >
-          <header>
-            <ThemeToggle />
-          </header>
-          <main>
-            Your app content
-          </main>
-        </ThemeProvider>
-      </body>
-    </html>
-  )
-}
+pnpm add @fakhrirafiki/theme-engine
 ```
-## 🎨 Theme Presets
+## Setup (Next.js App Router)
-Add beautiful color presets with smooth animations:
+### 1) Import CSS once
-```tsx
-import { ThemePresetButtons } from 'theme-engine'
+In `app/globals.css`:
-function ThemeSelector() {
-  return (
-    <ThemePresetButtons
-      animation={{
-        enabled: true,
-        duration: 4,
-        rowCount: 2,
-        scrollSpeed: 1,
-      }}
-      layout={{
-        buttonWidth: 140,
-        buttonGap: 12,
-        showColorBoxes: true,
-        colorBoxCount: 3,
-      }}
-    />
-  )
-}
+```css
+@import "@fakhrirafiki/theme-engine/styles";
 ```
-## 📦 Core Components
+Notes:
-### ThemeProvider
+- If you use Tailwind v4, you will typically also want:
-The heart of the theming system - coordinates dark/light mode with custom presets elegantly.
+```css
+@import "tailwindcss";
+@import "@fakhrirafiki/theme-engine/styles";
-```tsx
-<ThemeProvider
-  defaultMode="system"         // "light" | "dark" | "system"
-  defaultPreset="twitter"      // Default preset ID to apply
-  modeStorageKey="app-mode"    // localStorage key for theme mode
-  presetStorageKey="app-preset" // localStorage key for color preset
-  enablePresets={true}         // Enable preset functionality
->
-  {children}
-</ThemeProvider>
+@custom-variant dark (&:is(.dark *));
 ```
-### Custom Presets
-Add your own theme presets alongside the built-in TweakCN collection:
-```tsx
-import { ThemeProvider, type TweakCNThemePreset } from 'theme-engine'
-const customPresets: Record<string, TweakCNThemePreset> = {
-  "my-brand": {
-    label: "My Brand Theme",
-    styles: {
-      light: {
-        background: "#ffffff",
-        foreground: "#1a1a1a",
-        primary: "#0066cc",
-        "primary-foreground": "#ffffff",
-        secondary: "#f0f8ff",
-        "secondary-foreground": "#004499",
-        // ... all 36+ CSS properties
-        border: "#e2e8f0",
-        input: "#f1f5f9",
-        ring: "#0066cc",
-        radius: "0.5rem",
-      },
-      dark: {
-        background: "#0a0a0a",
-        foreground: "#fafafa",
-        primary: "#3399ff",
-        "primary-foreground": "#000000",
-        // ... all 36+ CSS properties
-      }
-    }
-  },
-  "retro-gaming": {
-    label: "Retro Gaming",
-    styles: {
-      light: {
-        background: "#f5f5dc",
-        foreground: "#2a1810",
-        primary: "#ff6b35",
-        "primary-foreground": "#ffffff",
-        accent: "#06ffa5",
-        "accent-foreground": "#2a1810",
-        // ... complete theme definition
-      },
-      dark: {
-        background: "#1a1a2e",
-        foreground: "#ffd23f",
-        primary: "#ff6b35",
-        "primary-foreground": "#000000",
-        // ... complete theme definition
-      }
-    }
-  }
-}
+- `@fakhrirafiki/theme-engine/styles` includes Tailwind v4 directives (`@theme inline`). If you are not using Tailwind v4, import only the non-tailwind CSS modules instead:
-function App() {
-  return (
-    <ThemeProvider
-      customPresets={customPresets}
-      defaultPreset="my-brand"
-    >
-      {/* Custom presets automatically appear in ThemePresetButtons */}
-      <ThemePresetButtons
-        showBuiltIn={true}
-        showCustom={true}
-        groupBy="provider"
-        labels={{
-          builtIn: "Built-in Themes",
-          custom: "🎨 Brand Themes"
-        }}
-      />
-    </ThemeProvider>
-  )
-}
+```css
+@import "@fakhrirafiki/theme-engine/styles/base.css";
+@import "@fakhrirafiki/theme-engine/styles/animations.css";
+@import "@fakhrirafiki/theme-engine/styles/components.css";
+@import "@fakhrirafiki/theme-engine/styles/utilities.css";
 ```
-### Preset Validation
+### 2) Wrap with `ThemeProvider`
-Validate your custom presets before using them to ensure they work correctly:
+In `app/layout.tsx`:
 ```tsx
-import { validateCustomPresets, logValidationResult } from 'theme-engine'
-const customPresets = {
-  "my-theme": {
-    label: "My Theme",
-    styles: {
-      light: { /* theme properties */ },
-      dark: { /* theme properties */ }
-    }
-  }
-}
+import { ThemeProvider } from "@fakhrirafiki/theme-engine";
+import "./globals.css";
-// Validate presets
-const validationResult = validateCustomPresets(customPresets);
-if (validationResult.isValid) {
-  console.log('✅ All presets are valid!');
-} else {
-  console.error('❌ Invalid presets:', validationResult.errors);
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeProvider defaultMode="system" defaultPreset="modern-minimal">
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  );
 }
-// Log detailed validation results
-logValidationResult(validationResult, 'My Custom Presets');
 ```
-**Required Properties** (minimum for a valid preset):
-- `background`, `foreground`
-- `primary`, `primary-foreground`
-- `secondary`, `secondary-foreground`
-- `card`, `card-foreground`
-**Recommended Properties** for complete themes:
-- `border`, `input`, `ring`
-- `muted`, `muted-foreground`
-- `accent`, `accent-foreground`
-- `destructive`, `destructive-foreground`
-- All 36+ CSS properties for full compatibility
+Notes:
-### ThemeScript
+- By default, `ThemeProvider` injects `ThemeScript` for preset restoration (to reduce flashes).
+- `ThemeScript` restores **preset colors** only (it does not set the `dark`/`light` class).
+- `defaultPreset="..."` pre-hydration only works for **built-in presets** (because `ThemeScript` uses `getPresetById()` internally). Custom `defaultPreset` still works after hydration.
-Pre-hydration script for seamless SSR theme restoration. Place in `<head>`:
-```tsx
-<ThemeScript
-  presetStorageKey="app-preset"
-  defaultPreset="twitter"  // Apply default preset if none stored
-/>
-```
+## Day-to-day usage
-### ThemeToggle
+### Toggle dark/light mode
-Beautiful dark/light mode toggle with ripple animation:
+Use the ready-made button:
 ```tsx
-<ThemeToggle
-  size="sm"           // "sm" | "md" | "lg"
-  variant="ghost"     // "default" | "outline" | "ghost"
-  className="custom-class"
-/>
-```
+"use client";
-### ThemePresetButtons
+import { ThemeToggle } from "@fakhrirafiki/theme-engine";
-Zero-config animated preset selector with beautiful color previews. State management is handled automatically via ThemeProvider context:
-```tsx
-{/* Basic usage - shows all presets */}
-<ThemePresetButtons />
-{/* Advanced usage with categorization */}
-<ThemePresetButtons
-  categories={["nature", "vibrant"]}  // Filter presets by category
-  maxPresets={20}     // Limit number of presets shown
-  showBuiltIn={true}  // Show built-in presets (default: true)
-  showCustom={true}   // Show custom presets (default: true)
-  groupBy="provider"  // Group by: 'none' | 'category' | 'provider'
-  labels={{
-    builtIn: "Built-in Themes",
-    custom: "🎨 Your Themes"
-  }}
-  showSectionHeaders={true}  // Show section headers when grouping
-  animation={{
-    enabled: true,
-    duration: 4,      // Animation duration in seconds
-    rowCount: 2,      // Number of animation rows
-    scrollSpeed: 1,   // Scroll speed multiplier
-  }}
-  layout={{
-    buttonWidth: 140,
-    buttonGap: 12,
-    rowGap: 12,
-    showColorBoxes: true,
-    colorBoxCount: 3,
-  }}
-/>
-```
-## 🎣 Hooks
-### useTheme
-Access both theme mode and preset state:
-```tsx
-function ThemeStatus() {
-  const {
-    mode,            // Current theme setting
-    setMode,         // Change theme mode
-    currentPreset,   // Current color preset
-    applyPreset,     // Apply new preset
-    clearPreset      // Clear current preset
-  } = useTheme()
-  return (
-    <div>
-      <p>Mode: {mode}</p>
-      <p>Preset: {currentPreset?.presetName || 'Default'}</p>
-    </div>
-  )
+export function HeaderThemeToggle() {
+  return <ThemeToggle size="md" variant="ghost" />;
 }
 ```
-## 🎨 TweakCN Preset Collection
-Theme Engine includes a complete collection of TweakCN-compatible presets with automatic built-in integration:
+Or control it yourself:
 ```tsx
-import { tweakcnPresets, getPresetById, getPresetIds } from 'theme-engine'
-// Get all preset IDs
-const allPresetIds = getPresetIds()
-// Get specific preset
-const twitterPreset = getPresetById('twitter')
-// Access raw TweakCN data
-const rawPresets = tweakcnPresets
-// Available presets: "twitter", "modern-minimal", "ocean-blue", etc.
-```
+"use client";
-## 🔧 Customization
+import { useTheme } from "@fakhrirafiki/theme-engine";
-### Zero-Config TweakCN Integration
-ThemePresetButtons automatically uses the built-in TweakCN preset collection - no configuration needed:
-```tsx
-import { ThemePresetButtons } from 'theme-engine'
-function App() {
+export function ModeButtons() {
+  const { mode, setMode, toggleMode } = useTheme();
   return (
     <div>
-      {/* Zero config - automatically uses TweakCN presets */}
-      <ThemePresetButtons />
-      {/* Filter specific presets if needed */}
-      <ThemePresetButtons
-        categories={["blue", "nature"]}
-        maxPresets={10}
-      />
+      <button onClick={() => setMode("system")}>System</button>
+      <button onClick={() => setMode("light")}>Light</button>
+      <button onClick={() => setMode("dark")}>Dark</button>
+      <button onClick={() => toggleMode()}>Toggle</button>
+      <div>Current: {mode}</div>
     </div>
-  )
+  );
 }
 ```
-### Custom Preset Integration
-Add your own presets to the TweakCN collection:
+### Pick a preset (by ID)
 ```tsx
-import { ThemePreset } from 'theme-engine'
-const myCustomPreset: ThemePreset = {
-  id: "my-brand",
-  name: "Brand Theme",
-  colors: {
-    light: {
-      primary: "#0066cc",
-      secondary: "#f0f0f0",
-      accent: "#ff6600",
-      background: "#ffffff",
-      foreground: "#1a1a1a",
-      // ... all 36+ CSS properties
-    },
-    dark: {
-      primary: "#3399ff",
-      secondary: "#2a2a2a",
-      accent: "#ff8833",
-      background: "#1a1a1a",
-      foreground: "#ffffff",
-      // ... all 36+ CSS properties
-    }
-  }
-}
+"use client";
-// Apply programmatically via useTheme hook
-function CustomControls() {
-  const { applyPreset } = useTheme()
-  return (
-    <button onClick={() => applyPreset(myCustomPreset)}>
-      Apply Brand Theme
-    </button>
-  )
-}
+import { useTypedTheme } from "@fakhrirafiki/theme-engine";
+import { customPresets } from "./custom-theme-presets";
-// Or apply a preset by ID (from built-in or custom presets)
-function QuickPresetSwitcher() {
-  const { setThemePresetById } = useTheme()
+export function PresetButtons() {
+  const { setThemePresetById, clearPreset, currentPreset } = useTypedTheme(customPresets);
   return (
     <div>
-      <button onClick={() => setThemePresetById('modern-minimal')}>
-        Modern Minimal
-      </button>
-      <button onClick={() => setThemePresetById('tiket-ngobrol')}>
-        Ngobrol Blue
-      </button>
+      <button onClick={() => setThemePresetById("my-brand")}>My Brand</button>
+      <button onClick={() => setThemePresetById("modern-minimal")}>Modern Minimal</button>
+      <button onClick={() => clearPreset()}>Reset</button>
+      <div>Active: {currentPreset?.presetName ?? "Default"}</div>
     </div>
-  )
+  );
 }
 ```
-## 🔄 Migration Guide
-### Current API Usage
+### Use the animated preset picker
-Use the clean theming system for all projects:
 ```tsx
-import { ThemeProvider, useTheme, ThemeScript } from 'theme-engine'
+"use client";
-function App() {
-  return (
-    <html>
-      <head>
-        <ThemeScript presetStorageKey="app-preset" />
-      </head>
-      <body>
-        <ThemeProvider
-          defaultMode="system"
-          defaultPreset="twitter"
-          enablePresets={true}
-        >
-          {children}
-        </ThemeProvider>
-      </body>
-    </html>
-  )
-}
+import { ThemePresetButtons } from "@fakhrirafiki/theme-engine";
-function MyComponent() {
-  const { applyPreset } = useTheme()
-  // Clean and simple!
+export function PresetPicker() {
+  return <ThemePresetButtons />;
 }
 ```
-### Benefits of Clean API
+## Presets
-- ✅ **Zero configuration** - Works out of the box with sensible defaults
-- ✅ **Perfect coordination** - Dark/light mode works seamlessly with presets
-- ✅ **Optimal performance** - Eliminates theme conflicts and infinite loops
-- ✅ **Reliable persistence** - Separate localStorage keys prevent conflicts
+### Built-in presets
-## 🎨 CSS Utilities & Modular Styles
+The package ships with a built-in preset collection:
-Theme engine provides modular CSS imports for advanced usage:
+```tsx
+import { getPresetIds, getPresetById } from "@fakhrirafiki/theme-engine";
-```css
-/* Complete theme system (recommended) */
-@import "theme-engine/styles";
-/* Or import specific modules */
-@import "theme-engine/styles/base.css";        /* CSS variables & defaults */
-@import "theme-engine/styles/animations.css";  /* View transition effects */
-@import "theme-engine/styles/components.css";  /* Component styles */
-@import "theme-engine/styles/utilities.css";   /* Dynamic utilities */
-@import "theme-engine/styles/tailwind.css";    /* Complete Tailwind integration */
+const ids = getPresetIds();
+const modernMinimal = getPresetById("modern-minimal");
 ```
-### Complete CSS Property System
-Theme engine manages 36+ CSS custom properties across categories:
-**🎨 Colors (28 properties)**
-- Base: `background`, `foreground`, `card`, `popover`
-- Brand: `primary`, `secondary`, `accent`, `muted`
-- System: `destructive`, `border`, `input`, `ring`
-- Charts: `chart-1` through `chart-5`
-- Sidebar: `sidebar`, `sidebar-primary`, `sidebar-accent`
-**✍️ Typography (3 properties)**
-- `font-sans`, `font-serif`, `font-mono`
-**📐 Layout (1 property)**
-- `radius` - Border radius system
-**🌑 Shadows (6 properties)**
-- `shadow-color`, `shadow-opacity`, `shadow-blur`
-- `shadow-spread`, `shadow-offset-x`, `shadow-offset-y`
+### Custom presets (recommended pattern)
-**📏 Spacing (2 properties)**
-- `letter-spacing`, `spacing`
+Create your presets in TweakCN-compatible format and pass them into `ThemeProvider`:
-### Dynamic Utilities
+```tsx
+import { ThemeProvider, type TweakCNThemePreset } from "@fakhrirafiki/theme-engine";
-CSS utilities that adapt to theme variables:
+// Tip: use `satisfies` (instead of `Record<string, ...>`) to keep literal keys for TS autocomplete
+const customPresets = {
+  "my-brand": {
+    label: "My Brand",
+    styles: {
+      light: {
+        background: "#ffffff",
+        foreground: "#111827",
+        card: "#ffffff",
+        "card-foreground": "#111827",
+        primary: "#2563eb",
+        "primary-foreground": "#ffffff",
+        secondary: "#e5e7eb",
+        "secondary-foreground": "#111827",
+      },
+      dark: {
+        background: "#0b1020",
+        foreground: "#f9fafb",
+        card: "#111827",
+        "card-foreground": "#f9fafb",
+        primary: "#60a5fa",
+        "primary-foreground": "#0b1020",
+        secondary: "#1f2937",
+        "secondary-foreground": "#f9fafb",
+      },
+    },
+  },
+} satisfies Record<string, TweakCNThemePreset>;
-```css
-/* Dynamic border radius */
-.rounded-theme { border-radius: var(--radius); }
-.rounded-theme-sm { border-radius: calc(var(--radius) * 0.5); }
-.rounded-theme-lg { border-radius: calc(var(--radius) * 2); }
-/* Dynamic shadows */
-.shadow-theme {
-  box-shadow: 0px var(--shadow-offset-y, 4px) var(--shadow-blur, 8px) 0px
-              rgba(0,0,0,var(--shadow-opacity, 0.1));
+export function AppRoot({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider customPresets={customPresets} defaultPreset="my-brand">
+      {children}
+    </ThemeProvider>
+  );
 }
-/* Dynamic spacing */
-.tracking-theme { letter-spacing: var(--letter-spacing); }
-.gap-theme { gap: var(--spacing, 0.25rem); }
 ```
-## 🤔 Troubleshooting
+Validation behavior:
-### Theme not persisting on refresh
+- Custom presets are validated in `ThemeProvider`.
+- Invalid custom presets are skipped; warnings are allowed.
+- You can validate manually via `validateCustomPresets()` / `logValidationResult()`.
-Make sure you're using `ThemeScript` in your `<head>`:
+## Persistence keys
-```tsx
-<head>
-  <ThemeScript presetStorageKey="your-key" />
-</head>
-```
+By default:
-### Preset colors not applying
+- Mode is stored in `localStorage['theme-engine-theme']`.
+- Preset is stored in `localStorage['theme-preset']`.
-Ensure you're using `ThemeProvider`:
+If you run multiple apps on the same domain, override the keys:
 ```tsx
-<ThemeProvider enablePresets={true}>
+<ThemeProvider modeStorageKey="my-app:mode" presetStorageKey="my-app:preset">
   {children}
 </ThemeProvider>
 ```
-### SSR hydration mismatch
+## Tailwind tokens you get
-Add `suppressHydrationWarning` to your `<html>` tag:
+After importing `@fakhrirafiki/theme-engine/styles`, you can use semantic tokens like:
-```tsx
-<html lang="en" suppressHydrationWarning>
-```
+- `bg-background`, `text-foreground`, `border-border`
+- `bg-primary`, `text-primary-foreground`
+- `bg-accent-success`, `text-accent-danger`, etc (if your presets include the `accent-*` variables)
-## 📦 Package Contents
+## Troubleshooting
-The npm package includes:
+### `useTheme must be used within a ThemeProvider`
-- **ESM and CommonJS builds** - Universal compatibility
-- **TypeScript declarations** - Full type safety
-- **Complete CSS system** - All styles included
-- **Source maps** - Enhanced debugging
-- **Tree-shaking support** - Optimal bundle size
-```
-theme-engine/
-├── dist/
-│   ├── index.js         # CommonJS build
-│   ├── index.mjs        # ESM build
-│   ├── index.d.ts       # TypeScript declarations
-│   └── styles/          # CSS files
-│       ├── index.css    # Complete system
-│       ├── base.css     # CSS variables
-│       ├── animations.css
-│       ├── components.css
-│       ├── utilities.css
-│       └── tailwind.css
-└── README.md
-```
+Wrap your component tree with `ThemeProvider` (and ensure the component is a client component).
-## 🏗️ Architecture
+### Preset doesn’t apply on refresh
-The theme engine elegantly coordinates two theming concerns:
+If you render `ThemeScript` manually (using `disableScript`), make sure both use the same `presetStorageKey`.
-- **Theme Mode** (light/dark/system) - Controlled by `ThemeProvider`
-- **Color Presets** - Managed by `ThemeProvider` using CSS variables with `!important`
-- **Coordination** - MutationObserver detects mode changes and reapplies presets
-- **Persistence** - Separate localStorage keys prevent conflicts
-- **Zero-Config** - Built-in TweakCN presets work automatically
+### `ThemePresetButtons` breaks
-This architecture ensures seamless coordination between appearance modes and color presets without conflicts.
+Ensure you imported `@fakhrirafiki/theme-engine/styles` (or at least `animations.css` + `components.css`).
-## 📄 License
+## License
-MIT License - see the monorepo root for details.
+MIT