@adia-ai/web-modules 0.8.36 → 0.8.37

package/form/form-popover/form-popover.js

@@ -24,7 +24,7 @@
  * truth, same rule as chart-legend-ui's peer contract).
  */
 
-import { UIElement } from '../../../web-components/core/element.js';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 const SUMMARY_EVENTS = ['change', 'input'];
 

package/generative/index.d.ts

@@ -8,4 +8,4 @@ export { A2UIRoot } from '@adia-ai/web-modules/runtime';
 export { UICanvas as Canvas } from '@adia-ai/web-components/components/canvas';
 export {
   registerResolver,
-} from '@adia-ai/a2ui-runtime';
+} from '@adia-ai/a2ui';

package/generative/index.js

@@ -22,7 +22,7 @@
  *   import { Canvas, A2UIRoot, registerResolver }
  *     from '@adia-ai/web-modules/generative';
  *
- * Pairs with the @adia-ai/a2ui-runtime registry (registerResolver, etc.)
+ * Pairs with the @adia-ai/a2ui registry (registerResolver, etc.)
  * for wiring data sources to api:// + resource:// URIs.
  */
 
@@ -42,4 +42,4 @@ export { UICanvas as Canvas } from '@adia-ai/web-components/components/canvas';
 // without a second import.
 export {
   registerResolver,
-} from '@adia-ai/a2ui-runtime';
+} from '@adia-ai/a2ui';

package/onboarding/index.js

@@ -0,0 +1 @@
+export { UIOnboardingChecklist } from './onboarding-checklist/onboarding-checklist.js';

