@molecule/app-feature-image-canvas-vue 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.
- package/README.md +370 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,377 @@
|
|
|
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.829Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-feature-image-canvas-vue
|
|
2
10
|
|
|
3
|
-
Canvas2D image-editing surface
|
|
11
|
+
Vue Canvas2D image-editing surface.
|
|
12
|
+
|
|
13
|
+
Exports `ImageCanvas` — the Vue 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
|
+
```ts
|
|
28
|
+
import { defineComponent, h, ref } from 'vue'
|
|
29
|
+
import { ImageCanvas, type ImageCanvasExportHandle } from '@molecule/app-feature-image-canvas-vue'
|
|
30
|
+
|
|
31
|
+
const Editor = defineComponent({
|
|
32
|
+
setup() {
|
|
33
|
+
const exportRef = ref<{ current: ImageCanvasExportHandle | null }>({ current: null })
|
|
34
|
+
const zoom = ref(1)
|
|
35
|
+
const pan = ref({ x: 0, y: 0 })
|
|
36
|
+
return () =>
|
|
37
|
+
h(ImageCanvas, {
|
|
38
|
+
src: '/photo.jpg',
|
|
39
|
+
filters: { brightness: 1.1, contrast: 1.2, sepia: 0.3 },
|
|
40
|
+
zoom: zoom.value,
|
|
41
|
+
pan: pan.value,
|
|
42
|
+
onChange: (next) => {
|
|
43
|
+
zoom.value = next.zoom
|
|
44
|
+
pan.value = next.pan
|
|
45
|
+
},
|
|
46
|
+
exportRef: exportRef.value,
|
|
47
|
+
})
|
|
48
|
+
},
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Type
|
|
53
|
+
|
|
54
|
+
`feature`
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npm install @molecule/app-feature-image-canvas-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
|
|
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
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
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.
|
|
4
207
|
|
|
208
|
+
```typescript
|
|
209
|
+
function clamp(value: number, min: number, max: number): number
|
|
5
210
|
```
|
|
6
|
-
|
|
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
|
|
7
271
|
```
|
|
8
272
|
|
|
9
|
-
|
|
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
|
+
Canvas2D image-editing surface. Renders a source image onto a canvas with a
|
|
285
|
+
filter chain (brightness, contrast, saturation, hue, sepia, grayscale, blur,
|
|
286
|
+
sharpen), pointer-event drag panning, and wheel zooming. The current state
|
|
287
|
+
can be exported to a data URL via the `exportRef` imperative handle.
|
|
288
|
+
|
|
289
|
+
All styling routes through `getClassMap()` (no raw class names). All
|
|
290
|
+
user-visible text routes through `t()` so the canvas translates via the
|
|
291
|
+
companion locale bond.
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
const ImageCanvas: DefineComponent<
|
|
295
|
+
ExtractPropTypes<{
|
|
296
|
+
src: { type: PropType<string | HTMLImageElement>; required: true }
|
|
297
|
+
filters: { type: PropType<ImageCanvasFilters> }
|
|
298
|
+
zoom: { type: NumberConstructor; default: number }
|
|
299
|
+
pan: { type: PropType<PanOffset> }
|
|
300
|
+
onChange: { type: PropType<NonNullable<ImageCanvasProps['onChange']>> }
|
|
301
|
+
exportRef: { type: PropType<NonNullable<ImageCanvasProps['exportRef']>> }
|
|
302
|
+
width: { type: NumberConstructor; default: number }
|
|
303
|
+
height: { type: NumberConstructor; default: number }
|
|
304
|
+
className: StringConstructor
|
|
305
|
+
}>,
|
|
306
|
+
() => VNode,
|
|
307
|
+
{},
|
|
308
|
+
{},
|
|
309
|
+
{},
|
|
310
|
+
ComponentOptionsMixin,
|
|
311
|
+
ComponentOptionsMixin,
|
|
312
|
+
{},
|
|
313
|
+
string,
|
|
314
|
+
PublicProps,
|
|
315
|
+
Readonly<
|
|
316
|
+
ExtractPropTypes<{
|
|
317
|
+
src: { type: PropType<string | HTMLImageElement>; required: true }
|
|
318
|
+
filters: { type: PropType<ImageCanvasFilters> }
|
|
319
|
+
zoom: { type: NumberConstructor; default: number }
|
|
320
|
+
pan: { type: PropType<PanOffset> }
|
|
321
|
+
onChange: { type: PropType<NonNullable<ImageCanvasProps['onChange']>> }
|
|
322
|
+
exportRef: { type: PropType<NonNullable<ImageCanvasProps['exportRef']>> }
|
|
323
|
+
width: { type: NumberConstructor; default: number }
|
|
324
|
+
height: { type: NumberConstructor; default: number }
|
|
325
|
+
className: StringConstructor
|
|
326
|
+
}>
|
|
327
|
+
> &
|
|
328
|
+
Readonly<{}>,
|
|
329
|
+
{ zoom: number; width: number; height: number },
|
|
330
|
+
{},
|
|
331
|
+
{},
|
|
332
|
+
{},
|
|
333
|
+
string,
|
|
334
|
+
ComponentProvideOptions,
|
|
335
|
+
true,
|
|
336
|
+
{},
|
|
337
|
+
any
|
|
338
|
+
>
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
- `props` — Component props (see {@link ImageCanvasProps}).
|
|
342
|
+
|
|
343
|
+
**Returns:** The image-canvas component.
|
|
344
|
+
|
|
345
|
+
## Injection Notes
|
|
346
|
+
|
|
347
|
+
### Requirements
|
|
348
|
+
|
|
349
|
+
Peer dependencies:
|
|
350
|
+
|
|
351
|
+
- `@molecule/app-ui` ^1.0.1
|
|
352
|
+
- `@molecule/app-ui-vue` ^1.1.0
|
|
353
|
+
- `@molecule/app-vue` ^3.5.0
|
|
354
|
+
- `vue` ^3.4.0
|
|
355
|
+
|
|
356
|
+
### Runtime Dependencies
|
|
357
|
+
|
|
358
|
+
- `@molecule/app-ui`
|
|
359
|
+
- `@molecule/app-ui-vue`
|
|
360
|
+
- `@molecule/app-vue`
|
|
361
|
+
- `vue`
|
|
362
|
+
|
|
363
|
+
- Pan / zoom interaction is CONTROLLED-ONLY: pointer-drag and wheel events
|
|
364
|
+
call `onChange` with the proposed `{ zoom, pan }` and never mutate
|
|
365
|
+
internal state. Without `onChange` and a caller feeding the values back
|
|
366
|
+
through the `zoom` / `pan` props, dragging and scrolling do nothing.
|
|
367
|
+
- Requires a bonded ClassMap (the frame and the loading text use ClassMap
|
|
368
|
+
tokens) and a bonded i18n provider for its aria labels and messages.
|
|
369
|
+
- URL sources load with `crossOrigin="anonymous"` so `toDataURL()` is never
|
|
370
|
+
blocked by a tainted canvas — remote images MUST be served with CORS
|
|
371
|
+
headers. Same-origin and data-URL sources are unaffected.
|
|
372
|
+
- The canvas bitmap is exactly `width` x `height` device-independent
|
|
373
|
+
pixels — there is no devicePixelRatio upscaling.
|
|
374
|
+
|
|
375
|
+
## Translations
|
|
10
376
|
|
|
11
|
-
|
|
377
|
+
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-vue",
|
|
3
|
-
"version": "
|
|
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-vue",
|
|
6
6
|
"type": "module",
|
|
@@ -55,9 +55,9 @@
|
|
|
55
55
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
56
56
|
"@molecule/app-i18n": "1.2.2",
|
|
57
57
|
"@molecule/app-icons": "1.0.4",
|
|
58
|
-
"@molecule/app-ui": "1.
|
|
59
|
-
"@molecule/app-ui-vue": "1.1
|
|
60
|
-
"@molecule/app-vue": "3.
|
|
58
|
+
"@molecule/app-ui": "1.5.0",
|
|
59
|
+
"@molecule/app-ui-vue": "1.2.1",
|
|
60
|
+
"@molecule/app-vue": "3.9.0",
|
|
61
61
|
"@types/node": "26.6.5",
|
|
62
62
|
"jsdom": "30.1.3",
|
|
63
63
|
"typescript": "6.0.3",
|