@symbiote-native/clipboard 0.0.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/clipboard",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "expo-clipboard wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters. Reads and writes clipboard text, URLs, and images, plus a clipboard-change listener.",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,112 @@
     "url": "https://github.com/OneEyed1366/symbiote-native/issues"
   },
   "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./svelte": {
+      "types": "./build/svelte/index.d.ts",
+      "default": "./build/svelte/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "expo-clipboard": "57.0.1",
+    "expo-modules-core": "57.0.5"
+  },
+  "peerDependencies": {
+    "@symbiote-native/angular": ">=0.6.2",
+    "@symbiote-native/engine": ">=0.1.7",
+    "@symbiote-native/react": ">=0.2.8",
+    "@symbiote-native/svelte": ">=0.1.0",
+    "@symbiote-native/vue": ">=0.3.8",
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/angular": "0.7.0",
+    "@symbiote-native/engine": "0.2.0",
+    "@symbiote-native/react": "0.3.0",
+    "@symbiote-native/svelte": "0.2.0",
+    "@symbiote-native/test-utils": "0.1.6",
+    "@symbiote-native/vue": "0.4.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
   }
 }

package/src/angular/index.ts

@@ -0,0 +1,8 @@
+// @symbiote-native/clipboard/angular: the Angular entry over the framework-agnostic core.
+// Unlike @symbiote-native/local-auth (all stateless functions, plain re-export), clipboard has
+// one listener-based piece — ClipboardService.connect() is the Angular-only lifecycle half; the
+// addClipboardListener subscription plumbing all lives in core, shared with React/Vue. Mirrors
+// @symbiote-native/sensors' AccelerometerService.
+
+export { ClipboardService } from './services/clipboard.service';
+export * from '../core';

package/src/angular/services/clipboard.service/index.ts

@@ -0,0 +1,35 @@
+import { effect, inject, Injectable, Injector, signal, type Signal } from '@angular/core';
+import { addClipboardListener, type IClipboardEvent } from '../../../core';
+
+// Angular twin of React's `useClipboard` hook and Vue's `useClipboard` composable. Angular has
+// no per-instance hook — state and lifecycle live in DI instead, so `connect()` stands in for
+// the hook's role: call it ONCE (typically from a component's field initializer, inside an
+// injection context).
+//
+//   readonly clipboardEvent = inject(ClipboardService).connect();
+//   // template: {{ clipboardEvent()?.contentTypes }}
+//
+// Mirrors AccelerometerService.connect() from @symbiote-native/sensors: the subscription doesn't
+// depend on anything the caller's own signals could change between renders, so a single
+// effect() that subscribes once and cleans up once is enough.
+@Injectable({ providedIn: 'root' })
+export class ClipboardService {
+  // Captured in the constructor (itself always run inside an injection context by Angular's own
+  // DI) so `connect()` can create an `effect()` even when called from plain field-initializer
+  // code that is not, on its own, an active injection context — mirrors AccelerometerService.
+  private readonly injector = inject(Injector);
+
+  connect(): Signal<IClipboardEvent | null> {
+    const event = signal<IClipboardEvent | null>(null);
+
+    effect(
+      onCleanup => {
+        const subscription = addClipboardListener(next => event.set(next));
+        onCleanup(() => subscription.remove());
+      },
+      { injector: this.injector },
+    );
+
+    return event.asReadonly();
+  }
+}

package/src/core/clipboard.ts

