gulp-mu-gulp-api 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output, localized console output (i18x) and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
 	"type": "module",
 	"main": "src/index.mjs",

package/src/index.mjs

@@ -147,6 +147,72 @@ export function LogTree(_spec) {
 	for (let line of _AsciiTreeLines(payload)) console.log(line);
 }
 
+/**
+ * Sends an image gallery to the dashboard log pane. Each item needs a `src`
+ * (data URI or https URL) and a `label`; optional `caption` and per-item `title`.
+ * CLI fallback: lists labels and src lengths on stdout.
+ *
+ * @param {object} _spec `{ title?, columns?, items: { label, src, caption?, title? }[] }`
+ */
+export function LogGallery(_spec) {
+	let payload = _NormalizeGallerySpec(_spec);
+	if (IsMicroGulp()) {
+		process.send({ type: 'structured-log', format: 'gallery', payload });
+		return;
+	}
+	console.log(_AsciiGallery(payload));
+}
+
+/**
+ * Renders µCSS BuildSkin `report.debug.previews` as a thumbnail gallery.
+ * Items without `thumbDataUri` are omitted (paths-only assets stay in the text log).
+ *
+ * @param {object[]} _previews preview entries from `report.debug.previews`
+ * @param {object} [_options] `{ title?, columns? }`
+ */
+export function LogAssetPreviews(_previews, _options = {}) {
+	let items = (_previews ?? [])
+		.filter((_entry) => _entry?.thumbDataUri)
+		.map((_entry) => ({
+			label: String(_entry.relPath ?? _entry.path ?? ''),
+			src: _entry.thumbDataUri,
+			caption: [
+				_entry.step,
+				_entry.skipped ? 'cached' : null,
+				_entry.width && _entry.height ? `${_entry.width}\u00d7${_entry.height}` : null,
+			].filter(Boolean).join(' \u00b7 '),
+		}));
+	if (!items.length) return;
+	LogGallery({
+		title: _options.title,
+		columns: _options.columns ?? 4,
+		items,
+	});
+}
+
+/**
+ * Convenience wrapper for a full µCSS `BuildSkin` debug block: summary table
+ * plus thumbnail gallery when `report.debug` is present.
+ *
+ * @param {object} _report BuildSkin return value
+ * @param {object} [_options] `{ title?, columns?, table?: boolean }`
+ */
+export function LogBuildDebugReport(_report, _options = {}) {
+	let debug = _report?.debug;
+	if (!debug) return;
+	if (_options.table !== false && debug.summary) {
+		LogTable({
+			columns: [{ id: 'metric', label: 'Metric' }, { id: 'value', label: 'Value' }],
+			rows: Object.entries(debug.summary).map(([metric, value]) => ({ metric, value: String(value) })),
+			hyphenate: false,
+		});
+	}
+	LogAssetPreviews(debug.previews, {
+		title: _options.title ?? 'Generated assets',
+		columns: _options.columns,
+	});
+}
+
 // -------------------------------------------------
 // sound & speech
 // -------------------------------------------------
@@ -425,6 +491,32 @@ function _AsciiTreeLines(_payload, _indent = '', _roots = null) {
 	return lines;
 }
 
+function _NormalizeGallerySpec(_spec) {
+	let columns = Math.max(1, Math.min(8, Number(_spec?.columns) || 4));
+	let items = (_spec?.items ?? []).map((_item) => ({
+		label: String(_item?.label ?? ''),
+		src: String(_item?.src ?? ''),
+		caption: _item?.caption != null ? String(_item.caption) : '',
+		title: _item?.title != null ? String(_item.title) : '',
+	})).filter((_item) => _item.src);
+	return {
+		title: _spec?.title != null ? String(_spec.title) : '',
+		columns,
+		items,
+	};
+}
+
+function _AsciiGallery(_payload) {
+	let lines = [];
+	if (_payload.title) lines.push(_payload.title);
+	for (let item of _payload.items) {
+		let meta = item.caption ? ` (${item.caption})` : '';
+		let srcHint = item.src.startsWith('data:') ? `[data URI, ${item.src.length} chars]` : item.src;
+		lines.push(`  ${item.label}${meta}: ${srcHint}`);
+	}
+	return lines.join('\n');
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
@@ -450,4 +542,7 @@ export default {
 	InstallStringExtensions: I18x.InstallStringExtensions,
 	LogTable,
 	LogTree,
+	LogGallery,
+	LogAssetPreviews,
+	LogBuildDebugReport,
 };