# QrCode

Themeable, accessible QR code — **own zero-dependency encoder**, framework
4-layer rigor, richer than the references it learns from.

> **Design proposal** (approved 2026-06-12). This README is both the design
> record and the component doc.

## Baseline

No Air baseline — new component (2026-06-12). Nothing in the legacy layers
rendered QR codes; the encoder itself is also new (`$libs/qr`, zero-dep).

## Talla y tema

**10 clave(s) pública(s)** en `lib/recipes/base.ts` (bloque `qr-code`), con sus pasos por talla y el nombre RESUELTO que consume la receta.
Es el contrato vivo: la pestaña **Tokens** de su demo lista estas mismas
claves y las resuelve sobre el escenario.

| Token (`--qr-code-…`) | Valor por defecto  |
| --------------------- | ------------------ |
| `fg`                  | `#18181b`          |
| `bg`                  | `#ffffff`          |
| `size-xs`             | `96px`             |
| `size-sm`             | `128px`            |
| `size-md`             | `160px`            |
| `size-lg`             | `200px`            |
| `size-xl`             | `256px`            |
| `radius`              | `var(--radius-md)` |
| `overlay-bg`          | `#ffffff`          |
| `overlay-radius`      | `var(--radius-sm)` |

**Lo que el guard R-5.4 da por silencioso, con su razón medida**
(`scripts/theming-sentinel-exceptions.ts`):

- `size-xs` — one step per instance: the wrapper writes var(--qr-code-size-{k}) inline from the size prop and the demo runs lg. Forced -> reaches (96px -> 123px)
- `size-sm` — same, one step per instance
- `size-md` — same, one step per instance
- `size-xl` — same, one step per instance
- `fg` — painted as the SVG fill of the module path, not as color on the root; read on the path -> reaches (rgb(24,24,27) -> rgb(1,2,3))

## Comparativa — why a new one (vs the references)

| Capability | ark-ui (zag + `uqr`) | qr-code-styling | react-qr-code | **QrCode (ours)** |
| --- | --- | --- | --- | --- |
| Parts / anatomy | ✅ Root·Frame·Pattern·Overlay·Download | ❌ imperative | ❌ single comp | ✅ |
| Encoder | `uqr` dep | qr-code-generator dep | qr.js dep | **own, zero-dep (`$libs/qr`)** |
| Error correction L/M/Q/H | ✅ | ✅ | ✅ | ✅ |
| Themeable colour (tokens) | ❌ `currentColor` only | ✅ free | fg/bg props | ✅ **via tokens + `color`** |
| Cell shapes (square/rounded/dots) | ❌ | ✅ | ❌ | ✅ |
| Logo overlay | ✅ | ✅ | partial | ✅ **+ auto quiet-zone + auto-boost ECC** |
| Download PNG/SVG | ✅ | ✅ | manual | ✅ **DownloadTrigger = `<Button>`** |
| `role=img` + label a11y | partial | ❌ | ❌ | ✅ |
| Framework morfo/recipe rigor | n/a | n/a | n/a | ✅ |

**Takeaway:** ark has the best *structure* but is visually flat and pulls an
encoder dependency; qr-code-styling is visually rich but imperative, dependency-
heavy, no a11y. Ours keeps ark's clean anatomy + API, owns the encoder (the QR
algorithm is the open ISO/IEC 18004 standard — no npm dep), and adds themeable
colour, cell shapes, a scannable logo overlay and real a11y.

## Encoder — `$libs/qr` (own, zero-dep)

`encode(value, { errorCorrection, minVersion?, maxVersion? }) → { matrix:
boolean[][], reserved: boolean[][], size, version, errorCorrection }`. A
from-scratch QR encoder (segment analysis → Reed-Solomon ECC over GF(256) →
matrix layout → mask selection over all 8 masks by penalty), pure and
zero-dependency, living in `$libs` alongside the other pure helpers. The
algorithm follows the public QR standard; `uqr`/nayuki are correctness
references only, never imported. Unit-tested against known vectors + structural
invariants; the demo harness round-trips encode→decode through `jsQR`
(versions 1–24, all ECC, all modes, all four cell shapes).

`reserved[y][x]` marks the **function modules** (finders, timing, alignment,
format/version info) — the eidos layer keeps those square even when
`cellShape` is `rounded`/`dots`, so the scanner's grid-lock pattern stays
intact and every shape remains scannable. Only the data modules take the
decorative shape.

## Scannability (verified)

- **Function patterns stay square** for all cell shapes (`reserved` mask) — what
  `qr-code-styling` does, and the reason rounded/dots still decode.
- **Logo** auto-boosts ECC to `H` and clears a central ~24% region so the lost
  modules fall within the error-correction budget.
- **Fixed-tone default colours** (dark-on-light) — a QR can't invert in dark
  mode and stay scannable, so the default fg/bg are theme-independent; theming
  is opt-in via `color`/`background` (you own the contrast).
- **Quiet zone is in modules, not pixels** — `margin` measures the quiet zone in
  QR *modules* (spec minimum 4 — ISO/IEC 18004), the canonical unit: it scales
  with the symbol so the clear ring stays proportional at any rendered size,
  which is what guarantees scannability. There is deliberately no pixel margin
  prop. For fixed pixel spacing in a layout, pad the container in CSS using the
  QR's `background` colour — the symbol's quiet zone stays canonical in modules.
- **Export bakes resolved colours** — a serialized SVG loses the document's CSS
  custom properties, so `DownloadTrigger` resolves `getComputedStyle` fills into
  the clone before writing PNG/SVG.
- **Logo in exports** — SVG export is lossless (the logo is XML and travels with
  it). PNG export omits the logo: browsers do not rasterize `<foreignObject>`
  content when an SVG is drawn to a canvas via `<img>` (a Chromium limitation,
  not a taint — the QR itself rasterizes fine). The cleared centre region stays,
  but the overlay is dropped. Use SVG to keep the logo. (A future PNG path could
  composite a raster logo directly onto the canvas; deferred — the `logo` slot is
  an arbitrary snippet, not a URL.)

## Anatomy (parts)

```
<QrCode value="https://…">          ← Frame  (svg, role="img", aria-label)
  └ Pattern                          ← the <path> matrix (decorative)
  └ Overlay                          ← centred logo slot (optional)
<QrCode.DownloadTrigger>             ← <Button> → PNG / SVG (optional)
```

morfo `scope: ['eidos']` (+ optional `sema` for a `commit-download` tap cue).
**No soma** — a QR is a pure display (like Avatar / Image): `value` → matrix in
a `$derived`, rendered to SVG. Download is imperative via `$adom`.

## API (root)

| Prop | Type | Default | |
| --- | --- | --- | --- |
| `value` | `string` | `''` | data to encode (bindable) |
| `size` | `ResponsiveProp<number \| Size>` | `'md'` | rendered box size |
| `errorCorrection` | `'L' \| 'M' \| 'Q' \| 'H'` | `'M'` | redundancy (auto-boosted to `H` when a logo is present) |
| `color` | `AffirmativeColorRole \| string` | `currentColor`/token | module colour |
| `background` | `string` | token / transparent | quiet-zone + module background |
| `cellShape` | `'square' \| 'rounded' \| 'dots'` | `'square'` | module shape |
| `margin` | `number` | `4` | quiet zone in modules, not pixels (spec min 4 — see Scannability) |
| `logo` | `Snippet` | — | centred overlay; clears the centre + boosts ECC to `H` |
| `alt` | `string` | `value` | accessible name for the Frame |

`DownloadTrigger` props: `format: 'png' \| 'svg'` (default `'png'`), `filename`
(default `'qrcode'`) + all `<Button>` props (`variant`, `size`, `color`, …).
It renders the framework `<Button>` and calls the root's colour-baking export
via context.

Compound: `<QrCode>` + `.DownloadTrigger`. The logo is the `logo` snippet prop
(not a subcomponent); the morfo's Overlay/Pattern parts are render internals.

## Decisiones

Each argued in place above; the compact register:

- **Own zero-dep encoder** (`$libs/qr`) — the QR algorithm is the open
  ISO/IEC 18004 standard; `uqr`/nayuki are correctness references only.
- **Function modules stay square** whatever `cellShape` (the `reserved` mask)
  — scannability over decoration (see Scannability).
- **Fixed-tone default colours** — a QR can't invert in dark mode and stay
  scannable; theming is opt-in via `color`/`background`.
- **`margin` in modules, not pixels** (spec min 4) — the quiet zone scales
  with the symbol; pixel spacing belongs to the container's CSS.
- **Exports bake resolved colours** (`getComputedStyle` into the clone) — a
  serialized SVG loses the document's custom properties.
- **No soma** — pure display (like Avatar/Image): `value` → matrix in a
  `$derived`; download is imperative via `$adom`.

## v1 scope (approved)

square/rounded/dots cell shapes · themeable colour · logo Overlay with auto
quiet-zone + auto-ECC-boost · download PNG + SVG · `role=img` + label.

## Gaps

- **Gradient fills + per-corner (finder) styling** — the marketing-grade
  flourishes of qr-code-styling — disposition: diferir (v2).
- **PNG export drops the logo** (`<foreignObject>` isn't rasterized when SVG
  draws to canvas; see Scannability) — disposition: diferir (a raster-logo
  composite path); SVG export is lossless.
- Demo page pending the v2 template migration — disposition: implementar
  (demo/docs web phase).

## Passive justification

Zero events by design: a QR is pure display — `value` in, SVG out; no
interaction surface of its own. The one interactive part, DownloadTrigger,
IS a composed `<Button>` (its `contact` firma and states live there). The
morfo may later add an optional `commit-download` cue (`scope` would gain
`sema`), which is the recorded exception path.

## Layers

- **`$libs/qr`** — own encoder + tests.
- **morfo** `qr-code.ts` — Frame / Pattern / Overlay / DownloadTrigger contract.
- **eidos** `qr-code/` — wrapper + recipe (`--qr-code-*` tokens) + SVG render
  from the matrix.
- **demo** `web/routes/uix/components/qr-code/` + nav entry.

## Audit exceptions

- `R-1.5 exception:` the only interactive part (`DownloadTrigger`) composes the canonical `<Button>` — the focus ring lives in `button.css`; `Pattern` and `Overlay` are display indicators.