@viniaraujo68/plinth 0.0.0-stage → 0.3.0

package/dist/async-action.svelte.js

@@ -0,0 +1,64 @@
+/**
+ * A promise-returning function plus the four-state machine every button around one ends up
+ * re-implementing: idle, pending, success, error.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { AsyncAction } from "@viniaraujo68/plinth";
+ *
+ *   const save = new AsyncAction((draft: Draft) => api.save(draft));
+ * </script>
+ *
+ * <button disabled={save.isPending} onclick={() => save.run(draft)}>Save</button>
+ * {#if save.isError}<p class="text-error">Could not save.</p>{/if}
+ * ```
+ */
+export class AsyncAction {
+    fn;
+    status = $state("idle");
+    error = $state(null);
+    isPending = $derived(this.status === "pending");
+    isSuccess = $derived(this.status === "success");
+    isError = $derived(this.status === "error");
+    /**
+     * Identifies the run whose result is allowed to write state. A second click while the first
+     * call is still in flight makes the first one stale: without this, a slow success landing after
+     * a fast failure would paint the button green.
+     */
+    #currentRun = 0;
+    constructor(fn) {
+        this.fn = fn;
+    }
+    reset = () => {
+        this.status = "idle";
+        this.error = null;
+        // Anything still in flight is abandoned rather than allowed to resurrect a settled state.
+        this.#currentRun++;
+    };
+    /**
+     * Runs the action and records the outcome.
+     *
+     * It never rejects: an event handler has nowhere to catch, so a rethrow here would surface as an
+     * unhandled rejection instead of as UI. Failure is `error` and `isError`. A run that failed —
+     * or that was superseded by a later `run`/`reset` — resolves to `undefined`.
+     */
+    run = async (...args) => {
+        const run = ++this.#currentRun;
+        this.status = "pending";
+        this.error = null;
+        try {
+            const result = (await this.fn(...args));
+            if (run !== this.#currentRun)
+                return undefined;
+            this.status = "success";
+            return result;
+        }
+        catch (failure) {
+            if (run !== this.#currentRun)
+                return undefined;
+            this.status = "error";
+            this.error = failure;
+            return undefined;
+        }
+    };
+}

package/dist/attachments/index.d.ts

@@ -0,0 +1,2 @@
+export { sortable, type SortableOptions } from "./sortable.js";
+export { tooltip, tooltipPanel, type TooltipOptions } from "./tooltip.js";

package/dist/attachments/index.js

@@ -0,0 +1,2 @@
+export { sortable } from "./sortable.js";
+export { tooltip, tooltipPanel } from "./tooltip.js";

package/dist/attachments/sortable.d.ts

@@ -0,0 +1,6 @@
+import type { Attachment } from "svelte/attachments";
+export interface SortableOptions {
+    onmove: (from: number, to: number) => void;
+    disabled?: boolean;
+}
+export declare const sortable: (options: SortableOptions) => Attachment<HTMLElement>;

package/dist/attachments/sortable.js

@@ -0,0 +1,227 @@
+import { tick } from "svelte";
+const ITEM = "[data-sortable-item]";
+const HANDLE = "[data-sortable-handle]";
+const DRAGGING = "data-sortable-dragging";
+const ANIMATION_ID = "plinth-sortable";
+const SHIFT_MS = 180;
+const SETTLE_MS = 160;
+const EASING = "cubic-bezier(0.2, 0, 0, 1)";
+const KEY_STEPS = {
+    ArrowLeft: -1,
+    ArrowUp: -1,
+    ArrowRight: 1,
+    ArrowDown: 1,
+};
+const destination = (key, from, last) => {
+    if (key === "Home")
+        return 0;
+    if (key === "End")
+        return last;
+    return key in KEY_STEPS ? from + KEY_STEPS[key] : null;
+};
+const layoutCenter = (element) => ({
+    x: element.offsetLeft + element.offsetWidth / 2,
+    y: element.offsetTop + element.offsetHeight / 2,
+});
+const draggedCenter = (current) => ({
+    x: current.startLeft + current.item.offsetWidth / 2 + current.x - current.grabX,
+    y: current.startTop + current.item.offsetHeight / 2 + current.y - current.grabY,
+});
+const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+const reducedMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+const cancelShift = (element) => {
+    for (const animation of element.getAnimations())
+        if (animation.id === ANIMATION_ID)
+            animation.cancel();
+};
+const offsetOf = (element) => {
+    const [x = "0", y = "0"] = element.style.translate.split(" ");
+    return { x: Number.parseFloat(x) || 0, y: Number.parseFloat(y) || 0 };
+};
+export const sortable = (options) => (container) => {
+    let drag = null;
+    let shifting = false;
+    let frame = 0;
+    const items = () => [...container.querySelectorAll(ITEM)];
+    const handleOf = (event) => {
+        const handle = event.target?.closest(HANDLE) ?? null;
+        return handle && container.contains(handle) ? handle : null;
+    };
+    const shift = async (move, still) => {
+        const before = new Map(items().map((element) => [element, element.getBoundingClientRect()]));
+        move();
+        await tick();
+        if (reducedMotion())
+            return;
+        for (const element of items()) {
+            const previous = before.get(element);
+            if (element === still || !previous)
+                continue;
+            cancelShift(element);
+            const current = element.getBoundingClientRect();
+            const dx = previous.left - current.left;
+            const dy = previous.top - current.top;
+            if (!dx && !dy)
+                continue;
+            element.animate([{ translate: `${dx}px ${dy}px` }, { translate: "0px 0px" }], {
+                duration: SHIFT_MS,
+                easing: EASING,
+                id: ANIMATION_ID,
+            });
+        }
+    };
+    const follow = () => {
+        if (!drag)
+            return;
+        const { item } = drag;
+        const dx = drag.x - drag.grabX - (item.offsetLeft - drag.startLeft);
+        const dy = drag.y - drag.grabY - (item.offsetTop - drag.startTop);
+        item.style.translate = `${dx}px ${dy}px`;
+    };
+    const targetFor = (current) => {
+        const all = items();
+        const from = all.indexOf(current.item);
+        if (from < 0)
+            return null;
+        const center = draggedCenter(current);
+        let index = -1;
+        let nearest = Infinity;
+        for (const [position, element] of all.entries()) {
+            if (element === current.item)
+                continue;
+            const gap = distance(center, layoutCenter(element));
+            if (gap < nearest) {
+                nearest = gap;
+                index = position;
+            }
+        }
+        if (index < 0)
+            return null;
+        const target = all[index];
+        const middle = layoutCenter(target);
+        const sameRow = Math.abs(target.offsetTop - current.item.offsetTop) < target.offsetHeight / 2;
+        const forward = index > from;
+        const passed = sameRow ? forward === center.x > middle.x : forward === center.y > middle.y;
+        return passed ? { from, to: index } : null;
+    };
+    const step = () => {
+        if (!drag || shifting)
+            return;
+        follow();
+        const target = targetFor(drag);
+        if (!target)
+            return;
+        shifting = true;
+        const { item } = drag;
+        void shift(() => {
+            options.onmove(target.from, target.to);
+        }, item).then(() => {
+            shifting = false;
+            follow();
+            frame = requestAnimationFrame(step);
+        });
+    };
+    const settle = (current) => {
+        const { item, restore } = current;
+        const offset = offsetOf(item);
+        item.style.translate = "";
+        item.removeAttribute(DRAGGING);
+        const done = () => {
+            item.style.position = restore.position;
+            item.style.zIndex = restore.zIndex;
+            item.style.willChange = restore.willChange;
+        };
+        if (reducedMotion() || (!offset.x && !offset.y)) {
+            done();
+            return;
+        }
+        const animation = item.animate([{ translate: `${offset.x}px ${offset.y}px` }, { translate: "0px 0px" }], { duration: SETTLE_MS, easing: EASING });
+        void animation.finished.then(done, done);
+    };
+    const stop = () => {
+        cancelAnimationFrame(frame);
+        window.removeEventListener("pointermove", onPointerMove);
+        window.removeEventListener("pointerup", onPointerUp);
+        window.removeEventListener("pointercancel", onPointerUp);
+        if (!drag)
+            return;
+        const current = drag;
+        drag = null;
+        settle(current);
+    };
+    function onPointerMove(event) {
+        if (drag?.pointerId !== event.pointerId)
+            return;
+        drag.x = event.clientX;
+        drag.y = event.clientY;
+        step();
+    }
+    function onPointerUp(event) {
+        if (drag?.pointerId === event.pointerId)
+            stop();
+    }
+    const onPointerDown = (event) => {
+        if (options.disabled || event.button !== 0 || drag)
+            return;
+        const item = handleOf(event)?.closest(ITEM);
+        if (!item)
+            return;
+        event.preventDefault();
+        cancelShift(item);
+        drag = {
+            item,
+            pointerId: event.pointerId,
+            grabX: event.clientX,
+            grabY: event.clientY,
+            startLeft: item.offsetLeft,
+            startTop: item.offsetTop,
+            x: event.clientX,
+            y: event.clientY,
+            restore: {
+                position: item.style.position,
+                zIndex: item.style.zIndex,
+                willChange: item.style.willChange,
+            },
+        };
+        if (getComputedStyle(item).position === "static")
+            item.style.position = "relative";
+        item.style.zIndex = "10";
+        item.style.willChange = "translate";
+        item.setAttribute(DRAGGING, "");
+        window.addEventListener("pointermove", onPointerMove);
+        window.addEventListener("pointerup", onPointerUp);
+        window.addEventListener("pointercancel", onPointerUp);
+    };
+    const onTouchMove = (event) => {
+        if (drag)
+            event.preventDefault();
+    };
+    const onKeyDown = (event) => {
+        if (options.disabled || drag)
+            return;
+        const item = handleOf(event)?.closest(ITEM);
+        if (!item)
+            return;
+        const all = items();
+        const from = all.indexOf(item);
+        const last = all.length - 1;
+        const to = destination(event.key, from, last);
+        if (to === null || from < 0)
+            return;
+        event.preventDefault();
+        if (to < 0 || to > last || to === from)
+            return;
+        void shift(() => {
+            options.onmove(from, to);
+        }).then(() => items()[to]?.querySelector(HANDLE)?.focus());
+    };
+    container.addEventListener("pointerdown", onPointerDown);
+    container.addEventListener("touchmove", onTouchMove, { passive: false });
+    container.addEventListener("keydown", onKeyDown);
+    return () => {
+        stop();
+        container.removeEventListener("pointerdown", onPointerDown);
+        container.removeEventListener("touchmove", onTouchMove);
+        container.removeEventListener("keydown", onKeyDown);
+    };
+};

package/dist/attachments/tooltip.d.ts

@@ -0,0 +1,37 @@
+import type { Attachment } from "svelte/attachments";
+export interface TooltipOptions {
+    /** Keeps the wiring attached but suppresses the panel, so a caller can gate a tooltip on
+        state — a rail label that is only worth showing while the rail is collapsed, say — without
+        conditionally applying the attachment and losing the listeners on every toggle. */
+    disabled?: boolean;
+}
+/**
+ * Attaches a plain-text tooltip to the host, shown on hover and on keyboard focus.
+ *
+ * The host stays the root of whatever the caller renders, so layout that depends on the element's
+ * own position — `join-item`, a grid cell, a flex child — keeps working untouched.
+ *
+ * ```svelte
+ * <button class="btn" {@attach tooltip("Archive")}>…</button>
+ * ```
+ *
+ * The panel is created lazily and owned by this attachment, which is what makes it cheap enough
+ * for one per row of a long list. Rich content belongs in markup instead — see `tooltipPanel`.
+ */
+export declare function tooltip(text: string, options?: TooltipOptions): Attachment<HTMLElement>;
+/**
+ * Wires the same hover and focus behavior between the host and a panel the caller renders itself,
+ * which is what rich content needs: a snippet rendered in the caller's markup keeps its component
+ * context, its scoped styles and its reactivity, none of which survive `createElement`.
+ *
+ * The panel is given the sanctioned tooltip styling when the attachment runs.
+ *
+ * Reactivity is `{@attach}`'s own: the expression re-runs whenever `panel` changes, tearing the
+ * old binding down and building a new one.
+ *
+ * ```svelte
+ * <span {@attach tooltipPanel(panel)}>…</span>
+ * <div bind:this={panel} popover="manual" role="tooltip">rich <strong>content</strong></div>
+ * ```
+ */
+export declare function tooltipPanel(panel: HTMLElement | undefined | null, options?: TooltipOptions): Attachment<HTMLElement>;

package/dist/attachments/tooltip.js

@@ -0,0 +1,166 @@
+import { positionUnder, supportsAnchorPositioning } from "../anchoring.js";
+/* Anchor positioning links a panel to its trigger through a document-wide custom ident, so every
+   binding needs an ident nothing else uses. A module-level counter is enough: the pair is created
+   and torn down together, and the value never leaves this module. */
+let bindingCount = 0;
+/** The panel's `margin` below, in pixels: `0.375rem` at the default root size. The script
+    fallback needs the number, since it places the panel from `getBoundingClientRect()` readings. */
+const GAP = 6;
+/* The panel is styled imperatively rather than through utility classes because the panel of the
+   string variant is created by this module, outside any component — a consumer's Tailwind build
+   has no source file to scan for those classes and would emit nothing. Reading the daisyUI custom
+   properties keeps it themed anyway, including inside a `data-theme` subtree. */
+const applyPanelStyle = (panel, anchorName) => {
+    panel.popover = "manual";
+    panel.role = "tooltip";
+    panel.style.setProperty("position-anchor", anchorName);
+    panel.style.setProperty("position-area", "top");
+    panel.style.setProperty("position-try-fallbacks", "flip-block, flip-inline");
+    Object.assign(panel.style, {
+        // A tooltip that swallows the pointer is a flicker loop: content taller than a small trigger
+        // ends up covering it, the host sees mouseleave, the panel hides, the host sees mouseenter
+        // again. Staying transparent to hit-testing is what breaks the cycle.
+        pointerEvents: "none",
+        whiteSpace: "normal",
+        overflowWrap: "break-word",
+        margin: "0.375rem",
+        width: "max-content",
+        maxWidth: "20rem",
+        padding: "0.25rem 0.5rem",
+        fontSize: "0.8125rem",
+        lineHeight: "1.25",
+        color: "var(--color-base-content)",
+        background: "var(--color-base-100)",
+        border: "1px solid color-mix(in oklch, var(--color-base-content) 15%, transparent)",
+        borderRadius: "var(--radius-field)",
+        boxShadow: "0 8px 24px rgb(0 0 0 / 0.2)",
+    });
+};
+const bind = (host, resolvePanel, options, 
+/* A panel the caller rendered is already in the document and visible; only `popover` takes it
+   out of the flow, so it has to be prepared immediately. A panel this module owns is created on
+   demand and can stay unprepared until the first show. */
+prepareImmediately) => {
+    const panelId = `plinth-tooltip-${bindingCount++}`;
+    const anchorName = `--${panelId}`;
+    let panel;
+    // The host may already carry either of these from the caller's own markup; both are restored
+    // verbatim on teardown so an attachment that re-runs leaves nothing behind.
+    const inheritedDescribedBy = host.getAttribute("aria-describedby");
+    const inheritedAnchorName = host.style.getPropertyValue("anchor-name");
+    host.style.setProperty("anchor-name", anchorName);
+    const prepare = () => {
+        if (panel)
+            return panel;
+        panel = resolvePanel();
+        if (!panel)
+            return undefined;
+        panel.id = panelId;
+        applyPanelStyle(panel, anchorName);
+        host.setAttribute("aria-describedby", [inheritedDescribedBy, panelId].filter(Boolean).join(" "));
+        return panel;
+    };
+    if (prepareImmediately)
+        prepare();
+    let stopPositioning;
+    const show = () => {
+        // Read through `options` at show time, not at bind time: a caller passing a plain object that
+        // it mutates would otherwise be stuck with whatever the flag was when the pair was created.
+        if (options.disabled)
+            return;
+        const shown = prepare();
+        if (!shown)
+            return;
+        shown.showPopover();
+        /* Without anchor positioning the `position-area` above is dropped and the UA popover rules
+           are all that is left, which -- with the `margin` overriding their `margin: auto` -- pins the
+           panel to the top corner of the screen. Script places it instead, to the same geometry:
+           centred on the host, above it, and below it when there is no room, which is `flip-block`. */
+        stopPositioning?.();
+        stopPositioning = supportsAnchorPositioning()
+            ? undefined
+            : positionUnder(shown, host, { side: "top", gap: GAP, inset: GAP });
+    };
+    const hide = () => {
+        stopPositioning?.();
+        stopPositioning = undefined;
+        panel?.hidePopover();
+    };
+    // A manual popover has no light dismiss, and the pointer never enters the panel, so Escape on
+    // the host is the only way out for someone reading the tooltip from the keyboard.
+    const onKeydown = (event) => {
+        if (event.key === "Escape")
+            hide();
+    };
+    host.addEventListener("mouseenter", show);
+    host.addEventListener("mouseleave", hide);
+    host.addEventListener("focusin", show);
+    host.addEventListener("focusout", hide);
+    host.addEventListener("keydown", onKeydown);
+    return () => {
+        host.removeEventListener("mouseenter", show);
+        host.removeEventListener("mouseleave", hide);
+        host.removeEventListener("focusin", show);
+        host.removeEventListener("focusout", hide);
+        host.removeEventListener("keydown", onKeydown);
+        hide();
+        host.style.removeProperty("anchor-name");
+        if (inheritedAnchorName)
+            host.style.setProperty("anchor-name", inheritedAnchorName);
+        if (inheritedDescribedBy)
+            host.setAttribute("aria-describedby", inheritedDescribedBy);
+        else
+            host.removeAttribute("aria-describedby");
+    };
+};
+/**
+ * Attaches a plain-text tooltip to the host, shown on hover and on keyboard focus.
+ *
+ * The host stays the root of whatever the caller renders, so layout that depends on the element's
+ * own position — `join-item`, a grid cell, a flex child — keeps working untouched.
+ *
+ * ```svelte
+ * <button class="btn" {@attach tooltip("Archive")}>…</button>
+ * ```
+ *
+ * The panel is created lazily and owned by this attachment, which is what makes it cheap enough
+ * for one per row of a long list. Rich content belongs in markup instead — see `tooltipPanel`.
+ */
+export function tooltip(text, options = {}) {
+    return (host) => {
+        let ownedPanel;
+        const unbind = bind(host, () => {
+            if (!ownedPanel) {
+                ownedPanel = document.createElement("div");
+                ownedPanel.textContent = text;
+                // Appended to the body rather than next to the host: an anchored popover escapes
+                // `overflow: hidden` and stacking contexts only from the top layer, and the top layer
+                // is only reachable from an element the host does not clip.
+                document.body.appendChild(ownedPanel);
+            }
+            return ownedPanel;
+        }, options, false);
+        return () => {
+            unbind();
+            ownedPanel?.remove();
+        };
+    };
+}
+/**
+ * Wires the same hover and focus behavior between the host and a panel the caller renders itself,
+ * which is what rich content needs: a snippet rendered in the caller's markup keeps its component
+ * context, its scoped styles and its reactivity, none of which survive `createElement`.
+ *
+ * The panel is given the sanctioned tooltip styling when the attachment runs.
+ *
+ * Reactivity is `{@attach}`'s own: the expression re-runs whenever `panel` changes, tearing the
+ * old binding down and building a new one.
+ *
+ * ```svelte
+ * <span {@attach tooltipPanel(panel)}>…</span>
+ * <div bind:this={panel} popover="manual" role="tooltip">rich <strong>content</strong></div>
+ * ```
+ */
+export function tooltipPanel(panel, options = {}) {
+    return (host) => bind(host, () => panel ?? undefined, options, true);
+}

package/dist/components/AsyncButton.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLButtonAttributes } from "svelte/elements";
+  import { AsyncAction } from "../async-action.svelte.js";
+  import { reportError } from "../error.js";
+  import LoadingButton from "./LoadingButton.svelte";
+
+  type ButtonClickEvent = MouseEvent & { currentTarget: EventTarget & HTMLButtonElement };
+
+  interface Props extends Omit<HTMLButtonAttributes, "onclick"> {
+    children: Snippet;
+    /** May return a promise; the button stays busy until it settles. */
+    onclick?: (event: ButtonClickEvent) => unknown;
+    /**
+     * Handles a rejection from `onclick`. Without it the failure goes to `reportError`, so a
+     * silent swallow is never the default.
+     */
+    onerror?: (error: unknown) => void;
+  }
+
+  let { children, onclick, onerror, ...rest }: Props = $props();
+
+  const action = new AsyncAction(async (event: ButtonClickEvent) => await onclick?.(event));
+
+  const handleClick = async (event: ButtonClickEvent) => {
+    await action.run(event);
+    if (action.isError) (onerror ?? reportError)(action.error);
+  };
+</script>
+
+<!--
+@component
+`LoadingButton` that derives its own busy state from the handler it was given: the click is
+awaited, the spinner runs for exactly as long as the promise, and a second click cannot start
+while the first is in flight.
+
+The rejection is caught here — an event handler has no caller to catch for it — and handed to
+`onerror`, or to `reportError` when the app has not said what to do with it.
+
+```svelte
+<AsyncButton class="btn btn-primary" onclick={() => api.publish(id)} onerror={showToast}>
+  Publish
+</AsyncButton>
+```
+-->
+
+<LoadingButton {...rest} loading={action.isPending} onclick={handleClick}>
+  {@render children()}
+</LoadingButton>

package/dist/components/AsyncButton.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { Snippet } from "svelte";
+import type { HTMLButtonAttributes } from "svelte/elements";
+type ButtonClickEvent = MouseEvent & {
+    currentTarget: EventTarget & HTMLButtonElement;
+};
+interface Props extends Omit<HTMLButtonAttributes, "onclick"> {
+    children: Snippet;
+    /** May return a promise; the button stays busy until it settles. */
+    onclick?: (event: ButtonClickEvent) => unknown;
+    /**
+     * Handles a rejection from `onclick`. Without it the failure goes to `reportError`, so a
+     * silent swallow is never the default.
+     */
+    onerror?: (error: unknown) => void;
+}
+/**
+ * `LoadingButton` that derives its own busy state from the handler it was given: the click is
+ * awaited, the spinner runs for exactly as long as the promise, and a second click cannot start
+ * while the first is in flight.
+ *
+ * The rejection is caught here — an event handler has no caller to catch for it — and handed to
+ * `onerror`, or to `reportError` when the app has not said what to do with it.
+ *
+ * ```svelte
+ * <AsyncButton class="btn btn-primary" onclick={() => api.publish(id)} onerror={showToast}>
+ * Publish
+ * </AsyncButton>
+ * ```
+ */
+declare const AsyncButton: import("svelte").Component<Props, {}, "">;
+type AsyncButton = ReturnType<typeof AsyncButton>;
+export default AsyncButton;