{"id":20269958,"url":"https://github.com/xcraft-inc/goblin-theme","last_synced_at":"2026-06-12T09:31:36.494Z","repository":{"id":78427027,"uuid":"196344008","full_name":"Xcraft-Inc/goblin-theme","owner":"Xcraft-Inc","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-18T14:33:04.000Z","size":483,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-18T19:02:42.876Z","etag":null,"topics":["goblins","theme-framework"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xcraft-Inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-07-11T07:37:10.000Z","updated_at":"2025-07-18T14:33:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"ff260e9e-8f90-4707-b0ad-8d269006c7eb","html_url":"https://github.com/Xcraft-Inc/goblin-theme","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/Xcraft-Inc/goblin-theme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fgoblin-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fgoblin-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fgoblin-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fgoblin-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xcraft-Inc","download_url":"https://codeload.github.com/Xcraft-Inc/goblin-theme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fgoblin-theme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34238712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["goblins","theme-framework"],"created_at":"2024-11-14T12:28:11.937Z","updated_at":"2026-06-12T09:31:36.488Z","avatar_url":"https://github.com/Xcraft-Inc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📘 goblin-theme\n\n## Aperçu\n\nLe module `goblin-theme` est un système de gestion de thèmes visuels pour l'écosystème Xcraft. Il fournit un framework complet pour composer, éditer et appliquer des thèmes graphiques dynamiques aux applications. Le module permet de créer des thèmes personnalisés en combinant différents éléments : couleurs, espacements, temporisations et styles visuels.\n\n## Sommaire\n\n- [Structure du module](#structure-du-module)\n- [Fonctionnement global](#fonctionnement-global)\n- [Exemples d'utilisation](#exemples-dutilisation)\n- [Interactions avec d'autres modules](#interactions-avec-dautres-modules)\n- [Configuration avancée](#configuration-avancée)\n- [Détails des sources](#détails-des-sources)\n\n## Structure du module\n\nLe module s'organise autour de plusieurs composants principaux :\n\n- **Acteur theme-composer** : Gestionnaire central des thèmes et compositions (type Goblin)\n- **Acteur theme-editor** : Service d'édition et d'application des thèmes (type Goblin)\n- **Widgets d'édition** : Interface utilisateur pour créer et modifier les thèmes\n- **Bibliothèques utilitaires** : Outils de manipulation des couleurs et unités\n- **Builders par défaut** : Constructeurs pour générer les différents aspects d'un thème\n- **Collections prédéfinies** : Palettes de couleurs, espacements et styles\n\n## Fonctionnement global\n\nLe système fonctionne selon une architecture modulaire où chaque thème est composé de quatre éléments principaux :\n\n1. **Colors** : Définit la palette de couleurs (base, hilite, light, dark, etc.)\n2. **Spacing** : Configure les espacements, marges et tailles de police\n3. **Timing** : Gère les durées d'animations et transitions\n4. **Look** : Détermine l'apparence générale et les accessoires visuels\n\nL'acteur `theme-composer` orchestre la composition des thèmes en chargeant dynamiquement ces éléments depuis des fichiers de configuration. Les thèmes peuvent être créés à la volée ou prédéfinis via la configuration du module.\n\nLe processus de composition suit cette logique :\n\n1. Chargement des fichiers de configuration pour chaque composant (colors, spacing, timing, look)\n2. Application des builders pour générer la palette complète, les formes et les styles\n3. Stockage du thème composé dans l'état de l'acteur\n4. Notification des changements aux composants d'interface\n\nL'acteur `theme-editor` agit comme une interface entre l'éditeur de thème et le bureau, permettant d'appliquer les changements de thème en temps réel.\n\n## Exemples d'utilisation\n\n### Création d'un compositeur de thème\n\n```javascript\nconst themeComposer = await this.quest.create('theme-composer', {\n  id: 'theme-composer@myApp',\n  desktopId,\n  displayName: 'Mon Thème',\n  builder: 'default',\n  colors: 'default',\n  spacing: 'default',\n  timing: 'default',\n  look: 'default',\n});\n```\n\n### Composition d'un nouveau thème\n\n```javascript\nawait themeComposer.composeTheme({\n  name: 'custom-theme',\n  displayName: 'Thème Personnalisé',\n  colors: 'dark',\n  spacing: 'compact',\n  timing: 'default',\n  look: 'default',\n});\n```\n\n### Utilisation des utilitaires de couleur\n\n```javascript\nconst {ColorManipulator} = require('goblin-theme');\n\n// Assombrir une couleur\nconst darkerColor = ColorManipulator.darken('#336799', 0.2);\n\n// Ajouter de la transparence\nconst fadedColor = ColorManipulator.fade('#336799', 0.5);\n\n// Calculer le contraste\nconst ratio = ColorManipulator.getContrastRatio('#ffffff', '#000000');\n```\n\n### Utilisation des utilitaires d'unités\n\n```javascript\nconst {Unit} = require('goblin-theme');\n\n// Convertir en pixels\nconst pixels = Unit.toPx(16); // \"16px\"\n\n// Additionner des valeurs avec unités\nconst total = Unit.add('10px', '5px'); // \"15px\"\n\n// Multiplier une valeur\nconst doubled = Unit.multiply('10px', 2); // \"20px\"\n```\n\n### Application d'un thème via l'éditeur\n\n```javascript\nconst themeEditor = await this.quest.create('theme-editor', {\n  id: 'theme-editor@myApp',\n  desktopId,\n});\n\n// Sélectionner et appliquer un thème\nawait themeEditor.select({composition: 'dark-theme'});\n```\n\n## Interactions avec d'autres modules\n\nLe module `goblin-theme` interagit étroitement avec :\n\n- **[goblin-laboratory]** : Fournit le composant `Frame` pour appliquer les thèmes et les widgets de base\n- **[goblin-gadgets]** : Utilise les widgets de base pour l'interface d'édition\n- **[xcraft-core-etc]** : Charge la configuration des compositions de thèmes\n- **[xcraft-core-converters]** : Convertit les formats de couleurs\n- **[xcraft-core-goblin]** : Framework de base pour les acteurs theme-composer et theme-editor\n\n## Configuration avancée\n\n| Option            | Description                                  | Type  | Valeur par défaut |\n| ----------------- | -------------------------------------------- | ----- | ----------------- |\n| `compositions`    | Liste des compositions de thèmes disponibles | Array | `[]`              |\n| `subThemeContext` | Liste des contextes de sous-thèmes           | Array | `[]`              |\n\n## Détails des sources\n\n### `lib/index.js`\n\nPoint d'entrée principal du module qui expose les utilitaires de manipulation des couleurs, des unités et les builders par défaut. Fournit une API unifiée pour accéder aux fonctionnalités du système de thèmes à travers les objets `ColorManipulator`, `ColorHelpers`, `Unit` et `defaultBuilders`.\n\n### `lib/theme-composer.js`\n\nActeur Goblin qui gère la composition et la gestion des thèmes. Il orchestre la création de thèmes en combinant les différents éléments (couleurs, espacements, etc.) et maintient l'état des thèmes disponibles.\n\n#### État et modèle de données\n\nL'état du compositeur contient :\n\n- `id` : Identifiant unique du compositeur\n- `themes` : Map des thèmes disponibles indexés par nom (contient le thème 'default' et les compositions configurées)\n- `colors` : Map des palettes de couleurs utilisées\n\n#### Méthodes publiques\n\n- **`create(desktopId, displayName, builder, colors, spacing, timing, look)`** — Initialise un nouveau compositeur de thème avec les paramètres spécifiés et charge automatiquement les compositions configurées dans `goblin-theme.compositions`.\n- **`composeTheme(name, displayName, builder, colors, spacing, timing, look, meta)`** — Compose un nouveau thème en combinant les éléments fournis et l'ajoute à la collection. Utilise la fonction `composeTheme` interne pour charger et assembler les composants.\n- **`change(path, newValue, clientSessionId)`** — Modifie une propriété d'un thème existant et déclenche un événement de rechargement pour la session client spécifiée.\n\n### `lib/themes/color-manipulator.js`\n\nBibliothèque complète de manipulation des couleurs offrant des fonctions pour modifier la luminosité, la saturation, la transparence et calculer les contrastes. Supporte les formats hexadécimaux, RGB, RGBA, HSL et HSLA avec des conversions automatiques entre espaces colorimétriques (RGB, HSL, HSV).\n\n#### Fonctions principales\n\n- **`darken(color, coefficient)`** — Assombrit une couleur selon le coefficient donné\n- **`lighten(color, coefficient)`** — Éclaircit une couleur selon le coefficient donné\n- **`fade(color, value)`** — Applique une transparence à une couleur\n- **`emphasize(color, coefficient)`** — Assombrit ou éclaircit automatiquement selon la luminance\n- **`getContrastRatio(foreground, background)`** — Calcule le ratio de contraste entre deux couleurs selon les standards WCAG\n- **`getLuminance(color)`** — Calcule la luminance relative d'une couleur\n- **`convertHexToRGB(color)`** — Convertit une couleur hexadécimale en format RGB\n- **`convertHexToRGBObject(hex)`** — Convertit une couleur hexadécimale en objet RGB\n- **`saturate(color, coefficient)`** — Modifie la saturation d'une couleur\n- **`brightnen(color, coefficient)`** — Modifie la luminosité d'une couleur dans l'espace HSV\n\n### `lib/themes/color-helpers.js`\n\nUtilitaires spécialisés pour la gestion des couleurs dans le contexte des thèmes Xcraft. Fournit notamment la fonction `getMarkColor` qui résout les références de couleurs symboliques comme 'primary', 'secondary', 'success', etc. vers les couleurs effectives du thème.\n\n#### Fonctions principales\n\n- **`getMarkColor(theme, value)`** — Résout une référence de couleur symbolique vers la couleur effective du thème. Supporte les couleurs directes (hex, rgb), les mots-clés de couleur (primary, secondary, success, etc.) et les conversions automatiques depuis d'autres espaces colorimétriques.\n\n### `lib/themes/unit.js`\n\nSystème de gestion des unités CSS permettant de manipuler et convertir les valeurs avec unités (px, rem, em, %, vmax, vmin, vh, vw). Offre des opérations arithmétiques sur les valeurs avec unités et gère la conversion entre différentes unités CSS.\n\n#### Fonctions principales\n\n- **`toValue(value)`** — Extrait la valeur numérique d'une chaîne avec unité\n- **`toInt(value)`** — Convertit une chaîne avec unité en entier\n- **`toPx(value)`** — Convertit un nombre en chaîne avec unité 'px'\n- **`toPc(n)`** — Convertit un nombre en pourcentage\n- **`to(n, cssUnit)`** — Convertit une valeur vers une unité CSS spécifique avec support des ratios\n- **`parse(value)`** — Analyse une valeur et retourne un objet {value, unit}\n- **`fix(value, decimals)`** — Formate un nombre avec un nombre spécifique de décimales\n- **`multiply(value, factor, rounded)`** — Multiplie une valeur avec gestion des unités et options d'arrondi\n- **`add(a, b, decimals)`** — Additionne deux valeurs avec unités compatibles\n- **`sub(a, b, decimals)`** — Soustrait deux valeurs avec unités compatibles\n\n### `widgets/theme-composer/widget.js`\n\nWidget principal qui orchestre l'interface d'édition des thèmes en combinant le sélecteur de compositions, l'éditeur de détails et l'aperçu des exemples. Gère la visibilité conditionnelle basée sur le contexte de thème sélectionné.\n\n### `widgets/composition-selector/widget.js`\n\nInterface de sélection des thèmes disponibles avec support pour les thèmes \"easter eggs\" cachés. Affiche la liste des compositions avec leur nom d'affichage et permet la sélection active. Inclut un bouton secret pour activer l'accès aux thèmes expérimentaux marqués avec `meta.egg = true`.\n\n### `widgets/composition-detail/widget.js`\n\nÉditeur détaillé des propriétés d'un thème permettant de modifier en temps réel les couleurs, espacements et autres paramètres. Utilise les définitions de propriétés des fichiers `props.js` pour générer automatiquement les champs d'édition appropriés. Supporte l'édition conditionnelle selon le thème actuel et organise les propriétés par catégories avec tri automatique.\n\n### `widgets/composition-samples/widget.js`\n\nAperçu en temps réel des thèmes avec des exemples d'interface utilisateur. Affiche une application factice utilisant le thème sélectionné pour visualiser l'impact des modifications. Inclut des contrôles de mise à l'échelle et présente divers composants UI (boutons, champs, tableaux, tickets, jauges, sliders, etc.) dans un environnement de démonstration complet avec barres de tâches, onglets et panneaux.\n\n### `widgets/context-switch/widget.js`\n\nSélecteur de contexte permettant de basculer entre différents compositeurs de thème disponibles. Affiche la liste des applications ayant un compositeur de thème actif et permet de naviguer entre elles pour éditer leurs thèmes respectifs.\n\n### `widgets/theme-editor/service.js`\n\nActeur Goblin pour l'éditeur de thème qui gère les interactions avec le bureau et l'application des changements de thème.\n\n#### État et modèle de données\n\nL'état de l'éditeur contient :\n\n- `id` : Identifiant unique de l'éditeur\n\n#### Méthodes publiques\n\n- **`create(desktopId)`** — Initialise un nouvel éditeur de thème pour le bureau spécifié.\n- **`select(composition)`** — Applique le thème sélectionné au bureau en utilisant l'API du bureau pour déclencher le changement de thème.\n\n### `widgets/theme-editor/widget.js`\n\nWidget principal de l'éditeur de thème qui combine le sélecteur de contexte et les compositeurs de thème pour chaque application disponible. Affiche une interface complète permettant de basculer entre les différents contextes d'application et d'éditer leurs thèmes respectifs.\n\n### `widgets/theme-context/index.js`\n\nConfiguration du contexte de thème incluant les polices, styles globaux et builders. Définit l'environnement d'exécution pour l'application des thèmes avec chargement des polices Lato et configuration des styles CSS globaux. Fournit les fonctions `getFonts` et `getGlobalStyles` pour l'intégration avec le système de thèmes.\n\n### `widgets/theme-context/fa-free.js` et `widgets/theme-context/fa-pro.js`\n\nConfiguration des icônes FontAwesome pour les versions gratuite et professionnelle. Ces fichiers initialisent la bibliothèque d'icônes utilisée dans l'interface des thèmes en chargeant les icônes nécessaires selon la licence disponible. Incluent des mappings et des fallbacks pour assurer la compatibilité entre les versions.\n\n### Builders par défaut\n\nLes builders sont des fonctions qui génèrent les différents aspects d'un thème :\n\n#### `default-palette-builder.js`\n\nGénère la palette de couleurs complète à partir des couleurs de base. Applique des transformations automatiques selon le mode sombre/clair et calcule toutes les variantes de couleurs nécessaires pour l'interface (backgrounds, borders, text colors, etc.). Utilise les fonctions de manipulation de couleurs pour créer des variations cohérentes et gère automatiquement l'inversion des transformations pour les thèmes sombres.\n\n#### `default-shapes-builder.js`\n\nCalcule les formes, tailles et espacements des éléments UI basés sur les paramètres de spacing. Génère les dimensions pour tous les composants (boutons, barres, panneaux, etc.) en utilisant les unités de base et les fonctions de manipulation d'unités. Adapte automatiquement les ombres et effets visuels selon le mode sombre/clair.\n\n#### `default-styles-builder.js`\n\nFournit les styles CSS de base et utilitaires incluant les resets CSS, les tailles complètes et les styles de mise en page fondamentaux. Définit des objets de style réutilisables pour normaliser l'apparence des éléments avec des utilitaires pour les marges, paddings, bordures et alignements.\n\n#### `default-transitions-builder.js`\n\nConfigure les animations et transitions avec des durées basées sur les paramètres de timing. Définit les transitions par défaut, les fonctions d'easing et les animations spécialisées (rotation, glissement, overlay, etc.). Inclut des fonctions utilitaires `create` et `easeOut` pour générer des transitions CSS personnalisées.\n\n#### `default-typo-builder.js`\n\nDéfinit la typographie et les polices en utilisant les paramètres de spacing pour la famille de police et l'échelle. Configure la pile de polices de fallback pour assurer la compatibilité avec les polices système.\n\n### Collections prédéfinies\n\nLe module inclut des collections prêtes à l'emploi organisées par catégories :\n\n#### Colors\n\nPalettes de couleurs prédéfinies avec support pour les thèmes sombres et clairs :\n\n- `default-colors` : Palette bleue standard\n- `dark-colors`, `matrix-colors`, `dragula-colors` : Thèmes sombres avec couleurs vives\n- `nord-colors` : Palette inspirée du thème Nord\n- `green-colors`, `red-colors`, `pink-colors` : Variantes colorées\n- `steampunk-colors`, `oldtimer-colors`, `clock-colors` : Thèmes spécialisés rétro\n- `mono-colors` : Thème monochrome\n\n#### Spacings\n\nConfigurations d'espacement pour différents styles d'interface :\n\n- `default-spacing` : Espacement standard (32px de hauteur de ligne)\n- `compact-spacing` : Interface compacte (25px de hauteur de ligne)\n- `rounded-spacing`, `smooth-spacing` : Variantes avec rayons arrondis\n- `special-spacing` : Configuration expérimentale avec espacement négatif\n- `clock-spacing`, `oldtimer-spacing`, `steampunk-spacing`, `royal-spacing` : Espacements thématiques avec polices spécialisées\n\n#### Timings\n\nParamètres de temporisation pour les animations :\n\n- `default-timing` : Durée de base de 250ms pour toutes les animations\n\n#### Looks\n\nStyles visuels définissant l'apparence générale :\n\n- `default-look` : Style moderne standard avec horloge analogique configurable\n- `dark-look`, `green-look`, `mono-look`, `nord-look`, `pink-look` : Variantes de style moderne\n- `clock-look`, `oldtimer-look`, `royal-look`, `steampunk-look` : Styles rétro avec accessoires (vis, engrenages) et gadgets d'accueil personnalisés\n\n### Fichiers de propriétés\n\nChaque catégorie inclut un fichier `props.js` définissant les types et contraintes des propriétés éditables, utilisé par l'interface d'édition pour générer automatiquement les contrôles appropriés. Ces fichiers spécifient les types de champs (color, pixel, bool, combo, integer, number, etc.) avec leurs paramètres de validation (min, max, step, list) et permettent la génération dynamique de l'interface d'édition.\n\n---\n\n_Document mis à jour_\n\n[goblin-laboratory]: https://github.com/Xcraft-Inc/goblin-laboratory\n[goblin-gadgets]: https://github.com/Xcraft-Inc/goblin-gadgets\n[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc\n[xcraft-core-converters]: https://github.com/Xcraft-Inc/xcraft-core-converters\n[xcraft-core-goblin]: https://github.com/Xcraft-Inc/xcraft-core-goblin","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcraft-inc%2Fgoblin-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxcraft-inc%2Fgoblin-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcraft-inc%2Fgoblin-theme/lists"}