@supersoniks/concorde 5.0.4 → 5.0.5

package/src/core/components/ui/loader/loader.md

@@ -1,6 +1,10 @@
-# Loader 
+# Loader
 
-## Inline mode
+**`sonic-loader`** shows a loading animation in the page or as a viewport overlay. Default **`mode`** is **`fixed`** (centered overlay). Use **`inline`** inside lists and fetch placeholders. Pair **`noDelay`** when the spinner should appear without the default fade-in wait. For **`sonic-fetch`** / **`sonic-list`**, set the parent **`loader`** attribute instead of embedding a tag manually.
+
+## Basic example
+
+Inline loaders fit content areas; they use the theme primary color unless **`currentColor`** is set.
 
 <sonic-code>
   <template>
@@ -8,48 +12,101 @@
   </template>
 </sonic-code>
 
-## CurrentColor 
+## Mode
+
+**`inline`** — ellipsis animation in the document flow. **`fixed`** — centered overlay (`position: fixed`); default when the tag is omitted.
 
 <sonic-code>
   <template>
-    <sonic-loader mode="inline" currentColor style="color:purple;"></sonic-loader>
+    <sonic-loader mode="inline"></sonic-loader>
   </template>
 </sonic-code>
 
+Use the checkbox below to toggle a **`fixed`** loader over the page (default **`mode`** on **`sonic-loader`**).
 
-## Align
+<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+
+## Inline alignment and color
+
+**`align`** only affects **`mode="inline"`**: **`left`** · **`center`** (default) · **`right`**. Set **`currentColor`** so dots follow the host `color` (for example on a purple parent).
 
 <sonic-code>
   <template>
-    <sonic-loader mode="inline" align="left"></sonic-loader>
-    <sonic-loader mode="inline" align="center"></sonic-loader>
-    <sonic-loader mode="inline" align="right"></sonic-loader>
+    <div class="grid gap-4">
+      <sonic-loader mode="inline" currentColor style="color: purple;"></sonic-loader>
+      <div class="flex flex-col gap-2">
+        <sonic-loader mode="inline" align="left"></sonic-loader>
+        <sonic-loader mode="inline" align="center"></sonic-loader>
+        <sonic-loader mode="inline" align="right"></sonic-loader>
+      </div>
+    </div>
   </template>
 </sonic-code>
 
-## Fixed mode
+## `noDelay`
 
-<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+By default **`mode="fixed"`** waits briefly before fading in. **`mode="inline"`** already skips that wait. Set **`noDelay`** on **`fixed`** (or pass **`noDelay: true`** to **`Loader.show()`**) to appear immediately.
 
+<sonic-code>
+  <template>
+    <sonic-loader mode="inline" noDelay></sonic-loader>
+  </template>
+</sonic-code>
+
+## Accessibility (`announce`)
+
+The animation is **`aria-hidden`** by default so screen readers are not spammed on every fetch. Set **`announce`** when the loader is injected **after** user action (for example a global overlay): the host gets **`role="status"`**, **`aria-live="polite"`**, and a localized **`aria-label`** (“Loading” / “Chargement en cours”, …). For in-button loading, prefer **`sonic-button`** **`loading`** and **`aria-busy`** on the control—not on the loader.
 
-## Loading button
 <sonic-code>
   <template>
-    <sonic-button loading>A loading button</sonic-button>
+    <sonic-loader mode="inline" announce></sonic-loader>
   </template>
 </sonic-code>
 
-## Hide / show programmatically
+## Show and hide programmatically
+
+Import **`Loader`** and call **`Loader.show()`** / **`Loader.hide()`**. **`hide()`** is reference-counted: call it once per **`show()`**. With no **`container`**, the loader is appended to the theme pop container and **`mode`** is always **`fixed`**. Pass **`container`** and **`mode: "inline"`** to mount an inline instance in a specific element.
 
 <sonic-code language="javascript">
   <template>
