@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/layout/action-card.d.ts

@@ -1,19 +1,107 @@
-import { TNode, Value } from '@tempots/dom';
+import { Value } from '@tempots/dom';
 import { ControlSize, IconSize } from '../theme';
 import { ThemeColorName } from '../../tokens';
+/**
+ * Configuration options for the {@link ActionCard} component.
+ */
 export interface ActionCardOptions {
+    /** Iconify icon identifier displayed on the left side of the card. */
     icon: Value<string>;
+    /** Primary title text displayed prominently in the card. */
     title: Value<string>;
+    /** Secondary description text displayed below the title. */
     description: Value<string>;
+    /**
+     * Whether the card is in an active/selected state, adding a visual highlight.
+     * @default false
+     */
     active?: Value<boolean>;
+    /**
+     * Whether the card is disabled. Disabled cards cannot be clicked and appear dimmed.
+     * @default false
+     */
     disabled?: Value<boolean>;
+    /**
+     * Click handler. When provided, the card becomes interactive with `role="button"`,
+     * keyboard support, and hover styles.
+     */
     onClick?: () => void;
+    /**
+     * Size variant controlling the card's padding and text sizing.
+     * @default 'md'
+     */
     size?: Value<ControlSize>;
+    /**
+     * Theme color for the icon.
+     * @default 'primary'
+     */
     iconColor?: Value<ThemeColorName>;
+    /**
+     * Size of the icon.
+     * @default 'md'
+     */
     iconSize?: Value<IconSize>;
+    /**
+     * CSS variable override for the card background color.
+     * Sets `--action-card-bg`.
+     */
     backgroundColor?: Value<string>;
+    /**
+     * CSS variable override for the card border color.
+     * Sets `--action-card-border`.
+     */
     borderColor?: Value<string>;
+    /**
+     * CSS variable override for the title text color.
+     * Sets `--action-card-title-color`.
+     */
     titleColor?: Value<string>;
+    /**
+     * CSS variable override for the description text color.
+     * Sets `--action-card-description-color`.
+     */
     descriptionColor?: Value<string>;
 }
-export declare function ActionCard({ icon, title, description, active, disabled, onClick, size, iconColor, iconSize, backgroundColor, borderColor, titleColor, descriptionColor, }: ActionCardOptions): TNode;
+/**
+ * Renders an interactive card with an icon, title, and description. Commonly
+ * used for selection grids, feature highlights, or navigation tiles.
+ *
+ * When an `onClick` handler is provided, the card becomes clickable with
+ * `role="button"`, keyboard activation (Enter/Space), and focus management.
+ * The card supports active and disabled states, and allows CSS variable
+ * overrides for custom theming.
+ *
+ * @param options - Configuration options for the action card.
+ * @returns A renderable card element.
+ *
+ * @example
+ * ```typescript
+ * // Basic clickable action card
+ * ActionCard({
+ *   icon: 'material-symbols:upload',
+ *   title: 'Upload File',
+ *   description: 'Select a file from your computer',
+ *   onClick: () => openFilePicker(),
+ * })
+ *
+ * // Active card in a selection grid
+ * const selected = prop('option-a')
+ * ActionCard({
+ *   icon: 'material-symbols:check-circle',
+ *   title: 'Option A',
+ *   description: 'The recommended choice',
+ *   active: selected.map(v => v === 'option-a'),
+ *   onClick: () => selected.set('option-a'),
+ * })
+ *
+ * // Disabled card with custom colors
+ * ActionCard({
+ *   icon: 'material-symbols:lock',
+ *   title: 'Premium Feature',
+ *   description: 'Upgrade to unlock',
+ *   disabled: true,
+ *   iconColor: 'warning',
+ * })
+ * ```
+ */
+export declare function ActionCard({ icon, title, description, active, disabled, onClick, size, iconColor, iconSize, backgroundColor, borderColor, titleColor, descriptionColor, }: ActionCardOptions): import("@tempots/dom").Renderable;

package/dist/types/components/layout/app-shell.d.ts

