hazo_ui 3.4.1 → 3.5.0

package/CHANGE_LOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v3.5.0 (2026-06-12)
+
+### New
+- `FunnelChart` — horizontal centered-bar conversion funnel with optional segment breakdown, hover tooltip (% of first / % of previous / drop-off), and edge-case handling (empty steps, zero values, single step). Closes FR-002.
+
 ## v3.4.1 — 2026-06-12
 
 **Fix:** Webpack compatibility in test-harness format.ts + source sync.

package/README.md

@@ -3362,6 +3362,66 @@ return error ? <ErrorBanner message={error} onDismiss={clearError} /> : null;
 
 Returns `{ error: string | null; setError: (v: unknown) => void; clearError: () => void }`. Pass `null` (or any nullish value) to `setError` to clear.
 
+### HazoUiEtaProgress (Requires optional `hazo_state` peer dependency)
+
+Smart ETA progress bar that learns from historical operation durations. Fetches a rolling window of past durations from `hazo_state`, estimates completion time based on remaining work units and concurrency, and animates smoothly toward the estimate. Requires `hazo_state` to be installed.
+
+```tsx
+import { HazoUiEtaProgress, type EtaProgressHandle } from "hazo_ui";
+import { useRef } from "react";
+
+function FileProcessor() {
+  const handleRef = useRef<EtaProgressHandle>(null);
+
+  async function processFiles(files: File[]) {
+    handleRef.current?.start();
+    
+    for (let i = 0; i < files.length; i++) {
+      await processFile(files[i]);
+      handleRef.current?.unitDone();
+    }
+    
+    handleRef.current?.finish();
+  }
+
+  return (
+    <>
+      <HazoUiEtaProgress
+        estimateKey="file_processing"
+        unitCount={totalFiles}
+        concurrency={3}
+        windowSize={10}
+        fallbackUnitMs={2000}
+        label="Processing files…"
+        handleRef={handleRef}
+      />
+      <button onClick={() => processFiles(files)}>Start</button>
+    </>
+  );
+}
+```
+
+**Installation requirement:** This component requires `hazo_state` as a peer dependency. Install it before using `HazoUiEtaProgress`:
+
+```bash
+npm install hazo_state
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `estimateKey` | `string` | **required** | Unique key for storing duration history in `hazo_state` |
+| `unitCount` | `number` | **required** | Total number of work units |
+| `concurrency` | `number` | `1` | How many units run in parallel |
+| `windowSize` | `number` | `5` | Number of past durations to average over |
+| `fallbackUnitMs` | `number` | `5000` | Per-unit estimate (ms) on cold start when no history exists |
+| `level` | `"global" \| "session" \| "local"` | `"global"` | hazo_state visibility level |
+| `label` | `string` | — | Label shown above the progress bar |
+| `endpoint` | `string` | `"/api/hazo-state"` | hazo_state API endpoint (for fetching history) |
+| `handleRef` | `RefObject<EtaProgressHandle>` | — | Ref exposing `start()`, `unitDone()`, `finish()` methods |
+| `className` | `string` | — | Additional classes |
+
+**Headless hook alternative:** For more control, use `useEtaProgress` directly without the component.
+
 ---
 
 ## HazoUiKanban — Drag-Drop Kanban (v2.13.0+)
@@ -3764,6 +3824,38 @@ Props:
 | `showYAxis`  | `boolean`      | `true`  | Render Y-axis ticks (max / mid / 0).                |
 | `className`  | `string`       | —       | Container className passthrough.                    |
 
+### FunnelChart
+
+Conversion-funnel visualization. Horizontal centered bars, one row per step.
+
+```tsx
+import { FunnelChart } from 'hazo_ui';
+
+<FunnelChart
+  steps={[
+    { label: 'Landing', value: 1000 },
+    { label: 'Timer start', value: 420 },
+    { label: 'Timer complete', value: 180 },
+  ]}
+  showDropoff
+/>
+```
+
+Optional `segments` prop splits each bar into colored sub-bands (mobile/desktop split, traffic-source mix, etc.).
+
+Props:
+
+| Prop           | Type                          | Default        | Description                                              |
+|----------------|-------------------------------|----------------|----------------------------------------------------------|
+| `steps`        | `FunnelStep[]`                | —              | Ordered funnel steps. Each has `label`, optional `value`, optional `segments`. |
+| `width`        | `number`                      | `360`          | viewBox width.                                           |
+| `height`       | `number`                      | auto           | viewBox height. Defaults to `PAD_TOP + steps.length * 44 + PAD_BOTTOM`. |
+| `color`        | `string`                      | `"#3b82f6"`    | Bar fill for steps without segments.                     |
+| `valueFormat`  | `(n: number) => string`       | `format_num`   | Override value formatting.                               |
+| `showDropoff`  | `boolean`                     | `true`         | Show per-step drop-off count below the value label.      |
+| `showTooltip`  | `boolean`                     | `true`         | Enable hover tooltip with full step metrics.             |
+| `className`    | `string`                      | —              | Container className passthrough.                         |
+
 ### DateRangeSelector
 
 Framework-agnostic segmented control (`value` + `onChange`) for picking

package/dist/index.cjs

@@ -10428,6 +10428,219 @@ function DateRangeSelector({
     }
   );
 }
+var PAD_LEFT4 = 80;
+var PAD_RIGHT4 = 72;
+var PAD_TOP4 = 12;
+var PAD_BOTTOM4 = 12;
+var ROW_H = 44;
+var LABEL_H = 14;
+var BAR_H = 22;
+var AXIS_LABEL_COLOR4 = "#8b949e";
+var GRIDLINE_COLOR3 = "#2a3441";
+function step_total(step) {
+  if (step.value !== void 0) return step.value;
+  if (step.segments) return step.segments.reduce((s, g) => s + g.value, 0);
+  return 0;
+}
+function FunnelChart({
+  steps,
+  width = 360,
+  height,
+  color: color2 = "#3b82f6",
+  valueFormat,
+  showDropoff = true,
+  showTooltip = true,
+  className
+}) {
+  const [hover_idx, set_hover_idx] = React26__namespace.useState(null);
+  const fmt = valueFormat ?? format_num;
+  const totals = steps.map(step_total);
+  const value_max = Math.max(1, ...totals);
+  const plot_w = width - PAD_LEFT4 - PAD_RIGHT4;
+  const vbox_h = height ?? PAD_TOP4 + steps.length * ROW_H + PAD_BOTTOM4;
+  const handle_mouse_move = React26__namespace.useCallback(
+    (e) => {
+      if (steps.length === 0) return;
+      const rect = e.currentTarget.getBoundingClientRect();
+      if (rect.height === 0) return;
+      const vbox_y = (e.clientY - rect.top) / rect.height * vbox_h;
+      const row_idx = Math.floor((vbox_y - PAD_TOP4) / ROW_H);
+      if (row_idx < 0 || row_idx >= steps.length) {
+        set_hover_idx(null);
+        return;
+      }
+      set_hover_idx(row_idx);
+    },
+    [steps.length, vbox_h]
+  );
+  const handle_mouse_leave = React26__namespace.useCallback(() => set_hover_idx(null), []);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "svg",
+    {
+      viewBox: `0 0 ${width} ${vbox_h}`,
+      onMouseMove: showTooltip ? handle_mouse_move : void 0,
+      onMouseLeave: showTooltip ? handle_mouse_leave : void 0,
+      className: cn("cls_hazo_chart cls_hazo_chart_funnel", className),
+      style: {
+        width: "100%",
+        height: "auto",
+        display: "block",
+        cursor: showTooltip ? "crosshair" : "default"
+      },
+      children: [
+        steps.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(
+          "line",
+          {
+            x1: PAD_LEFT4 + plot_w / 2,
+            x2: PAD_LEFT4 + plot_w / 2,
+            y1: PAD_TOP4,
+            y2: PAD_TOP4 + steps.length * ROW_H,
+            stroke: GRIDLINE_COLOR3,
+            strokeWidth: 0.5,
+            strokeDasharray: "2,3"
+          }
+        ),
+        steps.map((step, i) => {
+          const total = totals[i];
+          const bar_w = total / value_max * plot_w;
+          const bar_x = PAD_LEFT4 + (plot_w - bar_w) / 2;
+          const bar_y = PAD_TOP4 + i * ROW_H + LABEL_H;
+          const pct_first = i === 0 ? 100 : Math.round(total / (totals[0] || 1) * 100);
+          const value_label = i === 0 ? `${fmt(total)} (100%)` : `${fmt(total)} (${pct_first}%)`;
+          const dropoff = i > 0 ? totals[i - 1] - total : 0;
+          const label_x = bar_x + bar_w + 6;
+          return /* @__PURE__ */ jsxRuntime.jsxs("g", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "text",
+              {
+                x: PAD_LEFT4 - 6,
+                y: bar_y + BAR_H / 2 + 4,
+                textAnchor: "end",
+                fill: AXIS_LABEL_COLOR4,
+                fontSize: 9,
+                children: step.label
+              }
+            ),
+            step.segments ? (() => {
+              let cursor_x = bar_x;
+              return step.segments.map((seg, s_idx) => {
+                const seg_w = seg.value / value_max * plot_w;
+                const x = cursor_x;
+                cursor_x += seg_w;
+                return /* @__PURE__ */ jsxRuntime.jsx(
+                  "rect",
+                  {
+                    x,
+                    y: bar_y,
+                    width: seg_w,
+                    height: BAR_H,
+                    fill: seg.color
+                  },
+                  `seg_${s_idx}`
+                );
+              });
+            })() : /* @__PURE__ */ jsxRuntime.jsx("rect", { x: bar_x, y: bar_y, width: bar_w, height: BAR_H, fill: color2 }),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "text",
+              {
+                x: label_x,
+                y: bar_y + BAR_H / 2,
+                textAnchor: "start",
+                fill: color2,
+                fontSize: 9,
+                dominantBaseline: "middle",
+                children: value_label
+              }
+            ),
+            showDropoff && i > 0 && /* @__PURE__ */ jsxRuntime.jsx(
+              "text",
+              {
+                x: label_x,
+                y: bar_y + BAR_H / 2 + 10,
+                textAnchor: "start",
+                fill: AXIS_LABEL_COLOR4,
+                fontSize: 8,
+                children: `\u2212${fmt(dropoff)}`
+              }
+            )
+          ] }, `step_${i}`);
+        }),
+        showTooltip && hover_idx !== null && (() => {
+          const i = hover_idx;
+          const step = steps[i];
+          const total = totals[i];
+          const pct_first = i === 0 ? 100 : Math.round(total / (totals[0] || 1) * 100);
+          const pct_prev = i === 0 ? 100 : Math.round(total / (totals[i - 1] || 1) * 100);
+          const dropoff = i > 0 ? totals[i - 1] - total : 0;
+          const bar_w = total / value_max * plot_w;
+          const bar_x = PAD_LEFT4 + (plot_w - bar_w) / 2;
+          const bar_y = PAD_TOP4 + i * ROW_H + LABEL_H;
+          const bubble_anchor_y = bar_y + BAR_H / 2;
+          const lines = [
+            { text: step.label, accent: true },
+            { text: `Total: ${fmt(total)}`, accent: false },
+            { text: `% of first: ${pct_first}%`, accent: false }
+          ];
+          if (i > 0) {
+            lines.push({ text: `% of prev: ${pct_prev}%`, accent: false });
+            lines.push({ text: `Drop-off: \u2212${fmt(dropoff)}`, accent: false });
+          }
+          if (step.segments) {
+            step.segments.forEach((seg) => {
+              lines.push({ text: `${seg.label}: ${fmt(seg.value)}`, accent: false });
+            });
+          }
+          const line_h = 13;
+          const pad_v = 8;
+          const bubble_w = 120;
+          const bubble_h = lines.length * line_h + pad_v * 2;
+          const right_x = bar_x + bar_w + 6;
+          const left_x = bar_x - bubble_w - 6;
+          const fits_right = right_x + bubble_w <= width - 4;
+          const fits_left = left_x >= 4;
+          let bubble_x;
+          let bubble_y;
+          if (fits_right || fits_left) {
+            bubble_x = fits_right ? right_x : left_x;
+            bubble_y = Math.max(4, Math.min(bubble_anchor_y - bubble_h / 2, vbox_h - bubble_h - 4));
+          } else {
+            bubble_x = Math.min(Math.max(bar_x + bar_w / 2 - bubble_w / 2, 4), width - bubble_w - 4);
+            const below_y = bar_y + BAR_H + 6;
+            bubble_y = below_y + bubble_h <= vbox_h - 4 ? below_y : Math.max(4, bar_y - bubble_h - 6);
+          }
+          return /* @__PURE__ */ jsxRuntime.jsxs("g", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "rect",
+              {
+                x: bubble_x,
+                y: bubble_y,
+                width: bubble_w,
+                height: bubble_h,
+                rx: 3,
+                fill: "#0d1117",
+                stroke: color2,
+                strokeWidth: 0.5,
+                fillOpacity: 0.92
+              }
+            ),
+            lines.map((line, k) => /* @__PURE__ */ jsxRuntime.jsx(
+              "text",
+              {
+                x: bubble_x + 7,
+                y: bubble_y + pad_v + k * line_h + line_h * 0.75,
+                fill: line.accent ? color2 : AXIS_LABEL_COLOR4,
+                fontSize: line.accent ? 10 : 8,
+                fontWeight: line.accent ? 700 : 400,
+                children: line.text
+              },
+              k
+            ))
+          ] });
+        })()
+      ]
+    }
+  );
+}
 
 // src/assets/celebration-chime.mp3
 var celebration_chime_default = "data:text/plain;charset=utf-8,";
@@ -10954,6 +11167,7 @@ exports.DropdownMenuTrigger = DropdownMenuTrigger;
 exports.EmptyState = EmptyState;
 exports.ErrorBanner = ErrorBanner;
 exports.ErrorPage = ErrorPage;
+exports.FunnelChart = FunnelChart;
 exports.HazoContextProvider = HazoContextProvider;
 exports.HazoUiConfirmDialog = HazoUiConfirmDialog;
 exports.HazoUiDialog = HazoUiDialog;