hazo_ui 3.2.1 → 3.4.1

package/CHANGE_LOG.md

@@ -5,6 +5,84 @@ 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.4.1 — 2026-06-12
+
+**Fix:** Webpack compatibility in test-harness format.ts + source sync.
+
+- Changed `require("node:fs")` → `require("fs")` in `src/test-harness/scenarios/format.ts`. The `"node:"` prefix triggers webpack's `UnhandledSchemeError` at build time before the try/catch can degrade in the browser. The bare specifier allows webpack to stub it as an empty module on the client (resolve.fallback), and Next.js gracefully falls through the catch on the server. Both forms transpile to identical `__require("fs")` in dist.
+- Added `"use client"` directive to `src/index.ts` (already applied by tsup post-processing in dist, now the source matches).
+- Test-app: added `/device-hooks` nav entry for the new interactive demo.
+
+## v3.4.0 — 2026-06-12
+
+**New:** `use_wake_lock(active)` and `use_fullscreen()` — snake_case declarative hook variants (FR-001).
+
+Adds two thin wrapper hooks for snake_case consumers (the gotimer family) that can't adopt
+`useWakeLock` / `useFullscreen` verbatim because the existing hooks have different contracts.
+Both hooks delegate to their camelCase counterparts for all DOM-API logic (visibility-reacquire,
+unmount-release, SSR safety).
+
+- **`use_wake_lock(active: boolean): void`** — declarative; the screen wake lock is held while
+  `active` is `true` and released when it becomes `false`. No imperative `request()`/`release()`
+  calls required.
+- **`use_fullscreen<T>(): { is_fullscreen, toggle, ref }`** — self-binding; creates the ref
+  internally and returns it alongside `is_fullscreen: boolean` and `toggle: () => Promise<void>`.
+  The consumer attaches `ref` to the element to fullscreen.
+
+```ts
+import { use_wake_lock, use_fullscreen } from "hazo_ui";
+
+// Declarative wake lock
+use_wake_lock(timer.is_running);
+
+// Self-binding fullscreen
+const { is_fullscreen, toggle, ref } = use_fullscreen();
+return <div ref={ref}><button onClick={toggle}>Fullscreen</button></div>;
+```
+
+**Note:** The base `useFullscreen` hook syncs on the native `fullscreenchange` event. gotimer's
+local hook also had an Escape-key fallback for a browser-specific optimistic CSS state — this
+edge case is not included in `use_fullscreen` to avoid changing base-hook behaviour. Escape still
+exits real fullscreen via the `fullscreenchange` listener.
+
+**Exports added:** `use_wake_lock`, `use_fullscreen`, `UseFullscreenRefResult`.
+
+## v3.3.0 — 2026-06-11
+
+**New:** Required `doc` field on `Case` + per-case documentation accordion in `AutoTestRunner`.
+
+Every test case registered via `registerScenario` must now declare a `doc: CaseDoc` with four
+required string fields: `description`, `inputs`, `expectedOutputs`, and `caveats`. The field is
+enforced at the type level — a case without `doc` fails `tsc`. All 20 existing scenario files
+across the hazo workspace have been backfilled in this release.
+
+The `AutoTestRunner` renders a `▸/▾` caret toggle next to each case name. Clicking it expands a
+doc panel showing the four fields as labeled sections (Description / Inputs / Expected outputs /
+Caveats). Failed-case error output and "Copy prompt" behaviour are unchanged.
+
+**Exports added:** `CaseDoc` is now part of the public `hazo_ui/test-harness` surface.
+
+```ts
+import { registerScenario, type CaseDoc } from "hazo_ui/test-harness";
+
+registerScenario("my-pkg", {
+  name: "My Package",
+  pkg: "my-pkg",
+  cases: [
+    {
+      name: "creates a record",
+      doc: {
+        description: "Verifies that createRecord() inserts a row and returns the new ID.",
+        inputs: "A mock DB adapter seeded with an empty table; payload { title: 'hello' }.",
+        expectedOutputs: "Resolved string ID, table row count increases to 1.",
+        caveats: "None",
+      },
+      run: async () => { /* ... */ },
+    },
+  ],
+});
+```
+
 ## v3.2.0 — 2026-05-31
 
 **New:** `MarkdownEditor` — a generic, SSR-safe Markdown/MDX editor.

package/README.md

