@ccslabs/xtend 0.1.0-rc.1

package/docs/components/xtextarea.md

@@ -0,0 +1,98 @@
+# xtextarea - XTend Komponente
+
+> **Siehe auch:** [xform](./xform.md), [xinput](./xinput.md), [xselect](./xselect.md), [xstate](./xstate.md)
+
+## Uebersicht
+
+`<x-textarea>` ist das Long-Form-Input aus `WP-E10-10`. Die Komponente kapselt eine native `textarea`, ist form-associated, schreibt ihren Wert nach `xstate` und bringt RMT-, Fabric-, A11y- und Performance-Metadaten mit.
+
+## Verwendung
+
+```html
+<x-textarea id="notes" name="notes" maxlength="240" rows="5" required>
+  <span slot="label">Notes</span>
+  <span slot="hint">Keep the message concise.</span>
+  <span slot="error">A note is required.</span>
+</x-textarea>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `name` | String | Formularname |
+| `value` | String | aktueller Textwert |
+| `placeholder` | String | Platzhaltertext |
+| `required` | Boolean | aktiviert native Validierung |
+| `disabled` | Boolean | deaktiviert das Control |
+| `readonly` | Boolean | macht das Control lesbar |
+| `maxlength` | Number | maximale Zeichenanzahl |
+| `minlength` | Number | minimale Zeichenanzahl |
+| `rows` | Number | sichtbare Zeilen |
+| `label` | String | Label ohne Slot |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `textarea-changed` | `{ value, length, maxLength, source: 'x-textarea' }` |
+| `textarea-invalid` | `{ value, message, source: 'x-textarea' }` |
+
+## API
+
+- `element.value`
+- `element.maxLength`
+- `element.checkValidity()`
+- `element.reportValidity()`
+- `element.validate()`
+- `element.reset()`
+- `element.focus()`
+
+## State, RMT und Fabric
+
+`<x-textarea>` schreibt nach `xtextarea-value-<id>` und akzeptiert externe Wertupdates ueber denselben Key. Die RMT-Metadaten nutzen `xtend.rmt.component-contract.v1`, `adapter: 'xtend.component'` und `kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'`. RMT kann das Control als DOM-Descriptor erzeugen und Events wie `textarea-changed` an Scheduler-Kommandos binden.
+
+## A11y und Performance
+
+Das Control nutzt `role="textbox"` ueber die native Textarea, `aria-describedby`, eine polite Counter-Region mit `character-count-announcement` und eine assertive Fehlerregion. Das Performance-Profil ist `xtend.performance.component-profile.v1` mit `budgetClass: 'interactive-medium'`, `lane: 'user-blocking'` und `hydrationPolicy: 'visible'`.
+
+## Form Controls UX ab WP-E11-08
+
+`<x-textarea>` stellt `xtendFormControlUxProfile` mit `xtend.component.form-control-ux-profile.v1` bereit. Das Profil verbindet Label, Hint, Error, `textarea-changed`, `textarea-invalid`, `xtextarea-value-<id>`, `ui.user-blocking.input`, Fabric-Lane `user-blocking` und RMT Shell Authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: Enterprise-Schreibflaeche mit ruhiger Flaechenqualitaet, Live-Counter und getrennt themebaren Helper-/Error-Rollen.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-form-text` | Host-Textfarbe |
+| `--xtend-form-control-surface` | Textarea-Flaeche |
+| `--xtend-form-control-text` | Textarea-Text |
+| `--xtend-form-label-text` | Label |
+| `--xtend-form-helper-text` | Helper und Counter |
+| `--xtend-form-error-text` | Fehlertext |
+| `--xtend-form-error-surface` | Fehlerflaeche |
+| `--xtend-form-error-border` | Fehlerkante und Marker |
+| `--xtend-form-focus-ring` | Focus-Outline |
+| `--xtend-form-radius` | Textarea-/Error-Radius |
+| `--xtend-form-gap` | Meta- und Error-Abstand |
+| `--xtend-form-font-family` | Form-Typografie |
+| `--xtend-form-control-font-size` | Textarea-Schrift |
+| `--xtend-form-helper-font-size` | Helper/Error-Schrift |
+| `--xtend-form-icon-color` | Status-/Affordance-Fallback |
+
+Density-Profile: `comfortable`, `compact`, `dense`. Invalid/Error nutzt Kante, Ring und Marker statt ausschliesslich Farbe.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-textarea {
+  --xtend-form-control-surface: #fbf8f2;
+  --xtend-form-control-text: #16231f;
+  --xtend-form-label-text: #22312c;
+  --xtend-form-helper-text: #596861;
+  --xtend-form-error-text: #7d231c;
+  --xtend-form-error-border: #a64036;
+  --xtend-form-focus-ring: 3px solid #8f4f2a;
+  --xtend-form-radius: 0.35rem;
+}
+```

