@streamscloud/kit 0.71.0 → 0.73.0

package/dist/core/utils/image-preloader.d.ts

@@ -1 +1,3 @@
 export declare const preloadImage: (src: string, throwOnError?: boolean) => Promise<void>;
+/** Decodes a loaded `<img>` once, so a drag ghost snapshotted right after includes the picture. A broken image is ignored. */
+export declare const predecodeImage: (img: HTMLImageElement) => Promise<void>;

package/dist/core/utils/image-preloader.js

@@ -8,3 +8,12 @@ export const preloadImage = (src, throwOnError = false) => {
         img.src = src;
     });
 };
+/** Decodes a loaded `<img>` once, so a drag ghost snapshotted right after includes the picture. A broken image is ignored. */
+export const predecodeImage = async (img) => {
+    try {
+        await img.decode();
+    }
+    catch {
+        // a broken image has nothing to decode
+    }
+};

package/dist/ui/grid-card/cmp.grid-card-media.svelte

@@ -8,7 +8,7 @@ import { ProportionalContainer } from '../proportional-container';
 import { SeekBar } from '../seek-bar';
 import VideoPlayer from './video-player.svelte';
 import IconImageOff from '@fluentui/svg-icons/icons/image_off_20_regular.svg?raw';
-const { items, aspectRatio = 'vertical', objectFit = 'contain', showSeekBar = true, duration, decoding = 'auto' } = $props();
+const { items, aspectRatio = 'vertical', objectFit = 'contain', showSeekBar = true, duration, predecode = false } = $props();
 let currentIndex = $state(0);
 let currentTime = $state(0);
 let mediaDuration = $state(NaN);
