@fakhrirafiki/theme-engine 0.2.6 → 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
  1. package/README.md +142 -482
  2. package/dist/index.d.mts +57 -9
  3. package/dist/index.d.ts +57 -9
  4. package/dist/index.js +268 -260
  5. package/dist/index.mjs +256 -250
  6. package/dist/styles/animations.css +23 -1
  7. package/dist/styles/components.css +12 -3
  8. package/package.json +7 -7
package/dist/index.d.mts CHANGED
@@ -246,6 +246,9 @@ interface ThemeToggleProps {
246
246
  children?: ReactNode;
247
247
  }
248
248
 
249
+ declare const builtInPresetIds: readonly ["amber-minimal", "amethyst-haze", "bold-tech", "clean-slate", "cosmic-night", "doom-64", "elegant-luxury", "kodama-grove", "midnight-bloom", "mocha-mousse", "modern-minimal", "neo-brutalism", "northern-lights", "ocean-breeze", "pastel-dreams", "quantum-rose", "retro-arcade", "soft-pop", "solar-dusk", "starry-night", "sunset-horizon", "t3-chat", "vintage-paper", "violet-bloom"];
250
+ type BuiltInPresetId = (typeof builtInPresetIds)[number];
251
+
249
252
  /**
250
253
  * TweakCN Compatible Preset Collection
251
254
  *
@@ -259,6 +262,7 @@ interface ThemeToggleProps {
259
262
  * 2. Paste it into the tweakcnPresets constant below
260
263
  * 3. The conversion utilities will handle the rest
261
264
  */
265
+
262
266
  /**
263
267
  * TweakCN's ThemePreset interface structure (exact match with TweakCN)
264
268
  */
@@ -273,6 +277,7 @@ interface TweakCNThemePreset {
273
277
  /** Optional creation date (present in some TweakCN presets) */
274
278
  createdAt?: string;
275
279
  }
280
+
276
281
  /**
277
282
  * TweakCN Compatible Preset Collection
278
283
  *
@@ -283,10 +288,11 @@ declare const tweakcnPresets: Record<string, TweakCNThemePreset>;
283
288
  /**
284
289
  * Get all preset IDs
285
290
  */
286
- declare function getPresetIds(): string[];
291
+ declare function getPresetIds(): BuiltInPresetId[];
287
292
  /**
288
293
  * Get preset by ID
289
294
  */
295
+ declare function getPresetById(id: BuiltInPresetId): TweakCNThemePreset;
290
296
  declare function getPresetById(id: string): TweakCNThemePreset | null;
291
297
  /**
292
298
  * Get all preset labels
@@ -296,7 +302,7 @@ declare function getPresetLabels(): string[];
296
302
  * Search presets by name (case-insensitive)
297
303
  */
298
304
  declare function searchPresets(query: string): Array<{
299
- id: string;
305
+ id: BuiltInPresetId;
300
306
  preset: TweakCNThemePreset;
301
307
  }>;
302
308
  /**
@@ -306,7 +312,7 @@ declare function getPresetsCount(): number;
306
312
  /**
307
313
  * Get preset entries (id + preset pairs)
308
314
  */
309
- declare function getPresetEntries(): Array<[string, TweakCNThemePreset]>;
315
+ declare function getPresetEntries(): Array<[BuiltInPresetId, TweakCNThemePreset]>;
310
316
 
311
317
  /**
312
318
  * Context value for the unified theming system.
@@ -349,18 +355,21 @@ interface UnifiedThemeContextValue {
349
355
  /** Custom presets only */
350
356
  customPresets: Record<string, TweakCNThemePreset>;
351
357
  }
358
+ type CustomPresetsRecord$1 = Record<string, TweakCNThemePreset>;
359
+ type CustomPresetId$1<TCustomPresets> = TCustomPresets extends CustomPresetsRecord$1 ? Extract<keyof TCustomPresets, string> : never;
360
+ type PresetId<TCustomPresets> = BuiltInPresetId | CustomPresetId$1<TCustomPresets>;
352
361
  /**
353
362
  * Props for the UnifiedThemeProvider component.
354
363
  *
355
364
  * @public
356
365
  */
