@jskit-ai/uploads-image-web 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,80 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/uploads-image-web",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Reusable client-side image upload runtime with pre-upload image editing.",
+  dependsOn: [
+    "@jskit-ai/uploads-runtime"
+  ],
+  capabilities: {
+    provides: [
+      "runtime.uploads.image-web"
+    ],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    client: {
+      optimizeDeps: {
+        include: [
+          "@uppy/core",
+          "@uppy/dashboard",
+          "@uppy/image-editor",
+          "@uppy/compressor",
+          "@uppy/xhr-upload"
+        ]
+      }
+    },
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./client",
+          summary: "Exports reusable image upload client runtime helpers."
+        },
+        {
+          subpath: "./client/composables/createImageUploadRuntime",
+          summary: "Exports the reusable image upload runtime factory."
+        },
+        {
+          subpath: "./client/styles",
+          summary: "Exports Uppy CSS side effects for image upload UIs."
+        },
+        {
+          subpath: "./shared",
+          summary: "Exports shared image upload defaults."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/uploads-runtime": "0.1.1",
+        "@uppy/compressor": "^3.1.0",
+        "@uppy/core": "^5.2.0",
+        "@uppy/dashboard": "^5.1.1",
+        "@uppy/image-editor": "^4.2.0",
+        "@uppy/xhr-upload": "^5.1.1"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [],
+    text: []
+  }
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@jskit-ai/uploads-image-web",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./client/composables/createImageUploadRuntime": "./src/client/composables/createImageUploadRuntime.js",
+    "./client/styles": "./src/client/styles/index.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/uploads-runtime": "0.1.1",
+    "@uppy/compressor": "^3.1.0",
+    "@uppy/core": "^5.2.0",
+    "@uppy/dashboard": "^5.1.1",
+    "@uppy/image-editor": "^4.2.0",
+    "@uppy/xhr-upload": "^5.1.1"
+  }
+}

package/src/client/composables/createImageUploadRuntime.js

