@viniaraujo68/plinth 0.3.1 → 0.6.0

package/dist/url-state/url-store.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { ExternalStore, UrlStateCodec } from "./codec.js";
+import { SyncedState } from "./synced-state.svelte.js";
+export type ReplaceHistory = boolean | ((previous: URLSearchParams, next: URLSearchParams) => boolean);
+export interface UrlStoreOptions {
+    replace?: ReplaceHistory;
+}
+export declare const urlStore: (ownedParams: readonly string[], options?: UrlStoreOptions) => ExternalStore<URLSearchParams>;
+export interface UrlStateOptions<State> extends UrlStoreOptions {
+    resetOnCommit?: readonly (keyof State)[];
+    onSynced?: () => void;
+}
+export declare const createUrlState: <State>(codec: UrlStateCodec<State>, options?: UrlStateOptions<State>) => SyncedState<State, URLSearchParams>;

package/dist/url-state/url-store.svelte.js

@@ -0,0 +1,56 @@
+import { goto } from "$app/navigation";
+import { page } from "$app/state";
+import { BROWSER } from "esm-env";
+import { untrack } from "svelte";
+import { pickParams, sameLocation, withOwnedParams } from "./search-params.js";
+import { SyncedState } from "./synced-state.svelte.js";
+let pendingWrite;
+const currentUrl = () => new URL(pendingWrite?.href ?? page.url.href);
+export const urlStore = (ownedParams, options = {}) => {
+    const { replace = false } = options;
+    let lastSeenHref;
+    const replaces = (previous, next) => typeof replace === "function" ? replace(previous, next) : replace;
+    return {
+        read: () => currentUrl().searchParams,
+        write: (params) => {
+            if (!BROWSER)
+                return;
+            const base = currentUrl();
+            const target = withOwnedParams(base, ownedParams, params);
+            if (sameLocation(base, target))
+                return;
+            const write = {
+                href: target.href,
+                replace: replaces(pickParams(base.searchParams, ownedParams), params) &&
+                    (pendingWrite?.replace ?? true),
+            };
+            lastSeenHref = write.href;
+            pendingWrite = write;
+            void goto(write.href, {
+                keepFocus: true,
+                noScroll: true,
+                replaceState: write.replace,
+            }).finally(() => {
+                if (pendingWrite === write)
+                    pendingWrite = undefined;
+            });
+        },
+        subscribe: (onChange) => {
+            $effect(() => {
+                const href = page.url.href;
+                if (pendingWrite?.href === href)
+                    pendingWrite = undefined;
+                if (href === lastSeenHref)
+                    return;
+                lastSeenHref = href;
+                untrack(onChange);
+            });
+        },
+    };
+};
+export const createUrlState = (codec, options = {}) => new SyncedState({
+    codec,
+    store: urlStore(codec.ownedParams(), { replace: options.replace }),
+    resetOnCommit: options.resetOnCommit,
+    onSynced: options.onSynced,
+});

package/dist/virtual/DataList.svelte

