@tydavidson/design-system 1.1.15 → 1.1.16

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 (12) hide show
  1. package/dist/index.js +65 -2
  2. package/dist/index.js.map +1 -1
  3. package/dist/index.mjs +65 -2
  4. package/dist/index.mjs.map +1 -1
  5. package/dist/themes/index.d.mts +6 -2
  6. package/dist/themes/index.d.ts +6 -2
  7. package/dist/themes/index.js +65 -2
  8. package/dist/themes/index.js.map +1 -1
  9. package/dist/themes/index.mjs +65 -2
  10. package/dist/themes/index.mjs.map +1 -1
  11. package/docs/troubleshooting.md +147 -99
  12. package/package.json +1 -1
package/docs/troubleshooting.md CHANGED
@@ -1,148 +1,196 @@
1
1
  # Troubleshooting Guide
2
2
 
3
- Quick solutions for common issues when using the Float Design System.
3
+ This guide helps you resolve common issues when using the Float Design System.
4
4
 
5
- ## 🚨 Critical Issues
5
+ ## Quick Reference
6
6
 
7
- ### "Module not found" errors
7
+ | Issue | Solution | Version |
8
+ |-------|----------|---------|
9
+ | React Context errors in Next.js App Router | Use `ClientThemeProvider` and `ClientThemeToggle` | 1.1.9+ |
10
+ | Invalid hook call errors | Use `ClientThemeToggle` instead of `ThemeToggle` | 1.1.15+ |
11
+ | Server Component compatibility issues | Use Server Component safe components | 1.1.15+ |
8
12
 
9
- **Problem**: Can't import from `@tydavidson/design-system/themes`
13
+ ## Common Issues and Solutions
10
14
 
11
- **Solution**:
12
- 1. Ensure you're using version 1.1.4 or later
13
- 2. Clear your node_modules and reinstall: `rm -rf node_modules package-lock.json && npm install`
14
-
15
- ### React Context errors in Next.js App Router
15
+ ### 1. React Context Errors in Next.js App Router
16
16
 
17
- **Problem**: `Error: useTheme must be used within a ThemeContextProvider` or `createContext is not a function`
17
+ **Problem**: Server-side rendering doesn't match client-side rendering.
18
18
 
19
- **Solution**:
20
- 1. Use version 1.1.9 or later (Server Component compatibility added)
21
- 2. Use `ClientThemeProvider` instead of `ThemeProvider` in your root layout
22
- 3. For Server Components, use `useThemeServer` instead of `useTheme`
23
- 4. For theme toggles in Server Components, use `ClientThemeToggle`
19
+ **Solution**:
20
+ - Add `suppressHydrationWarning` to your `<html>` element
21
+ - Use the `mounted` pattern for client-only components:
24
22
 
25
23
  ```tsx
26
- // app/layout.tsx - Use ClientThemeProvider
27
- import { ClientThemeProvider } from '@tydavidson/design-system/themes';
28
-
29
- export default function RootLayout({ children }) {
30
- return (
31
- <html lang="en" suppressHydrationWarning>
32
- <body>
33
- <ClientThemeProvider>
34
- {children}
35
- </ClientThemeProvider>
36
- </body>
37
- </html>
38
- );
24
+ function ClientOnlyComponent() {
25
+ const [mounted, setMounted] = useState(false);
26
+
27
+ useEffect(() => {
28
+ setMounted(true);
29
+ }, []);
30
+
31
+ if (!mounted) return null;
32
+
33
+ return <ThemeToggle />;
39
34
  }
40
35
  ```
41
36
 
42
- ### Hydration mismatch errors
37
+ ### 2. Invalid Hook Call Errors
43
38
 
44
- **Problem**: Server and client rendering don't match
39
+ **Problem**: `Error: Invalid hook call. Hooks can only be called inside of the body of a function component.`
40
+
41
+ **Root Cause**: The design system was trying to use React hooks in invalid contexts.
42
+
43
+ **Solution**:
44
+ - Use `ClientThemeToggle` instead of `ThemeToggle` in Server Components
45
+ - Use `ClientThemeProvider` instead of `ThemeProvider` in Server Components
46
+ - All components that use hooks are now properly protected
45
47
 
46
- **Solution**:
47
48
  ```tsx
48
- // Add to your root layout
49
- <html lang="en" suppressHydrationWarning>
50
- ```
49
+ // ✅ Correct - Server Component safe
50
+ import { ClientThemeToggle } from '@tydavidson/design-system/themes';
51
51
 
