@motioncomplex/cosmos-lib 1.0.9

package/dist/three/shaders.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Built-in GLSL shader sources used by the Three.js integration layer.
+ *
+ * Currently contains the atmosphere glow shaders consumed by
+ * {@link createAtmosphere}. The shaders implement a Fresnel-based rim-lighting
+ * effect rendered on the back face of a slightly oversized sphere with additive
+ * blending.
+ *
+ * **`atmosphereVert`** -- Vertex shader that computes per-vertex view direction
+ * and normal vectors in world space.
+ *
+ * **`atmosphereFrag`** -- Fragment shader with the following uniforms:
+ * - `uAtmColor` (`vec3`) -- atmosphere RGB colour.
+ * - `uIntensity` (`float`) -- glow intensity multiplier.
+ *
+ * The fragment alpha is derived from `pow(rim, 3.0) * uIntensity`, where `rim`
+ * is `1.0 - abs(dot(normal, viewDir))`.
+ */
+export declare const SHADERS: {
+    readonly atmosphereVert: "\n    varying vec3 vNormal;\n    varying vec3 vViewDir;\n    void main() {\n      vec4 worldPos = modelMatrix * vec4(position, 1.0);\n      vViewDir    = normalize(cameraPosition - worldPos.xyz);\n      vNormal     = normalize(normalMatrix * normal);\n      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n    }\n  ";
+    readonly atmosphereFrag: "\n    uniform vec3  uAtmColor;\n    uniform float uIntensity;\n    varying vec3  vNormal;\n    varying vec3  vViewDir;\n    void main() {\n      float rim   = 1.0 - abs(dot(vNormal, vViewDir));\n      float alpha = pow(rim, 3.0) * uIntensity;\n      gl_FragColor = vec4(uAtmColor * alpha, alpha);\n    }\n  ";
+};

package/dist/three/types.d.ts

