@opencosmos/ui 1.3.1

package/src/dates.ts

@@ -0,0 +1,2 @@
+export * from './components/data-display/Calendar';
+export * from './components/layout/DatePicker';

package/src/dnd.ts

@@ -0,0 +1 @@
+export * from './components/forms/DragDrop';

package/src/forms.ts

@@ -0,0 +1 @@
+export * from './components/forms/Form';

package/src/globals.css

@@ -0,0 +1,187 @@
+/**
+ * Default CSS Variables — Studio Theme (Light/Dark)
+ *
+ * These values serve as fallback defaults and are overridden at runtime by ThemeProvider
+ * when a different theme is selected. ThemeProvider injects CSS variables dynamically
+ * based on the active theme (Studio, Terra, Volt, Speedboat) and color mode.
+ *
+ * See: packages/ui/src/providers/ThemeProvider.tsx
+ * See: packages/tokens/src/studio.ts, terra.ts, volt.ts, speedboat.ts
+ */
+
+@layer base {
+  :root {
+    /* ── Color Palette (Studio Light) ────────────────────────────── */
+    --color-background: #ffffff;
+    --color-background-secondary: #fafafa;
+    --color-background-tertiary: #f5f5f5;
+    --color-foreground: #0a0a0a;
+    --color-text-primary: var(--color-foreground);
+    --color-text-secondary: #525252;
+    --color-text-muted: #a3a3a3;
+
+    --color-primary: #0a0a0a;
+    --color-primary-foreground: #ffffff;
+
+    --color-secondary: #f5f5f5;
+    --color-secondary-foreground: #0a0a0a;
+
+    --color-accent: #0070f3;
+    --color-accent-foreground: #ffffff;
+
+    --color-destructive: #ef4444;
+    --color-destructive-foreground: #ffffff;
+
+    --color-muted: #f5f5f5;
+    --color-muted-foreground: #737373;
+
+    --color-popover: #ffffff;
+    --color-popover-foreground: #0a0a0a;
+
+    --color-card: #ffffff;
+    --color-card-foreground: #0a0a0a;
+
+    --color-success: #00a86b;
+    --color-success-foreground: #ffffff;
+
+    --color-warning: #f59e0b;
+    --color-warning-foreground: #ffffff;
+
+    --color-error: #ef4444;
+    --color-error-foreground: #ffffff;
+
+    --color-info: #0070f3;
+    --color-info-foreground: #ffffff;
+
+    --color-surface: #fafafa;
+    --color-border: #d4d4d4;
+    --color-input: #d4d4d4;
+    --color-ring: #0a0a0a;
+
+    --color-glass: rgba(255, 255, 255, 0.7);
+    --color-glass-border: rgba(0, 0, 0, 0.1);
+
+    --radius: 0.5rem;
+
+    /* ── Interaction Tokens ──────────────────────────────────────── */
+    --color-interaction-overlay: #000000;
+    --opacity-interaction-hover: 0.06;
+    --scale-interaction-active: 0.98;
+    --color-interaction-focus-ring: var(--color-ring);
+    --width-interaction-focus-ring: 2px;
+    --width-interaction-focus-offset: 2px;
+    --opacity-interaction-disabled: 0.5;
+
+    /* ── Effects — Blur (raw values for Tailwind utilities) ─────── */
+    --blur-sm: 4px;
+    --blur-md: 8px;
+    --blur-lg: 16px;
+    --blur-xl: 24px;
+
+    /* ── Effects — Shadow ─────────────────────────────────────────── */
+    --effect-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+    --effect-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    --effect-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+    --effect-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
+    --effect-shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+
+    /* ── Motion — Easing ──────────────────────────────────────────── */
+    --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+    --ease-in: cubic-bezier(0.4, 0, 1, 1);
+    --ease-out: cubic-bezier(0, 0, 0.2, 1);
+    --ease-spring: cubic-bezier(0.16, 1, 0.3, 1);
+
+    /* ── Motion — Duration (overridden by ThemeProvider) ──────────── */
+    --duration-default: 200ms;
+    --duration-fast: 100ms;
+    --duration-slow: 300ms;
+
+    /* ── Primary Color Scale (populated by Customizer) ────────────── */
+    --color-primary-50: initial;
+    --color-primary-100: initial;
+    --color-primary-200: initial;
+    --color-primary-300: initial;
+    --color-primary-400: initial;
+    --color-primary-500: initial;
+    --color-primary-600: initial;
+    --color-primary-700: initial;
+    --color-primary-800: initial;
+    --color-primary-900: initial;
+  }
+
+  .dark {
+    /* ── Color Palette (Studio Dark) ─────────────────────────────── */
+    --color-background: #000000;
+    --color-background-secondary: #171717;
+    --color-background-tertiary: #262626;
+    --color-foreground: #fafafa;
+    --color-text-primary: var(--color-foreground);
+    --color-text-secondary: #a3a3a3;
+    --color-text-muted: #858585;
+
+    --color-primary: #ffffff;
+    --color-primary-foreground: #0a0a0a;
+
+    --color-secondary: #262626;
+    --color-secondary-foreground: #fafafa;
+
+    --color-accent: #0090ff;
+    --color-accent-foreground: #ffffff;
+
+    --color-destructive: #ef4444;
+    --color-destructive-foreground: #ffffff;
+
+    --color-muted: #262626;
+    --color-muted-foreground: #a3a3a3;
+
+    --color-popover: #0a0a0a;
+    --color-popover-foreground: #fafafa;
+
+    --color-card: #0a0a0a;
+    --color-card-foreground: #fafafa;
+
+    --color-success: #10b981;
+    --color-success-foreground: #ffffff;
+
+    --color-warning: #f59e0b;
+    --color-warning-foreground: #ffffff;
+
+    --color-error: #ef4444;
+    --color-error-foreground: #ffffff;
+
+    --color-info: #0090ff;
+    --color-info-foreground: #ffffff;
+
+    --color-surface: #171717;
+    --color-border: #404040;
+    --color-input: #404040;
+    --color-ring: #d4d4d4;
+
+    --color-glass: rgba(0, 0, 0, 0.7);
+    --color-glass-border: rgba(255, 255, 255, 0.1);
+
+    /* ── Interaction Tokens — Dark Mode ──────────────────────────── */
+    --color-interaction-overlay: #ffffff;
+    --color-interaction-focus-ring: var(--color-ring);
+
+    /* ── Effects — Shadow (dark mode, heavier) ───────────────────── */
+    --effect-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.3);
+    --effect-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.5);
+    --effect-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.6);
+    --effect-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.7);
+    --effect-shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.8);
+  }
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+
+  * {
+    border-color: var(--color-border);
+  }
+}
+
+@import './components/layout/glass-surface.css';

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export { useTheme } from './useTheme';
+export { useMotionPreference } from './useMotionPreference';
+export { useForm } from './useForm';
+export type { ThemeHook } from './useTheme';
+export type { MotionPreference } from './useMotionPreference';
+export type { UseFormOptions, UseFormReturn } from './useForm';

