From 52b8201d2f213dcb130a52e7903dde40a55d57a2 Mon Sep 17 00:00:00 2001 From: Samuel Newman Date: Mon, 20 Apr 2026 06:53:04 -0700 Subject: [PATCH] Add READMEs to modules (#10306) --- modules/BlueskyClip/README.md | 134 ++++++++++ modules/BlueskyNSE/README.md | 135 ++++++++++ modules/Share-with-Bluesky/README.md | 140 ++++++++++ modules/bottom-sheet/README.md | 248 ++++++++++++++++++ .../README.md | 162 ++++++++++++ modules/expo-bluesky-gif-view/README.md | 167 ++++++++++++ modules/expo-bluesky-swiss-army/README.md | 231 ++++++++++++++++ modules/expo-emoji-picker/README.md | 114 +++++++- .../expo-receive-android-intents/README.md | 123 ++++++++- modules/expo-scroll-forwarder/README.md | 116 ++++++++ 10 files changed, 1564 insertions(+), 6 deletions(-) create mode 100644 modules/BlueskyClip/README.md create mode 100644 modules/BlueskyNSE/README.md create mode 100644 modules/Share-with-Bluesky/README.md create mode 100644 modules/bottom-sheet/README.md create mode 100644 modules/expo-background-notification-handler/README.md create mode 100644 modules/expo-bluesky-gif-view/README.md create mode 100644 modules/expo-bluesky-swiss-army/README.md create mode 100644 modules/expo-scroll-forwarder/README.md diff --git a/modules/BlueskyClip/README.md b/modules/BlueskyClip/README.md new file mode 100644 index 0000000000..147ee50e6d --- /dev/null +++ b/modules/BlueskyClip/README.md @@ -0,0 +1,134 @@ +# BlueskyClip + +An iOS App Clip implementation for Bluesky starter packs. App Clips are lightweight app experiences that allow users to preview and join Bluesky through starter packs without installing the full app. + +## What It Does + +BlueskyClip provides a minimal, on-demand iOS app experience for viewing and joining Bluesky starter packs. When a user encounters a starter pack link (e.g., `bsky.app/start/...` or `go.bsky.app/...`), iOS can present the App Clip instead of requiring a full app install. The App Clip: + +1. Loads the starter pack web page in a WKWebView +2. Allows users to browse the starter pack content +3. Presents the App Store overlay when the user decides to join +4. Passes the starter pack URI to the main app via shared UserDefaults + +## Architecture + +### Native iOS Implementation + +The App Clip is a standalone iOS target with its own minimal Swift implementation: + +- **AppDelegate.swift**: Standard app delegate that sets up the view controller and handles URL routing (both direct URL opens and universal links) +- **ViewController.swift**: Main view controller that manages the WKWebView, detects starter pack URLs, and communicates with the web layer + +### Communication Flow + +``` +User taps starter pack link + ↓ +iOS presents BlueskyClip App Clip + ↓ +WKWebView loads bsky.app with ?clip=true parameter + ↓ +Web app detects clip mode and sends actions via postMessage + ↓ +ViewController receives messages and: + - Presents App Store overlay (action: "present") + - Stores starter pack URI in shared UserDefaults (action: "store") + ↓ +User downloads main app + ↓ +Main app reads starterPackUri from shared UserDefaults + ↓ +Main app displays starter pack onboarding flow +``` + +### Key Implementation Details + +**URL Detection** (`isStarterPackUrl`): +- Matches `bsky.app/start/*` and `bsky.app/starter-pack/*` paths (4 path components) +- Matches short links `go.bsky.app/*` (2 path components) + +**WebView Communication** (`WKScriptMessageHandler`): +- Listens for messages on the "onMessage" channel +- Handles two action types: + - `present`: Shows the App Store overlay using `SKOverlay` + - `store`: Writes JSON data to shared UserDefaults with the specified key + +**Data Sharing**: +- Uses UserDefaults suite `group.app.bsky` (App Group) +- Primary key: `starterPackUri` - stores the starter pack URL +- The main app reads this value on launch via `SharedPrefs.getString('starterPackUri')` (see `src/components/hooks/useStarterPackEntry.native.ts`) + +## Configuration + +### Build Configuration + +The App Clip target is automatically configured via Expo config plugins located in `/plugins/starterPackAppClipExtension/`: + +- **withStarterPackAppClip.js**: Main plugin that orchestrates all configuration +- **withXcodeTarget.js**: Creates the App Clip target in Xcode with proper build settings +- **withAppEntitlements.js**: Configures main app entitlements for App Clip association +- **withClipEntitlements.js**: Sets up App Clip entitlements (App Groups, parent app identifier, associated domains) +- **withClipInfoPlist.js**: Generates the Info.plist for the App Clip target +- **withFiles.js**: Copies Swift source files and assets from `modules/BlueskyClip/` to the iOS build directory + +### Entitlements + +**Main App** (`app.entitlements`): +- `com.apple.security.application-groups`: `group.app.bsky` +- `com.apple.developer.associated-appclip-app-identifiers`: Links to the App Clip bundle ID + +**App Clip** (`BlueskyClip.entitlements`): +- `com.apple.security.application-groups`: `group.app.bsky` (for data sharing) +- `com.apple.developer.parent-application-identifiers`: Links to the main app bundle ID +- `com.apple.developer.associated-domains`: Inherits from main app config (for universal links) + +### Build Settings + +- Deployment target: iOS 15.1+ +- Bundle ID: `[main-app-bundle-id].AppClip` +- Product type: `com.apple.product-type.application.on-demand-install-capable` +- Development team: `B3LX46C5HS` +- Device family: iPhone only (1) + +## Platform Support + +- **iOS**: Full support via native App Clip +- **Android**: Not applicable (no App Clip equivalent) +- **Web**: Not applicable (web uses standard starter pack landing pages) + +## Integration with Main App + +The main app detects App Clip-originated starter packs through `useStarterPackEntry` hook: + +**Native** (`src/components/hooks/useStarterPackEntry.native.ts`): +- Reads `starterPackUri` from `SharedPrefs` (App Group) +- Clears the value after reading to prevent re-use +- Sets active starter pack in app state + +**Web** (`src/components/hooks/useStarterPackEntry.ts`): +- Detects `?clip=true` URL parameter +- Extracts starter pack URI from URL +- Sets active starter pack with `isClip: true` flag + +## Files + +``` +modules/BlueskyClip/ +├── AppDelegate.swift # App lifecycle and URL handling +├── ViewController.swift # WebView management and message handling +└── Images.xcassets/ # App Clip icon assets + ├── AppIcon.appiconset/ + │ ├── App-Icon-1024x1024@1x.png + │ └── Contents.json + └── Contents.json +``` + +## Development Notes + +- The App Clip is built as part of the main Xcode project when running `yarn prebuild` +- Source files are copied during the prebuild process, not directly referenced +- Changes to Swift files require running `yarn prebuild` to take effect +- The App Clip shares the same version number as the main app +- App Clips have a 15MB size limit (enforced by Apple) +- Users can convert an App Clip session into a full app install without losing data (via shared App Group) diff --git a/modules/BlueskyNSE/README.md b/modules/BlueskyNSE/README.md new file mode 100644 index 0000000000..63136141cc --- /dev/null +++ b/modules/BlueskyNSE/README.md @@ -0,0 +1,135 @@ +# BlueskyNSE + +BlueskyNSE is an iOS Notification Service Extension that processes push notifications before they are displayed to the user. NSE stands for "Notification Service Extension", a native iOS app extension type. + +## What It Does + +This extension intercepts incoming push notifications and performs processing before displaying them: + +1. Manages badge counts for app icon +2. Applies custom notification sounds based on user preferences +3. Enables notification customization without requiring the main app to be running + +## How It Works + +When a push notification arrives on iOS, the system can invoke this extension to modify the notification content before displaying it. The extension runs in a separate process from the main app and has strict time limits (approximately 30 seconds) to complete its work. + +### Architecture + +The extension uses shared UserDefaults (via App Groups) to access preferences set by the main app: + +- **App Group**: `group.app.bsky` allows data sharing between the main app and the extension +- **Shared Preferences**: Stored in UserDefaults suite accessible by both processes +- **Thread Safety**: Uses a dedicated serial DispatchQueue (`NSEPrefsQueue`) to prevent race conditions when multiple notifications arrive simultaneously + +### Notification Processing Flow + +1. System receives push notification +2. `NotificationService.didReceive()` is called +3. Extension creates mutable copy of notification content +4. Based on notification type (determined by `reason` field): + - **Chat messages** (`reason == "chat-message"`): Applies custom DM sound if user preference `playSoundChat` is enabled + - **Other notifications**: Increments and applies badge count +5. Extension delivers modified notification to system via `contentHandler` + +### Badge Count Management + +Badge counts are managed centrally by the extension: +- Each non-chat notification increments the badge count +- Count is synchronized across notification instances using the serial queue +- Main app can reset the count via the `expo-background-notification-handler` module + +### Notification Sounds + +Two sound types are supported: +- **Default system sound**: Standard iOS notification sound +- **DM sound**: Custom `dm.aiff` sound file for chat messages + +DM sound only plays if the user has enabled the `playSoundChat` preference in the main app's chat settings. + +## Key Files + +| File | Purpose | +|------|---------| +| `NotificationService.swift` | Main service extension implementation | +| `BlueskyNSE.entitlements` | iOS entitlements configuration for App Group access | +| `Info.plist` | Extension metadata and configuration | + +### NotificationService.swift + +Contains two main classes: + +**NotificationService**: The main extension class that implements `UNNotificationServiceExtension` +- `didReceive(_:withContentHandler:)`: Processes incoming notifications +- `serviceExtensionTimeWillExpire()`: Handles timeout scenarios +- Mutation methods for modifying notification content + +**NSEUtil**: Singleton utility class for shared state management +- Provides shared `UserDefaults` instance for the App Group +- Manages serial queue for thread-safe preference access +- Helper methods for notification content manipulation + +## Configuration + +### App Group Setup + +The extension requires the `group.app.bsky` App Group to be configured in: +1. Main app target capabilities +2. Extension target capabilities (defined in `BlueskyNSE.entitlements`) + +### Shared Preferences + +The following preferences are shared between the main app and extension: + +| Preference Key | Type | Purpose | +|----------------|------|---------| +| `badgeCount` | Int | Current badge count for app icon | +| `playSoundChat` | Bool | Whether to play sound for chat notifications | + +These are managed by the `expo-background-notification-handler` module in the main app. + +### Sound Files + +The custom DM sound file (`dm.aiff`) must be included in the extension's bundle. The iOS project configuration handles copying this resource during the build. + +## Platform Support + +- **iOS**: Fully supported (primary platform for this extension) +- **Android**: Not applicable (Android uses different notification handling mechanisms) +- **Web**: Not applicable (web notifications are handled by browser APIs) + +## Integration with Main App + +The extension coordinates with the main app through: + +1. **expo-background-notification-handler** module: Provides JavaScript API for managing shared preferences +2. **App Group shared storage**: Enables data synchronization between processes +3. **Push notification payload**: Must include `reason` field to determine notification type + +### Setting User Preferences + +Users can control notification sounds via the Chat Settings screen (`src/screens/Messages/Settings.tsx`): + +```typescript +import {useBackgroundNotificationPreferences} from '../../../modules/expo-background-notification-handler/src/BackgroundNotificationHandlerProvider' + +const {preferences, setPref} = useBackgroundNotificationPreferences() +setPref('playSoundChat', true) // Enable DM sounds +``` + +## Limitations + +1. **Time constraints**: Extension must complete processing within ~30 seconds or the system will terminate it +2. **Process isolation**: Runs in separate process with limited memory and resources +3. **iOS only**: Notification Service Extensions are an iOS-specific feature +4. **Concurrent processing**: Multiple notifications may arrive simultaneously, requiring careful state management + +## Best Practices + +When modifying this extension: + +1. Keep processing fast and synchronous when possible +2. Use the shared serial queue for any UserDefaults mutations +3. Avoid network requests that could cause timeouts +4. Always call `contentHandler` with modified content, even on errors +5. Test with multiple concurrent notifications to verify thread safety diff --git a/modules/Share-with-Bluesky/README.md b/modules/Share-with-Bluesky/README.md new file mode 100644 index 0000000000..9ba7a1314b --- /dev/null +++ b/modules/Share-with-Bluesky/README.md @@ -0,0 +1,140 @@ +# Share-with-Bluesky + +iOS Share Extension for the Bluesky Social app that enables users to share content from other apps directly to Bluesky. + +## Overview + +This module implements an iOS Share Extension (Action Extension) that appears in the system share sheet when users tap the share button in other iOS apps. It allows sharing text, URLs, images, and videos to create a new Bluesky post. + +## Features + +- Share plain text +- Share URLs (web links) +- Share images (up to 4 images, supports PNG, JPG, JPEG, GIF, HEIC) +- Share videos (single video, supports MOV, MP4, M4V) +- Automatic image dimension extraction +- Automatic video dimension extraction +- App group file sharing for media access + +## Architecture + +### iOS Share Extension + +The extension is implemented as a native iOS Share Extension using Swift. When a user shares content: + +1. The `ShareViewController` receives the shared content from the extension context +2. Content is processed based on its type (text, URL, image, or video) +3. Media files are copied to a shared App Group container (`group.app.bsky`) for access by the main app +4. Image and video dimensions are extracted and encoded into the URI +5. The extension constructs a deep link URL with the content encoded in query parameters +6. The main Bluesky app is opened with the deep link +7. The extension completes and dismisses + +### Deep Link Format + +The extension communicates with the main app using deep links with the `bluesky://` scheme: + +``` +bluesky://intent/compose?text= +bluesky://intent/compose?imageUris=||,|| +bluesky://intent/compose?videoUri=|| +``` + +The scheme can be customized by setting the `MainAppScheme` key in `Info.plist` to support forks. + +### Main App Integration + +The main app handles these deep links in `src/lib/hooks/useIntentHandler.ts`: + +- Parses the deep link parameters +- Validates image/video URIs for security (filters out external URLs) +- Opens the composer with the pre-populated content +- Supports up to 4 images or 1 video per share + +## Key Files + +### Module Files + +- `ShareViewController.swift` - Main view controller that handles share requests and processes content +- `Info.plist` - Extension configuration (activation rules, supported content types) +- `Share-with-Bluesky.entitlements` - App group entitlements for shared file access + +### App Integration + +- `src/lib/hooks/useIntentHandler.ts` - Main app hook that handles incoming deep links +- `android/app/src/main/AndroidManifest.xml` - Android share intent configuration (lines 57-76) + +## Configuration + +### Supported Content Types + +Defined in `Info.plist` under `NSExtensionActivationRule`: + +- Text: Plain text strings +- Web URLs: Up to 1 URL +- Images: Up to 10 images +- Videos: Up to 1 video + +### App Group + +The extension uses the `group.app.bsky` App Group identifier to share files with the main app. This is configured in: + +- `Share-with-Bluesky.entitlements` +- Main app's entitlements file + +### Custom Scheme + +The `MainAppScheme` in `Info.plist` defaults to `bluesky` but can be changed for forks to use a custom URL scheme. + +## Platform Support + +- iOS: Native Share Extension (this module) +- Android: Native share intents handled via MainActivity intent filters in AndroidManifest.xml +- Web: Not applicable (browser share APIs use different mechanisms) + +## Implementation Details + +### Image Processing + +When images are shared: + +1. Images are loaded from the extension's temporary directory or as UIImage objects +2. Images are converted to JPEG format at maximum quality +3. Dimensions are extracted from the UIImage +4. Files are saved to the App Group container with unique names +5. URIs are formatted as `||` + +### Video Processing + +When videos are shared: + +1. Videos are copied from the source URL to the App Group container +2. AVURLAsset is used to extract video track dimensions +3. Track dimensions are adjusted for video rotation using preferredTransform +4. URI is formatted as `||` + +### Security + +- External URLs in image URIs are filtered out in the main app to prevent potential security issues +- Only file:// URLs from the App Group container are accepted +- URI format is validated with a regex pattern before processing + +## Development + +This module is built as part of the main Xcode project. The extension target is included in the iOS build configuration. + +To modify the extension: + +1. Open the Xcode project in `/ios` +2. Navigate to the Share-with-Bluesky target +3. Edit `ShareViewController.swift` for logic changes +4. Edit `Info.plist` for configuration changes +5. Rebuild the iOS app + +## Limitations + +- Images: Maximum of 4 images per share (limited in main app handler) +- Videos: Only 1 video per share +- Mixed media: Cannot share images and videos together +- File size: No explicit limits, but large files may cause issues +- Formats: Only supports common image/video formats listed in constants diff --git a/modules/bottom-sheet/README.md b/modules/bottom-sheet/README.md new file mode 100644 index 0000000000..49007d97b5 --- /dev/null +++ b/modules/bottom-sheet/README.md @@ -0,0 +1,248 @@ +# Bottom Sheet Expo Module + +A custom Expo module that provides native bottom sheet functionality for iOS and Android, using platform-specific native bottom sheet implementations (UISheetPresentationController on iOS, Material BottomSheetDialog on Android). + +## Overview + +This module wraps native bottom sheet components to provide a React Native interface with cross-platform consistency. It uses native presentation APIs rather than JavaScript-based animations for better performance and native behavior. + +Key features: +- Native bottom sheet presentation on iOS and Android +- Automatic content height detection (no JS bridge round-trip) +- Configurable snap points (hidden, partial, full) +- Drag-to-dismiss with prevention controls +- Portal-based rendering for proper z-index layering +- Edge-to-edge support on modern Android versions +- iOS 26+ zoom transition support + +## Platform Support + +- **iOS**: Uses `UISheetPresentationController` (iOS 15+) +- **Android**: Uses Material Design `BottomSheetDialog` with `BottomSheetBehavior` +- **Web**: Not supported (throws error) + +## Architecture + +### TypeScript Layer + +The module exposes a React component that handles rendering and state management: + +- **BottomSheet.tsx** (Native): Main component wrapping the native view +- **BottomSheet.web.tsx** (Web): Stub that throws an error +- **BottomSheetNativeComponent.tsx**: React wrapper with portal integration +- **BottomSheetPortal.tsx**: Portal system for rendering sheets above app content +- **Portal.tsx**: Generic portal implementation for managing component hierarchy + +The component uses a class-based approach to expose imperative methods (`present()`, `dismiss()`, `dismissAll()`). + +### Native Layer + +#### iOS Implementation + +- **BottomSheetModule.swift**: Expo module definition with event handlers and prop bindings +- **SheetView.swift**: Main view component that creates and manages `SheetViewController` + - Observes content height via KVO (Key-Value Observing) on bounds + - Manages sheet lifecycle and state transitions + - Implements `UISheetPresentationControllerDelegate` for drag events +- **SheetViewController.swift**: UIViewController subclass with sheet presentation + - Configures detents (snap points) based on content height + - Handles iOS 26+ safe area adjustments for floating sheet style + - Animates detent changes when content resizes +- **SheetManager.swift**: Singleton that tracks all active sheets with weak references +- **Util.swift**: Helper for calculating screen height minus safe area insets + +#### Android Implementation + +- **BottomSheetModule.kt**: Expo module definition mirroring iOS functionality +- **BottomSheetView.kt**: Main view component managing Material BottomSheetDialog + - Uses `OnLayoutChangeListener` to observe content height natively + - Configures `BottomSheetBehavior` for drag and snap behavior + - Handles edge-to-edge display across Android versions (API 29-35+) + - Preserves status/nav bar appearance from host activity +- **DialogRootViewGroup.kt**: Custom ViewGroup acting as RootView for the dialog + - Forwards touch events to React Native event system + - Updates shadow node size to match window dimensions + - Based on React Native's ReactModalHostView pattern +- **SheetManager.kt**: Singleton for tracking sheets (same pattern as iOS) + +### Content Height Detection + +Both platforms detect content height changes natively without JS bridge round-trips: + +- **iOS**: KVO observation on the content view's `bounds` property +- **Android**: `OnLayoutChangeListener` on child views (catches React Native's direct `layout()` calls) + +This eliminates layout jank when content changes (e.g., keyboard appearance, dynamic content loading). + +## Props + +```typescript +interface BottomSheetViewProps { + children: React.ReactNode + + // Appearance + cornerRadius?: number + backgroundColor?: ColorValue + containerBackgroundColor?: ColorValue + + // Behavior + preventDismiss?: boolean // Disable swipe-to-dismiss + preventExpansion?: boolean // Lock to initial height (no full-screen) + disableDrag?: boolean // Disable drag handle (Android only) + fullHeight?: boolean // Start at full screen height + + // Height constraints + minHeight?: number // Minimum height in dp + maxHeight?: number // Maximum height in dp + + // iOS 26+ transition + sourceViewTag?: number // View tag for zoom transition origin + + // Events + onAttemptDismiss?: (event: BottomSheetAttemptDismissEvent) => void + onSnapPointChange?: (event: BottomSheetSnapPointChangeEvent) => void + onStateChange?: (event: BottomSheetStateChangeEvent) => void +} +``` + +## States and Snap Points + +### States +- `closed`: Sheet is dismissed +- `closing`: Sheet is animating closed +- `open`: Sheet is fully visible +- `opening`: Sheet is animating open + +### Snap Points +- `Hidden` (0): Dismissed +- `Partial` (1): Half-expanded / content height +- `Full` (2): Expanded to screen height + +## Usage + +### Basic Example + +```tsx +import {BottomSheet, BottomSheetProvider, BottomSheetOutlet} from '@modules/bottom-sheet' + +// In your app root: +function App() { + return ( + + + + + ) +} + +// In a component: +function MyComponent() { + const sheetRef = useRef(null) + + const openSheet = () => { + sheetRef.current?.present() + } + + const closeSheet = () => { + sheetRef.current?.dismiss() + } + + return ( + <> +