h2o-library 1.8.0 → 2.0.1

package/dist/components/src/table/table.d.ts

@@ -0,0 +1,78 @@
+import "./table.css";
+import React from "react";
+/**
+ * Sort state for a column: ascending, descending, or unsorted.
+ * @type {("asc"|"desc"|null)}
+ */
+export type SortDirection = "asc" | "desc" | null;
+/**
+ * One column: accessor `key` maps to `row[key]`, with optional `render` for custom cells.
+ * @template T - Row type.
+ * @property {string} key - Object key on each row, or a synthetic key for custom columns.
+ * @property {boolean} [sortable] - When `true` and `onSort` is provided, header is clickable.
+ * @property {function(unknown, T): React.ReactNode} [render] - If omitted, `String(row[key])` is used.
+ */
+export interface TableColumn<T> {
+    key: string;
+    label: string;
+    sortable?: boolean;
+    minWidth?: string;
+    maxWidth?: string;
+    width?: string;
+    render?: (value: unknown, row: T) => React.ReactNode;
+}
+/**
+ * @template T - Row object type; keys should match `TableColumn.key` where possible.
+ * Full data grid: sort, optional row selection, column edit popover (drag/drop + visibility), pagination, loading.
+ *
+ * @property {TableColumn<T>[]} columns - Column defs; can include a synthetic `__selection` for checkboxes.
+ * @property {T[]} data - Rows to render; order is preserved.
+ * @property {string} [sortKey] - **Controlled** sort column; use with `sortDirection` and `onSort`.
+ * @property {SortDirection} [sortDirection] - Current direction for `sortKey`.
+ * @property {boolean} [columnsEditable] - Enables “Edit columns” popover. Default `false`.
+ * @property {string[]} [visibleColumns] - **Controlled** list of column keys to show. Pair with `onVisibleColumnsChange`.
+ * @property {T[]} [selectedRows] - **Controlled** selected rows. Pair with `onSelectionChange` and `rowKey`.
+ * @property {keyof T} [rowKey] - Unique key field on `T` for selection identity. Often `"id"`.
+ * @property {number} [currentPage] - 1-based page index when `Pagination` is used.
+ * @property {string} [maxHeight] - Max height of the scrollable table body.
+ */
+interface TableProps<T extends Record<string, unknown>> {
+    columns: TableColumn<T>[];
+    data: T[];
+    isLoading?: boolean;
+    className?: string;
+    containerClassName?: string;
+    rowHeight?: string;
+    sortKey?: string;
+    sortDirection?: SortDirection;
+    columnsEditable?: boolean;
+    currentPage?: number;
+    totalPages?: number;
+    perPage?: number;
+    perPageOptions?: {
+        label: string;
+        value: number;
+    }[];
+    onSort?: (key: string, direction: SortDirection) => void;
+    onPageChange?: (page: number) => void;
+    onPerPageChange?: (perPage: number) => void;
+    onVisibleColumnsChange?: (keys: string[]) => void;
+    maxHeight?: string;
+    visibleColumns?: string[];
+    maxVisibleColumns?: number;
+    defaultVisibleColumns?: string[];
+    trailingColumns?: string[];
+    selectedRows?: T[];
+    onSelectionChange?: (rows: T[]) => void;
+    rowKey?: keyof T;
+    onRowClick?: (row: T, rowIndex: number) => void;
+}
+/**
+ * Renders a full-featured table: headers, body, optional selection column, sort indicators, edit-columns popover, and pagination.
+ *
+ * @template T - Row record type.
+ * @param {object} props - Column definitions, data, and optional controlled sorting / pagination / selection.
+ * @returns {JSX.Element} The table shell, scroll region, and optional `Pagination` / `Loader`.
+ */
+export declare function Table<T extends Record<string, unknown>>({ columns, data, isLoading, className, rowHeight, sortKey, sortDirection, onSort, currentPage, totalPages, perPage, perPageOptions, onPageChange, onPerPageChange, maxHeight, columnsEditable, containerClassName, visibleColumns, onVisibleColumnsChange, maxVisibleColumns, defaultVisibleColumns, trailingColumns, selectedRows, onSelectionChange, rowKey, onRowClick, }: TableProps<T>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/src/tabs/tabs.d.ts

@@ -0,0 +1,35 @@
+import "./tabs.css";
+/**
+ * One entry in a `Tabs` `tabs` list.
+ * @property {string} value - Emitted to `onChange` when the tab is activated.
+ */
+export type TabItem = {
+    label: string;
+    value: string;
+    disabled?: boolean;
+};
+/**
+ * **Controlled** tab strip: `selectedTab` must match a `TabItem.value` for the active state.
+ *
+ * @property {TabItem[]} tabs - Tab metadata; `disabled` items are skipped in keyboard nav.
+ * @property {string} selectedTab - Current `value` of the active tab.
+ * @property {(value: string) => void} onChange - Fires with the new tab `value` on click or keyboard.
+ * @property {"sm"|"md"|"lg"} [size] - Size token for the tab list. Default `"md"`.
+ */
+interface TabsProps {
+    tabs: TabItem[];
+    selectedTab: string;
+    onChange: (tab: string) => void;
+    ariaLabel?: string;
+    size?: "sm" | "md" | "lg";
+    tabClassName?: string;
+    className?: string;
+}
+/**
+ * Renders a `tablist` with one `button` per tab, roving tabindex, and arrow-key / Home / End support.
+ *
+ * @param {TabsProps} props - `tabs` / `selectedTab` / `onChange` plus `ariaLabel` for the list.
+ * @returns {JSX.Element} The horizontal tab list.
+ */
+export declare const Tabs: ({ tabs, selectedTab, onChange, ariaLabel, size, tabClassName, className, }: TabsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/src/tag/tag.d.ts

@@ -0,0 +1,26 @@
+import "./tag.css";
+import React from "react";
+/**
+ * Removable label chip with primary/secondary styles and sizes.
+ *
+ * @property {string} label - Visible text and remove `aria-label` source.
+ * @property {"primary"|"secondary"} [variant] - Color scheme. Default `"primary"`.
+ * @property {"sm"|"md"|"lg"} [size] - Typographic and hit-target scale. Default `"md"`.
+ * @property {() => void} onRemove - Fires when the user clicks the “×” control.
+ */
+type TagProps = {
+    label: string;
+    variant?: "primary" | "secondary";
+    size?: "sm" | "md" | "lg";
+    onRemove: () => void;
+    className?: string;
+};
+/**
+ * A dismissible tag used in multi-selects and filter lists; forwards ref to the root `div`.
+ *
+ * @param {TagProps} props - `label`, `onRemove`, and presentation props.
+ * @param {React.Ref<HTMLDivElement>} ref - Root element ref.
+ * @returns {React.ReactElement} The tag row and remove button.
+ */
+export declare const Tag: React.ForwardRefExoticComponent<TagProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/src/textarea/textarea.d.ts

@@ -0,0 +1,33 @@
+import "./textarea.css";
+import React from "react";
+import type { TooltipPosition } from "../../../types";
+/**
+ * Props for `Textarea`: extends `HTMLTextAreaElement` attributes (omits legacy HTML `size`).
+ *
+ * @property {string} [label] - Optional field label with optional info tooltip.
+ * @property {boolean} [showClear] - Renders clear when non-empty. Default `false`.
+ * @property {string} [note] - Helper line under the field.
+ * @property {string} [error] - Error line; invalid styling when set.
+ * @property {number} [maxLength] - When set, shows a live character counter vs this cap (e.g., 12/200).
+ * @property {"none"|"vertical"} [resize] - CSS resize mode. Default `"none"`.
+ */
+interface TextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size"> {
+    label?: string;
+    showClear?: boolean;
+    note?: string;
+    error?: string;
+    containerClassName?: string;
+    tooltip?: string;
+    tooltipPosition?: TooltipPosition;
+    maxLength?: number;
+    resize?: "none" | "vertical";
+}
+/**
+ * Multi-line input with label, clear, optional counter from `maxLength`, and note/error rows.
+ *
+ * @param {TextareaProps} props - Native `textarea` props plus H2O chrome.
+ * @param {React.Ref<HTMLTextAreaElement>} ref - Forwarded to `<textarea>`.
+ * @returns {React.ReactElement} Labeled field wrapper and counter when applicable.
+ */
+export declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+export {};

package/dist/components/src/time-picker/time-picker.d.ts

@@ -0,0 +1,31 @@
+import "./time-picker.css";
+/**
+ * Time selection UI: one clock or a start/end **range**; hour/minute columns with optional 12h format.
+ *
+ * @property {"single"|"range"} [mode] - `single` uses `value` as `string | null`; `range` as `[string|null, string|null]`. Default `"single"`.
+ * @property {string|null|[string|null,string|null]} [value] - `"HH:MM"`, partial `"HH:"` while picking hour, or `null` for empty. Range: tuple of same.
+ * @property {(v: string|null|[string|null,string|null]) => void} [onChange] - Emits the same shapes as `value` as the user picks.
+ * @property {12|24} [hourFormat] - 12- or 24-hour labels. Default `24`.
+ * @property {number} [minuteStep] - Minutes grid step, e.g. `5` → `00,05,…,55`. Default `5`.
+ */
+interface TimePickerProps {
+    mode?: "single" | "range";
+    value?: string | null | [string | null, string | null];
+    onChange?: (value: string | null | [string | null, string | null]) => void;
+    hourFormat?: 12 | 24;
+    minuteStep?: number;
+    startLabel?: string;
+    endLabel?: string;
+    disabled?: boolean;
+    className?: string;
+    error?: string;
+    note?: string;
+}
+/**
+ * Picker for a time or time range, with hour/minute dropdowns and optional labels or validation chrome.
+ *
+ * @param {TimePickerProps} props - Mode, `value`/`onChange` shape, and `hourFormat` / `minuteStep`.
+ * @returns {JSX.Element} The field group(s) and time lists when open.
+ */
+export declare const TimePicker: ({ mode, value, onChange, hourFormat, minuteStep, startLabel, endLabel, disabled, className, error, note, }: TimePickerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/src/toast/toast.d.ts

@@ -0,0 +1,54 @@
+import "./toast.css";
+import type React from "react";
+/**
+ * Color/semantic key for a toast: maps to icon and ARIA `role` (`error`/`warning` → `alert`, others often `status`).
+ * @type {("info"|"error"|"warning"|"success")}
+ */
+export type ToastVariant = "info" | "error" | "warning" | "success";
+/**
+ * Viewport region where `ToastProvider` positions the toast container (CSS BEM variant).
+ * @type {("top-right"|"top-left"|"bottom-right"|"bottom-left"|"top-center"|"bottom-center")}
+ */
+export type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+interface ToastAction {
+    label: string;
+    action: () => void;
+}
+/**
+ * Options passed to `useToast().show(options)`; describes one transient notification.
+ *
+ * @property {ToastVariant} variant - Visual/semantic style.
+ * @property {string} title - Bold heading in the toast header.
+ * @property {string} [description] - Optional body copy under the title.
+ * @property {ToastAction} [primaryAction] - Primary CTA; presence disables auto-dismiss by default.
+ * @property {ToastAction} [secondaryAction] - Secondary CTA; same as primary for auto-dismiss rules.
+ * @property {number} [duration] - Auto-close delay in ms. Default `5000`; `0` disables (`primaryAction` / `secondaryAction` also keep it open without timer).
+ */
+export interface ToastOptions {
+    variant: ToastVariant;
+    title: string;
+    description?: string;
+    primaryAction?: ToastAction;
+    secondaryAction?: ToastAction;
+    duration?: number;
+}
+/**
+ * Props for `ToastProvider` — mount once near the app root to enable `useToast()`.
+ *
+ * @property {React.ReactNode} children - Your app; context is available to descendants.
+ * @property {ToastPosition} [position] - Viewport region for the stack. Default `"bottom-right"`.
+ * @property {number} [maxToasts] - Max simultaneous toasts; older may be evicted. Default `5`.
+ */
+interface ToastProviderProps {
+    children: React.ReactNode;
+    position?: ToastPosition;
+    maxToasts?: number;
+}
+/**
+ * Context provider: renders `children` and a fixed-position stack of toasts; wires timers and `maxToasts` cap.
+ *
+ * @param {object} props - `position`, `maxToasts`, and `children`.
+ * @returns {JSX.Element} Provider element plus the global toast region.
+ */
+export declare const ToastProvider: React.FC<ToastProviderProps>;
+export {};

package/dist/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/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/entries/charts.d.ts

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

package/dist/entries/hooks.d.ts

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

package/dist/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/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";