docs(cropper): add bilingual usage guides

2026-09-29 17:09:39 +08:00
parent 23e0867027
commit 844acad316
8 changed files with 340 additions and 0 deletions
@@ -0,0 +1,48 @@
+---
+title: Basic usage
+description: Add the stylesheet source and create an interactive image cropper.
+order: 10
+toc:
+  - id: stylesheet
+    title: Stylesheet
+  - id: cropper
+    title: Cropper
+  - id: controls
+    title: External controls
+---
+
+## Stylesheet {#stylesheet}
+
+Add the package source to the application's Tailwind stylesheet:
+
+```css
+@import "@workspace/cropper/globals.css";
+```
+
+## Cropper {#cropper}
+
+Give the component an explicit width; `aspectRatio` determines its height:
+
+```tsx
+import { Cropper, type CropArea } from "@workspace/cropper"
+
+function ProductImageCropper({ src }: { src: string }) {
+  const [area, setArea] = React.useState<CropArea>()
+
+  return (
+    <Cropper
+      src={src}
+      alt="Product"
+      aspectRatio={4 / 3}
+      className="w-full max-w-xl rounded-xl"
+      onCropAreaChange={setArea}
+    />
+  )
+}
+```
+
+Users can drag the image, scroll to zoom, or focus the Cropper and use the arrow, `+`, `-`, `0`, and `Home` keys.
+
+## External controls {#controls}
+
+Control the crop with `value` and `onValueChange` to connect a Slider or reset button. `minZoom` is clamped to at least `1`, ensuring that the image always covers the viewport.