@supersoniks/concorde 4.5.2 → 4.7.0

package/ai/skills/concorde-get-set-dp/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: concorde-get-set-dp
+description: >-
+  Migration et usage de get/set/dp avec DataProviderKey statique.
+  Rejet des placeholders ${} par resolveStaticPublisherPath ; sub() et
+  décorateurs pour le dynamique.
+---
+
+# Concorde — get / set / dp (chemins statiques)
+
+Skill de **migration** vers Concorde ≥ 4.6 avec `resolveStaticPublisherPath`.
+À activer quand un projet monte de version ou refactorise vers `DataProviderKey`.
+
+Référence framework : skill **`concorde`**, doc `src/docs/_misc/dataProviderKey.md`.
+
+## Quand utiliser cette skill
+
+- Monter `@supersoniks/concorde` avec garde statique sur `get` / `set` / `dp`.
+- Auditer un codebase TypeScript existant avant/après upgrade.
+- Distinguer **chemin évalué en JS** vs **placeholder Concorde** `${prop}` / `{$prop}`.
+- Choisir entre API programmatique (`get/set/dp`) et réactivité (`sub`, décorateurs).
+
+## Règle de rejet (runtime)
+
+`resolveStaticPublisherPath` lève une erreur si la string passée à `get`, `set` ou `dp` contient **`${`** ou **`{$`** :
+
+| Appel | Résultat |
+|-------|----------|
+| `dp(new DataProviderKey("users.${userIndex}"))` | **throw** |
+| `get("users.${userIndex}")` | **throw** |
+| `dp(staticKey.path)` si `.path` contient `${` | **throw** |
+
+**OK** — le chemin est résolu **avant** l'appel (pas de placeholder littéral) :
+
+```typescript
+set(`app.pages.${index}.isComplete`, true); // → "app.pages.2.isComplete"
+dp(`${this.formDataProvider}/fieldName`); // → "checkoutForm/email"
+```
+
+**Faux positif fréquent** : grep `${` dans les sources TS ne suffit pas — vérifier la **valeur runtime** passée à `get/set/dp`.
+
+## Rétrocompatibilité
+
+| Avant | Après (recommandé) | Statut |
+|-------|-------------------|--------|
+| `dp(key.path)` | `dp(key)` | Équivalent si clé statique |
+| `set(key.path, v)` | `set(key, v)` | Équivalent |
+| `get("myCounter.count")` | `get(key.count)` | Typage amélioré |
+| `key.path` dans attribut HTML | Inchangé | Toujours valide |
+| `@onAssign(key.path)` | `@handle(key.leaf)` | Migration parallèle (skill `concorde`) |
+
+Aucune rupture pour le code qui passait déjà des **strings résolues** ou des clés **statiques**.
+
+## Trois niveaux d'accès DataProvider
+
+| Mécanisme | Contexte | Dynamique |
+|-----------|----------|-----------|
+| **`get` / `set` / `dp`** | Code impératif, snapshot instant T | **Non** (placeholder `${` interdit) |
+| **`sub(chemin \| clé)`** | Template Lit, réactivité | **Oui** — string, concat JS, ou `DataProviderKey` avec `${prop}` |
+| **`@subscribe` / `@publish` / `@handle`** | Propriétés composant | **Oui** — `DataProviderKey<T, U>` avec `"base.${prop}"` |
+| **`@bind`** | Legacy / bidirectionnel | Éviter sur composants métier — préférer `@subscribe` |
+
+### `sub()` — dynamique OK (clés incluses), ne pas migrer vers `get()`
+
+`sub()` accepte `string | DataProviderKey`, résout les placeholders `${prop}` depuis le **composant hôte** du template (comme `@subscribe`), et se ré-abonne quand les props observées changent.
+
+```typescript
+const userKey = new DataProviderKey<User, { userIndex: number }>("users.${userIndex}");
+
+html`<p>${sub(userKey.name)}</p>`
+html`<p>${sub(counterKey.count)}</p>`
+html`<p>${sub(this.formDataProvider + ".email")}</p>`
+```
+
+Doc : `src/docs/_directives/sub.md`.
+
+**Anti-pattern** : remplacer `sub(…)` par `get(…)` dans un template → perte de réactivité (snapshot unique).
+
+### Clé dynamique Concorde → décorateur ou factory
+
+```typescript
+export const resourceKey = new DataProviderKey<ResourceData, { resourceId: string }>(
+  "${resourceId}",
+);
+
+// ❌ dp(resourceKey) ou dp(resourceKey.path) → throw
+export const resourceProvider = (id: string) => dp<ResourceData>(id);
+
+@handle(resourceKey.conf.mode)
+onMode(mode: Mode) { /* … */ }
+```
+
+## Patterns avant / après
+
+### Statique typé (nouveau code)
+
+```typescript
+const cartKey = new DataProviderKey<Cart>("cart");
+set(cartKey, { items: [] });
+dp(cartKey.items[0].qty).set(1);
+```
+
+### ID runtime (string pure, pas placeholder Concorde)
+
+```typescript
+dp(resolvedId); // ex. "resource-abc123"
+set(`forms/${formId}`, formData);
+```
+
+### Index ou segment dynamique via JS (compatible)
+
+**Avant** :
+
+```typescript
+set(`app.pages.${index}.isComplete`, isComplete);
+return get(`app.labels.${language}.${key}`);
+```
+
+**Après** (option typée, même runtime) :
+
+```typescript
+const pagesKey = new DataProviderKey<AppState["pages"]>("app.pages");
+set(pagesKey[index].isComplete, isComplete);
+
+const labelsKey = new DataProviderKey<AppState["labels"]>("app.labels");
+return get(labelsKey[language][key]);
+```
+
+**Helper générique** — conserver si le suffixe ne contient jamais `${` :
+
+```typescript
+export const appSet = <P extends string>(path: P, value: AppValue<P>) => {
+  set(`app.${path}`, value);
+};
+```
+
+### Chemins entièrement statiques
+
+**Avant** :
+
+```typescript
+set("app.widget.computed", value);
+const publisher = dp("app.widget.distance");
+```
+
+**Après** :
+
+```typescript
+const widgetKey = new DataProviderKey<AppState["widget"]>("app.widget");
+set(widgetKey.computed, value);
+const publisher = dp(widgetKey.distance);
+```
+
+## Profils de risque (générique)
+
+| Profil codebase | Risque | Indice |
+|-----------------|--------|--------|
+| Strings JS uniquement, pas de `DataProviderKey` | Très faible | Chemins déjà résolus avant `get/set/dp` |
+| Mix `DataProviderKey` statique + `.path` | Faible | Simplifier `dp(key)` progressivement |
+| Clés avec `"${prop}"` passées à `dp()` | **Élevé** | Remplacer par factory `dp(idRésolu)` ou décorateur |
+| Templates avec `sub()` | Aucun | Ne pas « migrer » vers `get()` |
+
+Migrations **distinctes** (hors scope) : `PublisherManager`, `@onAssign` → `@handle`.
+
+## Checklist migration (agent)
+
+1. [ ] Confirmer version Concorde avec `resolveStaticPublisherPath` dans `dataProviderKey.ts`.
+2. [ ] Chercher `DataProviderKey(` dont le constructeur contient `${` ou `{$`.
+3. [ ] Pour chaque hit : si `get` / `set` / `dp` reçoit la clé → factory `dp(idRésolu)` ou décorateur.
+4. [ ] Simplifier `dp(staticKey.path)` → `dp(staticKey)` sur clés statiques.
+5. [ ] **Ne pas** toucher `sub(...)` ni décorateurs dynamiques sans raison.
+6. [ ] Distinguer grep `${` (source) vs valeur runtime.
+7. [ ] Tests manuels sur les flux métier qui utilisent clés dynamiques et formulaires `sub()`.
+
+## Anti-patterns
+
+| Anti-pattern | Pourquoi |
+|--------------|----------|
+| `dp(key)` sur clé `"${resourceId}"` | Throw immédiat |
+| `sub()` → `get()` dans template | Perte réactivité |
+| Refactor global `.path` → clé sur toutes les clés sans tri statique/dynamique | Régressions |
+| Confondre migration get/set/dp et suppression `PublisherManager` | Périmètres différents |
+
+## Fichiers de référence (package Concorde)
+
+- `src/core/utils/dataProviderKey.ts` — `resolveStaticPublisherPath`
+- `src/core/utils/PublisherProxy.ts` — overloads `get` / `set` / `dp`
+- `src/core/utils/publisherPathKey.spec.ts` — tests
+- `src/core/directives/DataProvider.ts` — `sub()`
+- `src/docs/_misc/dataProviderKey.md`
+
+## Maintenance
+
+Mettre à jour quand l'API Concorde évolue ou que de nouveaux cas edge sont documentés dans les specs.

