@epicbagel/saas-kit 1.1.0 → 1.2.1

package/dist/primitives/file-dropzone.d.cts

@@ -1,5 +1,6 @@
+import * as React from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
 
 interface FileDropzoneBaseProps {
     accept?: string;
@@ -29,8 +30,70 @@ type FileDropzoneProps = SingleFileDropzoneProps | MultiFileDropzoneProps;
  *
  * The primitive owns the hidden native input, focus state, drag state and
  * async busy state. It deliberately does not parse, upload or validate file
- * contents; those remain consumer concerns.
+ * contents; those remain consumer concerns. It installs `useFileDropGuard`,
+ * so a file dropped just beside it never opens in the browser.
  */
 declare function FileDropzone({ onFile, onFiles, multiple, accept, disabled, busy: externalBusy, label, description, busyLabel, icon, variant, className, }: FileDropzoneProps): react_jsx_runtime.JSX.Element;
+/**
+ * Makes sure a file dropped where nothing takes it never opens or downloads
+ * in the browser, which is what a browser does by default with a file
+ * dropped on a page. Returns the function that removes it again.
+ *
+ * Listens on `window`, after every other handler: a drag or a drop that a
+ * drop target has already accepted (`preventDefault`) is left alone, and so
+ * is a native `<input type="file">`, which takes its own drop. Any other file
+ * drag is cancelled, with the "no drop" cursor.
+ *
+ * Call it once in an app's entry, before rendering: it lives outside React,
+ * so a render error, an error boundary's fallback or an unmounted root never
+ * takes it away. `useFileDropGuard` is the same guard for a component's
+ * lifetime.
+ */
+declare function installFileDropGuard(): () => void;
+/**
+ * `installFileDropGuard` while the component is mounted (and `enabled`).
+ * `FileDropzone` and `FileDropArea` install it themselves. For a whole app,
+ * prefer `installFileDropGuard()` in the entry: a hook in the app's root
+ * component goes when a render error unmounts it.
+ */
+declare function useFileDropGuard(enabled?: boolean): void;
+interface FileDropAreaProps extends Omit<HTMLAttributes<HTMLDivElement>, "onDrop"> {
+    /**
+     * Every dropped file, unfiltered: the callback the region's file picker
+     * calls, so the caller validates types, sizes and counts and reports its
+     * own errors. Without it the area is a plain div and installs no guard.
+     */
+    onFiles?: (files: File[]) => void | Promise<void>;
+    /** The overlay stays down and drops are ignored; the page guard stays on. */
+    disabled?: boolean;
+    /**
+     * `area` (the default): a file dragged over this element raises an overlay
+     * over it, and a drop on it lands here. `page`: a file dragged anywhere in
+     * the document raises an overlay over the whole viewport, and a drop
+     * anywhere lands here.
+     */
+    scope?: "area" | "page";
+    /** The overlay's label. Defaults to "Drop to attach". */
+    label?: ReactNode;
+    /** A muted line under the label, such as the accepted types and limits. */
+    description?: ReactNode;
+    /** The overlay's icon. Defaults to the upload icon `FileDropzone` shows. */
+    icon?: ReactNode;
+}
+/**
+ * A region that takes files dragged onto it. While a file is dragged over
+ * it, an overlay covers it ("Drop to attach"), and a drop hands every file to
+ * `onFiles`, the callback its file picker already calls. A file dropped
+ * anywhere else in the page never opens in the browser (`useFileDropGuard`).
+ *
+ * The label stays on screen however the region sits: an area taller than the
+ * viewport centres it in the part that shows, and `scope="page"` covers the
+ * viewport itself, wherever in the page the region is.
+ *
+ * The overlay is decorative (`aria-hidden`): keep a picker in the region as
+ * the accessible way to add files. A drop target inside it (a
+ * `FileDropzone`) keeps its own drops, so a file is never delivered twice.
+ */
+declare const FileDropArea: React.ForwardRefExoticComponent<FileDropAreaProps & React.RefAttributes<HTMLDivElement>>;
 
-export { FileDropzone, type FileDropzoneProps };
+export { FileDropArea, type FileDropAreaProps, FileDropzone, type FileDropzoneProps, installFileDropGuard, useFileDropGuard };

package/dist/primitives/file-dropzone.d.ts

@@ -1,5 +1,6 @@
+import * as React from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
 
 interface FileDropzoneBaseProps {
     accept?: string;
@@ -29,8 +30,70 @@ type FileDropzoneProps = SingleFileDropzoneProps | MultiFileDropzoneProps;
  *
  * The primitive owns the hidden native input, focus state, drag state and
  * async busy state. It deliberately does not parse, upload or validate file
- * contents; those remain consumer concerns.
+ * contents; those remain consumer concerns. It installs `useFileDropGuard`,
+ * so a file dropped just beside it never opens in the browser.
  */
 declare function FileDropzone({ onFile, onFiles, multiple, accept, disabled, busy: externalBusy, label, description, busyLabel, icon, variant, className, }: FileDropzoneProps): react_jsx_runtime.JSX.Element;
+/**
+ * Makes sure a file dropped where nothing takes it never opens or downloads
+ * in the browser, which is what a browser does by default with a file
+ * dropped on a page. Returns the function that removes it again.
+ *
+ * Listens on `window`, after every other handler: a drag or a drop that a
+ * drop target has already accepted (`preventDefault`) is left alone, and so
+ * is a native `<input type="file">`, which takes its own drop. Any other file
+ * drag is cancelled, with the "no drop" cursor.
+ *
+ * Call it once in an app's entry, before rendering: it lives outside React,
+ * so a render error, an error boundary's fallback or an unmounted root never
+ * takes it away. `useFileDropGuard` is the same guard for a component's
+ * lifetime.
+ */
+declare function installFileDropGuard(): () => void;
+/**
+ * `installFileDropGuard` while the component is mounted (and `enabled`).
+ * `FileDropzone` and `FileDropArea` install it themselves. For a whole app,
+ * prefer `installFileDropGuard()` in the entry: a hook in the app's root
+ * component goes when a render error unmounts it.
+ */
+declare function useFileDropGuard(enabled?: boolean): void;
+interface FileDropAreaProps extends Omit<HTMLAttributes<HTMLDivElement>, "onDrop"> {
+    /**
+     * Every dropped file, unfiltered: the callback the region's file picker
+     * calls, so the caller validates types, sizes and counts and reports its
+     * own errors. Without it the area is a plain div and installs no guard.
+     */
+    onFiles?: (files: File[]) => void | Promise<void>;
+    /** The overlay stays down and drops are ignored; the page guard stays on. */
+    disabled?: boolean;
+    /**
+     * `area` (the default): a file dragged over this element raises an overlay
+     * over it, and a drop on it lands here. `page`: a file dragged anywhere in
+     * the document raises an overlay over the whole viewport, and a drop
+     * anywhere lands here.
+     */
+    scope?: "area" | "page";
+    /** The overlay's label. Defaults to "Drop to attach". */
+    label?: ReactNode;
+    /** A muted line under the label, such as the accepted types and limits. */
+    description?: ReactNode;
+    /** The overlay's icon. Defaults to the upload icon `FileDropzone` shows. */
+    icon?: ReactNode;
+}
+/**
+ * A region that takes files dragged onto it. While a file is dragged over
+ * it, an overlay covers it ("Drop to attach"), and a drop hands every file to
+ * `onFiles`, the callback its file picker already calls. A file dropped
+ * anywhere else in the page never opens in the browser (`useFileDropGuard`).
+ *
+ * The label stays on screen however the region sits: an area taller than the
+ * viewport centres it in the part that shows, and `scope="page"` covers the
+ * viewport itself, wherever in the page the region is.
+ *
+ * The overlay is decorative (`aria-hidden`): keep a picker in the region as
+ * the accessible way to add files. A drop target inside it (a
+ * `FileDropzone`) keeps its own drops, so a file is never delivered twice.
+ */
+declare const FileDropArea: React.ForwardRefExoticComponent<FileDropAreaProps & React.RefAttributes<HTMLDivElement>>;
 
-export { FileDropzone, type FileDropzoneProps };
+export { FileDropArea, type FileDropAreaProps, FileDropzone, type FileDropzoneProps, installFileDropGuard, useFileDropGuard };

package/dist/primitives/file-dropzone.js

@@ -1,12 +1,18 @@
 "use client";
 "use client";
 import {
-  FileDropzone
-} from "../chunk-6V4XMQ6D.js";
+  FileDropArea,
+  FileDropzone,
+  installFileDropGuard,
+  useFileDropGuard
+} from "../chunk-M7FYGAGO.js";
 import "../chunk-EIY5LLSP.js";
 import "../chunk-ZRLUUZHK.js";
 import "../chunk-HQRWRRZJ.js";
 import "../chunk-G6SRSWXB.js";
 export {
-  FileDropzone
+  FileDropArea,
+  FileDropzone,
+  installFileDropGuard,
+  useFileDropGuard
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicbagel/saas-kit",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Accessible React primitives, layout components and design tokens for SaaS apps, built on Radix UI and Tailwind CSS v4.",
   "license": "MIT",
   "keywords": [

package/dist/chunk-6V4XMQ6D.js

@@ -1,118 +0,0 @@
-"use client";
-import {
-  Text
-} from "./chunk-EIY5LLSP.js";
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger
-} from "./chunk-ZRLUUZHK.js";
-import {
-  Button
-} from "./chunk-HQRWRRZJ.js";
-import {
-  cn
-} from "./chunk-G6SRSWXB.js";
-
-// src/primitives/file-dropzone.tsx
-import { FileUp, Loader2 } from "lucide-react";
-import { useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-function FileDropzone({
-  onFile,
-  onFiles,
-  multiple = false,
-  accept,
-  disabled = false,
-  busy: externalBusy = false,
-  label = "Drop a file, or choose one",
-  description,
-  busyLabel = "Reading file\u2026",
-  icon,
-  variant = "dropzone",
-  className
-}) {
-  const inputRef = useRef(null);
-  const [dragging, setDragging] = useState(false);
-  const [internalBusy, setInternalBusy] = useState(false);
-  const busy = externalBusy || internalBusy;
-  async function select(files) {
-    if (files.length === 0 || disabled || busy) return;
-    setInternalBusy(true);
-    try {
-      if (multiple) {
-        await onFiles?.(files);
-      } else {
-        const first = files[0];
-        if (first) await onFile?.(first);
-      }
-    } finally {
-      setInternalBusy(false);
-      if (inputRef.current) inputRef.current.value = "";
-    }
-  }
-  function onDrop(event) {
-    event.preventDefault();
-    setDragging(false);
-    void select(Array.from(event.dataTransfer.files ?? []));
-  }
-  const trigger = /* @__PURE__ */ jsxs(
-    Button,
-    {
-      type: "button",
-      "data-file-dropzone": "true",
-      variant: "outline",
-      size: variant === "icon" ? "icon" : "default",
-      "aria-label": variant === "icon" ? String(busy ? busyLabel : label) : void 0,
-      disabled: disabled || busy,
-      onClick: () => inputRef.current?.click(),
-      onDragEnter: (event) => {
-        event.preventDefault();
-        setDragging(true);
-      },
-      onDragOver: (event) => {
-        event.preventDefault();
-        setDragging(true);
-      },
-      onDragLeave: () => setDragging(false),
-      onDrop,
-      className: cn(
-        variant === "dropzone" ? "h-auto w-full flex-col whitespace-normal border-2 border-dashed px-6 py-8 text-center" : variant === "button" ? "w-fit" : "",
-        dragging && "border-primary bg-primary/5",
-        className
-      ),
-      children: [
-        /* @__PURE__ */ jsx("span", { className: cn(
-          "flex items-center justify-center text-muted-foreground",
-          variant === "dropzone" && "mb-2 h-10 w-10 rounded-full bg-muted"
-        ), children: busy ? /* @__PURE__ */ jsx(Loader2, { className: "h-5 w-5 animate-spin" }) : icon ?? /* @__PURE__ */ jsx(FileUp, { className: "h-5 w-5" }) }),
-        /* @__PURE__ */ jsx("span", { className: variant === "icon" ? "sr-only" : "font-medium", children: busy ? busyLabel : label }),
-        description && variant === "dropzone" && /* @__PURE__ */ jsx(Text, { variant: "muted", className: "mt-1 max-w-md text-xs", children: description })
-      ]
-    }
-  );
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx(
-      "input",
-      {
-        ref: inputRef,
-        type: "file",
-        accept,
-        multiple,
-        disabled: disabled || busy,
-        onChange: (event) => void select(Array.from(event.target.files ?? [])),
-        className: "sr-only",
-        tabIndex: -1,
-        "aria-hidden": "true"
-      }
-    ),
-    variant === "icon" && description ? /* @__PURE__ */ jsxs(Tooltip, { children: [
-      /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: trigger }),
-      /* @__PURE__ */ jsx(TooltipContent, { children: description })
-    ] }) : trigger
-  ] });
-}
-
-export {
-  FileDropzone
-};

