@jmruthers/pace-core 0.5.189 → 0.5.191

package/src/components/AddressField/AddressField.tsx

@@ -12,8 +12,15 @@
  * - Debounced input with caching
  * - Keyboard navigation (Arrow keys, Enter, Escape)
  * - Accessible ARIA attributes
+ * - Semantic HTML (description list for suggestions)
  * - Loading and error states
  * - place_id storage for later retrieval
+ *
+ * @accessibility
+ * - Uses semantic HTML: `<dl>`, `<dt>`, `<dd>` for address suggestions
+ * - Proper ARIA attributes for combobox pattern
+ * - Keyboard navigation support
+ * - Screen reader friendly
  */
 
 import * as React from 'react';
@@ -74,8 +81,8 @@ const AddressField = React.forwardRef<HTMLInputElement, AddressFieldProps>(
     const [inputFocused, setInputFocused] = React.useState(false);
 
     const inputRef = React.useRef<HTMLInputElement>(null);
-    const suggestionsRef = React.useRef<HTMLUListElement>(null);
-    const containerRef = React.useRef<HTMLDivElement>(null);
+    const suggestionsRef = React.useRef<HTMLDListElement>(null);
+    const containerRef = React.useRef<HTMLFormElement>(null);
 
     // Use controlled or uncontrolled value
     const value = controlledValue !== undefined ? controlledValue : internalValue;
@@ -216,57 +223,61 @@ const AddressField = React.forwardRef<HTMLInputElement, AddressFieldProps>(
       }
     }, [isOpen]);
 
+    // Generate unique ID for suggestions list
+    const suggestionsId = React.useId();
+
     // Scroll selected item into view
+    // Uses getElementById instead of querySelector to handle React.useId() generated IDs
+    // which may contain colons (e.g., ':r15:') that are invalid in CSS selectors
     React.useEffect(() => {
-      if (selectedIndex >= 0 && suggestionsRef.current) {
-        const selectedItem = suggestionsRef.current.children[selectedIndex] as HTMLElement;
+      if (selectedIndex >= 0) {
+        const selectedItem = document.getElementById(
+          `${suggestionsId}-item-${selectedIndex}`
+        ) as HTMLElement;
         if (selectedItem && typeof selectedItem.scrollIntoView === 'function') {
           selectedItem.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
         }
       }
-    }, [selectedIndex]);
+    }, [selectedIndex, suggestionsId]);
 
     // 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>
+      <form ref={containerRef} className={cn('relative w-full', className)}>
+        <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 && (
+          <p className="absolute right-3 top-1/2 -translate-y-1/2 pointer-events-none">
+            <LoadingSpinner size="sm" />
+          </p>
+        )}
 
         {isOpen && suggestions.length > 0 && (
-          <ul
+          <dl
             ref={suggestionsRef}
             id={suggestionsId}
             role="listbox"
@@ -278,32 +289,32 @@ const AddressField = React.forwardRef<HTMLInputElement, AddressFieldProps>(
             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">
+              <React.Fragment key={suggestion.place_id}>
+                <dt
+                  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',
+                    'font-medium text-main-900'
+                  )}
+                  onClick={() => handleSelectAddress(suggestion.place_id)}
+                  onMouseEnter={() => setSelectedIndex(index)}
+                  data-testid={`address-suggestion-${index}`}
+                >
                   {suggestion.structured_formatting?.main_text || suggestion.description}
-                </div>
+                </dt>
                 {suggestion.structured_formatting?.secondary_text && (
-                  <div className="text-xs text-main-600 mt-0.5">
+                  <dd className="px-3 pb-2 text-xs text-main-600 mt-0.5">
                     {suggestion.structured_formatting.secondary_text}
-                  </div>
+                  </dd>
                 )}
-              </li>
+              </React.Fragment>
             ))}
-          </ul>
+          </dl>
         )}
 
         {autocompleteError && (
@@ -311,7 +322,7 @@ const AddressField = React.forwardRef<HTMLInputElement, AddressFieldProps>(
             {autocompleteError.message}
           </p>
         )}
-      </div>
+      </form>
     );
   }
 );

package/src/components/AddressField/README.md

