@fuzdev/fuz_ui 0.169.0

package/dist/TomeSection.svelte

@@ -0,0 +1,65 @@
+<script lang="ts" module>
+	import {create_context} from './context_helpers.js';
+
+	export type RegisterSectionHeader = (fragment: string) => string | undefined;
+	export const register_section_header_context = create_context<RegisterSectionHeader>();
+	export const section_depth_context = create_context(() => 0);
+	export const section_id_context = create_context<string | undefined>();
+</script>
+
+<script lang="ts">
+	import type {Snippet} from 'svelte';
+	import type {SvelteHTMLElements} from 'svelte/elements';
+	import {DEV} from 'esm-env';
+
+	import {intersect} from './intersect.svelte.js';
+	import {docs_links_context} from './docs_helpers.svelte.js';
+
+	const {
+		children,
+		...rest
+	}: SvelteHTMLElements['section'] & {
+		children: Snippet;
+	} = $props();
+
+	const docs_links = docs_links_context.get();
+
+	// Get parent depth and increment for children
+	const parent_depth = section_depth_context.get();
+	const current_depth = parent_depth + 1;
+	section_depth_context.set(current_depth);
+
+	// Read parent section ID before overwriting context (undefined for root sections)
+	const parent_section_id = section_id_context.get_maybe();
+
+	// Generate unique section ID immediately (before children render)
+	// Uses page-scoped counter from docs_links to ensure SSR/client consistency
+	const section_id = docs_links.generate_section_id();
+
+	// Provide own section ID to direct children (header) via context
+	section_id_context.set(section_id);
+
+	let fragment: string;
+
+	register_section_header_context.set((f) => {
+		fragment = f;
+		return parent_section_id; // Return parent section ID to header
+	});
+</script>
+
+<section
+	{...rest}
+	{@attach intersect(() => ({intersecting}) => {
+		if (!fragment) {
+			if (DEV) console.error('TomeSectionHeader must be a child of TomeSection'); // eslint-disable-line no-console
+			return;
+		}
+		if (intersecting) {
+			docs_links.fragments_onscreen.add(fragment);
+		} else {
+			docs_links.fragments_onscreen.delete(fragment);
+		}
+	})}
+>
+	{@render children()}
+</section>

package/dist/TomeSection.svelte.d.ts

@@ -0,0 +1,24 @@
+export type RegisterSectionHeader = (fragment: string) => string | undefined;
+export declare const register_section_header_context: {
+    get: (error_message?: string) => RegisterSectionHeader;
+    get_maybe: () => RegisterSectionHeader | undefined;
+    set: (value: RegisterSectionHeader) => RegisterSectionHeader;
+};
+export declare const section_depth_context: {
+    get: () => number;
+    set: (value?: number | undefined) => number;
+};
+export declare const section_id_context: {
+    get: (error_message?: string) => string | undefined;
+    get_maybe: () => string | undefined;
+    set: (value: string | undefined) => string | undefined;
+};
+import type { Snippet } from 'svelte';
+import type { SvelteHTMLElements } from 'svelte/elements';
+type $$ComponentProps = SvelteHTMLElements['section'] & {
+    children: Snippet;
+};
+declare const TomeSection: import("svelte").Component<$$ComponentProps, {}, "">;
+type TomeSection = ReturnType<typeof TomeSection>;
+export default TomeSection;
+//# sourceMappingURL=TomeSection.svelte.d.ts.map

