@renegades/react-native-tickle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renegades
+
+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,352 @@
+# react-native-tickle
+
+AHAP-style haptics (transient + continuous) on top of [Nitro Modules](https://nitro.margelo.com/) — the core functions are **UI-thread friendly** (`'worklet'`).
+
+## Why this package?
+
+Complete flexibility over iOS haptics with synchronous UI-thread execution.
+
+> iOS only (Core Haptics). Android support could be added in the future, but it’s currently unplanned.
+
+## Installation
+
+```sh
+npm i react-native-tickle react-native-nitro-modules
+```
+
+## Concepts (what to use when)
+
+- **Transient**: Instant “click/tap” events. No duration — you trigger them at a point in time.
+- **Continuous (pattern)**: Time-based patterns you _can_ define ahead of time. You provide **events** (with `duration`) and optionally **curves** (automation over time).
+- **Continuous player (real-time)**: For _unpredictable_ input (gesture position, scroll velocity, real-time data). You create a player once, then **start → update (many times) → stop**.
+
+### Why `events[]` and `curves[]` are separate
+
+On iOS Core Haptics, a pattern is made of two different building blocks:
+
+- **Events**: things that happen (transient “ticks” or continuous segments) at a `relativeTime`, with base `intensity`/`sharpness`.
+- **Curves**: how parameters (intensity/sharpness) evolve over time via control points, independent of “what event” is currently playing.
+
+They’re separate because they’re different object types in Core Haptics (events vs parameter curves) and they serve different jobs: **events define the structure**, **curves define the modulation**. You often combine both in one pattern.
+
+## Usage
+
+### Haptic "provider" (recommended)
+
+Wrap your app inside `HapticProvider`. This initializes the engine and automatically destroys it when the app goes to background.
+
+```tsx
+import { HapticProvider } from 'react-native-tickle';
+
+export function App() {
+  return <HapticProvider>{/* {Rest of your app} */}</HapticProvider>;
+}
+```
+
+### `startHaptic(events, curves)` (transient + continuous patterns)
+
+Play a transient:
+
+```ts
+import { startHaptic } from 'react-native-tickle';
+
+startHaptic(
+  [
+    {
+      type: 'transient',
+      relativeTime: 0,
+      parameters: [
+        { type: 'intensity', value: 1 },
+        { type: 'sharpness', value: 0.5 },
+      ],
+    },
+  ],
+  []
+);
+```
+
+Play a continuous pattern (events + curves together):
+
+```ts
+import { startHaptic } from 'react-native-tickle';
+
+startHaptic(
+  [
+    {
+      type: 'continuous',
+      relativeTime: 0,
+      duration: 1200,
+      parameters: [
+        { type: 'intensity', value: 0.2 },
+        { type: 'sharpness', value: 0.5 },
+      ],
+    },
+  ],
+  [
+    {
+      type: 'intensity',
+      relativeTime: 0,
+      controlPoints: [
+        { relativeTime: 0, value: 0.2 },
+        { relativeTime: 600, value: 1.0 },
+        { relativeTime: 1200, value: 0.2 },
+      ],
+    },
+  ]
+);
+```
+
+Combine transient + continuous in one pattern:
+
+```ts
+import { startHaptic } from 'react-native-tickle';
+
+startHaptic(
+  [
+    {
+      type: 'transient',
+      relativeTime: 0,
+      parameters: [
+        { type: 'intensity', value: 1 },
+        { type: 'sharpness', value: 0.8 },
+      ],
+    },
+    {
+      type: 'continuous',
+      relativeTime: 50,
+      duration: 800,
+      parameters: [
+        { type: 'intensity', value: 0.2 },
+        { type: 'sharpness', value: 0.4 },
+      ],
+    },
+  ],
+  []
+);
+```
+
+### Real-time continuous mode (continuous player)
+
+Use this when you _can't_ predefine a pattern. You start the player, update it in real time, then stop it.
+
+**Using the hook (recommended):**
+
+```tsx
+import { useContinuousPlayer } from 'react-native-tickle';
+
+function MyComponent() {
+  const { start, stop, update } = useContinuousPlayer('my-player', 1.0, 0.5);
+
+  const gesture = Gesture.Pan()
+    .onBegin(() => {
+      start();
+    })
+    .onUpdate((e) => {
+      update(e.translationY / 100, 0.5);
+    })
+    .onEnd(() => {
+      stop();
+    });
+}
+```
+
+**Manual control:**
+
+```ts
+import {
+  createContinuousPlayer,
+  startContinuousPlayer,
+  updateContinuousPlayer,
+  stopContinuousPlayer,
+  destroyContinuousPlayer,
+} from 'react-native-tickle';
+
+const PLAYER_ID = 'my-player';
+
+createContinuousPlayer(PLAYER_ID, 1.0, 0.5);
+startContinuousPlayer(PLAYER_ID);
+updateContinuousPlayer(PLAYER_ID, 0.8, 0.1);
+stopContinuousPlayer(PLAYER_ID);
+destroyContinuousPlayer(PLAYER_ID);
+```
+
+### Opt out of the provider (manual engine control)
+
+If you don’t want the provider behavior:
+
+```ts
+import { initializeEngine, destroyEngine } from 'react-native-tickle';
+
+initializeEngine();
+// ...
+destroyEngine();
+```
+
+### Stop everything (recommended in screen cleanups)
+
+Call `stopAllHaptics()` in your cleanup functions to terminate any ongoing continuous haptics. This prevents haptics from bleeding through to the next screen when navigating.
+
+```ts
+import { stopAllHaptics } from 'react-native-tickle';
+import { useEffect } from 'react';
+
+export function SomeScreen() {
+  useEffect(() => () => stopAllHaptics(), []);
+  return null;
+}
+```
+
+### Global enable/disable (settings toggle)
+
+Disable haptics globally for users who prefer no haptic feedback. The setting is **persisted** across app restarts. When disabled, all haptic calls become no-ops.
+
+**Using the hook (recommended):**
+
+```tsx
+import { useHapticsEnabled } from 'react-native-tickle';
+
+function SettingsScreen() {
+  const [hapticsEnabled, setHapticsEnabled] = useHapticsEnabled();
+
+  return <Switch value={hapticsEnabled} onValueChange={setHapticsEnabled} />;
+}
+```
+
+**Manual control:**
+
+```ts
+import { setHapticsEnabled, getHapticsEnabled } from 'react-native-tickle';
+
+const isEnabled = getHapticsEnabled(); // true by default
+setHapticsEnabled(false); // Disable all haptics
+setHapticsEnabled(true); // Re-enable haptics
+```
+
+### System haptics (predefined OS-level feedback)
+
+While the main purpose of this package is to support AHAP-style patterns (transient + continuous haptics with curves), system haptics are also available for completeness. These are simple, predefined OS-level feedback types that don't require pattern definitions. They can be called from the UI thread and don't require the haptic engine to be initialized.
+
+```ts
+import {
+  triggerImpact,
+  triggerNotification,
+  triggerSelection,
+} from 'react-native-tickle';
+
+// Impact feedback - simulates a physical collision
+triggerImpact('light'); // 'light' | 'medium' | 'heavy' | 'soft' | 'rigid'
+
+// Notification feedback - for alerts and status updates
+triggerNotification('success'); // 'success' | 'warning' | 'error'
+
+// Selection feedback - for picker wheels and toggles
+triggerSelection();
+```
+
+## API
+
+| Function                                                               | Purpose                                                         |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `HapticProvider`                                                       | Component that initializes engine; destroys on background       |
+| `useHapticEngine()`                                                    | Hook to manage engine lifecycle (used internally by provider)   |
+| `initializeEngine()` / `destroyEngine()`                               | Manual engine lifecycle                                         |
+| `startHaptic(events, curves)`                                          | Play a pattern (transient + continuous events, optional curves) |
+| `stopAllHaptics()`                                                     | Stop any running haptics (useful on unmount/navigation)         |
+| `useHapticsEnabled()`                                                  | Hook for reactive haptics enabled state                         |
+| `setHapticsEnabled(enabled)` / `getHapticsEnabled()`                   | Manual enable/disable toggle (persisted)                        |
+| `useContinuousPlayer(playerId, initialIntensity, initialSharpness)`    | Hook to manage a continuous player lifecycle                    |
+| `createContinuousPlayer(playerId, initialIntensity, initialSharpness)` | Create a continuous player with given ID                        |
+| `startContinuousPlayer(playerId)` / `stopContinuousPlayer(playerId)`   | Start/stop continuous playback for player                       |
+| `updateContinuousPlayer(playerId, intensityControl, sharpnessControl)` | Update intensity/sharpness for player                           |
+| `destroyContinuousPlayer(playerId)`                                    | Destroy player and release resources                            |
+| `triggerImpact(style)`                                                 | Trigger impact feedback (collision simulation)                  |
+| `triggerNotification(type)`                                            | Trigger notification feedback (alerts/status)                   |
+| `triggerSelection()`                                                   | Trigger selection feedback (pickers/toggles)                    |
+
+## Types (inputs)
+
+| Type                     | Values                                                |
+| ------------------------ | ----------------------------------------------------- |
+| `HapticParameterType`    | `'intensity' \| 'sharpness'`                          |
+| `HapticImpactStyle`      | `'light' \| 'medium' \| 'heavy' \| 'soft' \| 'rigid'` |
+| `HapticNotificationType` | `'success' \| 'warning' \| 'error'`                   |
+
+| `HapticEventParameter` | Type                  |
+| ---------------------- | --------------------- |
+| `type`                 | `HapticParameterType` |
+| `value`                | `number`              |
+
+**`HapticEvent`** (discriminated union)
+
+- **Transient:**
+
+  - `type`: `'transient'`
+  - `relativeTime`: `number`
+  - `parameters`: `HapticEventParameter[]`
+
+- **Continuous:**
+  - `type`: `'continuous'`
+  - `relativeTime`: `number`
+  - `duration`: `number`
+  - `parameters`: `HapticEventParameter[]`
+
+| `HapticCurveControlPoint` | Type     |
+| ------------------------- | -------- |
+| `relativeTime`            | `number` |
+| `value`                   | `number` |
+
+| `HapticCurve`   | Type                        |
+| --------------- | --------------------------- |
+| `type`          | `HapticCurveType`           |
+| `relativeTime`  | `number`                    |
+| `controlPoints` | `HapticCurveControlPoint[]` |
+
+## Limitations
+
+### Parameter curves affect all events in a pattern
+
+In CoreHaptics, `CHHapticParameterCurve` uses `hapticIntensityControl` and `hapticSharpnessControl` — these are **pattern-level multipliers**, not per-event modifiers. Any curve you define will multiply the intensity/sharpness of **all events** playing at that moment, including transients.
+
+**Example problem:**
+
+```ts
+startHaptic(
+  [
+    { type: 'continuous', relativeTime: 0, duration: 2000, parameters: [...] },
+    { type: 'transient', relativeTime: 1000, parameters: [{ type: 'intensity', value: 1.0 }, ...] },
+  ],
+  [
+    { type: 'intensity', relativeTime: 0, controlPoints: [
+      { relativeTime: 0, value: 1.0 },
+      { relativeTime: 1000, value: 0.3 },  // At t=1000ms, intensity control = 0.3
+      { relativeTime: 2000, value: 0.3 },
+    ]},
+  ]
+);
+```
+
+The transient at `t=1000ms` has base intensity `1.0`, but the curve sets `intensityControl=0.3` at that moment. **Effective intensity: 1.0 × 0.3 = 0.3**. The transient feels weaker than expected.
+
+**Workaround:** Play continuous and transient events in separate `startHaptic()` calls:
+
+```ts
+// Continuous with curves
+startHaptic(continuousEvents, curves);
+
+// Transients without curves (separate pattern)
+startHaptic(transientEvents, []);
+```
+
+Each call creates an isolated pattern/player — curves from one won't affect events in the other.
+
+> **Note:** The library automatically resets control values to `1.0` at the end of each continuous event, so transients **after** a continuous event finishes are not affected. This limitation only applies to transients **during** a continuous event with active curves.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT

package/Tickle.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Tickle"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://google.com.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/Tickle+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(tickle)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME tickle)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/tickle+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,126 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['Tickle_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/tickle+autolinking.gradle'
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["Tickle_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.tickle"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  implementation project(":react-native-nitro-modules")
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+Tickle_kotlinVersion=2.0.21
+Tickle_minSdkVersion=24
+Tickle_targetSdkVersion=34
+Tickle_compileSdkVersion=35
+Tickle_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "tickleOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::tickle::initialize(vm);
+}

package/android/src/main/java/com/margelo/nitro/tickle/Tickle.kt

@@ -0,0 +1,71 @@
+package com.margelo.nitro.tickle
+  
+import com.facebook.proguard.annotations.DoNotStrip
+
+@DoNotStrip
+class Tickle : HybridTickleSpec() {
+  override val memorySize: Long
+    get() = 0L
+
+  private var hapticsEnabled: Boolean = true
+
+  override fun startHaptic(events: Array<HapticEvent>, curves: Array<HapticCurve>) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun stopAllHaptics() {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun initializeEngine() {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun destroyEngine() {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun createContinuousPlayer(playerId: String, initialIntensity: Double, initialSharpness: Double) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun startContinuousPlayer(playerId: String) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun updateContinuousPlayer(playerId: String, intensityControl: Double, sharpnessControl: Double) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun stopContinuousPlayer(playerId: String) {
+    // TODO: Android haptics implementation not yet supported
+  }
+  
+  override fun destroyContinuousPlayer(playerId: String) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  // MARK: - Global Haptics Enable/Disable
+
+  override fun setHapticsEnabled(enabled: Boolean) {
+    hapticsEnabled = enabled
+  }
+
+  override fun getHapticsEnabled(): Boolean {
+    return hapticsEnabled
+  }
+
+  // MARK: - System Haptics (Predefined OS-level feedback)
+
+  override fun triggerImpact(style: HapticImpactStyle) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun triggerNotification(type: HapticNotificationType) {
+    // TODO: Android haptics implementation not yet supported
+  }
+
+  override fun triggerSelection() {
+    // TODO: Android haptics implementation not yet supported
+  }
+}

package/android/src/main/java/com/margelo/nitro/tickle/TicklePackage.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.tickle
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class TicklePackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("tickle")
+        }
+    }
+}