@adia-ai/web-components 0.4.6 → 0.4.7

package/components/tag/tag.js

@@ -1,89 +1,17 @@
 /**
- * <tag-ui text="Label" variant="info" removable></tag-ui>
+ * `<tag-ui>` — auto-registers the tag on import.
  *
- * Inline tag / chip. Pill-shaped, text rendered via CSS attr().
- * Optional dismiss button dispatches a 'remove' CustomEvent.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Variants: default, info, success, warning, danger
- * Sizes: sm, md (default)
+ *   import { UITag } from '@adia-ai/web-components/components/tag/class';
  *
- * Events:
- *   remove — { detail: { text, value } } fired when dismiss is clicked
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UITag } from './class.js';
 
-class UITag extends UIElement {
-  static properties = {
-    text:      { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
-    variant:   { type: String,  default: 'default', reflect: true },
-    size:      { type: String,  default: 'md', reflect: true },
-    removable: { type: Boolean, default: false, reflect: true },
-    disabled:  { type: Boolean, default: false, reflect: true },
-  };
-
-  static parts = {
-    dismiss: '<button slot="dismiss" type="button" aria-label="Remove"><icon-ui name="x"></icon-ui></button>',
-  };
-
-  static template = () => null;
-
-  #onClick = (e) => {
-    if (this.disabled) return;
-    if (e.target.closest('[slot="dismiss"]')) {
-      this.dispatchEvent(new CustomEvent('remove', {
-        bubbles: true,
-        detail: { text: this.text, value: this.text },
-      }));
-      this.remove();
-    }
-  };
-
-  #onKeydown = (e) => {
-    if (this.disabled) return;
-    if (e.target.closest('[slot="dismiss"]') && (e.key === 'Enter' || e.key === ' ')) {
-      e.preventDefault();
-      this.dispatchEvent(new CustomEvent('remove', {
-        bubbles: true,
-        detail: { text: this.text, value: this.text },
-      }));
-      this.remove();
-    }
-  };
-
-  connected() {
-    this.setAttribute('role', 'status');
-    this.setAttribute('tabindex', '0');
-
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKeydown);
-  }
-
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKeydown);
-  }
-
-  render() {
-    if (this.text) this.setAttribute('aria-label', this.text);
-
-    if (this.disabled) {
-      this.setAttribute('aria-disabled', 'true');
-      this.setAttribute('tabindex', '-1');
-    } else {
-      this.removeAttribute('aria-disabled');
-      this.setAttribute('tabindex', '0');
-    }
-
-    if (this.removable && !this.disabled) {
-      const btn = this.ensure('dismiss');
-      if (btn && btn.parentElement !== this) this.appendChild(btn);
-    } else {
-      this.drop('dismiss');
-    }
-  }
-}
-customElements.define('tag-ui', UITag);
+defineIfFree('tag-ui', UITag);
 
 export { UITag };

package/components/text/class.js

@@ -0,0 +1,46 @@
+/**
+ * Non-side-effect class export for `<text-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/text`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <text-ui variant="heading">Hello World</text-ui>
+ * <text-ui truncate>Long text that gets cut off...</text-ui>
+ * <text-ui variant="body" lines="3">Multi-line clamped content...</text-ui>
+ *
+ * Typography wrapper that applies role tokens.
+ *
+ * Properties:
+ *   variant  — body | heading | title | display | caption | label | kicker | code
+ *   truncate — single-line truncation with ellipsis
+ *   lines    — multi-line clamp count (0 = no clamp)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIText extends UIElement {
+  static properties = {
+    variant:  { type: String,  default: 'body', reflect: true },
+    strong:   { type: Boolean, default: false, reflect: true },
+    truncate: { type: Boolean, default: false, reflect: true },
+    lines:    { type: Number,  default: 0, reflect: true },
+  };
+
+  static template = () => null;
+
+  render() {
+    if (this.lines > 0) {
+      this.style.setProperty('--_text-lines', String(this.lines));
+    } else {
+      this.style.removeProperty('--_text-lines');
+    }
+  }
+}

package/components/text/text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/text
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run components`, then `npm run codegen:dts` to regenerate;
+ * or hand-author this file fully if rich event types are needed.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIText extends UIElement {
+  /** Multi-line clamp count (0 = no clamp) */
+  lines: number;
+  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
+  strong: boolean;
+  /** Display text content. The main payload field for Text components extracted from HTML. */
+  textContent: string;
+  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
+  truncate: boolean;
+  /** Typography variant — sets role tokens (size/weight/tracking/color). */
+  variant: 'body' | 'heading' | 'subheading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+}

