@molecule/app-feature-image-canvas-solid 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 +323 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,330 @@
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.482Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-image-canvas-solid
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
+ Solid Canvas2D image-editing surface.
12
+
13
+ Exports `ImageCanvas` — the Solid 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
+ ```tsx
28
+ import { createSignal } from 'solid-js'
29
+ import { ImageCanvas, type ImageCanvasExportHandle } from '@molecule/app-feature-image-canvas-solid'
30
+
31
+ export function Editor() {
32
+ const [zoom, setZoom] = createSignal(1)
33
+ const [pan, setPan] = createSignal({ x: 0, y: 0 })
34
+ const exportRef: { current: ImageCanvasExportHandle | null } = { current: null }
35
+ return (
36
+ <ImageCanvas
37
+ src="/photo.jpg"
38
+ filters={{ brightness: 1.1, contrast: 1.2, sepia: 0.3 }}
39
+ zoom={zoom()}
40
+ pan={pan()}
41
+ onChange={(next) => {
42
+ setZoom(next.zoom)
43
+ setPan(next.pan)
44
+ }}
45
+ exportRef={exportRef}
46
+ />
47
+ )
48
+ }
49
+ ```
50
+
51
+ ## Type
52
+
53
+ `feature`
54
+
55
+ ## Installation
56
+
57
+ ```bash
58
+ npm install @molecule/app-feature-image-canvas-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
59
+ ```
60
+
61
+ ## API
62
+
63
+ ### Interfaces
64
+
65
+ #### `PanOffset`
66
+
67
+ A two-dimensional offset, in CSS pixels, applied to the rendered image
68
+ relative to the centre of the canvas. Positive `x` shifts the image
69
+ right; positive `y` shifts it down.
70
+
71
+ ```typescript
72
+ interface PanOffset {
73
+ /** Horizontal offset, in CSS pixels. */
74
+ x: number
75
+ /** Vertical offset, in CSS pixels. */
76
+ y: number
77
+ }
78
+ ```
79
+
80
+ #### `ImageCanvasFilters`
81
+
82
+ Filter parameters applied to the source image before it is rendered to
83
+ the canvas. Every field is optional — omitted fields disable that
84
+ filter. Values are clamped at compose time so out-of-range numbers are
85
+ safe.
4
86
 
87
+ Implementation note: composition uses the Canvas2D `filter` property
88
+ (CSS `<filter-function>` syntax). Compose order is preserved.
89
+
90
+ ```typescript
91
+ interface ImageCanvasFilters {
92
+ /**
93
+ * Brightness multiplier. `1` is identity, `0` is black, `2` is twice
94
+ * as bright. Values < 0 are clamped to 0.
95
+ */
96
+ brightness?: number
97
+ /**
98
+ * Contrast multiplier. `1` is identity, `0` is fully grey, `2` is
99
+ * twice the contrast. Values < 0 are clamped to 0.
100
+ */
101
+ contrast?: number
102
+ /**
103
+ * Saturation multiplier. `1` is identity, `0` is grayscale, `2` is
104
+ * twice as saturated. Values < 0 are clamped to 0.
105
+ */
106
+ saturation?: number
107
+ /**
108
+ * Hue rotation in degrees. Normalised modulo 360 — any finite value
109
+ * is accepted.
110
+ */
111
+ hue?: number
112
+ /**
113
+ * Sepia amount in `[0, 1]`. `0` disables; `1` applies fully. Values
114
+ * outside the range are clamped.
115
+ */
116
+ sepia?: number
117
+ /**
118
+ * Grayscale amount in `[0, 1]`. `0` disables; `1` applies fully.
119
+ * Values outside the range are clamped.
120
+ */
121
+ grayscale?: number
122
+ /**
123
+ * Gaussian blur radius in CSS pixels. `0` disables. Negative values
124
+ * are clamped to 0.
125
+ */
126
+ blur?: number
127
+ /**
128
+ * Sharpen strength in `[0, 1]`. Approximated as a negative-blur
129
+ * contrast bump using the CSS `contrast()` filter; `0` disables.
130
+ * Values outside the range are clamped.
131
+ */
132
+ sharpen?: number
133
+ }
5
134
  ```
