lite-clipboard 0.1.0

package/.github/ workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # ─── Build ───────────────────────────────────────────
+      - name: Build
+        run: pnpm build
+
+      # ─── Quality checks ──────────────────────────────────
+      - name: Type check
+        run: pnpm test:types
+
+      - name: Lint
+        run: pnpm test:lint
+
+      - name: Size check
+        run: pnpm test:size
+
+      - name: Tests
+        run: pnpm test:coverage
+
+      # ─── Publish ────────────────────────────────────────
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matias Fandiño
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# lite-clipboard
+
+A tiny (600 bytes) clipboard library for React/Vue/Svelte 
+with a framework-agnostic core. No dependencies. TypeScript native.
+
+**Target: <600 bytes gzipped**
+
+## Philosophy
+
+lite-clipboard is designed as a **framework-agnostic** library:
+
+- **Core** (`core.ts`): Pure logic with zero framework imports — works anywhere
+- **Adapters** (`adapters/`): Thin wrapper for each framework (React, Vue, Svelte...)
+- Adding a new framework = one new file in `adapters/`
+
+The architecture is inspired by [nanostores](https://github.com/nanostores/nanostores) — the same logic can be wrapped for Vue, Svelte, Solid, or any framework.
+
+**Currently supported:** React 18+
+
+**Future plans:** Vue composable, Svelte store, Solid signals.
+
+## Features
+
+- Zero external dependencies
+- Tiny footprint (<600 bytes gzipped)
+- Full TypeScript support
+- Tree-shakeable
+- SSR-safe
+- React hook included
+- Framework-agnostic core (add your own wrapper!)
+
+## Install
+
+npm install lite-clipboard
+
+> lite-clipboard is fully tree-shakeable. Import only what you need
+> and your bundler will eliminate the rest.
+
+## Framework support
+
+| Framework | Import | Status |
+|---|---|---|
+| Vanilla JS | `import { copyToClipboard } from 'lite-clipboard'` | ✅ stable |
+| React | `import { useClipboard } from 'lite-clipboard/react'` | ✅ stable |
+| Vue | `import { useClipboard } from 'lite-clipboard/vue'` | 🔜 coming soon |
+| Svelte | `import { useClipboard } from 'lite-clipboard/svelte'` | 🔜 coming soon |
+
+## Usage
+
+### Default (React)
+
+import { useClipboard } from 'lite-clipboard'
+
+### Framework-specific (tree-shakeable)
+
+import { useClipboard } from 'lite-clipboard/react'
+
+### Vanilla JS / Framework agnostic
+
+import { copyToClipboard, formatData, isSupported } from 'lite-clipboard'
+
+### Core (Framework-Agnostic)
+
+The core module works anywhere — browser, Node.js (with clipboard polyfill), or any framework.
+
+```typescript
+import { isSupported, copyToClipboard, formatData } from 'lite-clipboard';
+
+// Check if clipboard API is available
+if (isSupported()) {
+  // Copy string
+  await copyToClipboard('Hello!');
+
+  // Copy JSON (auto-formatted as pretty JSON)
+  await copyToClipboard({ type: 'json', value: { name: 'test' } });
+
+  // Copy code
+  await copyToClipboard({ type: 'code', value: 'const x = 1', language: 'js' });
+}
+
+// Format without copying
+const text = formatData({ type: 'json', value: { foo: 'bar' } });
+// → "{\n  \"foo\": \"bar\"\n}"
+```
+
+### React Hook
+
+```tsx
+import { useClipboard } from 'lite-clipboard';
+
+function CopyButton({ text }) {
+  const { copied, copy } = useClipboard();
+
+  return (
+    <button onClick={() => copy(text)}>
+      {copied ? 'Copied!' : 'Copy'}
+    </button>
+  );
+}
+```
+
+#### With Callbacks
+
+```tsx
+import { useClipboard } from 'lite-clipboard';
+
+function CopyButton({ text }) {
+  const { copy } = useClipboard({
+    onSuccess: () => console.log('Copied!'),
+    onError: (err) => console.error('Failed:', err),
+  });
+
+  return <button onClick={() => copy(text)}>Copy</button>;
+}
+```
+
+#### With Auto-Reset
+
+```tsx
+import { useClipboard } from 'lite-clipboard';
+
+function CopyButton({ text }) {
+  // Auto-reset copied state after 2 seconds (default)
+  const { copied, copy } = useClipboard({ timeout: 2000 });
+
+  return <button onClick={() => copy(text)}>{copied ? 'Copied!' : 'Copy'}</button>;
+}
+```
+
+## API
+
+### CopyData Type
+
+```typescript
+type CopyData =
+  | string
+  | { type: 'json'; value: unknown }
+  | { type: 'code'; value: string; language: string };
+```
+
+### Core Functions
+
+| Function | Type | Description |
+|----------|------|-------------|
+| `isSupported()` | `() => boolean` | Check if Clipboard API is available (SSR-safe) |
+| `copyToClipboard(data)` | `(data: CopyData) => Promise<void>` | Copy to clipboard |
+| `formatData(data)` | `(data: CopyData) => string` | Format data without copying |
+| `copy` | alias for `copyToClipboard` | Shorthand |
+
+### React Hook
+
+```typescript
+interface UseClipboardOptions {
+  timeout?: number;        // Auto-reset delay in ms (default: 2000)
+  onSuccess?: () => void; // Called on successful copy
+  onError?: (error: string) => void; // Called on error
+}
+
+interface UseClipboardReturn {
+  copied: boolean;         // Current copied state
+  error: string | null;   // Current error message
+  supported: boolean;      // Clipboard API availability
+  copy: (data: CopyData) => Promise<void>;
+}
+```
+
+## Bundle Size
+
+| Module | Gzipped |
+|--------|---------|
+| Core utilities | ~166 bytes |
+| React hook | ~342 bytes |
+| **Hook target** | **<600 bytes** ✅ |
+
+## Browser Support
+
+Requires `navigator.clipboard` API:
+
+- Chrome 
+- Firefox 
+- Safari
+- Edge
+
+## Contributing
+
+The core is intentionally minimal. Want to add Vue or Svelte support? The core API is designed to be wrapped easily:
+
+```typescript
+// Example: Your own Vue composable
+import { copyToClipboard, isSupported } from 'lite-clipboard';
+
+export function useClipboard() {
+  return {
+    copy: copyToClipboard,
+    supported: isSupported(),
+  };
+}
+```
+
+## License
+
+MIT

package/dist/adapters/react.js

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { copyToClipboard, isSupported } from '../core.js';
+export function useClipboard(options = {}) {
+    const { onError, onSuccess, timeout = 2000 } = options;
+    const supported = isSupported();
+    const [copied, setCopied] = useState(false);
+    const [error, setError] = useState(null);
+    const timerRef = useRef(null);
+    const handleCopy = useCallback(async (data) => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        if (!supported) {
+            const message = 'Clipboard API not supported';
+            setError(message);
+            onError?.(message);
+            return;
+        }
+        try {
+            await copyToClipboard(data);
+            setCopied(true);
+            setError(null);
+            onSuccess?.();
+            timerRef.current = setTimeout(() => {
+                setCopied(false);
+            }, timeout);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            setError(message);
+            onError?.(message);
+        }
+    }, [onSuccess, onError, timeout, supported]);
+    useEffect(() => {
+        return () => {
+            if (timerRef.current) {
+                clearTimeout(timerRef.current);
+                timerRef.current = null;
+            }
+        };
+    }, []);
+    return {
+        copied,
+        copy: handleCopy,
+        error,
+        supported,
+    };
+}

