# sgapps-scroller -- Transform-based Scroll Container

Links: [Home](../index.md)

A zero-size custom element that turns any `overflow: hidden` box into a wheel- and drag-scrollable area: it moves the content with a generated `transform` rule instead of a native scrollbar, exposes the position through `element.attrdata.SGAppsScroller` and reports every change with a bubbling `sgapps-scroll` DOM event. Written by SGApps.IO.

## Overview

`custom-elements/scroller` registers the tag `<sgapps-scroller>` with the framework's `custom-elements` module. The element is a **marker**, not a wrapper: you put it as the first child of the box you want to scroll and leave the content next to it. When the element is initialised (`__onInit`) it:

1. gives itself a random `attr-sgapps-scroller-id` attribute (a new value on every init),
2. remembers `node.parentNode` as the **container** and appends a `<div>` to itself that will hold the generated stylesheets,
3. builds a `<style>` element with one rule that translates every **following sibling** of the marker,
4. attaches the wheel listeners (`onmousewheel`, `mousewheel`, `DOMMouseScroll`) and the drag listeners (`selectstart`, `draggstart`, `mousedown`) to the **container**, and `mouseup`, `mouseleave`, `mousemove` to `window`,
5. stores its API object as `node.attrdata.SGAppsScroller` and renders the initial position read from `node.attrdata.scrollTop` / `node.attrdata.scrollLeft` (the attributes); from then on the setters write every new position back into those two keys.

The generated rule, for a marker at `scrollLeft = 0`, `scrollTop = 30`:

```css
sgapps-scroller[attr-sgapps-scroller-id="sgapps-scrollerohy07fo2s00000"] ~ * {
    -webkit-transform:  translateX( 0px ) translateY( -30px );
    -ms-transform:  translateX( 0px ) translateY( -30px );
    transform:  translateX( 0px ) translateY( -30px );
}
```

Every change of `scrollTop` / `scrollLeft` (wheel, drag, sync, or your code) clamps the value to `[0, max]` when the limits are on, stores it, regenerates the `<style>` and, when the stored value actually changed, dispatches `sgapps-scroll` on the element. Nothing scrolls natively: the module never touches the container's own `scrollTop` and the browser never shows a scrollbar.

The module depends on `custom-elements`, `extensions/prototype` (for `attrdata`, the `_()` helpers and `fn.mouse.position`) and `uri-load` (to link `custom-elements/scroller/style.css`). [`custom-elements/lib`](lib.md) registers it for lazy loading: the module is required the first time an `<sgapps-scroller>` tag is seen in the document (immediately if one is already there). Its export is `true`, resolved after the element has been registered (so every tag already in the page is initialised) and the stylesheet has been linked.

### Markup requirements

| Requirement | Why |
|-------------|-----|
| The container has a fixed (or otherwise constrained) size and `overflow: hidden` | The content is only *translated*; without `overflow: hidden` it simply moves out of the box. `scrollTopMax` / `scrollLeftMax` are computed from the container's size |
| The container is `position: relative` (or any positioned box) | `style.css` makes the marker `position: absolute`, 0.1 x 0.1 px, so it takes no space; a positioning context keeps it inside the box |
| `<sgapps-scroller>` is the **first child** | The rule uses the general sibling combinator `~ *`: only siblings **after** the marker move |
| The content is made of **elements** (usually one block `<div>`) | `~ *` matches elements only -- bare text nodes never move -- and `transform` does not apply to non-replaced inline boxes, so wrap inline content in a block |
| The element is already inside its container when it is initialised | The parent is captured once, in `__onInit`; listeners go on that parent. Insert the marker together with (or after) the container, never into a detached node you attach later |
| Every option attribute is present in the markup before initialisation | Options are read from `attrdata`, which is computed from the attributes on **first access and then cached** -- later `setAttribute` calls are not seen (`__onAttrChange` is a no-op). Change options at runtime through the API setters instead |
| Numeric and boolean options use the `attrb-` prefix | `attr-x` gives a string, `attrb-x` a `JSON.parse`d value. The getters accept numbers / booleans only: `attr-scroll-top="20"` renders the initial offset but `scrollTop` reads `0` and the first move jumps back |

