h2o-library 1.7.1 → 2.0.0

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";

package/dist/esm/charts/charts.css

@@ -0,0 +1,377 @@
+/* ─── Bar ─── */
+
+.bar-chart-container {
+  font-family: inherit;
+  text-align: center;
+  padding: 2rem 2rem 2rem 0;
+}
+
+.bar-chart-y-label {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  word-break: break-word;
+  text-align: right;
+  line-height: 1.25;
+  font-size: 12px;
+  color: hsl(var(--muted-200));
+}
+
+/* ─── Line ─── */
+
+.line-chart-container {
+  font-family: inherit;
+  text-align: center;
+  padding: 2rem 2rem 2rem 0;
+}
+
+.pie-chart-container {
+  font-family: inherit;
+  text-align: center;
+}
+
+.pie-chart-clickable path,
+.pie-chart-clickable .recharts-pie-sector {
+  cursor: pointer;
+}
+
+.pie-chart-container path:focus,
+.pie-chart-container .recharts-pie-sector:focus,
+.pie-chart-container .recharts-layer path:focus {
+  outline: none;
+}
+
+/* ─── StatBar ─── */
+
+.stat-chart-container {
+  font-family: inherit;
+  display: flex;
+  flex-direction: column;
+}
+
+.stat-chart-compare-wrapper {
+  display: flex;
+  width: 100%;
+  align-items: flex-start;
+  gap: 0.5rem;
+}
+
+.stat-chart-compare-section {
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+.stat-chart-compare-label {
+  font-size: 0.875rem;
+  color: hsl(var(--muted-200));
+  text-align: center;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+}
+
+.stat-chart-compare-center {
+  flex: 0 0 auto;
+  min-width: 120px;
+  display: flex;
+  flex-direction: column;
+}
+
+.stat-chart-compare-center-label {
+  color: hsl(var(--muted-200));
+  font-size: 0.8125rem;
+  text-align: center;
+}
+
+.stat-chart-difference-col {
+  flex: 0 0 auto;
+  padding-left: 1rem;
+  text-align: left;
+}
+
+.stat-chart-difference-title {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: hsl(var(--primary-400));
+  display: flex;
+  align-items: flex-end;
+}
+
+.stat-chart-difference-row {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  height: 48px;
+  font-size: 0.8125rem;
+}
+
+.stat-chart-difference-positive,
+.stat-chart-difference-negative {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.stat-chart-difference-positive {
+  color: hsl(var(--success));
+}
+
+.stat-chart-difference-negative {
+  color: hsl(var(--destructive));
+}
+
+/* Stat bar rows: tooltip trigger must flex like the old track; overrides .tooltip-container { display: inline-block } */
+.stat-chart-container .stat-chart-bar-tooltip,
+.stat-chart-compare-section .stat-chart-bar-tooltip {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  align-items: center;
+  align-self: stretch;
+}
+
+.stat-chart-bar-track {
+  position: relative;
+  width: 100%;
+  height: 22px;
+  overflow: hidden;
+}
+
+/* ─── Gantt ─── */
+
+.gantt-chart-container {
+  font-family: inherit;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  overflow: visible;
+}
+
+.gantt-chart-legend {
+  margin-bottom: 0.75rem;
+}
+
+.gantt-bar-tooltip {
+  display: block;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+}
+
+.gantt-bar-tooltip-hit {
+  width: 100%;
+  height: 100%;
+  min-height: 1px;
+}
+
+/* ─── Heatmap ─── */
+
+.heatmap-header-label {
+  font-size: 0.75rem;
+  color: hsl(var(--muted-200));
+}
+
+.custom-chart-tooltip {
+  background-color: hsl(var(--tooltip-dark-bg));
+  color: hsl(var(--tooltip-dark-fg));
+  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+  font-size: 0.75rem;
+  white-space: nowrap;
+  position: relative;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  transform: translate(-50%, calc(-100% - 16px));
+}
+
+.custom-chart-tooltip > span {
+  font-size: 0.875rem;
+}
+
+.custom-chart-tooltip::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border-width: 8px;
+  border-style: solid;
+  border-color: hsl(var(--tooltip-dark-bg)) transparent transparent transparent;
+}
+
+.recharts-tooltip-wrapper {
+  z-index: 1000;
+}
+
+.heatmap-container {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  padding: 1rem;
+  display: flex;
+  flex-direction: column;
+  overflow: visible;
+  box-sizing: border-box;
+}
+
+.heatmap-grid {
+  display: grid;
+  gap: 0.5rem;
+  flex-grow: 1;
+  min-height: 0;
+  overflow: visible;
+}
+
+.heatmap-col-tooltip {
+  width: 100%;
+  min-width: 0;
+  display: block;
+  box-sizing: border-box;
+}
+
+.heatmap-col-header {
+  padding: 0.5rem;
+  font-weight: 400;
+  text-align: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+  display: block;
+  box-sizing: border-box;
+}
+
+.heatmap-row-tooltip {
+  width: 100%;
+  min-width: 0;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+}
+
+.heatmap-row-header {
+  padding: 0.5rem;
+  font-weight: 400;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+  display: block;
+  box-sizing: border-box;
+}
+
+.heatmap-cell {
+  box-sizing: border-box;
+  padding: 0.75rem;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+
+.heatmap-cell-content {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.heatmap-cell-value-container {
+  font-size: 0.875rem;
+}
+
+.heatmap-cell-percentage-container {
+  font-size: 0.75rem;
+}
+
+.heatmap-icon {
+  width: 0.75rem;
+  height: 0.75rem;
+}
+
+.heatmap-cell-tooltip-content {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  font-size: 0.75rem;
+}
+
+/* ─── Chart Wrapper ─── */
+.chart-container {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.chart-header {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.chart-title-container {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.chart-title {
+  margin: 0;
+  font-size: 1.5rem;
+  font-weight: 600;
+}
+
+.chart-info-icon {
+  color: hsl(var(--muted));
+  cursor: help;
+}
+
+.chart-metadata {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.chart-kpis {
+  display: flex;
+  gap: 2rem;
+  flex-wrap: wrap;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid hsl(var(--muted-50));
+}
+
+.chart-kpi {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.chart-kpi-label {
+  font-size: 0.875rem;
+  color: hsl(var(--muted-200));
+}
+
+.chart-kpi-value {
+  font-size: 1.5rem;
+  font-weight: 600;
+}
+
+.chart-legend {
+  padding-top: 0.5rem;
+}
+
+.chart-header-content {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.chart-description {
+  font-size: 1rem;
+  color: hsl(var(--muted-200));
+}

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

package/dist/esm/charts/src/chart/chart.d.ts

@@ -0,0 +1,35 @@
+import "../../charts.css";
+import type { BarChartDataPoint } from "../bar/chart-bar";
+import type { LineChartDataPoint } from "../line/chart-line";
+import type { PieChartDataPoint } from "../pie/chart-pie";
+import type { HeatmapData } from "../heatmap/chart-heatmap";
+export type ChartKPI = {
+    label: string;
+    value: string | number;
+};
+type BaseChartData = {
+    bar: BarChartDataPoint[];
+    line: LineChartDataPoint[];
+    pie: PieChartDataPoint[];
+    heatmap: HeatmapData;
+};
+export type ChartType = keyof BaseChartData;
+interface BaseChartProps {
+    type: ChartType;
+    title?: string;
+    info?: string;
+    description?: string;
+    kpis?: ChartKPI[];
+    height?: number;
+    className?: string;
+}
+type BarChartSpecificProps = {
+    layout?: "single" | "grouped" | "stacked" | "grouped-stacked";
+    orientation?: "vertical" | "horizontal";
+};
+type ChartTypeSpecificProps<T extends ChartType> = T extends "bar" ? BarChartSpecificProps : Record<string, never>;
+export type ChartProps<T extends ChartType> = BaseChartProps & {
+    data: BaseChartData[T];
+} & ChartTypeSpecificProps<T>;
+export declare const Chart: <T extends ChartType>({ type, title, info, description, kpis, data, height, className, ...chartSpecificProps }: ChartProps<T>) => import("react/jsx-runtime").JSX.Element;
+export {};