@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xradio.md

@@ -0,0 +1,119 @@
+# xradio - XTend Component
+
+> **See also:** [xform](./xform.md), [xinput](./xinput.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-radio>` completes the TypeScript-first selection controls from
+`WP-E10-09`. The component coordinates groups through `name`, supports keyboard
+navigation, and provides RMT, Fabric, a11y, and performance metadata for
+RMT-first apps.
+
+## Usage
+
+```html
+<x-radio id="plan-starter" name="plan" value="starter">
+  <span slot="label">Starter</span>
+</x-radio>
+<x-radio id="plan-pro" name="plan" value="pro" checked>
+  <span slot="label">Pro</span>
+</x-radio>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | String | group and form name |
+| `value` | String | value of the radio control |
+| `checked` | Boolean | current selected state |
+| `required` | Boolean | activates validation |
+| `disabled` | Boolean | disables the control |
+| `label` | String | ARIA/text label without slot |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `label` | visible label |
+| `hint` | additional helper text |
+| `error` | validation error |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `radio-changed` | `{ checked, value, name, source: 'x-radio' }` |
+| `radio-invalid` | `{ checked, value, name, message, source: 'x-radio' }` |
+
+## API
+
+- `element.checked`
+- `element.value`
+- `element.name`
+- `element.check()`
+- `element.checkValidity()`
+- `element.reportValidity()`
+- `element.validate()`
+- `element.reset()`
+- `element.focus()`
+
+## State, RMT, and Fabric
+
+`<x-radio>` writes individual state to `xradio-checked-<id>` and group value to
+`xradio-value-<name>`. RMT metadata uses
+`xtend.rmt.component-contract.v1`; RMT can template a radio group as a DOM
+descriptor and schedule the UI through `xtend.component` without importing
+XTend into the RMT kernel.
+
+## A11y and Performance
+
+The component uses `role="radio"`, `aria-checked`, `aria-describedby`, Space
+activation, and arrow-key navigation within the group. The performance profile
+is `xtend.performance.component-profile.v1` with
+`budgetClass: 'interactive-small'`, `lane: 'user-blocking'`, and
+`hydrationPolicy: 'visible'`.
+
+## Form Controls UX from WP-E11-08
+
+`<x-radio>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects label, hint,
+error, `radio-changed`, `radio-invalid`, `xradio-value-<name>`,
+`ui.user-blocking.input`, Fabric lane `user-blocking`, and RMT shell authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: enterprise radio option with robust native focus handling,
+group-safe validation, and separately themeable selection icon.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-form-text` | host text color |
+| `--xtend-form-control-surface` | native control surface |
+| `--xtend-form-control-text` | control text fallback |
+| `--xtend-form-label-text` | label |
+| `--xtend-form-helper-text` | helper |
+| `--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` | radio/error radius |
+| `--xtend-form-gap` | label/helper spacing |
+| `--xtend-form-font-family` | form typography |
+| `--xtend-form-control-font-size` | label font |
+| `--xtend-form-helper-font-size` | helper/error font |
+| `--xtend-form-icon-color` | radio accent |
+
+Density profiles: `comfortable`, `compact`, `dense`. Invalid state is not
+color-only and is mirrored through `aria-invalid`.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-radio {
+  --xtend-form-icon-color: #8f4f2a;
+  --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;
+}
+```

package/docs/en/components/xrouter.md

@@ -0,0 +1,260 @@
+# xrouter - XTend Component
+
+## Overview
+
+`<x-router>` is the client-side router for XTend SPAs. It processes declarative `<x-route>` definitions, supports hash and history mode, and synchronizes navigation with `xstate`.
+
+## Core Behavior
+
+- only direct `<x-route>` children of `<x-router>` count as top-level routes
+- nested routes are processed only through direct child routes of their parent route
+- navigation can be triggered declaratively, through `x-link` or programmatically via `xstate.set('router-navigate', '/target')`
+
+## Usage
+
+```html
+<x-router mode="history">
+  <x-route path="/" component="x-home" import="/components/xhome.js" title="Home"></x-route>
+  <x-route path="/docs" component="x-docs" import="/components/xdocs.js" title="Docs">
+    <x-route path=":topic" component="x-doc-topic" import="/components/xdoctopic.js" title-template="{{params.topic}} | XTend Docs"></x-route>
+  </x-route>
+  <x-route path="*" component="x-notfound" import="/components/xnotfound.js"></x-route>
+</x-router>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `mode` | string | `hash` or `history` |
+| `routesrc` | string | optional JSON source for routes |
+| `skeleton` | string | enables a native route skeleton fallback during import, definition and hydration |
+| `skeleton-lines` | number | number of skeleton lines for the route fallback |
+| `skeleton-min-height` | string | stable minimum height for the route fallback |
+| `title-template` / `document-title-template` | string | global document-title template, for example `{{title}} | App` |
+| `title-prefix` / `title-suffix` | string | simple prefix/suffix for route titles without a template |
+| `default-title` | string | fallback when a route does not define a title |
+
+## Document Title Rewrite and SEO Meta
+
+After every successful route match, XRouter rewrites the browser title and the SEO meta tags `description` and `keywords`. This prevents an SPA from staying on its initial title, and RMT routes can provide title information without XTend-specific runtime imports.
+
+Direct route attributes:
+
+```html
+<x-router mode="hash" document-title-template="{{title}} | XTend">
+  <x-route
+    path="/components/x-router"
+    component="x-doc-page"
+    title="XRouter"
+    document-title="XRouter Routing and SEO"
+    meta-description="Routing, page titles and RMT route metadata"
+    meta-keywords="xtend, xrouter, rmt">
+  </x-route>
+</x-router>
+```
+
+RMT can provide the same values through route records and `metadata`:
+
+```json
+{
+  "id": "settings",
+  "path": "/settings",
+  "router": "xtend.xrouter",
+  "component": "page.settings",
+  "metadata": {
+    "title": "Settings",
+    "documentTitle": "Settings | XTend App",
+    "metaDescription": "Settings for the XTend RMT app",
+    "seo": {
+      "keywords": ["xtend", "rmt", "routing"]
+    }
+  }
+}
+```
+
+Supported template variables are `{{title}}`, `{{routeTitle}}`, `{{documentTitle}}`, `{{path}}`, `{{routeId}}`, `{{component}}`, `{{params.name}}`, `{{query.name}}` and `{{metadata.name}}`. For nested routes, the leaf route wins so deep links can define their own titles.
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `xrouter-before-navigate` | cancelable, before programmatic router navigation |
+| `route-changed` | emitted after successful navigation |
+| `routechange` | legacy alias for `route-changed` |
+| `xrouter-after-navigate` | legacy window event after rendering a route |
+| `route-announced` | emitted after writing the route live region |
+| `xrouter-skeleton-shown` / `xrouter-skeleton-hidden` | mark the native route-skeleton lifecycle |
+| `xrouter-route-hydrated` | emitted after loader-based hydration of the rendered route subtree |
+| `xrouter-title-updated` | emitted after writing `document.title` and SEO meta tags |
+| `xrouter-scroll-boundary-normalized` | emitted when the router corrects a stale scroll position or a dead zone below the content area after a route change |
+| `xrouter-navigation-overlays-closed` | emitted when the router closes open app-shell overlays such as `x-header` before rendering a route |
+
+## XState Keys
+
+- `router-navigate`: programmatic navigation input
+- `router-navigated`: most recently triggered target path
+- `router-current`: currently rendered route
+- `router-rendered`: most recently rendered route
+- `router-scroll-boundary`: legacy snapshot of the last scroll-boundary check
+- `router-closed-navigation-overlays`: legacy snapshot of navigation overlays closed before route render
+- `xtend.router.current`: canonical route context
+- `xtend.router.announcement`: most recently announced route
+- `xtend.router.documentMeta`: most recently set document title and SEO meta tags
+- `xtend.router.skeleton`: current route-skeleton lifecycle
+- `xtend.router.scrollBoundary`: canonical snapshot of the last scroll-boundary check
+- `xtend.router.closedNavigationOverlays`: canonical snapshot of navigation overlays closed before route render
+
+The canonical mirror paths are maintained as well:
+
+- `xtend.router.lastNavigated`
+- `xtend.router.current`
+- `xtend.router.lastRendered`
+
+## Route Detail
+
+`route-changed` and `xrouter-after-navigate` provide a detail object with:
+
+```js
+{
+  path: '/docs/router',
+  routeId: 'docs-topic',
+  component: 'x-doc-topic',
+  params: { topic: 'router' },
+  query: {},
+  template: 'docs.topic.shell',
+  scheduleRef: 'route.visible.render',
+  title: 'Router',
+  documentTitle: 'Router | XTend Docs',
+  meta: {
+    schema: 'xtend.router.document-meta.v1',
+    scheduleRef: 'route.document.title.rewrite'
+  },
+  metadata: {}
+}
+```
+
+For nested routes, `component` is the leaf route; `params` are merged from the complete match chain.
+
+## Skeleton and Lazy Hydration
+
+XRouter can load route components shell-first:
+
+```html
+<x-router mode="hash" skeleton="article" skeleton-lines="8" skeleton-min-height="20rem">
+  <x-route
+    path="/docs"
+    component="xtend-doc-page"
+    import="/docs/utils/pageloader.js"
+    hydrate-schedule="docs.page.hydrate">
+  </x-route>
+</x-router>
+```
+
+If the component tag is not defined yet, XRouter first uses the route's explicit `import`. If no import is present, it delegates to `window.XTendLoader.ensureComponent(componentTag)`, so manifest components can be lazy-loaded natively through routes. After rendering, XRouter hydrates the route subtree through `window.XTendLoader.hydrateTree(...)`.
+
+## Navigation Routing UX Profile
+
+`<x-router>` provides `xtendNavigationRoutingUxProfile` with `xtend.component.navigation-routing-ux-profile.v1`. The profile describes `x-router` as a router outlet with `route-changed`, `route-announced`, `xrouter-before-navigate`, `xtend.router.current`, `route.visible.render`, `route.focus.restore`, `a11y.announce`, Fabric lane `transition` and RMT shell authoring.
+
+After a successful render, the router focuses its outlet and writes a polite, atomic live region. This lets RMT and Fabric schedule route render, focus restore and screen-reader announcement separately, without requiring the RMT kernel to import XTend internals.
+
+The new diagnostics details include `source: 'x-router'`, `stateKey` and `scheduleRef`, so `x-link`, feedback components and RMT schedulers can share the same route context.
+
+## Scroll Boundary, Overlays and Dead-Zone Protection
+
+Before every successful route render, `<x-router>` closes open navigation overlays that provide the stable component contract `isMenuOpen()` and `toggleMenu(false, options)`. This primarily stabilizes `x-header`: an open menu does not remain a layout factor from the previous page and does not create a dead zone when switching to a shorter route.
+
+After rendering, `<x-router>` sets native scroll restoration to `manual`, scrolls to the top or the given `scroll-to` target, and re-checks document height in microtask, frame and settled-timeout phases. If the browser still holds a stale scroll position from the previous, taller route, or if the current position is beyond the new maximum scroll range, the router normalizes the position and writes a snapshot to `xtend.router.scrollBoundary`.
+
+The snapshot follows `xtend.router.scroll-boundary.v1` and includes `path`, `phase`, `strategy`, `viewportHeight`, `scrollHeight`, `maxScrollTop`, `previousTop`, `normalizedTop`, `normalized` and `deadzoneDetected`. Fabric/RMT diagnostics can therefore make dead zones visible without app-specific scroll hacks.
+
+## RMT / XTendRMT Adapter
+
+Since Epic 05 / `WP-E05-10`, XRouter can consume native RMT routes through the adapter contract `xtend.rmt.xrouter-adapter.v1`.
+
+```js
+const adapter = window.xtend.rmt.createRmtXRouterAdapter({ routerElement });
+adapter.registerRoutes(runtimeRegistry);
+adapter.navigate({ routeId: 'home' }, { mapping });
+```
+
+The stable adapter ID is `xtend.xrouter`. The adapter consumes `routeRegistry.byRouter["xtend.xrouter"]`, maps `RmtRouteRegistryEntry` to XRouter-compatible records and calls `registerRoutes(...)` or `navigate(...)` on the target router.
+
+`<x-router>` provides:
+
+- `registerRoutes(routes, options)`
+- `navigate(to, options)`
+- `reuse-component` as opt-in for InsularHydration for SPA routes whose target uses the same component tag and implements `updateRoute(context)` or `routeChangedCallback(context)`
+
+RMT-relevant route data is preserved as attributes on `<x-route>`:
+
+- `data-rmt-route-id`
+- `data-rmt-router`
+- `data-rmt-template`
+- `data-rmt-schedule`
+- `data-rmt-params`
+- `data-rmt-query`
+- `data-rmt-metadata`
+
+This keeps XRouter a productive adapter for RMT routes without giving it RMT kernel knowledge.
+
+Further details:
+
+- [XTendRMT App DSL Reference](../xtendrmt-app-dsl.md)
+- [XTendRMT Runtime Bridge](../xtendrmt-runtime-bridge.md)
+- [XTendRMT Native Authoring Guide](../xtendrmt-native-authoring.md)
+
+## Notes
+
+- `routesrc` is loaded before the first render.
+- Lazy loading happens through the `import` attribute of each route.
+- Guards (`before-enter`) and lifecycle hooks remain supported.
+- With `reuse-component`, an app shell can keep its route component; XRouter then updates params, query and state and fires `xrouter-route-reused`.
+- RMT schedule refs are forwarded to route details via `data-rmt-schedule`.
+- Scroll-boundary normalization runs centrally in the router and should not be duplicated in app shells.
+- Core router changes should be checked against `node scripts/verify_xtend_core_contracts.js`.
+
+## ECH-WP-09 Token Table and Navigation States
+
+`signatureDesign`: `x-router` is the calm route-outlet base for enterprise shells. The router itself delegates active/current/selected state to `x-link`, `x-menu`, `x-tabs` and `x-header`, but exposes the same navigation-state contract, route announcements and focus restore.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-nav-surface` | optional outlet/route surface |
+| `--xtend-nav-text` | outlet text and inherited navigation color |
+| `--xtend-nav-border-color` | shared navigation edge for route shells |
+| `--xtend-nav-radius` | shared radius preset |
+| `--xtend-nav-gap` | shared navigation spacing |
+| `--xtend-nav-font-family` | inherited navigation typography |
+| `--xtend-nav-font-size` | inherited navigation text size |
+| `--xtend-nav-active-surface` | active/current/selected surface for connected navigation |
+| `--xtend-nav-active-text` | active/current/selected text |
+| `--xtend-nav-current-indicator` | non-color-only current indicator |
+| `--xtend-nav-hover-surface` | hover surface for connected navigation |
+| `--xtend-nav-focus-ring` | route focus and navigation focus |
+| `--xtend-nav-disabled-opacity` | disabled dimming for connected navigation |
+
+## ECH-WP-09 Keyboard Behavior
+
+After rendering, the router focuses the outlet and emits `route-announced` through a polite live region. Link and menu keyboard behavior remains in the respective navigation elements; the router keeps the route context `xtend.router.current`, so active/current/selected can be synchronized through `aria-current="page"` and `aria-selected="true"`.
+
+## ECH-WP-09 Foreign Theme
+
+```css
+[data-xtend-nav-theme="enterprise-foreign"] x-router {
+  --xtend-nav-surface: transparent;
+  --xtend-nav-text: #17231f;
+  --xtend-nav-border-color: rgba(23, 35, 31, 0.22);
+  --xtend-nav-radius: 0.35rem;
+  --xtend-nav-gap: 0.45rem;
+  --xtend-nav-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-nav-font-size: 1rem;
+  --xtend-nav-active-surface: #173f35;
+  --xtend-nav-active-text: #fffaf0;
+  --xtend-nav-current-indicator: #b56b35;
+  --xtend-nav-hover-surface: rgba(181, 107, 53, 0.14);
+  --xtend-nav-focus-ring: 3px solid #b56b35;
+  --xtend-nav-disabled-opacity: 0.44;
+}
+```

package/docs/en/components/xsection.md

@@ -0,0 +1,136 @@
+# xsection - XTend Component
+
+> **See also:** [xhero](./xhero.md), [xmasonry](./xmasonry.md)
+
+## Overview
+
+`<x-section>` is a flexible layout component for page sections, containers, and
+structured areas. It supports slots, theming, and responsive design.
+
+---
+
+## Features
+
+- Container for arbitrary content
+- Slots for flexible structure
+- Theming through CSS custom properties
+- Responsive design
+
+---
+
+## Usage
+
+```html
+<x-section>
+  <h2>Section</h2>
+  <p>Content...</p>
+</x-section>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `variant` | String | layout variant, for example primary, secondary |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| - | - |
+
+---
+
+## API
+
+- **Set variant:** `element.setAttribute('variant', 'primary')`
+
+---
+
+## Example: Dynamic JS
+
+```js
+const section = document.createElement('x-section');
+section.setAttribute('variant', 'primary');
+document.body.appendChild(section);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-section {
+  --section-bg: #f9f9f9;
+  --section-color: #222;
+}
+```
+
+---
+
+## Accessibility
+
+- Semantic HTML
+
+---
+
+*Last updated: July 16, 2025*
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-section` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component is suitable
+as a shell-first layout surface for RMT and uses the state key
+`xsection-state-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `layout.measure`
+- Event: `section-rendered`
+- Snapshot: `snapshot()`
+- CSS parts: `root`, `container`, `header`, `aside`, `content`, `footer`
+
+## ECH-WP-07 Token Table and signatureDesign
+
+`signatureDesign`: editorial enterprise section with controlled surface
+hierarchy, optional edge, and overflow-safe content lanes. It can be plain,
+framed, or a dense dashboard layout without requiring new attributes.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-layout-surface` | section surface |
+| `--xtend-layout-text` | main text color |
+| `--xtend-layout-border-color` | optional section edge |
+| `--xtend-layout-radius` | section radius |
+| `--xtend-layout-elevation` | optional section shadow |
+| `--xtend-layout-spacing` | section and content padding |
+| `--xtend-layout-gap` | slot spacing |
+| `--xtend-layout-font-family` | section typography |
+| `--xtend-layout-font-size` | content font size |
+| `--xtend-layout-media-radius` | media radius for slotted content |
+| `--xtend-layout-focus-ring` | focus inside the section |
+| `--xtend-layout-grid-min` | responsive content base |
+| `--xtend-layout-content-max` | section max width |
+
+## ECH-WP-07 External Theme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-section {
+  --xtend-layout-surface: #fffaf2;
+  --xtend-layout-text: #1d2722;
+  --xtend-layout-border-color: rgba(29, 39, 34, 0.18);
+  --xtend-layout-radius: 0.4rem;
+  --xtend-layout-elevation: none;
+  --xtend-layout-spacing: 1.6rem;
+  --xtend-layout-gap: 1.2rem;
+  --xtend-layout-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-layout-font-size: 1rem;
+  --xtend-layout-media-radius: 0.35rem;
+  --xtend-layout-focus-ring: 3px solid #8f4f2a;
+  --xtend-layout-grid-min: minmax(14rem, 1fr);
+  --xtend-layout-content-max: 76rem;
+}
+```

package/docs/en/components/xselect.md

@@ -0,0 +1,122 @@
+# xselect - XTend Component
+
+> **See also:** [xform](./xform.md), [xinput](./xinput.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-select>` is the TypeScript-first selection control from `WP-E10-09`. The
+component wraps a native `select`, remains form-associated, writes its value to
+`xstate`, and carries RMT, Fabric, a11y, and performance metadata without
+embedding XTend in the RMT kernel.
+
+## Usage
+
+```html
+<x-select id="plan-select" name="plan" value="pro" required>
+  <span slot="label">Plan</span>
+  <option value="starter">Starter</option>
+  <option value="pro">Pro</option>
+  <span slot="error">Please choose a plan.</span>
+</x-select>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | String | form name |
+| `value` | String | current value |
+| `multiple` | Boolean | allows multiple selection |
+| `required` | Boolean | activates native validation |
+| `disabled` | Boolean | disables the control |
+| `placeholder` | String | optional placeholder option |
+| `label` | String | ARIA/text label without slot |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| default | `option` elements for the native select |
+| `label` | visible label |
+| `hint` | additional helper text |
+| `error` | validation error |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `select-changed` | `{ value, values, source: 'x-select' }` |
+| `select-invalid` | `{ value, message, source: 'x-select' }` |
+
+## API
+
+- `element.value`
+- `element.values`
+- `element.checkValidity()`
+- `element.reportValidity()`
+- `element.validate()`
+- `element.reset()`
+- `element.focus()`
+
+## State, RMT, and Fabric
+
+`<x-select>` writes to `xselect-value-<id>` and reacts to external value
+updates. RMT metadata uses `xtend.rmt.component-contract.v1`,
+`adapter: 'xtend.component'`, and
+`kernelBoundary: 'no-rmt-kernel-import-of-xtend-types'`. Shell-first templates
+can schedule the component as a DOM descriptor while XTend remains the UI
+surface.
+
+## A11y and Performance
+
+The control uses `role="combobox"`, `aria-describedby`, visible label/hint/error
+slots, 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-select>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects label, hint,
+error, `select-changed`, `select-invalid`, `xselect-value-<id>`,
+`ui.user-blocking.input`, Fabric lane `user-blocking`, and RMT shell authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: enterprise select with clear native affordance,
+non-color-only validation, and density-safe label/helper rhythm.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-form-text` | host text color |
+| `--xtend-form-control-surface` | select surface |
+| `--xtend-form-control-text` | select text |
+| `--xtend-form-label-text` | label |
+| `--xtend-form-helper-text` | helper |
+| `--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` | select and error radius |
+| `--xtend-form-gap` | vertical rhythm |
+| `--xtend-form-font-family` | form typography |
+| `--xtend-form-control-font-size` | select font |
+| `--xtend-form-helper-font-size` | helper/error font |
+| `--xtend-form-icon-color` | native select affordance |
+
+Density profiles: `comfortable`, `compact`, `dense`. Invalid, `disabled`,
+`required`, and `busy` are mirrored visually and through ARIA.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-select {
+  --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/xsidepanel.md

@@ -0,0 +1,48 @@
+# xsidepanel - XTend Component
+
+`x-side-panel` is XTend's app-shell-adjacent side-panel surface. It registers
+with an enclosing `x-surface-manager`, uses the Surface Controller from
+`WP-SM-02`, and mirrors snapshots into placement, mode, pinning, collapsed
+state, size, and z-order.
+
+## Attributes
+
+- `surface-id`: stable surface ID
+- `label`: accessible name and panel title
+- `open`, `active`, `collapsed`, `pinned`
+- `placement`: `left`, `right`, `bottom`, or `inline`
+- `mode`: `docked`, `overlay`, `pinned`, `collapsed`, or `fullscreen`
+- `responsive-mode`: default `fullscreen-under-720`
+- `resizable`, `route-aware`, `modal`
+- `initial-width`, `initial-height`
+
+## API
+
+`toSurfaceRecord(managerId)` creates an `xtend.surface.record.v1` with
+`type: "side-panel"`. `applySurfaceSnapshot(record)` updates visible state,
+bounds, placement, mode, and a11y state.
+
+Commands: `openPanel()`, `closePanel(reason)`, `focusPanel()`, `pinPanel()`,
+`collapsePanel()`, `expandPanel(mode)`, `setPanelMode(mode, placement)`,
+`resizePanel(bounds)`, and `restorePanel()`.
+
+The element emits `surface-panel-command` with `open`, `close`, `focus`,
+`resize`, `pin`, `unpin`, `collapse`, `expand`, `dock`, `restore`, or
+`update`. The manager translates these commands into controller operations or
+`updateSurface`.
+
+RMT: `xtend.rmt.component-contract.v1`, `xtend.surface.record.v1`,
+`surface.visible.render`, `surface.user-blocking.open`,
+`surface.user-blocking.close`, `surface.transition.layout`,
+`surface.diagnostics.snapshot`.
+
+## ECH-WP-06 Overlay Parity
+
+`x-side-panel` exposes `surface`, `backdrop`, `close`, and `content` as shared
+overlay parts. The previous `scrim` part remains as an alias for `backdrop`.
+Surface, text, border, elevation, backdrop, z-index, and focus ring use
+`--xtend-overlay-*` and component-local `--side-panel-*` tokens.
+
+`mode="docked"` and `mode="pinned"` remain non-modal and app-shell-adjacent.
+`mode="overlay"` or `modal` activates the backdrop and overlay controls for
+SurfaceManager orchestration.