@@ -154,7 +154,7 @@ if (address) {
 
 ## ParsedAddress Type
 
-The `onChange` callback receives a `ParsedAddress` object matching the `pace_address` table structure:
+The `onChange` callback receives a `ParsedAddress` object matching the `core_address` table structure:
 
 ```typescript
 interface ParsedAddress {
@@ -202,7 +202,7 @@ The component uses intelligent caching to reduce API costs:
 
 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
+1. **Storing in Database**: Save `place_id` in your `core_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
@@ -215,7 +215,7 @@ The `place_id` is a stable identifier for a location that doesn't change. It's c
   apiKey={apiKey}
   onChange={async (address) => {
     // Store in database
-    await supabase.from('pace_address').insert({
+    await supabase.from('core_address').insert({
       place_id: address.place_id, // Store this!
       full_address: address.full_address,
       lat: address.lat,
@@ -242,6 +242,7 @@ const address = await getAddressByPlaceId(storedPlaceId, apiKey);
 
 The component follows WCAG 2.1 guidelines:
 
+- **Semantic HTML**: Uses description list (`<dl>`, `<dt>`, `<dd>`) for address suggestions, providing proper semantic meaning
 - **ARIA Attributes**: Proper `role`, `aria-expanded`, `aria-autocomplete`, `aria-controls`
 - **Keyboard Navigation**: Full keyboard support
 - **Screen Readers**: Proper announcements and labels
@@ -256,16 +257,16 @@ The component handles various error scenarios:
 - **Rate Limiting**: Informs user about quota limits
 - **Invalid Requests**: Validates input and displays errors
 
-## Integration with pace_address Table
+## Integration with core_address Table
 
-The `ParsedAddress` type matches the `pace_address` table structure, making it easy to store results:
+The `ParsedAddress` type matches the `core_address` table structure, making it easy to store results:
 
 ```tsx
 <AddressField
   apiKey={apiKey}
   onChange={async (address) => {
     const { data, error } = await supabase
-      .from('pace_address')
+      .from('core_address')
       .insert({
         place_id: address.place_id,
         full_address: address.full_address,

package/src/components/Alert/Alert.test.tsx

@@ -11,6 +11,19 @@ import { renderWithProviders } from '../../__tests__/helpers/test-utils';
 
 describe('Alert Component', () => {
     describe('Rendering', () => {
+    it('renders as semantic aside element', () => {
+      renderWithProviders(
+        <Alert>
+          <AlertTitle>Test Title</AlertTitle>
+          <AlertDescription>Test description</AlertDescription>
+        </Alert>
+      );
+      
+      const alert = screen.getByRole('alert');
+      expect(alert.tagName).toBe('ASIDE');
+      expect(alert).toBeInTheDocument();
+    });
+
     it('renders with default variant', () => {
       renderWithProviders(
         <Alert>
@@ -21,6 +34,7 @@ describe('Alert Component', () => {
       
       const alert = screen.getByRole('alert');
       expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(alert).toHaveClass('relative', 'w-full', 'rounded-lg', 'border', 'p-4');
     });
 
@@ -34,6 +48,7 @@ describe('Alert Component', () => {
       
       const alert = screen.getByRole('alert');
       expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(alert).toHaveClass('border-destructive', 'text-destructive');
     });
 
@@ -58,6 +73,7 @@ describe('Alert Component', () => {
       );
       
       const alert = screen.getByRole('alert');
+      expect(alert.tagName).toBe('ASIDE');
       expect(alert).toHaveClass('custom-alert-class');
     });
 
@@ -72,7 +88,7 @@ describe('Alert Component', () => {
     });
 
     it('forwards ref correctly', () => {
-      const ref = React.createRef<HTMLDivElement>();
+      const ref = React.createRef<HTMLElement>();
       
       renderWithProviders(
         <Alert ref={ref}>
@@ -80,7 +96,8 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(ref.current).toBeInstanceOf(HTMLDivElement);
+      expect(ref.current).toBeInstanceOf(HTMLElement);
+      expect(ref.current?.tagName).toBe('ASIDE');
       expect(ref.current).toHaveAttribute('role', 'alert');
     });
   });
@@ -258,6 +275,7 @@ describe('Alert Component', () => {
       
       const alert = screen.getByRole('alert');
       expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
     });
 
     it('does not have role="alert" for inline variant', () => {
@@ -283,6 +301,7 @@ describe('Alert Component', () => {
       
       const alert = screen.getByRole('alert');
       expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       
       // Screen readers will announce the content within the alert
       expect(screen.getByText('Important Notice')).toBeInTheDocument();
@@ -297,9 +316,11 @@ describe('Alert Component', () => {
         </Alert>
       );
       
+      const alert = screen.getByRole('alert');
       const title = screen.getByRole('heading', { level: 5 });
       const description = screen.getByText('Semantic description with proper heading structure');
       
+      expect(alert.tagName).toBe('ASIDE');
       expect(title).toBeInTheDocument();
       expect(description.tagName).toBe('P');
     });
@@ -320,7 +341,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByText('⚠️')).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Dismiss' })).toBeInTheDocument();
     });
@@ -334,7 +357,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByText('First description')).toBeInTheDocument();
       expect(screen.getByText('Second description')).toBeInTheDocument();
     });
@@ -346,7 +371,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByText('Description without title')).toBeInTheDocument();
     });
 
@@ -357,7 +384,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByRole('heading', { level: 5 })).toHaveTextContent('Title without description');
     });
   });
@@ -368,6 +397,7 @@ describe('Alert Component', () => {
       
       const alert = screen.getByRole('alert');
       expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(alert).toBeEmptyDOMElement();
     });
 
@@ -395,7 +425,9 @@ describe('Alert Component', () => {
       );
       
       // Should fallback to default behavior
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
     });
 
     it('handles rapid variant changes', () => {
@@ -424,7 +456,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
     });
   });
 
@@ -441,7 +475,9 @@ describe('Alert Component', () => {
         </form>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByRole('textbox')).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Submit' })).toBeInTheDocument();
     });
@@ -462,6 +498,8 @@ describe('Alert Component', () => {
       
       const alerts = screen.getAllByRole('alert');
       expect(alerts).toHaveLength(2);
+      expect(alerts[0].tagName).toBe('ASIDE');
+      expect(alerts[1].tagName).toBe('ASIDE');
       expect(alerts[0]).toHaveClass('bg-background', 'text-foreground');
       expect(alerts[1]).toHaveClass('border-destructive', 'text-destructive');
     });
@@ -482,7 +520,9 @@ describe('Alert Component', () => {
         </Alert>
       );
       
-      expect(screen.getByRole('alert')).toBeInTheDocument();
+      const alert = screen.getByRole('alert');
+      expect(alert).toBeInTheDocument();
+      expect(alert.tagName).toBe('ASIDE');
       expect(screen.getByText('Complex Alert')).toBeInTheDocument();
       expect(screen.getByText('This is a complex description with')).toBeInTheDocument();
       expect(screen.getByText('Multiple elements')).toBeInTheDocument();

package/src/components/Alert/Alert.tsx

@@ -10,6 +10,7 @@
  * Features:
  * - Multiple visual variants (default, destructive, inline)
  * - Title and description support
+ * - Semantic HTML: renders as `<aside>` element
  * - ARIA role="alert" for accessibility
  * - Keyboard and screen reader accessible
  * - Composable with icons and actions
@@ -40,6 +41,7 @@
  * ```
  *
  * @accessibility
+ * - Uses semantic HTML: `<aside>` element for better semantic meaning
  * - Uses role="alert" for screen reader announcement
  * - Title and description are semantically structured
  * - Supports keyboard navigation and focus
@@ -65,8 +67,8 @@ const getAlertClasses = (variant: "default" | "destructive" | "inline" = "defaul
 };
 
 const Alert = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement> & { variant?: "default" | "destructive" | "inline" }
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement> & { variant?: "default" | "destructive" | "inline" }
 >(({ className, variant = "default", ...props }, ref) => {
   const contextValue = React.useMemo(() => ({ variant }), [variant])
   
@@ -80,7 +82,7 @@ const Alert = React.forwardRef<
   
   return (
     <AlertContext.Provider value={contextValue}>
-      <div
+      <aside
         ref={ref}
         className={cn(getAlertClasses(variant), className)}
         role="alert"