@particle-academy/react-fancy 5.35.1 → 5.36.0

package/dist/qr-code.d.ts

@@ -0,0 +1,201 @@
+import * as react from 'react';
+import { SVGAttributes } from 'react';
+
+/**
+ * ISO/IEC 18004 table data for the QR encoder. **Data, not logic** — kept in
+ * its own module so the algorithm beside it can be read without scrolling past
+ * 160 rows, and so a correction here is a diff that cannot touch behaviour.
+ *
+ * There is no formula for these: the block structure per version and error
+ * correction level is a table in the standard. They were taken from the
+ * published error-correction table at
+ * <https://www.thonky.com/qr-code-tutorial/error-correction-table> rather than
+ * recalled, and every row is checked by `qr-code.test.tsx` against three
+ * equations that must all hold simultaneously:
+ *
+ *   1. `dataCodewords === g1Blocks * g1Size + g2Blocks * g2Size`
+ *   2. `totalCodewords === dataCodewords + ecPerBlock * (g1Blocks + g2Blocks)`
+ *   3. `totalCodewords === rawDataModules(version) / 8`, where
+ *      `rawDataModules` is counted from the matrix THIS code builds.
+ *
+ * The third is the one worth having: it ties a transcribed table to an
+ * independently constructed matrix, so a mistyped row, a wrong alignment
+ * pattern position and a wrong function-pattern layout cannot all agree.
+ */
+/** Error correction level. Higher levels survive more damage and hold less. */
+type QrErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+
+/**
+ * A QR encoder, dependency-free.
+ *
+ * ISO/IEC 18004, versions 1–40, error correction L/M/Q/H, with numeric,
+ * alphanumeric and byte modes and automatic selection between them. No
+ * Kanji mode and no structured append — neither has a caller here, and an
+ * untested branch in an encoder is worse than an absent one because the
+ * failure is a code a phone silently refuses to read.
+ *
+ * Table data and its provenance live in `./qr-tables`.
+ */
+
+/** Which encoding mode a value is carried in. */
+type QrMode = 'numeric' | 'alphanumeric' | 'byte';
+interface QrSymbol {
+    /** `size * size` modules, row-major. `true` is dark. */
+    modules: boolean[][];
+    /** Modules per side, `version * 4 + 17`. */
+    size: number;
+    version: number;
+    errorCorrection: QrErrorCorrection;
+    mode: QrMode;
+    /** The mask pattern chosen by penalty scoring, 0–7. */
+    mask: number;
+}
+/**
+ * The narrowest mode that can carry `value`.
+ *
+ * Narrower is denser: numeric packs 3 digits into 10 bits where byte mode
+ * would spend 24. A six-digit pairing PIN is a third of the size as numeric,
+ * which is the difference between a code a phone reads across a desk and one
+ * it does not.
+ */
+declare function selectMode(value: string): QrMode;
+interface EncodeOptions {
+    errorCorrection?: QrErrorCorrection;
+    /** Force a mode instead of selecting the narrowest that fits. */
+    mode?: QrMode;
+    /** Force a version. Throws if the value does not fit. */
+    version?: number;
+    /** Force a mask instead of scoring all eight. For tests and golden vectors. */
+    mask?: number;
+}
+/**
+ * Encode a string into a QR symbol.
+ *
+ * @throws RangeError when the value cannot fit, or when a forced version is
+ *   too small for it. **Throwing is deliberate**: the alternative is returning
+ *   a truncated symbol, which scans cleanly and yields the wrong string — a
+ *   silent corruption on the one surface whose entire job is to carry a value
+ *   accurately.
+ */
+declare function encodeQr(value: string, options?: EncodeOptions): QrSymbol;
+
+/**
+ * `viewBox` is omitted because the component computes it from the symbol's
+ * module count — overriding it would rescale the modules and break the
+ * crispness the vector output exists for.
+ *
+ * `version` is omitted because SVG has an attribute of that name and ours
+ * means the QR symbol version, a number. SVG's is a no-op in SVG 2 and was
+ * only ever a document-conformance hint, so nothing is lost by shadowing it,
+ * where renaming our prop would cost the one word every QR reference uses.
+ */
+interface QrCodeProps extends Omit<SVGAttributes<SVGSVGElement>, "children" | "viewBox" | "version"> {
+    /**
+     * What the code carries. Any string — a URL, a PIN, a token.
+     *
+     * An empty string renders a valid (empty) symbol rather than throwing, so a
+     * controlled surface can render before its value arrives.
+     */
+    value: string;
+    /** Rendered width and height in pixels. Default 192. */
+    size?: number;
+    /**
+     * Error correction level. Default `"M"` — about 15% of the symbol can be
+     * damaged and still read, which is the usual choice for a screen.
+     *
+     * Higher is not better by default: `"H"` survives ~30% damage and holds a
+     * third less, so the same value needs a bigger symbol with smaller modules,
+     * and on a phone screen that can read WORSE than `"M"` at the same pixel
+     * size. Raise it for print, for a label that will be scuffed, or when a logo
+     * covers part of the symbol.
+     */
+    errorCorrection?: QrErrorCorrection;
+    /**
+     * Accessible name. **Required**, and it must describe the DESTINATION rather
+     * than the artefact: "Pair this device" tells a screen-reader user what the
+     * code is for, where "QR code" tells them only that an image they cannot use
+     * is present.
+     *
+     * It is not a substitute for the value being reachable another way. A QR code
+     * is unusable by anyone who cannot point a second device at this screen, so
+     * the value should also appear as text or a link nearby — the `aria-label`
+     * cannot carry a URL a user is expected to type.
+     */
+    label: string;
+    /**
+     * Modules of quiet zone around the symbol. Default 4, which is the
+     * standard's minimum.
+     *
+     * **Do not set this to 0 to save space.** The quiet zone is not padding; it
+     * is how a scanner finds the symbol's edge. A code flush against
+     * surrounding content is the single most common reason a QR code that looks
+     * perfect will not scan.
+     */
+    quietZone?: number;
+    /** Module colour. Default `currentColor`, so it inherits text colour. */
+    foreground?: string;
+    /**
+     * Background colour. Default `"transparent"`.
+     *
+     * **A transparent background inherits whatever is behind it**, so on a dark
+     * surface the symbol renders dark-on-dark and most scanners will not read
+     * it. Set an explicit light background, or set `foreground` and background
+     * together, when the surface is not light. Contrast is what gets scanned,
+     * not the dark modules on their own.
+     */
+    background?: string;
+    /**
+     * Force a mode instead of picking the narrowest that fits. Rarely useful;
+     * the default packs digits three to ten bits where byte mode spends 24.
+     */
+    mode?: QrMode;
+    /**
+     * Force a symbol version (1–40), fixing the module count regardless of how
+     * little the value needs. Useful when several codes must render at the same
+     * module scale. Throws if the value does not fit.
+     */
+    version?: number;
+}
+
+/**
+ * A QR code, as an SVG, with no dependencies.
+ *
+ * ## Why SVG and one path
+ *
+ * The symbol is drawn as a **single `<path>`** of one-unit squares on a
+ * `viewBox` sized in modules, not as a grid of `<rect>` elements. A version 10
+ * symbol is 57x57 — over three thousand modules — and a rect each would be
+ * three thousand DOM nodes for something that never changes. One path is one
+ * node, and because the viewBox is in module units the symbol is resolution
+ * independent: `size` scales it with no resampling, so it stays crisp at any
+ * size and prints at the printer's resolution rather than the screen's.
+ *
+ * This matters more than it sounds for scanning. A raster QR code scaled to a
+ * non-integer multiple of its module size gets blurred module edges, and a
+ * scanner reading a blurred edge guesses. Vector output cannot have that
+ * problem.
+ *
+ * ## It is an image of a value, not the value
+ *
+ * A QR code is unreadable to anyone without a second device pointed at the
+ * screen — which includes every screen-reader user and anyone whose phone is
+ * the device showing it. So `label` is required, and the value should ALSO be
+ * reachable as text or a link beside it. A pairing panel that shows only a
+ * code is a panel some people cannot use at all.
+ *
+ * @example
+ * ```tsx
+ * <QrCode
+ *   value="https://alphar.tail1234.ts.net:7421/pair#482913"
+ *   size={192}
+ *   label="Pair this device"
+ * />
+ *
+ * // On a dark surface, set both colours: a transparent background renders
+ * // dark-on-dark and will not scan.
+ * <QrCode value={url} label="Pair" foreground="#0b0b0c" background="#ffffff" />
+ * ```
+ */
+declare const QrCode: react.ForwardRefExoticComponent<QrCodeProps & react.RefAttributes<SVGSVGElement>>;
+
+export { type EncodeOptions, QrCode, type QrCodeProps, type QrErrorCorrection, type QrMode, type QrSymbol, encodeQr, selectMode };