@@ -0,0 +1,168 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+
+import { CLIPBOARD_CHANGED_EVENT_NAME, expoClipboard } from './native-module';
+import type {
+  IClipboardEvent,
+  IClipboardImage,
+  IGetImageOptions,
+  IGetStringOptions,
+  ISetStringOptions,
+} from './types';
+
+// Matches the module name upstream's own Clipboard.ts passes to every UnavailabilityError.
+const NATIVE_MODULE_NAME = 'Clipboard';
+
+/**
+ * Gets the content of the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns an empty string.
+ * Due to iOS platform limitations, there is no way to distinguish between an empty clipboard
+ * and denied permission.
+ *
+ * @param options Options for the clipboard content to be retrieved.
+ * @returns A promise that resolves to the content of the clipboard, or an empty string if the
+ * clipboard is empty or permission was denied.
+ */
+export async function getStringAsync(options: IGetStringOptions = {}): Promise<string> {
+  if (!expoClipboard.getStringAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStringAsync');
+  }
+  return expoClipboard.getStringAsync(options);
+}
+
+/**
+ * Sets the content of the user's clipboard.
+ *
+ * @param text The string to save to the clipboard.
+ * @param options Options for the clipboard content to be set.
+ * @returns A promise that resolves to `true` once the string has been saved to the clipboard.
+ */
+export async function setStringAsync(
+  text: string,
+  options: ISetStringOptions = {},
+): Promise<boolean> {
+  if (!expoClipboard.setStringAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setStringAsync');
+  }
+  return expoClipboard.setStringAsync(text, options);
+}
+
+/**
+ * Returns whether the clipboard has text content. Returns `true` for both plain text and rich
+ * text (e.g. HTML).
+ */
+// DELIBERATE DIVERGENCE from expo: Clipboard.ts:57 declares this one plain `function`, not
+// `async` like its 8 siblings, so on a build without the native method the UnavailabilityError
+// escapes synchronously at the call site and `hasStringAsync().catch(handler)` never catches it.
+// Parity would hand callers a guard that fires differently from every other method in this API,
+// so we add `async` here instead of tagging it. Everything else stays a verbatim port.
+export async function hasStringAsync(): Promise<boolean> {
+  if (!expoClipboard.hasStringAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasStringAsync');
+  }
+  return expoClipboard.hasStringAsync();
+}
+
+/**
+ * Gets the URL from the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no URL in clipboard and denied
+ * permission.
+ * @platform ios
+ */
+export async function getUrlAsync(): Promise<string | null> {
+  if (!expoClipboard.getUrlAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getUrlAsync');
+  }
+  return expoClipboard.getUrlAsync();
+}
+
+/**
+ * Sets a URL in the user's clipboard. Behaves the same as `setStringAsync`, except that it sets
+ * the clipboard content type to be a URL, letting your app or other apps know that the clipboard
+ * contains a URL and behave accordingly.
+ * @platform ios
+ */
+export async function setUrlAsync(url: string): Promise<void> {
+  if (!expoClipboard.setUrlAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setUrlAsync');
+  }
+  return expoClipboard.setUrlAsync(url);
+}
+
+/**
+ * Returns whether the clipboard has URL content.
+ * @platform ios
+ */
+export async function hasUrlAsync(): Promise<boolean> {
+  if (!expoClipboard.hasUrlAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasUrlAsync');
+  }
+  return expoClipboard.hasUrlAsync();
+}
+
+/**
+ * Gets the image from the user's clipboard and returns it in the specified format.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no image in clipboard and denied
+ * permission.
+ *
+ * @param options Specifies the desired format of the image.
+ * @returns If there was an image in the clipboard, resolves to an `IClipboardImage` object
+ * containing the base64 string and metadata of the image. Otherwise resolves to `null` (this
+ * includes cases where permission was denied).
+ */
+export async function getImageAsync(options: IGetImageOptions): Promise<IClipboardImage | null> {
+  if (!expoClipboard.getImageAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getImageAsync');
+  }
+  return expoClipboard.getImageAsync(options);
+}
+
+/**
+ * Sets an image in the user's clipboard.
+ *
+ * @param base64Image Image encoded as a base64 string, without MIME type.
+ */
+export async function setImageAsync(base64Image: string): Promise<void> {
+  if (!expoClipboard.setImageAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setImageAsync');
+  }
+  return expoClipboard.setImageAsync(base64Image);
+}
+
+/**
+ * Returns whether the clipboard has image content.
+ */
+export async function hasImageAsync(): Promise<boolean> {
+  if (!expoClipboard.hasImageAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasImageAsync');
+  }
+  return expoClipboard.hasImageAsync();
+}
+
+/**
+ * Adds a listener that fires whenever the content of the user's clipboard changes. Kept here at
+ * the core level, framework-agnostic, exactly like `Accelerometer.addListener` lives in
+ * `@symbiote-native/sensors`' core — each adapter's `useClipboard` hook/composable/service wraps
+ * this in its own mount/unmount lifecycle rather than reimplementing the subscription.
+ *
+ * @param listener Callback invoked with an `IClipboardEvent` describing the new clipboard
+ * content types whenever the clipboard changes.
+ */
+export function addClipboardListener(
+  listener: (event: IClipboardEvent) => void,
+): EventSubscription {
+  return expoClipboard.addListener(CLIPBOARD_CHANGED_EVENT_NAME, listener);
+}
+
+/**
+ * Removes the listener added by `addClipboardListener`.
+ * @deprecated use `subscription.remove()` instead.
+ */
+export function removeClipboardListener(subscription: EventSubscription): void {
+  subscription.remove();
+}

