@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -1,41 +1,70 @@
 # 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.
+**`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
 
-With no `rounded`, corners are square. Boolean `rounded` uses the theme token `--sc-rounded`; `full` draws a circle when paired with `ratio="1/1"`.
+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 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>
+        <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="img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
         <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>
+        <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="img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
         <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>
+        <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="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <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>
-        <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 >
+          <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>
@@ -43,47 +72,70 @@ With no `rounded`, corners are square. Boolean `rounded` uses the theme token `-
 
 ## Aspect ratio
 
-`ratio` sets CSS `aspect-ratio` on the image (default `auto`). The image always fills the host width.
+**`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="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>
+      <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`). Use it on wide crops when the subject sits off-center.
+**`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="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>
+      <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 over a **positioned** parent (`position: relative` with a height). `ratio` is ignored while `cover` is set.
+**`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="img/concorde/plane_10.jpg" alt="Concorde fleet parked in a star"></sonic-image>
+      <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` 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).
+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>
@@ -98,8 +150,7 @@ Set `transition` to `fade` or `fade-scale-out`. The image stays transparent unti
           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';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
           host.appendChild(img);
         })()"
       >
@@ -116,8 +167,7 @@ Set `transition` to `fade` or `fade-scale-out`. The image stays transparent unti
           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';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
           host.appendChild(img);
         })()"
       >
@@ -135,17 +185,17 @@ Set `transition` to `fade` or `fade-scale-out`. The image stays transparent unti
   </template>
 </sonic-code>
 
-## Accessibility
+## Accessibility and parts
 
-Always set a meaningful `alt`. Use `alt=""` only for decorative images.
+Always set meaningful **`alt`** text (empty string 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"
+      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>
@@ -155,13 +205,29 @@ Always set a meaningful `alt`. Use `alt=""` only for decorative images.
 | 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.
+| `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

@@ -26,7 +26,7 @@ Set **`pushstate`** on same-origin **`href`** values to intercept clicks and nav
 
 <sonic-code>
   <template>
-    <sonic-link href="/core/components/ui/link" pushstate>Client navigation (pushstate)</sonic-link>
+    <sonic-link href="/#core/components" pushstate>Client navigation (pushstate)</sonic-link>
   </template>
 </sonic-code>
 
@@ -36,7 +36,7 @@ Default **`autoActive`** is **`partial`**: the host gets **`active`** when the c
 
 <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>
 
@@ -47,9 +47,9 @@ Default **`autoActive`** is **`partial`**: the host gets **`active`** when the c
 <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>
+      <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>
@@ -58,7 +58,7 @@ Default **`autoActive`** is **`partial`**: the host gets **`active`** when the c
 
 <sonic-code>
   <template>
-    <sonic-link href="/core/components/ui/link" autoActive="disabled" class="[&[active]]:text-success">autoActive disabled</sonic-link>
+    <sonic-link href="/#core/components/ui/link/link.md/link" autoActive="disabled" class="[&[active]]:text-success">autoActive disabled</sonic-link>
   </template>
 </sonic-code>
 

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

@@ -1,10 +1,20 @@
 # 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.
+**`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` renders an ellipsis animation in the document flow. `fixed` (default) covers the viewport with a centered animation; toggle it with the checkbox below.
+**`inline`** — ellipsis animation in the document flow. **`fixed`** — centered overlay (`position: fixed`); default when the tag is omitted.
 
 <sonic-code>
   <template>
@@ -12,26 +22,30 @@
   </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>
 
-## Alignment and color
+## Inline alignment and color
 
-`align` only affects `mode="inline"`: `left` · `center` (default) · `right`. Dots use `--sc-primary`; set `currentColor` to follow the host `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>
-      <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="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>
 
-## Delay
+## `noDelay`
 
-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.
+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>
@@ -39,33 +53,42 @@ A `fixed` loader waits 0.5 s before fading in, so short requests show nothing. `
   </template>
 </sonic-code>
 
-## Accessibility
+## Accessibility (`announce`)
 
-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.
+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>
-    <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>
+    <sonic-loader mode="inline" announce></sonic-loader>
   </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`.**
+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/ui/loader";
+import { Loader } from "@supersoniks/concorde/core/components/ui/loader/loader";
+
+Loader.show({
+  mode: "fixed",
+  noDelay: false,
+  announce: true,
+  container: document.querySelector("#foo"),
+});
 
-Loader.show({ announce: true });
-// …
 Loader.hide();
+  </template>
+</sonic-code>
+
+## Composition
 
-// Inline loader inside a given element
-Loader.show({ mode: "inline", container: document.querySelector("#results") });
+**`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>
 
