h2o-library 1.7.1 → 2.0.0

package/dist/types/components/src/toggle/toggle.d.ts

@@ -0,0 +1,35 @@
+import "./toggle.css";
+import React from "react";
+import type { TooltipPosition } from "../../../types";
+type BaseToggleProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> & {
+    label?: string;
+    description?: string;
+    containerClassName?: string;
+    size?: "sm" | "md" | "lg";
+    error?: string;
+    note?: string;
+    tooltip?: string;
+    tooltipPosition?: TooltipPosition;
+};
+type CardToggleProps = BaseToggleProps & {
+    isCard: true;
+    isDraggable?: boolean;
+};
+type InlineToggleProps = BaseToggleProps & {
+    isCard?: false;
+    isDraggable?: never;
+};
+/**
+ * Discriminated union: `isCard: true` enables card layout and optional `isDraggable`; otherwise inline switch.
+ * `size` is visual (`"sm"|"md"|"lg"`), not the HTML `size` attribute.
+ */
+type ToggleProps = CardToggleProps | InlineToggleProps;
+/**
+ * Switch UI backed by a checkbox input; supports inline, card, draggable card, and label tooltip.
+ *
+ * @param {ToggleProps} props - Union of card vs inline props; `ref` targets the `input`.
+ * @param {React.Ref<HTMLInputElement>} ref - Native checkbox ref.
+ * @returns {React.ReactElement} The toggle wrapper and `input` + visual thumb track.
+ */
+export declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/types/components/src/tooltip/tooltip.d.ts

@@ -0,0 +1,38 @@
+import "./tooltip.css";
+import type React from "react";
+import type { TooltipPosition } from "../../../types";
+type BaseProps = {
+    position?: TooltipPosition;
+    className?: string;
+    contentClassName?: string;
+    children: React.ReactNode;
+    variant?: "dark" | "light";
+    delay?: number;
+    maxWidth?: string | number;
+};
+type TextTooltip = BaseProps & {
+    text: string;
+    content?: never;
+};
+type ContentTooltip = BaseProps & {
+    content: React.ReactNode;
+    text?: never;
+};
+/**
+ * Props for `Tooltip`: **either** `text` (plain string) **or** `content` (rich `ReactNode`), not both.
+ *
+ * @property {import("../../../types").TooltipPosition} [position] - Placement vs the trigger. Default `"top"`.
+ * @property {React.ReactNode} children - Trigger element(s) wrapped for hover/focus.
+ * @property {"dark"|"light"} [variant] - Surface style. Default `"dark"`.
+ * @property {number} [delay] - Show delay in ms. Default `0`.
+ * @property {string|number} [maxWidth] - Tooltip body max width (CSS value).
+ */
+type TooltipProps = TextTooltip | ContentTooltip;
+/**
+ * Hover/focus tooltip: positions in a `createPortal` layer, hides on scroll (capture), and supports string or custom body.
+ *
+ * @param {TooltipProps} props - `text` XOR `content`, plus `children` as trigger.
+ * @returns {JSX.Element | null} Wrapper around `children` and the portaled bubble when visible.
+ */
+export declare const Tooltip: React.FC<TooltipProps>;
+export {};

package/dist/types/entries/charts.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath entry: `h2o-library/charts`
+ */
+export * from "../charts/index";

package/dist/types/entries/hooks.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath entry: `h2o-library/hooks`
+ */
+export * from "../hooks";

package/dist/types/entries/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Subpath entry: `h2o-library/types`
+ * Type-only re-exports (no runtime values). Requires TypeScript 5+.
+ */
+export type * from "../types";
+export type * from "../hooks";
+export type * from "../components";
+export type * from "../charts";
+export type * from "../utils";

package/dist/types/entries/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Subpath entry: `h2o-library/utils`
+ * Runtime utilities (e.g. `cn`). No React component surface.
+ */
+export * from "../utils";

