@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/misc/notice.d.ts

@@ -1,15 +1,108 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
+/**
+ * Visual variant for the Notice component, determining its color scheme
+ * and semantic meaning.
+ *
+ * - `'info'` - Informational notice (blue tones)
+ * - `'success'` - Success confirmation (green tones)
+ * - `'warning'` - Warning or caution (yellow/amber tones)
+ * - `'danger'` - Error or critical alert (red tones)
+ */
 export type NoticeVariant = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Visual tone for the Notice component, controlling its visual prominence.
+ *
+ * - `'subtle'` - Lighter background with softer colors
+ * - `'prominent'` - Stronger background with higher contrast
+ */
 export type NoticeTone = 'subtle' | 'prominent';
+/**
+ * ARIA role for the Notice component, determining how assistive technologies
+ * announce the notice.
+ *
+ * - `'status'` - Non-urgent information updates (used for info, success, warning)
+ * - `'alert'` - Urgent, time-sensitive information (used for danger by default)
+ */
 export type NoticeRole = 'status' | 'alert';
+/**
+ * Configuration options for the {@link Notice} component.
+ */
 export type NoticeOptions = {
+    /**
+     * The semantic variant controlling color scheme and default icon.
+     * @default 'info'
+     */
     variant?: Value<NoticeVariant>;
+    /**
+     * The visual tone controlling background intensity.
+     * @default 'subtle'
+     */
     tone?: Value<NoticeTone>;
+    /**
+     * ARIA role override. When not specified, defaults to `'alert'` for the
+     * `'danger'` variant and `'status'` for all others.
+     */
     role?: Value<NoticeRole | undefined>;
+    /**
+     * Optional title text displayed prominently above the notice body content.
+     */
     title?: Value<string | undefined>;
+    /**
+     * Icon identifier string (Iconify format), or `false` to suppress the icon entirely.
+     * When `undefined`, a default icon is chosen based on the variant.
+     */
     icon?: Value<string | false | undefined>;
+    /**
+     * Whether the notice can be dismissed by the user via a close button.
+     * @default false
+     */
     closable?: Value<boolean>;
+    /**
+     * Callback invoked when the notice is dismissed. If provided, the close
+     * button is shown regardless of the `closable` setting.
+     */
     onDismiss?: () => void;
+    /**
+     * Additional CSS class name(s) to apply to the notice root element.
+     */
     class?: Value<string>;
 };
+/**
+ * Renders a dismissible notice/alert banner with variant-driven styling,
+ * an optional icon, title, and close button. Supports accessible ARIA roles
+ * that automatically adapt based on the variant.
+ *
+ * When dismissed, the notice is hidden from the DOM and the optional
+ * `onDismiss` callback is invoked.
+ *
+ * @param options - Configuration options for the notice.
+ * @param children - Content nodes rendered inside the notice body.
+ * @returns A renderable notice element.
+ *
+ * @example
+ * ```typescript
+ * // Simple informational notice
+ * Notice(
+ *   { variant: 'info', title: 'Tip' },
+ *   'You can customize your dashboard in Settings.'
+ * )
+ *
+ * // Closable danger notice with callback
+ * Notice(
+ *   {
+ *     variant: 'danger',
+ *     title: 'Error',
+ *     closable: true,
+ *     onDismiss: () => console.log('dismissed'),
+ *   },
+ *   'Something went wrong. Please try again.'
+ * )
+ *
+ * // Notice without icon
+ * Notice(
+ *   { variant: 'warning', icon: false, tone: 'prominent' },
+ *   'This action cannot be undone.'
+ * )
+ * ```
+ */
 export declare function Notice({ variant, tone, role, title, icon, closable, onDismiss, class: cls, }: NoticeOptions, ...children: TNode[]): Renderable;

package/dist/types/components/misc/notification-panel.d.ts

@@ -0,0 +1,21 @@
+import { TNode, Value } from '@tempots/dom';
+export interface NotificationPanelItem {
+    id: string;
+    icon: string;
+    iconColor?: string;
+    title: string;
+    body: string;
+    time: string;
+    read: boolean;
+    source?: {
+        label: string;
+        type: string;
+    };
+    onClick?: () => void;
+}
+export interface NotificationPanelOptions {
+    items: Value<NotificationPanelItem[]>;
+    onMarkAllRead?: () => void;
+    onClose?: () => void;
+}
+export declare function NotificationPanel(options: NotificationPanelOptions): TNode;