@@ -73,15 +96,17 @@ Loader.show({ mode: "inline", container: document.querySelector("#results") });
 
 | 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` |
+| `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.
 
-No slots.
+### Static methods
 
-| Static method | Description |
+| 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 |
+| `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/docs/src/core/components/ui/menu/menu.md

@@ -1,6 +1,6 @@
 # Menu
 
-**`sonic-menu`** lays out navigation or actions as a **`direction`** row or column of **`sonic-menu-item`** entries (ghost **`variant`** and block **`shape`** by default), optional **`sonic-divider`** separators, and overflow content in the **`more`** slot (popover “…” trigger). Set `href` / `pushstate` / `autoActive` on each `sonic-menu-item` (same API as `sonic-button`), not on the menu host.
+**`sonic-menu`** lays out navigation or actions as a **`direction`** row or column of **`sonic-menu-item`** entries (ghost **`variant`** and block **`shape`** by default), optional **`sonic-divider`** separators, and overflow content in the **`more`** slot (popover “…” trigger). Set **`href`** / **`pushstate`** / **`autoActive`** on each **`sonic-menu-item`**—same API as **`sonic-button`**—not on the menu host.
 
 ## Basic example
 
@@ -40,11 +40,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu-item type="danger">
         <sonic-icon library="iconoir" name="log-out" slot="prefix"></sonic-icon>
@@ -62,11 +62,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu-item type="danger">
         <sonic-icon library="iconoir" name="log-out" slot="prefix"></sonic-icon>
@@ -91,11 +91,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-          Flights
+          History
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Baggage
+          Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="sm" direction="row">
@@ -106,11 +106,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-          Flights
+          History
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Baggage
+          Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu direction="row">
@@ -121,11 +121,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-          Flights
+          History
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Baggage
+          Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="lg" direction="row">
@@ -136,11 +136,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-          Flights
+          History
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Baggage
+          Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="xl" direction="row">
@@ -151,11 +151,11 @@ Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars o
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-          Flights
+          History
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Baggage
+          Orders
         </sonic-menu-item>
       </sonic-menu>
     </div>
@@ -243,11 +243,11 @@ Assign nodes to **`slot="more"`** to show the overflow popover. The trigger appe
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu slot="more">
         <sonic-menu-item>
@@ -285,11 +285,11 @@ With **`scrollable`**, the main slot scrolls with edge fade masks; drag-to-scrol
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="home" slot="prefix"></sonic-icon>
@@ -301,11 +301,11 @@ With **`scrollable`**, the main slot scrolls with edge fade masks; drag-to-scrol
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="home" slot="prefix"></sonic-icon>
@@ -317,11 +317,11 @@ With **`scrollable`**, the main slot scrolls with edge fade masks; drag-to-scrol
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
-        Flights
+        History
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Baggage
+        Orders
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="settings" slot="prefix"></sonic-icon>
@@ -356,15 +356,15 @@ With **`scrollable`**, the main slot scrolls with edge fade masks; drag-to-scrol
 |----------|---------|-------------|
 | `direction` | `column` (default) · `row` | Vertical list or horizontal bar |
 | `align` | `left` (default) · `center` · `right` | Alignment propagated to items (except square / circle **`shape`**) |
-| `size` | `2xs` … `2xl` (default: items keep their own size) | Propagated to items and the **`more`** trigger when unset on the item |
-| `shadow` | `none` · `sm` · `md` · `lg` | Shadow around the menu; none when omitted |
+| `size` | `xs` · `sm` · `md` · `lg` · `xl` | Propagated to items and the **`more`** trigger when unset on the item |
+| `shadow` | `sm` · `md` · `lg` | Shadow around the menu; omitted for none |
 | `minWidth` | CSS length | Minimum width of the container (default `0`) |
 | `scrollable` | boolean | Scroll with edge fade; auto-scroll when a single item is **`active`** |
 | `moreShape` | `circle` (default) · `square` | Shape of the **`more`** slot trigger button |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Visible items: `sonic-menu-item` · `sonic-divider` · nested `sonic-menu` |
+| *(default)* | Visible items: **`sonic-menu-item`**, **`sonic-divider`**, nested **`sonic-menu`** |
 | `more` | Popover content for the “…” control; shown only when the slot has assigned nodes |
 
-**`sonic-menu-item`** extends **`sonic-button`** (defaults `variant="ghost"` and `shape="block"`). See [Button](/core/components/ui/button) for `type` · `variant` · `href` · `pushstate` · `autoActive` and the item slots.
+**`sonic-menu-item`** extends **`sonic-button`** (defaults: **`variant="ghost"`**, **`shape="block"`**). Use the button docs for **`type`**, **`variant`**, **`href`**, **`pushstate`**, **`autoActive`**, and item slots.