@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/overlay/popover.d.ts

@@ -0,0 +1,100 @@
+import { TNode, Value, Renderable } from '@tempots/dom';
+import { Placement } from '@tempots/ui';
+import { FlyoutTrigger } from '../navigation/flyout';
+export type PopoverTrigger = FlyoutTrigger;
+/**
+ * Configuration options for the {@link Popover} component.
+ */
+export interface PopoverOptions {
+    /**
+     * The content to display inside the popover.
+     * Can be a static TNode or a factory function that returns TNode.
+     */
+    content: TNode | (() => TNode);
+    /**
+     * Placement of the popover relative to the trigger element.
+     * Uses the Floating UI placement model (e.g., `'top'`, `'bottom-start'`, `'right-end'`).
+     * @default 'bottom'
+     */
+    placement?: Value<Placement>;
+    /**
+     * Delay in milliseconds before showing the popover after trigger activation.
+     * @default 0
+     */
+    showDelay?: Value<number>;
+    /**
+     * Delay in milliseconds before hiding the popover after trigger deactivation.
+     * @default 0
+     */
+    hideDelay?: Value<number>;
+    /**
+     * Offset in pixels from the main axis (vertical for top/bottom placements,
+     * horizontal for left/right placements).
+     * @default 8
+     */
+    mainAxisOffset?: Value<number>;
+    /**
+     * Offset in pixels from the cross axis (horizontal for top/bottom placements,
+     * vertical for left/right placements).
+     * @default 0
+     */
+    crossAxisOffset?: Value<number>;
+    /**
+     * How the popover is triggered to show and hide.
+     * @default 'click'
+     */
+    showOn?: Value<PopoverTrigger>;
+    /**
+     * Whether the popover can be closed with the Escape key or by clicking outside.
+     * @default true
+     */
+    closable?: Value<boolean>;
+    /**
+     * ARIA role attribute applied to the popover container.
+     * @default 'dialog'
+     */
+    role?: Value<string>;
+    /**
+     * Value for the `aria-haspopup` attribute on the trigger element.
+     * Indicates the type of popup that the trigger controls.
+     * @default 'dialog'
+     */
+    hasPopup?: Value<boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid'>;
+}
+/**
+ * Popover component that displays arbitrary content in a positioned overlay panel
+ * triggered by clicking (or other interactions with) a trigger element.
+ *
+ * Unlike wrapper-based popover libraries, this component is designed to be a child
+ * of the trigger element, rather than wrapping it.
+ *
+ * Built on top of the Flyout component for positioning and interaction logic.
+ *
+ * @example
+ * ```typescript
+ * html.button(
+ *   'Click me',
+ *   Popover({
+ *     content: html.div(
+ *       html.p('Popover content'),
+ *       html.button('Action')
+ *     ),
+ *     placement: 'bottom-start'
+ *   })
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With lazy content loading
+ * html.button(
+ *   'Settings',
+ *   Popover({
+ *     content: () => SettingsPanel(),
+ *     placement: 'bottom-end',
+ *     showOn: 'click'
+ *   })
+ * )
+ * ```
+ */
+export declare function Popover(options: PopoverOptions): Renderable;

package/dist/types/components/overlay/ribbon.d.ts

@@ -1,25 +1,74 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
 import type { ThemeColorName } from '../../tokens';
 import { ExtendedColor } from '../theme/style-utils';