6
- npm install @molecule/app-feature-image-canvas-solid
135
+
136
+ #### `ImageCanvasExportHandle`
137
+
138
+ Imperative export handle exposed via `exportRef`. Callers use this to
139
+ grab the current rendered image (with all filters, zoom, and pan
140
+ baked in) as a data URL.
141
+
142
+ ```typescript
143
+ interface ImageCanvasExportHandle {
144
+ /**
145
+ * Snapshot the current canvas as a data URL.
146
+ *
147
+ * @param type - Image MIME type. Defaults to `image/png`.
148
+ * @param quality - Lossy quality in `[0, 1]` for `image/jpeg` /
149
+ * `image/webp`. Ignored for `image/png`.
150
+ * @returns A data URL string, or an empty string if the canvas is not
151
+ * yet mounted.
152
+ */
153
+ toDataURL: (type?: string, quality?: number) => string
154
+ }
155
+ ```
156
+
157
+ #### `ImageCanvasProps`
158
+
159
+ ImageCanvas component props (React's prop names).
160
+
161
+ ```typescript
162
+ interface ImageCanvasProps {
163
+ /**
164
+ * Image source. Either a string (URL or data URL) — which the
165
+ * component loads into an internal `HTMLImageElement` — or an
166
+ * already-loaded `HTMLImageElement` the caller manages.
167
+ */
168
+ src: string | HTMLImageElement
169
+ /** Filter chain applied to the rendered image. */
170
+ filters?: ImageCanvasFilters
171
+ /**
172
+ * Zoom factor. `1` is identity. Values <= 0 fall back to `1`.
173
+ * Defaults to `1`.
174
+ */
175
+ zoom?: number
176
+ /**
177
+ * Pan offset in CSS pixels relative to the centre of the canvas.
178
+ * Defaults to `{ x: 0, y: 0 }`.
179
+ */
180
+ pan?: PanOffset
181
+ /**
182
+ * Optional callback fired when the user pans or zooms the canvas.
183
+ * Use this for controlled-component patterns.
184
+ */
185
+ onChange?: (next: { zoom: number; pan: PanOffset }) => void
186
+ /**
187
+ * Imperative handle exposing `toDataURL()` for the caller to grab
188
+ * the rendered result.
189
+ */
190
+ exportRef?: { current: ImageCanvasExportHandle | null }
191
+ /** Pixel width of the canvas. Defaults to `512`. */
192
+ width?: number
193
+ /** Pixel height of the canvas. Defaults to `512`. */
194
+ height?: number
195
+ /** Extra classes merged onto the root element. */
196
+ className?: string
197
+ }
198
+ ```
199
+
200
+ ### Functions
201
+
202
+ #### `ImageCanvas(props)`
203
+
204
+ Canvas2D image-editing surface. Renders a source image onto a canvas with a
205
+ filter chain (brightness, contrast, saturation, hue, sepia, grayscale, blur,
206
+ sharpen), pointer-event drag panning, and wheel zooming. The current state
207
+ can be exported to a data URL via the `exportRef` imperative handle.
208
+
209
+ All styling routes through `getClassMap()` (no raw class names). All
210
+ user-visible text routes through `t()` so the canvas translates via the
211
+ companion locale bond.
212
+
213
+ ```typescript
214
+ function ImageCanvas(props: ImageCanvasProps): JSX.Element
7
215
  ```
8
216
 
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.
217
+ - `props` — Component props (see {@link ImageCanvasProps}).
218
+
219
+ **Returns:** The rendered image canvas.
220
+
221
+ #### `clamp(value, min, max)`
222
+
223
+ Clamp a numeric value into the closed interval `[min, max]`. Returns
224
+ `min` for non-finite inputs.
225
+
226
+ ```typescript
227
+ function clamp(value: number, min: number, max: number): number
228
+ ```
229
+
230
+ - `value` — The value to clamp.
231
+ - `min` — Inclusive minimum.
232
+ - `max` — Inclusive maximum.
233
+
234
+ **Returns:** The clamped value.
235
+
236
+ #### `composeFilterString(filters)`
237
+
238
+ Compose a CSS filter string from a set of `ImageCanvasFilters` values.
239
+ Out-of-range values are clamped; omitted / non-finite fields are
240
+ ignored. Returns `'none'` when no filters are active so callers can
241
+ assign the result directly to `CanvasRenderingContext2D.filter`.
242
+
243
+ ```typescript
244
+ function composeFilterString(filters?: ImageCanvasFilters): string
245
+ ```
246
+
247
+ - `filters` — The filter parameters. May be `undefined`.
248
+
249
+ **Returns:** A CSS filter string, or `'none'` when nothing applies.
250
+
251
+ #### `screenToCanvas(point, canvasSize, imageSize, zoom, pan)`
252
+
253
+ Convert a screen-space (canvas-relative) point into image-space
254
+ coordinates given the current zoom + pan and the source image
255
+ dimensions. Useful for tools that need to know which image pixel a
256
+ pointer event hit (cropping, picking, masking).
257
+
258
+ ```typescript
259
+ function screenToCanvas(
260
+ point: { x: number; y: number },
261
+ canvasSize: { width: number; height: number },
262
+ imageSize: { width: number; height: number },
263
+ zoom: number,
264
+ pan: PanOffset,
265
+ ): { x: number; y: number }
266
+ ```
267
+
268
+ - `point` — The canvas-space point in CSS pixels (origin top-left of the canvas element).
269
+ - `canvasSize` — The canvas size in CSS pixels.
270
+ - `imageSize` — The source image's natural size in pixels.
271
+ - `zoom` — The current zoom factor. Non-positive values fall back to `1`.
272
+ - `pan` — The current pan offset in CSS pixels.
273
+
274
+ **Returns:** The corresponding point in image-space coordinates.
275
+
276
+ #### `clampPan(pan, canvasSize, imageSize, zoom)`
277
+
278
+ Clamp a pan offset so the (zoomed) image cannot be dragged entirely
279
+ off-canvas. The clamp keeps at least half of the image visible in
280
+ each axis. Non-finite inputs are treated as `0`.
281
+
282
+ ```typescript
283
+ function clampPan(
284
+ pan: PanOffset,
285
+ canvasSize: { width: number; height: number },
286
+ imageSize: { width: number; height: number },
287
+ zoom: number,
288
+ ): PanOffset
289
+ ```
290
+
291
+ - `pan` — The desired pan offset, in CSS pixels.
292
+ - `canvasSize` — The canvas size in CSS pixels.
293
+ - `imageSize` — The source image's natural size in pixels.
294
+ - `zoom` — The current zoom factor. Non-positive values fall back to `1`.
295
+
296
+ **Returns:** The clamped pan offset.
297
+
298
+ ## Injection Notes
299
+
300
+ ### Requirements
301
+
302
+ Peer dependencies:
303
+
304
+ - `@molecule/app-solid` ^3.5.0
305
+ - `@molecule/app-ui` ^1.0.1
306
+ - `@molecule/app-ui-solid` ^1.1.0
307
+ - `solid-js` ^1.8.0
308
+
309
+ ### Runtime Dependencies
310
+
311
+ - `@molecule/app-solid`
312
+ - `@molecule/app-ui`
313
+ - `@molecule/app-ui-solid`
314
+ - `solid-js`
315
+
316
+ - Pan / zoom interaction is CONTROLLED-ONLY: pointer-drag and wheel events
317
+ call `onChange` with the proposed `{ zoom, pan }` and never mutate
318
+ internal state. Without `onChange` and a caller feeding the values back
319
+ through the `zoom` / `pan` props, dragging and scrolling do nothing.
320
+ - Requires a bonded ClassMap (the frame and the loading text use ClassMap
321
+ tokens) and a bonded i18n provider for its aria labels and messages.
322
+ - URL sources load with `crossOrigin="anonymous"` so `toDataURL()` is never
323
+ blocked by a tainted canvas — remote images MUST be served with CORS
324
+ headers. Same-origin and data-URL sources are unaffected.
325
+ - The canvas bitmap is exactly `width` x `height` device-independent
326
+ pixels — there is no devicePixelRatio upscaling.
327
+
328
+ ## Translations
10
329
 
11
- License: Apache-2.0
330
+ 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-solid",
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-solid",
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-solid": "3.7.2",
59
- "@molecule/app-ui": "1.4.0",
60
- "@molecule/app-ui-solid": "1.1.5",
58
+ "@molecule/app-solid": "3.9.0",
59
+ "@molecule/app-ui": "1.5.0",
60
+ "@molecule/app-ui-solid": "1.2.1",
61
61
  "@types/node": "26.6.5",
62
62
  "jsdom": "30.1.3",
63
63
  "solid-js": "1.9.17",