@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -1,10 +1,10 @@
 # Modal
 
-**`sonic-modal`** presents focused content in a `<dialog>` overlay with backdrop, enter/exit animation, and a built-in close control. Compose **`sonic-modal-title`** / **`sonic-modal-subtitle`** / **`sonic-modal-content`** / **`sonic-modal-actions`**, or use the default slot. Call **`show()`** on the element to open; use **`hideModal`** on action buttons or **`hide()`** from script. Set **`forceAction`** when dismissal must go through explicit actions only. Imperative dialogs: **`Modal.create()`** (also **`window.SonicModal`**).
+**`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
 
-Click the trigger to open. **`sonic-modal-actions`** lays out footer buttons; **`hideModal`** closes the modal on click. Scope form state with **`formDataProvider`** on **`sonic-modal-actions`** so child **`sonic-button`** elements share one publisher.
+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>
@@ -13,51 +13,38 @@ Click the trigger to open. **`sonic-modal-actions`** lays out footer buttons; **
     </sonic-button>
     <sonic-modal id="modalExample">
       <sonic-modal-title>
-        Export ready
+        Boarding pass ready
         <sonic-badge type="success" size="sm">New</sonic-badge>
       </sonic-modal-title>
-      <sonic-modal-subtitle>Your report finished processing.</sonic-modal-subtitle>
+      <sonic-modal-subtitle>Your check-in is complete.</sonic-modal-subtitle>
       <sonic-modal-content>
-        Download the CSV now or review the summary in your dashboard before sharing.
+        Download your boarding pass now or review your seat before departure.
       </sonic-modal-content>
-      <sonic-modal-actions formDataProvider="ModalMiniForm">
-        <sonic-button minWidth="8rem" value="true" name="click">
-          Save draft
-        </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`**.
+
 ## Scrollable content
 
-Long copy scrolls inside the dialog. Default **`maxHeight`** is `90vh`. Default **`align`** is `left`.
+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()">Venue details</sonic-button>
-    <sonic-modal align="left" id="modalText">
-      <sonic-modal-title>Hours and tickets</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>Opening hours</strong><br />
-            Wednesday–Saturday, 1:30 p.m.–7:00 p.m.; Sunday, 1:30 p.m.–6:00 p.m.
-          </p>
-          <p>
-            <strong>Ticketing</strong><br />
-            Some events require online or box-office reservations. Prices vary by event; booking ahead is recommended when capacity is limited.
-          </p>
-          <p>
-            <strong>Contact</strong><br />
-            tickets@example.com · +33 3 28 33 48 33
-          </p>
-          <p>
-            <strong>Access</strong><br />
-            14 Place Faidherbe, 59100 Roubaix<br />
-            Metro line 2, Eurotéléport stop
-          </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>
@@ -66,7 +53,7 @@ Long copy scrolls inside the dialog. Default **`maxHeight`** is `90vh`. Default
 
 ## Force action
 
-With **`forceAction`**, backdrop click, Escape, and the default close button are disabled. Provide **`sonic-modal-actions`** (or **`sonic-modal-close`**) so users can finish the flow.
+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>
@@ -74,7 +61,7 @@ With **`forceAction`**, backdrop click, Escape, and the default close button are
     <sonic-modal forceAction id="force">
       <sonic-modal-title>Allow analytics cookies?</sonic-modal-title>
       <sonic-modal-content>
-        We use cookies to measure traffic and improve the product. You can change this later in settings.
+        Analytics cookies measure traffic. You can change this later in settings.
       </sonic-modal-content>
       <sonic-modal-actions>
         <sonic-button hideModal minWidth="8rem">Decline</sonic-button>
@@ -84,9 +71,9 @@ With **`forceAction`**, backdrop click, Escape, and the default close button are
   </template>
 </sonic-code>
 
-## Custom dimensions
+## Dimensions
 
-Set **`width`** / **`height`** / **`maxWidth`** / **`maxHeight`** (CSS lengths). On narrow viewports the panel becomes a bottom sheet. Use **`rounded="none"`** for edge-to-edge media.
+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>
@@ -101,9 +88,8 @@ Set **`width`** / **`height`** / **`maxWidth`** / **`maxHeight`** (CSS lengths).
     >
       <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"
-        alt="View from an airplane window"
+        src="/img/concorde/plane_12.jpg"
+        alt="Concorde at the gate with boarding stairs"
       ></sonic-image>
     </sonic-modal>
   </template>
@@ -119,8 +105,8 @@ Set **`width`** / **`height`** / **`maxWidth`** / **`maxHeight`** (CSS lengths).
     <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"
-        alt="View from an airplane window"
+        src="/img/concorde/plane_10.jpg"
+        alt="Concorde fleet parked in a star"
       ></sonic-image>
     </sonic-modal>
   </template>
@@ -128,17 +114,15 @@ Set **`width`** / **`height`** / **`maxWidth`** / **`maxHeight`** (CSS lengths).
 
 ## Programmatic creation
 