package/src/core/index.ts

@@ -0,0 +1,23 @@
+export {
+  getStringAsync,
+  setStringAsync,
+  hasStringAsync,
+  getUrlAsync,
+  setUrlAsync,
+  hasUrlAsync,
+  getImageAsync,
+  setImageAsync,
+  hasImageAsync,
+  addClipboardListener,
+  removeClipboardListener,
+} from './clipboard';
+export {
+  ContentType,
+  StringFormat,
+  type IGetStringOptions,
+  type ISetStringOptions,
+  type IGetImageOptions,
+  type IClipboardImage,
+  type IClipboardEvent,
+} from './types';
+export type { EventSubscription } from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,42 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import type {
+  IClipboardEvent,
+  IClipboardImage,
+  IGetImageOptions,
+  IGetStringOptions,
+  ISetStringOptions,
+} from './types';
+
+const EXPO_CLIPBOARD_MODULE_NAME = 'ExpoClipboard';
+
+// The event name upstream's own ExpoClipboard.ts pairs with the native module's event map —
+// kept here, next to the module resolution, since core/clipboard.ts's addClipboardListener is
+// the only caller.
+export const CLIPBOARD_CHANGED_EVENT_NAME = 'onClipboardChanged';
+
+// addListener/removeAllListeners come from expo-modules-core's own NativeModule<Events> base
+// class (an EventEmitter) — always present, unlike the async methods below, each of which is
+// optional and checked at its own call site before throwing an UnavailabilityError, mirroring
+// @symbiote-native/local-auth's native-module.ts and upstream's own per-platform capability
+// checks (getUrlAsync/setUrlAsync/hasUrlAsync are iOS-only, hence optional there too).
+export type INativeClipboardModule = {
+  addListener(
+    eventName: typeof CLIPBOARD_CHANGED_EVENT_NAME,
+    listener: (event: IClipboardEvent) => void,
+  ): EventSubscription;
+  removeAllListeners(eventName: typeof CLIPBOARD_CHANGED_EVENT_NAME): void;
+  getStringAsync?(options?: IGetStringOptions): Promise<string>;
+  setStringAsync?(text: string, options?: ISetStringOptions): Promise<boolean>;
+  hasStringAsync?(): Promise<boolean>;
+  getUrlAsync?(): Promise<string | null>;
+  setUrlAsync?(url: string): Promise<void>;
+  hasUrlAsync?(): Promise<boolean>;
+  getImageAsync?(options: IGetImageOptions): Promise<IClipboardImage | null>;
+  setImageAsync?(base64Image: string): Promise<void>;
+  hasImageAsync?(): Promise<boolean>;
+};
+
+export const expoClipboard = requireNativeModule<INativeClipboardModule>(
+  EXPO_CLIPBOARD_MODULE_NAME,
+);

package/src/core/types.ts