package/dist/TomeSection.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TomeSection.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/TomeSection.svelte"],"names":[],"mappings":"AAKC,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAC7E,eAAO,MAAM,+BAA+B;;;;CAA0C,CAAC;AACvF,eAAO,MAAM,qBAAqB;;;CAA0B,CAAC;AAC7D,eAAO,MAAM,kBAAkB;;;;CAAuC,CAAC;AAGxE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAMvD,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,SAAS,CAAC,GAAG;IACxD,QAAQ,EAAE,OAAO,CAAC;CAClB,CAAC;AAyDH,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/TomeSectionHeader.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+	import {onDestroy, type Snippet} from 'svelte';
+	import type {SvelteHTMLElements} from 'svelte/elements';
+	import {page} from '$app/state';
+	import {resolve} from '$app/paths';
+
+	import Hashlink from './Hashlink.svelte';
+	import {
+		register_section_header_context,
+		section_depth_context,
+		section_id_context,
+	} from './TomeSection.svelte';
+	import {docs_links_context, docs_slugify, type DocsLinkTag} from './docs_helpers.svelte.js';
+
+	const {
+		text,
+		tag,
+		children,
+		...rest
+	}: // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
+	(SvelteHTMLElements['h2'] | SvelteHTMLElements['h3'] | SvelteHTMLElements['h4']) & {
+		text: string;
+		tag?: DocsLinkTag;
+		children?: Snippet;
+	} = $props();
+
+	const fragment = docs_slugify(text);
+
+	const register_section_header = register_section_header_context.get();
+	if (!register_section_header) {
+		throw Error('TomeSectionHeader must be a child of TomeSection');
+	}
+
+	const docs_links = docs_links_context.get();
+
+	// Auto-detect tag based on depth if not explicitly provided
+	const depth = section_depth_context.get();
+	const final_tag = tag ?? (depth === 1 ? 'h2' : depth === 2 ? 'h3' : 'h4');
+
+	// Get own section's ID from context
+	const my_section_id = section_id_context.get();
+
+	// Register with parent section to get parent's ID back
+	const parent_section_id = register_section_header(fragment);
+
+	// Register with docs_links using own section ID and parent section ID
+	let id: string | undefined;
+	if (page.url.pathname !== resolve(docs_links.root_path as any)) {
+		id = docs_links.add(
+			fragment,
+			text,
+			page.url.pathname,
+			final_tag,
+			depth,
+			parent_section_id,
+			my_section_id,
+		);
+	}
+
+	// Cleanup on unmount
+	onDestroy(() => {
+		if (id) docs_links.remove(id);
+	});
+</script>
+
+<header>
+	<svelte:element this={final_tag} {...rest} class:tome_section_header={true}>
+		<div class="flex_1">
+			{#if children}
+				{@render children()}
+			{:else}
+				{text}
+			{/if}
+		</div>
+		<Hashlink {fragment} />
+	</svelte:element>
+</header>
+
+<style>
+	.tome_section_header {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+	}
+	/* TODO @many how can this be done composably? currently using `:global` at usage site - ideally we'd continue to use :hover instead of JS */
+	.tome_section_header:hover :global(.hashlink) {
+		opacity: 1;
+	}
+</style>

package/dist/TomeSectionHeader.svelte.d.ts

@@ -0,0 +1,13 @@
+import { type Snippet } from 'svelte';
+import type { SvelteHTMLElements } from 'svelte/elements';
+import { type DocsLinkTag } from './docs_helpers.svelte.js';
+type $$ComponentProps = // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
+(SvelteHTMLElements['h2'] | SvelteHTMLElements['h3'] | SvelteHTMLElements['h4']) & {
+    text: string;
+    tag?: DocsLinkTag;
+    children?: Snippet;
+};
+declare const TomeSectionHeader: import("svelte").Component<$$ComponentProps, {}, "">;
+type TomeSectionHeader = ReturnType<typeof TomeSectionHeader>;
+export default TomeSectionHeader;
+//# sourceMappingURL=TomeSectionHeader.svelte.d.ts.map

package/dist/TomeSectionHeader.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TomeSectionHeader.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/TomeSectionHeader.svelte"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,OAAO,EAAC,MAAM,QAAQ,CAAC;AAC/C,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAUxD,OAAO,EAAmC,KAAK,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE3F,KAAK,gBAAgB,GACrB,AADyB,6EAA6E;AACtG,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AA0EH,QAAA,MAAM,iBAAiB,sDAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}

package/dist/TypeLink.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import Code from '@fuzdev/fuz_code/Code.svelte';
+
+	import DeclarationLink from './DeclarationLink.svelte';
+	import {library_context} from './library.svelte.js';
+
+	const {type}: {type: string} = $props();
+
+	const library = library_context.get();
+
+	// TODO is not extensible
+	// TODO maybe better name?
+</script>
+
+{#if library.lookup_declaration(type)}
+	<DeclarationLink name={type} />
+{:else}
+	<Code inline content={type} lang="ts" />
+{/if}

package/dist/TypeLink.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    type: string;
+};
+declare const TypeLink: import("svelte").Component<$$ComponentProps, {}, "">;
+type TypeLink = ReturnType<typeof TypeLink>;
+export default TypeLink;
+//# sourceMappingURL=TypeLink.svelte.d.ts.map

package/dist/TypeLink.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeLink.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/TypeLink.svelte"],"names":[],"mappings":"AAQC,KAAK,gBAAgB,GAAI;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC;AAuBzC,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/alert.d.ts

@@ -0,0 +1,7 @@
+export type AlertStatus = 'inform' | 'help' | 'error';
+export interface AlertStatusOptions {
+    color: string;
+    icon: string | null;
+}
+export declare const alert_status_options: Record<AlertStatus, AlertStatusOptions>;
+//# sourceMappingURL=alert.d.ts.map

package/dist/alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/alert.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,WAAW,EAAE,kBAAkB,CAIxE,CAAC"}

package/dist/alert.js

@@ -0,0 +1,6 @@
+// TODO move to module context?
+export const alert_status_options = {
+    inform: { color: 'var(--text_color_3)', icon: '✻' },
+    help: { color: 'var(--color_b_5)', icon: '➺' },
+    error: { color: 'var(--color_c_5)', icon: '!?' },
+};

package/dist/api_search.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Declaration } from './declaration.svelte.js';
+import type { Library } from './library.svelte.js';
+export interface DeclarationSearchState {
+    query: string;
+    all: Array<Declaration>;
+    filtered: Array<Declaration>;
+}
+/**
+ * Creates search state for the API index page (all declarations across all modules).
+ */
+export declare const create_declaration_search: (library: Library) => DeclarationSearchState;
+/**
+ * Creates search state for module-specific declaration lists.
+ */
+export declare const create_module_declaration_search: (declarations: Array<Declaration>) => DeclarationSearchState;
+//# sourceMappingURL=api_search.svelte.d.ts.map

