@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/NumberInputProps.d.ts

@@ -1,29 +1,66 @@
 import type { InputVariant } from '../Types/Internal/InputVariant.js';
 import type { FormEventHandler } from 'svelte/elements';
 import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Props for the {@link NumberInput} component.
+ *
+ * `value` is `number | null`; `null` represents the explicit empty
+ * state. The component will clamp the value to `[min, max]` on every
+ * input event when those bounds are provided.
+ */
 export interface NumberInputProps {
+    /** Current numeric value. Bindable. `null` represents explicit empty. */
     value: number | null;
+    /** Render the "- optional" suffix next to `labelTop`. */
     optional?: boolean;
+    /** `id` on the `<input>`. */
     id?: string | undefined;
+    /** Lower bound used for native validation and runtime clamping. */
     min?: number | undefined;
+    /** Upper bound used for native validation and runtime clamping. */
     max?: number | undefined;
+    /** Label rendered above the input. */
     labelTop?: string | undefined;
+    /** Label rendered inside the input on the right. */
     labelRight?: string | undefined;
+    /** Native `placeholder` attribute. */
     placeholder?: string | undefined;
+    /** Native `required` attribute. */
     required?: boolean;
+    /** Render variant. See {@link InputVariant}. */
     variant?: InputVariant;
+    /**
+     * When false (default) the input restricts to integers and uses step=1.
+     * When true, `step=0.01` is applied and decimal entry is accepted.
+     */
     decimal?: boolean;
+    /** Force the invalid visual state. */
     invalid?: boolean;
+    /** When true, render invalid visuals for unmet `required`/`invalid`. */
     showErrorColours?: boolean;
+    /** Native `disabled` attribute. */
     disabled?: boolean | undefined;
+    /** Icon rendered on the left of the input. */
     leftIcon?: PartialIconProps | undefined;
+    /** Icon rendered on the right of the input. */
     rightIcon?: PartialIconProps | undefined;
+    /** Click handler for the left icon. */
     onLeftIconClick?: ((e: MouseEvent) => void) | undefined;
+    /** Click handler for the right icon. */
     onRightIconClick?: ((e: MouseEvent) => void) | undefined;
+    /** Bindable reference to the underlying `<input>` element. */
     inputRef?: HTMLInputElement | undefined;
+    /** `data-type` attribute, used by domain-aware tooling. */
     'data-type'?: string;
+    /** Blur handler forwarded to the `<input>`. */
     onblur?: (e: FocusEvent) => void;
+    /** Focus handler forwarded to the `<input>`. */
     onfocus?: (e: FocusEvent) => void;
+    /** Keydown handler forwarded to the `<input>`. Defaults to `passthrough`. */
     onkeydown?: (e: KeyboardEvent) => void;
+    /**
+     * Input event forwarded to the `<input>`. Fires AFTER the internal
+     * clamp step.
+     */
     oninput?: FormEventHandler<HTMLInputElement>;
 }

package/dist/Components/PageHeading.svelte

@@ -1,19 +1,8 @@
 <svelte:options runes />
 
-<script
-	lang="ts"
-	module
->
-	import type { Snippet } from 'svelte';
-
-	export interface PageHeadingProps {
-		children: Snippet;
-		subtitle?: Snippet | undefined;
-		extras?: Snippet | undefined;
-	}
-</script>
-
 <script lang="ts">
+	import type { PageHeadingProps } from './PageHeadingProps.js';
+
 	let { children, subtitle, extras }: PageHeadingProps = $props();
 </script>
 

package/dist/Components/PageHeading.svelte.d.ts

@@ -1,9 +1,4 @@
-import type { Snippet } from 'svelte';
-export interface PageHeadingProps {
-    children: Snippet;
-    subtitle?: Snippet | undefined;
-    extras?: Snippet | undefined;
-}
+import type { PageHeadingProps } from './PageHeadingProps.js';
 declare const PageHeading: import("svelte").Component<PageHeadingProps, {}, "">;
 type PageHeading = ReturnType<typeof PageHeading>;
 export default PageHeading;

