@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/docs/src/core/components/ui/image/image.md

@@ -0,0 +1,233 @@
+# Image
+
+**`sonic-image`** wraps a responsive **`<img>`** with aspect ratio, `object-fit: cover`, optional rounded corners, and load transitions. The host shows a placeholder background (`--sc-placeholder-bg`) until the asset loads. Default **`loading`** is `lazy`; use **`loading="eager"`** for above-the-fold heroes.
+
+## Rounded
+
+Omit `rounded` for square corners. Boolean **`rounded`** uses the theme token `--sc-rounded`. Sizes: **`sm`**, **`md`**, **`lg`**, **`xl`**, **`full`** (circle — pair with `ratio="1/1"`), **`none`** (explicit reset).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-6 grid-cols-3  lg:grid-cols-4 items-end text-center text-xs ">
+      <div>
+        <sonic-image
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">default</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="sm"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">sm</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">rounded</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="md"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">md</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="lg"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">lg</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="xl"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">xl</p>
+      </div>
+      <div >
+        <div >
+          <sonic-image
+            rounded="full"
+            ratio="1/1"
+            src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+          ></sonic-image>
+          <p class="mt-2">full</p>
+        </div>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+## Aspect ratio
+
+**`ratio`** sets CSS `aspect-ratio` on the image (default **`auto`**). The image still fills the host width (`width: 100%`).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-8 grid-cols-2 items-center">
+      <sonic-image
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+      <sonic-image
+        ratio="16/9"
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+      <sonic-image
+        ratio="1/1"
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+      <sonic-image
+        ratio="2/3"
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+    </div>
+  </template>
+</sonic-code>
+
+## Object position
+
+**`objectPosition`** maps to CSS `object-position` (default **`center center`**). Useful on wide crops when the subject sits off-center.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-8 grid-cols-2 items-center">
+      <sonic-image
+        ratio="11/4"
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+      <sonic-image
+        objectPosition="center top"
+        ratio="11/4"
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+    </div>
+  </template>
+</sonic-code>
+
+## Cover
+
+**`cover`** stretches the image to fill a **positioned** parent (`position: relative` + fixed height or inset). Aspect ratio on the host is ignored while `cover` is set.
+
+<sonic-code>
+  <template>
+    <div class="h-96 relative rounded-lg overflow-hidden">
+      <sonic-image
+        cover
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+    </div>
+  </template>
+</sonic-code>
+
+## Load transition
+
+Set **`transition`** to **`fade`** (default when the attribute is present) or **`fade-scale-out`**. The image stays at `opacity: 0` until the browser fires **`load`**, then the **`loaded`** class runs the animation. Changing `src` on an existing element does not replay the effect — mount a new `sonic-image` when you need another entrance (galleries, infinite scroll).
+
+Click **Add image** to append small thumbnails and replay the transition. **Clear** resets the row.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2 mb-4">
+      <sonic-button
+        size="sm"
+        onclick="(function () {
+          var host = document.getElementById('sonic-image-transition-host');
+          var img = document.createElement('sonic-image');
+          img.transition = 'fade';
+          img.ratio = '1/1';
+          img.rounded = 'md';
+          img.loading = 'eager';
+          img.style.width = '8rem';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          host.appendChild(img);
+        })()"
+      >
+        Add image (fade)
+      </sonic-button>
+      <sonic-button
+        size="sm"
+        variant="outline"
+        onclick="(function () {
+          var host = document.getElementById('sonic-image-transition-host');
+          var img = document.createElement('sonic-image');
+          img.transition = 'fade-scale-out';
+          img.ratio = '1/1';
+          img.rounded = 'md';
+          img.loading = 'eager';
+          img.style.width = '8rem';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          host.appendChild(img);
+        })()"
+      >
+        Add image (fade-scale-out)
+      </sonic-button>
+      <sonic-button
+        size="sm"
+        variant="ghost"
+        onclick="document.getElementById('sonic-image-transition-host').replaceChildren()"
+      >
+        Clear
+      </sonic-button>
+    </div>
+    <div id="sonic-image-transition-host" class="flex flex-wrap gap-2 min-h-[5rem]"></div>
+  </template>
+</sonic-code>
+
+## Accessibility and parts
+
+Always set meaningful **`alt`** text (empty string only for decorative images). 
+
+<sonic-code>
+  <template>
+    <sonic-image
+      rounded="md"
+      ratio="16/9"
+      alt="Concorde aircraft in flight"
+      src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+    ></sonic-image>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `src` | URL | Image URL passed to `<img src>` |
+| `alt` | string | Accessible description; use `""` only for decorative images |
+| `loading` | `lazy` (default), `eager` | Native lazy loading |
+| `ratio` | CSS ratio, `auto` (default) | Host `aspect-ratio` on the image (ignored when `cover` is set) |
+| `rounded` | `none` (default), boolean, `base`, `sm`, `md`, `lg`, `xl`, `full` | Corner radius from theme tokens; `full` is a circle (often with `ratio="1/1"`) |
+| `objectPosition` | CSS position | Maps to `object-position` (default `center center`) |
+| `imageRendering` | CSS value | Maps to `image-rendering` (default `auto`) |
+| `cover` | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
+| `transition` | `fade`, `fade-scale-out` | Opacity (and scale) animation after `load`; remount to replay on `src` change |
+
+No slots — content is driven entirely by attributes on the inner `<img>`.
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `src` | URL | Image URL passed to `<img src>` |
+| `alt` | string | Accessible description; use `""` only for decorative images |
+| `loading` | `lazy` (default), `eager` | Native lazy loading |
+| `ratio` | CSS ratio, `auto` (default) | Host `aspect-ratio` on the image (ignored when `cover` is set) |
+| `rounded` | `none` (default), boolean, `base`, `sm`, `md`, `lg`, `xl`, `full` | Corner radius from theme tokens; `full` is a circle (often with `ratio="1/1"`) |
+| `objectPosition` | CSS position | Maps to `object-position` (default `center center`) |
+| `imageRendering` | CSS value | Maps to `image-rendering` (default `auto`) |
+| `cover` | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
+| `transition` | `fade`, `fade-scale-out` | Opacity (and scale) animation after `load`; remount to replay on `src` change |
+
+No slots — content is driven entirely by attributes on the inner `<img>`.

