@particle-academy/react-fancy 6.7.1 → 6.8.0

package/dist/qr-code.d.cts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { SVGAttributes } from 'react';
+import { SVGAttributes, HTMLAttributes } from 'react';
+import { S as Size } from './types-DJI492iY.cjs';
 
 /**
  * ISO/IEC 18004 table data for the QR encoder. **Data, not logic** — kept in
@@ -220,4 +221,222 @@ interface QrCodeProps extends Omit<SVGAttributes<SVGSVGElement>, "children" | "v
  */
 declare const QrCode: react.ForwardRefExoticComponent<QrCodeProps & react.RefAttributes<SVGSVGElement>>;
 
-export { type EncodeOptions, QrCode, type QrCodeProps, type QrErrorCorrection, type QrMode, type QrSymbol, encodeQr, selectMode };
+/** What a person can do with a code. Each renders one `Button`. */
+type QrCodeAction = "download-svg" | "download-png" | "share" | "print";
+/**
+ * How an action ended.
+ *
+ * - `done`: the file was handed to the browser, the share sheet completed, the
+ *   value was copied, or the print dialog was opened.
+ * - `cancelled`: the person dismissed the share sheet. Not an error.
+ * - `failed`: nothing happened that the person asked for; `error` says why.
+ */
+type QrCodeActionOutcome = "done" | "cancelled" | "failed";
+/** One action, reported. Plain JSON, so it can go straight to an agent or a log. */
+interface QrCodeActionEvent {
+    action: QrCodeAction;
+    outcome: QrCodeActionOutcome;
+    /** For `share`: whether the Web Share sheet or the clipboard carried it. */
+    via?: "share" | "clipboard";
+    /** For a download: the file name the browser was given. */
+    fileName?: string;
+    /** For `failed`: the reason, as text. */
+    error?: string;
+}
+/** Visible button text and the announcements read out after each action. */
+interface QrCodePanelLabels {
+    downloadSvg: string;
+    downloadPng: string;
+    share: string;
+    /** The share button's text where Web Share is absent and a web link is copied. */
+    copyLink: string;
+    /** The same, for a value that is not a web link. */
+    copy: string;
+    print: string;
+    downloaded: string;
+    shared: string;
+    copied: string;
+    printing: string;
+    failed: string;
+}
+interface QrCodePanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+    /** What the code carries. Any string; see `QrCode`'s `value`. */
+    value: string;
+    /**
+     * What the code is FOR, e.g. "Your sign-up link". Required. Names the code,
+     * the group around it, the SVG file's `<title>`, the print page's title,
+     * and the share sheet's title unless `shareTitle` is set.
+     */
+    label: string;
+    /** Rendered size of the code in pixels. Default 192. */
+    size?: number;
+    errorCorrection?: QrErrorCorrection;
+    quietZone?: number;
+    /**
+     * Module colour. Default `#000000`, on screen as well as in files.
+     *
+     * The panel does NOT inherit text colour the way a bare `<QrCode>` does: a
+     * code must be dark on light to scan, so the panel pins black on white in
+     * dark mode too. Black on white is 21:1, past WCAG AAA's 7:1.
+     */
+    foreground?: string;
+    /** Background, quiet zone included. Default `#ffffff`, in both colour schemes. */
+    background?: string;
+    mode?: QrMode;
+    version?: number;
+    /**
+     * Which actions to offer, in order. Default all four:
+     * `["download-svg", "download-png", "share", "print"]`. `[]` renders none.
+     */
+    actions?: readonly QrCodeAction[];
+    /**
+     * Show the value as selectable text under the code, and on the printed page.
+     * Default `false`, because not every value is meant to be read out: a WiFi
+     * block carries a password. Turn it on for a link or a reference a person
+     * might type instead of scanning.
+     */
+    showValue?: boolean;
+    /** Download file name, without extension. Sanitised. Default `"qr-code"`. */
+    fileName?: string;
+    /** PNG pixels per module, a whole number. Default 10. */
+    pngScale?: number;
+    /** Share sheet title. Default `label`. */
+    shareTitle?: string;
+    /** Printed width of the code in millimetres. Default 50. */
+    printSizeMm?: number;
+    /**
+     * Size of the action buttons. Default `"lg"`, which is 44px tall: WCAG
+     * 2.5.5's AAA target size. Smaller sizes still meet AA's 24px (2.5.8).
+     */
+    buttonSize?: Size;
+    /** Button text and announcements, for translation. Partial; the rest default. */
+    labels?: Partial<QrCodePanelLabels>;
+    /** Called once per action, with how it ended. */
+    onAction?: (event: QrCodeActionEvent) => void;
+}
+
+/**
+ * A QR code with what a person does with one: download it as SVG or PNG,
+ * share it (the Web Share sheet, or a copy where there is none), print it, and
+ * read the value as text.
+ *
+ * ## Why a panel, and not props on `<QrCode>`
+ *
+ * `<QrCode>` is an `<svg>`: it drops into a label template, a PDF, a canvas or
+ * a badge and draws a code, nothing else. Buttons, a live region and a print
+ * frame inside an `<svg>` would be invalid markup, and making it a `<div>`
+ * would break every caller that styles or measures it as an image. So the
+ * actions compose AROUND it, the way `Card` composes its sections, and the
+ * file formats are separate functions (`qrCodeSvg`, `qrCodePng`) that a host
+ * or an agent can call without rendering anything.
+ *
+ * ## The code tile is light in dark mode too
+ *
+ * The panel draws black modules on a white tile, quiet zone included, in both
+ * colour schemes. A QR code is read by contrast between dark modules and a
+ * LIGHT surround; most scanners do not read an inverted code, and the quiet
+ * zone must be the light colour for the finder patterns to be found. A dark
+ * page around a white tile is fine. Black on white is 21:1, past WCAG AAA.
+ *
+ * ## Accessibility
+ *
+ * - The group is named by `label`, and so is the code inside it (`role="img"`).
+ * - `showValue` puts the value on screen as selectable text, because a code is
+ *   unusable to anyone who cannot point a second device at the screen.
+ * - Every action is a react-fancy `Button` with a visible text label, in the
+ *   tab order, operable by Enter and Space, with the kit's `focus-visible`
+ *   ring. Default size `lg` is 44px tall, WCAG 2.5.5's AAA target size.
+ * - What each action did is announced through a polite `role="status"`.
+ *
+ * @example
+ * ```tsx
+ * <QrCodePanel
+ *   value="https://example.com/r/AbC123"
+ *   label="Your sign-up link"
+ *   showValue
+ *   fileName="sign-up-link"
+ *   onAction={(event) => console.log(event)}
+ * />
+ * ```
+ */
+declare const QrCodePanel: react.ForwardRefExoticComponent<QrCodePanelProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Files of a QR code: a standalone SVG and a PNG.
+ *
+ * Both are drawn from {@link modulePath}, the builder `<QrCode>` uses on
+ * screen, so a downloaded file carries exactly the modules the person saw.
+ *
+ * ## A file is always opaque
+ *
+ * On screen a code can inherit its colours: `currentColor` modules on a
+ * `transparent` background take whatever the page puts behind them. A file has
+ * no page behind it. A PNG with a transparent background opens dark-on-dark in
+ * every image viewer with a dark theme, and dark-on-dark does not scan. So in
+ * a file, `transparent` (or no background) becomes white and `currentColor`
+ * becomes black. Explicit colours are kept as given: choosing a dark
+ * background is the caller's decision, and the docs say what it costs.
+ */
+interface QrCodeFileOptions {
+    /**
+     * What the code is FOR, e.g. "Your sign-up link". Written into the SVG as
+     * its `<title>` and accessible name, so the file still says what it is when
+     * it is opened, attached or printed somewhere else. Required, as on
+     * `<QrCode>`.
+     */
+    label: string;
+    errorCorrection?: QrErrorCorrection;
+    mode?: QrMode;
+    version?: number;
+    /** Modules of quiet zone. Default 4, the standard's minimum. */
+    quietZone?: number;
+    /** Module colour. Default and `currentColor` both mean `#000000`. */
+    foreground?: string;
+    /** Background colour. Default and `transparent` both mean `#ffffff`. */
+    background?: string;
+}
+interface QrCodeSvgOptions extends QrCodeFileOptions {
+    /** Width and height in pixels. Default: ten pixels per module. */
+    size?: number;
+}
+interface QrCodePngOptions extends QrCodeFileOptions {
+    /**
+     * Pixels per module, rounded DOWN to a whole number. Default 10.
+     *
+     * Whole numbers only, because a module drawn across a fraction of a pixel
+     * gets a blurred edge, and a scanner reading a blurred edge guesses. Clamped
+     * to at least 1, and down so the image is at most 8192 pixels a side.
+     */
+    scale?: number;
+    /**
+     * The canvas to draw on. Default: a new `<canvas>`. Pass one to draw where
+     * there is no `document` (an `OffscreenCanvas` will not do: it has no
+     * `toBlob`) or to inspect the drawing in a test.
+     */
+    canvas?: HTMLCanvasElement;
+}
+/**
+ * A QR code as a standalone SVG document, with an XML declaration, a
+ * `<title>`, an accessible name and an opaque background.
+ *
+ * @throws RangeError when the value cannot fit, exactly as `encodeQr` does,
+ *   and as cheaply: an impossible value is refused from its length alone.
+ */
+declare function qrCodeSvg(value: string, options: QrCodeSvgOptions): string;
+/**
+ * A QR code as a PNG, drawn on a canvas from the same path data as the SVG.
+ *
+ * It does not load the SVG into an `<img>` first. That route needs a `blob:`
+ * or `data:` image, which a Content Security Policy of `img-src 'self'`
+ * blocks, and the download would then fail on exactly the sites careful
+ * enough to set one. `Path2D` takes the SVG path string directly, so the
+ * geometry is the SVG's and nothing is fetched.
+ *
+ * The background is painted over the whole canvas, quiet zone included, before
+ * any module. Each colour is set over a known default first: a canvas ignores
+ * a colour it cannot parse and keeps the previous one, so an unreadable
+ * background would otherwise inherit black and produce a black square.
+ */
+declare function qrCodePng(value: string, options: QrCodePngOptions): Promise<Blob>;
+
+export { type EncodeOptions, QrCode, type QrCodeAction, type QrCodeActionEvent, type QrCodeActionOutcome, type QrCodeFileOptions, QrCodePanel, type QrCodePanelLabels, type QrCodePanelProps, type QrCodePngOptions, type QrCodeProps, type QrCodeSvgOptions, type QrErrorCorrection, type QrMode, type QrSymbol, encodeQr, qrCodePng, qrCodeSvg, selectMode };

