gulp-mu-gulp-api 0.3.1 → 0.3.3

package/README.md

@@ -1,8 +1,20 @@
 # gulp-mu-gulp-api
 
-Public task API of the **µGulp™** orchestrator — progress reporting and interactive dashboard inputs from within gulp tasks.
+<p align="center">
+  <a href="https://github.com/mamekudz/microGulp">
+    <img src="https://raw.githubusercontent.com/mamekudz/microGulp/main/media/logo_readme.png" alt="µGulp logo" width="180">
+  </a>
+</p>
 
-Part of the [µGulp™ project on GitHub](https://github.com/mamekudz/microGulp) (subdirectory [`gulp-mu-gulp-api/`](https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api)).
+<p align="center">
+  <a href="https://github.com/mamekudz/microGulp">
+    <img src="https://raw.githubusercontent.com/mamekudz/microGulp/main/media/microgulp-ready.png" alt="µGulp ready" width="150">
+  </a>
+</p>
+
+Public task API of the **µGulp™** orchestrator — progress reporting, i18x console output and interactive dashboard inputs from within gulp tasks.
+
+[![npm version](https://img.shields.io/npm/v/gulp-mu-gulp-api.svg)](https://www.npmjs.com/package/gulp-mu-gulp-api) · [µGulp™ on GitHub](https://github.com/mamekudz/microGulp) · [source tree](https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api)
 
 [English](#english) · [Deutsch](#deutsch)
 
@@ -20,6 +32,15 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.3
+
+- **Changed** npm README: centered µGulp logo and µGulp ready badge (absolute raw URLs from the µGulp repo).
+
+### 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 +104,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 +126,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 +137,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)
@@ -166,9 +187,9 @@ MIT — © 2026 Meinolf Amekudzi
 
 # Deutsch
 
-**gulp-mu-gulp-api** ist die öffentliche Task-API des **µGulp™**-Orchestrators. Gulp-Tasks (und beliebige npm-Pakete innerhalb des Task-Streams) erhalten damit Zugriff auf die erweiterten µGulp™-Dashboard-Funktionen: Fortschrittsanzeige, Texteingaben mit Validierung, Farb- und Schriftart-Auswahl, Einzel- und Mehrfachauswahl, Slider und komplette Formulare.
+**gulp-mu-gulp-api** ist die öffentliche Task-API des **µGulp™**-Orchestrators. Gulp-Tasks (und beliebige npm-Pakete innerhalb des Task-Streams) erhalten damit Zugriff auf die erweiterten µGulp™-Dashboard-Funktionen: Fortschrittsanzeige, i18x-Konsolenausgabe, Texteingaben mit Validierung, Farb- und Schriftart-Auswahl, Einzel- und Mehrfachauswahl, Slider und komplette Formulare.
 
-Teil des [µGulp™-Projekts auf GitHub](https://github.com/mamekudz/microGulp) (Unterverzeichnis [`gulp-mu-gulp-api/`](https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api)).
+[![npm version](https://img.shields.io/npm/v/gulp-mu-gulp-api.svg)](https://www.npmjs.com/package/gulp-mu-gulp-api) · [µGulp™ auf GitHub](https://github.com/mamekudz/microGulp)
 
 Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna: Läuft der Task unter µGulp™, spricht es direkt über den IPC-Kanal des Worker-Prozesses mit der Engine. Läuft das Gulpfile klassisch über die gulp-CLI, degradieren alle Funktionen sauber — Fortschritt landet auf dem Terminal, Eingaben werden per readline abgefragt (TTY) oder mit den deklarierten Default-Werten beantwortet (CI/non-TTY). Tasks bleiben ohne µGulp™ voll lauffähig.
 
@@ -178,6 +199,15 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.3
+
+- **Geändert** npm-README: zentriertes µGulp-Logo und µGulp-ready-Badge (absolute raw-URLs aus dem µGulp-Repo).
+
+### 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 +271,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 +293,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 +304,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.1",
+	"version": "0.3.3",
 	"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",
@@ -43,6 +43,11 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"microgulp": {
+		"ready": true,
+		"certifiedSince": "0.3.2",
+		"role": "official-task-api"
+	},
 	"engines": {
 		"node": ">=18"
 	}

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*
@@ -520,7 +517,6 @@ function _AsciiGallery(_payload) {
 export default {
 	IsMicroGulp,
 	IsµGulp,
-	IsUGulp,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,