package/dist/core.js

@@ -0,0 +1,20 @@
+export function isSupported() {
+    return typeof navigator !== 'undefined' && 'clipboard' in navigator;
+}
+export function formatData(data) {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (data.type === 'json') {
+        return JSON.stringify(data.value, null, 2);
+    }
+    return data.value;
+}
+export async function copyToClipboard(data) {
+    if (!isSupported()) {
+        throw new Error('Clipboard API not supported');
+    }
+    const text = formatData(data);
+    await navigator.clipboard.writeText(text);
+}
+export const copy = copyToClipboard;

package/dist/index.js

@@ -0,0 +1,2 @@
+export { useClipboard } from './adapters/react.js';
+export { copyToClipboard, formatData, isSupported } from './core.js';

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "lite-clipboard",
+  "version": "0.1.0",
+  "description": "A tiny (600 bytes) clipboard hook for React/Vue/Svelte with a framework-agnostic core.",
+  "keywords": ["clipboard", "copy", "react", "hook", "javascript", "typescript"],
+  "author": "Matias Fandiño",
+  "license": "MIT",
+  "repository": "matifandy8/lite-clipboard",
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/adapters/react.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": "^20.0.0 || >=22.0.0"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/matiffar"
+    }
+  ],
+  "scripts": {
+    "build":         "tsc",
+    "test:lint":     "eslint .",
+    "test:coverage": "npx tsx core.test.ts && npx tsx adapters/react.test.ts",
+    "test:types":    "check-dts",
+    "test:size":     "size-limit",
+    "test":          "pnpm run /^test:/"
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "jsxSingleQuote": false,
+    "quoteProps": "consistent",
+    "semi": false,
+    "singleQuote": true,
+    "trailingComma": "none"
+  },
+  "size-limit": [
+    {
+      "name": "useClipboard",
+      "import": { "./dist/index.js": "{ useClipboard }" },
+      "limit": "600 B"
+    },
+    {
+      "name": "core",
+      "import": { "./dist/core.js": "{ copyToClipboard, formatData }" },
+      "limit": "300 B"
+    }
+  ],
+  "devDependencies": {
+    "@logux/eslint-config": "^57.0.2",
+    "@size-limit/preset-small-lib": "^12.0.1",
+    "@types/node": "^25.5.0",
+    "@types/react": "^18.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "better-node-test": "^0.8.3",
+    "check-dts": "^0.9.0",
+    "clean-publish": "^6.0.3",
+    "eslint": "^10.0.3",
+    "size-limit": "^12.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "clean-publish": {
+    "cleanDocs": true
+  }
+}