package/dist/types/hooks/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./src/use-click-outside";
+export * from "./src/use-copy-to-clipboard";
+export * from "./src/use-debounce";
+export * from "./src/use-event-listener";
+export { useEventListener as useEventListner } from "./src/use-event-listener";
+export * from "./src/use-dropdown-position";
+export * from "./src/use-focus-trap";
+export * from "./src/use-idle";
+export * from "./src/use-interval";
+export * from "./src/use-hover";
+export * from "./src/use-key-press";
+export * from "./src/use-long-press";
+export * from "./src/use-media-query";
+export * from "./src/use-mouse";
+export * from "./src/use-timeout";
+export { useToast, ToastContext, type ToastContextType } from "./src/use-toast";
+export * from "./src/use-window-scroll";
+export * from "./src/use-window-size";

package/dist/types/hooks/src/use-click-outside.d.ts

@@ -0,0 +1,13 @@
+import type { RefObject } from "react";
+type Handler = (event: MouseEvent | TouchEvent) => void;
+/**
+ * Run a handler when the user clicks/taps outside a referenced element.
+ *
+ * Commonly used to close popovers, dropdowns, menus, and dialogs.
+ *
+ * @param ref - Element ref that defines the “inside” area.
+ * @param handler - Called when an outside interaction happens.
+ * @param mouseEvent - Which mouse event to listen for (defaults to `"mousedown"`).
+ */
+export declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T>, handler: Handler, mouseEvent?: "mousedown" | "mouseup"): void;
+export {};

package/dist/types/hooks/src/use-copy-to-clipboard.d.ts

@@ -0,0 +1,15 @@
+export type UseCopyToClipboardState = {
+    copied: boolean;
+    error: Error | null;
+};
+/**
+ * Copy text to the system clipboard and track success for UI feedback.
+ *
+ * @param resetDelay - If set, `copied` resets to `false` after this many ms. @defaultValue 2000
+ * @returns `copy` function and `copied` / `error` state.
+ */
+export declare function useCopyToClipboard(resetDelay?: number): {
+    readonly copy: (text: string) => Promise<boolean>;
+    readonly copied: boolean;
+    readonly error: Error | null;
+};

package/dist/types/hooks/src/use-debounce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a value that only updates `delay` ms after `value` stops changing
+ * (leading/trailing: trailing only).
+ *
+ * @param value - Source value (often a string from an input).
+ * @param delay - Debounce window in ms.
+ * @returns The last stable value after the quiet period.
+ */
+export declare function useDebounce<T>(value: T, delay: number): T;

package/dist/types/hooks/src/use-dropdown-position.d.ts

@@ -0,0 +1,10 @@
+import type { RefObject } from "react";
+/**
+ * Decide whether a dropdown/menu should open above or below its trigger.
+ *
+ * @param containerRef - Ref to the trigger/container element.
+ * @param isOpen - Only measures while open.
+ * @param direction - Force `"top"`/`"bottom"` or let it auto-detect.
+ * @param menuHeight - Expected menu height (px) used for the calculation.
+ */
+export declare function useDropdownPosition(containerRef: RefObject<HTMLElement>, isOpen: boolean, direction?: "top" | "bottom" | "auto", menuHeight?: number): "top" | "bottom";

package/dist/types/hooks/src/use-event-listener.d.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from "react";
+type AddOptions = boolean | AddEventListenerOptions;
+/**
+ * Subscribes to a DOM `EventTarget` and keeps the latest `handler` without
+ * re-attaching on every render.
+ *
+ * @param event - Event name (e.g. `\"resize\"`, `\"click\"`).
+ * @param handler - Listener invoked when the event fires.
+ * @param target - `window` when `undefined`, nothing when `null`, the ref’s
+ *   `current` when a ref, or a raw element.
+ * @param options - Same as `addEventListener`’s third argument.
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (ev: WindowEventMap[K]) => void, target?: RefObject<EventTarget | null> | EventTarget | null, options?: AddOptions): void;
+export declare function useEventListener(event: string, handler: (ev: Event) => void, target?: RefObject<EventTarget | null> | EventTarget | null, options?: AddOptions): void;
+export {};

package/dist/types/hooks/src/use-focus-trap.d.ts

@@ -0,0 +1,8 @@
+import type { RefObject } from "react";
+/**
+ * Trap keyboard focus inside a container while `active` is true.
+ *
+ * @param ref - Container element that should contain focus.
+ * @param active - Enables/disables the trap.
+ */
+export declare function useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void;

