gulp-mu-gulp-api 0.2.0 → 0.2.1

package/README.md

@@ -23,7 +23,7 @@ npm install gulp-mu-gulp-api
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsUGulp } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, µMeta } from 'gulp-mu-gulp-api';
 
 export async function BUILD_THEME() {
     // single inputs
@@ -50,6 +50,8 @@ export async function BUILD_THEME() {
     PlaySignal('success');
     Speak('Theme build finished.');
 }
+BUILD_THEME.µDisplayName = µMeta('Build Theme', 'µDisplayName');
+BUILD_THEME.µDescription = µMeta('Compiles the Carbon/Neon dashboard skin.', 'µDescription');
 ```
 
 Complete forms in one go:
@@ -72,7 +74,8 @@ let values = await RequestForm({
 
 | Function | Purpose |
 | :--- | :--- |
-| `IsUGulp()` | `true` when the task runs under µGulp™ with an attached dashboard |
+| `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard (`IsUGulp` is a deprecated alias) |
+| `µMeta(text, property)` | Marks a µXXX task metadata string with an i18xe context tag (`µDisplayName`, `µDescription`, `µTooltip`, `µGroup`) |
 | `ReportProgress(value, label?)` | Report progress `0..1` to the task progress bar |
 | `CreateProgress(label?)` | Reporter object with `Update(value, stepLabel?)` and `Done()` |
 | `PlaySignal(signal?)` | Acoustic signal in the dashboard: `'success'` \| `'error'` \| `'attention'` (default) |
@@ -143,7 +146,7 @@ npm install gulp-mu-gulp-api
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsUGulp } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, µMeta } from 'gulp-mu-gulp-api';
 
 export async function BUILD_THEME() {
     // Einzeleingaben
@@ -170,6 +173,8 @@ export async function BUILD_THEME() {
     PlaySignal('success');
     Speak('Theme build finished.');
 }
+BUILD_THEME.µDisplayName = µMeta('Build Theme', 'µDisplayName');
+BUILD_THEME.µDescription = µMeta('Kompiliert den Carbon/Neon-Dashboard-Skin.', 'µDescription');
 ```
 
 Komplette Formulare in einem Rutsch:
@@ -192,7 +197,8 @@ let values = await RequestForm({
 
 | Funktion | Zweck |
 | :--- | :--- |
-| `IsUGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft |
+| `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft (`IsUGulp` ist ein veralteter Alias) |
+| `µMeta(text, property)` | Kennzeichnet einen µXXX-Metadaten-String mit einem i18xe-Kontext-Tag (`µDisplayName`, `µDescription`, `µTooltip`, `µGroup`) |
 | `ReportProgress(value, label?)` | Fortschritt `0..1` an die Task-Progressbar melden |
 | `CreateProgress(label?)` | Reporter-Objekt mit `Update(value, stepLabel?)` und `Done()` |
 | `PlaySignal(signal?)` | Akustisches Signal im Dashboard: `'success'` \| `'error'` \| `'attention'` (Default) |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output 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

@@ -37,10 +37,36 @@ const pendingUiRequests = new Map();
  * @returns {boolean} true when the task runs inside a µGulp worker with an
  * attached dashboard (progress and inputs are rendered in the webview)
  */
-export function IsUGulp() {
+export function IsMicroGulp() {
 	return typeof process.send === 'function' && process.env.UGULP === '1';
 }
 
+/** Brand-aligned alias for {@link IsMicroGulp}. */
+export const IsµGulp = IsMicroGulp;
+
+/** @deprecated Use {@link IsMicroGulp} or {@link IsµGulp}. */
+export const IsUGulp = IsMicroGulp;
+
+/**
+ * Marks a µXXX task metadata string for i18x (American English source).
+ * Appends the i18xe context tag for the property (`µDisplayName`,
+ * `µDescription`, …) so the dashboard can translate it and a later
+ * i18xe-server sync can pick it up. The classic gulp CLI ignores these
+ * properties entirely.
+ *
+ * @param {string} _text source phrase
+ * @param {'µDisplayName'|'µDescription'|'µTooltip'|'µGroup'} _contextProperty
+ * @returns {string}
+ */
+export function µMeta(_text, _contextProperty) {
+	let text = String(_text ?? '').trim();
+	if (!text || text.includes('<context="')) return text;
+	return text + '<context="' + _contextProperty + '"/>';
+}
+
+/** ASCII export alias for {@link µMeta}. */
+export const MicroGulpMeta = µMeta;
+
 // -------------------------------------------------
 // progress
 // -------------------------------------------------
@@ -55,7 +81,7 @@ export function IsUGulp() {
  */
 export function ReportProgress(_value, _label) {
 	let value = Math.max(0, Math.min(1, Number(_value) || 0));
-	if (IsUGulp()) {
+	if (IsMicroGulp()) {
 		process.send({ type: 'progress', value, label: _label });
 		return;
 	}
@@ -97,7 +123,7 @@ export function CreateProgress(_label) {
  * @param {'success'|'error'|'attention'} [_signal]
  */
 export function PlaySignal(_signal = 'attention') {
-	if (IsUGulp()) {
+	if (IsMicroGulp()) {
 		process.send({ type: 'sound', signal: _signal });
 		return;
 	}
@@ -117,7 +143,7 @@ export function PlaySignal(_signal = 'attention') {
 export function Speak(_text, _options) {
 	let text = String(_text ?? '').trim();
 	if (!text) return;
-	if (IsUGulp()) {
+	if (IsMicroGulp()) {
 		process.send({ type: 'speech', text, options: _options ?? null });
 		return;
 	}
@@ -149,7 +175,7 @@ export function Speak(_text, _options) {
  * @returns {Promise<object>} map fieldId -> value
  */
 export async function RequestForm(_form) {
-	if (IsUGulp()) {
+	if (IsMicroGulp()) {
 		_EnsureIpcListener();
 		let requestId = 'api-req-' + process.pid + '-' + (++uiRequestCounter);
 		return new Promise((_resolve) => {
@@ -308,7 +334,11 @@ async function _FallbackField(_field) {
 }
 
 export default {
+	IsMicroGulp,
+	IsµGulp,
 	IsUGulp,
+	µMeta,
+	MicroGulpMeta,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,