-Use **`Modal.create(options)`** when there is no modal in the template—for confirmations, toasts that need a follow-up, or one-off flows from script. The modal is appended to the nearest **`sonic-theme`** pop container (same as declarative modals), opened automatically, and returns the **`sonic-modal`** instance. Set **`removeOnHide: true`** to detach it from the DOM after close. In the browser, **`window.SonicModal`** is the same class after the module loads.
-
-Pass **`title`** / **`subtitle`** / **`content`** / **`actions`** as HTML strings (or Lit template results from application code). Put **`hideModal`** on action buttons in the **`actions`** string so clicks close the dialog.
+**`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: 'Send invite?',
-        subtitle: 'The recipient can join immediately.',
-        content: 'We will email an invitation to alex@example.com.',
+        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
       })"
@@ -148,28 +132,22 @@ Pass **`title`** / **`subtitle`** / **`content`** / **`actions`** as HTML string
   </template>
 </sonic-code>
 
-<sonic-code language="javascript">
+<sonic-code language="typescript">
   <template>
-import { Modal } from "@supersoniks/concorde/core/components/ui/modal/modal";
+import { Modal } from "@supersoniks/concorde/ui/modal";
 
 const modal = Modal.create({
-  title: "Delete project?",
-  subtitle: "This cannot be undone.",
-  content: "<p>All files in <strong>Acme HQ</strong> will be removed.</p>",
+  title: "Remove flight CN 001?",
+  content: "It will no longer appear on the departures board.",
   actions: `
-    <sonic-button hideModal minWidth="8rem">Cancel</sonic-button>
-    <sonic-button hideModal minWidth="8rem" type="danger">Delete</sonic-button>
+    &lt;sonic-button hideModal&gt;Cancel&lt;/sonic-button&gt;
+    &lt;sonic-button hideModal type="danger"&gt;Remove&lt;/sonic-button&gt;
   `,
   removeOnHide: true,
-  forceAction: false,
   maxWidth: "min(100vw, 28rem)",
 });
 
-modal.addEventListener("hidden", () => {
-  console.log("Modal removed from the DOM");
-});
-
-// Or close from script: await modal.hide(); await modal.dispose();
+modal.addEventListener("hidden", () => console.log("closed"));
   </template>
 </sonic-code>
 
@@ -179,57 +157,55 @@ modal.addEventListener("hidden", () => {
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `align` | `left` (default) · `center` · `right` | Align title and slotted content |
-| `maxWidth` | CSS length (default `min(100vw, 40rem)`) | Dialog max width |
-| `maxHeight` | CSS length (default `90vh`) | Scrollable body max height |
+| `align` | `left` (default) · `center` · `right` | Content alignment |
 | `width` | CSS length (default `100%`) | Dialog width |
 | `height` | CSS length (default `fit-content`) | Dialog height |
-| `paddingX` · `paddingY` | CSS length | Override content padding (`--sc-modal-px` / `--sc-modal-py`) |
-| `zIndex` | CSS number | Stacking order (default `990`) |
-| `effect` | `slide` (default) · `fade` · `none` | Open/close animation |
-| `fullscreen` | boolean | Full viewport; no backdrop |
-| `forceAction` | boolean | Disable overlay, Escape, and default close button |
-| `noCloseButton` | boolean | Hide built-in close when not **`forceAction`** |
-| `closeButtonType` | **`sonic-button`** `type` | Style of built-in close |
-| `visible` | boolean | When toggled, opens or closes the dialog |
-| `removeOnHide` | boolean | Remove element from DOM after close |
-| `removeHashOnHide` | boolean | Clear URL hash on close |
-| `closeOnLocationChange` | boolean | Close when app location changes |
-| `resetDataProviderOnHide` | string | Reset named **`formDataProvider`** on close |
-| `rounded` | `none` | Square dialog corners (useful for full-bleed media) |
+| `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)* | Additional markup alongside structured children |
+| *(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` | Fired when open animation completes |
-| `hide` | Fired when close starts |
-| `hidden` | Fired when close finishes |
+| `show` | Open animation finished |
+| `hide` | Close started |
+| `hidden` | Close finished |
 
-Methods: **`show()`** · **`hide()`** · **`dispose()`** (hide and remove). Static **`Modal.create(options)`** appends a modal to the theme pop container and opens it. **`options`** / **`styleSheet`** are JavaScript-only.
-
-### `sonic-modal-title` · `sonic-modal-subtitle` · `sonic-modal-content`
-
-| Slot | Description |
-|------|-------------|
-| *(default)* | Title, subtitle, or main body content |
-
-### `sonic-modal-actions`
-
-| Slot | Description |
-|------|-------------|
-| *(default)* | Footer actions (typically **`sonic-button`**) |
+### `sonic-modal-title` · `sonic-modal-subtitle` · `sonic-modal-content` · `sonic-modal-actions`
 
-Put **`hideModal`** on a **`sonic-button`** to close the parent modal on click. Ancestor **`formDataProvider`** on this element is inherited by child form controls.
+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. Calls **`hide()`** on the parent modal.
+Rendered automatically unless `forceAction` or `noCloseButton` is set. Place it manually to add a close button elsewhere.
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `type` | **`sonic-button`** `type` | Close button color |
-| `reset` | string | Passed to inner **`sonic-button`** **`reset`** |
-| `translation` | UI label object | Overrides default close **`aria-label`** |
+| `type` | `sonic-button` type | Button color |
+| `reset` | publisher id | Passed to the inner `sonic-button` `reset` |
+| `translation` | label object | Overrides the default `aria-label` |