package/dist/types/hooks/src/use-hover.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tracks whether the pointer is over a given element.
+ *
+ * @returns A tuple: `isHovered` and a **ref callback** to pass to a host element’s
+ *   `ref` prop (stores the node and wires `mouseenter` / `mouseleave`).
+ */
+export declare function useHover<T extends HTMLElement = HTMLElement>(): [
+    boolean,
+    (node: T | null) => void
+];

package/dist/types/hooks/src/use-idle.d.ts

@@ -0,0 +1,15 @@
+export type UseIdleOptions = {
+    /**
+     * DOM events on `window` that reset the idle timer. @defaultValue common
+     * user interaction events.
+     */
+    events?: Array<keyof WindowEventMap>;
+};
+/**
+ * Returns `true` when the user has been inactive (no registered events) for at least `ms`.
+ *
+ * @param ms - Idle duration in milliseconds.
+ * @param options - Optional list of `window` events that count as activity.
+ * @returns Whether the user is currently considered idle.
+ */
+export declare function useIdle(ms: number, options?: UseIdleOptions): boolean;

package/dist/types/hooks/src/use-interval.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repeats `callback` every `delay` ms. Pauses when `delay` is `null`.
+ *
+ * @param callback - Function called on each tick.
+ * @param delay - Interval in ms, or `null` to clear the interval.
+ */
+export declare function useInterval(callback: () => void, delay: number | null): void;

package/dist/types/hooks/src/use-key-press.d.ts

@@ -0,0 +1,13 @@
+type KeyTarget = string | readonly string[];
+/**
+ * Listens for `keydown` on `window` and either reports whether a key is held
+ * or runs a callback on each matching press.
+ *
+ * @param key - `KeyboardEvent.key` value, or a list of keys.
+ * @param handler - If provided, called for each matching `keydown`; no return value.
+ * @returns If `handler` is omitted: whether the key is currently held (`keydown`
+ *   without a matching `keyup` yet). If `handler` is provided: `undefined`.
+ */
+export declare function useKeyPress(key: KeyTarget, handler: (event: KeyboardEvent) => void): void;
+export declare function useKeyPress(key: KeyTarget, handler?: undefined): boolean;
+export {};

package/dist/types/hooks/src/use-long-press.d.ts

@@ -0,0 +1,20 @@
+import type { MouseEvent, PointerEvent } from "react";
+export type UseLongPressOptions = {
+    delay?: number;
+    moveThreshold?: number;
+    onClick?: (event: MouseEvent<HTMLElement> | PointerEvent<HTMLElement>) => void;
+};
+/**
+ * Pointer handlers to attach to an element to detect a long-press (hold) vs a short click.
+ *
+ * @param onLongPress - Invoked if the pointer stays down for `delay` without excess movement.
+ * @param options - Timing, move tolerance, and optional short-click handler.
+ * @returns Props to spread on a host element (`onPointerDown`, `onPointerMove`, `onPointerUp`, etc.).
+ */
+export declare function useLongPress(onLongPress: (event: React.PointerEvent<HTMLElement>) => void, options?: UseLongPressOptions): {
+    readonly onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerMove: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerUp: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerCancel: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerLeave: (event: React.PointerEvent<HTMLElement>) => void;
+};

package/dist/types/hooks/src/use-media-query.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Subscribe to a media query and get whether it currently matches.
+ *
+ * @param query - Any valid CSS media query, e.g. `\"(min-width: 768px)\"`.
+ * @returns `true` when the query matches.
+ */
+export declare const useMediaQuery: (query: string) => boolean;

package/dist/types/hooks/src/use-mouse.d.ts