package/dist/types/components/misc/notification-provider.d.ts

@@ -2,37 +2,111 @@ import { Provider, Signal, TNode } from '@tempots/dom';
 import { NotificationOptions } from './notification';
 import { RadiusName, ThemeColorName } from '../../tokens';
 import { AnimationConfig } from '../../utils';
+/**
+ * Internal representation of a queued notification within the notification
+ * provider. Each entry captures the resolved reactive signals, animation
+ * configuration, and lifecycle hooks for a single notification instance.
+ */
 type NotificationEntry = {
+    /** Animation configuration for the notification's enter/exit transitions. */
     animation: AnimationConfig;
+    /** Child content nodes rendered inside the notification body. */
     children: TNode[];
+    /** Reactive signal indicating whether the notification is in a loading state. */
     loading: Signal<boolean>;
+    /** Reactive signal controlling close button visibility. */
     withCloseButton: Signal<boolean>;
+    /** Reactive signal controlling border visibility. */
     withBorder: Signal<boolean>;
+    /** Reactive signal for the notification's theme color. */
     color: Signal<ThemeColorName>;
+    /** Reactive signal for the notification's border radius. */
     radius: Signal<RadiusName>;
+    /** Title content rendered above the notification body. */
     title: TNode;
+    /** Reactive signal for the Iconify icon identifier. */
     icon: Signal<string | undefined>;
+    /** Reactive signal for additional CSS class(es). */
     class: Signal<string | undefined>;
+    /** Registers a callback to be invoked when the notification should close. */
     listenRequestClose: (fn: () => void) => void;
+    /** Optional promise that, when resolved, triggers automatic dismissal. */
     delayedClose?: Promise<void>;
 };
+/**
+ * Options for showing a notification via the notification provider.
+ * Extends {@link NotificationOptions} with animation and auto-dismiss settings.
+ */
 export type ShowNotificationOptions = NotificationOptions & {
+    /**
+     * Animation configuration for the notification's enter/exit transitions.
+     * @default { fade: true }
+     */
     animation?: AnimationConfig;
+    /**
+     * Auto-dismiss behavior. When a `number` is provided, the notification
+     * is dismissed after that many seconds. When a `Promise` is provided,
+     * the notification is dismissed when the promise resolves.
+     */
     dismissAfter?: number | Promise<void>;
 };
+/**
+ * Function signature for showing a notification. Accepts configuration options
+ * and child content nodes.
+ *
+ * @param options - Configuration for the notification appearance and behavior.
+ * @param children - Content nodes rendered inside the notification body.
+ */
 export type NotificationShowFn = (options: ShowNotificationOptions, ...children: TNode[]) => void;
+/**
+ * Screen corner position where the notification viewport is anchored.
+ *
+ * - `'top-start'` - Top-left in LTR layouts, top-right in RTL
+ * - `'top-end'` - Top-right in LTR layouts, top-left in RTL
+ * - `'bottom-start'` - Bottom-left in LTR layouts, bottom-right in RTL
+ * - `'bottom-end'` - Bottom-right in LTR layouts, bottom-left in RTL
+ */
 export type NotificationViewportPosition = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/**
+ * Options for configuring the {@link NotificationProvider}.
+ */
 export type NotificationProviderOptions = {
+    /**
+     * Screen corner where notifications are displayed.
+     * @default 'bottom-end'
+     */
     position?: NotificationViewportPosition;
 };
+/**
+ * Value exposed by the {@link NotificationProvider} to its consumers.
+ * Provides methods to show and clear notifications, and reactive state
+ * about active notification count.
+ */
 export type NotificationProviderValue = {
+    /** Shows a new notification with the given options and content. */
     show: NotificationShowFn;
+    /** Dismisses all currently active notifications. */
     clear: () => void;
+    /** The viewport position where notifications are rendered. */
     position: NotificationViewportPosition;
+    /**
+     * Registers a listener invoked whenever a new notification is shown.
+     * Returns an unsubscribe function.
+     */
     listenOnShow: (fn: (entry: NotificationEntry) => void) => () => void;
+    /** Reactive signal tracking the number of currently visible notifications. */
     activeNotifications: Signal<number>;
 };
+/**
+ * A subset of the notification provider value exposing only the `show` and `clear` methods.
+ */
 type NotificationServiceHandle = Pick<NotificationProviderValue, 'show' | 'clear'>;
