@expofp/wayfinding 3.44.8 → 3.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -9,7 +9,7 @@ export { createWayfinding } from './createWayfinding.js';
9
9
  export type { WayfindingLayerOptions, WayfindingLayers } from './renderer/index.js';
10
10
  export { initWayfindingLayers, resolveWayfindingLayers } from './renderer/index.js';
11
11
  export type { GraphDataSource } from './core/index.js';
12
- export type { IconConfig, RendererPort } from './renderer/index.js';
12
+ export type { IconConfig, RendererPort, TrailOptions } from './renderer/index.js';
13
13
  export type { FloorContext, IconAsset, IconName, IconProvider } from './runtime/index.js';
14
14
  export type { GraphLine, Route, RouteEndpoint, RouteLine, RoutePoint, TransitionPointDef, } from './core/index.js';
15
15
  export type { PositionInput, SetRouteInput } from './runtime/index.js';
@@ -2,15 +2,30 @@ import type { ImageDef, RenderableDef } from '@expofp/renderer';
2
2
  import type { LayerManager } from './layerManager.js';
3
3
  import type { WayfindingLayers } from './layers.js';
4
4
  import type { IconConfig, RendererPort } from './types.js';
5
+ /**
6
+ * The size an icon canvas is drawn at, in CSS pixels.
7
+ * @param canvas - The icon's canvas.
8
+ * @param width - The width the caller stated, if any.
9
+ * @param height - The height the caller stated, if any.
10
+ * @returns The stated size, with whatever is missing read from the canvas's `style`.
11
+ * @throws When neither the caller nor the canvas says how big the icon is.
12
+ */
13
+ export declare function resolveCssSize(canvas: HTMLCanvasElement, width?: number, height?: number): {
14
+ readonly width: number;
15
+ readonly height: number;
16
+ };
5
17
  /**
6
18
  * Lays one wayfinding icon out for a new pixel size: an icon holds its on-screen size, so its
7
- * bounds are the source's pixel dimensions times the pixel size, about its own center.
19
+ * bounds are its size in CSS pixels times the pixel size, about its own center.
8
20
  *
9
21
  * The **only** writer of an icon's bounds size, which is what lets everything else here write
10
22
  * logical fields alone and never track a scale. Returns nothing when the size was already right, so
11
23
  * a settled camera costs no slot writes.
12
24
  */
13
- export declare function rescaleIcon(def: ImageDef, pixelSize: number): readonly RenderableDef[] | undefined;
25
+ export declare function rescaleIcon(def: ImageDef, size: {
26
+ readonly width: number;
27
+ readonly height: number;
28
+ }, pixelSize: number): readonly RenderableDef[] | undefined;
14
29
  /**
15
30
  * Manages `ImageDef` icons in the scene graph.
16
31
  *
@@ -1,20 +1,32 @@
1
1
  import { Rect } from '@expofp/geometry';
2
+ /**
3
+ * The size an icon canvas is drawn at, in CSS pixels.
4
+ * @param canvas - The icon's canvas.
5
+ * @param width - The width the caller stated, if any.
6
+ * @param height - The height the caller stated, if any.
7
+ * @returns The stated size, with whatever is missing read from the canvas's `style`.
8
+ * @throws When neither the caller nor the canvas says how big the icon is.
9
+ */
10
+ export function resolveCssSize(canvas, width, height) {
11
+ const resolvedWidth = width ?? parseFloat(canvas.style?.width ?? '');
12
+ const resolvedHeight = height ?? parseFloat(canvas.style?.height ?? '');
13
+ if (!(resolvedWidth > 0) || !(resolvedHeight > 0)) {
14
+ throw new Error(`renderer: canvas "${canvas.id}" has no CSS size: pass width and height, or draw it on a canvas whose style records one`);
15
+ }
16
+ return { width: resolvedWidth, height: resolvedHeight };
17
+ }
2
18
  /**
3
19
  * Lays one wayfinding icon out for a new pixel size: an icon holds its on-screen size, so its
4
- * bounds are the source's pixel dimensions times the pixel size, about its own center.
20
+ * bounds are its size in CSS pixels times the pixel size, about its own center.
5
21
  *
6
22
  * The **only** writer of an icon's bounds size, which is what lets everything else here write
7
23
  * logical fields alone and never track a scale. Returns nothing when the size was already right, so
8
24
  * a settled camera costs no slot writes.
9
25
  */
