@esportsplus/ui 0.55.0 → 0.56.2

package/src/components/scroll-fade/scss/index.scss

@@ -0,0 +1,104 @@
+@use 'sass:list';
+@use 'variables';
+
+// Blur strength per progressive layer, weakest (furthest from the edge) first.
+$strengths: 0.25, 0.5, 1, 2;
+
+.scroll-fade {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    position: relative;
+
+    // Content scrolls under a wash of the page colour that is also blurred, and the wash's own mask fades it in, so
+    // text dissolves into the edge instead of being cut by a hard gradient line.
+    &-edge {
+        backdrop-filter: blur(var(--blur));
+        background: linear-gradient(var(--direction), transparent, var(--fade-color));
+        height: var(--size);
+        inset-inline: 0;
+        mask-image: linear-gradient(var(--mask-direction), #000 var(--stop), transparent);
+        pointer-events: none;
+        position: absolute;
+        transition: opacity var(--duration) ease-out;
+        user-select: none;
+        z-index: 30;
+
+        &--bottom {
+            --direction: to bottom;
+            --mask-direction: to top;
+            bottom: 0;
+        }
+
+        &--fixed {
+            position: fixed;
+        }
+
+        // A masked or translucent parent would cut its children's backdrop off from the page, so the progressive
+        // edge keeps itself plain and gives the wash and each blur band their own element.
+        &--progressive {
+            backdrop-filter: none;
+            background: none;
+            mask-image: none;
+
+            &::before {
+                background: linear-gradient(var(--direction), transparent, var(--fade-color));
+                content: '';
+                inset: 0;
+                mask-image: linear-gradient(var(--mask-direction), #000 var(--stop), transparent);
+                position: absolute;
+            }
+
+            &::before,
+            .scroll-fade-layer {
+                transition: opacity var(--duration) ease-out;
+            }
+
+            &.--hidden {
+                opacity: 1;
+
+                &::before,
+                .scroll-fade-layer {
+                    opacity: 0;
+                }
+            }
+        }
+
+        &--top {
+            --direction: to top;
+            --mask-direction: to bottom;
+            top: 0;
+        }
+
+        &.--hidden {
+            opacity: 0;
+        }
+    }
+
+    // Each band starts a quarter further toward the edge and blurs twice as hard, so the stack ramps smoothly.
+    &-layer {
+        inset: 0;
+        mask-image: linear-gradient(var(--mask-direction), #000 calc(100% - (var(--layer) + 1) * 25%), transparent calc(100% - var(--layer) * 25%));
+        position: absolute;
+
+        @for $i from 1 through list.length($strengths) {
+            &:nth-child(#{$i}) {
+                backdrop-filter: blur(calc(var(--blur) * #{list.nth($strengths, $i)}));
+            }
+        }
+    }
+
+    &-viewport {
+        flex: 1;
+        min-height: 0;
+        overflow-y: auto;
+
+        &.--no-scrollbar {
+            scrollbar-width: none;
+
+            &::-webkit-scrollbar {
+                display: none;
+            }
+        }
+    }
+}

package/src/components/scroll-fade/scss/variables.scss

@@ -0,0 +1,10 @@
+// Standalone edges carry their own defaults; edges inside a container inherit its values instead.
+.scroll-fade,
+.scroll-fade-edge:not(.scroll-fade > *) {
+    --blur: 3px;
+    --duration: 200ms;
+    --fade-color: var(--color-white-300);
+    --size: 110px;
+    // Portion of the fade, from the edge in, that is fully opaque before the mask starts letting content through.
+    --stop: 35%;
+}

package/src/components/scroll-spine/index.ts

@@ -0,0 +1,355 @@
+import { html, type Attributes } from '@esportsplus/template';
+import { reactive } from '@esportsplus/reactivity';
+import './scss/index.scss';
+
+
+type A = Attributes & {
+    [SCROLL_SPINE_BUTTON]?: Attributes;
+    height?: number;
+    items: Item[];
+    label?: string;
+    state?: State;
+    // The element that scrolls; the window when omitted. Headings are found by id either way.
+    target?: HTMLElement | (() => HTMLElement | null | undefined);
+};
+
+type Band = {
+    height: number;
+    top: number;
+};
+
+type Edge = {
+    omega: number;
+    target: number;
+    value: number;
+    velocity: number;
+};
+
+type Item = {
+    id: string;
+    label: string;
+};
+
+type State = {
+    active: number;
+};
+
+
+// Scroll positions land a few pixels short of the end on some trackpads.
+const END_SLACK = 4;
+
+// Room between bands so neighbouring sections read as separate pieces.
+const GAP = 8;
+
+// Below this width there is no room for headings beside the bands.
+const INLINE_MIN = 120;
+
+// Space left above a heading after jumping to it, so it isn't flush.
+const JUMP_OFFSET = 16;
+
+// Leading edge: quick, so the marker answers the scroll at once (critically damped, 0.24s visual duration).
+const LEAD = (2 * Math.PI) / (1.2 * 0.24);
+
+// The current-section block reaches a little past its band.
+const MARK_PAD = 4;
+
+// A one-paragraph section still gets a band big enough to hover and click, and, with labels, tall enough for its heading.
+const MIN_BAND = 14;
+
+const MIN_BAND_LABELLED = 24;
+
+// Where on screen the "reading line" sits: a third of the way down is where eyes rest while reading, so a section counts
+// as current once its heading passes that line, not only when it hits the very top.
+const READ_LINE = 0.3;
+
+const SCROLL_SPINE_BUTTON = Symbol.for('@esportsplus/ui/scroll-spine.button');
+
+// Trailing edge: slower on purpose, that lag is the stretch; 0.42s is the shortest lag where it still reads on a one-band move.
+const TRAIL = (2 * Math.PI) / (1.2 * 0.42);
+
+
+function reduced() {
+    return matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+// Exact critically damped step for any dt, so a retarget mid-flight keeps the edge's velocity and fast scrolling bends
+// the marker instead of restarting it.
+function step(edge: Edge, dt: number) {
+    let decay = Math.exp(-edge.omega * dt),
+        offset = edge.value - edge.target,
+        slope = edge.velocity + edge.omega * offset;
+
+    edge.value = edge.target + (offset + slope * dt) * decay;
+    edge.velocity = (edge.velocity - edge.omega * slope * dt) * decay;
+
+    if (Math.abs(edge.value - edge.target) < 0.05 && Math.abs(edge.velocity) < 1) {
+        edge.value = edge.target;
+        edge.velocity = 0;
+        return false;
+    }
+
+    return true;
+}
+
+
+function template(
+    this: { attributes?: Partial<A> } | void,
+    { height = 320, items, label = 'On this page', state = reactive({ active: 0 }), target, ...attributes }: A
+) {
+    let bands: Band[] = [],
+        bottom: Edge = { omega: LEAD, target: 0, value: 0, velocity: 0 },
+        cleanup: VoidFunction | undefined,
+        end = 0,
+        fills: HTMLElement[] = [],
+        frame = 0,
+        inline = true,
+        marker: HTMLElement | undefined,
+        motion = 0,
+        nav: HTMLElement | undefined,
+        notch: HTMLElement | undefined,
+        offsets: number[] = [],
+        placed = false,
+        rows: HTMLElement[] = [],
+        scroller: HTMLElement | undefined,
+        time = 0,
+        upper: Edge = { omega: TRAIL, target: 0, value: 0, velocity: 0 };
+
+    function animate(now: number) {
+        let dt = time ? Math.min((now - time) / 1000, 1 / 30) : 1 / 60,
+            moving = step(upper, dt);
+
+        moving = step(bottom, dt) || moving;
+        time = now;
+        paint();
+        motion = moving ? requestAnimationFrame(animate) : 0;
+    }
+
+    function jump(i: number) {
+        let behavior: ScrollBehavior = reduced() ? 'auto' : 'smooth',
+            top = Math.max(0, offsets[i] - JUMP_OFFSET);
+
+        (scroller ?? window).scrollTo({ behavior, top });
+    }
+
+    // Measures section lengths and lays the bands out in proportion, so the spine is a scale drawing of the article.
+    function measure() {
+        let m = metrics(),
+            minBand = inline ? MIN_BAND_LABELLED : MIN_BAND,
+            free = height - GAP * (items.length - 1) - minBand * items.length,
+            tops = items.map((item) => {
+                let el = document.getElementById(item.id);
+
+                return el ? m.offsetOf(el) : 0;
+            }),
+            lengths = tops.map((top, i) => Math.max(1, (tops[i + 1] ?? m.height) - top)),
+            total = lengths.reduce((a, b) => a + b, 0),
+            y = 0;
+
+        end = m.height;
+        offsets = tops;
+        bands = lengths.map((length) => {
+            let band = { height: minBand + (free * length) / total, top: y };
+
+            y += band.height + GAP;
+
+            return band;
+        });
+
+        for (let i = 0, n = rows.length; i < n; i++) {
+            rows[i].style.height = `${bands[i].height}px`;
+            rows[i].style.top = `${bands[i].top}px`;
+        }
+
+        notch?.classList.add('--active');
+        move(true);
+        update();
+    }
+
+    function metrics() {
+        if (!scroller) {
+            return {
+                height: document.documentElement.scrollHeight,
+                offsetOf: (el: HTMLElement) => el.getBoundingClientRect().top + scrollY,
+                scrollTop: scrollY,
+                viewport: innerHeight
+            };
+        }
+
+        let box = scroller,
+            top = box.getBoundingClientRect().top;
+
+        return {
+            height: box.scrollHeight,
+            offsetOf: (el: HTMLElement) => el.getBoundingClientRect().top - top + box.scrollTop,
+            scrollTop: box.scrollTop,
+            viewport: box.clientHeight
+        };
+    }
+
+    // Moves the marker; the edge in the direction of travel leads.
+    function move(snap = false) {
+        let band = bands[state.active];
+
+        if (!band) {
+            return;
+        }
+
+        let from = upper.target,
+            to = band.top - MARK_PAD;
+
+        upper.target = to;
+        bottom.target = band.top + band.height + MARK_PAD;
+
+        if (!placed || snap || reduced()) {
+            placed = true;
+            bottom.value = bottom.target;
+            bottom.velocity = 0;
+            upper.value = upper.target;
+            upper.velocity = 0;
+            paint();
+            return;
+        }
+
+        let down = to >= from;
+
+        bottom.omega = down ? LEAD : TRAIL;
+        upper.omega = down ? TRAIL : LEAD;
+
+        if (!motion) {
+            time = 0;
+            motion = requestAnimationFrame(animate);
+        }
+    }
+
+    function onscroll() {
+        if (!frame) {
+            frame = requestAnimationFrame(update);
+        }
+    }
+
+    function paint() {
+        if (!marker) {
+            return;
+        }
+
+        marker.style.height = `${Math.max(0, bottom.value - upper.value)}px`;
+        marker.style.top = `${upper.value}px`;
+    }
+
+    // Follows the scroll: the reading dot and the read part of each band are written straight to the DOM every frame;
+    // reactive state only hears about it when the current section changes.
+    function update() {
+        frame = 0;
+
+        if (!bands.length) {
+            return;
+        }
+
+        let m = metrics(),
+            atEnd = m.scrollTop >= m.height - m.viewport - END_SLACK,
+            i = 0,
+            line = m.scrollTop + m.viewport * READ_LINE;
+
+        while (i < offsets.length - 1 && offsets[i + 1] <= line) {
+            i++;
+        }
+
+        if (atEnd) {
+            i = offsets.length - 1;
+        }
+
+        let band = bands[i],
+            finish = offsets[i + 1] ?? end,
+            start = offsets[i],
+            within = atEnd ? 1 : Math.min(1, Math.max(0, (line - start) / (finish - start)));
+
+        if (band && notch) {
+            notch.style.transform = `translateY(${band.top + within * band.height}px)`;
+        }
+
+        for (let k = 0, n = fills.length; k < n; k++) {
+            fills[k].style.transform = `scaleY(${k < i ? 1 : k === i ? within : 0})`;
+        }
+
+        if (i !== state.active) {
+            state.active = i;
+            move();
+        }
+    }
+
+    return html`
+        <nav
+            aria-label='${label}'
+            class='scroll-spine'
+            style='${`height: ${height}px;`}'
+            ${this?.attributes}
+            ${attributes}
+            ${{
+                onconnect: (el: HTMLElement) => {
+                    let source = typeof target === 'function' ? target() : target;
+
+                    fills = [...el.querySelectorAll<HTMLElement>('.scroll-spine-fill')];
+                    marker = el.querySelector<HTMLElement>('.scroll-spine-marker') ?? undefined;
+                    nav = el;
+                    notch = el.querySelector<HTMLElement>('.scroll-spine-notch') ?? undefined;
+                    rows = [...el.querySelectorAll<HTMLElement>('.scroll-spine-item')];
+                    scroller = source ?? undefined;
+
+                    // Wide enough for words: every band carries its heading. Narrow: bands only, and the heading shows on hover or focus.
+                    let width = new ResizeObserver(([entry]) => {
+                            let next = entry.contentRect.width >= INLINE_MIN;
+
+                            nav?.classList.toggle('--inline', next);
+
+                            if (next !== inline || !bands.length) {
+                                inline = next;
+                                measure();
+                            }
+                        }),
+                        content = new ResizeObserver(() => measure());
+
+                    width.observe(el);
+                    content.observe(scroller ? (scroller.firstElementChild ?? scroller) : document.body);
+                    (scroller ?? window).addEventListener('scroll', onscroll, { passive: true });
+                    cleanup = () => {
+                        content.disconnect();
+                        width.disconnect();
+                        (scroller ?? window).removeEventListener('scroll', onscroll);
+                    };
+                },
+                ondisconnect: () => {
+                    cancelAnimationFrame(frame);
+                    cancelAnimationFrame(motion);
+                    cleanup?.();
+                }
+            }}
+        >
+            <div aria-hidden='true' class='scroll-spine-marker'></div>
+            <ol class='scroll-spine-list'>
+                ${items.map((item, i) => html`
+                    <li class='scroll-spine-item'>
+                        <span aria-hidden='true' class='scroll-spine-band'>
+                            <span class='scroll-spine-fill'></span>
+                        </span>
+                        <button
+                            aria-current='${() => state.active === i && 'location'}'
+                            class='scroll-spine-button ${() => state.active === i && '--active'}'
+                            onclick='${() => jump(i)}'
+                            type='button'
+                            ${this?.attributes?.[SCROLL_SPINE_BUTTON]}
+                            ${attributes[SCROLL_SPINE_BUTTON]}
+                        >
+                            <span class='scroll-spine-label'>${item.label}</span>
+                        </button>
+                        <span aria-hidden='true' class='scroll-spine-preview'>${item.label}</span>
+                    </li>
+                `)}
+            </ol>
+            <div aria-hidden='true' class='scroll-spine-notch'></div>
+        </nav>
+    `;
+}
+
+
+export default Object.assign(template, { button: SCROLL_SPINE_BUTTON } as const);
+export type { Item, State };

package/src/components/scroll-spine/scss/index.scss

@@ -0,0 +1,209 @@
+@use 'variables';
+
+.scroll-spine {
+    flex: none;
+    position: relative;
+    user-select: none;
+    width: var(--width);
+
+    &-band {
+        background: var(--band-color);
+        border-radius: 999px;
+        inset-block: 0;
+        left: 50%;
+        overflow: hidden;
+        position: absolute;
+        translate: -50% 0;
+        width: var(--band-width);
+    }
+
+    &-button {
+        background: none;
+        border: 0;
+        border-radius: var(--border-radius-300);
+        color: inherit;
+        cursor: pointer;
+        font: inherit;
+        inset: 0;
+        outline: none;
+        padding: 0;
+        position: absolute;
+        text-align: left;
+        touch-action: manipulation;
+        transition: scale var(--transition-duration) var(--transition-timing-function);
+
+        &:active {
+            scale: var(--pressed-scale);
+        }
+
+        &:focus-visible {
+            outline: var(--border-width-500) solid var(--focus-color);
+        }
+    }
+
+    // Written by the scroll handler; starts empty.
+    &-fill {
+        background: var(--fill-color);
+        border-radius: 999px;
+        inset: 0;
+        position: absolute;
+        transform: scaleY(0);
+        transform-origin: top;
+    }
+
+    &-item {
+        left: 0;
+        position: absolute;
+        right: 0;
+    }
+
+    &-label {
+        border: 0;
+        clip-path: inset(50%);
+        height: 1px;
+        overflow: hidden;
+        position: absolute;
+        white-space: nowrap;
+        width: 1px;
+    }
+
+    &-list {
+        inset: 0;
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        position: absolute;
+    }
+
+    // The current section, as a soft block that stretches from band to band like a caterpillar.
+    &-marker {
+        background: var(--marker-color);
+        border-radius: var(--marker-radius);
+        left: 50%;
+        position: absolute;
+        translate: -50% 0;
+        width: 20px;
+    }
+
+    // Exactly where the reading line is, riding the bands.
+    &-notch {
+        background: var(--notch-color);
+        border-radius: 999px;
+        box-shadow: 0 0 0 3px var(--notch-ring-color);
+        height: var(--notch-size);
+        left: 50%;
+        margin: calc(var(--notch-size) / -2) 0 0 calc(var(--notch-size) / -2);
+        opacity: 0;
+        pointer-events: none;
+        position: absolute;
+        top: 0;
+        width: var(--notch-size);
+
+        &.--active {
+            opacity: 1;
+        }
+    }
+
+    // Hung off the left of the band; only used when the spine is too narrow for inline headings.
+    &-preview {
+        background: var(--preview-background);
+        border-radius: 999px;
+        color: var(--preview-color);
+        filter: blur(2px);
+        font-size: var(--font-size);
+        font-weight: var(--font-weight-500);
+        margin-right: 4px;
+        opacity: 0;
+        padding: 6px 12px;
+        pointer-events: none;
+        position: absolute;
+        right: 100%;
+        top: 0;
+        transition:
+            filter 0.1s var(--preview-timing-function),
+            opacity 0.1s var(--preview-timing-function),
+            translate 0.1s var(--preview-timing-function);
+        translate: 6px 0;
+        white-space: nowrap;
+        z-index: 10;
+    }
+
+    &-button:focus-visible + &-preview {
+        filter: none;
+        opacity: 1;
+        transition-duration: 0.2s;
+        translate: 0 0;
+    }
+
+    @media (hover: hover) {
+        &-button:hover + &-preview {
+            filter: none;
+            opacity: 1;
+            transition-duration: 0.2s;
+            translate: 0 0;
+        }
+    }
+
+    // Wide enough for words: every band carries its heading.
+    &.--inline {
+        .scroll-spine-band {
+            left: 0;
+            translate: none;
+        }
+
+        .scroll-spine-button {
+            left: -8px;
+            padding-left: 20px;
+        }
+
+        .scroll-spine-label {
+            clip-path: none;
+            color: var(--muted-color);
+            display: block;
+            font-size: var(--font-size);
+            height: auto;
+            line-height: 16px;
+            overflow: hidden;
+            position: static;
+            text-overflow: ellipsis;
+            transition: color var(--transition-duration) var(--transition-timing-function);
+            width: auto;
+        }
+
+        .scroll-spine-button.--active .scroll-spine-label {
+            color: var(--color);
+            font-weight: var(--font-weight-500);
+        }
+
+        .scroll-spine-marker {
+            left: -8px;
+            right: 0;
+            translate: none;
+            width: auto;
+        }
+
+        .scroll-spine-notch {
+            left: calc(var(--band-width) / 2);
+        }
+
+        .scroll-spine-preview {
+            display: none;
+        }
+
+        @media (hover: hover) {
+            .scroll-spine-button:hover .scroll-spine-label {
+                color: var(--color);
+            }
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        &-button {
+            transition: none;
+        }
+
+        &-preview {
+            translate: 0 0;
+        }
+    }
+}

package/src/components/scroll-spine/scss/variables.scss

@@ -0,0 +1,22 @@
+.scroll-spine {
+    --band-color: oklch(from var(--color) l c h / 0.12);
+    --band-width: 3px;
+    --color: var(--color-text-500);
+    --fill-color: var(--color);
+    --focus-color: var(--color);
+    --font-size: 13px;
+    --marker-color: oklch(from var(--color) l c h / 0.06);
+    --marker-radius: var(--border-radius-400);
+    --muted-color: var(--color-text-300);
+    --notch-color: var(--color);
+    // Matches whatever the spine sits on, so the reading dot looks cut out of the band.
+    --notch-ring-color: var(--color-grey-400);
+    --notch-size: 9px;
+    --pressed-scale: 0.96;
+    --preview-background: var(--color);
+    --preview-color: var(--color-white-300);
+    --preview-timing-function: cubic-bezier(0.23, 1, 0.32, 1);
+    --transition-duration: 0.15s;
+    --transition-timing-function: ease-out;
+    --width: 180px;
+}