@@ -3285,6 +3285,47 @@ try { await sync(); } catch (e) {
 
 Also exports `rawToast` (re-export of sonner's `toast`) for advanced use cases.
 
+### useWakeLock / use_wake_lock
+
+Screen Wake Lock API wrapper. Prevents screen sleep while the lock is held. Automatically
+reacquires when the tab becomes visible again. Returns `supported: false` in environments
+that don't implement the API (SSR, older browsers).
+
+**Imperative variant** (`useWakeLock`) — call `request()` / `release()` directly:
+
+```ts
+import { useWakeLock } from "hazo_ui";
+const { supported, acquired, request, release } = useWakeLock();
+```
+
+**Declarative variant** (`use_wake_lock`) — hold the lock while a condition is true:
+
+```ts
+import { use_wake_lock } from "hazo_ui";
+use_wake_lock(timer.is_running); // acquires when true, releases when false
+```
+
+### useFullscreen / use_fullscreen
+
+Fullscreen API wrapper. Syncs `isFullscreen`/`is_fullscreen` with the native
+`fullscreenchange` event; SSR-safe.
+
+**Explicit-ref variant** (`useFullscreen`) — pass your own element ref:
+
+```ts
+import { useFullscreen } from "hazo_ui";
+const container_ref = useRef<HTMLDivElement>(null);
+const { isFullscreen, toggle } = useFullscreen(container_ref);
+```
+
+**Self-binding variant** (`use_fullscreen`) — ref created and returned internally:
+
+```ts
+import { use_fullscreen } from "hazo_ui";
+const { is_fullscreen, toggle, ref } = use_fullscreen();
+return <div ref={ref}><button onClick={toggle}>Fullscreen</button></div>;
+```
+
 ### useLoadingState
 
 Hook that returns a controlled loading flag plus an async wrapper.
@@ -3920,13 +3961,18 @@ export default function RootLayout({ children }) {
 // test-app/scenarios/my_feature.ts
 import { registerScenario, assertEqual } from 'hazo_ui/test-harness';
 
-registerScenario({
-  id: 'my_feature',
+registerScenario('my_feature', {
   name: 'My Feature',
   pkg: 'my_pkg',
   cases: [
     {
       name: 'returns correct value',
+      doc: {
+        description: 'Verifies that myFunction adds two numbers correctly.',
+        inputs: 'myFunction(1, 2)',
+        expectedOutputs: 'Returns 3.',
+        caveats: 'None',
+      },
       run: async () => {
         const result = myFunction(1, 2);
         assertEqual(result, 3, 'should add two numbers');
@@ -3934,6 +3980,12 @@ registerScenario({
     },
     {
       name: 'throws on invalid input',
+      doc: {
+        description: 'Verifies that myFunction rejects null as the first argument.',
+        inputs: 'myFunction(null, 2)',
+        expectedOutputs: 'Throws an error containing "invalid input".',
+        caveats: 'None',
+      },
       run: async () => {
         await assertThrows(() => myFunction(null, 2), 'invalid input');
       },
@@ -3954,6 +4006,22 @@ export default function MyFeaturePage() {
 }
 ```
 
+### Case documentation (`doc` — required)
+
+Every case **must** include a `doc: CaseDoc` field. This is enforced at the TypeScript level — omitting it is a compile error. The `AutoTestRunner` surfaces it as a `▸/▾` per-case accordion so reviewers can read what each test verifies without opening the source file.
+
+```ts
+import type { CaseDoc } from 'hazo_ui/test-harness';
+
+// All four fields are required strings:
+const doc: CaseDoc = {
+  description: 'What this test verifies, in plain language.',
+  inputs: 'Inputs / preconditions fed in (URL, payload, fixture, state).',
+  expectedOutputs: 'What is asserted on success.',
+  caveats: 'None', // use "None" when nothing notable applies
+};
+```
+
 ### Copying failures as a Claude prompt
 
 `CopyAllFailuresButton` copies all failed cases as a structured prompt with 8 sections (what-went-wrong, expected/actual/diff, test code, code under test, error chain, context, ring buffer). Place it in your sidebar or test page header.

package/SETUP_CHECKLIST.md

@@ -258,8 +258,9 @@ import {
 // Import celebration (v2.18.0)
 import { CelebrationProvider, celebrate, CELEBRATION_GRADIENT } from 'hazo_ui';
 
-// Import test harness (v3.0.0) — test-app only, never in production bundles
-import { AutoTestProvider, AutoTestRunner, SidebarLayout, AppSidebar, registerScenario, assertEqual } from 'hazo_ui/test-harness';
+// Import test harness (v3.3.0) — test-app only, never in production bundles
+// Note: every Case must include a `doc: CaseDoc` field (required since v3.3.0)
+import { AutoTestProvider, AutoTestRunner, SidebarLayout, AppSidebar, registerScenario, assertEqual, type CaseDoc } from 'hazo_ui/test-harness';
 ```
 
 **Toaster setup**: Mount `<HazoUiToaster />` once at the root of your app (e.g., in `layout.tsx`) so `successToast()` / `errorToast()` calls have somewhere to render.

package/dist/index.cjs

@@ -74,6 +74,7 @@ var TogglePrimitive = require('@radix-ui/react-toggle');
 var ToggleGroupPrimitive = require('@radix-ui/react-toggle-group');
 var AlertDialogPrimitive = require('@radix-ui/react-alert-dialog');
 var sonner = require('sonner');
+var client$1 = require('hazo_state/client');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -7999,6 +8000,18 @@ function useFullscreen(elementRef) {
   }, [enter, exit]);
   return { isFullscreen: is_fullscreen, enter, exit, toggle };
 }
+function use_wake_lock(active) {
+  const { acquired, request, release } = useWakeLock();
+  React26.useEffect(() => {
+    if (active && !acquired) void request();
+    if (!active && acquired) void release();
+  }, [active, acquired, request, release]);
+}
+function use_fullscreen() {
+  const ref = React26.useRef(null);
+  const { isFullscreen, toggle } = useFullscreen(ref);
+  return { is_fullscreen: isFullscreen, toggle, ref };
+}
 function KanbanCard({
   item,
   renderCard,
@@ -10701,6 +10714,177 @@ function CelebrationModalInner({
   );
 }
 
+// src/components/hazo_ui_eta_progress/eta.ts
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function computeEta(durationWindow, unitCount, concurrency = 1, fallbackUnitMs = 5e3) {
+  const unitMs = durationWindow.length > 0 ? median(durationWindow) : fallbackUnitMs;
+  return unitMs * Math.ceil(unitCount / Math.max(1, concurrency));
+}
+function easeToward(elapsed, eta, maxCap = 0.95) {
+  if (eta <= 0 || elapsed <= 0) return 0;
+  const t = elapsed / eta;
+  return maxCap * (1 - Math.exp(-1.5 * t));
+}
+function HazoUiProgressBar({
+  value,
+  label,
+  showPercent = false,
+  size = 8,
+  className
+}) {
+  const pct = Math.round(Math.min(1, Math.max(0, value)) * 100);
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cn("w-full", className), children: [
+    (label || showPercent) && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between mb-1", children: [
+      label && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-sm text-muted-foreground", children: label }),
+      showPercent && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "text-xs text-muted-foreground tabular-nums", children: [
+        pct,
+        "%"
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        role: "progressbar",
+        "aria-valuenow": pct,
+        "aria-valuemin": 0,
+        "aria-valuemax": 100,
+        "aria-label": label,
+        className: "w-full rounded-full overflow-hidden bg-muted",
+        style: { height: size },
+        children: /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            className: "h-full rounded-full bg-accent transition-[width] duration-200 ease-out motion-reduce:transition-none",
+            style: { width: `${pct}%` }
+          }
+        )
+      }
+    )
+  ] });
+}
+function useEtaProgress(opts) {
+  const {
+    unitCount,
+    concurrency = 1,
+    fallbackUnitMs = 5e3,
+    loadDurations,
+    appendDuration
+  } = opts;
+  const [value, setValue] = React26__namespace.useState(0);
+  const stateRef = React26__namespace.useRef({
+    started: false,
+    finished: false,
+    startTime: 0,
+    unitsDone: 0,
+    unitTimestamps: [],
+    // timestamps of each unitDone() call
+    eta: 0,
+    rafId: 0
+  });
+  const stop = React26__namespace.useCallback(() => {
+    if (stateRef.current.rafId) {
+      cancelAnimationFrame(stateRef.current.rafId);
+      stateRef.current.rafId = 0;
+    }
+  }, []);
+  React26__namespace.useEffect(() => stop, [stop]);
+  const tick = React26__namespace.useCallback(() => {
+    const s = stateRef.current;
+    if (s.finished || !s.started) return;
+    const elapsed = Date.now() - s.startTime;
+    const timeValue = easeToward(elapsed, s.eta);
+    const unitValue = unitCount > 0 ? s.unitsDone / unitCount : 0;
+    setValue(Math.max(timeValue, unitValue));
+    s.rafId = requestAnimationFrame(tick);
+  }, [unitCount]);
+  const start = React26__namespace.useCallback(() => {
+    const s = stateRef.current;
+    if (s.started) return;
+    const window2 = loadDurations();
+    const eta = computeEta(window2, unitCount, concurrency, fallbackUnitMs);
+    s.started = true;
+    s.finished = false;
+    s.startTime = Date.now();
+    s.unitsDone = 0;
+    s.unitTimestamps = [];
+    s.eta = eta;
+    stop();
+    s.rafId = requestAnimationFrame(tick);
+  }, [loadDurations, unitCount, concurrency, fallbackUnitMs, stop, tick]);
+  const unitDone = React26__namespace.useCallback(() => {
+    const s = stateRef.current;
+    if (!s.started || s.finished) return;
+    s.unitsDone = Math.min(s.unitsDone + 1, unitCount);
+    s.unitTimestamps.push(Date.now());
+  }, [unitCount]);
+  const finish = React26__namespace.useCallback(() => {
+    const s = stateRef.current;
+    if (s.finished) return;
+    s.finished = true;
+    stop();
+    setValue(1);
+    if (s.started && s.unitTimestamps.length > 0) {
+      const totalMs = Date.now() - s.startTime;
+      const perUnitMs = totalMs / Math.ceil(unitCount / Math.max(1, concurrency));
+      appendDuration(perUnitMs);
+    }
+    s.started = false;
+    s.unitsDone = 0;
+  }, [stop, unitCount, concurrency, appendDuration]);
+  return { value, start, unitDone, finish };
+}
+function HazoUiEtaProgress({
+  estimateKey,
+  unitCount,
+  concurrency = 1,
+  windowSize = 5,
+  fallbackUnitMs = 5e3,
+  level = "global",
+  label,
+  endpoint,
+  handleRef,
+  className
+}) {
+  const { value: stored, append } = client$1.useHazoState(estimateKey, {
+    level,
+    fallback: [],
+    ...endpoint ? { endpoint } : {}
+  });
+  const durationWindow = Array.isArray(stored) ? stored : [];
+  const loadDurations = React26__namespace.useCallback(() => durationWindow, [durationWindow]);
+  const appendDuration = React26__namespace.useCallback(
+    (ms) => {
+      append(ms, windowSize);
+    },
+    [append, windowSize]
+  );
+  const handle = useEtaProgress({
+    unitCount,
+    concurrency,
+    fallbackUnitMs,
+    loadDurations,
+    appendDuration
+  });
+  React26__namespace.useEffect(() => {
+    if (handleRef) {
+      handleRef.current = handle;
+    }
+  }, [handleRef, handle]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    HazoUiProgressBar,
+    {
+      value: handle.value,
+      label,
+      className
+    }
+  );
+}
+
 Object.defineProperty(exports, "rawToast", {
   enumerable: true,
   get: function () { return sonner.toast; }
@@ -10783,6 +10967,7 @@ exports.HazoUiDialogPortal = DialogPortal;
 exports.HazoUiDialogRoot = Dialog;
 exports.HazoUiDialogTitle = DialogTitle;
 exports.HazoUiDialogTrigger = DialogTrigger;
+exports.HazoUiEtaProgress = HazoUiEtaProgress;
 exports.HazoUiFlexInput = HazoUiFlexInput;
 exports.HazoUiFlexRadio = HazoUiFlexRadio;
 exports.HazoUiKanban = HazoUiKanban;
@@ -10790,6 +10975,7 @@ exports.HazoUiKanbanFilter = HazoUiKanbanFilter;
 exports.HazoUiMultiFilterDialog = HazoUiMultiFilterDialog;
 exports.HazoUiMultiSortDialog = HazoUiMultiSortDialog;
 exports.HazoUiPillRadio = HazoUiPillRadio;
+exports.HazoUiProgressBar = HazoUiProgressBar;
 exports.HazoUiRte = HazoUiRte;
 exports.HazoUiTable = HazoUiTable;
 exports.HazoUiTextarea = HazoUiTextarea;
@@ -10863,12 +11049,15 @@ exports.applyKanbanFilter = applyKanbanFilter;
 exports.buttonGroupVariants = buttonGroupVariants;
 exports.celebrate = celebrate;
 exports.cn = cn;
+exports.computeEta = computeEta;
 exports.create_command_suggestion_extension = create_command_suggestion_extension;
+exports.easeToward = easeToward;
 exports.errorToast = errorToast;
 exports.format_num = format_num;
 exports.generateUUID = generateUUID;
 exports.get_hazo_ui_config = get_hazo_ui_config;
 exports.get_logger = get_logger;
+exports.median = median;
 exports.parse_commands_from_text = parse_commands_from_text;
 exports.pick_x_label_indices = pick_x_label_indices;
 exports.reset_hazo_ui_config = reset_hazo_ui_config;
@@ -10882,6 +11071,7 @@ exports.useClickOutside = useClickOutside;
 exports.useCopyToClipboard = useCopyToClipboard;
 exports.useDebounce = useDebounce;
 exports.useErrorDisplay = useErrorDisplay;
+exports.useEtaProgress = useEtaProgress;
 exports.useFullscreen = useFullscreen;
 exports.useIsMobile = useIsMobile;
 exports.useLoadingState = useLoadingState;
@@ -10890,5 +11080,7 @@ exports.useMediaQuery = useMediaQuery;
 exports.useSessionStorage = useSessionStorage;
 exports.useViewport = useViewport;
 exports.useWakeLock = useWakeLock;
+exports.use_fullscreen = use_fullscreen;
+exports.use_wake_lock = use_wake_lock;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map