@plone-collective/volto-image-editor 1.0.0-alpha.1 → 1.0.0-alpha.2

package/.changelog.draft

@@ -1,19 +1,8 @@
-## 1.0.0-alpha.1 (2025-10-20)
+## 1.0.0-alpha.2 (2025-10-29)
 
 ### Feature
 
-- Adds support editing the brightness of an image. @Humanaice 
-- Adds support editing the contrast of an image. @Humanaice 
-- Adds support editing the hue of an image. @Humanaice 
-- Adds support editing the saturation of an image. @Humanaice 
-- Adds support for image cropping. @Humanaice 
-- Adds support for image flipping. @Humanaice 
-- Adds support for rotating the image by 90 degrees clockwise and counter-clockwise. @Humanaice 
-- Implement a widget to edit Images in Volto. @Humanaice 
-
-### Internal
-
-- Adds basic instructions to use GitHub Copilot features. @ericof 
-- Implement GitHub Action's workflows. @ericof 
+- Update README to include a small demo of @plone-collective/volto-image-editor. @humanaice [#4](https://github.com/collective/volto-image-editor/issue/4)
+- Add Storybook stories for all components. @humanaice [#5](https://github.com/collective/volto-image-editor/issue/5)
 
 

package/CHANGELOG.md

@@ -8,6 +8,13 @@
 
 <!-- towncrier release notes start -->
 
+## 1.0.0-alpha.2 (2025-10-29)
+
+### Feature
+
+- Update README to include a small demo of @plone-collective/volto-image-editor. @humanaice [#4](https://github.com/collective/volto-image-editor/issue/4)
+- Add Storybook stories for all components. @humanaice [#5](https://github.com/collective/volto-image-editor/issue/5)
+
 ## 1.0.0-alpha.1 (2025-10-20)
 
 ### Feature

package/README.md

@@ -3,11 +3,13 @@
 An image editor, based on [React Advanced Image Cropper](https://www.npmjs.com/package/react-advanced-cropper), to be used with Plone and Volto.
 
 [![npm](https://img.shields.io/npm/v/@plone-collective/volto-image-editor)](https://www.npmjs.com/package/@plone-collective/volto-image-editor)
-[![](https://img.shields.io/badge/-Storybook-ff4785?logo=Storybook&logoColor=white&style=flat-square)](https://simplesconsultoria.github.io/volto-image-editor/)
+[![](https://img.shields.io/badge/-Storybook-ff4785?logo=Storybook&logoColor=white&style=flat-square)](https://collective.github.io/volto-image-editor/)
 [![Code analysis checks](https://github.com/collective/volto-image-editor/actions/workflows/main.yml/badge.svg)](https://github.com/collective/volto-image-editor/actions/workflows/main.yml)
 
 ## ✨ Features
 
+![Demo](https://raw.githubusercontent.com/collective/volto-image-editor/refs/heads/main/docs/docs/_static/volto-image-editor.gif)
+
 
 This add-on modifies Volto's File widget, providing an image editor with the following actions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plone-collective/volto-image-editor",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "An image editor to be used with Plone and Volto.",
   "main": "src/index.ts",
   "license": "MIT",
@@ -10,12 +10,22 @@
     "plone",
     "react"
   ],
-  "author": "Simples Consultoria",
+  "author": {
+    "name": "Simples Consultoria",
+    "url": "https://simplesconsultoria.com.br/"
+  },
   "homepage": "https://github.com/collective/volto-image-editor#readme",
   "repository": {
     "type": "git",
     "url": "git@github.com:collective/volto-image-editor"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/plone"
+  },
+  "bugs": {
+    "url": "https://github.com/collective/volto-image-edito/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -32,8 +42,8 @@
     "react": "18.2.0",
     "react-aria-components": "*",
     "react-dom": "18.2.0",
-    "@plone/types": "2.0.0-alpha.5",
-    "@plone/registry": "3.0.0-alpha.5"
+    "@plone/registry": "3.0.0-alpha.5",
+    "@plone/types": "2.0.0-alpha.5"
   },
   "devDependencies": {
     "@types/node": "^20.2.5",

package/src/components/ImageEditor/Editor/ImageEditor.mdx

@@ -0,0 +1,217 @@
+import { Meta, Canvas, Story, Controls, ArgTypes } from '@storybook/blocks';
+import * as ImageEditorStories from './ImageEditor.stories';
+
+<Meta of={ImageEditorStories} />
+
+# ImageEditor
+
+The `ImageEditor` is the main component that provides a complete interface for image editing, including crop, rotation, color adjustments and advanced settings.
+
+## Overview
+
+This component combines several features:
+
+- **Interactive cropper** with rectangular and circular stencils
+- **Transformations**: rotation (90°), horizontal/vertical flip
+- **Color adjustments**: brightness, contrast, saturation and hue
+- **Advanced settings**: aspect ratio, restrictions, dimensions
+
+---
+
+## Examples
+
+### Landscape (Horizontal)
+
+Most common format for landscape photos, screenshots and banners.
+
+<Canvas of={ImageEditorStories.Landscape} />
+
+### Portrait (Vertical)
+
+Ideal for profile photos, stories and mobile content.
+
+<Canvas of={ImageEditorStories.Portrait} />
+
+### Compact (Small)
+
+Demonstrates the editor in reduced dimensions, useful for modals or sidebars.
+
+<Canvas of={ImageEditorStories.Compact} />
+
+---
+
+## How to Use
+
+### Basic
+
+```tsx
+import ImageEditor from '@plone-collective/volto-image-editor/components/ImageEditor/ImageEditor';
+
+function MyEditor() {
+  const handleSave = (dataUrl: string) => {
+    // dataUrl is the edited image in base64 format
+    console.log('Image saved:', dataUrl);
+  };
+
+  const handleCancel = () => {
+    console.log('Edit cancelled');
+  };
+
+  return (
+    <ImageEditor
+      src="https://example.com/image.jpg"
+      onImageSave={handleSave}
+      onCancel={handleCancel}
+    />
+  );
+}
+```
+
+### With Data URL
+
+```tsx
+const imageDataUrl = 'data:image/jpeg;base64,/9j/4AAQ...';
+
+<ImageEditor
+  src={imageDataUrl}
+  onImageSave={(newDataUrl) => {
+    // Save the edited image
+    uploadImage(newDataUrl);
+  }}
+  onCancel={() => closeEditor()}
+/>;
+```
+
+---
+
+## Features
+
+### Edit Modes
+
+The editor has different modes accessible via the navigation bar:
+
+- **Crop**: Allows cropping the image with the configured stencil
+- **Brightness**: Adjusts image brightness (-100% to +100%)
+- **Contrast**: Adjusts contrast (-100% to +100%)
+- **Saturation**: Adjusts color saturation (-100% to +100%)
+- **Hue**: Adjusts hue/tone (360° rotation)
+
+### Transformations
+
+Actions available regardless of mode:
+
+- **Rotate Left**: Rotates 90° counterclockwise
+- **Rotate Right**: Rotates 90° clockwise
+- **Flip Horizontal**: Mirrors horizontally
+- **Flip Vertical**: Mirrors vertically
+- **Reset Rotation**: Undoes all transformations (appears after applying rotations/flips)
+
+### Settings
+
+Accessible via gear icon:
+
+- **Aspect Ratio**: Free, 1:1, 3:4, 4:3, 16:9, 9:16, 2:1, 21:9, 1:2
+- **Image Restriction**: Fit, Fill, Stencil, Free
+- **Stencil Type**: Rectangle, Circle
+- **Minimum dimensions**: Min Width/Height for crop
+- **Maximum dimensions**: Max Width/Height of crop (optional)
+- **Stencil Grid**: Shows grid in stencil to assist composition
+
+---
+
+## Keyboard Navigation
+
+### In Cropper
+
+- **Arrow keys**: Move stencil
+- **Shift + Arrow keys**: Move faster
+- **Alt + Arrow keys**: Resize stencil
+
+### In Sliders (Adjustments)
+
+- **Arrow Left/Down**: Decrease value
+- **Arrow Right/Up**: Increase value
+- **Page Down**: Decrease 10 steps
+- **Page Up**: Increase 10 steps
+- **Home**: Minimum value
+- **End**: Maximum value
+- **Space/Enter**: Reset to zero
+
+---
+
+## Performance
+
+### Implemented Optimizations
+
+1. **Canvas Rendering**: Filters applied via Canvas API (hardware-accelerated)
+2. **Debounced Updates**: Preview updates efficiently during adjustments
+3. **Lazy Loading**: Configuration components loaded on demand
+
+### Recommendations
+
+- **Image size**: Ideal between 800x600 and 2000x1500 pixels
+- **Format**: JPEG or PNG (WebP supported in modern browsers)
+- **File size**: Up to 5MB for better performance
+
+---
+
+## Accessibility
+
+- All buttons have descriptive labels
+- Complete keyboard navigation
+- ARIA attributes on sliders (role="slider", aria-valuemin, etc)
+- Visible focus indicators
+- Adequate contrast in all states
+
+---
+
+## Troubleshooting
+
+### Image won't load
+
+- Check CORS if image is from external domain
+- Use `crossOrigin="anonymous"` if necessary
+- Confirm that URL/dataURL is valid
+
+### Crop too small
+
+- Adjust `minWidth` and `minHeight` in settings
+- Check `imageRestriction` (may be limiting)
+
+### Slow performance
+
+- Reduce image size before loading
+- Avoid too frequent adjustments (debounce)
+- Use JPEG format for photos (smaller than PNG)
+
+---
+
+## Props
+
+### src
+
+- **Type**: `string`
+- **Required**: ✅
+- **Description**: URL or data URL of the image to be edited
+
+### onImageSave
+
+- **Type**: `(dataUrl: string) => void`
+- **Required**: ✅
+- **Description**: Callback called on save, receives the edited image as data URL
+
+### onCancel
+
+- **Type**: `() => void`
+- **Required**: ✅
+- **Description**: Callback called when editing is cancelled
+
+---
+
+## Related Components
+
+- **ImageEditorWrapper**: Wrapper with modal for use in widgets
+- **Navigation**: Editor toolbar
+- **SettingsModal**: Advanced settings panel
+- **Slider**: Control for color adjustments
+- **AdjustableImage**: Image renderer with filters

package/src/components/ImageEditor/{ImageEditor.scss → Editor/ImageEditor.scss}

@@ -1,5 +1,5 @@
 @import '~react-advanced-cropper/dist/style.css';
-@import '../../theme/constants';
+@import '../../../theme/constants';
 
 .image-editor {
   width: 100%;

package/src/components/ImageEditor/Editor/ImageEditor.stories.tsx

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import ImageEditor from './ImageEditor';
+import { DemoContainer, createDemoImageDataURL } from '../../../stories/utils';
+
+// Generate demo images once to avoid recreation
+const demoImageSrc = createDemoImageDataURL(960, 640);
+const portraitImageSrc = createDemoImageDataURL(640, 960);
+
+const meta: Meta = {
+  title: 'ImageEditor/ImageEditor',
+  component: ImageEditor as any,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Full image editor with cropper, adjustments, and settings. Provides complete editing capabilities including crop, rotate, flip, and color adjustments.',
+      },
+    },
+  },
+  argTypes: {
+    src: { control: false },
+    onImageSave: { control: false },
+    onCancel: { control: false },
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const Landscape: Story = {
+  render: () => {
+    function LandscapeStory() {
+      const handleSave = (_dataUrl: string) => {
+        /* no-op in story */
+      };
+
+      return (
+        <DemoContainer width={960} height={640}>
+          <ImageEditor
+            src={demoImageSrc}
+            onImageSave={handleSave}
+            onCancel={() => {
+              /* no-op */
+            }}
+          />
+        </DemoContainer>
+      );
+    }
+    return <LandscapeStory />;
+  },
+};
+
+export const Portrait: Story = {
+  render: () => {
+    function PortraitStory() {
+      const handleSave = (_dataUrl: string) => {
+        /* no-op in story */
+      };
+
+      return (
+        <DemoContainer width={640} height={960}>
+          <ImageEditor
+            src={portraitImageSrc}
+            onImageSave={handleSave}
+            onCancel={() => {
+              /* no-op */
+            }}
+          />
+        </DemoContainer>
+      );
+    }
+    return <PortraitStory />;
+  },
+};
+
+export const Compact: Story = {
+  render: () => {
+    function CompactStory() {
+      const compactImageSrc = createDemoImageDataURL(480, 320);
+
+      const handleSave = (_dataUrl: string) => {
+        /* no-op in story */
+      };
+
+      return (
+        <DemoContainer width={640} height={480}>
+          <ImageEditor
+            src={compactImageSrc}
+            onImageSave={handleSave}
+            onCancel={() => {
+              /* no-op */
+            }}
+          />
+        </DemoContainer>
+      );
+    }
+    return <CompactStory />;
+  },
+};

package/src/components/ImageEditor/{ImageEditor.tsx → Editor/ImageEditor.tsx}

@@ -8,13 +8,13 @@ import {
   ImageRestriction,
 } from 'react-advanced-cropper';
 import type { CropperRef, CropperPreviewRef } from 'react-advanced-cropper';
-import { AdjustablePreviewBackground } from './components/AdjustablePreviewBackground';
-import { Navigation } from './components/Navigation';
-import { Slider } from './components/Slider';
-import { AdjustableCropperBackground } from './components/AdjustableCropperBackground';
-import { Button } from './components/Button';
-import { SettingsModal } from './components/SettingsModal';
-import type { ImageSettings } from './types/ImageSettings';
+import { AdjustablePreviewBackground } from '../components/AdjustablePreviewBackground';
+import { Navigation } from '../components/Navigation/Navigation';
+import { Slider } from '../components/Slider/Slider';
+import { AdjustableCropperBackground } from '../components/AdjustableCropperBackground';
+import { Button } from '../components/Button/Button';
+import { SettingsModal } from '../components/SettingsModal/SettingsModal';
+import type { ImageSettings } from '../types/ImageSettings';
 import { ResetIcon } from '@plone-collective/volto-image-editor/icons/ResetIcon';
 import './ImageEditor.scss';