@supersoniks/concorde 5.1.1 → 5.1.2

package/.agents/skills/concorde-docs/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: concorde-docs
+description: >-
+  Writes, edits and trims Concorde documentation pages (*.md rendered by the
+  doc site): component pages, decorator pages, concept and misc guides. Short,
+  sober, generic English with live <sonic-code> examples and one API table.
+  Use when creating, rewriting, uniformizing, shortening or removing a doc page,
+  touching src/docs/navigation/navigation.ts, or when asked to make the docs
+  "cleaner", "shorter" or "less project-specific".
+---
+
+# Concorde docs
+
+Concorde is a **public, generic** web-component library. The docs explain the library, nothing else. Write as if the reader has never heard of the company or its products.
+
+## Principles
+
+1. **Short.** One idea per section, 0–4 sentences before an example. Cut anything the example already shows.
+2. **Example first.** A live `<sonic-code>` beats a paragraph. Prose states defaults, constraints and gotchas, not what the reader can see.
+3. **Generic.** No product, client, team or internal process. Demo data follows the aviation theme (see [Demo data](#demo-data)).
+4. **One source of truth.** Link to the page that owns a topic instead of re-explaining it.
+5. **Current API only.** Document the recommended way. Do not keep "legacy" tutorials; a removed or deprecated API gets one line + a link to its replacement, or nothing.
+
+## Stay generic — never write
+
+- Company or product names and history (ticketing, "La Billetterie", "nearly 100 sites", …). The only allowed brand is the npm scope `@supersoniks/concorde`.
+- Ticket / issue references (`REDMINE-12345`, Jira keys), branch names, MR links.
+- Paths or code from consumer apps (`la-billetterie/…`, `src/<app>/components/…`), lists of impacted files, migration audits.
+- Event-ticketing vocabulary in examples: events, shows, venues, orders, tickets, accreditations, counters. Use the aviation theme instead (see [Demo data](#demo-data)).
+- Internal hosts, tokens, real API keys, back-office URLs. Live demos call the local mock API (see below).
+- "We", "our team", "at X we usually…". Address the integrator in the imperative: "Set `announce` when…".
+
+Migration notes for one consumer app belong in that app's repo, not here. If such content exists on a page, delete it or move it out (ask before moving).
+
+## Page types
+
+| Type | Location | Template |
+|------|----------|----------|
+| UI / functional component | `src/core/components/<ui\|functional>/<name>/<name>.md` | [templates/component.md](templates/component.md) |
+| Decorator / directive | `src/docs/decorators/*.md` · `src/docs/directives/*.md` | [templates/decorator.md](templates/decorator.md) |
+| Getting started / misc | `src/docs/getting-started/` · `src/docs/misc/` | [templates/guide.md](templates/guide.md) |
+
+Before writing, read the source (`.ts`: props, slots, defaults, events) and **one sibling page** of the same type. Match the sibling over inventing a layout.
+
+Canonical siblings: `ui/alert/alert.md`, `ui/badge/badge.md`, `decorators/subscribe.md`, `getting-started/dataFlow.md`.
+
+## Writing rules
+
+- **English** only. Present tense. No marketing ("powerful", "seamless", "very useful").
+- **Title**: `# Alert`, `# @subscribe`, `# Data flow`. No "Legacy:" prefixes, no ticket numbers.
+- **Intro**: one paragraph, 1–3 sentences: what it does, when to choose it, the 1–2 key APIs.
+- **Headings**: sentence case, one concern each (`## Size`, `## Dynamic path`). `##` then `###`, never skip.
+- **Defaults first**: "With no `status`, the alert is `default`."
+- **Inline code**: tags, attributes, props, types in backticks. Never chain backtick spans with commas (they render glued): use `/`, ` · ` or "and".
+- **Bold** for behaviour that prevents misuse, not for every noun.
+- **Tables** for reference data (attributes, slots, options, routes). Not for narrative.
+- **Callouts**: `<sonic-alert status="info|warning">` only for something the reader will get wrong otherwise. Max one per page.
+- No emoji in headings or links.
+- **No "Next step(s)" section.** The pager already links the previous / next page; the sidebar order in `navigation.ts` is the reading order. Fix the order there instead.
+
+## Examples
+
+HTML demo (rendered live, editable):
+
+```html
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-badge>Default</sonic-badge>
+      <sonic-badge type="primary">Primary</sonic-badge>
+    </div>
+  </template>
+</sonic-code>
+```
+
+TypeScript snippet (not executed): `<sonic-code language="typescript">`, escape `<` `>` as `&lt;` `&gt;` inside the template.
+
+Lit component demo: put the component in `src/docs/example/<name>.ts`, register it in `DOCS_LIT_DEMO_REGISTRY` (`src/docs/components/docs-demo-sources.ts`), import it in `src/docs/docs.ts`, then embed `<docs-lit-demo for="<tag>"></docs-lit-demo>`. Source and live render then stay in sync.
+
+- Show all enum values in **one** grid, not one section per value.
+- Realistic copy from the aviation theme. Lorem ipsum only to demo truncation.
+- Network demos use the local mock: `serviceURL="/docs-mock-api"` + a route from `misc/docs-mock-api.md`. Add a route there (and in `src/docs/mock-api/`) rather than calling a third-party API.
+- Component pages get their `import "@supersoniks/concorde/<name>"` line added automatically under the intro: do not write one.
+- Imports use public entry points: `@supersoniks/concorde/decorators`, `@supersoniks/concorde/dataProviderKey`, … never `../../core/…`.
+- Demo `.ts` files under `src/docs/example/` go through the Vite alias (`@supersoniks/concorde` → `src/`), not the package exports: use `@supersoniks/concorde/decorators` · `directives` · `dataProviderKey` · `endpoint` or `@supersoniks/concorde/core/utils/<x>`. `@supersoniks/concorde/utils/<x>` breaks the dev server (fine in `.md` snippets).
+
+## Demo data
+
+The library is named after Concorde: every example tells a small aviation story. Pick the closest fit:
+
+| Need | Aviation equivalent |
+|------|---------------------|
+| User / profile | passenger, pilot, crew member (`Ada Lindqvist`, `Captain Leo Marchand`) |
+| List / table rows | flights (`CN 001` · `CDG → JFK` · `Boarding` / `Delayed` / `Landed`), aircraft, airports (`CDG` · `JFK` · `LHR`) |
+| Form | check-in, flight search (from / to / date / cabin), crew sign-up |
+| Status / alert | flight status, gate change, weather warning, turbulence |
+| Numbers / progress | altitude, speed (Mach 2.04), fuel, boarding progress |
+| Cart / selection | cabin class, meal choice, extra baggage |
+| Menu / navigation | Departures · Arrivals · Fleet · Crew |
+| Images | photos in `public/img/concorde/` (see below) — never picsum or any hotlinked URL |
+
+- Keep it light: one aviation word per example is enough; the example must still read as generic UI.
+- No real flight bookings or prices presented as genuine.
+- Lists and filters: reuse the `/flights` mock (departures / arrivals, `on-time` · `boarding` · `delayed` · `landed` · `cancelled`) and the `docs-flight-board` demo component (`src/docs/example/docs-flight-demos.ts`). Other mock routes (users, cats…) can stay: relabel them only when you touch the demo anyway.
+
+### Images
+
+Use `img/concorde/plane_XX.jpg` (relative path, served from `public/`). Always set a meaningful `alt`.
+
+| File | Subject | Fits |
+|------|---------|------|
+| `plane_03.jpg` | Specifications board, black & white | square crops |
+| `plane_04.jpg` | Concorde on the apron, blue sky | square / card / rounded |
+| `plane_05.jpg` | Concorde behind a car park | wide |
+| `plane_06.jpg` | Ground crew and boarding stairs | wide |
+| `plane_07.jpg` | Crowd around Concorde at night | 3/2 · 16/9 |
+| `plane_09.jpg` | Person on the apron, Concorde behind | wide |
+| `plane_10.jpg` | Fleet parked in a star, aerial | cover / fullscreen |
+| `plane_11.jpg` | Concorde flying over a field | object-position demos |
+| `plane_12.jpg` | Concorde at the gate, black & white | 16/9 · modal |
+| `plane_13.jpg` | Technicians on a wing structure | wide |
+| `plane_01.jpg` | Spectators on a terrace watching Concorde | wide |
+| `plane_02.jpg` | Nose above the boarding stairs (~4 MB: avoid in grids) | portrait-ish |
+| `plane_08.jpg` | Concorde in front of a hangar, with a car | wide |
+
+## Links
+
+- Internal link format: `[Data flow](/docs/getting-started/dataFlow)` — same path as under `src/` without `.md`. Components drop the trailing duplicate: `/core/components/ui/button` (source `…/button/button.md`).
+- Same pathnames serve SPA (browser), static HTML (crawlers), and Markdown (`….md` or `Accept: text/markdown`). Do not link `/…/button/button`.
+- Link the first mention of a concept that has its own page, not every mention.
+- Never link to source files of consumer apps or internal tools.
+
+## Adding, renaming or removing a page
+
+1. Edit `src/docs/navigation/navigation.ts` (sidebar order; strings are section titles).
+2. `grep -rn "<file>.md" src docs ai` and fix or drop every link to it.
+3. Regenerate search: `node scripts/create-search.js` (also runs on `yarn dev`).
+4. Component pages: the Components index (`docs-components-index`) reads the nav, nothing else to do.
+
+## Shortening an existing page
+
+Cut, in this order: repeated explanations of a linked concept → prose restating the example → "why we built it" history → alternative ways to do the same thing → edge cases nobody hits. Keep working examples untouched unless they are wrong or project-specific.
+
+## Checklist
+
+- [ ] Nothing company-, product- or ticket-specific; demo data uses the aviation theme
+- [ ] Title + one-paragraph intro
+- [ ] Each `##` section has an example, or is a short note under one
+- [ ] Defaults and required attributes stated
+- [ ] Exactly one `## API reference`, last, matching the source
+- [ ] No comma-chained inline code
+- [ ] Links resolve; nav and search updated if pages moved
+- [ ] Page is shorter than before, or every added line earns its place

package/.agents/skills/{concorde-component-docs/template.md → concorde-docs/templates/component.md}

@@ -1,6 +1,6 @@
 # ComponentName
 
-One paragraph: what **`sonic-component`** does, when to use it instead of alternatives, and the most important `` `attributes` `` / slots. Mention defaults only if they prevent mistakes.
+One paragraph: what **`sonic-component`** does, when to use it instead of alternatives, and the key attributes / slots. Mention defaults only if they prevent mistakes.
 
 ## Basic example
 
@@ -25,7 +25,7 @@ Short explanation of default and allowed values.
 
 ## Accessibility
 
-When screen readers or keyboard users need special handling.
+Only when screen readers or keyboard users need special handling. Otherwise drop this section.
 
 <sonic-code>
   <template>
@@ -43,3 +43,7 @@ When screen readers or keyboard users need special handling.
 |------|-------------|
 | *(default)* | Primary content |
 | `named` | Optional slot purpose |
+
+If the component has no slots, replace the slots table with one line: "No slots."
+
+Values: list literals with ` · ` (`sm` · `md` · `lg`) or a range with `…` (`2xs` … `2xl`), never commas between backtick spans.

package/.agents/skills/concorde-docs/templates/decorator.md

@@ -0,0 +1,43 @@
+# @decoratorName
+
+One paragraph: what it keeps in sync or triggers, on which property/method, and the key argument (`DataProviderKey`, `Endpoint`, …). Link the owning concept once ([Data flow](#docs/getting-started/dataFlow.md/dataFlow)).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { decoratorName } from "@supersoniks/concorde/decorators";
+
+@decoratorName(key)
+@state()
+value: Type | null = null;
+  </template>
+</sonic-code>
+
+## Basic usage
+
+One sentence on the default behaviour.
+
+<docs-lit-demo for="docs-decorator-name-demo"></docs-lit-demo>
+
+## Option or variant
+
+What changes, and the default.
+
+<sonic-code language="typescript">
+  <template>
+@decoratorName(key, { option: true })
+  </template>
+</sonic-code>
+
+## Notes
+
+- Lifecycle constraint (when it runs, when it stops)
+- Interaction with sibling decorators — link, don't re-explain
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` | `DataProviderKey<T>` | Path to read |
+| `options.option` | `boolean` (default `false`) | Behaviour in one line |

package/.agents/skills/concorde-docs/templates/guide.md

@@ -0,0 +1,25 @@
+# Topic
+
+One paragraph: the problem this page solves and the recommended approach. No history, no "why we built it".
+
+## Minimal example
+
+<sonic-code language="typescript">
+  <template>
+// smallest working code
+  </template>
+</sonic-code>
+
+## Step or concept
+
+Two to four sentences, then an example. Link pages that own sub-topics instead of repeating them.
+
+## Reference
+
+| Item | Role |
+|------|------|
+| `thing` | One line |
+
+## See also
+
+- [Related page](#docs/getting-started/dataFlow.md/dataFlow)