10
- export function rescaleIcon(def, pixelSize) {
26
+ export function rescaleIcon(def, size, pixelSize) {
11
27
  const bounds = def.bounds;
12
- // `ImageSource` also covers a `Blob`, which holds bytes and reports no pixel size. Every icon def
13
- // is built from `IconConfig.canvas` in `createIcon`, so the source here is always a canvas, and a
14
- // canvas reports its own size.
15
- const source = def.source;
16
- const width = source.width * pixelSize;
17
- const height = source.height * pixelSize;
28
+ const width = size.width * pixelSize;
29
+ const height = size.height * pixelSize;
18
30
  if (bounds.size.x === width && bounds.size.y === height)
19
31
  return undefined;
20
32
  bounds.set(bounds.center.x, bounds.center.y, width, height, bounds.rotation, bounds.elevation);
@@ -66,6 +78,7 @@ export function createIconManager(layerManager, port, layers, screenSpace = fals
66
78
  }
67
79
  function createIcon(iconKey, name, cfg, rotation = cfg.rotation) {
68
80
  const layer = layerFor(cfg);
81
+ const size = resolveCssSize(cfg.canvas, cfg.width, cfg.height);
69
82
  // The caller's own answer wins where it gave one. An icon whose rotation carries a plan bearing
70
83
  // opts out, because a screen-space def spins about the screen's normal and would point at a
71
84
  // fixed screen direction instead.
@@ -86,7 +99,7 @@ export function createIconManager(layerManager, port, layers, screenSpace = fals
86
99
  // through a quarter turn. Its own billboarding is what a cardinal snap would be for.
87
100
  if (cfg.cardinalSnap && !facesCamera)
88
101
  port.attachCardinalSnap(def);
89
- def.onScale = ({ pixelSize }) => rescaleIcon(def, pixelSize);
102
+ def.onScale = ({ pixelSize }) => rescaleIcon(def, size, pixelSize);
90
103
  layer.children.push(def);
91
104
  const record = {
92
105
  imageDef: def,
@@ -1,5 +1,5 @@
1
1
  export { createWayfindingRenderer } from './createWayfindingRenderer.js';
2
2
  export type { WayfindingLayerOptions, WayfindingLayers } from './layers.js';
3
3
  export { initWayfindingLayers, resolveWayfindingLayers } from './layers.js';
4
- export type { IconConfig, RendererPort, WayfindingRenderer } from './types.js';
4
+ export type { IconConfig, RendererPort, TrailOptions, WayfindingRenderer } from './types.js';
5
5
  //# sourceMappingURL=index.d.ts.map
@@ -17,7 +17,7 @@ export interface AnimationHandle {
17
17
  * segment once per lap, when the chase wraps.
18
18
  * @param segments - The defs to animate, in route order. Their `points` are moved in place.
19
19
  * @param onChange - Called with the defs that changed, for the caller to commit.
20
- * @param getPixelSize - Plan units per device pixel, which the speed is modulated by.
20
+ * @param getPixelSize - Plan units per CSS pixel, which the speed is modulated by.
21
21
  * @param startProgress - Where in the lap to resume, in `[0, 1)`.
22
22
  * @returns A handle, or nothing when there is no route to animate.
23
23
  */
@@ -15,7 +15,7 @@ const NOTHING = 0;
15
15
  * segment once per lap, when the chase wraps.
16
16
  * @param segments - The defs to animate, in route order. Their `points` are moved in place.
17
17
  * @param onChange - Called with the defs that changed, for the caller to commit.
18
- * @param getPixelSize - Plan units per device pixel, which the speed is modulated by.
18
+ * @param getPixelSize - Plan units per CSS pixel, which the speed is modulated by.
19
19
  * @param startProgress - Where in the lap to resume, in `[0, 1)`.
20
20
  * @returns A handle, or nothing when there is no route to animate.
21
21
  */
@@ -33,7 +33,7 @@ export function createRouteLineManager(layerManager, colors, port, layers) {
33
33
  *
34
34
  * Lays nothing out and returns nothing, so it never costs a write. It is here because the speed
35
35
  * term reads a scale and there is no other channel that carries one.
36
- * @param pixelSize - Plan units per device pixel.
36
+ * @param pixelSize - Plan units per CSS pixel.
37
37
  */
38
38
  function readPixelSize(pixelSize) {
39
39
  currentPixelSize = pixelSize;
@@ -1,6 +1,7 @@
1
1
  import { type Point2Like } from '@expofp/geometry';
2
2
  import type { ImageDef, LayerDef } from '@expofp/renderer';
3
3
  import type { LayerManager } from './layerManager.js';
4
+ import type { TrailOptions } from './types.js';
4
5
  /**
5
6
  * Manages named trails of evenly-spaced dots between two points.
6
7
  *
@@ -14,9 +15,7 @@ export interface TrailManager {
14
15
  * Place, update, or remove a named trail.
15
16
  * Pass `from/to = null` to remove the trail.
16
17
  */
17
- setTrail(name: string, from: Point2Like | null, to: Point2Like | null, options?: {
18
- readonly canvas: HTMLCanvasElement;
19
- }): void;
18
+ setTrail(name: string, from: Point2Like | null, to: Point2Like | null, options?: TrailOptions): void;
20
19
  /** Remove all trails. */
21
20
  destroy(): void;
22
21
  }
@@ -1,5 +1,6 @@
1
1
  import { Rect } from '@expofp/geometry';
2
2
  import { computeTrailPoints } from '../core/index.js';
3
+ import { resolveCssSize } from './iconManager.js';
3
4
  /** Distance between trail dots at a pixel size of 1, in the same units as route points. */
4
5
  const TRAIL_INTERVAL_AT_BASE_PIXEL_SIZE = 40;
5
6
  /**
@@ -32,7 +33,7 @@ export function createTrailManager(layerManager, layer) {
32
33
  * closure delegates to.
33
34
  *
34
35
  * One function per manager, not per def: what it reads is this manager's trails.
35
- * @param pixelSize - Plan units per device pixel.
36
+ * @param pixelSize - Plan units per CSS pixel.
36
37
  * @returns The dots that were written, plus the layer when the dot count changed with them.
37
38
  */
38
39
  function layOutTrails(pixelSize) {
@@ -90,7 +91,7 @@ export function createTrailManager(layerManager, layer) {
90
91
  const interval = TRAIL_INTERVAL_AT_BASE_PIXEL_SIZE * currentPixelSize;
91
92
  const points = computeTrailPoints(record.from, record.to, interval);
92
93
  const canvas = record.canvas;
93
- const size = { x: canvas.width * currentPixelSize, y: canvas.height * currentPixelSize };
94
+ const size = { x: record.width * currentPixelSize, y: record.height * currentPixelSize };
94
95
  const dots = record.dotDefs;
95
96
  const kept = Math.min(dots.length, points.length);
96
97
  const changed = [];
@@ -158,7 +159,15 @@ export function createTrailManager(layerManager, layer) {
158
159
  bufferRedraw(redraw(existing));
159
160
  return;
160
161
  }
161
- const record = { from, to, canvas: options.canvas, dotDefs: [] };
162
+ const { width, height } = resolveCssSize(options.canvas, options.width, options.height);
163
+ const record = {
164
+ from,
165
+ to,
166
+ canvas: options.canvas,
167
+ width,
168
+ height,
169
+ dotDefs: [],
170
+ };
162
171
  trails.set(name, record);
163
172
  bufferRedraw(redraw(record));
164
173
  },
@@ -25,8 +25,34 @@ export interface RouteColors {
25
25
  readonly remaining: string;
26
26
  readonly active: string;
27
27
  }
28
+ /** What a dot trail draws: one dot image, and the size it is drawn at. */
29
+ export interface TrailOptions {
30
+ /** The dot image. Must stay the same canvas for the life of the trail. */
31
+ readonly canvas: HTMLCanvasElement;
32
+ /**
33
+ * The dot's width in CSS pixels, not its canvas's backing width. Left out, it is read from the
34
+ * canvas's `style.width`; a canvas with neither makes `setTrail` throw.
35
+ */
36
+ readonly width?: number;
37
+ /** The dot's height in CSS pixels; see {@link width}. */
38
+ readonly height?: number;
39
+ }
28
40
  export interface IconConfig {
29
41
  readonly canvas: HTMLCanvasElement;
42
+ /**
43
+ * The width the icon is drawn at, in CSS pixels. Not the canvas's `width`: that is its backing
44
+ * store, in the device pixels it was rasterized at, which says how crisp the icon is and nothing
45
+ * about how big.
46
+ *
47
+ * Left out, it is read from the canvas's own `style.width`, which every canvas the SDK creates
48
+ * records. A canvas with neither makes `setIcon` throw.
49
+ *
50
+ * Read when the icon is created or its canvas changes: a later `setIcon` with the same canvas and
51
+ * a different width is ignored.
52
+ */
53
+ readonly width?: number;
54
+ /** The height the icon is drawn at, in CSS pixels; see {@link width}. */
55
+ readonly height?: number;
30
56
  /**
31
57
  * Draw the icon on the level above the other icons rather than among them — the live position,
32
58
  * which an endpoint pin must never cover. Two icon layers exist because the draw order inside one
@@ -106,9 +132,7 @@ export interface WayfindingRenderer {
106
132
  * clears it. `options` required when non-null; `canvas` must stay stable.
107
133
  * Buffered — `flush()` to commit.
108
134
  */
109
- setTrail(name: string, from: Point2Like | null, to: Point2Like | null, options?: {
110
- readonly canvas: HTMLCanvasElement;
111
- }): void;
135
+ setTrail(name: string, from: Point2Like | null, to: Point2Like | null, options?: TrailOptions): void;
112
136
  /**
113
137
  * Replace static route lines (passed + remaining) and (re)start the remaining
114
138
  * animation. Buffered — `flush()` to commit.
@@ -13,8 +13,12 @@ export function createEndpointView({ renderer, iconProvider, floorContext, }) {
13
13
  const sourcePosition = visibleRoutePoints[0];
14
14
  const destPosition = visibleRoutePoints[visibleRoutePoints.length - 1];
15
15
  const sourceInactive = from.id === CURRENT_POSITION_POINT_ID && snapped;
16
+ const source = iconProvider.getIcon(sourceInactive ? 'source_inactive' : 'source');
17
+ const destination = iconProvider.getIcon('destination');
16
18
  renderer.setIcon('source', {
17
- canvas: iconProvider.getIcon(sourceInactive ? 'source_inactive' : 'source').canvas,
19
+ canvas: source.canvas,
20
+ width: source.width,
21
+ height: source.height,
18
22
  x: sourcePosition.x,
19
23
  y: sourcePosition.y,
20
24
  hidden: isSourceIconHidden(from, fromOnFloor),
@@ -22,7 +26,9 @@ export function createEndpointView({ renderer, iconProvider, floorContext, }) {
22
26
  cardinalSnap: true,
23
27
  });
24
28
  renderer.setIcon('destination', {
25
- canvas: iconProvider.getIcon('destination').canvas,
29
+ canvas: destination.canvas,
30
+ width: destination.width,
31
+ height: destination.height,
26
32
  x: destPosition.x,
27
33
  y: destPosition.y,
28
34
  hidden: !toOnFloor || !to.bounds,
@@ -7,8 +7,11 @@ export function createPositionView({ renderer, iconProvider, }) {
7
7
  const hasHeading = Number.isFinite(input.heading);
8
8
  const iconName = hasHeading ? 'current_arrow' : 'current';
9
9
  const rotation = hasHeading ? degToRad(input.heading) : undefined;
10
+ const icon = iconProvider.getIcon(iconName);
10
11
  renderer.setIcon(POSITION_ICON_KEY, {
11
- canvas: iconProvider.getIcon(iconName).canvas,
12
+ canvas: icon.canvas,
13
+ width: icon.width,
14
+ height: icon.height,
12
15
  // Above the route icons: the live position must never end up under an endpoint pin.
13
16
  onTop: true,
14
17
  x: input.x,
@@ -25,7 +25,12 @@ export function createTrailView({ renderer, iconProvider, floorContext, }) {
25
25
  clearSlot(slot);
26
26
  return;
27
27
  }
28
- renderer.setTrail(slot, from, to, { canvas: iconProvider.getIcon('trail').canvas });
28
+ const dot = iconProvider.getIcon('trail');
29
+ renderer.setTrail(slot, from, to, {
30
+ canvas: dot.canvas,
31
+ width: dot.width,
32
+ height: dot.height,
33
+ });
29
34
  activeSlots.add(slot);
30
35
  },
31
36
  clear(slot) {
@@ -24,8 +24,11 @@ export function createTransitionView({ renderer, iconProvider, floorContext, onT
24
24
  floorOrder: floorContext.getFloorOrder(),
25
25
  });
26
26
  for (const [index, point] of transitionPoints.entries()) {
27
+ const icon = iconProvider.getIcon(iconNameFor(point.role, point.direction));
27
28
  renderer.setIcon(TRANSITION_ICON_NAME, {
28
- canvas: iconProvider.getIcon(iconNameFor(point.role, point.direction)).canvas,
29
+ canvas: icon.canvas,
30
+ width: icon.width,
31
+ height: icon.height,
29
32
  x: point.x,
30
33
  y: point.y,
31
34
  cardinalSnap: true,
@@ -4,7 +4,9 @@ import type { WayfindingRenderer } from '../renderer/index.js';
4
4
  export type IconName = 'source' | 'source_inactive' | 'destination' | 'current' | 'current_arrow' | 'transition' | 'transition_up' | 'transition_down' | 'transition_entry' | 'trail';
5
5
  export interface IconAsset {
6
6
  readonly canvas: HTMLCanvasElement;
7
+ /** The width the icon is drawn at, in CSS pixels; not the canvas's backing width. */
7
8
  readonly width: number;
9
+ /** The height the icon is drawn at, in CSS pixels; not the canvas's backing height. */
8
10
  readonly height: number;
9
11
  }
10
12
  export interface IconProvider {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expofp/wayfinding",
3
- "version": "3.44.8",
3
+ "version": "3.45.0",
4
4
  "type": "module",
5
5
  "description": "ExpoFP SDK internal: framework-neutral wayfinding (routing, snapping, scene rendering)",
6
6
  "homepage": "https://developer.expofp.com/",
@@ -34,12 +34,12 @@
34
34
  "dependencies": {
35
35
  "ngraph.graph": "^19.1.0",
36
36
  "tslib": "^2.3.0",
37
- "@expofp/geometry": "3.44.8"
37
+ "@expofp/geometry": "3.45.0"
38
38
  },
39
39
  "peerDependencies": {
40
- "@expofp/renderer": "3.44.8"
40
+ "@expofp/renderer": "3.45.0"
41
41
  },
42
42
  "devDependencies": {
43
- "@expofp/renderer": "3.44.8"
43
+ "@expofp/renderer": "3.45.0"
44
44
  }
45
45
  }