### Install Bridge Components (npm/yarn)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Install the npm package for the web layer. Use yarn or npm to add the bridge-components package to your project.

```bash
# npm
npm install @joemasilotti/bridge-components

# yarn
yarn add @joemasilotti/bridge-components
```

--------------------------------

### Install Bridge Components with NPM

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Add the bridge-components module to your project using NPM.

```bash
npm install @joemasilotti/bridge-components
```

--------------------------------

### Install Bridge Components with Yarn

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Add the bridge-components module to your project using Yarn.

```bash
yarn add @joemasilotti/bridge-components
```

--------------------------------

### Install Bridge Components with Rails Importmaps

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Pin the bridge-components module for use with Rails importmaps.

```bash
bin/importmap pin @joemasilotti/bridge-components
```

--------------------------------

### Android Color Resources for Theming

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

XML example for Android developers showing how to define color resources in `res/values/colors.xml`. Includes global fallback and per-component overrides for bridge components.

```xml
<!-- Android: res/values/colors.xml -->
<resources>
    <!-- Global fallback for all bridge components -->
    <color name="bridgework_color">#007AFF</color>
    <!-- Per-component overrides -->
    <color name="bridgework_button_color">#34C759</color>
    <color name="bridgework_menu_color">#FF9500</color>
    <color name="bridgework_form_color">#5856D6</color>
    <color name="bridgework_share_color">#FF2D55</color>
</resources>
```

--------------------------------

### Haptic Component Examples

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Triggers the device haptic engine with different feedback types. Supports 'success' (default), 'warning', and 'error'. Requires a physical device; Android requires Android 11+.

```html
<!-- Default success haptic -->
<button data-controller="bridge--haptic"
        data-action="bridge--haptic#vibrate">
  Complete action
</button>
```

```html
<!-- Warning haptic -->
<button data-controller="bridge--haptic"
        data-action="bridge--haptic#vibrate"
        data-bridge-feedback="warning">
  Low battery warning
</button>
```

```html
<!-- Error haptic -->
<button data-controller="bridge--haptic"
        data-action="bridge--haptic#vibrate"
        data-bridge-feedback="error">
  Submission failed
</button>
```

--------------------------------

### Per-Element Hex Color Override (HTML)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

HTML example demonstrating how to apply a per-element hex color override for a button using the `data-bridge-color` attribute. This applies to both platforms.

```html
<!-- Per-element hex override (both platforms) -->
<a href="/action"
   data-controller="bridge--button"
   data-bridge-color="#804F9F">
  Purple Button
</a>
```

--------------------------------

### Basic Menu Component Setup

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/menu.md

Define menu items using anchor tags with specific data attributes. The `data-bridge--menu-target="item"` attribute is crucial for identifying menu items. Titles and platform-specific images can be set using `data-bridge-title`, `data-bridge-ios-image`, and `data-bridge-android-image` attributes.

```html
<div data-controller="bridge--menu">
  <a href="/one"
    data-bridge--menu-target="item"
    data-bridge-title="One"
    data-bridge-ios-image="1.circle"
    data-bridge-android-image="counter_1">
      One
  </a>

  <a href="/two"
    data-bridge--menu-target="item"
    data-bridge-title="Two"
    data-bridge-ios-image="2.circle"
    data-bridge-android-image="counter_2">
      Two
  </a>
</div>
```

--------------------------------

### Integrate Theme Toggle Button

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Example of wiring a button to the theme controller for toggling dark mode. It uses a parent controller to manage the toggle action and a nested bridge--theme controller to apply the theme.

```html
<!-- Wire the toggle button to the theme controller -->
<div data-controller="theme">
  <div data-controller="bridge--theme"
       data-theme-target="bridge"
       data-bridge--theme-theme-value="light">
  </div>
  <button data-action="theme#toggle">Toggle dark mode</button>
</div>
```

--------------------------------

### Register Stimulus Controllers (JavaScript)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Load all bridge controllers into your Stimulus application with a single call after installing the npm package.

```javascript
// app/javascript/application.js
import { Application } from "@hotwired/stimulus"
import { controllers } from "@joemasilotti/bridge-components"

const application = Application.start()
application.load(controllers) // registers all bridge-- controllers at once
```

--------------------------------

### Register Stimulus Controllers

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Register the Stimulus controllers from the bridge-components module after starting your Stimulus application.

```javascript
import { Application } from "@hotwired/stimulus"
import { controllers } from "@joemasilotti/bridge-components"

const application = Application.start()
application.load(controllers)
```

--------------------------------

### Handling Scanned Barcodes with Stimulus JavaScript

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/barcode-scanner.md

Listen for the `bridge--barcode-scanner:scanned` event on the window to receive barcode scan results. The event detail contains the scanned barcode string. This example shows how to log the barcode to the console.

```html
<div data-controller="my-controller" 
    data-action="bridge--barcode-scanner:scanned@window->my-controller#scanned">
</div>
```

```javascript
// my_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  scanned(event) {
    const barcode = event.detail.barcode
    console.debug(`Scanned barcode: ${barcode}.`)
  }
}
```

