@flowdular/sdk 0.2.3 → 0.3.0

package/packages/client/src/shell/CommandPalette.tsrx

@@ -1,17 +1,44 @@
-import { Icon } from '@flowdular/sdk/ui';
-import type { NavigationContribution } from '../contributions.ts';
+import { useEffect, useRef, useState } from 'octane';
+import { Icon, trapFocus } from '@flowdular/sdk/ui';
+import type {
+	CommandSearchContribution,
+	CommandSearchHit,
+	NavigationContribution,
+} from '../contributions.ts';
 import { activeLocale, t } from '../i18n/runtime.ts';
+import {
+	commandSearchOutcome,
+	commandSearchReady,
+	groupCommandSearchHits,
+	runCommandSearch,
+	COMMAND_SEARCH_DEBOUNCE_MS,
+} from './command-search.ts';
 import { navigationGroupLabel } from './navigation.ts';
+import { nextPaletteIndex, paletteOptionId } from './palette-keys.ts';
 import type { NavigateToView } from './types.ts';
 
 export interface CommandPaletteProps {
 	items: readonly NavigationContribution[];
+	/** Contributions the member's scopes allow; empty means no record section. */
+	searches: readonly CommandSearchContribution[];
 	query: string;
 	onQuery: (query: string) => void;
 	onNavigate: NavigateToView;
+	onOpenHit: (hit: CommandSearchHit) => void;
 	onClose: () => void;
 }
 
+type RecordStatus = 'idle' | 'loading' | 'ready' | 'partial' | 'error';
+
+type PaletteOption =
+	| { readonly kind: 'view'; readonly item: NavigationContribution }
+	| { readonly kind: 'hit'; readonly hit: CommandSearchHit };
+
+/** Keys the list handles itself; anything else keeps typing in the input. */
+const SELECTION_KEYS = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
+
+const OPTIONS_ID = 'command-options';
+
 export function CommandPalette(props: CommandPaletteProps) @{
 	const locale = activeLocale();
 	const normalizedQuery = props.query.trim().toLocaleLowerCase(locale);
@@ -27,48 +54,233 @@ export function CommandPalette(props: CommandPaletteProps) @{
 						locale,
 					).includes(normalizedQuery)),
 	);
+	const [hits, setHits] = useState<readonly CommandSearchHit[]>([]);
+	const [recordStatus, setRecordStatus] = useState<RecordStatus>('idle');
+	const [active, setActive] = useState(0);
+	const dialog = useRef<HTMLElement | null>(null);
+	const results = useRef<HTMLDivElement | null>(null);
+	const groups = groupCommandSearchHits(hits);
+	/* Navigation entries first, then the record hits in the order they are
+   listed: one sequence, so an index is all the selection has to carry. */
+	const options: PaletteOption[] = [];
+	const views = matches.map((item, index) => {
+		options.push({ kind: 'view', item });
+		return { item, index };
+	});
+	const hitGroups = groups.map(
+		(group) => ({
+			provider: group.provider,
+			label: group.label,
+			hits: group.hits.map((hit) => {
+				options.push({ kind: 'hit', hit });
+				return { hit, index: options.length - 1 };
+			}),
+		}),
+	);
+	const activeIndex =
+		options.length === 0
+			? 0
+			: Math.min(Math.max(active, 0), options.length - 1);
+
+	const activate = (option: PaletteOption | undefined) => {
+		if (!option) return;
+		if (option.kind === 'view') props.onNavigate(option.item.viewId);
+		else props.onOpenHit(option.hit);
+	};
+
+	const keyDown = (event: KeyboardEvent) => {
+		if (SELECTION_KEYS.includes(event.key)) {
+			event.preventDefault();
+			setActive(nextPaletteIndex(activeIndex, options.length, event.key));
+			return;
+		}
+		if (event.key === 'Enter' && options[activeIndex]) {
+			event.preventDefault();
+			activate(options[activeIndex]);
+		}
+	};
+
+	/* Record hits are debounced and abortable, and they are resolved outside the
+   navigation list above: whatever a contribution does, typing and choosing a
+   navigation entry keep working at full speed. */
+	useEffect(() => {
+		const query = props.query.trim();
+		if (props.searches.length === 0 || !commandSearchReady(query)) {
+			setHits([]);
+			setRecordStatus('idle');
+			return;
+		}
+		const controller = new AbortController();
+		setRecordStatus('loading');
+		const timer = setTimeout(() => {
+			void runCommandSearch(props.searches, query, controller.signal).then(
+				(answer) => {
+					if (controller.signal.aborted) return;
+					setHits(answer.hits);
+					setRecordStatus(
+						commandSearchOutcome(props.searches.length, answer.failed.length),
+					);
+				},
+				() => {
+					if (controller.signal.aborted) return;
+					setHits([]);
+					setRecordStatus('error');
+				},
+			);
+		}, COMMAND_SEARCH_DEBOUNCE_MS);
+		return () => {
+			clearTimeout(timer);
+			controller.abort();
+		};
+	}, [props.query, props.searches]);
+
+	/* A new query is a new list, so the selection starts at the top of it. */
+	useEffect(() => setActive(0), [props.query, hits]);
+
+	useEffect(() => {
+		const list = results.current;
+		const option = list?.querySelector('[aria-selected="true"]');
+		if (!list || !option) return;
+		const bounds = list.getBoundingClientRect();
+		const selected = option.getBoundingClientRect();
+		if (selected.top < bounds.top) list.scrollTop -= bounds.top - selected.top;
+		else if (selected.bottom > bounds.bottom) list.scrollTop +=
+			selected.bottom - bounds.bottom;
+	}, [activeIndex]);
+
+	/* The palette is modal: Tab stays inside it, and closing puts the member
+   back where they opened it from, which is the topbar button or whatever had
+   focus when the shortcut was pressed. */
+	useEffect(() => {
+		const element = dialog.current;
+		return element === null ? undefined : trapFocus(element);
+	}, []);
+
 	<div class="command-layer" role="presentation" onClick={props.onClose}>
 		<section
 			class="command-dialog"
 			role="dialog"
 			aria-modal="true"
 			aria-label={t('shell.command.label')}
