@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/navigation/sidebar/sidebar-link.d.ts

@@ -1,30 +1,131 @@
 import { DOMContext, TNode, Value } from '@tempots/dom';
 import type { NavigationOptions } from '@tempots/ui';
+/**
+ * URL-based navigation action for a {@link SidebarLink}.
+ * Navigates to the specified URL using client-side routing.
+ */
 export type UrlAction = {
+    /** The URL or path to navigate to. */
     href: Value<string>;
+    /**
+     * Whether to use the View Transitions API for navigation animations.
+     * @default true
+     */
     viewTransition?: boolean;
+    /** Optional state object to pass to the navigation history entry. */
     state?: NavigationOptions['state'];
+    /** Scroll behavior after navigation. */
     scroll?: NavigationOptions['scroll'];
+    /** Whether to replace the current history entry instead of pushing a new one. */
     replace?: NavigationOptions['replace'];
 };
+/**
+ * Click-based action for a {@link SidebarLink}.
+ * Renders the link as a button that invokes the provided callback on click.
+ */
 export type ClickAction = {
+    /** Callback invoked when the sidebar link is clicked. */
     onClick: () => void;
 };
+/**
+ * Discriminated union of navigation actions for a {@link SidebarLink}.
+ * Either a URL-based navigation or a click-based callback action.
+ */
 export type LinkAction = UrlAction | ClickAction;
+/**
+ * Configuration options for the {@link SidebarLink} component.
+ * Extends {@link LinkAction} to provide either URL-based navigation or click-based actions.
+ */
 export type SidebarLinkOptions = {
+    /** Primary text or node content displayed as the link label. */
     content: TNode;
+    /** Optional icon identifier displayed at the start of the link. */
     icon?: Value<string>;
+    /** Optional content displayed at the right side of the link (e.g., badges, counts). */
     right?: TNode;
+    /**
+     * Optional inline action button rendered at the end of the link.
+     * Useful for quick actions like delete, settings, or expand/collapse toggles.
+     */
     action?: {
+        /** Icon identifier for the action button. */
         icon: Value<string>;
+        /** Accessible label for the action button. */
         label?: Value<string>;
+        /** Callback invoked when the action button is clicked. Receives the DOM context. */
         onClick?: (ctx: DOMContext) => void;
     };
+    /** ARIA expanded state, used when the link controls a collapsible section. */
     ariaExpanded?: Value<boolean>;
+    /** ID of the element this link controls (for ARIA `aria-controls`). */
     ariaControls?: Value<string>;
+    /** Accessible label for the link (for ARIA `aria-label`). */
     ariaLabel?: Value<string>;
 } & LinkAction;
