@capawesome/capacitor-shake 0.0.1 → 0.1.0

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-shake
+# Capacitor Shake Plugin
 
 Capacitor plugin to detect shake gestures.
 
@@ -18,9 +18,14 @@ Capacitor plugin to detect shake gestures.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Shake plugin is typically used to trigger an action when the user shakes the device, for example:
+
+- **Feedback and bug reporting**: Let users shake the device to open a feedback or bug report dialog.
+- **Debug menus**: Open a hidden developer or debug menu in internal builds when the device is shaken.
+- **Undo actions**: Offer a shake-to-undo interaction, a gesture many users already know from iOS.
+- **Refresh content**: Reload data or shuffle content when a shake gesture is detected.
 
 ## Compatibility
 
@@ -60,6 +65,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to detect shake gestures and stop detecting them.
+
+### Detect shake gestures
+
+Attach a `shake` listener and start watching for shake gestures. Use the `sensitivity` option to control how strong a shake must be to trigger an event (see [Sensitivity Levels](#sensitivity-levels)). Only available on Android and iOS:
+
 ```typescript
 import { Shake } from '@capawesome/capacitor-shake';
 
@@ -69,6 +80,14 @@ const startWatching = async () => {
   });
   await Shake.startWatching({ sensitivity: 'medium' });
 };
+```
+
+### Stop detecting shake gestures
+
+Stop watching and remove all listeners when you no longer need shake detection, for example when the user leaves the corresponding screen. The sensor is only active while you are watching, so this keeps the plugin battery-friendly:
+
+```typescript
+import { Shake } from '@capawesome/capacitor-shake';
 
 const stopWatching = async () => {
   await Shake.stopWatching();
@@ -80,10 +99,10 @@ const stopWatching = async () => {
 
 <docgen-index>
 
-* [`addListener('shake', ...)`](#addlistenershake-)
-* [`removeAllListeners()`](#removealllisteners)
 * [`startWatching(...)`](#startwatching)
 * [`stopWatching()`](#stopwatching)
+* [`addListener('shake', ...)`](#addlistenershake-)
+* [`removeAllListeners()`](#removealllisteners)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 
@@ -92,69 +111,69 @@ const stopWatching = async () => {
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
-### addListener('shake', ...)
+### startWatching(...)
 
 ```typescript
-addListener(eventName: 'shake', listenerFunc: () => void) => Promise<PluginListenerHandle>
+startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
 ```
 
-Called when a shake gesture is detected.
+Start watching for shake gestures.
 
 Only available on Android and iOS.
 
-| Param              | Type                       |
-| ------------------ | -------------------------- |
-| **`eventName`**    | <code>'shake'</code>       |
-| **`listenerFunc`** | <code>() =&gt; void</code> |
-
-**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+| Param         | Type                                                                  |
+| ------------- | --------------------------------------------------------------------- |
+| **`options`** | <code><a href="#startwatchingoptions">StartWatchingOptions</a></code> |
 
 **Since:** 0.1.0
 
 --------------------
 
 
-### removeAllListeners()
+### stopWatching()
 
 ```typescript
-removeAllListeners() => Promise<void>
+stopWatching() => Promise<void>
 ```
 
-Remove all listeners for this plugin.
+Stop watching for shake gestures.
+
+Only available on Android and iOS.
 
 **Since:** 0.1.0
 
 --------------------
 
 
-### startWatching(...)
+### addListener('shake', ...)
 
 ```typescript
-startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
+addListener(eventName: 'shake', listenerFunc: () => void) => Promise<PluginListenerHandle>
 ```
 
-Start watching for shake gestures.
+Called when a shake gesture is detected.
 
 Only available on Android and iOS.
 
-| Param         | Type                                                                  |
-| ------------- | --------------------------------------------------------------------- |
-| **`options`** | <code><a href="#startwatchingoptions">StartWatchingOptions</a></code> |
+| Param              | Type                       |
+| ------------------ | -------------------------- |
+| **`eventName`**    | <code>'shake'</code>       |
+| **`listenerFunc`** | <code>() =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
 
 **Since:** 0.1.0
 
 --------------------
 
 
-### stopWatching()
+### removeAllListeners()
 
 ```typescript
-stopWatching() => Promise<void>
+removeAllListeners() => Promise<void>
 ```
 
-Stop watching for shake gestures.
-
-Only available on Android and iOS.
+Remove all listeners for this plugin.
 
 **Since:** 0.1.0
 
@@ -164,13 +183,6 @@ Only available on Android and iOS.
 ### Interfaces
 
 
-#### PluginListenerHandle
-
-| Prop         | Type                                      |
-| ------------ | ----------------------------------------- |
-| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
-
-
 #### StartWatchingOptions
 
 | Prop              | Type                                                | Description                                                                                                                                                 | Default               | Since |
@@ -178,6 +190,13 @@ Only available on Android and iOS.
 | **`sensitivity`** | <code><a href="#sensitivity">Sensitivity</a></code> | The sensitivity of the shake detection. Use `'light'` to detect gentle shakes and `'hard'` to only detect strong shakes. Only available on Android and iOS. | <code>'medium'</code> | 0.1.0 |
 
 
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
 ### Type Aliases
 
 
@@ -195,6 +214,42 @@ The `sensitivity` option controls how strong a shake must be to emit a `shake` e
 - `medium`: A moderate shake is required to trigger an event (default).
 - `hard`: Only a strong shake triggers an event.
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It focuses on doing one thing well: detecting physical shake gestures on Android and iOS through a single, fully typed API. You can tune how strong a shake must be with three sensitivity levels, and the motion sensor only runs between `startWatching(...)` and `stopWatching()`, so it stays battery-friendly. It is actively maintained against the latest Capacitor version, giving you consistent shake behavior on both platforms from one dependency.
+
+### Which platforms are supported by the Shake plugin?
+
+The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented, since browsers do not provide a comparable shake detection API.
+
+### Does shake detection drain the battery?
+
+No, the plugin is designed to be battery-friendly. The motion sensor is only active between `startWatching(...)` and `stopWatching()`, so no sensor data is processed while you are not watching for shakes. Remember to call `stopWatching()` and `removeAllListeners()` when you no longer need shake detection.
+
+### How can I control how strong a shake must be?
+
+Pass the `sensitivity` option to `startWatching(...)`. Use `light` to detect gentle shakes, `medium` (the default) for moderate shakes, or `hard` to only detect strong shakes. See [Sensitivity Levels](#sensitivity-levels) for details.
+
+### Do I need any permissions to detect shake gestures?
+
+No, the plugin does not require any additional permissions or privacy descriptions on Android or iOS. You can install it and start watching for shake gestures right away.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes.
+- [Gyroscope](https://capawesome.io/docs/sdks/capacitor/gyroscope/): Read the device's gyroscope sensor.
+- [Haptics](https://capawesome.io/docs/sdks/capacitor/haptics/): Provide haptic feedback such as impacts, notifications, and vibrations.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/shake/CHANGELOG.md).

package/dist/docs.json

@@ -11,35 +11,30 @@
     ],
     "methods": [
       {
-        "name": "addListener",
-        "signature": "(eventName: 'shake', listenerFunc: () => void) => Promise<PluginListenerHandle>",
+        "name": "startWatching",
+        "signature": "(options?: StartWatchingOptions | undefined) => Promise<void>",
         "parameters": [
           {
-            "name": "eventName",
-            "docs": "",
-            "type": "'shake'"
-          },
-          {
-            "name": "listenerFunc",
+            "name": "options",
             "docs": "",
-            "type": "() => void"
+            "type": "StartWatchingOptions | undefined"
           }
         ],
-        "returns": "Promise<PluginListenerHandle>",
+        "returns": "Promise<void>",
         "tags": [
           {
             "name": "since",
             "text": "0.1.0"
           }
         ],
-        "docs": "Called when a shake gesture is detected.\n\nOnly available on Android and iOS.",
+        "docs": "Start watching for shake gestures.\n\nOnly available on Android and iOS.",
         "complexTypes": [
-          "PluginListenerHandle"
+          "StartWatchingOptions"
         ],
-        "slug": "addlistenershake-"
+        "slug": "startwatching"
       },
       {
-        "name": "removeAllListeners",
+        "name": "stopWatching",
         "signature": "() => Promise<void>",
         "parameters": [],
         "returns": "Promise<void>",
@@ -49,35 +44,40 @@
             "text": "0.1.0"
           }
         ],
-        "docs": "Remove all listeners for this plugin.",
+        "docs": "Stop watching for shake gestures.\n\nOnly available on Android and iOS.",
         "complexTypes": [],
-        "slug": "removealllisteners"
+        "slug": "stopwatching"
       },
       {
-        "name": "startWatching",
-        "signature": "(options?: StartWatchingOptions | undefined) => Promise<void>",
+        "name": "addListener",
+        "signature": "(eventName: 'shake', listenerFunc: () => void) => Promise<PluginListenerHandle>",
         "parameters": [
           {
-            "name": "options",
+            "name": "eventName",
             "docs": "",
-            "type": "StartWatchingOptions | undefined"
+            "type": "'shake'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "() => void"
           }
         ],
-        "returns": "Promise<void>",
+        "returns": "Promise<PluginListenerHandle>",
         "tags": [
           {
             "name": "since",
             "text": "0.1.0"
           }
         ],
-        "docs": "Start watching for shake gestures.\n\nOnly available on Android and iOS.",
+        "docs": "Called when a shake gesture is detected.\n\nOnly available on Android and iOS.",
         "complexTypes": [
-          "StartWatchingOptions"
+          "PluginListenerHandle"
         ],
-        "slug": "startwatching"
+        "slug": "addlistenershake-"
       },
       {
-        "name": "stopWatching",
+        "name": "removeAllListeners",
         "signature": "() => Promise<void>",
         "parameters": [],
         "returns": "Promise<void>",
@@ -87,30 +87,14 @@
             "text": "0.1.0"
           }
         ],
-        "docs": "Stop watching for shake gestures.\n\nOnly available on Android and iOS.",
+        "docs": "Remove all listeners for this plugin.",
         "complexTypes": [],
-        "slug": "stopwatching"
+        "slug": "removealllisteners"
       }
     ],
     "properties": []
   },
   "interfaces": [
-    {
-      "name": "PluginListenerHandle",
-      "slug": "pluginlistenerhandle",
-      "docs": "",
-      "tags": [],
-      "methods": [],
-      "properties": [
-        {
-          "name": "remove",
-          "tags": [],
-          "docs": "",
-          "complexTypes": [],
-          "type": "() => Promise<void>"
-        }
-      ]
-    },
     {
       "name": "StartWatchingOptions",
       "slug": "startwatchingoptions",
@@ -146,6 +130,22 @@
           "type": "Sensitivity"
         }
       ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
     }
   ],
   "enums": [],

package/dist/esm/definitions.d.ts

@@ -4,35 +4,35 @@ import type { PluginListenerHandle } from '@capacitor/core';
  */
 export interface ShakePlugin {
     /**
-     * Called when a shake gesture is detected.
+     * Start watching for shake gestures.
      *
      * Only available on Android and iOS.
      *
      * @since 0.1.0
      */
-    addListener(eventName: 'shake', listenerFunc: () => void): Promise<PluginListenerHandle>;
+    startWatching(options?: StartWatchingOptions): Promise<void>;
     /**
-     * Remove all listeners for this plugin.
+     * Stop watching for shake gestures.
+     *
+     * Only available on Android and iOS.
      *
      * @since 0.1.0
      */
-    removeAllListeners(): Promise<void>;
+    stopWatching(): Promise<void>;
     /**
-     * Start watching for shake gestures.
+     * Called when a shake gesture is detected.
      *
      * Only available on Android and iOS.
      *
      * @since 0.1.0
      */
-    startWatching(options?: StartWatchingOptions): Promise<void>;
+    addListener(eventName: 'shake', listenerFunc: () => void): Promise<PluginListenerHandle>;
     /**
-     * Stop watching for shake gestures.
-     *
-     * Only available on Android and iOS.
+     * Remove all listeners for this plugin.
      *
      * @since 0.1.0
      */
-    stopWatching(): Promise<void>;
+    removeAllListeners(): Promise<void>;
 }
 /**
  * @since 0.1.0

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * @since 0.1.0\n */\nexport interface ShakePlugin {\n  /**\n   * Called when a shake gesture is detected.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  addListener(\n    eventName: 'shake',\n    listenerFunc: () => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Remove all listeners for this plugin.\n   *\n   * @since 0.1.0\n   */\n  removeAllListeners(): Promise<void>;\n  /**\n   * Start watching for shake gestures.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  startWatching(options?: StartWatchingOptions): Promise<void>;\n  /**\n   * Stop watching for shake gestures.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  stopWatching(): Promise<void>;\n}\n\n/**\n * @since 0.1.0\n */\nexport interface StartWatchingOptions {\n  /**\n   * The sensitivity of the shake detection.\n   *\n   * Use `'light'` to detect gentle shakes and `'hard'` to only detect strong shakes.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   * @default 'medium'\n   * @example 'medium'\n   */\n  sensitivity?: Sensitivity;\n}\n\n/**\n * @since 0.1.0\n */\nexport type Sensitivity = 'hard' | 'light' | 'medium';\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * @since 0.1.0\n */\nexport interface ShakePlugin {\n  /**\n   * Start watching for shake gestures.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  startWatching(options?: StartWatchingOptions): Promise<void>;\n  /**\n   * Stop watching for shake gestures.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  stopWatching(): Promise<void>;\n  /**\n   * Called when a shake gesture is detected.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   */\n  addListener(\n    eventName: 'shake',\n    listenerFunc: () => void,\n  ): Promise<PluginListenerHandle>;\n  /**\n   * Remove all listeners for this plugin.\n   *\n   * @since 0.1.0\n   */\n  removeAllListeners(): Promise<void>;\n}\n\n/**\n * @since 0.1.0\n */\nexport interface StartWatchingOptions {\n  /**\n   * The sensitivity of the shake detection.\n   *\n   * Use `'light'` to detect gentle shakes and `'hard'` to only detect strong shakes.\n   *\n   * Only available on Android and iOS.\n   *\n   * @since 0.1.0\n   * @default 'medium'\n   * @example 'medium'\n   */\n  sensitivity?: Sensitivity;\n}\n\n/**\n * @since 0.1.0\n */\nexport type Sensitivity = 'hard' | 'light' | 'medium';\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-shake",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to detect shake gestures.",
+  "version": "0.1.0",
+  "description": "Capacitor plugin to detect shake gestures on Android and iOS.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -33,11 +33,19 @@
       "url": "https://opencollective.com/capawesome"
     }
   ],
-  "homepage": "https://capawesome.io/docs/plugins/shake/",
+  "homepage": "https://capawesome.io/docs/sdks/capacitor/shake/",
   "keywords": [
     "capacitor",
     "plugin",
-    "native"
+    "native",
+    "capacitor-plugin",
+    "shake",
+    "shake detection",
+    "shake gesture",
+    "shake event",
+    "motion detection",
+    "accelerometer",
+    "sensor"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",