Guide

Installation

1 npm install @xpulse/theme --registry=https://npm.xpulse.one

Nutzung

Wenn @xpulse/theme installiert und von @xpulse/app gestartet wurde, wird ein einzelnes minifiziertes CSS-Bundle unter /_theme/css/xpulse.css bereitgestellt. Alle Themes (dark, light sowie App-Overrides) sind darin enthalten.

Empfohlen – Template-Methods im Layout:

1 {% themeAssets() %}

Das rendert automatisch den Bundle-Link, das Anti-FOUC-Script und das Browser-Runtime-Script. Für Theme-Switching zusätzlich:

1 {% themeSwitcher() %}

JavaScript

@xpulse/theme ist ohne verpflichtendes Runtime-JavaScript nutzbar. Die meisten Anwendungsfälle basieren nur auf:

HTML-Struktur
CSS-Klassen (xpulse-*)
--xpulse-* Custom Properties

JavaScript ist nur für optionale Verhaltensschichten sinnvoll:

Theme-Switching via /_theme/theme.js
Live-Demo für :root-Tokens via themeTokenEditor()
Aktiven TOC-Eintrag beim Scrollen markieren
Copy-to-Clipboard bei Code-Blöcken

Was das Package liefert

Built-in Themes unter public/css/themes/ (dark, light)
Basis-CSS unter public/css/base.css
Komponenten-CSS unter public/css/components/
Ein einzelnes HTTP-Bundle: GET /_theme/css/xpulse.css
Browser-Runtime: GET /_theme/theme.js
Kein manuelles Registrieren von Themes nötig

Eigenes App-Theme

Lege in deiner App eine Datei unter src/themes/ an:

1 /* src/themes/app.css */
2 .xpulse-shell {
3   width: min(1100px, calc(100% - 32px));
4   margin: 32px auto;
5 }

Wichtig:

Kein @import des Basis-Themes – app.css enthält nur lokale Overrides
Die Datei wird ans Ende des Bundles angehängt
themeAssets() bindet app.css zusätzlich als separaten <link> ein, damit Änderungen in Entwicklung ohne Cache-Rebuild wirksam werden

Theme Switcher

1 {% themeAssets() %}
2 {% themeSwitcher() %}

theme.allow und theme.default in xpulse.json steuern den Switcher:

1 {
2   "theme": {
3     "default": "dark",
4     "allow": ["dark", "light"]
5   }
6 }

`allow`	Ergebnis
`[]` oder nicht gesetzt	Alle entdeckten Themes erlaubt
`["dark", "light"]`	Kompakter Mond/Sonne-Toggle
`["dark", "light", "high-contrast"]`	Select-Dropdown
`["dark"]`	Kein Switcher sichtbar

Caching

Das CSS-Bundle wird beim ersten Start in var/cache/theme/xpulse.css gecacht und bei Folgestarts direkt von dort geladen.

Im Dev-Mode (NODE_ENV !== 'production') wird der Cache automatisch übersprungen
Mit theme.init({ force: true }) kann der Cache manuell umgangen werden
TTL und aktivierter Status sind über xpulse.json konfigurierbar:

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

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

Komponenten-Klassen

Die CSS-Klassen aus @xpulse/theme folgen dem xpulse-*-Prefix und BEM:

.xpulse-box / .xpulse-box--header / .xpulse-box--content
.xpulse-brand / .xpulse-brand__title
.xpulse-nav__item--depth-1
.xpulse-button--primary / .xpulse-button--secondary

Die zugehörigen CSS-Variablen folgen dem Prefix --xpulse-*.

1	/* src/themes/app.css */
2	.xpulse-shell {
3	width: min(1100px, calc(100% - 32px));
4	margin: 32px auto;
5	}

1	{
2	"theme": {
3	"default": "dark",
4	"allow": ["dark", "light"]
5	}
6	}