@mapbox/mapbox-gl-style-spec 14.11.0-beta.1 → 14.11.0-beta.2

package/expression/definitions/image.ts

@@ -1,46 +1,62 @@
-import {ColorType, ResolvedImageType, StringType} from '../types';
 import ResolvedImage from '../types/resolved_image';
+import {ImageId} from '../types/image_id';
+import {ColorType, ResolvedImageType, StringType} from '../types';
 
 import type Color from '../../util/color';
-import type {Expression, SerializedExpression} from '../expression';
-import type EvaluationContext from '../evaluation_context';
 import type ParsingContext from '../parsing_context';
+import type EvaluationContext from '../evaluation_context';
 import type {Type} from '../types';
+import type {Expression, SerializedExpression} from '../expression';
 
 export type ImageParams = Record<string, Expression>;
+export type IconsetParams = {id: string};
 
 export type ImageOptions = {
-    params: ImageParams;
+    params?: ImageParams;
+    iconset?: IconsetParams;
 }
 
-function isImageOptions(value: unknown) {
-    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-        return true;
-    }
+type SerializedImageOptions = {
+    params?: Record<string, SerializedExpression>;
+    iconset?: IconsetParams;
+};
 
-    return false;
+function isImageOptions(value: unknown): value is ImageOptions {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
 export default class ImageExpression implements Expression {
     type: Type;
-    inputPrimary: Expression;
-    inputPrimaryParams: Record<string, Expression> | undefined;
-    inputSecondary: Expression | null | undefined;
-    inputSecondaryParams: Record<string, Expression> | undefined;
+
+    namePrimary: Expression;
+    paramsPrimary?: ImageParams;
+    iconsetIdPrimary?: string;
+
+    nameSecondary?: Expression;
+    paramsSecondary?: ImageParams;
+    iconsetIdSecondary?: string;
 
     _imageWarnHistory: Record<string, boolean> = {};
 
     constructor(
         inputPrimary: Expression,
         inputSecondary?: Expression | null,
-        inputPrimaryParams?: Record<string, Expression>,
-        inputSecondaryParams?: Record<string, Expression>
+        inputPrimaryOptions?: ImageOptions,
+        inputSecondaryOptions?: ImageOptions
     ) {
         this.type = ResolvedImageType;
-        this.inputPrimary = inputPrimary;
-        this.inputSecondary = inputSecondary;
-        this.inputPrimaryParams = inputPrimaryParams;
-        this.inputSecondaryParams = inputSecondaryParams;
+        this.namePrimary = inputPrimary;
+        this.nameSecondary = inputSecondary;
+
+        if (inputPrimaryOptions) {
+            this.paramsPrimary = inputPrimaryOptions.params;
+            this.iconsetIdPrimary = inputPrimaryOptions.iconset ? inputPrimaryOptions.iconset.id : undefined;
+        }
+
+        if (inputSecondaryOptions) {
+            this.paramsSecondary = inputSecondaryOptions.params;
+            this.iconsetIdSecondary = inputSecondaryOptions.iconset ? inputSecondaryOptions.iconset.id : undefined;
+        }
     }
 
     static parse(args: ReadonlyArray<unknown>, context: ParsingContext): Expression | null | void {
@@ -49,7 +65,7 @@ export default class ImageExpression implements Expression {
         }
 
         let nextArgId = 1;
-        const imageExpression: Array<{image: Expression, options: Record<string, Expression>}> = [];
+        const imageExpression: Array<{image: Expression, options?: ImageOptions}> = [];
 
         function tryParseImage() {
             if (nextArgId < args.length) {
@@ -59,7 +75,7 @@ export default class ImageExpression implements Expression {
                     return false;
                 }
 
-                imageExpression.push({image: imageName, options: undefined});
+                imageExpression.push({image: imageName, options: {}});
                 return true;
             }
 
@@ -68,45 +84,62 @@ export default class ImageExpression implements Expression {
 
         function tryParseOptions() {
             if (nextArgId < args.length) {
-                if (!isImageOptions(args[nextArgId])) {
+                const options = args[nextArgId];
+                if (!isImageOptions(options)) {
                     return true;
                 }
 
-                const params = (args[nextArgId] as ImageOptions).params;
-
+                const params = options.params;
+                const iconset = options.iconset;
                 const optionsContext = context.concat(nextArgId);
 
-                if (!params) {
+                if (!params && !iconset) {
                     nextArgId++;
                     return true;
                 }
 
-                if (typeof params !== 'object' || params.constructor !== Object) {
-                    optionsContext.error(`Image options \"params\" should be an object`);
-                    return false;
-                }
+                // Parse the image options params as expressions
+                if (params) {
+                    if (typeof params !== 'object' || params.constructor !== Object) {
+                        optionsContext.error(`Image options \"params\" should be an object`);
+                        return false;
+                    }
 
-                const parsed = {};
+                    const parsedParams: ImageParams = {};
+                    const childContext = optionsContext.concat(undefined, 'params');
+                    for (const key in params) {
+                        if (!key) {
+                            childContext.error(`Image parameter name should be non-empty`);
+                            return false;
+                        }
 
-                const childContext = optionsContext.concat(undefined, 'params');
+                        const value = childContext.concat(undefined, key).parse(params[key], undefined, ColorType, undefined, {typeAnnotation: 'coerce'});
+                        if (!value) {
+                            return false;
+                        }
 
-                for (const key in params) {
-                    if (!key) {
-                        childContext.error(`Image parameter name should be non-empty`);
+                        parsedParams[key] = value;
+                    }
+
+                    imageExpression[imageExpression.length - 1].options.params = parsedParams;
+                }
+
+                // Validate the iconset image options
+                if (iconset) {
+                    if (typeof iconset !== 'object' || iconset.constructor !== Object) {
+                        optionsContext.error(`Image options \"iconset\" should be an object`);
                         return false;
                     }
 
-                    const value = childContext.concat(undefined, key).parse(params[key], undefined, ColorType, undefined, {typeAnnotation: 'coerce'});
-                    if (!value) {
+                    if (!iconset.id) {
+                        optionsContext.error(`Image options \"iconset\" should have an \"id\" property`);
                         return false;
                     }
 
-                    parsed[key] = value;
+                    imageExpression[imageExpression.length - 1].options.iconset = iconset;
                 }
 
-                imageExpression[imageExpression.length - 1].options = parsed;
                 nextArgId++;
-
                 return true;
             }
 
@@ -162,17 +195,30 @@ export default class ImageExpression implements Expression {
     }
 
     evaluate(ctx: EvaluationContext): null | ResolvedImage {
+        const primaryId = {
+            name: this.namePrimary.evaluate(ctx),
+            iconsetId: this.iconsetIdPrimary
+        };
+
+        const secondaryId = this.nameSecondary ? {
+            name: this.nameSecondary.evaluate(ctx),
+            iconsetId: this.iconsetIdSecondary
+        } : undefined;
+
         const value = ResolvedImage.build(
-            this.inputPrimary.evaluate(ctx),
-            this.inputSecondary ? this.inputSecondary.evaluate(ctx) : undefined,
-            this.inputPrimaryParams ? this.evaluateParams(ctx, this.inputPrimaryParams) : undefined,
-            this.inputSecondaryParams ? this.evaluateParams(ctx, this.inputSecondaryParams) : undefined
+            primaryId,
+            secondaryId,
+            this.paramsPrimary ? this.evaluateParams(ctx, this.paramsPrimary) : undefined,
+            this.paramsSecondary ? this.evaluateParams(ctx, this.paramsSecondary) : undefined
         );
+
         if (value && ctx.availableImages) {
-            value.available = ctx.availableImages.indexOf(value.namePrimary) > -1;
-            // If there's a secondary variant, only mark it available if both are present
-            if (value.nameSecondary && value.available && ctx.availableImages) {
-                value.available = ctx.availableImages.indexOf(value.nameSecondary) > -1;
+            const primaryId = value.getPrimary().id;
+            value.available = ctx.availableImages.some((id) => ImageId.isEqual(id, primaryId));
+            if (value.available) {
+                // If there's a secondary variant, only mark it available if both are present
+                const secondaryId = value.getSecondary() ? value.getSecondary().id : null;
+                if (secondaryId) value.available = ctx.availableImages.some((id) => ImageId.isEqual(id, secondaryId));
             }
         }
 
@@ -180,20 +226,22 @@ export default class ImageExpression implements Expression {
     }
 
     eachChild(fn: (_: Expression) => void) {
-        fn(this.inputPrimary);
-        if (this.inputPrimaryParams) {
-            for (const key in this.inputPrimaryParams) {
-                if (this.inputPrimaryParams[key]) {
-                    fn(this.inputPrimaryParams[key]);
+        fn(this.namePrimary);
+
+        if (this.paramsPrimary) {
+            for (const key in this.paramsPrimary) {
+                if (this.paramsPrimary[key]) {
+                    fn(this.paramsPrimary[key]);
                 }
             }
         }
-        if (this.inputSecondary) {
-            fn(this.inputSecondary);
-            if (this.inputSecondaryParams) {
-                for (const key in this.inputSecondaryParams) {
-                    if (this.inputSecondaryParams[key]) {
-                        fn(this.inputSecondaryParams[key]);
+
+        if (this.nameSecondary) {
+            fn(this.nameSecondary);
+            if (this.paramsSecondary) {
+                for (const key in this.paramsSecondary) {
+                    if (this.paramsSecondary[key]) {
+                        fn(this.paramsSecondary[key]);
                     }
                 }
             }
@@ -205,33 +253,39 @@ export default class ImageExpression implements Expression {
         return false;
     }
 
-    serializeParams(params: Record<string, Expression> | undefined): {params: Record<string, SerializedExpression>} {
-        const result: Record<string, SerializedExpression> = {};
+    serializeOptions(params: ImageParams, iconsetId: string): SerializedImageOptions | undefined {
+        const result: SerializedImageOptions = {};
+
+        if (iconsetId) {
+            result.iconset = {id: iconsetId};
+        }
+
         if (params) {
+            result.params = {};
             for (const key in params) {
                 if (params[key]) {
-                    result[key] = params[key].serialize();
+                    result.params[key] = params[key].serialize();
                 }
             }
-        } else {
-            return undefined;
         }
 
-        return {params: result};
+        return Object.keys(result).length > 0 ? result : undefined;
     }
 
     serialize(): SerializedExpression {
-        const serialized: SerializedExpression = ["image", this.inputPrimary.serialize()];
+        const serialized: SerializedExpression = ['image', this.namePrimary.serialize()];
 
-        if (this.inputPrimaryParams) {
-            serialized.push(this.serializeParams(this.inputPrimaryParams));
+        if (this.paramsPrimary || this.iconsetIdPrimary) {
+            const options = this.serializeOptions(this.paramsPrimary, this.iconsetIdPrimary);
+            if (options) serialized.push(options);
         }
 
-        if (this.inputSecondary) {
-            serialized.push(this.inputSecondary.serialize());
+        if (this.nameSecondary) {
+            serialized.push(this.nameSecondary.serialize());
 
-            if (this.inputSecondaryParams) {
-                serialized.push(this.serializeParams(this.inputSecondaryParams));
+            if (this.paramsSecondary || this.iconsetIdSecondary) {
+                const options = this.serializeOptions(this.paramsSecondary, this.iconsetIdSecondary);
+                if (options) serialized.push(options);
             }
         }
 

package/expression/evaluation_context.ts

@@ -1,6 +1,7 @@
 import {Color} from './values';
 
 import type Point from '@mapbox/point-geometry';
+import type {ImageId} from './types/image_id';
 import type {FormattedSection} from './types/formatted';
 import type {GlobalProperties, Feature, FeatureState} from './index';
 import type {CanonicalTileID} from '../types/tile_id';
@@ -14,7 +15,7 @@ class EvaluationContext {
     feature: Feature | null | undefined;
     featureState: FeatureState | null | undefined;
     formattedSection: FormattedSection | null | undefined;
-    availableImages: Array<string> | null | undefined;
+    availableImages: ImageId[] | null | undefined;
     canonical: null | CanonicalTileID;
     featureTileCoord: Point | null | undefined;
     featureDistanceData: FeatureDistanceData | null | undefined;

package/expression/index.ts

@@ -35,6 +35,7 @@ import type Point from '@mapbox/point-geometry';
 import type {CanonicalTileID} from '../types/tile_id';
 import type {FeatureDistanceData} from '../feature_filter/index';
 import type {ConfigOptions} from '../types/config_options';
+import type {ImageId} from './types/image_id';
 
 export interface Feature {
     readonly type: 0 | 1 | 2 | 3 | 'Unknown' | 'Point' | 'LineString' | 'Polygon';
@@ -88,7 +89,7 @@ export class StyleExpression {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
         featureTileCoord?: Point,
         featureDistanceData?: FeatureDistanceData,
@@ -110,7 +111,7 @@ export class StyleExpression {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
         featureTileCoord?: Point,
         featureDistanceData?: FeatureDistanceData,
@@ -202,7 +203,7 @@ export class ZoomConstantExpression<Kind extends EvaluationKind> {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ): any {
         return this._styleExpression.evaluateWithoutErrorHandling(globals, feature, featureState, canonical, availableImages, formattedSection);
@@ -213,7 +214,7 @@ export class ZoomConstantExpression<Kind extends EvaluationKind> {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ): any {
         return this._styleExpression.evaluate(globals, feature, featureState, canonical, availableImages, formattedSection);
@@ -247,7 +248,7 @@ export class ZoomDependentExpression<Kind extends EvaluationKind> {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ): any {
         return this._styleExpression.evaluateWithoutErrorHandling(globals, feature, featureState, canonical, availableImages, formattedSection);
@@ -258,7 +259,7 @@ export class ZoomDependentExpression<Kind extends EvaluationKind> {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ): any {
         return this._styleExpression.evaluate(globals, feature, featureState, canonical, availableImages, formattedSection);
@@ -281,7 +282,7 @@ export type ConstantExpression = {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
     ) => any;
 };
 
@@ -296,7 +297,7 @@ export type SourceExpression = {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ) => any;
 };
@@ -310,7 +311,7 @@ export type CameraExpression = {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
     ) => any;
     readonly interpolationFactor: (input: number, lower: number, upper: number) => number;
     zoomStops: Array<number>;
@@ -328,7 +329,7 @@ export interface CompositeExpression {
         feature?: Feature,
         featureState?: FeatureState,
         canonical?: CanonicalTileID,
-        availableImages?: Array<string>,
+        availableImages?: ImageId[],
         formattedSection?: FormattedSection,
     ) => any;
     readonly interpolationFactor: (input: number, lower: number, upper: number) => number;

package/expression/types/formatted.ts

@@ -31,8 +31,11 @@ export default class Formatted {
 
     isEmpty(): boolean {
         if (this.sections.length === 0) return true;
-        return !this.sections.some(section => section.text.length !== 0 ||
-                                             (section.image && section.image.namePrimary));
+        return !this.sections.some(section => {
+            if (section.text.length !== 0) return true;
+            if (!section.image) return false;
+            return section.image.hasPrimary();
+        });
     }
 
     static factory(text: Formatted | string): Formatted {
@@ -52,7 +55,8 @@ export default class Formatted {
         const serialized: Array<unknown> = ["format"];
         for (const section of this.sections) {
             if (section.image) {
-                serialized.push(["image", section.image.namePrimary]);
+                const primaryId = section.image.getPrimary().id.toString();
+                serialized.push(['image', primaryId]);
                 continue;
             }
             serialized.push(section.text);

package/expression/types/image_id.ts

@@ -0,0 +1,61 @@
+import type {Brand} from '../../types/brand';
+
+export type ImageIdSpec = {
+    name: string;
+    iconsetId?: string;
+};
+
+/**
+ * `StringifiedImageId` is a stringified version of the `ImageId`.
+ *
+ * @private
+ */
+export type StringifiedImageId = Brand<string, 'ImageId'>;
+
+/**
+ * `ImageId` is a reference to an {@link ImageVariant} in the sprite or iconset.
+ *
+ * @private
+ */
+export class ImageId {
+    name: string;
+    iconsetId?: string;
+
+    constructor(id: string | ImageId | ImageIdSpec) {
+        if (typeof id === 'string') {
+            this.name = id;
+        } else {
+            this.name = id.name;
+            this.iconsetId = id.iconsetId;
+        }
+    }
+
+    static from(id: string | ImageId | ImageIdSpec): ImageId {
+        return new ImageId(id);
+    }
+
+    static toString(id: ImageId | ImageIdSpec): StringifiedImageId {
+        return JSON.stringify({name: id.name, iconsetId: id.iconsetId}) as StringifiedImageId;
+    }
+
+    static parse(str: StringifiedImageId): ImageId | null {
+        try {
+            const {name, iconsetId} = JSON.parse(str);
+            return new ImageId({name, iconsetId});
+        } catch (e) {
+            return null;
+        }
+    }
+
+    static isEqual(a: ImageId | ImageIdSpec, b: ImageId | ImageIdSpec): boolean {
+        return a.name === b.name && a.iconsetId === b.iconsetId;
+    }
+
+    toString(): StringifiedImageId {
+        return JSON.stringify({name: this.name, iconsetId: this.iconsetId}) as StringifiedImageId;
+    }
+
+    serialize(): ImageIdSpec {
+        return {name: this.name, iconsetId: this.iconsetId};
+    }
+}

package/expression/types/image_variant.ts

@@ -0,0 +1,79 @@
+import {ImageId} from './image_id';
+
+import type Color from '../../util/color';
+import type {Brand} from '../../types/brand';
+import type {ImageIdSpec} from './image_id';
+
+/**
+ * `StringifiedImageVariant` is a stringified version of the `ImageVariant`.
+ *
+ * @private
+ */
+export type StringifiedImageVariant = Brand<string, 'ImageVariant'>;
+
+/**
+ * {@link ImageVariant} rasterization options.
+ *
+ * @private
+ */
+export type RasterizationOptions = {
+    params?: Record<string, Color>;
+    transform?: DOMMatrix;
+}
+
+/**
+ * `ImageVariant` is a component of {@link ResolvedImage}
+ * that represents either the primary or secondary image
+ * along with its rendering configuration.
+ *
+ * @private
+ */
+export class ImageVariant {
+    id: ImageId;
+    options: RasterizationOptions;
+
+    constructor(id: string | ImageIdSpec, options: RasterizationOptions = {}) {
+        this.id = ImageId.from(id);
+        this.options = Object.assign({}, options);
+
+        if (!options.transform) {
+            this.options.transform = new DOMMatrix([1, 0, 0, 1, 0, 0]);
+        } else {
+            const {a, b, c, d, e, f} = options.transform;
+            this.options.transform = new DOMMatrix([a, b, c, d, e, f]);
+        }
+    }
+
+    toString(): StringifiedImageVariant {
+        const {a, b, c, d, e, f} = this.options.transform;
+
+        const serialized = {
+            name: this.id.name,
+            iconsetId: this.id.iconsetId,
+            params: this.options.params,
+            transform: {a, b, c, d, e, f},
+        };
+
+        return JSON.stringify(serialized) as StringifiedImageVariant;
+    }
+
+    static parse(str: StringifiedImageVariant): ImageVariant | null {
+        let name, iconsetId, params, transform;
+
+        try {
+            ({name, iconsetId, params, transform} = JSON.parse(str) || {});
+        } catch (e) {
+            return null;
+        }
+
+        if (!name) return null;
+
+        const {a, b, c, d, e, f} = transform || {};
+        return new ImageVariant({name, iconsetId}, {params, transform: new DOMMatrix([a, b, c, d, e, f])});
+    }
+
+    scaleSelf(factor: number): this {
+        this.options.transform.scaleSelf(factor);
+        return this;
+    }
+}