react-smart-copy 0.1.0 → 0.2.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 +136 -23
- package/dist/capture.cjs +498 -0
- package/dist/capture.cjs.map +1 -0
- package/dist/capture.d.cts +142 -0
- package/dist/capture.d.ts +142 -0
- package/dist/capture.js +485 -0
- package/dist/capture.js.map +1 -0
- package/dist/core.cjs +559 -22
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +257 -9
- package/dist/core.d.ts +257 -9
- package/dist/core.js +544 -23
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +645 -29
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +312 -11
- package/dist/index.d.ts +312 -11
- package/dist/index.js +627 -30
- package/dist/index.js.map +1 -1
- package/package.json +39 -10
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
//#region src/capture/environment.d.ts
|
|
2
|
+
/** A decoded image, ready to be drawn. `source` is platform-specific (an `HTMLImageElement` in browsers). */
|
|
3
|
+
interface DecodedImage {
|
|
4
|
+
readonly source: unknown;
|
|
5
|
+
readonly width: number;
|
|
6
|
+
readonly height: number;
|
|
7
|
+
}
|
|
8
|
+
interface PngTarget {
|
|
9
|
+
/** Integer pixel size of the output. */
|
|
10
|
+
readonly width: number;
|
|
11
|
+
readonly height: number;
|
|
12
|
+
/** CSS colour painted under the image, or `null` for transparency. */
|
|
13
|
+
readonly background: string | null;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Everything capture needs from the platform. The default uses the DOM;
|
|
17
|
+
* inject your own for workers (OffscreenCanvas), native shells or tests.
|
|
18
|
+
*/
|
|
19
|
+
interface CaptureEnvironment {
|
|
20
|
+
readonly createObjectURL: (blob: Blob) => string;
|
|
21
|
+
readonly revokeObjectURL: (url: string) => void;
|
|
22
|
+
/** Serialises an `<svg>` element to markup. */
|
|
23
|
+
readonly serializeSvg: (node: Element) => string;
|
|
24
|
+
/** Decodes an image from a `blob:` or `data:` URL. */
|
|
25
|
+
readonly loadImage: (url: string) => Promise<DecodedImage>;
|
|
26
|
+
/** Draws the image scaled to `target` and encodes it as PNG. */
|
|
27
|
+
readonly encodePng: (image: DecodedImage, target: PngTarget) => Promise<Blob>;
|
|
28
|
+
}
|
|
29
|
+
/** The DOM-backed environment, or `null` outside a browser. */
|
|
30
|
+
export declare function getDefaultCaptureEnvironment(): CaptureEnvironment | null;
|
|
31
|
+
//#endregion
|
|
32
|
+
//#region src/capture/options.d.ts
|
|
33
|
+
export declare const DEFAULT_CAPTURE_SCALE = 2;
|
|
34
|
+
export declare const MAX_CAPTURE_SCALE = 10;
|
|
35
|
+
/** 4096 × 4096: the canvas area limit of Safari/iOS, the strictest mainstream engine. */
|
|
36
|
+
export declare const DEFAULT_MAX_PIXELS = 16777216;
|
|
37
|
+
export declare const DEFAULT_CAPTURE_TIMEOUT_MS = 15000;
|
|
38
|
+
interface RenderOptions {
|
|
39
|
+
/** Output width in CSS px (before `scale`). Omit to use the intrinsic size; set one side to keep the aspect ratio. */
|
|
40
|
+
readonly width?: number;
|
|
41
|
+
/** Output height in CSS px (before `scale`). */
|
|
42
|
+
readonly height?: number;
|
|
43
|
+
/** Pixel density multiplier, e.g. `window.devicePixelRatio`. Default 2 (crisp on HiDPI). Max 10. */
|
|
44
|
+
readonly scale?: number;
|
|
45
|
+
/** CSS colour under the image. Default `null` (transparent). */
|
|
46
|
+
readonly background?: string | null;
|
|
47
|
+
/** Refuse outputs larger than this many pixels (memory / DoS guard). Default 16 777 216. */
|
|
48
|
+
readonly maxPixels?: number;
|
|
49
|
+
/** Give up after this long. Default 15 000 ms. `Infinity` disables. */
|
|
50
|
+
readonly timeoutMs?: number;
|
|
51
|
+
/** Cancel the capture. */
|
|
52
|
+
readonly signal?: AbortSignal;
|
|
53
|
+
/** Platform hooks. Defaults to the DOM. */
|
|
54
|
+
readonly environment?: CaptureEnvironment;
|
|
55
|
+
}
|
|
56
|
+
interface Size {
|
|
57
|
+
readonly width: number;
|
|
58
|
+
readonly height: number;
|
|
59
|
+
}
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region src/capture/svg.d.ts
|
|
62
|
+
export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
|
|
63
|
+
/** Refuse absurd markup before handing it to the image decoder. 10 M characters. */
|
|
64
|
+
export declare const DEFAULT_MAX_SVG_LENGTH = 10000000;
|
|
65
|
+
interface SvgToPngOptions extends RenderOptions {
|
|
66
|
+
/** Max markup length in characters. Default 10 000 000. */
|
|
67
|
+
readonly maxLength?: number;
|
|
68
|
+
}
|
|
69
|
+
/** Intrinsic size from the root tag: `width`/`height` in px, else the `viewBox`. */
|
|
70
|
+
export declare function readSvgSize(markup: string): Size | null;
|
|
71
|
+
/** Adds the SVG namespace when missing; `<img>` refuses to decode SVG without it. */
|
|
72
|
+
export declare function ensureSvgNamespace(markup: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* Rasterises SVG (an `<svg>` element or markup) to a PNG Blob, ready for
|
|
75
|
+
* `copy({ kind: 'image', blob })`.
|
|
76
|
+
*
|
|
77
|
+
* Security: the SVG is decoded as an *image*, where browsers disable scripts,
|
|
78
|
+
* event handlers and external resource loading, and it is never inserted into
|
|
79
|
+
* the document. Size is capped in characters and pixels.
|
|
80
|
+
*/
|
|
81
|
+
export declare function svgToPngBlob(source: Element | string, options?: SvgToPngOptions): Promise<Blob>;
|
|
82
|
+
//#endregion
|
|
83
|
+
//#region src/core/payload.d.ts
|
|
84
|
+
/**
|
|
85
|
+
* An image as a Blob, a promise of one, or a function producing one.
|
|
86
|
+
* Prefer the function form: it is invoked synchronously inside the user
|
|
87
|
+
* gesture, which Safari requires for async image generation.
|
|
88
|
+
*/
|
|
89
|
+
type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
90
|
+
interface ImagePayload {
|
|
91
|
+
readonly kind: 'image';
|
|
92
|
+
readonly blob: BlobSource;
|
|
93
|
+
}
|
|
94
|
+
//#endregion
|
|
95
|
+
//#region src/capture/element.d.ts
|
|
96
|
+
/** Anything with `canvas.toBlob()`: `HTMLCanvasElement`, or a compatible object. */
|
|
97
|
+
interface CanvasLike {
|
|
98
|
+
toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* What a rasteriser may return: a Blob (any raster format), a canvas, or a
|
|
102
|
+
* base64 `data:image/…` URL. Network URLs are refused (never fetched).
|
|
103
|
+
*/
|
|
104
|
+
type RasterizeOutput = Blob | CanvasLike | string;
|
|
105
|
+
interface RasterizeContext {
|
|
106
|
+
/** Pixel density to render at. */
|
|
107
|
+
readonly scale: number;
|
|
108
|
+
/** CSS size of the element (or the requested size). */
|
|
109
|
+
readonly width: number;
|
|
110
|
+
readonly height: number;
|
|
111
|
+
readonly backgroundColor: string | null;
|
|
112
|
+
/** Fires on timeout or caller abort: stop work early if you can. */
|
|
113
|
+
readonly signal: AbortSignal;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Turns a DOM node into pixels. Bring your own engine, e.g.
|
|
117
|
+
* `(node, { scale }) => domToBlob(node, { scale })` from `modern-screenshot`.
|
|
118
|
+
*/
|
|
119
|
+
type Rasterizer = (node: Element, context: RasterizeContext) => PromiseLike<RasterizeOutput> | RasterizeOutput;
|
|
120
|
+
interface CaptureElementOptions extends RenderOptions {
|
|
121
|
+
/** Required for HTML elements. `<svg>` elements are rasterised natively when omitted. */
|
|
122
|
+
readonly rasterize?: Rasterizer;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Captures an element as a PNG Blob, ready for `copy({ kind: 'image', blob })`.
|
|
126
|
+
* Output is verified to be a real PNG within `maxPixels`, or a classified
|
|
127
|
+
* `CopyFailure` is thrown (`invalid-payload`, `unsupported`, `too-large`,
|
|
128
|
+
* `timeout`, `aborted`, `blob-generation-failed`).
|
|
129
|
+
*/
|
|
130
|
+
export declare function captureElement(node: Element | null | undefined, options?: CaptureElementOptions): Promise<Blob>;
|
|
131
|
+
/**
|
|
132
|
+
* A lazy `BlobSource` for `copy()`. Resolving the element at click time and
|
|
133
|
+
* starting inside the gesture keeps Safari happy.
|
|
134
|
+
*
|
|
135
|
+
* @example copy({ kind: 'image', blob: captureSource(() => cardRef.current, { rasterize }) })
|
|
136
|
+
*/
|
|
137
|
+
export declare function captureSource(getNode: () => Element | null | undefined, options?: CaptureElementOptions): () => Promise<Blob>;
|
|
138
|
+
/** Shorthand for `{ kind: 'image', blob: captureSource(getNode, options) }`. */
|
|
139
|
+
export declare function captureImage(getNode: () => Element | null | undefined, options?: CaptureElementOptions): ImagePayload;
|
|
140
|
+
//#endregion
|
|
141
|
+
export type { CanvasLike, CaptureElementOptions, CaptureEnvironment, DecodedImage, PngTarget, RasterizeContext, RasterizeOutput, Rasterizer, RenderOptions, Size, SvgToPngOptions };
|
|
142
|
+
//# sourceMappingURL=capture.d.cts.map
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
//#region src/capture/environment.d.ts
|
|
2
|
+
/** A decoded image, ready to be drawn. `source` is platform-specific (an `HTMLImageElement` in browsers). */
|
|
3
|
+
interface DecodedImage {
|
|
4
|
+
readonly source: unknown;
|
|
5
|
+
readonly width: number;
|
|
6
|
+
readonly height: number;
|
|
7
|
+
}
|
|
8
|
+
interface PngTarget {
|
|
9
|
+
/** Integer pixel size of the output. */
|
|
10
|
+
readonly width: number;
|
|
11
|
+
readonly height: number;
|
|
12
|
+
/** CSS colour painted under the image, or `null` for transparency. */
|
|
13
|
+
readonly background: string | null;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Everything capture needs from the platform. The default uses the DOM;
|
|
17
|
+
* inject your own for workers (OffscreenCanvas), native shells or tests.
|
|
18
|
+
*/
|
|
19
|
+
interface CaptureEnvironment {
|
|
20
|
+
readonly createObjectURL: (blob: Blob) => string;
|
|
21
|
+
readonly revokeObjectURL: (url: string) => void;
|
|
22
|
+
/** Serialises an `<svg>` element to markup. */
|
|
23
|
+
readonly serializeSvg: (node: Element) => string;
|
|
24
|
+
/** Decodes an image from a `blob:` or `data:` URL. */
|
|
25
|
+
readonly loadImage: (url: string) => Promise<DecodedImage>;
|
|
26
|
+
/** Draws the image scaled to `target` and encodes it as PNG. */
|
|
27
|
+
readonly encodePng: (image: DecodedImage, target: PngTarget) => Promise<Blob>;
|
|
28
|
+
}
|
|
29
|
+
/** The DOM-backed environment, or `null` outside a browser. */
|
|
30
|
+
export declare function getDefaultCaptureEnvironment(): CaptureEnvironment | null;
|
|
31
|
+
//#endregion
|
|
32
|
+
//#region src/capture/options.d.ts
|
|
33
|
+
export declare const DEFAULT_CAPTURE_SCALE = 2;
|
|
34
|
+
export declare const MAX_CAPTURE_SCALE = 10;
|
|
35
|
+
/** 4096 × 4096: the canvas area limit of Safari/iOS, the strictest mainstream engine. */
|
|
36
|
+
export declare const DEFAULT_MAX_PIXELS = 16777216;
|
|
37
|
+
export declare const DEFAULT_CAPTURE_TIMEOUT_MS = 15000;
|
|
38
|
+
interface RenderOptions {
|
|
39
|
+
/** Output width in CSS px (before `scale`). Omit to use the intrinsic size; set one side to keep the aspect ratio. */
|
|
40
|
+
readonly width?: number;
|
|
41
|
+
/** Output height in CSS px (before `scale`). */
|
|
42
|
+
readonly height?: number;
|
|
43
|
+
/** Pixel density multiplier, e.g. `window.devicePixelRatio`. Default 2 (crisp on HiDPI). Max 10. */
|
|
44
|
+
readonly scale?: number;
|
|
45
|
+
/** CSS colour under the image. Default `null` (transparent). */
|
|
46
|
+
readonly background?: string | null;
|
|
47
|
+
/** Refuse outputs larger than this many pixels (memory / DoS guard). Default 16 777 216. */
|
|
48
|
+
readonly maxPixels?: number;
|
|
49
|
+
/** Give up after this long. Default 15 000 ms. `Infinity` disables. */
|
|
50
|
+
readonly timeoutMs?: number;
|
|
51
|
+
/** Cancel the capture. */
|
|
52
|
+
readonly signal?: AbortSignal;
|
|
53
|
+
/** Platform hooks. Defaults to the DOM. */
|
|
54
|
+
readonly environment?: CaptureEnvironment;
|
|
55
|
+
}
|
|
56
|
+
interface Size {
|
|
57
|
+
readonly width: number;
|
|
58
|
+
readonly height: number;
|
|
59
|
+
}
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region src/capture/svg.d.ts
|
|
62
|
+
export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
|
|
63
|
+
/** Refuse absurd markup before handing it to the image decoder. 10 M characters. */
|
|
64
|
+
export declare const DEFAULT_MAX_SVG_LENGTH = 10000000;
|
|
65
|
+
interface SvgToPngOptions extends RenderOptions {
|
|
66
|
+
/** Max markup length in characters. Default 10 000 000. */
|
|
67
|
+
readonly maxLength?: number;
|
|
68
|
+
}
|
|
69
|
+
/** Intrinsic size from the root tag: `width`/`height` in px, else the `viewBox`. */
|
|
70
|
+
export declare function readSvgSize(markup: string): Size | null;
|
|
71
|
+
/** Adds the SVG namespace when missing; `<img>` refuses to decode SVG without it. */
|
|
72
|
+
export declare function ensureSvgNamespace(markup: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* Rasterises SVG (an `<svg>` element or markup) to a PNG Blob, ready for
|
|
75
|
+
* `copy({ kind: 'image', blob })`.
|
|
76
|
+
*
|
|
77
|
+
* Security: the SVG is decoded as an *image*, where browsers disable scripts,
|
|
78
|
+
* event handlers and external resource loading, and it is never inserted into
|
|
79
|
+
* the document. Size is capped in characters and pixels.
|
|
80
|
+
*/
|
|
81
|
+
export declare function svgToPngBlob(source: Element | string, options?: SvgToPngOptions): Promise<Blob>;
|
|
82
|
+
//#endregion
|
|
83
|
+
//#region src/core/payload.d.ts
|
|
84
|
+
/**
|
|
85
|
+
* An image as a Blob, a promise of one, or a function producing one.
|
|
86
|
+
* Prefer the function form: it is invoked synchronously inside the user
|
|
87
|
+
* gesture, which Safari requires for async image generation.
|
|
88
|
+
*/
|
|
89
|
+
type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
90
|
+
interface ImagePayload {
|
|
91
|
+
readonly kind: 'image';
|
|
92
|
+
readonly blob: BlobSource;
|
|
93
|
+
}
|
|
94
|
+
//#endregion
|
|
95
|
+
//#region src/capture/element.d.ts
|
|
96
|
+
/** Anything with `canvas.toBlob()`: `HTMLCanvasElement`, or a compatible object. */
|
|
97
|
+
interface CanvasLike {
|
|
98
|
+
toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* What a rasteriser may return: a Blob (any raster format), a canvas, or a
|
|
102
|
+
* base64 `data:image/…` URL. Network URLs are refused (never fetched).
|
|
103
|
+
*/
|
|
104
|
+
type RasterizeOutput = Blob | CanvasLike | string;
|
|
105
|
+
interface RasterizeContext {
|
|
106
|
+
/** Pixel density to render at. */
|
|
107
|
+
readonly scale: number;
|
|
108
|
+
/** CSS size of the element (or the requested size). */
|
|
109
|
+
readonly width: number;
|
|
110
|
+
readonly height: number;
|
|
111
|
+
readonly backgroundColor: string | null;
|
|
112
|
+
/** Fires on timeout or caller abort: stop work early if you can. */
|
|
113
|
+
readonly signal: AbortSignal;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Turns a DOM node into pixels. Bring your own engine, e.g.
|
|
117
|
+
* `(node, { scale }) => domToBlob(node, { scale })` from `modern-screenshot`.
|
|
118
|
+
*/
|
|
119
|
+
type Rasterizer = (node: Element, context: RasterizeContext) => PromiseLike<RasterizeOutput> | RasterizeOutput;
|
|
120
|
+
interface CaptureElementOptions extends RenderOptions {
|
|
121
|
+
/** Required for HTML elements. `<svg>` elements are rasterised natively when omitted. */
|
|
122
|
+
readonly rasterize?: Rasterizer;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Captures an element as a PNG Blob, ready for `copy({ kind: 'image', blob })`.
|
|
126
|
+
* Output is verified to be a real PNG within `maxPixels`, or a classified
|
|
127
|
+
* `CopyFailure` is thrown (`invalid-payload`, `unsupported`, `too-large`,
|
|
128
|
+
* `timeout`, `aborted`, `blob-generation-failed`).
|
|
129
|
+
*/
|
|
130
|
+
export declare function captureElement(node: Element | null | undefined, options?: CaptureElementOptions): Promise<Blob>;
|
|
131
|
+
/**
|
|
132
|
+
* A lazy `BlobSource` for `copy()`. Resolving the element at click time and
|
|
133
|
+
* starting inside the gesture keeps Safari happy.
|
|
134
|
+
*
|
|
135
|
+
* @example copy({ kind: 'image', blob: captureSource(() => cardRef.current, { rasterize }) })
|
|
136
|
+
*/
|
|
137
|
+
export declare function captureSource(getNode: () => Element | null | undefined, options?: CaptureElementOptions): () => Promise<Blob>;
|
|
138
|
+
/** Shorthand for `{ kind: 'image', blob: captureSource(getNode, options) }`. */
|
|
139
|
+
export declare function captureImage(getNode: () => Element | null | undefined, options?: CaptureElementOptions): ImagePayload;
|
|
140
|
+
//#endregion
|
|
141
|
+
export type { CanvasLike, CaptureElementOptions, CaptureEnvironment, DecodedImage, PngTarget, RasterizeContext, RasterizeOutput, Rasterizer, RenderOptions, Size, SvgToPngOptions };
|
|
142
|
+
//# sourceMappingURL=capture.d.ts.map
|