Improve the handling of map options #4145

vicb · 2024-05-21T08:55:36Z

Content of this PR:

Fix comments in type MapOptions
Order default values using the type order,
Update Map props:
- use inline init where applicable
- fix types where applicable
- fix init to match type where applicable
A few other minor updates

I'd like to get some feedback and I'll create an issue and fill out the launch checklist after that.

Thanks!

Launch Checklist

Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
Briefly describe the changes in this PR.
Link to related issues.
Include before/after visuals or gifs if this PR includes visual changes.
Write tests for all new functionality.
Document any changes to public APIs.
Post benchmark scores.
Add an entry to CHANGELOG.md under the ## main section.

codecov-commenter · 2024-05-21T08:58:40Z

Codecov Report

Attention: Patch coverage is 88.37209% with 15 lines in your changes are missing coverage. Please review.

Project coverage is 86.87%. Comparing base (d7cd701) to head (df31dcf).
Report is 4 commits behind head on main.

Files	Patch %	Lines
src/ui/map.ts	84.09%	4 Missing and 10 partials ⚠️
src/util/test/util.ts	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4145      +/-   ##
==========================================
- Coverage   86.88%   86.87%   -0.01%     
==========================================
  Files         242      242              
  Lines       33044    33075      +31     
  Branches     2011     2017       +6     
==========================================
+ Hits        28709    28734      +25     
- Misses       3374     3383       +9     
+ Partials      961      958       -3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

src/ui/map.ts

HarelM · 2024-05-21T09:25:36Z

src/types/util.ts

