@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/components/monaco/monaco-editor-input.d.ts

@@ -1,12 +1,69 @@
+/**
+ * Monaco Editor integration component for BeatUI forms.
+ *
+ * Provides a rich code editor powered by Monaco Editor (VS Code's editor)
+ * that integrates with BeatUI's reactive form system, theming, and
+ * CSS injection strategy.
+ *
+ * @module
+ */
 import { Renderable } from '@tempots/dom';
 import type { InputOptions } from '../form/input/input-options';
 import { Merge } from '@tempots/std';
 import { MonacoEditorSpecificOptions } from '../../monaco/types';
+/**
+ * Options for the {@link MonacoEditorInput} component.
+ *
+ * Merges standard BeatUI {@link InputOptions} with Monaco-specific settings
+ * such as `language`, `editorOptions`, and `jsonSchemas`.
+ *
+ * @example
+ * ```ts
+ * const options: MonacoEditorInputOptions = {
+ *   value: prop('{}'),
+ *   onChange: v => console.log(v),
+ *   language: 'json',
+ *   editorOptions: { minimap: { enabled: false } },
+ *   cssInjection: 'link',
+ * }
+ * ```
+ */
 export type MonacoEditorInputOptions = Merge<InputOptions<string>, MonacoEditorSpecificOptions & {
+    /**
+     * CSS injection strategy for the Monaco editor stylesheet.
+     * - `'link'`: Lazily inject a `<link>` element pointing to the CSS asset.
+     * - `'none'`: Do not inject any CSS (the consumer manages styles).
+     * @default 'none'
+     */
     cssInjection?: 'link' | 'none';
 }>;
 /**
- * MonacoEditorInput mounts a Monaco editor in an InputContainer and wires its value to BeatUI inputs.
- * Note: This component dynamically imports 'monaco-editor' at runtime and does not include it in the main bundle.
+ * Mounts a Monaco (VS Code) editor inside a BeatUI form input container and
+ * wires its value to the reactive `InputOptions` interface.
+ *
+ * Monaco Editor is loaded lazily via CDN at runtime, so it is **not** included
+ * in the main library bundle. Language-specific features (validation, schemas)
+ * are also loaded on demand based on the `language` option.
+ *
+ * The component reacts to:
+ * - External `value` changes (syncs content into the editor)
+ * - `readOnly` / `disabled` changes
+ * - `language` and `jsonSchemas` changes (reconfigures validation)
+ * - Theme `appearance` changes (switches between VS light/dark themes)
+ *
+ * @param options - Configuration merging standard BeatUI input options with Monaco-specific settings.
+ * @returns A `Renderable` containing the Monaco editor.
+ *
+ * @example
+ * ```ts
+ * const code = prop('console.log("hello")')
+ *
+ * MonacoEditorInput({
+ *   value: code,
+ *   onChange: v => code.set(v),
+ *   language: 'javascript',
+ *   readOnly: false,
+ * })
+ * ```
  */
 export declare const MonacoEditorInput: (options: MonacoEditorInputOptions) => Renderable;

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

