# themed_varmory

A themed extension for [Varmory](https://www.npmjs.com/package/varmory) — adds a set of swappable visual themes (default, rpg, space, finance), a theme store, themed helper components, and a showcase wrapper that layers its own catalogue on top of varmory's built-in one.

- [Live Component Showcase](https://themed-varmory-384cf7df8efa.herokuapp.com/)
- [MCP Server](https://themed-varmory-384cf7df8efa.herokuapp.com/mcp) — Streamable HTTP

If Varmory is the showcase framework, themed_varmory is the skin. It ships:

- **Themes** — `default`, `rpg`, `space`, `finance`; each is a `{ common, dark, light }` triple of CSS files that swap CSS variables (`--q-primary`, `--q-surface-*`, fonts, glows, panel gradients, etc.) at runtime
- **Custom themes** — ship your own `{ common, dark, light }` triple and either replace the built-ins or merge in alongside them via the `theme` / `themes` plugin options; see [THEMING.md](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/THEMING.md) for the contract
- **`useThemeStore`** — Pinia store for `currentTheme`, `isDark`, `applyTheme()`, `toggleDark()`
- **Themed components** — `JPanel` (with `accent` prop that paints a theme-signature background), `JThemeSwitcher`, `JDarkSwitcher`, `JCurrentYear`. The accented `JPanel` is deliberately versatile — use it anywhere you'd reach for a `QCard`, but also as the building block for app headers, hero banners, callouts, featured sidebars, and **theme-styled dialogs** (see the *Accented JPanel* group in the Dialogs showcase for a drop-in dialog pattern).
- **Showcase wrapper** — a `JComponentShowcaseWithContent` that auto-loads themed_varmory's README, `docs/*.md`, and its own showcase categories, and merges them on top of varmory's built-in catalogue. Same-named entries override the built-ins.
- **Everything Varmory ships still works** — themed_varmory is additive. The full Quasar component catalogue (QBtn, QSelect, QTable, QDialog, …) is registered and browsable in the showcase, and varmory's [MCP server](docs/MCP.md) is reused as-is so AI agents can discover both varmory's built-ins and themed_varmory's components, docs, and API definitions through the same endpoint — no separate server to run.

## Quickest start: ask an AI agent

The fastest way to build with themed_varmory is to let an AI agent do it. Point your agent at the hosted showcase and ask it to build something:

> Build me a themed dashboard using https://themed-varmory-384cf7df8efa.herokuapp.com/ as the component library

The showcase host exposes an [MCP server](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/MCP) and machine-readable component/doc endpoints (`/llms.txt`, `/components`, `/docs/:name`), so agents like Claude can discover every component, its API, the themes, and the docs automatically — no manual setup on your side.

## Installation

```bash
npm install themed_varmory
```

Peer dependencies:

```bash
npm install vue@^3 quasar@^2 @quasar/extras@^1 pinia@^3 varmory@^1
```

## Setup

themed_varmory assumes **Quasar** and **Pinia** are already attached to the Vue app — the theme store is a Pinia store, and the components are Quasar-based.

```js
// vite.config.js
import vue from '@vitejs/plugin-vue';
import { quasar, transformAssetUrls } from '@quasar/vite-plugin';

export default {
    plugins: [
        vue({ template: { transformAssetUrls } }),
        quasar({ autoImportComponentCase: 'pascal' }),
    ],
};
```

In your app's entry file, install **Pinia first**, then **Quasar**, then **themed_varmory**:

```js
// main.js
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import { Quasar, Notify, Dialog, LocalStorage, SessionStorage } from 'quasar';
import { ThemedVarmory } from 'themed_varmory';
import 'quasar/dist/quasar.css';
import '@quasar/extras/material-icons/material-icons.css';
import App from './App.vue';

createApp(App)
    .use(createPinia())
    .use(Quasar, { plugins: { Notify, Dialog, LocalStorage, SessionStorage } })
    .use(ThemedVarmory, { theme: 'space' })
    .mount('#app');
```

themed_varmory internally installs varmory as a plugin, so you do **not** need to `.use(Varmory)` yourself — its showcase components are registered automatically.

### Plugin options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `theme` | `string \| object` | `'default'` | Built-in theme name (`'default'`, `'rpg'`, `'space'`, `'finance'`) or an inline `{ common, dark, light }` theme object. |
| `themes` | `object \| null` | — | Extra themes merged with the built-ins: `{ myBrand: { common, dark, light } }`. Pass `null` or `false` to disable the theme store entirely. |

See [THEMING.md](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/THEMING.md) for custom themes, the store API, and how to disable theming.

## Using the showcase

```vue
<template>
    <JComponentShowcaseWithContent />
</template>

<script>
import { JComponentShowcaseWithContent } from 'themed_varmory';
export default { components: { JComponentShowcaseWithContent } };
</script>
```

It auto-bundles:

- `README.md` at the themed_varmory root
- every file under `docs/*.md`
- every entry under `src/themed_varmory/showcase/categories/<NN Name>/*.vue`

…layered on top of varmory's built-in showcase. Same-named entries (for example a local `01 Colors/AllColors.vue`) override the built-in one. You can still pass extra `components` / `docs` props to add project-specific categories.

## Relationship to Varmory

| Varmory | themed_varmory |
|---------|----------------|
| Showcase framework, MCP server, component renderer, Quasar component docs | Skin + store + theme-aware helper components + showcase overrides |
| `Varmory` plugin registers `JComponentShowcase*` globally | `ThemedVarmory` plugin registers varmory **and** themed_varmory's components, plus boots the theme store |
| Exposes the whole Quasar API surface through MCP | Reuses `varmory/mcp`; the scanner walks themed_varmory's own `categories/` and `definitions/` folders so its components show up alongside varmory's |

Anything that works in a varmory app keeps working — themed_varmory is additive.

## Docs

- [Usage](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/USAGE.md) — entry-file wiring, peer setup, plugin options
- [Theming](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/THEMING.md) — built-in themes, theme store API, custom themes, disabling theming
- [Accent Background](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/AccentBackground.md) — `JPanel accent` prop and the `varmoryBackgroundAccent` CSS hook themes paint
- [Custom Components](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/CustomComponents.md) — conventions for building Vue components on top of themed_varmory
- [MCP Server](https://themed-varmory-384cf7df8efa.herokuapp.com/#docs/MCP.md) — exposing themed_varmory's showcase, docs, and API definitions to AI agents