entasis 0.11.0 → 0.12.0

package/dist/components/AIAskUserQuestion/AIAskUserQuestion.svelte

@@ -1,6 +1,8 @@
 <script lang="ts">
-	import { onDestroy } from 'svelte';
+	import { onDestroy, tick } from 'svelte';
+	import { SvelteMap } from 'svelte/reactivity';
 	import { createBindableValue } from '../../utils/state.svelte.js';
+	import { composedContains, getDeepActiveElement, resolveInitialFocus } from '../../utils/focus.js';
 	import Alert from '../Alert/Alert.svelte';
 	import Empty from '../Empty/Empty.svelte';
 	import Slot from '../Slot/Slot.svelte';
@@ -10,9 +12,10 @@
 	import AIAskUserQuestionStep from './AIAskUserQuestionStep.svelte';
 	import {
 		getFirstMissingAIAskQuestionIndex,
-		getAIAskQuestionType,
+		hasAIAskAnswer,
 		hasSameAIAskAnswer,
 		isAIAskQuestionAnswered,
+		isAIAskQuestionRequired,
 		toAIAskAnswerList
 	} from './aiAskUserQuestionAnswers.js';
 	import type {
@@ -35,6 +38,7 @@
 		autoAdvanceSingle,
 		autoAdvanceDelay,
 		autoAdvanceSingleDelay,
+		showOther = true,
 		disabled = false,
 		submitting = false,
 		title,
@@ -43,8 +47,11 @@
 		submitLabel,
 		submittingLabel,
 		discardLabel,
+		// Deprecated and no longer rendered; destructured so it never lands on the root element.
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
 		previousLabel,
 		nextLabel,
+		skipLabel,
 		emptyLabel,
 		emptyTitle,
 		emptyDescription,
@@ -60,6 +67,7 @@
 		children,
 		class: className,
 		theme,
+		onkeydown: onKeydownProp,
 		...attachments
 	}: AIAskUserQuestionProps = $props();
 	const t = $derived(useI18n());
@@ -76,8 +84,25 @@
 	let isSubmitting = $state(false);
 	let isDiscarding = $state(false);
 	let advanceTimer: ReturnType<typeof setTimeout> | undefined;
+	let bodyElement = $state<HTMLDivElement>();
+	// Number-key pickers of the default question steps, keyed by question id (read from the key
+	// handler only).
+	const pickers = new SvelteMap<string, (position: number) => boolean>();
+	// The "Other…" text of each choice question while Other is chosen. Kept here rather than in the
+	// step so it survives the step remounting, and so typed text that equals an option id still
+	// reads as Other.
+	const otherAnswers = new SvelteMap<string, string>();
 
-	const questionItems = $derived<AIAskQuestion[]>(Array.from(questions));
+	// A choice question without its own `showOther` takes the component's, so free text is on by
+	// default; the resolved question is what the steps, the state and the submit payload see.
+	const questionItems = $derived<AIAskQuestion[]>(
+		Array.from(questions, (question) =>
+			(question.type === 'single' || question.type === 'multiple') &&
+			question.showOther === undefined
+				? { ...question, showOther }
+				: question
+		)
+	);
 	const resolvedValues = $derived(valueState.value);
 	const shouldAutoAdvance = $derived(autoAdvance ?? autoAdvanceSingle ?? true);
 	const resolvedAutoAdvanceDelay = $derived(autoAdvanceDelay ?? autoAdvanceSingleDelay ?? 280);
@@ -90,6 +115,13 @@
 	const controlsDisabled = $derived(disabled || isWorking);
 	const isFirst = $derived(activeIndex <= 0);
 	const isLast = $derived(activeIndex >= questionItems.length - 1);
+	const canSkip = $derived(
+		Boolean(
+			activeQuestion &&
+			!isAIAskQuestionRequired(activeQuestion) &&
+			!hasAIAskAnswer(activeQuestion, resolvedValues)
+		)
+	);
 	const classes = $derived(useAIAskUserQuestionTheme(theme));
 	const componentState = $derived<AIAskUserQuestionState>({
 		questions: questionItems,
@@ -119,7 +151,21 @@
 		activeIndex = Math.max(0, Math.min(activeIndex, questionItems.length - 1));
 	});
 