357
- interface UnifiedThemeProviderProps {
366
+ interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined> {
358
367
  /** React children to wrap with theming context */
359
368
  children: react__default.ReactNode;
360
369
  /** Default appearance mode when no stored preference exists */
361
370
  defaultMode?: Mode;
362
371
  /** Default preset ID to use when no stored preset exists or when resetting */
363
- defaultPreset?: string;
372
+ defaultPreset?: PresetId<TCustomPresets>;
364
373
  /** Enable smooth transitions between modes */
365
374
  enableTransitions?: boolean;
366
375
  /** localStorage key for appearance mode persistence */
@@ -370,9 +379,16 @@ interface UnifiedThemeProviderProps {
370
379
  /** Enable custom color preset functionality */
371
380
  enablePresets?: boolean;
372
381
  /** Custom presets to add to the available collection */
373
- customPresets?: Record<string, TweakCNThemePreset>;
382
+ customPresets?: TCustomPresets;
374
383
  /** Whether to include built-in TweakCN presets (default: true) */
375
384
  includeBuiltInPresets?: boolean;
385
+ /** Disable injecting `ThemeScript` from inside `ThemeProvider` (useful if you render it in `<head>` yourself). */
386
+ disableScript?: boolean;
387
+ /**
388
+ * When true, the provider renders `null` until persisted preset is loaded from storage.
389
+ * Defaults to `true` when `disableScript` is enabled (backwards behavior), otherwise `false`.
390
+ */
391
+ deferRenderUntilReady?: boolean;
376
392
  }
377
393
  /**
378
394
  * Theme Provider - The heart of the elegant theming system.
@@ -402,7 +418,7 @@ interface UnifiedThemeProviderProps {
402
418
  *
403
419
  * @public
404
420
  */
405
- declare function ThemeProvider({ children, defaultMode, defaultPreset, enableTransitions, modeStorageKey, presetStorageKey, enablePresets, customPresets, includeBuiltInPresets, }: UnifiedThemeProviderProps): react_jsx_runtime.JSX.Element | null;
421
+ declare function ThemeProvider<const TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined>({ children, defaultMode, defaultPreset, enableTransitions, modeStorageKey, presetStorageKey, enablePresets, customPresets, includeBuiltInPresets, disableScript, deferRenderUntilReady, }: UnifiedThemeProviderProps<TCustomPresets>): react_jsx_runtime.JSX.Element | null;
406
422
  /**
407
423
  * Hook for accessing the unified theming system.
408
424
  *
@@ -474,7 +490,39 @@ declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & re
474
490
  /**
475
491
  * Main ThemePresetButtons component
476
492
  */
477
- declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, groupBy, labels, showSectionHeaders, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
493
+ declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
494
+
495
+ type CustomPresetsRecord = Record<string, TweakCNThemePreset>;
496
+ type CustomPresetId<TCustomPresets> = TCustomPresets extends CustomPresetsRecord ? Extract<keyof TCustomPresets, string> : never;
497
+ type ThemePresetId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = BuiltInPresetId | CustomPresetId<TCustomPresets>;
498
+ type LooseString = string & {};
499
+ /**
500
+ * Typed convenience wrapper around `useTheme()` that provides IntelliSense for preset IDs.
501
+ *
502
+ * - Built-in IDs come from `BuiltInPresetId`
503
+ * - Custom IDs are inferred from the keys of the `customPresets` argument
504
+ *
505
+ * The resulting `setThemePresetById()` still accepts any string, but VS Code will suggest known IDs first.
506
+ */
507
+ declare function useTypedTheme<const TCustomPresets extends CustomPresetsRecord | undefined = undefined>(customPresets?: TCustomPresets): {
508
+ setThemePresetById: (presetId: LooseString | ThemePresetId<TCustomPresets>) => void;
509
+ mode: Mode;
510
+ resolvedMode: "light" | "dark";
511
+ setMode: (mode: Mode) => void;
512
+ toggleMode: (coordinates?: Coordinates) => void;
513
+ currentPreset: {
514
+ presetId: string;
515
+ presetName: string;
516
+ colors: ThemePreset["colors"];
517
+ appliedAt: number;
518
+ } | null;
519
+ applyPreset: (preset: ThemePreset) => void;
520
+ clearPreset: () => void;
521
+ isUsingDefaultPreset: boolean;
522
+ availablePresets: Record<string, TweakCNThemePreset>;
523
+ builtInPresets: Record<string, TweakCNThemePreset>;
524
+ customPresets: Record<string, TweakCNThemePreset>;
525
+ };
478
526
 
479
527
  /**
480
528
  * Lightweight color utilities for theme-engine
@@ -517,4 +565,4 @@ declare function validateCustomPresets(customPresets: Record<string, TweakCNThem
517
565
  */
518
566
  declare function logValidationResult(result: ValidationResult, context?: string): void;
519
567
 
520
- export { type CompleteThemeSchema, type Coordinates, type Mode, type PresetProvider, type ThemePreset, ThemePresetButtons, type ThemePresetButtonsProps, ThemeProvider, ThemeScript, ThemeToggle, type ThemeToggleProps, type TweakCNThemePreset, type ValidationResult, formatColor, getPresetById, getPresetEntries, getPresetIds, getPresetLabels, getPresetsCount, logValidationResult, searchPresets, tweakcnPresets, useTheme, validateCustomPresets, validateTweakCNPreset, withAlpha };
568
+ export { type BuiltInPresetId, type CompleteThemeSchema, type Coordinates, type Mode, type PresetProvider, type ThemePreset, ThemePresetButtons, type ThemePresetButtonsProps, type ThemePresetId, ThemeProvider, ThemeScript, ThemeToggle, type ThemeToggleProps, type TweakCNThemePreset, type ValidationResult, builtInPresetIds, formatColor, getPresetById, getPresetEntries, getPresetIds, getPresetLabels, getPresetsCount, logValidationResult, searchPresets, tweakcnPresets, useTheme, useTypedTheme, validateCustomPresets, validateTweakCNPreset, withAlpha };
package/dist/index.d.ts CHANGED
@@ -246,6 +246,9 @@ interface ThemeToggleProps {
246
246
  children?: ReactNode;
247
247
  }
248
248
 
249
+ declare const builtInPresetIds: readonly ["amber-minimal", "amethyst-haze", "bold-tech", "clean-slate", "cosmic-night", "doom-64", "elegant-luxury", "kodama-grove", "midnight-bloom", "mocha-mousse", "modern-minimal", "neo-brutalism", "northern-lights", "ocean-breeze", "pastel-dreams", "quantum-rose", "retro-arcade", "soft-pop", "solar-dusk", "starry-night", "sunset-horizon", "t3-chat", "vintage-paper", "violet-bloom"];
250
+ type BuiltInPresetId = (typeof builtInPresetIds)[number];
251
+
249
252
  /**
250
253
  * TweakCN Compatible Preset Collection
251
254
  *
@@ -259,6 +262,7 @@ interface ThemeToggleProps {
259
262
  * 2. Paste it into the tweakcnPresets constant below
260
263
  * 3. The conversion utilities will handle the rest
261
264
  */
265
+
262
266
  /**
263
267
  * TweakCN's ThemePreset interface structure (exact match with TweakCN)
264
268
  */
@@ -273,6 +277,7 @@ interface TweakCNThemePreset {
273
277
  /** Optional creation date (present in some TweakCN presets) */
274
278
  createdAt?: string;
275
279
  }
280
+
276
281
  /**
277
282
  * TweakCN Compatible Preset Collection
278
283
  *
@@ -283,10 +288,11 @@ declare const tweakcnPresets: Record<string, TweakCNThemePreset>;
283
288
  /**
284
289
  * Get all preset IDs
285
290
  */
286
- declare function getPresetIds(): string[];
291
+ declare function getPresetIds(): BuiltInPresetId[];
287
292
  /**
288
293
  * Get preset by ID
289
294
  */
295
+ declare function getPresetById(id: BuiltInPresetId): TweakCNThemePreset;
290
296
  declare function getPresetById(id: string): TweakCNThemePreset | null;
291
297
  /**
292
298
  * Get all preset labels
@@ -296,7 +302,7 @@ declare function getPresetLabels(): string[];
296
302
  * Search presets by name (case-insensitive)
297
303
  */
298
304
  declare function searchPresets(query: string): Array<{
299
- id: string;
305
+ id: BuiltInPresetId;
300
306
  preset: TweakCNThemePreset;
301
307
  }>;
302
308
  /**
@@ -306,7 +312,7 @@ declare function getPresetsCount(): number;
306
312
  /**
307
313
  * Get preset entries (id + preset pairs)
308
314
  */
309
- declare function getPresetEntries(): Array<[string, TweakCNThemePreset]>;
315
+ declare function getPresetEntries(): Array<[BuiltInPresetId, TweakCNThemePreset]>;
310
316
 
311
317
  /**
312
318
  * Context value for the unified theming system.
@@ -349,18 +355,21 @@ interface UnifiedThemeContextValue {
349
355
  /** Custom presets only */
350
356
  customPresets: Record<string, TweakCNThemePreset>;
351
357
  }
358
+ type CustomPresetsRecord$1 = Record<string, TweakCNThemePreset>;
359
+ type CustomPresetId$1<TCustomPresets> = TCustomPresets extends CustomPresetsRecord$1 ? Extract<keyof TCustomPresets, string> : never;
360
+ type PresetId<TCustomPresets> = BuiltInPresetId | CustomPresetId$1<TCustomPresets>;
352
361
  /**
353
362
  * Props for the UnifiedThemeProvider component.
354
363
  *
355
364
  * @public
356
365
  */
357
- interface UnifiedThemeProviderProps {
366
+ interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined> {
358
367
  /** React children to wrap with theming context */
359
368
  children: react__default.ReactNode;
360
369
  /** Default appearance mode when no stored preference exists */
361
370
  defaultMode?: Mode;
362
371
  /** Default preset ID to use when no stored preset exists or when resetting */
363
- defaultPreset?: string;
372
+ defaultPreset?: PresetId<TCustomPresets>;
364
373
  /** Enable smooth transitions between modes */
365
374
  enableTransitions?: boolean;
366
375
  /** localStorage key for appearance mode persistence */
@@ -370,9 +379,16 @@ interface UnifiedThemeProviderProps {
370
379
  /** Enable custom color preset functionality */
371
380
  enablePresets?: boolean;
372
381
  /** Custom presets to add to the available collection */
373
- customPresets?: Record<string, TweakCNThemePreset>;
382
+ customPresets?: TCustomPresets;
374
383
  /** Whether to include built-in TweakCN presets (default: true) */
375
384
  includeBuiltInPresets?: boolean;
385
+ /** Disable injecting `ThemeScript` from inside `ThemeProvider` (useful if you render it in `<head>` yourself). */
386
+ disableScript?: boolean;
387
+ /**
388
+ * When true, the provider renders `null` until persisted preset is loaded from storage.
389
+ * Defaults to `true` when `disableScript` is enabled (backwards behavior), otherwise `false`.
390
+ */
391
+ deferRenderUntilReady?: boolean;
376
392
  }
377
393
  /**
378
394
  * Theme Provider - The heart of the elegant theming system.
@@ -402,7 +418,7 @@ interface UnifiedThemeProviderProps {
402
418
  *
403
419
  * @public
404
420
  */
405
- declare function ThemeProvider({ children, defaultMode, defaultPreset, enableTransitions, modeStorageKey, presetStorageKey, enablePresets, customPresets, includeBuiltInPresets, }: UnifiedThemeProviderProps): react_jsx_runtime.JSX.Element | null;
421
+ declare function ThemeProvider<const TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined>({ children, defaultMode, defaultPreset, enableTransitions, modeStorageKey, presetStorageKey, enablePresets, customPresets, includeBuiltInPresets, disableScript, deferRenderUntilReady, }: UnifiedThemeProviderProps<TCustomPresets>): react_jsx_runtime.JSX.Element | null;
406
422
  /**
407
423
  * Hook for accessing the unified theming system.
408
424
  *
@@ -474,7 +490,39 @@ declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & re
474
490
  /**
475
491
  * Main ThemePresetButtons component
476
492
  */
477
- declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, groupBy, labels, showSectionHeaders, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
493
+ declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
494
+
495
+ type CustomPresetsRecord = Record<string, TweakCNThemePreset>;
496
+ type CustomPresetId<TCustomPresets> = TCustomPresets extends CustomPresetsRecord ? Extract<keyof TCustomPresets, string> : never;
497
+ type ThemePresetId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = BuiltInPresetId | CustomPresetId<TCustomPresets>;
498
+ type LooseString = string & {};
499
+ /**
500
+ * Typed convenience wrapper around `useTheme()` that provides IntelliSense for preset IDs.
501
+ *
502
+ * - Built-in IDs come from `BuiltInPresetId`
503
+ * - Custom IDs are inferred from the keys of the `customPresets` argument
504
+ *
505
+ * The resulting `setThemePresetById()` still accepts any string, but VS Code will suggest known IDs first.
506
+ */
507
+ declare function useTypedTheme<const TCustomPresets extends CustomPresetsRecord | undefined = undefined>(customPresets?: TCustomPresets): {
508
+ setThemePresetById: (presetId: LooseString | ThemePresetId<TCustomPresets>) => void;
509
+ mode: Mode;
510
+ resolvedMode: "light" | "dark";
511
+ setMode: (mode: Mode) => void;
512
+ toggleMode: (coordinates?: Coordinates) => void;
513
+ currentPreset: {
514
+ presetId: string;
515
+ presetName: string;
516
+ colors: ThemePreset["colors"];
517
+ appliedAt: number;
518
+ } | null;
519
+ applyPreset: (preset: ThemePreset) => void;
520
+ clearPreset: () => void;
521
+ isUsingDefaultPreset: boolean;
522
+ availablePresets: Record<string, TweakCNThemePreset>;
523
+ builtInPresets: Record<string, TweakCNThemePreset>;
524
+ customPresets: Record<string, TweakCNThemePreset>;
525
+ };
478
526
 
479
527
  /**
480
528
  * Lightweight color utilities for theme-engine
@@ -517,4 +565,4 @@ declare function validateCustomPresets(customPresets: Record<string, TweakCNThem
517
565
  */
518
566
  declare function logValidationResult(result: ValidationResult, context?: string): void;
519
567
 
520
- export { type CompleteThemeSchema, type Coordinates, type Mode, type PresetProvider, type ThemePreset, ThemePresetButtons, type ThemePresetButtonsProps, ThemeProvider, ThemeScript, ThemeToggle, type ThemeToggleProps, type TweakCNThemePreset, type ValidationResult, formatColor, getPresetById, getPresetEntries, getPresetIds, getPresetLabels, getPresetsCount, logValidationResult, searchPresets, tweakcnPresets, useTheme, validateCustomPresets, validateTweakCNPreset, withAlpha };
568
+ export { type BuiltInPresetId, type CompleteThemeSchema, type Coordinates, type Mode, type PresetProvider, type ThemePreset, ThemePresetButtons, type ThemePresetButtonsProps, type ThemePresetId, ThemeProvider, ThemeScript, ThemeToggle, type ThemeToggleProps, type TweakCNThemePreset, type ValidationResult, builtInPresetIds, formatColor, getPresetById, getPresetEntries, getPresetIds, getPresetLabels, getPresetsCount, logValidationResult, searchPresets, tweakcnPresets, useTheme, useTypedTheme, validateCustomPresets, validateTweakCNPreset, withAlpha };