@adia-ai/web-modules 0.8.35 → 0.8.37

package/settings/integrations-page/integrations-page.yaml

@@ -0,0 +1,317 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIIntegrationsPage
+tag: integrations-page-ui
+status: stable
+component: IntegrationsPage
+category: container
+version: 1
+description: |
+  Module-tier Settings page composite — a searchable, category-grouped
+  grid of <integration-card-ui> tiles (SPEC-062). Owns the
+  `integrations` array, the search-filter state, the category /
+  status grouping, the responsive grid breakpoints, and the empty-state
+  copy. Card-level events (`connect` / `configure` / `disconnect` /
+  `retry`) bubble up unchanged with `provider` in detail; the page also
+  emits `search` (debounced) and a top-bar `filter-change` when the
+  user picks a status chip.
+
+  Lives in `packages/web-modules/settings/integrations-page/` per the
+  three-tier architecture — composes multiple primitives, holds layout
+  responsibility, consumed by the settings shell. Replaces the
+  hand-rolled `settings/integrations` HTML template per consumer.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-063-integrations-page.md
+
+# Per ADR-0027 — composites that programmatically create primitives in
+# their render() do NOT auto-import those primitives. Consumer (or demo
+# shell) must explicitly import each composed primitive.
+composes:
+  - integration-card-ui
+  - grid-ui
+  - search-ui
+  - segmented-ui
+  - segment-ui
+  - text-ui
+
+props:
+  integrations:
+    description: |
+      Array of integration descriptors — each item conforms to the
+      SPEC-062 <integration-card-ui> prop shape:
+      `{ provider, name, logo?, description?, status, category?,
+      error-message? }`. Empty array renders the empty-state slot.
+    type: array
+    default: []
+    required: true
+    dynamic: true
+  loading:
+    description: |
+      Renders a skeleton grid (6 tiles) instead of cards. Driven by the
+      consumer while the integrations payload is in flight.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+  search-placeholder:
+    description: |
+      Placeholder copy for the built-in search input. Defaults to
+      "Search integrations".
+    type: string
+    default: "Search integrations"
+    reflect: true
+  group-by:
+    description: |
+      How to bucket cards into sections. `category` groups by the per-item
+      `category` key; `status` groups by connection state; `none` renders
+      a single ungrouped grid.
+    type: string
+    default: category
+    enum:
+      - category
+      - status
+      - none
+    reflect: true
+  status-filter:
+    description: |
+      Optional status filter — restricts the visible cards to one status.
+      `all` (default) shows everything; the rest restrict to that status
+      bucket. Reflects so consumers can deep-link.
+    type: string
+    default: all
+    enum:
+      - all
+      - available
+      - connected
+      - error
+      - coming-soon
+    reflect: true
+    dynamic: true
+
+events:
+  connect:
+    description: Bubbled from a child <integration-card-ui> when its primary button is pressed while `status="available"`.
+    detail:
+      provider:
+        type: string
+        description: The provider key of the card that fired.
+  configure:
+    description: Bubbled from a child <integration-card-ui> while `status="connected"`.
+    detail:
+      provider:
+        type: string
+        description: The provider key of the card that fired.
+  disconnect:
+    description: Bubbled from a child card's overflow menu disconnect item.
+    detail:
+      provider:
+        type: string
+        description: The provider key of the card that fired.
+  retry:
+    description: Bubbled from a child <integration-card-ui> while `status="error"`.
+    detail:
+      provider:
+        type: string
+        description: The provider key of the card that fired.
+  search:
+    description: Debounced search input change.
+    detail:
+      query:
+        type: string
+        description: The current search query (lower-cased, trimmed).
+  filter-change:
+    description: User clicked a status filter chip in the top bar.
+    detail:
+      status:
+        type: string
+        description: The newly-selected status filter (`all` resets).
+
+slots:
+  header:
+    description: |
+      Optional page header (kicker / title / subtitle). Overrides the
+      default rendering — when supplied the composite stamps no
+      built-in heading.
+  empty:
+    description: |
+      Optional override for the empty-state copy. When supplied, replaces
+      the built-in "No integrations match" / "No integrations available"
+      messages.
+
+states:
+  - name: idle
+    description: Default; renders all groups matching the current filter.
+  - name: loading
+    description: Skeleton grid; cards hidden.
+    attribute: loading
+  - name: empty-search
+    description: Search query yields zero cards.
+    attribute: data-empty-search
+  - name: empty-data
+    description: "`integrations` array is empty."
+    attribute: data-empty-data
+
+traits: []
+
+tokens:
+  --integrations-page-bg:
+    description: Page background. Defaults to `var(--a-bg)`.
+    default: var(--a-bg)
+  --integrations-page-fg:
+    description: Primary foreground. Defaults to `var(--a-fg)`.
+    default: var(--a-fg)
+  --integrations-page-fg-muted:
+    description: Secondary foreground for empty-state copy + section meta.
+    default: var(--a-fg-muted)
+  --integrations-page-px:
+    description: Horizontal padding around the page.
+    default: var(--a-space-5)
+  --integrations-page-py:
+    description: Vertical padding around the page.
+    default: var(--a-space-5)
+  --integrations-page-gap:
+    description: Vertical gap between toolbar / sections / empty-state.
+    default: var(--a-space-5)
+  --integrations-page-section-gap:
+    description: Vertical gap between sibling category sections.
+    default: var(--a-space-6)
+  --integrations-page-card-gap:
+    description: Gap inside the grid between cards.
+    default: var(--a-space-4)
+  --integrations-page-grid-min:
+    description: Minimum card width for the auto-fill grid track.
+    default: var(--a-space-12)
+  --integrations-page-section-heading-fg:
+    description: Section heading color.
+    default: var(--a-fg-strong)
+  --integrations-page-section-heading-size:
+    description: Section heading font size.
+    default: var(--a-ui-sm)
+  --integrations-page-section-heading-weight:
+    description: Section heading font weight.
+    default: var(--a-weight-medium)
+
+a2ui:
+  rules:
+    - rule: |
+        Use <integrations-page-ui> for the canonical Settings >
+        Integrations grid. Supply the `integrations` array — the
+        composite owns the search + grouping + grid breakpoints +
+        empty state.
+      reason: One composite replaces the per-app hand-rolled grid.
+    - rule: |
+        `integrations` MUST be a non-empty array OR the page renders
+        the empty-state. Each item MUST satisfy the SPEC-062 card
+        prop contract (provider + name required).
+      reason: Cards generated from data; missing required keys break a11y wiring.
+    - rule: |
+        Do NOT slot <integration-card-ui> children directly — the page
+        generates cards from the `integrations` prop. Slotted children
+        are ignored.
+      reason: Single source of truth (prop), not mixed slot + data.
+    - rule: |
+        Do NOT nest <integrations-page-ui> inside another
+        <integrations-page-ui>.
+      reason: Composite carries page-level layout; nesting double-pads + double-toolbars.
+    - rule: |
+        For one-off integration tile groups (e.g., a single recommended
+        provider on a marketing page) use <integration-card-ui> directly
+        inside <grid-ui>; reach for the page composite only when search
+        + grouping + empty-state semantics are needed.
+      reason: Capacity guidance — page is a Settings construct.
+
+anti_patterns:
+  - wrong: |
+      {"component": "IntegrationsPage", "children": [
+        {"component": "IntegrationCard", "provider": "slack", "name": "Slack"}
+      ]}
+    why: |
+      Slotted cards are ignored — the page generates cards from the
+      `integrations` prop. The page renders empty.
+    fix: |
+      {"component": "IntegrationsPage", "integrations": [
+        {"provider": "slack", "name": "Slack", "status": "available"}
+      ]}
+  - wrong: |
+      {"component": "Page", "children": [
+        {"component": "Grid", "children": [
+          {"component": "IntegrationCard", "provider": "slack", "name": "Slack"}
+        ]}
+      ]}
+    why: |
+      Re-implements the page composite with primitives. Loses search,
+      grouping, and empty-state semantics.
+    fix: |
+      {"component": "IntegrationsPage", "integrations": [
+        {"provider": "slack", "name": "Slack", "status": "available"}
+      ]}
+
+examples:
+  - name: category-grouped
+    description: Full integrations page grouped by category (default).
+    a2ui: |
+      [
+        {
+          "id": "page",
+          "component": "IntegrationsPage",
+          "group-by": "category",
+          "integrations": [
+            {"provider": "slack",  "name": "Slack",  "logo": "/integrations/slack.svg",
+             "description": "Notifications and replies in channels.",
+             "status": "connected", "category": "Communication"},
+            {"provider": "github", "name": "GitHub", "logo": "/integrations/github.svg",
+             "description": "Sync issues and pull requests.",
+             "status": "available", "category": "Developer Tools"},
+            {"provider": "stripe", "name": "Stripe", "logo": "/integrations/stripe.svg",
+             "description": "Charge customers and reconcile invoices.",
+             "status": "error", "category": "Payments",
+             "error-message": "Token expired — re-authenticate."}
+          ]
+        }
+      ]
+  - name: loading-skeleton
+    description: Loading state — 6 skeleton tiles, no cards.
+    a2ui: |
+      [{"id": "page", "component": "IntegrationsPage", "loading": true}]
+  - name: empty-data
+    description: Empty state — no integrations available.
+    a2ui: |
+      [{"id": "page", "component": "IntegrationsPage", "integrations": []}]
+
+keywords:
+  - integrations
+  - integration
+  - settings
+  - settings-page
+  - connections
+  - third-party
+  - oauth
+  - providers
+  - app-directory
+  - marketplace
+
+synonyms:
+  integrations:
+    - integration
+    - connections
+    - apps
+    - providers
+  settings:
+    - settings
+    - account
+    - admin
+  marketplace:
+    - integrations
+    - app-directory
+    - apps
+  oauth:
+    - integration
+    - connection
+    - auth
+
+related:
+  - IntegrationCard
+  - Grid
+  - Search
+  - Segmented
+  - Page