--------------------------------

### Form Component HTML Equivalent

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Replaces a form's submit button with a native navigation bar button that automatically disables during submission. The button title comes from the <button>'s innerText or from data-bridge-title. This is the HTML equivalent of the Rails ERB example.

```html
<!-- HTML equivalent -->
<form
  data-controller="bridge--form"
  data-action="turbo:submit-start->bridge--form#submitStart turbo:submit-end->bridge--form#submitEnd">

  <input type="text" name="title" placeholder="Title">

  <button type="submit"
          data-bridge--form-target="submit"
          data-bridge-title="Save"
          data-bridge-color="#34C759">
    Save Post
  </button>
</form>

<style>
  [data-bridge-components~="form"][data-controller~="bridge--form"] [type="submit"] {
    display: none;
  }
</style>
```

--------------------------------

### Get Push Notification Token with Bridge Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

This component requests the device's push notification token (APNs/FCM). It displays the token in a target element and dispatches a `bridge--notification-token:retrieved` event. Use the `Enable notifications` button to trigger the request.

```html
<div data-controller="bridge--notification-token">
  <button data-action="bridge--notification-token#get">
    Enable notifications
  </button>
  <p data-bridge--notification-token-target="token"></p>
</div>

<!-- React to the token in another controller -->
<div data-controller="push-registration"
     data-action="bridge--notification-token:retrieved@window->push-registration#register">
</div>
```

--------------------------------

### Handle Search Queries in Stimulus Controller

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/search.md

This Stimulus controller demonstrates how to receive the search query from the event details and perform actions, such as filtering data. Ensure the controller is correctly imported and exported.

```javascript
// my_search_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  search(event) {
    const query = event.detail.query
    console.debug(`User searched for '${query}'.`)
    // Perform filtering...
  }
}
```

--------------------------------

### Register Native Components (iOS Swift)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Add the Swift package via Xcode and register the core components in your AppDelegate.swift file.

```swift
// AppDelegate.swift
import BridgeComponents
import HotwireNative
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Hotwire.registerBridgeComponents(Bridgework.coreComponents)
        return true
    }
}
```

--------------------------------

### Android Application Class for Firebase and Hotwire Integration

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Extend your `Application` class to initialize Firebase and register `WebFragment` for Hotwire integration, enabling notification handling.

```kotlin
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
    }
}
```

--------------------------------

### Add Android JitPack Repository

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Configure your Android project's settings.gradle.kts to include the JitPack repository for dependencies.

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") } // THIS LINE
    }
}
```

--------------------------------

### Form Component with Rails ERB

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Replaces a form's submit button with a native navigation bar button that automatically disables during submission. The button title comes from the <button>'s innerText or from data-bridge-title. This example uses Rails ERB.

```html
<%# Rails ERB %>
<%= form_with model: @post,
      data: {
        controller: "bridge--form",
        action: "turbo:submit-start->bridge--form#submitStart turbo:submit-end->bridge--form#submitEnd"
      } do |f| %>

  <%= f.text_field :title, placeholder: "Title" %>

  <%= f.submit "Save Post",
        data: {
          bridge__form_target: "submit",
          bridge_title: "Save",
          bridge_color: "#34C759"
        } %>
<% end %>

<style>
  [data-bridge-components~="form"][data-controller~="bridge--form"] [type="submit"] {
    display: none;
  }
</style>
```

--------------------------------

### Initialize Bridge Components (Android Kotlin)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Configure the JSON converter and register bridge components in your main Application class.

```kotlin
// YourApplication.kt
import com.masilotti.bridgecomponents.shared.Bridgework
import dev.hotwire.core.bridge.KotlinXJsonConverter
import dev.hotwire.core.config.Hotwire
import dev.hotwire.navigation.config.registerBridgeComponents

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate() 
        Hotwire.config.jsonConverter = KotlinXJsonConverter()
        Hotwire.registerBridgeComponents(*Bridgework.coreComponents)
    }
}
```

--------------------------------

### Listen for Search Queries with Stimulus

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/search.md

Attach this data attribute to an element to listen for the `bridge--search:queried` event dispatched from the window. This allows you to trigger a Stimulus controller action when the search query changes.

```html
<div data-controller="my-search"
     data-action="bridge--search:queried@window->my-search#search">
</div>
```

--------------------------------

### Android Project-Level Gradle Configuration

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Apply the Google Services plugin at the project level in your `build.gradle.kts` file to enable Firebase integration.

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

--------------------------------

### Register Core Components and Resolve Color (Swift)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Swift code for registering core bridge components and resolving a button tint using a hex color. It demonstrates the fallback mechanism for color resolution.

```swift
import BridgeComponents
import HotwireNative

// Register core components
Hotwire.registerBridgeComponents(Bridgework.coreComponents)

