@mosaicajs/deck 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/density-counter.js

@@ -2,19 +2,19 @@ import { WORLD_SIZE } from '@mosaicajs/client';
 import { worldBbox } from '@mosaicajs/client/internal';
 import { densityCellsOf, densityOfTiles } from './density.js';
 /**
- * The cell sizes on screen density's resolution is chosen from, in CSS pixels, coarse to fine.
+ * The cell sizes on screen that density can be drawn at, in CSS pixels, from coarse to fine.
  *
  * @category Colour
  */
 export const DENSITY_CELL_SIZES = [32, 24, 16, 12, 8, 6, 4];
 /**
- * The cell size density is drawn at until one is chosen, in CSS pixels.
+ * The cell size density is drawn at by default, in CSS pixels.
  *
  * @category Colour
  */
 export const DEFAULT_DENSITY_CELL_PX = 12;
 /**
- * How long the camera rests before {@link DensityCounter} asks for counts, in milliseconds.
+ * How long the camera must rest before {@link DensityCounter} fetches counts, in milliseconds.
  *
  * @category Colour
  */
@@ -34,8 +34,8 @@ const RINGS = 2;
 /** The deepest depth the aggregate route counts, the stored position's. */
 const DEEPEST = 32;
 /**
- * The depth whose cells are closest to `cellPx` across on screen at `zoom`, nearest on a log scale.
- * A cell at depth `d` is `WORLD_SIZE · 2^zoom / 2^d` pixels wide.
+ * The depth whose cells are closest to `cellPx` wide on screen at `zoom`, measured on a log scale.
+ * A cell at depth `d` is `512 · 2^zoom / 2^d` pixels wide.
  *
  * @category Colour
  */
@@ -68,8 +68,8 @@ function areaOf(camera, margin) {
     return worldBbox({ target: [camera.target[0] ?? 0, camera.target[1] ?? 0], zoom: camera.zoom, width: camera.width, height: camera.height }, margin);
 }
 /**
- * The stops of {@link DENSITY_CELL_SIZES} at `camera`, each with the depth it asks for and whether
- * that depth fits `limit` cells over the area asked for.
+ * Each size in {@link DENSITY_CELL_SIZES} at `camera`, with its depth and whether its cells over
+ * the area fetched number at most `limit`, the server's `selection.maxAggregateCells`.
  *
  * @category Colour
  */
@@ -92,7 +92,7 @@ function densityDepth(camera, cellPx, limit) {
     return Math.min(cellDepth(camera.zoom, nearestStop(cellPx)), deepest);
 }
 /**
- * The stop of {@link DENSITY_CELL_SIZES} nearest `px` on a log scale.
+ * The size in {@link DENSITY_CELL_SIZES} nearest `px`, measured on a log scale.
  *
  * @category Colour
  */
