@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -1,69 +1,50 @@
-## Modal
+# Modal
+
+**`sonic-modal`** shows focused content in a dialog with a backdrop, an enter / exit animation and a built-in close button. Compose it with **`sonic-modal-title`** · **`sonic-modal-subtitle`** · **`sonic-modal-content`** · **`sonic-modal-actions`**, open it with **`show()`** and close it with **`hide()`** or a **`hideModal`** button.
+
+## Basic example
+
+Backdrop click, Escape and the close button all close the modal. In **`sonic-modal-actions`**, a **`sonic-button`** with **`hideModal`** closes it on click.
 
 <sonic-code>
   <template>
     <sonic-button onclick="document.getElementById('modalExample').show()">
-      Simple modal
+      Open modal
     </sonic-button>
     <sonic-modal id="modalExample">
-      <sonic-modal-title
-        >Lorem ipsum dolor sit amet <sonic-badge type="danger" size="sm">+33</sonic-badge></sonic-modal-title
-      >
-      <sonic-modal-subtitle>Donec sed vestibulum augue.</sonic-modal-subtitle>
+      <sonic-modal-title>
+        Boarding pass ready
+        <sonic-badge type="success" size="sm">New</sonic-badge>
+      </sonic-modal-title>
+      <sonic-modal-subtitle>Your check-in is complete.</sonic-modal-subtitle>
       <sonic-modal-content>
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus.
+        Download your boarding pass now or review your seat before departure.
       </sonic-modal-content>
-      <sonic-modal-actions formDataProvider="ModalMiniForm">
-        <sonic-button FormCheckable  minWidth="8rem" value="true" name="click">
-          Click don't close
-        </sonic-button>
-        <sonic-button minWidth="8rem" type="success" hideModal>Confirm</sonic-button>
+      <sonic-modal-actions>
+        <sonic-button minWidth="8rem" hideModal>Later</sonic-button>
+        <sonic-button minWidth="8rem" type="success" hideModal>Download</sonic-button>
       </sonic-modal-actions>
     </sonic-modal>
   </template>
 </sonic-code>
 
+**`hideModal`** only works on **`sonic-button`** elements that are direct children of **`sonic-modal-actions`**.
 
-## Long text
+## Scrollable content
+
+Long content scrolls inside the dialog once it reaches **`maxHeight`** (default `90vh`). Content is left-aligned by default; set **`align`** to `center` or `right`.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="document.getElementById('modalText').show()"> Long text </sonic-button>
-    <sonic-modal align="left" id="modalText">
-      <sonic-modal-title>Infos et tarifs </sonic-modal-title>
+    <sonic-button onclick="document.getElementById('modalText').show()">Baggage details</sonic-button>
+    <sonic-modal id="modalText" maxHeight="20rem">
+      <sonic-modal-title>Baggage allowance</sonic-modal-title>
       <sonic-modal-content>
         <div class="prose">
-          <p>
-            <strong>Horaires d’ouverture </strong><br />
-            Du mercredi au samedi de 13h30 à 19h et le dimanche de 13h30 à 18h<br />
-            + horaires spécifiques pour événements ou festivals&nbsp;
-          </p>
-          <p>
-            <strong> Billetterie&nbsp;<br /></strong>
-            La participation à certains événements et activités est soumise à un système de billetterie avec achats ou
-            réservations disponibles en ligne ou au guichet.&nbsp;&nbsp;<strong><br /></strong>
-          </p>
-          <p>
-            Les tarifs (Tarif plein / Tarif Réduit / Tarif Spécifique) sont indiqués pour chaque événement et peuvent
-            varier selon la nature de l’événement. Les tarifs sont identiques en ligne et au guichet. Il est néanmoins
-            conseillé de réserver les billets en avance pour s’assurer une place.
-          </p>
-          <p>
-            L’accès au Skatepark, Fablab et Halle C sont soumis à adhésions. Les adhésions sont gratuites et
-            nominatives. Elle donnent accès aux espaces dans la limite des places disponibles.
-          </p>
-          <p>
-            <strong>+ d’infos <br /></strong>billetterie@laconditionpublique.com <br />+33 (0)328334833&nbsp;
-          </p>
-          <br />
-          <p>
-            <strong>Accès <br /></strong>14, place Faidherbe <br />59100 Roubaix <br />Métro / Tram : Arrêt
-            Eurotéléport, Ligne 2 <br />Bus / V’Lille : Arrêt Condition Publique&nbsp;
-          </p>
-          <p>
-            Accès handicapés : nous contacter avant votre venue au 03 28 33 48 33 ou par mail
-            billetterie@laconditionpublique.com
-          </p>
+          <p><strong>Cabin bag</strong><br />One cabin bag and one personal item are included in every cabin class.</p>
+          <p><strong>Checked baggage</strong><br />Drop checked bags at the counter at least one hour before departure.</p>
+          <p><strong>Extra baggage</strong><br />Add extra baggage online up to 24 hours before the flight.</p>
+          <p><strong>Contact</strong><br />support@example.com</p>
         </div>
       </sonic-modal-content>
     </sonic-modal>
