@lavalogic/scoria 0.35.0 → 0.37.0

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

@@ -1,25 +1,36 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import { browser } from '$app/environment';
-	import type { PortalProps } from './PortalProps.js';
-
-	let { target = browser ? globalThis.document.body : undefined, children }: PortalProps = $props();
-
-	let ref: HTMLElement | undefined = $state();
-
-	$effect(() => {
-		if (target && ref) {
-			target.appendChild(ref);
-		}
-
-		return () => {
-			ref?.parentNode?.removeChild(ref);
-		};
-	});
-	// 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}>
-	{@render children()}
-</div>
+<svelte:options runes />
+
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import type { PortalProps } from './PortalProps.js';
+
+	let { target = browser ? globalThis.document.body : undefined, children }: PortalProps = $props();
+
+	let ref: HTMLElement | undefined = $state();
+	let lastTarget: HTMLElement | undefined;
+
+	$effect(() => {
+		// 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;
+		};
+	});
+</script>
+
+<div bind:this={ref}>
+	{@render children()}
+</div>

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,82 +1,110 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import { devCatch, getCanvasContext } from '../Helpers/Helpers.svelte.js';
-	import { tick } from 'svelte';
-	import type { BubbleColour } from './BubbleColour.js';
-	import type { ProgressBubbleProps } from './ProgressBubbleProps.js';
-
-	let { value, colours }: ProgressBubbleProps = $props();
-
-	let current = $derived(value[0]);
-	// let current = $derived(37)
-	let total = $derived(value[1]);
-	let progress = $derived(`${current}/${total}`);
-
-	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);
-	$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);
-		}
-	});
-
-	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;
-		}
-	});
-</script>
-
-<div
-	class="progress-wrapper"
-	style={awaitedColours
-		? `--bar-background-colour: ${awaitedColours.backgroundColour}; --text-colour: ${awaitedColours.colour};`
-		: ''}
->
-	<progress value={current} max={total}>{progress}</progress>
-
-	<div class="progress-background" role="progressbar">
-		<div
-			class:fits={fitsInProgressBar}
-			class="progress-value"
-			bind:this={progressBarRef}
-			style={`width: ${Math.min((current / total) * 100, 100)}%;`}
-		>
-			<span class:fits={fitsInProgressBar} class="progress-text">{progress}</span>
-		</div>
-	</div>
-</div>
-
+<svelte:options runes />
+
+<script lang="ts">
+	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';
+
+	const { value, colours }: ProgressBubbleProps = $props();
+
+	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();
+
+	// 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 (!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();
+		};
+	});
+
+	// 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={wrapperStyle}
+>
+	<!--
+		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"
+		aria-valuenow={current}
+		aria-valuemin={0}
+		aria-valuemax={total}
+		aria-valuetext={progress}
+	>
+		<div
+			class:fits={fitsInProgressBar}
+			class="progress-value"
+			bind:this={progressBarRef}
+			style={barStyle}
+		>
+			<span
+				class:fits={fitsInProgressBar}
+				class="progress-text">{progress}</span
+			>
+		</div>
+	</div>
+</div>
+
 <style>.progress-wrapper {
   width: 100%;
   height: 100%;
@@ -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%;
@@ -128,4 +173,4 @@ progress {
 }
 .progress-text.fits {
   color: var(--text-colour, #3a4952);
-}</style>
+}</style>

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