@12-apps/ui 1.0.0 → 1.3.1

package/src/components/form/AddressAutocomplete/useAddressPredictions.ts

@@ -0,0 +1,136 @@
+import type React from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { MIN_QUERY_LENGTH } from './AddressAutocomplete.helpers';
+import type { AddressAutocompleteProps, AddressOptionValue } from './AddressAutocomplete.types';
+import { searchMockAddresses } from './mockPlaces';
+import type { GoogleMapsService } from './useGoogleMapsAPI';
+
+const DEBOUNCE_MS = 300;
+// Long enough to exercise the loading state, short enough not to slow tests down.
+const MOCK_PREDICTION_DELAY_MS = 100;
+
+type Restrictions = AddressAutocompleteProps['restrictions'];
+
+interface PredictionSink {
+  setOptions: (options: AddressOptionValue[]) => void;
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+}
+
+const predictionRequest = (
+  input: string,
+  restrictions: Restrictions,
+): google.maps.places.AutocompletionRequest => ({
+  input: input.trim(),
+  componentRestrictions: restrictions?.country ? { country: restrictions.country } : undefined,
+  types: restrictions?.types || [],
+});
+
+const fetchMockPredictions = (input: string, sink: PredictionSink) => {
+  window.setTimeout(() => {
+    sink.setLoading(false);
+    sink.setOptions(searchMockAddresses(input));
+    sink.setApiError(null);
+  }, MOCK_PREDICTION_DELAY_MS);
+};
+
+const fetchLivePredictions = (
+  service: google.maps.places.AutocompleteService,
+  input: string,
+  restrictions: Restrictions,
+  sink: PredictionSink,
+) => {
+  service.getPlacePredictions(predictionRequest(input, restrictions), (predictions, status) => {
+    sink.setLoading(false);
+
+    if (status === google.maps.places.PlacesServiceStatus.OK && predictions) {
+      sink.setOptions(predictions);
+      sink.setApiError(null);
+      return;
+    }
+
+    // No matches is a normal outcome, not something to complain about.
+    sink.setOptions([]);
+    sink.setApiError(
+      status === google.maps.places.PlacesServiceStatus.ZERO_RESULTS
+        ? null
+        : 'Failed to fetch address suggestions',
+    );
+  });
+};
+
+export const useAddressPredictions = ({
+  isLoaded,
+  services,
+  restrictions,
+  useMockData,
+  setInputValue,
+  setLoading,
+  setApiError,
+}: {
+  isLoaded: boolean;
+  services: GoogleMapsService;
+  restrictions: Restrictions;
+  useMockData: boolean;
+  setInputValue: (value: string) => void;
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+}) => {
+  const [options, setOptions] = useState<AddressOptionValue[]>([]);
+  const debounceTimeoutRef = useRef<number | undefined>(undefined);
+
+  const sink = useMemo<PredictionSink>(
+    () => ({ setOptions, setLoading, setApiError }),
+    [setLoading, setApiError],
+  );
+
+  const debouncedAutocomplete = useCallback(
+    (input: string) => {
+      window.clearTimeout(debounceTimeoutRef.current);
+
+      debounceTimeoutRef.current = window.setTimeout(() => {
+        if (!input.trim() || !isLoaded) {
+          setOptions([]);
+          setLoading(false);
+          return;
+        }
+
+        if (useMockData) {
+          fetchMockPredictions(input, sink);
+          return;
+        }
+
+        if (!services.autocompleteService) {
+          setOptions([]);
+          setLoading(false);
+          return;
+        }
+
+        fetchLivePredictions(services.autocompleteService, input, restrictions, sink);
+      }, DEBOUNCE_MS);
+    },
+    [isLoaded, services, restrictions, useMockData, sink, setLoading],
+  );
+
+  useEffect(() => () => window.clearTimeout(debounceTimeoutRef.current), []);
+
+  const handleInputChange = useCallback(
+    (_event: React.SyntheticEvent, value: string) => {
+      setInputValue(value);
+      setApiError(null);
+
+      if (value.length > MIN_QUERY_LENGTH) {
+        setLoading(true);
+        debouncedAutocomplete(value);
+        return;
+      }
+
+      setOptions([]);
+      setLoading(false);
+    },
+    [debouncedAutocomplete, setInputValue, setApiError, setLoading],
+  );
+
+  return { options, handleInputChange };
+};

package/src/components/form/AddressAutocomplete/useAddressSelection.ts