+/**
+ * Corner position for the {@link Ribbon} component.
+ * Determines which corner of the parent container the ribbon is placed at.
+ */
 export type RibbonCorner = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/**
+ * Configuration options for the {@link Ribbon} component.
+ */
 export type RibbonOptions = {
-    /** Background/text color theme (defaults to 'primary') */
+    /**
+     * Theme color applied to the ribbon background and text.
+     * Accepts any named theme color or an extended color value.
+     * @default 'primary'
+     */
     color?: Value<ThemeColorName | ExtendedColor>;
-    /** Extra classes */
+    /**
+     * Additional CSS class names to apply to the ribbon element.
+     */
     class?: Value<string>;
-    /** Horizontal nudge along the top edge before rotation (px if number). Default: 0px */
+    /**
+     * Horizontal nudge along the edge before rotation. Accepts a pixel number or CSS length string.
+     * @default 0
+     */
     inset?: Value<number | string>;
-    /** Fine vertical correction to align the band crossing (px if number). Default: -1px */
+    /**
+     * Vertical offset correction to fine-tune the band crossing position.
+     * Accepts a pixel number or CSS length string.
+     * @default 40
+     */
     offset?: Value<number | string>;
-    /** Minimum width of the band (px if number). Default: null */
+    /**
+     * Minimum width of the ribbon band. Accepts a pixel number or CSS length string.
+     * @default 100
+     */
     width?: Value<number | string>;
-    /** Rotation angle in degrees. Default: 45 */
+    /**
+     * Rotation angle of the ribbon in degrees.
+     * @default 45
+     */
     angle?: Value<number>;
-    /** Corner position. Default: 'top-end' */
+    /**
+     * Corner of the parent container where the ribbon is positioned.
+     * @default 'top-end'
+     */
     corner?: Value<RibbonCorner>;
 };
 /**
- * Ribbon: renders diagonal content at a specified corner.
- * Note: The parent container should be positioned (e.g., position: relative) for best results.
+ * Renders a diagonal ribbon badge at a specified corner of its parent container.
+ *
+ * The ribbon is positioned absolutely, so the parent container should use
+ * `position: relative` (or another positioning context) for correct placement.
+ * Theme-aware colors are applied via CSS custom properties, supporting both
+ * light and dark modes.
+ *
+ * @param options - Configuration options controlling color, position, size, and rotation
+ * @param children - Content to display inside the ribbon (typically short text like "New" or "Sale")
+ * @returns A renderable node
+ *
+ * @example
+ * ```typescript
+ * html.div(
+ *   attr.style('position: relative'),
+ *   Ribbon(
+ *     { color: 'danger', corner: 'top-end', angle: 45 },
+ *     'Sale'
+ *   ),
+ *   html.p('Product card content')
+ * )
+ * ```
  */
 export declare function Ribbon({ color, class: cls, inset, offset, width, angle, corner, }: RibbonOptions, ...children: TNode[]): Renderable;

package/dist/types/components/prosemirror/etoolbar-button.d.ts

@@ -1 +1,11 @@
+/**
+ * Re-exports the shared {@link EditorToolbarButton} component under its
+ * legacy alias `EToolbarButton` for backwards compatibility with older
+ * ProseMirror toolbar integrations.
+ *
+ * New code should import `EditorToolbarButton` directly from
+ * `../editor-toolbar` instead.
+ *
+ * @module
+ */
 export { EditorToolbarButton as EToolbarButton } from '../editor-toolbar';

package/dist/types/components/prosemirror/etoolbar-group.d.ts

@@ -1 +1,11 @@
+/**
+ * Re-exports the shared {@link EditorToolbarGroup} component under its
+ * legacy alias `EToolbarGroup` for backwards compatibility with older
+ * ProseMirror toolbar integrations.
+ *
+ * New code should import `EditorToolbarGroup` directly from
+ * `../editor-toolbar` instead.
+ *
+ * @module
+ */
 export { EditorToolbarGroup as EToolbarGroup } from '../editor-toolbar';

package/dist/types/components/prosemirror/link-control.d.ts

@@ -1,12 +1,53 @@
-import { Signal, TNode, Value } from '@tempots/dom';
+/**
+ * ProseMirror link editing control for the editor toolbar.
+ *
+ * Renders a toolbar button that toggles link marks on/off, along with an
+ * inline URL text input and a "go" button that opens the entered URL in a
+ * new tab.
+ *
+ * @module
+ */
+import { Signal, Value } from '@tempots/dom';
 import { EditorView } from 'prosemirror-view';
 import { ControlSize } from '../theme';