@@ -0,0 +1,215 @@
+<script lang="ts" generics="Row">
+  import { untrack, type Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import Skeleton from "../components/Skeleton.svelte";
+  import { DEFAULT_DATA_LIST_LABELS, type DataListFailure, type DataListLabels } from "./labels.js";
+  import type { ScrollAlign } from "./range.js";
+  import VirtualList from "./VirtualList.svelte";
+  import type { WindowedData } from "./windowed-data.svelte.js";
+  import { WindowedVirtualizer } from "./windowed-virtualizer.svelte.js";
+
+  type PlaceholderStatus = "loading" | "error";
+
+  interface Props {
+    data: WindowedData<Row>;
+    row: Snippet<[Row, number]>;
+    placeholder?: Snippet<[number, PlaceholderStatus]>;
+    empty?: Snippet;
+    error?: Snippet<[DataListFailure]>;
+    itemSize?: number | ((index: number) => number);
+    overscan?: number;
+    placeholderCount?: number;
+    class?: ClassValue;
+    crossSize?: number | string;
+    label?: string;
+    labels?: Partial<DataListLabels>;
+  }
+
+  let {
+    data,
+    row,
+    placeholder,
+    empty,
+    error,
+    itemSize = 48,
+    overscan = 6,
+    placeholderCount = 8,
+    class: className,
+    crossSize,
+    label,
+    labels,
+  }: Props = $props();
+
+  const text = $derived({ ...DEFAULT_DATA_LIST_LABELS, ...labels });
+
+  const estimate = (index: number) => (typeof itemSize === "function" ? itemSize(index) : itemSize);
+
+  const virtualizer = untrack(
+    () => new WindowedVirtualizer({ data, estimateSize: estimate, overscan: () => overscan }),
+  );
+
+  const retryPages = () => data.retry();
+
+  const failure: DataListFailure | null = $derived(
+    data.failures.length === 0
+      ? null
+      : { error: data.error, pages: data.failedPages, retry: retryPages },
+  );
+
+  const phase = $derived.by(() => {
+    if (data.resolved) return data.count === 0 ? "empty" : "ready";
+    return failure ? "failed" : "pending";
+  });
+
+  const placeholderIndices = $derived(
+    Array.from({ length: Math.max(0, placeholderCount) }, (_, index) => index),
+  );
+
+  export function scrollToIndex(index: number, align?: ScrollAlign): void {
+    virtualizer.scrollToIndex(index, align);
+  }
+
+  export function scrollToOffset(offset: number): void {
+    virtualizer.scrollToOffset(offset);
+  }
+
+  export function scrollToEnd(): void {
+    virtualizer.scrollToEnd();
+  }
+
+  export function retry(): void {
+    retryPages();
+  }
+</script>
+
+{#snippet placeholderView(index: number, status: PlaceholderStatus)}
+  {#if placeholder}
+    {@render placeholder(index, status)}
+  {:else}
+    <div
+      class="plinth-data-placeholder"
+      data-status={status}
+      style:block-size="{estimate(index)}px"
+    >
+      {#if status === "error"}
+        <span class="plinth-data-failed"></span>
+      {:else}
+        <Skeleton class="plinth-data-skeleton" />
+      {/if}
+    </div>
+  {/if}
+{/snippet}
+
+{#snippet failureView(current: DataListFailure)}
+  {#if error}
+    {@render error(current)}
+  {:else}
+    <span>{text.error}</span>
+    <button type="button" class="btn btn-ghost btn-xs" onclick={current.retry}>{text.retry}</button>
+  {/if}
+{/snippet}
+
+<div
+  class={["plinth-data-list", className]}
+  aria-busy={phase === "pending" || data.loading}
+  data-phase={phase}
+>
+  {#if phase === "failed" && failure}
+    <div class="plinth-data-state plinth-data-error" role="alert">
+      {@render failureView(failure)}
+    </div>
+  {:else if phase === "pending"}
+    <div class="plinth-data-placeholders" role="status" aria-label={text.loading}>
+      {#each placeholderIndices as index (index)}
+        {@render placeholderView(index, "loading")}
+      {/each}
+    </div>
+  {:else if phase === "empty"}
+    <div class="plinth-data-state">
+      {#if empty}{@render empty()}{:else}{text.empty}{/if}
+    </div>
+  {:else}
+    {#if failure}
+      <div class="plinth-data-banner plinth-data-error" role="alert">
+        {@render failureView(failure)}
+      </div>
+    {/if}
+    <VirtualList {virtualizer} class="plinth-data-viewport" {crossSize} {label}>
+      {#snippet item(index)}
+        {@const value = data.get(index)}
+        {#if value !== undefined}
+          {@render row(value, index)}
+        {:else}
+          {@render placeholderView(index, data.statusOf(index) === "error" ? "error" : "loading")}
+        {/if}
+      {/snippet}
+    </VirtualList>
+  {/if}
+</div>
+
+<style>
+  .plinth-data-list {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  .plinth-data-list > :global(.plinth-data-viewport) {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  .plinth-data-placeholders {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  .plinth-data-placeholder {
+    display: flex;
+    align-items: center;
+    padding-inline: 1rem;
+  }
+
+  .plinth-data-placeholder :global(.plinth-data-skeleton) {
+    inline-size: 60%;
+    block-size: 0.75rem;
+  }
+
+  .plinth-data-failed {
+    display: block;
+    inline-size: 60%;
+    block-size: 0.75rem;
+    border: 1px dashed color-mix(in oklch, var(--color-error) 45%, transparent);
+    border-radius: var(--radius-field, 0.5rem);
+  }
+
+  .plinth-data-state {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 0.75rem;
+    padding: 2rem 1rem;
+    color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+    text-align: center;
+  }
+
+  .plinth-data-banner {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+    padding: 0.375rem 0.75rem;
+    border-bottom: 1px solid color-mix(in oklch, var(--color-error) 30%, transparent);
+    background: color-mix(in oklch, var(--color-error) 10%, transparent);
+    font-size: 0.875rem;
+  }
+
+  .plinth-data-state.plinth-data-error {
+    color: var(--color-base-content);
+  }
+</style>

package/dist/virtual/DataList.svelte.d.ts

@@ -0,0 +1,52 @@
+import { type Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import { type DataListFailure, type DataListLabels } from "./labels.js";
+import type { ScrollAlign } from "./range.js";
+import type { WindowedData } from "./windowed-data.svelte.js";
+declare function $$render<Row>(): {
+    props: {
+        data: WindowedData<Row>;
+        row: Snippet<[Row, number]>;
+        placeholder?: Snippet<[number, "error" | "loading"]>;
+        empty?: Snippet;
+        error?: Snippet<[DataListFailure]>;
+        itemSize?: number | ((index: number) => number);
+        overscan?: number;
+        placeholderCount?: number;
+        class?: ClassValue;
+        crossSize?: number | string;
+        label?: string;
+        labels?: Partial<DataListLabels>;
+    };
+    exports: {
+        scrollToIndex: (index: number, align?: ScrollAlign) => void;
+        scrollToOffset: (offset: number) => void;
+        scrollToEnd: () => void;
+        retry: () => void;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Row> {
+    props(): ReturnType<typeof $$render<Row>>['props'];
+    events(): ReturnType<typeof $$render<Row>>['events'];
+    slots(): ReturnType<typeof $$render<Row>>['slots'];
+    bindings(): "";
+    exports(): {
+        scrollToIndex: (index: number, align?: ScrollAlign) => void;
+        scrollToOffset: (offset: number) => void;
+        scrollToEnd: () => void;
+        retry: () => void;
+    };
+}
+interface $$IsomorphicComponent {
+    new <Row>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Row>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Row>['props']>, ReturnType<__sveltets_Render<Row>['events']>, ReturnType<__sveltets_Render<Row>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Row>['bindings']>;
+    } & ReturnType<__sveltets_Render<Row>['exports']>;
+    <Row>(internal: unknown, props: ReturnType<__sveltets_Render<Row>['props']> & {}): ReturnType<__sveltets_Render<Row>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DataList: $$IsomorphicComponent;
+type DataList<Row> = InstanceType<typeof DataList<Row>>;
+export default DataList;

package/dist/virtual/VirtualList.svelte

@@ -0,0 +1,150 @@
+<script lang="ts">
+  import { untrack, type Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import type { ScrollAlign } from "./range.js";
+  import { Virtualizer, type ItemKey, type ScrollAnchor } from "./virtualizer.svelte.js";
+
+  interface SharedProps {
+    item: Snippet<[number]>;
+    class?: ClassValue;
+    crossSize?: number | string;
+    label?: string;
+  }
+
+  interface OwnedProps {
+    count: number;
+    itemSize?: number | ((index: number) => number);
+    overscan?: number;
+    getItemKey?: (index: number) => ItemKey;
+    horizontal?: boolean;
+    anchorTo?: ScrollAnchor;
+    followOnAppend?: boolean;
+    initialOffset?: number;
+    virtualizer?: never;
+  }
+
+  interface ExternalProps {
+    virtualizer: Virtualizer;
+    count?: never;
+    itemSize?: never;
+    overscan?: never;
+    getItemKey?: never;
+    horizontal?: never;
+    anchorTo?: never;
+    followOnAppend?: never;
+    initialOffset?: never;
+  }
+
+  type Props = SharedProps & (OwnedProps | ExternalProps);
+
+  let {
+    item,
+    class: className,
+    crossSize,
+    label,
+    virtualizer: external,
+    count,
+    itemSize,
+    overscan,
+    getItemKey,
+    horizontal,
+    anchorTo,
+    followOnAppend,
+    initialOffset,
+  }: Props = $props();
+
+  const owned = () =>
+    new Virtualizer({
+      count: () => count ?? 0,
+      estimateSize: (index) =>
+        typeof itemSize === "function" ? itemSize(index) : (itemSize ?? 48),
+      overscan: () => overscan ?? 6,
+      getItemKey: (index) => getItemKey?.(index) ?? index,
+      horizontal,
+      anchorTo,
+      followOnAppend,
+      initialOffset,
+    });
+
+  const virtualizer = untrack(() => external ?? owned());
+
+  const crossLength = $derived(typeof crossSize === "number" ? `${crossSize}px` : crossSize);
+  const axis = $derived(virtualizer.horizontal ? "X" : "Y");
+
+  export function scrollToIndex(index: number, align?: ScrollAlign): void {
+    virtualizer.scrollToIndex(index, align);
+  }
+
+  export function scrollToOffset(offset: number): void {
+    virtualizer.scrollToOffset(offset);
+  }
+
+  export function scrollToEnd(): void {
+    virtualizer.scrollToEnd();
+  }
+
+  export function prepend(count: number): void {
+    virtualizer.prepend(count);
+  }
+
+  export function clearMeasurements(): void {
+    virtualizer.clearMeasurements();
+  }
+</script>
+
+<div
+  class={["plinth-virtual", className]}
+  class:plinth-virtual-horizontal={virtualizer.horizontal}
+  role={label === undefined ? undefined : "region"}
+  aria-label={label}
+  {@attach virtualizer.viewport}
+>
+  <div
+    class="plinth-virtual-content"
+    style:block-size={virtualizer.horizontal ? undefined : `${virtualizer.totalSize}px`}
+    style:inline-size={virtualizer.horizontal ? `${virtualizer.totalSize}px` : undefined}
+    style:min-inline-size={virtualizer.horizontal ? undefined : crossLength}
+    style:min-block-size={virtualizer.horizontal ? crossLength : undefined}
+  >
+    {#each virtualizer.items as entry (entry.key)}
+      <div
+        class="plinth-virtual-item"
+        data-index={entry.index}
+        style:transform="translate{axis}({entry.start}px)"
+        {@attach virtualizer.measure(entry.index)}
+      >
+        {@render item(entry.index)}
+      </div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .plinth-virtual {
+    display: block;
+    position: relative;
+    overflow: auto;
+    overflow-anchor: none;
+  }
+
+  .plinth-virtual-content {
+    position: relative;
+    inline-size: 100%;
+  }
+
+  .plinth-virtual-horizontal > .plinth-virtual-content {
+    block-size: 100%;
+  }
+
+  .plinth-virtual-item {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+  }
+
+  .plinth-virtual-horizontal .plinth-virtual-item {
+    right: auto;
+    bottom: 0;
+  }
+</style>

package/dist/virtual/VirtualList.svelte.d.ts

@@ -0,0 +1,42 @@
+import { type Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import type { ScrollAlign } from "./range.js";
+import { Virtualizer, type ItemKey, type ScrollAnchor } from "./virtualizer.svelte.js";
+interface SharedProps {
+    item: Snippet<[number]>;
+    class?: ClassValue;
+    crossSize?: number | string;
+    label?: string;
+}
+interface OwnedProps {
+    count: number;
+    itemSize?: number | ((index: number) => number);
+    overscan?: number;
+    getItemKey?: (index: number) => ItemKey;
+    horizontal?: boolean;
+    anchorTo?: ScrollAnchor;
+    followOnAppend?: boolean;
+    initialOffset?: number;
+    virtualizer?: never;
+}
+interface ExternalProps {
+    virtualizer: Virtualizer;
+    count?: never;
+    itemSize?: never;
+    overscan?: never;
+    getItemKey?: never;
+    horizontal?: never;
+    anchorTo?: never;
+    followOnAppend?: never;
+    initialOffset?: never;
+}
+type Props = SharedProps & (OwnedProps | ExternalProps);
+declare const VirtualList: import("svelte").Component<Props, {
+    scrollToIndex: (index: number, align?: ScrollAlign) => void;
+    scrollToOffset: (offset: number) => void;
+    scrollToEnd: () => void;
+    prepend: (count: number) => void;
+    clearMeasurements: () => void;
+}, "">;
+type VirtualList = ReturnType<typeof VirtualList>;
+export default VirtualList;

package/dist/virtual/index.d.ts

@@ -0,0 +1,7 @@
+export { Virtualizer, type ItemKey, type ScrollAnchor, type VirtualItem, type VirtualizerOptions, } from "./virtualizer.svelte.js";
+export type { ScrollAlign } from "./range.js";
+export { WindowedData, type PageFailure, type PageRequest, type PageStatus, type WindowedDataOptions, type WindowedPage, } from "./windowed-data.svelte.js";
+export { WindowedVirtualizer, type WindowedVirtualizerOptions, } from "./windowed-virtualizer.svelte.js";
+export { DEFAULT_DATA_LIST_LABELS, type DataListFailure, type DataListLabels } from "./labels.js";
+export { default as VirtualList } from "./VirtualList.svelte";
+export { default as DataList } from "./DataList.svelte";

package/dist/virtual/index.js

@@ -0,0 +1,6 @@
+export { Virtualizer, } from "./virtualizer.svelte.js";
+export { WindowedData, } from "./windowed-data.svelte.js";
+export { WindowedVirtualizer, } from "./windowed-virtualizer.svelte.js";
+export { DEFAULT_DATA_LIST_LABELS } from "./labels.js";
+export { default as VirtualList } from "./VirtualList.svelte";
+export { default as DataList } from "./DataList.svelte";

package/dist/virtual/keyed-cache.d.ts

@@ -0,0 +1,7 @@
+export declare class KeyedCache<K, V> {
+    #private;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    getOrCreate(key: K, create: (key: K) => V): V;
+    clear(): void;
+}

package/dist/virtual/keyed-cache.js

@@ -0,0 +1,20 @@
+export class KeyedCache {
+    #entries = new Map();
+    get(key) {
+        return this.#entries.get(key);
+    }
+    set(key, value) {
+        this.#entries.set(key, value);
+    }
+    getOrCreate(key, create) {
+        const existing = this.#entries.get(key);
+        if (existing !== undefined)
+            return existing;
+        const created = create(key);
+        this.#entries.set(key, created);
+        return created;
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}

package/dist/virtual/labels.d.ts

@@ -0,0 +1,12 @@
+export interface DataListLabels {
+    loading: string;
+    empty: string;
+    error: string;
+    retry: string;
+}
+export declare const DEFAULT_DATA_LIST_LABELS: DataListLabels;
+export interface DataListFailure {
+    error: unknown;
+    pages: number[];
+    retry: () => void;
+}

package/dist/virtual/labels.js

@@ -0,0 +1,6 @@
+export const DEFAULT_DATA_LIST_LABELS = {
+    loading: "Loading",
+    empty: "Nothing to show",
+    error: "Some rows could not be loaded.",
+    retry: "Retry",
+};

package/dist/virtual/paging.d.ts

@@ -0,0 +1,5 @@
+export interface PageSpan {
+    first: number;
+    last: number;
+}
+export declare const pageSpan: (start: number, end: number, pageSize: number, knownCount: number | null) => PageSpan | null;

package/dist/virtual/paging.js

@@ -0,0 +1,11 @@
+export const pageSpan = (start, end, pageSize, knownCount) => {
+    const first = Math.floor(Math.max(0, start) / pageSize);
+    const last = Math.max(first, Math.floor(Math.max(0, end) / pageSize));
+    if (knownCount === null)
+        return { first, last };
+    if (knownCount <= 0)
+        return null;
+    const lastPage = Math.ceil(knownCount / pageSize) - 1;
+    const cappedLast = Math.min(last, lastPage);
+    return { first: Math.min(first, cappedLast), last: cappedLast };
+};

package/dist/virtual/range.d.ts

@@ -0,0 +1,9 @@
+import type { SizeTree } from "./size-tree.js";
+export type ScrollAlign = "start" | "center" | "end" | "auto";
+export interface IndexRange {
+    from: number;
+    to: number;
+}
+export declare const visibleRange: (tree: SizeTree, scrollOffset: number, viewportSize: number, overscan: number) => IndexRange | null;
+export declare const alignedOffset: (start: number, size: number, viewportSize: number, scrollOffset: number, align: ScrollAlign) => number | null;
+export declare const clampOffset: (offset: number, totalSize: number, viewportSize: number) => number;

package/dist/virtual/range.js

@@ -0,0 +1,31 @@
+export const visibleRange = (tree, scrollOffset, viewportSize, overscan) => {
+    if (tree.length === 0)
+        return null;
+    const first = tree.indexAt(scrollOffset);
+    const viewEnd = scrollOffset + viewportSize;
+    let last = first;
+    let edge = tree.startOf(first);
+    while (last < tree.length && edge < viewEnd) {
+        edge += tree.sizeAt(last);
+        last++;
+    }
+    const extra = Math.max(0, Math.floor(overscan));
+    return {
+        from: Math.max(0, first - extra),
+        to: Math.min(tree.length, Math.max(last, first + 1) + extra),
+    };
+};
+export const alignedOffset = (start, size, viewportSize, scrollOffset, align) => {
+    if (align === "start")
+        return start;
+    if (align === "end")
+        return start + size - viewportSize;
+    if (align === "center")
+        return start + size / 2 - viewportSize / 2;
+    if (start < scrollOffset)
+        return start;
+    if (start + size > scrollOffset + viewportSize)
+        return start + size - viewportSize;
+    return null;
+};
+export const clampOffset = (offset, totalSize, viewportSize) => Math.min(Math.max(0, offset), Math.max(0, totalSize - viewportSize));

package/dist/virtual/size-tree.d.ts

@@ -0,0 +1,10 @@
+export declare class SizeTree {
+    #private;
+    readonly length: number;
+    constructor(sizes: ArrayLike<number>);
+    get total(): number;
+    sizeAt(index: number): number;
+    set(index: number, size: number): boolean;
+    startOf(index: number): number;
+    indexAt(offset: number): number;
+}