feat: Add MapInspector enhancements with PhotoCarousel and ExpandableText

Major enhancements to Map components for rich property detail views.

NEW COMPONENTS:

1. Overlay Component (Shared)
   - Generic overlay for images/media with configurable background, height, align
   - Supports presets: 'dark', 'light', 'transparent' + custom colors
   - Reusable across SummaryCard, PhotoCarousel, and other components

2. PhotoCarousel Component
   - Embla-based photo carousel with swipe support
   - Navigation dots and prev/next arrows
   - topOverlay support for branding (PhotoCarousel.Overlay helper)
   - Configurable aspect ratio (5:4 default for properties)
   - Loading/error/empty states

3. ExpandableText Component
   - Line-clamp truncation with configurable maxLines
   - "View more" / "View less" toggle (inline with text)
   - Auto-detects if truncation needed
   - Controlled/uncontrolled modes

ENHANCEMENTS:

4. MapPlaceCard (renamed from LocationCard)
   - Added variant prop ('carousel' | 'list')
   - List variant: borderless, rounded on hover/select, smooth transitions
   - Better naming (MapPlaceCard fits Map component family)

5. MapSidebar Refactoring
   - Now uses MapPlaceCard component (removed duplicate code)
   - Borderless cards with background-only selection
   - Removed dividers between cards
   - ~100 lines of duplicate CSS removed

6. MapInspector Enhancements
   - PhotoCarousel integration (shows all property images vs single)
   - ExpandableText for descriptions (collapsible)
   - Headline support (auction/EOI info) using H3/Title 3 Emph
   - bottomAction support (link button at bottom, no divider)
   - Updated LocationData type: images, topOverlay, headline, bottomAction

7. Button Component
   - Added 'link' variant (link-style button with underline)
   - Useful for secondary actions

8. SummaryCard Refactoring
   - Now uses shared Overlay component (DRY)
   - Backward compatible (SummaryCard.Overlay still works)

All components follow SDK design patterns, use generic naming, and are
fully reusable across different use cases.

Author: JakeLin

packages/ui/src/components/Button/Button.module.css

@@ -135,6 +135,25 @@
   background-color: var(--ai-color-bg-secondary);
 }
 
