npm package: @qiiqa/bob-ui-react-themes
Description: React theming and context for Qiiqa UI
Latest version: 0.6.0

# @qiiqa/bob-ui-react-themes

The theming and customization layer for Qiiqa React applications.

---

## Concept: Themes vs Variants

Bob UI separates appearance into two distinct concerns:

### Theme (Developer's choice)
A **theme** defines the **structural UX style** of your app — border rendering, shadow depth, density, and can include custom fonts, background images, and icon styles. The developer picks one theme for their entire app and it stays fixed.

Bob UI ships two built-in themes:
- **`clean`** — Minimal, modern. Interactive elements have no visible borders by default; only the active state shows a bottom underline.
- **`pragmatic`** — Traditional, clear. All buttons and tabs always show a 1px border.

Developers can also supply a **fully custom theme** — a CSS file with their own fonts, images, and `--q-*` variable overrides.

### Variant (User's choice)
A **variant** is a **color palette and light/dark mood** that the end user can switch between at runtime. Each variant is a CSS file setting `--q-*` color variables (primaries, backgrounds, text, etc.).

Bob UI ships these built-in variants: `moonlit`, `ocean`, `dark`, `green`, `light`.

Users can also create and save their own custom variants via `BobVariantDesigner`.

---

## Features

- **Two-tier separation**: Developer chooses the theme; users choose their variant.
- **Dynamic variant loading**: Variant CSS files are fetched at runtime — no bundle-time coupling.
- **System-aware**: Can auto-detect OS dark/light preference via `BobThemeProvider`.
- **Persistent**: Remembers user variant choices in `localStorage`.
- **Custom variants**: Users can create, save, and delete their own color variants via `BobVariantDesigner`.

---

## ⚠️ Required: Copy Variant CSS Files to Your Public Folder

The provider loads variant CSS files dynamically from browser-accessible URLs. These files ship with this package under `themes/`, but **must be served as static files** by your app.

Copy from:
```
node_modules/@qiiqa/bob-ui-react-themes/themes/
```
To your app's `public/themes/` folder:
```
your-app/public/themes/
  ├── theme-moonlit.css    ← "moonlit" color variant
  ├── theme-ocean.css      ← "ocean" color variant
  ├── theme-dark.css       ← "dark" color variant
  ├── theme-green.css      ← "green" color variant
  └── theme-original.css   ← "original" color variant
```

Without this step, variant switching will silently fail with no visual error.

---

## Usage

> **Prefer using `@qiiqa/bob-ui-react`** (the aggregate package). It re-exports everything from this package, so you rarely need to import directly from `@qiiqa/bob-ui-react-themes`.

### BobThemeProvider

Wrap your application root. The `themes` array uses the format `'{variant} {theme}'`:

```tsx
import { BobThemeProvider } from '@qiiqa/bob-ui-react';

const App = () => (
    <BobThemeProvider
        themes={[
            // '{variant} {theme}' — variant = color palette, theme = clean or pragmatic
            { name: 'moonlit clean',     label: 'Moonlit',      url: '/themes/theme-moonlit.css' },
            { name: 'moonlit pragmatic', label: 'Moonlit Pro',  url: '/themes/theme-moonlit.css' },
            { name: 'ocean clean',       label: 'Ocean',        url: '/themes/theme-ocean.css' },
            { name: 'ocean pragmatic',   label: 'Ocean Pro',    url: '/themes/theme-ocean.css' },
            { name: 'dark clean',        label: 'Dark',         url: '/themes/theme-dark.css' },
            { name: 'dark pragmatic',    label: 'Dark Pro',     url: '/themes/theme-dark.css' },
        ]}
        defaultLight="moonlit clean"
        defaultDark="dark pragmatic"
    >
        <YourApp />
    </BobThemeProvider>
);
```

### BobVariantSelector

A compact two-dropdown selector for users to pick their preferred variant at runtime. Place it in a header or toolbar:

```tsx
import { BobVariantSelector } from '@qiiqa/bob-ui-react';

function Header() {
    return (
        <header>
            <h1>My App</h1>
            <BobVariantSelector />
        </header>
    );
}
```

- First dropdown → **Theme** (`clean` / `pragmatic`) — the structural style
- Second dropdown → **Variant** (`moonlit`, `ocean`, etc.) — the color palette

### BobThemeSelector

Identical to `BobVariantSelector` but uses `BobBoxSelect` for visual consistency with the Bob component system:

```tsx
import { BobThemeSelector } from '@qiiqa/bob-ui-react';
<BobThemeSelector />
```

### BobVariantDesigner

A full design panel for users/admins to live-edit CSS color variables and save named custom variants:

```tsx
import { BobVariantDesigner, BobDialogBase } from '@qiiqa/bob-ui-react';
import { useState } from 'react';

const [open, setOpen] = useState(false);

<BobDialogBase id="variant-designer" isOpen={open} onClose={() => setOpen(false)}>
    {open && <BobVariantDesigner onClose={() => setOpen(false)} />}
</BobDialogBase>
```

### useBobTheme

Hook to read or control the current selection:

```tsx
import { useBobTheme } from '@qiiqa/bob-ui-react';

const { currentTheme, setTheme, isAuto, setAuto } = useBobTheme();
// currentTheme: e.g. 'moonlit clean'
```

---

## Built-in Variants

| Variant name | Mood | CSS file |
|---|---|---|
| `moonlit` | Dark blue | `theme-moonlit.css` |
| `ocean` | Deep navy | `theme-ocean.css` |
| `dark` | Pure dark | `theme-dark.css` |
| `green` | Dark green | `theme-green.css` |
| `light` | Light | `theme-light.css` |

Each can be combined with `clean` or `pragmatic` in the `themes` array.

---

See `apps/bob-ui-demo` for live visual verification of all themes and variants.