package/src/hooks/useForm.ts

@@ -0,0 +1,247 @@
+'use client';
+
+import { useState, useCallback } from 'react';
+import type { FieldValidation, FormErrors } from '../lib/validation';
+import { validateField, validateForm } from '../lib/validation';
+
+export interface UseFormOptions<T> {
+  /**
+   * Initial form values
+   */
+  initialValues: T;
+
+  /**
+   * Validation rules for each field
+   */
+  validations?: Partial<Record<keyof T, FieldValidation>>;
+
+  /**
+   * Callback fired when form is submitted and valid
+   */
+  onSubmit?: (values: T) => void | Promise<void>;
+
+  /**
+   * When to validate fields
+   * @default 'onBlur'
+   */
+  validateOn?: 'onChange' | 'onBlur' | 'onSubmit';
+}
+
+export interface UseFormReturn<T> {
+  /**
+   * Current form values
+   */
+  values: T;
+
+  /**
+   * Current form errors
+   */
+  errors: FormErrors;
+
+  /**
+   * Whether the form is currently submitting
+   */
+  isSubmitting: boolean;
+
+  /**
+   * Whether the form has been touched/modified
+   */
+  isDirty: boolean;
+
+  /**
+   * Set value for a specific field
+   */
+  setValue: (name: keyof T, value: any) => void;
+
+  /**
+   * Set error for a specific field
+   */
+  setError: (name: keyof T, error: string | undefined) => void;
+
+  /**
+   * Handle input change event
+   */
+  handleChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+
+  /**
+   * Handle input blur event
+   */
+  handleBlur: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+
+  /**
+   * Handle form submit
+   */
+  handleSubmit: (e?: React.FormEvent<HTMLFormElement>) => Promise<void>;
+
+  /**
+   * Reset form to initial values
+   */
+  reset: () => void;
+
+  /**
+   * Manually validate all fields
+   */
+  validate: () => boolean;
+
+  /**
+   * Get props for a field (value, onChange, onBlur, error)
+   */
+  getFieldProps: (name: keyof T) => {
+    name: string;
+    value: any;
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    onBlur: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    error: boolean;
+  };
+}
+
+/**
+ * useForm Hook
+ *
+ * A lightweight form state management hook with built-in validation.
+ *
+ * Features:
+ * - Field-level validation
+ * - Configurable validation timing (onChange, onBlur, onSubmit)
+ * - Dirty state tracking
+ * - Submit handling with loading state
+ * - Helper functions for common patterns
+ *
+ * Example:
+ * ```tsx
+ * const form = useForm({
+ *   initialValues: { email: '', password: '' },
+ *   validations: {
+ *     email: { required: true, pattern: patterns.email },
+ *     password: { required: true, minLength: { value: 8, message: 'Min 8 chars' } }
+ *   },
+ *   onSubmit: async (values) => {
+ *     await login(values);
+ *   }
+ * });
+ *
+ * return (
+ *   <form onSubmit={form.handleSubmit}>
+ *     <FormField label="Email" error={form.errors.email}>
+ *       <TextField {...form.getFieldProps('email')} />
+ *     </FormField>
+ *     <Button type="submit" loading={form.isSubmitting}>Submit</Button>
+ *   </form>
+ * );
+ * ```
+ */
+export function useForm<T extends Record<string, any>>({
+  initialValues,
+  validations = {},
+  onSubmit,
+  validateOn = 'onBlur',
+}: UseFormOptions<T>): UseFormReturn<T> {
+  const [values, setValues] = useState<T>(initialValues);
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isDirty, setIsDirty] = useState(false);
+
+  const setValue = useCallback((name: keyof T, value: any) => {
+    setValues((prev) => ({ ...prev, [name]: value }));
+    setIsDirty(true);
+  }, []);
+
+  const setError = useCallback((name: keyof T, error: string | undefined) => {
+    setErrors((prev) => ({ ...prev, [name as string]: error }));
+  }, []);
+
+  const validateFieldByName = useCallback(
+    (name: keyof T) => {
+      const fieldRules = validations[name];
+      if (!fieldRules) return;
+
+      const error = validateField(values[name], fieldRules);
+      setError(name, error);
+      return !error;
+    },
+    [values, validations, setError]
+  );
+
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => {
+      const { name, value, type } = e.target;
+      const fieldValue = type === 'checkbox' ? (e.target as HTMLInputElement).checked : value;
+
+      setValue(name as keyof T, fieldValue);
+
+      if (validateOn === 'onChange') {
+        validateFieldByName(name as keyof T);
+      }
+    },
+    [setValue, validateOn, validateFieldByName]
+  );
+
+  const handleBlur = useCallback(
+    (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => {
+      const { name } = e.target;
+
+      if (validateOn === 'onBlur') {
+        validateFieldByName(name as keyof T);
+      }
+    },
+    [validateOn, validateFieldByName]
+  );
+
+  const validate = useCallback(() => {
+    const formErrors = validateForm(values, validations as any);
+    setErrors(formErrors);
+    return Object.keys(formErrors).length === 0;
+  }, [values, validations]);
+
+  const handleSubmit = useCallback(
+    async (e?: React.FormEvent<HTMLFormElement>) => {
+      e?.preventDefault();
+
+      const isValid = validate();
+      if (!isValid) return;
+
+      if (onSubmit) {
+        setIsSubmitting(true);
+        try {
+          await onSubmit(values);
+        } finally {
+          setIsSubmitting(false);
+        }
+      }
+    },
+    [validate, onSubmit, values]
+  );
+
+  const reset = useCallback(() => {
+    setValues(initialValues);
+    setErrors({});
+    setIsDirty(false);
+    setIsSubmitting(false);
+  }, [initialValues]);
+
+  const getFieldProps = useCallback(
+    (name: keyof T) => ({
+      name: name as string,
+      value: values[name] ?? '',
+      onChange: handleChange,
+      onBlur: handleBlur,
+      error: !!errors[name as string],
+    }),
+    [values, errors, handleChange, handleBlur]
+  );
+
+  return {
+    values,
+    errors,
+    isSubmitting,
+    isDirty,
+    setValue,
+    setError,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    reset,
+    validate,
+    getFieldProps,
+  };
+}

