@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xspinner.md

@@ -0,0 +1,118 @@
+# xspinner - XTend Component
+
+> **See also:** [xtoast](./xtoast.md), [xalert](./xalert.md)
+
+## Overview
+
+`<x-spinner>` is an animated, accessible loading indicator for asynchronous
+processes, loading states, and feedback. It is flexible, themeable, and
+supports multiple variants, overlay mode, state integration, and accessibility
+integration.
+
+---
+
+## Features
+
+- Animated loading indicator (circle, dots)
+- Size, color, speed, and type through attributes
+- Overlay mode (centered, translucent)
+- Slot for custom content
+- State integration through xstate
+- Events for pause/resume
+- Theming through CSS custom properties and XTheme
+- Accessibility: ARIA, `aria-busy`, `aria-label`, `aria-valuetext`
+- `prefers-reduced-motion` support
+
+---
+
+## Usage
+
+```html
+<x-spinner size="32" color="#C70039" speed="0.7s" type="dots"></x-spinner>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `size` | String | spinner size, for example 32, 48, 64 |
+| `color` | String | color as CSS color value, for example #007bff |
+| `speed` | String | animation duration, for example 1s, 0.7s |
+| `type` | String | `circle` (default), `dots` |
+| `paused` | Boolean | pauses animation |
+| `overlay` | Boolean | shows spinner as page overlay |
+| `aria-label` | String | accessible text for screen readers |
+| `aria-busy` | String | ARIA state (`true`/`false`) |
+| `aria-valuetext` | String | progress text for screen readers |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `spinner-started` | emitted when inserted |
+| `spinner-stopped` | emitted when removed |
+| `paused` | animation was paused |
+| `resumed` | animation was resumed |
+
+---
+
+## API
+
+- **Set size:** `element.setAttribute('size', '48')`
+- **Change type:** `element.setAttribute('type', 'dots')`
+- **Pause/resume:** `element.setAttribute('paused', '')` /
+  `element.removeAttribute('paused')`
+- **Imperative pause/resume:** `element.pause()` / `element.resume()`
+- **Snapshot:** `element.snapshot()`
+- **Enable overlay:** `element.setAttribute('overlay', '')`
+- **State integration:** `xstate.set('xspinner-paused-'+element.id, true)`
+
+## Feedback Status UX from WP-E11-09
+
+`<x-spinner>` exposes `xtendFeedbackStatusUxProfile` with
+`xtend.component.feedback-status-ux-profile.v1`. The profile describes the
+spinner as busy status with `spinner-started`, `spinner-stopped`, `paused`,
+`resumed`, `xspinner-paused-<id>`, `component.visible.mount`, Fabric lane
+`feedback`, a11y lane `a11y`, and RMT shell authoring.
+
+The component reports pause/resume through events with `source: 'x-spinner'`
+and `stateKey`. Animations are reduced-motion safe; busy state and
+`aria-valuetext` remain available to screen readers even without visible
+motion.
+
+---
+
+## Example: Dynamic JS
+
+```js
+const spinner = document.createElement('x-spinner');
+spinner.setAttribute('size', '48');
+spinner.setAttribute('type', 'dots');
+document.body.appendChild(spinner);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-spinner {
+  --spinner-color: #007bff;
+  --spinner-size: 40px;
+}
+```
+
+---
+
+## Accessibility
+
+- ARIA role, `aria-busy`, `aria-label`, `aria-valuetext`
+- respects `prefers-reduced-motion`
+
+---
+
+*Last updated: July 18, 2025*

package/docs/en/components/xstate.md

@@ -0,0 +1,163 @@
+# xstate - XTend Component
+
+> **See also:** [xalert](./xalert.md), [xtoast](./xtoast.md), [xbutton](./xbutton.md), [xtheme](./xtheme.md)
+
+## Overview
+
+`xstate` is the central state management module for XTend components. It
+supports global and local state, subscriptions, and reactive updates.
+
+Since `WP-E12-08`, `xstate` is explicitly documented as a non-visual
+**boundary probe**. The module is not reinterpreted as a Custom Element.
+Instead, it provides a gateable adapter, typing, and lifecycle surface for
+XTend UI, Fabric, and XTendRMT.
+
+---
+
+## Features
+
+- Global and component-based state management
+- Subscriptions for state changes with key filters
+- Reactive updates for components
+- Path updates, batch updates, and storage helpers
+- Compatibility facade for `on/off`
+- Lifecycle events for state operations
+- Fabric-compatible diagnostics snapshots
+- RMT State Scheduler Adapter without kernel coupling
+
+---
+
+## Usage
+
+```js
+import { xstate } from 'components/xstate.js';
+
+xstate.set('key', 'value');
+const value = xstate.get('key');
+const unsubscribe = xstate.subscribe((key, value, allData) => { ... }, 'key');
+```
+
+---
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `get(key)` | returns the value for a key |
+| `set(key, val)` | sets a value and notifies listeners |
+| `subscribe(fn, keyFilter?)` | canonical subscription contract with optional key filter |
+| `remove(key)` | removes a key from state |
+| `getPath(path)` | reads nested values through dot notation |
+| `setPath(path, value)` | writes nested values through dot notation |
+| `batchUpdate(updates)` | applies multiple updates in one step |
+| `saveToStorage(type?, key?)` | persists state to local or session storage |
+| `loadFromStorage(type?, key?)` | loads state from browser storage |
+| `on(key, fn)` | legacy compatibility for key-based listeners |
+| `off(key, fn)` | removes a listener registered through `on` |
+| `subscribeLifecycle(fn)` | subscribes to lifecycle/diagnostics events from the state boundary |
+| `snapshot()` | returns a stable state snapshot for tests and adapters |
+| `snapshotDiagnostics()` | returns Fabric-compatible diagnostics |
+| `createRmtStateAdapter(options?)` | creates a host-neutral RMT state adapter |
+
+---
+
+## Example: Use State in a Component
+
+```js
+xstate.set('user', { name: 'Konni' });
+const unsubscribe = xstate.subscribe((key, value) => {
+  if (key === 'user') {
+    // React to changes
+  }
+});
+```
+
+### Canonical Recommendation
+
+- New core implementations should use `subscribe(fn, keyFilter)`.
+- `on/off` remain allowed as a compatibility facade, but they are not the
+  canonical contract.
+
+---
+
+## Boundary Probe Contract
+
+`xstate` is not a visual element. Component catalog hardening therefore checks
+it as an infrastructure boundary:
+
+- Boundary Schema: `xtend.state.boundary-probe.v1`
+- Snapshot Schema: `xtend.state.snapshot.v1`
+- Lifecycle Schema: `xtend.state.lifecycle-event.v1`
+- Diagnostics Schema: `xtend.fabric.state-diagnostics.v1`
+- RMT Compatibility Schema: `xtend.rmt.state-scheduler-compatibility.v1`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+```js
+import { xstate } from '/components/xstate.js';
+
+const unsubscribeLifecycle = xstate.subscribeLifecycle((event, diagnostics) => {
+  console.log(event.type, diagnostics.operationCounts);
+});
+
+xstate.set('rmt.bridge.ready', true);
+
+const snapshot = xstate.snapshot();
+const diagnostics = xstate.snapshotDiagnostics();
+
+unsubscribeLifecycle();
+```
+
+## RMT State Scheduler Compatibility
+
+RMT must not import `xstate` directly. An XTend host can intentionally create
+an adapter and pass it to the State/Scheduler/Diagnostics Bridge:
+
+```js
+const stateAdapter = xstate.createRmtStateAdapter({
+  schedulerId: 'docs.app.shell'
+});
+
+stateAdapter.set('rmt.scheduler.lastEndpoint', {
+  id: 'docs.header.search',
+  lane: 'user-blocking'
+});
+
+stateAdapter.snapshot();
+stateAdapter.diagnostics();
+```
+
+XTendRMT therefore remains framework-agnostic. `xstate` is an optional host
+capability and not a kernel dependency.
+
+---
+
+## XTendRMT Bridge State
+
+XTendRMT uses `xstate` optionally as a host-state mirror. The
+State/Scheduler/Diagnostics Bridge writes into `xstate` only when a host passes
+a compatible target. Without `xstate`, an in-memory state handle remains
+active.
+
+Current bridge keys:
+
+- `rmt.bridge.ready`
+- `rmt.scheduler.lastEndpoint`
+- `rmt.adapter.lastResult`
+- `rmt.diagnostics.last`
+- `rmt.route.<id>.lastResult`
+- `rmt.component.<id>.lastResult`
+
+The implementation lives in `createRmtStateSchedulerDiagnosticsBridge`; details
+are in [XTendRMT Runtime Bridge](../xtendrmt-runtime-bridge.md).
+
+---
+
+## Notes
+
+- Used by almost all XTend components
+- Can also be used for custom purposes
+- In XTend Core, `xstate` is the first bootstrap base module
+
+---
+
+*Last updated: May 7, 2026*

package/docs/en/components/xstatus.md

@@ -0,0 +1,71 @@
+# xstatus - XTend Component
+
+> **See also:** [xalert](./xalert.md), [xtoast](./xtoast.md), [xprogress](./xprogress.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-status>` is a Fabric- and RMT-capable status control from `WP-E10-10`. It
+renders scheduler, validation, and system feedback as a live region and stays
+small enough to be used in RMT shells as a feedback building block.
+
+## Usage
+
+```html
+<x-status id="route-status" type="warning" state="validating" message="Validation is running" dismissible busy>
+  <span slot="label">Scheduler status</span>
+</x-status>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `type` | String | `info`, `success`, `warning`, or `error` |
+| `state` | String | domain status key |
+| `message` | String | visible message |
+| `dismissible` | Boolean | shows close action |
+| `busy` | Boolean | sets `aria-busy` |
+| `polite` | Boolean | forces polite live region |
+| `label` | String | label without slot |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `status-changed` | `{ type, status, message, busy, source: 'x-status' }` |
+| `status-dismissed` | `{ type, status, message, busy, source: 'x-status' }` |
+
+## API
+
+- `element.state`
+- `element.setStatus(nextState)`
+- `element.announce(message?)`
+- `element.dismiss()`
+
+## State, RMT, and Fabric
+
+`<x-status>` writes to `xstatus-state-<id>`. RMT can schedule status updates to
+`feedback.status.update` through `xtend.rmt.component-contract.v1` without
+importing XTend internally. The kernel boundary remains
+`no-rmt-kernel-import-of-xtend-types`; the UI component is the adapter outward.
+
+## A11y and Performance
+
+The control uses `role="status"` for polite messages and `role=alert` for
+critical warning/error paths. `scheduler-feedback`, `status-update`, and
+`validation-feedback` are documented as screen reader signals. The performance
+profile is `xtend.performance.component-profile.v1` with
+`budgetClass: 'feedback-small'`, `lane: 'feedback'`, and
+`hydrationPolicy: 'visible'`.
+
+## Feedback Status UX from WP-E11-09
+
+`<x-status>` exposes `xtendFeedbackStatusUxProfile` with
+`xtend.component.feedback-status-ux-profile.v1`. The profile connects
+`status-changed`, `status-dismissed`, `xstatus-state-<id>`,
+`feedback.status.update`, Fabric lane `feedback`, a11y lane `a11y`, and RMT
+shell authoring.
+
+The component is the shared inline status for forms, schedulers, route feedback,
+and diagnostics. It avoids color-only communication, remains forced-colors
+safe, and can be explicitly updated as a live region with `announce()`.

package/docs/en/components/xsummary.md

@@ -0,0 +1,90 @@
+# xsummary - XTend Component
+
+## Overview
+
+`<x-summary>` is an expandable disclosure component for compact detail areas.
+It uses native `<details>`/`<summary>` semantics, mirrors its open state into
+`xstate`, and works well for FAQ blocks, technical details, inline help, or
+dashboard summaries.
+
+## Usage
+
+```html
+<x-summary id="billing-details" type="info" open>
+  <span slot="title">Billing details</span>
+  <p>All invoice items are grouped by project and time period.</p>
+</x-summary>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `open` | boolean | opens the detail area |
+| `type` | string | visual variant: `info`, `success`, `warning`, `danger` |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `title` | content of the clickable summary header |
+| default | expandable content |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `open` | emitted when opening |
+| `close` | emitted when closing |
+
+The event detail contains:
+
+```js
+{
+  open: true
+}
+```
+
+## State Contract
+
+The instance uses a compatible `xstate` key:
+
+```js
+xsummary-open-<id>
+```
+
+If no `id` is set, the component creates a stable runtime ID for the current
+instance. External state changes on the key can open or close the component.
+
+Synchronization is reentrant-safe: attributes, native `<details>` state, and
+`xstate` are reconciled through one central open-state routine. Unchanged values
+are not published to `xstate` again, so external state updates do not trigger a
+recursive `open()`/`close()` loop.
+
+## A11y
+
+- The native `<summary>` remains the primary keyboard and screen reader surface.
+- `Enter` and `Space` toggle the state.
+- `aria-expanded` is synchronized with the current open state.
+- The summary header is focusable and has a visible focus state.
+
+## Notes
+
+- `x-summary` is an interactive display component and has been
+  component-suite-gated since `ER-WP-33`.
+- The Catalog Coverage Matrix now lists the component as `contract-gated`.
+- Further contract hardening for performance, browser regression, and
+  long-tail coverage follows in `ER-WP-35`; public types and event details have
+  existed since `ER-WP-34`.
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-summary` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component remains a
+disclosure display shell and uses the state key `xsummary-open-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.visible.mount`
+- Events: `open`, `close`
+- Snapshot: `snapshot()`
+- CSS parts: `container`, `summary`, `content`

package/docs/en/components/xsurfacemanager.md

@@ -0,0 +1,42 @@
+# xsurfacemanager - XTend Component
+
+`x-surface-manager` is the app-shell surface root for multi-window interfaces.
+The component instantiates `xtend.surface.controller.v1`, registers slotted
+`x-surface-window`, `x-side-panel`, and compatible overlay elements, and
+mirrors layout, focus, and lifecycle changes as `xtend.surface.snapshot.v1`.
+
+## Attributes
+
+- `manager-id`: stable manager ID for surface records
+- `state-key`: xstate registry key, defaults to `xtend.surface.registry`
+- `layout`: layout profile for the surface zone
+- `restore-key`: future persistence key for layout restore
+- `route-aware`: marks route-bound surface management
+- `modal-policy`: policy for future modal surface stacks
+
+## Slots
+
+- `windows`: freely positioned windows
+- `panels`: `x-side-panel` surfaces with docked, pinned, overlay, or collapsed modes
+- `overlays`: optional overlay bridge for `x-modal`, `x-dialog`, and `x-drawer`
+- `default`: simple Light DOM fallbacks
+
+## API
+
+`registerSurface(surface)`, `openSurface(id)`, `closeSurface(id)`,
+`focusSurface(id)`, `updateSurface(id, patch)`, `moveSurface(id, bounds)`,
+`resizeSurface(id, bounds)`, `minimizeSurface(id)`, `maximizeSurface(id)`,
+`restoreSurface(id)`, `pinSurface(id)`, `collapseSurface(id)`,
+`expandSurface(id)`, `dockSurface(id)`, and `snapshot()` delegate to the
+Surface Controller.
+
+Events: `surface-manager-ready`, `surface-registered`, `surface-opened`,
+`surface-closed`, `surface-focused`, `surface-updated`,
+`surface-layout-changed`, `surface-window-command`, `surface-panel-command`,
+and `surface-overlay-command`.
+
+RMT: `xtend.rmt.component-contract.v1`, `xtend.surface.manager.v1`,
+`xtend.surface.controller.v1`, `xtend.surface.overlay-stack-bridge.v1`,
+`surface.visible.render`, `surface.user-blocking.open`,
+`surface.user-blocking.close`, `surface.transition.layout`,
+`surface.diagnostics.snapshot`.

package/docs/en/components/xsurfacewindow.md

@@ -0,0 +1,31 @@
+# xsurfacewindow - XTend Component
+
+`x-surface-window` is XTend's first visible WindowManager surface. It registers
+with an enclosing `x-surface-manager`, provides window chrome, actions, bounds,
+and a content slot, and mirrors controller snapshots into attributes and CSS
+variables.
+
+## Attributes
+
+- `surface-id`: stable surface ID
+- `label`: accessible name and window title
+- `open`, `active`, `minimized`, `maximized`
+- `draggable`, `resizable`, `modal`
+- `initial-x`, `initial-y`, `initial-width`, `initial-height`
+
+## API
+
+`toSurfaceRecord(managerId)` creates an `xtend.surface.record.v1` for the
+manager. `applySurfaceSnapshot(record)` updates visible state, bounds, and
+z-order.
+
+Commands: `openWindow()`, `closeWindow(reason)`, `focusWindow()`,
+`minimizeWindow()`, `maximizeWindow()`, and `restoreWindow()`.
+
+The element emits `surface-window-command` with `open`, `close`, `focus`,
+`move`, `resize`, `minimize`, `maximize`, `restore`, or `update`. The manager
+translates these commands into controller operations.
+
+RMT: `xtend.rmt.component-contract.v1`, `xtend.surface.record.v1`,
+`surface.user-blocking.open`, `surface.user-blocking.close`,
+`surface.transition.layout`, `surface.diagnostics.snapshot`.

package/docs/en/components/xtabs.md

@@ -0,0 +1,187 @@
+# xtabs - XTend Component
+
+> **See also:** [xsection](./xsection.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-tabs>` is a component for tab navigation and structured content. It
+supports dynamic tabs, theming, and state integration.
+
+---
+
+## Features
+
+- Dynamic tab navigation
+- Slot for tab content
+- State integration through xstate
+- Theming through CSS custom properties
+
+---
+
+## Usage
+
+```html
+<x-tabs selected="0">
+  <x-tab name="Tab 1">Content 1</x-tab>
+  <x-tab name="Tab 2">Content 2</x-tab>
+</x-tabs>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| - | - | - |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `tab-selected` | tab change with `{ index }`, `bubbles: true`, `composed: true` |
+
+---
+
+## API
+
+- **Insert tabs through slot**
+- **State integration:** automatic through xstate
+
+---
+
+## Example: Dynamic JS
+
+```js
+const tabs = document.createElement('x-tabs');
+tabs.innerHTML = '<div slot="tab" label="A">A</div>';
+document.body.appendChild(tabs);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-tabs {
+  --tab-active-bg: #007bff;
+}
+```
+
+---
+
+## Accessibility
+
+`x-tabs` renders a `role="tablist"` header, creates `role="tab"` for every
+button, and connects buttons and panels through `aria-controls` and
+`aria-labelledby`.
+
+Keyboard navigation uses roving `tabindex`:
+
+| Key | Behavior |
+|-----|----------|
+| `ArrowRight` | next tab |
+| `ArrowLeft` | previous tab |
+| `Home` | first tab |
+| `End` | last tab |
+| `Enter` / `Space` | activate focused tab |
+
+Active panels carry `role="tabpanel"` and `aria-hidden="false"`; inactive
+panels are removed from visible navigation with `hidden` and
+`aria-hidden="true"`.
+
+## Performance Profile from WP-E12-02
+
+`x-tabs` has an explicit `xtendScaffoldPerformanceProfile` under
+`xtend.performance.component-profile.v1`.
+
+| Field | Value |
+|-------|-------|
+| Budget class | `critical` |
+| Lane | `user-blocking` |
+| Hydration policy | `visible` |
+| Tab switch budget | `16 ms` |
+| Keyboard budget | `16 ms` |
+| Render update budget | `28 ms` |
+
+RMT shells can schedule `x-tabs` through `ui.user-blocking.tabs`,
+`route.transition.tab`, `component.visible.hydrate`, and `diagnostics.snapshot`.
+The RMT kernel remains framework-agnostic; XTend-specific data lives in the
+component adapter metadata profile.
+
+The runtime provides `getPerformanceBudget()` and `snapshotPerformance()`.
+`snapshotPerformance()` returns local measurement points for hydration, render,
+tab switch, and keyboard interactions so Fabric or a later reporter can consume
+the data.
+
+## Component-Level Contract from ER-WP-33
+
+- `selected` determines the active tab index.
+- `text-color` synchronizes the text color in the tab header.
+- `tab-selected` is emitted after a tab change with `{ index }`.
+- `xtabs-selected` is the canonical `xstate` key for external tab changes.
+- Keyboard navigation includes `ArrowRight`, `ArrowLeft`, `Home`, `End`,
+  `Enter`, and `Space`.
+- `data-rmt-schedule="ui.user-blocking.tabs"` and
+  `data-xtend-lane="user-blocking"` form the fixture line for RMT/Fabric
+  scheduling.
+- `snapshotPerformance()` makes the WP-E12-02 runtime budget testable.
+- Since `WP-E12-03`, browser smoke and theme matrix explicitly cover `x-tabs`
+  keyboard, ARIA, and theme shell journeys.
+
+---
+
+*Last updated: May 7, 2026*
+
+## ECH-WP-09 Token Table and Navigation States
+
+`signatureDesign`: `x-tabs` creates an independent enterprise tab navigation
+with visible selected rail, wrap-safe labels, and fully replaceable typography.
+Active/current/selected, hover, focus, and disabled states are themeable through
+shared navigation tokens.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-nav-surface` | tablist surface |
+| `--xtend-nav-text` | tab text |
+| `--xtend-nav-border-color` | tab and tablist edges |
+| `--xtend-nav-radius` | tab radius |
+| `--xtend-nav-gap` | spacing between tabs |
+| `--xtend-nav-font-family` | tab typography |
+| `--xtend-nav-font-size` | tab text size |
+| `--xtend-nav-active-surface` | selected surface |
+| `--xtend-nav-active-text` | selected text |
+| `--xtend-nav-current-indicator` | non-color-only selected indicator |
+| `--xtend-nav-hover-surface` | hover surface |
+| `--xtend-nav-focus-ring` | keyboard focus |
+| `--xtend-nav-disabled-opacity` | disabled dimming |
+
+## ECH-WP-09 Keyboard Behavior
+
+`ArrowRight`, `ArrowLeft`, `Home`, `End`, `Enter`, and `Space` remain the
+binding keys. Disabled tabs are not focusable or activatable.
+Active/current/selected is mirrored through `aria-selected="true"` on the tab
+and `role="tabpanel"` on the panel; route tabs may additionally carry
+`aria-current="page"` through host logic.
+
+## ECH-WP-09 External Theme
+
+```css
+[data-xtend-nav-theme="enterprise-foreign"] x-tabs {
+  --xtend-nav-surface: #f3f0e8;
+  --xtend-nav-text: #202520;
+  --xtend-nav-border-color: rgba(32, 37, 32, 0.24);
+  --xtend-nav-radius: 0.35rem;
+  --xtend-nav-gap: 0.4rem;
+  --xtend-nav-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-nav-font-size: 0.95rem;
+  --xtend-nav-active-surface: #243c34;
+  --xtend-nav-active-text: #fff9ed;
+  --xtend-nav-current-indicator: #a65f2d;
+  --xtend-nav-hover-surface: rgba(166, 95, 45, 0.14);
+  --xtend-nav-focus-ring: 3px solid #a65f2d;
+  --xtend-nav-disabled-opacity: 0.42;
+}
+```