@fuzdev/fuz_ui 0.201.0 → 0.203.0

package/src/lib/contextmenu_state.svelte.ts

@@ -1,7 +1,7 @@
 import {onDestroy, type Snippet} from 'svelte';
 import type {Result} from '@fuzdev/fuz_util/result.js';
 import {is_promise} from '@fuzdev/fuz_util/async.js';
-import {BROWSER} from 'esm-env';
+import {BROWSER, DEV} from 'esm-env';
 import type {SvelteHTMLElements} from 'svelte/elements';
 import {EMPTY_OBJECT} from '@fuzdev/fuz_util/object.js';
 import type {Attachment} from 'svelte/attachments';
@@ -9,6 +9,8 @@ import type {Attachment} from 'svelte/attachments';
 import {Dimensions} from './dimensions.svelte.js';
 import {create_context} from './context_helpers.js';
 import {url_to_root_relative} from './library_helpers.js';
+import {icon_copy} from './icons.js';
+import type {SvgData} from './svg.js';
 
 export const contextmenu_context = create_context<() => ContextmenuState>();
 
@@ -20,7 +22,7 @@ export type ContextmenuParams =
 	| Snippet
 	// TODO maybe this should be generic?
 	| {snippet: 'link'; props: {href: string; icon?: string}}
-	| {snippet: 'text'; props: {content: string; icon: string; run: ContextmenuRun}}
+	| {snippet: 'text'; props: {content: string; icon: SvgData | string; run: ContextmenuRun}}
 	| {snippet: 'separator'; props: SvelteHTMLElements['li']};
 
 export type ContextmenuActivateResult =
@@ -53,36 +55,85 @@ export class EntryState {
 	}
 }
 