package/dist/qr-code.js

@@ -0,0 +1,4 @@
+export { QrCode, encodeQr, selectMode } from './chunk-PK2FHI5R.js';
+import './chunk-MMW2JGKZ.js';
+//# sourceMappingURL=qr-code.js.map
+//# sourceMappingURL=qr-code.js.map

package/dist/qr-code.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"qr-code.js"}

package/docs/QrCode.md

@@ -0,0 +1,132 @@
+# QrCode
+
+A QR code rendered as an SVG, with **no dependencies** — the encoder is part of
+the component.
+
+ISO/IEC 18004, versions 1–40, error correction L/M/Q/H, with numeric,
+alphanumeric and byte modes selected automatically.
+
+## Import
+
+```tsx
+import { QrCode } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<QrCode
+  value="https://alphar.tail1234.ts.net:7421/pair#482913"
+  size={192}
+  label="Pair this device"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | — | What the code carries. An empty string renders a valid empty symbol rather than throwing. |
+| label | `string` | — | **Required.** Accessible name. Describe the destination ("Pair this device"), not the artefact ("QR code"). |
+| size | `number` | `192` | Rendered width and height in pixels. |
+| errorCorrection | `"L" \| "M" \| "Q" \| "H"` | `"M"` | Damage tolerance. See the note below — higher is not automatically better. |
+| quietZone | `number` | `4` | Modules of clear margin. The standard's minimum is 4. |
+| foreground | `string` | `"currentColor"` | Module colour. |
+| background | `string` | `"transparent"` | Background colour. See the note below. |
+| mode | `"numeric" \| "alphanumeric" \| "byte"` | *auto* | Force an encoding mode. Rarely useful. |
+| version | `number` | *auto* | Force a symbol version 1–40, fixing the module count. Throws if the value does not fit. |
+
+Every other SVG attribute passes through. `viewBox` and SVG's own `version` are
+not accepted — the component owns the first, and the second collides with the QR
+symbol version.
+
+## Three ways a perfect-looking code fails to scan
+
+None of these are visible in a screenshot review, which is why they are here
+rather than in a footnote.
+
+**1. No quiet zone.** It is not padding — it is how a scanner finds the
+symbol's edge. A code flush against surrounding content is the single most
+common cause of "the QR code doesn't work". `quietZone={0}` is allowed, because
+a consumer compositing their own margin has a legitimate reason, but it is not
+a space saving.
+
+**2. A transparent background on a dark surface.** The default inherits
+whatever is behind it, so on a dark panel the symbol renders dark-on-dark and
+most scanners refuse it. Contrast is what gets scanned, not the dark modules on
+their own:
+
+```tsx
+<QrCode value={url} label="Pair" foreground="#0b0b0c" background="#ffffff" />
+```
+
+**3. Reaching for `"H"` because it sounds safer.** `"H"` survives about 30%
+damage against `"M"`'s 15%, but it holds a third less — so the same value needs
+a larger symbol, and at the same pixel width that means *smaller modules*. On a
+phone screen `"H"` can read worse than `"M"`. Raise it for print, for a label
+that will be scuffed, or when a logo covers part of the symbol.
+
+## It is an image of a value, not the value
+
+A QR code is unusable to anyone who cannot point a second device at the screen —
+every screen-reader user, and anyone whose phone is the device displaying it. So
+`label` is required, **and the value should also be reachable as text or a
+link** beside it. An `aria-label` cannot carry a URL someone is expected to
+type.
+
+```tsx
+<div className="flex flex-col items-center gap-3">
+  <QrCode value={pairUrl} label="Pair this device" background="#ffffff" />
+  <code className="text-sm">{pairUrl}</code>
+</div>
+```
+
+## A PIN is denser than a URL
+
+Mode selection is automatic and it matters. Numeric mode packs three digits into
+ten bits where byte mode spends twenty-four, so a six-digit PIN is a version 1
+symbol — the largest modules and the easiest read:
+
+```tsx
+<QrCode value="482913" label="Pairing PIN" />   {/* 21 modules + quiet zone */}
+```
+
+## Why SVG, and one path
+
+The symbol is one `<path>` of unit squares on a module-unit `viewBox`, not a
+`<rect>` per module. A version 10 symbol has over three thousand modules, so a
+rect each would be three thousand DOM nodes for something that never changes
+after render. Horizontal runs are packed into single rectangles.
+
+The module-unit viewBox is what makes `size` free: the symbol is resolution
+independent, so it stays crisp at any size and prints at the printer's
+resolution. That is not only cosmetic — a raster code scaled to a non-integer
+multiple of its module size has blurred module edges, and a scanner reading a
+blurred edge guesses.
+
+## The encoder on its own
+
+Exported alongside the component, for a consumer that needs modules rather than
+an SVG — a canvas, a PDF, a thermal printer, a terminal:
+
+```tsx
+import { encodeQr, selectMode } from "@particle-academy/react-fancy";
+
+const symbol = encodeQr("https://example.com", { errorCorrection: "Q" });
+symbol.modules;         // boolean[][], true is dark
+symbol.size;            // version * 4 + 17
+symbol.version;         // 1-40
+symbol.mask;            // the mask chosen by penalty scoring
+selectMode("482913");   // "numeric"
+```
+
+`encodeQr` throws a `RangeError` rather than truncating a value that does not
+fit. That is deliberate: a truncated symbol scans cleanly and yields the wrong
+string, which is silent corruption on a surface whose entire job is to carry a
+value accurately.
+
+## Not supported
+
+Kanji mode and structured append. Neither has a caller here, and an untested
+branch in an encoder is worse than an absent one — the failure is a code a
+phone quietly refuses to read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "5.35.1",
+  "version": "5.36.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",
@@ -713,6 +713,16 @@
         "default": "./dist/pull-quote.cjs"
       }
     },
+    "./qr-code": {
+      "import": {
+        "types": "./dist/qr-code.d.ts",
+        "default": "./dist/qr-code.js"
+      },
+      "require": {
+        "types": "./dist/qr-code.d.cts",
+        "default": "./dist/qr-code.cjs"
+      }
+    },
     "./radio-group": {
       "import": {
         "types": "./dist/radio-group.d.ts",