@amedia/brick-mcp 0.0.1-LLM-DOCS → 0.0.1-NEW-PATH-1

package/data/components/brick-dialog.md

@@ -1,418 +0,0 @@
----
-name: brick-dialog
-version: 2.0.13
-selector: brick-dialog-v2
-category: Feedback
-tags: [dialog, modal, overlay, popup, user-interaction, focus-management, accessibility]
-use_cases: [confirmation-dialogs, alert-messages, forms, subscription-offers, user-prompts, information-display, video-players, content-overlays]
-related: [brick-button]
----
-
-# Brick Dialog
-
-A Web Component for displaying dialog and modal windows that overlay page content and require user interaction.
-
-## Key Capabilities
-
-- **Dual modes**: Supports both non-modal dialogs and modal windows with different interaction patterns
-- **Position control**: Configure dialog position (top, center, bottom) for non-modal dialogs
-- **Template-based content**: Use HTML template tags to define header and content areas
-- **Full accessibility**: Built-in ARIA support, focus management, and keyboard navigation
-- **Focus trapping**: Automatic focus trapping for modal dialogs to ensure accessibility
-- **Automatic styling**: Includes close buttons and responsive layout out of the box
-
-## Props/Attributes
-
-| Attribute | Type | Default | Required | Description |
-|-----------|------|---------|----------|-------------|
-| `data-type` | `"dialog" \| "modal"` | `"dialog"` | no | The type of dialog to render. Use "dialog" for non-blocking overlays, "modal" for blocking interactions |
-| `data-position` | `"top" \| "center" \| "bottom"` | `"center"` | no | Position of the dialog in the viewport. Only applicable when `data-type="dialog"` |
-| `data-id` | string | - | no | Custom ID for the internal dialog element |
-
-## Examples
-
-### Basic Dialog
-
-A non-modal dialog allows users to interact with both the dialog and the underlying page content.
-
-```html
-<brick-dialog-v2 data-type="dialog" data-position="center">
-  <template data-name="header">
-    <h2>Dialog Title</h2>
-  </template>
-  <template data-name="content">
-    <p>This is a non-modal dialog. You can interact with the page behind it.</p>
-  </template>
-</brick-dialog-v2>
-
-<script>
-  const dialog = document.querySelector('brick-dialog-v2');
-  document.querySelector('.open-btn').addEventListener('click', () => {
-    dialog.openDialog();
-  });
-</script>
-```
-
-### Modal Dialog
-
-A modal dialog blocks interaction with the underlying page until dismissed.
-
-```html
-<brick-dialog-v2 data-type="modal">
-  <template data-name="header">
-    <h2>Confirm Action</h2>
-  </template>
-  <template data-name="content">
-    <p>Are you sure you want to proceed?</p>
-    <brick-button-v9 data-label="Confirm" data-version="primary"></brick-button-v9>
-    <brick-button-v9 data-label="Cancel" data-version="secondary"></brick-button-v9>
-  </template>
-</brick-dialog-v2>
-```
-
-### Dialog with Custom ID
-
-Provide a unique ID for the dialog element for better integration and tracking.
-
-```html
-<brick-dialog-v2 data-id="subscription-dialog" data-type="modal">
-  <template data-name="header">
-    <h2>Subscribe Today</h2>
-  </template>
-  <template data-name="content">
-    <p>Get access to premium content for just 1 kr!</p>
-    <brick-button-v9
-      data-label="Subscribe Now"
-      data-version="primary"
-      style="--brick-colors-buttonPrimaryBg:var(--brick-colors-buttonSignalBg);">
-    </brick-button-v9>
-  </template>
-</brick-dialog-v2>
-```
-
-### Dialog Positioned at Top
-
-Position a non-modal dialog at the top of the viewport.
-
-```html
-<brick-dialog-v2 data-type="dialog" data-position="top">
-  <template data-name="header">
-    <h2>Notification</h2>
-  </template>
-  <template data-name="content">
-    <p>New updates are available.</p>
-  </template>
-</brick-dialog-v2>
-```
-
-### Dialog with Rich Content
-
-Include complex content like forms, buttons, and links inside the dialog.
-
-```html
-<brick-dialog-v2 data-type="modal">
-  <template data-name="header">
-    <h2>Special Offer</h2>
-  </template>
-  <template data-name="content">
-    <p>Subscribe for 1 kr today!</p>
-    <brick-button-v9
-      onclick="alert('Button clicked!')"
-      data-label="Subscribe"
-      data-version="primary"
-      data-size="small">
-    </brick-button-v9>
-    <brick-button-v9
-      onclick="alert('Learn more')"
-      data-label="Learn More"
-      data-version="secondary"
-      data-size="small">
-    </brick-button-v9>
-    <p>Read more about <a href="#">what you get access to here.</a></p>
-  </template>
-</brick-dialog-v2>
-```
-
-## Framework Integration
-
-### Svelte
-
-Svelte 5 has a known issue where the first `<template>` tag may be stripped during compilation. Use a dummy template as a workaround.
-
-```svelte
-<script>
-  let dialogRef;
-
-  function openDialog() {
-    dialogRef.openDialog();
-  }
-</script>
-
-<brick-dialog-v2 bind:this={dialogRef} data-type="modal">
-  <!-- Workaround for Svelte 5 template stripping -->
-  <template data-name="template-for-svelte-compile-will-be-stripped"></template>
-
-  <template data-name="header">
-    <h2>Dialog Title</h2>
-  </template>
-
-  <template data-name="content">
-    <p>Dialog content goes here.</p>
-  </template>
-</brick-dialog-v2>
-
-<button on:click={openDialog}>Open Dialog</button>
-```
-
-### Svelte with Custom Styles
-
-You can include scoped styles within the template tags.
-
-```svelte
-<script>
-  let dialogRef;
-
-  function openDialog() {
-    dialogRef.openDialog();
-  }
-</script>
-
-<brick-dialog-v2 bind:this={dialogRef}>
-  <template data-name="header">
-    <style>
-      .custom-title {
-        color: red;
-      }
-    </style>
-    <h2><div class="custom-title">Dialog Title</div></h2>
-  </template>
-
-  <template data-name="content">
-    <p>Dialog content goes here.</p>
-  </template>
-</brick-dialog-v2>
-
-<button on:click={openDialog}>Open Dialog</button>
-```
-
-## Programmatic Usage
-
-```javascript
-import '@amedia/brick-dialog';
-
-// Create dialog element
-const dialog = document.createElement('brick-dialog-v2');
-dialog.dataset.type = 'modal';
-dialog.dataset.id = `dialog-${Math.random().toString(36).substring(2)}`;
-
-// Add content via templates
-dialog.innerHTML = `
-  <template data-name="header">
-    <h2>My Dialog</h2>
-  </template>
-  <template data-name="content">
-    <p>Dialog content here</p>
-  </template>
-`;
-
-// Append to DOM
-document.body.appendChild(dialog);
-
-// Open the dialog
-dialog.openDialog();
-
-// Close the dialog
-dialog.close();
-```
-
-### Using Methods
-
-```javascript
-const dialog = document.querySelector('brick-dialog-v2');
-
-// Open dialog (automatically calls show() or showModal() based on data-type)
-dialog.openDialog();
-
-// Alternative: use native dialog methods
-dialog.show();      // For non-modal dialogs
-dialog.showModal(); // For modal dialogs
-
-// Close dialog
-dialog.close();
-```
-
-## Accessibility
-
-The brick-dialog component is built with comprehensive accessibility features:
-
-### ARIA Support
-- Uses `role="dialog"` to inform assistive technologies
-- Adds `aria-modal="true"` for modal dialogs to indicate content underneath is inert
-- Automatically sets `aria-labelledby` if a heading with an ID is present in the header
-- Falls back to `aria-label="Dialog"` if no heading is found
-
-### Focus Management
-- Saves the previously focused element before opening
-- Automatically moves focus to the dialog when opened
-- Restores focus to the original element when closed
-- Maintains logical focus order for keyboard users
-
-### Keyboard Interactions
-- **Escape key**: Closes non-modal dialogs
-- **Tab key**: For modal dialogs, focus is trapped within the dialog
-  - Tab cycles forward through focusable elements
-  - Shift+Tab cycles backward
-  - Focus loops from last to first element and vice versa
-
-### Background Interaction Prevention
-- Modal dialogs add `aria-hidden="true"` to the `<body>` element
-- Disables scrolling on the body when modal is open
-- Ensures users cannot accidentally interact with background content
-
-### Close Buttons
-- Accessible close button in the header
-- Additional close button in the footer for modal dialogs
-- Both buttons use the accessible `brick-button-v9` component
-
-## CSS Customization
-
-The dialog supports CSS custom properties for styling customization. Scope your overrides appropriately.
-
-| Property | Description | Default |
-|----------|-------------|---------|
-| `--b-dialog-max-inline-size` | Controls the maximum width of the dialog | `80vw` |
-
-### Example
-
-```html
-<style>
-  brick-dialog-v2 {
-    --b-dialog-max-inline-size: 600px;
-  }
-
-  brick-dialog-v2 header {
-    border-bottom: 1px solid grey;
-    padding-bottom: var(--brick-space-x1);
-  }
-
-  brick-dialog-v2 p {
-    font-family: var(--brick-fonts-baseBodyM);
-  }
-</style>
-```
-
-## Template Tags
-
-Content is added to the dialog using HTML `<template>` tags with `data-name` attributes.
-
-| data-name | Description |
-|-----------|-------------|
-| `header` | Content for the dialog header (appears before the close button) |
-| `content` | Main content area of the dialog |
-
-## Common Patterns
-
-### Subscription Offer Modal
-
-Display a subscription offer that requires user attention.
-
-```html
-<brick-dialog-v2 data-type="modal" data-id="subscription-modal">
-  <template data-name="header">
-    <h2>Special Offer</h2>
-  </template>
-  <template data-name="content">
-    <p>Subscribe for only 1 kr today!</p>
-    <brick-button-v9
-      data-label="Subscribe Now"
-      data-version="primary"
-      style="--brick-colors-buttonPrimaryBg:var(--brick-colors-buttonSignalBg);">
-    </brick-button-v9>
-    <p>Learn more about <a href="/subscription">all the benefits here</a>.</p>
-  </template>
-</brick-dialog-v2>
-```
-
-### Confirmation Dialog
-
-Use a modal for critical actions requiring confirmation.
-
-```html
-<brick-dialog-v2 data-type="modal">
-  <template data-name="header">
-    <h2>Delete Confirmation</h2>
-  </template>
-  <template data-name="content">
-    <p>Are you sure you want to delete this item? This action cannot be undone.</p>
-    <brick-button-v9
-      class="confirm-delete"
-      data-label="Delete"
-      data-version="primary"
-      data-size="small">
-    </brick-button-v9>
-    <brick-button-v9
-      class="cancel"
-      data-label="Cancel"
-      data-version="secondary"
-      data-size="small">
-    </brick-button-v9>
-  </template>
-</brick-dialog-v2>
-```
-
-### Non-Modal Information Dialog
-
-Use a non-modal dialog for supplementary information.
-
-```html
-<brick-dialog-v2 data-type="dialog" data-position="bottom">
-  <template data-name="header">
-    <h2>Tip</h2>
-  </template>
-  <template data-name="content">
-    <p>You can use keyboard shortcuts to navigate faster!</p>
-  </template>
-</brick-dialog-v2>
-```
-
-## Technical Details
-
-- **Custom Element**: `brick-dialog-v2`
-- **Base Class**: BrickElement
-- **Dependencies**: @amedia/brick-template, @amedia/brick-tokens, @amedia/brick-button
-- **Renders as**: `<dialog>` element with wrapper divs and header/footer structure
-
-## Important Notes
-
-### Dialog vs Modal Choice
-
-**Use a dialog when:**
-- Information or interaction is supplementary and non-critical
-- Users might need to interact with both the dialog and main content
-- Minimizing workflow disruption is important
-
-**Use a modal when:**
-- Immediate user action is required before proceeding
-- User focus must be solely on the modal content
-- Preventing interaction with main content is necessary to avoid errors
-
-### Unique IDs
-
-Always provide a unique ID for the dialog when possible:
-
-```javascript
-const dialogId = `dialog-${Math.random().toString(36).substring(2)}`;
-// Or use a UUID library for more robustness
-```
-
-### Server-Side Rendering
-
-The current version (2.0.13) does not support server-side rendering. Future versions may add this capability if needed.
-
-### Template Tag Attributes
-
-Use `data-name` (not `name`) for template tag identification. This was changed in version 1.0.0.
-
-## Version
-
-Current version: 2.0.13