@adia-ai/web-components 0.4.5 → 0.4.7

package/components/drawer/class.js

@@ -0,0 +1,306 @@
+/**
+ * Non-side-effect class export for `<drawer-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/drawer`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <drawer-ui> — Slide-out panel anchored to a viewport edge.
+ *
+ * Uses native <dialog> for focus trapping, Escape key, and ::backdrop.
+ * Content panel slides in/out with CSS transitions.
+ * Exit animation plays before dialog.close() via [data-closing].
+ *
+ * Authoring — card-ui-style tags (recommended):
+ *   <drawer-ui side="right" size="md">
+ *     <header>Title block</header>
+ *     <section>Body content</section>
+ *     <footer>Action buttons</footer>
+ *   </drawer-ui>
+ *
+ * Authoring — explicit slots (also supported):
+ *   <drawer-ui>
+ *     <header slot="header">…</header>
+ *     <section slot="body">…</section>
+ *     <footer slot="footer">…</footer>
+ *   </drawer-ui>
+ *
+ * Title-only (stamps an empty header with a close button):
+ *   <drawer-ui text="Settings" side="right"></drawer-ui>
+ *
+ * API:
+ *   drawer.show() · drawer.hide() · drawer.open = true|false
+ *
+ * Events:
+ *   close — fired after the drawer finishes closing
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIDrawer extends UIElement {
+  #bound = false;
+  #closing = false;
+  #previousFocus = null;
+  #closeTimer = null;
+  #dialogRef = null;
+
+  static properties = {
+    text:      { type: String,  default: '', reflect: true },
+    side:      { type: String,  default: 'right', reflect: true },
+    size:      { type: String,  default: 'md', reflect: true },
+    permanent: { type: Boolean, default: false, reflect: true },
+    open:      { type: Boolean, default: false, reflect: true },
+  };
+
+  static parts = {
+    dialog: '<dialog slot="dialog"></dialog>',
+    panel:  '<div slot="panel"></div>',
+    header: '<header slot="header"></header>',
+    close:  '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
+    body:   '<section slot="body"></section>',
+    footer: '<footer slot="footer"></footer>',
+  };
+
+  // No template — drawer composes from authored light-DOM children. An empty
+  // html`` result would trigger stamp() → replaceChildren(), wiping authored
+  // [slot=header|body|footer] before render() can migrate them into the panel.
+
+  constructor() {
+    super();
+    // Safari requires <dialog>.showModal() to be invoked synchronously inside
+    // the click handler. The reactive system schedules render() in a microtask
+    // after the property change, which Safari treats as outside the user-gesture
+    // window and silently no-ops the showModal. Wrap the auto-installed `open`
+    // setter so dialog state syncs in the same synchronous frame as the
+    // assignment. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+    const desc = Object.getOwnPropertyDescriptor(this, 'open');
+    if (desc?.set) {
+      const origSet = desc.set;
+      Object.defineProperty(this, 'open', {
+        get: desc.get,
+        set: (v) => {
+          origSet.call(this, v);
+          this.#syncDialog();
+        },
+        configurable: true,
+      });
+    }
+  }
+
+  #onPress = (e) => {
+    if (e.target.closest('[slot="close"]')) this.open = false;
+  };
+
+  #onDialogCancel = (e) => {
+    e.preventDefault();
+    if (!this.permanent) this.open = false;
+  };
+
+  #onDialogClose = () => {
+    this.open = false;
+    this.#previousFocus?.focus();
+    this.#previousFocus = null;
+    this.dispatchEvent(new Event('close', { bubbles: true }));
+  };
+
+  #onDialogClick = (e) => {
+    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
+  };
+
+  connected() {
+    this.addEventListener('press', this.#onPress);
+
+    // Bind dialog listeners as soon as the dialog part is available.
+    const dialog = this.ensure('dialog');
+    if (dialog && !this.#bound) {
+      this.#bound = true;
+      this.#dialogRef = dialog;
+      dialog.addEventListener('cancel', this.#onDialogCancel);
+      dialog.addEventListener('close', this.#onDialogClose);
+      dialog.addEventListener('click', this.#onDialogClick);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('press', this.#onPress);
+    if (this.#dialogRef) {
+      this.#dialogRef.removeEventListener('cancel', this.#onDialogCancel);
+      this.#dialogRef.removeEventListener('close', this.#onDialogClose);
+      this.#dialogRef.removeEventListener('click', this.#onDialogClick);
+    }
+    if (this.#closeTimer != null) {
+      clearTimeout(this.#closeTimer);
+      this.#closeTimer = null;
+    }
+    this.#bound = false;
+    this.#dialogRef = null;
+  }
+
+  #getDuration() {
+    const raw = getComputedStyle(this).getPropertyValue('--drawer-duration').trim();
+    return parseFloat(raw) || 200;
+  }
+
+  /**
+   * Adopt a slotted part into the panel. Accepts either an explicit
+   * [slot="X"] element OR a bare tag matching the card-ui convention
+   * (<header> → header, <section> → body, <footer> → footer). The tag is only
+   * adopted when no slot attribute is set, so authors can still opt into
+   * explicit slotting. The slot attribute is normalized onto the adopted
+   * element so downstream CSS selectors (`[slot="header"]`) match in both
+   * cases.
+   */
+  #adoptSlot(slot, panel, mode = 'append') {
+    const fallbackTag = { header: 'header', body: 'section', footer: 'footer' }[slot];
+    const isMatch = (c) => c.getAttribute('slot') === slot
+      || (fallbackTag && !c.getAttribute('slot') && c.localName === fallbackTag);
+
+    const inDirect = [...this.children].find(isMatch);
+    const inPanel  = [...panel.children].find(c => c.getAttribute('slot') === slot);
+
+    if (inDirect && inPanel && inDirect !== inPanel) {
+      // User provided their own after we stamped a default — drop the stamp.
+      inPanel.remove();
+    }
+
+    const el = inDirect || inPanel || (() => {
+      const blueprint = this.constructor._pp?.[slot];
+      if (!blueprint) return null;
+      const clone = blueprint.cloneNode(true);
+      clone.setAttribute('data-stamped', '');
+      return clone;
+    })();
+    if (!el) return null;
+
+    if (el.getAttribute('slot') !== slot) el.setAttribute('slot', slot);
+
+    if (el.parentElement !== panel) {
+      if (mode === 'prepend') panel.prepend(el);
+      else panel.appendChild(el);
+    }
+    return el;
+  }
+
+  render() {
+    const dialog = this.ensure('dialog');
+
+    if (this.text) {
+      dialog.setAttribute('aria-label', this.text);
+      this.setAttribute('aria-label', this.text);
+    } else {
+      dialog.removeAttribute('aria-label');
+      this.removeAttribute('aria-label');
+    }
+
+    const panel = this.ensure('panel');
+    if (panel.parentElement !== dialog) dialog.appendChild(panel);
+
+    const header = this.#adoptSlot('header', panel, 'prepend');
+
+    // text="…" shorthand: stamp a [slot="heading"] into the header so the
+    // card-ui grid picks it up. Any author-supplied heading wins.
+    if (header) {
+      let stampedHeading = header.querySelector(':scope > [slot="heading"][data-stamped]');
+      const hasAuthorHeading = [...header.children].some(c =>
+        !c.hasAttribute('data-stamped') &&
+        (c.getAttribute('slot') === 'heading' || /^h[1-6]$/.test(c.localName))
+      );
+      if (this.text && !hasAuthorHeading) {
+        if (!stampedHeading) {
+          stampedHeading = document.createElement('span');
+          stampedHeading.setAttribute('slot', 'heading');
+          stampedHeading.setAttribute('data-stamped', '');
+          header.prepend(stampedHeading);
+        }
+        if (stampedHeading.textContent !== this.text) stampedHeading.textContent = this.text;
+      } else if (stampedHeading) {
+        stampedHeading.remove();
+      }
+    }
+
+    if (!this.permanent) {
+      const close = this.ensure('close');
+      if (header && close.parentElement !== header) header.appendChild(close);
+    } else {
+      this.drop('close');
+    }
+
+    // Body — multiple sections allowed (card-ui parity). Accepts either
+    // bare <section> tags or explicit [slot="body"]. If the author provides
+    // none, stamp an empty default so title-only drawers still lay out.
+    const authorSections = [...this.children].filter(c =>
+      c.getAttribute('slot') === 'body'
+      || (c.localName === 'section' && !c.getAttribute('slot'))
+    );
+    if (authorSections.length === 0) {
+      this.#adoptSlot('body', panel, 'append');
+    } else {
+      for (const s of authorSections) {
+        if (s.getAttribute('slot') !== 'body') s.setAttribute('slot', 'body');
+        if (s.parentElement !== panel) panel.appendChild(s);
+      }
+    }
+
+    // Footer is opt-in — only mounted if the author supplied one (either
+    // [slot="footer"] or a bare <footer> tag, card-ui style).
+    const userFooter = [...this.children].find(c =>
+      c.getAttribute('slot') === 'footer' || (!c.getAttribute('slot') && c.localName === 'footer')
+    );
+    if (userFooter) {
+      if (userFooter.getAttribute('slot') !== 'footer') userFooter.setAttribute('slot', 'footer');
+      if (userFooter.parentElement !== panel) panel.appendChild(userFooter);
+    }
+
+    // Sync open state — also syncs synchronously from the `open` setter
+    // (see constructor) so showModal() runs in the click handler's gesture
+    // frame on Safari.
+    this.#syncDialog();
+  }
+
+  #syncDialog() {
+    const dialog = this.#dialogRef;
+    if (!dialog) return;
+    if (this.open && !dialog.open) {
+      this.#closing = false;
+      this.#previousFocus = document.activeElement;
+      dialog.showModal();
+      // Synchronous reflow instead of rAF — Safari throttles
+      // requestAnimationFrame when a top-layer dialog is open, sometimes
+      // delaying [data-open] (and the slide-in transition) by tens of
+      // seconds. Forcing a reflow keeps the animation start in the same
+      // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+      void dialog.offsetHeight;
+      dialog.setAttribute('data-open', '');
+    } else if (!this.open && dialog.open && !this.#closing) {
+      this.#animateClose(dialog);
+    }
+  }
+
+  #animateClose(dialog) {
+    this.#closing = true;
+    // Set [data-closing] FIRST (carries the transition spec), force a
+    // reflow, THEN remove [data-open]. If both attribute changes batch
+    // into a single style update, Safari can skip the slide-out animation
+    // entirely.
+    dialog.setAttribute('data-closing', '');
+    void dialog.offsetHeight;
+    dialog.removeAttribute('data-open');
+
+    this.#closeTimer = setTimeout(() => {
+      this.#closeTimer = null;
+      this.#closing = false;
+      dialog.removeAttribute('data-closing');
+      if (dialog.open) dialog.close();
+    }, this.#getDuration());
+  }
+
+  show() { this.open = true; }
+  hide() { this.open = false; }
+}

