@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/overlay/dialogs.d.ts

@@ -0,0 +1,213 @@
+import { TNode, Value, Renderable } from '@tempots/dom';
+import { ThemeColorName } from '../../tokens';
+/**
+ * Configuration options for the {@link ConfirmationDialog} component.
+ */
+export interface ConfirmationDialogOptions {
+    /**
+     * Dialog title displayed next to the icon.
+     */
+    title: Value<string>;
+    /**
+     * Descriptive body text explaining what the action does.
+     */
+    body: Value<string>;
+    /**
+     * Iconify icon identifier displayed in a colored circle.
+     * @default 'lucide:alert-triangle'
+     */
+    icon?: Value<string>;
+    /**
+     * Semantic color applied to the icon background and confirm button.
+     * @default 'danger'
+     */
+    color?: Value<ThemeColorName>;
+    /**
+     * Optional list of consequences displayed as bullet points.
+     */
+    consequences?: string[];
+    /**
+     * Custom label for the confirm button. Falls back to i18n `confirm` string.
+     */
+    confirmText?: Value<string>;
+    /**
+     * Custom label for the cancel button. Falls back to i18n `cancel` string.
+     */
+    cancelText?: Value<string>;
+    /**
+     * Callback invoked when the user clicks the confirm button.
+     */
+    onConfirm?: () => void;
+    /**
+     * Callback invoked when the user clicks the cancel button or dismisses the dialog.
+     */
+    onCancel?: () => void;
+    /**
+     * Whether the dialog can be closed by clicking outside or pressing Escape.
+     * @default true
+     */
+    dismissable?: Value<boolean>;
+}
+/**
+ * A confirmation dialog for destructive or warning actions.
+ *
+ * Displays a title with an icon, a descriptive body, optional consequence list,
+ * and confirm/cancel action buttons. Built on top of {@link Modal}.
+ *
+ * @param options - Configuration options for the dialog content and callbacks
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * ConfirmationDialog(
+ *   {
+ *     title: 'Delete collection',
+ *     body: 'This will permanently remove all 24 records.',
+ *     icon: 'lucide:trash-2',
+ *     color: 'danger',
+ *     consequences: [
+ *       'All records will be moved to trash',
+ *       'Shared access will be revoked',
+ *     ],
+ *     confirmText: 'Delete collection',
+ *     cancelText: 'Keep collection',
+ *     onConfirm: () => deleteCollection(),
+ *   },
+ *   (open, close) => Button({ onClick: open }, 'Delete')
+ * )
+ * ```
+ */
+export declare function ConfirmationDialog(options: ConfirmationDialogOptions, fn: (open: () => void, close: () => void) => TNode): Renderable;
+/**
+ * Visual variant for the {@link AlertDialog}, controlling the default icon and color.
+ */
+export type AlertDialogVariant = 'info' | 'success' | 'warning' | 'error';
+/**
+ * Configuration options for the {@link AlertDialog} component.
+ */
+export interface AlertDialogOptions {
+    /**
+     * Dialog title displayed next to the icon.
+     */
+    title: Value<string>;
+    /**
+     * Body content of the alert.
+     */
+    body: TNode;
+    /**
+     * Visual variant controlling the default icon and color.
+     * @default 'info'
+     */
+    variant?: AlertDialogVariant;
+    /**
+     * Override icon. If not provided, a default icon is used based on the variant.
+     */
+    icon?: Value<string>;
+    /**
+     * Custom label for the OK button.
+     * @default 'OK'
+     */
+    okText?: Value<string>;
+    /**
+     * Callback invoked when the user acknowledges the alert.
+     */
+    onOk?: () => void;
+    /**
+     * Whether the dialog can be closed by clicking outside or pressing Escape.
+     * @default true
+     */
+    dismissable?: Value<boolean>;
+}
+/**
+ * An alert dialog for displaying important messages to the user.
+ *
+ * Supports info, success, warning, and error variants with appropriate icons and colors.
+ * Has a single acknowledge button. Built on top of {@link Modal}.
+ *
+ * @param options - Configuration options for the alert content
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * AlertDialog(
+ *   {
+ *     title: 'Changes saved',
+ *     body: html.p('Your settings have been updated successfully.'),
+ *     variant: 'success',
+ *   },
+ *   (open, close) => Button({ onClick: open }, 'Save')
+ * )
+ * ```
+ */
+export declare function AlertDialog(options: AlertDialogOptions, fn: (open: () => void, close: () => void) => TNode): Renderable;
+/**
+ * Configuration options for the {@link PromptDialog} component.
+ */
+export interface PromptDialogOptions {
+    /**
+     * Dialog title displayed in the header.
+     */
+    title: Value<string>;
+    /**
+     * Optional descriptive text above the input field.
+     */
+    body?: TNode;
+    /**
+     * Placeholder text for the input field.
+     */
+    placeholder?: Value<string>;
+    /**
+     * Default value pre-filled in the input field.
+     * @default ''
+     */
+    defaultValue?: string;
+    /**
+     * Custom label for the confirm button. Falls back to i18n `confirm` string.
+     */
+    confirmText?: Value<string>;
+    /**
+     * Custom label for the cancel button. Falls back to i18n `cancel` string.
+     */
+    cancelText?: Value<string>;
+    /**
+     * Callback invoked with the input value when the user confirms.
+     */
+    onConfirm?: (value: string) => void;
+    /**
+     * Callback invoked when the user cancels or dismisses the dialog.
+     */
+    onCancel?: () => void;
+    /**
+     * Whether the dialog can be closed by clicking outside or pressing Escape.
+     * @default true
+     */
+    dismissable?: Value<boolean>;
+}
+/**
+ * A prompt dialog for collecting text input from the user.
+ *
+ * Displays a title, optional description, a text input field, and confirm/cancel buttons.
+ * Built on top of {@link Modal}.
+ *
+ * @param options - Configuration options for the prompt
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * PromptDialog(
+ *   {
+ *     title: 'Rename file',
+ *     body: html.p('Enter a new name for this file.'),
+ *     placeholder: 'File name',
+ *     defaultValue: 'untitled.txt',
+ *     confirmText: 'Rename',
+ *     onConfirm: (name) => renameFile(name),
+ *   },
+ *   (open, close) => Button({ onClick: open }, 'Rename')
+ * )
+ * ```
+ */
+export declare function PromptDialog(options: PromptDialogOptions, fn: (open: () => void, close: () => void) => TNode): Renderable;

