@emuanalytics/flow-rdf-core 4.0.3 → 4.0.5

package/dist/shared/{flow-rdf-core.4dde996e.d.ts → flow-rdf-core.8b5acf14.d.ts}

@@ -1,7 +1,8 @@
+import EventEmitter$1, { EventEmitter } from 'eventemitter3';
+import * as lit from 'lit-html';
 import { Client } from '@emuanalytics/flow-engine-client';
 import { ISubscription, IObservableStream, IDisposer } from 'mobx-utils';
 import { MapLibreEvent, MapMouseEvent as MapMouseEvent$1, MapOptions as MapOptions$1, Map } from '@emuanalytics/maplibre-gl';
-import EventEmitter$1, { EventEmitter } from 'eventemitter3';
 
 type Annotation = {
     annotationType: string;
@@ -18,43 +19,497 @@ type Path<T, TBase = Record<string, unknown>> = PathImpl<T, TBase, StoreKey<T, T
 type PathValue<T, P extends Path<T, TBase>, TBase = Record<string, unknown>> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? Rest extends Path<T[Key], TBase> ? PathValue<T[Key], Rest, TBase> : never : never : P extends keyof T ? T[P] : never;
 
 type StoreConstructor<T extends StateStore> = new () => T;
+/**
+ * Store annotations are used when extending the {@link StateStore} class to mark state properties
+ * as observable, computed, and/or serializable.
+ *
+ * Annotations can be applied as decorators when using TypeScript or by passing an object to
+ * the {@link StateStore.initialize} method.
+ *
+ * Available annotations:
+ *
+ * | Annotation          |    Remarks                 |
+ * | ------------------- | -------------------------- |
+ * | `observable`        | alias for `observable.deep` |
+ * | `obervable.deep`    | Mark property as deeply observable. Child properties of objects and array elements will be recursively marked as observable. |
+ * | `obervable.ref`     | Mark property as observable. Track changes using strict `===` equality. Use this as an optimization for immutable object properties and arrays. The _value_ of the property is ignored, only its strict identity is considered.  |
+ * | `obervable.shallow` | Mark collection as observable. The collection itself is observable (reacting to inserts, deletions etc.), but the contents of the collection are not marked as observable.  |
+ * | `obervable.struct`  | Mark object or array as observable. Assigning a new value that is _structurally_ equal to the old value will not trigger a reactive update. |
+ * | `computed`          | Mark a getter as a computed property. Computed properties are lazily evaluated and memoized. |
+ * | `serialize`         | Mark a property as serializable. The property will be included in the serialized output of {@link StateStore.serialize}. |
+ * | `action`            | Mark a method as an _action_. Use this annotation for helper methods you declare on your derived {@link StateStore} class that modify state. The method will automatically be run in a transaction and can reduce the number of reactive updates triggered when modifying multiple observable properties. |
+ *
+ * @example
+ * Using annotations in JavaScript:
+ *```js
+ * import {
+ *   observable,
+ *   serialize,
+ *   computed,
+ *   StateStore
+ * } from '@emuanalytics/flow-rdf-core';
+ *
+ * // Declare a state store using annotations
+ * class AppState extends StateStore {
+ *   constructor() {
+ *     super();
+ *     this.initialize({
+ *       a: [observable, serialize],
+ *       b: [observable],
+ *       c: [computed],
+ *       d: [observable.ref],
+ *       helperMethod: [action]
+ *     });
+ *   }
+ *
+ *   a = 'a value';
+ *   b = 2;
+ *
+ *   get c() {
+ *    return `${this.a} - ${this.b}`;
+ *   }
+ *
+ *   d = { a: 1, b: 2 };
+ *
+ *   // This method will be run in a transaction
+ *   helperMethod(val) {
+ *     this.a = val;
+ *     this.increment('b');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Using TypeScript decorators:
+ *```js
+ * import {
+ *   observable,
+ *   serialize,
+ *   computed,
+ *   StateStore
+ * } from '@emuanalytics/flow-rdf-core';
+ *
+ * // Declare a state store using annotations
+ * class AppState extends StateStore {
+ *   constructor() {
+ *     super();
+ *     this.initialize();
+ *   }
+ *
+ *   @serialize
+ *   @observable
+ *   a = 'a value';
+ *
+ *   @observable
+ *   b = 2;
+ *
+ *   @computed
+ *   get c() {
+ *    return `${this.a} - ${this.b}`;
+ *   }
+ *
+ *   @observable.ref
+ *   d = { a: 1, b: 2 };
+ *
+ *   // This method will be run in a transaction
+ *   @action
+ *   helperMethod(val) {
+ *     this.a = val;
+ *     this.increment('b');
+ *   }
+ * }
+ * ```
+ */
 type StoreAnnotations<T extends StateStore> = {
     [P in StoreKey<T, StateStore>]?: Annotation | Annotation[];
 };
 type SerializationFormat = 'raw' | 'json' | 'lz';
+/**
+ * State stores define reactive application state and are the basis of Flo.w RDF's reactive functionality.
+ *
+ * In typical usage, the {@link StateStore} class is extended to define an application-specific
+ * state store and a singleton instance is created to manage application state. The application-specific
+ * class defines which state properties are available, their initial values, their types (when using TypeScript), and
+ * whether they are serialized.
+ *
+ * Properties of the application-specific state store can be marked as `observable` using decorators or annotations.
+ * Reads and writes to these properties are tracked within reactive contexts and will trigger updates to any
+ * dependent computations or side-effects.
+ *
+ * Getters can be marked as `computed` to define derived properties that are automatically updated when
+ * their dependencies change. Computed properties are lazy and memoized, meaning that they are only evaluated
+ * when an entity is observing their value and are only re-evaluated when their dependencies change.
+ *
+ * Observable state properties can also be marked as serializable using decorators or annotations. This allows the state store
+ * to be serialized to a string or object and deserialized. Serialization is can be used tp persist
+ * application state to local storage or for supporting shareable URLs with embedded state. Call {@link StateStore.serialize}
+ * to serialize the state store and {@link StateStore.deserialize} to update its properties from a previously serialized state.
+ *
+ * Because application state store instances are designed to be globally-available singletons, they can be a convenient
+ * way to expose state-related helper methods. These can be marked with the `action` annotation to automatically run
+ * within a transaction.
+ *
+ * ##TODO Describe state paths
+ *
+ * @example
+ * Define an application state store using TypeScript with decorators:
+ * ```ts
+ * import {
+ *   observable,
+ *   serialize,
+ *   computed,
+ *   StateStore
+ * } from '@emuanalytics/flow-rdf-core';
+ *
+ * class AppState extends StateStore {
+ *   constructor() {
+ *     super();
+ *     this.initialize();
+ *   }
+ *
+ *   // Observable and serializable property
+ *   @serialize
+ *   @observable
+ *   a = 'a value';
+ *
+ *   // Observable property - not serialized
+ *   @observable b = 2;
+ *
+ *   // Computed property
+ *   @computed
+ *   get c() {
+ *    return `${this.a} - ${this.b}`;
+ *   }
+ * }
+ *
+ * // Application-wide singleton instance
+ * export const appState = new AppState();
+ * ```
+ *
+ * @example
+ * Define an application state store using JavaScript with annotations:
+ * ```js
+ * import {
+ *   observable,
+ *   serialize,
+ *   computed,
+ *   StateStore
+ * } from '@emuanalytics/flow-rdf-core';
+ *
+ * // Declare a state store using annotations
+ * class AppState extends StateStore {
+ *   constructor() {
+ *     super();
+ *     this.initialize({
+ *       a: [observable, serialize],
+ *       b: [observable],
+ *       c: [computed]
+ *     });
+ *   }
+ *
+ *   a = 'a value';
+ *   b = 2;
+ *
+ *   get c() {
+ *    return `${this.a} - ${this.b}`;
+ *   }
+ * }
+ *
+ * // Application-wide singleton instance
+ * export const appState = new AppState();
+ * ```
+ */
 declare class StateStore {
     private get formattedName();
     private serializationAnnotations;
+    /**
+     * Returns `true` if the store has been initialized.
+     *
+     * Derived state stores **must** be initialized before use by calling {@link StateStore.initialize}
+     * in the constructor.
+     *
+     * @returns `true` if the store has been initialized.
+     */
     get initialized(): boolean;
     id: string;
-    constructor();
-    get<P extends Path<this, StateStore>>(path: P): PathValue<this, P, StateStore>;
-    set<P extends Path<this, StateStore>>(path: P, val: PathValue<this, P, StateStore>): void;
+    /**
+     * Constructs a new `StateStore`.
+     *
+     * In derived classes, call `super()` in the constructor followed by `this.initialize(...)`.
+     *
+     * @example
+     * ```js
+     * constructor() {
+     *   super();
+     *
+     *   // Required!
+     *   this.initialize();
+     * }
+     * ```
+     * @param id - Optional unique identifier for debugging purposes. If not supplied, a random identifier will be generated.
+     */
+    constructor(id?: string);
+    /**
+     * Returns the value at the specified path in the state store.
+     *
+     * @param path - State store path to retrieve.
+     * @typeParam TPath - Type defining possible state store paths.
+     * @returns The value of the state store property at the specified path.
+     */
+    get<TPath extends Path<this, StateStore>>(path: TPath): PathValue<this, TPath, StateStore>;
+    /**
+     * Sets the value at the specified path in the state store.
+     *
+     * @param path - State store path to set
+     * @param val - Value to set at the specified path
+     */
+    set<TPath extends Path<this, StateStore>>(path: TPath, val: PathValue<this, TPath, StateStore>): void;
+    /**
+     * Use this method to batch multiple state updates into a single transaction.
+     * This can improve performance by reducing the number of reactive updates triggered by
+     * state updates.
+     *
+     * @example
+     * Set multiple state properties within a transaction:
+     * ```js
+     * store.transaction(() => {
+     *  store.set('a', 1);
+     *  store.set('b', 2);
+     *  store.set('c', 3);
+     * });
+     * ```
+     *
+     * @param fn - The function to run within the transaction.
+     */
     transaction(fn: (state: this) => void): void;
+    /**
+     * Toggles the value at the specified path in the state store.
+     * This method assumes that the value at the specified path is a boolean.
+     *
+     * @param path - The path to the boolean value to toggle.
+     * @returns The new value at the specified path.
+     */
     toggle<P extends Path<this, StateStore>>(path: P): boolean;
+    /**
+     * Increments the value at the specified path in the state store.
+     * This method assumes that the value at the specified path is a number.
+     *
+     * @param path - The path to the number value to increment.
+     * @returns The new value at the specified path.
+     */
     increment<P extends Path<this, StateStore>>(path: P): number;
+    /**
+     * Decrements the value at the specified path in the state store.
+     * This method assumes that the value at the specified path is a number.
+     *
+     * @param path The path to the number value to decrement.
+     * @returns The new value at the specified path.
+     */
     decrement<P extends Path<this, StateStore>>(path: P): number;
+    /**
+     * Bind an HTML control element to a state store property. Two-way binding
+     * is established between the control and the state store property. When the
+     * control value changes, the state store property is updated. When the state
+     * store property changes, the control value is updated.
+     *
+     * Supports:
+     * - Native elements that emit an `input` event and have a `value` property.
+     * - Flo.w RDF UI custom elements that emit `flow-ui-input` or `flow-ui-change` events and have
+     * a value property.
+     *
+     * :::warning
+     * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+     * :::
+     *
+     * :::warning
+     * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+     * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+     * :::
+     *
+     * @example
+     * ```js
+     * const subscription = store.bindControl(document.getElementById('my-input'), 'myStateProperty');
+     * ...
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @param el - The HTML element to bind
+     * @param statePath - The path to the state store property to bind
+     * @param options - Binding options
+     * @param options.toState - A function to convert the control value to the state store value
+     * @param options.fromState - A function to convert the state store value to the control value
+     * @param options.updateOn - The event type that will trigger an update of the state store property. Default is `input`.
+     * @returns A subscription that can be used to `unsubscribe()` the binding.
+     */
     bindControl<TStatePath extends Path<this, StateStore>, TStateValue extends PathValue<this, TStatePath, StateStore>, TElementValue, TElement extends HTMLElement & {
         value: TElementValue;
     }>(el: TElement, statePath: TStatePath, options?: {
         toState?: (value: TElementValue) => TStateValue;
         fromState?: (value: TStateValue) => TElementValue;
+        updateOn: 'input' | 'change';
     }): ISubscription;
-    bindElementProp<TElementProp extends keyof TElement, TElement extends HTMLElement, TStatePath extends Path<this, StateStore>, TStateValue extends PathValue<this, TStatePath, StateStore>>(el: TElement, prop: TElementProp, statePath: TStatePath, options?: {
+    /**
+     * Bind an HTML element property to a state store property. One-way binding
+     * is established between the element property and the state store property.
+     * When the state store property changes, the element property is updated.
+     *
+     * :::warning
+     * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+     * :::
+     *
+     * :::warning
+     * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+     * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+     * :::
+     *
+     * @example
+     * ```js
+     * const el = document.getElementById('my-span');
+     * const subscription = store.bindElementProp(el, 'textContent', 'myStateProperty');
+     * ...
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @param el - The HTML element to bind
+     * @param prop - The property of the element to bind
+     * @param path - The path to the state store property to bind
+     * @param options - Binding options
+     * @param options.fromState - A function to convert the state store value to the element property value
+     * @returns A subscription that can be used to `unsubscribe()` the binding.
+     */
+    bindElementProp<TElementProp extends keyof TElement, TElement extends HTMLElement, TStatePath extends Path<this, StateStore>, TStateValue extends PathValue<this, TStatePath, StateStore>>(el: TElement, prop: TElementProp, path: TStatePath, options?: {
         fromState?: (value: TStateValue) => TElement[TElementProp];
     }): ISubscription;
-    bindElementAttr<TElement extends HTMLElement, P extends Path<this, StateStore>>(el: TElement, attr: string, statePath: P): ISubscription;
+    /**
+     * Bind an HTML element attribute to a state store property. One-way binding
+     * is established between the element attribute and the state store property.
+     * When the state store property changes, the element attribute is updated
+     * (using `el.setAttribute(...)`).
+     *
+     * :::warning
+     * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+     * :::
+     *
+     * :::warning
+     * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+     * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+     * :::
+     *
+     * @param el - The HTML element to bind
+     * @param attr - The attribute of the element to bind
+     * @param path - The path to the state store property to bind
+     * @returns
+     */
+    bindElementAttr<TElement extends HTMLElement, TStatePath extends Path<this, StateStore>, TStateValue extends PathValue<this, TStatePath, StateStore>>(el: TElement, attr: string, path: TStatePath, options?: {
+        fromState?: (value: TStateValue) => string;
+    }): ISubscription;
+    /**
+     * Create an observable stream that emits the value of the specified state store property
+     * when it changes. The stream can be subscribed to using its `subscribe()` method.
+     *
+     * :::warning
+     * Subscriptions should be disposed of when no longer required by calling their `unsubscribe()` method.
+     * :::
+     *
+     * :::danger
+     * It is an anti-pattern to modify state store properties directly from within a stream subscription.
+     * Use a `computed` property instead. Limit use of `toStream` to running imperative side-effects
+     * in response to a reactive update of a state property.
+     * :::
+     *
+     * @example
+     * ```js
+     * const subscription = store.toStream('myStateProperty').subscribe((value) => {
+     *  console.log('myStateProperty changed:', value);
+     * });
+     * ...
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @param path - The path to the state store property to bind
+     * @param fireImmediately - If `true`, the stream will emit the current value immediately
+     * If `false`, the stream will only emit values when the state store property changes.
+     *
+     * @returns An observable stream that emits the value of the specified state property.
+     */
     toStream<P extends Path<this, StateStore>>(path: P, fireImmediately?: boolean): IObservableStream<PathValue<this, P, StateStore>>;
+    /**
+     * Creates a reactive context that will automatically re-run the specified function
+     * whenever referenced reactive state changes. The supplied function is run immediately
+     * and referenced state properties are tracked. The function will be re-run when tracked
+     * state properties change.
+     *
+     * Note that referenced state properties are determined dynamically
+     * by access. If a code branch is not taken, the referenced state properties in that branch
+     * will not be tracked. If, on a subsequent run, the code branch is taken, the tracking
+     * will be updated to include the newly accessed state properties.
+     *
+     * This method is similar to `toStream` but allows access to the complete state object rather
+     * than a single property.
+     *
+     * :::warning
+     * Autoruns should be disposed of when no longer needed by invoking the `disposer` function
+     * returned when creating an autorun.
+     * :::
+     *
+     * :::danger
+     * It is an anti-pattern to modify state store properties directly from within an autorun.
+     * Use a `computed` property instead. Limit use of autoruns to running imperative side-effects
+     * in response to a reactive update.
+     * :::
+     *
+     * @example
+     * ```js
+     * const disposer = store.autorun((state) => {
+     *    // Set map properties as a side effect whenever any of `state.zoom`, `state.bearing`, or `state.pitch` change
+     *    map.setCenter({zoom: state.zoom, bearing: state.bearing, pitch: state.pitch});
+     * });
+     * ...
+     * disposer();
+     * ```
+     *
+     * @param autorunFn - The function to run within a reactive context
+     * @param name - Optional name for debugging purposes
+     * @returns - A disposer function. Invoke this function to dispose of the autorun.
+     */
     autorun(autorunFn: (state: this) => void, name?: string): IDisposer;
+    /**
+     * This method **must**
+     *  be called in the constructor of derived classes to initialize the state store.
+     * An exception will be thrown if this method is not called before using the state store.
+     *
+     * If using decorators to configure reactive properties, this method should be called without arguments.
+     * If not using decorators, supply reactive annotations to configure reactive properties.
+     *
+     * See {@link StoreAnnotations} for a list of available annotations.
+     *
+     * :::info
+     * If this method is called without using decorators and without supplying reactive annotations,
+     * the state store will be configured automatically:
+     *
+     * - All properties will be made observable.
+     * - All getters will converted to computed properties.
+     *
+     * This is only recommended for simple state stores in demos.
+     * :::
+     *
+     * @param annotations Optional annotations for configuring reactive properties.
+     */
     initialize(annotations?: StoreAnnotations<this>): void;
-    private makeObservable;
-    private makeAutoObservable;
+    /** Serialize to `raw` format */
     serialize(): Record<string, string>;
-    serialize(format: 'raw'): Record<string, string>;
-    serialize(format: 'lz' | 'json'): string;
+    /** Serialize to `raw` format */
+    serialize(format: 'raw', group?: string): Record<string, string>;
+    /** Serialize to `json` or `lz` format */
+    serialize(format: 'json' | 'lz', group?: string): string;
+    /** Deserialize `raw` format */
     deserialize(value: Record<string, string>): void;
+    /** Deserialize `raw` format */
     deserialize(value: Record<string, string>, format: 'raw'): void;
+    /** Deserialize `json` or `lz` format */
     deserialize(value: string, format: 'json' | 'lz'): void;
+    private makeObservable;
+    private makeAutoObservable;
     private checkInitialized;
 }
 
@@ -123,164 +578,161 @@ declare class Debugger<TState extends StateStore = StateStore> {
     private logStateValue;
 }
 
-/** Result format of a [[Query]]. */
-type QueryResultFormat = 'json' | 'geojson' | 'csv';
-/** [[FlowQueryDefinition]] 'attributes' entry. */
-type QueryAttribute = string | [any, string];
-/**
- * [[FlowQueryDefinition]] 'where' clauses.
- */
-interface QueryWhereClauses {
-    [attribute: string]: any;
-}
-/**
- * [[FlowQueryDefinition]] extra parameters.
- */
-interface QueryExtraParams {
-    [key: string]: string | number;
-}
-/**
- * [[FlowQueryDefinition]] 'order' clause.
- *
- * A field name or [field, asc/desc] tuple.
- */
-type QueryOrderClause = string | number | [string | number, 'asc' | 'desc'];
-interface QuerySampleOptions {
-    percentage: number;
-    method?: 'system' | 'bernoulli';
-    seed?: number;
-}
-/**
- * Definition of a Flo.w reactive dataset query.
- */
-interface QueryDefinition {
-    /** ID of dataset to query. */
-    datasetId: string;
-    /** Attributes to return in results. */
-    attributes?: QueryAttribute[];
-    /** DISTINCT ON attributes */
-    distinct?: string | string[];
-    /** Filter results using 'where' clauses. */
-    where?: QueryWhereClauses;
-    /** Sort results by attributes. */
-    order?: QueryOrderClause[];
-    /** Group results by attributes. */
-    group?: (string | number)[];
-    /** Start offset of returned results */
-    offset?: number;
-    /** Limit number of returned results */
-    limit?: number;
-    /** Format of returned data. */
-    format?: QueryResultFormat;
-    /** Additional query parameters. */
-    params?: QueryExtraParams;
-    /** Sampling options. */
-    sample?: QuerySampleOptions;
-}
-interface QueryOptions {
-    id?: string;
-    fireImmediately?: boolean;
-    delay?: number;
-    contextId?: string;
-}
-/**
- * [[FlowQuery]] query definition function.
- *
- * @typeParam TState  Type of application state.
- */
-type QueryDefinitionFn<TState> = (this: TState, store: TState) => QueryDefinition | Promise<QueryDefinition> | null;
-/**
- * [[FlowQuery]] result transform function.
- *
- * @typeParam T  Type of transformed query results.
- */
-type QueryResultTransformFn<T = any> = (results: any) => T | null;
-
-declare class Query<TResults, TState extends StateStore = any> {
-    private queryFn;
-    private static _defaultOptions;
-    static setDefaultOptions(options: QueryOptions): void;
-    private _options;
-    private _committer;
-    private _disposer;
-    private _transformFn;
-    private get formattedName();
-    get id(): string;
-    results: TResults | null;
-    busy: boolean;
-    error: Error | null;
-    constructor(queryFn: QueryDefinitionFn<TState | null>, transformFn?: QueryResultTransformFn<TResults>, options?: QueryOptions);
-    destroy(): void;
-    runImmediately(): Promise<TResults | null>;
-    private wake;
-    private sleep;
-    private runQuery;
-}
-declare function query<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult, TState>;
-declare function query<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult>, options?: QueryOptions): Query<TResult, TState>;
-declare function queryMany<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult[], TState>;
-declare function queryMany<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult[]>, options?: QueryOptions): Query<TResult[], TState>;
-declare function queryOne<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult, TState>;
-declare function queryOne<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult>, options?: QueryOptions): Query<TResult, TState>;
-
-/**
- * The `QueryRegistry` is a container for [[Query]] instances.
- *
- * Queries can be registered and retrieved by ID.
- */
-declare class QueryRegistry {
-    private _queries;
-    /**
-     * Register a Flo.w reactive query.
-     *
-     * @param query Query to register.
-     */
-    registerQuery(query: Query<any>): void;
-    /**
-     * Un-register a Flo.w reactive query.
-     *
-     * @param query Query to unregister.
-     */
-    unregisterQuery(query: Query<any>): void;
-    /**
-     * Retrieve the specified query.
-     *
-     * This method returns a promise that resolves when the query has been initialized.
-     *
-     * @param id Map ID.
-     */
-    getQuery<TResults = any, TState extends StateStore = any>(id: string): Promise<Query<TResults, TState>>;
-}
-
-declare class FlowError extends Error {
+declare class FlowCoreError extends Error {
     cause?: Error | undefined;
     constructor(message: string, cause?: Error | undefined);
 }
 
-declare class FlowExpressionError extends FlowError {
+declare class FlowCoreExpressionError extends FlowCoreError {
     readonly reason: 'parseError' | 'evaluationError';
     readonly errors: string[];
     constructor(expression: string, reason: 'parseError' | 'evaluationError', errors: string[]);
 }
 
+/**
+ * A Flo.w RDF reactive expression - used internally to parse and evaluate {@link MapLayer}
+ * style [expressions](/flow-rdf-core/expression-reference/). An expression can be evaluated
+ * and its MapLibre-compatible representation can be generated.
+ *
+ * @example
+ * ```js
+ * const ex = new ReactiveExpression('1 + 2');
+ * console.log(ex.value); // 3
+ * console.log(ex.maplibreExpression); // ['+', 1, 2]
+ * ```
+ *
+ *
+ */
 declare class ReactiveExpression<TState extends StateStore = StateStore, R = any> {
     private static parser;
     private static customFunctions;
+    /**
+     * Returns `true` if the specified custom function has been registered.
+     *
+     * @param fn - The custom function name
+     */
     static hasCustomFunction(fn: string): boolean;
+    /**
+     * Register a custom function to be used in reactive expressions.
+     *
+     * @param fn - The custom function to register
+     */
     static registerCustomFunction(fn: FlowCoreExpressionCustomFunction): void;
     private _expression;
     private parsedResult;
     private _store;
+    /**
+     * Parses a program string into a map of properties and their associated {@link ReactiveExpression}.
+     *
+     * The program string should be a series of property/expression pairs separated by semicolons as follows:
+     *
+     * ```js
+     * const program = `
+     *  prop1: 1 + 2;
+     *  prop2: 'a string';
+     *  prop3: $stateProp * 3;
+     * `;
+     *
+     * const parsedProgram = ReactiveExpression.parseProgram(program);
+     * // {
+     * //   prop1: ReactiveExpression,
+     * //   prop2: ReactiveExpression,
+     * //   prop3: ReactiveExpression
+     * // }
+     *
+     * ```
+     *
+     * @param program - The program to parse
+     * @returns A map of property names and their associated expressions.
+     */
     static parseProgram(program: string): {
         [key: string]: ReactiveExpression;
     };
+    /**
+     * Generates the MapLibre-compatible representation of this expression.
+     *
+     * This is used internally when creating MapLibre style specifications
+     * from Flo.w RDF {@link MapLayer} styles.
+     *
+     * This getter is a reactive `computed` and will re-evaluate within a
+     * reactive context when the expression value changes.
+     *
+     * @computed
+     *
+     * @returns The MapLibre-compatible representation of this expression
+     */
     get maplibreExpression(): ParserExpression | undefined;
+    /**
+     * Evaluates the expression and returns the result.
+     *
+     * This getter is a reactive `computed` and will re-evaluate within a
+     * reactive context when the expression value changes.
+     *
+     * @example
+     * ```js
+     * const ex = new ReactiveExpression('1 + 2');
+     * console.log(ex.value); // 3
+     * ```
+     *
+     * @computed
+     *
+     * @returns - The result of evaluating the expression
+     */
     get value(): R;
-    get parseError(): FlowExpressionError | null;
+    /**
+     * Returns  details of parsing errors if the expression could not be parsed.
+     */
+    get parseError(): FlowCoreExpressionError | null;
+    /**
+     * Returns the original expression string passed to the constructor.
+     */
     get expression(): string;
+    /**
+     * Returns the state store bound to the expression.
+     */
     get store(): TState | null;
+    /**
+     * Constructs a new `ReactiveExpression`.
+     *
+     * @example
+     * ```js
+     * const ex = new ReactiveExpression('1 + 2');
+     * console.log(ex.value); // 3
+     * ```
+     *
+     * @param expression - the string representation of the expression
+     * @param parsedExpression - Used internally to bypass parsing when evaluating a program.
+     */
     constructor(expression: string, parsedExpression?: ParserExpression);
+    /**
+     * Binds a {@link StateStore} to the expression. The state store is used to resolve
+     * state variables in the expression.
+     *
+     * Note: If no state store is bound, the expression will not be able to resolve
+     * state variables and will return `null` when evaluated. A console warning will
+     * be logged.
+     *
+     * @param store {@link StateStore} to bind to the expression
+     * @returns
+     */
     bindState(store: TState | null): this;
+    /**
+     * Returns a subscribable stream, which produces the value of the expression
+     * whenever a reactive update causes the expression to re-evaluate.
+     *
+     * @example
+     * ```js
+     * const ex = new ReactiveExpression('$val * 2');
+     * const subscription = ex.toStream().subscribe((value) => console.log(value));
+     * ...
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @param fireImmediately - If `true`, the stream will fire immediately with the current value.
+     * If `false` the stream will only fire when the value changes.
+     *
+     * @returns A subscribable stream of the expression value
+     */
     toStream(fireImmediately?: boolean): IObservableStream<R>;
     private evaluateExpression;
     private expandCustomFunctions;
@@ -295,8 +747,24 @@ interface FlowCoreExpressionCustomFunction {
     fn: FlowCoreExpressionCustomFunctionSignature;
 }
 type FlowCoreExpressionCustomFunctionSignature = <TState extends StateStore = any>(expr: ParserFunctionExpression, parentExpression: ReactiveExpression) => ParserExpression;
+interface FlowCoreExpressionCustomFunctions {
+    [name: string]: FlowCoreExpressionCustomFunction;
+}
 type ParserExpression = number | string | boolean | null | ParserFunctionExpression;
 type ParserFunctionExpression = [string, ...any[]];
+interface ParserProgram {
+    [key: string]: ParserExpressionWithIndex;
+}
+interface ParserExpressionWithIndex {
+    expr: ParserExpression;
+    start: ParserIndex;
+    end: ParserIndex;
+}
+interface ParserIndex {
+    offset: number;
+    line: number;
+    column: number;
+}
 
 declare class MapLayerStyleBuilder {
     private static _styleBuilders;
@@ -1474,7 +1942,7 @@ declare class MapDataSource {
 
 type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
-declare class FlowMapError extends FlowError {
+declare class FlowMapError extends FlowCoreError {
     constructor(message: string, originalError?: Error);
 }
 
@@ -1501,16 +1969,34 @@ interface MapFeature {
         [key: string]: any;
     };
 }
+/**
+ * Map parameters for use with the {@link FlowCoreMap.setCenter} and {@link FlowCoreMap.getCenter} methods.
+ */
 interface MapCenterOptions {
+    /** Longitude of map center */
     lng: number;
+    /** Latitude of map center */
     lat: number;
+    /** Map zoom level */
     zoom: number;
+    /** Map bearing in degrees */
     bearing: number;
+    /** Map pitch in degrees */
     pitch: number;
 }
+/**
+ * Animation options for use with the {@link FlowCoreMap.setCenter} and {@link FlowCoreMap.setBounds} methods.
+ */
 interface MapAnimationOptions {
+    /** Animation mode */
     mode?: 'jump' | 'ease' | 'fly';
+    /** Animation duration in milliseconds */
     duration?: number;
+    /** Animation easing function.
+     *
+     * A function taking a time in the range 0..1 and returning a number where 0 is
+     * the initial state and 1 is the final state.
+     */
     easing?: (time: number) => number;
 }
 interface MapPaddingOptions {
@@ -1532,38 +2018,103 @@ interface MapPaddingOptions {
     left: number;
 }
 
+/**
+ * This interface defines all event types emitted {@link FlowCoreMap} and
+ * the type of the corresponding event handler.
+ *
+ * {@link FlowCoreMap} extends [EventEmitter](https://github.com/dashed/EventEmitter3) to provide
+ * event handling capabilities. The {@link FlowCoreMap.on} method is used to subscribe to events.
+ *
+ * @example
+ * ```js
+ * map.on('click', (event) => {
+ *  console.log('Map clicked at:', event.lngLat);
+ * });
+ * ```
+ */
 interface MapEventTypes {
+    /**
+     * Emitted when the map is clicked.
+     * @group Mouse Events
+     */
     click: (event: MapMouseEvent) => void;
+    /**
+     * Emitted when the map is double-clicked.
+     * @group Mouse Events
+     */
     dblClick: (event: MapMouseEvent) => void;
+    /**
+     * Emitted when the mouse is moved. Note that this event is throttled to 100ms.
+     *
+     * @group Mouse Events
+     */
     mouseMove: (event: MapMouseEvent) => void;
+    /**
+     * Emitted when the mouse leaves the map bounds.
+     * @group Mouse Events
+     */
     mouseOut: (event: MapMouseEvent) => void;
+    /**
+     * Emitted when the map finishes panning or zooming.
+     *
+     * Note that this event is emitted following user interaction **and**
+     * programmatic changes to the map.
+     * @group Map Events
+     */
     moveEnd: (event: MapEvent) => void;
-    sourceAdded: (event: MapSourceEvent) => void;
-    sourceRemoved: (event: MapSourceEvent) => void;
-    beforeSourceAdded: (event: MapSourceEvent) => void;
-    beforeSourceRemoved: (event: MapSourceEvent) => void;
-    sourceFeatureState: (event: MapSourceEvent) => void;
+    /**
+     * Emitted when the map is destroyed.
+     * @group Map Events
+     */
     destroyed: (event: MapEvent) => void;
+    /**
+     * Emitted when the map has started or finished loading data.
+     * @group Loading Events
+     */
     loading: (event: MapLoadingEvent) => void;
-    beforeStyleChanged: (event: MapStyleChangeEvent) => void;
-    styleChanged: (event: MapStyleChangeEvent) => void;
-    error: (event: FlowMapError) => void;
-}
-interface MapEventTypes {
-    click: (event: MapMouseEvent) => void;
-    dblClick: (event: MapMouseEvent) => void;
-    mouseMove: (event: MapMouseEvent) => void;
-    mouseOut: (event: MapMouseEvent) => void;
-    moveEnd: (event: MapEvent) => void;
+    /**
+     * Emitted after a {@link MapDataSource} has been added to the map.
+     * @group Source Events
+     */
     sourceAdded: (event: MapSourceEvent) => void;
+    /**
+     * Emitted after a {@link MapDataSource} has been removed from the map.
+     * @group Source Events
+     */
     sourceRemoved: (event: MapSourceEvent) => void;
+    /**
+     * Emitted before a {@link MapDataSource} is added to the map.
+     * @group Source Events
+     */
     beforeSourceAdded: (event: MapSourceEvent) => void;
+    /**
+     * Emitted before a {@link MapDataSource} is removed from the map.
+     * @group Source Events
+     */
     beforeSourceRemoved: (event: MapSourceEvent) => void;
+    /**
+     * Emitted when map feature state changes following a call to {@link FlowCoreMap.setFeatureState},
+     * {@link FlowCoreMap.setFeatureStateBulk}, or {@link FlowCoreMap.removeFeatureState}.
+     * @group Source Events
+     */
     sourceFeatureState: (event: MapSourceEvent) => void;
-    destroyed: (event: MapEvent) => void;
-    loading: (event: MapLoadingEvent) => void;
+    /**
+     * Emitted before the map style changes.
+     * @group Style Events
+     */
     beforeStyleChanged: (event: MapStyleChangeEvent) => void;
+    /**
+     * Emitted after the map style has changed.
+     * @group Style Events
+     */
     styleChanged: (event: MapStyleChangeEvent) => void;
+    /**
+     * Emitted when an error has occurred.
+     *
+     * If no error handler is registered, the error will be logged to the console.
+     *
+     * @group Error Events
+     */
     error: (event: FlowMapError) => void;
 }
 type MapEventType = keyof MapEventTypes;
@@ -1723,13 +2274,36 @@ declare class ImageRegistry {
     private loadImage;
 }
 
+/**
+ * Options for creating a {@link MapFeatureStream}.
+ *
+ * See {@link FlowCoreMap.featureStream } for more information.
+ */
 interface FeatureStreamOptions {
+    /** An array of feature IDs to track. Note that {@link MapDataSourceOptions.featureId}
+     * must be set on the map data source to specify which feature property to use as the feature ID.
+     */
     featureIds: Array<string | number>;
+    /** Set to `true` to fire the stream immediately when subscribed. If `false`, the stream will only
+     * emit when feature data changes.
+     */
     fireImmediately?: boolean;
+    /** The map instance. */
     map: FlowCoreMap;
+    /** The map data source ID to track. */
     source: string;
+    /**
+     * The map data source layer to track. This only applies to vector data sources and can be
+     * omitted for Flo.w vector tiles. Defaults to `'geometry'`.
+     */
     sourceLayer?: string;
 }
+/**
+ * A observable stream of map feature data. Subscribe to an instance of this class to receive
+ * updates when map feature data changes.
+ *
+ * See {@link FlowCoreMap.featureStream } for usage information.
+ */
 declare class MapFeatureStream {
     private _boundHandleLoading;
     private _boundHandleSourceFeatureState;
@@ -1737,9 +2311,43 @@ declare class MapFeatureStream {
     private _sourceLoadCount;
     private _sourceLoaded;
     constructor(options: FeatureStreamOptions);
+    /**
+     * Returns feature data corresponding to the requested feature IDs. This is a computed property that will
+     * automatically update when the feature data changes. Accessing this property within a reactive
+     * context will automatically trigger a reactive update.
+     *
+     * :::info
+     * This method provides an alternative to {@link subscribe} for responding to feature data upates.
+     * :::
+     *
+     * @example
+     * ```js
+     * const featureStream = myMap.featureStream({
+     *   featureIds: ['feature1', 'feature2'],
+     *   source: 'my-source'
+     * });
+     *
+     * const disposer = appState.autoRun(() => {
+     *   const featureData = featureStream.featureData;
+     *   console.log('Feature data changed:', featureData);
+     * });
+     * ...
+     * disposer();
+     * ```
+     *
+     */
     get featureData(): Record<string | number, MapFeature>;
+    /** Returns the feature IDs being tracked. */
     get featureIds(): Array<string | number>;
+    /** Update the feature IDs being tracked. */
     set featureIds(featureIds: Array<string | number>);
+    /**
+     * Subscribe to the feature stream. The supplied handler will be called whenever the feature data changes.
+     *
+     * :::warning
+     * Subscriptions should be disposed of when no longer required by calling their `unsubscribe()` method.
+     * :::
+     */
     subscribe(handler: (featureData: Record<string | number, MapFeature>) => void): ISubscription;
     private featureFromMaplibreFeature;
     private handleLoading;
@@ -1749,13 +2357,32 @@ declare class MapFeatureStream {
     private suspend;
 }
 
+/**
+ * Map options supplied when creating a new {@link FlowCoreMap} instance.
+ */
 interface MapOptions<TState extends StateStore = StateStore> extends Omit<MapOptions$1, 'style'> {
+    /** Unique map identifier. */
     id?: string;
+    /** Base map style */
     baseStyle?: string | MapStyleSpecification;
+    /** Map container selector or element. This specifies where in the DOM the map will be inserted.  */
     container: string | HTMLElement;
+    /**
+     * Click tolerance in pixels. This defines a radius around the mouse position when selecting map features.
+     * Increase this value to make clicking on line features easier. (Default: 0)
+     */
     featureClickTolerance?: number;
+    /**
+     * Flow context identifier. This defines the {@link FlowContext} to use for data requests and reactive
+     * state. If not specified, the default context will be used. Note that the map initialization will
+     * pause until the context is initialized and ready to be used.
+     */
     contextId?: string;
 }
+/**
+ *
+ *
+ */
 declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventEmitter$1<MapEventTypes> {
     private static _defaultOptions;
     private _context;
@@ -1769,12 +2396,78 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
     private _style;
     private _styleUpdateSubscription;
     private _throttledMouseMove;
-    maplibreMap: Map;
+    private _maplibreMap;
+    /**
+     * Return the underlying [Maplibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) map instance. This can be used to
+     * access the full Maplibre API for advanced use cases.
+     *
+     * :::danger
+     * Use with caution. Directly modifying the Maplibre map instance can cause unexpected behavior particularly if
+     * the changes conflict with the {@link FlowCoreMap} state. Do not call any Maplibre methods that add or
+     * remove map layers or data sources, or modify the map style directly.
+     * :::
+     */
+    get maplibreMap(): Map;
+    /**
+     * Constructs a new `FlowCoreMap` instance.
+     *
+     * The map will be initialized with the specified options and base style.
+     * When the map API is ready for use, the {@link initialized} promise will resolve.
+     *
+     * @example
+     * ```js
+     * const map = new FlowCoreMap({
+     *   id: 'my-map',
+     *   container: '#map-container',
+     *   baseStyle: 'fjord',
+     * });
+     *
+     * map.initialized.then(() => {
+     *  console.log('Map initialized');
+     *  // Configure map data sources and layers
+     *  ...
+     * });
+     * ```
+     *
+     */
     constructor(options: MapOptions<TState>);
+    /**
+     * Returns the {@link FlowContext} associated with this map.
+     */
     get context(): FlowContext<TState>;
+    /**
+     * Returns the map's container element.
+     */
     get container(): HTMLElement;
+    /**
+     * Returns the map identifier.
+     */
     get id(): string;
+    /**
+     * Returns a promise that resolves when the map is fully initialized and ready for use.
+     *
+     * @example
+     * ```js
+     * map.initialized.then(() => {
+     *   console.log('Map ready fo use');
+     *   // Configure map data sources and layers
+     *   ...
+     * });
+     * ```
+     */
     get initialized(): Promise<void>;
+    /**
+     * Returns the full Maplibre style specification for this map. This is a `computed` property and will trigger
+     * reactive updates when accessed in a reactive context.
+     *
+     * @example
+     * ```js
+     * stateStore.autorun(() => {
+     *    const style = map.styleSpecification;
+     *    console.log('Map style was updated', style);
+     * });
+     * ```
+     */
     get styleSpecification(): MapStyleSpecification;
     /**
      * @internal
@@ -1782,24 +2475,160 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
      * Used by map export to get images added to map.
      */
     get imageRegistry(): ImageRegistry;
+    /**
+     * Adds a {@link MapLayer} to the map.
+     *
+     * @example
+     * Create a new circle layer and add it to the map:
+     * ```js
+     * const circleLayer = new MapLayer({
+     *    id: "circle-layer",
+     *    type: "circle",
+     *    source: "airquality",
+     *    style: layerStyle("circle")
+     *      .circleColor('red')
+     *      .build()
+     * });
+     *
+     * map.addLayer(layer);
+     * ```
+     */
     addLayer(layer: MapLayer): MapLayer;
+    /**
+     * Creates a new {@link MapLayer} instance using the provided options
+     * and adds it to the map.
+     *
+     * @example
+     * Create a new circle layer and add it to the map in a single step:
+     * ```js
+     * map.addLayer({
+     *    id: "circle-layer",
+     *    type: "circle",
+     *    source: "airquality",
+     *    style: layerStyle("circle")
+     *      .circleColor('red')
+     *      .build()
+     * });
+     * ```
+     */
     addLayer(layerOptions: MapLayerOptions): MapLayer;
+    /**
+     * Adds a {@link MapDataSource} to the map.
+     */
     addSource(source: MapDataSource): MapDataSource;
+    /**
+     * Creates a new {@link MapDataSource} instance using the provided options
+     * and adds it to the map.
+     */
     addSource(sourceOptions: MapDataSourceOptions): MapDataSource;
+    /**
+     * Destroys the map instance and removes it from the DOM.
+     */
     destroy(): void;
+    /**
+     * Called internally and by map plugins to notify an error.
+     *
+     * To handle errors, attach an error event listener to the map instance as follows:
+     *
+     * ```js
+     * map.on('error', (error) => {
+     *   // Handle error
+     *   console.error(`A map error occurred: ${error.message}`);
+     * });
+     * ```
+     *
+     * If no error event listener is attached, the error will be logged to the console.
+     */
     emitError(message: string, originalError?: Error): void;
+    /** Used internally and by plugins to emit a map event. */
     emitEvent<T extends MapEvent<keyof MapEventTypes, any>>(event: T): void;
+    /**
+     * Returns an observable {@link MapFeatureStream} for the specified feature identifiers. The feature stream
+     * will emit feature data for the specified features as their properties updated.
+     * Call the {@link MapFeatureStream.subscribe} method to receive feature data updates.
+     *
+     * :::warning
+     * All subscriptions should be disposed of when no longer needed.
+     * :::
+     *
+     * This method is used internally by the map popup plugin to receive feature properties for rendering
+     * popup content but can be used whenever you want to track feature data changes for a set of features.
+     *
+     * :::warning
+     * The feature stream will only emit feature data for features that are currently visible on the map. If the
+     * user pans the map away from the requested features, the map will eventually unload the features and will
+     * stop providing updates.
+     * :::
+     *
+     * @example
+     * ```js
+     * const subscription = map.featureStream({
+     *  source: 'my-data-source',
+     *  featureIds: ['feature-1', 'feature-2']
+     * }).subscribe((featureData) => {
+     *   console.log('Feature data updated', featureData);
+     * });
+     * ...
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @param options
+     * @returns
+     */
     featureStream(options: Omit<FeatureStreamOptions, 'map'>): MapFeatureStream;
-    private get formattedName();
+    /**
+     * Returns the feature state for the specified map feature.
+     *
+     * See ##TODO for more information about map feature state.
+     *
+     * @param feature - Map feature identifier
+     */
     getFeatureState(feature: MapFeatureIdentifier): Record<string, any>;
+    /**
+     * Returns the {@link MapLayer} with the specified ID.
+     *
+     * @param id - Map layer ID
+     */
     getLayer(id: string): MapLayer;
+    /**
+     * Returns all map layers that match the specified filter function.
+     * If no filter is specified, all layers are returned.
+     *
+     * @param filter - Filter function. Return `true` to include the map layer in the result.
+     */
     getLayers(filter?: (layer: MapLayer) => boolean): MapLayer[];
+    /**
+     * Returns a registered map plugin.
+     *
+     * @example
+     * Retrieve the popup plugin from a map:
+     * ```js
+     * const popupPlugin = map.getPlugin(PopupPlugin);
+     * popupPlugin.registerPopup('my-popup', {...});
+     * ```
+     *
+     * @param pluginOrName - Plugin constructor or name as a string.
+     */
     getPlugin<T extends MapPluginBase = MapPluginBase>(pluginOrName: PluginConstructor<T> | string): T;
+    /**
+     * Returns the {@link MapDataSource} with the specified ID.
+     *
+     * @param id - Data source ID
+     */
     getSource(id: string): MapDataSource;
+    /**
+     * Returns all {@link MapDataSource} instance that match the specified filter function.
+     * If no filter is specified, all data sources are returned.
+     *
+     * @param filter - Filter function. Return `true` to include the map data source in the result.
+     */
     getSources(filter?: (source: MapDataSource) => boolean): MapDataSource[];
     /**
      * Register a map icon image.
      *
+     * The image can be used on [symbol-type map layers](/flow-rdf-core/layer-reference/symbol) by specifying the image ID
+     * as the [`icon-image`](/flow-rdf-core/layer-reference/symbol#icon-image) property.
+     *
      * @param id Image ID.
      * @param src Image source URL.
      * @param width Image display width.
@@ -1809,35 +2638,151 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
      */
     registerImage(id: string, src: string, width?: number, height?: number, pixelDensity?: number, recolor?: boolean): void;
     /**
-     * Programmatically remove feature state properties from a map feature.
+     * Remove feature state properties from a map feature.
      *
      * @param feature Feature to modify. Specify `null` to modify all map features.
      * @param key Feature state key to remove. Specify `null` to remove all feature state for specified feature(s).
      */
     removeFeatureState(feature: PartialBy<MapFeatureIdentifier, 'id'>, key?: string, fireEvent?: boolean): void;
+    /**
+     * Remove the specified {@link MapLayer} from the map.
+     * @param id - Map layer ID
+     */
     removeLayer(id: string): this;
+    /**
+     * Remove the specified {@link MapDataSource} from the map.
+     * @param id - Map data source ID
+     */
     removeSource(id: string, removeLayers?: boolean): this;
+    /**
+     * Set the map's base style.
+     *
+     * ##TODO list of available base styles
+     *
+     * @param style - A style identifier or a Maplibre style specification.
+     */
     setBaseStyle(style: string | MapStyleSpecification): Promise<void>;
+    /**
+     * Returns the map's current center, bearing, pitch, and zoom level.
+     */
     getCenter(): MapCenterOptions;
-    setCenter(center: Partial<MapCenterOptions>, animationOptions?: MapAnimationOptions): this;
+    /**
+     * Sets one or more of the map's center, bearing, pitch, and/or zoom level.
+     * Animation options can be specified to animate the transition. If animation options are not specified,
+     * the map will jump to the new view immediately.
+     *
+     * A promise is returned that resolves when the map has finished moving.
+     *
+     * @example
+     * Zoom the map and log to console when finished:
+     * ```js
+     * const { zoom } = map.getCenter();
+     * map.setCenter({zoom: zoom + 2}, {mode: 'ease', duration: 2000}).then(() => {
+     *   console.log('Map zoomed ');
+     * });
+     * ```
+     *
+     * @param center
+     * @param animationOptions
+     * @returns A promise that resolves when the map has finished moving.
+     */
+    setCenter(center: Partial<MapCenterOptions>, animationOptions?: MapAnimationOptions): Promise<void>;
+    /**
+     * Returns the map's current bounds in degrees as an array of `[west, south, east, north]`.
+     *
+     * See also {@link getVisibleBounds}.
+     */
     getBounds(): [number, number, number, number];
+    /**
+     * Set the map's bounds to the specified bounding box.
+     *
+     * Animation options can be specified to animate the transition. If animation options are not specified,
+     * the map will jump to the new view immediately.
+     *
+     * Specify the `padding` option to add padding around the bounding box in pixels.
+     *
+     * @param bounds - Bounding box in degrees as an array of `[west, south, east, north]`.
+     * @param options - Animation and padding options.
+     */
     setBounds(bounds: [number, number, number, number], options?: MapAnimationOptions & {
         padding?: number;
     }): void;
+    /**
+     * Returns the map's current visible bounds in degrees as an array of `[west, south, east, north]`.
+     *
+     * The visible bounds may differ from the map's full bounds if fixed positioning is used. With fixed positioning,
+     * the map's canvas extends outside its container underneath other elements like side-bars. This allows side-bars
+     * to be opened and closed without re-rendering the map. The visible bounds represent the region of the map that
+     * is currently visible within the map's container.
+     *
+     * See also {@link getBounds}.
+     */
     getVisibleBounds(): [number, number, number, number];
     /**
-     * Programmatically set feature state properties for a map feature.
+     * Set feature state properties for a map feature.
+     *
+     * ##TODO more info on feature state
      *
      * @param feature Feature to modify.
      * @param state Feature state properties to set.
      */
     setFeatureState(feature: MapFeatureIdentifier, state: Record<string, any>, fireEvent?: boolean): void;
+    /**
+     * Set feature state properties in bulk for multiple map features.
+     *
+     * ##TODO more info on feature state
+     *
+     * @param feature Feature to modify.
+     * @param state Feature state properties to set.
+     */
     setFeatureStateBulk(sourceId: MapSourceIdentifier, featureState: {
         [featureId: MapFeatureId]: Record<string, any>;
     }): void;
+    /**
+     * Run a series of map updates as a single transaction. This can be used to batch multiple updates
+     * while only triggering a single re-render of the map.
+     *
+     * @example
+     * ```js
+     * map.transaction(() => {
+     *   map.addSource({ ... });
+     *   map.addLayer({ ... });
+     *   map.addLayer({ ... });
+     * });
+     * ```
+     *
+     * @param fn - Function containing map updates to run as a transaction.
+     */
     transaction(fn: () => void): void;
+    /**
+     * Register a map plugin with the map instance.
+     *
+     * Some plugins may require additional options to be passed when registering the plugin.
+     *
+     * @example
+     * Register the HoverEffectPlugin with the map:
+     * ```js
+     * map.usePlugin(HoverEffectPlugin);
+     * ```
+     *
+     * @param plugin - Plugin constructor or name
+     * @param options - Plugin-specific options
+     * @returns The plugin instance
+     */
     usePlugin<T extends MapPluginBase>(plugin: PluginConstructor<T>, options?: PluginOptionsType<T>): T;
+    /**
+     * Register multiple map plugins with the map instance.
+     *
+     * @example
+     * Register multiple plugins with the map:
+     * ```js
+     * map.usePlugins([HoverEffectPlugin, PopupPlugin]);
+     * ```
+     *
+     * @param plugins - Array of plugin constructors to register
+     */
     usePlugins(plugins: PluginConstructor[]): void;
+    private get formattedName();
     private bindMapEvents;
     private featureFromMaplibreFeature;
     private featureQueryBox;
@@ -1851,6 +2796,74 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
     private updateMapStyle;
 }
 
+type MapPopupTemplateFn<TState extends StateStore = StateStore> = (feature: MapFeature | null, state: TState) => string | Node | lit.TemplateResult;
+interface MapPopupEvents {
+    closed: (popup: MapPopup) => void;
+}
+/**
+ * [[MapPopup]] options.
+ */
+interface MapPopupOptions {
+    /** Specify a CSS class to add to the popup. */
+    class?: string;
+    /** Enable 'close' button. */
+    closeButton?: boolean;
+    /** Enable closing popup on click on map. */
+    closeOnClick?: boolean;
+    /** Enable closing pop when map is moved. */
+    closeOnMove?: boolean;
+    /** Specify popup content as HTML string or HTML node. */
+    content: string | Node | MapPopupTemplateFn;
+    /** Maximum width of popup in CSS units. */
+    maxWidth?: string;
+    trackFeature?: boolean;
+}
+/**
+ * Core functionality for Flo.w map popups.
+ *
+ *
+ */
+declare class MapPopup extends EventEmitter$1<MapPopupEvents> {
+    readonly map: FlowCoreMap;
+    readonly options: MapPopupOptions;
+    private _feature?;
+    private _contentContainer;
+    private _featureStream;
+    private _maplibrePopup;
+    private _featureStreamDisposer?;
+    /**
+     * Constructs a new `MapPopup` instance.
+     *
+     * This is called by the `FlowMap::openPopup` method.
+     *
+     * @param map Parent Flo.w map.
+     * @param options Popup options.
+     */
+    constructor(map: FlowCoreMap, options: MapPopupOptions);
+    get feature(): MapFeatureIdentifier | undefined;
+    /**
+     * Close the popup.
+     */
+    close(): void;
+    /**
+     * Move the popup to a new location.
+     *
+     * @param lngLat New location.
+     */
+    moveTo(lngLat: [number, number]): void;
+    /**
+     * Open the popup at the specified location.
+     *
+     * @param lngLat Popup location.
+     */
+    open(event: MapMouseEvent): void;
+    open(lngLat: [number, number], feature?: MapFeatureIdentifier): void;
+    private cssClasses;
+    private handleFeatureUpdate;
+    private popupCloseHandler;
+    private renderContent;
+}
+
 /**
  * The `MapRegistry` is a container for [[FlowCoreMap]] instances.
  *
@@ -1861,14 +2874,18 @@ declare class MapRegistry {
     /**
      * Register a Flo.w map.
      *
-     * @param id Map ID.
      * @param map Map to register.
      */
     registerMap(map: FlowCoreMap): FlowCoreMap;
     /**
      * Un-register a Flo.w map.
      *
-     * @param id Map ID.
+     * ```mermaid
+     * graph TB
+     *   mermaid.js --> TypeDoc;
+     * ```
+     *
+     * @param map - the map to unregister.
      */
     unregisterMap(map: FlowCoreMap): void;
     /**
@@ -1881,6 +2898,135 @@ declare class MapRegistry {
     getMap(id: string): Promise<FlowCoreMap>;
 }
 
+/** Result format of a [[Query]]. */
+type QueryResultFormat = 'json' | 'geojson' | 'csv';
+/** [[FlowQueryDefinition]] 'attributes' entry. */
+type QueryAttribute = string | [any, string];
+/**
+ * [[FlowQueryDefinition]] 'where' clauses.
+ */
+interface QueryWhereClauses {
+    [attribute: string]: any;
+}
+/**
+ * [[FlowQueryDefinition]] extra parameters.
+ */
+interface QueryExtraParams {
+    [key: string]: string | number;
+}
+/**
+ * [[FlowQueryDefinition]] 'order' clause.
+ *
+ * A field name or [field, asc/desc] tuple.
+ */
+type QueryOrderClause = string | number | [string | number, 'asc' | 'desc'];
+interface QuerySampleOptions {
+    percentage: number;
+    method?: 'system' | 'bernoulli';
+    seed?: number;
+}
+/**
+ * Definition of a Flo.w reactive dataset query.
+ */
+interface QueryDefinition {
+    /** ID of dataset to query. */
+    datasetId: string;
+    /** Attributes to return in results. */
+    attributes?: QueryAttribute[];
+    /** DISTINCT ON attributes */
+    distinct?: string | string[];
+    /** Filter results using 'where' clauses. */
+    where?: QueryWhereClauses;
+    /** Sort results by attributes. */
+    order?: QueryOrderClause[];
+    /** Group results by attributes. */
+    group?: (string | number)[];
+    /** Start offset of returned results */
+    offset?: number;
+    /** Limit number of returned results */
+    limit?: number;
+    /** Format of returned data. */
+    format?: QueryResultFormat;
+    /** Additional query parameters. */
+    params?: QueryExtraParams;
+    /** Sampling options. */
+    sample?: QuerySampleOptions;
+}
+interface QueryOptions {
+    id?: string;
+    fireImmediately?: boolean;
+    delay?: number;
+    contextId?: string;
+}
+/**
+ * [[FlowQuery]] query definition function.
+ *
+ * @typeParam TState  Type of application state.
+ */
+type QueryDefinitionFn<TState> = (this: TState, store: TState) => QueryDefinition | Promise<QueryDefinition> | null;
+/**
+ * [[FlowQuery]] result transform function.
+ *
+ * @typeParam T  Type of transformed query results.
+ */
+type QueryResultTransformFn<T = any> = (results: any) => T | null;
+
+declare class Query<TResults, TState extends StateStore = any> {
+    private queryFn;
+    private static _defaultOptions;
+    static setDefaultOptions(options: QueryOptions): void;
+    private _options;
+    private _committer;
+    private _disposer;
+    private _transformFn;
+    private get formattedName();
+    get id(): string;
+    results: TResults | null;
+    busy: boolean;
+    error: Error | null;
+    constructor(queryFn: QueryDefinitionFn<TState | null>, transformFn?: QueryResultTransformFn<TResults>, options?: QueryOptions);
+    destroy(): void;
+    runImmediately(): Promise<TResults | null>;
+    private wake;
+    private sleep;
+    private runQuery;
+}
+declare function query<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult, TState>;
+declare function query<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult>, options?: QueryOptions): Query<TResult, TState>;
+declare function queryMany<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult[], TState>;
+declare function queryMany<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult[]>, options?: QueryOptions): Query<TResult[], TState>;
+declare function queryOne<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, options: QueryOptions): Query<TResult, TState>;
+declare function queryOne<TResult = any, TState extends StateStore = any>(queryFn: QueryDefinitionFn<TState>, transformFn?: QueryResultTransformFn<TResult>, options?: QueryOptions): Query<TResult, TState>;
+
+/**
+ * The `QueryRegistry` is a container for [[Query]] instances.
+ *
+ * Queries can be registered and retrieved by ID.
+ */
+declare class QueryRegistry {
+    private _queries;
+    /**
+     * Register a Flo.w reactive query.
+     *
+     * @param query Query to register.
+     */
+    registerQuery(query: Query<any>): void;
+    /**
+     * Un-register a Flo.w reactive query.
+     *
+     * @param query Query to unregister.
+     */
+    unregisterQuery(query: Query<any>): void;
+    /**
+     * Retrieve the specified query.
+     *
+     * This method returns a promise that resolves when the query has been initialized.
+     *
+     * @param id Map ID.
+     */
+    getQuery<TResults = any, TState extends StateStore = any>(id: string): Promise<Query<TResults, TState>>;
+}
+
 declare const DEFAULT_CONTEXT_ID = "default";
 interface FlowContextOptions<TState extends StateStore = StateStore> {
     id?: string;
@@ -1904,13 +3050,10 @@ declare class FlowContext<TState extends StateStore = StateStore> {
      *
      * Use [[ContextRegistry.initializeContext]] to create an instance of `FlowCoreContext`.
      *
-     * @param id The ID of the context.
-     * @param host The Flo.w Engine host URL.
-     * @param apiKey The Flo.w Engine API key.
-     * @param enableDebug Set to `true` to enable the debugger.
+     * @param options - The context options.
      */
     constructor(options: FlowContextOptions<TState>);
     evaluateExpression(expr: string): any;
 }
 
-export { type QueryOptions as $, type Annotation as A, BackgroundLayerStyleBuilder as B, CircleLayerStyleBuilder as C, DEFAULT_CONTEXT_ID as D, type MapFeatureIdentifier as E, type FlowContextOptions as F, type MapPaddingOptions as G, HeatmapLayerStyleBuilder as H, type MapSourceIdentifier as I, type MapOptions as J, FlowCoreMap as K, LineLayerStyleBuilder as L, type MapStyleSpecification as M, Query as N, query as O, queryMany as P, QueryRegistry as Q, ReactiveExpression as R, StateStore as S, queryOne as T, type QueryResultFormat as U, type QueryAttribute as V, type QueryWhereClauses as W, type QueryExtraParams as X, type QueryOrderClause as Y, type QuerySampleOptions as Z, type QueryDefinition as _, FlowContext as a, type QueryDefinitionFn as a0, type QueryResultTransformFn as a1, traceReaction as a2, type Path as a3, type PathValue as a4, type StoreConstructor as a5, type StoreAnnotations as a6, type SerializationFormat as a7, MapEvent as a8, type MapFeatureId as a9, MapPluginBase as aa, PluginManager as ab, MapSourceEvent as ac, MapMouseEvent as ad, MapFeatureStream as ae, type PartialBy as af, MapStyleChangeEvent as ag, type PluginOptionsType as ah, type PluginEventsType as ai, type PluginConstructor as aj, type EventHandlers as ak, MapDataSource as b, MapLayer as c, MapRegistry as d, type FlowEngineEndpoint as e, type MapLayerType as f, FillLayerStyleBuilder as g, SymbolLayerStyleBuilder as h, FillExtrusionLayerStyleBuilder as i, RasterLayerStyleBuilder as j, HillshadeLayerStyleBuilder as k, layerStyle as l, MapLayerStyleBuilder as m, StyleExpression as n, expr as o, type MapLayerOptions as p, type MapLayerExpression as q, type MapLayerSpecification as r, type MapLayerPropertyMetadataIndex as s, type MapDataSourceType as t, type MapDataSourceOptions as u, type MapDataSourceSpecification as v, type MapGeojsonData as w, type MapAnimationOptions as x, type MapCenterOptions as y, type MapFeature as z };
+export { type MapOptions as $, type Annotation as A, BackgroundLayerStyleBuilder as B, CircleLayerStyleBuilder as C, DEFAULT_CONTEXT_ID as D, type MapLayerExpression as E, type FlowContextOptions as F, type MapLayerSpecification as G, HeatmapLayerStyleBuilder as H, type MapLayerPropertyMetadataIndex as I, type MapDataSourceType as J, type MapDataSourceOptions as K, LineLayerStyleBuilder as L, type MapStyleSpecification as M, type MapDataSourceSpecification as N, type MapGeojsonData as O, type ParserExpression as P, QueryRegistry as Q, ReactiveExpression as R, StateStore as S, type MapAnimationOptions as T, type MapCenterOptions as U, type MapFeature as V, type MapFeatureIdentifier as W, type MapPaddingOptions as X, type MapSourceIdentifier as Y, MapFeatureStream as Z, type FeatureStreamOptions as _, MapDataSource as a, FlowCoreMap as a0, type MapEventTypes as a1, type MapEventType as a2, MapEvent as a3, MapMouseEvent as a4, MapSourceEvent as a5, MapLoadingEvent as a6, MapStyleChangeEvent as a7, type MapPopupTemplateFn as a8, type MapPopupOptions as a9, type PluginEventsType as aA, type PluginConstructor as aB, type EventHandlers as aC, MapPopup as aa, Query as ab, query as ac, queryMany as ad, queryOne as ae, type QueryResultFormat as af, type QueryAttribute as ag, type QueryWhereClauses as ah, type QueryExtraParams as ai, type QueryOrderClause as aj, type QuerySampleOptions as ak, type QueryDefinition as al, type QueryOptions as am, type QueryDefinitionFn as an, type QueryResultTransformFn as ao, traceReaction as ap, type Path as aq, type PathValue as ar, type StoreConstructor as as, type StoreAnnotations as at, type SerializationFormat as au, type MapFeatureId as av, MapPluginBase as aw, PluginManager as ax, type PartialBy as ay, type PluginOptionsType as az, MapLayer as b, FlowContext as c, FlowCoreError as d, FlowCoreExpressionError as e, FlowMapError as f, MapRegistry as g, type FlowCoreExpressionCustomFunction as h, type FlowCoreExpressionCustomFunctionSignature as i, type FlowCoreExpressionCustomFunctions as j, type ParserExpressionWithIndex as k, type ParserFunctionExpression as l, type ParserIndex as m, type ParserProgram as n, type FlowEngineEndpoint as o, type MapLayerType as p, FillLayerStyleBuilder as q, SymbolLayerStyleBuilder as r, FillExtrusionLayerStyleBuilder as s, RasterLayerStyleBuilder as t, HillshadeLayerStyleBuilder as u, layerStyle as v, MapLayerStyleBuilder as w, StyleExpression as x, expr as y, type MapLayerOptions as z };