package/components/drawer/drawer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `<drawer-ui>` — Slide-out panel anchored to a viewport edge. Uses native <dialog> for focus trap, Escape dismiss, and ::backdrop. Panel is a flex column that scrolls as a whole — the header and footer stick to the top/bottom of the panel when the body overflows. Authors can compose content with either card-ui-style bare tags (<header>, <section>, <footer>) or explicit [slot="header|body|footer"] attributes; multiple <section> siblings are allowed and stack in author order between the sticky header and footer. The header activates a card-ui-aligned 3-column grid (icon | heading+description | action+close) when any direct [slot="icon|heading|description|action"] child is present.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/drawer
+ *
+ * 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 UIDrawer extends UIElement {
+  /** Controls visibility. When false, backdrop and panel are removed from DOM. */
+  open: boolean;
+  /** When true, hide close button and suppress backdrop/Escape dismiss */
+  permanent: boolean;
+  /** Anchor side */
+  side: 'left' | 'right' | 'top' | 'bottom';
+  /** Panel width/height */
+  size: 'sm' | 'md' | 'lg';
+  /** Title text displayed in the drawer header */
+  text: string;
+}

package/components/drawer/drawer.js

@@ -1,296 +1,17 @@
 /**
- * <drawer-ui> — Slide-out panel anchored to a viewport edge.
+ * `<drawer-ui>` — auto-registers the tag on import.
  *
- * Uses native <dialog> for focus trapping, Escape key, and ::backdrop.
- * Content panel slides in/out with CSS transitions.
- * Exit animation plays before dialog.close() via [data-closing].
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Authoring — card-ui-style tags (recommended):
- *   <drawer-ui side="right" size="md">
- *     <header>Title block</header>
- *     <section>Body content</section>
- *     <footer>Action buttons</footer>
- *   </drawer-ui>
+ *   import { UIDrawer } from '@adia-ai/web-components/components/drawer/class';
  *
- * Authoring — explicit slots (also supported):
- *   <drawer-ui>
- *     <header slot="header">…</header>
- *     <section slot="body">…</section>
- *     <footer slot="footer">…</footer>
- *   </drawer-ui>
- *
- * Title-only (stamps an empty header with a close button):
- *   <drawer-ui text="Settings" side="right"></drawer-ui>
- *
- * API:
- *   drawer.show() · drawer.hide() · drawer.open = true|false
- *
- * Events:
- *   close — fired after the drawer finishes closing
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIDrawer extends UIElement {
-  #bound = false;
-  #closing = false;
-  #previousFocus = null;
-  #closeTimer = null;
-  #dialogRef = null;
-
-  static properties = {
-    text:      { type: String,  default: '', reflect: true },
-    side:      { type: String,  default: 'right', reflect: true },
-    size:      { type: String,  default: 'md', reflect: true },
-    permanent: { type: Boolean, default: false, reflect: true },
-    open:      { type: Boolean, default: false, reflect: true },
-  };
-
-  static parts = {
-    dialog: '<dialog slot="dialog"></dialog>',
-    panel:  '<div slot="panel"></div>',
-    header: '<header slot="header"></header>',
-    close:  '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
-    body:   '<section slot="body"></section>',
-    footer: '<footer slot="footer"></footer>',
-  };
-
-  // No template — drawer composes from authored light-DOM children. An empty
-  // html`` result would trigger stamp() → replaceChildren(), wiping authored
-  // [slot=header|body|footer] before render() can migrate them into the panel.
-
-  constructor() {
-    super();
-    // Safari requires <dialog>.showModal() to be invoked synchronously inside
-    // the click handler. The reactive system schedules render() in a microtask
-    // after the property change, which Safari treats as outside the user-gesture
-    // window and silently no-ops the showModal. Wrap the auto-installed `open`
-    // setter so dialog state syncs in the same synchronous frame as the
-    // assignment. See docs/BROWSER-COMPAT.md §3a (Flavor C).
-    const desc = Object.getOwnPropertyDescriptor(this, 'open');
-    if (desc?.set) {
-      const origSet = desc.set;
-      Object.defineProperty(this, 'open', {
-        get: desc.get,
-        set: (v) => {
-          origSet.call(this, v);
-          this.#syncDialog();
-        },
-        configurable: true,
-      });
-    }
-  }
-
-  #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.open = false;
-  };
-
-  #onDialogCancel = (e) => {
-    e.preventDefault();
-    if (!this.permanent) this.open = false;
-  };
-
-  #onDialogClose = () => {
-    this.open = false;
-    this.#previousFocus?.focus();
-    this.#previousFocus = null;
-    this.dispatchEvent(new Event('close', { bubbles: true }));
-  };
-
-  #onDialogClick = (e) => {
-    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
-  };
-
-  connected() {
-    this.addEventListener('press', this.#onPress);
-
-    // Bind dialog listeners as soon as the dialog part is available.
-    const dialog = this.ensure('dialog');
-    if (dialog && !this.#bound) {
-      this.#bound = true;
-      this.#dialogRef = dialog;
-      dialog.addEventListener('cancel', this.#onDialogCancel);
-      dialog.addEventListener('close', this.#onDialogClose);
-      dialog.addEventListener('click', this.#onDialogClick);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('press', this.#onPress);
-    if (this.#dialogRef) {
-      this.#dialogRef.removeEventListener('cancel', this.#onDialogCancel);
-      this.#dialogRef.removeEventListener('close', this.#onDialogClose);
-      this.#dialogRef.removeEventListener('click', this.#onDialogClick);
-    }
-    if (this.#closeTimer != null) {
-      clearTimeout(this.#closeTimer);
-      this.#closeTimer = null;
-    }
-    this.#bound = false;
-    this.#dialogRef = null;
-  }
-
-  #getDuration() {
-    const raw = getComputedStyle(this).getPropertyValue('--drawer-duration').trim();
-    return parseFloat(raw) || 200;
-  }
-
-  /**
-   * Adopt a slotted part into the panel. Accepts either an explicit
-   * [slot="X"] element OR a bare tag matching the card-ui convention
-   * (<header> → header, <section> → body, <footer> → footer). The tag is only
-   * adopted when no slot attribute is set, so authors can still opt into
-   * explicit slotting. The slot attribute is normalized onto the adopted
-   * element so downstream CSS selectors (`[slot="header"]`) match in both
-   * cases.
-   */
-  #adoptSlot(slot, panel, mode = 'append') {
-    const fallbackTag = { header: 'header', body: 'section', footer: 'footer' }[slot];
-    const isMatch = (c) => c.getAttribute('slot') === slot
-      || (fallbackTag && !c.getAttribute('slot') && c.localName === fallbackTag);
-
-    const inDirect = [...this.children].find(isMatch);
-    const inPanel  = [...panel.children].find(c => c.getAttribute('slot') === slot);
-
-    if (inDirect && inPanel && inDirect !== inPanel) {
-      // User provided their own after we stamped a default — drop the stamp.
-      inPanel.remove();
-    }
-
-    const el = inDirect || inPanel || (() => {
-      const blueprint = this.constructor._pp?.[slot];
-      if (!blueprint) return null;
-      const clone = blueprint.cloneNode(true);
-      clone.setAttribute('data-stamped', '');
-      return clone;
-    })();
-    if (!el) return null;
-
-    if (el.getAttribute('slot') !== slot) el.setAttribute('slot', slot);
-
-    if (el.parentElement !== panel) {
-      if (mode === 'prepend') panel.prepend(el);
-      else panel.appendChild(el);
-    }
-    return el;
-  }
-
-  render() {
-    const dialog = this.ensure('dialog');
-
-    if (this.text) {
-      dialog.setAttribute('aria-label', this.text);
-      this.setAttribute('aria-label', this.text);
-    } else {
-      dialog.removeAttribute('aria-label');
-      this.removeAttribute('aria-label');
-    }
-
-    const panel = this.ensure('panel');
-    if (panel.parentElement !== dialog) dialog.appendChild(panel);
-
-    const header = this.#adoptSlot('header', panel, 'prepend');
-
-    // text="…" shorthand: stamp a [slot="heading"] into the header so the
-    // card-ui grid picks it up. Any author-supplied heading wins.
-    if (header) {
-      let stampedHeading = header.querySelector(':scope > [slot="heading"][data-stamped]');
-      const hasAuthorHeading = [...header.children].some(c =>
-        !c.hasAttribute('data-stamped') &&
-        (c.getAttribute('slot') === 'heading' || /^h[1-6]$/.test(c.localName))
-      );
-      if (this.text && !hasAuthorHeading) {
-        if (!stampedHeading) {
-          stampedHeading = document.createElement('span');
-          stampedHeading.setAttribute('slot', 'heading');
-          stampedHeading.setAttribute('data-stamped', '');
-          header.prepend(stampedHeading);
-        }
-        if (stampedHeading.textContent !== this.text) stampedHeading.textContent = this.text;
-      } else if (stampedHeading) {
-        stampedHeading.remove();
-      }
-    }
-
-    if (!this.permanent) {
-      const close = this.ensure('close');
-      if (header && close.parentElement !== header) header.appendChild(close);
-    } else {
-      this.drop('close');
-    }
-
-    // Body — multiple sections allowed (card-ui parity). Accepts either
-    // bare <section> tags or explicit [slot="body"]. If the author provides
-    // none, stamp an empty default so title-only drawers still lay out.
-    const authorSections = [...this.children].filter(c =>
-      c.getAttribute('slot') === 'body'
-      || (c.localName === 'section' && !c.getAttribute('slot'))
-    );
-    if (authorSections.length === 0) {
-      this.#adoptSlot('body', panel, 'append');
-    } else {
-      for (const s of authorSections) {
-        if (s.getAttribute('slot') !== 'body') s.setAttribute('slot', 'body');
-        if (s.parentElement !== panel) panel.appendChild(s);
-      }
-    }
-
-    // Footer is opt-in — only mounted if the author supplied one (either
-    // [slot="footer"] or a bare <footer> tag, card-ui style).
-    const userFooter = [...this.children].find(c =>
-      c.getAttribute('slot') === 'footer' || (!c.getAttribute('slot') && c.localName === 'footer')
-    );
-    if (userFooter) {
-      if (userFooter.getAttribute('slot') !== 'footer') userFooter.setAttribute('slot', 'footer');
-      if (userFooter.parentElement !== panel) panel.appendChild(userFooter);
-    }
-
-    // Sync open state — also syncs synchronously from the `open` setter
-    // (see constructor) so showModal() runs in the click handler's gesture
-    // frame on Safari.
-    this.#syncDialog();
-  }
-
-  #syncDialog() {
-    const dialog = this.#dialogRef;
-    if (!dialog) return;
-    if (this.open && !dialog.open) {
-      this.#closing = false;
-      this.#previousFocus = document.activeElement;
-      dialog.showModal();
-      // Synchronous reflow instead of rAF — Safari throttles
-      // requestAnimationFrame when a top-layer dialog is open, sometimes
-      // delaying [data-open] (and the slide-in transition) by tens of
-      // seconds. Forcing a reflow keeps the animation start in the same
-      // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
-      void dialog.offsetHeight;
-      dialog.setAttribute('data-open', '');
-    } else if (!this.open && dialog.open && !this.#closing) {
-      this.#animateClose(dialog);
-    }
-  }
-
-  #animateClose(dialog) {
-    this.#closing = true;
-    // Set [data-closing] FIRST (carries the transition spec), force a
-    // reflow, THEN remove [data-open]. If both attribute changes batch
-    // into a single style update, Safari can skip the slide-out animation
-    // entirely.
-    dialog.setAttribute('data-closing', '');
-    void dialog.offsetHeight;
-    dialog.removeAttribute('data-open');
-
-    this.#closeTimer = setTimeout(() => {
-      this.#closeTimer = null;
-      this.#closing = false;
-      dialog.removeAttribute('data-closing');
-      if (dialog.open) dialog.close();
-    }, this.#getDuration());
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIDrawer } from './class.js';
 
-  show() { this.open = true; }
-  hide() { this.open = false; }
-}
-customElements.define('drawer-ui', UIDrawer);
+defineIfFree('drawer-ui', UIDrawer);
 
 export { UIDrawer };