tempest-react-sdk 0.26.1 → 0.27.0

package/README.md

@@ -149,7 +149,7 @@ Via `package.json`:
 ```json
 {
   "dependencies": {
-    "tempest-react-sdk": "^0.26.0"
+    "tempest-react-sdk": "^0.27.0"
   }
 }
 ```

package/bin/lib/doctor/doctor.e2e.test.mjs

@@ -0,0 +1,201 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "tempest.mjs");
+
+let root;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-doctor-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/** Write a file under the fixture, creating parent directories. */
+function write(rel, contents) {
+    const path = join(root, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, typeof contents === "string" ? contents : JSON.stringify(contents));
+}
+
+/** Fake an installed package so `installedVersion` finds it. */
+function installed(name, version, extra = {}) {
+    write(`node_modules/${name}/package.json`, { name, version, ...extra });
+}
+
+/**
+ * Run the real CLI in the fixture directory.
+ *
+ * A subprocess rather than an imported function on purpose: `doctor` reads
+ * `process.cwd()` and reports through the exit code, and the exit code is the part
+ * that matters most — it decides whether a project "fails" the audit. Only running
+ * it the way a user does tests that.
+ */
+function doctor() {
+    const result = spawnSync(process.execPath, [CLI, "doctor"], {
+        cwd: root,
+        encoding: "utf8",
+        env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+    });
+    return { code: result.status, out: `${result.stdout}${result.stderr}` };
+}
+
+/** A plain, healthy React + Vite app that has never heard of the SDK. */
+function thirdPartyApp() {
+    write("package.json", {
+        name: "app-de-terceiro",
+        type: "module",
+        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0" },
+        devDependencies: { vite: "^7.0.0", "@vitejs/plugin-react": "^5.0.0", eslint: "^9.0.0" },
+    });
+    write("tsconfig.json", {
+        compilerOptions: { strict: true, jsx: "react-jsx", moduleResolution: "bundler" },
+    });
+    write(
+        "vite.config.ts",
+        'import { defineConfig } from "vite";\nexport default defineConfig({});',
+    );
+    write("src/App.tsx", "export const App = () => null;");
+    write("package-lock.json", "{}");
+    write("eslint.config.js", "export default [];");
+    installed("react", "19.0.0");
+    installed("react-dom", "19.0.0");
+    installed("vite", "7.0.0");
+    installed("@vitejs/plugin-react", "5.0.0");
+    installed("eslint", "9.0.0");
+    installed("prettier", "3.0.0");
+    installed(".bin/eslint", "0.0.0");
+}
+
+describe("tempest doctor — a third-party project that does not use the SDK", () => {
+    beforeEach(thirdPartyApp);
+
+    it("does not fail the audit just for not having the SDK", () => {
+        const { code, out } = doctor();
+        expect(out).toContain("tempest-react-sdk not installed");
+        expect(out).toContain("generic React/Vite health only");
+        expect(code).toBe(0);
+    });
+
+    it("never reports the missing SDK as a problem", () => {
+        const { out } = doctor();
+        expect(out).not.toMatch(/✗.*tempest-react-sdk/);
+    });
+
+    it("drops the SDK's own conventions from the report", () => {
+        const { out } = doctor();
+        // The `@/*` alias and `createViteConfig` are preferences, not health.
+        expect(out).not.toContain('tsconfig "@/*" alias');
+        expect(out).not.toContain("not using createViteConfig");
+        // The stylesheet is only *demanded* of an SDK project; the adoption hint at
+        // the end still mentions it, which is the point of that section.
+        expect(out).not.toContain('add import "tempest-react-sdk/styles.css"');
+    });
+
+    it("does not demand a src/main.tsx it has no reason to expect", () => {
+        const { out } = doctor();
+        expect(out).not.toContain("app entry");
+    });
+
+    it("explains moduleResolution without naming SDK subpaths", () => {
+        write("tsconfig.json", { compilerOptions: { strict: true, jsx: "react-jsx" } });
+        const { out } = doctor();
+        expect(out).toContain("moduleResolution");
+        expect(out).not.toContain("tempest-react-sdk/br");
+        expect(out).toContain("subpath exports");
+    });
+
+    it("closes with how to adopt, so the audit is not a dead end", () => {
+        const { out } = doctor();
+        expect(out).toContain("Adopting the SDK (optional)");
+        expect(out).toContain("npm i tempest-react-sdk");
+        expect(out).toContain("not all-or-nothing");
+    });
+});
+
+describe("tempest doctor — generic findings still surface", () => {
+    it("flags a missing lockfile", () => {
+        thirdPartyApp();
+        rmSync(join(root, "package-lock.json"));
+        expect(doctor().out).toContain("no lockfile");
+    });
+
+    it("flags a missing @vitejs/plugin-react", () => {
+        thirdPartyApp();
+        rmSync(join(root, "node_modules", "@vitejs", "plugin-react"), {
+            recursive: true,
+            force: true,
+        });
+        expect(doctor().out).toContain("@vitejs/plugin-react");
+    });
+
+    it("flags declared dependencies that are not installed", () => {
+        thirdPartyApp();
+        rmSync(join(root, "node_modules", "react"), { recursive: true, force: true });
+        expect(doctor().out).toMatch(/dependency\(ies\) not installed/);
+    });
+
+    it("flags env vars that Vite will not expose", () => {
+        thirdPartyApp();
+        write("src/api.ts", "export const url = import.meta.env.API_URL;");
+        expect(doctor().out).toContain("client env without VITE_ prefix");
+    });
+
+    it("still fails on a genuinely broken project", () => {
+        write("package.json", { name: "broken", dependencies: {} });
+        const { code, out } = doctor();
+        expect(out).toContain("react + react-dom present");
+        expect(code).toBe(1);
+    });
+});
+
+describe("tempest doctor — a project that does use the SDK", () => {
+    beforeEach(() => {
+        thirdPartyApp();
+        write("package.json", {
+            name: "sdk-app",
+            type: "module",
+            dependencies: {
+                "tempest-react-sdk": "^0.26.1",
+                react: "^19.0.0",
+                "react-dom": "^19.0.0",
+            },
+        });
+        installed("tempest-react-sdk", "0.26.1", { dependencies: { "lucide-react": "^1.26.0" } });
+        installed("lucide-react", "1.26.0");
+    });
+
+    it("checks the SDK's conventions again", () => {
+        write("tsconfig.json", {
+            compilerOptions: { strict: true, jsx: "react-jsx", moduleResolution: "bundler" },
+        });
+        const { out } = doctor();
+        expect(out).toContain('tsconfig "@/*" alias');
+    });
+
+    it("asks for the stylesheet import, which is a real defect without it", () => {
+        write("src/main.tsx", "export const main = 1;");
+        expect(doctor().out).toContain("styles.css");
+    });
+
+    it("omits the adoption hint — it has already adopted", () => {
+        expect(doctor().out).not.toContain("Adopting the SDK (optional)");
+    });
+
+    it("warns when the SDK is installed but undeclared", () => {
+        write("package.json", {
+            name: "sdk-app",
+            dependencies: { react: "^19.0.0", "react-dom": "^19.0.0" },
+        });
+        const { out, code } = doctor();
+        expect(out).toContain("tempest-react-sdk not in dependencies");
+        // Undeclared-but-present is a warning, not a blocking failure.
+        expect(code).toBe(0);
+    });
+});

