@tempots/beatui 0.82.0 → 0.83.0

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

@@ -1,95 +1,209 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
 import { Placement } from '@tempots/ui';
 import { FlyoutTrigger, FlyoutTriggerFunction } from './flyout';
+/**
+ * Trigger mode for the {@link Menu} component.
+ * Alias for {@link FlyoutTrigger} -- controls how the menu is shown (e.g., `'click'`, `'hover'`).
+ */
 export type MenuTrigger = FlyoutTrigger;
+/**
+ * Configuration options for the {@link Menu} component.
+ */
 export interface MenuOptions {
-    /** The menu items to display */
+    /**
+     * Factory function returning the array of menu items (created via {@link MenuItem},
+     * {@link MenuSeparator}, or custom nodes with `role="menuitem"`).
+     */
     items: () => TNode[];
-    /** Placement of the menu relative to the trigger element */
+    /**
+     * Placement of the menu relative to the trigger element.
+     * @default 'bottom-start'
+     */
     placement?: Value<Placement>;
-    /** Delay in milliseconds before showing the menu on hover */
+    /**
+     * Delay in milliseconds before showing the menu after trigger activation.
+     * @default 0
+     */
     showDelay?: Value<number>;
-    /** Delay in milliseconds before hiding the menu after mouse leave */
+    /**
+     * Delay in milliseconds before hiding the menu after trigger deactivation.
+     * @default 100
+     */
     hideDelay?: Value<number>;
-    /** Offset in pixels from the main axis */
+    /**
+     * Offset in pixels from the main axis.
+     * @default 4
+     */
     mainAxisOffset?: Value<number>;
-    /** Offset in pixels from the cross axis */
+    /**
+     * Offset in pixels from the cross axis.
+     * @default 0
+     */
     crossAxisOffset?: Value<number>;
-    /** How to show the menu (accepts Flyout trigger or a custom trigger function) */
+    /**
+     * How the menu is triggered to show and hide.
+     * Accepts a built-in {@link MenuTrigger} string or a custom {@link FlyoutTriggerFunction}.
+     * @default 'click'
+     */
     showOn?: Value<MenuTrigger> | FlyoutTriggerFunction;
-    /** Whether the menu can be closed with Escape key */
+    /**
+     * Whether the menu can be closed with the Escape key or by clicking outside.
+     * @default true
+     */
     closable?: Value<boolean>;
-    /** Callback when menu is closed */
+    /**
+     * Callback invoked when the menu is closed (via Escape, click outside, or after item activation).
+     */
     onClose?: () => void;
-    /** Callback when a menu item is selected */
+    /**
+     * Callback invoked when a menu item with a `key` is activated (via click or keyboard).
+     * Receives the menu item's `key` as an argument.
+     */
     onAction?: (key: string) => void;
-    /** Accessible label for the menu */
+    /**
+     * Accessible label for the menu container (`aria-label`).
+     */
     ariaLabel?: Value<string>;
-    /** ID of element that labels the menu */
+    /**
+     * ID of the element that labels the menu (`aria-labelledby`).
+     */
     ariaLabelledBy?: Value<string>;
 }
+/**
+ * Configuration options for the {@link MenuItem} component.
+ */
 export interface MenuItemOptions {
-    /** Unique identifier for the menu item */
+    /**
+     * Unique identifier for the menu item. Used by the `onAction` callback in {@link MenuOptions}.
+     * When not provided, a unique session ID is generated automatically.
+     */
     key?: Value<string>;
-    /** The text content of the menu item */
+    /**
+     * Primary text or node content displayed as the menu item label.
+     */
     content: TNode;
-    /** Content to display at the start of the menu item (icons, indicators) */
+    /**
+     * Optional content displayed at the start (left side) of the menu item,
+     * typically used for icons or selection indicators.
+     */
     startContent?: TNode;
-    /** Content to display at the end of the menu item (shortcuts, badges) */
+    /**
+     * Optional content displayed at the end (right side) of the menu item,
+     * typically used for keyboard shortcuts or badges.
+     */
     endContent?: TNode;
-    /** Whether the menu item is disabled */
+    /**
+     * Whether the menu item is disabled. Disabled items are skipped by keyboard
+     * navigation and cannot be activated.
+     * @default false
+     */
     disabled?: Value<boolean>;
-    /** Callback when the menu item is clicked */
+    /**
+     * Callback invoked when the menu item is clicked or activated via keyboard.
+     */
     onClick?: () => void;
-    /** ARIA label for accessibility */
+    /**
+     * Accessible label for the menu item (`aria-label`).
+     */
     ariaLabel?: Value<string>;
-    /** Submenu items for nested menus */
+    /**
+     * Factory function returning submenu items for nested menus.
+     * When provided, the menu item gains a hover-triggered submenu.
+     */
     submenu?: () => TNode[];
-    /** Placement of submenu relative to parent item */
+    /**
+     * Placement of the submenu relative to the parent menu item.
+     * @default 'right-start'
+     */
     submenuPlacement?: Value<Placement>;
 }
