@ngockhoi96/ctc 0.1.0

package/dist/index-CHCHjqWe.d.cts

@@ -0,0 +1,193 @@
+//#region src/lib/types.d.ts
+/**
+* Error codes for browser utility operations.
+*/
+type ErrorCode = "CLIPBOARD_NOT_SUPPORTED" | "CLIPBOARD_PERMISSION_DENIED" | "CLIPBOARD_WRITE_FAILED" | "CLIPBOARD_READ_FAILED" | "INSECURE_CONTEXT";
+/**
+* Structured error for browser utility operations.
+*
+* All clipboard functions accept an optional `onError` callback
+* that receives this type with a specific error code.
+*/
+interface BrowserUtilsError {
+  code: ErrorCode;
+  message: string;
+  cause?: unknown;
+}
+/**
+* Callback invoked when a browser utility operation fails.
+*
+* @param error - Structured error with code and message
+*/
+type OnErrorCallback = (error: BrowserUtilsError) => void;
+//#endregion
+//#region src/clipboard/types.d.ts
+/**
+* Options for clipboard operations.
+*/
+interface ClipboardOptions {
+  /**
+  * Callback invoked when the clipboard operation fails.
+  * Receives a structured error with a specific error code.
+  */
+  onError?: OnErrorCallback | undefined;
+}
+//#endregion
+//#region src/clipboard/copy.d.ts
+/**
+* Copy text to the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost) and must be called from
+* within a user gesture handler (click, keydown, etc.).
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* **User gesture requirement:** Must be called synchronously within a user
+* gesture handler. Programmatic calls from timers or microtasks will be
+* rejected by the browser with `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Secure context:** Returns `false` on HTTP pages with `INSECURE_CONTEXT`
+* error code. Use `copyToClipboardLegacy()` for HTTP environments.
+*
+* **Safari:** Calling any async operation before `writeText()` in the same
+* microtask may break Safari's user activation window. Keep the call
+* synchronous within the click handler.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const success = await copyToClipboard('Hello, world!')
+*   if (!success) {
+*     showError('Copy failed — check HTTPS and permissions')
+*   }
+* })
+* ```
+*/
+declare function copyToClipboard(text: string, options?: ClipboardOptions): Promise<boolean>;
+//#endregion
+//#region src/clipboard/detect.d.ts
+/**
+* Check if the Clipboard API is available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.writeText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the Clipboard API is absent.
+*
+* @returns `true` if clipboard write operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard access. Permission denial is surfaced at call
+* time via the `CLIPBOARD_PERMISSION_DENIED` error code on `copyToClipboard`.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   copyToClipboardLegacy(text)
+* }
+* ```
+*/
+declare function isClipboardSupported(): boolean;
+/**
+* Check if clipboard read operations are available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.readText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the read API is absent.
+*
+* @returns `true` if clipboard read operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard read access. Permission denial is surfaced at
+* call time via the `CLIPBOARD_PERMISSION_DENIED` error code on `readFromClipboard`.
+*
+* Firefox does not support the Permissions API `clipboard-read` query. This
+* function uses synchronous feature detection only — no async permission
+* queries are performed.
+*
+* @example
+* ```ts
+* if (isClipboardReadSupported()) {
+*   const text = await readFromClipboard()
+* }
+* ```
+*/
+declare function isClipboardReadSupported(): boolean;
+//#endregion
+//#region src/clipboard/fallback.d.ts
+/**
+* Copy text to the clipboard using the legacy `document.execCommand` API.
+*
+* Use this function when the modern Clipboard API is unavailable — for
+* example, on HTTP pages (non-HTTPS) or in browsers that do not support
+* `navigator.clipboard`. For HTTPS pages, prefer `copyToClipboard()`.
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* This function uses the deprecated `document.execCommand('copy')` API,
+* which is synchronous and text-only. It temporarily creates and removes a
+* textarea element in the DOM to perform the copy operation.
+*
+* **No secure context requirement:** This function works on HTTP pages.
+* This is by design — it exists for environments where `copyToClipboard()`
+* is unavailable due to missing secure context.
+*
+* **iOS Safari:** `execCommand` copy is not reliably supported on iOS.
+* This function may return `false` on iOS Safari without a usable fallback.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   const success = copyToClipboardLegacy(text)
+*   if (!success) {
+*     showManualCopyInstructions()
+*   }
+* }
+* ```
+*/
+declare function copyToClipboardLegacy(text: string, options?: ClipboardOptions): boolean;
+//#endregion
+//#region src/clipboard/read.d.ts
+/**
+* Read text from the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost). The browser may prompt
+* the user for permission on the first call.
+*
+* @param options - Optional configuration including `onError` callback
+* @returns The clipboard text on success, `null` on any failure (never throws)
+*
+* @remarks
+* **Permission prompt:** Chrome prompts for `clipboard-read` permission on
+* the first call. Firefox and Safari show a system-level paste prompt.
+* Permission denial is reported via `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Non-text content:** If the clipboard contains only non-text content
+* (e.g., an image), the browser throws `NotFoundError` which is reported
+* as `CLIPBOARD_READ_FAILED`.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const text = await readFromClipboard()
+*   if (text !== null) {
+*     input.value = text
+*   }
+* })
+* ```
+*/
+declare function readFromClipboard(options?: ClipboardOptions): Promise<string | null>;
+//#endregion
+export { copyToClipboard as a, ErrorCode as c, isClipboardSupported as i, OnErrorCallback as l, copyToClipboardLegacy as n, ClipboardOptions as o, isClipboardReadSupported as r, BrowserUtilsError as s, readFromClipboard as t };
+//# sourceMappingURL=index-CHCHjqWe.d.cts.map