// Resolve a button tint: inline hex → BridgeworkButtonColor → BridgeworkColor → tint
let color = Bridgework.color("Button", hex: "#FF3B30")
```

--------------------------------

### Register Native Components in AppDelegate (iOS)

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Import the BridgeComponents framework and register all available components in your AppDelegate.swift file.

```swift
import BridgeComponents // THIS LINE
import HotwireNative
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Hotwire.registerBridgeComponents(Bridgework.coreComponents) // THIS LINE
        return true
    }
}
```

--------------------------------

### Register Native Components in Application

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Extend your Application class to register bridge components. Ensure necessary imports are included and configure the JSON converter.

```kotlin
package com.your.package.name

import android.app.Application
import com.masilotti.bridgecomponents.shared.Bridgework // THIS LINE
import dev.hotwire.core.bridge.KotlinXJsonConverter // THIS LINE
import dev.hotwire.core.config.Hotwire
import dev.hotwire.navigation.config.registerBridgeComponents // THIS LINE

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate() 

        Hotwire.config.jsonConverter = KotlinXJsonConverter() // THIS LINE
        Hotwire.registerBridgeComponents(*Bridgework.coreComponents) // THIS LINE
    }
}
```

--------------------------------

### Show Toast with HTML

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/toast.md

This HTML snippet demonstrates how to show a toast message using data attributes. It's a direct alternative to the ERB version.

```html
<a
  href="#"
  data-controller="bridge--toast"
  data-action="bridge--toast#show"
  data-bridge-message="This is a toast message."
>
  Show a toast
</a>
```

--------------------------------

### Basic Location Component HTML

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/location.md

This HTML sets up the basic structure for the location component, including a button to trigger location retrieval and a paragraph to display the result.

```html
<div data-controller="bridge--location">
  <button data-action="bridge--location#get">Get location</button>

  <p data-bridge--location-target="result"></p>
</div>
```

--------------------------------

### Add Native Share Button with Bridge Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Integrate a native share button that opens the system share sheet. By default, it shares the current URL. Provide a custom URL using `data-bridge-url` and customize the color with `data-bridge-color`.

```html
<!-- Share current page URL -->
<meta data-controller="bridge--share">

<!-- Share a specific URL with custom color -->
<meta data-controller="bridge--share"
      data-bridge-url="https://example.com/article/42"
      data-bridge-color="#007AFF">
```

--------------------------------

### HTML Structure for Document Scanner

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/document-scanner.md

This HTML snippet sets up the basic structure for the document scanner component, including a button to initiate scanning and a div to display the results. It requires JavaScript to be functional.

```html
<div data-controller="bridge--document-scanner">
  <button data-action="bridge--document-scanner#scan">Scan</button>

  <div data-bridge--document-scanner-target="result"></div>
</div>
```

--------------------------------

### iOS Color Assets for Theming

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Instructions for iOS developers on how to add color assets to `Assets.xcassets` for global and component-specific color overrides. Follows a `Bridgework<ComponentName>Color` pattern.

```swift
// iOS: add color assets to Assets.xcassets
// BridgeworkColor        → global fallback for all components
// BridgeworkButtonColor  → overrides only the Button component
// BridgeworkMenuColor    → overrides only the Menu component
// (same pattern for Form, Share, etc.)
```

--------------------------------

### Basic Alert Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Displays a native confirmation dialog before following a link. The title is taken from the element's inner text. Supports custom titles, descriptions, destructive styling, and custom button labels.

```html
<a href="/delete/42"
   data-controller="bridge--alert"
   data-action="bridge--alert#show">
  Delete record
</a>
```

```html
<a href="/delete/42"
   data-controller="bridge--alert"
   data-action="bridge--alert#show"
   data-bridge-title="Delete Record?"
   data-bridge-description="This action cannot be undone."
   data-bridge-destructive="true"
   data-bridge-confirm="Delete"
   data-bridge-dismiss="Keep">
  Delete record
</a>
```

--------------------------------

### Add Bridge Components Dependency (Android Gradle)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Include the necessary Hotwire core, navigation fragments, and bridge-components dependencies in your app/build.gradle.kts file.

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("dev.hotwire:core:1.2.4")
    implementation("dev.hotwire:navigation-fragments:1.2.4")
    implementation("com.github.joemasilotti:bridge-components:0.13.2")
}
```

--------------------------------

### Register Components and Observe Theme Change (Kotlin)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Kotlin code for registering bridge components and observing theme change events. It uses `Bridgework.observe` with a `LifecycleOwner` to update the default night mode.

```kotlin
import com.masilotti.bridgecomponents.shared.Bridgework
import com.masilotti.bridgecomponents.shared.Events
import dev.hotwire.core.config.Hotwire
import dev.hotwire.navigation.config.registerBridgeComponents

// Register components
Hotwire.registerBridgeComponents(*Bridgework.coreComponents)

// Observe the theme-change event (e.g., in a Fragment)
Bridgework.observe(this, Events.themeDidChange) { nightMode: Int ->
    AppCompatDelegate.setDefaultNightMode(nightMode)
}
```

--------------------------------

### Add Bridge Search Component Markup

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/search.md

Include this HTML to render the native search field. It initializes the bridge search controller.

```html
<div data-controller="bridge--search"></div>
```

--------------------------------

### Basic Form Submission with HTML

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/form.md

