@renegades/react-native-tickle 0.1.0

package/nitrogen/generated/shared/c++/HybridTickleSpec.hpp

@@ -0,0 +1,87 @@
+///
+/// HybridTickleSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `HapticEvent` to properly resolve imports.
+namespace margelo::nitro::tickle { struct HapticEvent; }
+// Forward declaration of `HapticCurve` to properly resolve imports.
+namespace margelo::nitro::tickle { struct HapticCurve; }
+// Forward declaration of `HapticImpactStyle` to properly resolve imports.
+namespace margelo::nitro::tickle { enum class HapticImpactStyle; }
+// Forward declaration of `HapticNotificationType` to properly resolve imports.
+namespace margelo::nitro::tickle { enum class HapticNotificationType; }
+
+#include "HapticEvent.hpp"
+#include <vector>
+#include "HapticCurve.hpp"
+#include <string>
+#include "HapticImpactStyle.hpp"
+#include "HapticNotificationType.hpp"
+
+namespace margelo::nitro::tickle {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `Tickle`
+   * Inherit this class to create instances of `HybridTickleSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridTickle: public HybridTickleSpec {
+   * public:
+   *   HybridTickle(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridTickleSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridTickleSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridTickleSpec() override = default;
+
+    public:
+      // Properties
+      
+
+    public:
+      // Methods
+      virtual void startHaptic(const std::vector<HapticEvent>& events, const std::vector<HapticCurve>& curves) = 0;
+      virtual void stopAllHaptics() = 0;
+      virtual void initializeEngine() = 0;
+      virtual void destroyEngine() = 0;
+      virtual void createContinuousPlayer(const std::string& playerId, double initialIntensity, double initialSharpness) = 0;
+      virtual void startContinuousPlayer(const std::string& playerId) = 0;
+      virtual void updateContinuousPlayer(const std::string& playerId, double intensityControl, double sharpnessControl) = 0;
+      virtual void stopContinuousPlayer(const std::string& playerId) = 0;
+      virtual void destroyContinuousPlayer(const std::string& playerId) = 0;
+      virtual void setHapticsEnabled(bool enabled) = 0;
+      virtual bool getHapticsEnabled() = 0;
+      virtual void triggerImpact(HapticImpactStyle style) = 0;
+      virtual void triggerNotification(HapticNotificationType type) = 0;
+      virtual void triggerSelection() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "Tickle";
+  };
+
+} // namespace margelo::nitro::tickle

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "@renegades/react-native-tickle",
+  "version": "0.1.0",
+  "description": "Build and fine-tune haptic patterns with real-time previews",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "nitrogen",
+    "nitro.json",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "postinstall": "bash scripts/postinstall.sh",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "nitrogen": "nitrogen",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Renegades-Studio/react-native-tickle.git"
+  },
+  "author": "Renegades <info@renegades.xyz> (https://renegades.xyz)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Renegades-Studio/react-native-tickle/issues"
+  },
+  "homepage": "https://github.com/Renegades-Studio/react-native-tickle#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/compat": "^1.3.2",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.35.0",
+    "@react-native/babel-preset": "0.83.0",
+    "@react-native/eslint-config": "0.83.0",
+    "@react-native/eslint-plugin": "^0.83.1",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "~19.1.10",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-jest": "^29.12.1",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-native": "^5.0.0",
+    "jest": "^29.7.0",
+    "lefthook": "^2.0.3",
+    "nitrogen": "^0.32.1",
+    "prettier": "^2.8.8",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-builder-bob": "^0.40.17",
+    "react-native-nitro-modules": "0.32.1",
+    "release-it": "^19.0.4",
+    "turbo": "^2.5.6",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "^0.32.0"
+  },
+  "packageManager": "bun@1.1.38",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "custom",
+        {
+          "script": "nitrogen",
+          "clean": "nitrogen/"
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "nitro-module",
+    "languages": "kotlin-swift",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.56.0"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: {},
+      android: {},
+    },
+  },
+};

package/src/Tickle.nitro.ts

@@ -0,0 +1,84 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+export type HapticEventType = 'transient' | 'continuous';
+export type HapticParameterType = 'intensity' | 'sharpness';
+
+// MARK: - System Haptic Types
+
+/**
+ * Feedback intensity styles for impact haptics.
+ * Maps to UIImpactFeedbackGenerator.FeedbackStyle on iOS.
+ */
+export type HapticImpactStyle = 'rigid' | 'heavy' | 'medium' | 'light' | 'soft';
+
+/**
+ * Notification feedback categories for alert-style haptics.
+ * Maps to UINotificationFeedbackGenerator.FeedbackType on iOS.
+ */
+export type HapticNotificationType = 'error' | 'success' | 'warning';
+
+export type HapticEventParameter = {
+  type: HapticParameterType;
+  value: number;
+};
+export type HapticCurveControlPoint = {
+  relativeTime: number;
+  value: number;
+};
+
+export type HapticEvent = {
+  type: HapticEventType;
+  parameters: HapticEventParameter[];
+  relativeTime: number;
+  duration?: number; // Optional for transient events
+};
+
+export type HapticCurve = {
+  type: HapticParameterType;
+  controlPoints: HapticCurveControlPoint[];
+  relativeTime: number;
+};
+
+export interface Tickle
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  startHaptic(events: HapticEvent[], curves: HapticCurve[]): void;
+  stopAllHaptics(): void;
+  initializeEngine(): void;
+  destroyEngine(): void;
+
+  createContinuousPlayer(
+    playerId: string,
+    initialIntensity: number,
+    initialSharpness: number
+  ): void;
+  startContinuousPlayer(playerId: string): void;
+  updateContinuousPlayer(
+    playerId: string,
+    intensityControl: number,
+    sharpnessControl: number
+  ): void;
+  stopContinuousPlayer(playerId: string): void;
+  destroyContinuousPlayer(playerId: string): void;
+
+  setHapticsEnabled(enabled: boolean): void;
+  getHapticsEnabled(): boolean;
+
+  // MARK: - System Haptics (Predefined OS-level feedback)
+
+  /**
+   * Triggers an impact haptic with the specified style.
+   * Simulates a physical collision feedback.
+   */
+  triggerImpact(style: HapticImpactStyle): void;
+
+  /**
+   * Triggers a notification-style haptic for alerts and status updates.
+   */
+  triggerNotification(type: HapticNotificationType): void;
+
+  /**
+   * Triggers a selection change haptic.
+   * Best used for picker wheels, toggles, and selection changes.
+   */
+  triggerSelection(): void;
+}

package/src/index.tsx

@@ -0,0 +1,306 @@
+import { useEffect, useState, useCallback } from 'react';
+import { AppState } from 'react-native';
+import { NitroModules } from 'react-native-nitro-modules';
+import type {
+  Tickle,
+  HapticCurve,
+  HapticEventParameter,
+  HapticParameterType,
+  HapticImpactStyle,
+  HapticNotificationType,
+} from './Tickle.nitro';
+
+export type TransientHapticEvent = {
+  type: 'transient';
+  parameters: HapticEventParameter[];
+  relativeTime: number;
+};
+
+export type ContinuousHapticEvent = {
+  type: 'continuous';
+  parameters: HapticEventParameter[];
+  relativeTime: number;
+  duration: number;
+};
+
+export type HapticEvent = TransientHapticEvent | ContinuousHapticEvent;
+
+const TickleHybridObject = NitroModules.createHybridObject<Tickle>('Tickle');
+
+const boxedTickle = NitroModules.box(TickleHybridObject);
+
+export function startHaptic(
+  events: HapticEvent[],
+  curves: HapticCurve[]
+): void {
+  'worklet';
+
+  return boxedTickle.unbox().startHaptic(events, curves);
+}
+
+export function stopAllHaptics(): void {
+  'worklet';
+
+  return boxedTickle.unbox().stopAllHaptics();
+}
+
+export function initializeEngine(): void {
+  'worklet';
+
+  return boxedTickle.unbox().initializeEngine();
+}
+
+export function destroyEngine(): void {
+  'worklet';
+
+  return boxedTickle.unbox().destroyEngine();
+}
+
+export function createContinuousPlayer(
+  playerId: string,
+  initialIntensity: number,
+  initialSharpness: number
+): void {
+  'worklet';
+
+  return boxedTickle
+    .unbox()
+    .createContinuousPlayer(playerId, initialIntensity, initialSharpness);
+}
+
+export function startContinuousPlayer(playerId: string): void {
+  'worklet';
+
+  return boxedTickle.unbox().startContinuousPlayer(playerId);
+}
+
+export function updateContinuousPlayer(
+  playerId: string,
+  intensityControl: number,
+  sharpnessControl: number
+): void {
+  'worklet';
+
+  return boxedTickle
+    .unbox()
+    .updateContinuousPlayer(playerId, intensityControl, sharpnessControl);
+}
+
+export function stopContinuousPlayer(playerId: string): void {
+  'worklet';
+  return boxedTickle.unbox().stopContinuousPlayer(playerId);
+}
+
+export function destroyContinuousPlayer(playerId: string): void {
+  'worklet';
+  return boxedTickle.unbox().destroyContinuousPlayer(playerId);
+}
+
+// MARK: - System Haptics (Predefined OS-level feedback)
+
+/**
+ * Triggers an impact haptic with the specified style.
+ * Simulates a physical collision feedback.
+ *
+ * @param style - The intensity style of the impact ('rigid' | 'heavy' | 'medium' | 'light' | 'soft')
+ *
+ * @example
+ * ```ts
+ * // Light tap for subtle UI feedback
+ * triggerImpact('light');
+ *
+ * // Heavy impact for significant actions
+ * triggerImpact('heavy');
+ * ```
+ */
+export function triggerImpact(style: HapticImpactStyle): void {
+  'worklet';
+  return boxedTickle.unbox().triggerImpact(style);
+}
+
+/**
+ * Triggers a notification-style haptic for alerts and status updates.
+ * Use this for communicating outcomes of actions to the user.
+ *
+ * @param type - The notification type ('error' | 'success' | 'warning')
+ *
+ * @example
+ * ```ts
+ * // Success feedback after completing an action
+ * triggerNotification('success');
+ *
+ * // Error feedback when something goes wrong
+ * triggerNotification('error');
+ * ```
+ */
+export function triggerNotification(type: HapticNotificationType): void {
+  'worklet';
+  return boxedTickle.unbox().triggerNotification(type);
+}
+
+/**
+ * Triggers a selection change haptic.
+ * Best used for picker wheels, toggles, and selection changes.
+ *
+ * @example
+ * ```ts
+ * // When user scrolls through picker options
+ * triggerSelection();
+ * ```
+ */
+export function triggerSelection(): void {
+  'worklet';
+  return boxedTickle.unbox().triggerSelection();
+}
+
+// MARK: - Global Haptics Enable/Disable
+
+/**
+ * Enable or disable haptics globally. This setting is persisted across app restarts.
+ * When disabled, all haptic functions become no-ops (no haptics will play).
+ * This does not affect engine initialization/destruction.
+ *
+ * @param enabled - Whether haptics should be enabled
+ */
+export function setHapticsEnabled(enabled: boolean): void {
+  'worklet';
+  return boxedTickle.unbox().setHapticsEnabled(enabled);
+}
+
+/**
+ * Get the current global haptics enabled state.
+ * Defaults to true if not previously set.
+ *
+ * @returns Whether haptics are currently enabled
+ */
+export function getHapticsEnabled(): boolean {
+  'worklet';
+  return boxedTickle.unbox().getHapticsEnabled();
+}
+
+/**
+ * Hook to manage the global haptics enabled state.
+ * Provides reactive state and a setter function.
+ *
+ * @returns [isEnabled, setEnabled] - Current state and setter function
+ *
+ * @example
+ * ```tsx
+ * function SettingsScreen() {
+ *   const [hapticsEnabled, setHapticsEnabled] = useHapticsEnabled();
+ *
+ *   return (
+ *     <Switch
+ *       value={hapticsEnabled}
+ *       onValueChange={setHapticsEnabled}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useHapticsEnabled(): [boolean, (enabled: boolean) => void] {
+  const [enabled, setEnabled] = useState(() => getHapticsEnabled());
+
+  const setHapticsEnabledState = useCallback((value: boolean) => {
+    setHapticsEnabled(value);
+    setEnabled(value);
+  }, []);
+
+  return [enabled, setHapticsEnabledState] as const;
+}
+
+/**
+ * Hook to manage a continuous haptic player lifecycle.
+ *
+ * @param playerId - A unique string key to identify this player (e.g., 'my-palette')
+ * @param initialIntensity - Initial intensity value (0.0 to 1.0)
+ * @param initialSharpness - Initial sharpness value (0.0 to 1.0)
+ *
+ * @returns Object with JS-bound methods for convenience:
+ * - `start()` - Start the continuous haptic
+ * - `stop()` - Stop the continuous haptic
+ * - `update(intensity, sharpness)` - Update haptic parameters
+ * - `playerId` - The player key (for use in worklets)
+ *
+ * @example
+ * ```tsx
+ * const PLAYER_KEY = 'my-palette';
+ *
+ * function MyComponent() {
+ *   const { start, stop, update } = useContinuousPlayer(PLAYER_KEY, 1.0, 0.5);
+ *
+ *   const gesture = Gesture.Pan()
+ *     .onBegin(() => {
+ *       start();
+ *     })
+ *     .onUpdate(() => {
+ *       update(0.5, 0.5);
+ *     })
+ *     .onEnd(() => {
+ *       stop();
+ *     });
+ * }
+ * ```
+ */
+export function useContinuousPlayer(
+  playerId: string,
+  initialIntensity: number = 1.0,
+  initialSharpness: number = 0.5
+) {
+  useEffect(() => {
+    createContinuousPlayer(playerId, initialIntensity, initialSharpness);
+
+    return () => {
+      destroyContinuousPlayer(playerId);
+    };
+  }, [playerId, initialIntensity, initialSharpness]);
+
+  return {
+    start: () => {
+      'worklet';
+      startContinuousPlayer(playerId);
+    },
+    stop: () => {
+      'worklet';
+      stopContinuousPlayer(playerId);
+    },
+    update: (intensity: number, sharpness: number) => {
+      'worklet';
+      return updateContinuousPlayer(playerId, intensity, sharpness);
+    },
+    playerId,
+  };
+}
+
+export function useHapticEngine() {
+  useEffect(() => {
+    initializeEngine();
+
+    const off = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        initializeEngine();
+      } else if (state === 'background') {
+        destroyEngine();
+      }
+    });
+
+    return () => {
+      off.remove();
+    };
+  }, []);
+}
+
+export function HapticProvider({ children }: { children: React.ReactNode }) {
+  useHapticEngine();
+
+  return <>{children}</>;
+}
+
+export { TickleHybridObject };
+export type {
+  HapticCurve,
+  HapticEventParameter,
+  HapticParameterType,
+  HapticImpactStyle,
+  HapticNotificationType,
+};