@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/en/components/xhero.md

@@ -0,0 +1,157 @@
+# xhero - XTend Component
+
+> **See also:** [xsection](./xsection.md), [xbutton](./xbutton.md)
+
+## Overview
+
+`<x-hero>` is a flexible hero component for high-impact headers, landing pages,
+and entry points. It supports slots for title, subtitle, actions, and media.
+
+---
+
+## Features
+
+- Flexible layout for hero areas
+- Slots for title, text, actions, and media
+- Theming through CSS custom properties
+- Theme variants through `background-light`, `background-dark`,
+  `font-color-light`, `font-color-dark`, `overlay-light`, and `overlay-dark`
+- Responsive design
+
+---
+
+## Usage
+
+```html
+<x-hero>
+  <h1 slot="title">Welcome!</h1>
+  <p slot="subtitle">XTend makes web development simple.</p>
+  <x-button slot="action">Get started</x-button>
+</x-hero>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `background` | String | fixed background or CSS variable |
+| `background-light` | String | background for light themes |
+| `background-dark` | String | background for dark themes |
+| `background-image` | String | image background |
+| `overlay` | Boolean | activates overlay surface |
+| `overlay-light` | String | overlay color for light themes |
+| `overlay-dark` | String | overlay color for dark themes |
+| `font-color` | String | fixed text color |
+| `font-color-light` | String | text color for light themes |
+| `font-color-dark` | String | text color for dark themes |
+| `animate` | Boolean | activates entrance transition with reduced-motion fallback |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| - | - |
+
+---
+
+## API
+
+- **Insert content through slots**
+- **State integration:** optional through xstate
+
+---
+
+## Example: Dynamic JS
+
+```js
+const hero = document.createElement('x-hero');
+hero.innerHTML = '<h1 slot="title">Hello XTend!</h1>';
+document.body.appendChild(hero);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-hero {
+  --hero-bg: #f5f5f5;
+  --hero-color: #222;
+}
+```
+
+## Viewport Safety
+
+`x-hero` constrains host, root, and content to `max-width: 100%` and avoids
+inner `100vw` width on narrow viewports. The component therefore stays inside
+the visible viewport even in padded app shells or docs layouts.
+
+---
+
+## Accessibility
+
+- Semantic HTML, ARIA
+
+---
+
+*Last updated: July 16, 2025*
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-hero` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component remains a
+hero/display shell and can be rendered first in RMT with
+`component.shell.render`. The state key is `xhero-state-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.shell.render`
+- Events: `hero-rendered`, `hero-animated`
+- Snapshot: `snapshot()`
+- CSS parts: `root`, `overlay`, `content`, `scroll-button`
+
+## ECH-WP-07 Token Table and signatureDesign
+
+`signatureDesign`: immersive enterprise hero composition with editorial depth,
+media-capable surface, and tokenized content block. The default effect should
+feel elegant and independent while allowing image, app, and corporate
+presentation.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-layout-surface` | hero and content surface |
+| `--xtend-layout-text` | hero text color |
+| `--xtend-layout-border-color` | scroll-control edge |
+| `--xtend-layout-radius` | hero, content, and title radius |
+| `--xtend-layout-elevation` | hero, content, and title shadow |
+| `--xtend-layout-spacing` | hero and content padding |
+| `--xtend-layout-gap` | composition spacing for theme authors |
+| `--xtend-layout-font-family` | hero typography |
+| `--xtend-layout-font-size` | control and content scaling |
+| `--xtend-layout-media-radius` | image/hero radius |
+| `--xtend-layout-focus-ring` | scroll-control focus |
+| `--xtend-layout-grid-min` | responsive composition base |
+| `--xtend-layout-content-max` | content width |
+
+## ECH-WP-07 External Theme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-hero {
+  --xtend-layout-surface: rgba(248, 244, 239, 0.88);
+  --xtend-layout-text: #15231d;
+  --xtend-layout-border-color: rgba(21, 35, 29, 0.22);
+  --xtend-layout-radius: 0.45rem;
+  --xtend-layout-elevation: 0 20px 60px rgba(21, 35, 29, 0.16);
+  --xtend-layout-spacing: 4rem 2rem;
+  --xtend-layout-gap: 1rem;
+  --xtend-layout-font-family: "Aptos Display", "Segoe UI", sans-serif;
+  --xtend-layout-font-size: 1.05rem;
+  --xtend-layout-media-radius: 0.65rem;
+  --xtend-layout-focus-ring: 3px solid #8f4f2a;
+  --xtend-layout-grid-min: minmax(0, 1fr);
+  --xtend-layout-content-max: 42rem;
+}
+```