This HTML structure demonstrates the Form component's integration. The `data-action` attributes are crucial for managing the button's disabled state during form submission.

```html
<form 
  data-controller="bridge--form"
  data-action="turbo:submit-start->bridge--form#submitStart turbo:submit-end->bridge--form#submitEnd"
  >
  <!-- ... -->

  <button
    type="submit"
    data-bridge--form-target="submit"
    data-bridge-title="Submit"
  >
    Submit form
  </button>
</form>
```

--------------------------------

### Theme Toggle Controller Logic

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

A Stimulus controller to toggle the theme between 'dark' and 'light' and persist the selection in local storage. It requires a target element to update the theme value.

```javascript
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["bridge"]

  toggle() {
    const current = this.bridgeTarget.dataset.bridgeThemeThemeValue
    const next = current === "dark" ? "light" : "dark"
    this.bridgeTarget.dataset.bridgeThemeThemeValue = next
    localStorage.setItem("theme", next)
  }
}
```

--------------------------------

### Android Notification Token Dependencies (TOML)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Configure your `libs.versions.toml` file to include the necessary Firebase BOM and messaging dependencies for Android notification handling.

```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" }
```

--------------------------------

### Basic Barcode Scanner HTML Structure

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/barcode-scanner.md

Use this HTML structure to initialize the barcode scanner component. The `data-controller` attribute connects it to Stimulus, and `data-action` triggers the scan. The `data-bridge--barcode-scanner-target="result"` is optional for displaying scan results.

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

--------------------------------

### Show Toast with ERB

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/toast.md

Use this ERB snippet to display a toast message. It triggers the toast controller action with a predefined message.

```erb
<%= link_to "Show a toast", "#", data: {
  controller: "bridge--toast",
  action: "bridge--toast#show",
  bridge_message: "This is a toast message."
} %>
```

--------------------------------

### Set Alert Description

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/alert.md

An optional description can be set with `data-bridge-description`. This appears as smaller text below the title in the alert.

```erb
<%= link_to "Link title", "#", data: {
  controller: "bridge--alert",
  action: "bridge--alert#show",
  bridge_description: "Custom alert description."
} %>
```

```html
<a
    href="#"
    data-controller="bridge--alert"
    data-action="bridge--alert#show"
    data-bridge-description="Custom alert description"
>Link title</a>
```

--------------------------------

### HTML Table for Permissions Component

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/permissions.md

This HTML structure sets up a table to display permission statuses. It uses StimulusJS data attributes to connect to the Permissions controller, targeting specific table cells for camera, location, and notification statuses and codes.

```html
<table data-controller="bridge--permissions">
  <thead>
    <tr>
      <th>Permission</th>
      <th>Status</th>
      <th>Code</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <th>Camera</th>
      <td data-bridge--permissions-target="cameraStatus"></td>
      <td data-bridge--permissions-target="cameraCode"></td>
    </tr>

    <tr>
      <th>Location</th>
      <td data-bridge--permissions-target="locationStatus"></td>
      <td data-bridge--permissions-target="locationCode"></td>
    </tr>

    <tr>
      <th>Notifications</th>
      <td data-bridge--permissions-target="notificationsStatus"></td>
      <td data-bridge--permissions-target="notificationsCode"></td>
    </tr>
  </tbody>
</table>
```

--------------------------------

### HTML for Stimulus Event Handling

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/location.md

This HTML attaches a Stimulus controller to listen for custom events dispatched by the location component. It maps `bridge--location:retrieved` and `bridge--location:error` events to specific controller methods.

```html
<div data-controller="my-location"
     data-action="bridge--location:retrieved@window->my-location#retrieved bridge--location:error@window->my-location#error">
</div>
```

--------------------------------

### Post Notification Token (Swift)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Swift code snippet for posting a device token to the NotificationToken PRO component from AppDelegate. Requires `BridgeComponents` and `HotwireNative` imports.

```swift
// Post a typed notification from AppDelegate to the NotificationToken PRO component
func application (_ app: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Bridgework.post(.didReceiveNotificationToken, deviceToken)
}
```

--------------------------------

### Set Theme with HTML Attribute

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/theme.md

Use the `data-bridge--theme-theme-value` attribute to set the device's theme to dark or light mode. The Stimulus controller observes this attribute for changes.

```html
<div data-controller="bridge--theme" data-bridge--theme-theme-value="dark"></div>
```

--------------------------------

### Toggle App Theme with Bridge Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

This component allows toggling the app's dark/light mode at runtime by setting the `theme-value`. The native layer handles the actual appearance change. It can be configured with a server-rendered value.

```html
<!-- Set theme based on a server-rendered value -->
<div data-controller="bridge--theme"
     data-bridge--theme-theme-value="dark">
</div>
```

--------------------------------

### Android App-Level Gradle Dependencies

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Add the Firebase BOM and messaging implementation to your app's `build.gradle.kts` file to integrate Firebase Cloud Messaging.

```gradle
plugins {
    id("com.google.gms.google-services")
}

dependencies {
    implementation(platform(libs.firebase.bom))
    implementation(libs.firebase.messaging)
}
```

