@supersoniks/concorde 4.8.0 → 4.9.1

package/docs/src/docs/_getting-started/create-a-component.md

@@ -0,0 +1,139 @@
+# Creating components
+
+> **New app components:** start with [My first component](#docs/_getting-started/my-first-component.md/my-first-component) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). The `Subscriber` mixin below is [legacy](#docs/_core-concept/subscriber.md/subscriber).
+
+## Where to put it?
+
+In this document, we consider the src directory of the project as the root.<br>
+We describe how we organize our components as an example, however it depends on your project.
+
+In concorde each component is currently organized in the following directory structure (at least we try):
+
+- **/core/components/functional/component-name/component-name.ts**  
+  Generic/functional/generally unstyled component.
+  The component usually doesn't use any other concrete components.
+- **/core/components/ui/component-name/component-name.ts**  
+  Generic but UI-oriented component.
+  The component usually only uses generic components and other UI components.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  The component is intended to have a concrete usage within our ticketing system **"la-billetterie"**.
+  It usually only uses generic components from `core` and possibly other atoms.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  The component has a specific destination: (event / cart / gift card): `/components/destination/`
+  The component uses various components, usually from the `/components/atoms` directory.
+  It does not use components at the same level in the file hierarchy.
+
+## Starting from a Simple Model
+
+You can copy `example.ts` from the source to the desired destination to start with.
+This file contains a web component in the form of a class that extends the `Subscriber` mixin, with a reactive property and a render function.
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
+
+@customElement("sonic-example")
+export class SonicComponent extends Subscriber(LitElement) {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+**You can remove the dependency on `Subscriber`** if automatic population of the component with external data is not required.
+For example, for a UI component:
+
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("sonic-example")
+export class SonicComponent extends LitElement {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+Regarding `Subscriber`, see:
+
+- [🔔 Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+- [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)
+
+### Naming the Component
+
+The class name is not necessarily important. However, it is important to **give it a component name prefixed with "sonic"** (or a prefix of your own) using the dedicated metadata already present in the copied document. For example, a button component would be named as follows:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-button")
+  </template>
+</sonic-code>
+
+For less generic components with a specific destination, we advise to include the destination in the name.
+For example, for a "title" component in the "event" destination, the name would be simply:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-event-title")
+  </template>
+</sonic-code>
+
+
+## Modifying It
+
+#### Creating Reactive Properties and Modifying the Render Function
+
+To do this, study the functioning of https://lit.dev and also refer to [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
+
+#### HTML Structure of a Component
+
+The HTML structure of a component should remain as simple as possible.
+
+Ideally, there should be only one additional level of elements in addition to slots.
+
+- **The main component is already a wrapper**.
+  It receives classes to manage its layout, but it should not style internal elements.
+- **Slots handle the visual organization** of elements.
+- **The specificity of the component is expressed in this additional level** by adding a list, a functional native element (e.g., button), or another component.
+
+This leads to the creation of more components and thus raises questions about the hierarchical organization of files. However, this tends to atomize their roles.
+
+## Referencing It
+
+To compile the component, it needs to be referenced somewhere through an import statement. In particular, it is important to reference it in any component that uses it.
+
+In the case where it can be directly used in a page, it should also be globally referenced, especially considering the creation of **specific bundles** in the future.
+
+Here's where we add imports based on the component's location inside concorde as an example
+
+- **/core/components/functional/component-name/component-name.ts**  
+  In `/core/components/functional/functional.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **/core/components/ui/component-name/component-name.ts**  
+  In `/core/components/ui/ui.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  Nowhere else but where it will be used, except for possible **temporary** tests, for example, in `index.ts`.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  In `la-billetterie/components/concrete-destination/destination-concrete.ts`. 
+  If it's a new destination, you'll need to create the corresponding import .ts file and import it in `la-billetterie.ts`.
+
+## Using It
+
+As a reminder, the component is simply integrated into the context by adding a tag with the component's name, for example:
+
+
+<sonic-code language="html">
+  <template>
+<sonic-event-title></sonic-event-title>
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/my-first-component.md

@@ -0,0 +1,236 @@
+# My first component
+
+Build a **Lit** user card with Tailwind and Concorde UI, then connect it to the **DataProvider** store: declare the **data configuration** (type, key, scope), and let **`@subscribe`** keep the card in sync.
+
+> Legacy approach with the **Subscriber mixin**: [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber).
+
+## 1. Lit component + Tailwind
+
+Export Tailwind once (e.g. `src/docs/tailwind.ts` in this repo):
+
+<sonic-code language="typescript">
+  <template>
+import { css, unsafeCSS } from "lit";
+import tailwindImport from "./css/tailwind.css?inline";
+
+export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+User card — plain Lit properties and UI components (no store yet):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String }) first_name = "";
+  @property({ type: String }) last_name = "";
+  @property({ type: String }) email = "";
+  @property({ type: String }) avatar = "";
+
+  render() {
+    return html`&lt;div class="flex items-center gap-3 rounded-md p-2"&gt;
+      &lt;sonic-image src=${this.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;
+        &lt;div&gt;${this.first_name} &lt;span class="font-bold"&gt;${this.last_name}&lt;/span&gt;&lt;/div&gt;
+        &lt;div class="text-sm text-neutral-400"&gt;${this.email}&lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+## 2. Data configuration
+
+The card does not hard-code user fields anymore. You declare **what** is stored, **where** it lives, and **which ancestor scope** applies — then `@subscribe` mirrors that object on the component.
+
+### Type — shape of the data
+
+`DocsUserData` documents the fields you expect at this scope (first name, email, avatar, …). TypeScript checks that `user` matches that shape.
+
+<sonic-code language="typescript">
+  <template>
+export type DocsUserData = {
+  first_name: string;
+  last_name: string;
+  email: string;
+  avatar: string;
+};
+  </template>
+</sonic-code>
+
+### Key — path in the DataProvider
+
+`docsUserRowKey` points at the store segment to read. The path `"${dataProvider}"` is resolved at runtime from a property on the component (see scope below).
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+
+export const docsUserRowKey = new DataProviderKey&lt;
+  DocsUserData,
+  { dataProvider: string | null }
+&gt;("${dataProvider}");
+  </template>
+</sonic-code>
+
+The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+### Scope — which store segment applies
+
+A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+### Subscribe — keep the card in sync
+
+[`@subscribe`](#docs/_decorators/subscribe.md/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import {
+  ancestorAttribute,
+  subscribe,
+} from "@supersoniks/concorde/core/decorators/Subscriber";
+import { docsUserRowKey, type DocsUserData } from "./users";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @subscribe(docsUserRowKey)
+  @state()
+  user: DocsUserData | null = null;
+
+  render() {
+    const u = this.user;
+    if (!u) return nothing;
+    return html`&lt;div class="flex items-center gap-3 rounded-md p-2"&gt;
+      &lt;sonic-image src=${u.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;
+        &lt;div&gt;${u.first_name} &lt;span class="font-bold"&gt;${u.last_name}&lt;/span&gt;&lt;/div&gt;
+        &lt;div class="text-sm text-neutral-400"&gt;${u.email}&lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+Live code: `src/docs/example/users.ts`. In this repo, imports use **`core/…` paths** (short `@supersoniks/concorde/…` exports apply in **consumer apps** only).
+
+### Two scopes, one component
+
+The same `docs-user` is mounted twice. Each copy inherits a **different** nearest `dataProvider` — that is the row/list **scope**:
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="docs-user-two-scopes"></docs-demo-sources>
+    <docs-user-two-scopes></docs-user-two-scopes>
+  </template>
+</sonic-code>
+
+Markup (two isolated stores; keys from `docs-provider-keys.ts`):
+
+<sonic-code language="markup">
+  <template>
+    &lt;div class="grid md:grid-cols-2 gap-6"&gt;
+      &lt;div dataProvider="${docsUserScopeAKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+      &lt;div dataProvider="${docsUserScopeBKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+  </template>
+</sonic-code>
+
+Seeded in `docs-provider-keys.ts` (`set(docsUserScopeAKey, …)`): **Paul** / **Marie**. Without `@ancestorAttribute`, both cards would not know which store to read.
+
+## 3. Fetch users — `sonic-list` with `.items`
+
+Use a Lit parent and the **`items`** renderer (not HTML `<template>` children). The callback receives each row object from fetch — render fields directly (`${item.first_name}`, …), like porting a template that used `data-bind` / `<sonic-value>`.
+
+<sonic-code>
+  <template>
+      <docs-lit-demo for="docs-users-list"></docs-lit-demo>
+  </template>
+</sonic-code>
+
+Wrapper (`docs-users-list.ts`):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import "../../core/components/functional/list/list";
+import "./users";
+
+@customElement("docs-users-list")
+export class DocsUsersList extends LitElement {
+  private items = ({ first_name, last_name, email, avatar }) => html`
+    &lt;div class="flex gap-3"&gt;
+      &lt;sonic-image src=${avatar} ...&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;${first_name} &lt;b&gt;${last_name}&lt;/b&gt;&lt;/div&gt;
+      &lt;div class="text-sm text-neutral-400"&gt;${email}&lt;/div&gt;
+    &lt;/div&gt;
+  `;
+
+  render() {
+    return html`
+      &lt;sonic-list fetch dataProvider=${usersListEndpoint.path} key="data" .items=${this.items}&gt;&lt;/sonic-list&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+See [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) for `serviceURL="/docs-mock-api"`.
+
+## 4. Form preview with `formDataProvider`
+
+Edit fields in a form; the card follows the same `docsUserRowKey` when the preview host sets `dataProvider="userPreview"`.
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-1 gap-4 max-w-xl">
+      <form formDataProvider="${docsUserPreviewKey.path}" class="grid grid-cols-2 gap-3">
+        <sonic-input label="First name" name="first_name" value="Paul" size="sm"></sonic-input>
+        <sonic-input label="Last name" name="last_name" value="Metrand" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Email" name="email" value="paul@example.com" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Avatar URL" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
+      </form>
+      <sonic-divider align="left">Preview</sonic-divider>
+      <div dataProvider="${docsUserPreviewKey.path}">
+        <docs-user></docs-user>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)).
+
+## Next steps
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — full map
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed paths and host constraints
+- [@subscribe](#docs/_decorators/subscribe.md/subscribe) / [sub()](#docs/_directives/sub.md/sub) — read-only in templates
+- [List](#core/components/functional/list/list.md/list) — `.items`, `.noItems`, `.skeleton`

package/docs/src/docs/_getting-started/my-first-subscriber.md

@@ -0,0 +1,120 @@
+# Legacy: My first subscriber component
+
+> **New projects:** use [My first component](#docs/_getting-started/my-first-component.md/my-first-component) (`@ancestorAttribute`, `@subscribe` + `DataProviderKey`, `.items` on lists) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). This page documents the **Subscriber mixin** used by older apps and core components.
+
+Learn how to build a component with the **Subscriber** mixin, styled with Tailwind, filled from a DataProvider via automatic property mapping.
+
+## Create a classic lit component
+
+<sonic-code language="javascript" >
+  <template>
+  import { html, LitElement, nothing } from "lit";
+  import { customElement, property } from "lit/decorators.js";
+  @customElement("docs-user")
+  export class user extends LitElement {
+    @property({ type: String }) first_name = "";
+    @property({ type: String }) last_name = "";
+    @property({ type: String }) avatar = "";
+    @property({ type: String }) email = "";
+    render() {
+      return html`
+        &lt;img src="${this.avatar}" /&gt; &lt;br&gt;
+        ${this.first_name} ${this.last_name} &lt;br&gt;
+        ${this.email}`;
+    }
+  }
+  </template>
+</sonic-code>
+
+### Style with tailwind and ui components
+
+<sonic-code language="javascript">
+  <template>
+  import { css, unsafeCSS } from "lit";
+  import tailwindImport from "./css/tailwind.css?inline";
+  export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+    import { html, LitElement } from "lit";
+    import { customElement, property } from "lit/decorators.js";
+    import { tailwind } from "../tailwind";
+    import '@supersoniks/concode/ui/image'
+    import '@supersoniks/concode/ui/button'
+    import '@supersoniks/concode/ui/icon'
+    @customElement("docs-user")
+    export class user extends LitElement {
+      static styles = [tailwind];
+      @property({ type: String }) first_name = "";
+      @property({ type: String }) last_name = "";
+      @property({ type: String }) avatar = "";
+      @property({ type: String }) email = "";
+      render() {
+        return html`&lt;div class="flex items-center gap-3 p-2"&gt;
+          &lt;sonic-image src=${this.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+          &lt;div&gt;${this.first_name} &lt;span class="font-bold"&gt;${this.last_name}&lt;/span&gt;&lt;/div&gt;
+          &lt;div class="text-sm text-neutral-400"&gt;${this.email}&lt;/div&gt;
+        &lt;/div&gt;`;
+      }
+    }
+  </template>
+</sonic-code>
+
+## Add Subscriber mixin
+
+<sonic-code language="javascript">
+  <template>
+    import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
+    @customElement("docs-user")
+    export class user extends Subscriber(LitElement) {
+      // properties auto-filled from DataProvider when names match
+    }
+  </template>
+</sonic-code>
+
+See [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber).
+
+## Autofill from a dataProvider
+
+<sonic-code >
+<template>
+<docs-demo-sources for="list-users-fetch"></docs-demo-sources>
+<div serviceURL="/docs-mock-api">
+<sonic-fetch 
+    serviceURL="/docs-mock-api"
+    dataProvider="api/users/3" 
+    key="data">
+     <docs-user></docs-user>
+</sonic-fetch>
+</div>
+</template>
+</sonic-code>
+
+<sonic-code >
+<template>
+<sonic-fetch 
+    serviceURL="/docs-mock-api"
+    dataProvider="api/users/2" 
+    key="data"></sonic-fetch>
+<docs-user dataProvider="api/users/2" ></docs-user>
+</template>
+</sonic-code>
+
+<sonic-code >
+<template>
+<div class="grid grid-cols-1 gap-4">
+<form formDataProvider="userPreview" class="grid grid-cols-4 gap-3" >
+  <sonic-input label="First name" type="text" name="first_name" value="Paul" size="sm"></sonic-input>
+  <sonic-input label="Last name" type="text" name="last_name" value="Metrand" size="sm"></sonic-input>
+  <sonic-input class="col-span-2" label="email" type="text" name="email" value="paul@example.com" size="sm"></sonic-input>
+  <sonic-input label="Image url" type="text" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
+</form>
+<sonic-divider align="left">Preview before submit</sonic-divider>
+<div dataProvider="userPreview">
+  <docs-user></docs-user>
+</div>
+</div>
+</template>
+</sonic-code>

package/docs/src/docs/_getting-started/pubsub.md

@@ -0,0 +1,37 @@
+# Legacy: Sharing data
+
+> **New apps:** [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`get` / `set` / `DataProviderKey`, decorators). This page documents the historical **Publisher** proxy API (`PublisherManager`, `publisher.set`, `onAssign`, …).
+
+This section describes how data is shared between graphical and non-graphical components.
+
+Graphical components should not reference each other directly — they stay decoupled via a **publish/subscribe** store.
+
+## The Publisher
+
+### Principle
+
+* The **publisher** is a [JavaScript proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that holds data.<br>
+  Example: `{foo:{hello:["world"]}, bar:"baz"}`
+
+* Accessing a property (`myPublisher.foo.hello`) returns another **publisher** for that segment.
+
+* Missing properties create a publisher with internal data `null`, filled later.
+
+* **Subscribers** listen via `onAssign`, `onInternalMutation`, template filling on the **Subscriber mixin**, etc.
+
+* Updates use `publisher.set(...)` or nested assignment; changes propagate to subscribers.
+
+❇️ Order of creation vs subscription theoretically does not matter.
+
+### Methods
+
+* **set** — replace internal value  
+  <sonic-code language="javascript"><template>publisher.set({foo:{hello:["world"]}, bar:"baz"});</template></sonic-code>
+
+* **get** — read internal value  
+  <sonic-code language="javascript"><template>publisher.get()</template></sonic-code>
+
+* **onAssign / offAssign** — react to `set`  
+  <sonic-code language="javascript"><template>publisher.a.b.onAssign(console.log);</template></sonic-code>
+
+Modern equivalent: `get` / `set` / `@handle` — see [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).

package/docs/src/docs/_getting-started/start.md

@@ -0,0 +1,47 @@
+# Introduction
+
+## What is Concorde?
+
+Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of web components for shared apps and websites.  
+Build UIs without tying components to a specific host stack, while keeping visual consistency through a small set of CSS variables.
+
+## Why and use case
+
+In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.  
+One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.
+
+### Stack
+
+* Lit
+* TypeScript
+* Vite
+* Tailwind (starter kit, not required in the core package)
+
+### Functional features
+
+* **DataProvider** store (decorators, `get` / `set`)
+* Forms (`formDataProvider`)
+* Lists, queues, lazy loading
+* Router, states, UI kit with status variants
+
+## Learn Concorde
+
+| Step | Page |
+|------|------|
+| 1 | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — Lit card, `@ancestorAttribute`, `@bind`, mock API |
+| 2 | [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — Core concepts: decorators and APIs |
+| 3 | [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL` for this site (Misc) |
+| 4 | [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) — **recommended** project kit (Vite, Tailwind, `yarn ai:sync`) |
+| 5 | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `AGENTS.md`, Cursor / JetBrains rules |
+
+Legacy (Subscriber mixin, Publisher API): **Legacy** section at the bottom of the sidebar.
+
+## Start a new project
+
+<sonic-code language="bash">
+  <template>
+npx @supersoniks/create-concorde-ts-starter "project_name"
+  </template>
+</sonic-code>
+
+The starter runs **`yarn ai:sync`** for you. Details: [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents). Manual Vite setup: [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install).

package/docs/src/docs/_getting-started/theming.md

@@ -0,0 +1,91 @@
+# Adding styles
+
+## Normal Behavior
+
+No style crosses the shadow root of a component, except for inheritable properties (which have the "inherit" property possible) and CSS variables.
+Properties integrated via a "[slot](https://developer.mozilla.org/en/docs/Web/HTML/Element/slot)" remain stylizable in a conventional way.
+
+- **During creation / from the inside:**
+  - We edit the [static "styles" property of the lit component](https://lit.dev/docs/components/styles/), which can also reference shared and dynamic styles.
+    These styles are scoped and do not impact the outside.
+  - We use CSS variables as the value of properties intended to be customized from the outside.
+    For each variable, we define a default value to have a simple but consistent base style.
+  - We only rewrite inheritable properties with hard values if they are truly specific to the component.
+  - The `<style>` tag as a direct child can be used as a last resort, especially if there is a need for particularly dynamic customization. Performance is reduced.
+- **During use / from the outside:**
+  We define values for **inheritable CSS properties** (e.g., font-\_, color...) using tools like Tailwind.
+  We modify the value of **CSS variables** used by the component.
+
+## Choosing Style Presets via Reactive Properties:
+
+The declaration of reactive properties is useful for selecting a particular configuration that mostly affects a set of properties.
+
+For example, a `size` property (xs, sm, md, xl) will affect margins, font, line heights to align them with the corresponding CSS vars, which can be customized using the methods mentioned earlier if necessary.
+
+It is recommended to use the `{reflect: true}` property for reactive properties that have an associated style on the `:host()`. For example: `:host([type='primary']){...}`
+
+☢️ **Caution:** Passing class names via reactive properties / HTML attributes of the component should be avoided as it can quickly lead to difficult-to-manage situations.
+
+#### CSS "display" Property
+
+By default, the display property is `inline`.
+Therefore, be careful to define it according to the needs, as one might mistakenly expect it to be `block` as with a regular `<div>`.
+
+☢️ **Caution:** Defining the `display` property as `contents` may seem attractive at first, but:
+
+- It almost always leads to the creation of wrappers to style the content (instead of using `:host`).
+- It is no longer possible to directly add classes to the component or style it from the outside.
+  Ultimately, the amount of code to write increases significantly.
+
+## TAILWIND Functional Classes
+
+[tailwind](https://tailwindcss.com/) has been integrated into Concorde and is available in scoped components (with Shadow DOM).
+To use it, you need to import the following:
+
+<sonic-code language="javascript">
+  <template>
+import { tailwind } from "@supersoniks/concorde/la-billetterie/ui/theme/theme";
+  </template>
+</sonic-code>
+
+Then include the `tailwind` style in the static `styles` property of the component:
+
+<sonic-code language="javascript">
+  <template>
+static styles = [tailwind];
+  </template>
+</sonic-code>
+
+Finally, use it in the HTML within the render function:
+
+<sonic-code language="html">
+  <template>
+<p class="m-2">A paragraph with margin</p>
+  </template>
+</sonic-code>
+
+The colors from Concorde's theme are referenced in Tailwind's theme.
+
+## Operation without Shadow DOM
+
+### Usefulness
+
+This operation is particularly useful when it comes to **adding behavior to a simple existing element**.
+It may also become necessary to establish **compatibility with a traditional JS library**.
+
+For example, with a text input:
+
+- Trigger automatic data or filter update when typing text.
+- Automatic formatting.
+- Constraints that cannot be handled by native methods.
+
+### Consequences
+
+If there is no shadow DOM (see the **noShadowDom** property of **Subscriber**):
+
+- Styling using the static "styles" property of the lit component will not be applied.
+- The element and its content can be styled in a traditional manner.
+
+For example, the components `queue`, `list`, and `fetch` do not have a shadow DOM.
+
+ℹ️ **Note:** Specifically in this case, it may be useful to set the `display` property to `contents`.