From fcc66b22ee50e8fef6b62d3e4cf79df58df43e1e Mon Sep 17 00:00:00 2001 From: Shane Rosenthal Date: Tue, 9 Dec 2025 20:52:49 -0500 Subject: [PATCH] Updates API docs for mobile (JS) --- .../views/docs/mobile/2/apis/biometrics.md | 102 ++++++ resources/views/docs/mobile/2/apis/browser.md | 56 ++++ resources/views/docs/mobile/2/apis/camera.md | 314 ++++++++++++++++++ resources/views/docs/mobile/2/apis/device.md | 108 ++++++ resources/views/docs/mobile/2/apis/dialog.md | 129 ++++++- resources/views/docs/mobile/2/apis/file.md | 62 ++++ .../views/docs/mobile/2/apis/geolocation.md | 259 ++++++++++++++- resources/views/docs/mobile/2/apis/haptics.md | 28 ++ .../views/docs/mobile/2/apis/microphone.md | 164 +++++++++ resources/views/docs/mobile/2/apis/network.md | 35 ++ .../docs/mobile/2/apis/push-notifications.md | 108 ++++++ resources/views/docs/mobile/2/apis/scanner.md | 214 ++++++++++++ .../docs/mobile/2/apis/secure-storage.md | 69 ++++ resources/views/docs/mobile/2/apis/share.md | 123 +++++++ resources/views/docs/mobile/2/apis/system.md | 105 ++++++ 15 files changed, 1872 insertions(+), 4 deletions(-) diff --git a/resources/views/docs/mobile/2/apis/biometrics.md b/resources/views/docs/mobile/2/apis/biometrics.md index c70bc7e4..2a189cef 100644 --- a/resources/views/docs/mobile/2/apis/biometrics.md +++ b/resources/views/docs/mobile/2/apis/biometrics.md @@ -8,28 +8,65 @@ order: 100 The Biometrics API allows you to authenticate users using their device's biometric sensors like Face ID, Touch ID, or fingerprint scanners. + + + + ```php use Native\Mobile\Facades\Biometrics; ``` + + + +```js +import { biometric, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `prompt()` Prompts the user for biometric authentication. + + + + ```php use Native\Mobile\Facades\Biometrics; Biometrics::prompt(); ``` + + + +```js +// Basic usage +await biometric.prompt(); + +// With an identifier for tracking +await biometric.prompt() + .id('secure-action-auth'); +``` + + + + ## Events ### `Completed` Fired when biometric authentication completes (success or failure). + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Biometric\Completed; @@ -47,6 +84,71 @@ public function handle(bool $success) } ``` + + + +```js +import { biometric, on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const isAuthenticated = ref(false); + +const handleBiometricComplete = (payload) => { + if (payload.success) { + isAuthenticated.value = true; + unlockSecureFeature(); + } else { + showErrorMessage(); + } +}; + +const authenticate = async () => { + await biometric.prompt(); +}; + +onMounted(() => { + on(Events.Biometric.Completed, handleBiometricComplete); +}); + +onUnmounted(() => { + off(Events.Biometric.Completed, handleBiometricComplete); +}); +``` + + + + +```jsx +import { biometric, on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [isAuthenticated, setIsAuthenticated] = useState(false); + +const handleBiometricComplete = (payload) => { + if (payload.success) { + setIsAuthenticated(true); + unlockSecureFeature(); + } else { + showErrorMessage(); + } +}; + +const authenticate = async () => { + await biometric.prompt(); +}; + +useEffect(() => { + on(Events.Biometric.Completed, handleBiometricComplete); + + return () => { + off(Events.Biometric.Completed, handleBiometricComplete); + }; +}, []); +``` + + + + ## Platform Support - **iOS:** Face ID, Touch ID diff --git a/resources/views/docs/mobile/2/apis/browser.md b/resources/views/docs/mobile/2/apis/browser.md index 246ef73d..56c158aa 100644 --- a/resources/views/docs/mobile/2/apis/browser.md +++ b/resources/views/docs/mobile/2/apis/browser.md @@ -8,36 +8,92 @@ order: 200 The Browser API provides three methods for opening URLs, each designed for specific use cases: in-app browsing, system browser navigation, and web authentication flows. + + + + ```php use Native\Mobile\Facades\Browser; ``` + + + +```js +import { browser } from '#nativephp'; +``` + + + + ## Methods ### `inApp()` Opens a URL in an embedded browser within your app using Custom Tabs (Android) or SFSafariViewController (iOS). + + + + ```php Browser::inApp('https://nativephp.com/mobile'); ``` + + + +```js +await browser.inApp('https://nativephp.com/mobile'); +``` + + + + ### `open()` Opens a URL in the device's default browser app, leaving your application entirely. + + + + ```php Browser::open('https://nativephp.com/mobile'); ``` + + + +```js +await browser.open('https://nativephp.com/mobile'); +``` + + + + ### `auth()` Opens a URL in a specialized authentication browser designed for OAuth flows with automatic `nativephp://` redirect handling. + + + + ```php Browser::auth('https://provider.com/oauth/authorize?client_id=123&redirect_uri=nativephp://127.0.0.1/auth/callback'); ``` + + + +```js +await browser.auth('https://provider.com/oauth/authorize?client_id=123&redirect_uri=nativephp://127.0.0.1/auth/callback'); +``` + + + + ## Use Cases ### When to Use Each Method diff --git a/resources/views/docs/mobile/2/apis/camera.md b/resources/views/docs/mobile/2/apis/camera.md index c5e61311..aeeb7a91 100644 --- a/resources/views/docs/mobile/2/apis/camera.md +++ b/resources/views/docs/mobile/2/apis/camera.md @@ -7,20 +7,53 @@ order: 300 The Camera API provides access to the device's camera for taking photos, recording videos, and selecting media from the gallery. + + + + ```php use Native\Mobile\Facades\Camera; ``` + + + +```js +import { camera, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `getPhoto()` Opens the camera interface to take a photo. + + + + ```php Camera::getPhoto(); ``` + + + +```js +// Basic usage +await camera.getPhoto(); + +// With identifier for tracking +await camera.getPhoto() + .id('profile-pic'); +``` + + + + ### `recordVideo()` Opens the camera interface to record a video with optional configuration. @@ -30,6 +63,10 @@ Opens the camera interface to record a video with optional configuration. **Returns:** `PendingVideoRecorder` - Fluent interface for configuring video recording + + + + ```php // Basic video recording Camera::recordVideo(); @@ -44,6 +81,26 @@ Camera::recordVideo() ->start(); ``` + + + +```js +// Basic video recording +await camera.recordVideo(); + +// With maximum duration +await camera.recordVideo() + .maxDuration(60); + +// With identifier for tracking +await camera.recordVideo() + .maxDuration(30) + .id('my-video-123'); +``` + + + + ### `pickImages()` Opens the gallery/photo picker to select existing images. @@ -54,6 +111,10 @@ Opens the gallery/photo picker to select existing images. **Returns:** `bool` - `true` if picker opened successfully + + + + ```php // Pick a single image Camera::pickImages('images', false); @@ -65,6 +126,35 @@ Camera::pickImages('images', true); Camera::pickImages('all', true); ``` + + + +```js +// Pick images using fluent API +await camera.pickImages() + .images() + .multiple() + .maxItems(5); + +// Pick only videos +await camera.pickImages() + .videos() + .multiple(); + +// Pick any media type +await camera.pickImages() + .all() + .multiple() + .maxItems(10); + +// Single image selection +await camera.pickImages() + .images(); +``` + + + + ## PendingVideoRecorder The fluent API returned by `recordVideo()` provides several methods for configuring video recording: @@ -139,6 +229,10 @@ Fired when a photo is taken with the camera. **Payload:** `string $path` - File path to the captured photo + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Camera\PhotoTaken; @@ -151,6 +245,55 @@ public function handlePhotoTaken(string $path) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const photoPath = ref(''); + +const handlePhotoTaken = (payload) => { + photoPath.value = payload.path; + processPhoto(payload.path); +}; + +onMounted(() => { + on(Events.Camera.PhotoTaken, handlePhotoTaken); +}); + +onUnmounted(() => { + off(Events.Camera.PhotoTaken, handlePhotoTaken); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [photoPath, setPhotoPath] = useState(''); + +const handlePhotoTaken = (payload) => { + setPhotoPath(payload.path); + processPhoto(payload.path); +}; + +useEffect(() => { + on(Events.Camera.PhotoTaken, handlePhotoTaken); + + return () => { + off(Events.Camera.PhotoTaken, handlePhotoTaken); + }; +}, []); +``` + + + + ### `VideoRecorded` Fired when a video is successfully recorded. @@ -160,6 +303,10 @@ Fired when a video is successfully recorded. - `string $mimeType` - Video MIME type (default: `'video/mp4'`) - `?string $id` - Optional identifier if set via `id()` method + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Camera\VideoRecorded; @@ -177,6 +324,65 @@ public function handleVideoRecorded(string $path, string $mimeType, ?string $id } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const videoPath = ref(''); + +const handleVideoRecorded = (payload) => { + const { path, mimeType, id } = payload; + videoPath.value = path; + processVideo(path); + + if (id === 'my-upload-video') { + uploadVideo(path); + } +}; + +onMounted(() => { + on(Events.Camera.VideoRecorded, handleVideoRecorded); +}); + +onUnmounted(() => { + off(Events.Camera.VideoRecorded, handleVideoRecorded); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [videoPath, setVideoPath] = useState(''); + +const handleVideoRecorded = (payload) => { + const { path, mimeType, id } = payload; + setVideoPath(path); + processVideo(path); + + if (id === 'my-upload-video') { + uploadVideo(path); + } +}; + +useEffect(() => { + on(Events.Camera.VideoRecorded, handleVideoRecorded); + + return () => { + off(Events.Camera.VideoRecorded, handleVideoRecorded); + }; +}, []); +``` + + + + ### `VideoCancelled` Fired when video recording is cancelled by the user. @@ -185,6 +391,10 @@ Fired when video recording is cancelled by the user. - `bool $cancelled` - Always `true` - `?string $id` - Optional identifier if set via `id()` method + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Camera\VideoCancelled; @@ -197,12 +407,59 @@ public function handleVideoCancelled(bool $cancelled, ?string $id = null) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { onMounted, onUnmounted } from 'vue'; + +const handleVideoCancelled = (payload) => { + notifyUser('Video recording was cancelled'); +}; + +onMounted(() => { + on(Events.Camera.VideoCancelled, handleVideoCancelled); +}); + +onUnmounted(() => { + off(Events.Camera.VideoCancelled, handleVideoCancelled); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useEffect } from 'react'; + +const handleVideoCancelled = (payload) => { + notifyUser('Video recording was cancelled'); +}; + +useEffect(() => { + on(Events.Camera.VideoCancelled, handleVideoCancelled); + + return () => { + off(Events.Camera.VideoCancelled, handleVideoCancelled); + }; +}, []); +``` + + + + ### `MediaSelected` Fired when media is selected from the gallery. **Payload:** `array $media` - Array of selected media items + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Gallery\MediaSelected; @@ -217,6 +474,63 @@ public function handleMediaSelected($success, $files, $count) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const selectedFiles = ref([]); + +const handleMediaSelected = (payload) => { + const { success, files, count } = payload; + + if (success) { + selectedFiles.value = files; + files.forEach(file => processMedia(file)); + } +}; + +onMounted(() => { + on(Events.Gallery.MediaSelected, handleMediaSelected); +}); + +onUnmounted(() => { + off(Events.Gallery.MediaSelected, handleMediaSelected); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [selectedFiles, setSelectedFiles] = useState([]); + +const handleMediaSelected = (payload) => { + const { success, files, count } = payload; + + if (success) { + setSelectedFiles(files); + files.forEach(file => processMedia(file)); + } +}; + +useEffect(() => { + on(Events.Gallery.MediaSelected, handleMediaSelected); + + return () => { + off(Events.Gallery.MediaSelected, handleMediaSelected); + }; +}, []); +``` + + + + ## Storage Locations Media files are stored in different locations depending on the platform: diff --git a/resources/views/docs/mobile/2/apis/device.md b/resources/views/docs/mobile/2/apis/device.md index e0a6a24b..ccf79314 100644 --- a/resources/views/docs/mobile/2/apis/device.md +++ b/resources/views/docs/mobile/2/apis/device.md @@ -6,10 +6,25 @@ order: 400 ## Overview The Device API exposes internal information about the device, such as the model and operating system version, along with user information such as unique ids. + + + + + ```php use Native\Mobile\Facades\Device; ``` + + + +```js +import { device } from '#nativephp'; +``` + + + + ## Methods ### `getId()` @@ -18,12 +33,54 @@ Return a unique identifier for the device. Returns: `string` + + + + +```php +$id = Device::getId(); +``` + + + + +```js +const result = await device.getId(); +const deviceId = result.id; +``` + + + + ### `getInfo()` Return information about the underlying device/os/platform. Returns JSON encoded: `string` + + + + +```php +$info = Device::getInfo(); +$deviceInfo = json_decode($info); +``` + + + + +```js +const result = await device.getInfo(); +const deviceInfo = JSON.parse(result.info); + +console.log(deviceInfo.platform); // 'ios' or 'android' +console.log(deviceInfo.model); // e.g., 'iPhone13,4' +console.log(deviceInfo.osVersion); // e.g., '17.0' +``` + + + ### `vibrate()` @@ -31,20 +88,48 @@ Triggers device vibration for tactile feedback. **Returns:** `void` + + + + ```php Device::vibrate(); ``` + + + +```js +await device.vibrate(); +``` + + + + ### `flashlight()` Toggles the device flashlight (camera flash LED) on and off. **Returns:** `void` + + + + ```php Device::flashlight(); // Toggle flashlight state ``` + + + +```js +const result = await device.flashlight(); +console.log(result.state); // true = on, false = off +``` + + + ### `getBatteryInfo()` @@ -52,6 +137,29 @@ Return information about the battery. Returns JSON encoded: `string` + + + + +```php +$info = Device::getBatteryInfo(); +$batteryInfo = json_decode($info); +``` + + + + +```js +const result = await device.getBatteryInfo(); +const batteryInfo = JSON.parse(result.info); + +console.log(batteryInfo.batteryLevel); // 0-1 (e.g., 0.85 = 85%) +console.log(batteryInfo.isCharging); // true/false +``` + + + + ## Device Info | Prop | Type | Description diff --git a/resources/views/docs/mobile/2/apis/dialog.md b/resources/views/docs/mobile/2/apis/dialog.md index 16b583ca..1a72f6be 100644 --- a/resources/views/docs/mobile/2/apis/dialog.md +++ b/resources/views/docs/mobile/2/apis/dialog.md @@ -7,10 +7,24 @@ order: 500 The Dialog API provides access to native UI elements like alerts, toasts, and sharing interfaces. + + + + ```php use Native\Mobile\Facades\Dialog; ``` + + + +```js +import { dialog, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `alert()` @@ -24,9 +38,13 @@ Displays a native alert dialog with customizable buttons. **Button Positioning:** - **1 button** - Positive (OK/Confirm) -- **2 buttons** - Negative (Cancel) + Positive (OK/Confirm) +- **2 buttons** - Negative (Cancel) + Positive (OK/Confirm) - **3 buttons** - Negative (Cancel) + Neutral (Maybe) + Positive (OK/Confirm) + + + + ```php Dialog::alert( 'Confirm Action', @@ -35,18 +53,56 @@ Dialog::alert( ); ``` + + + +```js +// Simple usage +await dialog.alert('Confirm Action', 'Are you sure you want to delete this item?', ['Cancel', 'Delete']); + +// Fluent builder API +await dialog.alert() + .title('Confirm Action') + .message('Are you sure you want to delete this item?') + .buttons(['Cancel', 'Delete']); + +// Quick confirm dialog (OK/Cancel) +await dialog.alert() + .confirm('Confirm Action', 'Are you sure?'); + +// Quick destructive confirm (Cancel/Delete) +await dialog.alert() + .confirmDelete('Delete Item', 'This action cannot be undone.'); +``` + + + + ### `toast()` Displays a brief toast notification message. - **Parameters:** - `string $message` - The message to display + + + + ```php Dialog::toast('Item saved successfully!'); ``` + + + +```js +await dialog.toast('Item saved successfully!'); +``` + + + + #### Good toast messages - Short and clear @@ -83,10 +139,14 @@ Dialog::share( Fired when a button is pressed in an alert dialog. -**Payload:** +**Payload:** - `int $index` - Index of the pressed button (0-based) - `string $label` - Label/text of the pressed button + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Alert\ButtonPressed; @@ -107,3 +167,66 @@ public function handleAlertButton($index, $label) } } ``` + + + + +```js +import { dialog, on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const buttonLabel = ref(''); + +const handleButtonPressed = (payload) => { + const { index, label } = payload; + buttonLabel.value = label; + + if (index === 0) { + dialog.toast(`You pressed '${label}'`); + } else if (index === 1) { + performAction(); + dialog.toast(`You pressed '${label}'`); + } +}; + +onMounted(() => { + on(Events.Alert.ButtonPressed, handleButtonPressed); +}); + +onUnmounted(() => { + off(Events.Alert.ButtonPressed, handleButtonPressed); +}); +``` + + + + +```jsx +import { dialog, on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [buttonLabel, setButtonLabel] = useState(''); + +const handleButtonPressed = (payload) => { + const { index, label } = payload; + setButtonLabel(label); + + if (index === 0) { + dialog.toast(`You pressed '${label}'`); + } else if (index === 1) { + performAction(); + dialog.toast(`You pressed '${label}'`); + } +}; + +useEffect(() => { + on(Events.Alert.ButtonPressed, handleButtonPressed); + + return () => { + off(Events.Alert.ButtonPressed, handleButtonPressed); + }; +}, []); +``` + + + diff --git a/resources/views/docs/mobile/2/apis/file.md b/resources/views/docs/mobile/2/apis/file.md index 4317e8b7..a2c266d0 100644 --- a/resources/views/docs/mobile/2/apis/file.md +++ b/resources/views/docs/mobile/2/apis/file.md @@ -7,10 +7,24 @@ order: 600 The File API provides utilities for managing files on the device. You can move files between directories or copy files to new locations. These operations execute synchronously and return a boolean indicating success or failure. + + + + ```php use Native\Mobile\Facades\File; ``` + + + +```js +import { file } from '#nativephp'; +``` + + + + ## Methods ### `move(string $from, string $to)` @@ -23,6 +37,10 @@ Moves a file from one location to another. The source file is removed from its o **Returns:** `bool` - `true` on success, `false` on failure + + + + ```php // Move a captured photo to the app's storage directory $success = File::move( @@ -37,6 +55,26 @@ if ($success) { } ``` + + + +```js +// Move a captured photo to the app's storage directory +const result = await file.move( + '/var/mobile/Containers/Data/tmp/photo.jpg', + '/var/mobile/Containers/Data/Documents/photos/photo.jpg' +); + +if (result.success) { + // File moved successfully +} else { + // Move operation failed +} +``` + + + + ### `copy(string $from, string $to)` Copies a file to a new location. The source file remains in its original location. @@ -47,6 +85,10 @@ Copies a file to a new location. The source file remains in its original locatio **Returns:** `bool` - `true` on success, `false` on failure + + + + ```php // Copy a file to create a backup $success = File::copy( @@ -61,6 +103,26 @@ if ($success) { } ``` + + + +```js +// Copy a file to create a backup +const result = await file.copy( + '/var/mobile/Containers/Data/Documents/document.pdf', + '/var/mobile/Containers/Data/Documents/backups/document.pdf' +); + +if (result.success) { + // File copied successfully +} else { + // Copy operation failed +} +``` + + + + ## Examples ### Moving Captured Media diff --git a/resources/views/docs/mobile/2/apis/geolocation.md b/resources/views/docs/mobile/2/apis/geolocation.md index 7528bfe9..6e0d361d 100644 --- a/resources/views/docs/mobile/2/apis/geolocation.md +++ b/resources/views/docs/mobile/2/apis/geolocation.md @@ -7,10 +7,24 @@ order: 700 The Geolocation API provides access to the device's GPS and location services to determine the user's current position. + + + + ```php use Native\Mobile\Facades\Geolocation; ``` + + + +```js +import { geolocation, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `getCurrentPosition()` @@ -22,6 +36,10 @@ Gets the current GPS location of the device. **Returns:** Location data via events + + + + ```php // Get location using network positioning (faster, less accurate) Geolocation::getCurrentPosition(); @@ -30,26 +48,78 @@ Geolocation::getCurrentPosition(); Geolocation::getCurrentPosition(true); ``` + + + +```js +// Get location using network positioning (faster, less accurate) +await geolocation.getCurrentPosition(); + +// Get location using GPS (slower, more accurate) +await geolocation.getCurrentPosition() + .fineAccuracy(true); + +// With identifier for tracking +await geolocation.getCurrentPosition() + .fineAccuracy(true) + .id('current-loc'); +``` + + + + ### `checkPermissions()` Checks the current location permissions status. **Returns:** Permission status via events + + + + ```php Geolocation::checkPermissions(); ``` + + + +```js +await geolocation.checkPermissions(); +``` + + + + ### `requestPermissions()` Requests location permissions from the user. **Returns:** Permission status after request via events + + + + ```php Geolocation::requestPermissions(); ``` + + + +```js +await geolocation.requestPermissions(); + +// With remember flag +await geolocation.requestPermissions() + .remember(); +``` + + + + ## Events ### `LocationReceived` @@ -65,6 +135,10 @@ Fired when location data is requested (success or failure). - `string $provider` - Location provider used (GPS, network, etc.) - `string $error` - Error message (when unsuccessful) + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Geolocation\LocationReceived; @@ -83,13 +157,76 @@ public function handleLocationReceived( } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const location = ref({ latitude: null, longitude: null }); +const error = ref(''); + +const handleLocationReceived = (payload) => { + if (payload.success) { + location.value = { + latitude: payload.latitude, + longitude: payload.longitude + }; + } else { + error.value = payload.error; + } +}; + +onMounted(() => { + on(Events.Geolocation.LocationReceived, handleLocationReceived); +}); + +onUnmounted(() => { + off(Events.Geolocation.LocationReceived, handleLocationReceived); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [location, setLocation] = useState({ latitude: null, longitude: null }); +const [error, setError] = useState(''); + +const handleLocationReceived = (payload) => { + if (payload.success) { + setLocation({ + latitude: payload.latitude, + longitude: payload.longitude + }); + } else { + setError(payload.error); + } +}; + +useEffect(() => { + on(Events.Geolocation.LocationReceived, handleLocationReceived); + + return () => { + off(Events.Geolocation.LocationReceived, handleLocationReceived); + }; +}, []); +``` + + + + ### `PermissionStatusReceived` Fired when permission status is checked. **Event Parameters:** - `string $location` - Overall location permission status -- `string $coarseLocation` - Coarse location permission status +- `string $coarseLocation` - Coarse location permission status - `string $fineLocation` - Fine location permission status **Permission Values:** @@ -97,6 +234,10 @@ Fired when permission status is checked. - `'denied'` - Permission is denied - `'not_determined'` - Permission not yet requested + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Geolocation\PermissionStatusReceived; @@ -108,6 +249,55 @@ public function handlePermissionStatus($location, $coarseLocation, $fineLocation } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const permissionStatus = ref(''); + +const handlePermissionStatus = (payload) => { + const { location } = payload; + permissionStatus.value = location; +}; + +onMounted(() => { + on(Events.Geolocation.PermissionStatusReceived, handlePermissionStatus); +}); + +onUnmounted(() => { + off(Events.Geolocation.PermissionStatusReceived, handlePermissionStatus); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [permissionStatus, setPermissionStatus] = useState(''); + +const handlePermissionStatus = (payload) => { + const { location } = payload; + setPermissionStatus(location); +}; + +useEffect(() => { + on(Events.Geolocation.PermissionStatusReceived, handlePermissionStatus); + + return () => { + off(Events.Geolocation.PermissionStatusReceived, handlePermissionStatus); + }; +}, []); +``` + + + + ### `PermissionRequestResult` Fired when a permission request completes. @@ -122,6 +312,10 @@ Fired when a permission request completes. **Special Values:** - `'permanently_denied'` - User has permanently denied permission + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Geolocation\PermissionRequestResult; @@ -139,6 +333,69 @@ public function handlePermissionRequest($location, $coarseLocation, $fineLocatio } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const error = ref(''); + +const handlePermissionRequest = (payload) => { + const { location, coarseLocation, fineLocation } = payload; + + if (location === 'permanently_denied') { + error.value = 'Please enable location in Settings.'; + } else if (coarseLocation === 'granted' || fineLocation === 'granted') { + getCurrentLocation(); + } else { + error.value = 'Location permission is required.'; + } +}; + +onMounted(() => { + on(Events.Geolocation.PermissionRequestResult, handlePermissionRequest); +}); + +onUnmounted(() => { + off(Events.Geolocation.PermissionRequestResult, handlePermissionRequest); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [error, setError] = useState(''); + +const handlePermissionRequest = (payload) => { + const { location, coarseLocation, fineLocation } = payload; + + if (location === 'permanently_denied') { + setError('Please enable location in Settings.'); + } else if (coarseLocation === 'granted' || fineLocation === 'granted') { + getCurrentLocation(); + } else { + setError('Location permission is required.'); + } +}; + +useEffect(() => { + on(Events.Geolocation.PermissionRequestResult, handlePermissionRequest); + + return () => { + off(Events.Geolocation.PermissionRequestResult, handlePermissionRequest); + }; +}, []); +``` + + + + ## Privacy Considerations - **Explain why** you need location access before requesting diff --git a/resources/views/docs/mobile/2/apis/haptics.md b/resources/views/docs/mobile/2/apis/haptics.md index 14876f75..84e8ad2f 100644 --- a/resources/views/docs/mobile/2/apis/haptics.md +++ b/resources/views/docs/mobile/2/apis/haptics.md @@ -7,10 +7,24 @@ order: 800 The Haptics API provides access to the device's vibration and haptic feedback system for tactile user interactions. + + + + ```php use Native\Mobile\Facades\Haptics; ``` + + + +```js +import { device } from '#nativephp'; +``` + + + + ## Methods ### `vibrate()` @@ -19,10 +33,24 @@ Triggers device vibration for tactile feedback. **Returns:** `void` + + + + ```php Haptics::vibrate(); ``` + + + +```js +await device.vibrate(); +``` + + + + **Use haptics for:** Button presses, form validation, important notifications, game events. **Avoid haptics for:** Frequent events, background processes, minor updates. diff --git a/resources/views/docs/mobile/2/apis/microphone.md b/resources/views/docs/mobile/2/apis/microphone.md index 88c2ab6a..067d0d63 100644 --- a/resources/views/docs/mobile/2/apis/microphone.md +++ b/resources/views/docs/mobile/2/apis/microphone.md @@ -8,51 +8,130 @@ order: 900 The Microphone API provides access to the device's microphone for recording audio. It offers a fluent interface for starting and managing recordings, tracking them with unique identifiers, and responding to completion events. + + + + ```php use Native\Mobile\Facades\Microphone; ``` + + + +```js +import { microphone, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `record()` Start an audio recording. Returns a `PendingMicrophone` instance that controls the recording lifecycle. + + + + ```php Microphone::record()->start(); ``` + + + +```js +// Basic recording +await microphone.record(); + +// With identifier for tracking +await microphone.record() + .id('voice-memo'); +``` + + + + ### `stop()` Stop the current audio recording. If this results in a saved file, this dispatches the `AudioRecorded` event with the recording file path. + + + + ```php Microphone::stop(); ``` + + + +```js +await microphone.stop(); +``` + + + + ### `pause()` Pause the current audio recording without ending it. + + + + ```php Microphone::pause(); ``` + + + +```js +await microphone.pause(); +``` + + + + ### `resume()` Resume a paused audio recording. + + + + ```php Microphone::resume(); ``` + + + +```js +await microphone.resume(); +``` + + + + ### `getStatus()` Get the current recording status. **Returns:** `string` - One of: `"idle"`, `"recording"`, or `"paused"` + + + + ```php $status = Microphone::getStatus(); @@ -61,12 +140,30 @@ if ($status === 'recording') { } ``` + + + +```js +const result = await microphone.getStatus(); + +if (result.status === 'recording') { + // A recording is in progress +} +``` + + + + ### `getRecording()` Get the file path to the last recorded audio file. **Returns:** `string|null` - Path to the last recording, or `null` if none exists + + + + ```php $path = Microphone::getRecording(); @@ -75,6 +172,20 @@ if ($path) { } ``` + + + +```js +const result = await microphone.getRecording(); + +if (result.path) { + // Process the recording file +} +``` + + + + ## PendingMicrophone The `PendingMicrophone` provides a fluent interface for configuring and starting audio recordings. Most methods return @@ -174,6 +285,10 @@ Dispatched when an audio recording completes. The event includes the file path a - `string $mimeType` - MIME type of the audio (default: `'audio/m4a'`) - `?string $id` - The recorder's ID, if one was set + + + + ```php #[OnNative(MicrophoneRecorded::class)] public function handleAudioRecorded(string $path, string $mimeType, ?string $id) @@ -187,6 +302,55 @@ public function handleAudioRecorded(string $path, string $mimeType, ?string $id) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { ref, onMounted, onUnmounted } from 'vue'; + +const recordings = ref([]); + +const handleAudioRecorded = (payload) => { + const { path, mimeType, id } = payload; + recordings.value.push({ path, mimeType, id }); +}; + +onMounted(() => { + on(Events.Microphone.MicrophoneRecorded, handleAudioRecorded); +}); + +onUnmounted(() => { + off(Events.Microphone.MicrophoneRecorded, handleAudioRecorded); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useState, useEffect } from 'react'; + +const [recordings, setRecordings] = useState([]); + +const handleAudioRecorded = (payload) => { + const { path, mimeType, id } = payload; + setRecordings(prev => [...prev, { path, mimeType, id }]); +}; + +useEffect(() => { + on(Events.Microphone.MicrophoneRecorded, handleAudioRecorded); + + return () => { + off(Events.Microphone.MicrophoneRecorded, handleAudioRecorded); + }; +}, []); +``` + + + + ## Notes - **Microphone Permission:** The first time your app requests microphone access, users will be prompted for permission. If denied, recording functions will fail silently. diff --git a/resources/views/docs/mobile/2/apis/network.md b/resources/views/docs/mobile/2/apis/network.md index 985b848c..b206dc8c 100644 --- a/resources/views/docs/mobile/2/apis/network.md +++ b/resources/views/docs/mobile/2/apis/network.md @@ -7,10 +7,24 @@ order: 1000 The Network API provides access to the device's current network status and connection information. You can check whether the device is connected, determine the connection type, and detect metered or low-bandwidth conditions. + + + + ```php use Native\Mobile\Facades\Network; ``` + + + +```js +import { network } from '#nativephp'; +``` + + + + ## Methods ### `status()` @@ -26,6 +40,10 @@ The returned object contains the following properties: - `isExpensive` (bool) - Whether the connection is metered/cellular (iOS only, always `false` on Android) - `isConstrained` (bool) - Whether Low Data Mode is enabled (iOS only, always `false` on Android) + + + + ```php $status = Network::status(); @@ -37,6 +55,23 @@ if ($status) { } ``` + + + +```js +const status = await network.status(); + +if (status) { + console.log(status.connected); // true/false + console.log(status.type); // "wifi", "cellular", "ethernet", or "unknown" + console.log(status.isExpensive); // true/false (iOS only) + console.log(status.isConstrained); // true/false (iOS only) +} +``` + + + + ## Notes - **iOS-specific properties:** The `isExpensive` and `isConstrained` properties are only meaningful on iOS. On Android, these values will always be `false`. diff --git a/resources/views/docs/mobile/2/apis/push-notifications.md b/resources/views/docs/mobile/2/apis/push-notifications.md index ce8c837c..a919d5f7 100644 --- a/resources/views/docs/mobile/2/apis/push-notifications.md +++ b/resources/views/docs/mobile/2/apis/push-notifications.md @@ -7,10 +7,24 @@ order: 1100 The PushNotifications API handles device registration for Firebase Cloud Messaging to receive push notifications. + + + + ```php use Native\Mobile\Facades\PushNotifications; ``` + + + +```js +import { pushNotifications, on, off, Events } from '#nativephp'; +``` + + + + ## Methods ### `enroll()` @@ -19,12 +33,55 @@ Requests permission and enrolls the device for push notifications. **Returns:** `void` + + + + +```php +PushNotifications::enroll(); +``` + + + + +```js +// Basic enrollment +await pushNotifications.enroll(); + +// With identifier for tracking +await pushNotifications.enroll() + .id('main-enrollment') + .remember(); +``` + + + + ### `getToken()` Retrieves the current push notification token for this device. **Returns:** `string|null` - The FCM token, or `null` if not available + + + + +```php +$token = PushNotifications::getToken(); +``` + + + + +```js +const result = await pushNotifications.getToken(); +const token = result.token; // APNS token on iOS, FCM token on Android +``` + + + + ## Events ### `TokenGenerated` @@ -33,6 +90,10 @@ Fired when a push notification token is successfully generated. **Payload:** `string $token` - The FCM token for this device + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\PushNotification\TokenGenerated; @@ -45,6 +106,53 @@ public function handlePushToken(string $token) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { onMounted, onUnmounted } from 'vue'; + +const handleTokenGenerated = (payload) => { + const { token } = payload; + // Send token to your backend + sendTokenToServer(token); +}; + +onMounted(() => { + on(Events.PushNotification.TokenGenerated, handleTokenGenerated); +}); + +onUnmounted(() => { + off(Events.PushNotification.TokenGenerated, handleTokenGenerated); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useEffect } from 'react'; + +const handleTokenGenerated = (payload) => { + const { token } = payload; + // Send token to your backend + sendTokenToServer(token); +}; + +useEffect(() => { + on(Events.PushNotification.TokenGenerated, handleTokenGenerated); + + return () => { + off(Events.PushNotification.TokenGenerated, handleTokenGenerated); + }; +}, []); +``` + + + + ## Permission Flow 1. User taps "Enable Notifications" diff --git a/resources/views/docs/mobile/2/apis/scanner.md b/resources/views/docs/mobile/2/apis/scanner.md index 1f465489..4702d8ca 100644 --- a/resources/views/docs/mobile/2/apis/scanner.md +++ b/resources/views/docs/mobile/2/apis/scanner.md @@ -7,13 +7,31 @@ order: 1200 The Scanner API provides cross-platform barcode and QR code scanning capabilities through a native camera interface. + + + + ```php use Native\Mobile\Facades\Scanner; use Native\Mobile\Events\Scanner\CodeScanned; ``` + + + +```js +import { scanner, on, off, Events } from '#nativephp'; +``` + + + + ## Basic Usage + + + + ```php // Open scanner Scanner::scan(); @@ -26,42 +44,183 @@ public function handleScan($data, $format, $id = null) } ``` + + + +```js +import { scanner, dialog, on, off, Events } from '#nativephp'; +import { onMounted, onUnmounted } from 'vue'; + +// Open scanner +await scanner.scan(); + +// Listen for scan results +const handleScan = (payload) => { + const { data, format, id } = payload; + dialog.toast(`Scanned: ${data}`); +}; + +onMounted(() => { + on(Events.Scanner.CodeScanned, handleScan); +}); + +onUnmounted(() => { + off(Events.Scanner.CodeScanned, handleScan); +}); +``` + + + + +```jsx +import { scanner, dialog, on, off, Events } from '#nativephp'; +import { useEffect } from 'react'; + +// Open scanner +await scanner.scan(); + +// Listen for scan results +const handleScan = (payload) => { + const { data, format, id } = payload; + dialog.toast(`Scanned: ${data}`); +}; + +useEffect(() => { + on(Events.Scanner.CodeScanned, handleScan); + + return () => { + off(Events.Scanner.CodeScanned, handleScan); + }; +}, []); +``` + + + + ## Configuration Methods ### `prompt(string $prompt)` Set custom prompt text displayed on the scanner screen. + + + + ```php Scanner::scan()->prompt('Scan product barcode'); ``` + + + +```js +await scanner.scan() + .prompt('Scan product barcode'); +``` + + + + ### `continuous(bool $continuous = true)` Keep scanner open to scan multiple codes. Default is `false` (closes after first scan). + + + + ```php Scanner::scan()->continuous(true); ``` + + + +```js +await scanner.scan() + .continuous(true); +``` + + + + ### `formats(array $formats)` Specify which barcode formats to scan. Default is `['qr']`. **Available formats:** `qr`, `ean13`, `ean8`, `code128`, `code39`, `upca`, `upce`, `all` + + + + ```php Scanner::scan()->formats(['qr', 'ean13', 'code128']); ``` + + + +```js +await scanner.scan() + .formats(['qr', 'ean13', 'code128']); +``` + + + + ### `id(string $id)` Set a unique identifier for the scan session. Useful for handling different scan contexts. + + + + ```php Scanner::scan()->id('checkout-scanner'); ``` + + + +```js +await scanner.scan() + .id('checkout-scanner'); +``` + + + + +### Combined Example + + + + + +```php +Scanner::scan() + ->prompt('Scan your ticket') + ->continuous(true) + ->formats(['qr', 'ean13']) + ->id('ticket-scanner'); +``` + + + + +```js +await scanner.scan() + .prompt('Scan your ticket') + .continuous(true) + .formats(['qr', 'ean13']) + .id('ticket-scanner'); +``` + + + + ## Events ### `CodeScanned` @@ -73,6 +232,10 @@ Fired when a barcode is successfully scanned. - `string $format` - The barcode format - `string|null $id` - The scan session ID (if set) + + + + ```php #[OnNative(CodeScanned::class)] public function handleScan($data, $format, $id = null) @@ -83,6 +246,57 @@ public function handleScan($data, $format, $id = null) } ``` + + + +```js +import { on, off, Events } from '#nativephp'; +import { onMounted, onUnmounted } from 'vue'; + +const handleScan = (payload) => { + const { data, format, id } = payload; + + if (id === 'product-scanner') { + addProduct(data); + } +}; + +onMounted(() => { + on(Events.Scanner.CodeScanned, handleScan); +}); + +onUnmounted(() => { + off(Events.Scanner.CodeScanned, handleScan); +}); +``` + + + + +```jsx +import { on, off, Events } from '#nativephp'; +import { useEffect } from 'react'; + +const handleScan = (payload) => { + const { data, format, id } = payload; + + if (id === 'product-scanner') { + addProduct(data); + } +}; + +useEffect(() => { + on(Events.Scanner.CodeScanned, handleScan); + + return () => { + off(Events.Scanner.CodeScanned, handleScan); + }; +}, []); +``` + + + + ## Notes - **Platform Support:** diff --git a/resources/views/docs/mobile/2/apis/secure-storage.md b/resources/views/docs/mobile/2/apis/secure-storage.md index 35a58127..7dac7fb4 100644 --- a/resources/views/docs/mobile/2/apis/secure-storage.md +++ b/resources/views/docs/mobile/2/apis/secure-storage.md @@ -8,10 +8,24 @@ order: 1300 The SecureStorage API provides secure storage using the device's native keychain (iOS) or keystore (Android). It's ideal for storing sensitive data like tokens, passwords, and user credentials. + + + + ```php use Native\Mobile\Facades\SecureStorage; ``` + + + +```js +import { secureStorage } from '#nativephp'; +``` + + + + ## Methods ### `set()` @@ -24,10 +38,28 @@ Stores a secure value in the native keychain or keystore. **Returns:** `bool` - `true` if successfully stored, `false` otherwise + + + + ```php SecureStorage::set('api_token', 'abc123xyz'); ``` + + + +```js +const result = await secureStorage.set('api_token', 'abc123xyz'); + +if (result.success) { + // Value stored securely +} +``` + + + + ### `get()` Retrieves a secure value from the native keychain or keystore. @@ -37,10 +69,25 @@ Retrieves a secure value from the native keychain or keystore. **Returns:** `string|null` - The stored value or `null` if not found + + + + ```php $token = SecureStorage::get('api_token'); ``` + + + +```js +const result = await secureStorage.get('api_token'); +const token = result.value; // or null if not found +``` + + + + ### `delete()` Deletes a secure value from the native keychain or keystore. @@ -50,6 +97,28 @@ Deletes a secure value from the native keychain or keystore. **Returns:** `bool` - `true` if successfully deleted, `false` otherwise + + + + +```php +SecureStorage::delete('api_token'); +``` + + + + +```js +const result = await secureStorage.delete('api_token'); + +if (result.success) { + // Value deleted +} +``` + + + + ## Platform Implementation ### iOS - Keychain Services diff --git a/resources/views/docs/mobile/2/apis/share.md b/resources/views/docs/mobile/2/apis/share.md index 38fc154d..ddfd28ef 100644 --- a/resources/views/docs/mobile/2/apis/share.md +++ b/resources/views/docs/mobile/2/apis/share.md @@ -7,10 +7,24 @@ order: 1400 The Share API enables users to share content from your app using the native share sheet. On iOS, this opens the native share menu with options like Messages, Mail, and social media apps. On Android, it launches the system share intent with available apps. + + + + ```php use Native\Mobile\Facades\Share; ``` + + + +```js +import { share } from '#nativephp'; +``` + + + + ## Methods ### `url()` @@ -24,6 +38,10 @@ Share a URL using the native share dialog. **Returns:** `void` + + + + ```php Share::url( title: 'Check this out', @@ -32,6 +50,20 @@ Share::url( ); ``` + + + +```js +await share.url( + 'Check this out', + 'I found something interesting', + 'https://example.com/article' +); +``` + + + + ### `file()` Share a file using the native share dialog. @@ -43,6 +75,10 @@ Share a file using the native share dialog. **Returns:** `void` + + + + ```php Share::file( title: 'Share Document', @@ -51,12 +87,30 @@ Share::file( ); ``` + + + +```js +await share.file( + 'Share Document', + 'Check out this PDF', + '/path/to/document.pdf' +); +``` + + + + ## Examples ### Sharing a Website Link Share a link to your app's website or external content. + + + + ```php Share::url( title: 'My Awesome App', @@ -65,10 +119,28 @@ Share::url( ); ``` + + + +```js +await share.url( + 'My Awesome App', + 'Download my app today!', + 'https://myapp.com' +); +``` + + + + ### Sharing Captured Photos Share a photo that was captured with the camera. + + + + ```php use Native\Mobile\Attributes\OnNative; use Native\Mobile\Events\Camera\PhotoTaken; @@ -84,6 +156,57 @@ public function handlePhotoTaken(string $path) } ``` + + + +```js +import { share, on, off, Events } from '#nativephp'; +import { onMounted, onUnmounted } from 'vue'; + +const handlePhotoTaken = (payload) => { + share.file( + 'My Photo', + 'Check out this photo I just took!', + payload.path + ); +}; + +onMounted(() => { + on(Events.Camera.PhotoTaken, handlePhotoTaken); +}); + +onUnmounted(() => { + off(Events.Camera.PhotoTaken, handlePhotoTaken); +}); +``` + + + + +```jsx +import { share, on, off, Events } from '#nativephp'; +import { useEffect } from 'react'; + +const handlePhotoTaken = (payload) => { + share.file( + 'My Photo', + 'Check out this photo I just took!', + payload.path + ); +}; + +useEffect(() => { + on(Events.Camera.PhotoTaken, handlePhotoTaken); + + return () => { + off(Events.Camera.PhotoTaken, handlePhotoTaken); + }; +}, []); +``` + + + + ## Notes - The native share sheet opens, allowing users to choose which app to share with (Messages, Email, social media, etc.) diff --git a/resources/views/docs/mobile/2/apis/system.md b/resources/views/docs/mobile/2/apis/system.md index 5ea860e7..78c165af 100644 --- a/resources/views/docs/mobile/2/apis/system.md +++ b/resources/views/docs/mobile/2/apis/system.md @@ -7,10 +7,26 @@ order: 1500 The System API provides access to basic system functions like flashlight control and platform detection. + + + + ```php use Native\Mobile\Facades\System; ``` + + + +```js +import { system } from '#nativephp'; +// or import individual functions +import { isIos, isAndroid, isMobile } from '#nativephp'; +``` + + + + ## Methods ### `flashlight()` - Deprecated, see [Device](device) @@ -19,24 +35,113 @@ Toggles the device flashlight (camera flash LED) on and off. **Returns:** `void` + + + + ```php System::flashlight(); // Toggle flashlight state ``` + + + +```js +// Use device.flashlight() instead +import { device } from '#nativephp'; + +await device.flashlight(); +``` + + + + ### `isIos()` Determines if the current device is running iOS. **Returns:** `true` if iOS, `false` otherwise + + + + +```php +if (System::isIos()) { + // iOS-specific code +} +``` + + + + +```js +const ios = await system.isIos(); + +if (ios) { + // iOS-specific code +} +``` + + + + ### `isAndroid()` Determines if the current device is running Android. **Returns:** `true` if Android, `false` otherwise + + + + +```php +if (System::isAndroid()) { + // Android-specific code +} +``` + + + + +```js +const android = await system.isAndroid(); + +if (android) { + // Android-specific code +} +``` + + + + ### `isMobile()` Determines if the current device is running Android or iOS. **Returns:** `true` if Android or iOS, `false` otherwise + + + + + +```php +if (System::isMobile()) { + // Mobile-specific code +} +``` + + + + +```js +const mobile = await system.isMobile(); + +if (mobile) { + // Mobile-specific code +} +``` + + +