@@ -0,0 +1,169 @@
+import type * as THREE from 'three';
+/**
+ * Configuration for {@link createPlanet}.
+ *
+ * @example
+ * ```ts
+ * const opts: PlanetOptions = {
+ *   radius: 6.5,
+ *   textureUrl: 'earth-bluemarble-4k.jpg',
+ *   atmosphere: { color: 0x4488ff, intensity: 1.3 },
+ * }
+ * ```
+ */
+export interface PlanetOptions {
+    /** Sphere radius in scene units. */
+    radius: number;
+    /** Single texture URL for the planet surface. */
+    textureUrl?: string;
+    /** Fallback chain of texture URLs — takes priority over `textureUrl` if provided. */
+    textureUrls?: string[];
+    /** URL for a bump/displacement map to add surface relief. */
+    bumpUrl?: string;
+    /** Base colour as a hex number (e.g. `0x3366aa`). Used when no texture is loaded. */
+    color?: number;
+    /** Emissive colour (self-illumination), e.g. for a star. */
+    emissive?: number;
+    /** Emissive intensity multiplier. @defaultValue `1` */
+    emissiveIntensity?: number;
+    /** Optional atmospheric glow shell rendered around the planet. */
+    atmosphere?: {
+        /** Atmosphere colour as a hex number. */
+        color: number;
+        /** Glow intensity. @defaultValue `1` */
+        intensity?: number;
+    };
+    /** Optional planetary ring system (e.g. Saturn). */
+    rings?: {
+        /** Inner ring radius in scene units. */
+        inner: number;
+        /** Outer ring radius in scene units. */
+        outer: number;
+        /** Ring colour as a hex number. */
+        color: number;
+        /** Ring opacity (0–1). */
+        opacity: number;
+        /** Axial tilt of the ring plane in degrees. @defaultValue `0` */
+        tilt?: number;
+    };
+    /** When `true`, renders a black-hole accretion-disk effect instead of a standard sphere. */
+    isBlackHole?: boolean;
+}
+/**
+ * Return value of {@link createPlanet}.
+ */
+export interface PlanetResult {
+    /** Top-level group containing the planet mesh, atmosphere, and rings. */
+    group: THREE.Group;
+    /** The planet's surface mesh. */
+    mesh: THREE.Mesh;
+    /** Dispose all GPU resources (geometries, materials, textures). */
+    dispose: () => void;
+}
+/**
+ * Configuration for {@link createNebula}.
+ *
+ * @example
+ * ```ts
+ * const opts: NebulaOptions = {
+ *   radius: 3000,
+ *   textureUrls: ['orion-nebula-hubble.jpg'],
+ *   opacity: 0.9,
+ * }
+ * ```
+ */
+export interface NebulaOptions {
+    /** Visual radius of the nebula sprite in scene units. */
+    radius: number;
+    /** Aspect ratio (width / height) of the sprite. @defaultValue `1` */
+    aspect?: number;
+    /** Fallback chain of texture URLs for the nebula image. */
+    textureUrls: string[];
+    /** Sprite opacity (0–1). @defaultValue `1` */
+    opacity?: number;
+}
+/**
+ * Return value of {@link createNebula}.
+ */
+export interface NebulaResult {
+    /** Top-level group containing the sprite and hit mesh. */
+    group: THREE.Group;
+    /** The billboard sprite displaying the nebula texture. */
+    sprite: THREE.Sprite;
+    /** Invisible mesh used for raycasting / click detection. */
+    hitMesh: THREE.Mesh;
+    /** Dispose all GPU resources (geometries, materials, textures). */
+    dispose: () => void;
+}
+/**
+ * Configuration for {@link createStarField}.
+ *
+ * @example
+ * ```ts
+ * const stars = createStarField({ count: 5000, maxRadius: 10000 }, THREE)
+ * scene.add(stars)
+ * ```
+ */
+export interface StarFieldOptions {
+    /** Number of stars to generate. @defaultValue `2000` */
+    count?: number;
+    /** Minimum distance from the origin. @defaultValue `500` */
+    minRadius?: number;
+    /** Maximum distance from the origin. @defaultValue `5000` */
+    maxRadius?: number;
+    /** Minimum star point size. @defaultValue `0.5` */
+    sizeMin?: number;
+    /** Maximum star point size. @defaultValue `2` */
+    sizeMax?: number;
+    /** Point opacity (0–1). @defaultValue `1` */
+    opacity?: number;
+}
+/**
+ * Configuration for {@link createOrbit}.
+ *
+ * @example
+ * ```ts
+ * const ring = createOrbit({ color: 0x888888, opacity: 0.4 }, THREE)
+ * scene.add(ring)
+ * ```
+ */
+export interface OrbitOptions {
+    /** Line colour as a hex number. @defaultValue `0xffffff` */
+    color?: number;
+    /** Line opacity (0–1). @defaultValue `0.3` */
+    opacity?: number;
+    /** Number of line segments forming the circle. @defaultValue `128` */
+    segments?: number;
+}
+/**
+ * Options for {@link CameraFlight.flyTo}.
+ *
+ * @example
+ * ```ts
+ * flight.flyTo(target, lookAt, { duration: 2000, easing: 'inOut' })
+ * ```
+ */
+export interface FlightOptions {
+    /** Animation duration in milliseconds. @defaultValue `1500` */
+    duration?: number;
+    /** Easing curve. @defaultValue `'inOut'` */
+    easing?: 'in' | 'out' | 'inOut';
+    /** Callback invoked when the flight completes. */
+    onDone?: () => void;
+}
+/**
+ * Options for {@link CameraFlight.orbitAround}.
+ *
+ * @example
+ * ```ts
+ * flight.orbitAround(planet.group.position, { radius: 20, speed: 0.5 })
+ * ```
+ */
+export interface OrbitAroundOptions {
+    /** Orbit radius in scene units. @defaultValue `10` */
+    radius?: number;
+    /** Angular speed in radians per second. @defaultValue `0.3` */
+    speed?: number;
+    /** Camera elevation above the orbit plane in scene units. @defaultValue `0` */
+    elevation?: number;
+}

package/dist/transitions.d.ts