package/dist/qr-code.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { SVGAttributes } from 'react';
+import { SVGAttributes, HTMLAttributes } from 'react';
+import { S as Size } from './types-DJI492iY.js';
 
 /**
  * ISO/IEC 18004 table data for the QR encoder. **Data, not logic** — kept in
@@ -220,4 +221,222 @@ interface QrCodeProps extends Omit<SVGAttributes<SVGSVGElement>, "children" | "v
  */
 declare const QrCode: react.ForwardRefExoticComponent<QrCodeProps & react.RefAttributes<SVGSVGElement>>;
 
-export { type EncodeOptions, QrCode, type QrCodeProps, type QrErrorCorrection, type QrMode, type QrSymbol, encodeQr, selectMode };
+/** What a person can do with a code. Each renders one `Button`. */
+type QrCodeAction = "download-svg" | "download-png" | "share" | "print";
+/**
+ * How an action ended.
+ *
+ * - `done`: the file was handed to the browser, the share sheet completed, the
+ *   value was copied, or the print dialog was opened.
+ * - `cancelled`: the person dismissed the share sheet. Not an error.
+ * - `failed`: nothing happened that the person asked for; `error` says why.
+ */
+type QrCodeActionOutcome = "done" | "cancelled" | "failed";
+/** One action, reported. Plain JSON, so it can go straight to an agent or a log. */
+interface QrCodeActionEvent {
+    action: QrCodeAction;
+    outcome: QrCodeActionOutcome;
+    /** For `share`: whether the Web Share sheet or the clipboard carried it. */
+    via?: "share" | "clipboard";
+    /** For a download: the file name the browser was given. */
+    fileName?: string;
+    /** For `failed`: the reason, as text. */
+    error?: string;
+}
+/** Visible button text and the announcements read out after each action. */
+interface QrCodePanelLabels {
+    downloadSvg: string;
+    downloadPng: string;
+    share: string;
+    /** The share button's text where Web Share is absent and a web link is copied. */
+    copyLink: string;
+    /** The same, for a value that is not a web link. */
+    copy: string;
+    print: string;
+    downloaded: string;
+    shared: string;
+    copied: string;
+    printing: string;
+    failed: string;
+}
+interface QrCodePanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+    /** What the code carries. Any string; see `QrCode`'s `value`. */
+    value: string;
+    /**
+     * What the code is FOR, e.g. "Your sign-up link". Required. Names the code,
+     * the group around it, the SVG file's `<title>`, the print page's title,
+     * and the share sheet's title unless `shareTitle` is set.
+     */
+    label: string;
+    /** Rendered size of the code in pixels. Default 192. */
+    size?: number;
+    errorCorrection?: QrErrorCorrection;
+    quietZone?: number;
+    /**
+     * Module colour. Default `#000000`, on screen as well as in files.
+     *
+     * The panel does NOT inherit text colour the way a bare `<QrCode>` does: a
+     * code must be dark on light to scan, so the panel pins black on white in
+     * dark mode too. Black on white is 21:1, past WCAG AAA's 7:1.
+     */
+    foreground?: string;
+    /** Background, quiet zone included. Default `#ffffff`, in both colour schemes. */
+    background?: string;
+    mode?: QrMode;
+    version?: number;
+    /**
+     * Which actions to offer, in order. Default all four:
+     * `["download-svg", "download-png", "share", "print"]`. `[]` renders none.
+     */
+    actions?: readonly QrCodeAction[];
+    /**
+     * Show the value as selectable text under the code, and on the printed page.
+     * Default `false`, because not every value is meant to be read out: a WiFi
+     * block carries a password. Turn it on for a link or a reference a person
+     * might type instead of scanning.
+     */
+    showValue?: boolean;
+    /** Download file name, without extension. Sanitised. Default `"qr-code"`. */
+    fileName?: string;
+    /** PNG pixels per module, a whole number. Default 10. */
+    pngScale?: number;
+    /** Share sheet title. Default `label`. */
+    shareTitle?: string;
+    /** Printed width of the code in millimetres. Default 50. */
+    printSizeMm?: number;
+    /**
+     * Size of the action buttons. Default `"lg"`, which is 44px tall: WCAG
+     * 2.5.5's AAA target size. Smaller sizes still meet AA's 24px (2.5.8).
+     */
+    buttonSize?: Size;
+    /** Button text and announcements, for translation. Partial; the rest default. */
+    labels?: Partial<QrCodePanelLabels>;
+    /** Called once per action, with how it ended. */
+    onAction?: (event: QrCodeActionEvent) => void;
+}
+
+/**
+ * A QR code with what a person does with one: download it as SVG or PNG,
+ * share it (the Web Share sheet, or a copy where there is none), print it, and
+ * read the value as text.
+ *
+ * ## Why a panel, and not props on `<QrCode>`
+ *
+ * `<QrCode>` is an `<svg>`: it drops into a label template, a PDF, a canvas or
+ * a badge and draws a code, nothing else. Buttons, a live region and a print
+ * frame inside an `<svg>` would be invalid markup, and making it a `<div>`
+ * would break every caller that styles or measures it as an image. So the
+ * actions compose AROUND it, the way `Card` composes its sections, and the
+ * file formats are separate functions (`qrCodeSvg`, `qrCodePng`) that a host
+ * or an agent can call without rendering anything.
+ *
+ * ## The code tile is light in dark mode too
+ *
+ * The panel draws black modules on a white tile, quiet zone included, in both
+ * colour schemes. A QR code is read by contrast between dark modules and a
+ * LIGHT surround; most scanners do not read an inverted code, and the quiet
+ * zone must be the light colour for the finder patterns to be found. A dark
+ * page around a white tile is fine. Black on white is 21:1, past WCAG AAA.
+ *
+ * ## Accessibility
+ *
+ * - The group is named by `label`, and so is the code inside it (`role="img"`).
+ * - `showValue` puts the value on screen as selectable text, because a code is
+ *   unusable to anyone who cannot point a second device at the screen.
+ * - Every action is a react-fancy `Button` with a visible text label, in the
+ *   tab order, operable by Enter and Space, with the kit's `focus-visible`
+ *   ring. Default size `lg` is 44px tall, WCAG 2.5.5's AAA target size.
+ * - What each action did is announced through a polite `role="status"`.
+ *
+ * @example
+ * ```tsx
+ * <QrCodePanel
+ *   value="https://example.com/r/AbC123"
+ *   label="Your sign-up link"
+ *   showValue
+ *   fileName="sign-up-link"
+ *   onAction={(event) => console.log(event)}
+ * />
+ * ```
+ */
+declare const QrCodePanel: react.ForwardRefExoticComponent<QrCodePanelProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Files of a QR code: a standalone SVG and a PNG.
+ *
+ * Both are drawn from {@link modulePath}, the builder `<QrCode>` uses on
+ * screen, so a downloaded file carries exactly the modules the person saw.
+ *
+ * ## A file is always opaque
+ *
+ * On screen a code can inherit its colours: `currentColor` modules on a
+ * `transparent` background take whatever the page puts behind them. A file has
+ * no page behind it. A PNG with a transparent background opens dark-on-dark in
+ * every image viewer with a dark theme, and dark-on-dark does not scan. So in
+ * a file, `transparent` (or no background) becomes white and `currentColor`
+ * becomes black. Explicit colours are kept as given: choosing a dark
+ * background is the caller's decision, and the docs say what it costs.
+ */
+interface QrCodeFileOptions {
+    /**
+     * What the code is FOR, e.g. "Your sign-up link". Written into the SVG as
+     * its `<title>` and accessible name, so the file still says what it is when
+     * it is opened, attached or printed somewhere else. Required, as on
+     * `<QrCode>`.
+     */
+    label: string;
+    errorCorrection?: QrErrorCorrection;
+    mode?: QrMode;
+    version?: number;
+    /** Modules of quiet zone. Default 4, the standard's minimum. */
+    quietZone?: number;
+    /** Module colour. Default and `currentColor` both mean `#000000`. */
+    foreground?: string;
+    /** Background colour. Default and `transparent` both mean `#ffffff`. */
+    background?: string;
+}
+interface QrCodeSvgOptions extends QrCodeFileOptions {
+    /** Width and height in pixels. Default: ten pixels per module. */
+    size?: number;
+}
+interface QrCodePngOptions extends QrCodeFileOptions {
+    /**
+     * Pixels per module, rounded DOWN to a whole number. Default 10.
+     *
+     * Whole numbers only, because a module drawn across a fraction of a pixel
+     * gets a blurred edge, and a scanner reading a blurred edge guesses. Clamped
+     * to at least 1, and down so the image is at most 8192 pixels a side.
+     */
+    scale?: number;
+    /**
+     * The canvas to draw on. Default: a new `<canvas>`. Pass one to draw where
+     * there is no `document` (an `OffscreenCanvas` will not do: it has no
+     * `toBlob`) or to inspect the drawing in a test.
+     */
+    canvas?: HTMLCanvasElement;
+}
+/**
+ * A QR code as a standalone SVG document, with an XML declaration, a
+ * `<title>`, an accessible name and an opaque background.
+ *
+ * @throws RangeError when the value cannot fit, exactly as `encodeQr` does,
+ *   and as cheaply: an impossible value is refused from its length alone.
+ */
+declare function qrCodeSvg(value: string, options: QrCodeSvgOptions): string;
+/**
+ * A QR code as a PNG, drawn on a canvas from the same path data as the SVG.
+ *
+ * It does not load the SVG into an `<img>` first. That route needs a `blob:`
+ * or `data:` image, which a Content Security Policy of `img-src 'self'`
+ * blocks, and the download would then fail on exactly the sites careful
+ * enough to set one. `Path2D` takes the SVG path string directly, so the
+ * geometry is the SVG's and nothing is fetched.
+ *
+ * The background is painted over the whole canvas, quiet zone included, before
+ * any module. Each colour is set over a known default first: a canvas ignores
+ * a colour it cannot parse and keeps the previous one, so an unreadable
+ * background would otherwise inherit black and produce a black square.
+ */
+declare function qrCodePng(value: string, options: QrCodePngOptions): Promise<Blob>;
+
+export { type EncodeOptions, QrCode, type QrCodeAction, type QrCodeActionEvent, type QrCodeActionOutcome, type QrCodeFileOptions, QrCodePanel, type QrCodePanelLabels, type QrCodePanelProps, type QrCodePngOptions, type QrCodeProps, type QrCodeSvgOptions, type QrErrorCorrection, type QrMode, type QrSymbol, encodeQr, qrCodePng, qrCodeSvg, selectMode };

