@supersoniks/concorde 5.0.3 → 5.0.5

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

@@ -1,91 +1,253 @@
-# Adding styles
+# Customization
 
-## Normal Behavior
+## Theme-first customization
 
-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.
+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.
 
-- **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.
+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.
 
-## Choosing Style Presets via Reactive Properties:
+<sonic-code language="html">
+  <template>
+<sonic-theme color font class="block bg-base min-h-screen">
+  <!-- your app -->
+</sonic-theme>
+  </template>
+</sonic-code>
 
-The declaration of reactive properties is useful for selecting a particular configuration that mostly affects a set of properties.
+<sonic-code language="javascript">
+  <template>
+import "@supersoniks/concorde/theme";
+  </template>
+</sonic-code>
 
-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.
+| 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.) |
 
-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']){...}`
+Popovers, modals, and toasts mount under the nearest `<sonic-theme>`.
 
-☢️ **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.
+## Customization example
 
-#### CSS "display" Property
+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.
 
-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>`.
+<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>
 
-☢️ **Caution:** Defining the `display` property as `contents` may seem attractive at first, but:
+<sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button>
 
-- 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
+**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"`.
 
-[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:
+**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.
 
-<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:
+## Only essential CSS variables (public theme API)
 
-<sonic-code language="javascript">
-  <template>
-static styles = [tailwind];
-  </template>
-</sonic-code>
+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`).
 
-Finally, use it in the HTML within the render function:
+### Surfaces and foreground
 
-<sonic-code language="html">
-  <template>
-<p class="m-2">A paragraph with margin</p>
-  </template>
-</sonic-code>
+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.).
+
+#### Neutral fills
+
+| Variable | Role |
+|----------|------|
+| `--sc-base` | Main surface / page background |
+| `--sc-base-50` … `--sc-base-900` | Neutral scale (borders, subtle backgrounds, muted UI) |
+
+#### Neutral foreground
+
+| Variable | Role |
+|----------|------|
+| `--sc-base-content` | Default body text and icons on neutral surfaces |
 
-The colors from Concorde's theme are referenced in Tailwind's theme.
+#### Semantic fills
 
-## Operation without Shadow DOM
+| 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) |
 
-### Usefulness
+#### Semantic foreground
 
-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**.
+| Variable | Role |
+|----------|------|
+| `--sc-primary-content`, `--sc-secondary-content`, … | Text/icons on the matching semantic **fill** (`--sc-primary`, etc.) |
 
-For example, with a text input:
+### Shape
 
-- Trigger automatic data or filter update when typing text.
-- Automatic formatting.
-- Constraints that cannot be handled by native methods.
+| Variable | Role |
+|----------|------|
+| `--sc-rounded` | **Single primitive** corner radius; the theme computes `--sc-rounded-sm`, `--sc-btn-rounded`, `--sc-input-rounded`, etc. |
 
-### Consequences
+### Typography
 
-If there is no shadow DOM (see the **noShadowDom** property of **Subscriber**):
+| 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.) |
 
-- 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.
+### Forms (only if you customize inputs globally)
 
-For example, the components `queue`, `list`, and `fetch` do not have a shadow DOM.
+Interactive controls expose a few extra **theme-level** tokens; prefer these over styling individual inputs from outside.
+
+| 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 |
+
+---
+
+## Tailwind in new components ?
+
+Set <code>tailwind.config.js</code> to match concorde style token in your custom component.
+
+<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>
 
-ℹ️ **Note:** Specifically in this case, it may be useful to set the `display` property to `contents`.

package/src/docs/code.ts

@@ -18,6 +18,25 @@ import "prismjs/components/prism-bash"; // Language
 // import "prismjs/components/prism-css"; // Language
 import "prismjs/components/prism-markup"; // Language
 
+let normalizeWhitespaceDefaultsApplied = false;
+
+function normalizeDocsCodeLanguage(language: string): string {
+  return language === "html" ? "markup" : language;
+}
+
+function applyNormalizeWhitespaceDefaults(): void {
+  if (normalizeWhitespaceDefaultsApplied) return;
+  normalizeWhitespaceDefaultsApplied = true;
+  Prism.plugins.NormalizeWhitespace.setDefaults({
+    "remove-trailing": true,
+    "remove-indent": true,
+    "left-trim": true,
+    "right-trim": true,
+    "remove-initial-line-feed": true,
+    "tabs-to-tabs": 2,
+  });
+}
+
 const tagName = "sonic-code";
 @customElement(tagName)
 export class DocsCode extends LitElement {
@@ -38,6 +57,7 @@ export class DocsCode extends LitElement {
         padding-right: 5rem !important;
         border: 1px solid var(--sc-base-200);
         border-radius: var(--sc-rounded);
+        margin: 0 !important;
       }
       .custom-scroll {
         overflow: auto !important;
@@ -70,62 +90,95 @@ export class DocsCode extends LitElement {
   @property({ type: Boolean, reflect: true }) showCode = false;
   @property({ type: Boolean, reflect: true }) toggleCode = false;
   @property({ type: Boolean, reflect: true }) noEdit = false;
-  @property({ type: Boolean, reflect: true }) noOutput = false;
 
   @property() language = "markup";
-  @property() defaultCode?: string;
-  @property() currentCode?: string;
+  @property({ attribute: false }) defaultCode?: string;
+  @property({ attribute: false }) currentCode?: string;
+  @property({ attribute: false }) codeOutput?: string;
 
-  @property() codeOutput?: string;
+  @query("#codePreview") codePreview!: HTMLPreElement;
 
-  //ELEMENTS
-  @property() templateEl: HTMLTemplateElement | null;
-  @query("#codePreview") codePreview;
-  @query("#codeRender") codeRender;
+  private templateEl: HTMLTemplateElement | null = null;
 
-  //States
   @state() codeEdited = false;
 
-  /** Aperçu live uniquement pour les blocs markup (évite d’injecter du HTML depuis des exemples JS). */
-  private get rendersLiveOutput(): boolean {
-    return this.language === "markup" && !this.noOutput;
+  /** Live preview only for markup (avoid injecting HTML from JS/TS examples). */
+  private get prismLanguage(): string {
+    return normalizeDocsCodeLanguage(this.language);
   }
 
-  // createRenderRoot() {
-  //   return this;
-  // }
+  private get rendersLiveOutput(): boolean {
+    return this.prismLanguage === "markup";
+  }
 
   connectedCallback() {
     super.connectedCallback();
     if (!this.toggleCode) {
       this.showCode = true;
     }
+    this.syncFromTemplate();
+  }
+
+  willUpdate(changedProperties: PropertyValues) {
+    if (
+      changedProperties.has("language") &&
+      changedProperties.get("language") !== undefined
+    ) {
+      this.applyLanguageChange();
+    }
+  }
 
+  private normalizeSourceForHighlight(source: string): string {
+    applyNormalizeWhitespaceDefaults();
+    const nw = Prism.plugins.NormalizeWhitespace;
+    return nw
+      .normalize(source)
+      .replaceAll('=""', "")
+      .replaceAll(""", '"')
+      .replaceAll('"{', "'{")
+      .replaceAll('}"', "}'")
+      .replaceAll("&", "&");
+  }
+
+  private highlightSource(source: string): string {
+    const lang = this.prismLanguage;
+    const grammar = Prism.languages[lang];
+    if (!grammar) {
+      return source;
+    }
+    return Prism.highlight(
+      this.normalizeSourceForHighlight(source),
+      grammar,
+      lang,
+    );
+  }
+
+  private syncFromTemplate() {
     this.templateEl = this.querySelector("template");
     this.defaultCode = this.readTemplateSourceCode();
+    this.codeEdited = false;
 
     if (this.defaultCode) {
-      Prism.plugins.NormalizeWhitespace.setDefaults({
-        "remove-trailing": true,
-        "remove-indent": true,
-        "left-trim": true,
-        "right-trim": true,
-        "remove-initial-line-feed": true,
-        "tabs-to-tabs": 2,
-      });
-      const nw = Prism.plugins.NormalizeWhitespace;
-      const normalizedCode = nw
-        .normalize(this.defaultCode)
-        .replaceAll('=""', "")
-        .replaceAll(""", '"')
-        .replaceAll('"{', "'{")
-        .replaceAll('}"', "}'")
-        .replaceAll("&", "&");
-      this.currentCode = Prism.highlight(
-        normalizedCode,
-        Prism.languages[this.language],
-        this.language,
-      );
+      this.currentCode = this.highlightSource(this.defaultCode);
+    } else {
+      this.currentCode = undefined;
+    }
+
+    if (this.rendersLiveOutput) {
+      this.codeOutput = this.defaultCode;
+    } else {
+      this.removeOutputSlot();
+    }
+  }
+
+  private applyLanguageChange() {
+    this.defaultCode = this.readTemplateSourceCode();
+    this.codeEdited = false;
+
+    if (this.defaultCode) {
+      this.currentCode = this.highlightSource(this.defaultCode);
+    } else {
+      this.currentCode = undefined;
     }
 
     if (this.rendersLiveOutput) {
@@ -148,10 +201,10 @@ export class DocsCode extends LitElement {
    * when the fragment has elements; otherwise textContent (imports, types, etc.).
    */
   private readTemplateSourceCode(): string {
-    const template = this.templateEl;
+    const template = this.templateEl ?? this.querySelector("template");
     if (!template) return "";
 
-    if (this.language === "markup") {
+    if (this.prismLanguage === "markup") {
       return this.decodeTemplateEntities(template.innerHTML);
     }
 
@@ -160,11 +213,16 @@ export class DocsCode extends LitElement {
     return template.content.textContent ?? "";
   }
 
+  private getPreviewPlainText(): string {
+    return this.codePreview?.innerText ?? "";
+  }
+
   updateCodeRender() {
-    if (this.defaultCode !== this.currentCode) {
-      this.codeEdited = true;
+    const plain = this.getPreviewPlainText();
+    this.codeEdited = plain !== (this.defaultCode ?? "");
+    if (this.rendersLiveOutput) {
+      this.codeOutput = plain;
     }
-    this.codeOutput = this.codePreview?.innerText;
   }
 
   resetCode() {
@@ -173,11 +231,7 @@ export class DocsCode extends LitElement {
     if (this.defaultCode) {
       this.currentCode = "";
       window.requestAnimationFrame(() => {
-        this.currentCode = Prism.highlight(
-          this.defaultCode || "",
-          Prism.languages[this.language],
-          this.language,
-        );
+        this.currentCode = this.highlightSource(this.defaultCode || "");
       });
     }
     if (this.rendersLiveOutput) {
@@ -189,15 +243,27 @@ export class DocsCode extends LitElement {
     this.showCode = !this.showCode;
   }
 
-  handleCopyCode(e: Event) {
-    const text = this.codeOutput ?? this.defaultCode;
-    if (text) {
-      navigator.clipboard.writeText(text);
-      const button = e.currentTarget as HTMLButtonElement;
+  private getCopyText(): string {
+    if (!this.noEdit) {
+      const fromPreview = this.getPreviewPlainText();
+      if (fromPreview) return fromPreview;
+    }
+    return this.codeOutput ?? this.defaultCode ?? "";
+  }
+
+  async handleCopyCode(e: Event) {
+    const text = this.getCopyText();
+    if (!text) return;
+
+    const button = e.currentTarget as HTMLButtonElement;
+    try {
+      await navigator.clipboard.writeText(text);
       button?.setAttribute("active", "");
       setTimeout(() => {
         button?.removeAttribute("active");
       }, 500);
+    } catch {
+      // Clipboard unavailable or permission denied.
     }
   }
 
@@ -205,8 +271,7 @@ export class DocsCode extends LitElement {
     super.updated(changedProperties);
     if (
       changedProperties.has("codeOutput") ||
-      changedProperties.has("language") ||
-      changedProperties.has("noOutput")
+      changedProperties.has("language")
     ) {
       this.appendOutput();
     }
@@ -216,6 +281,7 @@ export class DocsCode extends LitElement {
     this.querySelector("[slot=output]")?.remove();
   }
 
+  /** Trusted doc demo markup only — same source as the live preview slot. */
   appendOutput() {
     if (!this.rendersLiveOutput) {
       this.removeOutputSlot();
@@ -231,20 +297,21 @@ export class DocsCode extends LitElement {
       output.innerHTML = this.codeOutput || "";
     }
   }
+
   handleGetSDUI() {
     SDUIUtils.toJson(this.templateEl?.content.children);
   }
 
   render() {
-    // ${this.language === "markup" ? html`<div class="py-3">${unsafeHTML(this.codeOutput || "")}</div>` : nothing} //
+    const isMarkup = this.prismLanguage === "markup";
 
     return html`
       <div
-        class="relative ${this.language === "markup"
+        class="relative ${isMarkup
           ? "rounded-md border border-neutral-200 bg-neutral-50/80 dark:border-neutral-700/80 dark:bg-neutral-900/40 p-4"
           : ""}"
       >
-        ${this.language === "markup" && !this.noOutput
+        ${isMarkup
           ? html`<slot name="output" class="block py-3"></slot>`
           : nothing}
 
@@ -282,7 +349,7 @@ export class DocsCode extends LitElement {
                 name="check"
               ></sonic-icon>
             </sonic-button>
-            ${this.language == "markup"
+            ${isMarkup
               ? html`<sonic-button
                   size="2xs"
                   shape
@@ -316,7 +383,7 @@ export class DocsCode extends LitElement {
           <div>
             <pre
               id="codePreview"
-              class="rounded-md custom-scroll language-${this.language} ${!this
+              class="rounded-md custom-scroll language-${this.prismLanguage} ${!this
                 .showCode || !this.currentCode
                 ? "hidden"
                 : ""}"