package/dist/types/components/overlay/drawer.d.ts

@@ -1,29 +1,93 @@
 import { TNode, Renderable, Value } from '@tempots/dom';
 import { OverlayEffect } from '../theme/types';
+/**
+ * Configuration options for the {@link Drawer} component, defining its content layout
+ * and behavioral properties.
+ */
 export interface DrawerOptions {
-    /** Size of the drawer */
+    /**
+     * Size preset controlling the width (for left/right drawers) or height (for top/bottom drawers).
+     * @default 'md'
+     */
     size?: Value<'sm' | 'md' | 'lg' | 'xl'>;
-    /** Side of the viewport/element to anchor the drawer to */
+    /**
+     * Side of the viewport or container element to anchor the drawer to.
+     * Logical values `'inline-start'` and `'inline-end'` respect the document's writing direction.
+     * @default 'right'
+     */
     side?: Value<'top' | 'right' | 'bottom' | 'left' | 'inline-start' | 'inline-end'>;
-    /** Whether the drawer can be closed by clicking outside or pressing escape */
+    /**
+     * Whether the drawer can be closed by clicking outside or pressing the Escape key.
+     * When `false`, the overlay enters non-capturing mode and ignores dismiss gestures.
+     * @default true
+     */
     dismissable?: Value<boolean>;
-    /** Whether to show the close button in header (only applies if header is provided) */
+    /**
+     * Whether to show the close button in the drawer header.
+     * Only rendered when header content is provided.
+     * @default true
+     */
     showCloseButton?: Value<boolean>;
-    /** Callback when drawer is closed */
+    /**
+     * Callback invoked when the drawer is closed via dismiss gestures (click outside or Escape).
+     */
     onClose?: () => void;
-    /** Overlay effect */
+    /**
+     * Visual effect applied to the overlay backdrop behind the drawer.
+     * @default 'opaque'
+     */
     overlayEffect?: Value<OverlayEffect>;
-    /** Container for the overlay: 'body' (default) or 'element' (current element) */
+    /**
+     * Where to attach the overlay in the DOM.
+     * - `'body'` - Renders via a portal to the document body.
+     * - `'element'` - Renders as a child of the current element context.
+     * @default 'body'
+     */
     container?: 'body' | 'element';
-    /** Header content for the drawer */
+    /**
+     * Optional header content displayed at the top of the drawer panel.
+     * When provided alongside `showCloseButton`, a close button is rendered in the header.
+     */
     header?: TNode;
-    /** Body content for the drawer */
+    /**
+     * Main body content of the drawer. Rendered inside a scrollable panel.
+     */
     body: TNode;
-    /** Footer content for the drawer */
+    /**
+     * Optional footer content, typically used for action buttons at the bottom of the drawer.
+     */
     footer?: TNode;
 }
 /**
- * Drawer component that provides a slide-out panel anchored to any side
- * Built on top of the overlay component
+ * Slide-out panel component that anchors to any side of the viewport or container.
+ *
+ * Built on top of {@link Overlay}, the Drawer provides animated open/close transitions,
+ * focus trapping, keyboard and click-outside dismissal, and proper ARIA attributes
+ * (`role="dialog"`, `aria-modal`). The body content is rendered inside a
+ * {@link ScrollablePanel} for built-in scrolling behavior.
+ *
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ *   Call `open(options)` with a {@link DrawerOptions} object to display the drawer.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Drawer((open, close) =>
+ *   Button(
+ *     { onClick: () => open({
+ *       side: 'right',
+ *       size: 'md',
+ *       header: html.h3('Settings'),
+ *       body: html.div(
+ *         html.p('Drawer body content here'),
+ *         FormField({ label: 'Name' }, TextInput({ value: prop('') }))
+ *       ),
+ *       footer: Button({ variant: 'filled', onClick: close }, 'Save'),
+ *       onClose: () => console.log('Drawer closed'),
+ *     })},
+ *     'Open Drawer'
+ *   )
+ * )
+ * ```
  */
 export declare function Drawer(fn: (open: (options: DrawerOptions) => void, close: () => void) => TNode): Renderable;

