Pacem JS - <pacem-dock>

`<pacem-dock>` is a *sticky* container that knows when it is stuck. It holds on to the top (or the bottom) edge while
the page scrolls past it, and its `docked` property tells you whether it is stuck right now: a header that grows a shadow,
a total that stays in reach, a bar that changes its mind.

```html
<pacem-dock id="bar" style="top: var(--pacem-layout-header-height)">...</pacem-dock>

<pacem-dock snap="bottom" css-class="{{ { 'rise-3': #bar.docked } }}">...</pacem-dock>
```

## Usage

**Stick it.** `snap` is `top` (default) or `bottom`: the dock holds on to that edge of the viewport, without leaving
its parent. The element has no look of its own, it is a place to put things.

**Mind the header.** The top edge of the *viewport* sits behind the site header: offset the dock with `top` (or `bottom`),
and the layout has a token for the header: `--pacem-layout-header-height`.

```html
<pacem-dock style="top: var(--pacem-layout-header-height)">...</pacem-dock>
```

**Listen to it.** `docked` is `true` while the dock is stuck. It *emits*, so bindings follow it
(`{{ #bar.docked }}`) and so does `propertychange`.

> Being stuck is a CSS thing: the dock sticks anywhere `position: sticky` does. It can't leave its parent, and an ancestor
> with `overflow: hidden` breaks it. Inside a grid or flex parent it is confined to its own row: use a plain block.

**Know its limits.** The *awareness* needs `scroll-state` container queries, which today means Chromium: elsewhere the dock
still sticks, and `docked` stays `false`. It follows the **page** scroll, so a dock inside a scrolling box (a tab, a
dialog) sticks to *that* box, and `docked` is not meant for it. While the parent pushes the dock away at the end of its
run, it still counts as docked: *stuck* means displaced from its natural place.

## Customization

A dock is a surface-less box: color it as anything else, with the generic utilities, and let `docked` switch the elevation.

```html
<pacem-dock id="bar" class="surface fill-primary-container"
             css-class="{{ { 'rise-3': #bar.docked } }}">...</pacem-dock>
```

The edge distance is plain CSS (`top`, `bottom`), the layering too: a dock that must stay over the page content needs a `z-index`.

## Examples

### A total that stays in reach
`snap="bottom"`: the bar holds on to the bottom edge until the list ends, and lifts while it is stuck.

```html
<!-- <pacem-dock>: sticks to the bottom; docked lifts it -->
<pacem-dock id="bar" snap="bottom" class="surface fill-accent-container"
            css-class="{{ { 'rise-3': #bar.docked } }}">
    Total € 17.50
</pacem-dock>
```

### A bar that changes its mind
Under the site header, a title bar shows a hint only while it is stuck.

```html
<!-- <pacem-dock>: sticks under the site header -->
<pacem-dock id="bar" style="top: var(--pacem-layout-header-height)">
    Espresso menu
    <!-- shown only while the dock is stuck -->
    <pacem-span hide="{{ !#bar.docked }}" text="still reading?"></pacem-span>
</pacem-dock>
```