package/components/text/text.js

@@ -1,36 +1,17 @@
 /**
- * <text-ui variant="heading">Hello World</text-ui>
- * <text-ui truncate>Long text that gets cut off...</text-ui>
- * <text-ui variant="body" lines="3">Multi-line clamped content...</text-ui>
+ * `<text-ui>` — auto-registers the tag on import.
  *
- * Typography wrapper that applies role tokens.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Properties:
- *   variant  — body | heading | title | display | caption | label | kicker | code
- *   truncate — single-line truncation with ellipsis
- *   lines    — multi-line clamp count (0 = no clamp)
+ *   import { UIText } from '@adia-ai/web-components/components/text/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIText extends UIElement {
-  static properties = {
-    variant:  { type: String,  default: 'body', reflect: true },
-    strong:   { type: Boolean, default: false, reflect: true },
-    truncate: { type: Boolean, default: false, reflect: true },
-    lines:    { type: Number,  default: 0, reflect: true },
-  };
-
-  static template = () => null;
+import { defineIfFree } from '../../core/register.js';
+import { UIText } from './class.js';
 
-  render() {
-    if (this.lines > 0) {
-      this.style.setProperty('--_text-lines', String(this.lines));
-    } else {
-      this.style.removeProperty('--_text-lines');
-    }
-  }
-}
-customElements.define('text-ui', UIText);
+defineIfFree('text-ui', UIText);
 
 export { UIText };

package/components/textarea/class.js

@@ -0,0 +1,134 @@
+/**
+ * Non-side-effect class export for `<textarea-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/textarea`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <textarea-ui> — Multiline text input. The host IS the interactive surface.
+ * Uses contenteditable for text entry, ElementInternals for form participation.
+ * No native <textarea> inside.
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export class UITextarea extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    placeholder: { type: String,  default: '', reflect: true },
+    label:       { type: String,  default: '', reflect: true },
+    rows:        { type: Number,  default: 3, reflect: true },
+    resize:      { type: String,  default: 'vertical', reflect: true },
+  };
+
+  static template = () => null;
+
+  #textEl = null;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'textbox');
+    this.setAttribute('aria-multiline', 'true');
+
+    if (!this.querySelector('[slot="text"]')) {
+      this.innerHTML = `
+        ${this.label ? `<label slot="label" label="${this.label}"></label>` : ''}
+        <div slot="text" contenteditable="plaintext-only" tabindex="0"
+             ${this.value ? '' : 'data-empty=""'}
+             data-placeholder="${this.placeholder}"></div>
+      `;
+    }
+
+    this.#textEl = this.querySelector('[slot="text"]');
+    if (this.value) this.#textEl.textContent = this.value;
+
+    if (this.#textEl) {
+      this.#textEl.addEventListener('input', this.#onInput);
+      this.#textEl.addEventListener('keydown', this.#onKeydown);
+      this.#textEl.addEventListener('blur', this.#onBlur);
+      this.#textEl.addEventListener('paste', this.#onPaste);
+    }
+  }
+
+  render() {
+    if (!this.#textEl) return;
+
+    this.#textEl.setAttribute('data-placeholder', this.placeholder);
+
+    if (this.disabled || this.readonly) {
+      this.#textEl.contentEditable = 'false';
+    } else {
+      this.#textEl.contentEditable = 'plaintext-only';
+    }
+
+    // Sync programmatic `value` assignments (form.reset(), trait writes,
+    // controlled-input patterns) into the contenteditable surface. Skip
+    // when the surface already matches to avoid clobbering an in-flight
+    // edit's caret.
+    const text = this.value || '';
+    if (this.#textEl.textContent !== text) {
+      this.#textEl.textContent = text;
+      this.#textEl.toggleAttribute('data-empty', !text);
+    }
+
+    const label = this.querySelector('[slot="label"]');
+    if (label && this.label) label.setAttribute('label', this.label);
+
+    this.setAttribute('aria-label', this.label || this.placeholder || '');
+  }
+
+  #onInput = () => {
+    const text = this.#textEl.textContent || '';
+    this.value = text;
+    this.#textEl.toggleAttribute('data-empty', !text);
+    this.syncValue(text);
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  #onKeydown = (e) => {
+    // Enter without shift submits; shift+enter inserts newline
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      this.dispatchEvent(new Event('submit', { bubbles: true }));
+    }
+  };
+
+  #onBlur = () => {
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  #onPaste = (e) => {
+    e.preventDefault();
+    const text = e.clipboardData?.getData('text/plain') || '';
+    document.execCommand('insertText', false, text);
+  };
+
+  focus() { this.#textEl?.focus(); }
+
+  clear() {
+    this.value = '';
+    if (this.#textEl) {
+      this.#textEl.textContent = '';
+      this.#textEl.setAttribute('data-empty', '');
+    }
+    this.syncValue('');
+  }
+
+  disconnected() {
+    super.disconnected();
+    if (this.#textEl) {
+      this.#textEl.removeEventListener('input', this.#onInput);
+      this.#textEl.removeEventListener('keydown', this.#onKeydown);
+      this.#textEl.removeEventListener('blur', this.#onBlur);
+      this.#textEl.removeEventListener('paste', this.#onPaste);
+    }
+    this.#textEl = null;
+  }
+}

package/components/textarea/textarea.js

@@ -1,124 +1,17 @@
 /**
- * <textarea-ui> — Multiline text input. The host IS the interactive surface.
- * Uses contenteditable for text entry, ElementInternals for form participation.
- * No native <textarea> inside.
+ * `<textarea-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UITextarea } from '@adia-ai/web-components/components/textarea/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
+import { defineIfFree } from '../../core/register.js';
+import { UITextarea } from './class.js';
 
-class UITextarea extends UIFormElement {
-  static properties = {
-    ...UIFormElement.properties,
-    placeholder: { type: String,  default: '', reflect: true },
-    label:       { type: String,  default: '', reflect: true },
-    rows:        { type: Number,  default: 3, reflect: true },
-    resize:      { type: String,  default: 'vertical', reflect: true },
-  };
-
-  static template = () => null;
-
-  #textEl = null;
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'textbox');
-    this.setAttribute('aria-multiline', 'true');
-
-    if (!this.querySelector('[slot="text"]')) {
-      this.innerHTML = `
-        ${this.label ? `<label slot="label" label="${this.label}"></label>` : ''}
-        <div slot="text" contenteditable="plaintext-only" tabindex="0"
-             ${this.value ? '' : 'data-empty=""'}
-             data-placeholder="${this.placeholder}"></div>
-      `;
-    }
-
-    this.#textEl = this.querySelector('[slot="text"]');
-    if (this.value) this.#textEl.textContent = this.value;
-
-    if (this.#textEl) {
-      this.#textEl.addEventListener('input', this.#onInput);
-      this.#textEl.addEventListener('keydown', this.#onKeydown);
-      this.#textEl.addEventListener('blur', this.#onBlur);
-      this.#textEl.addEventListener('paste', this.#onPaste);
-    }
-  }
-
-  render() {
-    if (!this.#textEl) return;
-
-    this.#textEl.setAttribute('data-placeholder', this.placeholder);
-
-    if (this.disabled || this.readonly) {
-      this.#textEl.contentEditable = 'false';
-    } else {
-      this.#textEl.contentEditable = 'plaintext-only';
-    }
-
-    // Sync programmatic `value` assignments (form.reset(), trait writes,
-    // controlled-input patterns) into the contenteditable surface. Skip
-    // when the surface already matches to avoid clobbering an in-flight
-    // edit's caret.
-    const text = this.value || '';
-    if (this.#textEl.textContent !== text) {
-      this.#textEl.textContent = text;
-      this.#textEl.toggleAttribute('data-empty', !text);
-    }
-
-    const label = this.querySelector('[slot="label"]');
-    if (label && this.label) label.setAttribute('label', this.label);
-
-    this.setAttribute('aria-label', this.label || this.placeholder || '');
-  }
-
-  #onInput = () => {
-    const text = this.#textEl.textContent || '';
-    this.value = text;
-    this.#textEl.toggleAttribute('data-empty', !text);
-    this.syncValue(text);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #onKeydown = (e) => {
-    // Enter without shift submits; shift+enter inserts newline
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault();
-      this.dispatchEvent(new Event('submit', { bubbles: true }));
-    }
-  };
-
-  #onBlur = () => {
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #onPaste = (e) => {
-    e.preventDefault();
-    const text = e.clipboardData?.getData('text/plain') || '';
-    document.execCommand('insertText', false, text);
-  };
-
-  focus() { this.#textEl?.focus(); }
-
-  clear() {
-    this.value = '';
-    if (this.#textEl) {
-      this.#textEl.textContent = '';
-      this.#textEl.setAttribute('data-empty', '');
-    }
-    this.syncValue('');
-  }
-
-  disconnected() {
-    super.disconnected();
-    if (this.#textEl) {
-      this.#textEl.removeEventListener('input', this.#onInput);
-      this.#textEl.removeEventListener('keydown', this.#onKeydown);
-      this.#textEl.removeEventListener('blur', this.#onBlur);
-      this.#textEl.removeEventListener('paste', this.#onPaste);
-    }
-    this.#textEl = null;
-  }
-}
-customElements.define('textarea-ui', UITextarea);
+defineIfFree('textarea-ui', UITextarea);
 
 export { UITextarea };

package/components/timeline/class.js

@@ -0,0 +1,176 @@
+/**
+ * Non-side-effect class export for `<timeline-ui>` (+ co-located primitives).
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/timeline`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <timeline-ui> — Vertical (or horizontal) event / progress log.
+ *
+ * Each <timeline-item-ui> is one entry, with its own state via the `status`
+ * enum (idle | active | completed | error), optional icon, duration, and an
+ * expandable outcomes list. `[spinner]` is an orthogonal presentation hint
+ * that animates the dot as a ring when combined with `status="active"`.
+ *
+ *   <timeline-ui>
+ *     <timeline-item-ui text="Shipped"   time="2h ago" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="Delivery"  time="now"    status="active" spinner></timeline-item-ui>
+ *     <timeline-item-ui text="Received"></timeline-item-ui>
+ *   </timeline-ui>
+ *
+ * For agent reasoning / pipeline views, set size="sm" and use
+ *   duration, outcomes, spinner, status="error"
+ *
+ *   <timeline-ui size="sm">
+ *     <timeline-item-ui text="search" duration="850ms" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="generate" status="active" spinner></timeline-item-ui>
+ *   </timeline-ui>
+ *
+ * For wizard / numbered-circle patterns, use the dedicated <stepper-ui>.
+ *
+ * Attributes (container):
+ *   orientation — vertical (default) | horizontal
+ *   size        — md (default) | sm
+ *
+ * Attributes (item):
+ *   text        — primary label
+ *   description — secondary text (optional)
+ *   time        — right-aligned timestamp (optional; mutually exclusive with duration)
+ *   duration    — right-aligned duration label (e.g. "850ms", "2s"); also set when live=true
+ *   icon        — icon-ui name (replaces the dot when set)
+ *   variant     — default | success | accent | warning | danger  (colors the dot/icon)
+ *   completed   — boolean; renders "done" state
+ *   active      — boolean; renders "active" state
+ *   error       — boolean; renders "error" state (red dot)
+ *   spinner     — boolean; spinning dot while active
+ *
+ * JS (item):
+ *   .outcomes = string[]    // renders an expandable sub-list under the row
+ */
+
+import { UIElement } from '../../core/element.js';
+
+// ── Container ──────────────────────────────────────────────────
+
+export class UITimeline extends UIElement {
+  static properties = {
+    orientation: { type: String, default: 'vertical', reflect: true },
+    size:        { type: String, default: 'md',       reflect: true },
+  };
+
+  static template = () => null;
+
+  render() {
+    const items = [...this.querySelectorAll(':scope > timeline-item-ui')];
+    for (const item of items) item.removeAttribute('data-last');
+    const last = items[items.length - 1];
+    if (last) last.setAttribute('data-last', '');
+  }
+}
+
+export class UITimelineItem extends UIElement {
+  static properties = {
+    text:        { type: String,  default: '',        reflect: true },
+    description: { type: String,  default: '',        reflect: true },
+    time:        { type: String,  default: '',        reflect: true },
+    duration:    { type: String,  default: '',        reflect: true },
+    icon:        { type: String,  default: '',        reflect: true },
+    variant:     { type: String,  default: 'default', reflect: true },
+    status:      { type: String,  default: 'idle',    reflect: true },
+    spinner:     { type: Boolean, default: false,     reflect: true },
+  };
+
+  static template = () => null;
+
+  #outcomes = [];
+  #expanded = false;
+
+  get outcomes() { return this.#outcomes; }
+  set outcomes(v) {
+    this.#outcomes = Array.isArray(v) ? v.slice() : [];
+    this.render();
+  }
+
+  connected() {
+    if (!this.querySelector(':scope > [slot="label"]')) {
+      // Author provided just text/time — stamp the default slot structure
+      this.innerHTML = `
+        <span slot="label"></span>
+        <span slot="description"></span>
+        <span slot="time"></span>
+      `;
+    }
+  }
+
+  render() {
+    const label = this.querySelector(':scope > [slot="label"]');
+    const desc  = this.querySelector(':scope > [slot="description"]');
+    const time  = this.querySelector(':scope > [slot="time"]');
+    if (label) label.textContent = this.text;
+    if (desc)  desc.textContent  = this.description;
+    if (time)  time.textContent  = this.duration || this.time;
+
+    if (this.icon) {
+      let iconEl = this.querySelector(':scope > [slot="icon"]');
+      if (!iconEl) {
+        iconEl = document.createElement('icon-ui');
+        iconEl.setAttribute('slot', 'icon');
+        this.prepend(iconEl);
+      }
+      iconEl.setAttribute('name', this.icon);
+    } else {
+      this.querySelector(':scope > [slot="icon"]')?.remove();
+    }
+
+    // Outcomes sub-list + toggle chevron
+    let body = this.querySelector(':scope > [slot="outcomes"]');
+    if (this.#outcomes.length > 0) {
+      if (!body) {
+        body = document.createElement('ul');
+        body.setAttribute('slot', 'outcomes');
+        this.appendChild(body);
+      }
+      body.innerHTML = '';
+      for (const o of this.#outcomes) {
+        const li = document.createElement('li');
+        li.textContent = o;
+        body.appendChild(li);
+      }
+      body.hidden = !this.#expanded;
+
+      // Toggle chevron lives on the row — we stamp a button once
+      let toggle = this.querySelector(':scope > [data-timeline-toggle]');
+      if (!toggle) {
+        toggle = document.createElement('button');
+        toggle.type = 'button';
+        toggle.setAttribute('data-timeline-toggle', '');
+        toggle.setAttribute('aria-label', 'Toggle details');
+        toggle.addEventListener('click', (e) => {
+          e.stopPropagation();
+          this.#expanded = !this.#expanded;
+          this.render();
+          this.dispatchEvent(new CustomEvent('timeline-toggle', {
+            bubbles: true, detail: { expanded: this.#expanded },
+          }));
+        });
+        this.appendChild(toggle);
+      }
+      toggle.innerHTML = '';
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('name', this.#expanded ? 'caret-down' : 'caret-right');
+      caret.setAttribute('color', 'muted');
+      caret.setAttribute('size', 'sm');
+      toggle.appendChild(caret);
+    } else {
+      this.querySelector(':scope > [data-timeline-toggle]')?.remove();
+      body?.remove();
+    }
+  }
+}

package/components/timeline/timeline.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<timeline-ui>` — Timeline and step wizard. Two modes: timeline (per-item state) and steps (parent-driven).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/timeline
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run components`, then `npm run codegen:dts` to regenerate;
+ * or hand-author this file fully if rich event types are needed.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UITimeline extends UIElement {
+  /** Layout direction */
+  orientation: 'vertical' | 'horizontal';
+  /** Rail size preset — use `sm` for agent-reasoning/pipeline views; `md` is the default. */
+  size: 'sm' | 'md';
+}