API Reference

Sightline provides a comprehensive TypeScript API for building incident mapping applications. This page provides an overview of the main modules and how to generate detailed API documentation.

Generating API Documentation

You can generate full API documentation locally using TypeDoc:

pnpm docs:api

This generates markdown documentation in the docs-api/ directory, organized by module:

core/ - Core types, contexts, and configuration
adapters/ - Data adapters for different sources
controls/ - UI control components
ui/ - Base UI components
hooks/ - React hooks
lib/ - Utility functions

Module Overview

Core (`@/core`)

The core module provides the foundation of Sightline:

import {
  // Configuration
  ConfigProvider,
  useConfig,
  useBranding,
  useDataSources,
  useLoaderConfig,

  // Data management
  DataProvider,
  useData,
  useIncidents,
  useFilters,
  useSelection,

  // Theme
  ThemeProvider,
  useTheme,
  useResolvedTheme,

  // Map engine
  MapEngine,

  // Types
  type Incident,
  type IncidentDisplay,
  type IncidentFilters,
  type MapConfig,
  type LoaderConfig,
} from '@/core';

Adapters (`@/adapters`)

Data adapters provide a uniform interface for different data sources:

import {
  createAdapter,
  StaticAdapter,
  SupabaseAdapter,
  ApiAdapter,
  type DataAdapter,
  type FilterOptions,
} from '@/adapters';

// Create an adapter based on config
const adapter = createAdapter(dataSourceConfig);
const incidents = await adapter.getIncidents(filters);

Controls (`@/controls`)

Pre-built UI controls for common functionality:

import {
  FilterSidebar,
  IncidentFeed,
  TimelineControl,
  ThemeToggle,
  SourceToggle,
  StatsPanel,
} from '@/controls';

Hooks (`@/hooks`)

React hooks for state management and configuration:

import {
  useMapUIState,
  useRendererConfig,
  type FeedStyle,
  type MapUIState,
} from '@/hooks';

UI (`@/ui`)

Base UI components for building custom interfaces:

import {
  // Layout components
  Dropdown,
  DropdownItem,
  DropdownTrigger,
  AccordionSection,
  ToggleButton,
  ToggleButtonGroup,
  ErrorBoundary,
  
  // Loading states
  Loader,
  InlineLoader,
  LoaderOverlay,
  FullPageState,
  FullPageLoading,
  
  // Info display
  InfoPopover,
  DemoBadge,
  
  // Types
  type LoaderVariant,
  type LoaderSize,
  type InfoPopoverProps,
  type DemoBadgeProps,
} from '@/ui';

Utilities (`@/lib`)

Helper functions and utilities:

import {
  // Filtering
  filterIncidents,
  createFilterSets,
  hasActiveFilters,

  // Formatting
  formatLocation,
  formatDuration,
  pluralize,

  // Incident utilities
  getSensitivityDisplay,
  getVisualMedia,

  // Styling
  cn,
} from '@/lib';

Key Types

Incident

The core data type representing an incident:

interface Incident {
  id: string;
  status: PublicationStatus;
  createdAt: string;
  updatedAt: string;

  // Required nested objects
  temporal: TemporalData;
  location: LocationData;

  // Optional nested objects
  classification?: ClassificationData;
  objectCharacteristics?: ObjectCharacteristics;
  witnesses?: WitnessData;
  sensorEvidence?: SensorEvidenceData;
  investigation?: InvestigationData;
  responseImpact?: ResponseImpactData;
  // ... more
}

IncidentFilters

Filter criteria for querying incidents:

interface IncidentFilters {
  // Location
  countries?: string[];
  siteTypes?: SiteType[];
  locationSensitivities?: LocationSensitivity[];

  // Classification
  incidentTypes?: IncidentType[];
  hynekClassifications?: HynekClassification[];
  valleeClassifications?: ValleeClassification[];

  // Quick filters
  hasRadarConfirmation?: boolean;
  hasMultipleWitnesses?: boolean;
  hasMilitaryWitness?: boolean;
  hasPhysicalEvidence?: boolean;
  hasOfficialInvestigation?: boolean;
  hasVideoEvidence?: boolean;

  // Data source
  dataSourceIds?: string[];
}

MapConfig

Configuration for the map application:

interface MapConfig {
  branding: BrandingConfig;
  dataSources: DataSourceConfig[];
  controls: ControlsConfig;
  map: MapViewConfig;
  theme: ThemeConfig;
  labels?: LabelsConfig;
  features?: FeaturesConfig;
  filterVisibility?: FilterVisibilityConfig;
}

For the complete type definitions, see the Data Specification documentation or generate the full API docs with pnpm docs:api.

API Reference

Sightline provides a comprehensive TypeScript API for building incident mapping applications. This page provides an overview of the main modules and how to generate detailed API documentation.

Generating API Documentation

You can generate full API documentation locally using TypeDoc:

pnpm docs:api

This generates markdown documentation in the docs-api/ directory, organized by module:

