@12-apps/ui 1.0.0 → 1.3.1

package/src/components/feedback/TutorialOverlay/TutorialStepBody.tsx

@@ -0,0 +1,255 @@
+import CompleteIcon from '@mui/icons-material/CheckCircle';
+import CloseIcon from '@mui/icons-material/Close';
+import PrevIcon from '@mui/icons-material/NavigateBefore';
+import NextIcon from '@mui/icons-material/NavigateNext';
+import RestartIcon from '@mui/icons-material/Refresh';
+import {
+  alpha,
+  Box,
+  Button,
+  IconButton,
+  Stack,
+  styled,
+  Typography } from '@mui/material';
+import React, {  } from 'react';
+
+import type { TutorialOverlayProps } from './TutorialOverlay.types';
+
+// Animation keyframes
+
+const StepIndicator = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  gap: theme.spacing(1),
+  marginTop: theme.spacing(2),
+  marginBottom: theme.spacing(2) }));
+
+
+const StepDot = styled(Box, {
+  shouldForwardProp: (prop) => prop !== 'active' && prop !== 'completed' })<{ active?: boolean; completed?: boolean }>(({ theme, active, completed }) => ({
+  width: 8,
+  height: 8,
+  borderRadius: '50%',
+  background: completed
+    ? theme.palette.success.main
+    : active
+      ? theme.palette.primary.main
+      : alpha(theme.palette.text.primary, 0.3),
+  transition: 'all 0.3s ease',
+  ...(active && {
+    transform: 'scale(1.5)' }) }));
+
+// Title, body copy, the step dots and the navigation row.
+
+// The step's controls: skip/restart on the left, previous/next on the right.
+const TutorialStepNav: React.FC<{
+  currentStep: number;
+  stepCount: number;
+  isLastStep: boolean;
+  allowSkip: boolean;
+  requiresActionBeforeNext?: boolean;
+  onNext: () => void;
+  onPrev: () => void;
+  onSkip: () => void;
+  onRestart: () => void;
+}> = ({
+  currentStep,
+  stepCount,
+  isLastStep,
+  allowSkip,
+  requiresActionBeforeNext,
+  onNext,
+  onPrev,
+  onSkip,
+  onRestart }) => (
+        <Stack
+          direction="row"
+          spacing={1}
+          justifyContent="space-between"
+          data-testid="tutorial-navigation"
+        >
+          <Stack direction="row" spacing={1}>
+            {allowSkip && (
+              <Button size="small" onClick={onSkip} variant="text">
+                Skip
+              </Button>
+            )}
+            {stepCount > 1 && (
+              <IconButton
+                size="small"
+                onClick={onRestart}
+                disabled={currentStep === 0}
+                title="Restart"
+              >
+                <RestartIcon fontSize="small" />
+              </IconButton>
+            )}
+          </Stack>
+
+          <Stack direction="row" spacing={1}>
+            {stepCount > 1 && currentStep > 0 && (
+              <Button
+                size="small"
+                startIcon={<PrevIcon />}
+                onClick={onPrev}
+                disabled={currentStep === 0}
+                data-testid="tutorial-prev-button"
+              >
+                Previous
+              </Button>
+            )}
+
+            {!isLastStep ? (
+              <Button
+                variant="contained"
+                size="small"
+                endIcon={<NextIcon />}
+                onClick={onNext}
+                disabled={requiresActionBeforeNext}
+                title={requiresActionBeforeNext ? 'Complete the required action first' : ''}
+                data-testid="tutorial-next-button"
+              >
+                Next
+              </Button>
+            ) : (
+              <Button
+                variant="contained"
+                size="small"
+                endIcon={<CompleteIcon />}
+                onClick={onNext}
+                sx={{
+                  background: 'linear-gradient(135deg, #84fab0 0%, #8fd3f4 100%)' }}
+                data-testid="tutorial-finish-button"
+              >
+                {stepCount === 1 ? 'Complete' : 'Finish'}
+              </Button>
+            )}
+          </Stack>
+        </Stack>
+);
+
+const StepDots: React.FC<{ currentStep: number; stepCount: number }> = ({
+  currentStep,
+  stepCount }) => (
+  <StepIndicator data-testid="tutorial-step-indicators">
+    {Array.from({ length: stepCount }).map((_, index) => (
+      <StepDot
+        key={index}
+        active={index === currentStep}
+        completed={index < currentStep}
+        data-testid={`tutorial-indicator-${index}`}
+      />
+    ))}
+  </StepIndicator>
+);
+
+// Title, and the close button when skipping is allowed.
+const TutorialStepHeader: React.FC<{
+  title: React.ReactNode;
+  currentStep: number;
+  allowSkip: boolean;
+  onSkip: () => void;
+}> = ({ title, currentStep, allowSkip, onSkip }) => (
+        <Box
+          sx={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}
+        >
+          <Typography
+            id={`tutorial-title-${currentStep}`}
+            variant="h6"
+            fontWeight="bold"
+            sx={{ flex: 1 }}
+            data-testid="tutorial-step-title"
+          >
+            {title}
+          </Typography>
+          {allowSkip && (
+            <IconButton
+              size="small"
+              onClick={onSkip}
+              sx={{ ml: 1, mt: -1, mr: -1 }}
+              data-testid="tutorial-close-button"
+            >
+              <CloseIcon fontSize="small" />
+            </IconButton>
+          )}
+        </Box>
+);
+
+export const TutorialStepBody: React.FC<{
+  step: TutorialOverlayProps['steps'][number];
+  currentStep: number;
+  stepCount: number;
+  progress: number;
+  isLastStep: boolean;
+  allowSkip: boolean;
+  showProgress: boolean;
+  requiresActionBeforeNext?: boolean;
+  onNext: () => void;
+  onPrev: () => void;
+  onSkip: () => void;
+  onRestart: () => void;
+}> = ({
+  step,
+  currentStep,
+  stepCount,
+  progress: _progress,
+  isLastStep,
+  allowSkip,
+  showProgress,
+  requiresActionBeforeNext,
+  onNext,
+  onPrev,
+  onSkip,
+  onRestart }) => (
+      <Stack spacing={2}>
+        <TutorialStepHeader
+          title={step.title}
+          currentStep={currentStep}
+          allowSkip={allowSkip}
+          onSkip={onSkip}
+        />
+
+        <Typography
+          id={`tutorial-content-${currentStep}`}
+          variant="body2"
+          color="text.secondary"
+          data-testid="tutorial-step-content"
+        >
+          {step.content}
+        </Typography>
+
+        {showProgress && (
+          <Typography variant="caption" color="text.secondary" align="center">
+            {currentStep + 1} of {stepCount}
+          </Typography>
+        )}
+
+        {step.action && (
+          <Button
+            variant="contained"
+            size="small"
+            onClick={step.action.onClick}
+            sx={{
+              background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+              color: 'white' }}
+          >
+            {step.action.label}
+          </Button>
+        )}
+
+        <StepDots currentStep={currentStep} stepCount={stepCount} />
+
+        <TutorialStepNav
+          currentStep={currentStep}
+          stepCount={stepCount}
+          isLastStep={isLastStep}
+          allowSkip={allowSkip}
+          requiresActionBeforeNext={requiresActionBeforeNext}
+          onNext={onNext}
+          onPrev={onPrev}
+          onSkip={onSkip}
+          onRestart={onRestart}
+        />
+      </Stack>
+);
+
+// Main component

