@viniaraujo68/plinth 0.0.0-stage → 0.3.0

package/dist/components/RefreshButton.svelte

@@ -0,0 +1,246 @@
+<script lang="ts">
+  import { untrack } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import { AsyncAction } from "../async-action.svelte.js";
+  import { reportError } from "../error.js";
+
+  interface IntervalOption {
+    value: number;
+    label: string;
+  }
+
+  interface Props {
+    /** The reload itself. Awaited, so the spinner and the countdown follow the real request. */
+    onRefresh: () => unknown | Promise<unknown>;
+    /** Auto-refresh periods offered by the picker, in seconds. Pass `[]` for a manual-only control. */
+    intervals?: IntervalOption[];
+    /**
+     * Period selected when auto-refresh is switched on, one of `intervals`. Defaults to the second
+     * option, and so does a period the picker does not offer.
+     */
+    defaultInterval?: number;
+    /** Whether auto-refresh is armed. Pass `true` to start with it on; bind to follow the toggle. */
+    autoRefresh?: boolean;
+    /**
+     * When the data on screen last landed, as an epoch millisecond count. Left out, the control
+     * times its own successful refreshes — which is wrong the moment the data also arrives from
+     * somewhere else, such as a server-rendered first load.
+     */
+    lastSuccessAt?: number | null;
+    /** Formatting locale for the timestamp. Defaults to the browser's. */
+    locale?: string;
+    refreshLabel?: string;
+    startLabel?: string;
+    pauseLabel?: string;
+    intervalLabel?: string;
+    class?: ClassValue;
+  }
+
+  const defaultIntervals: IntervalOption[] = [
+    { value: 10, label: "10s" },
+    { value: 30, label: "30s" },
+    { value: 60, label: "1m" },
+    { value: 300, label: "5m" },
+  ];
+
+  let {
+    onRefresh,
+    intervals = defaultIntervals,
+    defaultInterval,
+    autoRefresh = $bindable(false),
+    lastSuccessAt,
+    locale,
+    refreshLabel = "Refresh now",
+    startLabel = "Start auto-refresh",
+    pauseLabel = "Pause auto-refresh",
+    intervalLabel = "Auto-refresh interval",
+    class: cls,
+  }: Props = $props();
+
+  // A seed, not a binding: once the user has picked a period, a re-render of the parent must not
+  // yank it back to the default. `untrack` states that and keeps the compiler from warning.
+  let periodSec = $state(
+    untrack(() =>
+      intervals.some((option) => option.value === defaultInterval)
+        ? defaultInterval!
+        : (intervals[1]?.value ?? intervals[0]?.value ?? null),
+    ),
+  );
+  const scheduled = $derived(intervals.length > 0 && periodSec !== null);
+  let ownLastSuccessAt = $state<number | null>(null);
+  let nextRefreshAt = $state<number | null>(null);
+  let now = $state(Date.now());
+  let visible = $state(true);
+
+  const action = new AsyncAction(async () => {
+    await onRefresh();
+    ownLastSuccessAt = Date.now();
+  });
+
+  const refresh = async () => {
+    await action.run();
+    if (action.isError) reportError(action.error);
+  };
+
+  const shownAt = $derived(lastSuccessAt === undefined ? ownLastSuccessAt : lastSuccessAt);
+
+  // A hidden tab gets its timers throttled to once a minute or worse, so an unattended schedule
+  // would drift and then fire a burst on focus. Suspending it outright is both honest and cheaper.
+  $effect(() => {
+    const track = () => {
+      visible = document.visibilityState === "visible";
+    };
+    track();
+    document.addEventListener("visibilitychange", track);
+    return () => {
+      document.removeEventListener("visibilitychange", track);
+    };
+  });
+
+  // One second-resolution timer drives both the countdown and the firing, so what the user reads
+  // is the schedule itself rather than a second clock that agrees with it only approximately.
+  // The deadline is a plain local: writing it to state would make this effect depend on its own
+  // output and re-run forever.
+  $effect(() => {
+    if (!autoRefresh || !scheduled || !visible) {
+      nextRefreshAt = null;
+      return;
+    }
+
+    const period = periodSec! * 1000;
+    let deadline = Date.now() + period;
+    nextRefreshAt = deadline;
+    now = Date.now();
+
+    const id = setInterval(() => {
+      now = Date.now();
+      if (now < deadline) return;
+      deadline = now + period;
+      nextRefreshAt = deadline;
+      void refresh();
+    }, 1000);
+
+    return () => {
+      clearInterval(id);
+      nextRefreshAt = null;
+    };
+  });
+
+  const secondsLeft = $derived(
+    nextRefreshAt === null ? null : Math.max(0, Math.ceil((nextRefreshAt - now) / 1000)),
+  );
+
+  const formatTime = (ms: number | null): string =>
+    ms === null
+      ? "--:--:--"
+      : new Date(ms).toLocaleTimeString(locale, {
+          hour: "2-digit",
+          minute: "2-digit",
+          second: "2-digit",
+        });
+</script>
+
+<!--
+@component
+Freshness control: when the data last landed, a "refresh now" button, and an auto-refresh toggle
+with a period picker.
+
+It owns its schedule — this library ships no query layer to delegate one to — and suspends it
+while the tab is hidden, resuming on the next visible second rather than firing a backlog. The
+countdown replaces the timestamp while auto-refresh is armed, so the strip never changes width.
+
+```svelte
+<RefreshButton onRefresh={() => reload()} lastSuccessAt={loadedAt} />
+```
+-->
+
+<div
+  class={[
+    "inline-flex h-8 items-center rounded-field border border-base-content/15 bg-base-100 pr-1 pl-2.5",
+    cls,
+  ]}
+>
+  <span class="flex items-center gap-1.5 text-base-content/55">
+    <span
+      class={[
+        "size-1.5 rounded-full transition",
+        secondsLeft === null
+          ? "bg-base-content/30"
+          : "animate-pulse bg-success ring-2 ring-success/25",
+      ]}
+    ></span>
+    <span class="font-mono text-xs tabular-nums" data-testid="refresh-clock">
+      {secondsLeft === null ? formatTime(shownAt) : `${secondsLeft}s`}
+    </span>
+  </span>
+
+  <!-- Icons are inline SVG throughout the library: a component that renders an icon-font class
+       would silently render nothing unless the consumer also installs that plugin in its own
+       Tailwind chain. -->
+  <button
+    type="button"
+    class="btn ml-1.5 btn-square btn-ghost btn-xs"
+    title={refreshLabel}
+    aria-label={refreshLabel}
+    onclick={refresh}
+  >
+    <svg
+      class={["size-3.5", action.isPending && "animate-spin"]}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
+      <path d="M21 3v5h-5" />
+      <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />
+      <path d="M8 16H3v5" />
+    </svg>
+  </button>
+
+  {#if scheduled}
+    <span class="mx-0.5 h-5 w-px bg-base-content/15"></span>
+
+    <button
+      type="button"
+      class={[
+        "btn btn-square btn-ghost btn-xs",
+        autoRefresh ? "text-primary" : "text-base-content/55",
+      ]}
+      title={autoRefresh ? pauseLabel : startLabel}
+      aria-label={autoRefresh ? pauseLabel : startLabel}
+      aria-pressed={autoRefresh}
+      onclick={() => {
+        autoRefresh = !autoRefresh;
+      }}
+    >
+      {#if autoRefresh}
+        <svg class="size-3.5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+          <rect x="6" y="4" width="4" height="16" rx="1" />
+          <rect x="14" y="4" width="4" height="16" rx="1" />
+        </svg>
+      {:else}
+        <svg class="size-3.5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+          <path
+            d="M7 4.5v15a1 1 0 0 0 1.53.85l11.5-7.5a1 1 0 0 0 0-1.7L8.53 3.65A1 1 0 0 0 7 4.5Z"
+          />
+        </svg>
+      {/if}
+    </button>
+  {/if}
+
+  {#if scheduled && autoRefresh}
+    <select
+      class="select ml-0.5 w-18 select-ghost font-mono select-xs"
+      aria-label={intervalLabel}
+      bind:value={periodSec}
+    >
+      {#each intervals as option (option.value)}
+        <option value={option.value}>{option.label}</option>
+      {/each}
+    </select>
+  {/if}
+</div>

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

@@ -0,0 +1,46 @@
+import type { ClassValue } from "svelte/elements";
+interface IntervalOption {
+    value: number;
+    label: string;
+}
+interface Props {
+    /** The reload itself. Awaited, so the spinner and the countdown follow the real request. */
+    onRefresh: () => unknown | Promise<unknown>;
+    /** Auto-refresh periods offered by the picker, in seconds. Pass `[]` for a manual-only control. */
+    intervals?: IntervalOption[];
+    /**
+     * Period selected when auto-refresh is switched on, one of `intervals`. Defaults to the second
+     * option, and so does a period the picker does not offer.
+     */
+    defaultInterval?: number;
+    /** Whether auto-refresh is armed. Pass `true` to start with it on; bind to follow the toggle. */
+    autoRefresh?: boolean;
+    /**
+     * When the data on screen last landed, as an epoch millisecond count. Left out, the control
+     * times its own successful refreshes — which is wrong the moment the data also arrives from
+     * somewhere else, such as a server-rendered first load.
+     */
+    lastSuccessAt?: number | null;
+    /** Formatting locale for the timestamp. Defaults to the browser's. */
+    locale?: string;
+    refreshLabel?: string;
+    startLabel?: string;
+    pauseLabel?: string;
+    intervalLabel?: string;
+    class?: ClassValue;
+}
+/**
+ * Freshness control: when the data last landed, a "refresh now" button, and an auto-refresh toggle
+ * with a period picker.
+ *
+ * It owns its schedule — this library ships no query layer to delegate one to — and suspends it
+ * while the tab is hidden, resuming on the next visible second rather than firing a backlog. The
+ * countdown replaces the timestamp while auto-refresh is armed, so the strip never changes width.
+ *
+ * ```svelte
+ * <RefreshButton onRefresh={() => reload()} lastSuccessAt={loadedAt} />
+ * ```
+ */
+declare const RefreshButton: import("svelte").Component<Props, {}, "autoRefresh">;
+type RefreshButton = ReturnType<typeof RefreshButton>;
+export default RefreshButton;

package/dist/components/SegmentedControl.svelte

@@ -0,0 +1,147 @@
+<script lang="ts" generics="Id extends string">
+  import type { ClassValue } from "svelte/elements";
+  import type { SegmentedOption } from "./segmented.js";
+
+  interface Props {
+    /** The choices, in the order they are shown. `id` is the value, so it has to be unique. */
+    options: readonly SegmentedOption<Id>[];
+    /** The chosen `id`. Bindable, and also reported through {@link Props.onchange}. */
+    value: Id;
+    /** Accessible name of the group. A prop because the library ships no translations. */
+    label: string;
+    /**
+     * Visible text before the buttons — "Show:", "Goals and assists:". It is not the accessible
+     * name; `label` is, so a caption can be as terse as it likes without a screen reader hearing
+     * half a sentence.
+     */
+    caption?: string;
+    /** `sm` is for a control inside a card header, where the default height would dominate. */
+    size?: "sm" | "md";
+    /** Classes for the wrapper — spacing, alignment. */
+    class?: ClassValue;
+    /** Called with the new `id` only when it actually changes; re-picking the current one is silent. */
+    onchange?: (id: Id) => void;
+  }
+
+  let {
+    options,
+    value = $bindable(),
+    label,
+    caption,
+    size = "md",
+    class: className,
+    onchange,
+  }: Props = $props();
+
+  const pick = (id: Id) => {
+    if (id === value) return;
+    value = id;
+    onchange?.(id);
+  };
+</script>
+
+<!--
+@component
+A row of mutually exclusive buttons: one of them is the current choice, and pressing another
+moves the choice there. It is the control for a small, fixed set of views of the same thing —
+"total, per match, per day" — where a `Select` would hide options that are cheaper to see.
+
+Each button is a toggle button (`aria-pressed`) inside a labelled `group`, rather than a radio
+group: a radio group moves the choice with the arrow keys as focus moves, which re-renders
+whatever the control drives on every keystroke, where Tab and Enter let a keyboard user look at the
+options before committing to one.
+
+The colours come from two custom properties with library defaults, so an app with its own
+contrast-tuned inks can hand them in without restyling the component:
+`--segmented-ink` for the resting text, `--segmented-ink-selected` for the chosen one.
+
+```svelte
+<SegmentedControl
+  bind:value={unit}
+  label="Unit"
+  caption="Goals:"
+  options={[
+    { id: "total", label: "Total" },
+    { id: "match", label: "Per match" },
+  ]}
+/>
+```
+-->
+
+<div class={["plinth-segmented", className]} data-size={size}>
+  {#if caption}<span class="plinth-segmented-caption">{caption}</span>{/if}
+  <div class="plinth-segmented-options" role="group" aria-label={label}>
+    {#each options as option (option.id)}
+      <button
+        type="button"
+        class="plinth-segment"
+        class:plinth-segment-selected={option.id === value}
+        aria-pressed={option.id === value}
+        disabled={option.disabled}
+        onclick={() => pick(option.id)}
+      >
+        {option.label}
+      </button>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .plinth-segmented {
+    --segmented-ink-default: color-mix(in oklch, var(--color-base-content) 70%, transparent);
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.375rem 0.5rem;
+  }
+
+  .plinth-segmented-caption {
+    font-size: 0.72rem;
+    color: var(--segmented-ink, var(--segmented-ink-default));
+  }
+
+  .plinth-segmented-options {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.3125rem;
+  }
+
+  .plinth-segment {
+    min-height: 2rem;
+    padding: 0.25rem 0.6875rem;
+    border: 1px solid color-mix(in oklch, var(--color-base-content) 15%, transparent);
+    /* The theme's field radius rather than a pill, like the table's sort pills: these are
+       controls, and they should match the buttons and inputs they sit among. */
+    border-radius: var(--radius-field, 0.5rem);
+    background: var(--color-base-100);
+    color: var(--segmented-ink, var(--segmented-ink-default));
+    font-size: 0.78rem;
+    cursor: pointer;
+  }
+
+  .plinth-segment:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  .plinth-segment-selected {
+    border-color: var(--color-primary);
+    background: color-mix(in oklch, var(--color-primary) 14%, transparent);
+    color: var(--segmented-ink-selected, var(--color-primary));
+    font-weight: 600;
+  }
+
+  [data-size="sm"] .plinth-segment {
+    min-height: 1.625rem;
+    padding: 0.125rem 0.5rem;
+    font-size: 0.7rem;
+  }
+
+  /* 40px on a phone: at the default height a segment is too small a target for a thumb. */
+  @media (max-width: 35rem) {
+    [data-size="md"] .plinth-segment {
+      min-height: 2.5rem;
+    }
+  }
+</style>

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

@@ -0,0 +1,71 @@
+import type { ClassValue } from "svelte/elements";
+import type { SegmentedOption } from "./segmented.js";
+declare function $$render<Id extends string>(): {
+    props: {
+        /** The choices, in the order they are shown. `id` is the value, so it has to be unique. */
+        options: readonly SegmentedOption<Id>[];
+        /** The chosen `id`. Bindable, and also reported through {@link Props.onchange}. */
+        value: Id;
+        /** Accessible name of the group. A prop because the library ships no translations. */
+        label: string;
+        /**
+         * Visible text before the buttons — "Show:", "Goals and assists:". It is not the accessible
+         * name; `label` is, so a caption can be as terse as it likes without a screen reader hearing
+         * half a sentence.
+         */
+        caption?: string;
+        /** `sm` is for a control inside a card header, where the default height would dominate. */
+        size?: "sm" | "md";
+        /** Classes for the wrapper — spacing, alignment. */
+        class?: ClassValue;
+        /** Called with the new `id` only when it actually changes; re-picking the current one is silent. */
+        onchange?: (id: Id) => void;
+    };
+    exports: {};
+    bindings: "value";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Id extends string> {
+    props(): ReturnType<typeof $$render<Id>>['props'];
+    events(): ReturnType<typeof $$render<Id>>['events'];
+    slots(): ReturnType<typeof $$render<Id>>['slots'];
+    bindings(): "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Id extends string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Id>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Id>['props']>, ReturnType<__sveltets_Render<Id>['events']>, ReturnType<__sveltets_Render<Id>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Id>['bindings']>;
+    } & ReturnType<__sveltets_Render<Id>['exports']>;
+    <Id extends string>(internal: unknown, props: ReturnType<__sveltets_Render<Id>['props']> & {}): ReturnType<__sveltets_Render<Id>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * A row of mutually exclusive buttons: one of them is the current choice, and pressing another
+ * moves the choice there. It is the control for a small, fixed set of views of the same thing —
+ * "total, per match, per day" — where a `Select` would hide options that are cheaper to see.
+ *
+ * Each button is a toggle button (`aria-pressed`) inside a labelled `group`, rather than a radio
+ * group: a radio group moves the choice with the arrow keys as focus moves, which re-renders
+ * whatever the control drives on every keystroke, where Tab and Enter let a keyboard user look at the
+ * options before committing to one.
+ *
+ * The colours come from two custom properties with library defaults, so an app with its own
+ * contrast-tuned inks can hand them in without restyling the component:
+ * `--segmented-ink` for the resting text, `--segmented-ink-selected` for the chosen one.
+ *
+ * ```svelte
+ * <SegmentedControl
+ * bind:value={unit}
+ * label="Unit"
+ * caption="Goals:"
+ * options={[
+ *   { id: "total", label: "Total" },
+ *   { id: "match", label: "Per match" },
+ * ]}
+ * />
+ * ```
+ */
+declare const SegmentedControl: $$IsomorphicComponent;
+type SegmentedControl<Id extends string> = InstanceType<typeof SegmentedControl<Id>>;
+export default SegmentedControl;