package/dist/api_search.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_search.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/api_search.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,qBAAqB,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,KAAG,sBAwB5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gCAAgC,GAC5C,cAAc,KAAK,CAAC,WAAW,CAAC,KAC9B,sBAyCF,CAAC"}

package/dist/api_search.svelte.js

@@ -0,0 +1,61 @@
+/**
+ * Creates search state for the API index page (all declarations across all modules).
+ */
+export const create_declaration_search = (library) => {
+    let query = $state('');
+    const all = $derived(library.declarations);
+    const filtered = $derived.by(() => {
+        const items = query.trim() ? library.search_declarations(query) : all;
+        return items.sort((a, b) => a.name.localeCompare(b.name));
+    });
+    return {
+        get query() {
+            return query;
+        },
+        set query(v) {
+            query = v;
+        },
+        get all() {
+            return all;
+        },
+        get filtered() {
+            return filtered;
+        },
+    };
+};
+/**
+ * Creates search state for module-specific declaration lists.
+ */
+export const create_module_declaration_search = (declarations) => {
+    let query = $state('');
+    const all = $derived(declarations);
+    const filtered = $derived.by(() => {
+        const trimmed_query = query.trim();
+        if (!trimmed_query)
+            return all.sort((a, b) => a.name.localeCompare(b.name));
+        const terms = trimmed_query.toLowerCase().split(/\s+/);
+        const items = all.filter((d) => {
+            const name_lower = d.name.toLowerCase();
+            const kind_lower = d.kind.toLowerCase();
+            const module_path_lower = d.module_path.toLowerCase();
+            return terms.every((term) => name_lower.includes(term) ||
+                kind_lower.includes(term) ||
+                module_path_lower.includes(term));
+        });
+        return items.sort((a, b) => a.name.localeCompare(b.name));
+    });
+    return {
+        get query() {
+            return query;
+        },
+        set query(v) {
+            query = v;
+        },
+        get all() {
+            return all;
+        },
+        get filtered() {
+            return filtered;
+        },
+    };
+};

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const MAIN_HEADER_MARGIN_TOP = "calc(60px + var(--space_lg))";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,iCAAiC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,3 @@
+// TODO the 60px is a hack, need `--docs_primary_nav_height` exported or :root values from Fuz -- the --space_lg also needs to be kept in sync
+// see also the same issue in Moss
+export const MAIN_HEADER_MARGIN_TOP = 'calc(60px + var(--space_lg))';