package/src/components/feedback/index.ts

@@ -1,3 +1,4 @@
+export * from './ConfirmAction';
 export * from './Dialog';
 export * from './Modal';
 export * from './Sonner';

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

@@ -0,0 +1,58 @@
+import type { AddressAutocompleteProps, AddressOptionValue } from './AddressAutocomplete.types';
+
+// Below this the field clears its options rather than querying Places.
+export const MIN_QUERY_LENGTH = 2;
+
+type DefaultedKeys =
+  | 'variant'
+  | 'label'
+  | 'placeholder'
+  | 'floating'
+  | 'error'
+  | 'disabled'
+  | 'required'
+  | 'fullWidth'
+  | 'defaultValue'
+  | 'getCurrentLocation';
+
+export type ResolvedAddressProps = AddressAutocompleteProps &
+  Required<Pick<AddressAutocompleteProps, DefaultedKeys>>;
+
+const ADDRESS_AUTOCOMPLETE_DEFAULTS: Pick<AddressAutocompleteProps, DefaultedKeys> = {
+  variant: 'outlined',
+  label: 'Address',
+  placeholder: 'Enter an address',
+  floating: false,
+  error: false,
+  disabled: false,
+  required: false,
+  fullWidth: true,
+  defaultValue: '',
+  getCurrentLocation: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: AddressAutocompleteProps): Partial<AddressAutocompleteProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<AddressAutocompleteProps>;
+
+// Applied as a merge rather than destructuring defaults, which would otherwise
+// put ten branches into the component's own complexity budget.
+export const resolveAddressProps = (props: AddressAutocompleteProps): ResolvedAddressProps =>
+  ({ ...ADDRESS_AUTOCOMPLETE_DEFAULTS, ...definedProps(props) }) as ResolvedAddressProps;
+
+export const addressOptionLabel = (option: AddressOptionValue): string => {
+  if (typeof option === 'string') return option;
+  return option.description || '';
+};
+
+// A string only ever equals the same string, so a mixed pair is never a match.
+export const isSameAddressOption = (
+  option: AddressOptionValue,
+  value: AddressOptionValue,
+): boolean => {
+  if (typeof option === 'string' || typeof value === 'string') return option === value;
+  return option.place_id === value.place_id;
+};

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