-	function setAnswer(questionId: string, answer: AIAskAnswer): void {
+	function registerPicker(questionId: string, pick: (position: number) => boolean): () => void {
+		pickers.set(questionId, pick);
+		return () => {
+			if (pickers.get(questionId) === pick) pickers.delete(questionId);
+		};
+	}
+
+	function setOther(questionId: string, text: string | undefined): void {
+		if (controlsDisabled) return;
+		if (text === undefined) otherAnswers.delete(questionId);
+		else otherAnswers.set(questionId, text);
+	}
+
+	/** `advance: false` (an "Other…" edit) never schedules the auto-advance. */
+	function setAnswer(questionId: string, answer: AIAskAnswer, advance = true): void {
 		const question = questionItems.find((candidate) => candidate.id === questionId);
 		if (!question) throw new Error(`Cannot answer missing AI question "${questionId}".`);
 		if (controlsDisabled) return;
@@ -131,7 +177,8 @@
 			errorMessage = undefined;
 		}
 		onValueChange?.(nextValues);
-		scheduleAdvance(question, answer);
+		if (advance) scheduleAdvance(question, answer);
+		else clearAdvance();
 	}
 
 	function goTo(index: number): void {
@@ -140,16 +187,36 @@
 			activeIndex = 0;
 			return;
 		}
-		activeIndex = Math.max(0, Math.min(index, questionItems.length - 1));
+		const nextIndex = Math.max(0, Math.min(index, questionItems.length - 1));
+		// The step that held focus turns inert, which drops focus to <body> and out of the number
+		// keys and Enter. Focus that was inside the steps follows to the new one; a header pager or
+		// footer button keeps its own focus.
+		const followFocus =
+			nextIndex !== activeIndex &&
+			bodyElement !== undefined &&
+			composedContains(bodyElement, getDeepActiveElement(bodyElement.ownerDocument));
+		activeIndex = nextIndex;
+		if (followFocus) void focusActiveStep();
+	}
+
+	async function focusActiveStep(): Promise<void> {
+		await tick();
+		const step = bodyElement?.querySelector<HTMLElement>(
+			'[data-step-active="true"] [data-slot="ai-ask-user-question-step"]'
+		);
+		// A custom `children` body has no step element: its first control takes focus.
+		const scope = step ?? bodyElement;
+		if (scope) resolveInitialFocus(scope).focus({ preventScroll: true });
 	}
 
 	function scheduleAdvance(question: AIAskQuestion, answer: AIAskAnswer): void {
 		clearAdvance();
 		if (
 			!shouldAutoAdvance ||
-			getAIAskQuestionType(question) !== 'single' ||
+			question.type !== 'single' ||
 			typeof answer !== 'string' ||
-			answer.length === 0 ||
+			// Only a picked option advances (an app's own question renderer may set free text).
+			!question.options.some((option) => option.id === answer) ||
 			isLast ||
 			controlsDisabled ||
 			activeQuestion?.id !== question.id
@@ -211,7 +278,7 @@
 				questions: questionItems
 			});
 		} catch (error) {
-			errorMessage = getErrorMessage(error, 'Unable to submit the answers.');
+			errorMessage = getErrorMessage(error, t.aiAskSubmitFailed);
 		} finally {
 			isSubmitting = false;
 		}
@@ -225,7 +292,7 @@
 		try {
 			await onDiscard();
 		} catch (error) {
-			errorMessage = getErrorMessage(error, 'Unable to discard the questions.');
+			errorMessage = getErrorMessage(error, t.aiAskDiscardFailed);
 		} finally {
 			isDiscarding = false;
 		}
@@ -234,6 +301,50 @@
 	function getErrorMessage(error: unknown, fallback: string): string {
 		return error instanceof Error && error.message ? error.message : fallback;
 	}