@@ -72,33 +53,43 @@
 
 ## Force action
 
+With **`forceAction`**, backdrop click, Escape and the close button are disabled. Provide **`hideModal`** buttons so users can finish the flow. **`noCloseButton`** only hides the close button.
+
 <sonic-code>
   <template>
-    <sonic-button onclick="document.getElementById('force').show()"> Force action to close</sonic-button>
+    <sonic-button onclick="document.getElementById('force').show()">Cookie consent</sonic-button>
     <sonic-modal forceAction id="force">
-      <sonic-modal-title>Do you want some cookies ? </sonic-modal-title>
+      <sonic-modal-title>Allow analytics cookies?</sonic-modal-title>
       <sonic-modal-content>
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus.
+        Analytics cookies measure traffic. You can change this later in settings.
       </sonic-modal-content>
-      <sonic-modal-actions >
-        <sonic-button hideModal minWidth="8rem"> Nope </sonic-button>
-        <sonic-button hideModal minWidth="8rem" type="success">Hell yes !</sonic-button>
+      <sonic-modal-actions>
+        <sonic-button hideModal minWidth="8rem">Decline</sonic-button>
+        <sonic-button hideModal minWidth="8rem" type="success">Accept</sonic-button>
       </sonic-modal-actions>
     </sonic-modal>
-    </sonic-modal>
   </template>
 </sonic-code>
 
-## Custom dimensions
+## Dimensions
+
+Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS lengths. Below 768px the panel becomes a bottom sheet. **`rounded="none"`** removes the corner radius for edge-to-edge media.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="document.getElementById('CustomWidth').show()"> Custom width </sonic-button>
-    <sonic-modal maxHeight="50vh" maxWidth="90vw" width="100%" height="100%" id="CustomWidth">
+    <sonic-button onclick="document.getElementById('CustomWidth').show()">Image preview</sonic-button>
+    <sonic-modal
+      rounded="none"
+      maxHeight="50vh"
+      maxWidth="90vw"
+      width="100%"
+      height="100%"
+      id="CustomWidth"
+    >
       <sonic-image
         cover
-        objectPosition="center 20%"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        src="img/concorde/plane_12.jpg"
+        alt="Concorde at the gate with boarding stairs"
       ></sonic-image>
     </sonic-modal>
   </template>
@@ -106,14 +97,115 @@
 
 ## Fullscreen
 
+**`fullscreen`** fills the viewport and hides the backdrop.
+
 <sonic-code>
   <template>
-    <sonic-button onclick="document.getElementById('Fullscreen').show()"> Fullscreen </sonic-button>
+    <sonic-button onclick="document.getElementById('Fullscreen').show()">Fullscreen</sonic-button>
     <sonic-modal fullscreen id="Fullscreen">
       <sonic-image
         cover
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        src="img/concorde/plane_10.jpg"
+        alt="Concorde fleet parked in a star"
       ></sonic-image>
     </sonic-modal>
   </template>