package/dist/context_helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wraps Svelte's `setContext` and `getContext` for better ergonomics.
+ * When no value is set in the context,
+ * `get` throws an error and `get_maybe` returns `undefined`.
+ * If a `fallback` is provided, the `value` argument to `set` is optional
+ * and `get_maybe` is omitted from the type.
+ */
+export declare function create_context<T>(fallback: () => T): {
+    get: () => T;
+    set: (value?: T) => T;
+};
+export declare function create_context<T>(): {
+    get: (error_message?: string) => T;
+    get_maybe: () => T | undefined;
+    set: (value: T) => T;
+};
+//# sourceMappingURL=context_helpers.d.ts.map

package/dist/context_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/context_helpers.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG;IACrD,GAAG,EAAE,MAAM,CAAC,CAAC;IACb,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;CACtB,CAAC;AACF,wBAAgB,cAAc,CAAC,CAAC,KAAK;IACpC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,MAAM,KAAK,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC/B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CACrB,CAAC"}

package/dist/context_helpers.js

@@ -0,0 +1,19 @@
+import { getContext, setContext } from 'svelte';
+export function create_context(fallback) {
+    const key = Symbol();
+    const get_maybe = () => {
+        const value = getContext(key); // treat `null` as a valid value - the `typescript-eslint` rule below is bugged because `??` would clobber nulls, see issue https://github.com/typescript-eslint/typescript-eslint/issues/7842
+        return value === undefined ? fallback?.() : value;
+    };
+    return {
+        get: (error_message) => {
+            const value = get_maybe();
+            if (value === undefined)
+                throw Error(error_message ?? 'context value is not set');
+            return value;
+        },
+        get_maybe,
+        // this is typesafe, so no runtime check:
+        set: (value = fallback?.()) => setContext(key, value),
+    };
+}

package/dist/contextmenu_helpers.d.ts

@@ -0,0 +1,16 @@
+import type { ContextmenuState } from './contextmenu_state.svelte.js';
+export declare const CONTEXTMENU_DEFAULT_OPEN_OFFSET_X = -2;
+export declare const CONTEXTMENU_DEFAULT_OPEN_OFFSET_Y = -2;
+export declare const CONTEXTMENU_DEFAULT_BYPASS_WINDOW = 750;
+export declare const CONTEXTMENU_DEFAULT_BYPASS_MOVE_TOLERANCE = 11;
+export declare const CONTEXTMENU_DEFAULT_LONGPRESS_DURATION = 633;
+export declare const CONTEXTMENU_DEFAULT_LONGPRESS_MOVE_TOLERANCE = 21;
+/**
+ * Returns true if valid and narrows the type to HTMLElement | SVGElement.
+ */
+export declare const contextmenu_is_valid_target: (target: EventTarget | null, shiftKey: boolean) => target is HTMLElement | SVGElement;
+export declare const contextmenu_create_keyboard_handlers: (contextmenu: ContextmenuState) => Map<string, () => void>;
+export declare const contextmenu_create_keydown_handler: (keyboard_handlers: Map<string, () => void>) => ((e: KeyboardEvent) => void);
+export declare const contextmenu_calculate_constrained_x: (menu_x: number, menu_width: number, layout_width: number) => number;
+export declare const contextmenu_calculate_constrained_y: (menu_y: number, menu_height: number, layout_height: number) => number;
+//# sourceMappingURL=contextmenu_helpers.d.ts.map

package/dist/contextmenu_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextmenu_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/contextmenu_helpers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAGpE,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,eAAO,MAAM,yCAAyC,KAAK,CAAC;AAC5D,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAC1D,eAAO,MAAM,4CAA4C,KAAK,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACvC,QAAQ,WAAW,GAAG,IAAI,EAC1B,UAAU,OAAO,KACf,MAAM,IAAI,WAAW,GAAG,UAIF,CAAC;AAI1B,eAAO,MAAM,oCAAoC,GAChD,aAAa,gBAAgB,KAC3B,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAWtB,CAAC;AAEJ,eAAO,MAAM,kCAAkC,GAC9C,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,KACxC,CAAC,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,CAO7B,CAAC;AAEF,eAAO,MAAM,mCAAmC,GAC/C,QAAQ,MAAM,EACd,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,MAAoE,CAAC;AAExE,eAAO,MAAM,mCAAmC,GAC/C,QAAQ,MAAM,EACd,aAAa,MAAM,EACnB,eAAe,MAAM,KACnB,MAAsE,CAAC"}

