@bagisto-native/core 1.0.0 → 1.0.2

package/readme.md

@@ -0,0 +1,368 @@
+# @bagisto-native/core
+
+`@bagisto-native/core` is the **foundation module for Bagisto Native**, enabling seamless communication between **web applications** and **native applications** using **Hotwire technology**.
+
+It is built to work seamlessly with [**Open Source Headless eCommerce**](https://bagisto.com/en/headless-ecommerce/
+), and any React.js/Next.js setup allowing developers to connect a headless storefront with native mobile apps.
+
+This module provides:
+
+- Core **Web Components** for native interaction
+- Hotwire **bridge bundle (`bundle.js`)**
+- Utility functions for **web ↔ native communication**
+
+
+> **Note:** To create **Bagisto Headless Commerce**, use the following command:
+>
+> ```bash
+> npx -y @bagisto-headless/create your-storefront
+> ```
+
+
+
+## 📦 Installation
+
+Install the module via npm:
+
+```bash
+npm install @bagisto-native/core
+```
+
+> **Note:** This module must be used alongside `@bagisto-native/react` if you're using React/Next.js.
+
+
+## 🛠️ Setup
+
+### 1. Add the Hotwire Bridge Bundle
+
+The Hotwire bridge bundle (`bundle.js`) is required for native communication.
+
+**Steps:**
+
+1. Navigate to `node_modules/@bagisto-native/core/public`
+2. Copy `bundle.js`
+3. Paste it into your project's `public` directory
+4. Include it in your HTML:
+
+```html
+<script src="/bundle.js"></script>
+```
+5. Or, include this as a static script in Next.js or similar frameworks.
+
+
+## 🌐 Web Components
+
+`@bagisto-native/core` provides the following **Web Components**:
+
+| Component            | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| `dynamic-button`      | Handles native buttons for cart (also cart count), share, barcode, and image search |
+| `hotwire-toast`       | Trigger native toast messages                                     |
+| `hotwire-search`      | Trigger native search events                                      |
+| `hotwire-location`    | Auto-fill checkout address using native location                  |
+| `hotwire-history-sync` | Send current page URL and tab-title to native apps                              |
+| `hotwire-theme-mode`   | Send current theme mode (light/dark)                              |
+
+> These components are primarily used in web projects but are wrapped by React components in `@bagisto-native/react`.
+
+## ⚡ Usage Examples
+
+### Hotwire Toast
+
+```tsx
+import '@bagisto-native/core';
+
+<hotwire-toast style="display: none;"></hotwire-toast>
+```
+
+Trigger a toast using the `triggerHotwireNativeToast(message: string)` function.
+
+```ts
+import { triggerHotwireNativeToast } from '@bagisto-native/core';
+
+triggerHotwireNativeToast('Hello World!');
+```
+
+
+### Hotwire History Sync
+
+```tsx
+import '@bagisto-native/core';
+
+<hotwire-history-sync style="display: none;"></hotwire-history-sync>
+```
+
+Send current url and tab-title using the `triggerHistorySyncEvent(url: URL, tabTitle: string)` function.
+
+```ts
+import { triggerHistorySyncEvent } from '@bagisto-native/core';
+
+triggerHistorySyncEvent(new URL('https://example.com'));
+```
+
+### Hotwire Theme Mode
+
+```tsx
+import '@bagisto-native/core';
+
+<hotwire-theme-mode style="display: none;"></hotwire-theme-mode>
+```
+
+Send theme mode using the `triggerThemeModeEvent(mode: 'light' | 'dark')` function.
+
+```ts
+import { triggerThemeModeEvent } from '@bagisto-native/core';
+
+triggerThemeModeEvent('light'); // 'light' or 'dark'
+```
+
+### Hotwire Search
+
+```tsx
+import '@bagisto-native/core';
+
+<hotwire-search style="display: none;"></hotwire-search>
+```
+
+Listen to search events:
+
+```ts
+// Listen for a custom event from Turbo.
+const handleTurboSearch = (e: Event) => {
+    const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
+    const query = customEvent.detail.query || customEvent.detail.code;
+    if (!query) return;
+    router.push(`/search?q=${encodeURIComponent(query)}`);
+};
+
+window.addEventListener("turbo:next-search", handleTurboSearch);
+```
+
+### Hotwire Location
+
+```tsx
+import '@bagisto-native/core';
+
+<hotwire-location style="display: none;"></hotwire-location>
+```
+
+Listen to location events:
+
+```ts
+// Listen for a custom event from Turbo.
+const handleLocationEvent = (e: Event) => {
+    const customEvent = e as CustomEvent<{ data: any }>;
+    const data = customEvent.detail.data;
+    console.log(data);
+
+    // Here, data include the current address of the user's device.
+};
+
+window.addEventListener("turbo:hotwire-app-fill-addresses", handleLocationEvent);
+```
+
+### Dynamic Button
+
+```tsx
+import '@bagisto-native/core';
+
+<dynamic-button data-page-type="home" style="display: none;"></dynamic-button>
+```
+
+> Use `pageType='home'` on homepage, `pageType='product'` on product pages.
+
+On both the home page and product page variants, the dynamic button component also shows the cart icon in the native app area. When we click on the cart icon, it emits the turbo:next-cart-modal event. You can open the cart modal or route to the cart page as per your requirement by listening to this event.
+
+If you want to open the cart modal and also include the native modal close button on the screen, you can use the following configuration of DynamicButton:
+
+```tsx
+<dynamic-button
+  data-action="click->bridge--dynamicbutton#sendModalOpenEvent"
+  style="display: none;"
+>
+</dynamic-button>
+
+<dynamic-button
+  data-action="click->bridge--dynamicbutton#sendModalDismissEvent"
+  style="display: none;"
+>
+</dynamic-button>
+```
+
+Now, you also have to send the event to the native side of the application when you open the modal, and also send the event when you close the modal via external sources.
+
+For sending the modal open event, use the following method:
+
+```tsx
+import { triggerDynamicButtonModalOpenEvent } from '@bagisto-native/core';
+
+triggerDynamicButtonModalOpenEvent();
+```
+
+For sending the modal dismiss event, use the following method:
+
+```tsx
+import { triggerDynamicButtonModalDismissEvent } from '@bagisto-native/core';
+
+triggerDynamicButtonModalDismissEvent();
+```
+
+However, without the native cart modal close icon, you can handle the cart modal or any other modal by only listening to the turbo:next-cart-modal event.
+
+For using the cart count variant, you need to add the following configuration of DynamicButton:
+
+```tsx
+<dynamic-button
+  data-action="click->bridge--dynamicbutton#sendCartCount"
+  style="display: none;"
+>
+</dynamic-button>
+```
+Now, whenever the cart count changes, you also need to notify the native app. For this, you can use the following method from `@bagisto-native/core`:
+
+```tsx
+import { triggerCartCountValue } from '@bagisto-native/core';
+
+triggerCartCountValue(5);
+```
+
+##### Dynamic Button Home Page Variant
+
+It basically shows three icons on the home page. The first one is for the Image Search feature, the second one is for the Barcode/QR code feature, and the third one is for the Cart and cart count feature.
+
+When you click on the Image Search icon or the Barcode/QR code icon, the corresponding native component opens and sends the processed data via the `turbo:next-search` event. You can listen to this event and handle the search process.
+
+```tsx
+const handleTurboSearch = (e: Event) => {
+    const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
+    const query = customEvent.detail.query || customEvent.detail.code;
+    if (!query) return;
+    window.location.href = `/search?q=${encodeURIComponent(query)}`;
+};
+
+window.addEventListener("turbo:next-search", handleTurboSearch);
+```
+
+##### Dynamic Button Product Page Variant
+
+In this variant, the dynamic button component shows the product share icon and cart icon in the application’s native area. The cart icon works the same as in the home page variant of the dynamic button component. When you click on the product share icon, it will open the native share modal, and you can handle the share process.
+
+
+##### Dynamic Button Emtpy Variant
+
+When we use the home or product variant of the dynamic button and then navigate to the auth pages, the previous-page icon remains visible. To hide this icon on the auth pages, use the empty variant of the dynamic button.
+
+```ts
+<dynamic-button data-page-type="empty" style="display: none;"></dynamic-button>
+```
+
+
+## ⚡ Utility Functions
+
+`@bagisto-native/core` provides several **helper functions**:
+
+### `triggerHotwireNativeToast(message: string)`
+
+Trigger a native toast message (hotwire-toast component must be present in the DOM):
+
+```ts
+import { triggerHotwireNativeToast } from "@bagisto-native/core";
+
+triggerHotwireNativeToast("Hello World!");
+```
+
+
+### `triggerHistorySyncEvent(url: URL, tabTitle: string)`
+
+Send the current URL and tab-title to the native app (hotwire-history-sync component must be present in the DOM):
+
+```ts
+import { triggerHistorySyncEvent } from "@bagisto-native/core";
+
+const url = new URL(window.location.href);
+const tabTitle = document?.title || "";
+triggerHistorySyncEvent(url, tabTitle);
+```
+
+
+### `triggerThemeModeEvent(mode: "light" | "dark")`
+
+Send the current theme mode (hotwire-theme-mode component must be present in the DOM):
+
+```ts
+import { triggerThemeModeEvent } from "@bagisto-native/core";
+
+triggerThemeModeEvent("light");
+```
+
+
+### `triggerCartCountValue(cartCount: number)`
+
+Send the cart count to the native app (the dynamic-button click->bridge--dynamicbutton#sendCartCount action variant must be present in the DOM):
+
+```ts
+import { triggerCartCountValue } from "@bagisto-native/core";
+
+triggerCartCountValue(3);
+```
+
+
+### `isTurboNativeUserAgent(userAgent?: string): boolean`
+
+Check if the current environment is a Turbo Native app:
+
+```ts
+import { isTurboNativeUserAgent } from "@bagisto-native/core";
+
+// Client-side
+if (isTurboNativeUserAgent()) {
+    console.log("Running in Turbo Native");
+}
+
+// Server-side
+isTurboNativeUserAgent(req.headers['user-agent']);
+
+```
+
+### `triggerDynamicButtonModalOpenEvent()`
+
+Trigger a modal open event (the dynamic-button click->bridge--dynamicbutton#sendModalOpenEvent action variant must be present in the DOM):
+
+```ts
+import { triggerDynamicButtonModalOpenEvent } from "@bagisto-native/core";
+
+triggerDynamicButtonModalOpenEvent();
+```
+
+### `triggerDynamicButtonModalDismissEvent()`
+
+Trigger a modal dismiss event (the dynamic-button click->bridge--dynamicbutton#sendModalDismissEvent action variant must be present in the DOM):
+
+```ts
+import { triggerDynamicButtonModalDismissEvent } from "@bagisto-native/core";
+
+triggerDynamicButtonModalDismissEvent();
+```
+
+## Build the Native iOS App
+
+After completing the setup of **Bagisto Native**, you can proceed to build the native iOS application using the official open-source repository.
+
+🔗 Bagisto Native iOS App:  
+https://github.com/SocialMobikul/BagistoNative_iOS
+
+
+## 📋 Requirements
+
+* Node.js >= 18
+* Works with any web project; for React/Next.js, use `@bagisto-native/react` for wrappers
+
+
+## 🆘 Support
+
+Open an issue or discussion in the repository if you need help.
+
+
+## 📄 License
+
+MIT License