@@ -63,7 +63,7 @@ const onCarouselIndexChanged = (index) => {
             active={true}
             on={{ timeUpdate: onPlayerTimeUpdate, durationChange: onPlayerDurationChange, activate: onPlayerActivate }} />
         {:else}
-          <Image src={items[0].url} showStubOnError={true} decoding={decoding} />
+          <Image src={items[0].url} showStubOnError={true} predecode={predecode} />
         {/if}
       </div>
     {:else}
@@ -78,7 +78,7 @@ const onCarouselIndexChanged = (index) => {
                   active={item === items[currentIndex]}
                   on={{ timeUpdate: onPlayerTimeUpdate, durationChange: onPlayerDurationChange, activate: onPlayerActivate }} />
               {:else}
-                <Image src={item.url} showStubOnError={true} decoding={decoding} />
+                <Image src={item.url} showStubOnError={true} predecode={predecode} />
               {/if}
             </div>
           {/snippet}

package/dist/ui/grid-card/cmp.grid-card-media.svelte.d.ts

@@ -15,8 +15,8 @@ type Props = {
     showSeekBar?: boolean;
     /** Duration in seconds; rendered as a badge overlay at the bottom-right of the media. `≤ 0` / `undefined` renders nothing. */
     duration?: number;
-    /** Forwarded to each `Image`. Pass `'sync'` when the card sits in a `DragSource`, or the first drag ghost comes out without the picture. @default 'auto' */
-    decoding?: 'sync' | 'async' | 'auto';
+    /** Forwarded to each `Image`. Set it when the card sits in a `DragSource`, or the first drag ghost comes out without the picture. @default false */
+    predecode?: boolean;
 };
 /**
  * Media slot for `GridCard`. Renders an empty placeholder, a single `Image` / `VideoPlayer`, or

package/dist/ui/image/cmp.image.svelte

@@ -1,14 +1,18 @@
-<script lang="ts">import { Icon } from '../icon';
+<script lang="ts">import { predecodeImage } from '../../core/utils';
+import { Icon } from '../icon';
 import { calculateImageState } from './image-state';
 import IconImageOff from '@fluentui/svg-icons/icons/image_off_20_regular.svg?raw';
-let { src, alt = '', showStubOnError = false, decoding = 'auto', on, stub } = $props();
+let { src, alt = '', showStubOnError = false, predecode = false, on, stub } = $props();
 let hasError = $state(false);
 const imageState = $derived(calculateImageState(src, hasError, showStubOnError));
 // A 0.01x density makes the intrinsic size 100× the natural one, so `contain` sizing always scales the picture
 // down to fit — small pictures upscale too — and the box hugs the picture, rounding its own corners.
 // `src` must stay unset: it would join srcset as the 1x candidate and win.
 const srcset = $derived(src ? `${src.replace(/\s/g, (char) => encodeURIComponent(char))} 0.01x` : undefined);
-const onLoad = () => {
+const onLoad = (event) => {
+    if (predecode && event.currentTarget instanceof HTMLImageElement) {
+        void predecodeImage(event.currentTarget);
+    }
     hasError = false;
     on?.load?.(true);
 };
@@ -26,7 +30,6 @@ const onLoadError = () => {
       srcset={srcset}
       alt={alt || ''}
       draggable="false"
-      decoding={decoding}
       onload={onLoad}
       onerror={onLoadError} />
   {/if}

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

@@ -5,8 +5,8 @@ type Props = {
     alt?: string;
     /** Show a placeholder stub instead of an error icon when image fails to load */
     showStubOnError?: boolean;
-    /** `'sync'` paints the picture in the same frame as its box — needed when the element can be dragged, or the first drag ghost comes out empty. @default 'auto' */
-    decoding?: 'sync' | 'async' | 'auto';
+    /** Decodes the picture once right after it loads. Set it when the element can be dragged, or the first drag ghost comes out empty. @default false */
+    predecode?: boolean;
     on?: {
         /** Fires after load attempt; `true` if successful, `false` on error */
         load?: (loadedSuccessfully: boolean) => void;

package/dist/ui/page-layout/cmp.page-layout.svelte

@@ -1,13 +1,16 @@
-<script lang="ts">import LayoutControlButton from './layout-control-button.svelte';
+<script lang="ts">import { Spinner } from '../spinner';
+import LayoutControlButton from './layout-control-button.svelte';
 import { PageLayoutLocalization } from './page-layout-localization';
+import { resolvePageLoading } from './page-loading';
 import IconDismiss from '@fluentui/svg-icons/icons/dismiss_20_regular.svg?raw';
 import IconWindow from '@fluentui/svg-icons/icons/window_20_regular.svg?raw';
 import IconWindowMultiple from '@fluentui/svg-icons/icons/window_multiple_20_regular.svg?raw';
-const { children, title, actions, navigationToggle, editorControls, scrollable = false, inert = false } = $props();
+const { children, title, actions, navigationToggle, editorControls, scrollable = false, inert = false, loading = false } = $props();
 const localization = new PageLayoutLocalization();
+const { timeout: loadingTimeout, blocking: loadingBlocking } = $derived(resolvePageLoading(loading));
 </script>
 
-<div class="page-layout" class:page-layout--scrollable={scrollable} inert={inert}>
+<div class="page-layout" class:page-layout--scrollable={scrollable} inert={inert || loadingBlocking}>
   <div class="page-layout__header">
     <div class="page-layout__title">
       {#if typeof title === 'function'}
@@ -50,6 +53,9 @@ const localization = new PageLayoutLocalization();
   <div class="page-layout__body">
     {@render children()}
   </div>
+  {#if loading}
+    <Spinner position="absolute-center" timeout={loadingTimeout} blocking={loadingBlocking} />
+  {/if}
 </div>
 
 <!--
@@ -63,6 +69,12 @@ outlined squares. Every entry takes `{ active?, onClick }`, and the group render
 navigation → panels → close. Set `scrollable` to let the whole page scroll as one document with
 sticky panel headers.
 
+`loading` (`true` or `{ timeout, blocking }`) shows a delayed `Spinner` centered over the layout.
+`blocking` makes the whole layout — header included — `inert` at once and dims it with the
+`Spinner` overlay after the same `timeout`; `inert` alone blocks without a spinner. With
+`scrollable` the layout itself scrolls, so the spinner and overlay stay at the top of the scroll.
+A loading `PagePanel` inside a loading layout draws its own spinner and overlay on top.
+
 ### CSS Custom Properties
 | Property | Description | Default |
 |---|---|---|
@@ -84,6 +96,7 @@ sticky panel headers.
   flex-direction: column;
   height: 100%;
   max-height: 100%;
+  position: relative;
   background: var(--_page-layout--background);
   color: var(--_page-layout--color);
 }

package/dist/ui/page-layout/cmp.page-layout.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { EditorControls, PageLayoutAction } from './types';
+import type { EditorControls, PageLayoutAction, PageLoading } from './types';
 import type { Snippet } from 'svelte';
 type Props = {
     children: Snippet;
@@ -11,6 +11,8 @@ type Props = {
     scrollable?: boolean;
     /** Sets `inert` on the whole layout — header and body stop taking focus, clicks and assistive-tech interaction. */
     inert?: boolean;
+    /** Shows a `Spinner` centered over the layout; `blocking` also makes the whole layout `inert` and dims it. @default false */
+    loading?: PageLoading;
 };
 /**
  * PageLayout — top-level window chrome. Renders a fixed-height header (title + actions + an optional
@@ -22,6 +24,12 @@ type Props = {
  * navigation → panels → close. Set `scrollable` to let the whole page scroll as one document with
  * sticky panel headers.
  *
+ * `loading` (`true` or `{ timeout, blocking }`) shows a delayed `Spinner` centered over the layout.
+ * `blocking` makes the whole layout — header included — `inert` at once and dims it with the
+ * `Spinner` overlay after the same `timeout`; `inert` alone blocks without a spinner. With
+ * `scrollable` the layout itself scrolls, so the spinner and overlay stay at the top of the scroll.
+ * A loading `PagePanel` inside a loading layout draws its own spinner and overlay on top.
+ *
  * ### CSS Custom Properties
  * | Property | Description | Default |
  * |---|---|---|

package/dist/ui/page-layout/cmp.page-panel.svelte

@@ -1,13 +1,16 @@
 <script lang="ts">import { horizontalWheelScroll } from '../../core/actions';
 import { slideHorizontally, transitionDuration } from '../../core/transitions';
 import { Icon } from '../icon';
+import { Spinner } from '../spinner';
 import PanelCollapseButton from './cmp.panel-collapse-button.svelte';
 import { PageLayoutLocalization } from './page-layout-localization';
+import { resolvePageLoading } from './page-loading';
 import IconChevronLeft from '@fluentui/svg-icons/icons/chevron_left_20_regular.svg?raw';
 import IconChevronRight from '@fluentui/svg-icons/icons/chevron_right_20_regular.svg?raw';
 import { untrack } from 'svelte';
-const { panelState, children, id, header, footer, title, actionsLeft, actionsCenter, actionsRight, collapseButtons, hideHeader = false, balanceHeaderCenter = false, resizing = null, borders = [], on } = $props();
+const { panelState, children, id, header, footer, title, actionsLeft, actionsCenter, actionsRight, collapseButtons, hideHeader = false, balanceHeaderCenter = false, resizing = null, borders = [], loading = false, on } = $props();
 const localization = new PageLayoutLocalization();
+const { timeout: loadingTimeout, blocking: loadingBlocking } = $derived(resolvePageLoading(loading));
 const isFlex = untrack(() => !resizing);
 const HEADER_SCROLL_STEP = 160;
 let panelRef = $state(undefined);
@@ -137,7 +140,8 @@ $effect(() => {
     class:page-panel--border-top={borders.includes('top')}
     class:page-panel--border-right={borders.includes('right')}
     class:page-panel--border-bottom={borders.includes('bottom')}
-    class:page-panel--border-left={borders.includes('left')}>
+    class:page-panel--border-left={borders.includes('left')}
+    inert={loadingBlocking}>
     {#if !hideHeader}
       <div class="page-panel__header" class:page-panel__header--balanced={balanceHeaderCenter}>
         {#if header}
@@ -239,6 +243,10 @@ $effect(() => {
         aria-valuenow={entry.width ?? 0}>
       </button>
     {/if}
+
+    {#if loading}
+      <Spinner position="absolute-center" timeout={loadingTimeout} blocking={loadingBlocking} />
+    {/if}
   </div>
 {/if}
 
@@ -250,6 +258,11 @@ instance, and configurable borders. Collapse uses the `slideHorizontally` transi
 
 Pass the same `panelState` instance to every panel + collapse button that should coordinate.
 
+`loading` (`true` or `{ timeout, blocking }`) shows a delayed `Spinner` centered over the panel.
+`blocking` makes the whole panel — header and footer included — `inert` at once and dims it with
+the `Spinner` overlay after the same `timeout`. Inside a `scrollable` `PageLayout` the panel is as
+tall as its content, so the spinner sits in the middle of the whole panel, not of the viewport.
+
 ### Header modes
 - `title` (string | Snippet) — renders in the left section; `actionsLeft` / `actionsRight` and
   `collapseButtons` are placed alongside.

package/dist/ui/page-layout/cmp.page-panel.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { PanelState } from './panel-state.svelte';
-import type { PanelBorder, PanelResizingSettings } from './types';
+import type { PageLoading, PanelBorder, PanelResizingSettings } from './types';
 import type { Snippet } from 'svelte';
 type Props = {
     /** The shared `PanelState` instance this panel registers with. */
@@ -22,6 +22,8 @@ type Props = {
     /** Resize / collapse config. `null` ⇒ the panel is `flex: 1` (no resizing). @default null */
     resizing?: PanelResizingSettings | null;
     borders?: PanelBorder[];
+    /** Shows a `Spinner` centered over the panel; `blocking` also makes the whole panel `inert` and dims it. @default false */
+    loading?: PageLoading;
     on?: {
         collapse?: (collapsed: boolean) => void;
     };
@@ -33,6 +35,11 @@ type Props = {
  *
  * Pass the same `panelState` instance to every panel + collapse button that should coordinate.
  *
+ * `loading` (`true` or `{ timeout, blocking }`) shows a delayed `Spinner` centered over the panel.
+ * `blocking` makes the whole panel — header and footer included — `inert` at once and dims it with
+ * the `Spinner` overlay after the same `timeout`. Inside a `scrollable` `PageLayout` the panel is as
+ * tall as its content, so the spinner sits in the middle of the whole panel, not of the viewport.
+ *
  * ### Header modes
  * - `title` (string | Snippet) — renders in the left section; `actionsLeft` / `actionsRight` and
  * `collapseButtons` are placed alongside.

package/dist/ui/page-layout/index.d.ts

@@ -5,4 +5,4 @@ export { default as PagePanels } from './cmp.page-panels.svelte';
 export { default as PanelCollapseButton } from './cmp.panel-collapse-button.svelte';
 export { default as PanelContent } from './cmp.panel-content.svelte';
 export { PanelEntry, PanelState, SidebarsToggle } from './panel-state.svelte';
-export type { EditorControls, PageLayoutAction, PanelBorder, PanelResizingSettings } from './types';
+export type { EditorControls, PageLayoutAction, PageLoading, PanelBorder, PanelResizingSettings } from './types';

package/dist/ui/page-layout/page-loading.d.ts

@@ -0,0 +1,5 @@
+import type { PageLoading } from './types';
+export declare const resolvePageLoading: (loading: PageLoading) => {
+    timeout: number;
+    blocking: boolean;
+};

package/dist/ui/page-layout/page-loading.js

@@ -0,0 +1,7 @@
+const DEFAULT_LOADING_TIMEOUT = 500;
+export const resolvePageLoading = (loading) => {
+    if (typeof loading === 'object') {
+        return { timeout: loading.timeout ?? DEFAULT_LOADING_TIMEOUT, blocking: loading.blocking === true };
+    }
+    return { timeout: DEFAULT_LOADING_TIMEOUT, blocking: false };
+};

package/dist/ui/page-layout/types.d.ts

@@ -30,3 +30,11 @@ export type EditorControls = {
     panelsToggle: PageLayoutAction;
     close: PageLayoutAction;
 };
+/**
+ * `PageLayout` / `PagePanel` loading state. `true` shows a non-blocking `Spinner` after 500ms. The object form sets the delay in ms (`timeout`, default
+ * 500) and, with `blocking`, makes the whole component `inert` at once and dims it with the `Spinner` overlay after the same delay.
+ */
+export type PageLoading = boolean | {
+    timeout?: number;
+    blocking?: boolean;
+};

package/dist/ui/tile-card/cmp.tile-card.svelte

@@ -1,11 +1,17 @@
-<script lang="ts">import { Checkbox } from '../checkbox';
+<script lang="ts">import { predecodeImage } from '../../core/utils';
+import { Checkbox } from '../checkbox';
 import { ToolbarIconButton } from '../page-toolbar';
 import { PlayIndicator } from '../play-indicator';
 import { Popover } from '../popover';
 import { TileCardLocalization } from './tile-card-localization';
 import IconMore from '@fluentui/svg-icons/icons/more_vertical_20_regular.svg?raw';
-const { title, meta, preview, decoding = 'auto', menu, menuLabel, selected = false, checkboxVisibility = 'hover', on } = $props();
+const { title, meta, preview, predecode = false, menu, menuLabel, selected = false, checkboxVisibility = 'hover', on } = $props();
 const localization = new TileCardLocalization();
+const onPictureLoad = (event) => {
+    if (predecode && event.currentTarget instanceof HTMLImageElement) {
+        void predecodeImage(event.currentTarget);
+    }
+};
 // Safari paints no frame for preload="metadata" until a seek target is given.
 const withFirstFrame = (src) => (src.includes('#') ? src : `${src}#t=0.001`);
 </script>
@@ -19,7 +25,7 @@ const withFirstFrame = (src) => (src.includes('#') ? src : `${src}#t=0.001`);
       {#if typeof preview === 'function'}
         {@render preview()}
       {:else if 'image' in preview}
-        <img class="tile-card__picture" src={preview.image} alt="" decoding={decoding} />
+        <img class="tile-card__picture" src={preview.image} alt="" onload={onPictureLoad} />
       {:else}
         <video class="tile-card__picture" src={withFirstFrame(preview.video)} poster={preview.poster} preload="metadata" muted playsinline></video>
         <span class="tile-card__play"><PlayIndicator /></span>

package/dist/ui/tile-card/cmp.tile-card.svelte.d.ts

@@ -6,8 +6,8 @@ type Props = {
     meta?: string;
     /** Top area: `image` / `video` render a drag-safe picture or frame (contain, never upscaled; a video gets a play glyph); a snippet renders custom content. The area is `pointer-events: none` — interactive content belongs in `menu` or `on.activate`. */
     preview?: TileCardPreview;
-    /** Decoding of the `image` preview. Pass `'sync'` when the tile sits in a `DragSource`, or the first drag ghost comes out without the picture — the same goes for an `<img>` in a preview snippet. @default 'auto' */
-    decoding?: 'sync' | 'async' | 'auto';
+    /** Decodes the `image` preview once right after it loads. Set it when the tile sits in a `DragSource`, or the first drag ghost comes out without the picture — an `<img>` in a preview snippet needs `predecodeImage` from its owner. @default false */
+    predecode?: boolean;
     /** `PopoverItem`s of the kebab menu at the end of the footer. */
     menu?: Snippet;
     /** Accessible name of the kebab menu. @default localized "Actions" */

package/package.json

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