--------------------------------

### Trigger Review Prompt in HTML

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/review-prompt.md

Use this HTML snippet to create a link that triggers the review prompt. Ensure the 'bridge--review-prompt' controller and 'prompt' action are correctly configured.

```html
<a
  href="#"
  data-controller="bridge--review-prompt"
  data-action="bridge--review-prompt#prompt"
>
  Prompt for review
</a>
```

--------------------------------

### Button Component: Right-side Icon (HTML)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Configure a native right-side icon button using `data-bridge-ios-image` for SF Symbols and `data-bridge-android-image` for Material Symbols.

```html
<!-- Right-side icon button (SF Symbol on iOS, Material Symbol on Android) -->
<a href="/camera"
   data-controller="bridge--button"
   data-bridge-ios-image="camera"
   data-bridge-android-image="photo_camera">
  Camera
</a>
```

--------------------------------

### Menu Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Adds a native 'more' button to the navigation bar that opens a UIMenu or DropdownMenu. Each item can carry an icon and be marked destructive. Requires a specific style to hide the component's container.

```html
<div data-controller="bridge--menu" data-bridge-color="#007AFF">

  <a href="/edit"
     data-bridge--menu-target="item"
     data-bridge-title="Edit"
     data-bridge-ios-image="pencil"
     data-bridge-android-image="edit">
    Edit
  </a>

  <a href="/share"
     data-bridge--menu-target="item"
     data-bridge-title="Share"
     data-bridge-ios-image="square.and.arrow.up"
     data-bridge-android-image="share">
    Share
  </a>

  <a href="/delete"
     data-bridge--menu-target="item"
     data-bridge-title="Delete"
     data-bridge-destructive="true">
    Delete
  </a>

</div>

<style>
  [data-bridge-components~="menu"][data-controller~="bridge--menu"] {
    display: none;
  }
</style>
```

--------------------------------

### Permissions Component (`bridge--permissions`)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Reads the authorization status for camera, location, and push-notification permissions and updates bound target elements with human-readable status and numeric codes.

```APIDOC
## Permissions Component (`bridge--permissions`)

Reads the current authorization status for camera, location, and push-notification permissions and populates bound target elements with a human-readable status and a numeric code.

```html
<table data-controller="bridge--permissions">
  <thead>
    <tr><th>Permission</th><th>Status</th><th>Code</th></tr>
  </thead>
  <tbody>
    <tr>
      <th>Camera</th>
      <td data-bridge--permissions-target="cameraStatus"></td>
      <td data-bridge--permissions-target="cameraCode"></td>
    </tr>
    <tr>
      <th>Location</th>
      <td data-bridge--permissions-target="locationStatus"></td>
      <td data-bridge--permissions-target="locationCode"></td>
    </tr>
    <tr>
      <th>Notifications</th>
      <td data-bridge--permissions-target="notificationsStatus"></td>
      <td data-bridge--permissions-target="notificationsCode"></td>
    </tr>
  </tbody>
</table>

<!--
  Notification status codes returned:
   1  = authorized (granted)
   0  = denied
  -1  = not determined
  -2  = unknown
-->
```
```

--------------------------------

### JavaScript Event Listener for Notification Token

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

This JavaScript code demonstrates how to listen for the `bridge--notification-token:retrieved` event. The event detail contains the notification token, which is then logged to the console.

```html
<div data-controller="my-controller"
    data-action="bridge--notification-token:retrieved@window->my-controller#retrieved">
</div>
```

```javascript
// my_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  retrieved(event) {
    const token = event.detail.token
    console.debug(`Retrieved notification token: ${token}.`)
  }
}
```

--------------------------------

### NFC Component HTML Structure

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/nfc.md

This HTML structure sets up the basic UI for the NFC component, including buttons for reading and writing, and an input field for data.

```html
<div data-controller="bridge--nfc">
  <button data-action="bridge--nfc#read">Read</button>
  <p data-bridge--nfc-target="result"></p>

  <input data-bridge--nfc-target="value" value="Hello, world!" type="text">
  <button data-action="bridge--nfc#write">Write</button>
</div>
```

--------------------------------

### Enable Biometrics Lock

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/biometrics-lock.md

Enable the biometrics lock by calling the `#enable` action. This is typically done when a user signs in to secure their session.

```html
<div data-controller="bridge--biometrics-lock">
  <button data-action="bridge--biometrics-lock#enable">
    Enable lock
  </button>
</div>
```

--------------------------------

### Add Meta Tag to All Pages

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/biometrics-lock.md

Add this meta tag to every page of your application to ensure the app correctly locks when it enters the background. This is a prerequisite for the biometrics lock functionality.

```html
<meta data-controller="bridge--biometrics-lock">
```

--------------------------------

### Bridgework - Android Kotlin API

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

The `Bridgework` Kotlin singleton offers `coreComponents`, a `post` method for emitting bridge notifications, and an `observe` extension for subscribing with a `LifecycleOwner`.

