makersclaw 0.2.0 → 0.3.0

package/r/file-upload.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "file-upload",
+  "type": "registry:block",
+  "title": "FileUpload",
+  "description": "Files chosen or dropped, each uploaded through your async onUpload(file, { onProgress, signal }) with a progress bar, cancel while it runs, a retry when it fails and a remove once done. Variants: a list of file cards, one file at a time, Uploading/Finished sections, image thumbnails (one or two columns), and a profile picture.",
+  "registryDependencies": [
+    "https://cdn.jsdelivr.net/npm/makersclaw@0.3.0/r/core.json"
+  ],
+  "dependencies": [],
+  "files": [
+    {
+      "path": "registry/blocks/file-upload/index.js",
+      "type": "registry:component",
+      "target": "@components/makersclaw/blocks/file-upload/index.js",
+      "content": "// The FileUpload block — `makersclaw add file-upload`. Fixed: compose it\n// through its props (README.md beside this file); an upload it cannot be\n// is your own component in components/, built on the kit's FileInput.\nexport { FileUpload, formatSize, fileIcon } from \"./file-upload\";\n"
+    },
+    {
+      "path": "registry/blocks/file-upload/file-upload.jsx",
+      "type": "registry:component",
+      "target": "@components/makersclaw/blocks/file-upload/file-upload.jsx",
+      "content": "\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { Avatar, Button, FileDrop, FileInput, IconButton, Image, Item, ItemGroup, Kicker, Notice, Progress, Spinner, cx } from \"../../ui\";\n\n// FileUpload — files chosen or dropped, each one uploaded through the\n// caller's `onUpload(file, { onProgress, signal })`, shown with its bar,\n// a retry when it fails, a cancel while it runs and a remove once done.\n// The picker is the kit's (FileDrop, or FileInput with picker=\"button\");\n// the upload itself is the caller's: storage is the app's, not the block's.\n\n/* ------------------------------------------------------------------------\n   Helpers\n   ------------------------------------------------------------------------ */\n\nconst EXT_TYPES = {\n  png: \"image/png\", jpg: \"image/jpeg\", jpeg: \"image/jpeg\", gif: \"image/gif\", webp: \"image/webp\", svg: \"image/svg+xml\", avif: \"image/avif\",\n  csv: \"text/csv\", xls: \"application/vnd.ms-excel\", xlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n  pdf: \"application/pdf\", doc: \"application/msword\", docx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n  txt: \"text/plain\", md: \"text/markdown\", zip: \"application/zip\", mp4: \"video/mp4\", mov: \"video/quicktime\", mp3: \"audio/mpeg\",\n};\n\n/** The glyph for a file, from its type (or, failing that, its extension). */\nexport function fileIcon(type, name) {\n  const t = type || EXT_TYPES[String(name ?? \"\").split(\".\").pop()?.toLowerCase()] || \"\";\n  if (t.startsWith(\"image/\")) return \"image\";\n  if (t.startsWith(\"video/\") || t.startsWith(\"audio/\")) return \"play\";\n  if (/zip|tar|gzip|compressed|rar|7z/.test(t)) return \"archive\";\n  if (/csv|excel|spreadsheet/.test(t)) return \"grid\";\n  return \"file\";\n}\n\nfunction isImage(type, name) {\n  return fileIcon(type, name) === \"image\";\n}\n\n/** 3_250_000 → \"3.1 MB\"; 900 → \"900 B\". */\nexport function formatSize(bytes) {\n  const n = Number(bytes);\n  if (!Number.isFinite(n) || n < 0) return \"\";\n  if (n < 1024) return `${n} B`;\n  const units = [\"KB\", \"MB\", \"GB\", \"TB\"];\n  let v = n / 1024;\n  let i = 0;\n  for (; v >= 1024 && i < units.length - 1; i++) v /= 1024;\n  return `${v < 10 ? v.toFixed(1).replace(/\\.0$/, \"\") : Math.round(v)} ${units[i]}`;\n}\n\n/** \"image/*,.pdf\" + 10 MB → \"Images, PDF · up to 10 MB\". */\nfunction acceptHint(accept, maxSize) {\n  const parts = [];\n  if (accept) {\n    const kinds = accept\n      .split(\",\")\n      .map((a) => a.trim())\n      .filter(Boolean)\n      .map((a) => (a.endsWith(\"/*\") ? `${a.slice(0, -2)}s` : a.startsWith(\".\") ? a.slice(1).toUpperCase() : a.split(\"/\").pop().replace(/\\+.*$/, \"\").toUpperCase()))\n      .map((k) => k.charAt(0).toUpperCase() + k.slice(1));\n    parts.push([...new Set(kinds)].join(\", \"));\n  }\n  if (maxSize) parts.push(`up to ${formatSize(maxSize)}`);\n  return parts.join(\" · \") || undefined;\n}\n\nconst clamp = (n) => Math.min(100, Math.max(0, Math.round(Number(n) || 0)));\n\n// What the caller hears about a file: never the File, never our state.\nfunction publicFile(item) {\n  const { id, name, size, type, url, meta } = item;\n  return { ...(meta ?? {}), id, name, size, type, url };\n}\n\n/* ------------------------------------------------------------------------\n   The upload queue\n   ------------------------------------------------------------------------ */\n\nfunction useUploads({ defaultFiles, onUpload, onRemove, onChange, autoUpload, thumbs }) {\n  // A default entry with a `file` (a File handed over from a paste or a\n  // drop elsewhere on the page) starts uploading on mount; the rest are\n  // files already uploaded.\n  const [items, setItems] = useState(() =>\n    (defaultFiles ?? []).map((f, i) =>\n      f.file\n        ? { id: f.id ?? `file-${i}`, name: f.file.name, size: f.file.size, type: f.file.type, file: f.file, status: autoUpload ? \"uploading\" : \"queued\", progress: null }\n        : { id: f.id ?? `file-${i}`, name: f.name, size: f.size, type: f.type, url: f.url, status: \"done\", progress: 100 },\n    ),\n  );\n  const seq = useRef(0);\n  const controllers = useRef(new Map());\n  const previews = useRef(new Set());\n  const first = useRef(true);\n  const itemsRef = useRef(items);\n  itemsRef.current = items;\n\n  // Abort what still runs and free the previews when the block leaves.\n  useEffect(() => {\n    const ctl = controllers.current;\n    const urls = previews.current;\n    // Cleared too, so a remount (React's dev double effect) starts afresh.\n    return () => {\n      for (const c of ctl.values()) c.abort();\n      for (const u of urls) URL.revokeObjectURL(u);\n      ctl.clear();\n      urls.clear();\n    };\n  }, []);\n\n  // onChange hears the uploaded list when it changes — not every tick of\n  // a bar.\n  const doneSig = items\n    .filter((i) => i.status === \"done\")\n    .map((i) => `${i.id}\\u0000${i.url ?? \"\"}`)\n    .join(\"\\u0001\");\n  useEffect(() => {\n    if (first.current) {\n      first.current = false;\n      return;\n    }\n    onChange?.(itemsRef.current.filter((i) => i.status === \"done\").map(publicFile));\n    // onChange is the caller's; the uploaded list is what changed.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [doneSig]);\n\n  const patch = (id, next) => setItems((all) => all.map((i) => (i.id === id ? { ...i, ...next } : i)));\n\n  // Handed-over files: their previews, then their uploads.\n  useEffect(() => {\n    for (const it of itemsRef.current) {\n      if (!it.file) continue;\n      if (thumbs && !it.preview && isImage(it.type, it.name) && URL.createObjectURL) {\n        const preview = URL.createObjectURL(it.file);\n        previews.current.add(preview);\n        patch(it.id, { preview });\n      }\n      if (it.status === \"uploading\" && !controllers.current.has(it.id)) start(it);\n    }\n    // Mount only: later files arrive through add().\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  function forget(item) {\n    controllers.current.get(item.id)?.abort();\n    controllers.current.delete(item.id);\n    if (item.preview) {\n      URL.revokeObjectURL(item.preview);\n      previews.current.delete(item.preview);\n    }\n  }\n\n  async function start(item) {\n    if (!item.file) return;\n    if (!onUpload) {\n      // No uploader: the block is only a picker; the file counts as added.\n      patch(item.id, { status: \"done\", progress: 100, url: item.preview });\n      return;\n    }\n    controllers.current.get(item.id)?.abort();\n    const ctl = new AbortController();\n    controllers.current.set(item.id, ctl);\n    patch(item.id, { status: \"uploading\", progress: null, error: null });\n    let res;\n    try {\n      res = await onUpload(item.file, {\n        signal: ctl.signal,\n        onProgress: (p) => {\n          if (!ctl.signal.aborted) patch(item.id, { progress: clamp(p) });\n        },\n      });\n    } catch (e) {\n      res = { ok: false, error: e?.message };\n    }\n    if (ctl.signal.aborted) return;\n    controllers.current.delete(item.id);\n    if (res?.ok) {\n      const { ok, error, url, ...meta } = res;\n      patch(item.id, { status: \"done\", progress: 100, url: url ?? item.url, meta });\n    } else {\n      patch(item.id, { status: \"failed\", error: res?.error || \"The upload failed.\" });\n    }\n  }\n\n  function add(files, { replace = false } = {}) {\n    const fresh = files.map((file) => {\n      seq.current += 1;\n      let preview;\n      if (thumbs && isImage(file.type, file.name) && typeof URL !== \"undefined\" && URL.createObjectURL) {\n        preview = URL.createObjectURL(file);\n        previews.current.add(preview);\n      }\n      return {\n        id: `upload-${seq.current}`,\n        name: file.name,\n        size: file.size,\n        type: file.type,\n        file,\n        preview,\n        status: autoUpload ? \"uploading\" : \"queued\",\n        progress: null,\n      };\n    });\n    if (replace) for (const old of itemsRef.current) forget(old);\n    setItems((all) => (replace ? fresh : [...all, ...fresh]));\n    if (autoUpload) for (const it of fresh) start(it);\n  }\n\n  function cancel(item) {\n    forget(item);\n    setItems((all) => all.filter((i) => i.id !== item.id));\n  }\n\n  async function remove(item) {\n    if (item.status !== \"done\" || !onRemove) return cancel(item);\n    patch(item.id, { removing: true, error: null });\n    let res;\n    try {\n      res = await onRemove(publicFile(item));\n    } catch (e) {\n      res = { ok: false, error: e?.message };\n    }\n    if (res?.ok) cancel(item);\n    else patch(item.id, { removing: false, error: res?.error || \"It could not be removed.\" });\n  }\n\n  function uploadQueued() {\n    for (const it of itemsRef.current) if (it.status === \"queued\") start(it);\n  }\n\n  function clear() {\n    for (const it of itemsRef.current) if (it.status === \"queued\") forget(it);\n    setItems((all) => all.filter((i) => i.status !== \"queued\"));\n  }\n\n  return { items, add, start, cancel, remove, uploadQueued, clear };\n}\n\n/* ------------------------------------------------------------------------\n   One file's row\n   ------------------------------------------------------------------------ */\n\nfunction statusText(item) {\n  const size = formatSize(item.size);\n  const word = {\n    queued: \"Ready to upload\",\n    uploading: \"Uploading…\",\n    done: \"Uploaded\",\n    failed: \"Not uploaded\",\n  }[item.status];\n  return [size, word].filter(Boolean).join(\" · \");\n}\n\nfunction FileRow({ item, look, thumb, onRetry, onCancel, onRemove, disabled }) {\n  const failed = item.status === \"failed\";\n  const running = item.status === \"uploading\";\n  const src = item.preview ?? (isImage(item.type, item.name) ? item.url : undefined);\n  const media =\n    thumb && src && !failed ? (\n      <Image src={src} alt=\"\" ratio=\"photo\" className=\"w-16 shrink-0\" />\n    ) : undefined;\n\n  const actions = (\n    <>\n      {failed && item.file ? (\n        <IconButton icon=\"refresh\" label={`Retry ${item.name}`} size=\"sm\" onClick={() => onRetry(item)} disabled={disabled} />\n      ) : null}\n      {running ? (\n        <IconButton icon=\"x\" label={`Cancel ${item.name}`} size=\"sm\" onClick={() => onCancel(item)} />\n      ) : (\n        <IconButton\n          icon={item.status === \"done\" ? \"trash\" : \"x\"}\n          label={`Remove ${item.name}`}\n          size=\"sm\"\n          loading={item.removing}\n          onClick={() => onRemove(item)}\n          disabled={disabled}\n        />\n      )}\n    </>\n  );\n\n  return (\n    <Item\n      variant={look}\n      icon={media ? undefined : failed ? \"warning\" : fileIcon(item.type, item.name)}\n      media={media}\n      title={item.name}\n      description={statusText(item)}\n      actions={actions}\n      aria-busy={running || undefined}\n    >\n      {running ? (\n        <div className=\"flex items-center gap-3\">\n          <Progress value={item.progress ?? undefined} aria-label={`Uploading ${item.name}`} className=\"min-w-0 flex-1\" />\n          <span data-nums className=\"w-9 shrink-0 text-right text-xs text-muted-foreground\">\n            {item.progress == null ? \"\" : `${item.progress}%`}\n          </span>\n        </div>\n      ) : null}\n      {item.error ? (\n        <p role=\"alert\" className=\"text-xs text-destructive\">\n          {item.error}\n        </p>\n      ) : null}\n    </Item>\n  );\n}\n\n/* ------------------------------------------------------------------------\n   The picture of one person or thing (variant=\"avatar\")\n   ------------------------------------------------------------------------ */\n\nfunction AvatarUpload({ value, name, onUpload, onRemove, onChange, accept, maxSize, label, hint, uploadLabel, disabled, className }) {\n  const [src, setSrc] = useState(value ?? null);\n  const [state, setState] = useState({ busy: false, progress: null, error: null, removing: false });\n  const last = useRef(null);\n  const ctl = useRef(null);\n  const blob = useRef(null);\n\n  useEffect(\n    () => () => {\n      ctl.current?.abort();\n      if (blob.current) URL.revokeObjectURL(blob.current);\n    },\n    [],\n  );\n\n  function show(next) {\n    if (blob.current && blob.current !== next) {\n      URL.revokeObjectURL(blob.current);\n      blob.current = null;\n    }\n    setSrc(next);\n    onChange?.(next);\n  }\n\n  async function upload(file) {\n    if (maxSize && file.size > maxSize) {\n      setState({ busy: false, progress: null, error: `${file.name} is over ${formatSize(maxSize)}.`, removing: false });\n      return;\n    }\n    if (!onUpload) return;\n    last.current = file;\n    ctl.current?.abort();\n    const c = new AbortController();\n    ctl.current = c;\n    setState({ busy: true, progress: null, error: null, removing: false });\n    let res;\n    try {\n      res = await onUpload(file, {\n        signal: c.signal,\n        onProgress: (p) => {\n          if (!c.signal.aborted) setState((s) => ({ ...s, progress: clamp(p) }));\n        },\n      });\n    } catch (e) {\n      res = { ok: false, error: e?.message };\n    }\n    if (c.signal.aborted) return;\n    if (res?.ok) {\n      let url = res.url;\n      if (!url && typeof URL !== \"undefined\" && URL.createObjectURL) {\n        url = URL.createObjectURL(file);\n        blob.current = url;\n      }\n      show(url ?? null);\n      setState({ busy: false, progress: null, error: null, removing: false });\n    } else {\n      setState({ busy: false, progress: null, error: res?.error || \"The picture was not uploaded.\", removing: false });\n    }\n  }\n\n  async function remove() {\n    setState((s) => ({ ...s, removing: true, error: null }));\n    let res = { ok: true };\n    if (onRemove) {\n      try {\n        res = await onRemove();\n      } catch (e) {\n        res = { ok: false, error: e?.message };\n      }\n    }\n    if (res?.ok) {\n      show(null);\n      setState({ busy: false, progress: null, error: null, removing: false });\n    } else setState((s) => ({ ...s, removing: false, error: res?.error || \"The picture was not removed.\" }));\n  }\n\n  return (\n    <div className={cx(\"grid gap-3\", className)} aria-busy={state.busy || undefined}>\n      <div className=\"flex flex-wrap items-center gap-4\">\n        <Avatar name={name} src={src ?? undefined} size=\"lg\" label={name ? `${name}'s picture` : \"Picture\"} />\n        <div className=\"grid min-w-0 flex-1 gap-0.5\">\n          <p className=\"text-sm font-medium text-foreground\">{label}</p>\n          {hint ?? acceptHint(accept, maxSize) ? <p className=\"text-xs text-muted-foreground\">{hint ?? acceptHint(accept, maxSize)}</p> : null}\n        </div>\n        <div className=\"flex flex-wrap gap-2\">\n          <FileInput\n            accept={accept}\n            onFiles={(files) => upload(files[0])}\n            onReject={(files) => setState((s) => ({ ...s, error: `${files[0]?.name ?? \"That file\"} is not a picture this accepts.` }))}\n            disabled={disabled || state.removing}\n            loading={state.busy}\n            variant=\"secondary\"\n            size=\"sm\"\n          >\n            {uploadLabel}\n          </FileInput>\n          {src ? (\n            <Button variant=\"danger\" size=\"sm\" icon=\"trash\" onClick={remove} loading={state.removing} disabled={disabled || state.busy}>\n              Remove\n            </Button>\n          ) : null}\n        </div>\n      </div>\n      {state.busy ? <Progress value={state.progress ?? undefined} aria-label=\"Uploading the picture\" /> : null}\n      {state.error ? (\n        <Notice\n          tone=\"danger\"\n          action={\n            last.current && !state.busy ? (\n              <Button size=\"sm\" variant=\"secondary\" icon=\"refresh\" onClick={() => upload(last.current)}>\n                Retry\n              </Button>\n            ) : null\n          }\n          onDismiss={() => setState((s) => ({ ...s, error: null }))}\n        >\n          {state.error}\n        </Notice>\n      ) : null}\n    </div>\n  );\n}\n\n/* ------------------------------------------------------------------------\n   FileUpload\n   ------------------------------------------------------------------------ */\n\nconst LOOK = { list: \"outline\", single: \"muted\", sections: \"plain\", preview: \"outline\" };\n\nexport function FileUpload({\n  onUpload,\n  onRemove,\n  onChange,\n  variant = \"list\",\n  defaultFiles,\n  accept,\n  multiple,\n  maxSize,\n  maxFiles,\n  autoUpload = true,\n  picker = \"drop\",\n  label,\n  hint,\n  buttonLabel = \"Add files\",\n  uploadLabel,\n  columns = 1,\n  disabled = false,\n  value,\n  name,\n  className,\n  \"aria-label\": ariaLabel,\n}) {\n  if (variant === \"avatar\") {\n    return (\n      <AvatarUpload\n        value={value}\n        name={name}\n        onUpload={onUpload}\n        onRemove={onRemove}\n        onChange={onChange}\n        accept={accept ?? \"image/png,image/jpeg,image/webp\"}\n        maxSize={maxSize}\n        label={label ?? \"Profile picture\"}\n        hint={hint}\n        uploadLabel={uploadLabel ?? \"Upload picture\"}\n        disabled={disabled}\n        className={className}\n      />\n    );\n  }\n  return (\n    <FileList\n      {...{ onUpload, onRemove, onChange, variant, defaultFiles, accept, maxSize, maxFiles, autoUpload, picker, hint, buttonLabel, columns, disabled, className, ariaLabel }}\n      multiple={variant === \"single\" ? false : multiple ?? true}\n      label={label ?? (variant === \"single\" ? \"Drop a file here or browse\" : \"Drop files here or browse\")}\n      uploadLabel={uploadLabel}\n    />\n  );\n}\n\nfunction FileList({\n  onUpload,\n  onRemove,\n  onChange,\n  variant,\n  defaultFiles,\n  accept,\n  multiple,\n  maxSize,\n  maxFiles,\n  autoUpload,\n  picker,\n  label,\n  hint,\n  buttonLabel,\n  uploadLabel,\n  columns,\n  disabled,\n  className,\n  ariaLabel,\n}) {\n  const single = variant === \"single\";\n  const thumbs = variant === \"preview\";\n  const q = useUploads({ defaultFiles, onUpload, onRemove, onChange, autoUpload, thumbs });\n  const [rejected, setRejected] = useState([]);\n  const look = LOOK[variant] ?? LOOK.list;\n  const full = !single && maxFiles && q.items.length >= maxFiles;\n\n  function take(files) {\n    const no = [];\n    let ok = files.filter((f) => {\n      if (maxSize && f.size > maxSize) {\n        no.push({ name: f.name, reason: `over ${formatSize(maxSize)}` });\n        return false;\n      }\n      return true;\n    });\n    if (!single && maxFiles) {\n      const room = Math.max(0, maxFiles - q.items.length);\n      for (const f of ok.slice(room)) no.push({ name: f.name, reason: `only ${maxFiles} ${maxFiles === 1 ? \"file\" : \"files\"} in all` });\n      ok = ok.slice(0, room);\n    }\n    setRejected(no);\n    if (ok.length) q.add(ok, { replace: single });\n  }\n\n  function refuse(files) {\n    setRejected(files.map((f) => ({ name: f.name, reason: \"not a type this accepts\" })));\n  }\n\n  const shownHint = hint ?? acceptHint(accept, maxSize);\n  const door =\n    picker === \"button\" ? (\n      <div className=\"flex flex-wrap items-center gap-x-3 gap-y-1\">\n        <FileInput accept={accept} multiple={multiple} onFiles={take} onReject={refuse} disabled={disabled || full} size=\"sm\">\n          {buttonLabel}\n        </FileInput>\n        {shownHint ? <span className=\"text-xs text-muted-foreground\">{shownHint}</span> : null}\n      </div>\n    ) : (\n      <FileDrop\n        accept={accept}\n        multiple={multiple}\n        onFiles={take}\n        onReject={refuse}\n        disabled={disabled || full}\n        label={full ? `That is ${maxFiles} — remove one to add another` : label}\n        hint={shownHint}\n        size={variant === \"sections\" ? \"sm\" : \"md\"}\n        invalid={rejected.length > 0}\n        aria-label={ariaLabel}\n      />\n    );\n\n  const row = (item) => (\n    <FileRow key={item.id} item={item} look={look} thumb={thumbs} onRetry={q.start} onCancel={q.cancel} onRemove={q.remove} disabled={disabled} />\n  );\n\n  const queued = q.items.filter((i) => i.status === \"queued\");\n  const running = q.items.filter((i) => i.status === \"uploading\" || i.status === \"failed\");\n  const done = q.items.filter((i) => i.status === \"done\");\n\n  let list = null;\n  if (q.items.length && variant === \"sections\") {\n    list = (\n      <div className=\"grid gap-4\">\n        {[\n          { key: \"queued\", label: \"Ready\", rows: queued },\n          { key: \"running\", label: \"Uploading\", rows: running, busy: running.some((i) => i.status === \"uploading\") },\n          { key: \"done\", label: \"Finished\", rows: done },\n        ]\n          .filter((s) => s.rows.length)\n          .map((s) => (\n            <section key={s.key} aria-label={s.label} className=\"grid gap-1\">\n              <div className=\"flex items-center gap-2\">\n                {s.busy ? <Spinner size=\"sm\" label={null} className=\"text-muted-foreground\" /> : null}\n                <Kicker>\n                  {s.label} · {s.rows.length}\n                </Kicker>\n              </div>\n              <ItemGroup aria-label={s.label}>{s.rows.map(row)}</ItemGroup>\n            </section>\n          ))}\n      </div>\n    );\n  } else if (q.items.length) {\n    list = (\n      <ul role=\"list\" aria-label=\"Files\" className={cx(\"grid gap-2\", columns === 2 && \"sm:grid-cols-2\")}>\n        {q.items.map((item) => (\n          <li key={item.id} className=\"min-w-0\">\n            {row(item)}\n          </li>\n        ))}\n      </ul>\n    );\n  }\n\n  return (\n    <div className={cx(\"grid min-w-0 gap-3\", className)}>\n      {door}\n      {rejected.length ? (\n        <Notice tone=\"danger\" title={rejected.length === 1 ? \"One file was not added\" : `${rejected.length} files were not added`} onDismiss={() => setRejected([])}>\n          <ul className=\"grid gap-0.5\">\n            {rejected.map((r, i) => (\n              <li key={i} className=\"break-all\">\n                {r.name} — {r.reason}\n              </li>\n            ))}\n          </ul>\n        </Notice>\n      ) : null}\n      {list}\n      {!autoUpload && queued.length ? (\n        <div className=\"flex flex-wrap justify-end gap-2\">\n          <Button variant=\"quiet\" size=\"sm\" onClick={q.clear}>\n            Clear\n          </Button>\n          <Button variant=\"primary\" size=\"sm\" icon=\"upload\" onClick={q.uploadQueued} disabled={disabled}>\n            {uploadLabel ?? `Upload ${queued.length} ${queued.length === 1 ? \"file\" : \"files\"}`}\n          </Button>\n        </div>\n      ) : null}\n    </div>\n  );\n}\n"
+    },
+    {
+      "path": "registry/blocks/file-upload/README.md",
+      "type": "registry:file",
+      "target": "@components/makersclaw/blocks/file-upload/README.md",
+      "content": "# FileUpload\n\nFiles chosen or dropped, each one uploaded through your `onUpload` as\nsoon as it lands. Every file shows its bar while it runs (with Cancel),\nthe reason and a Retry when it fails, and a Remove once it is up. Files\nthe picker refuses (wrong type, too big, too many) are named in a notice.\nThe upload itself is yours: the block never fetches.\n\n```jsx\nimport { FileUpload } from \"../components/blocks/file-upload\";   // a Makersclaw app (\"./blocks/file-upload\" from components/)\nimport { FileUpload } from \"@/components/makersclaw/blocks/file-upload\";   // a shadcn project\n```\n\nA client component. The picker is the kit's `FileDrop` (or `FileInput`\nwith `picker=\"button\"`), so the browser's own file dialog opens and the\nkeyboard works: Tab to the zone, Enter or Space.\n\n## The data\n\nWhat the block tells you about a file (in `onChange` and `onRemove`):\n`{ id, name, size, type, url?, ...whatever your onUpload returned }`.\nNever the `File` and never the block's own state.\n\n## Props\n\n- `onUpload(file, { onProgress, signal })` — upload one `File`. Call\n  `onProgress(percent)` (0–100) as it goes; without it the bar sweeps.\n  Watch `signal` (an AbortSignal): it aborts when the person cancels or\n  replaces the file, and pass it to `fetch`. Return `{ ok: true, url?,\n  ...anything }` or `{ ok: false, error }`; a throw counts as failed and\n  its message is shown. Without `onUpload` the block is a picker only:\n  files count as added at once.\n- `variant` — how the files show, default `\"list\"`:\n  - `list` — the drop zone, then a card per file (name, size, state).\n  - `single` — one file at a time in a filled panel; a new pick replaces\n    it (and aborts its upload). An import, a contract.\n  - `sections` — a one-row drop zone, then the files grouped under\n    \"Ready\", \"Uploading\" (failed ones stay here with Retry) and\n    \"Finished\".\n  - `preview` — cards with the picture itself for images. `columns={2}`\n    lays them two across from 640px.\n  - `avatar` — one picture of a person or a company: the current one (or\n    the initials), Upload picture, Remove. Takes `value` (the current\n    URL) and `name`; `onChange(url | null)`.\n- `onRemove(file)` — delete an uploaded file from storage; return\n  `{ ok }` like `onUpload`. The row shows a spinner, and on failure stays\n  with the reason. Without it Remove only drops the row. Removing a file\n  that is still queued, uploading or failed never calls it.\n- `onChange(files)` — the uploaded files, every time that list changes.\n  Save their ids or URLs with the record here.\n- `defaultFiles` — what shows at first: files already uploaded\n  (`[{ id, name, size, type, url? }]`). An entry that is `{ id?, file }`\n  (a `File` you got from a paste or a drop elsewhere on the page) starts\n  uploading on mount.\n- `accept` — as the input's: `\"image/*\"`, `\".csv,.xlsx\"`. The picker\n  greys out the rest; a drop of the rest is refused and named.\n- `multiple` — default `true` (`false` for `single` and `avatar`).\n- `maxSize` — bytes, per file. Bigger files are refused and named.\n- `maxFiles` — how many in all; the zone says so when it is full.\n- `autoUpload` — default `true`. `false` holds new files as \"Ready to\n  upload\" with Clear and an \"Upload N files\" button, for a form that\n  sends its attachments on submit.\n- `picker` — `\"drop\"` (default: the drop zone) · `\"button\"` (a\n  `FileInput` button and the hint beside it, for a tight form row).\n- `label` — the zone's line (default \"Drop files here or browse\"); in\n  `avatar`, the name beside the picture (\"Profile picture\").\n- `hint` — the muted line: default built from `accept` and `maxSize`\n  (\"Images · up to 4 MB\").\n- `buttonLabel` — `picker=\"button\"`'s text, default \"Add files\".\n- `uploadLabel` — the queue's submit text, or `avatar`'s button text.\n- `columns` — `1` (default) or `2`, for `list` and `preview`.\n- `disabled` — no picking, no retry, no remove.\n- `aria-label` — the drop zone's name when `label` is not enough.\n- `className` — layout around it. Never colour.\n\n`formatSize(bytes)` (\"3.1 MB\") and `fileIcon(type, name)` (the kit icon\nfor a file) are exported too, for your own file rows.\n\n## Example\n\n```jsx\n// components/DealFiles.jsx — client\n\"use client\";\nimport { FileUpload } from \"./blocks/file-upload\";\n\n// Your storage route answers a PUT with { id, url }. XMLHttpRequest, not\n// fetch, because only it reports upload progress.\nfunction put(file, { onProgress, signal }) {\n  return new Promise((resolve) => {\n    const xhr = new XMLHttpRequest();\n    xhr.open(\"PUT\", `/api/files?name=${encodeURIComponent(file.name)}`);\n    xhr.upload.onprogress = (e) => e.lengthComputable && onProgress((e.loaded / e.total) * 100);\n    xhr.onload = () =>\n      xhr.status < 300 ? resolve({ ok: true, ...JSON.parse(xhr.responseText) }) : resolve({ ok: false, error: `Upload failed (${xhr.status}).` });\n    xhr.onerror = () => resolve({ ok: false, error: \"The connection dropped. Try again.\" });\n    signal.addEventListener(\"abort\", () => xhr.abort());\n    xhr.send(file);\n  });\n}\n\nexport default function DealFiles({ deal, onSaveFiles }) {\n  return (\n    <FileUpload\n      defaultFiles={deal.files}\n      onUpload={put}\n      onRemove={(f) => fetch(`/api/files/${f.id}`, { method: \"DELETE\" }).then((r) => ({ ok: r.ok }))}\n      onChange={(files) => onSaveFiles(files.map((f) => ({ id: f.id, name: f.name, size: f.size, url: f.url })))}\n      maxSize={50 * 1024 * 1024}\n    />\n  );\n}\n```\n\nOne spreadsheet to import, and a profile picture:\n\n```jsx\n<FileUpload variant=\"single\" accept=\".csv,.xlsx\" maxSize={10 * 1024 * 1024} onUpload={put} onChange={([f]) => setImport(f ?? null)} />\n\n<FileUpload variant=\"avatar\" name={me.name} value={me.avatarUrl} onUpload={put} onChange={(url) => saveProfile({ avatar_url: url })} />\n```\n\n## What it will not do\n\n- Store anything: `onUpload` is yours (a storage bucket, a signed URL).\n- Crop or resize a picture, or read a spreadsheet's rows: do that in\n  `onUpload` or after `onChange`.\n- Reorder files, or keep a list you control from outside: `defaultFiles`\n  is where it starts; remount it (a `key`) to start again.\n- Show a chat message's attachments: that is the chat block's composer.\n\nA file picker it cannot be is your own component in `components/`,\nbuilt on the kit's `FileInput` or `FileDrop` — not an edit to this\nblock. Its files are fixed: `npm run check` refuses a change, and\n`makersclaw add file-upload` restores them.\n\n## Credits\n\nPorted from blocks.so (https://blocks.so, file-upload 01, 03–06, MIT) and Creative Tim UI (https://github.com/creativetimofficial/ui, modals-05 and account-avatar-upload-01, MIT), rewritten on the Makersclaw kit.\n"
+    }
+  ],
+  "categories": [
+    "file",
+    "upload",
+    "dropzone",
+    "drag",
+    "drop",
+    "attachment",
+    "progress",
+    "image",
+    "photo",
+    "avatar",
+    "profile picture",
+    "csv",
+    "import",
+    "retry"
+  ],
+  "docs": "Installed to components/makersclaw/blocks/file-upload. Import: import { FileUpload, formatSize, fileIcon } from \"@/components/makersclaw/blocks/file-upload\". Props and an example: components/makersclaw/blocks/file-upload/README.md. Makersclaw builds whole apps from these blocks: https://makersclaw.com",
+  "meta": {
+    "makersclaw": {
+      "version": "0.3.0",
+      "useWhen": "A form or page takes files the app stores: attachments on a record, a CSV to import, product photos, a logo, a profile picture. Not for showing files already stored with no way to add (a table or list), and not for a chat message's attachments (the chat block's composer has those)."
+    }
+  }
+}