@zentauri-ui/zentauri-components 2.2.2 → 2.3.1

package/src/ui/qr-code/qr-code-base.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import QRCode from "qrcode";
+
+import { cn } from "../../lib/utils";
+
+import type { QrCodeBaseProps } from "./types";
+import {
+  qrCodeCanvasWrapperVariants,
+  qrCodeCaptionVariants,
+  qrCodeVariants,
+} from "./variants";
+
+/**
+ * QrCodeBase renders a QR code onto a `<canvas>` element using the `qrcode`
+ * npm package. It is the static (non-animated) implementation of the public
+ * `QrCode` component.
+ *
+ * --- Props ---
+ *
+ * - `value` — The string to encode. When empty/falsy the canvas is cleared.
+ * - `canvasSize` — Pixel dimensions of the canvas (default: 200). Both width
+ *   and height are set to this value, producing a square QR code.
+ * - `level` — Error correction level (`"L"` | `"M"` | `"Q"` | `"H"`). Higher
+ *   levels survive more visual damage but hold less data.
+ * - `bgColor` / `fgColor` — Background and foreground colours passed to the
+ *   underlying `QRCode.toCanvas` options.
+ * - `margin` — Quiet-zone width in QR modules (default: 2). Passed directly
+ *   to the `qrcode` library.
+ * - `caption` — Optional label rendered below the QR code.
+ * - `ref` — React 19 ref forwarded to the root `<div>` element.
+ * - `className` / `...rest` — Spread onto the root `<div>` for layout or
+ *   style overrides.
+ *
+ * --- Rendering lifecycle ---
+ *
+ * A `useEffect` watches `[value, canvasSize, level, bgColor, fgColor, margin]`.
+ * On every change it:
+ *   1. Grabs the canvas element from the ref.
+ *   2. If `value` is empty, clears the canvas with `ctx.clearRect` so a stale
+ *      QR code doesn't persist.
+ *   3. Otherwise calls `QRCode.toCanvas()` which draws the QR pattern
+ *       asynchronously (via callback) onto the canvas element.
+ *
+ * The outer `<div>` uses design-system variants (`qrCodeVariants`) for
+ * consistent theming and carries `data-slot="qr-code"` for scoped styling and
+ * testing.
+ *
+ * --- Accessibility ---
+ *
+ * The `<canvas>` has an `aria-label` describing it as a "QR code for {value}".
+ * Screen readers will announce the purpose, though the raw value is exposed
+ * (consider truncating for secrets).
+ */
+export function QrCodeBase({
+  value,
+  canvasSize = 200,
+  level = "M",
+  bgColor = "#ffffff",
+  fgColor = "#000000",
+  margin = 2,
+  caption,
+  className,
+  ref,
+  ...rest
+}: QrCodeBaseProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  /**
+   * Draw the QR pattern whenever input props change.
+   *
+   * The conditional `if (!value)` branch handles the "clear" case: when the
+   * user deletes the input text, we clear the canvas so a stale QR code isn't
+   * displayed. Without this the old QR pattern persists because
+   * `QRCode.toCanvas` is never called (it returns early for empty values).
+   */
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    if (!value) {
+      const ctx = canvas.getContext("2d");
+      if (ctx) {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+      }
+      return;
+    }
+
+    QRCode.toCanvas(
+      canvas,
+      value,
+      {
+        width: canvasSize,
+        margin,
+        color: {
+          dark: fgColor,
+          light: bgColor,
+        },
+        errorCorrectionLevel: level,
+      },
+      (error) => {
+        if (error) {
+          console.error("QR Code generation error:", error);
+        }
+      },
+    );
+  }, [value, canvasSize, level, bgColor, fgColor, margin]);
+
+  /**
+   * The root element is a `<div>` (not the `<canvas>`) so consumers can apply
+   * layout classes, the caption sits outside the canvas, and the component
+   * plays well with flex/grid containers.
+   *
+   * Nested structure:
+   *   <div data-slot="qr-code">          ← root (ref, className, ...rest)
+   *     <div>                            ← canvas wrapper (theme rounding/overflow)
+   *       <canvas data-slot="qr-code-canvas" />
+   *     </div>
+   *     {caption && <span data-slot="qr-code-caption" />}
+   *   </div>
+   */
+  return (
+    <div
+      ref={ref}
+      data-slot="qr-code"
+      className={cn(qrCodeVariants(), className)}
+      {...rest}
+    >
+      <div className={qrCodeCanvasWrapperVariants()}>
+        <canvas
+          ref={canvasRef}
+          width={canvasSize}
+          height={canvasSize}
+          data-slot="qr-code-canvas"
+          className="block h-auto max-w-full"
+          aria-label={`QR code for ${value}`}
+        />
+      </div>
+      {caption ? (
+        <span data-slot="qr-code-caption" className={qrCodeCaptionVariants()}>
+          {caption}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+QrCodeBase.displayName = "QrCode";

package/src/ui/qr-code/qr-code.test.tsx

@@ -0,0 +1,58 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { QrCode } from "./qr-code";
+
+vi.mock("qrcode", () => ({
+  default: {
+    toCanvas: vi.fn(
+      (
+        _canvas: HTMLCanvasElement,
+        _value: string,
+        _opts: unknown,
+        cb?: (err?: Error) => void,
+      ) => {
+        cb?.();
+      },
+    ),
+  },
+}));
+
+describe("QrCode", () => {
+  it("should expose displayName", () => {
+    expect(QrCode.displayName).toBe("QrCode");
+  });
+
+  it("should stamp data-slot", () => {
+    render(<QrCode value="https://example.com" />);
+    const root = document.querySelector('[data-slot="qr-code"]');
+    expect(root).toBeTruthy();
+    expect(root?.getAttribute("data-slot")).toBe("qr-code");
+  });
+
+  it("should render canvas element", () => {
+    render(<QrCode value="https://example.com" />);
+    const canvas = document.querySelector('[data-slot="qr-code-canvas"]');
+    expect(canvas).toBeTruthy();
+  });
+
+  it("should render with caption", () => {
+    render(<QrCode value="test" caption="Scan me" />);
+    expect(screen.getByText("Scan me")).toBeInTheDocument();
+  });
+
+  it("should forward ref", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<QrCode value="test" ref={ref} />);
+    expect(ref.current?.getAttribute("data-slot")).toBe("qr-code");
+  });
+
+  it("should apply custom className", () => {
+    const { container } = render(
+      <QrCode value="test" className="custom-class" />,
+    );
+    const root = container.querySelector('[data-slot="qr-code"]');
+    expect(root?.className).toMatch(/custom-class/);
+  });
+});

package/src/ui/qr-code/qr-code.tsx

@@ -0,0 +1,2 @@
+// qr-code.tsx — default static entry (no framer-motion)
+export { QrCodeBase as QrCode } from "./qr-code-base";

package/src/ui/qr-code/types.ts

@@ -0,0 +1,22 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+export type QrCodeLevel = "L" | "M" | "Q" | "H";
+
+export interface QrCodeBaseProps extends ComponentPropsWithRef<"div"> {
+  value: string;
+  canvasSize?: number;
+  level?: QrCodeLevel;
+  bgColor?: string;
+  fgColor?: string;
+  margin?: number;
+  caption?: ReactNode;
+}
+
+export type QrCodeProps = QrCodeBaseProps;
+
+export const QR_CODE_LEVEL_LABELS: Record<QrCodeLevel, string> = {
+  L: "Low (7%)",
+  M: "Medium (15%)",
+  Q: "Quartile (25%)",
+  H: "High (30%)",
+} as const;

package/src/ui/qr-code/variants.ts

@@ -0,0 +1,11 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiQrCodeBase,
+  zuiQrCodeCanvasWrapper,
+  zuiQrCodeCaptionBase,
+} from "../../design-system/qr-code";
+
+export const qrCodeVariants = cva(zuiQrCodeBase);
+export const qrCodeCanvasWrapperVariants = cva(zuiQrCodeCanvasWrapper);
+export const qrCodeCaptionVariants = cva(zuiQrCodeCaptionBase);

package/src/ui/qr-scanner/index.ts

@@ -0,0 +1,17 @@
+"use client";
+
+export { QrScanner } from "./qr-scanner";
+export type {
+  QrScannerBaseProps,
+  QrScannerProps,
+  QrScannerRef,
+  QrScannerVariantProps,
+} from "./types";
+export {
+  qrScannerFallbackVariants,
+  qrScannerOverlayVariants,
+  qrScannerStatusVariants,
+  qrScannerVariants,
+  qrScannerVideoVariants,
+  qrScannerViewfinderVariants,
+} from "./variants";