@devultur/convex 1.3.0 → 1.3.1

package/dist/react.d.ts

@@ -107,6 +107,32 @@ interface MediaObjectUrl {
  */
 declare function useMediaObjectUrl(media: DevulturMedia | null | undefined, options?: UseMediaObjectUrlOptions): MediaObjectUrl;
 
+/**
+ * Every string `<Preview>`, `<PdfThumbnail>` and their PDF pages show or announce. Pass any subset as `labels` on a
+ * component or on `PdfPreviewProvider`; the component's wins over the provider's, which wins over the English defaults.
+ */
+interface PreviewLabels {
+    /** Accessible name of a pdf.js document: its title and page count. */
+    document: (title: string, pageCount: number) => string;
+    /** Accessible name of one pdf.js page. */
+    page: (page: number, pageCount: number) => string;
+    /** Announced (visually hidden) while a preview loads, when no `loading` is passed. */
+    loading: string;
+    /** Note after the last rendered page when a PDF has more than `maxPages`; `fallback` follows it. */
+    pageCap: (shown: number, total: number) => string;
+    /** `title` of the default fallback's download link when a fetch was refused or the type can't be previewed. */
+    error: (code: MediaFetchErrorCode) => string;
+    /** Accessible name of a `<PdfThumbnail>`, from its title. */
+    thumbnail: (title: string) => string;
+    /** Name of a PDF (pdf.js document, `<iframe>` title, thumbnail) with no `title` and no filename. */
+    untitledPdf: string;
+    /** Name of an image or audio preview with no `title` and no filename. */
+    untitledMedia: string;
+    /** Text of the default fallback's download link when the media has no filename. */
+    download: string;
+}
+declare const defaultPreviewLabels: PreviewLabels;
+
 interface PdfPreviewConfig {
     /**
      * Imports pdf.js. Without it, PDFs render in an `<iframe>` (the browser's own viewer) and `<PdfThumbnail>` renders
@@ -115,15 +141,18 @@ interface PdfPreviewConfig {
     pdfjs?: PdfjsLoader;
     /** URL of `pdf.worker.min.mjs`, set on `GlobalWorkerOptions.workerSrc` before a document opens. */
     workerSrc?: string;
+    /** Labels for every `<Preview>` and `<PdfThumbnail>` below it; a component's own `labels` win over these. */
+    labels?: Partial<PreviewLabels>;
 }
 /**
- * Renders the PDFs of every `<Preview>` and `<PdfThumbnail>` below it with pdf.js, on a `<canvas>`.
+ * Renders the PDFs of every `<Preview>` and `<PdfThumbnail>` below it with pdf.js, on a `<canvas>`, and gives them
+ * default `labels`.
  *
  * @example
  * import { loadPdfjs } from "@devultur/convex/pdfjs";
  * <PdfPreviewProvider pdfjs={loadPdfjs}>{children}</PdfPreviewProvider>
  */
-declare function PdfPreviewProvider({ pdfjs, workerSrc, children }: PdfPreviewConfig & {
+declare function PdfPreviewProvider({ pdfjs, workerSrc, labels, children, }: PdfPreviewConfig & {
     children: React.ReactNode;
 }): React.JSX.Element;
 
@@ -140,11 +169,13 @@ interface PdfThumbnailProps {
     fallback?: React.ReactNode;
     /** Shown until page 1 is drawn, including while off-screen. Default: nothing. */
     loading?: React.ReactNode;
-    /** Accessible name of the thumbnail. Default: the filename. */
+    /** Title the accessible name is built from (`labels.thumbnail`). Default: the filename. */
     title?: string;
     className?: string;
     /** Overrides the provider's `workerSrc`. */
     pdfWorkerSrc?: string;
+    /** Overrides `thumbnail` and `untitledPdf`; wins over `PdfPreviewProvider`'s `labels`. English by default. */
+    labels?: Partial<PreviewLabels>;
 }
 /**
  * Page 1 of a PDF on a small canvas, for lists and upload queues. Nothing is fetched until it nears the viewport.
@@ -164,9 +195,14 @@ interface PreviewProps {
     maxBytes?: number;
     /** Size cap for text previews. Default 1 MiB. */
     maxTextBytes?: number;
-    /** Shown for types that don't preview inline and when the fetch fails. Default: a `<DownloadLink>`. */
-    fallback?: React.ReactNode;
-    /** Shown while a private file is loading. Default: nothing. */
+    /**
+     * Shown for types that don't preview inline and when the fetch fails. Default: a `<DownloadLink>`.
+     * As a function it receives why: a `MediaFetchError` when the fetch was refused (`http_error`, `too_large`,
+     * `type_mismatch`) or the type doesn't preview inline (`unsupported_type`, nothing fetched), `null` otherwise
+     * (a network failure, a PDF pdf.js can't open, or the link after the `maxPages` note).
+     */
+    fallback?: React.ReactNode | ((error: MediaFetchError | null) => React.ReactNode);
+    /** Shown while a file loads. Default: `labels.loading`, visually hidden, in a `role="status"`. `null` → nothing. */
     loading?: React.ReactNode;
     /** Accessible name of the preview (`alt`, `title`, `aria-label`). Default: the filename (text: none). */
     title?: string;
@@ -178,6 +214,8 @@ interface PreviewProps {
     maxPages?: number;
     /** URL of pdf.js's worker for this preview; overrides `PdfPreviewProvider`'s `workerSrc`. */
     pdfWorkerSrc?: string;
+    /** Overrides any string shown or announced; wins over `PdfPreviewProvider`'s `labels`. English by default. */
+    labels?: Partial<PreviewLabels>;
 }
 /**
  * Renders a media inline by its content type: images in an `<img>`, PDFs on `<canvas>` pages with pdf.js under a
@@ -188,7 +226,7 @@ interface PreviewProps {
  * @example
  * <Preview media={document.file} maxBytes={20_000_000} className="h-[80vh] w-full" />
  */
-declare function Preview({ media, contentType, fallback, ...viewProps }: PreviewProps): React.JSX.Element | null;
+declare function Preview({ media, contentType, fallback, loading, labels, ...viewProps }: PreviewProps): React.JSX.Element | null;
 
 /** How a content type renders inline: `<img>`, a PDF view (pdf.js canvases or `<iframe>`), `<audio>` or `<pre>`. */
 type PreviewKind = "image" | "pdf" | "audio" | "text";
@@ -433,4 +471,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, defaultPreviewLabels, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };

package/dist/react.js

@@ -381,10 +381,45 @@ function useMediaObjectUrl(media, options) {
 
 // src/pdf-context.tsx
 import React3 from "react";
+
+// src/preview-labels.ts
+var ERROR_TEXT = {
+  http_error: "The file couldn't be loaded.",
+  too_large: "The file is too large to preview.",
+  unsupported_type: "This file type can't be previewed.",
+  type_mismatch: "The file's content doesn't match its type."
+};
+var defaultPreviewLabels = {
+  document: (title, pageCount) => `${title}, ${pageCount === 1 ? "1 page" : `${pageCount} pages`}`,
+  page: (page, pageCount) => `Page ${page} of ${pageCount}`,
+  loading: "Loading\u2026",
+  pageCap: (shown, total) => `Showing the first ${shown} of ${total} pages.`,
+  error: (code) => ERROR_TEXT[code],
+  thumbnail: (title) => title,
+  untitledPdf: "PDF",
+  untitledMedia: "Preview",
+  download: "Download"
+};
+function mergePreviewLabels(...sources) {
+  const merged = { ...defaultPreviewLabels };
+  for (const source of sources) {
+    for (const [key, value] of Object.entries(source ?? {})) {
+      if (value !== void 0) merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+// src/pdf-context.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
 var PdfPreviewContext = React3.createContext({});
-function PdfPreviewProvider({ pdfjs, workerSrc, children }) {
-  const config = React3.useMemo(() => ({ pdfjs, workerSrc }), [pdfjs, workerSrc]);
+function PdfPreviewProvider({
+  pdfjs,
+  workerSrc,
+  labels,
+  children
+}) {
+  const config = React3.useMemo(() => ({ pdfjs, workerSrc, labels }), [pdfjs, workerSrc, labels]);
   return /* @__PURE__ */ jsx2(PdfPreviewContext.Provider, { value: config, children });
 }
 var loadedModules = /* @__PURE__ */ new WeakMap();
@@ -413,6 +448,10 @@ function usePdfjs(workerSrcOverride) {
   if (!loaded.pdfjs) return { status: "unavailable" };
   return { status: "ready", pdfjs: loaded.pdfjs, workerSrc: workerSrcOverride ?? workerSrc };
 }
+function usePreviewLabels(labels) {
+  const providerLabels = React3.useContext(PdfPreviewContext).labels;
+  return mergePreviewLabels(providerLabels, labels);
+}
 
 // src/pdf-thumbnail.tsx
 import React6 from "react";
@@ -555,7 +594,7 @@ var VISUALLY_HIDDEN = {
 var DEFAULT_MAX_PAGES = 500;
 var keepBytes = (bytes) => bytes;
 function PdfPreview(props) {
-  const { media, expectedType, maxBytes, fallback, loading, title, className, pdfWorkerSrc, maxPages } = props;
+  const { media, expectedType, maxBytes, renderFallback, loading, labels, title, className, pdfWorkerSrc } = props;
   const pdfjsState = usePdfjs(pdfWorkerSrc);
   const { value: bytes, error } = useMediaResource(media, {
     isEnabled: true,
@@ -563,9 +602,9 @@ function PdfPreview(props) {
     contentType: expectedType,
     decode: keepBytes
   });
-  if (error) return /* @__PURE__ */ jsx3(Fragment, { children: fallback });
+  if (error) return /* @__PURE__ */ jsx3(Fragment, { children: renderFallback(error) });
   if (!bytes || pdfjsState.status === "loading") return /* @__PURE__ */ jsx3(Fragment, { children: loading });
-  const label = title ?? media.filename ?? "PDF";
+  const label = title ?? media.filename ?? labels.untitledPdf;
   if (pdfjsState.status === "unavailable") return /* @__PURE__ */ jsx3(PdfFrame, { bytes, label, className });
   return /* @__PURE__ */ jsx3(
     PdfCanvasDocument,
@@ -575,39 +614,54 @@ function PdfPreview(props) {
       bytes,
       label,
       className,
-      fallback,
+      renderFallback,
       loading,
-      maxPages: maxPages ?? DEFAULT_MAX_PAGES
+      labels,
+      maxPages: props.maxPages ?? DEFAULT_MAX_PAGES
     }
   );
 }
 function PdfCanvasDocument(props) {
-  const { pdfjs, workerSrc, bytes, label, className, fallback, loading, maxPages } = props;
+  const { pdfjs, workerSrc, bytes, label, className, renderFallback, loading, labels, maxPages } = props;
   const { document: document2, error } = usePdfDocument({ pdfjs, bytes, workerSrc });
   const containerRef = React5.useRef(null);
   const [width, setWidth] = React5.useState(null);
   React5.useLayoutEffect(() => {
     if (document2) setWidth(containerRef.current?.clientWidth ?? 0);
   }, [document2]);
-  if (error) return /* @__PURE__ */ jsx3(Fragment, { children: fallback });
+  if (error) return /* @__PURE__ */ jsx3(Fragment, { children: renderFallback(error) });
   if (!document2) return /* @__PURE__ */ jsx3(Fragment, { children: loading });
   const shownPageCount = Math.min(document2.numPages, Math.max(1, maxPages));
   const isTruncated = shownPageCount < document2.numPages;
   const pageNumbers = Array.from({ length: shownPageCount }, (_, index) => index + 1);
-  const pageCountLabel = document2.numPages === 1 ? "1 page" : `${document2.numPages} pages`;
-  return /* @__PURE__ */ jsxs2("div", { ref: containerRef, role: "document", "aria-label": `${label}, ${pageCountLabel}`, className, children: [
-    width !== null && pageNumbers.map((pageNumber) => /* @__PURE__ */ jsx3(PdfPageView, { document: document2, pageNumber, width }, pageNumber)),
-    isTruncated && /* @__PURE__ */ jsxs2("p", { children: [
-      "Showing the first ",
-      shownPageCount,
-      " of ",
-      document2.numPages,
-      " pages. ",
-      fallback
-    ] })
-  ] });
+  return /* @__PURE__ */ jsxs2(
+    "div",
+    {
+      ref: containerRef,
+      role: "document",
+      "aria-label": labels.document(label, document2.numPages),
+      className,
+      children: [
+        width !== null && pageNumbers.map((pageNumber) => /* @__PURE__ */ jsx3(
+          PdfPageView,
+          {
+            document: document2,
+            pageNumber,
+            width,
+            label: labels.page(pageNumber, document2.numPages)
+          },
+          pageNumber
+        )),
+        isTruncated && /* @__PURE__ */ jsxs2("p", { children: [
+          labels.pageCap(shownPageCount, document2.numPages),
+          " ",
+          renderFallback(null)
+        ] })
+      ]
+    }
+  );
 }
-function PdfPageView({ document: document2, pageNumber, width }) {
+function PdfPageView({ document: document2, pageNumber, width, label }) {
   const pageRef = React5.useRef(null);
   const canvasRef = React5.useRef(null);
   const isVisible = useIsVisible(pageRef);
@@ -620,7 +674,7 @@ function PdfPageView({ document: document2, pageNumber, width }) {
     shouldExtractText: true
   });
   const placeholderStyle = isRendered ? void 0 : { aspectRatio: "1 / 1.4142", maxWidth: "100%" };
-  return /* @__PURE__ */ jsxs2("section", { ref: pageRef, "aria-label": `Page ${pageNumber} of ${document2.numPages}`, style: placeholderStyle, children: [
+  return /* @__PURE__ */ jsxs2("section", { ref: pageRef, "aria-label": label, style: placeholderStyle, children: [
     /* @__PURE__ */ jsx3("canvas", { ref: canvasRef, style: { display: "block", maxWidth: "100%" } }),
     text && /* @__PURE__ */ jsx3("p", { style: VISUALLY_HIDDEN, children: text })
   ] });
@@ -645,6 +699,7 @@ function PdfThumbnail(props) {
   const containerRef = React6.useRef(null);
   const isVisible = useIsVisible(containerRef);
   const pdfjsState = usePdfjs(props.pdfWorkerSrc);
+  const labels = usePreviewLabels(props.labels);
   const expectedType = media ? expectedContentType(media, contentType) : null;
   const isPdf = previewKindOf(expectedType) === "pdf";
   const { value: bytes, error } = useMediaResource(media, {
@@ -665,7 +720,7 @@ function PdfThumbnail(props) {
         workerSrc: pdfjsState.workerSrc,
         bytes,
         width,
-        label: props.title ?? media.filename ?? "PDF",
+        label: labels.thumbnail(props.title ?? media.filename ?? labels.untitledPdf),
         fallback,
         loading
       }
@@ -689,21 +744,32 @@ import { VideoPlayer } from "@devultur/react";
 import { Fragment as Fragment3, jsx as jsx5 } from "react/jsx-runtime";
 var DEFAULT_MAX_TEXT_BYTES = 1024 * 1024;
 var DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
-function Preview({ media, contentType, fallback, ...viewProps }) {
+function Preview({ media, contentType, fallback, loading, labels, ...viewProps }) {
+  const text = usePreviewLabels(labels);
   if (!media) return null;
-  const fallbackNode = fallback === void 0 ? /* @__PURE__ */ jsx5(DownloadLink, { media, children: media.filename ?? "Download" }) : fallback;
   if (media.kind === "video") return /* @__PURE__ */ jsx5(VideoPreview, { media, className: viewProps.className });
+  const renderFallback = (error) => {
+    const fetchError = error instanceof MediaFetchError ? error : null;
+    if (typeof fallback === "function") return fallback(fetchError);
+    if (fallback !== void 0) return fallback;
+    return /* @__PURE__ */ jsx5(DefaultFallback, { media, error: fetchError, labels: text });
+  };
   const expectedType = expectedContentType(media, contentType);
   const kind = previewKindOf(expectedType);
-  if (!expectedType || !kind) return /* @__PURE__ */ jsx5(Fragment3, { children: fallbackNode });
-  const props = { ...viewProps, media, expectedType, fallback: fallbackNode };
+  if (!expectedType || !kind) return /* @__PURE__ */ jsx5(Fragment3, { children: renderFallback(unsupportedType(expectedType)) });
+  const loadingNode = loading === void 0 ? /* @__PURE__ */ jsx5(LoadingStatus, { text: text.loading }) : loading;
+  const props = { ...viewProps, media, expectedType, renderFallback, loading: loadingNode, labels: text };
   if (kind === "text") return /* @__PURE__ */ jsx5(TextPreview, { ...props });
-  if (kind === "pdf") {
-    const { maxBytes = DEFAULT_MAX_BYTES, loading = null } = props;
-    return /* @__PURE__ */ jsx5(PdfPreview, { ...props, maxBytes, loading });
-  }
+  if (kind === "pdf") return /* @__PURE__ */ jsx5(PdfPreview, { ...props, maxBytes: props.maxBytes ?? DEFAULT_MAX_BYTES });
   return /* @__PURE__ */ jsx5(BinaryPreview, { ...props, kind });
 }
+var unsupportedType = (contentType) => new MediaFetchError("unsupported_type", `Can't preview ${contentType ?? "an unknown type"} inline`);
+function DefaultFallback({ media, error, labels }) {
+  return /* @__PURE__ */ jsx5(DownloadLink, { media, title: error ? labels.error(error.code) : void 0, children: media.filename ?? labels.download });
+}
+function LoadingStatus({ text }) {
+  return /* @__PURE__ */ jsx5("span", { role: "status", style: VISUALLY_HIDDEN, children: text });
+}
 function VideoPreview({ media, className }) {
   const videoProps = useVideoProps(media);
   if (!videoProps) return null;
@@ -714,8 +780,9 @@ function BinaryPreview({
   kind,
   expectedType,
   maxBytes = DEFAULT_MAX_BYTES,
-  fallback,
-  loading = null,
+  renderFallback,
+  loading,
+  labels,
   title,
   className
 }) {
@@ -723,9 +790,9 @@ function BinaryPreview({
   const isPublicImage = kind === "image" && media.visibility === "public";
   const verified = useMediaObjectUrl(media, { enabled: !isPublicImage, contentType: expectedType, maxBytes });
   const objectUrl = isPublicImage ? url(media) : verified.objectUrl;
-  if (verified.error) return /* @__PURE__ */ jsx5(Fragment3, { children: fallback });
+  if (verified.error) return /* @__PURE__ */ jsx5(Fragment3, { children: renderFallback(verified.error) });
   if (!objectUrl) return /* @__PURE__ */ jsx5(Fragment3, { children: loading });
-  const label = title ?? media.filename ?? "Preview";
+  const label = title ?? media.filename ?? labels.untitledMedia;
   if (kind === "image") {
     return /* @__PURE__ */ jsx5("img", { src: objectUrl, alt: label, width: media.width, height: media.height, className });
   }
@@ -736,8 +803,8 @@ function TextPreview({
   media,
   expectedType,
   maxTextBytes = DEFAULT_MAX_TEXT_BYTES,
-  fallback,
-  loading = null,
+  renderFallback,
+  loading,
   title,
   className
 }) {
@@ -747,7 +814,7 @@ function TextPreview({
     contentType: expectedType,
     decode: decodeText
   });
-  if (error) return /* @__PURE__ */ jsx5(Fragment3, { children: fallback });
+  if (error) return /* @__PURE__ */ jsx5(Fragment3, { children: renderFallback(error) });
   if (text === null) return /* @__PURE__ */ jsx5(Fragment3, { children: loading });
   return /* @__PURE__ */ jsx5("pre", { title, className, children: text });
 }
@@ -1366,6 +1433,7 @@ export {
   PdfPreviewProvider,
   PdfThumbnail,
   Preview,
+  defaultPreviewLabels,
   useDevultur,
   useDevulturMedia,
   useDevulturProgress,

package/dist/validators.d.ts

@@ -12,22 +12,22 @@ import { DevulturKind } from '@devultur/core';
  */
 declare const dv: {
     media(kind?: DevulturKind): convex_values.VObject<{
-        filename?: string | undefined;
         key?: string | undefined;
-        width?: number | undefined;
+        filename?: string | undefined;
         height?: number | undefined;
+        width?: number | undefined;
+        visibility: "public" | "private";
         id: string;
         kind: DevulturKind;
-        visibility: "public" | "private";
     }, {
-        kind: convex_values.VLiteral<DevulturKind, "required"> | convex_values.VUnion<"image" | "video" | "file", [convex_values.VLiteral<"image", "required">, convex_values.VLiteral<"video", "required">, convex_values.VLiteral<"file", "required">], "required", never>;
+        kind: convex_values.VLiteral<DevulturKind, "required"> | convex_values.VUnion<"video" | "image" | "file", [convex_values.VLiteral<"image", "required">, convex_values.VLiteral<"video", "required">, convex_values.VLiteral<"file", "required">], "required", never>;
         id: convex_values.VString<string, "required">;
         visibility: convex_values.VUnion<"public" | "private", [convex_values.VLiteral<"public", "required">, convex_values.VLiteral<"private", "required">], "required", never>;
         filename: convex_values.VString<string | undefined, "optional">;
         key: convex_values.VString<string | undefined, "optional">;
         width: convex_values.VFloat64<number | undefined, "optional">;
         height: convex_values.VFloat64<number | undefined, "optional">;
-    }, "required", "id" | "kind" | "visibility" | "filename" | "key" | "width" | "height">;
+    }, "required", "key" | "filename" | "visibility" | "height" | "width" | "id" | "kind">;
 };
 
 export { dv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Convex component for Devultur media: media records, uploads, transcodes, watch progress and React bindings",
   "keywords": [
     "convex",
@@ -55,8 +55,8 @@
     "dist"
   ],
   "dependencies": {
-    "@devultur/core": "1.3.0",
-    "@devultur/react": "1.3.0"
+    "@devultur/core": "1.3.1",
+    "@devultur/react": "1.3.1"
   },
   "peerDependencies": {
     "convex": ">=1.25.0",