@adia-ai/web-components 0.6.35 → 0.6.37

package/components/popover/popover.css

@@ -5,15 +5,11 @@
     --popover-py-default:      var(--a-space-2);
     --popover-radius-default:  var(--a-radius-lg);
 
-    /* ── Colors ── */
+    /* ── Colors (default panel chrome — opt out per `:has(>card-ui)` rule
+       below or by setting tokens to transparent / 0) ── */
     --popover-bg-default:      var(--a-bg-subtle);
     --popover-border-default:  var(--a-border-subtle);
     --popover-shadow-default:  var(--a-shadow-lg);
-    --popover-fg-default:      var(--a-fg);
-
-    /* ── Typography ── */
-    --popover-font-default:    var(--a-font-family);
-    --popover-font-size-default: var(--a-ui-size);
   }
 
   :scope {
@@ -34,25 +30,55 @@
     display: none !important;
   }
 
+  /* ── popover-ui's CSS opinions, narrowly scoped ──
+   *
+   * What's HERE and why:
+   *  • [slot="content"]:not(:popover-open) display:none — required Popover
+   *    API mechanics (closed-state visibility for slotted children).
+   *  • [slot="content"] margin: 0 — reset UA stylesheet's `margin: auto`
+   *    on popover elements (otherwise popover centers in viewport).
+   *  • [slot="content"] box-sizing — universal sanity.
+   *  • Default panel chrome — defensive for the bare-HTML case
+   *    (<div slot="content">Hello</div> needs to be visible against the
+   *    page). Opt out by putting a surface primitive (card-ui / drawer-ui
+   *    / menu-ui) as the only child — they own their own chrome.
+   *  • Light enter/exit animation (opacity + 4px translate) tied to the
+   *    :popover-open state; honors prefers-reduced-motion.
+   *
+   * What's deliberately NOT here:
+   *  • width / max-width / max-height / overflow-y — set by core/anchor.js
+   *    inline during anchoring; those are the anchor module's contract,
+   *    not the shell's.
+   *  • font-family / font-size / color — inherit from the page naturally.
+   *  • Prose first/last-child margin resets — touched consumer DOM.
+   */
   [slot="content"] {
     box-sizing: border-box;
+    /* Reset UA stylesheet's `[popover]` defaults — it sets `margin: auto`
+       (centers in viewport) AND `padding: 0.25em` (~3.75 px at default
+       font-size, leaks into card-ui / drawer-ui consumers and looks like
+       phantom inset between popover edge and inner surface). Both must
+       be zeroed; the chrome rule below re-applies padding only when no
+       surface primitive is in the slot. */
     margin: 0;
+    padding: 0;
+    opacity: 1;
+    translate: 0 0;
+    transition: opacity var(--a-duration-fast) var(--a-easing-out),
+                translate var(--a-duration-fast) var(--a-easing-out);
+  }
+
+  /* Skip chrome when the slot IS a surface primitive itself
+     (`<card-ui slot="content">…`) AND when it CONTAINS one as the only
+     child (`<div slot="content"><card-ui>…</card-ui></div>`). Both
+     shapes appear in consumer code; both should let the inner surface
+     own padding + bg + border + radius + shadow. */
+  [slot="content"]:not(card-ui):not(drawer-ui):not(menu-ui):not(:has(> card-ui:only-child)):not(:has(> drawer-ui:only-child)):not(:has(> menu-ui:only-child)) {
     padding: var(--popover-py, var(--popover-py-default)) var(--popover-px, var(--popover-px-default));
     background: var(--popover-bg, var(--popover-bg-default));
     border: 1px solid var(--popover-border, var(--popover-border-default));
     border-radius: var(--popover-radius, var(--popover-radius-default));
     box-shadow: var(--popover-shadow, var(--popover-shadow-default));
-    font-family: var(--popover-font, var(--popover-font-default));
-    font-size: var(--popover-font-size, var(--popover-font-size-default));
-    color: var(--popover-fg, var(--popover-fg-default));
-    max-height: calc(100vh - 3rem);
-    overflow-y: auto;
-    /* Fade + lift in on first paint. @starting-style is the initial frame
-       browsers paint before the popover transitions to its open state. */
-    opacity: 1;
-    translate: 0 0;
-    transition: opacity var(--a-duration-fast) var(--a-easing-out),
-                translate var(--a-duration-fast) var(--a-easing-out);
   }
 
   [slot="content"]:popover-open {
@@ -65,10 +91,4 @@
   @media (prefers-reduced-motion: reduce) {
     [slot="content"] { transition: none; }
   }
-
-  /* Collapse default margins on the first/last block child so the
-     content sits snug inside --popover-py (no phantom extra space
-     below <p>, <h*>, etc.). */
-  [slot="content"] > :first-child { margin-block-start: 0; }
-  [slot="content"] > :last-child  { margin-block-end:   0; }
 }

