@viniaraujo68/plinth 0.3.1 → 0.6.0

package/dist/virtual/size-tree.js

@@ -0,0 +1,56 @@
+export class SizeTree {
+    length;
+    #sizes;
+    #sums;
+    #topStep;
+    constructor(sizes) {
+        const length = sizes.length;
+        this.length = length;
+        this.#sizes = Float64Array.from(sizes);
+        this.#sums = new Float64Array(length + 1);
+        for (let node = 1; node <= length; node++) {
+            this.#sums[node] += this.#sizes[node - 1];
+            const parent = node + (node & -node);
+            if (parent <= length)
+                this.#sums[parent] += this.#sums[node];
+        }
+        this.#topStep = length === 0 ? 0 : 2 ** Math.floor(Math.log2(length));
+    }
+    get total() {
+        return this.startOf(this.length);
+    }
+    sizeAt(index) {
+        return index >= 0 && index < this.length ? this.#sizes[index] : 0;
+    }
+    set(index, size) {
+        if (index < 0 || index >= this.length)
+            return false;
+        const delta = size - this.#sizes[index];
+        if (delta === 0)
+            return false;
+        this.#sizes[index] = size;
+        for (let node = index + 1; node <= this.length; node += node & -node)
+            this.#sums[node] += delta;
+        return true;
+    }
+    startOf(index) {
+        let sum = 0;
+        for (let node = Math.min(Math.max(0, index), this.length); node > 0; node -= node & -node)
+            sum += this.#sums[node];
+        return sum;
+    }
+    indexAt(offset) {
+        if (this.length === 0)
+            return -1;
+        let position = 0;
+        let remaining = offset;
+        for (let step = this.#topStep; step > 0; step = Math.floor(step / 2)) {
+            const next = position + step;
+            if (next <= this.length && this.#sums[next] <= remaining) {
+                position = next;
+                remaining -= this.#sums[next];
+            }
+        }
+        return Math.min(position, this.length - 1);
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { Attachment } from "svelte/attachments";
+import { type ScrollAlign } from "./range.js";
+export type ItemKey = string | number;
+export type ScrollAnchor = "start" | "end";
+export interface VirtualItem {
+    index: number;
+    key: ItemKey;
+    start: number;
+    size: number;
+}
+export interface VirtualizerOptions {
+    count: () => number;
+    estimateSize?: number | ((index: number) => number);
+    overscan?: number | (() => number);
+    getItemKey?: (index: number) => ItemKey;
+    horizontal?: boolean;
+    anchorTo?: ScrollAnchor;
+    followOnAppend?: boolean;
+    initialOffset?: number | (() => number);
+}
+export declare class Virtualizer {
+    #private;
+    readonly horizontal: boolean;
+    readonly anchorTo: ScrollAnchor;
+    readonly items: VirtualItem[];
+    constructor(options: VirtualizerOptions);
+    get totalSize(): number;
+    get scrollOffset(): number;
+    get viewportSize(): number;
+    get isScrolling(): boolean;
+    viewport: Attachment<HTMLElement>;
+    measure: (index: number) => Attachment<HTMLElement>;
+    scrollToOffset(offset: number): void;
+    scrollToEnd(): void;
+    scrollToIndex(index: number, align?: ScrollAlign): void;
+    prepend(count: number): void;
+    clearMeasurements(): void;
+}

package/dist/virtual/virtualizer.svelte.js

@@ -0,0 +1,295 @@
+import { untrack } from "svelte";
+import { KeyedCache } from "./keyed-cache.js";
+import { alignedOffset, clampOffset, visibleRange } from "./range.js";
+import { SizeTree } from "./size-tree.js";
+const DEFAULT_ESTIMATE = 48;
+const DEFAULT_OVERSCAN = 6;
+const SCROLL_IDLE_MS = 150;
+const END_TOLERANCE = 4;
+const SUBPIXEL = 0.5;
+export class Virtualizer {
+    horizontal;
+    anchorTo;
+    #count;
+    #estimate;
+    #overscan;
+    #keyOf;
+    #followOnAppend;
+    #initialOffset;
+    #scrollOffset = $state(0);
+    #viewportSize = $state(0);
+    #isScrolling = $state(false);
+    #measured = $state.raw(new KeyedCache());
+    #measureAttachments = new KeyedCache();
+    #element;
+    #idleTimer;
+    #anchorIndex = 0;
+    #anchorDelta = 0;
+    #atEnd = false;
+    #previousCount = 0;
+    #skipNextFollow = false;
+    #ownScrollOffset = null;
+    #scrollRequest = 0;
+    #deferredTarget = null;
+    #initialApplied = false;
+    #layout = $derived.by(() => {
+        const count = Math.max(0, Math.floor(this.#count()));
+        const measured = this.#measured;
+        const sizes = new Float64Array(count);
+        for (let index = 0; index < count; index++)
+            sizes[index] = measured.get(this.#keyOf(index)) ?? this.#estimate(index);
+        return { tree: new SizeTree(sizes) };
+    });
+    items = $derived.by(() => {
+        const { tree } = this.#layout;
+        const range = visibleRange(tree, this.#scrollOffset, this.#viewportSize, this.#overscan());
+        if (!range)
+            return [];
+        const items = [];
+        let start = tree.startOf(range.from);
+        for (let index = range.from; index < range.to; index++) {
+            const size = tree.sizeAt(index);
+            items.push({ index, key: this.#keyOf(index), start, size });
+            start += size;
+        }
+        return items;
+    });
+    constructor(options) {
+        const { estimateSize = DEFAULT_ESTIMATE, overscan = DEFAULT_OVERSCAN } = options;
+        this.#count = options.count;
+        this.#estimate = typeof estimateSize === "function" ? estimateSize : () => estimateSize;
+        this.#overscan = typeof overscan === "function" ? overscan : () => overscan;
+        this.#keyOf = options.getItemKey ?? ((index) => index);
+        this.horizontal = options.horizontal ?? false;
+        this.anchorTo = options.anchorTo ?? "start";
+        this.#followOnAppend = options.followOnAppend ?? false;
+        this.#initialOffset = options.initialOffset;
+        $effect(() => {
+            const { tree } = this.#layout;
+            const viewportSize = this.#viewportSize;
+            untrack(() => this.#holdAnchor(tree, viewportSize));
+        });
+        $effect(() => {
+            const count = this.#count();
+            untrack(() => this.#countChanged(count));
+        });
+    }
+    get totalSize() {
+        return this.#layout.tree.total;
+    }
+    get scrollOffset() {
+        return this.#scrollOffset;
+    }
+    get viewportSize() {
+        return this.#viewportSize;
+    }
+    get isScrolling() {
+        return this.#isScrolling;
+    }
+    viewport = (element) => untrack(() => {
+        this.#element = element;
+        this.#viewportSize = this.#clientSize(element);
+        this.#scrollOffset = this.#readScroll(element);
+        this.#captureAnchor();
+        const deferred = this.#deferredTarget;
+        this.#deferredTarget = null;
+        if (deferred) {
+            this.#scrollTo(deferred);
+        }
+        else if (!this.#initialApplied && this.#initialOffset !== undefined) {
+            const initial = this.#initialOffset;
+            this.#scrollTo(typeof initial === "function" ? initial : () => initial);
+        }
+        this.#initialApplied = true;
+        const onScroll = () => this.#userScrolled(element);
+        const observer = new ResizeObserver(() => {
+            this.#viewportSize = this.#clientSize(element);
+        });
+        element.addEventListener("scroll", onScroll, { passive: true });
+        observer.observe(element);
+        return () => {
+            element.removeEventListener("scroll", onScroll);
+            observer.disconnect();
+            clearTimeout(this.#idleTimer);
+            this.#isScrolling = false;
+            if (this.#element === element)
+                this.#element = undefined;
+        };
+    });
+    measure = (index) => this.#measureAttachments.getOrCreate(index, () => (element) => {
+        const observer = new ResizeObserver(([entry]) => this.#report(index, element, entry));
+        observer.observe(element);
+        return () => observer.disconnect();
+    });
+    scrollToOffset(offset) {
+        if (Number.isNaN(offset))
+            return;
+        this.#scrollTo(() => offset);
+    }
+    scrollToEnd() {
+        this.#scrollTo(() => Number.POSITIVE_INFINITY);
+    }
+    scrollToIndex(index, align = "start") {
+        if (Number.isNaN(index))
+            return;
+        untrack(() => {
+            const { tree } = this.#layout;
+            if (tree.length === 0)
+                return;
+            const target = Math.min(Math.max(0, Math.trunc(index)), tree.length - 1);
+            const resolved = align === "auto" ? this.#autoAlign(tree, target) : align;
+            if (!resolved)
+                return;
+            this.#scrollTo(() => {
+                const current = this.#layout.tree;
+                if (target >= current.length)
+                    return null;
+                return alignedOffset(current.startOf(target), current.sizeAt(target), this.#viewportSize, this.#scrollOffset, resolved);
+            });
+        });
+    }
+    prepend(count) {
+        if (!(count > 0))
+            return;
+        this.#anchorIndex += Math.floor(count);
+        this.#skipNextFollow = true;
+    }
+    clearMeasurements() {
+        untrack(() => {
+            this.#measured = new KeyedCache();
+            this.#measureAttachments.clear();
+            this.#captureAnchor();
+        });
+    }
+    #autoAlign(tree, index) {
+        const start = tree.startOf(index);
+        const end = start + tree.sizeAt(index);
+        if (start < this.#scrollOffset)
+            return "start";
+        if (end > this.#scrollOffset + this.#viewportSize)
+            return "end";
+        return null;
+    }
+    #report(index, element, entry) {
+        untrack(() => {
+            const size = this.#sizeOf(element, entry);
+            if (!(size > 0))
+                return;
+            const { tree } = this.#layout;
+            if (index >= tree.length)
+                return;
+            this.#measured.set(this.#keyOf(index), size);
+            if (tree.set(index, size))
+                this.#layout = { tree };
+        });
+    }
+    #sizeOf(element, entry) {
+        const box = entry?.borderBoxSize[0];
+        if (box)
+            return this.horizontal ? box.inlineSize : box.blockSize;
+        const rect = element.getBoundingClientRect();
+        return this.horizontal ? rect.width : rect.height;
+    }
+    #userScrolled(element) {
+        const offset = this.#readScroll(element);
+        this.#scrollOffset = offset;
+        const own = this.#ownScrollOffset;
+        this.#ownScrollOffset = null;
+        if (own !== null && Math.abs(offset - own) < SUBPIXEL)
+            return;
+        this.#scrollRequest++;
+        this.#atEnd = this.#isAtEnd(offset);
+        this.#captureAnchor();
+        this.#isScrolling = true;
+        clearTimeout(this.#idleTimer);
+        this.#idleTimer = setTimeout(() => (this.#isScrolling = false), SCROLL_IDLE_MS);
+    }
+    #scrollTo(target) {
+        untrack(() => {
+            const element = this.#element;
+            if (!element) {
+                this.#deferredTarget = target;
+                return;
+            }
+            const request = ++this.#scrollRequest;
+            this.#applyScroll(element, target);
+            requestAnimationFrame(() => {
+                const current = this.#element;
+                if (request === this.#scrollRequest && current)
+                    this.#applyScroll(current, target);
+            });
+        });
+    }
+    #applyScroll(element, target) {
+        untrack(() => {
+            const offset = target();
+            if (offset === null)
+                return;
+            this.#writeScroll(element, clampOffset(offset, this.totalSize, this.#viewportSize));
+            this.#atEnd = this.#isAtEnd(this.#scrollOffset);
+            this.#captureAnchor();
+        });
+    }
+    #holdAnchor(tree, viewportSize) {
+        const element = this.#element;
+        if (!element || tree.length === 0)
+            return;
+        if (this.#anchorIndex >= tree.length) {
+            this.#anchorIndex = tree.length - 1;
+            this.#anchorDelta = 0;
+        }
+        const desired = Math.max(0, this.#anchoredOffset(tree, viewportSize));
+        if (Math.abs(desired - this.#readScroll(element)) > SUBPIXEL)
+            this.#writeScroll(element, desired);
+    }
+    #countChanged(count) {
+        const grew = count > this.#previousCount;
+        const skip = this.#skipNextFollow;
+        this.#previousCount = count;
+        this.#skipNextFollow = false;
+        if (count === 0) {
+            this.#anchorIndex = 0;
+            this.#anchorDelta = 0;
+        }
+        if (grew && !skip && this.#followOnAppend && this.#atEnd)
+            this.scrollToEnd();
+    }
+    #anchoredOffset(tree, viewportSize) {
+        if (this.anchorTo === "end")
+            return tree.startOf(this.#anchorIndex + 1) - viewportSize - this.#anchorDelta;
+        return tree.startOf(this.#anchorIndex) - this.#anchorDelta;
+    }
+    #captureAnchor() {
+        const { tree } = this.#layout;
+        if (tree.length === 0) {
+            this.#anchorIndex = 0;
+            this.#anchorDelta = 0;
+            return;
+        }
+        if (this.anchorTo === "end") {
+            const bottom = this.#scrollOffset + this.#viewportSize;
+            this.#anchorIndex = tree.indexAt(Math.max(0, bottom - 1));
+            this.#anchorDelta = tree.startOf(this.#anchorIndex + 1) - bottom;
+            return;
+        }
+        this.#anchorIndex = tree.indexAt(this.#scrollOffset);
+        this.#anchorDelta = tree.startOf(this.#anchorIndex) - this.#scrollOffset;
+    }
+    #isAtEnd(offset) {
+        return offset + this.#viewportSize >= this.totalSize - END_TOLERANCE;
+    }
+    #clientSize(element) {
+        return this.horizontal ? element.clientWidth : element.clientHeight;
+    }
+    #readScroll(element) {
+        return this.horizontal ? element.scrollLeft : element.scrollTop;
+    }
+    #writeScroll(element, offset) {
+        if (this.horizontal)
+            element.scrollLeft = offset;
+        else
+            element.scrollTop = offset;
+        this.#ownScrollOffset = this.#readScroll(element);
+        this.#scrollOffset = this.#ownScrollOffset;
+    }
+}

package/dist/virtual/windowed-data.svelte.d.ts

@@ -0,0 +1,38 @@
+export interface WindowedPage<Row> {
+    items: readonly Row[];
+    total: number;
+}
+export interface PageRequest {
+    page: number;
+    offset: number;
+    limit: number;
+    signal: AbortSignal;
+}
+export interface WindowedDataOptions<Row> {
+    pageSize: number;
+    fetchPage: (request: PageRequest) => Promise<WindowedPage<Row>>;
+    retain?: number;
+    signature?: () => string;
+}
+export type PageStatus = "loading" | "ready" | "error";
+export interface PageFailure {
+    page: number;
+    error: unknown;
+}
+export declare class WindowedData<Row> {
+    #private;
+    readonly pageSize: number;
+    readonly retain: number;
+    readonly failures: PageFailure[];
+    readonly loading: boolean;
+    constructor(options: WindowedDataOptions<Row>);
+    get count(): number;
+    get resolved(): boolean;
+    get failedPages(): number[];
+    get error(): unknown;
+    get(index: number): Row | undefined;
+    statusOf(index: number): PageStatus | "idle";
+    ensure(start: number, end: number): void;
+    retry(): void;
+    dispose(): void;
+}

package/dist/virtual/windowed-data.svelte.js

@@ -0,0 +1,139 @@
+import { untrack } from "svelte";
+import { SvelteMap } from "svelte/reactivity";
+import { pageSpan } from "./paging.js";
+const DEFAULT_RETAIN = 2;
+class PageSlot {
+    status = $state("loading");
+    rows = $state.raw([]);
+    error = $state.raw(undefined);
+    controller = null;
+    released = false;
+}
+export class WindowedData {
+    pageSize;
+    retain;
+    #fetchPage;
+    #signature;
+    #slots = new SvelteMap();
+    #currentSignature;
+    #disposed = false;
+    #count = $state(0);
+    #resolved = $state(false);
+    failures = $derived.by(() => [...this.#slots]
+        .filter(([, slot]) => slot.status === "error")
+        .map(([page, slot]) => ({ page, error: slot.error }))
+        .sort((left, right) => left.page - right.page));
+    loading = $derived.by(() => [...this.#slots.values()].some((slot) => slot.status === "loading"));
+    constructor(options) {
+        this.pageSize = Math.max(1, Math.floor(options.pageSize));
+        this.retain = Math.max(0, Math.floor(options.retain ?? DEFAULT_RETAIN));
+        this.#fetchPage = options.fetchPage;
+        this.#signature = options.signature;
+    }
+    get count() {
+        return this.#count;
+    }
+    get resolved() {
+        return this.#resolved;
+    }
+    get failedPages() {
+        return this.failures.map((failure) => failure.page);
+    }
+    get error() {
+        return this.failures[0]?.error;
+    }
+    get(index) {
+        if (!(index >= 0))
+            return undefined;
+        const slot = this.#slots.get(Math.floor(index / this.pageSize));
+        if (slot?.status !== "ready")
+            return undefined;
+        return slot.rows[index % this.pageSize];
+    }
+    statusOf(index) {
+        if (!(index >= 0))
+            return "idle";
+        return this.#slots.get(Math.floor(index / this.pageSize))?.status ?? "idle";
+    }
+    ensure(start, end) {
+        if (this.#disposed)
+            return;
+        const signature = this.#signature?.() ?? "";
+        untrack(() => {
+            if (signature !== this.#currentSignature)
+                this.#rekey(signature);
+            const span = pageSpan(start, end, this.pageSize, this.#resolved ? this.#count : null);
+            if (!span)
+                return;
+            for (let page = span.first; page <= span.last; page++) {
+                if (this.#slots.has(page))
+                    continue;
+                const slot = new PageSlot();
+                this.#slots.set(page, slot);
+                this.#load(page, slot);
+            }
+            for (const [page, slot] of this.#slots) {
+                if (page >= span.first - this.retain && page <= span.last + this.retain)
+                    continue;
+                this.#release(slot);
+                this.#slots.delete(page);
+            }
+        });
+    }
+    retry() {
+        if (this.#disposed)
+            return;
+        untrack(() => {
+            for (const [page, slot] of this.#slots)
+                if (slot.status === "error")
+                    this.#load(page, slot);
+        });
+    }
+    dispose() {
+        this.#disposed = true;
+        untrack(() => this.#releaseAll());
+    }
+    #rekey(signature) {
+        this.#releaseAll();
+        this.#currentSignature = signature;
+        this.#count = 0;
+        this.#resolved = false;
+    }
+    #load(page, slot) {
+        const controller = new AbortController();
+        slot.controller = controller;
+        slot.status = "loading";
+        slot.error = undefined;
+        const settled = (apply) => {
+            if (slot.released || controller.signal.aborted)
+                return;
+            slot.controller = null;
+            apply();
+        };
+        const request = (async () => this.#fetchPage({
+            page,
+            offset: page * this.pageSize,
+            limit: this.pageSize,
+            signal: controller.signal,
+        }))();
+        void request.then((result) => settled(() => {
+            slot.rows = result.items;
+            slot.status = "ready";
+            this.#count = Math.max(0, Math.floor(result.total));
+            this.#resolved = true;
+        }), (error) => settled(() => {
+            slot.error = error;
+            slot.status = "error";
+        }));
+    }
+    #release(slot) {
+        slot.released = true;
+        slot.controller?.abort();
+        slot.controller = null;
+    }
+    #releaseAll() {
+        for (const slot of this.#slots.values())
+            this.#release(slot);
+        this.#slots.clear();
+    }
+}

package/dist/virtual/windowed-virtualizer.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { WindowedData } from "./windowed-data.svelte.js";
+import { Virtualizer, type VirtualizerOptions } from "./virtualizer.svelte.js";
+export interface WindowedVirtualizerOptions<Row> extends Omit<VirtualizerOptions, "count"> {
+    data: WindowedData<Row>;
+}
+export declare class WindowedVirtualizer<Row> extends Virtualizer {
+    readonly data: WindowedData<Row>;
+    constructor({ data, ...options }: WindowedVirtualizerOptions<Row>);
+}

package/dist/virtual/windowed-virtualizer.svelte.js

@@ -0,0 +1,22 @@
+import { untrack } from "svelte";
+import { Virtualizer } from "./virtualizer.svelte.js";
+export class WindowedVirtualizer extends Virtualizer {
+    data;
+    constructor({ data, ...options }) {
+        super({ ...options, count: () => data.count });
+        this.data = data;
+        $effect(() => {
+            const items = this.items;
+            const first = items.at(0)?.index ?? 0;
+            const last = items.at(-1)?.index ?? first;
+            data.ensure(first, last);
+        });
+        let hadRows = false;
+        $effect(() => {
+            const count = data.count;
+            if (count === 0 && hadRows)
+                untrack(() => this.clearMeasurements());
+            hadRows = count > 0;
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viniaraujo68/plinth",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "description": "A personal Svelte 5 design system: theme, application shell, interface primitives, routing metadata, a fetch wrapper and locale-aware formatters.",
   "license": "MIT",
   "type": "module",
@@ -96,6 +96,18 @@
       "types": "./dist/formatters.d.ts",
       "default": "./dist/formatters.js"
     },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "svelte": "./dist/i18n/index.js"
+    },
+    "./virtual": {
+      "types": "./dist/virtual/index.d.ts",
+      "svelte": "./dist/virtual/index.js"
+    },
+    "./url-state": {
+      "types": "./dist/url-state/index.d.ts",
+      "svelte": "./dist/url-state/index.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {