@we-are-singular/svelte-chop-chop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 We Are Singular
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# svelte-chop-chop
+
+> Headless-first image cropping and editing SDK for Svelte 5.  
+> Zero dependencies beyond Svelte.
+
+[![npm](https://img.shields.io/npm/v/@we-are-singular/svelte-chop-chop)](https://www.npmjs.com/package/@we-are-singular/svelte-chop-chop)
+[![license](https://img.shields.io/github/license/we-are-singular/svelte-chop-chop)](LICENSE)
+
+**[Documentation & Demo →](https://svelte-chop-chop.pages.dev)**
+
+---
+
+## Features
+
+- **`<Cropper>`** — Lightweight crop component with handles, grid overlays, and transforms
+- **`<ImageEditor>`** — Full-featured editor with plugin-driven toolbar
+- **Headless composables** — `createCropper` and `createImageEditor` for fully custom UI
+- **Plugin system** — filters, finetune, frame, watermark, resize (all opt-in)
+- **Presets** — `profilePicture`, `coverPhoto`, `productImage`
+- **Three themes** — default, dark, minimal (CSS custom properties)
+- **Zero runtime dependencies** — peer dep: `svelte ^5.0.0` only
+
+---
+
+## Install
+
+```bash
+npm install @we-are-singular/svelte-chop-chop
+```
+
+---
+
+## Quick Start
+
+### Cropper
+
+```svelte
+<script lang="ts">
+  import { Cropper } from '@we-are-singular/svelte-chop-chop';
+  import '@we-are-singular/svelte-chop-chop/themes/default';
+</script>
+
+<Cropper src="/photo.jpg" aspectRatio={16 / 9} style="height: 400px;" />
+```
+
+### Image Editor
+
+```svelte
+<script lang="ts">
+  import { ImageEditor } from '@we-are-singular/svelte-chop-chop';
+  import { pluginFilters } from '@we-are-singular/svelte-chop-chop/plugins/filters';
+  import { pluginFinetune } from '@we-are-singular/svelte-chop-chop/plugins/finetune';
+  import { pluginFrame } from '@we-are-singular/svelte-chop-chop/plugins/frame';
+  import { pluginWatermark } from '@we-are-singular/svelte-chop-chop/plugins/watermark';
+  import { pluginResize } from '@we-are-singular/svelte-chop-chop/plugins/resize';
+  import type { ExportResult } from '@we-are-singular/svelte-chop-chop';
+  import '@we-are-singular/svelte-chop-chop/themes/default';
+
+  function handleExport(result: ExportResult) {
+    const url = URL.createObjectURL(result.blob!);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'edited.jpg';
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+</script>
+
+<ImageEditor
+  src="/photo.jpg"
+  plugins={[pluginFilters(), pluginFinetune(), pluginFrame(), pluginWatermark(), pluginResize()]}
+  onexport={handleExport}
+  style="height: 500px;"
+/>
+```
+
+---
+
+## Cropper Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `ImageSource` | — | URL, data URL, `File`, `Blob`, or `HTMLImageElement` |
+| `aspectRatio` | `number \| { min?: number; max?: number } \| null` | `null` | Aspect ratio constraint |
+| `sizeConstraints` | `SizeConstraints` | — | Min/max width/height in pixels |
+| `grid` | `"none" \| "rule-of-thirds" \| "grid" \| "golden-ratio"` | `"rule-of-thirds"` | Grid overlay |
+| `transitions` | `boolean` | `true` | CSS transitions |
+| `stencil` | `Component` | `CropStencil` | Custom stencil component |
+| `readOnly` | `boolean` | `false` | Disable interaction |
+| `class` / `style` | `string` | `''` | Root element styling |
+
+**Bindable:** `coordinates` (`CropCoordinates`), `transforms` (`TransformState`)  
+**Events:** `onchange`, `onready`, `onerror`
+
+---
+
+## Headless Usage
+
+```typescript
+import { createCropper } from '@we-are-singular/svelte-chop-chop/headless';
+import { createImageEditor } from '@we-are-singular/svelte-chop-chop';
+
+// Lightweight cropper
+const cropper = createCropper({ aspectRatio: 16 / 9 });
+await cropper.loadImage('/photo.jpg');
+const result = await cropper.export({ format: 'image/webp', quality: 0.9 });
+
+// Full editor
+const editor = createImageEditor({ plugins: [pluginFilters()] });
+await editor.loadImage('/photo.jpg');
+editor.applyFilter('clarendon');
+editor.rotate(90);
+const result = await editor.export({ format: 'image/webp', quality: 0.9 });
+// result.blob, result.dataURL, result.canvas, result.coordinates
+```
+
+---
+
+## Plugins
+
+| Import | Description |
+|--------|-------------|
+| `@we-are-singular/svelte-chop-chop/plugins/filters` | 16 Instagram-style color filter presets |
+| `@we-are-singular/svelte-chop-chop/plugins/finetune` | Brightness, contrast, saturation, exposure, etc. |
+| `@we-are-singular/svelte-chop-chop/plugins/frame` | Decorative frame at export (solid, line, hook) |
+| `@we-are-singular/svelte-chop-chop/plugins/watermark` | Text watermark at export |
+| `@we-are-singular/svelte-chop-chop/plugins/resize` | Output width/height controls |
+
+### Custom Plugin
+
+```typescript
+import type { ChopPlugin } from '@we-are-singular/svelte-chop-chop';
+
+const myPlugin: ChopPlugin = {
+  name: 'my-plugin',
+  setup(ctx) {
+    ctx.registerAction({
+      id: 'my-action',
+      label: 'My Action',
+      group: 'tabs',
+      execute: () => ctx.showPanel('my-panel'),
+    });
+
+    ctx.registerPostProcessor(async (drawCtx, canvas) => {
+      // draw on canvas at export time
+    });
+
+    return () => { /* cleanup */ };
+  },
+};
+```
+
+---
+
+## Presets
+
+```typescript
+import { profilePicture, coverPhoto, productImage } from '@we-are-singular/svelte-chop-chop/presets';
+
+// Spread into component props
+<Cropper src="/photo.jpg" {...profilePicture} />
+```
+
+| Preset | Aspect | Max Size | Format |
+|--------|--------|----------|--------|
+| `profilePicture` | 1:1 | 512px | JPEG |
+| `coverPhoto` | 16:9 | min 1200px wide | JPEG |
+| `productImage` | 1:1 | — | PNG |
+
+---
+
+## Theming
+
+```css
+@import '@we-are-singular/svelte-chop-chop/themes/default'; /* or dark, minimal */
+```
+
+Override any CSS custom property:
+
+```css
+:root {
+  --chop-bg: #1a1a2e;
+  --chop-stencil-border: #e94560;
+  --chop-toolbar-active: #e94560;
+}
+```
+
+**Available variables:** `--chop-bg`, `--chop-canvas-bg`, `--chop-color`, `--chop-border-radius`, `--chop-stencil-border`, `--chop-stencil-border-active`, `--chop-grid-color`, `--chop-overlay`, `--chop-toolbar-bg`, `--chop-toolbar-color`, `--chop-toolbar-active`, `--chop-transition-duration`, `--chop-transition-easing`
+
+---
+
+## Package Exports
+
+| Path | Description |
+|------|-------------|
+| `@we-are-singular/svelte-chop-chop` | Components, composables, types |
+| `@we-are-singular/svelte-chop-chop/headless` | `createCropper` composable |
+| `@we-are-singular/svelte-chop-chop/plugins` | All plugin factories |
+| `@we-are-singular/svelte-chop-chop/presets` | Preset bundles |
+| `@we-are-singular/svelte-chop-chop/themes/default` | Default CSS theme |
+| `@we-are-singular/svelte-chop-chop/themes/dark` | Dark CSS theme |
+| `@we-are-singular/svelte-chop-chop/themes/minimal` | Minimal CSS theme |
+
+---
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `R` / `Shift+R` | Rotate 90° CW / CCW |
+| `H` / `V` | Flip horizontal / vertical |
+| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / Redo |
+| `+` / `-` | Zoom in / out |
+| `0` | Reset crop to image bounds |
+| `Escape` | Reset all transforms |
+| `Ctrl+F` | Toggle filters panel |
+| Arrow keys | Move crop 1px (10px with Shift) |
+
+---
+
+## License
+
+MIT © [We Are Singular](https://github.com/we-are-singular)

package/dist/components/CircleStencil.svelte

@@ -0,0 +1,126 @@
+<!--
+  svelte-chop-chop — Circular crop stencil
+  Same contract as CropStencil, but with circular mask.
+-->
+<script lang="ts">
+  import type { HandlePosition, Point, StencilProps } from '../core/types.js';
+  import { createDragHandler } from '../core/interactions.js';
+  import DragHandle from './DragHandle.svelte';
+
+  let {
+    rect,
+    aspectRatio = 1,
+    active,
+    imageBounds,
+    grid,
+    transitions,
+    onmove,
+    onresize,
+    onresizestart,
+    onresizeend,
+  }: StencilProps & {
+    onmove: (delta: Point) => void;
+    onresize: (handle: HandlePosition, delta: Point) => void;
+    onresizestart?: () => void;
+    onresizeend?: () => void;
+  } = $props();
+
+  const drag = createDragHandler({
+    onMove: (delta) => onmove(delta),
+  });
+
+  // The circle is inscribed in a 1:1 square bounding rect.
+  // cx/cy are used for the circle border positioning only.
+  const size = $derived(Math.min(rect.width, rect.height));
+  const cx   = $derived(rect.width / 2);
+  const cy   = $derived(rect.height / 2);
+</script>
+
+<div
+  class="chop-stencil chop-stencil-circle"
+  class:chop-stencil-active={active}
+  style:left="{rect.x}px"
+  style:top="{rect.y}px"
+  style:width="{rect.width}px"
+  style:height="{rect.height}px"
+  role="group"
+  aria-label="Circular crop area"
+  onpointerdown={drag.onpointerdown}
+  onpointermove={drag.onpointermove}
+  onpointerup={drag.onpointerup}
+>
+  <svg class="chop-circle-overlay" aria-hidden="true">
+    <defs>
+      <mask id="chop-circle-mask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white" />
+        <circle
+          cx="{cx}"
+          cy="{cy}"
+          r="{size / 2}"
+          fill="black"
+        />
+      </mask>
+    </defs>
+    <rect
+      x="0"
+      y="0"
+      width="100%"
+      height="100%"
+      fill="var(--chop-overlay, rgba(0, 0, 0, 0.55))"
+      mask="url(#chop-circle-mask)"
+    />
+  </svg>
+
+  <div
+    class="chop-circle-border"
+    style:left="{cx}px"
+    style:top="{cy}px"
+    style:width="{size}px"
+    style:height="{size}px"
+    style:margin-left="-{size / 2}px"
+    style:margin-top="-{size / 2}px"
+  ></div>
+
+  <!-- Handles at the 4 bounding-box corners — correct for a 1:1 square crop with circular mask -->
+  <DragHandle position="nw" {onresize} {onresizestart} {onresizeend} size={16} />
+  <DragHandle position="ne" {onresize} {onresizestart} {onresizeend} size={16} />
+  <DragHandle position="sw" {onresize} {onresizestart} {onresizeend} size={16} />
+  <DragHandle position="se" {onresize} {onresizestart} {onresizeend} size={16} />
+</div>
+
+<style>
+  .chop-stencil-circle {
+    position: absolute;
+    border: none;
+    box-sizing: border-box;
+    z-index: 5;
+    touch-action: none;
+  }
+
+  .chop-circle-overlay {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+  }
+
+  .chop-circle-border {
+    position: absolute;
+    border: 2px solid var(--chop-stencil-border, rgba(255, 255, 255, 0.8));
+    border-radius: 50%;
+    box-sizing: border-box;
+    pointer-events: none;
+  }
+
+  .chop-stencil-active .chop-circle-border {
+    border-color: var(--chop-stencil-border-active, #fff);
+  }
+
+  /* Give circle handles a subtle dark outline so they're visible on light images */
+  :global(.chop-stencil-circle .chop-handle) {
+    border: 2px solid rgba(0, 0, 0, 0.35);
+    box-sizing: border-box;
+  }
+</style>

package/dist/components/CircleStencil.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { HandlePosition, Point, StencilProps } from '../core/types.js';
+type $$ComponentProps = StencilProps & {
+    onmove: (delta: Point) => void;
+    onresize: (handle: HandlePosition, delta: Point) => void;
+    onresizestart?: () => void;
+    onresizeend?: () => void;
+};
+declare const CircleStencil: import("svelte").Component<$$ComponentProps, {}, "">;
+type CircleStencil = ReturnType<typeof CircleStencil>;
+export default CircleStencil;

package/dist/components/CropOverlay.svelte

@@ -0,0 +1,51 @@
+<!--
+  svelte-chop-chop — Dark overlay with crop cutout
+  Shows dimmed area outside the crop rectangle.
+  Positioned to cover imageBounds; cutout at rect.
+-->
+<script lang="ts">
+  import type { Rect } from '../core/types.js';
+
+  let { rect, imageBounds }: { rect: Rect; imageBounds: Rect } = $props();
+
+  const maskX = $derived(rect.x - imageBounds.x);
+  const maskY = $derived(rect.y - imageBounds.y);
+</script>
+
+<svg
+  class="chop-overlay"
+  aria-hidden="true"
+  style:left="{imageBounds.x}px"
+  style:top="{imageBounds.y}px"
+  style:width="{imageBounds.width}px"
+  style:height="{imageBounds.height}px"
+>
+  <defs>
+    <mask id="chop-crop-mask">
+      <rect x="0" y="0" width="100%" height="100%" fill="white" />
+      <rect
+        x="{maskX}"
+        y="{maskY}"
+        width="{rect.width}"
+        height="{rect.height}"
+        fill="black"
+      />
+    </mask>
+  </defs>
+  <rect
+    x="0"
+    y="0"
+    width="100%"
+    height="100%"
+    fill="var(--chop-overlay, rgba(0, 0, 0, 0.55))"
+    mask="url(#chop-crop-mask)"
+  />
+</svg>
+
+<style>
+  .chop-overlay {
+    position: absolute;
+    pointer-events: none;
+    z-index: 2;
+  }
+</style>

package/dist/components/CropOverlay.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Rect } from '../core/types.js';
+type $$ComponentProps = {
+    rect: Rect;
+    imageBounds: Rect;
+};
+declare const CropOverlay: import("svelte").Component<$$ComponentProps, {}, "">;
+type CropOverlay = ReturnType<typeof CropOverlay>;
+export default CropOverlay;

package/dist/components/CropStencil.svelte

@@ -0,0 +1,84 @@
+<!--
+  svelte-chop-chop — Default rectangular stencil
+  Uses DragHandle, CropOverlay, GridOverlay.
+-->
+<script lang="ts">
+  import type { HandlePosition, Point, StencilProps } from '../core/types.js';
+  import { createDragHandler } from '../core/interactions.js';
+  import DragHandle from './DragHandle.svelte';
+  import GridOverlay from './GridOverlay.svelte';
+
+  let {
+    rect,
+    aspectRatio,
+    active,
+    imageBounds,
+    grid,
+    transitions,
+    onmove,
+    onresize,
+    onresizestart,
+    onresizeend,
+  }: StencilProps & {
+    onmove: (delta: Point) => void;
+    onresize: (handle: HandlePosition, delta: Point) => void;
+    onresizestart?: () => void;
+    onresizeend?: () => void;
+  } = $props();
+
+  const drag = createDragHandler({
+    onMove: (delta) => onmove(delta),
+  });
+</script>
+
+<div
+  class="chop-stencil chop-stencil-rect"
+  class:chop-stencil-active={active}
+  class:chop-stencil-transitions={transitions}
+  style:left="{rect.x}px"
+  style:top="{rect.y}px"
+  style:width="{rect.width}px"
+  style:height="{rect.height}px"
+  role="group"
+  aria-label="Crop area"
+  onpointerdown={drag.onpointerdown}
+  onpointermove={drag.onpointermove}
+  onpointerup={drag.onpointerup}
+>
+  {#if !aspectRatio || aspectRatio === null}
+    <DragHandle position="nw" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="ne" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="sw" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="se" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="n" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="s" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="e" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="w" {onresize} {onresizestart} {onresizeend} />
+  {:else}
+    <DragHandle position="nw" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="ne" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="sw" {onresize} {onresizestart} {onresizeend} />
+    <DragHandle position="se" {onresize} {onresizestart} {onresizeend} />
+  {/if}
+
+  <GridOverlay {rect} {grid} {active} />
+</div>
+
+<style>
+  .chop-stencil {
+    position: absolute;
+    border: 2px solid var(--chop-stencil-border, rgba(255, 255, 255, 0.8));
+    box-sizing: border-box;
+    z-index: 5;
+    touch-action: none;
+  }
+
+  .chop-stencil-active {
+    border-color: var(--chop-stencil-border-active, #fff);
+  }
+
+  .chop-stencil-transitions {
+    transition: border-color var(--chop-transition-duration, 300ms)
+      var(--chop-transition-easing, cubic-bezier(0.4, 0, 0.2, 1));
+  }
+</style>

package/dist/components/CropStencil.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { HandlePosition, Point, StencilProps } from '../core/types.js';
+type $$ComponentProps = StencilProps & {
+    onmove: (delta: Point) => void;
+    onresize: (handle: HandlePosition, delta: Point) => void;
+    onresizestart?: () => void;
+    onresizeend?: () => void;
+};
+declare const CropStencil: import("svelte").Component<$$ComponentProps, {}, "">;
+type CropStencil = ReturnType<typeof CropStencil>;
+export default CropStencil;