@aurodesignsystem/auro-dialog 4.2.0 → 4.2.1

package/demo/support/demo-support.js

@@ -0,0 +1,140 @@
+// Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+// See LICENSE in the project root for license information.
+//
+// Local-demo renderer for auro-dialog. Vendored from the Auro formkit
+// `@aurodesignsystem/utils/demo-support` module (which is a private, unpublished
+// workspace package and cannot be installed here). Renders demo pages with the
+// same unified/remark/rehype pipeline AuroDocsSite uses — NOT marked.js — so the
+// rich `docs/pages` markup (HTML + tables + fenced code) renders correctly. Also
+// injects the top page-nav from `pages.json`.
+//
+// The remark/rehype stack is loaded from the jsDelivr ESM CDN, consistent with
+// the other CDN imports in the demo HTML files.
+
+import { unified } from 'https://cdn.jsdelivr.net/npm/unified@11/+esm';
+import remarkParse from 'https://cdn.jsdelivr.net/npm/remark-parse@11/+esm';
+import remarkGfm from 'https://cdn.jsdelivr.net/npm/remark-gfm@4/+esm';
+import remarkRehype from 'https://cdn.jsdelivr.net/npm/remark-rehype@11/+esm';
+import rehypeRaw from 'https://cdn.jsdelivr.net/npm/rehype-raw@7/+esm';
+import rehypeHighlight from 'https://cdn.jsdelivr.net/npm/rehype-highlight@7/+esm';
+import rehypeStringify from 'https://cdn.jsdelivr.net/npm/rehype-stringify@10/+esm';
+
+/**
+ * Fetches `pages.json`, builds a top nav bar with a link to each page, and
+ * prepends it to <body>.
+ * @param {string} pagesDir - Directory containing pages.json (relative to the HTML file).
+ * @param {string} [activeFile] - Filename (e.g. "index.md") of the current page.
+ */
+export async function injectPageNav(pagesDir, activeFile) {
+  let files = [];
+  try {
+    const res = await fetch(`${pagesDir}pages.json`);
+    if (!res.ok) {
+      return;
+    }
+    files = await res.json();
+  } catch {
+    return;
+  }
+
+  if (!files.length || document.getElementById('page-nav')) {
+    return;
+  }
+
+  const nav = document.createElement('nav');
+  nav.id = 'page-nav';
+
+  files.forEach((file) => {
+    const label = file.replace(/\.md$/, '').replace(/-/g, ' ');
+    const a = document.createElement('auro-hyperlink');
+    a.textContent = label;
+    a.setAttribute('href', `./${file.replace(/\.md$/, '.html')}`);
+    a.setAttribute('type', 'cta');
+    a.setAttribute('variant', 'ghost');
+    a.setAttribute('size', 'sm');
+    a.dataset.page = file;
+
+    if (file === activeFile) {
+      a.setAttribute('variant', 'tertiary');
+    }
+
+    nav.appendChild(a);
+  });
+
+  document.body.prepend(nav);
+}
+
+export async function renderPage(mdPath) {
+  const pagesDir = mdPath.substring(0, mdPath.lastIndexOf('/') + 1);
+  const activeFile = mdPath.split('/').pop().split('?')[0];
+  await injectPageNav(pagesDir, activeFile);
+
+  try {
+    const response = await fetch(mdPath);
+    if (!response.ok) {
+      console.error(`Failed to load "${mdPath}": ${response.status} ${response.statusText}`);
+      return;
+    }
+
+    const text = await response.text();
+    const result = await unified()
+      .use(remarkParse)
+      .use(remarkGfm)
+      .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeRaw)
+      .use(rehypeHighlight)
+      .use(rehypeStringify)
+      .process(text);
+
+    // Parse the rendered HTML into detached nodes and move them into <main>.
+    // Content is the repo's own trusted docs markdown; avoiding innerHTML keeps
+    // the write explicit and lets custom elements upgrade on connection.
+    const parsed = new DOMParser().parseFromString(String(result), 'text/html');
+    const main = document.querySelector('main');
+    if (!main) {
+      console.error('renderPage: no <main> element found; cannot render page content.');
+      return;
+    }
+    main.replaceChildren(...parsed.body.childNodes);
+    addCopyButtons();
+  } catch (err) {
+    console.error('Error rendering markdown page:', err);
+  }
+}
+
+function addCopyButtons() {
+  document.querySelectorAll('pre code[class*="language-"], pre code[class*="hljs"]').forEach((code) => {
+    const pre = code.parentElement;
+    const wrapper = document.createElement('div');
+    wrapper.className = 'pre-wrapper';
+    pre.parentNode.insertBefore(wrapper, pre);
+    wrapper.appendChild(pre);
+    const btn = document.createElement('button');
+    btn.className = 'copy-btn';
+    btn.textContent = 'Copy';
+    btn.addEventListener('click', () => {
+      const raw = code.textContent;
+      const text = raw.replace(/​/g, '').replace(/^\n+/, '').replace(/\n+$/, '\n').replace(/^\$ /, '');
+      navigator.clipboard.writeText(text).then(() => {
+        btn.textContent = 'Copied!';
+        setTimeout(() => { btn.textContent = 'Copy'; }, 1500);
+      });
+    });
+    wrapper.appendChild(btn);
+  });
+}
+
+export function openAccordion(id) {
+  document.querySelectorAll('auro-accordion').forEach((accordion) => {
+    accordion.removeAttribute('expanded');
+  });
+  const target = document.getElementById(id);
+  if (target) {
+    target.setAttribute('expanded', '');
+    setTimeout(() => {
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }, 550);
+  }
+}
+
+window.openAccordion = openAccordion;

