@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/kit/FileField.tsx

@@ -0,0 +1,492 @@
+import { ArrowClockwiseIcon, UploadSimpleIcon, XIcon } from "@phosphor-icons/react";
+import { useEffect, useRef, useState, type CSSProperties, type DragEvent } from "react";
+
+import type { Attachment } from "../types";
+import { useKit, useParts } from "./context";
+import { ariaOf, type ControlBase } from "./Field";
+import { FileMark } from "./FileMark";
+import { formatSize } from "./numbers";
+import { failureOf, familyOf, isAbort, limitsOf, refusalOf, type FileHost } from "./uploads";
+
+// --- One file -----------------------------------------------------------------------------
+
+export interface FileChipProps {
+  name: string;
+  /** Its weight in bytes; none while it is not known. */
+  size?: number | undefined;
+  /** Its type, for its glyph when its name has no extension. */
+  type?: string | undefined;
+  /** On its way: how much of it has gone, from 0 to 1. */
+  progress?: number | undefined;
+  /** What went wrong with it, in place of its size. */
+  problem?: string | null | undefined;
+  /** Opens it: the chip is a button. */
+  onOpen?: (() => void) | undefined;
+  onRetry?: (() => void) | undefined;
+  onRemove?: (() => void) | undefined;
+}
+
+/**
+ * A file as a chip: the glyph of its family, its name, and under it its size, how much has gone while it uploads (a line filling at its foot), or what went wrong in the danger
+ * tone; at its end, trying it again and taking it away. With `onOpen` it opens on a click.
+ */
+export function FileChip({
+  name,
+  size,
+  type = "",
+  progress,
+  problem,
+  onOpen,
+  onRetry,
+  onRemove,
+}: FileChipProps) {
+  const { code, messages } = useKit();
+  const part = useParts();
+  const family = familyOf(name, type);
+  // The name says its extension; under it, how big it is, or how far it has gone.
+  const meta =
+    problem ??
+    (progress !== undefined
+      ? `${messages.uploading} ${new Intl.NumberFormat(code, { style: "percent" }).format(progress)}`
+      : size !== undefined
+        ? formatSize(size, code)
+        : "");
+  const body = (
+    <>
+      <FileMark name={name} type={type} size={28} />
+      <span className={part("sc-attachment__text")}>
+        <span className={part("sc-attachment__name")} title={name}>
+          {name}
+        </span>
+        {meta !== "" && <span className={part("sc-attachment__meta")}>{meta}</span>}
+      </span>
+    </>
+  );
+  return (
+    <div
+      data-family={family}
+      className={part("sc-attachment", ...(problem ? (["sc-attachment--failed"] as const) : []))}
+    >
+      {onOpen ? (
+        <button
+          type="button"
+          onClick={onOpen}
+          aria-label={messages.open(name)}
+          className={part("sc-attachment__main")}
+        >
+          {body}
+        </button>
+      ) : (
+        <span className={part("sc-attachment__main")}>{body}</span>
+      )}
+      {onRetry && (
+        <button
+          type="button"
+          onClick={onRetry}
+          aria-label={messages.retry}
+          title={messages.retry}
+          className={part("sc-attachment__action")}
+        >
+          <ArrowClockwiseIcon aria-hidden weight="bold" />
+        </button>
+      )}
+      {onRemove && (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label={messages.remove(name)}
+          title={messages.remove(name)}
+          className={part("sc-attachment__action")}
+        >
+          <XIcon aria-hidden weight="bold" />
+        </button>
+      )}
+      {progress !== undefined && (
+        <span
+          role="progressbar"
+          aria-label={name}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={Math.round(progress * 100)}
+          style={{ "--_progress": progress } as CSSProperties}
+          className={part("sc-attachment__bar")}
+        />
+      )}
+    </div>
+  );
+}
+
+/** Files already sent, as chips in a row that wraps; with `onOpen`, each opens on a click. */
+export function FileChips({
+  files,
+  onOpen,
+}: {
+  files: readonly Attachment[];
+  onOpen?: ((file: Attachment) => void) | undefined;
+}) {
+  const part = useParts();
+  return (
+    <ul className={part("sc-attachments")}>
+      {files.map((file) => (
+        <li key={file.id}>
+          <FileChip
+            name={file.name}
+            size={file.size}
+            type={file.media_type}
+            onOpen={onOpen && (() => onOpen(file))}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// --- Files on their way -------------------------------------------------------------------
+
+/** A file picked here, on its way or in: what its chip draws. */
+export interface Upload {
+  /** Tells it from the others here. */
+  key: number;
+  name: string;
+  size: number | undefined;
+  type: string;
+  /**
+   * uploading: on its way (`progress`, 0 to 1); done: stored as `id`; failed: its upload failed,
+   * to be tried again; refused: never sent, a kind not taken or too heavy (`problem` says which).
+   */
+  state: "uploading" | "done" | "failed" | "refused";
+  progress: number;
+  id: string | null;
+  problem: string | null;
+  /** The bytes, kept to try again. */
+  file: File | null;
+}
+
+/** What files may be picked: their kinds, their most in MB, one or many, how many at most. */
+export interface UploadRules {
+  accept?: readonly string[] | undefined;
+  maxMb?: number | undefined;
+  /** False: one file, a new pick replacing it. */
+  multiple?: boolean | undefined;
+  max?: number | undefined;
+}
+
+/** Files picked and how each goes, and what can be done with them. */
+export interface Uploads {
+  items: readonly Upload[];
+  /** The ids of the files in, in the order they were picked. */
+  ids: string[];
+  /** What the files still wait on: one on its way, or one that failed or was refused; null once all are in. */
+  waiting: "uploading" | "failed" | null;
+  add: (files: readonly File[]) => void;
+  remove: (key: number) => void;
+  retry: (key: number) => void;
+  /** Takes them all away, letting go of any on its way. */
+  clear: () => void;
+}
+
+let picks = 0;
+
+/** A file already in, by its id: what `useUploads` starts from. */
+export function uploaded(id: string, known: Attachment | undefined): Upload {
+  return {
+    key: ++picks,
+    name: known?.name ?? "",
+    size: known?.size,
+    type: known?.media_type ?? "",
+    state: "done",
+    progress: 1,
+    id,
+    problem: null,
+    file: null,
+  };
+}
+
+/**
+ * Files picked and sent at once through `host`: each is refused before it goes when it is not a
+ * kind taken, is too heavy, or is one too many; then it is on its way, then in (its id) or failed
+ * (to be tried again). With `multiple` false a new pick replaces what was there. Whatever is on
+ * its way when its file goes (taken away, cleared, the component gone) is let go.
+ */
+export function useUploads(
+  host: FileHost | undefined,
+  { accept, maxMb, multiple = true, max = Infinity }: UploadRules,
+  start: () => Upload[] = () => [],
+): Uploads {
+  const { code, messages } = useKit();
+  const [items, setItems] = useState<Upload[]>(start);
+  const running = useRef(new Map<number, AbortController>());
+
+  useEffect(() => {
+    const now = running.current;
+    return () => {
+      for (const controller of now.values()) controller.abort();
+      now.clear();
+    };
+  }, []);
+
+  const change = (key: number, patch: Partial<Upload>) => {
+    setItems((now) => now.map((item) => (item.key === key ? { ...item, ...patch } : item)));
+  };
+
+  const letGo = (key: number) => {
+    running.current.get(key)?.abort();
+    running.current.delete(key);
+  };
+
+  const send = (key: number, file: File) => {
+    if (!host) return;
+    const controller = new AbortController();
+    running.current.set(key, controller);
+    host
+      .upload(file, (progress) => change(key, { progress }), controller.signal)
+      .then(
+        (stored) => {
+          change(key, { state: "done", id: stored.id, progress: 1, file: null });
+        },
+        (error: unknown) => {
+          if (isAbort(error)) return;
+          change(key, { state: "failed", problem: failureOf(error, maxMb, code, messages) });
+        },
+      )
+      .finally(() => {
+        if (running.current.get(key) === controller) running.current.delete(key);
+      });
+  };
+
+  const add = (files: readonly File[]) => {
+    if (!host || files.length === 0) return;
+    const picked = multiple ? files : files.slice(0, 1);
+    const kept = multiple ? items.filter((item) => item.state !== "refused").length : 0;
+    const fresh = picked.map((file, index): Upload => {
+      const problem =
+        kept + index >= max
+          ? messages.tooMany(max)
+          : refusalOf(file, accept, maxMb, code, messages);
+      return {
+        key: ++picks,
+        name: file.name || messages.file,
+        size: file.size,
+        type: file.type,
+        state: problem === null ? "uploading" : "refused",
+        progress: 0,
+        id: null,
+        problem,
+        file: problem === null ? file : null,
+      };
+    });
+    if (!multiple) for (const key of running.current.keys()) letGo(key);
+    setItems((now) => (multiple ? [...now, ...fresh] : fresh));
+    for (const item of fresh) if (item.file) send(item.key, item.file);
+  };
+
+  const remove = (key: number) => {
+    letGo(key);
+    setItems((now) => now.filter((item) => item.key !== key));
+  };
+
+  const retry = (key: number) => {
+    const item = items.find((each) => each.key === key);
+    if (item?.state !== "failed" || !item.file) return;
+    change(key, { state: "uploading", progress: 0, problem: null });
+    send(key, item.file);
+  };
+
+  const clear = () => {
+    for (const key of [...running.current.keys()]) letGo(key);
+    setItems([]);
+  };
+
+  const ids = items.flatMap((item) => (item.state === "done" && item.id ? [item.id] : []));
+  const waiting = items.some((item) => item.state === "uploading")
+    ? "uploading"
+    : items.some((item) => item.state === "failed" || item.state === "refused")
+      ? "failed"
+      : null;
+  return { items, ids, waiting, add, remove, retry, clear };
+}
+
+/**
+ * The files picked, as chips: each with how it goes; taken away while they can be, the failed
+ * tried again; once in, a name not known here is read from the host's files, and opens there.
+ */
+export function UploadChips({
+  uploads,
+  host,
+  closed = false,
+}: {
+  uploads: Uploads;
+  host: FileHost | undefined;
+  closed?: boolean | undefined;
+}) {
+  const { messages } = useKit();
+  const part = useParts();
+  return (
+    <ul className={part("sc-attachments")}>
+      {uploads.items.map((item) => {
+        const stored = item.id !== null ? host?.known.get(item.id) : undefined;
+        const { open } = host ?? {};
+        return (
+          <li key={item.key}>
+            <FileChip
+              name={stored?.name ?? (item.name || messages.file)}
+              size={stored?.size ?? item.size}
+              type={stored?.media_type ?? item.type}
+              progress={item.state === "uploading" ? item.progress : undefined}
+              problem={item.problem}
+              onOpen={stored && open && (() => open(stored))}
+              onRetry={
+                !closed && item.state === "failed" ? () => uploads.retry(item.key) : undefined
+              }
+              onRemove={closed ? undefined : () => uploads.remove(item.key)}
+            />
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/** Whether what is dragged carries files (not words, not a link). */
+export function carriesFiles(event: DragEvent): boolean {
+  return [...event.dataTransfer.types].includes("Files");
+}
+
+// --- The field ----------------------------------------------------------------------------
+
+export interface FileFieldProps extends ControlBase {
+  /** The ids of the files in. */
+  value: string[];
+  onChange: (ids: string[]) => void;
+  /** Where its files go and are found; none: it takes none (closed). */
+  files?: FileHost | undefined;
+  /** The kinds it takes: types, families ("image/*"), extensions (".xlsx"); none: any. */
+  accept?: readonly string[] | undefined;
+  multiple?: boolean | undefined;
+  /** The most a file may weigh, in MB (50 at most). */
+  maxMb?: number | undefined;
+  /**
+   * Hears what the field still waits on before its form may go, in words (a file on its way,
+   * one that failed), and null once nothing.
+   */
+  onWait?: ((problem: string | null) => void) | undefined;
+}
+
+/**
+ * Files to give: a zone to drop them on or press to choose them, saying what it takes; each file
+ * uploads at once (a line fills under it), then sits as a chip to take away; what is wrong with
+ * one (too heavy, a kind not taken, an upload that failed, to try again) says so on its chip.
+ * The value is the ids of the files in. One file unless `multiple`: once it is in, the zone
+ * steps aside until it is taken away. Closed, the chips are read, and open where the host shows
+ * files.
+ */
+export function FileField({
+  value,
+  onChange,
+  files,
+  accept,
+  multiple = false,
+  maxMb,
+  onWait,
+  ...control
+}: FileFieldProps) {
+  const { code, messages } = useKit();
+  const part = useParts();
+  const picker = useRef<HTMLInputElement>(null);
+  const [over, setOver] = useState(false);
+  const uploads = useUploads(files, { accept, maxMb, multiple }, () =>
+    value.map((id) => uploaded(id, files?.known.get(id))),
+  );
+  const closed = control.disabled === true || files === undefined;
+
+  // The ids go up whenever the files in change.
+  const sent = useRef(value.join(" "));
+  const ids = uploads.ids;
+  useEffect(() => {
+    const now = ids.join(" ");
+    if (now === sent.current) return;
+    sent.current = now;
+    onChange(ids);
+  }, [ids, onChange]);
+
+  const wait =
+    uploads.waiting === "uploading"
+      ? messages.stillUploading
+      : uploads.waiting === "failed"
+        ? messages.fixFiles
+        : null;
+  useEffect(() => {
+    onWait?.(wait);
+  }, [wait, onWait]);
+
+  // Files in whose names are not known here are asked for, once.
+  const missing = ids.filter((id) => !files?.known.has(id)).join(" ");
+  useEffect(() => {
+    if (missing !== "") files?.find?.(missing.split(" "));
+  }, [missing, files]);
+
+  const held = uploads.items.some((item) => item.state !== "refused" && item.state !== "failed");
+  const zone = closed ? uploads.items.length === 0 : multiple || !held;
+  const { id, labelledBy } = control;
+
+  return (
+    <div className={part("sc-upload")}>
+      {zone && (
+        <button
+          type="button"
+          id={id}
+          disabled={closed}
+          data-drop
+          data-over={over || undefined}
+          data-invalid={control.invalid || undefined}
+          {...ariaOf(control)}
+          // Its name is its label and what it says.
+          aria-labelledby={
+            labelledBy === undefined || id === undefined ? labelledBy : `${labelledBy} ${id}`
+          }
+          aria-required={undefined}
+          onClick={() => picker.current?.click()}
+          onDragOver={(event) => {
+            if (closed || !carriesFiles(event)) return;
+            event.preventDefault();
+            event.dataTransfer.dropEffect = "copy";
+            setOver(true);
+          }}
+          onDragLeave={() => {
+            setOver(false);
+          }}
+          onDrop={(event) => {
+            if (closed) return;
+            event.preventDefault();
+            setOver(false);
+            uploads.add([...event.dataTransfer.files]);
+          }}
+          className={part("sc-upload__zone")}
+        >
+          <span aria-hidden className={part("sc-upload__icon")}>
+            <UploadSimpleIcon weight="bold" />
+          </span>
+          <span className={part("sc-upload__text")}>
+            <strong>{messages.upload(multiple)}</strong>
+            <small>
+              {messages.drop}. {limitsOf(accept, maxMb, code, messages)}
+            </small>
+          </span>
+        </button>
+      )}
+      <input
+        ref={picker}
+        type="file"
+        hidden
+        tabIndex={-1}
+        accept={accept?.join(",")}
+        multiple={multiple}
+        onChange={(event) => {
+          uploads.add([...(event.target.files ?? [])]);
+          event.target.value = "";
+        }}
+      />
+      {uploads.items.length > 0 && <UploadChips uploads={uploads} host={files} closed={closed} />}
+    </div>
+  );
+}

package/src/kit/FileMark.tsx

@@ -0,0 +1,56 @@
+import {
+  FileAudioIcon,
+  FileDocIcon,
+  FileIcon,
+  FileImageIcon,
+  FilePdfIcon,
+  FilePptIcon,
+  FileTextIcon,
+  FileVideoIcon,
+  FileXlsIcon,
+  FileZipIcon,
+  type Icon,
+} from "@phosphor-icons/react";
+
+import { Mark } from "./Mark";
+import { familyOf, type FileFamily } from "./uploads";
+
+/** Each family's glyph: the format's own sheet (PDF, Word, Excel, PowerPoint), a picture, a clip. */
+const GLYPHS: Readonly<Record<FileFamily, Icon>> = {
+  image: FileImageIcon,
+  pdf: FilePdfIcon,
+  sheet: FileXlsIcon,
+  doc: FileDocIcon,
+  slides: FilePptIcon,
+  text: FileTextIcon,
+  archive: FileZipIcon,
+  audio: FileAudioIcon,
+  video: FileVideoIcon,
+  other: FileIcon,
+};
+
+/**
+ * A file's mark: the glyph of its family, bare, by its name's extension (then its type), the
+ * common formats in their own tint (a PDF rose, a sheet green, a document blue, slides amber, a
+ * picture sand), the rest in the muted ink. It keeps `Mark`'s square.
+ */
+export function FileMark({
+  name,
+  type = "",
+  size,
+  className,
+}: {
+  name: string;
+  /** Its media type, when the name says nothing. */
+  type?: string | undefined;
+  size?: number | undefined;
+  className?: string | undefined;
+}) {
+  const family = familyOf(name, type);
+  const Glyph = GLYPHS[family];
+  return (
+    <Mark size={size} className={className}>
+      <Glyph weight="regular" data-family={family} />
+    </Mark>
+  );
+}