+/**
+ * Renders a sidebar link as an anchor element with client-side navigation support.
+ *
+ * @param options - URL navigation options (href, viewTransition, state, scroll, replace)
+ * @param children - Child content for the anchor
+ * @returns A renderable anchor node
+ */
 export declare function SidebarUrlLink(options: UrlAction, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Renders a sidebar link in its active (current page) state as a non-interactive `<span>`.
+ *
+ * Used internally by {@link SidebarLink} when the link's href matches the current URL.
+ *
+ * @param children - Child content for the active link display
+ * @returns A renderable span node
+ */
 export declare function SidebarActiveLink(...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Renders a sidebar link as a `<button>` element for click-based actions.
+ *
+ * Supports ARIA attributes for accessibility when the button controls a collapsible
+ * section or acts as a toggle.
+ *
+ * @param options - Click action and optional ARIA attributes
+ * @param children - Child content for the button
+ * @returns A renderable button node
+ */
 export declare function SidebarClickLink(options: ClickAction & Partial<Pick<SidebarLinkOptions, 'ariaExpanded' | 'ariaControls' | 'ariaLabel'>>, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Sidebar navigation link component that supports both URL-based navigation and click-based actions.
+ *
+ * For URL-based links, automatically detects the active state by comparing the link's `href`
+ * with the current URL via the `Location` provider. Active links render as non-interactive
+ * `<span>` elements, while inactive links render as client-side navigating anchors.
+ *
+ * For click-based links (when `onClick` is provided), renders as a `<button>` element.
+ *
+ * @param options - Configuration options including content, icon, action, and link behavior
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * // URL-based navigation link
+ * SidebarLink({
+ *   content: 'Dashboard',
+ *   icon: 'home',
+ *   href: '/dashboard',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Click-based action link with an inline action button
+ * SidebarLink({
+ *   content: 'Projects',
+ *   icon: 'folder',
+ *   onClick: () => toggleProjectsPanel(),
+ *   ariaExpanded: isExpanded,
+ *   action: {
+ *     icon: 'plus',
+ *     label: 'Create project',
+ *     onClick: () => createProject(),
+ *   },
+ * })
+ * ```
+ */
 export declare function SidebarLink(options: SidebarLinkOptions): import("@tempots/dom").Renderable;

package/dist/types/components/navigation/sidebar/sidebar-separator.d.ts

@@ -1 +1,18 @@
+/**
+ * Visual separator rendered as a horizontal rule within a {@link Sidebar}.
+ *
+ * Used to visually divide groups of sidebar links or sections.
+ *
+ * @returns A renderable `<hr>` node with the sidebar separator class
+ *
+ * @example
+ * ```typescript
+ * Sidebar(
+ *   { backgroundMode: 'light' },
+ *   SidebarGroup({ header: html.span('Section A') }, ...linksA),
+ *   SidebarSeparator(),
+ *   SidebarGroup({ header: html.span('Section B') }, ...linksB),
+ * )
+ * ```
+ */
 export declare function SidebarSeparator(): import("@tempots/dom").Renderable;

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

@@ -1,10 +1,67 @@
 import { Provider, TNode, Value } from '@tempots/dom';
+/**
+ * Background mode for the {@link Sidebar} component, controlling its visual appearance
+ * in relation to the surrounding page content.
+ */
 export type SidebarBackgroundMode = 'light' | 'dark';
+/**
+ * Configuration options for the {@link Sidebar} component.
+ */
 export type SidebarOptions = {
+    /**
+     * Background mode controlling the sidebar's visual appearance.
+     * When set to `'dark'`, the sidebar applies a dark background CSS modifier class.
+     * @default 'light'
+     */
     backgroundMode?: Value<SidebarBackgroundMode>;
 };
+/**
+ * Context value provided by the {@link Sidebar} component to its descendants.
+ * Child components (e.g., {@link SidebarLink}, {@link SidebarGroup}) can consume
+ * this context to adapt their appearance to the sidebar's background mode.
+ */
 export type SidebarContextValue = {
+    /** The current background mode of the enclosing sidebar. */
     backgroundMode: SidebarBackgroundMode;
 };
+/**
+ * Provider for the sidebar context, allowing child components to access the sidebar's
+ * background mode. Uses the Tempo provider pattern with a `mark` and `create` function.
+ *
+ * @example
+ * ```typescript
+ * Use(SidebarContext, (ctx) => {
+ *   // ctx.backgroundMode is 'light' or 'dark'
+ *   return html.span(`Background: ${ctx.backgroundMode}`)
+ * })
+ * ```
+ */
 export declare const SidebarContext: Provider<SidebarContextValue, object>;
+/**
+ * Sidebar navigation container that provides a vertical navigation panel with context
+ * for child components.
+ *
+ * The sidebar provides a {@link SidebarContext} to its descendants, allowing child
+ * components like {@link SidebarLink} and {@link SidebarGroup} to adapt their styling
+ * based on the sidebar's background mode.
+ *
+ * @param options - Configuration options controlling the sidebar's background appearance
+ * @param children - Child content, typically {@link SidebarGroup}, {@link SidebarLink},
+ *   and {@link SidebarSeparator} components
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Sidebar(
+ *   { backgroundMode: 'dark' },
+ *   SidebarGroup(
+ *     { header: html.span('Navigation') },
+ *     SidebarLink({ content: 'Dashboard', icon: 'home', href: '/' }),
+ *     SidebarLink({ content: 'Settings', icon: 'cog', href: '/settings' }),
+ *   ),
+ *   SidebarSeparator(),
+ *   SidebarLink({ content: 'Logout', icon: 'logout', onClick: handleLogout }),
+ * )
+ * ```
+ */
 export declare function Sidebar({ backgroundMode }: SidebarOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

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

@@ -1,6 +1,7 @@
 import { TNode, Value } from '@tempots/dom';
 import { ControlSize, ButtonVariant } from '../../theme';
 import { ThemeColorName } from '../../../tokens';
+export type TabsVariant = ButtonVariant | 'underline' | 'pill';
 export interface TabItem<T extends string> {
     /** Unique identifier for the tab */
     key: T;
@@ -24,7 +25,7 @@ export interface TabsOptions<T extends string> {
     /** Size of the tabs */
     size?: Value<ControlSize>;
     /** Visual variant */
-    variant?: Value<ButtonVariant>;
+    variant?: Value<TabsVariant>;
     /** Color used by certain variants (e.g., filled) */
     color?: Value<ThemeColorName>;
     /** Whether tabs are disabled */
@@ -54,4 +55,4 @@ export interface TabsOptions<T extends string> {
  * })
  * ```
  */
-export declare function Tabs<T extends string>(options: TabsOptions<T>): TNode;
+export declare function Tabs<T extends string>(options: TabsOptions<T>): import("@tempots/dom").Renderable;

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;