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.