From 35088f2436023e53f6f98b4f402cbe12ccfd77e3 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 16:16:18 +0100 Subject: [PATCH 1/7] chore: improve interpolation documentation and update SDK support details in v8.json --- build/generate-docs.ts | 20 ++++++ src/reference/v8.json | 155 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 171 insertions(+), 4 deletions(-) diff --git a/build/generate-docs.ts b/build/generate-docs.ts index 900038cf..5a8a5e44 100644 --- a/build/generate-docs.ts +++ b/build/generate-docs.ts @@ -217,6 +217,26 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { } }); } + if (parameter.type === 'interpolation') { + // the type is a non-basic type => we can attach further docs from v8 + const interpolation = v8.interpolation; + markdown += ` \n ${interpolation.doc}`; + const interpolation_name=v8.interpolation_name; + markdown += ` \n Possible values are:`; + for (const [key,val] of Object.entries(interpolation_name.values)) { + markdown += ` \n - \`["${key}"` + for (const param of val.syntax.overloads[0].parameters) { + markdown += `, ${param}` + } + markdown += `]\`: ${val.doc}`; + if (val.syntax.parameters) { + markdown += ` \n Possible parameters are:` + for (const param of val.syntax.parameters) { + markdown += `\n - \`${param.name}\`: ${param.doc}` + } + } + } + } markdown += '\n'; } return markdown; diff --git a/src/reference/v8.json b/src/reference/v8.json index 587ddc50..1dded972 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -3394,7 +3394,7 @@ } }, "interpolate": { - "doc": "Produces continuous, smooth results by interpolating between pairs of input and output values (\"stops\"). The `input` may be any numeric expression (e.g., `[\"get\", \"population\"]`). Stop inputs must be numeric literals in strictly ascending order. The output type must be `number`, `array`, `color`, `array`, or `projection`.\n\nInterpolation types:\n\n- `[\"linear\"]`, or an expression returning one of those types: Interpolates linearly between the pair of stops just less than and just greater than the input.\n\n- `[\"exponential\", base]`: Interpolates exponentially between the stops just less than and just greater than the input. `base` controls the rate at which the output increases: higher values make the output increase more towards the high end of the range. With values close to 1 the output increases linearly.\n\n- `[\"cubic-bezier\", x1, y1, x2, y2]`: Interpolates using the cubic bezier curve defined by the given control points.\n\n - [Animate map camera around a point](https://maplibre.org/maplibre-gl-js/docs/examples/animate-camera-around-point/)\n\n - [Change building color based on zoom level](https://maplibre.org/maplibre-gl-js/docs/examples/change-building-color-based-on-zoom-level/)\n\n - [Create a heatmap layer](https://maplibre.org/maplibre-gl-js/docs/examples/heatmap-layer/)\n\n - [Visualize population density](https://maplibre.org/maplibre-gl-js/docs/examples/visualize-population-density/)", + "doc": "Produces continuous, smooth results by interpolating between pairs of input and output values (\"stops\"). The `input` may be any numeric expression (e.g., `[\"get\", \"population\"]`). Stop inputs must be numeric literals in strictly ascending order. The output type must be `number`, `array`, `color`, `array`, or `projection`.\n\n - [Animate map camera around a point](https://maplibre.org/maplibre-gl-js/docs/examples/animate-camera-around-point/)\n\n - [Change building color based on zoom level](https://maplibre.org/maplibre-gl-js/docs/examples/change-building-color-based-on-zoom-level/)\n\n - [Create a heatmap layer](https://maplibre.org/maplibre-gl-js/docs/examples/heatmap-layer/)\n\n - [Visualize population density](https://maplibre.org/maplibre-gl-js/docs/examples/visualize-population-density/)", "syntax": { "overloads": [ { @@ -3405,7 +3405,7 @@ "parameters": [ { "name": "interpolation_type", - "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"], + "type": "interpolation", "doc": "The interpolation type." }, { @@ -3447,7 +3447,8 @@ "parameters": [ { "name": "interpolation_type", - "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"] + "type": "interpolation", + "doc": "The interpolation type." }, { "name": "input", @@ -3485,7 +3486,8 @@ "parameters": [ { "name": "interpolation_type", - "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"] + "type": "interpolation", + "doc": "The interpolation type." }, { "name": "input", @@ -7992,5 +7994,150 @@ "type": "string", "doc": "A name of a feature property to use as ID for feature state." } + }, + "interpolation": { + "type": "array", + "value": "interpolation_name", + "minimum": 1, + "doc": "An interpolation defines a function that can be used for transitioning between style properties or feature filters. The first element of an interpolation array is a string naming the interpolation operator, e.g. `\\\"linear\\\"` or `\\\"exponential\\\"`. Elements that follow (if any) are the _arguments_ to the interpolation." + }, + "interpolation_name": { + "doc": "First element in an interpolation array. May be followed by a number of arguments.", + "type": "enum", + "values": { + "linear": { + "doc": "Interpolates linearly between the pair of stops just less than and just greater than the input", + "syntax": { + "overloads": [ + { + "parameters": [], + "output-type": "interpolation" + } + ], + "parameters": [] + }, + "example": ["linear"], + "sdk-support": { + "interpolate": { + "js": "0.42.0", + "android": "6.0.0", + "ios": "4.0.0" + }, + "interpolate-hcl": { + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + }, + "interpolate-lab":{ + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + } + } + }, + "exponential": { + "doc": "Interpolates exponentially between the stops just less than and just greater than the input.", + "syntax": { + "overloads": [ + { + "parameters": [ + "base" + ], + "output-type": "interpolation" + } + ], + "parameters": [ + { + "name": "base", + "type": "number literal", + "doc": "controls the rate at which the output increases: higher values make the output increase more towards the high end of the range. With values close to 1 the output increases linearly" + } + ] + }, + "example": [ + "exponential", + 2 + ], + "sdk-support": { + "interpolate": { + "js": "0.42.0", + "android": "6.0.0", + "ios": "4.0.0" + }, + "interpolate-hcl": { + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + }, + "interpolate-lab":{ + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + } + } + }, + "cubic-bezier": { + "doc": "Interpolates using the cubic bezier curve defined by the given control points.", + "syntax": { + "overloads": [ + { + "parameters": [ + "x1", + "y1", + "x2", + "y2" + ], + "output-type": "interpolation" + } + ], + "parameters": [ + { + "name": "x1", + "type": "number literal", + "doc": "X-coordinate of the first control point (P1). Must be between 0 and 1 for a valid monotonic easing curve. Controls how quickly the curve accelerates at the beginning." + }, + { + "name": "y1", + "type": "number literal", + "doc": "Y-coordinate of the first control point (P1). Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the starting slope of the curve." + }, + { + "name": "x2", + "type": "number literal", + "doc": "X-coordinate of the second control point (P2). Must be between 0 and 1 for a valid monotonic easing curve. Controls when the curve begins to decelerate toward the end." + }, + { + "name": "y2", + "type": "number literal", + "doc": "Y-coordinate of the second control point (P2). Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the ending slope of the curve." + } + ] + }, + "example": [ + "cubic-bezier", + 2, + 3, + 2, + 3 + ], + "sdk-support": { + "interpolate": { + "js": "0.42.0", + "android": "6.0.0", + "ios": "4.0.0" + }, + "interpolate-hcl": { + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + }, + "interpolate-lab":{ + "js": "0.49.0", + "ios": "https://github.com/maplibre/maplibre-native/issues/2784", + "android": "https://github.com/maplibre/maplibre-native/issues/2784" + } + } + } + } } } From b30dbf518042e951c34c1d6b2202d5fc3e7323db Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:01:37 +0100 Subject: [PATCH 2/7] fix "Parameters:" in the docs even if there are not parameters --- build/generate-docs.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build/generate-docs.ts b/build/generate-docs.ts index 5a8a5e44..f12805a9 100644 --- a/build/generate-docs.ts +++ b/build/generate-docs.ts @@ -229,8 +229,8 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { markdown += `, ${param}` } markdown += `]\`: ${val.doc}`; - if (val.syntax.parameters) { - markdown += ` \n Possible parameters are:` + if (val.syntax.parameters.length) { + markdown += ` \n Parameters are:` for (const param of val.syntax.parameters) { markdown += `\n - \`${param.name}\`: ${param.doc}` } From 446cd69979b4bf775f56a3c177c343b81de8cb3d Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:18:15 +0100 Subject: [PATCH 3/7] Update src/reference/v8.json --- src/reference/v8.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reference/v8.json b/src/reference/v8.json index 1dded972..02c7472e 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -7999,7 +7999,7 @@ "type": "array", "value": "interpolation_name", "minimum": 1, - "doc": "An interpolation defines a function that can be used for transitioning between style properties or feature filters. The first element of an interpolation array is a string naming the interpolation operator, e.g. `\\\"linear\\\"` or `\\\"exponential\\\"`. Elements that follow (if any) are the _arguments_ to the interpolation." + "doc": "An interpolation defines how to transition between items. The first element of an interpolation array is a string naming the interpolation operator, e.g. `\\\"linear\\\"` or `\\\"exponential\\\"`. Elements that follow (if any) are the _arguments_ to the interpolation." }, "interpolation_name": { "doc": "First element in an interpolation array. May be followed by a number of arguments.", From d1719bc7265be957d48a6f52369825406830a58e Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:22:47 +0100 Subject: [PATCH 4/7] Update src/reference/v8.json --- src/reference/v8.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reference/v8.json b/src/reference/v8.json index 02c7472e..f922393a 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -8050,7 +8050,7 @@ { "name": "base", "type": "number literal", - "doc": "controls the rate at which the output increases: higher values make the output increase more towards the high end of the range. With values close to 1 the output increases linearly" + "doc": "rate at which the output increases in `f(x) = x^r`. Values higher than 1 increase, close to one behave linearly and below one decrease." } ] }, From 87c0da022aa1b47d269192239bae126738a76d7c Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:24:24 +0100 Subject: [PATCH 5/7] Update src/reference/v8.json --- src/reference/v8.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/reference/v8.json b/src/reference/v8.json index f922393a..0f8e1b62 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -8094,22 +8094,22 @@ { "name": "x1", "type": "number literal", - "doc": "X-coordinate of the first control point (P1). Must be between 0 and 1 for a valid monotonic easing curve. Controls how quickly the curve accelerates at the beginning." + "doc": "X-coordinate of the first control point. Must be between 0 and 1 for a valid monotonic easing curve. Controls how quickly the curve accelerates at the beginning." }, { "name": "y1", "type": "number literal", - "doc": "Y-coordinate of the first control point (P1). Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the starting slope of the curve." + "doc": "Y-coordinate of the first control point. Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the starting slope of the curve." }, { "name": "x2", "type": "number literal", - "doc": "X-coordinate of the second control point (P2). Must be between 0 and 1 for a valid monotonic easing curve. Controls when the curve begins to decelerate toward the end." + "doc": "X-coordinate of the second control point. Must be between 0 and 1 for a valid monotonic easing curve. Controls when the curve begins to decelerate toward the end." }, { "name": "y2", "type": "number literal", - "doc": "Y-coordinate of the second control point (P2). Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the ending slope of the curve." + "doc": "Y-coordinate of the second control point. Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the ending slope of the curve." } ] }, From 26e80de54314882941a578c2f4449cf184b1ae54 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:52:18 +0100 Subject: [PATCH 6/7] docs rewordings --- src/reference/v8.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/reference/v8.json b/src/reference/v8.json index 0f8e1b62..eae09c5f 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -4106,7 +4106,7 @@ } }, "rgba": { - "doc": "Creates a color value from red, green, blue components, which must range between 0 and 255, and an alpha component which must range between 0 and 1. If any component is out of range, the expression is an error.", + "doc": "Creates a color value from red, green, blue components, which must range between 0 and 255, and an alpha component which must range between zero and one. If any component is out of range, the expression is an error.", "syntax": { "overloads": [ { @@ -7999,7 +7999,7 @@ "type": "array", "value": "interpolation_name", "minimum": 1, - "doc": "An interpolation defines how to transition between items. The first element of an interpolation array is a string naming the interpolation operator, e.g. `\\\"linear\\\"` or `\\\"exponential\\\"`. Elements that follow (if any) are the _arguments_ to the interpolation." + "doc": "An interpolation defines how to transition between items. The first element of an interpolation array is a string naming the interpolation operator, e.g. `\"linear\"` or `\"exponential\"`. Elements that follow (if any) are the _arguments_ to the interpolation." }, "interpolation_name": { "doc": "First element in an interpolation array. May be followed by a number of arguments.", @@ -8050,7 +8050,7 @@ { "name": "base", "type": "number literal", - "doc": "rate at which the output increases in `f(x) = x^r`. Values higher than 1 increase, close to one behave linearly and below one decrease." + "doc": "rate at which the output increases in `f(x) = x^r`. Values higher than 1 increase, close to one behaves linearly, and below one decrease." } ] }, @@ -8077,7 +8077,7 @@ } }, "cubic-bezier": { - "doc": "Interpolates using the cubic bezier curve defined by the given control points.", + "doc": "Interpolates using the cubic bézier curve defined by the given control points.", "syntax": { "overloads": [ { @@ -8094,22 +8094,22 @@ { "name": "x1", "type": "number literal", - "doc": "X-coordinate of the first control point. Must be between 0 and 1 for a valid monotonic easing curve. Controls how quickly the curve accelerates at the beginning." + "doc": "X-coordinate of the first control point. Must be between zero and one for a valid monotonic easing curve. Controls how quickly the curve speeds up at the beginning." }, { "name": "y1", "type": "number literal", - "doc": "Y-coordinate of the first control point. Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the starting slope of the curve." + "doc": "Y-coordinate of the first control point. Typically between zero and one, but may exceed this range for overshoot effects. Influences the starting slope of the curve." }, { "name": "x2", "type": "number literal", - "doc": "X-coordinate of the second control point. Must be between 0 and 1 for a valid monotonic easing curve. Controls when the curve begins to decelerate toward the end." + "doc": "X-coordinate of the second control point. Must be between zero and one for a valid monotonic easing curve. Controls when the curve begins to decelerate toward the end." }, { "name": "y2", "type": "number literal", - "doc": "Y-coordinate of the second control point. Typically between 0 and 1, but may exceed this range for overshoot effects. Influences the ending slope of the curve." + "doc": "Y-coordinate of the second control point. Typically between zero and one, but may exceed this range for overshoot effects. Influences the ending slope of the curve." } ] }, From 1ef6397e2041b106f526d142aa20b8a07f5bd474 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 4 Dec 2025 22:53:36 +0100 Subject: [PATCH 7/7] move to different functions for better readability --- build/generate-docs.ts | 86 +++++++++++++++++++++++++++--------------- 1 file changed, 55 insertions(+), 31 deletions(-) diff --git a/build/generate-docs.ts b/build/generate-docs.ts index f12805a9..2bc2c4f9 100644 --- a/build/generate-docs.ts +++ b/build/generate-docs.ts @@ -195,9 +195,7 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { }); markdown += `${codeBlockMarkdown(codeBlockLines.join('\n'), 'js')}\n`; for (const parameter of syntax.parameters ?? []) { - const type = parameterTypeToType(parameter.type) - .replaceAll('<', '<') - .replaceAll('>', '>'); + const type = parameterTypeToType(parameter.type); markdown += `- \`${parameter.name}\`: \`${type}\``; if (parameter.doc) { markdown += `- ${parameter.doc}`; @@ -205,36 +203,16 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { if (typeof parameter.type !== 'string' && !Array.isArray(parameter.type)) { // the type is an object type => we can attach more documentation about the contained variables markdown += ' \nParameters:'; - Object.entries(parameter.type).forEach(([key, val]) => { - const type = jsonObjectToType(val).replaceAll('<', '<').replaceAll('>', '>'); - markdown += `\n - \`${key}\`: \`${type}\` - ${val.doc}`; - if (val.type === 'enum' && val.values) { - markdown += ' \n Possible values are:'; - for (const [enumKey, enumValue] of Object.entries(val.values)) { - const defaultIndicator = val.default === enumKey ? ' *default*' : ''; - markdown += `\n - \`"${enumKey}"\`${defaultIndicator} - ${enumValue.doc}`; - } - } - }); + const containedVariables = containedVariablesToMarkdown(parameter.type); + for (const line of containedVariables.split('\n')) { + markdown += `\n ${line}`; + } } if (parameter.type === 'interpolation') { - // the type is a non-basic type => we can attach further docs from v8 - const interpolation = v8.interpolation; - markdown += ` \n ${interpolation.doc}`; - const interpolation_name=v8.interpolation_name; - markdown += ` \n Possible values are:`; - for (const [key,val] of Object.entries(interpolation_name.values)) { - markdown += ` \n - \`["${key}"` - for (const param of val.syntax.overloads[0].parameters) { - markdown += `, ${param}` - } - markdown += `]\`: ${val.doc}`; - if (val.syntax.parameters.length) { - markdown += ` \n Parameters are:` - for (const param of val.syntax.parameters) { - markdown += `\n - \`${param.name}\`: ${param.doc}` - } - } + markdown += " "; + const interpolationSyntax = interpolationSyntaxToMarkdown(); + for (const line of interpolationSyntax.split('\n')) { + markdown += `\n ${line}`; } } markdown += '\n'; @@ -242,6 +220,52 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { return markdown; } +/** + * Converts the contained variables object to markdown format. + * @param type - the contained variables object + * @returns the markdown string for the interpolation's syntax section + */ +function containedVariablesToMarkdown(type: {[key: string]: JsonObject}) { + let markdown = ""; + Object.entries(type).forEach(([key, val]) => { + const type = jsonObjectToType(val); + markdown += `\n- \`${key}\`: \`${type}\` - ${val.doc}`; + if (val.type === 'enum' && val.values) { + markdown += ' \n Possible values are:'; + for (const [enumKey, enumValue] of Object.entries(val.values)) { + const defaultIndicator = val.default === enumKey ? ' *default*' : ''; + markdown += `\n - \`"${enumKey}"\`${defaultIndicator} - ${enumValue.doc}`; + } + } + }); + return markdown +} + +/** + * Converts the interpolation syntax object to markdown format. + * @returns the markdown string for the interpolation's syntax section + */ +function interpolationSyntaxToMarkdown() { + const interpolation = v8.interpolation; + let markdown = interpolation.doc; + const interpolation_name=v8.interpolation_name; + markdown += ` \nPossible values are:`; + for (const [key,val] of Object.entries(interpolation_name.values)) { + markdown += ` \n - \`["${key}"` + for (const param of val.syntax.overloads[0].parameters) { + markdown += `, ${param}` + } + markdown += `]\`: ${val.doc}`; + if (val.syntax.parameters.length) { + markdown += ` \n Parameters are:` + for (const param of val.syntax.parameters) { + markdown += ` \n \`${param.name}\`: ${param.doc}` + } + } + } + return markdown +} + /** * The requires field has some syntax which can contain "!" and "source". * @param requires - a list of requirements for the property