+/**
+ * Configuration options for the {@link MenuSeparator} component.
+ */
 export interface MenuSeparatorOptions {
-    /** Optional label for the separator */
+    /**
+     * Optional label displayed alongside the separator line,
+     * useful for grouping related menu items under a heading.
+     */
     label?: TNode;
 }
 /**
- * Menu component that provides a list of actions or options.
- * Built on top of the Flyout component for positioning and overlay behavior.
+ * Dropdown menu component that provides a list of actions or options.
+ *
+ * Built on top of the {@link Flyout} component for positioning and overlay behavior.
+ * Follows the WAI-ARIA menu pattern with full keyboard navigation support:
+ * - Arrow Up/Down to navigate items
+ * - Home/End to jump to first/last item
+ * - Enter/Space to activate the focused item
+ * - Escape to close
+ * - Arrow Right to open submenus, Arrow Left to close them
  *
- * Follows WAI-ARIA menu pattern with proper keyboard navigation and accessibility.
+ * Focus is restored to the trigger element when the menu closes.
+ *
+ * @param options - Configuration options for menu behavior, positioning, and accessibility
+ * @returns A renderable node to be placed inside the trigger element
  *
  * @example
  * ```typescript
  * Button(
- *   { onClick: () => {} },
+ *   { variant: 'outline' },
  *   'Actions',
  *   Menu({
  *     items: () => [
- *       MenuItem({ content: 'Edit', onClick: () => console.log('edit') }),
- *       MenuItem({ content: 'Delete', onClick: () => console.log('delete') }),
- *     ]
+ *       MenuItem({ content: 'Edit', key: 'edit', onClick: () => console.log('edit') }),
+ *       MenuItem({ content: 'Duplicate', key: 'dup' }),
+ *       MenuSeparator(),
+ *       MenuItem({ content: 'Delete', key: 'delete', disabled: true }),
+ *     ],
+ *     onAction: (key) => console.log('Selected:', key),
+ *     placement: 'bottom-start',
  *   })
  * )
  * ```
  */
 export declare function Menu(options: MenuOptions): Renderable;
 /**
- * MenuItem component for individual menu items.
+ * Individual menu item component with optional start/end content and submenu support.
+ *
+ * Renders a `role="menuitem"` element with proper ARIA attributes for disabled state,
+ * selection state, and submenu expansion. Disabled items prevent click propagation
+ * and are skipped by keyboard navigation.
+ *
+ * @param options - Configuration options for the menu item's content, behavior, and accessibility
+ * @returns A renderable node
  *
  * @example
  * ```typescript
  * MenuItem({
+ *   key: 'edit',
  *   content: 'Edit',
- *   startContent: Icon({ icon: 'edit' }),
- *   endContent: html.span('⌘E'),
- *   onClick: () => console.log('edit clicked')
+ *   startContent: Icon({ icon: 'edit', size: 'sm' }),
+ *   endContent: html.span(attr.class('shortcut'), 'Ctrl+E'),
+ *   onClick: () => console.log('edit clicked'),
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Menu item with a submenu
+ * MenuItem({
+ *   content: 'Export as...',
+ *   submenu: () => [
+ *     MenuItem({ content: 'PDF', onClick: () => exportAs('pdf') }),
+ *     MenuItem({ content: 'CSV', onClick: () => exportAs('csv') }),
+ *   ],
  * })
  * ```
  */
 export declare function MenuItem(options: MenuItemOptions): Renderable;
 /**
- * MenuSeparator component for visual grouping of menu items.
- * Creates a visual divider between groups of menu items.
+ * Visual separator for grouping related menu items within a {@link Menu}.
+ *
+ * Renders a `role="separator"` element with horizontal orientation. An optional label
+ * can be provided to act as a section heading for the items below.
+ *
+ * @param options - Optional configuration with a label for the separator
+ * @returns A renderable node
  *
  * @example
  * ```typescript
@@ -102,5 +216,11 @@ export declare function MenuItem(options: MenuItemOptions): Renderable;
  *   ]
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With a labeled section
+ * MenuSeparator({ label: 'Advanced' })
+ * ```
  */
 export declare function MenuSeparator(options?: MenuSeparatorOptions): Renderable;

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

