@project-skymap/library 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -5,102 +5,95 @@ type SceneNode = {
     label: string;
     level: number;
     parent?: string;
+    children?: string[];
     weight?: number;
     icon?: string;
-    color?: string;
-    size?: number;
     meta?: Record<string, unknown>;
 };
-type SceneLink = {
-    source: string;
-    target: string;
-};
 type SceneModel = {
-    meta?: Record<string, unknown>;
     nodes: SceneNode[];
-    links: SceneLink[];
+    links?: SceneLink[];
+    meta?: Record<string, unknown>;
 };
-type ConstellationItem = {
-    id: string;
-    title: string;
-    type: "book" | "division" | "custom";
-    image: string;
-    anchors: string[];
-    center: [number, number, number] | null;
-    radius: number;
-    rotationDeg: number;
-    aspectRatio?: number;
-    opacity: number;
-    blend: "normal" | "additive" | "screen";
-    zBias: number;
-    fade: {
-        zoomInStart: number;
-        zoomInEnd: number;
-        hoverBoost: number;
-        minOpacity: number;
-        maxOpacity: number;
+type LayoutAlgorithm = "phyllotaxis" | "voronoi";
+type LayoutConfig = {
+    algorithm: LayoutAlgorithm;
+    radius?: number;
+    voronoi?: {
+        width: number;
+        height: number;
     };
 };
-type ConstellationConfig = {
-    version: number;
-    atlasBasePath: string;
-    constellations: ConstellationItem[];
-};
-type Vector3Arr = [number, number, number];
-type StarArrangement = Record<string, {
-    position: Vector3Arr;
-}>;
-type GroupDef = {
-    name: string;
-    start: number;
-    end: number;
+type StarArrangement = {
+    [id: string]: {
+        position: [number, number, number];
+    };
 };
 type StarMapConfig = {
-    background?: string;
-    camera?: {
-        fov?: number;
-        z?: number;
-        lon?: number;
-        lat?: number;
-    };
+    data?: any;
+    adapter?: (data: any) => SceneModel;
+    model?: SceneModel;
+    layout: LayoutConfig;
     arrangement?: StarArrangement;
-    polygons?: Record<string, Vector3Arr[]>;
-    editable?: boolean;
-    constellations?: ConstellationConfig;
-    groups?: Record<string, GroupDef[]>;
-    showBookLabels?: boolean;
-    showDivisionLabels?: boolean;
-    showChapterLabels?: boolean;
-    showGroupLabels?: boolean;
+    polygons?: Record<string, [number, number][]>;
+    background?: string;
+    labelColors?: Record<string, string>;
+    constellations?: any;
+    showConstellationArt?: boolean;
     showConstellationLines?: boolean;
     showDivisionBoundaries?: boolean;
-    showConstellationArt?: boolean;
     showBackdropStars?: boolean;
     backdropStarsCount?: number;
     showAtmosphere?: boolean;
-    model?: SceneModel;
-    data?: any;
-    adapter?: (data: any) => SceneModel;
-    visuals?: {
-        colorBy?: Array<{
-            when: Record<string, unknown>;
-            value: string;
-        }>;
-        sizeBy?: Array<{
-            when: Record<string, unknown>;
-            field: "weight";
-            scale: [number, number];
-        }>;
-    };
-    focus?: {
-        nodeId?: string;
-        animate?: boolean;
-    };
-    layout?: {
-        mode?: "radial" | "grid" | "force" | "spherical" | "manual";
-        radius?: number;
-        chapterRingSpacing?: number;
+    showBookLabels?: boolean;
+    showChapterLabels?: boolean;
+    showDivisionLabels?: boolean;
+    showGroupLabels?: boolean;
+    groups?: Record<string, {
+        name: string;
+        start: number;
+        end: number;
+    }[]>;
+    editable?: boolean;
+    projection?: "perspective" | "stereographic" | "blended";
+    camera?: {
+        lon?: number;
+        lat?: number;
     };
+    fitProjection?: boolean;
+};
+type SceneLink = {
+    source: string;
+    target: string;
+};
+type ConstellationConfig = {
+    version: number;
+    atlasBasePath: string;
+    constellations: {
+        id: string;
+        title: string;
+        type: string;
+        image: string;
+        anchors: string[];
+        center: null | [number, number];
+        radius: number;
+        rotationDeg: number;
+        opacity: number;
+        blend: string;
+        zBias: number;
+        fade: {
+            zoomInStart: number;
+            zoomInEnd: number;
+            hoverBoost: number;
+            minOpacity: number;
+            maxOpacity: number;
+        };
+    }[];
+};
+type HierarchyFilter = {
+    testament?: string;
+    division?: string;
+    bookKey?: string;
 };
 
 type StarMapProps = {
@@ -116,6 +109,9 @@ type StarMapHandle = {
     setHoveredBook: (id: string | null) => void;
     setFocusedBook: (id: string | null) => void;
     setOrderRevealEnabled: (enabled: boolean) => void;
+    setHierarchyFilter: (filter: HierarchyFilter | null) => void;
+    flyTo: (nodeId: string, targetFov?: number) => void;
+    setProjection: (id: "perspective" | "stereographic" | "blended") => void;
 };
 declare const StarMap: React.ForwardRefExoticComponent<StarMapProps & React.RefAttributes<StarMapHandle>>;
 
@@ -29195,4 +29191,59 @@ interface GenerateOptions {
 declare const defaultGenerateOptions: GenerateOptions;
 declare function generateArrangement(bible: BibleJSON, options?: Partial<GenerateOptions>): StarArrangement;
 
-export { type BibleJSON, type ConstellationConfig, type GenerateOptions, type SceneLink, type SceneModel, type SceneNode, type StarArrangement, StarMap, type StarMapConfig, type StarMapHandle, type StarMapProps, bibleToSceneModel, defaultGenerateOptions, defaultStars, generateArrangement };
+/**
+ * Projection system inspired by Stellarium's projection architecture.
+ *
+ * Stellarium supports 5 projection types (Perspective, Stereographic, Mercator,
+ * Hammer, Mollweide). We implement Perspective, Stereographic, and a Blended
+ * mode that reproduces the original auto-blend behavior.
+ *
+ * Each projection maps a view-space unit direction vector to/from 2D screen
+ * coordinates, independent of Three.js's built-in camera projection.
+ */
+type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+interface Projection {
+    /** Unique key for config / serialization */
+    readonly id: string;
+    /** Human-readable name */
+    readonly label: string;
+    /** Maximum valid FOV in degrees for this projection */
+    readonly maxFov: number;
+    /**
+     * Integer sent to the shader as uProjectionType.
+     * 0 = perspective, 1 = stereographic, 2 = blended (auto)
+     */
+    readonly glslProjectionType: number;
+    /**
+     * Forward projection: view-space unit direction -> raw projected xy.
+     * Returns null if the point should be clipped.
+     * The returned {x,y} are pre-scale values (caller multiplies by uScale/uAspect).
+     * Also returns the original dir.z for clipping decisions.
+     */
+    forward(dir: Vec3): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /**
+     * Inverse projection: NDC xy (after dividing out scale/aspect) -> view-space
+     * unit direction vector. Used for mouse picking / unprojection.
+     */
+    inverse(uvX: number, uvY: number, fovRad: number): Vec3;
+    /**
+     * Compute the uniform scale factor for a given FOV (radians).
+     */
+    getScale(fovRad: number): number;
+    /**
+     * Whether a view-space direction with the given z component should be clipped.
+     */
+    isClipped(dirZ: number): boolean;
+}
+type ProjectionId = "perspective" | "stereographic";
+declare const PROJECTIONS: Record<ProjectionId, () => Projection>;
+
+export { type BibleJSON, type ConstellationConfig, type GenerateOptions, type HierarchyFilter, PROJECTIONS, type Projection, type ProjectionId, type SceneLink, type SceneModel, type SceneNode, type StarArrangement, StarMap, type StarMapConfig, type StarMapHandle, type StarMapProps, bibleToSceneModel, defaultGenerateOptions, defaultStars, generateArrangement };

package/dist/index.d.ts

@@ -5,102 +5,95 @@ type SceneNode = {
     label: string;
     level: number;
     parent?: string;
+    children?: string[];
     weight?: number;
     icon?: string;
-    color?: string;
-    size?: number;
     meta?: Record<string, unknown>;
 };
-type SceneLink = {
-    source: string;
-    target: string;
-};
 type SceneModel = {
-    meta?: Record<string, unknown>;
     nodes: SceneNode[];
-    links: SceneLink[];
+    links?: SceneLink[];
+    meta?: Record<string, unknown>;
 };
-type ConstellationItem = {
-    id: string;
-    title: string;
-    type: "book" | "division" | "custom";
-    image: string;
-    anchors: string[];
-    center: [number, number, number] | null;
-    radius: number;
-    rotationDeg: number;
-    aspectRatio?: number;
-    opacity: number;
-    blend: "normal" | "additive" | "screen";
-    zBias: number;
-    fade: {
-        zoomInStart: number;
-        zoomInEnd: number;
-        hoverBoost: number;
-        minOpacity: number;
-        maxOpacity: number;
+type LayoutAlgorithm = "phyllotaxis" | "voronoi";
+type LayoutConfig = {
+    algorithm: LayoutAlgorithm;
+    radius?: number;
+    voronoi?: {
+        width: number;
+        height: number;
     };
 };
-type ConstellationConfig = {
-    version: number;
-    atlasBasePath: string;
-    constellations: ConstellationItem[];
-};
-type Vector3Arr = [number, number, number];
-type StarArrangement = Record<string, {
-    position: Vector3Arr;
-}>;
-type GroupDef = {
-    name: string;
-    start: number;
-    end: number;
+type StarArrangement = {
+    [id: string]: {
+        position: [number, number, number];
+    };
 };
 type StarMapConfig = {
-    background?: string;
-    camera?: {
-        fov?: number;
-        z?: number;
-        lon?: number;
-        lat?: number;
-    };
+    data?: any;
+    adapter?: (data: any) => SceneModel;
+    model?: SceneModel;
+    layout: LayoutConfig;
     arrangement?: StarArrangement;
-    polygons?: Record<string, Vector3Arr[]>;
-    editable?: boolean;
-    constellations?: ConstellationConfig;
-    groups?: Record<string, GroupDef[]>;
-    showBookLabels?: boolean;
-    showDivisionLabels?: boolean;
-    showChapterLabels?: boolean;
-    showGroupLabels?: boolean;
+    polygons?: Record<string, [number, number][]>;
+    background?: string;
+    labelColors?: Record<string, string>;
+    constellations?: any;
+    showConstellationArt?: boolean;
     showConstellationLines?: boolean;
     showDivisionBoundaries?: boolean;
-    showConstellationArt?: boolean;
     showBackdropStars?: boolean;
     backdropStarsCount?: number;
     showAtmosphere?: boolean;
-    model?: SceneModel;
-    data?: any;
-    adapter?: (data: any) => SceneModel;
-    visuals?: {
-        colorBy?: Array<{
-            when: Record<string, unknown>;
-            value: string;
-        }>;
-        sizeBy?: Array<{
-            when: Record<string, unknown>;
-            field: "weight";
-            scale: [number, number];
-        }>;
-    };
-    focus?: {
-        nodeId?: string;
-        animate?: boolean;
-    };
-    layout?: {
-        mode?: "radial" | "grid" | "force" | "spherical" | "manual";
-        radius?: number;
-        chapterRingSpacing?: number;
+    showBookLabels?: boolean;
+    showChapterLabels?: boolean;
+    showDivisionLabels?: boolean;
+    showGroupLabels?: boolean;
+    groups?: Record<string, {
+        name: string;
+        start: number;
+        end: number;
+    }[]>;
+    editable?: boolean;
+    projection?: "perspective" | "stereographic" | "blended";
+    camera?: {
+        lon?: number;
+        lat?: number;
     };
+    fitProjection?: boolean;
+};
+type SceneLink = {
+    source: string;
+    target: string;
+};
+type ConstellationConfig = {
+    version: number;
+    atlasBasePath: string;
+    constellations: {
+        id: string;
+        title: string;
+        type: string;
+        image: string;
+        anchors: string[];
+        center: null | [number, number];
+        radius: number;
+        rotationDeg: number;
+        opacity: number;
+        blend: string;
+        zBias: number;
+        fade: {
+            zoomInStart: number;
+            zoomInEnd: number;
+            hoverBoost: number;
+            minOpacity: number;
+            maxOpacity: number;
+        };
+    }[];
+};
+type HierarchyFilter = {
+    testament?: string;
+    division?: string;
+    bookKey?: string;
 };
 
 type StarMapProps = {
@@ -116,6 +109,9 @@ type StarMapHandle = {
     setHoveredBook: (id: string | null) => void;
     setFocusedBook: (id: string | null) => void;
     setOrderRevealEnabled: (enabled: boolean) => void;
+    setHierarchyFilter: (filter: HierarchyFilter | null) => void;
+    flyTo: (nodeId: string, targetFov?: number) => void;
+    setProjection: (id: "perspective" | "stereographic" | "blended") => void;
 };
 declare const StarMap: React.ForwardRefExoticComponent<StarMapProps & React.RefAttributes<StarMapHandle>>;
 
@@ -29195,4 +29191,59 @@ interface GenerateOptions {
 declare const defaultGenerateOptions: GenerateOptions;
 declare function generateArrangement(bible: BibleJSON, options?: Partial<GenerateOptions>): StarArrangement;
 
-export { type BibleJSON, type ConstellationConfig, type GenerateOptions, type SceneLink, type SceneModel, type SceneNode, type StarArrangement, StarMap, type StarMapConfig, type StarMapHandle, type StarMapProps, bibleToSceneModel, defaultGenerateOptions, defaultStars, generateArrangement };
+/**
+ * Projection system inspired by Stellarium's projection architecture.
+ *
+ * Stellarium supports 5 projection types (Perspective, Stereographic, Mercator,
+ * Hammer, Mollweide). We implement Perspective, Stereographic, and a Blended
+ * mode that reproduces the original auto-blend behavior.
+ *
+ * Each projection maps a view-space unit direction vector to/from 2D screen
+ * coordinates, independent of Three.js's built-in camera projection.
+ */
+type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+interface Projection {
+    /** Unique key for config / serialization */
+    readonly id: string;
+    /** Human-readable name */
+    readonly label: string;
+    /** Maximum valid FOV in degrees for this projection */
+    readonly maxFov: number;
+    /**
+     * Integer sent to the shader as uProjectionType.
+     * 0 = perspective, 1 = stereographic, 2 = blended (auto)
+     */
+    readonly glslProjectionType: number;
+    /**
+     * Forward projection: view-space unit direction -> raw projected xy.
+     * Returns null if the point should be clipped.
+     * The returned {x,y} are pre-scale values (caller multiplies by uScale/uAspect).
+     * Also returns the original dir.z for clipping decisions.
+     */
+    forward(dir: Vec3): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /**
+     * Inverse projection: NDC xy (after dividing out scale/aspect) -> view-space
+     * unit direction vector. Used for mouse picking / unprojection.
+     */
+    inverse(uvX: number, uvY: number, fovRad: number): Vec3;
+    /**
+     * Compute the uniform scale factor for a given FOV (radians).
+     */
+    getScale(fovRad: number): number;
+    /**
+     * Whether a view-space direction with the given z component should be clipped.
+     */
+    isClipped(dirZ: number): boolean;
+}
+type ProjectionId = "perspective" | "stereographic";
+declare const PROJECTIONS: Record<ProjectionId, () => Projection>;
+
+export { type BibleJSON, type ConstellationConfig, type GenerateOptions, type HierarchyFilter, PROJECTIONS, type Projection, type ProjectionId, type SceneLink, type SceneModel, type SceneNode, type StarArrangement, StarMap, type StarMapConfig, type StarMapHandle, type StarMapProps, bibleToSceneModel, defaultGenerateOptions, defaultStars, generateArrangement };