jg-clipboard 0.1.0 → 0.1.1

package/API.md

@@ -1,6 +1,6 @@
 # <a id="api-reference"></a>jg-clipboard API reference
 
-Every export of `jg-clipboard@0.1.0`, 10 in all, with its signature, its errors, and an example. It's generated from the package's TSDoc.
+Every export of `jg-clipboard@0.1.1`, 10 in all, with its signature, its errors, and an example. It's generated from the package's TSDoc.
 
 - Functions: [`copyHtml`](#api-copyHtml), [`copyImage`](#api-copyImage), [`copyText`](#api-copyText), [`getClipboardSupport`](#api-getClipboardSupport), [`readClipboard`](#api-readClipboard), [`readText`](#api-readText)
 - Constants: [`ERRORS`](#api-ERRORS)

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1
+
+### Added
+
+- `RECIPES.md`, patterns for apps that use the package: a copy button that explains a refusal, and a paste button for text or an image. Each block is typechecked against the release.
+
 ## 0.1.0
 
 The first release.

package/README.md

@@ -91,6 +91,8 @@ Every failure is an `Exception` with one of these codes, and the browser's error
 
 The full API reference ships in the package as `API.md`, generated from its TSDoc for the installed version, and is at https://jg-packages.jesusgraterol.dev/packages/jg-clipboard/.
 
+Recipes for common jobs ship as `RECIPES.md`, with every block typechecked against the release, and are at https://jg-packages.jesusgraterol.dev/packages/jg-clipboard/recipes/.
+
 ## License
 
 [MIT](https://github.com/jesusgraterol/jg-packages/blob/main/packages/jg-clipboard/LICENSE)

package/RECIPES.md

@@ -0,0 +1,107 @@
+# jg-clipboard recipes
+
+Patterns for copy and paste buttons that work across browsers, and say what to do when the browser refuses.
+
+## A copy button that explains a refusal
+
+Use this for a button that copies a code snippet, a share link, or a key. Browsers refuse a copy for several reasons, and jg-clipboard names each one with a code, so the message can tell the person what to do next, and how to get the text another way:
+
+```ts
+import { copyText, ERRORS } from 'jg-clipboard';
+import { hasErrorCode } from 'jg-exception';
+
+// the element whose text the button copies
+declare const snippet: HTMLElement;
+
+// a status line, such as an element with role="status", so screen readers announce the outcome
+declare const copyStatus: HTMLElement;
+
+// says what to do after a copy failed, so the text can still be copied by hand
+const describeCopyFailure = (error: unknown): string => {
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_PERMISSION_DENIED)) {
+    return 'Your browser blocked copying. Select the text and copy it manually.';
+  }
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_NO_USER_GESTURE)) {
+    return 'Your browser only copies right after a click. Click Copy again.';
+  }
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_NOT_FOCUSED)) {
+    return 'Copying needs this tab to be in focus. Click the page, then click Copy again.';
+  }
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_UNSUPPORTED)) {
+    return "This browser can't copy from this page. Select the text and copy it manually.";
+  }
+  return 'Copying failed. Select the text and copy it manually.';
+};
+
+button.addEventListener('click', async () => {
+  // cleared first, so an earlier outcome never shows during this attempt
+  copyStatus.textContent = '';
+  try {
+    // nothing awaits before copyText, so the browser still sees the click
+    await copyText(snippet.textContent ?? '');
+    copyStatus.textContent = 'Copied';
+  } catch (error) {
+    copyStatus.textContent = describeCopyFailure(error);
+  }
+});
+```
+
+`CLIPBOARD_WRITE_FAILED`, and anything unexpected, gets the general message. A `CLIPBOARD_PERMISSION_DENIED` error's `data.permission` holds the Permissions API's state, or `null` where the browser can't say; `'denied'` means the site's settings block the clipboard, which no second click fixes. To hide a button that can never work, check `getClipboardSupport().copyText` first, and keep the messages, because a supported copy can still be refused.
+
+## A paste button for text or an image
+
+Use this for a paste button in a composer that takes a screenshot or text. `readClipboard` reads every kind of content with one call, so the person sees one paste prompt at most, and returns an image as PNG, whatever type it was copied as. A browser that reads only text gets `readText` instead:
+
+```ts
+import { ERRORS, getClipboardSupport, readClipboard, readText } from 'jg-clipboard';
+import { hasErrorCode } from 'jg-exception';
+
+// a status line that says why a paste failed
+declare const pasteStatus: HTMLElement;
+
+const support = getClipboardSupport();
+
+// a browser that can't read the clipboard gets no button, and the keyboard still pastes there
+pasteButton.hidden = !support.read && !support.readText;
+
+// shows a pasted image, and releases the previous one, so repeated pastes don't keep it in memory
+const showImage = (image: Blob): void => {
+  if (preview.src.startsWith('blob:')) {
+    URL.revokeObjectURL(preview.src);
+  }
+  preview.src = URL.createObjectURL(image);
+};
+
+const describePasteFailure = (error: unknown): string => {
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_PERMISSION_DENIED)) {
+    return 'Your browser blocked pasting. Paste with Ctrl+V, or Cmd+V on a Mac, instead.';
+  }
+  if (hasErrorCode(error, ERRORS.CLIPBOARD_INVALID_IMAGE)) {
+    return "The copied image can't be read. Save it, then attach the file instead.";
+  }
+  return 'Pasting failed. Paste with Ctrl+V, or Cmd+V on a Mac, instead.';
+};
+
+pasteButton.addEventListener('click', async () => {
+  pasteStatus.textContent = '';
+  try {
+    // nothing awaits before the read, which Safari needs
+    if (!support.read) {
+      input.value = await readText();
+      return;
+    }
+    const { text, image } = await readClipboard();
+    if (image !== null) {
+      showImage(image);
+    } else if (text !== null) {
+      input.value = text;
+    } else {
+      pasteStatus.textContent = 'The clipboard holds no text or image to paste.';
+    }
+  } catch (error) {
+    pasteStatus.textContent = describePasteFailure(error);
+  }
+});
+```
+
+Safari and Firefox show a paste prompt on every read, and Chromium asks for the clipboard-read permission once, so read only when the person clicks. Which content wins when the clipboard holds both depends on the app: copied spreadsheet cells can come with a picture of the cells, so a field for tables would check `text` first. `CLIPBOARD_INVALID_IMAGE` means the clipboard held an image the browser can't decode, and `readClipboard` then fails as a whole, even when there was text too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jg-clipboard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Copy and read text, HTML, and images on the browser clipboard, with support detection and coded errors that say why the browser refused.",
   "author": "Jesus Graterol",
   "license": "MIT",
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "API.md"
+    "API.md",
+    "RECIPES.md"
   ],
   "sideEffects": false,
   "engines": {
@@ -42,7 +43,7 @@
     "clipboard-api"
   ],
   "dependencies": {
-    "jg-exception": "^1.1.0"
+    "jg-exception": "^1.2.0"
   },
   "devDependencies": {
     "@jg-packages/eslint-config": "0.0.0",