package/dist/types/components/overlay/index.d.ts

@@ -2,6 +2,10 @@ export * from './overlay';
 export * from './modal';
 export * from './drawer';
 export * from './tooltip';
+export * from './popover';
 export * from './ribbon';
 export * from './lightbox';
 export * from './announcement-bar';
+export * from './command-palette';
+export * from './block-command-palette';
+export * from './dialogs';

package/dist/types/components/overlay/lightbox.d.ts

@@ -1,22 +1,65 @@
 import { Renderable, Value, TNode } from '@tempots/dom';
 import { OverlayEffect } from '../theme';
+/**
+ * Configuration options for the {@link Lightbox} component.
+ */
 export interface LightboxOptions {
-    /** Whether clicking outside/Escape closes the lightbox (default: true) */
+    /**
+     * Whether the lightbox can be closed by clicking outside or pressing the Escape key.
+     * When `false`, the overlay ignores dismiss gestures.
+     * @default true
+     */
     dismissable?: Value<boolean>;
-    /** Whether to show the close button in the top-end corner (default: true) */
+    /**
+     * Whether to show a close button in the top-end corner of the lightbox.
+     * @default true
+     */
     showCloseButton?: Value<boolean>;
-    /** Overlay effect (default: 'opaque') */
+    /**
+     * Visual effect applied to the overlay backdrop behind the lightbox.
+     * @default 'opaque'
+     */
     overlayEffect?: Value<OverlayEffect>;
-    /** Container for the overlay: 'body' (default) or 'element' */
+    /**
+     * Where to attach the overlay in the DOM.
+     * - `'body'` - Renders via a portal to the document body.
+     * - `'element'` - Renders as a child of the current element context.
+     * @default 'body'
+     */
     container?: 'body' | 'element';
-    /** Padding (in px) kept around content; content is capped by viewport minus padding (default: 32) */
+    /**
+     * Padding in pixels kept around the content. The content is constrained to the
+     * viewport dimensions minus this padding on each side.
+     * @default 32
+     */
     padding?: Value<number>;
 }
 /**
- * Lightbox overlay for displaying arbitrary content maximized and centered.
- * - Attaches via Portal to body by default
- * - Dark background via Overlay effect
- * - Fades in/out using the overlay's animated toggle
- * - Caps content to viewport (minus padding) and clips overflow; no transform scaling
+ * Lightbox overlay for displaying arbitrary content maximized and centered over a dark backdrop.
+ *
+ * The lightbox attaches via a portal to the document body by default, fades in/out using
+ * the overlay's animated toggle, and constrains content to the viewport dimensions minus
+ * configurable padding. Overflow is clipped without transform scaling.
+ *
+ * Built on top of {@link Overlay}.
+ *
+ * @param options - Configuration options controlling dismissability, close button, overlay effect, and padding
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ *   Call `open(content)` with a `TNode` to display the lightbox content.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Lightbox(
+ *   { dismissable: true, padding: 48 },
+ *   (open, close) => html.img(
+ *     attr.src('/thumb.jpg'),
+ *     attr.alt('Thumbnail'),
+ *     on.click(() => open(
+ *       html.img(attr.src('/full-size.jpg'), attr.alt('Full size image'))
+ *     ))
+ *   )
+ * )
+ * ```
  */
 export declare function Lightbox(options: LightboxOptions, fn: (open: (content: TNode) => void, close: () => void) => TNode): Renderable;

