@oeave/bakery3 0.2.0 → 0.3.0

package/dist/hotspots/index.d.ts

@@ -1,32 +1,117 @@
-import { Group, Camera, Vector3, Object3D } from 'three';
+import { Group, Vector3, Camera, Material, Color, Object3D, Intersection } from 'three';
+import { T as Timeline } from '../timeline-ChwgD7bT.js';
+import '../animation-B1h0Ryvj.js';
 
 /**
  * The implementation behind `@oeave/bakery3/hotspots`. `index.ts` lists what
- * is public; the orb's parts and the brand color are here for the SDK's own
- * pointer handling and the monorepo's tools (`internal.ts`).
+ * is public; the parts, the pose and the brand color are here for the SDK's
+ * own pointer handling and the monorepo's tools (`internal.ts`).
+ *
+ * One function decides how a hotspot looks: `poseOf` turns its state (how far
+ * it has appeared, how far it is open, the hover, the label, the pulse) into
+ * numbers on its parts. The live hotspot applies them every frame;
+ * `animateHotspots` samples them at every frame of a timeline and writes them
+ * as tracks, which is how the render plays the same motion the viewport
+ * showed. There is no second animation system to drift from the first.
  */
 
 /** `[x, y, z]`, in meters: the protocol's own vector shape. */
 type Vec3 = [number, number, number];
