Component Reference

import { MapEngine } from '@/core';

<MapEngine
  incidents={incidents}
  selectedIncident={selectedIncident}
  onIncidentSelect={setSelectedIncident}
  currentDate={currentDate}
  sidebarOpen={isSidebarOpen}
  rightSidebarOpen={isRightSidebarOpen}
  renderMarker={(props) => <CustomMarker {...props} />}
  renderPopup={(props) => <CustomPopup {...props} />}
  renderCluster={(props) => <CustomCluster {...props} />}
/>

import { DataProvider } from '@/core';

<DataProvider>
  <YourApp />
</DataProvider>

import { ThemeProvider } from '@/core';

<ThemeProvider>
  <YourApp />
</ThemeProvider>

import { FilterSidebar } from '@/controls/filters';

<FilterSidebar 
  isOpen={isSidebarOpen}
  filters={filters}
  onFilterChange={updateFilter}
  incidentCount={filteredIncidents.length}
  countries={filterOptions.countries}
  // ... additional filter option props
/>

import { TimelineControl } from '@/controls';

<TimelineControl />

import { IncidentFeed } from '@/controls';

<IncidentFeed 
  incidents={filteredIncidents}
  selectedIncident={selectedIncident}
  onIncidentSelect={setSelectedIncident}
  renderFeedItem={(props) => <CustomFeedItem {...props} />}
/>

import { StatsPanel } from '@/controls';

<StatsPanel 
  incidents={filteredIncidents} 
  totalIncidents={incidents.length} 
/>

import { ThemeToggle } from '@/controls';

<ThemeToggle variant="icon-only" />
<ThemeToggle variant="button" size="sm" showLabel />
<ThemeToggle variant="dropdown" showLabel />

import { SourceToggle } from '@/controls';

<SourceToggle
  sources={dataSources}
  enabledIds={enabledSourceIds}
  onToggle={(sourceId) => toggleSource(sourceId)}
  incidentCounts={countsBySource}
/>

import { DefaultMarker, PulseMarker } from '@/examples/renderers';

// Simple colored marker
<DefaultMarker incident={incident} isSelected={false} onClick={() => {}} />

// Animated pulsing marker
<PulseMarker incident={incident} isSelected={false} onClick={() => {}} />

import { CompactPopup, StandardPopup, FullViewModal } from '@/examples/renderers';

// Minimal popup
<CompactPopup incident={incident} onClose={() => {}} />

// Full details popup
<StandardPopup incident={incident} onClose={() => {}} />

// Modal with all sections
<FullViewModal incident={incident} onClose={() => {}} />

import { DefaultFeedItem, CompactFeedItem, MediaPreviewFeedItem } from '@/examples/renderers';

// Standard feed item
<DefaultFeedItem incident={incident} isSelected={false} onClick={() => {}} />

// Minimal height
<CompactFeedItem incident={incident} isSelected={false} onClick={() => {}} />

// With thumbnail
<MediaPreviewFeedItem incident={incident} isSelected={false} onClick={() => {}} />

import { DefaultCluster } from '@/examples/renderers';

// React clustering mode only
<DefaultCluster cluster={cluster} incidents={incidents} onClick={() => {}} />

import { useData } from '@/core';

function MyComponent() {
  const {
    // Data
    incidents,          // All loaded incidents
    filteredIncidents,  // After filters applied
    
    // Selection
    selectedIncident,
    setSelectedIncident,
    
    // Filters
    filters,
    updateFilter,
    resetFilters,       // Reset all filters to defaults
    
    // Data sources
    dataSources,
    enabledSourceIds,   // Array of enabled source IDs
    toggleSource,
    
    // Loading state
    isLoading,
    error,
    
    // Actions
    refresh,            // Refresh data from all sources
  } = useData();
}

import { useTheme } from '@/core';

function MyComponent() {
  const {
    theme,          // Current setting: 'light' | 'dark' | 'system'
    resolvedTheme,  // Actual theme: 'light' | 'dark'
    setTheme,       // Set theme
    toggleTheme,    // Toggle between light/dark
  } = useTheme();
}

