@undefine-ui/design-system 3.6.0 → 3.6.2

package/README.md

@@ -90,6 +90,7 @@ The package includes a comprehensive icon library with 45+ SVG icons organized b
 - **Date & Time:** Calendar, Clock
 - **Data:** SortUp, SortDown, StatUp, StatDown
 - **Toast:** InfoToast, SuccessToast, WarningToast, ErrorToast
+- **Location:** MapPinXMark
 - **System:** KeyCommand
 
 **Usage:**
@@ -599,6 +600,158 @@ const sortOptions: SortOption[] = [
 - `open` - Whether the button is in open/active state
 - All standard MUI ButtonBase props
 
+### Google Places Autocomplete
+
+A Google Places address autocomplete component with structured address parsing, coordinates extraction, and React Hook Form integration. Perfect for address lookup, location selection, and form-based address capture.
+
+**Setup:**
+
+```tsx
+import { GooglePlacesProvider } from '@undefine-ui/design-system';
+
+// Wrap your app with GooglePlacesProvider
+function App() {
+  return (
+    <GooglePlacesProvider apiKey={process.env.GOOGLE_MAPS_API_KEY}>
+      {/* Your app content */}
+    </GooglePlacesProvider>
+  );
+}
+```
+
+**Usage:**
+
+```tsx
+import {
+  GooglePlacesAutocomplete,
+  Field,
+  type PlaceType,
+  type PlaceDetails
+} from '@undefine-ui/design-system';
+
+// Basic usage
+const [value, setValue] = useState<PlaceType | null>(null);
+
+<GooglePlacesAutocomplete
+  label="Search for a location"
+  placeholder="Start typing..."
+  onChange={setValue}
+/>
+
+// With place details (includes parsed address and coordinates)
+<GooglePlacesAutocomplete
+  label="Search address"
+  fetchPlaceDetails
+  onPlaceDetailsChange={(details) => {
+    console.log(details?.parsedAddress?.city);    // "Lagos"
+    console.log(details?.parsedAddress?.country); // "Nigeria"
+    console.log(details?.coordinates?.latitude);  // 6.5245
+  }}
+/>
+
+// With country restriction
+<GooglePlacesAutocomplete
+  label="US addresses only"
+  componentRestrictions={{ country: 'us' }}
+  onChange={setValue}
+/>
+```
+
+**React Hook Form Integration:**
+
+```tsx
+import { Form, Field } from '@undefine-ui/design-system';
+import { useForm } from 'react-hook-form';
+
+const MyForm = () => {
+  const methods = useForm({
+    defaultValues: {
+      location: null,
+      address: ''
+    }
+  });
+
+  return (
+    <Form methods={methods} onSubmit={(data) => console.log(data)}>
+      {/* Store full PlaceType object */}
+      <Field.GooglePlacesAutocomplete name="location" label="Location" valueType="full" />
+
+      {/* Store only description string */}
+      <Field.GooglePlacesAutocomplete name="address" label="Address" valueType="description" />
+
+      {/* Store PlaceDetails with parsed address */}
+      <Field.GooglePlacesAutocomplete
+        name="fullAddress"
+        label="Full Address"
+        valueType="details"
+        fetchPlaceDetails
+      />
+    </Form>
+  );
+};
+```
+
+**GooglePlacesAutocomplete Props:**
+
+- `label` - Input label
+- `placeholder` - Input placeholder
+- `value` - Selected place (controlled)
+- `onChange` - Callback when selection changes `(place: PlaceType | null) => void`
+- `fetchPlaceDetails` - Fetch full place details on selection (default: `false`)
+- `onPlaceDetailsChange` - Callback with place details `(details: PlaceDetails | null) => void`
+- `componentRestrictions` - Country restrictions `{ country: string | string[] }`
+- `types` - Place types to search for (e.g., `['address']`, `['establishment']`)
+- `debounceMs` - Debounce delay in milliseconds (default: `300`)
+- `error` / `errorMessage` / `helperText` - Error and helper text display
+- All standard MUI TextField props
+
+**Field.GooglePlacesAutocomplete Props:**
+
+- `name` - Form field name (required)
+- `valueType` - What to store in form: `'full'` (PlaceType), `'description'` (string), or `'details'` (PlaceDetails)
+- `onValueChange` - Callback when value changes (raw PlaceType)
+- `onPlaceDetailsChange` - Callback when place details are fetched
+- All `GooglePlacesAutocomplete` props except `value`, `onChange`, `error`, `errorMessage`
+
+**PlaceDetails Structure:**
+
+```typescript
+interface PlaceDetails {
+  placeId: string;
+  description: string;
+  formattedAddress?: string;
+  lat?: number;
+  lng?: number;
+
+  // Structured parsed address
+  parsedAddress?: {
+    streetNumber?: string;
+    street?: string;
+    address?: string; // Full formatted address
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+    stateCode?: string;
+    country?: string;
+    countryCode?: string;
+    postalCode?: string;
+    county?: string;
+  };
+
+  // Coordinates
+  coordinates?: {
+    latitude: number;
+    longitude: number;
+  };
+}
+```
+
+**Exported Utilities:**
+
+- `GooglePlacesProvider` - Context provider for API key
+- `useGooglePlacesAutocomplete` - Hook for custom implementations
+- `parseAddressComponents` - Parse raw Google address components into structured format
+
 ### OTP Input
 
 A one-time password input component with keyboard navigation, paste support, and validation. Perfect for email/SMS verification, PIN codes, and security codes.