Référence API · Thèmes principaux

@oriatheme/core

API de contrat de thème, de validation, de résolution et d'importation/exportation sans dépendance DOM, stockage, React ou Vue.

Forfait et environnement

Pur TypeScript ; sécurisé dans l'évaluation des modules Node, SSR et navigateur.

bash

pnpm add @oriatheme/core

bash

npm install @oriatheme/core

bash

yarn add @oriatheme/core

bash

bun add @oriatheme/core

Utilisez le gestionnaire de packages et le fichier de verrouillage déjà choisis par le projet consommateur. Les exemples utilisent uniquement les exportations racine du package ; n'effectuez pas d'importation approfondie à partir de modèles src, dist ou de registre.

Fonctions publiques

Exporter	Signature	Descriptif
`defineTokenContract`	`(input: TokenContractInput) => TokenContract`	Crée un contrat immuable et validé.
`extendTokenContract`	`(base, extension) => TokenContract`	Ajoute des jetons de contrat sans perdre la base.
`getTokenDefinition`	`(contract, path) => TokenDefinition \| undefined`	Recherche un jeton déclaré.
`token / colorToken`	`(type, options) => TokenDefinition`	Crée des définitions de jetons de contrat.
`validateTheme`	`(input, contract) => ValidationResult<ThemeDefinition>`	Ne lance jamais une entrée sérialisée non fiable.
`normalizeTheme`	`(theme, contract) => ThemeDefinition`	Canonique la commande et comble les défauts du contrat.
`resolveTheme`	`(theme, mode, options?) => ResolvedTheme`	Résout les références et compile les variables sécurisées CSS.
`resolveThemeWithContract`	`(theme, contract, mode, options?) => ResolvedTheme`	Résolveur sécurisé avec un contrat explicite.
`cloneTheme`	`(theme, identity, clock?) => ThemeDefinition`	Crée une copie complète horodatée.
`createThemeFromSeed`	`(seed, options) => ThemeDefinition`	Crée un thème personnalisé complet de contrat standard.
`exportTheme`	`(theme) => string`	Sérialise le format de thème public.
`importTheme`	`(json, options) => ImportResult`	Valide JSON, force le type personnalisé et gère les conflits.
`analyzeTheme`	`(theme, contract) => ThemeDiagnostics`	Renvoie les erreurs de blocage et les avertissements de contraste.
`contrastRatio`	`(foreground, background) => number`	Calcule le contraste WCAG pour les couleurs hexadécimales statiques.
`toCssVariable`	(path, prefix?, cssNameStyle?) => `--${string}`	Convertit un chemin validé en propriété personnalisée CSS.
`isTokenPath`	`(value) => value is TokenPath`	Réduit une chaîne à un chemin de jeton de marque.
`oriaStandardContract / oriaDefaultTheme`	`TokenContract / ThemeDefinition`	Le contrat oria-standard@2 par défaut et le thème par défaut depuis la 0.3.0.
`oriaStandardContractV1 / oriaDefaultThemeV1`	`TokenContract / ThemeDefinition`	Les exportations v1 héritées sont conservées uniquement comme entrée de migration.
`migrateOriaStandardV1ToV2`	`(input: unknown) => ThemeMigrationResult`	Convertit un thème standard v1 complet en v2 avec des avertissements et requireReview.

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.
}

Branchez sur les résultats validateTheme ou importTheme pour la saisie de l'utilisateur ; ne correspondent pas aux messages d'erreur.

Types et limites importants

ThemeDefinition est le thème sérialisé complet (schemaVersion 1 ; le contrat par défaut est oria-standard@2 depuis 0.3.0) ; TokenContract décrit les chemins et les valeurs sûres ; ValidationResult / ImportResult discrimine sur ok ; OriaThemeError.code est la branche d'erreur stable. ResolvedTheme contient des variables compilées et colorScheme. ThemeMigrationResult contient le thème migré, les avertissements et requireReview.