@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/components/data/calendar.d.ts

@@ -0,0 +1,107 @@
+import { Value, type Renderable } from '@tempots/dom';
+import { ControlSize } from '../theme';
+import { ThemeColorName } from '../../tokens';
+import type { PlainDate } from '../../temporal/types';
+/**
+ * Configuration options for the {@link Calendar} component.
+ * Uses Temporal `PlainDate` for date values — no time or timezone concerns.
+ */
+export interface CalendarOptions {
+    /** The currently selected date. */
+    value?: Value<PlainDate | null>;
+    /** Callback invoked when a date is selected. */
+    onSelect?: (date: PlainDate) => void;
+    /**
+     * Predicate that returns `true` if the given date should be disabled (unselectable).
+     * Replaces min/max — use e.g. `d => PlainDate.compare(d, minDate) < 0` for range constraints.
+     */
+    isDateDisabled?: (date: PlainDate) => boolean;
+    /** Theme color for selected and today highlights. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Visual size of the calendar. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Whether the calendar is disabled. @default false */
+    disabled?: Value<boolean>;
+    /**
+     * The day the week starts on.
+     * 0 = Sunday, 1 = Monday, etc.
+     * @default 0
+     */
+    weekStartsOn?: number;
+}
+/**
+ * Configuration options for the {@link DateCalendar} component.
+ * Convenience wrapper that uses JavaScript `Date` objects.
+ */
+export interface DateCalendarOptions {
+    /** The currently selected date (year, month, day). */
+    value?: Value<Date | null>;
+    /** Callback invoked when a date is selected. */
+    onSelect?: (date: Date) => void;
+    /**
+     * Predicate that returns `true` if the given date should be disabled (unselectable).
+     * Replaces min/max — use e.g. `d => d < minDate || d > maxDate` for range constraints.
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Theme color for selected and today highlights. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Visual size of the calendar. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Whether the calendar is disabled. @default false */
+    disabled?: Value<boolean>;
+    /**
+     * The day the week starts on.
+     * 0 = Sunday, 1 = Monday, etc.
+     * @default 0
+     */
+    weekStartsOn?: number;
+}
+/**
+ * A calendar component for date selection with month/year navigation.
+ *
+ * Uses Temporal `PlainDate` internally — a date-only type with no time or
+ * timezone concerns, 1-based months, and proper date arithmetic.
+ *
+ * Renders a full month grid with day-of-week headers, previous/next month
+ * navigation, and a flexible `isDateDisabled` predicate for controlling which
+ * dates are selectable. The calendar highlights the currently selected date
+ * and today's date. Navigation buttons allow moving between months and years.
+ *
+ * @param options - Configuration for the calendar
+ * @returns A calendar element with date selection capability
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { Calendar, PlainDate } from '@tempots/beatui'
+ *
+ * const date = prop<PlainDate | null>(null)
+ * Calendar({
+ *   value: date,
+ *   onSelect: date.set,
+ * })
+ * ```
+ */
+export declare function Calendar(options?: CalendarOptions): Renderable;
+/**
+ * A convenience calendar wrapper that uses JavaScript `Date` objects.
+ *
+ * Accepts and fires `Date` values, converting to/from `PlainDate` internally.
+ * Use this when integrating with existing `Date`-based code.
+ *
+ * @param options - Configuration for the calendar (uses `Date` objects)
+ * @returns A calendar element with date selection capability
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { DateCalendar } from '@tempots/beatui'
+ *
+ * const date = prop<Date | null>(new Date())
+ * DateCalendar({
+ *   value: date,
+ *   onSelect: date.set,
+ * })
+ * ```
+ */
+export declare function DateCalendar(options?: DateCalendarOptions): Renderable;

package/dist/types/components/data/history-timeline.d.ts

