@fakhrirafiki/theme-engine 0.4.8 → 0.4.9

package/README.md

@@ -25,6 +25,7 @@ Theme system for **Next.js (App Router)**: mode (`light | dark | system`) + them
 - [Built-in presets](#-built-in-presets)
 - [Tailwind tokens](#-tailwind-tokens-you-get)
 - [Components](#-components)
+- [Recipe: ThemePresetSelect](#-recipe-themepresetselect-simple-list)
 - [API reference](#-api-reference)
 - [Troubleshooting](#-troubleshooting)
 
@@ -166,8 +167,8 @@ export function TypedPresetButtons() {
 
 ### SSR & flashes
 
-- `ThemeProvider` injects `ThemeScript` to restore **preset colors** before hydration (reduces flashes).
-- `ThemeScript` restores **preset colors only** (it does not set the `.dark` / `.light` class).
+- `ThemeProvider` injects a small pre-hydration script to restore **preset colors** before hydration (reduces flashes).
+- The pre-hydration script restores **preset colors only** (it does not set the `.dark` / `.light` class).
 - `defaultPreset="..."` pre-hydration only works for **built-in presets**. Custom `defaultPreset` still works after hydration.
 
 ### Persistence
@@ -325,6 +326,101 @@ export function PresetPicker() {
 }
 ```
 
+### 🧾 Recipe: `ThemePresetSelect` (simple list)
+
+Want a simple, scrollable preset list (e.g. for a settings modal)? Copy-paste this component and style it however you like.
+
+> Note: this snippet uses Tailwind utility classes. If you don’t use Tailwind, replace the classes with your own styles/UI components.
+
+```tsx
+'use client';
+
+import { formatColor, useThemeEngine } from '@fakhrirafiki/theme-engine';
+
+type ThemePresetSelectProps = {
+  allowedPresetIds?: string[];
+};
+
+export function ThemePresetSelect({
+  allowedPresetIds = [
+    'modern-minimal',
+    'violet-bloom',
+    'vercel',
+    'mono',
+  ],
+}: ThemePresetSelectProps) {
+  const { currentTheme, applyThemeById, availablePresets, resolvedMode } = useThemeEngine();
+
+  const presets = allowedPresetIds
+    .map((id) => {
+      const preset = availablePresets[id];
+      if (!preset) return null;
+      return { id, label: preset.label };
+    })
+    .filter((preset): preset is { id: string; label: string } => preset !== null);
+
+  const getPreviewColors = (presetId: string): string[] => {
+    const preset = availablePresets[presetId];
+    if (!preset) return [];
+
+    const scheme = resolvedMode === 'dark' ? preset.styles.dark : preset.styles.light;
+    const primary = (scheme as any).primary as string | undefined;
+    const secondary = (scheme as any).secondary as string | undefined;
+    const accent = (scheme as any).accent as string | undefined;
+
+    return [primary, secondary, accent].filter(Boolean) as string[];
+  };
+
+  return (
+    <div className="mt-4 max-h-[70vh] space-y-2 overflow-y-auto pr-1">
+      {presets.map((preset) => {
+        const isActive = currentTheme?.presetId === preset.id;
+        const previewColors = getPreviewColors(preset.id).slice(0, 3);
+
+        return (
+          <button
+            key={preset.id}
+            type="button"
+            className={`w-full rounded-full border px-3 py-2 text-xs transition-colors ${
+              isActive
+                ? 'border-primary/70 bg-primary/10 text-foreground'
+                : 'border-border bg-muted/40 text-muted-foreground hover:border-muted-foreground/40 hover:bg-muted/60'
+            }`}
+            onClick={() => applyThemeById(preset.id)}
+          >
+            <span className="flex items-center justify-between gap-3">
+              <span className="flex items-center gap-2">
+                {previewColors.length > 0 && (
+                  <span className="flex gap-1">
+                    {previewColors.map((color, index) => (
+                      <span
+                        key={index}
+                        className="inline-block h-2.5 w-2.5 rounded-full border border-foreground/10 shadow-sm"
+                        style={{ backgroundColor: formatColor(color, 'hex') }}
+                      />
+                    ))}
+                  </span>
+                )}
+
+                <span className="text-xs font-medium text-foreground">{preset.label}</span>
+              </span>
+
+              {isActive && (
+                <span className="inline-flex items-center rounded-full bg-primary/10 px-2 py-0.5 text-[10px] font-medium text-foreground">
+                  Aktif
+                </span>
+              )}
+            </span>
+          </button>
+        );
+      })}
+
+      {presets.length === 0 && <p className="text-xs text-muted-foreground">Belum ada tema yang tersedia.</p>}
+    </div>
+  );
+}
+```
+
 ---
 
 ## 🧾 API Reference
@@ -349,7 +445,7 @@ export function PresetPicker() {
 | `modeStorageKey` | `string` | `'theme-engine-theme'` | `localStorage` key for mode |
 | `presetStorageKey` | `string` | `'theme-preset'` | `localStorage` key for preset |
 | `customPresets` | `Record<string, TweakCNThemePreset>` | `undefined` | Add your own presets (can override built-ins by ID) |
-| `ThemeScript` | n/a | always on | `ThemeProvider` always injects `ThemeScript` for pre-hydration preset restoration |
+| `Pre-hydration script` | n/a | always on | `ThemeProvider` always injects a pre-hydration script for preset restoration |
 
 ### `useThemeEngine()`
 
@@ -382,15 +478,6 @@ Return fields:
 | `builtInPresets` | `Record<string, TweakCNThemePreset>` | Built-in only |
 | `customPresets` | `Record<string, TweakCNThemePreset>` | Custom only |
 
-### `ThemeScript`
-
-Normally you don’t need this (it’s injected by `ThemeProvider` by default).
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `presetStorageKey` | `string` | `'theme-preset'` | Must match `ThemeProvider` |
-| `defaultPreset` | `string` | `undefined` | Built-in preset ID for pre-hydration default |
-
 ### Utilities
 
 | Export | Description |
@@ -410,7 +497,7 @@ Note: the thrown error string might mention `useTheme` because `useThemeEngine()
 
 ### Preset doesn’t apply on refresh
 
-`ThemeProvider` injects `ThemeScript` automatically. Avoid rendering `ThemeScript` manually (you may end up with duplicates).
+`ThemeProvider` injects a pre-hydration script automatically. Avoid injecting another preset-restoration script manually (you may end up with duplicates).
 
 ### Styles don’t load / components look unstyled
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fakhrirafiki/theme-engine",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "Elegant theming system with smooth transitions, custom presets, semantic accent colors, and complete shadcn/ui support for modern React applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",