@@ -126,33 +126,22 @@ function levelsAt(camera, depth, limit, groupings) {
     return levels;
 }
 /**
- * Keeps the counts density is drawn from for a camera: one `POST /v1/aggregate` grouping of cells,
- * registered with the store, which sends its filters and its highlight with it and asks again when
- * either changes. The counts are the highlighted items' under a highlight and the filtered items'
- * otherwise.
+ * Fetches the counts that density is drawn from, for the area around a camera. It registers an
+ * aggregate with the store, so the counts cover only what the viewer may see under the store's
+ * filters, and it fetches again when the filters, the highlight or the store's view (coordinate
+ * system) change. While a
+ * highlight is set, it counts the highlighted items.
  *
- * A camera change asks nothing while the camera moves. {@link DENSITY_SETTLE_MS} after the last
- * one, the counter works out the depth whose cells are nearest the chosen size on screen and asks
- * for that depth over the viewport and a margin, unless the counts asked for last are at that depth
- * and their area holds the viewport. The same request asks for up to {@link RINGS} coarser levels,
- * each a depth coarser over twice the reach, as the points' ring is fetched coarser further out. A
- * move that leaves the finest area asked for drops the registration at once, so a filter changed
- * during the move asks nothing for an area no longer shown. The counts held are drawn at their own
- * world positions until the next answer lands, so a zoom scales them with the map and a pan within
- * the margin asks nothing: the finest level held whose area holds the viewport is drawn, so a zoom
- * out draws the coarser levels' counts to the edges, and where no level holds it the widest is
- * drawn. A view switch asks again at once.
+ * Tell it where the camera is with `look` and what to draw with `set`. Once the camera has rested
+ * for {@link DENSITY_SETTLE_MS}, it fetches cells of about the chosen size on screen over the
+ * viewport and a margin round it, so a short pan needs no new request. Until the first answer for
+ * the view arrives, or after the server refuses one, `counts` returns the coarser counts that come
+ * with the map's tiles. After that it returns the last answer until the next one arrives.
+ * `onChange` is called whenever the counts to draw change.
  *
- * A depth whose cells over the area would pass `selection.maxAggregateCells` is never asked for.
- * Where the server refuses a request with `422` anyway, the counter asks one depth coarser, up to
- * three times. After any other refusal it drops the answer it held, so density is drawn from the
- * frame's tile counts as below, and it asks again at the camera's next rest.
- *
- * Until an answer is held for the view, density is drawn from the counts the frame's tiles carry,
- * which land with each viewport response ahead of its points. They count the same items, at the
- * tiles' coarser cells, and are not drawn once an answer is held.
- *
- * `onChange` is called when the counts to draw change.
+ * A {@link MosaicaLayer} with a `store` keeps a counter of its own. Make one yourself and pass it
+ * as the layer's `densityCounter` if your own code also needs the counts, as `<mosaica-map>` does
+ * for its density key.
  *
  * @category Colour
  */