+
+	function isTextEntry(target: EventTarget | null): boolean {
+		if (!(target instanceof HTMLElement)) return false;
+		if (target.isContentEditable || target instanceof HTMLTextAreaElement) return true;
+		return (
+			target instanceof HTMLInputElement &&
+			!['radio', 'checkbox', 'button', 'submit', 'reset', 'file'].includes(target.type)
+		);
+	}
+
+	function isChoice(target: EventTarget | null): boolean {
+		return target instanceof Element && target.closest('[role="radio"],[role="checkbox"]') !== null;
+	}
+
+	// The step itself holds focus when a step change finds no control inside it (a file step).
+	function isStep(target: EventTarget | null): boolean {
+		return target instanceof Element && target.matches('[data-slot="ai-ask-user-question-step"]');
+	}
+
+	// Number keys 1–9 pick the active question's options (Other… comes last); Enter continues or
+	// submits from a choice, a one-line field or a focused step, and Ctrl/Cmd+Enter does so from a
+	// textarea.
+	function handleKeydown(event: KeyboardEvent & { currentTarget: EventTarget & HTMLDivElement }) {
+		const preventedBefore = event.defaultPrevented;
+		onKeydownProp?.(event);
+		if ((!preventedBefore && event.defaultPrevented) || controlsDisabled || event.isComposing) {
+			return;
+		}
+		const target = event.target;
+		if (event.key === 'Enter') {
+			if (event.repeat || event.shiftKey || event.altKey) return;
+			const modified = event.ctrlKey || event.metaKey;
+			const textArea = target instanceof HTMLTextAreaElement;
+			if (textArea ? !modified : modified && !isTextEntry(target)) return;
+			if (!isChoice(target) && !isTextEntry(target) && !isStep(target)) return;
+			if (preventedBefore && !isChoice(target)) return;
+			event.preventDefault();
+			nextOrSubmit();
+			return;
+		}
+		if (preventedBefore || event.ctrlKey || event.metaKey || event.altKey) return;
+		if (!/^[1-9]$/.test(event.key) || isTextEntry(target) || !activeQuestion) return;
+		if (pickers.get(activeQuestion.id)?.(Number(event.key) - 1)) event.preventDefault();
+	}
 </script>
 
 <div
@@ -241,6 +352,7 @@
 	data-slot="ai-ask-user-question"
 	class={classes.root({ className })}
 	{...attachments}