package/ai/skills/concorde-imports/SKILL.md

@@ -0,0 +1,78 @@
+# Imports Concorde — chemins courts
+
+Toujours préférer le **chemin export le plus court** documenté dans `package.json` de `@supersoniks/concorde` — **dans les projets consommateurs** (apps qui installent le package).
+
+Éviter les chemins `ui/…`, `functional/…`, `core/…` quand un alias racine existe **en dehors du monorepo Concorde**.
+
+## Dans le dépôt Concorde (lib + doc)
+
+Les exports courts (`@supersoniks/concorde/list`, `/menu`, `/queue`, …) **ne résolvent pas** ici : l’alias Vite `@supersoniks/concorde` pointe sur `src/`, pas sur les sous-chemins `package.json`.
+
+| Besoin | ✅ Dans ce repo | ❌ Ne pas utiliser ici |
+|--------|----------------|------------------------|
+| `sonic-list` | `import "../../core/components/functional/list/list"` ou `@supersoniks/concorde/core/components/functional/list/list` | `@supersoniks/concorde/list` |
+| `sonic-queue` | `…/core/components/functional/queue/queue` | `@supersoniks/concorde/queue` |
+| UI (button, input, …) | `…/core/components/ui/…` ou relatif depuis `src/docs` | `@supersoniks/concorde/button`, etc. |
+| `@subscribe`, `@ancestorAttribute` | `@supersoniks/concorde/core/decorators/Subscriber` | — |
+| `DataProviderKey` | `@supersoniks/concorde/core/utils/dataProviderKey` | `@supersoniks/concorde/dataProviderKey` (alias doc seulement si configuré) |
+
+`@supersoniks/concorde/decorators` peut fonctionner (fichier `src/decorators.ts`) ; préférer quand même les chemins `core/…` dans `src/docs/example/**` pour cohérence.
+
+## Composants UI
+
+| Composant | ✅ Préférer | ❌ Éviter |
+|-----------|------------|----------|
+| Menu | `@supersoniks/concorde/menu` | `…/ui/menu` |
+| Menu item | `@supersoniks/concorde/menu-item` | `…/ui/menu-item` |
+| Divider | `@supersoniks/concorde/divider` | `…/ui/divider` |
+| Button | `@supersoniks/concorde/button` | `…/ui/button` |
+| Theme | `@supersoniks/concorde/theme` | `…/ui/theme` |
+| Scope | `@supersoniks/concorde/sonic-scope` | `…/functional/sonic-scope` |
+| Input | `@supersoniks/concorde/input` | `…/ui/form/input` |
+| Select | `@supersoniks/concorde/select` | `…/ui/form/select` |
+| Checkbox | `@supersoniks/concorde/checkbox` | `…/ui/form/checkbox` |
+
+## Composants fonctionnels
+
+| Composant | ✅ Préférer | ❌ Éviter |
+|-----------|------------|----------|
+| List | `@supersoniks/concorde/list` | `…/functional/list` |
+| Queue | `@supersoniks/concorde/queue` | `…/functional/queue` |
+| Router | `@supersoniks/concorde/router` | `…/core/components/functional/router/router` |
+| Fetch | `@supersoniks/concorde/fetch` | `…/functional/fetch` |
+| Value | `@supersoniks/concorde/value` | `…/functional/value` |
+
+## Utilitaires & types
+
+| Besoin | ✅ Préférer | ❌ Éviter |
+|--------|------------|----------|
+| Décorateurs | `@supersoniks/concorde/decorators` | chemins `…/core/decorators/…` |
+| Directives (`sub`) | `@supersoniks/concorde/directives` | — |
+| `get` / `set` / `dp` | `@supersoniks/concorde/utils` | `PublisherManager` |
+| `DataProviderKey` | `@supersoniks/concorde/dataProviderKey` | `…/core/utils/dataProviderKey` |
+| `Endpoint` | `@supersoniks/concorde/utils/endpoint` | `…/core/utils/endpoint` |
+| `APIConfiguration` | `@supersoniks/concorde/utils/api` | `…/core/utils/api` |
+| Vite config | `@supersoniks/concorde/vite-config` | — |
+
+## Exemples
+
+```typescript
+import "@supersoniks/concorde/menu";
+import "@supersoniks/concorde/menu-item";
+import "@supersoniks/concorde/divider";
+import "@supersoniks/concorde/button";
+import "@supersoniks/concorde/theme";
+import "@supersoniks/concorde/input";
+import "@supersoniks/concorde/list";
+import "@supersoniks/concorde/queue";
+import "@supersoniks/concorde/router";
+
+import { subscribe, handle, get } from "@supersoniks/concorde/decorators";
+import { sub } from "@supersoniks/concorde/directives";
+import { get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+```
+
+Side-effect imports (enregistrement custom elements) : toujours le chemin **composant** court ci-dessus.