+/**
+ * Where a hotspot is headed. `hidden` is not there at all, `closed` is the
+ * resting dot, `open` is the dot as it looks while its panel is showing.
+ */
+type HotspotState = 'hidden' | 'closed' | 'open';
+/** Where a hotspot is now, including the moves between states. */
+type HotspotPhase = 'hidden' | 'entering' | 'closed' | 'opening' | 'open' | 'closing' | 'leaving';
+/**
+ * The built-in looks.
+ *
+ * - `orb`: a glowing core in a soft halo that breathes.
+ * - `ring`: a small glowing core inside a ring.
+ * - `glass`: a clear glass bead with a glowing core inside.
+ * - `solid`: a glossy colored bead that barely glows.
+ */
+type HotspotPreset = 'orb' | 'ring' | 'glass' | 'solid';
+/** The meshes a hotspot can be made of; which exist depends on the preset. */
+type HotspotPartName = 'core' | 'halo' | 'ring' | 'shell' | 'tether' | 'dot';
+/**
+ * When the label beside a hotspot shows.
+ *
+ * - `never` (default): the hotspot draws no text.
+ * - `always`: whenever the hotspot is there.
+ * - `open`: while it is open.
+ * - `hover`: while the pointer is over it, and while it is open. A timeline
+ *   hovers it with a `hover` event.
+ */
+type HotspotLabelShow = 'never' | 'always' | 'open' | 'hover';
+/** Which side of the orb the label is on. `auto` moves it off a screen edge. */
+type HotspotLabelSide = 'auto' | 'left' | 'right';
+/**
+ * A material of your own for a part, or a function asked once per part that
+ * returns one (or `undefined` to keep the preset's). A node material with an
+ * `emissiveNode` should multiply it by `bakeryEmissiveIntensity()` from
+ * `@oeave/bakery3/tsl`, so the glow the state animates reaches it in the
+ * viewport as it does in the render.
+ */
+type HotspotMaterial = Material | ((part: {
+    name: HotspotPartName;
+    color: Color;
+}) => Material | undefined);
 type HotspotOptions = {
     /** Stable identity: it names the group and travels with `hotspotSpecOf`. */
     id: string;
-    /** A caption for the app to show; the orb itself draws no text. */
+    /** The hotspot's caption: the text of its label, and yours to show in your app. */
     label?: string;
-    /** Where the orb is, in the parent's space (world space without a parent). */
-    position: Vec3 | Vector3;
     /**
-     * A surface point on the model, in the same space as `position`. When given
-     * the hotspot is anchored: a thin line is drawn from here to the orb.
+     * Where the orb is, in the parent's space (world space without a parent).
+     * With an `anchor`, you can give `direction` and `distance` instead.
+     */
+    position?: Vec3 | Vector3;
+    /**
+     * A point on the model's surface, in the same space as `position`. When
+     * given, the hotspot is tied to it: a thin line runs from a small dot on
+     * the surface out to the orb.
      */
     anchor?: Vec3 | Vector3;
+    /**
+     * Which way the orb stands off the anchor, in the parent's space. Default:
+     * toward `position`, or straight up.
+     */
+    direction?: Vec3 | Vector3;
+    /** How far the orb stands off the anchor, in meters. Default: to `position`, or 0.1. */
+    distance?: number;
     /**
      * Attach to this object so the hotspot follows it. Without one the caller
      * adds `hotspot.object` to the scene themselves.
      */
     parent?: Object3D;
-    /** CSS color of the orb, halo and line. Default the brand cyan, `#33d1ff`. */
+    /**
+     * Whether the hotspot shows up in renders. Default false: a hotspot is
+     * viewport UI and the capture walks past it. With true it is part of the
+     * scene, its glow lights the model in the render, and `animateHotspots`
+     * can play its states in a video.
+     */
+    render?: boolean;
+    /** The look. Default `orb`. */
+    style?: HotspotPreset;
+    /** Any CSS color. Default the brand cyan, `#33d1ff`. */
     color?: string;
+    /** The color it turns while open. Default: it keeps `color`. */
+    openColor?: string;
+    /**
+     * How bright the glowing parts are (emission strength). Default 3 for
+     * `orb` and `ring`, 6 for `glass`, 0.2 for `solid`; 1 for a hotspot that
+     * does not render, so the color on screen is exactly `color`.
+     */
+    intensity?: number;
+    /**
+     * How much the hotspot lights the model around it while open: a point light
+     * at the orb, in candela. A closed hotspot gives a third of it. Default 0.
+     */
+    glow?: number;
+    /** Your own material for some or all parts, a TSL node material included. */
+    material?: HotspotMaterial;
     /**
      * How the orb is sized. `screen` (default) keeps it the same size on screen
      * wherever it is: `size` is then a fraction of the viewport height, and
@@ -34,33 +119,86 @@ type HotspotOptions = {
      * `world` is a fixed radius in meters, which shrinks with distance.
      */
     sizing?: 'screen' | 'world';
-    /** Orb radius: a fraction of viewport height (`screen`, default 0.012) or meters (`world`, default 0.03). */
+    /** Orb radius: a fraction of viewport height (`screen`, default 0.015) or meters (`world`, default 0.03). */
     size?: number;
-    /** Whether the halo breathes. Default true. */
-    pulse?: boolean;
+    /** Whether the closed hotspot breathes, or how fast, in cycles a second. Default true (0.7). */
+    pulse?: boolean | number;
+    /** Draw the line to the anchor. Default true when anchored. */
+    tether?: boolean;
+    /** Draw the small dot on the anchor. Default true when anchored. */
+    dot?: boolean;
+    /** When the label beside the orb shows. Default `never`. */
+    showLabel?: HotspotLabelShow;
+    /** Which side the label is on. Default `auto`: right, or left near the right edge. */
+    labelSide?: HotspotLabelSide;
+    /**
+     * The label's CSS font. Its pixel size is how sharp the label is, not how
+     * big: the label is sized to the orb. Default the platform's UI face at 40px.
+     */
+    labelFont?: string;
+    /** The label's text color. Default white. */
+    labelColor?: string;
+    /** The label's background color. Default near black. */
+    labelBackground?: string;
+    /** How opaque the shown label is. Default 0.9. */
+    labelOpacity?: number;
+    /** The label's height, as a multiple of its default. Default 1. */
+    labelSize?: number;
+    /** The state it starts in, already there. Default `closed`. */
+    state?: HotspotState;
+    /** Seconds each move takes. Default 0.8 to appear, 0.45 to open, 0.3 for the label. */
+    timing?: {
+        appear?: number;
+        open?: number;
+        label?: number;
+    };
 };
 type Hotspot = {
     readonly id: string;
     readonly label: string | undefined;
     /**
-     * The group holding everything (the orb, and the tether when anchored),
-     * placed at the orb; excluded from capture, named `bakery3-hotspot-<id>`.
+     * The group holding everything, placed at the anchor (at the orb when
+     * there is none), named `bakery3-hotspot-<id>`.
      */
     readonly object: Group;
-    /** Whether `setSelected(true)` is in effect. */
+    /** The state it is headed for. */
+    readonly state: HotspotState;
+    /** Where it is now, moves included. */
+    readonly phase: HotspotPhase;
+    /** Whether it is open, or opening. */
     readonly selected: boolean;
-    /** Whether the cursor is over it; set by `attachHotspots`. */
+    /** Whether it is hovered, by the pointer or by `setHovered()`. */
     readonly hovered: boolean;
+    /** Meters from the anchor to the orb. */
+    readonly distance: number;
+    /** The side the label is on, or headed for. */
+    readonly labelSide: 'left' | 'right';
+    /** True while `animateHotspots` drives it: `update()` then leaves it to the timeline. */
+    readonly driven: boolean;
+    /** Move to a state, animated unless `instant`. */
+    setState(state: HotspotState, options?: {
+        instant?: boolean;
+    }): void;
+    /** `setState('open')` or `setState('closed')`. */
     setSelected(on: boolean): void;
-    /** Advance the pulse; `seconds` is any monotonic clock. */
+    /** Hover it, or stop: what `attachHotspots` does as the pointer moves. */
+    setHovered(on: boolean): void;
+    /** Change the label's text. */
+    setLabel(text: string): void;
+    /** Stand the orb this far off the anchor, in meters. */
+    setDistance(meters: number): void;
+    /** Point the orb this way from the anchor (parent space). */
+    setDirection(direction: Vec3 | Vector3): void;
+    /** Advance the moves and the pulse; `seconds` is any monotonic clock. */
     update(seconds: number): void;
     /**
-     * Scale the orb so it projects to its `size` for this camera. Called by
-     * `attachHotspots.update()`; a host without pointer handling calls it
-     * itself once per frame. No-op for `sizing: 'world'`.
+     * Turn the orb and its label to face this camera, put the label on the
+     * side with room, and, for a screen-sized orb, scale it to its `size`.
+     * Called by `attachHotspots.update()`; a host without pointer handling
+     * calls it itself once per frame, before `update()`.
      */
     fit(camera: Camera): void;
-    /** Detach from its parent and free every geometry and material. */
+    /** Detach from its parent and free every geometry, material and texture. */
     dispose(): void;
 };
 /** A hotspot as data, in world space: what to keep with a capture. */
