@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/DragMenu/DragMenuHolder.svelte

@@ -1,108 +1,121 @@
-<svelte:options runes />
-
-<script lang="ts" generics="T">
-	import { type DndEvent, dndzone } from 'svelte-dnd-action';
-	import { flip } from 'svelte/animate';
-	import type { DragMenuHolderProps } from './DragMenuHolderProps.js';
-	import type { Draggable } from './Draggable.js';
-	import DraggableCard from './DraggableCard.svelte';
-
-	const {
-		items: originalItems,
-		onUpdate,
-		snippet: customSnippet,
-		transformToDraggable,
-		flipDurationMS = 60,
-		label
-	}: DragMenuHolderProps<T> = $props();
-
-	let items: Array<Draggable<T>> = $state([]);
-
-	function consider(newItems: Array<Draggable<T>>) {
-		items = newItems;
-	}
-	function finalise(newItems: Array<Draggable<T>>) {
-		items = newItems;
-		onUpdate(items.map((it) => it.original));
-	}
-
-	$effect.pre(() => {
-		void originalItems;
-		items = originalItems.map(transformToDraggable);
-	});
-
-	const snippet = $derived(customSnippet ?? draggableWithSelect);
-</script>
-
-{#snippet draggableWithSelect<T>(item: Draggable<T>, index: number)}
-	<DraggableCard
-		title={item.title}
-		subtitle={item.subtitle}
-		{index}
-		selectable
-		selected={item.selected}
-	/>
-{/snippet}
-
-<div class="wrapper">
-	{#if label}
-		<span class="top-label">{label}</span>
-		<span class="top-label-border">{label}</span>
-	{/if}
-	<div
-		class="dnd"
-		use:dndzone={{ items, flipDurationMs: flipDurationMS, delayTouchStart: 30 }}
-		onconsider={(e: CustomEvent<DndEvent<Draggable<T>>>) => {
-			consider(e.detail.items);
-		}}
-		onfinalize={(e: CustomEvent<DndEvent<Draggable<T>>>) => {
-			finalise(e.detail.items);
-		}}
-	>
-		<!-- svelte-ignore a11y_no_static_element_interactions -->
-		{#each items as item, index (item.id)}
-			<!-- svelte-ignore a11y_click_events_have_key_events -->
-			<div
-				class="contents"
-				onclick={(e) => {
-					if (item.toggleSelected) {
-						e.stopPropagation();
-						item.toggleSelected();
-					}
-				}}
-				animate:flip={{ duration: flipDurationMS }}
-			>
-				<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
-				{@render snippet(item, index)}
-			</div>
-		{/each}
-	</div>
-</div>
-
-<!-- 
-tabindex="0"
-role="button"
-				onkeydown={(e) => {
-					const prevTarget = e.target;
-					console.log(e.key);
-					if (e.key == 'ArrowUp') {
-						e.stopPropagation();
-						up(item, index);
-					} else if (e.key == 'ArrowDown') {
-						e.stopPropagation();
-						down(item, index);
-					} else if (e.key == ' ') {
-						alert('SPACEBAR');
-					}
-					tick().then(() => {
-						if (prevTarget && 'focus' in prevTarget) {
-							(prevTarget as HTMLElement).focus();
-						} else {
-							console.warn(`prev target is undefined`);
-						}
-					});
-				}} -->
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	generics="T"
+>
+	import { type DndEvent, dndzone } from 'svelte-dnd-action';
+	import { flip } from 'svelte/animate';
+	import type { DragMenuHolderProps } from './DragMenuHolderProps.js';
+	import type { Draggable } from './Draggable.js';
+	import DraggableCard from './DraggableCard.svelte';
+
+	const {
+		items: originalItems,
+		onUpdate,
+		snippet: customSnippet,
+		transformToDraggable,
+		flipDurationMS = 60,
+		label,
+	}: DragMenuHolderProps<T> = $props();
+
+	let items: Array<Draggable<T>> = $state([]);
+	/**
+	 * `true` between `consider` and `finalise` events from dndzone.
+	 * While true we suppress the `originalItems -> items` sync effect
+	 * so an unrelated parent mutation cannot replace the user's
+	 * in-progress drag state.
+	 */
+	let isDragging = $state(false);
+
+	/** Compare two id sequences. Used to skip the sync effect when nothing changed. */
+	function sameIdSequence(a: ReadonlyArray<Draggable<T>>, b: ReadonlyArray<Draggable<T>>): boolean {
+		if (a.length !== b.length) {
+			return false;
+		}
+		for (let i = 0; i < a.length; i++) {
+			if (a[i].id !== b[i].id) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	function consider(newItems: Array<Draggable<T>>) {
+		isDragging = true;
+		items = newItems;
+	}
+	function finalise(newItems: Array<Draggable<T>>) {
+		items = newItems;
+		isDragging = false;
+		onUpdate(items.map((it) => it.original));
+	}
+
+	$effect.pre(() => {
+		// Re-establish the dependency on the source array.
+		const next = originalItems.map(transformToDraggable);
+		// Skip when a drag is in progress so the user's transient
+		// ordering is not clobbered by an unrelated parent mutation.
+		if (isDragging) {
+			return;
+		}
+		// Skip when the logical content is unchanged. Prevents flicker
+		// when the parent recreates the array reference with the same
+		// items (e.g. an unrelated `$derived` invalidation).
+		if (sameIdSequence(items, next)) {
+			return;
+		}
+		items = next;
+	});
+
+	const snippet = $derived(customSnippet ?? draggableWithSelect);
+</script>
+
+{#snippet draggableWithSelect<T>(item: Draggable<T>, index: number)}
+	<DraggableCard
+		title={item.title}
+		subtitle={item.subtitle}
+		{index}
+		selectable
+		selected={item.selected}
+	/>
+{/snippet}
+
+<div class="wrapper">
+	{#if label}
+		<span class="top-label">{label}</span>
+		<span class="top-label-border">{label}</span>
+	{/if}
+	<div
+		class="dnd"
+		use:dndzone={{ items, flipDurationMs: flipDurationMS, delayTouchStart: 30 }}
+		onconsider={(e: CustomEvent<DndEvent<Draggable<T>>>) => {
+			consider(e.detail.items);
+		}}
+		onfinalize={(e: CustomEvent<DndEvent<Draggable<T>>>) => {
+			finalise(e.detail.items);
+		}}
+	>
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		{#each items as item, index (item.id)}
+			<!-- svelte-ignore a11y_click_events_have_key_events -->
+			<div
+				class="contents"
+				onclick={(e) => {
+					if (item.toggleSelected) {
+						e.stopPropagation();
+						item.toggleSelected();
+					}
+				}}
+				animate:flip={{ duration: flipDurationMS }}
+			>
+				<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
+				{@render snippet(item, index)}
+			</div>
+		{/each}
+	</div>
+</div>
+
 <style>.top-label {
   position: absolute;
   left: 0.5rem;
@@ -157,5 +170,4 @@ div.dnd {
   flex: 1;
   gap: 0.5rem;
   padding: 0.5rem;
-  outline-color: red;
-}</style>
+}</style>

package/dist/Components/DragMenu/DragMenuHolderProps.d.ts

@@ -1,10 +1,39 @@
 import type { Snippet } from 'svelte';
 import type { Draggable } from './Draggable.js';
+/**
+ * Props for the {@link DragMenuHolder} component.
+ *
+ * `DragMenuHolder` wraps `svelte-dnd-action`'s `dndzone` to render a
+ * reorderable list of cards. The component maintains its own local
+ * copy of `items` synced from `originalItems` so that mid-drag
+ * updates to the parent's source array do not flicker. Generic over
+ * the consumer's payload type `T`.
+ */
 export interface DragMenuHolderProps<T> {
-    items: Array<T>;
+    /**
+     * The source items. Pass a plain array; the component maps each
+     * entry through {@link transformToDraggable} to produce the
+     * {@link Draggable} view used internally.
+     *
+     * Marked `ReadonlyArray` to make the no-mutation contract explicit.
+     */
+    items: ReadonlyArray<T>;
+    /**
+     * Map a single payload `T` to its {@link Draggable} view. The
+     * returned object's `id` is used as the `{#each}` key, so it MUST
+     * be stable across re-renders of the same logical item.
+     */
     transformToDraggable: (item: T) => Draggable<T>;
+    /** Optional snippet to render each draggable card. Defaults to a `DraggableCard` with selection support. */
     snippet?: Snippet<[Draggable<T>, number]>;
+    /** Called when the user finalises a reorder. Receives the original payloads in their new order. */
     onUpdate: (items: Array<T>) => void;
+    /** Optional label rendered as an absolute-positioned tag on the holder. */
     label?: string;
+    /**
+     * Animation duration in milliseconds for the FLIP transition.
+     * Defaults to 60ms. Naming preserved for source compatibility;
+     * future versions may expose a `flipDurationMs` alias.
+     */
     flipDurationMS?: number;
 }

package/dist/Components/DragMenu/DraggableCard.svelte

@@ -1,43 +1,79 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import Checkbox from '../Checkbox.svelte';
-	import type { DraggableCardProps } from './DraggableCardProps.js';
-
-	let {
-		selectable,
-		title,
-		subtitle,
-		index,
-		selected = $bindable(false),
-		touch = false,
-		toggleSelected
-	}: DraggableCardProps = $props();
-</script>
-
-<div class="card" class:touch>
-	{#if selectable}
-		<div class="limit-size" class:touch>
-			<Checkbox
-				value={selected}
-				onchange={(
-					e: Event & {
-						currentTarget: EventTarget & HTMLInputElement;
-					}
-				) => {
-					e.stopPropagation();
-					toggleSelected?.();
-				}}
-			/>
-		</div>
-	{/if}
-	<div class="text" class:touch>
-		<span class="title" class:touch>{title}</span>
-		<span class="subtitle" class:touch>{subtitle}</span>
-	</div>
-	<span class="row" class:touch>{index + 1}</span>
-</div>
-
+<svelte:options runes />
+
+<script lang="ts">
+	import { devCatch } from '../../Helpers/Helpers.svelte.js';
+	import Checkbox from '../Checkbox.svelte';
+	import type { DraggableCardProps } from './DraggableCardProps.js';
+
+	// `selected` must remain `let` because it is `$bindable`; the rest
+	// are read-only props.
+	let {
+		selectable,
+		title,
+		subtitle,
+		index,
+		selected = $bindable(false),
+		touch = false,
+		toggleSelected,
+	}: DraggableCardProps = $props();
+
+	function fireToggle(): void {
+		if (!toggleSelected) {
+			return;
+		}
+		const result = toggleSelected();
+		if (result instanceof Promise) {
+			result.catch((e: unknown) => {
+				devCatch(e);
+			});
+		}
+	}
+</script>
+
+<div
+	class="card"
+	class:touch
+	role={selectable ? 'checkbox' : 'listitem'}
+	aria-checked={selectable ? selected : undefined}
+	aria-label={title}
+>
+	{#if selectable}
+		<div
+			class="limit-size"
+			class:touch
+		>
+			<Checkbox
+				value={selected}
+				onchange={(
+					e: Event & {
+						currentTarget: EventTarget & HTMLInputElement;
+					}
+				) => {
+					e.stopPropagation();
+					fireToggle();
+				}}
+			/>
+		</div>
+	{/if}
+	<div
+		class="text"
+		class:touch
+	>
+		<span
+			class="title"
+			class:touch>{title}</span
+		>
+		<span
+			class="subtitle"
+			class:touch>{subtitle}</span
+		>
+	</div>
+	<span
+		class="row"
+		class:touch>{index + 1}</span
+	>
+</div>
+
 <style>.limit-size:not(.touch) {
   width: 1.5rem;
 }
@@ -134,4 +170,4 @@
   height: 1.75rem;
   width: 1.75rem;
   margin-right: 1rem;
-}</style>
+}</style>

package/dist/Components/DragMenu/DraggableCardProps.d.ts

@@ -1,9 +1,35 @@
+/**
+ * Props for the {@link DraggableCard} component.
+ *
+ * `DraggableCard` is the card variant rendered inside
+ * `DragMenuHolder`. It can optionally render a selection checkbox
+ * and a 1-based row badge. `selected` is `$bindable` so the parent
+ * can two-way bind, while `toggleSelected` is the imperative
+ * callback used by the inner `Checkbox`.
+ */
 export interface DraggableCardProps {
+    /** When true, render the selection `Checkbox`. */
     selectable: boolean;
+    /** Card title shown on the first line. */
     title: string;
+    /** Card subtitle shown on the second line. */
     subtitle: string;
+    /** Zero-based index. The card renders `index + 1` as the row badge. */
     index: number;
+    /** Render a larger touch-friendly variant. Defaults to `false`. */
     touch?: boolean;
+    /**
+     * Whether the card is currently selected. Two-way bindable.
+     * Defaults to `false`.
+     */
     selected?: boolean;
-    toggleSelected?: () => void;
+    /**
+     * Imperative selection toggle. Invoked by the inner `Checkbox`
+     * `onchange` handler. Optional; omit if `selectable` is false.
+     *
+     * May return a Promise for async toggling. Promise rejections
+     * are NOT caught by the card; the parent is responsible for
+     * routing them through `ToastContext.toast` or `devCatch`.
+     */
+    toggleSelected?: () => void | Promise<void>;
 }

package/dist/Components/FileCard.svelte

@@ -1,26 +1,30 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import Action from './Action.svelte';
-	import type { FileCardProps } from './FileCardProps.js';
-
-	const { file, ondelete }: FileCardProps = $props();
-</script>
-
-<div>
-	<span>{file.name}</span>
-	<Action
-		icon={{ name: 'circle-cross' }}
-		backgroundColour="transparent"
-		label="Delete"
-		onclick={ondelete}
-	/>
-</div>
-
+<svelte:options runes />
+
+<script lang="ts">
+	import Action from './Action.svelte';
+	import { Colour } from '../scss/colours.js';
+	import type { FileCardProps } from './FileCardProps.js';
+
+	const { file, ondelete }: FileCardProps = $props();
+</script>
+
+<div
+	role="listitem"
+	aria-label={file.name}
+>
+	<span>{file.name}</span>
+	<Action
+		icon={{ name: 'circle-cross' }}
+		backgroundColour={Colour['$transparent-0']}
+		label="Delete"
+		onclick={ondelete}
+	/>
+</div>
+
 <style>div {
   display: flex;
   flex-flow: row nowrap;
   flex-grow: 1;
   align-items: center;
   gap: 0.375rem;
-}</style>
+}</style>

package/dist/Components/FileCardProps.d.ts

@@ -1,4 +1,20 @@
 export interface FileCardProps {
+    /**
+     * The browser `File` to display. Only `file.name` is rendered; the
+     * card itself does not read the file's contents.
+     *
+     * Note: this is the plain Web API `File` type. The card performs no
+     * allow-listing of MIME type or extension - validation is the
+     * responsibility of the consumer (typically `FileUpload`).
+     */
     file: File;
-    ondelete: () => void;
+    /**
+     * Callback invoked when the user activates the delete affordance.
+     *
+     * May return a `Promise` to support callers that perform asynchronous
+     * cleanup (e.g. revoking an object URL or notifying a backend).
+     * Returned promises are not awaited by the card; consumers should
+     * handle their own error reporting.
+     */
+    ondelete: () => void | Promise<void>;
 }