package/docs/components/xtheme.md

@@ -0,0 +1,167 @@
+# xtheme - XTend Core-Modul
+
+## Uebersicht
+
+`xtheme.js` ist das zentrale Theme-Management von XTend. Die Runtime wird unter `window.XTend.theme` bereitgestellt; `window.XTheme` bleibt als oeffentliche Kompatibilitaets-Fassade erhalten.
+
+## Oeffentliche API
+
+| Methode | Beschreibung |
+|---------|--------------|
+| `getCurrentTheme()` | liefert das aktive Theme |
+| `getAvailableThemes()` | liefert alle bekannten Themes |
+| `setTheme(themeName)` | schaltet auf ein Theme um |
+| `toggleDarkMode()` | schaltet zwischen `light` und `dark` um |
+| `registerTheme(name, properties)` | registriert oder erweitert ein Theme |
+| `loadExternalTheme(name, cssUrl)` | laedt ein externes Theme-CSS |
+| `removeExternalTheme(name)` | entfernt ein externes Theme-CSS |
+| `set(name, value)` | Kompatibilitaets-Fassade fuer Theme oder CSS-Variable |
+| `get(name)` | liest aktuelles Theme oder CSS-Variable |
+| `subscribe(fn)` | registriert einen Listener fuer Theme-Aenderungen |
+| `getDesignTokens(themeName?)` | liefert die zentralen XTend-Design-Tokens fuer ein Theme |
+| `getDesignTokenContract()` | liefert den produktiven Contract `xtend.design-tokens.product-contract.v1` mit Theme Packs, Density Packs und CSS Parts |
+| `setDensity(density)` | setzt die globale Density Boundary auf `compact`, `comfortable` oder `dense` |
+| `getDensity()` | liefert die aktive Density |
+| `getAvailableDensities()` | liefert alle unterstuetzten Density Presets |
+| `getThemeContext()` | liefert den propagierten Theme-/Density-/Preference-Kontext |
+| `snapshotPerformance()` | liefert den aktuellen Performance-/Fabric-Diagnostics-Snapshot |
+| `getPerformanceProfile()` | liefert das Performance Profile `xtend.performance.component-profile.v1` |
+| `getRmtMetadata()` | liefert RMT Shell Authoring Metadata ohne RMT-Kernel-Kopplung |
+| `getComponentNetworkContext()` | liefert den Component Network Provider Contract |
+| `getA11yPreferences()` | liefert Reduced-Motion-, Forced-Colors- und Color-Scheme-Snapshot |
+| `getMotionPreference()` | liefert `default` oder `reduced` |
+| `getContrastPreference()` | liefert `normal` oder `forced-colors` |
+| `getA11yProfile()` | liefert den Runtime-A11y-Provider-Contract |
+| `getMotionContrastPolicy()` | liefert die Motion-/Contrast-Policy fuer Gates |
+
+## `set(name, value)` Contract
+
+```js
+window.XTend.theme.setTheme('dark');
+window.XTend.theme.set('light');
+window.XTend.theme.set('--primary-color', '#0e4e81');
+```
+
+- `set('dark')` ist ein Alias fuer `setTheme('dark')`
+- `set('--primary-color', '#0e4e81')` schreibt eine CSS-Variable in das aktuelle Theme
+
+## Theme-Lifecycle
+
+- das aktive Theme wird ueber `data-theme` auf `document.documentElement` gespiegelt
+- Density wird ueber `data-xtend-density` auf `document.documentElement` gespiegelt
+- Motion- und Contrast-Preferences werden ueber `data-xtend-motion`, `data-xtend-contrast` und `data-xtend-forced-colors` gespiegelt
+- `document.documentElement.style.colorScheme` folgt dem aktiven Theme (`light`/`dark`)
+- registrierte CSS-Variablen werden pro Theme verwaltet und beim Wechsel neu angewendet
+- extern geladene Themes werden zwischengespeichert und spaeter beim Aktivieren erneut angewendet
+- Theme-Aenderungen werden ueber `xstate` synchronisiert:
+  - `theme`
+  - `themes`
+  - `xtend.theme.current`
+  - `xtend.theme.density`
+  - `xtend.theme.available`
+  - `xtend.theme.preferences`
+  - `xtend.theme.context`
+  - `xtend.theme.performanceProfile`
+  - `xtend.theme.performanceSnapshot`
+  - `xtend.theme.rmtMetadata`
+  - `xtend.theme.componentNetwork`
+  - `xtend.theme.prefersReducedMotion`
+  - `xtend.theme.forcedColors`
+  - `xtend.a11y.motion`
+  - `xtend.a11y.contrast`
+
+## Zentrale XTend-Tokens
+
+Die Default-Themes liefern produktive Basistokens fuer Core-Komponenten, unter anderem:
+
+- `--xtend-color-primary`
+- `--xtend-color-primary-dark`
+- `--xtend-color-accent`
+- `--xtend-glass-bg`
+- `--xtend-glass-blur`
+- `--xtend-shadow`
+- `--xtend-border`
+- `--xtend-radius`
+- `--xtend-font-family`
+- `--xtend-focus-outline`
+- `--xtend-focus-outline-offset`
+- `--xtend-surface`
+- `--xtend-surface-muted`
+- `--xtend-text`
+- `--xtend-overlay-bg`
+- `--xtend-motion-duration-fast`
+- `--xtend-motion-duration-base`
+- `--xtend-motion-scale`
+- `--xtend-density-scale`
+- `--xtend-density-spacing`
+- `--xtend-control-height`
+- `--xtend-font-scale`
+
+Ab `WP-E12-12` sind diese Tokens Teil des Produktcontracts `xtend.design-tokens.product-contract.v1`. `getDesignTokenContract()` gibt Theme Packs (`light`, `dark`, `high-contrast`, `forced-colors`), Density Packs (`compact`, `comfortable`, `dense`) und stabile CSS Parts zurueck. Die separate Entwicklerdokumentation liegt in [Design Tokens](../design-tokens.md).
+
+## Performance Profile und Density Boundary
+
+`x-theme` ist ab `WP-E12-05` die zentrale Theme-, Preference- und Density Boundary fuer den Komponentenstack. Das Modul besitzt ein explizites Performance Profile:
+
+- Schema: `xtend.performance.component-profile.v1`
+- Lane: `user-blocking`
+- Hydration Policy: `eager`
+- Messpunkte: `xtend.theme.initialize`, `xtend.theme.apply`, `xtend.theme.propagate`, `xtend.theme.density` und `xtend.theme.external-css`
+- Fabric Snapshot Path: `xtend.theme.performanceSnapshot`
+
+Density wird als Provider-Kontext behandelt, nicht als lokale Komponenteneigenschaft. `setDensity('compact')`, `setDensity('comfortable')` und `setDensity('dense')` setzen `data-xtend-density` und die Tokens `--xtend-density-scale`, `--xtend-density-spacing`, `--xtend-control-height` und `--xtend-font-scale`. `spacious` ist kein produktiver Density-Name mehr und wird bei alten Persistenzdaten auf `comfortable` normalisiert.
+
+Der propagierte Kontext liegt unter `xtend.theme.context` und nutzt das Schema `xtend.theme.context.v1`. Er enthaelt Theme, Density, A11y Preferences, aktive Tokens, Density Tokens, RMT Metadata, Fabric Lane und eine `propagationVersion`.
+
+## RMT und Component Network
+
+`x-theme` stellt RMT Shell Authoring Metadata bereit, ohne XTend in den RMT Kernel einzubetten:
+
+- RMT Schema: `xtend.rmt.component-contract.v1`
+- Adapter: `xtend.theme-provider`
+- Shell Authoring Schema: `xtend.rmt.shell-authoring.component.v1`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+Der Component Network Contract nutzt `xtend.component.network.v1`. Verbraucher wie `xtend.component`, `xtend.xrouter`, `xtend.fabric-telemetry` oder `rmt.shell-authoring` lesen den publizierten Kontext ueber Events und `xstate`, nicht ueber harte Imports.
+
+## Reduced Motion und Forced Colors
+
+`x-theme` ist ab `WP-E12-04` die zentrale A11y-Preference-Boundary fuer den Komponentenstack. Das Modul beobachtet `prefers-reduced-motion: reduce`, `forced-colors: active` und `prefers-color-scheme: dark`, ohne XTendRMT oder Host-Frameworks zu importieren.
+
+- Reduced Motion setzt `data-xtend-motion="reduced"` und reduziert zentrale Motion-Tokens auf `0ms`.
+- Forced Colors setzt `data-xtend-contrast="forced-colors"` und `data-xtend-forced-colors="active"`.
+- Die internen CSS-Regeln nutzen `forced-color-adjust: auto`, `Canvas`, `CanvasText`, `Highlight` und `HighlightText`.
+- Bei System-Preference-Wechseln feuert `theme-preference-changed`.
+- Eine unsichtbare Live-Region mit `role="status"` und `aria-live="polite"` meldet Theme- und Preference-Wechsel fuer Screenreader.
+- Die Policy liegt als `xtend.a11y.motion-contrast-policy.v1` vor und wird ueber `getMotionContrastPolicy()` sichtbar.
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `theme-initialized` | nach Initialisierung des Theme-Managers |
+| `theme-changed` | nach Theme-Wechsel |
+| `theme-variable-changed` | nach Anpassung einer CSS-Variable |
+| `theme-preference-changed` | nach Reduced-Motion-, Forced-Colors- oder System-Preference-Wechsel |
+| `theme-a11y-announcement` | nach Screenreader-Announcement fuer Theme- oder Preference-Wechsel |
+| `theme-density-changed` | nach Density-Wechsel |
+| `theme-context-changed` | nach Propagation eines neuen Theme-Kontexts |
+| `theme-performance-measured` | nach lokaler Theme-/Density-/Propagation-Messung |
+
+## Beispiel
+
+```js
+window.XTend.theme.setTheme('light');
+window.XTend.theme.set('--body-bg', '#f9f9f9');
+
+window.XTend.theme.registerTheme('dark', {
+  '--body-bg': '#181a1b',
+  '--text-color': '#fff'
+});
+```
+
+## Hinweise
+
+- `xtheme.js` ist ein Core-Modul, kein separates Styling-Framework.
+- Die Runtime ist namespaced unter `window.XTend.theme`; `window.XTheme` ist nur die oeffentliche Kompatibilitaets-Fassade.
+- Externe Theme-CSS-Dateien bleiben nach dem ersten Laden fuer spaetere Aktivierungen verfuegbar.