-export class SubmenuState {
+/**
+ * Shared `items` state for `SubmenuState` and `RootMenuState`.
+ *
+ * The source of truth is a plain non-reactive array because items register and
+ * unregister from component lifecycles that can interleave within a single batch -
+ * effect teardowns can observe stale signal values mid-batch, so read-copy-write
+ * against the reactive array can lose concurrent registrations (e.g. reopening the
+ * menu while it's open). Every mutation publishes an immutable snapshot, preserving
+ * the reassignment (not mutation) contract for readers.
+ */
+export class ContextmenuItemsState {
+	#items_source: Array<ItemState> = [];
+	#items: ReadonlyArray<ItemState> = $state.raw([]);
+
+	get items(): ReadonlyArray<ItemState> {
+		return this.#items;
+	}
+
+	set items(value: ReadonlyArray<ItemState>) {
+		// copy for the published snapshot too, so callers mutating
+		// their own array can't mutate it in readers' hands
+		this.#items_source = [...value];
+		this.#items = [...value];
+	}
+
+	/**
+	 * Appends `item`, publishing a new immutable `items`.
+	 */
+	add_item(item: ItemState): void {
+		this.#items_source.push(item);
+		this.#items = [...this.#items_source];
+	}
+
+	/**
+	 * Removes `item` if present, publishing a new immutable `items`.
+	 * Safe to call from effect teardown - it reads only the non-reactive source array.
+	 */
+	remove_item(item: ItemState): void {
+		const index = this.#items_source.indexOf(item);
+		if (index === -1) return;
+		this.#items_source.splice(index, 1);
+		this.#items = [...this.#items_source];
+	}
+}
+
+export class SubmenuState extends ContextmenuItemsState {
 	readonly is_menu = true;
 	readonly menu: SubmenuState | RootMenuState;
 	readonly depth: number;
 
 	selected: boolean = $state.raw(false);
-	items: ReadonlyArray<ItemState> = $state.raw([]);
 
 	constructor(menu: SubmenuState | RootMenuState, depth: number) {
+		super();
 		this.menu = menu;
 		this.depth = depth;
 	}
 }
 
-export class RootMenuState {
+export class RootMenuState extends ContextmenuItemsState {
 	readonly is_menu = true;
 	readonly menu = null;
 	readonly depth = 1;
-
-	items: ReadonlyArray<ItemState> = $state.raw([]);
 }
 
 export type ContextmenuRun = () => ContextmenuActivateResult | Promise<ContextmenuActivateResult>;
 
+/** Extracts a string `message` property from a thrown value or failed result, if present. */
+const to_error_message = (value: unknown): string | undefined => {
+	const message = (value as {message?: unknown} | null | undefined)?.message;
+	return typeof message === 'string' ? message : undefined;
+};
+
 export interface ContextmenuStateOptions {
 	layout?: Dimensions; // TODO consider making this a prop on `ContextmenuRoot`, and being assigned here
 }
 
 /**
- * Creates a contextmenu store.
+ * Manages contextmenu state.
  * See usage with `ContextmenuRoot.svelte` and `Contextmenu.svelte`.
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/contextmenu_event}
@@ -102,10 +153,16 @@ export class ContextmenuState {
 	params: ReadonlyArray<ContextmenuParams> = $state.raw([]);
 	error: string | undefined = $state.raw();
 
-	// These arrays use immutable updates (reassignment, not mutation).
-	// If you need reactivity, use `$contextmenu` in a reactive statement to react to all changes, and
-	// then access the immutable `contextmenu.root_menu` and `contextmenu.selections`.
-	// See `ContextmenuEntry.svelte` and `ContextmenuSubmenu.svelte` for reactive usage examples.
+	/**
+	 * The element the menu was opened from, while opened, else `undefined`.
+	 * Resolves the popover host when the menu opens inside a modal `<dialog>` -
+	 * see `contextmenu_resolve_popover_host`. Deliberately not reactive -
+	 * read it in event handlers and attachments, not in templates.
+	 */
+	target: HTMLElement | SVGElement | undefined = undefined;
+
+	// These arrays use immutable updates (reassignment, not mutation) - readers can depend
+	// on snapshot identity, and `ContextmenuItemsState` documents the publication contract.
 	readonly root_menu: RootMenuState = new RootMenuState();
 	selections: ReadonlyArray<ItemState> = $state.raw([]);
 
@@ -116,12 +173,11 @@ export class ContextmenuState {
 		return !!selected?.is_menu && selected.items.length > 0;
 	});
 
-	can_select_next = $derived.by(() => {
-		const menu = this.selections.at(-1)?.menu ?? this.root_menu;
-		return menu.items.length > 1;
-	});
-
-	can_select_previous = $derived.by(() => {
+	/**
+	 * Whether `select_next` and `select_previous` can move the selection -
+	 * the selected menu has more than one item.
+	 */
+	can_select_sibling = $derived.by(() => {
 		const menu = this.selections.at(-1)?.menu ?? this.root_menu;
 		return menu.items.length > 1;
 	});
@@ -129,6 +185,9 @@ export class ContextmenuState {
 	can_activate = $derived.by(() => {
 		const selected = this.selections.at(-1);
 		if (!selected) return false;
+		// the selected item can unregister out from under the selection
+		// (e.g. its component unmounted) - its action must not run
+		if (!selected.menu.items.includes(selected)) return false;
 		if (selected.is_menu) return selected.items.length > 0;
 		return !selected.disabled();
 	});
@@ -140,18 +199,38 @@ export class ContextmenuState {
 		this.layout = layout ?? new Dimensions();
 	}
 
-	open(params: Array<ContextmenuParams>, x: number, y: number): void {
-		this.selections = [];
+	open(
+		params: Array<ContextmenuParams>,
+		x: number,
+		y: number,
+		target?: HTMLElement | SVGElement,
+	): void {
+		this.#clear_selections();
 		this.opened = true;
+		this.error = undefined;
 		this.x = x;
 		this.y = y;
 		this.params = params;
+		this.target = target;
 	}
 
 	close(): void {
 		if (!this.opened) return;
 		this.reset_items(this.root_menu.items);
+		this.#clear_selections();
 		this.opened = false;
+		this.target = undefined;
+	}
+
+	/**
+	 * Deselects every selected item and empties `selections`. Items can outlive
+	 * a selection (e.g. surviving a reopen-while-open), so clearing the array
+	 * without deselecting would leave ghost highlights.
+	 */
+	#clear_selections(): void {
+		if (!this.selections.length) return;
+		for (const s of this.selections) s.selected = false;
+		this.selections = [];
 	}
 
 	reset_items(items: ReadonlyArray<ItemState>): void {
@@ -166,78 +245,94 @@ export class ContextmenuState {
 		}
 	}
 
-	activate(item: ItemState): boolean | Promise<ContextmenuActivateResult> {
-		if (item.is_menu) {
-			this.expand_selected();
-		} else {
-			if (item.disabled()) return false;
-			let returned;
-			try {
-				returned = item.run()();
-			} catch (error) {
-				const message = typeof error?.message === 'string' ? error.message : undefined;
-				item.error_message = message ?? 'unknown error';
-				this.error = message;
-			}
-			if (is_promise(returned)) {
-				item.pending = true;
-				item.error_message = null;
-				const promise = (item.promise = returned
-					.then(
-						(result) => {
-							if (promise !== item.promise) return;
-							if (typeof result?.ok === 'boolean') {
-								if (result.ok) {
-									if (result.close !== false) {
-										this.close();
-									}
-								} else {
-									const message = typeof result.message === 'string' ? result.message : undefined;
-									item.error_message = message ?? 'unknown error';
-									this.error = message;
-								}
-							} else {
-								// void or undefined - default behavior is to close
-								this.close();
-							}
-							return result;
-						},
-						(err) => {
-							if (promise !== item.promise) return;
-							const message = typeof err?.message === 'string' ? err.message : undefined;
-							item.error_message = message ?? 'unknown error';
-							this.error = message;
-						},
-					)
-					.finally(() => {
-						if (promise !== item.promise) return;
-						item.pending = false;
-						item.promise = null;
-					}));
-				return item.promise; // async path
-			}
-			// synchronous path
-			if (typeof returned?.ok === 'boolean') {
-				if (returned.ok) {
-					if (returned.close !== false) {
-						this.close();
-					}
-				} else {
-					const message = typeof returned.message === 'string' ? returned.message : undefined;
-					item.error_message = message ?? 'unknown error';
-					this.error = message;
+	/**
+	 * Sets the error state for a failed activation.
+	 * `error_message` falls back to `'unknown error'` so the entry always displays something,
+	 * while `error` keeps the raw message so external consumers can detect its absence.
+	 */
+	#handle_error(item: EntryState, message: string | undefined): void {
+		item.error_message = message ?? 'unknown error';
+		this.error = message;
+	}
+
+	/**
+	 * Applies an activation result, returning `false` when it failed.
+	 */
+	#handle_result(item: EntryState, result: ContextmenuActivateResult): boolean {
+		if (typeof result?.ok === 'boolean') {
+			if (result.ok) {
+				if (result.close !== false) {
+					this.close();
 				}
 			} else {
-				// void or undefined - default behavior is to close
-				this.close();
+				this.#handle_error(item, to_error_message(result));
+				return false;
 			}
+		} else {
+			// void or undefined - default behavior is to close
+			this.close();
 		}
 		return true;
 	}
 
+	/**
+	 * Activates `item` - expanding submenus, running entries.
+	 *
+	 * @returns for async runs, the activation promise; for sync runs, `false` when the
+	 * activation didn't run (disabled) or failed (a throw or `{ok: false}`), else `true`
+	 */
+	activate(item: ItemState): boolean | Promise<ContextmenuActivateResult> {
+		if (item.is_menu) {
+			// select before expanding - `expand_selected` operates on the selection
+			// tail, and callers aren't required to have selected (hovered) `item` first
+			this.select(item);
+			this.expand_selected();
+			return true;
+		}
+		if (item.disabled()) return false;
+		let returned;
+		try {
+			returned = item.run()();
+		} catch (error) {
+			// keep the menu open so the entry displays the error, matching the async failure path
+			this.#handle_error(item, to_error_message(error));
+			return false;
+		}
+		if (is_promise(returned)) {
+			item.pending = true;
+			item.error_message = null;
+			const promise = (item.promise = returned
+				.then(
+					(result) => {
+						if (promise !== item.promise) return;
+						this.#handle_result(item, result);
+						return result;
+					},
+					(err) => {
+						if (promise !== item.promise) return;
+						this.#handle_error(item, to_error_message(err));
+					},
+				)
+				.finally(() => {
+					if (promise !== item.promise) return;
+					item.pending = false;
+					item.promise = null;
+				}));
+			return item.promise; // async path
+		}
+		// synchronous path
+		return this.#handle_result(item, returned);
+	}
+
+	/**
+	 * Activates the selected item, or if none is selected, selects the first.
+	 * Returns `false` without activating when the selected item has unregistered
+	 * out from under the selection (e.g. its component unmounted).
+	 */
 	activate_selected(): void | boolean | Promise<ContextmenuActivateResult> {
 		const selected = this.selections.at(-1);
 		if (selected) {
+			if (!selected.menu.items.includes(selected)) return false;
 			return this.activate(selected);
 		}
 		this.select_first();
@@ -248,7 +343,7 @@ export class ContextmenuState {
 	// Could be improved but it's fine because we're using mutation and the N is very small,
 	// and it allows us to have a single code path for the various selection methods.
 	/**
-	 * Activates the selected entry, or if none, selects the first.
+	 * Selects `item` and its ancestor menus, deselecting everything else.
 	 */
 	// TODO implement focus management per APG: call .focus() on the selected item's DOM element (requires storing element refs in EntryState/SubmenuState)
 	select(item: ItemState): void {
@@ -286,6 +381,11 @@ export class ContextmenuState {
 		}
 		const item = this.selections.at(-1)!;
 		const index = item.menu.items.indexOf(item);
+		if (index === -1) {
+			// the selected item unregistered out from under the selection - restart
+			this.select_first();
+			return;
+		}
 		this.select(item.menu.items[index === item.menu.items.length - 1 ? 0 : index + 1]!);
 	}
 
@@ -296,6 +396,11 @@ export class ContextmenuState {
 		}
 		const item = this.selections.at(-1)!;
 		const index = item.menu.items.indexOf(item);
+		if (index === -1) {
+			// the selected item unregistered out from under the selection - restart
+			this.select_last();
+			return;
+		}
 		this.select(item.menu.items[index === 0 ? item.menu.items.length - 1 : index - 1]!);
 	}
 
@@ -318,10 +423,9 @@ export class ContextmenuState {
 	add_entry(run: () => ContextmenuRun, disabled: () => boolean = () => false): EntryState {
 		const menu = contextmenu_submenu_context.get_maybe() ?? this.root_menu;
 		const entry = new EntryState(menu, run, disabled);
-		menu.items = [...menu.items, entry];
-		// TODO messy, runs more than needed
+		menu.add_item(entry);
 		onDestroy(() => {
-			menu.items = [];
+			menu.remove_item(entry);
 		});
 		return entry;
 	}
@@ -332,46 +436,43 @@ export class ContextmenuState {
 	add_submenu(): SubmenuState {
 		const menu = contextmenu_submenu_context.get_maybe() ?? this.root_menu;
 		const submenu = new SubmenuState(menu, menu.depth + 1);
-		menu.items = [...menu.items, submenu];
+		menu.add_item(submenu);
 		contextmenu_submenu_context.set(submenu);
-		// TODO messy, runs more than needed
 		onDestroy(() => {
-			menu.items = [];
+			menu.remove_item(submenu);
 		});
 		return submenu;
 	}
 }
 
+// The dataset attribute is only a crawl marker for `contextmenu_query_params` -
+// the params themselves live in `contextmenu_params_by_element`, keyed by element.
 // The dataset key must not have capital letters or dashes or it'll differ between JS and DOM:
 // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset
 const CONTEXTMENU_DATASET_KEY = 'contextmenu';
 const CONTEXTMENU_DOM_QUERY = `a,[data-${CONTEXTMENU_DATASET_KEY}]`;
-const contextmenu_cache: Map<string, ContextmenuParams | Array<ContextmenuParams>> = new Map();
-let cache_key_counter = 0;
+const contextmenu_params_by_element: WeakMap<
+	Element,
+	ContextmenuParams | Array<ContextmenuParams>
+> = new WeakMap();
 
 /**
  * Creates an attachment that sets up contextmenu behavior on an element.
  * @param params - contextmenu parameters or nullish to disable
  */
 export const contextmenu_attachment =
-	<T extends ContextmenuParams, U extends T | Array<T>>(
-		params: U | null | undefined,
+	(
+		params: ContextmenuParams | Array<ContextmenuParams> | null | undefined,
 	): Attachment<HTMLElement | SVGElement> =>
 	(el): undefined | (() => void) => {
-		// TODO could clean up the dataset attr, maybe use a weakmap?
 		if (params == null) return;
 
-		// Only create key once per element, reuse on updates
-		let key = el.dataset[CONTEXTMENU_DATASET_KEY];
-		if (!key) {
-			key = cache_key_counter++ + '';
-			el.dataset[CONTEXTMENU_DATASET_KEY] = key;
-		}
-
-		contextmenu_cache.set(key, params);
+		el.dataset[CONTEXTMENU_DATASET_KEY] = '';
+		contextmenu_params_by_element.set(el, params);
 
 		return () => {
-			contextmenu_cache.delete(key);
+			contextmenu_params_by_element.delete(el);
+			delete el.dataset[CONTEXTMENU_DATASET_KEY]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
 		};
 	};
 
@@ -388,9 +489,9 @@ export interface ContextmenuOpenOptions {
  * Opens the contextmenu, if appropriate,
  * querying the menu items from the DOM starting at the event target.
  * @param target - the leaf element from which to open the contextmenu
- * @param x - the page X coordinate at which to open the contextmenu, typically the mouse `pageX`
- * @param y - the page Y coordinate at which to open the contextmenu, typically the mouse `pageY`
- * @param contextmenu - the contextmenu store
+ * @param x - the client (viewport) X coordinate at which to open the contextmenu, typically the mouse `clientX` - the menu positions with `fixed`
+ * @param y - the client (viewport) Y coordinate at which to open the contextmenu, typically the mouse `clientY` - the menu positions with `fixed`
+ * @param contextmenu - the contextmenu state
  * @param options - optional configuration for filtering entries and haptic feedback
  * @returns a boolean indicating if the menu was opened or not
  */
@@ -419,7 +520,7 @@ export const contextmenu_open = (
 	// No-op if empty
 	if (!params?.length) return false;
 
-	contextmenu.open(params, x, y);
+	contextmenu.open(params, x, y, target);
 
 	// `navigator.vibrate()` works with `ContextmenuRoot` but gets blocked by some browsers
 	// when used with `ContextmenuRootForSafariCompatibility` because its longpress
@@ -438,19 +539,16 @@ const contextmenu_query_params = (
 	let params: null | Array<ContextmenuParams> = null;
 	// crawl DOM for contextmenu entries
 	let el: HTMLElement | SVGElement | null | undefined = target;
-	let cache_key: string, cached: ContextmenuParams | Array<ContextmenuParams> | undefined;
 	while ((el = el?.closest(CONTEXTMENU_DOM_QUERY))) {
-		if ((cache_key = el.dataset[CONTEXTMENU_DATASET_KEY]!)) {
-			params ??= [];
-			cached = contextmenu_cache.get(cache_key);
-			if (cached === undefined) {
-				continue;
-			}
+		// Params may be missing when the element matched as a bare `<a>`, or when a
+		// stale marker was left behind - treat the element as having no registered entries.
+		const registered = contextmenu_params_by_element.get(el);
+		if (registered !== undefined) {
 			// preserve bubbling order
-			if (Array.isArray(cached)) {
-				(params ??= []).push(...cached);
+			if (Array.isArray(registered)) {
+				(params ??= []).push(...registered);
 			} else {
-				(params ??= []).push(cached);
+				(params ??= []).push(registered);
 			}
 		}
 		if (el.tagName === 'A') {
@@ -470,7 +568,7 @@ const contextmenu_query_params = (
 				snippet: 'text',
 				props: {
 					content: 'copy text',
-					icon: '📋',
+					icon: icon_copy,
 					run: async () => {
 						await navigator.clipboard.writeText(text);
 					},
@@ -486,11 +584,13 @@ const non_scoped_roots: Set<symbol> = new Set();
 
 /**
  * Registers a contextmenu root and warns if multiple non-scoped roots are detected.
- * Only active in development mode. Automatically handles cleanup on unmount.
+ * Only active in development mode - `DEV` is a build-time constant, so production
+ * bundles eliminate the check. Automatically handles cleanup on unmount.
  *
  * @param get_scoped - getter function that returns the current scoped value
  */
 export const contextmenu_check_global_root = (get_scoped: () => boolean): void => {
+	if (!DEV) return;
 	$effect(() => {
 		const id = Symbol('contextmenu_root');
 

package/src/lib/declaration.svelte.ts

@@ -145,8 +145,9 @@ export class Declaration {
 	/**
 	 * Other modules that also export this declaration (re-export paths
 	 * relative to src/lib). Absent when only exported from its defining module.
+	 * The back-link of those modules' `Module.re_exports` edges.
 	 */
-	also_exported_from = $derived(field<Array<string>>(this.declaration_json, 'alsoExportedFrom'));
+	also_exported_from = $derived(this.declaration_json.alsoExportedFrom);
 
 	/**
 	 * Mutation documentation from `@mutates` tags, mapping parameter names to descriptions.