```APIDOC
## `Bridgework` – Android Kotlin API

`Bridgework` is a Kotlin singleton exposing `coreComponents`, a typed `post` method to emit bridge notifications, and an `observe` extension to subscribe with a `LifecycleOwner`.

```kotlin
import com.masilotti.bridgecomponents.shared.Bridgework
import com.masilotti.bridgecomponents.shared.Events
import dev.hotwire.core.config.Hotwire
import dev.hotwire.navigation.config.registerBridgeComponents

// Register components
Hotwire.registerBridgeComponents(*Bridgework.coreComponents)

// Observe the theme-change event (e.g., in a Fragment)
Bridgework.observe(this, Events.themeDidChange) { nightMode: Int ->
    AppCompatDelegate.setDefaultNightMode(nightMode)
}

// Post a custom typed notification to the bus
val myEvent = Bridgework.BridgeNotification<String>("custom-event")
Bridgework.post(myEvent, "payload value")
```
```

--------------------------------

### Button Component: Left-side with Custom Color (HTML)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Create a left-side native button with a custom hex color using `data-bridge-side="left"` and `data-bridge-color`.

```html
<!-- Left-side button with custom color -->
<a href="/cancel"
   data-controller="bridge--button"
   data-bridge-side="left"
   data-bridge-color="#FF3B30">
  Cancel
</a>
```

--------------------------------

### Image Button (ERB)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

Create an image button using this ERB snippet. Specify iOS and Android image names using data attributes.

```erb
<%= link_to "Button", "#", data: {
  controller: "bridge--button",
  bridge_ios_image: "photo",
  bridge_android_image: "Image"
} %>
```

--------------------------------

### HTML Structure for Notification Token Component

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Use this HTML structure to integrate the notification token component into your web page. It includes a button to trigger the token retrieval and a paragraph to display the token.

```html
<div data-controller="bridge--notification-token">
  <button data-action="bridge--notification-token#get">
    Get notification token
  </button>

  <p data-bridge--notification-token-target="token"></p>
</div>
```

--------------------------------

### Trigger Haptic Feedback with Button

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/haptic.md

Use this HTML button to trigger a default haptic vibration when clicked. Ensure the 'bridge--haptic' controller is loaded.

```html
<button data-controller="bridge--haptic" data-action="bridge--haptic#vibrate">
  Vibrate
</button>
```

--------------------------------

### Share the Current URL

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/share.md

Use this snippet to add a share button that shares the current page's URL. Ensure the `bridge--share` controller is included in your meta tags.

```html
<meta data-controller="bridge--share">
```

--------------------------------

### Basic Form Submission with ERB

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/form.md

Use this ERB snippet to integrate the Form component. Ensure the `data-action` attributes are wired to disable the button during submission.

```erb
<%= form_with model: @model, data: {
  controller: "bridge--form",
  action: "turbo:submit-start->bridge--form#submitStart turbo:submit-end->bridge--form#submitEnd"
} do |form| %>
  <%# ... %>

  <%= form.submit "Submit form", data: {
    bridge__form_target: "submit",
    bridge_title: "Submit"
  } %>
<% end %>
```

--------------------------------

### Prompt In-App Review with Bridge Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Use this component to trigger the native App Store or Google Play in-app review dialog. The OS determines if the dialog is actually shown. It can be triggered by user action or automatically after a milestone.

```html
<!-- Prompt after a key user action -->
<a href="#"
   data-controller="bridge--review-prompt"
   data-action="bridge--review-prompt#prompt">
  Enjoying the app?
</a>

<!-- Trigger automatically after a milestone (using a custom Stimulus controller) -->
<div data-controller="milestone"
     data-action="milestone:reached->bridge--review-prompt#prompt">
  <div data-controller="bridge--review-prompt"></div>
</div>
```

--------------------------------

### Android Manifest Configuration for Barcode Scanner

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/barcode-scanner.md

To enable the Google code scanner API on Android, add this meta-data tag to your `<application>` in `AndroidManifest.xml`. This declares the necessary dependencies for the barcode UI.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application>
        <meta-data
            android:name="com.google.mlkit.vision.DEPENDENCIES"
            android:value="barcode_ui" />
    </application>
