@rcarls/rc-dialog 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# @rcarls/rc-dialog
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 4341311: Add reusable fullscreen dialogs and declarative dialog popup mode to `rc-select` and
+  `rc-combobox`. Dialog selection and creation are staged until Done, while close and Escape
+  discard the draft. Fullscreen surfaces follow the visual viewport under browser zoom and
+  software keyboards, and anchored popups now clamp to the visual viewport.
+- 2c7c80a: Give `rc-dialog` a surface styling contract.
+
+  It exposed only `--rc-dialog-scrim`, so both themes drew the surface by selecting the native
+  `<dialog>` directly. It now installs a light-DOM base stylesheet, the same pattern as `rc-button`
+  and `rc-disclosure`, and exposes minimum and maximum inline and block bounds, padding, border, radius, background,
+  foreground, and shadow, plus fullscreen-specific padding and background for the two values that
+  variant genuinely needs of its own.
+
+  Fullscreen geometry, meaning position, size, margin, radius, and shadow, stays structural rather
+  than something a theme sets: filling the visual viewport is what keeps the surface correct under browser zoom
+  and a software keyboard.
+
+  Material's explicit block bound with `overflow: hidden` moved into the base layer rather than
+  staying a theme value. It exists because Chromium does not reliably clip a scrolling element's
+  own border radius at the scroll boundary, which is a correctness fix every theme needs.
+
+  `--rc-dialog-visual-viewport-left`, `-top`, `-width`, and `-height` are no longer documented as
+  theme properties. They are geometry the component writes while a fullscreen dialog is open:
+  readable if something inside the dialog needs the same measurements, but setting them does not
+  move the dialog. They are candidates for private `--_rc-dialog-*` names in a future revision.
+
+- 57338f5: `rc-dialog`, `rc-bottom-sheet`, and `rc-snackbar` now fade in and out through
+  CSS alone, using `@starting-style` and a discrete `display`/`overlay`
+  transition, driven by the shared `--rc-motion-effects-*` tokens (and
+  `--rc-motion-spatial-*` for `rc-snackbar`'s slide). `showModal()`/`show()`/
+  `close()` all stay synchronous, and nothing in any of the three components
+  waits on the transition finishing, so a zero-duration theme or a browser
+  without support for the CSS involved both degrade to an instant, fully
+  correct open and close.
+
+  `rc-dialog` and `rc-bottom-sheet` animate opacity only, not a scale or slide
+  transform: both support pointer resize and read `getBoundingClientRect()` to
+  compute drag deltas, and a transform is a visual effect that
+  `getBoundingClientRect()` reports for as long as it's still animating,
+  corrupting that measurement if a resize or drag starts during the entrance.
+  `rc-snackbar` has no such feature, so it fades and slides up from the
+  block-end edge it's anchored to.
+
+### Patch Changes
+
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Patch Changes
+
+- 57370e4: Align component metadata, aggregate framework typings, development-time native-child
+  validation, controlled menu state, package declarations, and public documentation before the
+  next release.
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- e57277f: Add Material 3 search-view, fixed-pane splitter, dialog scrim, and resize enhancements.
+
+  `rc-search-bar` now supports `variant="view"`, controlled/default open state, search-view methods, a rich `suggestions` slot, and datalist-derived text suggestions. `rc-splitter` adds `mode="fixed"` for clampable pixel primary panes. `rc-common` now honors CSS max-size constraints during resize gestures, and `rc-dialog` exposes a scrim token plus resize handle/origin hooks used by themed surfaces.
+
+### Patch Changes
+
+- Updated dependencies [e57277f]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+  - @rcarls/rc-common@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+
+## 0.3.0
+
+### Added
+
+- Add non-modal `show()` support and the `modal` property for controlled open behavior.
+- Add `rc-dialog-open` and `rc-dialog-toggle` events.
+
+### Changed
+
+- Warn in development when the inner `<dialog>` has no enabled button.
+- Update package metadata, README intro, and docs links.
+
+### Fixed
+
+- Restore focus to `document.body` when the opener is removed while the dialog is open.
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0
+
+### Patch Changes
+
+- @rcarls/rc-common@0.2.0

package/README.md

@@ -0,0 +1,348 @@
+# `@rcarls/rc-dialog`
+
+Draggable, resizable wrapper for a native `<dialog>`, following the [WAI-ARIA Dialog Modal pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-dialog](https://richardcarls.github.io/rc-webcomponents/components/rc-dialog).
+
+---
+
+## Installation
+
+```bash
+npm install @rcarls/rc-dialog
+```
+
+## Import
+
+```js
+import '@rcarls/rc-dialog'; // side-effect: registers <rc-dialog>
+import { RCDialog } from '@rcarls/rc-dialog'; // named class export
+```
+
+---
+
+## Basic usage
+
+Place a `<dialog>` element directly inside `<rc-dialog>`. The inner `<dialog>` must have
+`aria-labelledby` or `aria-label` to satisfy the
+[WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
+
+```html
+<rc-dialog id="my-dialog">
+  <dialog aria-labelledby="dlg-title">
+    <h2 id="dlg-title">Hello</h2>
+    <p>Dialog content.</p>
+    <button onclick="document.querySelector('#my-dialog').close()">Close</button>
+  </dialog>
+</rc-dialog>
+
+<button onclick="document.querySelector('#my-dialog').showModal()">Open</button>
+```
+
+---
+
+## API
+
+### Properties / attributes
+
+| Property          | Attribute          | Type                                                                                                           | Default      | Description                                                                                                                                                                                           |
+| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`            | `open`             | `boolean`                                                                                                      | None         | Controlled open state. Setting to `true`/`false` opens/closes the dialog silently (no `rc-dialog-toggle` event). Reads the inner `<dialog>.open` value.                                               |
+| `defaultOpen`     | `default-open`     | `boolean`                                                                                                      | `false`      | Uncontrolled initial open state. The component takes ownership after initialization.                                                                                                                  |
+| `variant`         | `variant`          | `'standard' \| 'fullscreen'`                                                                                   | `'standard'` | Surface presentation. Fullscreen themes the direct child dialog to the current visual viewport and disables move/resize controllers.                                                                  |
+| `modal`           | None               | `boolean`                                                                                                      | `true`       | Whether controlled `open` / `defaultOpen` opens as modal (`showModal`) or non-modal (`show`). No effect on direct `showModal()` / `show()` calls. JS property only; no attribute.                     |
+| `movable`         | `movable`          | `boolean`                                                                                                      | `false`      | Enable drag-to-move. Named `movable` (not `draggable`) to avoid colliding with the HTML `draggable` attribute.                                                                                        |
+| `moveHandle`      | `move-handle`      | `string`                                                                                                       | `''`         | CSS selector for the drag handle within the inner `<dialog>` (for example, `'.titlebar'`). Defaults to the whole dialog.                                                                              |
+| `moveBounds`      | `move-bounds`      | `'viewport' \| 'parent'`                                                                                       | `'viewport'` | Constrains drag within the viewport or the nearest positioned ancestor.                                                                                                                               |
+| `moveStep`        | `move-step`        | `number`                                                                                                       | `4`          | Keyboard arrow-key step in px when moving. Shift multiplies by 10×.                                                                                                                                   |
+| `resize`          | `resize`           | `'none' \| 'both' \| 'horizontal' \| 'vertical'`                                                               | `'none'`     | Enables edge/corner resizing, mirroring CSS `resize` semantics.                                                                                                                                       |
+| `resizeOrigin`    | `resize-origin`    | `'' \| 'top' \| 'right' \| 'bottom' \| 'left' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `''`         | Constrains fallback edge detection or supplies the default origin for explicit handles. Empty keeps free edge detection.                                                                              |
+| `resizeHandle`    | `resize-handle`    | `string`                                                                                                       | `''`         | CSS selector for explicit resize handles within the inner `<dialog>`. Matching handles receive pointer and keyboard resize behavior.                                                                  |
+| `resizeThreshold` | `resize-threshold` | `number`                                                                                                       | `8`          | Edge hit-test band in px (straddles the border, half inside and half outside).                                                                                                                        |
+| `resizeStep`      | `resize-step`      | `number`                                                                                                       | `4`          | Keyboard arrow-key step in px when resizing. Shift multiplies by 10×.                                                                                                                                 |
+| `closedBy`        | `closed-by`        | `'any' \| 'closerequest' \| 'none' \| ''`                                                                      | `''`         | Proxied to the inner `<dialog closedby="...">` attribute (Chrome 134+, Safari 18.4+, Firefox 139+). `'any'` = Escape or backdrop click; `'closerequest'` = Escape only; `'none'` = programmatic only. |
+| `lightDismiss`    | `light-dismiss`    | `boolean`                                                                                                      | `false`      | JS fallback for backdrop-click dismissal. Detects clicks whose target is the `<dialog>` element itself and calls `requestClose()`. Works in all browsers alongside or instead of `closed-by`.         |
+
+### Methods
+
+```ts
+showModal(): void          // Opens as modal (traps focus, shows backdrop).
+show(): void               // Opens as non-modal.
+close(returnValue?): void  // Closes immediately; sets returnValue.
+requestClose(returnValue?): void
+  // Requests close: fires rc-dialog-request-close first. If not prevented,
+  // proceeds to close. Falls back to a synthesized cancel event on older
+  // browsers that lack native HTMLDialogElement.requestClose().
+```
+
+### Read-only getters
+
+```ts
+open: boolean; // Whether the inner <dialog> is currently open.
+returnValue: string; // The return value set when the dialog last closed.
+```
+
+### Events
+
+| Event                     | Cancelable | Detail                                   | Description                                                                                                      |
+| ------------------------- | ---------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `rc-dialog-open`          | No         | None                                     | Fired when the dialog opens via `showModal()` or `show()`.                                                       |
+| `rc-dialog-toggle`        | No         | `{ open: boolean, returnValue: string }` | Fired when user or native interaction changes the open state. Not fired on silent host writes (`open` property). |
+| `rc-dialog-request-close` | **Yes**    | `{ returnValue: string }`                | Fired before close (Escape, backdrop click, or `requestClose()`). Call `preventDefault()` to block.              |
+| `rc-dialog-cancel`        | No         | None                                     | Fired after `rc-dialog-request-close` when the close was not prevented. Backward-compatible alias.               |
+| `rc-dialog-close`         | No         | `{ returnValue: string }`                | Fired after the dialog has closed.                                                                               |
+
+---
+
+### Theming
+
+Set the `--rc-dialog-min-inline-size`, `--rc-dialog-max-inline-size`, and
+`--rc-dialog-max-block-size` surface bounds on `<rc-dialog>` or a theme scope.
+The component also exposes surface padding, border, radius, background,
+foreground, shadow, and `--rc-dialog-scrim` properties. Theme packages map
+their design-system values onto those public properties.
+
+---
+
+## Examples
+
+### Movable dialog with a drag handle
+
+```html
+<rc-dialog id="dlg" movable move-handle=".titlebar">
+  <dialog aria-labelledby="dlg-title">
+    <div class="titlebar">
+      <span id="dlg-title">Settings</span>
+      <button onclick="document.querySelector('#dlg').close()">✕</button>
+    </div>
+    <div class="body">…</div>
+  </dialog>
+</rc-dialog>
+```
+
+Drag the `.titlebar` to reposition. Focus the titlebar and use **Arrow keys** to move it
+(Shift = 10× step).
+
+### Fullscreen dialog
+
+`variant="fullscreen"` is a separately usable surface variant. It tracks the visual viewport,
+including zoom offsets and software-keyboard resizing, while the dialog is open. The consumer
+still owns the native dialog content and accessible header/actions.
+
+```html
+<rc-dialog id="picker" variant="fullscreen">
+  <dialog aria-labelledby="picker-title">
+    <header>
+      <button aria-label="Close" onclick="picker.close('cancel')">✕</button>
+      <h2 id="picker-title">Categories</h2>
+      <button onclick="picker.close('done')">Done</button>
+    </header>
+  </dialog>
+</rc-dialog>
+```
+
+### Movable + resizable
+
+```html
+<rc-dialog id="dlg" movable move-handle=".titlebar" resize="both">
+  <dialog aria-labelledby="dlg-title" style="min-width: 20rem; min-height: 10rem;">…</dialog>
+</rc-dialog>
+```
+
+All eight resize handles are active (top, right, bottom, left, and the four corners).
+Opposite-edge handles anchor the far side and move `left` or `top`, mirroring OS-window resize
+semantics. A small keyboard-accessible resize button is injected at the bottom-right corner.
+
+### Explicit resize handle
+
+```html
+<rc-dialog id="sheet-like" resize="vertical" resize-origin="top" resize-handle=".resize-handle">
+  <dialog aria-labelledby="sheet-title">
+    <button
+      type="button"
+      class="resize-handle"
+      data-rc-dialog-resize-axis="y"
+      data-rc-dialog-resize-origin="top"
+      aria-label="Resize"
+    ></button>
+    <h2 id="sheet-title">Filters</h2>
+  </dialog>
+</rc-dialog>
+```
+
+Use `data-rc-dialog-resize-axis="x|y|both"` and
+`data-rc-dialog-resize-origin="top|right|bottom|left|top-left|..."`
+on individual handles to override the host resize direction or origin.
+
+### Minimal / no-header dialog
+
+No titlebar or footer structure is required. Any layout is valid.
+
+```html
+<rc-dialog id="dlg">
+  <dialog
+    aria-labelledby="dlg-title"
+    aria-describedby="dlg-desc"
+    style="border-radius: 12px; padding: 2rem; position: relative;"
+  >
+    <button
+      style="position:absolute;top:.5rem;right:.5rem;"
+      onclick="document.querySelector('#dlg').close()"
+      aria-label="Close"
+    >
+      ✕
+    </button>
+    <h3 id="dlg-title">Quick note</h3>
+    <p id="dlg-desc">Content here.</p>
+  </dialog>
+</rc-dialog>
+```
+
+### Alert / confirm dialog
+
+Use `role="alertdialog"` with `aria-describedby` pointing to the message text. Assistive
+technology treats this with higher urgency.
+
+```html
+<rc-dialog id="confirm">
+  <dialog role="alertdialog" aria-labelledby="confirm-title" aria-describedby="confirm-msg">
+    <div class="titlebar"><span id="confirm-title">Delete item?</span></div>
+    <p id="confirm-msg">This action cannot be undone.</p>
+    <div class="footer">
+      <button onclick="document.querySelector('#confirm').close('cancel')">Cancel</button>
+      <button onclick="document.querySelector('#confirm').close('delete')">Delete</button>
+    </div>
+  </dialog>
+</rc-dialog>
+```
+
+### Native form integration
+
+`<form method="dialog">` submits to the dialog: the submit button's `value` becomes
+`returnValue`, and the dialog closes without JavaScript.
+
+```html
+<rc-dialog id="dlg">
+  <dialog aria-labelledby="dlg-title">
+    <div class="titlebar">
+      <span id="dlg-title">New contact</span>
+      <button formmethod="dialog" form="contact-form" value="cancel">✕</button>
+    </div>
+    <form id="contact-form" method="dialog">
+      <label>Name <input name="name" type="text" /></label>
+      <label>Email <input name="email" type="email" /></label>
+    </form>
+    <div class="footer">
+      <button formmethod="dialog" form="contact-form" value="cancel">Cancel</button>
+      <button type="submit" form="contact-form" value="save">Save</button>
+    </div>
+  </dialog>
+</rc-dialog>
+```
+
+### Cancelable close guard (unsaved changes)
+
+```html
+<rc-dialog id="dlg" movable move-handle=".titlebar">
+  <dialog aria-labelledby="dlg-title">
+    <div class="titlebar">
+      <span id="dlg-title">Edit note</span>
+      <!-- requestClose() fires rc-dialog-request-close; close() bypasses it -->
+      <button onclick="document.querySelector('#dlg').requestClose('cancel')">✕</button>
+    </div>
+    <textarea id="note" rows="5"></textarea>
+    <p id="warning" hidden role="alert">Unsaved changes; save or discard first.</p>
+    <div class="footer">
+      <button onclick="note.value=''; dlg.close('discard')">Discard</button>
+      <button onclick="dlg.close('save')">Save</button>
+    </div>
+  </dialog>
+</rc-dialog>
+
+<script>
+  document.querySelector('#dlg').addEventListener('rc-dialog-request-close', (e) => {
+    if (document.querySelector('#note').value.trim()) {
+      e.preventDefault();
+      document.querySelector('#warning').hidden = false;
+    }
+  });
+</script>
+```
+
+### Light-dismiss (click backdrop to close)
+
+```html
+<!-- Native (Chrome 134+ / Safari 18.4+ / Firefox 139+) + JS fallback -->
+<rc-dialog id="dlg" closed-by="any" light-dismiss>
+  <dialog aria-labelledby="dlg-title" aria-describedby="dlg-body">
+    <div class="header"><span id="dlg-title">Info</span></div>
+    <div id="dlg-body">Click the backdrop or press Escape to dismiss.</div>
+  </dialog>
+</rc-dialog>
+```
+
+`closed-by="any"` delegates to the browser's native light-dismiss on supporting browsers.
+`light-dismiss` adds a JS click-on-backdrop fallback that works everywhere and routes through
+`requestClose()`, so close guards still apply.
+
+---
+
+## Accessibility
+
+`<rc-dialog>` delegates entirely to the native `<dialog>` element:
+
+- **Focus trapping:** Built into `showModal()` (Tab/Shift+Tab stays inside the dialog).
+- **Focus restoration:** `rc-dialog` captures the focused element before opening and restores
+  focus to it on close. If the opener was removed from the DOM while the dialog was open, focus
+  falls back to `document.body`.
+- **Escape to close:** Native behavior routes through `rc-dialog-request-close` so guards still
+  apply.
+- **`aria-modal`:** `showModal()` implies `aria-modal="true"` without an explicit attribute.
+
+**Required:** The inner `<dialog>` must have `aria-labelledby` or `aria-label`. In development
+mode the component logs a console warning if either is absent.
+
+**Alert dialogs:** When `role="alertdialog"` is set, add `aria-describedby` pointing to the
+message text. A dev-mode warning fires if it is missing.
+
+---
+
+## CSS layout for scrollable dialogs
+
+When the dialog needs scrollable body content (especially when resizable), use flex layout so
+the body grows and the header/footer stay fixed:
+
+```css
+dialog[open] {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden; /* dialog box doesn't scroll; body does */
+}
+
+.dlg-header,
+.dlg-footer {
+  flex-shrink: 0;
+}
+
+.dlg-body {
+  flex: 1;
+  overflow: auto;
+  min-height: 0; /* lets flex child shrink below content height */
+}
+```
+
+> **Note:** `display: flex` must be scoped to `dialog[open]`, not `dialog`. Author styles take
+> precedence over the UA `dialog:not([open]) { display: none }` rule. Scoping to `[open]`
+> prevents all dialogs from being visible on page load.
+
+---
+
+## Browser support
+
+| Feature                              | Requirement                                                                 |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| Core (`<dialog>` delegation, events) | Chrome 37+, Firefox 98+, Safari 15.4+                                       |
+| Drag / resize                        | Any browser supporting Pointer Events                                       |
+| `closed-by` attribute proxy          | Chrome 134+, Safari 18.4+, Firefox 139+                                     |
+| `requestClose()` native method       | Chrome 134+, Safari 18.4+, Firefox 139+ (fallback active on older browsers) |
+| `light-dismiss` JS fallback          | All browsers                                                                |