@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/Contexts/ContextMenu.svelte

@@ -1,157 +1,178 @@
-<svelte:options runes />
-
-<!-- 
-@component
-
-
- -->
-<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 ContextMenuOption from './ContextMenuOption.svelte';
-	import type { MaybeFocusable } from './MaybeFocusable.js';
-
-	const contextMenuContext = getContext<ContextMenuContext>(ContextMenuContext.identifier);
-
-	let _x: number = $state(0);
-	let _y: number = $state(0);
-
-	$effect(() => {
-		if (contextMenuContext.showMenu) {
-			recalculateCoordinates();
-		}
-	});
-
-	function recalculateCoordinates() {
-		_x = contextMenuContext.x;
-		_y = contextMenuContext.y;
-
-		tick()
-			.then(() => {
-				const rect = menuEl?.getBoundingClientRect();
-				if (!rect) {
-					return;
-				}
-				_x = Math.min(window.innerWidth - rect.width, _x);
-				if (_y > window.innerHeight - rect.height) {
-					_y -= rect.height;
-				}
-			})
-			.catch(devCatch);
-	}
-
-	let menuEl = $state<HTMLUListElement | undefined>();
-	function closeOnClickOutside(e: MouseEvent) {
-		if (!menuEl) {
-			return;
-		}
-		if (e.target === menuEl || menuEl.contains(e.target as Node)) {
-			return;
-		}
-		contextMenuContext.closeMenu();
-	}
-
-	let previousElement = $state<MaybeFocusable | null | undefined>();
-
-	$effect.pre(() => {
-		if (contextMenuContext.showMenu) {
-			untrack(() => {
-				previousElement = document.activeElement as MaybeFocusable;
-			});
-		}
-	});
-
-	function refocusPrevious() {
-		previousElement?.focus?.();
-	}
-
-	function focusNext() {
-		if (!menuEl) {
-			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`);
-		}
-		found?.focus();
-	}
-
-	function focusPrev() {
-		if (!menuEl) {
-			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');
-		}
-		found?.focus();
-	}
-</script>
-
-<svelte:body onclick={closeOnClickOutside} />
-
-{#if contextMenuContext.showMenu}
-	<ul
-		transition:fade={{ duration: 50 }}
-		bind:this={menuEl}
-		style="top: {_y}px; left: {_x}px;"
-		role="menu"
-		aria-label="Context menu"
-		onkeydown={(e) => {
-			if (e.key === 'Escape') {
-				e.stopImmediatePropagation();
-				e.stopPropagation();
-				e.preventDefault();
-				contextMenuContext.closeMenu();
-				refocusPrevious();
-			} else if (e.key == 'ArrowUp') {
-				e.stopImmediatePropagation();
-				e.stopPropagation();
-				e.preventDefault();
-				focusPrev();
-			} else if (e.key == 'ArrowDown') {
-				e.stopImmediatePropagation();
-				e.stopPropagation();
-				e.preventDefault();
-				focusNext();
-			}
-		}}
-	>
-		{#each contextMenuContext.items as item, index (item)}
-			<ContextMenuOption
-				{index}
-				disabled={item.disabled}
-				onclick={() => {
-					item.callback();
-					contextMenuContext.closeMenu();
-				}}
-				text={item.text}
-			/>
-		{/each}
-	</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>
+<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);
+
+	$effect(() => {
+		if (contextMenuContext.showMenu) {
+			recalculateCoordinates();
+		}
+	});
+
+	function recalculateCoordinates() {
+		_x = contextMenuContext.x;
+		_y = contextMenuContext.y;
+
+		tick()
+			.then(() => {
+				const rect = menuEl?.getBoundingClientRect();
+				if (!rect) {
+					return;
+				}
+				_x = Math.min(window.innerWidth - rect.width, _x);
+				if (_y > window.innerHeight - rect.height) {
+					_y -= rect.height;
+				}
+			})
+			.catch(devCatch);
+	}
+
+	let menuEl = $state<HTMLUListElement | undefined>();
+	function closeOnClickOutside(e: MouseEvent) {
+		if (!menuEl) {
+			return;
+		}
+		if (e.target === menuEl || menuEl.contains(e.target as Node)) {
+			return;
+		}
+		contextMenuContext.closeMenu();
+	}
+
+	let previousElement = $state<MaybeFocusable | null | undefined>();
+
+	$effect.pre(() => {
+		if (contextMenuContext.showMenu) {
+			untrack(() => {
+				previousElement = document.activeElement as MaybeFocusable;
+			});
+		}
+	});
+
+	function refocusPrevious() {
+		previousElement?.focus?.();
+	}
+
+	function focusNext() {
+		if (!menuEl) {
+			return;
+		}
+		const items = [...menuEl.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+		if (items.length === 0) {
+			return;
+		}
+		const index = items.indexOf(document.activeElement as HTMLElement);
+		items.at((index + 1) % items.length)?.focus();
+	}
+
+	function focusPrev() {
+		if (!menuEl) {
+			return;
+		}
+		const items = [...menuEl.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+		if (items.length === 0) {
+			return;
+		}
+		const index = items.indexOf(document.activeElement as HTMLElement);
+		items.at((index - 1 + items.length) % items.length)?.focus();
+	}
+</script>
+
+<svelte:body onclick={closeOnClickOutside} />
+
+{#if contextMenuContext.showMenu}
+	<ul
+		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();
+				e.stopPropagation();
+				e.preventDefault();
+				contextMenuContext.closeMenu();
+				refocusPrevious();
+			} else if (e.key == 'ArrowUp') {
+				e.stopImmediatePropagation();
+				e.stopPropagation();
+				e.preventDefault();
+				focusPrev();
+			} else if (e.key == 'ArrowDown') {
+				e.stopImmediatePropagation();
+				e.stopPropagation();
+				e.preventDefault();
+				focusNext();
+			}
+		}}
+	>
+		{#each contextMenuContext.items as item, index (item)}
+			<ContextMenuOption
+				{index}
+				disabled={item.disabled}
+				onclick={() => {
+					void item.callback();
+					contextMenuContext.closeMenu();
+				}}
+				text={item.text}
+			/>
+		{/each}
+	</ul>
+{/if}
+
+<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 />
-
-<hr />
-
-<style>
-	hr {
-		border-top: 1px solid #0003;
-		width: 100%;
-		margin: 2px 0;
-	}
-</style>
+<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: 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,64 +1,73 @@
-<svelte:options runes />
-
-<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 element = $state<HTMLButtonElement | undefined>();
-
-	$effect(() => {
-		void element;
-		if (index == 0) {
-			tick()
-				.then(() => {
-					if (element) {
-						element.focus();
-					}
-				})
-				.catch(devCatch);
-		}
-	});
-</script>
-
-<button
-	class="context-menu-item"
-	role="menuitem"
-	class:disabled
-	tabindex={index}
-	bind:this={element}
-	onclick={(e) => {
-		e.stopImmediatePropagation();
-		e.stopPropagation();
-		e.preventDefault();
-		onclick?.(e);
-	}}
->
-	{#if text}
-		{text}
-	{:else if children}
-		{@render children()}
-	{/if}
-</button>
-
+<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 = '', index, disabled = false, onclick, children }: ContextMenuOptionProps = $props();
+
+	let element = $state<HTMLButtonElement | undefined>();
+
+	$effect(() => {
+		void element;
+		// 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(() => {
+					element?.focus();
+				})
+				.catch(devCatch);
+		}
+	});
+</script>
+
+<button
+	class="context-menu-item"
+	role="menuitem"
+	class:disabled
+	tabindex={index === 0 ? 0 : -1}
+	aria-disabled={disabled ? 'true' : undefined}
+	bind:this={element}
+	onclick={(e) => {
+		e.stopImmediatePropagation();
+		e.stopPropagation();
+		e.preventDefault();
+		void onclick?.(e);
+	}}
+>
+	{#if text}
+		{text}
+	{:else if children}
+		{@render children()}
+	{/if}
+</button>
+
 <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,13 +76,13 @@ 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 {
   background: #ffffff;
-}</style>
+}</style>

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