@viniaraujo68/plinth 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,49 @@
+import { type Snippet } from "svelte";
+import type { ClassValue, HTMLButtonAttributes } from "svelte/elements";
+type Props = HTMLButtonAttributes & {
+    children: Snippet;
+    content: Snippet;
+    /** Classes for the panel — the only part of this component the trigger's `class` cannot
+        reach, since the trigger is the root. */
+    panelClass?: ClassValue | null;
+    /** Whether the panel is open, however it got there. Bind to read it; the popover decides it. */
+    expanded?: boolean;
+    /** Hangs the panel just under the trigger at the trigger's width, as a field's list does. */
+    matchWidth?: boolean;
+};
+/**
+ * A button that toggles a panel through the native popover API, so clicking the trigger again,
+ * clicking outside, and pressing Escape all dismiss it without a single listener of our own. The
+ * button is the root: class, handlers and aria go straight onto it, and `panelClass` styles the
+ * panel.
+ *
+ * The popover itself — not a local flag — is the source of truth for open/closed; `aria-expanded`
+ * and the bindable `expanded` are read back from its `toggle` event. Content mounts just before the
+ * panel shows, however it was opened, and unmounts once the panel is really hidden, so an expensive
+ * menu costs nothing until it is used. An element inside it marked `autofocus` takes the focus as the
+ * panel shows, and closing the panel with the focus inside it hands the focus back to the trigger.
+ *
+ * `open()` and `close()` are exposed for `bind:this`, which is what a form inside the panel needs to
+ * dismiss itself after submitting. `open()` on a panel that is already open moves the focus back to
+ * its `autofocus` element.
+ *
+ * A panel that would run off the side of the screen is pulled back onto it and keeps half a rem from
+ * the edge, in both the anchored and the scripted placement; `--dropdown-edge` changes the distance.
+ * `matchWidth` hangs it instead just under the trigger and exactly as wide, for a trigger that is a
+ * field, the way the `Select` panel hangs under its control.
+ *
+ * ```svelte
+ * <Dropdown bind:this={menu} class="btn" panelClass="dropdown menu w-56 rounded-box bg-base-200 p-2">
+ * Actions
+ * {#snippet content()}
+ *   <li><button onclick={() => menu.close()}>Archive</button></li>
+ * {/snippet}
+ * </Dropdown>
+ * ```
+ */
+declare const Dropdown: import("svelte").Component<Props, {
+    open: () => void;
+    close: () => void;
+}, "expanded">;
+type Dropdown = ReturnType<typeof Dropdown>;
+export default Dropdown;

