@adia-ai/web-components 0.4.6 → 0.4.8

package/components/popover/popover.js

@@ -1,184 +1,17 @@
 /**
- * <popover-ui trigger="click" placement="bottom-start">
- *   <button-ui slot="trigger" text="Open"></button-ui>
- *   <div slot="content">Popover content here</div>
- * </popover-ui>
+ * `<popover-ui>` — auto-registers the tag on import.
  *
- * Built on the web platform:
- *   • Popover API — content has popover="manual"; showPopover() promotes it
- *     to the top layer (no z-index, no overflow clipping, ESC bubbling handled).
- *   • CSS Anchor Positioning — used natively when supported, JS fallback otherwise
- *     (see @core/anchor.js).
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Triggers: click | hover | manual. ESC closes click/manual popovers.
+ *   import { UIPopover } from '@adia-ai/web-components/components/popover/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import { anchorPopover } from '../../core/anchor.js';
-
-const HOVER_CLOSE_DELAY = 120;
-
-class UIPopover extends UIElement {
-  static properties = {
-    placement: { type: String,  default: 'bottom', reflect: true },
-    gap:       { type: Number,  default: 4, reflect: true },
-    open:      { type: Boolean, default: false, reflect: true },
-    trigger:   { type: String,  default: 'click', reflect: true },
-  };
-
-  static template = () => null;
-
-  #anchorCleanup = null;
-  #bound = false;
-  #hoverTimer = null;
-  #content = null;
-  #rafId = null;
-
-  connected() {
-    const content = this.querySelector('[slot="content"]');
-    if (content) {
-      if (!content.hasAttribute('popover')) content.setAttribute('popover', 'manual');
-      // Sync state when the browser toggles the popover (e.g. light-dismiss, ESC on auto, programmatic).
-      content.addEventListener('toggle', this.#onToggle);
-      this.#content = content;
-    }
-
-    if (!this.#bound) {
-      this.#bound = true;
-
-      if (this.trigger === 'click') {
-        this.addEventListener('click', this.#onClick);
-      }
-
-      if (this.trigger === 'hover') {
-        this.addEventListener('pointerenter', this.#onEnter);
-        this.addEventListener('pointerleave', this.#onLeave);
-        // Also let the pointer cross into the content without closing.
-        if (content) {
-          content.addEventListener('pointerenter', this.#onEnter);
-          content.addEventListener('pointerleave', this.#onLeave);
-        }
-      }
-    }
-  }
-
-  render() {
-    if (this.open) this.#show();
-    else this.#hide();
-  }
-
-  // ── Public API ──
-  show()   { this.open = true; }
-  hide()   { this.open = false; }
-  toggle() { this.open = !this.open; }
-
-  // ── Internal ──
-
-  #show() {
-    const trigger = this.querySelector('[slot="trigger"]');
-    const content = this.#content ?? this.querySelector('[slot="content"]');
-    if (!trigger || !content) return;
-
-    if (!content.matches(':popover-open')) {
-      // try/catch covers test envs (happy-dom) without the API. Known iOS
-      // Safari quirks at the supported floor (light-dismiss broken on
-      // 17.0–18.2, virtual-keyboard-on-input persists past 18.3) are
-      // documented in docs/BROWSER-COMPAT.md §3a.
-      try { content.showPopover(); } catch { /* popover API unavailable — anchor positioning still runs */ }
-    }
-
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = anchorPopover(trigger, content, {
-      placement: this.placement,
-      gap: this.gap,
-    });
-
-    if (this.trigger === 'click' || this.trigger === 'manual') {
-      // Defer to next frame so the opening click doesn't trigger outside-dismiss.
-      this.#rafId = requestAnimationFrame(() => {
-        this.#rafId = null;
-        document.addEventListener('pointerdown', this.#onOutside);
-        document.addEventListener('keydown', this.#onKey);
-      });
-    }
-  }
-
-  #hide() {
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = null;
-
-    const content = this.#content ?? this.querySelector('[slot="content"]');
-    if (content?.matches(':popover-open')) {
-      try { content.hidePopover(); } catch { /* popover API unavailable */ }
-    }
-
-    if (this.#rafId != null) {
-      cancelAnimationFrame(this.#rafId);
-      this.#rafId = null;
-    }
-    document.removeEventListener('pointerdown', this.#onOutside);
-    document.removeEventListener('keydown', this.#onKey);
-  }
-
-  // ── Events ──
-
-  #onClick = (e) => {
-    const trigger = this.querySelector('[slot="trigger"]');
-    if (trigger && (e.target === trigger || trigger.contains(e.target))) {
-      this.open = !this.open;
-    }
-  };
-
-  #onOutside = (e) => {
-    if (!this.open) return;
-    const content = this.#content;
-    // Click inside host or inside the (top-layer) content: keep open.
-    if (this.contains(e.target) || content?.contains(e.target)) return;
-    this.open = false;
-  };
-
-  #onKey = (e) => {
-    if (e.key === 'Escape' && this.open) {
-      e.stopPropagation();
-      this.open = false;
-    }
-  };
-
-  #onEnter = () => {
-    clearTimeout(this.#hoverTimer);
-    this.open = true;
-  };
-
-  #onLeave = () => {
-    clearTimeout(this.#hoverTimer);
-    this.#hoverTimer = setTimeout(() => { this.open = false; }, HOVER_CLOSE_DELAY);
-  };
-
-  #onToggle = (e) => {
-    // Reflect browser-driven state changes (e.g. popover-auto light-dismiss).
-    const nowOpen = e.newState === 'open';
-    if (nowOpen !== this.open) this.open = nowOpen;
-  };
+import { defineIfFree } from '../../core/register.js';
+import { UIPopover } from './class.js';
 
