hazo_ui 6.0.0 → 6.3.0

package/dist/index.utils.cjs

@@ -7,6 +7,78 @@ function cn(...inputs) {
   return tailwindMerge.twMerge(clsx.clsx(inputs));
 }
 
+// src/lib/remembered_state.ts
+function readRememberedState(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function writeRememberedState(key, snapshot) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(snapshot));
+  } catch {
+  }
+}
+function hasUrlParam(search, paramName) {
+  try {
+    return new URLSearchParams(search).has(paramName);
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/announce.ts
+var DEFAULT_ANNOUNCE_EVENT = "hazo_ui:announce";
+function announce(message, priority = "polite", options) {
+  if (typeof window === "undefined") return;
+  const trimmed = message.trim();
+  if (!trimmed) return;
+  const eventName = options?.eventName ?? DEFAULT_ANNOUNCE_EVENT;
+  window.dispatchEvent(
+    new CustomEvent(eventName, {
+      detail: { message: trimmed, priority }
+    })
+  );
+}
+
+// src/lib/scroll_restore.ts
+var DEFAULT_SCROLL_RESTORE_PREFIX = "hazo_ui:scrollPos";
+function buildScrollRestoreKey(prefix, treeId, viewName) {
+  return `${prefix}.${treeId}.${viewName}`;
+}
+function saveScrollPos(key, scrollY) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, String(Math.round(scrollY)));
+  } catch {
+  }
+}
+function loadScrollPos(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return null;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+exports.DEFAULT_ANNOUNCE_EVENT = DEFAULT_ANNOUNCE_EVENT;
+exports.DEFAULT_SCROLL_RESTORE_PREFIX = DEFAULT_SCROLL_RESTORE_PREFIX;
+exports.announce = announce;
+exports.buildScrollRestoreKey = buildScrollRestoreKey;
 exports.cn = cn;
+exports.hasUrlParam = hasUrlParam;
+exports.loadScrollPos = loadScrollPos;
+exports.readRememberedState = readRememberedState;
+exports.saveScrollPos = saveScrollPos;
+exports.writeRememberedState = writeRememberedState;
 //# sourceMappingURL=index.utils.cjs.map
 //# sourceMappingURL=index.utils.cjs.map

package/dist/index.utils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/lib/utils.ts"],"names":["twMerge","clsx"],"mappings":";;;;;AAWO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAOA,qBAAA,CAAQC,SAAA,CAAK,MAAM,CAAC,CAAA;AAC7B","file":"index.utils.cjs","sourcesContent":["// Utility functions for hazo_ui component library\n// Provides className merging utility (cn function)\n\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Merges class names using clsx and tailwind-merge\n * @param inputs - Class values to merge\n * @returns Merged class string\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n\n/**\n * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent\n * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an\n * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but\n * not protocol-relative `//…`). Returns `undefined` for anything else, so the\n * anchor renders with no href rather than an active malicious one.\n * @param url - Candidate href (may be undefined)\n * @returns The original url if allowed, otherwise undefined\n */\nexport function safeHref(url?: string): string | undefined {\n  if (!url) return undefined;\n  const trimmed = url.trim();\n  const lower = trimmed.toLowerCase();\n  if (\n    lower.startsWith(\"http://\") ||\n    lower.startsWith(\"https://\") ||\n    lower.startsWith(\"mailto:\")\n  ) {\n    return trimmed;\n  }\n  // Same-origin absolute path, but not protocol-relative \"//host\".\n  if (trimmed.startsWith(\"/\") && !trimmed.startsWith(\"//\")) {\n    return trimmed;\n  }\n  return undefined;\n}\n\n"]}
+{"version":3,"sources":["../src/lib/utils.ts","../src/lib/remembered_state.ts","../src/lib/announce.ts","../src/lib/scroll_restore.ts"],"names":["twMerge","clsx"],"mappings":";;;;;AAWO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAOA,qBAAA,CAAQC,SAAA,CAAK,MAAM,CAAC,CAAA;AAC7B;;;ACIO,SAAS,oBAAuB,GAAA,EAAuB;AAC5D,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,IAAA;AAC1C,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AAC3C,IAAA,OAAO,GAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA,GAAU,IAAA;AAAA,EACxC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAaO,SAAS,oBAAA,CAAwB,KAAa,QAAA,EAAmB;AACtE,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,aAAa,OAAA,CAAQ,GAAA,EAAK,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA;AAAA,EAC3D,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AAeO,SAAS,WAAA,CAAY,QAAgB,SAAA,EAA4B;AACtE,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,eAAA,CAAgB,MAAM,CAAA,CAAE,IAAI,SAAS,CAAA;AAAA,EAClD,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;;;ACtCO,IAAM,sBAAA,GAAyB;AAuB/B,SAAS,QAAA,CACd,OAAA,EACA,QAAA,GAA6B,QAAA,EAC7B,OAAA,EACM;AACN,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,MAAM,OAAA,GAAU,QAAQ,IAAA,EAAK;AAC7B,EAAA,IAAI,CAAC,OAAA,EAAS;AACd,EAAA,MAAM,SAAA,GAAY,SAAS,SAAA,IAAa,sBAAA;AACxC,EAAA,MAAA,CAAO,aAAA;AAAA,IACL,IAAI,YAA8B,SAAA,EAAW;AAAA,MAC3C,MAAA,EAAQ,EAAE,OAAA,EAAS,OAAA,EAAS,QAAA;AAAS,KACtC;AAAA,GACH;AACF;;;ACrDO,IAAM,6BAAA,GAAgC;AAStC,SAAS,qBAAA,CAAsB,MAAA,EAAgB,MAAA,EAAgB,QAAA,EAA0B;AAC9F,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,MAAM,IAAI,QAAQ,CAAA,CAAA;AACxC;AAUO,SAAS,aAAA,CAAc,KAAa,OAAA,EAAuB;AAChE,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,YAAA,CAAa,QAAQ,GAAA,EAAK,MAAA,CAAO,KAAK,KAAA,CAAM,OAAO,CAAC,CAAC,CAAA;AAAA,EAC9D,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AASO,SAAS,cAAc,GAAA,EAA4B;AACxD,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,IAAA;AAC1C,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,IAAA,MAAM,CAAA,GAAI,MAAA,CAAO,QAAA,CAAS,GAAA,EAAK,EAAE,CAAA;AACjC,IAAA,OAAO,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA,GAAI,CAAA,GAAI,IAAA;AAAA,EAClC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF","file":"index.utils.cjs","sourcesContent":["// Utility functions for hazo_ui component library\n// Provides className merging utility (cn function)\n\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Merges class names using clsx and tailwind-merge\n * @param inputs - Class values to merge\n * @returns Merged class string\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n\n/**\n * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent\n * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an\n * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but\n * not protocol-relative `//…`). Returns `undefined` for anything else, so the\n * anchor renders with no href rather than an active malicious one.\n * @param url - Candidate href (may be undefined)\n * @returns The original url if allowed, otherwise undefined\n */\nexport function safeHref(url?: string): string | undefined {\n  if (!url) return undefined;\n  const trimmed = url.trim();\n  const lower = trimmed.toLowerCase();\n  if (\n    lower.startsWith(\"http://\") ||\n    lower.startsWith(\"https://\") ||\n    lower.startsWith(\"mailto:\")\n  ) {\n    return trimmed;\n  }\n  // Same-origin absolute path, but not protocol-relative \"//host\".\n  if (trimmed.startsWith(\"/\") && !trimmed.startsWith(\"//\")) {\n    return trimmed;\n  }\n  return undefined;\n}\n\n","// remembered_state.ts — SSR-safe localStorage read/write/URL-param helpers\n// backing `useRememberedState` (src/hooks/use_remembered_state.ts). Pure,\n// framework-free functions (no React) so they're independently testable and\n// usable outside the hook. No \"use client\" directive here — this module is\n// re-exported from both the main client bundle (`hazo_ui`) and the pure\n// server-safe subpath (`hazo_ui/utils`), same dual-export pattern as `cn`.\n\n/**\n * Reads and JSON-parses the remembered value stored under `key`. SSR-safe —\n * returns `null` on the server, when nothing is stored, or when the stored\n * value is corrupt/unparsable.\n *\n * @param key - localStorage key to read.\n *\n * @example\n *   const seed = readRememberedState<MySeed>(\"myapp:tool:cgt\");\n */\nexport function readRememberedState<T>(key: string): T | null {\n  if (typeof window === \"undefined\") return null;\n  try {\n    const raw = window.localStorage.getItem(key);\n    return raw ? (JSON.parse(raw) as T) : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * JSON-stringifies and writes `snapshot` under `key`. SSR-safe — no-ops on\n * the server. Quota / private-mode errors are swallowed; losing a memory\n * write is non-fatal.\n *\n * @param key      - localStorage key to write.\n * @param snapshot - Serialisable value to remember.\n *\n * @example\n *   writeRememberedState(\"myapp:tool:cgt\", { proceeds: 1000 });\n */\nexport function writeRememberedState<T>(key: string, snapshot: T): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(key, JSON.stringify(snapshot));\n  } catch {\n    /* quota / private-mode — non-fatal */\n  }\n}\n\n/**\n * True when `paramName` is present in the given search string (e.g.\n * `window.location.search`). Generic form of the \"an explicit shared-link /\n * saved-record query param always wins over remembered state\" precedence\n * check — callers supply the param name (e.g. `\"restore\"`); this module\n * never hardcodes one.\n *\n * @param search    - A URL search string, e.g. `window.location.search`.\n * @param paramName - The query param to look for.\n *\n * @example\n *   hasUrlParam(\"?restore=abc123\", \"restore\"); // true\n */\nexport function hasUrlParam(search: string, paramName: string): boolean {\n  try {\n    return new URLSearchParams(search).has(paramName);\n  } catch {\n    return false;\n  }\n}\n","// announce.ts — SSR-safe screen-reader announcement bus. Dispatches a\n// `window` CustomEvent that `LiveRegion` (../components/live_region/)\n// listens for. Pure, framework-free (no React) so it's independently\n// testable and usable outside a component. No \"use client\" directive here\n// — this module is re-exported from both the main client bundle\n// (`hazo_ui`) and the pure server-safe subpath (`hazo_ui/utils`), same\n// dual-export pattern as `cn` and the `remembered_state` helpers.\n//\n// Ported from Kinstripe's `src/lib/a11y/announce.ts`, which hardcoded the\n// event name to `\"kinstripe:announce\"`. Here the event name is caller-\n// configurable (`options.eventName`) so multiple apps — or multiple\n// `LiveRegion` instances on the same page — don't collide on a single\n// hardcoded channel; it defaults to `DEFAULT_ANNOUNCE_EVENT` for\n// single-app usage.\n\nexport type AnnouncePriority = \"polite\" | \"assertive\";\n\nexport interface LiveAnnouncement {\n  message: string;\n  priority: AnnouncePriority;\n}\n\nexport interface AnnounceOptions {\n  /** Custom-event name the paired `LiveRegion` listens on. Must match the `eventName` it was mounted with. Default `DEFAULT_ANNOUNCE_EVENT`. */\n  eventName?: string;\n}\n\n/** Default `window` CustomEvent name used when `announce()` / `LiveRegion` are not given an explicit `eventName`. */\nexport const DEFAULT_ANNOUNCE_EVENT = \"hazo_ui:announce\";\n\n/**\n * Dispatch a screen-reader announcement via a `window` CustomEvent. Safe to\n * call from anywhere in the client tree — no-ops during SSR or before a\n * `LiveRegion` has mounted (fire-and-forget; there's no queue/replay).\n *\n * Use `\"polite\"` (default) for ambient updates (\"Sarah joined the canvas\",\n * \"2 new notifications\"). Use `\"assertive\"` only for things the user must\n * hear immediately (errors that interrupt a task).\n *\n * @param message  - Text to announce. Empty / whitespace-only messages are dropped (no dispatch).\n * @param priority - `\"polite\"` (default) or `\"assertive\"`.\n * @param options.eventName - Custom-event name to dispatch on. Default `DEFAULT_ANNOUNCE_EVENT`.\n *\n * @example\n *   announce(\"2 new notifications\");\n *   announce(\"Save failed — check your connection\", \"assertive\");\n *\n * @example\n *   // namespaced channel — must match the eventName the LiveRegion was mounted with\n *   announce(\"Saved\", \"polite\", { eventName: \"myapp:announce\" });\n */\nexport function announce(\n  message: string,\n  priority: AnnouncePriority = \"polite\",\n  options?: AnnounceOptions,\n): void {\n  if (typeof window === \"undefined\") return;\n  const trimmed = message.trim();\n  if (!trimmed) return;\n  const eventName = options?.eventName ?? DEFAULT_ANNOUNCE_EVENT;\n  window.dispatchEvent(\n    new CustomEvent<LiveAnnouncement>(eventName, {\n      detail: { message: trimmed, priority },\n    }),\n  );\n}\n","// scroll_restore.ts — SSR-safe localStorage read/write helpers backing\n// `useScrollRestore` (../hooks/use_scroll_restore.ts). Pure, framework-free\n// functions (no React) so they're independently testable and usable\n// outside the hook — same split as `remembered_state.ts` /\n// `useRememberedState`. No \"use client\" directive here.\n//\n// Ported from Kinstripe's `src/lib/hooks/useScrollRestore.ts`, which\n// hardcoded the key prefix to `\"kinstripe.scrollPos\"`. Here the prefix is a\n// parameter (`buildScrollRestoreKey`) / hook option, so the package stays\n// app-agnostic.\n\n/** Default localStorage key prefix used when no `prefix` option is given. */\nexport const DEFAULT_SCROLL_RESTORE_PREFIX = \"hazo_ui:scrollPos\";\n\n/**\n * Composes the localStorage key from a prefix, tree id, and view name.\n *\n * @example\n *   buildScrollRestoreKey(\"hazo_ui:scrollPos\", \"tree-42\", \"canvas\");\n *   // -> \"hazo_ui:scrollPos.tree-42.canvas\"\n */\nexport function buildScrollRestoreKey(prefix: string, treeId: string, viewName: string): string {\n  return `${prefix}.${treeId}.${viewName}`;\n}\n\n/**\n * Persists a scroll position (rounded to the nearest pixel) under `key`.\n * SSR-safe — no-ops on the server. Quota / private-mode errors are\n * swallowed; a failed write is non-fatal.\n *\n * @param key     - localStorage key (see `buildScrollRestoreKey`).\n * @param scrollY - Scroll offset in pixels.\n */\nexport function saveScrollPos(key: string, scrollY: number): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(key, String(Math.round(scrollY)));\n  } catch {\n    /* quota exceeded — silently drop */\n  }\n}\n\n/**\n * Reads back the scroll position stored under `key`. SSR-safe — returns\n * `null` on the server, when nothing is stored, or when the stored value\n * isn't a finite number.\n *\n * @param key - localStorage key (see `buildScrollRestoreKey`).\n */\nexport function loadScrollPos(key: string): number | null {\n  if (typeof window === \"undefined\") return null;\n  try {\n    const raw = window.localStorage.getItem(key);\n    if (!raw) return null;\n    const n = Number.parseInt(raw, 10);\n    return Number.isFinite(n) ? n : null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/index.utils.d.cts

@@ -1,2 +1,32 @@
-export { c as cn } from './index.utils-DZVbQXFR.cjs';
+export { A as AnnounceOptions, a as AnnouncePriority, D as DEFAULT_ANNOUNCE_EVENT, L as LiveAnnouncement, b as announce, c as cn, h as hasUrlParam, r as readRememberedState, w as writeRememberedState } from './announce-DAnQDTld.cjs';
 import 'clsx';
+
+/** Default localStorage key prefix used when no `prefix` option is given. */
+declare const DEFAULT_SCROLL_RESTORE_PREFIX = "hazo_ui:scrollPos";
+/**
+ * Composes the localStorage key from a prefix, tree id, and view name.
+ *
+ * @example
+ *   buildScrollRestoreKey("hazo_ui:scrollPos", "tree-42", "canvas");
+ *   // -> "hazo_ui:scrollPos.tree-42.canvas"
+ */
+declare function buildScrollRestoreKey(prefix: string, treeId: string, viewName: string): string;
+/**
+ * Persists a scroll position (rounded to the nearest pixel) under `key`.
+ * SSR-safe — no-ops on the server. Quota / private-mode errors are
+ * swallowed; a failed write is non-fatal.
+ *
+ * @param key     - localStorage key (see `buildScrollRestoreKey`).
+ * @param scrollY - Scroll offset in pixels.
+ */
+declare function saveScrollPos(key: string, scrollY: number): void;
+/**
+ * Reads back the scroll position stored under `key`. SSR-safe — returns
+ * `null` on the server, when nothing is stored, or when the stored value
+ * isn't a finite number.
+ *
+ * @param key - localStorage key (see `buildScrollRestoreKey`).
+ */
+declare function loadScrollPos(key: string): number | null;
+
+export { DEFAULT_SCROLL_RESTORE_PREFIX, buildScrollRestoreKey, loadScrollPos, saveScrollPos };

package/dist/index.utils.d.ts

@@ -1,2 +1,32 @@
-export { c as cn } from './index.utils-DZVbQXFR.js';
+export { A as AnnounceOptions, a as AnnouncePriority, D as DEFAULT_ANNOUNCE_EVENT, L as LiveAnnouncement, b as announce, c as cn, h as hasUrlParam, r as readRememberedState, w as writeRememberedState } from './announce-DAnQDTld.js';
 import 'clsx';
+
+/** Default localStorage key prefix used when no `prefix` option is given. */
+declare const DEFAULT_SCROLL_RESTORE_PREFIX = "hazo_ui:scrollPos";
+/**
+ * Composes the localStorage key from a prefix, tree id, and view name.
+ *
+ * @example
+ *   buildScrollRestoreKey("hazo_ui:scrollPos", "tree-42", "canvas");
+ *   // -> "hazo_ui:scrollPos.tree-42.canvas"
+ */
+declare function buildScrollRestoreKey(prefix: string, treeId: string, viewName: string): string;
+/**
+ * Persists a scroll position (rounded to the nearest pixel) under `key`.
+ * SSR-safe — no-ops on the server. Quota / private-mode errors are
+ * swallowed; a failed write is non-fatal.
+ *
+ * @param key     - localStorage key (see `buildScrollRestoreKey`).
+ * @param scrollY - Scroll offset in pixels.
+ */
+declare function saveScrollPos(key: string, scrollY: number): void;
+/**
+ * Reads back the scroll position stored under `key`. SSR-safe — returns
+ * `null` on the server, when nothing is stored, or when the stored value
+ * isn't a finite number.
+ *
+ * @param key - localStorage key (see `buildScrollRestoreKey`).
+ */
+declare function loadScrollPos(key: string): number | null;
+
+export { DEFAULT_SCROLL_RESTORE_PREFIX, buildScrollRestoreKey, loadScrollPos, saveScrollPos };

package/dist/index.utils.js

@@ -5,6 +5,69 @@ function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
 
-export { cn };
+// src/lib/remembered_state.ts
+function readRememberedState(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function writeRememberedState(key, snapshot) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(snapshot));
+  } catch {
+  }
+}
+function hasUrlParam(search, paramName) {
+  try {
+    return new URLSearchParams(search).has(paramName);
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/announce.ts
+var DEFAULT_ANNOUNCE_EVENT = "hazo_ui:announce";
+function announce(message, priority = "polite", options) {
+  if (typeof window === "undefined") return;
+  const trimmed = message.trim();
+  if (!trimmed) return;
+  const eventName = options?.eventName ?? DEFAULT_ANNOUNCE_EVENT;
+  window.dispatchEvent(
+    new CustomEvent(eventName, {
+      detail: { message: trimmed, priority }
+    })
+  );
+}
+
+// src/lib/scroll_restore.ts
+var DEFAULT_SCROLL_RESTORE_PREFIX = "hazo_ui:scrollPos";
+function buildScrollRestoreKey(prefix, treeId, viewName) {
+  return `${prefix}.${treeId}.${viewName}`;
+}
+function saveScrollPos(key, scrollY) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, String(Math.round(scrollY)));
+  } catch {
+  }
+}
+function loadScrollPos(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return null;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+export { DEFAULT_ANNOUNCE_EVENT, DEFAULT_SCROLL_RESTORE_PREFIX, announce, buildScrollRestoreKey, cn, hasUrlParam, loadScrollPos, readRememberedState, saveScrollPos, writeRememberedState };
 //# sourceMappingURL=index.utils.js.map
 //# sourceMappingURL=index.utils.js.map

package/dist/index.utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/lib/utils.ts"],"names":[],"mappings":";;;AAWO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAO,OAAA,CAAQ,IAAA,CAAK,MAAM,CAAC,CAAA;AAC7B","file":"index.utils.js","sourcesContent":["// Utility functions for hazo_ui component library\n// Provides className merging utility (cn function)\n\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Merges class names using clsx and tailwind-merge\n * @param inputs - Class values to merge\n * @returns Merged class string\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n\n/**\n * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent\n * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an\n * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but\n * not protocol-relative `//…`). Returns `undefined` for anything else, so the\n * anchor renders with no href rather than an active malicious one.\n * @param url - Candidate href (may be undefined)\n * @returns The original url if allowed, otherwise undefined\n */\nexport function safeHref(url?: string): string | undefined {\n  if (!url) return undefined;\n  const trimmed = url.trim();\n  const lower = trimmed.toLowerCase();\n  if (\n    lower.startsWith(\"http://\") ||\n    lower.startsWith(\"https://\") ||\n    lower.startsWith(\"mailto:\")\n  ) {\n    return trimmed;\n  }\n  // Same-origin absolute path, but not protocol-relative \"//host\".\n  if (trimmed.startsWith(\"/\") && !trimmed.startsWith(\"//\")) {\n    return trimmed;\n  }\n  return undefined;\n}\n\n"]}
+{"version":3,"sources":["../src/lib/utils.ts","../src/lib/remembered_state.ts","../src/lib/announce.ts","../src/lib/scroll_restore.ts"],"names":[],"mappings":";;;AAWO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAO,OAAA,CAAQ,IAAA,CAAK,MAAM,CAAC,CAAA;AAC7B;;;ACIO,SAAS,oBAAuB,GAAA,EAAuB;AAC5D,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,IAAA;AAC1C,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AAC3C,IAAA,OAAO,GAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA,GAAU,IAAA;AAAA,EACxC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAaO,SAAS,oBAAA,CAAwB,KAAa,QAAA,EAAmB;AACtE,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,aAAa,OAAA,CAAQ,GAAA,EAAK,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA;AAAA,EAC3D,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AAeO,SAAS,WAAA,CAAY,QAAgB,SAAA,EAA4B;AACtE,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,eAAA,CAAgB,MAAM,CAAA,CAAE,IAAI,SAAS,CAAA;AAAA,EAClD,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;;;ACtCO,IAAM,sBAAA,GAAyB;AAuB/B,SAAS,QAAA,CACd,OAAA,EACA,QAAA,GAA6B,QAAA,EAC7B,OAAA,EACM;AACN,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,MAAM,OAAA,GAAU,QAAQ,IAAA,EAAK;AAC7B,EAAA,IAAI,CAAC,OAAA,EAAS;AACd,EAAA,MAAM,SAAA,GAAY,SAAS,SAAA,IAAa,sBAAA;AACxC,EAAA,MAAA,CAAO,aAAA;AAAA,IACL,IAAI,YAA8B,SAAA,EAAW;AAAA,MAC3C,MAAA,EAAQ,EAAE,OAAA,EAAS,OAAA,EAAS,QAAA;AAAS,KACtC;AAAA,GACH;AACF;;;ACrDO,IAAM,6BAAA,GAAgC;AAStC,SAAS,qBAAA,CAAsB,MAAA,EAAgB,MAAA,EAAgB,QAAA,EAA0B;AAC9F,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,MAAM,IAAI,QAAQ,CAAA,CAAA;AACxC;AAUO,SAAS,aAAA,CAAc,KAAa,OAAA,EAAuB;AAChE,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,YAAA,CAAa,QAAQ,GAAA,EAAK,MAAA,CAAO,KAAK,KAAA,CAAM,OAAO,CAAC,CAAC,CAAA;AAAA,EAC9D,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AASO,SAAS,cAAc,GAAA,EAA4B;AACxD,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,IAAA;AAC1C,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,IAAA,MAAM,CAAA,GAAI,MAAA,CAAO,QAAA,CAAS,GAAA,EAAK,EAAE,CAAA;AACjC,IAAA,OAAO,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA,GAAI,CAAA,GAAI,IAAA;AAAA,EAClC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF","file":"index.utils.js","sourcesContent":["// Utility functions for hazo_ui component library\n// Provides className merging utility (cn function)\n\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Merges class names using clsx and tailwind-merge\n * @param inputs - Class values to merge\n * @returns Merged class string\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n\n/**\n * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent\n * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an\n * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but\n * not protocol-relative `//…`). Returns `undefined` for anything else, so the\n * anchor renders with no href rather than an active malicious one.\n * @param url - Candidate href (may be undefined)\n * @returns The original url if allowed, otherwise undefined\n */\nexport function safeHref(url?: string): string | undefined {\n  if (!url) return undefined;\n  const trimmed = url.trim();\n  const lower = trimmed.toLowerCase();\n  if (\n    lower.startsWith(\"http://\") ||\n    lower.startsWith(\"https://\") ||\n    lower.startsWith(\"mailto:\")\n  ) {\n    return trimmed;\n  }\n  // Same-origin absolute path, but not protocol-relative \"//host\".\n  if (trimmed.startsWith(\"/\") && !trimmed.startsWith(\"//\")) {\n    return trimmed;\n  }\n  return undefined;\n}\n\n","// remembered_state.ts — SSR-safe localStorage read/write/URL-param helpers\n// backing `useRememberedState` (src/hooks/use_remembered_state.ts). Pure,\n// framework-free functions (no React) so they're independently testable and\n// usable outside the hook. No \"use client\" directive here — this module is\n// re-exported from both the main client bundle (`hazo_ui`) and the pure\n// server-safe subpath (`hazo_ui/utils`), same dual-export pattern as `cn`.\n\n/**\n * Reads and JSON-parses the remembered value stored under `key`. SSR-safe —\n * returns `null` on the server, when nothing is stored, or when the stored\n * value is corrupt/unparsable.\n *\n * @param key - localStorage key to read.\n *\n * @example\n *   const seed = readRememberedState<MySeed>(\"myapp:tool:cgt\");\n */\nexport function readRememberedState<T>(key: string): T | null {\n  if (typeof window === \"undefined\") return null;\n  try {\n    const raw = window.localStorage.getItem(key);\n    return raw ? (JSON.parse(raw) as T) : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * JSON-stringifies and writes `snapshot` under `key`. SSR-safe — no-ops on\n * the server. Quota / private-mode errors are swallowed; losing a memory\n * write is non-fatal.\n *\n * @param key      - localStorage key to write.\n * @param snapshot - Serialisable value to remember.\n *\n * @example\n *   writeRememberedState(\"myapp:tool:cgt\", { proceeds: 1000 });\n */\nexport function writeRememberedState<T>(key: string, snapshot: T): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(key, JSON.stringify(snapshot));\n  } catch {\n    /* quota / private-mode — non-fatal */\n  }\n}\n\n/**\n * True when `paramName` is present in the given search string (e.g.\n * `window.location.search`). Generic form of the \"an explicit shared-link /\n * saved-record query param always wins over remembered state\" precedence\n * check — callers supply the param name (e.g. `\"restore\"`); this module\n * never hardcodes one.\n *\n * @param search    - A URL search string, e.g. `window.location.search`.\n * @param paramName - The query param to look for.\n *\n * @example\n *   hasUrlParam(\"?restore=abc123\", \"restore\"); // true\n */\nexport function hasUrlParam(search: string, paramName: string): boolean {\n  try {\n    return new URLSearchParams(search).has(paramName);\n  } catch {\n    return false;\n  }\n}\n","// announce.ts — SSR-safe screen-reader announcement bus. Dispatches a\n// `window` CustomEvent that `LiveRegion` (../components/live_region/)\n// listens for. Pure, framework-free (no React) so it's independently\n// testable and usable outside a component. No \"use client\" directive here\n// — this module is re-exported from both the main client bundle\n// (`hazo_ui`) and the pure server-safe subpath (`hazo_ui/utils`), same\n// dual-export pattern as `cn` and the `remembered_state` helpers.\n//\n// Ported from Kinstripe's `src/lib/a11y/announce.ts`, which hardcoded the\n// event name to `\"kinstripe:announce\"`. Here the event name is caller-\n// configurable (`options.eventName`) so multiple apps — or multiple\n// `LiveRegion` instances on the same page — don't collide on a single\n// hardcoded channel; it defaults to `DEFAULT_ANNOUNCE_EVENT` for\n// single-app usage.\n\nexport type AnnouncePriority = \"polite\" | \"assertive\";\n\nexport interface LiveAnnouncement {\n  message: string;\n  priority: AnnouncePriority;\n}\n\nexport interface AnnounceOptions {\n  /** Custom-event name the paired `LiveRegion` listens on. Must match the `eventName` it was mounted with. Default `DEFAULT_ANNOUNCE_EVENT`. */\n  eventName?: string;\n}\n\n/** Default `window` CustomEvent name used when `announce()` / `LiveRegion` are not given an explicit `eventName`. */\nexport const DEFAULT_ANNOUNCE_EVENT = \"hazo_ui:announce\";\n\n/**\n * Dispatch a screen-reader announcement via a `window` CustomEvent. Safe to\n * call from anywhere in the client tree — no-ops during SSR or before a\n * `LiveRegion` has mounted (fire-and-forget; there's no queue/replay).\n *\n * Use `\"polite\"` (default) for ambient updates (\"Sarah joined the canvas\",\n * \"2 new notifications\"). Use `\"assertive\"` only for things the user must\n * hear immediately (errors that interrupt a task).\n *\n * @param message  - Text to announce. Empty / whitespace-only messages are dropped (no dispatch).\n * @param priority - `\"polite\"` (default) or `\"assertive\"`.\n * @param options.eventName - Custom-event name to dispatch on. Default `DEFAULT_ANNOUNCE_EVENT`.\n *\n * @example\n *   announce(\"2 new notifications\");\n *   announce(\"Save failed — check your connection\", \"assertive\");\n *\n * @example\n *   // namespaced channel — must match the eventName the LiveRegion was mounted with\n *   announce(\"Saved\", \"polite\", { eventName: \"myapp:announce\" });\n */\nexport function announce(\n  message: string,\n  priority: AnnouncePriority = \"polite\",\n  options?: AnnounceOptions,\n): void {\n  if (typeof window === \"undefined\") return;\n  const trimmed = message.trim();\n  if (!trimmed) return;\n  const eventName = options?.eventName ?? DEFAULT_ANNOUNCE_EVENT;\n  window.dispatchEvent(\n    new CustomEvent<LiveAnnouncement>(eventName, {\n      detail: { message: trimmed, priority },\n    }),\n  );\n}\n","// scroll_restore.ts — SSR-safe localStorage read/write helpers backing\n// `useScrollRestore` (../hooks/use_scroll_restore.ts). Pure, framework-free\n// functions (no React) so they're independently testable and usable\n// outside the hook — same split as `remembered_state.ts` /\n// `useRememberedState`. No \"use client\" directive here.\n//\n// Ported from Kinstripe's `src/lib/hooks/useScrollRestore.ts`, which\n// hardcoded the key prefix to `\"kinstripe.scrollPos\"`. Here the prefix is a\n// parameter (`buildScrollRestoreKey`) / hook option, so the package stays\n// app-agnostic.\n\n/** Default localStorage key prefix used when no `prefix` option is given. */\nexport const DEFAULT_SCROLL_RESTORE_PREFIX = \"hazo_ui:scrollPos\";\n\n/**\n * Composes the localStorage key from a prefix, tree id, and view name.\n *\n * @example\n *   buildScrollRestoreKey(\"hazo_ui:scrollPos\", \"tree-42\", \"canvas\");\n *   // -> \"hazo_ui:scrollPos.tree-42.canvas\"\n */\nexport function buildScrollRestoreKey(prefix: string, treeId: string, viewName: string): string {\n  return `${prefix}.${treeId}.${viewName}`;\n}\n\n/**\n * Persists a scroll position (rounded to the nearest pixel) under `key`.\n * SSR-safe — no-ops on the server. Quota / private-mode errors are\n * swallowed; a failed write is non-fatal.\n *\n * @param key     - localStorage key (see `buildScrollRestoreKey`).\n * @param scrollY - Scroll offset in pixels.\n */\nexport function saveScrollPos(key: string, scrollY: number): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(key, String(Math.round(scrollY)));\n  } catch {\n    /* quota exceeded — silently drop */\n  }\n}\n\n/**\n * Reads back the scroll position stored under `key`. SSR-safe — returns\n * `null` on the server, when nothing is stored, or when the stored value\n * isn't a finite number.\n *\n * @param key - localStorage key (see `buildScrollRestoreKey`).\n */\nexport function loadScrollPos(key: string): number | null {\n  if (typeof window === \"undefined\") return null;\n  try {\n    const raw = window.localStorage.getItem(key);\n    if (!raw) return null;\n    const n = Number.parseInt(raw, 10);\n    return Number.isFinite(n) ? n : null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_ui",
-  "version": "6.0.0",
+  "version": "6.3.0",
   "description": "Set of UI components for common interaction elements in a SaaS app",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
     "react-dom": "^18.0.0 || ^19.0.0",
     "hazo_core": "^1.2.1",
     "hazo_state": "^0.1.2",
-    "hazo_theme": "^1.0.0"
+    "hazo_theme": "^1.0.1"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.1.0",
@@ -115,7 +115,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "hazo_core": "^1.2.1",
-    "hazo_theme": "^1.0.0",
+    "hazo_theme": "^1.0.1",
     "postcss": "^8.4.49",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

package/dist/index.utils-DZVbQXFR.d.cts

@@ -1,20 +0,0 @@
-import { ClassValue } from 'clsx';
-
-/**
- * Merges class names using clsx and tailwind-merge
- * @param inputs - Class values to merge
- * @returns Merged class string
- */
-declare function cn(...inputs: ClassValue[]): string;
-/**
- * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent
- * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an
- * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but
- * not protocol-relative `//…`). Returns `undefined` for anything else, so the
- * anchor renders with no href rather than an active malicious one.
- * @param url - Candidate href (may be undefined)
- * @returns The original url if allowed, otherwise undefined
- */
-declare function safeHref(url?: string): string | undefined;
-
-export { cn as c, safeHref as s };

package/dist/index.utils-DZVbQXFR.d.ts

@@ -1,20 +0,0 @@
-import { ClassValue } from 'clsx';
-
-/**
- * Merges class names using clsx and tailwind-merge
- * @param inputs - Class values to merge
- * @returns Merged class string
- */
-declare function cn(...inputs: ClassValue[]): string;
-/**
- * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent
- * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an
- * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but
- * not protocol-relative `//…`). Returns `undefined` for anything else, so the
- * anchor renders with no href rather than an active malicious one.
- * @param url - Candidate href (may be undefined)
- * @returns The original url if allowed, otherwise undefined
- */
-declare function safeHref(url?: string): string | undefined;
-
-export { cn as c, safeHref as s };