@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/Base/Pagination.svelte

@@ -1,192 +1,200 @@
-<svelte:options runes />
-
-<!-- @component
-	Allows for automated pagination of local content in cases where a collection may become a performance concern
-
-	### Usage
-	```svelte
-		<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
-	```
- -->
-<script
-	lang="ts"
-	generics="T extends object"
->
-	import { autoPluralise, generateShortUUID } from '../../Helpers/Helpers.svelte.js';
-	import { Colour } from '../../scss/colours.js';
-	import { Side } from '../../Types/Internal/Side.js';
-	import { Size } from '../../Types/Internal/Size.js';
-	import { Variant } from '../../Types/Internal/Variant.js';
-	import Button from '../Button.svelte';
-	import Icon from '../Icon.svelte';
-	import NumberInput from '../NumberInput.svelte';
-	import type { PaginationProps } from './PaginationProps.js';
-
-	const {
-		items,
-		key,
-		pageSize = 20,
-		snippet,
-		itemName = 'Item',
-		border = false,
-		padding = '1.5rem', //sizing.$regular-padding
-		gap = '1.5rem', // sizing.$regular-gap
-		height,
-	}: PaginationProps<T> = $props();
-
-	const _uuid = generateShortUUID();
-	let pageIndex = $state(0);
-	let pageValue = $derived(pageIndex + 1);
-	const startIndex = $derived(pageIndex * pageSize);
-	const pageItems = $derived(items.slice(startIndex, startIndex + pageSize));
-
-	const lastPage = $derived(Math.ceil(items.length / pageSize));
-	const lastPageIndex = $derived(lastPage - 1);
-
-	let debounceTimeout = -1;
-	function onNumberInput(e: Event) {
-		const page = parseInt((e.target as HTMLInputElement).value);
-
-		clearTimeout(debounceTimeout);
-		if (!isNaN(page)) {
-			debounceTimeout = setTimeout(() => {
-				pageIndex = Math.max(page - 1, 0);
-			}, 400) as unknown as number;
-		}
-	}
-
-	let pageButtons: Array<number> = $state([]);
-
-	$effect(() => {
-		const startingPage = Math.min(lastPage - 2, pageIndex - 1);
-		const pageToStartWith = Math.max(1, Math.min(startingPage, lastPage - 4));
-
-		pageButtons = new Array<number>(Math.min(lastPage, 5))
-			.fill(pageToStartWith)
-			.map((item, index) => item + index);
-	});
-</script>
-
-<!-- PROPER -->
-<!-- 
-
-	<div class="pagination">
-		<div>page {pageIndex}</div>
-		<button
-			onclick={() => {
-				pageIndex = Math.max(pageIndex - 1, 0);
-			}}>Previous</button
-		>
-		<button
-			onclick={() => {
-				pageIndex = Math.min(pageIndex + 1, lastPageIndex);
-			}}>Next</button
-		>
-	</div>
-</div> -->
-
-<!-- 	style={`${padding ? `padding: ${padding};` : ''}` +
-		`${gap ? `gap: ${gap};` : ''}` +
-		`${height ? `height: ${height};` : ''}`} -->
-<div
-	class="wrapper"
-	class:border
-	style={(padding ? `padding: ${padding};` : '') +
-		(gap ? `gap: ${gap};` : '') +
-		(height ? `height: ${height};` : '')}
->
-	{#each pageItems as item, index (item[key])}
-		{@render snippet(item, index)}
-	{/each}
-	<div class="spread_row bottom_row">
-		<div class="block">
-			<span>{items.length} {autoPluralise(itemName, items.length)}</span>
-		</div>
-
-		<div class="block records-per-page">
-			<span>Records per Page: {pageSize}</span>
-		</div>
-
-		<div class="spacer"></div>
-		<!-- {/* TODO switch to a lib element for this */} -->
-
-		<div class="scrollable">
-			<div class="block">
-				<Icon
-					name="paper"
-					colour={Colour['$ui-blue-6']}
-				/>
-				<span>{lastPage} {autoPluralise('Page', lastPage)}</span>
-			</div>
-
-			<div class="block">
-				<label for="{_uuid}-jump-to-page"
-					><Icon
-						name="arrow-move-horizontal"
-						colour={Colour['$ui-blue-6']}
-					/></label
-				>
-
-				<label for="{_uuid}-jump-to-page">Jump to page:</label>
-
-				<NumberInput
-					id="{_uuid}-jump-to-page"
-					value={pageValue}
-					oninput={onNumberInput}
-				/>
-			</div>
-
-			<div class="block nopad page-arrow">
-				<Button
-					variant={Variant.Toolbar}
-					disabled={pageIndex === 0}
-					side={Side.Bottom}
-					onclick={() => {
-						pageIndex = Math.max(pageIndex - 1, 0);
-					}}
-					size={Size.FillHeight}
-					iconLeft={{
-						name: 'left-close',
-						size: Size.FillHeight,
-					}}>Previous Page</Button
-				>
-			</div>
-
-			{#key pageButtons}
-				{#each pageButtons as pageNumber (pageNumber)}
-					<div class="block nopad">
-						<Button
-							variant={Variant.Toolbar}
-							side={Side.Bottom}
-							size={Size.FillHeight}
-							toggled={pageIndex + 1 === pageNumber}
-							onclick={() => {
-								pageIndex = pageNumber - 1;
-							}}>{pageNumber}</Button
-						>
-					</div>
-				{/each}
-			{/key}
-
-			<div class="block nopad page-arrow">
-				<Button
-					variant={Variant.Toolbar}
-					side={Side.Bottom}
-					size={Size.FillHeight}
-					onclick={() => {
-						pageIndex = Math.min(pageIndex + 1, lastPageIndex);
-					}}
-					disabled={pageIndex == lastPageIndex}
-					iconRight={{
-						name: 'right-close',
-						size: Size.FillHeight,
-					}}>Next Page</Button
-				>
-			</div>
-		</div>
-	</div>
-</div>
-
+<svelte:options runes />
+
+<!--
+@component
+Generic local-collection paginator. Renders a window of items via a
+`snippet` plus a control bar with page-number buttons, a jump-to-page
+input, and previous/next buttons. The component is generic over
+`T extends object` with a `key: keyof T` used as the
+`{#each}` key inside the rendered page.
+
+### Usage
+
+```svelte
+<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
+```
+
+The `pageButtons` window (up to five numbered buttons) is recomputed
+via `$derived`, not via an `$effect`, so the page bar diffs in a
+single reactive pass and the keyed `{#each pageButtons as page ...}`
+preserves button identity across page changes.
+-->
+<script
+	lang="ts"
+	generics="T extends object"
+>
+	import { autoPluralise, generateWeakId } from '../../Helpers/Helpers.svelte.js';
+	import { Colour } from '../../scss/colours.js';
+	import { Side } from '../../Types/Internal/Side.js';
+	import { Size } from '../../Types/Internal/Size.js';
+	import { Variant } from '../../Types/Internal/Variant.js';
+	import Button from '../Button.svelte';
+	import Icon from '../Icon.svelte';
+	import NumberInput from '../NumberInput.svelte';
+	import type { PaginationProps } from './PaginationProps.js';
+
+	const {
+		items,
+		key,
+		pageSize = 20,
+		snippet,
+		itemName = 'Item',
+		border = false,
+		padding = '1.5rem', // sizing.$regular-padding
+		gap = '1.5rem', // sizing.$regular-gap
+		height,
+	}: PaginationProps<T> = $props();
+
+	const _uuid = generateWeakId();
+	let pageIndex = $state(0);
+	const pageValue = $derived(pageIndex + 1);
+	const startIndex = $derived(pageIndex * pageSize);
+	const pageItems = $derived(items.slice(startIndex, startIndex + pageSize));
+
+	const lastPage = $derived(Math.ceil(items.length / pageSize));
+	const lastPageIndex = $derived(lastPage - 1);
+
+	// Debounced jump-to-page handler. Reads the raw event because the
+	// debounce drives state, not the input value directly; binding to
+	// `pageValue` would defeat the debounce.
+	let debounceTimeout = -1;
+	function onNumberInput(e: Event) {
+		const value = (e.target as HTMLInputElement).value;
+		const page = Number(value);
+
+		clearTimeout(debounceTimeout);
+		if (!isNaN(page)) {
+			debounceTimeout = setTimeout(() => {
+				pageIndex = Math.max(page - 1, 0);
+			}, 400) as unknown as number;
+		}
+	}
+
+	/**
+	 * Compute the window of up to five page numbers shown in the
+	 * control bar. Centred on the current page where possible and
+	 * clamped against both ends. Pulled into a stand-alone helper so
+	 * the windowing logic is unit-testable from outside the component.
+	 */
+	function getPageWindow(
+		currentIndex: number,
+		totalPages: number,
+		windowSize: number
+	): Array<number> {
+		const start = Math.min(totalPages - 2, currentIndex - 1);
+		const clampedStart = Math.max(1, Math.min(start, totalPages - (windowSize - 1)));
+		const count = Math.min(totalPages, windowSize);
+		const out = new Array<number>(count);
+		for (let i = 0; i < count; i++) {
+			out[i] = clampedStart + i;
+		}
+		return out;
+	}
+
+	const pageButtons = $derived(getPageWindow(pageIndex, lastPage, 5));
+</script>
+
+<div
+	class="wrapper"
+	class:border
+	style:padding
+	style:gap
+	style:height
+>
+	{#each pageItems as item, index (item[key])}
+		{@render snippet(item, index)}
+	{/each}
+	<div class="spread_row bottom_row">
+		<div class="block">
+			<span>{items.length} {autoPluralise(itemName, items.length)}</span>
+		</div>
+
+		<div class="block records-per-page">
+			<span>Records per Page: {pageSize}</span>
+		</div>
+
+		<div class="spacer"></div>
+
+		<div
+			class="scrollable"
+			role="navigation"
+			aria-label="Pagination"
+		>
+			<div class="block">
+				<Icon
+					name="paper"
+					colour={Colour['$ui-blue-6']}
+				/>
+				<span>{lastPage} {autoPluralise('Page', lastPage)}</span>
+			</div>
+
+			<div class="block">
+				<label for="{_uuid}-jump-to-page"
+					><Icon
+						name="arrow-move-horizontal"
+						colour={Colour['$ui-blue-6']}
+					/></label
+				>
+
+				<label for="{_uuid}-jump-to-page">Jump to page:</label>
+
+				<NumberInput
+					id="{_uuid}-jump-to-page"
+					value={pageValue}
+					oninput={onNumberInput}
+				/>
+			</div>
+
+			<div class="block nopad page-arrow">
+				<Button
+					variant={Variant.Toolbar}
+					disabled={pageIndex === 0}
+					side={Side.Bottom}
+					onclick={() => {
+						pageIndex = Math.max(pageIndex - 1, 0);
+					}}
+					size={Size.FillHeight}
+					iconLeft={{
+						name: 'left-close',
+						size: Size.FillHeight,
+					}}>Previous Page</Button
+				>
+			</div>
+
+			{#each pageButtons as pageNumber (pageNumber)}
+				<div class="block nopad">
+					<Button
+						variant={Variant.Toolbar}
+						side={Side.Bottom}
+						size={Size.FillHeight}
+						toggled={pageIndex + 1 === pageNumber}
+						label={`Go to page ${pageNumber.toString()}`}
+						onclick={() => {
+							pageIndex = pageNumber - 1;
+						}}>{pageNumber}</Button
+					>
+				</div>
+			{/each}
+
+			<div class="block nopad page-arrow">
+				<Button
+					variant={Variant.Toolbar}
+					side={Side.Bottom}
+					size={Size.FillHeight}
+					onclick={() => {
+						pageIndex = Math.min(pageIndex + 1, lastPageIndex);
+					}}
+					disabled={pageIndex == lastPageIndex}
+					iconRight={{
+						name: 'right-close',
+						size: Size.FillHeight,
+					}}>Next Page</Button
+				>
+			</div>
+		</div>
+	</div>
+</div>
+
 <style>.wrapper {
   display: flex;
   flex: 1;
@@ -261,4 +269,4 @@
 }
 .spread_row .spacer {
   flex-grow: 2;
-}</style>
+}</style>

package/dist/Components/Base/Pagination.svelte.d.ts

@@ -21,12 +21,22 @@ interface $$IsomorphicComponent {
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 /**
- * Allows for automated pagination of local content in cases where a collection may become a performance concern
+ * Generic local-collection paginator. Renders a window of items via a
+ * `snippet` plus a control bar with page-number buttons, a jump-to-page
+ * input, and previous/next buttons. The component is generic over
+ * `T extends object` with a `key: keyof T` used as the
+ * `{#each}` key inside the rendered page.
  *
  * ### Usage
+ *
  * ```svelte
- * 	<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
+ * <Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
  * ```
+ *
+ * The `pageButtons` window (up to five numbered buttons) is recomputed
+ * via `$derived`, not via an `$effect`, so the page bar diffs in a
+ * single reactive pass and the keyed `{#each pageButtons as page ...}`
+ * preserves button identity across page changes.
  */
 declare const Pagination: $$IsomorphicComponent;
 type Pagination<T extends object> = InstanceType<typeof Pagination<T>>;

package/dist/Components/Base/PaginationProps.d.ts

@@ -1,14 +1,71 @@
 import type { Snippet } from 'svelte';
+/**
+ * Props for {@link Pagination}.
+ *
+ * `Pagination` renders a windowed view of a local collection along
+ * with a control bar (records-per-page, jump-to-page, prev/next, and
+ * up to five numbered page buttons). It is generic over the item
+ * record `T`.
+ */
 export interface PaginationProps<T extends object> {
-    /** Used to index each item for a unique key. Duplicate values will result in error */
+    /**
+     * Property name on each item whose value is used as the `{#each}`
+     * key. Duplicate values across `items` will cause Svelte to throw
+     * at render time, so the chosen field should be unique (typically
+     * an `id` column).
+     *
+     * The constraint enforces a string key only; uniqueness across
+     * the collection cannot be expressed in the type system - mirror
+     * the contract of `Table.selectionExtractor` if you need a
+     * derived key.
+     */
     key: string & keyof T;
-    items: Array<T>;
-    /** Second argument is the index */
+    /** The collection to paginate. */
+    items: ReadonlyArray<T>;
+    /**
+     * Renderer invoked once per item in the current page. The second
+     * argument is the index within the current page (zero-based).
+     */
     snippet: Snippet<[T, number]>;
+    /**
+     * Number of items rendered per page.
+     *
+     * @default 20
+     */
     pageSize?: number;
+    /**
+     * Singular noun shown next to the total record count
+     * ("`<count>` `<itemName>`s"); pluralised automatically by
+     * `autoPluralise`.
+     *
+     * @default 'Item'
+     */
     itemName?: string;
+    /**
+     * When `true` the wrapper draws a rounded thick border around
+     * the rendered items.
+     */
     border?: boolean;
+    /**
+     * Raw CSS length used for the wrapper `padding`. Strings are
+     * accepted because the component takes any CSS value; prefer
+     * one of the standard `sizing.$*-padding` tokens
+     * (`'1.5rem'` matches `sizing.$regular-padding`).
+     *
+     * @default '1.5rem'
+     */
     padding?: string;
+    /**
+     * Raw CSS length used for the wrapper `gap`. Same conventions as
+     * `padding`; prefer the `sizing.$*-gap` tokens.
+     *
+     * @default '1.5rem'
+     */
     gap?: string;
+    /**
+     * Optional raw CSS length used for the wrapper `height`. Useful
+     * for fixed-height scroll containers; left unset by default so
+     * the wrapper consumes the available flex space.
+     */
     height?: string;
 }

package/dist/Components/Base/Snippets.svelte

@@ -1,29 +1,36 @@
-<svelte:options runes />
-
-<!-- @component
-An empty component that only exists to export common snippets
- -->
-<script
-	lang="ts"
-	module
->
-	import { getErrorMessage, loadingText } from '../../Helpers/Helpers.svelte.js';
-	import Button from '../Button.svelte';
-
-	export const pending = _pending;
-	export const failed = _failed;
-</script>
-
-{#snippet _pending()}
-	{loadingText}
-{/snippet}
-{#snippet _failed(e: unknown, retry?: () => void)}
-	Error: {getErrorMessage(e)}
-	{#if retry}
-		<Button
-			onclick={() => {
-				retry();
-			}}>Retry</Button
-		>
-	{/if}
-{/snippet}
+<svelte:options runes />
+
+<!-- @component
+An empty component that only exists to export common snippets
+(`pending` and `failed`) for re-use by `{#await}` blocks and other
+async-status surfaces. The component itself renders nothing.
+ -->
+<script
+	lang="ts"
+	module
+>
+	import { getErrorMessage, loadingText } from '../../Helpers/Helpers.svelte.js';
+	import Button from '../Button.svelte';
+
+	// The local `{#snippet _pending}` / `{#snippet _failed}` declarations
+	// must be hoistable references for `export const` to bind to them.
+	// Svelte 5 currently requires the snippet name to differ from the
+	// exported binding, so we use an underscore prefix on the local
+	// declaration and expose the un-prefixed name as the public surface.
+	export const pending = _pending;
+	export const failed = _failed;
+</script>
+
+{#snippet _pending()}
+	{loadingText}
+{/snippet}
+{#snippet _failed(e: unknown, retry?: () => void)}
+	Error: {getErrorMessage(e)}
+	{#if retry}
+		<Button
+			onclick={() => {
+				retry();
+			}}>Retry</Button
+		>
+	{/if}
+{/snippet}

package/dist/Components/Base/Snippets.svelte.d.ts

@@ -1,6 +1,10 @@
 export declare const pending: () => ReturnType<import("svelte").Snippet>;
 export declare const failed: (e: unknown, retry?: () => void) => ReturnType<import("svelte").Snippet>;
-/** An empty component that only exists to export common snippets */
+/**
+ * An empty component that only exists to export common snippets
+ * (`pending` and `failed`) for re-use by `{#await}` blocks and other
+ * async-status surfaces. The component itself renders nothing.
+ */
 declare const Snippets: import("svelte").Component<Record<string, never>, {}, "">;
 type Snippets = ReturnType<typeof Snippets>;
 export default Snippets;

package/dist/Components/BigRadioSet.svelte

@@ -1,31 +1,40 @@
-<svelte:options runes />
-
-<script lang="ts" generics="T">
-	import type { BigRadioOption } from '../Types/Internal/BigRadioOption.js';
-	import type { BigRadioSetProps } from './BigRadioSetProps.js';
-	let { name, options, selected = $bindable() }: BigRadioSetProps<T> = $props();
-
-	// let selected: T | undefined = $state();
-</script>
-
-<div class="wrapper">
-	{#each options as option (option)}
-		<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
-		{@render radio(option)}
-	{/each}
-</div>
-
-{#snippet radio(option: BigRadioOption<T>)}
-	<!-- {@debug selected} -->
-	<label class:selected={selected === option.value}>
-		<input type="radio" {name} bind:group={selected} value={option.value} />
-		<div class="text">
-			<h5 class="title">{option.label}</h5>
-			<p class="note">{option.info}</p>
-		</div>
-	</label>
-{/snippet}
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	generics="T"
+>
+	import type { BigRadioOption } from '../Types/Internal/BigRadioOption.js';
+	import type { BigRadioSetProps } from './BigRadioSetProps.js';
+	let { name, options, selected = $bindable(), onchange }: BigRadioSetProps<T> = $props();
+</script>
+
+<div
+	class="wrapper"
+	role="radiogroup"
+>
+	{#each options as option (option.value)}
+		<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
+		{@render radio(option)}
+	{/each}
+</div>
+
+{#snippet radio(option: BigRadioOption<T>)}
+	<label class:selected={selected === option.value}>
+		<input
+			type="radio"
+			{name}
+			bind:group={selected}
+			value={option.value}
+			onchange={() => void onchange?.(option.value)}
+		/>
+		<div class="text">
+			<h5 class="title">{option.label}</h5>
+			<p class="note">{option.info}</p>
+		</div>
+	</label>
+{/snippet}
+
 <style>.wrapper {
   display: flex;
   flex-flow: row wrap;
@@ -60,7 +69,7 @@ label input {
   accent-color: #259fc7;
 }
 label input:checked {
-  accent-color: #94dff6;
+  accent-color: #9fdaec;
 }
 label .text h5 {
   font-size: 1rem;
@@ -78,4 +87,4 @@ label.selected {
 }
 label.selected h5 {
   color: #ffffff;
-}</style>
+}</style>