@@ -0,0 +1,96 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize } from '../theme/types';
+/**
+ * Represents a single item in the breadcrumb navigation trail.
+ */
+export interface BreadcrumbItem {
+    /** Display text for the breadcrumb item. */
+    label: string;
+    /** Optional URL for navigation (renders as `<a>` if provided). */
+    href?: string;
+    /** Optional click handler (renders as `<button>` if provided without href). */
+    onClick?: () => void;
+    /** Optional Iconify icon name (e.g., `'mdi:home'`). */
+    icon?: string;
+    /** Whether this item represents the current page. @default false */
+    current?: boolean;
+}
+/**
+ * Configuration options for the {@link Breadcrumbs} component.
+ */
+export interface BreadcrumbsOptions {
+    /** Array of breadcrumb items to display. */
+    items: Value<BreadcrumbItem[]>;
+    /**
+     * Separator character or string displayed between items.
+     * @default '/'
+     */
+    separator?: Value<string>;
+    /**
+     * Maximum number of items to display. When exceeded, middle items
+     * are collapsed into an ellipsis ("...").
+     * @default undefined (show all items)
+     */
+    maxItems?: Value<number>;
+    /**
+     * Size of the breadcrumb text and icons.
+     * @default 'md'
+     */
+    size?: Value<ControlSize>;
+}
+/**
+ * Navigation breadcrumbs component that displays a hierarchical trail of links
+ * leading to the current page.
+ *
+ * Breadcrumbs help users understand their location within a site hierarchy and
+ * provide a convenient way to navigate back to parent pages. The component supports
+ * collapsing middle items when the trail becomes too long, and can display icons
+ * alongside labels.
+ *
+ * Each item can be rendered as:
+ * - An anchor (`<a>`) if `href` is provided
+ * - A button (`<button>`) if `onClick` is provided
+ * - A plain span (`<span>`) if neither is provided
+ *
+ * The last item is automatically marked with `aria-current="page"` if its `current`
+ * property is true, indicating the current page to screen readers.
+ *
+ * @param options - Configuration for items, separator, max items, and size
+ * @returns A `<nav>` element containing the breadcrumb trail
+ *
+ * @example
+ * ```typescript
+ * Breadcrumbs({
+ *   items: [
+ *     { label: 'Home', href: '/', icon: 'mdi:home' },
+ *     { label: 'Products', href: '/products' },
+ *     { label: 'Electronics', href: '/products/electronics' },
+ *     { label: 'Laptop', current: true }
+ *   ]
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With max items to collapse long trails
+ * Breadcrumbs({
+ *   items: longItemsList,
+ *   maxItems: 3,
+ *   separator: '>',
+ *   size: 'sm'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With click handlers instead of links
+ * Breadcrumbs({
+ *   items: [
+ *     { label: 'Home', onClick: () => navigate('/') },
+ *     { label: 'Settings', onClick: () => navigate('/settings') },
+ *     { label: 'Profile', current: true }
+ *   ]
+ * })
+ * ```
+ */
+export declare function Breadcrumbs({ items, separator, maxItems, size, }: BreadcrumbsOptions): TNode;

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

@@ -1,46 +1,148 @@
 import { Renderable, TNode, Value } from '@tempots/dom';
 import { Placement } from '@tempots/ui';
+/**
+ * Built-in trigger modes that control how the {@link Flyout} is shown.
+ *
+ * - `'hover'` - Shows on mouse enter, hides on mouse leave.
+ * - `'focus'` - Shows on focus, hides on blur.
+ * - `'hover-focus'` - Combines both hover and focus triggers.
+ * - `'click'` - Shows on click, hides on clicking outside.
+ * - `'never'` - Never shows automatically; must be controlled programmatically via a custom trigger function.
+ */
 export type FlyoutTrigger = 'hover' | 'focus' | 'hover-focus' | 'click' | 'never';
+/**
+ * Custom trigger function for the {@link Flyout} component.
+ * Receives `show` and `hide` callbacks and returns trigger content that controls
+ * when the flyout appears and disappears.
+ *
+ * @param show - Call to show the flyout
+ * @param hide - Call to hide the flyout
+ * @returns A renderable node containing the trigger logic
+ */
 export type FlyoutTriggerFunction = (show: () => void, hide: () => void) => TNode;
+/**
+ * Positioning data for a popover arrow element, provided by the PopOver positioning engine.
+ */
 export interface PopOverArrowOptions {
+    /** The computed placement of the popover (e.g., `'top'`, `'bottom-start'`). */
     placement: string;
+    /** Horizontal offset of the arrow in pixels relative to the popover container. */
     x?: number;
+    /** Vertical offset of the arrow in pixels relative to the popover container. */
     y?: number;
+    /** Offset from the center of the reference element, used for arrow alignment. */
     centerOffset: number;
+    /** Width of the popover container in pixels. */
     containerWidth: number;
+    /** Height of the popover container in pixels. */
     containerHeight: number;
 }