@@ -0,0 +1,93 @@
+import type React from 'react';
+import { useCallback, useState } from 'react';
+
+import type {
+  AddressAutocompleteProps,
+  AddressDetails,
+  AddressOptionValue,
+} from './AddressAutocomplete.types';
+import { useAddressPredictions } from './useAddressPredictions';
+import { useAddressSelection } from './useAddressSelection';
+import { useCurrentLocation } from './useCurrentLocation';
+import { useGoogleMapsAPI } from './useGoogleMapsAPI';
+
+export interface AddressAutocompleteState {
+  inputValue: string;
+  options: AddressOptionValue[];
+  loading: boolean;
+  apiError: string | null;
+  mapsError: string | null;
+  isLoaded: boolean;
+  handleInputChange: (event: React.SyntheticEvent, value: string) => void;
+  handleSelect: (event: React.SyntheticEvent, value: AddressOptionValue | null) => void;
+  handleGetCurrentLocation: () => void;
+}
+
+// Owns the state the three Places concerns share — the field's text, whether a
+// request is in flight, and the last error — then hands each concern the slice it
+// writes to.
+export const useAddressAutocomplete = ({
+  defaultValue,
+  googleMapsApiKey,
+  restrictions,
+  onSelect,
+}: {
+  defaultValue: string;
+  googleMapsApiKey: string;
+  restrictions: AddressAutocompleteProps['restrictions'];
+  onSelect: (address: AddressDetails) => void;
+}): AddressAutocompleteState => {
+  const [inputValue, setInputValue] = useState(defaultValue);
+  const [loading, setLoading] = useState(false);
+  const [apiError, setApiError] = useState<string | null>(null);
+
+  const { isLoaded, error: mapsError, services, useMockData } = useGoogleMapsAPI(googleMapsApiKey);
+
+  // A resolved address both notifies the caller and becomes the field's text.
+  const applyAddress = useCallback(
+    (address: AddressDetails) => {
+      onSelect(address);
+      setInputValue(address.formatted);
+    },
+    [onSelect],
+  );
+
+  const { options, handleInputChange } = useAddressPredictions({
+    isLoaded,
+    services,
+    restrictions,
+    useMockData,
+    setInputValue,
+    setLoading,
+    setApiError,
+  });
+
+  const handleSelect = useAddressSelection({
+    services,
+    useMockData,
+    setLoading,
+    setApiError,
+    onSelect,
+    applyAddress,
+  });
+
+  const handleGetCurrentLocation = useCurrentLocation({
+    services,
+    useMockData,
+    setLoading,
+    setApiError,
+    applyAddress,
+  });
+
+  return {
+    inputValue,
+    options,
+    loading,
+    apiError,
+    mapsError,
+    isLoaded,
+    handleInputChange,
+    handleSelect,
+    handleGetCurrentLocation,
+  };
+};

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

@@ -0,0 +1,57 @@
+import type { AddressDetails } from './AddressAutocomplete.types';
+
+// The shape shared by google.maps.GeocoderAddressComponent and the canned mock
+// components: enough to read a part out by type.
+interface AddressComponentLike {
+  long_name: string;
+  types: string[];
+}
+
+interface LatLngLike {
+  lat: () => number;
+  lng: () => number;
+}
+
+// Google reports address parts as an unordered list tagged by type, so every part
+// has to be looked up rather than indexed.
+const componentReader =
+  (components: readonly AddressComponentLike[]) =>
+  (type: string): string =>
+    components.find((component) => component.types.includes(type))?.long_name || '';
+
+// Places and Geocoder results both make the whole geometry chain optional.
+export const coordinatesOf = (geometry?: { location?: LatLngLike }): AddressDetails['coordinates'] => ({
+  lat: geometry?.location?.lat() || 0,
+  lng: geometry?.location?.lng() || 0,
+});
+
+// The four ways an address can arrive — a mock or live prediction, a mock or live
+// reverse geocode — all land here, so they agree on how a place becomes an
+// AddressDetails.
+export const toAddressDetails = ({
+  components,
+  formatted,
+  coordinates,
+}: {
+  components: readonly AddressComponentLike[];
+  formatted: string;
+  coordinates: AddressDetails['coordinates'];
+}): AddressDetails => {
+  const read = componentReader(components);
+  const street = `${read('street_number')} ${read('route')}`.trim();
+
+  return {
+    formatted,
+    // A street number on its own is not an address; fall back to the route name.
+    street: street || read('route'),
+    city: read('locality') || read('administrative_area_level_2'),
+    state: read('administrative_area_level_1'),
+    country: read('country'),
+    postalCode: read('postal_code'),
+    coordinates,
+  };
+};
+
+// freeSolo mode hands back whatever was typed, with no components to read.
+export const freeSoloAddress = (value: string): AddressDetails =>
+  toAddressDetails({ components: [], formatted: value, coordinates: { lat: 0, lng: 0 } });

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

