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

package/dist/carousel/carousel.js

@@ -0,0 +1,134 @@
+import { html, nothing } from "lit-html";
+import { AsterElement, define, each, uid } from "../base/element.js";
+/**
+ * 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 class Carousel extends AsterElement {
+    #slides = this.prop([]);
+    #label = this.prop("");
+    #index = this.prop(0);
+    /** The slides don't all fit: only then are there places to move to. */
+    #overflows = this.prop(false);
+    #resize;
+    #id = uid("aster-carousel");
+    #observer;
+    /** Rebuilt when descriptors change or the element reconnects. */
+    #observed;
+    #restoreId;
+    #restoreFocus;
+    get slides() {
+        return this.#slides.value;
+    }
+    set slides(v) {
+        const ids = v.filter(s => s.id !== undefined).map(s => s.id);
+        if (new Set(ids).size !== ids.length || ids.some(id => !id))
+            throw new TypeError("Carousel slide IDs must be unique and nonempty");
+        const current = this.#slides.peek()[this.#index.peek()]?.id;
+        const active = document.activeElement;
+        this.#restoreFocus = active instanceof HTMLElement && active.closest("aster-carousel") === this ? active : undefined;
+        this.#restoreId = current && v.some(s => s.id === current) ? current : undefined;
+        this.#slides.value = [...v];
+    }
+    get label() {
+        return this.#label.value;
+    }
+    set label(v) {
+        this.#label.value = v;
+    }
+    /** The slide most in view. */
+    get index() {
+        return this.#index.value;
+    }
+    /** Brings a slide into view (smoothly unless motion is reduced). */
+    show(index) {
+        const slides = this.#slideEls();
+        const target = slides[Math.max(0, Math.min(slides.length - 1, index))];
+        const rail = this.querySelector(".aster-carousel-rail");
+        if (!target || !rail)
+            return;
+        const behavior = matchMedia("(prefers-reduced-motion: reduce)").matches ? "instant" : "smooth";
+        const rtl = getComputedStyle(this).direction === "rtl";
+        const first = slides[0];
+        const left = first ? rtl ? target.offsetLeft + target.offsetWidth - first.offsetLeft - first.offsetWidth : target.offsetLeft - first.offsetLeft : 0;
+        rail.scrollTo({ left, behavior: behavior });
+    }
+    disconnectedCallback() {
+        this.#observer?.disconnect();
+        this.#resize?.disconnect();
+        this.#observed = undefined;
+        super.disconnectedCallback();
+    }
+    render() {
+        const slides = this.#slides.value;
+        const index = Math.min(this.#index.value, Math.max(0, slides.length - 1));
+        const arrow = (back) => html `<svg viewBox="0 0 16 16" aria-hidden="true"><path d=${back ? "m10 3-5 5 5 5" : "m6 3 5 5-5 5"}/></svg>`;
+        return html `<section class="aster-carousel" aria-roledescription="carousel" aria-label=${this.#label.value}>
+      <div class="aster-carousel-rail" id=${`${this.#id}-rail`}>
+        ${each(slides.map((slide, index) => ({ slide, index })), x => x.slide.id === undefined ? `index:${x.index}` : `id:${x.slide.id}`, ({ slide: s, index: i }) => html `<div class="aster-carousel-slide" role="group" aria-roledescription="slide"
+            aria-label=${`${i + 1} of ${slides.length}: ${s.label}`} data-index=${i}>${s.view}</div>`)}
+      </div>
+      ${slides.length > 1 && this.#overflows.value
+            ? html `<div class="aster-carousel-nav">
+            <span aria-live="polite" aria-atomic="true">${index + 1} of ${slides.length}</span>
+            <button type="button" aria-controls=${`${this.#id}-rail`} aria-label="Previous" title="Previous" ?disabled=${index === 0} @click=${() => this.show(index - 1)}>${arrow(true)}</button>
+            <button type="button" aria-controls=${`${this.#id}-rail`} aria-label="Next" title="Next" ?disabled=${index === slides.length - 1} @click=${() => this.show(index + 1)}>${arrow(false)}</button>
+          </div>`
+            : nothing}
+    </section>`;
+    }
+    updated() {
+        if (this.#observed !== this.#slides.peek()) {
+            this.#observe();
+            if (this.#restoreId) {
+                const index = this.#slides.peek().findIndex(s => s.id === this.#restoreId);
+                this.#restoreId = undefined;
+                if (index >= 0) {
+                    this.#index.value = index;
+                    const rail = this.querySelector(".aster-carousel-rail"), slide = this.#slideEls()[index], first = this.#slideEls()[0];
+                    if (rail && slide && first)
+                        rail.scrollLeft = getComputedStyle(this).direction === "rtl" ? slide.offsetLeft + slide.offsetWidth - first.offsetLeft - first.offsetWidth : slide.offsetLeft - first.offsetLeft;
+                }
+            }
+        }
+        const focused = this.#restoreFocus;
+        this.#restoreFocus = undefined;
+        if (focused?.isConnected && (document.activeElement === document.body || document.activeElement === focused))
+            focused.focus({ preventScroll: true });
+    }
+    /** The slide most in view becomes current. */
+    #observe() {
+        const rail = this.querySelector(".aster-carousel-rail");
+        if (!rail)
+            return;
+        this.#observer?.disconnect();
+        this.#observed = this.#slides.peek();
+        this.#index.value = Math.min(this.#index.peek(), Math.max(0, this.#slides.peek().length - 1));
+        const ratios = new Map();
+        this.#observer = new IntersectionObserver((entries) => {
+            for (const e of entries)
+                ratios.set(Number(e.target.dataset.index), e.intersectionRatio);
+            let best = this.#index.peek();
+            let most = -1;
+            for (const [i, r] of ratios)
+                if (r > most + 0.01 || (Math.abs(r - most) <= 0.01 && i < best))
+                    [best, most] = [i, r];
+            if (most > 0)
+                this.#index.value = best;
+        }, { root: rail, threshold: [0, 0.25, 0.5, 0.75, 1] });
+        for (const el of this.#slideEls())
+            this.#observer.observe(el);
+        this.#resize?.disconnect();
+        this.#resize = new ResizeObserver(() => (this.#overflows.value = rail.scrollWidth > rail.clientWidth + 1));
+        this.#resize.observe(rail);
+        for (const el of this.#slideEls())
+            this.#resize.observe(el);
+    }
+    #slideEls() {
+        return [...this.querySelectorAll(".aster-carousel-slide")].filter(el => el.closest("aster-carousel") === this);
+    }
+}
+define("aster-carousel", Carousel);

package/dist/component/component.d.ts

@@ -0,0 +1,73 @@
+import { type ProgressPolicy, type PageScope } from "@getaster/data";
+import "../progress/status.ts";
+import { AsterElement, type View } from "../base/element.ts";
+/** Browser preferences and CSS-owned content dimensions, refreshed by the host. */
+export interface ComponentEnvironment {
+    /** Surface content width in CSS pixels, observed rather than computed by layout code. */
+    readonly width: number;
+    /** Surface content height in CSS pixels. */
+    readonly height: number;
+    /** Non-zero surface, visible document and no inherited visibility:hidden. Offscreen scrolling does not pause it. */
+    readonly visible: boolean;
+    /** The live prefers-reduced-motion preference. */
+    readonly reducedMotion: boolean;
+    /** The live forced-colors preference. */
+    readonly forcedColors: boolean;
+    /** Explicit host locale, nearest lang or browser language. */
+    readonly locale: string;
+    /** Computed CSS direction of the host. */
+    readonly direction: string;
+    /** Browser device pixel ratio. */
+    readonly pixelRatio: number;
+    /** Current CSS token values; vendor-specific colour conversion belongs in its adapter. */
+    readonly theme: Readonly<Record<"surface" | "text" | "muted" | "rule" | "accent" | "positive" | "negative", string>>;
+    /** Computed CSS font family. */
+    readonly font: string;
+}
+/** One mount's private DOM and cancellation boundary. */
+export interface ComponentMount {
+    /** Private subtree for this mount; stale asynchronous work cannot touch a later mount's node. */
+    readonly node: HTMLElement;
+    /** Aborted on replacement, retry, disconnect or update failure. */
+    readonly signal: AbortSignal;
+    /** Initial browser environment; subsequent values arrive through update. */
+    readonly environment: ComponentEnvironment;
+    /** Nearest scope; borrowed, never disposed by the host. */
+    readonly scope: PageScope | undefined;
+}
+/** A mounted vendor component. Every resource created by mount belongs here. */
+export interface ComponentSession {
+    /** Synchronous signal reads are tracked; called again when they or the environment change. */
+    update(environment: ComponentEnvironment): void;
+    /** Stops subscriptions, vendor listeners, observers and vendor rendering. Called exactly once. */
+    dispose(): void;
+}
+/** Vendor-neutral lifecycle. Lazy imports belong in mount and must honour its signal. */
+export interface ComponentAdapter {
+    /** Acquires a session; check cancellation after awaits and release partial acquisitions before throwing. */
+    mount(context: ComponentMount): ComponentSession | Promise<ComponentSession>;
+}
+/** A stable vendor-owned surface with an independently rendered accessible alternative. */
+export declare class ComponentHost extends AsterElement {
+    #private;
+    get progressPolicy(): ProgressPolicy;
+    set progressPolicy(value: ProgressPolicy);
+    /** Replacing the adapter disposes its previous session and mounts afresh when visible. */
+    get adapter(): ComponentAdapter | undefined;
+    set adapter(value: ComponentAdapter | undefined);
+    /** Required: HTML data and keyboard actions equivalent to the visual content. */
+    get alternative(): (() => View) | undefined;
+    set alternative(value: (() => View) | undefined);
+    /** Visible heading and accessible name for this component. */
+    get label(): string;
+    set label(value: string);
+    /** Defaults to the nearest lang attribute, then the browser language. */
+    get locale(): string | undefined;
+    set locale(value: string | undefined);
+    /** Retries a failed mount or update with a fresh DOM node. */
+    retry(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): View;
+    protected updated(): void;
+}

package/dist/component/component.js

@@ -0,0 +1,190 @@
+import { effect, signal, untracked } from "@preact/signals-core";
+import { html, nothing } from "lit-html";
+import { progressPolicy } from "@getaster/data";
+import "../progress/status.js";
+import { AsterElement, define, scopeOf, uid } from "../base/element.js";
+/** A stable vendor-owned surface with an independently rendered accessible alternative. */
+export class ComponentHost extends AsterElement {
+    #progressPolicy = this.prop({});
+    #adapter = this.prop(undefined);
+    #alternative = this.prop(undefined);
+    #label = this.prop("Chart");
+    #locale = this.prop(undefined);
+    #attempt = signal(0);
+    #status = this.prop("waiting");
+    #environment = signal(undefined);
+    #id = uid("aster-component");
+    #surface;
+    #abort;
+    #session;
+    #stopUpdate;
+    #generation = 0;
+    #size = { width: 0, height: 0 };
+    #refresh;
+    get progressPolicy() { return this.#progressPolicy.value; }
+    set progressPolicy(value) { progressPolicy(value); this.#progressPolicy.value = Object.freeze({ ...value }); }
+    /** Replacing the adapter disposes its previous session and mounts afresh when visible. */
+    get adapter() { return this.#adapter.value; }
+    set adapter(value) { this.#adapter.value = value; }
+    /** Required: HTML data and keyboard actions equivalent to the visual content. */
+    get alternative() { return this.#alternative.value; }
+    set alternative(value) { this.#alternative.value = value; }
+    /** Visible heading and accessible name for this component. */
+    get label() { return this.#label.value; }
+    set label(value) { this.#label.value = value; }
+    /** Defaults to the nearest lang attribute, then the browser language. */
+    get locale() { return this.#locale.value; }
+    set locale(value) { this.#locale.value = value; }
+    /** Retries a failed mount or update with a fresh DOM node. */
+    retry() { this.#attempt.value++; }
+    connectedCallback() {
+        super.connectedCallback();
+        this.#surface = this.querySelector(".aster-component-surface");
+        const motion = matchMedia("(prefers-reduced-motion: reduce)");
+        const contrast = matchMedia("(forced-colors: active)");
+        const refresh = () => {
+            if (!this.isConnected)
+                return;
+            const style = getComputedStyle(this);
+            const token = (name) => style.getPropertyValue(`--aster-${name}`).trim();
+            const next = {
+                ...this.#size,
+                visible: this.#size.width > 0 && this.#size.height > 0 && !document.hidden && style.visibility !== "hidden",
+                reducedMotion: motion.matches, forcedColors: contrast.matches,
+                locale: this.#locale.peek() ?? this.closest("[lang]")?.getAttribute("lang") ?? navigator.language,
+                direction: style.direction, pixelRatio: devicePixelRatio,
+                theme: { surface: token("surface"), text: token("text"), muted: token("text-2"), rule: token("rule"), accent: token("accent"), positive: token("positive"), negative: token("negative") },
+                font: style.fontFamily,
+            };
+            if (JSON.stringify(next) !== JSON.stringify(this.#environment.peek()))
+                this.#environment.value = next;
+        };
+        this.#refresh = refresh;
+        const resize = new ResizeObserver(([entry]) => {
+            if (!entry)
+                return;
+            this.#size = { width: entry.contentRect.width, height: entry.contentRect.height };
+            refresh();
+        });
+        resize.observe(this.#surface);
+        const attributes = new MutationObserver((records) => {
+            if (records.some((r) => r.target instanceof Element && r.target.contains(this)))
+                refresh();
+        });
+        attributes.observe(document.documentElement, { attributes: true, subtree: true, attributeFilter: ["class", "style", "hidden", "lang", "dir", "data-identity", "data-scheme", "data-density"] });
+        for (const media of [motion, contrast])
+            media.addEventListener("change", refresh);
+        document.addEventListener("visibilitychange", refresh);
+        document.addEventListener("load", refresh, true);
+        window.addEventListener("resize", refresh);
+        refresh();
+        this.onDisconnect(() => {
+            resize.disconnect();
+            attributes.disconnect();
+            for (const media of [motion, contrast])
+                media.removeEventListener("change", refresh);
+            document.removeEventListener("visibilitychange", refresh);
+            document.removeEventListener("load", refresh, true);
+            window.removeEventListener("resize", refresh);
+            this.#refresh = undefined;
+        });
+        this.onDisconnect(effect(() => {
+            const adapter = this.#adapter.value;
+            const alternative = this.#alternative.value;
+            this.#attempt.value;
+            untracked(() => {
+                this.#dispose();
+                this.#status.value = "waiting";
+                if (!adapter || !alternative)
+                    return;
+                const generation = this.#generation;
+                const stop = effect(() => {
+                    const environment = this.#environment.value;
+                    if (environment?.visible)
+                        untracked(() => {
+                            if (!this.#abort && this.#status.peek() !== "error")
+                                void this.#mount(adapter, environment, generation);
+                        });
+                });
+                this.#stopUpdate = stop;
+            });
+        }));
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.#dispose();
+        this.#environment.value = undefined;
+        this.#size = { width: 0, height: 0 };
+    }
+    render() {
+        this.#locale.value;
+        const status = this.#status.value;
+        const alternative = this.#alternative.value;
+        return html `<section class="aster-component" aria-labelledby=${this.#id}>
+      <h3 id=${this.#id}>${this.#label.value}</h3>
+      <div class="aster-component-surface" aria-hidden="true"></div>
+      <div class="aster-component-status"><aster-progress-status .busy=${status === "loading"}
+        .error=${status === "error" ? "Visualisation unavailable." : !alternative ? "Provide an accessible alternative to enable this visualisation." : undefined}
+        .progressPolicy=${this.#progressPolicy.value} .pendingText=${"Loading visualisation…"} .completeText=${"Visualisation ready"}></aster-progress-status>
+        ${status === "error" ? html `<button class="aster-button" type="button" @click=${() => this.retry()}>Retry visualisation</button>` : nothing}</div>
+      <div class="aster-component-alternative" role="region" aria-label=${`${this.#label.value} data and actions`} tabindex="0">${alternative?.() ?? nothing}</div>
+    </section>`;
+    }
+    updated() { this.#refresh?.(); }
+    async #mount(adapter, environment, generation) {
+        const abort = new AbortController();
+        this.#abort = abort;
+        const node = document.createElement("div");
+        node.className = "aster-component-content";
+        this.#surface.replaceChildren(node);
+        this.#status.value = "loading";
+        try {
+            const session = await adapter.mount({ node, signal: abort.signal, environment, scope: scopeOf(this) });
+            if (generation !== this.#generation || abort.signal.aborted) {
+                session.dispose();
+                return;
+            }
+            this.#session = session;
+            this.#stopUpdate?.();
+            this.#stopUpdate = effect(() => {
+                const current = this.#environment.value;
+                if (!current)
+                    return;
+                try {
+                    session.update(current);
+                }
+                catch (error) {
+                    queueMicrotask(() => this.#fail(error, generation));
+                }
+            });
+            this.#status.value = "ready";
+        }
+        catch (error) {
+            this.#fail(error, generation);
+        }
+    }
+    #fail(error, generation) {
+        if (generation !== this.#generation || !this.isConnected)
+            return;
+        this.#dispose();
+        this.#status.value = "error";
+        this.emit("component-error", error);
+    }
+    #dispose() {
+        this.#generation++;
+        this.#abort?.abort();
+        this.#abort = undefined;
+        this.#stopUpdate?.();
+        this.#stopUpdate = undefined;
+        const session = this.#session;
+        this.#session = undefined;
+        try {
+            session?.dispose();
+        }
+        catch (error) {
+            this.emit("component-error", error);
+        }
+        this.#surface?.replaceChildren();
+    }
+}
+define("aster-component", ComponentHost);

package/dist/component/echarts.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentAdapter, ComponentEnvironment } from "./component.ts";
+/** The small structural API the adapter needs; pass an optional ECharts module via load. */
+export interface EChartsRuntime {
+    /** Creates one SVG chart. Locale packs are registered by the application loader. */
+    init(node: HTMLElement, theme?: undefined, options?: {
+        renderer: "svg";
+        locale: string;
+        devicePixelRatio: number;
+    }): EChartsInstance;
+}
+/** Public ECharts methods used by the reference adapter. */
+export interface EChartsInstance {
+    /** Updates chart options without publishing synthetic selection events. */
+    setOption(option: object, options: {
+        notMerge: boolean;
+        silent: boolean;
+        replaceMerge?: string[];
+    }): void;
+    /** Resizes internal chart rendering to observed CSS dimensions. */
+    resize(options: {
+        width: number;
+        height: number;
+        silent: boolean;
+    }): void;
+    /** Attaches the adapter's pointer action callback. */
+    on(event: "click", listener: (event: unknown) => void): void;
+    /** Removes the same callback before disposing. */
+    off(event: "click", listener: (event: unknown) => void): void;
+    /** Releases vendor-owned rendering and event resources. */
+    dispose(): void;
+}
+/** Configuration stays in the application; no ECharts dependency ships in the elements package. */
+export interface EChartsAdapterOptions {
+    /** Lazy module load. Register any modular charts/components before returning it. */
+    readonly load: () => Promise<EChartsRuntime>;
+    /** Reads public data signals; must return a complete option, including empty/loading states. */
+    readonly option: (environment: ComponentEnvironment) => Readonly<Record<string, unknown>>;
+    /** Merge stable named series/data for incremental transitions; omitted option fields are retained. Default replace. */
+    readonly updateMode?: "replace" | "merge";
+    /** Explicit mapping of vendor events to public data actions; no implicit record/index mapping. */
+    readonly click?: (event: unknown) => void;
+}
+/** CSS colours resolved to sRGB for vendor parsers that don't understand modern CSS colours. */
+export declare function echartsColors(environment: ComponentEnvironment): ComponentEnvironment["theme"];
+/** ECharts reference lifecycle: stable SVG, reactive options, silent updates and exact disposal. */
+export declare function echartsAdapter(options: EChartsAdapterOptions): ComponentAdapter;

package/dist/component/echarts.js

@@ -0,0 +1,95 @@
+/** CSS colours resolved to sRGB for vendor parsers that don't understand modern CSS colours. */
+export function echartsColors(environment) {
+    const canvas = document.createElement("canvas");
+    canvas.width = canvas.height = 1;
+    const ctx = canvas.getContext("2d", { willReadFrequently: true });
+    const colour = (value) => {
+        ctx.clearRect(0, 0, 1, 1);
+        ctx.fillStyle = value;
+        ctx.fillRect(0, 0, 1, 1);
+        const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+        return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+    };
+    const theme = environment.theme;
+    return { surface: colour(theme.surface), text: colour(theme.text), muted: colour(theme.muted), rule: colour(theme.rule), accent: colour(theme.accent), positive: colour(theme.positive), negative: colour(theme.negative) };
+}
+/** ECharts reference lifecycle: stable SVG, reactive options, silent updates and exact disposal. */
+export function echartsAdapter(options) {
+    return {
+        async mount({ node, signal, environment }) {
+            const runtime = await options.load();
+            if (signal.aborted)
+                return { update() { }, dispose() { } };
+            let chart;
+            let locale = environment.locale;
+            const click = (event) => { if (!signal.aborted)
+                options.click?.(event); };
+            const dispose = () => {
+                const owned = chart;
+                chart = undefined;
+                if (!owned)
+                    return;
+                try {
+                    owned.off("click", click);
+                }
+                finally {
+                    owned.dispose();
+                }
+            };
+            const init = (current) => {
+                chart = runtime.init(node, undefined, { renderer: "svg", locale: current.locale, devicePixelRatio: current.pixelRatio });
+                try {
+                    chart.on("click", click);
+                }
+                catch (error) {
+                    dispose();
+                    throw error;
+                }
+                locale = current.locale;
+            };
+            init(environment);
+            let previous;
+            let previousMotion;
+            return {
+                update(current) {
+                    // Read data while hidden too, so showing the component uses the latest state.
+                    const option = options.option(current);
+                    if (!current.visible || current.forcedColors) {
+                        node.hidden = true;
+                        previous = undefined;
+                        return;
+                    }
+                    node.hidden = false;
+                    if (locale !== current.locale) {
+                        dispose();
+                        init(current);
+                        previous = undefined;
+                        previousMotion = undefined;
+                    }
+                    const colors = echartsColors(current);
+                    chart.setOption({
+                        backgroundColor: colors.surface,
+                        color: [colors.accent, colors.muted, colors.negative],
+                        textStyle: { color: colors.text, fontFamily: current.font },
+                        ...option,
+                        // HTML tooltips would escape the host's presentation-only subtree.
+                        tooltip: { show: false },
+                        animation: !current.reducedMotion && option.animation !== false,
+                        ...(current.reducedMotion ? {
+                            animationDuration: 0, animationDurationUpdate: 0,
+                            series: (Array.isArray(option.series) ? option.series : option.series ? [option.series] : []).map((series) => ({ ...series, animation: false, animationDuration: 0, animationDurationUpdate: 0, universalTransition: false })),
+                        } : {}),
+                    }, options.updateMode === "merge" && (previousMotion === undefined || previousMotion === current.reducedMotion)
+                        ? { notMerge: false, replaceMerge: ["series"], silent: true }
+                        : { notMerge: true, silent: true });
+                    previousMotion = current.reducedMotion;
+                    if (!previous || previous.width !== current.width || previous.height !== current.height || previous.pixelRatio !== current.pixelRatio) {
+                        chart.resize({ width: current.width, height: current.height, silent: true });
+                    }
+                    previous = current;
+                },
+                dispose,
+            };
+        },
+    };
+}