Skip to content

chore: improve interpolation documentation by making it an syntax-enum #1400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+210 −19
Open

chore: improve interpolation documentation by making it an syntax-enum #1400

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
35088f2
chore: improve interpolation documentation and update SDK support det…
CommanderStorm Dec 4, 2025
b30dbf5
fix "Parameters:" in the docs even if there are not parameters
CommanderStorm Dec 4, 2025
446cd69
Update src/reference/v8.json
CommanderStorm Dec 4, 2025
d1719bc
Update src/reference/v8.json
CommanderStorm Dec 4, 2025
87c0da0
Update src/reference/v8.json
CommanderStorm Dec 4, 2025
26e80de
docs rewordings
CommanderStorm Dec 4, 2025
1ef6397
move to different functions for better readability
CommanderStorm Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions build/generate-docs.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,26 @@ function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) {
}
});
}
if (parameter.type === 'interpolation') {
Copy link
Collaborator

@HarelM HarelM Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a different way to achieve this? I prefer to be as generic as possible here...

Copy link
Member Author

@CommanderStorm CommanderStorm Dec 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other "length1-array with syntax-enum as value" is expressions.
Expressions are manually codegen-ed, so there is no code to reuse.

Also, the indentation and newline requirement (those two spaces before \n) would be a bit tricky to do this way.

Unless you want a major change to how this system works (which might make sense, but would be a larger change)

Copy link
Collaborator

@HarelM HarelM Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In saying the same thing in both comments basically: is there a more generalized way to achieve the same thing? Or maybe reuse some code?
At the very least, since this is specific, it should be extracted to a method.

Copy link
Member Author

@CommanderStorm CommanderStorm Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generalised? Not without basically rewriting the entire thing.
This is one of the core parts and the impact of this is likely larger.
I don't think that reusing code is possible.

I moved the two things you commented on to a function each.

// 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 += '\n';
}
return markdown;
Expand Down
155 changes: 151 additions & 4 deletions src/reference/v8.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<number>`, `color`, `array<color>`, 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<number>`, `color`, `array<color>`, 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": [
{
Expand All @@ -3405,7 +3405,7 @@
"parameters": [
{
"name": "interpolation_type",
"type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"],
"type": "interpolation",
"doc": "The interpolation type."
},
{
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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 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.",
"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"
}
}
}
}
}
}
Loading