@molecule/app-feature-image-canvas-angular 0.0.0-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 CHANGED
@@ -1,3 +1,617 @@
1
- # Temporary Holding Version
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
+ -->
2
8
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
9
+ # @molecule/app-feature-image-canvas-angular
10
+
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
+ }
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
+ }
500
+ ```
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
513
+ ```
514
+
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
616
+
617
+ Translation strings are provided by `@molecule/app-locales-feature-image-canvas`.
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Framework-free helpers of the Angular Canvas2D image-editing surface — the same
3
+ * values `@molecule/app-feature-image-canvas-react` exports.
4
+ *
5
+ * @module
6
+ */
7
+ import type { ImageCanvasFilters, PanOffset } from './types.js';
8
+ /**
9
+ * Clamp a numeric value into the closed interval `[min, max]`. Returns
10
+ * `min` for non-finite inputs.
11
+ *
12
+ * @param value - The value to clamp.
13
+ * @param min - Inclusive minimum.
14
+ * @param max - Inclusive maximum.
15
+ * @returns The clamped value.
16
+ */
17
+ export declare function clamp(value: number, min: number, max: number): number;
18
+ /**
19
+ * Compose a CSS filter string from a set of `ImageCanvasFilters` values.
20
+ * Out-of-range values are clamped; omitted / non-finite fields are
21
+ * ignored. Returns `'none'` when no filters are active so callers can
22
+ * assign the result directly to `CanvasRenderingContext2D.filter`.
23
+ *
24
+ * @param filters - The filter parameters. May be `undefined`.
25
+ * @returns A CSS filter string, or `'none'` when nothing applies.
26
+ */
27
+ export declare function composeFilterString(filters?: ImageCanvasFilters): string;
28
+ /**
29
+ * Convert a screen-space (canvas-relative) point into image-space
30
+ * coordinates given the current zoom + pan and the source image
31
+ * dimensions. Useful for tools that need to know which image pixel a
32
+ * pointer event hit (cropping, picking, masking).
33
+ *
34
+ * @param point - The canvas-space point in CSS pixels (origin top-left
35
+ * of the canvas element).
36
+ * @param canvasSize - The canvas size in CSS pixels.
37
+ * @param imageSize - The source image's natural size in pixels.
38
+ * @param zoom - The current zoom factor. Non-positive values fall back
39
+ * to `1`.
40
+ * @param pan - The current pan offset in CSS pixels.
41
+ * @returns The corresponding point in image-space coordinates.
42
+ */
43
+ export declare function screenToCanvas(point: {
44
+ x: number;
45
+ y: number;
46
+ }, canvasSize: {
47
+ width: number;
48
+ height: number;
49
+ }, imageSize: {
50
+ width: number;
51
+ height: number;
52
+ }, zoom: number, pan: PanOffset): {
53
+ x: number;
54
+ y: number;
55
+ };
56
+ /**
57
+ * Clamp a pan offset so the (zoomed) image cannot be dragged entirely
58
+ * off-canvas. The clamp keeps at least half of the image visible in
59
+ * each axis. Non-finite inputs are treated as `0`.
60
+ *
61
+ * @param pan - The desired pan offset, in CSS pixels.
62
+ * @param canvasSize - The canvas size in CSS pixels.
63
+ * @param imageSize - The source image's natural size in pixels.
64
+ * @param zoom - The current zoom factor. Non-positive values fall back
65
+ * to `1`.
66
+ * @returns The clamped pan offset.
67
+ */
68
+ export declare function clampPan(pan: PanOffset, canvasSize: {
69
+ width: number;
70
+ height: number;
71
+ }, imageSize: {
72
+ width: number;
73
+ height: number;
74
+ }, zoom: number): PanOffset;
75
+ //# sourceMappingURL=helpers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAuCxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/B,UAAU,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7C,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,SAAS,GACb;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAa1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,SAAS,EACd,UAAU,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7C,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5C,IAAI,EAAE,MAAM,GACX,SAAS,CAgBX"}