API-Referenz · Kernthemen

@oriatheme/core

Themenvertrags-, Validierungs-, Auflösungs- und Import-/Export-APIs ohne DOM-, Speicher-, React- oder Vue-Abhängigkeit.

Paket und Umgebung

Rein TypeScript; sicher bei der Knoten-, SSR- und Browsermodul-Evaluierung.

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

Verwenden Sie den Paketmanager und die Sperrdatei, die bereits vom Verbraucherprojekt ausgewählt wurden. Beispiele verwenden nur Paket-Root-Exporte; Führen Sie keinen Deep-Import aus src-, dist- oder Registry-Vorlagen durch.

Öffentliche Funktionen

Exportieren	Unterschrift	Beschreibung
`defineTokenContract`	`(input: TokenContractInput) => TokenContract`	Erstellt einen unveränderlichen, validierten Vertrag.
`extendTokenContract`	`(base, extension) => TokenContract`	Fügt Vertragstoken hinzu, ohne die Basis zu verlieren.
`getTokenDefinition`	`(contract, path) => TokenDefinition \| undefined`	Sucht nach einem deklarierten Token.
`token / colorToken`	`(type, options) => TokenDefinition`	Erstellt Vertrags-Token-Definitionen.
`validateTheme`	`(input, contract) => ValidationResult<ThemeDefinition>`	Wird niemals für nicht vertrauenswürdige serialisierte Eingaben ausgelöst.
`normalizeTheme`	`(theme, contract) => ThemeDefinition`	Kanonisiert die Bestellung und erfüllt Vertragsvorgaben.
`resolveTheme`	`(theme, mode, options?) => ResolvedTheme`	Löst Referenzen auf und kompiliert sichere CSS-Variablen.
`resolveThemeWithContract`	`(theme, contract, mode, options?) => ResolvedTheme`	Sicherer Resolver mit explizitem Vertrag.
`cloneTheme`	`(theme, identity, clock?) => ThemeDefinition`	Erstellt eine vollständige Kopie mit Zeitstempel.
`createThemeFromSeed`	`(seed, options) => ThemeDefinition`	Erstellt ein vollständiges benutzerdefiniertes Standard-Vertragsthema.
`exportTheme`	`(theme) => string`	Serialisiert das öffentliche Theme-Format.
`importTheme`	`(json, options) => ImportResult`	Validiert JSON, erzwingt eine benutzerdefinierte Art und behandelt Konflikte.
`analyzeTheme`	`(theme, contract) => ThemeDiagnostics`	Gibt Blockierungsfehler und Kontrastwarnungen zurück.
`contrastRatio`	`(foreground, background) => number`	Berechnet den WCAG-Kontrast für statische Hex-Farben.
`toCssVariable`	(path, prefix?, cssNameStyle?) => `--${string}`	Konvertiert einen validierten Pfad in eine benutzerdefinierte CSS-Eigenschaft.
`isTokenPath`	`(value) => value is TokenPath`	Schränkt eine Zeichenfolge auf einen Marken-Token-Pfad ein.
`oriaStandardContract / oriaDefaultTheme`	`TokenContract / ThemeDefinition`	Der Standardvertrag und das Standardthema von oria-standard@2 seit 0.3.0.
`oriaStandardContractV1 / oriaDefaultThemeV1`	`TokenContract / ThemeDefinition`	Legacy v1-Exporte werden nur als Migrationseingabe beibehalten.
`migrateOriaStandardV1ToV2`	`(input: unknown) => ThemeMigrationResult`	Konvertiert ein vollständiges v1-Standarddesign in v2 mit Warnungen und erfordert eine Überprüfung.

import { oriaStandardContract, resolveTheme, validateTheme } from "@oriatheme/core";

const checked = validateTheme(input, oriaStandardContract);
if (checked.ok) {
  const resolved = resolveTheme(checked.value, "dark");
  // resolved.variables is safe compiler output.
}

Verzweigen Sie auf „validateTheme“- oder „importTheme“-Ergebnisse für Benutzereingaben; stimmen nicht mit den Fehlermeldungen überein.

Wichtige Typen und Grenzen

ThemeDefinition ist das vollständige serialisierte Theme (schemaVersion 1; der Standardvertrag ist oria-standard@2 seit 0.3.0); TokenContract beschreibt Pfade und sichere Werte; ValidationResult / ImportResult unterscheiden nach ok; OriaThemeError.code ist der stabile Fehlerzweig. ResolvedTheme enthält kompilierte Variablen und colorScheme. ThemeMigrationResult enthält das migrierte Design, Warnungen und erfordert eine Überprüfung.