studio-engine 0.4.11 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b843f965201c31cd83f0c1fd3f39830730fbc9e139a31c3a856c3e99853bf053
-  data.tar.gz: c7383f3cf9943f93a2f06150909ee23461d194e93b44c33848bb39106a6f10f9
+  metadata.gz: 38d351424eeef931252e2c219759db0fdd55605176d2daf7ca10ba283332144f
+  data.tar.gz: d23cacb846cc912b926bca4093bf6d9a8d0de3c1332147244cb0005d82ace99b
 SHA512:
-  metadata.gz: 2b65ebd2d798a2e06aa2572160d241e2c4557033da6aa3fb2ed4c2bb214e9f2c2119b11cd53e778401f100f318fce49a33531f260e0e8fe05d26449df3281fca
-  data.tar.gz: 8eae952bd9cc78f3705cea486a63fdfb6b667e112c1c207992813b2d3c942bda0fa513f1df4120069b3916703db4bab1d7aabdac3dd6553cacc0a8e239a77353
+  metadata.gz: 6e3af533680b72fc4a010c6c07143d75f332d7f6b82c8f5ef8310bfdd979258f2050d7bb581c39aad61c8187d7510e30abb5d621a7d4626769122f20bafe8957
+  data.tar.gz: 9434c0b55cd9275491cddaad6eae404ca78b30dd7d3e0fe42e29ae0b5ae8f5ee78b7a346b8e00c89ad8c4f881097e512092d9c607d023670bb017416a1bfb2b8

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Both consumer Rails apps pin to a tag in their `Gemfile`; bumping the tag is a release.
 
