feature: Promote the basemap toggle

[theduckylittle]

This moves the basemap toggle to a first class component.

There hasn't been any known traction on the experimental API but there was uptake of the basemap switcher component itself.

This also fixes some bugs with the previous implementation:

1. It is more determinante than the previous one. Mostly because it's using internal selectors and wired right to the store.
2. The CSS is more sane and ported to Less so folks can more easily override the styling without rewriting the inline styles of the component.

Screencast.From.2026-08-02.11-47-47.mp4

[chughes-lincoln]

I have a couple comments.

1. The basemap toggle doesn't behave well with other layers in your radio buttons group in the catalog that aren't in the basemap-toggle list. See below - I turned on the County Aerial (COG) layer, and then switched it to No background using the toggle. Now both No background and County Aerial (COG) are on.

2. My other concern is that the toggle isn't keyboard navigable and doesn't comply with WCAG. I was experimenting a bit with the underlying code and think I have it 90% there (other than needing to adjust the css). Essentially I changed the individual basemap-toggle-chips from divs to buttons (lines 52 and 59 of basemap-toggle.js), as well as the overarching basemap toggle (lines 97 and 113 of basemap-toggle.js). I then added onFocus and onBlur so that navigating to the basemap-toggle then opens it.

<button
      onMouseOver={() => setOpen(true)}
      onFocus={() => setOpen(true)}
      onMouseOut={() => setOpen(false)}
      onBlur={() => setOpen(false)}
      className={`basemap-toggle ${isOpen ? "full-open" : ""}`}
    >
      {layers.map((layer, idx) => (
        <BasemapToggleChip
          key={layer.path || idx}
          label={layer.label}
          src={layer.src}
          path={layer.path}
          active={idx === activeIndex}
          open={isOpen || idx === activeIndex}
          onClick={() => handleLayerClick(layer)}
        />
      ))}
    </button>

The only issue I had with this is that changing the basemap-toggle-chips to buttons made them look a bit odd (similar to how changing the Tabs to buttons made them look odd before we adjusted the css - i.e. it inherits some settings from buttons)

[chughes-lincoln]

Also, I don't know if there would be interest in this, but I was experimenting with more of a simplified UI just with CSS changes and am pretty happy with how it turned out. Could be added as an example in the docs.

[theduckylittle]

I just pushed a few updates that I think are worthwhile:

• There is a separate commit that now tracks mapbook readiness in the ui reducer. This is a missing oversight from years of development but was made particularly useful here. It might serve to do some more UI optimization into the future to prevent re-paints on Mapbook load.
• There is now an error state (see picture) with helpful warning messages in the console and a tooltip the user.
• I've migrated to buttons. There's probably a better "highlighted" state we could implement using borders... I'm open to ideas but this was in spirit of the previous component but with more sane styling.

[elil]

An error to the user, even with tool tip,

might not be the most straight forward for what is partly a site configuration issue. The console message is useful to the dev/admin.

Are there ways to allow for using the layer switcher or buttons for fewer than all the background/basemap layers? Maybe start with turning all of the basemap layers off then adding the one that was selected?

I see the role of the basemap toggle for very basic users who might search one default thing and toggle one basemap button and then leave. For users willing to use the TOC, there are lots of basemaps, etc. I don't see the button/toggle users as advanced users.

[chughes-lincoln]

The keyboard navigation changes look good to me.

[theduckylittle]

@elil,

might not be the most straight forward for what is partly a site configuration issue. The console message is useful to the dev/admin.

I was trying to give the user a path to issue elevation. For captive users like a city employee, they'd be able to reach out and say "Hey! This looks broken, plz can fix?" I think it's a sensible to have an error state but I definitely sympathize with making it less reachable.

Are there ways to allow for using the layer switcher or buttons for fewer than all the background/basemap layers?Maybe start with turning all of the basemap layers off then adding the one that was selected?

We don't have a bespoke "background" flag. It's only a constructed concept that the mapbook allows us to more-or-less "mock."

This obviously appears a bit more broken in our demo than I think it would be on a live site. I have a few thoughts on how we could move forward:

1. We could comment this out by default and add a "use at your own danger" warning with links to the docs. This has the disadvantage of not showing off the component which I think is a nice addition for those more basic users.
2. Curate our demo config on the basemap list. This may show fewer default backgrounds but would give us a more complete experience in the demo.
3. Require that the basemap toggle point to a "exclusive group," as we have implemented the basemaps in the demo. This may get a little tricky as we'd need to make some rough code as to how to render a thumbnail or expand the mapbook to allow defining a thumbnail. I'd lean towards expanding the mapbook definition with a thumb-url= or similar. This would prevent the basemap toggle from ever being invalid but there will be constraints on how many layers the user may want in that exclusive toggle.
4. "A better dead pedal" if folks have a better idea on a neutral state then we can just move forward with that instead of the error state as implemented.

[elil]

Can the layers to turn off be caught by group title? Like catching all layers within the "Backgrounds" group title here,

