@tempots/beatui 0.82.0 → 0.83.0

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

@@ -1,4 +1,85 @@
 import { Renderable, Value } from '@tempots/dom';
+/**
+ * Attaches a reactive value to the nearest parent DOM element as an
+ * "expando" property (a dynamic property on the element object). This
+ * allows passing arbitrary typed data through the DOM without relying
+ * on `data-*` attributes or custom events.
+ *
+ * The value is kept in sync: whenever the reactive `value` changes, the
+ * expando property on the element is updated. The property is keyed by
+ * an internal prefix plus the provided `name`.
+ *
+ * @typeParam T - The type of the value to store on the element.
+ * @param name - A unique name for the expando property.
+ * @param value - A reactive or static value to bind to the element.
+ * @returns A renderable that, when mounted, attaches the expando property.
+ *
+ * @example
+ * ```typescript
+ * // Attach a typed value to a list item
+ * const items = [{ id: 1, label: 'Apple' }, { id: 2, label: 'Banana' }]
+ *
+ * html.ul(
+ *   ...items.map(item =>
+ *     html.li(
+ *       Expando('item', item),
+ *       on.click(emitExpando('item', (clicked: typeof item) => {
+ *         console.log('Selected:', clicked.label)
+ *       })),
+ *       item.label
+ *     )
+ *   )
+ * )
+ * ```
+ */
 export declare const Expando: <T>(name: string, value: Value<T>) => Renderable;
+/**
+ * Creates an event handler that reads an expando property from `event.target`
+ * and passes it to the provided callback. Use this with {@link Expando} to
+ * retrieve typed data from DOM event targets.
+ *
+ * @typeParam T - The type of the expando value to retrieve.
+ * @param name - The expando property name (must match the name used in {@link Expando}).
+ * @param fn - Callback receiving the typed expando value.
+ * @returns An event handler function suitable for use with `on.*` bindings.
+ *
+ * @example
+ * ```typescript
+ * html.button(
+ *   Expando('id', 42),
+ *   on.click(emitExpando('id', (id: number) => {
+ *     console.log('Clicked item with id:', id)
+ *   })),
+ *   'Click me'
+ * )
+ * ```
+ */
 export declare const emitExpando: <T>(name: string, fn: (text: T) => void) => (event: Event) => void;
+/**
+ * Creates an event handler that reads an expando property from the currently
+ * selected `<option>` element within a `<select>`. Use this with {@link Expando}
+ * on individual `<option>` elements to retrieve typed data when the selection changes.
+ *
+ * @typeParam T - The type of the expando value stored on each option.
+ * @param name - The expando property name (must match the name used in {@link Expando}).
+ * @param fn - Callback receiving the typed expando value from the selected option.
+ * @returns An event handler function suitable for use with `on.change` on a `<select>`.
+ *
+ * @example
+ * ```typescript
+ * const fruits = [
+ *   { id: 1, name: 'Apple' },
+ *   { id: 2, name: 'Banana' },
+ * ]
+ *
+ * html.select(
+ *   on.change(emitOptionExpando('fruit', (fruit: typeof fruits[0]) => {
+ *     console.log('Selected:', fruit.name)
+ *   })),
+ *   ...fruits.map(fruit =>
+ *     html.option(Expando('fruit', fruit), fruit.name)
+ *   )
+ * )
+ * ```
+ */
 export declare const emitOptionExpando: <T>(name: string, fn: (text: T) => void) => (event: Event) => void;

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

@@ -1,8 +1,9 @@
+export * from './empty-state';
 export * from './expando';
 export * from './style-portal';
 export * from './link-portal';
 export * from './notice';
 export * from './opengraph';
 export * from './notification';
+export * from './notification-panel';
 export * from './notification-provider';
-export * from './notification';

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

@@ -1,11 +1,49 @@
 import { Renderable, Value } from '@tempots/dom';
+/**
+ * Configuration options for the {@link LinkPortal} component.
+ */
 export type LinkPortalOptions = {
+    /**
+     * Optional `id` attribute for the injected `<link>` element, useful for
+     * deduplication or later removal.
+     */
     id?: Value<string>;
+    /**
+     * The URL of the linked resource (e.g., a stylesheet URL).
+     */
     href: Value<string>;
+    /**
+     * The relationship type of the linked resource.
+     * @default 'stylesheet'
+     */
     rel?: Value<string>;
 };
 /**
- * Injects a <link rel="stylesheet"> tag with the provided href into <head> via Portal.
- * Keeps styling SSR/SSG-friendly while leveraging browser caching of CSS assets.
+ * Injects a `<link>` tag into `<head>` via a Portal. By default, the `rel`
+ * attribute is set to `"stylesheet"`, making this ideal for dynamically loading
+ * CSS files. The portal approach keeps styling SSR/SSG-friendly while
+ * leveraging browser caching of CSS assets.
+ *
+ * @param options - Configuration for the link element.
+ * @returns A renderable that portals a `<link>` element into `<head>`.
+ *
+ * @example
+ * ```typescript
+ * // Load an external stylesheet
+ * LinkPortal({ href: 'https://cdn.example.com/styles.css' })
+ *
+ * // Load a font with a custom id for deduplication
+ * LinkPortal({
+ *   id: 'google-fonts',
+ *   href: 'https://fonts.googleapis.com/css2?family=Inter',
+ *   rel: 'stylesheet',
+ * })
+ *
+ * // Preconnect to a CDN
+ * LinkPortal({
+ *   href: 'https://cdn.example.com',
+ *   rel: 'preconnect',
+ * })
+ * ```
  */
 export declare const LinkPortal: ({ id, href, rel, }: LinkPortalOptions) => Renderable;

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;