+/* ========== LINK VARIANT ========== */
+.buttonLink {
+  background-color: transparent;
+  color: var(--ai-color-brand-primary);
+  border: none;
+  padding: 0;
+  text-decoration: underline;
+  font-weight: var(--ai-font-weight-medium);
+}
+
+.buttonLink:not(:disabled):hover {
+  opacity: 0.8;
+  background-color: transparent;
+}
+
+.buttonLink:not(:disabled):active {
+  opacity: 0.6;
+}
+
 /* ========== ICON-ONLY BUTTONS ========== */
 .buttonIconOnly {
   min-width: 44px;

packages/ui/src/components/Button/Button.module.css.d.ts

@@ -4,6 +4,7 @@ declare const styles: {
   readonly buttonSecondary: string;
   readonly buttonTertiary: string;
   readonly buttonGhost: string;
+  readonly buttonLink: string;
   readonly buttonIconOnly: string;
   readonly label: string;
   readonly leftIcon: string;

packages/ui/src/components/Button/Button.tsx

@@ -6,7 +6,7 @@ import type { IconName } from '../../tokens/icons';
 import type { ColorVariant } from '../../tokens/colors';
 import styles from './Button.module.css';
 
-export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'ghost';
+export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'link';
 
 export interface ButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'color'> {
   /**
@@ -117,6 +117,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>((props, r
     secondary: styles.buttonSecondary,
     tertiary: styles.buttonTertiary,
     ghost: styles.buttonGhost,
+    link: styles.buttonLink,
   }[variant];
 
   const colorClass = {

packages/ui/src/components/Card/SummaryCard.module.css

@@ -29,7 +29,7 @@
 }
 
 /* Flat variant - topOverlay uses Card's border-radius */
-.summaryCard[data-variant='flat'] .topOverlay {
+.summaryCard[data-variant='flat'] .overlay {
   border-top-left-radius: var(--ai-radius-xl);
   border-top-right-radius: var(--ai-radius-xl);
 }
@@ -444,7 +444,7 @@
 }
 
 /* Top Overlay - Positioned inside imageWrapper, sibling to imageSection */
-.topOverlay {
+.overlay {
   position: absolute;
   top: 0;
   left: 0;

packages/ui/src/components/Card/SummaryCard.module.css.d.ts

@@ -29,7 +29,7 @@ declare const styles: {
   readonly emptyState: string;
   readonly emptyTitle: string;
   readonly emptyMessage: string;
-  readonly topOverlay: string;
+  readonly overlay: string;
 };
 
 export default styles;

packages/ui/src/components/Card/SummaryCard.tsx

@@ -8,6 +8,7 @@ import { Icon } from '../Icon';
 import type { IconName } from '../../tokens/icons';
 import { Skeleton } from '../Skeleton';
 import { Alert } from '../Alert';
+import { Overlay, type OverlayProps } from '../Overlay';
 import styles from './SummaryCard.module.css';
 
 export interface SummaryCardImage {
@@ -278,103 +279,9 @@ const normalizeImage = (image: string | SummaryCardImage): SummaryCardImage => {
 
 /**
  * Props for SummaryCard.Overlay helper component
+ * @deprecated Use OverlayProps from shared Overlay component
  */
-export interface SummaryCardOverlayProps {
-  /**
-   * Background style for the overlay
-   * - "dark": Semi-transparent dark background (rgba(0, 0, 0, 0.6))
-   * - "light": Semi-transparent light background (rgba(255, 255, 255, 0.8))
-   * - "transparent": No background
-   * - Custom string: Any valid CSS color value
-   * @default "dark"
-   */
-  background?: 'dark' | 'light' | 'transparent' | string;
-
-  /**
-   * Height of the overlay
-   * @default 40
-   */
-  height?: number | string;
-
-  /**
-   * Horizontal alignment of content
-   * @default "center"
-   */
-  align?: 'left' | 'center' | 'right';
-
-  /**
-   * Padding inside the overlay
-   * @default 8
-   */
-  padding?: number;
-
-  /**
-   * Content to render inside the overlay
-   */
-  children: React.ReactNode;
-
-  /**
-   * Additional CSS class name
-   */
-  className?: string;
-}
-
-/**
- * Helper component for creating consistently styled overlays on SummaryCard images
- *
- * @example
- * ```tsx
- * <SummaryCard
- *   images="property.jpg"
- *   topOverlay={
- *     <SummaryCard.Overlay background="dark" height={40} align="center">
- *       <img src="logo.png" alt="Logo" style={{ height: 24 }} />
- *     </SummaryCard.Overlay>
- *   }
- * />
- * ```
- */
-const SummaryCardOverlay = React.forwardRef<HTMLDivElement, SummaryCardOverlayProps>(
-  (
-    { background = 'dark', height = 40, align = 'center', padding = 8, children, className },
-    ref
-  ) => {
-    // Map background presets to CSS values
-    const backgroundMap: Record<string, string> = {
-      dark: 'rgba(0, 0, 0, 0.6)',
-      light: 'rgba(255, 255, 255, 0.8)',
-      transparent: 'transparent',
-    };
-
-    const backgroundValue = backgroundMap[background] || background;
-
-    // Map align to justify-content values
-    const justifyContentMap: Record<string, string> = {
-      left: 'flex-start',
-      center: 'center',
-      right: 'flex-end',
-    };
-
-    const justifyContent = justifyContentMap[align] || 'center';
-
-    return (
-      <div
-        ref={ref}
-        className={cn(styles.topOverlay, className)}
-        style={{
-          background: backgroundValue,
-          height: typeof height === 'number' ? `${height}px` : height,
-          justifyContent,
-          padding: `${padding}px`,
-        }}
-      >
-        {children}
-      </div>
-    );
-  }
-);
-
-SummaryCardOverlay.displayName = 'SummaryCard.Overlay';
+export type SummaryCardOverlayProps = OverlayProps;
 
 /**
  * SummaryCard component for displaying entity information with images.
@@ -876,8 +783,8 @@ SummaryCardComponent.displayName = 'SummaryCard';
 
 // Create typed SummaryCard with Overlay subcomponent
 export const SummaryCard = SummaryCardComponent as typeof SummaryCardComponent & {
-  Overlay: typeof SummaryCardOverlay;
+  Overlay: typeof Overlay;
 };
 
-// Attach Overlay component to SummaryCard
-SummaryCard.Overlay = SummaryCardOverlay;
+// Attach shared Overlay component to SummaryCard
+SummaryCard.Overlay = Overlay;

packages/ui/src/components/ExpandableText/ExpandableText.module.css

@@ -0,0 +1,46 @@
+/* ExpandableText Container */
+.expandableText {
+  position: relative;
+}
+
+/* Text Content */
+.text {
+  margin: 0;
+  font-size: var(--ai-font-size-body);
+  line-height: var(--ai-line-height-body);
+  color: var(--ai-color-text-primary);
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+/* Clamped State - Use line-clamp */
+.clamped {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Toggle Button */
+.toggleButton {
+  display: inline;
+  margin-left: var(--ai-spacing-1);
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--ai-color-text-primary);
+  font-size: var(--ai-font-size-body-small);
+  font-weight: var(--ai-font-weight-medium);
+  cursor: pointer;
+  text-decoration: underline;
+  transition: opacity 0.2s ease;
+  white-space: nowrap;
+}
+
+.toggleButton:hover {
+  opacity: 0.8;
+}
+
+.toggleButton:active {
+  opacity: 0.6;
+}

packages/ui/src/components/ExpandableText/ExpandableText.module.css.d.ts

@@ -0,0 +1,8 @@
+declare const styles: {
+  readonly expandableText: string;
+  readonly text: string;
+  readonly clamped: string;
+  readonly toggleButton: string;
+};
+
+export default styles;

packages/ui/src/components/ExpandableText/ExpandableText.tsx

@@ -0,0 +1,119 @@
+import React, { useState, useRef, useEffect } from 'react';
+import { cn } from '../../utils/cn';
+import styles from './ExpandableText.module.css';
+
+export interface ExpandableTextProps {
+  /**
+   * Text content to display
+   */
+  text: string;
+
+  /**
+   * Maximum number of lines to show when collapsed
+   * @default 3
+   */
+  maxLines?: number;
+
+  /**
+   * Label for expand button
+   * @default 'View more'
+   */
+  expandLabel?: string;
+
+  /**
+   * Label for collapse button
+   * @default 'View less'
+   */
+  collapseLabel?: string;
+
+  /**
+   * Additional CSS class name
+   */
+  className?: string;
+
+  /**
+   * Force expanded state (controlled component)
+   */
+  expanded?: boolean;
+
+  /**
+   * Callback when expanded state changes
+   */
+  onExpandChange?: (expanded: boolean) => void;
+}
+
+/**
+ * ExpandableText - Text component with line-clamp and expand/collapse functionality.
+ * Automatically detects if text needs truncation.
+ *
+ * @example
+ * ```tsx
+ * <ExpandableText
+ *   text="Long description text..."
+ *   maxLines={3}
+ *   expandLabel="Read more"
+ *   collapseLabel="Read less"
+ * />
+ * ```
+ */
+export const ExpandableText: React.FC<ExpandableTextProps> = ({
+  text,
+  maxLines = 3,
+  expandLabel = 'View more',
+  collapseLabel = 'View less',
+  className,
+  expanded: controlledExpanded,
+  onExpandChange,
+}) => {
+  const [internalExpanded, setInternalExpanded] = useState(false);
+  const [needsTruncation, setNeedsTruncation] = useState(false);
+  const textRef = useRef<HTMLParagraphElement>(null);
+
+  const isControlled = controlledExpanded !== undefined;
+  const expanded = isControlled ? controlledExpanded : internalExpanded;
+
+  // Detect if text needs truncation
+  useEffect(() => {
+    const element = textRef.current;
+    if (!element) return;
+
+    // Compare scroll height with client height to determine if text is truncated
+    const isOverflowing = element.scrollHeight > element.clientHeight;
+    setNeedsTruncation(isOverflowing);
+  }, [text, maxLines]);
+
+  const handleToggle = () => {
+    if (isControlled) {
+      onExpandChange?.(!expanded);
+    } else {
+      setInternalExpanded(!expanded);
+      onExpandChange?.(!expanded);
+    }
+  };
+
+  return (
+    <div className={cn(styles.expandableText, className)}>
+      <p
+        ref={textRef}
+        className={cn(styles.text, !expanded && styles.clamped)}
+        style={{
+          WebkitLineClamp: expanded ? 'unset' : maxLines,
+        }}
+      >
+        {text}
+        {needsTruncation && (
+          <button
+            className={styles.toggleButton}
+            onClick={handleToggle}
+            type="button"
+            aria-expanded={expanded}
+          >
+            {expanded ? collapseLabel : expandLabel}
+          </button>
+        )}
+      </p>
+    </div>
+  );
+};
+
+ExpandableText.displayName = 'ExpandableText';

packages/ui/src/components/ExpandableText/index.ts

@@ -0,0 +1,2 @@
+export { ExpandableText } from './ExpandableText';
+export type { ExpandableTextProps } from './ExpandableText';