Concorde Framework

@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 : concorde.supersoniks.org
• Code source public : github.com/supersoniks/concorde
• Développement interne : GitLab Supersoniks (Merge Requests)

📚 Documentation

La documentation en ligne est disponible ici :

👉 https://concorde.supersoniks.org/

Elle est générée à partir des fichiers .md du code source (yarn build-docs).

En local : yarn dev → https://localhost:3000

🤖 Agent IA (Cursor + JetBrains)

Disclaimer : les règles n'ont pas encore été vraiment testées et seront mises à jour au fur et à mesure.

Règles et skills installables depuis ai/ :

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.

📁 Structure du projet

concorde/
├── src/                    # Code source principal
│   ├── 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

• Formulaires : input, select, checkbox, radio, textarea, switch, fieldset
• Navigation : button, link, menu
• Feedback : alert, alert-messages, badge, modal, toast, tooltip, progress
• Layout : card, table, divider, group
• Media : icon, image, loader

Composants fonctionnels

• Data : fetch, list, queue, subscriber, value
• Navigation : router, redirect, states
• 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).

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.
• 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.
• 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 ApiResult<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.

🛠️ Développement

Le projet utilise yarn (voir packageManager dans package.json).

Installation

yarn install

Serveur de dev

yarn dev

Lance Vite sur https://localhost:3000 (host 0.0.0.0, SSL local).

Build de la librairie

yarn build

Produit dist/ ainsi que concorde-core.es.js / concorde-core.bundle.js.

Build de la documentation

yarn build-docs

Tests

yarn test       # mode watch (développement)
yarn test:ci    # exécution unique (utilisé par la CI)

🔧 Technologies

• Lit — Web Components
• TypeScript — langage principal
• Tailwind CSS — styles utilitaires
• Vite — build / dev server
• Vitest — tests (environnement jsdom)

🔁 Intégration continue

GitLab (développement interne)

CI définie dans .gitlab-ci.yml :

• 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 (script gitlab/job_tests.sh).

GitHub (miroir public)

CI définie dans .github/workflows/ci.yml — exécute yarn test:ci sur chaque push et Pull Request.

Le dépôt GitHub est un export filtré depuis GitLab (librairie uniquement — pas de site doc, pas de sonic-captcha, pas d’infra interne). Voir OPEN_SOURCE_CHECKPOINT.md.

🤝 Contribution

Voir CONTRIBUTING.md.

Résumé :

• Équipe interne : branche + Merge Request sur GitLab interne.
• Contributeurs externes : Un jour peut-être.

📄 Licence

MIT — voir le fichier LICENSE.