package/dist/qr-code.js

@@ -1,4 +1,7 @@
-export { QrCode, encodeQr, selectMode } from './chunk-RLE5WYY6.js';
+export { QrCode, QrCodePanel, encodeQr, qrCodePng, qrCodeSvg, selectMode } from './chunk-PIG3UTHU.js';
+import './chunk-4GPH7HOR.js';
+import './chunk-45BBNJQD.js';
+import './chunk-J3A4Z2P7.js';
 import './chunk-MMW2JGKZ.js';
 //# sourceMappingURL=qr-code.js.map
 //# sourceMappingURL=qr-code.js.map

package/docs/PromptInput.md

@@ -31,8 +31,12 @@ import { PromptInput } from "@particle-academy/react-fancy";
 ## Features
 
 - Auto-resizes up to `maxHeight`.
-- `/` opens a filtered command palette. ↑/↓ navigate, Enter inserts.
+- `/` opens a filtered command palette. ↑/↓ navigate, Enter inserts. The
+  highlighted row is kept scrolled into view.
 - `@` opens a mention picker filtered against `mentions`.
+- Long command names and hints wrap inside the menu; a long mention name is
+  truncated with an ellipsis and kept whole in its `title`. The menu never
+  scrolls sideways.
 - Drop files anywhere on the input to attach. Chip bar shows attachments.
 - ⌘+Enter (or Ctrl+Enter) submits. Plain Enter inserts a newline. An Enter
   that confirms an IME composition neither submits nor picks from a menu.