@@ -0,0 +1,113 @@
+import type React from 'react';
+import { useCallback } from 'react';
+
+import { coordinatesOf, freeSoloAddress, toAddressDetails } from './AddressAutocomplete.mapper';
+import type {
+  AddressDetails,
+  AddressOptionValue,
+  AddressPrediction,
+} from './AddressAutocomplete.types';
+import { MOCK_PLACE_DETAILS } from './mockPlaces';
+import type { GoogleMapsService } from './useGoogleMapsAPI';
+
+const MOCK_DETAILS_DELAY_MS = 50;
+
+const PLACE_DETAIL_FIELDS = ['formatted_address', 'address_components', 'geometry'];
+
+interface SelectionSink {
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+  applyAddress: (address: AddressDetails) => void;
+}
+
+const resolveMockPlace = (value: AddressPrediction, sink: SelectionSink) => {
+  window.setTimeout(() => {
+    sink.setLoading(false);
+
+    const place = MOCK_PLACE_DETAILS[value.place_id];
+    if (!place) {
+      sink.setApiError('Address details not found');
+      return;
+    }
+
+    sink.applyAddress(
+      toAddressDetails({
+        components: place.address_components,
+        formatted: place.formatted_address || value.description,
+        coordinates: coordinatesOf(place.geometry),
+      }),
+    );
+  }, MOCK_DETAILS_DELAY_MS);
+};
+
+const resolveLivePlace = (
+  service: google.maps.places.PlacesService,
+  value: AddressPrediction,
+  sink: SelectionSink,
+) => {
+  const request: google.maps.places.PlaceDetailsRequest = {
+    placeId: value.place_id,
+    fields: PLACE_DETAIL_FIELDS,
+  };
+
+  service.getDetails(request, (place, status) => {
+    sink.setLoading(false);
+
+    if (status !== google.maps.places.PlacesServiceStatus.OK || !place) {
+      sink.setApiError('Failed to get address details');
+      return;
+    }
+
+    sink.applyAddress(
+      toAddressDetails({
+        components: place.address_components ?? [],
+        formatted: place.formatted_address || value.description,
+        coordinates: coordinatesOf(place.geometry),
+      }),
+    );
+  });
+};
+
+export const useAddressSelection = ({
+  services,
+  useMockData,
+  setLoading,
+  setApiError,
+  onSelect,
+  applyAddress,
+}: {
+  services: GoogleMapsService;
+  useMockData: boolean;
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+  onSelect: (address: AddressDetails) => void;
+  applyAddress: (address: AddressDetails) => void;
+}) =>
+  useCallback(
+    (_event: React.SyntheticEvent, value: AddressOptionValue | null) => {
+      // freeSolo text is reported as typed; there is no place to look up, and the
+      // input already holds it.
+      if (typeof value === 'string') {
+        onSelect(freeSoloAddress(value));
+        return;
+      }
+
+      if (!value) return;
+
+      setLoading(true);
+      const sink: SelectionSink = { setLoading, setApiError, applyAddress };
+
+      if (useMockData && 'place_id' in value) {
+        resolveMockPlace(value, sink);
+        return;
+      }
+
+      if (!services.placesService) {
+        setLoading(false);
+        return;
+      }
+
+      resolveLivePlace(services.placesService, value, sink);
+    },
+    [services, useMockData, setLoading, setApiError, onSelect, applyAddress],
+  );

package/src/components/form/AddressAutocomplete/useCurrentLocation.ts

@@ -0,0 +1,116 @@
+import { useCallback } from 'react';
+
+import { coordinatesOf, toAddressDetails } from './AddressAutocomplete.mapper';
+import type { AddressDetails } from './AddressAutocomplete.types';
+import { MOCK_ADDRESSES, MOCK_PLACE_DETAILS } from './mockPlaces';
+import type { GoogleMapsService } from './useGoogleMapsAPI';
+
+const MOCK_GEOLOCATION_DELAY_MS = 500;
+
+const GEOLOCATION_OPTIONS: PositionOptions = {
+  enableHighAccuracy: true,
+  timeout: 10_000,
+  maximumAge: 600_000, // 10 minutes
+};
+
+interface LocationSink {
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+  applyAddress: (address: AddressDetails) => void;
+}
+
+// Mock mode answers with the first canned address after a pause, so the button
+// behaves like a real geolocation round trip.
+const resolveMockLocation = (sink: LocationSink) => {
+  window.setTimeout(() => {
+    sink.setLoading(false);
+
+    const mockLocation = MOCK_ADDRESSES[0];
+    if (!mockLocation) {
+      sink.setApiError('No mock location available');
+      return;
+    }
+
+    const mockDetails = MOCK_PLACE_DETAILS[mockLocation.place_id];
+    if (!mockDetails) {
+      sink.setApiError('Mock location details not found');
+      return;
+    }
+
+    sink.applyAddress(
+      toAddressDetails({
+        components: mockDetails.address_components,
+        formatted: mockDetails.formatted_address,
+        coordinates: coordinatesOf(mockDetails.geometry),
+      }),
+    );
+  }, MOCK_GEOLOCATION_DELAY_MS);
+};
+
+const geocodePosition =
+  (geocoder: google.maps.Geocoder, sink: LocationSink) => (position: GeolocationPosition) => {
+    const { latitude, longitude } = position.coords;
+    const location = new google.maps.LatLng(latitude, longitude);
+
+    geocoder.geocode({ location }, (results, status) => {
+      sink.setLoading(false);
+
+      const place = status === 'OK' ? results?.[0] : undefined;
+      if (!place) {
+        sink.setApiError('Unable to retrieve address for current location');
+        return;
+      }
+
+      sink.applyAddress(
+        toAddressDetails({
+          components: place.address_components,
+          formatted: place.formatted_address,
+          // The device's own fix is more precise than the geocoded place's.
+          coordinates: { lat: latitude, lng: longitude },
+        }),
+      );
+    });
+  };
+
+export const useCurrentLocation = ({
+  services,
+  useMockData,
+  setLoading,
+  setApiError,
+  applyAddress,
+}: {
+  services: GoogleMapsService;
+  useMockData: boolean;
+  setLoading: (loading: boolean) => void;
+  setApiError: (message: string | null) => void;
+  applyAddress: (address: AddressDetails) => void;
+}) =>
+  useCallback(() => {
+    if (!navigator.geolocation) {
+      setApiError('Geolocation is not supported by this browser');
+      return;
+    }
+
+    const sink: LocationSink = { setLoading, setApiError, applyAddress };
+
+    if (useMockData) {
+      setLoading(true);
+      resolveMockLocation(sink);
+      return;
+    }
+
+    if (!services.geocoder) {
+      setApiError('Geocoding service not available');
+      return;
+    }
+
+    setLoading(true);
+    navigator.geolocation.getCurrentPosition(
+      geocodePosition(services.geocoder, sink),
+      () => {
+        setLoading(false);
+        setApiError('Unable to retrieve your location');
+      },
+      GEOLOCATION_OPTIONS,
+    );
+  }, [services, useMockData, setLoading, setApiError, applyAddress]);