@@ -0,0 +1,245 @@
+import Uppy from "@uppy/core";
+import Dashboard from "@uppy/dashboard";
+import ImageEditor from "@uppy/image-editor";
+import Compressor from "@uppy/compressor";
+import XHRUpload from "@uppy/xhr-upload";
+import {
+  DEFAULT_IMAGE_COMPRESSOR_OPTIONS,
+  DEFAULT_IMAGE_DASHBOARD_OPTIONS,
+  DEFAULT_IMAGE_EDITOR_OPTIONS,
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+} from "../../shared/imageUploadDefaults.js";
+import { parseUploadResponse } from "../support/parseUploadResponse.js";
+import { stopImageEditor } from "../support/stopImageEditor.js";
+
+function normalizeObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+function createImageUploadRuntime({
+  endpoint = "",
+  method = "POST",
+  fieldName = "file",
+  withCredentials = true,
+  maxNumberOfFiles = 1,
+  allowedMimeTypes = DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  maxUploadBytes = DEFAULT_IMAGE_UPLOAD_MAX_BYTES,
+  note = "",
+  dashboardOptions = {},
+  imageEditorOptions = {},
+  compressorOptions = {},
+  parseResponse = parseUploadResponse,
+  resolveRequestHeaders = null,
+  onSelectedFileNameChanged = null,
+  onUploadSuccess = null,
+  onInvalidResponse = null,
+  onUploadError = null,
+  onRestrictionFailed = null,
+  onUnavailable = null,
+  dependencies = {}
+} = {}) {
+  const UppyClass = dependencies.UppyClass || Uppy;
+  const DashboardPlugin = dependencies.DashboardPlugin || Dashboard;
+  const ImageEditorPlugin = dependencies.ImageEditorPlugin || ImageEditor;
+  const CompressorPlugin = dependencies.CompressorPlugin || Compressor;
+  const XHRUploadPlugin = dependencies.XHRUploadPlugin || XHRUpload;
+  let uploadUppy = null;
+
+  const normalizedAllowedMimeTypes =
+    Array.isArray(allowedMimeTypes) && allowedMimeTypes.length > 0
+      ? allowedMimeTypes.map((value) => String(value || "").trim()).filter(Boolean)
+      : [...DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES];
+  const normalizedMaxUploadBytes =
+    Number.isInteger(maxUploadBytes) && maxUploadBytes > 0 ? maxUploadBytes : DEFAULT_IMAGE_UPLOAD_MAX_BYTES;
+  const normalizedEndpoint = String(endpoint || "").trim();
+  const normalizedFieldName = String(fieldName || "file").trim() || "file";
+  const normalizedMethod = String(method || "POST").trim().toUpperCase() || "POST";
+  const dashboardNote =
+    String(note || "").trim() ||
+    `Accepted: ${normalizedAllowedMimeTypes.join(", ")}, max ${Math.floor(normalizedMaxUploadBytes / (1024 * 1024))}MB`;
+
+  function emitSelectedFileName(fileName) {
+    if (typeof onSelectedFileNameChanged === "function") {
+      onSelectedFileNameChanged(String(fileName || ""));
+    }
+  }
+
+  function setup() {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    if (uploadUppy) {
+      return;
+    }
+
+    const uppy = new UppyClass({
+      autoProceed: false,
+      restrictions: {
+        maxNumberOfFiles: Number.isInteger(maxNumberOfFiles) && maxNumberOfFiles > 0 ? maxNumberOfFiles : 1,
+        allowedFileTypes: [...normalizedAllowedMimeTypes],
+        maxFileSize: normalizedMaxUploadBytes
+      }
+    });
+
+    uppy.use(DashboardPlugin, {
+      ...DEFAULT_IMAGE_DASHBOARD_OPTIONS,
+      ...normalizeObject(dashboardOptions),
+      note: dashboardNote,
+      doneButtonHandler: () => {
+        const dashboard = uppy.getPlugin("Dashboard");
+        if (dashboard && typeof dashboard.closeModal === "function") {
+          dashboard.closeModal();
+        }
+      }
+    });
+
+    uppy.use(ImageEditorPlugin, {
+      ...DEFAULT_IMAGE_EDITOR_OPTIONS,
+      ...normalizeObject(imageEditorOptions)
+    });
+
+    uppy.use(CompressorPlugin, {
+      ...DEFAULT_IMAGE_COMPRESSOR_OPTIONS,
+      ...normalizeObject(compressorOptions)
+    });
+
+    uppy.use(XHRUploadPlugin, {
+      endpoint: normalizedEndpoint,
+      method: normalizedMethod,
+      formData: true,
+      fieldName: normalizedFieldName,
+      withCredentials: withCredentials !== false,
+      onBeforeRequest: async (xhr) => {
+        const headers =
+          typeof resolveRequestHeaders === "function"
+            ? normalizeObject(await resolveRequestHeaders({ xhr, uppy }))
+            : {};
+        for (const [headerName, headerValue] of Object.entries(headers)) {
+          if (headerValue == null) {
+            continue;
+          }
+          xhr.setRequestHeader(headerName, String(headerValue));
+        }
+      },
+      getResponseData: parseResponse
+    });
+
+    uppy.on("file-added", (file) => {
+      emitSelectedFileName(file?.name || "");
+    });
+
+    uppy.on("file-removed", () => {
+      emitSelectedFileName("");
+    });
+
+    uppy.on("file-editor:complete", (file) => {
+      emitSelectedFileName(file?.name || "");
+      stopImageEditor(uppy);
+    });
+
+    uppy.on("file-editor:cancel", () => {
+      stopImageEditor(uppy);
+    });
+
+    uppy.on("dashboard:modal-closed", () => {
+      stopImageEditor(uppy);
+    });
+
+    uppy.on("upload-success", (file, response) => {
+      const data = response?.body;
+      if (!data || typeof data !== "object") {
+        if (typeof onInvalidResponse === "function") {
+          onInvalidResponse({
+            file,
+            response,
+            uppy
+          });
+        }
+        return;
+      }
+
+      if (typeof onUploadSuccess === "function") {
+        onUploadSuccess({
+          data,
+          file,
+          response,
+          uppy
+        });
+      }
+
+      emitSelectedFileName("");
+    });
+
+    uppy.on("upload-error", (file, error, response) => {
+      if (typeof onUploadError === "function") {
+        onUploadError({
+          file,
+          error,
+          response,
+          uppy
+        });
+      }
+    });
+
+    uppy.on("restriction-failed", (file, error) => {
+      if (typeof onRestrictionFailed === "function") {
+        onRestrictionFailed({
+          file,
+          error,
+          uppy
+        });
+      }
+    });
+
+    uppy.on("complete", (result) => {
+      const successfulCount = Array.isArray(result?.successful) ? result.successful.length : 0;
+      if (successfulCount <= 0) {
+        return;
+      }
+
+      try {
+        uppy.clear();
+      } catch {
+        // Upload succeeded; ignore clear timing issues.
+      }
+    });
+
+    uploadUppy = uppy;
+  }
+
+  function openEditor() {
+    setup();
+
+    const uppy = uploadUppy;
+    if (!uppy) {
+      if (typeof onUnavailable === "function") {
+        onUnavailable();
+      }
+      return;
+    }
+
+    const dashboard = uppy.getPlugin("Dashboard");
+    if (dashboard && typeof dashboard.openModal === "function") {
+      dashboard.openModal();
+    }
+  }
+
+  function destroy() {
+    if (!uploadUppy) {
+      return;
+    }
+
+    uploadUppy.destroy();
+    uploadUppy = null;
+  }
+
+  return Object.freeze({
+    destroy,
+    openEditor,
+    setup
+  });
+}
+
+export { createImageUploadRuntime };