</manifest>
```

--------------------------------

### Trigger Review Prompt in ERB

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/review-prompt.md

Use this ERB snippet to create a link that triggers the review prompt. Ensure the 'bridge--review-prompt' controller and 'prompt' action are correctly configured.

```erb
<%= link_to "Prompt for review", "#", data: {
  controller: "bridge--review-prompt",
  action: "bridge--review-prompt#prompt"
} %>
```

--------------------------------

### Search Component Event Listener

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Listens for 'bridge--search:queried' events from the search component to filter a list. The 'event.detail.query' contains the current search query.

```javascript
// item_list_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  filter(event) {
    const query = event.detail.query?.toLowerCase() ?? ""
    this.element.querySelectorAll("li").forEach(item => {
      item.hidden = !item.textContent.toLowerCase().includes(query)
    })
  }
}
```

--------------------------------

### Add Bridge Components Dependency (Android)

Source: https://github.com/joemasilotti/bridge-components/blob/main/README.md

Include the bridge-components dependency in your app's build.gradle.kts file, replacing `<latest-version>` with the actual latest release version.

```kotlin
dependencies {
    // ...

    implementation("dev.hotwire:core:<hotwire-native-version>")
    implementation("dev.hotwire:navigation-fragments:<hotwire-native-version>")

    implementation("com.github.joemasilotti:bridge-components:<latest-verison>") // THIS LINE
}
```

--------------------------------

### Barcode Scanner Event Listener Controller

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Stimulus controller to handle the 'scanned' event from the barcode scanner. It fetches product information based on the scanned barcode and updates the DOM.

```javascript
// inventory_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  async lookup(event) {
    const { barcode } = event.detail
    const response = await fetch(`/products?barcode=${encodeURIComponent(barcode)}`)
    const html = await response.text()
    this.element.innerHTML = html
  }
}
```

--------------------------------

### Custom Color Button (HTML)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

This HTML snippet demonstrates how to set a custom button color using a HEX code via the `data-bridge-color` attribute.

```html
<a
    href="#"
    data-controller="bridge--button"
    data-bridge-color="#804F9F"
>Button</a>
```

--------------------------------

### Share a Custom URL

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/share.md

Configure the Share component to share a specific URL by setting the `data-bridge-url` attribute. This is useful when you want to share content other than the current page.

```html
<meta data-controller="bridge--share" data-bridge-url="https://bridgecomponents.dev">
```

--------------------------------

### Image Button (HTML)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

The HTML version of an image button. iOS uses SF Symbols and Android uses Material Symbols, specified via data attributes.

```html
<a 
    href="#"
    data-controller="bridge--button"
    data-bridge-ios-image="photo"
    data-bridge-android-image="Image"
>Button</a>
```

--------------------------------

### Text Button (HTML)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

This is the HTML equivalent for a text-based button. It is used in conjunction with the bridge--button controller.

```html
<a href="#" data-controller="bridge--button">Button</a>
```

--------------------------------

### Text Button (ERB)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

Use this ERB snippet to create a text-based button. The underlying HTML element will be clicked when the native button is tapped.

```erb
<%= link_to "Button", "#", data: {
  controller: "bridge--button"
} %>
```

--------------------------------

### Location Component Map Controller

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Stimulus controller for handling location events. The `center` method updates a map with the retrieved coordinates, and `showError` displays an alert if location retrieval fails.

```javascript
// map_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  center(event) {
    const { latitude, longitude } = event.detail
    // e.g. update a Mapbox / Leaflet map
    this.map.flyTo({ center: [longitude, latitude], zoom: 14 })
  }

  showError() {
    alert("Could not retrieve your location. Please check permissions.")
  }
}
```

--------------------------------

### Register Push Notification Token

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

A Stimulus controller to handle the `bridge--notification-token:retrieved` event. It receives the token and sends it to the server via a POST request. Ensure the server endpoint is correctly configured.

```javascript
// push_registration_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  async register(event) {
    const { token } = event.detail
    await fetch("/push_registrations", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token })
    })
  }
}
```

--------------------------------

### Android Manifest Permissions for Notifications

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/notification-token.md

Declare the `POST_NOTIFICATIONS` permission in your `AndroidManifest.xml` to allow your application to send and receive notifications.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application>
        <!-- ...
    </application>
</manifest>
```

--------------------------------

### Left Button (HTML)

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/button.md

The HTML representation for a left-aligned button. Use the `data-bridge-side="left"` attribute to position it.

```html
<a
    href="#"
    data-controller="bridge--button"
    data-bridge-side="left"
>Button</a>
```

--------------------------------

### Search Component Activation

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Embeds a native UISearchController or search view in the navigation bar. Fires a 'bridge--search:queried' JavaScript event when the query text changes.

```html
<!-- Activate the native search bar -->
<div data-controller="bridge--search"></div>
```

--------------------------------

### Android Permissions for Location

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/location.md

These XML permissions are required in your `AndroidManifest.xml` to access the user's location on Android devices. `ACCESS_FINE_LOCATION` provides precise location, while `ACCESS_COARSE_LOCATION` provides approximate location.

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
```

--------------------------------

### Android Application Subclass for NFC

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/nfc.md

Register WebFragment in your Application subclass to enable NFC functionality on Android. This is required for using NfcAdapter.

```kotlin
package com.masilotti.demo

import android.app.Application

class DemoApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Hotwire.registerFragmentDestinations(WebFragment::class)
        Hotwire.defaultFragmentDestination = WebFragment::class
    }
}
```

--------------------------------

### Customizing Submit Button Color with HTML

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/form.md

Set a custom submit button color for individual buttons using the `data-bridge-color` attribute with a HEX code in HTML.

```html
<form data-controller="bridge--form" data-bridge-color="#804F9F">
  <!-- ... -->
</form>
```

--------------------------------

### Biometrics Lock Component Enable Button

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

HTML structure for enabling the biometric lock feature. Clicking the button triggers the `enable` action of the biometrics lock controller.

```html
<!-- Enable lock (e.g., on sign-in page) -->
<div data-controller="bridge--biometrics-lock">
  <button data-action="bridge--biometrics-lock#enable">
    Enable biometric lock
  </button>
