@supersoniks/concorde 5.1.1 → 5.1.2

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

@@ -0,0 +1,214 @@
+# Icon
+
+**`sonic-icon`** renders inline SVG icons from the **bundled core set** or from **CDN libraries**. Set **`name`** (and **`library`** / **`prefix`** when needed); scale with **`size`**. Icons inherit **`currentColor`** and are **`aria-hidden`** by default—keep visible text nearby or label the control that contains them.
+
+## Core library
+
+Omit **`library`** to use the bundled set in `icons.json`. Available **`name`** values: `cancel` · `check` · `check-circled-outline` · `emoji-puzzled` · `info-empty` · `loader` · `minus-small` · `more-horiz` · `more-vert` · `nav-arrow-down` · `warning-circled-outline`.
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
+      <div class="text-center">
+        <sonic-icon name="cancel" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">cancel</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="check" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">check</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="check-circled-outline" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">check-circled-outline</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="emoji-puzzled" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">emoji-puzzled</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="info-empty" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">info-empty</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="loader" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">loader</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="minus-small" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">minus-small</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="more-horiz" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">more-horiz</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="more-vert" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">more-vert</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="nav-arrow-down" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">nav-arrow-down</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon name="warning-circled-outline" size="lg"></sonic-icon>
+        <div class="text-xs mt-1">warning-circled-outline</div>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+## External libraries
+
+Set **`library`** to load SVGs from a built-in CDN template. **`prefix`** falls back to each library’s default when omitted (`outline` for **`heroicons`**, **`regular`** for **`fontAwesome`** and **`material`**, and so on).
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
+      <sonic-link href="https://heroicons.com/" target="_blank" class="text-center underline">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">heroicons</div>
+      </sonic-link>
+      <sonic-link href="https://iconoir.com/" target="_blank" class="text-center underline">
+        <sonic-icon library="iconoir" name="2x2-cell" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">iconoir</div>
+      </sonic-link>
+      <sonic-link href="https://materialdesignicons.com/" target="_blank" class="text-center underline">
+        <sonic-icon library="material" prefix="outline" name="email" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">material design</div>
+      </sonic-link>
+      <sonic-link href="https://fontawesome.com/search?o=r&m=free&s=regular" target="_blank" class="text-center underline">
+        <sonic-icon library="fontAwesome" prefix="regular" name="user" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">fontAwesome regular</div>
+      </sonic-link>
+      <sonic-link href="https://fontawesome.com/search?o=r&m=free&s=solid" target="_blank" class="text-center underline">
+        <sonic-icon library="fontAwesome" prefix="solid" name="book" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">fontAwesome solid</div>
+      </sonic-link>
+      <sonic-link href="https://feathericons.com/" target="_blank" class="text-center underline">
+        <sonic-icon library="feathers" name="activity" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">feathers</div>
+      </sonic-link>
+      <sonic-link href="https://lucide.dev/" target="_blank" class="text-center underline">
+        <sonic-icon library="lucide" name="album" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">lucide</div>
+      </sonic-link>
+    </div>
+  </template>
+</sonic-code>
+
+## Custom library
+
+Use **`library="custom"`** with SVG files on your origin. On an ancestor (for example **`sonic-scope`** or **`sonic-code`**), set **`customIconLibraryPath`** to a URL template with **`$prefix`** and **`$name`** placeholders, and optionally **`customIconDefaultPrefix`** when **`prefix`** is omitted.
+
+<sonic-code
+  customIconLibraryPath="/svg/$prefix/$name.svg"
+  customIconDefaultPrefix="regular"
+>
+  <template>
+    <sonic-scope
+      customIconLibraryPath="/svg/$prefix/$name.svg"
+      customIconDefaultPrefix="regular"
+    >
+      <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
+        <div class="text-center">
+          <sonic-icon library="custom" prefix="regular" name="plane"></sonic-icon>
+          <br />
+          <div class="text-xs mt-1">regular</div>
+        </div>
+        <div class="text-center">
+          <sonic-icon library="custom" prefix="solid" name="plane"></sonic-icon>
+          <br />
+          <div class="text-xs mt-1">solid</div>
+        </div>
+        <div class="text-center">
+          <sonic-icon library="custom" name="plane"></sonic-icon>
+          <br />
+          <div class="text-xs mt-1">default prefix</div>
+        </div>
+      </div>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Size
+
+Omit **`size`** for the default scale (`1em` height, inherited from the font size). Steps go from `2xs` to `3xl`.
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="2xs"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">2xs</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="xs"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">xs</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="sm"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">sm</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">default</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="lg"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">lg</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="xl"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">xl</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="2xl"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">2xl</div>
+      </div>
+      <div class="text-center">
+        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="3xl"></sonic-icon>
+        <br />
+        <div class="text-xs mt-1">3xl</div>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+On connect, the host sets **`aria-hidden="true"`**. Treat icons as decorative unless the surrounding control already has an accessible name. Do not rely on **`sonic-icon`** alone for meaning—use visible text or **`aria-label`** on the parent button / link.
+
+<sonic-code>
+  <template>
+    <sonic-button type="neutral" variant="outline" shape="circle" aria-label="Flight details">
+      <sonic-icon library="iconoir" name="airplane"></sonic-icon>
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `name` | string | Icon id in the core bundle or in the remote library |
+| `library` | `heroicons` · `iconoir` · `feathers` · `lucide` · `material` · `fontAwesome` · `custom` | CDN or custom template; omit for bundled core icons |
+| `prefix` | string | Library-specific variant; defaults per library when empty |
+| `size` | `2xs` · `xs` · `sm` · `lg` · `xl` · `2xl` · `3xl` (default `1em`, no attribute) | `em`-based SVG scale on the host |
+
+Ancestor attributes (for **`library="custom"`** only): **`customIconLibraryPath`** (URL template with **`$prefix`** and **`$name`**) and **`customIconDefaultPrefix`**. May be set on **`sonic-scope`**, theme roots, or globally in the document.
+
+No slots — the component inlines fetched or bundled SVG markup.

