@neobyzantine/series-player 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+import React from 'react';
+import * as _neobyzantine_types from '@neobyzantine/types';
+import { HistoricalEvent } from '@neobyzantine/types';
+import L from 'leaflet';
+
+interface SeriesEntry {
+    slug: string;
+    title: string;
+    date_display?: string;
+    color?: string;
+}
+interface AnimationFeatureProperties {
+    sort_order: number;
+    label?: string;
+    narration?: string;
+    zoom?: number;
+    animation_pause_ms?: number;
+    [key: string]: unknown;
+}
+interface AnimationFeature {
+    type: 'Feature';
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number];
+    };
+    properties: AnimationFeatureProperties;
+}
+interface AnimationFeatureCollection {
+    type: 'FeatureCollection';
+    features: AnimationFeature[];
+}
+interface AnimatorEvents {
+    step: {
+        index: number;
+        total: number;
+        props: AnimationFeatureProperties;
+    };
+    play: undefined;
+    pause: undefined;
+    reset: undefined;
+    complete: undefined;
+}
+type AnimatorEventName = keyof AnimatorEvents;
+
+interface SeriesPlayerProps {
+    entries: SeriesEntry[];
+    onEventLoad: (slug: string) => Promise<HistoricalEvent>;
+    apiBase?: string;
+    /** Color for map animation pulses. Defaults to active entry color or gold. */
+    accentColor?: string;
+    ttsEnabled?: boolean;
+    autoPlayInterval?: number;
+    resolvePortrait?: (path: string) => string;
+    sanitizeHtml?: (html: string) => string;
+    onEventChange?: (index: number, event: HistoricalEvent) => void;
+    height?: string;
+    className?: string;
+}
+declare function SeriesPlayer({ entries, onEventLoad, accentColor, ttsEnabled, autoPlayInterval, resolvePortrait, sanitizeHtml, onEventChange, height, className, }: SeriesPlayerProps): React.JSX.Element;
+
+interface SeriesStepListProps {
+    entries: SeriesEntry[];
+    currentIndex: number;
+    jumpHistory: number[];
+    onSelect: (index: number) => void;
+}
+declare function SeriesStepList({ entries, currentIndex, jumpHistory, onSelect }: SeriesStepListProps): React.JSX.Element;
+
+interface SeriesEventPanelProps {
+    event: HistoricalEvent | null;
+    loading?: boolean;
+    error?: string | null;
+    accentColor?: string;
+    /** Convert storage path to URL — consumer knows the URL scheme. */
+    resolvePortrait?: (path: string) => string;
+    /** Sanitize HTML before dangerouslySetInnerHTML — consumer provides sanitizer. */
+    sanitizeHtml?: (html: string) => string;
+    onActorClick?: (actor: _neobyzantine_types.Actor) => void;
+    onRelatedClick?: (slug: string) => void;
+    className?: string;
+}
+declare function SeriesEventPanel({ event, loading, error, accentColor, resolvePortrait, sanitizeHtml, onActorClick, onRelatedClick, className, }: SeriesEventPanelProps): React.JSX.Element | null;
+
+interface AnimatorControlsProps {
+    playing: boolean;
+    current: number;
+    total: number;
+    currentStep: AnimationFeatureProperties | null;
+    accentColor?: string;
+    onPlay: () => void;
+    onPause: () => void;
+    onReset: () => void;
+    onStepForward: () => void;
+    onStepBack: () => void;
+}
+declare function AnimatorControls({ playing, current, total, currentStep, accentColor, onPlay, onPause, onReset, onStepForward, onStepBack, }: AnimatorControlsProps): React.JSX.Element | null;
+
+type Listener<K extends AnimatorEventName> = (data: AnimatorEvents[K]) => void;
+interface EventAnimatorOptions {
+    stepMs?: number;
+    ttsEnabled?: boolean;
+}
+/**
+ * Step-by-step playback of a GeoJSON feature collection on a Leaflet map.
+ * Each Point feature represents one animation step: the map flies to it,
+ * a pulsing marker is shown, and optional TTS narration is spoken.
+ *
+ * Pure TypeScript class — no React. Wire into React via AnimatorDriver (uses useMap()).
+ */
+declare class EventAnimator {
+    private readonly map;
+    private readonly color;
+    private readonly stepMs;
+    private ttsEnabled;
+    current: number;
+    playing: boolean;
+    private timer;
+    private pulseMarker;
+    private listeners;
+    readonly steps: AnimationFeature[];
+    constructor(map: L.Map, geojson: AnimationFeatureCollection, color: string, options?: EventAnimatorOptions);
+    get total(): number;
+    on<K extends AnimatorEventName>(event: K, fn: Listener<K>): this;
+    private emit;
+    play(): void;
+    pause(): void;
+    reset(): void;
+    stepForward(): void;
+    stepBack(): void;
+    setTTS(enabled: boolean): void;
+    private goto;
+    private schedule;
+    private clearPulse;
+    private speak;
+}
+
+interface AnimatedEventMapProps {
+    geojson: AnimationFeatureCollection | null;
+    color?: string;
+    stepMs?: number;
+    ttsEnabled?: boolean;
+    onAnimatorReady?: (animator: EventAnimator) => void;
+    onStep?: (data: AnimatorEvents['step']) => void;
+    onComplete?: () => void;
+    center?: [number, number];
+    zoom?: number;
+    height?: string;
+    className?: string;
+}
+declare function AnimatedEventMap({ geojson, color, stepMs, ttsEnabled, onAnimatorReady, onStep, onComplete, center, // Constantinople
+zoom, height, className, }: AnimatedEventMapProps): React.JSX.Element;
+
+interface SeriesPlayerState {
+    currentIndex: number;
+    event: HistoricalEvent | null;
+    loading: boolean;
+    error: string | null;
+    jumpHistory: number[];
+    autoPlaying: boolean;
+}
+interface SeriesPlayerActions {
+    next(): void;
+    prev(): void;
+    goTo(index: number): void;
+    jumpToRelated(slug: string): void;
+    backFromJump(): void;
+    toggleAutoPlay(): void;
+}
+declare function useSeriesPlayer(entries: SeriesEntry[], onEventLoad: (slug: string) => Promise<HistoricalEvent>, opts?: {
+    onEventChange?: (index: number, event: HistoricalEvent) => void;
+    autoPlayInterval?: number;
+}): [SeriesPlayerState, SeriesPlayerActions];
+
+export { AnimatedEventMap, type AnimatedEventMapProps, type AnimationFeature, type AnimationFeatureCollection, type AnimationFeatureProperties, AnimatorControls, type AnimatorControlsProps, type AnimatorEventName, type AnimatorEvents, EventAnimator, type EventAnimatorOptions, type SeriesEntry, SeriesEventPanel, type SeriesEventPanelProps, SeriesPlayer, type SeriesPlayerActions, type SeriesPlayerProps, type SeriesPlayerState, SeriesStepList, type SeriesStepListProps, useSeriesPlayer };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+import React from 'react';
+import * as _neobyzantine_types from '@neobyzantine/types';
+import { HistoricalEvent } from '@neobyzantine/types';
+import L from 'leaflet';
+
+interface SeriesEntry {
+    slug: string;
+    title: string;
+    date_display?: string;
+    color?: string;
+}
+interface AnimationFeatureProperties {
+    sort_order: number;
+    label?: string;
+    narration?: string;
+    zoom?: number;
+    animation_pause_ms?: number;
+    [key: string]: unknown;
+}
+interface AnimationFeature {
+    type: 'Feature';
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number];
+    };
+    properties: AnimationFeatureProperties;
+}
+interface AnimationFeatureCollection {
+    type: 'FeatureCollection';
+    features: AnimationFeature[];
+}
+interface AnimatorEvents {
+    step: {
+        index: number;
+        total: number;
+        props: AnimationFeatureProperties;
+    };
+    play: undefined;
+    pause: undefined;
+    reset: undefined;
+    complete: undefined;
+}
+type AnimatorEventName = keyof AnimatorEvents;
+
+interface SeriesPlayerProps {
+    entries: SeriesEntry[];
+    onEventLoad: (slug: string) => Promise<HistoricalEvent>;
+    apiBase?: string;
+    /** Color for map animation pulses. Defaults to active entry color or gold. */
+    accentColor?: string;
+    ttsEnabled?: boolean;
+    autoPlayInterval?: number;
+    resolvePortrait?: (path: string) => string;
+    sanitizeHtml?: (html: string) => string;
+    onEventChange?: (index: number, event: HistoricalEvent) => void;
+    height?: string;
+    className?: string;
+}
+declare function SeriesPlayer({ entries, onEventLoad, accentColor, ttsEnabled, autoPlayInterval, resolvePortrait, sanitizeHtml, onEventChange, height, className, }: SeriesPlayerProps): React.JSX.Element;
+
+interface SeriesStepListProps {
+    entries: SeriesEntry[];
+    currentIndex: number;
+    jumpHistory: number[];
+    onSelect: (index: number) => void;
+}
+declare function SeriesStepList({ entries, currentIndex, jumpHistory, onSelect }: SeriesStepListProps): React.JSX.Element;
+
+interface SeriesEventPanelProps {
+    event: HistoricalEvent | null;
+    loading?: boolean;
+    error?: string | null;
+    accentColor?: string;
+    /** Convert storage path to URL — consumer knows the URL scheme. */
+    resolvePortrait?: (path: string) => string;
+    /** Sanitize HTML before dangerouslySetInnerHTML — consumer provides sanitizer. */
+    sanitizeHtml?: (html: string) => string;
+    onActorClick?: (actor: _neobyzantine_types.Actor) => void;
+    onRelatedClick?: (slug: string) => void;
+    className?: string;
+}
+declare function SeriesEventPanel({ event, loading, error, accentColor, resolvePortrait, sanitizeHtml, onActorClick, onRelatedClick, className, }: SeriesEventPanelProps): React.JSX.Element | null;
+
+interface AnimatorControlsProps {
+    playing: boolean;
+    current: number;
+    total: number;
+    currentStep: AnimationFeatureProperties | null;
+    accentColor?: string;
+    onPlay: () => void;
+    onPause: () => void;
+    onReset: () => void;
+    onStepForward: () => void;
+    onStepBack: () => void;
+}
+declare function AnimatorControls({ playing, current, total, currentStep, accentColor, onPlay, onPause, onReset, onStepForward, onStepBack, }: AnimatorControlsProps): React.JSX.Element | null;
+
+type Listener<K extends AnimatorEventName> = (data: AnimatorEvents[K]) => void;
+interface EventAnimatorOptions {
+    stepMs?: number;
+    ttsEnabled?: boolean;
+}
+/**
+ * Step-by-step playback of a GeoJSON feature collection on a Leaflet map.
+ * Each Point feature represents one animation step: the map flies to it,
+ * a pulsing marker is shown, and optional TTS narration is spoken.
+ *
+ * Pure TypeScript class — no React. Wire into React via AnimatorDriver (uses useMap()).
+ */
+declare class EventAnimator {
+    private readonly map;
+    private readonly color;
+    private readonly stepMs;
+    private ttsEnabled;
+    current: number;
+    playing: boolean;
+    private timer;
+    private pulseMarker;
+    private listeners;
+    readonly steps: AnimationFeature[];
+    constructor(map: L.Map, geojson: AnimationFeatureCollection, color: string, options?: EventAnimatorOptions);
+    get total(): number;
+    on<K extends AnimatorEventName>(event: K, fn: Listener<K>): this;
+    private emit;
+    play(): void;
+    pause(): void;
+    reset(): void;
+    stepForward(): void;
+    stepBack(): void;
+    setTTS(enabled: boolean): void;
+    private goto;
+    private schedule;
+    private clearPulse;
+    private speak;
+}
+
+interface AnimatedEventMapProps {
+    geojson: AnimationFeatureCollection | null;
+    color?: string;
+    stepMs?: number;
+    ttsEnabled?: boolean;
+    onAnimatorReady?: (animator: EventAnimator) => void;
+    onStep?: (data: AnimatorEvents['step']) => void;
+    onComplete?: () => void;
+    center?: [number, number];
+    zoom?: number;
+    height?: string;
+    className?: string;
+}
+declare function AnimatedEventMap({ geojson, color, stepMs, ttsEnabled, onAnimatorReady, onStep, onComplete, center, // Constantinople
+zoom, height, className, }: AnimatedEventMapProps): React.JSX.Element;
+
+interface SeriesPlayerState {
+    currentIndex: number;
+    event: HistoricalEvent | null;
+    loading: boolean;
+    error: string | null;
+    jumpHistory: number[];
+    autoPlaying: boolean;
+}
+interface SeriesPlayerActions {
+    next(): void;
+    prev(): void;
+    goTo(index: number): void;
+    jumpToRelated(slug: string): void;
+    backFromJump(): void;
+    toggleAutoPlay(): void;
+}
+declare function useSeriesPlayer(entries: SeriesEntry[], onEventLoad: (slug: string) => Promise<HistoricalEvent>, opts?: {
+    onEventChange?: (index: number, event: HistoricalEvent) => void;
+    autoPlayInterval?: number;
+}): [SeriesPlayerState, SeriesPlayerActions];
+
+export { AnimatedEventMap, type AnimatedEventMapProps, type AnimationFeature, type AnimationFeatureCollection, type AnimationFeatureProperties, AnimatorControls, type AnimatorControlsProps, type AnimatorEventName, type AnimatorEvents, EventAnimator, type EventAnimatorOptions, type SeriesEntry, SeriesEventPanel, type SeriesEventPanelProps, SeriesPlayer, type SeriesPlayerActions, type SeriesPlayerProps, type SeriesPlayerState, SeriesStepList, type SeriesStepListProps, useSeriesPlayer };