npm package: @loudpacks/theme-core
Description: Shared business logic, types, hooks, and utilities for theme switcher
Author: Noted
Latest version: 0.2.0

# @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

```bash
pnpm add @loudpacks/theme-core
```

## Type Re-exports

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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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)

```typescript
// 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`:

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

## Development

```bash
# 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