@adia-ai/web-components 0.6.33 → 0.6.35

package/components/integration-card/integration-card.class.js

@@ -0,0 +1,410 @@
+/**
+ * Non-side-effect class export for `<integration-card-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/integration-card`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <integration-card-ui provider="slack" name="Slack"
+ *                       logo="/integrations/slack.svg"
+ *                       description="Send AI replies and notifications to channels."
+ *                       status="available">
+ * </integration-card-ui>
+ *
+ * Single tile representing one third-party integration. Status drives the
+ * button label + variant; tile chrome borrows from <card-ui> but the
+ * primitive is its own surface (one tile = one provider, never compose
+ * <card-ui> around it).
+ *
+ * Events:
+ *   connect    — { detail: { provider } } fired when `status="available"`
+ *   configure  — { detail: { provider } } fired when `status="connected"`
+ *   retry      — { detail: { provider } } fired when `status="error"`
+ *   disconnect — bubbled from consumer-provided overflow menu items
+ *                with `data-action="disconnect"` in the `actions` slot
+ */
+
+import { UIElement } from '../../core/element.js';
+
+const STATUS = Object.freeze({
+  AVAILABLE:    'available',
+  CONNECTED:    'connected',
+  ERROR:        'error',
+  PENDING:      'pending',
+  COMING_SOON:  'coming-soon',
+});
+
+const ACTION_FOR_STATUS = Object.freeze({
+  available:     { event: 'press',     emits: 'connect',    label: 'Connect',    variant: 'primary', icon: '' },
+  connected:     { event: 'press',     emits: 'configure',  label: 'Configure',  variant: 'outline', icon: '' },
+  error:         { event: 'press',     emits: 'retry',      label: 'Retry',      variant: 'outline', icon: 'arrow-clockwise' },
+  pending:       { event: 'press',     emits: '',           label: 'Connecting…', variant: 'outline', icon: '' },
+});
+
+const BADGE_FOR_STATUS = Object.freeze({
+  connected:    { variant: 'success', text: 'Connected',   icon: 'check' },
+  error:        { variant: 'danger',  text: 'Error',       icon: 'warning-circle' },
+  pending:      { variant: 'info',    text: 'Connecting…', icon: '' },
+  'coming-soon':{ variant: 'muted',   text: 'Coming soon', icon: '' },
+});
+
+export class UIIntegrationCard extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs (slot 11).
+  static requiredIcons = ['check', 'warning-circle', 'arrow-clockwise'];
+
+  static properties = {
+    provider:        { type: String,  default: '',          reflect: true },
+    name:            { type: String,  default: '',          reflect: false },
+    logo:            { type: String,  default: '',          reflect: false },
+    description:     { type: String,  default: '',          reflect: false },
+    status:          { type: String,  default: 'available', reflect: true },
+    'error-message': { type: String,  default: '',          attribute: 'error-message' },
+    disabled:        { type: Boolean, default: false,       reflect: true },
+  };
+
+  static parts = {
+    body:      '<div slot="body" data-integration-card-body></div>',
+    logo:      '<div slot="logo" data-integration-card-logo></div>',
+    heading:   '<div slot="heading" data-integration-card-heading></div>',
+    desc:      '<p slot="description" data-integration-card-description></p>',
+    error:     '<p slot="error" data-integration-card-error></p>',
+    status:    '<badge-ui slot="status" data-integration-card-status></badge-ui>',
+    footer:    '<footer slot="footer" data-integration-card-footer></footer>',
+    button:    '<button-ui slot="action" data-integration-card-action></button-ui>',
+  };
+
+  static template = () => null;
+
+  // Stable ID for aria-labelledby pointing at the provider name.
+  #headingId = '';
+
+  // Cached element refs (lazily filled in `connected()`).
+  #bodyEl = null;
+  #logoEl = null;
+  #headingEl = null;
+  #descEl = null;
+  #errorEl = null;
+  #statusEl = null;
+  #footerEl = null;
+  #buttonEl = null;
+
+  connected() {
+    // Group semantic — labeled region announced by SR.
+    this.setAttribute('role', 'group');
+
+    // Build the static frame once. ensure() is idempotent.
+    this.#bodyEl    = this.ensure('body');
+    this.#logoEl    = this.ensure('logo');
+    this.#headingEl = this.ensure('heading');
+    this.#descEl    = this.ensure('desc');
+    this.#statusEl  = this.ensure('status');
+    this.#footerEl  = this.ensure('footer');
+
+    // Slot/structural arrangement: logo + heading + status sit inside body row;
+    // description sits below; error sits below description; button sits in footer.
+    // We arrange via DOM order so CSS direct-child selectors apply consistently.
+    if (this.#logoEl.parentElement !== this.#bodyEl)    this.#bodyEl.appendChild(this.#logoEl);
+    if (this.#headingEl.parentElement !== this.#bodyEl) this.#bodyEl.appendChild(this.#headingEl);
+    if (this.#statusEl.parentElement !== this.#bodyEl)  this.#bodyEl.appendChild(this.#statusEl);
+
+    // Assign a stable id for aria-labelledby (don't clobber author-set id).
+    if (!this.#headingEl.id) {
+      this.#headingId = `integration-card-heading-${Math.random().toString(36).slice(2, 9)}`;
+      this.#headingEl.id = this.#headingId;
+    } else {
+      this.#headingId = this.#headingEl.id;
+    }
+    this.setAttribute('aria-labelledby', this.#headingId);
+
+    // Wire action button activation. The button-ui dispatches `press`; we
+    // re-dispatch a typed event (connect / configure / retry) based on status.
+    this.addEventListener('press', this.#onPress);
+
+    // Catch consumer-wired overflow actions in the `actions` slot. The
+    // menu-ui dispatches `action` with the action name in detail — when
+    // it's `disconnect`, we re-dispatch as a typed event with the
+    // provider key. Same recipe for `reauth` / `re-authenticate`.
+    this.addEventListener('action', this.#onMenuAction);
+  }
+
+  disconnected() {
+    this.removeEventListener('press', this.#onPress);
+    this.removeEventListener('action', this.#onMenuAction);
+    this.#bodyEl = null;
+    this.#logoEl = null;
+    this.#headingEl = null;
+    this.#descEl = null;
+    this.#errorEl = null;
+    this.#statusEl = null;
+    this.#footerEl = null;
+    this.#buttonEl = null;
+  }
+
+  render() {
+    if (!this.#headingEl) return;
+
+    const status = this.#normalizedStatus();
+
+    // ── Heading ──────────────────────────────────────────────────────
+    if (this.name && this.#headingEl.textContent !== this.name) {
+      this.#headingEl.textContent = this.name;
+    }
+
+    // ── Description ─────────────────────────────────────────────────
+    // The default slot supersedes the description prop when non-empty.
+    // We detect "consumer-authored description" via any direct child that
+    // isn't one of our stamped data-integration-card-* elements and isn't
+    // a slotted action / menu.
+    const hasCustomDesc = this.#hasConsumerDescription();
+    if (hasCustomDesc) {
+      if (this.#descEl.parentElement === this) {
+        this.#descEl.remove();
+      }
+    } else {
+      if (!this.#descEl.parentElement) this.appendChild(this.#descEl);
+      if (this.description) {
+        if (this.#descEl.textContent !== this.description) {
+          this.#descEl.textContent = this.description;
+        }
+        this.#descEl.hidden = false;
+      } else {
+        this.#descEl.textContent = '';
+        this.#descEl.hidden = true;
+      }
+    }
+
+    // ── Logo ────────────────────────────────────────────────────────
+    this.#renderLogo();
+
+    // ── Status badge ────────────────────────────────────────────────
+    this.#renderStatusBadge(status);
+
+    // ── Error message (status="error" only) ─────────────────────────
+    this.#renderError(status);
+
+    // ── Action button (label + variant + visibility) ────────────────
+    this.#renderActionButton(status);
+  }
+
+  // ── Private rendering helpers ─────────────────────────────────────
+
+  #normalizedStatus() {
+    const s = (this.status || '').trim() || STATUS.AVAILABLE;
+    // Validate against the enum; fall back to `available` on bad input.
+    if (Object.values(STATUS).includes(s)) return s;
+    return STATUS.AVAILABLE;
+  }
+
+  #hasConsumerDescription() {
+    // Author description = direct child element that is neither one of our
+    // stamped data- markers nor an [slot="actions"] / [slot="action"] node.
+    for (const child of this.children) {
+      if (child === this.#bodyEl) continue;
+      if (child === this.#descEl) continue;
+      if (child === this.#errorEl) continue;
+      if (child === this.#footerEl) continue;
+      if (child.getAttribute && child.getAttribute('slot') === 'actions') continue;
+      if (child.dataset && (
+        child.dataset.integrationCardBody !== undefined ||
+        child.dataset.integrationCardDescription !== undefined ||
+        child.dataset.integrationCardError !== undefined ||
+        child.dataset.integrationCardFooter !== undefined
+      )) continue;
+      // Any other direct child counts as consumer-authored description content.
+      return true;
+    }
+    return false;
+  }
+
+  #renderLogo() {
+    if (!this.#logoEl) return;
+    const logo = (this.logo || '').trim();
+
+    // No logo → strip any prior content and hide.
+    if (!logo) {
+      this.#logoEl.replaceChildren();
+      this.#logoEl.hidden = true;
+      return;
+    }
+    this.#logoEl.hidden = false;
+
+    // URL vs icon-name sniff: presence of '/' → URL.
+    const isUrl = logo.includes('/');
+
+    if (isUrl) {
+      // Reuse existing <img> if same src; otherwise re-stamp.
+      let img = this.#logoEl.querySelector(':scope > img');
+      if (img && img.getAttribute('src') === logo) {
+        img.setAttribute('alt', `${this.name || this.provider || 'Integration'} logo`);
+        return;
+      }
+      this.#logoEl.replaceChildren();
+      img = document.createElement('img');
+      img.setAttribute('src', logo);
+      img.setAttribute('alt', `${this.name || this.provider || 'Integration'} logo`);
+      img.setAttribute('data-integration-logo', '');
+      img.setAttribute('loading', 'lazy');
+      img.setAttribute('decoding', 'async');
+      this.#logoEl.appendChild(img);
+      return;
+    }
+
+    // Icon name → <icon-ui>.
+    let icon = this.#logoEl.querySelector(':scope > icon-ui');
+    if (icon && icon.getAttribute('name') === logo) return;
+    this.#logoEl.replaceChildren();
+    icon = document.createElement('icon-ui');
+    icon.setAttribute('name', logo);
+    icon.setAttribute('aria-hidden', 'true');
+    this.#logoEl.appendChild(icon);
+  }
+
+  #renderStatusBadge(status) {
+    if (!this.#statusEl) return;
+    const cfg = BADGE_FOR_STATUS[status];
+    if (!cfg) {
+      // No badge for `available` — keep DOM but hide.
+      this.#statusEl.hidden = true;
+      this.#statusEl.removeAttribute('aria-label');
+      return;
+    }
+    this.#statusEl.hidden = false;
+    this.#statusEl.setAttribute('variant', cfg.variant);
+    this.#statusEl.setAttribute('text', cfg.text);
+    this.#statusEl.setAttribute('size', 'sm');
+    if (cfg.icon) this.#statusEl.setAttribute('icon', cfg.icon);
+    else this.#statusEl.removeAttribute('icon');
+    // Explicit aria-label so SR announces "Connected" even when text rendering
+    // is delayed by icon-registry boot.
+    this.#statusEl.setAttribute('aria-label', cfg.text);
+  }
+
+  #renderError(status) {
+    const msg = (this['error-message'] || this.getAttribute('error-message') || '').trim();
+    if (status === STATUS.ERROR && msg) {
+      if (!this.#errorEl) this.#errorEl = this.ensure('error');
+      if (!this.#errorEl.parentElement) {
+        // Insert after description, before footer if possible.
+        if (this.#descEl?.parentElement === this) {
+          this.#descEl.after(this.#errorEl);
+        } else if (this.#footerEl?.parentElement === this) {
+          this.insertBefore(this.#errorEl, this.#footerEl);
+        } else {
+          this.appendChild(this.#errorEl);
+        }
+      }
+      if (this.#errorEl.textContent !== msg) this.#errorEl.textContent = msg;
+      this.#errorEl.hidden = false;
+      this.#errorEl.setAttribute('role', 'status');
+    } else if (this.#errorEl) {
+      this.#errorEl.hidden = true;
+      this.#errorEl.textContent = '';
+    }
+  }
+
+  #renderActionButton(status) {
+    // coming-soon → hide the button entirely; the badge carries the label.
+    if (status === STATUS.COMING_SOON) {
+      this.drop('button');
+      this.#buttonEl = null;
+      // Footer with no button can still hold the [slot="actions"] menu,
+      // so we keep the footer node attached.
+      return;
+    }
+
+    const cfg = ACTION_FOR_STATUS[status];
+    if (!cfg) {
+      this.drop('button');
+      this.#buttonEl = null;
+      return;
+    }
+
+    // Ensure the button exists and sits inside the footer (light DOM
+    // positioning: button is a direct child of footer, footer is a direct
+    // child of host).
+    if (!this.#buttonEl) this.#buttonEl = this.ensure('button');
+    if (this.#buttonEl.parentElement !== this.#footerEl) {
+      this.#footerEl.insertBefore(this.#buttonEl, this.#footerEl.firstChild);
+    }
+
+    this.#buttonEl.setAttribute('text', cfg.label);
+    this.#buttonEl.setAttribute('variant', cfg.variant);
+    this.#buttonEl.setAttribute('size', 'sm');
+    if (cfg.icon) this.#buttonEl.setAttribute('icon', cfg.icon);
+    else this.#buttonEl.removeAttribute('icon');
+
+    // Toggle semantics — aria-pressed reflects "is the integration on?"
+    // Provides screen-reader feedback on the action's effect.
+    if (status === STATUS.CONNECTED) {
+      this.#buttonEl.setAttribute('aria-pressed', 'true');
+    } else if (status === STATUS.AVAILABLE) {
+      this.#buttonEl.setAttribute('aria-pressed', 'false');
+    } else {
+      this.#buttonEl.removeAttribute('aria-pressed');
+    }
+
+    // Explicit aria-label so SR announces "Connect to Slack" outside group ctx.
+    const verbForStatus = {
+      available:  'Connect to',
+      connected:  'Configure',
+      error:      'Retry connecting',
+      pending:    'Connecting to',
+    }[status] || cfg.label;
+    const labelTarget = this.name || this.provider || 'integration';
+    this.#buttonEl.setAttribute('aria-label', `${verbForStatus} ${labelTarget}`);
+
+    // pending → non-interactive; disabled prop → non-interactive too.
+    if (status === STATUS.PENDING || this.disabled) {
+      this.#buttonEl.setAttribute('disabled', '');
+    } else {
+      this.#buttonEl.removeAttribute('disabled');
+    }
+  }
+
+  // ── Event handlers ────────────────────────────────────────────────
+
+  #onPress = (e) => {
+    // Only react to presses on OUR action button — overflow menu items
+    // dispatch `action` instead.
+    if (!this.#buttonEl) return;
+    if (e.target !== this.#buttonEl && !e.composedPath?.().includes(this.#buttonEl)) return;
+    if (this.disabled) { e.stopPropagation(); return; }
+
+    const status = this.#normalizedStatus();
+    if (status === STATUS.PENDING || status === STATUS.COMING_SOON) {
+      e.stopPropagation();
+      return;
+    }
+
+    const cfg = ACTION_FOR_STATUS[status];
+    if (!cfg || !cfg.emits) return;
+
+    this.dispatchEvent(new CustomEvent(cfg.emits, {
+      bubbles: true,
+      detail: { provider: this.provider },
+    }));
+  };
+
+  #onMenuAction = (e) => {
+    // Bubbled `action` events from the consumer-provided overflow menu
+    // in [slot="actions"]. Detail shape from menu-item-ui: { action: '<name>' }.
+    const action = e.detail?.action || e.target?.getAttribute?.('action');
+    if (!action) return;
+    if (action === 'disconnect' || action === 'reauth' || action === 're-authenticate') {
+      const emits = action === 'disconnect' ? 'disconnect' : 'reauth';
+      this.dispatchEvent(new CustomEvent(emits, {
+        bubbles: true,
+        detail: { provider: this.provider },
+      }));
+    }
+  };
+}

package/components/integration-card/integration-card.css

@@ -0,0 +1,169 @@
+@scope (integration-card-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --integration-card-bg-default:              var(--a-bg);
+    --integration-card-border-default:          1px solid var(--a-border-subtle);
+    --integration-card-radius-default:          var(--a-radius-md);
+    --integration-card-px-default:              var(--a-space-4);
+    --integration-card-py-default:              var(--a-space-4);
+    --integration-card-gap-default:             var(--a-space-3);
+
+    /* ── Inner rhythm ── */
+    --integration-card-row-gap-default:         var(--a-space-3);
+    --integration-card-text-gap-default:        var(--a-space-1);
+
+    /* ── Logo ── */
+    --integration-card-logo-size-default:       var(--a-space-7);
+    --integration-card-logo-radius-default:     var(--a-radius-sm);
+
+    /* ── Typography ── */
+    --integration-card-heading-fg-default:      var(--a-fg-strong);
+    --integration-card-heading-size-default:    var(--a-ui-size);
+    --integration-card-heading-weight-default:  var(--a-weight-medium);
+    --integration-card-description-fg-default:  var(--a-fg-muted);
+    --integration-card-description-size-default: var(--a-ui-sm);
+    --integration-card-error-fg-default:        var(--a-danger-text);
+    --integration-card-error-size-default:      var(--a-ui-sm);
+
+    /* ── States ── */
+    --integration-card-disabled-opacity-default: 0.6;
+  }
+
+  /* ── Base — vertical stack: body row + (description) + (error) + footer ── */
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    grid-template-rows: auto 1fr auto;
+    gap: var(--integration-card-gap, var(--integration-card-gap-default));
+    padding: var(--integration-card-py, var(--integration-card-py-default)) var(--integration-card-px, var(--integration-card-px-default));
+    background: var(--integration-card-bg, var(--integration-card-bg-default));
+    border: var(--integration-card-border, var(--integration-card-border-default));
+    border-radius: var(--integration-card-radius, var(--integration-card-radius-default));
+    width: stretch;
+    min-width: 0;
+  }
+
+  /* ── Status-driven border tints ── */
+  :scope[status="connected"] {
+    --integration-card-border-default: 1px solid var(--a-success-border, var(--a-success-strong));
+  }
+  :scope[status="error"] {
+    --integration-card-border-default: 1px solid var(--a-danger-border, var(--a-danger-strong));
+  }
+
+  /* ── Coming-soon + disabled → opacity reduction ── */
+  :scope[status="coming-soon"],
+  :scope[disabled] {
+    opacity: var(--integration-card-disabled-opacity, var(--integration-card-disabled-opacity-default));
+  }
+
+  /* ── Body row — logo | heading | status badge ── */
+  :scope > [data-integration-card-body] {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    align-items: center;
+    column-gap: var(--integration-card-row-gap, var(--integration-card-row-gap-default));
+  }
+
+  /* ── Logo square ── */
+  :scope > [data-integration-card-body] > [data-integration-card-logo] {
+    grid-column: 1;
+    inline-size: var(--integration-card-logo-size, var(--integration-card-logo-size-default));
+    block-size: var(--integration-card-logo-size, var(--integration-card-logo-size-default));
+    border-radius: var(--integration-card-logo-radius, var(--integration-card-logo-radius-default));
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    flex-shrink: 0;
+  }
+  :scope > [data-integration-card-body] > [data-integration-card-logo][hidden] {
+    display: none;
+  }
+  :scope [data-integration-card-logo] > img {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: contain;
+    display: block;
+  }
+  :scope [data-integration-card-logo] > icon-ui {
+    --a-icon-size: calc(var(--integration-card-logo-size, var(--integration-card-logo-size-default)) - var(--a-space-1));
+    color: var(--a-fg-muted);
+  }
+
+  /* ── Heading (provider name) ── */
+  :scope > [data-integration-card-body] > [data-integration-card-heading] {
+    grid-column: 2;
+    color: var(--integration-card-heading-fg, var(--integration-card-heading-fg-default));
+    font-size: var(--integration-card-heading-size, var(--integration-card-heading-size-default));
+    font-weight: var(--integration-card-heading-weight, var(--integration-card-heading-weight-default));
+    line-height: 1.3;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ── Status badge (sits in body row, right-aligned) ── */
+  :scope > [data-integration-card-body] > [data-integration-card-status] {
+    grid-column: 3;
+    justify-self: end;
+  }
+  :scope > [data-integration-card-body] > [data-integration-card-status][hidden] {
+    display: none;
+  }
+
+  /* ── Description ── */
+  :scope > [data-integration-card-description] {
+    margin: 0;
+    color: var(--integration-card-description-fg, var(--integration-card-description-fg-default));
+    font-size: var(--integration-card-description-size, var(--integration-card-description-size-default));
+    line-height: 1.4;
+  }
+  :scope > [data-integration-card-description][hidden] {
+    display: none;
+  }
+
+  /* ── Author-provided description (default slot) — same typography
+     by selector rather than slot to support bare <p>, <text-ui>, <small>. */
+  :scope > p:not([data-integration-card-description]):not([data-integration-card-error]),
+  :scope > small:not([data-integration-card-error]) {
+    margin: 0;
+    color: var(--integration-card-description-fg, var(--integration-card-description-fg-default));
+    font-size: var(--integration-card-description-size, var(--integration-card-description-size-default));
+    line-height: 1.4;
+  }
+
+  /* ── Error message ── */
+  :scope > [data-integration-card-error] {
+    margin: 0;
+    color: var(--integration-card-error-fg, var(--integration-card-error-fg-default));
+    font-size: var(--integration-card-error-size, var(--integration-card-error-size-default));
+    line-height: 1.4;
+  }
+  :scope > [data-integration-card-error][hidden] {
+    display: none;
+  }
+
+  /* ── Footer — action button + optional [slot="actions"] overflow ── */
+  :scope > [data-integration-card-footer] {
+    display: flex;
+    align-items: center;
+    gap: var(--integration-card-row-gap, var(--integration-card-row-gap-default));
+    margin: 0;
+    padding: 0;
+  }
+
+  /* Action button is first child of footer; menu / overflow goes to the right. */
+  :scope > [data-integration-card-footer] > [data-integration-card-action] {
+    flex: 0 0 auto;
+  }
+  :scope > [data-integration-card-footer] > [slot="actions"] {
+    margin-inline-start: auto;
+  }
+
+  /* ── Disabled state — button-ui already dims; ensure card chrome too. */
+  :scope[disabled] {
+    pointer-events: none;
+  }
+}

package/components/integration-card/integration-card.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `<integration-card-ui>` — Single-tile primitive representing one third-party integration (Slack, GitHub, Stripe, …). Shows the provider logo + name + description + status pill + a single primary action button whose label and variant are derived from `status`. Composes into a grid via the SPEC-063 integrations-page composite. One tile = one provider; the button variant is computed from `status`, not a separate prop. Distinct from <option-card-ui> (a single-select radio with no status / async action) and <card-ui> (the generic bordered surface this specializes).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/integration-card
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). 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 interface IntegrationCardConfigureEventDetail {
+  /** The provider key for this card. */
+  provider: string;
+}
+
+export type IntegrationCardConfigureEvent = CustomEvent<IntegrationCardConfigureEventDetail>;
+export interface IntegrationCardConnectEventDetail {
+  /** The provider key for this card. */
+  provider: string;
+}
+
+export type IntegrationCardConnectEvent = CustomEvent<IntegrationCardConnectEventDetail>;
+export interface IntegrationCardDisconnectEventDetail {
+  /** The provider key for this card. */
+  provider: string;
+}
+
+export type IntegrationCardDisconnectEvent = CustomEvent<IntegrationCardDisconnectEventDetail>;
+export interface IntegrationCardRetryEventDetail {
+  /** The provider key for this card. */
+  provider: string;
+}
+
+export type IntegrationCardRetryEvent = CustomEvent<IntegrationCardRetryEventDetail>;
+
+export class UIIntegrationCard extends UIElement {
+  /** One-line description of what the integration does. */
+  description: string;
+  /** Disables the action button. */
+  disabled: boolean;
+  /** Logo URL (preferred — renders as <img>) or icon name (renders as <icon-ui>). URLs are sniffed by presence of `/`. */
+  logo: string;
+  /** Display name shown as the card title. Required. */
+  name: string;
+  /** Provider key — `slack`, `github`, etc. — used for analytics + a11y label. Required. */
+  provider: string;
+  /** Current connection state — drives the button label, variant, and visibility. `available` shows a primary `Connect`; `connected` shows an outline `Configure`; `error` shows an outline `Retry`; `pending` shows a non-interactive spinner; `coming-soon` hides the button. */
+  status: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIIntegrationCard, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'configure', listener: (ev: IntegrationCardConfigureEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'connect', listener: (ev: IntegrationCardConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'disconnect', listener: (ev: IntegrationCardDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'retry', listener: (ev: IntegrationCardRetryEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/integration-card/integration-card.examples.md

@@ -0,0 +1,41 @@
+# integration-card — Examples
+
+## Available (default)
+
+```html
+<integration-card-ui
+  provider="slack"
+  name="Slack"
+  logo="/integrations/slack.svg"
+  description="Send AI replies and notifications to channels."
+  status="available">
+</integration-card-ui>
+```
+
+## Connected — overflow menu
+
+```html
+<integration-card-ui provider="github" name="GitHub" status="connected"
+                      logo="/integrations/github.svg"
+                      description="Sync issues and pull requests.">
+  <menu-ui slot="actions" label="More" trigger-icon="dots-three" trigger-variant="ghost">
+    <menu-item-ui action="reauth">Re-authenticate</menu-item-ui>
+    <menu-item-ui action="disconnect" variant="danger">Disconnect</menu-item-ui>
+  </menu-ui>
+</integration-card-ui>
+```
+
+## Error — Retry
+
+```html
+<integration-card-ui provider="stripe" name="Stripe" status="error"
+                      error-message="Token expired — re-authenticate.">
+</integration-card-ui>
+```
+
+## Coming soon (non-interactive)
+
+```html
+<integration-card-ui provider="zapier" name="Zapier" status="coming-soon">
+</integration-card-ui>
+```