-</sonic-code>
+</sonic-code>
+
+## Programmatic creation
+
+**`Modal.create(options)`** (also `window.SonicModal.create`) appends a modal to the theme pop container, opens it and returns the element. **`title`** · **`subtitle`** · **`content`** · **`actions`** accept HTML strings or Lit templates. Set **`removeOnHide: true`** to remove it from the DOM after closing.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="window.SonicModal.create({
+        title: 'Announce gate change?',
+        subtitle: 'Passengers are notified immediately.',
+        content: 'Flight CN 001 now departs from gate B12.',
+        actions: '&lt;sonic-button hideModal minWidth=\'8rem\'&gt;Cancel&lt;/sonic-button&gt;&lt;sonic-button hideModal minWidth=\'8rem\' type=\'success\'&gt;Send&lt;/sonic-button&gt;',
+        removeOnHide: true
+      })"
+    >
+      Open programmatic modal
+    </sonic-button>
+  </template>
+</sonic-code>
+
+<sonic-code language="typescript">
+  <template>
+import { Modal } from "@supersoniks/concorde/ui/modal";
+
+const modal = Modal.create({
+  title: "Remove flight CN 001?",
+  content: "It will no longer appear on the departures board.",
+  actions: `
+    &lt;sonic-button hideModal&gt;Cancel&lt;/sonic-button&gt;
+    &lt;sonic-button hideModal type="danger"&gt;Remove&lt;/sonic-button&gt;
+  `,
+  removeOnHide: true,
+  maxWidth: "min(100vw, 28rem)",
+});
+
+modal.addEventListener("hidden", () => console.log("closed"));
+  </template>
+</sonic-code>
+
+## API reference
+
+### `sonic-modal`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `align` | `left` (default) · `center` · `right` | Content alignment |
+| `width` | CSS length (default `100%`) | Dialog width |
+| `height` | CSS length (default `fit-content`) | Dialog height |
+| `maxWidth` | CSS length (default `min(100vw, 40rem)`) | Dialog max width |
+| `maxHeight` | CSS length (default `90vh`) | Dialog max height; content scrolls beyond |
+| `paddingX` · `paddingY` | CSS length (default `1.5rem` · `2.5rem`) | Content padding |
+| `zIndex` | number (default `990`) | Stacking order |
+| `effect` | `slide` (default) · `fade` · `none` | Open / close animation |
+| `fullscreen` | boolean | Fill the viewport, no backdrop |
+| `rounded` | `none` | Remove the corner radius |
+| `forceAction` | boolean | Disable backdrop click, Escape and close button |
+| `noCloseButton` | boolean | Hide the close button only |
+| `closeButtonType` | `sonic-button` type | Color of the close button |
+| `visible` | boolean | Opens or closes the modal when toggled |
+| `removeOnHide` | boolean | Remove the element after closing |
+| `removeHashOnHide` | boolean | Clear the URL hash after closing |
+| `closeOnLocationChange` | boolean | Close when the location changes |
+| `resetDataProviderOnHide` | publisher id | Reset this data provider to `{}` after closing |
+
+JavaScript-only properties: `options` (same keys as `Modal.create`) and `styleSheet` (`CSSResult` or `CSSStyleSheet`, or an array, adopted in the shadow root).
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Modal content, usually the `sonic-modal-*` children |
+
+| Method | Description |
+|--------|-------------|
+| `show()` | Open the modal |
+| `hide()` | Close the modal (returns a promise) |
+| `dispose()` | Close and remove the modal |
+| `Modal.create(options)` | Static: create, append and open a modal |
+| `Modal.disposeAll()` | Static: close and remove every modal |
+
+| Event | Description |
+|-------|-------------|
+| `show` | Open animation finished |
+| `hide` | Close started |
+| `hidden` | Close finished |
+
+### `sonic-modal-title` · `sonic-modal-subtitle` · `sonic-modal-content` · `sonic-modal-actions`
+
+No attributes. Default slot only. In `sonic-modal-actions`, child `sonic-button` elements with `hideModal` close the modal.
+
+### `sonic-modal-close`
+
+Rendered automatically unless `forceAction` or `noCloseButton` is set. Place it manually to add a close button elsewhere.
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `sonic-button` type | Button color |
+| `reset` | publisher id | Passed to the inner `sonic-button` `reset` |
+| `translation` | label object | Overrides the default `aria-label` |

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