@@ -0,0 +1,35 @@
+import { TNode, Value } from '@tempots/dom';
+export interface HistoryEntry {
+    id: string;
+    /** Action label (e.g., "DELETED", "EDITED", "CREATED") */
+    action: string;
+    /** Color for the action label and timeline dot */
+    actionColor: string;
+    /** Icon for the timeline dot */
+    icon: string;
+    /** Target name */
+    target: string;
+    /** Icon for the target */
+    targetIcon: string;
+    /** Actor info */
+    actor: {
+        name: string;
+        initials: string;
+    };
+    /** Timestamp string */
+    time: string;
+    /** Detail text */
+    detail: string;
+    /** Whether this entry can be restored */
+    restorable?: boolean;
+    /** Callback for restore action */
+    onRestore?: () => void;
+}
+export interface HistoryTimelineOptions {
+    entries: Value<HistoryEntry[]>;
+    filters?: {
+        value: string;
+        label: string;
+    }[];
+}
+export declare function HistoryTimeline(options: HistoryTimelineOptions): TNode;

package/dist/types/components/data/icon-badge.d.ts

@@ -0,0 +1,14 @@
+import { TNode, Value } from '@tempots/dom';
+import { IconOptions } from './icon';
+import { ThemeColorName } from '../../tokens';
+export interface IconBadgeOptions extends IconOptions {
+    /** Show a dot indicator */
+    indicator?: Value<boolean>;
+    /** Show a count badge. If > 0, displays the number. */
+    count?: Value<number>;
+    /** Max count to display (e.g., 9 shows "9+") */
+    maxCount?: Value<number>;
+    /** Color of the indicator badge */
+    indicatorColor?: Value<ThemeColorName>;
+}
+export declare function IconBadge(options: IconBadgeOptions): TNode;

package/dist/types/components/data/icon.d.ts

@@ -3,21 +3,72 @@ import { IconSize } from '../theme';
 import { ThemeColorName } from '../../tokens';
 import { ForegroundTone } from '../theme/style-utils';
 export declare const isIndexedDBAvailable: boolean;
+/**
+ * Stores an icon SVG string in the local cache (IndexedDB or in-memory fallback).
+ *
+ * @param id - The icon identifier (e.g., `'mdi/home'`)
+ * @param svgString - The raw SVG markup to cache
+ */
 export declare function storeIconLocally(id: string, svgString: string): Promise<void>;
+/**
+ * Retrieves a cached icon SVG string from local storage (IndexedDB or in-memory fallback).
+ *
+ * @param id - The icon identifier (e.g., `'mdi/home'`)
+ * @returns The cached SVG string, or `null` if not found
+ */
 export declare function getIconLocally(id: string): Promise<string | null>;
+/**
+ * Configuration options for the {@link Icon} component.
+ */
 export interface IconOptions {
+    /** Icon name in Iconify format (e.g., `'mdi:home'`, `'line-md:loading-twotone-loop'`). */
     icon: Value<string>;
+    /** Size of the icon. @default 'md' */
     size?: Value<IconSize>;
+    /** Theme color applied to the icon. Uses foreground color values. */
     color?: Value<ThemeColorName>;
+    /** Accessible title for informative icons. Also sets the tooltip. */
     title?: Value<string | undefined>;
     /**
-     * Whether this icon is decorative (hidden from screen readers) or informative.
-     * - 'decorative': Icon is purely visual, hidden from screen readers with aria-hidden="true"
-     * - 'informative': Icon conveys meaning, gets aria-label and role="img"
-     * - 'auto': Automatically determined based on presence of title prop
+     * Accessibility mode for the icon.
+     * - `'decorative'`: Hidden from screen readers with `aria-hidden="true"`
+     * - `'informative'`: Gets `aria-label` and `role="img"` for screen readers
+     * - `'auto'`: Determined by the presence of a `title` prop
      * @default 'auto'
      */
     accessibility?: Value<'decorative' | 'informative' | 'auto'>;
+    /** Foreground color tone: `'solid'` for vibrant or `'soft'` for muted. @default 'solid' */
     tone?: Value<ForegroundTone>;
 }