package/demo/voiceover.html

@@ -0,0 +1,38 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  Demo shell. Content authored in ../docs/pages/voiceover.md → ./voiceover.md.
+  Rendered by ./demo-support.js (remark/rehype) with the top page-nav from ./pages.json.
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-dialog | VoiceOver</title>
+
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+    <link rel="stylesheet" type="text/css" href="./demo-nav.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-nav@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
+
+    <script type="module">
+      import { renderPage } from './support/demo-support.js';
+      await renderPage('./voiceover.md');
+    </script>
+  </body>
+</html>

package/demo/voiceover.md

@@ -0,0 +1,19 @@
+<auro-header level="1" id="overview">Dialog - VoiceOver Behavior</auro-header>
+<p>This page documents the screen reader experience when using the <code>&lt;auro-dialog&gt;</code> component. Because the component is built on the native <code>&lt;dialog&gt;</code> element, announcements follow the platform's standard dialog conventions.</p>
+<auro-header level="2" id="openAnnouncement">Opening the Dialog</auro-header>
+<p>When the dialog opens, focus is moved into it and the screen reader announces:</p>
+<ol>
+<li><strong>Role:</strong> <em>"dialog"</em> (from the native <code>&lt;dialog&gt;</code> element).</li>
+<li><strong>Accessible name:</strong> the <code>header</code> slot content, via <code>aria-labelledby</code>.</li>
+<li><strong>Description:</strong> the <code>content</code> slot, via <code>aria-describedby</code>.</li>
+<li><strong>First control:</strong> the first focusable element inside the dialog receives focus and is announced.</li>
+</ol>
+<auro-header level="2" id="navigatingContent">Navigating Content</auro-header>
+<p>Within the dialog, the user navigates with the standard reading and Tab commands. Focus is trapped, so swiping or tabbing past the last element wraps back to the first and never lands on the obscured page behind the dialog. For a modal dialog, the rest of the page is <code>inert</code>, so the screen reader's virtual cursor cannot reach it either.</p>
+<auro-header level="2" id="closeGesture">Closing the Dialog</auro-header>
+<ul>
+<li><strong>Non-modal:</strong> the dialog can be dismissed with the close button (announced using the <code>ariaLabel.dialog.close</code> slot text, or <em>"Close"</em> by default), the <code>Esc</code> key, or the platform dismiss gesture.</li>
+<li><strong>Modal:</strong> passive dismissal is disabled. The dismiss gesture and <code>Esc</code> have no effect — the user must activate the explicit action in the footer.</li>
+</ul>
+<div class="note"><strong>iOS VoiceOver:</strong> the two-finger <em>"scrub"</em> (a <em>"Z"</em> shape) acts as the <code>Esc</code> key. <strong>Android TalkBack:</strong> the back gesture (swipe inward from a screen edge) dismisses a non-modal dialog.</div>
+<p>When the dialog closes, focus returns to the triggering element, so the screen reader resumes from where the user left off on the page.</p>

package/demo/why-dialog.html

@@ -0,0 +1,38 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  Demo shell. Content authored in ../docs/pages/why-dialog.md → ./why-dialog.md.
+  Rendered by ./demo-support.js (remark/rehype) with the top page-nav from ./pages.json.
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-dialog | Why auro-dialog</title>
+
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+    <link rel="stylesheet" type="text/css" href="./demo-nav.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-nav@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
+
+    <script type="module">
+      import { renderPage } from './support/demo-support.js';
+      await renderPage('./why-dialog.md');
+    </script>
+  </body>
+</html>

package/demo/why-dialog.md