package/docs/src/core/components/ui/icon/icons.json

@@ -0,0 +1 @@
+{"core":{"cancel":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M6.75827 17.2426L12.0009 12M17.2435 6.75736L12.0009 12M12.0009 12L6.75827 6.75736M12.0009 12L17.2435 17.2426\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","check-circled-outline":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M7 12.5L10 15.5L17 8.5\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 22C17.5228 22 22 17.5228 22 12C22 6.47715 17.5228 2 12 2C6.47715 2 2 6.47715 2 12C2 17.5228 6.47715 22 12 22Z\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","check":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M5 13L9 17L19 7\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","emoji-puzzled":"<svg width=\"24px\" height=\"24px\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" ><path d=\"M2 12c0 5.523 4.477 10 10 10s10-4.477 10-10S17.523 2 12 2\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"></path><path d=\"M11.5 15.5s1.5-2 4.5-2 4.5 2 4.5 2M3 4c0-2.754 4-2.754 4 0 0 1.967-2 1.64-2 4M5 11.01l.01-.011\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"></path><path d=\"M17.5 9a.5.5 0 110-1 .5.5 0 010 1zM10.5 9a.5.5 0 110-1 .5.5 0 010 1z\" fill=\"#000\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"></path></svg>","info-empty":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12 11.5V16.5\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 7.51L12.01 7.49889\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 22C17.5228 22 22 17.5228 22 12C22 6.47715 17.5228 2 12 2C6.47715 2 2 6.47715 2 12C2 17.5228 6.47715 22 12 22Z\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","loader":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" class=\"feather feather-loader\"><line x1=\"12\" y1=\"2\" x2=\"12\" y2=\"6\"></line><line x1=\"12\" y1=\"18\" x2=\"12\" y2=\"22\"></line><line x1=\"4.93\" y1=\"4.93\" x2=\"7.76\" y2=\"7.76\"></line><line x1=\"16.24\" y1=\"16.24\" x2=\"19.07\" y2=\"19.07\"></line><line x1=\"2\" y1=\"12\" x2=\"6\" y2=\"12\"></line><line x1=\"18\" y1=\"12\" x2=\"22\" y2=\"12\"></line><line x1=\"4.93\" y1=\"19.07\" x2=\"7.76\" y2=\"16.24\"></line><line x1=\"16.24\" y1=\"7.76\" x2=\"19.07\" y2=\"4.93\"></line></svg>","minus-small":"<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"none\" viewBox=\"0 0 24 24\" stroke-width=\"1.5\" stroke=\"currentColor\" class=\"w-6 h-6\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M18 12H6\" />\n</svg>\n","more-horiz":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M18 12.5C18.2761 12.5 18.5 12.2761 18.5 12C18.5 11.7239 18.2761 11.5 18 11.5C17.7239 11.5 17.5 11.7239 17.5 12C17.5 12.2761 17.7239 12.5 18 12.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 12.5C12.2761 12.5 12.5 12.2761 12.5 12C12.5 11.7239 12.2761 11.5 12 11.5C11.7239 11.5 11.5 11.7239 11.5 12C11.5 12.2761 11.7239 12.5 12 12.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M6 12.5C6.27614 12.5 6.5 12.2761 6.5 12C6.5 11.7239 6.27614 11.5 6 11.5C5.72386 11.5 5.5 11.7239 5.5 12C5.5 12.2761 5.72386 12.5 6 12.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","more-vert":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12 12.5C12.2761 12.5 12.5 12.2761 12.5 12C12.5 11.7239 12.2761 11.5 12 11.5C11.7239 11.5 11.5 11.7239 11.5 12C11.5 12.2761 11.7239 12.5 12 12.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 18.5C12.2761 18.5 12.5 18.2761 12.5 18C12.5 17.7239 12.2761 17.5 12 17.5C11.7239 17.5 11.5 17.7239 11.5 18C11.5 18.2761 11.7239 18.5 12 18.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 6.5C12.2761 6.5 12.5 6.27614 12.5 6C12.5 5.72386 12.2761 5.5 12 5.5C11.7239 5.5 11.5 5.72386 11.5 6C11.5 6.27614 11.7239 6.5 12 6.5Z\" fill=\"currentColor\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","nav-arrow-down":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M6 9L12 15L18 9\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n","warning-circled-outline":"<svg width=\"24\" height=\"24\" stroke-width=\"1.5\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M12 7L12 13\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 17.01L12.01 16.9989\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n<path d=\"M12 22C17.5228 22 22 17.5228 22 12C22 6.47715 17.5228 2 12 2C6.47715 2 2 6.47715 2 12C2 17.5228 6.47715 22 12 22Z\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n"}}

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

@@ -0,0 +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-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>
+
+## 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="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 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 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);
+        })()"
+      >
+        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

@@ -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/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>
+  </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/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>
+
+### AutoActive disabled
+
+<sonic-code>
+  <template>
+    <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

@@ -0,0 +1,87 @@
+# Loader
+
+**`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>
+    <sonic-loader mode="inline"></sonic-loader>
+  </template>
+</sonic-code>
+
+<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>
+    <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
+
+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" noDelay></sonic-loader>
+  </template>
+</sonic-code>
+
+## 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.
+
+<sonic-code>
+  <template>
+    <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>
+
+## 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/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>
+
+## 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 |