nexus-shared 3.2.0 → 4.0.0

package/dist/Interfaces/FileInterfaces.d.ts

@@ -0,0 +1,162 @@
+import type { ApiModuleValue, AppModule } from "./ApiInterfaces.ts";
+/**
+ * Whose files: the module that owns the row, the category, and the row's id. The module decides who may change them
+ * (with Nexus, its `Files/Ticket` signs the change), so it is the owner's module, not the one that stores the bytes.
+ *
+ * @example
+ * { module: NexusModule.Enterprise, category: "branch-picture", ownerId: branch.id }
+ * { module: NexusModule.Enterprise, category: "user-picture", ownerId: "me" } // the person's own
+ */
+export interface FileOwner<TModule extends ApiModuleValue = AppModule> {
+    module: TModule;
+    /** The category's code: `branch-picture`, `subscriber-document`. */
+    category: string;
+    /** The owner row's id, as the module answers it; `me` for the person's own. */
+    ownerId: string;
+}
+/** Which copy of a stored file: the file itself, or its small picture. */
+export type FileCopy = "original" | "thumbnail";
+/** One stored file, as the adapter reads it. */
+export interface StoredFile {
+    /** Its id, as the backend answers it (with Nexus, encrypted for the person asking). */
+    id: string;
+    /** The name it is shown by, with the extension of what it really is. */
+    name: string;
+    /** What its bytes are: `image/png`, `image/jpeg`, `image/webp`, `application/pdf`. */
+    contentType: string;
+    /** Its size in bytes. */
+    size: number;
+    /** A picture's size in pixels; null for a document. */
+    width: number | null;
+    height: number | null;
+    /** Whether a thumbnail was stored with it. Without one, the thumbnail copy is the file itself (pictures only). */
+    hasThumbnail: boolean;
+    /** Whether it is the owner's picture: at most one per owner and category. */
+    isPrimary: boolean;
+    /** When it was stored: an ISO UTC moment, or null when the backend does not say. */
+    createdAt: string | null;
+}
+/** What a category takes, as the backend says: what a gallery tells the person before an upload is refused. */
+export interface FileCategoryInfo {
+    /** The category's code. */
+    code: string;
+    /** Its name: "Branch picture". */
+    name: string;
+    /** The MIME types it takes: `["image/png", "image/jpeg", "image/webp"]`. */
+    types: readonly string[];
+    /** The largest file it takes, in bytes. */
+    maxBytes: number;
+    /** How many files one owner keeps. */
+    maxCount: number;
+    /** The longest side of a thumbnail in pixels; 0 when it keeps none. */
+    thumbnailSize: number;
+    /** Whether this person may change the files: upload, make primary, rename, delete. */
+    canWrite: boolean;
+    /**
+     * The longest side a stored picture may have, in pixels: Drive's `Nexus:Drive:Pictures:MaxSide`. Every picture is
+     * made to fit it in the browser before it is sent. Default `PICTURE_LIMITS.maxSide` (1920) when the backend does not say.
+     */
+    pictureMaxSide?: number;
+    /** The highest quality a picture is written at, in percent: Drive's `Quality`. Default `PICTURE_LIMITS.quality` (80). */
+    pictureQuality?: number;
+    /**
+     * The most bytes a stored picture may hold: Drive's `MaxKilobytes`, never above `maxBytes`. The browser writes every
+     * picture under it (a lower quality, then a smaller size). Default `PICTURE_LIMITS.maxBytes` (300 KB), at most `maxBytes`.
+     */
+    pictureMaxBytes?: number;
+}
+/** An owner's files and what their category takes. */
+export interface OwnerFiles {
+    category: FileCategoryInfo;
+    /** The live files, in their order. */
+    files: StoredFile[];
+    /**
+     * Why this person may only look (`category.canWrite` false), in the backend's words when it gave them: the refusal of
+     * the write ticket ("You do not hold the key to change this branch").
+     */
+    readOnlyReason?: string;
+}
+/** What an upload sends: the file the browser made, and for a picture its thumbnail. */
+export interface FileUpload {
+    file: Blob;
+    /** The name to keep: "Front desk.jpg". The backend keeps the real kind's extension whatever it says. */
+    name: string;
+    thumbnail?: Blob | null;
+}
+/** What every call of the adapter takes. */
+export interface FileCallOptions {
+    signal?: AbortSignal;
+    /** Shows no toast for this call: the panel says what happened. */
+    toast?: false;
+}
+/** Picture kinds a browser canvas writes, and so the ones the editor saves. */
+export type PictureType = "image/jpeg" | "image/png" | "image/webp";
+/** The MIME types of pictures (what a canvas can read back), in the order a file picker offers them. */
+export declare const PICTURE_TYPES: readonly PictureType[];
+/** Whether a MIME type is a picture this package can show and edit. */
+export declare const isPictureType: (type: string | null | undefined) => type is PictureType;
+/** What the editor is opened with (a part of `nexus-image-editor`'s `ImageEditorOptions`). */
+export interface ImageEditorOptions {
+    src?: File | Blob | string;
+    /** A number locks the shape (1 for a logo or an avatar); `free` lets the person choose. */
+    aspect?: number | "free" | "original" | Array<number | "free" | "original">;
+    /** A round guide over a square crop, for a person's picture. */
+    shape?: "rect" | "circle";
+    maxWidth?: number;
+    maxHeight?: number;
+    minWidth?: number;
+    minHeight?: number;
+    type?: PictureType;
+    /**
+     * The kinds the place the picture goes to takes (a file category's): the only ones the editor offers and saves - a
+     * picture too large as a PNG becomes a JPEG or a WebP only when one of them is taken, else stays a PNG, made smaller.
+     */
+    types?: readonly PictureType[];
+    /** 0-1. */
+    quality?: number;
+    /** 0-1: the highest quality written (the slider's top, where it starts at most). */
+    maxQuality?: number;
+    /** The most bytes the saved file may hold: a lower quality, then a smaller picture, until it fits. */
+    maxBytes?: number;
+    /** The longest side of a thumbnail made with the picture, in pixels. */
+    thumbnail?: number | boolean;
+    title?: string;
+    fileName?: string;
+    signal?: AbortSignal;
+}
+/** What the editor answers on Save. */
+export interface ImageEditorResult {
+    blob: Blob;
+    width: number;
+    height: number;
+    type: string;
+    thumbnail: Blob | null;
+    name: string;
+    /** What `maxBytes` took (another type, a lower quality 0-1, the size it would have had), or null when nothing. */
+    fitted?: {
+        maxBytes: number;
+        type?: string;
+        quality?: number;
+        from?: {
+            width: number;
+            height: number;
+        };
+    } | null;
+}
+/** One picture of the viewer. */
+export interface ImageViewerItem {
+    src: string | Blob;
+    title?: string;
+}
+/** The parts of `nexus-image-editor` this package calls. */
+export interface ImageEditorModule {
+    openImageEditor(options?: ImageEditorOptions): Promise<ImageEditorResult | null>;
+    openImageViewer(options: {
+        images: ImageViewerItem[];
+        index?: number;
+        title?: string;
+    }): Promise<void>;
+    /** Makes the stored picture without opening the editor: the size clamped, the thumbnail made. `null` edits: as it is. */
+    renderImage(src: File | Blob | string, edits: null, options?: Pick<ImageEditorOptions, "maxWidth" | "maxHeight" | "type" | "types" | "quality" | "maxQuality" | "maxBytes" | "thumbnail">): Promise<Omit<ImageEditorResult, "name">>;
+    readonly VERSION: string;
+}

package/dist/Interfaces/FileInterfaces.js

@@ -0,0 +1,4 @@
+/** The MIME types of pictures (what a canvas can read back), in the order a file picker offers them. */
+export const PICTURE_TYPES = ["image/jpeg", "image/png", "image/webp"];
+/** Whether a MIME type is a picture this package can show and edit. */
+export const isPictureType = (type) => PICTURE_TYPES.includes(type);