@@ -0,0 +1,36 @@
+<auro-header level="1" id="overview">Dialog - Why auro-dialog?</auro-header>
+<p>The native HTML <code>&lt;dialog&gt;</code> element provides the foundation for overlays, but building a production-ready, accessible, on-brand dialog on top of it requires a substantial amount of repeated work. <code>&lt;auro-dialog&gt;</code> is built on the native element and layers on the behavior, styling, and accessibility that Alaska experiences need. This page explains what the component adds.</p>
+<auro-header level="2" id="modalControl">Unified modal and non-modal modes</auro-header>
+<p>Native <code>&lt;dialog&gt;</code> exposes two very different entry points — <code>show()</code> for non-modal and <code>showModal()</code> for modal — with different dismissal semantics you must wire up yourself.</p>
+<p><code>&lt;auro-dialog&gt;</code> exposes a single <code>open</code> attribute plus a <code>modal</code> toggle, and handles the rest:</p>
+<ul>
+<li>Non-modal dialogs use the Popover API and dismiss on close button, <code>Esc</code>, or backdrop click.</li>
+<li>Modal dialogs use <code>showModal()</code>, suppress passive dismissal, and hide the close button so the user must take an explicit action.</li>
+</ul>
+<auro-header level="2" id="focusManagement">Focus management</auro-header>
+<p>With the native element you are responsible for moving focus into the dialog, trapping it, and restoring it afterward. <code>&lt;auro-dialog&gt;</code> does all three automatically: it focuses the first element on open, traps <code>Tab</code> focus while open, and restores focus to the triggering element (or a configurable <code>triggerElement</code>) on close.</p>
+<auro-header level="2" id="responsiveLayout">Responsive layout</auro-header>
+<p>Native dialogs have no built-in responsive behavior. <code>&lt;auro-dialog&gt;</code> adapts to the viewport — presenting as a full-width, size-scaled panel below the mobile breakpoint — and offers <code>sm</code>, <code>md</code>, and <code>lg</code> sizes that can be decoupled between desktop and mobile.</p>
+<auro-header level="2" id="theming">Styling &amp; theming</auro-header>
+<p>Styling a native <code>&lt;dialog&gt;</code> and its <code>::backdrop</code> from scratch is tedious and easy to get wrong. <code>&lt;auro-dialog&gt;</code> ships with Auro Design System styling out of the box, plus <code>::part()</code> selectors (<code>dialog</code>, <code>dialog-header</code>, <code>dialog-content</code>, <code>dialog-footer</code>, <code>close-button</code>) and design tokens for backdrop and surface colors.</p>
+<auro-header level="2" id="accessibility">Accessibility</auro-header>
+<p>The component wires up <code>aria-labelledby</code> and <code>aria-describedby</code> from the header and content slots, renders an accessible close button with a customizable label, and manages the <code>inert</code> background for modal dialogs — the details that are easy to omit when hand-rolling a dialog.</p>
+<auro-header level="2" id="layeredComponents">Layered components</auro-header>
+<p>Placing other floating UI (popovers, dropdowns) inside a native dialog can lead to top-layer stacking conflicts. <code>&lt;auro-dialog&gt;</code> coordinates with the shared Auro floating-UI runtime so layered components stack and dismiss correctly.</p>
+<auro-header level="2" id="summary">Summary</auro-header>
+<table>
+<thead>
+<tr><th>Capability</th><th><code>&lt;dialog&gt;</code></th><th><code>auro-dialog</code></th></tr>
+</thead>
+<tbody>
+<tr><td>Modal / non-modal API</td><td>Two separate methods</td><td>Single <code>open</code> + <code>modal</code></td></tr>
+<tr><td>Focus trap &amp; restore</td><td>Manual</td><td>Automatic</td></tr>
+<tr><td>Responsive / mobile presentation</td><td>No</td><td>Automatic at breakpoint</td></tr>
+<tr><td>Size options</td><td>No</td><td><code>sm</code> / <code>md</code> / <code>lg</code>, decoupled by breakpoint</td></tr>
+<tr><td>Design system styling</td><td>Unstyled</td><td>On-brand, themeable</td></tr>
+<tr><td>Backdrop styling</td><td>Manual <code>::backdrop</code></td><td>Design tokens</td></tr>
+<tr><td>Accessible close button</td><td>Build your own</td><td>Built-in, labelable</td></tr>
+<tr><td>ARIA labelling</td><td>Manual</td><td>Wired from slots</td></tr>
+<tr><td>Layered floating components</td><td>Stacking conflicts</td><td>Coordinated top-layer</td></tr>
+</tbody>
+</table>