package/components/popover/popover.yaml

@@ -76,10 +76,14 @@ a2ui:
       everything else (inline forms, color pickers, theme panels,
       export menus with non-action content).
     - >-
-      Use [placement="bottom-end"] for topbar overflow / settings
-      buttons; [placement="bottom-start"] for inline form fields;
-      top-* variants when trigger sits low in the viewport
-      (statusbar). [gap] (default 4px) controls offset from anchor.
+      Placement convention (ADR-0034): default `bottom` centers under
+      the trigger — correct for wide pickers (calendar, color,
+      date-range, filter forms). Use `bottom-start` for trigger-width
+      menus (action lists, listboxes, breadcrumb overflow — popover
+      width ≈ trigger width). Use `bottom-end` only when the trigger
+      sits at the right edge of a container by construction (toolbar
+      spillover). Use `top-*` when the trigger sits low in the
+      viewport (statusbar). [gap] (default 4px) sets offset from anchor.
     - >-
       [trigger="hover"] is for non-essential disclosure only — never
       use it for popovers containing inputs, destructive actions, or

package/components/qr-code/QR-TEST.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 330 330" width="330" height="330" shape-rendering="crispEdges">
+  <rect width="100%" height="100%" fill="#fff"/>
+  <g fill="#000"><rect x="40" y="40" width="10" height="10"/><rect x="50" y="40" width="10" height="10"/><rect x="60" y="40" width="10" height="10"/><rect x="70" y="40" width="10" height="10"/><rect x="80" y="40" width="10" height="10"/><rect x="90" y="40" width="10" height="10"/><rect x="100" y="40" width="10" height="10"/><rect x="120" y="40" width="10" height="10"/><rect x="150" y="40" width="10" height="10"/><rect x="170" y="40" width="10" height="10"/><rect x="180" y="40" width="10" height="10"/><rect x="190" y="40" width="10" height="10"/><rect x="220" y="40" width="10" height="10"/><rect x="230" y="40" width="10" height="10"/><rect x="240" y="40" width="10" height="10"/><rect x="250" y="40" width="10" height="10"/><rect x="260" y="40" width="10" height="10"/><rect x="270" y="40" width="10" height="10"/><rect x="280" y="40" width="10" height="10"/><rect x="40" y="50" width="10" height="10"/><rect x="100" y="50" width="10" height="10"/><rect x="190" y="50" width="10" height="10"/><rect x="220" y="50" width="10" height="10"/><rect x="280" y="50" width="10" height="10"/><rect x="40" y="60" width="10" height="10"/><rect x="60" y="60" width="10" height="10"/><rect x="70" y="60" width="10" height="10"/><rect x="80" y="60" width="10" height="10"/><rect x="100" y="60" width="10" height="10"/><rect x="120" y="60" width="10" height="10"/><rect x="140" y="60" width="10" height="10"/><rect x="160" y="60" width="10" height="10"/><rect x="170" y="60" width="10" height="10"/><rect x="220" y="60" width="10" height="10"/><rect x="240" y="60" width="10" height="10"/><rect x="250" y="60" width="10" height="10"/><rect x="260" y="60" width="10" height="10"/><rect x="280" y="60" width="10" height="10"/><rect x="40" y="70" width="10" height="10"/><rect x="60" y="70" width="10" height="10"/><rect x="70" y="70" width="10" height="10"/><rect x="80" y="70" width="10" height="10"/><rect x="100" y="70" width="10" height="10"/><rect x="130" y="70" width="10" height="10"/><rect x="150" y="70" width="10" height="10"/><rect x="160" y="70" width="10" height="10"/><rect x="190" y="70" width="10" height="10"/><rect x="220" y="70" width="10" height="10"/><rect x="240" y="70" width="10" height="10"/><rect x="250" y="70" width="10" height="10"/><rect x="260" y="70" width="10" height="10"/><rect x="280" y="70" width="10" height="10"/><rect x="40" y="80" width="10" height="10"/><rect x="60" y="80" width="10" height="10"/><rect x="70" y="80" width="10" height="10"/><rect x="80" y="80" width="10" height="10"/><rect x="100" y="80" width="10" height="10"/><rect x="130" y="80" width="10" height="10"/><rect x="190" y="80" width="10" height="10"/><rect x="200" y="80" width="10" height="10"/><rect x="220" y="80" width="10" height="10"/><rect x="240" y="80" width="10" height="10"/><rect x="250" y="80" width="10" height="10"/><rect x="260" y="80" width="10" height="10"/><rect x="280" y="80" width="10" height="10"/><rect x="40" y="90" width="10" height="10"/><rect x="100" y="90" width="10" height="10"/><rect x="120" y="90" width="10" height="10"/><rect x="160" y="90" width="10" height="10"/><rect x="170" y="90" width="10" height="10"/><rect x="180" y="90" width="10" height="10"/><rect x="220" y="90" width="10" height="10"/><rect x="280" y="90" width="10" height="10"/><rect x="40" y="100" width="10" height="10"/><rect x="50" y="100" width="10" height="10"/><rect x="60" y="100" width="10" height="10"/><rect x="70" y="100" width="10" height="10"/><rect x="80" y="100" width="10" height="10"/><rect x="90" y="100" width="10" height="10"/><rect x="100" y="100" width="10" height="10"/><rect x="120" y="100" width="10" height="10"/><rect x="140" y="100" width="10" height="10"/><rect x="160" y="100" width="10" height="10"/><rect x="180" y="100" width="10" height="10"/><rect x="200" y="100" width="10" height="10"/><rect x="220" y="100" width="10" height="10"/><rect x="230" y="100" width="10" height="10"/><rect x="240" y="100" width="10" height="10"/><rect x="250" y="100" width="10" height="10"/><rect x="260" y="100" width="10" height="10"/><rect x="270" y="100" width="10" height="10"/><rect x="280" y="100" width="10" height="10"/><rect x="160" y="110" width="10" height="10"/><rect x="170" y="110" width="10" height="10"/><rect x="190" y="110" width="10" height="10"/><rect x="200" y="110" width="10" height="10"/><rect x="40" y="120" width="10" height="10"/><rect x="60" y="120" width="10" height="10"/><rect x="100" y="120" width="10" height="10"/><rect x="110" y="120" width="10" height="10"/><rect x="130" y="120" width="10" height="10"/><rect x="140" y="120" width="10" height="10"/><rect x="150" y="120" width="10" height="10"/><rect x="160" y="120" width="10" height="10"/><rect x="170" y="120" width="10" height="10"/><rect x="190" y="120" width="10" height="10"/><rect x="230" y="120" width="10" height="10"/><rect x="260" y="120" width="10" height="10"/><rect x="280" y="120" width="10" height="10"/><rect x="40" y="130" width="10" height="10"/><rect x="50" y="130" width="10" height="10"/><rect x="60" y="130" width="10" height="10"/><rect x="70" y="130" width="10" height="10"/><rect x="130" y="130" width="10" height="10"/><rect x="150" y="130" width="10" height="10"/><rect x="160" y="130" width="10" height="10"/><rect x="190" y="130" width="10" height="10"/><rect x="200" y="130" width="10" height="10"/><rect x="220" y="130" width="10" height="10"/><rect x="230" y="130" width="10" height="10"/><rect x="250" y="130" width="10" height="10"/><rect x="270" y="130" width="10" height="10"/><rect x="280" y="130" width="10" height="10"/><rect x="60" y="140" width="10" height="10"/><rect x="70" y="140" width="10" height="10"/><rect x="80" y="140" width="10" height="10"/><rect x="100" y="140" width="10" height="10"/><rect x="110" y="140" width="10" height="10"/><rect x="130" y="140" width="10" height="10"/><rect x="140" y="140" width="10" height="10"/><rect x="170" y="140" width="10" height="10"/><rect x="180" y="140" width="10" height="10"/><rect x="190" y="140" width="10" height="10"/><rect x="220" y="140" width="10" height="10"/><rect x="240" y="140" width="10" height="10"/><rect x="250" y="140" width="10" height="10"/><rect x="260" y="140" width="10" height="10"/><rect x="280" y="140" width="10" height="10"/><rect x="70" y="150" width="10" height="10"/><rect x="80" y="150" width="10" height="10"/><rect x="110" y="150" width="10" height="10"/><rect x="160" y="150" width="10" height="10"/><rect x="180" y="150" width="10" height="10"/><rect x="200" y="150" width="10" height="10"/><rect x="250" y="150" width="10" height="10"/><rect x="40" y="160" width="10" height="10"/><rect x="70" y="160" width="10" height="10"/><rect x="90" y="160" width="10" height="10"/><rect x="100" y="160" width="10" height="10"/><rect x="130" y="160" width="10" height="10"/><rect x="150" y="160" width="10" height="10"/><rect x="170" y="160" width="10" height="10"/><rect x="180" y="160" width="10" height="10"/><rect x="190" y="160" width="10" height="10"/><rect x="200" y="160" width="10" height="10"/><rect x="220" y="160" width="10" height="10"/><rect x="230" y="160" width="10" height="10"/><rect x="280" y="160" width="10" height="10"/><rect x="70" y="170" width="10" height="10"/><rect x="80" y="170" width="10" height="10"/><rect x="90" y="170" width="10" height="10"/><rect x="110" y="170" width="10" height="10"/><rect x="120" y="170" width="10" height="10"/><rect x="170" y="170" width="10" height="10"/><rect x="180" y="170" width="10" height="10"/><rect x="190" y="170" width="10" height="10"/><rect x="200" y="170" width="10" height="10"/><rect x="220" y="170" width="10" height="10"/><rect x="230" y="170" width="10" height="10"/><rect x="270" y="170" width="10" height="10"/><rect x="280" y="170" width="10" height="10"/><rect x="40" y="180" width="10" height="10"/><rect x="50" y="180" width="10" height="10"/><rect x="60" y="180" width="10" height="10"/><rect x="90" y="180" width="10" height="10"/><rect x="100" y="180" width="10" height="10"/><rect x="110" y="180" width="10" height="10"/><rect x="130" y="180" width="10" height="10"/><rect x="150" y="180" width="10" height="10"/><rect x="190" y="180" width="10" height="10"/><rect x="200" y="180" width="10" height="10"/><rect x="210" y="180" width="10" height="10"/><rect x="250" y="180" width="10" height="10"/><rect x="260" y="180" width="10" height="10"/><rect x="280" y="180" width="10" height="10"/><rect x="60" y="190" width="10" height="10"/><rect x="80" y="190" width="10" height="10"/><rect x="90" y="190" width="10" height="10"/><rect x="120" y="190" width="10" height="10"/><rect x="130" y="190" width="10" height="10"/><rect x="140" y="190" width="10" height="10"/><rect x="170" y="190" width="10" height="10"/><rect x="200" y="190" width="10" height="10"/><rect x="210" y="190" width="10" height="10"/><rect x="230" y="190" width="10" height="10"/><rect x="240" y="190" width="10" height="10"/><rect x="250" y="190" width="10" height="10"/><rect x="40" y="200" width="10" height="10"/><rect x="50" y="200" width="10" height="10"/><rect x="70" y="200" width="10" height="10"/><rect x="90" y="200" width="10" height="10"/><rect x="100" y="200" width="10" height="10"/><rect x="110" y="200" width="10" height="10"/><rect x="120" y="200" width="10" height="10"/><rect x="150" y="200" width="10" height="10"/><rect x="160" y="200" width="10" height="10"/><rect x="170" y="200" width="10" height="10"/><rect x="190" y="200" width="10" height="10"/><rect x="200" y="200" width="10" height="10"/><rect x="210" y="200" width="10" height="10"/><rect x="220" y="200" width="10" height="10"/><rect x="230" y="200" width="10" height="10"/><rect x="240" y="200" width="10" height="10"/><rect x="270" y="200" width="10" height="10"/><rect x="120" y="210" width="10" height="10"/><rect x="130" y="210" width="10" height="10"/><rect x="140" y="210" width="10" height="10"/><rect x="160" y="210" width="10" height="10"/><rect x="200" y="210" width="10" height="10"/><rect x="240" y="210" width="10" height="10"/><rect x="280" y="210" width="10" height="10"/><rect x="40" y="220" width="10" height="10"/><rect x="50" y="220" width="10" height="10"/><rect x="60" y="220" width="10" height="10"/><rect x="70" y="220" width="10" height="10"/><rect x="80" y="220" width="10" height="10"/><rect x="90" y="220" width="10" height="10"/><rect x="100" y="220" width="10" height="10"/><rect x="120" y="220" width="10" height="10"/><rect x="160" y="220" width="10" height="10"/><rect x="170" y="220" width="10" height="10"/><rect x="180" y="220" width="10" height="10"/><rect x="200" y="220" width="10" height="10"/><rect x="220" y="220" width="10" height="10"/><rect x="240" y="220" width="10" height="10"/><rect x="280" y="220" width="10" height="10"/><rect x="40" y="230" width="10" height="10"/><rect x="100" y="230" width="10" height="10"/><rect x="130" y="230" width="10" height="10"/><rect x="140" y="230" width="10" height="10"/><rect x="150" y="230" width="10" height="10"/><rect x="160" y="230" width="10" height="10"/><rect x="180" y="230" width="10" height="10"/><rect x="190" y="230" width="10" height="10"/><rect x="200" y="230" width="10" height="10"/><rect x="240" y="230" width="10" height="10"/><rect x="40" y="240" width="10" height="10"/><rect x="60" y="240" width="10" height="10"/><rect x="70" y="240" width="10" height="10"/><rect x="80" y="240" width="10" height="10"/><rect x="100" y="240" width="10" height="10"/><rect x="130" y="240" width="10" height="10"/><rect x="170" y="240" width="10" height="10"/><rect x="180" y="240" width="10" height="10"/><rect x="190" y="240" width="10" height="10"/><rect x="200" y="240" width="10" height="10"/><rect x="210" y="240" width="10" height="10"/><rect x="220" y="240" width="10" height="10"/><rect x="230" y="240" width="10" height="10"/><rect x="240" y="240" width="10" height="10"/><rect x="270" y="240" width="10" height="10"/><rect x="280" y="240" width="10" height="10"/><rect x="40" y="250" width="10" height="10"/><rect x="60" y="250" width="10" height="10"/><rect x="70" y="250" width="10" height="10"/><rect x="80" y="250" width="10" height="10"/><rect x="100" y="250" width="10" height="10"/><rect x="140" y="250" width="10" height="10"/><rect x="170" y="250" width="10" height="10"/><rect x="180" y="250" width="10" height="10"/><rect x="200" y="250" width="10" height="10"/><rect x="210" y="250" width="10" height="10"/><rect x="240" y="250" width="10" height="10"/><rect x="260" y="250" width="10" height="10"/><rect x="270" y="250" width="10" height="10"/><rect x="40" y="260" width="10" height="10"/><rect x="60" y="260" width="10" height="10"/><rect x="70" y="260" width="10" height="10"/><rect x="80" y="260" width="10" height="10"/><rect x="100" y="260" width="10" height="10"/><rect x="120" y="260" width="10" height="10"/><rect x="150" y="260" width="10" height="10"/><rect x="210" y="260" width="10" height="10"/><rect x="230" y="260" width="10" height="10"/><rect x="240" y="260" width="10" height="10"/><rect x="250" y="260" width="10" height="10"/><rect x="270" y="260" width="10" height="10"/><rect x="280" y="260" width="10" height="10"/><rect x="40" y="270" width="10" height="10"/><rect x="100" y="270" width="10" height="10"/><rect x="130" y="270" width="10" height="10"/><rect x="170" y="270" width="10" height="10"/><rect x="200" y="270" width="10" height="10"/><rect x="230" y="270" width="10" height="10"/><rect x="240" y="270" width="10" height="10"/><rect x="40" y="280" width="10" height="10"/><rect x="50" y="280" width="10" height="10"/><rect x="60" y="280" width="10" height="10"/><rect x="70" y="280" width="10" height="10"/><rect x="80" y="280" width="10" height="10"/><rect x="90" y="280" width="10" height="10"/><rect x="100" y="280" width="10" height="10"/><rect x="120" y="280" width="10" height="10"/><rect x="130" y="280" width="10" height="10"/><rect x="150" y="280" width="10" height="10"/><rect x="160" y="280" width="10" height="10"/><rect x="170" y="280" width="10" height="10"/><rect x="190" y="280" width="10" height="10"/><rect x="200" y="280" width="10" height="10"/><rect x="220" y="280" width="10" height="10"/><rect x="250" y="280" width="10" height="10"/><rect x="280" y="280" width="10" height="10"/></g>
+</svg>

