@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -1,107 +1,167 @@
 # Image
 
+**`sonic-image`** wraps a responsive `<img>` with aspect ratio, `object-fit: cover`, optional rounded corners and a load transition. The host shows a placeholder background (`--sc-placeholder-bg`) until the file loads. With no `loading`, the image is `lazy`; set `loading="eager"` for above-the-fold images.
+
 ## Rounded
 
+With no `rounded`, corners are square. Boolean `rounded` uses the theme token `--sc-rounded`; `full` draws a circle when paired with `ratio="1/1"`.
+
 <sonic-code>
   <template>
-    <div class="grid gap-8 grid-cols-3 items-center">
-      <sonic-image
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-        ratio="1/1"
-      >
-      </sonic-image>
-      <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>
-      <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>
-      <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>
-      <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>
-      <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>
+    <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="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">default</p>
+      </div>
+      <div>
+        <sonic-image rounded="sm" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">sm</p>
+      </div>
+      <div>
+        <sonic-image rounded ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">rounded</p>
+      </div>
+      <div>
+        <sonic-image rounded="md" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">md</p>
+      </div>
+      <div>
+        <sonic-image rounded="lg" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">lg</p>
+      </div>
+      <div>
+        <sonic-image rounded="xl" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">xl</p>
+      </div>
+      <div>
+        <sonic-image rounded="full" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">full</p>
+      </div>
     </div>
   </template>
 </sonic-code>
 
-## Ratio
+## Aspect ratio
+
+`ratio` sets CSS `aspect-ratio` on the image (default `auto`). The image always fills the host width.
 
 <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>
+      <sonic-image src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="16/9" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="1/1" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="2/3" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
     </div>
   </template>
 </sonic-code>
 
 ## Object position
 
+`objectPosition` maps to CSS `object-position` (default `center center`). Use it on wide crops when the subject sits off-center.
+
 <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"
-        ratio="11/4"
-      >
-      </sonic-image>
-      <sonic-image
-        objectPosition="center top"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-        ratio="11/4"
-      >
-      </sonic-image>
+      <sonic-image ratio="11/4" src="img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
+      <sonic-image objectPosition="center top" ratio="11/4" src="img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
     </div>
   </template>
 </sonic-code>
 
 ## Cover
 
+`cover` stretches the image over a **positioned** parent (`position: relative` with a height). `ratio` is ignored while `cover` is set.
+
 <sonic-code>
   <template>
-    <div class="h-96 relative">
-      <sonic-image
-        cover
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+    <div class="h-96 relative rounded-lg overflow-hidden">
+      <sonic-image cover src="img/concorde/plane_10.jpg" alt="Concorde fleet parked in a star"></sonic-image>
+    </div>
+  </template>
+</sonic-code>
+
+## Load transition
+
+Set `transition` to `fade` or `fade-scale-out`. The image stays transparent until the browser fires `load`, then animates in. **Changing `src` on an existing element does not replay the effect**: mount a new `sonic-image` instead (galleries, infinite scroll).
+
+<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';
+          var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
+          img.src = 'img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
+          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';
+          var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
+          img.src = 'img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
+          host.appendChild(img);
+        })()"
       >
-      </sonic-image>
+        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
+
+Always set a meaningful `alt`. Use `alt=""` only for decorative images.
+
+<sonic-code>
+  <template>
+    <sonic-image
+      rounded="md"
+      ratio="16/9"
+      alt="Crowd gathered around Concorde at night"
+      src="img/concorde/plane_07.jpg"
+    ></sonic-image>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `src` | URL | Image URL passed to `<img src>` |
+| `alt` | string | Accessible description; `""` only for decorative images |
+| `loading` | `lazy` (default) · `eager` | Native lazy loading |
+| `ratio` | CSS ratio (default `auto`) | `aspect-ratio` of the image; ignored when `cover` is set |
+| `rounded` | `none` (default) · boolean · `base` · `sm` · `md` · `lg` · `xl` · `full` | Corner radius from theme tokens |
+| `objectPosition` | CSS position (default `center center`) | Maps to `object-position` |
+| `imageRendering` | CSS value (default `auto`) | Maps to `image-rendering` |
+| `cover` | boolean | Absolutely fills a positioned parent |
+| `transition` | `fade` · `fade-scale-out` | Entrance animation after `load`; not replayed on `src` change |
+
+No slots.

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

@@ -1,34 +1,55 @@
 # Link
 