package/src/components/form/AddressAutocomplete/useGoogleMapsAPI.ts

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from 'react';
+
+export interface GoogleMapsService {
+  autocompleteService: google.maps.places.AutocompleteService | null;
+  placesService: google.maps.places.PlacesService | null;
+  geocoder: google.maps.Geocoder | null;
+}
+
+export const useGoogleMapsAPI = (apiKey: string) => {
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [useMockData, setUseMockData] = useState(false);
+  const serviceRef = useRef<GoogleMapsService>({
+    autocompleteService: null,
+    placesService: null,
+    geocoder: null,
+  });
+
+  useEffect(() => {
+    // Use mock data for demo key or test environment
+    if (!apiKey || apiKey === 'demo-key' || apiKey === 'test-key') {
+      setUseMockData(true);
+      setIsLoaded(true);
+      setError(null);
+      return;
+    }
+
+    // Check if Google Maps is already loaded
+    if (window.google && window.google.maps && window.google.maps.places) {
+      initializeServices();
+      return;
+    }
+
+    // Load Google Maps API
+    const script = document.createElement('script');
+    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&libraries=places`;
+    script.async = true;
+    script.defer = true;
+    
+    script.onload = () => {
+      initializeServices();
+    };
+    
+    script.onerror = () => {
+      setError('Failed to load Google Maps API');
+    };
+
+    document.head.appendChild(script);
+
+    return () => {
+      // Cleanup script if component unmounts
+      if (document.head.contains(script)) {
+        document.head.removeChild(script);
+      }
+    };
+  }, [apiKey]);
+
+  const initializeServices = () => {
+    try {
+      if (window.google && window.google.maps && window.google.maps.places) {
+        serviceRef.current = {
+          autocompleteService: new window.google.maps.places.AutocompleteService(),
+          placesService: new window.google.maps.places.PlacesService(document.createElement('div')),
+          geocoder: new window.google.maps.Geocoder(),
+        };
+        setIsLoaded(true);
+        setError(null);
+      }
+    } catch {
+      setError('Failed to initialize Google Maps services');
+    }
+  };
+
+  return { isLoaded, error, services: serviceRef.current, useMockData };
+};

package/src/components/form/Button/Button.helpers.ts

@@ -0,0 +1,36 @@
+import type { ButtonProps } from './Button.types';
+
+type ButtonDefaultedKeys =
+  | 'variant'
+  | 'color'
+  | 'size'
+  | 'loading'
+  | 'iconPosition'
+  | 'glow'
+  | 'pulse'
+  | 'ripple'
+  | 'active';
+
+type ResolvedButtonProps = ButtonProps & Required<Pick<ButtonProps, ButtonDefaultedKeys>>;
+
+const BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {
+  variant: 'solid',
+  color: 'primary',
+  size: 'md',
+  loading: false,
+  iconPosition: 'left',
+  glow: false,
+  pulse: false,
+  ripple: true,
+  active: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `size={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: ButtonProps): Partial<ButtonProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<ButtonProps>;
+
+export const resolveButtonProps = (props: ButtonProps): ResolvedButtonProps =>
+  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps;

package/src/components/form/Button/Button.stories.tsx

@@ -1,4 +1,7 @@
-import { Add, ArrowForward,Delete, Save } from '@mui/icons-material';
+import Add from '@mui/icons-material/Add';
+import ArrowForward from '@mui/icons-material/ArrowForward';
+import Delete from '@mui/icons-material/Delete';
+import Save from '@mui/icons-material/Save';
 import { Stack } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';