@@ -0,0 +1,246 @@
+import type { MorphOptions, StaggerOptions, HeroExpandOptions } from './types.js';
+/**
+ * Wrap a DOM mutation in the View Transitions API.
+ *
+ * When the browser supports `document.startViewTransition`, the provided
+ * callback is executed inside a view transition so the browser can
+ * automatically cross-fade old and new DOM states. On unsupported browsers
+ * the callback is invoked directly as a no-op fallback.
+ *
+ * Custom CSS variables `--cosmos-vt-duration` and `--cosmos-vt-easing` are
+ * set on the document element so companion stylesheets can pick them up.
+ *
+ * @param updateFn - A synchronous or asynchronous function that mutates the DOM
+ *                   (e.g. swapping panel content, re-rendering a component).
+ * @param opts     - Transition options. See {@link MorphOptions} for defaults.
+ * @returns A promise that resolves when the view transition finishes (or
+ *          immediately after `updateFn` on unsupported browsers).
+ *
+ * @example
+ * ```ts
+ * import { morph } from '@motioncomplex/cosmos-lib'
+ *
+ * // Morph a detail panel from one star to another
+ * const controller = new AbortController()
+ * await morph(() => {
+ *   panel.innerHTML = renderStarDetail(nextStar)
+ * }, { duration: 350, easing: 'ease-out', signal: controller.signal })
+ * ```
+ */
+export declare function morph(updateFn: () => void | Promise<void>, opts?: MorphOptions): Promise<void>;
+/**
+ * Stagger-reveal all direct children of a container element.
+ *
+ * Each child fades in and slides from the specified direction with a
+ * configurable inter-child delay, producing a cascading entrance effect.
+ * Animation is driven by `requestAnimationFrame` for frame-accurate timing
+ * and can be cancelled at any time via an `AbortSignal`.
+ *
+ * @param container - The parent element whose direct children will be animated.
+ * @param opts      - Stagger options controlling delay, timing, direction, and
+ *                    cancellation. See {@link StaggerOptions} for defaults.
+ * @returns A promise that resolves when the last child finishes its entrance
+ *          animation, or immediately if the container has no children or the
+ *          signal is already aborted.
+ *
+ * @example
+ * ```ts
+ * import { staggerIn } from '@motioncomplex/cosmos-lib'
+ *
+ * // Stagger-reveal a grid of star cards from the bottom
+ * const grid = document.querySelector<HTMLElement>('.star-card-grid')!
+ * await staggerIn(grid, {
+ *   delay: 100,
+ *   stagger: 60,
+ *   duration: 500,
+ *   from: 'bottom',
+ *   distance: '24px',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Cancel mid-animation with an AbortController
+ * const controller = new AbortController()
+ * staggerIn(grid, { signal: controller.signal })
+ * // later...
+ * controller.abort()
+ * ```
+ */
+export declare function staggerIn(container: HTMLElement, opts?: StaggerOptions): Promise<void>;
+/**
+ * Stagger-hide all direct children of a container element.
+ *
+ * The inverse of {@link staggerIn}: children fade out and slide in the
+ * specified direction, animated in **reverse DOM order** (last child first)
+ * to create a natural cascading exit. Driven by `requestAnimationFrame`
+ * and cancellable via `AbortSignal`.
+ *
+ * @param container - The parent element whose direct children will be animated out.
+ * @param opts      - Stagger options controlling timing, direction, and
+ *                    cancellation. See {@link StaggerOptions} for defaults.
+ *                    Note: `delay` is ignored for stagger-out; animation
+ *                    begins immediately.
+ * @returns A promise that resolves when the last child finishes its exit
+ *          animation, or immediately if the container is empty or the signal
+ *          is already aborted.
+ *
+ * @example
+ * ```ts
+ * import { staggerOut } from '@motioncomplex/cosmos-lib'
+ *
+ * // Stagger-hide a grid of star cards before removing them
+ * const grid = document.querySelector<HTMLElement>('.star-card-grid')!
+ * await staggerOut(grid, {
+ *   stagger: 40,
+ *   duration: 300,
+ *   from: 'bottom',
+ *   distance: '12px',
+ * })
+ * grid.innerHTML = ''
+ * ```
+ */
+export declare function staggerOut(container: HTMLElement, opts?: StaggerOptions): Promise<void>;
+/**
+ * Fade an element in or out.
+ *
+ * Applies a CSS opacity transition and toggles `pointer-events` accordingly
+ * (`'auto'` when fading in, `'none'` when fading out). Resolves when the
+ * `transitionend` event fires, with a safety timeout in case the event is
+ * swallowed.
+ *
+ * @param el        - The DOM element to fade.
+ * @param direction - `'in'` to fade the element to full opacity, `'out'` to
+ *                    fade it to transparent.
+ * @param duration  - Transition duration in milliseconds. Defaults to `300`.
+ * @returns A promise that resolves when the fade completes.
+ *
+ * @example
+ * ```ts
+ * import { fade } from '@motioncomplex/cosmos-lib'
+ *
+ * const tooltip = document.getElementById('star-tooltip')!
+ * // Show the tooltip
+ * await fade(tooltip, 'in', 200)
+ * // Later, hide it
+ * await fade(tooltip, 'out', 200)
+ * ```
+ */
+export declare function fade(el: HTMLElement, direction: 'in' | 'out', duration?: number): Promise<void>;
+/**
+ * Crossfade two elements: fades `from` out while fading `to` in simultaneously.
+ *
+ * Both fade animations run in parallel via {@link fade}. After both complete,
+ * the outgoing element is hidden with `display: none` so it no longer occupies
+ * layout space.
+ *
+ * @param from     - The currently visible element to fade out.
+ * @param to       - The incoming element to fade in. Its `display` style is
+ *                   cleared before the fade begins.
+ * @param duration - Transition duration in milliseconds for each fade.
+ *                   Defaults to `400`.
+ * @returns A promise that resolves when both fades are complete and `from` has
+ *          been hidden.
+ *
+ * @example
+ * ```ts
+ * import { crossfade } from '@motioncomplex/cosmos-lib'
+ *
+ * const listView   = document.getElementById('star-list')!
+ * const detailView = document.getElementById('star-detail')!
+ *
+ * // Swap from list view to detail view
+ * await crossfade(listView, detailView, 350)
+ * ```
+ */
+export declare function crossfade(from: HTMLElement, to: HTMLElement, duration?: number): Promise<void>;
+/**
+ * Hero expand -- animates an element from its current bounding rect to fill
+ * the viewport using the FLIP (First-Last-Invert-Play) technique.
+ *
+ * Reads the element's current position, computes the translate/scale needed
+ * to cover the full viewport, and animates using a CSS `transform` transition.
+ * No GSAP or other animation library is required. Styles are cleaned up
+ * automatically when the transition ends (or after a safety timeout).
+ *
+ * Cancellable via `opts.signal`; if aborted the element stays in its
+ * current state.
+ *
+ * @param element - The DOM element to expand (e.g. a star card thumbnail).
+ * @param opts    - Animation options. See {@link HeroExpandOptions} for defaults.
+ *
+ * @example
+ * ```ts
+ * import { heroExpand } from '@motioncomplex/cosmos-lib'
+ *
+ * const card = document.querySelector<HTMLElement>('.star-card')!
+ * heroExpand(card, {
+ *   duration: 500,
+ *   easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+ *   onDone: () => showFullScreenOverlay(card.dataset.starId!),
+ * })
+ * ```
+ */
+export declare function heroExpand(element: HTMLElement, opts?: HeroExpandOptions): void;
+/**
+ * Hero collapse -- animates an overlay element from full-viewport size down
+ * into the bounding rect of a target element, producing the reverse of
+ * {@link heroExpand}.
+ *
+ * If no `overlayEl` is supplied, a temporary full-screen `<div>` is created,
+ * appended to `document.body`, and automatically removed after the animation
+ * completes. When a pre-existing overlay is passed it is **not** removed --
+ * only its transform and opacity are animated.
+ *
+ * Cancellable via `opts.signal`; if aborted, cleanup runs immediately.
+ *
+ * @param targetElement - The element to collapse into (e.g. the original
+ *                        thumbnail card).
+ * @param opts          - Animation options. See {@link HeroExpandOptions} for
+ *                        defaults.
+ * @param overlayEl     - Optional pre-existing overlay element. When omitted a
+ *                        temporary overlay `<div>` is created and removed
+ *                        automatically after animation.
+ *
+ * @example
+ * ```ts
+ * import { heroCollapse } from '@motioncomplex/cosmos-lib'
+ *
+ * const card    = document.querySelector<HTMLElement>('.star-card')!
+ * const overlay = document.getElementById('fullscreen-overlay')!
+ *
+ * heroCollapse(card, {
+ *   duration: 400,
+ *   onDone: () => overlay.remove(),
+ * }, overlay)
+ * ```
+ */
+export declare function heroCollapse(targetElement: HTMLElement, opts?: HeroExpandOptions, overlayEl?: HTMLElement): void;
+/**
+ * Legacy namespace re-exporting all transition functions.
+ *
+ * @deprecated Use the named exports `morph`, `staggerIn`, `staggerOut`,
+ * `fade`, `crossfade`, `heroExpand`, and `heroCollapse` directly instead.
+ * This object is retained solely for backwards compatibility and will be
+ * removed in a future major release.
+ *
+ * @example
+ * ```ts
+ * // Before (deprecated)
+ * import { Transitions } from '@motioncomplex/cosmos-lib'
+ * Transitions.staggerIn(grid)
+ *
+ * // After (preferred)
+ * import { staggerIn } from '@motioncomplex/cosmos-lib'
+ * staggerIn(grid)
+ * ```
+ */
+export declare const Transitions: {
+    morph: typeof morph;
+    staggerIn: typeof staggerIn;
+    staggerOut: typeof staggerOut;
+    fade: typeof fade;
+    crossfade: typeof crossfade;
+    heroExpand: typeof heroExpand;
+    heroCollapse: typeof heroCollapse;
+};