phoria2 1.1.0 → 1.3.0

package/dist/types/View.d.ts

@@ -16,6 +16,7 @@ import type { ToneMapping, BloomOptions } from './webgl/WebGLRenderer.js';
 import type { CameraOptions } from './scene/cameras.js';
 import type { ColorInput, Vec3Input } from './types.js';
 import type { Node } from './scene/Node.js';
+import type { KeyboardOptions } from './keyboard.js';
 export type RenderMode = 'auto' | 'always' | 'manual';
 export type ViewOptions = {
     /**
@@ -106,6 +107,24 @@ export type ViewOptions = {
      * longest frame step in seconds, so a background tab doesn't jump (default 0.1)
      */
     maxDelta?: number;
+    /**
+     * cut motion short, for people it makes unwell: frame() jumps rather
+     * than glides, auto-rotation holds, and charts change at once with their flows still. Default 'auto': as the
+     * system's setting (prefers-reduced-motion), followed as it changes
+     */
+    reducedMotion?: 'auto' | boolean;
+    /**
+     * use without a pointer: the canvas joins the page's tab order, and
+     * the arrow keys step through what can be hovered or clicked - each with the hover tint, the tooltip and hover
+     * handlers - with Enter or Space to click and Escape to leave. A screen reader hears each one. { label: (hit) =>
+     * text } says what it hears (default: the tooltip's text, the data, or the name). Default false
+     */
+    keyboard?: boolean | KeyboardOptions;
+    /**
+     * what the view shows, for screen readers: the canvas's label. With keyboard
+     * on and no description, one is made from the scene (charts describe themselves)
+     */
+    description?: string | null;
 };
 export type ViewEvent = 'click' | 'hover';
 export type ViewHandler = (hit: Hit | null, event: PointerEvent | MouseEvent | null) => void;