+/**
+ * Internal implementation of the global notification service. Maintains a
+ * stack of attached provider handles so that the most recently attached
+ * provider receives show/clear calls. This enables nested providers where
+ * inner providers take precedence.
+ */
 declare class NotificationServiceImpl {
     private handles;
     attach(handle: NotificationServiceHandle): () => void;
@@ -41,7 +115,74 @@ declare class NotificationServiceImpl {
     show(options: ShowNotificationOptions, ...children: TNode[]): void;
     clear(): void;
 }
+/**
+ * Global singleton notification service that delegates to the most recently
+ * attached {@link NotificationProvider}. Use this to show notifications
+ * imperatively from anywhere in the application without needing direct
+ * access to the provider context.
+ *
+ * @example
+ * ```typescript
+ * // Show a notification imperatively
+ * NotificationService.show(
+ *   { title: 'Saved', color: 'success', dismissAfter: 3 },
+ *   'Your changes have been saved.'
+ * )
+ *
+ * // Clear all active notifications
+ * NotificationService.clear()
+ * ```
+ */
 export declare const NotificationService: NotificationServiceImpl;
+/**
+ * Provider that manages the notification system lifecycle. Creates a notification
+ * queue, registers with the global {@link NotificationService}, and exposes
+ * `show` / `clear` methods to consumers via the Tempo provider pattern.
+ *
+ * Attach this provider in your application root (or use BeatUI's built-in
+ * integration) to enable notification rendering through {@link NotificationViewport}.
+ *
+ * @example
+ * ```typescript
+ * import { Provide, Use } from '@tempots/dom'
+ *
+ * // Provide the notification system
+ * Provide(NotificationProvider, { position: 'top-end' },
+ *   // Consume from a child component
+ *   Use(NotificationProvider, ({ show }) => {
+ *     show(
+ *       { title: 'Hello', color: 'primary', dismissAfter: 5 },
+ *       'Welcome to the app!'
+ *     )
+ *     return html.div('App content')
+ *   })
+ * )
+ * ```
+ */
 export declare const NotificationProvider: Provider<NotificationProviderValue, NotificationProviderOptions>;
+/**
+ * Renders the notification viewport container that displays active notifications.
+ * Must be placed inside a tree that has a {@link NotificationProvider} ancestor.
+ *
+ * The viewport listens for new notifications via `listenOnShow` and renders
+ * each one with enter/exit animations managed by `AnimatedToggle`. Notifications
+ * with `delayedClose` are automatically dismissed when the delay resolves.
+ *
+ * @returns A renderable viewport element positioned according to the provider's
+ *   `position` setting (e.g., `'bottom-end'`).
+ *
+ * @example
+ * ```typescript
+ * import { Provide } from '@tempots/dom'
+ *
+ * // Place the viewport at the app root alongside the provider
+ * Provide(NotificationProvider, { position: 'bottom-end' },
+ *   html.div(
+ *     // ... app content ...
+ *   ),
+ *   NotificationViewport()
+ * )
+ * ```
+ */
 export declare function NotificationViewport(): import("@tempots/dom").Renderable;
 export {};

package/dist/types/components/misc/notification.d.ts

@@ -1,17 +1,110 @@
 import { Renderable, TNode, Value } from '@tempots/dom';
 import { ThemeColorName } from '../../tokens/colors';
 import { RadiusName } from '../../tokens/radius';
+/**
+ * Configuration options for the {@link Notification} component.
+ */
 export type NotificationOptions = {
+    /**
+     * Whether the notification is in a loading state. When `true`, a spinner
+     * icon replaces the custom icon.
+     * @default false
+     */
     loading?: Value<boolean>;
+    /**
+     * Whether to display a close button in the notification.
+     * @default false
+     */
     withCloseButton?: Value<boolean>;
+    /**
+     * Whether the notification displays a colored border.
+     * @default false
+     */
     withBorder?: Value<boolean>;
+    /**
+     * Theme color applied to the notification accent, icon, and close button.
+     * @default 'primary'
+     */
     color?: Value<ThemeColorName>;
+    /**
+     * Border radius applied to the notification container.
+     * @default 'md'
+     */
     radius?: Value<RadiusName>;
+    /**
+     * Optional title content rendered above the notification body.
+     */
     title?: TNode;
+    /**
+     * Iconify icon identifier to display. When `undefined` and not loading,
+     * a colored accent bar is shown instead.
+     */
     icon?: Value<string | undefined>;
+    /**
+     * Callback invoked when the close button is clicked.
+     */
     onClose?: () => void;
+    /**
+     * Additional CSS class name(s) to apply to the notification root element.
+     */
     class?: Value<string | undefined>;
 };
+/**
+ * Builds the CSS class string for a Notification element based on its state flags.
+ *
+ * @param withBorder - Whether the bordered modifier class is applied.
+ * @param hasIcon - Whether the has-icon modifier class is applied.
+ * @param hasCloseButton - Whether the closable modifier class is applied.
+ * @param loading - Whether the loading modifier class is applied.
+ * @param extra - Optional additional CSS class(es) to append.
+ * @returns A space-separated class string for the notification root element.
+ */
 export declare function generateNotificationClasses(withBorder: boolean, hasIcon: boolean, hasCloseButton: boolean, loading: boolean, extra?: string): string;
+/**
+ * Builds the inline CSS style string for a Notification element, setting
+ * CSS custom properties for accent color and border radius.
+ *
+ * @param color - Theme color name used for the accent (maps to the 500 shade).
+ * @param radius - Radius token name for the notification border radius.
+ * @returns A semicolon-separated CSS variable declaration string.
+ */
 export declare function generateNotificationStyles(color: ThemeColorName, radius: RadiusName): string;
+/**
+ * Renders a notification card with optional icon, title, body content,
+ * loading state, and close button. Uses ARIA live regions for accessibility.
+ *
+ * The notification displays one of three visual states for the left column:
+ * - A loading spinner when `loading` is `true`
+ * - A custom icon when `icon` is provided
+ * - A colored accent bar as a fallback
+ *
+ * @param options - Configuration options for the notification.
+ * @param children - Content nodes rendered inside the notification body.
+ * @returns A renderable notification section element.
+ *
+ * @example
+ * ```typescript
+ * // Basic notification with title
+ * Notification(
+ *   { title: html.strong('Upload complete'), color: 'success' },
+ *   'Your file has been uploaded successfully.'
+ * )
+ *
+ * // Notification with icon and close button
+ * Notification(
+ *   {
+ *     icon: 'material-symbols:info-outline',
+ *     withCloseButton: true,
+ *     onClose: () => console.log('closed'),
+ *   },
+ *   'A new version is available.'
+ * )
+ *
+ * // Loading notification
+ * Notification(
+ *   { loading: true, title: html.span('Processing...') },
+ *   'Please wait while we process your request.'
+ * )
+ * ```
+ */
 export declare function Notification({ loading, withCloseButton, withBorder, color, radius, title, icon, onClose, class: cls, }?: NotificationOptions, ...children: TNode[]): Renderable;

package/dist/types/components/misc/style-portal.d.ts

@@ -1,10 +1,40 @@
 import { Renderable, Value } from '@tempots/dom';
+/**
+ * Configuration options for the {@link StylePortal} component.
+ */
 export type StylePortalOptions = {
+    /**
+     * Optional `id` attribute for the injected `<style>` element, useful for
+     * deduplication or later removal.
+     */
     id?: Value<string>;
+    /**
+     * The CSS content to inject. Supports reactive values so styles update
+     * dynamically when the value changes.
+     */
     css: Value<string>;
 };
 /**
- * Injects a <style> tag with the provided CSS into <head> via Portal.
+ * Injects a `<style>` tag with the provided CSS into `<head>` via a Portal.
  * Ensures declarative, SSR/SSG-friendly styling without imperative DOM APIs.
+ * When the `css` value is reactive, the style content updates automatically.
+ *
+ * @param options - Configuration for the style element.
+ * @returns A renderable that portals a `<style>` element into `<head>`.
+ *
+ * @example
+ * ```typescript
+ * // Inject static CSS
+ * StylePortal({
+ *   id: 'custom-theme',
+ *   css: ':root { --accent: #3b82f6; }',
+ * })
+ *
+ * // Inject reactive CSS that updates with a signal
+ * const accentColor = prop('#3b82f6')
+ * StylePortal({
+ *   css: accentColor.map(color => `:root { --accent: ${color}; }`),
+ * })
+ * ```
  */
 export declare const StylePortal: ({ id, css }: StylePortalOptions) => Renderable;

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;