@@ -225,7 +229,11 @@ Data handles: the root `[data-react-fancy-prompt-input]` (with
 `[data-react-fancy-prompt-input-attachment="<id>"]`, plus `-attach`, `-send`,
 `-meter`, `-hint` and `-error`. The text field is
 `[data-react-fancy-prompt-input-textarea]`, or `[data-react-fancy-composer-input]`
-with inline pills on; `inputId` gives it one id in both modes.
+with inline pills on; `inputId` gives it one id in both modes. The open `/` or
+`@` menu is `[data-react-fancy-prompt-input-menu="cmd" | "mention"]`, a
+`role="listbox"`; each row is a `role="option"`
+`[data-react-fancy-prompt-input-menu-item="<command name or mention id>"]`, and
+the highlighted one has `aria-selected="true"`.
 
 ## Defaults
 

package/docs/QrCode.md

@@ -164,6 +164,114 @@ value accurately.
 Capacity at the largest symbol (version 40, level `L`): **7,089** digits,
 **4,296** alphanumeric characters, or **2,953** bytes.
 
+## `QrCodePanel`: download, share, print
+
+`<QrCode>` is only an `<svg>`. `QrCodePanel` composes it with what a person does
+with a code: download it as SVG or PNG, share it, print it, and read the value
+as text.
+
+```tsx
+import { QrCodePanel } from "@particle-academy/react-fancy";
+
+<QrCodePanel
+  value="https://example.com/r/AbC123"
+  label="Your sign-up link"
+  showValue
+  fileName="sign-up-link"
+  onAction={(event) => console.log(event)}
+/>
+```
+
+It is a composition rather than props on `<QrCode>` because buttons, a live
+region and a print frame cannot live inside an `<svg>`, and turning `<QrCode>`
+into a `<div>` would break every caller that places it as an image.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value, label, size, errorCorrection, quietZone, mode, version | | | As on `<QrCode>`. `label` also names the group, the SVG file's `<title>`, the print page and the share sheet. |
+| foreground | `string` | `"#000000"` | Module colour, on screen and in files. |
+| background | `string` | `"#ffffff"` | Background and quiet zone, in **both** colour schemes. |
+| actions | `QrCodeAction[]` | all four | Any of `"download-svg"`, `"download-png"`, `"share"`, `"print"`, in the order given. `[]` renders none. |
+| showValue | `boolean` | `false` | Show the value as selectable text, and on the printed page. |
+| fileName | `string` | `"qr-code"` | Download name without extension. Letters, digits, `.`, `_`, `-` are kept; any other run becomes `-`. |
+| pngScale | `number` | `10` | PNG pixels per module, rounded down to a whole number. |
+| shareTitle | `string` | `label` | Title for the share sheet. |
+| printSizeMm | `number` | `50` | Printed width of the code. |
+| buttonSize | `Size` | `"lg"` | `lg` is 44px tall, WCAG 2.5.5's AAA target size. |
+| labels | `Partial<QrCodePanelLabels>` | English | Button text and announcements, for translation. |
+| onAction | `(event: QrCodeActionEvent) => void` | | Called once per action. |
+
+`onAction` receives plain JSON: `{ action, outcome, via?, fileName?, error? }`,
+where `outcome` is `"done"`, `"cancelled"` (the person dismissed the share sheet)
+or `"failed"` (with `error`). Every action reports, including a failure, so
+nothing fails silently.
+
+### Each action
+
+- **Download SVG**: a standalone SVG file with an XML declaration, a `<title>`
+  and an accessible name. Its path is the on-screen path, byte for byte.
+- **Download PNG**: drawn on a canvas from the same path data, at a whole number
+  of pixels per module, so no module edge is blurred. It is drawn with `Path2D`
+  rather than by loading the SVG into an `<img>`, because a Content Security
+  Policy of `img-src 'self'` blocks the `blob:` or `data:` image that route needs.
+  At most 8192 pixels a side.
+- **Share**: the Web Share sheet where the browser has one, sharing a web link
+  as `url` and anything else as `text`. Where it is absent, or `canShare`
+  refuses the data, the button reads "Copy link" (or "Copy" for a value that is
+  not a web link) and copies the value instead. A dismissed share sheet is
+  `cancelled`, not an error.
+- **Print**: a hidden frame holding nothing but the code, at `printSizeMm`, and
+  the value when `showValue` is on, then the browser's print dialog. The page is
+  built with DOM calls, never written as HTML, so neither `label` nor `value` is
+  parsed as markup. Styling goes through the CSSOM, which a CSP without
+  `'unsafe-inline'` allows.
+
+### The code tile is light in dark mode too
+
+A QR code is read by the contrast between dark modules and a **light**
+surround, quiet zone included: most scanners do not read an inverted code. So
+the panel draws black on white in both colour schemes. Black on white is 21:1,
+past WCAG AAA's 7:1. A dark page around a white tile is fine. If you pass your
+own colours, keep the background the lighter one.
+
+**Files are always opaque.** In a downloaded SVG or PNG, `transparent` (or no
+background) becomes white and `currentColor` becomes black, because a file has
+no page behind it to inherit. Explicit colours are kept as given.
+
+### Accessibility
+
+- The group and the code are both named by `label`.
+- `showValue` puts the value on screen as selectable text, for anyone who cannot
+  point a second device at the screen. It is off by default because not every
+  value is for reading out: a WiFi block carries a password.
+- Every action is a react-fancy `Button` with visible text, in the tab order,
+  operable by Enter and Space, with the kit's `focus-visible` ring.
+- What each action did is announced through a polite `role="status"` region.
+
+### Stable handles
+
+`[data-react-fancy-qr-code-panel]` on the root, `-panel-code`, `-panel-value`,
+`-panel-actions` and `-panel-status` on its parts, and
+`[data-react-fancy-qr-code-action="download-png"]` (and so on) on each button.
+The share button also carries `data-via="share"` or `data-via="clipboard"`.
+
+## The files on their own
+
+The panel's file formats are plain functions, for a host or an agent that wants
+a file without rendering anything:
+
+```tsx
+import { qrCodePng, qrCodeSvg } from "@particle-academy/react-fancy";
+
+const svg: string = qrCodeSvg("https://example.com/r/AbC123", { label: "Your sign-up link" });
+const png: Blob = await qrCodePng("https://example.com/r/AbC123", { label: "Your sign-up link", scale: 12 });
+```
+
+`qrCodeSvg` works anywhere, including on the server. `qrCodePng` needs a
+browser canvas. Both take `errorCorrection`, `mode`, `version`, `quietZone`,
+`foreground` and `background`, and throw the encoder's `RangeError` for a value
+that cannot fit.
+
 ## Not supported
 
 Kanji mode and structured append. Neither has a caller here, and an untested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "6.7.1",
+  "version": "6.8.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",