package/dist/types/components/overlay/modal.d.ts

@@ -1,40 +1,140 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
 import { OverlayEffect } from '../theme';
+/**
+ * Configuration options for the {@link Modal} component.
+ */
 export interface ModalOptions {
-    /** Size of the modal */
+    /**
+     * Size preset controlling the maximum width of the modal dialog.
+     * @default 'md'
+     */
     size?: Value<'sm' | 'md' | 'lg' | 'xl'>;
-    /** Whether the modal can be closed by clicking outside or pressing escape */
+    /**
+     * Whether the modal can be closed by clicking outside or pressing the Escape key.
+     * When `false`, the overlay enters non-capturing mode and ignores dismiss gestures.
+     * @default true
+     */
     dismissable?: Value<boolean>;
-    /** Whether to show the close button in header (only applies if header is provided) */
+    /**
+     * Whether to show the close button in the modal header.
+     * Only rendered when header content is provided.
+     * @default true
+     */
     showCloseButton?: Value<boolean>;
-    /** Callback when modal is closed */
+    /**
+     * Callback invoked when the modal is closed via dismiss gestures (click outside or Escape).
+     */
     onClose?: () => void;
-    /** Overlay effect */
+    /**
+     * Visual effect applied to the overlay backdrop behind the modal.
+     * @default 'opaque'
+     */
     overlayEffect?: Value<OverlayEffect>;
-    /** Container for the overlay: 'body' (default) or 'element' (current element) */
+    /**
+     * Where to attach the overlay in the DOM.
+     * - `'body'` - Renders via a portal to the document body.
+     * - `'element'` - Renders as a child of the current element context.
+     * @default 'body'
+     */
     container?: 'body' | 'element';
-    /** Position of the modal: 'center' (default), 'top', 'bottom', 'left', 'right', 'top-start', 'top-end', 'bottom-start', 'bottom-end' */
+    /**
+     * Position of the modal dialog within the overlay.
+     * Controls alignment relative to the viewport or container.
+     * @default 'center'
+     */
     position?: Value<'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'>;
 }
+/**
+ * Content layout options for a modal dialog, defining the header, body, and footer sections.
+ */
 export interface ModalContentOptions {
-    /** Optional header content - if provided, overrides title */
+    /**
+     * Optional header content displayed at the top of the modal.
+     * When provided, an ARIA `labelledby` association is created for accessibility.
+     */
     header?: TNode;
-    /** Main body content */
+    /**
+     * Main body content of the modal dialog. This section is always rendered
+     * and is referenced via ARIA `describedby` for screen readers.
+     */
     body: TNode;
-    /** Optional footer content with action items */
+    /**
+     * Optional footer content, typically used for action buttons (e.g., confirm, cancel).
+     */
     footer?: TNode;
 }
 /**
- * Modal component that provides a structured dialog with optional header, body, and footer
- * Built on top of the overlay component
+ * Modal dialog component with structured header, body, and footer sections.
+ *
+ * Built on top of {@link Overlay}, it provides focus trapping, keyboard dismissal,
+ * click-outside dismissal, and proper ARIA attributes (`role="dialog"`, `aria-modal`,
+ * `aria-labelledby`, `aria-describedby`).
+ *
+ * @param options - Configuration options controlling size, position, dismissability, and overlay effect
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ *   Call `open(content)` with a {@link ModalContentOptions} object to display the modal.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * const isOpen = prop(false)
+ *
+ * Modal(
+ *   { size: 'lg', dismissable: true, onClose: () => isOpen.set(false) },
+ *   (open, close) => Button(
+ *     { onClick: () => open({
+ *       header: html.h2('Confirm Action'),
+ *       body: html.p('Are you sure you want to proceed?'),
+ *       footer: Fragment(
+ *         Button({ variant: 'outline', onClick: close }, 'Cancel'),
+ *         Button({ color: 'primary', variant: 'filled', onClick: close }, 'OK')
+ *       ),
+ *     })},
+ *     'Open Modal'
+ *   )
+ * )
+ * ```
  */
 export declare function Modal(options: ModalOptions, fn: (open: (content: ModalContentOptions) => void, close: () => void) => TNode): Renderable;
 /**
- * Convenience function to create a confirmation modal
+ * Convenience wrapper around {@link Modal} that provides a pre-built confirmation dialog
+ * with configurable confirm and cancel buttons.
+ *
+ * The modal automatically includes localized button labels (via {@link BeatUII18n}) and
+ * hides the header close button by default.
+ *
+ * @param options - Combined {@link ModalOptions} plus confirmation-specific settings:
+ * @param options.confirmText - Custom label for the confirm button. Falls back to the i18n `confirm` string.
+ * @param options.cancelText - Custom label for the cancel button. Falls back to the i18n `cancel` string.
+ * @param options.onConfirm - Callback invoked when the user clicks the confirm button.
+ * @param options.onCancel - Callback invoked when the user clicks the cancel button.
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ *   Call `open(message)` with a `TNode` to display the confirmation message.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * ConfirmModal(
+ *   {
+ *     onConfirm: () => console.log('Confirmed'),
+ *     onCancel: () => console.log('Cancelled'),
+ *     confirmText: 'Delete',
+ *     cancelText: 'Keep',
+ *   },
+ *   (open, close) => Button(
+ *     { onClick: () => open(html.p('Delete this item permanently?')) },
+ *     'Delete Item'
+ *   )
+ * )
+ * ```
  */
 export declare function ConfirmModal(options: ModalOptions & {
+    /** Custom label for the confirm button. Falls back to the i18n `confirm` string. */
     confirmText?: Value<string>;
+    /** Custom label for the cancel button. Falls back to the i18n `cancel` string. */
     cancelText?: Value<string>;
+    /** Callback invoked when the user clicks the confirm button. */
     onConfirm?: () => void;
+    /** Callback invoked when the user clicks the cancel button. */
     onCancel?: () => void;
 }, fn: (open: (message: TNode) => void, close: () => void) => TNode): Renderable;

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