-## Href
+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 attibute</sonic-link>
+    <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 attibute</sonic-link>
+    <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/ui/link" 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>
+    <sonic-link href="/core/components" class="[&[active]]:text-success">autoActive partial (default)</sonic-link>
   </template>
 </sonic-code>
 
-### AutoActive Strict vs partial
+### 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</sonic-link>
+      <sonic-link href="/core/components/ui/link" autoActive="strict" class="[&[active]]:text-success">autoActive strict</sonic-link>
+      <sonic-link href="/core/components/ui/button" autoActive="strict" class="[&[active]]:text-success">autoActive strict (other page)</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>
@@ -37,7 +58,24 @@
 
 <sonic-code>
   <template>
-      <sonic-link href="/#core/components/ui/link/link.md/link" autoActive="disabled" class="[&[active]]:text-success">autoActive disabled</sonic-link>
+    <sonic-link href="/core/components/ui/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

@@ -1,6 +1,10 @@
-# Loader 
+# Loader
 
-## Inline mode
+**`sonic-loader`** shows a loading animation, either in the content flow or as a viewport overlay. With no `mode`, it is `fixed` (centered overlay); use `mode="inline"` inside content areas. For [Fetch](/core/components/functional/fetch) and [List](/core/components/functional/list), set their `loader` attribute instead of adding the tag yourself.
+
+## Mode
+
+`inline` renders an ellipsis animation in the document flow. `fixed` (default) covers the viewport with a centered animation; toggle it with the checkbox below.
 
 <sonic-code>
   <template>
@@ -8,48 +12,76 @@
   </template>
 </sonic-code>
 
-## CurrentColor 
+<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+
+## Alignment and color
+
+`align` only affects `mode="inline"`: `left` · `center` (default) · `right`. Dots use `--sc-primary`; set `currentColor` to follow the host `color`.
 
 <sonic-code>
   <template>
-    <sonic-loader mode="inline" currentColor style="color:purple;"></sonic-loader>
+    <div class="grid gap-4">
+      <sonic-loader mode="inline" currentColor style="color: purple;"></sonic-loader>
+      <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>
   </template>
 </sonic-code>
 
+## Delay
 
-## Align
+A `fixed` loader waits 0.5 s before fading in, so short requests show nothing. `inline` loaders appear at once. Set `noDelay` (or pass `noDelay: true` to `Loader.show()`) to show a `fixed` loader immediately.
 
 <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>
+    <sonic-loader mode="inline" noDelay></sonic-loader>
   </template>
 </sonic-code>
 
-## Fixed mode
-
-<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+## Accessibility
 
+The animation is `aria-hidden` by default so screen readers are not flooded on every request. Set `announce` when the loader appears after a user action: the host gets `role="status"`, `aria-live="polite"` and a localized "Loading" label. For a busy button, use the `loading` attribute of `sonic-button` instead.
 
-## Loading button
 <sonic-code>
   <template>
-    <sonic-button loading>A loading button</sonic-button>
+    <div class="flex flex-wrap items-center gap-4">
+      <sonic-loader mode="inline" announce></sonic-loader>
+      <sonic-button loading>Confirm check-in</sonic-button>
+    </div>
   </template>
 </sonic-code>
 
-## Hide / show programmatically
+## Show and hide programmatically
+
+`Loader.show()` mounts one shared instance; `Loader.hide()` is reference-counted, so call it once per `show()`. **Without `container`, the loader goes to the theme pop container and `mode` is forced to `fixed`.**
 
 <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/ui/loader";
+
+Loader.show({ announce: true });
+// …
+Loader.hide();
+
+// Inline loader inside a given element
+Loader.show({ mode: "inline", container: document.querySelector("#results") });
   </template>
-</sonic-code>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `mode` | `inline` · `fixed` (default `fixed`) | In-flow ellipsis or viewport-centered overlay |
+| `noDelay` | boolean | Skips the 0.5 s fade-in delay of `fixed` |
+| `announce` | boolean | Adds `role="status"`, `aria-live="polite"` and a localized label |
+| `align` | `left` · `center` · `right` (default `center`) | Horizontal alignment, `mode="inline"` only |
+| `currentColor` | boolean | Dots use `currentColor` instead of `--sc-primary` |
+
+No slots.
+
+| Static method | Description |
+|--------|-------------|
+| `Loader.show(conf?)` | Mounts the shared instance. `conf`: `mode` · `noDelay` · `announce` · `container` |
+| `Loader.hide()` | Decrements the show counter; removes the instance when it reaches zero |