payload-plugin-aspect-preview 0.1.0

package/dist/styles.scss

@@ -0,0 +1,482 @@
+@import '~@payloadcms/ui/scss';
+
+// ─────────────────────────────────────────────
+// Aspect Ratio Preview Grid (right column)
+// ─────────────────────────────────────────────
+.focal-preview {
+  &__grid {
+    // True masonry via CSS columns — works in all modern browsers
+    // Items flow top-to-bottom in each column, tightly packed with no
+    // empty spaces regardless of individual card heights.
+    columns: 3;
+    column-gap: base(0.5);
+
+    @media (max-width: 1400px) {
+      columns: 2;
+    }
+
+    @media (max-width: 768px) {
+      columns: 1;
+    }
+  }
+
+  &__card {
+    // Prevent card from splitting across columns
+    break-inside: avoid;
+    margin-bottom: base(0.5);
+
+    background: var(--theme-elevation-0);
+    border: 1px solid var(--theme-elevation-100);
+    border-radius: var(--border-radius-s);
+    overflow: hidden;
+    transition:
+      transform 0.15s ease,
+      box-shadow 0.15s ease;
+
+    &:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 6px 16px rgba(0, 0, 0, 0.08);
+    }
+  }
+
+  &__card-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: base(0.25);
+    padding: base(0.375) base(0.5);
+    background: var(--theme-elevation-50);
+    border-bottom: 1px solid var(--theme-elevation-100);
+  }
+
+  &__card-name {
+    font-size: base(0.65);
+    font-weight: 600;
+    color: var(--theme-text);
+  }
+
+  &__card-ratio {
+    font-size: base(0.6);
+    color: var(--theme-elevation-500);
+    background: var(--theme-elevation-100);
+    padding: 1px 5px;
+    border-radius: var(--border-radius-s);
+    font-weight: 500;
+  }
+
+  &__card-frame {
+    position: relative;
+    width: 100%;
+    overflow: hidden;
+    background: var(--theme-elevation-100);
+    line-height: 0;
+  }
+
+  &__card-image {
+    display: block;
+    transition: opacity 0.2s ease;
+  }
+
+  &__card-overlay {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.06);
+    z-index: 1;
+  }
+
+  &__card-crosshair {
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+    z-index: 2;
+    width: 16px;
+    height: 16px;
+
+    &::before,
+    &::after {
+      content: '';
+      position: absolute;
+      background: rgba(255, 255, 255, 0.95);
+      box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.35);
+    }
+
+    &::before {
+      width: 100%;
+      height: 2px;
+      top: 50%;
+      left: 0;
+      transform: translateY(-50%);
+    }
+
+    &::after {
+      width: 2px;
+      height: 100%;
+      left: 50%;
+      top: 0;
+      transform: translateX(-50%);
+    }
+  }
+
+  &__card-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: base(0.25);
+    padding: base(0.25) base(0.5);
+    background: var(--theme-elevation-50);
+    border-top: 1px solid var(--theme-elevation-100);
+  }
+
+  &__card-usage {
+    font-size: base(0.55);
+    color: var(--theme-elevation-500);
+    line-height: 1.3;
+  }
+
+  &__card-source {
+    font-size: base(0.55);
+    font-weight: 600;
+    padding: 1px 4px;
+    border-radius: var(--border-radius-s);
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    flex-shrink: 0;
+
+    &--css {
+      color: #0f766e;
+      background: #ccfbf1;
+    }
+
+    &--crop {
+      color: #9a3412;
+      background: #ffedd5;
+    }
+  }
+}
+
+// ─────────────────────────────────────────────
+// Focal Point Editor (two-column)
+// ─────────────────────────────────────────────
+.focal-editor {
+  margin-top: base(1);
+  padding: base(1);
+  background: var(--theme-elevation-0);
+  border-radius: var(--border-radius-m);
+  border: 1px solid var(--theme-elevation-100);
+
+  // Two-column layout
+  &__layout {
+    display: flex;
+    gap: base(1.5);
+    align-items: flex-start;
+
+    @media (max-width: 900px) {
+      flex-direction: column;
+    }
+  }
+
+  &__left {
+    position: sticky;
+    top: 75px;
+    align-self: flex-start;
+    width: 50%;
+    flex-shrink: 0;
+    display: flex;
+    flex-direction: column;
+    gap: base(0.75);
+
+    @media (max-width: 900px) {
+      position: relative;
+      top: auto;
+      width: 100%;
+    }
+  }
+
+  &__right {
+    flex: 1;
+    min-width: 0;
+  }
+
+  // Toolbar: inputs (2 rows) on the left, button column on the right
+  &__toolbar {
+    display: flex;
+    align-items: stretch;
+    gap: base(2);
+    margin-bottom: base(0.5);
+    flex-wrap: wrap;
+  }
+
+  &__toolbar-inputs {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    gap: base(2);
+    flex-wrap: wrap;
+  }
+
+  &__toolbar-row {
+    display: flex;
+    align-items: center;
+    gap: base(1);
+    flex-wrap: wrap;
+  }
+
+  &__toolbar-col {
+    display: flex;
+    flex-direction: column;
+    gap: base(0.5);
+  }
+
+  &__row-label {
+    font-size: base(0.7);
+    font-weight: 600;
+    color: var(--theme-elevation-800);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    width: 52px;
+    flex-shrink: 0;
+    text-align: left;
+    align-self: flex-start;
+    padding-right: base(0.25);
+  }
+
+  &__toolbar-actions {
+    display: flex;
+    flex-direction: column;
+    gap: base(0.35);
+    align-items: stretch;
+    justify-content: space-between;
+    flex: 1 1 auto;
+  }
+
+  &__mode-toggle {
+    display: flex;
+    gap: 0;
+    border-radius: var(--border-radius-s);
+    overflow: hidden;
+    border: 1px solid var(--theme-elevation-150);
+  }
+
+  &__mode-btn {
+    padding: base(0.35) base(0.75);
+    border: none;
+    background: var(--theme-elevation-0);
+    color: var(--theme-text);
+    font-size: base(0.7);
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.15s ease;
+    border-right: 1px solid var(--theme-elevation-150);
+    flex: 1 1 100%;
+
+    &:last-child {
+      border-right: none;
+    }
+
+    &--active {
+      background: var(--theme-elevation-900);
+      color: var(--theme-elevation-0);
+    }
+
+    &:hover:not(&--active) {
+      background: var(--theme-elevation-100);
+    }
+  }
+
+  &__inputs {
+    display: flex;
+    align-items: center;
+    gap: base(0.5);
+  }
+
+  &__subgroup {
+    display: flex;
+    flex-direction: column;
+    gap: base(0.5);
+  }
+
+  &__subgroup-label {
+    font-size: base(0.6);
+    font-weight: 600;
+    color: var(--theme-elevation-500);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    line-height: 1;
+    width: 100%;
+    text-align: left;
+  }
+
+  &__subgroup-inputs {
+    display: flex;
+    align-items: center;
+    gap: base(0.4);
+  }
+
+  &__input-group {
+    display: flex;
+    align-items: center;
+    gap: base(0.25);
+
+    label {
+      font-size: base(0.7);
+      color: var(--theme-elevation-600);
+      font-weight: 600;
+      line-height: 1;
+      min-width: 10px;
+      text-align: center;
+    }
+
+    input {
+      width: 48px;
+      padding: base(0.25) base(0.35);
+      border: 1px solid var(--theme-elevation-150);
+      border-radius: var(--border-radius-s);
+      background: var(--theme-elevation-0);
+      color: var(--theme-text);
+      font-size: base(0.7);
+      text-align: center;
+      font-weight: 500;
+
+      &:focus {
+        outline: none;
+        border-color: var(--theme-elevation-400);
+        box-shadow: 0 0 0 2px var(--theme-elevation-100);
+      }
+
+      &:disabled {
+        background: var(--theme-elevation-50);
+        color: var(--theme-elevation-400);
+        cursor: not-allowed;
+      }
+    }
+
+    span {
+      font-size: base(0.65);
+      color: var(--theme-elevation-500);
+    }
+  }
+
+  &__btn {
+    padding: base(0.35) base(0.625);
+    border-radius: var(--border-radius-s);
+    border: 1px solid var(--theme-elevation-150);
+    background: var(--theme-elevation-0);
+    color: var(--theme-text);
+    font-size: base(0.7);
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.15s ease;
+
+    &:hover {
+      background: var(--theme-elevation-100);
+      border-color: var(--theme-elevation-200);
+    }
+  }
+
+  // Image
+  &__image-wrapper {
+    width: 100%;
+    border-radius: var(--border-radius-m);
+    overflow: hidden;
+    border: 1px solid var(--theme-elevation-100);
+    background: var(--theme-elevation-50);
+    display: flex;
+    justify-content: center;
+    align-items: center;
+  }
+
+  &__react-crop {
+    width: 100%;
+    display: block;
+    line-height: 0;
+
+    &.is-focal-mode {
+      cursor: crosshair;
+    }
+
+    &.is-crop-mode {
+      cursor: crosshair;
+    }
+
+    img {
+      display: block;
+      width: 100%;
+      height: auto;
+      object-fit: contain;
+    }
+  }
+
+  &__crop-overlay {
+    position: absolute;
+    z-index: 5;
+    pointer-events: none;
+    border: 2px dashed rgba(255, 255, 255, 0.9);
+    box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.45);
+    transition: all 0.15s ease;
+  }
+
+  &__focal-overlay {
+    position: absolute;
+    inset: 0;
+    z-index: 10;
+    pointer-events: none;
+
+    &.is-active {
+      pointer-events: auto;
+      cursor: crosshair;
+    }
+  }
+
+  &__crosshair {
+    position: absolute;
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+    z-index: 2;
+    width: 24px;
+    height: 24px;
+
+    &-h,
+    &-v {
+      position: absolute;
+      background: rgba(255, 255, 255, 0.95);
+      box-shadow: 0 0 0 1.5px rgba(0, 0, 0, 0.4);
+    }
+
+    &-h {
+      width: 24px;
+      height: 2px;
+      left: 50%;
+      top: 50%;
+      transform: translate(-50%, -50%);
+    }
+
+    &-v {
+      width: 2px;
+      height: 24px;
+      left: 50%;
+      top: 50%;
+      transform: translate(-50%, -50%);
+    }
+  }
+
+  &__empty {
+    padding: base(2);
+    text-align: center;
+    color: var(--theme-elevation-600);
+    font-size: base(0.75);
+    border: 2px dashed var(--theme-elevation-100);
+    border-radius: var(--border-radius-m);
+    background: var(--theme-elevation-50);
+  }
+}
+
+// React Crop overrides
+.ReactCrop {
+  &__crop-selection {
+    border: 2px dashed rgba(255, 255, 255, 0.9);
+    box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.5);
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+export interface AspectRatioConfig {
+    /** Display label, e.g. "Social Share". */
+    name: string;
+    /** Display token, e.g. "16:9". */
+    ratio: string;
+    /** Ratio numerator (or absolute px width for exact targets). */
+    width: number;
+    /** Ratio denominator (or absolute px height for exact targets). */
+    height: number;
+    /** How the frontend renders this ratio; drives a display badge only. Defaults to 'css'. */
+    source?: 'css' | 'crop';
+    /** Optional description shown in the preview card footer. */
+    usage?: string;
+    /** Optional free-form grouping label. */
+    category?: string;
+}
+export interface AspectPreviewPluginOptions {
+    /** Upload collections (by slug) to enhance with the inline editor. */
+    collections: string[];
+    /** Aspect ratios shown in the live preview grid. Defaults to DEFAULT_ASPECT_RATIOS. */
+    aspectRatios?: AspectRatioConfig[];
+    /** Disable the plugin while keeping the schema field for DB consistency. */
+    disabled?: boolean;
+}
+export interface CropConfig {
+    unit: 'px' | '%';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FocalPointState {
+    x: number;
+    y: number;
+}
+export interface UploadEditsState {
+    crop?: CropConfig;
+    focalPoint?: FocalPointState;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["export interface AspectRatioConfig {\n  /** Display label, e.g. \"Social Share\". */\n  name: string\n  /** Display token, e.g. \"16:9\". */\n  ratio: string\n  /** Ratio numerator (or absolute px width for exact targets). */\n  width: number\n  /** Ratio denominator (or absolute px height for exact targets). */\n  height: number\n  /** How the frontend renders this ratio; drives a display badge only. Defaults to 'css'. */\n  source?: 'css' | 'crop'\n  /** Optional description shown in the preview card footer. */\n  usage?: string\n  /** Optional free-form grouping label. */\n  category?: string\n}\n\nexport interface AspectPreviewPluginOptions {\n  /** Upload collections (by slug) to enhance with the inline editor. */\n  collections: string[]\n  /** Aspect ratios shown in the live preview grid. Defaults to DEFAULT_ASPECT_RATIOS. */\n  aspectRatios?: AspectRatioConfig[]\n  /** Disable the plugin while keeping the schema field for DB consistency. */\n  disabled?: boolean\n}\n\nexport interface CropConfig {\n  unit: 'px' | '%'\n  x: number\n  y: number\n  width: number\n  height: number\n}\n\nexport interface FocalPointState {\n  x: number\n  y: number\n}\n\nexport interface UploadEditsState {\n  crop?: CropConfig\n  focalPoint?: FocalPointState\n}\n"],"names":[],"mappings":"AAuCA,WAGC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "payload-plugin-aspect-preview",
+  "version": "0.1.0",
+  "description": "Single-screen crop, focal point, and live multi-aspect-ratio preview editor for Payload upload collections.",
+  "keywords": ["payload", "payload-plugin", "payloadcms", "focal-point", "crop", "aspect-ratio", "media"],
+  "license": "MIT",
+  "author": "Sebastian Kolbusz <s.kolbusz@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s-kolbusz/payload-plugin-aspect-preview.git"
+  },
+  "homepage": "https://github.com/s-kolbusz/payload-plugin-aspect-preview#readme",
+  "bugs": "https://github.com/s-kolbusz/payload-plugin-aspect-preview/issues",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/exports/client.js",
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./types": {
+      "import": "./dist/exports/types.js",
+      "types": "./dist/exports/types.d.ts",
+      "default": "./dist/exports/types.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "pnpm clean && pnpm copyfiles && pnpm build:types && pnpm build:swc",
+    "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths --ignore \"**/*.spec.ts\"",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "clean": "rimraf dist *.tsbuildinfo",
+    "copyfiles": "copyfiles -u 1 \"src/**/*.{scss,css}\" dist/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "next dev dev --turbo",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "react-image-crop": "^11.1.2"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": "^3.85.0",
+    "payload": "^3.85.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@payloadcms/db-mongodb": "^3.85.0",
+    "@payloadcms/next": "^3.85.0",
+    "@payloadcms/richtext-lexical": "^3.85.0",
+    "@payloadcms/ui": "^3.85.0",
+    "@swc/cli": "^0.5.0",
+    "@swc/core": "^1.10.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^7.0.3",
+    "next": "^16.0.0",
+    "payload": "^3.85.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rimraf": "^6.0.0",
+    "sharp": "0.34.2",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}