@@ -0,0 +1,81 @@
+// Ported from expo-clipboard's own Clipboard.types.ts. ContentType and StringFormat are enums —
+// kept unprefixed, matching this repo's convention for enums (see AuthenticationType /
+// SecurityLevel in @symbiote-native/local-auth); the plain option/result shapes get this repo's
+// `I`-prefix convention for exported types. `ClipboardPasteButton`'s own types
+// (PasteEventPayload, TextPasteEvent, ImagePasteEvent, AcceptedContentType, CornerStyleType,
+// DisplayModeType) are intentionally not ported — that native paste-button view is out of scope
+// for this pass (see the package README).
+
+/**
+ * Type used to define what type of data is stored in the clipboard.
+ */
+export enum ContentType {
+  PLAIN_TEXT = 'plain-text',
+  HTML = 'html',
+  IMAGE = 'image',
+  /**
+   * @platform iOS
+   */
+  URL = 'url',
+}
+
+/**
+ * Type used to determine string format stored in the clipboard.
+ */
+export enum StringFormat {
+  PLAIN_TEXT = 'plainText',
+  HTML = 'html',
+}
+
+export type IGetStringOptions = {
+  /**
+   * The target format of the clipboard string to be converted to, if possible.
+   * @default StringFormat.PLAIN_TEXT
+   */
+  preferredFormat?: StringFormat;
+};
+
+export type ISetStringOptions = {
+  /**
+   * The input format of the provided string. Adjusting this option can help other applications
+   * interpret copied string properly.
+   * @default StringFormat.PLAIN_TEXT
+   */
+  inputFormat?: StringFormat;
+};
+
+export type IGetImageOptions = {
+  /**
+   * The format of the clipboard image to be converted to.
+   */
+  format: 'png' | 'jpeg';
+  /**
+   * Specify the quality of the returned image, between `0` and `1`. Defaults to `1` (highest
+   * quality). Applicable only when `format` is set to `jpeg`, ignored otherwise.
+   * @default 1
+   */
+  jpegQuality?: number;
+};
+
+export type IClipboardImage = {
+  /**
+   * A Base64-encoded string of the image data, already prepended with a
+   * `data:image/png;base64,` or `data:image/jpeg;base64,` prefix. Its format depends on the
+   * `format` option passed to `getImageAsync`.
+   */
+  data: string;
+  /**
+   * Dimensions (`width` and `height`) of the image pasted from clipboard.
+   */
+  size: {
+    width: number;
+    height: number;
+  };
+};
+
+export type IClipboardEvent = {
+  /**
+   * An array of content types that are available on the clipboard.
+   */
+  contentTypes: ContentType[];
+};

package/src/react/hooks/use-clipboard/index.ts

@@ -0,0 +1,17 @@
+// React lifecycle wiring over the framework-agnostic addClipboardListener subscription (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks and the shape of
+// @symbiote-native/sensors' useAccelerometer, adjusted for clipboard's single always-on
+// subscription (there is no per-call config like updateIntervalMs to resubscribe on).
+import { useEffect, useState } from 'react';
+import { addClipboardListener, type IClipboardEvent } from '../../../core';
+
+export function useClipboard(): IClipboardEvent | null {
+  const [event, setEvent] = useState<IClipboardEvent | null>(null);
+
+  useEffect(() => {
+    const subscription = addClipboardListener(setEvent);
+    return () => subscription.remove();
+  }, []);
+
+  return event;
+}

package/src/react/index.ts

@@ -0,0 +1,9 @@
+// @symbiote-native/clipboard/react: the React entry over the framework-agnostic core. Unlike
+// @symbiote-native/local-auth (all stateless functions, plain re-export), clipboard has one
+// listener-based piece — useClipboard wraps addClipboardListener with React's own lifecycle
+// (hooks/use-clipboard), mirroring the lifecycle-bucket naming convention of
+// adapters/react/src/hooks (never `composables`, that's Vue's term) and the shape of
+// @symbiote-native/sensors' useAccelerometer.
+
+export { useClipboard } from './hooks/use-clipboard';
+export * from '../core';

package/src/svelte/index.ts

@@ -0,0 +1,8 @@
+// @symbiote-native/clipboard/svelte: the Svelte entry over the framework-agnostic core. Unlike
+// @symbiote-native/local-auth (all stateless functions, plain re-export), clipboard has one
+// listener-based piece — useClipboard wires addClipboardListener's lifecycle onto a Svelte
+// `$effect` (runes/use-clipboard.svelte.ts), mirroring the lifecycle-bucket naming convention of
+// adapters/svelte/src/runes (never `hooks/`/`composables/`, those are React's and Vue's terms).
+
+export { useClipboard } from './runes/use-clipboard.svelte';
+export * from '../core';