package/src/client/index.js

@@ -0,0 +1,5 @@
+export { createImageUploadRuntime } from "./composables/createImageUploadRuntime.js";
+
+const clientProviders = Object.freeze([]);
+
+export { clientProviders };

package/src/client/styles/index.js

@@ -0,0 +1,5 @@
+import "@uppy/core/css/style.min.css";
+import "@uppy/dashboard/css/style.min.css";
+import "@uppy/image-editor/css/style.min.css";
+
+export {};

package/src/client/support/parseUploadResponse.js

@@ -0,0 +1,13 @@
+function parseUploadResponse(xhr) {
+  if (!xhr?.responseText) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(xhr.responseText);
+  } catch {
+    return {};
+  }
+}
+
+export { parseUploadResponse };

package/src/client/support/stopImageEditor.js

@@ -0,0 +1,8 @@
+function stopImageEditor(uppy) {
+  const imageEditor = uppy?.getPlugin?.("ImageEditor");
+  if (imageEditor && typeof imageEditor.stop === "function") {
+    imageEditor.stop();
+  }
+}
+
+export { stopImageEditor };

package/src/shared/imageUploadDefaults.js

@@ -0,0 +1,29 @@
+import {
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+} from "@jskit-ai/uploads-runtime/shared";
+
+const DEFAULT_IMAGE_EDITOR_OPTIONS = Object.freeze({
+  quality: 0.9
+});
+
+const DEFAULT_IMAGE_COMPRESSOR_OPTIONS = Object.freeze({
+  quality: 0.84,
+  limit: 1
+});
+
+const DEFAULT_IMAGE_DASHBOARD_OPTIONS = Object.freeze({
+  inline: false,
+  closeAfterFinish: false,
+  showProgressDetails: true,
+  proudlyDisplayPoweredByUppy: false,
+  hideUploadButton: false
+});
+
+export {
+  DEFAULT_IMAGE_COMPRESSOR_OPTIONS,
+  DEFAULT_IMAGE_DASHBOARD_OPTIONS,
+  DEFAULT_IMAGE_EDITOR_OPTIONS,
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+};

package/src/shared/index.js

@@ -0,0 +1,7 @@
+export {
+  DEFAULT_IMAGE_COMPRESSOR_OPTIONS,
+  DEFAULT_IMAGE_DASHBOARD_OPTIONS,
+  DEFAULT_IMAGE_EDITOR_OPTIONS,
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+} from "./imageUploadDefaults.js";