@@ -1,42 +1,118 @@
 import { TNode } from '@tempots/dom';
 import { BeatUIBreakpoint } from './with-breakpoint';
 import { PanelColor, PanelShadow } from '../theme';
+/**
+ * Per-breakpoint dimension values (in pixels) for AppShell sections.
+ * Each property corresponds to a standard BeatUI breakpoint.
+ */
 export interface AppShellBreakpointOptions {
+    /** Width/height at the zero (smallest) breakpoint in pixels. */
     zero: number;
+    /** Width/height at the xs breakpoint in pixels. */
     xs: number;
+    /** Width/height at the sm breakpoint in pixels. */
     sm: number;
+    /** Width/height at the md breakpoint in pixels. */
     md: number;
+    /** Width/height at the lg breakpoint in pixels. */
     lg: number;
+    /** Width/height at the xl breakpoint in pixels. */
     xl: number;
 }
+/** Partial version of {@link AppShellBreakpointOptions} where all breakpoints are optional. */
 export type AppShellBreakpointOptionalOptions = Partial<AppShellBreakpointOptions>;
+/** Options for horizontal AppShell sections (banner, header, footer, mainHeader, mainFooter). */
 export interface AppShellHorizontalOptions {
+    /** Content to render inside this section. */
     content: TNode;
+    /** Section height in pixels, or per-breakpoint heights. */
     height?: number | AppShellBreakpointOptionalOptions;
+    /** Background color of the panel. @default 'white' */
     color?: PanelColor;
+    /** Shadow depth of the panel edge. @default 'none' */
     shadow?: PanelShadow;
 }
+/** Options for vertical AppShell sections (menu, aside). */
 export interface AppShellVerticalOptions {
+    /** Content to render inside this section. */
     content: TNode;
+    /** Section width in pixels, or per-breakpoint widths. */
     width?: number | AppShellBreakpointOptionalOptions;
+    /** Background color of the panel. @default 'white' */
     color?: PanelColor;
+    /** Shadow depth of the panel edge. @default 'none' */
     shadow?: PanelShadow;
 }
+/** Options for the main content area of the AppShell. */
 export interface AppShellMainOptions {
+    /** Content to render in the main area. */
     content: TNode;
+    /** Background color of the panel. @default 'white' */
     color?: PanelColor;
+    /** Shadow depth of the panel edge. @default 'none' */
     shadow?: PanelShadow;
 }
+/**
+ * Configuration options for the {@link AppShell} component.
+ * Each section (banner, header, menu, main, aside, footer) is optional except `main`.
+ */
 export interface AppShellOptions {
+    /** Top banner section spanning full width above the header. */
     banner?: AppShellHorizontalOptions;
+    /** Header section with optional hamburger/aside toggle buttons. */
     header?: AppShellHorizontalOptions;
+    /** Bottom footer section spanning full width. */
     footer?: AppShellHorizontalOptions;
+    /** Left navigation menu panel; collapses to hamburger on small screens. */
     menu?: AppShellVerticalOptions;
+    /** Right sidebar panel; collapses to toggle button on medium screens. */
     aside?: AppShellVerticalOptions;
+    /** Main content area (required). */
     main: AppShellMainOptions;
+    /** Secondary header within the main content area. */
     mainHeader?: AppShellHorizontalOptions;
+    /** Secondary footer within the main content area. */
     mainFooter?: AppShellHorizontalOptions;
+    /** Breakpoint at which menu/aside collapse to float panels. @default 'md' */
     mediumBreakpoint?: BeatUIBreakpoint;
+    /** Breakpoint at which all panels collapse to hamburger menu. @default 'sm' */
     smallBreakpoint?: BeatUIBreakpoint;
 }
