@viniaraujo68/plinth 0.0.0-stage → 0.3.0

package/dist/components/Modal.svelte

@@ -0,0 +1,187 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import Dialog from "./Dialog.svelte";
+
+  interface Props {
+    /** Names the dialog for assistive technology, and heads it visually. */
+    title: string;
+    /**
+     * The scrollable body. Optional: a dialog whose whole question fits in its title -- a confirm
+     * is the usual one -- would otherwise render an empty padded strip between the header and the
+     * actions. Omitted, there is no body element at all, and the header's own rule becomes the
+     * single divider above the footer.
+     */
+    children?: Snippet;
+    /** Actions, laid out end-aligned under a divider. Nothing is rendered when it is omitted. */
+    footer?: Snippet;
+    /** Extra classes for the box -- width, max-width, a taller cap. Not for the backdrop. */
+    class?: ClassValue;
+    /** Accessible name of the close button. A prop because the library ships no translations. */
+    closeLabel?: string;
+    /**
+     * Whether the modal can be dismissed without a decision. `false` removes the close button and
+     * blocks both Escape and the click outside, which makes the footer the only way out -- so a
+     * modal that sets it owes the user an explicit action there.
+     */
+    dismissible?: boolean;
+    /** Called once the modal has actually closed, whichever way it was closed. */
+    onclose?: () => void;
+  }
+
+  let {
+    title,
+    children,
+    footer,
+    class: className,
+    closeLabel = "Close",
+    dismissible = true,
+    onclose,
+  }: Props = $props();
+
+  const titleId = $props.id();
+
+  let dialog = $state<Dialog>();
+  let box = $state<HTMLDivElement>();
+  let closeButton = $state<HTMLButtonElement>();
+  let open = $state(false);
+  let pressedOutside = false;
+
+  /** Open the modal. The content is mounted by this call, not before it. */
+  export function show() {
+    open = true;
+    dialog?.show();
+
+    // The browser's initial focus lands on the first focusable descendant, which is the ✕ --
+    // opening a dialog on "close" is a poor first move, and it tells a screen reader nothing about
+    // what was opened. Anything the content marks `autofocus` is chosen ahead of the button, so
+    // only this fallback needs correcting, and the box is the target the dialog pattern names.
+    if (closeButton && document.activeElement === closeButton) box?.focus();
+  }
+
+  /** Close the modal. `onclose` fires after the element reports itself closed. */
+  export function close() {
+    dialog?.close();
+  }
+
+  $effect(() => {
+    if (!open) return;
+
+    // A native modal makes the rest of the document inert, but it does not stop it from SCROLLING
+    // behind the backdrop. Saving the inline value instead of toggling a class is what lets a
+    // modal opened over another modal put back exactly what it found. Compensating for the
+    // scrollbar that disappears with it is the app's call, through `scrollbar-gutter: stable`.
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+
+    return () => {
+      document.body.style.overflow = previousOverflow;
+    };
+  });
+</script>
+
+<!--
+@component
+A dialog with chrome: a title, a close button, an optional scrollable body and an optional footer.
+
+Composition over `Dialog`, so modality, the focus trap, Escape and returning focus to the opener
+stay the browser's job. What is added on top is everything a native modal leaves to the page, and
+all of it shows up first on a phone: the background is kept from scrolling behind the backdrop,
+the box is capped in `dvh` so the on-screen keyboard cannot push the submit button out of reach,
+the close button is a full 44px touch target, and the body scrolls under a header that does not.
+
+The content is mounted on `show()` and unmounted after it closes, so an expensive form inside a
+rarely opened modal costs nothing until it is opened.
+
+```svelte
+<script lang="ts">
+  let editor = $state<Modal>();
+</script>
+
+<button onclick={() => editor?.show()}>Edit</button>
+
+<Modal bind:this={editor} title="Edit profile" class="max-w-lg">
+  <form id="profile">...</form>
+
+  {#snippet footer()}
+    <button class="btn" onclick={() => editor?.close()}>Cancel</button>
+    <button class="btn btn-primary" form="profile">Save</button>
+  {/snippet}
+</Modal>
+```
+-->
+
+<Dialog
+  bind:this={dialog}
+  class="modal motion-reduce:transition-none"
+  aria-labelledby={titleId}
+  onclose={() => {
+    open = false;
+    onclose?.();
+  }}
+  oncancel={(event) => {
+    if (!dismissible) event.preventDefault();
+  }}
+  onpointerdown={(event) => {
+    // A press that starts inside the box and ends outside it still produces a click on the dialog,
+    // because the click target is the common ancestor of the two. Selecting text and dragging past
+    // the edge would close the modal and lose the form, so the press has to have started outside.
+    pressedOutside = event.target === event.currentTarget;
+  }}
+  onclick={(event) => {
+    if (dismissible && pressedOutside && event.target === event.currentTarget) close();
+  }}
+>
+  <div
+    bind:this={box}
+    tabindex="-1"
+    class={[
+      // dvh, not vh: the visible viewport shrinks when the on-screen keyboard opens, and a `vh`
+      // cap would leave the footer under it.
+      "modal-box flex max-h-[calc(100dvh-40px)] flex-col overflow-hidden p-0 motion-reduce:transition-none",
+      className,
+    ]}
+  >
+    <header
+      class="flex flex-none items-start justify-between gap-3 border-b border-base-content/10 px-6 py-4"
+    >
+      <h2 id={titleId} class="text-lg leading-7 font-semibold">{title}</h2>
+      {#if dismissible}
+        <button
+          bind:this={closeButton}
+          type="button"
+          class="btn -my-2 -mr-3 size-11 shrink-0 btn-ghost text-base"
+          aria-label={closeLabel}
+          onclick={close}
+        >
+          <!-- The negative margins let the 44px target eat into the header padding instead of
+               growing the header by the difference. -->
+          ✕
+        </button>
+      {/if}
+    </header>
+
+    {#if children}
+      <!-- `min-h-0` is load-bearing: a flex child defaults to `min-height: auto` and refuses to
+           shrink below its content, which would push the box past its own max-height and take the
+           scrolling with it. `overscroll-contain` keeps a flick at the end of a long form from
+           scrolling the page underneath. -->
+      <div class="min-h-0 flex-1 overflow-y-auto overscroll-contain px-6 py-5">
+        {@render children()}
+      </div>
+    {/if}
+
+    {#if footer}
+      <!-- Two adjacent rules read as one thick line, so with no body between them the footer drops
+           its own and lets the header's separate the title from the actions. -->
+      <footer
+        class={[
+          "flex flex-none flex-wrap justify-end gap-2 px-6 py-4",
+          children && "border-t border-base-content/10",
+        ]}
+      >
+        {@render footer()}
+      </footer>
+    {/if}
+  </div>
+</Dialog>

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

@@ -0,0 +1,62 @@
+import type { Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+interface Props {
+    /** Names the dialog for assistive technology, and heads it visually. */
+    title: string;
+    /**
+     * The scrollable body. Optional: a dialog whose whole question fits in its title -- a confirm
+     * is the usual one -- would otherwise render an empty padded strip between the header and the
+     * actions. Omitted, there is no body element at all, and the header's own rule becomes the
+     * single divider above the footer.
+     */
+    children?: Snippet;
+    /** Actions, laid out end-aligned under a divider. Nothing is rendered when it is omitted. */
+    footer?: Snippet;
+    /** Extra classes for the box -- width, max-width, a taller cap. Not for the backdrop. */
+    class?: ClassValue;
+    /** Accessible name of the close button. A prop because the library ships no translations. */
+    closeLabel?: string;
+    /**
+     * Whether the modal can be dismissed without a decision. `false` removes the close button and
+     * blocks both Escape and the click outside, which makes the footer the only way out -- so a
+     * modal that sets it owes the user an explicit action there.
+     */
+    dismissible?: boolean;
+    /** Called once the modal has actually closed, whichever way it was closed. */
+    onclose?: () => void;
+}
+/**
+ * A dialog with chrome: a title, a close button, an optional scrollable body and an optional footer.
+ *
+ * Composition over `Dialog`, so modality, the focus trap, Escape and returning focus to the opener
+ * stay the browser's job. What is added on top is everything a native modal leaves to the page, and
+ * all of it shows up first on a phone: the background is kept from scrolling behind the backdrop,
+ * the box is capped in `dvh` so the on-screen keyboard cannot push the submit button out of reach,
+ * the close button is a full 44px touch target, and the body scrolls under a header that does not.
+ *
+ * The content is mounted on `show()` and unmounted after it closes, so an expensive form inside a
+ * rarely opened modal costs nothing until it is opened.
+ *
+ * ```svelte
+ * <script lang="ts">
+ * let editor = $state<Modal>();
+ * </script>
+ *
+ * <button onclick={() => editor?.show()}>Edit</button>
+ *
+ * <Modal bind:this={editor} title="Edit profile" class="max-w-lg">
+ * <form id="profile">...</form>
+ *
+ * {#snippet footer()}
+ *   <button class="btn" onclick={() => editor?.close()}>Cancel</button>
+ *   <button class="btn btn-primary" form="profile">Save</button>
+ * {/snippet}
+ * </Modal>
+ * ```
+ */
+declare const Modal: import("svelte").Component<Props, {
+    show: () => void;
+    close: () => void;
+}, "">;
+type Modal = ReturnType<typeof Modal>;
+export default Modal;

package/dist/components/MultiSelect.svelte

@@ -0,0 +1,256 @@
+<script lang="ts" generics="O extends SelectOption = SelectOption">
+  import type { Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import Dropdown from "./Dropdown.svelte";
+  import Listbox from "./Listbox.svelte";
+  import type { SelectOption } from "./select.js";
+
+  interface Props {
+    /** The rows, in the order they are listed. `value` is the key, so it has to be unique. */
+    options: readonly O[];
+    /** The picked values, in the order they were picked. Bindable, and reported through `onchange`. */
+    value?: string[];
+    onchange?: (value: string[]) => void;
+    /** Shown in the field while nothing is picked. */
+    placeholder?: string;
+    /** What the search reads for a row. Defaults to its label. */
+    searchText?: (option: O) => string;
+    searchPlaceholder?: string;
+    /** Shown in place of the list when the search matches nothing. */
+    emptyLabel?: string;
+    /**
+     * Shows a spinner, a placeholder chip for each pick whose option has not arrived yet, and
+     * `loadingLabel` in an empty list.
+     */
+    loading?: boolean;
+    loadingLabel?: string;
+    disabled?: boolean;
+    /** Blocks the surrounding form's submission while nothing is picked. */
+    required?: boolean;
+    /** Submits every picked value under this name with a surrounding `<form>`. */
+    name?: string;
+    /** The field's id, for a `<label for>`. */
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** Accessible name of a chip's remove button. */
+    removeLabel?: (label: string) => string;
+    /** Renders a chip's content in place of its label. */
+    chip?: Snippet<[O]>;
+    /**
+     * Renders a row in place of its label. The row is already a `role="option"` button, so the
+     * snippet must not hold buttons, links or anything else interactive.
+     */
+    option?: Snippet<[O]>;
+    /** Classes for the field — width, margins. */
+    class?: ClassValue;
+  }
+
+  let {
+    options,
+    value = $bindable([]),
+    onchange,
+    placeholder = "Select…",
+    searchText,
+    searchPlaceholder,
+    emptyLabel,
+    loading = false,
+    loadingLabel,
+    disabled = false,
+    required = false,
+    name,
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby,
+    removeLabel = (label) => `Remove ${label}`,
+    chip,
+    option,
+    class: className,
+  }: Props = $props();
+
+  const uid = $props.id();
+  const triggerId = $derived(id ?? `plinth-multiselect-${uid}`);
+  const listboxId = `plinth-multiselect-${uid}-listbox`;
+
+  let dropdown = $state<ReturnType<typeof Dropdown>>();
+  let isOpen = $state(false);
+
+  const picks = $derived([...new Set(value)]);
+  const byValue = $derived(new Map(options.map((candidate) => [candidate.value, candidate])));
+  const isLocked = (picked: string) => byValue.get(picked)?.disabled === true;
+
+  const commit = (next: string[]) => {
+    value = next;
+    onchange?.(next);
+  };
+
+  const remove = (picked: string) => commit(picks.filter((other) => other !== picked));
+
+  const toggle = (picked: O) => {
+    if (picks.includes(picked.value)) remove(picked.value);
+    else commit([...picks, picked.value]);
+  };
+
+  const focusField = () => document.getElementById(triggerId)?.focus({ preventScroll: true });
+
+  const onkeydown = (event: KeyboardEvent) => {
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      dropdown?.open();
+    } else if (event.key === "Backspace" && !event.repeat) {
+      const last = picks.findLast((picked) => !isLocked(picked));
+      if (last === undefined) return;
+      event.preventDefault();
+      remove(last);
+    }
+  };
+</script>
+
+<!--
+@component
+Picks several options. The field shows the picks as removable chips, in the order they were made;
+opening it lists every option under a search box, with the picked ones checked, and Enter or a
+click checks or unchecks a row without closing the list. The search folds case and accents, and a
+row matches when it contains every word typed.
+
+A disabled option cannot be checked or unchecked: picked, it is locked, and its chip has no ✕. On
+the field, the arrows open the list and Backspace removes the last pick that is not locked. The
+chips' remove buttons are not Tab stops; from the keyboard, a pick is unchecked in the list.
+
+It is a `Dropdown` with a `Listbox` inside, so the focus moves into the search box as the list
+opens and comes back to the field as it closes. Shift+Tab from the search box reaches the field
+with the list still open, and an arrow key sends the focus back in.
+
+`required` blocks the surrounding form while nothing is picked, and `name` submits one entry per
+pick.
+
+```svelte
+<MultiSelect options={people} bind:value={members} aria-label="Members">
+  {#snippet chip(person)}{person.label}{/snippet}
+</MultiSelect>
+```
+-->
+
+<div
+  class={[
+    "plinth-multiselect select relative flex h-auto min-h-11 w-full flex-wrap items-center gap-1 py-1",
+    picks.length > 0 && "ps-1.5",
+    disabled && "cursor-not-allowed border-base-200 bg-base-200 text-base-content/40",
+    className,
+  ]}
+  onfocusout={(event) => {
+    const next = event.relatedTarget;
+    if (next instanceof Node && !event.currentTarget.contains(next)) dropdown?.close();
+  }}
+>
+  {#each picks as picked (picked)}
+    {@const pickedOption = byValue.get(picked)}
+    {@const label = pickedOption?.label ?? picked}
+    {#if !pickedOption && loading}
+      <span class="h-6.5 w-20 skeleton rounded-field"></span>
+    {:else}
+      <span
+        class="pointer-events-none relative z-1 inline-flex max-w-full items-center gap-1 rounded-field border border-base-content/15 bg-base-200 py-0.5 ps-2 pe-1 text-sm"
+      >
+        <span class="min-w-0 truncate">
+          {#if pickedOption && chip}{@render chip(pickedOption)}{:else}{label}{/if}
+        </span>
+        {#if !disabled && !isLocked(picked)}
+          <button
+            type="button"
+            tabindex="-1"
+            class="pointer-events-auto relative flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-full text-base-content/50 after:absolute after:-inset-1.5 hover:bg-base-content/10 hover:text-base-content"
+            aria-label={removeLabel(label)}
+            onclick={() => {
+              remove(picked);
+              focusField();
+            }}
+          >
+            <svg
+              class="size-3"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2.5"
+              stroke-linecap="round"
+              aria-hidden="true"
+            >
+              <path d="M18 6 6 18M6 6l12 12" />
+            </svg>
+          </button>
+        {/if}
+      </span>
+    {/if}
+  {:else}
+    <span class="min-w-0 truncate text-base-content/50">{placeholder}</span>
+  {/each}
+
+  {#if loading}
+    <span class="loading ms-auto loading-xs self-center loading-spinner"></span>
+  {/if}
+
+  <Dropdown
+    bind:this={dropdown}
+    bind:expanded={isOpen}
+    id={triggerId}
+    role="combobox"
+    class="absolute inset-0 cursor-pointer rounded-field focus-visible:outline-none disabled:cursor-not-allowed"
+    panelClass="rounded-box border border-base-content/10 bg-base-100 p-1 whitespace-normal text-base-content shadow-lg"
+    matchWidth
+    {disabled}
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledby}
+    aria-haspopup="listbox"
+    aria-controls={isOpen ? listboxId : undefined}
+    {onkeydown}
+  >
+    <span class="sr-only">
+      {picks.flatMap((picked) => byValue.get(picked)?.label ?? (loading ? [] : picked)).join(", ")}
+    </span>
+
+    {#snippet content()}
+      <Listbox
+        id={listboxId}
+        {options}
+        value={picks}
+        onpick={toggle}
+        searchable
+        {searchText}
+        {searchPlaceholder}
+        {emptyLabel}
+        {loading}
+        {loadingLabel}
+        autofocus
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledby}
+        {option}
+      />
+    {/snippet}
+  </Dropdown>
+
+  {#if name}
+    {#each picks as picked (picked)}
+      <input type="hidden" {name} value={picked} {disabled} />
+    {/each}
+  {/if}
+
+  {#if required}
+    <input
+      class="sr-only"
+      tabindex="-1"
+      aria-hidden="true"
+      {disabled}
+      {required}
+      value={picks.join(",")}
+      onfocus={focusField}
+    />
+  {/if}
+</div>
+
+<style>
+  .plinth-multiselect:has(> :global([aria-expanded="true"])) {
+    background-image:
+      linear-gradient(135deg, #0000 50%, currentColor 50%),
+      linear-gradient(45deg, currentColor 50%, #0000 50%);
+  }
+</style>

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

@@ -0,0 +1,89 @@
+import type { Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import type { SelectOption } from "./select.js";
+declare function $$render<O extends SelectOption = SelectOption>(): {
+    props: {
+        /** The rows, in the order they are listed. `value` is the key, so it has to be unique. */
+        options: readonly O[];
+        /** The picked values, in the order they were picked. Bindable, and reported through `onchange`. */
+        value?: string[];
+        onchange?: (value: string[]) => void;
+        /** Shown in the field while nothing is picked. */
+        placeholder?: string;
+        /** What the search reads for a row. Defaults to its label. */
+        searchText?: (option: O) => string;
+        searchPlaceholder?: string;
+        /** Shown in place of the list when the search matches nothing. */
+        emptyLabel?: string;
+        /**
+         * Shows a spinner, a placeholder chip for each pick whose option has not arrived yet, and
+         * `loadingLabel` in an empty list.
+         */
+        loading?: boolean;
+        loadingLabel?: string;
+        disabled?: boolean;
+        /** Blocks the surrounding form's submission while nothing is picked. */
+        required?: boolean;
+        /** Submits every picked value under this name with a surrounding `<form>`. */
+        name?: string;
+        /** The field's id, for a `<label for>`. */
+        id?: string;
+        "aria-label"?: string;
+        "aria-labelledby"?: string;
+        /** Accessible name of a chip's remove button. */
+        removeLabel?: (label: string) => string;
+        /** Renders a chip's content in place of its label. */
+        chip?: Snippet<[O]>;
+        /**
+         * Renders a row in place of its label. The row is already a `role="option"` button, so the
+         * snippet must not hold buttons, links or anything else interactive.
+         */
+        option?: Snippet<[O]>;
+        /** Classes for the field — width, margins. */
+        class?: ClassValue;
+    };
+    exports: {};
+    bindings: "value";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<O extends SelectOption = SelectOption> {
+    props(): ReturnType<typeof $$render<O>>['props'];
+    events(): ReturnType<typeof $$render<O>>['events'];
+    slots(): ReturnType<typeof $$render<O>>['slots'];
+    bindings(): "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <O extends SelectOption = SelectOption>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<O>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<O>['props']>, ReturnType<__sveltets_Render<O>['events']>, ReturnType<__sveltets_Render<O>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<O>['bindings']>;
+    } & ReturnType<__sveltets_Render<O>['exports']>;
+    <O extends SelectOption = SelectOption>(internal: unknown, props: ReturnType<__sveltets_Render<O>['props']> & {}): ReturnType<__sveltets_Render<O>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * Picks several options. The field shows the picks as removable chips, in the order they were made;
+ * opening it lists every option under a search box, with the picked ones checked, and Enter or a
+ * click checks or unchecks a row without closing the list. The search folds case and accents, and a
+ * row matches when it contains every word typed.
+ *
+ * A disabled option cannot be checked or unchecked: picked, it is locked, and its chip has no ✕. On
+ * the field, the arrows open the list and Backspace removes the last pick that is not locked. The
+ * chips' remove buttons are not Tab stops; from the keyboard, a pick is unchecked in the list.
+ *
+ * It is a `Dropdown` with a `Listbox` inside, so the focus moves into the search box as the list
+ * opens and comes back to the field as it closes. Shift+Tab from the search box reaches the field
+ * with the list still open, and an arrow key sends the focus back in.
+ *
+ * `required` blocks the surrounding form while nothing is picked, and `name` submits one entry per
+ * pick.
+ *
+ * ```svelte
+ * <MultiSelect options={people} bind:value={members} aria-label="Members">
+ * {#snippet chip(person)}{person.label}{/snippet}
+ * </MultiSelect>
+ * ```
+ */
+declare const MultiSelect: $$IsomorphicComponent;
+type MultiSelect<O extends SelectOption = SelectOption> = InstanceType<typeof MultiSelect<O>>;
+export default MultiSelect;