package/dist/contextmenu_helpers.js

@@ -0,0 +1,39 @@
+import { is_editable, swallow, inside_editable } from '@fuzdev/fuz_util/dom.js';
+// Constants for default prop values
+export const CONTEXTMENU_DEFAULT_OPEN_OFFSET_X = -2;
+export const CONTEXTMENU_DEFAULT_OPEN_OFFSET_Y = -2;
+export const CONTEXTMENU_DEFAULT_BYPASS_WINDOW = 750;
+export const CONTEXTMENU_DEFAULT_BYPASS_MOVE_TOLERANCE = 11;
+export const CONTEXTMENU_DEFAULT_LONGPRESS_DURATION = 633;
+export const CONTEXTMENU_DEFAULT_LONGPRESS_MOVE_TOLERANCE = 21;
+/**
+ * Returns true if valid and narrows the type to HTMLElement | SVGElement.
+ */
+export const contextmenu_is_valid_target = (target, shiftKey) => !shiftKey &&
+    (target instanceof HTMLElement || target instanceof SVGElement) &&
+    !is_editable(target) &&
+    !inside_editable(target);
+// TODO maybe bind these to the contextmenu instance instead of including the function wrapper
+// TODO customize
+export const contextmenu_create_keyboard_handlers = (contextmenu) => new Map([
+    ['Escape', () => contextmenu.close()],
+    ['ArrowLeft', () => contextmenu.collapse_selected()],
+    ['ArrowRight', () => contextmenu.expand_selected()],
+    ['ArrowDown', () => contextmenu.select_next()],
+    ['ArrowUp', () => contextmenu.select_previous()],
+    ['Home', () => contextmenu.select_first()],
+    ['End', () => contextmenu.select_last()],
+    [' ', () => contextmenu.activate_selected()],
+    ['Enter', () => contextmenu.activate_selected()],
+]);
+export const contextmenu_create_keydown_handler = (keyboard_handlers) => {
+    return (e) => {
+        const handler = keyboard_handlers.get(e.key);
+        if (!handler || is_editable(e.target))
+            return;
+        swallow(e);
+        handler();
+    };
+};
+export const contextmenu_calculate_constrained_x = (menu_x, menu_width, layout_width) => menu_x + Math.min(0, layout_width - (menu_x + menu_width));
+export const contextmenu_calculate_constrained_y = (menu_y, menu_height, layout_height) => menu_y + Math.min(0, layout_height - (menu_y + menu_height));

package/dist/contextmenu_state.svelte.d.ts