package/onboarding/onboarding-checklist/onboarding-checklist.a2ui.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/OnboardingChecklist.json",
+  "title": "OnboardingChecklist",
+  "description": "Module-tier onboarding checklist — a progressive setup-step widget\n(\"Getting started\" card seen in Stripe / Linear / Vercel dashboards).\nComposes <progress-ui> (top fill bar), <list-ui> + <list-item-ui>\n(the step rows), <check-ui> (per-item completion checkbox), and\noptional <button-ui> (per-item action CTA).\n\nOwns the data model (items: array of {id, label, description, href,\ndone}), the persistence contract (storage-key writes a JSON blob to\nlocalStorage / sessionStorage), the auto-computed progress display,\nand the dismiss-on-complete behavior. Items are data, not slotted\nmarkup — host wiring uses stable per-item ids, not DOM positions.\n\nUse for the \"card of optional setup tasks\" case; use <step-progress-ui>\nfor horizontal multi-screen wizards where the user is locked into\nlinear progression.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "title": {
+      "description": "Header label above the progress bar. Defaults to \"Get started\".",
+      "type": "string",
+      "default": "Get started"
+    },
+    "items": {
+      "description": "Step list — each item is { id, label, description?, href?, done? }. Required, non-empty.",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "collapsed": {
+      "description": "Initial / current collapsed state — hides the item list, keeps progress + header visible.",
+      "$ref": "common_types.json#/$defs/DynamicBoolean"
+    },
+    "collapsible": {
+      "description": "Show a top-right collapse toggle.",
+      "type": "boolean",
+      "default": true
+    },
+    "component": {
+      "const": "OnboardingChecklist"
+    },
+    "dismiss-on-complete": {
+      "description": "Auto-hide the widget when all items are done.",
+      "type": "boolean",
+      "default": true
+    },
+    "storage": {
+      "description": "Persistence backend when storage-key is set.",
+      "type": "string",
+      "enum": [
+        "local",
+        "session",
+        "none"
+      ],
+      "default": "local"
+    },
+    "storage-key": {
+      "description": "localStorage key for per-item completion persistence. Empty string disables storage (ephemeral).",
+      "type": "string",
+      "default": ""
+    },
+    "value": {
+      "description": "Completion map mapping item id to boolean. When set, host owns state and storage attributes are ignored.",
+      "type": "object",
+      "default": {}
+    }
+  },
+  "required": [
+    "component",
+    "items"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{ \"component\": \"OnboardingChecklist\", \"items\": [{ \"id\": \"x\", \"label\": \"Step 1\" }] }\n",
+        "why": "Empty checklist — renders an empty card.\n",
+        "wrong": "{ \"component\": \"OnboardingChecklist\", \"items\": [] }\n"
+      },
+      {
+        "fix": "{ \"component\": \"OnboardingChecklist\", \"items\": [\n  { \"id\": \"a\", \"label\": \"Step A\" }, { \"id\": \"b\", \"label\": \"Step B\" }\n] }\n",
+        "why": "Items missing `id`. The component cannot persist completion\nwithout stable per-item identifiers.\n",
+        "wrong": "{ \"component\": \"OnboardingChecklist\", \"items\": [\n  { \"label\": \"Step A\" }, { \"label\": \"Step B\" }\n] }\n"
+      }
+    ],
+    "category": "feedback",
+    "composes": [],
+    "events": {
+      "onboarding-complete": {
+        "description": "Fired when all items become done.",
+        "detail": {
+          "value": {
+            "description": "The completion map at the moment of full completion.",
+            "type": "object"
+          }
+        }
+      },
+      "onboarding-dismiss": {
+        "description": "Fired when the widget collapses or auto-dismisses on completion.",
+        "detail": {
+          "reason": {
+            "description": "Why the widget was dismissed.",
+            "type": "string",
+            "enum": [
+              "collapsed",
+              "complete"
+            ]
+          }
+        }
+      },
+      "onboarding-step-action": {
+        "description": "Fired when the user clicks an item's action CTA.",
+        "detail": {
+          "href": {
+            "description": "The href of the CTA (may be empty when host wires the click elsewhere).",
+            "type": "string"
+          },
+          "id": {
+            "description": "The id of the step whose CTA was clicked.",
+            "type": "string"
+          }
+        }
+      },
+      "onboarding-step-complete": {
+        "description": "Fired when a step transitions from undone to done.",
+        "detail": {
+          "id": {
+            "description": "The id of the step that just completed.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Snapshot of the full completion map after the change.",
+            "type": "object"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Three-step dashboard setup card.",
+        "a2ui": "[\n  {\n    \"id\": \"onb-1\",\n    \"component\": \"OnboardingChecklist\",\n    \"storageKey\": \"acme:onboarding:v1\",\n    \"items\": [\n      { \"id\": \"profile\", \"label\": \"Complete your profile\", \"description\": \"Add a photo and bio\", \"href\": \"/settings/profile\" },\n      { \"id\": \"team\",    \"label\": \"Invite your team\",      \"description\": \"Add at least one teammate\", \"href\": \"/settings/team\" },\n      { \"id\": \"connect\", \"label\": \"Connect a data source\", \"description\": \"Hook up the first integration\", \"href\": \"/integrations\" }\n    ]\n  }\n]\n",
+        "name": "basic-checklist"
+      }
+    ],
+    "keywords": [
+      "onboarding",
+      "checklist",
+      "getting-started",
+      "setup",
+      "steps",
+      "progress",
+      "getting started"
+    ],
+    "name": "UIOnboardingChecklist",
+    "related": [
+      "Check",
+      "List",
+      "ListItem",
+      "Progress",
+      "Button",
+      "StepProgress"
+    ],
+    "slots": {
+      "description": {
+        "description": "Optional subtitle / supporting prose rendered beneath the header. Renders at body-subtle typography. Use for richer markup than the plain [description] attribute string."
+      },
+      "complete": {
+        "description": "Content shown when all items are done and dismiss-on-complete is false."
+      },
+      "footer": {
+        "description": "Optional footer content (e.g. \"Skip for now\" link / button)."
+      },
+      "header": {
+        "description": "Custom title region above the progress bar. Overrides the default [title] attribute label."
+      }
+    },
+    "states": [
+      {
+        "description": "Some items incomplete; widget visible and expanded.",
+        "name": "idle"
+      },
+      {
+        "description": "Item list hidden; header + progress visible.",
+        "attribute": "collapsed",
+        "name": "collapsed"
+      },
+      {
+        "description": "All items done. Behavior depends on dismiss-on-complete.",
+        "attribute": "data-complete",
+        "name": "complete"
+      },
+      {
+        "description": "Widget removed from layout after collapse or auto-dismiss.",
+        "attribute": "hidden",
+        "name": "dismissed"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "checklist": [
+        "todo",
+        "task-list",
+        "steps"
+      ],
+      "getting-started": [
+        "onboarding",
+        "setup",
+        "welcome"
+      ],
+      "onboarding": [
+        "getting-started",
+        "setup",
+        "welcome",
+        "kickoff"
+      ],
+      "setup": [
+        "onboarding",
+        "getting-started",
+        "configuration"
+      ]
+    },
+    "tag": "onboarding-checklist-ui",
+    "tokens": {
+      "--onboarding-checklist-bg": {
+        "description": "Card background. Defaults to elevated canvas tier.",
+        "default": "var(--a-canvas-1)"
+      },
+      "--onboarding-checklist-border": {
+        "description": "Outer border.",
+        "default": "1px solid var(--a-border-subtle)"
+      },
+      "--onboarding-checklist-fg": {
+        "description": "Primary foreground color.",
+        "default": "var(--a-fg)"
+      },
+      "--onboarding-checklist-fg-muted": {
+        "description": "Secondary foreground color for descriptions + meta.",
+        "default": "var(--a-fg-muted)"
+      },
+      "--onboarding-checklist-gap": {
+        "description": "Gap between header / progress / items / footer.",
+        "default": "var(--a-space-3)"
+      },
+      "--onboarding-checklist-progress-fill": {
+        "description": "Progress-bar fill color (forwarded to inner <progress-ui> via --progress-fill).",
+        "default": "var(--md-sys-color-primary)"
+      },
+      "--onboarding-checklist-px": {
+        "description": "Inline (left/right) padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--onboarding-checklist-py": {
+        "description": "Block (top/bottom) padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--onboarding-checklist-radius": {
+        "description": "Outer card radius.",
+        "default": "var(--a-radius-lg)"
+      },
+      "--onboarding-checklist-shadow": {
+        "description": "Card elevation.",
+        "default": "var(--a-shadow-sm)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/onboarding/onboarding-checklist/onboarding-checklist.css

@@ -0,0 +1,157 @@
+/* ═══════════════════════════════════════════════════════════════
+   onboarding-checklist-ui — Module CSS
+
+   Two-block @scope:
+     Block 1 — TOKENS  (:where(:scope))
+     Block 2 — BASE    (:scope + descendant rules)
+
+   Tokens consumed (substrate):
+     --a-canvas-1, --a-fg, --a-fg-muted, --a-primary,
+     --a-radius-lg, --a-shadow-sm, --a-border-subtle,
+     --a-space-1, --a-space-2, --a-space-3, --a-space-4,
+     --a-bg-muted, --a-focus-ring, --a-ui-sm, --a-weight-medium
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (onboarding-checklist-ui) {
+
+  /* ── Block 1: TOKENS ────────────────────────────────────────── */
+
+  :where(:scope) {
+    --onboarding-checklist-bg:            var(--a-canvas-1);
+    --onboarding-checklist-fg:            var(--md-sys-color-neutral-on-surface);
+    --onboarding-checklist-fg-muted:      var(--a-fg-muted);
+    --onboarding-checklist-radius:        var(--a-radius-lg);
+    --onboarding-checklist-px:            var(--a-space-4);
+    --onboarding-checklist-py:            var(--a-space-4);
+    --onboarding-checklist-gap:           var(--a-space-3);
+    --onboarding-checklist-progress-fill: var(--md-sys-color-primary);
+    --onboarding-checklist-shadow:        var(--a-shadow-sm);
+    --onboarding-checklist-border:        1px solid var(--md-sys-color-neutral-outline-variant);
+  }
+
+  /* ── Block 2: BASE ──────────────────────────────────────────── */
+
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    padding: var(--onboarding-checklist-py) var(--onboarding-checklist-px);
+    background: var(--onboarding-checklist-bg);
+    color: var(--onboarding-checklist-fg);
+    border-radius: var(--onboarding-checklist-radius);
+    border: var(--onboarding-checklist-border);
+    box-shadow: var(--onboarding-checklist-shadow);
+  }
+
+  :scope[hidden] {
+    display: none;
+  }
+
+  /* Header ── title + collapse toggle */
+  :scope > [data-part="header"] {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    gap: var(--a-space-2);
+    margin-block-end: var(--onboarding-checklist-gap);
+  }
+
+  :scope > [data-part="header"] > [data-part="title"] {
+    flex: 1;
+    min-width: 0;
+    font-weight: var(--a-weight-medium);
+    color: var(--onboarding-checklist-fg);
+  }
+
+  :scope > [data-part="header"] > [data-part="collapse-toggle"] {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--a-space-1);
+    margin: 0;
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--a-radius-md);
+    color: var(--onboarding-checklist-fg-muted);
+    cursor: pointer;
+    font: inherit;
+    /* font-family floor — see segment.css rationale (inline default). */
+    font-family: var(--onboarding-checklist-font-family, var(--a-font-family-ui));
+    appearance: none;
+  }
+
+  :scope > [data-part="header"] > [data-part="collapse-toggle"]:hover {
+    background: var(--a-bg-muted);
+    color: var(--onboarding-checklist-fg);
+  }
+
+  :scope > [data-part="header"] > [data-part="collapse-toggle"]:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
+  }
+
+  /* Progress bar — forward token to inner <progress-ui> */
+  :scope > [data-part="progress"] {
+    --progress-fill: var(--onboarding-checklist-progress-fill);
+    display: block;
+    margin-block-end: var(--onboarding-checklist-gap);
+  }
+
+  /* Live region — visually hidden but read by SR */
+  :scope > [data-part="meter"] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* Item list */
+  :scope > [data-part="items"] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-2);
+    margin: 0;
+  }
+
+  /* Complete-slot — shown when all done + dismiss-on-complete=false. Sits
+     BELOW the item list (template order), so it needs LEADING spacing to
+     separate it from the items above — matching the footer convention.
+     Descendant (not child) combinator: the conditional render branch
+     (`${allDone ? html`…` : null}`) is wrapped by the template engine in a
+     <span style="display:contents">, so `:scope > [data-part]` never matches.
+     The static header/progress/items/footer above stay `:scope >`. */
+  :scope [data-part="complete"] {
+    margin-block-start: var(--onboarding-checklist-gap);
+    color: var(--onboarding-checklist-fg-muted);
+  }
+
+  /* Footer slot */
+  :scope > [data-part="footer"] {
+    margin-block-start: var(--onboarding-checklist-gap);
+  }
+
+  :scope > [data-part="footer"]:empty {
+    display: none;
+  }
+
+  /* Collapsed state — hide body, keep header + progress. The complete block
+     is wrapped in a display:contents span (conditional render), so its rule
+     uses the descendant combinator while the static items/footer keep `>`. */
+  :scope[collapsed] > [data-part="items"],
+  :scope[collapsed] > [data-part="footer"],
+  :scope[collapsed] [data-part="complete"] {
+    display: none;
+  }
+
+  /* Done items — dim the description slightly so progression reads. */
+  :scope [data-item-id][data-done="true"] [slot="description"] {
+    color: var(--onboarding-checklist-fg-muted);
+    text-decoration: line-through;
+    text-decoration-color: var(--md-sys-color-neutral-outline-variant);
+  }
+}