import { useMapUIState } from '@/hooks';

const {
  // Sidebar state
  sidebarOpen,
  setSidebarOpen,
  toggleSidebar,      // (hasPopupOpen?: boolean) => void
  rightSidebarOpen,
  setRightSidebarOpen,
  toggleRightSidebar, // (hasPopupOpen?: boolean) => void

  // Timeline state
  timelineOpen,
  setTimelineOpen,
  toggleTimeline,
  isPlaying,
  setIsPlaying,
  togglePlayback,

  // Full view modal
  fullViewIncident,
  setFullViewIncident,
  openFullView,
  closeFullView,

  // Map refit triggers
  fitBoundsKey,
  triggerFitBounds,
  recenterPopupKey,
  triggerRecenterPopup,
} = useMapUIState();

import { useRendererConfig } from '@/hooks';

const {
  markerStyle,
  popupStyle,
  feedStyle,
} = useRendererConfig();

interface MarkerRendererProps {
  /** Incidents at this location (may be multiple stacked) */
  incidents: IncidentDisplay[];
  /** Whether any incident at this location is selected */
  isSelected: boolean;
  /** Whether any incident is newly appeared (for animation) */
  isNew: boolean;
  /** Callback when marker is clicked */
  onClick: () => void;
  /** Computed marker size based on incident count and sensitivity */
  size: number;
  /** Primary color for this marker (highest sensitivity color) */
  color: string;
}

interface PopupRendererProps {
  /** The incident being displayed */
  incident: IncidentDisplay;
  /** Close the popup */
  onClose: () => void;
  /** Data source this incident belongs to */
  dataSource?: DataSourceConfig;
  /** Open full view modal for this incident (optional) */
  onViewDetails?: (incident: IncidentDisplay) => void;
}

interface FeedItemRendererProps {
  /** The incident being displayed */
  incident: IncidentDisplay;
  /** Whether this item is currently selected */
  isSelected: boolean;
  /** Whether this item is highlighted (e.g., newly appeared) */
  isHighlighted: boolean;
  /** Callback when item is clicked */
  onClick: () => void;
  /** Data source this incident belongs to */
  dataSource?: DataSourceConfig;
}

interface ClusterRendererProps {
  /** Number of incidents in this cluster */
  pointCount: number;
  /** Alias for pointCount (for convenience) */
  count: number;
  /** Total number of points that could be in cluster */
  pointCountAbbreviated: string;
  /** Incidents in this cluster (if available) */
  incidents?: IncidentDisplay[];
  /** Cluster coordinates [longitude, latitude] */
  coordinates: [number, number];
  /** Callback to expand/zoom into cluster */
  onExpand: () => void;
  /** Callback when cluster is clicked */
  onClick: () => void;
  /** Computed cluster size */
  size: number;
  /** Primary color for this cluster (highest sensitivity color) */
  color: string;
}

import { InfoPopover } from '@/ui';

<InfoPopover 
  content="This is helpful information."
  position="bottom"
  maxWidth={280}
>
  <span>Hover me</span>
</InfoPopover>

// With JSX content
<InfoPopover 
  content={
    <div>
      <p className="font-medium">Title</p>
      <p className="text-muted-foreground text-xs">Description text.</p>
    </div>
  }
  showIcon
>
  <span>More info</span>
</InfoPopover>

import { DemoBadge } from '@/ui';

// Default disclaimer
<DemoBadge />

// Custom disclaimer text
<DemoBadge disclaimer="Sample data for testing purposes only." />

// With custom styling
<DemoBadge className="text-sm" />

import { Loader, InlineLoader, LoaderOverlay } from '@/ui';

// Basic loader with variant
<Loader variant="orbit" size="lg" />
<Loader variant="dots" size="sm" />
<Loader variant="spinner" size="md" />

// Inline loader for buttons/text
<InlineLoader size="sm" />

// Overlay loader for cards/sections
<LoaderOverlay visible={isLoading} message="Loading..." variant="orbit" />

import { FullPageLoading } from '@/ui';

<FullPageLoading 
  message="Initializing..."
  variant="orbit"
  size="lg"
/>