@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Progress/Progress.tsx

@@ -0,0 +1,129 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './Progress.module.scss';
+
+/** Visual size — controls the track height. */
+export type ProgressSize = 'sm' | 'md' | 'lg';
+
+/** Color tone for the fill. Default `'default'` uses the accent color. */
+export type ProgressTone = 'default' | 'success' | 'warning' | 'danger';
+
+/** Label render mode. */
+export type ProgressLabel = boolean | ReactNode;
+
+export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+  /**
+   * Current progress value. Omit (or pass `undefined`) to render the
+   * indeterminate animation.
+   *
+   * Two-channel behavior for out-of-range and degenerate values:
+   * - **Visual fill** is clamped to [0%, 100%]. Values outside [0, max]
+   *   render at the nearest valid bound.
+   * - **ARIA `aria-valuenow`** reports the raw number — this is the right
+   *   screen-reader behavior so consumer bugs (a value drifting past max)
+   *   surface in audits and SR announcements.
+   *
+   * Degenerate inputs fall back to the indeterminate animation: `NaN`,
+   * `Infinity`, `-Infinity`, and the case where `max <= 0`. This is the
+   * common file-upload race condition (`bytes_uploaded / total_bytes`
+   * before `total_bytes` is known produces NaN).
+   */
+  value?: number;
+  /**
+   * Upper bound. Defaults to `100`. Consumers using fraction values
+   * (0.0–1.0) pass `max={1}`. Consumers tracking a count ("3 of 10")
+   * pass `max={10}`.
+   */
+  max?: number;
+  /**
+   * Track height.
+   * - `sm` — 4px (compact / inside form rows)
+   * - `md` — 8px (default)
+   * - `lg` — 12px (page-level emphasis)
+   */
+  size?: ProgressSize;
+  /**
+   * Fill color tone. Defaults to `'default'` (accent blue). Tone applies
+   * ONLY to determinate mode; indeterminate always uses the accent tone
+   * because state-color semantics don't apply to an unknown total.
+   * - `default` — `--color-accent`
+   * - `success` — `--color-success`
+   * - `warning` — `--color-warning-strong`
+   * - `danger` — `--color-danger`
+   */
+  tone?: ProgressTone;
+  /**
+   * Optional label rendered to the RIGHT of the bar.
+   * - `false` (default) — no label
+   * - `true` — render `{Math.round((value / max) * 100)}%` when determinate.
+   *   Auto-suppressed when indeterminate (there's no percentage to show).
+   * - `ReactNode` — render the node as-is, in BOTH determinate and
+   *   indeterminate modes. Consumers wanting "Loading…" text next to an
+   *   indeterminate bar pass `label="Loading…"`.
+   */
+  label?: ProgressLabel;
+}
+
+const SIZE_CLASS: Record<ProgressSize, string> = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+};
+
+const TONE_CLASS: Record<ProgressTone, string> = {
+  default: styles.toneDefault,
+  success: styles.toneSuccess,
+  warning: styles.toneWarning,
+  danger: styles.toneDanger,
+};
+
+/**
+ * Linear progress bar: determinate against `max`, or an indeterminate slide when `value` is omitted; `role="progressbar"` is locked.
+ * @see docs/components/Progress.md
+ */
+export const Progress = forwardRef<HTMLDivElement, ProgressProps>(function Progress(
+  { value, max = 100, size = 'md', tone = 'default', label = false, className, ...rest },
+  ref,
+) {
+  // Determinate requires a finite numeric value AND a positive max. NaN /
+  // Infinity / max<=0 are silent consumer-bug paths (esp. file-upload divides
+  // bytes_uploaded / total_bytes before total_bytes is known → NaN). Fall
+  // back to the indeterminate animation rather than rendering a vanished bar
+  // or announcing "NaN percent" to screen readers.
+  const determinate = typeof value === 'number' && Number.isFinite(value) && max > 0;
+  const indeterminate = !determinate;
+  // VISUAL clamp only — ARIA reports the raw `value` via aria-valuenow below.
+  const percent = determinate ? Math.max(0, Math.min(100, (value / max) * 100)) : 0;
+  // Indeterminate has no aria-valuenow, so aria-valuetext is the only thing a
+  // screen reader has. Prefer the consumer's aria-label; the translated
+  // fallback is what it hears when there isn't one. This was hardcoded English
+  // in both progress components (#503).
+  const t = useTranslation();
+  const ariaLabel = rest['aria-label'];
+  const valuetext = indeterminate ? ariaLabel || t('progress.indeterminate') : undefined;
+
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <div
+      ref={ref}
+      role="progressbar"
+      className={clsx(styles.progress, SIZE_CLASS[size], TONE_CLASS[tone], className)}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      aria-valuenow={determinate ? value : undefined}
+      aria-valuetext={valuetext}
+      {...rest}
+    >
+      <div className={styles.track}>
+        <div
+          className={clsx(styles.fill, indeterminate && styles.indeterminate)}
+          style={determinate ? { width: `${percent}%` } : undefined}
+        />
+      </div>
+      {label !== false && !(label === true && indeterminate) && (
+        <span className={styles.label}>{label === true ? `${Math.round(percent)}%` : label}</span>
+      )}
+    </div>
+  );
+});

