@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/FileView.tsx

@@ -0,0 +1,620 @@
+import { DownloadSimpleIcon } from "@phosphor-icons/react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+
+import { formatSize } from "./about";
+import { classes } from "./classes";
+import {
+  baseName,
+  cleanDocument,
+  extensionOf,
+  pretty,
+  previewOf,
+  tableOf,
+  typedFor,
+  type Preview,
+} from "./files";
+import { AudioPlayer } from "./kit/AudioPlayer";
+import { Button } from "./kit/Button";
+import { KitProvider, type KitClassNames, type KitPart } from "./kit/context";
+import { FileMark } from "./kit/FileMark";
+import { Markdown } from "./surface/Markdown";
+import type { FilePreview, PreviewSheet, PreviewSlide } from "./types";
+
+/** The words a file's view says; a host gives its own, in its language. */
+export interface FileMessages {
+  /** The button that saves the file under its name. */
+  download: string;
+  /** In the preview's place, for a kind that can't be shown here. */
+  noPreview: string;
+  /** Under it: what to do instead. */
+  noPreviewHint: string;
+  /** Under a long file shown only in part. */
+  truncated: string;
+  /** In the bar, for a file whose name has no extension. */
+  file: string;
+  /** A file's size, as the host's people read it. */
+  size: (bytes: number) => string;
+  /** A PDF's pages, in the bar. */
+  pages: (count: number) => string;
+  /** The tabs of a spreadsheet's sheets, for screen readers. */
+  sheets: string;
+  /** Under a sheet shown in part: its first rows of how many. */
+  rows: (shown: number, total: number) => string;
+  /** In place of a sheet with nothing in it. */
+  emptySheet: string;
+  /** Over a slide: its number. */
+  slide: (number: number) => string;
+  /** Over a slide's speaker notes. */
+  notes: string;
+}
+
+export const FILE_MESSAGES: FileMessages = {
+  download: "Download",
+  noPreview: "This file can't be previewed here.",
+  noPreviewHint: "Download it to open it on your device.",
+  truncated: "Only the beginning is shown. Download it to see it whole.",
+  file: "File",
+  size: (bytes) => formatSize(bytes),
+  pages: (count) => (count === 1 ? "1 page" : `${count} pages`),
+  sheets: "Sheets",
+  rows: (shown, total) => `The first ${shown} of ${total} rows`,
+  emptySheet: "This sheet is empty.",
+  slide: (number) => `Slide ${number}`,
+  notes: "Notes",
+};
+
+/** The parts, by the class each carries; `classNames` adds a host's own under the same keys. */
+export type FilePart =
+  | "sc-file"
+  | "sc-file__bar"
+  | "sc-file__meta"
+  | "sc-file__body"
+  | "sc-file__text"
+  | "sc-file__plain"
+  | "sc-file__code"
+  | "sc-file__table"
+  | "sc-file__sheet"
+  | "sc-file__tabs"
+  | "sc-file__tab"
+  | "sc-file__document"
+  | "sc-file__slides"
+  | "sc-file__slide"
+  | "sc-file__notes"
+  | "sc-file__frame"
+  | "sc-file__image"
+  | "sc-file__media"
+  | "sc-file__none"
+  | "sc-file__note";
+
+type ClassNames = Partial<Record<FilePart | KitPart, string>> | undefined;
+
+export interface FileViewProps {
+  /** The file's bytes, as the API answers them (`Response.blob()`). */
+  blob: Blob;
+  /** Its name or path, with its extension: how it is read, and what it is saved as. */
+  name: string;
+  /**
+   * What the API made of it to draw (`client.files.preview`): a spreadsheet's sheets, a Word
+   * file as a document, a deck's slides, the words of a text, how a picture, a video or a sound
+   * is typed. Without it, what the browser can read of the bytes alone.
+   */
+  preview?: FilePreview | undefined;
+  messages?: Partial<FileMessages> | undefined;
+  classNames?: ClassNames;
+}
+
+/** The most of a file read as words: a longer one shows its beginning. */
+const TEXT_LIMIT = 256 * 1024;
+/** The most rows a table draws. */
+const ROW_LIMIT = 500;
+
+/**
+ * One file, to see and to save, whatever its kind: a bar with its kind, its size (a PDF's pages)
+ * and the button that saves it under its name, over the file as it reads. A PDF in the browser's
+ * own viewer; a spreadsheet as a grid, its header kept in view, its sheets as tabs at its foot; a
+ * Word file as a document at a reading measure; a deck as its slides one under another, their
+ * notes under each; Markdown drawn, plain words as written, a source in the mono face, wrapped,
+ * never run; a picture whole, a video and a sound in the browser's own players; any other kind
+ * says it can't be shown, and is saved. What it can't read alone (a sheet, a document, slides)
+ * it draws from `preview`. It fills the height it is given (a dialog's body), and scrolls inside.
+ * The addresses it makes for the bytes are let go when it goes.
+ */
+export function FileView(props: FileViewProps) {
+  return (
+    <KitProvider classNames={props.classNames as KitClassNames}>
+      <View {...props} />
+    </KitProvider>
+  );
+}
+
+function View({ blob, name, preview, messages, classNames }: FileViewProps) {
+  const words = { ...FILE_MESSAGES, ...messages };
+  const extension = extensionOf(name);
+  // What is saved is plain bytes, so opening its address shows nothing, it only downloads.
+  const saved = useMemo(() => new Blob([blob], { type: "application/octet-stream" }), [blob]);
+  const save = useObjectUrl(saved);
+  const pages = preview?.kind === "pdf" ? preview.pages : null;
+
+  return (
+    <div className={`sc ${classes(classNames, "sc-file")}`}>
+      <div className={classes(classNames, "sc-file__bar")}>
+        <FileMark name={name} size={24} />
+        <span className={classes(classNames, "sc-file__meta")}>
+          <span>{extension === "" ? words.file : extension.toUpperCase()}</span>
+          <span>{words.size(blob.size)}</span>
+          {pages !== null && <span>{words.pages(pages)}</span>}
+        </span>
+        {save !== null && (
+          <Button size="sm" icon={DownloadSimpleIcon} href={save} download={baseName(name)}>
+            {words.download}
+          </Button>
+        )}
+      </div>
+      <div className={classes(classNames, "sc-file__body")}>
+        {preview === undefined ? (
+          <Read blob={blob} name={name} words={words} classNames={classNames} />
+        ) : (
+          <Previewed
+            preview={preview}
+            blob={blob}
+            name={name}
+            words={words}
+            classNames={classNames}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface Drawn {
+  name: string;
+  words: FileMessages;
+  classNames: ClassNames;
+}
+
+/** Under a file shown only in part: the words that say so. */
+function Cut({
+  shown,
+  words,
+  classNames,
+}: { shown: boolean; words: FileMessages } & Pick<Drawn, "classNames">) {
+  return shown ? <p className={classes(classNames, "sc-file__note")}>{words.truncated}</p> : null;
+}
+
+/** The file as the API made it to draw, by its kind. */
+function Previewed({
+  preview,
+  blob,
+  name,
+  words,
+  classNames,
+}: Drawn & { preview: FilePreview; blob: Blob }) {
+  switch (preview.kind) {
+    case "pdf":
+      return <Pdf blob={blob} name={name} classNames={classNames} />;
+    case "image":
+      return preview.media_type.includes("svg") ? (
+        <Svg blob={blob} name={name} classNames={classNames} />
+      ) : (
+        <Media
+          blob={blob}
+          type={preview.media_type}
+          name={name}
+          classNames={classNames}
+          kind="image"
+        />
+      );
+    case "video":
+    case "audio":
+      return (
+        <Media
+          blob={blob}
+          type={preview.media_type}
+          name={name}
+          classNames={classNames}
+          kind={preview.kind}
+        />
+      );
+    case "sheet":
+      return (
+        <Sheets
+          sheets={preview.sheets}
+          truncated={preview.truncated}
+          words={words}
+          classNames={classNames}
+        />
+      );
+    case "document":
+      return (
+        <Document
+          html={preview.html}
+          truncated={preview.truncated}
+          words={words}
+          classNames={classNames}
+        />
+      );
+    case "slides":
+      return (
+        <Slides
+          slides={preview.slides}
+          truncated={preview.truncated}
+          words={words}
+          classNames={classNames}
+        />
+      );
+    case "markdown":
+    case "text":
+      return (
+        <Words
+          text={preview.text}
+          markdown={preview.kind === "markdown"}
+          truncated={preview.truncated}
+          words={words}
+          classNames={classNames}
+        />
+      );
+    case "code":
+    case "json":
+      return (
+        <Source
+          text={preview.kind === "json" && !preview.truncated ? pretty(preview.text) : preview.text}
+          truncated={preview.truncated}
+          words={words}
+          classNames={classNames}
+        />
+      );
+    case "unknown":
+      return <None name={name} words={words} classNames={classNames} />;
+  }
+}
+
+/** The file as the browser reads its bytes alone, by its name and type. */
+function Read({ blob, name, words, classNames }: Drawn & { blob: Blob }) {
+  const preview: Preview = previewOf(name, blob.type);
+  const svg = extensionOf(name) === "svg";
+  const reads = preview === "markdown" || preview === "text" || preview === "code";
+  const text = useText(blob, reads || preview === "table", TEXT_LIMIT);
+  const cut = blob.size > TEXT_LIMIT;
+
+  if (preview === "image") {
+    return svg ? (
+      <Svg blob={blob} name={name} classNames={classNames} />
+    ) : (
+      <Media blob={typedFor(blob, name)} name={name} classNames={classNames} kind="image" />
+    );
+  }
+  if (preview === "pdf") return <Pdf blob={blob} name={name} classNames={classNames} />;
+  if (preview === "none") return <None name={name} words={words} classNames={classNames} />;
+  if (text === null) return null;
+
+  const rows = preview === "table" ? tableOf(text) : null;
+  if (rows !== null) {
+    const [columns = [], ...body] = rows;
+    return (
+      <Sheets
+        sheets={[{ name: baseName(name), columns, rows: body, total_rows: body.length }]}
+        truncated={cut}
+        words={words}
+        classNames={classNames}
+      />
+    );
+  }
+  if (preview === "markdown" || preview === "text") {
+    return (
+      <Words
+        text={text}
+        markdown={preview === "markdown"}
+        truncated={cut}
+        words={words}
+        classNames={classNames}
+      />
+    );
+  }
+  // A source, or a CSV not simple enough for a table: as written, in the mono face.
+  return (
+    <Source
+      text={extensionOf(name) === "json" && !cut ? pretty(text) : text}
+      truncated={cut}
+      words={words}
+      classNames={classNames}
+    />
+  );
+}
+
+/** A PDF in the browser's own viewer. */
+function Pdf({ blob, name, classNames }: { blob: Blob; name: string; classNames: ClassNames }) {
+  const typed = useMemo(() => typedFor(blob, name), [blob, name]);
+  const view = useObjectUrl(typed);
+  return (
+    view !== null && (
+      <iframe src={view} title={baseName(name)} className={classes(classNames, "sc-file__frame")} />
+    )
+  );
+}
+
+/**
+ * An SVG, from its words as a data address: one of the page's own (a blob's) would run its
+ * scripts as the page if it were opened apart.
+ */
+function Svg({ blob, name, classNames }: { blob: Blob; name: string; classNames: ClassNames }) {
+  const text = useText(blob, true, Infinity);
+  return (
+    text !== null && (
+      <div className={classes(classNames, "sc-file__image")}>
+        <img
+          src={`data:image/svg+xml;charset=utf-8,${encodeURIComponent(text)}`}
+          alt={baseName(name)}
+        />
+      </div>
+    )
+  );
+}
+
+/** A picture whole, a video or a sound in the browser's own player, from its bytes typed. */
+function Media({
+  blob,
+  type,
+  name,
+  kind,
+  classNames,
+}: {
+  blob: Blob;
+  /** The type it plays as; none: the one the bytes came with. */
+  type?: string | undefined;
+  name: string;
+  kind: "image" | "video" | "audio";
+  classNames: ClassNames;
+}) {
+  const typed = useMemo(
+    () => (type === undefined || blob.type === type ? blob : new Blob([blob], { type })),
+    [blob, type],
+  );
+  const src = useObjectUrl(typed);
+  if (src === null) return null;
+  if (kind === "image") {
+    return (
+      <div className={classes(classNames, "sc-file__image")}>
+        <img src={src} alt={baseName(name)} />
+      </div>
+    );
+  }
+  return (
+    <div className={classes(classNames, "sc-file__media")} data-kind={kind}>
+      {kind === "video" ? (
+        <video src={src} controls playsInline preload="metadata" aria-label={baseName(name)} />
+      ) : (
+        <>
+          <FileMark name={name} size={44} />
+          <AudioPlayer src={src} label={baseName(name)} />
+        </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A spreadsheet: one sheet at a time as a grid, its columns over it kept in view as it scrolls;
+ * its sheets as tabs at its foot, as a spreadsheet has them. Under a
+ * sheet shown in part, how many of its rows are.
+ */
+function Sheets({
+  sheets,
+  truncated,
+  words,
+  classNames,
+}: {
+  sheets: readonly PreviewSheet[];
+  truncated: boolean;
+} & Omit<Drawn, "name">) {
+  const [at, setAt] = useState(0);
+  const sheet = sheets[at] ?? sheets[0];
+  if (sheet === undefined) return <None name="" words={words} classNames={classNames} />;
+  const rows = sheet.rows.slice(0, ROW_LIMIT);
+  const width = Math.max(sheet.columns?.length ?? 0, ...rows.map((row) => row.length));
+  const several = sheets.length > 1;
+  return (
+    <div className={classes(classNames, "sc-file__sheet")}>
+      {/* Another sheet opens at its top-left corner. */}
+      <div
+        key={at}
+        role={several ? "tabpanel" : undefined}
+        className={classes(classNames, "sc-file__table")}
+      >
+        {sheet.columns === null ? (
+          <p className={classes(classNames, "sc-file__note")}>{words.emptySheet}</p>
+        ) : (
+          <table>
+            <thead>
+              <tr>
+                {pad(sheet.columns, width).map((cell, index) => (
+                  <th key={index} scope="col">
+                    {cell}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row, index) => (
+                <tr key={index}>
+                  {pad(row, width).map((cell, column) => (
+                    <td key={column} title={cell.length > 36 ? cell : undefined}>
+                      {cell}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+        {sheet.total_rows > rows.length ? (
+          <p className={classes(classNames, "sc-file__note")}>
+            {words.rows(rows.length, sheet.total_rows)}
+          </p>
+        ) : (
+          <Cut shown={truncated} words={words} classNames={classNames} />
+        )}
+      </div>
+      {several && (
+        <div
+          role="tablist"
+          aria-label={words.sheets}
+          className={classes(classNames, "sc-file__tabs")}
+        >
+          {sheets.map((each, index) => (
+            <button
+              key={index}
+              type="button"
+              role="tab"
+              aria-selected={index === at}
+              onClick={() => {
+                setAt(index);
+              }}
+              className={classes(classNames, "sc-file__tab")}
+            >
+              {each.name}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** A row as wide as the widest, its missing cells empty. */
+const pad = (cells: readonly string[], width: number): string[] =>
+  cells.length >= width ? [...cells] : [...cells, ...Array<string>(width - cells.length).fill("")];
+
+/**
+ * A Word file as its HTML at a reading measure: headings, paragraphs, lists, tables, pictures,
+ * kept to what a viewer draws (`cleanDocument`), again here after the API.
+ */
+function Document({
+  html,
+  truncated,
+  words,
+  classNames,
+}: { html: string; truncated: boolean } & Omit<Drawn, "name">) {
+  const clean = useMemo(() => cleanDocument(html), [html]);
+  return (
+    <div className={classes(classNames, "sc-file__text")}>
+      <div
+        className={classes(classNames, "sc-file__document")}
+        // Kept to the API's allow-list, by the API and again by `cleanDocument`.
+        dangerouslySetInnerHTML={{ __html: clean }}
+      />
+      <Cut shown={truncated} words={words} classNames={classNames} />
+    </div>
+  );
+}
+
+/** A deck: its slides one under another, each a card with its number, its words, its notes. */
+function Slides({
+  slides,
+  truncated,
+  words,
+  classNames,
+}: { slides: readonly PreviewSlide[]; truncated: boolean } & Omit<Drawn, "name">) {
+  return (
+    <>
+      <ol className={classes(classNames, "sc-file__slides")}>
+        {slides.map((slide, index) => (
+          <li key={index} className={classes(classNames, "sc-file__slide")}>
+            <span>{words.slide(index + 1)}</span>
+            {slide.title !== null && slide.title !== "" && <h3>{slide.title}</h3>}
+            {slide.text !== "" && <p>{slide.text}</p>}
+            {slide.notes !== null && slide.notes !== "" && (
+              <div className={classes(classNames, "sc-file__notes")}>
+                <span>{words.notes}</span>
+                <p>{slide.notes}</p>
+              </div>
+            )}
+          </li>
+        ))}
+      </ol>
+      <Cut shown={truncated} words={words} classNames={classNames} />
+    </>
+  );
+}
+
+/** Words at a reading measure: Markdown drawn, plain words as written. */
+function Words({
+  text,
+  markdown,
+  truncated,
+  words,
+  classNames,
+}: { text: string; markdown: boolean; truncated: boolean } & Omit<Drawn, "name">) {
+  return (
+    <div className={classes(classNames, "sc-file__text")}>
+      {markdown ? (
+        <Markdown text={text} />
+      ) : (
+        <p className={classes(classNames, "sc-file__plain")}>{text}</p>
+      )}
+      <Cut shown={truncated} words={words} classNames={classNames} />
+    </div>
+  );
+}
+
+/** A source as written, in the mono face, its long lines wrapped; never run. */
+function Source({
+  text,
+  truncated,
+  words,
+  classNames,
+}: { text: string; truncated: boolean } & Omit<Drawn, "name">) {
+  return (
+    <>
+      <pre className={classes(classNames, "sc-file__code")}>
+        <code>{text}</code>
+      </pre>
+      <Cut shown={truncated} words={words} classNames={classNames} />
+    </>
+  );
+}
+
+/** A kind that can't be shown: its mark, the line that says so, and what to do instead. */
+function None({ name, words, classNames }: Drawn): ReactNode {
+  return (
+    <div className={classes(classNames, "sc-file__none")}>
+      <FileMark name={name} size={44} />
+      <p>
+        <strong>{words.noPreview}</strong>
+        <span>{words.noPreviewHint}</span>
+      </p>
+    </div>
+  );
+}
+
+/** The first `limit` bytes of a blob as words, once read; null while reading, or when not wanted. */
+function useText(blob: Blob, wanted: boolean, limit: number): string | null {
+  const [text, setText] = useState<string | null>(null);
+  useEffect(() => {
+    if (!wanted) return;
+    let live = true;
+    void (blob.size > limit ? blob.slice(0, limit) : blob).text().then((read) => {
+      if (live) setText(read);
+    });
+    return () => {
+      live = false;
+      setText(null);
+    };
+  }, [blob, wanted, limit]);
+  return text;
+}
+
+/** An address for a blob while it is shown, let go when it changes or goes. */
+function useObjectUrl(blob: Blob | null): string | null {
+  const [url, setUrl] = useState<string | null>(null);
+  useEffect(() => {
+    if (blob === null) return;
+    const made = URL.createObjectURL(blob);
+    setUrl(made);
+    return () => {
+      URL.revokeObjectURL(made);
+      setUrl(null);
+    };
+  }, [blob]);
+  return url;
+}