+/**
+ * Configuration properties for the {@link LinkControl} component.
+ */
 export interface LinkDialogButtonProps {
+    /** Ticker signal that increments on every ProseMirror state change. */
     stateUpdate: Signal<number>;
+    /** Signal holding the current ProseMirror `EditorView`. */
     view: Signal<EditorView>;
+    /** Signal indicating whether the editor is in read-only mode. */
     isReadOnly: Signal<boolean>;
+    /** Accessible label for the link toolbar button. */
     label: Value<string>;
+    /** Placeholder text shown in the URL input field. */
     linkUrlPlaceholder: Value<string>;
+    /** Size of the toolbar button and input controls. */
     size: Value<ControlSize>;
 }
-export declare function LinkControl({ stateUpdate, view, isReadOnly, label, linkUrlPlaceholder, size, }: LinkDialogButtonProps): TNode;
+/**
+ * A toolbar control for editing hyperlinks in a ProseMirror editor.
+ *
+ * Renders a link toggle button that creates or removes link marks on the
+ * current selection. When a link is active, an inline `TextInput` appears
+ * allowing the user to edit the URL, along with a "go" button to open the
+ * URL in a new browser tab.
+ *
+ * @param props - Configuration for the link control (view, state, labels, etc.).
+ * @returns A `TNode` renderable for inclusion in a ProseMirror toolbar.
+ *
+ * @example
+ * ```ts
+ * LinkControl({
+ *   stateUpdate: editorStateNotifier,
+ *   view: editorViewSignal,
+ *   isReadOnly: signal(false),
+ *   label: 'Link',
+ *   linkUrlPlaceholder: 'Enter URL...',
+ *   size: 'sm',
+ * })
+ * ```
+ */
+export declare function LinkControl({ stateUpdate, view, isReadOnly, label, linkUrlPlaceholder, size, }: LinkDialogButtonProps): import("@tempots/dom").Renderable<import("@tempots/dom").DOMContext>;

package/dist/types/components/prosemirror/prosemirror-toolbar.d.ts

@@ -1,18 +1,58 @@
-import { TNode, Value, Signal } from '@tempots/dom';
+/**
+ * Toolbar component for the ProseMirror markdown editor.
+ *
+ * Renders formatting buttons (bold, italic, code), heading level selectors,
+ * list toggles (bullet/ordered), block formatting (blockquote, code block,
+ * horizontal rule), and an inline link editor -- all driven by the
+ * {@link MarkdownFeatures} configuration.
+ *
+ * @module
+ */
+import { Value, Signal } from '@tempots/dom';
 import type { EditorView } from 'prosemirror-view';
 import type { MarkdownFeatures } from './prosemirror-markdown-input';
 import { ControlSize } from '../theme';
+/**
+ * Options for configuring the ProseMirror markdown toolbar.
+ */
 export interface ProseMirrorToolbarOptions {
-    /** The ProseMirror editor view */
+    /** Signal holding the ProseMirror editor view, or `null` before initialization. */
     view: Signal<EditorView | null>;
+    /** Ticker signal that increments on every ProseMirror state change. */
     stateUpdate: Signal<number>;
-    /** Enabled markdown features */
+    /** Signal of enabled markdown features controlling which toolbar buttons are visible. */
     features: Signal<MarkdownFeatures>;
-    /** Whether the editor is readonly */
+    /**
+     * Signal indicating whether the editor is in read-only mode.
+     * Toolbar buttons are disabled when `true`.
+     * @default signal(false)
+     */
     readOnly?: Signal<boolean>;
+    /**
+     * Size of the toolbar buttons.
+     * @default 'sm'
+     */
     size?: Value<ControlSize>;
 }
 /**
- * Create a toolbar for the ProseMirror markdown editor
+ * Creates a formatting toolbar for the ProseMirror markdown editor.
+ *
+ * The toolbar adapts dynamically to the enabled {@link MarkdownFeatures},
+ * showing only the relevant button groups. It integrates with BeatUI's
+ * i18n system for localised button labels and tooltips.
+ *
+ * @param options - Toolbar configuration including the editor view, features, and size.
+ * @returns A `TNode` renderable containing the complete toolbar.
+ *
+ * @example
+ * ```ts
+ * ProseMirrorToolbar({
+ *   view: editorViewSignal,
+ *   stateUpdate: editorStateNotifier,
+ *   features: signal(DEFAULT_FEATURES),
+ *   readOnly: signal(false),
+ *   size: 'sm',
+ * })
+ * ```
  */
