@getaster/elements 0.0.0-stage → 0.1.0-preview.0

package/dist/base/drag.js

@@ -0,0 +1,139 @@
+/**
+ * Pointer drags that work on touch screens too.
+ *
+ * A mouse lifts a drag once it moves `distance` pixels. A touch or pen
+ * lifts it by holding still for `HOLD_MS`; moving more than `HOLD_SLOP`
+ * first is a scroll, left to the browser, and the press is forgotten.
+ * `touch-action` is fixed when a touch starts, so it stays at the default
+ * (scrolling works everywhere) and a lifted drag holds the page still by
+ * cancelling its `touchmove`s instead. While a drag is lifted, its
+ * scroller follows it near the top and bottom edges.
+ *
+ * Moves are listened for on the document by pointer id, so they keep
+ * arriving when the row under the finger is re-rendered away; only a mouse
+ * takes pointer capture.
+ */
+/** How long a touch or pen holds still to lift a drag. */
+export const HOLD_MS = 400;
+/** How far a held touch or pen may drift and still be holding still. */
+export const HOLD_SLOP = 8;
+/** The auto-scroll band at a scroller's top and bottom, and the most it scrolls per frame. */
+const EDGE = 48;
+const SPEED = 16;
+/** Whether a press lifts by holding still (touch, pen) rather than by moving (mouse). */
+export function holds(e) {
+    return e.pointerType === "touch" || e.pointerType === "pen";
+}
+/** Follows the press `down` until it lifts a drag and ends, or turns out to be a tap or a scroll. */
+export function pressDrag(down, options, handlers) {
+    const id = down.pointerId;
+    const hold = holds(down);
+    const from = { x: down.clientX, y: down.clientY };
+    let at = from;
+    let lifted = false;
+    let frame = 0;
+    const scroller = options.scroller?.() ?? scrollerOf(options.capture);
+    const lift = () => {
+        lifted = true;
+        if (!hold)
+            options.capture.setPointerCapture(id);
+        handlers.lift();
+        handlers.move(at.x, at.y);
+        follow();
+    };
+    const timer = hold ? setTimeout(lift, HOLD_MS) : undefined;
+    /** Scrolls while the pointer is in an edge band, re-reporting its place as the content moves. */
+    const follow = () => {
+        if (frame || !scroller)
+            return;
+        const step = () => {
+            frame = 0;
+            const v = lifted ? speed(scroller, at.y, options.inset?.() ?? 0) : 0;
+            if (!v)
+                return;
+            const before = scroller.scrollTop;
+            scroller.scrollTop += v;
+            if (scroller.scrollTop === before)
+                return;
+            handlers.move(at.x, at.y);
+            frame = requestAnimationFrame(step);
+        };
+        frame = requestAnimationFrame(step);
+    };
+    const move = (e) => {
+        if (e.pointerId !== id)
+            return;
+        at = { x: e.clientX, y: e.clientY };
+        if (!lifted) {
+            const dx = at.x - from.x;
+            const dy = at.y - from.y;
+            if (hold) {
+                if (Math.hypot(dx, dy) > HOLD_SLOP)
+                    stop(false);
+            }
+            else if ((options.vertical ? Math.abs(dy) : Math.hypot(dx, dy)) >= options.distance)
+                lift();
+            return;
+        }
+        handlers.move(at.x, at.y);
+        follow();
+    };
+    const up = (e) => e.pointerId === id && stop(true);
+    const cancel = (e) => e.pointerId === id && stop(false);
+    const still = (e) => lifted && e.preventDefault();
+    // A held press would otherwise open the context menu or start selecting text.
+    const quiet = (e) => e.preventDefault();
+    const escape = (e) => {
+        if (e.key !== "Escape")
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        stop(false);
+    };
+    const listeners = [
+        [document, "pointermove", move],
+        [document, "pointerup", up],
+        [document, "pointercancel", cancel],
+    ];
+    if (hold) {
+        listeners.push([document, "touchmove", still, { passive: false }], [window, "contextmenu", quiet, { capture: true }], [document, "selectstart", quiet, { capture: true }]);
+    }
+    if (options.escape)
+        listeners.push([document, "keydown", escape, { capture: true }]);
+    for (const [target, type, fn, o] of listeners)
+        target.addEventListener(type, fn, o);
+    function stop(drop) {
+        clearTimeout(timer);
+        cancelAnimationFrame(frame);
+        frame = 0;
+        for (const [target, type, fn, o] of listeners)
+            target.removeEventListener(type, fn, o);
+        if (options.capture.hasPointerCapture(id))
+            options.capture.releasePointerCapture(id);
+        if (lifted)
+            handlers.end(drop);
+        lifted = false;
+    }
+}
+/** Pixels per frame to scroll `el` with the pointer at `y`: negative up, 0 outside the edge bands. */
+function speed(el, y, inset) {
+    const page = el === document.scrollingElement;
+    const top = (page ? 0 : el.getBoundingClientRect().top) + inset;
+    const bottom = page ? innerHeight : el.getBoundingClientRect().bottom;
+    const band = Math.min(EDGE, (bottom - top) / 4);
+    if (band <= 0 || y < top)
+        return 0;
+    if (y < top + band)
+        return -Math.ceil((SPEED * (top + band - y)) / band);
+    if (y > bottom - band)
+        return Math.ceil((SPEED * Math.min(band, y - (bottom - band))) / band);
+    return 0;
+}
+function scrollerOf(el) {
+    for (let n = el.parentElement; n; n = n.parentElement) {
+        const overflow = getComputedStyle(n).overflowY;
+        if ((overflow === "auto" || overflow === "scroll") && n.scrollHeight > n.clientHeight)
+            return n;
+    }
+    return document.scrollingElement ?? document.documentElement;
+}

