@supersoniks/concorde 4.6.0 → 4.7.3

package/.gitlab-ci.yml

@@ -0,0 +1,23 @@
+stages:
+  - test
+
+variables:
+  GIT_STRATEGY: clone
+  GIT_DEPTH: "0"
+
+# TESTS : sur les Merge Requests ET sur les push dans master
+tests:
+  stage: test
+  tags:
+    - ssks7
+  rules:
+    # Dans le contexte d'une Merge Request
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      when: on_success
+    # Sur un push direct dans master
+    - if: '$CI_COMMIT_BRANCH == "master"'
+      when: on_success
+    # Sinon rien (push de branches sans MR)
+    - when: never
+  script:
+    - bash gitlab/job_tests.sh

package/README.md

@@ -1,101 +1,152 @@
 # Concorde Framework
 
-Framework de composants Web basé sur Lit Element avec un système de thèmes, de data binding et de composants réutilisables.
+`@supersoniks/concorde` — framework de composants Web basé sur Lit avec système de thèmes, data binding (décorateurs `@subscribe` / `@publish` / `@handle` / `@bind`...) et composants réutilisables.
+
+## 📚 Documentation
+
+La documentation en ligne (à jour) est disponible ici :
+
+👉 **https://doc.concorde.test/**
+
+Elle est générée à partir des fichiers `.md` du code source (`yarn build-docs`).Utilisation à vos risques — contributions et retours bienvenus !**
+
+## 🤖 Agent IA (Cursor + JetBrains)
+
+
+> **Disclaimer : les règles n'ont encore été vraiment testées et seront msie a jour au fur et a mesure. 
+
+Règles et skills installables depuis `ai/` :
+
+```bash
+yarn ai-init
+# ou dans un projet consommateur :
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+```
+
+Installe `.cursor/skills`, `.cursor/rules`, `.aiassistant/rules` et `AGENTS.md`. Voir [ai/README.md](ai/README.md).
 
 ## 📁 Structure du projet
 
 ```
 concorde/
 ├── src/                    # Code source principal
-│   ├── core/              # Cœur du framework
-│   │   ├── components/    # Composants UI et fonctionnels
-│   │   ├── mixins/        # Mixins réutilisables
-│   │   ├── utils/         # Utilitaires
-│   │   └── _types/        # Types TypeScript
-│   ├── docs/              # Composants de documentation
-│   └── index.ts           # Point d'entrée principal
-├── docs/                  # Documentation générée
-├── dist/                  # Fichiers de build
-├── public/                # Assets publics
-├── package.json           # Configuration npm
-├── vite.config.mts        # Configuration Vite
-└── tailwind.config.js     # Configuration Tailwind
+│   ├── core/               # Cœur du framework
+│   │   ├── components/      # Composants UI et fonctionnels
+│   │   ├── decorators/      # Décorateurs (subscribe, publish, handle, bind...)
+│   │   ├── directives/      # Directives Lit
+│   │   ├── mixins/          # Mixins réutilisables
+│   │   ├── utils/           # Utilitaires
+│   │   └── _types/          # Types TypeScript
+│   ├── docs/                # Sources de la documentation
+│   └── index.ts             # Point d'entrée principal
+├── dist/                   # Build de la librairie (généré)
+├── docs/                   # Documentation générée (généré)
+├── public/                 # Assets publics
+├── gitlab/                 # Scripts des jobs GitLab CI
+├── scripts/                # Scripts de build / publication
+├── vite.config.mts         # Configuration Vite
+├── tailwind.config.js      # Configuration Tailwind
+└── package.json            # Configuration du package (yarn)
 ```
 
 ## 🎨 Composants disponibles
 
-### Composants UI (20)
-- **Formulaires** : input, select, checkbox, radio, textarea
+### Composants UI
+- **Formulaires** : input, select, checkbox, radio, textarea, switch, fieldset
 - **Navigation** : button, link, menu
-- **Feedback** : alert, badge, modal, toast, tooltip
+- **Feedback** : alert, alert-messages, badge, modal, toast, tooltip, progress
 - **Layout** : card, table, divider, group
-- **Media** : icon, image, loader, progress
+- **Media** : icon, image, loader
 