package/docs/src/core/components/ui/link/link.md

@@ -0,0 +1,81 @@
+# Link
+
+Links **navigate** with inherited typography: internal routes, anchors, or external URLs. The default slot is the anchor label. For in-app routing, pair **`href`** with **`pushstate`**; use **`autoActive`** to reflect the current URL on the host (`active`).
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-link href="/">Basic link with href attribute</sonic-link>
+  </template>
+</sonic-code>
+
+## Target
+
+**`target="_blank"`** opens a new browsing context and sets **`rel="noopener noreferrer"`**.
+
+<sonic-code>
+  <template>
+    <sonic-link href="/" target="_blank">Link with target attribute</sonic-link>
+  </template>
+</sonic-code>
+
+## Pushstate
+
+Set **`pushstate`** on same-origin **`href`** values to intercept clicks and navigate through Concorde’s client router without a full reload.
+
+<sonic-code>
+  <template>
+    <sonic-link href="/#core/components" pushstate>Client navigation (pushstate)</sonic-link>
+  </template>
+</sonic-code>
+
+## AutoActive
+
+Default **`autoActive`** is **`partial`**: the host gets **`active`** when the current URL starts with **`href`**. Style with **`[&[active]]:`** utilities or host selectors.
+
+<sonic-code>
+  <template>
+    <sonic-link href="/#core/components" class="[&[active]]:text-success">autoActive partial (default)</sonic-link>
+  </template>
+</sonic-code>
+
+### AutoActive strict vs partial
+
+**`strict`** requires pathname, search, and hash to match. **`strict-path-only`** matches pathname and hash but ignores search.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-3">
+      <sonic-link href="/#core" autoActive="strict" class="[&[active]]:text-success">autoActive strict</sonic-link>
+      <sonic-link href="/#core/components/ui/link/link.md/link" autoActive="strict" class="[&[active]]:text-success">autoActive strict (long href)</sonic-link>
+      <sonic-link href="/#core/components" autoActive="strict-path-only" class="[&[active]]:text-success">autoActive strict-path-only</sonic-link>
+    </div>
+  </template>
+</sonic-code>
+
+### AutoActive disabled
+
+<sonic-code>
+  <template>
+    <sonic-link href="/#core/components/ui/link/link.md/link" autoActive="disabled" class="[&[active]]:text-success">autoActive disabled</sonic-link>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+The inner **`<a>`** uses **`focus-visible`** outline styling. Set **`data-aria-label`** when the slot text is not sufficient on its own.
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `href` | URL | Link target; without **`href`**, only the slot is rendered (no **`<a>`**) |
+| `target` | e.g. `_blank` | Navigation target; **`_blank`** adds **`rel="noopener noreferrer"`** |
+| `pushstate` | boolean | Intercepts click for Concorde client navigation without reload |
+| `autoActive` | `partial` (default) · `strict` · `strict-path-only` · `disabled` | When the host gets the **`active`** attribute (same-origin **`href`** only) |
+| `data-aria-label` | string | Accessible **`aria-label`** when the slot text is not enough |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Link content (text, icons) |

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

@@ -0,0 +1,112 @@
+# Loader
+
+**`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>
+    <sonic-loader mode="inline"></sonic-loader>
+  </template>
+</sonic-code>
+
+## 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"></sonic-loader>
+  </template>
+</sonic-code>
+
+Use the checkbox below to toggle a **`fixed`** loader over the page (default **`mode`** on **`sonic-loader`**).
+
+<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>
+    <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>
+
+## `noDelay`
+
+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.
+
+<sonic-code>
+  <template>
+    <sonic-loader mode="inline" announce></sonic-loader>
+  </template>
+</sonic-code>
+
+## 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";
+
+Loader.show({
+  mode: "fixed",
+  noDelay: false,
+  announce: true,
+  container: document.querySelector("#foo"),
+});
+
+Loader.hide();
+  </template>
+</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. |