snice 4.8.0 → 4.10.0

package/docs/components/modal.md

@@ -1,25 +1,20 @@
-# Modal Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/modal.md instead)
 
-The `<snice-modal>` component provides a dialog overlay for displaying content on top of the main page. It includes features like focus trapping, backdrop dismiss, keyboard navigation, and accessibility support.
+# Modal
+`<snice-modal>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Slots](#slots)
-- [Examples](#examples)
+A dialog overlay with focus trapping, backdrop dismiss, and keyboard navigation.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/modal/snice-modal';
+```
+
 ```html
 <snice-modal label="Confirm Action">
-  <div slot="header">
-    <h2>Confirm</h2>
-  </div>
-
+  <div slot="header"><h2>Confirm</h2></div>
   <p>Are you sure you want to proceed?</p>
-
   <div slot="footer">
     <button>Cancel</button>
     <button>Confirm</button>
@@ -27,187 +22,50 @@ The `<snice-modal>` component provides a dialog overlay for displaying content o
 </snice-modal>
 ```
 
-```typescript
-import 'snice/components/modal/snice-modal';
-
-const modal = document.querySelector('snice-modal');
-
-// Open the modal
-modal.show();
-
-// Listen for events
-modal.addEventListener('modal-close', () => {
-  console.log('Modal closed');
-});
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `open` | `boolean` | `false` | Whether the modal is visible |
-| `size` | `'small' \| 'medium' \| 'large' \| 'fullscreen'` | `'medium'` | Size variant of the modal |
-| `noBackdropDismiss` | `boolean` | `false` | Prevent closing when clicking backdrop |
-| `noEscapeDismiss` | `boolean` | `false` | Prevent closing with Escape key |
-| `noFocusTrap` | `boolean` | `false` | Disable focus trapping |
-| `noCloseButton` | `boolean` | `false` | Hide the close button in header |
-| `label` | `string` | `''` | Accessible label for the modal |
-
-## Methods
-
-### `show(): void`
-Open the modal.
-
-```typescript
-modal.show();
-```
-
-### `close(): void`
-Close the modal.
-
-```typescript
-modal.close();
-```
-
-## Events
-
-### `modal-open`
-Fired when the modal opens.
-
-**Event Detail:**
-```typescript
-{
-  modal: SniceModalElement; // Reference to the modal element
-}
-```
-
-**Usage:**
-```typescript
-modal.addEventListener('modal-open', (e) => {
-  console.log('Modal opened:', e.detail.modal);
-});
-```
-
-### `modal-close`
-Fired when the modal closes.
-
-**Event Detail:**
-```typescript
-{
-  modal: SniceModalElement; // Reference to the modal element
-}
-```
+## Importing
 
-**Usage:**
+**ESM (bundler)**
 ```typescript
-modal.addEventListener('modal-close', (e) => {
-  console.log('Modal closed:', e.detail.modal);
-});
-```
-
-## Slots
-
-### `header` (named slot)
-Content for the modal header. Typically used for titles.
-
-```html
-<snice-modal>
-  <div slot="header">
-    <h2>Modal Title</h2>
-  </div>
-</snice-modal>
-```
-
-### Default slot
-Main content of the modal body.
-
-```html
-<snice-modal>
-  <p>This goes in the body</p>
-</snice-modal>
+import 'snice/components/modal/snice-modal';
 ```
 
-### `footer` (named slot)
-Content for the modal footer. Typically used for action buttons.
-
+**CDN**
 ```html
-<snice-modal>
-  <div slot="footer">
-    <button>Cancel</button>
-    <button>OK</button>
-  </div>
-</snice-modal>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-modal.min.js"></script>
 ```
 
 ## Examples
 
-### Basic Modal
-
-```html
-<button id="openModal">Open Modal</button>
-
-<snice-modal id="myModal" label="Example Modal">
-  <div slot="header">
-    <h2>Hello</h2>
-  </div>
-
-  <p>This is a basic modal example.</p>
-
-  <div slot="footer">
-    <button id="closeModal">Close</button>
-  </div>
-</snice-modal>
-
-<script type="module">
-  import 'snice/components/modal/snice-modal';
-
-  const modal = document.querySelector('#myModal');
-  const openBtn = document.querySelector('#openModal');
-  const closeBtn = document.querySelector('#closeModal');
+### Sizes
 
-  openBtn.addEventListener('click', () => modal.show());
-  closeBtn.addEventListener('click', () => modal.close());
-</script>
-```
-
-### Size Variants
+Use the `size` attribute to set the modal width.
 
 ```html
-<!-- Small -->
 <snice-modal size="small" label="Small Modal">
   <div slot="header"><h2>Small</h2></div>