package/dist/index.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_clipboard = require("./clipboard-Bs9DV14p.cjs");
+exports.copyToClipboard = require_clipboard.copyToClipboard;
+exports.copyToClipboardLegacy = require_clipboard.copyToClipboardLegacy;
+exports.isClipboardReadSupported = require_clipboard.isClipboardReadSupported;
+exports.isClipboardSupported = require_clipboard.isClipboardSupported;
+exports.readFromClipboard = require_clipboard.readFromClipboard;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { a as copyToClipboard, c as ErrorCode, i as isClipboardSupported, l as OnErrorCallback, n as copyToClipboardLegacy, o as ClipboardOptions, r as isClipboardReadSupported, s as BrowserUtilsError, t as readFromClipboard } from "./index-CHCHjqWe.cjs";
+export { type BrowserUtilsError, type ClipboardOptions, type ErrorCode, type OnErrorCallback, copyToClipboard, copyToClipboardLegacy, isClipboardReadSupported, isClipboardSupported, readFromClipboard };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as copyToClipboard, c as ErrorCode, i as isClipboardSupported, l as OnErrorCallback, n as copyToClipboardLegacy, o as ClipboardOptions, r as isClipboardReadSupported, s as BrowserUtilsError, t as readFromClipboard } from "./index-B7FFRy7e.mjs";
+export { type BrowserUtilsError, type ClipboardOptions, type ErrorCode, type OnErrorCallback, copyToClipboard, copyToClipboardLegacy, isClipboardReadSupported, isClipboardSupported, readFromClipboard };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as copyToClipboard, i as isClipboardSupported, n as copyToClipboardLegacy, r as isClipboardReadSupported, t as readFromClipboard } from "./clipboard-OTP55cvN.mjs";
+export { copyToClipboard, copyToClipboardLegacy, isClipboardReadSupported, isClipboardSupported, readFromClipboard };

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "@ngockhoi96/ctc",
+	"version": "0.1.0",
+	"license": "MIT",
+	"type": "module",
+	"description": "Modular, tree-shakeable browser utilities library",
+	"sideEffects": false,
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"lint": "biome check",
+		"lint:fix": "biome check --fix",
+		"format": "biome format --write",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:e2e": "playwright test",
+		"size": "size-limit",
+		"validate": "publint && attw --pack",
+		"setup": "lefthook install",
+		"changeset": "changeset"
+	},
+	"files": [
+		"dist"
+	],
+	"size-limit": [
+		{
+			"path": "dist/index.mjs",
+			"limit": "1 KB"
+		},
+		{
+			"path": "dist/clipboard/index.mjs",
+			"limit": "1 KB"
+		}
+	],
+	"devDependencies": {
+		"@arethetypeswrong/cli": "0.18.2",
+		"@biomejs/biome": "2.4.10",
+		"@changesets/changelog-github": "0.6.0",
+		"@changesets/cli": "2.30.0",
+		"@commitlint/cli": "20.5.0",
+		"@commitlint/config-conventional": "20.5.0",
+		"@playwright/test": "^1.59.1",
+		"@size-limit/file": "12.0.1",
+		"@types/node": "^25.6.0",
+		"@vitest/coverage-v8": "4.1.3",
+		"http-server": "^14.1.1",
+		"lefthook": "2.1.5",
+		"publint": "0.3.18",
+		"size-limit": "12.0.1",
+		"tsdown": "0.21.7",
+		"typescript": "6.0.2",
+		"vitest": "4.1.3"
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.cts",
+	"typesVersions": {
+		"*": {
+			"clipboard": [
+				"./dist/clipboard/index.d.cts"
+			]
+		}
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		},
+		"./clipboard": {
+			"import": "./dist/clipboard/index.mjs",
+			"require": "./dist/clipboard/index.cjs"
+		},
+		"./package.json": "./package.json"
+	}
+}