@molecule/app-feature-image-canvas-svelte 0.0.1-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +313 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,320 @@
1
+ <!--
2
+ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
+ Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
+ Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
+ To change this document, edit the module-level JSDoc in src/index.ts.
6
+ Generated: 2026-11-21T12:46:31.614Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-image-canvas-svelte
2
10
 
3
- Canvas2D image-editing surface — accepts an image source, applies a filter chain (brightness, contrast, saturation, hue, sepia, grayscale, blur, sharpen), supports zoom + pan, exports back to data URL
11
+ Svelte Canvas2D image-editing surface.
12
+
13
+ Exports `ImageCanvas` — the Svelte counterpart of
14
+ `@molecule/app-feature-image-canvas-react` with the same props and the same
15
+ DOM: an image rendered onto a canvas with a filter chain (brightness,
16
+ contrast, saturation, hue, sepia, grayscale, blur, sharpen), pointer-drag
17
+ panning, wheel zooming, and a `toDataURL()` export handle, plus the
18
+ framework-free `clamp`, `composeFilterString`, `screenToCanvas` and
19
+ `clampPan` helpers.
20
+
21
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
22
+ > It is written to be read by coding agents as much as by people, and is generated from this
23
+ > package's source — edit `src/index.ts` JSDoc, not this file.
24
+
25
+ ## Quick Start
26
+
27
+ ```svelte
28
+ <script lang="ts">
29
+ import {
30
+ ImageCanvas,
31
+ type ImageCanvasExportHandle,
32
+ } from '@molecule/app-feature-image-canvas-svelte'
4
33
 
34
+ let zoom = $state(1)
35
+ let pan = $state({ x: 0, y: 0 })
36
+ const exportRef: { current: ImageCanvasExportHandle | null } = { current: null }
37
+ </script>
38
+
39
+ <ImageCanvas
40
+ src="/photo.jpg"
41
+ filters={{ brightness: 1.1, contrast: 1.2, sepia: 0.3 }}
42
+ {zoom}
43
+ {pan}
44
+ onChange={(next) => {
45
+ zoom = next.zoom
46
+ pan = next.pan
47
+ }}
48
+ {exportRef}
49
+ />
5
50
  ```
6
- npm install @molecule/app-feature-image-canvas-svelte
51
+
52
+ ## Type
53
+
54
+ `feature`
55
+
56
+ ## Installation
57
+
58
+ ```bash
59
+ npm install @molecule/app-feature-image-canvas-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
60
+ ```
61
+
62
+ ## API
63
+
64
+ ### Interfaces
65
+
66
+ #### `PanOffset`
67
+
68
+ A two-dimensional offset, in CSS pixels, applied to the rendered image
69
+ relative to the centre of the canvas. Positive `x` shifts the image
70
+ right; positive `y` shifts it down.
71
+
72
+ ```typescript
73
+ interface PanOffset {
74
+ /** Horizontal offset, in CSS pixels. */
75
+ x: number
76
+ /** Vertical offset, in CSS pixels. */
77
+ y: number
78
+ }
7
79
  ```
8
80
 
