@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -1,70 +1,41 @@
 # 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.
+**`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
 
-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).
+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 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>
+        <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="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-        ></sonic-image>
+        <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="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="/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="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="/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="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="/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="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-        ></sonic-image>
+        <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 >
-        <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>
+        <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>
@@ -72,70 +43,47 @@ Omit `rounded` for square corners. Boolean **`rounded`** uses the theme token `-
 
 ## Aspect ratio
 
-**`ratio`** sets CSS `aspect-ratio` on the image (default **`auto`**). The image still fills the host width (`width: 100%`).
+`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`**). Useful on wide crops when the subject sits off-center.
+`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="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>
+      <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 to fill a **positioned** parent (`position: relative` + fixed height or inset). Aspect ratio on the host is ignored while `cover` is set.
+`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="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      ></sonic-image>
+      <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`** (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.
+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>
@@ -150,7 +98,8 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
           img.rounded = 'md';
           img.loading = 'eager';
           img.style.width = '8rem';
-          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          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);
         })()"
       >
@@ -167,7 +116,8 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
           img.rounded = 'md';
           img.loading = 'eager';
           img.style.width = '8rem';
-          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          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);
         })()"
       >
@@ -185,17 +135,17 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
   </template>
 </sonic-code>
 
-## Accessibility and parts
+## Accessibility
 
-Always set meaningful **`alt`** text (empty string only for decorative images). 
+Always set a meaningful `alt`. Use `alt=""` 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"
+      alt="Crowd gathered around Concorde at night"
+      src="/img/concorde/plane_07.jpg"
     ></sonic-image>
   </template>
 </sonic-code>
@@ -205,29 +155,13 @@ Always set meaningful **`alt`** text (empty string only for decorative images).
 | 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>`.
+| `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/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" pushstate>Client navigation (pushstate)</sonic-link>
+    <sonic-link href="/core/components/ui/link" 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" 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>
+      <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>
@@ -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/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>
 

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

@@ -1,20 +1,10 @@
 # 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>
+**`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`** — ellipsis animation in the document flow. **`fixed`** — centered overlay (`position: fixed`); default when the tag is omitted.
+`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>
@@ -22,30 +12,26 @@ Inline loaders fit content areas; they use the theme primary color unless **`cur
   </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
+## 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).
+`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>
-      <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>
+      <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>
 
-## `noDelay`
+## Delay
 
-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.
+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>
@@ -53,42 +39,33 @@ By default **`mode="fixed"`** waits briefly before fading in. **`mode="inline"`*
   </template>
 </sonic-code>
 
-## Accessibility (`announce`)
+## Accessibility
 
-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.
+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>
-    <sonic-loader mode="inline" announce></sonic-loader>
+    <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
 
-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.
+`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";
-
-Loader.show({
-  mode: "fixed",
-  noDelay: false,
-  announce: true,
-  container: document.querySelector("#foo"),
-});
+import { Loader } from "@supersoniks/concorde/ui/loader";
 
+Loader.show({ announce: true });
+// …
 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>
+// Inline loader inside a given element
+Loader.show({ mode: "inline", container: document.querySelector("#results") });
   </template>
 </sonic-code>
 
@@ -96,17 +73,15 @@ Loader.hide();
 
 | 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.
+| `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` |
 
-### Static methods
+No slots.
 
-| Method | Description |
+| Static 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. |
+| `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 |

package/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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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>
-          History
+          Flights
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Orders
+          Baggage
         </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>
-          History
+          Flights
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Orders
+          Baggage
         </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>
-          History
+          Flights
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Orders
+          Baggage
         </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>
-          History
+          Flights
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Orders
+          Baggage
         </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>
-          History
+          Flights
         </sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-          Orders
+          Baggage
         </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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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>
-        History
+        Flights
       </sonic-menu-item>
       <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
-        Orders
+        Baggage
       </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` | `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 |
+| `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 |
 | `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"`**, **`shape="block"`**). Use the button docs for **`type`**, **`variant`**, **`href`**, **`pushstate`**, **`autoActive`**, and item slots.
+**`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.