@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/component-ux-app-authoring.md

@@ -0,0 +1,118 @@
+# Component UX App Authoring
+
+Docs Contract: `xtend.docs.component-ux-app-authoring.v1`
+
+This guide is for app authors who use XTend components in RMT-first apps. The app can be written completely in RMT vNext; XTend provides local Web Components and XTendRMT orchestrates shell, routes, templates, schedules and diagnostics.
+
+## Ground Rules
+
+- The app shell renders `shell-first`.
+- XTend components are described in vNext as `surface ... component x-*` and compiled into `xtend.component` records.
+- XRouter is connected through the router adapter.
+- Templates preferably use `dom_descriptor` as generated output.
+- Events are bound with `on ... -> action ...`.
+- Hydration, Fabric lane, fiber and diagnostics remain schedulable metadata.
+- The RMT kernel imports no XTend classes or XTend types.
+
+Boundary:
+
+```text
+no-rmt-kernel-import-of-xtend-types
+```
+
+## Minimal Component Surface
+
+```rmt
+template settings.feedback {
+  state settings.feedback.status type string initial "ready"
+
+  selector settings.feedback.view from state settings.feedback.status {
+    output StatusView
+  }
+
+  portal surface.root root "#settings-root" layer surface
+
+  surface settings.feedback.status kind card component x-status {
+    source selector settings.feedback.view
+    portal surface.root
+
+    lane visible weight 80 {
+      mount x-status
+      hydrate feedback-status from selector settings.feedback.view
+    }
+  }
+}
+```
+
+The output still contains `xtend.component`, accessibility, style, schedule and Fabric metadata. The source you write is the vNext source.
+
+## App Shell Pattern
+
+```rmt
+template dashboard.app {
+  state dashboard.theme type string initial "dark"
+  state dashboard.density type string initial "compact"
+  state dashboard.motion type string initial "reduced-motion"
+
+  action dashboard.refresh {
+    emit dashboard.refresh.requested with action dashboard.refresh
+  }
+
+  portal surface.root root "#app-root" layer surface
+
+  surface dashboard.page kind page component x-section {
+    source state dashboard.theme
+    portal surface.root
+
+    lane visible weight 80 {
+      hydrate dashboard-shell from endpoint xtendrmt.route.render
+      hydrate settings-feedback-status from endpoint xtendrmt.component.mount
+    }
+
+    on click target refresh-button -> action dashboard.refresh {
+      payload theme from state.dashboard.theme
+      payload density from state.dashboard.density
+      payload motion from state.dashboard.motion
+    }
+  }
+}
+```
+
+## UX Rules for Apps
+
+| Dimension | App Rule |
+| --- | --- |
+| Shell | Host page provides only the root, loader, manifest and RMT runtime |
+| Routing | Routes come from RMT and are activated through XRouter |
+| Theme | `light`, `dark`, `high-contrast` and `forced-colors` remain app states |
+| Motion | `reduced-motion` must be visible all the way into overlays, feedback and media |
+| Density | `comfortable`, `compact` and `dense` must not break layout |
+| A11y | Route announcements, live regions, error regions and focus restore are part of the app |
+| Performance | Hydration policies and Fabric lanes are schedule data, not host-specific logic |
+
+## Gates for App Authors
+
+```bash
+node scripts/run_xtend_tests.js rmt-first-class-app --json
+node scripts/run_xtend_tests.js rmt-shell-authoring-ux --json
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+node scripts/run_xtend_tests.js browser --json
+```
+
+For PRs, the shared fast path is:
+
+```bash
+npm run test:pr
+```
+
+## When an App Path Is Ready
+
+An RMT-first XTend app path is considered ready when:
+
+- the shell is not assembled manually from static XTend markup,
+- components come through `xtend.component` records,
+- route, theme, motion, density and hydration are visible in RMT,
+- browser smokes cover the core journeys,
+- the Component Shell Theme Matrix does not break,
+- no external CDN or import-map dependencies are introduced.

package/docs/en/component-ux-authoring.md