package/ai/skills/concorde-menu/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: concorde-menu
+description: >-
+  Menus et navigation Concorde : sonic-menu, sonic-menu-item, sonic-divider.
+  Sidebar, sections, routes pushstate.
+---
+
+# Concorde — menus et navigation
+
+Référence doc : `node_modules/@supersoniks/concorde/src/core/components/ui/menu/menu.md`
+
+## Imports
+
+```typescript
+import "@supersoniks/concorde/menu";
+import "@supersoniks/concorde/divider";
+```
+
+## Structure type (navigation latérale)
+
+```html
+<nav aria-label="Navigation latérale">
+  <sonic-menu direction="column" align="left" size="sm" class="w-full">
+    <sonic-menu-item pushstate href="/" autoActive="strict">Accueil</sonic-menu-item>
+
+    <sonic-divider label="Section A" align="left" size="sm"></sonic-divider>
+    <sonic-menu-item pushstate href="/a/page" autoActive="strict">Page A</sonic-menu-item>
+
+    <sonic-divider label="Section B" align="left" size="sm"></sonic-divider>
+    <sonic-menu-item pushstate href="/b/page" autoActive="strict">Page B</sonic-menu-item>
+  </sonic-menu>
+</nav>
+```
+
+## Règles
+
+| Contexte | Composants |
+|----------|------------|
+| Liste de liens / nav | **`sonic-menu`** + **`sonic-menu-item`** |
+| Séparation de sections | **`sonic-divider`** avec `label` |
+| Liens internes (router Concorde) | `pushstate` + `href` sur **`sonic-menu-item`** |
+| Item actif | `autoActive="strict"` sur chaque item de route |
+
+## Interdits pour la navigation
+
+- **Ne pas** empiler des **`sonic-button`** ghost pour simuler un menu latéral.
+- **Ne pas** inventer des séparateurs custom quand **`sonic-divider`** suffit.
+- **Ne pas** oublier `pushstate` sur les liens internes.
+- **Ne pas** mettre `autoActive` sur le **`sonic-menu`** — c’est sur chaque **`sonic-menu-item`**.
+
+## Attributs utiles
+
+### sonic-menu
+
+`direction="column"`, `align="left"`, `size="sm"` pour une sidebar.
+
+### sonic-menu-item
+
+Hérite de **`sonic-button`** : `pushstate`, `href`, `autoActive`, `variant`.
+
+### sonic-divider
+
+`label`, `align="left"`, `size="sm"`.
+
+## Routes fichier
+
+Pas de **tirets** dans les noms de dossiers sous `routes/` — le générateur Concorde produit des identifiants JS invalides (`dpkey-dynamic` → erreur).
+
+## Checklist
+
+- [ ] `sonic-menu` englobe tous les items
+- [ ] Sections séparées par `sonic-divider` avec `label`
+- [ ] Chaque route : `pushstate` + `href` + `autoActive="strict"`
+- [ ] Imports `@supersoniks/concorde/menu`, `/menu-item`, `/divider` (pas `ui/…`)

