@fxi/zartigl 0.4.1 → 0.4.2

package/README.md

@@ -37,30 +37,29 @@ const map = new maplibregl.Map({
   zoom: 2,
 });
 
+const currents = searchCatalog("ocean-current-velocity")[0];
 const z = new Zartigl({
   id: "zarr-layer",
   map,
   catalog,
+  layer: currents.id,
   source: "auto",
   // Optional: expose only the month ending at the latest available timestamp.
   timeRange: { trailing: "P1M" },
+  time: new Date("2025-01-01T00:00:00Z"),
+  depth: 0,
+  settings: { palette: "rdylbu", opacity: 0.9 },
   geoVideo: { autoplay: false, loop: true, playbackRate: 1 },
 });
 
-const currents = searchCatalog("ocean-current-velocity")[0];
-await z.setLayer(currents.id);
-z.setTimeAndDepth(new Date("2025-01-01T00:00:00Z"), 0);
-z.updateSettings({
-  palette: "rdylbu",
-  opacity: 0.9,
-});
+z.on("status", (status) => console.log(status.phase));
+await z.init();
 ```
 
-Pass a source UUID (or source type) as the optional second argument when entry
-and source should switch atomically. `setSource()` changes the source of the
-active entry.
+Use `await z.update({ ... })` to change any subset of the active configuration.
+Pass `layer` and `source` together when both should switch atomically.
 
-`setLayer()` resolves after the field store's consolidated metadata and coordinate axes have loaded. Metadata getters are therefore authoritative after the awaited call, including exact values for irregular time axes.
+`init()` and layer/source updates resolve after consolidated metadata and coordinate axes have loaded. Metadata getters are therefore authoritative afterward, including exact values for irregular time axes.
 
 The root import does not bundle the catalog presets. Import catalog data from `@fxi/zartigl/catalog` only when you want the built-in catalog.
 
@@ -115,13 +114,12 @@ z.on("status", (status) => {
 // GeoVideo uses native media playback and reports scientific time updates.
 z.on("timeChange", (time) => console.log(new Date(time)));
 z.on("playbackChange", (playing) => console.log({ playing }));
-z.setPlaybackRate(2);
-z.setLoop(false);
+await z.update({ geoVideo: { playbackRate: 2, loop: false } });
 
 // Embedding applications can stop rendering and abort field requests while
 // retaining the latest requested time/depth for one reload on resume.
 z.suspend();
-z.setTime(new Date("2025-02-01T00:00:00Z"));
+await z.update({ time: new Date("2025-02-01T00:00:00Z") });
 z.resume();
 
 const series = await z.queryTimeSeries({
@@ -227,10 +225,13 @@ const map = new maplibregl.Map({
 
 map.setProjection({ type: "globe" });
 
+const ice = searchCatalog("sea-ice-thickness")[0];
+const video = ice.sources.find((source) => source.type === "geovideo")!;
 const z = new Zartigl({
   map,
   catalog,
-  source: "auto",
+  layer: ice.id,
+  source: video.id,
   geoVideo: {
     autoplay: true,
     loop: true,
@@ -238,13 +239,10 @@ const z = new Zartigl({
   },
 });
 
-const ice = searchCatalog("sea-ice-thickness")[0];
-await z.setLayer(ice.id);
-await z.setSource(ice.sources.find((source) => source.type === "geovideo")!.id);
+await z.init();
 ```
 
-`setSource()` selects the entry's published GeoVideo manifest by its stable
-source UUID. Globe projection demonstrates its polar
+The source UUID selects the entry's published GeoVideo manifest. Globe projection demonstrates its polar
 coverage. `loop` and `playbackRate` are optional playback settings. Browsers
 may restrict autoplay, so embedding applications should provide a user-gesture
 fallback when necessary.

package/dist/zartigl.d.ts

@@ -4,6 +4,8 @@ import { Map as Map_2 } from 'maplibre-gl';
 
 export declare function buildMapxWidgetSnippet(options: MapxWidgetSnippetOptions): string;
 