@@ -0,0 +1,96 @@
+# Component UX Authoring
+
+Docs contract: `xtend.docs.component-ux-authoring.v1`
+
+This guide is the canonical working guide for XTend component authors after `WP-E11-16`. It turns the Epic 11 contracts into concrete rules for new and modernized web components.
+
+## Principle
+
+An XTend component is UX-ready only when its visible shell, styling, a11y, performance, component network, RMT authorability and browser-close smokes fit together. Individual components may stay small, but their contracts must be complete.
+
+The technical boundary remains:
+
+```text
+no-rmt-kernel-import-of-xtend-types
+```
+
+RMT may schedule, render and configure XTend components. The RMT kernel, however, imports no XTend classes or XTend types.
+
+## Required Contracts
+
+| Contract | Purpose | Gate |
+| --- | --- | --- |
+| `xtend.component.shell.v1` | root, DOM mode, states, slots, parts, focus and lifecycle | `component-shell-contract` |
+| `xtend.component.styling.v1` | tokens, CSS parts, variants, size, density and theme bridges | `component-styling-contract` |
+| `xtend.component.runtime-a11y.v1` | keyboard, focus, ARIA, screenreader and high contrast | `runtime-a11y-contract` |
+| `xtend.component.ux-performance.v1` | shell, hydration, render, event and interaction budgets | `component-ux-performance` |
+| `xtend.component.network.v1` | events, commands, form association, router context and feedback | `component-network-contract` |
+| `xtend.rmt.shell-authoring.v1` | shell, style, a11y, variants, commands and events in RMT | `rmt-shell-authoring-ux` |
+| `xtend.epic11.component-lab-ux-inspector.v1` | preview, RMT inspector, state, a11y, performance and source links | `component-lab-ux-inspector` |
+| `xtend.epic11.component-ux-browser-smokes.v1` | real UX journeys for prioritized families | `component-ux-browser-smokes` |
+| `xtend.epic11.component-shell-theme-matrix.v1` | theme, motion, density, viewport and visual states | `component-shell-theme-matrix` |
+
+## Authoring Order
+
+1. Choose a family: `form-controls`, `feedback-status`, `navigation-routing`, `overlay-interaction` or `layout-display-media`.
+2. Define the shell contract: root, slots, states, parts, focus and lifecycle.
+3. Treat styling as API: document tokens, parts, variants, size and density.
+4. Model a11y first: define keyboard, labels, ARIA, live regions, focus restore and screenreader signals.
+5. Set the performance profile: lane, hydration policy, critical measurement points and budget class.
+6. Describe the component network: define events, commands, form association, router context or feedback channels.
+7. Add RMT authoring: maintain `xtend.component` record, `dom_descriptor`, schedules, commands and events.
+8. Accept Fabric context: ingest lane, fiber and telemetry through adapter data.
+9. Make Component Lab visible: link preview, docs, types, fixture, state, a11y and performance.
+10. Check browser and theme matrix: run local smokes and shell matrix.
+
+## Family Rules
+
+| Family | Minimum |
+| --- | --- |
+| Form controls | label, help text, error region, required/invalid, form association, value event, keyboard entry |
+| Feedback/status | live region, role, tone, dismiss/timeout, non-color status, reduced motion |
+| Navigation/routing | active state, `aria-current`, keyboard activation, route announcement, focus restore, tablist ARIA and roving `tabindex` |
+| Overlay/interaction | initial focus, focus trap, Escape, focus restore, scroll lock, reduced motion |
+| Layout/display/media | responsive slots, stable layout, lazy/visible hydration, media shell, code/display semantics |
+
+## Theme Matrix
+
+Every prioritized shell must remain representable in the Component Shell Theme Matrix:
+
+- Themes: `light`, `dark`, `high-contrast`, `forced-colors`
+- Motion: `default-motion`, `reduced-motion`
+- Density: `comfortable`, `compact`, `dense`
+- Viewports: `desktop-1280`, `tablet-768`, `mobile-390`
+
+The gate currently checks `360` shell combinations:
+
+Since `WP-E12-03`, `x-tabs` is part of the navigation/routing matrix and must preserve arrow key, `Home`, `End`, `aria-controls`, `role=tabpanel`, `aria-selected` and visible focus in browser smokes and theme matrix.
+
+```bash
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+```
+
+## Local Gates
+
+```bash
+node scripts/run_xtend_tests.js component-shell-contract --json
+node scripts/run_xtend_tests.js component-styling-contract --json
+node scripts/run_xtend_tests.js runtime-a11y-contract --json
+node scripts/run_xtend_tests.js component-ux-performance --json
+node scripts/run_xtend_tests.js component-network-contract --json
+node scripts/run_xtend_tests.js rmt-shell-authoring-ux --json
+node scripts/run_xtend_tests.js component-lab-ux-inspector --json
+node scripts/run_xtend_tests.js component-ux-browser-smokes --json
+node scripts/run_xtend_tests.js component-shell-theme-matrix --json
+node scripts/run_xtend_tests.js references --json
+```
+
+## Definition of Done
+
+- Docs, `.d.ts`, fixture, component suite and RMT metadata exist.
+- Shell, styling, a11y, performance and network contracts are visible.
+- Events are `bubbles: true` and `composed: true` when hosts or RMT should consume them.
+- Commands are declarable and not only private methods.
+- Theme, density and motion are not hard-hidden in Shadow DOM.
+- Browser smoke or theme matrix covers the relevant visible path.
+- No new path introduces a hard XTend dependency into the RMT kernel.

