@undefine-ui/design-system 3.6.1 → 3.7.0

package/README.md

@@ -62,6 +62,7 @@ const ThemeSwitcher = () => {
 ```tsx
 import {
   CopyButton,
+  CustomFormLabel,
   Field,
   Form,
   Icon,
@@ -600,6 +601,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.
@@ -661,6 +814,65 @@ import { OTPInput, Field } from '@undefine-ui/design-system';
 
 The `Field.OTP` component automatically integrates with React Hook Form, providing validation and error handling out of the box.
 
+### FormLabel
+
+A custom form label component with support for optional text, tooltips, and custom icons. Perfect for creating consistent form field labels across your application.
+
+**Usage:**
+
+```tsx
+import { CustomFormLabel } from '@undefine-ui/design-system';
+
+// Basic label
+<CustomFormLabel label="Email Address" />
+
+// Optional field label
+<CustomFormLabel label="Phone Number" optional />
+
+// With tooltip
+<CustomFormLabel
+  label="API Key"
+  tooltip="Your API key can be found in the developer settings."
+/>
+
+// Optional with tooltip
+<CustomFormLabel
+  label="Company Name"
+  optional
+  tooltip="Enter your company name if applicable."
+/>
+
+// With custom icon
+<CustomFormLabel
+  label="Password"
+  tooltip="Password must be at least 8 characters long."
+  icon={<Icon icon="HelpCircle" sx={{ width: 16, height: 16, color: 'primary.main' }} />}
+/>
+
+// Complete form example
+<Box>
+  <CustomFormLabel label="Full Name" />
+  <TextField fullWidth placeholder="Enter your full name" size="small" />
+</Box>
+```
+
+**Props:**
+
+- `label` - Label text to display (required)
+- `optional` - Show "(Optional)" text after label (default: `false`)
+- `tooltip` - Tooltip text shown on hover of info icon
+- `icon` - Custom icon for tooltip (default: `InfoCircle` icon)
+- `sx` - MUI sx prop for styling
+- All MUI `FormLabelProps` are supported (except `children`)
+
+**Features:**
+
+- **Optional indicator:** Shows "(Optional)" text for non-required fields
+- **Tooltip support:** Info icon with tooltip for additional context
+- **Custom icons:** Replace default info icon with custom icons
+- **Flexible styling:** Supports all MUI FormLabel props and sx styling
+- **Theme integration:** Uses theme variables for consistent styling
+
 ### Dialog
 
 Custom dialog components with close button and feedback variations. Includes a base `CustomDialog` with a close button positioned on the right, and a `FeedbackDialog` for success, error, and confirmation states.