scradar/src/scradar.d.ts

CSS-first scroll interaction library with progress-based animations

export interface ScradarOptions {
  target?: string;
  root?: Element | Window | null;
  boundary?: boolean | number;
  totalProgress?: boolean;
  momentum?: boolean;
  debug?: boolean;
  prefix?: string;
}

export interface ScradarSettings {
  visibility?: boolean | string | string[];
  fill?: boolean | string | string[];
  cover?: boolean | string | string[];
  enter?: boolean | string | string[];
  exit?: boolean | string | string[];
  offsetEnter?: boolean | string | string[];
  offsetExit?: boolean | string | string[];
  visibilityStep?: number[];
  fillStep?: number[];
  coverStep?: number[];
  enterStep?: number[];
  exitStep?: number[];
  peak?: number[] | { start: number; peak: number; end: number };
  once?: boolean;
  trigger?: string;
  horizontal?: boolean;
  container?: string;
  receiver?: string;
  delay?: string;
  breakpoint?: Record<number, Partial<ScradarSettings>>;
}

export interface ScradarController {
  el: HTMLElement;
  settings: ScradarSettings;
  visibility: number;
  fill: number;
  cover: number;
  enter: number;
  exit: number;
  peak: number;
  offsetEnter: number;
  offsetExit: number;
  containerSize: number;
  update(resize?: boolean): void;
  destroy(): void;
}

export interface ScradarEventDetail {
  from?: 'top' | 'bottom';
  isInitial?: boolean;
  value?: number;
  step?: number;
  prevStep?: number;
  maxStep?: number;
  type?: string;
  scroll?: 1 | -1 | 0;
  status?: 1 | -1;
}

declare global {
  interface HTMLElement {
    scradar?: ScradarController;
  }
  
  interface HTMLElementEventMap {
    'scrollEnter': CustomEvent<ScradarEventDetail>;
    'scrollExit': CustomEvent<ScradarEventDetail>;
    'fullIn': CustomEvent<ScradarEventDetail>;
    'fullOut': CustomEvent<ScradarEventDetail>;
    'fire': CustomEvent<ScradarEventDetail>;
    'collisionEnter': CustomEvent<ScradarEventDetail>;
    'collisionExit': CustomEvent<ScradarEventDetail>;
    'stepChange': CustomEvent<ScradarEventDetail>;
    'visibilityUpdate': CustomEvent<ScradarEventDetail>;
    'fillUpdate': CustomEvent<ScradarEventDetail>;
    'coverUpdate': CustomEvent<ScradarEventDetail>;
    'enterUpdate': CustomEvent<ScradarEventDetail>;
    'exitUpdate': CustomEvent<ScradarEventDetail>;
    'peakUpdate': CustomEvent<ScradarEventDetail>;
    'offsetEnterUpdate': CustomEvent<ScradarEventDetail>;
    'offsetExitUpdate': CustomEvent<ScradarEventDetail>;
  }
  
  interface WindowEventMap {
    'scrollTurn': CustomEvent<ScradarEventDetail>;
    'momentum': CustomEvent<ScradarEventDetail>;
  }
  
  interface DocumentEventMap {
    'scradarReady': CustomEvent<{ scradar: Scradar }>;
  }
}

declare class Scradar {
  static defaults: ScradarOptions;
  static configs: Record<string, ScradarSettings | ((element: HTMLElement) => ScradarSettings)>;
  
  constructor(target?: string | ScradarOptions, options?: ScradarOptions);
  
  readonly elements: HTMLElement[];
  readonly root: Element | Window;
  readonly scroll: 1 | -1 | 0;
  readonly progress: number;
  
  update(): void;
  destroy(): void;
  refresh(): void;
  
  on(event: string, callback: (detail: ScradarEventDetail) => void): void;
  off(event: string, callback: (detail: ScradarEventDetail) => void): void;
}

export default Scradar;

export = Scradar;

// React helper functions
export function setScradarConfigs(configs: Record<string, ScradarSettings | ((element: HTMLElement) => ScradarSettings)>): void;

// Vue helper functions (for Vue 3)
export interface VueApp {
  config: {
    globalProperties: {
      $scradar: typeof Scradar;
      $scradarConfigs: (configs: Record<string, ScradarSettings | ((element: HTMLElement) => ScradarSettings)>) => void;
    };
  };
  directive: (name: string, options: any) => void;
  use: (plugin: any, options?: any) => void;
}

// Vue 2 compatibility
export interface Vue2 {
  directive: (name: string, options: any) => void;
  prototype: {
    $scradar: typeof Scradar;
  };
}