Name (key) parts of components

[Malvoz]

In line with Open UI's component spec template we should name parts of components using the HTML part attribute.

This would enable author- and user style sheets (requested in #297) via the CSS ::part() pseudo-element. And to some extent help us answer how styling MapML with CSS works.

Example

If we set part="reload-button" on the reload button, authors (and users/user style sheets) can now style the reload button:

<style>
  ::part(reload-button) {
    color: white;
    background-color: black;
  }

  /* I also briefly experimented with feature styling */
  ::part(feature) {
    fill: green;
    stroke: lime;
  }

  /* or scoped (`:defined` is optional): `mapml-viewer:defined::part(...) {}` */
</style>

<mapml-viewer ... controls>
  <layer- ...>
</mapml-viewer>

Notes

We should document any named parts as eligible for styling (related: Maps4HTML/web-map-doc#26).

References

• HTML part attribute definition: https://www.w3.org/TR/css-shadow-parts/#part-attr (91%~ browser support)
• CSS ::part pseudo-element definition: https://www.w3.org/TR/css-shadow-parts/#part (91%~ browser support)

[prushforth]

Relative to @zcorpan's question, I was wondering what the pros and cons of going this route vs allowing the user to turn controls off / prune the set of controls that are presented, and subsequently provide their own controls, per how video works. I wonder if video will be updated to use parts? On the other hand, you're correct it might make for a more developer-friendly custom element. But I wonder if the platform would implement that stuff, and would it just be noise for platform implementers?

Relative to developers providing their own controls, it might be useful to consider a special 'static' layer, that the user could declaratively add and add their own controls to, and render / layout with CSS Grid, which would not pan or zoom with the map, i.e. would behave similar to what the Leaflet leaflet-control-container does (in leaflet's case, I believe by glancing at the example, the controls "layer" (it's a div with that class, that is a following sibling to the map container div) is always placed on top of all the other panes on the map (on top of the map container), and is thus static by virtue of not being selected by CSS transforms that apply to everything under the map container div.

[Malvoz]

this route vs allowing the user to turn controls off / prune the set of controls that are presented, and subsequently provide their own controls, per how video works.

An important consideration and difference between adding custom controls (for styling purposes) vs styling default controls is that in the latter accessibility & localization is mostly handled by the UA for the author.

I think defining parts for (default) controls in particular can be viewed as a precedent for potentially future standard pseudo-elements (although currently only vendor-prefixed ones are available for styling video controls, such as: ::-webkit-media-controls-*). How/whether authors should be able to style default controls I think largely depends on what the future holds for video.

I wonder if video will be updated to use parts?

Video and other native elements will not be updated to use parts. It is a way for us, using web components, to:

1. Enable styles to penetrate the shadow boundary to the defined parts
2. "Define the recommended DOM to represent the component's anatomy" per the Open UI component spec template, which will help us understand which required parts of components to propose for standardization (and also partly sets us up to potentially make an Open UI proposal for maps in the future if we were to go with that strategy).

would it just be noise for platform implementers?

After defining all necessary parts (possibly (and parts of) features, layers, controls, etc.), I think anything that is not defined as such can be considered noise (there are a lot of "unnecessary" div and span elements, e.g. leaflet-container is really just <map> in the MapML proposal).

it might be useful to consider a special 'static' layer, that the user could declaratively add and add their own controls

I think that'd complicate <layer>, and also looks semantically inappropriate. Amelia hinted at <map-control>. Which I think seems more reasonable. We should discuss adding custom controls in a separate issue.

[Malvoz]

Another example is setting part="layer" on (e.g.) the .mapml-layer div elements which enables authors to blend layers (#305):

::part(layer) { mix-blend-mode: /*<blend-mode>*/ }

[Malvoz]

In line with Open UI's component spec template we should name parts of components using the HTML part attribute.

An alternative/additional way to enable custom CSS is to utilize Custom Properties, as they apply cross shadow boundaries.

Example:

<style>
  mapml-viewer {
   --mapml-controls--size: 24px; /* overrides the value defined in mapml.css due to higher selector specificity */
  }
</style>

<mapml-viewer>
  #shadow-root
  <link rel="stylesheet" src="mapml.css">
  <!-- mapml.css:
  :host {
    --mapml-controls--size: 44px;
  }
  .leaflet-control a {
    height: var(--mapml-controls--size);
    width: var(--mapml-controls--size);
  }
  -->
</mapml-viewer>

This approach would probably require a lengthy list of variable definitions though, depending on which parts of the map UI we want to allow customization of (controls (size, color, bg-color, etc.), features (fill, stroke, etc.), and so on).