@adia-ai/a2ui-corpus 0.6.38 → 0.6.39

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — @adia-ai/a2ui-corpus
 
+## [0.6.39] — 2026-05-26
+
+### Changed — catalog regen for `<tour-ui>` + slot-selector substrate sweep
+
+- `catalog-a2ui_0_9.json` + `_rules.txt` regenerated absorbing the new `<tour-ui>` + `<tour-step-ui>` primitives and substrate slot-selector sweep (+263 lines / +12 rule lines).
+- `chunk-embeddings.json` refreshed (corpus content unchanged from v0.6.38; timestamp refresh only).
+
 ## [0.6.38] — 2026-05-26
 
 ### Added — 1 new chunk + catalog regen for Wave 5e cohort

package/catalog-a2ui_0_9.json

@@ -13978,6 +13978,9 @@
           "description": {
             "description": "Override slot for richer description markup than the plain [description] attribute string (inline links, code spans, multiple lines). Renders beneath the primary text at body-subtle typography."
           },
+          "action": {
+            "description": "Trailing action affordance on the row (typically a `<button-ui>`). Promotes the row's grid from 2-column (icon | content) to 3-column (icon | content | action), right-aligned + vertically centered across both content rows. Used by `<onboarding-checklist-ui>` item rows and any consumer that needs an end-aligned action button on a list-item."
+          },
           "icon": {
             "description": "Override the [icon] glyph with a custom slotted element (e.g. a colored <icon-ui>, an image, or an avatar-ui). Mutually exclusive with the [icon] attribute — slot child wins if both are present."
           }
@@ -26105,6 +26108,266 @@
         "version": 1
       }
     },