package/dist/Components/PageHeadingProps.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+export interface PageHeadingProps {
+    /**
+     * Title snippet rendered inside the `<h1>`. Must produce a single,
+     * short line of text - this heading is also the semantic page
+     * landmark for screen readers, so prefer plain text and avoid block
+     * markup.
+     */
+    children: Snippet;
+    /**
+     * Optional sub-title rendered beneath the title in a one-line slot.
+     * Use for a status, breadcrumb tail, or short description. Wraps to
+     * a single visual row; longer content will be truncated by the
+     * surrounding mixin.
+     */
+    subtitle?: Snippet | undefined;
+    /**
+     * Optional trailing snippet rendered in a right-aligned button row.
+     * Use for primary page actions (Save, Edit, ...) or status chips
+     * such as `Bubble`. Omit for headings without actions.
+     */
+    extras?: Snippet | undefined;
+}

package/dist/Components/PageHeadingProps.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/PasswordInput.svelte

@@ -1,11 +1,12 @@
 <svelte:options runes />
 
 <script lang="ts">
+	import { cssLength, passthrough } from '../Helpers/Helpers.svelte.js';
 	import { ColourSet } from '../scss/colours.js';
 	import { Size } from '../Types/Internal/Size.js';
 	import Action from './Action.svelte';
 	import Icon from './Icon.svelte';
-	import type { InputProps } from './InputProps.js';
+	import type { PasswordInputProps } from './PasswordInputProps.js';
 	let {
 		value = $bindable(''),
 		label = undefined,
@@ -15,12 +16,13 @@
 		showInput = $bindable(false),
 		leftIcon = undefined,
 		inputRef = $bindable(),
-		...inputEvents
-	}: InputProps = $props();
+		autocomplete = 'current-password',
+		onblur,
+		onfocus,
+		onkeydown = passthrough,
+	}: PasswordInputProps = $props();
 
