@molecule/app-feature-image-canvas-angular 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 +610 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,617 @@
|
|
|
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.228Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-feature-image-canvas-angular
|
|
2
10
|
|
|
3
|
-
Canvas2D image-editing surface
|
|
11
|
+
Angular Canvas2D image-editing surface.
|
|
12
|
+
|
|
13
|
+
Exports `<div mol-image-canvas>` — the Angular 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 { Component, signal } from '@angular/core'
|
|
29
|
+
import {
|
|
30
|
+
ImageCanvas,
|
|
31
|
+
type ImageCanvasExportHandle,
|
|
32
|
+
} from '@molecule/app-feature-image-canvas-angular'
|
|
33
|
+
|
|
34
|
+
@Component({
|
|
35
|
+
selector: 'app-editor',
|
|
36
|
+
standalone: true,
|
|
37
|
+
imports: [ImageCanvas],
|
|
38
|
+
template: `
|
|
39
|
+
<div
|
|
40
|
+
mol-image-canvas
|
|
41
|
+
[src]="'/photo.jpg'"
|
|
42
|
+
[filters]="filters"
|
|
43
|
+
[zoom]="zoom()"
|
|
44
|
+
[pan]="pan()"
|
|
45
|
+
[onChange]="applyView"
|
|
46
|
+
[exportRef]="exportRef"
|
|
47
|
+
></div>
|
|
48
|
+
`,
|
|
49
|
+
})
|
|
50
|
+
export class Editor {
|
|
51
|
+
protected readonly zoom = signal(1)
|
|
52
|
+
protected readonly pan = signal({ x: 0, y: 0 })
|
|
53
|
+
protected readonly filters = { brightness: 1.1, contrast: 1.2, sepia: 0.3 }
|
|
54
|
+
protected readonly exportRef: { current: ImageCanvasExportHandle | null } = { current: null }
|
|
55
|
+
|
|
56
|
+
protected readonly applyView = (next: { zoom: number; pan: { x: number; y: number } }) => {
|
|
57
|
+
this.zoom.set(next.zoom)
|
|
58
|
+
this.pan.set(next.pan)
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Type
|
|
64
|
+
|
|
65
|
+
`feature`
|
|
66
|
+
|
|
67
|
+
## Installation
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install @molecule/app-feature-image-canvas-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## API
|
|
74
|
+
|
|
75
|
+
### Interfaces
|
|
76
|
+
|
|
77
|
+
#### `PanOffset`
|
|
78
|
+
|
|
79
|
+
A two-dimensional offset, in CSS pixels, applied to the rendered image
|
|
80
|
+
relative to the centre of the canvas. Positive `x` shifts the image
|
|
81
|
+
right; positive `y` shifts it down.
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
interface PanOffset {
|
|
85
|
+
/** Horizontal offset, in CSS pixels. */
|
|
86
|
+
x: number
|
|
87
|
+
/** Vertical offset, in CSS pixels. */
|
|
88
|
+
y: number
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
#### `ImageCanvasFilters`
|
|
93
|
+
|
|
94
|
+
Filter parameters applied to the source image before it is rendered to
|
|
95
|
+
the canvas. Every field is optional — omitted fields disable that
|
|
96
|
+
filter. Values are clamped at compose time so out-of-range numbers are
|
|
97
|
+
safe.
|
|
98
|
+
|
|
99
|
+
Implementation note: composition uses the Canvas2D `filter` property
|
|
100
|
+
(CSS `<filter-function>` syntax). Compose order is preserved.
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
interface ImageCanvasFilters {
|
|
104
|
+
/**
|
|
105
|
+
* Brightness multiplier. `1` is identity, `0` is black, `2` is twice
|
|
106
|
+
* as bright. Values < 0 are clamped to 0.
|
|
107
|
+
*/
|
|
108
|
+
brightness?: number
|
|
109
|
+
/**
|
|
110
|
+
* Contrast multiplier. `1` is identity, `0` is fully grey, `2` is
|
|
111
|
+
* twice the contrast. Values < 0 are clamped to 0.
|
|
112
|
+
*/
|
|
113
|
+
contrast?: number
|
|
114
|
+
/**
|
|
115
|
+
* Saturation multiplier. `1` is identity, `0` is grayscale, `2` is
|
|
116
|
+
* twice as saturated. Values < 0 are clamped to 0.
|
|
117
|
+
*/
|
|
118
|
+
saturation?: number
|
|
119
|
+
/**
|
|
120
|
+
* Hue rotation in degrees. Normalised modulo 360 — any finite value
|
|
121
|
+
* is accepted.
|
|
122
|
+
*/
|
|
123
|
+
hue?: number
|
|
124
|
+
/**
|
|
125
|
+
* Sepia amount in `[0, 1]`. `0` disables; `1` applies fully. Values
|
|
126
|
+
* outside the range are clamped.
|
|
127
|
+
*/
|
|
128
|
+
sepia?: number
|
|
129
|
+
/**
|
|
130
|
+
* Grayscale amount in `[0, 1]`. `0` disables; `1` applies fully.
|
|
131
|
+
* Values outside the range are clamped.
|
|
132
|
+
*/
|
|
133
|
+
grayscale?: number
|
|
134
|
+
/**
|
|
135
|
+
* Gaussian blur radius in CSS pixels. `0` disables. Negative values
|
|
136
|
+
* are clamped to 0.
|
|
137
|
+
*/
|
|
138
|
+
blur?: number
|
|
139
|
+
/**
|
|
140
|
+
* Sharpen strength in `[0, 1]`. Approximated as a negative-blur
|
|
141
|
+
* contrast bump using the CSS `contrast()` filter; `0` disables.
|
|
142
|
+
* Values outside the range are clamped.
|
|
143
|
+
*/
|
|
144
|
+
sharpen?: number
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
#### `ImageCanvasExportHandle`
|
|
149
|
+
|
|
150
|
+
Imperative export handle exposed via `exportRef`. Callers use this to
|
|
151
|
+
grab the current rendered image (with all filters, zoom, and pan
|
|
152
|
+
baked in) as a data URL.
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
interface ImageCanvasExportHandle {
|
|
156
|
+
/**
|
|
157
|
+
* Snapshot the current canvas as a data URL.
|
|
158
|
+
*
|
|
159
|
+
* @param type - Image MIME type. Defaults to `image/png`.
|
|
160
|
+
* @param quality - Lossy quality in `[0, 1]` for `image/jpeg` /
|
|
161
|
+
* `image/webp`. Ignored for `image/png`.
|
|
162
|
+
* @returns A data URL string, or an empty string if the canvas is not
|
|
163
|
+
* yet mounted.
|
|
164
|
+
*/
|
|
165
|
+
toDataURL: (type?: string, quality?: number) => string
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### `ImageCanvasProps`
|
|
170
|
+
|
|
171
|
+
ImageCanvas component props (React's prop names).
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
interface ImageCanvasProps {
|
|
175
|
+
/**
|
|
176
|
+
* Image source. Either a string (URL or data URL) — which the
|
|
177
|
+
* component loads into an internal `HTMLImageElement` — or an
|
|
178
|
+
* already-loaded `HTMLImageElement` the caller manages.
|
|
179
|
+
*/
|
|
180
|
+
src: string | HTMLImageElement
|
|
181
|
+
/** Filter chain applied to the rendered image. */
|
|
182
|
+
filters?: ImageCanvasFilters
|
|
183
|
+
/**
|
|
184
|
+
* Zoom factor. `1` is identity. Values <= 0 fall back to `1`.
|
|
185
|
+
* Defaults to `1`.
|
|
186
|
+
*/
|
|
187
|
+
zoom?: number
|
|
188
|
+
/**
|
|
189
|
+
* Pan offset in CSS pixels relative to the centre of the canvas.
|
|
190
|
+
* Defaults to `{ x: 0, y: 0 }`.
|
|
191
|
+
*/
|
|
192
|
+
pan?: PanOffset
|
|
193
|
+
/**
|
|
194
|
+
* Optional callback fired when the user pans or zooms the canvas.
|
|
195
|
+
* Use this for controlled-component patterns.
|
|
196
|
+
*/
|
|
197
|
+
onChange?: (next: { zoom: number; pan: PanOffset }) => void
|
|
198
|
+
/**
|
|
199
|
+
* Imperative handle exposing `toDataURL()` for the caller to grab
|
|
200
|
+
* the rendered result.
|
|
201
|
+
*/
|
|
202
|
+
exportRef?: { current: ImageCanvasExportHandle | null }
|
|
203
|
+
/** Pixel width of the canvas. Defaults to `512`. */
|
|
204
|
+
width?: number
|
|
205
|
+
/** Pixel height of the canvas. Defaults to `512`. */
|
|
206
|
+
height?: number
|
|
207
|
+
/** Extra classes merged onto the root element. */
|
|
208
|
+
className?: string
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Classes
|
|
213
|
+
|
|
214
|
+
#### `ImageCanvas`
|
|
215
|
+
|
|
216
|
+
Canvas2D image-editing surface: a source image drawn onto a canvas with a
|
|
217
|
+
filter chain, pointer-drag panning, wheel zooming, and a `toDataURL()`
|
|
218
|
+
export handle.
|
|
219
|
+
|
|
220
|
+
The host IS React's root element (`div[mol-image-canvas]`), so the host
|
|
221
|
+
carries the region role, the aria label, the ClassMap classes and the frame
|
|
222
|
+
size exactly as React renders them. All user-visible text is translated
|
|
223
|
+
through the binding's `useTranslation()`.
|
|
224
|
+
|
|
225
|
+
```typescript
|
|
226
|
+
@Component({
|
|
227
|
+
selector: 'div[mol-image-canvas]',
|
|
228
|
+
standalone: true,
|
|
229
|
+
inputs: [
|
|
230
|
+
'src',
|
|
231
|
+
'filters',
|
|
232
|
+
'zoom',
|
|
233
|
+
'pan',
|
|
234
|
+
'onChange',
|
|
235
|
+
'exportRef',
|
|
236
|
+
'width',
|
|
237
|
+
'height',
|
|
238
|
+
'className',
|
|
239
|
+
],
|
|
240
|
+
host: {
|
|
241
|
+
role: 'region',
|
|
242
|
+
'data-mol-id': 'image-canvas',
|
|
243
|
+
'[attr.aria-label]': 'ariaLabel()',
|
|
244
|
+
'[class]': 'classes()',
|
|
245
|
+
'[style.display]': '"inline-block"',
|
|
246
|
+
'[style.width.px]': 'widthValue()',
|
|
247
|
+
'[style.height.px]': 'heightValue()',
|
|
248
|
+
'[style.position]': '"relative"',
|
|
249
|
+
},
|
|
250
|
+
template: `<canvas
|
|
251
|
+
#surface
|
|
252
|
+
[attr.width]="widthValue()"
|
|
253
|
+
[attr.height]="heightValue()"
|
|
254
|
+
[attr.aria-label]="dragLabel()"
|
|
255
|
+
data-mol-id="image-canvas-surface"
|
|
256
|
+
[attr.data-loading]="loadingAttr()"
|
|
257
|
+
[attr.data-error]="errorAttr()"
|
|
258
|
+
[style.display]="'block'"
|
|
259
|
+
[style.width.px]="widthValue()"
|
|
260
|
+
[style.height.px]="heightValue()"
|
|
261
|
+
[style.cursor]="cursor()"
|
|
262
|
+
[style.touch-action]="'none'"
|
|
263
|
+
(pointerdown)="handlePointerDown($event)"
|
|
264
|
+
(pointermove)="handlePointerMove($event)"
|
|
265
|
+
(pointerup)="endDrag($event)"
|
|
266
|
+
(pointercancel)="endDrag($event)"
|
|
267
|
+
(wheel)="handleWheel($event)"
|
|
268
|
+
></canvas>
|
|
269
|
+
@if (loadingAttr() === 'true') {
|
|
270
|
+
<p [class]="noteClasses()" data-mol-id="image-canvas-loading">{{ loadingLabel() }}</p>
|
|
271
|
+
}
|
|
272
|
+
@if (loadError() !== null) {
|
|
273
|
+
<p [class]="noteClasses()" data-mol-id="image-canvas-error" role="alert">
|
|
274
|
+
{{ errorLabel() }}
|
|
275
|
+
</p>
|
|
276
|
+
}`,
|
|
277
|
+
})
|
|
278
|
+
export class ImageCanvas implements OnInit, OnChanges, AfterViewInit, OnDestroy {
|
|
279
|
+
src?: string | HTMLImageElement
|
|
280
|
+
filters?: ImageCanvasFilters
|
|
281
|
+
/** Zoom factor; values <= 0 fall back to `1`. */
|
|
282
|
+
zoom?: number
|
|
283
|
+
pan?: PanOffset
|
|
284
|
+
onChange?: (next: { zoom: number; pan: PanOffset }) => void
|
|
285
|
+
exportRef?: ImageCanvasProps['exportRef']
|
|
286
|
+
width?: number
|
|
287
|
+
height?: number
|
|
288
|
+
className?: string
|
|
289
|
+
|
|
290
|
+
@ViewChild('surface') private surface?: ElementRef<HTMLCanvasElement>
|
|
291
|
+
|
|
292
|
+
private readonly i18n = useTranslation()
|
|
293
|
+
private t = this.i18n.t
|
|
294
|
+
private readonly classMap: UIClassMap = getClassMap()
|
|
295
|
+
|
|
296
|
+
private readonly image = signal<HTMLImageElement | null>(null)
|
|
297
|
+
private readonly loadError = signal<string | null>(null)
|
|
298
|
+
private loadToken = 0
|
|
299
|
+
private viewReady = false
|
|
300
|
+
private dragState: {
|
|
301
|
+
pointerId: number | null
|
|
302
|
+
startX: number
|
|
303
|
+
startY: number
|
|
304
|
+
startPan: PanOffset
|
|
305
|
+
} = { pointerId: null, startX: 0, startY: 0, startPan: { x: 0, y: 0 } }
|
|
306
|
+
|
|
307
|
+
/** The region's translated aria label. */
|
|
308
|
+
protected readonly ariaLabel = computed(() =>
|
|
309
|
+
this.t('imageCanvas.aria.region', {}, { defaultValue: 'Image canvas' }),
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
/** The canvas's translated aria label. */
|
|
313
|
+
protected readonly dragLabel = computed(() =>
|
|
314
|
+
this.t('imageCanvas.aria.canvas', {}, { defaultValue: 'Drag to pan, scroll to zoom' }),
|
|
315
|
+
)
|
|
316
|
+
|
|
317
|
+
/** The translated loading message. */
|
|
318
|
+
protected readonly loadingLabel = computed(() =>
|
|
319
|
+
this.t('imageCanvas.loading', {}, { defaultValue: 'Loading image…' }),
|
|
320
|
+
)
|
|
321
|
+
|
|
322
|
+
/** The translated error message. */
|
|
323
|
+
protected readonly errorLabel = computed(() =>
|
|
324
|
+
this.t('imageCanvas.error', {}, { defaultValue: 'Image failed to load.' }),
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
protected readonly loadingAttr = computed(() =>
|
|
328
|
+
this.image() ? 'false' : this.loadError() ? 'false' : 'true',
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
protected readonly errorAttr = computed(() => (this.loadError() ? 'true' : 'false'))
|
|
332
|
+
|
|
333
|
+
ngOnInit(): void {
|
|
334
|
+
const src = this.src
|
|
335
|
+
if (typeof src === 'string') {
|
|
336
|
+
this.load(src)
|
|
337
|
+
} else if (src !== undefined && isImageElement(src)) {
|
|
338
|
+
this.image.set(src)
|
|
339
|
+
this.loadError.set(null)
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
ngOnChanges(changes: SimpleChanges): void {
|
|
344
|
+
if (!this.viewReady) return
|
|
345
|
+
if (changes['src']) {
|
|
346
|
+
const src = changes['src'].currentValue as string | HTMLImageElement | undefined
|
|
347
|
+
if (typeof src === 'string') this.load(src)
|
|
348
|
+
else if (src !== undefined && isImageElement(src)) {
|
|
349
|
+
this.image.set(src)
|
|
350
|
+
this.loadError.set(null)
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
this.paint()
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
ngAfterViewInit(): void {
|
|
357
|
+
this.viewReady = true
|
|
358
|
+
this.paint()
|
|
359
|
+
if (this.exportRef) {
|
|
360
|
+
this.exportRef.current = {
|
|
361
|
+
toDataURL: (type, quality) => {
|
|
362
|
+
const canvas = this.surface?.nativeElement
|
|
363
|
+
if (!canvas) return ''
|
|
364
|
+
return canvas.toDataURL(type, quality)
|
|
365
|
+
},
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
}
|
|
4
369
|
|
|
370
|
+
ngOnDestroy(): void {
|
|
371
|
+
if (this.exportRef) this.exportRef.current = null
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
classes(): string {
|
|
375
|
+
return this.classMap.cn(this.className)
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
widthValue(): number {
|
|
379
|
+
return this.width ?? 512
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
heightValue(): number {
|
|
383
|
+
return this.height ?? 512
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
cursor(): string {
|
|
387
|
+
return this.onChange ? 'grab' : 'default'
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/** The loading/error paragraph's class list. */
|
|
391
|
+
noteClasses(): string {
|
|
392
|
+
return this.classMap.cn(this.classMap.textSize('xs'), this.classMap.sp('p', 2))
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
handlePointerDown(event: PointerEvent): void {
|
|
396
|
+
const canvas = this.surface?.nativeElement
|
|
397
|
+
if (!canvas) return
|
|
398
|
+
canvas.setPointerCapture(event.pointerId)
|
|
399
|
+
this.dragState = {
|
|
400
|
+
pointerId: event.pointerId,
|
|
401
|
+
startX: event.clientX,
|
|
402
|
+
startY: event.clientY,
|
|
403
|
+
startPan: { ...this.safePan() },
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
handlePointerMove(event: PointerEvent): void {
|
|
408
|
+
const state = this.dragState
|
|
409
|
+
if (state.pointerId !== event.pointerId) return
|
|
410
|
+
const dx = event.clientX - state.startX
|
|
411
|
+
const dy = event.clientY - state.startY
|
|
412
|
+
const image = this.image()
|
|
413
|
+
const next = clampPan(
|
|
414
|
+
{ x: state.startPan.x + dx, y: state.startPan.y + dy },
|
|
415
|
+
{ width: this.widthValue(), height: this.heightValue() },
|
|
416
|
+
image
|
|
417
|
+
? { width: image.naturalWidth, height: image.naturalHeight }
|
|
418
|
+
: { width: this.widthValue(), height: this.heightValue() },
|
|
419
|
+
this.safeZoom(),
|
|
420
|
+
)
|
|
421
|
+
this.onChange?.({ zoom: this.safeZoom(), pan: next })
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
endDrag(event: PointerEvent): void {
|
|
425
|
+
const state = this.dragState
|
|
426
|
+
if (state.pointerId !== event.pointerId) return
|
|
427
|
+
const canvas = this.surface?.nativeElement
|
|
428
|
+
if (canvas && canvas.hasPointerCapture(event.pointerId)) {
|
|
429
|
+
canvas.releasePointerCapture(event.pointerId)
|
|
430
|
+
}
|
|
431
|
+
this.dragState = { pointerId: null, startX: 0, startY: 0, startPan: { x: 0, y: 0 } }
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
handleWheel(event: WheelEvent): void {
|
|
435
|
+
const factor = event.deltaY < 0 ? 1.1 : 1 / 1.1
|
|
436
|
+
const nextZoom = clamp(this.safeZoom() * factor, 0.05, 32)
|
|
437
|
+
this.onChange?.({ zoom: nextZoom, pan: this.safePan() })
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
private safeZoom(): number {
|
|
441
|
+
const zoom = this.zoom
|
|
442
|
+
return zoom !== undefined && Number.isFinite(zoom) && zoom > 0 ? zoom : 1
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
private safePan(): PanOffset {
|
|
446
|
+
return {
|
|
447
|
+
x: Number.isFinite(this.pan?.x) ? (this.pan?.x as number) : 0,
|
|
448
|
+
y: Number.isFinite(this.pan?.y) ? (this.pan?.y as number) : 0,
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
private load(src: string): void {
|
|
453
|
+
const token = ++this.loadToken
|
|
454
|
+
this.loadError.set(null)
|
|
455
|
+
const img = new Image()
|
|
456
|
+
img.crossOrigin = 'anonymous'
|
|
457
|
+
img.onload = () => {
|
|
458
|
+
if (token !== this.loadToken) return
|
|
459
|
+
this.image.set(img)
|
|
460
|
+
this.paint()
|
|
461
|
+
}
|
|
462
|
+
img.onerror = () => {
|
|
463
|
+
if (token !== this.loadToken) return
|
|
464
|
+
this.loadError.set(src)
|
|
465
|
+
this.image.set(null)
|
|
466
|
+
this.paint()
|
|
467
|
+
}
|
|
468
|
+
img.src = src
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
private paint(): void {
|
|
472
|
+
const canvas = this.surface?.nativeElement
|
|
473
|
+
if (!canvas) return
|
|
474
|
+
const ctx = canvas.getContext('2d')
|
|
475
|
+
if (!ctx) return
|
|
476
|
+
|
|
477
|
+
const image = this.image()
|
|
478
|
+
const zoom = this.safeZoom()
|
|
479
|
+
const pan = this.safePan()
|
|
480
|
+
const width = this.widthValue()
|
|
481
|
+
const height = this.heightValue()
|
|
482
|
+
|
|
483
|
+
ctx.save()
|
|
484
|
+
ctx.clearRect(0, 0, width, height)
|
|
485
|
+
|
|
486
|
+
if (!image) {
|
|
487
|
+
ctx.restore()
|
|
488
|
+
return
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
ctx.filter = composeFilterString(this.filters)
|
|
492
|
+
const drawWidth = image.naturalWidth * zoom
|
|
493
|
+
const drawHeight = image.naturalHeight * zoom
|
|
494
|
+
const dx = width / 2 - drawWidth / 2 + pan.x
|
|
495
|
+
const dy = height / 2 - drawHeight / 2 + pan.y
|
|
496
|
+
ctx.drawImage(image, dx, dy, drawWidth, drawHeight)
|
|
497
|
+
ctx.restore()
|
|
498
|
+
}
|
|
499
|
+
}
|
|
5
500
|
```
|
|
6
|
-
|
|
501
|
+
|
|
502
|
+
_(The 30 longest member comments are left out to fit; the full declaration is in `node_modules/@molecule/app-feature-image-canvas-angular/dist/image-canvas.component.d.ts`.)_
|
|
503
|
+
|
|
504
|
+
### Functions
|
|
505
|
+
|
|
506
|
+
#### `clamp(value, min, max)`
|
|
507
|
+
|
|
508
|
+
Clamp a numeric value into the closed interval `[min, max]`. Returns
|
|
509
|
+
`min` for non-finite inputs.
|
|
510
|
+
|
|
511
|
+
```typescript
|
|
512
|
+
function clamp(value: number, min: number, max: number): number
|
|
7
513
|
```
|
|
8
514
|
|
|
9
|
-
|
|
515
|
+
- `value` — The value to clamp.
|
|
516
|
+
- `min` — Inclusive minimum.
|
|
517
|
+
- `max` — Inclusive maximum.
|
|
518
|
+
|
|
519
|
+
**Returns:** The clamped value.
|
|
520
|
+
|
|
521
|
+
#### `composeFilterString(filters)`
|
|
522
|
+
|
|
523
|
+
Compose a CSS filter string from a set of `ImageCanvasFilters` values.
|
|
524
|
+
Out-of-range values are clamped; omitted / non-finite fields are
|
|
525
|
+
ignored. Returns `'none'` when no filters are active so callers can
|
|
526
|
+
assign the result directly to `CanvasRenderingContext2D.filter`.
|
|
527
|
+
|
|
528
|
+
```typescript
|
|
529
|
+
function composeFilterString(filters?: ImageCanvasFilters): string
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
- `filters` — The filter parameters. May be `undefined`.
|
|
533
|
+
|
|
534
|
+
**Returns:** A CSS filter string, or `'none'` when nothing applies.
|
|
535
|
+
|
|
536
|
+
#### `screenToCanvas(point, canvasSize, imageSize, zoom, pan)`
|
|
537
|
+
|
|
538
|
+
Convert a screen-space (canvas-relative) point into image-space
|
|
539
|
+
coordinates given the current zoom + pan and the source image
|
|
540
|
+
dimensions. Useful for tools that need to know which image pixel a
|
|
541
|
+
pointer event hit (cropping, picking, masking).
|
|
542
|
+
|
|
543
|
+
```typescript
|
|
544
|
+
function screenToCanvas(
|
|
545
|
+
point: { x: number; y: number },
|
|
546
|
+
canvasSize: { width: number; height: number },
|
|
547
|
+
imageSize: { width: number; height: number },
|
|
548
|
+
zoom: number,
|
|
549
|
+
pan: PanOffset,
|
|
550
|
+
): { x: number; y: number }
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
- `point` — The canvas-space point in CSS pixels (origin top-left of the canvas element).
|
|
554
|
+
- `canvasSize` — The canvas size in CSS pixels.
|
|
555
|
+
- `imageSize` — The source image's natural size in pixels.
|
|
556
|
+
- `zoom` — The current zoom factor. Non-positive values fall back to `1`.
|
|
557
|
+
- `pan` — The current pan offset in CSS pixels.
|
|
558
|
+
|
|
559
|
+
**Returns:** The corresponding point in image-space coordinates.
|
|
560
|
+
|
|
561
|
+
#### `clampPan(pan, canvasSize, imageSize, zoom)`
|
|
562
|
+
|
|
563
|
+
Clamp a pan offset so the (zoomed) image cannot be dragged entirely
|
|
564
|
+
off-canvas. The clamp keeps at least half of the image visible in
|
|
565
|
+
each axis. Non-finite inputs are treated as `0`.
|
|
566
|
+
|
|
567
|
+
```typescript
|
|
568
|
+
function clampPan(
|
|
569
|
+
pan: PanOffset,
|
|
570
|
+
canvasSize: { width: number; height: number },
|
|
571
|
+
imageSize: { width: number; height: number },
|
|
572
|
+
zoom: number,
|
|
573
|
+
): PanOffset
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
- `pan` — The desired pan offset, in CSS pixels.
|
|
577
|
+
- `canvasSize` — The canvas size in CSS pixels.
|
|
578
|
+
- `imageSize` — The source image's natural size in pixels.
|
|
579
|
+
- `zoom` — The current zoom factor. Non-positive values fall back to `1`.
|
|
580
|
+
|
|
581
|
+
**Returns:** The clamped pan offset.
|
|
582
|
+
|
|
583
|
+
## Injection Notes
|
|
584
|
+
|
|
585
|
+
### Requirements
|
|
586
|
+
|
|
587
|
+
Peer dependencies:
|
|
588
|
+
|
|
589
|
+
- `@angular/common` ^22.0.0
|
|
590
|
+
- `@angular/core` ^22.0.0
|
|
591
|
+
- `@angular/platform-browser` ^22.0.0
|
|
592
|
+
- `@molecule/app-angular` ^3.5.0
|
|
593
|
+
- `@molecule/app-ui` ^1.0.1
|
|
594
|
+
- `@molecule/app-ui-angular` ^1.1.0
|
|
595
|
+
|
|
596
|
+
### Runtime Dependencies
|
|
597
|
+
|
|
598
|
+
- `@angular/common`
|
|
599
|
+
- `@angular/core`
|
|
600
|
+
- `@angular/platform-browser`
|
|
601
|
+
- `@molecule/app-angular`
|
|
602
|
+
- `@molecule/app-ui`
|
|
603
|
+
- `@molecule/app-ui-angular`
|
|
604
|
+
|
|
605
|
+
- The host element IS the React root: `div[mol-image-canvas]` carries
|
|
606
|
+
`role="region"`, the aria label, the ClassMap classes and the pixel frame
|
|
607
|
+
size. An attribute selector is used so the host is a plain `<div>`.
|
|
608
|
+
- Pan / zoom interaction is CONTROLLED-ONLY: pointer-drag and wheel events
|
|
609
|
+
call `onChange` with the proposed `{ zoom, pan }` and never mutate
|
|
610
|
+
internal state.
|
|
611
|
+
- Requires a bonded ClassMap and i18n provider.
|
|
612
|
+
- URL sources load with `crossOrigin="anonymous"` so `toDataURL()` is never
|
|
613
|
+
blocked by a tainted canvas.
|
|
614
|
+
|
|
615
|
+
## Translations
|
|
10
616
|
|
|
11
|
-
|
|
617
|
+
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-angular",
|
|
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-angular",
|
|
6
6
|
"type": "module",
|
|
@@ -59,12 +59,12 @@
|
|
|
59
59
|
"@angular/compiler-cli": "22.2.3",
|
|
60
60
|
"@angular/core": "22.2.3",
|
|
61
61
|
"@angular/platform-browser": "22.2.3",
|
|
62
|
-
"@molecule/app-angular": "3.
|
|
62
|
+
"@molecule/app-angular": "3.9.0",
|
|
63
63
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
64
64
|
"@molecule/app-i18n": "1.2.2",
|
|
65
65
|
"@molecule/app-icons": "1.0.4",
|
|
66
|
-
"@molecule/app-ui": "1.
|
|
67
|
-
"@molecule/app-ui-angular": "1.
|
|
66
|
+
"@molecule/app-ui": "1.5.0",
|
|
67
|
+
"@molecule/app-ui-angular": "1.3.1",
|
|
68
68
|
"@types/node": "26.6.5",
|
|
69
69
|
"jsdom": "30.1.3",
|
|
70
70
|
"rxjs": "7.8.2",
|