52
- ## 🟡 Common Issues
52
+ export default function ServerComponent() {
53
+ return <ClientThemeToggle />;
54
+ }
53
55
 
54
- ### Theme colors not working
56
+ // ❌ Incorrect - May cause hook errors
57
+ import { ThemeToggle } from '@tydavidson/design-system/themes';
55
58
 
56
- **Problem**: Components appear in default colors instead of theme colors
59
+ export default function ServerComponent() {
60
+ return <ThemeToggle />; // This could cause issues
61
+ }
62
+ ```
57
63
 
58
- **Solutions**:
59
- 1. Import the CSS: `import '@tydavidson/design-system/themes/theme.css'`
60
- 2. Configure Tailwind with the color tokens (see setup guide)
61
- 3. Check that CSS variables are set on `:root`
64
+ ### 3. Server Component Compatibility Issues
62
65
 
63
- ### Icons not displaying
66
+ **Problem**: Components using React hooks in Server Component context.
64
67
 
65
- **Problem**: Icons show as empty boxes or don't render
68
+ **Solution**:
69
+ - Use Server Component safe components
70
+ - All exported components are now properly protected
71
+ - Components return safe placeholders during SSR
66
72
 
67
- **Solution**:
68
- ```bash
69
- npm install @tabler/icons-react
70
- ```
73
+ **Server Component Safe Components:**
74
+ - `ClientThemeProvider` - Safe theme provider for Server Components
75
+ - `ClientThemeToggle` - Safe theme toggle for Server Components
76
+ - `useThemeServer` - Server-safe theme hook
71
77
 
72
- ### TypeScript errors
78
+ **Client Component Only Components:**
79
+ - `ThemeToggle` - Only use in Client Components
80
+ - `ThemeProvider` - Only use in Client Components
81
+ - `useTheme` - Only use in Client Components
73
82
 
74
- **Problem**: TypeScript can't find types
83
+ ### 4. CSS Variables Not Working
75
84
 
76
- **Solutions**:
77
- 1. The package includes types - no additional @types package needed
78
- 2. Check your `tsconfig.json` includes `node_modules`
79
- 3. Restart your TypeScript server
85
+ **Problem**: Theme colors aren't applying correctly.
80
86
 
81
- ### Bundle size too large
87
+ **Solution**:
88
+ - Ensure CSS variables are properly imported
89
+ - Check that the theme provider is wrapping your app
90
+ - Verify Tailwind CSS is configured correctly
82
91
 
83
- **Problem**: Design system is making your bundle huge
92
+ ```tsx
93
+ // Make sure to import the CSS
94
+ import '@tydavidson/design-system/src/themes/theme.css';
95
+ ```
84
96
 
85
- **Solutions**:
86
- 1. Use tree-shaking - only import what you need
87
- 2. Icon libraries are external (won't be bundled)
88
- 3. Use dynamic imports for large components
97
+ ### 5. Hydration Mismatch Errors
89
98
 
90
- ## 🔧 Quick Fixes
99
+ **Problem**: Server and client rendering don't match.
91
100
 
92
- ### Missing peer dependencies
101
+ **Solution**:
102
+ - Use `suppressHydrationWarning` on the `<html>` element
103
+ - Use client-only components for theme-dependent UI
104
+ - Ensure consistent initial state between server and client
93
105
 
94
- ```bash
95
- npm install react react-dom next-themes @tabler/icons-react
106
+ ```tsx
107
+ // In your root layout
108
+ <html suppressHydrationWarning>
109
+ <body>
110
+ <ThemeProvider>
111
+ {children}
112
+ </ThemeProvider>
113
+ </body>
114
+ </html>
96
115
  ```
97
116
 
98
- ### CSS not loading
117
+ ### 6. Module Resolution Issues
99
118
 
100
- Add to your main CSS file or layout:
101
- ```css
102
- @import '@tydavidson/design-system/themes/theme.css';
103
- ```
119
+ **Problem**: Can't import components or themes.
104
120
 
105
- ### Tailwind not recognizing classes
121
+ **Solution**:
122
+ - Check that you're using the correct import paths
123
+ - Ensure the package is properly installed
124
+ - Verify TypeScript configuration
106
125
 