-  import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
-  // Show 
-  Loader.show({
-    mode:"fixed" // optional : fixed | inline
-    container : document.querySelector('#foo') // optional, default : parent sonic-theme || document.body
-  });
-  // Hide 
-  Loader.hide();
+import { Loader } from "@supersoniks/concorde/core/components/ui/loader/loader";
+
+Loader.show({
+  mode: "fixed",
+  noDelay: false,
+  announce: true,
+  container: document.querySelector("#foo"),
+});
+
+Loader.hide();
   </template>
-</sonic-code>
+</sonic-code>
+
+## Composition
+
+**`sonic-button`** **`loading`** shows an icon spinner and sets **`aria-busy`** on the button. **`sonic-fetch`** and **`sonic-list`** render **`sonic-loader`** when their **`loader`** attribute is set: **`true`** or an empty string maps to **`fixed`**; otherwise use **`inline`** or **`fixed`**.
+
+<sonic-code>
+  <template>
+    <sonic-button loading>Save changes</sonic-button>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `mode` | `inline` · `fixed` (default `fixed`) | Layout: in-flow ellipsis vs viewport-centered overlay |
+| `noDelay` | boolean | Skips the initial fade-in delay before the animation appears |
+| `announce` | boolean | **`role="status"`** and **`aria-live="polite"`** with localized loading label when the loader should be announced |
+| `align` | `left` · `center` · `right` | Horizontal alignment for **`mode="inline"`** only (attribute selector; default centered) |
+| `currentColor` | boolean | Uses `currentColor` for dot fill instead of **`--sc-primary`** |
+
+This component has **no slots**. The animation markup is internal.
+
+### Static methods
+
+| Method | Description |
+|--------|-------------|
+| `Loader.show(conf?)` | Mounts the shared loader instance. **`conf.mode`**, **`conf.noDelay`**, **`conf.announce`**, optional **`conf.container`**. Without **`container`**, uses the theme pop container and forces **`fixed`**. |
+| `Loader.hide()` | Decrements the show counter and removes the instance from the DOM when it reaches zero. |

package/src/core/components/ui/loader/loader.ts

@@ -1,12 +1,27 @@
-import { html, LitElement, css } from "lit";
+import { html, LitElement, css, PropertyValues } from "lit";
 import { customElement, property } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
 
 import { inline } from "@supersoniks/concorde/core/components/ui/loader/styles/inline";
 import { fixed } from "@supersoniks/concorde/core/components/ui/loader/styles/fixed";
 import { Theme } from "@supersoniks/concorde/core/components/ui/theme/theme";
-export type LoaderMode = "inline" | "fixed" | "noDelay";
-type LoaderConf = { mode?: string; container?: HTMLElement; noDelay?: boolean };
+import {
+  resolveUiLabel,
+  uiAriaLabels,
+} from "@supersoniks/concorde/core/components/ui/_i18n/ui-aria-labels";
+
+export type LoaderMode = "inline" | "fixed";
+
+export type LoaderConf = {
+  mode?: LoaderMode;
+  container?: HTMLElement;
+  noDelay?: boolean;
+  /** Screen reader announcement when the loader is injected (e.g. global overlay). */
+  announce?: boolean;
+};
+
 const tagName = "sonic-loader";
