@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,7 +1,18 @@
 import type { ReactNode } from 'react';
 
+import type { MockPrediction } from './mockPlaces';
+
 /// <reference types="@types/google.maps" />
 
+// What the Autocomplete holds: a live prediction, a canned one, or — in freeSolo
+// mode — the raw text.
+export type AddressOptionValue =
+  | string
+  | google.maps.places.AutocompletePrediction
+  | MockPrediction;
+
+export type AddressPrediction = google.maps.places.AutocompletePrediction | MockPrediction;
+
 export interface AddressDetails {
   formatted: string;
   street: string;

package/src/components/form/AddressAutocomplete/AddressAutocompleteField.tsx

@@ -0,0 +1,86 @@
+import { Alert, Autocomplete, Box } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import {
+  addressOptionLabel,
+  isSameAddressOption,
+  MIN_QUERY_LENGTH,
+  type ResolvedAddressProps,
+} from './AddressAutocomplete.helpers';
+import type { AddressAutocompleteState } from './AddressAutocomplete.hooks';
+import { AddressInputField } from './AddressInputField';
+import { AddressOption } from './AddressOption';
+import { AddressSuggestionsPaper } from './AddressSuggestionsPaper';
+
+export type AddressAutocompleteFieldProps = ResolvedAddressProps & AddressAutocompleteState;
+
+// The live field, rendered once Google Maps (or the mock stand-in) is ready.
+export const AddressAutocompleteField: FC<AddressAutocompleteFieldProps> = ({
+  variant,
+  label,
+  placeholder,
+  icon,
+  floating,
+  error,
+  helperText,
+  disabled,
+  required,
+  fullWidth,
+  getCurrentLocation,
+  inputValue,
+  options,
+  loading,
+  apiError,
+  handleInputChange,
+  handleSelect,
+  handleGetCurrentLocation,
+}) => (
+  <Box data-testid="address-autocomplete-container">
+    <Autocomplete
+      freeSolo
+      options={options}
+      inputValue={inputValue}
+      onInputChange={handleInputChange}
+      onChange={handleSelect}
+      loading={loading}
+      disabled={disabled}
+      fullWidth={fullWidth}
+      getOptionLabel={addressOptionLabel}
+      isOptionEqualToValue={isSameAddressOption}
+      PaperComponent={AddressSuggestionsPaper}
+      noOptionsText={
+        inputValue.length <= MIN_QUERY_LENGTH ? 'Type at least 3 characters' : 'No addresses found'
+      }
+      renderOption={({ key, ...optionProps }, option, state) => (
+        <AddressOption
+          key={key}
+          optionProps={optionProps}
+          option={option}
+          index={state.index}
+        />
+      )}
+      renderInput={(params) => (
+        <AddressInputField
+          params={params}
+          addressVariant={variant}
+          label={floating ? undefined : label}
+          placeholder={placeholder}
+          icon={icon}
+          error={error || !!apiError}
+          helperText={apiError || helperText}
+          required={required}
+          disabled={disabled}
+          loading={loading}
+          showCurrentLocation={getCurrentLocation && !loading}
+          onGetCurrentLocation={handleGetCurrentLocation}
+        />
+      )}
+    />
+    {apiError && (
+      <Alert severity="warning" sx={{ mt: 1 }}>
+        {apiError}
+      </Alert>
+    )}
+  </Box>
+);

package/src/components/form/AddressAutocomplete/AddressFallbackField.tsx

@@ -0,0 +1,64 @@
+import { Alert, Box, CircularProgress, InputAdornment } from '@mui/material';
+import type { FC, ReactNode } from 'react';
+import React from 'react';
+
+import type { AddressAutocompleteProps } from './AddressAutocomplete.types';
+import { AddressTextField } from './AddressTextField';
+
+export interface AddressFallbackFieldProps {
+  variant: AddressAutocompleteProps['variant'];
+  label?: string;
+  placeholder?: string;
+  icon?: ReactNode;
+  floating: boolean;
+  fullWidth: boolean;
+  mapsError: string | null;
+}
+
+// Stands in for the Autocomplete before Google Maps is usable: a disabled field
+// that either spins or explains why it never loaded.
+export const AddressFallbackField: FC<AddressFallbackFieldProps> = ({
+  variant,
+  label,
+  placeholder,
+  icon,
+  floating,
+  fullWidth,
+  mapsError,
+}) => {
+  const startAdornment = icon ? <InputAdornment position="start">{icon}</InputAdornment> : undefined;
+
+  if (!mapsError) {
+    return (
+      <AddressTextField
+        addressVariant={variant}
+        label={floating ? undefined : label}
+        placeholder="Loading Google Maps..."
+        disabled
+        fullWidth={fullWidth}
+        InputProps={{
+          startAdornment,
+          endAdornment: <CircularProgress color="inherit" size={20} />,
+        }}
+      />
+    );
+  }
+
+  return (
+    <Box>
+      <AddressTextField
+        addressVariant={variant}
+        label={floating ? undefined : label}
+        placeholder={placeholder}
+        error
+        disabled
+        fullWidth={fullWidth}
+        helperText={mapsError}
+        InputProps={{ startAdornment }}
+      />
+      <Alert severity="error" sx={{ mt: 1 }}>
+        Google Maps API failed to load. Please check your API key and internet connection.
+      </Alert>
+    </Box>
+  );
+};

package/src/components/form/AddressAutocomplete/AddressInputField.tsx

@@ -0,0 +1,80 @@
+import CurrentLocationIcon from '@mui/icons-material/MyLocation';
+import type { AutocompleteRenderInputParams } from '@mui/material';
+import { CircularProgress, IconButton, InputAdornment } from '@mui/material';
+import type { FC, ReactNode } from 'react';
+import React from 'react';
+
+import type { AddressAutocompleteProps } from './AddressAutocomplete.types';
+import { AddressTextField } from './AddressTextField';
+
+const CurrentLocationButton: FC<{ disabled: boolean; onClick: () => void }> = ({
+  disabled,
+  onClick,
+}) => (
+  <InputAdornment position="end">
+    <IconButton
+      edge="end"
+      onClick={onClick}
+      size="small"
+      title="Use current location"
+      disabled={disabled}
+      data-testid="address-current-location-button"
+    >
+      <CurrentLocationIcon />
+    </IconButton>
+  </InputAdornment>
+);
+
+export interface AddressInputFieldProps {
+  params: AutocompleteRenderInputParams;
+  addressVariant: AddressAutocompleteProps['variant'];
+  label?: string;
+  placeholder?: string;
+  icon?: ReactNode;
+  error: boolean;
+  helperText?: string;
+  required: boolean;
+  disabled: boolean;
+  loading: boolean;
+  showCurrentLocation: boolean;
+  onGetCurrentLocation: () => void;
+}
+
+export const AddressInputField: FC<AddressInputFieldProps> = ({
+  params,
+  addressVariant,
+  label,
+  placeholder,
+  icon,
+  error,
+  helperText,
+  required,
+  disabled,
+  loading,
+  showCurrentLocation,
+  onGetCurrentLocation,
+}) => (
+  <AddressTextField
+    {...params}
+    addressVariant={addressVariant}
+    label={label}
+    placeholder={placeholder}
+    error={error}
+    helperText={helperText}
+    required={required}
+    InputProps={{
+      ...params.InputProps,
+      startAdornment: icon && <InputAdornment position="start">{icon}</InputAdornment>,
+      endAdornment: (
+        <>
+          {loading && <CircularProgress color="inherit" size={20} data-testid="address-loading" />}
+          {showCurrentLocation && (
+            <CurrentLocationButton disabled={disabled} onClick={onGetCurrentLocation} />
+          )}
+          {params.InputProps.endAdornment}
+        </>
+      ),
+    }}
+    inputProps={{ ...params.inputProps, 'data-testid': 'address-input' }}
+  />
+);

package/src/components/form/AddressAutocomplete/AddressOption.tsx

@@ -0,0 +1,83 @@
+import LocationIcon from '@mui/icons-material/LocationOn';
+import { alpha, Box, styled } from '@mui/material';
+import type { FC, HTMLAttributes } from 'react';
+import React from 'react';
+
+import type { AddressOptionValue } from './AddressAutocomplete.types';
+
+// Module-local: styled() components cannot be exported across a module boundary
+// here without tripping TS2742.
+const SuggestionItem = styled(Box)(({ theme }) => ({
+  padding: theme.spacing(1.5),
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: theme.spacing(1.5),
+  cursor: 'pointer',
+  transition: theme.transitions.create(['background-color']),
+  '&:hover': {
+    backgroundColor: alpha(theme.palette.primary.main, 0.08),
+  },
+}));
+
+const LocationIconWrapper = styled(Box)(({ theme }) => ({
+  marginTop: theme.spacing(0.5),
+  color: theme.palette.text.secondary,
+}));
+
+const AddressText = styled(Box)(({ theme }) => ({
+  flex: 1,
+  '& .primary': {
+    fontSize: '0.9rem',
+    fontWeight: 500,
+    color: theme.palette.text.primary,
+    marginBottom: theme.spacing(0.25),
+  },
+  '& .secondary': {
+    fontSize: '0.8rem',
+    color: theme.palette.text.secondary,
+  },
+}));
+
+// Predictions carry the street line and the rest already split; freeSolo text has
+// to be split on the first comma to get the same two lines.
+const optionText = (option: AddressOptionValue) => {
+  if (typeof option === 'string') {
+    return {
+      testId: 'address-suggestion-text',
+      primary: option.split(',')[0],
+      secondary: option.split(',').slice(1).join(','),
+    };
+  }
+
+  return {
+    testId: 'address-prediction-text',
+    primary: option.structured_formatting?.main_text || option.description?.split(',')[0],
+    secondary:
+      option.structured_formatting?.secondary_text ||
+      option.description?.split(',').slice(1).join(','),
+  };
+};
+
+export interface AddressOptionProps {
+  optionProps: HTMLAttributes<HTMLLIElement>;
+  option: AddressOptionValue;
+  index: number;
+}
+
+export const AddressOption: FC<AddressOptionProps> = ({ optionProps, option, index }) => {
+  const { testId, primary, secondary } = optionText(option);
+
+  return (
+    <li {...optionProps} data-testid={`address-suggestion-${index}`}>
+      <SuggestionItem>
+        <LocationIconWrapper>
+          <LocationIcon fontSize="small" />
+        </LocationIconWrapper>
+        <AddressText data-testid={testId}>
+          <div className="primary">{primary}</div>
+          <div className="secondary">{secondary}</div>
+        </AddressText>
+      </SuggestionItem>
+    </li>
+  );
+};

package/src/components/form/AddressAutocomplete/AddressSuggestionsPaper.tsx

@@ -0,0 +1,24 @@
+import type { PaperProps } from '@mui/material';
+import { alpha, Paper, useTheme } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+// The dropdown surface, frosted to match the glass field.
+export const AddressSuggestionsPaper: FC<PaperProps> = (props) => {
+  const theme = useTheme();
+
+  return (
+    <Paper
+      {...props}
+      elevation={8}
+      data-testid="address-suggestions-dropdown"
+      sx={{
+        mt: 1,
+        background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.98)} 0%, ${alpha(theme.palette.background.paper, 0.95)} 100%)`,
+        backdropFilter: 'blur(20px)',
+        WebkitBackdropFilter: 'blur(20px)',
+        border: `1px solid ${alpha(theme.palette.divider, 0.18)}`,
+      }}
+    />
+  );
+};

package/src/components/form/AddressAutocomplete/AddressTextField.tsx

@@ -0,0 +1,43 @@
+import type { TextFieldProps } from '@mui/material';
+import { alpha, styled, TextField } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import type { AddressAutocompleteProps } from './AddressAutocomplete.types';
+
+// Kept module-local on purpose: the inferred type of a styled() component cannot
+// be named across a module boundary here (TS2742), so the plain component below
+// is what the rest of the folder imports.
+const GlassTextField = styled(TextField)(({ theme }) => ({
+  '& .MuiOutlinedInput-root': {
+    background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.8)} 0%, ${alpha(theme.palette.background.paper, 0.6)} 100%)`,
+    backdropFilter: 'blur(10px)',
+    WebkitBackdropFilter: 'blur(10px)',
+    border: `1px solid ${alpha(theme.palette.divider, 0.18)}`,
+    transition: theme.transitions.create(['border-color', 'box-shadow', 'background']),
+    '&:hover': {
+      background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.9)} 0%, ${alpha(theme.palette.background.paper, 0.7)} 100%)`,
+      borderColor: theme.palette.primary.main,
+    },
+    '&.Mui-focused': {
+      background: theme.palette.background.paper,
+      boxShadow: `0 0 0 2px ${alpha(theme.palette.primary.main, 0.25)}`,
+    },
+    '& fieldset': {
+      border: 'none',
+    },
+  },
+}));
+
+export type AddressTextFieldProps = Omit<TextFieldProps, 'variant'> & {
+  addressVariant: AddressAutocompleteProps['variant'];
+};
+
+// 'glass' is not a MUI variant: it renders the outlined field with the frosted
+// treatment on top.
+export const AddressTextField: FC<AddressTextFieldProps> = ({ addressVariant, ...props }) =>
+  addressVariant === 'glass' ? (
+    <GlassTextField variant="outlined" {...props} />
+  ) : (
+    <TextField variant={addressVariant} {...props} />
+  );

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

@@ -0,0 +1,208 @@
+export interface MockPrediction {
+  place_id: string;
+  description: string;
+  structured_formatting: {
+    main_text: string;
+    secondary_text: string;
+  };
+  matched_substrings?: google.maps.places.PredictionSubstring[];
+  terms?: google.maps.places.PredictionTerm[];
+  types?: string[];
+}
+
+// Canned Places data so the component renders and is testable without a Google
+// Maps key.
+export const MOCK_ADDRESSES: MockPrediction[] = [
+  {
+    place_id: 'mock_1',
+    description: '123 Main Street, San Francisco, CA 94105, USA',
+    structured_formatting: {
+      main_text: '123 Main Street',
+      secondary_text: 'San Francisco, CA 94105, USA',
+    },
+    matched_substrings: [],
+    terms: [],
+    types: ['street_address'],
+  },
+  {
+    place_id: 'mock_2',
+    description: '456 Oak Avenue, New York, NY 10001, USA',
+    structured_formatting: {
+      main_text: '456 Oak Avenue',
+      secondary_text: 'New York, NY 10001, USA',
+    },
+    matched_substrings: [],
+    terms: [],
+    types: ['street_address'],
+  },
+  {
+    place_id: 'mock_3',
+    description: '789 Pine Boulevard, Los Angeles, CA 90001, USA',
+    structured_formatting: {
+      main_text: '789 Pine Boulevard',
+      secondary_text: 'Los Angeles, CA 90001, USA',
+    },
+    matched_substrings: [],
+    terms: [],
+    types: ['street_address'],
+  },
+  {
+    place_id: 'mock_4',
+    description: '321 Elm Street, Chicago, IL 60601, USA',
+    structured_formatting: {
+      main_text: '321 Elm Street',
+      secondary_text: 'Chicago, IL 60601, USA',
+    },
+    matched_substrings: [],
+    terms: [],
+    types: ['street_address'],
+  },
+  {
+    place_id: 'mock_5',
+    description: '654 Maple Drive, Austin, TX 78701, USA',
+    structured_formatting: {
+      main_text: '654 Maple Drive',
+      secondary_text: 'Austin, TX 78701, USA',
+    },
+    matched_substrings: [],
+    terms: [],
+    types: ['street_address'],
+  },
+];
+
+interface MockPlaceDetails {
+  formatted_address: string;
+  address_components: Array<{
+    long_name: string;
+    types: string[];
+  }>;
+  geometry: {
+    location: {
+      lat: () => number;
+      lng: () => number;
+    };
+  };
+}
+
+export const MOCK_PLACE_DETAILS: Record<string, MockPlaceDetails> = {
+  mock_1: {
+    formatted_address: '123 Main Street, San Francisco, CA 94105, USA',
+    address_components: [
+      { long_name: '123', types: ['street_number'] },
+      { long_name: 'Main Street', types: ['route'] },
+      { long_name: 'San Francisco', types: ['locality'] },
+      { long_name: 'California', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '94105', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 37.7749, lng: () => -122.4194 } },
+  },
+  mock_2: {
+    formatted_address: '456 Oak Avenue, New York, NY 10001, USA',
+    address_components: [
+      { long_name: '456', types: ['street_number'] },
+      { long_name: 'Oak Avenue', types: ['route'] },
+      { long_name: 'New York', types: ['locality'] },
+      { long_name: 'New York', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '10001', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 40.7128, lng: () => -74.0060 } },
+  },
+  mock_3: {
+    formatted_address: '789 Pine Boulevard, Los Angeles, CA 90001, USA',
+    address_components: [
+      { long_name: '789', types: ['street_number'] },
+      { long_name: 'Pine Boulevard', types: ['route'] },
+      { long_name: 'Los Angeles', types: ['locality'] },
+      { long_name: 'California', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '90001', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 34.0522, lng: () => -118.2437 } },
+  },
+  mock_4: {
+    formatted_address: '321 Elm Street, Chicago, IL 60601, USA',
+    address_components: [
+      { long_name: '321', types: ['street_number'] },
+      { long_name: 'Elm Street', types: ['route'] },
+      { long_name: 'Chicago', types: ['locality'] },
+      { long_name: 'Illinois', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '60601', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 41.8781, lng: () => -87.6298 } },
+  },
+  mock_5: {
+    formatted_address: '654 Maple Drive, Austin, TX 78701, USA',
+    address_components: [
+      { long_name: '654', types: ['street_number'] },
+      { long_name: 'Maple Drive', types: ['route'] },
+      { long_name: 'Austin', types: ['locality'] },
+      { long_name: 'Texas', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '78701', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 30.2672, lng: () => -97.7431 } },
+  },
+  mock_6: {
+    formatted_address: '1000 Broadway, New York, NY 10001, USA',
+    address_components: [
+      { long_name: '1000', types: ['street_number'] },
+      { long_name: 'Broadway', types: ['route'] },
+      { long_name: 'New York', types: ['locality'] },
+      { long_name: 'New York', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '10001', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 40.7589, lng: () => -73.9851 } },
+  },
+  mock_7: {
+    formatted_address: '250 Market Street, San Francisco, CA 94102, USA',
+    address_components: [
+      { long_name: '250', types: ['street_number'] },
+      { long_name: 'Market Street', types: ['route'] },
+      { long_name: 'San Francisco', types: ['locality'] },
+      { long_name: 'California', types: ['administrative_area_level_1'] },
+      { long_name: 'United States', types: ['country'] },
+      { long_name: '94102', types: ['postal_code'] },
+    ],
+    geometry: { location: { lat: () => 37.7879, lng: () => -122.4075 } },
+  },
+};
+
+// Every word has to appear somewhere in the address, which is roughly how Google
+// treats a multi-word query.
+const matchesAllWords = (address: MockPrediction, searchTerm: string): boolean => {
+  const description = address.description.toLowerCase();
+  const mainText = address.structured_formatting.main_text.toLowerCase();
+  const secondaryText = address.structured_formatting.secondary_text?.toLowerCase() || '';
+
+  return searchTerm
+    .split(' ')
+    .every(
+      (word) =>
+        description.includes(word) || mainText.includes(word) || secondaryText.includes(word),
+    );
+};
+
+// Addresses whose street line starts with the query come first; the rest sort
+// alphabetically.
+const byRelevance =
+  (searchTerm: string) =>
+  (a: MockPrediction, b: MockPrediction): number => {
+    const aMain = a.structured_formatting.main_text.toLowerCase();
+    const bMain = b.structured_formatting.main_text.toLowerCase();
+
+    if (aMain.startsWith(searchTerm) && !bMain.startsWith(searchTerm)) return -1;
+    if (!aMain.startsWith(searchTerm) && bMain.startsWith(searchTerm)) return 1;
+    return aMain.localeCompare(bMain);
+  };
+
+export const searchMockAddresses = (input: string): MockPrediction[] => {
+  const searchTerm = input.toLowerCase().trim();
+
+  return MOCK_ADDRESSES.filter((address) => matchesAllWords(address, searchTerm)).sort(
+    byRelevance(searchTerm),
+  );
+};