@gv-tech/design-system 2.1.1 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gv-tech/design-system",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Garcia Ventures react design system",
   "repository": "git@github.com:Garcia-Ventures/gvtech-design.git",
   "license": "MIT",
@@ -99,7 +99,6 @@
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
     "lucide-react": "^0.563.0",
-    "next-themes": "^0.4.6",
     "react-day-picker": "^9.13.2",
     "react-hook-form": "^7.71.1",
     "react-icons": "^5.5.0",
@@ -131,6 +130,7 @@
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "lint-staged": "^16.2.7",
+    "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
@@ -145,6 +145,7 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "next-themes": "^0.4.0",
     "prop-types": "^15.8.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",

package/scripts/validate.js

@@ -15,6 +15,7 @@ const steps = [
     cmd: fix ? 'yarn lint:fix' : 'yarn lint',
   },
   { name: 'TypeScript type check', cmd: 'npx tsc --noEmit' },
+  { name: 'Test (vitest)', cmd: 'yarn test:ci' },
   { name: 'Build (vite)', cmd: 'yarn build' },
 ];
 

package/src/App.tsx

@@ -1,4 +1,3 @@
-import { ThemeProvider } from 'next-themes';
 import * as React from 'react';
 import { Footer, Sidebar } from './components/docs';
 import { navItems } from './components/docs/Sidebar';
@@ -21,6 +20,7 @@ import {
   SearchTrigger,
 } from './components/ui/search';
 import { Toaster as SonnerToaster } from './components/ui/sonner';
+import { ThemeProvider } from './components/ui/theme-provider';
 import { ThemeToggle } from './components/ui/theme-toggle';
 import { Toaster } from './components/ui/toaster';
 import { TooltipProvider } from './components/ui/tooltip';