</div>
```

--------------------------------

### Show Toast Message with Bridge Component

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Use this component to display short-lived native messages. It works on both Android and iOS. Configure the message using the `data-bridge-message` attribute.

```html
<!-- Rails ERB -->
<%= link_to "Save draft", "#",
      data: {
        controller: "bridge--toast",
        action: "bridge--toast#show",
        bridge_message: "Draft saved successfully."
      } %>

<!-- HTML equivalent -->
<a href="#"
   data-controller="bridge--toast"
   data-action="bridge--toast#show"
   data-bridge-message="Draft saved successfully.">
  Save draft
</a>
```

--------------------------------

### Permissions Component HTML Structure

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

HTML table structure for the Permissions component. It binds to data attributes to display authorization status and codes for camera, location, and notifications.

```html
<table data-controller="bridge--permissions">
  <thead>
    <tr><th>Permission</th><th>Status</th><th>Code</th></tr>
  </thead>
  <tbody>
    <tr>
      <th>Camera</th>
      <td data-bridge--permissions-target="cameraStatus"></td>
      <td data-bridge--permissions-target="cameraCode"></td>
    </tr>
    <tr>
      <th>Location</th>
      <td data-bridge--permissions-target="locationStatus"></td>
      <td data-bridge--permissions-target="locationCode"></td>
    </tr>
    <tr>
      <th>Notifications</th>
      <td data-bridge--permissions-target="notificationsStatus"></td>
      <td data-bridge--permissions-target="notificationsCode"></td>
    </tr>
  </tbody>
</table>

<!--
  Notification status codes returned:
   1  = authorized (granted)
   0  = denied
  -1  = not determined
  -2  = unknown
-->
```

--------------------------------

### Post Custom Typed Notification (Kotlin)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Kotlin code for posting a custom typed notification to the bridge bus. It defines a `BridgeNotification` with a specific payload type and sends it with a value.

```kotlin
// Post a custom typed notification to the bus
val myEvent = Bridgework.BridgeNotification<String>("custom-event")
Bridgework.post(myEvent, "payload value")
```

--------------------------------

### Bridgework - iOS Swift API

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

The `Bridgework` Swift namespace provides access to core components, a helper for resolving colors, and a method to post typed notifications.

```APIDOC
## `Bridgework` – iOS Swift API

`Bridgework` is the central Swift namespace. `coreComponents` returns the array passed to `Hotwire.registerBridgeComponents`. The `color(_:hex:)` helper resolves a component's tint with a four-level fallback: inline hex → named asset `Bridgework<Name>Color` → named asset `BridgeworkColor` → system tint.

```swift
import BridgeComponents
import HotwireNative

// Register core components
Hotwire.registerBridgeComponents(Bridgework.coreComponents)

// Resolve a button tint: inline hex → BridgeworkButtonColor → BridgeworkColor → tint
let color = Bridgework.color("Button", hex: "#FF3B30")

// Post a typed notification from AppDelegate to the NotificationToken PRO component
func application(_ app: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Bridgework.post(.didReceiveNotificationToken, deviceToken)
}
```
```

--------------------------------

### Button Component: Hide Web Element (CSS)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Apply CSS to hide the underlying HTML element when the native button is active, ensuring a seamless native UI experience.

```css
<!-- Hide the web element when the native button is active -->
<style>
  [data-bridge-components~="button"][data-controller~="bridge--button"] {
    display: none;
  }
</style>
```

--------------------------------

### Android Manifest Permissions for NFC

Source: https://github.com/joemasilotti/bridge-components/blob/main/docs/components/nfc.md

Add NFC permissions and features to your AndroidManifest.xml file to allow the application to interact with NFC hardware.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.NFC" />
    <uses-feature android:name="android.hardware.nfc" android:required="false" />

    <application>
        <!-- ... -->
    </application>
</manifest>
```

--------------------------------

### Button Component: Right-side Text (HTML)

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Use the `bridge--button` Stimulus controller to add a native right-side text button. Tapping it triggers a click event on the HTML element.

```html
<!-- Right-side text button (default) -->
<a href="/new" data-controller="bridge--button">New Item</a>
```

--------------------------------

### Location Component HTML

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

HTML structure for the location component. It provides a button to request the user's location and a paragraph to display results or errors. Another div shows how to integrate with a map controller.

```html
<div data-controller="bridge--location">
  <button data-action="bridge--location#get">Use my location</button>
  <p data-bridge--location-target="result"></p>
</div>

<div data-controller="map"
     data-action="
       bridge--location:retrieved@window->map#center
       bridge--location:error@window->map#showError">
</div>
```

--------------------------------

### Biometrics Lock Component Meta Tag

Source: https://context7.com/joemasilotti/bridge-components/llms.txt

Meta tag to enable the biometrics lock component. This should be added to every page to ensure consistent background locking behavior.

```html
<!-- Add to EVERY page to ensure consistent lock behavior -->
<meta data-controller="bridge--biometrics-lock">
```