phoria2 1.0.0 → 1.2.0

package/src/View.js

@@ -27,6 +27,7 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
 /** @import { CameraOptions } from './scene/cameras.js' */
 /** @import { ColorInput, Vec3Input } from './types.js' */
 /** @import { Node } from './scene/Node.js' */
+/** @import { Keyboard, KeyboardOptions } from './keyboard.js' */
 
 /**
  * @typedef {'auto' | 'always' | 'manual'} RenderMode
@@ -53,6 +54,8 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
  * @property {(hit: Hit) => TooltipContent} [tooltip] what to show for the thing under the pointer - see tooltip()
  * @property {number} [pixelRatio] default min(devicePixelRatio, 2)
  * @property {boolean} [antialias] (default true)
+ * @property {boolean} [outlineAntialias] soft-edged outlines with round corners (default: as antialias); change it
+ *   any time with view.renderer.outlineAntialias
  * @property {'auto' | 'own' | 'shared'} [context] which WebGL context draws it: 'own' gives the canvas one of
  *   its own; 'shared' draws with the page's one shared context and copies the picture over, so a page can hold
  *   any number of views (browsers allow about 16 live contexts). 'auto' (default): own for the first four
@@ -63,13 +66,23 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
  *   additive points and lines (default off). true for the defaults, or { strength, radius, threshold }
  * @property {boolean} [autoLight] light a scene that has no lights, with one console note (default true)
  * @property {number} [maxDelta] longest frame step in seconds, so a background tab doesn't jump (default 0.1)
+ * @property {'auto' | boolean} [reducedMotion] 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
+ * @property {boolean | KeyboardOptions} [keyboard] 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
+ * @property {string | null} [description] 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)
  */
 
 /** @typedef {'click' | 'hover'} ViewEvent */
 /** @typedef {(hit: Hit | null, event: PointerEvent | MouseEvent | null) => void} ViewHandler */
 
 const OPTIONS = ['canvas', 'scene', 'camera', 'orbit', 'background', 'renderMode', 'framing', 'highlight', 'tooltip', 'pixelRatio',
-  'antialias', 'context', 'toneMapping', 'exposure', 'bloom', 'autoLight', 'maxDelta']
+  'antialias', 'outlineAntialias', 'context', 'toneMapping', 'exposure', 'bloom', 'autoLight', 'maxDelta', 'reducedMotion',
+  'keyboard', 'description']
 const FRAMING_OPTIONS = ['keep', 'aspect']
 const HINTS = {
   renderer: 'the View makes its renderer - read it from view.renderer',
@@ -88,6 +101,8 @@ const EVENT_HINTS = {
 }
 // how far the highlight colour is mixed in
 const HIGHLIGHT_AMOUNT = 0.45
+// what the keyboard's focus is tinted with when nothing says otherwise - focus must always show
+const FOCUS_COLOR = Color.fromInput('#ffcc00')
 // views that get a WebGL context of their own before 'auto' starts sharing one
 const OWN_CONTEXTS = 4
 // above this many things to test (instances, triangles, points, segments), picking goes to the
@@ -159,6 +174,15 @@ export class View {
   #tooltipClass = ''
   #tooltipLoading = false
   /** @type {Color | null} */ #highlight = null
+  /** @type {'auto' | boolean} */ #motion = 'auto'
+  // keyboard use: its code loads when asked for; the thing it has stepped to shows as hovered
+  /** @type {Keyboard | null} */ #keyboard = null
+  /** @type {Hit | null} */ #keyFocus = null
+  /** @type {string | null} */ #description = null
+  // the canvas had no role, so describing it gave it one - taken away again with the description
+  #gaveRole = false
+  // the system's prefers-reduced-motion, kept up to date
+  #systemReduced = false
   /** @type {{ x: number, y: number, clientX: number, clientY: number, event: PointerEvent } | null} */ #pointer = null
   #pickPending = false
   // a hover pick is out on the GPU
@@ -213,7 +237,7 @@ export class View {
     // the renderer checks these too; checked here, the error names the View
     if (options.exposure !== undefined) checkRange('View', 'exposure', options.exposure, 0)
     const shared = context === 'shared' || (context === 'auto' && ownContexts >= OWN_CONTEXTS)
-    this.renderer = new WebGLRenderer({ canvas: this.canvas, shared, antialias: options.antialias, toneMapping: options.toneMapping, exposure: options.exposure, bloom: options.bloom })
+    this.renderer = new WebGLRenderer({ canvas: this.canvas, shared, antialias: options.antialias, outlineAntialias: options.outlineAntialias, toneMapping: options.toneMapping, exposure: options.exposure, bloom: options.bloom })
     if (!shared) {
       this.#ownContext = true
       ownContexts++
@@ -225,6 +249,7 @@ export class View {
       this.invalidate()
     }
     if (options.autoLight !== undefined) this.autoLight = !!options.autoLight
+    if (options.reducedMotion !== undefined) this.#setMotion(options.reducedMotion)
     if (options.maxDelta !== undefined) this.maxDelta = checkRange('View', 'maxDelta', options.maxDelta, 0, Infinity, { above: true })
     if (options.renderMode !== undefined) this.renderMode = checkOneOf('View', 'renderMode', options.renderMode, ['auto', 'always', 'manual'])
     if (options.pixelRatio !== undefined) {
@@ -245,6 +270,8 @@ export class View {
     }
     if (options.highlight !== undefined) this.#setHighlight(options.highlight)
     if (options.tooltip !== undefined) this.tooltip(options.tooltip)
+    if (options.description !== undefined) this.description = options.description
+    if (options.keyboard !== undefined && options.keyboard !== false) this.#loadKeyboard(options.keyboard)
     this.#labels = new LabelLayer(this.canvas, {
       interactive: (label) => labelHandlers(label, 'click').length > 0 || labelHandlers(label, 'hover').length > 0,
       on: (type, label, e) => this.#labelPointer(type, label, e),
@@ -322,6 +349,51 @@ export class View {
     this.invalidate()
   }
 
+  /**
+   * 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() { return this.#motion === 'auto' ? this.#systemReduced : this.#motion }
+  /** @param {'auto' | boolean} v */
+  set reducedMotion(v) { this.#setMotion(v) }
+
+  /** @param {'auto' | boolean} v */
+  #setMotion(v) {
+    if (v !== 'auto' && typeof v !== 'boolean') fail('View', `'reducedMotion' is 'auto' (as the system's setting), true or false, got ${describe(v)}`)
+    this.#motion = v
+    this.invalidate()
+  }
+
+  /**
+   * 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() { return this.#description }
+  /** @param {string | null} v */
+  set description(v) {
+    if (v !== null && typeof v !== 'string') fail('View', `'description' is text for screen readers, or null, got ${describe(v)}`)
+    this.#description = v
+    if (this.#keyboard) {
+      this.#keyboard.setDescription(v)
+      return
+    }
+    const canvas = this.canvas
+    if (v === null) {
+      canvas.removeAttribute('aria-label')
+      if (this.#gaveRole) canvas.removeAttribute('role')
+      this.#gaveRole = false
+      return
+    }
+    canvas.setAttribute('aria-label', v)
+    // a picture, to a screen reader, unless the page has said otherwise
+    if (!canvas.hasAttribute('role')) {
+      canvas.setAttribute('role', 'img')
+      this.#gaveRole = true
+    }
+  }
+
   /** Canvas width in CSS pixels. */
   get width() { return this.#width }
   /** Canvas height in CSS pixels. */
@@ -395,6 +467,7 @@ export class View {
     this.time += dt
     this.#onFrame?.(dt, this.time)
     // the same order as the live loop, so a stepped frame is the frame a user sees
+    this.scene.motionReduced = this.reducedMotion
     this.scene.update(dt, this.time)
     this.#updateControls(dt)
     return this.#render(true)
@@ -409,7 +482,7 @@ export class View {
     if (this.#flight) return this.#fly(dt)
     if (!this.controls) return
     const waiting = this.#autoFrame && samePlace(cameraPlace(this.camera), this.#autoFrameFrom)
-    this.controls.update(dt)
+    this.controls.update(dt, this.reducedMotion)
     if (waiting) this.#autoFrameFrom = cameraPlace(this.camera)
   }
 
@@ -448,8 +521,8 @@ export class View {
     // remember what was drawn - including what drawing changed, such as fitting the camera - so
     // the next frame compares against it and doesn't draw the same picture again
     if (this.renderMode === 'auto') this.#watch.changed(this.scene, this.camera)
-    // things may have moved under a still pointer
-    if (this.#pointer && this.#needsHover()) this.#pickPending = true
+    // things may have moved under a still pointer - or the keyboard's focus moved on screen
+    if ((this.#pointer || this.#keyFocus) && this.#needsHover()) this.#pickPending = true
     return frame
   }
 
@@ -491,43 +564,26 @@ export 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 = this.scene, { padding = 0.2, direction: towards, duration = 0 } = {}) {
-    if (!(padding >= 0)) fail('View', `frame() padding is the margin around, as a fraction of the size (0.2 = 20%), got ${describe(padding)}`)
-    if (padding >= 1) warnOnce(this, `frame() padding ${padding} leaves a margin of ${Math.round(padding * 100)}% - it is a fraction of the size (0.2 = 20%)`)
     checkRange('View', 'frame() duration', duration, 0)
     const cam = /** @type {any} */ (this.camera)
     const from = placeOf(cam)
     this.#flight = null
-    const direction = towards === undefined ? cam.position.clone().sub(cam.target ?? new Vec3()).normalize()
-      : typeof towards === 'string' ? presetDirection(/** @type {CameraPreset} */ (towards)) : Vec3.fromInput(towards, 'View').normalize()
-    if (towards !== undefined && !(direction.len() > 0)) fail('View', `frame() direction is a preset name or a vector from the target towards the camera, got ${describe(towards)}`)
-    if (direction.len() === 0) direction.set(0, 0.3, 1).normalize()
-    const points = target instanceof Box3 ? corners(target) : this.#drawnPoints(target, direction)
+    const fit = this.#fit('frame', target, padding, towards)
     // an explicit frame replaces the preset camera's fit on the first frame
     this.#autoFrame = false
-    if (!points.length) return this
-    const ortho = cam.constructor.type === 'orthographic-camera'
-    const { center, size } = fitPoints(points, direction, { aspect: cam.aspect, fov: ortho ? undefined : cam.fov, padding })
-    const radius = Math.max(1e-3, ...points.map((p) => Math.hypot(p[0] - center[0], p[1] - center[1], p[2] - center[2])))
-    if (ortho) {
-      cam.height = size
-      cam.position.copy(center).add(direction.clone().multiplyScalar(radius * 4))
-      cam.far = Math.max(cam.far, radius * 10)
-    } else {
-      const distance = size
-      cam.position.copy(center).add(direction.clone().multiplyScalar(distance))
-      // keep the near/far range sensible for the model's size
-      cam.near = Math.max(1e-3, distance / 1000)
-      cam.far = Math.max(cam.far, distance * 10)
-    }
-    cam.target = center
+    if (!fit) return this
+    setPlace(cam, fit.place)
+    cam.near = fit.near ?? cam.near
+    cam.far = Math.max(cam.far, fit.far)
     // framed for the canvas as it is now
     this.#designed = cam.aspect
     this.#applied = 1
-    if (duration > 0) {
+    if (duration > 0 && !this.reducedMotion) {
       // the camera starts where it was and glides there, frame by frame
       this.#flight = { from, to: placeOf(cam), time: 0, duration }
       setPlace(cam, from)
@@ -536,6 +592,56 @@ export class View {
     return 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 = this.scene, { padding = 0.2, direction } = {}) {
+    const fit = this.#fit('framing', target, padding, direction)
+    if (!fit) return null
+    const { position, target: at, height } = fit.place
+    return height === undefined ? { position, target: at } : { position, target: at, height }
+  }
+
+  /**
+   * The camera's place to frame something, worked out without moving it - for frame() and framing().
+   * @param {string} method its caller, for errors @param {Node | Box3} target @param {number} padding
+   * @param {CameraPreset | Vec3Input | undefined} towards
+   * @returns {{ place: Place, near: number | undefined, far: number } | null}
+   */
+  #fit(method, target, padding, towards) {
+    if (!(padding >= 0)) fail('View', `${method}() padding is the margin around, as a fraction of the size (0.2 = 20%), got ${describe(padding)}`)
+    if (padding >= 1) warnOnce(this, `${method}() padding ${padding} leaves a margin of ${Math.round(padding * 100)}% - it is a fraction of the size (0.2 = 20%)`)
+    const cam = /** @type {any} */ (this.camera)
+    const direction = towards === undefined ? cam.position.clone().sub(cam.target ?? new Vec3()).normalize()
+      : typeof towards === 'string' ? presetDirection(/** @type {CameraPreset} */ (towards)) : Vec3.fromInput(towards, 'View').normalize()
+    if (towards !== undefined && !(direction.len() > 0)) fail('View', `${method}() direction is a preset name or a vector from the target towards the camera, got ${describe(towards)}`)
+    if (direction.len() === 0) direction.set(0, 0.3, 1).normalize()
+    const points = target instanceof Box3 ? corners(target) : this.#drawnPoints(target, direction)
+    if (!points.length) return null
+    const ortho = cam.constructor.type === 'orthographic-camera'
+    const { center, size } = fitPoints(points, direction, { aspect: cam.aspect, fov: ortho ? undefined : cam.fov, padding })
+    const radius = Math.max(1e-3, ...points.map((p) => Math.hypot(p[0] - center[0], p[1] - center[1], p[2] - center[2])))
+    if (ortho) {
+      return { place: { position: center.clone().add(direction.clone().multiplyScalar(radius * 4)), target: center, height: size },
+        near: undefined, far: radius * 10 }
+    }
+    // keep the near/far range sensible for the model's size
+    const distance = size
+    return { place: { position: center.clone().add(direction.clone().multiplyScalar(distance)), target: center },
+      near: Math.max(1e-3, distance / 1000), far: distance * 10 }
+  }
+
   /**
    * One frame of a glide: round the target as it moves, closing the distance evenly, so the picture
    * turns and zooms rather than cutting through what is in view.
@@ -772,6 +878,39 @@ export class View {
     })
   }
 
+  /** @param {true | KeyboardOptions} options */
+  #loadKeyboard(options) {
+    if (options !== true && (typeof options !== 'object' || options === null || Array.isArray(options))) {
+      fail('View', `'keyboard' is true, false or { label: (hit) => text }, got ${describe(options)}`)
+    }
+    const o = options === true ? {} : options
+    checkOptions('View', o, ['label'], { describe: "use 'label: (hit) => text'", text: "use 'label: (hit) => text'" }, 'keyboard')
+    if (o.label !== undefined && typeof o.label !== 'function') fail('View', `keyboard.label is a function (hit) => text, got ${describe(o.label)}`)
+    import('./keyboard.js').then(({ Keyboard }) => {
+      if (this.#disposed) return
+      this.#keyboard = new Keyboard(this, {
+        focus: (hit) => {
+          this.#keyFocus = hit
+          this.#pickPending = true
+          this.invalidate()
+        },
+        press: (hit) => {
+          for (const fn of handlersAbove(hit.node, 'click')) fn(hit)
+          for (const fn of this.#handlers.click) fn(hit, null)
+        },
+        tooltip: (hit) => this.#tooltipFor(hit)?.(hit),
+        viewWide: () => this.#handlers.hover.size > 0 || this.#handlers.click.size > 0 || !!this.#tooltipContent,
+      }, o)
+      this.#keyboard.setDescription(this.#description)
+    })
+  }
+
+  /** Where the keyboard's focus shows - its middle, on screen - in place of the pointer. @param {Hit} hit */
+  #keyAt(hit) {
+    const { x, y } = this.project(hit.point), rect = this.canvas.getBoundingClientRect()
+    return { x, y, clientX: rect.left + x, clientY: rect.top + y, event: null }
+  }
+
   /** The nearest node tooltip above the hit, or the View's. @param {Hit} hit */
   #tooltipFor(hit) {
     for (let n = /** @type {any} */ (hit.node); n; n = n.parent) if (n.tooltip) return n.tooltip
@@ -820,7 +959,8 @@ export class View {
       sharedContext: this.renderer.shared,
       frame, labels: this.#labelStats, bounds: drawn, nodes, autoLight: this.autoLight,
       contextLost: !!this.renderer.gl?.isContextLost?.(),
-      interaction: { hover: this.#handlers.hover.size, click: this.#handlers.click.size, tooltip: !!this.#tooltipContent, highlight: !!this.#highlight },
+      interaction: { hover: this.#handlers.hover.size, click: this.#handlers.click.size, tooltip: !!this.#tooltipContent, highlight: !!this.#highlight,
+        keyboard: !!this.#keyboard, reducedMotion: this.reducedMotion, description: this.canvas.getAttribute?.('aria-label') ?? this.#description },
     })
   }
 
@@ -837,6 +977,8 @@ export class View {
     this.controls?.dispose()
     this.#labels.dispose()
     this.#tooltip?.dispose()
+    this.#keyboard?.dispose()
+    if (this.#description !== null && !this.#keyboard) this.description = null
     this.renderer.dispose(this.scene)
     if (this.#ownContext) ownContexts--
     if (this.#ownCanvas) this.canvas.remove()
@@ -877,6 +1019,7 @@ export class View {
       if (this.#running) {
         this.time += dt
         this.#onFrame?.(dt, this.time)
+        this.scene.motionReduced = this.reducedMotion
         this.scene.update(dt, this.time)
       }
       this.#updateControls(dt)
@@ -902,6 +1045,8 @@ export class View {
     this.#pickPending = false
     if (!this.#needsHover()) return
     const p = this.#pointer
+    // what the keyboard stepped to is shown until the pointer moves
+    if (this.#keyFocus) return this.#setHovered(this.#keyFocus, this.#keyAt(this.#keyFocus))
     if (this.#labelHover) return this.#setHovered(this.#labelHover)
     if (!p || this.#dragging) return this.#setHovered(null)
     const frame = this.#gpuFrame()
@@ -922,9 +1067,11 @@ export class View {
     })
   }
 
-  /** @param {Hit | null} hit */
-  #setHovered(hit) {
-    const p = this.#pointer
+  /**
+   * @param {Hit | null} hit
+   * @param {{ clientX: number, clientY: number, event: PointerEvent | null } | null} [p] where it is shown - the pointer, or the keyboard's focus
+   */
+  #setHovered(hit, p = this.#pointer) {
     const before = this.#hovered
     // the same thing under the pointer: the same node, instance and row of data - a line's segments
     // and a surface's rows are told apart by their data, without a plain mesh changing per triangle
@@ -978,13 +1125,16 @@ export class View {
   /** @param {Hit | null} hit @returns {FrameHighlight | null} */
   #highlightFor(hit) {
     if (!hit) return null
-    // the nearest colour wins, and the nearest highlightWhole is what is tinted as one
+    // the nearest colour wins - or the nearest false, which tints nothing - and the nearest
+    // highlightWhole is what is tinted as one
     let color = null, whole = null
     for (let n = /** @type {any} */ (hit.node); n; n = n.parent) {
       color ??= n.highlight
       whole ??= n.highlightWhole ? n : null
     }
     color ??= this.#highlight
+    // the keyboard's focus always shows
+    if (!color && hit === this.#keyFocus) color = FOCUS_COLOR
     if (!color) return null
     const node = /** @type {any} */ (hit.node)
     if (whole) {
@@ -1001,17 +1151,19 @@ export class View {
   /** @param {FrameDescription} frame */
   #occlude(frame) {
     const labels = /** @type {(import('./frame.js').FrameLabel & { occluded?: boolean })[]} */ (frame.labels)
-    if (!labels.some((l) => l.style.occlude && l.visible)) return
-    // what this frame drew hides what is behind it - the same surfaces the picture shows
+    // a label waiting to be zoomed in to won't show either way, so it needs no ray
+    const halfHeight = this.height / 2
+    const testing = labels.filter((l) => l.style.occlude && l.visible && !(l.style.minScale && l.scale * halfHeight < l.style.minScale))
+    if (!testing.length) return
+    // what this frame drew hides what is behind it - the same surfaces the picture shows, each placed
+    // once for all the rays, which ask only whether anything is nearer than their label
+    const solids = Raycaster.solids([...frame.opaque, ...frame.transparent])
     const raycaster = new Raycaster()
-    const drawn = [...frame.opaque, ...frame.transparent]
-    for (const label of labels) {
-      if (!label.style.occlude || !label.visible) continue
+    for (const label of testing) {
       raycaster.setFromCamera(label.ndc, this.camera)
       const distance = label.position.distanceTo(raycaster.ray.origin)
       // only solid surfaces hide labels, and not the instance or point being labelled
-      const blocker = raycaster.intersectDrawn(drawn).find((h) => !(h.node === label.node && (label.index === null || h.instance === label.index)))
-      label.occluded = !!blocker && blocker.distance < distance * 0.995
+      label.occluded = raycaster.blocked(solids, distance * 0.995, label.node, label.index)
     }
   }
 
@@ -1022,6 +1174,8 @@ export class View {
       return { x: e.clientX - rect.left, y: e.clientY - rect.top, clientX: e.clientX, clientY: e.clientY, event: e }
     }
     const move = (e) => {
+      // the pointer takes over from the keyboard
+      if (this.#keyFocus) this.#keyboard?.clear()
       this.#pointer = at(e)
       const press = this.#press
       if (press && press.id === e.pointerId && !press.moved && Math.hypot(this.#pointer.x - press.x, this.#pointer.y - press.y) >= DRAG_START) press.moved = true
@@ -1108,6 +1262,17 @@ export class View {
       resize.observe(canvas)
       this.#cleanup.push(() => resize.disconnect())
     }
+    // the system's reduced-motion setting, followed as it changes
+    const motion = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)')
+    if (motion) {
+      const follow = () => {
+        this.#systemReduced = motion.matches
+        this.invalidate()
+      }
+      this.#systemReduced = motion.matches
+      motion.addEventListener?.('change', follow)
+      this.#cleanup.push(() => motion.removeEventListener?.('change', follow))
+    }
     // an off-screen view (a dashboard tile scrolled away) does no work at all
     if (typeof IntersectionObserver !== 'undefined') {
       const visible = new IntersectionObserver(([entry]) => {

package/src/charts/Chart.js

@@ -118,6 +118,22 @@ export class Chart extends Group {
     return `Chart (${s.mark}): ${shown} of ${s.rows.length} rows shown${axes.length ? `; ${axes.join(', ')}` : ''}${s.links.length ? `; ${s.links.length} links` : ''}`
   }
 
+  /**
+   * 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() {
+    const s = /** @type {ReturnType<typeof normalise>} */ (this.#spec), o = /** @type {any} */ (s.options)
+    if (o.description) return String(o.description)
+    // each field once, though it may set more than one channel (z and colour by region)
+    const by = [...new Set(['x', 'y', 'z', 'color', 'size'].map((k) => /** @type {any} */ (s.channels)[k]).filter((c) => c?.field).map((c) => c.title))]
+    const count = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`
+    const what = `${s.mark} chart of ${count(s.rows.length, 'row')}${by.length ? ` by ${by.join(', ')}` : ''}${s.links.length ? ` and ${count(s.links.length, 'link')}` : ''}`
+    return o.title ? `${o.title}: ${what}` : what
+  }
+
   /** @internal @returns {Record<string, unknown>} */
   jsonOptions() {
     return { ...this.#input }
@@ -305,14 +321,16 @@ export class Chart extends Group {
 
   /** @param {number} dt */
   #step(dt) {
-    this.#mark?.tick?.(dt)
+    // with motion reduced (the View's reducedMotion), flows stand still and a change shows at once
+    const still = /** @type {any} */ (this.root).motionReduced === true
+    if (!still) this.#mark?.tick?.(dt)
     const tw = this.#tween
     if (!tw) return
     const o = this.#input.transition ?? {}
     const duration = o.duration ?? 0.5
     const ease = EASES[o.ease ?? 'out']
     if (!ease) fail('chart()', `transition ease '${o.ease}' - expected ${Object.keys(EASES).map((e) => `'${e}'`).join(', ')}`)
-    tw.t = Math.min(1, tw.t + dt / duration)
+    tw.t = still ? 1 : Math.min(1, tw.t + dt / duration)
     const k = ease(tw.t)
     const state = new Float32Array(tw.from.length)
     for (let i = 0; i < state.length; i++) state[i] = tw.from[i] + (tw.to[i] - tw.from[i]) * k

package/src/explain.js

@@ -22,7 +22,7 @@ import { Box3 } from './value/Box3.js'
  * @property {boolean} autoLight
  * @property {boolean} contextLost
  * @property {boolean} [sharedContext] drawn with the page's shared WebGL context
- * @property {{ hover: number, click: number, tooltip: boolean, highlight: boolean }} interaction
+ * @property {{ hover: number, click: number, tooltip: boolean, highlight: boolean, keyboard?: boolean, reducedMotion?: boolean, description?: string | null }} interaction
  * @property {string[]} [notes] lines from nodes that describe themselves, such as charts
  */
 
@@ -115,7 +115,7 @@ export function explain(info) {
 
   if (info.labels && info.labels.total) {
     const s = info.labels
-    lines.push(`Labels: ${s.shown} shown, ${s.dimmed ? `${s.dimmed} dimmed (covered by labels or geometry), ` : ''}${s.overlapped} hidden by overlap, ${s.occluded} hidden behind geometry, ${s.offscreen} off screen`)
+    lines.push(`Labels: ${s.shown} shown, ${s.dimmed ? `${s.dimmed} dimmed (covered by labels or geometry), ` : ''}${s.overlapped} hidden by overlap, ${s.occluded} hidden behind geometry, ${s.offscreen} off screen${s.zoomedOut ? `, ${s.zoomedOut} waiting to be zoomed in to (minScale)` : ''}`)
     if (s.overlapped > s.shown * 3) warnings.push(`${s.overlapped} labels are hidden by overlap - give the important ones a higher priority, label fewer things, or use overlap: 'dim' or 'show'`)
     if (s.offscreen === s.total) warnings.push('every label is off screen - check their positions, or call view.frame()')
   }
@@ -125,6 +125,10 @@ export function explain(info) {
     lines.push(`Interaction: ${[ix.hover && plural(ix.hover, 'hover handler'), ix.click && plural(ix.click, 'click handler'),
       ix.tooltip && 'tooltip', ix.highlight && 'hover highlight'].filter(Boolean).join(', ')}`)
   }
+  if (ix.keyboard || ix.reducedMotion || ix.description) {
+    lines.push(`Accessibility: ${[ix.keyboard && 'keyboard (arrow keys step through what can be hovered)', ix.reducedMotion && 'reduced motion',
+      ix.description && `described as "${ix.description}"`].filter(Boolean).join(', ')}`)
+  }
 
   if (info.width < 2 || info.height < 2) warnings.unshift(`the canvas is ${info.width} x ${info.height} - give it a size in the page (CSS width and height)`)
   if (info.contextLost) warnings.unshift('the WebGL context is lost - nothing draws until the browser restores it')

package/src/frame.js

@@ -6,6 +6,7 @@ import { Box3 } from './value/Box3.js'
 import { warnOnce } from './validate.js'
 import { fitPointShadow, fitShadow, fitSpotShadow, SPOT_TILES } from './shadow.js'
 import { worldPlane } from './clip.js'
+import { hiddenInstance } from './scene/drawables.js'
 
 /** @import { Scene } from './scene/Scene.js' */
 /** @import { Camera } from './scene/cameras.js' */
@@ -89,6 +90,8 @@ export const LIGHT_LIMITS = { punctual: 4, directional: 2 }
  * @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
  */
 
 /**
@@ -239,13 +242,13 @@ export function collect(scene, camera) {
           else capped.set(item.clip, [item])
         }
         frame.stats.drawn++
-        if (node.labels) instanceLabels(node, viewProjection, view, frame.labels)
+        if (node.labels) instanceLabels(node, viewProjection, view, projection[5], frame.labels)
       } else {
         frame.stats.culled++
       }
     } else if (node.isLabel) {
       const position = node.worldPosition
-      frame.labels.push({ key: node, node, index: null, text: node.text, style: node, position, ...project(position, viewProjection, view) })
+      frame.labels.push({ key: node, node, index: null, text: node.text, style: node, position, ...project(position, viewProjection, view, projection[5]) })
     } else if (node.lightKind) {
       addLight(/** @type {Light} */ (node))
     }
@@ -323,7 +326,7 @@ export function collect(scene, camera) {
   if (items.length && sun >= 0) {
     const light = frame.lights[sun]
     const bounds = (/** @type {any} */ n) => n.expandBounds(new Box3())
-    const fit = fitShadow(/** @type {Vec3} */ (light.direction), items.map((c) => bounds(c.node)), receivers.map(bounds))
+    const fit = fitShadow(/** @type {Vec3} */ (light.direction), items.map((c) => bounds(c.node)), receivers.map(bounds), undefined, /** @type {any} */ (light.node).shadowBounds)
     if (fit) {
       frame.lights.splice(sun, 1)
       frame.lights.unshift(light)
@@ -392,10 +395,22 @@ let nextId = 1
 
 /**
  * Labels for every instance or point that has text, from the node's `labels` option.
- * @param {any} node InstancedMesh or Points @param {Mat4} viewProjection @param {Mat4} view @param {FrameLabel[]} out
+ * @param {any} node InstancedMesh or Points @param {Mat4} viewProjection @param {Mat4} view
+ * @param {number} yScale the projection's vertical scale @param {FrameLabel[]} out
  */
-function instanceLabels(node, viewProjection, view, out) {
-  const { labels, worldMatrix: w } = node
+function instanceLabels(node, viewProjection, view, yScale, out) {
+  // several labels per instance: the first keeps the plain key, so a single set's labels don't change identity
+  if (Array.isArray(node.labels)) {
+    node.labels.forEach((labels, layer) => instanceLabelSet(node, labels, layer, viewProjection, view, yScale, out))
+  } else instanceLabelSet(node, node.labels, 0, viewProjection, view, yScale, out)
+}
+
+/**
+ * @param {any} node @param {any} labels one set of instance labels @param {number} layer its place in the list
+ * @param {Mat4} viewProjection @param {Mat4} view @param {number} yScale @param {FrameLabel[]} out
+ */
+function instanceLabelSet(node, labels, layer, viewProjection, view, yScale, out) {
+  const { worldMatrix: w } = node
   let id = ids.get(node)
   if (id === undefined) ids.set(node, id = nextId++)
   const instanced = 'instanceMatrices' in node
@@ -409,6 +424,8 @@ function instanceLabels(node, viewProjection, view, out) {
   const data = Array.isArray(node.data) ? node.data : null
   const byRow = typeof labels.priority === 'function'
   for (let i = 0; i < n; i++) {
+    // an instance scaled to nothing is hidden, and so is its label
+    if (instanced && hiddenInstance(node.instanceMatrices, i)) continue
     const row = data ? data[i] : null
     const text = labels.text(row, i)
     if (text === null || text === undefined || text === '') continue
@@ -427,7 +444,7 @@ function instanceLabels(node, viewProjection, view, out) {
       w[1] * x + w[5] * y + w[9] * z + w[13],
       w[2] * x + w[6] * y + w[10] * z + w[14])
     const style = byRow ? { ...labels, priority: labels.priority(row, i) } : labels
-    out.push({ key: `${id}:${i}`, node, index: i, text: String(text), style, position, ...project(position, viewProjection, view) })
+    out.push({ key: layer ? `${id}:${i}:${layer}` : `${id}:${i}`, node, index: i, text: String(text), style, position, ...project(position, viewProjection, view, yScale) })
   }
 }
 
@@ -453,10 +470,13 @@ export function toScreen(position, viewProjection) {
  * units, for both kinds of camera (an orthographic one's clip w is always 1).
  * @param {Vec3} position @param {Mat4} viewProjection @param {Mat4} view
  */
-function project(position, viewProjection, view) {
+function project(position, viewProjection, view, yScale) {
   const { ndc, visible } = toScreen(position, viewProjection)
   const depth = -(view[2] * position[0] + view[6] * position[1] + view[10] * position[2] + view[14])
-  return { ndc: /** @type {[number, number]} */ ([ndc[0], ndc[1]]), depth, visible }
+  // clip w at the point: its depth for a perspective camera, 1 for an orthographic one
+  const m = viewProjection
+  const w = m[3] * position[0] + m[7] * position[1] + m[11] * position[2] + m[15]
+  return { ndc: /** @type {[number, number]} */ ([ndc[0], ndc[1]]), depth, visible, scale: w > 0 ? yScale / w : 0 }
 }
 
 // The six planes (a, b, c, d with the normal pointing inwards) of a view-projection matrix.