-### Composants fonctionnels (15)
+### Composants fonctionnels
 - **Data** : fetch, list, queue, subscriber, value
 - **Navigation** : router, redirect, states
-- **Logic** : if, submit, mix, translation
-- **Advanced** : sdui (Server Driven UI)
+- **Logique** : if, submit, mix, translation
+- **Avancé** : sdui (Server Driven UI)
+
+## 🔗 Concepts clés : Endpoint, DataProvider / DataProviderKey & décorateurs
+
+Le cœur de Concorde est un **data binding réactif**. Un **DataProvider** (publisher / store observable) détient les données ; les composants s'y **abonnent** ou y **publient** via des **décorateurs**, en ciblant soit un chemin typé local (**DataProviderKey**), soit une ressource distante (**Endpoint**).
+
+```mermaid
+flowchart LR
+  api[("API / Endpoint<T>")] -->|"@get"| dp["DataProvider (store)"]
+  dp -->|"@subscribe / @bind / @handle"| comp["Composant Lit"]
+  comp -->|"@publish / @bind"| dp
+```
+
+### Les briques de données
+
+- **`DataProviderKey<T>`** — chemin **typé** en notation pointée vers une structure composite, ex. `new DataProviderKey<Data>("data").items[0]` → `"data.items.0"`. Navigation type-safe, chemins dynamiques via `${prop}`. Import : `@supersoniks/concorde/dataProviderKey`. Voir [la doc DataProviderKey](https://doc.concorde.test/#docs/_misc/dataProviderKey.md/dataProviderKey).
+- **`Endpoint<T, U>`** — un **unique chemin HTTP** (sans notation pointée) portant le type de réponse `T` ; segments dynamiques `${...}`. Consommé par `@get`. Import : `@supersoniks/concorde/utils/endpoint`. Voir [la doc Endpoint](https://doc.concorde.test/#docs/_misc/endpoint.md/endpoint).
+- **DataProvider** — le publisher observable qui notifie ses abonnés à chaque assignation.
+
+### Les décorateurs (`src/core/decorators/subscriber/`)
+
+| Décorateur | Rôle | Cible |
+|---|---|---|
+| `@subscribe(key)` | Liaison **lecture seule** : la propriété suit le publisher | `DataProviderKey<T>` |
+| `@publish(key)` | Liaison **écriture seule** : assigner la propriété publie vers le chemin | `DataProviderKey<T>` |
+| `@bind(path)` | Liaison **bidirectionnelle** (accepte aussi un chemin string) | chemin / clé |
+| `@handle(...keys)` | Appelle une **méthode typée** à chaque assignation (effets de bord, calculs) | jusqu'à 3 `DataProviderKey<T>` |
+| `@get(endpoint)` | Charge des données via l'API ; la propriété devient `ApiGetResult<T> \| null` | `Endpoint<T>` |
+
+`DataProviderKey` est la pierre angulaire : c'est lui qui fournit les chemins **typés** utilisés par `@subscribe`, `@publish`, `@bind` et `@handle`, tandis que `Endpoint` fait le pont avec les données distantes via `@get`. Détails et exemples sur la [documentation des décorateurs](https://doc.concorde.test/#docs/_decorators/subscribe.md/subscribe).
 
 ## 🛠️ Développement
 
+Le projet utilise **yarn** (voir `packageManager` dans `package.json`).
+
 ### Installation
 ```bash
-npm install
-# ou
 yarn install
 ```
 
-### Développement
+### Serveur de dev
 ```bash
-npm run dev
-# ou
 yarn dev
 ```
+Lance Vite sur `https://localhost:3000` (host `0.0.0.0`, SSL local).
 
-### Build
+### Build de la librairie
 ```bash
-npm run build
-# ou
 yarn build
 ```
+Produit `dist/` ainsi que `concorde-core.es.js` / `concorde-core.bundle.js`.
 
-### Tests
+### Build de la documentation
 ```bash
-npm test
-# ou
-yarn test
+yarn build-docs
 ```
 
-## 📚 Documentation
-
-- **[Documentation principale](docs/)** - Documentation générée
-- **[Composants](src/core/components/)** - Code source des composants
-- **[Exemples](docs/)** - Exemples d'utilisation
+### Tests
+```bash
+yarn test       # mode watch (développement)
+yarn test:ci    # exécution unique (utilisé par la CI)
+```
 
 ## 🔧 Technologies
 
-- **Lit Element** - Web Components
-- **TypeScript** - Langage principal
-- **Tailwind CSS** - Styles utilitaires
-- **Vite** - Build tool
-- **Vitest** - Tests
+- **Lit** — Web Components
+- **TypeScript** — langage principal
+- **Tailwind CSS** — styles utilitaires
+- **Vite** — build / dev server
+- **Vitest** — tests (environnement jsdom)
 
-## 📄 Licence
+## 🔁 Intégration continue (GitLab)
 
-MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+Le projet est hébergé sur GitLab et la CI est définie dans [.gitlab-ci.yml](.gitlab-ci.yml) :
 
-## 🤝 Contribution
+- le job `tests` s'exécute sur les **Merge Requests** et sur les push dans **`master`** ;
+- il tourne sur le runner `ssks7` et lance `yarn install` + `yarn test:ci` dans le conteneur `nodejs` (script [gitlab/job_tests.sh](gitlab/job_tests.sh)).
 
-Pour contribuer au projet :
+## 🤝 Contribution
 
-1. Fork le projet
-2. Créer une branche feature
-3. Modifier le code
-4. Tester avec `npm test`
-5. Créer une Pull Request
+1. Créer une branche à partir de `master`.
+2. Faire ses modifications.
+3. Vérifier les tests : `yarn test:ci`.
+4. Ouvrir une **Merge Request** vers `master` (la CI lance les tests automatiquement).
 
-## 📞 Support
+## 📄 Licence
 
-- **Issues** : [GitHub Issues](https://github.com/supersoniks/concorde/issues)
-- **Documentation** : [docs/](docs/)
+MIT — voir le fichier [LICENSE](LICENSE).

package/ai/AGENTS.md

@@ -0,0 +1,52 @@
+# Agents — Concorde
+
+Guide pour les agents IA sur un projet **Concorde** (Lit + DataProvider).
+
+## Skills / rules (après installation)
+
+| Fichier | Rôle |
+|---------|------|
+| `.cursor/skills/concorde/SKILL.md` | Patterns framework |
+| `.cursor/skills/concorde-imports/SKILL.md` | Imports courts |
+| `.cursor/skills/concorde-scope/SKILL.md` | Scope + APIConfiguration |
+| `.cursor/skills/concorde-theme/SKILL.md` | Design tokens sonic-theme |
+| `.cursor/skills/concorde-menu/SKILL.md` | Navigation sonic-menu |
+| `.cursor/skills/concorde-get-set-dp/SKILL.md` | Migration get/set/dp + DataProviderKey statique |
+| `.cursor/rules/concorde.mdc` | Règles Cursor (patterns) |
+| `.aiassistant/rules/concorde.md` | Règles JetBrains AI Assistant |
+
+Installation :
+
+```bash
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+```
+
+Source : `@supersoniks/concorde/ai/`
+
+## Imports dans ce dépôt (lib + doc)
+
+Les chemins courts (`@supersoniks/concorde/list`, `/menu`, `/queue`, …) sont des **exports npm** pour les apps **externes**. Dans le repo Concorde (`src/docs`, `src/core`, démos), utiliser les chemins **réels** :
+
+- Composants : `@supersoniks/concorde/core/components/…` ou import relatif (`../../core/components/functional/list/list`)
+- Décorateurs : `@supersoniks/concorde/core/decorators/Subscriber` (ou `src/decorators.ts` via `@supersoniks/concorde/decorators` si résolu par l’alias Vite racine)
+- `DataProviderKey` : `@supersoniks/concorde/core/utils/dataProviderKey`
+
+Skill **`concorde-imports`** : section « Dans le dépôt Concorde ».
+
+## Conventions impératives
+
+- Toujours **DataProvider**, accès via **`get` / `set`**
+- Pas de **`sonic-fetch`**, pas de **`PublisherManager`**
+- Pas de `@onAssign` — **`@handle`** + `DataProviderKey`
+- Pas de **`@bind`** sur les composants métier — **`@subscribe`** + `DataProviderKey<T, U>` (type + contraintes hôte `${…}`)
+- Formulaires : **`formDataProvider`** + `name` sur `sonic-input`
+- Listes : templates **Lit** (`.items`, `.separator`, `.noItems`, `.skeleton`) — pas de promotion des `<template>` HTML
+- **Scope** (API/forms) ≠ **theme** (couleurs) — skills `concorde-scope` / `concorde-theme`
+
+## Migration get / set / dp
+
+Skill **`concorde-get-set-dp`** : chemins sans placeholder **`${…}`** / **`{$…}`** pour `get` / `set` / `dp` ; chemins JS évalués OK ; clés dynamiques → décorateurs, `dp(idRésolu)`, ou **`sub(clé)`** dans les templates Lit.
+
+## Documentation
+
+Fichiers `.md` dans le package : `node_modules/@supersoniks/concorde/src/` (composants, décorateurs, getting-started).

package/ai/README.md

@@ -0,0 +1,30 @@
+# Agent IA — Concorde
+
+Fichiers installables pour **Cursor** et **JetBrains AI Assistant**.
+
+## Installation dans un projet
+
+```bash
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+```
+
+Options :
+
+- `--overlay <dir>` — couche additionnelle (ex. kit starter)
+- `--merge-agents` — fusionne avec un `AGENTS.md` existant
+- `--cursor-only` / `--jetbrains-only`
+
+Depuis le dépôt Concorde (dev) : `yarn ai-init`
+
+## Contenu
+
+| Dossier | Cible |
+|---------|--------|
+| `skills/` | `.cursor/skills/` (concorde, imports, scope, theme, menu) |
+| `cursor/rules/` | `.cursor/rules/` |
+| `jetbrains/rules/` | `.aiassistant/rules/` |
+| `AGENTS.md` | racine du projet |
+
+## Template starter
+
+Le package `create-concorde-ts-starter` ajoute un overlay via `yarn ai:sync`.

package/ai/cursor/rules/concorde-menu.mdc

@@ -0,0 +1,15 @@
+---
+description: Navigation Concorde — sonic-menu, sonic-menu-item, sonic-divider
+globs: **/{layout,sidebar,nav,docs-shell,routes}/**
+alwaysApply: false
+---
+
+# Navigation Concorde
+
+1. **`sonic-menu`** + **`sonic-menu-item`** — pas une liste de boutons ghost.
+2. Sections : **`sonic-divider`** (`label`, `align="left"`, `size="sm"`).
+3. Liens internes : `pushstate` + `href` + `autoActive="strict"`.
+
+Référence : `.cursor/skills/concorde-menu/SKILL.md`
+
+Pas de tirets dans les noms de dossiers de routes (générateur Concorde).

package/ai/cursor/rules/concorde-scope.mdc

@@ -0,0 +1,14 @@
+---
+description: Scope — inherited API, form, icon defaults (not theme)
+globs: **/*.{ts,tsx,html}
+alwaysApply: false
+---
+
+# Scope
+
+Skill **`concorde-scope`**
+
+- `<sonic-scope>` — light DOM, attributes inherited by descendants
+- API: `serviceURL`, `token`, `credentials` → `@get`, list, queue
+- Or: `DataProviderKey<APIConfiguration>` as 2nd arg to `@get`
+- Not for colors/fonts — use **`concorde-theme`**

package/ai/cursor/rules/concorde-theme.mdc

@@ -0,0 +1,13 @@
+---
+description: sonic-theme — design tokens, not API scope
+globs: **/*.{ts,tsx,css,html}
+alwaysApply: false
+---
+
+# Theme
+
+Skill **`concorde-theme`**
+
+- `<sonic-theme background color font>` + `--sc-*` CSS variables
+- `theme="dark"` for built-in dark palette
+- Not for `serviceURL` / API — use **`concorde-scope`**

package/ai/cursor/rules/concorde.mdc

@@ -0,0 +1,49 @@
+---
+description: Patterns Concorde — DataProvider, décorateurs, templates Lit list/queue, pas sonic-fetch
+globs: **/*.{ts,tsx,js,mjs}
+alwaysApply: false
+---
+
+# Concorde — patterns
+
+Référence : `.cursor/skills/concorde/SKILL.md` + `.cursor/skills/concorde-imports/SKILL.md`
+Migration get/set/dp : `.cursor/skills/concorde-get-set-dp/SKILL.md`
+
+## Imports
+
+**Apps externes** : chemins courts (`@supersoniks/concorde/list`, `/menu`, `/decorators`, …) — voir skill `concorde-imports`.
+
+**Dépôt Concorde (lib + doc)** : chemins longs ou relatifs — ex. `core/components/functional/list/list`, `core/decorators/Subscriber`, `core/utils/dataProviderKey`. Pas `@supersoniks/concorde/list` ici.
+
+## Vocabulaire
+
+- **DataProvider** (jamais « publisher »)
+- Accès : **`get` / `set`** — pas `PublisherManager`
+
+## Interdits (nouveau code)
+
+- `sonic-fetch` → `sonic-queue` + filtre, ou `@get`
+- `@onAssign` → `@handle` + `DataProviderKey`
+- `@bind` → `@subscribe` + `DataProviderKey<T, U>` (pas sur composants métier)
+- `data-bind` HTML → `@subscribe` / `sub()`
+- `sonic-input` + `@input` → `formDataProvider` + `name`
+- Templates HTML sur list/queue → `.items`, `.separator`, `.noItems`, `.skeleton`
+
+## DataProviderKey dynamique
+
+```typescript
+new DataProviderKey<T, { userIndex: number }>("users.${userIndex}")
+```
+
+Placeholder `${prop}` = chaîne normale, résolu depuis le composant hôte.
+
+## get / set / dp vs sub()
+
+- **`get` / `set` / `dp`** : pas de `${` / `{$` dans la string passée (clé statique ou chemin JS évalué).
+- **`sub(chemin | DataProviderKey)`** : dynamique OK dans les templates (placeholders `${…}` sur l’hôte).
+- Clé dynamique → décorateur ou `dp(idRésolu)`, pas `dp(cléAvecPlaceholder)`.
+
+## Scope / theme
+
+- **Scope** : `<sonic-scope serviceURL="…">` · `@get(endpoint)` ou `@get(endpoint, apiConfigKey)` — skills `concorde-scope`
+- **Theme** : `<sonic-theme background color font>` · `--sc-*` — skill `concorde-theme`

package/ai/jetbrains/rules/concorde.md

@@ -0,0 +1,39 @@
+# Concorde — patterns agent
+
+Référence doc : fichiers `.md` dans `node_modules/@supersoniks/concorde/src/`.
+
+## Imports
+
+**Apps externes** : chemins courts (`/menu`, `/list`, `/decorators`, `/dataProviderKey`, …).
+
+**Dépôt Concorde (lib + doc)** : `core/components/functional/list/list`, `core/decorators/Subscriber`, `core/utils/dataProviderKey` — pas `@supersoniks/concorde/list` ici.
+
+## Vocabulaire
+
+- **DataProvider** (jamais « publisher »)
+- Accès : **get / set** — pas PublisherManager
+
+## Interdits (nouveau code)
+
+- sonic-fetch → sonic-queue + filtre, ou @get
+- @onAssign → @handle + DataProviderKey
+- data-bind HTML → @subscribe / sub()
+- sonic-input + @input → formDataProvider + name
+- Templates HTML list/queue → .items, .separator, .noItems, .skeleton
+- Chemins longs ui/…, functional/…, core/… quand un alias racine existe
+
+## DataProviderKey dynamique
+
+Placeholder `${prop}` dans une chaîne normale : `"users.${userIndex}"`.
+
+## Scope vs theme
+
+- **Scope** (`sonic-scope`) : `serviceURL`, `formDataProvider`, icônes — skill `concorde-scope`
+- **Theme** (`sonic-theme`) : `--sc-*` tokens, dark mode — skill `concorde-theme`
+- `@get(endpoint)` sans clé config → hérite scope ; `@get(endpoint, apiConfigKey)` → DataProvider
+
+## Navigation
+
+sonic-menu + sonic-menu-item + sonic-divider. pushstate + autoActive="strict".
+
+Pas de tirets dans les noms de dossiers routes.