107
- Update your `tailwind.config.js`:
108
- ```js
109
- content: [
110
- "./src/**/*.{js,ts,jsx,tsx}",
111
- "./node_modules/@tydavidson/design-system/dist/**/*.{js,mjs}",
112
- ],
126
+ ```tsx
127
+ // Correct import paths
128
+ import { Button } from '@tydavidson/design-system';
129
+ import { ClientThemeToggle } from '@tydavidson/design-system/themes';
113
130
  ```
114
131
 
115
- ### Theme provider not working
132
+ ## Server Component Best Practices
133
+
134
+ ### Using Theme System in Server Components
116
135
 
117
- Make sure you're using the correct import:
136
+ **For Server Components:**
118
137
  ```tsx
119
- import { ThemeProvider } from '@tydavidson/design-system/themes';
120
- // NOT ThemeContextProvider (deprecated)
138
+ import { useThemeServer, ClientThemeToggle } from '@tydavidson/design-system/themes';
139
+
140
+ export default function ServerComponent() {
141
+ const { theme, isDark } = useThemeServer();
142
+
143
+ return (
144
+ <div className={isDark ? 'dark' : 'light'}>
145
+ <h1>Current theme: {theme}</h1>
146
+ <ClientThemeToggle />
147
+ </div>
148
+ );
149
+ }
121
150
  ```
122
151
 
123
- ## 📋 Checklist
152
+ **For Client Components:**
153
+ ```tsx
154
+ 'use client';
155
+ import { useTheme, ThemeToggle } from '@tydavidson/design-system/themes';
156
+
157
+ export default function ClientComponent() {
158
+ const { theme, setTheme, isDark } = useTheme();
159
+
160
+ return (
161
+ <div>
162
+ <button onClick={() => setTheme('dark')}>
163
+ Switch to Dark Mode
164
+ </button>
165
+ <ThemeToggle />
166
+ </div>
167
+ );
168
+ }
169
+ ```
170
+
171
+ ### Component Safety Guidelines
172
+
173
+ 1. **Always use `ClientThemeToggle` in Server Components**
174
+ 2. **Use `ClientThemeProvider` for Server Component layouts**
175
+ 3. **Use `useThemeServer` for Server Component theme detection**
176
+ 4. **Mark components that use hooks with `'use client'`**
177
+ 5. **Use proper SSR protection for browser APIs**
124
178
 
125
- Before reporting an issue, verify:
179
+ ## Version Compatibility
126
180
 
127
- - [ ] Using latest version (1.1.4+)
128
- - [ ] All peer dependencies installed
129
- - [ ] CSS imported correctly
130
- - [ ] Tailwind configured with color tokens
131
- - [ ] ThemeProvider wrapping your app
132
- - [ ] `suppressHydrationWarning` on html element
133
- - [ ] No conflicting CSS frameworks
181
+ | Next.js Version | Design System Version | Notes |
182
+ |----------------|----------------------|-------|
183
+ | 13+ (App Router) | 1.1.15+ | Full Server Component support |
184
+ | 12+ (Pages Router) | 1.1.0+ | Basic compatibility |
185
+ | < 12 | Not supported | Use newer Next.js version |
134
186
 
135
- ## 🆘 Still Having Issues?
187
+ ## Getting Help
136
188
 
137
- 1. Check the browser console for specific error messages
138
- 2. Verify your setup matches the [setup guide](./setup-guide.md)
139
- 3. Try the [theme usage examples](./theme-usage.md)
140
- 4. Check if the issue is in the consuming project, not the design system
189
+ If you're still experiencing issues:
141
190
 
142
- ## Version History
191
+ 1. Check the [Setup Guide](./setup-guide.md) for proper installation
192
+ 2. Review the [Theme Usage Guide](./theme-usage.md) for theme system details
193
+ 3. Ensure you're using the latest version of the design system
194
+ 4. Check that all dependencies are compatible
143
195
 
144
- - **1.1.4**: Fixed React context compatibility with Next.js App Router
145
- - **1.1.3**: Added ESM exports for Next.js compatibility
146
- - **1.1.2**: Fixed internal module resolution issues
147
- - **1.1.1**: Fixed import path issues
148
- - **1.1.0**: Added theme system exports
196
+ For additional support, please check the project documentation or create an issue in the repository.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tydavidson/design-system",
3
- "version": "1.1.15",
3
+ "version": "1.1.16",
4
4
  "description": "Float Design System with email components and theme system",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",