@@ -0,0 +1,82 @@
+import { Value } from '@tempots/dom';
+import { ControlSize } from '../theme';
+/**
+ * Configuration options for the {@link Pagination} component.
+ */
+export interface PaginationOptions {
+    /** Current page number (1-indexed). */
+    currentPage: Value<number>;
+    /** Total number of pages available. */
+    totalPages: Value<number>;
+    /** Callback invoked when a page is selected. */
+    onPageChange: (page: number) => void;
+    /** Number of page siblings to show around the current page. @default 1 */
+    siblings?: Value<number>;
+    /** Whether to show Previous/Next navigation buttons. @default true */
+    showPrevNext?: Value<boolean>;
+    /** Whether to show First/Last page buttons. @default false */
+    showFirstLast?: Value<boolean>;
+    /** Size affecting button dimensions and font size. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Whether to distribute items across the full available width. @default false */
+    justify?: Value<boolean>;
+    /** Whether to dynamically adjust the number of visible page numbers to fit available space. @default false */
+    responsive?: Value<boolean>;
+}
+/**
+ * Generates an array of page numbers and ellipsis markers for pagination display.
+ *
+ * The algorithm shows:
+ * - The first page (if not in range)
+ * - An ellipsis if there's a gap after first page
+ * - Page numbers around the current page (siblings)
+ * - An ellipsis if there's a gap before last page
+ * - The last page (if not in range)
+ *
+ * @param current - The current page number (1-indexed)
+ * @param total - The total number of pages
+ * @param siblings - Number of page numbers to show on each side of current
+ * @returns Array of page numbers and 'dots' markers for ellipsis
+ *
+ * @example
+ * ```typescript
+ * generatePaginationRange(5, 10, 1) // [1, 'dots', 4, 5, 6, 'dots', 10]
+ * generatePaginationRange(1, 10, 1) // [1, 2, 'dots', 10]
+ * generatePaginationRange(10, 10, 1) // [1, 'dots', 9, 10]
+ * ```
+ */
+export declare function generatePaginationRange(current: number, total: number, siblings: number): (number | 'dots')[];
+/**
+ * A pagination component for navigating through multiple pages of content.
+ *
+ * Features:
+ * - Configurable number of sibling pages shown around current page
+ * - Optional First/Last page navigation buttons
+ * - Optional Previous/Next navigation buttons
+ * - Ellipsis indicators for collapsed page ranges
+ * - Responsive sizing with theme support
+ * - Full keyboard navigation and ARIA support
+ *
+ * @param options - Configuration for appearance and behavior
+ * @returns A navigation element with pagination controls
+ *
+ * @example
+ * ```typescript
+ * const currentPage = prop(1)
+ * const totalPages = prop(10)
+ *
+ * Pagination({
+ *   currentPage,
+ *   totalPages,
+ *   onPageChange: (page) => {
+ *     currentPage.set(page)
+ *     // Load page data...
+ *   },
+ *   siblings: 1,
+ *   showPrevNext: true,
+ *   showFirstLast: false,
+ *   size: 'md'
+ * })
+ * ```
+ */
+export declare function Pagination({ currentPage, totalPages, onPageChange, siblings, showPrevNext, showFirstLast, size, justify, responsive, }: PaginationOptions): import("@tempots/dom").Renderable;

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

@@ -1,6 +1,48 @@
 import { TNode, Value } from '@tempots/dom';
+/**
+ * Configuration options for the {@link SidebarGroup} component.
+ */
 export type SidebarGroupOptions = {
+    /**
+     * Whether to render the group in compact "rail" mode, typically used for
+     * icon-only sidebar layouts.
+     * @default false
+     */
     rail?: Value<boolean>;
+    /**
+     * Optional header content displayed above the group of sidebar links.
+     * Typically a section title or label.
+     */
     header?: TNode;
 };
+/**
+ * Groups related sidebar links under an optional header within a {@link Sidebar}.
+ *
+ * Renders as a vertical stack with an optional header section and a container
+ * for child links. Supports a compact "rail" mode for icon-only sidebars.
+ *
+ * @param options - Configuration options for the sidebar group
+ * @param children - Child content, typically {@link SidebarLink} components
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * SidebarGroup(
+ *   { header: html.span('Main Navigation') },
+ *   SidebarLink({ content: 'Home', icon: 'home', href: '/' }),
+ *   SidebarLink({ content: 'About', icon: 'info', href: '/about' }),
+ *   SidebarLink({ content: 'Contact', icon: 'mail', href: '/contact' }),
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Rail mode (icon-only)
+ * SidebarGroup(
+ *   { rail: true },
+ *   SidebarLink({ content: '', icon: 'home', href: '/' }),
+ *   SidebarLink({ content: '', icon: 'settings', href: '/settings' }),
+ * )
+ * ```
+ */
 export declare function SidebarGroup({ rail, header }: SidebarGroupOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

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;