package/docs/components/xtoast.md

@@ -0,0 +1,62 @@
+# xtoast - XTend Komponente
+
+## Uebersicht
+
+`<x-toast>` ist die kompakte Feedback-Komponente fuer temporaere Hinweise. Toasts sind nicht blockierend, leben kurz und werden im XTend-Core bevorzugt ueber `window.XToast` erzeugt.
+
+## Verwendung
+
+```html
+<x-toast type="success" duration="3000">Gespeichert</x-toast>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `type` | string | `info`, `success`, `warning`, `error` |
+| `duration` | number | Dauer in Millisekunden, `0` deaktiviert Auto-Close |
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `toast-shown` | nach dem Einfuegen des Toasts |
+| `toast-dismissed` | nach dem Schliessen des Toasts |
+
+Die Events liefern:
+
+```js
+{
+  id: 'toast-abc123',
+  message: 'Gespeichert',
+  type: 'success',
+  duration: 3000,
+  reason: 'timeout'
+}
+```
+
+## Runtime-Contract
+
+- API-gemanagte Toasts werden aggregiert in `xstate.get('ui').toasts`
+- die Komponente selbst stellt den Lifecycle ueber Events bereit
+- der versteckte globale Helper-Pfad lebt in `api.js`, nicht mehr in der Komponente
+- der API-Toast-Stack nutzt `#xtoast-container` als viewport-sichere Surface mit `width: min(24rem, calc(100vw - 2rem))`
+
+## Layout
+
+`window.XToast.show()` legt API-gemanagte Toasts in einem frameworkeigenen Stack ab. Dieser Stack bleibt rechts unten im Viewport, nutzt Safe-Area-Abstaende und dehnt Toasts innerhalb der verfuegbaren Breite, statt sie ueber den rechten Viewport-Rand hinauslaufen zu lassen.
+
+Direkt platzierte `<x-toast>` Elemente sind ebenfalls containerfreundlich: die Komponente nutzt `max-width: 100%`, bricht lange Inhalte um und reserviert Platz fuer den Close-Button.
+
+## Feedback Status UX ab WP-E11-09
+
+`<x-toast>` stellt `xtendFeedbackStatusUxProfile` mit `xtend.component.feedback-status-ux-profile.v1` bereit. Das Profil beschreibt `x-toast` als kurzlebige Feedback-Shell mit `toast-shown`, `toast-dismissed`, `xtoast-state-<id>`, `a11y.announce`, Fabric-Lane `a11y` und RMT Shell Authoring.
+
+Timeouts liefern `reason: 'timeout'`; manuelle Dismiss-Pfade liefern `reason: 'button'` oder `manual`. Event-Details enthalten `source: 'x-toast'`, `stateKey` und `dismissed`, damit Status- und Diagnostik-Lanes Toast-Lifecycles eindeutig zuordnen koennen.
+
+## Hinweise
+
+- Toasts sind semantisch fuer kurzlebige, nicht blockierende Hinweise gedacht
+- fuer laenger sichtbare oder inhaltlich wichtigere Meldungen ist `x-alert` die richtige Komponente
+- `window.XToast.show()` ist der bevorzugte Einstieg fuer API-gemanagte Toasts

