@krizaka/ui 2.3.0 → 2.4.0

package/registry/image-cropper.json

@@ -0,0 +1,313 @@
+{
+  "name": "image-cropper",
+  "type": "primitive",
+  "title": "Image cropper",
+  "summary": "A fixed frame — square, round, 9:16, a banner — over a picture or a video the person drags and zooms; a focus point and a zoom out, `cropRect` for the pixels.",
+  "description": "A fixed frame — square, round, 9:16, a banner — over a picture or a video the person drags and zooms; a focus point and a zoom out, `cropRect` for the pixels.",
+  "status": "beta",
+  "category": "media",
+  "platforms": "web",
+  "whenToUse": [
+    "To frame a profile picture or a cover before sending it.",
+    "To choose what a vertical (9:16) or square version of a landscape video keeps."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "To cut a video in time (not in space): the video trimmer.",
+      "use": "video-trimmer"
+    },
+    {
+      "when": "To send a file as it is: the file upload.",
+      "use": "file-upload"
+    }
+  ],
+  "bestPractices": [
+    "Store the focus point and the zoom (screen-independent), and crop on the server with `cropRect`.",
+    "Use `round` for an avatar: the person sees what others will see.",
+    "Keep the zoom slider (`showZoom`): pinch and Ctrl + wheel are not obvious to everyone."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Arrow keys",
+        "action": "Move the picture in the frame (Shift: faster)."
+      },
+      {
+        "keys": "+ / −",
+        "action": "Zoom in or out."
+      }
+    ],
+    "notes": [
+      "The frame is a focusable `group` named by `labels.frame` and described by `labels.instructions`.",
+      "The zoom is a `slider` read as a percentage.",
+      "Nothing moves but what the person moves."
+    ]
+  },
+  "related": [
+    "file-upload",
+    "media-capture",
+    "avatar",
+    "slider"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/image-cropper",
+    "import": "import { ImageCropper, cropRect } from \"@krizaka/ui/image-cropper\";",
+    "props": [
+      {
+        "component": "ImageCropper",
+        "description": "Chooses what a fixed frame keeps of a picture or a video: drag, zoom, keyboard; a focus point and a zoom out.",
+        "props": [
+          {
+            "name": "aspect",
+            "type": "number",
+            "default": null,
+            "description": "The frame's width / height: 1 (a square), 9 / 16 (vertical), 3 (a banner).",
+            "required": true
+          },
+          {
+            "name": "alt",
+            "type": "string",
+            "default": "",
+            "description": "The picture's alternative text, passed translated (empty when the frame's name says enough).",
+            "required": false
+          },
+          {
+            "name": "children",
+            "type": "ReactElement<{ className?: string; style?: CSSProperties; }, string | JSXElementConstructor<any>> | undefined",
+            "default": null,
+            "description": "A media element instead of `src` — a `<video>` to choose the frame of a clip. Its natural size is in `naturalSize`.",
+            "required": false
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "Classes merged on the root.",
+            "required": false
+          },
+          {
+            "name": "defaultValue",
+            "type": "CropValue",
+            "default": "{ x: 0.5, y: 0.5, zoom: 1 }",
+            "description": "The crop at first, uncontrolled. Default: centred, no zoom.",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<ImageCropperLabels>",
+            "default": null,
+            "description": "The words, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "maxZoom",
+            "type": "number",
+            "default": "4",
+            "description": "The largest zoom. Default 4.",
+            "required": false
+          },
+          {
+            "name": "naturalSize",
+            "type": "{ width: number; height: number; }",
+            "default": null,
+            "description": "The source's size when `children` is a video: `{ width: video.videoWidth, height: video.videoHeight }`.",
+            "required": false
+          },
+          {
+            "name": "onValueChange",
+            "type": "((value: CropValue) => void)",
+            "default": null,
+            "description": "Called on every move.",
+            "required": false
+          },
+          {
+            "name": "round",
+            "type": "boolean",
+            "default": null,
+            "description": "A round mask over the square frame (a profile picture).",
+            "required": false
+          },
+          {
+            "name": "showZoom",
+            "type": "boolean",
+            "default": "true",
+            "description": "Shows the zoom slider under the frame. Default `true`.",
+            "required": false
+          },
+          {
+            "name": "src",
+            "type": "string",
+            "default": null,
+            "description": "The picture to crop. Or `children`: a `<video>` (with the class it is given through `mediaClassName`).",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "CropValue",
+            "default": null,
+            "description": "The crop (controlled).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "avatar",
+        "title": "Profile picture",
+        "description": "A round mask on a square frame.",
+        "path": "examples/image-cropper/avatar.tsx",
+        "module": "@krizaka/ui/registry/examples/image-cropper/avatar",
+        "code": "\"use client\";\n\nimport { type CropValue, ImageCropper } from \"@krizaka/ui/image-cropper\";\nimport * as React from \"react\";\n\n// A round mask on a square frame: what others will see. Send the focus point and the zoom with the file.\nexport default function ImageCropperAvatar() {\n  const [crop, setCrop] = React.useState<CropValue>({ x: 0.42, y: 0.5, zoom: 1.4 });\n  return (\n    <div className=\"w-64\">\n      <ImageCropper src=\"https://www.krizaka.com/assets/orochia/tour/elena-live.jpg\" aspect={1} round value={crop} onValueChange={setCrop} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "banner",
+        "title": "Banner",
+        "description": "A 3:1 frame for a profile's cover, zoomed in.",
+        "path": "examples/image-cropper/banner.tsx",
+        "module": "@krizaka/ui/registry/examples/image-cropper/banner",
+        "code": "import { ImageCropper } from \"@krizaka/ui/image-cropper\";\n\n// A profile's cover: a 3:1 frame, zoomed in on the centre.\nexport default function ImageCropperBanner() {\n  return (\n    <div className=\"w-full max-w-lg\">\n      <ImageCropper src=\"https://www.krizaka.com/assets/orochia/tour/alex-discover.jpg\" aspect={3} defaultValue={{ x: 0.5, y: 0.45, zoom: 1.2 }} labels={{ frame: \"Cover picture\" }} />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "vertical-video",
+        "title": "Vertical version of a video",
+        "description": "A `<video>` as the media, a 9:16 frame: choose what the vertical cut keeps.",
+        "path": "examples/image-cropper/vertical-video.tsx",
+        "module": "@krizaka/ui/registry/examples/image-cropper/vertical-video",
+        "code": "\"use client\";\n\nimport { ImageCropper } from \"@krizaka/ui/image-cropper\";\n\nconst TOUR = \"https://www.krizaka.com/assets/orochia/tour\";\n\n// A landscape video, a 9:16 frame: choose what the vertical version keeps. The size is the video's own.\nexport default function ImageCropperVerticalVideo() {\n  return (\n    <div className=\"w-48\">\n      <ImageCropper aspect={9 / 16} naturalSize={{ width: 1280, height: 800 }} defaultValue={{ x: 0.35, y: 0.5, zoom: 1 }} showZoom={false} labels={{ frame: \"Vertical frame\" }}>\n        <video src={`${TOUR}/elena-earnings.mp4`} poster={`${TOUR}/elena-earnings.jpg`} muted playsInline preload=\"none\" aria-hidden />\n      </ImageCropper>\n    </div>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "image-cropper/image-cropper.tsx",
+      "content": "// Client. A fixed frame (a profile picture's square, a vertical 9:16, a banner) over a picture or a video the person\n// drags and zooms to choose what stays in. The value is a focus point (0–1 on each axis) and a zoom — independent of\n// the screen, the same on the server — and `cropRect` turns it into pixels of the source. Keyboard: the frame takes the\n// focus, the arrows move (Shift: faster), + / − zoom; the zoom is also a slider. No motion but the person's own.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { clamp } from \"../media\";\nimport { Slider } from \"../slider\";\n\nexport const imageCropper = tv({\n  slots: {\n    root: \"flex w-full flex-col gap-3\",\n    frame:\n      \"relative w-full cursor-grab touch-none overflow-hidden rounded-xl bg-media active:cursor-grabbing \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-surface-0\",\n    media: \"pointer-events-none absolute max-w-none select-none\",\n    grid:\n      \"pointer-events-none absolute inset-0 rounded-xl border-2 border-fg-on-media/80 \" +\n      \"bg-[linear-gradient(to_right,transparent_33.2%,var(--kz-text-on-media)_33.3%,transparent_33.5%,transparent_66.5%,var(--kz-text-on-media)_66.6%,transparent_66.8%),linear-gradient(to_bottom,transparent_33.2%,var(--kz-text-on-media)_33.3%,transparent_33.5%,transparent_66.5%,var(--kz-text-on-media)_66.6%,transparent_66.8%)] opacity-40\",\n    round: \"pointer-events-none absolute inset-0 rounded-full shadow-[0_0_0_9999px_var(--kz-scrim-strong)]\",\n  },\n});\n\n/** Where the frame looks: the focus point (0–1 from the left and the top of the source) and the zoom (1 = covers). */\nexport type CropValue = { x: number; y: number; zoom: number };\n\n/** The crop in pixels of the source: what to cut from an image of `width` × `height` for a frame of `aspect`. */\nexport function cropRect(value: CropValue, source: { width: number; height: number }, aspect: number) {\n  const mediaAspect = source.width / source.height;\n  const width = (mediaAspect > aspect ? source.height * aspect : source.width) / value.zoom;\n  const height = width / aspect;\n  const x = clamp(value.x * source.width - width / 2, 0, source.width - width);\n  const y = clamp(value.y * source.height - height / 2, 0, source.height - height);\n  return { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };\n}\n\nexport type ImageCropperLabels = {\n  /** The frame's accessible name (\"Crop area\"). */\n  frame: string;\n  /** How to use it with the keyboard, read with the frame (\"Use the arrow keys to move the picture, + and − to zoom.\"). */\n  instructions: string;\n  /** The zoom slider (\"Zoom\"). */\n  zoom: string;\n};\n\nexport const imageCropperLabels: ImageCropperLabels = {\n  frame: \"Crop area\",\n  instructions: \"Drag or use the arrow keys to move the picture, + and − to zoom.\",\n  zoom: \"Zoom\",\n};\n\nexport type ImageCropperProps = {\n  /** The picture to crop. Or `children`: a `<video>` (with the class it is given through `mediaClassName`). */\n  src?: string;\n  /** The picture's alternative text, passed translated (empty when the frame's name says enough). */\n  alt?: string;\n  /** A media element instead of `src` — a `<video>` to choose the frame of a clip. Its natural size is in `naturalSize`. */\n  children?: React.ReactElement<{ className?: string; style?: React.CSSProperties }>;\n  /** The source's size when `children` is a video: `{ width: video.videoWidth, height: video.videoHeight }`. */\n  naturalSize?: { width: number; height: number };\n  /** The frame's width / height: 1 (a square), 9 / 16 (vertical), 3 (a banner). */\n  aspect: number;\n  /** A round mask over the square frame (a profile picture). */\n  round?: boolean;\n  /** The crop (controlled). */\n  value?: CropValue;\n  /** The crop at first, uncontrolled. Default: centred, no zoom. */\n  defaultValue?: CropValue;\n  /** Called on every move. */\n  onValueChange?: (value: CropValue) => void;\n  /** The largest zoom. Default 4. */\n  maxZoom?: number;\n  /** Shows the zoom slider under the frame. Default `true`. */\n  showZoom?: boolean;\n  /** The words, passed translated; English by default. */\n  labels?: Partial<ImageCropperLabels>;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\n/** Chooses what a fixed frame keeps of a picture or a video: drag, zoom, keyboard; a focus point and a zoom out. */\nexport function ImageCropper({\n  src,\n  alt = \"\",\n  children,\n  naturalSize,\n  aspect,\n  round,\n  value: valueProp,\n  defaultValue = { x: 0.5, y: 0.5, zoom: 1 },\n  onValueChange,\n  maxZoom = 4,\n  showZoom = true,\n  labels: given,\n  className,\n}: ImageCropperProps) {\n  const labels = { ...imageCropperLabels, ...given };\n  const s = imageCropper();\n  const frame = React.useRef<HTMLDivElement>(null);\n  const drag = React.useRef<{ x: number; y: number; from: CropValue } | null>(null);\n  const [inner, setInner] = React.useState(defaultValue);\n  const [loaded, setLoaded] = React.useState<{ width: number; height: number } | null>(null);\n  const value = valueProp ?? inner;\n  const id = React.useId();\n  const size = naturalSize ?? loaded;\n  const mediaAspect = size ? size.width / size.height : aspect;\n\n  // The media's box, in % of the frame: it covers the frame at zoom 1.\n  const widthPct = (mediaAspect > aspect ? (mediaAspect / aspect) * 100 : 100) * value.zoom;\n  const heightPct = (mediaAspect > aspect ? 100 : (aspect / mediaAspect) * 100) * value.zoom;\n  // The focus point's limits: the media never leaves a gap in the frame.\n  const halfX = 50 / widthPct;\n  const halfY = 50 / heightPct;\n\n  const set = (next: CropValue) => {\n    const zoom = clamp(next.zoom, 1, maxZoom);\n    const wPct = (mediaAspect > aspect ? (mediaAspect / aspect) * 100 : 100) * zoom;\n    const hPct = (mediaAspect > aspect ? 100 : (aspect / mediaAspect) * 100) * zoom;\n    const fixed = { x: clamp(next.x, 50 / wPct, 1 - 50 / wPct), y: clamp(next.y, 50 / hPct, 1 - 50 / hPct), zoom };\n    if (!valueProp) setInner(fixed);\n    onValueChange?.(fixed);\n  };\n\n  const x = clamp(value.x, halfX, 1 - halfX);\n  const y = clamp(value.y, halfY, 1 - halfY);\n  const style: React.CSSProperties = {\n    width: `${widthPct}%`,\n    height: `${heightPct}%`,\n    left: `${50 - x * widthPct}%`,\n    top: `${50 - y * heightPct}%`,\n  };\n\n  return (\n    <div className={s.root({ className })}>\n      <div\n        ref={frame}\n        role=\"group\"\n        tabIndex={0}\n        aria-label={labels.frame}\n        aria-describedby={`${id}-help`}\n        className={s.frame()}\n        style={{ aspectRatio: String(aspect) }}\n        onPointerDown={(event) => {\n          frame.current?.setPointerCapture?.(event.pointerId);\n          drag.current = { x: event.clientX, y: event.clientY, from: { x, y, zoom: value.zoom } };\n        }}\n        onPointerMove={(event) => {\n          const start = drag.current;\n          const box = frame.current?.getBoundingClientRect();\n          if (!start || !box?.width) return;\n          set({\n            x: start.from.x - (event.clientX - start.x) / ((box.width * widthPct) / 100),\n            y: start.from.y - (event.clientY - start.y) / ((box.height * heightPct) / 100),\n            zoom: value.zoom,\n          });\n        }}\n        onPointerUp={() => {\n          drag.current = null;\n        }}\n        onWheel={(event) => {\n          if (!event.ctrlKey && !event.metaKey) return;\n          event.preventDefault();\n          set({ x, y, zoom: value.zoom - event.deltaY * 0.01 });\n        }}\n        onKeyDown={(event) => {\n          const nudge = event.shiftKey ? 0.1 : 0.02;\n          const moves: Record<string, CropValue> = {\n            ArrowLeft: { x: x - nudge, y, zoom: value.zoom },\n            ArrowRight: { x: x + nudge, y, zoom: value.zoom },\n            ArrowUp: { x, y: y - nudge, zoom: value.zoom },\n            ArrowDown: { x, y: y + nudge, zoom: value.zoom },\n            \"+\": { x, y, zoom: value.zoom + 0.1 },\n            \"=\": { x, y, zoom: value.zoom + 0.1 },\n            \"-\": { x, y, zoom: value.zoom - 0.1 },\n          };\n          const next = moves[event.key];\n          if (!next) return;\n          event.preventDefault();\n          set(next);\n        }}\n      >\n        {children ? (\n          React.cloneElement(children, { className: s.media({ className: children.props.className }), style: { ...children.props.style, ...style } })\n        ) : src ? (\n          <img\n            src={src}\n            alt={alt}\n            draggable={false}\n            className={s.media()}\n            style={style}\n            onLoad={(event) => setLoaded({ width: event.currentTarget.naturalWidth, height: event.currentTarget.naturalHeight })}\n          />\n        ) : null}\n        <span className={round ? s.round() : s.grid()} aria-hidden />\n        <span id={`${id}-help`} className=\"sr-only\">\n          {labels.instructions}\n        </span>\n      </div>\n      {showZoom && (\n        <Slider\n          label={labels.zoom}\n          min={1}\n          max={maxZoom}\n          step={0.05}\n          value={value.zoom}\n          onValueChange={(zoom) => set({ x, y, zoom })}\n          formatValue={(v) => `${Math.round(v * 100)} %`}\n        />\n      )}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "image-cropper/index.ts",
+      "content": "/** @krizaka/ui/image-cropper — `ImageCropper` (a fixed frame over a picture or a video: drag, zoom, keyboard; a focus point out), `cropRect`, `imageCropper` (the slots). Client (\"use client\"). */\nexport { cropRect, type CropValue, ImageCropper, imageCropper, type ImageCropperLabels, imageCropperLabels, type ImageCropperProps } from \"./image-cropper\";\n"
+    },
+    {
+      "path": "image-cropper/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Image cropper\",\n  summary: \"A fixed frame — square, round, 9:16, a banner — over a picture or a video the person drags and zooms; a focus point and a zoom out, `cropRect` for the pixels.\",\n  status: \"beta\",\n  category: \"media\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To frame a profile picture or a cover before sending it.\",\n    \"To choose what a vertical (9:16) or square version of a landscape video keeps.\",\n  ],\n  whenNotToUse: [\n    { when: \"To cut a video in time (not in space): the video trimmer.\", use: \"video-trimmer\" },\n    { when: \"To send a file as it is: the file upload.\", use: \"file-upload\" },\n  ],\n  bestPractices: [\n    \"Store the focus point and the zoom (screen-independent), and crop on the server with `cropRect`.\",\n    \"Use `round` for an avatar: the person sees what others will see.\",\n    \"Keep the zoom slider (`showZoom`): pinch and Ctrl + wheel are not obvious to everyone.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Arrow keys\", action: \"Move the picture in the frame (Shift: faster).\" },\n      { keys: \"+ / −\", action: \"Zoom in or out.\" },\n    ],\n    notes: [\n      \"The frame is a focusable `group` named by `labels.frame` and described by `labels.instructions`.\",\n      \"The zoom is a `slider` read as a percentage.\",\n      \"Nothing moves but what the person moves.\",\n    ],\n  },\n  related: [\"file-upload\", \"media-capture\", \"avatar\", \"slider\"],\n  web: {\n    imports: [\"ImageCropper\", \"cropRect\"],\n    examples: [\n      { name: \"avatar\", title: \"Profile picture\", description: \"A round mask on a square frame.\" },\n      { name: \"banner\", title: \"Banner\", description: \"A 3:1 frame for a profile's cover, zoomed in.\" },\n      { name: \"vertical-video\", title: \"Vertical version of a video\", description: \"A `<video>` as the media, a 9:16 frame: choose what the vertical cut keeps.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "media.ts",
+      "content": "// Shared by the data and media primitives (client): the clock format, the reduced-motion preference, the\n// in-view observer, a debounced callback. Never an entry of its own.\nimport * as React from \"react\";\n\n/** Seconds as a clock: `75` → `1:15`, `3725` → `1:02:05`. Negative or unknown values read `0:00`. */\nexport function formatClock(seconds: number): string {\n  const s = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;\n  const h = Math.floor(s / 3600);\n  const m = Math.floor((s % 3600) / 60);\n  const rest = String(s % 60).padStart(2, \"0\");\n  return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${rest}` : `${m}:${rest}`;\n}\n\n/** Clamps `value` between `min` and `max`. */\nexport const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));\n\nconst REDUCE = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduce = (notify: () => void) => {\n  if (typeof window === \"undefined\" || !window.matchMedia) return () => undefined;\n  const query = window.matchMedia(REDUCE);\n  query.addEventListener?.(\"change\", notify);\n  return () => query.removeEventListener?.(\"change\", notify);\n};\n\n/** `true` when the person asked for less motion (`prefers-reduced-motion: reduce`); follows a change of the setting. */\nexport function usePrefersReducedMotion(): boolean {\n  return React.useSyncExternalStore(\n    subscribeReduce,\n    () => (typeof window !== \"undefined\" && window.matchMedia ? window.matchMedia(REDUCE).matches : false),\n    () => false,\n  );\n}\n\n/** The latest value of a callback, for an effect or an event that must not re-subscribe when it changes. */\nexport function useLatest<T>(value: T) {\n  const ref = React.useRef(value);\n  React.useLayoutEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\n/** Calls `onChange(visible)` when at least `threshold` of the element enters or leaves the viewport. */\nexport function useInView(ref: React.RefObject<Element | null>, onChange: (visible: boolean) => void, enabled = true, threshold = 0.25) {\n  const latest = useLatest(onChange);\n  React.useEffect(() => {\n    const element = ref.current;\n    if (!enabled || !element || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => entry && latest.current(entry.isIntersecting), { threshold });\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, [ref, enabled, threshold, latest]);\n}\n\n/** A stable function that runs `callback` once `delay` ms have passed without a new call; `cancel()` drops the pending one. */\nexport function useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delay: number) {\n  const latest = useLatest(callback);\n  const [debounced] = React.useState(() => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let wait = delay;\n    const run = (...args: A) => {\n      clearTimeout(timer);\n      if (wait <= 0) latest.current(...args);\n      else timer = setTimeout(() => latest.current(...args), wait);\n    };\n    return Object.assign(run, {\n      cancel: () => clearTimeout(timer),\n      setDelay: (next: number) => {\n        wait = next;\n      },\n    });\n  });\n  React.useEffect(() => debounced.setDelay(delay), [debounced, delay]);\n  React.useEffect(() => () => debounced.cancel(), [debounced]);\n  return debounced;\n}\n\n/** A value controlled by a prop when it is given, held inside otherwise; `set` calls `onChange` either way. */\nexport function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (next: T) => void) {\n  const [inner, setInner] = React.useState(defaultValue);\n  const controlled = value !== undefined;\n  const current = controlled ? value : inner;\n  const set = React.useCallback(\n    (next: T) => {\n      if (!controlled) setInner(next);\n      onChange?.(next);\n    },\n    [controlled, onChange],\n  );\n  return [current, set] as const;\n}\n\n/** Starts a media element without an unhandled rejection (autoplay refused, the source replaced meanwhile). */\nexport function playSafely(media: HTMLMediaElement | null | undefined) {\n  try {\n    const started = media?.play() as Promise<void> | undefined;\n    started?.catch?.(() => undefined);\n  } catch {\n    // Not playable here (no media support): the controls stay as they are.\n  }\n}\n"
+    },
+    {
+      "path": "meta.ts",
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [
+    "slider"
+  ],
+  "demo": {
+    "path": "examples/image-cropper/avatar.tsx",
+    "content": "\"use client\";\n\nimport { type CropValue, ImageCropper } from \"@krizaka/ui/image-cropper\";\nimport * as React from \"react\";\n\n// A round mask on a square frame: what others will see. Send the focus point and the zoom with the file.\nexport default function ImageCropperAvatar() {\n  const [crop, setCrop] = React.useState<CropValue>({ x: 0.42, y: 0.5, zoom: 1.4 });\n  return (\n    <div className=\"w-64\">\n      <ImageCropper src=\"https://www.krizaka.com/assets/orochia/tour/elena-live.jpg\" aspect={1} round value={crop} onValueChange={setCrop} />\n    </div>\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "ImageCropper",
+      "description": "Chooses what a fixed frame keeps of a picture or a video: drag, zoom, keyboard; a focus point and a zoom out.",
+      "props": [
+        {
+          "name": "aspect",
+          "type": "number",
+          "default": null,
+          "description": "The frame's width / height: 1 (a square), 9 / 16 (vertical), 3 (a banner).",
+          "required": true
+        },
+        {
+          "name": "alt",
+          "type": "string",
+          "default": "",
+          "description": "The picture's alternative text, passed translated (empty when the frame's name says enough).",
+          "required": false
+        },
+        {
+          "name": "children",
+          "type": "ReactElement<{ className?: string; style?: CSSProperties; }, string | JSXElementConstructor<any>> | undefined",
+          "default": null,
+          "description": "A media element instead of `src` — a `<video>` to choose the frame of a clip. Its natural size is in `naturalSize`.",
+          "required": false
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Classes merged on the root.",
+          "required": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "CropValue",
+          "default": "{ x: 0.5, y: 0.5, zoom: 1 }",
+          "description": "The crop at first, uncontrolled. Default: centred, no zoom.",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<ImageCropperLabels>",
+          "default": null,
+          "description": "The words, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "maxZoom",
+          "type": "number",
+          "default": "4",
+          "description": "The largest zoom. Default 4.",
+          "required": false
+        },
+        {
+          "name": "naturalSize",
+          "type": "{ width: number; height: number; }",
+          "default": null,
+          "description": "The source's size when `children` is a video: `{ width: video.videoWidth, height: video.videoHeight }`.",
+          "required": false
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: CropValue) => void)",
+          "default": null,
+          "description": "Called on every move.",
+          "required": false
+        },
+        {
+          "name": "round",
+          "type": "boolean",
+          "default": null,
+          "description": "A round mask over the square frame (a profile picture).",
+          "required": false
+        },
+        {
+          "name": "showZoom",
+          "type": "boolean",
+          "default": "true",
+          "description": "Shows the zoom slider under the frame. Default `true`.",
+          "required": false
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "default": null,
+          "description": "The picture to crop. Or `children`: a `<video>` (with the class it is given through `mediaClassName`).",
+          "required": false
+        },
+        {
+          "name": "value",
+          "type": "CropValue",
+          "default": null,
+          "description": "The crop (controlled).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}