@yuneta/gobj-ui 7.23.45 → 7.23.46

package/README.md

@@ -1364,6 +1364,59 @@ only while there is somewhere to go back to, spent when used, and dropped by a
 refresh. Undoing is another write, like the drag. The host must define the key
 `"undo the order"`.
 
+### The bytes a node owns but cannot hold — `yui_asset_*`
+
+A treedb node often owns something that is not JSON: a photo, a plan, a
+clip. Those bytes cannot live in the treedb — it is held in memory and
+timeranger2 rewrites the whole record on every update — so the SDK's
+`C_ASSETS` keeps them in a directory it owns and the node names one with an
+**fkey**.
+
+`get-asset` answers in one of two shapes, and the **backend** decides which:
+
+```json
+{"mode": "url",    "url": "/assets/ab/cd/<id>.jpg?e=<expires>&s=<token>"}
+{"mode": "inline", "content_type": "image/jpeg", "content64": "..."}
+```
+
+It signs a URL when a web server sits in front of the store and hands over
+the bytes when there is none, so a consumer has **one** code path and a node
+with no web server still shows its images instead of showing nothing.
+
+This module is the two ends of that, and **it does not talk to the
+backend** — asking is an action and belongs in the view's own FSM:
+
+| | |
+|---|---|
+| `yui_asset_id(ref)` / `yui_asset_ids(ref)` | the id(s) a column names. Reads a single-valued fkey (`"assets^<id>^as_foto"`), an array fkey, and an expanded ref (`{id}`). An empty column answers nothing rather than throwing |
+| `yui_asset_src(answer)` | the two shapes into one `src`. `null` when the answer carries neither — never an empty string, because `<img src="">` reloads the page in some browsers |
+| `yui_asset_element(answer, opts)` | the element, picked from the **content type the backend stored**: `<img>`, `<video>` or `<audio>`. Video and audio are assets too, and an `<img>` whose src is a film shows the broken box this exists to remove |
+| `yui_asset_missing(detail, opts)` | the marker, for when there is nothing to show |
+
+**A missing asset is now said out loud.** It used to leave a broken box and
+no word about it, which is indistinguishable from a slow one and from a bug
+— 47 such holes in one day on `artgins.ytreedb.com` before anybody noticed.
+`yui_asset_element()` wires `onerror` so the dead element is **replaced** by
+the marker, whatever the reason: an expired signature, a blob gone from the
+store, an unsupported codec.
+
+The marker's label carries its i18n key (`asset not available`, overridable
+with `opts.key`), so it follows a language change; `opts.detail` is DATA — a
+name or a path, the thing a person can act on — and is never translated.
+
+```js
+import {yui_asset_id, yui_asset_element} from "@yuneta/gobj-ui/src/yui_asset.js";
+import "@yuneta/gobj-ui/src/yui_asset.css";
+
+// in the view's FSM, not in a DOM callback:
+const id = yui_asset_id(device.foto);
+if(id) {
+    gobj_send_event(gobj, "EV_ASK_ASSET", {asset_id: id, slot: "foto"}, gobj);
+}
+// ...and when the answer arrives, in the action:
+$box.appendChild(yui_asset_element(answer, {detail: device.foto_name}));
+```
+
 ### Frontend view — `setup_frontend_view`
 
 `setup_frontend_view(self)` opens the **gobj tree of the app's own yuno** in a

package/dist/gobj-ui.cjs.js

@@ -67043,6 +67043,118 @@ function register_c_yui_period() {
 	return create_gclass(GCLASS_NAME);
 }
 //#endregion
