feat: integrate local search functionality and enhance documentation

- Added `@easyops-cn/docusaurus-search-local` package for improved search capabilities in the documentation.
- Configured the search plugin in `docusaurus.config.ts` to index documentation.
- Updated sidebar to include new navigation items for better user experience.
- Enhanced the examples and payment flow documentation to clarify integration steps and usage patterns.
- Removed outdated "Common mistakes" guide and streamlined troubleshooting content for clarity.

Author: piotr-graczyk-dev

bun.lock

@@ -36,18 +36,7 @@ import { ApplePayButton } from '@gmisoftware/react-native-pay'
 
 ### Nitro and onPress
 
-If `onPress` does not fire (e.g. with Nitro host components), wrap the handler with `callback` from `react-native-nitro-modules`:
-
-```tsx
-import { callback } from 'react-native-nitro-modules'
-
-<ApplePayButton
-  buttonType="buy"
-  buttonStyle="black"
-  onPress={callback(handlePayment)}
-  style={{ width: '100%', height: 48 }}
-/>
-```
+If `onPress` does not fire, use Nitro's `callback(...)` wrapper. See [Troubleshooting: Nitro callback for onPress](/docs/troubleshooting#nitro-callback-for-onpress).
 
 ---
 
@@ -84,7 +73,7 @@ import { GooglePayButton } from '@gmisoftware/react-native-pay'
 
 ### Nitro and onPress
 
