@ds-gn/ui 0.0.0-stage → 0.5.0

package/dist/components/Modal/src/Modal.d.ts

@@ -0,0 +1,166 @@
+import '../../../types/global.d.ts';
+import '../../Button/src/Button.js';
+import { type CSSResultGroup } from 'lit';
+import { Base } from '../../../common/Base/Base.js';
+import { type SurfaceType } from '../../../common/props/surface/surface.props.js';
+import { type ModalCloseReasonType, type ModalMotionType, type ModalPlacementType, type ModalSizeType } from './Modal.props.js';
+/**
+ * Accessible modal dialog built on the native `<dialog>` element and
+ * `showModal()`, so the top layer, background inertness, and focus containment
+ * come from the platform rather than a hand-rolled focus trap.
+ *
+ * All copy is supplied by the consumer through slots — `heading`, `description`,
+ * the default content slot, `footer`, and an optional `close` control whose
+ * activation is picked up automatically.
+ *
+ * @fires dsgn-modal-open - Fired after the dialog enters the top layer.
+ * @fires dsgn-modal-request-close - Fired before closing; cancelable, `detail` is `{ reason }`. Call `preventDefault()` to keep the modal open.
+ * @fires dsgn-modal-close - Fired once the exit animation has finished and the dialog has left the top layer; `detail` is `{ reason, returnValue }`.
+ *
+ * @slot - Modal body content.
+ * @slot heading - Title content; supplies the dialog's accessible name.
+ * @slot description - Supporting text referenced by `aria-describedby`.
+ * @slot footer - Actions, typically buttons.
+ * @slot close - A close control; clicking anything slotted here requests a close.
+ *
+ * @csspart dialog - Native dialog element.
+ * @csspart close-button - Built-in close button.
+ */
+export declare class Modal extends Base {
+    static styles: CSSResultGroup;
+    private _dialog;
+    surface: SurfaceType;
+    /**
+     * Whether the modal is shown. This is the single source of truth: the
+     * component drives `showModal()`/`close()` from it, and sets it back to
+     * `false` itself whenever the dialog closes (Escape, backdrop, close control).
+     * A consumer holding `open` in its own state should therefore listen for
+     * `dsgn-modal-close` and mirror the change back, otherwise the two will drift
+     * on the next open.
+     */
+    open: boolean;
+    placement: ModalPlacementType;
+    /** Motion origin. `inherit` follows `placement`; `none` is fade-only. */
+    motion: ModalMotionType;
+    size: ModalSizeType;
+    /**
+     * Accessible name for the dialog, for the case where there is no visible
+     * heading. A filled `heading` slot takes precedence.
+     */
+    ariaLabel: string;
+    /**
+     * Accessible name for the built-in close control. Supplied by the CMS via the
+     * consuming template; the default is a Storybook/dev fallback only. Ignored
+     * when the consumer slots their own control into `close`.
+     */
+    closeLabel: string;
+    /**
+     * Drops the built-in close control. Every modal gets one by default so there
+     * is always a visible way out; opt out only when the flow supplies its own
+     * dismissal (a footer "Cancel", say) — and never together with
+     * `no-escape-dismiss`, which would leave keyboard users stuck.
+     *
+     * A control slotted into `close` replaces the built-in one whatever this is
+     * set to, since it is the slot's fallback content.
+     */
+    noCloseControl: boolean;
+    /** Blocks dismissal by clicking the backdrop. */
+    noBackdropDismiss: boolean;
+    /**
+     * Blocks dismissal by Escape. Reserve it for flows that would lose data —
+     * always leave a visible way out (a close control or a footer action), or
+     * keyboard users are stuck.
+     */
+    noEscapeDismiss: boolean;
+    /** Drives `data-state`, which the stylesheet keys the exit animation on. */
+    private _closing;
+    private _hasHeading;
+    private _hasDescription;
+    private _hasFooter;
+    private _hasCloseControl;
+    private _closeReason;
+    private _returnValue;
+    private _previouslyFocused;
+    private _pointerDownOnBackdrop;
+    private _holdsScrollLock;
+    /**
+     * Whether the header will show a close control — either one the consumer
+     * slotted, or the built-in default that has not been opted out of.
+     */
+    private get _hasCloseAffordance();
+    /** The resolved animation origin, with `inherit` folded into `placement`. */
+    private get _motionOrigin();
+    /** Show the modal. No-op if it is already open. */
+    show(): void;
+    /**
+     * Close the modal immediately, without firing the cancelable
+     * `dsgn-modal-request-close` — this is the imperative "I have decided" path.
+     * The optional `returnValue` lands on the native dialog and on the
+     * `dsgn-modal-close` detail.
+     */
+    close(returnValue?: string): void;
+    /**
+     * Ask to close. Fires the cancelable `dsgn-modal-request-close`; the modal
+     * stays open if a listener calls `preventDefault()`. This is the path Escape,
+     * the backdrop, and the slotted close control take, so a consumer can guard
+     * all of them (e.g. "discard unsaved changes?") in one listener.
+     */
+    requestClose(reason?: ModalCloseReasonType): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changedProperties: Map<string | number | symbol, unknown>): void;
+    private _syncDialogState;
+    private _openDialog;
+    /**
+     * Play the exit animation, then leave the top layer. The dialog stays in the
+     * top layer for the whole animation because `dialog.close()` is what removes
+     * it, and that is deliberately the last step — no timers involved, the wait is
+     * on the animations' own `finished` promises.
+     */
+    private _runCloseSequence;
+    /**
+     * Deliberate initial focus: an author-marked `[autofocus]` (light DOM first,
+     * since that is where the modal's content lives), otherwise the dialog itself.
+     * The native autofocus algorithm is not relied on — it is inconsistent for
+     * content that reaches the dialog through a slot.
+     */
+    private _focusInitialElement;
+    private _restoreFocus;
+    private _acquireScrollLock;
+    private _releaseScrollLock;
+    /**
+     * The native `close` event is the single point where "the dialog is now
+     * shut" is handled, so a consumer calling `close()` on the inner dialog
+     * directly still gets the scroll unlock, focus restore, and public event.
+     */
+    private _handleNativeClose;
+    /**
+     * Escape (and any other platform close request) is always prevented, because
+     * the default behavior would yank the dialog out of the top layer before the
+     * exit animation could run. The dismissal is then re-issued through
+     * `requestClose()` so it is cancelable and animated like every other path.
+     */
+    private _handleCancel;
+    /**
+     * Clicks on the backdrop are reported with the dialog itself as the target
+     * (the panel is the dialog's only child and covers it). Requiring the press
+     * *and* the release to land there stops a text selection that started inside
+     * the modal and ended on the backdrop from dismissing it.
+     */
+    private _handlePointerDown;
+    private _handleDialogClick;
+    private _handleCloseControlClick;
+    /**
+     * Empty regions collapse rather than leaving stray padding, and an empty
+     * `heading`/`description` must not be referenced by `aria-labelledby` /
+     * `aria-describedby` — a dangling reference produces no accessible name at
+     * all, which is worse than falling back to `aria-label`.
+     */
+    private _handleSlotChange;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dsgn-modal': Modal;
+    }
+}