+//#region src/yui_asset.js
+function ref_to_id(ref) {
+	if (!ref) return null;
+	if (typeof ref === "string") {
+		const parts = ref.split("^");
+		return parts.length >= 2 ? parts[1] : null;
+	}
+	if (typeof ref === "object" && typeof ref.id === "string") return ref.id;
+	return null;
+}
+/***************************************************************************
+*  Every asset id a column names, in order. Always an array, possibly empty.
+***************************************************************************/
+function yui_asset_ids(ref) {
+	if (Array.isArray(ref)) return ref.map(ref_to_id).filter((id) => !!id);
+	const id = ref_to_id(ref);
+	return id ? [id] : [];
+}
+/***************************************************************************
+*  The first asset id a column names, or null.
+***************************************************************************/
+function yui_asset_id(ref) {
+	const ids = yui_asset_ids(ref);
+	return ids.length ? ids[0] : null;
+}
+/***************************************************************************
+*  Turn a `get-asset` answer into something an element can load.
+*
+*  Returns null when the answer carries neither -- which the caller must
+*  treat as "missing", never as an empty src: an <img src=""> reloads the
+*  PAGE in some browsers.
+***************************************************************************/
+function yui_asset_src(answer) {
+	if (!answer) return null;
+	if (answer.mode === "url" && answer.url) return answer.url;
+	if (answer.mode === "inline" && answer.content64) return `data:${answer.content_type || "application/octet-stream"};base64,${answer.content64}`;
+	return null;
+}
+/***************************************************************************
+*  The marker for an asset that is not there.
+*
+*  A missing image used to leave a broken box and no word about it, which
+*  is indistinguishable from a slow one and from a bug.  This says so, and
+*  it says WHICH: `detail` is data (a name, a path) and is never
+*  translated, while the label carries its i18n key so a language change
+*  re-translates it.
+***************************************************************************/
+function yui_asset_missing(detail, opts = {}) {
+	const key = opts.key || "asset not available";
+	const children = [["span", { class: "ASSET_MISSING_ICON yi-triangle-exclamation" }], [
+		"span",
+		{
+			class: "ASSET_MISSING_LABEL",
+			i18n: key
+		},
+		key
+	]];
+	if (detail) children.push([
+		"span",
+		{ class: "ASSET_MISSING_DETAIL" },
+		String(detail)
+	]);
+	const attrs = { class: `ASSET_MISSING ${opts.class || ""}`.trim() };
+	if (detail) attrs.title = String(detail);
+	else attrs["data-i18n-title"] = key;
+	return (0, _yuneta_gobj_js.createElement2)([
+		"div",
+		attrs,
+		children
+	]);
+}
+/***************************************************************************
+*  The element for one asset.
+*
+*  The KIND comes from the content type the backend stored, not from the
+*  name a person typed: video and audio are assets too, and an <img> whose
+*  src is a film shows the broken box this module exists to remove.
+*
+*  `detail` is what the missing marker shows -- pass the original name or
+*  the source path, the thing a person can act on.
+***************************************************************************/
+function yui_asset_element(answer, opts = {}) {
+	const src = yui_asset_src(answer);
+	if (!src) return yui_asset_missing(opts.detail, opts);
+	const ct = (answer.content_type || "").toLowerCase();
+	const cls = `ASSET_MEDIA ${opts.class || ""}`.trim();
+	let el;
+	if (ct.startsWith("video/")) el = (0, _yuneta_gobj_js.createElement2)(["video", {
+		class: cls,
+		controls: "",
+		preload: "metadata"
+	}]);
+	else if (ct.startsWith("audio/")) el = (0, _yuneta_gobj_js.createElement2)(["audio", {
+		class: cls,
+		controls: "",
+		preload: "metadata"
+	}]);
+	else {
+		el = (0, _yuneta_gobj_js.createElement2)(["img", {
+			class: cls,
+			loading: "lazy"
+		}]);
+		el.alt = opts.alt || opts.detail || "";
+	}
+	el.src = src;
+	el.onerror = () => {
+		const $marker = yui_asset_missing(opts.detail, opts);
+		if (el.parentNode) el.parentNode.replaceChild($marker, el);
+	};
+	return el;
+}
+//#endregion
 //#region src/dev_machine_trace.js
 /***********************************************************************
 *          dev_machine_trace.js
@@ -68791,6 +68903,11 @@ exports.set_submit_state = set_submit_state;
 exports.setup_dev = setup_dev;
 exports.setup_frontend_view = setup_frontend_view;
 exports.toggleClasses = toggleClasses;
+exports.yui_asset_element = yui_asset_element;
+exports.yui_asset_id = yui_asset_id;
+exports.yui_asset_ids = yui_asset_ids;
+exports.yui_asset_missing = yui_asset_missing;
+exports.yui_asset_src = yui_asset_src;
 exports.yui_is_dark = yui_is_dark;
 exports.yui_mount_service_view = yui_mount_service_view;
 exports.yui_shell_close_drawer = yui_shell_close_drawer;

package/dist/gobj-ui.es.js

@@ -67038,6 +67038,118 @@ function register_c_yui_period() {
 	return create_gclass(GCLASS_NAME);
 }
 //#endregion
+//#region src/yui_asset.js
+function ref_to_id(ref) {
+	if (!ref) return null;
+	if (typeof ref === "string") {
+		const parts = ref.split("^");
+		return parts.length >= 2 ? parts[1] : null;
+	}
+	if (typeof ref === "object" && typeof ref.id === "string") return ref.id;
+	return null;
+}
+/***************************************************************************
+*  Every asset id a column names, in order. Always an array, possibly empty.
+***************************************************************************/
+function yui_asset_ids(ref) {
+	if (Array.isArray(ref)) return ref.map(ref_to_id).filter((id) => !!id);
+	const id = ref_to_id(ref);
+	return id ? [id] : [];
+}
+/***************************************************************************
+*  The first asset id a column names, or null.
+***************************************************************************/
+function yui_asset_id(ref) {
+	const ids = yui_asset_ids(ref);
+	return ids.length ? ids[0] : null;
+}
+/***************************************************************************
+*  Turn a `get-asset` answer into something an element can load.
+*
+*  Returns null when the answer carries neither -- which the caller must
+*  treat as "missing", never as an empty src: an <img src=""> reloads the
+*  PAGE in some browsers.
+***************************************************************************/
+function yui_asset_src(answer) {
+	if (!answer) return null;
+	if (answer.mode === "url" && answer.url) return answer.url;
+	if (answer.mode === "inline" && answer.content64) return `data:${answer.content_type || "application/octet-stream"};base64,${answer.content64}`;
+	return null;
+}
+/***************************************************************************
+*  The marker for an asset that is not there.
+*
+*  A missing image used to leave a broken box and no word about it, which
+*  is indistinguishable from a slow one and from a bug.  This says so, and
+*  it says WHICH: `detail` is data (a name, a path) and is never
+*  translated, while the label carries its i18n key so a language change
+*  re-translates it.
+***************************************************************************/
+function yui_asset_missing(detail, opts = {}) {
+	const key = opts.key || "asset not available";
+	const children = [["span", { class: "ASSET_MISSING_ICON yi-triangle-exclamation" }], [
+		"span",
+		{
+			class: "ASSET_MISSING_LABEL",
+			i18n: key
+		},
+		key
+	]];
+	if (detail) children.push([
+		"span",
+		{ class: "ASSET_MISSING_DETAIL" },
+		String(detail)
+	]);
+	const attrs = { class: `ASSET_MISSING ${opts.class || ""}`.trim() };
+	if (detail) attrs.title = String(detail);
+	else attrs["data-i18n-title"] = key;
+	return createElement2([
+		"div",
+		attrs,
+		children
+	]);
+}
+/***************************************************************************
+*  The element for one asset.
+*
+*  The KIND comes from the content type the backend stored, not from the
+*  name a person typed: video and audio are assets too, and an <img> whose
+*  src is a film shows the broken box this module exists to remove.
+*
+*  `detail` is what the missing marker shows -- pass the original name or
+*  the source path, the thing a person can act on.
+***************************************************************************/
+function yui_asset_element(answer, opts = {}) {
+	const src = yui_asset_src(answer);
+	if (!src) return yui_asset_missing(opts.detail, opts);
+	const ct = (answer.content_type || "").toLowerCase();
+	const cls = `ASSET_MEDIA ${opts.class || ""}`.trim();
+	let el;
+	if (ct.startsWith("video/")) el = createElement2(["video", {
+		class: cls,
+		controls: "",
+		preload: "metadata"
+	}]);
+	else if (ct.startsWith("audio/")) el = createElement2(["audio", {
+		class: cls,
+		controls: "",
+		preload: "metadata"
+	}]);
+	else {
+		el = createElement2(["img", {
+			class: cls,
+			loading: "lazy"
+		}]);
+		el.alt = opts.alt || opts.detail || "";
+	}
+	el.src = src;
+	el.onerror = () => {
+		const $marker = yui_asset_missing(opts.detail, opts);
+		if (el.parentNode) el.parentNode.replaceChild($marker, el);
+	};
+	return el;
+}
+//#endregion
 //#region src/dev_machine_trace.js
 /***********************************************************************
 *          dev_machine_trace.js
@@ -68721,6 +68833,6 @@ function setup_frontend_view(self) {
 	return win;
 }
 //#endregion
-export { EditControl, MarkerControl, YUI_PERIODS, YUI_PERIODS_DEFAULT, YUI_ROLLING, addClasses, apply_dev_traces, attach_clear, build_dev_panel, dev_window_was_open, disableElements, enableElements, epoch_to_local_input, epoch_to_ms, expose_view_container, fmt_epoch, getStrokeColor, infer_period, info_traffic, inject_svg_icons, is_current_period, iso_week, local_input_to_epoch, ms_to_epoch, period_bounds, period_bounds_epoch, period_label, period_name, period_shift, period_spec, period_start, refresh_clear, register_c_g6_nodes_tree, register_c_yui_form, register_c_yui_fsm_graph, register_c_yui_gclass, register_c_yui_gobj_tree_js, register_c_yui_json, register_c_yui_json_graph, register_c_yui_map, register_c_yui_nav, register_c_yui_pager, register_c_yui_period, register_c_yui_schema_editor, register_c_yui_service_view, register_c_yui_shell, register_c_yui_treedb_graph, register_c_yui_treedb_schema, register_c_yui_treedb_topic_with_form, register_c_yui_treedb_topics, register_c_yui_uplot, register_c_yui_window, register_c_yui_window_manager, register_c_yui_wizard, removeChildElements, removeClasses, rolling_bounds, safe_locale, set_active_state, set_cancel_state, set_pressed_state, set_submit_state, setup_dev, setup_frontend_view, toggleClasses, yui_is_dark, yui_mount_service_view, yui_shell_close_drawer, yui_shell_close_dropdown, yui_shell_confirm_danger, yui_shell_confirm_ok, yui_shell_confirm_yesno, yui_shell_confirm_yesnocancel, yui_shell_navigate, yui_shell_open_drawer, yui_shell_overlay_dismissed, yui_shell_pop_escape, yui_shell_push_escape, yui_shell_refresh_avatars, yui_shell_register_event_handler, yui_shell_register_overlay, yui_shell_set_avatar_provider, yui_shell_set_connection_state, yui_shell_set_sub_routes, yui_shell_set_toolbar_item_badge, yui_shell_set_toolbar_item_icon, yui_shell_set_translator, yui_shell_show_error, yui_shell_show_info, yui_shell_show_modal, yui_shell_show_route_map, yui_shell_show_warning, yui_shell_toggle_drawer, yui_shell_unpark_route, yui_theme_now, yui_toolbar, yui_watch_theme };
+export { EditControl, MarkerControl, YUI_PERIODS, YUI_PERIODS_DEFAULT, YUI_ROLLING, addClasses, apply_dev_traces, attach_clear, build_dev_panel, dev_window_was_open, disableElements, enableElements, epoch_to_local_input, epoch_to_ms, expose_view_container, fmt_epoch, getStrokeColor, infer_period, info_traffic, inject_svg_icons, is_current_period, iso_week, local_input_to_epoch, ms_to_epoch, period_bounds, period_bounds_epoch, period_label, period_name, period_shift, period_spec, period_start, refresh_clear, register_c_g6_nodes_tree, register_c_yui_form, register_c_yui_fsm_graph, register_c_yui_gclass, register_c_yui_gobj_tree_js, register_c_yui_json, register_c_yui_json_graph, register_c_yui_map, register_c_yui_nav, register_c_yui_pager, register_c_yui_period, register_c_yui_schema_editor, register_c_yui_service_view, register_c_yui_shell, register_c_yui_treedb_graph, register_c_yui_treedb_schema, register_c_yui_treedb_topic_with_form, register_c_yui_treedb_topics, register_c_yui_uplot, register_c_yui_window, register_c_yui_window_manager, register_c_yui_wizard, removeChildElements, removeClasses, rolling_bounds, safe_locale, set_active_state, set_cancel_state, set_pressed_state, set_submit_state, setup_dev, setup_frontend_view, toggleClasses, yui_asset_element, yui_asset_id, yui_asset_ids, yui_asset_missing, yui_asset_src, yui_is_dark, yui_mount_service_view, yui_shell_close_drawer, yui_shell_close_dropdown, yui_shell_confirm_danger, yui_shell_confirm_ok, yui_shell_confirm_yesno, yui_shell_confirm_yesnocancel, yui_shell_navigate, yui_shell_open_drawer, yui_shell_overlay_dismissed, yui_shell_pop_escape, yui_shell_push_escape, yui_shell_refresh_avatars, yui_shell_register_event_handler, yui_shell_register_overlay, yui_shell_set_avatar_provider, yui_shell_set_connection_state, yui_shell_set_sub_routes, yui_shell_set_toolbar_item_badge, yui_shell_set_toolbar_item_icon, yui_shell_set_translator, yui_shell_show_error, yui_shell_show_info, yui_shell_show_modal, yui_shell_show_route_map, yui_shell_show_warning, yui_shell_toggle_drawer, yui_shell_unpark_route, yui_theme_now, yui_toolbar, yui_watch_theme };
 
 //# sourceMappingURL=gobj-ui.es.js.map

package/index.js

@@ -119,6 +119,7 @@ export {
 export { addClasses, removeClasses, toggleClasses, removeChildElements, disableElements, enableElements, set_submit_state, set_cancel_state, set_active_state, set_pressed_state, getStrokeColor } from "./src/lib_graph.js";
 export { inject_svg_icons } from "./src/lib_icons.js";
 export { EditControl, MarkerControl } from "./src/lib_maplibre.js";
+export { yui_asset_id, yui_asset_ids, yui_asset_src, yui_asset_element, yui_asset_missing } from "./src/yui_asset.js";
 export { yui_toolbar } from "./src/yui_toolbar.js";
 export { yui_theme_now, yui_is_dark, yui_watch_theme } from "./src/yui_theme.js";
 export { attach_clear, refresh_clear } from "./src/yui_inputs.js";
@@ -131,6 +132,7 @@ export { setup_frontend_view } from "./src/yui_frontend_view.js";
  *    import "gobj-ui/src/c_yui_shell.css";     // declarative shell
  *    import "gobj-ui/src/c_yui_map.css";
  *    import "gobj-ui/src/yui_toolbar.css";
+ *    import "gobj-ui/src/yui_asset.css";
  *    import "gobj-ui/src/lib_graph.css";
  *    import "gobj-ui/src/yui_icons.css";
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.23.45",
+  "version": "7.23.46",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",
@@ -20,7 +20,7 @@
     "src/",
     "vite-plugin-yuneta-html.js"
   ],
-  "description": "Yuneta UI Library — the active line: declarative shell (C_YUI_SHELL+NAV+PAGER+WIZARD) + windows, TreeDB views, forms, charts and maps.  Consumed by wattyzer and the yunetas JS yunos (gui_agent, gui_treedb).  The frozen legacy GClass GUI stack (C_YUI_MAIN/TABS/ROUTING) lives on the v1 branch, npm dist-tag 'legacy' (consumed by estadodelaire and hidraulia).",
+  "description": "Yuneta UI Library \u2014 the active line: declarative shell (C_YUI_SHELL+NAV+PAGER+WIZARD) + windows, TreeDB views, forms, charts and maps.  Consumed by wattyzer and the yunetas JS yunos (gui_agent, gui_treedb).  The frozen legacy GClass GUI stack (C_YUI_MAIN/TABS/ROUTING) lives on the v1 branch, npm dist-tag 'legacy' (consumed by estadodelaire and hidraulia).",
   "scripts": {
     "build": "vite build",
     "test": "vitest run",

package/src/yui_asset.css

@@ -0,0 +1,43 @@
+/*
+ *  The marker of an asset that is not there.
+ *
+ *  It takes the SPACE an image would have taken, so a card does not jump
+ *  when one is missing, and it is quiet enough to sit in a gallery without
+ *  shouting -- it reports a fact, it is not an error dialog.
+ */
+.ASSET_MISSING {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 0.25rem;
+    min-width: 5rem;
+    min-height: 5rem;
+    padding: 0.5rem;
+    border: 1px dashed var(--bulma-border, #dbdbdb);
+    border-radius: var(--bulma-radius, 4px);
+    color: var(--bulma-text-weak, #7a7a7a);
+    background: var(--bulma-scheme-main-bis, transparent);
+    text-align: center;
+}
+
+.ASSET_MISSING_ICON {
+    font-size: 1.25rem;
+    opacity: 0.7;
+}
+
+.ASSET_MISSING_LABEL {
+    font-size: 0.75rem;
+}
+
+/*
+ *  The detail is a name or a path: it must not stretch the card, and it is
+ *  the one thing a person can act on, so it stays readable rather than
+ *  being cut to nothing.
+ */
+.ASSET_MISSING_DETAIL {
+    font-size: 0.7rem;
+    opacity: 0.75;
+    max-width: 12rem;
+    overflow-wrap: anywhere;
+}

package/src/yui_asset.js

@@ -0,0 +1,180 @@
+/*
+ *  The bytes a treedb node owns but cannot hold -- a photo, a plan, a clip.
+ *
+ *  A node names its asset with an FKEY, and the BACKEND decides how the
+ *  bytes travel: a signed url when a web server sits in front of the store,
+ *  the bytes inline when there is none (the SDK's `C_ASSETS get-asset`).
+ *  That is why a consumer has ONE code path, and why a node with no web
+ *  server in front of it still shows its images instead of showing nothing.
+ *
+ *  WHAT THIS MODULE DOES NOT DO IS TALK TO THE BACKEND.  Asking is an
+ *  ACTION and belongs in the view's own FSM; these are the two ends of it:
+ *  read the id out of the fkey before asking, and turn the answer into an
+ *  element afterwards.
+ *
+ *  Using Bulma Framework (https://bulma.io)
+ */
+
+import {
+    createElement2
+} from "@yuneta/gobj-js";
+
+import "./yui_asset.css";
+
+/*
+ *  A treedb fkey is `topic^id^hook`, and a column holds either one of them
+ *  (a single-valued fkey, like a device's photo) or a list (an array fkey,
+ *  like the plans of a bay).  An expanded ref -- what `refs` options give
+ *  back -- is an object carrying the id instead.
+ */
+function ref_to_id(ref)
+{
+    if(!ref) {
+        return null;
+    }
+    if(typeof ref === "string") {
+        const parts = ref.split("^");
+        return parts.length >= 2? parts[1]: null;
+    }
+    if(typeof ref === "object" && typeof ref.id === "string") {
+        return ref.id;
+    }
+    return null;
+}
+
+/***************************************************************************
+ *  Every asset id a column names, in order. Always an array, possibly empty.
+ ***************************************************************************/
+function yui_asset_ids(ref)
+{
+    if(Array.isArray(ref)) {
+        return ref.map(ref_to_id).filter((id) => !!id);
+    }
+    const id = ref_to_id(ref);
+    return id? [id]: [];
+}
+
+/***************************************************************************
+ *  The first asset id a column names, or null.
+ ***************************************************************************/
+function yui_asset_id(ref)
+{
+    const ids = yui_asset_ids(ref);
+    return ids.length? ids[0]: null;
+}
+
+/***************************************************************************
+ *  Turn a `get-asset` answer into something an element can load.
+ *
+ *  Returns null when the answer carries neither -- which the caller must
+ *  treat as "missing", never as an empty src: an <img src=""> reloads the
+ *  PAGE in some browsers.
+ ***************************************************************************/
+function yui_asset_src(answer)
+{
+    if(!answer) {
+        return null;
+    }
+    if(answer.mode === "url" && answer.url) {
+        return answer.url;
+    }
+    if(answer.mode === "inline" && answer.content64) {
+        const ct = answer.content_type || "application/octet-stream";
+        return `data:${ct};base64,${answer.content64}`;
+    }
+    return null;
+}
+
+/***************************************************************************
+ *  The marker for an asset that is not there.
+ *
+ *  A missing image used to leave a broken box and no word about it, which
+ *  is indistinguishable from a slow one and from a bug.  This says so, and
+ *  it says WHICH: `detail` is data (a name, a path) and is never
+ *  translated, while the label carries its i18n key so a language change
+ *  re-translates it.
+ ***************************************************************************/
+function yui_asset_missing(detail, opts = {})
+{
+    const key = opts.key || "asset not available";
+    const children = [
+        ["span", {class: "ASSET_MISSING_ICON yi-triangle-exclamation"}],
+        /*
+         *  createElement2() translates the content itself when it is given
+         *  `i18n`, so the KEY is what goes in -- passing t(key) would
+         *  translate it twice and, worse, freeze it: refresh_language()
+         *  only re-translates a node that carries its key.
+         */
+        ["span", {class: "ASSET_MISSING_LABEL", i18n: key}, key]
+    ];
+    if(detail) {
+        children.push(["span", {class: "ASSET_MISSING_DETAIL"}, String(detail)]);
+    }
+    /*
+     *  The tooltip is the DETAIL when there is one -- a name or a path,
+     *  which is data and must never be translated -- and the label
+     *  otherwise, through `data-i18n-title` so it follows the language.
+     */
+    const attrs = {class: `ASSET_MISSING ${opts.class || ""}`.trim()};
+    if(detail) {
+        attrs.title = String(detail);
+    } else {
+        attrs["data-i18n-title"] = key;
+    }
+    return createElement2(["div", attrs, children]);
+}
+
+/***************************************************************************
+ *  The element for one asset.
+ *
+ *  The KIND comes from the content type the backend stored, not from the
+ *  name a person typed: video and audio are assets too, and an <img> whose
+ *  src is a film shows the broken box this module exists to remove.
+ *
+ *  `detail` is what the missing marker shows -- pass the original name or
+ *  the source path, the thing a person can act on.
+ ***************************************************************************/
+function yui_asset_element(answer, opts = {})
+{
+    const src = yui_asset_src(answer);
+    if(!src) {
+        return yui_asset_missing(opts.detail, opts);
+    }
+
+    const ct = (answer.content_type || "").toLowerCase();
+    const cls = `ASSET_MEDIA ${opts.class || ""}`.trim();
+
+    let el;
+    if(ct.startsWith("video/")) {
+        el = createElement2(["video", {class: cls, controls: "", preload: "metadata"}]);
+    } else if(ct.startsWith("audio/")) {
+        el = createElement2(["audio", {class: cls, controls: "", preload: "metadata"}]);
+    } else {
+        el = createElement2(["img", {class: cls, loading: "lazy"}]);
+        el.alt = opts.alt || opts.detail || "";
+    }
+    el.src = src;
+
+    /*
+     *  A url can 403 (expired signature), a blob can be gone from the
+     *  store, a codec can be unsupported. Whatever the reason, the element
+     *  is REPLACED by the marker: leaving the dead one in place is the
+     *  silent gap this module was written to stop.
+     */
+    el.onerror = () => {
+        const $marker = yui_asset_missing(opts.detail, opts);
+        if(el.parentNode) {
+            el.parentNode.replaceChild($marker, el);
+        }
+    };
+
+    return el;
+}
+
+export {
+    yui_asset_id,
+    yui_asset_ids,
+    yui_asset_src,
+    yui_asset_element,
+    yui_asset_missing
+};

package/src/yui_asset.test.js

@@ -0,0 +1,79 @@
+/***********************************************************************
+ *          yui_asset.test.js
+ *
+ *      Unit tests for the pure logic of yui_asset.
+ *      Run with: npm test
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    yui_asset_id,
+    yui_asset_ids,
+    yui_asset_src,
+} from "./yui_asset.js";
+
+/*
+ *  A treedb fkey is `topic^id^hook`.
+ */
+test("reads the id out of a single-valued fkey", () => {
+    expect(yui_asset_id("assets^abc123^as_foto")).toBe("abc123");
+    expect(yui_asset_ids("assets^abc123^as_foto")).toEqual(["abc123"]);
+});
+
+test("reads every id out of an array fkey, in order", () => {
+    expect(yui_asset_ids([
+        "assets^p1^as_plano",
+        "assets^p2^as_plano",
+    ])).toEqual(["p1", "p2"]);
+    expect(yui_asset_id(["assets^p1^as_plano", "assets^p2^as_plano"])).toBe("p1");
+});
+
+test("reads an EXPANDED ref, which is what the refs options give back", () => {
+    expect(yui_asset_id({id: "abc123", content_type: "image/jpeg"})).toBe("abc123");
+});
+
+/*
+ *  An empty column is the normal state of a device nobody photographed. It
+ *  must answer "nothing", never throw and never a half-parsed id.
+ */
+test("an empty or malformed column yields nothing, and does not throw", () => {
+    expect(yui_asset_ids(null)).toEqual([]);
+    expect(yui_asset_ids(undefined)).toEqual([]);
+    expect(yui_asset_ids("")).toEqual([]);
+    expect(yui_asset_ids([])).toEqual([]);
+    expect(yui_asset_id(null)).toBe(null);
+    expect(yui_asset_id("not-an-fkey")).toBe(null);
+    expect(yui_asset_id({})).toBe(null);
+    expect(yui_asset_ids(["assets^ok^as_foto", "rubbish", null])).toEqual(["ok"]);
+});
+
+/*
+ *  The two shapes the backend answers with, and the ONE code path they
+ *  exist to give the caller.
+ */
+test("a signed url is used as it comes", () => {
+    expect(yui_asset_src({
+        mode: "url",
+        url: "/assets/ab/cd/abcd.jpg?e=1&s=tok",
+    })).toBe("/assets/ab/cd/abcd.jpg?e=1&s=tok");
+});
+
+test("inline bytes become a data url carrying their own type", () => {
+    expect(yui_asset_src({
+        mode: "inline",
+        content_type: "image/jpeg",
+        content64: "AAAA",
+    })).toBe("data:image/jpeg;base64,AAAA");
+});
+
+/*
+ *  Anything else is MISSING, and must come back as null rather than as an
+ *  empty string: <img src=""> reloads the page in some browsers, which is a
+ *  worse failure than the one being reported.
+ */
+test("an unusable answer is null, never an empty src", () => {
+    expect(yui_asset_src(null)).toBe(null);
+    expect(yui_asset_src({})).toBe(null);
+    expect(yui_asset_src({mode: "url"})).toBe(null);
+    expect(yui_asset_src({mode: "inline", content_type: "image/png"})).toBe(null);
+    expect(yui_asset_src({mode: "url", url: ""})).toBe(null);
+});