package/docs/en/component-ux-gates.md

@@ -0,0 +1,45 @@
+# Component UX Gates
+
+Docs contract: `xtend.docs.component-ux-gates.v1`
+
+This page describes the local gate chain for Epic 11. It connects authoring guides, browser smokes, theme matrix, RMT shell authoring, Component Lab and reference gates.
+
+## Gate Groups
+
+| Group | Gate | Purpose |
+| --- | --- | --- |
+| Foundation | `component-shell-contract` | Component Shell Contract `xtend.component.shell.v1` |
+| Foundation | `component-styling-contract` | Styling Contract `xtend.component.styling.v1` |
+| Foundation | `runtime-a11y-contract` | Runtime A11y `xtend.component.runtime-a11y.v1` |
+| Foundation | `component-ux-performance` | Performance Profile `xtend.component.ux-performance.v1` |
+| Foundation | `component-network-contract` | Component Network `xtend.component.network.v1` |
+| RMT | `rmt-shell-authoring-ux` | RMT Shell Authoring `xtend.rmt.shell-authoring.v1` |
+| Lab | `component-lab-ux-inspector` | Component Lab UX Inspector `xtend.epic11.component-lab-ux-inspector.v1` |
+| Browser | `component-ux-browser-smokes` | Browser UX Smokes `xtend.epic11.component-ux-browser-smokes.v1` |
+| Visual | `component-shell-theme-matrix` | Component Shell Theme Matrix `xtend.epic11.component-shell-theme-matrix.v1` |
+| Docs | `component-ux-authoring-docs` | Component UX Authoring Docs `xtend.epic11.component-ux-authoring-docs.v1` |
+| Migration | `component-long-tail-migration` | Legacy Long-Tail Migration `xtend.epic11.legacy-long-tail-migration.v1` |
+| Handoff | `epic11-enterprise-ux-handoff` | Epic 11 Enterprise UX Handoff `xtend.epic11.enterprise-ux-handoff.v1` |
+| References | `references` | Documentation and demo reference paths |
+
+## Quick Epic 11 Check
+
+```bash
+node scripts/run_xtend_tests.js component-network-contract rmt-shell-authoring-ux form-controls-ux feedback-status-ux navigation-routing-ux overlay-interaction-ux layout-display-media-ux component-lab-ux-inspector component-ux-browser-smokes component-shell-theme-matrix component-ux-authoring-docs component-long-tail-migration epic11-enterprise-ux-handoff references --json
+```
+
+## PR Gate
+
+The PR gate includes the Component UX docs so new guides do not drift away from the productive gate chain:
+
+```bash
+npm run test:pr
+```
+
+## Release Note
+
+`component-shell-theme-matrix` is not a screenshot diff runner yet. It is the deterministic local contract for later visual snapshot automation. Until real snapshots are connected, this matrix remains the binding source for theme, motion, density and viewport obligations.
+
+## Handoff
+
+After `WP-E11-18`, Epic 11 is complete in `completed-with-accepted-long-tail-handoff` mode. The legacy long-tail migration is gateable as a plan; open implementations intentionally remain prioritized in waves.

package/docs/en/components/x-rmt-lifecycle-demo-build.md

