@amedia/brick-mcp 0.0.2 → 0.1.0

package/dist/data/components/brick-dialog.md

@@ -0,0 +1,458 @@
+---
+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