@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Contexts/ContextMenu.svelte

@@ -1,19 +1,44 @@
 <svelte:options runes />
 
-<!-- 
+<!--
 @component
+Visual host for `ContextMenuContext`. Renders the fixed-positioned
+`<ul role="menu">` near the `(x, y)` coordinates the context exposes,
+and clamps the position so the menu never spills off the viewport.
 
+Mounted exactly once at the app root by `ContextWrapper`; consumers do
+not render `ContextMenu` directly. Open a menu through the context:
 
- -->
+```svelte
+<script lang="ts">
+	import { ContextMenuContext } from '@lavalogic/scoria';
+	import { getContext } from 'svelte';
+
+	const ctx = getContext<ContextMenuContext>(ContextMenuContext.identifier);
+</script>
+
+<button oncontextmenu={(e) => ctx.openContextMenu(e, items)}>
+	Right-click me
+</button>
+```
+
+### Keyboard
+
+`Escape` closes the menu and returns focus to the previously focused
+element; `ArrowUp` / `ArrowDown` cycle focus through the items.
+-->
 <script lang="ts">
 	import { ContextMenuContext } from '../../Contexts/ContextMenuContext.svelte.js';
 	import { devCatch } from '../../Helpers/Helpers.svelte.js';
 	import { getContext, tick, untrack } from 'svelte';
 	import { fade } from 'svelte/transition';
+	import { usePrefersReducedMotion } from '../../Helpers/prefersReducedMotion.svelte.js';
 	import ContextMenuOption from './ContextMenuOption.svelte';
 	import type { MaybeFocusable } from './MaybeFocusable.js';
 
 	const contextMenuContext = getContext<ContextMenuContext>(ContextMenuContext.identifier);
+	const reducedMotion = usePrefersReducedMotion();
+	const fadeDuration = $derived(reducedMotion.matches ? 0 : 50);
 
 	let _x: number = $state(0);
 	let _y: number = $state(0);
@@ -72,12 +97,11 @@
 			return;
 		}
 		const items = [...menuEl.querySelectorAll<HTMLElement>('[role="menuitem"]')];
-		const index = items.indexOf(document.activeElement as HTMLElement);
-		const found = items.at((index + 1) % items.length);
-		if (!found) {
-			console.warn(`could not find next item`);
+		if (items.length === 0) {
+			return;
 		}
-		found?.focus();
+		const index = items.indexOf(document.activeElement as HTMLElement);
+		items.at((index + 1) % items.length)?.focus();
 	}
 
 	function focusPrev() {
@@ -85,13 +109,11 @@
 			return;
 		}
 		const items = [...menuEl.querySelectorAll<HTMLElement>('[role="menuitem"]')];
-		const index = items.indexOf(document.activeElement as HTMLElement);
-
-		const found = items.at((index - 1 + items.length) % items.length);
-		if (!found) {
-			console.warn('could not find prev item');
+		if (items.length === 0) {
+			return;
 		}
-		found?.focus();
+		const index = items.indexOf(document.activeElement as HTMLElement);
+		items.at((index - 1 + items.length) % items.length)?.focus();
 	}
 </script>
 