@@ -0,0 +1,75 @@
+# x-rmt-lifecycle-demo-build - XTend Component
+
+## Overview
+
+`<x-rmt-lifecycle-demo-build>` is the RC1 test-build component generated from
+`xtendrmt/rmt-lifecycle-demo.rmt`. It serves as local, manifested evidence for
+the RMT vNext app build path and combines root lifecycle, template extension,
+scheduler handshake, a11y profile, and performance profile in one Custom
+Element.
+
+## Usage
+
+```html
+<x-rmt-lifecycle-demo-build
+  variant="rc1"
+  aria-label="RMT Lifecycle Demo Build">
+  Lifecycle Demo
+</x-rmt-lifecycle-demo-build>
+<script type="module" src="/components/x-rmt-lifecycle-demo-build.js"></script>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `variant` | String | marks the local demo variant for fixtures and browser smokes |
+| `aria-label` | String | required name for the semantic `region` in Shadow DOM |
+
+## Scaffold Contracts
+
+The generated component exposes these static contracts:
+
+- `xtendScaffoldWiring` with `xtend.scaffold.feature-wiring.v1`
+- `xtendScaffoldExtensionPoints` with
+  `xtend.scaffold.component-extension-points.v1`
+- `xtendScaffoldA11yProfile` with `xtend.a11y.profile.v1`
+- `xtendScaffoldPerformanceProfile` with
+  `xtend.performance.component-profile.v1`
+
+The root lifecycle uses `xtend.rmt.root-handshake.v1` and stays connected to
+the XTend host adapter through scheduler endpoint hints. The RMT kernel does
+not read the XTend component directly; it treats component refs, templates, and
+events as data.
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `rmt-lifecycle-demo-build-ready` | ready channel declared in scaffold wiring for host adapters |
+| `rmt-lifecycle-demo-build-changed` | state-change channel declared in scaffold wiring for host adapters |
+
+## A11y Profile
+
+The a11y profile sets `role="region"`, requires an `aria-label`, describes
+screen reader signals for semantic region and status changes, and carries
+reduced-motion/forced-colors rules in Shadow DOM.
+
+## Performance Profile
+
+The performance profile uses `xtend.performance.component-profile.v1`,
+`budgetClass: critical`, `lane: user-blocking`, and
+`hydrationPolicy: visible`. Critical measurement points are loader, mount,
+hydration, render, update, state sync, and event action.
+
+## RC1 Build Boundary
+
+The component is intentionally a build artifact from the RMT vNext path:
+
+- Source: `xtendrmt/rmt-lifecycle-demo.rmt`
+- Generator: `xtend-builder/generators/rmt-build.js`
+- Build component: `components/x-rmt-lifecycle-demo-build.js`
+- Browser smoke: `tests/browser/fixtures/rmt-lifecycle-demo-rmt-build-smoke.html`
+
+It is therefore part of RC1 test-build recovery: manifest, docs, suite,
+fixture, and public types remain visible in the Component Catalog.

package/docs/en/components/xalert.md

@@ -0,0 +1,94 @@
+# xalert - XTend Component
+
+## Overview
+
+`<x-alert>` is the prominent feedback component for longer-lived notices,
+warnings, and errors. Unlike toasts, an alert can be blocking or explicitly
+closable.
+
+## Usage
+
+```html
+<x-alert type="error" closable overlay aria-label="Error notice">
+  An error occurred
+</x-alert>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `type` | string | `info`, `success`, `warning`, `error` |
+| `closable` | boolean | shows a close button |
+| `duration` | number | optional auto-close duration |
+| `overlay` | boolean | shows the alert as a centered overlay |
+| `aria-label` | string | screen reader label |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `alert-shown` | after the alert is shown |
+| `alert-dismissed` | after the alert is closed |
+
+## State Contract
+
+The instance mirrors its state compatibly into `xstate`:
+
+- `xtend.component.x-alert.<id>`
+- `xalert-state-<id>`
+
+The event detail includes:
+
+```js
+{
+  id: 'alert-abc123',
+  type: 'error',
+  closable: true,
+  overlay: true,
+  dismissed: false,
+  reason: 'connected'
+}
+```
+
+## Runtime Contract
+
+- API-managed alerts are aggregated in `xstate.get('ui').alerts`.
+- The instance itself exposes its lifecycle through `alert-shown` and
+  `alert-dismissed`.
+- API and component no longer maintain separate close paths.
+
+## Feedback Status UX from WP-E11-09
+
+`<x-alert>` exposes `xtendFeedbackStatusUxProfile` with
+`xtend.component.feedback-status-ux-profile.v1`. The profile describes
+`x-alert` as a longer-lived feedback shell with `alert-shown`,
+`alert-dismissed`, `xalert-state-<id>`, `a11y.announce`, Fabric lane `a11y`,
+and RMT shell authoring.
+
+Errors and warnings use assertive live regions; neutral and success notices
+remain polite. Event details include `source: 'x-alert'` and `stateKey`, so
+form, router, or RMT adapters can schedule and diagnose alerts consistently.
+
+## Contrast Colors
+
+`<x-alert>` uses solid contrast colors without gradients. The variants `info`,
+`success`, `warning`, and `error` each set dedicated tokens for background,
+text, border, and accent so alerts remain readable in light and dark mode while
+preserving their signal value.
+
+The most important theme tokens are:
+
+- `--xtend-alert-info-bg`, `--xtend-alert-info-fg`, `--xtend-alert-info-border`, `--xtend-alert-info-accent`
+- `--xtend-alert-success-bg`, `--xtend-alert-success-fg`, `--xtend-alert-success-border`, `--xtend-alert-success-accent`
+- `--xtend-alert-warning-bg`, `--xtend-alert-warning-fg`, `--xtend-alert-warning-border`, `--xtend-alert-warning-accent`
+- `--xtend-alert-error-bg`, `--xtend-alert-error-fg`, `--xtend-alert-error-border`, `--xtend-alert-error-accent`
+
+For dark mode, the same tokens can be overridden with the `-dark` suffix, for
+example `--xtend-alert-error-bg-dark`.
+
+## Notes
+
+- Alerts are intended for more important, longer-lived, or blocking feedback.
+- `window.XAlert.show()` is the preferred entry point for API-managed alerts.
+- For short, non-blocking notices, `x-toast` is the better component.

