uitheme-web 1.0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 tonyedgal
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,226 @@
1
+ # uitheme-web
2
+
3
+ Web framework agnostic UI theme switching library. Built with a framework-agnostic core and React adapter. Additional framework support planned for future releases.
4
+
5
+ ## UI-Theme version 1 release
6
+
7
+ Introducing version 1 of `uitheme-web`, a comprehensive solution for managing UI themes across web applications. This release marks a significant milestone in our journey to provide developers with a robust, flexible, and easy-to-use theming library, that supports all web javascript UI frameworks.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install uitheme-web
13
+ ```
14
+
15
+ ```bash
16
+ pnpm add uitheme-web
17
+ ```
18
+
19
+ ```bash
20
+ yarn add uitheme-web
21
+ ```
22
+
23
+ ## Tailwind Setup For Prebuilt Components
24
+
25
+ `UIThemeSwitcher`, `UIThemeSelector`, and the bundled select primitives use Tailwind utility classes. `uitheme-web` does not ship a compiled CSS file for those components, so the consuming app must include the package in Tailwind's source scan.
26
+
27
+ For Tailwind v4, add an `@source` directive next to your Tailwind import:
28
+
29
+ ```css
30
+ @import 'tailwindcss';
31
+ @source '../node_modules/uitheme-web/dist';
32
+ ```
33
+
34
+ Adjust the relative path to match your app structure.
35
+
36
+ If you are using the prebuilt components without this setup, the controls will mount but the expected borders, spacing, typography, hover states, and dropdown styling will be missing because Tailwind never sees the classes inside the installed package.
37
+
38
+ ## Provider Selection
39
+
40
+ Choose the right provider for your framework:
41
+
42
+ | Provider | Best For | Key Features |
43
+ | ----------------------- | ------------------------------ | ------------------------------------------------ |
44
+ | UIThemeProvider | All React apps | Universal provider with full feature set |
45
+ | NextUIThemeProvider | Next.js, Remix, SSR frameworks | Pre-hydration script, CSP support, animations |
46
+ | TanStackUIThemeProvider | TanStack Start apps | Isomorphic rendering, useHydrated() integration |
47
+ | ViteUIThemeProvider | Vite React SPAs | Lightweight, transition control, no SSR overhead |
48
+
49
+ ## Quick Start
50
+
51
+ ### React
52
+
53
+ Basic pattern that works across all providers:
54
+
55
+ ```tsx
56
+ import { UIThemeProvider, useUITheme } from 'uitheme-web/react';
57
+
58
+ function App() {
59
+ return (
60
+ <UIThemeProvider defaultTheme="system" defaultColorTheme="default">
61
+ <YourApp />
62
+ </UIThemeProvider>
63
+ );
64
+ }
65
+
66
+ function ThemeToggle() {
67
+ const { theme, toggleTheme, ref } = useUITheme();
68
+
69
+ return (
70
+ <button ref={ref} onClick={() => toggleTheme()}>
71
+ {theme === 'light' ? 'Dark' : 'Light'}
72
+ </button>
73
+ );
74
+ }
75
+ ```
76
+
77
+ **Framework Setup Guides:**
78
+
79
+ - [Next.js / SSR Setup Guide](../../docs/nextjs-setup.md) - Complete guide with App Router, Pages Router, CSP support
80
+ - [TanStack Start Setup Guide](../../docs/tanstack-start-setup.md) - Isomorphic rendering, hydration-safe patterns
81
+ - [Vite React SPA Setup Guide](../../docs/vite-setup.md) - Client-side setup, flash prevention, routing
82
+
83
+ ## API Reference
84
+
85
+ ### Shared Hook Return (All Providers)
86
+
87
+ All providers expose the same hook interface:
88
+
89
+ | Property | Type | Description |
90
+ | ---------------------- | ------------------------------------------------------- | ---------------------------------- |
91
+ | theme | Theme | Current theme |
92
+ | colorTheme | ColorTheme | Current color theme |
93
+ | resolvedTheme | 'light' \| 'dark' | Resolved theme (system → actual) |
94
+ | systemTheme | 'light' \| 'dark' | OS theme preference |
95
+ | ref | RefObject<HTMLElement> | Ref for animation origin |
96
+ | setTheme | (theme: Theme) => void | Set theme instantly |
97
+ | setColorTheme | (colorTheme: ColorTheme) => void | Set color theme |
98
+ | switchTheme | (theme: Theme, animationOff?: boolean) => Promise<void> | Switch with animation |
99
+ | switchColorTheme | (colorTheme: string) => void | Switch color theme with animation |
100
+ | toggleTheme | (animationOff?: boolean) => Promise<void> | Toggle light/dark |
101
+ | toggleLightTheme | (animationOff?: boolean) => Promise<void> | Toggle to light |
102
+ | toggleDarkTheme | (animationOff?: boolean) => Promise<void> | Toggle to dark |
103
+ | toggleColorTheme | () => void | Toggle between color themes |
104
+ | createColorThemeToggle | (colorTheme: string) => () => void | Create color theme toggle |
105
+ | isColorThemeActive | (colorTheme: string) => boolean | Check if color theme active |
106
+ | switchThemeFromElement | (theme: Theme, element: HTMLElement) => Promise<void> | Switch with animation from element |
107
+
108
+ ### Provider Props
109
+
110
+ | Prop | UITheme | NextUITheme | TanStackUITheme | ViteUITheme | Type | Default |
111
+ | ------------------------- | ------- | ----------- | --------------- | ----------- | ------------------ | --------------------------- |
112
+ | defaultTheme | ✓ | ✓ | ✓ | ✓ | Theme | 'system' |
113
+ | defaultColorTheme | ✓ | ✓ | ✓ | ✓ | ColorTheme | 'default' |
114
+ | themes | ✓ | ✓ | ✓ | ✓ | Theme[] | ['light', 'dark', 'system'] |
115
+ | colorThemes | ✓ | ✓ | ✓ | ✓ | ColorTheme[] | ['default'] |
116
+ | animationType | ✓ | ✓ | ✓ | ✓ | ThemeAnimationType | CIRCLE |
117
+ | duration | ✓ | ✓ | ✓ | ✓ | number | 500 |
118
+ | storageKey | ✓ | ✓ | ✓ | ✓ | string | varies |
119
+ | colorStorageKey | ✓ | ✓ | ✓ | ✓ | string | varies |
120
+ | nonce | ✗ | ✓ | ✗ | ✗ | string | - |
121
+ | disablePreHydrationScript | ✗ | ✓ | ✗ | ✗ | boolean | false |
122
+ | disableTransitionOnChange | ✗ | ✗ | ✗ | ✓ | boolean | false |
123
+ | onThemeChange | ✓ | ✓ | ✓ | ✓ | function | - |
124
+ | onColorThemeChange | ✓ | ✓ | ✓ | ✓ | function | - |
125
+
126
+ ### Components
127
+
128
+ **UIThemeSwitcher**: Pre-built theme toggle buttons with animations
129
+ **UIThemeSelector**: Dropdown selector for color themes
130
+
131
+ See framework-specific guides for component usage examples.
132
+
133
+ ---
134
+
135
+ <details>
136
+ <summary>CSS Variables Setup</summary>
137
+
138
+ Define theme variables in your global CSS file:
139
+
140
+ ```css
141
+ :root {
142
+ --background: 0 0% 100%;
143
+ --foreground: 222.2 84% 4.9%;
144
+ --primary: 221.2 83.2% 53.3%;
145
+ }
146
+
147
+ .dark {
148
+ --background: 222.2 84% 4.9%;
149
+ --foreground: 210 40% 98%;
150
+ --primary: 217.2 91.2% 59.8%;
151
+ }
152
+
153
+ /* Color theme variants */
154
+ .theme-blue {
155
+ --primary: 221.2 83.2% 53.3%;
156
+ }
157
+
158
+ .theme-blue.dark {
159
+ --primary: 217.2 91.2% 59.8%;
160
+ }
161
+
162
+ .theme-green {
163
+ --primary: 142.1 76.2% 36.3%;
164
+ }
165
+
166
+ .theme-green.dark {
167
+ --primary: 142.1 70.6% 45.3%;
168
+ }
169
+ ```
170
+
171
+ </details>
172
+
173
+ <details>
174
+ <summary>Browser Support</summary>
175
+
176
+ - View Transitions API: Chrome 111+, Edge 111+
177
+ - Fallback: All modern browsers with CSS transitions
178
+ - Reduced Motion: Respects prefers-reduced-motion
179
+ - Framework Support: React 16.8+ (hooks required)
180
+
181
+ </details>
182
+
183
+ <details>
184
+ <summary>Advanced Configuration</summary>
185
+
186
+ ### Animation Control
187
+
188
+ ```tsx
189
+ const { switchTheme, toggleTheme } = useUITheme();
190
+
191
+ // With animation (default)
192
+ await switchTheme('dark');
193
+
194
+ // Without animation
195
+ await switchTheme('dark', true);
196
+ await toggleTheme(true);
197
+ ```
198
+
199
+ ### Custom Hook Usage
200
+
201
+ ```tsx
202
+ import { useTheme } from 'uitheme-web/react';
203
+
204
+ const { theme, toggleTheme, ref } = useTheme({
205
+ animationType: ThemeAnimationType.BLUR_CIRCLE,
206
+ duration: 750,
207
+ colorThemes: ['default', 'blue', 'green'],
208
+ onThemeChange: (theme) => console.log('Theme:', theme),
209
+ });
210
+ ```
211
+
212
+ </details>
213
+
214
+ ## Features
215
+
216
+ - Multiple theme support (light, dark, system)
217
+ - Framework-agnostic core
218
+ - Persistent theme storage
219
+ - SSR/SSG compatible
220
+ - Tree-shakeable
221
+ - TypeScript support
222
+ - Zero dependencies (per framework)
223
+
224
+ ## License
225
+
226
+ MIT
@@ -0,0 +1,106 @@
1
+ declare enum ThemeAnimationType {
2
+ CIRCLE = "circle",
3
+ BLUR_CIRCLE = "blur-circle",
4
+ SLIDE = "slide"
5
+ }
6
+ type Theme = 'light' | 'dark' | 'system';
7
+ type ColorTheme = string;
8
+ type SlideDirection = 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
9
+ interface AnimationConfig {
10
+ a?: number;
11
+ b?: number;
12
+ x: number;
13
+ y: number;
14
+ duration: number;
15
+ easing: string;
16
+ animationType: ThemeAnimationType;
17
+ blurAmount: number;
18
+ styleId: string;
19
+ }
20
+ interface ThemeConfig {
21
+ themes?: Theme[];
22
+ colorThemes?: ColorTheme[];
23
+ defaultTheme?: Theme;
24
+ defaultColorTheme?: ColorTheme;
25
+ globalClassName?: string;
26
+ colorThemePrefix?: string;
27
+ storageKey?: string;
28
+ colorStorageKey?: string;
29
+ }
30
+ interface ThemeState {
31
+ theme: Theme;
32
+ colorTheme: ColorTheme;
33
+ resolvedTheme: 'light' | 'dark';
34
+ }
35
+
36
+ /**
37
+ * Injects base styles required for view transitions
38
+ */
39
+ declare const injectBaseStyles: () => void;
40
+ /**
41
+ * Creates an SVG blur circle mask for animations
42
+ * @param blur - Blur amount for the gaussian filter
43
+ * @returns Data URI string for the SVG mask
44
+ */
45
+ declare const createBlurCircleMask: (blur: number) => string;
46
+ /**
47
+ * Gets the system theme preference
48
+ * @returns 'light' or 'dark' based on system preference
49
+ */
50
+ declare const getSystemTheme: () => "light" | "dark";
51
+ /**
52
+ * Resolves a theme value to its actual light/dark value
53
+ * @param theme - Theme to resolve ('light', 'dark', or 'system')
54
+ * @returns Resolved theme ('light' or 'dark')
55
+ */
56
+ declare const resolveTheme: (theme: string) => "light" | "dark";
57
+ /**
58
+ * Resolves a stored theme to the server-side class to apply on <html>.
59
+ * CSS mode uses the 'system' class so media queries can respond before hydration.
60
+ */
61
+ declare const resolveThemeForServer: (theme: string) => "light" | "dark" | "system";
62
+ /**
63
+ * Checks if the browser supports View Transitions API
64
+ * @returns true if view transitions are supported
65
+ */
66
+ declare const supportsViewTransitions: () => boolean;
67
+ /**
68
+ * Checks if user prefers reduced motion
69
+ * @returns true if user prefers reduced motion
70
+ */
71
+ declare const prefersReducedMotion: () => boolean;
72
+ /**
73
+ * Converts a slide direction to from coordinates
74
+ * @param direction - Slide direction
75
+ * @returns Object with a (x) and b (y) coordinates
76
+ */
77
+ declare const getSlideFromCoords: (direction: SlideDirection) => {
78
+ a: number;
79
+ b: number;
80
+ };
81
+ /**
82
+ * Creates a circle expanding animation for theme transitions
83
+ * @param config - Animation configuration
84
+ */
85
+ declare const createCircleAnimation: (config: AnimationConfig) => void;
86
+ /**
87
+ * Creates a slide animation for theme transitions
88
+ * @param config - Animation configuration
89
+ */
90
+ declare const createSlideAnimation: (config: AnimationConfig) => void;
91
+ /**
92
+ * Creates a blur circle animation for theme transitions
93
+ * @param config - Animation configuration
94
+ */
95
+ declare const createBlurCircleAnimation: (config: AnimationConfig) => void;
96
+
97
+ declare const STORAGE_KEY = "theme";
98
+ declare const COLOR_STORAGE_KEY = "color-theme";
99
+ declare const GLOBAL_CLASS_NAME = "dark";
100
+ declare const COLOR_THEME_PREFIX = "theme-";
101
+ declare const DEFAULT_DURATION = 750;
102
+ declare const DEFAULT_EASING = "ease-in-out";
103
+ declare const DEFAULT_BLUR_AMOUNT = 2;
104
+ declare const DEFAULT_STYLE_ID = "ui-theme-style";
105
+
106
+ export { type AnimationConfig as A, type ColorTheme as C, DEFAULT_DURATION as D, GLOBAL_CLASS_NAME as G, type SlideDirection as S, type Theme as T, ThemeAnimationType as a, type ThemeConfig as b, type ThemeState as c, createCircleAnimation as d, createBlurCircleAnimation as e, createSlideAnimation as f, getSystemTheme as g, createBlurCircleMask as h, injectBaseStyles as i, getSlideFromCoords as j, STORAGE_KEY as k, COLOR_STORAGE_KEY as l, COLOR_THEME_PREFIX as m, DEFAULT_EASING as n, DEFAULT_BLUR_AMOUNT as o, prefersReducedMotion as p, DEFAULT_STYLE_ID as q, resolveTheme as r, supportsViewTransitions as s, resolveThemeForServer as t };
@@ -0,0 +1,106 @@
1
+ declare enum ThemeAnimationType {
2
+ CIRCLE = "circle",
3
+ BLUR_CIRCLE = "blur-circle",
4
+ SLIDE = "slide"
5
+ }
6
+ type Theme = 'light' | 'dark' | 'system';
7
+ type ColorTheme = string;
8
+ type SlideDirection = 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
9
+ interface AnimationConfig {
10
+ a?: number;
11
+ b?: number;
12
+ x: number;
13
+ y: number;
14
+ duration: number;
15
+ easing: string;
16
+ animationType: ThemeAnimationType;
17
+ blurAmount: number;
18
+ styleId: string;
19
+ }
20
+ interface ThemeConfig {
21
+ themes?: Theme[];
22
+ colorThemes?: ColorTheme[];
23
+ defaultTheme?: Theme;
24
+ defaultColorTheme?: ColorTheme;
25
+ globalClassName?: string;
26
+ colorThemePrefix?: string;
27
+ storageKey?: string;
28
+ colorStorageKey?: string;
29
+ }
30
+ interface ThemeState {
31
+ theme: Theme;
32
+ colorTheme: ColorTheme;
33
+ resolvedTheme: 'light' | 'dark';
34
+ }
35
+
36
+ /**
37
+ * Injects base styles required for view transitions
38
+ */
39
+ declare const injectBaseStyles: () => void;
40
+ /**
41
+ * Creates an SVG blur circle mask for animations
42
+ * @param blur - Blur amount for the gaussian filter
43
+ * @returns Data URI string for the SVG mask
44
+ */
45
+ declare const createBlurCircleMask: (blur: number) => string;
46
+ /**
47
+ * Gets the system theme preference
48
+ * @returns 'light' or 'dark' based on system preference
49
+ */
50
+ declare const getSystemTheme: () => "light" | "dark";
51
+ /**
52
+ * Resolves a theme value to its actual light/dark value
53
+ * @param theme - Theme to resolve ('light', 'dark', or 'system')
54
+ * @returns Resolved theme ('light' or 'dark')
55
+ */
56
+ declare const resolveTheme: (theme: string) => "light" | "dark";
57
+ /**
58
+ * Resolves a stored theme to the server-side class to apply on <html>.
59
+ * CSS mode uses the 'system' class so media queries can respond before hydration.
60
+ */
61
+ declare const resolveThemeForServer: (theme: string) => "light" | "dark" | "system";
62
+ /**
63
+ * Checks if the browser supports View Transitions API
64
+ * @returns true if view transitions are supported
65
+ */
66
+ declare const supportsViewTransitions: () => boolean;
67
+ /**
68
+ * Checks if user prefers reduced motion
69
+ * @returns true if user prefers reduced motion
70
+ */
71
+ declare const prefersReducedMotion: () => boolean;
72
+ /**
73
+ * Converts a slide direction to from coordinates
74
+ * @param direction - Slide direction
75
+ * @returns Object with a (x) and b (y) coordinates
76
+ */
77
+ declare const getSlideFromCoords: (direction: SlideDirection) => {
78
+ a: number;
79
+ b: number;
80
+ };
81
+ /**
82
+ * Creates a circle expanding animation for theme transitions
83
+ * @param config - Animation configuration
84
+ */
85
+ declare const createCircleAnimation: (config: AnimationConfig) => void;
86
+ /**
87
+ * Creates a slide animation for theme transitions
88
+ * @param config - Animation configuration
89
+ */
90
+ declare const createSlideAnimation: (config: AnimationConfig) => void;
91
+ /**
92
+ * Creates a blur circle animation for theme transitions
93
+ * @param config - Animation configuration
94
+ */
95
+ declare const createBlurCircleAnimation: (config: AnimationConfig) => void;
96
+
97
+ declare const STORAGE_KEY = "theme";
98
+ declare const COLOR_STORAGE_KEY = "color-theme";
99
+ declare const GLOBAL_CLASS_NAME = "dark";
100
+ declare const COLOR_THEME_PREFIX = "theme-";
101
+ declare const DEFAULT_DURATION = 750;
102
+ declare const DEFAULT_EASING = "ease-in-out";
103
+ declare const DEFAULT_BLUR_AMOUNT = 2;
104
+ declare const DEFAULT_STYLE_ID = "ui-theme-style";
105
+
106
+ export { type AnimationConfig as A, type ColorTheme as C, DEFAULT_DURATION as D, GLOBAL_CLASS_NAME as G, type SlideDirection as S, type Theme as T, ThemeAnimationType as a, type ThemeConfig as b, type ThemeState as c, createCircleAnimation as d, createBlurCircleAnimation as e, createSlideAnimation as f, getSystemTheme as g, createBlurCircleMask as h, injectBaseStyles as i, getSlideFromCoords as j, STORAGE_KEY as k, COLOR_STORAGE_KEY as l, COLOR_THEME_PREFIX as m, DEFAULT_EASING as n, DEFAULT_BLUR_AMOUNT as o, prefersReducedMotion as p, DEFAULT_STYLE_ID as q, resolveTheme as r, supportsViewTransitions as s, resolveThemeForServer as t };