@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/components/navigation/toolbar/toolbar.d.ts

@@ -1,17 +1,142 @@
 import { TNode, Value } from '@tempots/dom';
 import { ButtonOptions } from '../../button/button';
+/**
+ * Configuration options for the {@link Toolbar} component.
+ */
 export interface ToolbarOptions {
+    /**
+     * Accessible label for the toolbar (`aria-label`).
+     * Provides a descriptive label for screen readers.
+     */
     ariaLabel?: Value<string>;
 }
+/**
+ * Horizontal toolbar component with roving tabindex keyboard navigation.
+ *
+ * Renders a `role="toolbar"` container with `aria-orientation="horizontal"`.
+ * Implements the WAI-ARIA toolbar pattern:
+ * - Arrow Left/Right to move focus between focusable children
+ * - Home/End to jump to first/last focusable item
+ * - Roving tabindex ensures only one item is tabbable at a time
+ *
+ * @param children - Toolbar items, typically {@link ToolbarButton}, {@link ToolbarGroup},
+ *   {@link ToolbarDivider}, and {@link ToolbarSpacer} components
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Toolbar(
+ *   ToolbarGroup(
+ *     ToolbarButton({ onClick: () => bold() }, Icon({ icon: 'bold' })),
+ *     ToolbarButton({ onClick: () => italic() }, Icon({ icon: 'italic' })),
+ *   ),
+ *   ToolbarDivider(),
+ *   ToolbarGroup(
+ *     ToolbarButton({ onClick: () => alignLeft() }, Icon({ icon: 'align-left' })),
+ *     ToolbarButton({ onClick: () => alignCenter() }, Icon({ icon: 'align-center' })),
+ *   ),
+ *   ToolbarSpacer(),
+ *   ToolbarButton({ onClick: () => save() }, 'Save'),
+ * )
+ * ```
+ */
 export declare function Toolbar(...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Configuration options for the {@link ToolbarButton} component.
+ * Extends {@link ButtonOptions} with toolbar-specific properties.
+ */
 export interface ToolbarButtonOptions extends ButtonOptions {
+    /**
+     * Whether the button displays only an icon without text.
+     * When `true`, ensure `ariaLabel` is provided for accessibility.
+     */
     iconOnly?: Value<boolean>;
+    /**
+     * Accessible label for the button (`aria-label`).
+     * Required when `iconOnly` is `true` to provide a text alternative.
+     */
     ariaLabel?: Value<string>;
 }
+/**
+ * Button component pre-configured for use inside a {@link Toolbar}.
+ *
+ * Applies default toolbar styling (neutral color, light variant, medium roundedness)
+ * that can be overridden via the options object.
+ *
+ * @param options - Button configuration options. Defaults are overridden with toolbar-appropriate values.
+ * @param children - Child content for the button (text, icons, or both)
+ * @returns A renderable button node
+ *
+ * @example
+ * ```typescript
+ * ToolbarButton(
+ *   { onClick: () => toggleBold() },
+ *   Icon({ icon: 'bold', size: 'sm' })
+ * )
+ * ```
+ */
 export declare function ToolbarButton(options: ButtonOptions, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Configuration options for the {@link ToolbarGroup} component.
+ */
 export interface ToolbarGroupOptions {
+    /**
+     * Accessible label for the toolbar group (`aria-label`).
+     * Provides a descriptive label for screen readers.
+     */
     ariaLabel?: Value<string>;
 }
+/**
+ * Groups related toolbar items together within a {@link Toolbar}.
+ *
+ * Renders a `role="group"` container that visually and semantically groups
+ * related buttons or controls.
+ *
+ * @param children - Toolbar items to group (e.g., {@link ToolbarButton} components)
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * ToolbarGroup(
+ *   ToolbarButton({ onClick: () => bold() }, Icon({ icon: 'bold' })),
+ *   ToolbarButton({ onClick: () => italic() }, Icon({ icon: 'italic' })),
+ *   ToolbarButton({ onClick: () => underline() }, Icon({ icon: 'underline' })),
+ * )
+ * ```
+ */
 export declare function ToolbarGroup(...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Visual divider for separating groups of items within a {@link Toolbar}.
+ *
+ * Renders a `role="separator"` element with vertical orientation.
+ *
+ * @returns A renderable divider node
+ *
+ * @example
+ * ```typescript
+ * Toolbar(
+ *   ToolbarGroup(boldBtn, italicBtn),
+ *   ToolbarDivider(),
+ *   ToolbarGroup(alignLeftBtn, alignCenterBtn),
+ * )
+ * ```
+ */
 export declare function ToolbarDivider(): import("@tempots/dom").Renderable;
+/**
+ * Flexible spacer that pushes toolbar items apart within a {@link Toolbar}.
+ *
+ * Uses CSS flex to fill available space, creating a gap between the items
+ * before and after it.
+ *
+ * @returns A renderable spacer node
+ *
+ * @example
+ * ```typescript
+ * Toolbar(
+ *   ToolbarGroup(editBtns),
+ *   ToolbarSpacer(),
+ *   ToolbarButton({ onClick: save }, 'Save'),
+ * )
+ * ```
+ */
 export declare function ToolbarSpacer(): import("@tempots/dom").Renderable;

package/dist/types/components/navigation/tree-view.d.ts

@@ -0,0 +1,95 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize } from '../theme';
+/**
+ * Data structure representing a single item in the tree hierarchy.
+ */
+export interface TreeItemData {
+    /** Unique identifier for the tree item */
+    id: string;
+    /** Display label for the item */
+    label: string;
+    /** Optional icon name (Iconify format, e.g., `'mdi:folder'`) */
+    icon?: string;
+    /** Child items nested under this item */
+    children?: TreeItemData[];
+    /** Optional badge text displayed on the right */
+    badge?: string;
+}
+/**
+ * Configuration options for the {@link TreeView} component.
+ */
+export interface TreeViewOptions {
+    /** Array of tree items to render */
+    items: Value<TreeItemData[]>;
+    /** Currently selected item ID */
+    selectedId?: Value<string | undefined>;
+    /** Callback when an item is selected */
+    onSelect?: (id: string) => void;
+    /**
+     * Set of expanded item IDs for controlled mode (read-only).
+     * When provided, the component reads expansion state from this value.
+     * Use together with `onToggle` to handle state updates externally.
+     * When omitted, the component manages its own expansion state internally.
+     */
+    expandedIds?: Value<Set<string>>;
+    /**
+     * Callback when an item is expanded or collapsed.
+     * In controlled mode (when `expandedIds` is provided), use this to update your external state.
+     * In uncontrolled mode, this is called after the internal state is updated.
+     */
+    onToggle?: (id: string, expanded: boolean) => void;
+    /** Size of the tree items */
+    size?: Value<ControlSize>;
+}
+/**
+ * TreeView component for displaying hierarchical data with expand/collapse functionality.
+ *
+ * The TreeView renders a tree structure where items can have nested children. Each item
+ * can display an icon, label, and badge. Items with children show a chevron that can be
+ * clicked to expand or collapse the nested content.
+ *
+ * The component supports both controlled and uncontrolled modes:
+ * - **Controlled**: Pass `expandedIds` as a prop to manage expansion state externally
+ * - **Uncontrolled**: Let the component manage its own expansion state internally
+ *
+ * @param options - Configuration for tree items, selection, expansion, and callbacks
+ * @param children - Additional child nodes appended to the tree container
+ * @returns A tree navigation element with interactive expand/collapse behavior
+ *
+ * @example
+ * ```typescript
+ * // Uncontrolled mode — component manages expansion state internally
+ * TreeView({
+ *   items: [
+ *     {
+ *       id: 'folder1',
+ *       label: 'Documents',
+ *       icon: 'mdi:folder',
+ *       children: [
+ *         { id: 'file1', label: 'Report.pdf', icon: 'mdi:file-pdf' },
+ *         { id: 'file2', label: 'Data.xlsx', icon: 'mdi:file-excel' },
+ *       ]
+ *     },
+ *     { id: 'file3', label: 'Image.png', icon: 'mdi:file-image' }
+ *   ],
+ *   onSelect: (id) => console.log('Selected:', id),
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Controlled mode — parent manages expansion state
+ * const expandedIds = prop(new Set(['folder1']))
+ *
+ * TreeView({
+ *   items: treeData,
+ *   expandedIds,
+ *   onToggle: (id, expanded) => {
+ *     const ids = new Set(expandedIds.value)
+ *     expanded ? ids.add(id) : ids.delete(id)
+ *     expandedIds.set(ids)
+ *   },
+ * })
+ * ```
+ */
+export declare function TreeView({ items, selectedId, onSelect, expandedIds: externalExpandedIds, onToggle, size, }: TreeViewOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/overlay/announcement-bar.d.ts

@@ -1,21 +1,60 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
 import type { ThemeColorName } from '../../tokens';
+/**
+ * Configuration options for the {@link AnnouncementBar} component.
+ */
 export type AnnouncementBarOptions = {
+    /**
+     * Theme color applied to the announcement bar background.
+     * @default 'primary'
+     */
     color?: Value<ThemeColorName>;
+    /**
+     * Optional icon identifier displayed at the start of the announcement bar.
+     * When `undefined` or not provided, no icon is rendered.
+     */
     icon?: Value<string | undefined>;
+    /**
+     * Whether the announcement bar can be dismissed by the user via a close button.
+     * @default false
+     */
     closable?: Value<boolean>;
+    /**
+     * Callback invoked when the user dismisses the announcement bar.
+     * When provided and `closable` is not explicitly set, the bar is implicitly made dismissible.
+     */
     onDismiss?: () => void;
+    /**
+     * Additional CSS class names to apply to the announcement bar element.
+     */
     class?: Value<string>;
 };
 /**
- * AnnouncementBar component - displays a colored announcement bar at the top center of its container
+ * Displays a colored announcement bar, typically at the top of a page or container.
+ *
+ * Supports an optional leading icon, user-dismissible close button, and theme color
+ * customization. When dismissed, the bar is removed from the DOM and the `onDismiss`
+ * callback is invoked.
+ *
+ * @param options - Configuration options controlling color, icon, closability, and styling
+ * @param children - Text or node content displayed inside the announcement bar
+ * @returns A renderable node that is conditionally visible based on dismiss state
  *
  * @example
  * ```typescript
  * AnnouncementBar(
- *   { color: 'warning', closable: true },
+ *   { color: 'warning', closable: true, onDismiss: () => console.log('dismissed') },
  *   "You're on our launch Free plan with unlimited resumes and redaction!"
  * )
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With an icon
+ * AnnouncementBar(
+ *   { color: 'info', icon: 'info-circle', closable: true },
+ *   'System maintenance scheduled for tonight at 10 PM.'
+ * )
+ * ```
  */
 export declare function AnnouncementBar({ color, icon, closable, onDismiss, class: cls, }: AnnouncementBarOptions, ...children: TNode[]): Renderable;

package/dist/types/components/overlay/block-command-palette.d.ts

@@ -0,0 +1,25 @@
+import { TNode, Value } from '@tempots/dom';
+export interface BlockCommandItem {
+    /** Icon name for the command */
+    icon: string;
+    /** Display label */
+    label: string;
+    /** Optional description text */
+    description?: string;
+    /** Optional keyboard shortcut */
+    shortcut?: string;
+    /** Callback when this command is selected */
+    onSelect: () => void;
+}
+export interface BlockCommandPaletteOptions {
+    /** List of available commands */
+    items: Value<BlockCommandItem[]>;
+    /** Callback when the palette should close */
+    onClose: () => void;
+    /** Position (if absolute positioning is needed) */
+    position?: Value<{
+        x: number;
+        y: number;
+    }>;
+}
+export declare function BlockCommandPalette(options: BlockCommandPaletteOptions): TNode;

package/dist/types/components/overlay/command-palette.d.ts

@@ -0,0 +1,17 @@
+import { Renderable, TNode, Value } from '@tempots/dom';
+export interface CommandPaletteItem {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    shortcut?: string[];
+    section?: string;
+    onSelect: () => void;
+}
+export interface CommandPaletteOptions {
+    placeholder?: Value<string>;
+    emptyMessage?: Value<string>;
+    size?: Value<'sm' | 'md' | 'lg'>;
+    container?: 'body' | 'element';
+}
+export declare function CommandPalette(options: CommandPaletteOptions, fn: (open: (items: CommandPaletteItem[]) => void, close: () => void) => TNode): Renderable;

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';