+
 @customElement(tagName)
 export class Loader extends LitElement {
   static styles = [
@@ -42,45 +57,70 @@ export class Loader extends LitElement {
       }
     `,
   ];
-  static loader: Loader;
+
+  static loader: Loader | null = null;
   static callCounter = 0;
-  static show(conf?: LoaderConf) {
-    if (!Loader.loader)
-      Loader.loader = document.createElement("sonic-loader") as Loader;
-    const loader: Loader = Loader.loader;
-    if (!conf) conf = {};
-    if (conf.mode) loader.setAttribute("mode", conf.mode);
-    if (conf.noDelay) loader.setAttribute("noDelay", "");
-
-    if (!conf.container) {
-      conf.container = Theme.getPopContainer();
-      conf.mode = "fixed";
+
+  static show(conf: LoaderConf = {}) {
+    if (!Loader.loader) {
+      Loader.loader = document.createElement(tagName) as Loader;
     }
+    const loader = Loader.loader;
 
-    conf.container.appendChild(loader);
+    const container = conf.container ?? Theme.getPopContainer();
+    const mode: LoaderMode = conf.container ? (conf.mode ?? "fixed") : "fixed";
+    const noDelay = conf.noDelay ?? false;
+
+    loader.mode = mode;
+    loader.noDelay = noDelay;
+    loader.announce = conf.announce ?? false;
+    container.appendChild(loader);
     Loader.callCounter++;
   }
 
   static hide() {
+    if (Loader.callCounter <= 0) return;
     Loader.callCounter--;
     if (Loader.callCounter > 0) return;
-    if (Loader.loader) Loader.loader.remove();
+    Loader.loader?.remove();
   }
 
+  /** Display mode: inline (in content) or fixed (viewport overlay). */
+  @property({ type: String }) mode: LoaderMode = "fixed";
+  /** Skip the initial fade-in delay before the loader appears. */
+  @property({ type: Boolean }) noDelay = false;
   /**
-   * Mode d'affichage du loader
-   * * inline : Loader dans le contenu
-   * * fixed : Loader global par dessus la page
+   * When true, exposes `role="status"` and `aria-live="polite"` on the host (like `sonic-alert`).
+   * Use when the loader appears after user action; default inline loaders stay decorative.
    */
-  @property({ type: String }) mode: LoaderMode = "fixed";
-  @property({ type: Boolean }) noDelay: boolean = false;
+  @property({ type: Boolean, reflect: true }) announce = false;
+
+  willUpdate(changed: PropertyValues<this>) {
+    if (changed.has("announce")) {
+      this._syncAnnounceA11y();
+    }
+  }
+
+  private _syncAnnounceA11y() {
+    if (!this.announce) {
+      this.removeAttribute("role");
+      this.removeAttribute("aria-live");
+      this.removeAttribute("aria-label");
+      return;
+    }
+    this.setAttribute("role", "status");
+    this.setAttribute("aria-live", "polite");
+    this.setAttribute("aria-label", resolveUiLabel(uiAriaLabels.loading));
+  }
 
   render() {
-    return html`<div
-      class="sonic-loader sonic-loader--${this.mode} ${this.noDelay
-        ? "sonic-loader--nodelay"
-        : ""} "
-    >
+    const classes = {
+      "sonic-loader": true,
+      [`sonic-loader--${this.mode}`]: true,
+      "sonic-loader--nodelay": this.noDelay,
+    };
+
+    return html`<div aria-hidden="true" class=${classMap(classes)}>
       <div></div>
       <div></div>
       <div></div>

package/src/core/components/ui/loader/styles/fixed.ts

@@ -22,7 +22,7 @@ export const fixed = css`
     position: fixed;
     top: 50%;
     left: 50%;
-    transform: transateY(-50%) translateX(-50%);
+    transform: translate(-50%, -50%);
     z-index: 999;
   }
 
@@ -37,20 +37,15 @@ export const fixed = css`
     display: none !important;
   }
   .sonic-loader--fixed > div {
-    background-color: var(--sc-_loader-bg);
-    width: 5rem;
-    height: 5rem;
-    border-radius: 100%;
-    margin: 2px;
-    animation-fill-mode: both;
     position: absolute;
-    top: 0px;
-    opacity: 0;
-    margin: 0;
     top: -2.5rem;
     left: -2.5rem;
     width: 5rem;
     height: 5rem;
-    animation: sonic-loader--fixed 1s 0s linear infinite;
+    border-radius: 100%;
+    background-color: var(--sc-_loader-bg);
+    opacity: 0;
+    animation: sonic-loader--fixed 1s linear infinite;
+    animation-fill-mode: both;
   }
 `;