@loudpacks/theme-core

Shared business logic, types, hooks, and utilities for the @loudpacks theme switcher system.

Overview

This package provides the core functionality for theme switching, including:

• Type re-exports from @loudpacks/theme-definitions
• React hooks for theme management
• Validation utilities
• Type guards for runtime type checking
• Shared business logic

Installation

pnpm add @loudpacks/theme-core

Type Re-exports

All types and constants from @loudpacks/theme-definitions are re-exported for convenience:

import {
  // Types
  type ThemeName,
  type ColorScheme,
  type ThemeMetadata,
  type ColorSchemeMode,

  // Constants
  DEFAULT_THEME_NAME,
  DEFAULT_COLOR_SCHEME,
  VALID_THEME_NAMES,

  // Theme data
  THEMES
} from '@loudpacks/theme-core';

This means you can import types and constants from @loudpacks/theme-core without directly depending on @loudpacks/theme-definitions.

React Hooks

useSystemColorScheme

Detects the system's preferred color scheme:

import { useSystemColorScheme } from '@loudpacks/theme-core';

function App() {
  const systemScheme = useSystemColorScheme();
  // Returns 'light' or 'dark' based on system preference

  return <div>System prefers: {systemScheme}</div>;
}

useThemePreview

Manages temporary theme preview state:

import { useThemePreview } from '@loudpacks/theme-core';

function ThemeSettings() {
  const {
    isPreviewActive,
    previewTheme,
    startPreview,
    endPreview,
  } = useThemePreview();

  return (
    <div>
      <button onClick={() => startPreview('ocean')}>
        Preview Ocean Theme
      </button>
      <button onClick={endPreview}>
        End Preview
      </button>
      {isPreviewActive && <p>Previewing: {previewTheme}</p>}
    </div>
  );
}

Utilities

getThemeColors

Resolves theme colors based on theme name and color scheme:

import { getThemeColors } from '@loudpacks/theme-core';

const colors = getThemeColors('ocean', 'dark');
console.log(colors.background); // "#0f1f1e"
console.log(colors.tint); // "#5eead4"

validateTheme

Validates a theme object structure and returns errors:

import { validateTheme } from '@loudpacks/theme-core';

const errors = validateTheme(themeObject, 'myTheme');
if (errors.length > 0) {
  console.error('Theme validation failed:', errors);
}

validateThemes

Validates multiple themes:

import { validateThemes } from '@loudpacks/theme-core';

const result = validateThemes({ theme1, theme2 });
if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

assertValidTheme

Throws an error if theme is invalid:

import { assertValidTheme } from '@loudpacks/theme-core';

try {
  assertValidTheme(themeObject, 'myTheme');
  // Theme is valid
} catch (error) {
  // Theme is invalid
}

Type Guards

isValidThemeName

Runtime type guard for theme names:

import { isValidThemeName } from '@loudpacks/theme-core';

const userInput: unknown = 'ocean';

if (isValidThemeName(userInput)) {
  // TypeScript now knows userInput is ThemeName
  const theme = THEMES[userInput]; // Type-safe access
}

isValidColorScheme

Runtime type guard for color scheme modes:

import { isValidColorScheme } from '@loudpacks/theme-core';

const setting: unknown = 'dark';

if (isValidColorScheme(setting)) {
  // TypeScript now knows setting is ColorSchemeMode
  applyColorScheme(setting); // Type-safe usage
}

Type Definitions

Core Types (Re-exported from theme-definitions)

// Theme name union type
type ThemeName =
  | 'monochrome'
  | 'ocean'
  | 'sepia'
  | 'nord'
  | 'crimson'
  | 'forest'
  | 'lavender'
  | 'amber'
  | 'midnight'
  | 'rose';

// Color scheme mode
type ColorSchemeMode = 'light' | 'dark' | 'system';

// Color scheme with 18 properties
interface ColorScheme {
  background: string;
  surface: string;
  text: string;
  textSecondary: string;
  border: string;
  tint: string;
  icon: string;
  tabIconDefault: string;
  tabIconSelected: string;
  elevatedSurface: string;
  selectedSurface: string;
  overlay: string;
  hover: string;
  pressed: string;
  disabled: string;
  highlight: string;
  linkColor: string;
  accentSecondary: string;
}

// Theme metadata
interface ThemeMetadata {
  displayName: string;
  description: string;
  light: ColorScheme;
  dark: ColorScheme;
}

Package Structure

@loudpacks/theme-core/
├── dist/
│   ├── index.js         # CommonJS build
│   ├── index.mjs        # ESM build
│   └── index.d.ts       # TypeScript declarations
└── src/
    ├── hooks/
    │   ├── useSystemColorScheme.ts
    │   └── useThemePreview.ts
    ├── utils/
    │   ├── getThemeColors.ts
    │   └── validateTheme.ts
    ├── types.ts         # Type definitions and re-exports
    └── index.ts         # Main exports

Dependencies

This package has a workspace dependency on @loudpacks/theme-definitions:

{
  "dependencies": {
    "@loudpacks/theme-definitions": "workspace:*"
  },
  "peerDependencies": {
    "react": ">=18.0.0"
  }
}

Development

# Build package
pnpm --filter @loudpacks/theme-core build

# Run tests
pnpm --filter @loudpacks/theme-core test

# Type check
pnpm --filter @loudpacks/theme-core typecheck

Related Packages

• @loudpacks/theme-definitions - Theme color definitions (360 colors)
• @loudpacks/theme-web - Next.js implementation
• @loudpacks/theme-native - React Native implementation

License

MIT