package/docs/en/components/xicon.md

@@ -0,0 +1,149 @@
+# xicon - XTend Component
+
+> **See also:** [xbutton](./xbutton.md), [xtheme](./xtheme.md), [xrouter](./xrouter.md)
+
+## Overview
+
+`<x-icon>` is the universal iconography adapter for XTend apps. The component
+renders local inline SVG icons, registered icon packs, or controlled URL
+sources while remaining framework-agnostic, RMT-compatible, and CDN-free.
+
+The included `core` pack covers the most important XTend UI symbols. The local
+`lucide` adapter serves as a larger superset, loads from local ESM artifacts,
+and avoids external CDN dependencies, FCP slowdowns, and privacy issues.
+
+## Features
+
+- local `core` icon pack with base icons for shell, docs, status, and
+  navigation
+- local `lucide` IconPack adapter as a superset without remote runtime import
+- global registry `window.XTend.icons` for custom icon packs and corporate
+  design sets
+- direct sources through `src` for SVG files from repo, app bundle, or host CDN
+  policies
+- raw SVG pack entries are reduced to allowed nodes and attributes before
+  rendering
+- a11y mode for decorative and semantic icons
+- state integration through `xicon-state-<id>`
+- RMT shell authoring through `xtend.rmt.component-contract.v1`
+- performance profile `xtend.performance.component-profile.v1` with
+  `display-micro` budget
+
+## Usage
+
+```html
+<x-icon name="search" label="Search"></x-icon>
+<x-icon name="gauge" pack="lucide" size="1.25rem" label="Performance"></x-icon>
+<x-icon src="/assets/icons/company.svg" label="Corporate Icon"></x-icon>
+<x-icon name="chevron-right" decorative></x-icon>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | String | icon name or alias from the registry |
+| `pack` | String | optional icon pack, for example `core` or `lucide` |
+| `src` | String | controlled URL source for an icon from repo, app bundle, or host policy |
+| `label` | String | accessible name for screen readers |
+| `size` | String | CSS size, for example `1em`, `20px`, `1.25rem` |
+| `stroke-width` | String | stroke width for inline SVG paths |
+| `color` | String | CSS color value; default is `currentColor` |
+| `decorative` | Boolean | sets `aria-hidden` and removes semantic image role |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `icon-ready` | icon was resolved from pack or `src` |
+| `icon-missing` | registry could not resolve `name`/`pack` |
+| `icon-pack-registered` | a pack was registered in the global registry |
+
+## API
+
+| Method | Purpose |
+|--------|---------|
+| `setIcon(name, options?)` | sets icon, pack, label, or `src` programmatically |
+| `registerPack(pack, options?)` | registers a pack through the component |
+| `snapshot()` | returns `xtend.component.x-icon.state.v1` including registry snapshot |
+| `window.XTend.icons.register(pack, options?)` | global pack registration |
+| `window.XTend.icons.resolve(name, options?)` | global resolution without rendering |
+| `window.XTend.icons.snapshot()` | registry snapshot for diagnostics |
+
+## Custom Icon Packs
+
+```js
+window.XTend.icons.register({
+  id: 'brand',
+  label: 'Corporate Design Icons',
+  cdnAllowed: false,
+  icons: {
+    product: {
+      aliases: ['logo-mark'],
+      nodes: [
+        { tag: 'path', attrs: { d: 'M12 3 21 8v8l-9 5-9-5V8Z' } }
+      ]
+    }
+  }
+});
+```
+
+Packs can contain custom SVG node descriptors, individual path strings, inline
+SVG records, or URL records. Remote sources are not the XTend default; hosts
+must intentionally provide them as `src` or pack URLs.
+
+## ECH-WP-04 Control Rule
+
+No text glyphs as controls: close, menu, disclosure, status, and action
+controls must not be styled with visible characters such as `x`, `&times;`,
+arrows, or emoji. Use `x-icon`, inline SVG, or a tokenized CSS graphic.
+
+Required for icon controls:
+
+- The button has an accessible name, for example `aria-label`.
+- The button exposes a stable control part, for example `part="close control"`.
+- The graphic exposes an icon part, for example `part="control icon"` or
+  `part="close-icon control icon"`.
+- The core pack contains at least `close`, `menu`, `chevron-left`,
+  `chevron-right`, `chevron-up`, `chevron-down`, `success`, `warning`, `error`,
+  and `info` for framework controls.
+- Custom icon packs must use local SVG node descriptors or safe `src` sources;
+  CDN dependencies are not an XTend default base.
+
+## RMT and Fabric
+
+`x-icon` declares `xtendRmtMetadata` with `adapter: 'xtend.component'`,
+`templateMode: 'dom_descriptor'`, `shellAuthoring.attributes`, and the boundary
+`no-rmt-kernel-import-of-xtend-types`. RMT can therefore author icons in app
+shells, navigation, buttons, or docs templates without importing the XTend
+kernel or an icon vendor.
+
+Fabric consumes:
+
+- `icon-ready`
+- `icon-missing`
+- `icon-pack-registered`
+- State key `xicon-state-<id>`
+- `snapshot()`
+
+## Styling and Theming
+
+```css
+x-icon {
+  --xtend-icon-size: 1rem;
+  --xtend-icon-color: currentColor;
+  --xtend-icon-stroke-width: 2;
+}
+```
+
+The icon follows `currentColor` and therefore integrates into `x-theme`,
+`x-header`, `x-button`, `x-menu`, and custom corporate design tokens. In
+forced-colors mode, the component remains readable through system colors.
+
+## Accessibility
+
+- with `label`, the host renders `role="img"` and `aria-label`
+- without label or with `decorative`, the component renders `aria-hidden`
+- URL icons receive an empty `alt` when decorative
+- `icon-missing` is available as a diagnostic event without burdening screen
+  readers with error signals

package/docs/en/components/xinput.md

@@ -0,0 +1,147 @@
+# xinput - XTend Component
+
+> **See also:** [xform](./xform.md), [xstate](./xstate.md)
+
+## Overview
+
+`<x-input>` is a versatile input field with theming, state integration, and
+full form support.
+
+---
+
+## Features
+
+- Standard input with slot for label
+- State integration through xstate
+- Theming through CSS custom properties
+- Form integration
+
+---
+
+## Usage
+
+```html
+<x-input value="Hello"></x-input>
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `value` | String | value of the input field |
+| `type` | String | input type (text, number, etc.) |
+| `placeholder` | String | placeholder text |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `input` | emitted while typing |
+| `change` | emitted when the value changes |
+| `input-changed` | current XTend contract for value changes, detail: `{ value }` |
+| `validation-failed` | validation error, detail: `{ value }` |
+
+---
+
+## API
+
+- **Set/read value:** `element.value = 'Text'`
+- **State integration:** automatic through xstate
+- **Validation:** `element.checkValidity()`, `element.reportValidity()`
+- **Reset:** `element.reset()`
+
+## State Contract from ER-WP-33
+
+`<x-input>` writes its value to `xinput-value-<id>` and reacts to external
+changes of that key. The validation region uses `role="alert"` and
+`aria-live="assertive"`, so form errors become semantically visible and not
+only color-coded.
+
+## Form Controls UX from WP-E11-08
+
+`<x-input>` exposes `xtendFormControlUxProfile` with
+`xtend.component.form-control-ux-profile.v1`. The profile connects label, hint,
+error, `input-changed`, `validation-failed`, `xinput-value-<id>`,
+`ui.user-blocking.input`, Fabric lane `user-blocking`, and RMT shell authoring.
+
+---
+
+## Example: Dynamic JS
+
+```js
+const input = document.createElement('x-input');
+input.value = 'Hello';
+document.body.appendChild(input);
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-input {
+  --input-border: 1px solid #ccc;
+  --input-bg: #fff;
+  --input-bg-dark: #0f0f12;
+  --input-placeholder-color-dark: #b8c4d4;
+}
+```
+
+`<x-input>` automatically uses `--xtend-surface` and `--xtend-text` from
+`x-theme`. In `data-theme="dark"`, a dark background is set through
+`--input-bg-dark`, `--xtend-control-bg-dark`, or the theme surface fallback so
+text and search fields remain readable in the Docs App.
+
+---
+
+## Accessibility
+
+- Label slot, ARIA, form integration
+
+---
+
+*Last updated: July 16, 2025*
+
+## ECH-WP-08 Form Theme/A11y Hardening
+
+`signatureDesign`: precise enterprise text field with calm surface, clear
+status typography, and dense but readable form rhythm.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-form-text` | host text color |
+| `--xtend-form-control-surface` | input surface |
+| `--xtend-form-control-text` | input text |
+| `--xtend-form-label-text` | label |
+| `--xtend-form-helper-text` | helper/hint |
+| `--xtend-form-error-text` | error text |
+| `--xtend-form-error-surface` | error surface |
+| `--xtend-form-error-border` | error edge and marker |
+| `--xtend-form-focus-ring` | native focus outline |
+| `--xtend-form-radius` | control and error radius |
+| `--xtend-form-gap` | label, helper, and error spacing |
+| `--xtend-form-font-family` | form typography |
+| `--xtend-form-control-font-size` | control font |
+| `--xtend-form-helper-font-size` | helper/error font |
+| `--xtend-form-icon-color` | icon/affordance color for controls with icons |
+
+Density profiles: `density="comfortable"`, `density="compact"`, and
+`density="dense"`. Invalid/error state is not color-only: control edge, inner
+ring, and error marker remain visible in dark/forced-colors modes.
+
+```css
+[data-xtend-form-theme="enterprise-foreign"] x-input {
+  --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/xlightbox.md

@@ -0,0 +1,113 @@
+# xlightbox - XTend Component
+
+> **See also:** [xplayer](./xplayer.md)
+
+## Overview
+
+`<x-lightbox>` displays images in a viewport-wide overlay. It supports trigger
+slots, API-controlled opening, Escape close, focus return, and
+viewport-bounded media scaling.
+
+---
+
+## Features
+
+- Overlay for images and media
+- Trigger slot and global helper API
+- Keyboard support with Escape close
+- Viewport-bounded image scaling with body portal
+- Theming through CSS custom properties
+
+---
+
+## Usage
+
+```html
+<x-lightbox id="logo-lightbox" src="/assets/logo.png" alt="XTend Logo">
+  <x-button slot="trigger" variant="secondary">View logo</x-button>
+</x-lightbox>
+
+<img src="/assets/preview.jpg" data-xlightbox alt="Preview" />
+```
+
+---
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `src` | String | image source for trigger, API, and `data-xlightbox` |
+| `open` | Boolean | opens the lightbox in controlled mode when `src` is set |
+| `alt` | String | alternative text for the displayed image |
+
+---
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `lightbox-opened` | emitted on open, detail: `{ src }` |
+| `lightbox-closed` | emitted on close |
+
+---
+
+## API
+
+- **Open:** `element.open(src)`
+- **Close:** `element.close()`
+- **Global helper:** `window.showLightbox(src)`
+- **State:** `xlightbox-open-<id>`
+
+`src` configures the image source but does not open the lightbox
+automatically. For direct UI usage, place an element in the `trigger` slot.
+When opened, the lightbox portals itself to `document.body` so overlay and
+image are not clipped by app-shell containers, `main`, cards, or transformed
+demo frames.
+
+---
+
+## Example: Dynamic JS
+
+```js
+const lightbox = document.createElement('x-lightbox');
+document.body.appendChild(lightbox);
+lightbox.open('/assets/image.jpg');
+```
+
+---
+
+## Styling and Theming
+
+```css
+x-lightbox {
+  --lightbox-bg: rgba(0,0,0,0.9);
+  --lightbox-padding: clamp(0.75rem, 2vw, 2rem);
+  --lightbox-radius: 0.75rem;
+}
+```
+
+---
+
+## Accessibility
+
+- focus management, keyboard navigation, and focus return
+- `role="dialog"`, `aria-modal="true"`, and closed state with `aria-hidden`
+  and `inert`
+- image scaling via `object-fit: contain` and
+  `max-height: calc(100dvh - padding)`
+
+---
+
+*Last updated: July 16, 2025*
+
+## Layout Display Media UX Profile
+
+Starting with `WP-E11-12`, `x-lightbox` exposes the profile
+`xtend.component.layout-display-media-ux-profile.v1`. The component combines
+overlay and media maturity and uses the state key `xlightbox-open-<id>`.
+
+- Profile getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `media.lazy.load`
+- Events: `lightbox-opened`, `lightbox-closed`
+- Snapshot: `snapshot()`
+- CSS parts: `overlay`, `content`, `close`, `media`

package/docs/en/components/xlink.md

@@ -0,0 +1,130 @@
+# xlink - XTend Component
+
+## Overview
+
+`<x-link>` is the declarative link component for XTend SPAs. It works with
+`<x-router>`, detects hash and history mode, and keeps active state current
+even during programmatic navigation.
+
+## Usage
+
+```html
+<x-link href="/docs">Open documentation</x-link>
+<x-link href="https://example.com">External link</x-link>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `href` | string | target path or external URL |
+| `active` | boolean | set when the link is currently active |
+| `state` | string | optional JSON for `history.pushState()` |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `before-navigate` | cancelable, before navigation |
+| `after-navigate` | after successful navigation |
+
+`before-navigate` and `after-navigate` provide:
+
+```js
+{
+  href: '/docs',
+  mode: 'history',
+  state: { ... },
+  source: 'x-link',
+  stateKey: 'xlink-active-link-123',
+  scheduleRef: 'ui.user-blocking.navigation'
+}
+```
+
+## Contract
+
+- internal links are normalized and navigate in SPA-compatible mode
+- external links keep default behavior and automatically receive
+  `target="_blank"` plus `rel="noopener noreferrer"`
+- active state updates on `popstate`, `hashchange`, `x-navigate`, and
+  `xrouter-after-navigate`
+- active links mirror `aria-current="page"` and `xlink-active-<id>`
+- Enter and Space activate the same navigation path
+- long labels and slotted icon/text content remain overflow-safe in narrow
+  menus, sidebars, and header drawers
+
+## Navigation Routing UX Profile
+
+`<x-link>` exposes `xtendNavigationRoutingUxProfile` with
+`xtend.component.navigation-routing-ux-profile.v1`. The profile describes
+`x-link` as a router link with `before-navigate`, `after-navigate`,
+`x-navigate`, `xlink-active-<id>`, `ui.user-blocking.navigation`, active state,
+keyboard activation, Fabric lane `user-blocking`, and RMT shell authoring.
+
+The link component delegates route announcements to `x-router`, but remains
+responsible for visible active state, keyboard activation, and safe external
+links.
+
+## Overflow Safety
+
+`x-link` is overflow-safe for app-shell navigation, menus, and sidebars. The
+host constrains itself to the available container, slotted content receives
+`min-width: 0`, and long labels may wrap. For intentionally one-line links,
+set `--xtend-link-white-space: nowrap`.
+
+## Notes
+
+- router mode is detected from the first discovered `<x-router>`
+- identical target paths do not trigger redundant URL changes
+- `x-link` uses the same navigation contract as `x-router`
+
+## ECH-WP-09 Token Table and Navigation States
+
+`signatureDesign`: `x-link` is the compact enterprise router link with visible
+current indicator and tokenized active/disabled behavior. Active/current/
+selected, hover, focus, and disabled states must remain readable in dense
+headers, sidebars, and menus.
+
+| Token | Purpose |
+| --- | --- |
+| `--xtend-nav-surface` | link surface |
+| `--xtend-nav-text` | link text |
+| `--xtend-nav-border-color` | shared navigation edge |
+| `--xtend-nav-radius` | link radius |
+| `--xtend-nav-gap` | spacing between icon and label |
+| `--xtend-nav-font-family` | link typography |
+| `--xtend-nav-font-size` | link text size |
+| `--xtend-nav-active-surface` | active/current/selected surface |
+| `--xtend-nav-active-text` | active/current/selected text |
+| `--xtend-nav-current-indicator` | non-color-only current indicator |
+| `--xtend-nav-hover-surface` | hover surface |
+| `--xtend-nav-focus-ring` | keyboard focus |
+| `--xtend-nav-disabled-opacity` | disabled dimming |
+
+## ECH-WP-09 Keyboard Behavior
+
+`Enter` and `Space` activate internal links through the same navigation path as
+click. Disabled links remove the internal `href`, set `aria-disabled="true"`,
+and are not keyboard-activatable. Active/current is mirrored through
+`aria-current="page"`; composite navigation can add `aria-selected="true"` on
+the host.
+
+## ECH-WP-09 External Theme
+
+```css
+[data-xtend-nav-theme="enterprise-foreign"] x-link {
+  --xtend-nav-surface: transparent;
+  --xtend-nav-text: #17231f;
+  --xtend-nav-border-color: transparent;
+  --xtend-nav-radius: 0.3rem;
+  --xtend-nav-gap: 0.4rem;
+  --xtend-nav-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-nav-font-size: 0.96rem;
+  --xtend-nav-active-surface: rgba(181, 107, 53, 0.16);
+  --xtend-nav-active-text: #173f35;
+  --xtend-nav-current-indicator: #b56b35;
+  --xtend-nav-hover-surface: rgba(181, 107, 53, 0.1);
+  --xtend-nav-focus-ring: 3px solid #b56b35;
+  --xtend-nav-disabled-opacity: 0.44;
+}
+```