gm3/examples/desktop/mapbook.xml

Line 529 in f2876d7

<group title="Backgrounds" expand="true" multiple="false">

, for the layers to turn off before turning on the toggled layer (at least when multiple="false"). So the toggle is essentially a layer selector within that group title.

multiple="true", nested groups, or toggling between multiple groups might make things a little more complicated.

[elil]

Or I guess a brute force method could be configuring all the layers to turn off before turning the toggled layer on. Essentially enumerating what is a "background" for the toggle. That could simplify some of the complexity of pulling from nested group titles or multiple group titles.

[klassenjs]

Could we just point the basemap toggle at a mapbook group instead of giving it it's own layer list? I think that would get rid of most of the confusing behavior between the layer control and this new control.

(It wouldn't need to even necessarily be an exclusive group, but probably only makes sense for leaf groups. Click on the new control just toggles that layer and if other layers turn off is part of the normal group handling.)

[chughes-lincoln]

I think the issue is when you have a lot of datasets in that mapbook group (i.e. historical imagery).

I wouldn't want all of these layers to show up in a basemap toggle (vs just None, the latest aerial, and maybe something like OpenStreetMap). I think my ideal behavior would be that the basemap toggle is essentially just a subset of a radio buttons group, where if you switch away from the toggle layers, they would just show as inactive (i.e. in the screenshot below they would all be gray, rather than two gray and one green).

[klassenjs]

I wouldn't select that group for the basemap toggle. Also, the nesting could be a problem.

[tchaddad]

Another perspective after reviewing:

The current behavior is fine, it's just that the "error" message is misleading, or not really even indicative of an error, just a potentially confusing situation.

If the message was portrayed as informational rather than as an error, it could simply inform the user with a message along the lines of something like this:

FYI: The selected Base Map is outside of the Quick Switch Base Map options, and so the Base Map Switcher is not currently available...

As currently implemented, the message appears anytime an option outside the configured set is used, but the switcher returns as soon as the user is using an option from the set again.

For the UX to make sense, it would be best to show the user which layers in the TOC are part of the Quick Switch set:

Is this a reasonable compromise? Can the alert style be changed from "Danger" to "info"?

[elil]

How the basemap toggle/switcher should work really depends on goals or target audience. I see the role of the basemap toggle for very basic users who might search one default thing and toggle one basemap button and then leave. For users willing to use the TOC, there are lots of basemaps, etc. I don't see the button/toggle users as advanced users. For advanced users the toggle is just a click saver. They can switch from the few "popular" options in the toggle or many more options themselves in the TOC since they know how to use the site.

Most of these improvements target what I think are more advanced users. I think all those error message and other things are great for those users. I just don't see those users as the target of this tool. I'm targeting the user who comes to the site, types a random thing in a search box (name, address, map-taxlot, etc), gets zoomed to that result, turns on some basemap toggle, and leaves. Maybe an advanced "drive-by" user would get as advanced as clicking a neighboring property with the identify tool. I don't see these drive-by users reading anything much less sorting out a new vocabulary to know what it means and how to take action on it. I'm expecting these drive-by users, after minimal effort and minimum time duration (achieving either success or failure), to leave the site.

[tchaddad]

How the basemap toggle/switcher should work really depends on goals or target audience. I see the role of the basemap toggle for very basic users who might search one default thing and toggle one basemap button and then leave.

I feel like my comment is consistent with this target audience, and my suggestion is to not update the behavior in this PR, but to improve the style/content/presentation of the messages that pop-up.

[elil]

This may be a difference of opinion of our users 😂.

I think half of our users would be helped and half would be hurt by this:

FYI: The selected Base Map is outside of the Quick Switch Base Map options, and so the Base Map Switcher is not currently available...

The users who would be helped are already capably self-serving themselves in the TOC and I'm not worried about them.

[tchaddad]

Haha, so then I am completely missing your point! What behavior change are you requesting in how the new feature works?

The message you highlighted is intended to be for the people who would be confused if they got themselves into a situation where they bumped into it. Advanced users already don't have a problem that needs to be solved. Or at least that is how I interpret the situation, which seems consistent with what you are saying...

[chughes-lincoln]

I think the issue is that it still forces the toggle users to then go into the TOC to get the basemap toggle working again (instead of being able to use the toggle to switch back to one of the toggle layers - i.e. I can use the catalog to switch to some old imagery layer (which turns off the OpenStreetMap layer as it's in the same radio button group), I can then use the toggle to switch to OpenStreetMap, which turns off the old imagery layer.)

In my ideal scenario the basemap toggle is just giving you a shortcut to interacting with a subset of your radio buttons group (i.e. clicking No background in the basemap toggle is equivalent to clicking No background in the TOC - and if you choose a layer in the TOC that's not in basemap toggle, it just switches the toggle layers to be inactive - i.e. in the screenshot below they would all be gray, rather than 2 gray and 1 green)