## Getting Started

```html
<div class="viewport" style="position: relative; overflow: hidden; width: 300px; height: 160px;">
    <sgapps-scroller attrb-scroll-top="0"></sgapps-scroller>
    <div class="content">
        <p>... more content than fits in 300 x 160 ...</p>
    </div>
</div>
```

```js
App.require('custom-elements/lib').then(function (registerCustomElements) {
    // registers lazy loading of <sgapps-scroller>; the tag above is already in the page,
    // so the module is being required now
    registerCustomElements(function (err) {
        if (err) return console.error(err);
        // resolves with `true` once the element is registered and style.css is linked
        App.require('custom-elements/scroller').then(function () {
            var scroller = document.querySelector('sgapps-scroller').attrdata.SGAppsScroller;
            console.log(scroller.scrollTop, scroller.scrollTopMax); // 0 <overflow in px>
            scroller.scrollTopBy(40);                                // content moves up by 40 px
        });
    });
});
```

The wheel and the drag work without any code once the element is initialised. Use the API only when you need to move the content yourself or read where it is.

## API Reference

### Lifecycle callbacks (registered with `custom-elements`)

| Callback | When | What it does |
|----------|------|--------------|
| `__onInit` | On registration for the tags already in the document; for every tag inserted afterwards; again when an initialised element is moved (re-inserted) | Everything described in the Overview: id attribute, style holder, API object, listeners, first render from `attrdata.scrollTop` / `attrdata.scrollLeft` (not clamped, no event) |
| `__onAttrChange`, `__onContentChange` | After attribute / child changes | Guarded by `typeof SGAppsScroller.scrollCheckerInit === "function"` -- never defined, so **no-ops** |
| `__onRemove` | When the element is removed | Empty. The listeners on the old container and on `window` stay attached |

### `element.attrdata.SGAppsScroller`

The API object created by `__onInit` (`undefined` before). All state lives in the element's `attrdata` bag, so the object is a set of accessors plus a few methods:

```js
var node = document.getElementById('s1');
var scroller = node.attrdata.SGAppsScroller;
```

#### Position

| Property | Type | Get | Set |
|----------|------|-----|-----|
| `scrollTop` | number | `attrdata.scrollTop` when it is a number, otherwise `0` | Numbers only (anything else is silently ignored). Clamped to `[0, scrollTopMax]` when `scrollLimitEnabled && scrollLimitEnabledOy`. Stores the value, re-renders the `<style>`, dispatches `sgapps-scroll` when the stored value changed |
| `scrollLeft` | number | `attrdata.scrollLeft` when it is a number, otherwise `0` | Same, with `scrollLeftMax` and `scrollLimitEnabledOx` |
| `scrollTopMax` | number, read-only | `max(sum of the heights of every child node of the container - container height, 0)`; `0` when the element has no parent | -- |
| `scrollLeftMax` | number, read-only | Same with widths | -- |

The sizes come from the `r()` helper of `extensions/prototype`: `clientHeight` / `clientWidth` of an element, and **`1` for anything without a size** -- whitespace text nodes and the 0.1 px marker itself. With the usual markup (one content `<div>`, whitespace between the tags) `scrollTopMax` is the real overflow plus a few pixels; with several block siblings their widths are summed (`scrollLeftMax` far too large) and margins that collapse through a sibling are not counted.

#### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `scrollTopBy(px)` | `undefined` | `scrollTop = scrollTop + (parseFloat(px) \|\| 0)` -- strings are parsed, `NaN` counts as 0 |
| `scrollLeftBy(px)` | `undefined` | Same for the horizontal axis |
| `scrollTopRelative([i])` | number | With a number `i`: `scrollTop = scrollTopMax * i` (`0` = start, `1` = end, clamped like any set). Always returns `scrollTop / scrollTopMax` -- `NaN` when `scrollTopMax` is `0` |
| `scrollLeftRelative([i])` | number | Same for the horizontal axis |
| `isDragging()` | boolean | `true` between a left-button `mousedown` on the container and the next `mouseup` on the window |
| `initDrag(pos)` | `undefined` | Starts a drag at `pos` (`{ x, y }` in page coordinates). Cancels a running drag first, remembers `pos` and the current `scrollTop` / `scrollLeft` |
| `updateDrag(pos)` | `null` when not dragging, else `undefined` | `scrollTop = startScrollTop - (pos.y - start.y)` when `draggEnabled && draggEnabledOy`; `scrollLeft = startScrollLeft - (pos.x - start.x)` when `draggEnabled && draggEnabledOx`. One pixel of pointer movement is one pixel of scroll; `scrollSpeed` is **not** applied to drags |
| `cancelDrag()` | `undefined` | Clears the drag flag |
| `styleRender.update()` | `undefined` | Regenerates the `<style>` from the last stored values. Old `<style>` nodes are trimmed so the holder keeps at most 4; the newest wins by cascade order |
| `_vars` | object | Internals: `pNode`, `flags.mouseDownFlag` (`null` or `{ ev, scrollTop, scrollLeft }` of the drag start), `scrollTop` / `scrollLeft` (last rendered values), `styleNode` (the holder `<div>`), `pMaxTop` / `pMaxLeft` |

#### Option properties

Each option is an accessor backed by `attrdata` (so the attribute value is the initial value). Boolean setters accept booleans only and otherwise print `SGAppsScroller.<name> is not boolean, <value>` with `console.log` and ignore the value; numeric setters silently ignore non-numbers; the string setter logs `... is not string` for non-strings.

| Property | Type | Default | Read by | Effect |
|----------|------|---------|---------|--------|
| `scrollCssTransformPrefix` | string | none (the getter returns `true` when unset, which the renderer ignores) | `styleRender.update()` | Text prepended to the generated `transform` value, e.g. `'scale(0.5)'` -> `transform: scale(0.5) translateX(...) translateY(...)` -- combine the scrolling with your own transform on the content |
| `scrollLimitEnabled` | boolean | `true` | `scrollTop` / `scrollLeft` setters | Master switch of the clamping. Off: negative values and values beyond the max are stored and rendered |
| `scrollLimitEnabledOx` | boolean | `true` | `scrollLeft` setter | Clamp the horizontal axis (needs `scrollLimitEnabled` too) |
| `scrollLimitEnabledOy` | boolean | `true` | `scrollTop` setter | Clamp the vertical axis (needs `scrollLimitEnabled` too) |
| `draggEnabled` | boolean | `true` | `updateDrag`, `selectstart` / `draggstart` handlers | Master switch of the drag: `false` stops both axes and lets text be selected again in the container |
| `draggEnabledOx` | boolean | `true` | `updateDrag` | Drag moves the horizontal axis |
| `draggEnabledOy` | boolean | `true` | `updateDrag` | Drag moves the vertical axis |
| `draggOutsideEnabled` | boolean | `false` | `mousedown` handler | The drag starts only when the pointer's page position is inside the container's box. `true` skips the test -- also the only way to get drags on a **scrolled page** (see Caveats) |
| `wheelEnabled` | boolean | `true` | wheel handler | Master switch of the wheel |
| `mouseWheelReverseAxis` | boolean | `false` | wheel handler | Swaps `deltaX` and `deltaY`: a vertical wheel scrolls horizontally. The vertical branch still multiplies the **original** `ev.deltaY`, so a purely horizontal gesture scrolls nothing (see Caveats) |
| `mouseWheelReverseDirection` | boolean | `false` | nothing | Accessor exists, never read |
| `scrollSpeed` | number | `1` | wheel handler | Multiplier of every wheel delta (both axes) |
| `scrollSpeedOx`, `scrollSpeedOy` | number | `1` | wheel handler | Extra multiplier per axis |
| `minStepOx`, `maxStepOx`, `minStepOy`, `maxStepOy` | number | `1`, `100` | nothing | Accessors exist, never read |