@@ -1,11 +1,72 @@
 import { TNode, Value } from '@tempots/dom';
 import { OverlayEffect } from '../theme/types';
+/**
+ * Configuration options for the Overlay component.
+ */
 export type OverlayOptions = {
+    /**
+     * Visual effect applied to the overlay backdrop.
+     * @default 'opaque'
+     */
     effect?: Value<OverlayEffect>;
+    /**
+     * Interaction mode for the overlay.
+     * - `'capturing'` - Listens for Escape key presses and click-outside events to close the overlay.
+     * - `'non-capturing'` - Does not register any close event listeners, making the overlay non-dismissable via user interaction.
+     * @default 'capturing'
+     */
     mode?: Value<'capturing' | 'non-capturing'>;
+    /**
+     * Callback invoked when the user clicks outside the overlay content area.
+     * Only fires when `mode` is `'capturing'`.
+     */
     onClickOutside?: () => void;
+    /**
+     * Callback invoked when the user presses the Escape key.
+     * Only fires when `mode` is `'capturing'`.
+     */
     onEscape?: () => void;
+    /**
+     * Content to render inside the overlay.
+     */
     content?: TNode;
+    /**
+     * Where to attach the overlay in the DOM.
+     * - `'body'` - Renders via a portal to the document body.
+     * - `'element'` - Renders as a child of the current element context.
+     * @default 'body'
+     */
     container?: 'body' | 'element';
 };
+/**
+ * Low-level overlay primitive that manages a full-screen backdrop with animated open/close transitions.
+ *
+ * The overlay handles event delegation (Escape key, click-outside), inerts sibling elements
+ * for accessibility, and supports portal rendering to the document body.
+ *
+ * Higher-level components such as {@link Modal}, {@link Drawer}, and {@link Lightbox} are built
+ * on top of this primitive.
+ *
+ * @param fn - A render function that receives `open` and `close` callbacks and returns the trigger content.
+ *   Call `open(options)` to display the overlay and `close()` to dismiss it.
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Overlay((open, close) => {
+ *   return Button(
+ *     { onClick: () => open({
+ *       effect: 'opaque',
+ *       content: html.div(
+ *         html.p('Overlay content'),
+ *         Button({ onClick: close }, 'Close')
+ *       ),
+ *       onEscape: close,
+ *       onClickOutside: close,
+ *     })},
+ *     'Open Overlay'
+ *   )
+ * })
+ * ```
+ */
 export declare function Overlay(fn: (open: (options: OverlayOptions) => void, close: () => void) => TNode): import("@tempots/dom").Renderable;