package/docs/en/components/xbutton.md

@@ -0,0 +1,118 @@
+# xbutton - XTend Component
+
+> **See also:** [xalert](./xalert.md), [xstate](./xstate.md), [xtheme](./xtheme.md)
+
+## Overview
+
+`<x-button>` is the interactive base button for XTend apps. The component
+provides variants, sizes, loading state, decorative icons, focus-visible
+styles, reduced-motion/forced-colors paths, and, since `WP-E12-06`, an explicit
+performance and interaction budget.
+
+## Features
+
+- Variants: `primary`, `secondary`, `danger`
+- Sizes: `small`, normal, `large`
+- Loading state through `loading` and `aria-busy`
+- Disabled/busy guards for click and keyboard activation
+- Touch target token `--xtend-button-min-touch-target`
+- State integration through `xbutton-state-<id>`
+- Fabric-compatible events `button-interaction` and
+  `button-performance-measured`
+- Slot fallback remains intact so late content such as `x-icon` hydrates cleanly
+
+## Usage
+
+```html
+<x-button variant="primary" size="large" icon="/icons/save.svg">Save</x-button>
+<x-button loading aria-label="Saving">Please wait...</x-button>
+<x-button aria-label="Switch theme"><x-icon name="sun" decorative></x-icon></x-button>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `disabled` | Boolean | disables interaction and sets `aria-disabled` |
+| `label` | String | fallback text when no slot content exists |
+| `variant` | String | `primary`, `secondary`, `danger`, or custom class |
+| `size` | String | `small`, normal, or `large` |
+| `icon` | String | SVG string or icon URL |
+| `loading` | Boolean | shows spinner, blocks interaction, and sets busy state |
+| `aria-label` | String | accessible name for screen readers |
+| `aria-busy` | Boolean | explicit busy state without requiring a loading spinner |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `click` | forwarded click from the internal button shell |
+| `focus` / `blur` | forwarded focus events |
+| `loading-start` | `loading` was activated |
+| `loading-end` | `loading` was deactivated |
+| `button-interaction` | Fabric-compatible interaction measurement for click/keyboard |
+| `button-performance-measured` | performance measurement after hydration, update, or interaction |
+
+## API
+
+| Method | Purpose |
+|--------|---------|
+| `setLoading(loading, options?)` | toggles loading state programmatically |
+| `getPerformanceBudget()` | returns the millisecond budgets of the performance profile |
+| `getInteractionBudget()` | returns click, keyboard, busy, and touch-target budgets |
+| `snapshotPerformance()` | returns the current `xtend.component.performance-snapshot.v1` snapshot |
+
+## Performance Profile
+
+`x-button` has the runtime profile `xtend.performance.component-profile.v1`:
+
+- `budgetClass`: `interactive-small`
+- `lane`: `user-blocking`
+- `hydrationPolicy`: `visible`
+- `criticalMeasurements`: `xtend.component.hydrate`, `xtend.component.render`,
+  `xtend.component.update`, `xtend.event.handler`,
+  `xtend.interaction.click`, `xtend.interaction.keyboard`
+- `budgetsMs`: `hydrate`, `renderUpdate`, `eventAction`, `keyboardAction`,
+  `busyToggle`, `stateSync`
+
+Fabric, regression gates, and later RMT shells can therefore schedule the
+button as a small user-blocking interaction.
+
+## RMT and Fabric
+
+The component declares `xtendRmtMetadata` with `adapter: 'xtend.component'`,
+`templateMode: 'dom_descriptor'`, `eventBindingMode:
+'dom-event-to-rmt-command'`, and the boundary
+`no-rmt-kernel-import-of-xtend-types`. RMT can author and schedule the button
+without importing XTend types into the kernel.
+
+Fabric consumes:
+
+- `button-interaction`
+- `button-performance-measured`
+- `snapshotPerformance()`
+- State key `xbutton-state-<id>`
+
+## Styling and Theming
+
+```css
+x-button {
+  --primary-color: #007bff;
+  --focus-color: #80bfff;
+  --xtend-button-min-touch-target: 44px;
+}
+```
+
+The button respects `prefers-reduced-motion` and `forced-colors`. In
+forced-colors mode it uses system colors, visible focus, and a textual busy
+signal.
+
+## Accessibility
+
+- native button in Shadow DOM with `role="button"`
+- visible `:focus-visible` state
+- `aria-disabled` and `aria-busy`
+- decorative icons with empty `alt`
+- minimum touch target through token
+- keyboard activation through native button semantics plus measurement point
+  for `Enter` and `Space`

package/docs/en/components/xcalendar.md

@@ -0,0 +1,95 @@
+# xcalendar - XTend Component
+
+> **See also:** [xcards](./xcards.md), [xform](./xform.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-calendar>` is a modern, accessible calendar with form integration, state
+management, and theming. It is suitable for date selection and appointment
+management.
+
+---
+
+## Features
+
+- Form-associated (HTML5 Form API)
+- State integration through xstate
+- Theming through CSS custom properties
+- Responsive design
+
+---
+
+## Usage
+
+```html
+<x-calendar></x-calendar>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `value` | String | selected date in ISO format |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | emitted when a date is selected |
+| `date-select` | current XTend contract for date selection, detail: `{ value, date }` |
+
+---
+
+## API
+
+- **Set/read value:** `element.value = '2025-07-16'`
+- **State integration:** automatic through xstate
+
+## Component-Level Contract from ER-WP-33
+
+`<x-calendar>` is form-associated, writes selection and view date to
+`xcalendar-state-<id>`, and renders the month view as an ARIA grid. Day cells
+use `role="gridcell"` and `aria-selected`; month navigation is exposed through
+labeled buttons.
+
+## Form Controls UX from WP-E11-08
+
+`<x-calendar>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects date
+selection, `date-select`, `xcalendar-state-<id>`, `ui.user-blocking.input`,
+grid a11y, Fabric lane `user-blocking`, and RMT shell authoring.
+
+---
+
+## Example: Dynamic JS
+
+```js
+const cal = document.createElement('x-calendar');
+cal.value = '2025-07-16';
+document.body.appendChild(cal);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-calendar {
+  --border-color: #ccc;
+  --background-color: #fff;
+}
+```
+
+---
+
+## Accessibility
+
+- ARIA roles, keyboard navigation
+
+---
+
+*Last updated: July 16, 2025*