package/docs/components/xtooltip.md

@@ -0,0 +1,66 @@
+# xtooltip - XTend Komponente
+
+> **Siehe auch:** [xpopover](./xpopover.md), [xdrawer](./xdrawer.md), [xdialog](./xdialog.md), [xmodal](./xmodal.md)
+
+## Uebersicht
+
+`<x-tooltip>` ist die leichte Overlay-Hilfe aus `WP-E10-11`. Die Komponente verbindet ein Ziel-Element ueber `aria-describedby`, oeffnet bei Hover oder Fokus und schliesst ueber Blur, Mouseleave oder `Escape`.
+
+## Verwendung
+
+```html
+<button id="schedule-help">Inspect schedule</button>
+<x-tooltip id="route-tooltip" for="schedule-help" placement="top" delay="20" label="Tooltip help">
+  Explains the scheduled action.
+</x-tooltip>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `for` | String | ID des Anchor-Elements |
+| `placement` | String | `top`, `right`, `bottom` oder `left` |
+| `open` | Boolean | oeffnet den Tooltip kontrolliert |
+| `delay` | Number | Oeffnungsverzoegerung in Millisekunden |
+| `label` | String | zugaenglicher Name fuer den Tooltip |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `tooltip-opened` | `{ id, open, source, placement }` |
+| `tooltip-closed` | `{ id, open, source, placement }` |
+
+## API
+
+- `show()`
+- `hide()`
+- `toggle()`
+
+## State, RMT und Fabric
+
+`<x-tooltip>` schreibt nach `xtooltip-open-<id>`. Der RMT Contract ist `xtend.rmt.component-contract.v1` und nutzt die Schedules `component.visible.mount`, `component.idle.hydrate` und `overlay.tooltip.position`. Der Kernel Boundary bleibt `no-rmt-kernel-import-of-xtend-types`.
+
+## A11y und Performance
+
+Die Komponente nutzt `role="tooltip"`, setzt `aria-describedby` am Anchor und dokumentiert `dismiss-on-escape` als Screenreader-Signal. Das Performance-Profil ist `xtend.performance.component-profile.v1` mit `budgetClass: 'overlay-small'`, `lane: 'visible'` und `hydrationPolicy: 'idle'`.
+
+## Overlay Interaction UX Profil
+
+Seit `WP-E11-11` deklariert `<x-tooltip>` das Runtime-Profil `xtend.component.overlay-interaction-ux-profile.v1` ueber `xtendOverlayInteractionUxProfile`.
+
+| Feld | Wert |
+|------|------|
+| Family | `tooltip` |
+| State Key | `xtooltip-open-<id>` |
+| Schedule | `overlay.position.update` |
+| Commands | `show`, `hide`, `toggle`, `snapshot` |
+
+Das Profil haelt Tooltip-Overlays bewusst nicht modal: kein Focus Trap, kein Inert, kein Scroll Lock. RMT kann Positionierung und Dismissal schedulen, waehrend der Host weiterhin `aria-describedby`, Hover/Fokus und Escape verwaltet.
+
+## ECH-WP-06 Overlay-Paritaet
+
+`x-tooltip` expose `surface`, `backdrop`, `close` und `content` als Overlay-Parts, wobei `backdrop` und `close` bewusst nicht-interaktive Sentinels fuer Theme-/Part-Paritaet sind. Der Tooltip bleibt nicht-modal und informationsbezogen.
+
+Surface, Text, Elevation, Radius, Typografie und Z-Index laufen ueber `--xtend-overlay-*`, `--tooltip-*` oder `--xtooltip-*` Tokens. Focus Trap, Inert und Scroll Lock sind fuer Tooltips nicht anwendbar.

package/docs/components/xtype.md

@@ -0,0 +1,82 @@
+# xtype – XTend Komponente
+
+> **Siehe auch:** [xwriter](./xwriter.md)
+
+## Übersicht
+
+`<x-type>` ist eine Komponente für animierte Texteffekte (z.B. Typing Animation). Sie eignet sich für Hero-Bereiche, Überschriften und interaktive UI-Elemente.
+
+---
+
+## Features
+- Animierte Texteffekte (Typing, Loop)
+- Anpassbare Geschwindigkeit
+- Theming via CSS Custom Properties
+
+---
+
+## Verwendung
+
+```html
+<x-type text="XTend rocks!" speed="80"></x-type>
+```
+
+---
+
+## Attribute
+| Attribut    | Typ     | Beschreibung                        |
+|-------------|---------|-------------------------------------|
+| `text`      | String  | Anzuzeigender Text                   |
+| `speed`     | Number  | Geschwindigkeit in ms pro Zeichen    |
+| `loop`      | Boolean | Endlosschleife                       |
+
+---
+
+## Events
+| Event         | Beschreibung                        |
+|---------------|-------------------------------------|
+| `done`        | Wird nach Animation ausgelöst        |
+
+---
+
+## API
+- **Text dynamisch setzen:** `element.setAttribute('text', 'Hallo')`
+
+---
+
+## Beispiel: Dynamisch per JS
+
+```js
+const type = document.createElement('x-type');
+type.setAttribute('text', 'Hallo Welt!');
+document.body.appendChild(type);
+```
+
+---
+
+## Styling & Theming
+
+```css
+x-type {
+  --type-color: #007bff;
+}
+```
+
+---
+
+## Accessibility
+- Semantisches HTML
+
+---
+
+*Letzte Aktualisierung: 16. Juli 2025*
+
+## Layout Display Media UX Profil
+
+`x-type` stellt ab `WP-E11-12` das Profil `xtend.component.layout-display-media-ux-profile.v1` bereit. Die Komponente nutzt eine Shadow-DOM-Shell fuer Text und Cursor, kann idle hydriert werden und schreibt ihren aktuellen Text nach `xtype-current`.
+
+- Profil-Getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.idle.hydrate`
+- Events: `typing-started`, `typing-completed`, `text-erased`
+- Snapshot: `snapshot()`
+- CSS Parts: `root`, `text`, `cursor`

