copy-image-clipboard - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

CHANGELOG.md

@@ -5,2 +5,12 @@ # Changelog
 
+## 2.1.0 - 2022-02-19
+
+**Features**
+
+- Add JSDoc comments to all exported functions
+
+**Fixes**
+
+- Improve documentation organization and clarity
+
 ## 2.0.1 - 2021-09-09
@@ -7,0 +17,0 @@

dist/index.browser.js

@@ -1,2 +0,2 @@
-/* copy-image-clipboard 2.0.1 - Licensed MIT @ Luan Eduardo da Costa */
+/* copy-image-clipboard 2.1.0 - Licensed MIT @ Luan Eduardo da Costa */
 var CopyImageClipboard=function(n){"use strict";function t(n,t,o,e){return new(o||(o=Promise))((function(i,r){function c(n){try{a(e.next(n))}catch(n){r(n)}}function u(n){try{a(e.throw(n))}catch(n){r(n)}}function a(n){var t;n.done?i(n.value):(t=n.value,t instanceof o?t:new o((function(n){n(t)}))).then(c,u)}a((e=e.apply(n,t||[])).next())}))}function o(n){return t(this,void 0,void 0,(function*(){const t=yield fetch(`${n}`);return yield t.blob()}))}function e(n){return n.type.includes("jpeg")}function i(n){return n.type.includes("png")}function r(n){return t(this,void 0,void 0,(function*(){return new Promise((function(t,o){const e=document.createElement("img");e.crossOrigin="anonymous",e.src=n,e.onload=function(n){const o=n.target;t(o)},e.onabort=o,e.onerror=o}))}))}function c(n){return t(this,void 0,void 0,(function*(){return new Promise((function(t,o){const e=document.createElement("canvas"),i=e.getContext("2d");if(i){const{width:r,height:c}=n;e.width=r,e.height=c,i.drawImage(n,0,0,r,c),e.toBlob((function(n){n?t(n):o("Cannot get blob from image element")}),"image/png",1)}}))}))}function u(n){return t(this,void 0,void 0,(function*(){const t=URL.createObjectURL(n),o=yield r(t);return yield c(o)}))}function a(n){return t(this,void 0,void 0,(function*(){const t={[n.type]:n},o=new ClipboardItem(t);yield navigator.clipboard.write([o])}))}return n.canCopyImagesToClipboard=function(){var n;const t="undefined"!=typeof fetch,o="undefined"!=typeof ClipboardItem,e=!!(null===(n=null===navigator||void 0===navigator?void 0:navigator.clipboard)||void 0===n?void 0:n.write);return t&&o&&e},n.convertBlobToPng=u,n.copyBlobToClipboard=a,n.copyImageToClipboard=function(n){return t(this,void 0,void 0,(function*(){const t=yield o(n);if(e(t)){const n=yield u(t);return yield a(n),t}if(i(t))return yield a(t),t;throw new Error("Cannot copy this type of image to clipboard")}))},n.createImageElement=r,n.getBlobFromImageElement=c,n.getBlobFromImageSource=o,n.isJpegBlob=e,n.isPngBlob=i,n.requestClipboardWritePermission=function(){var n;return t(this,void 0,void 0,(function*(){if(!(null===(n=null===navigator||void 0===navigator?void 0:navigator.permissions)||void 0===n?void 0:n.query))return!1;const{state:t}=yield navigator.permissions.query({name:"clipboard-write"});return"granted"===t}))},Object.defineProperty(n,"__esModule",{value:!0}),n}({});

dist/index.common.js

@@ -15,2 +15,8 @@ 'use strict';
 
