@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Nav/NavServiceMenuList.svelte

@@ -4,13 +4,19 @@
 	import { Colour } from '../../scss/colours.js';
 	import { Size } from '../../Types/Internal/Size.js';
 	import Icon from '../Icon.svelte';
+	import { Dimensions } from './Dimensions.js';
 	import type { NavServiceMenuListProps } from './NavServiceMenuListProps.js';
 	import ServiceMenuItem from './ServiceMenuItem.svelte';
 
 	const { title, items, icon }: NavServiceMenuListProps = $props();
 </script>
 
-<div class="wrapper">
+<div
+	class="wrapper"
+	style="--icon-column-width: {Dimensions.smallPanelWidth}rem"
+	role="group"
+	aria-label={title}
+>
 	<h3>
 		<div class="icon">
 			{#if icon}
@@ -24,7 +30,10 @@
 		{title}
 	</h3>
 
-	<div class="items">
+	<div
+		class="items"
+		role="list"
+	>
 		{#each items as { item } (item.label)}
 			<ServiceMenuItem {item} />
 		{/each}
@@ -43,7 +52,7 @@ h3 .icon {
   flex-flow: row nowrap;
   align-items: center;
   justify-content: center;
-  width: 3.4rem;
+  width: var(--icon-column-width);
 }
 
 .wrapper {

package/dist/Components/Nav/NavServiceMenuListProps.d.ts

@@ -1,7 +1,31 @@
 import type { IconProps } from '../IconProps.js';
 import type { SideMenuItemProps } from './SideMenuItemProps.js';
+/**
+ * Props for the {@link NavServiceMenuList} component.
+ *
+ * A titled, optionally-iconed list of {@link ServiceMenuItem} entries.
+ * Used inside `ServicesNav` to render a single service grouping
+ * (e.g. "Orders", "Receiving") with its child links.
+ */
 export interface NavServiceMenuListProps {
-    items: Array<SideMenuItemProps>;
+    /**
+     * The menu entries to render in order. Each entry wraps a
+     * {@link CallbackButtonWithIcon} via `SideMenuItemProps.item`.
+     *
+     * Marked `readonly` so the component cannot accidentally mutate
+     * caller state. Callers pass an array literal or a `$state` value.
+     */
+    items: ReadonlyArray<SideMenuItemProps>;
+    /** The list heading shown above the items. */
     title: string;
+    /**
+     * Optional icon rendered to the left of the title.
+     *
+     * `IconProps` is spread onto the rendered `<Icon>`. Default colour
+     * and size are supplied by the component; pass only the overrides
+     * you need. The `name` property is required by `IconProps` and is
+     * effectively required here too: omit the prop entirely if no icon
+     * is wanted.
+     */
     icon?: IconProps;
 }

package/dist/Components/Nav/NavTab.svelte

@@ -1,56 +1,24 @@
 <svelte:options runes />
 
-<script lang="ts">
-	import { devCatch } from '../../Helpers/Helpers.svelte.js';
+<script
+	lang="ts"
+	generics="Args"
+>
+	import { useAsyncFlag } from '../../Helpers/AsyncFlag.svelte.js';
 	import { Colour } from '../../scss/colours.js';
 	import { Size } from '../../Types/Internal/Size.js';
 	import Icon from '../Icon.svelte';
 	import type { NavTabProps } from './NavTabProps.js';
 
-	let { option, selected }: NavTabProps = $props();
-
-	let disabled = $state(true);
-	let visible = $state(true);
-	let isValid = $state(true);
-
-	$effect(() => {
-		if (typeof option.isValid === 'boolean') {
-			isValid = option.isValid;
-		} else {
-			option.isValid
-				?.then((v) => {
-					isValid = v;
-				})
-				.catch(devCatch);
-		}
-	});
-	$effect(() => {
-		if (typeof option.disabled === 'boolean') {
-			disabled = option.disabled;
-		} else if (option.disabled == undefined) {
-			disabled = false;
-		} else {
-			option.disabled
-				.then((v) => {
-					disabled = v;
-				})
-				.catch(devCatch);
-		}
-	});
+	// `Args` defaults to `unknown` on the props interface, but we still
+	// pass the generic explicitly so consumers using the component as
+	// `<NavTab>` inside a typed snippet receive the same `Args` rune.
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+	let { option, selected }: NavTabProps<Args> = $props();
 
-	$effect(() => {
-		if (typeof option.visible === 'boolean') {
-			visible = option.visible;
-		} else if (option.visible == undefined) {
-			visible = true;
-		} else {
-			option.visible
-				.then((v) => {
-					visible = v;
-				})
-				.catch(devCatch);
-		}
-	});
+	const isValid = useAsyncFlag(() => option.isValid, true);
+	const disabled = useAsyncFlag(() => option.disabled, false);
+	const visible = useAsyncFlag(() => option.visible, true);
 </script>
 
 <button
@@ -60,9 +28,12 @@
 	}}
 	type="button"
 	class="tab"
-	{disabled}
-	class:invalid={!isValid}
-	class:hidden={!visible}
+	role="tab"
+	aria-selected={selected}
+	aria-label={option.label}
+	disabled={disabled.value}
+	class:invalid={!isValid.value}
+	class:hidden={!visible.value}
 >
 	<Icon
 		name="nothing"

package/dist/Components/Nav/NavTab.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { NavTabProps } from './NavTabProps.js';
-declare const NavTab: import("svelte").Component<NavTabProps, {}, "">;
-type NavTab = ReturnType<typeof NavTab>;
+declare function $$render<Args>(): {
+    props: NavTabProps<Args>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Args> {
+    props(): ReturnType<typeof $$render<Args>>['props'];
+    events(): ReturnType<typeof $$render<Args>>['events'];
+    slots(): ReturnType<typeof $$render<Args>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Args>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Args>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Args>['props']>, ReturnType<__sveltets_Render<Args>['events']>, ReturnType<__sveltets_Render<Args>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Args>['bindings']>;
+    } & ReturnType<__sveltets_Render<Args>['exports']>;
+    <Args>(internal: unknown, props: ReturnType<__sveltets_Render<Args>['props']> & {}): ReturnType<__sveltets_Render<Args>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const NavTab: $$IsomorphicComponent;
+type NavTab<Args> = InstanceType<typeof NavTab<Args>>;
 export default NavTab;

package/dist/Components/Nav/NavTabProps.d.ts

@@ -1,5 +1,19 @@
 import type { TabOption } from '../../Types/Internal/TabOption.js';
-export interface NavTabProps {
-    option: TabOption<unknown>;
+/**
+ * Props for the {@link NavTab} component.
+ *
+ * `NavTab` is the tab button variant used by `ServicesNav` inside the
+ * shared `HorizontalTabGroup`. It mirrors the underlying
+ * {@link TabOption} `isValid` / `disabled` / `visible` async-flag
+ * contract via the shared `useAsyncFlag` helper, so consumers can
+ * pass plain booleans or Promises interchangeably.
+ *
+ * Generic over `Args` so the option's `content` snippet can be typed
+ * without resorting to `unknown` at the call site.
+ */
+export interface NavTabProps<Args = unknown> {
+    /** The tab option to render. */
+    option: TabOption<Args>;
+    /** Whether this tab is the currently selected one. */
     selected: boolean;
 }

package/dist/Components/Nav/ServiceMenuItem.svelte

@@ -2,9 +2,8 @@
 
 <script lang="ts">
 	import { dev } from '$app/environment';
-	import { resolve } from '$app/paths';
 	import { page } from '$app/state';
-	import { devCatch } from '../../Helpers/Helpers.svelte.js';
+	import { useAsyncFlag } from '../../Helpers/AsyncFlag.svelte.js';
 	import { Size } from '../../Types/Internal/Size.js';
 	import Icon from '../Icon.svelte';
 	import { Dimensions } from './Dimensions.js';
@@ -14,21 +13,31 @@
 
 	const selected = $derived(maybeSelected ?? (item.path ? page.url.pathname == item.path : false));
 
-	let visible = $state(true);
+	const visible = useAsyncFlag(() => item.visible, true);
 
-	$effect(() => {
-		if (typeof item.visible === 'boolean') {
-			visible = item.visible;
-		} else if (item.visible == undefined) {
-			visible = true;
-		} else {
-			item.visible
-				.then((v) => {
-					visible = v;
-				})
-				.catch(devCatch);
+	/**
+	 * Constrain the rendered `href` to safe, relative paths only.
+	 *
+	 * `item.path` is typed as the SvelteKit `Pathname` brand at the
+	 * boundary, but the property is still a `string` at runtime. To
+	 * keep the trust boundary tight we reject anything that contains
+	 * a URL scheme (anything matching `^[a-z][a-z0-9+.-]*:`) and any
+	 * input that does not start with `/`. Disallowed values resolve
+	 * to `#` so the link is harmless if a future consumer supplies an
+	 * unsafe value.
+	 */
+	function safeHref(path: string): string {
+		if (typeof path !== 'string' || path.length === 0) {
+			return '#';
 		}
-	});
+		if (!path.startsWith('/')) {
+			return '#';
+		}
+		if (/^[a-z][a-z0-9+.-]*:/i.test(path)) {
+			return '#';
+		}
+		return path;
+	}
 </script>
 
 {#if item.callback}
@@ -38,7 +47,7 @@
 		}}
 		style="--iconWidth: {Dimensions.smallPanelWidth}rem"
 		class:selected
-		class:hidden={!visible}
+		class:hidden={!visible.value}
 	>
 		<!-- <div class="selected-marker"></div> -->
 		<div class="icon-wrapper">
@@ -59,12 +68,12 @@
 		</div></button
 	>
 {:else if item.path}
-	<!-- FIXME why is this type cast required? -->
 	<a
-		href={resolve(item.path as '/')}
+		href={safeHref(item.path)}
 		style="--iconWidth: {Dimensions.smallPanelWidth}rem"
+		aria-current={selected ? 'page' : undefined}
 		class:selected
-		class:hidden={!visible}
+		class:hidden={!visible.value}
 	>
 		<!-- <div class="selected-marker"></div> -->
 		<div class="icon-wrapper">
@@ -126,7 +135,7 @@ a .text .label {
 button .subtitle,
 a .subtitle {
   font-size: 0.875rem;
-  color: #9da9b1;
+  color: #718a9b;
 }
 button,
 a {

package/dist/Components/Nav/ServicesNav.svelte

@@ -1,35 +1,62 @@
 <svelte:options runes />
 
-<script lang="ts">
+<script
+	lang="ts"
+	generics="Args"
+>
+	import { devCatch } from '../../Helpers/Helpers.svelte.js';
 	import type { TabOption } from '../../Types/Internal/TabOption.js';
 	import HorizontalTabGroup from '../HorizontalTabGroup.svelte';
 	import NavTab from './NavTab.svelte';
 	import type { ServicesNavProps } from './ServicesNavProps.js';
 
-	const { onclose, serviceTabs, selectedServiceTab }: ServicesNavProps = $props();
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+	const { onclose, serviceTabs, selectedServiceTab }: ServicesNavProps<Args> = $props();
+
+	let dialogRef: HTMLDialogElement | undefined = $state.raw();
 
-	let servicesDialogRef: HTMLDivElement | undefined = $state.raw();
+	function fireClose(): void {
+		const result = onclose();
+		if (result instanceof Promise) {
+			result.catch((e: unknown) => {
+				devCatch(e);
+			});
+		}
+	}
+
+	// Open the dialog as soon as we mount; native showModal() gives us a
+	// real focus trap, Escape-to-close, and inert background without any
+	// manual aria-modal / tabindex bookkeeping.
+	$effect(() => {
+		const dialog = dialogRef;
+		if (dialog && !dialog.open) {
+			dialog.showModal();
+		}
+	});
 </script>
 
-<div
-	bind:this={servicesDialogRef}
-	role="dialog"
-	tabindex="0"
+<dialog
+	bind:this={dialogRef}
+	aria-label="Services"
 	class="overlay"
-	onclick={(e) => {
-		e.stopPropagation();
-		if (servicesDialogRef === e.target) {
-			onclose();
-		}
+	oncancel={(e) => {
+		// Escape fires `cancel` first; prevent the native close so we
+		// fully delegate to the parent (it owns the visibility flag).
+		e.preventDefault();
+		fireClose();
 	}}
-	onkeydown={(e) => {
-		if (e.key === 'Escape') {
-			onclose();
+	onclick={(e) => {
+		// Native <dialog> click target is the dialog element itself when
+		// the user clicks the backdrop; clicks on inner content bubble
+		// up with a different target.
+		if (dialogRef === e.target) {
+			fireClose();
 		}
 	}}
 >
 	<div
 		role="navigation"
+		aria-label="Services tabs"
 		class="services"
 	>
 		<HorizontalTabGroup
@@ -41,22 +68,35 @@
 			grow
 		/>
 	</div>
-</div>
+</dialog>
 
-{#snippet navTab(option: TabOption<unknown>, selected: boolean)}
+{#snippet navTab(option: TabOption<Args>, selected: boolean)}
 	<NavTab
 		{option}
 		{selected}
 	/>
 {/snippet}
 
-<style>div.overlay {
+<style>dialog.overlay {
   position: fixed;
   top: calc(3.25rem + var(--env-border-height, 0));
   bottom: 0;
   left: 0;
   right: 0;
+  width: 100%;
+  height: auto;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: transparent;
   z-index: 98;
+  overflow: visible;
+  color: inherit;
+}
+
+dialog.overlay::backdrop {
   background-color: rgba(0, 0, 0, 0.2);
 }
 
@@ -73,20 +113,6 @@ div.services {
   flex-flow: row nowrap;
   align-items: stretch;
   justify-content: stretch;
-  height: min(710px, 80%);
-  width: 800px;
-}
-
-div.wrapper {
-  display: flex;
-  flex-flow: row wrap;
-  width: 600px;
-  gap: 1.5rem;
-  --input-width: 100%;
-}
-div.wrapper .row {
-  width: 100%;
-  gap: 1.5rem;
-  display: flex;
-  flex-flow: row nowrap;
+  height: var(--services-nav-height, min(710px, 80%));
+  width: var(--services-nav-width, 800px);
 }</style>

package/dist/Components/Nav/ServicesNav.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { ServicesNavProps } from './ServicesNavProps.js';
-declare const ServicesNav: import("svelte").Component<ServicesNavProps, {}, "">;
-type ServicesNav = ReturnType<typeof ServicesNav>;
+declare function $$render<Args>(): {
+    props: ServicesNavProps<Args>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Args> {
+    props(): ReturnType<typeof $$render<Args>>['props'];
+    events(): ReturnType<typeof $$render<Args>>['events'];
+    slots(): ReturnType<typeof $$render<Args>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Args>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Args>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Args>['props']>, ReturnType<__sveltets_Render<Args>['events']>, ReturnType<__sveltets_Render<Args>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Args>['bindings']>;
+    } & ReturnType<__sveltets_Render<Args>['exports']>;
+    <Args>(internal: unknown, props: ReturnType<__sveltets_Render<Args>['props']> & {}): ReturnType<__sveltets_Render<Args>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const ServicesNav: $$IsomorphicComponent;
+type ServicesNav<Args> = InstanceType<typeof ServicesNav<Args>>;
 export default ServicesNav;

package/dist/Components/Nav/ServicesNavProps.d.ts

@@ -1,6 +1,22 @@
 import type { TabOption } from '../../Types/Internal/TabOption.js';
-export interface ServicesNavProps {
-    onclose: () => void;
-    serviceTabs: Array<TabOption<unknown>>;
-    selectedServiceTab: TabOption<unknown> | undefined;
+/**
+ * Props for the {@link ServicesNav} dropdown.
+ *
+ * `ServicesNav` is the floating service-switcher panel rendered above
+ * the rest of the app chrome. It wraps the shared `HorizontalTabGroup`
+ * with the `NavTab` snippet so each service appears as a labelled
+ * tab. Generic over `Args` so the option's `content` snippet can be
+ * typed by the host rather than collapsing to `unknown`.
+ */
+export interface ServicesNavProps<Args = unknown> {
+    /**
+     * Called when the user dismisses the dropdown (click on the
+     * overlay or `Escape`). May return a Promise so async cleanup is
+     * supported.
+     */
+    onclose: () => void | Promise<void>;
+    /** The service tabs to render. */
+    serviceTabs: ReadonlyArray<TabOption<Args>>;
+    /** The currently selected tab, matched by reference. */
+    selectedServiceTab: TabOption<Args> | undefined;
 }

package/dist/Components/Nav/SideMenuItemProps.d.ts

@@ -1,7 +1,23 @@
 import type { CallbackButtonWithIcon } from './CallbackButtonWithIcon.js';
 import type { SideMenuItemVariant } from './SideMenuItemVariant.js';
+/**
+ * Props for the {@link ServiceMenuItem} component.
+ *
+ * Each item is either a path-bearing link or a callback-bearing
+ * button (encoded by the {@link CallbackButtonWithIcon} discriminated
+ * union). Selection state is auto-derived from the current
+ * `page.url.pathname` for path items unless the host overrides it
+ * via `selected`.
+ */
 export interface SideMenuItemProps {
+    /** The underlying nav button data (path-or-callback). */
     item: CallbackButtonWithIcon;
+    /**
+     * Override the auto-derived selection. When omitted (and `item.path`
+     * is supplied) selection is computed by comparing `page.url.pathname`
+     * to `item.path`.
+     */
     selected?: boolean;
+    /** Visual variant. */
     variant?: SideMenuItemVariant;
 }

package/dist/Components/NumberInput.svelte

@@ -1,13 +1,14 @@
 <svelte:options runes />
 
 <script lang="ts">
+	import { cssLength, passthrough } from '../Helpers/Helpers.svelte.js';
 	import { InputVariant } from '../Types/Internal/InputVariant.js';
 	import { Size } from '../Types/Internal/Size.js';
 	import Icon from './Icon.svelte';
 	import type { NumberInputProps } from './NumberInputProps.js';
 	let {
 		id,
-		value = $bindable(), // FIXME why is undefined allowed here?
+		value = $bindable(null),
 		min,
 		max,
 		labelTop,
@@ -27,28 +28,34 @@
 
 		onblur,
 		onfocus,
-		onkeydown,
+		onkeydown = passthrough,
 		oninput,
 
 		inputRef = $bindable(),
 		'data-type': dataType,
 	}: NumberInputProps = $props();
 
-	// NOTE cannot alter signature because it's passed by a use: directive
-	function numberValidator(_node: HTMLInputElement, _newValue: number | null) {
-		return {
-			update(newValue: number) {
-				const underMinimum = min != undefined && min > newValue;
-				const overMaximum = max != undefined && max < newValue;
-
-				value = isNaN(newValue) ? 0 : underMinimum ? min : overMaximum ? max : newValue;
-			},
-		};
+	function clamp(e: Event): void {
+		const raw = (e.target as HTMLInputElement).value;
+		if (raw === '') {
+			if (value !== null) {
+				value = null;
+			}
+			return;
+		}
+		const next = Number(raw);
+		if (isNaN(next)) {
+			return;
+		}
+		const lo = min ?? -Infinity;
+		const hi = max ?? Infinity;
+		const clamped = Math.max(lo, Math.min(hi, next));
+		if (clamped !== value) {
+			value = clamped;
+		}
 	}
 
-	let isInvalid = $derived(
-		showErrorColours && ((required && (value == null || value.toString().trim() === '')) || invalid)
-	);
+	const isInvalid = $derived(showErrorColours && ((required && value == null) || invalid));
 </script>
 
 <div
@@ -69,13 +76,13 @@
 			>
 			{#if variant === InputVariant.Default}
 				<span
+					aria-hidden="true"
 					class="border"
 					class:invalid={isInvalid}
 					>{labelTop}{#if optional}<i>&nbsp;- optional</i>{/if}</span
 				>
 			{/if}
 		{/if}
-		<!-- style="--background-colour: {leftIcon?.backgroundColour ?? rightIcon?.backgroundColour};" -->
 		<div
 			class="icon-container"
 			class:for-modal={variant == InputVariant.Modal}
@@ -86,10 +93,10 @@
 					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}
 				/>
@@ -99,16 +106,19 @@
 				class:invalid={isInvalid}
 				class:for-default={variant === InputVariant.Default}
 				data-type={dataType}
-				use:numberValidator={value}
 				class:left-pad={leftIcon != undefined}
 				class:right-pad={rightIcon != undefined || (labelRight && variant == InputVariant.Modal)}
 				class:for-modal={variant == InputVariant.Modal}
 				type="number"
+				aria-invalid={isInvalid || undefined}
 				bind:value
 				{onblur}
 				{onfocus}
 				{onkeydown}
-				{oninput}
+				oninput={(e) => {
+					clamp(e);
+					oninput?.(e);
+				}}
 				bind:this={inputRef}
 				{placeholder}
 				{required}
@@ -123,10 +133,10 @@
 					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}
 				/>
@@ -379,5 +389,5 @@ input[type=number] {
 input::-webkit-outer-spin-button,
 input::-webkit-inner-spin-button {
   -webkit-appearance: none;
-  margin: 0; /* <-- Apparently some margin are still there even though it's hidden */
+  margin: 0;
 }</style>