package/test/createImageUploadRuntime.test.js

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createImageUploadRuntime } from "../src/client/composables/createImageUploadRuntime.js";
+
+class FakeUppy {
+  constructor(options) {
+    this.options = options;
+    this.plugins = new Map();
+    this.pluginOptions = new Map();
+    this.eventHandlers = new Map();
+    this.clearCount = 0;
+    this.destroyCount = 0;
+  }
+
+  use(plugin, options) {
+    const pluginName = String(plugin?.name || plugin?.pluginName || "");
+    this.pluginOptions.set(pluginName, options);
+
+    if (pluginName === "Dashboard") {
+      this.plugins.set("Dashboard", {
+        openCount: 0,
+        closeCount: 0,
+        openModal() {
+          this.openCount += 1;
+        },
+        closeModal() {
+          this.closeCount += 1;
+        }
+      });
+    } else if (pluginName === "ImageEditor") {
+      this.plugins.set("ImageEditor", {
+        stopCount: 0,
+        stop() {
+          this.stopCount += 1;
+        }
+      });
+    }
+
+    return this;
+  }
+
+  on(eventName, handler) {
+    this.eventHandlers.set(eventName, handler);
+    return this;
+  }
+
+  getPlugin(name) {
+    return this.plugins.get(name) || null;
+  }
+
+  clear() {
+    this.clearCount += 1;
+  }
+
+  destroy() {
+    this.destroyCount += 1;
+  }
+}
+
+function setWindowStub() {
+  const previousWindow = globalThis.window;
+  globalThis.window = {};
+  return () => {
+    if (previousWindow === undefined) {
+      delete globalThis.window;
+      return;
+    }
+    globalThis.window = previousWindow;
+  };
+}
+
+test("createImageUploadRuntime wires headers and lifecycle callbacks", async () => {
+  const restoreWindow = setWindowStub();
+  let fakeUppy = null;
+
+  try {
+    const fileNames = [];
+    const successPayloads = [];
+    const invalidResponses = [];
+    const unavailableCalls = [];
+    const restrictionFailures = [];
+    const uploadErrors = [];
+
+    const runtime = createImageUploadRuntime({
+      endpoint: "/api/upload",
+      fieldName: "avatar",
+      resolveRequestHeaders: async () => ({
+        "csrf-token": "csrf-1"
+      }),
+      onSelectedFileNameChanged: (name) => {
+        fileNames.push(name);
+      },
+      onUploadSuccess: (payload) => {
+        successPayloads.push(payload.data);
+      },
+      onInvalidResponse: (payload) => {
+        invalidResponses.push(payload.response?.body || null);
+      },
+      onUploadError: (payload) => {
+        uploadErrors.push(payload.error?.message || "");
+      },
+      onRestrictionFailed: (payload) => {
+        restrictionFailures.push(payload.error?.message || "");
+      },
+      onUnavailable: () => {
+        unavailableCalls.push(true);
+      },
+      dependencies: {
+        UppyClass: class extends FakeUppy {
+          constructor(options) {
+            super(options);
+            fakeUppy = this;
+          }
+        },
+        DashboardPlugin: { name: "Dashboard" },
+        ImageEditorPlugin: { name: "ImageEditor" },
+        CompressorPlugin: { name: "Compressor" },
+        XHRUploadPlugin: { name: "XHRUpload" }
+      }
+    });
+
+    runtime.setup();
+    runtime.openEditor();
+
+    assert.ok(fakeUppy);
+    const pluginOptions = fakeUppy.pluginOptions || new Map();
+    const xhrOptions = pluginOptions.get("XHRUpload");
+
+    const headers = [];
+    await xhrOptions.onBeforeRequest({
+      setRequestHeader(name, value) {
+        headers.push([name, value]);
+      }
+    });
+    assert.deepEqual(headers, [["csrf-token", "csrf-1"]]);
+
+    fakeUppy.eventHandlers.get("file-added")({ name: "face.png" });
+    fakeUppy.eventHandlers.get("file-editor:complete")({ name: "face-edited.png" });
+    fakeUppy.eventHandlers.get("upload-success")({}, { body: { ok: true } });
+    fakeUppy.eventHandlers.get("upload-success")({}, { body: "" });
+    fakeUppy.eventHandlers.get("upload-error")({}, new Error("boom"), {});
+    fakeUppy.eventHandlers.get("restriction-failed")({}, new Error("nope"));
+    fakeUppy.eventHandlers.get("complete")({ successful: [{}] });
+
+    assert.deepEqual(fileNames, ["face.png", "face-edited.png", ""]);
+    assert.deepEqual(successPayloads, [{ ok: true }]);
+    assert.deepEqual(invalidResponses, [null]);
+    assert.deepEqual(uploadErrors, ["boom"]);
+    assert.deepEqual(restrictionFailures, ["nope"]);
+    assert.equal(fakeUppy.clearCount, 1);
+
+    runtime.destroy();
+    assert.equal(fakeUppy.destroyCount, 1);
+    assert.deepEqual(unavailableCalls, []);
+  } finally {
+    restoreWindow();
+  }
+});
+
+test("createImageUploadRuntime reports unavailable editor outside browser environments", () => {
+  const unavailableCalls = [];
+
+  const runtime = createImageUploadRuntime({
+    onUnavailable: () => {
+      unavailableCalls.push(true);
+    }
+  });
+
+  runtime.openEditor();
+  assert.deepEqual(unavailableCalls, [true]);
+});

package/test/exportsContract.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluatePackageExportsContract } from "../../../tooling/test-support/exportsContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "uploads-image-web");
+
+test("uploads-image-web exports are explicit and aligned with usage", () => {
+  const result = evaluatePackageExportsContract({
+    repoRoot: REPO_ROOT,
+    packageDir: PACKAGE_DIR,
+    packageId: "@jskit-ai/uploads-image-web",
+    requiredExports: ["./client", "./shared"]
+  });
+
+  assert.deepEqual(result.wildcardExports, []);
+  assert.deepEqual(result.missingRequiredExports, []);
+  assert.deepEqual(result.missingExports, []);
+  assert.deepEqual(result.staleExports, []);
+});