@adia-ai/web-components 0.4.5 → 0.4.7

package/components/range/range.js

@@ -1,184 +1,17 @@
 /**
- * <range-input label="Width" value="63" min="0" max="100" step="1" suffix="rem"></range-input>
+ * `<range-ui>` — auto-registers the tag on import.
  *
- * A draggable numeric field — NOT a slider. The entire field is the scrubber surface.
- * Horizontal drag on the value changes it. No track, no thumb.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Layout: [label]  [value] [suffix]
- *   - Label left-aligned, muted
- *   - Value right-aligned, bold, editable via horizontal drag
- *   - Suffix after value, muted
- *   - While dragging: accent highlight on the field
+ *   import { UIRange } from '@adia-ai/web-components/components/range/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-
-class UIRange extends UIFormElement {
-  // Opt out of UIFormElement's per-control `label` deprecation warning.
-  // range-ui's `label` is a first-class API: it renders as the in-track
-  // caption next to the value (the entire field is the scrubber surface)
-  // and the host gets `aria-label` wired from it for proper screen-reader
-  // announcement. Same opt-out rationale as input-ui.
-  static labelDeprecated = false;
-
-  static properties = {
-    ...UIFormElement.properties,
-    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
-    value:  { type: Number,  default: 0,  reflect: true },
-    min:    { type: Number,  default: 0,  reflect: true },
-    max:    { type: Number,  default: 100, reflect: true },
-    step:   { type: Number,  default: 1,  reflect: true },
-    label:  { type: String,  default: '', reflect: true },
-    suffix: { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #fieldEl = null;
-  #valueEl = null;
-  #dragging = false;
-  #startX = 0;
-  #startVal = 0;
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'spinbutton');
-    this.setAttribute('tabindex', '0');
-
-    if (!this.querySelector('[slot="field"]')) {
-      const inner = `
-        <span slot="label">${this.label}</span>
-        <span slot="value">${this.#format(this.value)}</span>
-        ${this.suffix ? `<span slot="suffix">${this.suffix}</span>` : ''}
-      `;
-      this.innerHTML = `
-        <div slot="field">
-          <div slot="layer" data-layer="base">${inner}</div>
-          <div slot="layer" data-layer="fill" aria-hidden="true">${inner}</div>
-        </div>
-      `;
-    }
-
-    this.#fieldEl = this.querySelector('[slot="field"]');
-    this.#valueEl = this.querySelector('[data-layer="base"] [slot="value"]');
-
-    if (this.#fieldEl) this.#fieldEl.addEventListener('pointerdown', this.#onPointerDown);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    if (!this.#fieldEl) return;
-
-    const formatted = this.#format(this.value);
-    if (this.#valueEl) this.#valueEl.textContent = formatted;
-    const fillValueEl = this.querySelector('[data-layer="fill"] [slot="value"]');
-    if (fillValueEl) fillValueEl.textContent = formatted;
-
-    // Update fill percentage via CSS var (drives clip-path on fill layer)
-    const range = this.max - this.min;
-    const pct = range > 0 ? ((this.value - this.min) / range) * 100 : 0;
-    this.style.setProperty('--range-fill-pct', `${pct}%`);
-
-    this.setAttribute('aria-valuemin', this.min);
-    this.setAttribute('aria-valuemax', this.max);
-    this.setAttribute('aria-valuenow', this.value);
-    this.setAttribute('aria-valuetext', `${this.value}${this.suffix ? ' ' + this.suffix : ''}`);
-    this.setAttribute('aria-label', this.label || '');
-
-    this.syncValue(String(this.value));
-  }
-
-  #format(v) {
-    // Show decimal places matching step precision
-    const decimals = (String(this.step).split('.')[1] || '').length;
-    return decimals > 0 ? v.toFixed(decimals) : String(v);
-  }
-
-  #snap(raw) {
-    const stepped = Math.round((raw - this.min) / this.step) * this.step + this.min;
-    return Math.max(this.min, Math.min(this.max, parseFloat(stepped.toFixed(10))));
-  }
-
-  #setValue(v) {
-    const snapped = this.#snap(v);
-    if (snapped === this.value) return;
-    this.value = snapped;
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-  }
-
-  // ── Pointer drag ──
-
-  #valueFromX(clientX) {
-    const rect = this.#fieldEl.getBoundingClientRect();
-    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
-    return this.#snap(this.min + ratio * (this.max - this.min));
-  }
-
-  #onPointerDown = (e) => {
-    if (this.disabled) return;
-    e.preventDefault();
-
-    // Click: jump to position immediately
-    this.#setValue(this.#valueFromX(e.clientX));
-
-    // Then start drag from that position
-    this.#dragging = true;
-    this.#startX = e.clientX;
-    this.#startVal = this.value;
-    this.setAttribute('data-dragging', '');
-    this.#fieldEl.setPointerCapture(e.pointerId);
-    this.#fieldEl.addEventListener('pointermove', this.#onPointerMove);
-    this.#fieldEl.addEventListener('pointerup', this.#onPointerUp);
-  };
-
-  #onPointerMove = (e) => {
-    if (!this.#dragging) return;
-    const dx = e.clientX - this.#startX;
-    // 1:1 — dragging across the full field width traverses the full range
-    const fieldWidth = this.#fieldEl.getBoundingClientRect().width;
-    const range = this.max - this.min;
-    const delta = (dx / fieldWidth) * range;
-    this.#setValue(this.#startVal + delta);
-  };
-
-  #onPointerUp = (e) => {
-    this.#dragging = false;
-    this.removeAttribute('data-dragging');
-    this.#fieldEl.releasePointerCapture(e.pointerId);
-    this.#fieldEl.removeEventListener('pointermove', this.#onPointerMove);
-    this.#fieldEl.removeEventListener('pointerup', this.#onPointerUp);
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  // ── Keyboard ──
-
-  #onKey = (e) => {
-    if (this.disabled) return;
-    let v = this.value;
-    switch (e.key) {
-      case 'ArrowRight': case 'ArrowUp':   v += this.step; break;
-      case 'ArrowLeft':  case 'ArrowDown': v -= this.step; break;
-      case 'Home': v = this.min; break;
-      case 'End':  v = this.max; break;
-      case 'PageUp':   v += this.step * 10; break;
-      case 'PageDown': v -= this.step * 10; break;
-      default: return;
-    }
-    e.preventDefault();
-    this.#setValue(v);
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
+import { defineIfFree } from '../../core/register.js';
+import { UIRange } from './class.js';
 
-  disconnected() {
-    super.disconnected();
-    this.#fieldEl?.removeEventListener('pointerdown', this.#onPointerDown);
-    this.#fieldEl?.removeEventListener('pointermove', this.#onPointerMove);
-    this.#fieldEl?.removeEventListener('pointerup', this.#onPointerUp);
-    this.removeEventListener('keydown', this.#onKey);
-    this.#fieldEl = null;
-    this.#valueEl = null;
-  }
-}
-customElements.define('range-ui', UIRange);
+defineIfFree('range-ui', UIRange);
 
 export { UIRange };

package/components/rating/class.js

@@ -0,0 +1,148 @@
+/**
+ * Non-side-effect class export for `<rating-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/rating`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <rating-ui> — Discrete pictorial rating (stars by default).
+ *
+ * Supports keyboard (arrows), mouse hover preview, and 0.5-step precision.
+ * The host is role=slider per ARIA APG for custom rating widgets.
+ *
+ *   <rating-ui value="3.5" max="5" allow-half name="review"></rating-ui>
+ *   <rating-ui value="4" icon="heart" variant="accent"></rating-ui>
+ *   <rating-ui value="5" readonly></rating-ui>
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export class UIRating extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
+    value:     { type: Number,  default: 0, reflect: true },
+    max:       { type: Number,  default: 5, reflect: true },
+    icon:      { type: String,  default: 'star', reflect: true },
+    readonly:  { type: Boolean, default: false, reflect: true },
+    allowHalf: { type: Boolean, default: false, reflect: true, attribute: 'allow-half' },
+    size:      { type: String,  default: 'md', reflect: true },
+  };
+
+  static template = () => null;
+
+  #hoverValue = null;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'slider');
+    this.setAttribute('aria-orientation', 'horizontal');
+    this.setAttribute('aria-valuemin', '0');
+    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', this.readonly ? '-1' : '0');
+    this.addEventListener('pointermove', this.#onPointer);
+    this.addEventListener('pointerleave', this.#onLeave);
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    const max = Number(this.max) || 5;
+    const display = this.#hoverValue ?? (Number(this.value) || 0);
+
+    const symbols = Array.from({ length: max }, (_, i) => {
+      const slotValue = i + 1;
+      const fill =
+        display >= slotValue        ? 'full' :
+        display >= slotValue - 0.5  ? 'half' :
+                                      'empty';
+      return `
+        <span data-rating-symbol data-fill="${fill}" aria-hidden="true">
+          <icon-ui name="${this.icon}" data-rating-symbol-bg></icon-ui>
+          <icon-ui name="${this.icon}" weight="fill" data-rating-symbol-fg></icon-ui>
+        </span>
+      `;
+    }).join('');
+
+    this.innerHTML = symbols;
+    this.setAttribute('aria-valuemax', String(max));
+    this.setAttribute('aria-valuenow', String(Number(this.value) || 0));
+    this.setAttribute('aria-valuetext', `${Number(this.value) || 0} out of ${max}`);
+    if (this.readonly) this.setAttribute('aria-readonly', 'true');
+    else this.removeAttribute('aria-readonly');
+  }
+
+  #valueFromEvent(e) {
+    const symbols = [...this.querySelectorAll('[data-rating-symbol]')];
+    const target = symbols.find(s => s.contains(e.target));
+    if (!target) return null;
+    const idx = symbols.indexOf(target);
+    if (idx === -1) return null;
+    if (this.allowHalf) {
+      const rect = target.getBoundingClientRect();
+      const isHalf = (e.clientX - rect.left) < rect.width / 2;
+      return idx + (isHalf ? 0.5 : 1);
+    }
+    return idx + 1;
+  }
+
+  #onPointer = (e) => {
+    if (this.readonly || this.disabled) return;
+    const v = this.#valueFromEvent(e);
+    if (v == null) return;
+    if (v !== this.#hoverValue) {
+      this.#hoverValue = v;
+      this.render();
+    }
+  };
+
+  #onLeave = () => {
+    if (this.#hoverValue == null) return;
+    this.#hoverValue = null;
+    this.render();
+  };
+
+  #onClick = (e) => {
+    if (this.readonly || this.disabled) return;
+    const v = this.#valueFromEvent(e);
+    if (v == null) return;
+    this.#commit(v);
+  };
+
+  #onKey = (e) => {
+    if (this.readonly || this.disabled) return;
+    const step = this.allowHalf ? 0.5 : 1;
+    const max = Number(this.max) || 5;
+    const v = Number(this.value) || 0;
+    let next = v;
+    if (e.key === 'ArrowRight' || e.key === 'ArrowUp')   { next = Math.min(max, v + step); }
+    else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') { next = Math.max(0, v - step); }
+    else if (e.key === 'Home') next = 0;
+    else if (e.key === 'End')  next = max;
+    else return;
+    e.preventDefault();
+    this.#commit(next);
+  };
+
+  #commit(v) {
+    this.value = v;
+    this.#hoverValue = null;
+    this.syncValue(String(v));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+    this.render();
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.removeEventListener('pointermove', this.#onPointer);
+    this.removeEventListener('pointerleave', this.#onLeave);
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}

package/components/rating/rating.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `<rating-ui>` — Star rating input (or other icon set).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/rating
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export interface RatingChangeEventDetail {
+  value: number;
+}
+export type RatingChangeEvent = CustomEvent<RatingChangeEventDetail>;
+
+export class UIRating extends UIFormElement {
+  /** Numeric rating value — overrides UIFormElement.value (which is String). */
+  value: number;
+  /** Maximum rating — number of icons rendered. */
+  max: number;
+  /** Phosphor icon name (default: `star`). */
+  icon: string;
+  /** Read-only mode (display only; no interaction). */
+  readonly: boolean;
+  /** Allow half-step values (0.5, 1.5, …). */
+  allowHalf: boolean;
+  size: 'sm' | 'md' | 'lg';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIRating, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: RatingChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/rating/rating.js