-export declare function ProseMirrorToolbar({ view, stateUpdate, features, readOnly, size, }: ProseMirrorToolbarOptions): TNode;
+export declare function ProseMirrorToolbar({ view, stateUpdate, features, readOnly, size, }: ProseMirrorToolbarOptions): import("@tempots/dom").Renderable;

package/dist/types/components/prosemirror/utils.d.ts

@@ -1,12 +1,124 @@
+/**
+ * Utility functions for inspecting ProseMirror editor state.
+ *
+ * Provides helpers to check whether specific marks or nodes are active in the
+ * current selection and to create reactive signals that track mark/node
+ * activity as the user navigates the document.
+ *
+ * @module
+ */
 import { Signal } from '@tempots/dom';
 import { Mark, MarkType, NodeType } from 'prosemirror-model';
 import { EditorState } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
+/**
+ * Checks whether a mark of the given type is active in the current editor
+ * selection.
+ *
+ * Works for both empty (collapsed) and non-empty selections. For empty
+ * selections it also inspects `storedMarks` and adjacent nodes.
+ *
+ * @param state - The current ProseMirror editor state.
+ * @param markType - The mark type to look for.
+ * @returns `true` if the mark type is present in the selection.
+ *
+ * @example
+ * ```ts
+ * const bold = editorView.state.schema.marks.strong
+ * if (isMarkActive(editorView.state, bold)) {
+ *   console.log('Bold is active')
+ * }
+ * ```
+ */
 export declare function isMarkActive(state: EditorState, markType: MarkType): boolean;
+/**
+ * Returns the first `Mark` instance of the given type found in the current
+ * selection, or `null` if no such mark is present.
+ *
+ * For empty (collapsed) selections the function checks, in order:
+ * 1. `storedMarks` (marks queued for the next typed character)
+ * 2. Marks at the resolved cursor position
+ * 3. Marks on the node immediately after the cursor
+ *
+ * For non-empty selections the function iterates over all nodes in the range.
+ *
+ * Comparisons are done by mark-type name to avoid object-identity issues
+ * that can occur with ProseMirror schemas.
+ *
+ * @param state - The current ProseMirror editor state.
+ * @param markType - The mark type to retrieve.
+ * @returns The found `Mark` instance, or `null`.
+ *
+ * @example
+ * ```ts
+ * const linkMark = getMarkByType(editorView.state, editorView.state.schema.marks.link)
+ * if (linkMark) {
+ *   console.log('Link href:', linkMark.attrs.href)
+ * }
+ * ```
+ */
 export declare function getMarkByType(state: EditorState, markType: MarkType): Mark | null;
+/**
+ * Creates a reactive `Signal<boolean>` that tracks whether a mark of the
+ * given type is active in the current ProseMirror selection.
+ *
+ * The signal recomputes whenever the `state` ticker updates (which is
+ * triggered on every editor transaction).
+ *
+ * @param state - A ticker signal that increments on every editor state change.
+ * @param view - A signal holding the current `EditorView`.
+ * @param markType - The name of the mark type to track (e.g. `'strong'`, `'em'`, `'link'`).
+ * @returns A derived `Signal<boolean>` that is `true` when the mark is active.
+ *
+ * @example
+ * ```ts
+ * const isBold = makeActiveMarkSignal(stateUpdate, editorView, 'strong')
+ * isBold.on(active => {
+ *   console.log('Bold active:', active)
+ * })
+ * ```
+ */
 export declare function makeActiveMarkSignal(state: Signal<number>, view: Signal<EditorView>, markType: string): import("@tempots/dom").Computed<boolean>;
 /**
- * Check if a node type is active at the current selection
+ * Checks whether a node of the given type is active at the current selection
+ * position.
+ *
+ * Walks up the document tree from the resolved cursor position and also
+ * checks the node at the exact position. If `attrs` are provided, the
+ * function additionally verifies that the node's attributes match.
+ *
+ * @param state - The current ProseMirror editor state.
+ * @param nodeType - The node type to look for.
+ * @param attrs - Optional attribute constraints to match against the node's attributes.
+ * @returns `true` if a matching node is found in the current selection.
+ *
+ * @example
+ * ```ts
+ * const heading = editorView.state.schema.nodes.heading
+ * if (isNodeActive(editorView.state, heading, { level: 2 })) {
+ *   console.log('Currently inside an H2')
+ * }
+ * ```
  */
 export declare function isNodeActive(state: EditorState, nodeType: NodeType, attrs?: Record<string, unknown>): boolean;