@@ -71,29 +209,97 @@ type HotspotSpec = {
     anchor?: Vec3;
 };
 declare function createHotspot(options: HotspotOptions): Hotspot;
+/**
+ * Where to put a hotspot for a click on a model: the surface point, and the
+ * way out of the surface there.
+ *
+ * `along: 'normal'` (default) stands the orb off the face that was hit;
+ * `'center'` stands it away from `center` (the model's middle) through the
+ * point, which keeps orbs on a curved or noisy surface from pointing every
+ * which way. Both are returned in `space`'s coordinates (world without one),
+ * ready to pass as `anchor` and `direction` with `parent: space`.
+ */
+declare function hotspotFromHit(hit: Intersection, options?: {
+    along?: 'normal' | 'center';
+    center?: Vector3;
+    space?: Object3D;
+}): {
+    anchor: Vector3;
+    direction: Vector3;
+};
 /**
  * A hotspot as plain data, in world space, ready for `productState`.
  *
  * Reads through the parents so a hotspot riding on a product that has been
- * moved reports where it actually is, not where it was authored.
+ * moved reports where it actually is, not where it was authored. The
+ * position is where the orb stands once it is out, whatever it is doing.
  */
 declare function hotspotSpecOf(hotspot: Hotspot): HotspotSpec;