package/dist/chunk-I5UQSBBZ.cjs

@@ -1,118 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }"use client";
-
-
-var _chunk373W6VADcjs = require('./chunk-373W6VAD.cjs');
-
-
-
-
-var _chunkU2NES7VRcjs = require('./chunk-U2NES7VR.cjs');
-
-
-var _chunkL4DH72UFcjs = require('./chunk-L4DH72UF.cjs');
-
-
-var _chunkKWLSBTB2cjs = require('./chunk-KWLSBTB2.cjs');
-
-// src/primitives/file-dropzone.tsx
-var _lucidereact = require('lucide-react');
-var _react = require('react');
-var _jsxruntime = require('react/jsx-runtime');
-function FileDropzone({
-  onFile,
-  onFiles,
-  multiple = false,
-  accept,
-  disabled = false,
-  busy: externalBusy = false,
-  label = "Drop a file, or choose one",
-  description,
-  busyLabel = "Reading file\u2026",
-  icon,
-  variant = "dropzone",
-  className
-}) {
-  const inputRef = _react.useRef.call(void 0, null);
-  const [dragging, setDragging] = _react.useState.call(void 0, false);
-  const [internalBusy, setInternalBusy] = _react.useState.call(void 0, false);
-  const busy = externalBusy || internalBusy;
-  async function select(files) {
-    if (files.length === 0 || disabled || busy) return;
-    setInternalBusy(true);
-    try {
-      if (multiple) {
-        await _optionalChain([onFiles, 'optionalCall', _ => _(files)]);
-      } else {
-        const first = files[0];
-        if (first) await _optionalChain([onFile, 'optionalCall', _2 => _2(first)]);
-      }
-    } finally {
-      setInternalBusy(false);
-      if (inputRef.current) inputRef.current.value = "";
-    }
-  }
-  function onDrop(event) {
-    event.preventDefault();
-    setDragging(false);
-    void select(Array.from(_nullishCoalesce(event.dataTransfer.files, () => ( []))));
-  }
-  const trigger = /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, 
-    _chunkL4DH72UFcjs.Button,
-    {
-      type: "button",
-      "data-file-dropzone": "true",
-      variant: "outline",
-      size: variant === "icon" ? "icon" : "default",
-      "aria-label": variant === "icon" ? String(busy ? busyLabel : label) : void 0,
-      disabled: disabled || busy,
-      onClick: () => _optionalChain([inputRef, 'access', _3 => _3.current, 'optionalAccess', _4 => _4.click, 'call', _5 => _5()]),
-      onDragEnter: (event) => {
-        event.preventDefault();
-        setDragging(true);
-      },
-      onDragOver: (event) => {
-        event.preventDefault();
-        setDragging(true);
-      },
-      onDragLeave: () => setDragging(false),
-      onDrop,
-      className: _chunkKWLSBTB2cjs.cn.call(void 0, 
-        variant === "dropzone" ? "h-auto w-full flex-col whitespace-normal border-2 border-dashed px-6 py-8 text-center" : variant === "button" ? "w-fit" : "",
-        dragging && "border-primary bg-primary/5",
-        className
-      ),
-      children: [
-        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, "span", { className: _chunkKWLSBTB2cjs.cn.call(void 0, 
-          "flex items-center justify-center text-muted-foreground",
-          variant === "dropzone" && "mb-2 h-10 w-10 rounded-full bg-muted"
-        ), children: busy ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.Loader2, { className: "h-5 w-5 animate-spin" }) : _nullishCoalesce(icon, () => ( /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.FileUp, { className: "h-5 w-5" }))) }),
-        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, "span", { className: variant === "icon" ? "sr-only" : "font-medium", children: busy ? busyLabel : label }),
-        description && variant === "dropzone" && /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk373W6VADcjs.Text, { variant: "muted", className: "mt-1 max-w-md text-xs", children: description })
-      ]
-    }
-  );
-  return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
-    /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-      "input",
-      {
-        ref: inputRef,
-        type: "file",
-        accept,
-        multiple,
-        disabled: disabled || busy,
-        onChange: (event) => void select(Array.from(_nullishCoalesce(event.target.files, () => ( [])))),
-        className: "sr-only",
-        tabIndex: -1,
-        "aria-hidden": "true"
-      }
-    ),
-    variant === "icon" && description ? /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkU2NES7VRcjs.Tooltip, { children: [
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkU2NES7VRcjs.TooltipTrigger, { asChild: true, children: trigger }),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkU2NES7VRcjs.TooltipContent, { children: description })
-    ] }) : trigger
-  ] });
-}
-
-
-
-exports.FileDropzone = FileDropzone;