package/dist/base/element.d.ts

@@ -0,0 +1,51 @@
+import { type ReadonlySignal, type Signal } from "@preact/signals-core";
+import type { PageScope } from "@getaster/data";
+import { nothing, type TemplateResult } from "lit-html";
+export type View = TemplateResult | typeof nothing;
+/** A plain value or a signal of one; elements read either. */
+export type Bindable<T> = T | ReadonlySignal<T>;
+export declare function read<T>(value: Bindable<T>): T;
+/**
+ * The base of every Aster element: light DOM, rendered with lit-html from
+ * `render()`. Any signal `render()` reads schedules a re-render.
+ *
+ * Only signals read while `render()` runs are tracked. Callbacks lit calls
+ * later, during the commit (such as `repeat`'s template), are not, so keyed
+ * lists use `each`, which builds every item's view first.
+ *
+ * Invariant: the template is computed synchronously when its signals change,
+ * and committed to the DOM once per microtask, so a batch of changes costs
+ * one commit. The first render on connect commits immediately.
+ *
+ * An element defined after it was created (a lazily loaded page) may have
+ * had properties set while it was a plain element; on first connect they
+ * are re-set through the class's setters.
+ */
+export declare abstract class AsterElement extends HTMLElement {
+    #private;
+    protected abstract render(): View;
+    /** Runs after each commit; geometry reads belong here. */
+    protected updated(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** A signal-backed property: `#x = this.prop(1)` and get/set through it. */
+    protected prop<T>(initial: T): Signal<T>;
+    /** Disposed when the element disconnects. */
+    protected onDisconnect(cleanup: () => void): void;
+    /** Listens on `target` until the element disconnects. */
+    protected listen<K extends keyof WindowEventMap>(target: EventTarget, type: K, handler: (event: WindowEventMap[K]) => void, options?: AddEventListenerOptions): void;
+    protected emit<T>(type: string, detail?: T): boolean;
+}
+export declare function define(name: string, ctor: CustomElementConstructor): void;
+/** Makes `scope` the page scope for `el` and everything inside it. */
+export declare function provideScope(el: Element, scope: PageScope): void;
+/** The page scope `el` is in: the nearest one provided on it or an ancestor. */
+export declare function scopeOf(el: Element): PageScope | undefined;
+/** A document-unique id for ARIA references. */
+export declare function uid(prefix: string): string;
+/**
+ * A keyed list for templates. Each item's view is built now, inside the
+ * caller's `render()`, so the signals it reads are tracked; lit then only
+ * moves and updates the finished views.
+ */
+export declare function each<T>(items: readonly T[], key: (item: T) => string, view: (item: T) => View): unknown;

package/dist/base/element.js

@@ -0,0 +1,133 @@
+import { computed, effect, signal, untracked } from "@preact/signals-core";
+import { nothing, render } from "lit-html";
+import { repeat } from "lit-html/directives/repeat.js";
+export function read(value) {
+    return isSignal(value) ? value.value : value;
+}
+function isSignal(value) {
+    return typeof value === "object" && value !== null && "peek" in value && "subscribe" in value;
+}
+/**
+ * The base of every Aster element: light DOM, rendered with lit-html from
+ * `render()`. Any signal `render()` reads schedules a re-render.
+ *
+ * Only signals read while `render()` runs are tracked. Callbacks lit calls
+ * later, during the commit (such as `repeat`'s template), are not, so keyed
+ * lists use `each`, which builds every item's view first.
+ *
+ * Invariant: the template is computed synchronously when its signals change,
+ * and committed to the DOM once per microtask, so a batch of changes costs
+ * one commit. The first render on connect commits immediately.
+ *
+ * An element defined after it was created (a lazily loaded page) may have
+ * had properties set while it was a plain element; on first connect they
+ * are re-set through the class's setters.
+ */
+export class AsterElement extends HTMLElement {
+    #dispose;
+    #queued = false;
+    #view;
+    #cleanups = [];
+    /** Runs after each commit; geometry reads belong here. */
+    updated() { }
+    connectedCallback() {
+        this.#upgradeProperties();
+        const view = computed(() => this.render());
+        this.#view = view;
+        let first = true;
+        this.#dispose = effect(() => {
+            view.value;
+            if (first) {
+                first = false;
+                // Children connecting during the commit must not subscribe this effect.
+                untracked(() => this.#commit());
+            }
+            else {
+                this.#schedule();
+            }
+        });
+    }
+    disconnectedCallback() {
+        this.#dispose?.();
+        this.#dispose = undefined;
+        for (const cleanup of this.#cleanups.splice(0))
+            cleanup();
+    }
+    /** A signal-backed property: `#x = this.prop(1)` and get/set through it. */
+    prop(initial) {
+        return signal(initial);
+    }
+    /** Disposed when the element disconnects. */
+    onDisconnect(cleanup) {
+        this.#cleanups.push(cleanup);
+    }
+    /** Listens on `target` until the element disconnects. */
+    listen(target, type, handler, options) {
+        target.addEventListener(type, handler, options);
+        this.onDisconnect(() => target.removeEventListener(type, handler, options));
+    }
+    emit(type, detail) {
+        return this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, cancelable: true }));
+    }
+    #upgradeProperties() {
+        for (const name of Object.keys(this)) {
+            let proto = Object.getPrototypeOf(this);
+            while (proto && proto !== HTMLElement.prototype && !Object.getOwnPropertyDescriptor(proto, name)?.set) {
+                proto = Object.getPrototypeOf(proto);
+            }
+            if (!proto || proto === HTMLElement.prototype)
+                continue;
+            const value = this[name];
+            delete this[name];
+            this[name] = value;
+        }
+    }
+    #schedule() {
+        if (this.#queued)
+            return;
+        this.#queued = true;
+        queueMicrotask(() => {
+            this.#queued = false;
+            if (this.#dispose)
+                this.#commit();
+        });
+    }
+    #commit() {
+        if (!this.#view)
+            return;
+        render(this.#view.peek(), this, { host: this });
+        this.updated();
+    }
+}
+export function define(name, ctor) {
+    if (!customElements.get(name))
+        customElements.define(name, ctor);
+}
+const SCOPE = Symbol("aster-scope");
+/** Makes `scope` the page scope for `el` and everything inside it. */
+export function provideScope(el, scope) {
+    el[SCOPE] = scope;
+}
+/** The page scope `el` is in: the nearest one provided on it or an ancestor. */
+export function scopeOf(el) {
+    for (let n = el; n; n = n.parentNode ?? (n instanceof ShadowRoot ? n.host : null)) {
+        const scope = n[SCOPE];
+        if (scope)
+            return scope;
+    }
+    return undefined;
+}
+let ids = 0;
+/** A document-unique id for ARIA references. */
+export function uid(prefix) {
+    return `${prefix}-${(ids++).toString(36)}`;
+}
+/**
+ * A keyed list for templates. Each item's view is built now, inside the
+ * caller's `render()`, so the signals it reads are tracked; lit then only
+ * moves and updates the finished views.
+ */
+export function each(items, key, view) {
+    const built = items.map((item) => ({ key: key(item), view: view(item) }));
+    return repeat(built, (b) => b.key, (b) => b.view);
+}

package/dist/breadcrumbs/breadcrumbs.d.ts

@@ -0,0 +1,23 @@
+export interface BreadcrumbItem {
+    readonly id: string;
+    readonly label: string;
+    readonly href?: string;
+    readonly activate?: () => void;
+}
+export declare const Breadcrumbs: import("../index.ts").DeclaredElement<{
+    readonly items: {
+        readonly type: import("../index.ts").CompositeType<readonly BreadcrumbItem[]>;
+        readonly initial: () => readonly BreadcrumbItem[];
+        readonly description: string;
+    };
+    readonly label: {
+        readonly type: import("../index.ts").CompositeType<string>;
+        readonly initial: () => string;
+        readonly description: string;
+    };
+    readonly maxVisible: {
+        readonly type: import("../index.ts").CompositeType<number>;
+        readonly initial: () => number;
+        readonly description: string;
+    };
+}>;

package/dist/breadcrumbs/breadcrumbs.js

@@ -0,0 +1,51 @@
+import { html, nothing } from "lit-html";
+import { each } from "../base/element.js";
+import { defineElement, elementProperty } from "../composition/element.js";
+import { compositeTypes as t } from "../composition/contracts.js";
+import { sidebarHref } from "../sidebar/sidebar.js";
+import { Menu } from "../menu/menu.js";
+const items = t.custom("breadcrumbs with unique IDs, labels and safe links", (v) => {
+    if (!Array.isArray(v))
+        return false;
+    const ids = new Set();
+    return v.every(i => {
+        if (!i || typeof i.id !== "string" || !i.id || ids.has(i.id) || typeof i.label !== "string" || !i.label.trim())
+            return false;
+        ids.add(i.id);
+        return (i.href === undefined || typeof i.href === "string" && sidebarHref(i.href)) && (i.activate === undefined || typeof i.activate === "function") && !(i.href && i.activate);
+    });
+}, { type: "array", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string" }, label: { type: "string" }, href: { type: "string" }, activate: { asterType: "function" } }, additionalProperties: false } });
+export const Breadcrumbs = defineElement({
+    tag: "aster-breadcrumbs",
+    properties: {
+        items: elementProperty(items, () => [], "Ancestor locations"),
+        label: elementProperty(t.string, () => "Breadcrumb", "Navigation name"),
+        maxVisible: elementProperty(t.custom("at least three visible items", (v) => Number.isSafeInteger(v) && v >= 3, { type: "integer", minimum: 3 }), () => 4, "Visible item budget including overflow"),
+    },
+    render: (p, element) => {
+        const activate = (item, e) => {
+            if (e && (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0))
+                return;
+            if (!element.dispatchEvent(new CustomEvent("navigate", { detail: item.id, bubbles: true, cancelable: true }))) {
+                e?.preventDefault();
+                return;
+            }
+            item.activate?.();
+        };
+        const overflow = p.items.length > p.maxVisible;
+        const omitted = overflow ? p.items.slice(1, p.items.length - (p.maxVisible - 2)) : [];
+        const shown = overflow ? [p.items[0], ...p.items.slice(-(p.maxVisible - 2))] : p.items;
+        return html `<nav class="aster-breadcrumbs" aria-label=${p.label}><ol>
+      ${each(shown, i => i.id, item => html `<li>
+        ${item === p.items.at(-1) ? html `<span aria-current="page" title=${item.label}>${item.label}</span>`
+            : item.href ? html `<a href=${item.href} title=${item.label} @click=${(e) => activate(item, e)}>${item.label}</a>`
+                : html `<button type="button" title=${item.label} @click=${() => activate(item)}>${item.label}</button>`}
+        ${overflow && item === p.items[0] ? html `<span class="aster-breadcrumb-overflow"><button type="button" aria-label="Show ancestors" aria-haspopup="menu" @click=${(e) => {
+            const menu = element.querySelector("aster-menu");
+            const choices = omitted.map(i => i.href ? { kind: "link", label: i.label, href: i.href, activate: event => activate(i, event) } : { label: i.label, run: () => activate(i) });
+            menu.openFrom(e.currentTarget, choices, "Ancestors");
+        }}>…</button></span>` : nothing}
+      </li>`)}
+    </ol></nav><aster-menu></aster-menu>`;
+    },
+});

package/dist/button/button.d.ts

@@ -0,0 +1,37 @@
+import { AsterElement, type Bindable, type View } from "../base/element.ts";
+/**
+ * A button with every state: rest, hover, pressed, focus, busy and
+ * disabled. Busy and confirmation swap the label in place; every label is
+ * stacked in one grid cell, so the width never changes. While busy, clicks
+ * are ignored and a submit doesn't fire.
+ *
+ * Prefer `reason` to disabling: the button stays focusable, says why in its
+ * title, and its click is swallowed.
+ */
+export declare class Button extends AsterElement {
+    #private;
+    get label(): string;
+    set label(v: string);
+    /** Shown while busy, such as "Inviting…". */
+    get busyLabel(): string | undefined;
+    set busyLabel(v: string | undefined);
+    /** Shown briefly by `confirm()`, such as "Copied". */
+    get confirmLabel(): string | undefined;
+    set confirmLabel(v: string | undefined);
+    get busy(): Bindable<boolean>;
+    set busy(v: Bindable<boolean>);
+    get variant(): "secondary" | "primary";
+    set variant(v: "secondary" | "primary");
+    get type(): "button" | "submit";
+    set type(v: "button" | "submit");
+    get icon(): View;
+    set icon(v: View);
+    /** Why the button can't act now. Setting it disables the button without removing it from the tab order. */
+    get reason(): string | undefined;
+    set reason(v: string | undefined);
+    connectedCallback(): void;
+    /** Shows the confirm label in place for a moment. */
+    confirm(ms?: number): void;
+    focus(options?: FocusOptions): void;
+    protected render(): View;
+}

package/dist/button/button.js

@@ -0,0 +1,108 @@
+import { html, nothing } from "lit-html";
+import { AsterElement, define, read } from "../base/element.js";
+/**
+ * A button with every state: rest, hover, pressed, focus, busy and
+ * disabled. Busy and confirmation swap the label in place; every label is
+ * stacked in one grid cell, so the width never changes. While busy, clicks
+ * are ignored and a submit doesn't fire.
+ *
+ * Prefer `reason` to disabling: the button stays focusable, says why in its
+ * title, and its click is swallowed.
+ */
+export class Button extends AsterElement {
+    #label = this.prop("");
+    #busyLabel = this.prop(undefined);
+    #confirmLabel = this.prop(undefined);
+    #busy = this.prop(false);
+    #confirming = this.prop(false);
+    #variant = this.prop("secondary");
+    #type = this.prop("button");
+    #icon = this.prop(nothing);
+    #reason = this.prop(undefined);
+    #confirmTimer;
+    get label() {
+        return this.#label.value;
+    }
+    set label(v) {
+        this.#label.value = v;
+    }
+    /** Shown while busy, such as "Inviting…". */
+    get busyLabel() {
+        return this.#busyLabel.value;
+    }
+    set busyLabel(v) {
+        this.#busyLabel.value = v;
+    }
+    /** Shown briefly by `confirm()`, such as "Copied". */
+    get confirmLabel() {
+        return this.#confirmLabel.value;
+    }
+    set confirmLabel(v) {
+        this.#confirmLabel.value = v;
+    }
+    get busy() {
+        return this.#busy.value;
+    }
+    set busy(v) {
+        this.#busy.value = v;
+    }
+    get variant() {
+        return this.#variant.value;
+    }
+    set variant(v) {
+        this.#variant.value = v;
+    }
+    get type() {
+        return this.#type.value;
+    }
+    set type(v) {
+        this.#type.value = v;
+    }
+    get icon() {
+        return this.#icon.value;
+    }
+    set icon(v) {
+        this.#icon.value = v;
+    }
+    /** Why the button can't act now. Setting it disables the button without removing it from the tab order. */
+    get reason() {
+        return this.#reason.value;
+    }
+    set reason(v) {
+        this.#reason.value = v;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.listen(this, "click", (e) => this.#guard(e), { capture: true });
+    }
+    /** Shows the confirm label in place for a moment. */
+    confirm(ms = 1600) {
+        clearTimeout(this.#confirmTimer);
+        this.#confirming.value = true;
+        this.#confirmTimer = setTimeout(() => (this.#confirming.value = false), ms);
+    }
+    focus(options) {
+        this.querySelector("button")?.focus(options);
+    }
+    render() {
+        const busy = read(this.#busy.value);
+        const confirming = this.#confirming.value;
+        const labels = [this.#label.value, this.#busyLabel.value, this.#confirmLabel.value];
+        const showing = busy && labels[1] ? 1 : confirming && labels[2] ? 2 : 0;
+        const reason = this.#reason.value;
+        return html `<button class="aster-button" type=${this.#type.value} data-variant=${this.#variant.value}
+      aria-busy=${busy ? "true" : "false"} aria-disabled=${reason ? "true" : nothing} title=${reason ?? nothing}>
+      ${this.#icon.value}
+      <span class="aster-label-swap">
+        ${labels.map((l, i) => (l === undefined ? nothing : html `<span ?data-off=${i !== showing}>${l}</span>`))}
+      </span>
+    </button>`;
+    }
+    #guard(e) {
+        if (read(this.#busy.peek()) || this.#reason.peek()) {
+            e.preventDefault();
+            e.stopImmediatePropagation();
+        }
+    }
+}
+define("aster-button", Button);

package/dist/caret/caret-group.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A group with one caret: a bar that slides to the selected or current
+ * descendant. `axis="x"` puts it under the item (tabs); the default `y` puts
+ * it at the item's left edge (nav, lists).
+ *
+ * The caret's position is read from the item's offsets after layout and
+ * written as CSS variables; CSS draws and animates it. The group is the
+ * caret's containing block, so it must stay `position: relative`.
+ */
+export declare class CaretGroup extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}

package/dist/caret/caret-group.js

@@ -0,0 +1,71 @@
+import { define } from "../base/element.js";
+const SELECTED = '[aria-current="true"], [aria-current="page"], [aria-selected="true"]';
+/**
+ * A group with one caret: a bar that slides to the selected or current
+ * descendant. `axis="x"` puts it under the item (tabs); the default `y` puts
+ * it at the item's left edge (nav, lists).
+ *
+ * The caret's position is read from the item's offsets after layout and
+ * written as CSS variables; CSS draws and animates it. The group is the
+ * caret's containing block, so it must stay `position: relative`.
+ */
+export class CaretGroup extends HTMLElement {
+    #caret = document.createElement("span");
+    #mutations;
+    #resize;
+    #frame = 0;
+    #placed = false;
+    connectedCallback() {
+        this.#caret.className = "aster-caret";
+        this.#caret.setAttribute("aria-hidden", "true");
+        if (this.#caret.parentNode !== this)
+            this.prepend(this.#caret);
+        this.#mutations = new MutationObserver(() => this.#queue());
+        this.#mutations.observe(this, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            attributeFilter: ["aria-current", "aria-selected", "hidden"],
+        });
+        this.#resize = new ResizeObserver(() => this.#queue(false));
+        this.#resize.observe(this);
+        void document.fonts?.ready.then(() => this.#queue(false));
+        this.#queue(false);
+    }
+    disconnectedCallback() {
+        this.#mutations?.disconnect();
+        this.#resize?.disconnect();
+        cancelAnimationFrame(this.#frame);
+        this.#placed = false;
+    }
+    #queue(animate = true) {
+        cancelAnimationFrame(this.#frame);
+        this.#frame = requestAnimationFrame(() => this.#place(animate && this.#placed));
+    }
+    #place(animate) {
+        const item = [...this.querySelectorAll(SELECTED)].find((el) => el.closest("aster-caret-group") === this && el.offsetParent !== null);
+        const style = this.#caret.style;
+        if (!item) {
+            style.setProperty("--caret-opacity", "0");
+            return;
+        }
+        this.#caret.toggleAttribute("data-instant", !animate);
+        const { pos, size } = this.#offsets(item);
+        style.setProperty("--caret-opacity", "1");
+        style.setProperty("--caret-pos", `${pos}px`);
+        style.setProperty("--caret-size", `${size}px`);
+        this.#placed = true;
+    }
+    /** The item's position within this group, through any positioned ancestors in between. */
+    #offsets(item) {
+        const x = this.getAttribute("axis") === "x";
+        let pos = 0;
+        for (let el = item; el && el !== this; el = el.offsetParent) {
+            pos += x ? el.offsetLeft : el.offsetTop;
+            if (!this.contains(el.offsetParent))
+                break;
+        }
+        return { pos, size: x ? item.offsetWidth : item.offsetHeight };
+    }
+}
+define("aster-caret-group", CaretGroup);

package/dist/carousel/carousel.d.ts

@@ -0,0 +1,28 @@
+import { AsterElement, type View } from "../base/element.ts";
+export interface Slide {
+    readonly id?: string;
+    /** Names the slide, after its position ("2 of 5: Brand refresh"). */
+    readonly label: string;
+    readonly view: View;
+}
+/**
+ * A row of cards that snaps one at a time, the next one peeking in (the APG
+ * carousel pattern, without rotation): Previous and Next, and "n of m" said
+ * as it changes. Scrolling, swiping and the buttons all move it; the current
+ * slide is whichever is most in view. When every slide fits, there are no
+ * buttons.
+ */
+export declare class Carousel extends AsterElement {
+    #private;
+    get slides(): readonly Slide[];
+    set slides(v: readonly Slide[]);
+    get label(): string;
+    set label(v: string);
+    /** The slide most in view. */
+    get index(): number;
+    /** Brings a slide into view (smoothly unless motion is reduced). */
+    show(index: number): void;
+    disconnectedCallback(): void;
+    protected render(): View;
+    protected updated(): void;
+}