+export declare function buildStandaloneDemoHtml(options: StandaloneDemoSnippetOptions): string;
+
 export declare function buildStandaloneDemoSnippet(options: StandaloneDemoSnippetOptions): string;
 
 export declare function buildWmtsLegendUrl(options: {
@@ -1192,10 +1194,13 @@ export declare class Zartigl {
     private readonly id;
     private readonly map;
     private readonly catalog;
+    private readonly initialLayer;
+    private readonly initialTime?;
+    private readonly initialDepth?;
     private sourcePreference;
     private timeRange?;
     private fullTimeMeta;
-    private readonly autoplay;
+    private autoplay;
     private loop;
     private playbackRate;
     private readonly metadata?;
@@ -1222,6 +1227,9 @@ export declare class Zartigl {
     private activeFieldSource;
     private switchGeneration;
     private destroyed;
+    private initialized;
+    private initStarted;
+    private updateQueue;
     private suspended;
     private attachQueued;
     private querySources;
@@ -1230,24 +1238,26 @@ export declare class Zartigl {
     private readonly onStyleData;
     private readonly onMapIdle;
     constructor(options: ZartiglOptions);
-    setLayer(id: string, preference?: CatalogSourcePreference): Promise<void>;
-    setSource(preference: CatalogSourcePreference): Promise<void>;
-    show(): void;
-    hide(): void;
+    init(): Promise<void>;
+    update(change: ZartiglUpdate): Promise<void>;
+    private applyUpdate;
+    private loadLayer;
+    private changeSource;
+    private applyVisible;
     /** Pause rendering and abort field requests without discarding layer state. */
     suspend(): void;
     /** Resume rendering and load only the latest requested time/depth state. */
     resume(): void;
     destroy(): void;
-    setTime(time: Date | string | number): void;
+    private applyTime;
     play(): Promise<void>;
     pause(): void;
-    setLoop(loop: boolean): void;
-    setPlaybackRate(rate: number): void;
+    private applyLoop;
+    private applyPlaybackRate;
     /** Apply or clear a time window without rebuilding source metadata or the map layer. */
-    setTimeRange(range?: TimeRange | null): TimeMeta;
-    setDepth(depth: number): void;
-    setTimeAndDepth(time: Date | string | number, depth: number): void;
+    private applyTimeRange;
+    private applyDepth;
+    private applyTimeAndDepth;
     on<K extends keyof ZartiglEventMap>(event: K, handler: ZartiglEventMap[K]): this;
     off<K extends keyof ZartiglEventMap>(event: K, handler: ZartiglEventMap[K]): this;
     getTimeMeta(options?: {
@@ -1271,7 +1281,7 @@ export declare class Zartigl {
     /** Whether palette/domain styling is applied to values in the active renderer. */
     supportsDynamicStyle(): boolean;
     getDebugInfo(): ZartiglDebugInfo;
-    updateSettings(settings: Partial<ZartiglSettings>): void;
+    private applySettings;
     queryTimeSeries(options: QueryPointOptions): Promise<ZarrPointSeriesResult>;
     queryDepthProfile(options: QueryDepthProfileOptions): Promise<ZarrPointSeriesResult>;
     private attachWhenReady;
@@ -1345,8 +1355,11 @@ export declare interface ZartiglOptions {
     id?: string;
     map: Map_2;
     catalog: Catalog;
+    layer: string;
     source?: CatalogSourcePreference;
     timeRange?: TimeRange;
+    time?: Date | string | number;
+    depth?: number;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;
     settings?: Partial<ZartiglSettings>;
@@ -1393,4 +1406,15 @@ export declare type ZartiglStatus = {
     error: Error;
 };
 
+export declare interface ZartiglUpdate {
+    layer?: string;
+    source?: CatalogSourcePreference;
+    timeRange?: TimeRange | null;
+    time?: Date | string | number;
+    depth?: number;
+    settings?: Partial<ZartiglSettings>;
+    geoVideo?: GeoVideoOptions;
+    visible?: boolean;
+}
+
 export { }