package/src/components/Progress/index.ts

@@ -0,0 +1,2 @@
+export { Progress } from './Progress';
+export type { ProgressProps, ProgressSize, ProgressTone, ProgressLabel } from './Progress';

package/src/components/QrCode/QrCode.module.scss

@@ -0,0 +1,97 @@
+@use '../../styles/mixins' as *;
+@use './QrCode.tokens';
+
+.root {
+  // Centres the painted frame, which is up to ONE MODULE narrower than the
+  // button once the symbol snaps to a whole number of device pixels per module
+  // — `side / dpr` CSS px, not a fraction of a pixel. The leftover shows as
+  // paper, reading as a slightly wider quiet zone.
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: var(--qr-radius);
+  background: var(--qr-paper);
+  cursor: pointer;
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Swapping the pair is the whole of the inverted state.
+.root.inverted {
+  --qr-ink: var(--color-bg);
+  --qr-paper: var(--color-fg);
+}
+
+// The painted box. `relative` anchors the logo overlay — the one internal-anchor
+// exception Rule 4 allows; it lives here rather than on `.root` so the overlay's
+// percentage size resolves against the SYMBOL, not against the button.
+.frame {
+  position: relative;
+  display: block;
+  max-width: 100%;
+}
+
+.svg {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: inherit;
+
+  // Forced-colors mode would override ink and paper with the same pair of
+  // system colours and flatten the symbol. For a QR code that is not "looks
+  // different", it is "does not scan" — the contrast IS the content.
+  forced-color-adjust: none;
+}
+
+.paper {
+  fill: var(--qr-paper);
+}
+
+.ink {
+  fill: var(--qr-ink);
+}
+
+// The mark is a CSS alpha mask filled with the current ink, so it recolours
+// with the theme AND with the inverted state. `--qr-logo-src` / `--qr-logo-size`
+// are set inline by the component.
+.logo {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: var(--qr-logo-size, 0);
+  aspect-ratio: 1;
+  translate: -50% -50%;
+  background: var(--qr-ink);
+  mask-image: var(--qr-logo-src, none);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+}
+
+// Compound selector so it wins over `.root` regardless of source order.
+.root.error {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 1;
+  padding: var(--qr-error-padding);
+  background: var(--qr-error-bg);
+  color: var(--qr-error-fg);
+  font-size: var(--qr-error-font-size);
+  text-align: center;
+
+  // The plate's content is the consumer's name plus the message, and a name
+  // that is a URL or a bare ID is one unbreakable token — the default
+  // `overflow-wrap: normal` runs it straight out of the plate sideways.
+  // No `min-height` and no `overflow` here on purpose: `aspect-ratio` with an
+  // `auto` min-height already gives the box a content-based floor, so the
+  // square is a minimum and a wrapped name grows the plate instead of
+  // spilling. Pinning `min-height` to anything explicit REPLACES that
+  // automatic floor and reintroduces the vertical overflow.
+  overflow-wrap: anywhere;
+  cursor: default;
+}

package/src/components/QrCode/QrCode.tokens.scss

@@ -0,0 +1,17 @@
+// QrCode.tokens.scss — Component-scoped tokens for <QrCode>. Ink and paper
+// follow the theme; the `.inverted` class swaps the pair, which is why they are
+// a pair of aliases rather than fixed values. Symbol geometry (the 4-module
+// quiet zone, the punch side) is computed from the module count, not tokenised.
+:root {
+  // The code itself. Swapped wholesale by `.inverted`.
+  --qr-ink: var(--color-fg);
+  --qr-paper: var(--color-bg);
+
+  --qr-radius: var(--radius-sm);
+
+  // Error plate — shown when the value is empty or too long to encode.
+  --qr-error-bg: var(--color-bg-muted);
+  --qr-error-fg: var(--color-fg);
+  --qr-error-font-size: var(--font-size-sm);
+  --qr-error-padding: var(--space-3);
+}

package/src/components/QrCode/QrCode.tsx

@@ -0,0 +1,233 @@
+import {
+  forwardRef,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type CSSProperties,
+  type Ref,
+} from 'react';
+import clsx from 'clsx';
+import { mergeRefs } from '../_internal/refs';
+import { useTranslation } from '../../i18n';
+import { cssUrl, encodeQr, snapWidth, type QrCodeLevel } from './qr';
+import styles from './QrCode.module.scss';
+
+export type { QrCodeLevel };
+
+/** Share of the punch-out the mark fills, leaving paper around it. */
+const LOGO_FILL = 0.72;
+
+export interface QrCodeProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'value' | 'type'
+> {
+  /**
+   * The string to encode — a URL, an ID, a vCard. Encoded as UTF-8, so any
+   * script works.
+   *
+   * An empty string, or one past the largest symbol's capacity at the chosen
+   * `level` (~1273 bytes at `'H'`, ~2953 at `'L'`), renders a **disabled**
+   * button carrying a localized "unavailable" message instead of a code. It
+   * never throws — a long CRM field cannot white-screen a page.
+   */
+  value: string;
+  /**
+   * URL of a **single-colour** SVG to place in the centre. It is used as a CSS
+   * alpha mask and filled with the code's current ink, so it recolours itself
+   * in both themes and in the inverted state — the file's own colours are
+   * discarded. Full-colour artwork and photographs are not supported.
+   *
+   * Setting this also raises the default `level` to `'H'`, because the
+   * punch-out destroys modules outright.
+   */
+  logo?: string;
+  /**
+   * Error-correction level — how much damage the symbol survives. `'L'` ~7%,
+   * `'M'` ~15%, `'Q'` ~25%, `'H'` ~30%. Higher levels need a larger symbol for
+   * the same data. Defaults to `'H'` when `logo` is set, `'M'` otherwise.
+   */
+  level?: QrCodeLevel;
+}
+
+/**
+ * Snap the painted width down to a whole number of DEVICE pixels per module.
+ *
+ * A QR symbol only looks sharp when one module maps to an integer number of
+ * device pixels. It otherwise loses either way: `shape-rendering: crispEdges`
+ * snaps alternate modules to different widths (measured 4.878px/module
+ * rendering as a mix of 4px and 5px — a 20% jitter across the grid), while
+ * default antialiasing keeps the geometry even but spends most of a pixel
+ * blending every edge. Both read as a blurry code.
+ *
+ * So the component measures the box the parent gave it and paints the largest
+ * exact multiple that fits, centred, with the shortfall showing as a slightly
+ * wider quiet zone. The shortfall is up to ONE MODULE — `side / dpr` CSS px,
+ * not a fraction of a pixel — which is why `snapWidth` refuses the trade past
+ * a bounded share of the box.
+ *
+ * Returns `null` when it cannot measure (SSR, jsdom, a zero-width container,
+ * a box too small for even 1px per module) or when snapping would cost more
+ * than `snapWidth`'s budget; callers fall back to fluid `width: 100%` without
+ * `crispEdges`, which is the correct behaviour when the premise does not hold.
+ */
+function useSnappedWidth(side: number): [Ref<HTMLButtonElement>, number | null] {
+  const hostRef = useRef<HTMLButtonElement | null>(null);
+  const [width, setWidth] = useState<number | null>(null);
+  // Tracked in state so a zoom change re-runs the effect and re-subscribes the
+  // media query below to the NEW ratio. Seeded from the real ratio rather than
+  // from 1: starting at 1 made the effect run twice on mount at any other dpr,
+  // and made the FIRST subscription `(resolution: 1dppx)` — a query that never
+  // matches on a 2dppx screen, so the initial zoom listener was dead.
+  const [dpr, setDpr] = useState(() => globalThis.devicePixelRatio || 1);
+
+  useLayoutEffect(() => {
+    const host = hostRef.current;
+    if (!host || side <= 0) return;
+
+    const recompute = () => {
+      const ratio = window.devicePixelRatio || 1;
+      setDpr(ratio);
+      // The arithmetic lives in `snapWidth` so it can be unit-tested directly,
+      // without a stubbed layout, across ratios jsdom cannot report.
+      setWidth(snapWidth(host.getBoundingClientRect().width, side, ratio));
+    };
+
+    recompute();
+
+    const cleanups: Array<() => void> = [];
+
+    if (typeof ResizeObserver !== 'undefined') {
+      const observer = new ResizeObserver(recompute);
+      observer.observe(host);
+      cleanups.push(() => observer.disconnect());
+    }
+
+    // Zooming changes devicePixelRatio WITHOUT changing our CSS width, so the
+    // ResizeObserver never fires for it. This does.
+    if (typeof window.matchMedia === 'function') {
+      const query = window.matchMedia(`(resolution: ${dpr}dppx)`);
+      query.addEventListener('change', recompute);
+      cleanups.push(() => query.removeEventListener('change', recompute));
+    }
+
+    return () => {
+      for (const cleanup of cleanups) cleanup();
+    };
+  }, [side, dpr]);
+
+  return [hostRef, width];
+}
+
+/**
+ * A scannable, theme-following QR code that fills its container; clicking swaps ink and paper.
+ * @see docs/components/QrCode.md
+ */
+export const QrCode = forwardRef<HTMLButtonElement, QrCodeProps>(function QrCode(
+  { value, logo, level, className, style, onClick, title, 'aria-label': ariaLabel, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  const [inverted, setInverted] = useState(false);
+
+  // One truthiness rule for the whole component: an empty string is not a logo,
+  // not a name and not a tooltip. Splitting this across `logo ?` and
+  // `logo !== undefined` punches a hole into a level-M symbol with nothing to
+  // fill it; the same slip on the name is below, at the `||` fallbacks.
+  const hasLogo = Boolean(logo);
+
+  const resolvedLevel: QrCodeLevel = level ?? (hasLogo ? 'H' : 'M');
+  const matrix = useMemo(() => encodeQr(value, resolvedLevel), [value, resolvedLevel]);
+
+  // Called unconditionally, before the error branch returns. `0` parks the hook
+  // when there is no symbol to measure for.
+  const [hostRef, snappedWidth] = useSnappedWidth(matrix?.side ?? 0);
+  // Memoized so the merged callback ref keeps its identity across renders —
+  // a fresh function would detach and reattach the node on every render.
+  const rootRef = useMemo(() => mergeRefs(ref, hostRef), [ref, hostRef]);
+
+  // {...props} first so the ARIA contract below cannot be clobbered — the
+  // component owns `type`, `aria-pressed` and the toggle. `aria-label` and
+  // `title` are destructured out instead, so the consumer's value is a
+  // FALLBACK rather than something the spread order silently eats.
+  if (matrix === null) {
+    return (
+      <button
+        {...props}
+        ref={rootRef}
+        type="button"
+        disabled
+        className={clsx(styles.root, styles.error, className)}
+        style={style}
+        title={title}
+      >
+        {/* The consumer's name goes in as CONTENT, not as a competing
+            aria-label: name-from-content then reads "<name> — <message>", so a
+            browse-mode user can tell WHICH code failed without hearing the
+            message twice. */}
+        {ariaLabel ? `${ariaLabel} — ${t('qrCode.error')}` : t('qrCode.error')}
+      </button>
+    );
+  }
+
+  const { side, path, punch } = matrix;
+  const offset = (side - punch) / 2;
+
+  const logoVars = logo
+    ? ({
+        '--qr-logo-src': cssUrl(logo),
+        '--qr-logo-size': `${((punch * LOGO_FILL) / side) * 100}%`,
+      } as CSSProperties)
+    : undefined;
+
+  return (
+    <button
+      {...props}
+      ref={rootRef}
+      type="button"
+      aria-pressed={inverted}
+      // `||`, not `??`, on both: `aria-label={row.name ?? ''}` is ordinary
+      // consumer code, and an empty aria-label does not remove the name — it
+      // drops the computation through to `title`, making the invert hint the
+      // name. `title=""` likewise means "no tooltip", not "empty tooltip".
+      aria-label={ariaLabel || t('qrCode.label')}
+      // `title` with an aria-label present is exposed as the DESCRIPTION, not
+      // the name — so it explains what pressing does without touching the
+      // name-exact contract. Doubles as a tooltip for sighted mouse users.
+      title={title || t('qrCode.invertHint')}
+      className={clsx(styles.root, inverted && styles.inverted, className)}
+      style={{ ...logoVars, ...style }}
+      onClick={(event) => {
+        setInverted((current) => !current);
+        onClick?.(event);
+      }}
+    >
+      {/* The painted box, up to one module narrower than the button so the
+          symbol lands on an exact module grid. It also anchors the logo
+          overlay, whose size is a percentage of the SYMBOL — not of the
+          button, which is why the anchor moved here. */}
+      <span className={styles.frame} style={{ width: snappedWidth ?? '100%' }}>
+        <svg
+          className={styles.svg}
+          viewBox={`0 0 ${side} ${side}`}
+          // `crispEdges` ONLY once the width is snapped. Unsnapped it is
+          // actively worse than antialiasing: it rounds each module's edges to
+          // the pixel grid independently, so adjacent modules come out
+          // different widths. Snapped, every module is the same whole number of
+          // device pixels and the symbol is pixel-exact.
+          shapeRendering={snappedWidth === null ? undefined : 'crispEdges'}
+          aria-hidden="true"
+          focusable="false"
+        >
+          <rect className={styles.paper} width={side} height={side} />
+          <path className={styles.ink} d={path} />
+          {hasLogo && (
+            <rect className={styles.paper} x={offset} y={offset} width={punch} height={punch} />
+          )}
+        </svg>
+        {hasLogo && <span className={styles.logo} aria-hidden="true" />}
+      </span>
+    </button>
+  );
+});

package/src/components/QrCode/index.ts

@@ -0,0 +1,2 @@
+export { QrCode } from './QrCode';
+export type { QrCodeProps, QrCodeLevel } from './QrCode';

package/src/components/QrCode/qr.ts

@@ -0,0 +1,161 @@
+import qrcode from 'qrcode-generator';
+
+/**
+ * Error-correction level — how much of the symbol can be destroyed and still
+ * decode. `'L'` ~7%, `'M'` ~15%, `'Q'` ~25%, `'H'` ~30%.
+ */
+export type QrCodeLevel = 'L' | 'M' | 'Q' | 'H';
+
+/** Quiet-zone width in modules. Four is the ISO/IEC 18004 minimum. */
+const QUIET = 4;
+
+/**
+ * The share of the symbol's WIDTH the centre punch-out occupies.
+ *
+ * Note the dimensions: level `'H'`'s ~30% recovery budget is a fraction of
+ * codewords, i.e. of AREA, so a width ratio is not directly comparable to it.
+ * After the odd-rounding below the realised width peaks at 28%, which is 7.8%
+ * of the area — nowhere near the limit. The real constraint on this number is
+ * visual, not arithmetic: bigger than about a quarter of the width and the
+ * mark stops reading as a mark in a code and starts reading as a hole punched
+ * through one.
+ */
+const PUNCH_RATIO = 0.24;
+
+/**
+ * UTF-8 bytes, re-expressed as a latin1 string.
+ *
+ * `qrcode-generator`'s default `stringToBytes` is `s.charCodeAt(i) & 0xff`,
+ * which silently truncates every code point above U+00FF — `'Привет'` encodes
+ * to garbage that still scans. Pre-encoding here turns that truncation into an
+ * identity function, because every char we hand it is already a single byte.
+ *
+ * The usual fix, assigning `qrcode.stringToBytes = …`, is shared mutable state
+ * on a module-level singleton: it would reach every other consumer of the
+ * package inside the host app. This stays local.
+ */
+export function toByteString(value: string): string {
+  return Array.from(new TextEncoder().encode(value), (byte) => String.fromCharCode(byte)).join('');
+}
+
+/**
+ * Characters that would terminate a CSS `url("…")` early. Includes `\f`
+ * (U+000C FORM FEED): CSS input preprocessing (CSS Syntax Level 3 §3.3)
+ * converts every form feed to a line feed before tokenizing, so it is a
+ * newline for this purpose and closes the same breakout as `\n` and `\r`.
+ */
+const CSS_URL_UNSAFE = /["'()\\\n\r\f]/g;
+
+/**
+ * Wrap a consumer-supplied URL in a CSS `url("…")`, percent-encoding anything
+ * that could break out of the declaration. React does not sanitise custom
+ * properties, so this is a trust boundary.
+ *
+ * `encodeURI` is the wrong tool: it double-encodes `%` in already-encoded URLs
+ * and in `data:` URIs, which is most of what a logo is.
+ */
+export function cssUrl(src: string): string {
+  const safe = src.replace(
+    CSS_URL_UNSAFE,
+    (char) => `%${char.charCodeAt(0).toString(16).padStart(2, '0')}`,
+  );
+  return `url("${safe}")`;
+}
+
+/** Geometry for one encoded symbol, in module units. */
+export interface QrMatrix {
+  /** `viewBox` side — the module count plus both quiet zones. */
+  side: number;
+  /** A single SVG path covering every dark module, quiet-zone offset applied. */
+  path: string;
+  /** Side of the centred logo punch-out. Always odd, so it stays on module boundaries. */
+  punch: number;
+}
+
+/**
+ * Encode `value` and flatten it to SVG geometry. Returns `null` when there is
+ * nothing to encode (empty value) or the value exceeds the largest version at
+ * this level — both are the caller's error branch, never a throw.
+ */
+export function encodeQr(value: string, level: QrCodeLevel): QrMatrix | null {
+  if (value === '') return null;
+
+  try {
+    const qr = qrcode(0, level); // 0 = pick the smallest version that fits
+    qr.addData(toByteString(value)); // always Byte mode; addData has no auto-detection
+    qr.make();
+
+    const count = qr.getModuleCount();
+    let path = '';
+    for (let row = 0; row < count; row += 1) {
+      for (let col = 0; col < count; col += 1) {
+        if (qr.isDark(row, col)) {
+          path += `M${col + QUIET} ${row + QUIET}h1v1h-1z`;
+        }
+      }
+    }
+
+    // `| 1` rounds up to the next odd number. The module count is always odd,
+    // so an odd punch keeps `(side - punch) / 2` integral. FLOOR, not ceil:
+    // double-rounding up puts a v1 symbol's punch at 33% of its width. Both
+    // variants sit inside level H's budget on area (7.8% flooring, ~11%
+    // ceiling, against ~30%) — flooring wins on looks, not on arithmetic. It
+    // caps the width at 28% for every version.
+    //
+    // Boundary the area maths does NOT cover: from version 7 up (59 bytes at
+    // level 'H', which is the default whenever `logo` is set) there is a centre
+    // alignment pattern, and the punch lands on it. Reed–Solomon protects data
+    // and ECC codewords, not function patterns, so no amount of budget buys
+    // that back. Decoders in practice extrapolate the module grid from the
+    // finder and timing patterns — which is why every commercial logo-QR
+    // generator gets away with it — but it is extrapolation, not recovery, and
+    // nothing here would notice it breaking. The playground demo carries an
+    // over-v7 logo example so the case is scannable by hand.
+    return { side: count + QUIET * 2, path, punch: Math.floor(count * PUNCH_RATIO) | 1 };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How much of the available width snapping may give up.
+ *
+ * Rounding down to a whole number of device pixels per module costs up to ONE
+ * MODULE — `side / dpr` CSS px, not a fraction of a pixel — and that is a
+ * share of the box, not a constant: at 41 modules and dpr 1 a 320px box loses
+ * 10%, a 200px box 18%, a 120px box 32%; a 177-module symbol in a 320px box
+ * loses 45%.
+ *
+ * A QR code exists to be scanned, and whether a camera resolves one depends on
+ * the ABSOLUTE size of a module, not on whether its edges are crisp. Unbounded
+ * snapping therefore shrinks the symbol hardest exactly where it is already
+ * tightest, and can push it under the ~100px floor the component's own docs
+ * warn about. An eighth is the line: past that, a bigger antialiased code
+ * beats a smaller pixel-exact one.
+ */
+const MAX_SNAP_SHORTFALL = 1 / 8;
+
+/**
+ * The largest painted width, in CSS pixels, that gives every module a whole
+ * number of DEVICE pixels — or `null` when that is impossible or too costly.
+ *
+ * A QR symbol only looks sharp at an integer scale. Off it, both rendering
+ * modes lose: `shape-rendering: crispEdges` rounds each module's edges to the
+ * pixel grid independently, so neighbours come out different widths (a measured
+ * 4.878px/module rendered as a mix of 4px and 5px), while default antialiasing
+ * keeps the geometry even but spends most of a pixel blending every edge.
+ *
+ * Returns `null` when there is nothing to measure (`available` of 0, as SSR and
+ * jsdom report), when the box cannot fit even one device pixel per module, or
+ * when the snap would cost more than `MAX_SNAP_SHORTFALL` of the width. In all
+ * three the caller should fall back to fluid width WITHOUT `crispEdges` —
+ * unsnapped, `crispEdges` is the worse of the two.
+ */
+export function snapWidth(available: number, side: number, dpr: number): number | null {
+  if (!(available > 0) || !(side > 0) || !(dpr > 0)) return null;
+  const scale = Math.floor((available * dpr) / side);
+  if (scale < 1) return null;
+
+  const painted = (side * scale) / dpr;
+  return available - painted <= available * MAX_SNAP_SHORTFALL ? painted : null;
+}