package/dist/components/ErrorDisplay.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  interface Props {
+    /** Wire the `reset` a `svelte:boundary` hands to its `failed` snippet. Omitted, no button. */
+    reset?: () => void;
+    title?: string;
+    message?: string;
+  }
+
+  let {
+    reset,
+    title = "Something went wrong",
+    message = "The application ran into an unexpected problem.",
+  }: Props = $props();
+</script>
+
+<!--
+@component
+Calm in-place fallback for a crashed subtree: it says what happened and offers the way out.
+
+It shows no technical detail on purpose — a stack is not source-mapped in production and the
+message was written for whoever wrote the code, not for whoever is reading the screen. Reporting
+is not this component's job either: it renders on every retry, so a report from here would be
+counted once per render. Wire `reportError` on the boundary's `onerror` instead.
+
+```svelte
+<svelte:boundary onerror={reportError}>
+  {@render children()}
+  {#snippet failed(_error, reset)}<ErrorDisplay {reset} />{/snippet}
+</svelte:boundary>
+```
+-->
+
+<div
+  class="flex h-full w-full flex-col items-center justify-center gap-2 p-8 text-center"
+  role="alert"
+>
+  <svg
+    class="size-12 text-base-content/40"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
+    <path d="M12 9v4" />
+    <path d="M12 17h.01" />
+  </svg>
+  <p class="text-xs font-medium tracking-widest text-base-content/55 uppercase">Error</p>
+  <p class="text-xl font-semibold">{title}</p>
+  <p class="max-w-md text-sm text-base-content/60">{message}</p>
+  {#if reset}
+    <div class="mt-4">
+      <button type="button" class="btn btn-primary" onclick={reset}>Try again</button>
+    </div>
+  {/if}
+</div>

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

@@ -0,0 +1,24 @@
+interface Props {
+    /** Wire the `reset` a `svelte:boundary` hands to its `failed` snippet. Omitted, no button. */
+    reset?: () => void;
+    title?: string;
+    message?: string;
+}
+/**
+ * Calm in-place fallback for a crashed subtree: it says what happened and offers the way out.
+ *
+ * It shows no technical detail on purpose — a stack is not source-mapped in production and the
+ * message was written for whoever wrote the code, not for whoever is reading the screen. Reporting
+ * is not this component's job either: it renders on every retry, so a report from here would be
+ * counted once per render. Wire `reportError` on the boundary's `onerror` instead.
+ *
+ * ```svelte
+ * <svelte:boundary onerror={reportError}>
+ * {@render children()}
+ * {#snippet failed(_error, reset)}<ErrorDisplay {reset} />{/snippet}
+ * </svelte:boundary>
+ * ```
+ */
+declare const ErrorDisplay: import("svelte").Component<Props, {}, "">;
+type ErrorDisplay = ReturnType<typeof ErrorDisplay>;
+export default ErrorDisplay;

package/dist/components/ErrorPage.svelte

@@ -0,0 +1,119 @@
+<script lang="ts">
+  interface Props {
+    /** HTTP status behind the failure. 404 gets its own wording and icon. */
+    status: number;
+    /** Message from `error(status, message)`. Ignored for a 404, where the path says more. */
+    message?: string;
+    /** Path that was asked for. Shown only on a 404. */
+    pathname?: string;
+    /** Where "back to start" goes. Pass `resolve("/")` from an app with a base path. */
+    homeHref?: string;
+    /** The chip above the heading, given the status. */
+    statusLabel?: (status: number) => string;
+    /** Heading of a 404. */
+    notFoundTitle?: string;
+    /**
+     * Body of a 404, given the path when one was passed. Left out, the English sentence renders
+     * with the address in a monospace run of its own, which a returned string cannot carry.
+     */
+    notFoundBody?: (pathname: string | undefined) => string;
+    /** Heading of every other status. */
+    errorTitle?: string;
+    /** Body of every other status, used when no `message` was passed. */
+    errorBody?: string;
+    /** Label of the link home. */
+    homeLabel?: string;
+    /** Label of the reload button, which a 404 does not offer. */
+    reloadLabel?: string;
+  }
+
+  let {
+    status,
+    message,
+    pathname,
+    homeHref = "/",
+    statusLabel = (status: number) => `Error ${status}`,
+    notFoundTitle = "Page not found",
+    notFoundBody,
+    errorTitle = "Something went wrong",
+    errorBody = "The application ran into an unexpected problem.",
+    homeLabel = "Back to start",
+    reloadLabel = "Reload",
+  }: Props = $props();
+
+  const notFound = $derived(status === 404);
+</script>
+
+<!--
+@component
+Route-level error page: status-aware, human-facing, rendered from an app's `+error.svelte`.
+
+Everything it shows arrives as a prop rather than being read from `$app/state` inside the
+component. That keeps it renderable — and testable — outside a SvelteKit navigation, and it keeps
+the choice of what to reveal at the app's own `+error.svelte`, which is where the app can tell an
+intentional `error(403, "...")` message apart from one it would rather not print.
+
+Every word of the copy is a prop with an English default, because the library ships no
+translations: `statusLabel`, `notFoundTitle`, `notFoundBody`, `errorTitle`, `errorBody`,
+`homeLabel` and `reloadLabel`. `message` still wins over `errorBody` whenever the app passed one.
+
+```svelte
+<script lang="ts">
+  import { page } from "$app/state";
+  import { resolve } from "$app/paths";
+</script>
+
+<ErrorPage status={page.status} message={page.error?.message} pathname={page.url.pathname}
+  homeHref={resolve("/")} />
+```
+-->
+
+<div class="flex h-full w-full flex-col items-center justify-center gap-2 p-8 text-center">
+  <svg
+    class="size-12 text-base-content/40"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    {#if notFound}
+      <path d="m16.24 7.76-1.8 5.41a2 2 0 0 1-1.27 1.27l-5.41 1.8 1.8-5.41a2 2 0 0 1 1.27-1.27z" />
+      <circle cx="12" cy="12" r="10" />
+    {:else}
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
+      <path d="M12 9v4" />
+      <path d="M12 17h.01" />
+    {/if}
+  </svg>
+  <p class="text-xs font-medium tracking-widest text-base-content/55 uppercase">
+    {statusLabel(status)}
+  </p>
+  <h1 class="text-xl font-semibold">
+    {notFound ? notFoundTitle : errorTitle}
+  </h1>
+  <p class="max-w-md text-sm break-words text-base-content/60">
+    {#if notFound}
+      {#if notFoundBody}
+        {notFoundBody(pathname)}
+      {:else}
+        The address {#if pathname}<span class="font-mono break-all">{pathname}</span>{:else}you
+          asked for{/if} does not exist, or has moved.
+      {/if}
+    {:else}
+      {message ?? errorBody}
+    {/if}
+  </p>
+  <div class="mt-4 flex gap-2">
+    <!-- The link is resolved by the app, which is the side that knows its route ids and its base
+         path; the library only renders what it was handed. -->
+    <!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
+    <a class="btn btn-primary" href={homeHref}>{homeLabel}</a>
+    {#if !notFound}
+      <!-- A reload is worth offering only for a failure that might not repeat; a 404 will. -->
+      <button type="button" class="btn" onclick={() => location.reload()}>{reloadLabel}</button>
+    {/if}
+  </div>
+</div>

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

@@ -0,0 +1,52 @@
+interface Props {
+    /** HTTP status behind the failure. 404 gets its own wording and icon. */
+    status: number;
+    /** Message from `error(status, message)`. Ignored for a 404, where the path says more. */
+    message?: string;
+    /** Path that was asked for. Shown only on a 404. */
+    pathname?: string;
+    /** Where "back to start" goes. Pass `resolve("/")` from an app with a base path. */
+    homeHref?: string;
+    /** The chip above the heading, given the status. */
+    statusLabel?: (status: number) => string;
+    /** Heading of a 404. */
+    notFoundTitle?: string;
+    /**
+     * Body of a 404, given the path when one was passed. Left out, the English sentence renders
+     * with the address in a monospace run of its own, which a returned string cannot carry.
+     */
+    notFoundBody?: (pathname: string | undefined) => string;
+    /** Heading of every other status. */
+    errorTitle?: string;
+    /** Body of every other status, used when no `message` was passed. */
+    errorBody?: string;
+    /** Label of the link home. */
+    homeLabel?: string;
+    /** Label of the reload button, which a 404 does not offer. */
+    reloadLabel?: string;
+}
+/**
+ * Route-level error page: status-aware, human-facing, rendered from an app's `+error.svelte`.
+ *
+ * Everything it shows arrives as a prop rather than being read from `$app/state` inside the
+ * component. That keeps it renderable — and testable — outside a SvelteKit navigation, and it keeps
+ * the choice of what to reveal at the app's own `+error.svelte`, which is where the app can tell an
+ * intentional `error(403, "...")` message apart from one it would rather not print.
+ *
+ * Every word of the copy is a prop with an English default, because the library ships no
+ * translations: `statusLabel`, `notFoundTitle`, `notFoundBody`, `errorTitle`, `errorBody`,
+ * `homeLabel` and `reloadLabel`. `message` still wins over `errorBody` whenever the app passed one.
+ *
+ * ```svelte
+ * <script lang="ts">
+ * import { page } from "$app/state";
+ * import { resolve } from "$app/paths";
+ * </script>
+ *
+ * <ErrorPage status={page.status} message={page.error?.message} pathname={page.url.pathname}
+ * homeHref={resolve("/")} />
+ * ```
+ */
+declare const ErrorPage: import("svelte").Component<Props, {}, "">;
+type ErrorPage = ReturnType<typeof ErrorPage>;
+export default ErrorPage;

package/dist/components/JsonInput.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+  import type { Attachment } from "svelte/attachments";
+  import type { ClassValue, HTMLTextareaAttributes } from "svelte/elements";
+  import { formatJsonText, parseJsonText } from "./json-text.js";
+
+  type Props = Omit<
+    HTMLTextareaAttributes,
+    "bind:value" | "children" | "class" | "onblur" | "required" | "value"
+  > & {
+    /** The text being edited. Bindable: the field holds text, never a parsed object. */
+    value?: string;
+    /** `true` while the text does not parse. Bind it to gate a submit. */
+    invalid?: boolean;
+    /** The field's visible label. */
+    label?: string;
+    /** Reformats the text on blur when it parses. Text that does not parse is left as typed. */
+    formatOnBlur?: boolean;
+    /** Rejects blank text, in `invalid` and in the surrounding form's validation. */
+    required?: boolean;
+    /** Leads the error shown under the field; the parser's own message follows it. */
+    invalidLabel?: string;
+    /** The error for blank text when `required`. */
+    requiredLabel?: string;
+    /** Classes for the whole field. The textarea is where every other attribute goes. */
+    class?: ClassValue;
+  };
+
+  let {
+    value = $bindable(""),
+    invalid = $bindable(false),
+    label,
+    formatOnBlur = false,
+    required = false,
+    invalidLabel = "Invalid JSON",
+    requiredLabel = "Required",
+    rows = 12,
+    class: className,
+    ...rest
+  }: Props = $props();
+
+  const uid = $props.id();
+  const fieldId = $derived(rest.id ?? `plinth-json-input-${uid}`);
+  const errorId = `plinth-json-input-${uid}-error`;
+
+  let touched = $state(false);
+
+  const result = $derived(parseJsonText(value, { required, requiredMessage: requiredLabel }));
+  const message = $derived(result.valid ? "" : `${invalidLabel}: ${result.error}`);
+  const showError = $derived(touched && !result.valid);
+
+  $effect(() => {
+    const next = !result.valid;
+    if (invalid !== next) invalid = next;
+  });
+
+  const validity: Attachment<HTMLTextAreaElement> = (field) => {
+    field.setCustomValidity(message);
+  };
+
+  const onblur = () => {
+    touched = true;
+    if (formatOnBlur) value = formatJsonText(value);
+  };
+</script>
+
+<!--
+@component
+A JSON text field: it parses as you type, reports whether the text parses through a bindable
+`invalid`, and can reformat the document on blur.
+
+It holds text, never a parsed object. A document is invalid for most of the time it is being
+edited, and holding the object would throw away what was typed. Bind `invalid` to gate a submit,
+then parse the text once when sending, with `parseJsonText` or `JSON.parse`.
+
+The error waits for the first blur, since every document is invalid while its first brace is being
+typed, and it carries the parser's own message, which names where the document broke. The same
+message is the textarea's custom validity, so a surrounding form will not submit text that does not
+parse.
+
+```svelte
+<JsonInput bind:value={text} bind:invalid label="Settings" formatOnBlur required />
+<button disabled={invalid} onclick={() => save(JSON.parse(text))}>Save</button>
+```
+-->
+
+<div class={["plinth-json-input fieldset w-full", className]}>
+  {#if label}
+    <label class="fieldset-legend" for={fieldId}>{label}</label>
+  {/if}
+  <textarea
+    {...rest}
+    {@attach validity}
+    id={fieldId}
+    class={["textarea w-full font-mono text-xs", showError && "textarea-error"]}
+    {rows}
+    {required}
+    spellcheck="false"
+    aria-invalid={showError}
+    aria-describedby={[rest["aria-describedby"], showError && errorId].filter(Boolean).join(" ") ||
+      undefined}
+    bind:value
+    {onblur}></textarea>
+  {#if showError}
+    <p id={errorId} class="label whitespace-normal text-error">{message}</p>
+  {/if}
+</div>

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

@@ -0,0 +1,40 @@
+import type { ClassValue, HTMLTextareaAttributes } from "svelte/elements";
+type Props = Omit<HTMLTextareaAttributes, "bind:value" | "children" | "class" | "onblur" | "required" | "value"> & {
+    /** The text being edited. Bindable: the field holds text, never a parsed object. */
+    value?: string;
+    /** `true` while the text does not parse. Bind it to gate a submit. */
+    invalid?: boolean;
+    /** The field's visible label. */
+    label?: string;
+    /** Reformats the text on blur when it parses. Text that does not parse is left as typed. */
+    formatOnBlur?: boolean;
+    /** Rejects blank text, in `invalid` and in the surrounding form's validation. */
+    required?: boolean;
+    /** Leads the error shown under the field; the parser's own message follows it. */
+    invalidLabel?: string;
+    /** The error for blank text when `required`. */
+    requiredLabel?: string;
+    /** Classes for the whole field. The textarea is where every other attribute goes. */
+    class?: ClassValue;
+};
+/**
+ * A JSON text field: it parses as you type, reports whether the text parses through a bindable
+ * `invalid`, and can reformat the document on blur.
+ *
+ * It holds text, never a parsed object. A document is invalid for most of the time it is being
+ * edited, and holding the object would throw away what was typed. Bind `invalid` to gate a submit,
+ * then parse the text once when sending, with `parseJsonText` or `JSON.parse`.
+ *
+ * The error waits for the first blur, since every document is invalid while its first brace is being
+ * typed, and it carries the parser's own message, which names where the document broke. The same
+ * message is the textarea's custom validity, so a surrounding form will not submit text that does not
+ * parse.
+ *
+ * ```svelte
+ * <JsonInput bind:value={text} bind:invalid label="Settings" formatOnBlur required />
+ * <button disabled={invalid} onclick={() => save(JSON.parse(text))}>Save</button>
+ * ```
+ */
+declare const JsonInput: import("svelte").Component<Props, {}, "invalid" | "value">;
+type JsonInput = ReturnType<typeof JsonInput>;
+export default JsonInput;