@@ -1,96 +1,216 @@
 # Pop
 
-## Placement
+**`sonic-pop`** anchors a floating panel to a trigger: put the control in the default slot and the panel (menu, form, any markup) in **`slot="content"`**. A click on the trigger toggles the panel unless **`manual`** is set. The panel follows the trigger while open and flips to stay inside the viewport.
+
+## Basic example
+
 <sonic-code>
   <template>
-    <sonic-pop class="inline-block" placement="left">
-      <sonic-button>Left</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" placement="right">
-      <sonic-button>Right</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" placement="top">
-      <sonic-button>Top</sonic-button>
+    <sonic-pop>
+      <sonic-button>Notifications</sonic-button>
       <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" placement="bottom">
-      <sonic-button>Bottom</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
+        <sonic-menu-item>
+          <sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>
+          Notifications
+        </sonic-menu-item>
+        <sonic-menu-item>
+          <sonic-icon library="iconoir" name="settings" slot="prefix"></sonic-icon>
+          Settings
+        </sonic-menu-item>
       </sonic-menu>
     </sonic-pop>
   </template>
 </sonic-code>
 
+## Placement
+
+**`placement`** is a side (`top` · `bottom` · `left` · `right`) with an optional alignment suffix (`-start` · `-center` · `-end`). Default is `bottom`; without a suffix, the panel aligns to `start`. The space syntax (`bottom center`) is deprecated.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-pop placement="top">
+        <sonic-button>Top</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="bottom">
+        <sonic-button>Bottom</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="left">
+        <sonic-button>Left</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="right">
+        <sonic-button>Right</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="top-center">
+        <sonic-button>Top center</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="bottom-center">
+        <sonic-button>Bottom center</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="left-center">
+        <sonic-button>Left center</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop placement="bottom-end">
+        <sonic-button>Bottom end</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+    </div>
+  </template>
+</sonic-code>
+
 ## Shadow
+
+The panel shadow defaults to `lg`.
+
 <sonic-code>
   <template>
-    <sonic-pop class="inline-block" shadow="none" placement='top' >
-      <sonic-button>None</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" shadow="sm"  placement='top'>
-      <sonic-button>Small</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" shadow="md"  placement='top'>
-      <sonic-button>Medium</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" shadow="lg"  placement='top'>
-      <sonic-button>Large</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
+    <div class="flex flex-wrap gap-2">
+      <sonic-pop shadow="none">
+        <sonic-button>None</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop shadow="sm">
+        <sonic-button>Small</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop shadow="md">
+        <sonic-button>Medium</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop shadow="lg">
+        <sonic-button>Large</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+    </div>
   </template>
 </sonic-code>
 
-## noToggle
+## Inline
+
+The host is middle-aligned by default. Set **`inline`** to baseline-align a trigger inside running text.
+
 <sonic-code>
   <template>
-    <sonic-pop class="inline-block"  noToggle>
-      <sonic-button>No toggle on click</sonic-button>
-      <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
-      </sonic-menu>
-    </sonic-pop>
-    <sonic-pop class="inline-block" >
-      <sonic-button>Default toggle on click</sonic-button>
+    <p>
+      You are signed in as
+      <sonic-pop inline>
+        <sonic-button variant="link">ada.lindqvist@example.com</sonic-button>
+        <sonic-menu slot="content">
+          <sonic-menu-item>Profile</sonic-menu-item>
+          <sonic-menu-item>Sign out</sonic-menu-item>
+        </sonic-menu>
+      </sonic-pop>
+      on this device.
+    </p>
+  </template>
+</sonic-code>
+
+## No toggle
+
+With **`noToggle`**, clicking the trigger opens the pop but does not close it. Close it with an outside click, Escape or **`hide()`**.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-pop noToggle>
+        <sonic-button>No toggle</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+      <sonic-pop>
+        <sonic-button>Default toggle</sonic-button>
+        <sonic-menu slot="content"><sonic-menu-item>Item</sonic-menu-item></sonic-menu>
+      </sonic-pop>
+    </div>
+  </template>
+</sonic-code>
+
+## Manual control
+
+**`manual`** disables the built-in click and keyboard handling on the trigger. Call **`show()`** and **`hide()`** instead.
+
+<sonic-code>
+  <template>
+    <sonic-pop manual id="manualPop">
+      <sonic-button onclick="alert('Custom action, the pop stays closed')">Manual trigger</sonic-button>
       <sonic-menu slot="content">
