@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

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

@@ -1,10 +1,10 @@
 # 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.
+**`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`**).
 
 ## 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.
+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.
 
 <sonic-code>
   <template>
@@ -13,38 +13,51 @@ Backdrop click, Escape and the close button all close the modal. In **`sonic-mod
     </sonic-button>
     <sonic-modal id="modalExample">
       <sonic-modal-title>
-        Boarding pass ready
+        Export 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-subtitle>Your report finished processing.</sonic-modal-subtitle>
       <sonic-modal-content>
-        Download your boarding pass now or review your seat before departure.
+        Download the CSV now or review the summary in your dashboard before sharing.
       </sonic-modal-content>
-      <sonic-modal-actions>
-        <sonic-button minWidth="8rem" hideModal>Later</sonic-button>
+      <sonic-modal-actions formDataProvider="ModalMiniForm">
+        <sonic-button minWidth="8rem" value="true" name="click">
+          Save draft
+        </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 content scrolls inside the dialog once it reaches **`maxHeight`** (default `90vh`). Content is left-aligned by default; set **`align`** to `center` or `right`.
+Long copy scrolls inside the dialog. Default **`maxHeight`** is `90vh`. Default **`align`** is `left`.
 
 <sonic-code>
   <template>
-    <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-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-modal-content>
         <div class="prose">
-          <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>
+          <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>
         </div>
       </sonic-modal-content>
     </sonic-modal>
@@ -53,7 +66,7 @@ Long content scrolls inside the dialog once it reaches **`maxHeight`** (default
 
 ## 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.
+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.
 
 <sonic-code>
   <template>
@@ -61,7 +74,7 @@ With **`forceAction`**, backdrop click, Escape and the close button are disabled
     <sonic-modal forceAction id="force">
       <sonic-modal-title>Allow analytics cookies?</sonic-modal-title>
       <sonic-modal-content>
-        Analytics cookies measure traffic. You can change this later in settings.
+        We use cookies to measure traffic and improve the product. You can change this later in settings.
       </sonic-modal-content>
       <sonic-modal-actions>
         <sonic-button hideModal minWidth="8rem">Decline</sonic-button>
@@ -71,9 +84,9 @@ With **`forceAction`**, backdrop click, Escape and the close button are disabled
   </template>
 </sonic-code>
 
-## Dimensions
+## Custom 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.
+Set **`width`** / **`height`** / **`maxWidth`** / **`maxHeight`** (CSS lengths). On narrow viewports the panel becomes a bottom sheet. Use **`rounded="none"`** for edge-to-edge media.
 
 <sonic-code>
   <template>
@@ -88,8 +101,9 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
     >
       <sonic-image
         cover
-        src="img/concorde/plane_12.jpg"
-        alt="Concorde at the gate with boarding stairs"
+        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"
       ></sonic-image>
     </sonic-modal>
   </template>
@@ -105,8 +119,8 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
     <sonic-modal fullscreen id="Fullscreen">
       <sonic-image
         cover
-        src="img/concorde/plane_10.jpg"
-        alt="Concorde fleet parked in a star"
+        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"
       ></sonic-image>
     </sonic-modal>
   </template>
@@ -114,15 +128,17 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
 
 ## 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.
+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.
 
 <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.',
+        title: 'Send invite?',
+        subtitle: 'The recipient can join immediately.',
+        content: 'We will email an invitation to alex@example.com.',
         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
       })"
@@ -132,22 +148,28 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
   </template>
 </sonic-code>
 
-<sonic-code language="typescript">
+<sonic-code language="javascript">
   <template>
-import { Modal } from "@supersoniks/concorde/ui/modal";
+import { Modal } from "@supersoniks/concorde/core/components/ui/modal/modal";
 
 const modal = Modal.create({
-  title: "Remove flight CN 001?",
-  content: "It will no longer appear on the departures board.",
+  title: "Delete project?",
+  subtitle: "This cannot be undone.",
+  content: "<p>All files in <strong>Acme HQ</strong> will be removed.</p>",
   actions: `
-    &lt;sonic-button hideModal&gt;Cancel&lt;/sonic-button&gt;
-    &lt;sonic-button hideModal type="danger"&gt;Remove&lt;/sonic-button&gt;
+    <sonic-button hideModal minWidth="8rem">Cancel</sonic-button>
+    <sonic-button hideModal minWidth="8rem" type="danger">Delete</sonic-button>
   `,
   removeOnHide: true,
+  forceAction: false,
   maxWidth: "min(100vw, 28rem)",
 });
 
-modal.addEventListener("hidden", () => console.log("closed"));
+modal.addEventListener("hidden", () => {
+  console.log("Modal removed from the DOM");
+});
+
+// Or close from script: await modal.hide(); await modal.dispose();
   </template>
 </sonic-code>
 
@@ -157,55 +179,57 @@ modal.addEventListener("hidden", () => console.log("closed"));
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `align` | `left` (default) · `center` · `right` | Content alignment |
+| `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 |
 | `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).
+| `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) |
 
 | 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 |
+| *(default)* | Additional markup alongside structured children |
 
 | Event | Description |
 |-------|-------------|
-| `show` | Open animation finished |
-| `hide` | Close started |
-| `hidden` | Close finished |
+| `show` | Fired when open animation completes |
+| `hide` | Fired when close starts |
+| `hidden` | Fired when close finishes |
 
-### `sonic-modal-title` · `sonic-modal-subtitle` · `sonic-modal-content` · `sonic-modal-actions`
+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`**) |
 
-No attributes. Default slot only. In `sonic-modal-actions`, child `sonic-button` elements with `hideModal` close the modal.
+Put **`hideModal`** on a **`sonic-button`** to close the parent modal on click. Ancestor **`formDataProvider`** on this element is inherited by child form controls.
 
 ### `sonic-modal-close`
 
-Rendered automatically unless `forceAction` or `noCloseButton` is set. Place it manually to add a close button elsewhere.
+Rendered automatically unless **`forceAction`** or **`noCloseButton`** is set. Calls **`hide()`** on the parent modal.
 
 | 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` |
+| `type` | **`sonic-button`** `type` | Close button color |
+| `reset` | string | Passed to inner **`sonic-button`** **`reset`** |
+| `translation` | UI label object | Overrides default close **`aria-label`** |