package/components/qr-code/qr-code.a2ui.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/QRCode.json",
+  "title": "QRCode",
+  "description": "Inline QR code generator — renders a scannable code as inline SVG.\nTwo modes:\n\n**A. Auto-encode (default).** Set `[value]` to a string (URL, plain\ntext, share link, 2FA secret). The component encodes the data with\nthe built-in zero-deps QR encoder (byte mode, ECC level configurable,\nversions 1–10 up to ~150 byte chars) and renders an SVG.\n\n**B. Bring-your-own matrix.** Set `[matrix]` to a JSON string of a\n2-D 0/1 array (`[[1,0,1,...],[...],...]`). The component renders the\nsupplied matrix directly without invoking its own encoder. Use this\nwhen you need versions 11–40, kanji/alphanumeric mode, or any\nencoder feature beyond the built-in. When both `[value]` and\n`[matrix]` are set, the matrix wins (BYO override).\n\nOutput is a single `<svg>` with `viewBox=\"0 0 N N\"`. Crisp-edges\nrendering preserves the scannable cell boundaries at any size.\nSizing is controlled by the `[size]` prop (host CSS-pixel dimension);\ninternal cell size is computed from `size / (matrix-size + 2 ·\nmargin)`. ARIA: `role=\"img\"` with `aria-label` (default \"QR code\"\nor the `[label]` prop).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "background": {
+      "description": "Background (light-cell) color. **Empty defaults to `#ffffff` —\nhardcoded white** alongside the black foreground, for guaranteed\nscanability. Override only when paired with an explicit\n[color] (the contrast pair must scan).\n",
+      "type": "string",
+      "default": ""
+    },
+    "color": {
+      "description": "Foreground (dark-cell) color. Any CSS color string (hex, rgb,\ntoken reference). **Empty defaults to `#000000` — hardcoded black\nfor guaranteed scanability** (theme-aware `currentColor` would\nproduce light-on-dark in dark mode, which most phone scanners\nrefuse to decode). Override for branded QRs only when you've\nverified the chosen color/background pair scans on the target\ndevices.\n",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "QRCode"
+    },
+    "errorCorrection": {
+      "description": "Error-correction level (auto-encode mode only). `L` (7% recovery),\n`M` (15%, default), `Q` (25%), `H` (30%). Higher levels recover\nfrom more damage at the cost of QR-version size growth.\n",
+      "type": "string",
+      "enum": [
+        "L",
+        "M",
+        "Q",
+        "H"
+      ],
+      "default": "M"
+    },
+    "label": {
+      "description": "`aria-label` for the SVG. Defaults to \"QR code\". Customize for\nbetter AT context (e.g. \"Share link QR code\", \"2FA setup QR\").\n",
+      "type": "string",
+      "default": "QR code"
+    },
+    "margin": {
+      "description": "Quiet zone in cells around the QR pattern. QR spec requires a\nminimum 4-cell margin for reliable scanning; smaller values may\nnot scan on some devices. Default `4`.\n",
+      "type": "number",
+      "default": 4
+    },
+    "matrix": {
+      "description": "BYO precomputed bit matrix as JSON — a 2-D array of 0/1\n(`[[1,0,...],[0,1,...],...]`). When set, the built-in encoder is\nbypassed and this matrix renders directly. Useful for QR variants\nthe built-in doesn't support (versions 11–40, alphanumeric mode,\nkanji, etc.) — bring your own encoder, pass the matrix here.\n",
+      "type": "string",
+      "default": ""
+    },
+    "size": {
+      "description": "Host display size in CSS pixels (width and height; the SVG is\nalways square). Default 200. Internal cell size is computed from\nthis divided by `matrix-size + 2·margin`.\n",
+      "type": "number",
+      "default": 200
+    },
+    "value": {
+      "description": "The string to encode (URL / text / share link / 2FA seed). When\n[matrix] is also set, the matrix wins. Empty value + empty matrix\nrenders nothing.\n",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "Drop the ECC level (lower L gives more capacity for the same\nversion), OR shorten the URL (use a URL shortener), OR encode\nwith a BYO encoder library + pass the [matrix]:\n`<qr-code-ui matrix=\"[[1,0,1,...],...]\"></qr-code-ui>`\n",
+        "why": "Built-in encoder covers versions 1–10. Data beyond v10 capacity\nthrows + renders empty + sets [data-error]. Console warns with\nthe byte length so consumers can diagnose.\n",
+        "wrong": "<qr-code-ui value=\"https://very.long.url.that.exceeds.150.bytes.of.utf8.encoded.length...\"></qr-code-ui>\n"
+      },
+      {
+        "fix": "<qr-code-ui value=\"...\" margin=\"4\"></qr-code-ui>\n",
+        "why": "Zero margin breaks scanning. QR spec requires a 4-cell quiet\nzone for reliable detection.\n",
+        "wrong": "<qr-code-ui value=\"...\" margin=\"0\"></qr-code-ui>\n"
+      }
+    ],
+    "category": "display",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Plain URL encoding at default size + ECC-M.",
+        "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"value\": \"https://example.com\"\n  }\n]\n",
+        "name": "default"
+      },
+      {
+        "description": "Custom colors matching brand chrome.",
+        "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"value\": \"https://adia.health/share/abc123\",\n    \"size\": 280,\n    \"color\": \"#1e293b\",\n    \"background\": \"#ffffff\",\n    \"errorCorrection\": \"Q\"\n  }\n]\n",
+        "name": "branded"
+      },
+      {
+        "description": "BYO precomputed matrix from an external encoder.",
+        "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"matrix\": \"[[1,1,1,1,1,1,1,0,1,...]...]\",\n    \"size\": 200,\n    \"label\": \"Boarding pass QR\"\n  }\n]\n",
+        "name": "byo-matrix"
+      }
+    ],
+    "keywords": [
+      "qr-code",
+      "qr",
+      "barcode",
+      "scan",
+      "share",
+      "2fa",
+      "share-link"
+    ],
+    "name": "UIQRCode",
+    "related": [
+      "link",
+      "share"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default — QR rendered (or empty if no value/matrix).",
+        "name": "idle"
+      },
+      {
+        "description": "Auto-encode failed (data too long for v1–10 at requested ECC). Renders an empty placeholder; logs a console warning. Switch to a BYO matrix from an external encoder, or downgrade the ECC level.",
+        "attribute": "data-error",
+        "name": "error"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "qr": [
+        "qr-code",
+        "barcode"
+      ],
+      "scan": [
+        "qr-code",
+        "barcode"
+      ]
+    },
+    "tag": "qr-code-ui",
+    "tokens": {
+      "--qr-code-bg": {
+        "description": "Background (light) color when [background] is empty.",
+        "default": "transparent"
+      },
+      "--qr-code-fg": {
+        "description": "Foreground (dark) color when [color] is empty.",
+        "default": "currentColor"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/qr-code/qr-code.class.js

@@ -0,0 +1,129 @@
+/**
+ * Non-side-effect class export for `<qr-code-ui>`.
+ *
+ * Importing this file gives you the class 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/qr-code`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <qr-code-ui value="https://example.com" size="200"></qr-code-ui>
+ *
+ * Two modes:
+ *   A. Auto-encode (default) — set `[value]`, built-in encoder runs.
+ *   B. BYO matrix — set `[matrix]` (JSON 2-D 0/1 array), bypass the encoder.
+ *
+ * Matrix wins when both are set. Empty value + empty matrix renders
+ * nothing.
+ *
+ * @see ./qr-encoder.js for the encoder implementation.
+ */
+
+import { UIElement } from '../../core/element.js';
+import { encodeQR, matrixToSVG } from './qr-encoder.js';
+
+export class UIQRCode extends UIElement {
+  static properties = {
+    value:           { type: String, default: '',       reflect: true },
+    matrix:          { type: String, default: '',       reflect: true },
+    size:            { type: Number, default: 200,      reflect: true },
+    errorCorrection: { type: String, default: 'M',      reflect: true, attribute: 'error-correction' },
+    margin:          { type: Number, default: 4,        reflect: true },
+    color:           { type: String, default: '',       reflect: true },
+    background:      { type: String, default: '',       reflect: true },
+    label:           { type: String, default: 'QR code', reflect: true },
+  };
+
+  static template = () => null;
+
+  #lastSig = '';
+
+  #parseMatrix(raw) {
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed) || parsed.length === 0) return null;
+      if (!Array.isArray(parsed[0])) return null;
+      // Coerce to 0/1
+      return parsed.map((row) => row.map((v) => (v ? 1 : 0)));
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn('[qr-code-ui] invalid [matrix] JSON:', e.message);
+      return null;
+    }
+  }
+
+  #resolveMatrix() {
+    // BYO matrix wins
+    const byo = this.#parseMatrix(this.matrix);
+    if (byo) {
+      this.removeAttribute('data-error');
+      return byo;
+    }
+    if (!this.value) {
+      this.removeAttribute('data-error');
+      return null;
+    }
+    try {
+      const result = encodeQR(this.value, { errorCorrection: this.errorCorrection || 'M' });
+      this.removeAttribute('data-error');
+      return result.matrix;
+    } catch (e) {
+      this.setAttribute('data-error', '');
+      // eslint-disable-next-line no-console
+      console.warn(`[qr-code-ui] encode failed for value (${this.value?.length || 0} chars at ECC=${this.errorCorrection}): ${e.message}. Lower ECC, shorten input, or supply a precomputed [matrix].`);
+      return null;
+    }
+  }
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'img');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', this.label || 'QR code');
+  }
+
+  render() {
+    // Cheap idempotence: compute a signature of inputs, skip re-render
+    // if nothing changed (encoding is non-trivial — version selection +
+    // RS ECC + 8 mask evaluations).
+    const sig = `${this.value}|${this.matrix}|${this.size}|${this.errorCorrection}|${this.margin}|${this.color}|${this.background}`;
+    if (sig === this.#lastSig && this.querySelector('svg')) return;
+    this.#lastSig = sig;
+
+    // Keep aria-label fresh from prop
+    if (this.label) this.setAttribute('aria-label', this.label);
+
+    const matrix = this.#resolveMatrix();
+    if (!matrix) {
+      this.innerHTML = '';
+      return;
+    }
+
+    const svg = matrixToSVG(matrix, {
+      cellSize: 8, // arbitrary internal unit; host CSS controls actual size via [size]
+      margin: Number.isFinite(this.margin) ? this.margin : 4,
+      // Hardcoded fallback to black-on-white — the scannable convention.
+      // Theme-aware `currentColor` produces light-on-dark in dark mode,
+      // which most phone cameras (iPhone Camera in particular) refuse to
+      // decode. Consumers wanting brand chrome must set [color] +
+      // [background] explicitly; the bare default ALWAYS scans.
+      color: this.color || '#000000',
+      background: this.background || '#ffffff',
+    });
+    this.innerHTML = svg;
+
+    // Lock the visual size on the SVG root (CSS host dims would also
+    // work, but explicit width/height on the SVG keeps the box clear
+    // when the host is laid out as inline content).
+    const svgEl = this.querySelector('svg');
+    if (svgEl && Number.isFinite(this.size)) {
+      svgEl.setAttribute('width', String(this.size));
+      svgEl.setAttribute('height', String(this.size));
+    }
+  }
+}

