gulp-mu-css 2.0.0

package/README.md

@@ -0,0 +1,135 @@
+# µCSS (npm-Paket `gulp-mu-css`)
+
+Node-Modul zur Kompilierung von **µCSS**-erweiterten Stylesheets — Sprites, Cursor, Farbfunktionen, eingebettetes JavaScript und PSD-basierte Bilderzeugung, gesteuert über ein Skin-Manifest. µCSS 2 ist die Adobe-unabhängige Node-Neuimplementierung des 2013 als Photoshop-Script eingeführten µCSS.
+
+Der technische Paketname ist `gulp-mu-css` (das µ-Zeichen bereitet in npm-/git-Namen Probleme); **µCSS** ist der Anzeigename.
+
+Das ausführliche deutsche Handbuch liegt diesem Paket als PDF bei: **`docs/microCSS.pdf`** (Markdown-Quelle unter `docs/manual/`).
+
+## Installation
+
+```bash
+npm install gulp-mu-css
+```
+
+Die Bilderzeugung (Sprite-Atlas, PSD-Rendering) nutzt das Schwesterpaket [`gulp-mu-ps`](https://www.npmjs.com/package/gulp-mu-ps), das als Abhängigkeit automatisch mitinstalliert wird.
+
+## Was µCSS macht
+
+- **JavaScript im CSS-Wert** — `µ(ausdruck)` (ASCII-Alias `mu(...)`) wird ausgewertet und durch das Ergebnis ersetzt, z. B. `color: µ($.linkColor);` oder `µ($.zIndex + 10)`.
+- **Direktiven mit AST-Zugriff** — `-µ: Direktive(...)` (ASCII-Alias `-mu:`) führt JavaScript mit Zugriff auf die umgebende Regel und das Dokument aus und wird aus der Ausgabe entfernt.
+- **Sprite-Atlas** — `-µ: Sprite("imgs/logo.png")` registriert Bilder, packt sie in einen Atlas (inkl. `@2x`) und schreibt die Regel auf `background-image`/`image-set`/`background-position`/`width`/`height` um.
+- **Cursor & Preload** — `-µ: Cursor("zoom")` erzeugt `cursor: url(...) x y, fallback` (mit `image-set` bei vorhandener `@2x`-Quelle); Cursor-Bilder können automatisch in eine Preload-Regel gesammelt werden.
+- **Farb-API** — `Lighten`, `Alpha`, `MixColors`, `ParseColor`, `FormatColor` (Modelle `hsl` und `oklch`).
+- **PSD-Bilderzeugung** — Button-/Icon-Serien, App-Icons und Animations-Strips aus geschichteten Entwürfen (über `gulp-mu-ps`), direkt an den CSS-Build gekoppelt.
+- **Skin-Manifest & inkrementeller Build** — ein Manifest pro Skin, mtime-basierter Cache (Atlas und PSD-Schritte werden nur bei Änderungen neu erzeugt).
+
+Die Quell-Stylesheets bleiben dabei **syntaktisch valides CSS** — Editoren, Linter und Diffs funktionieren unverändert. Intern ist µCSS eine PostCSS-Pipeline, das PostCSS-Ökosystem (cssnano, Stylelint, …) bleibt andockbar.
+
+## Quell-Stylesheets (`*.µ.css`)
+
+Quell-Stylesheets verwenden das Doppelsuffix `*.µ.css` (ASCII-Alternative `*.mu.css`), damit Editoren sie automatisch als CSS erkennen. Für den Compiler ist die Endung irrelevant — das Manifest referenziert die Quellen explizit.
+
+```css
+a:link {
+	color: µ($.linkColor);
+	border-bottom: 1px dashed µ(Lighten($.selectBaseBrgdColor, 0.7));
+}
+div.companylogo {
+	-µ: Sprite("imgs/logos/dosing_logo.png");
+}
+*.cursor_zoom {
+	-µ: Cursor("zoom");
+}
+```
+
+Eigene Makro-Helper werden als `function` (keine Arrow-Function) deklariert und mit `this` = Auswertungs-Scope aufgerufen:
+
+```js
+// helpers.mjs — im Manifest unter helpers: { Borders } registrieren
+export function Borders(_baseColor, _pixelWidth, _topLighten, _rightLighten, _bottomLighten, _leftLighten) {
+	this.AddProperty("border-top", `${_pixelWidth}px solid ${Lighten(_baseColor, _topLighten)}`);
+	this.AddProperty("border-right", `${_pixelWidth}px solid ${Lighten(_baseColor, _rightLighten)}`);
+	this.AddProperty("border-bottom", `${_pixelWidth}px solid ${Lighten(_baseColor, _bottomLighten)}`);
+	this.AddProperty("border-left", `${_pixelWidth}px solid ${Lighten(_baseColor, _leftLighten)}`);
+}
+```
+
+```css
+div.menu {
+	-µ: Borders($.menuBaseBrgdColor, 1, 0.3, -0.3, -0.3, 0.3);
+}
+```
+
+## Schnellstart über das Skin-Manifest (empfohlen)
+
+Pro Skin ein Manifest `skins/src/<skinname>.µcss.mjs` (ASCII-Alternative `.mucss.mjs`); der Skin-Name ergibt sich aus dem Teil vor dem Doppelsuffix.
+
+```js
+// skins/src/std.µcss.mjs
+import { DefineSkin } from "gulp-mu-css";
+
+export default DefineSkin({
+	vars: { linkColor: "#aabbcc", selectBaseBrgdColor: "#007570" },
+	cursors: [{ name: "zoom", fallback: "zoom-in", image: "imgs/cursors/zoom.png", hotspot: [10, 8] }],
+	media: [
+		{ buttonsAndIcons: "dev/media/final/panelbuttons.psd", layout: "std", outputDir: "imgs/panelbuttons" },
+		{ copyFolder: "dev/media/final/fonts", to: "fonts" }
+	],
+	sprites: { file: "imgs/sprites.png", retina: true },
+	files: [{ source: "src.µ.css", target: "std.css" }]
+});
+```
+
+```js
+// gulpfile.mjs des Projekts
+import gulp from "gulp";
+import { BuildSkin } from "gulp-mu-css";
+
+export async function SkinStd() {
+	await BuildSkin("skins/src/std.µcss.mjs");   // inkrementell, Cache in skins/std/.cache/
+}
+export function SkinWatch() {
+	gulp.watch(["skins/src/**", "dev/media/final/**"], SkinStd);
+}
+```
+
+`BuildSkin(manifestPfad, { force?, outputDir?, rootDir? })` führt zuerst die `media`-Steps aus (`buttonsAndIcons`, `appIcons`, `sequenceStrip`, `copy`, `copyFolder`), kompiliert dann alle `files`-Einträge, löst den Sprite-Atlas auf und schreibt alles nach `skins/<skinname>/`. Der globale Schalter `imageFormat: "webp"` stellt Atlas und bilderzeugende Steps auf WebP um. Details und alle Optionen stehen im Handbuch (`docs/microCSS.pdf`).
+
+## Programmatische Nutzung
+
+```js
+import { CompileMcss, SpriteManager, CursorManager } from "gulp-mu-css";
+
+const sprites = new SpriteManager({ baseDir: "skins/std", atlasFile: "imgs/sprites.png", retina: true });
+const cursors = new CursorManager([
+	{ name: "zoom", fallback: "zoom-in", image: "imgs/general/gui/cursors/zoom.png", hotspot: [10, 8] }
+], { baseDir: "skins/std" });
+
+const document = CompileMcss(source, {
+	vars: { linkColor: "#aabbcc", selectBaseBrgdColor: "#007570" },
+	sprites,
+	cursors
+});
+await sprites.Resolve(document);   // packt den Atlas und schreibt die Sprite-Regeln um
+await document.ToFile("skins/std/std.css");
+```
+
+Wichtigste Exporte: `CompileMcss`, `CssDocument`/`CssRule` (PostCSS-AST-Wrapper mit `FindRule`, `AddRule`, `AddProperty`/`ChangeProperty`/`RemoveProperty`, `ToCss`/`ToFile`/`ToJson`/`FromJson`), die Farb-API (`Lighten`, `Alpha`, `MixColors`, …), `SpriteManager`, `CursorManager`, `PreloadRegistry`, `DefineSkin`/`BuildSkin`.
+
+## Fehlerdiagnostik
+
+Build-Fehler nennen immer den Verursacher samt Quellbezug:
+
+- **Inline-JavaScript**: Fehler werden als PostCSS-Fehler mit Datei, Zeile, Spalte und Quelltext-Ausschnitt gemeldet; der fehlschlagende Ausdruck wird genannt. JS-Syntaxfehler erscheinen als `invalid JavaScript expression "..."`.
+- **Fehlende Sprite-Bilder**: vor dem Packen geprüft; *alle* fehlenden Dateien werden gesammelt gemeldet — mit URL, aufgelöstem Pfad und referenzierender Regel.
+- **`media`-Steps in `BuildSkin`**: Fehler nennen Step-Nummer und -Typ; fehlende Quellen melden den aufgelösten Pfad statt eines rohen `ENOENT`.
+- **Fehlende Cursor-Bilder**: nur eine Warnung (einmal pro Cursor), da die CSS über den Fallback funktionsfähig bleibt.
+
+## Handbuch
+
+Das vollständige Benutzerhandbuch liegt als **`docs/microCSS.pdf`** bei (Markdown-Quelle: `docs/manual/microCSS-Handbuch.md`). Es behandelt Grundideen, alle Direktiven und Manifest-Optionen, die Bilderzeugung (inkl. `mode: "topLayerSets"` und `outputBase`), den inkrementellen Build sowie die Migration von µCSS 1.
+
+## Lizenz
+
+MIT