+			tabIndex={-1}
+			ref={dialog}
 			onClick={(event) => event.stopPropagation()}
+			onKeyDown={keyDown}
 		>
 			<label class="command-dialog__input">
 				<Icon name="search" size={16} />
 				<input
-					autoFocus
 					type="search"
+					role="combobox"
+					aria-expanded={options.length > 0}
+					aria-controls={OPTIONS_ID}
+					aria-autocomplete="list"
+					autocomplete="off"
+					aria-activedescendant={options.length > 0
+						? paletteOptionId(activeIndex)
+						: undefined}
 					placeholder={t('shell.command.placeholder')}
 					value={props.query}
 					onInput={(event) => props.onQuery(event.currentTarget.value)}
 				/>
 				<span class="ui-kbd">ESC</span>
 			</label>
-			<div class="command-dialog__results">
+			<div
+				class="command-dialog__results"
+				id={OPTIONS_ID}
+				role="listbox"
+				aria-label={t('shell.command.label')}
+				ref={results}
+			>
 				<div class="ui-menu__label">{t('shell.command.section')}</div>
 				@if (matches.length === 0) {
-					<p class="ui-table__empty">{t('shell.command.empty', {
+					<p class="ui-table__empty" role="status">{t('shell.command.empty', {
 						query: props.query,
 					})}</p>
 				}
-				@for (const item of matches; key item.id) {
+				@for (const view of views; key view.item.id) {
 					<button
-						class="command-item"
+						class={[
+							'command-item',
+							view.index === activeIndex && 'command-item--active',
+						]}
 						type="button"
-						onClick={() => props.onNavigate(item.viewId)}
+						role="option"
+						id={paletteOptionId(view.index)}
+						aria-selected={view.index === activeIndex}
+						tabIndex={-1}
+						onClick={() => props.onNavigate(view.item.viewId)}
 					>
-						<Icon name={item.glyph} size={16} />
+						<Icon name={view.item.glyph} size={16} />
 						<span class="ui-cell">
-							<b>{item.label}</b>
+							<b>{view.item.label}</b>
 							<small>
-								{navigationGroupLabel(t, item.group) + ' · ' + item.description}
+								{navigationGroupLabel(t, view.item.group) + ' · ' +
+									view.item.description}
 							</small>
 						</span>
 						<span class="ui-kbd">↵</span>
 					</button>
 				}
+				@if (recordStatus === 'loading') {
+					<>
+						<div class="ui-menu__label">{t('shell.command.records')}</div>
+						<p class="ui-table__empty" role="status">{t(
+							'shell.command.searching',
+						)}</p>
+					</>
+				}
+				@if (recordStatus === 'error') {
+					<>
+						<div class="ui-menu__label">{t('shell.command.records')}</div>
+						<p class="ui-table__empty" role="status">{t(
+							'shell.command.recordsError',
+						)}</p>
+					</>
+				}
+				@if (recordStatus === 'partial') {
+					<>
+						<div class="ui-menu__label">{t('shell.command.records')}</div>
+						<p class="ui-table__empty" role="status">{t(
+							'shell.command.recordsPartial',
+						)}</p>
+					</>
+				}
+				@if (recordStatus === 'ready' && groups.length === 0) {
+					<>
+						<div class="ui-menu__label">{t('shell.command.records')}</div>
+						<p class="ui-table__empty" role="status">{t(
+							'shell.command.recordsEmpty',
+							{ query: props.query },
+						)}</p>
+					</>
+				}
+				@for (const group of hitGroups; key group.provider) {
+					<>
+						<div class="ui-menu__label">{group.label}</div>
+						@for (const entry of group.hits; key entry.hit.id) {
+							<button
+								class={[
+									'command-item',
+									entry.index === activeIndex && 'command-item--active',
+								]}
+								type="button"
+								role="option"
+								id={paletteOptionId(entry.index)}
+								aria-selected={entry.index === activeIndex}
+								tabIndex={-1}
+								onClick={() => props.onOpenHit(entry.hit)}
+							>
+								<Icon name="file-text" size={16} />
+								<span class="ui-cell">
+									<b>{entry.hit.title}</b>
+									<small>{entry.hit.snippet}</small>
+								</span>
+								<span class="ui-kbd">↵</span>
+							</button>
+						}
+					</>
+				}
 			</div>
 			<footer class="command-dialog__foot">
 				<span>{t('shell.command.open')}</span>

package/packages/client/src/shell/command-search.ts

@@ -0,0 +1,126 @@
+import type {
+	CommandSearchContribution,
+	CommandSearchHit,
+} from '../contributions.ts';
+
+/** A query shorter than this asks nobody; the palette shows navigation only. */
+export const COMMAND_SEARCH_MINIMUM = 2;
+/** Idle time after the last keystroke before a contribution is asked. */
+export const COMMAND_SEARCH_DEBOUNCE_MS = 200;
+/** Hits one group shows, so a talkative provider cannot bury the others. */
+export const COMMAND_SEARCH_GROUP_LIMIT = 5;
+
+export interface CommandSearchGroup {
+	readonly provider: string;
+	readonly label: string;
+	readonly hits: readonly CommandSearchHit[];
+}
+
+export function commandSearchReady(query: string): boolean {
+	return query.trim().length >= COMMAND_SEARCH_MINIMUM;
+}
+
+/**
+ * Groups by provider in first-seen order and caps each group. The order the
+ * hits arrive in is the answer's own ranking, so grouping never reorders
+ * within a provider and never compares scores across providers.
+ */
+export function groupCommandSearchHits(
+	hits: readonly CommandSearchHit[],
+): readonly CommandSearchGroup[] {
+	const groups = new Map<string, CommandSearchHit[]>();
+	const labels = new Map<string, string>();
+	for (const hit of hits) {
+		const group = groups.get(hit.provider);
+		if (group) {
+			if (group.length < COMMAND_SEARCH_GROUP_LIMIT) group.push(hit);
+			continue;
+		}
+		groups.set(hit.provider, [hit]);
+		labels.set(hit.provider, hit.providerLabel);
+	}
+	return [...groups].map(([provider, entries]) => ({
+		provider,
+		label: labels.get(provider) ?? provider,
+		hits: entries,
+	}));
+}
+
+export interface CommandSearchAnswer {
+	readonly hits: readonly CommandSearchHit[];
+	/** Ids of the contributions that answered nothing the palette can list. */
+	readonly failed: readonly string[];
+}
+
+/* Which contribution answered with a hit, so opening one reaches its author and
+   nobody else. Weakly keyed by the hit: an answer the palette replaced takes its
+   entries with it, so nothing is pruned and nothing is held alive. */
+const hitOrigin = new WeakMap<CommandSearchHit, CommandSearchContribution>();
+
+/**
+ * Tells the contribution that answered with this hit that the member opened it.
+ * Fire and forget on the navigation path: the answer is never awaited and a
+ * contribution that throws or rejects is isolated here, so whatever it does the
+ * record still opens. A hit from no known answer reaches nobody.
+ */
+export function commandSearchHitOpened(hit: CommandSearchHit): void {
+	const contribution = hitOrigin.get(hit);
+	if (!contribution?.onOpen) return;
+	try {
+		void Promise.resolve(contribution.onOpen(hit)).catch(() => undefined);
+	} catch {
+		/* A contribution that throws before it returns a promise is the same
+		   failure as one that rejects, and costs the member the same nothing. */
+	}
+}
+
+/**
+ * Asks every contribution in parallel and keeps their declared order. A
+ * contribution is foreign code on the shell's critical path: one that rejects
+ * or answers with something unreadable contributes nothing, so the palette
+ * keeps listing navigation entries whatever a module does. It is named in
+ * `failed` instead, because a member who is shown three groups out of four has
+ * to be told the fourth is missing rather than read the list as complete. An
+ * empty list is an answer, not a failure.
+ */
+export async function runCommandSearch(
+	contributions: readonly CommandSearchContribution[],
+	query: string,
+	signal: AbortSignal,
+): Promise<CommandSearchAnswer> {
+	const answers = await Promise.allSettled(
+		/* `async` so a contribution that throws before it returns a promise is
+		   isolated by the same settlement as one that rejects. */
+		contributions.map(async (contribution) =>
+			contribution.search({ query, signal }),
+		),
+	);
+	const hits: CommandSearchHit[] = [];
+	const failed: string[] = [];
+	for (const [index, answer] of answers.entries()) {
+		if (answer.status !== 'fulfilled' || !Array.isArray(answer.value)) {
+			failed.push(contributions[index]!.id);
+			continue;
+		}
+		for (const hit of answer.value) {
+			if (hit && typeof hit.id === 'string' && typeof hit.title === 'string') {
+				hits.push(hit);
+				hitOrigin.set(hit, contributions[index]!);
+			}
+		}
+	}
+	return { hits, failed };
+}
+
+/**
+ * What the palette says about its record section. Every asked contribution
+ * failing is a failure the member has to see in place of the hits; some of them
+ * failing still lists what came back, under a notice that it is incomplete.
+ */
+export function commandSearchOutcome(
+	asked: number,
+	failed: number,
+): 'ready' | 'partial' | 'error' {
+	if (asked > 0 && failed >= asked) return 'error';
+	return failed > 0 ? 'partial' : 'ready';
+}

package/packages/client/src/shell/command.ts

@@ -0,0 +1,30 @@
+type CommandPaletteListener = (query: string) => void;
+
+/* One workspace shell subscribes at a time; the set exists so a widget in a
+   module can reach the palette without the shell exporting its state. */
+const listeners = new Set<CommandPaletteListener>();
+
+/**
+ * Opens the workspace command palette, optionally seeded with a query. Safe to
+ * call before the shell is mounted: with no listener it does nothing.
+ */
+export function openCommandPalette(query = ''): void {
+	for (const listener of [...listeners]) {
+		try {
+			listener(query);
+		} catch {
+			/* A listener is the shell's own; a throw must not reach the widget
+			   that asked, which has nothing to do about it. */
+		}
+	}
+}
+
+/** Subscribes the shell. The returned function detaches it. */
+export function onOpenCommandPalette(
+	listener: CommandPaletteListener,
+): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}

package/packages/client/src/shell/navigation.ts

@@ -58,6 +58,18 @@ export function navigationForIdentity(
 	);
 }
 
+/**
+ * A hit's route, or null when it is not a plain path inside this workspace.
+ * The route comes from a module, and the shell pushes it at the browser: a
+ * protocol-relative `//host` leaves the application, and a backslash does the
+ * same once the URL parser normalizes it to a slash.
+ */
+export function workspaceHitRoute(route: string): string | null {
+	if (typeof route !== 'string') return null;
+	if (!route.startsWith('/') || route.startsWith('//')) return null;
+	return route.includes('\\') ? null : route;
+}
+
 export function viewHref(
 	viewId: ShellView,
 	workspaceSlug?: string | null,

package/packages/client/src/shell/palette-keys.ts

@@ -0,0 +1,27 @@
+/**
+ * The palette lists navigation entries and record hits as one sequence, and
+ * the member moves through it with the arrow keys while focus stays in the
+ * input. The active option is named by id rather than focused, so typing is
+ * never interrupted by focus moving to a button.
+ */
+export function paletteOptionId(index: number): string {
+	return 'command-option-' + String(index);
+}
+
+/**
+ * The option an arrow, Home or End key selects. Selection wraps at both ends,
+ * and a key this list does not handle leaves it where it was.
+ */
+export function nextPaletteIndex(
+	current: number,
+	count: number,
+	key: string,
+): number {
+	if (count <= 0) return 0;
+	const index = Math.min(Math.max(current, 0), count - 1);
+	if (key === 'ArrowDown') return (index + 1) % count;
+	if (key === 'ArrowUp') return (index - 1 + count) % count;
+	if (key === 'Home') return 0;
+	if (key === 'End') return count - 1;
+	return index;
+}

package/packages/client/src/shell/shell.css

@@ -619,6 +619,13 @@
 	border-top: 1px solid var(--line-2);
 }
 
+/* The palette is driven from the input with the arrow keys, so the active
+   option is marked rather than focused and needs a resting state of its own. */
+.command-item--active,
+.command-item:focus-visible {
+	background: var(--primary-tint);
+}
+
 /* Mobile */
 .mobile-header,
 .scrim {