@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xcards.md

@@ -0,0 +1,139 @@
+# xcards - XTend Component
+
+> **See also:** [xmasonry](./xmasonry.md), [xcalendar](./xcalendar.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-cards>` is a flexible grid layout for arbitrary content. It supports
+responsive design, theming, and state integration.
+
+---
+
+## Features
+
+- Grid layout with variable column count
+- Responsive behavior (one column on mobile)
+- Theming through CSS custom properties
+- State integration through xstate
+
+---
+
+## Usage
+
+```html
+<x-cards columns="4" gap="2rem">
+  <div>Card 1</div>
+  <div>Card 2</div>
+</x-cards>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `columns` | Number | number of columns (default: 3) |
+| `gap` | String | spacing between cards (default: 1.5rem) |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| - | - |
+
+---
+
+## API
+
+- **Set columns dynamically:** `element.setAttribute('columns', 2)`
+- **State integration:** automatic through xstate
+
+---
+
+## Example: Dynamic JS
+
+```js
+const cards = document.createElement('x-cards');
+cards.setAttribute('columns', 2);
+document.body.appendChild(cards);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-cards {
+  --card-columns: 4;
+  --card-gap: 2rem;
+}
+```
+
+---
+
+## Accessibility
+
+- Grid role, semantic HTML
+
+---
+
+*Last updated: July 16, 2025*
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-cards` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component describes a
+responsive card grid for RMT shell authoring and uses the state key
+`xcards-state-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `layout.reflow.commit`
+- Event: `cards-layout`
+- Snapshot: `snapshot()`
+- CSS parts: `root`, `grid`, `item`
+
+## ECH-WP-07 Token Table and signatureDesign
+
+`signatureDesign`: independent enterprise card rhythm with tokenized glass,
+edge, depth, and typography. The default grid should not look like a generic
+SaaS card grid while still remaining fully themeable.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-layout-surface` | card surface |
+| `--xtend-layout-text` | card text color |
+| `--xtend-layout-border-color` | card edge |
+| `--xtend-layout-radius` | card radius |
+| `--xtend-layout-elevation` | card shadow |
+| `--xtend-layout-spacing` | card padding |
+| `--xtend-layout-gap` | grid spacing |
+| `--xtend-layout-font-family` | card typography |
+| `--xtend-layout-font-size` | card text size |
+| `--xtend-layout-media-radius` | image/media radius |
+| `--xtend-layout-focus-ring` | card focus |
+| `--xtend-layout-grid-min` | grid lower bound |
+| `--xtend-layout-content-max` | grid max width |
+
+## ECH-WP-07 External Theme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-cards,
+[data-xtend-layout-theme="enterprise-foreign"] x-card {
+  --xtend-layout-surface: #f8f4ef;
+  --xtend-layout-text: #1b2823;
+  --xtend-layout-border-color: rgba(27, 40, 35, 0.18);
+  --xtend-layout-radius: 0.3rem;
+  --xtend-layout-elevation: 0 12px 30px rgba(27, 40, 35, 0.12);
+  --xtend-layout-spacing: 1.35rem;
+  --xtend-layout-gap: 1.1rem;
+  --xtend-layout-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-layout-font-size: 1rem;
+  --xtend-layout-media-radius: 0.25rem;
+  --xtend-layout-focus-ring: 3px solid #8f4f2a;
+  --xtend-layout-grid-min: minmax(15rem, 1fr);
+  --xtend-layout-content-max: 74rem;
+}
+```

package/docs/en/components/xcheckbox.md

@@ -0,0 +1,118 @@
+# xcheckbox - XTend Component
+
+> **See also:** [xform](./xform.md), [xinput](./xinput.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-checkbox>` is the TypeScript-first binary control from `WP-E10-09`. It is
+form-associated, supports `checked` and `indeterminate`, reports changes
+through XTend events, and can be scheduled by RMT as a framework-agnostic UI
+component.
+
+## Usage
+
+```html
+<x-checkbox id="terms" name="terms" required checked>
+  <span slot="label">Accept terms of service</span>
+  <span slot="error">Consent is required.</span>
+</x-checkbox>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | String | form name |
+| `value` | String | form value when active, default `on` |
+| `checked` | Boolean | current selected state |
+| `indeterminate` | Boolean | visual mixed 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 |
+|-------|--------|
+| `checkbox-changed` | `{ checked, value, source: 'x-checkbox' }` |
+| `checkbox-invalid` | `{ checked, value, message, source: 'x-checkbox' }` |
+
+## API
+
+- `element.checked`
+- `element.value`
+- `element.indeterminate`
+- `element.toggle()`
+- `element.checkValidity()`
+- `element.reportValidity()`
+- `element.validate()`
+- `element.reset()`
+- `element.focus()`
+
+## State, RMT, and Fabric
+
+`<x-checkbox>` writes to `xcheckbox-checked-<id>`. RMT sees the component
+through `xtend.rmt.component-contract.v1` as a DOM descriptor, not as an XTend
+kernel dependency. Fabric metadata binds events to the `user-blocking` lane and
+keeps the boundary string `no-rmt-kernel-import-of-xtend-types` visible.
+
+## A11y and Performance
+
+The control mirrors `aria-checked`, `aria-describedby`, `required`, and
+`disabled` to the native checkbox. The performance profile uses
+`xtend.performance.component-profile.v1` with `budgetClass:
+'interactive-small'`, `lane: 'user-blocking'`, and `hydrationPolicy:
+'visible'`.
+
+## Form Controls UX from WP-E11-08
+
+`<x-checkbox>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects label, hint,
+error, `checkbox-changed`, `checkbox-invalid`, `xcheckbox-checked-<id>`,
+`ui.user-blocking.input`, Fabric lane `user-blocking`, and RMT shell authoring.
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: tactile enterprise checkbox with native reliability,
+separately themeable selection affordance, and status-stable helper/error
+rhythm.
+
+| 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` | native control/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` | checkbox accent |
+
+Density profiles: `comfortable`, `compact`, `dense`. Invalid state is visible
+through outline and error marker in addition to color.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-checkbox {
+  --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/xcode.md

@@ -0,0 +1,153 @@
+# xcode - XTend Component
+
+> See also: [xwriter](./xwriter.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-code>` renders code examples as an XTend Web Component with copy control,
+state integration, theming, and optional Prism.js syntax highlighting. The
+component is Shadow DOM based, so it can be used in any app or Developer Center
+surface without global `pre code` selectors leaking into the host.
+
+Prism remains optional and host-neutral. When `window.Prism` or a registered
+XCode highlighter is available, XCode renders token spans. When no grammar is
+available, the code remains safely escaped and visible as plain text.
+
+## Usage
+
+```html
+<x-code lang="js">
+  <template data-x-code-mode="text">console.log('Hello XTend!');</template>
+</x-code>
+```
+
+The alias attribute `language` is supported for existing fixtures and external
+hosts:
+
+```html
+<x-code language="rmt">
+  <template data-x-code-mode="text">template docs.demo { surface root { lane visible { hydrate page } } }</template>
+</x-code>
+```
+
+## Prism and RMT
+
+The Developer Center loads `components/prism.js` followed by
+`components/prism-rmt.js`. The RMT middleware registers `Prism.languages.rmt`
+and the aliases `rmt-vnext` and `xtendrmt`. This lets every XCode instance
+highlight RMT vNext app shells, primitives, lanes, events, and boundary rules:
+
+- `template`, `state`, `selector`, `datasource`, `action`, `portal`,
+  `overlay`, `resource`, `surface`, `remote surface`
+- `lane`, lifecycle operations, `when`, `slot`, `trust boundary`, `sanitize`
+- event bindings, payloads, reducer, effects, dotted primitive IDs, and
+  component tags
+
+Hosts can register their own highlighter:
+
+```js
+customElements.get('x-code')?.registerHighlighter({
+  highlight({ code, language }) {
+    return { html: code, highlighted: false, engine: 'plain-text', language };
+  }
+});
+```
+
+## Developer Center
+
+Markdown code fences from Parsedown are converted to `<x-code>` after Trusted
+DOM sanitizing. Every code surface in the Developer Center therefore uses the
+same path:
+
+- copy control and a11y signals from XCode
+- `docs.syntax.highlight` as an RMT schedule
+- Prism highlighting in Shadow DOM
+- plain-text fallback without a raw HTML sink
+
+## Attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `lang` | String | primary language, for example `js`, `html`, `rmt` |
+| `language` | String | compatibility alias when `lang` is not set |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `code-copied` | emitted after successful copy control |
+
+## API
+
+- `hydrate()` rerenders code and highlighting.
+- `snapshot()` returns language, code length, and highlighting metadata.
+- `customElements.get('x-code').registerHighlighter(provider)` registers an
+  optional host highlighter.
+
+The snapshot adds these non-breaking fields:
+
+- `highlighted`
+- `highlightEngine`
+- `highlightLanguage`
+- `languageAlias`
+
+## Layout Display Media UX Profile
+
+`x-code` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. Code blocks can therefore
+be authored in RMT as idle-hydratable display shells and use the state key
+`xcode-state-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.idle.hydrate`
+- Event: `code-copied`
+- Snapshot: `snapshot()`
+- CSS parts: `root`, `copy`, `pre`, `code`
+
+## Token Table
+
+ECH-WP-07 remains visible as the tokenization contract. `signatureDesign`:
+readable enterprise code surface with clear copy control, internal overflow,
+Prism-compatible token coloring, and an independent themeable monospace
+personality.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-layout-surface` | code surface |
+| `--xtend-layout-text` | code text color |
+| `--xtend-layout-border-color` | code and copy edge |
+| `--xtend-layout-radius` | code and copy radius |
+| `--xtend-layout-elevation` | code shadow |
+| `--xtend-layout-spacing` | code padding |
+| `--xtend-layout-gap` | theme spacing for tooling |
+| `--xtend-layout-font-family` | monospace/code typography |
+| `--xtend-layout-font-size` | code font size |
+| `--xtend-layout-media-radius` | copy-control radius |
+| `--xtend-layout-focus-ring` | copy-control focus |
+| `--xtend-layout-grid-min` | code layout minimum |
+| `--xtend-layout-content-max` | code max width |
+| `--x-code-token-keyword` | Prism keyword and RMT primitive |
+| `--x-code-token-string` | Prism string |
+| `--x-code-token-property` | Prism property and RMT IDs |
+| `--x-code-token-class` | component tags |
+| `--x-code-token-comment` | comments |
+
+## External Theme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-code {
+  --xtend-layout-surface: #151b19;
+  --xtend-layout-text: #f7f1e7;
+  --xtend-layout-border-color: rgba(247, 241, 231, 0.18);
+  --xtend-layout-radius: 0.35rem;
+  --xtend-layout-elevation: 0 16px 40px rgba(21, 27, 25, 0.22);
+  --xtend-layout-spacing: 1.25rem 1.4rem;
+  --xtend-layout-gap: 0.75rem;
+  --xtend-layout-font-family: "Cascadia Code", "Fira Mono", monospace;
+  --xtend-layout-font-size: 0.95rem;
+  --xtend-layout-media-radius: 999px;
+  --xtend-layout-focus-ring: 3px solid #d48b57;
+  --xtend-layout-grid-min: minmax(0, 1fr);
+  --xtend-layout-content-max: 68rem;
+}
+```

package/docs/en/components/xdialog.md

@@ -0,0 +1,108 @@
+# xdialog - XTend Component
+
+## Overview
+
+`<x-dialog>` is XTend's state-driven dialog component. It combines attribute
+control, `xstate` open flags, and aggregated `ui.dialogs` state into a shared
+overlay contract.
+
+## Usage
+
+```html
+<x-dialog overlay title="Example dialog" width="400px">
+  <p>Content</p>
+  <div slot="actions">
+    <button onclick="this.closest('x-dialog').close()">Close</button>
+  </div>
+</x-dialog>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `open` | boolean | dialog is open |
+| `overlay` | boolean | shows an overlay background |
+| `title` | string | dialog title line |
+| `width` | string | target width of the dialog |
+| `height` | string | target height of the dialog |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| default | main dialog content |
+| `actions` | actions in the footer |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `dialog-opened` | after successful opening |
+| `dialog-closed` | after successful closing |
+
+Events provide:
+
+```js
+{
+  id: 'dialog-abc123',
+  open: false,
+  source: 'button'
+}
+```
+
+## API
+
+- `element.open()`
+- `element.close()`
+
+API- and XState-controlled dialogs use the same open flags:
+
+- `xtend.component.x-dialog.<id>.open`
+- `dialog-open-<id>`
+- `xdialog-open-<id>`
+
+## Runtime Contract
+
+- API-managed dialogs read title, content, and actions from
+  `xstate.get('ui').dialogs`.
+- User interactions such as Escape, overlay click, and close button write open
+  state back.
+- API-managed dialogs remove themselves from `ui.dialogs` and the DOM after
+  closing.
+
+## Notes
+
+- Direct DOM usage through slots remains supported.
+- `window.XDialog.show()` is the preferred entry point for API-managed dialogs.
+- Focus trap, focus return, and ARIA roles are part of the default behavior.
+
+## Overlay Interaction UX Profile
+
+Since `WP-E11-11`, `<x-dialog>` declares the runtime profile
+`xtend.component.overlay-interaction-ux-profile.v1` through
+`xtendOverlayInteractionUxProfile`.
+
+| Field | Value |
+|-------|-------|
+| Family | `dialog` |
+| State Key | `dialog-open-<id>` |
+| Schedule | `overlay.stack.open` |
+| Commands | `open`, `close`, `focus-trap`, `apply-inert`, `lock-scroll`, `snapshot` |
+
+The profile standardizes focus trap, focus return, Escape topmost rule,
+background inert, balanced scroll lock, and host-local portal semantics. RMT
+can plan the dialog in shell-first templates while the RMT kernel remains
+framework-agnostic through `no-rmt-kernel-import-of-xtend-types`.
+
+## ECH-WP-06 Overlay Parity
+
+`x-dialog` exposes `surface`, `backdrop`, `close`, and `content` as shared
+overlay parts. `overlay` remains as an alias for `backdrop`. Surface, text,
+backdrop, elevation, radius, z-index, action colors, close surface, and focus
+ring can be overridden through `--xtend-overlay-*`, `--dialog-*`, or
+`--xdialog-*` tokens.
+
+`x-dialog` is modal: focus trap, background inert, scroll lock, Escape, and
+focus return remain active in the default path. Dialogs without `overlay` keep
+the surface parts but omit the visual backdrop.

package/docs/en/components/xdrawer.md

@@ -0,0 +1,110 @@
+# xdrawer - XTend Component
+
+> **See also:** [xpopover](./xpopover.md), [xtooltip](./xtooltip.md), [xrouter](./xrouter.md), [xlink](./xlink.md)
+
+## Overview
+
+`<x-drawer>` is the shell and navigation component from `WP-E10-11`. It
+provides side panels and navigation drawers for RMT-first apps, supports focus
+trap, Escape close, outside click, and optional route-aware behavior.
+
+## Usage
+
+```html
+<x-drawer id="app-nav" placement="left" modal label="App navigation" route-aware>
+  <button slot="trigger" type="button">Open navigation</button>
+  <strong slot="header">Navigation</strong>
+  <a href="#/overview">Overview</a>
+  <small slot="footer">Signed in</small>
+</x-drawer>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `open` | Boolean | opens the drawer in controlled mode |
+| `placement` | String | `left`, `right`, or `bottom` |
+| `modal` | Boolean | activates focus trap and `aria-modal` |
+| `label` | String | accessible name for the drawer |
+| `route-aware` | Boolean | closes after XRouter route changes and emits route signal |
+
+## Events
+
+| Event | Detail |
+|-------|--------|
+| `drawer-opened` | `{ id, open, source, placement, modal }` |
+| `drawer-closed` | `{ id, open, source, placement, modal }` |
+| `drawer-route-selected` | `{ id, routeRef, source: 'x-router' }` |
+
+## API
+
+- `openDrawer()`
+- `closeDrawer()`
+- `toggle()`
+
+## Theme and Tokens
+
+`<x-drawer>` synchronizes `data-theme` from `document.documentElement` and
+automatically uses the global XTend tokens from `x-theme`. Without custom
+drawer tokens, background, text, border, and overlay fall back to
+`--xtend-surface`, `--xtend-text`, `--xtend-border-color`, and
+`--xtend-overlay-bg`. Navigation drawers therefore remain readable in bright
+mode and dark mode even when an app shell provides no custom drawer colors.
+
+| Token | Purpose |
+|-------|---------|
+| `--drawer-bg` / `--drawer-bg-dark` | surface background |
+| `--drawer-color` / `--drawer-color-dark` | text color |
+| `--drawer-border` / `--drawer-border-dark` | borders and separators |
+| `--drawer-overlay-bg` / `--drawer-overlay-bg-dark` | backdrop color |
+| `--drawer-focus` | focus ring |
+| `--drawer-close-size` | size of the close icon button |
+| `--drawer-close-border` / `--drawer-close-color` | border and icon color of the close button |
+| `--drawer-close-hover-bg` / `--drawer-close-hover-bg-dark` | hover surface of the close button |
+
+## State, RMT, and Fabric
+
+`<x-drawer>` writes to `xdrawer-open-<id>`. The RMT contract is
+`xtend.rmt.component-contract.v1` and uses `component.lazy.hydrate`,
+`route.visible.render`, and `overlay.drawer.transition`. The kernel boundary
+remains `no-rmt-kernel-import-of-xtend-types`.
+
+## A11y and Performance
+
+The component uses `role="dialog"`, `aria-modal`, `aria-hidden`,
+`aria-expanded`, `inert`, focus trap, and focus return. On close, focus is
+returned to the trigger or last active element before the drawer surface is
+hidden from assistive technology. The screen reader signal
+`route-change-announcement` is intended for app-shell navigation. The
+performance profile is `xtend.performance.component-profile.v1` with
+`budgetClass: 'overlay-large'`, `lane: 'visible'`, and
+`hydrationPolicy: 'lazy'`.
+
+## Overlay Interaction UX Profile
+
+Since `WP-E11-11`, `<x-drawer>` declares the runtime profile
+`xtend.component.overlay-interaction-ux-profile.v1` through
+`xtendOverlayInteractionUxProfile`.
+
+| Field | Value |
+|-------|-------|
+| Family | `drawer` |
+| State Key | `xdrawer-open-<id>` |
+| Schedule | `overlay.stack.open` |
+| Commands | `open`, `close`, `toggle`, `focus-trap`, `apply-inert`, `lock-scroll`, `snapshot` |
+
+The profile describes drawers as route-aware overlays: modal behavior is
+optional, focus trap is active only in modal operation, Escape closes the
+topmost overlay, and XRouter route changes may close the drawer in a controlled
+way.
+
+## ECH-WP-06 Overlay Parity
+
+`x-drawer` uses the shared overlay part aliases `surface`, `backdrop`, `close`,
+and `content`. `overlay` remains as a legacy alias for `backdrop`. Host themes
+can control surface, text, border, elevation, backdrop, z-index, and focus ring
+through `--xtend-overlay-*` or compatible `--drawer-*` tokens.
+
+Modality is optional: `modal` activates focus trap, background inert, and
+scroll lock; non-modal drawers remain controllable for app-shell navigation.