@@ -173,6 +162,11 @@ export class DensityCounter {
     /** The tiles projection last read, and the counts derived from it. */
     tiles = null;
     unsubscribe;
+    /**
+     * @param store - The store to fetch through.
+     * @param onChange - Called whenever the counts to draw change.
+     * @param settleMs - How long the camera must rest before counts are fetched, in milliseconds.
+     */
     constructor(store, onChange, settleMs = DENSITY_SETTLE_MS) {
         this.store = store;
         this.onChange = onChange;
@@ -182,7 +176,7 @@ export class DensityCounter {
         this.meta = store.get('meta');
         this.unsubscribe = store.subscribe(() => this.read());
     }
-    /** The camera moved or the canvas was resized. Counts are asked for once it has rested. */
+    /** Tell the counter the camera has moved or the canvas has been resized. */
     look(camera) {
         const drawn = this.answered();
         this.camera = camera;
@@ -194,7 +188,7 @@ export class DensityCounter {
             this.onChange();
         this.schedule();
     }
-    /** What to draw. Off drops the registration and the counts held at once. */
+    /** Turn density on or off and choose the cell size. Turning it off drops the counts held. */
     set(settings) {
         const was = this.settings;
         this.settings = settings;
@@ -206,8 +200,8 @@ export class DensityCounter {
             this.schedule();
     }
     /**
-     * The counts to draw: the last answer, while it was counted in the store's current view, and
-     * until there is one the frame's tile counts. Nothing while density is off.
+     * The counts to draw, or `null` while density is off or there are none. Until the first answer
+     * for the current view arrives, these are the coarser counts that come with the map's tiles.
      */
     counts() {
         if (!this.settings.on)
@@ -229,14 +223,17 @@ export class DensityCounter {
             this.tiles = { tiles, counts: densityOfTiles(tiles, this.store.get('view').depth) };
         return this.tiles.counts.cells.length > 0 ? this.tiles.counts : null;
     }
-    /** The resolution stops at the camera as it stands; every stop is enabled before a camera and `meta`. */
+    /**
+     * The cell sizes density can be drawn at for the current camera. Every stop is enabled until the
+     * counter has a camera and the store has `meta`.
+     */
     stops() {
         const meta = this.store.get('meta');
         if (!this.camera || !meta)
             return DENSITY_CELL_SIZES.map((px) => ({ px, depth: 0, enabled: true }));
         return resolutionStops(this.camera, meta.selection.maxAggregateCells);
     }
-    /** Drop the registration and stop following the store. */
+    /** Stop fetching counts and unsubscribe from the store. */
     dispose() {
         this.stop();
         this.unsubscribe();

package/dist/density.d.ts

@@ -21,37 +21,37 @@ import { type Rgb } from './colour.js';
  * {@link filterDensity} smooths the binned image so the cells do not show as hard-edged squares.
  */
 /**
- * How density is drawn: `none`; `smooth`, a soft wash; `hex`, hexagonal bins; `grid`, square bins
- * one cell wide; or `contours`, lines of equal density.
+ * How density is drawn: `none`, `smooth` (a soft wash), `hex` (hexagonal bins), `grid` (square
+ * cells) or `contours` (lines of equal density).
  *
  * @category Colour
  */
 export type DensityMode = 'none' | 'smooth' | 'hex' | 'grid' | 'contours';
 /**
- * The colours density is drawn in: `warm-grey`, one neutral hue whose strength follows the count,
- * or a ramp (`viridis`, `cividis`, `magma`, `greys`) whose dense end contrasts with the ground, so
- * dense ground is dark on a light map and bright on a dark one.
+ * The colours density is drawn in: `warm-grey`, one neutral colour that strengthens with the
+ * count, or one of the ramps `viridis`, `cividis`, `magma` and `greys`. A ramp runs whichever way
+ * makes dense areas dark on a light map and bright on a dark one.
  *
  * @category Colour
  */
 export type DensityColours = 'warm-grey' | 'viridis' | 'cividis' | 'magma' | 'greys';
 /**
- * How a count is placed between no items and the largest count drawn: `linear`, in proportion to
- * the count, or `log`, in proportion to the logarithm of one more than the count, which spreads
- * counts that span several orders of magnitude.
+ * How a cell's count is placed between zero and the largest count drawn: `linear`, in proportion
+ * to the count, or `log`, in proportion to `log(1 + count)`, which suits counts that span several
+ * orders of magnitude.
  *
  * @category Colour
  */
 export type DensityScale = 'linear' | 'log';
-/** The density scale used where none is set. */
+/** The density scale used when none is set: `log`. */
 export declare const DEFAULT_DENSITY_SCALE: DensityScale;
 /**
- * Where `count` sits on `scale`, from 0 at no items to 1 at `max`: `count / max` under `linear` and
- * `log1p(count) / log1p(max)` under `log`. A count is clamped to `[0, max]`, and every count is at
- * 0 where `max` is 0 or less.
+ * Where `count` falls on `scale`, from 0 for no items to 1 for `max`: `count / max` under `linear`,
+ * and `log1p(count) / log1p(max)` under `log`. The count is clamped to `[0, max]`, and the result
+ * is 0 if `max` is 0 or less.
  */
 export declare function densityPosition(count: number, max: number, scale: DensityScale): number;
-/** The count at `position` on `scale` up to `max`: the inverse of {@link densityPosition}. */
+/** The count at `position` on `scale`, the inverse of {@link densityPosition}. Use it to label a density key. */
 export declare function densityCountAt(position: number, max: number, scale: DensityScale): number;
 /** The largest count among `cells`, 0 where there are none. */
 export declare function maxCount(cells: readonly {
@@ -93,15 +93,16 @@ export type DensityCell = {
     count: number;
 };
 /**
- * The counts density is drawn from: one {@link DensityCell} per non-empty cell at `depth`, where a
- * cell at depth `d` is one of `2^d` by `2^d` over the view, as a tile is at depths up to 16.
+ * Counts of items by cell, which density is drawn from. At depth `d` the view's square is divided
+ * into `2^d` by `2^d` cells, so each depth halves the cell's width. Only cells with a count are
+ * listed.
  *
  * @category Colour
  */
 export type DensityCounts = {
     /** The depth the cells are at. */
     depth: number;
-    /** The cells with a count, in any order. */
+    /** The cells, in any order. */
     cells: readonly DensityCell[];
 };
 /**

package/dist/density.js

@@ -1,11 +1,11 @@
 import { WORLD_SIZE } from '@mosaicajs/client';
 import { RAMPS, rampAt } from './colour.js';
-/** The density scale used where none is set. */
+/** The density scale used when none is set: `log`. */
 export const DEFAULT_DENSITY_SCALE = 'log';
 /**
- * Where `count` sits on `scale`, from 0 at no items to 1 at `max`: `count / max` under `linear` and
- * `log1p(count) / log1p(max)` under `log`. A count is clamped to `[0, max]`, and every count is at
- * 0 where `max` is 0 or less.
+ * Where `count` falls on `scale`, from 0 for no items to 1 for `max`: `count / max` under `linear`,
+ * and `log1p(count) / log1p(max)` under `log`. The count is clamped to `[0, max]`, and the result
+ * is 0 if `max` is 0 or less.
  */
 export function densityPosition(count, max, scale) {
     if (!(max > 0))
@@ -13,7 +13,7 @@ export function densityPosition(count, max, scale) {
     const c = Math.min(max, Math.max(0, count));
     return scale === 'log' ? Math.log1p(c) / Math.log1p(max) : c / max;
 }
-/** The count at `position` on `scale` up to `max`: the inverse of {@link densityPosition}. */
+/** The count at `position` on `scale`, the inverse of {@link densityPosition}. Use it to label a density key. */
 export function densityCountAt(position, max, scale) {
     if (!(max > 0))
         return 0;

package/dist/frame.d.ts

@@ -1,16 +1,28 @@
 import type { Store } from '@mosaicajs/client';
 /**
- * A box in world units, `[x0, y0, x1, y1]`, around where the items the store's filters admit are:
- * the smallest box of whole cells, at depth 8 over the view's extent, that holds every one of
- * them. An item far from the rest widens the box to take it in.
+ * Finds the box round the items that the store's filters match, so you can move the camera there
+ * with {@link cameraFitting}. The box is `[x0, y0, x1, y1]` in world units, made of whole cells 2
+ * units wide, or wider if the server's `selection.maxAggregateCells` is low. It holds every match,
+ * so one item far from the rest widens it.
  *
- * It asks one `POST /v1/aggregate` of the store, a count by cells over the store's filters and its
- * selected region, so the box is computed over the items this viewer may see. The request carries
- * the filters as they stand when it is sent, and is sent again if they change before the answer
- * lands. The registration is dropped once the answer lands.
+ * The count goes through the store, so the box covers only items this viewer may see, under the
+ * store's filters and selected region. If the filters change before the answer arrives, the store
+ * asks again. The promise waits for the store's `/v1/meta`.
  *
- * Resolves to `null` where no item matches, where the server refuses the count, where its
- * `selection.maxAggregateCells` admits no cell level, and once `signal` aborts. Waits for `meta`.
+ * @param store - The store whose filters are matched.
+ * @param options.signal - Aborts the search, which then resolves to `null`.
+ * @returns The box, or `null` if no item matches, if the server refuses or does not allow the
+ *   count, or once `signal` aborts.
+ *
+ * @example
+ * ```ts
+ * const box = await frameMatches(store);
+ * if (box) {
+ *   viewState = {...viewState, ...cameraFitting(box, deck.width, deck.height)};
+ *   deck.setProps({viewState});
+ *   tell();
+ * }
+ * ```
  */
 export declare function frameMatches(store: Store, options?: {
     signal?: AbortSignal;

package/dist/frame.js

@@ -8,17 +8,29 @@ import { densityCellsOf } from './density.js';
 const FRAME_DEPTH = 8;
 let framings = 0;
 /**
- * A box in world units, `[x0, y0, x1, y1]`, around where the items the store's filters admit are:
- * the smallest box of whole cells, at depth 8 over the view's extent, that holds every one of
- * them. An item far from the rest widens the box to take it in.
+ * Finds the box round the items that the store's filters match, so you can move the camera there
+ * with {@link cameraFitting}. The box is `[x0, y0, x1, y1]` in world units, made of whole cells 2
+ * units wide, or wider if the server's `selection.maxAggregateCells` is low. It holds every match,
+ * so one item far from the rest widens it.
  *
- * It asks one `POST /v1/aggregate` of the store, a count by cells over the store's filters and its
- * selected region, so the box is computed over the items this viewer may see. The request carries
- * the filters as they stand when it is sent, and is sent again if they change before the answer
- * lands. The registration is dropped once the answer lands.
+ * The count goes through the store, so the box covers only items this viewer may see, under the
+ * store's filters and selected region. If the filters change before the answer arrives, the store
+ * asks again. The promise waits for the store's `/v1/meta`.
  *
- * Resolves to `null` where no item matches, where the server refuses the count, where its
- * `selection.maxAggregateCells` admits no cell level, and once `signal` aborts. Waits for `meta`.
+ * @param store - The store whose filters are matched.
+ * @param options.signal - Aborts the search, which then resolves to `null`.
+ * @returns The box, or `null` if no item matches, if the server refuses or does not allow the
+ *   count, or once `signal` aborts.
+ *
+ * @example
+ * ```ts
+ * const box = await frameMatches(store);
+ * if (box) {
+ *   viewState = {...viewState, ...cameraFitting(box, deck.width, deck.height)};
+ *   deck.setProps({viewState});
+ *   tell();
+ * }
+ * ```
  */
 export function frameMatches(store, options = {}) {
     framings += 1;

package/dist/index.d.ts

@@ -1,12 +1,55 @@
 /**
- * A deck.gl layer that draws a Mosaica store, for a host that builds its own `Deck`.
- * {@link MosaicaLayer} draws the marks, density, the artifacts' names and outlines and the
- * selection. {@link CATEGORY_PALETTES} and {@link RAMPS} are the named colour sets a
- * {@link Colouring} chooses from, and {@link Sizing} the sizes a number column sizes marks
- * between. {@link viewInputOf} turns the host's camera into a view for the store,
- * {@link DensityCounter} keeps the counts density is drawn from, {@link frameMatches} and
- * {@link cameraFitting} open the camera on the matched items, {@link resolvePick} reads a pick, and
- * {@link basemapLayers} draws a basemap under the points.
+ * `@mosaicajs/deck` draws a Mosaica map with deck.gl, for an app that builds its own `Deck`. If
+ * you want a ready-made map, the `<mosaica-map>` element in `@mosaicajs/components` wraps this
+ * package and handles the camera for you.
+ *
+ * {@link MosaicaLayer} is a deck.gl layer that draws what a store from `@mosaicajs/client`
+ * publishes: the points, density, the artifacts' names and outlines, and the selected region. It
+ * fetches nothing itself. Your app owns the camera. Each time the view state changes, pass the
+ * camera to {@link viewInputOf} and give the result to the store's `setView`. The store fetches
+ * what the new view needs, and the layer redraws when the store's projections change.
+ *
+ * The rest of the package works alongside the layer. {@link resolvePick} turns a deck.gl pick into
+ * the item or artifact under the pointer. {@link frameMatches} and {@link cameraFitting} find the
+ * camera that shows the filtered items. {@link basemapLayers} draws a world outline, map tiles or
+ * an image under the points. {@link DensityCounter} fetches the counts that density is drawn from,
+ * and the layer keeps one of its own unless you pass yours. {@link Colouring}, {@link Sizing} and
+ * the named palettes and ramps are the choices for colouring and sizing points by a column.
+ *
+ * @example
+ * ```ts
+ * import {Deck, OrthographicView} from '@deck.gl/core';
+ * import {createStore} from '@mosaicajs/client';
+ * import {MosaicaLayer, viewInputOf} from '@mosaicajs/deck';
+ *
+ * type Camera = {target: [number, number, number]; zoom: number};
+ *
+ * const store = createStore({viewerUrl: 'http://localhost:8080', token});
+ * let viewState: Camera = {target: [256, 256, 0], zoom: 0};
+ *
+ * // Tell the store where the camera is. viewInputOf returns null until /v1/meta has arrived.
+ * function tell() {
+ *   const input = viewInputOf(store, viewState, deck.width, deck.height);
+ *   if (input) store.setView(input);
+ * }
+ *
+ * const deck = new Deck<OrthographicView>({
+ *   parent: document.getElementById('map') as HTMLDivElement,
+ *   views: new OrthographicView({flipY: true}),
+ *   viewState,
+ *   controller: true,
+ *   layers: [new MosaicaLayer({id: 'mosaica', store})],
+ *   onViewStateChange: ({viewState: next}) => {
+ *     viewState = next as Camera;
+ *     deck.setProps({viewState});
+ *     tell();
+ *   }
+ * });
+ *
+ * store.subscribe('meta', (meta) => {
+ *   if (meta) tell();
+ * });
+ * ```
  *
  * @module @mosaicajs/deck
  */

package/dist/index.js

@@ -1,12 +1,55 @@
 /**
- * A deck.gl layer that draws a Mosaica store, for a host that builds its own `Deck`.
- * {@link MosaicaLayer} draws the marks, density, the artifacts' names and outlines and the
- * selection. {@link CATEGORY_PALETTES} and {@link RAMPS} are the named colour sets a
- * {@link Colouring} chooses from, and {@link Sizing} the sizes a number column sizes marks
- * between. {@link viewInputOf} turns the host's camera into a view for the store,
- * {@link DensityCounter} keeps the counts density is drawn from, {@link frameMatches} and
- * {@link cameraFitting} open the camera on the matched items, {@link resolvePick} reads a pick, and
- * {@link basemapLayers} draws a basemap under the points.
+ * `@mosaicajs/deck` draws a Mosaica map with deck.gl, for an app that builds its own `Deck`. If
+ * you want a ready-made map, the `<mosaica-map>` element in `@mosaicajs/components` wraps this
+ * package and handles the camera for you.
+ *
+ * {@link MosaicaLayer} is a deck.gl layer that draws what a store from `@mosaicajs/client`
+ * publishes: the points, density, the artifacts' names and outlines, and the selected region. It
+ * fetches nothing itself. Your app owns the camera. Each time the view state changes, pass the
+ * camera to {@link viewInputOf} and give the result to the store's `setView`. The store fetches
+ * what the new view needs, and the layer redraws when the store's projections change.
+ *
+ * The rest of the package works alongside the layer. {@link resolvePick} turns a deck.gl pick into
+ * the item or artifact under the pointer. {@link frameMatches} and {@link cameraFitting} find the
+ * camera that shows the filtered items. {@link basemapLayers} draws a world outline, map tiles or
+ * an image under the points. {@link DensityCounter} fetches the counts that density is drawn from,
+ * and the layer keeps one of its own unless you pass yours. {@link Colouring}, {@link Sizing} and
+ * the named palettes and ramps are the choices for colouring and sizing points by a column.
+ *
+ * @example
+ * ```ts
+ * import {Deck, OrthographicView} from '@deck.gl/core';
+ * import {createStore} from '@mosaicajs/client';
+ * import {MosaicaLayer, viewInputOf} from '@mosaicajs/deck';
+ *
+ * type Camera = {target: [number, number, number]; zoom: number};
+ *
+ * const store = createStore({viewerUrl: 'http://localhost:8080', token});
+ * let viewState: Camera = {target: [256, 256, 0], zoom: 0};
+ *
+ * // Tell the store where the camera is. viewInputOf returns null until /v1/meta has arrived.
+ * function tell() {
+ *   const input = viewInputOf(store, viewState, deck.width, deck.height);
+ *   if (input) store.setView(input);
+ * }
+ *
+ * const deck = new Deck<OrthographicView>({
+ *   parent: document.getElementById('map') as HTMLDivElement,
+ *   views: new OrthographicView({flipY: true}),
+ *   viewState,
+ *   controller: true,
+ *   layers: [new MosaicaLayer({id: 'mosaica', store})],
+ *   onViewStateChange: ({viewState: next}) => {
+ *     viewState = next as Camera;
+ *     deck.setProps({viewState});
+ *     tell();
+ *   }
+ * });
+ *
+ * store.subscribe('meta', (meta) => {
+ *   if (meta) tell();
+ * });
+ * ```
  *
  * @module @mosaicajs/deck
  */