package/components/qr-code/qr-code.css

@@ -0,0 +1,41 @@
+/* ═══════════════════════════════════════════════════════════════
+   QR-CODE-UI — Inline scannable QR code.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (qr-code-ui) {
+  :where(:scope) {
+    --qr-code-fg-default: currentColor;
+    --qr-code-bg-default: transparent;
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: inline-block;
+    /* The SVG itself carries explicit width/height; this is a fallback
+       for cases where the SVG hasn't stamped yet (empty value/matrix). */
+    line-height: 0;
+    color: var(--qr-code-fg, var(--qr-code-fg-default));
+    background: var(--qr-code-bg, var(--qr-code-bg-default));
+  }
+
+  :scope svg {
+    display: block;
+    /* Width / height come from the explicit SVG attributes set by JS
+       per the [size] prop. CSS `width: 100%` would stretch to fill the
+       host, but the host is inline-block sized-to-content (the SVG
+       itself), which produces a circular sizing dependency in some
+       browsers + zero-height in others. Trust the SVG attributes. */
+    shape-rendering: crispEdges;
+  }
+
+  /* Encode-error state — caller passed data too long for v1-10 at
+     the configured ECC. Render an empty placeholder; the warning
+     went to console. Visually: a dashed outline at the requested
+     size so the layout doesn't collapse silently. */
+  :scope[data-error] {
+    border: 1px dashed var(--a-border-strong);
+    border-radius: var(--a-radius-sm);
+    min-width: 4em;
+    min-height: 4em;
+  }
+}

