@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/DragMenu/DragMenuHolder.svelte

@@ -1,6 +1,9 @@
 <svelte:options runes />
 
-<script lang="ts" generics="T">
+<script
+	lang="ts"
+	generics="T"
+>
 	import { type DndEvent, dndzone } from 'svelte-dnd-action';
 	import { flip } from 'svelte/animate';
 	import type { DragMenuHolderProps } from './DragMenuHolderProps.js';
@@ -13,22 +16,56 @@
 		snippet: customSnippet,
 		transformToDraggable,
 		flipDurationMS = 60,
-		label
+		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(() => {
-		void originalItems;
-		items = originalItems.map(transformToDraggable);
+		// 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);
@@ -79,30 +116,6 @@
 	</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`);
-						}
-					});
-				}} -->
-
 <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>

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,9 +1,12 @@
 <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,
@@ -11,13 +14,34 @@
 		index,
 		selected = $bindable(false),
 		touch = false,
-		toggleSelected
+		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>
+<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>
+		<div
+			class="limit-size"
+			class:touch
+		>
 			<Checkbox
 				value={selected}
 				onchange={(
@@ -26,16 +50,28 @@
 					}
 				) => {
 					e.stopPropagation();
-					toggleSelected?.();
+					fireToggle();
 				}}
 			/>
 		</div>
 	{/if}
-	<div class="text" class:touch>
-		<span class="title" class:touch>{title}</span>
-		<span class="subtitle" class:touch>{subtitle}</span>
+	<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>
+	<span
+		class="row"
+		class:touch>{index + 1}</span
+	>
 </div>
 
 <style>.limit-size:not(.touch) {

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

@@ -2,16 +2,20 @@
 
 <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>
+<div
+	role="listitem"
+	aria-label={file.name}
+>
 	<span>{file.name}</span>
 	<Action
 		icon={{ name: 'circle-cross' }}
-		backgroundColour="transparent"
+		backgroundColour={Colour['$transparent-0']}
 		label="Delete"
 		onclick={ondelete}
 	/>

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>;
 }

package/dist/Components/FileUpload.svelte

@@ -1,17 +1,15 @@
 <svelte:options runes />
 
 <script lang="ts">
-	import { ColourSet } from '../scss/colours.js';
+	import { cssLength } from '../Helpers/Helpers.svelte.js';
+	import { Colour, ColourSet } from '../scss/colours.js';
 	import { InputVariant } from '../Types/Internal/InputVariant.js';
 	import { Size } from '../Types/Internal/Size.js';
-	import { onMount } from 'svelte';
 	import Action from './Action.svelte';
 	import FileCard from './FileCard.svelte';
-	import type { FileUploadProps } from './FileUploadProps.js';
+	import type { FileRejection, FileUploadProps } from './FileUploadProps.js';
 	import Icon from './Icon.svelte';
 
-	let _files: FileList | null | undefined = $state();
-
 	let {
 		accept,
 		files = $bindable([]),
@@ -21,9 +19,6 @@
 		placeholder,
 		required = false,
 		variant = InputVariant.Default,
-		selectNone = false,
-		noresize = false,
-		uppercase = false,
 		disabled,
 		optional = false,
 		leftIcon,
@@ -34,16 +29,68 @@
 		inputRef = $bindable(),
 		onblur,
 		onfocus,
+		onchange,
+		onreject,
+		maxSize,
+		allowedMimeTypes,
+		allowedExtensions,
 	}: FileUploadProps = $props();
 
-	function onchange(e: Event & { currentTarget: EventTarget & HTMLInputElement }) {
-		const markedFiles = (e.target as HTMLInputElement).files ?? [];
-		for (let i = 0; i < markedFiles.length; i++) {
-			files.push(markedFiles[i]);
+	function reasonToReject(file: File): FileRejection['reason'] | null {
+		if (maxSize != undefined && file.size > maxSize) {
+			return 'size';
+		}
+		if (allowedMimeTypes && allowedMimeTypes.length > 0) {
+			if (!allowedMimeTypes.includes(file.type)) {
+				return 'mime';
+			}
+		}
+		if (allowedExtensions && allowedExtensions.length > 0) {
+			const lower = file.name.toLocaleLowerCase();
+			const matched = allowedExtensions.some((ext) => lower.endsWith(ext.toLocaleLowerCase()));
+			if (!matched) {
+				return 'extension';
+			}
+		}
+		return null;
+	}
+
+	function partition(candidates: ArrayLike<File>): {
+		accepted: ReadonlyArray<File>;
+		rejected: ReadonlyArray<FileRejection>;
+	} {
+		const accepted: Array<File> = [];
+		const rejected: Array<FileRejection> = [];
+		for (let i = 0; i < candidates.length; i++) {
+			const file = candidates[i];
+			const reason = reasonToReject(file);
+			if (reason == null) {
+				accepted.push(file);
+			} else {
+				rejected.push({ file, reason });
+			}
+		}
+		return { accepted, rejected };
+	}
+
+	function commit(accepted: ReadonlyArray<File>) {
+		if (accepted.length === 0) {
+			return;
+		}
+		files = [...files, ...accepted];
+		onchange?.(files);
+	}
+
+	function onPickerChange(e: Event & { currentTarget: EventTarget & HTMLInputElement }) {
+		const markedFiles = e.currentTarget.files ?? [];
+		const { accepted, rejected } = partition(markedFiles);
+		if (rejected.length > 0) {
+			onreject?.(rejected);
 		}
+		commit(accepted);
 	}
 
-	function a() {
+	function openPicker() {
 		inputRef?.showPicker();
 	}
 
@@ -58,26 +105,22 @@
 			return;
 		}
 
-		const len = e.dataTransfer.files.length;
-		for (let i = 0; i < len; i++) {
-			files.push(e.dataTransfer.files[i]);
+		const { accepted, rejected } = partition(e.dataTransfer.files);
+		if (rejected.length > 0) {
+			onreject?.(rejected);
 		}
+		commit(accepted);
 	}
 
 	function ondragover(e: DragEvent) {
 		e.preventDefault();
-
 		dragover = true;
 	}
 
 	function ondragleave(e: DragEvent) {
 		e.preventDefault();
-
 		dragover = false;
 	}
-	onMount(() => {
-		console.log('Drag and drop file uploading may not work');
-	});
 </script>
 
 <label
@@ -87,9 +130,7 @@
 	{ondragover}
 	{ondragleave}
 >
-	<!-- HACK removed label for modals for now because I couldn't think of a decent style that doesn't interfere with scrolling -->
 	{#if labelTop && variant !== InputVariant.Modal}
-		<!-- <span class="top-label" class:invalid={isInvalid}>{labelTop}{#if optional}<i>&nbsp;- optional</i>{/if}</span> -->
 		<span
 			class="top-label"
 			class:for-default={variant === InputVariant.Default}
@@ -101,7 +142,6 @@
 			>
 		{/if}
 	{/if}
-	<!-- style="--background-colour: {leftIcon?.backgroundColour ?? rightIcon?.backgroundColour};" -->
 	<div
 		class="icon-container"
 		class:for-modal={variant == InputVariant.Modal}
@@ -112,23 +152,19 @@
 				size={leftIcon.size ?? Size.Medium}
 				colour={leftIcon.colour}
 				float
-				left="0.75rem"
-				top="50%"
-				anchorX="0"
-				anchorY="-50%"
+				left={cssLength('0.75rem')}
+				top={cssLength('50%')}
+				anchorX={cssLength('0')}
+				anchorY={cssLength('-50%')}
 				clickable={!!onLeftIconClick}
 				onclick={onLeftIconClick}
 			/>
 		{/if}
 		<input
 			hidden
-			class:noresize
-			class:uppercase
-			class:select-none={selectNone}
 			class:left-pad={leftIcon != undefined}
 			class:right-pad={rightIcon != undefined}
 			class:for-modal={variant == InputVariant.Modal}
-			bind:files={_files}
 			{onblur}
 			{accept}
 			{onfocus}
@@ -138,16 +174,21 @@
 			{required}
 			{disabled}
 			{multiple}
-			{onchange}
+			onchange={onPickerChange}
 		/>
 
-		<div class="file-list">
+		<div
+			class="file-list"
+			role="list"
+			aria-label="Selected files"
+		>
 			{#if files.length}
 				{#each files as file, index (file)}
 					<FileCard
 						{file}
 						ondelete={() => {
-							files.splice(index, 1);
+							files = files.toSpliced(index, 1);
+							onchange?.(files);
 						}}
 					/>
 				{/each}
@@ -160,26 +201,25 @@
 		<div class="side">
 			<Action
 				colourSet={ColourSet.Secondary}
-				backgroundColour="transparent"
+				backgroundColour={Colour['$transparent-0']}
 				icon={{ name: 'upload' }}
 				label="Upload"
 				size={Size.Medium}
 				onclick={() => {
-					a();
+					openPicker();
 				}}
 			/>
 		</div>
-		<!-- </div> -->
 		{#if rightIcon}
 			<Icon
 				name={rightIcon.name}
 				size={rightIcon.size ?? Size.Medium}
 				colour={rightIcon.colour}
 				float
-				right={variant == InputVariant.Modal ? '1rem' : '0.5rem'}
-				top="50%"
-				anchorX="0"
-				anchorY="-50%"
+				right={cssLength(variant == InputVariant.Modal ? '1rem' : '0.5rem')}
+				top={cssLength('50%')}
+				anchorX={cssLength('0')}
+				anchorY={cssLength('-50%')}
 				clickable={!!onRightIconClick}
 				onclick={onRightIconClick}
 			/>

package/dist/Components/FileUploadProps.d.ts

@@ -1,24 +1,54 @@
 import type { InputVariant } from '../Types/Internal/InputVariant.js';
 import type { PartialIconProps } from './PartialIconProps.js';
+/** Reason a file was rejected during the client-side validation pass. */
+export type FileRejectReason = 'mime' | 'extension' | 'size';
+export interface FileRejection {
+    file: File;
+    reason: FileRejectReason;
+}
 export interface FileUploadProps {
+    /** HTML `accept` attribute hint. UI only - NOT a security boundary. */
     accept: string;
-    files: Array<File>;
+    /** Bindable list of selected files. */
+    files: ReadonlyArray<File>;
+    /** Whether multiple files may be selected. */
     multiple?: boolean;
+    /** Blur handler forwarded to the underlying file input. */
     onblur?: (e: FocusEvent) => void;
+    /** Focus handler forwarded to the underlying file input. */
     onfocus?: (e: FocusEvent) => void;
+    /** Top label rendered above the drop zone in the default variant. */
     labelTop?: string | undefined;
+    /** Right-positioned label rendered inside the drop zone. */
     labelRight?: string;
+    /** Placeholder text. */
     placeholder?: string | undefined;
+    /** Whether at least one file is required. */
     required?: boolean;
+    /** Visual variant. */
     variant?: InputVariant;
-    selectNone?: boolean;
+    /** When true, the visible "- optional" hint is rendered. */
     optional?: boolean;
-    uppercase?: boolean;
+    /** Disable the drop zone and underlying input. */
     disabled?: boolean;
+    /** Optional left-positioned icon. */
     leftIcon?: PartialIconProps;
+    /** Optional right-positioned icon. */
     rightIcon?: PartialIconProps;
+    /** Click handler for the left icon. */
     onLeftIconClick?: () => void;
+    /** Click handler for the right icon. */
     onRightIconClick?: () => void;
+    /** Bindable ref to the hidden file input element. */
     inputRef?: HTMLInputElement | undefined;
-    noresize?: boolean;
+    /** Notification of every change to `files`. */
+    onchange?: (files: ReadonlyArray<File>) => void;
+    /** Notification of files rejected by client-side validation. */
+    onreject?: (rejections: ReadonlyArray<FileRejection>) => void;
+    /** Maximum permitted file size, in bytes. */
+    maxSize?: number;
+    /** Allowed MIME types (exact match). */
+    allowedMimeTypes?: ReadonlyArray<string>;
+    /** Allowed file extensions including leading dot, case-insensitive. */
+    allowedExtensions?: ReadonlyArray<string>;
 }