@supersoniks/concorde 5.0.3 → 5.0.5

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

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

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

@@ -1,6 +1,10 @@
-# Loader 
+# Loader
 
-## Inline mode
+**`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>
@@ -8,48 +12,101 @@
   </template>
 </sonic-code>
 
-## CurrentColor 
+## Mode
+
+**`inline`** — ellipsis animation in the document flow. **`fixed`** — centered overlay (`position: fixed`); default when the tag is omitted.
 
 <sonic-code>
   <template>
-    <sonic-loader mode="inline" currentColor style="color:purple;"></sonic-loader>
+    <sonic-loader mode="inline"></sonic-loader>
   </template>
 </sonic-code>
 
+Use the checkbox below to toggle a **`fixed`** loader over the page (default **`mode`** on **`sonic-loader`**).
 
-## Align
+<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+
+## Inline alignment and color
+
+**`align`** only affects **`mode="inline"`**: **`left`** · **`center`** (default) · **`right`**. Set **`currentColor`** so dots follow the host `color` (for example on a purple parent).
 
 <sonic-code>
   <template>
-    <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="grid gap-4">
+      <sonic-loader mode="inline" currentColor style="color: purple;"></sonic-loader>
+      <div class="flex flex-col gap-2">
+        <sonic-loader mode="inline" align="left"></sonic-loader>
+        <sonic-loader mode="inline" align="center"></sonic-loader>
+        <sonic-loader mode="inline" align="right"></sonic-loader>
+      </div>
+    </div>
   </template>
 </sonic-code>
 
-## Fixed mode
+## `noDelay`
 
-<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
+By default **`mode="fixed"`** waits briefly before fading in. **`mode="inline"`** already skips that wait. Set **`noDelay`** on **`fixed`** (or pass **`noDelay: true`** to **`Loader.show()`**) to appear immediately.
 
+<sonic-code>
+  <template>
+    <sonic-loader mode="inline" noDelay></sonic-loader>
+  </template>
+</sonic-code>
+
+## Accessibility (`announce`)
+
+The animation is **`aria-hidden`** by default so screen readers are not spammed on every fetch. Set **`announce`** when the loader is injected **after** user action (for example a global overlay): the host gets **`role="status"`**, **`aria-live="polite"`**, and a localized **`aria-label`** (“Loading” / “Chargement en cours”, …). For in-button loading, prefer **`sonic-button`** **`loading`** and **`aria-busy`** on the control—not on the loader.
 
-## Loading button
 <sonic-code>
   <template>
-    <sonic-button loading>A loading button</sonic-button>
+    <sonic-loader mode="inline" announce></sonic-loader>
   </template>
 </sonic-code>
 
-## Hide / show programmatically
+## Show and hide programmatically
+
+Import **`Loader`** and call **`Loader.show()`** / **`Loader.hide()`**. **`hide()`** is reference-counted: call it once per **`show()`**. With no **`container`**, the loader is appended to the theme pop container and **`mode`** is always **`fixed`**. Pass **`container`** and **`mode: "inline"`** to mount an inline instance in a specific element.
 
 <sonic-code language="javascript">
   <template>
-  import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
-  // Show 
-  Loader.show({
-    mode:"fixed" // optional : fixed | inline
-    container : document.querySelector('#foo') // optional, default : parent sonic-theme || document.body
-  });
-  // Hide 
-  Loader.hide();
+import { Loader } from "@supersoniks/concorde/core/components/ui/loader/loader";
+
+Loader.show({
+  mode: "fixed",
+  noDelay: false,
+  announce: true,
+  container: document.querySelector("#foo"),
+});
+
+Loader.hide();
   </template>
-</sonic-code>
+</sonic-code>
+
+## Composition
+
+**`sonic-button`** **`loading`** shows an icon spinner and sets **`aria-busy`** on the button. **`sonic-fetch`** and **`sonic-list`** render **`sonic-loader`** when their **`loader`** attribute is set: **`true`** or an empty string maps to **`fixed`**; otherwise use **`inline`** or **`fixed`**.
+
+<sonic-code>
+  <template>
+    <sonic-button loading>Save changes</sonic-button>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `mode` | `inline` · `fixed` (default `fixed`) | Layout: in-flow ellipsis vs viewport-centered overlay |
+| `noDelay` | boolean | Skips the initial fade-in delay before the animation appears |
+| `announce` | boolean | **`role="status"`** and **`aria-live="polite"`** with localized loading label when the loader should be announced |
+| `align` | `left` · `center` · `right` | Horizontal alignment for **`mode="inline"`** only (attribute selector; default centered) |
+| `currentColor` | boolean | Uses `currentColor` for dot fill instead of **`--sc-primary`** |
+
+This component has **no slots**. The animation markup is internal.
+
+### Static methods
+
+| Method | Description |
+|--------|-------------|
+| `Loader.show(conf?)` | Mounts the shared loader instance. **`conf.mode`**, **`conf.noDelay`**, **`conf.announce`**, optional **`conf.container`**. Without **`container`**, uses the theme pop container and forces **`fixed`**. |
+| `Loader.hide()` | Decrements the show counter and removes the instance from the DOM when it reaches zero. |

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

@@ -1,9 +1,35 @@
 # 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.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-menu direction="row">
+      <sonic-menu-item variant="ghost">
+        <sonic-icon library="iconoir" name="home" slot="prefix"></sonic-icon>
+        Home
+      </sonic-menu-item>
+      <sonic-menu-item>
+        <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
+        Profile
+      </sonic-menu-item>
+      <sonic-menu-item type="danger">
+        <sonic-icon library="iconoir" name="log-out" slot="prefix"></sonic-icon>
+        Log out
+      </sonic-menu-item>
+    </sonic-menu>
+  </template>
+</sonic-code>
+
 ## Direction
+
+Default **`direction`** is **`column`**. Use **`row`** for horizontal toolbars or tabs.
+
 <sonic-code>
   <template>
-    <sonic-menu direction="row" >
+    <sonic-menu direction="row">
       <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="arrow-right" slot="prefix"></sonic-icon>
         Row
@@ -12,11 +38,11 @@
         <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
         Profile
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
       </sonic-menu-item>
@@ -25,7 +51,7 @@
         Log out
       </sonic-menu-item>
     </sonic-menu>
-    <sonic-menu direction ="column" >
+    <sonic-menu direction="column">
       <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="arrow-down" slot="prefix"></sonic-icon>
         Column
@@ -34,11 +60,11 @@
         <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
         Profile
       </sonic-menu-item>
-    <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
       </sonic-menu-item>
@@ -51,90 +77,83 @@
 </sonic-code>
 
 ## Size
+
+**`size`** on the menu propagates to items and the **`more`** trigger when they omit their own **`size`**.
+
 <sonic-code>
   <template>
     <div class="grid gap-3">
       <sonic-menu size="xs" direction="row">
-        <sonic-menu-item>
-          XS
-        </sonic-menu-item>
+        <sonic-menu-item>XS</sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
           Profile
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
           History
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
           Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="sm" direction="row">
-        <sonic-menu-item>
-          Small
-        </sonic-menu-item>
+        <sonic-menu-item>Small</sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
           Profile
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
           History
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
           Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu direction="row">
-        <sonic-menu-item>
-          Medium
-        </sonic-menu-item>
+        <sonic-menu-item>Medium</sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
           Profile
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
           History
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
           Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="lg" direction="row">
-        <sonic-menu-item>
-          Large
-        </sonic-menu-item>
+        <sonic-menu-item>Large</sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
           Profile
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
           History
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
           Orders
         </sonic-menu-item>
       </sonic-menu>
       <sonic-menu size="xl" direction="row">
-        <sonic-menu-item>
-          XL
-        </sonic-menu-item>
+        <sonic-menu-item>XL</sonic-menu-item>
         <sonic-menu-item>
           <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
           Profile
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
           History
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
           Orders
         </sonic-menu-item>
@@ -144,72 +163,73 @@
 </sonic-code>
 
 ## Shadow
+
+Optional **`shadow`** wraps the menu surface (no shadow when omitted).
+
 <sonic-code>
   <template>
     <div class="grid gap-3">
       <sonic-menu direction="row">
-        <sonic-menu-item>
-          None
-        </sonic-menu-item>
+        <sonic-menu-item>None</sonic-menu-item>
       </sonic-menu>
       <sonic-menu shadow="sm" direction="row">
-        <sonic-menu-item>
-          Small
-        </sonic-menu-item>
+        <sonic-menu-item>Small</sonic-menu-item>
       </sonic-menu>
       <sonic-menu shadow="md" direction="row">
-        <sonic-menu-item>
-          Medium
-        </sonic-menu-item>
+        <sonic-menu-item>Medium</sonic-menu-item>
       </sonic-menu>
       <sonic-menu shadow="lg" direction="row">
-        <sonic-menu-item>
-          Large
-        </sonic-menu-item>
+        <sonic-menu-item>Large</sonic-menu-item>
       </sonic-menu>
     </div>
   </template>
 </sonic-code>
 
 ## Align
+
+**`align`** propagates to items except square / circle **`shape`**.
+
 <sonic-code>
   <template>
-    <sonic-menu  align="center">
-      <sonic-menu-item variant="ghost">
-        <sonic-icon library="iconoir" name="home"></sonic-icon>
-        Home
-      </sonic-menu-item>
-      <sonic-menu-item>
-        <sonic-icon library="iconoir" name="user"></sonic-icon>
-        Profile
-      </sonic-menu-item>
-    </sonic-menu>
-    <sonic-menu  align="left">
-      <sonic-menu-item variant="ghost">
-        <sonic-icon library="iconoir" name="home"></sonic-icon>
-        Home
-      </sonic-menu-item>
-      <sonic-menu-item>
-        <sonic-icon library="iconoir" name="user"></sonic-icon>
-        Profile
-      </sonic-menu-item>
-    </sonic-menu>
-    <sonic-menu  align="right">
-      <sonic-menu-item variant="ghost">
-        <sonic-icon library="iconoir" name="home"></sonic-icon>
-        Home
-      </sonic-menu-item>
-      <sonic-menu-item>
-        <sonic-icon library="iconoir" name="user"></sonic-icon>
-        Profile
-      </sonic-menu-item>
-    </sonic-menu>
+    <div class="grid gap-3">
+      <sonic-menu align="center">
+        <sonic-menu-item variant="ghost">
+          <sonic-icon library="iconoir" name="home"></sonic-icon>
+          Home
+        </sonic-menu-item>
+        <sonic-menu-item>
+          <sonic-icon library="iconoir" name="user"></sonic-icon>
+          Profile
+        </sonic-menu-item>
+      </sonic-menu>
+      <sonic-menu align="left">
+        <sonic-menu-item variant="ghost">
+          <sonic-icon library="iconoir" name="home"></sonic-icon>
+          Home
+        </sonic-menu-item>
+        <sonic-menu-item>
+          <sonic-icon library="iconoir" name="user"></sonic-icon>
+          Profile
+        </sonic-menu-item>
+      </sonic-menu>
+      <sonic-menu align="right">
+        <sonic-menu-item variant="ghost">
+          <sonic-icon library="iconoir" name="home"></sonic-icon>
+          Home
+        </sonic-menu-item>
+        <sonic-menu-item>
+          <sonic-icon library="iconoir" name="user"></sonic-icon>
+          Profile
+        </sonic-menu-item>
+      </sonic-menu>
+    </div>
   </template>
 </sonic-code>
 
+## More
 
+Assign nodes to **`slot="more"`** to show the overflow popover. The trigger appears only when the slot has content. Icon orientation follows **`direction`** (vertical ellipsis in a row menu).
 
-## More
 <sonic-code>
   <template>
     <sonic-menu direction="row">
@@ -221,20 +241,20 @@
         <sonic-icon library="iconoir" name="user"></sonic-icon>
         Profile
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
       </sonic-menu-item>
       <sonic-menu slot="more">
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="settings" slot="prefix"></sonic-icon>
           Settings
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="chat-bubble" slot="prefix"></sonic-icon>
           Messages
         </sonic-menu-item>
@@ -249,6 +269,9 @@
 </sonic-code>
 
 ## Scrollable
+
+With **`scrollable`**, the main slot scrolls with edge fade masks; drag-to-scroll works on pointer devices. When exactly one item is **`active`**, the menu scrolls it into view.
+
 <sonic-code>
   <template>
     <sonic-menu direction="row" scrollable>
@@ -260,14 +283,15 @@
         <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
         Profile
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
-      </sonic-menu-item>   <sonic-menu-item variant="ghost">
+      </sonic-menu-item>
+      <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="home" slot="prefix"></sonic-icon>
         Home
       </sonic-menu-item>
@@ -275,14 +299,15 @@
         <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
         Profile
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
-      </sonic-menu-item>   <sonic-menu-item variant="ghost">
+      </sonic-menu-item>
+      <sonic-menu-item variant="ghost">
         <sonic-icon library="iconoir" name="home" slot="prefix"></sonic-icon>
         Home
       </sonic-menu-item>
@@ -290,28 +315,28 @@
         <sonic-icon library="iconoir" name="user" slot="prefix"></sonic-icon>
         Profile
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="clock-outline" slot="prefix"></sonic-icon>
         History
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="bag" slot="prefix"></sonic-icon>
         Orders
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="settings" slot="prefix"></sonic-icon>
         Settings
       </sonic-menu-item>
-      <sonic-menu-item >
+      <sonic-menu-item>
         <sonic-icon library="iconoir" name="chat-bubble" slot="prefix"></sonic-icon>
         Messages
       </sonic-menu-item>
       <sonic-menu slot="more">
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="settings" slot="prefix"></sonic-icon>
           Settings
         </sonic-menu-item>
-        <sonic-menu-item >
+        <sonic-menu-item>
           <sonic-icon library="iconoir" name="chat-bubble" slot="prefix"></sonic-icon>
           Messages
         </sonic-menu-item>
@@ -321,9 +346,25 @@
           Log out
         </sonic-menu-item>
       </sonic-menu>
-      
+    </sonic-menu>
   </template>
 </sonic-code>
 
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `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 |
+| `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`** |
+| `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.