luxen-ui 0.1.0

package/dist/skills/luxen-ui/references/dialog.md

@@ -0,0 +1,435 @@
+---
+outline: deep
+---
+
+# Dialog
+
+Dialogs display critical information or request user input in a modal overlay that blocks interaction with the rest of the page. Commonly used for confirmations, forms, and alerts.
+
+<ElementSpec
+  tag="l-dialog"
+  type="shadow"
+/>
+
+## Options
+
+### Basic
+
+Open with `command="--show"` on a trigger button. Any descendant with `command="--hide"` closes the dialog. Note the `--` prefix — it's required by the native [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API) for custom elements.
+
+```html
+<button
+  type="button"
+  class="l-button"
+  command="--show"
+  commandfor="my-dialog"
+>
+  Open dialog
+</button>
+
+<l-dialog
+  id="my-dialog"
+  title="Dialog title"
+>
+  <button
+    slot="close"
+    type="button"
+    class="l-close"
+    data-appearance="ring"
+    aria-label="Close"
+    command="--hide"
+    commandfor="my-dialog"
+  ></button>
+  <article class="h-[340px]">…</article>
+  <menu slot="footer">
+    <button
+      autofocus
+      type="button"
+      class="l-button"
+      command="--hide"
+      commandfor="my-dialog"
+    >
+      Cancel
+    </button>
+    <button
+      type="button"
+      class="l-button"
+      data-variant="primary"
+    >
+      Confirm
+    </button>
+  </menu>
+</l-dialog>
+```
+
+### Light dismiss
+
+Add `light-dismiss` to close when the backdrop is clicked.
+
+```html
+<button
+  type="button"
+  class="l-button"
+  command="--show"
+  commandfor="dialog-light-dismiss"
+>
+  Open dialog
+</button>
+
+<l-dialog
+  id="dialog-light-dismiss"
+  title="Dialog title"
+  light-dismiss
+>
+  <button
+    slot="close"
+    type="button"
+    class="l-close"
+    data-appearance="ring"
+    aria-label="Close"
+    command="--hide"
+    commandfor="dialog-light-dismiss"
+  ></button>
+  <article class="py-4">
+    <p>Click the backdrop or press Escape to close.</p>
+  </article>
+  <menu slot="footer">
+    <button
+      type="button"
+      class="l-button"
+      command="--hide"
+      commandfor="dialog-light-dismiss"
+    >
+      Close
+    </button>
+  </menu>
+</l-dialog>
+```
+
+### Scrollable content
+
+Long content can scroll while the header stays in view.
+
+```html
+<button
+  type="button"
+  class="l-button"
+  command="--show"
+  commandfor="dialog-scrollable"
+>
+  Open dialog
+</button>
+
+<l-dialog
+  id="dialog-scrollable"
+  title="Terms of Service"
+>
+  <button
+    slot="close"
+    type="button"
+    class="l-close"
+    data-appearance="ring"
+    aria-label="Close"
+    command="--hide"
+    commandfor="dialog-scrollable"
+  ></button>
+  <article class="flex flex-col gap-4">
+    <h3 class="font-semibold">1. Acceptance</h3>
+    <p>
+      By accessing or using this service, you agree to be bound by these terms. If you disagree with
+      any part of the terms, you may not access the service. These terms apply to all visitors,
+      users, and others who access or use the service.
+    </p>
+    <h3 class="font-semibold">2. Accounts</h3>
+    <p>
+      When you create an account with us, you must provide accurate, complete, and current
+      information at all times. Failure to do so constitutes a breach of the terms, which may result
+      in immediate termination of your account on our service.
+    </p>
+    <p>
+      You are responsible for safeguarding the password that you use to access the service and for
+      any activities or actions under your password, whether your password is with our service or a
+      third-party service.
+    </p>
+    <h3 class="font-semibold">3. Content</h3>
+    <p>
+      Our service allows you to post, link, store, share and otherwise make available certain
+      information, text, graphics, videos, or other material. You are responsible for the content
+      that you post, including its legality, reliability, and appropriateness.
+    </p>
+    <p>
+      By posting content, you grant us the right and license to use, modify, publicly perform,
+      publicly display, reproduce, and distribute such content on and through the service. You
+      retain any and all of your rights to any content you submit, post or display.
+    </p>
+    <h3 class="font-semibold">4. Prohibited uses</h3>
+    <p>
+      You may use the service only for lawful purposes and in accordance with these terms. You agree
+      not to use the service in any way that violates any applicable national or international law
+      or regulation.
+    </p>
+    <p>
+      You may not exploit, harm, or attempt to exploit or harm minors in any way by exposing them to
+      inappropriate content, asking for personally identifiable information, or otherwise.
+    </p>
+    <p>
+      You may not transmit, or procure the sending of, any advertising or promotional material,
+      including any junk mail, chain letter, spam, or any other similar solicitation.
+    </p>
+    <h3 class="font-semibold">5. Termination</h3>
+    <p>
+      We may terminate or suspend your account immediately, without prior notice or liability, for
+      any reason whatsoever, including without limitation if you breach the terms. Upon termination,
+      your right to use the service will immediately cease.
+    </p>
+    <p>
+      If you wish to terminate your account, you may simply discontinue using the service. All
+      provisions of the terms which by their nature should survive termination shall survive
+      termination.
+    </p>
+    <h3 class="font-semibold">6. Limitation of liability</h3>
+    <p>
+      In no event shall the company, nor its directors, employees, partners, agents, suppliers, or
+      affiliates, be liable for any indirect, incidental, special, consequential, or punitive
+      damages resulting from your use of the service.
+    </p>
+    <h3 class="font-semibold">7. Changes</h3>
+    <p>
+      We reserve the right, at our sole discretion, to modify or replace these terms at any time. If
+      a revision is material, we will provide at least 30 days notice prior to any new terms taking
+      effect. What constitutes a material change will be determined at our sole discretion.
+    </p>
+  </article>
+  <menu slot="footer">
+    <button
+      type="button"
+      class="l-button"
+      command="--hide"
+      commandfor="dialog-scrollable"
+    >
+      Decline
+    </button>
+    <button
+      type="button"
+      class="l-button"
+      data-variant="primary"
+      command="--hide"
+      commandfor="dialog-scrollable"
+    >
+      Accept
+    </button>
+  </menu>
+</l-dialog>
+```
+
+### Blurred backdrop
+
+Set `--backdrop-blur` to any CSS length to frost the page behind the dialog. Defaults to `0` (no blur).
+
+```html
+<button
+  type="button"
+  class="l-button"
+  command="--show"
+  commandfor="dialog-blurred-backdrop"
+>
+  Open dialog
+</button>
+
+<l-dialog
+  id="dialog-blurred-backdrop"
+  title="Dialog title"
+  style="--backdrop-blur: 4px"
+>
+  <button
+    slot="close"
+    type="button"
+    class="l-close"
+    data-appearance="ring"
+    aria-label="Close"
+    command="--hide"
+    commandfor="dialog-blurred-backdrop"
+  ></button>
+  <p>The page behind this dialog is blurred via <code>--backdrop-blur</code>.</p>
+  <menu slot="footer">
+    <button
+      type="button"
+      class="l-button"
+      command="--hide"
+      commandfor="dialog-blurred-backdrop"
+    >
+      Cancel
+    </button>
+    <button
+      type="button"
+      class="l-button"
+      data-variant="primary"
+      command="--hide"
+      commandfor="dialog-blurred-backdrop"
+    >
+      Confirm
+    </button>
+  </menu>
+</l-dialog>
+```
+
+### Form with autofocus
+
+Add `autofocus` to any focusable element inside the dialog to focus it automatically on open.
+
+```html
+<button
+  type="button"
+  class="l-button"
+  command="--show"
+  commandfor="dialog-form"
+>
+  Edit profile
+</button>
+
+<l-dialog
+  id="dialog-form"
+  title="Edit profile"
+>
+  <button
+    slot="close"
+    type="button"
+    class="l-close"
+    data-appearance="ring"
+    aria-label="Close"
+    command="--hide"
+    commandfor="dialog-form"
+  ></button>
+  <form class="flex flex-col gap-4">
+    <label class="flex flex-col gap-1">
+      <span class="text-sm font-medium">Name</span>
+      <input
+        autofocus
+        type="text"
+        name="name"
+        value="Ada Lovelace"
+        required
+        class="rounded border px-3 py-2 text-sm outline-none focus:border-sky-500"
+      />
+    </label>
+    <label class="flex flex-col gap-1">
+      <span class="text-sm font-medium">Email</span>
+      <input
+        type="email"
+        name="email"
+        value="ada@example.com"
+        required
+        class="rounded border px-3 py-2 text-sm outline-none focus:border-sky-500"
+      />
+    </label>
+  </form>
+  <menu slot="footer">
+    <button
+      type="button"
+      class="l-button"
+      command="--hide"
+      commandfor="dialog-form"
+    >
+      Cancel
+    </button>
+    <button
+      type="button"
+      class="l-button"
+      data-variant="primary"
+      command="--hide"
+      commandfor="dialog-form"
+    >
+      Save
+    </button>
+  </menu>
+</l-dialog>
+```
+
+## Accessibility
+
+### Criteria
+
+| Check | Description |
+|-------|-------------|
+| Role | Rendered as a native `<dialog>` in the shadow root — built-in `dialog` role and modal semantics |
+| Accessible name | The `title` property is rendered as an `<h2>` inside the dialog header |
+| Focus management | Focus is trapped inside the modal; moves to the first focusable element on open |
+| Focus restoration | Focus returns to the trigger element when the dialog closes |
+| Close button | Consumer provides the close button via `slot="close"` with `aria-label="Close"` |
+| Motion | Respects `prefers-reduced-motion` |
+
+### Rules
+- Always set a meaningful `title` — it becomes the dialog heading and accessible name
+- Put the close button in `slot="close"` with `class="l-close"` and `command="--hide"` `commandfor="<id>"`
+- Use `command="--show"` and `command="--hide"` with `commandfor` pointing at the dialog id. The `--` prefix is mandatory for custom elements
+
+### Keyboard interactions
+
+| Key | Description |
+|-----|-------------|
+| Escape | Closes the dialog |
+| Tab | Cycles focus through focusable elements inside the dialog |
+| Shift + Tab | Cycles focus backward through focusable elements inside the dialog |
+
+## API reference
+
+### Importing
+
+```js
+import 'luxen-ui/dialog';
+```
+
+### Attributes & Properties
+
+<ApiTable :data="[
+  { Attribute: 'title', Description: 'Dialog title rendered in the header as an `<h2>`' },
+  { Attribute: 'open', Description: 'Whether the dialog is open. Reflects to attribute' },
+  { Attribute: 'light-dismiss', Description: 'Close when the backdrop is clicked' },
+]" />
+
+### Commands
+
+Open and close the dialog by toggling its `open` property, or via the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API) from any light-DOM button. Custom commands must start with `--`.
+
+<ApiTable :data="[
+  { Command: '--show', Description: 'Sets `open = true`' },
+  { Command: '--hide', Description: 'Sets `open = false`' },
+]" />
+
+### Events
+
+<ApiTable :data="[
+  { Event: 'show', Description: 'Fired when the dialog opens' },
+  { Event: 'after-show', Description: 'Fired after the open animation completes' },
+  { Event: 'hide', Description: 'Fired when the dialog is about to close. Cancelable — call `event.preventDefault()` to keep it open' },
+  { Event: 'after-hide', Description: 'Fired after the close animation completes' },
+]" />
+
+### Slots
+
+<ApiTable :data="[
+  { Slot: '(default)', Description: 'Body content' },
+  { Slot: 'close', Description: 'Close button (typically `<button class=&quot;l-close&quot;>`)' },
+  { Slot: 'footer', Description: 'Footer actions' },
+]" />
+
+### CSS parts
+
+<ApiTable :data="[
+  { Part: 'dialog', Description: 'The native `<dialog>` element' },
+  { Part: 'header', Description: 'The header wrapper containing the title and close slot' },
+  { Part: 'title', Description: 'The dialog title heading' },
+  { Part: 'body', Description: 'The body wrapper around the default slot' },
+  { Part: 'footer', Description: 'The footer wrapper around the footer slot' },
+]" />
+
+### CSS custom properties
+
+<ApiTable :data="[
+  { Name: '--width', Description: 'Dialog width. Default `31rem`' },
+  { Name: '--border-radius', Description: 'Border radius. Default `6px`' },
+  { Name: '--show-duration', Description: 'Open transition duration. Default `200ms`' },
+  { Name: '--hide-duration', Description: 'Close transition duration. Default `200ms`' },
+  { Name: '--backdrop', Description: 'Backdrop color' },
+  { Name: '--backdrop-blur', Description: 'Backdrop blur amount (any CSS length). Default `0`' },
+]" />