gulp-mu-gulp-api 0.3.0 → 0.3.2

package/README.md

@@ -20,6 +20,11 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.2
+
+- **Added** `FormatValue()` — renders `<name format="…"/>` placeholders from `<format …>` XML definitions in the consumer project's `i18x/gulp/<lid>.json`.
+- **Changed** built-in format IDs to CamelCase (`floatFix2`, `stdDate`, `progressDuration`, `byteSize`, …); lifecycle duration logs expect raw milliseconds with `format="progressDuration"`.
+
 ### 0.3.0
 
 - **Added** integrated i18x console layer: `Log`, `Warn`, `LogError`, `Translate`, `GetLid`, `SetLid`, `GetTimeZone`, `DateInTimeZone`, `InstallStringExtensions` — translations live in the consumer project's `i18x/gulp/<lid>.json`; language follows `MICROGULP_LANG` (set by the µGulp dashboard) with locale fallback.
@@ -83,7 +88,7 @@ let values = await RequestForm({
 
 | Function | Purpose |
 | :--- | :--- |
-| `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard (`IsUGulp` is a deprecated alias) |
+| `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard |
 | `InstallStringExtensions()` | Installs µLib-compatible `String.prototype.i18xTrans()`/`i18xRegister()` (auto-run on import) |
 | `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) |
 | `Translate(text, values?)` | Returns the translated string without logging |
@@ -105,8 +110,8 @@ Write the i18xe context tag **into** the source phrase and mark it with `.i18xRe
 
 | Placeholder | Source |
 | :--- | :--- |
-| `version` | `µI18nContext.version` export, else `package.json` |
-| `project` | `µI18nContext.project` export, else `package.json` `name` |
+| `version` | `µI18xContext.version` export, else `package.json` |
+| `project` | `µI18xContext.project` export, else `package.json` `name` |
 | `workspace` | workspace folder name |
 | `source` | gulpfile path relative to the workspace |
 | `gulpfile` | gulpfile file name |
@@ -116,7 +121,7 @@ Write the i18xe context tag **into** the source phrase and mark it with `.i18xRe
 Export defaults from the gulpfile (overrides `package.json`):
 
 ```javascript
-export const µI18nContext = { version: '1.13', project: 'eMP' };
+export const µI18xContext = { version: '1.13', project: 'eMP' };
 
 MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
 // => "Make Build V1.13" in the dashboard (translatable per language)
@@ -178,6 +183,11 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.2
+
+- **Neu** `FormatValue()` — rendert `<name format="…"/>`-Platzhalter aus `<format …>`-XML-Definitionen in `i18x/gulp/<lid>.json` des Verbraucherprojekts.
+- **Geändert** Format-IDs auf CamelCase (`floatFix2`, `stdDate`, `progressDuration`, `byteSize`, …); Lifecycle-Dauer-Logs erwarten Roh-Millisekunden mit `format="progressDuration"`.
+
 ### 0.3.0
 
 - **Neu** integrierte i18x-Konsolenschicht: `Log`, `Warn`, `LogError`, `Translate`, `GetLid`, `SetLid`, `GetTimeZone`, `DateInTimeZone`, `InstallStringExtensions` — Übersetzungen liegen im Verbraucherprojekt unter `i18x/gulp/<lid>.json`; die Sprache folgt `MICROGULP_LANG` (vom µGulp-Dashboard gesetzt) mit Locale-Fallback.
@@ -241,7 +251,7 @@ let values = await RequestForm({
 
 | Funktion | Zweck |
 | :--- | :--- |
-| `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft (`IsUGulp` ist ein veralteter Alias) |
+| `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft |
 | `InstallStringExtensions()` | Installiert µLib-kompatible `String.prototype.i18xTrans()`/`i18xRegister()` (läuft beim Import automatisch) |
 | `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x (`<context="task log"/>` usw.) |
 | `Translate(text, values?)` | Gibt den übersetzten String zurück, ohne zu loggen |
@@ -263,8 +273,8 @@ Den i18xe-Kontext-Tag **in** die Textphrase schreiben und mit `.i18xRegister()`
 
 | Platzhalter | Quelle |
 | :--- | :--- |
-| `version` | `µI18nContext.version`-Export, sonst `package.json` |
-| `project` | `µI18nContext.project`-Export, sonst `package.json` `name` |
+| `version` | `µI18xContext.version`-Export, sonst `package.json` |
+| `project` | `µI18xContext.project`-Export, sonst `package.json` `name` |
 | `workspace` | Workspace-Ordnername |
 | `source` | Gulpfile-Pfad relativ zum Workspace |
 | `gulpfile` | Gulpfile-Dateiname |
@@ -274,7 +284,7 @@ Den i18xe-Kontext-Tag **in** die Textphrase schreiben und mit `.i18xRegister()`
 Defaults im Gulpfile exportieren (`package.json` wird überschrieben):
 
 ```javascript
-export const µI18nContext = { version: '1.13', project: 'eMP' };
+export const µI18xContext = { version: '1.13', project: 'eMP' };
 
 MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
 // => „Make Build V1.13“ im Dashboard (pro Sprache übersetzbar)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"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/i18x.mjs

@@ -50,6 +50,7 @@ const LIDS_MAIN_CULTURES = {
 };
 
 let dictionaryCache = new Map();
+let formatDefinitionCache = new Map();
 let availableLids = null;
 let activeLid = null;
 const timeZoneFormatters = {};
@@ -175,6 +176,7 @@ export function GetLid() {
  */
 export function SetLid(_lid) {
 	activeLid = _lid ? _BestAvailableLid(_lid, _AvailableLids()) : null;
+	formatDefinitionCache.clear();
 }
 
 /** Loads and caches `<dir>/<lid>.json`; a missing/broken file yields source text. */
@@ -191,29 +193,104 @@ function _LoadDictionary(_lid) {
 	return dictionary;
 }
 
-/** Substitutes `<name/>` placeholders; honors `format="…"` for int and clock times. */
+/** @param {Record<string, string>} _dictionary */
+function _ExtractFormatDefinitions(_dictionary) {
+	let formats = {};
+	for (let [key, value] of Object.entries(_dictionary)) {
+		if (!key.startsWith('<format name=')) continue;
+		let match = key.match(/<format name="([^"]+)"/);
+		if (match) formats[match[1]] = value;
+	}
+	return formats;
+}
+
+/** Localized i18xe format XML keyed by format id (from i18x/gulp dictionaries). */
+function _LoadFormatDefinitions(_lid) {
+	if (formatDefinitionCache.has(_lid)) return formatDefinitionCache.get(_lid);
+	let formats = { ..._ExtractFormatDefinitions(_LoadDictionary(DEFAULT_LID)) };
+	if (_lid !== DEFAULT_LID) {
+		Object.assign(formats, _ExtractFormatDefinitions(_LoadDictionary(_lid)));
+	}
+	formatDefinitionCache.set(_lid, formats);
+	return formats;
+}
+
+/** Formats milliseconds as M:SS or H:MM:SS (progress bar durations). */
+function _FormatDuration(_ms) {
+	let ms = Math.max(0, Number(_ms) || 0);
+	let totalSeconds = Math.round(ms / 1000);
+	let seconds = totalSeconds % 60;
+	let minutes = Math.floor(totalSeconds / 60) % 60;
+	let hours = Math.floor(totalSeconds / 3600);
+	let pad = (_n) => String(_n).padStart(2, '0');
+	return hours > 0 ? hours + ':' + pad(minutes) + ':' + pad(seconds) : minutes + ':' + pad(seconds);
+}
+
+/**
+ * Formats a numeric value with a named i18xe format definition from the
+ * project's i18x/gulp dictionaries (synced from i18xe prod).
+ * @param {number|string} _value
+ * @param {string} _formatName e.g. 'int', 'floatFix2', 'byteSize'
+ * @param {string} [_lid]
+ * @returns {string}
+ */
+export function FormatValue(_value, _formatName, _lid) {
+	let lid = _lid ?? GetLid();
+	let tz = GetTimeZone();
+	if (_formatName === 'progressDuration') return _FormatDuration(Number(_value));
+	if (_formatName === 'stdTime') {
+		let date = new Date(Number(_value) || 0);
+		try {
+			return new Intl.DateTimeFormat(lid, { hour: '2-digit', minute: '2-digit', timeZone: tz }).format(date);
+		} catch {
+			return date.toISOString();
+		}
+	}
+	if (_formatName === 'stdDateTime' || _formatName === 'fullDateTime') {
+		let date = new Date(Number(_value) || 0);
+		try {
+			return new Intl.DateTimeFormat(lid, {
+				year: 'numeric', month: '2-digit', day: '2-digit',
+				hour: '2-digit', minute: '2-digit', timeZone: tz,
+			}).format(date);
+		} catch {
+			return date.toISOString();
+		}
+	}
+	if (_formatName === 'byteSize') {
+		let bytes = Number(_value);
+		if (!Number.isFinite(bytes)) return String(_value);
+		if (bytes >= 1073741824) return FormatValue(bytes / 1073741824, 'floatFix2', lid) + ' GB';
+		if (bytes >= 1048576) return FormatValue(bytes / 1048576, 'floatFix2', lid) + ' MB';
+		if (bytes >= 1024) return FormatValue(bytes / 1024, 'floatFix2', lid) + ' KB';
+		return FormatValue(bytes, 'int', lid) + ' Bytes';
+	}
+	let number = Number(_value);
+	if (!Number.isFinite(number)) return String(_value);
+	let definition = _LoadFormatDefinitions(lid)[_formatName];
+	if (!definition) return String(_value);
+	let groupSeparator = definition.match(/<xa if="1000\|1000\+">([^<]*)<\/xa>/)?.[1] ?? ',';
+	let decimalSeparator = definition.match(/if="0~">([^<]*)<m0\/>/)?.[1]
+		?? definition.match(/<\/xa>([^<]*)<f0\/>/)?.[1] ?? '.';
+	let fractionDigits = _formatName === 'floatFix1' ? 1
+		: (_formatName.startsWith('floatFix') ? 2 : 0);
+	if (_formatName === 'int') number = Math.round(number);
+	let negative = number < 0;
+	let absolute = Math.abs(number);
+	let integerPart = String(Math.trunc(fractionDigits ? absolute : Math.round(absolute)));
+	let grouped = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, groupSeparator);
+	let fraction = fractionDigits ? decimalSeparator + absolute.toFixed(fractionDigits).split('.')[1] : '';
+	return (negative ? '-' : '') + grouped + fraction;
+}
+
+/** Substitutes `<name/>` placeholders; honors `format="…"` via FormatValue. */
 function _ApplyPlaceholders(_text, _values) {
 	let text = String(_text);
+	let lid = GetLid();
 	for (let key of Object.keys(_values ?? {})) {
 		let pattern = new RegExp('<' + key + '(?:\\s+format="([^"]*)")?\\s*/>', 'g');
-		text = text.replace(pattern, (_match, _formatName) => {
-			if (_formatName === 'int') return String(Math.round(Number(_values[key]) || 0));
-			if (_formatName === 'stdtime' || _formatName === 'stddatetime') {
-				let date = new Date(Number(_values[key]) || 0);
-				let lid = GetLid();
-				try {
-					return new Intl.DateTimeFormat(lid, {
-						...( _formatName === 'stddatetime'
-							? { year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }
-							: { hour: '2-digit', minute: '2-digit' }),
-						timeZone: GetTimeZone(),
-					}).format(date);
-				} catch {
-					return date.toISOString();
-				}
-			}
-			return String(_values[key]);
-		});
+		text = text.replace(pattern, (_match, _formatName) =>
+			_formatName ? FormatValue(_values[key], _formatName, lid) : String(_values[key]));
 	}
 	return text.replace(/<[^>]*>/g, '');
 }
@@ -302,5 +379,5 @@ InstallStringExtensions();
 
 export default {
 	GetLid, SetLid, GetTimeZone, DateInTimeZone,
-	Translate, Log, Warn, LogError, InstallStringExtensions,
+	Translate, FormatValue, Log, Warn, LogError, InstallStringExtensions,
 };

package/src/index.mjs

@@ -30,7 +30,7 @@
 
 // Localized console output (i18x). Re-exported so tasks import everything
 // from one place: `import { Log, Warn, ReportProgress } from 'gulp-mu-gulp-api'`.
-export { Log, Warn, LogError, Translate, GetLid, SetLid, GetTimeZone, DateInTimeZone, InstallStringExtensions } from './i18x.mjs';
+export { Log, Warn, LogError, Translate, FormatValue, GetLid, SetLid, GetTimeZone, DateInTimeZone, InstallStringExtensions } from './i18x.mjs';
 import * as I18x from './i18x.mjs';
 
 let uiRequestCounter = 0;
@@ -43,15 +43,12 @@ const pendingUiRequests = new Map();
  * attached dashboard (progress and inputs are rendered in the webview)
  */
 export function IsMicroGulp() {
-	return typeof process.send === 'function' && process.env.UGULP === '1';
+	return typeof process.send === 'function' && process.env.MICROGULP === '1';
 }
 
 /** Brand-aligned alias for {@link IsMicroGulp}. */
 export const IsµGulp = IsMicroGulp;
 
-/** @deprecated Use {@link IsMicroGulp} or {@link IsµGulp}. */
-export const IsUGulp = IsMicroGulp;
-
 /*
  * Task metadata (µDisplayName, µDescription, µTooltip, µGroup) is localized
  * the same way as any other i18x phrase: with the context tag written *into*
@@ -147,6 +144,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,10 +488,35 @@ 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,
-	IsUGulp,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,
@@ -450,4 +538,7 @@ export default {
 	InstallStringExtensions: I18x.InstallStringExtensions,
 	LogTable,
 	LogTree,
+	LogGallery,
+	LogAssetPreviews,
+	LogBuildDebugReport,
 };