+/**
+ * Renders an SVG icon from the Iconify icon library with lazy-loading and caching.
+ *
+ * Icons are fetched from the Iconify API on first use and cached in IndexedDB
+ * (with an in-memory fallback) for subsequent loads. The icon is only loaded when
+ * it enters the viewport (`WhenInViewport`), preventing unnecessary network requests.
+ *
+ * The component handles three states: pending (spinning placeholder), success (rendered SVG),
+ * and failure (error indicator). Accessibility is configurable: decorative icons are hidden
+ * from screen readers, while informative icons receive proper ARIA attributes.
+ *
+ * @param options - Configuration for icon name, size, color, and accessibility
+ * @param children - Additional child nodes appended to the icon container
+ * @returns A span element containing the rendered icon
+ *
+ * @example
+ * ```typescript
+ * Icon({ icon: 'mdi:home', size: 'lg', color: 'primary' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Informative icon with accessible label
+ * Icon({
+ *   icon: 'mdi:alert',
+ *   color: 'warning',
+ *   title: 'Warning: unsaved changes',
+ *   accessibility: 'informative'
+ * })
+ * ```
+ */
 export declare function Icon({ icon, size, color, title, accessibility, tone, }: IconOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

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

@@ -1,6 +1,15 @@
+export * from './avatar';
+export * from './calendar';
+export * from './range-calendar';
+export * from './avatar-group';
 export * from './badge';
+export * from './history-timeline';
 export * from './icon';
+export * from './icon-badge';
 export * from './page-drop-zone';
+export * from './presence-overlay';
+export * from './progress-bar';
+export * from './skeleton';
 export * from './table';
 export * from './tag';
 export * from './unstyled-drop-zone';

package/dist/types/components/data/page-drop-zone.d.ts

@@ -1,34 +1,87 @@
 import { TNode, Value, Signal } from '@tempots/dom';
+/**
+ * Configuration options for the {@link PageDropZone} component.
+ */
 export type PageDropZoneOptions = {
+    /**
+     * Callback invoked when valid files are dropped or selected via the file picker.
+     * The `via` parameter indicates whether files came from drag-and-drop or the
+     * click-triggered file dialog.
+     */
     onChange: (files: File[], via: 'dragdrop' | 'click') => void;
+    /**
+     * MIME type filter for accepted files (e.g., `'image/*'`, `'application/pdf'`).
+     * Files that do not match are filtered out and reported via `onInvalidSelection`.
+     * @default '*\/*'
+     */
     accept?: Value<string>;
+    /**
+     * Render function for overlay content shown while files are being dragged
+     * over the page. Receives the reactive file signal. Only rendered when
+     * `isDragging` is `true`.
+     */
     onDragContent?: (options: {
         files: Signal<File[]>;
     }) => TNode;
+    /**
+     * Render function for persistent content. Receives reactive drag state,
+     * file list, and a function to programmatically open the file picker.
+     */
     content?: (options: {
+        /** Reactive signal that is `true` while files are being dragged over the page. */
         isDragging: Signal<boolean>;
+        /** Reactive signal containing the current file list. */
         files: Signal<File[]>;
+        /** Opens the native file picker dialog programmatically. */
         selectFiles: () => void;
     }) => TNode;
+    /**
+     * Callback invoked when dropped files do not match the `accept` filter.
+     * Receives the full list of dropped files (including invalid ones).
+     */
     onInvalidSelection?: (files: File[]) => void;
+    /**
+     * Whether the drop zone is disabled. Disabled zones ignore all drag events.
+     * @default false
+     */
     disabled?: Value<boolean>;
 };
 /**
  * Detects filesystem drag-and-drop events at the page/document level.
  *
- * This component listens for drag events at the document level and provides
- * reactive state about drag operations. It can optionally render an overlay
- * when files are being dragged over the page.
+ * Unlike {@link UnstyledDropZone} which scopes drag events to a specific element,
+ * `PageDropZone` listens for drag events on the entire `document`, making it
+ * ideal for full-page drop targets. It uses a drag counter to correctly track
+ * nested `dragenter`/`dragleave` events, and automatically filters dropped
+ * files against the `accept` MIME type pattern.
+ *
+ * The component provides two render slots:
+ * - `onDragContent` - Overlay shown only while files are being dragged over the page
+ * - `content` - Persistent content with reactive drag state and file selection utilities
+ *
+ * Document event listeners are automatically cleaned up when the component is disposed.
+ *
+ * @param options - Configuration options for the page drop zone.
+ * @returns A renderable fragment containing the hidden file input, optional drag
+ *   overlay, and persistent content.
  *
  * @example
  * ```typescript
+ * // Full-page drop zone with overlay and content
  * PageDropZone({
- *   onChange: (files) => console.log('Files dropped:', files),
- *   content: ({ isDragging }) =>
+ *   accept: 'image/*',
+ *   onChange: (files, via) => console.log('Files:', files, 'via:', via),
+ *   onInvalidSelection: (files) => console.warn('Invalid files:', files),
+ *   onDragContent: () =>
+ *     html.div(
+ *       attr.class('overlay'),
+ *       'Drop images here'
+ *     ),
+ *   content: ({ isDragging, files, selectFiles }) =>
  *     html.div(
- *       attr.class('fixed inset-0 bg-black/50 flex items-center justify-center'),
- *       html.div('Drop files here')
- *     )
+ *       html.button(on.click(selectFiles), 'Browse files'),
+ *       files.map(f => html.div(`${f.length} file(s) selected`))
+ *     ),
  * })
  * ```
  */

package/dist/types/components/data/presence-overlay.d.ts

@@ -0,0 +1,26 @@
+import { TNode } from '@tempots/dom';
+export interface PresenceSelection {
+    /** Author display name */
+    author: string;
+    /** Author's presence color (hex) */
+    color: string;
+}
+/**
+ * PresenceCursor renders a cursor indicator with an author name tag.
+ * Used to show collaborative editing cursors.
+ */
+export declare function PresenceCursor(options: {
+    author: string;
+    color: string;
+}): TNode;
+/**
+ * PresenceHighlight wraps text with a colored selection highlight.
+ * Used to show collaborative editing selections.
+ */
+export declare function PresenceHighlight(options: {
+    color: string;
+}, ...children: TNode[]): TNode;
+/**
+ * PresenceSelectionMark wraps text with both highlight and cursor.
+ */
+export declare function PresenceSelectionMark(options: PresenceSelection, ...children: TNode[]): TNode;

package/dist/types/components/data/progress-bar.d.ts

@@ -0,0 +1,81 @@
+import { TNode, Value } from '@tempots/dom';
+import { ThemeColorName } from '../../tokens';
+import { RadiusName } from '../../tokens/radius';
+import { ExtendedColor } from '../theme/style-utils';
+/**
+ * Configuration options for the {@link ProgressBar} component.
+ */
+export interface ProgressBarOptions {
+    /** Current progress value (0 to max). @default 0 */
+    value?: Value<number>;
+    /** Maximum value for the progress bar. @default 100 */
+    max?: Value<number>;
+    /** Visual size variant. @default 'md' */
+    size?: Value<'sm' | 'md' | 'lg'>;
+    /** Theme color for the progress fill. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Whether to show indeterminate loading animation. @default false */
+    indeterminate?: Value<boolean>;
+    /** Whether to show percentage text label. @default false */
+    showLabel?: Value<boolean>;
+    /** Border radius preset for the progress bar. @default 'full' */
+    roundedness?: Value<RadiusName>;
+}
+/**
+ * Generates CSS class names for the progress bar based on size and indeterminate state.
+ *
+ * @param size - Size variant (sm, md, lg)
+ * @param indeterminate - Whether in indeterminate state
+ * @param roundedness - Border radius preset
+ * @returns Space-separated CSS class string
+ */
+export declare function generateProgressBarClasses(size: 'sm' | 'md' | 'lg', indeterminate: boolean, roundedness: RadiusName): string;
+/**
+ * Generates inline CSS custom properties for progress bar theming based on color.
+ * Sets fill and track colors for both light and dark modes.
+ *
+ * @param color - The theme color
+ * @returns Semicolon-separated CSS custom property declarations
+ */
+export declare function generateProgressBarStyles(color: ExtendedColor): string;
+/**
+ * A horizontal progress bar component that shows completion status.
+ * Supports determinate (with value) and indeterminate (loading) states,
+ * configurable sizing, theming, and optional percentage labels.
+ *
+ * Uses ARIA progressbar role with proper attributes for accessibility.
+ *
+ * @param options - Configuration for value, size, color, and display options
+ * @returns A styled progress bar element with track and fill
+ *
+ * @example
+ * ```typescript
+ * // Basic determinate progress bar
+ * ProgressBar({ value: 65, max: 100 })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With label showing percentage
+ * ProgressBar({ value: 75, showLabel: true, color: 'success' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Indeterminate loading state
+ * ProgressBar({ indeterminate: true, color: 'primary' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom sizing and color
+ * ProgressBar({
+ *   value: 42,
+ *   max: 100,
+ *   size: 'lg',
+ *   color: 'warning',
+ *   roundedness: 'sm'
+ * })
+ * ```
+ */
+export declare function ProgressBar({ value, max, size, color, indeterminate, showLabel, roundedness, }: ProgressBarOptions): TNode;

package/dist/types/components/data/range-calendar.d.ts

@@ -0,0 +1,104 @@
+import { Value, type Renderable } from '@tempots/dom';
+import { ControlSize } from '../theme';
+import { ThemeColorName } from '../../tokens';
+import type { PlainDate } from '../../temporal/types';
+/**
+ * Configuration options for the {@link RangeCalendar} component.
+ * Uses Temporal `PlainDate` for date values — no time or timezone concerns.
+ */
+export interface RangeCalendarOptions {
+    /** The currently selected date range as `[start, end]`. */
+    value?: Value<[PlainDate, PlainDate] | null>;
+    /** Callback invoked when a complete range is selected. */
+    onChange?: (range: [PlainDate, PlainDate]) => void;
+    /**
+     * Predicate that returns `true` if the given date should be disabled (unselectable).
+     */
+    isDateDisabled?: (date: PlainDate) => boolean;
+    /** Theme color for selected and today highlights. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Visual size of the calendar. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Whether the calendar is disabled. @default false */
+    disabled?: Value<boolean>;
+    /**
+     * The day the week starts on.
+     * 0 = Sunday, 1 = Monday, etc.
+     * @default 0
+     */
+    weekStartsOn?: number;
+}
+/**
+ * Configuration options for the {@link DateRangeCalendar} component.
+ * Convenience wrapper that uses JavaScript `Date` objects.
+ */
+export interface DateRangeCalendarOptions {
+    /** The currently selected date range as `[start, end]`. */
+    value?: Value<[Date, Date] | null>;
+    /** Callback invoked when a complete range is selected. */
+    onChange?: (range: [Date, Date]) => void;
+    /**
+     * Predicate that returns `true` if the given date should be disabled (unselectable).
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Theme color for selected and today highlights. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Visual size of the calendar. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Whether the calendar is disabled. @default false */
+    disabled?: Value<boolean>;
+    /**
+     * The day the week starts on.
+     * 0 = Sunday, 1 = Monday, etc.
+     * @default 0
+     */
+    weekStartsOn?: number;
+}
+/**
+ * A calendar component for date range selection with hover preview.
+ *
+ * Uses Temporal `PlainDate` internally — a date-only type with no time or
+ * timezone concerns, 1-based months, and proper date arithmetic.
+ *
+ * Users click twice to select a range: the first click sets the start date,
+ * hovering shows a preview, and the second click completes the range.
+ * The range is auto-sorted so start is always before end.
+ *
+ * @param options - Configuration for the range calendar
+ * @returns A calendar element with date range selection capability
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { RangeCalendar, PlainDate } from '@tempots/beatui'
+ *
+ * const range = prop<[PlainDate, PlainDate] | null>(null)
+ * RangeCalendar({
+ *   value: range,
+ *   onChange: range.set,
+ * })
+ * ```
+ */
+export declare function RangeCalendar(options?: RangeCalendarOptions): Renderable;
+/**
+ * A convenience range calendar wrapper that uses JavaScript `Date` objects.
+ *
+ * Accepts and fires `Date` values, converting to/from `PlainDate` internally.
+ * Use this when integrating with existing `Date`-based code.
+ *
+ * @param options - Configuration for the range calendar (uses `Date` objects)
+ * @returns A calendar element with date range selection capability
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { DateRangeCalendar } from '@tempots/beatui'
+ *
+ * const range = prop<[Date, Date] | null>(null)
+ * DateRangeCalendar({
+ *   value: range,
+ *   onChange: range.set,
+ * })
+ * ```
+ */
+export declare function DateRangeCalendar(options?: DateRangeCalendarOptions): Renderable;

package/dist/types/components/data/skeleton.d.ts

@@ -0,0 +1,70 @@
+import { TNode, Value } from '@tempots/dom';
+import { RadiusName } from '../../tokens/radius';
+/**
+ * Configuration options for the {@link Skeleton} component.
+ */
+export interface SkeletonOptions {
+    /** Visual style variant for the skeleton shape. @default 'text' */
+    variant?: Value<'text' | 'rect' | 'circle'>;
+    /** CSS width value (e.g., '100px', '50%'). Default is 100% for text/rect. */
+    width?: Value<string | undefined>;
+    /** CSS height value (e.g., '100px', '2rem'). Default varies by variant. */
+    height?: Value<string | undefined>;
+    /** Number of text lines to render (only applies to text variant). @default 1 */
+    lines?: Value<number>;
+    /** Whether to show the shimmer animation. @default true */
+    animate?: Value<boolean>;
+    /** Border radius preset for the skeleton. @default 'sm' */
+    roundedness?: Value<RadiusName>;
+}
+/**
+ * Generates CSS class names for the skeleton based on variant and animation state.
+ *
+ * @param variant - Shape variant (text, rect, or circle)
+ * @param animate - Whether shimmer animation is enabled
+ * @param roundedness - Border radius preset
+ * @returns Space-separated CSS class string
+ */
+export declare function generateSkeletonClasses(variant: 'text' | 'rect' | 'circle', animate: boolean, roundedness: RadiusName): string;
+/**
+ * Generates inline CSS styles for the skeleton based on width and height.
+ *
+ * @param width - CSS width value
+ * @param height - CSS height value
+ * @param variant - Shape variant
+ * @returns Semicolon-separated CSS property declarations
+ */
+export declare function generateSkeletonStyles(width: string | undefined, height: string | undefined, variant: 'text' | 'rect' | 'circle'): string;
+/**
+ * A loading placeholder component that shows a shimmer animation.
+ * Supports text (single or multi-line), rectangular, and circular variants.
+ * Used to indicate that content is loading while maintaining layout structure.
+ *
+ * @param options - Configuration for variant, dimensions, animation, and shape
+ * @returns A styled div element with shimmer animation
+ *
+ * @example
+ * ```typescript
+ * // Single line text skeleton
+ * Skeleton({ variant: 'text' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-line text skeleton
+ * Skeleton({ variant: 'text', lines: 3 })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Circle skeleton for avatar
+ * Skeleton({ variant: 'circle', width: '48px', height: '48px', roundedness: 'full' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Rectangle skeleton with custom dimensions
+ * Skeleton({ variant: 'rect', width: '200px', height: '120px', roundedness: 'md' })
+ * ```
+ */
+export declare function Skeleton({ variant, width, height, lines, animate, roundedness, }: SkeletonOptions): TNode;