@supersoniks/concorde 5.0.5 → 5.1.0

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

@@ -1,253 +1,91 @@
-# Customization
+# Adding styles
 
-## Theme-first customization
+## Normal Behavior
 
-Concorde components ship with **default styles** (fallback values in each component and in `<sonic-theme>`).  
-You do not need to define any CSS variables to get a usable UI.
+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.
 
-To align the kit with your brand, override **only the essential theme tokens** on `<sonic-theme>`, on `:root`, or in a project stylesheet.  
-Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—**do not copy long lists of derived variables** unless you have a specific need.
+- **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.
 
-<sonic-code language="html">
-  <template>
-<sonic-theme color font class="block bg-base min-h-screen">
-  <!-- your app -->
-</sonic-theme>
-  </template>
-</sonic-code>
-
-<sonic-code language="javascript">
-  <template>
-import "@supersoniks/concorde/theme";
-  </template>
-</sonic-code>
-
-| Attribute | Effect |
-|-----------|--------|
-| *(omit)* \| `theme="custom"` | Default: core tokens + your `--sc-*`; no built-in light/dark palette |
-| `theme="light"` \| `"dark"` \| `"auto"` | Opt-in presets; `auto` follows `prefers-color-scheme` |
-| `class="bg-base block"` (Tailwind) | Page/surface background (`--sc-base`) |
-| `color` | Text color (`--sc-base-content`) |
-| `font` | Base font family/weight (`--sc-font-family-base`, etc.) |
-
-Popovers, modals, and toasts mount under the nearest `<sonic-theme>`.
-
-## Customization example
-
-Example (full brand override on `<sonic-theme>` or `:root`). Set every essential token below; derived radii and shadows still come from the theme engine—only `--sc-rounded` is listed here.
-
-<sonic-code language="css">
-  <template>
-sonic-theme {
-  /* Semantic fills */
-  --sc-primary: #353429;
-  --sc-secondary: #f43f5e;
-  --sc-info: #7c3aed;
-  --sc-danger: #d71839;
-  --sc-warning: #f97316;
-  --sc-success: #10b981;
-  --sc-contrast: #111;
-
-  /* Text/icons on semantic fills */
-  --sc-primary-content: #fff;
-  --sc-secondary-content: #fff;
-  --sc-info-content: #fff;
-  --sc-danger-content: #fff;
-  --sc-warning-content: #fff;
-  --sc-success-content: #fff;
-  --sc-contrast-content: #fff;
-
-  /* Neutral fills */
-  --sc-base: #fff;
-  --sc-base-50: #f6f6f5;
-  --sc-base-100: #ededec;
-  --sc-base-200: #d7d7d4;
-  --sc-base-300: #c8c7c4;
-  --sc-base-400: #a8a7a2;
-  --sc-base-500: #94938c;
-  --sc-base-600: #76756c;
-  --sc-base-700: #59584e;
-  --sc-base-800: #47463b;
-  --sc-base-900: #353429;
-
-  /* Text/icons on neutral surfaces */
-  --sc-base-content: var(--sc-base-900);
-
-  /* Typography */
-  --sc-font-family-base: "Oswald", system-ui, -apple-system, "Segoe UI", Roboto,
-    "Helvetica Neue", Arial, sans-serif;
-  --sc-headings-font-family: "alternate-gothic-compressed", system-ui, sans-serif;
-  --sc-headings-line-height: 1.1;
-  --sc-headings-font-weight: bold;
-  --sc-headings-text-transform: none;
-
-  /* Shape (primitive only) */
-  --sc-rounded: 0;
-
-  /* Forms */
-  --sc-border-width: 0.2rem;
-  --sc-form-height: 2em;
-  --sc-input-bg: var(--sc-base);
-  --sc-input-color: var(--sc-base-content);
-  --sc-input-border-color: var(--sc-input-color);
-  --sc-input-active-bg: var(--sc-primary);
-  --sc-input-active-color: var(--sc-primary-content);
-  --sc-input-active-border-color: var(--sc-primary);
-}
-  </template>
-</sonic-code>
-
-<sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button>
+## 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.
 
-**Without these overrides**, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set `theme="light"`, `theme="dark"`, or `theme="auto"`.
+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.
 
-**What we intentionally avoid:** large public `--sc-alert-*` / `--sc-badge-*` APIs or `::part()` styling hooks on most components. Prefer attributes (`type`, `status`, `size`, …) and the theme tokens above.
+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.
 
-## Only essential CSS variables (public theme API)
+#### CSS "display" Property
 