@@ -0,0 +1,12 @@
+export type MouseState = {
+    x: number;
+    y: number;
+    hasMoved: boolean;
+};
+/**
+ * Tracks the latest pointer position from `window` `pointermove` / `mousemove` events.
+ *
+ * @param enabled - When `false`, stops listening. @defaultValue true
+ * @returns Last coordinates and whether a move has been observed.
+ */
+export declare function useMouse(enabled?: boolean): MouseState;

package/dist/types/hooks/src/use-timeout.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs `callback` once after `delay` ms. The timer resets when `delay` or
+ * `callback` identity changes; set `delay` to `null` to cancel.
+ *
+ * @param callback - Function to invoke after the delay.
+ * @param delay - Milliseconds, or `null` to skip scheduling.
+ */
+export declare function useTimeout(callback: () => void, delay: number | null): void;

package/dist/types/hooks/src/use-toast.d.ts

@@ -0,0 +1,15 @@
+import type { ToastOptions } from "../../components/src/toast/toast";
+/**
+ * Return type of `useToast()`: imperative API to show and remove toasts.
+ */
+export interface ToastContextType {
+    /** Show a toast. Returns the toast id. */
+    show: (options: ToastOptions) => string;
+    /** Programmatically dismiss a toast by id. */
+    dismiss: (id: string) => void;
+}
+export declare const ToastContext: import("react").Context<ToastContextType | undefined>;
+/**
+ * Subscribes to the toast context; throws if `ToastProvider` is not an ancestor.
+ */
+export declare const useToast: () => ToastContextType;

package/dist/types/hooks/src/use-window-scroll.d.ts

@@ -0,0 +1,10 @@
+export type WindowScrollState = {
+    x: number;
+    y: number;
+};
+/**
+ * Subscribes to `window` scroll and returns the current `scrollX` / `scrollY`.
+ *
+ * @returns Latest scroll offsets; `{ x: 0, y: 0 }` during SSR.
+ */
+export declare function useWindowScroll(): WindowScrollState;

package/dist/types/hooks/src/use-window-size.d.ts

@@ -0,0 +1,10 @@
+export type WindowSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Subscribes to `window` `resize` and returns `innerWidth` / `innerHeight`.
+ *
+ * @returns Viewport size; `{ width: 0, height: 0 }` before mount / during SSR.
+ */
+export declare function useWindowSize(): WindowSize;

package/dist/types/index.cjs.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=index.cjs.js.map

package/dist/types/index.d.ts

@@ -1,2 +1,9 @@
-export type TooltipPosition = "top" | "bottom" | "left" | "right";
-export * from "./src/icon";
+/**
+ * Subpath entry: `h2o-library/types`
+ * Type-only re-exports (no runtime values). Requires TypeScript 5+.
+ */
+export type * from "./types";
+export type * from "./hooks";
+export type * from "./components";
+export type * from "./charts";
+export type * from "./utils";

package/dist/types/index.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=index.js.map

package/dist/types/src/icon.d.ts

