@tileflow/core 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/build.js

@@ -7953,6 +7953,9 @@ function compareCodeUnits3(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+// src/layer-domain.ts
+var tileflowLayerDomainMetadataKey = "tileflow:domain";
+
 // src/cartography/domains.ts
 var tileflowLayerDomains = Object.freeze([
   ...tileflowSemanticModuleNames,
@@ -8326,6 +8329,11 @@ function featureState(name) {
   if (!key) throw new Error("expr.featureState requires a non-empty state key.");
   return make(["feature-state", key]);
 }
+function globalState(name) {
+  const key = name.trim();
+  if (!key) throw new Error("expr.globalState requires a non-empty state key.");
+  return make(["global-state", key]);
+}
 function variable(name) {
   const key = name.trim();
   if (!key) throw new Error("expr.var requires a non-empty variable name.");
@@ -8568,6 +8576,12 @@ function visitExpression(value, path, variables, issues) {
       }
       return;
     }
+    case "global-state": {
+      if (exact(2) && !isNonEmptyString(value[1])) {
+        addExpressionIssue(issues, [...path, 1], "Global-state keys must be non-empty strings.");
+      }
+      return;
+    }
     case "var": {
       if (exact(2)) {
         if (!isNonEmptyString(value[1])) {
@@ -8834,6 +8848,7 @@ var expr = Object.freeze({
   has,
   id,
   featureState,
+  globalState,
   interpolate: interpolate2,
   let: letValue,
   literal,
@@ -14091,8 +14106,11 @@ function finalizeTileflowLayers(input) {
     }
     const metadata = isRecord8(layer.metadata) ? { ...layer.metadata } : void 0;
     if (metadata) {
+      const owner = metadata[tileflowCompilerMetadataKeys.owner];
       delete metadata[tileflowCompilerProvenanceMetadataKey];
       for (const key of Object.values(tileflowCompilerMetadataKeys)) delete metadata[key];
+      if (tileflowLayerDomains.includes(owner))
+        metadata[tileflowLayerDomainMetadataKey] = owner;
     }
     return {
       ...layer,

package/dist/index.d.ts

@@ -169,6 +169,7 @@ declare function toNumber(value: TileflowDataExpressionInput<unknown>, fallback?
 declare function toBoolean(value: TileflowDataExpressionInput<unknown>, fallback?: TileflowDataExpressionInput<boolean>): TileflowExpression<boolean>;
 declare function toString(value: TileflowDataExpressionInput<unknown>): TileflowExpression<string>;
 declare function featureState(name: string): TileflowExpression<unknown>;
+declare function globalState(name: string): TileflowExpression<unknown>;
 declare function variable<T>(name: string): TileflowExpression<T>;
 declare function letValue<TBinding, TResult>(name: string, value: TileflowDataExpressionInput<TBinding>, body: TileflowDataExpressionInput<TResult>): TileflowExpression<TileflowDataExpressionResult<TResult>>;
 declare function abs(value: TileflowDataExpressionInput<number>): TileflowExpression<number>;
@@ -211,6 +212,7 @@ declare const expr: Readonly<{
     has: typeof has;
     id: typeof id;
     featureState: typeof featureState;
+    globalState: typeof globalState;
     interpolate: typeof interpolate;
     let: typeof letValue;
     literal: typeof literal;

package/dist/index.js

@@ -9316,6 +9316,9 @@ function compareCodeUnits3(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+// src/layer-domain.ts
+var tileflowLayerDomainMetadataKey = "tileflow:domain";
+
 // src/cartography/domains.ts
 var tileflowLayerDomains = Object.freeze([
   ...tileflowSemanticModuleNames,
@@ -9677,6 +9680,11 @@ function featureState(name) {
   if (!key) throw new Error("expr.featureState requires a non-empty state key.");
   return make(["feature-state", key]);
 }
+function globalState(name) {
+  const key = name.trim();
+  if (!key) throw new Error("expr.globalState requires a non-empty state key.");
+  return make(["global-state", key]);
+}
 function variable(name) {
   const key = name.trim();
   if (!key) throw new Error("expr.var requires a non-empty variable name.");
@@ -9919,6 +9927,12 @@ function visitExpression(value, path, variables, issues) {
       }
       return;
     }
+    case "global-state": {
+      if (exact(2) && !isNonEmptyString(value[1])) {
+        addExpressionIssue(issues, [...path, 1], "Global-state keys must be non-empty strings.");
+      }
+      return;
+    }
     case "var": {
       if (exact(2)) {
         if (!isNonEmptyString(value[1])) {
@@ -10185,6 +10199,7 @@ var expr = Object.freeze({
   has,
   id,
   featureState,
+  globalState,
   interpolate: interpolate2,
   let: letValue,
   literal,
@@ -15578,8 +15593,11 @@ function finalizeTileflowLayers(input) {
     }
     const metadata = isRecord8(layer.metadata) ? { ...layer.metadata } : void 0;
     if (metadata) {
+      const owner = metadata[tileflowCompilerMetadataKeys.owner];
       delete metadata[tileflowCompilerProvenanceMetadataKey];
       for (const key of Object.values(tileflowCompilerMetadataKeys)) delete metadata[key];
+      if (tileflowLayerDomains.includes(owner))
+        metadata[tileflowLayerDomainMetadataKey] = owner;
     }
     return {
       ...layer,
@@ -16618,6 +16636,12 @@ var expressionBuilders = [
     returns: "registered field value",
     serializedOperator: "get"
   },
+  {
+    arguments: ["name: nonempty string"],
+    name: "globalState",
+    returns: "unknown",
+    serializedOperator: "global-state"
+  },
   {
     arguments: ["left: T", "right: T"],
     name: "gt",

package/dist/native.d.ts

@@ -26,12 +26,39 @@ declare function resolveTileflowNativeManifestUrl(value: unknown, options?: Tile
 /** Resolve a resource against its owner without fetching it or authorizing requests. */
 declare function resolveTileflowNativeResourceUrl(value: unknown, options: TileflowNativeResourceUrlOptions): string;
 
+type TileflowColor = `#${string}`;
 type TileflowViewConfig = {
     bearing?: number;
     center?: readonly [number, number];
     pitch?: number;
     zoom?: number;
 };
+type MapLibreSprite = string | Array<{
+    id: string;
+    url: string;
+}>;
+type TileflowProjection = 'globe' | 'mercator';
+type TileflowLight = {
+    anchor?: 'map' | 'viewport';
+    color?: TileflowColor;
+    intensity?: number;
+    position?: readonly [number, number, number];
+};
+type MapLibreStyle = {
+    sky?: Record<string, unknown>;
+    version: 8;
+    name: string;
+    glyphs?: string;
+    light?: TileflowLight;
+    projection?: {
+        type: TileflowProjection;
+    };
+    sprite?: MapLibreSprite;
+    sources: Record<string, Record<string, unknown>>;
+    layers: Array<Record<string, unknown>>;
+    terrain?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
 
 /** Runtime-ready logical map with all relative theme resources already resolved. */
 type TileflowRuntimeManifestMap = TileflowRuntimeManifestMapEntry & {
@@ -47,6 +74,24 @@ type TileflowStyleFontFace = {
     style?: 'italic' | 'normal' | 'oblique';
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
+/**
+ * A continuous blend of named themes of one Tileflow map. `position` places the map between
+ * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
+ * to the third.
+ */
+type TileflowThemeBlendSelection = Readonly<{
+    /** From 0 to `themes.length - 1`. */
+    position: number;
+    /** Two to eight concrete theme names of the map, in blend order. */
+    themes: readonly string[];
+}>;
+declare const tileflowThemeBlendLimits: Readonly<{
+    maximumThemes: 8;
+    minimumThemes: 2;
+}>;
+declare function validateTileflowThemeBlendSelection(value: unknown): value is TileflowThemeBlendSelection;
+/** The theme nearest to a blend position, which a blend shows when it cannot blend. */
+declare function nearestTileflowBlendTheme(blend: TileflowThemeBlendSelection): string;
 
 /** The first and only public multi-theme runtime manifest contract. */
 declare const tileflowRuntimeManifestVersion: 1;
@@ -219,4 +264,92 @@ type TileflowNativeInitialViewOptions = {
 /** Resolve once or repeatedly without changing source generations, themes or acquisition. */
 declare function resolveTileflowNativeInitialView(options?: TileflowNativeInitialViewOptions): TileflowNativeInitialView;
 
-export { type TileflowNativeAbortSignal, type TileflowNativeInitialView, type TileflowNativeInitialViewOptions, type TileflowNativeManifestAcquire, type TileflowNativeManifestLoadOptions, type TileflowNativeManifestOperation, type TileflowNativeManifestReader, type TileflowNativeManifestResponse, type TileflowNativeManifestResult, type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, type TileflowNativeSource, type TileflowNativeSourceController, TileflowNativeSourceError, type TileflowNativeSourceErrorCode, type TileflowNativeSourceErrorField, type TileflowNativeSourceOptions, type TileflowNativeSourceState, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, createTileflowNativeSourceController, loadTileflowNativeManifest, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits };
+/**
+ * Theme blending plans one MapLibre style that can show any point between the themes of one map.
+ *
+ * The themes of a Tileflow map compile to the same sources, layers, filters, and expressions; they
+ * differ only in token values: colours, numbers, and image names. A plan keeps the first theme's
+ * structure and records every value that differs as a template the browser fills in for a blend
+ * position: 0 is the first theme, 1 the second, and 1.25 a quarter of the way from the second to
+ * the third. Filling a template needs no expression parsing in the browser, so the renderer only
+ * receives plain values.
+ *
+ * Values that MapLibre evaluates per feature (data-driven values, such as a fill colour chosen by
+ * land-use class) are baked into tiles, and changing them re-lays the whole source out. A plan
+ * splits such a layer into one layer per branch that a feature can take through the value's
+ * decisions on feature data, each filtered to the features that take it, so each value depends
+ * only on zoom and the blend position. A value that reads feature data continuously is drawn once
+ * per theme instead, and the copies cross-fade by opacity. Images are mixed in their pixels.
+ * Values that read feature state cannot be split, because filters cannot read state; they switch
+ * when the dominant theme changes.
+ */
+/** A paint value that the browser sets as the blend moves. */
+type TileflowThemeBlendPaint = Readonly<{
+    layer: string;
+    property: string;
+    template: unknown;
+    /** Ground values follow the blend position; symbol values follow the label cross-fade. */
+    follows: TileflowThemeBlendClock;
+}>;
+/** Image names whose artwork differs between themes and is mixed in pixels. */
+type TileflowThemeBlendImage = Readonly<{
+    names: readonly string[];
+    follows: TileflowThemeBlendClock;
+}>;
+/** A value that can only change all at once, when the dominant theme changes. */
+type TileflowThemeBlendSwitch = Readonly<{
+    layer: string;
+    group: 'layout' | 'paint';
+    property: string;
+    values: readonly unknown[];
+}>;
+/**
+ * `position` values follow the blend; `dominant` values follow a short cross-fade that starts when
+ * the nearest theme changes. Labels use it because light lettering on a dark plate and dark
+ * lettering on a light plate meet in the same grey halfway.
+ */
+type TileflowThemeBlendClock = 'dominant' | 'position';
+type TileflowThemeBlendPlan = Readonly<{
+    /** Number of themes; blend positions run from 0 to `themes - 1`. */
+    themes: number;
+    paints: readonly TileflowThemeBlendPaint[];
+    images: readonly TileflowThemeBlendImage[];
+    switches: readonly TileflowThemeBlendSwitch[];
+    /** Root sky and light, when they differ between themes. */
+    sky?: unknown;
+    light?: unknown;
+    summary: Readonly<{
+        splitLayers: number;
+        copiedLayers: number;
+        /** Per-theme layers of which only the nearest theme's copy is shown. */
+        switchedLayers: number;
+        switchedValues: number;
+    }>;
+    /** The style at a blend position: every template filled, every switch at the nearest theme. */
+    styleAt(position: number): MapLibreStyle;
+}>;
+type TileflowThemeBlendOptions = Readonly<{
+    /**
+     * How icon images that differ between themes change. `mix` (the default) mixes their artwork in
+     * pixels under the first theme's image names. `switch` changes the image names when the nearest
+     * theme changes, for renderers that cannot replace an image's pixels while keeping its stretch
+     * and content metadata.
+     */
+    iconImages?: 'mix' | 'switch';
+    /**
+     * How values that read feature data change when they can be neither split nor cross-faded.
+     * `values` (the default) sets each value when the nearest theme changes. `layers` draws such a
+     * layer once per theme and shows only the nearest theme's copy, for renderers that cannot set
+     * data-driven values at run time reliably.
+     */
+    featureSwitches?: 'layers' | 'values';
+}>;
+declare class TileflowThemeBlendError extends Error {
+    name: string;
+}
+/** Plans a blend of two or more compiled themes of one map, in blend order. */
+declare function planTileflowThemeBlend(styles: readonly MapLibreStyle[], options?: TileflowThemeBlendOptions): TileflowThemeBlendPlan;
+/** Fills one blend template for a position. Plain values pass through unchanged. */
+declare function fillTileflowThemeBlendTemplate(template: unknown, position: number): unknown;
+
+export { type TileflowNativeAbortSignal, type TileflowNativeInitialView, type TileflowNativeInitialViewOptions, type TileflowNativeManifestAcquire, type TileflowNativeManifestLoadOptions, type TileflowNativeManifestOperation, type TileflowNativeManifestReader, type TileflowNativeManifestResponse, type TileflowNativeManifestResult, type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, type TileflowNativeSource, type TileflowNativeSourceController, TileflowNativeSourceError, type TileflowNativeSourceErrorCode, type TileflowNativeSourceErrorField, type TileflowNativeSourceOptions, type TileflowNativeSourceState, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, type TileflowThemeBlendClock, TileflowThemeBlendError, type TileflowThemeBlendImage, type TileflowThemeBlendOptions, type TileflowThemeBlendPaint, type TileflowThemeBlendPlan, type TileflowThemeBlendSelection, type TileflowThemeBlendSwitch, createTileflowNativeSourceController, fillTileflowThemeBlendTemplate, loadTileflowNativeManifest, nearestTileflowBlendTheme, planTileflowThemeBlend, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits, tileflowThemeBlendLimits, validateTileflowThemeBlendSelection };