+/**
+ * A responsive application layout shell with CSS Grid that provides structured
+ * sections for banner, header, menu, main content, aside, and footer.
+ *
+ * The layout adapts to three responsive tiers:
+ * - **Large** (above `mediumBreakpoint`): All panels visible in a three-column grid
+ * - **Medium** (between `smallBreakpoint` and `mediumBreakpoint`): Menu pinned, aside collapses
+ * - **Small** (at or below `smallBreakpoint`): All panels collapse, header shows hamburger buttons
+ *
+ * Collapsed panels animate in as floating overlays with proper ARIA landmarks
+ * (`navigation`, `complementary`) and toggle buttons.
+ *
+ * @param options - Layout configuration with content for each section
+ * @returns A responsive CSS Grid layout element
+ *
+ * @example
+ * ```typescript
+ * AppShell({
+ *   header: {
+ *     content: html.div('My App'),
+ *     height: 60,
+ *     shadow: 'sm'
+ *   },
+ *   menu: {
+ *     content: SidebarNavigation(),
+ *     width: { md: 240, lg: 280 }
+ *   },
+ *   main: {
+ *     content: RouterOutlet()
+ *   },
+ *   footer: {
+ *     content: html.div('Footer'),
+ *     height: 48
+ *   }
+ * })
+ * ```
+ */
 export declare function AppShell({ smallBreakpoint, mediumBreakpoint, ...options }: AppShellOptions): import("@tempots/dom").Renderable;

package/dist/types/components/layout/card.d.ts

@@ -1,9 +1,36 @@
 import { TNode, Value } from '@tempots/dom';
 import { CardVariant, ControlSize } from '../theme';
 import { RadiusName } from '../../tokens/radius';
+/** Configuration options for the {@link Card} component. */
 export interface CardOptions {
+    /** The visual style variant of the card. @default 'default' */
     variant?: Value<CardVariant>;
+    /** Controls the internal padding size. @default 'md' */
     size?: Value<ControlSize>;
+    /** The border radius of the card. @default 'lg' */
     roundedness?: Value<RadiusName>;
 }
