@cartbot/plate-search 3.1.1 → 3.1.3

package/README.md

@@ -35,6 +35,112 @@ const MyComponent = () => {
 };
 ```
 
+### Customizing Action Button
+
+You can customize the "Show Products" button label:
+
+```jsx
+<PlateSearch
+  apiKey="YOUR_API_KEY"
+  productsUrl="/products"
+  actionButtonLabel="View Parts"
+/>
+```
+
+### Controlled Modal State
+
+Control the modal open/close state from your own UI using either **controlled props** or **imperative methods**:
+
+**Option 1: Controlled Props (Recommended)**
+
+```jsx
+import { useState } from "react";
+import PlateSearch from "@cartbot/plate-search";
+
+function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Search by Registration</button>
+
+      <PlateSearch
+        apiKey="YOUR_API_KEY"
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        hideDefaultButton
+        onModalClose={() => console.log("Modal closed")}
+      />
+    </>
+  );
+}
+```
+
+**Option 2: Imperative Methods (via ref)**
+
+```jsx
+import { useRef } from "react";
+import PlateSearch from "@cartbot/plate-search";
+
+function App() {
+  const plateSearchRef = useRef();
+
+  return (
+    <>
+      <button onClick={() => plateSearchRef.current?.open()}>
+        Search by Registration
+      </button>
+
+      <PlateSearch
+        ref={plateSearchRef}
+        apiKey="YOUR_API_KEY"
+        hideDefaultButton
+        onModalClose={() => console.log("Modal closed")}
+      />
+    </>
+  );
+}
+
+// Available methods:
+// plateSearchRef.current.open()   - Open the modal
+// plateSearchRef.current.close()  - Close the modal
+// plateSearchRef.current.toggle() - Toggle modal state
+```
+
+### Auto-Close on Vehicle Selection
+
+By default, the component shows a confirmation/summary page after vehicle selection. To auto-close the modal immediately after selection:
+
+```jsx
+<PlateSearch
+  apiKey="YOUR_API_KEY"
+  autoCloseOnSelect={true}
+  onModalClose={() => {
+    // Modal closed after vehicle selection
+    const vehicle = JSON.parse(
+      localStorage.getItem("partbot_selected_vehicle")
+    );
+    console.log("Selected:", vehicle);
+  }}
+/>
+```
+
+### Listening to Events
+
+The component dispatches DOM events you can listen to:
+
+```jsx
+// Listen to modal close events
+document.addEventListener("plate-search-modal-close", (e) => {
+  console.log("Modal closed at", e.detail.timestamp);
+});
+
+// Listen to vehicle selection events
+document.addEventListener("plate-search-change", (e) => {
+  console.log("Vehicle selected:", e.detail.vehicle_ids);
+});
+```
+
 ### Advanced Usage
 
 If you need direct access to the component without Shadow DOM isolation (for example, to apply your own styling), you can import the raw component:
@@ -56,6 +162,44 @@ import { PlateSearchRaw } from "@cartbot/plate-search";
 />
 ```
 
+### Web Component - Customization
+
+```html
+<!-- Custom action button label -->
+<plate-search
+  data-api-key="YOUR_API_KEY"
+  data-products-url="/products"
+  data-action-button-label="View Parts"
+/>
+
+<!-- Hide default button (trigger modal from your own button) -->
+<button onclick="document.querySelector('plate-search').open()">
+  Search by Rego
+</button>
+<plate-search data-api-key="YOUR_API_KEY" data-hide-default-button="true" />
+
+<!-- Auto-close after vehicle selection -->
+<plate-search data-api-key="YOUR_API_KEY" data-auto-close-on-select="true" />
+
+<script>
+  // Control modal programmatically
+  const plateSearch = document.querySelector("plate-search");
+
+  plateSearch.open(); // Open the modal
+  plateSearch.close(); // Close the modal
+  plateSearch.toggle(); // Toggle modal open/close
+
+  // Listen to events
+  document.addEventListener("plate-search-modal-close", (e) => {
+    console.log("Modal closed at", e.detail.timestamp);
+  });
+
+  document.addEventListener("plate-search-change", (e) => {
+    console.log("Vehicle selected:", e.detail.vehicle_ids);
+  });
+</script>
+```
+
 Copyright (c) Partbot Software Pty Ltd
 
 [use.partbot.io](https://use.partbot.io)