package/components/qr-code/qr-code.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `<qr-code-ui>` — Inline QR code generator — renders a scannable code as inline SVG.
+Two modes:
+
+**A. Auto-encode (default).** Set `[value]` to a string (URL, plain
+text, share link, 2FA secret). The component encodes the data with
+the built-in zero-deps QR encoder (byte mode, ECC level configurable,
+versions 1–10 up to ~150 byte chars) and renders an SVG.
+
+**B. Bring-your-own matrix.** Set `[matrix]` to a JSON string of a
+2-D 0/1 array (`[[1,0,1,...],[...],...]`). The component renders the
+supplied matrix directly without invoking its own encoder. Use this
+when you need versions 11–40, kanji/alphanumeric mode, or any
+encoder feature beyond the built-in. When both `[value]` and
+`[matrix]` are set, the matrix wins (BYO override).
+
+Output is a single `<svg>` with `viewBox="0 0 N N"`. Crisp-edges
+rendering preserves the scannable cell boundaries at any size.
+Sizing is controlled by the `[size]` prop (host CSS-pixel dimension);
+internal cell size is computed from `size / (matrix-size + 2 ·
+margin)`. ARIA: `role="img"` with `aria-label` (default "QR code"
+or the `[label]` prop).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/qr-code
+ *
+ * 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 class UIQRCode extends UIElement {
+  /** Background (light-cell) color. **Empty defaults to `#ffffff` —
+hardcoded white** alongside the black foreground, for guaranteed
+scanability. Override only when paired with an explicit
+[color] (the contrast pair must scan).
+ */
+  background: string;
+  /** Foreground (dark-cell) color. Any CSS color string (hex, rgb,
+token reference). **Empty defaults to `#000000` — hardcoded black
+for guaranteed scanability** (theme-aware `currentColor` would
+produce light-on-dark in dark mode, which most phone scanners
+refuse to decode). Override for branded QRs only when you've
+verified the chosen color/background pair scans on the target
+devices.
+ */
+  color: string;
+  /** Error-correction level (auto-encode mode only). `L` (7% recovery),
+`M` (15%, default), `Q` (25%), `H` (30%). Higher levels recover
+from more damage at the cost of QR-version size growth.
+ */
+  errorCorrection: 'L' | 'M' | 'Q' | 'H';
+  /** `aria-label` for the SVG. Defaults to "QR code". Customize for
+better AT context (e.g. "Share link QR code", "2FA setup QR").
+ */
+  label: string;
+  /** Quiet zone in cells around the QR pattern. QR spec requires a
+minimum 4-cell margin for reliable scanning; smaller values may
+not scan on some devices. Default `4`.
+ */
+  margin: number;
+  /** BYO precomputed bit matrix as JSON — a 2-D array of 0/1
+(`[[1,0,...],[0,1,...],...]`). When set, the built-in encoder is
+bypassed and this matrix renders directly. Useful for QR variants
+the built-in doesn't support (versions 11–40, alphanumeric mode,
+kanji, etc.) — bring your own encoder, pass the matrix here.
+ */
+  matrix: string;
+  /** Host display size in CSS pixels (width and height; the SVG is
+always square). Default 200. Internal cell size is computed from
+this divided by `matrix-size + 2·margin`.
+ */
+  size: number;
+  /** The string to encode (URL / text / share link / 2FA seed). When
+[matrix] is also set, the matrix wins. Empty value + empty matrix
+renders nothing.
+ */
+  value: string;
+}

package/components/qr-code/qr-code.js

@@ -0,0 +1,17 @@
+/**
+ * `<qr-code-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIQRCode } from '@adia-ai/web-components/components/qr-code/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIQRCode } from './qr-code.class.js';
+
+defineIfFree('qr-code-ui', UIQRCode);
+
+export { UIQRCode };