@@ -168,6 +187,22 @@ export declare class View {
     get highlight(): Color | null;
     /** @param {ColorInput | null} v */
     set highlight(v: ColorInput | null);
+    /**
+     * Is motion cut short - glides, auto-rotation, chart transitions? Set true or false, or 'auto' (the
+     * default) to follow the system's setting. Read it for motion of your own, such as a timeline.
+     * @returns {boolean}
+     */
+    get reducedMotion(): boolean;
+    /** @param {'auto' | boolean} v */
+    set reducedMotion(v: 'auto' | boolean);
+    /**
+     * What the view shows, for screen readers - the canvas's label - or null. With keyboard on and no
+     * description, one is made from the scene.
+     * @returns {string | null}
+     */
+    get description(): string | null;
+    /** @param {string | null} v */
+    set description(v: string | null);
     /** Canvas width in CSS pixels. */
     get width(): number;
     /** Canvas height in CSS pixels. */
@@ -220,7 +255,8 @@ export declare class View {
      * @param {Node | Box3} [target] (default the scene)
      * @param {{ padding?: number, direction?: CameraPreset | Vec3Input, duration?: number }} [options] padding is
      *   the margin around it, as a fraction of its size: 0 is a tight fit, 0.2 (the default) leaves a fifth.
-     *   duration is in seconds (default 0: straight there); a press or the wheel stops the glide
+     *   duration is in seconds (default 0: straight there); a press or the wheel stops the glide, and with
+     *   reducedMotion it goes straight there
      * @returns {this}
      */
     frame(target?: Node | Box3, { padding, direction: towards, duration }?: {
@@ -228,6 +264,28 @@ export declare class View {
         direction?: CameraPreset | Vec3Input;
         duration?: number;
     }): this;
+    /**
+     * Where frame() would put the camera, without moving it: its position, target and - for an
+     * orthographic camera - height, or null when there is nothing to frame. For a camera of your own
+     * that eases after something moving rather than jumping each frame:
+     *
+     *     const aim = view.framing(debris)
+     *     if (aim) {
+     *       view.camera.position.lerp(aim.position, 0.1)
+     *       view.camera.target.lerp(aim.target, 0.1)
+     *     }
+     * @param {Node | Box3} [target] (default the scene)
+     * @param {{ padding?: number, direction?: CameraPreset | Vec3Input }} [options] as frame()
+     * @returns {{ position: Vec3, target: Vec3, height?: number } | null}
+     */
+    framing(target?: Node | Box3, { padding, direction }?: {
+        padding?: number;
+        direction?: CameraPreset | Vec3Input;
+    }): {
+        position: Vec3;
+        target: Vec3;
+        height?: number;
+    } | null;
     /**
      * The nearest hit under a canvas position - CSS pixels from the canvas's top left, or a pointer
      * event. Found on the GPU from the last frame drawn (one pass, however many instances), then made
@@ -281,6 +339,17 @@ export declare class View {
         width: number;
         height: number;
     } | null;
+    /**
+     * Everything inside an area of the canvas, nearest first: a box `{ x, y, width, height }` or a
+     * lasso of `[x, y]` points, CSS pixels from the canvas's top left. Each point, instance and line
+     * segment is its own hit, found by where it is (a mesh by its middle) - hidden behind others or
+     * not - so a box dragged over a scatter selects that region of it.
+     *
+     *     const picked = view.pickArea({ x: 40, y: 30, width: 200, height: 120 }).map((h) => h.datum)
+     * @param {import('./area.js').PickArea} area
+     * @returns {Hit[]}
+     */
+    pickArea(area: import('./area.js').PickArea): Hit[];
     /** Every hit under a canvas position, nearest first. @param {number | MouseEvent} x @param {number} [y] @returns {Hit[]} */
     pickAll(x: number | MouseEvent, y?: number): Hit[];
     /**

package/dist/types/area.d.ts

@@ -0,0 +1,18 @@
+import type { Hit } from './Raycaster.js';
+import type { Node } from './scene/Node.js';
+import type { Camera } from './scene/cameras.js';
+export type PickArea = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | [number, number][];
+/**
+ * Everything in the scene the camera shows, pickable, whose place falls inside the area - nearest
+ * the camera first.
+ * @param {Node} scene @param {Camera} camera @param {Float32Array} viewProjection
+ * @param {number} width @param {number} height the canvas, CSS pixels
+ * @param {PickArea} area
+ * @returns {Hit[]}
+ */
+export declare function pickArea(scene: Node, camera: Camera, viewProjection: Float32Array, width: number, height: number, area: PickArea): Hit[];

package/dist/types/charts/Chart.d.ts

@@ -45,6 +45,13 @@ export declare class Chart extends Group {
     filter(fn: ((row: any) => boolean) | null): this;
     /** One line about this chart, for view.explain(). */
     explain(): string;
+    /**
+     * One sentence about this chart for screen readers - the spec's description, or its title and what
+     * it shows: "Sales by month: bar chart of 12 rows by Month, Sales". A View with keyboard: true labels
+     * its canvas with this.
+     * @returns {string}
+     */
+    summary(): string;
     toJSON(): Record<string, unknown>;
     /** A new chart from the same spec and transform. @returns {any} */
     clone(): any;

package/dist/types/explain.d.ts

@@ -36,6 +36,9 @@ export type ExplainInfo = {
         click: number;
         tooltip: boolean;
         highlight: boolean;
+        keyboard?: boolean;
+        reducedMotion?: boolean;
+        description?: string | null;
     };
     /**
      * lines from nodes that describe themselves, such as charts

package/dist/types/frame.d.ts

@@ -146,6 +146,11 @@ export type FrameLabel = {
      * in front of the camera and inside the view
      */
     visible: boolean;
+    /**
+     * how far zoomed in at the point: half the view's height, in world units, is 1 / scale -
+     * the layer turns it into pixels to one world unit, for minScale
+     */
+    scale: number;
 };
 export type ShadowFrame = {
     light: FrameLight;
@@ -353,6 +358,8 @@ export type FrameDescription = {
  * @property {[number, number]} ndc [x, y] in -1..1
  * @property {number} depth
  * @property {boolean} visible in front of the camera and inside the view
+ * @property {number} scale how far zoomed in at the point: half the view's height, in world units, is 1 / scale -
+ *   the layer turns it into pixels to one world unit, for minScale
  */
 /**
  * The shadow-casting directional light's view of the scene: what to draw into its depth map.

package/dist/types/geometry/Geometry.d.ts

@@ -21,6 +21,19 @@ export type GeometryOptions = {
      * rgb per vertex, sRGB 0-1 like every colour input
      */
     colors?: ArrayLike<number>;
+    /**
+     * points: one per vertex, a multiple of the material's size
+     */
+    sizes?: ArrayLike<number>;
+    /**
+     * points: one per vertex, 0-1, multiplying the material's opacity
+     */
+    opacities?: ArrayLike<number>;
+    /**
+     * points: one per vertex, radians anticlockwise on screen - turns
+     * each point's texture
+     */
+    angles?: ArrayLike<number>;
     /**
      * vertex indices; triangles for meshes, pairs for lines
      */
@@ -38,6 +51,9 @@ export declare class Geometry {
     /** @type {Float32Array | null} */ uvs: Float32Array | null;
     /** A second UV set, for baked occlusion and light maps. @type {Float32Array | null} */ uvs2: Float32Array | null;
     /** @type {Float32Array | null} */ colors: Float32Array | null;
+    /** Points: each one's size, as a multiple of the material's. @type {Float32Array | null} */ sizes: Float32Array | null;
+    /** Points: each one's opacity, 0-1, times the material's. @type {Float32Array | null} */ opacities: Float32Array | null;
+    /** Points: each one's turn on screen, in radians anticlockwise. @type {Float32Array | null} */ angles: Float32Array | null;
     /** @type {Uint16Array | Uint32Array | null} */ indices: Uint16Array | Uint32Array | null;
     /**
      * Draw only the first `drawCount` vertices (indices, when indexed), or all of them when null -
@@ -56,7 +72,9 @@ export declare class Geometry {
     constructor(options: GeometryOptions);
     /**
      * xyz per vertex. Computed (smooth) from the triangles on first read when not supplied, so
-     * points and lines - whose geometry has no triangles - never pay for them.
+     * points and lines - whose geometry has no triangles - never pay for them - and computed again after
+     * needsUpdate(), so they follow positions edited in place. Normals that were supplied, assigned or
+     * made by calling computeNormals() are kept as they are.
      * @type {Float32Array}
      */
     get normals(): Float32Array;
@@ -77,7 +95,11 @@ export declare class Geometry {
     get drawnVertices(): number;
     /** Local space bounds, cached until needsUpdate(). @returns {Box3} */
     get bounds(): Box3;
-    /** Call after editing the arrays in place. It is no longer what its generator made, so toJSON() saves the arrays. @returns {this} */
+    /**
+     * Call after editing the arrays in place. It is no longer what its generator made, so toJSON() saves
+     * the arrays; normals that were worked out on first read are worked out again on the next.
+     * @returns {this}
+     */
     needsUpdate(): this;
     /**
      * Compute vertex normals from the triangles. Smooth normals average the faces sharing each vertex;

package/dist/types/index.d.ts

@@ -37,6 +37,7 @@ export type RenderMode = import('./View.js').RenderMode;
 export type CameraPreset = import('./presets.js').CameraPreset;
 export type TooltipContent = import('./tooltip.js').TooltipContent;
 export type Hit = import('./Raycaster.js').Hit;
+export type PickArea = import('./area.js').PickArea;
 export type LabelPlacement = import('./scene/drawables.js').LabelPlacement;
 export type LabelPlace = import('./scene/drawables.js').LabelPlace;
 export type InstanceLabels = import('./scene/drawables.js').InstanceLabels;
@@ -49,6 +50,7 @@ export type ImageOptions = import('./snapshot.js').ImageOptions;
 /** @typedef {import('./presets.js').CameraPreset} CameraPreset */
 /** @typedef {import('./tooltip.js').TooltipContent} TooltipContent */
 /** @typedef {import('./Raycaster.js').Hit} Hit */
+/** @typedef {import('./area.js').PickArea} PickArea */
 /** @typedef {import('./scene/drawables.js').LabelPlacement} LabelPlacement */
 /** @typedef {import('./scene/drawables.js').LabelPlace} LabelPlace */
 /** @typedef {import('./scene/drawables.js').InstanceLabels} InstanceLabels */

package/dist/types/keyboard.d.ts

@@ -0,0 +1,48 @@
+import type { Hit } from './Raycaster.js';
+import type { TooltipContent } from './tooltip.js';
+import type { Node } from './scene/Node.js';
+import type { View } from './View.js';
+export type KeyboardOptions = {
+    /**
+     * what a screen reader says for each thing stepped to (default: the
+     * tooltip's text, then its data, then the node's name)
+     */
+    label?: (hit: Hit) => string;
+};
+export type KeyboardHooks = {
+    /**
+     * show this as hovered, or nothing
+     */
+    focus: (hit: Hit | null) => void;
+    /**
+     * click it
+     */
+    press: (hit: Hit) => void;
+    /**
+     * the tooltip's content for it, if there is a tooltip
+     */
+    tooltip: (hit: Hit) => TooltipContent;
+    /**
+     * does the View itself answer hovers or clicks (a tooltip, handlers)?
+     */
+    viewWide: () => boolean;
+};
+export type Item = {
+    node: Node;
+    index: number | null;
+    whole: Node | null;
+};
+export declare class Keyboard {
+    #private;
+    /** @param {View} view @param {KeyboardHooks} hooks @param {KeyboardOptions} options */
+    constructor(view: View, hooks: KeyboardHooks, options: KeyboardOptions);
+    /**
+     * The canvas's label for screen readers: the View's description, or - when it has none - one made
+     * from the scene: what its charts show, and how many things there are to step through.
+     * @param {string | null} text
+     */
+    setDescription(text: string | null): void;
+    /** Step off whatever was stepped to: the pointer has taken over, or focus has gone. */
+    clear(): void;
+    dispose(): void;
+}

package/dist/types/labels.d.ts

@@ -18,6 +18,10 @@ export type LabelStats = {
      * behind the camera or outside the view
      */
     offscreen: number;
+    /**
+     * hidden because the view isn't zoomed in to their minScale
+     */
+    zoomedOut: number;
 };
 export type Entry = {
     el: HTMLDivElement;

package/dist/types/material/Material.d.ts

@@ -211,6 +211,18 @@ export type MaterialOptions = {
      * Lines: width in pixels (default 1)
      */
     width?: number;
+    /**
+     * Lines: dashed, with dashes this long in the model's units; 0 is solid (default 0)
+     */
+    dash?: number;
+    /**
+     * Lines: the gaps between dashes; 0 is as long as the dashes (default 0)
+     */
+    gap?: number;
+    /**
+     * Lines: moves the dashes along the lines - animate it for flow (default 0)
+     */
+    dashOffset?: number;
 };
 /**
  * The one material: what a surface looks like. Plain objects passed as a `material` become
@@ -275,6 +287,9 @@ export declare class Material {
     /** @type {number} */ size: number;
     /** @type {boolean} */ sizeAttenuation: boolean;
     /** @type {number} */ width: number;
+    /** Lines: dash length in the model's units; 0 is solid. @type {number} */ dash: number;
+    /** Lines: gap length; 0 is the dash's. @type {number} */ gap: number;
+    /** Lines: how far the dashes have moved along. @type {number} */ dashOffset: number;
     /** @param {MaterialOptions} [options] */
     constructor(options?: MaterialOptions);
     /** Base colour; assign any colour input. @returns {Color} */

package/dist/types/material/Texture.d.ts

@@ -64,9 +64,15 @@ export type TextureOptions = {
      */
     flipY?: boolean;
 };
+export type TextureRegion = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 /**
  * An image for a material map. A video's frames upload by themselves as it plays; after drawing on
- * a canvas, call `needsUpdate()`.
+ * a canvas, call `needsUpdate()` - with the rectangle drawn in, to send only that.
  */
 export declare class Texture {
     #private;
@@ -114,7 +120,17 @@ export declare class Texture {
     /** 'srgb' for colour (decoded to linear by the GPU), 'linear' for data such as normals and roughness. Call needsUpdate() after changing it. @returns {'srgb' | 'linear'} */
     get colorSpace(): 'srgb' | 'linear';
     set colorSpace(v: 'srgb' | 'linear');
-    needsUpdate(): this;
+    /**
+     * Upload the image again, after drawing on it (a canvas) or changing its pixels. Give the
+     * rectangle that changed - in the image's pixels, from its top left - and only that is sent: for a
+     * big canvas drawn on a little at a time, far less to send each frame.
+     *
+     *     ctx.fillRect(x, y, 20, 20)
+     *     texture.needsUpdate({ x, y, width: 20, height: 20 })
+     * @param {TextureRegion} [region]
+     * @returns {this}
+     */
+    needsUpdate(region?: TextureRegion): this;
     /** Release the GPU copy. @returns {void} */
     dispose(): void;
     /** A description (url plus options that differ from the defaults), or null for an in-memory image. */

package/dist/types/particles/Emitter.d.ts

@@ -61,6 +61,28 @@ export type EmitterOptions = NodeOptions & SpawnOptions & {
     frustumCulled?: boolean;
     renderOrder?: number;
     onParticle?: ((p: Particle) => boolean | void) | null;
+    sort?: boolean;
+} & LookOptions;
+export type LookOptions = {
+    /**
+     * a multiple of the material's size, or several each particle goes
+     * through over its life - [0.5, 3] for smoke that billows out (default 1)
+     */
+    size?: number | number[];
+    /**
+     * each particle's size varies by up to this share either way, 0-1 (default 0)
+     */
+    sizeSpread?: number;
+    /**
+     * 0-1, or several each particle goes through - [0, 1, 0] fades in
+     * and out (default 1)
+     */
+    opacity?: number | number[];
+    /**
+     * radians per second: a number turns each particle up to that
+     * fast either way, [min, max] a range. Spinning particles start at a random angle (default 0)
+     */
+    spin?: number | [number, number];
 };
 /**
  * Particles drawn as points. Add it to a scene and it runs itself.
@@ -102,11 +124,11 @@ export declare class Emitter extends Points {
     /**
      * Change several settings at once - a preset, say. Vectors are copied into the emitter's own,
      * so anything bound to `emitter.gravity` and friends stays bound. Live particles carry on.
-     * @param {SpawnOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
+     * @param {SpawnOptions & LookOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
      *   onParticle?: ((p: Particle) => boolean | void) | null }} options
      * @returns {this}
      */
-    set(options: SpawnOptions & {
+    set(options: SpawnOptions & LookOptions & {
         rate?: number;
         gravity?: Vec3Input;
         drag?: number;
@@ -121,6 +143,21 @@ export declare class Emitter extends Points {
     set color(v: ColorInput | ColorInput[]);
     /** @returns {[number, number, number][]} */
     get color(): [number, number, number][];
+    /** Each particle's size over its life, as multiples of the material's. @param {number | number[]} v */
+    set size(v: number | number[]);
+    /** @returns {number[]} */
+    get size(): number[];
+    /** How much each particle's size varies, 0-1 either way. @param {number} v */
+    set sizeSpread(v: number);
+    get sizeSpread(): number;
+    /** Each particle's opacity over its life. @param {number | number[]} v */
+    set opacity(v: number | number[]);
+    /** @returns {number[]} */
+    get opacity(): number[];
+    /** How fast particles turn, radians per second, as a [min, max] range. @param {number | [number, number]} v */
+    set spin(v: number | [number, number]);
+    /** @returns {[number, number]} */
+    get spin(): [number, number];
     /**
      * Birth `count` particles at once - explosions, splashes. Options override the emitter's own
      * spawn settings for this burst only.

package/dist/types/scene/Node.d.ts

@@ -5,7 +5,7 @@ import { Mat4 } from '../value/Mat4.js';
 import { Quat } from '../value/Quat.js';
 import { Vec3 } from '../value/Vec3.js';
 import { Clip } from '../clip.js';
-import type { ColorInput, Vec3Input } from '../types.js';
+import type { ColorInput, QuatInput, Vec3Input } from '../types.js';
 import type { Hit } from '../Raycaster.js';
 import type { Camera } from './cameras.js';
 import type { ClipOptions } from '../clip.js';
@@ -59,9 +59,9 @@ export type NodeOptions = {
      */
     rotation?: Vec3Input | Euler;
     /**
-     * [x, y, z, w] - instead of rotation
+     * [x, y, z, w] or { x, y, z, w } - instead of rotation
      */
-    quaternion?: ArrayLike<number>;
+    quaternion?: QuatInput;
     /**
      * a number scales uniformly
      */
@@ -87,9 +87,10 @@ export type NodeOptions = {
      */
     tooltip?: ((hit: Hit) => any) | null;
     /**
-     * hover tint for this subtree, over the View's
+     * hover tint for this subtree, over the View's; false for none - a
+     * floor or wall left plain under a View that tints everything else (null: the View's)
      */
-    highlight?: ColorInput | null;
+    highlight?: ColorInput | null | false;
     /**
      * hovering any part of this subtree tints all of it, as one thing - a
      * piece of furniture, a machine - rather than just the part under the pointer (default false)
@@ -127,7 +128,7 @@ export type NodeOptions = {
      */
     clip?: ClipOptions | Clip | null;
 };
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 /** @import { Hit } from '../Raycaster.js' */
 /** @import { Camera } from './cameras.js' */
 /** @import { ClipOptions } from '../clip.js' */
@@ -157,7 +158,7 @@ export type NodeOptions = {
  * @property {string} [name]
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion] [x, y, z, w] - instead of rotation
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - instead of rotation
  * @property {Vec3Input | number} [scale] a number scales uniformly
  * @property {boolean} [visible]
  * @property {boolean} [pickable] include in view.pick() (default true)
@@ -167,7 +168,8 @@ export type NodeOptions = {
  * @property {UpdateHandler | UpdateHandler[]} [onUpdate]
  * @property {((hit: Hit) => any) | null} [tooltip] tooltip for anything picked in this subtree; nearer nodes win, and
  *   all win over the View's
- * @property {ColorInput | null} [highlight] hover tint for this subtree, over the View's
+ * @property {ColorInput | null | false} [highlight] hover tint for this subtree, over the View's; false for none - a
+ *   floor or wall left plain under a View that tints everything else (null: the View's)
  * @property {boolean} [highlightWhole] hovering any part of this subtree tints all of it, as one thing - a
  *   piece of furniture, a machine - rather than just the part under the pointer (default false)
  * @property {((hit: Hit | null) => void) | null} [onHover] called as the thing under the pointer in this subtree changes
@@ -244,14 +246,17 @@ export declare class Node {
     set rotation(v: Vec3Input);
     /** Kept in sync with rotation. Assigning copies, normalised. @returns {Quat} */
     get quaternion(): Quat;
-    /** @param {ArrayLike<number>} v */
-    set quaternion(v: ArrayLike<number>);
+    /** @param {QuatInput} v */
+    set quaternion(v: QuatInput);
     /** @param {NodeOptions} [options] */
     constructor(options?: NodeOptions);
-    /** Hover tint for this subtree, over the View's; set any colour, or null. @returns {Color | null} */
-    get highlight(): Color | null;
-    /** @param {ColorInput | null} value */
-    set highlight(value: ColorInput | null);
+    /**
+     * Hover tint for this subtree, over the View's: a colour, false for none, or null to use the View's.
+     * @returns {Color | null | false}
+     */
+    get highlight(): Color | null | false;
+    /** @param {ColorInput | null | false} value */
+    set highlight(value: ColorInput | null | false);
     /**
      * The section plane cutting this subtree, or null. Set { normal, offset, cap }, a Clip or null;
      * move the cut by changing its offset or normal in place.