package/ai/skills/concorde-scope/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: concorde-scope
+description: >-
+  Scope (sonic-scope) — inherited API, form, and icon defaults. Not UI.
+  APIConfiguration via attributes or DataProvider.
+---
+
+# Scope — configuration héritée
+
+**Scope** = defaults app-wide via `<sonic-scope>` (light DOM). Les descendants lisent les attributs ancêtres — pas de shadow root.
+
+```typescript
+import "@supersoniks/concorde/sonic-scope";
+```
+
+## Attributs courants
+
+| Zone | Attributs | Consommé par |
+|------|-----------|--------------|
+| API | `serviceURL`, `token`, `credentials`, `userName`, `password` | `@get`, `sonic-list`, `sonic-queue`, `sonic-submit` |
+| Forms | `formDataProvider`, `dataProvider`, `submitResultDataProvider` | champs form, `sonic-submit` |
+| Icons | `customIconLibraryPath`, `customIconDefaultPrefix` | `sonic-icon` `library="custom"` |
+
+## APIConfiguration
+
+Type : `@supersoniks/concorde/utils/api`.
+
+| Champ | Rôle |
+|-------|------|
+| `serviceURL` | URL de base API |
+| `token` | Bearer |
+| `userName` / `password` | Basic auth (si pas de token) |
+| `credentials` | Mode `fetch` (`omit`, `same-origin`, `include`) |
+| `authToken` | Refresh token (attribut scope : `eventsApiToken`) |
+| `tokenProvider` | Chemin pour obtenir un nouveau bearer |
+| `cache`, `blockUntilDone`, `keepAlive`, `addHTTPResponse` | Options avancées fetch |
+
+## Deux façons de configurer l’API
+
+**1. Scope** — attributs sur `<sonic-scope>` ou `<sonic-theme>` (API seulement sur scope recommandé) :
+
+```html
+<sonic-scope serviceURL="https://api.example.com" token="…">
+  …
+</sonic-scope>
+```
+
+```typescript
+@get(usersEndpoint) // pas de 2ᵉ arg — hérite serviceURL
+@state() data: ApiGetResult<Users> | null = null;
+```
+
+**2. DataProvider** — objet typé :
+
+```typescript
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+
+const apiKey = new DataProviderKey<APIConfiguration>("myApi");
+set(apiKey, { serviceURL: "https://api.example.com", credentials: "same-origin" });
+
+@get(usersEndpoint, apiKey)
+@state() data: ApiGetResult<Users> | null = null;
+```
+
+Les deux patterns peuvent coexister (scope pour l’URL par défaut, clé explicite quand nécessaire).
+
+## Séparation theme / scope
+
+- **Scope** → API, forms, icônes app-wide
+- **Theme** → couleurs, typo (`concorde-theme`) — **pas** `serviceURL`