package/src/hooks/useMotionPreference.test.ts

@@ -0,0 +1,102 @@
+import { renderHook, act } from '@testing-library/react'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useMotionPreference } from './useMotionPreference'
+import { useCustomizer } from '../lib/store/customizer'
+
+// Helper to mock matchMedia with a specific matches value
+function mockMatchMedia(matches: boolean) {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  })
+}
+
+describe('useMotionPreference', () => {
+  beforeEach(() => {
+    // Reset the Zustand store to defaults before each test
+    useCustomizer.setState({
+      motion: 5,
+      prefersReducedMotion: false,
+    })
+    // Default: system does not prefer reduced motion
+    mockMatchMedia(false)
+  })
+
+  it('returns scale, shouldAnimate, and prefersReducedMotion', () => {
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current).toHaveProperty('scale')
+    expect(result.current).toHaveProperty('shouldAnimate')
+    expect(result.current).toHaveProperty('prefersReducedMotion')
+  })
+
+  it('returns default values from the store', () => {
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.scale).toBe(5)
+    expect(result.current.shouldAnimate).toBe(true)
+    expect(result.current.prefersReducedMotion).toBe(false)
+  })
+
+  it('shouldAnimate is false when scale is 0', () => {
+    useCustomizer.setState({ motion: 0 })
+
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.scale).toBe(0)
+    expect(result.current.shouldAnimate).toBe(false)
+  })
+
+  it('shouldAnimate is false when system prefers reduced motion', () => {
+    // Mock the system preference to prefer reduced motion
+    mockMatchMedia(true)
+
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.prefersReducedMotion).toBe(true)
+    expect(result.current.shouldAnimate).toBe(false)
+  })
+
+  it('shouldAnimate is false when both scale is 0 and system prefers reduced motion', () => {
+    useCustomizer.setState({ motion: 0 })
+    mockMatchMedia(true)
+
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.scale).toBe(0)
+    expect(result.current.prefersReducedMotion).toBe(true)
+    expect(result.current.shouldAnimate).toBe(false)
+  })
+
+  it('shouldAnimate is true when scale is above 0 and system does not prefer reduced motion', () => {
+    useCustomizer.setState({ motion: 10 })
+
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.scale).toBe(10)
+    expect(result.current.shouldAnimate).toBe(true)
+  })
+
+  it('reflects changes when motion is updated via the store', () => {
+    const { result } = renderHook(() => useMotionPreference())
+
+    expect(result.current.scale).toBe(5)
+    expect(result.current.shouldAnimate).toBe(true)
+
+    act(() => {
+      useCustomizer.setState({ motion: 0 })
+    })
+
+    expect(result.current.scale).toBe(0)
+    expect(result.current.shouldAnimate).toBe(false)
+  })
+})

