FluentUI: Dienste für die WvdS-DW-Registry

Zurück: FluentUI (Design-System-Bibliothek) · Verwandt: FluentUI: Öffentliche Helper-API · FluentUI: Design-Tokens

1. Zweck

Status: Tier 1 — beschreibt umgesetzten Code.

Die Plugins der WvdS-DW- und DWDO-Familie (wksourceview, wkdogit, wkdoado, wkdoadogit, wkdocore) zeichnen ihre Oberfläche nicht selbst, sondern holen sich drei Dienste aus der Service-Registry von wkcore:

ui.components — fünf Grundbausteine: button, badge, card, alert, icon; dazu als Zugabe dieses Wikis der geteilte Dokumentenkopf header (Abschnitt 4)
ui.icons — Auflösung eines Icon-Alias zu fertigem Markup
ui.tokens — die Farbwerte als PHP-Array, für serverseitige Verbraucher

Vorgesehen ist dafür das Plugin wvdsdwui. Es ist hier bewusst nicht installiert: dieses Wiki besitzt mit wkfluentui bereits ein Design-System, und zwei Token-Sätze plus zwei Icon-Anbieter im selben Wiki hießen, dass die Ladereihenfolge über die Farbe entscheidet und nicht die Absicht. Stattdessen meldet wkfluentui die drei Dienste selbst an.

2. Wie die Anmeldung funktioniert

action/dwdobridge.php hängt sich an das Ereignis WKCORE_REGISTER_SERVICES und trägt die drei Dienste in die Registry ein. Die Kopplung ist in beide Richtungen freiwillig:

Ist wkcore nicht installiert, feuert das Ereignis nie — dieses Plugin verhält sich exakt wie zuvor.
Findet ein DWDO-Plugin keinen Dienst, fällt es laut eigenem Vertrag auf schlichtes Markup zurück.

Die Anmeldung überschreibt nichts: wäre wvdsdwui doch installiert, gewinnt, wer zuerst registriert — statt dass eines das andere still verdrängt.

Die Helfer implementieren kein Interface. Der Vertrag (wvdsdwui\ComponentContract, wvdsdwui\IconProvider) gehört zu genau dem Plugin, das hier ersetzt wird, existiert also nicht. Die Konsumenten rufen die Dienste ohnehin dynamisch auf und typisieren nie gegen das Interface — Signaturgleichheit ist damit der gesamte Vertrag. Eine geänderte Signatur bricht Aufrufer lautlos.

3. ''ui.components''

Umsetzung: helper/uicomponents.php.