+    "Tour": {
+      "title": "Tour",
+      "description": "Spotlight-driven product tour / guided walkthrough. Hosts a sequence\nof `<tour-step>` children, each targeting an element via CSS selector.\nWhen active, dims the page with a scrim, cuts a \"hole\" around the\ncurrent step's target, and renders a popover next to it with step\ncontent + Skip / Previous / Next navigation.\n\nUse for first-run onboarding tours, feature introductions after a\nrelease, and inline walkthroughs the user opts into (\"Take the tour\").\nDistinct from `<onboarding-checklist-ui>` (persistent todo-list of\nsetup steps the user works through at their own pace) and from\n`<tooltip-ui>` (single hover hint with no orchestration).\n\nArchitecture: tour-ui is a behavioral wrapper (`display: contents`)\nthat reads target / title / content from `<tour-step>` children. On\nstart, mounts a spotlight + popover surface into `document.body`\n(top-layer via Popover API). The spotlight is a transparent\nposition:fixed element with a huge box-shadow that produces the\ndimmed scrim outside its bounds (single-element backdrop, no clip-path\nor SVG mask needed). The popover is anchored to the target via the\nsame `core/anchor.js` pattern used by menu-ui / context-menu-ui /\npopover-ui.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "active": {
+          "description": "Whether the tour is currently running. Setting to `true` mounts\nthe spotlight + popover; setting to `false` tears down.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "auto-start": {
+          "description": "Start the tour automatically when the element connects. Useful for\nfirst-run flows gated by a storage flag on the consumer side.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "Tour"
+        },
+        "step": {
+          "description": "Current step index (0-based). Setting this property advances the\ntour to that step (updating spotlight + popover position).\n",
+          "type": "number",
+          "default": 0
+        },
+        "storage-key": {
+          "description": "Optional localStorage key. When set, the tour records its\ncompletion state (`\"done\"`) to that key on finish/skip — and\nrefuses to auto-start on subsequent loads if the key is \"done\".\nUseful for \"show this tour once per user\" flows.\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<tour-ui><tour-step target=\"#dashboard\" title=\"Dashboard\">Tour the dashboard…</tour-step>…</tour-ui>",
+            "why": "Bare divs have no target / title — tour-ui can't position the spotlight.",
+            "wrong": "<tour-ui><div>step 1 content</div><div>step 2 content</div></tour-ui>"
+          },
+          {
+            "fix": "<tour-step target=\"#dashboard\">",
+            "why": "target is a CSS selector — bare \"dashboard\" matches a <dashboard> element, NOT an id; use the # prefix.",
+            "wrong": "<tour-step target=\"dashboard\">"
+          }
+        ],
+        "category": "feedback",
+        "composes": [
+          "button-ui",
+          "tour-step-ui"
+        ],
+        "events": {
+          "tour-finish": {
+            "description": "Fired when the user completes the last step. detail = { totalSteps }. Bubbles."
+          },
+          "tour-skip": {
+            "description": "Fired when the user skips the tour mid-way. detail = { step, totalSteps }. Bubbles."
+          },
+          "tour-start": {
+            "description": "Fired when the tour starts (after spotlight + popover mount). detail = { step }. Bubbles."
+          },
+          "tour-step-change": {
+            "description": "Fired when the active step changes. detail = { from, to, totalSteps }. Bubbles."
+          }
+        },
+        "examples": [
+          {
+            "description": "A 3-step product tour anchored to selector-resolved elements.",
+            "a2ui": "[\n  { \"id\": \"tour\", \"component\": \"Tour\", \"auto-start\": true, \"children\": [\"s1\", \"s2\", \"s3\"] },\n  { \"id\": \"s1\", \"component\": \"TourStep\", \"target\": \"#dashboard\", \"title\": \"Your dashboard\", \"textContent\": \"Here's where you'll see your latest activity.\" },\n  { \"id\": \"s2\", \"component\": \"TourStep\", \"target\": \"#filters\", \"title\": \"Filters\", \"textContent\": \"Narrow results by status, owner, or date.\" },\n  { \"id\": \"s3\", \"component\": \"TourStep\", \"target\": \"#export\", \"title\": \"Export\", \"textContent\": \"Download a CSV of the current view.\" }\n]\n",
+            "name": "basic-tour"
+          }
+        ],
+        "keywords": [
+          "tour",
+          "product-tour",
+          "walkthrough",
+          "guided-tour",
+          "spotlight",
+          "coachmark",
+          "feature-introduction"
+        ],
+        "name": "UITour",
+        "related": [
+          "tooltip",
+          "popover",
+          "onboarding-checklist"
+        ],
+        "slots": {
+          "default": {
+            "description": "<tour-step> children — each declares target + title + body content."
+          }
+        },
+        "states": [
+          {
+            "description": "Tour is dormant; no scrim / popover rendered.",
+            "name": "idle"
+          },
+          {
+            "description": "Tour is running; scrim dims the page, current target is spotlighted.",
+            "name": "active"
+          },
+          {
+            "description": "Last step reached (Done is shown instead of Next).",
+            "name": "complete"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "spotlight": [
+            "coachmark",
+            "feature-highlight"
+          ],
+          "tour": [
+            "product-tour",
+            "guided-tour",
+            "walkthrough",
+            "feature-intro"
+          ]
+        },
+        "tag": "tour-ui",
+        "tokens": {
+          "--tour-popover-bg": {
+            "description": "Background of the step-content popover.",
+            "default": "var(--a-bg-subtle)"
+          },
+          "--tour-popover-border": {
+            "description": "Border color of the popover.",
+            "default": "var(--a-border-subtle)"
+          },
+          "--tour-popover-max-width": {
+            "description": "Maximum width of the popover.",
+            "default": "22rem"
+          },
+          "--tour-popover-min-width": {
+            "description": "Minimum width of the popover (so step text wraps reasonably).",
+            "default": "18rem"
+          },
+          "--tour-popover-radius": {
+            "description": "Border-radius of the popover.",
+            "default": "var(--a-radius-lg)"
+          },
+          "--tour-popover-shadow": {
+            "description": "Shadow of the popover.",
+            "default": "var(--a-shadow-lg)"
+          },
+          "--tour-scrim": {
+            "description": "Backdrop scrim color (everything outside the spotlight).",
+            "default": "var(--a-scrim-dialog)"
+          },
+          "--tour-spotlight-padding": {
+            "description": "Padding around the target bounding box (the spotlight's \"halo\").",
+            "default": "var(--a-space-2)"
+          },
+          "--tour-spotlight-radius": {
+            "description": "Border radius of the spotlight cutout.",
+            "default": "var(--a-radius-md)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "TourStep": {
+      "title": "TourStep",
+      "description": "Single step inside a `<tour-ui>` walkthrough. Declares a target\nelement (via CSS selector), a title, and body content. The host\n`<tour-ui>` reads these declaratively and renders them in the\npopover as the user advances through the tour.\n\n`<tour-step>` itself renders nothing — it's a data carrier (light\nDOM source of truth). The tour-ui orchestrator clones the body\ncontent into the spotlight popover when the step becomes active.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "title": {
+          "description": "Step heading rendered in the popover.",
+          "type": "string",
+          "default": ""
+        },
+        "component": {
+          "const": "TourStep"
+        },
+        "placement": {
+          "description": "Preferred popover placement relative to the target. Same vocabulary\nas `core/anchor.js` (`top`, `bottom`, `left`, `right`,\n`bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow\nvia position-try-fallbacks.\n",
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-start",
+            "top-end",
+            "bottom-start",
+            "bottom-end",
+            "left-start",
+            "left-end",
+            "right-start",
+            "right-end"
+          ],
+          "default": "bottom"
+        },
+        "target": {
+          "description": "CSS selector for the element to spotlight when this step is\nactive. Resolved via `document.querySelector(target)` at step\nactivation time. If the selector matches nothing, the spotlight\nfalls back to viewport-center and the popover anchors to the\npage (no halo cutout).\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<tour-step target=\"#dashboard\">",
+            "why": "target is a CSS selector — bare \"dashboard\" doesn't match.",
+            "wrong": "<tour-step target=\"dashboard\">"
+          }
+        ],
+        "category": "feedback",
+        "composes": [],
+        "events": {},
+        "examples": [],
+        "keywords": [
+          "tour-step",
+          "walkthrough-step",
+          "guided-step"
+        ],
+        "name": "UITourStep",
+        "related": [
+          "tour"
+        ],
+        "slots": {
+          "default": {
+            "description": "Body content rendered inside the step popover (plain text or inline HTML)."
+          }
+        },
+        "states": [],
+        "status": "stable",
+        "synonyms": {
+          "step": [
+            "tour-step",
+            "walkthrough-step"
+          ]
+        },
+        "tag": "tour-step-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
     "Tree": {
       "title": "Tree",
       "description": "Collapsible tree container with keyboard navigation (arrow keys, Enter/Space). Manages selection across nested tree-item-ns.",

package/catalog-a2ui_0_9_rules.txt

@@ -753,6 +753,18 @@
 - Set [delay=0] only for high-frequency exploratory surfaces (sparkline ticks, chart hover). Keep the default 400ms delay elsewhere to avoid hover noise.
 - [indicator] (dot | line | dashed) is meaningful only in pointer mode for per-series swatches. Omit it or leave default "none" for text-mode tooltips.
 
+## TourStep
+- Single step inside <tour-ui>. Declares target (CSS selector) + title + body content.
+- target is a CSS selector (e.g. "#dashboard", ".filters button"), NOT a bare ID. Use the # prefix.
+- Renders nothing on its own — tour-ui orchestrates the popover stamping when the step becomes active.
+
+## Tour
+- Use tour-ui for spotlight-driven product tours / walkthroughs — sequence of steps each targeting a CSS-selector-resolved element.
+- Children are <tour-step target="..." title="..."> with body content as the default slot. tour-ui reads them in DOM order.
+- Set [auto-start] for first-run flows (paired with [storage-key] so it only shows once). Otherwise call .start() programmatically from a "Take the tour" button.
+- Distinct from <onboarding-checklist-ui> (persistent setup todo-list, user-paced) and <tooltip-ui> (single hover hint, no orchestration).
+- Listen to `tour-finish` for "user completed the tour" analytics; `tour-skip` for "user opted out". Both fire once per session.
+
 ## TreeItem
 - <tree-item-ui> MUST be a direct or nested descendant of <tree-ui>. It is not a standalone primitive — outside a <tree-ui> parent, selection / expansion / keyboard nav don't wire.
 - Provide a stable [value] attribute on every <tree-item-ui> that consumers will select. The `tree-select` event's detail.value is the identifier downstream code reads to know which node was picked.