package/src/hooks/useMotionPreference.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useCustomizer } from '../lib/store/customizer';
+
+export interface MotionPreference {
+  /**
+   * Motion intensity level (0-10)
+   * 0 = no motion, 10 = full motion
+   */
+  scale: number;
+
+  /**
+   * Whether animations should be displayed
+   * False when scale is 0 or prefersReducedMotion is true
+   */
+  shouldAnimate: boolean;
+
+  /**
+   * System preference for reduced motion
+   */
+  prefersReducedMotion: boolean;
+}
+
+/**
+ * Hook to access motion preferences
+ *
+ * Automatically syncs with system `prefers-reduced-motion` media query
+ * and respects user's manual motion intensity setting.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedComponent() {
+ *   const { scale, shouldAnimate } = useMotionPreference();
+ *
+ *   if (!shouldAnimate) {
+ *     return <div>Content without animation</div>;
+ *   }
+ *
+ *   return (
+ *     <motion.div
+ *       animate={{ opacity: 1 }}
+ *       transition={{ duration: 0.3 * (scale / 10) }}
+ *     >
+ *       Content with scaled animation
+ *     </motion.div>
+ *   );
+ * }
+ * ```
+ */
+export function useMotionPreference(): MotionPreference {
+  const { motion, prefersReducedMotion, setPrefersReducedMotion } = useCustomizer();
+
+  // Listen for system prefers-reduced-motion changes
+  useEffect(() => {
+    // Only run in browser environment
+    if (typeof window === 'undefined') return;
+
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    // Set initial value
+    setPrefersReducedMotion(mediaQuery.matches);
+
+    // Listen for changes
+    const handleChange = (e: MediaQueryListEvent) => {
+      setPrefersReducedMotion(e.matches);
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [setPrefersReducedMotion]);
+
+  return {
+    scale: motion,
+    shouldAnimate: motion > 0 && !prefersReducedMotion,
+    prefersReducedMotion,
+  };
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,58 @@
+'use client';
+
+import { useThemeStore } from '../lib/store/theme';
+import type { ThemeName, ColorMode } from '@thesage/tokens';
+
+export interface ThemeHook {
+  /**
+   * Current theme name
+   */
+  theme: ThemeName;
+
+  /**
+   * Current color mode (light/dark)
+   */
+  mode: ColorMode;
+
+  /**
+   * Set the theme
+   */
+  setTheme: (theme: ThemeName) => void;
+
+  /**
+   * Set the color mode
+   */
+  setMode: (mode: ColorMode) => void;
+
+  /**
+   * Toggle between light and dark mode
+   */
+  toggleMode: () => void;
+
+  /**
+   * Combined theme configuration
+   */
+  themeConfig: { name: ThemeName; mode: ColorMode };
+}
+
+/**
+ * Hook to access and control theme settings
+ *
+ * @example
+ * ```tsx
+ * function ThemeSelector() {
+ *   const { theme, mode, setTheme, toggleMode } = useTheme();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {theme} - {mode}</p>
+ *       <button onClick={() => setTheme('sage')}>Sage Theme</button>
+ *       <button onClick={toggleMode}>Toggle Mode</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useTheme(): ThemeHook {
+  return useThemeStore();
+}

package/src/hooks.ts

@@ -0,0 +1,9 @@
+/**
+ * Hooks subpath export
+ * Allows: import { ... } from '@thesage/ui/hooks'
+ */
+
+// Re-export all hooks
+export * from './hooks/useTheme';
+export * from './hooks/useMotionPreference';
+export * from './hooks/useForm';