gulp-mu-gulp-api 0.3.11 → 0.3.12

package/README.md

@@ -37,6 +37,13 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.12
+
+- **Added** `RegisterDashboardFont({ id, file, family?, usage? })` — registers a workspace font for µGulp dashboard **task icons** and/or **run-log** typography. `usage`: `'task-icons'` (default), `'log'`, or `'all'`. Call at gulpfile load time; the scan worker forwards the registry to the engine.
+- **Added** `GetRegisteredDashboardFonts()` / `ClearRegisteredDashboardFonts()` — snapshot / test helpers.
+- Pair with gulpfile metadata `µIcon` (glyph) and optional `µIconFont = '<id>'`, or declarative `export const µDashboardFonts = […]`. Config/setting `dashboardFonts` is an alternative when not using the API.
+- Outside µGulp the helpers are no-ops (fonts are a dashboard/host concern).
+
 ### 0.3.11
 
 - **Added** `ShowModalMessage({ variant?, title?, message?, buttons?, presentation? })` — blocking modal (info/warning/error) in the µGulp dashboard glass panel, or native VS Code/Cursor dialogs when `presentation` is `ide`/`auto` (host setting `microgulp.modalPresentation`).
@@ -89,7 +96,7 @@ npm install gulp-mu-gulp-api
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, RegisterDashboardFont, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -161,6 +168,9 @@ let values = await RequestForm({
 | `PlaySignal(signal?)` | Preset acoustic signal: `'success'` \| `'error'` \| `'attention'` (default) |
 | `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas; `options.loop` repeats until `StopSound` |
 | `StopSound(sample)` | Stops a looping sample started with `PlaySound(sample, { loop: true })` |
+| `RegisterDashboardFont(spec)` | Registers a workspace font for dashboard task icons / run-log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
+| `GetRegisteredDashboardFonts()` | Snapshot of fonts registered in this process (scan worker / tests) |
+| `ClearRegisteredDashboardFonts()` | Clears the in-process registry (tests) |
 | `Speak(text, options?)` | Speech output in the dashboard; `options`: `{ rate?, pitch?, volume? }` per-call overrides |
 | `RequestForm(form)` | Request a complete form; resolves with `{ fieldId: value, … }` |
 | `ShowModalMessage(spec)` | Blocking modal (`info`/`warning`/`error`); `presentation`: `webview` \| `ide` \| `auto` |
@@ -194,6 +204,25 @@ MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i
 // => "Make Build V1.13" in the dashboard (translatable per language)
 ```
 
+### Dashboard fonts (task icons & run log)
+
+Project fonts are independent of the dashboard skin. Register them at gulpfile load time:
+
+```javascript
+import { RegisterDashboardFont } from 'gulp-mu-gulp-api';
+
+RegisterDashboardFont({
+    id: 'ProjectIcons',
+    file: 'assets/task-icons.woff2', // relative to the gulpfile directory
+    usage: 'task-icons',             // or 'log' / 'all'
+});
+
+BUILD.µIcon = '\uE101';
+BUILD.µIconFont = 'ProjectIcons';   // optional when only one task-icons font is registered
+```
+
+Alternatively export `µDashboardFonts` from the gulpfile, or set `dashboardFonts` in `microgulp.config.json` / the `microgulp.dashboardFonts` extension setting. Files must stay under the workspace (`woff2` / `woff` / `ttf` / `otf`). The first `task-icons` font becomes the default for glyph `µIcon` entries; `usage: 'log'` restyles the run-sector log.
+
 ### Field types (for `RequestForm`)
 
 A field descriptor is `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.
@@ -281,6 +310,13 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.12
+
+- **Neu** `RegisterDashboardFont({ id, file, family?, usage? })` — registriert einen Workspace-Font für **Task-Icons** und/oder die **Run-Log**-Typografie im µGulp-Dashboard. `usage`: `'task-icons'` (Default), `'log'` oder `'all'`. Aufruf beim Laden des Gulpfiles; der Scan-Worker reicht die Registry an die Engine weiter.
+- **Neu** `GetRegisteredDashboardFonts()` / `ClearRegisteredDashboardFonts()` — Snapshot- bzw. Test-Helfer.
+- Zusammen mit Metadaten `µIcon` (Glyph) und optional `µIconFont = '<id>'`, oder deklarativ `export const µDashboardFonts = […]`. Alternative: `dashboardFonts` in Config/Setting.
+- Außerhalb von µGulp sind die Helfer No-ops (Fonts sind Sache von Dashboard/Host).
+
 ### 0.3.11
 
 - **Neu** `ShowModalMessage({ variant?, title?, message?, buttons?, presentation? })` — blockierendes Modal (info/warning/error) als Dashboard-Glaspanel oder natives VS-Code-/Cursor-Dialogfenster bei `presentation` `ide`/`auto` (Host-Setting `microgulp.modalPresentation`).
@@ -333,7 +369,7 @@ npm install gulp-mu-gulp-api
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, RegisterDashboardFont, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -405,6 +441,9 @@ let values = await RequestForm({
 | `PlaySignal(signal?)` | Vorgabe-Signal: `'success'` \| `'error'` \| `'attention'` (Default) |
 | `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas; `options.loop` wiederholt bis `StopSound` |
 | `StopSound(sample)` | Stoppt eine Schleife von `PlaySound(sample, { loop: true })` |
+| `RegisterDashboardFont(spec)` | Registriert einen Workspace-Font für Dashboard-Task-Icons / Run-Log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
+| `GetRegisteredDashboardFonts()` | Snapshot der in diesem Prozess registrierten Fonts (Scan-Worker / Tests) |
+| `ClearRegisteredDashboardFonts()` | Leert die In-Process-Registry (Tests) |
 | `Speak(text, options?)` | Sprachausgabe im Dashboard; `options`: `{ rate?, pitch?, volume? }` je Aufruf |
 | `RequestForm(form)` | Komplettes Formular anfordern; löst mit `{ fieldId: value, … }` auf |
 | `ShowModalMessage(spec)` | Blockierendes Modal (`info`/`warning`/`error`); `presentation`: `webview` \| `ide` \| `auto` |
@@ -438,6 +477,25 @@ MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i
 // => „Make Build V1.13“ im Dashboard (pro Sprache übersetzbar)
 ```
 
+### Dashboard-Fonts (Task-Icons & Run-Log)
+
+Projekt-Fonts sind unabhängig vom Dashboard-Skin. Beim Laden des Gulpfiles registrieren:
+
+```javascript
+import { RegisterDashboardFont } from 'gulp-mu-gulp-api';
+
+RegisterDashboardFont({
+    id: 'ProjectIcons',
+    file: 'assets/task-icons.woff2', // relativ zum Gulpfile-Ordner
+    usage: 'task-icons',             // oder 'log' / 'all'
+});
+
+BUILD.µIcon = '\uE101';
+BUILD.µIconFont = 'ProjectIcons';   // optional, wenn nur ein task-icons-Font registriert ist
+```
+
+Alternativ `µDashboardFonts` aus dem Gulpfile exportieren oder `dashboardFonts` in `microgulp.config.json` / Setting `microgulp.dashboardFonts`. Dateien müssen unter dem Workspace liegen (`woff2` / `woff` / `ttf` / `otf`). Der erste `task-icons`-Font ist Default für Glyph-`µIcon`; `usage: 'log'` setzt die Run-Log-Schrift.
+
 ### Feldtypen (für `RequestForm`)
 
 Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.11",
+	"version": "0.3.12",
 	"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

@@ -800,10 +800,62 @@ export function NotifyTasksChanged() {
 	}
 }
 
+// -------------------------------------------------
+// dashboard fonts (task icons / run log)
+// -------------------------------------------------
+
+/** @type {Map<string, { id: string, file: string, family?: string, usage?: string|string[] }>} */
+const registeredDashboardFonts = new Map();
+
+/**
+ * Registers a project font for the µGulp dashboard. Call at gulpfile load
+ * time (top-level). The scan worker forwards the registry to the engine;
+ * the host serves the file into the webview / HTTP dashboard.
+ *
+ * @param {object} _spec
+ * @param {string} _spec.id stable id (also default CSS `font-family`)
+ * @param {string} _spec.file path relative to the gulpfile directory (or absolute under the workspace)
+ * @param {string} [_spec.family] CSS font-family name (default: id)
+ * @param {string|string[]} [_spec.usage] `'task-icons'`, `'log'`, or `'all'` (default: task-icons)
+ *
+ * @example
+ * RegisterDashboardFont({ id: 'ProjectIcons', file: 'assets/icons.woff2', usage: 'task-icons' });
+ * BUILD.µIcon = '\uE001';
+ * BUILD.µIconFont = 'ProjectIcons'; // optional when only one task-icons font is registered
+ */
+export function RegisterDashboardFont(_spec) {
+	if (_spec == null || typeof _spec !== 'object') return;
+	let id = String(_spec.id ?? '').trim();
+	if (!id) return;
+	let file = String(_spec.file ?? _spec.path ?? '').trim();
+	if (!file) return;
+	let entry = { id, file };
+	if (_spec.family != null) entry.family = String(_spec.family);
+	if (_spec.usage != null) entry.usage = _spec.usage;
+	registeredDashboardFonts.set(id, entry);
+}
+
+/**
+ * Snapshot of fonts registered via {@link RegisterDashboardFont} in this
+ * process (used by the µGulp scan worker). Safe to call outside µGulp.
+ * @returns {object[]}
+ */
+export function GetRegisteredDashboardFonts() {
+	return [...registeredDashboardFonts.values()].map((_entry) => ({ ..._entry }));
+}
+
+/** Clears the in-process registry (tests). */
+export function ClearRegisteredDashboardFonts() {
+	registeredDashboardFonts.clear();
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
 	NotifyTasksChanged,
+	RegisterDashboardFont,
+	GetRegisteredDashboardFonts,
+	ClearRegisteredDashboardFonts,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,