material 1.0.4 → 3.0.0-next.1

package/dist/components/dialog/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dialog Component Module
+ *
+ * A Material Design 3 dialog implementation with support for multiple sizes,
+ * animations, content types, and interactive features like confirmation.
+ *
+ * Dialogs inform users about critical information, require decisions,
+ * or involve multiple tasks.
+ *
+ * @module components/dialog
+ * @category Components
+ */
+export { default, default as createDialog } from "./dialog.js";
+export type { DialogConfig, DialogComponent, DialogButton, DialogEvent, DialogConfirmOptions, DialogSize, DialogAnimation, DialogFooterAlignment, DialogEventType, } from "./types.js";

package/dist/components/dialog/index.js

@@ -0,0 +1 @@
+export { default, default as createDialog } from "./dialog.js";

package/dist/components/dialog/types.d.ts

@@ -0,0 +1,627 @@
+import type { ButtonComponent } from "../button/types.js";
+import type { DividerComponent } from "../divider/types.js";
+import type { EventCallback } from "../../core/state/emitter.js";
+/**
+ * Dialog size types - determines the width and height of the dialog
+ *
+ * @category Components
+ * @remarks
+ * - small: 320px width, for simple messages or choices
+ * - medium: 560px width, for standard forms or content (default)
+ * - large: 800px width, for complex forms or rich content
+ * - fullwidth: Spans the full width of the viewport with margins
+ * - fullscreen: Takes up the entire viewport (similar to a new page)
+ */
+export type DialogSize = 'small' | 'medium' | 'large' | 'fullwidth' | 'fullscreen';
+/**
+ * Dialog animation types - controls how the dialog appears and disappears
+ *
+ * @category Components
+ * @remarks
+ * - scale: Scale up/down animation from center (default)
+ * - slide-up: Slide in from bottom, slide out to bottom
+ * - slide-down: Slide in from top, slide out to top
+ * - fade: Simple fade in/out animation
+ */
+export type DialogAnimation = 'scale' | 'slide-up' | 'slide-down' | 'fade';
+/**
+ * Dialog footer alignment types - controls how buttons in the footer are aligned
+ *
+ * @category Components
+ * @remarks
+ * - right: Align buttons to the right (default, follows Material Design guidelines)
+ * - left: Align buttons to the left
+ * - center: Center buttons in footer
+ * - space-between: Space buttons evenly, with first button at left, last at right
+ */
+export type DialogFooterAlignment = 'right' | 'left' | 'center' | 'space-between';
+/**
+ * Dialog event types - events that can be listened to with the on() method
+ *
+ * @category Components
+ * @remarks
+ * - beforeopen: Fired inside `open()`, before anything changes (can be prevented)
+ * - open: Fired inside `open()`, once the dialog is open: `isOpen()` is true.
+ *   The surface may not be visible yet, and focus may not be in it
+ * - afteropen: Fired later, never inside `open()`: the dialog is visible and
+ *   focus is in it (`animationDuration` after it was shown). Not fired when
+ *   the dialog closes first
+ * - beforeclose: Fired inside `close()`, before anything changes (can be prevented).
+ *   Not fired when the browser has closed a top-layer dialog itself: nothing
+ *   can refuse that
+ * - close: Fired inside `close()`, once the dialog is closed: `isOpen()` is false
+ * - afterclose: Fired later, never inside `close()`: the dialog is removed
+ *   (`animationDuration` after it closed). Not fired when the dialog opens
+ *   again first
+ *
+ * A listener hears the events emitted after it was added: add an `open`
+ * listener before calling `open()`, or listen to `afteropen`.
+ */
+export type DialogEventType = 'open' | 'close' | 'beforeopen' | 'beforeclose' | 'afteropen' | 'afterclose';
+/**
+ * Configuration interface for the Dialog component
+ *
+ * @category Components
+ * @description
+ * Defines the appearance and behavior of a dialog component.
+ * All properties are optional with sensible defaults.
+ */
+export interface DialogConfig {
+    /**
+     * Dialog title text - appears in the header
+     * @example "Settings"
+     */
+    title?: string;
+    /**
+     * Dialog subtitle text - appears below title in smaller text
+     * @example "Configure your preferences"
+     */
+    subtitle?: string;
+    /**
+     * Dialog content (text or HTML)
+     * Can include rich content like forms, images, etc.
+     * @example "This action cannot be undone."
+     */
+    content?: string;
+    /**
+     * Whether to show a close affordance in the header. A basic dialog has
+     * none in M3: it is dismissed by its actions. A full-screen dialog shows
+     * one unless this is set to false.
+     * @default false (true for the fullscreen size)
+     */
+    closeButton?: boolean;
+    /**
+     * Accessible name for a dialog without a headline
+     */
+    ariaLabel?: string;
+    /**
+     * ARIA role for the dialog. A basic dialog is an `alertdialog` and a
+     * full-screen one a `dialog`; set this to override.
+     */
+    role?: 'alertdialog' | 'dialog';
+    /**
+     * Additional CSS classes to apply to the dialog
+     * @example "settings-dialog important-dialog"
+     */
+    class?: string;
+    /**
+     * Dialog size variant
+     * Controls the width and height of the dialog
+     * @default "medium"
+     */
+    size?: DialogSize | string;
+    /**
+     * Dialog animation variant
+     * Controls how the dialog appears and disappears
+     * @default "scale"
+     */
+    animation?: DialogAnimation | string;
+    /**
+     * Footer buttons alignment
+     * Controls how buttons in the footer are positioned
+     * @default "right"
+     */
+    footerAlignment?: DialogFooterAlignment | string;
+    /**
+     * Whether dialog is initially open
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Whether to close when clicking overlay background
+     * When true, allows users to dismiss by clicking outside
+     * @default true
+     */
+    closeOnOverlayClick?: boolean;
+    /**
+     * Whether to close when Escape key is pressed
+     *
+     * Escape is handled as a key press, in both layers, by the topmost open
+     * dialog only, and after whatever is open inside it (a menu, a select) has
+     * had the key. `false`, or a `beforeclose` listener that refuses, holds
+     * for any number of presses.
+     *
+     * The remaining limit, with `layer: "top"`: a close request that is not a
+     * key press (a back gesture) reaches the dialog as the browser's `cancel`,
+     * which a page may refuse twice in a row. The browser closes the dialog
+     * itself on the third: the dialog then closes with `close`, and
+     * `beforeclose` is not asked.
+     * @default true
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Whether dialog should be modal
+     * When true, prevents interaction with background content
+     * @default true
+     */
+    modal?: boolean;
+    /**
+     * Whether to focus the first focusable element when opened
+     * Important for accessibility and keyboard navigation
+     * @default true
+     */
+    autofocus?: boolean;
+    /**
+     * Whether to trap focus within dialog when opened
+     * Prevents tabbing outside the dialog, improving accessibility
+     * @default true
+     */
+    trapFocus?: boolean;
+    /**
+     * Parent element to append dialog to
+     * @default document.body
+     */
+    container?: HTMLElement;
+    /**
+     * `"top"` makes the dialog itself a `<dialog>` element, rendered in place in
+     * `container` (or `document.body`) and kept there when it closes, and opens
+     * it with `showModal()`: in the browser's top layer, above every z-index and
+     * outside any clipping ancestor, with the rest of the page inert. The scrim
+     * is its `::backdrop`, and the overlay element is not used. Escape reaches
+     * the dialog as its `cancel` event.
+     *
+     * Where the browser has no `showModal()`, the dialog behaves as without it.
+     */
+    layer?: "top";
+    /**
+     * Footer buttons configuration
+     * Array of button objects to display in the footer
+     */
+    buttons?: DialogButton[];
+    /**
+     * Whether to show a divider between header and content
+     * @default false
+     */
+    divider?: boolean;
+    /**
+     * Dialog z-index - controls stacking order
+     * @default 1000
+     */
+    zIndex?: number;
+    /**
+     * How long `afteropen` and `afterclose` wait after opening and closing, in
+     * milliseconds, and when a closed dialog leaves the DOM. By default they
+     * follow the stylesheet: 450 after opening, 200 after closing.
+     */
+    animationDuration?: number;
+    /**
+     * Event handlers for dialog events
+     * Register event handlers during initialization
+     * @example
+     * {
+     *   afteropen: (event) => { console.log('Dialog opened'); }
+     * }
+     */
+    on?: {
+        [key in DialogEventType]?: (event: DialogEvent) => void;
+    };
+}
+/**
+ * Dialog button configuration
+ *
+ * Defines the appearance and behavior of buttons in the dialog footer.
+ *
+ * @category Components
+ */
+export interface DialogButton {
+    /**
+     * Button text label
+     * @example "Save" | "Cancel" | "Delete"
+     */
+    text: string;
+    /**
+     * Button variant (uses button component variants)
+     * @default "text"
+     * @example "filled" | "text" | "outlined" | "tonal"
+     */
+    variant?: string;
+    /**
+     * Button size
+     * @default "medium"
+     * @example "small" | "medium" | "large"
+     */
+    size?: string;
+    /**
+     * Button click handler
+     * Return false to prevent dialog closing
+     * @param event - The click event
+     * @param dialog - The dialog component instance
+     * @returns Optional boolean, false prevents dialog from closing
+     */
+    onClick?: (event: MouseEvent, dialog: DialogComponent) => void | boolean;
+    /**
+     * Whether to close the dialog when this button is clicked
+     * Set to false for validation or multi-step flows
+     * @default true
+     */
+    closeDialog?: boolean;
+    /**
+     * Whether to autofocus this button when the dialog opens
+     * Typically used for primary action buttons
+     * @default false
+     */
+    autofocus?: boolean;
+    /**
+     * Additional button attributes to pass to the button element
+     * @example { 'data-id': 'save-button', 'form': 'profile-form' }
+     */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Dialog event object
+ *
+ * Passed to event handlers registered with the on() method.
+ *
+ * @category Components
+ */
+export interface DialogEvent {
+    /**
+     * Dialog component instance that triggered the event
+     */
+    dialog: DialogComponent;
+    /**
+     * Original browser event if applicable
+     * May be undefined for programmatic events
+     */
+    originalEvent?: Event;
+    /**
+     * Call this method to prevent the default action
+     * For example, to prevent a dialog from closing
+     */
+    preventDefault: () => void;
+    /**
+     * Whether the default action was prevented
+     * Will be true if preventDefault() was called
+     */
+    defaultPrevented: boolean;
+}
+/**
+ * Dialog component interface
+ *
+ * Provides methods for controlling a Material Design 3 dialog
+ *
+ * @category Components
+ */
+/**
+ * The elements withStructure builds and hangs off the component.
+ *
+ * @category Components
+ * @internal
+ */
+export interface DialogStructure {
+    /** Always built by withStructure, whatever the config */
+    header: HTMLElement;
+    /** Always built by withStructure, whatever the config */
+    content: HTMLElement;
+    /** Only when the dialog has buttons, and set back to null when the last goes */
+    footer: HTMLElement | null;
+    /** Divider components, not elements: the code reaches for `.element` on them */
+    headerDivider: DividerComponent | null;
+    footerDivider: DividerComponent | null;
+    container: HTMLElement;
+}
+/**
+ * A footer button as the dialog keeps it: the live button component and the
+ * config it was built from. `getButtons()` hands back the configs, which is
+ * why the public type is DialogButton and this one is not.
+ *
+ * @category Components
+ * @internal
+ */
+export interface DialogButtonRecord {
+    instance: ButtonComponent;
+    config: DialogButton;
+}
+/**
+ * What a dialog feature needs from the component it is handed.
+ *
+ * The dialog pipe is createBase, withEvents, withElement, then these -- so the
+ * element and the emitter are both installed before any feature runs.
+ * `structure` and `overlay` come from withStructure, which is the first of
+ * them, so everything after it can count on them; they are optional here
+ * because withStructure itself is handed a component without them.
+ *
+ * @category Components
+ * @internal
+ */
+export interface DialogFeatureComponent {
+    element: HTMLElement;
+    config: DialogConfig & Record<string, unknown>;
+    getClass: (name: string) => string;
+    on: (event: string, handler: EventCallback) => unknown;
+    off: (event: string, handler: EventCallback) => unknown;
+    emit: (event: string, data?: unknown) => unknown;
+    _buttons?: DialogButtonRecord[];
+}
+/**
+ * A dialog that has been through withStructure.
+ *
+ * withStructure is the first feature in the pipe and the only one handed a
+ * component without these, so every feature after it can count on them. Two
+ * host types rather than one with optionals: the optionals would have every
+ * later feature checking for something that is always there.
+ *
+ * @category Components
+ * @internal
+ */
+export interface DialogStructured extends DialogFeatureComponent {
+    overlay: HTMLElement;
+    structure: DialogStructure;
+}
+export interface DialogComponent {
+    /**
+     * The dialog's root DOM element
+     */
+    element: HTMLElement;
+    /**
+     * The dialog's overlay/backdrop element
+     */
+    overlay: HTMLElement;
+    /**
+     * Opens the dialog.
+     *
+     * When it returns, `isOpen()` is true and `open` has been emitted
+     * (`beforeopen` first; a listener that prevents it leaves the dialog closed,
+     * with no `open`). The surface is shown, focus moves in and the animation
+     * runs after that; `afteropen` is emitted once they have, never inside this
+     * call. On an open dialog it does nothing and emits nothing.
+     *
+     * From then on Escape and a click on the scrim close it (`closeOnEscape`,
+     * `closeOnOverlayClick`). The event that opened it never does: a dialog
+     * opened from an Escape `keydown` stays open through that key press, in
+     * both layers. A held key repeats, and its first repeat is a new key press.
+     * @returns Dialog component for method chaining
+     * @example
+     * // An `open` listener must be added before the call to hear it
+     * dialog.on('open', build);
+     * dialog.open();
+     */
+    open: () => DialogComponent;
+    /**
+     * Closes the dialog.
+     *
+     * When it returns, `isOpen()` is false and `close` has been emitted
+     * (`beforeclose` first; a listener that prevents it leaves the dialog open,
+     * with no `close`). The surface animates out and is removed after that;
+     * `afterclose` is emitted once it is, never inside this call. On a closed
+     * dialog it does nothing and emits nothing.
+     *
+     * `close()` then `open()` at once ends open, and `open()` then `close()`
+     * ends closed: the later call wins, and what the earlier one still had to
+     * do (its `afterclose`, or showing the surface and its `afteropen`) is
+     * dropped.
+     * @returns Dialog component for method chaining
+     */
+    close: () => DialogComponent;
+    /**
+     * Toggles dialog open/closed state
+     * @param open - Optional boolean to force specific state
+     * @returns Dialog component for method chaining
+     * @example
+     * dialog.toggle(); // Toggle current state
+     * dialog.toggle(true); // Force open
+     */
+    toggle: (open?: boolean) => DialogComponent;
+    /**
+     * Checks if dialog is currently open. It changes inside `open()` and
+     * `close()`, before their `open` and `close` events, and does not wait for
+     * the animation.
+     * @returns True if dialog is open, false otherwise
+     */
+    isOpen: () => boolean;
+    /**
+     * Sets dialog title text
+     * @param title - New title to display in header
+     * @returns Dialog component for method chaining
+     */
+    setTitle: (title: string) => DialogComponent;
+    /**
+     * Gets dialog current title text
+     * @returns Current title text
+     */
+    getTitle: () => string;
+    /**
+     * Sets dialog subtitle text
+     * @param subtitle - New subtitle to display below title
+     * @returns Dialog component for method chaining
+     */
+    setSubtitle: (subtitle: string) => DialogComponent;
+    /**
+     * Gets dialog current subtitle text
+     * @returns Current subtitle text
+     */
+    getSubtitle: () => string;
+    /**
+     * Sets dialog content
+     * @param content - New content (text or HTML)
+     * @returns Dialog component for method chaining
+     */
+    setContent: (content: string) => DialogComponent;
+    /**
+     * Gets dialog content
+     * @returns Current content text/HTML
+     */
+    getContent: () => string;
+    /**
+     * Adds a button to the dialog footer
+     * @param button - Button configuration object
+     * @returns Dialog component for method chaining
+     */
+    addButton: (button: DialogButton) => DialogComponent;
+    /**
+     * Removes a button by index or text
+     * @param indexOrText - Button index or text content
+     * @returns Dialog component for method chaining
+     * @example
+     * dialog.removeButton(0); // Remove first button
+     * dialog.removeButton('Cancel'); // Remove button with text 'Cancel'
+     */
+    removeButton: (indexOrText: number | string) => DialogComponent;
+    /**
+     * Gets all footer buttons
+     * @returns Array of button configuration objects
+     */
+    getButtons: () => DialogButton[];
+    /**
+     * Sets footer button alignment
+     * @param alignment - Alignment value
+     * @returns Dialog component for method chaining
+     */
+    setFooterAlignment: (alignment: DialogFooterAlignment | string) => DialogComponent;
+    /**
+     * Sets dialog size
+     * @param size - Size variant
+     * @returns Dialog component for method chaining
+     */
+    setSize: (size: DialogSize | string) => DialogComponent;
+    /**
+     * Adds an event listener to the dialog
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Dialog component for method chaining
+     * @example
+     * dialog.on('beforeclose', (event) => {
+     *   // Prevent dialog from closing if form is invalid
+     *   if (!isFormValid()) {
+     *     event.preventDefault();
+     *   }
+     * });
+     */
+    on: (event: DialogEventType | string, handler: (event: DialogEvent) => void) => DialogComponent;
+    /**
+     * Removes an event listener from the dialog
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Dialog component for method chaining
+     */
+    off: (event: DialogEventType | string, handler: (event: DialogEvent) => void) => DialogComponent;
+    /**
+     * Gets dialog header element
+     * @returns Header element or null if not present
+     */
+    getHeaderElement: () => HTMLElement | null;
+    /**
+     * Gets dialog content element
+     * @returns Content element or null if not present
+     */
+    getContentElement: () => HTMLElement | null;
+    /**
+     * Gets dialog footer element
+     * @returns Footer element or null if not present
+     */
+    getFooterElement: () => HTMLElement | null;
+    /**
+     * Shows or hides the divider between header and content
+     * @param show - Whether to show or hide divider
+     * @returns Dialog component for method chaining
+     */
+    toggleDivider: (show: boolean) => DialogComponent;
+    /**
+     * Checks if the dialog has a divider visible
+     * @returns True if divider is visible, false otherwise
+     */
+    hasDivider: () => boolean;
+    /**
+     * Creates a confirmation dialog with Yes/No buttons
+     * Returns a promise that resolves to true if confirmed, false otherwise
+     *
+     * @param options - Confirmation dialog options
+     * @returns Promise resolving to boolean result
+     * @example
+     * const result = await dialog.confirm({
+     *   title: 'Delete Item',
+     *   message: 'Are you sure you want to delete this item?'
+     * });
+     *
+     * if (result) {
+     *   deleteItem();
+     * }
+     */
+    confirm: (options?: DialogConfirmOptions) => Promise<boolean>;
+    /**
+     * Destroys the dialog and removes it from DOM
+     * Cleans up all event listeners and references
+     */
+    destroy: () => void;
+}
+/**
+ * Options for confirmation dialog
+ *
+ * Used with the dialog.confirm() method to create a simple
+ * confirmation dialog with customizable options.
+ *
+ * @category Components
+ */
+export interface DialogConfirmOptions {
+    /**
+     * Confirmation dialog title
+     * @default "Confirm"
+     * @example "Delete Item"
+     */
+    title?: string;
+    /**
+     * Confirmation message/question to display
+     * Required field for the confirmation dialog
+     * @example "Are you sure you want to delete this item?"
+     */
+    message: string;
+    /**
+     * Confirm button text
+     * @default "Yes"
+     * @example "Delete" | "Confirm" | "Yes, I'm sure"
+     */
+    confirmText?: string;
+    /**
+     * Cancel button text
+     * @default "No"
+     * @example "Cancel" | "No, go back"
+     */
+    cancelText?: string;
+    /**
+     * Confirm button variant
+     * @default "filled"
+     * @example "filled" | "tonal"
+     */
+    confirmVariant?: string;
+    /**
+     * Cancel button variant
+     * @default "text"
+     * @example "text" | "outlined"
+     */
+    cancelVariant?: string;
+    /**
+     * Dialog size for the confirmation dialog
+     * @default "small"
+     */
+    size?: DialogSize | string;
+}
+/**
+ * Registers DialogConfig with the global defaults map, so
+ * `setComponentDefaults("dialog", ...)` is typed without core
+ * importing anything from this component. FLO-115.
+ */
+declare module "../../core/config/global" {
+    interface ComponentConfigMap {
+        dialog?: Partial<DialogConfig>;
+    }
+}

package/dist/components/dialog/types.js

@@ -0,0 +1 @@
+export {};