@jmruthers/pace-core 0.5.186 → 0.5.187

package/src/components/AddressField/AddressField.tsx

@@ -0,0 +1,323 @@
+/**
+ * @file AddressField Component
+ * @package @jmruthers/pace-core
+ * @module Components/AddressField
+ * @since 0.1.0
+ *
+ * Address input field with Google Places API autocomplete.
+ * Provides address suggestions, keyboard navigation, and accessibility.
+ *
+ * Features:
+ * - Google Places API autocomplete integration
+ * - Debounced input with caching
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - Accessible ARIA attributes
+ * - Loading and error states
+ * - place_id storage for later retrieval
+ */
+
+import * as React from 'react';
+import { Input } from '../Input/Input';
+import { LoadingSpinner } from '../LoadingSpinner';
+import { cn } from '../../utils/core/cn';
+import { useAddressAutocomplete } from '../../hooks/useAddressAutocomplete';
+import type { AddressFieldProps, AddressFieldRef } from './types';
+import type { ParsedAddress } from '../../utils/google-places';
+
+/**
+ * AddressField component
+ * 
+ * A production-ready address input field with Google Places API autocomplete.
+ * Returns structured address data including place_id for later retrieval.
+ * 
+ * @param props - AddressField configuration
+ * @param ref - Forwarded ref for imperative access
+ * @returns JSX.Element - The rendered address field
+ * 
+ * @example
+ * ```tsx
+ * <AddressField
+ *   apiKey={apiKey}
+ *   onChange={(address) => {
+ *     // address includes place_id, full_address, lat, lng, etc.
+ *     console.log(address.place_id);
+ *   }}
+ *   placeholder="Enter your address"
+ * />
+ * ```
+ */
+const AddressField = React.forwardRef<HTMLInputElement, AddressFieldProps>(
+  (
+    {
+      apiKey,
+      value: controlledValue,
+      defaultValue = '',
+      onChange,
+      onInputChange,
+      placeholder = 'Enter address',
+      error,
+      disabled,
+      className,
+      size = 'md',
+      variant = 'default',
+      autocompleteOptions,
+      debounceDelay,
+      cacheEnabled = true,
+      cacheTTL,
+      ...props
+    },
+    ref
+  ) => {
+    const [internalValue, setInternalValue] = React.useState(defaultValue);
+    const [isOpen, setIsOpen] = React.useState(false);
+    const [selectedIndex, setSelectedIndex] = React.useState(-1);
+    const [inputFocused, setInputFocused] = React.useState(false);
+
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const suggestionsRef = React.useRef<HTMLUListElement>(null);
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    // Use controlled or uncontrolled value
+    const value = controlledValue !== undefined ? controlledValue : internalValue;
+
+    // Use autocomplete hook
+    const { suggestions, isLoading, error: autocompleteError, selectAddress, clearSuggestions } =
+      useAddressAutocomplete(apiKey, value, {
+        autocompleteOptions,
+        debounceDelay,
+        cacheEnabled,
+        cacheTTL,
+      });
+
+    // Update suggestions visibility
+    React.useEffect(() => {
+      if (suggestions.length > 0 && inputFocused && value.trim()) {
+        setIsOpen(true);
+      } else if (suggestions.length === 0 || !value.trim()) {
+        setIsOpen(false);
+      }
+    }, [suggestions, inputFocused, value]);
+
+    // Handle input change
+    const handleInputChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        const newValue = e.target.value;
+        if (controlledValue === undefined) {
+          setInternalValue(newValue);
+        }
+        onInputChange?.(newValue);
+        setSelectedIndex(-1);
+        if (!newValue.trim()) {
+          onChange?.(null);
+          clearSuggestions();
+        }
+      },
+      [controlledValue, onInputChange, onChange, clearSuggestions]
+    );
+
+    // Handle address selection
+    const handleSelectAddress = React.useCallback(
+      async (placeId: string) => {
+        setIsOpen(false);
+        setSelectedIndex(-1);
+        const address = await selectAddress(placeId);
+        if (address) {
+          // Update input with formatted address
+          const displayValue = address.full_address || '';
+          if (controlledValue === undefined) {
+            setInternalValue(displayValue);
+          }
+          onInputChange?.(displayValue);
+          onChange?.(address);
+        }
+        inputRef.current?.blur();
+      },
+      [selectAddress, onChange, onInputChange, controlledValue]
+    );
+
+    // Handle keyboard navigation
+    const handleKeyDown = React.useCallback(
+      (e: React.KeyboardEvent<HTMLInputElement>) => {
+        if (!isOpen || suggestions.length === 0) {
+          if (e.key === 'Escape') {
+            setIsOpen(false);
+            inputRef.current?.blur();
+          }
+          return;
+        }
+
+        switch (e.key) {
+          case 'ArrowDown':
+            e.preventDefault();
+            setSelectedIndex((prev) => (prev < suggestions.length - 1 ? prev + 1 : prev));
+            break;
+          case 'ArrowUp':
+            e.preventDefault();
+            setSelectedIndex((prev) => (prev > 0 ? prev - 1 : -1));
+            break;
+          case 'Enter':
+            e.preventDefault();
+            if (selectedIndex >= 0 && selectedIndex < suggestions.length) {
+              handleSelectAddress(suggestions[selectedIndex].place_id);
+            }
+            break;
+          case 'Escape':
+            e.preventDefault();
+            setIsOpen(false);
+            setSelectedIndex(-1);
+            inputRef.current?.blur();
+            break;
+          case 'Tab':
+            setIsOpen(false);
+            setSelectedIndex(-1);
+            break;
+        }
+      },
+      [isOpen, suggestions, selectedIndex, handleSelectAddress]
+    );
+
+    // Handle focus
+    const handleFocus = React.useCallback(() => {
+      setInputFocused(true);
+      if (suggestions.length > 0 && value.trim()) {
+        setIsOpen(true);
+      }
+    }, [suggestions, value]);
+
+    // Handle blur
+    const handleBlur = React.useCallback(
+      (e: React.FocusEvent<HTMLInputElement>) => {
+        // Delay to allow click events on suggestions
+        setTimeout(() => {
+          if (!containerRef.current?.contains(document.activeElement)) {
+            setInputFocused(false);
+            setIsOpen(false);
+            setSelectedIndex(-1);
+          }
+        }, 200);
+      },
+      []
+    );
+
+    // Click outside handler
+    React.useEffect(() => {
+      const handleClickOutside = (event: MouseEvent) => {
+        if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+          setIsOpen(false);
+          setSelectedIndex(-1);
+        }
+      };
+
+      if (isOpen) {
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => {
+          document.removeEventListener('mousedown', handleClickOutside);
+        };
+      }
+    }, [isOpen]);
+
+    // Scroll selected item into view
+    React.useEffect(() => {
+      if (selectedIndex >= 0 && suggestionsRef.current) {
+        const selectedItem = suggestionsRef.current.children[selectedIndex] as HTMLElement;
+        if (selectedItem && typeof selectedItem.scrollIntoView === 'function') {
+          selectedItem.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+        }
+      }
+    }, [selectedIndex]);
+
+    // Combine refs
+    React.useImperativeHandle(ref, () => inputRef.current as HTMLInputElement);
+
+    const suggestionsId = React.useId();
+    const hasError = error || !!autocompleteError;
+
+    return (
+      <div ref={containerRef} className={cn('relative w-full', className)}>
+        <div className="relative">
+          <Input
+            ref={inputRef}
+            type="text"
+            value={value}
+            onChange={handleInputChange}
+            onKeyDown={handleKeyDown}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            placeholder={placeholder}
+            disabled={disabled}
+            error={hasError}
+            size={size}
+            variant={variant}
+            role="combobox"
+            aria-expanded={isOpen}
+            aria-autocomplete="list"
+            aria-controls={suggestionsId}
+            aria-haspopup="listbox"
+            aria-activedescendant={
+              selectedIndex >= 0 ? `${suggestionsId}-item-${selectedIndex}` : undefined
+            }
+            {...props}
+          />
+          {isLoading && (
+            <div className="absolute right-3 top-1/2 -translate-y-1/2 pointer-events-none">
+              <LoadingSpinner size="sm" />
+            </div>
+          )}
+        </div>
+
+        {isOpen && suggestions.length > 0 && (
+          <ul
+            ref={suggestionsRef}
+            id={suggestionsId}
+            role="listbox"
+            className={cn(
+              'absolute z-[99999] w-full mt-1 max-h-60 overflow-y-auto',
+              'border border-main-300 bg-main-50 shadow-lg rounded-md',
+              'list-none p-0 m-0'
+            )}
+            data-testid="address-suggestions"
+          >
+            {suggestions.map((suggestion, index) => (
+              <li
+                key={suggestion.place_id}
+                id={`${suggestionsId}-item-${index}`}
+                role="option"
+                aria-selected={selectedIndex === index}
+                className={cn(
+                  'px-3 py-2 cursor-pointer text-sm',
+                  'hover:bg-main-100 focus:bg-main-100',
+                  'border-b border-main-200 last:border-b-0',
+                  selectedIndex === index && 'bg-main-100'
+                )}
+                onClick={() => handleSelectAddress(suggestion.place_id)}
+                onMouseEnter={() => setSelectedIndex(index)}
+                data-testid={`address-suggestion-${index}`}
+              >
+                <div className="font-medium text-main-900">
+                  {suggestion.structured_formatting?.main_text || suggestion.description}
+                </div>
+                {suggestion.structured_formatting?.secondary_text && (
+                  <div className="text-xs text-main-600 mt-0.5">
+                    {suggestion.structured_formatting.secondary_text}
+                  </div>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+
+        {autocompleteError && (
+          <p className="mt-1 text-sm text-destructive" role="alert">
+            {autocompleteError.message}
+          </p>
+        )}
+      </div>
+    );
+  }
+);
+
+AddressField.displayName = 'AddressField';
+
+export { AddressField };
+export type { AddressFieldProps, AddressFieldRef, ParsedAddress } from './types';
+

package/src/components/AddressField/README.md

@@ -0,0 +1,336 @@
+# AddressField Component
+
+A production-ready address input field with Google Places API autocomplete integration. Provides address suggestions, keyboard navigation, caching for cost optimization, and returns structured address data including `place_id` for later retrieval.
+
+## Features
+
+- **Google Places API Integration**: Real-time address autocomplete suggestions
+- **Cost Optimization**: Built-in caching (1hr for autocomplete, 24hr for place details)
+- **place_id Storage**: Always returns `place_id` for efficient address retrieval
+- **Keyboard Navigation**: Full keyboard support (Arrow keys, Enter, Escape)
+- **Accessibility**: WCAG compliant with proper ARIA attributes
+- **Error Handling**: Graceful error handling with user-friendly messages
+- **Loading States**: Visual feedback during API calls
+- **TypeScript**: Fully typed with comprehensive type definitions
+
+## Installation
+
+The component is part of `@jmruthers/pace-core`. No additional installation required.
+
+## Setup
+
+### Google Cloud Console Configuration
+
+1. **Enable the Places API** in your Google Cloud Console
+2. **Create an API Key** with the following restrictions:
+   - **Application restrictions**: HTTP referrers (web sites)
+   - **Website restrictions**: Add your domain(s) and `http://localhost:*` for local development
+     - Example: `http://localhost:8091/*`
+     - Example: `https://yourdomain.com/*`
+3. **API restrictions**: Restrict to "Places API" only (recommended for security)
+
+### Environment Variable
+
+Set your API key in your `.env` file:
+
+```bash
+VITE_GOOGLE_PLACES_API_KEY=your-api-key-here
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { AddressField } from '@jmruthers/pace-core';
+
+function MyForm() {
+  const [address, setAddress] = useState(null);
+  const apiKey = import.meta.env.VITE_GOOGLE_PLACES_API_KEY;
+
+  return (
+    <AddressField
+      apiKey={apiKey}
+      onChange={(parsedAddress) => {
+        setAddress(parsedAddress);
+        // parsedAddress includes place_id, full_address, lat, lng, etc.
+        console.log('Selected place_id:', parsedAddress.place_id);
+      }}
+      placeholder="Enter your address"
+    />
+  );
+}
+```
+
+### Controlled Input
+
+```tsx
+function ControlledExample() {
+  const [inputValue, setInputValue] = useState('');
+  const [address, setAddress] = useState(null);
+
+  return (
+    <AddressField
+      apiKey={apiKey}
+      value={inputValue}
+      onInputChange={setInputValue}
+      onChange={setAddress}
+    />
+  );
+}
+```
+
+### With Country Restriction
+
+```tsx
+<AddressField
+  apiKey={apiKey}
+  onChange={handleAddressChange}
+  autocompleteOptions={{
+    components: 'country:au', // Restrict to Australia
+  }}
+/>
+```
+
+### With Custom Cache Settings
+
+```tsx
+<AddressField
+  apiKey={apiKey}
+  onChange={handleAddressChange}
+  cacheEnabled={true}
+  cacheTTL={{
+    autocomplete: 1800, // 30 minutes
+    placeDetails: 43200, // 12 hours
+  }}
+/>
+```
+
+### Retrieving Address from Stored place_id
+
+If you've stored a `place_id` in your database, you can retrieve the full address later:
+
+```tsx
+import { getAddressByPlaceId } from '@jmruthers/pace-core/utils/google-places';
+
+// Later, retrieve address from stored place_id
+const address = await getAddressByPlaceId(storedPlaceId, apiKey);
+if (address) {
+  console.log(address.full_address);
+  console.log(address.lat, address.lng);
+}
+```
+
+## Props
+
+### AddressFieldProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | **required** | Google Places API key |
+| `value` | `string` | - | Controlled input value |
+| `defaultValue` | `string` | `''` | Uncontrolled default value |
+| `onChange` | `(address: ParsedAddress \| null) => void` | - | Callback when address is selected |
+| `onInputChange` | `(value: string) => void` | - | Callback when input value changes |
+| `placeholder` | `string` | `'Enter address'` | Placeholder text |
+| `error` | `boolean` | `false` | Error state styling |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
+| `variant` | `'default' \| 'destructive'` | `'default'` | Input variant |
+| `autocompleteOptions` | `AutocompleteOptions` | - | Google Places API options |
+| `debounceDelay` | `number` | `300` | Debounce delay in milliseconds |
+| `cacheEnabled` | `boolean` | `true` | Enable caching |
+| `cacheTTL` | `{ autocomplete?: number; placeDetails?: number }` | `{ autocomplete: 3600, placeDetails: 86400 }` | Cache TTL in seconds |
+
+### AutocompleteOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `components` | `string` | Restrict results to specific countries (e.g., `'country:au'`) |
+| `location` | `string` | Location bias (e.g., `'-37.8136,144.9631'`) |
+| `radius` | `number` | Radius in meters for location bias |
+| `types` | `string` | Restrict results to specific place types |
+| `language` | `string` | Language code for results (e.g., `'en'`) |
+
+## ParsedAddress Type
+
+The `onChange` callback receives a `ParsedAddress` object matching the `pace_address` table structure:
+
+```typescript
+interface ParsedAddress {
+  place_id: string; // Always included - stable identifier
+  full_address: string | null;
+  street_number: string | null;
+  route: string | null;
+  suburb: string | null;
+  state: string | null;
+  postcode: string | null;
+  country: string | null;
+  lat: number | null;
+  lng: number | null;
+}
+```
+
+## Caching Strategy
+
+The component uses intelligent caching to reduce API costs:
+
+- **Autocomplete Results**: Cached for 1 hour (default) by query string
+- **Place Details**: Cached for 24 hours (default) by `place_id`
+- **Request Deduplication**: Prevents duplicate simultaneous requests
+
+### Why This Matters
+
+- **Cost Savings**: Repeated searches for the same address don't trigger new API calls
+- **Performance**: Cached results are returned instantly
+- **place_id Storage**: Store `place_id` in your database to retrieve addresses later without autocomplete searches
+
+### Cache Configuration
+
+```tsx
+<AddressField
+  apiKey={apiKey}
+  cacheEnabled={true} // Enable/disable caching
+  cacheTTL={{
+    autocomplete: 3600, // 1 hour in seconds
+    placeDetails: 86400, // 24 hours in seconds
+  }}
+/>
+```
+
+## place_id Usage
+
+The `place_id` is a stable identifier for a location that doesn't change. It's crucial for:
+
+1. **Storing in Database**: Save `place_id` in your `pace_address` table
+2. **Retrieving Later**: Use `getAddressByPlaceId()` to get full address without autocomplete
+3. **Verification**: Verify addresses haven't changed
+4. **Cost Efficiency**: Place details lookups are cheaper than autocomplete searches
+
+### Example: Storing and Retrieving
+
+```tsx
+// When user selects an address
+<AddressField
+  apiKey={apiKey}
+  onChange={async (address) => {
+    // Store in database
+    await supabase.from('pace_address').insert({
+      place_id: address.place_id, // Store this!
+      full_address: address.full_address,
+      lat: address.lat,
+      lng: address.lng,
+      // ... other fields
+    });
+  }}
+/>
+
+// Later, retrieve from stored place_id
+const storedPlaceId = 'ChIJ123...';
+const address = await getAddressByPlaceId(storedPlaceId, apiKey);
+```
+
+## Keyboard Navigation
+
+- **Arrow Down**: Navigate to next suggestion
+- **Arrow Up**: Navigate to previous suggestion
+- **Enter**: Select highlighted suggestion
+- **Escape**: Close suggestions dropdown
+- **Tab**: Close suggestions and move to next field
+
+## Accessibility
+
+The component follows WCAG 2.1 guidelines:
+
+- **ARIA Attributes**: Proper `role`, `aria-expanded`, `aria-autocomplete`, `aria-controls`
+- **Keyboard Navigation**: Full keyboard support
+- **Screen Readers**: Proper announcements and labels
+- **Focus Management**: Proper focus handling
+
+## Error Handling
+
+The component handles various error scenarios:
+
+- **Network Errors**: Displays user-friendly error message
+- **API Key Errors**: Clear error about API key configuration
+- **Rate Limiting**: Informs user about quota limits
+- **Invalid Requests**: Validates input and displays errors
+
+## Integration with pace_address Table
+
+The `ParsedAddress` type matches the `pace_address` table structure, making it easy to store results:
+
+```tsx
+<AddressField
+  apiKey={apiKey}
+  onChange={async (address) => {
+    const { data, error } = await supabase
+      .from('pace_address')
+      .insert({
+        place_id: address.place_id,
+        full_address: address.full_address,
+        street_number: address.street_number,
+        route: address.route,
+        suburb: address.suburb,
+        state: address.state,
+        postcode: address.postcode,
+        country: address.country,
+        lat: address.lat,
+        lng: address.lng,
+        organisation_id: currentOrganisationId,
+      });
+  }}
+/>
+```
+
+## API Key Setup
+
+1. Get a Google Places API key from [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the following APIs:
+   - Places API
+   - Places API (New)
+3. Set up API key restrictions (recommended)
+4. Add to your environment variables:
+
+```env
+VITE_GOOGLE_PLACES_API_KEY=your-api-key-here
+```
+
+## Best Practices
+
+1. **Store place_id**: Always save `place_id` in your database for later retrieval
+2. **Enable Caching**: Keep caching enabled to reduce API costs
+3. **Handle Errors**: Implement proper error handling in your `onChange` callback
+4. **Country Restrictions**: Use `autocompleteOptions.components` to restrict to specific countries
+5. **Debounce Delay**: Adjust `debounceDelay` based on your needs (default 300ms is usually good)
+
+## Troubleshooting
+
+### No suggestions appearing
+
+- Check API key is valid and has Places API enabled
+- Verify API key has billing enabled
+- Check browser console for error messages
+- Ensure input has at least 2-3 characters
+
+### Suggestions not closing
+
+- Check if there are click handlers preventing blur events
+- Verify `onBlur` is not being prevented
+
+### Caching not working
+
+- Ensure `cacheEnabled` is `true` (default)
+- Check that `useQueryCache` hook is working properly
+
+## Related Components
+
+- `Input` - Base input component used by AddressField
+- `Select` - Similar dropdown pattern for reference
+
+## Related Utilities
+
+- `getAddressByPlaceId` - Retrieve address from stored `place_id`
+- `fetchPlaceAutocomplete` - Direct API access (if needed)
+- `fetchPlaceDetails` - Direct API access (if needed)
+

package/src/components/AddressField/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file AddressField Component Exports
+ * @package @jmruthers/pace-core
+ * @module Components/AddressField
+ * @since 0.1.0
+ */
+
+export { AddressField } from './AddressField';
+export type { AddressFieldProps, AddressFieldRef, ParsedAddress, AutocompleteOptions } from './types';
+