+ * See https://medium.com/terria/typescript-transforming-optional-properties-to-required-properties-that-may-be-undefined-7482cb4e1585
+ */
+
+export type Complete<T> = {


I was actually thinking of removing this folder entirely, and move the types to either the utils folder or the files that are using those.
I also don't see this is used in another place, so I'm not sure there's an actual need to move it...

I prefer not to have too much noise in map.ts but no strong opinion, I can do whatever you think is best.

One other unrelated question, do you know why const defaultMinZoom = -2;?
I would love to add a comment there because it doesn't look intuitive

No clue why it's -2.

If you prefer no to put it in map.ts I would recommend adding it to the utils file.
Also the tilejson and remove this folder completely.

-2 is to render maps < 512px (see mapbox/mapbox-gl-js#9028)

HarelM · 2024-05-21T09:27:39Z

I don't have any objections to this PR in general.
Can we close the following PR:

Fix MapOptions#style is optional in the Map constructor #4003?

vicb · 2024-05-21T09:30:43Z

I don't have any objections to this PR in general. Can we close the following PR:

Fix MapOptions#style is optional in the Map constructor #4003?

For now style is not addressed in this PR but I think it should be.
Let's close the other PR once this has been updated.
The first commit is only about cleaning the existing stuff. I'll add more commits to improve the type after we agree on the first one.

vicb · 2024-05-22T08:26:52Z

It looks like some tests are failing...
I'll try to reproduce locally and fix

HarelM · 2024-05-22T09:19:36Z

I'm not sure the failing test is your fault. I see it on a PR for a package update.
Wait a bit with the investigation...

HarelM · 2024-05-22T09:23:03Z

src/ui/map.ts

        if (this.style) {
-            this.style.setEventedParent(null);
+            // transformStyle relies on having previous style serialized.


Is this a bug fix? If so, I think it will be better to have this in a different PR...?

This is only code factorization:

this.style is tested on l 1732, 1737, and 1738 on the left

options.transformStyle is tested l 1732 and 1737 on the left

HarelM · 2024-05-22T09:28:17Z

src/ui/map.ts

-    getImage(id: string): StyleImage {
-        return this.style.getImage(id);
+    getImage(id: string): StyleImage | undefined {
+        return this.style?.getImage(id);


Isn't this a behavior change? As far as I understand, before this change if style was not defined, this method would have thrown an exception, wouldn't it?

Discussed offline with @HarelM

Summary of the discussion: What is the expected behavior of this function:

throw is not documented

the type of this.style: Style does not let users think it might throw

is it valuable to throw here?

I think the behavior should be consistent across methods.

Some might throw:

getImage(id: string): StyleImage { return this.style.getImage(id); }

Some are noops when style is undefined

redraw(): this { if (this.style) { // cancel the scheduled update if (this._frameRequest) { this._frameRequest.abort(); this._frameRequest = null; } this._render(0); } return this; }

Some warn when style is undefined

_updateDiff(style: StyleSpecification, options?: StyleSwapOptions & StyleOptions) { try { if (this.style.setState(style, options)) { this._update(true); } } catch (e) { warnOnce( `Unable to perform style diff: ${e.message || e.error || e}. Rebuilding the style from scratch.` ); this._updateStyle(style, options); } }

HarelM · 2024-05-22T09:31:55Z

I believe this PR got too big... :-(
Let's try and keep the PRs small, with small increments so these increments can be merged.
From previous commit to latest commit there are a lot of changes which I think should be discussed before merging.
The previous commit was great in terms of adding correctness to types without changing any implementation (maybe besides moving the initialization out of the constructor).
Let's start with that and then move on to fixing things/changing logic.

HarelM · 2024-05-22T09:36:27Z

src/ui/map.ts

@@ -298,14 +301,15 @@ export type MapOptions = {
     * the schema described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/),
     * or a URL to such JSON.
     */
-    style: StyleSpecification | string;
+    style?: StyleSpecification | string;


I think that other improvements are great, I would avoid changing this as part of this PR, keep it as is for now and open a different PR just for this change (with its impact obviously).

vicb

@HarelM

Maybe the best way to move forward is to remove the last commit from this PR.

I can then submit another PR making MapOptions.style optional and dropping all the other changes in that last commit as I don't think you find them useful?

vicb · 2024-05-23T04:31:13Z

src/ui/map.ts

        if (this.style) {
-            this.style.setEventedParent(null);
+            // transformStyle relies on having previous style serialized.


This is only code factorization:

this.style is tested on l 1732, 1737, and 1738 on the left

options.transformStyle is tested l 1732 and 1737 on the left

vicb · 2024-05-23T04:37:25Z

src/ui/map.ts

-    getImage(id: string): StyleImage {
-        return this.style.getImage(id);
+    getImage(id: string): StyleImage | undefined {
+        return this.style?.getImage(id);


Discussed offline with @HarelM

Summary of the discussion: What is the expected behavior of this function:

throw is not documented

the type of this.style: Style does not let users think it might throw

is it valuable to throw here?

I think the behavior should be consistent across methods.

Some might throw:

getImage(id: string): StyleImage { return this.style.getImage(id); }

Some are noops when style is undefined

redraw(): this { if (this.style) { // cancel the scheduled update if (this._frameRequest) { this._frameRequest.abort(); this._frameRequest = null; } this._render(0); } return this; }

Some warn when style is undefined

_updateDiff(style: StyleSpecification, options?: StyleSwapOptions & StyleOptions) { try { if (this.style.setState(style, options)) { this._update(true); } } catch (e) { warnOnce( `Unable to perform style diff: ${e.message || e.error || e}. Rebuilding the style from scratch.` ); this._updateStyle(style, options); } }

HarelM · 2024-05-23T07:08:50Z

Yes, let's drop the last commit and open an issue about the inconsistency of the methods.
Once we agree on the way forward in the issue we can continue to open a PR with the agreed upon changes.
It's not that I don't think they are valuable, it's just that they need a bit more discussion as some of them are breaking changes to public API methods in terms of behavior and I would like to make sure we discuss them properly.
Generally speaking, I agree that the current API is not consistent, and we should dive into it and see what improvements are considered low hanging fruits and what will need a breaking change as part of a breaking change version (see #3834) , but I believe it is out of scope for this PR.
In general, I would prefer to better document the current behavior in types and method docs as an initial non-breaking-change manner, and then later on, if needed, change the behavior as part of a breaking change version.

HarelM

THANKS!

vicb · 2024-05-23T07:51:06Z

Thanks for your help Harel!

vicb force-pushed the mapopttype branch from a471e7c to 5464136 Compare May 21, 2024 09:10

HarelM reviewed May 21, 2024

View reviewed changes

src/ui/map.ts Show resolved Hide resolved

HarelM reviewed May 21, 2024

View reviewed changes

src/ui/map.ts Outdated Show resolved Hide resolved

HarelM reviewed May 21, 2024

View reviewed changes

Improve the handling of map options

263365b

vicb force-pushed the mapopttype branch 4 times, most recently from 22aed2a to 093c84c Compare May 22, 2024 08:15

Get ride of the src/types

df31dcf

vicb force-pushed the mapopttype branch from 093c84c to 98670d0 Compare May 22, 2024 08:19

HarelM reviewed May 22, 2024

View reviewed changes

vicb commented May 23, 2024

View reviewed changes

vicb force-pushed the mapopttype branch from 98670d0 to df31dcf Compare May 23, 2024 07:33

HarelM approved these changes May 23, 2024

View reviewed changes

HarelM merged commit 6d49f57 into maplibre:main May 23, 2024
15 checks passed

vicb deleted the mapopttype branch May 23, 2024 07:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the handling of map options #4145

Improve the handling of map options #4145

vicb commented May 21, 2024

codecov-commenter commented May 21, 2024 •

edited

Loading

HarelM May 21, 2024

vicb May 21, 2024

HarelM May 21, 2024

vicb May 21, 2024

HarelM commented May 21, 2024 •

edited

Loading

vicb commented May 21, 2024

vicb commented May 22, 2024

HarelM commented May 22, 2024

HarelM May 22, 2024

vicb May 23, 2024

HarelM May 22, 2024 •

edited

Loading

vicb May 23, 2024

HarelM commented May 22, 2024

HarelM May 22, 2024

vicb left a comment

vicb May 23, 2024

vicb May 23, 2024

HarelM commented May 23, 2024

HarelM left a comment

vicb commented May 23, 2024

Improve the handling of map options #4145

Improve the handling of map options #4145

Conversation

vicb commented May 21, 2024

Launch Checklist

codecov-commenter commented May 21, 2024 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HarelM commented May 21, 2024 • edited Loading

vicb commented May 21, 2024

vicb commented May 22, 2024

HarelM commented May 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HarelM May 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HarelM commented May 22, 2024

Choose a reason for hiding this comment

vicb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HarelM commented May 23, 2024

HarelM left a comment

Choose a reason for hiding this comment

vicb commented May 23, 2024

codecov-commenter commented May 21, 2024 •

edited

Loading

HarelM commented May 21, 2024 •

edited

Loading

HarelM May 22, 2024 •

edited

Loading