sitepong 0.1.10 → 0.1.11

package/README.md

@@ -694,27 +694,92 @@ Targeting options (provide at least one):
 
 #### Live Activities (iOS)
 
-Register the per-instance push token from your native bridge:
+SitePong ships a turnkey Live Activity package — a generic SwiftUI Widget Extension that the bundled config plugin generates at prebuild, plus a JavaScript API that drives it from data. **No Swift required.** Customers compose their Live Activity using SF Symbols, custom progress bars, and styled text fields entirely from JS.
+
+Install the package:
+
+```bash
+npm install @sitepong/expo-live-activity
+```
+
+Add the config plugin to `app.json` / `app.config.js`:
+
+```json
+{
+  "plugins": ["@sitepong/expo-live-activity"]
+}
+```
+
+Then prebuild and rebuild your app (`npx expo prebuild --clean`). The plugin creates a Widget Extension target named `SitePongLiveActivityWidget` containing the SitePong template, sets `NSSupportsLiveActivities` in the main app, and wires the extension into the Xcode project.
+
+Start a Live Activity from JavaScript:
 
 ```typescript
-import {
-  registerLiveActivityToken,
-  registerPushToStartToken,
-  endLiveActivity,
-} from '@sitepong/sdk/react-native';
+import { startLiveActivity, updateLiveActivity, endLiveActivity } from '@sitepong/expo-live-activity';
+
+const { activityId } = await startLiveActivity({
+  activityType: 'order-tracking',
+  attributes: { id: '#1234' },
+  contentState: {
+    title: 'Order #1234',
+    subtitle: 'Driver is on the way',
+    titleStyle:    { size: 16, weight: 'bold',    color: '#111827' },
+    subtitleStyle: { size: 14, weight: 'regular', color: '#6b7280' },
+    leadingIcon:  { symbol: 'shippingbox.fill', color: '#3b82f6' },
+    trailingIcon: { symbol: 'checkmark.seal.fill', color: '#10b981' }, // hidden until you set it
+    progress: {
+      style: 'bar-with-icon',  // 'bar' | 'bar-with-icon' | 'circular' | 'timer'
+      value: 0.6,
+      icon: 'car.fill',         // SF Symbol slides along the track
+      iconColor: '#3b82f6',
+      trackColor: '#e5e7eb',
+      fillColor: '#3b82f6',
+      label: '15 minutes away',
+    },
+  },
+});
+```
 
-// When ActivityKit gives you a push token for a running activity
-registerLiveActivityToken('DeliveryActivityAttributes', activity.id, pushToken, {
-  environment: 'production',
+Update it locally as state changes:
+
+```typescript
+await updateLiveActivity(activityId, {
+  title: 'Order #1234',
+  subtitle: 'Driver is two blocks away',
+  progress: { style: 'bar-with-icon', value: 0.9, icon: 'car.fill', fillColor: '#3b82f6' },
 });
+```
 
-// Or register a push-to-start token (iOS 17.2+) so the activity can be launched remotely
-registerPushToStartToken('DeliveryActivityAttributes', pushToStartToken, {
-  environment: 'production',
+Or update it remotely from your backend by calling `POST /api/push/live-activity` (see endpoint table below). The package automatically forwards the per-activity push token to SitePong on `startLiveActivity`, so backend updates reach the right device with no extra wiring.
+
+End the activity when the work completes:
+
+```typescript
+await endLiveActivity(activityId, {
+  finalContentState: {
+    title: 'Delivered',
+    leadingIcon: { symbol: 'checkmark.seal.fill', color: '#10b981' },
+  },
+  dismissalDate: Date.now() + 60_000, // remove from lock screen after 1 minute
 });
+```
+
+**Visibility-driven slots.** Every visual element in `contentState` is optional. The SwiftUI template hides slots whose value is omitted, so you control layout density entirely from data. Set `trailingIcon` only on the final "delivered" update and it appears; omit it everywhere else and it stays hidden.
+
+**Available styles.** Title and subtitle accept `size`, `weight` (`ultraLight`...`black`), `color` (hex), `italic`, `monospacedDigit`. Icons accept any SF Symbol name plus `color`, `weight`, `size`. Progress supports `bar`, `bar-with-icon` (the Uber-Eats-style sliding icon), `circular`, and `timer` (Apple's auto-updating countdown).
+
+**Bringing your own widget.** If you need a visually distinctive Live Activity beyond what the template covers, you can skip `@sitepong/expo-live-activity` and write the Widget Extension yourself in Swift, then call the lower-level token registration directly:
+
+```typescript
+import {
+  registerLiveActivityToken,
+  registerPushToStartToken,
+  endLiveActivity as endLiveActivityToken,
+} from 'sitepong/react-native';
 
-// When the activity ends, deactivate its token
-endLiveActivity('DeliveryActivityAttributes', activity.id);
+registerLiveActivityToken('MyActivityAttributes', activity.id, pushToken, { environment: 'production' });
+registerPushToStartToken('MyActivityAttributes', pushToStartToken, { environment: 'production' });
+endLiveActivityToken('MyActivityAttributes', activity.id);
 ```
 
 #### Token invalidation