package/src/svelte/runes/use-clipboard.svelte.ts

@@ -0,0 +1,33 @@
+// Svelte lifecycle wiring over the framework-agnostic addClipboardListener subscription (core/) —
+// the Svelte twin of vue/composables/use-clipboard and react/hooks/use-clipboard, adjusted for
+// clipboard's single always-on subscription (no per-call config to resubscribe on).
+//
+// `.svelte.ts` (not `.ts`): runes ($state/$effect) are only usable in a file with this extension
+// outside an actual `.svelte` component. `runes/` is Svelte's own term for the bucket React calls
+// `hooks/` and Vue calls `composables/` — see adapters/svelte/src/runes.
+//
+// Vue's onMounted/onUnmounted pair collapses into ONE `$effect` whose returned function is the
+// teardown. The effect only WRITES `event`, never reads it, so its dependency set stays empty: it
+// subscribes exactly once on mount and removes the subscription exactly once on unmount.
+//
+// Returns a boxed getter object, NOT a bare `$state`: Svelte 5 reactivity is lexically scoped to
+// the declaring module, so a raw `let x = $state(...)` handed out of a plain function arrives
+// dead at the caller. `.current` is the Svelte equivalent of unwrapping Vue's `Ref` via `.value`.
+import { addClipboardListener, type EventSubscription, type IClipboardEvent } from '../../core';
+
+export function useClipboard(): { readonly current: IClipboardEvent | null } {
+  let event = $state<IClipboardEvent | null>(null);
+
+  $effect(() => {
+    const subscription: EventSubscription = addClipboardListener(next => {
+      event = next;
+    });
+    return () => subscription.remove();
+  });
+
+  return {
+    get current(): IClipboardEvent | null {
+      return event;
+    },
+  };
+}

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,6 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program. adapters/svelte gets these for free because render.ts does a real value import from
+// 'svelte' (any file in a program importing a module loads its ambient globals for the whole
+// program); this package has no such import, so a triple-slash reference does the same job
+// explicitly rather than relying on an incidental side-effect.
+/// <reference types="svelte" />

package/src/vue/composables/use-clipboard/index.ts

@@ -0,0 +1,25 @@
+// Vue lifecycle wiring over the framework-agnostic addClipboardListener subscription (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/vue/src/composables and the
+// onMounted/onUnmounted shape of @symbiote-native/sensors' useAccelerometer composable, adjusted
+// for clipboard's single always-on subscription (no per-call config to resubscribe on).
+
+import { onMounted, onUnmounted, ref, type Ref } from '@vue/runtime-core';
+import { addClipboardListener, type EventSubscription, type IClipboardEvent } from '../../../core';
+
+export function useClipboard(): Ref<IClipboardEvent | null> {
+  // A plain ref: the value is a POJO clipboard event, not an engine node, so no shallowRef needed.
+  const event = ref<IClipboardEvent | null>(null);
+  let subscription: EventSubscription | undefined;
+
+  onMounted(() => {
+    subscription = addClipboardListener(next => {
+      event.value = next;
+    });
+  });
+
+  onUnmounted(() => {
+    subscription?.remove();
+  });
+
+  return event;
+}

package/src/vue/index.ts

@@ -0,0 +1,9 @@
+// @symbiote-native/clipboard/vue: the Vue entry over the framework-agnostic core. Unlike
+// @symbiote-native/local-auth (all stateless functions, plain re-export), clipboard has one
+// listener-based piece — useClipboard wires addClipboardListener's lifecycle onto Vue's own
+// onMounted/onUnmounted (composables/use-clipboard), mirroring the lifecycle-bucket naming
+// convention of adapters/vue/src/composables (never `hooks/`, that's React's term) and the
+// shape of @symbiote-native/sensors' useAccelerometer composable.
+
+export { useClipboard } from './composables/use-clipboard';
+export * from '../core';