Methode	Signatur	Ergebnis
`button()`	`(string $label, array $opts = [])`	`<button type=„button“>` bzw. `<a>` bei gesetztem `href`. `opts`: `variant`, `icon` (ein Alias, kein Markup), `href`
`badge()`	`(string $text, string $variant = '')`	`<span class=„wk-badge …“>`; gestaltete Varianten: `success`, `warn`, `error`, `info`
`card()`	`(string $title, string $bodyHtml)`	delegiert an `widgets()→card()`
`alert()`	`(string $message, string $level = 'info')`	Meldungsblock mit `role=„status“` und Statussymbol; unbekannte Stufe wird zu `info`
`icon()`	`(string $alias, array $attr = [])`	delegiert an `ui.icons`; unbekannter Alias ergibt ''''
`header()`	`(array $spec)`	kein Teil des Fünfer-Vertrags — der geteilte Dokumentenkopf, siehe Abschnitt 4

Escaping: jeder Skalarwert wird hier escaped. Einzige Ausnahme ist card()s $bodyHtml — ein fertiges Fragment, dessen Escaping laut Vertrag der Aufrufer verantwortet.

Abweichung vom Original: button() prüft den href auf ausführbare Schemata (javascript:, vbscript:, data:) und ersetzt sie durch '#'. hsc() allein macht javascript:alert(1) nur attributsicher, verhindert aber nicht die Ausführung beim Klick. Relative und absolute Pfade, Query, Fragment, http(s): und mailto: gehen unverändert durch.

4. Der geteilte Dokumentenkopf

Umsetzung: helper/docheader.php plus die .wk-dochead*-Regeln in style.css. Erreichbar als sechste Methode auf ui.components.

Warum es ihn gibt

Zwei Plugins bauten je einen eigenen Kopf für dieselbe Aufgabe — wksourceview für eine Datei, wkdoadogit für ein Repository. Gleiche Aufgabe, verschiedene Elementreihenfolge, verschiedenes Kürzungsverhalten, verschiedene Tönung. Auf einer Seite mit beiden standen zwei Auffassungen davon nebeneinander, was ein Kopf ist.

Der Vertrag ist das Spec-Array, nicht das Markup. Der Aufrufer beschreibt, was im Kopf steht; das Bauteil entscheidet Anordnung, Reihenfolge, Kürzung und Verankerung. Ein Aufrufer kann damit keinen abweichend geformten Kopf erzeugen — genau das ist der Zweck.

Zonen

Zone	Inhalt	Verhalten
`ident`	Symbol + Name (+ eine gedämpfte Referenz dahinter)	nimmt die freie Breite, kürzt
`meta`	Zustands-Abzeichen	kurz, fest, schrumpft nie
`tabs`	Geschwisteransichten desselben Objekts	entfällt bei weniger als zwei Reitern
`actions`	Verweise und Knöpfe auf dem Objekt	am Ende der Leiste

Schlüssel des Spec-Arrays

Schlüssel	Bedeutung
`name`	der Anzeigename — das, wonach ein Leser sucht
`icon`	Symbol-Alias (siehe Abschnitt 5), kein Markup
`reference`	Qualifizierung hinter dem Namen; entfällt, wenn sie den Namen nur wiederholt
`headingLevel`	2–6: der Name wird eine echte Überschrift. Ohne Angabe ein `<span>`
`badges`	Liste aus `text`, `variant`, `mono`
`tabs`	Liste aus `label`, `href`, `active`, `disabled`
`actions`	Liste aus `label`, `icon`, `href`, `title`, `class`, `attrs`
`layout`	`row` (volle Lesespalte) oder `stacked` (schmale Spalte)
`sticky`	oben am scrollenden Vorfahren verankern
`class`	zusätzliche Klasse am Wurzelelement, für Plugin-eigene Anker

stacked ist kein Geschmack, sondern eine Messung. In der 15-em-Seitenspalte ist der Name das einzige schrumpffähige Element neben kurzen Abzeichen fester Breite — auf einer gemeinsamen Zeile wurde er auf ein Zeichen eingedampft. Deshalb bekommt die Identität dort eine eigene Zeile.

Ohne headingLevel ist der Name absichtlich keine Überschrift. Eine Werkzeugleiste, die oben am Scrollbereich klebt, ist Bedienrahmen; sie in die Dokumentgliederung zu schreiben, führt die Navigation mit Screenreadern in die Irre.

Sicherheit

Jeder Skalarwert wird hier escaped; es gibt keinen Schlüssel, über den ein Aufrufer rohes HTML übergeben kann. Das ist Absicht: ein Kopf besteht aus Namen, Pfaden und Refs, die aus Repositories und Seitentext stammen.

href läuft durch dieselbe Schema-Prüfung wie button() (siehe Abschnitt 3).
attrs wird gefiltert: nur kleingeschriebene Namen aus a–z0–9-; on… wird abgewiesen; href, class, src, srcdoc, style, action, formaction, form, type ebenfalls — die ersten beiden, weil sie eigene Schlüssel haben und doppelt ausgegeben würden (der Browser behält die erste Nennung, also die ungeprüfte).
Ein Wert true erzeugt ein Attribut ohne Wert (download).

Rückfall

Ein Verbraucher prüft mit method_exists($ui, 'header'). Fehlt die Methode — etwa weil doch das originale wvdsdwui die Dienste stellt — zeichnet er seinen eigenen, bewusst schlichten Kopf mit demselben Inhalt. Dieser Rückfall darf nicht zu einer zweiten Umsetzung derselben Gestaltung wachsen; das wäre genau die Abweichung, gegen die das Bauteil angetreten ist.

5. ''ui.icons''

Umsetzung: helper/icons.php. Methoden: has(), icon(), aliases(), name() (letzteres liefert 'wkfluentui-svg' und erscheint in Diagnose-Ansichten).

Die Glyphen sind Inline-SVG, keine Icon-Schrift: kein zusätzlicher Request, kein Aufblitzen vor dem Laden, keine Lizenzpflicht, und die Farbe kommt über currentColor automatisch vom umgebenden Text. Gezeichnet wird auf einem einheitlichen 16×16-Raster.

Ein unbekannter Alias ist kein Fehler: has() meldet false, icon() liefert ''''''. Ein fehlendes Symbol kann eine Seite nie zerstören, es entfällt nur die Verzierung. * Barrierefreiheit: ohne ''label ist ein Symbol dekorativ (aria-hidden=„true“). Mit nicht-leerem label wird es bedeutungstragend (role=„img“ + aria-label). Ein title allein ist kein zugänglicher Name — Tooltips werden uneinheitlich ausgegeben und auf Touch-Geräten nie.

Verfügbare Aliase

project, dashboard, board, pipeline, wiki, org, home, menu, settings, account, repo, source, branch, commit, merge, tag, add, edit, delete, save, search, run, play, link, close, query, drawer, permalink, download, check, warning, error, info, bug, test, folder, file, rocket

Aliase werden auf zwei Wegen angefordert: direkt über →icon('alias') und indirekt als dritter Konstruktorparameter einer Hub-Definition in wkdocore. Wer nur nach icon()-Aufrufen sucht, übersieht die zweite Form — genau so blieb der fehlende Alias pipeline zunächst unbemerkt und die Hub-Leiste zeigte einen Eintrag ohne Symbol.

6. ''ui.tokens''

Ein einfaches Array name ⇒ Farbwert, ohne das Präfix –wk- (die Form, die wvdsdwui veröffentlicht). Es richtet sich an PHP-seitige Verbraucher — Diagnose-Ansichten, serverseitig erzeugte Inline-Stile. Was die Stylesheets der DWDO-Plugins tatsächlich lesen, sind die CSS-Eigenschaften in style.css; beide müssen zusammen gepflegt werden.

7. Die Kompatibilitätsschicht im CSS

Die DWDO-Stylesheets zeichnen gegen ein zweites Vokabular: –wk-color-accent, –wk-color-bg, –wk-color-surface, –wk-color-border, –wk-color-text-muted und weitere, dazu –wk-motion, –wk-easing, –wk-elevation-3. Dieses Wiki kennt stattdessen die flache Palette (–wk-accent, –wk-ink, –wk-paper, …).

Ohne Übersetzung lösen die var()-Aufrufe der DWDO-Plugins zu nichts auf: kein Hintergrund, kein Rahmen, keine Textfarbe — sichtbar kaputte Flächen, nicht bloß ein anderer Farbton. Die Schicht in style.css ist deshalb tragend, nicht dekorativ.

Jede Zeile ist ein Alias auf die flache Palette, nie eine neue Farbe. Überschreibt ein Template die flache Palette, färben sich die DWDO-Bildschirme automatisch mit — es gibt keine zweite Stelle zu pflegen.

–wk-color-bg ist die Grundfläche, –wk-color-surface die erhöhte Fläche darauf. Die flache Palette benennt das genau andersherum (–wk-surface ist die hellste Farbe). Die Zuordnung ist deshalb bewusst nicht namensgleich.