package/docs/components/xutils.md

@@ -0,0 +1,144 @@
+# xutils - XTend Utility-Modul
+
+## Uebersicht
+
+`x-utils` ist ein Manifest-geführtes Utility-Modul und keine eigene Custom-Element-Oberflaeche. Das Modul exportiert `XUtils` und stellt im Browser zusaetzlich `window.XUtils` bereit. Es sammelt kleine DOM-, Event-, A11y-, Format- und Low-Code-Helfer fuer XTend-Komponenten und Demos.
+
+## Import
+
+```js
+import { XUtils } from './components/xutils.js';
+
+const button = XUtils.create('button', {
+  textContent: 'Speichern'
+});
+```
+
+Im Browser ist nach dem Laden des Moduls verfuegbar:
+
+```js
+window.XUtils.find('[data-action="save"]');
+```
+
+## DOM- und Event-API
+
+| Methode | Beschreibung |
+|---------|--------------|
+| `find(selector, root?)` | gibt das erste passende Element zurueck |
+| `findAll(selector, root?)` | gibt alle passenden Elemente als Array zurueck |
+| `create(tag, props?)` | erzeugt ein Element und weist Properties zu |
+| `on(el, type, handler, opts?)` | registriert einen Listener und gibt eine Cleanup-Funktion zurueck |
+| `delegate(root, selector, type, handler)` | delegiert Events innerhalb eines Containers |
+
+## A11y- und UI-Helfer
+
+| Methode | Beschreibung |
+|---------|--------------|
+| `setAria(el, attrs)` | setzt `aria-*` Attribute aus einem Objekt |
+| `focusTrap(container)` | fokussiert das erste fokussierbare Element im Container |
+| `fadeIn(el, duration?)` | einfache Opacity-Animation |
+| `fadeOut(el, duration?)` | einfache Opacity-Animation |
+| `resolveUiEffects(input?)` | normalisiert opt-in UI-Effekte aus Body-Attribut, Loader-Option oder RMT |
+| `prepareUiEffects(input?)` | bereitet einen opt-in UI-Effekt vor, z.B. Body-Fade |
+| `releaseUiEffects(input?)` | gibt einen vorbereiteten UI-Effekt wieder frei |
+| `isMobile()` | prueft den lokalen Mobile-Breakpoint |
+
+## Format- und Datenhelfer
+
+| Methode | Beschreibung |
+|---------|--------------|
+| `hexToRgb(hex)` | wandelt Hex-Farben in RGB-Werte |
+| `contrastColor(hex)` | liefert Schwarz oder Weiss als Kontrastfarbe |
+| `formatDate(date, locale?)` | formatiert ein Datum |
+| `formatNumber(num, locale?)` | formatiert eine Zahl |
+| `uniqueId(prefix?)` | erzeugt eine einfache Runtime-ID |
+| `deepClone(obj)` | erzeugt eine JSON-basierte Kopie |
+
+## XTemplate Recipes
+
+`XUtils.XTemplate` enthaelt kleine Low-Code-Rezepte fuer einfache DOM-Fragmente:
+
+```js
+const card = XUtils.XTemplate.card({
+  title: 'Status',
+  content: 'Alle Systeme bereit'
+});
+
+const action = XUtils.XTemplate.button({
+  label: 'Aktualisieren',
+  onClick: () => window.location.reload()
+});
+```
+
+Aktuelle Rezepte:
+
+| Recipe | Beschreibung |
+|--------|--------------|
+| `card(opts)` | erzeugt eine einfache Card-Struktur |
+| `button(opts)` | erzeugt einen Button |
+| `modal(opts)` | erzeugt eine einfache Modal-Struktur |
+
+## Contract
+
+- `x-utils` ist als Manifest-Eintrag vorhanden, bleibt aber ein Utility-Modul.
+- Es registriert kein `customElements.define()`.
+- Die Datei `docs/components/xutils.md` ist der kanonische Docs-Slug zum Source-Basename `xutils.js`.
+- Runtime-Tag und Manifest-Key bleiben fuer die Catalog Matrix `x-utils`.
+
+## Utility Boundary Contract
+
+Seit `WP-E12-09` ist `x-utils` als nicht-visuelle Utility-Boundary gatebar:
+
+- Utility Schema: `xtend.utility.module-contract.v1`
+- Import Policy Schema: `xtend.utility.import-policy.v1`
+- Import Policy Result Schema: `xtend.utility.import-policy-result.v1`
+- Boundary Probe Schema: `xtend.utility.boundary-probe.v1`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+Die Runtime stellt dafuer drei explizite Contract-APIs bereit:
+
+| Methode | Beschreibung |
+|---------|--------------|
+| `getUtilityContract()` | liefert Kategorien, Exports, Globals und Methoden der Utility-Oberflaeche |
+| `snapshotUtilityContract()` | liefert einen stabilen Boundary-Snapshot fuer Fixtures und Catalog-Gates |
+| `assertLocalImport(specifier)` | prueft, ob ein Import-Specifier lokal und policy-konform ist |
+
+```js
+const local = XUtils.assertLocalImport('/components/xbutton.js');
+const blocked = XUtils.assertLocalImport('https://cdn.ccs-networks.de/xtend/components/xstate.js');
+
+console.log(local.allowed);   // true
+console.log(blocked.allowed); // false
+```
+
+`assertLocalImport()` dispatcht im Browser zusaetzlich `xutils:import-policy-check`. Das Event ist fuer Test-, Fabric- und Security-Harnesses gedacht; der RMT Kernel importiert `x-utils` weiterhin nicht.
+
+## UI Effects Boundary
+
+Seit `xtend.utility.ui-effects.v1` kapselt `x-utils` opt-in Effekte, die die App-Shell beeinflussen koennen. Der globale Loader versteckt den Body nicht mehr standardmaessig. Ein Fade-In muss bewusst aktiviert werden:
+
+```html
+<body xt-ui-effects="fade-in">
+```
+
+RMT-Hosts koennen denselben Effekt als nicht-visuellen Intent beschreiben:
+
+```json
+{
+  "id": "app.ui-effects",
+  "kind": "ui_effects",
+  "tag": "ui-effects",
+  "props": {
+    "effect": "fade-in"
+  }
+}
+```
+
+Die Host-Seite bleibt Ausfuehrungsort. RMT beschreibt nur den Intent; `XUtils.prepareUiEffects()` und `XUtils.releaseUiEffects()` setzen die DOM-Attribute `data-xt-ui-effects`, `data-xt-ui-effects-state` und `data-xt-ui-effects-ready`. Fuer RMT-lose Umgebungen reicht das Body-Attribut. Fuer Shell-first Apps, die keinen Effekt wollen, ist kein Attribut noetig oder explizit `xt-ui-effects="none"` moeglich.
+
+## Hinweise
+
+- Neue Komponenten sollten fuer produktive UI-Vertraege bevorzugt eigene Component-APIs und XTend-Fabric-Gates nutzen.
+- `x-utils` bleibt ein kleiner Hilfsmodul-Pfad fuer Bestand, Demos und einfache DOM-Arbeit.
+- Suite, Fixture und Utility-Typisierung sind seit `WP-E12-09` vorhanden.
+- Seit `WP-E13-05` ist `x-utils` als `closed-as-utility-boundary` bewertet. Ein eigenes visuelles Performance-Profil ist fuer diese Utility-Boundary keine offene RC1-Aufgabe.