package/bin/tempest.mjs

@@ -312,16 +312,45 @@ function doctor() {
     checks.push(["section", "Project"]);
     checks.push(["ok", "package.json found"]);
     const sdkInstalled = installedVersion("tempest-react-sdk");
-    checks.push(
-        deps["tempest-react-sdk"]
-            ? ["ok", "tempest-react-sdk in dependencies", deps["tempest-react-sdk"]]
-            : ["fail", "tempest-react-sdk in dependencies", "npm install tempest-react-sdk"],
-    );
-    checks.push(
-        sdkInstalled
-            ? ["ok", "tempest-react-sdk installed", `v${sdkInstalled}`]
-            : ["fail", "tempest-react-sdk installed", "run npm install"],
-    );
+
+    /**
+     * Whether this project has adopted the SDK.
+     *
+     * When it has not, `doctor` runs in **generic mode**: the checks that only make
+     * sense once you use the SDK (its `@/*` alias, `createViteConfig`, the
+     * `styles.css` import, its optional peers) drop out, and not having the SDK is
+     * reported as information rather than as a defect.
+     *
+     * Without this the tool is useless on the exact project it should help most —
+     * somebody's existing app, being evaluated. It reported two hard failures for the
+     * single fact "you have not installed this yet", exited non-zero, and buried the
+     * findings that *were* actionable (no lockfile, no plugin-react, no linter) among
+     * warnings that were really just the SDK's own conventions.
+     */
+    const usesSdk = Boolean(deps["tempest-react-sdk"] || sdkInstalled);
+
+    if (usesSdk) {
+        checks.push(
+            deps["tempest-react-sdk"]
+                ? ["ok", "tempest-react-sdk in dependencies", deps["tempest-react-sdk"]]
+                : [
+                      "warn",
+                      "tempest-react-sdk not in dependencies",
+                      `installed as v${sdkInstalled} but undeclared — add it to package.json`,
+                  ],
+        );
+        checks.push(
+            sdkInstalled
+                ? ["ok", "tempest-react-sdk installed", `v${sdkInstalled}`]
+                : ["fail", "tempest-react-sdk installed", "run npm install"],
+        );
+    } else {
+        checks.push([
+            "info",
+            "tempest-react-sdk not installed",
+            "checking generic React/Vite health only — `npm i tempest-react-sdk` to adopt it",
+        ]);
+    }
     const reactV = installedVersion("react");
     checks.push(
         deps.react && deps["react-dom"]
@@ -438,11 +467,15 @@ function doctor() {
     if (tsc) {
         checks.push(["section", "TypeScript"]);
         const co = tsc.compilerOptions;
-        checks.push(
-            co.paths?.["@/*"]
-                ? ["ok", 'tsconfig "@/*" alias']
-                : ["warn", 'tsconfig "@/*" alias', 'add "paths": { "@/*": ["./src/*"] }'],
-        );
+        // The `@/*` alias is the SDK's convention, not a health property: a project
+        // that has not adopted the SDK is not wrong for lacking it.
+        if (usesSdk) {
+            checks.push(
+                co.paths?.["@/*"]
+                    ? ["ok", 'tsconfig "@/*" alias']
+                    : ["warn", 'tsconfig "@/*" alias', 'add "paths": { "@/*": ["./src/*"] }'],
+            );
+        }
         const mr = String(co.moduleResolution ?? "").toLowerCase();
         checks.push(
             ["bundler", "node16", "nodenext"].includes(mr)
@@ -450,7 +483,9 @@ function doctor() {
                 : [
                       "warn",
                       `moduleResolution: ${co.moduleResolution ?? "(unset)"}`,
-                      'use "bundler" — otherwise subpath types (tempest-react-sdk/br, /charts…) won\'t resolve',
+                      usesSdk
+                          ? 'use "bundler" — otherwise subpath types (tempest-react-sdk/br, /charts…) won\'t resolve'
+                          : 'use "bundler" — a bundled app needs it for any package that ships subpath exports',
                   ],
         );
         checks.push(
@@ -491,11 +526,21 @@ function doctor() {
     if (!viteCfg) {
         checks.push(["warn", "vite config", "no vite.config.* found"]);
     } else {
-        checks.push(
-            fileIncludes(join(ROOT, viteCfg), "createViteConfig")
-                ? ["ok", `${viteCfg} uses createViteConfig`]
-                : ["warn", `${viteCfg}`, "not using createViteConfig from tempest-react-sdk/vite"],
-        );
+        // `createViteConfig` is a convenience, not a requirement — only worth
+        // mentioning to a project that already uses the SDK, and even then as info.
+        if (usesSdk) {
+            checks.push(
+                fileIncludes(join(ROOT, viteCfg), "createViteConfig")
+                    ? ["ok", `${viteCfg} uses createViteConfig`]
+                    : [
+                          "info",
+                          `${viteCfg}`,
+                          "not using createViteConfig from tempest-react-sdk/vite — optional",
+                      ],
+            );
+        } else {
+            checks.push(["ok", `${viteCfg} found`]);
+        }
         // React plugin is required for JSX/Fast Refresh in a Vite React app.
         checks.push(
             installedVersion("@vitejs/plugin-react")
@@ -508,14 +553,23 @@ function doctor() {
         );
     }
     const entry = firstExisting(["src/main.tsx", "src/main.ts", "src/index.tsx", "src/index.ts"]);
-    if (entry) {
-        checks.push(
-            fileIncludes(join(ROOT, entry), "tempest-react-sdk/styles.css")
-                ? ["ok", `${entry} imports styles.css`]
-                : ["warn", `${entry}`, 'add import "tempest-react-sdk/styles.css"'],
-        );
-    } else {
-        checks.push(["warn", "app entry", "no src/main.tsx found"]);
+    if (usesSdk) {
+        // Without the stylesheet every component renders unstyled, so for an SDK
+        // project this is a real defect. For anyone else the entry's filename is
+        // their business, not ours.
+        if (entry) {
+            checks.push(
+                fileIncludes(join(ROOT, entry), "tempest-react-sdk/styles.css")
+                    ? ["ok", `${entry} imports styles.css`]
+                    : ["warn", `${entry}`, 'add import "tempest-react-sdk/styles.css"'],
+            );
+        } else {
+            checks.push([
+                "warn",
+                "app entry",
+                "none of src/main.tsx, src/main.ts, src/index.tsx, src/index.ts found — cannot verify the styles.css import",
+            ]);
+        }
     }
     // styles.css should be imported once — duplicates re-inject the whole sheet.
     const stylesImports = (src.match(/tempest-react-sdk\/styles\.css/g) ?? []).length;
@@ -600,6 +654,26 @@ function doctor() {
         checks.push(["ok", "client env vars use the VITE_ prefix"]);
     }
 
+    /*
+     * In generic mode, close with what adoption would actually take. A tool that
+     * audits somebody's project and then says nothing about the next step reads as an
+     * ad for a product they cannot find the door to.
+     */
+    if (!usesSdk) {
+        checks.push(["section", "Adopting the SDK (optional)"]);
+        checks.push(["info", "install", "npm i tempest-react-sdk"]);
+        checks.push([
+            "info",
+            "import the stylesheet once, in your entry",
+            'import "tempest-react-sdk/styles.css"',
+        ]);
+        checks.push([
+            "info",
+            "not all-or-nothing",
+            "one component at a time works — the @/* alias, createViteConfig and the scaffold are all optional",
+        ]);
+    }
+
     return report(checks);
 }
 

package/dist/components/ImageCropper/ImageCropper.cjs

@@ -0,0 +1,2 @@
+const e=require("../../utils/cn.cjs"),t=require("./crop-geometry.cjs"),n=require("./ImageCropper.module.cjs");let r=require("react"),i=require("react/jsx-runtime");var a=12,o=.15;function s({src:s,aspect:c=1,maxZoom:l=4,maxSize:u,outputType:d=`image/png`,outputQuality:f=.92,shape:p=`rect`,onCropChange:m,label:h=`Área de recorte`,className:g,ref:_,...v}){let y=`${(0,r.useId)()}-hint`,b=(0,r.useRef)(null),x=(0,r.useRef)(null),S=(0,r.useRef)(null),[C,w]=(0,r.useState)(null),[T,E]=(0,r.useState)(null),[D,O]=(0,r.useState)({width:0,height:0}),[k,A]=(0,r.useState)(1),[j,M]=(0,r.useState)({x:0,y:0});(0,r.useEffect)(()=>{if(typeof s==`string`){w(s);return}let e=URL.createObjectURL(s);return w(e),()=>URL.revokeObjectURL(e)},[s]),(0,r.useEffect)(()=>{E(null),A(1),M({x:0,y:0})},[C]),(0,r.useEffect)(()=>{let e=b.current;if(!e)return;let t=()=>O({width:e.clientWidth,height:e.clientHeight});if(t(),typeof ResizeObserver>`u`)return;let n=new ResizeObserver(t);return n.observe(e),()=>n.disconnect()},[]);let N=T?t.coverScale(T,D)*k:0,P=(0,r.useMemo)(()=>T?{width:T.width*N,height:T.height*N}:{width:0,height:0},[T,N]),F=(0,r.useCallback)(e=>{M(n=>{let r=t.clampOffset(e,P,D);return r.x===n.x&&r.y===n.y?n:(m?.({zoom:k,offset:r}),r)})},[P,D,m,k]),I=(0,r.useCallback)(e=>{let n=Math.min(l,Math.max(1,e));if(A(n),!T)return;let r=t.coverScale(T,D)*n,i={width:T.width*r,height:T.height*r};M(e=>{let r=t.clampOffset(e,i,D);return m?.({zoom:n,offset:r}),r})},[D,l,T,m]),L=(0,r.useCallback)(()=>{A(1),M({x:0,y:0}),m?.({zoom:1,offset:{x:0,y:0}})},[m]),R=(0,r.useCallback)(async()=>{let e=x.current;if(!e||!T)return null;let n=t.computeCropRect({image:T,frame:D,zoom:k,offset:j});if(n.sWidth<=0||n.sHeight<=0)return null;let r=t.outputSize(n,u),i=document.createElement(`canvas`);i.width=r.width,i.height=r.height;let a=i.getContext(`2d`);return a?(a.drawImage(e,n.sx,n.sy,n.sWidth,n.sHeight,0,0,r.width,r.height),new Promise(e=>{i.toBlob(t=>e(t),d,f)})):null},[D,u,T,j,f,d,k]);(0,r.useImperativeHandle)(_,()=>({crop:R,reset:L}),[R,L]);let z=e=>{T&&(S.current={pointerId:e.pointerId,startX:e.clientX,startY:e.clientY,from:j},e.currentTarget.setPointerCapture?.(e.pointerId))},B=e=>{let t=S.current;!t||t.pointerId!==e.pointerId||F({x:t.from.x+(e.clientX-t.startX),y:t.from.y+(e.clientY-t.startY)})},V=e=>{S.current?.pointerId===e.pointerId&&(S.current=null)},H=e=>{let t=e.shiftKey?a*4:a,n={ArrowLeft:{x:-t,y:0},ArrowRight:{x:t,y:0},ArrowUp:{x:0,y:-t},ArrowDown:{x:0,y:t}}[e.key];if(n){e.preventDefault(),F({x:j.x+n.x,y:j.y+n.y});return}e.key===`+`||e.key===`=`?(e.preventDefault(),I(k+o)):e.key===`-`||e.key===`_`?(e.preventDefault(),I(k-o)):e.key===`0`&&(e.preventDefault(),L())};return(0,i.jsxs)(`div`,{className:e.cn(n.default.wrapper,g),...v,children:[(0,i.jsx)(`div`,{ref:b,className:e.cn(n.default.frame,p===`circle`&&n.default.circle),style:{aspectRatio:String(c)},role:`group`,"aria-label":h,"aria-describedby":y,tabIndex:0,onPointerDown:z,onPointerMove:B,onPointerUp:V,onPointerCancel:V,onKeyDown:H,onWheel:e=>{e.preventDefault(),I(k+(e.deltaY<0?o:-.15))},children:C&&(0,i.jsx)(`img`,{ref:x,src:C,alt:``,draggable:!1,className:n.default.image,style:{width:P.width||void 0,height:P.height||void 0,transform:`translate(${j.x}px, ${j.y}px)`},onLoad:e=>{let t=e.currentTarget;t.naturalWidth>0&&t.naturalHeight>0&&E({width:t.naturalWidth,height:t.naturalHeight})}})}),(0,i.jsxs)(`div`,{className:n.default.controls,children:[(0,i.jsx)(`input`,{type:`range`,className:n.default.zoom,min:1,max:l,step:.01,value:k,onChange:e=>I(Number(e.target.value)),"aria-label":`Zoom`,disabled:!T}),(0,i.jsx)(`button`,{type:`button`,className:n.default.reset,onClick:L,disabled:!T,children:`Centralizar`})]}),(0,i.jsxs)(`p`,{id:y,className:n.default.hint,children:[`Arraste para reposicionar. Setas movem, `,(0,i.jsx)(`kbd`,{children:`+`}),` e `,(0,i.jsx)(`kbd`,{children:`−`}),` dão zoom,`,` `,(0,i.jsx)(`kbd`,{children:`0`}),` centraliza.`]})]})}exports.ImageCropper=s;
+//# sourceMappingURL=ImageCropper.cjs.map

package/dist/components/ImageCropper/ImageCropper.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageCropper.cjs","names":[],"sources":["../../../src/components/ImageCropper/ImageCropper.tsx"],"sourcesContent":["import {\n    type HTMLAttributes,\n    type KeyboardEvent,\n    type PointerEvent as ReactPointerEvent,\n    useCallback,\n    useEffect,\n    useId,\n    useImperativeHandle,\n    useMemo,\n    useRef,\n    useState,\n} from \"react\";\n\nimport { cn } from \"@/utils/cn\";\n\nimport {\n    clampOffset,\n    computeCropRect,\n    coverScale,\n    type Offset,\n    outputSize,\n    type Size,\n} from \"./crop-geometry\";\nimport styles from \"./ImageCropper.module.css\";\n\n/** Imperative handle for exporting the current crop. */\nexport interface ImageCropperHandle {\n    /**\n     * Render the current crop and resolve with it.\n     *\n     * Resolves `null` when the image has not loaded yet or the browser refuses to\n     * encode — never throws, so a submit handler does not need a try/catch.\n     */\n    crop: () => Promise<Blob | null>;\n    /** Recentre at zoom 1. */\n    reset: () => void;\n}\n\nexport interface ImageCropperProps extends Omit<HTMLAttributes<HTMLDivElement>, \"children\"> {\n    /** The image to crop: a `File`/`Blob` from an input, or a URL. */\n    src: File | Blob | string;\n    /** Crop aspect ratio as `width / height`. Default `1` (square). */\n    aspect?: number;\n    /** Maximum zoom over the cover scale. Default `4`. */\n    maxZoom?: number;\n    /**\n     * Cap on the longest edge of the exported image, in px.\n     *\n     * Without it the export keeps the source resolution, which is right for a\n     * document scan and wasteful for an avatar.\n     */\n    maxSize?: number;\n    /** Output MIME type. Default `\"image/png\"`. */\n    outputType?: string;\n    /** Output quality for lossy types, `0`–`1`. Default `0.92`. */\n    outputQuality?: number;\n    /** Overlay shape. `\"circle\"` for an avatar, `\"rect\"` for a document. Default `\"rect\"`. */\n    shape?: \"rect\" | \"circle\";\n    /** Called whenever the crop changes, e.g. to enable a submit button. */\n    onCropChange?: (state: { zoom: number; offset: Offset }) => void;\n    /** Accessible name for the crop area. */\n    label?: string;\n    ref?: React.Ref<ImageCropperHandle>;\n}\n\n/** Pixels moved per arrow-key press. */\nconst KEY_STEP = 12;\n\n/** Zoom added or removed per `+`/`-` press, and per wheel notch. */\nconst ZOOM_STEP = 0.15;\n\n/**\n * Crop an image to a fixed aspect ratio.\n *\n * The frame stays put and the image pans and zooms behind it — the model an avatar\n * or document-photo flow wants, where the output shape is decided by the app and\n * the user only chooses what lands inside it. (A free-form draggable rectangle is a\n * different component; this one cannot produce an off-ratio crop by construction.)\n *\n * The export reads the *natural* pixels through a canvas, so a 4000 px photo is not\n * silently downsampled to whatever the on-screen preview measured. The image is\n * also always clamped to cover the frame, so an export can never contain the empty\n * bands you get from panning past an edge.\n *\n * Works by pointer, wheel and keyboard: arrows pan, `+`/`-` zoom, `0` resets.\n *\n * @example\n * const cropper = useRef<ImageCropperHandle>(null);\n *\n * <ImageCropper ref={cropper} src={file} aspect={1} shape=\"circle\" maxSize={512} />\n * <Button onClick={async () => upload(await cropper.current?.crop())}>Salvar</Button>\n */\nexport function ImageCropper({\n    src,\n    aspect = 1,\n    maxZoom = 4,\n    maxSize,\n    outputType = \"image/png\",\n    outputQuality = 0.92,\n    shape = \"rect\",\n    onCropChange,\n    label = \"Área de recorte\",\n    className,\n    ref,\n    ...rest\n}: ImageCropperProps) {\n    /**\n     * Id for the shortcut hint.\n     *\n     * Generated rather than derived from `label`: a label with spaces would produce\n     * an id with spaces, and `aria-describedby` splits on whitespace — so the\n     * description would silently never associate with the frame.\n     */\n    const hintId = `${useId()}-hint`;\n\n    const frameRef = useRef<HTMLDivElement>(null);\n    const imageRef = useRef<HTMLImageElement | null>(null);\n    const dragRef = useRef<{\n        pointerId: number;\n        startX: number;\n        startY: number;\n        from: Offset;\n    } | null>(null);\n\n    const [url, setUrl] = useState<string | null>(null);\n    const [natural, setNatural] = useState<Size | null>(null);\n    const [frame, setFrame] = useState<Size>({ width: 0, height: 0 });\n    const [zoom, setZoom] = useState(1);\n    const [offset, setOffset] = useState<Offset>({ x: 0, y: 0 });\n\n    /**\n     * Resolve `src` to a displayable URL.\n     *\n     * A `File`/`Blob` needs `createObjectURL`, and the URL must be revoked when the\n     * source changes or the component unmounts — otherwise every re-pick of a photo\n     * leaks the previous one for the lifetime of the document.\n     */\n    useEffect(() => {\n        if (typeof src === \"string\") {\n            setUrl(src);\n            return;\n        }\n        const objectUrl = URL.createObjectURL(src);\n        setUrl(objectUrl);\n        return () => URL.revokeObjectURL(objectUrl);\n    }, [src]);\n\n    // A new source invalidates the previous framing.\n    useEffect(() => {\n        setNatural(null);\n        setZoom(1);\n        setOffset({ x: 0, y: 0 });\n    }, [url]);\n\n    /** Track the frame's rendered size — the crop math is all relative to it. */\n    useEffect(() => {\n        const element = frameRef.current;\n        if (!element) return;\n        const measure = () =>\n            setFrame({ width: element.clientWidth, height: element.clientHeight });\n        measure();\n        if (typeof ResizeObserver === \"undefined\") return;\n        const observer = new ResizeObserver(measure);\n        observer.observe(element);\n        return () => observer.disconnect();\n    }, []);\n\n    const scale = natural ? coverScale(natural, frame) * zoom : 0;\n\n    /**\n     * On-screen image size.\n     *\n     * Memoized because the pan callback depends on it: a fresh object every render\n     * would rebuild that callback every render, and the pointer handlers close over\n     * it during a drag.\n     */\n    const displayed = useMemo<Size>(\n        () =>\n            natural\n                ? { width: natural.width * scale, height: natural.height * scale }\n                : { width: 0, height: 0 },\n        [natural, scale],\n    );\n\n    /** Apply a pan, clamped so the frame stays covered. */\n    const pan = useCallback(\n        (next: Offset) => {\n            setOffset((current) => {\n                const clamped = clampOffset(next, displayed, frame);\n                if (clamped.x === current.x && clamped.y === current.y) return current;\n                onCropChange?.({ zoom, offset: clamped });\n                return clamped;\n            });\n        },\n        [displayed, frame, onCropChange, zoom],\n    );\n\n    /**\n     * Apply a zoom, then re-clamp the offset.\n     *\n     * Re-clamping is not optional: zooming *out* shrinks the image, so an offset\n     * that was legal a moment ago can now expose background.\n     */\n    const applyZoom = useCallback(\n        (next: number) => {\n            const clampedZoom = Math.min(maxZoom, Math.max(1, next));\n            setZoom(clampedZoom);\n            if (!natural) return;\n            const nextScale = coverScale(natural, frame) * clampedZoom;\n            const nextDisplayed = {\n                width: natural.width * nextScale,\n                height: natural.height * nextScale,\n            };\n            setOffset((current) => {\n                const clamped = clampOffset(current, nextDisplayed, frame);\n                onCropChange?.({ zoom: clampedZoom, offset: clamped });\n                return clamped;\n            });\n        },\n        [frame, maxZoom, natural, onCropChange],\n    );\n\n    const reset = useCallback(() => {\n        setZoom(1);\n        setOffset({ x: 0, y: 0 });\n        onCropChange?.({ zoom: 1, offset: { x: 0, y: 0 } });\n    }, [onCropChange]);\n\n    /**\n     * Draw the current crop and encode it.\n     *\n     * Returns `null` rather than throwing on the paths a caller cannot do anything\n     * about: no image yet, no 2D context, or an encoder that declined.\n     */\n    const crop = useCallback(async (): Promise<Blob | null> => {\n        const image = imageRef.current;\n        if (!image || !natural) return null;\n\n        const rect = computeCropRect({ image: natural, frame, zoom, offset });\n        if (rect.sWidth <= 0 || rect.sHeight <= 0) return null;\n\n        const out = outputSize(rect, maxSize);\n        const canvas = document.createElement(\"canvas\");\n        canvas.width = out.width;\n        canvas.height = out.height;\n        const context = canvas.getContext(\"2d\");\n        if (!context) return null;\n\n        context.drawImage(\n            image,\n            rect.sx,\n            rect.sy,\n            rect.sWidth,\n            rect.sHeight,\n            0,\n            0,\n            out.width,\n            out.height,\n        );\n\n        return new Promise((resolve) => {\n            canvas.toBlob((blob) => resolve(blob), outputType, outputQuality);\n        });\n    }, [frame, maxSize, natural, offset, outputQuality, outputType, zoom]);\n\n    useImperativeHandle(ref, () => ({ crop, reset }), [crop, reset]);\n\n    const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>): void => {\n        if (!natural) return;\n        dragRef.current = {\n            pointerId: event.pointerId,\n            startX: event.clientX,\n            startY: event.clientY,\n            from: offset,\n        };\n        event.currentTarget.setPointerCapture?.(event.pointerId);\n    };\n\n    const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>): void => {\n        const drag = dragRef.current;\n        if (!drag || drag.pointerId !== event.pointerId) return;\n        pan({\n            x: drag.from.x + (event.clientX - drag.startX),\n            y: drag.from.y + (event.clientY - drag.startY),\n        });\n    };\n\n    const endDrag = (event: ReactPointerEvent<HTMLDivElement>): void => {\n        if (dragRef.current?.pointerId !== event.pointerId) return;\n        dragRef.current = null;\n    };\n\n    const onKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {\n        const step = event.shiftKey ? KEY_STEP * 4 : KEY_STEP;\n        const moves: Record<string, Offset> = {\n            ArrowLeft: { x: -step, y: 0 },\n            ArrowRight: { x: step, y: 0 },\n            ArrowUp: { x: 0, y: -step },\n            ArrowDown: { x: 0, y: step },\n        };\n        const move = moves[event.key];\n        if (move) {\n            event.preventDefault();\n            pan({ x: offset.x + move.x, y: offset.y + move.y });\n            return;\n        }\n        if (event.key === \"+\" || event.key === \"=\") {\n            event.preventDefault();\n            applyZoom(zoom + ZOOM_STEP);\n        } else if (event.key === \"-\" || event.key === \"_\") {\n            event.preventDefault();\n            applyZoom(zoom - ZOOM_STEP);\n        } else if (event.key === \"0\") {\n            event.preventDefault();\n            reset();\n        }\n    };\n\n    return (\n        <div className={cn(styles.wrapper, className)} {...rest}>\n            <div\n                ref={frameRef}\n                className={cn(styles.frame, shape === \"circle\" && styles.circle)}\n                style={{ aspectRatio: String(aspect) }}\n                role=\"group\"\n                aria-label={label}\n                aria-describedby={hintId}\n                tabIndex={0}\n                onPointerDown={onPointerDown}\n                onPointerMove={onPointerMove}\n                onPointerUp={endDrag}\n                onPointerCancel={endDrag}\n                onKeyDown={onKeyDown}\n                onWheel={(event) => {\n                    event.preventDefault();\n                    applyZoom(zoom + (event.deltaY < 0 ? ZOOM_STEP : -ZOOM_STEP));\n                }}\n            >\n                {url && (\n                    <img\n                        ref={imageRef}\n                        src={url}\n                        alt=\"\"\n                        draggable={false}\n                        className={styles.image}\n                        style={{\n                            width: displayed.width || undefined,\n                            height: displayed.height || undefined,\n                            transform: `translate(${offset.x}px, ${offset.y}px)`,\n                        }}\n                        onLoad={(event) => {\n                            const element = event.currentTarget;\n                            // A decode can succeed and still report no intrinsic size —\n                            // an SVG without a viewBox is the common case. Accepting\n                            // that would enable the controls over an image the crop\n                            // maths can do nothing with.\n                            if (element.naturalWidth > 0 && element.naturalHeight > 0) {\n                                setNatural({\n                                    width: element.naturalWidth,\n                                    height: element.naturalHeight,\n                                });\n                            }\n                        }}\n                    />\n                )}\n            </div>\n\n            <div className={styles.controls}>\n                <input\n                    type=\"range\"\n                    className={styles.zoom}\n                    min={1}\n                    max={maxZoom}\n                    step={0.01}\n                    value={zoom}\n                    onChange={(event) => applyZoom(Number(event.target.value))}\n                    aria-label=\"Zoom\"\n                    disabled={!natural}\n                />\n                <button type=\"button\" className={styles.reset} onClick={reset} disabled={!natural}>\n                    Centralizar\n                </button>\n            </div>\n\n            <p id={hintId} className={styles.hint}>\n                Arraste para reposicionar. Setas movem, <kbd>+</kbd> e <kbd>−</kbd> dão zoom,{\" \"}\n                <kbd>0</kbd> centraliza.\n            </p>\n        </div>\n    );\n}\n"],"mappings":"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"}