-  <p>This is a small modal.</p>
-</snice-modal>
-
-<!-- Medium (default) -->
-<snice-modal size="medium" label="Medium Modal">
-  <div slot="header"><h2>Medium</h2></div>
-  <p>This is a medium modal.</p>
+  <p>Compact dialog for simple confirmations.</p>
 </snice-modal>
 
-<!-- Large -->
 <snice-modal size="large" label="Large Modal">
   <div slot="header"><h2>Large</h2></div>
-  <p>This is a large modal.</p>
+  <p>Spacious dialog for detailed forms.</p>
 </snice-modal>
 
-<!-- Fullscreen -->
 <snice-modal size="fullscreen" label="Fullscreen Modal">
   <div slot="header"><h2>Fullscreen</h2></div>
-  <p>This modal takes up the entire screen.</p>
+  <p>Takes up the entire viewport.</p>
 </snice-modal>
 ```
 
 ### Without Close Button
 
-```html
-<snice-modal no-close-button label="Forced Choice">
-  <div slot="header">
-    <h2>Choose an Option</h2>
-  </div>
-
-  <p>You must select one of the options below.</p>
+Set `no-close-button` to hide the default close button.
 
+```html
+<snice-modal no-close-button label="Choose an Option">
+  <div slot="header"><h2>Required Choice</h2></div>
+  <p>Select one of the options below.</p>
   <div slot="footer">
     <button onclick="this.closest('snice-modal').close()">Option A</button>
     <button onclick="this.closest('snice-modal').close()">Option B</button>
@@ -217,14 +75,12 @@ Content for the modal footer. Typically used for action buttons.
 
 ### Prevent Backdrop Dismiss
 
-```html
-<snice-modal no-backdrop-dismiss label="Important">
-  <div slot="header">
-    <h2>Important Information</h2>
-  </div>
-
-  <p>Click the button to close, clicking outside won't work.</p>
+Set `no-backdrop-dismiss` to prevent closing when clicking outside.
 
+```html
+<snice-modal no-backdrop-dismiss label="Important Notice">
+  <div slot="header"><h2>Important</h2></div>
+  <p>Clicking outside won't close this modal.</p>
   <div slot="footer">
     <button onclick="this.closest('snice-modal').close()">I Understand</button>
   </div>
@@ -233,14 +89,12 @@ Content for the modal footer. Typically used for action buttons.
 
 ### Prevent Escape Dismiss
 
+Set `no-escape-dismiss` to prevent closing with the Escape key.
+
 ```html
 <snice-modal no-escape-dismiss label="Confirmation Required">
-  <div slot="header">
-    <h2>Confirm Action</h2>
-  </div>
-
-  <p>Press Escape won't close this modal.</p>
-
+  <div slot="header"><h2>Confirm Action</h2></div>
+  <p>Pressing Escape won't close this modal.</p>
   <div slot="footer">
     <button onclick="this.closest('snice-modal').close()">Confirm</button>
   </div>
@@ -253,36 +107,21 @@ Content for the modal footer. Typically used for action buttons.
 <button id="deleteBtn">Delete Item</button>
 
 <snice-modal id="confirmModal" size="small" label="Confirm Delete">
-  <div slot="header">
-    <h2>Confirm Delete</h2>
-  </div>
-
-  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
-
+  <div slot="header"><h2>Confirm Delete</h2></div>
+  <p>Are you sure? This action cannot be undone.</p>
   <div slot="footer">
     <button id="cancelBtn">Cancel</button>
-    <button id="confirmBtn" style="background: #dc2626; color: white;">Delete</button>
+    <button id="confirmBtn">Delete</button>
   </div>
 </snice-modal>
 
 <script type="module">
   import 'snice/components/modal/snice-modal';
 
