@camstack/ui-library 1.2.7 → 1.2.9

package/dist/composites/format-state-value.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Leaf formatting for the device State panel — in particular, turning epoch
+ * timestamps into readable local dates.
+ *
+ * ## Why this needs a rule rather than a `typeof`
+ *
+ * `lastFetchedAt: 1785060000000` is unreadable, and every `runtimeState` slice is
+ * required to carry one. But "large number" is not "timestamp": `bitrate`,
+ * `memoryRss`, `diskFree` and `retentionDays` are all numbers, and rendering a
+ * bitrate as a date in 1970 is worse than leaving it raw.
+ *
+ * So a value is treated as a time point only when BOTH hold:
+ *
+ *   1. the KEY names a time point — `…At`, `…AtMs`, `timestamp`, `…Since`,
+ *      `lastSeen`, `expires…`; and
+ *   2. the NUMBER falls in a plausible epoch range.
+ *
+ * Requiring both is what keeps `uptimeSeconds` (a duration whose name contains
+ * "time"), `timeoutMs` and `batchIntervalMs` (durations ending in "Ms") out of it.
+ * Durations are deliberately NOT converted — this formats instants, not spans.
+ *
+ * ## The raw value is never lost
+ *
+ * This is a debugging panel, so the exact number still matters. The formatted text
+ * is what is shown; `raw` is returned alongside for a `title` tooltip, and search
+ * matches against both. Replacing the value outright would trade one kind of
+ * unreadability for another.
+ */
+export declare function isTimeKey(key: string): boolean;
+/** Epoch milliseconds for a numeric value under a time-shaped key, else null. */
+export declare function epochMsOf(value: number): number | null;
+/**
+ * Locale-formatted instant. `undefined` locale means the viewer's own locale,
+ * which is the point — an operator in Rome should not read UTC.
+ */
+export declare function formatLocalDate(epochMs: number): string;
+export interface FormattedLeaf {
+    /** What is displayed. */
+    readonly text: string;
+    /**
+     * The untouched original, present ONLY when `text` differs from it — so a
+     * caller can show a tooltip without one on every unremarkable value.
+     */
+    readonly raw: string | null;
+}
+/**
+ * Format one leaf of the state tree, given the key it sits under.
+ *
+ * Handles two timestamp shapes:
+ *   - a NUMBER under a time-shaped key → local date, raw kept
+ *   - an ISO-8601 STRING → local date, raw kept. No key check needed: an ISO
+ *     string is unambiguous, and a Moleculer round-trip turns every `Date` into
+ *     one, so these appear whether or not the key looks temporal.
+ */
+export declare function formatLeafValue(key: string, value: unknown): FormattedLeaf;
+/**
+ * Strict ISO-8601 with a time part. Requires the `T` and at least
+ * `hh:mm` — a bare `2026-07-26` is far more often a version, an id fragment or a
+ * label than a date, and `Date.parse` would silently read it as UTC midnight and
+ * shift it a day in a negative-offset locale.
+ */
+export declare function isIsoDateString(value: string): boolean;

package/dist/index.cjs

@@ -44922,6 +44922,137 @@ function StatusBadge$1({ status }) {
 	}
 }
 //#endregion