@@ -1,4 +1,6 @@
-import { Business, Home, LocalShipping } from '@mui/icons-material';
+import Business from '@mui/icons-material/Business';
+import Home from '@mui/icons-material/Home';
+import LocalShipping from '@mui/icons-material/LocalShipping';
 import { Alert,Box, Paper, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
@@ -222,7 +224,7 @@ const WithValidationComponent = () => {
     } else {
       setError(false);
       setHelperText('');
-      // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console -- demo output for the Storybook docs page
       console.log(`Address confirmed: ${address.formatted}`);
     }
   };

package/src/components/form/AddressAutocomplete/AddressAutocomplete.test.stories.tsx

@@ -180,7 +180,7 @@ export const KeyboardNavigation: Story = {
     googleMapsApiKey: 'demo-key',
     onSelect: fn(),
   },
-  play: async ({ canvasElement }) => {
+  play: async ({ canvasElement, args }) => {
     const canvas = within(canvasElement);
 
     try {
@@ -188,9 +188,9 @@ export const KeyboardNavigation: Story = {
       const input = await canvas.findByPlaceholderText('Use Tab and Enter...');
       await expect(input).not.toBeDisabled();
 
-      // Focus the input
-      input.focus();
-      await expect(input).toHaveFocus();
+      // Focus the input the way a user would
+      await userEvent.click(input);
+      await waitFor(() => expect(input).toHaveFocus());
 
       // Type to trigger suggestions
       await userEvent.type(input, 'main');
@@ -215,8 +215,9 @@ export const KeyboardNavigation: Story = {
       // Try to select with Enter key
       await userEvent.keyboard('{Enter}');
 
-      // Wait a moment for any selection to process
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      // Selection resolves the place asynchronously, so wait on the callback
+      // rather than on the clock.
+      await waitFor(() => expect(args.onSelect).toHaveBeenCalled());
 
       // Test Escape key closes suggestions
       await userEvent.clear(input);
@@ -313,16 +314,17 @@ export const FocusManagementTest: Story = {
       const input = await canvas.findByPlaceholderText('Test focus behavior...');
       await expect(input).not.toBeDisabled();
 
-      // Test focus
-      input.focus();
-      await expect(input).toHaveFocus();
+      // Clicking focuses the field and tabbing away releases it. The DOM
+      // focus()/blur() calls this used to make asserted the browser's own API
+      // rather than the component's focus handling.
+      await userEvent.click(input);
+      await waitFor(() => expect(input).toHaveFocus());
 
-      // Test blur
-      input.blur();
-      await expect(input).not.toHaveFocus();
+      await userEvent.tab();
+      await waitFor(() => expect(input).not.toHaveFocus());
 
       // Focus again and type
-      input.focus();
+      await userEvent.click(input);
       await userEvent.type(input, 'Focus test');
       await expect(input).toHaveValue('Focus test');
 
@@ -462,7 +464,7 @@ export const VisualStatesTest: Story = {
 
       // Test focus state
       await userEvent.click(input);
-      await expect(input).toHaveFocus();
+      await waitFor(() => expect(input).toHaveFocus());
 
       // Test typing state
       await userEvent.type(input, 'Testing');
@@ -549,8 +551,10 @@ export const EdgeCasesTest: Story = {
 
       // Test empty input doesn't trigger suggestions
       await expect(input).toHaveValue('');
-      const initialSuggestion = body.queryByTestId('address-suggestion-0');
-      expect(initialSuggestion).not.toBeInTheDocument();
+      await waitFor(() => {
+        const initialSuggestion = body.queryByTestId('address-suggestion-0');
+        expect(initialSuggestion).not.toBeInTheDocument();
+      });
 
       // Test minimum characters requirement (less than 3 chars)
       await userEvent.type(input, 'ab');