-	// let inputRef: HTMLInputElement | undefined = undefined;
-
-	function toggleVisibility() {
+	function toggleVisibility(): void {
 		showInput = !showInput;
 		inputRef?.focus();
 	}
@@ -30,29 +32,38 @@
 	<label>
 		{#if label}
 			<span class="for-default">{label}</span>
-			<span class="border">{label}</span>
+			<span
+				aria-hidden="true"
+				class="border">{label}</span
+			>
 		{/if}
-		<!-- style="--background-colour: {leftIcon?.backgroundColour};" -->
 		<div class="icon-container">
 			{#if leftIcon}
 				<Icon
 					name={leftIcon.name}
 					size={leftIcon.size ?? Size.Medium}
 					float
-					left="0.75rem"
-					top="50%"
-					anchorX="0"
-					anchorY="-50%"
+					left={cssLength('0.75rem')}
+					top={cssLength('50%')}
+					anchorX={cssLength('0')}
+					anchorY={cssLength('-50%')}
 				/>
 			{/if}
 			<input
 				class="for-default"
-				{...inputEvents}
 				class:left-pad={leftIcon != undefined}
 				class:right-pad={true}
-				{...{ type: showInput ? 'text' : 'password' }}
+				type={showInput ? 'text' : 'password'}
+				{autocomplete}
+				autocapitalize="none"
+				autocorrect="off"
+				spellcheck="false"
+				data-form-type="password"
 				bind:value
 				bind:this={inputRef}
+				{onblur}
+				{onfocus}
+				{onkeydown}
 				{placeholder}
 				{required}
 				{disabled}
@@ -60,8 +71,9 @@
 
 			<div class="right-icon">
 				<Action
+					label={showInput ? 'Hide password' : 'Show password'}
 					colourSet={showInput ? ColourSet.Secondary : ColourSet.Auxiliary}
-					icon={{ name: 'assessment' }}
+					icon={{ name: showInput ? 'visibility-off' : 'visibility' }}
 					size={Size.MediumSmall}
 					onclick={toggleVisibility}
 				/>

package/dist/Components/PasswordInput.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { InputProps } from './InputProps.js';
-declare const PasswordInput: import("svelte").Component<InputProps, {}, "value" | "inputRef" | "showInput">;
+import type { PasswordInputProps } from './PasswordInputProps.js';
+declare const PasswordInput: import("svelte").Component<PasswordInputProps, {}, "value" | "inputRef" | "showInput">;
 type PasswordInput = ReturnType<typeof PasswordInput>;
 export default PasswordInput;

package/dist/Components/PasswordInputProps.d.ts

@@ -0,0 +1,21 @@
+import type { InputProps } from './InputProps.js';
+/**
+ * Props for the {@link PasswordInput} component.
+ *
+ * Extends the shared {@link InputProps} with password-specific fields.
+ * The `autocomplete` value should be set explicitly based on the form
+ * context:
+ * - `current-password` for sign-in flows (the default).
+ * - `new-password` for password creation / change flows.
+ * - `one-time-code` for OTP / 2FA inputs.
+ * - `off` to opt out of browser autofill entirely.
+ *
+ * Per OWASP / NIST guidance, lacking this attribute degrades password
+ * manager interop and can push users toward weaker passwords.
+ */
+export interface PasswordInputProps extends InputProps {
+    /**
+     * Native `autocomplete` value. Defaults to `'current-password'`.
+     */
+    autocomplete?: 'current-password' | 'new-password' | 'one-time-code' | 'off';
+}

package/dist/Components/PasswordInputProps.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Portal.svelte

@@ -7,17 +7,28 @@
 	let { target = browser ? globalThis.document.body : undefined, children }: PortalProps = $props();
 
 	let ref: HTMLElement | undefined = $state();
+	let lastTarget: HTMLElement | undefined;
 
 	$effect(() => {
-		if (target && ref) {
-			target.appendChild(ref);
+		// Identity guard: only re-parent when `target` actually changes.
+		// `appendChild` already moves the node when called, so this avoids
+		// unnecessary detach/attach when an upstream `$state` target
+		// re-fires the effect without changing identity.
+		if (target && ref && target !== lastTarget) {
+			if (target.ownerDocument === globalThis.document) {
+				target.appendChild(ref);
+				lastTarget = target;
+			}
 		}
 
+		// Cleanup is necessary, not redundant: without it, the appended
+		// node would remain inside `target` after the Portal unmounts,
+		// because `target` outlives the component.
 		return () => {
 			ref?.parentNode?.removeChild(ref);
+			lastTarget = undefined;
 		};
 	});
-	// this block is almost needless/useless (if not totally) as, on destroy, the ref will no longer exist/be in the DOM anyways
 </script>
 
 <div bind:this={ref}>

package/dist/Components/PortalProps.d.ts

@@ -1,5 +1,24 @@
 import type { Snippet } from 'svelte';
 export interface PortalProps {
-    target?: HTMLElement;
+    /**
+     * The DOM element to receive the portalled children. Defaults to
+     * `document.body` in the browser, or `undefined` during SSR (in
+     * which case nothing is appended until the component is hydrated).
+     *
+     * The element must belong to the active document tree - the
+     * portal does not validate this, and detached or cross-document
+     * targets will produce inert DOM. Pass only trusted, in-tree
+     * elements: arbitrary user input must not reach this prop.
+     */
+    target?: HTMLElement | undefined;
+    /**
+     * The children snippet to render inside `target`. Rendered as a
+     * single wrapper `<div>` which is appended to `target` on mount
+     * and removed on unmount.
+     *
+     * The default `Snippet` parameter tuple is empty, which is correct
+     * here - the portal does not pass arguments to the rendered
+     * snippet.
+     */
     children: Snippet;
 }

package/dist/Components/ProgressBubble.svelte

@@ -1,78 +1,106 @@
 <svelte:options runes />
 
 <script lang="ts">
-	import { devCatch, getCanvasContext } from '../Helpers/Helpers.svelte.js';
-	import { tick } from 'svelte';
+	import { useAsyncFlag } from '../Helpers/AsyncFlag.svelte.js';
+	import { getCanvasContext } from '../Helpers/Helpers.svelte.js';
 	import type { BubbleColour } from './BubbleColour.js';
 	import type { ProgressBubbleProps } from './ProgressBubbleProps.js';
 
-	let { value, colours }: ProgressBubbleProps = $props();
+	const { value, colours }: ProgressBubbleProps = $props();
 
-	let current = $derived(value[0]);
-	// let current = $derived(37)
-	let total = $derived(value[1]);
-	let progress = $derived(`${current}/${total}`);
+	const current = $derived(value[0]);
+	const total = $derived(value[1]);
+	const progress = $derived(`${current}/${total}`);
+
+	// Clamp the percentage so callers passing `current > total` do not
+	// blow past the bar's edge.
+	const percent = $derived(Math.min((current / total) * 100, 100));
 
 	let progressBarRef: HTMLDivElement | undefined = $state();
 
-	// for some reason, doing this in a derived-by puts the browser in some kind of infinite loop
-	let fitsInProgressBar = $state(false);
+	// Observed inline-size of the filled bar. A `ResizeObserver` is used
+	// instead of `getBoundingClientRect()` inside an `$effect`: the latter
+	// forces a synchronous layout flush on every `progress` change, which
+	// is expensive inside a table with many `ProgressBubble` cells. The
+	// observer notifies us only when the bar's actual rendered size
+	// changes, and does so via a microtask scheduled by the browser so we
+	// never force layout ourselves.
+	let barWidth = $state(0);
 	$effect(() => {
-		if (progress && progressBarRef) {
-			const oldRef = progressBarRef;
-			tick()
-				.then(() => {
-					if (oldRef === progressBarRef) {
-						const textWidth = getCanvasContext()?.measureText(`__${progress}__`).width ?? 0;
-						const progresValueWidth = progressBarRef.getBoundingClientRect().width;
-
-						fitsInProgressBar = progresValueWidth > textWidth;
-					} else {
-						fitsInProgressBar = false;
-					}
-				})
-				.catch(devCatch);
+		if (!progressBarRef) {
+			return;
 		}
+		const ro = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			barWidth = entry.borderBoxSize[0]?.inlineSize ?? entry.contentRect.width;
+		});
+		ro.observe(progressBarRef);
+		return () => {
+			ro.disconnect();
+		};
 	});
 
-	let awaitedColours: BubbleColour | undefined = $state();
-
-	$effect(() => {
-		if (colours) {
-			if (colours instanceof Promise) {
-				colours
-					.then((c) => {
-						awaitedColours = c;
-					})
-					.catch((e: unknown) => {
-						devCatch(e);
-						awaitedColours = undefined;
-					});
-			} else {
-				awaitedColours = colours;
-			}
-		} else {
-			awaitedColours = undefined;
-		}
+	// Whether the `current/total` label fits inside the filled bar.
+	// Measured via a memoised offscreen canvas so we do not trigger
+	// layout.
+	const fitsInProgressBar = $derived.by(() => {
+		const textWidth = getCanvasContext()?.measureText(`__${progress}__`).width ?? 0;
+		return barWidth > textWidth;
 	});
+
+	// `colours` may be a bare `BubbleColour`, a Promise resolving to one,
+	// or undefined. Routed through `useAsyncFlag` which (a) cancels stale
+	// Promises via a sequence ticket so the freshest value always wins,
+	// (b) reports errors through `ToastContext` when one is mounted, and
+	// (c) falls back to `undefined` while no resolution is available.
+	const awaitedColoursFlag = useAsyncFlag<BubbleColour | undefined>(() => colours, undefined);
+	const awaitedColours = $derived(awaitedColoursFlag.value);
+
+	// Precompute the wrapper and bar style strings. Each colour comes
+	// from the trusted `Colour` registry (see `Bubble.svelte` security
+	// note) so interpolation into `style="..."` is safe.
+	const wrapperStyle = $derived(
+		awaitedColours
+			? `--bar-background-colour: ${awaitedColours.backgroundColour}; --text-colour: ${awaitedColours.colour};`
+			: ''
+	);
+	const barStyle = $derived(`width: ${percent}%;`);
 </script>
 
 <div
 	class="progress-wrapper"
-	style={awaitedColours
-		? `--bar-background-colour: ${awaitedColours.backgroundColour}; --text-colour: ${awaitedColours.colour};`
-		: ''}
+	style={wrapperStyle}
 >
-	<progress value={current} max={total}>{progress}</progress>
+	<!--
+		Native `<progress>` is kept as a fallback for assistive tech that
+		ignores ARIA progressbar roles. Previously it was `display: none`,
+		which removed it from the accessibility tree; it is now visually
+		hidden (off-screen, zero opacity, but still in the layout tree).
+	-->
+	<progress
+		class="visually-hidden"
+		value={current}
+		max={total}>{progress}</progress
+	>
 
-	<div class="progress-background" role="progressbar">
+	<div
+		class="progress-background"
+		role="progressbar"
+		aria-valuenow={current}
+		aria-valuemin={0}
+		aria-valuemax={total}
+		aria-valuetext={progress}
+	>
 		<div
 			class:fits={fitsInProgressBar}
 			class="progress-value"
 			bind:this={progressBarRef}
-			style={`width: ${Math.min((current / total) * 100, 100)}%;`}
+			style={barStyle}
 		>
-			<span class:fits={fitsInProgressBar} class="progress-text">{progress}</span>
+			<span
+				class:fits={fitsInProgressBar}
+				class="progress-text">{progress}</span
+			>
 		</div>
 	</div>
 </div>
@@ -93,6 +121,15 @@
   border-radius: var(--progress-bar-radius, 12px);
   transition: border-radius ease-out 0.15s 0s;
 }
+@media (prefers-reduced-motion: reduce) {
+  .progress-wrapper .progress-background,
+  .progress-wrapper .progress-value {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
 .progress-wrapper .progress-background {
   position: relative;
   width: 100%;
@@ -107,14 +144,22 @@
   position: relative;
 }
 
-progress {
-  display: none;
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
 }
 
 .progress-text {
   position: absolute;
-  top: 8px;
-  bottom: 8px;
+  top: 0.5rem;
+  bottom: 0.5rem;
   left: -2px;
   right: -2px;
   max-height: 100%;

package/dist/Components/ProgressBubbleProps.d.ts

@@ -1,5 +1,26 @@
+import type { AsyncFlag } from '../Types/Internal/AsyncFlag.js';
 import type { BubbleColour } from './BubbleColour.js';
+/**
+ * Props for {@link ProgressBubble}.
+ *
+ * Renders a horizontal progress bar with `current/total` text embedded
+ * inside (or alongside) the filled portion. The `value` tuple uses a
+ * labelled-tuple type so consumers cannot confuse the two slots.
+ */
 export interface ProgressBubbleProps {
-    value: [number, number];
-    colours?: BubbleColour | Promise<BubbleColour> | undefined;
+    /**
+     * Labelled `[current, total]` tuple. The first slot is the amount
+     * progressed; the second is the upper bound. Previously typed as
+     * `[number, number]`; the labelled-tuple variant compiles
+     * identically but documents the position in the editor's tooltip.
+     */
+    value: [current: number, total: number];
+    /**
+     * Optional foreground / background colour pair, possibly arriving
+     * asynchronously. Typed via {@link AsyncFlag} so the resolution
+     * pattern matches the rest of the library (buttons, tabs, modals).
+     * Resolved internally by `useAsyncFlag`; stale Promises are
+     * discarded.
+     */
+    colours?: AsyncFlag<BubbleColour> | undefined;
 }