+/**
+ * Creates a reactive `Signal<boolean>` that tracks whether a node of the
+ * given type (and optional attributes) is active at the current selection.
+ *
+ * The signal recomputes whenever the `state` ticker updates.
+ *
+ * @param state - A ticker signal that increments on every editor state change.
+ * @param view - A signal holding the current `EditorView`.
+ * @param nodeTypeName - The name of the node type to track (e.g. `'heading'`, `'bullet_list'`).
+ * @param attrs - Optional attribute constraints (e.g. `{ level: 2 }` for H2 headings).
+ * @returns A derived `Signal<boolean>` that is `true` when the node is active.
+ *
+ * @example
+ * ```ts
+ * const isH2 = makeActiveNodeSignal(stateUpdate, editorView, 'heading', { level: 2 })
+ * isH2.on(active => {
+ *   console.log('Inside H2:', active)
+ * })
+ * ```
+ */
 export declare function makeActiveNodeSignal(state: Signal<number>, view: Signal<EditorView>, nodeTypeName: string, attrs?: Record<string, unknown>): import("@tempots/dom").Computed<boolean>;

package/dist/types/components/theme/style-utils.d.ts

@@ -1,16 +1,111 @@
 import { ThemeColorName } from '../../tokens/colors';
+/**
+ * Extended color type that includes theme colors and the special `'transparent'` value.
+ */
 export type ExtendedColor = ThemeColorName | 'transparent';
+/**
+ * Theme appearance mode.
+ * Either `'light'` or `'dark'`.
+ */
 export type Mode = 'light' | 'dark';
+/**
+ * Background style variant.
+ * - `'solid'`: Full-intensity solid background
+ * - `'light'`: Light, subtle background
+ * - `'soft'`: Medium-intensity background
+ * - `'lighter'`: Very subtle background
+ */
 export type BackgroundVariant = 'solid' | 'light' | 'soft' | 'lighter';
+/**
+ * Foreground color tone for text and icons.
+ * - `'solid'`: High-contrast, vibrant color
+ * - `'soft'`: Lower-contrast, muted color
+ */
 export type ForegroundTone = 'solid' | 'soft';
+/**
+ * Computes background and text colors for a given color, variant, and theme mode.
+ * Applies variant-specific styling (solid, light, soft, lighter) and mode-specific shades.
+ *
+ * @param color - The theme color name
+ * @param variant - The background style variant
+ * @param mode - The theme mode ('light' or 'dark')
+ * @returns An object containing `backgroundColor` and `textColor` CSS values
+ *
+ * @example
+ * ```ts
+ * const { backgroundColor, textColor } = backgroundValue('primary', 'solid', 'light')
+ * // Returns: { backgroundColor: 'var(--color-primary-500)', textColor: 'var(--color-white)' }
+ * ```
+ */
 export declare function backgroundValue(color: ExtendedColor, variant: BackgroundVariant, mode: Mode): {
     backgroundColor: string;
     textColor: string;
 };
+/**
+ * Computes hover state background and text colors for interactive elements.
+ * Applies darker/lighter shades depending on the variant and mode.
+ *
+ * @param color - The theme color name
+ * @param variant - The background style variant ('solid', 'light', or 'soft')
+ * @param mode - The theme mode ('light' or 'dark')
+ * @returns An object containing `backgroundColor` and `textColor` CSS values for hover state
+ *
+ * @example
+ * ```ts
+ * const hover = hoverBackgroundValue('primary', 'solid', 'dark')
+ * // Returns darker shade for hover effect
+ * ```
+ */
 export declare function hoverBackgroundValue(color: ExtendedColor, variant: 'solid' | 'light' | 'soft', mode: Mode): {
     backgroundColor: string;
     textColor: string;
 };