Two more `attrdata` keys are read directly, without an accessor: `sgappsSyncSelectors` (string) and `sgappsSyncInversed` (truthy) -- see [Sync](#sync). They are plain properties of the bag: `node.attrdata.sgappsSyncSelectors = '#other'` takes effect on the next event.

### Input handling

**Wheel.** The handler is registered three times on the container: as `container.onmousewheel`, with `addEventListener('mousewheel')` and with `addEventListener('DOMMouseScroll')` (no standard `wheel` listener). It returns when `wheelEnabled` is `false`; otherwise it reads `deltaX` / `deltaY`, swaps them when `mouseWheelReverseAxis` is set, and calls `scrollLeftBy(deltaX * scrollSpeed * scrollSpeedOx)` and `scrollTopBy(ev.deltaY * scrollSpeed * scrollSpeedOy)`. The event is never `preventDefault`ed. In Chromium the legacy `mousewheel` event fires **both** the `onmousewheel` property handler and the `addEventListener` one, so one wheel tick scrolls twice its delta -- calibrate `scrollSpeed` on the browser you target. The `DOMMouseScroll` branch (Firefox) synthesises `deltaY = ev.detail * ev.movementY`, and `movementY` is `0` on that event, so **the wheel does nothing in Firefox**; the drag works there.

**Drag.** A **left-button** `mousedown` on the container (other buttons are ignored) is hit-tested against the container's box unless `draggOutsideEnabled`: the pointer's `pageX` / `pageY` must lie inside `PXY()` + `r()` of the container. `PXY()` subtracts the scroll offset of every ancestor, the document included, so it yields viewport coordinates while the pointer is in page coordinates: as soon as the page is scrolled, the test fails by the scroll distance and no drag starts. When the test passes, `initDrag(pos)` is called; `mousemove` on `window` calls `updateDrag(...)` (one `scrollTop` set, then one `scrollLeft` set -- up to two `sgapps-scroll` events per pointer move); `mouseup` on `window` calls `cancelDrag()`. Moving the pointer 20 px up moves the content 20 px up. Because the move and release listeners are on `window`, a drag continues outside the container and ends wherever the button is released. `selectstart` on the container is prevented while `draggEnabled` is `true`, so text inside the box cannot be selected with the mouse; the `draggstart` listener is a typo of `dragstart` and never fires. Single-finger touches are converted to mouse events by `extensions/prototype`, which is how the drag works on touch screens (the native page scroll is not prevented).

### `element.methods`

| Method | Returns | Description |
|--------|---------|-------------|
| `el.methods.scrollCheckerStop()` | `undefined` | `clearInterval` of a timer that is never set -- a no-op kept from an earlier polling design |

The lifecycle callbacks are reachable through `methods` as well (`el.methods.__onInit()` re-initialises the element -- see Caveats before doing that).

## Events

| Event | Arguments | Description |
|-------|-----------|-------------|
| `sgapps-scroll` | none -- a plain `Event`, `bubbles: true`, `cancelable: true`, no `detail` | Dispatched **synchronously** on the `<sgapps-scroller>` element from the `scrollTop` / `scrollLeft` setters, after clamping and rendering, only when the stored value changed. Read the position from `ev.target.attrdata.SGAppsScroller`. Not dispatched for the initial position taken from the attributes or for sets that end at the same value (wheel at the end of the content). `preventDefault()` changes nothing: the position is already stored and rendered |

```js
// one listener for every scroller on the page: the event bubbles
document.addEventListener('sgapps-scroll', function (ev) {
    var s = ev.target.attrdata.SGAppsScroller;
    console.log(ev.target.id, s.scrollTop, '/', s.scrollTopMax, '=', s.scrollTopRelative());
});
```

### Sync

The element registers its own `sgapps-scroll` listener. When `attrdata.sgappsSyncSelectors` (attribute `attr-sgapps-sync-selectors`) is set, every event runs `document.querySelectorAll(selectors)` and, for each result that is an `sgapps-scroller` element, copies the **relative** position:

| `attrb-sgapps-sync-inversed` | Target receives |
|------------------------------|-----------------|
| not set | `target.scrollTopRelative(source.scrollTopRelative())` then `target.scrollLeftRelative(source.scrollLeftRelative())` |
| `"true"` | `target.scrollTopRelative(source.scrollLeftRelative())` then `target.scrollLeftRelative(source.scrollTopRelative())` |

Both axes are always copied. Because positions are relative, boxes with different content sizes stay proportionally aligned. Two scrollers may point at each other: the round trip stops as soon as a set produces the same stored value (normally the first or second echo, with float drift such as `20` -> `20.000000000000004`). Errors thrown in the listener (an invalid selector, a target that is not initialised yet) are caught and reported with `console.warn('sgapps-scroller Sync Selecting ... ', err)`.

The source must overflow on **both** axes: when its max on an axis is `0`, the relative helper returns `0/0 = NaN`, the target stores `NaN`, its rule becomes `translateX( NaNpx )` (invalid -- the browser drops the whole `transform`) and a mutual sync recurses until `RangeError: Maximum call stack size exceeded` (see Caveats).

## Attributes

| Attribute | `attrdata` key | Type | Default | Used | Description |
|-----------|----------------|------|---------|------|-------------|
| `attrb-scroll-top` | `scrollTop` | number | `0` | yes | Initial vertical offset, rendered as is (not clamped, no event) |
| `attrb-scroll-left` | `scrollLeft` | number | `0` | yes | Initial horizontal offset |
| `attr-scroll-css-transform-prefix` | `scrollCssTransformPrefix` | string | none | yes | Prefix of the generated `transform` value |
| `attr-sgapps-sync-selectors` | `sgappsSyncSelectors` | string (CSS selector list) | none | yes | Scrollers to update on every `sgapps-scroll` event of this element |
| `attrb-sgapps-sync-inversed` | `sgappsSyncInversed` | boolean | `false` | yes | Cross the axes when syncing. Truthiness check: with the `attr-` prefix even `"false"` is a non-empty string and enables it |
| `attrb-scroll-limit-enabled` | `scrollLimitEnabled` | boolean | `true` | yes | Clamp positions to `[0, max]` |
| `attrb-scroll-limit-enabled-ox` / `-oy` | `scrollLimitEnabledOx` / `Oy` | boolean | `true` | yes | Clamp per axis |
| `attrb-dragg-enabled` | `draggEnabled` | boolean | `true` | yes | Drag on / off (also text selection in the container) |
| `attrb-dragg-enabled-ox` / `-oy` | `draggEnabledOx` / `Oy` | boolean | `true` | yes | Drag per axis |
| `attrb-dragg-outside-enabled` | `draggOutsideEnabled` | boolean | `false` | yes | Skip the "pointer inside the container" test on `mousedown` |
| `attrb-wheel-enabled` | `wheelEnabled` | boolean | `true` | yes | Wheel scrolling |
| `attrb-mouse-wheel-reverse-axis` | `mouseWheelReverseAxis` | boolean | `false` | yes (partly) | Vertical wheel scrolls horizontally; horizontal wheel scrolls nothing |
| `attrb-mouse-wheel-reverse-direction` | `mouseWheelReverseDirection` | boolean | `false` | no | Dead option |
| `attrb-scroll-speed`, `-ox`, `-oy` | `scrollSpeed`, `scrollSpeedOx`, `scrollSpeedOy` | number | `1` | yes | Wheel multipliers |
| `attrb-min-step-ox`, `attrb-max-step-ox`, `attrb-min-step-oy`, `attrb-max-step-oy` | `minStepOx`, ... | number | `1`, `100` | no | Dead options |
| `attr-sgapps-scroller-id` | `sgappsScrollerId` | string | generated | internal | Written by `__onInit`; keys the generated rule. Do not set it yourself |
| `attrb-scroll-top-initial`, `attrb-scroll-left-initial` | -- | -- | -- | no | Listed in the module's `readme.md` and used in its test template, but nothing in the code reads them |

## CSS Surface

| Where | Rule | Notes |
|-------|------|-------|
| `custom-elements/scroller/style.css` (linked when the module loads) | `sgapps-scroller { display: inline-block; height: 0.1px; width: 0.1px; position: absolute; }` | Makes the marker invisible and flow-free |
| generated `<style>` inside the marker's holder `<div>` | `sgapps-scroller[attr-sgapps-scroller-id="<id>"] ~ * { transform: <prefix> translateX( -<scrollLeft>px ) translateY( -<scrollTop>px ); }` (+ `-webkit-` / `-ms-`) | One new `<style>` per position change; the holder keeps the last 4. Specificity `0,1,1`: a class rule on the content loses to it, an inline `style="transform: ..."` on a sibling wins and breaks the scrolling |
| your container | `overflow: hidden; position: relative; width / height` | Not provided by the module |
| optional, your content | `sgapps-scroller ~ * { transition: transform .15s ease-out; }` | Animates every step (wheel, buttons, sync). Avoid it for drags, which should follow the pointer |

## Use Cases

### A vertical list with a custom scrollbar indicator

```js
App.require('custom-elements/scroller').then(function () {
    var node = document.getElementById('list-scroller');
    var scroller = node.attrdata.SGAppsScroller;
    var track = document.getElementById('track');
    var thumb = document.getElementById('thumb');

    var render = function () {
        var max = scroller.scrollTopMax;
        var viewport = document.getElementById('list').clientHeight;
        var ratio = viewport / (viewport + max);
        thumb.style.height = Math.max(ratio * 100, 8) + '%';
        thumb.style.top = (max ? scroller.scrollTopRelative() : 0) * (100 - Math.max(ratio * 100, 8)) + '%';
    };

    node.addEventListener('sgapps-scroll', render);
    render(); // the initial position never emits an event

    track.addEventListener('click', function (ev) {
        var rect = track.getBoundingClientRect();
        scroller.scrollTopRelative((ev.clientY - rect.top) / rect.height);
    });
});
```

### A fixed header row above a scrolling table

```html
<div class="pane" id="head-pane">
    <sgapps-scroller id="head" attrb-wheel-enabled="false" attrb-dragg-enabled="false"></sgapps-scroller>
    <table class="wide"><thead> ... </thead></table>
</div>
<div class="pane" id="body-pane">
    <sgapps-scroller id="body" attr-sgapps-sync-selectors="#head"></sgapps-scroller>
    <table class="wide"><tbody> ... </tbody></table>
</div>
```

```js
App.require('custom-elements/scroller').then(function () {
    var head = document.getElementById('head').attrdata.SGAppsScroller;
    // both axes are always copied: the header's vertical max is 0 or a few px, so pin it
    document.getElementById('head').addEventListener('sgapps-scroll', function () {
        if (head.scrollTop !== 0) head.scrollTop = 0;
    });
});
```

### Scroll an element into view, page through the content

```js
var container = document.getElementById('viewport');
var node = container.querySelector('sgapps-scroller');
var scroller = node.attrdata.SGAppsScroller;

var scrollIntoView = function (target) {
    var content = node.nextElementSibling;
    scroller.scrollTop = target.getBoundingClientRect().top - content.getBoundingClientRect().top;   // clamped
};
var pageDown = function () { scroller.scrollTopBy(container.clientHeight - 20); };
var atEnd = function () { return scroller.scrollTopMax > 0 && scroller.scrollTopRelative() >= 1; };
```

### Runtime configuration and dynamically added boxes

```js
var scroller = document.getElementById('s1').attrdata.SGAppsScroller;
scroller.scrollSpeed = 0.5;               // half wheel speed
scroller.wheelEnabled = false;            // freeze the wheel while a modal is open
scroller.draggEnabled = false;            // no dragging, text selectable again
scroller.scrollCssTransformPrefix = 'scale(0.8)';   // zoomed-out content that still scrolls

// a box created later: the MutationObserver initialises the marker after insertion (asynchronously)
var box = document.createElement('div');
box.className = 'viewport';
box.innerHTML = '<sgapps-scroller attrb-scroll-top="40" attrb-scroll-speed="2"></sgapps-scroller><div class="content">' + bigHtml + '</div>';
document.body.appendChild(box);
setTimeout(function () {
    console.log(box.firstChild.attrdata.SGAppsScroller.scrollTop); // 40
}, 0);
```

## Caveats

| Caveat | Impact |
|--------|--------|
| Dragging does not start while the page is scrolled | The `mousedown` hit test compares page coordinates with `PXY()` (viewport coordinates): with the page scrolled, a press inside a box starts no drag. Work-around: `draggOutsideEnabled = true`, or keep the box in an unscrolled page |
| The wheel handler runs twice per tick in Chromium | Registered both as `container.onmousewheel` and with `addEventListener('mousewheel')`. Firefox has no `mousewheel` event; its `DOMMouseScroll` path computes `0`, so the wheel does nothing there |
| The wheel is never `preventDefault`ed | The page (or any scrollable ancestor) scrolls along with the box, also at the limit or with `wheelEnabled = false`. Add your own `wheel` listener with `preventDefault()` on the container if that matters |
| `mouseWheelReverseAxis` is half-implemented | After swapping the deltas the vertical branch still uses `ev.deltaY`: vertical wheel -> horizontal scroll works, horizontal wheel -> nothing |
| Options are read once | `attrdata` is built on first access and cached; `__onAttrChange` is a no-op. `setAttribute('attrb-wheel-enabled', 'false')` after init changes nothing; use `SGAppsScroller.wheelEnabled = false` |
| Numeric / boolean options need the `attrb-` prefix | `attr-scroll-top="20"` yields the string `"20"`: the initial render uses it but the getter returns `0`, so `scrollTopBy(10)` jumps to 10, not 30 |
| `scrollTopMax` / `scrollLeftMax` count every child node of the container | Text nodes and the marker count 1 px each; borders and margins of the siblings are ignored; block siblings stacked vertically have their **widths summed** for `scrollLeftMax`. Keep one content element per box |
| Relative helpers return `NaN` when the max is `0` | Guard with `scrollTopMax > 0` |
| Sync from a scroller whose max is `0` on an axis corrupts the target | The target receives `NaN` and its `transform` becomes invalid -- it stops moving on **both** axes until a number is set on that axis again; a mutual sync between two such scrollers recurses until `RangeError: Maximum call stack size exceeded`. Both boxes must overflow on both axes, or sync one way only and pin the other axis of the target (see the table example) |
| The sync round trip drifts | Relative positions are multiplied back: `s1.scrollTop = 10` can come back as `10.000000000000002`, with an extra event. Round the values you display |
| The initial position is not clamped and emits no event | `attrb-scroll-top="500"` in a box with `scrollTopMax` 77 renders `translateY(-500px)` (blank box) until the first move; indicators built from the event must render once by hand after init |
| Clamping uses the layout of the moment | `scrollTopMax` is recomputed on every set; nothing re-clamps when the content grows or shrinks later |
| Every scroll step creates a `<style>` element | The holder keeps up to 4; fine for wheel and drag, but do not drive animations through the setters at 60 fps on large pages |
| `__onRemove` cleans nothing | Removing the marker leaves the listeners on the old container and on `window`. The siblings snap back to `transform: none` because the generated rule leaves with the element |
| Re-inserting or moving an initialised marker runs `__onInit` again | New random id, new API object (old references are stale), a second holder and another set of listeners (the wheel step then triples). Create the marker in its final place |
| Native scrolling of the container adds up | `overflow: hidden` does not stop `focus()`, `scrollIntoView()` or find-in-page from scrolling the box natively; the module neither reads nor resets `container.scrollTop`. Reset it yourself (for example on `focusin`) |
| The `mouseleave` handler on `window` references an undeclared `ev` | A `ReferenceError` if the event ever reaches `window`; browsers do not deliver it there in practice, so a drag ends only on `mouseup` |
| Only following **elements** move | Text nodes directly inside the container stay in place; inline siblings ignore `transform`. Wrap the content in one block element |
| No keyboard, no scroll-snap, no inertia | Arrow keys, Page Up / Down, Home / End and momentum scrolling are not implemented -- wire them to `scrollTopBy()` / `scrollTopRelative()` yourself |

## Notes

- Live demo: [playground](playground.html#module=scroller ':ignore :target=_blank') -- boxes A and B are synced, C reverses the wheel axis, the buttons drive the API on A.
- Related: [custom-elements/lib](lib.md) (registration), the framework's `custom-elements` (`registerMethods`, `lazyLoadModules`, `element.methods`) and `extensions/prototype` (`attrdata`, `fn.mouse.position`, the `_()` helpers).