+## v0.4.12 (2026-06-02)
+
+Promotes the image crop-and-upload UI out of Turf Monster into the engine: a shared cropper modal, the immediate-save upload host, the loading-card-around-a-Turbo-submit helper, and the generic "saving" card. Any consumer can now add a cropped image upload (avatar, banner, logo, OG image) with one `imageUploadHost(...)` x-data plus the cropper assets partial — no bespoke JS.
+
+### Added
+- **`studio/_cropper_assets`** — cropper.js (1.6.2) CSS + JS **and** the three inline factories below. Render it on pages that can open the cropper (avatar field, banner editor); both the library and the behavior load only where an upload trigger exists. The JS rides with the page, **not** the modal host, so it works whether or not an app overrides `studio/modals/_host`.
+  - `window.imageUploadHost(opts)` — x-data host for crop-then-immediate-save uploaders. `open()` (modal-as-picker) / `onFileSelected()` (native picker) → `applyCrop()` drops the Blob into a hidden form input and submits with a loading card + toast.
+  - `window.submitFormWithProgress(form, opts)` — opens the `saving` card, holds ≥450ms, submits the Turbo form, then closes + toasts on `turbo:submit-end`.
+  - `window.cropPhotoModal(opts)` — the crop modal's x-data factory.
+- **`studio/modals/_crop_photo`** — the shared image cropper modal. Opens via `Alpine.store('modals').open('crop-photo', { imageUrl?, aspectRatio?, maxWidth?, maxHeight?, transparent?, autoCropArea?, dispatch? })`; hands the cropped Blob back via the `crop-photo-confirmed` window event.
+- **`studio/modals/_saving`** — generic loading card (title from `props.title`), opened by `submitFormWithProgress`.
+
+### Integration
+Register the two modals in your `studio/modals/host` block + render the assets on each upload page:
+```erb
+<%# inside the studio/modals/host block %>
+<template x-if="$store.modals.current().id === 'crop-photo'"><%= render "studio/modals/crop_photo" %></template>
+<template x-if="$store.modals.current().id === 'saving'"><%= render "studio/modals/saving" %></template>
+
+<%# on each page with an image upload %>
+<%= render "studio/cropper_assets" %>
+<div x-data="imageUploadHost({ aspectRatio: 1, filename: 'avatar.png', saving: 'Saving photo…', dismissible: true, toast: false })"
+     @crop-photo-confirmed.window="applyCrop($event.detail.blob)"> … hidden form (x-ref form + fileInput) + trigger … </div>
+```
+Registrations live in the host **block** (the consumer's `yield` content), so apps that override `studio/modals/_host` — like Turf Monster, which has a substantially diverged host — integrate the same way.
+
+### Migration
+For an app that had its own copies (Turf Monster):
+1. `bundle update studio-engine`.
+2. Delete the local `crop_photo_modal.js` (+ its importmap pin / `application.js` import), the `imageUploadHost` + `submitFormWithProgress` definitions, and `modals/_crop_photo` / `modals/_saving` / `shared/_cropper_assets`.
+3. Point the host block's crop-photo / saving registrations at `studio/modals/crop_photo` / `studio/modals/saving`, and the cropper-asset renders at `studio/cropper_assets`.
+
 ## v0.4.11 (2026-05-24)
 
 Preserves non-dismissible modals (e.g. pending on-chain TX) across bfcache restore and Turbo snapshot caching. Previously, the modal host's cleanup hooks called `closeAll()` on both `pageshow.persisted` and `turbo:before-cache`, which silently dropped any `dismissible: false` modal — including the processing card a still-in-flight JS promise was expecting to resolve against. The promise's `solanaModal.success()` then no-op'd against an empty stack and the user saw nothing despite their TX landing on-chain.

data/app/views/studio/_cropper_assets.html.erb

@@ -0,0 +1,11 @@
+<%# Cropper.js + the image-upload factories for the shared crop-photo modal.
+    Render on pages that can open the cropper (an avatar field, a banner editor,
+    etc.) — this loads cropper.js (~40 KB) AND defines imageUploadHost /
+    cropPhotoModal / submitFormWithProgress inline, so both the library and the
+    behavior only load where an upload trigger exists rather than globally.
+
+    Pair with: the crop-photo + saving modal registrations in your modal-host
+    block (see the README / CHANGELOG), and x-data="imageUploadHost({...})". %>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.css">
+<script defer src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"></script>
+<%= render "studio/modals/image_upload" %>

data/app/views/studio/modals/_crop_photo.html.erb

@@ -0,0 +1,69 @@
+<%#
+  Crop Photo modal — content partial for the modal host. Register it in your
+  studio/modals/host block alongside the `saving` modal — a template x-if on
+  $store.modals.current().id === 'crop-photo' that renders this partial (see
+  the CHANGELOG Integration section). Opened via
+  Alpine.store('modals').open('crop-photo', { imageUrl? }).
+
+  The modal always hands the cropped Blob back to its opener via the
+  'crop-photo-confirmed' window event — the opener's host owns the upload.
+  How the image gets IN depends on the props:
+
+    * imageUrl passed — the opener already let the user pick a file; the
+      modal jumps straight to the cropper (e.g. an avatar field).
+
+    * no imageUrl — the modal IS the picker: a click/drag-drop empty state
+      lets the user choose a file inside the modal, then crops (e.g. a
+      banner editor's open()).
+
+  The cropPhotoModal() factory ships in studio/modals/_image_upload; cropper.js
+  loads via studio/_cropper_assets on the pages that can open this modal.
+
+  Single root: lives inside the host's <template x-if>, so only the outer
+  div is the top-level element here.
+%>
+<div x-data="cropPhotoModal()">
+  <h3 class="text-heading font-bold text-lg text-center mb-4">Crop Photo</h3>
+
+  <template x-if="error">
+    <p class="text-red-400 text-sm mb-3 text-center" x-text="error"></p>
+  </template>
+
+  <input type="file" x-ref="filePicker" @change="onFilePicked($event)" accept="image/*" class="hidden">
+
+  <%# Empty state: click / drag-drop landing zone. %>
+  <template x-if="!imageUrl">
+    <div @click="$refs.filePicker.click()"
+         @dragover.prevent="dragging = true"
+         @dragleave.prevent="dragging = false"
+         @drop.prevent="onDrop($event)"
+         :class="dragging ? 'border-primary bg-primary/10' : 'border-subtle hover:border-primary'"
+         class="cursor-pointer border-2 border-dashed rounded-lg flex flex-col items-center justify-center text-center p-8 mb-4 transition"
+         style="min-height: 240px;">
+      <svg class="w-12 h-12 text-muted mb-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M7 16a4 4 0 01-.88-7.9 5 5 0 019.9-1A5.5 5.5 0 0118 16h-1m-6-4l3-3m0 0l3 3m-3-3v12"/>
+      </svg>
+      <p class="text-sm font-medium text-body">Drop an image or click to upload</p>
+      <p class="text-xs text-muted mt-1">PNG or JPG</p>
+    </div>
+  </template>
+
+  <%# Loaded state: cropper canvas. %>
+  <template x-if="imageUrl">
+    <div class="w-full mb-4" style="max-height: 360px;">
+      <img x-ref="cropImage" :src="imageUrl" class="max-w-full" style="display: block;">
+    </div>
+  </template>
+
+  <button type="button" @click="confirm()"
+          :disabled="!imageUrl"
+          :class="!imageUrl ? 'opacity-60 cursor-not-allowed' : ''"
+          class="btn btn-primary btn-lg w-full"
+          x-text="imageUrl ? 'Crop &amp; Save' : 'Upload an Image to Continue'">
+  </button>
+
+  <button type="button" @click="cancel()"
+          class="block mx-auto mt-4 text-xs text-secondary hover:text-heading underline underline-offset-2">
+    Cancel
+  </button>
+</div>

data/app/views/studio/modals/_image_upload.html.erb

@@ -0,0 +1,232 @@
+<%#
+  Image-upload client behavior for the crop-photo + saving modals.
+
+  Ships three window factories inline (engine convention — see _head /
+  _flash) so they're defined before Alpine processes any x-data that
+  references them:
+
+    cropPhotoModal()          x-data for studio/modals/_crop_photo
+    submitFormWithProgress()  loading card + toast around a Turbo submit
+    imageUploadHost()         host for crop-then-immediate-save uploaders
+                              (x-data in the consumer's upload views)
+
+  Rendered once by the modal host. cropper.js itself loads via
+  studio/_cropper_assets on the pages that can open the cropper.
+%>
+<script>
+  // === window.cropPhotoModal — x-data for studio/modals/_crop_photo =========
+  //
+  // The modal hands the cropped Blob back to its opener via the
+  // 'crop-photo-confirmed' window event — the opener's host owns the upload.
+  // The image gets IN two ways:
+  //   * imageUrl prop — the opener already picked a file and passes the data
+  //     URL (avatar uploader / avatar_cropper); the modal jumps to the cropper.
+  //   * no imageUrl — the modal itself is the picker (click/drag-drop empty
+  //     state), then crops (e.g. a banner editor's open()).
+  function cropPhotoModal(opts) {
+    opts = opts || {};
+    return {
+      cropper: null,
+      imageUrl: null,
+      fromParent: false,
+      dragging: false,
+      error: null,
+      // Configurable crop output. Defaults = avatar (square 256px, transparent).
+      // Callers override per-use via the modal props, e.g.
+      //   Alpine.store('modals').open('crop-photo',
+      //     { imageUrl, aspectRatio: 3, maxWidth: 900, maxHeight: 300 })
+      aspectRatio: 1,
+      maxWidth: 256,
+      maxHeight: 256,
+      transparent: true,
+      autoCropArea: 0.9,
+      // dispatch: keep the modal open after confirm so the opener's host can run
+      // its own processing -> success flow (it replaces the modal). When false
+      // (fromParent, e.g. avatar_cropper) the modal closes itself after confirm.
+      dispatch: false,
+
+      init() {
+        var current = this.$store.modals.current();
+        var props = (current && current.props) || {};
+        if (props.aspectRatio) this.aspectRatio = props.aspectRatio;
+        if (props.maxWidth) this.maxWidth = props.maxWidth;
+        if (props.maxHeight) this.maxHeight = props.maxHeight;
+        if (typeof props.transparent === "boolean") this.transparent = props.transparent;
+        if (props.dispatch) this.dispatch = true;
+        if (props.autoCropArea) this.autoCropArea = props.autoCropArea;
+        if (props.imageUrl) {
+          this.fromParent = true;
+          this.imageUrl = props.imageUrl;
+          this.mountCropper();
+        }
+      },
+
+      destroy() {
+        if (this.cropper) { this.cropper.destroy(); this.cropper = null; }
+      },
+
+      mountCropper() {
+        var self = this;
+        this.$nextTick(function () {
+          if (typeof Cropper === "undefined") return;
+          if (self.cropper) { self.cropper.destroy(); self.cropper = null; }
+          self.cropper = new Cropper(self.$refs.cropImage, {
+            aspectRatio: self.aspectRatio, viewMode: 1, dragMode: "move",
+            autoCropArea: self.autoCropArea, cropBoxResizable: true,
+            cropBoxMovable: true, background: false, guides: true
+          });
+          // Cropping in progress — lock the modal (no click-outside / escape) so
+          // an accidental click doesn't discard the crop. Cancel still works.
+          var cur = self.$store.modals.current();
+          if (cur && cur.props) cur.props.dismissible = false;
+        });
+      },
+
+      readFile(file) {
+        if (!file) return;
+        if (!file.type || file.type.indexOf("image/") !== 0) {
+          this.error = "Please choose an image file.";
+          return;
+        }
+        var self = this;
+        var reader = new FileReader();
+        reader.onload = function (e) {
+          self.error = null;
+          self.imageUrl = e.target.result;
+          self.mountCropper();
+        };
+        reader.readAsDataURL(file);
+      },
+
+      onFilePicked(event) {
+        var file = event.target.files[0];
+        event.target.value = "";
+        this.readFile(file);
+      },
+
+      onDrop(event) {
+        this.dragging = false;
+        var file = event.dataTransfer && event.dataTransfer.files && event.dataTransfer.files[0];
+        this.readFile(file);
+      },
+
+      cancel() {
+        if (this.cropper) { this.cropper.destroy(); this.cropper = null; }
+        this.$store.modals.close();
+      },
+
+      confirm() {
+        if (!this.cropper) return;
+        var self = this;
+        // Cap WIDTH only. For a fixed-aspect crop the aspect already bounds the
+        // height (= width / aspectRatio); also passing maxHeight makes cropper.js
+        // downscale the whole SOURCE to fit maxHeight when the source is taller
+        // (a 1983x793 upload -> 500/793 ~= 0.63x), tanking fidelity. maxWidth
+        // alone keeps the crop at source resolution up to the cap.
+        var canvasOpts = { maxWidth: this.maxWidth, imageSmoothingQuality: "high" };
+        if (!this.transparent) canvasOpts.fillColor = "#ffffff";
+        var canvas = this.cropper.getCroppedCanvas(canvasOpts);
+        canvas.toBlob(function (blob) {
+          try {
+            window.dispatchEvent(new CustomEvent("crop-photo-confirmed", { detail: { blob: blob } }));
+          } catch (_) {}
+          if (self.cropper) { self.cropper.destroy(); self.cropper = null; }
+          // dispatch mode: the opener's host owns the post-confirm flow
+          // (processing modal -> success toast), so don't pop the stack here.
+          // fromParent (no dispatch): close the modal now.
+          if (!self.dispatch) self.$store.modals.close();
+        }, "image/png");
+      }
+    };
+  }
+  window.cropPhotoModal = cropPhotoModal;
+  if (typeof Alpine !== "undefined") {
+    Alpine.data("cropPhotoModal", cropPhotoModal);
+  } else {
+    document.addEventListener("alpine:init", function () { Alpine.data("cropPhotoModal", cropPhotoModal); });
+  }
+
+  // === window.submitFormWithProgress — loading card + toast for a Turbo submit
+  //
+  // Swaps in the 'saving' card while the form uploads, then closes it (held
+  // >= ~450ms so it doesn't flash) and toasts on completion. opts: { saving,
+  // success, successMessage, failure, failureMessage, dismissible (default
+  // false), toast (default true) }.
+  window.submitFormWithProgress = function (form, opts) {
+    opts = opts || {};
+    var store = window.Alpine && Alpine.store("modals");
+    var hold = (window.StudioModals && window.StudioModals.holdAtLeast)
+      ? window.StudioModals.holdAtLeast(450)
+      : { then: function (cb) { cb(); } };
+    if (store) {
+      store.open("saving", { dismissible: opts.dismissible === true, title: opts.saving || "Saving…" }, { replace: true });
+    }
+    var onEnd = function (e) {
+      form.removeEventListener("turbo:submit-end", onEnd);
+      var ok = e.detail && e.detail.success;
+      hold.then(function () {
+        if (store) store.close();
+        if (opts.toast !== false) {
+          window.dispatchEvent(new CustomEvent("toast", { detail: {
+            type: ok ? "notice" : "alert",
+            title: ok ? (opts.success || "Saved") : (opts.failure || "Couldn't save"),
+            message: ok ? (opts.successMessage || "") : (opts.failureMessage || "Please try again.")
+          } }));
+        }
+      });
+    };
+    form.addEventListener("turbo:submit-end", onEnd);
+    form.requestSubmit();
+  };
+
+  // === window.imageUploadHost — x-data host for crop-then-immediate-save ======
+  //
+  // Two entry points feed the SHARED crop-photo modal in dispatch mode:
+  //   open()           — the modal itself is the click/drag-drop target (banner)
+  //   onFileSelected() — a native file picker hands the image in (avatar)
+  // Both dispatch the cropped Blob via 'crop-photo-confirmed'; applyCrop() drops
+  // it into the host's own hidden form input and submits immediately with a
+  // loading card + toast (submitFormWithProgress). opts = crop config
+  // (aspectRatio, maxWidth, maxHeight, transparent, autoCropArea) + save copy
+  // (saving, success, successMessage, failure, dismissible, toast, filename).
+  window.imageUploadHost = function (opts) {
+    opts = opts || {};
+    function cropProps(extra) {
+      var p = {
+        aspectRatio: opts.aspectRatio || 1,
+        transparent: opts.transparent !== false,
+        dispatch: true
+      };
+      if (opts.maxWidth) p.maxWidth = opts.maxWidth;
+      if (opts.maxHeight) p.maxHeight = opts.maxHeight;
+      if (opts.autoCropArea) p.autoCropArea = opts.autoCropArea;
+      if (extra) { for (var k in extra) { p[k] = extra[k]; } }
+      return p;
+    }
+    return {
+      // Modal-as-picker: the crop modal itself is the file picker / drop target.
+      open() {
+        if (!window.Alpine || !Alpine.store("modals")) return;
+        Alpine.store("modals").open("crop-photo", cropProps());
+      },
+      // Native picker: read the chosen image, then hand it to the modal.
+      onFileSelected(event) {
+        var file = event.target.files[0];
+        if (!file) return;
+        var reader = new FileReader();
+        reader.onload = function (e) {
+          Alpine.store("modals").open("crop-photo", cropProps({ imageUrl: e.target.result }));
+        };
+        reader.readAsDataURL(file);
+        event.target.value = "";
+      },
+      applyCrop(blob) {
+        if (!blob) return;
+        var dt = new DataTransfer();
+        dt.items.add(new File([blob], opts.filename || "image.png", { type: "image/png" }));
+        this.$refs.fileInput.files = dt.files;
+        window.submitFormWithProgress(this.$refs.form, opts);
+      }
+    };
+  };
+</script>

data/app/views/studio/modals/_saving.html.erb

@@ -0,0 +1,7 @@
+<%# Generic "saving" loading card, opened by window.submitFormWithProgress with
+    a { title } prop while a Turbo form uploads. Register it in your modal-host
+    block alongside crop-photo. Single root for the host's <template x-if>. %>
+<div>
+  <%= render "studio/modals/blocks/processing_card",
+        title_key: "$store.modals.current()?.props?.title || 'Saving…'" %>
+</div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.4.11"
+  VERSION = "0.4.12"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.4.11
+  version: 0.4.12
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-24 00:00:00.000000000 Z
+date: 2026-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -146,7 +146,11 @@ files:
 - app/views/schema/index.html.erb
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
+- app/views/studio/_cropper_assets.html.erb
+- app/views/studio/modals/_crop_photo.html.erb
 - app/views/studio/modals/_host.html.erb
+- app/views/studio/modals/_image_upload.html.erb
+- app/views/studio/modals/_saving.html.erb
 - app/views/studio/modals/blocks/_error_card.html.erb
 - app/views/studio/modals/blocks/_processing_card.html.erb
 - app/views/studio/modals/blocks/_progress_countdown.html.erb