+/**
+ * A container component that groups content with visual separation using
+ * elevation, borders, or background color depending on the variant.
+ *
+ * @param options - Configuration options for appearance and sizing
+ * @param children - Content to render inside the card
+ * @returns A styled div element
+ *
+ * @example
+ * ```typescript
+ * Card(
+ *   { variant: 'elevated', size: 'lg' },
+ *   html.h2('Card Title'),
+ *   html.p('Card content goes here.')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Card with default options
+ * Card({}, html.p('Simple card'))
+ * ```
+ */
 export declare function Card({ variant, size, roundedness }?: CardOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/layout/center.d.ts

@@ -1,7 +1,46 @@
 import { TNode, Value } from '@tempots/dom';
 import { CenterGap } from '../theme';
+/** Configuration options for the {@link Center} component. */
 export interface CenterOptions {
+    /** Gap size between centered content and surrounding elements. @default 'lg' */
     gap?: Value<CenterGap>;
 }
+/**
+ * Horizontally centers its children within a container.
+ * Uses the `bc-center-h` CSS class for horizontal centering only.
+ *
+ * @param children - Child nodes to center horizontally
+ * @returns A div element with horizontally centered content
+ *
+ * @example
+ * ```typescript
+ * CenterH(
+ *   html.h1('Centered Heading'),
+ *   html.p('This paragraph is horizontally centered.')
+ * )
+ * ```
+ */
 export declare function CenterH(...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Centers its children both horizontally and vertically within a container.
+ * Supports configurable gap spacing between content and the container edges.
+ *
+ * @param options - Configuration options for gap spacing
+ * @param children - Child nodes to center
+ * @returns A div element with centered content
+ *
+ * @example
+ * ```typescript
+ * Center(
+ *   { gap: 'md' },
+ *   html.div('This content is centered on the page')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Center with default gap
+ * Center({}, Icon({ icon: 'line-md:loading-twotone-loop', size: 'xl' }))
+ * ```
+ */
 export declare function Center({ gap }?: CenterOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/layout/collapse.d.ts

@@ -1,5 +1,33 @@
 import { TNode, Value } from '@tempots/dom';
+/** Configuration options for the {@link Collapse} component. */
 export type CollapseOption = {
+    /** Reactive boolean controlling whether the content is expanded or collapsed. */
     open: Value<boolean>;
 };
+/**
+ * Animated collapsible container that smoothly expands and contracts its content.
+ * Measures the natural content height and uses CSS transitions for smooth animation.
+ *
+ * The component manages four animation states internally: `closed`, `start-opening`,
+ * `opened`, and `start-closing`, applying corresponding CSS classes for each.
+ *
+ * @param options - Configuration with the `open` signal controlling visibility
+ * @param children - Content to show/hide with animation
+ * @returns A container element with animated collapse behavior
+ *
+ * @example
+ * ```typescript
+ * import { prop } from '@tempots/dom'
+ *
+ * const isOpen = prop(false)
+ *
+ * Stack(
+ *   Button({ onClick: () => isOpen.set(!isOpen.value) }, 'Toggle'),
+ *   Collapse(
+ *     { open: isOpen },
+ *     html.p('This content is collapsible.')
+ *   )
+ * )
+ * ```
+ */
 export declare function Collapse({ open }: CollapseOption, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/layout/divider.d.ts

@@ -0,0 +1,84 @@
+import { TNode, Value } from '@tempots/dom';
+/**
+ * Orientation of the divider line.
+ *
+ * - `'horizontal'` - Horizontal separator (default)
+ * - `'vertical'` - Vertical separator
+ */
+export type DividerOrientation = 'horizontal' | 'vertical';
+/**
+ * Visual style variant of the divider line.
+ *
+ * - `'solid'` - Solid line (default)
+ * - `'dashed'` - Dashed line
+ * - `'dotted'` - Dotted line
+ */
+export type DividerVariant = 'solid' | 'dashed' | 'dotted';
+/**
+ * Visual weight/prominence of the divider.
+ *
+ * - `'subtle'` - Lighter, less prominent
+ * - `'default'` - Standard prominence
+ * - `'strong'` - Darker, more prominent
+ */
+export type DividerTone = 'subtle' | 'default' | 'strong';
+/**
+ * Alignment of the label text in a labeled divider.
+ *
+ * - `'left'` - Label aligned to the left
+ * - `'center'` - Label centered (default)
+ * - `'right'` - Label aligned to the right
+ */
+export type DividerLabelAlign = 'left' | 'center' | 'right';
+/**
+ * Configuration options for the {@link Divider} component.
+ */
+export interface DividerOptions {
+    /** Orientation of the divider. @default 'horizontal' */
+    orientation?: Value<DividerOrientation>;
+    /** Line style variant. @default 'solid' */
+    variant?: Value<DividerVariant>;
+    /** Visual prominence level. @default 'default' */
+    tone?: Value<DividerTone>;
+    /** Optional label to display in the middle of the divider. */
+    label?: TNode;
+    /** Alignment of the label text. @default 'center' */
+    labelAlign?: Value<DividerLabelAlign>;
+}
+/**
+ * A visual separator component for dividing content sections.
+ * Can be horizontal or vertical, with optional label text centered (or aligned)
+ * within the divider line.
+ *
+ * @param options - Configuration for orientation, style, tone, and label
+ * @returns A semantic `<hr>` element or a labeled container with divider lines
+ *
+ * @example
+ * ```typescript
+ * // Simple horizontal divider
+ * Divider()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Divider with centered label
+ * Divider({ label: 'OR' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Vertical divider
+ * Divider({ orientation: 'vertical' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dashed divider with label aligned left
+ * Divider({
+ *   variant: 'dashed',
+ *   label: 'Section Break',
+ *   labelAlign: 'left'
+ * })
+ * ```
+ */
+export declare function Divider({ orientation, variant, tone, label, labelAlign, }?: DividerOptions): import("@tempots/dom").Renderable;

package/dist/types/components/layout/group.d.ts

@@ -1,2 +1,17 @@
 import { TNode } from '@tempots/dom';
+/**
+ * Horizontal group layout that arranges children in a row with consistent spacing.
+ * Uses the `bc-group` CSS class for flexbox row layout with gap.
+ *
+ * @param children - Child nodes to arrange horizontally
+ * @returns A div element with horizontal group layout
+ *
+ * @example
+ * ```typescript
+ * Group(
+ *   Button({ variant: 'outline' }, 'Cancel'),
+ *   Button({ variant: 'filled', color: 'primary' }, 'Save')
+ * )
+ * ```
+ */
 export declare function Group(...children: TNode[]): import("@tempots/dom").Renderable;

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

@@ -1,8 +1,10 @@
+export * from './accordion';
 export * from './action-card';
 export * from './app-shell';
 export * from './card';
 export * from './center';
 export * from './collapse';
+export * from './divider';
 export * from './nine-slice-scroll-view';
 export * from './group';
 export * from './scrollable-panel';

package/dist/types/components/layout/nine-slice-scroll-view.d.ts

@@ -1,21 +1,126 @@
 import { TNode, Value } from '@tempots/dom';
+/**
+ * Controls how the end sidebar and footer regions are anchored relative
+ * to the body content or the container edge.
+ *
+ * - `'container-edge'` - Anchors to the container edge (fixed position)
+ * - `'body-end'` - Anchors the end sidebar to the body content's right edge
+ * - `'body-bottom'` - Anchors the footer to the body content's bottom edge
+ * - `'body-end-bottom'` - Anchors both end sidebar and footer to the body content edges
+ */
 export type AnchorMode = 'container-edge' | 'body-end' | 'body-bottom' | 'body-end-bottom';
+/**
+ * Configuration options for the {@link NineSliceScrollView} component.
+ *
+ * The nine-slice layout divides the view into nine regions arranged in a 3x3 grid:
+ * ```
+ * +------------+----------+----------+
+ * | topStart   | header   | topEnd   |
+ * +------------+----------+----------+
+ * | sideStart  |   body   | sideEnd  |
+ * +------------+----------+----------+
+ * | bottomStart| footer   | bottomEnd|
+ * +------------+----------+----------+
+ * ```
+ *
+ * The body region scrolls while surrounding regions remain fixed. Header and
+ * footer translate horizontally with the body, while sidebars translate vertically.
+ * Corner regions remain completely fixed.
+ */
 export type NineSliceScrollViewOptions = {
+    /** The main scrollable content area (center cell of the nine-slice grid). */
     body: TNode;
+    /** Total width of the scrollable content in the body, as a bigint in pixels. */
     contentWidth: Value<bigint>;
+    /** Total height of the scrollable content in the body, as a bigint in pixels. */
     contentHeight: Value<bigint>;
+    /**
+     * Content for the top-center header region. Scrolls horizontally with the body
+     * but remains fixed vertically.
+     */
     header?: TNode;
+    /**
+     * Fixed pixel height of the header region.
+     * @default 0
+     */
     headerHeight?: Value<number>;
+    /** Content for the top-start corner (top-left in LTR, top-right in RTL). */
     topStart?: TNode;
+    /** Content for the top-end corner (top-right in LTR, top-left in RTL). */
     topEnd?: TNode;
+    /**
+     * Content for the bottom-center footer region. Scrolls horizontally with the body
+     * but remains fixed vertically.
+     */
     footer?: TNode;
+    /**
+     * Fixed pixel height of the footer region.
+     * @default 0
+     */
     footerHeight?: Value<number>;
+    /** Content for the bottom-start corner (bottom-left in LTR, bottom-right in RTL). */
     bottomStart?: TNode;
+    /** Content for the bottom-end corner (bottom-right in LTR, bottom-left in RTL). */
     bottomEnd?: TNode;
+    /**
+     * Content for the start sidebar (left in LTR, right in RTL). Scrolls vertically
+     * with the body but remains fixed horizontally.
+     */
     sidebarStart?: TNode;
+    /**
+     * Fixed pixel width of the start sidebar.
+     * @default 0
+     */
     sidebarStartWidth?: Value<number>;
+    /**
+     * Content for the end sidebar (right in LTR, left in RTL). Scrolls vertically
+     * with the body but remains fixed horizontally.
+     */
     sidebarEnd?: TNode;
+    /**
+     * Fixed pixel width of the end sidebar.
+     * @default 0
+     */
     sidebarEndWidth?: Value<number>;
+    /**
+     * Controls how the end sidebar and footer anchor relative to the body content.
+     * @default 'container-edge'
+     */
     anchorMode?: Value<AnchorMode>;
 };
+/**
+ * Renders a nine-slice scrolling layout where the central body region scrolls
+ * in both axes while surrounding regions (header, footer, sidebars, and corners)
+ * remain fixed or scroll in only one axis. This is ideal for spreadsheet-like
+ * UIs, data grids with frozen rows/columns, or any layout requiring synchronized
+ * scrolling with fixed periphery.
+ *
+ * The component manages its own scroll state via wheel event throttling and
+ * custom scrollbars, providing consistent cross-browser behavior. Content
+ * dimensions must be provided explicitly since the body content is translated
+ * rather than natively scrolled.
+ *
+ * @param options - Configuration options for the nine-slice scroll view.
+ * @returns A renderable nine-slice container element.
+ *
+ * @example
+ * ```typescript
+ * const contentW = prop(5000n)
+ * const contentH = prop(10000n)
+ *
+ * NineSliceScrollView({
+ *   body: html.div(
+ *     // Large scrollable content
+ *     ...cells
+ *   ),
+ *   contentWidth: contentW,
+ *   contentHeight: contentH,
+ *   header: html.div('Column Headers'),
+ *   headerHeight: 40,
+ *   sidebarStart: html.div('Row Labels'),
+ *   sidebarStartWidth: 200,
+ *   topStart: html.div('Corner'),
+ * })
+ * ```
+ */
 export declare function NineSliceScrollView({ body, contentWidth, contentHeight, header, headerHeight, topStart, topEnd, footer, footerHeight, bottomStart, bottomEnd, sidebarStart, sidebarStartWidth, sidebarEnd, sidebarEndWidth, anchorMode, }: NineSliceScrollViewOptions): import("@tempots/dom").Renderable;

package/dist/types/components/layout/scrollable-panel.d.ts

@@ -1,8 +1,62 @@
 import { TNode, Value } from '@tempots/dom';
+/**
+ * Configuration options for the {@link ScrollablePanel} component.
+ */
 export type ScrollablePanelOptions = {
+    /**
+     * Optional header content rendered above the scrollable body.
+     * Remains fixed while the body scrolls.
+     */
     header?: TNode;
+    /**
+     * Optional footer content rendered below the scrollable body.
+     * Remains fixed while the body scrolls.
+     */
     footer?: TNode;
+    /**
+     * The main scrollable content area of the panel.
+     */
     body: TNode;
+    /**
+     * Whether to display scroll shadow indicators at the top/bottom edges
+     * when the body content overflows. Shadows help indicate scrollable content
+     * that is currently out of view.
+     * @default true
+     */
     shadowOnScroll?: Value<boolean>;
 };
+/**
+ * Renders a panel with a scrollable body and optional fixed header/footer.
+ * Automatically displays scroll shadow indicators at the top and bottom
+ * edges when content overflows, providing a visual cue that more content
+ * is available.
+ *
+ * The shadow state updates reactively based on the scroll position:
+ * - No shadow when content fits without scrolling
+ * - Bottom shadow when scrolled to top (more content below)
+ * - Top shadow when scrolled to bottom (more content above)
+ * - Both shadows when scrolled to the middle
+ *
+ * @param options - Configuration options for the scrollable panel.
+ * @param children - Additional content nodes appended after the footer.
+ * @returns A scrollable panel element with shadow indicators.
+ *
+ * @example
+ * ```typescript
+ * // Panel with header and scrollable body
+ * ScrollablePanel({
+ *   header: html.h2('File Browser'),
+ *   body: html.div(
+ *     ...files.map(file => html.div(file.name))
+ *   ),
+ *   footer: html.div('10 files'),
+ * })
+ *
+ * // Panel without scroll shadows
+ * ScrollablePanel({
+ *   body: html.div('Content here'),
+ *   shadowOnScroll: false,
+ * })
+ * ```
+ */
 export declare function ScrollablePanel({ header, footer, body, shadowOnScroll }: ScrollablePanelOptions, ...children: TNode[]): import("@tempots/dom").Renderable;