@@ -99,11 +121,12 @@
 
 {#if contextMenuContext.showMenu}
 	<ul
-		transition:fade={{ duration: 50 }}
+		transition:fade={{ duration: fadeDuration }}
 		bind:this={menuEl}
 		style="top: {_y}px; left: {_x}px;"
 		role="menu"
 		aria-label="Context menu"
+		tabindex="-1"
 		onkeydown={(e) => {
 			if (e.key === 'Escape') {
 				e.stopImmediatePropagation();
@@ -129,7 +152,7 @@
 				{index}
 				disabled={item.disabled}
 				onclick={() => {
-					item.callback();
+					void item.callback();
 					contextMenuContext.closeMenu();
 				}}
 				text={item.text}
@@ -138,20 +161,18 @@
 	</ul>
 {/if}
 
-<style>
-	ul {
-		padding: 4px;
-		position: fixed;
-		display: grid;
-		border: 1px solid #0003;
-		box-shadow: 2px 2px 5px 0px #0002;
-		gap: 4px;
-		background: white;
-		z-index: 9999;
-		line-height: initial;
-	}
-
-	ul:focus {
-		outline: none;
-	}
-</style>
+<style>ul {
+  padding: 0.375rem;
+  position: fixed;
+  display: grid;
+  border: solid 1px #cbd4da;
+  box-shadow: 2px 2px 5px 0px rgba(0, 0, 0, 0.13);
+  gap: 0.375rem;
+  background: #ffffff;
+  z-index: 99999;
+  line-height: initial;
+}
+
+ul:focus {
+  outline: none;
+}</style>

package/dist/Components/Contexts/ContextMenu.svelte.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Visual host for `ContextMenuContext`. Renders the fixed-positioned
+ * `<ul role="menu">` near the `(x, y)` coordinates the context exposes,
+ * and clamps the position so the menu never spills off the viewport.
+ *
+ * Mounted exactly once at the app root by `ContextWrapper`; consumers do
+ * not render `ContextMenu` directly. Open a menu through the context:
+ *
+ * ```svelte
+ * <script lang="ts">
+ * import { ContextMenuContext } from '@lavalogic/scoria';
+ * import { getContext } from 'svelte';
+ *
+ * const ctx = getContext<ContextMenuContext>(ContextMenuContext.identifier);
+ * </script>
+ *
+ * <button oncontextmenu={(e) => ctx.openContextMenu(e, items)}>
+ * Right-click me
+ * </button>
+ * ```
+ *
+ * ### Keyboard
+ *
+ * `Escape` closes the menu and returns focus to the previously focused
+ * element; `ArrowUp` / `ArrowDown` cycle focus through the items.
+ */
 declare const ContextMenu: import("svelte").Component<Record<string, never>, {}, "">;
 type ContextMenu = ReturnType<typeof ContextMenu>;
 export default ContextMenu;

package/dist/Components/Contexts/ContextMenuDivider.svelte

@@ -1,11 +1,19 @@
 <svelte:options runes />
 
+<!--
+@component
+Visual separator for {@link ContextMenu}. Renders a thin horizontal
+rule. The native `<hr>` ARIA mapping is `role="separator"`, which is
+the correct semantic inside a `role="menu"` group, so no explicit
+role is set.
+
+Intended for use between groups of `ContextMenuOption` entries inside
+a context menu rendered via the visual host.
+-->
 <hr />
 
-<style>
-	hr {
-		border-top: 1px solid #0003;
-		width: 100%;
-		margin: 2px 0;
-	}
-</style>
+<style>hr {
+  border-top: solid 1px #cbd4da;
+  width: 100%;
+  margin: 2px 0;
+}</style>

package/dist/Components/Contexts/ContextMenuDivider.svelte.d.ts

@@ -3,4 +3,13 @@ type ContextMenuDivider = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<Record<string, never>>): void;
 };
+/**
+ * Visual separator for {@link ContextMenu}. Renders a thin horizontal
+ * rule. The native `<hr>` ARIA mapping is `role="separator"`, which is
+ * the correct semantic inside a `role="menu"` group, so no explicit
+ * role is set.
+ *
+ * Intended for use between groups of `ContextMenuOption` entries inside
+ * a context menu rendered via the visual host.
+ */
 declare const ContextMenuDivider: import("svelte").Component<Record<string, never>, {}, "">;

package/dist/Components/Contexts/ContextMenuOption.svelte

@@ -1,28 +1,35 @@
 <svelte:options runes />
 
+<!--
+@component
+A single row inside the {@link ContextMenu} host. Renders a
+`<button role="menuitem">` and assigns a roving `tabindex`: the
+first option (index `0`) receives focus on mount and is the only
+tab stop, all subsequent options carry `tabindex="-1"` so arrow-key
+navigation owns focus traversal within the menu.
+
+Consumers do not usually mount `ContextMenuOption` directly; the
+visual host iterates over `ContextMenuContext.items` and renders one
+option per entry.
+-->
 <script lang="ts">
 	import { devCatch } from '../../Helpers/Helpers.svelte.js';
 	import { tick } from 'svelte';
 	import type { ContextMenuOptionProps } from './ContextMenuOptionProps.js';
 
-	let {
-		text = $bindable(''),
-		index,
-		disabled = false,
-		onclick,
-		children,
-	}: ContextMenuOptionProps = $props();
+	let { text = '', index, disabled = false, onclick, children }: ContextMenuOptionProps = $props();
 
 	let element = $state<HTMLButtonElement | undefined>();
 
 	$effect(() => {
 		void element;
-		if (index == 0) {
+		// Only the first option seeds focus. The check stays inside the
+		// effect (rather than gating registration) so Svelte's reactive
+		// dependency on `index` is recorded.
+		if (index === 0) {
 			tick()
 				.then(() => {
-					if (element) {
-						element.focus();
-					}
+					element?.focus();
 				})
 				.catch(devCatch);
 		}
@@ -33,13 +40,14 @@
 	class="context-menu-item"
 	role="menuitem"
 	class:disabled
-	tabindex={index}
+	tabindex={index === 0 ? 0 : -1}
+	aria-disabled={disabled ? 'true' : undefined}
 	bind:this={element}
 	onclick={(e) => {
 		e.stopImmediatePropagation();
 		e.stopPropagation();
 		e.preventDefault();
-		onclick?.(e);
+		void onclick?.(e);
 	}}
 >
 	{#if text}
@@ -52,13 +60,14 @@
 <style>button {
   background-color: #ffffff;
   border: none;
-  padding: 4px 15px;
+  padding: 0.375rem 0.75rem;
   cursor: default;
-  font-size: 14px;
+  font-size: 0.875rem;
   display: flex;
   align-items: center;
-  grid-gap: 5px;
+  grid-gap: 0.375rem;
   user-select: none;
+  color: #3a4952;
 }
 
 button:focus,
@@ -67,11 +76,11 @@ button:focus-within {
 }
 
 button:hover {
-  background: rgba(0, 0, 0, 0.1333333333);
+  background: #e9ecf1;
 }
 
 button.disabled {
-  color: rgba(0, 0, 0, 0.4);
+  color: #8096a5;
 }
 
 button.disabled:hover {

package/dist/Components/Contexts/ContextMenuOption.svelte.d.ts

@@ -1,4 +1,15 @@
 import type { ContextMenuOptionProps } from './ContextMenuOptionProps.js';
-declare const ContextMenuOption: import("svelte").Component<ContextMenuOptionProps, {}, "text">;
+/**
+ * A single row inside the {@link ContextMenu} host. Renders a
+ * `<button role="menuitem">` and assigns a roving `tabindex`: the
+ * first option (index `0`) receives focus on mount and is the only
+ * tab stop, all subsequent options carry `tabindex="-1"` so arrow-key
+ * navigation owns focus traversal within the menu.
+ *
+ * Consumers do not usually mount `ContextMenuOption` directly; the
+ * visual host iterates over `ContextMenuContext.items` and renders one
+ * option per entry.
+ */
+declare const ContextMenuOption: import("svelte").Component<ContextMenuOptionProps, {}, "">;
 type ContextMenuOption = ReturnType<typeof ContextMenuOption>;
 export default ContextMenuOption;

package/dist/Components/Contexts/ContextMenuOptionProps.d.ts

@@ -1,8 +1,40 @@
 import type { Snippet } from 'svelte';
+/**
+ * Props for {@link ContextMenuOption}.
+ *
+ * A single item inside the {@link ContextMenu} host. The host renders
+ * one option per entry in `ContextMenuContext.items`; consumers do not
+ * usually instantiate this component directly.
+ */
 export interface ContextMenuOptionProps {
+    /**
+     * Zero-based position of this option in the parent menu. The host
+     * uses the value to assign a roving `tabindex` (`0` for the first
+     * option, `-1` for the rest) and to seed initial focus.
+     *
+     * Must be a non-negative integer.
+     */
     index: number;
+    /**
+     * Plain-text label rendered inside the option button. If both
+     * `text` and `children` are supplied, `text` wins; prefer one or
+     * the other to keep the rendered output predictable.
+     */
     text?: string;
-    disabled?: boolean | undefined;
-    onclick?: (e: MouseEvent) => void;
+    /**
+     * When `true` the option is rendered greyed-out and ignores
+     * `onclick`. Hover styles are also suppressed.
+     */
+    disabled?: boolean;
+    /**
+     * Click handler. Receives the underlying `MouseEvent`. The handler
+     * may return a `Promise` because the menu host awaits the close
+     * sequence after invoking it.
+     */
+    onclick?: (e: MouseEvent) => void | Promise<void>;
+    /**
+     * Snippet alternative to `text` for richer content (icons, key
+     * hints). Ignored when `text` is set.
+     */
     children?: Snippet;
 }

package/dist/Components/Contexts/Toast.svelte

@@ -1,5 +1,20 @@
 <svelte:options runes />
 
+<!--
+@component
+Single toast rendering. Renders a horizontally-sliding pill near the
+bottom-right of the viewport via `ToastContainer`. The severity of the
+underlying toast drives both the colouring and the live-region
+semantics:
+
+- `Validity.Invalid` -> `role="alert"`, `aria-live="assertive"`.
+- All other severities -> `role="status"`, `aria-live="polite"`.
+
+The slide transition honours `prefers-reduced-motion` through the
+shared `usePrefersReducedMotion` helper; when the user has opted in
+the duration collapses to zero. The copy action is only shown when
+`navigator.clipboard` is present (HTTPS or `localhost`).
+-->
 <script
 	lang="ts"
 	module
@@ -14,7 +29,12 @@
 </script>
 
 <script lang="ts">
+	import { usePrefersReducedMotion } from '../../Helpers/prefersReducedMotion.svelte.js';
+
 	let { toast, copy }: ToastProps = $props();
+
+	const reducedMotion = usePrefersReducedMotion();
+	const slideDuration = $derived(reducedMotion.matches ? 0 : 500);
 </script>
 
 <output
@@ -24,7 +44,7 @@
 	class:success={toast.result == Validity.Valid}
 	class:warning={toast.result == Validity.Warning}
 	class:error={toast.result == Validity.Invalid}
-	transition:slide={{ axis: 'x', duration: 500 }}
+	transition:slide={{ axis: 'x', duration: slideDuration }}
 >
 	<div>
 		<div class="noshrink">
@@ -32,6 +52,7 @@
 				<Action
 					onclick={copy}
 					icon={{ name: 'copy' }}
+					label="Copy to clipboard"
 					size={Size.MediumLarge}
 					colourSet={ColourSet.Auxiliary}
 				/>
@@ -48,6 +69,7 @@
 				<Action
 					size={Size.MediumLarge}
 					icon={{ name: 'cross' }}
+					label="Dismiss"
 					onclick={() => {
 						toast.close?.();
 					}}
@@ -63,6 +85,7 @@
   font-size: 1.125rem;
   padding: 0.75rem;
   border-radius: 4px;
+  max-width: var(--toast-max-width, 32rem);
 }
 output.info, output.success {
   color: #ffffff;
@@ -86,7 +109,8 @@ output > div {
   align-items: center;
 }
 output span {
-  text-wrap: nowrap;
-  word-break: keep-all;
-  overflow: hidden;
+  word-break: break-word;
+  overflow-wrap: anywhere;
+  min-width: 0;
+  flex: 1 1 auto;
 }</style>

package/dist/Components/Contexts/Toast.svelte.d.ts

@@ -1,4 +1,18 @@
 import type { ToastProps } from './ToastProps.js';
+/**
+ * Single toast rendering. Renders a horizontally-sliding pill near the
+ * bottom-right of the viewport via `ToastContainer`. The severity of the
+ * underlying toast drives both the colouring and the live-region
+ * semantics:
+ *
+ * - `Validity.Invalid` -> `role="alert"`, `aria-live="assertive"`.
+ * - All other severities -> `role="status"`, `aria-live="polite"`.
+ *
+ * The slide transition honours `prefers-reduced-motion` through the
+ * shared `usePrefersReducedMotion` helper; when the user has opted in
+ * the duration collapses to zero. The copy action is only shown when
+ * `navigator.clipboard` is present (HTTPS or `localhost`).
+ */
 declare const Toast: import("svelte").Component<ToastProps, {}, "">;
 type Toast = ReturnType<typeof Toast>;
 export default Toast;

package/dist/Components/Contexts/ToastContainer.svelte

@@ -1,5 +1,20 @@
 <svelte:options runes />
 
+<!--
+@component
+Live region for the {@link ToastContext}. Iterates the context's
+queue and renders one `Toast` per message, providing the
+copy-to-clipboard callback (the container owns the clipboard logic
+because the toast itself only knows the message it should copy).
+
+The wrapping `<section>` carries `role="region"` plus
+`aria-live="polite"` so multiple toast appearances are announced as
+a single rolling region without interrupting the user; individual
+`Toast` elements override `aria-live` to `assertive` for hard errors.
+
+Mounted once at the app root by `ContextWrapper`; consumers should
+not render this directly.
+-->
 <script lang="ts">
 	import { ToastContext } from '../../Contexts/ToastContext.svelte.js';
 	import { devCatch } from '../../Helpers/Helpers.svelte.js';
@@ -9,31 +24,35 @@
 
 	const toastContext = getContext<ToastContext>(ToastContext.identifier);
 
-	function copyDataToClipboard(text: string) {
-		//clipboard doesn't exist in http connections. This may be redundant now but you never know
+	function copyDataToClipboard(text: string): void {
+		// `navigator.clipboard` is `undefined` on insecure (HTTP)
+		// origins and in some embedded WebViews. The compile-time
+		// type says it is always defined, hence the eslint disable;
+		// the runtime check is the load-bearing one.
 		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 		if (!navigator.clipboard) {
 			toastContext.toast({
 				result: Validity.Invalid,
 				message: 'Cannot Copy in an Insecure Connection',
-				copyable: false
+				copyable: false,
 			});
 			return;
 		}
 
-		// copy plain value
-
 		navigator.clipboard.writeText(text).catch(devCatch);
 		toastContext.toast({
 			result: Validity.Info,
 			message: 'Message copied to clipboard',
-			copyable: false
+			copyable: false,
 		});
 	}
 </script>
 
-<section>
-	{#each toastContext.toasts as toast (toast)}
+<section
+	aria-live="polite"
+	aria-label="Notifications"
+>
+	{#each toastContext.toasts as toast (toast.id)}
 		<Toast
 			{toast}
 			copy={() => {
@@ -46,12 +65,12 @@
 <style>section {
   user-select: none;
   gap: 0.5rem;
-  bottom: 8rem;
-  right: 2rem;
+  bottom: var(--toast-bottom, 8rem);
+  right: var(--toast-right, 2rem);
   display: flex;
   position: fixed;
   flex-flow: column-reverse nowrap;
   justify-content: flex-end;
   align-items: flex-end;
-  z-index: 9999;
+  z-index: 99999;
 }</style>

package/dist/Components/Contexts/ToastContainer.svelte.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Live region for the {@link ToastContext}. Iterates the context's
+ * queue and renders one `Toast` per message, providing the
+ * copy-to-clipboard callback (the container owns the clipboard logic
+ * because the toast itself only knows the message it should copy).
+ *
+ * The wrapping `<section>` carries `role="region"` plus
+ * `aria-live="polite"` so multiple toast appearances are announced as
+ * a single rolling region without interrupting the user; individual
+ * `Toast` elements override `aria-live` to `assertive` for hard errors.
+ *
+ * Mounted once at the app root by `ContextWrapper`; consumers should
+ * not render this directly.
+ */
 declare const ToastContainer: import("svelte").Component<Record<string, never>, {}, "">;
 type ToastContainer = ReturnType<typeof ToastContainer>;
 export default ToastContainer;

package/dist/Components/Contexts/ToastProps.d.ts

@@ -1,5 +1,18 @@
 import type { IdentifiableToastMessage } from '../../Types/Internal/IdentifiableToastMessage.js';
+/**
+ * Props for {@link Toast}.
+ *
+ * `Toast` is the per-message renderer used by `ToastContainer`. The
+ * container provides the `copy` callback because copy-to-clipboard is
+ * a host-level concern (the host knows which message text or verbose
+ * representation to write).
+ */
 export interface ToastProps {
+    /** The toast message and metadata to render. */
     toast: IdentifiableToastMessage;
-    copy: () => void;
+    /**
+     * Click handler for the copy action. Allowed to return a promise
+     * so callers can await the underlying `navigator.clipboard.writeText`.
+     */
+    copy: () => void | Promise<void>;
 }

package/dist/Components/Contexts/Tooltip.svelte

@@ -1,5 +1,16 @@
 <svelte:options runes />
 
+<!--
+@component
+Visual host for `TooltipContext`. Renders a fixed-position tooltip at
+the coordinates the context exposes, with a CSS arrow that points
+back toward the anchored element on the configured side.
+
+The tooltip just appears and disappears; no transition is applied,
+which is the conservative choice for `prefers-reduced-motion`. Reads
+the context with `getContext` and relies on `ContextWrapper` to have
+set it up at the app root.
+-->
 <script lang="ts">
 	import { TooltipContext } from '../../Contexts/TooltipContext.svelte.js';
 	import { Side } from '../../Types/Internal/Side.js';
@@ -25,19 +36,19 @@
 
 <style>.tooltip-wrapper {
   position: fixed;
-  z-index: 9999;
+  z-index: 99999;
   border-radius: 4px;
-  background-color: black;
-  color: white;
-  box-shadow: 0px 0px 5px rgba(0, 0, 0, 0.1333333333);
+  background-color: #3a4952;
+  color: #ffffff;
+  box-shadow: 0px 0px 5px rgba(0, 0, 0, 0.13);
   border: solid 2px #dae0e5;
 }
 .tooltip-wrapper .tooltip {
   padding: 0.5rem;
-  background-color: black;
+  background-color: #3a4952;
   border-radius: 4px;
   font-weight: 500;
-  white-space: preserve;
+  white-space: pre-wrap;
 }
 .tooltip-wrapper.top-arrow {
   left: var(--x, 0);
@@ -54,7 +65,7 @@
   left: 50%;
   translate: -50% -50%;
   transform: rotate(45deg);
-  background-color: black;
+  background-color: #3a4952;
   border: solid 2px #dae0e5;
 }
 .tooltip-wrapper.bottom-arrow {
@@ -72,7 +83,7 @@
   left: 50%;
   translate: -50% -50%;
   transform: rotate(45deg);
-  background-color: black;
+  background-color: #3a4952;
   border: solid 2px #dae0e5;
 }
 .tooltip-wrapper.left-arrow {
@@ -90,7 +101,7 @@
   left: 0;
   translate: -50% -50%;
   transform: rotate(45deg);
-  background-color: black;
+  background-color: #3a4952;
   border: solid 2px #dae0e5;
 }
 .tooltip-wrapper.right-arrow {
@@ -108,6 +119,6 @@
   left: 100%;
   translate: -50% -50%;
   transform: rotate(45deg);
-  background-color: black;
+  background-color: #3a4952;
   border: solid 2px #dae0e5;
 }</style>

package/dist/Components/Contexts/Tooltip.svelte.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Visual host for `TooltipContext`. Renders a fixed-position tooltip at
+ * the coordinates the context exposes, with a CSS arrow that points
+ * back toward the anchored element on the configured side.
+ *
+ * The tooltip just appears and disappears; no transition is applied,
+ * which is the conservative choice for `prefers-reduced-motion`. Reads
+ * the context with `getContext` and relies on `ContextWrapper` to have
+ * set it up at the app root.
+ */
 declare const Tooltip: import("svelte").Component<Record<string, never>, {}, "">;
 type Tooltip = ReturnType<typeof Tooltip>;
 export default Tooltip;