+//#region src/composites/format-state-value.ts
+/**
+* Leaf formatting for the device State panel — in particular, turning epoch
+* timestamps into readable local dates.
+*
+* ## Why this needs a rule rather than a `typeof`
+*
+* `lastFetchedAt: 1785060000000` is unreadable, and every `runtimeState` slice is
+* required to carry one. But "large number" is not "timestamp": `bitrate`,
+* `memoryRss`, `diskFree` and `retentionDays` are all numbers, and rendering a
+* bitrate as a date in 1970 is worse than leaving it raw.
+*
+* So a value is treated as a time point only when BOTH hold:
+*
+*   1. the KEY names a time point — `…At`, `…AtMs`, `timestamp`, `…Since`,
+*      `lastSeen`, `expires…`; and
+*   2. the NUMBER falls in a plausible epoch range.
+*
+* Requiring both is what keeps `uptimeSeconds` (a duration whose name contains
+* "time"), `timeoutMs` and `batchIntervalMs` (durations ending in "Ms") out of it.
+* Durations are deliberately NOT converted — this formats instants, not spans.
+*
+* ## The raw value is never lost
+*
+* This is a debugging panel, so the exact number still matters. The formatted text
+* is what is shown; `raw` is returned alongside for a `title` tooltip, and search
+* matches against both. Replacing the value outright would trade one kind of
+* unreadability for another.
+*/
+/**
+* Keys that name an instant. Anchored to the END of the key so `updatedAt` and
+* `lastPushAtMs` match while `timeoutMs`, `batchIntervalMs`, `retentionDays` and
+* `uptimeSeconds` do not.
+*/
+var TIME_KEY_PATTERNS = [
+	/at$/i,
+	/atms$/i,
+	/^timestamp$/i,
+	/timestamp$/i,
+	/since$/i,
+	/^lastseen$/i,
+	/lastseen$/i,
+	/^expires?$/i,
+	/expiry$/i
+];
+/**
+* Plausible epoch windows, roughly 2001 → 2096. Deliberately narrow: it is what
+* separates a timestamp from a byte count that happens to be large, and from `0`
+* (which in this codebase means "never", and must stay `0` rather than becoming
+* 1 January 1970).
+*/
+var MS_EPOCH_MIN = 0xe8d4a51000;
+var MS_EPOCH_MAX = 4e12;
+var SEC_EPOCH_MIN = 1e9;
+var SEC_EPOCH_MAX = 4e9;
+function isTimeKey(key) {
+	return TIME_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+/** Epoch milliseconds for a numeric value under a time-shaped key, else null. */
+function epochMsOf(value) {
+	if (!Number.isFinite(value)) return null;
+	if (value >= MS_EPOCH_MIN && value <= MS_EPOCH_MAX) return value;
+	if (value >= SEC_EPOCH_MIN && value <= SEC_EPOCH_MAX) return value * 1e3;
+	return null;
+}
+/**
+* Locale-formatted instant. `undefined` locale means the viewer's own locale,
+* which is the point — an operator in Rome should not read UTC.
+*/
+function formatLocalDate(epochMs) {
+	const date = new Date(epochMs);
+	if (Number.isNaN(date.getTime())) return String(epochMs);
+	return date.toLocaleString(void 0, {
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	});
+}
+function plain(v) {
+	if (v === null) return "null";
+	if (v === void 0) return "undefined";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean") return String(v);
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return String(v);
+	}
+}
+/**
+* Format one leaf of the state tree, given the key it sits under.
+*
+* Handles two timestamp shapes:
+*   - a NUMBER under a time-shaped key → local date, raw kept
+*   - an ISO-8601 STRING → local date, raw kept. No key check needed: an ISO
+*     string is unambiguous, and a Moleculer round-trip turns every `Date` into
+*     one, so these appear whether or not the key looks temporal.
+*/
+function formatLeafValue(key, value) {
+	if (typeof value === "number" && isTimeKey(key)) {
+		const epochMs = epochMsOf(value);
+		if (epochMs !== null) return {
+			text: formatLocalDate(epochMs),
+			raw: String(value)
+		};
+	}
+	if (typeof value === "string" && isIsoDateString(value)) {
+		const parsed = Date.parse(value);
+		if (!Number.isNaN(parsed)) return {
+			text: formatLocalDate(parsed),
+			raw: value
+		};
+	}
+	return {
+		text: plain(value),
+		raw: null
+	};
+}
+/**
+* Strict ISO-8601 with a time part. Requires the `T` and at least
+* `hh:mm` — a bare `2026-07-26` is far more often a version, an id fragment or a
+* label than a date, and `Date.parse` would silently read it as UTC midnight and
+* shift it a day in a negative-offset locale.
+*/
+function isIsoDateString(value) {
+	return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/.test(value);
+}
+//#endregion
 //#region src/composites/state-values-stream.tsx
 /**
 * StateValuesStream — live current-state tree for ui-library.
@@ -45443,24 +45574,28 @@ function CapNode({ capName, slice, updatedAt, searchNeedle, isPathOpen, onToggle
 function TreeNode({ path, nodeKey, value, depth, searchNeedle, isPathOpen, onToggle }) {
 	const branch = asBranch(value);
 	const indentStyle = { paddingLeft: `${12 + depth * 14}px` };
-	if (!branch) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: "flex items-start gap-1 px-3 py-0.5",
-		style: indentStyle,
-		children: [
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-				className: cn("shrink-0", highlightCls(nodeKey, searchNeedle, "text-primary/70")),
-				children: nodeKey
-			}),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-				className: "text-foreground-subtle",
-				children: ":"
-			}),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-				className: cn("break-all", highlightCls(formatValue(value), searchNeedle, valueCls(value))),
-				children: formatValue(value)
-			})
-		]
-	});
+	if (!branch) {
+		const leaf = formatLeafValue(nodeKey, value);
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: "flex items-start gap-1 px-3 py-0.5",
+			style: indentStyle,
+			children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: cn("shrink-0", highlightCls(nodeKey, searchNeedle, "text-primary/70")),
+					children: nodeKey
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "text-foreground-subtle",
+					children: ":"
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: cn("break-all", highlightCls(leaf.text, searchNeedle, valueCls(value))),
+					...leaf.raw === null ? {} : { title: leaf.raw },
+					children: leaf.text
+				})
+			]
+		});
+	}
 	const open = isPathOpen(path, depth);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: "flex items-center gap-1 px-3 py-0.5 hover:bg-surface-hover/30 cursor-pointer select-none",
@@ -45525,17 +45660,6 @@ function asBranch(value) {
 	}
 	return null;
 }
-function formatValue(v) {
-	if (v === null) return "null";
-	if (v === void 0) return "undefined";
-	if (typeof v === "string") return v;
-	if (typeof v === "number" || typeof v === "boolean") return String(v);
-	try {
-		return JSON.stringify(v);
-	} catch {
-		return String(v);
-	}
-}
 /** Tailwind colour for a leaf value by JS type. */
 function valueCls(v) {
 	if (v === null || v === void 0) return "text-foreground-subtle/60";
@@ -45549,18 +45673,27 @@ function highlightCls(text, needle, base) {
 	if (needle && text.toLowerCase().includes(needle)) return cn(base, "bg-violet-500/20 rounded px-0.5");
 	return base;
 }
-/** Deep search a slice — true when `needle` appears in any key or any
-*  stringified leaf value anywhere in the tree. */
-function sliceMatchesSearch(value, needle) {
-	if (Array.isArray(value)) return value.some((v) => sliceMatchesSearch(v, needle));
+/**
+* Deep search a slice — true when `needle` appears in any key or any leaf value
+* anywhere in the tree.
+*
+* `key` is threaded down so a leaf is matched the way it is DISPLAYED: a timestamp
+* shown as a local date has to be findable by typing part of that date. Both forms
+* match, so the raw epoch still works too — the operator should not have to know
+* which one the panel chose to render.
+*/
+function sliceMatchesSearch(value, needle, key = "") {
+	if (Array.isArray(value)) return value.some((v, i) => sliceMatchesSearch(v, needle, String(i)));
 	if (value && typeof value === "object") {
 		for (const [k, v] of Object.entries(value)) {
 			if (k.toLowerCase().includes(needle)) return true;
-			if (sliceMatchesSearch(v, needle)) return true;
+			if (sliceMatchesSearch(v, needle, k)) return true;
 		}
 		return false;
 	}
-	return formatValue(value).toLowerCase().includes(needle);
+	const leaf = formatLeafValue(key, value);
+	if (leaf.text.toLowerCase().includes(needle)) return true;
+	return leaf.raw !== null && leaf.raw.toLowerCase().includes(needle);
 }
 /** Human "Ns ago" / "Nm ago" age label for the per-cap freshness
 *  indicator. */

package/dist/index.js

@@ -44898,6 +44898,137 @@ function StatusBadge$1({ status }) {
 	}
 }
 //#endregion
+//#region src/composites/format-state-value.ts
+/**
+* Leaf formatting for the device State panel — in particular, turning epoch
+* timestamps into readable local dates.
+*
+* ## Why this needs a rule rather than a `typeof`
+*
+* `lastFetchedAt: 1785060000000` is unreadable, and every `runtimeState` slice is
+* required to carry one. But "large number" is not "timestamp": `bitrate`,
+* `memoryRss`, `diskFree` and `retentionDays` are all numbers, and rendering a
+* bitrate as a date in 1970 is worse than leaving it raw.
+*
+* So a value is treated as a time point only when BOTH hold:
+*
+*   1. the KEY names a time point — `…At`, `…AtMs`, `timestamp`, `…Since`,
+*      `lastSeen`, `expires…`; and
+*   2. the NUMBER falls in a plausible epoch range.
+*
+* Requiring both is what keeps `uptimeSeconds` (a duration whose name contains
+* "time"), `timeoutMs` and `batchIntervalMs` (durations ending in "Ms") out of it.
+* Durations are deliberately NOT converted — this formats instants, not spans.
+*
+* ## The raw value is never lost
+*
+* This is a debugging panel, so the exact number still matters. The formatted text
+* is what is shown; `raw` is returned alongside for a `title` tooltip, and search
+* matches against both. Replacing the value outright would trade one kind of
+* unreadability for another.
+*/
+/**
+* Keys that name an instant. Anchored to the END of the key so `updatedAt` and
+* `lastPushAtMs` match while `timeoutMs`, `batchIntervalMs`, `retentionDays` and
+* `uptimeSeconds` do not.
+*/
+var TIME_KEY_PATTERNS = [
+	/at$/i,
+	/atms$/i,
+	/^timestamp$/i,
+	/timestamp$/i,
+	/since$/i,
+	/^lastseen$/i,
+	/lastseen$/i,
+	/^expires?$/i,
+	/expiry$/i
+];
+/**
+* Plausible epoch windows, roughly 2001 → 2096. Deliberately narrow: it is what
+* separates a timestamp from a byte count that happens to be large, and from `0`
+* (which in this codebase means "never", and must stay `0` rather than becoming
+* 1 January 1970).
+*/
+var MS_EPOCH_MIN = 0xe8d4a51000;
+var MS_EPOCH_MAX = 4e12;
+var SEC_EPOCH_MIN = 1e9;
+var SEC_EPOCH_MAX = 4e9;
+function isTimeKey(key) {
+	return TIME_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+/** Epoch milliseconds for a numeric value under a time-shaped key, else null. */
+function epochMsOf(value) {
+	if (!Number.isFinite(value)) return null;
+	if (value >= MS_EPOCH_MIN && value <= MS_EPOCH_MAX) return value;
+	if (value >= SEC_EPOCH_MIN && value <= SEC_EPOCH_MAX) return value * 1e3;
+	return null;
+}
+/**
+* Locale-formatted instant. `undefined` locale means the viewer's own locale,
+* which is the point — an operator in Rome should not read UTC.
+*/
+function formatLocalDate(epochMs) {
+	const date = new Date(epochMs);
+	if (Number.isNaN(date.getTime())) return String(epochMs);
+	return date.toLocaleString(void 0, {
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	});
+}
+function plain(v) {
+	if (v === null) return "null";
+	if (v === void 0) return "undefined";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean") return String(v);
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return String(v);
+	}
+}
+/**
+* Format one leaf of the state tree, given the key it sits under.
+*
+* Handles two timestamp shapes:
+*   - a NUMBER under a time-shaped key → local date, raw kept
+*   - an ISO-8601 STRING → local date, raw kept. No key check needed: an ISO
+*     string is unambiguous, and a Moleculer round-trip turns every `Date` into
+*     one, so these appear whether or not the key looks temporal.
+*/
+function formatLeafValue(key, value) {
+	if (typeof value === "number" && isTimeKey(key)) {
+		const epochMs = epochMsOf(value);
+		if (epochMs !== null) return {
+			text: formatLocalDate(epochMs),
+			raw: String(value)
+		};
+	}
+	if (typeof value === "string" && isIsoDateString(value)) {
+		const parsed = Date.parse(value);
+		if (!Number.isNaN(parsed)) return {
+			text: formatLocalDate(parsed),
+			raw: value
+		};
+	}
+	return {
+		text: plain(value),
+		raw: null
+	};
+}
+/**
+* Strict ISO-8601 with a time part. Requires the `T` and at least
+* `hh:mm` — a bare `2026-07-26` is far more often a version, an id fragment or a
+* label than a date, and `Date.parse` would silently read it as UTC midnight and
+* shift it a day in a negative-offset locale.
+*/
+function isIsoDateString(value) {
+	return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/.test(value);
+}
+//#endregion
 //#region src/composites/state-values-stream.tsx
 /**
 * StateValuesStream — live current-state tree for ui-library.
@@ -45419,24 +45550,28 @@ function CapNode({ capName, slice, updatedAt, searchNeedle, isPathOpen, onToggle
 function TreeNode({ path, nodeKey, value, depth, searchNeedle, isPathOpen, onToggle }) {
 	const branch = asBranch(value);
 	const indentStyle = { paddingLeft: `${12 + depth * 14}px` };
-	if (!branch) return /* @__PURE__ */ jsxs("div", {
-		className: "flex items-start gap-1 px-3 py-0.5",
-		style: indentStyle,
-		children: [
-			/* @__PURE__ */ jsx("span", {
-				className: cn("shrink-0", highlightCls(nodeKey, searchNeedle, "text-primary/70")),
-				children: nodeKey
-			}),
-			/* @__PURE__ */ jsx("span", {
-				className: "text-foreground-subtle",
-				children: ":"
-			}),
-			/* @__PURE__ */ jsx("span", {
-				className: cn("break-all", highlightCls(formatValue(value), searchNeedle, valueCls(value))),
-				children: formatValue(value)
-			})
-		]
-	});
+	if (!branch) {
+		const leaf = formatLeafValue(nodeKey, value);
+		return /* @__PURE__ */ jsxs("div", {
+			className: "flex items-start gap-1 px-3 py-0.5",
+			style: indentStyle,
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: cn("shrink-0", highlightCls(nodeKey, searchNeedle, "text-primary/70")),
+					children: nodeKey
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "text-foreground-subtle",
+					children: ":"
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: cn("break-all", highlightCls(leaf.text, searchNeedle, valueCls(value))),
+					...leaf.raw === null ? {} : { title: leaf.raw },
+					children: leaf.text
+				})
+			]
+		});
+	}
 	const open = isPathOpen(path, depth);
 	return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsxs("div", {
 		className: "flex items-center gap-1 px-3 py-0.5 hover:bg-surface-hover/30 cursor-pointer select-none",
@@ -45501,17 +45636,6 @@ function asBranch(value) {
 	}
 	return null;
 }
-function formatValue(v) {
-	if (v === null) return "null";
-	if (v === void 0) return "undefined";
-	if (typeof v === "string") return v;
-	if (typeof v === "number" || typeof v === "boolean") return String(v);
-	try {
-		return JSON.stringify(v);
-	} catch {
-		return String(v);
-	}
-}
 /** Tailwind colour for a leaf value by JS type. */
 function valueCls(v) {
 	if (v === null || v === void 0) return "text-foreground-subtle/60";
@@ -45525,18 +45649,27 @@ function highlightCls(text, needle, base) {
 	if (needle && text.toLowerCase().includes(needle)) return cn(base, "bg-violet-500/20 rounded px-0.5");
 	return base;
 }
-/** Deep search a slice — true when `needle` appears in any key or any
-*  stringified leaf value anywhere in the tree. */
-function sliceMatchesSearch(value, needle) {
-	if (Array.isArray(value)) return value.some((v) => sliceMatchesSearch(v, needle));
+/**
+* Deep search a slice — true when `needle` appears in any key or any leaf value
+* anywhere in the tree.
+*
+* `key` is threaded down so a leaf is matched the way it is DISPLAYED: a timestamp
+* shown as a local date has to be findable by typing part of that date. Both forms
+* match, so the raw epoch still works too — the operator should not have to know
+* which one the panel chose to render.
+*/
+function sliceMatchesSearch(value, needle, key = "") {
+	if (Array.isArray(value)) return value.some((v, i) => sliceMatchesSearch(v, needle, String(i)));
 	if (value && typeof value === "object") {
 		for (const [k, v] of Object.entries(value)) {
 			if (k.toLowerCase().includes(needle)) return true;
-			if (sliceMatchesSearch(v, needle)) return true;
+			if (sliceMatchesSearch(v, needle, k)) return true;
 		}
 		return false;
 	}
-	return formatValue(value).toLowerCase().includes(needle);
+	const leaf = formatLeafValue(key, value);
+	if (leaf.text.toLowerCase().includes(needle)) return true;
+	return leaf.raw !== null && leaf.raw.toLowerCase().includes(needle);
 }
 /** Human "Ns ago" / "Nm ago" age label for the per-cap freshness
 *  indicator. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/ui-library",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",