docs: add additional plugin documentation from v2 site (#92)

Author: imhoffd

action-sheet/README.md

@@ -9,6 +9,33 @@ npm install @capacitor/action-sheet
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { ActionSheet, ActionSheetOptionStyle } from '@capacitor/action-sheet';
+
+const showActions = async () => {
+  const result = await ActionSheet.showActions({
+    title: 'Photo Options',
+    message: 'Select an option to perform',
+    options: [
+      {
+        title: 'Upload',
+      },
+      {
+        title: 'Share',
+      },
+      {
+        title: 'Remove',
+        style: ActionSheetOptionStyle.Destructive,
+      },
+    ],
+  });
+
+  console.log('Action Sheet result:', result);
+};
+```
+
 ## API
 
 <docgen-index>

app-launcher/README.md

@@ -9,6 +9,22 @@ npm install @capacitor/app-launcher
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { AppLauncher } from '@capacitor/app-launcher';
+
+const checkCanOpenUrl = async () => {
+  const { value } = await AppLauncher.canOpenUrl({ url: 'com.getcapacitor.myapp' });
+
+  alert('Can open url: ', value);
+};
+
+const openPortfolioPage = async () => {
+  await AppLauncher.openUrl({ url: 'com.getcapacitor.myapp://page?id=portfolio' });
+};
+```
+
 ## API
 
 <docgen-index>
@@ -30,10 +46,13 @@ canOpenUrl(options: CanOpenURLOptions) => Promise<CanOpenURLResult>
 
 Check if an app can be opened with the given URL.
 
-On iOS  you must declare the URL schemes you pass to this method by adding
-the LSApplicationQueriesSchemes key to your app's Info.plist file.
-This method always returns false for undeclared schemes, whether or not an appropriate
-app is installed. To learn more about the key, see
+On iOS you must declare the URL schemes you pass to this method by adding
+the `LSApplicationQueriesSchemes` key to your app's `Info.plist` file.
+Learn more about configuring
+[`Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist).
+
+This method always returns false for undeclared schemes, whether or not an
+appropriate app is installed. To learn more about the key, see
 [LSApplicationQueriesSchemes](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/plist/info/LSApplicationQueriesSchemes).
 
 | Param         | Type                                                            |

app-launcher/src/definitions.ts

@@ -2,10 +2,13 @@ export interface AppLauncherPlugin {
   /**
    * Check if an app can be opened with the given URL.
    *
-   * On iOS  you must declare the URL schemes you pass to this method by adding
-   * the LSApplicationQueriesSchemes key to your app's Info.plist file.
-   * This method always returns false for undeclared schemes, whether or not an appropriate
-   * app is installed. To learn more about the key, see
+   * On iOS you must declare the URL schemes you pass to this method by adding
+   * the `LSApplicationQueriesSchemes` key to your app's `Info.plist` file.
+   * Learn more about configuring
+   * [`Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist).
+   *
+   * This method always returns false for undeclared schemes, whether or not an
+   * appropriate app is installed. To learn more about the key, see
    * [LSApplicationQueriesSchemes](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/plist/info/LSApplicationQueriesSchemes).
    *
    * @since 1.0.0

app/README.md

@@ -9,6 +9,30 @@ npm install @capacitor/app
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { App } from '@capacitor/app';
+
+App.addListener('appStateChange', ({ isActive }) => {
+  console.log('App state changed. Is active?', isActive);
+});
+
+App.addListener('appUrlOpen', data => {
+  console.log('App opened with URL:', data);
+});
+
+App.addListener('appRestoredResult', data => {
+  console.log('Restored state:', data);
+});
+
+const checkAppLaunchUrl = async () => {
+  const { url } = await App.getLaunchUrl();
+
+  alert('App opened with URL: ' + url);
+};
+```
+
 ## API
 
 <docgen-index>
@@ -144,6 +168,24 @@ If the app was launched with previously persisted plugin call data, such as on A
 when an activity returns to an app that was closed, this call will return any data
 the app was launched with, converted into the form of a result from a plugin call.
 
+On Android, due to memory constraints on low-end devices, it's possible
+that, if your app launches a new activity, your app will be terminated by
+the operating system in order to reduce memory consumption.
+
+For example, that means the Camera API, which launches a new Activity to
+take a photo, may not be able to return data back to your app.
+
+To avoid this, Capacitor stores all restored activity results on launch.
+You should add a listener for `appRestoredResult` in order to handle any
+plugin call results that were delivered when your app was not running.
+
+Once you have that result (if any), you can update the UI to restore a
+logical experience for the user, such as navigating or selecting the
+proper tab.
+
+We recommend every Android app using plugins that rely on external
+Activities (for example, Camera) to have this event and process handled.
+
 | Param              | Type                                                          |
 | ------------------ | ------------------------------------------------------------- |
 | **`eventName`**    | <code>'appRestoredResult'</code>                              |

app/src/definitions.ts

@@ -178,6 +178,24 @@ export interface AppPlugin {
    * when an activity returns to an app that was closed, this call will return any data
    * the app was launched with, converted into the form of a result from a plugin call.
    *
+   * On Android, due to memory constraints on low-end devices, it's possible
+   * that, if your app launches a new activity, your app will be terminated by
+   * the operating system in order to reduce memory consumption.
+   *
+   * For example, that means the Camera API, which launches a new Activity to
+   * take a photo, may not be able to return data back to your app.
+   *
+   * To avoid this, Capacitor stores all restored activity results on launch.
+   * You should add a listener for `appRestoredResult` in order to handle any
+   * plugin call results that were delivered when your app was not running.
+   *
+   * Once you have that result (if any), you can update the UI to restore a
+   * logical experience for the user, such as navigating or selecting the
+   * proper tab.
+   *
+   * We recommend every Android app using plugins that rely on external
+   * Activities (for example, Camera) to have this event and process handled.
+   *
    * @since 1.0.0
    */
   addListener(

browser/README.md

@@ -2,13 +2,25 @@
 
 The Browser API provides the ability to open an in-app browser and subscribe to browser events.
 
+On iOS, this uses `SFSafariViewController` and is compliant with leading OAuth service in-app-browser requirements.
+
 ## Install
 
 ```bash
 npm install @capacitor/browser
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { Browser } from '@capacitor/browser';
+
+const openCapacitorSite = async () => {
+  await Browser.open({ url: 'http://capacitorjs.com/' });
+};
+```
+
 ## API
 
 <docgen-index>

camera/README.md

@@ -9,6 +9,58 @@ npm install @capacitor/camera
 npx cap sync
 ```
 
+## iOS Notes
+
+iOS requires the following usage description be added and filled out for your app in `Info.plist`:
+
+- `NSCameraUsageDescription` (`Privacy - Camera Usage Description`)
+- `NSPhotoLibraryAddUsageDescription` (`Privacy - Photo Library Additions Usage Description`)
+- `NSPhotoLibraryUsageDescription` (`Privacy - Photo Library Usage Description`)
+
+Read about [Configuring `Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) in the [iOS Guide](https://capacitorjs.com/docs/ios) for more information on setting iOS permissions in Xcode
+
+## Android Notes
+
+This API requires the following permissions be added to your `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+```
+
+The storage permissions are for reading/saving photo files.
+
+Read about [Setting Permissions](https://capacitorjs.com/docs/android/configuration#setting-permissions) in the [Android Guide](https://capacitorjs.com/docs/android) for more information on setting Android permissions.
+
+Additionally, because the Camera API launches a separate Activity to handle taking the photo, you should listen for `appRestoredResult` in the `App` plugin to handle any camera data that was sent in the case your app was terminated by the operating system while the Activity was running.
+
+## PWA Notes
+
+[PWA Elements](https://capacitorjs.com/docs/web/pwa-elements) are required for Camera plugin to work.
+
+## Example
+
+```typescript
+import { Camera, CameraResultType } from '@capacitor/camera';
+
+const takePicture = async () {
+  const image = await Camera.getPhoto({
+    quality: 90,
+    allowEditing: true,
+    resultType: CameraResultType.Uri
+  });
+
+  // image.webPath will contain a path that can be set as an image src.
+  // You can access the original file using image.path, which can be
+  // passed to the Filesystem API to read the raw data of the image,
+  // if desired (or pass resultType: CameraResultType.Base64 to getPhoto)
+  var imageUrl = image.webPath;
+
+  // Can be set to the src of an image now
+  imageElement.src = imageUrl;
+};
+```
+
 ## API
 
 <docgen-index>

clipboard/README.md

@@ -9,6 +9,24 @@ npm install @capacitor/clipboard
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { Clipboard } from '@capacitor/clipboard';
+
+const writeToClipboard = async () => {
+  await Clipboard.write({
+    string: "Hello World!"
+  });
+};
+
+const checkClipboard = async () => {
+  const { type, value } = await Clipboard.read();
+
+  alert(`Got ${type} from clipboard: ${value}`);
+};
+```
+
 ## API
 
 <docgen-index>

device/README.md

@@ -9,6 +9,24 @@ npm install @capacitor/device
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { Device } from '@capacitor/device';
+
+const logDeviceInfo = async () => {
+  const info = await Device.getInfo();
+
+  console.log(info);
+};
+
+const logBatteryInfo = async () => {
+  const info = await Device.getBatteryInfo();
+
+  console.log(info);
+};
+```
+
 ## API
 
 <docgen-index>

dialog/README.md

@@ -9,6 +9,38 @@ npm install @capacitor/dialog
 npx cap sync
 ```
 
+## Example
+
+```typescript
+import { Dialog } from '@capacitor/dialog';
+
+const showAlert = async () => {
+  await Dialog.alert({
+    title: 'Stop',
+    message: 'this is an error',
+  });
+};
+
+const showConfirm = async () => {
+  const { value } = await Dialog.confirm({
+    title: 'Confirm',
+    message: `Are you sure you'd like to press the red button?`,
+  });
+
+  console.log('Confirmed:', value);
+};
+
+const showPrompt = async () => {
+  const { value, cancelled } = await Dialog.prompt({
+    title: 'Hello',
+    message: `What's your name?`,
+  });
+
+  console.log('Name:', value);
+  console.log('Cancelled:', cancelled);
+};
+```
+
 ## API
 
 <docgen-index>