First pass at documenting-specifying how map media / container queries

should work.

Author: prushfor

docs/api/layer-api.md

@@ -124,6 +124,10 @@ To get the `<map-layer>`'s opacity value:
 let layer = document.querySelector('map-layer');
 let opacity = layer.opacity;
 ```
+---
+### media
+
+Reflects the [media](../elements/layer#media) attribute of the `<layer->` element.
 
 ### extent
 

docs/api/map-link-api.md

@@ -4,6 +4,21 @@ title: HTMLLinkElement
 slug: /api/map-link-api
 ---
 
+# HTMLLinkElement
+
+The `<map-link>` element is intended to implement an extension of the HTML `<link>` 
+element and `HTMLLinkElement` API. This document reflects proposed changes to that
+API and is a work in progress.
+
+
+## Properties
+
+### media
+
+Reflects the [media](../elements/link#media) attribute of the `<map-link>` element.
+
+---
+
 This document is copied from the old "Custom Rendering API" page, and is under
 construction.  It will eventually describe the API of the map-link custom element;
 the "Custom Rendering API" is currently sourced from the map-link custom element,

docs/api/mapml-viewer-api.mdx

@@ -222,6 +222,7 @@ let zoom = map.zoom;
 | [defineCustomProjection(options)](#definecustomprojectionoptions) 	| Define a custom projection for use by the page. |
 | [zoomTo(lat, lon, zoom)](#zoomtolat-lon-zoom) | Fly or pan the map to a (new) location and zoom level.|
 | [geojson2mapml(json, options)](#zoomtolat-lon-zoom) | Add a GeoJSON Layer to the map. |
+| [matchMedia(mediaQueryString)](#matchmediamediaquerystring)        | Returns a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList) object.
 
 
 ### back()
@@ -358,6 +359,20 @@ Check out [this application](https://maps4html.org/experiments/api/custom-map-ui
 
 ---
 
+### matchMedia(mediaQueryString)
+
+Returns a [MediaQueryList object](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
+The `matches` property of the MediaQueryList object can be used for an instantaneous
+determination of if the map meets the media conditions.  To react to changes in
+the map media conditions, use MediaQueryList.addEventListener('change', callbackFn)
+to add an event listener for `change` events that are triggered by changes in the 
+state of the queried map properties (projection, zoom, extent); any change to the
+map that results in a change in state of the 
+[MediaQueryListEvent `matches` boolean property](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList/change_event)
+triggers the `change` event and calls the callbackFn.
+
+---
+
 ## Events
 
 | Event name      	| Description                                          	|

docs/elements/layer.md

@@ -63,6 +63,21 @@ and the fetched `<map-title>` element is used.
 
 ---
 
+### `media`
+
+The `media` attribute is used to express media conditions under which the layer 
+content should be used / loaded from `src`.  Media conditions evaluate to `true` or `false`.  
+A layer for which the media condition evaluates to `false` is by default hidden.  
+A layer for which the media condition evaluates to `true` is added to the map 
+according to its `checked` attribute, and is added to the layer control according
+to its `hidden` attribute.
+
+Map media queries can include extended CSS map properties including:    
+[projection](../../api/mapml-viewer-api#projection), [zoom](../../api/mapml-viewer-api#zoom), 
+and [extent](../../api/mapml-viewer-api#extent).
+
+---
+
 ### `opacity`
 
 The `opacity` attribute is used to set the initial opacity of the `<map-layer>` element.
@@ -113,4 +128,4 @@ The following example sets the initial `opacity` for a `<map-layer>`.
 ---
 
 > - [Edit this page on **Github**](https://github.com/Maps4HTML/web-map-doc/edit/main/docs/elements/layer.md)
-> - [Chat with us on **Gitter**](https://gitter.im/Maps4HTML/chat)
+> - [Chat with us on **Gitter**](https://gitter.im/Maps4HTML/chat)

docs/elements/link.md

@@ -130,6 +130,20 @@ Projection values [defined by the polyfill](../mapml-viewer#projection) include:
 | Permitted ARIA roles | No roles permitted. |
 | DOM Interface    | [HTMLLinkElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement) |
 
+---
+### `media`
+
+The `media` attribute is used to express media conditions under which the linked 
+content should be loaded from its `href` attribute.  Media conditions evaluate to `true` or `false`.  
+A map-link for which the media condition evaluates to `false` is not loaded / unloaded.  
+Content linked via a map-link for which the media condition evaluates to `true` 
+is loaded from its `href` attribute; when the condition subsequently evaluates to
+`false`, the content is unloaded.
+
+Map media queries can include extended CSS map properties including:    
+[projection](../../api/mapml-viewer-api#projection), [zoom](../../api/mapml-viewer-api#zoom), 
+and [extent](../../api/mapml-viewer-api#extent).
+
 ---
 
 ## Examples

docs/elements/style.md

@@ -6,6 +6,22 @@ slug: /elements/style/
 
 The `<map-style>` element allows map authors to embed CSS into map layers. The CSS can be used to style the geometry of the layer using [`<map-span>`](../../elements/span/), and by setting the class attribute to the [child elements](../geometry/#child-elements) of the geometry.
 
+## Attributes
+
+### `media`
+
+The `media` attribute is used to express media conditions under which the contained 
+styles should be applied.  Media conditions evaluate to `true` or `false`.  A map-style 
+for which the media condition evaluates to `false` is not loaded / removed.  Styles 
+contained in a `<map-style>` for which the media condition evaluates to `true` 
+are applied; when the condition subsequently evaluates to `false`, the styles are removed.
+
+Map media queries can include extended CSS map properties including:    
+[projection](../../api/mapml-viewer-api#projection), [zoom](../../api/mapml-viewer-api#zoom), 
+and [extent](../../api/mapml-viewer-api#extent).
+
+---
+
 :::note
 
 All the Demo's on the documentation pages contain a "CSS" tab which adds the CSS using the `<map-style>` element dynamically.