+/**
+ * Configuration options for the {@link Flyout} component.
+ */
 export interface FlyoutOptions {
-    /** The flyout content to display */
+    /**
+     * Factory function that returns the flyout content to display.
+     * Called lazily when the flyout opens.
+     */
     content: () => TNode;
-    /** Placement of the flyout relative to the trigger element */
+    /**
+     * Placement of the flyout relative to the trigger element.
+     * Uses the Floating UI placement model (e.g., `'top'`, `'bottom-start'`, `'right-end'`).
+     * @default 'top'
+     */
     placement?: Value<Placement>;
-    /** Delay in milliseconds before showing the flyout on hover */
+    /**
+     * Delay in milliseconds before showing the flyout after trigger activation.
+     * @default 250
+     */
     showDelay?: Value<number>;
-    /** Delay in milliseconds before hiding the flyout after mouse leave */
+    /**
+     * Delay in milliseconds before hiding the flyout after trigger deactivation.
+     * @default 500
+     */
     hideDelay?: Value<number>;
-    /** Offset in pixels from the main axis (vertical for top/bottom, horizontal for left/right) */
+    /**
+     * Offset in pixels from the main axis (vertical for top/bottom placements,
+     * horizontal for left/right placements).
+     * @default 8
+     */
     mainAxisOffset?: Value<number>;
-    /** Offset in pixels from the cross axis (horizontal for top/bottom, vertical for left/right) */
+    /**
+     * Offset in pixels from the cross axis (horizontal for top/bottom placements,
+     * vertical for left/right placements).
+     * @default 0
+     */
     crossAxisOffset?: Value<number>;
-    /** How to show the flyout */
+    /**
+     * How the flyout is triggered to show and hide. Accepts a built-in {@link FlyoutTrigger}
+     * string or a custom {@link FlyoutTriggerFunction} for programmatic control.
+     * @default 'hover-focus'
+     */
     showOn?: Value<FlyoutTrigger> | FlyoutTriggerFunction;
-    /** Whether the flyout can be closed with Escape key or clicking outside */
+    /**
+     * Whether the flyout can be closed with the Escape key or by clicking outside.
+     * @default true
+     */
     closable?: Value<boolean>;
-    /** Optional arrow configuration - receives a signal with PopOver positioning data */
+    /**
+     * Optional arrow renderer. Receives a signal with {@link PopOverArrowOptions} positioning
+     * data and returns a TNode to render as the arrow element.
+     */
     arrow?: (signal: any) => TNode;
-    /** Additional role attribute for accessibility */
+    /**
+     * ARIA role attribute applied to the flyout container.
+     * @default 'dialog'
+     */
     role?: Value<string>;
-    /** Optional aria-haspopup value for the trigger element */
+    /**
+     * Value for the `aria-haspopup` attribute on the trigger element.
+     * Indicates the type of popup that the trigger controls.
+     * @default 'dialog'
+     */
     hasPopup?: Value<boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid'>;
 }
 /**
- * Flyout component that provides a flexible popover with various trigger options.
- * This is the base component that powers Tooltip and other overlay components.
+ * Flexible popover component with configurable trigger modes, animated transitions,
+ * and accessibility support.
+ *
+ * Unlike wrapper-based flyout libraries, this component is designed to be rendered as a
+ * **child** of the trigger element. It attaches event listeners to the parent element
+ * and manages the popover lifecycle (show/hide with delays, animation, keyboard dismissal).
+ *
+ * This is the base component that powers {@link Tooltip}, {@link Menu}, and other
+ * positioned overlay components.
+ *
+ * Uses `@tempots/ui` PopOver for Floating UI-based positioning.
+ *
+ * @param options - Configuration options controlling content, placement, triggers, delays, and accessibility
+ * @returns A renderable node to be placed inside the trigger element
  *
- * Unlike other flyout libraries, this component is designed to be a child of the element
- * it provides a flyout for, rather than wrapping it.
+ * @example
+ * ```typescript
+ * // Hover-triggered flyout
+ * html.button(
+ *   'Hover me',
+ *   Flyout({
+ *     content: () => html.div('Flyout content'),
+ *     placement: 'bottom',
+ *     showOn: 'hover',
+ *     showDelay: 200,
+ *     hideDelay: 300,
+ *   })
+ * )
+ * ```
  *
- * Uses @tempo-ts/ui PopOver for positioning.
+ * @example
+ * ```typescript
+ * // Click-triggered flyout with custom trigger function
+ * html.button(
+ *   'Click me',
+ *   Flyout({
+ *     content: () => html.div('Custom content'),
+ *     showOn: (show, hide) => on.click(() => show()),
+ *   })
+ * )
+ * ```
  */
 export declare function Flyout(options: FlyoutOptions): Renderable;

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