-        <sonic-menu-item><sonic-icon library="iconoir" name="bell-notification" slot="prefix"></sonic-icon>Notifications</sonic-menu-item>
+        <sonic-menu-item>Opened from script</sonic-menu-item>
       </sonic-menu>
     </sonic-pop>
+    <sonic-button onclick="document.getElementById('manualPop').show()" class="ml-5" variant="outline">
+      Open the pop
+    </sonic-button>
   </template>
 </sonic-code>
 
+## Keep open on select
+
+A click inside the panel closes the pop by default. Set **`data-on-select="keep"`** on the panel or a descendant to keep it open, for example while ticking checkboxes.
 
-## manual
 <sonic-code>
   <template>
-    <sonic-pop class="inline-block" manual id="manualPop">
-      <sonic-button onclick="alert('customAction without opening Pop content')">Manual doesn't open on click</sonic-button>
+    <div class="flex flex-wrap gap-2">
+      <sonic-pop>
+        <sonic-button>Closes on select</sonic-button>
+        <div slot="content" class="grid gap-2 p-3">
+          <sonic-checkbox>Window seat</sonic-checkbox>
+          <sonic-checkbox>Extra baggage</sonic-checkbox>
+        </div>
+      </sonic-pop>
+      <sonic-pop>
+        <sonic-button>Stays open on select</sonic-button>
+        <div slot="content" class="grid gap-2 p-3" data-on-select="keep">
+          <sonic-checkbox>Window seat</sonic-checkbox>
+          <sonic-checkbox>Extra baggage</sonic-checkbox>
+        </div>
+      </sonic-pop>
+    </div>
+  </template>
+</sonic-code>
+
+## Keyboard
+
+**ArrowDown** on the trigger opens the pop. **Escape** closes the most recently opened pop, before an enclosing `sonic-modal`, and returns focus to its trigger.
+
+<sonic-code>
+  <template>
+    <sonic-pop>
+      <sonic-button>Focus me, then press ArrowDown</sonic-button>
       <sonic-menu slot="content">
-        <sonic-menu-item>Hourra !</sonic-menu-item>
+        <sonic-menu-item>First item</sonic-menu-item>
+        <sonic-menu-item>Second item</sonic-menu-item>
       </sonic-menu>
     </sonic-pop>
-    <sonic-button onclick="document.getElementById('manualPop').show()" class="ml-5"  variant="outline">
-      <sonic-icon name="sparkles" library="custom"></sonic-icon>
-      Click to open pop
-    </sonic-button>
   </template>
-</sonic-code>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `placement` | `top` · `bottom` (default) · `left` · `right`, each with optional `-start` · `-center` · `-end` | Side and alignment relative to the trigger |
+| `shadow` | `none` · `sm` · `md` · `lg` (default `lg`) | Panel shadow |
+| `inline` | boolean | Baseline-align the host in text |
+| `noToggle` | boolean | A trigger click does not close an open pop |
+| `manual` | boolean | Disable trigger click and keyboard handling |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Trigger |
+| `content` | Floating panel; `data-on-select="keep"` inside it prevents close on click |
+
+| Method | Description |
+|--------|-------------|
+| `show()` | Open the panel |
+| `hide()` | Close the panel |
+
+| Event | Description |
+|-------|-------------|
+| `show` | Panel opened |
+| `hide` | Panel closed |