+/**
+ * Gets a blob from an image source attribute using the Fetch API.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a image blob.
+ */
 function getBlobFromImageSource(imageSource) {
@@ -22,8 +28,26 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Checks if is a JPEG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a JPEG image or not.
+ */
 function isJpegBlob(blob) {
     return blob.type.includes('jpeg');
 }
+/**
+ * Checks if is a PNG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a PNG image or not.
+ */
 function isPngBlob(blob) {
     return blob.type.includes('png');
 }
+/**
+ * Created an image element for a given image source attribute.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<HTMLImageElement>} A promise that resolves to an image element. Rejects the promise if cannot create an image element.
+ */
 function createImageElement(imageSource) {
@@ -44,2 +68,8 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Gets a blob from an image element.
+ *
+ * @param {HTMLImageElement} imageElement An image element
+ * @returns {Promise<Blob>} A Promise that resolves to a image blob. Rejects the promise if cannot get a blob from the image element.
+ */
 function getBlobFromImageElement(imageElement) {
@@ -65,2 +95,8 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Converts a JPEG image blob to PNG.
+ *
+ * @param {Blob} imageBlob JPEG blob that will be converted to PNG.
+ * @returns {Promise<Blob>} A Promise that resolves to a PNG image blob. Rejects the promise if cannot create an image element or if cannot get a blob from the image element.
+ */
 function convertBlobToPng(imageBlob) {
@@ -73,2 +109,9 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Copies a blob to user's clipboard.
+ *
+ * Throws an error if cannot write on the user's clipboard.
+ *
+ * @param {Blob} blob Blob to be copied.
+ */
 function copyBlobToClipboard(blob) {
@@ -81,2 +124,13 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Copies a PNG or JPEG image to clipboard.
+ *
+ * This function downloads the image to copy with it's original dimensions.
+ *
+ * - If the image is JPEG it will be converted automatically to PNG and then copied.
+ * - If the image is not PNG or JPEG an error will be thrown.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a blob. Generally you don't need to use the returned blob for nothing.
+ */
 function copyImageToClipboard(imageSource) {
@@ -97,2 +151,12 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Requests the permission to write data on the user's clipboard.
+ *
+ * Reasons why you generally don't need to use this function:
+ *
+ * - The Permission to write data on the clipboard is automatically granted to pages when they are in the browser active tab.
+ * - If the browser has not implemented the Permissions API yet, this function will return false.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves to a boolean indicating if the permission was granted or not.
+ */
 function requestClipboardWritePermission() {
@@ -109,2 +173,7 @@ var _a;
 }
+/**
+ * Checks if can copy images to the clipboard using the Fetch API and the Clipboard API.
+ *
+ * @returns {Boolean} A boolean indicating if can copy or not.
+ */
 function canCopyImagesToClipboard() {
@@ -111,0 +180,0 @@ var _a;

dist/index.d.ts

@@ -0,10 +1,79 @@
+/**
+ * Gets a blob from an image source attribute using the Fetch API.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a image blob.
+ */
 export declare function getBlobFromImageSource(imageSource: string): Promise<Blob>;
+/**
+ * Checks if is a JPEG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a JPEG image or not.
+ */
 export declare function isJpegBlob(blob: Blob): boolean;
+/**
+ * Checks if is a PNG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a PNG image or not.
+ */
 export declare function isPngBlob(blob: Blob): boolean;
+/**
+ * Created an image element for a given image source attribute.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<HTMLImageElement>} A promise that resolves to an image element. Rejects the promise if cannot create an image element.
+ */
 export declare function createImageElement(imageSource: string): Promise<HTMLImageElement>;
+/**
+ * Gets a blob from an image element.
+ *
+ * @param {HTMLImageElement} imageElement An image element
+ * @returns {Promise<Blob>} A Promise that resolves to a image blob. Rejects the promise if cannot get a blob from the image element.
+ */
 export declare function getBlobFromImageElement(imageElement: HTMLImageElement): Promise<Blob>;
+/**
+ * Converts a JPEG image blob to PNG.
+ *
+ * @param {Blob} imageBlob JPEG blob that will be converted to PNG.
+ * @returns {Promise<Blob>} A Promise that resolves to a PNG image blob. Rejects the promise if cannot create an image element or if cannot get a blob from the image element.
+ */
 export declare function convertBlobToPng(imageBlob: Blob): Promise<Blob>;
+/**
+ * Copies a blob to user's clipboard.
+ *
+ * Throws an error if cannot write on the user's clipboard.
+ *
+ * @param {Blob} blob Blob to be copied.
+ */
 export declare function copyBlobToClipboard(blob: Blob): Promise<void>;
+/**
+ * Copies a PNG or JPEG image to clipboard.
+ *
+ * This function downloads the image to copy with it's original dimensions.
+ *
+ * - If the image is JPEG it will be converted automatically to PNG and then copied.
+ * - If the image is not PNG or JPEG an error will be thrown.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a blob. Generally you don't need to use the returned blob for nothing.
+ */
 export declare function copyImageToClipboard(imageSource: string): Promise<Blob>;
+/**
+ * Requests the permission to write data on the user's clipboard.
+ *
+ * Reasons why you generally don't need to use this function:
+ *
+ * - The Permission to write data on the clipboard is automatically granted to pages when they are in the browser active tab.
+ * - If the browser has not implemented the Permissions API yet, this function will return false.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves to a boolean indicating if the permission was granted or not.
+ */
 export declare function requestClipboardWritePermission(): Promise<boolean>;
+/**
+ * Checks if can copy images to the clipboard using the Fetch API and the Clipboard API.
+ *
+ * @returns {Boolean} A boolean indicating if can copy or not.
+ */
 export declare function canCopyImagesToClipboard(): boolean;

dist/index.js

@@ -11,2 +11,8 @@ function __awaiter(thisArg, _arguments, P, generator) {
 
+/**
+ * Gets a blob from an image source attribute using the Fetch API.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a image blob.
+ */
 function getBlobFromImageSource(imageSource) {
@@ -18,8 +24,26 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Checks if is a JPEG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a JPEG image or not.
+ */
 function isJpegBlob(blob) {
     return blob.type.includes('jpeg');
 }
+/**
+ * Checks if is a PNG image blob.
+ *
+ * @param {Blob} blob A blob.
+ * @returns {boolean} A boolean indicating if the blob is a PNG image or not.
+ */
 function isPngBlob(blob) {
     return blob.type.includes('png');
 }
+/**
+ * Created an image element for a given image source attribute.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<HTMLImageElement>} A promise that resolves to an image element. Rejects the promise if cannot create an image element.
+ */
 function createImageElement(imageSource) {
@@ -40,2 +64,8 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Gets a blob from an image element.
+ *
+ * @param {HTMLImageElement} imageElement An image element
+ * @returns {Promise<Blob>} A Promise that resolves to a image blob. Rejects the promise if cannot get a blob from the image element.
+ */
 function getBlobFromImageElement(imageElement) {
@@ -61,2 +91,8 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Converts a JPEG image blob to PNG.
+ *
+ * @param {Blob} imageBlob JPEG blob that will be converted to PNG.
+ * @returns {Promise<Blob>} A Promise that resolves to a PNG image blob. Rejects the promise if cannot create an image element or if cannot get a blob from the image element.
+ */
 function convertBlobToPng(imageBlob) {
@@ -69,2 +105,9 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Copies a blob to user's clipboard.
+ *
+ * Throws an error if cannot write on the user's clipboard.
+ *
+ * @param {Blob} blob Blob to be copied.
+ */
 function copyBlobToClipboard(blob) {
@@ -77,2 +120,13 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Copies a PNG or JPEG image to clipboard.
+ *
+ * This function downloads the image to copy with it's original dimensions.
+ *
+ * - If the image is JPEG it will be converted automatically to PNG and then copied.
+ * - If the image is not PNG or JPEG an error will be thrown.
+ *
+ * @param {string} imageSource The image source attribute.
+ * @returns {Promise<Blob>} A promise that resolves to a blob. Generally you don't need to use the returned blob for nothing.
+ */
 function copyImageToClipboard(imageSource) {
@@ -93,2 +147,12 @@ return __awaiter(this, void 0, void 0, function* () {
 }
+/**
+ * Requests the permission to write data on the user's clipboard.
+ *
+ * Reasons why you generally don't need to use this function:
+ *
+ * - The Permission to write data on the clipboard is automatically granted to pages when they are in the browser active tab.
+ * - If the browser has not implemented the Permissions API yet, this function will return false.
+ *
+ * @returns {Promise<boolean>} A Promise that resolves to a boolean indicating if the permission was granted or not.
+ */
 function requestClipboardWritePermission() {
@@ -105,2 +169,7 @@ var _a;
 }
+/**
+ * Checks if can copy images to the clipboard using the Fetch API and the Clipboard API.
+ *
+ * @returns {Boolean} A boolean indicating if can copy or not.
+ */
 function canCopyImagesToClipboard() {
@@ -107,0 +176,0 @@ var _a;

package.json

 {
   "name": "copy-image-clipboard",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "main": "dist/index.js",
@@ -5,0 +5,0 @@ "module": "dist/index.js",

README.md

@@ -1,6 +0,10 @@
-<h1 style="text-align: center">
+<p align="center">
+  <img src="assets/Logo.png" alt="Copy Image Clipboard Logo" />
+</p>
+
+<h1 align="center">
   <span>Copy Image Clipboard</span>
 </h1>
 
-<p style="text-align: center">
+<p align="center">
   <a href="https://www.npmjs.com/package/copy-image-clipboard">
@@ -27,22 +31,20 @@ <img alt="NPM Version" src="https://img.shields.io/npm/v/copy-image-clipboard">
   <a href="https://www.npmjs.com/package/copy-image-clipboard?activeTab=dependencies">
-    <img alt="Dependencies" src="https://img.shields.io/david/LuanEdCosta/copy-image-clipboard">
+    <img alt="Dependencies" src="https://img.shields.io/librariesio/release/npm/copy-image-clipboard/2.0.1">
   </a>
 </p>
 
-Created with :heart: by Luan Eduardo da Costa | [Follow me on Linkedin](https://www.linkedin.com/in/luaneducosta/)
+<h5 align="center">
+    <a href="https://luanedcosta.github.io/copy-image-clipboard" target="_blank">👉 TEST IN YOUR BROWSER 👈</a>
+</h5>
 
+- :white_check_mark: Copy JPG or PNG images to clipboard easily.
+- :white_check_mark: It is a lightweight library with `0 dependencies`.
+- :white_check_mark: You can use with React, Vue, Angular or with any other framework.
+
 ---
 
-## :page_with_curl: About
+## :arrow_down: Installation
 
-This library allows you to **copy JPG and PNG images (only)** to clipboard easily. Can be used with React, Vue, Angular and other web frameworks.
+### Using a package manager
 
-It uses the new browser Clipboard API and has **no external dependencies**.
-
-:point_right: [CLICK HERE](https://luanedcosta.github.io/copy-image-clipboard/) to see the demo project in your browser.
-
-## :white_check_mark: Installation
-
-### Using **yarn**
-
 ```bash
@@ -52,4 +54,2 @@ yarn add copy-image-clipboard
 
-### Using **npm**
-
 ```bash
@@ -59,18 +59,12 @@ npm i copy-image-clipboard
 
-### Downloading The Source Code
+### Without a package manager
 
-1. Download [dist/index.browser.js](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist/index.browser.js) or other file from the [dist](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist) folder.
-2. Put wherever you want :smile:.
+Without a package manager you have to choose one of these:
 
-Abou the **dist** folder:
+<details>
+<summary>Use from a CDN Provider</summary>
+<br>
 
-- The **index.browser.js** file is minified to use in browsers and exposes everything from this library in a variable called **CopyImageClipboard**. Ex: `CopyImageClipboard.copyImageToClipboard('...')`.
-- The **index.js** file uses the ES Modules module format and is not minified.
-- The **index.common.js** file uses the CommonJs module format and is not minified.
-- The **index.d.ts** file contains TypeScript types.
+**jsDelivr**
 
-### Using From CDN Providers
-
-jsDelivr
-
 ```javascript
@@ -80,2 +74,58 @@ <script src="https://cdn.jsdelivr.net/npm/copy-image-clipboard/dist/index.browser.js"></script>
 
+With a CDN Provider you will be using the [dist/index.browser.js](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist/index.browser.js) file. _See more about this file below_.
+
+---
+
+</details>
+
+<details>
+<summary>Download the entire repository</summary>
+<br>
+
+- Use `degit` to download this repository without the git history:
+
+```
+npx degit LuanEdCosta/copy-image-clipboard
+```
+
+- Download a zipped file on GitHub:
+
+<img src="assets/DownloadRepository.png" alt="Download the entire repository" />
+
+After downloading the repository, you can use a file from the [dist folder](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist) in your code. _See more about the dist folder files below_.
+
+---
+
+</details>
+
+<details>
+<summary>Download a file from the dist folder</summary>
+<br>
+
+Open the [dist folder](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist) and choose one of these files to download:
+
+- [dist/index.browser.js](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist/index.browser.js)
+- [dist/index.common.js](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist/index.common.js)
+- [dist/index.js](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist/index.js)
+
+_See more about these files below._
+
+---
+
+</details>
+
+#### About the [dist folder](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/dist)
+
+- **index.browser.js**
+  - Minified to use in browsers
+  - Exposes everything in a variable called **CopyImageClipboard**. e.g. `CopyImageClipboard.copyImageToClipboard('...')`.
+- **index.js**
+  - Uses ESM module format.
+  - Is not minified.
+- **index.common.js**
+  - Uses CommonJs module format.
+  - Is not minified.
+- **index.d.ts**
+  - Contains TypeScript types.
+
 ## :zap: Usage
@@ -114,3 +164,3 @@
 
-### Copy image rendered in the document
+### Copy the rendered image into the document
 
@@ -168,4 +218,6 @@ With this approach no HTTP request is necessary, but the image is copied with the image element dimensions in the document. If the image is 1000x1000 but is shown as 300x300, the copied image will be 300x300. Use `copyImageToClipboard` function to copy the image with its original dimensions.
 
-- React + TypeScript | [View Code](https://github.com/LuanEdCosta/copy-image-clipboard/tree/master/demo) - [View in Your Browser](https://luanedcosta.github.io/copy-image-clipboard/)
+- React + TypeScript - [Show me the code](https://github.com/LuanEdCosta/copy-image-clipboard/blob/master/demo/src/pages/Home/index.tsx) | [See it running in your browser](https://luanedcosta.github.io/copy-image-clipboard/)
 
+_You can contribute with more examples if you want_ :smile:
+
 ## :globe_with_meridians: Compatibility
@@ -188,13 +240,13 @@
 
-### For now you can copy only JPG and PNG images
+- **For now you can copy only JPG and PNG images**
 
-Other image types are not supported. If you try to copy other type an error will be thrown.
+  Other image types are not supported. If you try to copy other type an error will be thrown.
 
-### This library only works in pages with HTTPS
+- **This library only works in pages with HTTPS**
 
-This limitation was defined by the browsers due to security risks involved when dealing with the user's clipboard.
+  This limitation was defined by the browsers due to security risks involved when dealing with the user's clipboard.
 
-### You can only copy an image in the user's active tab/document
+- **You can only copy an image in the user's active tab/document**
 
-If the user is navigating in another tab and the copy function is called, an error will be thrown.
+  If the user is navigating in another tab and the copy function is called, an error will be thrown.
 
@@ -207,3 +259,2 @@ ## :handshake: Contribution
 
-- Take a look at the [Projects Tab](https://github.com/LuanEdCosta/copy-image-clipboard/projects) on GitHub to see some tasks that need to be done.
 - [Create an issue](https://github.com/LuanEdCosta/copy-image-clipboard/issues) to suggest an improvement or to describe a bug.
@@ -210,0 +261,0 @@ - Read the [Contribution Guide](https://github.com/LuanEdCosta/copy-image-clipboard/blob/master/CONTRIBUTING.md) to see how to contribute with code.

No alert changes

Improved metrics

Total package byte prevSize

34702

increased by36.48%

Lines of code

446

increased by86.61%

Number of lines in readme file

258

increased by24.64%

No dependency changes