-  const deleteBtn = document.querySelector('#deleteBtn');
-  const modal = document.querySelector('#confirmModal');
-  const cancelBtn = document.querySelector('#cancelBtn');
-  const confirmBtn = document.querySelector('#confirmBtn');
-
-  deleteBtn.addEventListener('click', () => {
-    modal.show();
-  });
-
-  cancelBtn.addEventListener('click', () => {
-    modal.close();
-  });
-
-  confirmBtn.addEventListener('click', () => {
-    // Perform delete action
+  const modal = document.getElementById('confirmModal');
+  document.getElementById('deleteBtn').addEventListener('click', () => modal.show());
+  document.getElementById('cancelBtn').addEventListener('click', () => modal.close());
+  document.getElementById('confirmBtn').addEventListener('click', () => {
     console.log('Item deleted');
     modal.close();
   });
@@ -292,28 +131,16 @@ Content for the modal footer. Typically used for action buttons.
 ### Form in Modal
 
 ```html
-<button id="showFormModal">Edit Profile</button>
+<button id="editBtn">Edit Profile</button>
 
 <snice-modal id="formModal" label="Edit Profile">
-  <div slot="header">
-    <h2>Edit Profile</h2>
-  </div>
-
-  <form id="profileForm">
-    <div style="display: flex; flex-direction: column; gap: 1rem;">
-      <div>
-        <label for="name">Name:</label>
-        <input type="text" id="name" name="name" required>
-      </div>
-      <div>
-        <label for="email">Email:</label>
-        <input type="email" id="email" name="email" required>
-      </div>
-    </div>
+  <div slot="header"><h2>Edit Profile</h2></div>
+  <form id="profileForm" style="display:flex;flex-direction:column;gap:1rem;">
+    <label>Name: <input type="text" name="name" required></label>
+    <label>Email: <input type="email" name="email" required></label>
   </form>
-
   <div slot="footer">
-    <button type="button" onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
     <button type="submit" form="profileForm">Save</button>
   </div>
 </snice-modal>
@@ -321,238 +148,58 @@ Content for the modal footer. Typically used for action buttons.
 <script type="module">
   import 'snice/components/modal/snice-modal';
 
-  const showBtn = document.querySelector('#showFormModal');
-  const modal = document.querySelector('#formModal');
-  const form = document.querySelector('#profileForm');
-
-  showBtn.addEventListener('click', () => modal.show());
-
-  form.addEventListener('submit', (e) => {
+  const modal = document.getElementById('formModal');
+  document.getElementById('editBtn').addEventListener('click', () => modal.show());
+  document.getElementById('profileForm').addEventListener('submit', (e) => {
     e.preventDefault();
-    const formData = new FormData(form);
-    console.log('Saving:', Object.fromEntries(formData));
+    console.log('Saved:', Object.fromEntries(new FormData(e.target)));
     modal.close();
   });
 </script>
 ```
 
-### With Event Handling
+### Programmatic Control
 
 ```typescript
-import type { SniceModalElement } from 'snice/components/modal/snice-modal.types';
-
-const modal = document.querySelector<SniceModalElement>('snice-modal');
-
-modal.addEventListener('modal-open', () => {
-  console.log('Modal opened');
-  // Pause video, etc.
-});
-
-modal.addEventListener('modal-close', () => {
-  console.log('Modal closed');
-  // Resume video, etc.
-});
-
-// Open programmatically
-modal.show();
-
-// Close programmatically
-modal.close();
-
-// Toggle based on state
-if (modal.open) {
-  modal.close();
-} else {
-  modal.show();
-}
-```
-
-### Dynamic Content
-
-```html
-<button id="showDetails">Show Details</button>
-
-<snice-modal id="detailsModal" label="Item Details">
-  <div slot="header">
-    <h2 id="itemTitle">Loading...</h2>
-  </div>
-
-  <div id="itemContent">
-    <p>Loading...</p>
-  </div>
-
-  <div slot="footer">
-    <button onclick="this.closest('snice-modal').close()">Close</button>
-  </div>
-</snice-modal>
-
-<script type="module">
-  import 'snice/components/modal/snice-modal';
-
-  const showBtn = document.querySelector('#showDetails');
-  const modal = document.querySelector('#detailsModal');
-  const title = document.querySelector('#itemTitle');
-  const content = document.querySelector('#itemContent');
-
-  showBtn.addEventListener('click', async () => {
-    modal.show();
-
-    // Fetch data
-    const response = await fetch('/api/item/123');
-    const item = await response.json();
-
-    // Update modal content
-    title.textContent = item.name;
-    content.innerHTML = `
-      <p><strong>ID:</strong> ${item.id}</p>
-      <p><strong>Description:</strong> ${item.description}</p>
-      <p><strong>Price:</strong> $${item.price}</p>
-    `;
-  });
-</script>
-```
-
-### Complete Example
+const modal = document.querySelector('snice-modal');
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <style>
-    .demo-container {
-      padding: 2rem;
-      display: flex;
-      gap: 1rem;
-      flex-wrap: wrap;
-    }
-
-    .demo-container button {
-      padding: 0.5rem 1rem;
-      cursor: pointer;
-    }
-
-    snice-modal h2 {
-      margin: 0;
-    }
-
-    snice-modal [slot="footer"] {
-      display: flex;
-      gap: 0.5rem;
-      justify-content: flex-end;
-    }
-  </style>
-
-  <script type="module">
-    import 'snice/components/modal/snice-modal';
-
-    document.addEventListener('DOMContentLoaded', () => {
-      // Setup all modals
-      document.querySelectorAll('[data-modal-trigger]').forEach(btn => {
-        const modalId = btn.getAttribute('data-modal-trigger');
-        const modal = document.querySelector(`#${modalId}`);
-
-        btn.addEventListener('click', () => modal?.show());
-      });
-
-      // Setup close buttons
-      document.querySelectorAll('[data-modal-close]').forEach(btn => {
-        btn.addEventListener('click', () => {
-          btn.closest('snice-modal')?.close();
-        });
-      });
-    });
-  </script>
-</head>
-<body>
-  <div class="demo-container">
-    <button data-modal-trigger="modal1">Small Modal</button>
-    <button data-modal-trigger="modal2">Medium Modal</button>
-    <button data-modal-trigger="modal3">Large Modal</button>
-    <button data-modal-trigger="modal4">Fullscreen Modal</button>
-  </div>
+modal.show();  // Open
+modal.close(); // Close
 
-  <snice-modal id="modal1" size="small" label="Small Modal">
-    <div slot="header"><h2>Small Modal</h2></div>
-    <p>This is a small modal with minimal content.</p>
-    <div slot="footer">
-      <button data-modal-close>Close</button>
-    </div>
-  </snice-modal>
-
-  <snice-modal id="modal2" size="medium" label="Medium Modal">
-    <div slot="header"><h2>Medium Modal</h2></div>
-    <p>This is a medium-sized modal with more content.</p>
-    <p>It can hold paragraphs, images, forms, and more.</p>
-    <div slot="footer">
-      <button data-modal-close>Cancel</button>
-      <button data-modal-close>OK</button>
-    </div>
-  </snice-modal>
-
-  <snice-modal id="modal3" size="large" label="Large Modal">
-    <div slot="header"><h2>Large Modal</h2></div>
-    <p>This is a large modal for displaying lots of content.</p>
-    <p>Perfect for detailed forms or extensive information.</p>
-    <div slot="footer">
-      <button data-modal-close>Close</button>
-    </div>
-  </snice-modal>
-
-  <snice-modal id="modal4" size="fullscreen" label="Fullscreen Modal">
-    <div slot="header"><h2>Fullscreen Modal</h2></div>
-    <p>This modal takes up the entire viewport.</p>
-    <p>Ideal for immersive experiences or complex workflows.</p>
-    <div slot="footer">
-      <button data-modal-close>Close</button>
-    </div>
-  </snice-modal>
-</body>
-</html>
+modal.addEventListener('modal-open', () => console.log('Opened'));
+modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
 
-## Accessibility
-
-The modal component includes comprehensive accessibility features:
-
-- `role="dialog"` on the modal container
-- `aria-modal="true"` to indicate modal behavior
-- `aria-label` for screen reader context
-- `aria-hidden` reflects visibility state
-- Focus trap keeps keyboard navigation within modal
-- Focus restoration returns focus to trigger element on close
-- Escape key support for closing
-- Close button is keyboard accessible
-
-### Keyboard Support
-
-- **Escape**: Close modal (unless `noEscapeDismiss` is true)
-- **Tab**: Cycle through focusable elements within modal (trapped)
-- **Shift + Tab**: Reverse cycle through focusable elements
-
-## Behavior
-
-### Focus Management
+## Slots
 
-When a modal opens:
-1. Current focus is stored
-2. Body scroll is locked
-3. Focus moves to first focusable element in modal
-4. Tab navigation is trapped within the modal
+| Name | Description |
+|------|-------------|
+| (default) | Modal body content |
+| `header` | Header content (typically a title) |
+| `footer` | Footer content (typically action buttons) |
 
-When a modal closes:
-1. Body scroll is restored
-2. Focus returns to the previously focused element
+## Properties
 
-### Dismissal
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `open` | `boolean` | `false` | Whether the modal is visible |
+| `size` | `'small' \| 'medium' \| 'large' \| 'fullscreen'` | `'medium'` | Modal width variant |
+| `noBackdropDismiss` (attr: `no-backdrop-dismiss`) | `boolean` | `false` | Prevent closing on backdrop click |
+| `noEscapeDismiss` (attr: `no-escape-dismiss`) | `boolean` | `false` | Prevent closing with Escape key |
+| `noFocusTrap` (attr: `no-focus-trap`) | `boolean` | `false` | Disable focus trapping |
+| `noCloseButton` (attr: `no-close-button`) | `boolean` | `false` | Hide the close button |
+| `label` | `string` | `''` | Accessible label for screen readers |
 
-By default, modals can be dismissed by:
-- Clicking the close button
-- Clicking the backdrop
-- Pressing Escape
+## Events
 
-This behavior can be customized with `noBackdropDismiss`, `noEscapeDismiss`, and `noCloseButton` properties.
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `modal-open` | `{ modal: SniceModalElement }` | Fired when the modal opens |
+| `modal-close` | `{ modal: SniceModalElement }` | Fired when the modal closes |
 
-## Browser Support
+## Methods
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | -- | Opens the modal |
+| `close()` | -- | Closes the modal |