@@ -1,6 +1,9 @@
+export * from './breadcrumbs';
 export * from './flyout';
 export * from './link';
 export * from './menu';
+export * from './pagination';
 export * from './sidebar/index';
 export * from './tabs';
 export * from './toolbar';
+export * from './tree-view';

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

@@ -1,20 +1,120 @@
 import { TNode, Value } from '@tempots/dom';
 import type { NavigationOptions } from '@tempots/ui';
 import { ThemeColorName } from '../../../tokens';
+/**
+ * Visual style variant for the {@link Link} component.
+ *
+ * - `'default'` - Standard underlined link appearance.
+ * - `'plain'` - No underline; inherits text color.
+ * - `'hover'` - Underline appears only on hover.
+ */
 export type LinkVariant = 'default' | 'plain' | 'hover';
+/**
+ * Configuration options for the {@link Link} component.
+ */
 export interface LinkOptions {
+    /**
+     * The URL or path that the link navigates to.
+     */
     href: Value<string>;
+    /**
+     * Visual style variant controlling underline behavior.
+     * @default 'default'
+     */
     variant?: Value<LinkVariant>;
+    /**
+     * Theme color applied to the link text and hover state.
+     * @default 'primary'
+     */
     color?: Value<ThemeColorName>;
+    /**
+     * Theme color applied to the link text when disabled.
+     * @default 'base'
+     */
     colorDisabled?: Value<ThemeColorName>;
+    /**
+     * Whether the link is disabled. When `true`, the link renders as a non-interactive
+     * `<span>` element instead of an anchor.
+     * @default false
+     */
     disabled?: Value<boolean>;
+    /**
+     * 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 (e.g., scroll to top or preserve position).
+     */
     scroll?: NavigationOptions['scroll'];
+    /**
+     * Whether to replace the current history entry instead of pushing a new one.
+     */
     replace?: NavigationOptions['replace'];
+    /**
+     * Target attribute for the anchor element (e.g., `'_blank'` for new tab).
+     */
     target?: Value<string>;
+    /**
+     * Relationship attribute for the anchor element (e.g., `'noopener noreferrer'`).
+     */
     rel?: Value<string>;
 }
+/**
+ * Generates the CSS class string for the link based on its variant and disabled state.
+ *
+ * @param variant - The visual style variant
+ * @param disabled - Whether the link is disabled
+ * @returns A space-separated CSS class string
+ */
 export declare function generateLinkClasses(variant: LinkVariant, disabled: boolean): string;
+/**
+ * Generates the inline CSS custom properties for link color theming in both light and dark modes.
+ *
+ * @param color - The theme color name to use for link text
+ * @returns A semicolon-separated CSS custom property string
+ */
 export declare function generateLinkStyles(color: ThemeColorName): string;
+/**
+ * Themed navigation link component with support for client-side routing, view transitions,
+ * and disabled state.
+ *
+ * When enabled, renders as an `Anchor` element from `@tempots/ui` with client-side navigation.
+ * When disabled, renders as a `<span>` element with disabled styling to prevent interaction.
+ *
+ * @param options - Configuration options controlling appearance, navigation behavior, and accessibility
+ * @param children - Child content displayed inside the link
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * Link(
+ *   { href: '/about', color: 'primary', variant: 'default' },
+ *   'About Us'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // External link opening in a new tab
+ * Link(
+ *   { href: 'https://example.com', target: '_blank', rel: 'noopener noreferrer' },
+ *   'Visit Example'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disabled link
+ * const isDisabled = prop(true)
+ * Link(
+ *   { href: '/dashboard', disabled: isDisabled, colorDisabled: 'base' },
+ *   'Dashboard'
+ * )
+ * ```
+ */
 export declare function Link({ href, variant, color, colorDisabled, disabled, viewTransition, state, scroll, replace, target, rel, }: LinkOptions, ...children: TNode[]): import("@tempots/dom").Renderable;