@streamscloud/kit 0.55.0 → 0.56.0

package/dist/core/data-loaders/cursor-data-loader-with-search.svelte.d.ts

@@ -2,13 +2,14 @@ import { ContinuationToken, type CursorResult } from '..';
 import type { IDataLoader } from './data-loader';
 export declare class CursorDataLoaderWithSearch<T> implements IDataLoader<T> {
     items: T[];
-    private continuationToken;
+    private _continuationToken;
     private _searchString;
-    private loadPage;
-    private pending;
-    private generation;
-    private searchStringMinLength;
+    private _loadPage;
+    private _pending;
+    private _generation;
+    private _searchStringMinLength;
     private _loading;
+    private _failed;
     constructor(init: {
         loadPage: (continuationToken: ContinuationToken, searchString: string) => Promise<CursorResult<T> | null>;
         searchStringMinLength?: number;
@@ -16,6 +17,7 @@ export declare class CursorDataLoaderWithSearch<T> implements IDataLoader<T> {
     get searchString(): string;
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset(): Promise<void>;
     updateSearchString: (searchString: string | null) => void;

package/dist/core/data-loaders/cursor-data-loader-with-search.svelte.js

@@ -2,17 +2,18 @@ import { ContinuationToken } from '..';
 import { Utils } from '../utils';
 export class CursorDataLoaderWithSearch {
     items = $state.raw([]);
-    continuationToken = $state.raw(ContinuationToken.init());
+    _continuationToken = $state.raw(ContinuationToken.init());
     _searchString = $state.raw('');
-    loadPage;
-    pending = null;
-    generation = 0;
-    searchStringMinLength = 1;
+    _loadPage;
+    _pending = null;
+    _generation = 0;
+    _searchStringMinLength = 1;
     _loading = $state(false);
+    _failed = $state(false);
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
         if (init.searchStringMinLength !== undefined) {
-            this.searchStringMinLength = init.searchStringMinLength;
+            this._searchStringMinLength = init.searchStringMinLength;
         }
         this.updateSearchString = Utils.debounce(this.updateSearchString, 400);
     }
@@ -25,33 +26,36 @@ export class CursorDataLoaderWithSearch {
     get initialLoading() {
         return this._loading && this.items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this.pending) {
-            return this.pending;
+        if (this._pending) {
+            return this._pending;
         }
-        if (!this.continuationToken.canLoadMore) {
+        if (!this._continuationToken.canLoadMore) {
             return [];
         }
         this._loading = true;
         const pending = this.runLoad();
-        this.pending = pending;
+        this._pending = pending;
         try {
             return await pending;
         }
         finally {
             // a concurrent reset() may have installed a newer load — leave that one alone
-            if (this.pending === pending) {
-                this.pending = null;
+            if (this._pending === pending) {
+                this._pending = null;
                 this._loading = false;
             }
         }
     };
     async reset() {
-        this.generation++;
-        this.pending = null;
+        this._generation++;
+        this._pending = null;
         this._loading = false;
         this.items = [];
-        this.continuationToken = ContinuationToken.init();
+        this._continuationToken = ContinuationToken.init();
         await this.loadMore();
     }
     updateSearchString = (searchString) => {
@@ -67,22 +71,28 @@ export class CursorDataLoaderWithSearch {
         }
     };
     runLoad = async () => {
-        const generation = this.generation;
+        const generation = this._generation;
         const search = this.isSearchStringEffective(this._searchString) ? this._searchString : '';
+        this._failed = false;
         try {
-            const result = (await this.loadPage(this.continuationToken, search)) ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            const page = await this._loadPage(this._continuationToken, search);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
-            this.continuationToken = result.continuationToken;
+            const result = page ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            this._failed = page === null;
+            this._continuationToken = result.continuationToken;
             this.items = [...this.items, ...result.items];
             return result.items;
         }
         catch (error) {
             console.error('CursorDataLoaderWithSearch: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
     };
-    isSearchStringEffective = (searchString) => searchString && searchString.length >= this.searchStringMinLength;
+    isSearchStringEffective = (searchString) => searchString && searchString.length >= this._searchStringMinLength;
 }

package/dist/core/data-loaders/cursor-data-loader.svelte.d.ts

@@ -3,15 +3,17 @@ import type { IDataLoader } from './data-loader';
 export declare class CursorDataLoader<T> implements IDataLoader<T> {
     items: T[];
     continuationToken: ContinuationToken;
-    private loadPage;
-    private pending;
-    private generation;
+    private _loadPage;
+    private _pending;
+    private _generation;
     private _loading;
+    private _failed;
     constructor(init: {
         loadPage: (continuationToken: ContinuationToken) => Promise<CursorResult<T> | null>;
     });
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset(): Promise<void>;
     private runLoad;

package/dist/core/data-loaders/cursor-data-loader.svelte.js

@@ -2,12 +2,13 @@ import { ContinuationToken } from '..';
 export class CursorDataLoader {
     items = $state.raw([]);
     continuationToken = $state.raw(ContinuationToken.init());
-    loadPage;
-    pending = null;
-    generation = 0;
+    _loadPage;
+    _pending = null;
+    _generation = 0;
     _loading = $state(false);
+    _failed = $state(false);
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
     }
     get loading() {
         return this._loading;
@@ -15,49 +16,58 @@ export class CursorDataLoader {
     get initialLoading() {
         return this._loading && this.items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this.pending) {
-            return this.pending;
+        if (this._pending) {
+            return this._pending;
         }
         if (!this.continuationToken.canLoadMore) {
             return [];
         }
         this._loading = true;
         const pending = this.runLoad();
-        this.pending = pending;
+        this._pending = pending;
         try {
             return await pending;
         }
         finally {
             // a concurrent reset() may have installed a newer load — leave that one alone
-            if (this.pending === pending) {
-                this.pending = null;
+            if (this._pending === pending) {
+                this._pending = null;
                 this._loading = false;
             }
         }
     };
     async reset() {
-        this.generation++;
-        this.pending = null;
+        this._generation++;
+        this._pending = null;
         this._loading = false;
         this.items = [];
         this.continuationToken = ContinuationToken.init();
         await this.loadMore();
     }
     runLoad = async () => {
-        const generation = this.generation;
+        const generation = this._generation;
+        this._failed = false;
         try {
-            const result = (await this.loadPage(this.continuationToken)) ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            const page = await this._loadPage(this.continuationToken);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
+            const result = page ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            this._failed = page === null;
             this.continuationToken = result.continuationToken;
             this.items = [...this.items, ...result.items];
             return result.items;
         }
         catch (error) {
             console.error('CursorDataLoader: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
     };

package/dist/core/data-loaders/data-loader.d.ts

@@ -3,5 +3,7 @@ export interface IDataLoader<T> {
     loading: boolean;
     /** Loading with nothing to show yet — first load, or a reload after the list was cleared by a reset. */
     initialLoading: boolean;
+    /** The last attempt did not deliver a page, whether it returned nothing or threw; cleared when the next attempt starts. */
+    failed: boolean;
     loadMore: () => Promise<T[]>;
 }

package/dist/core/data-loaders/index.d.ts

@@ -1,4 +1,5 @@
 export type { IDataLoader } from './data-loader';
 export { CursorDataLoader } from './cursor-data-loader.svelte';
 export { CursorDataLoaderWithSearch } from './cursor-data-loader-with-search.svelte';
+export { KeyedCursorDataLoader } from './keyed-cursor-data-loader.svelte';
 export { PageDataLoader } from './page-data-loader.svelte';

package/dist/core/data-loaders/index.js

@@ -1,4 +1,5 @@
 // Data loaders
 export { CursorDataLoader } from './cursor-data-loader.svelte';
 export { CursorDataLoaderWithSearch } from './cursor-data-loader-with-search.svelte';
+export { KeyedCursorDataLoader } from './keyed-cursor-data-loader.svelte';
 export { PageDataLoader } from './page-data-loader.svelte';

package/dist/core/data-loaders/keyed-cursor-data-loader.svelte.d.ts

@@ -0,0 +1,28 @@
+import { ContinuationToken, type CursorResult } from '..';
+export declare class KeyedCursorDataLoader<T> {
+    private _loaders;
+    private _loaded;
+    private _pending;
+    private _loadPage;
+    private _loadAlongside;
+    constructor(init: {
+        loadPage: (key: string, continuationToken: ContinuationToken) => Promise<CursorResult<T> | null>;
+        /** Started with the key's first page and awaited by `ensureLoaded`; its outcome never reaches `isLoaded`. */
+        loadAlongside?: (key: string) => Promise<void>;
+    });
+    items: (key?: string) => T[];
+    loading: (key?: string) => boolean;
+    initialLoading: (key?: string) => boolean;
+    canLoadMore: (key?: string) => boolean;
+    /** False until the key's first page loaded without failing, so a failed load can be retried; a later failed page never clears it. */
+    isLoaded: (key?: string) => boolean;
+    /** Loads the key's first page once; concurrent and repeat calls share that load's promise. */
+    ensureLoaded: (key?: string) => Promise<void>;
+    loadMore: (key?: string) => Promise<T[]>;
+    /** Drops the key's pages and loads them again from the first one. */
+    reload: (key?: string) => Promise<void>;
+    private startLoad;
+    private runLoad;
+    private runAlongside;
+    private loaderFor;
+}

package/dist/core/data-loaders/keyed-cursor-data-loader.svelte.js

@@ -0,0 +1,66 @@
+import { ContinuationToken } from '..';
+import { CursorDataLoader } from './cursor-data-loader.svelte';
+export class KeyedCursorDataLoader {
+    _loaders = {};
+    _loaded = $state.raw({});
+    _pending = {};
+    _loadPage;
+    _loadAlongside;
+    constructor(init) {
+        this._loadPage = init.loadPage;
+        this._loadAlongside = init.loadAlongside;
+    }
+    items = (key = '') => this.loaderFor(key).items;
+    loading = (key = '') => this.loaderFor(key).loading;
+    initialLoading = (key = '') => this.loaderFor(key).initialLoading;
+    canLoadMore = (key = '') => this.loaderFor(key).continuationToken.canLoadMore;
+    /** False until the key's first page loaded without failing, so a failed load can be retried; a later failed page never clears it. */
+    isLoaded = (key = '') => this._loaded[key] === true;
+    /** Loads the key's first page once; concurrent and repeat calls share that load's promise. */
+    ensureLoaded = (key = '') => {
+        if (this._loaded[key]) {
+            return Promise.resolve();
+        }
+        return this._pending[key] ?? this.startLoad(key);
+    };
+    loadMore = (key = '') => this.loaderFor(key).loadMore();
+    /** Drops the key's pages and loads them again from the first one. */
+    reload = (key = '') => {
+        this._loaded = { ...this._loaded, [key]: false };
+        return this.startLoad(key);
+    };
+    startLoad = async (key) => {
+        const pending = this.runLoad(key);
+        this._pending[key] = pending;
+        try {
+            await pending;
+        }
+        finally {
+            // a concurrent reload() may have installed a newer load — leave that one alone
+            if (this._pending[key] === pending) {
+                this._pending[key] = undefined;
+            }
+        }
+    };
+    runLoad = async (key) => {
+        const loader = this.loaderFor(key);
+        const alongside = this.runAlongside(key);
+        await loader.reset();
+        this._loaded = { ...this._loaded, [key]: !loader.failed };
+        await alongside;
+    };
+    runAlongside = async (key) => {
+        try {
+            await this._loadAlongside?.(key);
+        }
+        catch (error) {
+            console.error('KeyedCursorDataLoader: failed to load alongside the page', error);
+        }
+    };
+    loaderFor = (key) => {
+        if (!this._loaders[key]) {
+            this._loaders[key] = new CursorDataLoader({ loadPage: (continuationToken) => this._loadPage(key, continuationToken) });
+        }
+        return this._loaders[key];
+    };
+}

package/dist/core/data-loaders/page-data-loader.svelte.d.ts

@@ -2,11 +2,12 @@ import type { IDataLoader } from './data-loader';
 export declare class PageDataLoader<T> implements IDataLoader<T> {
     private _items;
     private _loading;
-    private canLoadMore;
-    private perPage;
-    private loadPage;
-    private pageNumber;
-    private generation;
+    private _failed;
+    private _canLoadMore;
+    private _perPage;
+    private _loadPage;
+    private _pageNumber;
+    private _generation;
     constructor(init: {
         loadPage: (page: number, perPage: number) => Promise<T[]>;
         perPage?: number;
@@ -14,6 +15,7 @@ export declare class PageDataLoader<T> implements IDataLoader<T> {
     get items(): T[];
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset: () => Promise<void>;
 }

package/dist/core/data-loaders/page-data-loader.svelte.js

@@ -1,15 +1,16 @@
 export class PageDataLoader {
     _items = $state.raw([]);
     _loading = $state(false);
-    canLoadMore = $state(true);
-    perPage = 20;
-    loadPage;
-    pageNumber = 1;
-    generation = 0;
+    _failed = $state(false);
+    _canLoadMore = $state(true);
+    _perPage = 20;
+    _loadPage;
+    _pageNumber = 1;
+    _generation = 0;
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
         if (init.perPage) {
-            this.perPage = init.perPage;
+            this._perPage = init.perPage;
         }
     }
     get items() {
@@ -21,39 +22,46 @@ export class PageDataLoader {
     get initialLoading() {
         return this._loading && this._items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this._loading || !this.canLoadMore) {
+        if (this._loading || !this._canLoadMore) {
             return [];
         }
-        const generation = this.generation;
+        const generation = this._generation;
         this._loading = true;
+        this._failed = false;
         try {
-            const items = await this.loadPage(this.pageNumber, this.perPage);
+            const items = await this._loadPage(this._pageNumber, this._perPage);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
-            this.pageNumber++;
-            this.canLoadMore = items.length === this.perPage;
+            this._pageNumber++;
+            this._canLoadMore = items.length === this._perPage;
             this._items = [...this._items, ...items];
             return items;
         }
         catch (error) {
             console.error('PageDataLoader: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
         finally {
-            if (generation === this.generation) {
+            if (generation === this._generation) {
                 this._loading = false;
             }
         }
     };
     reset = async () => {
-        this.generation++;
+        this._generation++;
         this._loading = false;
-        this.pageNumber = 1;
+        this._pageNumber = 1;
         this._items = [];
-        this.canLoadMore = true;
+        this._canLoadMore = true;
         await this.loadMore();
     };
 }

package/dist/ui/spinner/cmp.spinner.svelte

@@ -12,11 +12,11 @@ $effect(() => {
 });
 </script>
 
-{#if visible}
-  {#if blocking}
-    <div class="spinner-overlay" class:spinner-overlay--fixed={position === 'fixed-center'}></div>
-  {/if}
+{#if blocking}
+  <div class="spinner-overlay" class:spinner-overlay--fixed={position === 'fixed-center'} class:spinner-overlay--dimmed={visible}></div>
+{/if}
 
+{#if visible}
   <span
     class="spinner spinner--{size}"
     class:spinner--accent={color === 'accent'}
@@ -41,7 +41,9 @@ $effect(() => {
 @component
 Spinner — indeterminate loading indicator. Single-arc circle rotating at a constant rate. Color preset (`accent` default) resolves to a semantic token; override the public CSS vars on any ancestor for global theming. Pass `label` to expose it to screen readers as a live status region.
 
-Convenience props for the common "load happens, show a centered spinner with optional dimmer" pattern: `position` centers it within the nearest positioned ancestor (`absolute-center`) or the viewport (`fixed-center`); `blocking` adds a semi-transparent overlay; `timeout` delays visibility to avoid flicker for fast operations.
+Convenience props for the common "load happens, show a centered spinner with optional dimmer" pattern: `position` centers it within the nearest positioned ancestor (`absolute-center`) or the viewport (`fixed-center`); `blocking` adds an overlay; `timeout` delays visibility to avoid flicker for fast operations.
+
+`blocking` and `timeout` are orthogonal. The overlay mounts with the component and swallows pointer input from the first millisecond regardless of `timeout`; once `timeout` elapses the spinner appears and the overlay fades to its dim background. Pointer input only — a focused control underneath still reacts to the keyboard; wrap the region in `inert` if that matters.
 
 For tight inline glyphs inside other kit cmps (Button loading state, async Select), use the internal `_internal/spinner` instead — that one fills its inline box and inherits `currentColor` for stroke.
 
@@ -58,7 +60,7 @@ For tight inline glyphs inside other kit cmps (Button loading state, async Selec
 | `--sc-kit--spinner--color-text` | Color for `text` preset | `--sc-kit--color--text--primary` |
 | `--sc-kit--spinner--color-on-accent` | Color for `on-accent` preset | `--sc-kit--color--text--on-accent` |
 | `--sc-kit--spinner--duration` | Rotation duration | `1.6s` |
-| `--sc-kit--spinner--overlay--background` | Backdrop color when `blocking` is true | `rgba(0, 0, 0, 0.3)` |
+| `--sc-kit--spinner--overlay--background` | Backdrop color the `blocking` overlay fades to once the spinner shows | `rgba(0, 0, 0, 0.3)` |
 | `--sc-kit--spinner--overlay--z-index` | Backdrop stacking | `--sc-kit--z-index--popover` minus 1 |
 
 ### Size presets
@@ -74,12 +76,17 @@ For tight inline glyphs inside other kit cmps (Button loading state, async Selec
   --_overlay--z-index: var(--sc-kit--spinner--overlay--z-index, calc(var(--sc-kit--z-index--popover) - 1));
   position: absolute;
   inset: 0;
-  background: var(--_overlay--background);
+  background-color: var(--_overlay--background);
+  opacity: 0;
   z-index: var(--_overlay--z-index);
+  transition: opacity var(--sc-kit--duration--base) var(--sc-kit--ease--default);
 }
 .spinner-overlay--fixed {
   position: fixed;
 }
+.spinner-overlay--dimmed {
+  opacity: 1;
+}
 
 .spinner {
   --_spinner--size: var(--sc-kit--spinner--size, 1.25rem);

package/dist/ui/spinner/cmp.spinner.svelte.d.ts

@@ -7,15 +7,17 @@ type Props = {
     label?: string;
     /** Centering mode. `absolute-center` centers within the closest positioned ancestor; `fixed-center` centers in the viewport. Omit for an inline-flex glyph at the current position. */
     position?: 'absolute-center' | 'fixed-center';
-    /** Renders a semi-transparent overlay behind the spinner. Pair with `position` for a full-area dimmer. */
+    /** Renders an overlay that swallows pointer input immediately, independent of `timeout`; it stays invisible until `timeout` elapses, then fades to its dim background. Pair with `position` for a full-area dimmer. */
     blocking?: boolean;
-    /** Delay in ms before the spinner becomes visible (and the optional overlay renders). Prevents flicker for fast operations. @default 0 */
+    /** Delay in ms before the spinner becomes visible (and a `blocking` overlay dims). Prevents flicker for fast operations. @default 0 */
     timeout?: number;
 };
 /**
  * Spinner — indeterminate loading indicator. Single-arc circle rotating at a constant rate. Color preset (`accent` default) resolves to a semantic token; override the public CSS vars on any ancestor for global theming. Pass `label` to expose it to screen readers as a live status region.
  *
- * Convenience props for the common "load happens, show a centered spinner with optional dimmer" pattern: `position` centers it within the nearest positioned ancestor (`absolute-center`) or the viewport (`fixed-center`); `blocking` adds a semi-transparent overlay; `timeout` delays visibility to avoid flicker for fast operations.
+ * Convenience props for the common "load happens, show a centered spinner with optional dimmer" pattern: `position` centers it within the nearest positioned ancestor (`absolute-center`) or the viewport (`fixed-center`); `blocking` adds an overlay; `timeout` delays visibility to avoid flicker for fast operations.
+ *
+ * `blocking` and `timeout` are orthogonal. The overlay mounts with the component and swallows pointer input from the first millisecond regardless of `timeout`; once `timeout` elapses the spinner appears and the overlay fades to its dim background. Pointer input only — a focused control underneath still reacts to the keyboard; wrap the region in `inert` if that matters.
  *
  * For tight inline glyphs inside other kit cmps (Button loading state, async Select), use the internal `_internal/spinner` instead — that one fills its inline box and inherits `currentColor` for stroke.
  *
@@ -32,7 +34,7 @@ type Props = {
  * | `--sc-kit--spinner--color-text` | Color for `text` preset | `--sc-kit--color--text--primary` |
  * | `--sc-kit--spinner--color-on-accent` | Color for `on-accent` preset | `--sc-kit--color--text--on-accent` |
  * | `--sc-kit--spinner--duration` | Rotation duration | `1.6s` |
- * | `--sc-kit--spinner--overlay--background` | Backdrop color when `blocking` is true | `rgba(0, 0, 0, 0.3)` |
+ * | `--sc-kit--spinner--overlay--background` | Backdrop color the `blocking` overlay fades to once the spinner shows | `rgba(0, 0, 0, 0.3)` |
  * | `--sc-kit--spinner--overlay--z-index` | Backdrop stacking | `--sc-kit--z-index--popover` minus 1 |
  *
  * ### Size presets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/kit",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "author": "StreamsCloud",
   "repository": {
     "type": "git",