package/ai/skills/concorde-theme/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: concorde-theme
+description: >-
+  sonic-theme — design tokens (colors, fonts, dark mode). Not API scope.
+---
+
+# Theme — design system
+
+`<sonic-theme>` définit la base visuelle Concorde. **Pas** pour l’API (`serviceURL` → scope, skill `concorde-scope`).
+
+```typescript
+import "@supersoniks/concorde/theme";
+```
+
+```html
+<sonic-theme background color font>
+  …app…
+</sonic-theme>
+
+<!-- dark -->
+<sonic-theme theme="dark" background color font>…</sonic-theme>
+```
+
+## Attributs
+
+| Attribut | Rôle |
+|----------|------|
+| `background` | Fond page / surface (`--sc-base`) |
+| `color` | Couleur texte (`--sc-base-content`) |
+| `font` | Famille / graisse (`--sc-font-family-base`) |
+| `theme="light"` \| `"dark"` | Palette built-in |
+
+## Variables CSS
+
+Override dans `:root` ou fichier CSS projet :
+
+- Surfaces : `--sc-base`, `--sc-base-content`, `--sc-base-50` … `--sc-base-900`
+- Sémantique : `--sc-primary`, `--sc-success`, `--sc-warning`, `--sc-danger`, `--sc-info` (+ `-content`)
+- Forme : `--sc-rounded`, `--sc-btn-rounded`, `--sc-border-width`
+- Typo : `--sc-font-family-base`, `--sc-headings-font-family`
+
+Doc composant : `node_modules/@supersoniks/concorde/src/core/components/ui/theme/`.
+
+Popovers, modals, toasts se montent sous le `<sonic-theme>` le plus proche.
+
+Palette generator : [concordecolors](https://delanfranchi.github.io/concordecolors/).

package/build-infos.json

@@ -1 +1 @@
-{"date":1779897585}
+{"date":1780500767}