+/** One change, at a time on the timeline: a state, a hover, or both. */
+type HotspotEvent = {
+    /** The hotspot, or its id. */
+    hotspot: Hotspot | string;
+    /** Seconds from the start of the timeline. */
+    at: number;
+    state?: HotspotState;
+    /**
+     * The pointer moves onto it (true) or off (false): the hover look, and the
+     * label of a hotspot that shows it on hover.
+     */
+    hover?: boolean;
+};
+type AnimateHotspotsOptions = {
+    /** The changes, in any order. */
+    events?: HotspotEvent[];
+    /**
+     * Where each hotspot is at time zero, already there: one state for all, or
+     * one per id. Default `hidden`, so a clip opens on the model alone.
+     */
+    initial?: HotspotState | Record<string, HotspotState>;
+    /**
+     * Round each pulse to whole breaths over the timeline, so a clip that loops
+     * does not hitch at the seam. Default true.
+     */
+    loop?: boolean;
+};
+type AnimatedHotspots = {
+    /** How many tracks were written. */
+    readonly tracks: number;
+    /** Remove the tracks and hand the hotspots back to their own `update()`. */
+    release(): void;
+};
+/**
+ * Play hotspot states on a timeline, so a video renders them.
+ *
+ * Every frame of the timeline is posed by the same function the live hotspot
+ * uses, and written as ordinary tracks (position, rotation, scale, emission,
+ * opacity, the glow light's intensity), so `seek()` previews exactly what the
+ * render traces. The camera at each frame decides what a live camera would:
+ * the size of a screen-sized orb, which way the rig faces, and which side the
+ * label is on. Author the camera first. Calling it again on the same timeline
+ * replaces what it wrote. Hotspots must be made with `render: true`.
+ *
+ * While animated, a hotspot's `update()` and `fit()` stand aside.
+ */
+declare function animateHotspots(timeline: Timeline, hotspots: Hotspot[], options?: AnimateHotspotsOptions): AnimatedHotspots;
+/** Undo `animateHotspots` on a timeline: its tracks go, the hotspots are live again. */
+declare function releaseHotspots(timeline: Timeline): void;
 type AttachHotspotsOptions = {
     hotspots: Hotspot[];
     camera: Camera;
     /** The renderer's canvas, or whatever element receives the pointer. */
     domElement: HTMLElement;
-    /** Selection changed: the hotspot now selected, or null when cleared. */
+    /** Selection changed: the hotspot now open, or null when cleared. */
     onSelect?(hotspot: Hotspot | null): void;
     /** The pointer moved onto (or off) a hotspot. */
     onHover?(hotspot: Hotspot | null): void;
 };
 type AttachedHotspots = {
-    /** Advance every hotspot's pulse. Call once per frame. */
+    /** Fit and advance every hotspot. Call once per frame. */
     update(seconds: number): void;
-    /** The hotspot currently selected, if any. */
+    /** The hotspot currently open, if any. */
     readonly selected: Hotspot | null;
-    /** Select (or clear) programmatically; fires `onSelect` like a click would. */
+    /** Open one (or close all) programmatically; fires `onSelect` like a click would. */
     select(hotspot: Hotspot | null): void;
     /** Remove the listeners. Does not dispose the hotspots. */
     dispose(): void;
@@ -101,11 +307,11 @@ type AttachedHotspots = {
 /**
  * Wire hover and click for a set of hotspots on one canvas.
  *
- * Raycasts the orbs (core and halo, so the target is a little generous) from
- * the pointer through `camera`; sets `cursor: pointer` over one; toggles
- * selection on click, one at a time. Nothing here is a render loop: call
- * `update()` from yours.
+ * Raycasts the heads (core and halo, ring or glass, and the label, so the
+ * target is a little generous) from the pointer through `camera`; sets
+ * `cursor: pointer` over one; opens it on click and closes the one that was
+ * open. Nothing here is a render loop: call `update()` from yours.
  */
 declare function attachHotspots(options: AttachHotspotsOptions): AttachedHotspots;
 
-export { type AttachHotspotsOptions, type AttachedHotspots, type Hotspot, type HotspotOptions, type HotspotSpec, type Vec3, attachHotspots, createHotspot, hotspotSpecOf };
+export { type AnimateHotspotsOptions, type AnimatedHotspots, type AttachHotspotsOptions, type AttachedHotspots, type Hotspot, type HotspotEvent, type HotspotLabelShow, type HotspotLabelSide, type HotspotMaterial, type HotspotOptions, type HotspotPartName, type HotspotPhase, type HotspotPreset, type HotspotSpec, type HotspotState, type Vec3, animateHotspots, attachHotspots, createHotspot, hotspotFromHit, hotspotSpecOf, releaseHotspots };