@@ -1 +1 @@
-export type IconType = "plus" | "minus" | "chevron-right" | "chevron-down" | "chevron-left" | "chevron-up" | "home" | "close" | "drag-handle" | "search" | "info" | "calendar" | "calendar-check" | "user" | "sort-up" | "sort-down" | "clock" | "wand" | "bell" | "trash" | "filter" | "building" | "envelope" | "stats" | "log-out" | "log-in" | "edit" | "eye" | "eye-off" | "image" | "settings" | "upload" | "download" | "note" | "arrow-up" | "arrow-down" | "double-chevron-right" | "double-chevron-left" | "chevrons-y" | "chevrons-x" | "sort" | "coffee" | "bell-filled" | "dots-horizontal" | "dots-vertical" | "layout" | "check" | "chevron-up-down" | "list" | "select-size" | "copy" | "cut" | "paste" | "swap" | "shuffle" | "compact-view" | "relaxed-view" | "send" | "phone" | "users" | "hint" | "forbidden" | "inbox" | "message" | "bold" | "italic" | "underline" | "strikethrough" | "quote" | "list-ul" | "list-ol" | "comment" | "link" | "undo" | "redo" | "align-left" | "align-center" | "align-right";
+export type IconType = "alert" | "align-center" | "align-left" | "align-right" | "arrow-down" | "arrow-down-narrow-wide" | "arrow-down-wide-narrow" | "arrow-left" | "arrow-right" | "arrow-up" | "arrow-up-narrow-wide" | "arrow-up-wide-narrow" | "bell" | "bell-ring" | "bold" | "building" | "calendar" | "calendar-check" | "calendar-clock" | "calendar-cog" | "calendar-plus" | "calendar-sync" | "camera" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "chevron-up" | "chevrons-x" | "chevrons-y" | "clock" | "clock-alert" | "close" | "coffee" | "comment" | "compact-view" | "copy" | "cut" | "dashboard" | "dots-horizontal" | "dots-vertical" | "double-chevron-left" | "double-chevron-right" | "download" | "drag-handle" | "edit" | "envelope" | "external-link" | "eye" | "eye-off" | "file" | "file-code" | "filter" | "filter-plus" | "flag" | "forbidden" | "grid" | "hint" | "hospital" | "home" | "image" | "inbox" | "info" | "italic" | "layout" | "library" | "link" | "list" | "list-ol" | "list-ul" | "log-in" | "log-out" | "maximize" | "message" | "minimize" | "minus" | "note" | "paste" | "phone" | "plus" | "quote" | "redo" | "refresh" | "relaxed-view" | "search" | "send" | "settings" | "shuffle" | "stats" | "strikethrough" | "swap" | "swap-vertical" | "trash" | "underline" | "undo" | "upload" | "user" | "user-check" | "users" | "wand" | "zoom-in" | "zoom-out" | "sort" | "sun" | "moon" | "tool" | "hook" | "component" | "arrow-up-right" | "chart" | "star" | "sparkles" | "terminal" | "shield" | "code";

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

@@ -0,0 +1,2 @@
+export type TooltipPosition = "top" | "bottom" | "left" | "right";
+export * from "./src/icon";

package/dist/types/types/src/icon.d.ts

@@ -0,0 +1 @@
+export type IconType = "alert" | "align-center" | "align-left" | "align-right" | "arrow-down" | "arrow-down-narrow-wide" | "arrow-down-wide-narrow" | "arrow-left" | "arrow-right" | "arrow-up" | "arrow-up-narrow-wide" | "arrow-up-wide-narrow" | "bell" | "bell-ring" | "bold" | "building" | "calendar" | "calendar-check" | "calendar-clock" | "calendar-cog" | "calendar-plus" | "calendar-sync" | "camera" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "chevron-up" | "chevrons-x" | "chevrons-y" | "clock" | "clock-alert" | "close" | "coffee" | "comment" | "compact-view" | "copy" | "cut" | "dashboard" | "dots-horizontal" | "dots-vertical" | "double-chevron-left" | "double-chevron-right" | "download" | "drag-handle" | "edit" | "envelope" | "external-link" | "eye" | "eye-off" | "file" | "file-code" | "filter" | "filter-plus" | "flag" | "forbidden" | "grid" | "hint" | "hospital" | "home" | "image" | "inbox" | "info" | "italic" | "layout" | "library" | "link" | "list" | "list-ol" | "list-ul" | "log-in" | "log-out" | "maximize" | "message" | "minimize" | "minus" | "note" | "paste" | "phone" | "plus" | "quote" | "redo" | "refresh" | "relaxed-view" | "search" | "send" | "settings" | "shuffle" | "stats" | "strikethrough" | "swap" | "swap-vertical" | "trash" | "underline" | "undo" | "upload" | "user" | "user-check" | "users" | "wand" | "zoom-in" | "zoom-out" | "sort" | "sun" | "moon" | "tool" | "hook" | "component" | "arrow-up-right" | "chart" | "star" | "sparkles" | "terminal" | "shield" | "code";

package/dist/types/utils/index.d.ts

@@ -0,0 +1,7 @@
+export { cn } from "./src/cn";
+export * from "./src/object";
+export * from "./src/array";
+export * from "./src/string";
+export * from "./src/format";
+export * from "./src/math";
+export * from "./src/async";

