@adia-ai/web-components 0.6.35 → 0.6.37

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