Skip to content

Latest commit

 

History

History
154 lines (124 loc) · 3.77 KB

SETTINGS_DOCUMENTATION.md

File metadata and controls

154 lines (124 loc) · 3.77 KB

Settings & Theme Customization

Overview

Centralized user settings system with custom theme creation capabilities.

Centralized Types

Location

hub/src/types/settings.ts - All settings types are centralized here

Available Settings Types

- UserSettings - Main settings container
- ThemeSettings - Theme configuration
- NotificationSettings - Notification preferences
- PrivacySettings - Privacy controls
- PlaybackSettings - Audio playback preferences
- CustomThemeDefinition - Custom theme structure

Features

1. Theme Selection

  • 10 Preset Themes: ember-noir, coastline-dawn, midnight-neon, royal-violet, sunlit-canvas, forest-echo, aurora-frost, crimson-stage, desert-mirage, retro-wave
  • Custom Theme Creation: Users can create personalized themes

2. Custom Theme Editor

Navigate to /settings and click "Create Custom" to:

  • Set theme name and description
  • Choose light or dark mode
  • Customize 7 palette colors:
    • Background
    • Surface
    • Foreground
    • Muted
    • Border
    • Primary
    • Secondary
  • Live color picker with hex input
  • Save to user profile
  • Delete custom theme

3. Persistent Settings

All settings are:

  • Saved to profiles.settings JSON column in database
  • Automatically loaded on user login
  • Applied across all components

API Endpoints

Update Settings

PUT /api/user/profile/settings
Body: { settings: UserSettings }

Profile with Settings

GET /api/user/profile/me
Response includes: user.profile.settings

Database Schema

Migration Required

ALTER TABLE profiles ADD COLUMN settings JSON DEFAULT NULL;

File: hubx/add_settings_column.sql

Frontend Implementation

Using Settings in Components

import { useAuth } from '@/contexts/AuthContext';
import { UserSettings } from '@/types/settings';

const { user } = useAuth();
const settings = user?.profile?.settings as UserSettings;

// Access specific settings
const theme = settings?.theme;
const notifications = settings?.notifications?.enabled;

Custom Theme Context

import { useTheme } from '@/contexts/ThemeContext';

const { 
  activeTheme,      // Current active theme
  themes,           // All preset themes
  customTheme,      // User's custom theme
  setTheme,         // Switch theme
  setCustomTheme    // Save custom theme
} = useTheme();

Files Modified

Backend

  • hubx/src/models/Profile.ts - Added settings column
  • hubx/src/routes/user/profile.ts - Added PUT /settings endpoint
  • hubx/migrations/20260123000000-add-settings-to-profile.js - Migration file

Frontend Types

  • hub/src/types/settings.ts - NEW: Centralized settings types
  • hub/src/types/user.ts - Updated to use UserSettings
  • hub/src/types/index.ts - Export settings types

Frontend Context

  • hub/src/contexts/ThemeContext.tsx - Added custom theme support
  • hub/src/lib/profileApi.ts - Added updateSettings function

Frontend UI

  • hub/src/app/settings/page.tsx - Complete settings page with custom theme editor

Usage Example

// Save notification settings
await updateSettings({
  notifications: {
    enabled: true,
    email: true,
    releaseUpdates: true
  }
});

// Create custom theme
await updateSettings({
  theme: 'custom',
  customTheme: {
    id: 'custom',
    name: 'My Theme',
    mode: 'dark',
    palette: {
      background: '#000000',
      surface: '#111111',
      // ... other colors
    }
  }
});

Benefits

  1. Type Safety: All settings have proper TypeScript types
  2. Centralized: Single source of truth for settings structure
  3. Extensible: Easy to add new settings categories
  4. Persistent: All settings saved to database
  5. User-Friendly: Visual theme editor with live preview
  6. Flexible: Supports both preset and custom themes