package/dist/types/utils/src/array.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @returns A new list with only the first occurrence of each value (uses `Set`, reference equality for objects).
+ */
+export declare function unique<T>(array: readonly T[]): T[];
+/**
+ * @param key - Returns a key used to de-dupe; first item wins.
+ */
+export declare function uniqueBy<T, K extends string | number | boolean | bigint | null | undefined>(array: readonly T[], key: (item: T) => K): T[];
+/**
+ * @returns Record: each key maps to items in that group.
+ */
+export declare function groupBy<T, K extends string | number | symbol>(array: readonly T[], key: (item: T) => K): Record<K, T[]>;
+/**
+ * @returns Tuple `[passing, failing]`.
+ */
+export declare function partition<T>(array: readonly T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * Non-mutating sort by a string or number key. `undefined` sorts last in ascending order.
+ */
+export declare function sortBy<T>(array: readonly T[], key: (item: T) => string | number | undefined, order?: "asc" | "desc"): T[];
+/**
+ * If `end` is omitted, returns `0..n-1`. Otherwise returns numbers from `start` (inclusive) to `end` (exclusive) with `step`.
+ */
+export declare function range(nOrStart: number, end?: number, step?: number): number[];

package/dist/types/utils/src/async.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolves after `ms` (or immediately if `ms <= 0`).
+ */
+export declare function sleep(ms: number): Promise<void>;
+export type DebouncedFunction<T extends (...args: never[]) => unknown> = ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * Trailing debounce with `cancel()`.
+ */
+export declare function debounce<T extends (...args: never[]) => unknown>(func: T, waitMs: number): DebouncedFunction<T>;
+export type ThrottledFunction<T extends (...args: never[]) => unknown> = ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * Throttle with trailing scheduling; `cancel()` clears a pending run.
+ */
+export declare function throttle<T extends (...args: never[]) => unknown>(func: T, waitMs: number): ThrottledFunction<T>;
+export type RetryOptions = {
+    attempts: number;
+    delay?: number;
+    backoff?: number;
+};
+/**
+ * Retry async work with optional delay and multiplicative backoff between attempts.
+ */
+export declare function retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/**
+ * Reject with `Error(message)` if `ms` elapses before `promise` settles.
+ * Does not cancel the underlying work.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;

package/dist/types/utils/src/cn.d.ts

@@ -0,0 +1,9 @@
+import { type ClassValue } from "clsx";
+/**
+ * Tailwind-friendly `className` combiner. Uses `clsx` for conditional lists and
+ * `tailwind-merge` to drop conflicting utility classes.
+ *
+ * @param inputs - `clsx` input list (strings, objects, arrays, falsy to omit).
+ * @returns A single merged `class` string.
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/types/utils/src/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Human-readable file size; binary 1024 scale.
+ */
+export declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * `Intl.NumberFormat` wrapper. Non-finite returns `String(n)`.
+ */
+export declare function formatNumber(n: number, options?: Intl.NumberFormatOptions, locale?: string): string;
+/**
+ * @param value - `Date` or ms timestamp; invalid date yields empty string
+ */
+export declare function formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * `Intl.RelativeTimeFormat` for value vs base. Uses a coarse best unit.
+ */
+export declare function formatRelative(value: Date | number, base?: Date | number, locale?: string): string;
+/**
+ * Same local calendar day.
+ */
+export declare function isSameDay(a: Date, b: Date): boolean;

package/dist/types/utils/src/math.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @param n - Value
+ * @param min - Inclusive min (swapped with max if `min > max`)
+ * @param max - Inclusive max
+ */
+export declare function clamp(n: number, min: number, max: number): number;
+/**
+ * Round to a number of fraction digits.
+ */
+export declare function round(n: number, decimals?: number): number;
+/**
+ * Linear interpolation: `a + (b - a) * t`.
+ */
+export declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Inclusive or exclusive (open interval) check between min and max.
+ */
+export declare function inRange(n: number, min: number, max: number, exclusive?: boolean): boolean;
+/**
+ * safe `toFixed` for non-finite numbers: returns `fallback` instead of `"NaN"`.
+ */
+export declare function toFixedSafe(n: number, fractionDigits?: number, fallback?: string): string;

package/dist/types/utils/src/object.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @param object - Source object.
+ * @param keys - Keys to keep on the new object.
+ * @returns A new object with only the given keys.
+ */
+export declare function pick<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * @param object - Source object.
+ * @param keys - Keys to remove (shallow copy without these keys).
+ * @returns A new object without the listed keys.
+ */
+export declare function omit<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Omit<T, K>;
+/**
+ * @param value - Any value to test.
+ * @returns `true` if `value` is a plain object (including `{}`, not `null`, not a class instance).
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Shallow merge: later keys overwrite earlier ones. Arrays and nested objects
+ * are not deeply merged; use `deepMerge` for plain object trees.
+ *
+ * @param target - First object; result is a shallow copy of this plus sources.
+ * @param sources - Any number of partial objects to merge in order.
+ */
+export declare function merge<T extends object>(target: T, ...sources: Array<Partial<T> | object>): T;
+/**
+ * Deep-merge plain objects only. Arrays are treated as values (replaced).
+ * `undefined` in the source does not clear an existing value.
+ */
+export declare function deepMerge<T extends object>(target: T, source: object): T;
+/**
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns `true` if both are `Object.is` or share same own enumerable keys with `Object.is` per key.
+ */
+export declare function isShallowEqual(a: unknown, b: unknown): boolean;

package/dist/types/utils/src/string.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @returns First character uppercased, rest unchanged (empty string unchanged).
+ */
+export declare function capitalize(s: string): string;
+/**
+ * Title-case by uppercasing the first char of each whitespace-separated word.
+ */
+export declare function toTitleCase(s: string): string;
+/**
+ * @param maxLength - Max length of result string including `suffix` when truncating.
+ */
+export declare function truncate(s: string, maxLength: number, suffix?: string): string;
+/**
+ * URL-ish slug: lowercase, trim, spaces/underscores to hyphens, strip non a-z0-9 hyphen.
+ */
+export declare function slugify(s: string): string;
+/**
+ * `foo_bar` or `foo bar` to `fooBar`.
+ */
+export declare function camelCase(s: string): string;
+/**
+ * `fooBar` or `foo bar` to `foo-bar`.
+ */
+export declare function kebabCase(s: string): string;

package/dist/utils/charts/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./src/chart/chart";
+export * from "./src/bar/chart-bar";
+export * from "./src/pie/chart-pie";
+export * from "./src/line/chart-line";
+export * from "./src/heatmap/chart-heatmap";
+export * from "./src/stat/chart-stat";
+export * from "./src/gantt/chart-gantt";
+export * from "./src/legend/legend";

package/dist/utils/charts/src/bar/chart-bar.d.ts

@@ -0,0 +1,27 @@
+import type React from "react";
+import "../../charts.css";
+export interface BarChartDataPoint {
+    x: string;
+    [key: string]: number | string;
+}
+export interface BarSeriesConfig {
+    key: string;
+    label?: string;
+    color: string;
+    unit?: string;
+    stackId?: string;
+}
+export interface BarChartProps {
+    data: BarChartDataPoint[];
+    bars: BarSeriesConfig[];
+    layout?: "single" | "grouped" | "stacked" | "grouped-stacked";
+    orientation?: "vertical" | "horizontal";
+    showGrid?: boolean;
+    showLegend?: boolean;
+    height?: number;
+    className?: string;
+    onXAxisTickClick?: (value: string | number, event: React.MouseEvent) => void;
+    onYAxisTickClick?: (value: string | number, event: React.MouseEvent) => void;
+    onBarClick?: (dataPoint: BarChartDataPoint, index: number, dataKey: string, event: React.MouseEvent<SVGElement>) => void;
+}
+export declare const BarChart: ({ data, bars, layout, orientation, showGrid, showLegend, height, className, onXAxisTickClick, onYAxisTickClick, onBarClick, }: BarChartProps) => import("react/jsx-runtime").JSX.Element;