9
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
81
+ #### `ImageCanvasFilters`
82
+
83
+ Filter parameters applied to the source image before it is rendered to
84
+ the canvas. Every field is optional — omitted fields disable that
85
+ filter. Values are clamped at compose time so out-of-range numbers are
86
+ safe.
87
+
88
+ Implementation note: composition uses the Canvas2D `filter` property
89
+ (CSS `<filter-function>` syntax). Compose order is preserved.
90
+
91
+ ```typescript
92
+ interface ImageCanvasFilters {
93
+ /**
94
+ * Brightness multiplier. `1` is identity, `0` is black, `2` is twice
95
+ * as bright. Values < 0 are clamped to 0.
96
+ */
97
+ brightness?: number
98
+ /**
99
+ * Contrast multiplier. `1` is identity, `0` is fully grey, `2` is
100
+ * twice the contrast. Values < 0 are clamped to 0.
101
+ */
102
+ contrast?: number
103
+ /**
104
+ * Saturation multiplier. `1` is identity, `0` is grayscale, `2` is
105
+ * twice as saturated. Values < 0 are clamped to 0.
106
+ */
107
+ saturation?: number
108
+ /**
109
+ * Hue rotation in degrees. Normalised modulo 360 — any finite value
110
+ * is accepted.
111
+ */
112
+ hue?: number
113
+ /**
114
+ * Sepia amount in `[0, 1]`. `0` disables; `1` applies fully. Values
115
+ * outside the range are clamped.
116
+ */
117
+ sepia?: number
118
+ /**
119
+ * Grayscale amount in `[0, 1]`. `0` disables; `1` applies fully.
120
+ * Values outside the range are clamped.
121
+ */
122
+ grayscale?: number
123
+ /**
124
+ * Gaussian blur radius in CSS pixels. `0` disables. Negative values
125
+ * are clamped to 0.
126
+ */
127
+ blur?: number
128
+ /**
129
+ * Sharpen strength in `[0, 1]`. Approximated as a negative-blur
130
+ * contrast bump using the CSS `contrast()` filter; `0` disables.
131
+ * Values outside the range are clamped.
132
+ */
133
+ sharpen?: number
134
+ }
135
+ ```
136
+
137
+ #### `ImageCanvasExportHandle`
138
+
139
+ Imperative export handle exposed via `exportRef`. Callers use this to
140
+ grab the current rendered image (with all filters, zoom, and pan
141
+ baked in) as a data URL.
142
+
143
+ ```typescript
144
+ interface ImageCanvasExportHandle {
145
+ /**
146
+ * Snapshot the current canvas as a data URL.
147
+ *
148
+ * @param type - Image MIME type. Defaults to `image/png`.
149
+ * @param quality - Lossy quality in `[0, 1]` for `image/jpeg` /
150
+ * `image/webp`. Ignored for `image/png`.
151
+ * @returns A data URL string, or an empty string if the canvas is not
152
+ * yet mounted.
153
+ */
154
+ toDataURL: (type?: string, quality?: number) => string
155
+ }
156
+ ```
157
+
158
+ #### `ImageCanvasProps`
159
+
160
+ ImageCanvas component props (React's prop names).
161
+
162
+ ```typescript
163
+ interface ImageCanvasProps {
164
+ /**
165
+ * Image source. Either a string (URL or data URL) — which the
166
+ * component loads into an internal `HTMLImageElement` — or an
167
+ * already-loaded `HTMLImageElement` the caller manages.
168
+ */
169
+ src: string | HTMLImageElement
170
+ /** Filter chain applied to the rendered image. */
171
+ filters?: ImageCanvasFilters
172
+ /**
173
+ * Zoom factor. `1` is identity. Values <= 0 fall back to `1`.
174
+ * Defaults to `1`.
175
+ */
176
+ zoom?: number
177
+ /**
178
+ * Pan offset in CSS pixels relative to the centre of the canvas.
179
+ * Defaults to `{ x: 0, y: 0 }`.
180
+ */
181
+ pan?: PanOffset
182
+ /**
183
+ * Optional callback fired when the user pans or zooms the canvas.
184
+ * Use this for controlled-component patterns.
185
+ */
186
+ onChange?: (next: { zoom: number; pan: PanOffset }) => void
187
+ /**
188
+ * Imperative handle exposing `toDataURL()` for the caller to grab
189
+ * the rendered result.
190
+ */
191
+ exportRef?: { current: ImageCanvasExportHandle | null }
192
+ /** Pixel width of the canvas. Defaults to `512`. */
193
+ width?: number
194
+ /** Pixel height of the canvas. Defaults to `512`. */
195
+ height?: number
196
+ /** Extra classes merged onto the root element. */
197
+ className?: string
198
+ }
199
+ ```
200
+
201
+ ### Functions
202
+
203
+ #### `clamp(value, min, max)`
204
+
205
+ Clamp a numeric value into the closed interval `[min, max]`. Returns
206
+ `min` for non-finite inputs.
207
+
208
+ ```typescript
209
+ function clamp(value: number, min: number, max: number): number
210
+ ```
211
+
212
+ - `value` — The value to clamp.
213
+ - `min` — Inclusive minimum.
214
+ - `max` — Inclusive maximum.
215
+
216
+ **Returns:** The clamped value.
217
+
218
+ #### `composeFilterString(filters)`
219
+
220
+ Compose a CSS filter string from a set of `ImageCanvasFilters` values.
221
+ Out-of-range values are clamped; omitted / non-finite fields are
222
+ ignored. Returns `'none'` when no filters are active so callers can
223
+ assign the result directly to `CanvasRenderingContext2D.filter`.
224
+
225
+ ```typescript
226
+ function composeFilterString(filters?: ImageCanvasFilters): string
227
+ ```
228
+
229
+ - `filters` — The filter parameters. May be `undefined`.
230
+
231
+ **Returns:** A CSS filter string, or `'none'` when nothing applies.
232
+
233
+ #### `screenToCanvas(point, canvasSize, imageSize, zoom, pan)`
234
+
235
+ Convert a screen-space (canvas-relative) point into image-space
236
+ coordinates given the current zoom + pan and the source image
237
+ dimensions. Useful for tools that need to know which image pixel a
238
+ pointer event hit (cropping, picking, masking).
239
+
240
+ ```typescript
241
+ function screenToCanvas(
242
+ point: { x: number; y: number },
243
+ canvasSize: { width: number; height: number },
244
+ imageSize: { width: number; height: number },
245
+ zoom: number,
246
+ pan: PanOffset,
247
+ ): { x: number; y: number }
248
+ ```
249
+
250
+ - `point` — The canvas-space point in CSS pixels (origin top-left of the canvas element).
251
+ - `canvasSize` — The canvas size in CSS pixels.
252
+ - `imageSize` — The source image's natural size in pixels.
253
+ - `zoom` — The current zoom factor. Non-positive values fall back to `1`.
254
+ - `pan` — The current pan offset in CSS pixels.
255
+
256
+ **Returns:** The corresponding point in image-space coordinates.
257
+
258
+ #### `clampPan(pan, canvasSize, imageSize, zoom)`
259
+
260
+ Clamp a pan offset so the (zoomed) image cannot be dragged entirely
261
+ off-canvas. The clamp keeps at least half of the image visible in
262
+ each axis. Non-finite inputs are treated as `0`.
263
+
264
+ ```typescript
265
+ function clampPan(
266
+ pan: PanOffset,
267
+ canvasSize: { width: number; height: number },
268
+ imageSize: { width: number; height: number },
269
+ zoom: number,
270
+ ): PanOffset
271
+ ```
272
+
273
+ - `pan` — The desired pan offset, in CSS pixels.
274
+ - `canvasSize` — The canvas size in CSS pixels.
275
+ - `imageSize` — The source image's natural size in pixels.
276
+ - `zoom` — The current zoom factor. Non-positive values fall back to `1`.
277
+
278
+ **Returns:** The clamped pan offset.
279
+
280
+ ### Constants
281
+
282
+ #### `ImageCanvas`
283
+
284
+ ```typescript
285
+ const ImageCanvas: LegacyComponentType
286
+ ```
287
+
288
+ ## Injection Notes
289
+
290
+ ### Requirements
291
+
292
+ Peer dependencies:
293
+
294
+ - `@molecule/app-svelte` ^3.5.0
295
+ - `@molecule/app-ui` ^1.0.1
296
+ - `@molecule/app-ui-svelte` ^1.1.0
297
+ - `svelte` ^5.0.0
298
+
299
+ ### Runtime Dependencies
300
+
301
+ - `@molecule/app-svelte`
302
+ - `@molecule/app-ui`
303
+ - `@molecule/app-ui-svelte`
304
+ - `svelte`
305
+
306
+ - Pan / zoom interaction is CONTROLLED-ONLY: pointer-drag and wheel events
307
+ call `onChange` with the proposed `{ zoom, pan }` and never mutate
308
+ internal state. Without `onChange` and a caller feeding the values back
309
+ through the `zoom` / `pan` props, dragging and scrolling do nothing.
310
+ - Requires a bonded ClassMap (the frame and the loading text use ClassMap
311
+ tokens) and a bonded i18n provider for its aria labels and messages.
312
+ - URL sources load with `crossOrigin="anonymous"` so `toDataURL()` is never
313
+ blocked by a tainted canvas — remote images MUST be served with CORS
314
+ headers. Same-origin and data-URL sources are unaffected.
315
+ - The canvas bitmap is exactly `width` x `height` device-independent
316
+ pixels — there is no devicePixelRatio upscaling.
317
+
318
+ ## Translations
10
319
 
11
- License: Apache-2.0
320
+ Translation strings are provided by `@molecule/app-locales-feature-image-canvas`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-feature-image-canvas-svelte",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Canvas2D image-editing surface — accepts an image source, applies a filter chain (brightness, contrast, saturation, hue, sepia, grayscale, blur, sharpen), supports zoom + pan, exports back to data URL",
5
5
  "homepage": "https://www.molecule.dev/packages/app-feature-image-canvas-svelte",
6
6
  "type": "module",
@@ -61,9 +61,9 @@
61
61
  "@molecule/app-framework-conformance": "0.0.0",
62
62
  "@molecule/app-i18n": "1.2.2",
63
63
  "@molecule/app-icons": "1.0.4",
64
- "@molecule/app-svelte": "3.7.2",
65
- "@molecule/app-ui": "1.4.0",
66
- "@molecule/app-ui-svelte": "1.1.7",
64
+ "@molecule/app-svelte": "3.9.0",
65
+ "@molecule/app-ui": "1.5.0",
66
+ "@molecule/app-ui-svelte": "1.2.1",
67
67
  "@sveltejs/package": "3.0.2",
68
68
  "@sveltejs/vite-plugin-svelte": "7.1.2",
69
69
  "@types/node": "26.6.5",