@space-man/react-theme-animation 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tony Edgal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,623 @@
+# @spaceman/react-theme-animation
+
+React theme switching with smooth view transition animations, multi-theme support, and synchronized state management.
+
+## Features
+
+- 🎨 **Smooth Animations**: Beautiful view transition animations for theme switching with customizable origins
+- 🌓 **Multi-Theme Support**: Support for light, dark, and system themes
+- 🎯 **Color Themes**: Additional color theme variants (brand colors, etc.)
+- 🪝 **Powerful Hook**: `useThemeAnimation` hook with full control
+- 🧩 **Ready Components**: `ThemeSwitcher` and `ThemeSelector` components
+- 🎛️ **Provider Pattern**: Centralized theme state management with `SpacemanThemeProvider`
+- 🔄 **State Synchronization**: Prevents state drift between multiple components
+- 📱 **Responsive**: Works on all screen sizes including high-resolution displays
+- ⚡ **Performance**: Optimized animations with reduced motion support
+- 🔧 **TypeScript**: Full TypeScript support with comprehensive types
+- 🎛️ **Customizable**: Extensive configuration options
+- 🔙 **Backward Compatible**: Works with existing implementations
+
+## Installation
+
+```bash
+npm install @spaceman/react-theme-animation
+```
+
+## Usage Patterns
+
+This library supports two main usage patterns:
+
+1. **Hook-Only Usage**: Direct hook usage for custom implementations
+2. **Provider Pattern**: Centralized state management (recommended)
+
+---
+
+## 1. Hook-Only Usage For Light and Dark mode animation
+
+Perfect for custom theme toggle buttons and complete control over animated theme logic.
+
+### Basic Theme Toggle
+
+```tsx
+import { useThemeAnimation } from '@spaceman/react-theme-animation';
+
+function ThemeToggle() {
+  const { theme, toggleTheme, ref } = useThemeAnimation();
+
+  return (
+    <button ref={ref} onClick={toggleTheme} className="theme-toggle-btn">
+      {theme === 'light' ? '🌙' : '🌞'} {theme}
+    </button>
+  );
+}
+```
+
+---
+
+## 2. Provider Pattern (Recommended)
+
+The most powerful pattern using `SpacemanThemeProvider` for centralized theme state management. This prevents state drift and provides synchronized animations.
+
+### Basic Provider Setup
+
+```tsx
+import {
+  SpacemanThemeProvider,
+  ThemeSwitcher,
+  ThemeSelector,
+} from '@spaceman/react-theme-animation';
+
+function App() {
+  return (
+    <SpacemanThemeProvider>
+      <div className="app">
+        <header>
+          <ThemeSwitcher />
+        </header>
+
+        <aside>
+          <ThemeSelector colorThemes={['default', 'blue', 'green', 'purple']} />
+        </aside>
+
+        <main>
+          <YourAppContent />
+        </main>
+      </div>
+    </SpacemanThemeProvider>
+  );
+}
+```
+
+### Advanced Provider Configuration
+
+```tsx
+import {
+  SpacemanThemeProvider,
+  ThemeSwitcher,
+  ThemeSelector,
+  ThemeAnimationType,
+} from '@spaceman/react-theme-animation';
+
+function App() {
+  return (
+    <SpacemanThemeProvider
+      defaultTheme="system"
+      defaultColorTheme="blue"
+      themes={['light', 'dark', 'system']}
+      colorThemes={['default', 'blue', 'green', 'purple', 'red']}
+      animationType={ThemeAnimationType.BLUR_CIRCLE}
+      blurAmount={10}
+      duration={1000}
+      onThemeChange={theme => {
+        // Analytics, localStorage, etc.
+        console.log('Global theme changed:', theme);
+      }}
+      onColorThemeChange={colorTheme => {
+        console.log('Global color theme changed:', colorTheme);
+      }}
+    >
+      <AppLayout />
+    </SpacemanThemeProvider>
+  );
+}
+
+function AppLayout() {
+  return (
+    <div className="app-layout">
+      <Header />
+      <Sidebar />
+      <MainContent />
+    </div>
+  );
+}
+
+function Header() {
+  return (
+    <header className="header">
+      <h1>My App</h1>
+      <ThemeSwitcher className="ml-auto" />
+    </header>
+  );
+}
+
+function Sidebar() {
+  return (
+    <aside className="sidebar">
+      <h2>Settings</h2>
+      <ThemeSelector colorThemes={['default', 'blue', 'green', 'purple', 'red']} />
+    </aside>
+  );
+}
+```
+
+### Using the Provider Hook
+
+Access theme state anywhere in your component tree. This hook also enables you to set a reference point for the animation to start from.
+
+```tsx
+import { useSpacemanTheme } from '@spaceman/react-theme-animation';
+
+function ThemeStatus() {
+  const { theme, colorTheme, switchTheme, setColorTheme, switchThemeFromElement } =
+    useSpacemanTheme();
+
+  const handleCustomThemeSwitch = event => {
+    // Animate from the clicked element
+    switchThemeFromElement('dark', event.currentTarget);
+  };
+
+  return (
+    <div className="theme-status">
+      <p>Current theme: {theme}</p>
+      <p>Current color: {colorTheme}</p>
+
+      <button onClick={handleCustomThemeSwitch}>Switch to Dark (with animation)</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Complete Example: Advanced Theme System
+
+Here's a complete example showcasing all features:
+
+```tsx
+import React from 'react';
+import {
+  SpacemanThemeProvider,
+  ThemeSwitcher,
+  ThemeSelector,
+  useSpacemanTheme,
+  ThemeAnimationType,
+} from '@spaceman/react-theme-animation';
+
+// Main App with Provider
+function App() {
+  return (
+    <SpacemanThemeProvider
+      defaultTheme="system"
+      defaultColorTheme="blue"
+      themes={['light', 'dark', 'system']}
+      colorThemes={['default', 'blue', 'green', 'purple', 'red', 'orange']}
+      animationType={ThemeAnimationType.CIRCLE}
+      duration={800}
+      onThemeChange={theme => {
+        // Save to localStorage, analytics, etc.
+        localStorage.setItem('preferred-theme', theme);
+      }}
+      onColorThemeChange={colorTheme => {
+        localStorage.setItem('preferred-color-theme', colorTheme);
+      }}
+    >
+      <AppContent />
+    </SpacemanThemeProvider>
+  );
+}
+
+// App Layout
+function AppContent() {
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      <Header />
+      <div className="container mx-auto px-4 py-8">
+        <div className="grid grid-cols-1 lg:grid-cols-4 gap-8">
+          <Sidebar />
+          <MainContent />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Header with Theme Switcher
+function Header() {
+  return (
+    <header className="border-b bg-card">
+      <div className="container mx-auto px-4 py-4 flex items-center justify-between">
+        <h1 className="text-2xl font-bold">Theme Demo</h1>
+        <div className="flex items-center gap-4">
+          <ThemeSwitcher className="rounded-lg" />
+        </div>
+      </div>
+    </header>
+  );
+}
+
+// Sidebar with Theme Selector
+function Sidebar() {
+  return (
+    <aside className="space-y-6">
+      <div className="bg-card p-6 rounded-lg border">
+        <h2 className="text-lg font-semibold mb-4">Theme Settings</h2>
+        <div className="space-y-4">
+          <div>
+            <label className="text-sm font-medium mb-2 block">Color Theme</label>
+            <ThemeSelector colorThemes={['default', 'blue', 'green', 'purple', 'red', 'orange']} />
+          </div>
+        </div>
+      </div>
+
+      <ThemeInfo />
+    </aside>
+  );
+}
+
+// Component using the theme hook
+function ThemeInfo() {
+  const { theme, colorTheme, switchThemeFromElement } = useSpacemanTheme();
+
+  const quickSwitchTheme = (newTheme, event) => {
+    switchThemeFromElement(newTheme, event.currentTarget);
+  };
+
+  return (
+    <div className="bg-card p-6 rounded-lg border">
+      <h3 className="text-lg font-semibold mb-4">Current State</h3>
+      <div className="space-y-2 text-sm">
+        <p>
+          <strong>Theme:</strong> {theme}
+        </p>
+        <p>
+          <strong>Color:</strong> {colorTheme}
+        </p>
+      </div>
+
+      <div className="mt-4 space-y-2">
+        <p className="text-sm font-medium">Quick Switch:</p>
+        <div className="flex gap-2">
+          {['light', 'dark'].map(t => (
+            <button
+              key={t}
+              onClick={e => quickSwitchTheme(t, e)}
+              className="px-3 py-1 text-xs bg-primary text-primary-foreground rounded hover:bg-primary/90 transition-colors"
+            >
+              {t}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Main content area
+function MainContent() {
+  return (
+    <main className="lg:col-span-3 space-y-6">
+      <div className="bg-card p-6 rounded-lg border">
+        <h2 className="text-xl font-semibold mb-4">Welcome to Theme Demo</h2>
+        <p className="text-muted-foreground">
+          This demo showcases the spaceman-react-theme-animation library with synchronized theme
+          state, smooth animations, and multiple color themes.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        {[1, 2, 3, 4].map(i => (
+          <div key={i} className="bg-card p-6 rounded-lg border">
+            <h3 className="font-semibold mb-2">Card {i}</h3>
+            <p className="text-sm text-muted-foreground">
+              Sample content that adapts to the current theme and color scheme.
+            </p>
+          </div>
+        ))}
+      </div>
+    </main>
+  );
+}
+
+export default App;
+```
+
+---
+
+## API Reference
+
+### SpacemanThemeProvider
+
+Context provider for centralized theme state management.
+
+```tsx
+<SpacemanThemeProvider
+  defaultTheme="system"
+  defaultColorTheme="blue"
+  themes={['light', 'dark', 'system']}
+  colorThemes={['default', 'blue', 'green', 'purple']}
+  animationType={ThemeAnimationType.CIRCLE}
+  duration={800}
+  onThemeChange={theme => console.log('Theme:', theme)}
+  onColorThemeChange={colorTheme => console.log('Color:', colorTheme)}
+>
+  <App />
+</SpacemanThemeProvider>
+```
+
+#### SpacemanThemeProvider Props
+
+| Property             | Type                               | Default                       | Description                           |
+| -------------------- | ---------------------------------- | ----------------------------- | ------------------------------------- |
+| `defaultTheme`       | `Theme`                            | `'system'`                    | Initial theme                         |
+| `defaultColorTheme`  | `ColorTheme`                       | `'default'`                   | Initial color theme                   |
+| `themes`             | `Theme[]`                          | `['light', 'dark', 'system']` | Available themes                      |
+| `colorThemes`        | `ColorTheme[]`                     | `['default']`                 | Available color themes                |
+| `animationType`      | `ThemeAnimationType`               | `ThemeAnimationType.CIRCLE`   | Animation type                        |
+| `duration`           | `number`                           | `500`                         | Animation duration in ms              |
+| `blurAmount`         | `number`                           | `2`                           | Blur amount for blur-circle animation |
+| `onThemeChange`      | `(theme: Theme) => void`           | -                             | Global theme change callback          |
+| `onColorThemeChange` | `(colorTheme: ColorTheme) => void` | -                             | Global color theme change callback    |
+
+### useSpacemanTheme
+
+Hook to access theme state from SpacemanThemeProvider context.
+
+```tsx
+const { theme, colorTheme, switchTheme, setColorTheme, switchThemeFromElement, ref } =
+  useSpacemanTheme();
+```
+
+#### Returns
+
+| Property                 | Type                                                    | Description                                       |
+| ------------------------ | ------------------------------------------------------- | ------------------------------------------------- |
+| `theme`                  | `Theme`                                                 | Current theme                                     |
+| `colorTheme`             | `ColorTheme`                                            | Current color theme                               |
+| `switchTheme`            | `(theme: Theme) => Promise<void>`                       | Switch to specific theme                          |
+| `setColorTheme`          | `(colorTheme: ColorTheme) => void`                      | Set color theme                                   |
+| `switchThemeFromElement` | `(theme: Theme, element: HTMLElement) => Promise<void>` | Switch theme with animation from specific element |
+| `ref`                    | `RefObject<HTMLElement>`                                | Ref for animation origin                          |
+
+### useThemeAnimation
+
+Standalone hook for theme management and animations.
+
+```tsx
+const { theme, colorTheme, switchTheme, setColorTheme, toggleTheme, ref } = useThemeAnimation({
+  themes: ['light', 'dark', 'system'],
+  colorThemes: ['default', 'blue', 'green', 'purple'],
+  animationType: ThemeAnimationType.SCALE,
+  duration: 800,
+  onThemeChange: theme => console.log('Theme changed:', theme),
+  onColorThemeChange: colorTheme => console.log('Color changed:', colorTheme),
+});
+```
+
+#### Options
+
+| Property             | Type                               | Default                       | Description                           |
+| -------------------- | ---------------------------------- | ----------------------------- | ------------------------------------- |
+| `themes`             | `Theme[]`                          | `['light', 'dark', 'system']` | Available themes                      |
+| `colorThemes`        | `ColorTheme[]`                     | `['default']`                 | Available color themes                |
+| `theme`              | `Theme`                            | `'system'`                    | Initial theme                         |
+| `colorTheme`         | `ColorTheme`                       | `'default'`                   | Initial color theme                   |
+| `animationType`      | `ThemeAnimationType`               | `ThemeAnimationType.CIRCLE`   | Animation type                        |
+| `duration`           | `number`                           | `500`                         | Animation duration in ms              |
+| `blurAmount`         | `number`                           | `2`                           | Blur amount for blur-circle animation |
+| `onThemeChange`      | `(theme: Theme) => void`           | -                             | Theme change callback                 |
+| `onColorThemeChange` | `(colorTheme: ColorTheme) => void` | -                             | Color theme change callback           |
+
+#### Return
+
+| Property        | Type                               | Description               |
+| --------------- | ---------------------------------- | ------------------------- |
+| `theme`         | `Theme`                            | Current theme             |
+| `colorTheme`    | `ColorTheme`                       | Current color theme       |
+| `switchTheme`   | `(theme: Theme) => Promise<void>`  | Switch to specific theme  |
+| `setColorTheme` | `(colorTheme: ColorTheme) => void` | Set color theme           |
+| `toggleTheme`   | `() => Promise<void>`              | Toggle between light/dark |
+| `ref`           | `RefObject<HTMLElement>`           | Ref for animation origin  |
+
+### ThemeSwitcher
+
+Pre-built theme switcher component with animated buttons.
+
+```tsx
+<ThemeSwitcher
+  themes={['light', 'dark', 'system']}
+  currentTheme="light"
+  onThemeChange={theme => console.log(theme)}
+  animationType={ThemeAnimationType.CIRCLE}
+  duration={600}
+  className="custom-class"
+/>
+```
+
+#### ThemeSwitcher Props
+
+| Property        | Type                     | Default                       | Description                         |
+| --------------- | ------------------------ | ----------------------------- | ----------------------------------- |
+| `themes`        | `Theme[]`                | `['light', 'dark', 'system']` | Available themes                    |
+| `currentTheme`  | `Theme`                  | -                             | Controlled current theme (optional) |
+| `onThemeChange` | `(theme: Theme) => void` | -                             | Theme change callback (optional)    |
+| `animationType` | `ThemeAnimationType`     | `ThemeAnimationType.CIRCLE`   | Animation type                      |
+| `duration`      | `number`                 | `500`                         | Animation duration in ms            |
+| `className`     | `string`                 | -                             | Additional CSS classes              |
+
+> **Note**: When used with `SpacemanThemeProvider`, `currentTheme` and `onThemeChange` are automatically handled by the context.
+
+### ThemeSelector
+
+Dropdown selector for color themes.
+
+```tsx
+<ThemeSelector
+  colorThemes={['default', 'blue', 'green', 'purple']}
+  currentColorTheme="blue"
+  onColorThemeChange={colorTheme => console.log(colorTheme)}
+  animationType={ThemeAnimationType.BLUR_CIRCLE}
+  duration={400}
+/>
+```
+
+#### ThemeSelector Props
+
+| Property             | Type                               | Default                       | Description                               |
+| -------------------- | ---------------------------------- | ----------------------------- | ----------------------------------------- |
+| `themes`             | `Theme[]`                          | `['light', 'dark', 'system']` | Available themes (for standalone hook)    |
+| `colorThemes`        | `ColorTheme[]`                     | `['default']`                 | Available color themes                    |
+| `currentColorTheme`  | `ColorTheme`                       | -                             | Controlled current color theme (optional) |
+| `onColorThemeChange` | `(colorTheme: ColorTheme) => void` | -                             | Color theme change callback (optional)    |
+| `animationType`      | `ThemeAnimationType`               | `ThemeAnimationType.CIRCLE`   | Animation type                            |
+| `duration`           | `number`                           | `500`                         | Animation duration in ms                  |
+
+> **Note**: When used with `SpacemanThemeProvider`, `currentColorTheme` and `onColorThemeChange` are automatically handled by the context.
+
+### ThemeAnimationType
+
+Animation types for theme transitions.
+
+```tsx
+enum ThemeAnimationType {
+  CIRCLE = 'circle',
+  BLUR_CIRCLE = 'blur-circle',
+}
+```
+
+### Types
+
+```tsx
+type Theme = 'light' | 'dark' | 'system';
+type ColorTheme = string; // e.g., 'default', 'blue', 'green', etc.
+
+interface SpacemanThemeProviderProps {
+  children: React.ReactNode;
+  defaultTheme?: Theme;
+  defaultColorTheme?: ColorTheme;
+  themes?: Theme[];
+  colorThemes?: ColorTheme[];
+  animationType?: ThemeAnimationType;
+  duration?: number;
+  blurAmount?: number;
+  onThemeChange?: (theme: Theme) => void;
+  onColorThemeChange?: (colorTheme: ColorTheme) => void;
+}
+
+interface UseThemeAnimationProps {
+  themes?: Theme[];
+  colorThemes?: ColorTheme[];
+  theme?: Theme;
+  colorTheme?: ColorTheme;
+  animationType?: ThemeAnimationType;
+  duration?: number;
+  blurAmount?: number;
+  onThemeChange?: (theme: Theme) => void;
+  onColorThemeChange?: (colorTheme: ColorTheme) => void;
+}
+
+interface UseThemeAnimationReturn {
+  theme: Theme;
+  colorTheme: ColorTheme;
+  switchTheme: (theme: Theme) => Promise<void>;
+  setColorTheme: (colorTheme: ColorTheme) => void;
+  toggleTheme: () => Promise<void>;
+  ref: RefObject<HTMLElement>;
+}
+
+interface ThemeSwitcherProps {
+  themes?: Theme[];
+  currentTheme?: Theme;
+  onThemeChange?: (theme: Theme) => void;
+  animationType?: ThemeAnimationType;
+  duration?: number;
+  className?: string;
+}
+
+interface ThemeSelectorProps {
+  themes?: Theme[];
+  colorThemes?: ColorTheme[];
+  currentColorTheme?: ColorTheme;
+  onColorThemeChange?: (colorTheme: ColorTheme) => void;
+  animationType?: ThemeAnimationType;
+  duration?: number;
+}
+```
+
+---
+
+## CSS Variables
+
+The library uses CSS custom properties for theming. Define these in your CSS:
+
+```css
+/* Base theme variables */
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+}
+
+/* Dark theme */
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+}
+
+/* Add other theme variants from design system or tweakcn */
+
+.theme-supabase {
+  --background: oklch(0.9911 0 0);
+  --foreground: oklch(0.2046 0 0);
+}
+
+.theme-supabase.dark {
+  --background: oklch(0.1822 0 0);
+  --foreground: oklch(0.9288 0.0126 255.5078);
+}
+
+.theme-mono {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.1448 0 0);
+}
+
+.theme-mono.dark {
+  --background: oklch(0.1448 0 0);
+  --foreground: oklch(1 0 0);
+}
+```
+
+---
+
+## Browser Support
+
+- **View Transitions API**: Chrome 111+, Edge 111+
+- **Fallback**: All modern browsers with CSS transitions
+- **Reduced Motion**: Respects `prefers-reduced-motion` setting
+- **Framework Support**: React 16.8+ (hooks required)
+
+---
+
+## Performance
+
+- Animations use the View Transitions API when available
+- Optimized for 60fps animations
+- Respects `prefers-reduced-motion` setting
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
+
+## License
+
+MIT

package/dist/cjs/components/SpacemanThemeProvider.d.ts

@@ -0,0 +1,51 @@
+import React, { ReactNode } from 'react';
+import { Theme, ColorTheme, ThemeAnimationType } from '../types';
+/**
+ * Context type for the Spaceman Theme Provider
+ */
+interface SpacemanThemeContextType {
+    theme: Theme;
+    colorTheme: ColorTheme;
+    resolvedTheme: 'light' | 'dark';
+    setTheme: (theme: Theme) => void;
+    setColorTheme: (colorTheme: ColorTheme) => void;
+    toggleTheme: () => Promise<void>;
+    switchTheme: (theme: Theme) => Promise<void>;
+    switchThemeFromElement: (theme: Theme, element: HTMLButtonElement) => Promise<void>;
+    ref: React.RefObject<HTMLButtonElement | null>;
+}
+/**
+ * Props for the Spaceman Theme Provider
+ */
+interface SpacemanThemeProviderProps {
+    children: ReactNode;
+    themes?: Theme[];
+    colorThemes?: ColorTheme[];
+    defaultTheme?: Theme;
+    defaultColorTheme?: ColorTheme;
+    animationType?: ThemeAnimationType;
+    duration?: number;
+}
+/**
+ * Spaceman Theme Provider - Provides centralized theme state management
+ *
+ * This provider creates a single source of truth for theme state using the useThemeAnimation hook.
+ * All theme-related components should consume from this context to ensure synchronization.
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options (default: ['light', 'dark', 'system'])
+ * @param colorThemes - Available color theme options (default: ['default'])
+ * @param defaultTheme - Default theme to use (default: 'system')
+ * @param defaultColorTheme - Default color theme to use (default: 'default')
+ * @param animationType - Animation type for theme transitions (default: CIRCLE)
+ * @param duration - Animation duration in milliseconds (default: 750)
+ */
+export declare const SpacemanThemeProvider: React.FC<SpacemanThemeProviderProps>;
+/**
+ * Hook to consume the Spaceman Theme context
+ *
+ * @returns Theme context value with all theme state and methods
+ * @throws Error if used outside of SpacemanThemeProvider
+ */
+export declare const useSpacemanTheme: () => SpacemanThemeContextType;
+export {};