Bridge Components

repository·main·Indexed 19 days ago

https://github.com/joemasilotti/bridge-components

A collection of reusable, production-ready native components for iOS and Android and corresponding Stimulus controllers for Hotwire Native applications. It enables web views to drive native mobile features such as barcode scanning, biometrics, haptics, native alerts, and toolbar buttons.

Tokens
16.9K
Snippets
62
Records
79
Agent score
63%

What's inside @joemasilotti/bridge-components

  1. Understand the Bridge Components PRO License (Individual, Single-User)

    main

    The Bridge Components PRO License is a single-user agreement for individuals who have purchased the Pro package. It allows for the creation of both personal and commercial projects but imposes strict restrictions on the redistribution and modification of the software itself.

    Key Terms

    • Software: The Bridge Components Pro package, including components, code, templates, and documentation.
    • Licensee: The single individual who purchased the software.
    • Projects: Any applications, websites, or products developed using the software.

    Permitted Uses

    • Unlimited Projects: You may use the software in an unlimited number of personal or commercial projects without additional fees.
    • Deployment: You may deploy projects containing the software for clients or end-users.
    • Modification: You are permitted to modify the software as needed for integration into your projects.

    Prohibited Uses

    • No Redistribution: You cannot sell, rent, lease, sublicense, or share the software (modified or unmodified) as a standalone product.
    • No Open Source: You are prohibited from releasing the software under an open-source license or uploading it to public repositories.
    • No Competing Services: You cannot use the software to create a competing library, toolkit, or service.
    • No License Transfer: The license is non-transferable and applies only to the original purchaser.

    Ownership and Liability

    • Intellectual Property: All rights remain the exclusive property of Joseph Masilotti. Modifications do not grant ownership of the original software.
    • Disclaimer: The software is provided "AS IS" without warranties of any kind.
    • Limitation of Liability: Joseph Masilotti's total liability is limited to the amount actually paid by you for the software.
  2. Listen for Bridge Component JavaScript events

    main

    Several bridge components fire custom JavaScript events that you can listen to for cross-controller coordination. These events are prefixed with the bridge-- namespace.

    Common use cases include listening for:

    • Search: When a search query is executed (search component).
    • Notification Token: When a token is retrieved (notification-token component).
    • Location: When location data is retrieved (location component).
    • Barcode: When a barcode is scanned (barcode-scanner component).
  3. Understand permitted and prohibited uses of Bridge Components PRO

    main

    Permitted Uses

    • Unlimited Projects: You may use the Software in unlimited projects, including commercial client work, without additional fees.
    • Deployment: You may deploy projects containing the Software for internal use, for clients, or for public end-users.
    • Modification: You are permitted to modify the Software as needed for integration into your Projects.

    Prohibited Uses

    • Redistribution: You must not distribute, publish, share, sublicense, rent, lease, or sell the Software (modified or unmodified) as a stand-alone or competing product.
    • Open Source Release: You must not release the Software under an open source license or upload it to any public code repository accessible outside your organization.
    • Competing Services: You must not use or modify the Software to create a service, library, or toolkit that competes with Bridge Components.
    • Unauthorized Access: Access must not be shared with individuals (including subcontractors or freelancers) unless they are counted as Authorized Developers within your active seat count.
  4. Configure iOS for Notification Token retrieval

    main

    To enable notification token access on iOS, follow these steps:

    1. Enable Capabilities: In Xcode, enable the Push Notification capability.
    2. Update AppDelegate: In your AppDelegate.swift, implement the didRegisterForRemoteNotificationsWithDeviceToken method to post the token to the bridge.
    class AppDelegate: UIResponder, UIApplicationDelegate {
        func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
            Bridgework.post(.didReceiveNotificationToken, deviceToken)
        }
    }
  5. Manage Bridge Components PRO Team License seats

    main

    The Bridge Components PRO Team License allows access for up to 25 developers. To maintain compliance, the Licensee must manage access through the following process:

    1. Maintain a Developer List: Keep an up-to-date list of the GitHub usernames for all developers who require access to the private Bridge Components PRO repository.
    2. Update Access: To add, remove, or update developers, you must notify Joseph Masilotti with the requested changes.
    3. Revoke Access: When a developer leaves the team or no longer requires access, you must notify Joseph Masilotti so that access can be revoked.
    4. Reassign Seats: You may reassign seats to different developers as staffing changes occur, provided the total number of active Authorized Developers does not exceed the purchased seat count (25).
  6. Use the Haptic Component to trigger device vibration

    main

    The Haptic Component allows you to trigger the device's haptic engine (vibration) via Stimulus. This component requires a physical device to function. Android users must be on Android 11 or later.

    To use it, attach the bridge--haptic Stimulus controller to an element and call the vibrate action.

    <button data-controller="bridge--haptic" data-action="bridge--haptic#vibrate">
      Vibrate
    </button>
  7. Use the Theme Component to toggle dark/light mode

    main

    The bridge--theme Stimulus controller allows you to toggle the device's dark or light mode appearance, which styles native elements in the Hotwire Native app.

    To use it, attach the bridge--theme controller to an element and use the data-bridge--theme-theme-value attribute to specify the desired mode. The controller watches this attribute for changes and communicates the new value to the iOS or Android application.

    Supported values for data-bridge--theme-theme-value:

    • "dark": Sets the device to dark mode.
    • "light": Sets the device to light mode.
    <div data-controller="bridge--theme" data-bridge--theme-theme-value="dark"></div>
  8. Configure Android for Notification Token retrieval

    main

    Android requires Firebase Cloud Messaging (FCM) integration.

    1. Firebase Setup

    • Create a Firebase project and an Android app.
    • Download google-services.json and place it in the App/ directory of your project.

    2. Dependencies

    Add the following to your libs.versions.toml:

    [versions]
    firebaseBom = "33.10.0"
    
    [libraries]
    firebase-bom = { module = "com.google.firebase:firebase-bom", version.ref = "firebaseBom" }
    firebase-messaging = { module = "com.google.firebase:firebase-messaging" }

    Add the Google Services plugin to your project's build.gradle.kts:

    plugins {
        id("com.google.gms.google-services") version "4.4.2" apply false
    }

    And apply the plugin and dependencies in your app's build.gradle.kts:

    plugins {
        id("com.google.gms.google-services")
    }
    
    dependencies {
        implementation(platform(libs.firebase.bom))
        implementation(libs.firebase.messaging)
    }

    3. WebFragment Registration

    In your Application subclass, initialize Firebase and register the WebFragment to hook into the web view:

    package com.masilotti.demo
    
    import android.app.Application
    import com.google.firebase.FirebaseApp
    
    class DemoApplication : Application() {
        override fun onCreate() {
            super.onCreate()
    
            FirebaseApp.initializeApp(this)
            Hotwire.registerFragmentDestinations(WebFragment::class)
            Hotwire.defaultFragmentDestination = WebFragment::class
        }
    }

    4. Permissions

    Add the following permission to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
  9. Use the Barcode Scanner Stimulus controller

    main

    The Barcode Scanner component presents a native camera interface to scan barcodes and QR codes. It is implemented as a Stimulus controller named bridge--barcode-scanner.

    To use it, you can trigger the scan via a bridge--barcode-scanner#scan action and optionally capture the result in a Stimulus target.

    Note: This is a PRO component. You must purchase a PRO license to access the underlying Swift and Kotlin code.

    <div data-controller="bridge--barcode-scanner">
      <button data-action="bridge--barcode-scanner#scan">Scan</button>
      <p data-bridge--barcode-scanner-target="result"></p>
    </div>