@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xtextarea.md

@@ -0,0 +1,115 @@
+# xtextarea - XTend Component
+
+> **See also:** [xform](./xform.md), [xinput](./xinput.md), [xselect](./xselect.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-textarea>` is the long-form input from `WP-E10-10`. The component wraps a
+native `textarea`, is form-associated, writes its value to `xstate`, and brings
+RMT, Fabric, a11y, and performance metadata.
+
+## Usage
+
+```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>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | String | form name |
+| `value` | String | current text value |
+| `placeholder` | String | placeholder text |
+| `required` | Boolean | activates native validation |
+| `disabled` | Boolean | disables the control |
+| `readonly` | Boolean | makes the control read-only |
+| `maxlength` | Number | maximum character count |
+| `minlength` | Number | minimum character count |
+| `rows` | Number | visible rows |
+| `label` | String | label without 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, and Fabric
+
+`<x-textarea>` writes to `xtextarea-value-<id>` and accepts external value
+updates through the same key. RMT metadata uses
+`xtend.rmt.component-contract.v1`, `adapter: 'xtend.component'`, and
+`kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'`. RMT can create the
+control as a DOM descriptor and bind events such as `textarea-changed` to
+scheduler commands.
+
+## A11y and Performance
+
+The control uses `role="textbox"` through the native textarea,
+`aria-describedby`, a polite counter region with
+`character-count-announcement`, and an assertive error region. The performance
+profile is `xtend.performance.component-profile.v1` with
+`budgetClass: 'interactive-medium'`, `lane: 'user-blocking'`, and
+`hydrationPolicy: 'visible'`.
+
+## Form Controls UX from WP-E11-08
+
+`<x-textarea>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects label, hint,
+error, `textarea-changed`, `textarea-invalid`, `xtextarea-value-<id>`,
+`ui.user-blocking.input`, Fabric lane `user-blocking`, and RMT shell authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: enterprise writing surface with calm surface quality, live
+counter, and separately themeable helper/error roles.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-form-text` | host text color |
+| `--xtend-form-control-surface` | textarea surface |
+| `--xtend-form-control-text` | textarea text |
+| `--xtend-form-label-text` | label |
+| `--xtend-form-helper-text` | helper and counter |
+| `--xtend-form-error-text` | error text |
+| `--xtend-form-error-surface` | error surface |
+| `--xtend-form-error-border` | error edge and marker |
+| `--xtend-form-focus-ring` | focus outline |
+| `--xtend-form-radius` | textarea/error radius |
+| `--xtend-form-gap` | meta and error spacing |
+| `--xtend-form-font-family` | form typography |
+| `--xtend-form-control-font-size` | textarea font |
+| `--xtend-form-helper-font-size` | helper/error font |
+| `--xtend-form-icon-color` | status/affordance fallback |
+
+Density profiles: `comfortable`, `compact`, `dense`. Invalid/error state uses
+edge, ring, and marker instead of color only.
+
+```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/en/components/xtheme.md

@@ -0,0 +1,203 @@
+# xtheme - XTend Core Module
+
+## Overview
+
+`xtheme.js` is XTend's central theme management module. The runtime is exposed
+under `window.XTend.theme`; `window.XTheme` remains as the public compatibility
+facade.
+
+## Public API
+
+| Method | Description |
+|--------|-------------|
+| `getCurrentTheme()` | returns the active theme |
+| `getAvailableThemes()` | returns all known themes |
+| `setTheme(themeName)` | switches to a theme |
+| `toggleDarkMode()` | switches between `light` and `dark` |
+| `registerTheme(name, properties)` | registers or extends a theme |
+| `loadExternalTheme(name, cssUrl)` | loads an external theme CSS |
+| `removeExternalTheme(name)` | removes an external theme CSS |
+| `set(name, value)` | compatibility facade for theme or CSS variable |
+| `get(name)` | reads current theme or CSS variable |
+| `subscribe(fn)` | registers a listener for theme changes |
+| `getDesignTokens(themeName?)` | returns central XTend design tokens for a theme |
+| `getDesignTokenContract()` | returns the productive contract `xtend.design-tokens.product-contract.v1` with theme packs, density packs, and CSS parts |
+| `setDensity(density)` | sets the global density boundary to `compact`, `comfortable`, or `dense` |
+| `getDensity()` | returns the active density |
+| `getAvailableDensities()` | returns all supported density presets |
+| `getThemeContext()` | returns propagated theme/density/preference context |
+| `snapshotPerformance()` | returns the current performance/Fabric diagnostics snapshot |
+| `getPerformanceProfile()` | returns the performance profile `xtend.performance.component-profile.v1` |
+| `getRmtMetadata()` | returns RMT shell authoring metadata without RMT kernel coupling |
+| `getComponentNetworkContext()` | returns the Component Network Provider Contract |
+| `getA11yPreferences()` | returns reduced-motion, forced-colors, and color-scheme snapshot |
+| `getMotionPreference()` | returns `default` or `reduced` |
+| `getContrastPreference()` | returns `normal` or `forced-colors` |
+| `getA11yProfile()` | returns the runtime a11y provider contract |
+| `getMotionContrastPolicy()` | returns the motion/contrast policy for 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')` is an alias for `setTheme('dark')`
+- `set('--primary-color', '#0e4e81')` writes a CSS variable into the current
+  theme
+
+## Theme Lifecycle
+
+- the active theme is mirrored to `data-theme` on `document.documentElement`
+- density is mirrored to `data-xtend-density` on `document.documentElement`
+- motion and contrast preferences are mirrored to `data-xtend-motion`,
+  `data-xtend-contrast`, and `data-xtend-forced-colors`
+- `document.documentElement.style.colorScheme` follows the active theme
+  (`light`/`dark`)
+- registered CSS variables are managed per theme and reapplied on switch
+- externally loaded themes are cached and reapplied when activated later
+- theme changes are synchronized through `xstate`:
+  - `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`
+
+## Central XTend Tokens
+
+The default themes provide productive base tokens for core components,
+including:
+
+- `--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`
+
+Starting with `WP-E12-12`, these tokens are part of the product contract
+`xtend.design-tokens.product-contract.v1`. `getDesignTokenContract()` returns
+theme packs (`light`, `dark`, `high-contrast`, `forced-colors`), density packs
+(`compact`, `comfortable`, `dense`), and stable CSS parts. The separate
+developer documentation is [Design Tokens](../design-tokens.md).
+
+## Performance Profile and Density Boundary
+
+Since `WP-E12-05`, `x-theme` is the central theme, preference, and density
+boundary for the component stack. The module has an explicit performance
+profile:
+
+- Schema: `xtend.performance.component-profile.v1`
+- Lane: `user-blocking`
+- Hydration Policy: `eager`
+- Measurement points: `xtend.theme.initialize`, `xtend.theme.apply`,
+  `xtend.theme.propagate`, `xtend.theme.density`, and
+  `xtend.theme.external-css`
+- Fabric Snapshot Path: `xtend.theme.performanceSnapshot`
+
+Density is treated as provider context, not as a local component property.
+`setDensity('compact')`, `setDensity('comfortable')`, and
+`setDensity('dense')` set `data-xtend-density` and the tokens
+`--xtend-density-scale`, `--xtend-density-spacing`,
+`--xtend-control-height`, and `--xtend-font-scale`. `spacious` is no longer a
+productive density name and is normalized to `comfortable` for old persisted
+data.
+
+The propagated context lives under `xtend.theme.context` and uses schema
+`xtend.theme.context.v1`. It contains theme, density, a11y preferences, active
+tokens, density tokens, RMT metadata, Fabric lane, and a `propagationVersion`.
+
+## RMT and Component Network
+
+`x-theme` provides RMT shell authoring metadata without embedding XTend in the
+RMT kernel:
+
+- 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`
+
+The Component Network Contract uses `xtend.component.network.v1`. Consumers
+such as `xtend.component`, `xtend.xrouter`, `xtend.fabric-telemetry`, or
+`rmt.shell-authoring` read the published context through events and `xstate`,
+not through hard imports.
+
+## Reduced Motion and Forced Colors
+
+Since `WP-E12-04`, `x-theme` is the central a11y preference boundary for the
+component stack. The module observes `prefers-reduced-motion: reduce`,
+`forced-colors: active`, and `prefers-color-scheme: dark` without importing
+XTendRMT or host frameworks.
+
+- Reduced motion sets `data-xtend-motion="reduced"` and reduces central motion
+  tokens to `0ms`.
+- Forced colors sets `data-xtend-contrast="forced-colors"` and
+  `data-xtend-forced-colors="active"`.
+- Internal CSS rules use `forced-color-adjust: auto`, `Canvas`, `CanvasText`,
+  `Highlight`, and `HighlightText`.
+- System preference changes fire `theme-preference-changed`.
+- An invisible live region with `role="status"` and `aria-live="polite"`
+  announces theme and preference changes for screen readers.
+- The policy exists as `xtend.a11y.motion-contrast-policy.v1` and is exposed
+  through `getMotionContrastPolicy()`.
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `theme-initialized` | after theme manager initialization |
+| `theme-changed` | after theme switch |
+| `theme-variable-changed` | after a CSS variable change |
+| `theme-preference-changed` | after reduced-motion, forced-colors, or system preference changes |
+| `theme-a11y-announcement` | after screen reader announcement for theme or preference change |
+| `theme-density-changed` | after density change |
+| `theme-context-changed` | after propagation of a new theme context |
+| `theme-performance-measured` | after local theme/density/propagation measurement |
+
+## Example
+
+```js
+window.XTend.theme.setTheme('light');
+window.XTend.theme.set('--body-bg', '#f9f9f9');
+
+window.XTend.theme.registerTheme('dark', {
+  '--body-bg': '#181a1b',
+  '--text-color': '#fff'
+});
+```
+
+## Notes
+
+- `xtheme.js` is a core module, not a separate styling framework.
+- The runtime is namespaced under `window.XTend.theme`; `window.XTheme` is only
+  the public compatibility facade.
+- External theme CSS files remain available for later activations after their
+  first load.

package/docs/en/components/xtoast.md

@@ -0,0 +1,78 @@
+# xtoast - XTend Component
+
+## Overview
+
+`<x-toast>` is the compact feedback component for temporary notices. Toasts are
+non-blocking, short-lived, and are preferably created through `window.XToast`
+in XTend Core.
+
+## Usage
+
+```html
+<x-toast type="success" duration="3000">Saved</x-toast>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `type` | string | `info`, `success`, `warning`, `error` |
+| `duration` | number | duration in milliseconds, `0` disables auto-close |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `toast-shown` | after the toast is inserted |
+| `toast-dismissed` | after the toast is closed |
+
+Events provide:
+
+```js
+{
+  id: 'toast-abc123',
+  message: 'Saved',
+  type: 'success',
+  duration: 3000,
+  reason: 'timeout'
+}
+```
+
+## Runtime Contract
+
+- API-managed toasts are aggregated in `xstate.get('ui').toasts`
+- the component itself exposes lifecycle through events
+- the hidden global helper path lives in `api.js`, no longer in the component
+- the API toast stack uses `#xtoast-container` as a viewport-safe surface with
+  `width: min(24rem, calc(100vw - 2rem))`
+
+## Layout
+
+`window.XToast.show()` places API-managed toasts in a framework-owned stack.
+This stack stays bottom-right in the viewport, uses safe-area spacing, and
+stretches toasts within the available width instead of letting them overflow
+past the right viewport edge.
+
+Directly placed `<x-toast>` elements are container-friendly as well: the
+component uses `max-width: 100%`, wraps long content, and reserves space for
+the close button.
+
+## Feedback Status UX from WP-E11-09
+
+`<x-toast>` exposes `xtendFeedbackStatusUxProfile` with
+`xtend.component.feedback-status-ux-profile.v1`. The profile describes
+`x-toast` as a short-lived feedback shell with `toast-shown`,
+`toast-dismissed`, `xtoast-state-<id>`, `a11y.announce`, Fabric lane `a11y`,
+and RMT shell authoring.
+
+Timeouts provide `reason: 'timeout'`; manual dismiss paths provide
+`reason: 'button'` or `manual`. Event details include `source: 'x-toast'`,
+`stateKey`, and `dismissed`, so status and diagnostics lanes can unambiguously
+map toast lifecycles.
+
+## Notes
+
+- Toasts are semantically meant for short-lived, non-blocking notices.
+- Use `x-alert` for messages that should remain visible longer or carry more
+  important content.
+- `window.XToast.show()` is the preferred entry point for API-managed toasts.

package/docs/en/components/xtooltip.md

@@ -0,0 +1,85 @@
+# xtooltip - XTend Component
+
+> **See also:** [xpopover](./xpopover.md), [xdrawer](./xdrawer.md), [xdialog](./xdialog.md), [xmodal](./xmodal.md)
+
+## Overview
+
+`<x-tooltip>` is the lightweight overlay help component from `WP-E10-11`. The
+component connects to a target element through `aria-describedby`, opens on
+hover or focus, and closes on blur, mouseleave, or `Escape`.
+
+## Usage
+
+```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>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `for` | String | ID of the anchor element |
+| `placement` | String | `top`, `right`, `bottom`, or `left` |
+| `open` | Boolean | opens the tooltip in controlled mode |
+| `delay` | Number | opening delay in milliseconds |
+| `label` | String | accessible name for the tooltip |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `tooltip-opened` | `{ id, open, source, placement }` |
+| `tooltip-closed` | `{ id, open, source, placement }` |
+
+## API
+
+- `show()`
+- `hide()`
+- `toggle()`
+
+## State, RMT, and Fabric
+
+`<x-tooltip>` writes to `xtooltip-open-<id>`. The RMT contract is
+`xtend.rmt.component-contract.v1` and uses the schedules
+`component.visible.mount`, `component.idle.hydrate`, and
+`overlay.tooltip.position`. The kernel boundary remains
+`no-rmt-kernel-import-of-xtend-types`.
+
+## A11y and Performance
+
+The component uses `role="tooltip"`, sets `aria-describedby` on the anchor, and
+documents `dismiss-on-escape` as a screen reader signal. The performance
+profile is `xtend.performance.component-profile.v1` with
+`budgetClass: 'overlay-small'`, `lane: 'visible'`, and `hydrationPolicy:
+'idle'`.
+
+## Overlay Interaction UX Profile
+
+Since `WP-E11-11`, `<x-tooltip>` declares the runtime profile
+`xtend.component.overlay-interaction-ux-profile.v1` through
+`xtendOverlayInteractionUxProfile`.
+
+| Field | Value |
+|-------|-------|
+| Family | `tooltip` |
+| State Key | `xtooltip-open-<id>` |
+| Schedule | `overlay.position.update` |
+| Commands | `show`, `hide`, `toggle`, `snapshot` |
+
+The profile intentionally keeps tooltip overlays non-modal: no focus trap, no
+inert, no scroll lock. RMT can schedule positioning and dismissal while the
+host continues to manage `aria-describedby`, hover/focus, and Escape.
+
+## ECH-WP-06 Overlay Parity
+
+`x-tooltip` exposes `surface`, `backdrop`, `close`, and `content` as overlay
+parts, with `backdrop` and `close` intentionally acting as non-interactive
+sentinels for theme/part parity. The tooltip remains non-modal and
+information-oriented.
+
+Surface, text, elevation, radius, typography, and z-index use
+`--xtend-overlay-*`, `--tooltip-*`, or `--xtooltip-*` tokens. Focus trap, inert,
+and scroll lock do not apply to tooltips.

package/docs/en/components/xtype.md

@@ -0,0 +1,91 @@
+# xtype - XTend Component
+
+> **See also:** [xwriter](./xwriter.md)
+
+## Overview
+
+`<x-type>` is a component for animated text effects such as typing animation.
+It is suitable for hero areas, headings, and interactive UI elements.
+
+---
+
+## Features
+
+- Animated text effects (typing, loop)
+- Customizable speed
+- Theming through CSS custom properties
+
+---
+
+## Usage
+
+```html
+<x-type text="XTend rocks!" speed="80"></x-type>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `text` | String | text to display |
+| `speed` | Number | speed in ms per character |
+| `loop` | Boolean | endless loop |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `done` | emitted after animation |
+
+---
+
+## API
+
+- **Set text dynamically:** `element.setAttribute('text', 'Hello')`
+
+---
+
+## Example: Dynamic JS
+
+```js
+const type = document.createElement('x-type');
+type.setAttribute('text', 'Hello world!');
+document.body.appendChild(type);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-type {
+  --type-color: #007bff;
+}
+```
+
+---
+
+## Accessibility
+
+- Semantic HTML
+
+---
+
+*Last updated: July 16, 2025*
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-type` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component uses a
+Shadow DOM shell for text and cursor, can be hydrated on idle, and writes its
+current text to `xtype-current`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.idle.hydrate`
+- Events: `typing-started`, `typing-completed`, `text-erased`
+- Snapshot: `snapshot()`
+- CSS parts: `root`, `text`, `cursor`