components/drop-zone/drop-zone.ts

Functions

Imports

It imports no other module of this repo. Imported by components/drop-zone/drop-zone.react.tsx, components/media-library/media-library.ts.

Source

1// The drop zone: choose files by browsing or by dropping them, check them against the rules
2// (type, size, count) and say, in words, which were taken and which were not and why. The
3// real <input type="file"> is the control, so click, Enter and Space open the picker with no
4// script; this module adds drop (on the zone, or anywhere on the page), paste, and the checks.
5// A dragenter depth counter keeps the page-wide target steady, and a drop off the zone never
6// navigates away. Every file is checked and each refusal named. No framework; the React wrapper uses the same pure functions.
7
8const READY = "data-cap-ready";
9
10// ---------------------------------------------------------------------------------------
11// The rules, pure. They take anything shaped like a File, so they run anywhere.
12
13export interface FileLike {
14  name: string;
15  type: string;
16  size: number;
17}
18
19export interface DropRules {
20  // The same list the input's accept attribute takes: ".pdf", "image/*", "image/png".
21  accept?: string;
22  // The largest file, in bytes. Absent or 0: no limit.
23  maxBytes?: number;
24  // The most files taken at once. Absent: no limit.
25  maxFiles?: number;
26}
27
28export type RejectReason = "type" | "size" | "count";
29
30export interface Rejection<F extends FileLike = File> {
31  file: F;
32  reason: RejectReason;
33  // A whole sentence naming the file and the reason.
34  message: string;
35}
36
37export interface Validation<F extends FileLike = File> {
38  accepted: F[];
39  rejected: Array<Rejection<F>>;
40}
41
42// "image/*, .pdf" gives ["image/*", ".pdf"], lower-cased.
43export function parseAccept(accept: string | null | undefined): string[] {
44  return (accept ?? "")
45    .split(",")
46    .map((s) => s.trim().toLowerCase())
47    .filter(Boolean);
48}
49
50// The platform's rule for accept: an extension, a type with a wildcard, or an exact type.
51export function matchesAccept(file: Pick<FileLike, "name" | "type">, accept: string | null | undefined): boolean {
52  const list = parseAccept(accept);
53  if (list.length === 0) return true;
54  const name = file.name.toLowerCase();
55  const type = file.type.toLowerCase();
56  return list.some((rule) => {
57    if (rule.startsWith(".")) return name.endsWith(rule);
58    if (rule.endsWith("/*")) return type.startsWith(rule.slice(0, -1));
59    return type === rule;
60  });
61}
62
63const KIND_NAMES: Record<string, string> = {
64  "image/*": "images",
65  "image/jpeg": "JPEG",
66  "image/png": "PNG",
67  "image/webp": "WebP",
68  "image/gif": "GIF",
69  "image/avif": "AVIF",
70  "image/svg+xml": "SVG",
71  "application/pdf": "PDF",
72  "video/*": "video",
73  "audio/*": "audio",
74  "text/plain": "text",
75  "text/markdown": "Markdown",
76};
77
78// The accept list as a person would say it: "images and PDF", "JPEG, PNG and WebP".
79export function acceptLabel(accept: string | null | undefined): string {
80  const names: string[] = [];
81  for (const rule of parseAccept(accept)) {
82    const name = KIND_NAMES[rule] ?? (rule.startsWith(".") ? rule.slice(1).toUpperCase() : rule);
83    if (!names.includes(name)) names.push(name);
84  }
85  if (names.length === 0) return "any file";
86  if (names.length === 1) return names[0] ?? "";
87  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
88}
89
90// A size as a person reads it. Binary division, as the site's media page states sizes.
91export function formatBytes(size: number): string {
92  if (size < 1024) return `${size} B`;
93  if (size < 1024 * 1024) return `${Math.round(size / 1024)} kB`;
94  const mb = size / (1024 * 1024);
95  return `${mb >= 100 ? Math.round(mb) : mb.toFixed(1).replace(/\.0$/, "")} MB`;
96}
97
98export function rejectionMessage(file: FileLike, reason: RejectReason, rules: DropRules): string {
99  if (reason === "type") return `${file.name}: type not allowed. This takes ${acceptLabel(rules.accept)}.`;
100  if (reason === "size") return `${file.name}: too big at ${formatBytes(file.size)}. The limit is ${formatBytes(rules.maxBytes ?? 0)}.`;
101  const n = rules.maxFiles ?? 0;
102  return `${file.name}: too many files. The limit is ${n} ${n === 1 ? "file" : "files"} at a time, so this one was left out.`;
103}
104
105// Checks every file, in order. A file is refused for its type first, then its size; the files
106// that pass are counted, and any beyond maxFiles are refused as too many. Nothing is dropped
107// silently: every refusal comes back with a sentence that names the file.
108export function validateFiles<F extends FileLike>(files: Iterable<F> | ArrayLike<F>, rules: DropRules = {}): Validation<F> {
109  const accepted: F[] = [];
110  const rejected: Array<Rejection<F>> = [];
111  const refuse = (file: F, reason: RejectReason) => rejected.push({ file, reason, message: rejectionMessage(file, reason, rules) });
112  for (const file of Array.from(files as ArrayLike<F>)) {
113    if (!matchesAccept(file, rules.accept)) refuse(file, "type");
114    else if (rules.maxBytes && file.size > rules.maxBytes) refuse(file, "size");
115    else if (rules.maxFiles != null && rules.maxFiles > 0 && accepted.length >= rules.maxFiles) refuse(file, "count");
116    else accepted.push(file);
117  }
118  return { accepted, rejected };
119}
120
121// The words for what was taken: "photo.jpg is ready to upload", "3 files are ready to upload".
122export function acceptedText(files: readonly FileLike[]): string {
123  if (files.length === 0) return "";
124  if (files.length === 1) return `${files[0]?.name ?? "The file"} is ready to upload.`;
125  return `${files.length} files are ready to upload.`;
126}
127
128// "1 file was not added", "3 files were not added".
129export function rejectedLead(count: number): string {
130  return count === 1 ? "1 file was not added" : `${count} files were not added`;
131}
132
133// True while the pointer carries files (and not a dragged link or a selection of text).
134export function dragHasFiles(e: Pick<DragEvent, "dataTransfer">): boolean {
135  const types = e.dataTransfer?.types;
136  return !!types && Array.from(types).includes("Files");
137}
138
139// Puts files into the input, so a form posts them. Returns false where the browser cannot.
140export function setInputFiles(input: HTMLInputElement, files: readonly File[]): boolean {
141  try {
142    const transfer = new DataTransfer();
143    for (const f of files) transfer.items.add(f);
144    input.files = transfer.files;
145    return true;
146  } catch {
147    return false;
148  }
149}
150
151// ---------------------------------------------------------------------------------------
152// The DOM.
153
154export interface DropDetail {
155  accepted: File[];
156  rejected: Array<Rejection>;
157}
158
159const CRIT_GLYPH = "M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z";
160
161function glyph(): SVGSVGElement {
162  const ns = "http://www.w3.org/2000/svg";
163  const svg = document.createElementNS(ns, "svg");
164  svg.setAttribute("class", "cap-status-glyph");
165  svg.setAttribute("viewBox", "0 0 16 16");
166  svg.setAttribute("aria-hidden", "true");
167  svg.setAttribute("focusable", "false");
168  const p = document.createElementNS(ns, "path");
169  p.setAttribute("fill", "currentColor");
170  p.setAttribute("fill-rule", "evenodd");
171  p.setAttribute("d", CRIT_GLYPH);
172  svg.append(p);
173  return svg;
174}
175
176const part = <T extends HTMLElement = HTMLElement>(zone: HTMLElement, name: string) => zone.querySelector<T>(`[data-cap-part='${name}']`);
177
178// The rules a zone states: accept from its input, limits from its data attributes. A zone
179// that takes one file (no multiple attribute) takes at most one.
180export function rulesOf(zone: HTMLElement): DropRules {
181  const input = part<HTMLInputElement>(zone, "input");
182  const maxBytes = Number(zone.dataset.maxBytes);
183  const maxFiles = Number(zone.dataset.maxFiles);
184  const rules: DropRules = { accept: input?.getAttribute("accept") ?? zone.dataset.accept ?? "" };
185  if (Number.isFinite(maxBytes) && maxBytes > 0) rules.maxBytes = maxBytes;
186  if (Number.isFinite(maxFiles) && maxFiles > 0) rules.maxFiles = maxFiles;
187  else if (input && !input.multiple) rules.maxFiles = 1;
188  return rules;
189}
190
191function render(zone: HTMLElement, result: Validation): void {
192  const status = part(zone, "status");
193  const alert = part(zone, "rejections");
194  if (status) {
195    if (result.accepted.length === 0) status.replaceChildren();
196    else {
197      const lead = document.createElement("p");
198      lead.className = "cap-drop-lead";
199      lead.textContent = acceptedText(result.accepted);
200      const list = document.createElement("ul");
201      list.className = "cap-drop-files";
202      for (const f of result.accepted) {
203        const li = document.createElement("li");
204        const name = document.createElement("span");
205        name.className = "cap-drop-file-name";
206        name.textContent = f.name;
207        const size = document.createElement("span");
208        size.className = "cap-drop-file-size";
209        size.textContent = formatBytes(f.size);
210        li.append(name, size);
211        list.append(li);
212      }
213      status.replaceChildren(lead, list);
214    }
215  }
216  if (alert) {
217    if (result.rejected.length === 0) alert.replaceChildren();
218    else {
219      const lead = document.createElement("p");
220      lead.className = "cap-drop-lead";
221      lead.dataset.tone = "crit";
222      lead.append(glyph(), document.createTextNode(rejectedLead(result.rejected.length)));
223      const list = document.createElement("ul");
224      list.className = "cap-drop-files";
225      for (const r of result.rejected) {
226        const li = document.createElement("li");
227        li.textContent = r.message;
228        list.append(li);
229      }
230      alert.replaceChildren(lead, list);
231    }
232  }
233  setState(zone, result.rejected.length > 0 ? "rejected" : "idle");
234}
235
236type ZoneState = "idle" | "over" | "rejected";
237const resting = new WeakMap<HTMLElement, ZoneState>();
238
239function setState(zone: HTMLElement, state: ZoneState): void {
240  if (state !== "over") resting.set(zone, state);
241  zone.dataset.state = state;
242}
243
244// Checks files against the zone's rules, shows the result, puts the accepted files in the
245// input, and tells the page with cap-drop-accepted and cap-drop-rejected. Returns the result.
246export function acceptFiles(zone: HTMLElement, files: Iterable<File> | ArrayLike<File>, opts: { fromInput?: boolean } = {}): Validation {
247  const result = validateFiles(files, rulesOf(zone));
248  const input = part<HTMLInputElement>(zone, "input");
249  if (input && (!opts.fromInput || result.rejected.length > 0)) setInputFiles(input, result.accepted);
250  render(zone, result);
251  const detail: DropDetail = { accepted: result.accepted, rejected: result.rejected };
252  if (result.accepted.length > 0) zone.dispatchEvent(new CustomEvent("cap-drop-accepted", { bubbles: true, detail }));
253  if (result.rejected.length > 0) zone.dispatchEvent(new CustomEvent("cap-drop-rejected", { bubbles: true, detail }));
254  return result;
255}
256
257function isEditable(target: EventTarget | null): boolean {
258  return target instanceof Element && target.closest("input, textarea, [contenteditable='true']") !== null;
259}
260
261// Attaches one zone. Returns a function that detaches it.
262export function attachDropZone(zone: HTMLElement): () => void {
263  if (zone.hasAttribute(READY)) return () => {};
264  zone.setAttribute(READY, "");
265  const input = part<HTMLInputElement>(zone, "input");
266  const page = zone.dataset.scope === "page";
267  // The listeners go on the window for "drop anywhere", on the zone otherwise.
268  const target: EventTarget = page ? window : zone;
269  // A counter, not a boolean: dragenter and dragleave fire for every nested element crossed.
270  let depth = 0;
271  const disabled = () => !!input?.disabled;
272  const rest = (): ZoneState => resting.get(zone) ?? "idle";
273
274  const onEnter = (e: Event) => {
275    if (!dragHasFiles(e as DragEvent) || disabled()) return;
276    depth += 1;
277    setState(zone, "over");
278  };
279  const onOver = (e: Event) => {
280    const ev = e as DragEvent;
281    if (!dragHasFiles(ev) || disabled()) return;
282    ev.preventDefault();
283    if (ev.dataTransfer) ev.dataTransfer.dropEffect = "copy";
284  };
285  const onLeave = (e: Event) => {
286    if (depth === 0 || !dragHasFiles(e as DragEvent)) return;
287    depth = Math.max(0, depth - 1);
288    if (depth === 0) setState(zone, rest());
289  };
290  const onDrop = (e: Event) => {
291    const ev = e as DragEvent;
292    depth = 0;
293    if (zone.dataset.state === "over") setState(zone, rest());
294    // A zone on the page has already taken this drop.
295    if (ev.defaultPrevented) return;
296    const files = ev.dataTransfer?.files;
297    if (!files || files.length === 0) {
298      // A dropped link or text would navigate away from the page; a field still takes its text.
299      if (page && !isEditable(ev.target)) ev.preventDefault();
300      return;
301    }
302    if (disabled()) return;
303    ev.preventDefault();
304    acceptFiles(zone, files);
305    input?.focus({ preventScroll: true });
306  };
307  const onChange = () => {
308    if (input?.files) acceptFiles(zone, Array.from(input.files), { fromInput: true });
309  };
310  const onPaste = (e: Event) => {
311    const files = (e as ClipboardEvent).clipboardData?.files;
312    if (!files || files.length === 0 || disabled()) return;
313    e.preventDefault();
314    acceptFiles(zone, files);
315  };
316
317  target.addEventListener("dragenter", onEnter);
318  target.addEventListener("dragover", onOver);
319  target.addEventListener("dragleave", onLeave);
320  target.addEventListener("drop", onDrop);
321  input?.addEventListener("change", onChange);
322  const pasteTarget: EventTarget | null = zone.hasAttribute("data-paste") ? (page ? document : zone) : null;
323  pasteTarget?.addEventListener("paste", onPaste);
324  return () => {
325    target.removeEventListener("dragenter", onEnter);
326    target.removeEventListener("dragover", onOver);
327    target.removeEventListener("dragleave", onLeave);
328    target.removeEventListener("drop", onDrop);
329    input?.removeEventListener("change", onChange);
330    pasteTarget?.removeEventListener("paste", onPaste);
331    zone.removeAttribute(READY);
332  };
333}
334
335// Attaches to every [data-cap="drop-zone"] under root not yet attached. Returns a function
336// that detaches them all.
337export function enhance(root: ParentNode = document): () => void {
338  const undo = Array.from(root.querySelectorAll<HTMLElement>("[data-cap='drop-zone']:not([data-cap-ready])")).map(attachDropZone);
339  return () => undo.forEach((f) => f());
340}