-  disconnected() {
-    clearTimeout(this.#hoverTimer);
-    this.#hide();
-    if (this.trigger === 'click') {
-      this.removeEventListener('click', this.#onClick);
-    }
-    if (this.trigger === 'hover') {
-      this.removeEventListener('pointerenter', this.#onEnter);
-      this.removeEventListener('pointerleave', this.#onLeave);
-      if (this.#content) {
-        this.#content.removeEventListener('pointerenter', this.#onEnter);
-        this.#content.removeEventListener('pointerleave', this.#onLeave);
-      }
-    }
-    this.#content?.removeEventListener('toggle', this.#onToggle);
-    this.#content = null;
-    this.#bound = false;
-  }
-}
+defineIfFree('popover-ui', UIPopover);
 
-customElements.define('popover-ui', UIPopover);
 export { UIPopover };

package/components/progress/class.js

@@ -0,0 +1,74 @@
+/**
+ * Non-side-effect class export for `<progress-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/progress`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <progress-ui value="60"></progress-ui>
+ * <progress-ui variant="spinner"></progress-ui>
+ * <progress-ui></progress-ui>              <!-- indeterminate bar -->
+ *
+ * Progress indicator. Bar (default) or spinner variant.
+ * value null (absent) = indeterminate, 0-100 = determinate.
+ * (Legacy `value="-1"` is still treated as indeterminate for back-compat.)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIProgress extends UIElement {
+  static properties = {
+    value:   { type: Number, default: null,  reflect: true },
+    variant: { type: String, default: 'bar', reflect: true },
+  };
+
+  static template = () => null;
+
+  #track = null;
+  #fill = null;
+
+  connected() {
+    this.setAttribute('role', 'progressbar');
+    this.setAttribute('aria-valuemin', '0');
+    this.setAttribute('aria-valuemax', '100');
+
+    if (this.variant === 'bar') {
+      this.#track = document.createElement('div');
+      this.#track.setAttribute('slot', 'track');
+      this.#fill = document.createElement('div');
+      this.#fill.setAttribute('slot', 'fill');
+      this.#track.appendChild(this.#fill);
+      this.appendChild(this.#track);
+    }
+  }
+
+  render() {
+    const indeterminate = this.value == null || this.value < 0;
+    const clamped = Math.max(0, Math.min(100, this.value));
+
+    this.setAttribute('aria-busy', String(indeterminate));
+
+    if (indeterminate) {
+      this.removeAttribute('aria-valuenow');
+    } else {
+      this.setAttribute('aria-valuenow', String(clamped));
+    }
+
+    if (this.#fill) {
+      this.#fill.style.width = indeterminate ? '100%' : `${clamped}%`;
+    }
+  }
+
+  disconnected() {
+    this.#track?.remove();
+    this.#track = null;
+    this.#fill = null;
+  }
+}

package/components/progress/progress.a2ui.json

@@ -43,6 +43,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {},
     "examples": [
       {
@@ -158,6 +159,9 @@
         "progress",
         "tracker"
       ],
+      "tags": [
+        "LoadingIndicator"
+      ],
       "timeline": [
         "social",
         "post",

package/components/progress/progress.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `<progress-ui>` — Progress indicator. Bar (default) or spinner. Value < 0 = indeterminate.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/progress
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIProgress extends UIElement {
+  /** Current progress. 0..max (or 0..1 when max omitted). null = indeterminate (legacy -1 accepted for back-compat). */
+  value: number;
+  /** Display variant. Structural values (bar, spinner) set the render mode; semantic values (primary/success/warning/danger/info) set the fill color. Prefer the `color` global attribute for color; variant-as-color accepted for back-compat with older exemplars. */
+  variant: 'bar' | 'spinner' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+}

package/components/progress/progress.js

@@ -1,64 +1,17 @@
 /**
- * <progress-ui value="60"></progress-ui>
- * <progress-ui variant="spinner"></progress-ui>
- * <progress-ui></progress-ui>              <!-- indeterminate bar -->
+ * `<progress-ui>` — auto-registers the tag on import.
  *
- * Progress indicator. Bar (default) or spinner variant.
- * value null (absent) = indeterminate, 0-100 = determinate.
- * (Legacy `value="-1"` is still treated as indeterminate for back-compat.)
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIProgress } from '@adia-ai/web-components/components/progress/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIProgress extends UIElement {
-  static properties = {
-    value:   { type: Number, default: null,  reflect: true },
-    variant: { type: String, default: 'bar', reflect: true },
-  };
-
-  static template = () => null;
-
-  #track = null;
-  #fill = null;
-
-  connected() {
-    this.setAttribute('role', 'progressbar');
-    this.setAttribute('aria-valuemin', '0');
-    this.setAttribute('aria-valuemax', '100');
-
-    if (this.variant === 'bar') {
-      this.#track = document.createElement('div');
-      this.#track.setAttribute('slot', 'track');
-      this.#fill = document.createElement('div');
-      this.#fill.setAttribute('slot', 'fill');
-      this.#track.appendChild(this.#fill);
-      this.appendChild(this.#track);
-    }
-  }
-
-  render() {
-    const indeterminate = this.value == null || this.value < 0;
-    const clamped = Math.max(0, Math.min(100, this.value));
-
-    this.setAttribute('aria-busy', String(indeterminate));
-
-    if (indeterminate) {
-      this.removeAttribute('aria-valuenow');
-    } else {
-      this.setAttribute('aria-valuenow', String(clamped));
-    }
-
-    if (this.#fill) {
-      this.#fill.style.width = indeterminate ? '100%' : `${clamped}%`;
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIProgress } from './class.js';
 
-  disconnected() {
-    this.#track?.remove();
-    this.#track = null;
-    this.#fill = null;
-  }
-}
-customElements.define('progress-ui', UIProgress);
+defineIfFree('progress-ui', UIProgress);
 
 export { UIProgress };