core/ - Core types, contexts, and configuration
adapters/ - Data adapters for different sources
controls/ - UI control components
ui/ - Base UI components
hooks/ - React hooks
lib/ - Utility functions

Module Overview

Core (`@/core`)

The core module provides the foundation of Sightline:

import {
  // Configuration
  ConfigProvider,
  useConfig,
  useBranding,
  useDataSources,
  useLoaderConfig,

  // Data management
  DataProvider,
  useData,
  useIncidents,
  useFilters,
  useSelection,

  // Theme
  ThemeProvider,
  useTheme,
  useResolvedTheme,

  // Map engine
  MapEngine,

  // Types
  type Incident,
  type IncidentDisplay,
  type IncidentFilters,
  type MapConfig,
  type LoaderConfig,
} from '@/core';

Adapters (`@/adapters`)

Data adapters provide a uniform interface for different data sources:

import {
  createAdapter,
  StaticAdapter,
  SupabaseAdapter,
  ApiAdapter,
  type DataAdapter,
  type FilterOptions,
} from '@/adapters';

// Create an adapter based on config
const adapter = createAdapter(dataSourceConfig);
const incidents = await adapter.getIncidents(filters);

Controls (`@/controls`)

Pre-built UI controls for common functionality:

import {
  FilterSidebar,
  IncidentFeed,
  TimelineControl,
  ThemeToggle,
  SourceToggle,
  StatsPanel,
} from '@/controls';

Hooks (`@/hooks`)

React hooks for state management and configuration:

import {
  useMapUIState,
  useRendererConfig,
  type FeedStyle,
  type MapUIState,
} from '@/hooks';

UI (`@/ui`)

Base UI components for building custom interfaces:

import {
  // Layout components
  Dropdown,
  DropdownItem,
  DropdownTrigger,
  AccordionSection,
  ToggleButton,
  ToggleButtonGroup,
  ErrorBoundary,
  
  // Loading states
  Loader,
  InlineLoader,
  LoaderOverlay,
  FullPageState,
  FullPageLoading,
  
  // Info display
  InfoPopover,
  DemoBadge,
  
  // Types
  type LoaderVariant,
  type LoaderSize,
  type InfoPopoverProps,
  type DemoBadgeProps,
} from '@/ui';

Utilities (`@/lib`)

Helper functions and utilities:

import {
  // Filtering
  filterIncidents,
  createFilterSets,
  hasActiveFilters,

  // Formatting
  formatLocation,
  formatDuration,
  pluralize,

  // Incident utilities
  getSensitivityDisplay,
  getVisualMedia,

  // Styling
  cn,
} from '@/lib';

Key Types

Incident

The core data type representing an incident:

interface Incident {
  id: string;
  status: PublicationStatus;
  createdAt: string;
  updatedAt: string;

  // Required nested objects
  temporal: TemporalData;
  location: LocationData;

  // Optional nested objects
  classification?: ClassificationData;
  objectCharacteristics?: ObjectCharacteristics;
  witnesses?: WitnessData;
  sensorEvidence?: SensorEvidenceData;
  investigation?: InvestigationData;
  responseImpact?: ResponseImpactData;
  // ... more
}

IncidentFilters

Filter criteria for querying incidents:

interface IncidentFilters {
  // Location
  countries?: string[];
  siteTypes?: SiteType[];
  locationSensitivities?: LocationSensitivity[];

  // Classification
  incidentTypes?: IncidentType[];
  hynekClassifications?: HynekClassification[];
  valleeClassifications?: ValleeClassification[];

  // Quick filters
  hasRadarConfirmation?: boolean;
  hasMultipleWitnesses?: boolean;
  hasMilitaryWitness?: boolean;
  hasPhysicalEvidence?: boolean;
  hasOfficialInvestigation?: boolean;
  hasVideoEvidence?: boolean;

  // Data source
  dataSourceIds?: string[];
}

MapConfig

Configuration for the map application:

interface MapConfig {
  branding: BrandingConfig;
  dataSources: DataSourceConfig[];
  controls: ControlsConfig;
  map: MapViewConfig;
  theme: ThemeConfig;
  labels?: LabelsConfig;
  features?: FeaturesConfig;
  filterVisibility?: FilterVisibilityConfig;
}

For the complete type definitions, see the Data Specification documentation or generate the full API docs with pnpm docs:api.

API Reference

Generating API Documentation

Module Overview

Core (`@/core`)

Adapters (`@/adapters`)

Controls (`@/controls`)

Hooks (`@/hooks`)

UI (`@/ui`)

Utilities (`@/lib`)

Key Types

Incident

IncidentFilters

MapConfig

See Also

On this page

API Reference

Generating API Documentation

Module Overview

Core (`@/core`)

Adapters (`@/adapters`)

Controls (`@/controls`)

Hooks (`@/hooks`)

UI (`@/ui`)

Utilities (`@/lib`)

Key Types

Incident

IncidentFilters

MapConfig

See Also

On this page