+	onkeydown={handleKeydown}
 >
 	{#if questionItems.length === 0}
 		{#if empty}
@@ -271,7 +383,7 @@
 			/>
 		{/if}
 
-		<div data-slot="ai-ask-user-question-body" class={classes.body()}>
+		<div bind:this={bodyElement} data-slot="ai-ask-user-question-body" class={classes.body()}>
 			{#if children}
 				<Slot render={children} payload={componentState} />
 			{:else}
@@ -289,8 +401,12 @@
 							errorMessage={errorQuestionId === item.id ? errorMessage : undefined}
 							disabled={controlsDisabled}
 							renderer={questionSlot}
-							onValueChange={(answer) => setAnswer(item.id, answer)}
+							other={otherAnswers.get(item.id)}
+							onValueChange={(answer, options) =>
+								setAnswer(item.id, answer, options?.advance ?? true)}
+							onOtherChange={(text) => setOther(item.id, text)}
 							onError={(message) => setQuestionError(item.id, message)}
+							onRegister={(pick) => registerPicker(item.id, pick)}
 							{theme}
 						/>
 					{/snippet}
@@ -298,7 +414,7 @@
 			{/if}
 
 			{#if errorMessage && !errorQuestionId}
-				<Alert color="danger" variant="soft" description={errorMessage} class={classes.error()} />
+				<Alert color="danger" variant="soft" description={errorMessage} class={classes.alert()} />
 			{/if}
 		</div>
 
@@ -306,19 +422,17 @@
 			<Slot render={footer} payload={componentState} class={classes.footer()} />
 		{:else}
 			<AIAskUserQuestionFooter
-				{isFirst}
 				{isLast}
+				{canSkip}
 				disabled={controlsDisabled}
 				isSubmitting={resolvedIsSubmitting}
 				{isDiscarding}
 				canDiscard={Boolean(onDiscard)}
-				previousLabel={previousLabel ?? t.aiAskPrevious}
 				nextLabel={nextLabel ?? t.aiAskNext}
+				skipLabel={skipLabel ?? t.aiAskSkip}
 				submitLabel={submitLabel ?? t.submit}
 				submittingLabel={submittingLabel ?? t.aiAskSubmitting}
 				discardLabel={discardLabel ?? t.dismiss}
-				onPrevious={() => goTo(activeIndex - 1)}
-				onNext={() => goTo(activeIndex + 1)}
 				onPrimary={nextOrSubmit}
 				onDiscard={() => void discardAnswers()}
 				{theme}

package/dist/components/AIAskUserQuestion/AIAskUserQuestionFileStep.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import FileInput from '../Form/File/FileInput.svelte';
+	import { useI18n } from '../../i18n/context.svelte.js';
 	import type { FileRejection } from '../Form/File/fileAcceptance.js';
 	import type { AIFileQuestion } from './aiAskUserQuestion.props.js';
 	import {
@@ -10,6 +11,9 @@
 	let {
 		question,
 		files,
+		labelledby,
+		invalid = false,
+		describedby,
 		disabled = false,
 		required = false,
 		onValueChange,
@@ -18,6 +22,12 @@
 	}: {
 		question: AIFileQuestion;
 		files: File[];
+		/** Id of the question title that names the file group. */
+		labelledby?: string;
+		/** Marks the group `data-invalid` while the question shows an error. */
+		invalid?: boolean;
+		/** Id of the question's error message. */
+		describedby?: string;
 		disabled?: boolean;
 		required?: boolean;
 		onValueChange: (files: File[]) => void;
@@ -27,6 +37,7 @@
 
 	const types = $derived(normalizeAccept(question.accept));
 	const classes = $derived(useAIAskUserQuestionTheme(theme));
+	const t = $derived(useI18n());
 
 	function normalizeAccept(accept: string | readonly string[] | undefined): string[] {
 		if (!accept) return [];
@@ -39,15 +50,24 @@
 
 	function formatRejections(rejections: FileRejection[]): string {
 		const reasons = new Set(rejections.map((rejection) => rejection.reason));
-		if (reasons.has('type')) return 'Some files do not match the accepted type.';
-		if (reasons.has('size')) return 'Some files are larger than the allowed size.';
-		if (reasons.has('limit')) return 'Too many files selected for this question.';
-		if (reasons.has('duplicate')) return 'Some files were already selected.';
-		return 'Some files could not be added.';
+		if (reasons.has('type')) return t.aiAskFileType;
+		if (reasons.has('size')) return t.aiAskFileSize;
+		if (reasons.has('limit')) return t.aiAskFileLimit;
+		if (reasons.has('duplicate')) return t.aiAskFileDuplicate;
+		return t.aiAskFileRejected;
 	}
 </script>
 
-<div data-slot="ai-ask-user-question-file" class={classes.file()}>
+<!-- The group carries the question's name and error message, as the choice and text controls do
+     (a group has no aria-invalid, so the invalid state is a data attribute). -->
+<div
+	data-slot="ai-ask-user-question-file"
+	data-invalid={invalid || undefined}
+	role="group"
+	aria-labelledby={labelledby}
+	aria-describedby={describedby}
+	class={classes.file()}
+>
 	{#if question.multiple ?? true}
 		<FileInput
 			mode="multiple"

package/dist/components/AIAskUserQuestion/AIAskUserQuestionFileStep.svelte.d.ts

@@ -3,6 +3,12 @@ import { type AIAskUserQuestionThemeProps } from './aiAskUserQuestion.theme.js';
 type $$ComponentProps = {
     question: AIFileQuestion;
     files: File[];
+    /** Id of the question title that names the file group. */
+    labelledby?: string;
+    /** Marks the group `data-invalid` while the question shows an error. */
+    invalid?: boolean;
+    /** Id of the question's error message. */
+    describedby?: string;
     disabled?: boolean;
     required?: boolean;
     onValueChange: (files: File[]) => void;

package/dist/components/AIAskUserQuestion/AIAskUserQuestionFooter.svelte

@@ -1,6 +1,5 @@
 <script lang="ts">
 	import Button from '../Button/Button.svelte';
-	import { arrowLeftIcon } from '../Icons/arrowLeft.js';
 	import { arrowRightIcon } from '../Icons/arrowRight.js';
 	import { checkIcon } from '../Icons/check.js';
 	import {
@@ -9,93 +8,68 @@
 	} from './aiAskUserQuestion.theme.js';
 
 	let {
-		isFirst,
 		isLast,
+		canSkip,
 		disabled,
 		isSubmitting,
 		isDiscarding,
 		canDiscard,
-		previousLabel,
 		nextLabel,
+		skipLabel,
 		submitLabel,
 		submittingLabel,
 		discardLabel,
-		onPrevious,
-		onNext,
 		onPrimary,
 		onDiscard,
 		theme
 	}: {
-		isFirst: boolean;
 		isLast: boolean;
+		/** The active question is optional and unanswered, so the primary action skips it. */
+		canSkip: boolean;
 		disabled: boolean;
 		isSubmitting: boolean;
 		isDiscarding: boolean;
 		canDiscard: boolean;
-		previousLabel: string;
 		nextLabel: string;
+		skipLabel: string;
 		submitLabel: string;
 		submittingLabel: string;
 		discardLabel: string;
-		onPrevious: () => void;
-		onNext: () => void;
 		onPrimary: () => void;
 		onDiscard: () => void;
 		theme?: AIAskUserQuestionThemeProps;
 	} = $props();
 
 	const classes = $derived(useAIAskUserQuestionTheme(theme));
+	const skipping = $derived(!isLast && canSkip);
 </script>
 
+<!-- The step dots and the primary action navigate; there is no second pair of arrow buttons. -->
 <div data-slot="ai-ask-user-question-footer" class={classes.footer()}>
-	<div class="flex items-center gap-1">
+	{#if canDiscard}
 		<Button
 			type="button"
-			squared
-			variant="outline"
+			variant="ghost"
+			color="neutral"
 			size="small"
-			label={previousLabel}
-			disabled={disabled || isFirst}
-			onclick={onPrevious}
-		>
-			{@render arrowLeftIcon({ size: 16 })}
-		</Button>
-		<Button
-			type="button"
-			squared
-			variant="outline"
-			size="small"
-			label={nextLabel}
-			disabled={disabled || isLast}
-			onclick={onNext}
-		>
-			{@render arrowRightIcon({ size: 16 })}
-		</Button>
-	</div>
-	<div class="flex min-w-0 items-center gap-2">
-		{#if canDiscard}
-			<Button
-				type="button"
-				variant="ghost"
-				color="neutral"
-				size="small"
-				loading={isDiscarding}
-				{disabled}
-				onclick={onDiscard}
-			>
-				{discardLabel}
-			</Button>
-		{/if}
-		<Button
-			type="button"
-			size="small"
-			prefix={isLast ? checkIcon : undefined}
-			suffix={isLast ? undefined : arrowRightIcon}
-			loading={isLast && isSubmitting}
+			loading={isDiscarding}
 			{disabled}
-			onclick={onPrimary}
+			onclick={onDiscard}
 		>
-			{isLast ? (isSubmitting ? submittingLabel : submitLabel) : nextLabel}
+			{discardLabel}
 		</Button>
-	</div>
+	{/if}
+	<Button
+		type="button"
+		size="small"
+		variant={skipping ? 'outline' : undefined}
+		color={skipping ? 'neutral' : undefined}
+		prefix={isLast ? checkIcon : undefined}
+		suffix={isLast ? undefined : arrowRightIcon}
+		loading={isLast && isSubmitting}
+		{disabled}
+		onclick={onPrimary}
+	>
+		{isLast ? (isSubmitting ? submittingLabel : submitLabel) : skipping ? skipLabel : nextLabel}
+	</Button>
 </div>

package/dist/components/AIAskUserQuestion/AIAskUserQuestionFooter.svelte.d.ts

@@ -1,18 +1,17 @@
 import { type AIAskUserQuestionThemeProps } from './aiAskUserQuestion.theme.js';
 type $$ComponentProps = {
-    isFirst: boolean;
     isLast: boolean;
+    /** The active question is optional and unanswered, so the primary action skips it. */
+    canSkip: boolean;
     disabled: boolean;
     isSubmitting: boolean;
     isDiscarding: boolean;
     canDiscard: boolean;
-    previousLabel: string;
     nextLabel: string;
+    skipLabel: string;
     submitLabel: string;
     submittingLabel: string;
     discardLabel: string;
-    onPrevious: () => void;
-    onNext: () => void;
     onPrimary: () => void;
     onDiscard: () => void;
     theme?: AIAskUserQuestionThemeProps;

package/dist/components/AIAskUserQuestion/AIAskUserQuestionHeader.svelte

@@ -39,22 +39,25 @@
 			<div class={classes.title()}>{title}</div>
 			{#if context}<div class={classes.description()}>{context}</div>{/if}
 		</div>
-		<div class={classes.progressGroup()}>
-			<span class={classes.progress()}>
-				{progressLabel(activeIndex + 1, questions.length)}
-			</span>
-			<div class={classes.steps()} aria-label={t.questions}>
-				{#each questions as question, index (question.id)}
-					<button
-						type="button"
-						aria-label={t.goToQuestion(index + 1)}
-						aria-current={index === activeIndex ? 'step' : undefined}
-						{disabled}
-						class={classes.step({ active: index === activeIndex })}
-						onclick={() => onSelect(index)}
-					></button>
-				{/each}
+		<!-- A lone question has nowhere to go: no pager. -->
+		{#if questions.length > 1}
+			<div class={classes.progressGroup()}>
+				<span class={classes.progress()}>
+					{progressLabel(activeIndex + 1, questions.length)}
+				</span>
+				<div class={classes.steps()} role="group" aria-label={t.questions}>
+					{#each questions as question, index (question.id)}
+						<button
+							type="button"
+							aria-label={t.goToQuestion(index + 1)}
+							aria-current={index === activeIndex ? 'step' : undefined}
+							{disabled}
+							class={classes.step({ active: index === activeIndex })}
+							onclick={() => onSelect(index)}
+						></button>
+					{/each}
+				</div>
 			</div>
-		</div>
+		{/if}
 	</div>
 </div>