-These are the **smallest set** we recommend customizing. Everything else should stay internal to the theme or to components (`--sc_*` private variables, attributes like `type`, `size`, `variant`).
+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>`.
 
-### Surfaces and foreground
+☢️ **Caution:** Defining the `display` property as `contents` may seem attractive at first, but:
 
-Tokens **without** a `-content` suffix are **fill / background** colors.  
-Tokens **with** `-content` are **text and icons** on top of the matching fill (solid buttons, badges, alerts, etc.).
+- 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.
 
-#### Neutral fills
+## TAILWIND Functional Classes
 
-| Variable | Role |
-|----------|------|
-| `--sc-base` | Main surface / page background |
-| `--sc-base-50` … `--sc-base-900` | Neutral scale (borders, subtle backgrounds, muted UI) |
+[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:
 
-#### Neutral foreground
-
-| Variable | Role |
-|----------|------|
-| `--sc-base-content` | Default body text and icons on neutral surfaces |
-
-#### Semantic fills
+<sonic-code language="javascript">
+  <template>
+import { tailwind } from "@supersoniks/concorde/la-billetterie/ui/theme/theme";
+  </template>
+</sonic-code>
 
-| Variable | Role |
-|----------|------|
-| `--sc-primary` | Primary actions, links, emphasis |
-| `--sc-secondary` | Secondary brand accent (when used) |
-| `--sc-info`, `--sc-success`, `--sc-warning`, `--sc-danger` | Status and feedback |
-| `--sc-contrast` | High-contrast fills (e.g. on media) |
+Then include the `tailwind` style in the static `styles` property of the component:
 
-#### Semantic foreground
+<sonic-code language="javascript">
+  <template>
+static styles = [tailwind];
+  </template>
+</sonic-code>
 
-| Variable | Role |
-|----------|------|
-| `--sc-primary-content`, `--sc-secondary-content`, … | Text/icons on the matching semantic **fill** (`--sc-primary`, etc.) |
+Finally, use it in the HTML within the render function:
 
-### Shape
+<sonic-code language="html">
+  <template>
+<p class="m-2">A paragraph with margin</p>
+  </template>
+</sonic-code>
 
-| Variable | Role |
-|----------|------|
-| `--sc-rounded` | **Single primitive** corner radius; the theme computes `--sc-rounded-sm`, `--sc-btn-rounded`, `--sc-input-rounded`, etc. |
+The colors from Concorde's theme are referenced in Tailwind's theme.
 
-### Typography
+## Operation without Shadow DOM
 
-| Variable | Role |
-|----------|------|
-| `--sc-font-family-base` | Body UI text |
-| `--sc-font-weight-base`, `--sc-font-style-base` | Optional |
-| `--sc-headings-font-family`, `--sc-headings-line-height`, `--sc-headings-font-weight`, `--sc-headings-text-transform` | Headings (modal titles, etc.) |
+### Usefulness
 
-### Forms (only if you customize inputs globally)
+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**.
 
-Interactive controls expose a few extra **theme-level** tokens; prefer these over styling individual inputs from outside.
+For example, with a text input:
 
-| Variable | Role |
-|----------|------|
-| `--sc-border-width` | Default border thickness |
-| `--sc-form-height` | Control height |
-| `--sc-input-bg`, `--sc-input-color`, `--sc-input-border-color` | Default field chrome |
-| `--sc-input-active-bg`, `--sc-input-active-color`, `--sc-input-active-border-color` | Focus/active state |
+- Trigger automatic data or filter update when typing text.
+- Automatic formatting.
+- Constraints that cannot be handled by native methods.
 
----
+### Consequences
 
-## Tailwind in new components ?
+If there is no shadow DOM (see the **noShadowDom** property of **Subscriber**):
 
-Set <code>tailwind.config.js</code> to match concorde style token in your custom component.
+- 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.
 
-<sonic-code language="js">
-  <template>
-...
-theme: {
-  borderRadius: {
-    DEFAULT: "var(--sc-rounded)",
-    none: "0",
-    sm: "var(--sc-rounded-sm)",
-    md: "var(--sc-rounded-md)",
-    lg: "var(--sc-rounded-lg)",
-    xl: "var(--sc-rounded-xl)",
-    full: "9999px",
-  },
-  boxShadow: {
-    DEFAULT: "var(--sc-shadow)",
-    none: "none",
-    sm: "var(--sc-shadow-sm)",
-    md: "var(--sc-shadow-md)",
-    lg: "var(--sc-shadow-lg)",
-    xl: "var(--sc-shadow-xl)",
-  },
-  colors: {
-    transparent: "transparent",
-    current: "currentColor",
-    content: "var(--sc-base-content)",
-    base: "var(--sc-base)",
-    neutral: {
-      0: "var(--sc-base)",
-      50: "var(--sc-base-50)",
-      100: "var(--sc-base-100)",
-      200: "var(--sc-base-200)",
-      300: "var(--sc-base-300)",
-      400: "var(--sc-base-400)",
-      500: "var(--sc-base-500)",
-      600: "var(--sc-base-600)",
-      700: "var(--sc-base-700)",
-      800: "var(--sc-base-800)",
-      900: "var(--sc-base-900)",
-      content: "var(--sc-base)",
-    },
-    primary: {
-      DEFAULT: "var(--sc-primary)",
-      content: "var(--sc-primary-content)",
-    },
-    success: {
-      DEFAULT: "var(--sc-success)",
-      content: "var(--sc-success-content)",
-    },
-    danger: {
-      DEFAULT: "var(--sc-danger)",
-      content: "var(--sc-danger-content)",
-    },
-    warning: {
-      DEFAULT: "var(--sc-warning)",
-      content: "var(--sc-warning-content)",
-    },
-    info: {
-      DEFAULT: "var(--sc-info)",
-      content: "var(--sc-info-content)",
-    },
-    contrast: {
-      DEFAULT: "var(--sc-contrast)",
-      content: "var(--sc-contrast-content)",
-    },
-  },
-  extend: {
-    borderWidth: {
-      DEFAULT: "var(--sc-border-width)",
-    },
-    fontFamily: {
-      headings: ["var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))"],
-      body: ["var(--sc-font-family-base)"],
-      monospace: ["var(--sc-font-family-monospace, monospace)"],
-    }
-  }
-  </template>
-</sonic-code>
+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`.