@@ -1,138 +1,17 @@
 /**
- * <rating-ui> — Discrete pictorial rating (stars by default).
+ * `<rating-ui>` — auto-registers the tag on import.
  *
- * Supports keyboard (arrows), mouse hover preview, and 0.5-step precision.
- * The host is role=slider per ARIA APG for custom rating widgets.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- *   <rating-ui value="3.5" max="5" allow-half name="review"></rating-ui>
- *   <rating-ui value="4" icon="heart" variant="accent"></rating-ui>
- *   <rating-ui value="5" readonly></rating-ui>
+ *   import { UIRating } from '@adia-ai/web-components/components/rating/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-
-class UIRating extends UIFormElement {
-  static properties = {
-    ...UIFormElement.properties,
-    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
-    value:     { type: Number,  default: 0, reflect: true },
-    max:       { type: Number,  default: 5, reflect: true },
-    icon:      { type: String,  default: 'star', reflect: true },
-    readonly:  { type: Boolean, default: false, reflect: true },
-    allowHalf: { type: Boolean, default: false, reflect: true, attribute: 'allow-half' },
-    size:      { type: String,  default: 'md', reflect: true },
-  };
-
-  static template = () => null;
-
-  #hoverValue = null;
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'slider');
-    this.setAttribute('aria-orientation', 'horizontal');
-    this.setAttribute('aria-valuemin', '0');
-    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', this.readonly ? '-1' : '0');
-    this.addEventListener('pointermove', this.#onPointer);
-    this.addEventListener('pointerleave', this.#onLeave);
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    const max = Number(this.max) || 5;
-    const display = this.#hoverValue ?? (Number(this.value) || 0);
-
-    const symbols = Array.from({ length: max }, (_, i) => {
-      const slotValue = i + 1;
-      const fill =
-        display >= slotValue        ? 'full' :
-        display >= slotValue - 0.5  ? 'half' :
-                                      'empty';
-      return `
-        <span data-rating-symbol data-fill="${fill}" aria-hidden="true">
-          <icon-ui name="${this.icon}" data-rating-symbol-bg></icon-ui>
-          <icon-ui name="${this.icon}" weight="fill" data-rating-symbol-fg></icon-ui>
-        </span>
-      `;
-    }).join('');
-
-    this.innerHTML = symbols;
-    this.setAttribute('aria-valuemax', String(max));
-    this.setAttribute('aria-valuenow', String(Number(this.value) || 0));
-    this.setAttribute('aria-valuetext', `${Number(this.value) || 0} out of ${max}`);
-    if (this.readonly) this.setAttribute('aria-readonly', 'true');
-    else this.removeAttribute('aria-readonly');
-  }
-
-  #valueFromEvent(e) {
-    const symbols = [...this.querySelectorAll('[data-rating-symbol]')];
-    const target = symbols.find(s => s.contains(e.target));
-    if (!target) return null;
-    const idx = symbols.indexOf(target);
-    if (idx === -1) return null;
-    if (this.allowHalf) {
-      const rect = target.getBoundingClientRect();
-      const isHalf = (e.clientX - rect.left) < rect.width / 2;
-      return idx + (isHalf ? 0.5 : 1);
-    }
-    return idx + 1;
-  }
-
-  #onPointer = (e) => {
-    if (this.readonly || this.disabled) return;
-    const v = this.#valueFromEvent(e);
-    if (v == null) return;
-    if (v !== this.#hoverValue) {
-      this.#hoverValue = v;
-      this.render();
-    }
-  };
-
-  #onLeave = () => {
-    if (this.#hoverValue == null) return;
-    this.#hoverValue = null;
-    this.render();
-  };
-
-  #onClick = (e) => {
-    if (this.readonly || this.disabled) return;
-    const v = this.#valueFromEvent(e);
-    if (v == null) return;
-    this.#commit(v);
-  };
-
-  #onKey = (e) => {
-    if (this.readonly || this.disabled) return;
-    const step = this.allowHalf ? 0.5 : 1;
-    const max = Number(this.max) || 5;
-    const v = Number(this.value) || 0;
-    let next = v;
-    if (e.key === 'ArrowRight' || e.key === 'ArrowUp')   { next = Math.min(max, v + step); }
-    else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') { next = Math.max(0, v - step); }
-    else if (e.key === 'Home') next = 0;
-    else if (e.key === 'End')  next = max;
-    else return;
-    e.preventDefault();
-    this.#commit(next);
-  };
-
-  #commit(v) {
-    this.value = v;
-    this.#hoverValue = null;
-    this.syncValue(String(v));
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-    this.render();
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIRating } from './class.js';
 
-  disconnected() {
-    super.disconnected();
-    this.removeEventListener('pointermove', this.#onPointer);
-    this.removeEventListener('pointerleave', this.#onLeave);
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKey);
-  }
-}
+defineIfFree('rating-ui', UIRating);
 
-customElements.define('rating-ui', UIRating);
 export { UIRating };

package/components/richtext/class.js

@@ -0,0 +1,87 @@
+/**
+ * Non-side-effect class export for `<richtext-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/richtext`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement } from '../../core/element.js';
+import { renderMarkdown } from '../../core/markdown.js';
+
+/**
+ * <richtext-ui> — Renders markdown to styled HTML.
+ *
+ * Takes markdown as a `src` URL (fetched) or `markdown` property (inline),
+ * converts it to HTML, and displays it with prose-appropriate typography.
+ *
+ * Usage:
+ *   <richtext-ui src="/docs/readme.md"></richtext-ui>
+ *   <richtext-ui markdown="# Hello\nSome **bold** text."></richtext-ui>
+ *
+ * Programmatic:
+ *   const el = document.querySelector('richtext-ui');
+ *   el.markdown = '# Title\nParagraph text.';
+ */
+export class UIRichText extends UIElement {
+  static properties = {
+    src:      { type: String, default: '', reflect: true },
+    // Markdown bodies can be arbitrarily large; reflecting to the attribute
+    // would bloat the DOM (and break parsing on multi-line content with
+    // unescaped quotes). The property is the source of truth.
+    markdown: { type: String, default: '', reflect: false },
+  };
+
+  static template = () => null;
+
+  #bodyEl = null;
+  #lastSrc = '';
+  #lastMd = '';
+
+  connected() {
+    if (!this.#bodyEl) {
+      this.#bodyEl = document.createElement('div');
+      this.#bodyEl.setAttribute('data-richtext-body', '');
+      this.appendChild(this.#bodyEl);
+    }
+  }
+
+  render() {
+    // Fetch from URL
+    if (this.src && this.src !== this.#lastSrc) {
+      this.#lastSrc = this.src;
+      this.#lastMd = '';
+      this.#load();
+      return;
+    }
+
+    // Inline markdown
+    if (this.markdown && this.markdown !== this.#lastMd) {
+      this.#lastMd = this.markdown;
+      this.#lastSrc = '';
+      this.#bodyEl.innerHTML = renderMarkdown(this.markdown);
+    }
+  }
+
+  async #load() {
+    try {
+      const res = await fetch(this.src);
+      if (!this.isConnected) return;
+      if (!res.ok) {
+        this.#bodyEl.innerHTML = `<p>Failed to load: ${this.src}</p>`;
+        return;
+      }
+      const md = await res.text();
+      if (!this.isConnected) return;
+      this.#bodyEl.innerHTML = renderMarkdown(md);
+    } catch (e) {
+      if (!this.isConnected) return;
+      this.#bodyEl.innerHTML = `<p>Error: ${e.message}</p>`;
+    }
+  }
+}

package/components/richtext/richtext.a2ui.json

@@ -73,7 +73,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "tags": [
+        "markdown",
+        "md-render",
+        "rich-text"
+      ]
+    },
     "tag": "richtext-ui",
     "tokens": {},
     "traits": [],

package/components/richtext/richtext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<richtext-ui>` — Renders markdown to styled HTML.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/richtext
+ *
+ * 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 UIRichtext extends UIElement {
+  /** Component property: markdown. */
+  markdown: string;
+  /** Source URL (image, iframe, etc.). */
+  src: string;
+}