@viniaraujo68/plinth 0.0.0-stage → 0.2.0

package/dist/components/OptionPanel.svelte

@@ -0,0 +1,241 @@
+<script lang="ts">
+  import { flushSync, onDestroy, type Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import { positionUnder, supportsAnchorPositioning } from "../anchoring.js";
+  import type { SelectOption } from "./select.js";
+
+  /** `margin-block: 0.25rem` below, in pixels: the gap the anchored path puts under the control. */
+  const GAP = 4;
+
+  interface Props {
+    /** Document-unique id of the popover. `Select` names it from the trigger's `popovertarget`. */
+    id: string;
+    /** The `anchor-name` the control declares, which is what the panel hangs itself under. */
+    anchorName: string;
+    /**
+     * The control itself. Read only where the browser has no anchor positioning and the panel has
+     * to be placed by script — measuring it is the one thing {@link Props.anchorName} cannot do.
+     */
+    anchor?: HTMLElement;
+    listboxId: string;
+    /** Id of the control the listbox borrows its accessible name from. */
+    labelledBy: string;
+    /** The rows to render — already filtered, in the order they are shown. */
+    options: readonly SelectOption[];
+    /** The selected value, marked with a ✓ and `aria-selected`. */
+    value: string | null;
+    /** Index into `options`, or `-1`. The control owns it: the arrows move it, Enter reads it. */
+    highlighted: number;
+    /** Row ids, so the control can point `aria-activedescendant` at the same element. */
+    optionId: (index: number) => string;
+    option?: Snippet<[SelectOption]>;
+    /** Shown in place of the list when `options` is empty. Nothing is rendered without one. */
+    emptyLabel?: string;
+    class?: ClassValue;
+    /**
+     * Open and close, reported from `beforetoggle` rather than from `toggle`: it is synchronous,
+     * so a control can settle its own state — the highlight, the text a `Combobox` puts back —
+     * in the same task the panel changes state, with no frame in between showing the other one.
+     */
+    onopenchange: (open: boolean) => void;
+    onhighlight: (value: string) => void;
+    onchoose: (option: SelectOption) => void;
+  }
+
+  let {
+    id,
+    anchorName,
+    anchor,
+    listboxId,
+    labelledBy,
+    options,
+    value,
+    highlighted,
+    optionId,
+    option,
+    emptyLabel,
+    class: className,
+    onopenchange,
+    onhighlight,
+    onchoose,
+  }: Props = $props();
+
+  let panel = $state<HTMLDivElement>();
+  let isMounted = $state(false);
+
+  let stopPositioning: (() => void) | undefined;
+
+  /* Without anchor positioning the placement rules at the bottom of this file are dropped and
+     the UA popover ones are all that is left -- which, with the `margin-block` below overriding
+     half of their `margin: auto`, pins the panel to the top of the screen at an intrinsic width.
+     Script places it instead, to the same geometry: under the control, as wide as it, a hair
+     below it, and above it when there is no room. */
+  const reposition = () => {
+    stopPositioning?.();
+    stopPositioning = undefined;
+    if (!panel || !anchor || supportsAnchorPositioning()) return;
+
+    stopPositioning = positionUnder(panel, anchor, { gap: GAP, matchWidth: true });
+  };
+
+  const releasePositioning = () => {
+    stopPositioning?.();
+    stopPositioning = undefined;
+  };
+
+  // A panel left open when its control is destroyed would otherwise leave the reposition
+  // listeners on the window, holding a detached element.
+  onDestroy(releasePositioning);
+
+  /** Shows the panel. For a control that is not a `popovertarget` invoker — a `Combobox` input. */
+  export function show() {
+    isMounted = true;
+    if (panel && !panel.matches(":popover-open")) panel.showPopover();
+    // Ahead of the `toggle` event, which arrives a task later: the panel is on screen from this
+    // line onwards, so anything but a synchronous placement is a painted frame in the wrong place.
+    reposition();
+  }
+
+  export function hide() {
+    panel?.hidePopover();
+  }
+
+  export function isShown() {
+    return panel?.matches(":popover-open") ?? false;
+  }
+
+  // The highlight is an attribute on the control, not a focus ring the browser scrolls to on its
+  // own, so keeping it on screen is ours to do. `nearest` is what makes it a nudge of the list
+  // rather than a jump of the page.
+  $effect(() => {
+    if (!isMounted || highlighted < 0) return;
+
+    document.getElementById(optionId(highlighted))?.scrollIntoView({
+      block: "nearest",
+      inline: "nearest",
+    });
+  });
+
+  /* A hidden popover stops rendering entirely, which freezes any exit transition mid-flight and
+     means its `transitionend` never arrives. Asking the element whether it is actually visible is
+     the only reading that holds for both an animated and an instant close. */
+  const unmountWhenHidden = () => {
+    if (panel && !panel.checkVisibility({ opacityProperty: true, visibilityProperty: true }))
+      isMounted = false;
+  };
+  /* `transitionend` bubbles, so a row's own transition would reach the panel and ask whether to
+     unmount the list while it is plainly open. Only the panel's transitions can be its exit. */
+  const onTransitionSettled = (event: TransitionEvent) => {
+    if (event.target === event.currentTarget) unmountWhenHidden();
+  };
+
+  const onBeforeToggle = (event: ToggleEvent) => {
+    const open = event.newState === "open";
+    onopenchange(open);
+    if (!open) return;
+
+    isMounted = true;
+    // The browser shows the popover in this same task, so the rows have to exist before the
+    // handler returns -- otherwise the first painted frame is an empty panel.
+    flushSync();
+  };
+
+  const onToggle = (event: ToggleEvent) => {
+    if (event.newState === "open") {
+      isMounted = true;
+      reposition();
+    } else {
+      releasePositioning();
+      unmountWhenHidden();
+    }
+  };
+</script>
+
+<!--
+@component
+Internal. The top-layer list `Select` and `Combobox` both drop under their control: the popover
+element, the rows, the highlight's scrolling and the mount bookkeeping. Neither the query nor the
+selection lives here — the control owns both and hands down what to draw.
+
+Not exported from the package: it is the shared half of two components, not a third one.
+-->
+
+<div
+  bind:this={panel}
+  popover
+  {id}
+  class={[
+    "flex flex-col overflow-hidden rounded-box border border-base-content/10 bg-base-100 shadow-lg",
+    className,
+  ]}
+  style:position-anchor={anchorName}
+  onbeforetoggle={onBeforeToggle}
+  ontoggle={onToggle}
+  ontransitionend={onTransitionSettled}
+  ontransitioncancel={onTransitionSettled}
+>
+  {#if isMounted}
+    <div
+      id={listboxId}
+      role="listbox"
+      aria-labelledby={labelledBy}
+      class="max-h-64 overflow-y-auto overscroll-contain p-1"
+    >
+      {#each options as candidate, index (candidate.value)}
+        <button
+          type="button"
+          id={optionId(index)}
+          role="option"
+          tabindex="-1"
+          disabled={candidate.disabled}
+          aria-selected={candidate.value === value}
+          aria-disabled={candidate.disabled}
+          class={[
+            "flex min-h-11 w-full cursor-pointer items-center gap-2 rounded-field px-3 py-2 text-start text-sm",
+            // A tint of the foreground rather than a step of the surface: base-200 is lighter than
+            // base-100 in a light theme and darker in a dark one, so a surface step reads as
+            // "raised" in one and "recessed" in the other.
+            index === highlighted && "bg-base-content/10",
+            candidate.disabled && "cursor-not-allowed opacity-40",
+          ]}
+          onmousedown={(event) => event.preventDefault()}
+          onpointermove={() => onhighlight(candidate.value)}
+          onclick={() => onchoose(candidate)}
+        >
+          <span class="min-w-0 flex-1 truncate">
+            {#if option}{@render option(candidate)}{:else}{candidate.label}{/if}
+          </span>
+          <span class="flex-none text-xs" aria-hidden="true">
+            {candidate.value === value ? "✓" : ""}
+          </span>
+        </button>
+      {/each}
+
+      {#if options.length === 0 && emptyLabel !== undefined}
+        <p class="px-3 py-4 text-center text-sm text-base-content/60">{emptyLabel}</p>
+      {/if}
+    </div>
+  {/if}
+</div>
+
+<style>
+  [popover] {
+    position-area: bottom;
+    position-try: top;
+    /* The panel is the control's list, so it is the control's width -- an option that fits the
+       closed control fits the open one. */
+    width: anchor-size(width);
+    /* Overriding the UA's `margin: auto`, which would otherwise centre the panel in the whole
+       region below the anchor instead of hanging it just under the control. The inline margins
+       stay auto so the panel keeps sitting over the anchor. */
+    margin-block: 0.25rem;
+  }
+
+  /* A closed popover is hidden by a rule in the UA stylesheet, which every author rule outranks --
+     including any `display` a utility class on the panel might carry. Restating the rule here puts
+     it at a specificity a utility cannot reach, while leaving an exit transition possible for a
+     caller who asks for one with `transition-behavior: allow-discrete`. */
+  [popover]:not(:popover-open) {
+    display: none;
+  }
+</style>

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

@@ -0,0 +1,51 @@
+import { type Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import type { SelectOption } from "./select.js";
+interface Props {
+    /** Document-unique id of the popover. `Select` names it from the trigger's `popovertarget`. */
+    id: string;
+    /** The `anchor-name` the control declares, which is what the panel hangs itself under. */
+    anchorName: string;
+    /**
+     * The control itself. Read only where the browser has no anchor positioning and the panel has
+     * to be placed by script — measuring it is the one thing {@link Props.anchorName} cannot do.
+     */
+    anchor?: HTMLElement;
+    listboxId: string;
+    /** Id of the control the listbox borrows its accessible name from. */
+    labelledBy: string;
+    /** The rows to render — already filtered, in the order they are shown. */
+    options: readonly SelectOption[];
+    /** The selected value, marked with a ✓ and `aria-selected`. */
+    value: string | null;
+    /** Index into `options`, or `-1`. The control owns it: the arrows move it, Enter reads it. */
+    highlighted: number;
+    /** Row ids, so the control can point `aria-activedescendant` at the same element. */
+    optionId: (index: number) => string;
+    option?: Snippet<[SelectOption]>;
+    /** Shown in place of the list when `options` is empty. Nothing is rendered without one. */
+    emptyLabel?: string;
+    class?: ClassValue;
+    /**
+     * Open and close, reported from `beforetoggle` rather than from `toggle`: it is synchronous,
+     * so a control can settle its own state — the highlight, the text a `Combobox` puts back —
+     * in the same task the panel changes state, with no frame in between showing the other one.
+     */
+    onopenchange: (open: boolean) => void;
+    onhighlight: (value: string) => void;
+    onchoose: (option: SelectOption) => void;
+}
+/**
+ * Internal. The top-layer list `Select` and `Combobox` both drop under their control: the popover
+ * element, the rows, the highlight's scrolling and the mount bookkeeping. Neither the query nor the
+ * selection lives here — the control owns both and hands down what to draw.
+ *
+ * Not exported from the package: it is the shared half of two components, not a third one.
+ */
+declare const OptionPanel: import("svelte").Component<Props, {
+    show: () => void;
+    hide: () => void;
+    isShown: () => boolean;
+}, "">;
+type OptionPanel = ReturnType<typeof OptionPanel>;
+export default OptionPanel;

package/dist/components/Paginator.svelte

@@ -0,0 +1,205 @@
+<script lang="ts">
+  import type { ClassValue } from "svelte/elements";
+
+  /** The server answered with a count: the last page is reachable and the summary is exact. */
+  interface CountedPages {
+    totalPages: number;
+    totalItems?: number;
+    hasNextPage?: never;
+  }
+
+  /** Keyset or "one row too many" pagination: only the existence of a next page is known. */
+  interface UncountedPages {
+    hasNextPage: boolean;
+    totalPages?: never;
+    totalItems?: never;
+  }
+
+  type Props = {
+    class?: ClassValue;
+    /** One-based. */
+    pageNumber: number;
+    pageSize?: number;
+    /** Sizes offered by the picker. */
+    pageSizes?: number[];
+    /**
+     * Fires when the user picks a different page. Never fires for a size change — that is a
+     * separate event with a separate payload ({@link Props.onPageSizeChange}).
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Fires when the user picks a new page size. The consumer owns the state: both the refetch
+     * and the reset back to page 1, since a new size invalidates the old page arithmetic.
+     */
+    onPageSizeChange?: (size: number) => void;
+  } & (CountedPages | UncountedPages);
+
+  let {
+    class: cls,
+    pageNumber,
+    pageSize,
+    pageSizes = [10, 20, 50, 100],
+    onPageChange,
+    onPageSizeChange,
+    totalPages,
+    totalItems,
+    hasNextPage,
+  }: Props = $props();
+
+  const range = (start: number, end: number): number[] =>
+    Array.from({ length: Math.max(0, end - start + 1) }, (_, i) => start + i);
+
+  const canGoNext = $derived(
+    hasNextPage ?? (totalPages !== undefined && totalPages > 0 && pageNumber < totalPages),
+  );
+
+  const [firstShown, lastShown] = $derived(
+    pageSize === undefined || totalItems === undefined
+      ? [undefined, undefined]
+      : [(pageNumber - 1) * pageSize + 1, Math.min(pageNumber * pageSize, totalItems)],
+  );
+
+  const setPage = (page: number) => {
+    const clamped = Math.max(1, totalPages === undefined ? page : Math.min(page, totalPages));
+
+    // Clicking the current page, or an arrow at a bound, is not a change — staying silent here is
+    // what keeps a consumer from refetching the page it is already showing.
+    if (clamped === pageNumber) return;
+
+    onPageChange?.(clamped);
+  };
+
+  // `null` is the ellipsis. Around the current page the window is always the same width, so the
+  // buttons under the cursor do not shift as the user walks through the pages.
+  const pages = $derived.by((): (number | null)[] => {
+    if (totalPages === undefined) {
+      const leading =
+        pageNumber <= 3 ? range(1, pageNumber) : [1, null, pageNumber - 1, pageNumber];
+      return hasNextPage ? [...leading, pageNumber + 1, null] : leading;
+    }
+
+    if (totalPages <= 5) return range(1, totalPages);
+    if (pageNumber < 4) return [...range(1, 5), null, totalPages];
+    if (pageNumber > totalPages - 4) return [1, null, ...range(totalPages - 4, totalPages)];
+
+    return [1, null, pageNumber - 1, pageNumber, pageNumber + 1, null, totalPages];
+  });
+</script>
+
+<!--
+@component
+Page selector for a list, in two flavours picked by which props are passed: `totalPages`
+(optionally with `totalItems`, which turns on the size picker and the "showing x to y" summary),
+or `hasNextPage` alone when the backend only knows whether one more page exists. The two are
+mutually exclusive in the type, so a partially-wired paginator is a compile error.
+
+It holds no state: `pageNumber` comes in, `onPageChange` goes out, and the consumer decides what
+that means. Sizing is in `em`, so the whole strip scales with the font size around it.
+
+```svelte
+<Paginator pageNumber={page} totalPages={data.pages} totalItems={data.count}
+  pageSize={size} onPageChange={(p) => (page = p)} onPageSizeChange={(s) => { size = s; page = 1; }} />
+```
+-->
+
+{#snippet chevron(direction: "left" | "right")}
+  <svg
+    class="size-[1em]"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d={direction === "left" ? "m15 18-6-6 6-6" : "m9 18 6-6-6-6"} />
+  </svg>
+{/snippet}
+
+{#snippet pageButton(page: number)}
+  <button
+    type="button"
+    class="btn h-[1.75em] min-w-[1.75em] px-2 tabular-nums btn-primary aria-[current=false]:btn-ghost"
+    onclick={() => setPage(page)}
+    aria-current={page === pageNumber}
+    aria-label={`Page ${page}`}
+  >
+    {page}
+  </button>
+{/snippet}
+
+{#snippet pageSelector()}
+  <button
+    type="button"
+    class="btn size-[1.75em] btn-ghost px-1"
+    aria-label="Previous page"
+    disabled={pageNumber <= 1}
+    onclick={() => setPage(pageNumber - 1)}
+  >
+    {@render chevron("left")}
+  </button>
+
+  <!-- Keyed by position: the list is a pure projection of `pageNumber`, and the ellipsis entries
+       are indistinguishable from one another by value. -->
+  {#each pages as page, slot (slot)}
+    {#if page === null}
+      <span class="mx-2 inline-block text-center" aria-hidden="true">...</span>
+    {:else}
+      {@render pageButton(page)}
+    {/if}
+  {/each}
+
+  <button
+    type="button"
+    class="btn size-[1.75em] btn-ghost px-1"
+    aria-label="Next page"
+    disabled={!canGoNext}
+    onclick={() => setPage(pageNumber + 1)}
+  >
+    {@render chevron("right")}
+  </button>
+{/snippet}
+
+{#if totalItems === undefined || pageSize === undefined}
+  <nav class={["flex place-content-center gap-px", cls]} aria-label="Pagination">
+    {@render pageSelector()}
+  </nav>
+{:else}
+  <nav class={["@container", cls]} aria-label="Pagination">
+    <div class="grid items-center justify-items-center gap-1 @min-[45rem]:grid-cols-3">
+      <!-- Narrow, the summary and the size picker fall below the buttons: the control the user
+           came for stays at the top of the block rather than being pushed off by chrome. -->
+      <div class="flex items-center gap-1 @max-[45rem]:order-last @min-[45rem]:mr-auto">
+        <span class="text-nowrap">Items per page:</span>
+        <select
+          class="select box-content w-[3ch] select-xs"
+          aria-label="Items per page"
+          value={pageSize}
+          onchange={({ currentTarget }) => onPageSizeChange?.(Number(currentTarget.value))}
+        >
+          {#each pageSizes as size (size)}
+            <option value={size}>{size}</option>
+          {/each}
+        </select>
+      </div>
+
+      <div class="text-center tabular-nums" data-testid="paginator-summary">
+        Showing {firstShown} to {lastShown} of {totalItems} items
+      </div>
+
+      <div class="flex items-center gap-px @max-[45rem]:order-first @min-[45rem]:ml-auto">
+        {@render pageSelector()}
+      </div>
+    </div>
+  </nav>
+{/if}
+
+<style>
+  /* The strip sizes itself in `em`, so every control has to inherit the surrounding font size
+     rather than fall back to the browser default for form elements. */
+  button,
+  span {
+    font-size: inherit;
+  }
+</style>

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

@@ -0,0 +1,48 @@
+import type { ClassValue } from "svelte/elements";
+/** The server answered with a count: the last page is reachable and the summary is exact. */
+interface CountedPages {
+    totalPages: number;
+    totalItems?: number;
+    hasNextPage?: never;
+}
+/** Keyset or "one row too many" pagination: only the existence of a next page is known. */
+interface UncountedPages {
+    hasNextPage: boolean;
+    totalPages?: never;
+    totalItems?: never;
+}
+type Props = {
+    class?: ClassValue;
+    /** One-based. */
+    pageNumber: number;
+    pageSize?: number;
+    /** Sizes offered by the picker. */
+    pageSizes?: number[];
+    /**
+     * Fires when the user picks a different page. Never fires for a size change — that is a
+     * separate event with a separate payload ({@link Props.onPageSizeChange}).
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Fires when the user picks a new page size. The consumer owns the state: both the refetch
+     * and the reset back to page 1, since a new size invalidates the old page arithmetic.
+     */
+    onPageSizeChange?: (size: number) => void;
+} & (CountedPages | UncountedPages);
+/**
+ * Page selector for a list, in two flavours picked by which props are passed: `totalPages`
+ * (optionally with `totalItems`, which turns on the size picker and the "showing x to y" summary),
+ * or `hasNextPage` alone when the backend only knows whether one more page exists. The two are
+ * mutually exclusive in the type, so a partially-wired paginator is a compile error.
+ *
+ * It holds no state: `pageNumber` comes in, `onPageChange` goes out, and the consumer decides what
+ * that means. Sizing is in `em`, so the whole strip scales with the font size around it.
+ *
+ * ```svelte
+ * <Paginator pageNumber={page} totalPages={data.pages} totalItems={data.count}
+ * pageSize={size} onPageChange={(p) => (page = p)} onPageSizeChange={(s) => { size = s; page = 1; }} />
+ * ```
+ */
+declare const Paginator: import("svelte").Component<Props, {}, "">;
+type Paginator = ReturnType<typeof Paginator>;
+export default Paginator;