@@ -205,7 +205,7 @@ function App() {
   };
 
   return (
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+    <ThemeProvider>
       <TooltipProvider>
         <div className="flex h-screen bg-background">
           {/* Sidebar */}

package/src/components/ui/alert-dialog.test.tsx

@@ -50,6 +50,7 @@ describe('AlertDialog', () => {
         <AlertDialogContent>
           <AlertDialogHeader>
             <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogCancel>Cancel</AlertDialogCancel>
@@ -72,6 +73,7 @@ describe('AlertDialog', () => {
         <AlertDialogContent>
           <AlertDialogHeader>
             <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+            <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogAction>Continue</AlertDialogAction>

package/src/components/ui/theme-provider.test.tsx

@@ -0,0 +1,47 @@
+import { ThemeProvider } from '@/components/ui/theme-provider';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+describe('ThemeProvider', () => {
+  it('renders children correctly', () => {
+    render(
+      <ThemeProvider>
+        <div data-testid="child">Hello</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+    expect(screen.getByTestId('child')).toHaveTextContent('Hello');
+  });
+
+  it('applies class attribute to html element by default', () => {
+    render(
+      <ThemeProvider>
+        <div>Content</div>
+      </ThemeProvider>,
+    );
+    // next-themes applies the attribute to the html element;
+    // in jsdom the attribute should be set to 'class' by default
+    const html = document.documentElement;
+    // The attribute prop controls how the theme class is toggled.
+    // We verify the provider renders without error, which confirms the defaults are valid.
+    expect(html).toBeDefined();
+  });
+
+  it('allows overriding default props', () => {
+    render(
+      <ThemeProvider defaultTheme="dark" enableSystem={false}>
+        <div data-testid="child">Dark Mode</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+  });
+
+  it('passes additional next-themes props through', () => {
+    render(
+      <ThemeProvider storageKey="my-app-theme" themes={['light', 'dark', 'ocean']}>
+        <div data-testid="child">Custom themes</div>
+      </ThemeProvider>,
+    );
+    expect(screen.getByTestId('child')).toBeInTheDocument();
+  });
+});

package/src/components/ui/theme-provider.tsx

@@ -0,0 +1,12 @@
+import type { ThemeProviderProps as NextThemesProviderProps } from 'next-themes';
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+
+export type ThemeProviderProps = NextThemesProviderProps;
+
+export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
+  return (
+    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem {...props}>
+      {children}
+    </NextThemesProvider>
+  );
+}

package/src/components/ui/theme-toggle.test.tsx

@@ -0,0 +1,49 @@
+import { ThemeToggle } from '@/components/ui/theme-toggle';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ThemeProvider } from 'next-themes';
+import { describe, expect, it, vi } from 'vitest';
+
+// Mock the useTheme hook to control its return values
+vi.mock('@/hooks/use-theme', async () => {
+  const actual = await vi.importActual('@/hooks/use-theme');
+  return {
+    ...actual,
+    useTheme: () => ({
+      theme: 'light',
+      setTheme: vi.fn(),
+      resolvedTheme: 'light',
+      tokens: {},
+    }),
+  };
+});
+
+describe('ThemeToggle', () => {
+  it('renders binary toggle by default', () => {
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    // Use role button which is accessible
+    const button = screen.getByRole('button', { name: /toggle theme/i });
+    expect(button).toBeInTheDocument();
+  });
+
+  it('renders ternary toggle with dropdown', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeProvider>
+        <ThemeToggle variant="ternary" />
+      </ThemeProvider>,
+    );
+    const button = screen.getByRole('button'); // Dropdown trigger
+    expect(button).toBeInTheDocument();
+
+    // Open dropdown
+    await user.click(button);
+    expect(await screen.findByText('Light')).toBeInTheDocument();
+    expect(screen.getByText('Dark')).toBeInTheDocument();
+    expect(screen.getByText('System')).toBeInTheDocument();
+  });
+});

package/src/components/ui/theme-toggle.tsx

@@ -5,9 +5,9 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { useTheme } from '@/hooks/use-theme';
 import { cn } from '@/lib/utils';
 import { Moon, Sun, SunMoon } from 'lucide-react';
-import { useTheme } from 'next-themes';
 
 export interface ThemeToggleProps {
   /**

package/src/hooks/use-theme.test.tsx

@@ -0,0 +1,27 @@
+import { useTheme } from '@/hooks/use-theme';
+import { theme } from '@/theme/tokens';
+import { renderHook } from '@testing-library/react';
+import { ThemeProvider } from 'next-themes';
+import { describe, expect, it } from 'vitest';
+
+describe('useTheme', () => {
+  it('returns default light tokens when no theme is set', () => {
+    const { result } = renderHook(() => useTheme(), {
+      wrapper: ({ children }) => <ThemeProvider>{children}</ThemeProvider>,
+    });
+
+    expect(result.current.tokens).toEqual(theme.light);
+  });
+
+  it('returns dark tokens when theme is dark', () => {
+    const { result } = renderHook(() => useTheme(), {
+      wrapper: ({ children }) => (
+        <ThemeProvider defaultTheme="dark" enableSystem={false}>
+          {children}
+        </ThemeProvider>
+      ),
+    });
+
+    expect(result.current.tokens).toEqual(theme.dark);
+  });
+});

package/src/hooks/use-theme.ts

@@ -0,0 +1,15 @@
+import { theme } from '@/theme/tokens';
+import { useTheme as useNextTheme } from 'next-themes';
+
+export function useTheme() {
+  const context = useNextTheme();
+  const { resolvedTheme } = context;
+
+  // Default to light theme tokens if resolvedTheme is undefined or invalid
+  const activeTokens = resolvedTheme === 'dark' ? theme.dark : theme.light;
+
+  return {
+    ...context,
+    tokens: activeTokens,
+  };
+}

package/src/index.ts

@@ -45,6 +45,7 @@ export * from './components/ui/switch';
 export * from './components/ui/table';
 export * from './components/ui/tabs';
 export * from './components/ui/textarea';
+export * from './components/ui/theme-provider';
 export * from './components/ui/theme-toggle';
 export * from './components/ui/toast';
 export { Toaster as ToasterToast } from './components/ui/toaster';
@@ -53,4 +54,5 @@ export * from './components/ui/toggle-group';
 export * from './components/ui/tooltip';
 
 // Hooks
+export * from './hooks/use-theme';
 export * from './hooks/use-toast';

package/src/pages/GettingStarted.tsx

@@ -133,10 +133,34 @@ export function InstallationPage() {
         <CodeBlock
           code={`{
   "react": "^18 || ^19",
-  "react-dom": "^18 || ^19"
+  "react-dom": "^18 || ^19",
+  "next-themes": "^0.4.0"
 }`}
           language="json"
         />
+        <p className="text-sm text-muted-foreground">
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">next-themes</code> is required for the design
+          system's <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>,{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeToggle</code>, and{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">useTheme</code> to work. Install it alongside the
+          design system:
+        </p>
+        <Tabs defaultValue="npm" className="w-full">
+          <TabsList>
+            <TabsTrigger value="npm">npm</TabsTrigger>
+            <TabsTrigger value="yarn">yarn</TabsTrigger>
+            <TabsTrigger value="pnpm">pnpm</TabsTrigger>
+          </TabsList>
+          <TabsContent value="npm" className="mt-4">
+            <CodeBlock code="npm install next-themes" language="bash" />
+          </TabsContent>
+          <TabsContent value="yarn" className="mt-4">
+            <CodeBlock code="yarn add next-themes" language="bash" />
+          </TabsContent>
+          <TabsContent value="pnpm" className="mt-4">
+            <CodeBlock code="pnpm add next-themes" language="bash" />
+          </TabsContent>
+        </Tabs>
       </section>
 
       <section className="space-y-4">
@@ -253,15 +277,22 @@ module.exports = {
 
       <section className="space-y-4">
         <h2 className="text-2xl font-semibold tracking-tight">Start Using Components</h2>
-        <p className="text-muted-foreground">Now you can import and use components from the design system:</p>
+        <p className="text-muted-foreground">
+          Wrap your app with <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> and start
+          importing components:
+        </p>
         <CodeBlock
-          code={`import { Button } from '@gv-tech/design-system';
+          code={`import { ThemeProvider, ThemeToggle, Button } from '@gv-tech/design-system';
+import '@gv-tech/design-system/style.css';
 
 export default function App() {
   return (
-    <Button variant="default">
-      Click me
-    </Button>
+    <ThemeProvider>
+      <div>
+        <ThemeToggle variant="ternary" />
+        <Button variant="default">Click me</Button>
+      </div>
+    </ThemeProvider>
   );
 }`}
         />

package/src/pages/components/ThemeToggleDocs.tsx

@@ -30,23 +30,178 @@ export function ThemeToggleDocs() {
       </ComponentShowcase>
 
       <ComponentShowcase
-        title="Custom State Integration"
-        description="You can control the theme externally by passing customTheme and onThemeChange props."
+        title="Controlled Mode"
+        description="You can control the theme externally by passing customTheme and onThemeChange props. This is useful for testing or when using a different theme provider."
         code={`const [theme, setTheme] = useState('light');
 
 <ThemeToggle
   customTheme={theme}
-  onThemeChange={(newTheme) => setTheme(newTheme)}
+  onThemeChange={setTheme}
 />
 
 <p>Current Theme: {theme}</p>`}
       >
         <div className="flex flex-col items-center gap-4">
-          <ThemeToggle customTheme={customTheme} onThemeChange={(newTheme) => setCustomTheme(newTheme)} />
+          <ThemeToggle customTheme={customTheme} onThemeChange={setCustomTheme} />
           <p className="text-sm font-medium">Current Selection: {customTheme}</p>
         </div>
       </ComponentShowcase>
 
+      {/* ThemeProvider Section */}
+      <div className="mt-12 space-y-6">
+        <div>
+          <h3 className="text-xl font-semibold">ThemeProvider</h3>
+          <p className="mt-2 text-muted-foreground">
+            The design system exports a pre-configured{' '}
+            <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> that wraps{' '}
+            <code className="text-sm bg-muted px-1.5 py-0.5 rounded">next-themes</code> with sensible defaults. Wrap
+            your application with it to enable theme switching for all design system components.
+          </p>
+        </div>
+
+        <div className="rounded-md border bg-muted p-4">
+          <pre className="text-xs">
+            <code>
+              {`import { ThemeProvider, ThemeToggle } from '@gv-tech/design-system';
+import '@gv-tech/design-system/style.css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeToggle variant="ternary" />
+      {/* Your app content */}
+    </ThemeProvider>
+  );
+}`}
+            </code>
+          </pre>
+        </div>
+
+        <div className="space-y-4">
+          <h4 className="font-medium text-foreground">Defaults</h4>
+          <p className="text-sm text-muted-foreground">
+            Out of the box, <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code> applies these
+            defaults. You can override any of them by passing the corresponding prop.
+          </p>
+          <div className="rounded-md border">
+            <table className="w-full text-sm">
+              <thead>
+                <tr className="border-b bg-muted/50">
+                  <th className="p-3 text-left font-medium">Prop</th>
+                  <th className="p-3 text-left font-medium">Default</th>
+                  <th className="p-3 text-left font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr className="border-b">
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">attribute</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">"class"</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Applies the theme as a CSS class on the HTML element</td>
+                </tr>
+                <tr className="border-b">
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">defaultTheme</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">"system"</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Respects the user's operating system preference</td>
+                </tr>
+                <tr>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">enableSystem</code>
+                  </td>
+                  <td className="p-3">
+                    <code className="text-xs bg-muted px-1 py-0.5 rounded">true</code>
+                  </td>
+                  <td className="p-3 text-muted-foreground">Enables automatic detection of the OS color scheme</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div className="rounded-md border bg-muted p-4">
+          <p className="text-xs font-medium text-muted-foreground mb-2">Overriding defaults:</p>
+          <pre className="text-xs">
+            <code>
+              {`<ThemeProvider
+  defaultTheme="dark"
+  storageKey="my-app-theme"
+  themes={['light', 'dark', 'ocean']}
+>
+  <App />
+</ThemeProvider>`}
+            </code>
+          </pre>
+        </div>
+      </div>
+
+      {/* useTheme Section */}
+      <div className="mt-12 space-y-4">
+        <h3 className="text-xl font-semibold">useTheme Hook</h3>
+        <p className="text-sm text-muted-foreground">
+          The <code className="text-sm bg-muted px-1.5 py-0.5 rounded">useTheme</code> hook provides access to the
+          current theme, theme controls, and the active design tokens. It must be used within a{' '}
+          <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>.
+        </p>
+        <div className="rounded-md border bg-muted p-4">
+          <pre className="text-xs">
+            <code>
+              {`import { useTheme } from '@gv-tech/design-system';
+
+export function MyComponent() {
+  const { theme, setTheme, resolvedTheme, tokens } = useTheme();
+
+  return (
+    <div style={{ backgroundColor: tokens.background }}>
+      <p>Current theme: {theme}</p>
+      <p>Resolved theme: {resolvedTheme}</p>
+      <button onClick={() => setTheme('dark')}>Dark Mode</button>
+    </div>
+  );
+}`}
+            </code>
+          </pre>
+        </div>
+
+        <PropsTable
+          props={[
+            {
+              name: 'theme',
+              type: 'string',
+              required: false,
+              description: 'The current theme name ("light", "dark", or "system").',
+            },
+            {
+              name: 'setTheme',
+              type: '(theme: string) => void',
+              required: false,
+              description: 'Function to programmatically change the theme.',
+            },
+            {
+              name: 'resolvedTheme',
+              type: 'string',
+              required: false,
+              description:
+                'The resolved theme ("light" or "dark"). Useful when theme is "system" and you need the actual value.',
+            },
+            {
+              name: 'tokens',
+              type: 'ThemeTokens',
+              required: false,
+              description:
+                'The active color tokens for the current resolved theme (light or dark). Contains background, foreground, primary, and other design token values.',
+            },
+          ]}
+        />
+      </div>
+
+      {/* ThemeToggle Props Section */}
       <div className="space-y-4">
         <h3 className="text-xl font-semibold">ThemeToggle Props</h3>
         <PropsTable
@@ -81,41 +236,60 @@ export function ThemeToggleDocs() {
         />
       </div>
 
+      {/* Integration Section */}
       <div className="mt-12 space-y-6">
         <div>
           <h3 className="text-xl font-semibold">Integration</h3>
           <p className="mt-2 text-muted-foreground">
-            The `ThemeToggle` component is built to be flexible and works seamlessly with `next-themes` by default, but
-            it can also be used in a fully controlled manner with any theme provider or custom state.
+            The <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeToggle</code> component works seamlessly
+            with the design system's <code className="text-sm bg-muted px-1.5 py-0.5 rounded">ThemeProvider</code>. It
+            can also be used in a fully controlled manner with any theme provider or custom state.
           </p>
         </div>
 
         <div className="grid gap-6 md:grid-cols-2">
           <div className="rounded-lg border bg-muted/50 p-6">
-            <h4 className="font-medium text-foreground">With next-themes</h4>
+            <h4 className="font-medium text-foreground">With ThemeProvider (Recommended)</h4>
             <p className="mt-1 text-sm text-muted-foreground">
-              Simply drop the component anywhere. It will automatically detect the `ThemeProvider` and handle switching.
+              Wrap your app with the design system's{' '}
+              <code className="text-xs bg-muted px-1 py-0.5 rounded">ThemeProvider</code> and drop in the toggle.
+              Everything connects automatically.
             </p>
             <pre className="mt-4 overflow-x-auto rounded-md bg-background p-4 text-xs">
-              <code>{`<ThemeProvider attribute="class">
+              <code>{`import { ThemeProvider, ThemeToggle } from '@gv-tech/design-system';
+
+<ThemeProvider>
   <ThemeToggle />
 </ThemeProvider>`}</code>
             </pre>
           </div>
 
           <div className="rounded-lg border bg-muted/50 p-6">
-            <h4 className="font-medium text-foreground">Custom Provider</h4>
+            <h4 className="font-medium text-foreground">Controlled / Custom State</h4>
             <p className="mt-1 text-sm text-muted-foreground">
               Pass your own theme state and change handler to integrate with custom logic or external storage.
             </p>
             <pre className="mt-4 overflow-x-auto rounded-md bg-background p-4 text-xs">
-              <code>{`<ThemeToggle 
-  customTheme={myTheme} 
-  onThemeChange={(t) => updateMyTheme(t)} 
+              <code>{`const [theme, setTheme] = useState("light")
+
+<ThemeToggle 
+  customTheme={theme} 
+  onThemeChange={setTheme} 
 />`}</code>
             </pre>
           </div>
         </div>
+
+        <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-6">
+          <h4 className="font-medium text-amber-600 dark:text-amber-400">⚠️ Important: Shared Context</h4>
+          <p className="mt-1 text-sm text-muted-foreground">
+            The design system marks <code className="text-xs bg-muted px-1 py-0.5 rounded">next-themes</code> as a{' '}
+            <strong>peer dependency</strong>, meaning it uses the same instance as your project. This ensures that{' '}
+            <code className="text-xs bg-muted px-1 py-0.5 rounded">useTheme</code>,{' '}
+            <code className="text-xs bg-muted px-1 py-0.5 rounded">ThemeToggle</code>, and your own components all share
+            the same theme context — no duplicate providers needed.
+          </p>
+        </div>
       </div>
     </ComponentSection>
   );

package/vite.config.ts

@@ -27,13 +27,14 @@ export default defineConfig({
         }
       : undefined,
     rollupOptions: {
-      external: isLibrary ? ['react', 'react-dom', 'prop-types'] : [],
+      external: isLibrary ? ['react', 'react-dom', 'prop-types', 'next-themes'] : [],
       output: {
         globals: isLibrary
           ? {
               react: 'React',
               'react-dom': 'ReactDOM',
               'prop-types': 'PropTypes',
+              'next-themes': 'NextThemes',
             }
           : {},
         manualChunks(id) {