@adia-ai/web-modules 0.8.35 → 0.8.37

package/settings/integrations-page/integrations-page.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `<integrations-page-ui>` — Module-tier Settings page composite — a
+ * searchable, category-grouped grid of <integration-card-ui> tiles
+ * (SPEC-062).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/integrations-page
+ *
+ * Hand-authored alongside `<name>.yaml`; regenerate when the props /
+ * events shape changes.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface IntegrationDescriptor {
+  /** Provider key — `slack`, `github`, etc. Required. */
+  provider: string;
+  /** Display name shown as the card title. Required. */
+  name: string;
+  /** Logo URL or registered icon name. Optional. */
+  logo?: string;
+  /** One-line description. Optional. */
+  description?: string;
+  /** Connection state. Required for status-driven button + badge. */
+  status: 'available' | 'connected' | 'error' | 'pending' | 'coming-soon';
+  /** Category bucket — used when `group-by="category"`. Optional. */
+  category?: string;
+  /** Error message shown when `status="error"`. Optional. */
+  'error-message'?: string;
+  /** camelCase alias for `error-message`. Optional. */
+  errorMessage?: string;
+}
+
+export interface IntegrationsPageSearchEventDetail {
+  /** Lower-cased, trimmed query value. */
+  query: string;
+}
+export type IntegrationsPageSearchEvent =
+  CustomEvent<IntegrationsPageSearchEventDetail>;
+
+export interface IntegrationsPageFilterChangeEventDetail {
+  /** The newly-selected status filter (`all` resets). */
+  status: 'all' | 'available' | 'connected' | 'error' | 'coming-soon';
+}
+export type IntegrationsPageFilterChangeEvent =
+  CustomEvent<IntegrationsPageFilterChangeEventDetail>;
+
+export interface IntegrationsPageCardEventDetail {
+  /** Provider key of the card that fired. */
+  provider: string;
+}
+export type IntegrationsPageCardEvent =
+  CustomEvent<IntegrationsPageCardEventDetail>;
+
+export class UIIntegrationsPage extends UIElement {
+  /** Array of integration descriptors. Each item satisfies SPEC-062. */
+  integrations: IntegrationDescriptor[];
+  /** Renders skeleton grid when true. */
+  loading: boolean;
+  /** Placeholder copy for the built-in search input. */
+  'search-placeholder': string;
+  /** How to bucket cards into sections. */
+  'group-by': 'category' | 'status' | 'none';
+  /** Restrict visible cards to a single status. `all` resets. */
+  'status-filter': 'all' | 'available' | 'connected' | 'error' | 'coming-soon';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIIntegrationsPage, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'search', listener: (ev: IntegrationsPageSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'filter-change', listener: (ev: IntegrationsPageFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'connect', listener: (ev: IntegrationsPageCardEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'configure', listener: (ev: IntegrationsPageCardEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'disconnect', listener: (ev: IntegrationsPageCardEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'retry', listener: (ev: IntegrationsPageCardEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/settings/integrations-page/integrations-page.js

@@ -0,0 +1,413 @@
+/**
+ * <integrations-page-ui> — module-tier Settings composite.
+ *
+ *   <integrations-page-ui id="settings-integrations" group-by="category">
+ *   </integrations-page-ui>
+ *   <script>
+ *     document.querySelector('#settings-integrations').integrations = [
+ *       { provider: 'slack',  name: 'Slack',  logo: '/slack.svg',
+ *         status: 'connected',  category: 'Communication',
+ *         description: 'Send replies to channels.' },
+ *       { provider: 'github', name: 'GitHub', logo: '/github.svg',
+ *         status: 'available', category: 'Developer Tools',
+ *         description: 'Sync issues + PRs.' },
+ *     ];
+ *   </script>
+ *
+ * Composes <integration-card-ui> × N inside <grid-ui> with a built-in
+ * <search-ui> filter + <segmented-ui> status-filter top bar. Owns the
+ * data (integrations prop) → renders cards; card-level events bubble
+ * up unchanged via <integration-card-ui>'s typed emits.
+ *
+ * Per ADR-0027 — composites that programmatically create primitives in
+ * their render() do NOT auto-import those primitives. Consumer (or
+ * demo shell) must explicitly import <integration-card-ui>,
+ * <grid-ui>, <search-ui>, <segmented-ui> + <segment-ui>, and
+ * <text-ui> in addition to this module.
+ */
+
+import { UIElement, html } from '@adia-ai/web-components/core/element';
+
+// Status filter top-bar options. Order matches the spec's intent:
+// `all` first (default reset), then connection-state buckets.
+const FILTER_OPTIONS = Object.freeze([
+  { value: 'all',         label: 'All' },
+  { value: 'available',   label: 'Available' },
+  { value: 'connected',   label: 'Connected' },
+  { value: 'error',       label: 'Issues' },
+  { value: 'coming-soon', label: 'Coming soon' },
+]);
+
+const SKELETON_COUNT = 6;
+
+class UIIntegrationsPage extends UIElement {
+  static properties = {
+    integrations:        { type: Array,   default: [] },
+    loading:             { type: Boolean, default: false,  reflect: true },
+    'search-placeholder':{ type: String,  default: 'Search integrations', reflect: true },
+    'group-by':          { type: String,  default: 'category', reflect: true },
+    'status-filter':     { type: String,  default: 'all',  reflect: true },
+  };
+
+  static template = (host) => host._renderTemplate();
+
+  // ── lifecycle state ─────────────────────────────────────────────
+
+  #query = '';
+  #headerId = `intpage-h-${Math.random().toString(36).slice(2, 8)}`;
+  #searchTimer = null;
+
+  // ── attribute parsing ──────────────────────────────────────────
+
+  /**
+   * `integrations` accepts JSON via the HTML attribute path — the
+   * canonical authoring shape for a2ui-generated markup. Default
+   * UIElement attribute reflection would assign the string verbatim
+   * and break the array shape; parse here.
+   */
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (name === 'integrations') {
+      if (newVal == null) {
+        this.integrations = [];
+      } else {
+        try {
+          const parsed = JSON.parse(newVal);
+          this.integrations = Array.isArray(parsed) ? parsed : [];
+        } catch {
+          this.integrations = [];
+        }
+      }
+      return;
+    }
+    super.attributeChangedCallback(name, oldVal, newVal);
+  }
+
+  // ── lifecycle ───────────────────────────────────────────────────
+
+  connected() {
+    // Landmark + label so SR announces the region.
+    this.setAttribute('role', 'region');
+    this.setAttribute('aria-labelledby', this.#headerId);
+    if (!this.hasAttribute('aria-label')) {
+      this.setAttribute('aria-label', 'Integrations');
+    }
+
+    // Late-parse JSON attribute (UIElement assigns the raw String on
+    // first connect; we re-parse here).
+    if (this.hasAttribute('integrations') && !Array.isArray(this.integrations)) {
+      try { this.integrations = JSON.parse(this.getAttribute('integrations')); }
+      catch { this.integrations = []; }
+    }
+
+    this.addEventListener('input',  this.#onSearchInput);
+    this.addEventListener('change', this.#onFilterChange);
+  }
+
+  disconnected() {
+    this.removeEventListener('input',  this.#onSearchInput);
+    this.removeEventListener('change', this.#onFilterChange);
+    if (this.#searchTimer) {
+      clearTimeout(this.#searchTimer);
+      this.#searchTimer = null;
+    }
+  }
+
+  render() {
+    this.#syncEmptyAttrs();
+    // The composite re-stamps the <segmented-ui> + its <segment-ui> children on
+    // every render, but segmented-ui's own render() — which applies [selected]
+    // to the active segment — does NOT re-run after a parent re-stamp. Without
+    // this, the selected segment loses [selected] and its label renders in the
+    // dim unselected color on the light pill (bug-52). render() runs post-stamp
+    // (element.js: stamp() then render()), so the segmented-ui is freshly mounted.
+    this.querySelector('segmented-ui[data-part="filter"]')?.render?.();
+  }
+
+  // ── render ──────────────────────────────────────────────────────
+
+  _renderTemplate() {
+    const placeholder = this['search-placeholder'] || 'Search integrations';
+    const filterValue = this['status-filter'] || 'all';
+    const isLoading   = !!this.loading;
+    const groups      = this.#computeGroups();
+
+    return html`
+      <header data-part="header">
+        <h2 data-part="title" id=${this.#headerId}>Integrations</h2>
+        <slot name="header"></slot>
+      </header>
+
+      <div data-part="toolbar" role="search">
+        <search-ui
+          data-part="search"
+          placeholder=${placeholder}
+          value=${this.#query}
+          aria-label="Search integrations"
+        ></search-ui>
+
+        <segmented-ui
+          data-part="filter"
+          value=${filterValue}
+          aria-label="Filter integrations by status"
+        >
+          ${FILTER_OPTIONS.map((opt) => html`
+            <segment-ui
+              value=${opt.value}
+              text=${opt.label}
+              data-filter=${opt.value}
+            ></segment-ui>
+          `)}
+        </segmented-ui>
+      </div>
+
+      ${isLoading
+        ? this.#renderSkeleton()
+        : this.#renderGroupsOrEmpty(groups)}
+    `;
+  }
+
+  #renderSkeleton() {
+    const tiles = [];
+    for (let i = 0; i < SKELETON_COUNT; i++) {
+      tiles.push(html`
+        <div data-part="skeleton-tile" aria-hidden="true"></div>
+      `);
+    }
+    return html`
+      <div data-part="skeleton" aria-busy="true" aria-live="polite">
+        <grid-ui columns="1 2@sm 3@lg" gap="md">
+          ${tiles}
+        </grid-ui>
+      </div>
+    `;
+  }
+
+  #renderGroupsOrEmpty(groups) {
+    const totalVisible = groups.reduce((sum, g) => sum + g.items.length, 0);
+    const integrationsArr = Array.isArray(this.integrations) ? this.integrations : [];
+    if (totalVisible === 0) {
+      const hasData = integrationsArr.length > 0;
+      const reason = hasData ? 'empty-search' : 'empty-data';
+      return this.#renderEmpty(reason);
+    }
+    return html`
+      <div data-part="sections">
+        ${groups.map((g) => this.#renderSection(g))}
+      </div>
+    `;
+  }
+
+  #renderSection(group) {
+    const { label, items, key } = group;
+    // group-by="none" → single ungrouped grid, no heading
+    if (group.key === '__none__') {
+      return html`
+        <section data-part="section" data-group="__none__">
+          <grid-ui columns="1 2@sm 3@lg" gap="md">
+            ${items.map((item) => this.#renderCard(item))}
+          </grid-ui>
+        </section>
+      `;
+    }
+    return html`
+      <section data-part="section" data-group=${key} role="group" aria-label=${label}>
+        <text-ui data-part="section-heading" variant="kicker">${label}</text-ui>
+        <grid-ui columns="1 2@sm 3@lg" gap="md">
+          ${items.map((item) => this.#renderCard(item))}
+        </grid-ui>
+      </section>
+    `;
+  }
+
+  #renderCard(item) {
+    // The card primitive expects flat string attributes; map our descriptor
+    // shape onto its prop contract. We let card-ui handle status-driven
+    // button rendering, badge, and event emission.
+    const provider    = String(item?.provider ?? '');
+    const name        = String(item?.name ?? '');
+    const description = String(item?.description ?? '');
+    const logo        = String(item?.logo ?? '');
+    const status      = String(item?.status ?? 'available');
+    const errMsg      = String(item?.['error-message'] ?? item?.errorMessage ?? '');
+    return html`
+      <integration-card-ui
+        data-provider=${provider}
+        provider=${provider}
+        name=${name}
+        description=${description}
+        logo=${logo}
+        status=${status}
+        error-message=${errMsg}
+      ></integration-card-ui>
+    `;
+  }
+
+  #renderEmpty(reason) {
+    const isSearch = reason === 'empty-search';
+    const heading = isSearch
+      ? `No integrations match "${this.#query}"`
+      : 'No integrations available yet';
+    const desc = isSearch
+      ? 'Try a different keyword or clear the search.'
+      : 'Integrations will appear here once they are available.';
+    return html`
+      <div data-part="empty" data-empty-reason=${reason} role="status">
+        <slot name="empty">
+          <text-ui data-part="empty-heading" variant="heading">${heading}</text-ui>
+          <text-ui data-part="empty-description" variant="body" color="subtle">${desc}</text-ui>
+        </slot>
+      </div>
+    `;
+  }
+
+  // ── data shaping ────────────────────────────────────────────────
+
+  /**
+   * Apply search + status-filter, then bucket by `group-by`. Returns
+   * an array of `{ key, label, items }`.
+   *
+   * `group-by="none"` returns a single synthetic group with key
+   * `__none__` so the renderer can skip the heading.
+   */
+  #computeGroups() {
+    const all = Array.isArray(this.integrations) ? this.integrations : [];
+    const q = (this.#query || '').trim().toLowerCase();
+    const statusFilter = this['status-filter'] || 'all';
+
+    const filtered = all.filter((item) => {
+      if (!item || typeof item !== 'object') return false;
+      // Status filter
+      if (statusFilter !== 'all') {
+        const itemStatus = String(item.status ?? 'available');
+        if (itemStatus !== statusFilter) return false;
+      }
+      // Search filter — matches name, description, provider, category
+      if (q) {
+        const hay = [
+          item.name,
+          item.description,
+          item.provider,
+          item.category,
+        ].map((s) => String(s ?? '').toLowerCase()).join(' ');
+        if (!hay.includes(q)) return false;
+      }
+      return true;
+    });
+
+    const groupBy = this['group-by'] || 'category';
+    if (groupBy === 'none') {
+      return [{ key: '__none__', label: '', items: filtered }];
+    }
+
+    // Group by the chosen key. Preserve first-seen order so the section
+    // order is stable across re-renders.
+    const order = [];
+    const map = new Map();
+    for (const item of filtered) {
+      const raw = groupBy === 'status'
+        ? String(item.status ?? 'available')
+        : String(item.category ?? 'Other');
+      const key = raw || 'Other';
+      if (!map.has(key)) {
+        map.set(key, []);
+        order.push(key);
+      }
+      map.get(key).push(item);
+    }
+    return order.map((key) => ({
+      key,
+      label: groupBy === 'status' ? this.#statusLabel(key) : key,
+      items: map.get(key),
+    }));
+  }
+
+  #statusLabel(status) {
+    switch (status) {
+      case 'available':   return 'Available';
+      case 'connected':   return 'Connected';
+      case 'error':       return 'Issues';
+      case 'pending':     return 'Connecting';
+      case 'coming-soon': return 'Coming soon';
+      default:            return status || 'Other';
+    }
+  }
+
+  #syncEmptyAttrs() {
+    const all = Array.isArray(this.integrations) ? this.integrations : [];
+    const groups = this.#computeGroups();
+    const totalVisible = groups.reduce((sum, g) => sum + g.items.length, 0);
+    if (this.loading) {
+      this.removeAttribute('data-empty-search');
+      this.removeAttribute('data-empty-data');
+      return;
+    }
+    if (totalVisible === 0 && all.length > 0) {
+      this.setAttribute('data-empty-search', '');
+      this.removeAttribute('data-empty-data');
+    } else if (all.length === 0) {
+      this.setAttribute('data-empty-data', '');
+      this.removeAttribute('data-empty-search');
+    } else {
+      this.removeAttribute('data-empty-search');
+      this.removeAttribute('data-empty-data');
+    }
+  }
+
+  // ── event delegation ────────────────────────────────────────────
+
+  /**
+   * Listen for the inner <search-ui> emitting `input`. We track the
+   * query locally (drives the filter), debounce the upward `search`
+   * emit so external listeners aren't spammed.
+   */
+  #onSearchInput = (e) => {
+    const target = e.target;
+    if (!target || !target.closest) return;
+    const search = target.closest('search-ui[data-part="search"]');
+    if (!search || !this.contains(search)) return;
+
+    const value = String(e.detail?.value ?? search.value ?? '');
+    this.#query = value;
+
+    // Trigger a re-render to apply the filter. UIElement reactivity is
+    // property-based; we toggle a private signal indirectly by setting
+    // a dummy reflection here is overkill — just request a render via
+    // a no-op property assignment. Simpler: mutate the array reference.
+    this.integrations = Array.isArray(this.integrations) ? [...this.integrations] : [];
+
+    // Debounce upward emit so consumers don't get spammed.
+    if (this.#searchTimer) clearTimeout(this.#searchTimer);
+    this.#searchTimer = setTimeout(() => {
+      this.dispatchEvent(new CustomEvent('search', {
+        bubbles: true,
+        detail: { query: value.toLowerCase().trim() },
+      }));
+    }, 250);
+  };
+
+  /**
+   * Listen for the inner <segmented-ui> emitting `change` with a new
+   * value. Update [status-filter] + re-render + emit `filter-change`.
+   */
+  #onFilterChange = (e) => {
+    const target = e.target;
+    if (!target || !target.closest) return;
+    const segmented = target.closest('segmented-ui[data-part="filter"]');
+    if (!segmented || !this.contains(segmented)) return;
+
+    const value = String(e.detail?.value ?? segmented.value ?? 'all');
+    if (this['status-filter'] === value) return;
+    this['status-filter'] = value;
+
+    this.dispatchEvent(new CustomEvent('filter-change', {
+      bubbles: true,
+      detail: { status: value },
+    }));
+  };
+}
+
+if (!customElements.get('integrations-page-ui')) {
+  customElements.define('integrations-page-ui', UIIntegrationsPage);
+}
+
+export { UIIntegrationsPage };