Seiten

Inhalt

API

init(options = {})

1 import theme from '@xpulse/theme';
2  
3 await theme.init();
4  
5 // Mit Optionen
6 await theme.init({ root: process.cwd(), force: false });

Baut das CSS-Bundle, schreibt den Cache, registriert die HTTP-Routen und hängt sich in http:response:before ein — ab dann werden CSS-Bundle, Anti-FOUC-Script und theme.js automatisch in jede HTML-Antwort injiziert. themeAssets() im Template ist damit optional.

Option	Typ	Beschreibung	Default
`root`	`string`	Basis-Verzeichnis – bestimmt wo nach `src/themes/` gesucht wird	`process.cwd()`
`force`	`boolean`	Cache ignorieren und Bundle neu aufbauen	`false`

init() ist idempotent – mehrfache Aufrufe werden ignoriert.

href()

1 theme.href();
2 // → '/_theme/css/xpulse.css'

URL des gebündelten CSS (Base + Components + alle Themes, minifiziert).

scriptHref()

1 theme.scriptHref();
2 // → '/_theme/theme.js'

URL des Browser-Runtime-Scripts (Theme-Toggle, Token-Editor).

current()

1 theme.current();
2 // → 'dark'

Aktuelles Default-Theme laut Config (theme.default in xpulse.json).

available()

1 theme.available();
2 // → ['dark', 'light']

Alle Themes die im gebündelten CSS per [data-theme="..."]-Selektor entdeckt wurden.

allowed()

1 theme.allowed();
2 // → ['dark', 'light']

Subset von available(), gefiltert durch theme.allow in xpulse.json. Wenn theme.allow leer oder nicht gesetzt – identisch mit available().

has(name)

1 theme.has('dark');   // → true
2 theme.has('foo');    // → false

Prüft ob ein Theme im Bundle bekannt ist.

set(name)

1 theme.set('light');  // → true
2 theme.set('foo');    // → false (unbekannt)

Setzt das aktuelle Theme. Gibt false zurück wenn das Theme unbekannt oder nicht in allowed() ist.

toggle()

1 theme.toggle();

Wechselt zwischen den zwei erlaubten Themes. Gibt false zurück wenn allowed() nicht exakt 2 Einträge hat.

Registrierte Routen

Route	Beschreibung
`GET /_theme/css/xpulse.css`	Minifiziertes All-in-One-CSS-Bundle
`GET /_theme/theme.js`	Browser-Runtime-Script

Template-Methoden

`themeAssets()`

1 {% themeAssets() %}

Rendert:

<link rel="stylesheet" href="/_theme/css/xpulse.css">
Optional: <link rel="stylesheet" href="/_theme/app.css"> falls ein App-Theme vorhanden
Inline Anti-FOUC-Script (setzt data-theme + theme-*-Klasse sofort im <head>)
<script defer src="/_theme/theme.js">

`themeSwitcher()`

1 {% themeSwitcher() %}

Rendert keinen Output wenn allowed() nur 1 Theme enthält. Bei genau dark + light → kompakter Mond/Sonne-Toggle-Button. Bei mehr als 2 Themes → <select>-Dropdown.

`themeTokenEditor()`

1 {% themeTokenEditor() %}

Live-Editor für ausgewählte :root-Tokens. Setzt CSS Custom Properties direkt im Browser und speichert Overrides in localStorage.

Discovery

Theme-Namen werden aus dem gebündelten CSS per Regex ermittelt:

1 [data-theme="dark"]   → 'dark'
2 [data-theme="light"]  → 'light'

CSS-Quelldateien werden in dieser Reihenfolge gebündelt:

1 1. public/css/base.css
2 2. public/css/components/*.css  (via @import in components.css)
3 3. public/css/themes/*.css      (Built-in Themes)
4 4. src/themes/*.css             (App-Overrides, optional)

Caching

Das Bundle wird in var/cache/theme/xpulse.css gecacht.

In Dev-Mode (NODE_ENV !== 'production') immer übersprungen
init({ force: true }) ignoriert den Cache
Konfigurierbar über theme.cache in xpulse.json

1 {
2   "theme": {
3     "cache": {
4       "enabled": true,
5       "ttl": 0
6     }
7   }
8 }

ttl: 0 = kein Ablauf. ttl: 3600 = Cache nach 1 Stunde ungültig.

Events

Bundle-Build

Event	Payload	Wann
`themes:load:start`	—	Build beginnt
`theme:basics:loaded`	—	`base.css` geladen
`theme:components:loaded`	—	Alle Component-CSS geladen
`theme:loaded`	`{ name }`	Einzelnes Theme-CSS geladen
`themes:concatenated`	—	Alle Parts zusammengefügt
`themes:minified`	—	Bundle minifiziert
`themes:cached`	`{ path }`	Bundle auf Disk geschrieben
`themes:load:end`	—	Build abgeschlossen
`theme:ready`	`{ theme, available }`	`init()` vollständig

Cache

Event	Payload	Wann
`themes:cache:hit`	`{ path }`	Gültiger Cache-File gefunden
`themes:cache:miss`	—	Bundle wird neu gebaut
`themes:cache:loaded`	`{ serveCount }`	Bundle-Request bedient

Laufzeit

Event	Payload	Wann
`theme:changed`	`{ from, to }`	`set()` / `toggle()` erfolgreich
`theme:warning`	`{ type, … }`	Ungültiges/verbotenes Theme, Toggle-Fehler
`theme:error`	`{ type }`	Keine Themes im Bundle gefunden

1	import theme from '@xpulse/theme';
2
3	await theme.init();
4
5	// Mit Optionen
6	await theme.init({ root: process.cwd(), force: false });

1	theme.has('dark'); // → true
2	theme.has('foo'); // → false

1	theme.set('light'); // → true
2	theme.set('foo'); // → false (unbekannt)

1	[data-theme="dark"] → 'dark'
2	[data-theme="light"] → 'light'

1	1. public/css/base.css
2	2. public/css/components/*.css (via @import in components.css)
3	3. public/css/themes/*.css (Built-in Themes)
4	4. src/themes/*.css (App-Overrides, optional)