@viniaraujo68/plinth 0.0.0-stage → 0.2.0

package/dist/confirm/Confirmer.svelte

@@ -0,0 +1,194 @@
+<script lang="ts">
+  import type { ClassValue } from "svelte/elements";
+  import Modal from "../components/Modal.svelte";
+  import { challengeSatisfied } from "./challenge.js";
+  import {
+    getDefaultConfirmManager,
+    type ConfirmManager,
+    type ConfirmRequest,
+  } from "./confirm-manager.svelte.js";
+
+  interface Props {
+    /** Queue to render. Defaults to the one behind the module-level `confirm` helper. */
+    manager?: ConfirmManager;
+    /** Extra classes for the box -- a wider cap for a long name. Not for the backdrop. */
+    class?: ClassValue;
+    /**
+     * Default label of the confirm action, for apps that are not in English. A call overrides it
+     * with `confirmLabel`; this is what every call that does not gets.
+     */
+    confirmLabel?: string;
+    /** Default label of the cancel action. Overridden per call by `cancelLabel`. */
+    cancelLabel?: string;
+    /** Accessible name of the close button, which never varies per call. */
+    closeLabel?: string;
+    /**
+     * Labels the challenge input. A function rather than a string because the challenge itself has
+     * to appear inside the sentence, and only the app knows where its language puts it.
+     */
+    challengeLabel?: (challenge: string) => string;
+  }
+
+  let {
+    manager,
+    class: className,
+    confirmLabel = "Confirm",
+    cancelLabel = "Cancel",
+    closeLabel = "Close",
+    challengeLabel = (challenge) => `Type ${challenge} to confirm`,
+  }: Props = $props();
+
+  const resolvedManager = $derived(manager ?? getDefaultConfirmManager());
+
+  let modal = $state<Modal>();
+  // What is on screen, which is NOT the same as `manager.current`: the head of the queue advances
+  // the moment a request is settled, and the dialog is still fading out at that point. Holding the
+  // snapshot until the next one is actually presented is what keeps the closing box from flashing
+  // the next question's title.
+  let shown = $state<ConfirmRequest | null>(null);
+  let typed = $state("");
+
+  // Not `$state`: nothing renders from it, and it is written and read within one close cycle.
+  let outcome = false;
+
+  const inputId = $props.id();
+  const enabled = $derived(challengeSatisfied(shown?.challenge, typed));
+
+  // A question that fits entirely in its title -- "Delete this night?" -- has nothing to put in a
+  // body, and `Modal` renders no body element at all when it is handed no snippet. Deciding here
+  // rather than rendering an empty wrapper is what keeps that case from showing a padded strip
+  // between the header and the actions.
+  const hasBody = $derived(Boolean(shown?.description ?? shown?.challenge));
+
+  $effect(() =>
+    resolvedManager.attach(() => {
+      shown = resolvedManager.current;
+      typed = "";
+      outcome = false;
+      modal?.show();
+    }),
+  );
+
+  // Every path out of the dialog goes through `close`, so the decision is recorded first and read
+  // back once the element reports itself closed. That also means the awaiting caller resumes with
+  // the backdrop already gone, rather than racing a navigation against a closing dialog.
+  const decide = (confirmed: boolean) => {
+    outcome = confirmed;
+    modal?.close();
+  };
+
+  const handleClose = () => {
+    if (!shown) return;
+
+    const confirmed = outcome;
+    outcome = false;
+    // Escape, the backdrop and the close button never touch `outcome`, so they all arrive here as
+    // false -- cancel is the default of every path that is not the confirm action itself.
+    resolvedManager.settle(shown.id, confirmed);
+  };
+
+  const handleChallengeKeydown = (event: KeyboardEvent) => {
+    if (event.key !== "Enter") return;
+
+    // There is no form here, so nothing submits on its own and Enter has to be wired to the action
+    // it stands in for. Prevented in both branches: an Enter that lands before the gate opens must
+    // do nothing at all rather than fall through to anything else.
+    event.preventDefault();
+    if (enabled) decide(true);
+  };
+</script>
+
+<!--
+@component
+Renders a `ConfirmManager`'s queue as a modal question. Mount exactly one, unconditionally, in the
+app's root layout, next to `Toaster` and for the same reason: the call site that asks the question
+is somewhere else entirely.
+
+With no `manager` prop it renders the queue behind the module-level `confirm` helper, which is what
+lets any module in the app write the one line this exists for:
+
+```ts
+if (!(await confirm({ title: `Delete ${night.name}?`, danger: true }))) return;
+await api.delete(`/nights/${night.id}`);
+```
+
+The library ships no translations, so the four labels here are how an app localizes every confirm
+at once; a single call overrides any of them through its own options.
+
+Focus never lands on the confirm action. It opens on cancel, or on the challenge input when there
+is one, so a stray Enter can only ever cancel -- and in the challenge input Enter confirms solely
+when what has been typed already matches.
+-->
+
+{#snippet body()}
+  <div class="flex flex-col gap-4" data-testid="confirm-body">
+    {#if shown?.description}
+      <p class="text-sm whitespace-pre-line text-base-content/70" data-testid="confirm-description">
+        {shown.description}
+      </p>
+    {/if}
+
+    {#if shown?.challenge}
+      <div class="flex flex-col gap-2">
+        <label class="text-sm font-medium" for={inputId}>
+          {shown.challengeLabel ?? challengeLabel(shown.challenge)}
+        </label>
+        <!-- The browser opens a dialog on its first focusable descendant, which is the ✕.
+             Autofocus is how content overrides that, and it is the seam `Modal` already documents;
+             the a11y rule suppressed here is about a page stealing focus from a reader, which is
+             not what a dialog that has just taken focus by definition is doing. Autocomplete,
+             correction and capitalisation are off because the comparison is exact, and a phone
+             capitalising the first letter would make the gate unopenable. -->
+        <!-- svelte-ignore a11y_autofocus -->
+        <input
+          id={inputId}
+          data-testid="confirm-challenge"
+          class="input w-full"
+          type="text"
+          autocomplete="off"
+          autocapitalize="none"
+          autocorrect="off"
+          spellcheck="false"
+          autofocus
+          bind:value={typed}
+          onkeydown={handleChallengeKeydown}
+        />
+      </div>
+    {/if}
+  </div>
+{/snippet}
+
+{#snippet footer()}
+  <!-- The other half of the focus rule: with no challenge to type, cancel is where the dialog
+       opens, one Enter away from the safe outcome rather than from the destructive one. -->
+  <!-- svelte-ignore a11y_autofocus -->
+  <button
+    type="button"
+    class="btn btn-ghost"
+    data-testid="confirm-cancel"
+    autofocus={!shown?.challenge}
+    onclick={() => decide(false)}
+  >
+    {shown?.cancelLabel ?? cancelLabel}
+  </button>
+  <button
+    type="button"
+    class={["btn", shown?.danger ? "btn-error" : "btn-primary"]}
+    data-testid="confirm-accept"
+    data-danger={shown?.danger ? "true" : undefined}
+    disabled={!enabled}
+    onclick={() => decide(true)}
+  >
+    {shown?.confirmLabel ?? confirmLabel}
+  </button>
+{/snippet}
+
+<Modal
+  bind:this={modal}
+  title={shown?.title ?? ""}
+  class={["max-w-md", className]}
+  {closeLabel}
+  onclose={handleClose}
+  children={hasBody ? body : undefined}
+  {footer}
+/>

package/dist/confirm/Confirmer.svelte.d.ts

@@ -0,0 +1,45 @@
+import type { ClassValue } from "svelte/elements";
+import { type ConfirmManager } from "./confirm-manager.svelte.js";
+interface Props {
+    /** Queue to render. Defaults to the one behind the module-level `confirm` helper. */
+    manager?: ConfirmManager;
+    /** Extra classes for the box -- a wider cap for a long name. Not for the backdrop. */
+    class?: ClassValue;
+    /**
+     * Default label of the confirm action, for apps that are not in English. A call overrides it
+     * with `confirmLabel`; this is what every call that does not gets.
+     */
+    confirmLabel?: string;
+    /** Default label of the cancel action. Overridden per call by `cancelLabel`. */
+    cancelLabel?: string;
+    /** Accessible name of the close button, which never varies per call. */
+    closeLabel?: string;
+    /**
+     * Labels the challenge input. A function rather than a string because the challenge itself has
+     * to appear inside the sentence, and only the app knows where its language puts it.
+     */
+    challengeLabel?: (challenge: string) => string;
+}
+/**
+ * Renders a `ConfirmManager`'s queue as a modal question. Mount exactly one, unconditionally, in the
+ * app's root layout, next to `Toaster` and for the same reason: the call site that asks the question
+ * is somewhere else entirely.
+ *
+ * With no `manager` prop it renders the queue behind the module-level `confirm` helper, which is what
+ * lets any module in the app write the one line this exists for:
+ *
+ * ```ts
+ * if (!(await confirm({ title: `Delete ${night.name}?`, danger: true }))) return;
+ * await api.delete(`/nights/${night.id}`);
+ * ```
+ *
+ * The library ships no translations, so the four labels here are how an app localizes every confirm
+ * at once; a single call overrides any of them through its own options.
+ *
+ * Focus never lands on the confirm action. It opens on cancel, or on the challenge input when there
+ * is one, so a stray Enter can only ever cancel -- and in the challenge input Enter confirms solely
+ * when what has been typed already matches.
+ */
+declare const Confirmer: import("svelte").Component<Props, {}, "">;
+type Confirmer = ReturnType<typeof Confirmer>;
+export default Confirmer;

package/dist/confirm/challenge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether a typed value satisfies a confirm challenge.
+ *
+ * Both sides are trimmed at the ends and then compared exactly: case, accents, inner spacing and
+ * punctuation all have to match. The trim is there because the string being typed is almost always
+ * a name read or copied off the row above it, and a copy picks up a trailing space far more often
+ * than anyone means to type one. Folding case or accents on top of that would give away the one
+ * thing the gate exists for — making the hand slow down over the exact name of the thing that is
+ * about to be destroyed.
+ */
+export declare const matchesChallenge: (typed: string, challenge: string) => boolean;
+/**
+ * Whether the confirm action may be enabled for a request. A request with no challenge is always
+ * satisfied, so no caller has to branch on the option itself.
+ */
+export declare const challengeSatisfied: (challenge: string | undefined, typed: string) => boolean;

package/dist/confirm/challenge.js

@@ -0,0 +1,16 @@
+/**
+ * Whether a typed value satisfies a confirm challenge.
+ *
+ * Both sides are trimmed at the ends and then compared exactly: case, accents, inner spacing and
+ * punctuation all have to match. The trim is there because the string being typed is almost always
+ * a name read or copied off the row above it, and a copy picks up a trailing space far more often
+ * than anyone means to type one. Folding case or accents on top of that would give away the one
+ * thing the gate exists for — making the hand slow down over the exact name of the thing that is
+ * about to be destroyed.
+ */
+export const matchesChallenge = (typed, challenge) => typed.trim() === challenge.trim();
+/**
+ * Whether the confirm action may be enabled for a request. A request with no challenge is always
+ * satisfied, so no caller has to branch on the option itself.
+ */
+export const challengeSatisfied = (challenge, typed) => challenge === undefined || matchesChallenge(typed, challenge);

package/dist/confirm/confirm-manager.svelte.d.ts

@@ -0,0 +1,91 @@
+/** What a call to `confirm` asks. Everything but the title has a default. */
+export interface ConfirmOptions {
+    /** Names the dialog for assistive technology, and heads it visually. The question being asked. */
+    title: string;
+    /**
+     * The consequence, in prose, under the title. A string rather than a snippet on purpose: the
+     * whole point of the imperative API is that the options object is plain data, so it can be built
+     * in a store, an action or a `.ts` module that has no component scope to author a snippet in.
+     * A confirm that needs markup is a `Modal` composed by hand, and that path already exists.
+     */
+    description?: string;
+    /** Overrides the host's `confirmLabel` for this one call. */
+    confirmLabel?: string;
+    /** Overrides the host's `cancelLabel` for this one call. */
+    cancelLabel?: string;
+    /** Styles the confirm action as destructive. Does not change any behaviour. */
+    danger?: boolean;
+    /**
+     * A stronger gate: the confirm action stays disabled until this exact string has been typed.
+     * Reach for it when the action destroys something that took a while to build and the name is on
+     * screen to be read off — a project, a group, a production database. A blank or whitespace-only
+     * value is treated as no challenge at all, so `challenge={maybeName}` is safe.
+     */
+    challenge?: string;
+    /** Overrides the host's `challengeLabel` for this one call. Labels the challenge input. */
+    challengeLabel?: string;
+}
+/** A queued question. Produced by the manager; consumed by `Confirmer`. */
+export interface ConfirmRequest extends ConfirmOptions {
+    id: string;
+}
+/** What the host registers with `attach`: a nudge to put `current` on screen. */
+export type ConfirmPresenter = () => void;
+/**
+ * The queue behind `Confirmer`. Owns ids, ordering and the promise each call is waiting on.
+ *
+ * Most apps never touch this class: `confirm(...)` goes through the process-wide default manager
+ * and a single `<Confirmer />` near the app root renders it. Construct one explicitly to scope a
+ * queue to a subtree, or to give a test a manager it can throw away afterwards.
+ */
+export declare class ConfirmManager {
+    #private;
+    /** The request on screen, or null when nothing is being asked. */
+    get current(): ConfirmRequest | null;
+    /** How many calls are still waiting for an answer, the one on screen included. */
+    get pending(): number;
+    /** Ask, and resolve once the question has been answered — `true` only for the confirm action. */
+    confirm: (options: ConfirmOptions) => Promise<boolean>;
+    /**
+     * Answer the request on screen. The host's contract, called once the dialog has actually closed,
+     * so the awaiting caller resumes into a page with nothing on top of it.
+     *
+     * An id that is not the head is ignored, which is what makes a close event arriving after
+     * `cancelAll` harmless.
+     */
+    settle: (id: string, confirmed: boolean) => void;
+    /**
+     * Answer everything still waiting with `false` and empty the queue. Cancel is the safe answer,
+     * so this is what sign-out, a hard navigation or the last host unmounting should do — never
+     * leaving an `await confirm(...)` pending forever.
+     */
+    cancelAll: () => void;
+    /**
+     * Register a host. Returns the detach function, which is why `Confirmer` can hand this straight
+     * back out of an `$effect`.
+     *
+     * When the last host detaches every pending call is cancelled: a promise nobody can ever answer
+     * is worse than a `false`.
+     */
+    attach: (present: ConfirmPresenter) => (() => void);
+}
+export declare const createConfirmManager: () => ConfirmManager;
+/**
+ * The manager backing the module-level `confirm` helper.
+ *
+ * A singleton only in the browser. On the server every call hands back a fresh manager, because a
+ * module-level queue there is shared by every concurrent request.
+ */
+export declare const getDefaultConfirmManager: () => ConfirmManager;
+/**
+ * Ask the question, await the answer: a one-line replacement for the browser's own `confirm()`,
+ * from anywhere, with no context to plumb and no component to mount at the call site.
+ *
+ * ```ts
+ * if (!(await confirm({ title: "Delete this night?", danger: true }))) return;
+ * ```
+ *
+ * Resolves `true` only for the confirm action. Cancel, Escape, the close button, a click on the
+ * backdrop and the host unmounting all resolve `false`.
+ */
+export declare const confirm: (options: ConfirmOptions) => Promise<boolean>;

package/dist/confirm/confirm-manager.svelte.js

@@ -0,0 +1,149 @@
+import { untrack } from "svelte";
+let nextSequence = 0;
+const createRequestId = () => `confirm-${++nextSequence}`;
+/**
+ * The queue behind `Confirmer`. Owns ids, ordering and the promise each call is waiting on.
+ *
+ * Most apps never touch this class: `confirm(...)` goes through the process-wide default manager
+ * and a single `<Confirmer />` near the app root renders it. Construct one explicitly to scope a
+ * queue to a subtree, or to give a test a manager it can throw away afterwards.
+ */
+export class ConfirmManager {
+    /**
+     * Everything asked and not yet answered, oldest first. The head is the one on screen.
+     *
+     * Concurrent calls QUEUE rather than replacing or rejecting. Replacing would answer a question
+     * the user never saw, and answering it `false` is a lie about intent that a caller is free to
+     * log as "the user cancelled". Rejecting would throw at a call site written as
+     * `if (!(await confirm(...))) return;`, which is the shape this API exists to make safe. Waiting
+     * is the only rule under which no request is ever answered by anything but a person looking at
+     * it.
+     */
+    #queue = $state([]);
+    // Plain Map and Set, not the reactive ones: nothing renders from either. The rendered surface is
+    // the queue and nothing else.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #resolvers = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #presenters = new Set();
+    /** The request on screen, or null when nothing is being asked. */
+    get current() {
+        return this.#queue[0] ?? null;
+    }
+    /** How many calls are still waiting for an answer, the one on screen included. */
+    get pending() {
+        return this.#queue.length;
+    }
+    /** Ask, and resolve once the question has been answered — `true` only for the confirm action. */
+    confirm = (options) => {
+        const request = {
+            ...options,
+            challenge: options.challenge?.trim() ? options.challenge : undefined,
+            id: createRequestId(),
+        };
+        return new Promise((resolve) => {
+            this.#resolvers.set(request.id, resolve);
+            this.#queue.push(request);
+            // Only the head is ever on screen, so a call that lands behind one waits to be presented by
+            // the `settle` that retires the request in front of it.
+            if (this.#queue.length === 1)
+                this.#present();
+        });
+    };
+    /**
+     * Answer the request on screen. The host's contract, called once the dialog has actually closed,
+     * so the awaiting caller resumes into a page with nothing on top of it.
+     *
+     * An id that is not the head is ignored, which is what makes a close event arriving after
+     * `cancelAll` harmless.
+     */
+    settle = (id, confirmed) => {
+        if (this.#queue[0]?.id !== id)
+            return;
+        this.#queue.shift();
+        this.#resolvers.get(id)?.(confirmed);
+        this.#resolvers.delete(id);
+        if (this.#queue.length > 0)
+            this.#present();
+    };
+    /**
+     * Answer everything still waiting with `false` and empty the queue. Cancel is the safe answer,
+     * so this is what sign-out, a hard navigation or the last host unmounting should do — never
+     * leaving an `await confirm(...)` pending forever.
+     */
+    cancelAll = () => {
+        const dropped = this.#queue;
+        this.#queue = [];
+        for (const request of dropped) {
+            this.#resolvers.get(request.id)?.(false);
+            this.#resolvers.delete(request.id);
+        }
+    };
+    /**
+     * Register a host. Returns the detach function, which is why `Confirmer` can hand this straight
+     * back out of an `$effect`.
+     *
+     * When the last host detaches every pending call is cancelled: a promise nobody can ever answer
+     * is worse than a `false`.
+     */
+    attach = (present) => {
+        this.#presenters.add(present);
+        // Read without subscribing. `attach` is called from the host's `$effect`, and a dependency on
+        // the queue there would tear the host down and rebuild it on every question asked -- and the
+        // teardown cancels the very queue it had just read.
+        if (untrack(() => this.#queue.length) > 0)
+            this.#present();
+        return () => {
+            this.#presenters.delete(present);
+            if (this.#presenters.size === 0)
+                this.cancelAll();
+        };
+    };
+    /**
+     * Deferred by a microtask, always. Two of the three callers are already inside something that
+     * must not be re-entered: `attach` runs inside the host's `$effect`, where the synchronous flush
+     * that raises a `<dialog>` is an error, and `settle` runs inside the previous dialog's own close
+     * event. Deferring uniformly is one rule instead of three, and a microtask is invisible.
+     */
+    #present() {
+        queueMicrotask(() => {
+            if (this.#queue.length === 0)
+                return;
+            for (const present of this.#presenters)
+                present();
+        });
+    }
+}
+export const createConfirmManager = () => new ConfirmManager();
+let browserManager = null;
+/**
+ * The manager backing the module-level `confirm` helper.
+ *
+ * A singleton only in the browser. On the server every call hands back a fresh manager, because a
+ * module-level queue there is shared by every concurrent request.
+ */
+export const getDefaultConfirmManager = () => {
+    if (typeof document === "undefined")
+        return createConfirmManager();
+    browserManager ??= createConfirmManager();
+    return browserManager;
+};
+/**
+ * Ask the question, await the answer: a one-line replacement for the browser's own `confirm()`,
+ * from anywhere, with no context to plumb and no component to mount at the call site.
+ *
+ * ```ts
+ * if (!(await confirm({ title: "Delete this night?", danger: true }))) return;
+ * ```
+ *
+ * Resolves `true` only for the confirm action. Cancel, Escape, the close button, a click on the
+ * backdrop and the host unmounting all resolve `false`.
+ */
+export const confirm = (options) => {
+    // There is nobody to ask on the server, and "no" is the only safe answer to a question about
+    // destroying something. Answering rather than queueing is also what keeps a confirm reached
+    // during SSR from hanging the render forever.
+    if (typeof document === "undefined")
+        return Promise.resolve(false);
+    return getDefaultConfirmManager().confirm(options);
+};

package/dist/confirm/index.d.ts

@@ -0,0 +1,3 @@
+export { challengeSatisfied, matchesChallenge } from "./challenge.js";
+export { confirm, ConfirmManager, createConfirmManager, getDefaultConfirmManager, type ConfirmOptions, type ConfirmPresenter, type ConfirmRequest, } from "./confirm-manager.svelte.js";
+export { default as Confirmer } from "./Confirmer.svelte";

package/dist/confirm/index.js

@@ -0,0 +1,3 @@
+export { challengeSatisfied, matchesChallenge } from "./challenge.js";
+export { confirm, ConfirmManager, createConfirmManager, getDefaultConfirmManager, } from "./confirm-manager.svelte.js";
+export { default as Confirmer } from "./Confirmer.svelte";

package/dist/error.d.ts

@@ -0,0 +1,25 @@
+/** Anything that can receive an unexpected error: a console, a telemetry client, a test spy. */
+export type ErrorReporter = (error: unknown) => void;
+/**
+ * Install the app's reporter — Sentry, a logging endpoint, whatever the app already has.
+ *
+ * This is the whole point of routing reports through one function: the library and every app
+ * component keep calling `reportError`, and only the app decides where that lands. Passing `null`
+ * restores the console default, which is also what a test should do on teardown.
+ */
+export declare const setErrorReporter: (next: ErrorReporter | null) => void;
+/**
+ * The single reporting channel for unexpected errors.
+ *
+ * Wire it at catch points — `svelte:boundary`'s `onerror`, SvelteKit's `handleError` hooks, a
+ * handler that swallows a rejection — and never inside a component that merely *displays* a
+ * failure, or the same error gets reported once per render.
+ *
+ * ```svelte
+ * <svelte:boundary onerror={reportError}>
+ *   {@render children()}
+ *   {#snippet failed(_error, reset)}<ErrorDisplay {reset} />{/snippet}
+ * </svelte:boundary>
+ * ```
+ */
+export declare const reportError: (error: unknown) => void;

package/dist/error.js

@@ -0,0 +1,39 @@
+const consoleReporter = (error) => {
+    console.error(error);
+};
+let reporter = consoleReporter;
+/**
+ * Install the app's reporter — Sentry, a logging endpoint, whatever the app already has.
+ *
+ * This is the whole point of routing reports through one function: the library and every app
+ * component keep calling `reportError`, and only the app decides where that lands. Passing `null`
+ * restores the console default, which is also what a test should do on teardown.
+ */
+export const setErrorReporter = (next) => {
+    reporter = next ?? consoleReporter;
+};
+/**
+ * The single reporting channel for unexpected errors.
+ *
+ * Wire it at catch points — `svelte:boundary`'s `onerror`, SvelteKit's `handleError` hooks, a
+ * handler that swallows a rejection — and never inside a component that merely *displays* a
+ * failure, or the same error gets reported once per render.
+ *
+ * ```svelte
+ * <svelte:boundary onerror={reportError}>
+ *   {@render children()}
+ *   {#snippet failed(_error, reset)}<ErrorDisplay {reset} />{/snippet}
+ * </svelte:boundary>
+ * ```
+ */
+export const reportError = (error) => {
+    try {
+        reporter(error);
+    }
+    catch (reporterFailure) {
+        // A reporter that throws would replace the original failure with its own, inside a handler
+        // whose job was to contain a crash. The original error is the one worth keeping.
+        consoleReporter(error);
+        consoleReporter(reporterFailure);
+    }
+};