-Same as Apple: if needed, use `callback(handlePayment)` for `onPress`.
+Same as Apple: if needed, use `callback(handlePayment)` for `onPress`. See [Troubleshooting: Nitro callback for onPress](/docs/troubleshooting#nitro-callback-for-onpress).
 
 ---
 

docs/docs/api/components.md

@@ -147,6 +147,8 @@ Use `'TEST'` for development/sandbox; `'PRODUCTION'` for live charges.
 
 ## Pass types (iOS)
 
+These iOS-only types appear in payment-related metadata returned by Apple Pay APIs (for example pass details tied to the selected card) and are mostly useful in advanced/native-integrated flows.
+
 ```ts
 type PassActivationState =
   | 'activated'
@@ -178,6 +180,8 @@ interface PKSecureElementPass extends PKPass {
 
 Used on iOS when `billingContactRequired` / `shippingContactRequired` is requested in `PaymentRequest`.
 
+These fields are populated from the contact information the user approves in the Apple Pay sheet.
+
 ```ts
 type CNContactType = 'person' | 'organization'
 

docs/docs/api/types.md

@@ -12,6 +12,8 @@ import { usePaymentCheckout } from '@gmisoftware/react-native-pay'
 
 Pass a single config object. iOS reads the Apple Pay merchant ID from the native app configuration. Use `applePayMerchantIdentifier` only if you need to override it at runtime.
 
+Source of truth for these types: [`package/src/hooks/usePaymentCheckout.ts`](https://github.com/gmi-software/react-native-pay/blob/main/package/src/hooks/usePaymentCheckout.ts).
+
 ```ts
 interface UsePaymentCheckoutConfig {
   merchantName?: string
@@ -115,7 +117,7 @@ If you call `startPayment()` when `items.length === 0`, the hook sets `error` to
 
 Use `usePaymentCheckout` when you want cart state + defaults managed in React state.
 
-Use [HybridPaymentHandler](/docs/api/hybrid-payment-handler) when you need to build the full `PaymentRequest` yourself (for example custom shipping/contact requirements or prebuilt request payloads from your backend).
+Use [HybridPaymentHandler](/docs/api/hybrid-payment-handler) when you need to build the full `PaymentRequest` yourself (for example custom shipping/contact requirements or prebuilt request payloads from your backend). Utility helpers for this path are documented in [Utility functions](/docs/api/utils).
 
 ## Next
 

docs/docs/api/use-payment-checkout.md

@@ -2,6 +2,12 @@
 
 Helpers for building payment requests, items, and formatting. All are exported from `@gmisoftware/react-native-pay`.
 
+## When to use these helpers
+
+Use these functions when you are building a manual or low-level flow (usually with `HybridPaymentHandler`) and need to assemble `PaymentRequest` data yourself.
+
+If you use `usePaymentCheckout`, cart state and request building are handled for you internally, so these helpers are optional.
+
 ## createPaymentRequest(options)
 
 Builds a full `PaymentRequest` with one line item and sensible defaults.

docs/docs/api/utils.md

@@ -2,13 +2,75 @@
 
 The repository includes a full example app in the **`example/`** folder: an Expo app that demonstrates the checkout flow with `usePaymentCheckout`, cart management, and platform-specific buttons.
 
-## What’s in the example
+## Key checkout snippet
+
+From `example/app/(tabs)/index.tsx`:
+
+```tsx
+import { Platform } from 'react-native'
+import {
+  ApplePayButton,
+  GooglePayButton,
+  usePaymentCheckout,
+} from '@gmisoftware/react-native-pay'
+import { callback } from 'react-native-nitro-modules'
+
+const {
+  canMakePayments,
+  isCheckingStatus,
+  items,
+  total,
+  addItems,
+  clearItems,
+  startPayment,
+  isProcessing,
+  reset,
+} = usePaymentCheckout({
+  countryCode: 'US',
+  currencyCode: 'USD',
+})
+
+const handleAddCoffee = () => {
+  clearItems()
+  addItems([
+    { label: 'Coffee', amount: 4.99 },
+    { label: 'Tax', amount: 0.5 },
+  ])
+}
+
+const handlePayment = async () => {
+  const paymentResult = await startPayment()
+  if (paymentResult?.success) {
+    reset()
+    clearItems()
+  }
+}
+
+{Platform.OS === 'ios' ? (
+  <ApplePayButton
+    buttonType="buy"
+    buttonStyle="black"
+    onPress={callback(handlePayment)}
+    style={{ width: '100%', height: 56 }}
+  />
+) : (
+  <GooglePayButton
+    buttonType="buy"
+    theme="dark"
+    radius={8}
+    onPress={callback(handlePayment)}
+    style={{ width: '100%', height: 56 }}
+  />
+)}
+```
+
+## What’s in the full example
 
 - **Checkout flow** — Add items (e.g. “Coffee”, “Subscription”), see cart and total, then pay with Apple Pay or Google Pay.
 - **Status** — Check whether the device can make payments or only set up cards.
 - **Cart UI** — Add/clear items and display total.
 - **Result handling** — Success and error messages; reset and clear cart after success.
-- **Nitro `callback`** — Buttons use `callback(handlePayment)` from `react-native-nitro-modules` so `onPress` works correctly with Nitro host components.
+- **Nitro `callback`** — Buttons use `callback(handlePayment)` (see [Troubleshooting: Nitro callback for onPress](/docs/troubleshooting#nitro-callback-for-onpress)).
 
 ## Run the example
 
@@ -42,7 +104,7 @@ Use the checkout screen in the example app as a reference for:
 5. Renders **ApplePayButton** on iOS and **GooglePayButton** on Android with `callback(handlePayment)`.
 6. On successful payment, shows an alert and calls `reset()` and `clearItems()`.
 
-Copy these patterns into your app: config setup, cart handling, button usage, and `callback(...)` wrapping where needed.
+Copy these patterns into your app: config setup, cart handling, button usage, and native-safe `onPress` handlers.
 
 ## Plugin config in the example
 
@@ -52,4 +114,4 @@ The example’s **`app.json`** includes the React Native Pay plugin (e.g. with a
 
 - [Quick Start](/docs/quick-start) — Minimal integration in your app
 - [API: usePaymentCheckout](/docs/api/use-payment-checkout) — Hook options and return value
-- [Common mistakes](/docs/guides/common-mistakes) — What to avoid
+- [Troubleshooting](/docs/troubleshooting) — Common integration issues and fixes

docs/docs/examples.md

@@ -69,7 +69,7 @@ app.post('/process-payment', async (req, res) => {
 - Creating a payment method/source/intent from Apple Pay or Google Pay token payloads.
 - Idempotency (e.g. using `transactionId` to avoid duplicate charges).
 - Handling failures and refunds.
-- Provider-specific walkthroughs in [Integrations](/docs/integrations/overview) (for example: [Przelewy24 Apple Pay + Google Pay cookbook](/docs/integrations/przelewy24)).
+- Provider-specific walkthroughs in [Przelewy24 Apple Pay + Google Pay cookbook](/docs/integrations/przelewy24).
 
 ## Security
 

docs/docs/guides/common-mistakes.md

@@ -2,6 +2,8 @@
 
 This cookbook shows how to use `@gmisoftware/react-native-pay` for wallet payments and process them with Przelewy24 on your backend.
 
+The library is not a gateway SDK. It only presents the native payment sheet and returns the payment token that your backend maps to Przelewy24 APIs.
+
 It follows the same contract used across this library:
 
 - the app collects `PaymentResult` and `PaymentToken`