@@ -0,0 +1,152 @@
+import { type Snippet } from 'svelte';
+import type { Result } from '@fuzdev/fuz_util/result.js';
+import type { SvelteHTMLElements } from 'svelte/elements';
+import type { Attachment } from 'svelte/attachments';
+import { Dimensions } from './dimensions.svelte.js';
+export type ContextmenuParams = Snippet | {
+    snippet: 'link';
+    props: {
+        href: string;
+        icon?: string;
+    };
+} | {
+    snippet: 'text';
+    props: {
+        content: string;
+        icon: string;
+        run: ContextmenuRun;
+    };
+} | {
+    snippet: 'separator';
+    props: SvelteHTMLElements['li'];
+};
+export type ContextmenuActivateResult = void | undefined | Result<{
+    close?: boolean;
+}, {
+    message?: string;
+}>;
+export type ItemState = SubmenuState | EntryState;
+export declare class EntryState {
+    readonly is_menu = false;
+    readonly menu: SubmenuState | RootMenuState;
+    readonly run: () => ContextmenuRun;
+    readonly disabled: () => boolean;
+    selected: boolean;
+    pending: boolean;
+    error_message: string | null;
+    promise: Promise<ContextmenuActivateResult> | null;
+    constructor(menu: SubmenuState | RootMenuState, run: () => ContextmenuRun, disabled?: () => boolean);
+}
+export declare class SubmenuState {
+    readonly is_menu = true;
+    readonly menu: SubmenuState | RootMenuState;
+    readonly depth: number;
+    selected: boolean;
+    items: ReadonlyArray<ItemState>;
+    constructor(menu: SubmenuState | RootMenuState, depth: number);
+}
+export declare class RootMenuState {
+    readonly is_menu = true;
+    readonly menu: null;
+    readonly depth = 1;
+    items: ReadonlyArray<ItemState>;
+}
+export type ContextmenuRun = () => ContextmenuActivateResult | Promise<ContextmenuActivateResult>;
+export interface ContextmenuStateOptions {
+    layout?: Dimensions;
+}
+/**
+ * Creates a `contextmenu` store.
+ * See usage with `ContextmenuRoot.svelte` and `Contextmenu.svelte`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/contextmenu_event
+ */
+export declare class ContextmenuState {
+    layout: Dimensions;
+    /**
+     * If an initial layout is provided, control is deferred externally.
+     * Otherwise the layout syncs to the page dimensions.
+     */
+    readonly has_custom_layout: boolean;
+    opened: boolean;
+    x: number;
+    y: number;
+    params: ReadonlyArray<ContextmenuParams>;
+    error: string | undefined;
+    readonly root_menu: RootMenuState;
+    selections: ReadonlyArray<ItemState>;
+    can_collapse: boolean;
+    can_expand: boolean;
+    can_select_next: boolean;
+    can_select_previous: boolean;
+    can_activate: boolean;
+    constructor(options?: ContextmenuStateOptions);
+    open(params: Array<ContextmenuParams>, x: number, y: number): void;
+    close(): void;
+    reset_items(items: ReadonlyArray<ItemState>): void;
+    activate(item: ItemState): boolean | Promise<ContextmenuActivateResult>;
+    activate_selected(): void | boolean | Promise<ContextmenuActivateResult>;
+    /**
+     * Activates the selected entry, or if none, selects the first.
+     */
+    select(item: ItemState): void;
+    collapse_selected(): void;
+    expand_selected(): void;
+    select_next(): void;
+    select_previous(): void;
+    select_first(): void;
+    select_last(): void;
+    /**
+     * Used by `ContextmenuEntry` and custom entry components
+     * @initializes
+     */
+    add_entry(run: () => ContextmenuRun, disabled?: () => boolean): EntryState;
+    /**
+     * @initializes
+     */
+    add_submenu(): SubmenuState;
+}
+/**
+ * Creates an attachment that sets up contextmenu behavior on an element.
+ * @param params Contextmenu parameters or nullish to disable
+ */
+export declare const contextmenu_attachment: <T extends ContextmenuParams, U extends T | Array<T>>(params: U | null | undefined) => Attachment<HTMLElement | SVGElement>;
+export interface ContextmenuOpenOptions {
+    link_enabled?: boolean;
+    text_enabled?: boolean;
+    separator_enabled?: boolean;
+    vibrate?: boolean;
+}
+/**
+ * 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 options optional configuration for filtering entries and haptic feedback
+ * @returns a boolean indicating if the menu was opened or not
+ */
+export declare const contextmenu_open: (target: HTMLElement | SVGElement, x: number, y: number, contextmenu: ContextmenuState, options?: ContextmenuOpenOptions) => boolean;
+export declare const contextmenu_context: {
+    get: (error_message?: string) => ContextmenuState;
+    get_maybe: () => ContextmenuState | undefined;
+    set: (value: ContextmenuState) => ContextmenuState;
+};
+export declare const contextmenu_submenu_context: {
+    get: (error_message?: string) => SubmenuState;
+    get_maybe: () => SubmenuState | undefined;
+    set: (value: SubmenuState) => SubmenuState;
+};
+export declare const contextmenu_dimensions_context: {
+    get: () => Dimensions;
+    set: (value?: Dimensions | undefined) => Dimensions;
+};
+/**
+ * Registers a contextmenu root and warns if multiple non-scoped roots are detected.
+ * Only active in development mode. Automatically handles cleanup on unmount.
+ *
+ * @param get_scoped Getter function that returns the current scoped value
+ */
+export declare const contextmenu_check_global_root: (get_scoped: () => boolean) => void;
+//# sourceMappingURL=contextmenu_state.svelte.d.ts.map

package/dist/contextmenu_state.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextmenu_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/contextmenu_state.svelte.ts"],"names":[],"mappings":"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"}