feat(Map): add top-level autoExpandOnCarouselClick prop for better DX

Promotes autoExpandOnCarouselClick to a top-level Map prop for improved
discoverability and cleaner API.

Better Developer Experience:
Before (nested):
  <Map compactMapProps={{ autoExpandOnCarouselClick: true }} />

After (top-level):
  <Map autoExpandOnCarouselClick={true} />

Benefits:
- More discoverable (shows in autocomplete immediately)
- Simpler API (no nested objects for common features)
- Intuitive (primary interactions should be top-level)
- Consistent (matches other boolean flags like showPopup, loading, error)

Implementation:
- Added autoExpandOnCarouselClick to MapProps interface with JSDoc
- Default: false (backward compatible)
- Passes directly to CompactMap (not via compactMapProps)
- Excluded from compactMapProps type to prevent duplication

Documentation:
- Updated Maps story Advanced Features section
- Added code example showing top-level usage
- Clarified this is a Map component feature (requires orchestrator)

Author: JakeLin

packages/ui/src/components/Map/Map.tsx

@@ -14,10 +14,18 @@ export interface MapProps extends Omit<MapViewProps, 'className' | 'style'> {
    */
   onToggleFullscreen?: (isFullscreen: boolean) => void;
 
+  /**
+   * Auto-expand to fullscreen when user clicks a carousel card.
+   * When true, selecting a location from the carousel automatically triggers fullscreen
+   * mode with the Inspector panel open.
+   * @default false
+   */
+  autoExpandOnCarouselClick?: boolean;
+
   /**
    * Props passed to CompactMap when not in fullscreen
    */
-  compactMapProps?: Omit<CompactMapProps, keyof MapViewProps | 'onExpand'>;
+  compactMapProps?: Omit<CompactMapProps, keyof MapViewProps | 'onExpand' | 'autoExpandOnCarouselClick'>;
 
   /**
    * Props passed to FullscreenMap when in fullscreen
@@ -62,6 +70,7 @@ export const Map: React.FC<MapProps> = ({
   isInspectorOpen,
   scrollWheelZoom,
   showPopup,
+  autoExpandOnCarouselClick = false,
   loading = false,
   error = false,
   isFullscreen: controlledIsFullscreen,
@@ -129,7 +138,12 @@ export const Map: React.FC<MapProps> = ({
     <>
       {/* Compact Map */}
       {!isFullscreen && (
-        <CompactMap {...commonMapProps} onExpand={handleExpand} {...compactMapProps} />
+        <CompactMap
+          {...commonMapProps}
+          onExpand={handleExpand}
+          autoExpandOnCarouselClick={autoExpandOnCarouselClick}
+          {...compactMapProps}
+        />
       )}
 
       {/* Fullscreen Map */}

packages/ui/src/components/Map/Maps.stories.tsx

@@ -985,13 +985,29 @@ const handleMapToggle = (fullscreen: boolean) => {
               Auto-Expand on Carousel Click
             </h3>
             <p style={{ margin: '0 0 12px', fontSize: '14px', color: 'var(--ai-color-text-secondary)' }}>
-              Set <code>autoExpandOnCarouselClick={'{true}'}</code> on <code>CompactMap</code> to
-              automatically expand to fullscreen when users click a carousel card. This provides faster
-              access to detailed location information (one click instead of two).
+              Set <code>autoExpandOnCarouselClick={'{true}'}</code> on the <code>Map</code> component
+              (top-level prop) to automatically expand to fullscreen when users click a carousel card.
+              This provides faster access to detailed location information (one click instead of two).
             </p>
-            <div style={{ fontSize: '13px', color: 'var(--ai-color-text-secondary)' }}>
+            <div style={{ fontSize: '13px', color: 'var(--ai-color-text-secondary)', marginBottom: '12px' }}>
               <strong>Default:</strong> <code>false</code> (users must click expand button manually)
             </div>
+            <pre
+              style={{
+                margin: 0,
+                padding: '12px',
+                background: 'var(--ai-color-bg-tertiary)',
+                borderRadius: '6px',
+                fontSize: '12px',
+                lineHeight: '1.5',
+                fontFamily: 'Monaco, Menlo, monospace',
+              }}
+            >
+              <code>{`<Map
+  locations={locations}
+  autoExpandOnCarouselClick={true}
+/>`}</code>
+            </pre>
           </div>
         </div>
       </section>