+/**
+ * Computes the border color for a given color and theme mode.
+ * Uses medium-intensity shades (500 for light, 600 for dark).
+ *
+ * @param color - The theme color name
+ * @param mode - The theme mode ('light' or 'dark')
+ * @returns A CSS color value string
+ *
+ * @example
+ * ```ts
+ * const border = borderColorValue('primary', 'light')
+ * // Returns 'var(--color-primary-500)'
+ * ```
+ */
 export declare function borderColorValue(color: ExtendedColor, mode: Mode): string;
+/**
+ * Computes the text color for a given color and theme mode.
+ * Uses high-contrast shades (800 for light, 200 for dark) for readability.
+ *
+ * @param color - The theme color name
+ * @param mode - The theme mode ('light' or 'dark')
+ * @returns A CSS color value string
+ *
+ * @example
+ * ```ts
+ * const text = textColorValue('primary', 'light')
+ * // Returns 'var(--color-primary-800)'
+ * ```
+ */
 export declare function textColorValue(color: ExtendedColor, mode: Mode): string;
+/**
+ * Computes the foreground color (for icons, accents) with a specified tone.
+ * Supports both solid (vibrant) and soft (muted) tones.
+ *
+ * @param color - The theme color name
+ * @param tone - The foreground tone ('solid' for vibrant, 'soft' for muted)
+ * @param mode - The theme mode ('light' or 'dark')
+ * @returns A CSS color value string
+ *
+ * @example
+ * ```ts
+ * const icon = foregroundColorValue('success', 'solid', 'light')
+ * // Returns 'var(--color-success-500)'
+ *
+ * const mutedIcon = foregroundColorValue('success', 'soft', 'light')
+ * // Returns 'var(--color-success-300)'
+ * ```
+ */
 export declare function foregroundColorValue(color: ThemeColorName, tone: ForegroundTone, mode: Mode): string;

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

@@ -1,9 +1,48 @@
 import { Provider } from '@tempots/dom';
 import '../../styles/index.css';
 import { AppearancePreference, ThemeValue } from './types';
+/**
+ * Configuration options for the Theme provider.
+ */
 export interface ThemeOptions {
+    /** Initial appearance preference. Defaults to `'system'`. */
     defaultAppearance?: AppearancePreference;
+    /** localStorage key for persisting appearance preference. Defaults to `'bui-appearance'`. */
     appearancePreferenceKey?: string;
 }
+/**
+ * Theme provider that manages light/dark appearance mode.
+ * Tracks system appearance, user preference, and persists settings to localStorage.
+ * The resolved appearance is available as a reactive signal.
+ *
+ * @example
+ * ```ts
+ * import { Provide } from '@tempots/dom'
+ * import { Theme } from '@tempots/beatui'
+ *
+ * Provide(Theme, { defaultAppearance: 'dark' },
+ *   html.div({},
+ *     html.p({}, 'Theme is active!')
+ *   )
+ * )
+ * ```
+ */
 export declare const Theme: Provider<ThemeValue, ThemeOptions>;
+/**
+ * Reactive attribute that applies the current theme appearance as a CSS class.
+ * Maps the resolved appearance ('light' or 'dark') to class names `'b-light'` or `'b-dark'`.
+ * Typically attached to the document body or root element.
+ *
+ * @returns A reactive `attr.class` attribute
+ *
+ * @example
+ * ```ts
+ * import { html } from '@tempots/dom'
+ * import { ThemeAppearance } from '@tempots/beatui'
+ *
+ * html.body(ThemeAppearance(),
+ *   html.div({}, 'Content inherits theme appearance')
+ * )
+ * ```
+ */
 export declare const ThemeAppearance: () => import("@tempots/dom").Renderable;