package/settings/notification-preferences/notification-preferences.a2ui.json

@@ -0,0 +1,245 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/NotificationPreferences.json",
+  "title": "NotificationPreferences",
+  "description": "Page-level Settings composite: a matrix of notification types (rows)\n× delivery channels (columns: in-app, email, SMS) with a binary\n<check-ui> in each cell and an optional <switch-ui> column-header\nmaster toggle for bulk-flipping a channel across every row.\n\nForm-bearing — the composite extends UIFormElement and serializes its\ncurrent preferences shape as JSON on `value`. Per first-principle #2\n(\"save is the consumer's job\"), the composite does NOT mutate the\npassed-in `preferences` array; it emits a typed `change` event per\ncell toggle and a `bulk-toggle` event per column-header switch, and\nexposes the staged JSON via the form value so a host <form> submit\ncarries it through ElementInternals.\n\nChannels are columns; types are rows (the smaller-set / larger-set\ninvariant — channels are 3-5 in the wild, types are 10-50). Layout\nrenders as a semantic ARIA grid (`role=\"table\"`/`row`/`cell`/\n`rowheader`/`columnheader`) — NOT native `<table>` (per the HTML\nparser strip rule, table-content tags would foster-parent out of a\ncustom-element subtree).\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-064-notification-preferences.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "channelEnabled": {
+      "description": "Map of channel-key → master-toggle boolean for the column-header\n<switch-ui>. When omitted, master toggles default to `true` for\nevery channel. Independent of cell values — toggling the master\noff does NOT auto-update the cells; the host receives a\n`bulk-toggle` event and updates `preferences` itself.\n",
+      "type": "object",
+      "default": {}
+    },
+    "channels": {
+      "description": "Column definitions — one record per delivery channel. Each\ncarries a stable `key`, a `label` (the column header), and an\noptional `icon` name (Phosphor — defaults to no icon when\nabsent). Example: [{key:\"in-app\", label:\"In-app\", icon:\"chat-circle\"},\n{key:\"email\", label:\"Email\", icon:\"envelope\"}]. Empty array\nrenders nothing (the matrix needs at least one column).\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "component": {
+      "const": "NotificationPreferences"
+    },
+    "disabled": {
+      "description": "All cells + master toggles become non-interactive.",
+      "type": "boolean",
+      "default": false
+    },
+    "group-by": {
+      "description": "Row-grouping mode. `none` (default) renders all rows in one\nblock. `group` renders one section per unique `preferences[].group`\nvalue with a header row above each section.\n",
+      "type": "string",
+      "enum": [
+        "none",
+        "group"
+      ],
+      "default": "none"
+    },
+    "loading": {
+      "description": "Renders a skeleton matrix overlay. Cells become non-interactive\nand dim while loading.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "preferences": {
+      "description": "Matrix data — one row per notification type. Each record carries\na stable `key`, a `label`, optional `description` (rendered under\nthe label), optional `group` (when `group-by=\"group\"`), and a\n`channels` map keyed by channel key with boolean values.\nExample: {key:\"mentions\", label:\"Mentions\", channels:{\"in-app\":true,\nemail:false, sms:false}}. Empty array renders the empty state.\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    }
+  },
+  "required": [
+    "component",
+    "preferences",
+    "channels"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<notification-preferences-ui id=\"prefs\"></notification-preferences-ui>\n<script>\n  document.querySelector('#prefs').channels = [\n    {key:'email', label:'Email'}\n  ];\n  document.querySelector('#prefs').preferences = [\n    {key:'mentions', label:'Mentions', channels:{email:true}},\n    {key:'replies',  label:'Replies',  channels:{email:false}}\n  ];\n</script>\n",
+        "why": "Cells are generated from the `preferences` matrix. Slotted\nswitches are ignored and the host renders empty.\n",
+        "wrong": "<notification-preferences-ui>\n  <switch-ui label=\"Email mentions\"></switch-ui>\n  <switch-ui label=\"Email replies\"></switch-ui>\n</notification-preferences-ui>\n"
+      },
+      {
+        "fix": "<notification-preferences-ui id=\"prefs\"></notification-preferences-ui>\n<script>/* set channels + preferences here */</script>\n",
+        "why": "Re-implements the matrix in raw HTML — loses the typed\n`change` / `bulk-toggle` event contract, the column-master\nswitch, the group-by support, and the consistent token-driven\nvisual treatment. Worse, table-content tags inside a custom\nelement subtree are foster-parented out of the DOM by the HTML\nparser — they silently vanish.\n",
+        "wrong": "<table>\n  <thead><tr><th></th><th>Email</th></tr></thead>\n  <tbody>\n    <tr><th>Mentions</th><td><check-ui></check-ui></td></tr>\n  </tbody>\n</table>\n"
+      }
+    ],
+    "category": "container",
+    "composes": [
+      "check-ui",
+      "switch-ui",
+      "icon-ui",
+      "text-ui",
+      "empty-state-ui"
+    ],
+    "events": {
+      "bulk-toggle": {
+        "description": "Fired when the user toggles a column-header <switch-ui>.\nBubbles. Mirrors `change` shape but for the column master —\nhost applies the bulk change to its own `preferences` data.\n",
+        "detail": {
+          "channel": {
+            "description": "The `key` of the channel column whose master flipped.",
+            "type": "string"
+          },
+          "enabled": {
+            "description": "The new desired master state.",
+            "type": "boolean"
+          }
+        }
+      },
+      "change": {
+        "description": "Fired when the user toggles a cell <check-ui>. Bubbles. The\ncomposite emits this with the previous state — the host must\napply the new state to its own data and re-pass `preferences`\nfor the cell to visually update.\n",
+        "detail": {
+          "channel": {
+            "description": "The `key` of the channel column whose cell flipped.",
+            "type": "string"
+          },
+          "enabled": {
+            "description": "The new desired state (true = opted in).",
+            "type": "boolean"
+          },
+          "row": {
+            "description": "The `key` of the notification type whose cell flipped.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Three channels (in-app / email / SMS) × four notification types.",
+        "a2ui": "[\n  {\n    \"id\": \"np-default\",\n    \"component\": \"NotificationPreferences\",\n    \"name\": \"notifications\",\n    \"channels\": [\n      {\"key\": \"in-app\", \"label\": \"In-app\", \"icon\": \"chat-circle\"},\n      {\"key\": \"email\",  \"label\": \"Email\",  \"icon\": \"envelope\"},\n      {\"key\": \"sms\",    \"label\": \"SMS\",    \"icon\": \"device-mobile\"}\n    ],\n    \"preferences\": [\n      {\"key\": \"mentions\", \"label\": \"Mentions\",\n       \"channels\": {\"in-app\": true, \"email\": true,  \"sms\": false}},\n      {\"key\": \"comments\", \"label\": \"Comments\",\n       \"channels\": {\"in-app\": true, \"email\": false, \"sms\": false}},\n      {\"key\": \"releases\", \"label\": \"Releases\",\n       \"channels\": {\"in-app\": false,\"email\": true,  \"sms\": false}},\n      {\"key\": \"security\", \"label\": \"Security alerts\",\n       \"channels\": {\"in-app\": true, \"email\": true,  \"sms\": true}}\n    ]\n  }\n]\n",
+        "name": "default"
+      },
+      {
+        "description": "Same matrix grouped by category via group-by=\"group\".",
+        "a2ui": "[\n  {\n    \"id\": \"np-grouped\",\n    \"component\": \"NotificationPreferences\",\n    \"name\": \"notifications\",\n    \"groupBy\": \"group\",\n    \"channels\": [\n      {\"key\": \"in-app\", \"label\": \"In-app\"},\n      {\"key\": \"email\",  \"label\": \"Email\"}\n    ],\n    \"preferences\": [\n      {\"key\": \"mentions\", \"label\": \"Mentions\", \"group\": \"Activity\",\n       \"channels\": {\"in-app\": true, \"email\": true}},\n      {\"key\": \"comments\", \"label\": \"Comments\", \"group\": \"Activity\",\n       \"channels\": {\"in-app\": true, \"email\": false}},\n      {\"key\": \"digest\",   \"label\": \"Weekly digest\", \"group\": \"Summaries\",\n       \"channels\": {\"in-app\": false, \"email\": true}}\n    ]\n  }\n]\n",
+        "name": "grouped"
+      }
+    ],
+    "keywords": [
+      "notification-preferences",
+      "notifications",
+      "preferences",
+      "opt-in",
+      "opt-out",
+      "alerts",
+      "channels",
+      "in-app",
+      "email",
+      "sms",
+      "subscriptions",
+      "notification-settings"
+    ],
+    "name": "UINotificationPreferences",
+    "related": [
+      "Check",
+      "Switch",
+      "Table",
+      "EmptyState",
+      "Icon",
+      "Text"
+    ],
+    "slots": {
+      "empty": {
+        "description": "Custom empty-state copy shown when `preferences` is empty. Falls\nback to a default <empty-state-ui> when not provided.\n"
+      },
+      "footer": {
+        "description": "Optional content below the matrix — e.g. a global Save Changes\nbutton row or fine-print disclaimer. Falls back to nothing.\n"
+      },
+      "header": {
+        "description": "Optional content above the matrix — e.g. a page title, intro\ncopy, or per-page save row. Falls back to nothing when empty.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — matrix rendered, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Skeleton overlay while data loads.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "All toggles non-interactive.",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "No notification types configured.",
+        "attribute": "empty",
+        "name": "empty"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "channels": [
+        "delivery",
+        "destinations"
+      ],
+      "notifications": [
+        "alerts",
+        "messages",
+        "updates"
+      ],
+      "preferences": [
+        "settings",
+        "opt-ins",
+        "subscriptions"
+      ]
+    },
+    "tag": "notification-preferences-ui",
+    "tokens": {
+      "--notification-preferences-bg": {
+        "description": "Host background.",
+        "default": "var(--a-bg)"
+      },
+      "--notification-preferences-border": {
+        "description": "Row separator color.",
+        "default": "var(--a-border-subtle)"
+      },
+      "--notification-preferences-channel-width": {
+        "description": "Minimum column width for each channel cell.",
+        "default": "var(--a-space-9)"
+      },
+      "--notification-preferences-group-fg": {
+        "description": "Group-heading label color.",
+        "default": "var(--a-fg-muted)"
+      },
+      "--notification-preferences-px": {
+        "description": "Host horizontal padding.",
+        "default": "var(--a-space-5)"
+      },
+      "--notification-preferences-py": {
+        "description": "Host vertical padding.",
+        "default": "var(--a-space-5)"
+      },
+      "--notification-preferences-radius": {
+        "description": "Outer matrix container radius.",
+        "default": "var(--a-radius-md)"
+      },
+      "--notification-preferences-row-bg": {
+        "description": "Even-row zebra background.",
+        "default": "var(--a-bg-muted)"
+      },
+      "--notification-preferences-row-label-min": {
+        "description": "Minimum row-label column width.",
+        "default": "12rem"
+      },
+      "--notification-preferences-row-px": {
+        "description": "Per-cell horizontal padding.",
+        "default": "var(--a-space-3)"
+      },
+      "--notification-preferences-row-py": {
+        "description": "Per-row vertical padding.",
+        "default": "var(--a-space-3)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}