@adia-ai/web-components 0.6.36 → 0.6.37

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 };

package/components/qr-code/qr-code.yaml

@@ -0,0 +1,203 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIQRCode
+tag: qr-code-ui
+status: stable
+component: QRCode
+category: display
+version: 1
+description: |
+  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).
+props:
+  value:
+    description: |
+      The string to encode (URL / text / share link / 2FA seed). When
+      [matrix] is also set, the matrix wins. Empty value + empty matrix
+      renders nothing.
+    type: string
+    default: ""
+    reflect: true
+  matrix:
+    description: |
+      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.
+    type: string
+    default: ""
+    reflect: true
+  size:
+    description: |
+      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`.
+    type: number
+    default: 200
+    reflect: true
+  errorCorrection:
+    description: |
+      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.
+    type: string
+    default: M
+    enum: [L, M, Q, H]
+    reflect: true
+    attribute: error-correction
+  margin:
+    description: |
+      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`.
+    type: number
+    default: 4
+    reflect: true
+  color:
+    description: |
+      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.
+    type: string
+    default: ""
+    reflect: true
+  background:
+    description: |
+      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).
+    type: string
+    default: ""
+    reflect: true
+  label:
+    description: |
+      `aria-label` for the SVG. Defaults to "QR code". Customize for
+      better AT context (e.g. "Share link QR code", "2FA setup QR").
+    type: string
+    default: "QR code"
+    reflect: true
+events: {}
+slots: {}
+states:
+  - name: idle
+    description: Default — QR rendered (or empty if no value/matrix).
+  - name: error
+    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
+traits: []
+tokens:
+  --qr-code-fg:
+    description: Foreground (dark) color when [color] is empty.
+    default: currentColor
+  --qr-code-bg:
+    description: Background (light) color when [background] is empty.
+    default: transparent
+requiredIcons: []
+a2ui:
+  rules:
+    - rule: "Set [value] for URLs / share links / plain text. The built-in encoder covers byte-mode UTF-8 up to QR version 10 (~150 chars at ECC-M, more at lower ECC levels)."
+      reason: "Default mode for the 95% case."
+    - rule: "For data that exceeds version 10, switch to a higher ECC level downgrade ([error-correction=L]) OR use a BYO encoder and pass the precomputed [matrix]."
+      reason: "Encoder capacity contract."
+    - rule: "When QR sits over a non-white surface, set [background] to a solid color. White-on-image QR backgrounds are unreliable for scanners — quiet-zone contrast against the dark cells is the load-bearing visual."
+      reason: "Scannability constraint."
+    - rule: "The [margin] (quiet zone) defaults to 4 cells per QR spec. Smaller margins may scan on some devices but not others; do not go below 2."
+      reason: "Quiet-zone requirement."
+anti_patterns:
+  - wrong: |
+      <qr-code-ui value="https://very.long.url.that.exceeds.150.bytes.of.utf8.encoded.length..."></qr-code-ui>
+    why: |
+      Built-in encoder covers versions 1–10. Data beyond v10 capacity
+      throws + renders empty + sets [data-error]. Console warns with
+      the byte length so consumers can diagnose.
+    fix: |
+      Drop the ECC level (lower L gives more capacity for the same
+      version), OR shorten the URL (use a URL shortener), OR encode
+      with a BYO encoder library + pass the [matrix]:
+      `<qr-code-ui matrix="[[1,0,1,...],...]"></qr-code-ui>`
+  - wrong: |
+      <qr-code-ui value="..." margin="0"></qr-code-ui>
+    why: |
+      Zero margin breaks scanning. QR spec requires a 4-cell quiet
+      zone for reliable detection.
+    fix: |
+      <qr-code-ui value="..." margin="4"></qr-code-ui>
+examples:
+  - name: default
+    description: Plain URL encoding at default size + ECC-M.
+    a2ui: |
+      [
+        {
+          "id": "q",
+          "component": "QRCode",
+          "value": "https://example.com"
+        }
+      ]
+  - name: branded
+    description: Custom colors matching brand chrome.
+    a2ui: |
+      [
+        {
+          "id": "q",
+          "component": "QRCode",
+          "value": "https://adia.health/share/abc123",
+          "size": 280,
+          "color": "#1e293b",
+          "background": "#ffffff",
+          "errorCorrection": "Q"
+        }
+      ]
+  - name: byo-matrix
+    description: BYO precomputed matrix from an external encoder.
+    a2ui: |
+      [
+        {
+          "id": "q",
+          "component": "QRCode",
+          "matrix": "[[1,1,1,1,1,1,1,0,1,...]...]",
+          "size": 200,
+          "label": "Boarding pass QR"
+        }
+      ]
+keywords:
+  - qr-code
+  - qr
+  - barcode
+  - scan
+  - share
+  - 2fa
+  - share-link
+synonyms:
+  qr:
+    - qr-code
+    - barcode
+  scan:
+    - qr-code
+    - barcode
+related:
+  - link
+  - share