@tempots/beatui 0.82.1 → 0.83.3

package/dist/types/components/beatui.d.ts

@@ -1,12 +1,47 @@
 import { TNode } from '@tempots/dom';
 import { AppearancePreference } from './theme';
 import { NotificationViewportPosition } from './misc/notification-provider';
+/** Configuration options for the {@link BeatUI} root provider. */
 export type BeatUIOptions = {
+    /** Whether to load and provide the authentication i18n translations. @default false */
     includeAuthI18n?: boolean;
+    /** Whether to enable light/dark appearance toggling. @default true */
     enableAppearance?: boolean;
+    /** The initial appearance preference when appearance is enabled. @default 'system' */
     defaultAppearance?: AppearancePreference;
+    /** localStorage key used to persist the appearance preference. @default 'bui-appearance' */
     appearancePreferenceKey?: string;
+    /** Whether to include the notification system provider and viewport. @default true */
     includeNotifications?: boolean;
+    /** Position of the notification viewport on screen. @default 'bottom-end' */
     notificationPosition?: NotificationViewportPosition;
 };
+/**
+ * Root provider component that initializes all BeatUI subsystems: routing,
+ * locale, i18n, theming, and notifications. Wrap your application with this
+ * component to enable all BeatUI features.
+ *
+ * @param options - Configuration for which subsystems to enable
+ * @param children - The application content
+ * @returns A provider tree wrapping the children
+ *
+ * @example
+ * ```typescript
+ * import { BeatUI } from '@tempots/beatui'
+ *
+ * BeatUI(
+ *   { enableAppearance: true, includeNotifications: true },
+ *   html.div('My Application')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With auth i18n support
+ * BeatUI(
+ *   { includeAuthI18n: true, defaultAppearance: 'dark' },
+ *   AppLayout({ children: Router({ ... }) })
+ * )
+ * ```
+ */
 export declare function BeatUI({ includeAuthI18n, enableAppearance, defaultAppearance, appearancePreferenceKey, includeNotifications, notificationPosition, }: BeatUIOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/button/button.d.ts

@@ -3,23 +3,84 @@ import { ControlSize, ButtonVariant } from '../theme';
 import { ThemeColorName } from '../../tokens';
 import { ExtendedColor } from '../theme/style-utils';
 import { RadiusName } from '../../tokens/radius';
+/** Configuration options for the {@link Button} component. */
 export interface ButtonOptions {
+    /** The HTML button type attribute. @default 'button' */
     type?: Value<'submit' | 'reset' | 'button'>;
+    /** Whether the button is disabled and non-interactive. @default false */
     disabled?: Value<boolean>;
+    /** Whether to show a loading spinner and disable interaction. @default false */
     loading?: Value<boolean>;
+    /** Visual style variant controlling background, text, and border colors. @default 'filled' */
     variant?: Value<ButtonVariant>;
+    /** Size affecting padding, font size, and icon dimensions. @default 'md' */
     size?: Value<ControlSize>;
+    /** Theme color for the button's color scheme. @default 'base' */
     color?: Value<ThemeColorName>;
+    /** Border radius preset. @default 'sm' */
     roundedness?: Value<RadiusName>;
+    /** Callback invoked when the button is clicked. */
     onClick?: () => void;
+    /** Whether the button takes the full width of its container. @default false */
     fullWidth?: Value<boolean>;
     /**
      * Whether to stop event propagation on click.
      * When true (default), prevents the click event from bubbling up.
      * Set to false if you need parent elements to receive click events (e.g., for Flyout triggers).
+     * @default true
      */
     stopPropagation?: boolean;
 }
+/**
+ * Generates CSS class names for a button based on size, roundedness, loading state, and width.
+ *
+ * @param size - Control size for padding and text
+ * @param roundedness - Border radius preset name
+ * @param loading - Whether loading spinner is shown
+ * @param fullWidth - Whether button is full-width
+ * @returns Space-separated CSS class string
+ */
 export declare function generateButtonClasses(size: ControlSize, roundedness: RadiusName, loading: boolean, fullWidth: boolean): string;
+/**
+ * Generates inline CSS custom properties for button theming based on variant, color, and disabled state.
+ * Sets background, text, border, hover, and text-shadow values for both light and dark modes.
+ *
+ * @param variant - The visual style variant
+ * @param color - The theme color
+ * @param disabled - Whether the button is disabled (suppresses hover styles)
+ * @returns Semicolon-separated CSS custom property declarations
+ */
 export declare function generateButtonStyles(variant: ButtonVariant, color: ExtendedColor, disabled: boolean): string;
+/**
+ * An interactive button component with theme-aware styling, loading state, and accessibility support.
+ *
+ * When `loading` is true, the button content is replaced with a spinning icon and the button is
+ * disabled. The button preserves its dimensions during loading to prevent layout shift.
+ * Screen readers are notified of the loading state via `aria-busy` and `aria-label`.
+ *
+ * For submit buttons (`type: 'submit'`), the default browser form submission behavior is preserved.
+ * For other button types, `preventDefault()` is called automatically.
+ *
+ * @param options - Configuration for appearance, behavior, and state
+ * @param children - Content to display inside the button (text, icons, etc.)
+ * @returns A styled button element
+ *
+ * @example
+ * ```typescript
+ * Button(
+ *   { variant: 'filled', color: 'primary', onClick: () => console.log('clicked') },
+ *   'Save Changes'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Button with loading state
+ * const saving = prop(false)
+ * Button(
+ *   { variant: 'filled', color: 'success', loading: saving, onClick: handleSave },
+ *   'Submit'
+ * )
+ * ```
+ */
 export declare function Button({ type, disabled, loading, variant, size, color, roundedness, onClick, fullWidth, stopPropagation, }: ButtonOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/button/close-button.d.ts

@@ -2,14 +2,45 @@ import { Renderable, TNode, Value } from '@tempots/dom';
 import { ControlSize } from '../theme';
 import { ThemeColorName } from '../../tokens';
 import { RadiusName } from '../../tokens/radius';
+/** Configuration options for the {@link CloseButton} component. */
 export type CloseButtonOptions = {
+    /** Size of the close button icon and hit target. @default 'sm' */
     size?: Value<ControlSize>;
+    /** Icon name from Iconify. @default 'line-md:close' */
     icon?: Value<string>;
+    /** Whether the button is disabled. */
     disabled?: Value<boolean>;
+    /** Border radius of the button. @default 'full' */
     roundedness?: Value<RadiusName>;
+    /** Theme color for the icon. @default 'base' */
     color?: Value<ThemeColorName>;
+    /** Callback invoked when the button is clicked. */
     onClick?: () => void;
-    /** Optional localized label for screen readers; defaults to t.$.closeModal */
+    /** Localized label for screen readers. Defaults to the i18n `closeModal` translation. */
     label?: Value<string>;
 };
+/**
+ * A small icon-only button for dismissing modals, drawers, notifications, and tags.
+ * Renders as a text-variant button with a close icon (X) and proper ARIA labeling
+ * for screen reader accessibility.
+ *
+ * @param options - Configuration for size, icon, and behavior
+ * @param children - Additional child nodes appended to the button
+ * @returns A Renderable button element
+ *
+ * @example
+ * ```typescript
+ * CloseButton({ onClick: () => modal.close() })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom icon and label
+ * CloseButton({
+ *   icon: 'mdi:close-circle',
+ *   label: 'Dismiss notification',
+ *   onClick: handleDismiss
+ * })
+ * ```
+ */
 export declare function CloseButton({ size, icon, disabled, roundedness, color, onClick, label, }: CloseButtonOptions, ...children: TNode[]): Renderable;

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

@@ -1,2 +1,4 @@
 export * from './button';
 export * from './close-button';
+export * from './toggle-button';
+export * from './toggle-button-group';

package/dist/types/components/button/toggle-button-group.d.ts

@@ -0,0 +1,95 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize, ButtonVariant } from '../theme';
+import { ThemeColorName } from '../../tokens';
+import { RadiusName } from '../../tokens/radius';
+/**
+ * Describes a single item within a {@link ToggleButtonGroup}.
+ */
+export interface ToggleButtonGroupItem {
+    /** Unique key identifying this item within the group */
+    key: string;
+    /** Content rendered inside the toggle button (text, icons, or any TNode) */
+    label: TNode;
+    /** Whether this specific button is disabled. @default false */
+    disabled?: boolean;
+}
+/**
+ * Configuration options for the {@link ToggleButtonGroup} component.
+ */
+export interface ToggleButtonGroupOptions {
+    /** The toggle button items to render */
+    items: ToggleButtonGroupItem[];
+    /** Array of currently selected item keys */
+    value: Value<string[]>;
+    /** Callback invoked when the selection changes */
+    onChange?: (value: string[]) => void;
+    /**
+     * Whether multiple items can be selected simultaneously.
+     * When false, selecting an item deselects all others.
+     * @default false
+     */
+    multiple?: Value<boolean>;
+    /** Whether the entire group is disabled. @default false */
+    disabled?: Value<boolean>;
+    /** Visual style variant applied to all buttons. @default 'outline' */
+    variant?: Value<ButtonVariant>;
+    /** Size affecting padding, font size, and dimensions. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Theme color for pressed buttons. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Border radius preset for the group's outer corners. @default 'sm' */
+    roundedness?: Value<RadiusName>;
+    /**
+     * Layout orientation of the button group.
+     * @default 'horizontal'
+     */
+    orientation?: Value<'horizontal' | 'vertical'>;
+}
+/**
+ * A group container for toggle buttons that manages single or multiple
+ * selection. Buttons are visually connected with shared borders and
+ * the group's outer corners use the specified border radius.
+ *
+ * Uses `role="group"` for accessibility. In single-selection mode,
+ * selecting a button deselects all others (like a radio group).
+ * In multiple-selection mode, each button toggles independently.
+ *
+ * @param options - Configuration for the toggle button group
+ * @returns A styled group of toggle buttons
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { ToggleButtonGroup } from '@tempots/beatui'
+ *
+ * // Single selection
+ * const alignment = prop<string[]>(['left'])
+ * ToggleButtonGroup({
+ *   items: [
+ *     { key: 'left', label: 'Left' },
+ *     { key: 'center', label: 'Center' },
+ *     { key: 'right', label: 'Right' },
+ *   ],
+ *   value: alignment,
+ *   onChange: alignment.set,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple selection
+ * const formats = prop<string[]>([])
+ * ToggleButtonGroup({
+ *   items: [
+ *     { key: 'bold', label: 'B' },
+ *     { key: 'italic', label: 'I' },
+ *     { key: 'underline', label: 'U' },
+ *   ],
+ *   value: formats,
+ *   onChange: formats.set,
+ *   multiple: true,
+ *   variant: 'outline',
+ * })
+ * ```
+ */
+export declare function ToggleButtonGroup({ items, value, onChange, multiple, disabled, variant, size, color, roundedness, orientation, }: ToggleButtonGroupOptions): import("@tempots/dom").Renderable;

package/dist/types/components/button/toggle-button.d.ts

@@ -0,0 +1,60 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize, ButtonVariant } from '../theme';
+import { ThemeColorName } from '../../tokens';
+import { RadiusName } from '../../tokens/radius';
+/**
+ * Configuration options for the {@link ToggleButton} component.
+ */
+export interface ToggleButtonOptions {
+    /** Whether the button is currently pressed/active. */
+    pressed: Value<boolean>;
+    /** Callback invoked when the button is toggled. */
+    onToggle?: (pressed: boolean) => void;
+    /** Whether the button is disabled. @default false */
+    disabled?: Value<boolean>;
+    /** Visual style variant. @default 'outline' */
+    variant?: Value<ButtonVariant>;
+    /** Size affecting padding, font size, and icon dimensions. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Theme color for the pressed state. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /** Border radius preset. @default 'sm' */
+    roundedness?: Value<RadiusName>;
+    /** Whether the button takes the full width of its container. @default false */
+    fullWidth?: Value<boolean>;
+}
+/**
+ * A toggle button that can be pressed/unpressed, similar to a checkbox
+ * but styled as a button with visual feedback for the pressed state.
+ *
+ * Uses `aria-pressed` for accessibility. When pressed, the button displays
+ * a filled appearance using the specified color; when unpressed, it shows
+ * the variant's default appearance.
+ *
+ * @param options - Configuration for the toggle button
+ * @param children - Content to display inside the button
+ * @returns A styled toggle button element
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { ToggleButton } from '@tempots/beatui'
+ *
+ * const bold = prop(false)
+ * ToggleButton(
+ *   { pressed: bold, onToggle: bold.set, variant: 'outline' },
+ *   'B'
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Icon toggle
+ * const starred = prop(false)
+ * ToggleButton(
+ *   { pressed: starred, onToggle: starred.set, color: 'yellow' },
+ *   Icon({ icon: starred.map(s => s ? 'lucide:star' : 'lucide:star-off') })
+ * )
+ * ```
+ */
+export declare function ToggleButton({ pressed, onToggle, disabled, variant, size, color, roundedness, fullWidth, }: ToggleButtonOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/data/avatar-group.d.ts

@@ -0,0 +1,74 @@
+import { TNode, Value } from '@tempots/dom';
+import { ThemeColorName } from '../../tokens';
+import { AvatarSize } from './avatar';
+/**
+ * Configuration options for the {@link AvatarGroup} component.
+ */
+export interface AvatarGroupOptions {
+    /** Size of avatars in the group. @default 'md' */
+    size?: Value<AvatarSize>;
+    /** Spacing between avatars: 'tight' for overlap, 'normal' for standard gap. @default 'tight' */
+    spacing?: Value<'tight' | 'normal'>;
+}
+/**
+ * Configuration options for the {@link AvatarGroupOverflow} component.
+ */
+export interface AvatarGroupOverflowOptions {
+    /** Number to display in the overflow indicator (e.g., +5). */
+    count: Value<number>;
+    /** Size matching the avatar group. @default 'md' */
+    size?: Value<AvatarSize>;
+    /** Theme color for the overflow indicator background. @default 'base' */
+    color?: Value<ThemeColorName>;
+}
+/**
+ * Renders a container for grouping multiple Avatar components with overlapping or spaced layout.
+ *
+ * The AvatarGroup component provides a styled container for displaying multiple avatars
+ * in a row. It supports two spacing modes:
+ * - **tight**: Avatars overlap with negative margin for a compact, stacked appearance
+ * - **normal**: Avatars are spaced with standard gap
+ *
+ * The group automatically applies consistent sizing to all child avatars via CSS classes.
+ * For displaying overflow (e.g., "+5 more"), use the {@link AvatarGroupOverflow} component.
+ *
+ * @param options - Configuration for size and spacing
+ * @param children - Avatar components to display in the group
+ * @returns A div element containing the avatar group
+ *
+ * @example
+ * ```typescript
+ * AvatarGroup({ size: 'lg', spacing: 'tight' },
+ *   Avatar({ src: 'user1.jpg', name: 'Alice' }),
+ *   Avatar({ src: 'user2.jpg', name: 'Bob' }),
+ *   Avatar({ src: 'user3.jpg', name: 'Charlie' }),
+ *   AvatarGroupOverflow({ count: 5 })
+ * )
+ * ```
+ */
+export declare function AvatarGroup({ size, spacing }: AvatarGroupOptions, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Renders an overflow indicator for AvatarGroup showing the count of hidden avatars.
+ *
+ * This component displays a styled avatar-like element with a "+N" label indicating
+ * how many additional avatars are not shown in the group. It should be used as the
+ * last child of an {@link AvatarGroup}.
+ *
+ * The overflow indicator inherits the styling of the avatar group and matches the
+ * size of other avatars in the group.
+ *
+ * @param options - Configuration for count, size, and color
+ * @returns A div element styled as an avatar showing the overflow count
+ *
+ * @example
+ * ```typescript
+ * AvatarGroup({ size: 'md', spacing: 'tight' },
+ *   Avatar({ name: 'Alice' }),
+ *   Avatar({ name: 'Bob' }),
+ *   Avatar({ name: 'Charlie' }),
+ *   AvatarGroupOverflow({ count: 7, color: 'primary' })
+ * )
+ * // Displays: [A] [B] [C] [+7]
+ * ```
+ */
+export declare function AvatarGroupOverflow({ count, size, color, }: AvatarGroupOverflowOptions): import("@tempots/dom").Renderable;

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

@@ -0,0 +1,62 @@
+import { TNode, Value } from '@tempots/dom';
+import { ThemeColorName } from '../../tokens';
+/**
+ * Size options for Avatar components.
+ * Ranges from `'xs'` (24px) to `'2xl'` (96px).
+ */
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Configuration options for the {@link Avatar} component.
+ */
+export interface AvatarOptions {
+    /** Image URL for the avatar. @default undefined */
+    src?: Value<string | undefined>;
+    /** Name for generating initials fallback. @default undefined */
+    name?: Value<string | undefined>;
+    /** Icon name (Iconify format) as a fallback. @default undefined */
+    icon?: Value<string | undefined>;
+    /** Size of the avatar. @default 'md' */
+    size?: Value<AvatarSize>;
+    /** Shape variant: circle or square. @default 'circle' */
+    variant?: Value<'circle' | 'square'>;
+    /** Theme color for the avatar background. @default 'base' */
+    color?: Value<ThemeColorName>;
+    /** Whether to add a border around the avatar. @default false */
+    bordered?: Value<boolean>;
+}
+/**
+ * Renders a user avatar with image, initials, or icon fallback.
+ *
+ * The Avatar component displays user profile images with graceful fallbacks:
+ * 1. Image from `src` prop (if provided and loads successfully)
+ * 2. Initials derived from `name` prop (if image fails or is not provided)
+ * 3. Icon from `icon` prop (if provided and no name is available)
+ * 4. Default user icon (if all else fails)
+ *
+ * Supports multiple sizes, shapes (circle or square), theme colors, and optional borders.
+ * The component automatically applies the appropriate background color and text color
+ * based on the theme color and appearance mode.
+ *
+ * @param options - Configuration for image, name, icon, size, shape, color, and border
+ * @param children - Additional child nodes appended to the avatar container
+ * @returns A div element containing the rendered avatar
+ *
+ * @example
+ * ```typescript
+ * // Avatar with image
+ * Avatar({ src: 'https://example.com/avatar.jpg', name: 'John Doe', size: 'lg' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Avatar with initials fallback
+ * Avatar({ name: 'Jane Smith', color: 'primary', variant: 'square' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Avatar with icon fallback
+ * Avatar({ icon: 'mdi:account', size: 'xl', bordered: true })
+ * ```
+ */
+export declare function Avatar({ src, name, icon, size, variant, color, bordered, }: AvatarOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

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

@@ -3,14 +3,61 @@ import { ControlSize, ButtonVariant } from '../theme';
 import { ThemeColorName } from '../../tokens';
 import { ExtendedColor } from '../theme/style-utils';
 import { RadiusName } from '../../tokens/radius';
+/** Configuration options for the {@link Badge} component. */
 export interface BadgeOptions {
+    /** Visual style variant matching button variants. @default 'filled' */
     variant?: Value<ButtonVariant>;
+    /** Size of the badge affecting padding and font. @default 'md' */
     size?: Value<ControlSize>;
+    /** Theme color for the badge background and text. @default 'base' */
     color?: Value<ThemeColorName>;
+    /** Border radius of the badge. @default 'full' */
     roundedness?: Value<RadiusName>;
+    /** Whether to render as a circle (equal width and height). @default false */
     circle?: Value<boolean>;
+    /** Whether the badge takes the full width of its container. @default false */
     fullWidth?: Value<boolean>;
+    /** Whether to render as a small colored dot indicator (8px by default). @default false */
+    dot?: Value<boolean>;
 }
-export declare function generateBadgeClasses(size: ControlSize, roundedness: RadiusName, circle: boolean, fullWidth: boolean): string;
+/**
+ * Generates CSS class names for the badge based on size, roundedness, and shape.
+ *
+ * @param size - Control size for padding and text
+ * @param roundedness - Border radius preset
+ * @param circle - Whether to force a circular shape
+ * @param fullWidth - Whether to stretch to full container width
+ * @param dot - Whether to render as a small dot indicator
+ * @returns Space-separated CSS class string
+ */
+export declare function generateBadgeClasses(size: ControlSize, roundedness: RadiusName, circle: boolean, fullWidth: boolean, dot: boolean): string;
+/**
+ * Generates inline CSS custom properties for badge theming based on variant and color.
+ * Sets background, text, border, and hover colors for both light and dark modes.
+ *
+ * @param variant - The visual style variant
+ * @param color - The theme color
+ * @returns Semicolon-separated CSS custom property declarations
+ */
 export declare function generateBadgeStyles(variant: ButtonVariant, color: ExtendedColor): string;
-export declare function Badge({ variant, size, color, roundedness, circle, fullWidth, }: BadgeOptions, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * A small status indicator or label component with theme-aware colors.
+ * Supports all button variants (filled, light, outline, default, text) and
+ * can be rendered as a pill, circle, or full-width element.
+ *
+ * @param options - Configuration for variant, size, color, and shape
+ * @param children - Content to display inside the badge (text, number, icon)
+ * @returns A styled span element
+ *
+ * @example
+ * ```typescript
+ * Badge({ variant: 'filled', color: 'success', size: 'sm' }, '3')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Circle badge for notification counts
+ * Badge({ circle: true, color: 'danger', size: 'xs' }, '9+')
+ * ```
+ */
+export declare function Badge({ variant, size, color, roundedness, circle, fullWidth, dot, }: BadgeOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

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

@@ -0,0 +1,59 @@
+import { Value, type Prop, type TNode } from '@tempots/dom';
+import { ControlSize } from '../theme';
+import { ThemeColorName } from '../../tokens';
+import type { BeatUITemporal, PlainDate } from '../../temporal/types';
+export declare const YEARS_PER_PAGE = 20;
+export declare const DAYS_IN_WEEK = 7;
+export declare const MONTH_NAMES: string[];
+export declare const SHORT_MONTH_NAMES: string[];
+export declare const DAY_NAMES: string[];
+export type CalendarView = 'days' | 'months' | 'years';
+export declare function generateCalendarClasses(size: ControlSize, disabled: boolean): string;
+export declare function generateCalendarStyles(color: ThemeColorName): string;
+/** Base cell data computed by {@link buildCalendarGrid}. */
+export interface CalendarBaseCell {
+    day: number;
+    date: PlainDate;
+    inMonth: boolean;
+    isToday: boolean;
+    isDisabled: boolean;
+}
+/** Builds the base array of day cells for a given month. */
+export declare function buildCalendarGrid(T: BeatUITemporal, year: number, month: number, weekStartsOn: number, today: PlainDate, isDateDisabled?: (date: PlainDate) => boolean): CalendarBaseCell[];
+/** State and actions returned by {@link createCalendarNav}. */
+export interface CalendarNav {
+    today: PlainDate;
+    currentYear: Prop<number>;
+    currentMonth: Prop<number>;
+    view: Prop<CalendarView>;
+    yearPageStart: Prop<number>;
+    shiftedDayNames: string[];
+    prevMonth: () => void;
+    nextMonth: () => void;
+    prevYear: () => void;
+    nextYear: () => void;
+    prevYearPage: () => void;
+    nextYearPage: () => void;
+    switchToMonthsView: () => void;
+    switchToYearsView: () => void;
+    selectMonth: (month: number) => void;
+    selectYear: (year: number) => void;
+}
+/** Creates the shared navigation state for a calendar. */
+export declare function createCalendarNav(T: BeatUITemporal, initialYear: number, initialMonth: number, disabled: Value<boolean>, weekStartsOn: number): CalendarNav;
+export interface CalendarShellOptions {
+    size: Value<ControlSize>;
+    disabled: Value<boolean>;
+    color: Value<ThemeColorName>;
+    ariaLabel: string;
+}
+/**
+ * Renders the full calendar shell: outer wrapper, navigation header
+ * (days/months/years), weekday headers, month picker, year picker,
+ * and a custom day grid.
+ */
+export declare function renderCalendarShell(nav: CalendarNav, opts: CalendarShellOptions, renderGrid: () => TNode): TNode;
+/** Converts a `PlainDate` to a JavaScript `Date` (local midnight). */
+export declare function plainDateToDate(pd: PlainDate): Date;
+/** Converts a JavaScript `Date` to a `PlainDate`. */
+export declare function dateToPlainDate(T: BeatUITemporal, d: Date): PlainDate;