@geoqiao/pi-ask 1.1.0

package/src/result.ts

@@ -0,0 +1,23 @@
+import {
+	CANCELLED_RESULT_TEXT,
+	ELABORATED_RESULT_TEXT,
+	SUBMITTED_RESULT_TEXT,
+} from "./constants/text.ts";
+import { formatElaborationLines, formatResultLines } from "./result-format.ts";
+import type { AskResult } from "./types.ts";
+
+export function renderResultText(result: AskResult): string {
+	if (result.error) {
+		return "Invalid input";
+	}
+	if (result.cancelled) {
+		return CANCELLED_RESULT_TEXT;
+	}
+	if (result.mode === "elaborate") {
+		const lines = formatElaborationLines(result, { mode: "render" });
+		return lines.join("\n") || ELABORATED_RESULT_TEXT;
+	}
+
+	const lines = formatResultLines(result, { mode: "render" });
+	return lines.join("\n") || SUBMITTED_RESULT_TEXT;
+}

package/src/schema.ts

@@ -0,0 +1,74 @@
+import { Type } from "typebox";
+
+export const AskOptionSchema = Type.Object({
+	value: Type.Optional(
+		Type.String({
+			description:
+				"Required machine-readable value returned for this option in the result",
+		})
+	),
+	label: Type.Optional(
+		Type.String({
+			description: "Required short visible option label shown in the list",
+		})
+	),
+	description: Type.Optional(
+		Type.String({
+			description: "Optional one-line explanation to help the user choose",
+		})
+	),
+	preview: Type.Optional(
+		Type.String({
+			description:
+				"Optional preview content shown in the dedicated preview pane for preview questions",
+		})
+	),
+});
+
+export const AskQuestionSchema = Type.Object({
+	id: Type.Optional(
+		Type.String({
+			description:
+				"Required stable question identifier used as the key in returned answers",
+		})
+	),
+	label: Type.Optional(
+		Type.String({
+			description: "Short tab label, e.g. Goal, Audience, Tone, Scope",
+		})
+	),
+	prompt: Type.Optional(
+		Type.String({
+			description:
+				"Required direct question shown to the user; ask about one decision at a time",
+		})
+	),
+	type: Type.Optional(
+		Type.String({
+			description:
+				"Question type: `single` means one answer is expected, `multi` means multiple answers could reasonably be selected, and `preview` means options need preview-pane detail. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.",
+		})
+	),
+	required: Type.Optional(
+		Type.Boolean({
+			description:
+				"Advisory only; marks the question as important but never blocks submission",
+		})
+	),
+	options: Type.Array(AskOptionSchema, {
+		description:
+			"Answer options; provide clear, distinct choices and do not add filler options",
+	}),
+});
+
+export const AskParamsSchema = Type.Object({
+	title: Type.Optional(
+		Type.String({
+			description:
+				"Optional short title shown above the clarification flow, e.g. README direction",
+		})
+	),
+	questions: Type.Array(AskQuestionSchema, {
+		description: "Questions to ask in the interactive clarification flow",
+	}),
+});

package/src/state/answers.ts

@@ -0,0 +1,251 @@
+import type {
+	AskDisplayOption,
+	AskResultAnswer,
+	AskSelectedOption,
+	AskStateAnswer,
+} from "../types.ts";
+
+export interface ExtraOptionNote {
+	label: string;
+	note: string;
+}
+
+export function emptyAnswer(): AskStateAnswer {
+	return { selected: [] };
+}
+
+export function cloneAnswer(answer: AskStateAnswer): AskStateAnswer {
+	return {
+		selected: answer.selected.map(cloneSelection),
+		customSelected: answer.customSelected,
+		customText: answer.customText,
+		note: answer.note,
+		optionNotes: answer.optionNotes ? { ...answer.optionNotes } : undefined,
+	};
+}
+
+export function cloneResultAnswer(answer: AskResultAnswer): AskResultAnswer {
+	return {
+		values: [...answer.values],
+		labels: [...answer.labels],
+		indices: [...answer.indices],
+		customText: answer.customText,
+		note: answer.note,
+		optionNotes: answer.optionNotes ? { ...answer.optionNotes } : undefined,
+	};
+}
+
+export function toggleSelection(
+	answer: AskStateAnswer,
+	option: AskDisplayOption,
+	index: number
+): AskStateAnswer {
+	const next = cloneAnswer(answer);
+	const selectedIndex = next.selected.findIndex(
+		(selection) => selection.value === option.value
+	);
+
+	if (selectedIndex >= 0) {
+		next.selected.splice(selectedIndex, 1);
+		return next;
+	}
+
+	next.selected.push({
+		value: option.value,
+		label: option.label,
+		index: index + 1,
+	});
+	return next;
+}
+
+export function setSingleSelection(
+	answer: AskStateAnswer,
+	option: AskDisplayOption,
+	index: number
+): AskStateAnswer {
+	return {
+		...emptyAnswer(),
+		note: answer.note,
+		optionNotes: answer.optionNotes ? { ...answer.optionNotes } : undefined,
+		selected: [
+			{
+				value: option.value,
+				label: option.label,
+				index: index + 1,
+			},
+		],
+	};
+}
+
+export function saveCustomText(
+	answer: AskStateAnswer,
+	rawValue: string,
+	mode: "single" | "multi"
+): AskStateAnswer {
+	const trimmed = rawValue.trim();
+	const next = cloneAnswer(answer);
+	if (mode === "single") {
+		next.selected = [];
+	}
+	if (!trimmed) {
+		next.customSelected = undefined;
+		next.customText = undefined;
+		return next;
+	}
+	next.customSelected = true;
+	next.customText = rawValue;
+	return next;
+}
+
+export function setCustomSelected(
+	answer: AskStateAnswer,
+	selected: boolean
+): AskStateAnswer {
+	const next = cloneAnswer(answer);
+	next.customSelected = selected || undefined;
+	return next;
+}
+
+export function saveQuestionNote(
+	answer: AskStateAnswer,
+	rawValue: string
+): AskStateAnswer {
+	const next = cloneAnswer(answer);
+	if (rawValue.trim()) {
+		next.note = rawValue;
+		return next;
+	}
+	next.note = undefined;
+	return next;
+}
+
+export function saveOptionNote(
+	answer: AskStateAnswer,
+	optionValue: string,
+	rawValue: string
+): AskStateAnswer {
+	const next = cloneAnswer(answer);
+	const optionNotes = { ...(next.optionNotes ?? {}) };
+	if (rawValue.trim()) {
+		optionNotes[optionValue] = rawValue;
+	} else {
+		delete optionNotes[optionValue];
+	}
+	next.optionNotes =
+		Object.keys(optionNotes).length > 0 ? optionNotes : undefined;
+	return next;
+}
+
+export function isAnswerEmpty(answer: AskStateAnswer): boolean {
+	return (
+		answer.selected.length === 0 &&
+		!answer.customText &&
+		!answer.note &&
+		(!answer.optionNotes || Object.keys(answer.optionNotes).length === 0)
+	);
+}
+
+export function isAnswerAnswered(answer?: AskStateAnswer): boolean {
+	if (!answer) {
+		return false;
+	}
+	return (
+		answer.selected.length > 0 ||
+		!!(answer.customSelected && answer.customText?.trim())
+	);
+}
+
+export function hasAnswerNotes(answer?: AskStateAnswer): boolean {
+	return !!(answer?.note || answer?.optionNotes);
+}
+
+export function isResultAnswerEmpty(answer: AskResultAnswer): boolean {
+	return (
+		answer.values.length === 0 &&
+		answer.labels.length === 0 &&
+		answer.indices.length === 0 &&
+		!answer.customText &&
+		!answer.note &&
+		(!answer.optionNotes || Object.keys(answer.optionNotes).length === 0)
+	);
+}
+
+export function isResultAnswerCommitted(answer: AskResultAnswer): boolean {
+	return (
+		answer.values.length > 0 ||
+		answer.labels.length > 0 ||
+		answer.indices.length > 0 ||
+		!!answer.customText
+	);
+}
+
+export function isCustomOnlyAnswer(answer: AskResultAnswer): boolean {
+	return answer.indices.length === 0 && !!answer.customText;
+}
+
+export function isOptionSelected(
+	answer: AskStateAnswer | undefined,
+	optionValue: string
+): boolean {
+	return !!answer?.selected.some(
+		(selection) => selection.value === optionValue
+	);
+}
+
+export function serializeAnswer(answer: AskStateAnswer): AskResultAnswer {
+	const selectedCustomText = answer.customSelected
+		? answer.customText
+		: undefined;
+	const values = [
+		...answer.selected.map((selection) => selection.value),
+		...(selectedCustomText ? [selectedCustomText] : []),
+	];
+	const labels = [
+		...answer.selected.map((selection) => selection.label),
+		...(selectedCustomText ? [selectedCustomText] : []),
+	];
+	const indices = answer.selected.map((selection) => selection.index);
+	const selectedNotes = answer.optionNotes
+		? Object.fromEntries(
+				answer.selected
+					.map((selection) => [
+						selection.value,
+						answer.optionNotes?.[selection.value],
+					])
+					.filter((entry): entry is [string, string] => !!entry[1])
+			)
+		: undefined;
+
+	return {
+		values,
+		labels,
+		indices,
+		customText: selectedCustomText,
+		note: answer.note,
+		optionNotes:
+			selectedNotes && Object.keys(selectedNotes).length > 0
+				? selectedNotes
+				: undefined,
+	};
+}
+
+export function getExtraOptionNotes(args: {
+	answer: AskStateAnswer;
+	questionOptions: Array<{ value: string; label: string }>;
+	selectedValues?: Iterable<string>;
+}): ExtraOptionNote[] {
+	const selectedValues = new Set(args.selectedValues ?? []);
+	return Object.entries(args.answer.optionNotes ?? {})
+		.filter(([value, note]) => !selectedValues.has(value) && Boolean(note))
+		.map(([value, note]) => {
+			const option = args.questionOptions.find(
+				(candidate) => candidate.value === value
+			);
+			return option ? { label: option.label, note } : undefined;
+		})
+		.filter((entry): entry is ExtraOptionNote => Boolean(entry));
+}
+
+function cloneSelection(selection: AskSelectedOption): AskSelectedOption {
+	return { ...selection };
+}

package/src/state/create.ts

@@ -0,0 +1,18 @@
+import type { AskParams } from "../types.ts";
+import { normalizeQuestions } from "./normalize.ts";
+import { createInitialState as createBaseState } from "./transitions.ts";
+
+interface CreateInitialStateOptions {
+	allowFreeform?: boolean;
+	presentSingleAsMulti?: boolean;
+}
+
+export function createInitialState(
+	params: AskParams,
+	options: CreateInitialStateOptions = {}
+) {
+	return createBaseState({
+		title: params.title,
+		questions: normalizeQuestions(params, options),
+	});
+}

package/src/state/editor.ts

@@ -0,0 +1,70 @@
+import type { AskState } from "../types.ts";
+import {
+	getAnswer,
+	getCurrentOption,
+	getCurrentQuestion,
+	getOptionNote,
+	getQuestionNote,
+	isSubmitTab,
+} from "./selectors.ts";
+import {
+	enterInputMode,
+	saveCustomAnswer,
+	saveNote,
+	submitCustomAnswer,
+} from "./transitions.ts";
+import { isEditingView } from "./view.ts";
+
+export function getEditorDraft(state: AskState): string {
+	if (state.view.kind === "input") {
+		return getAnswer(state, state.view.questionId)?.customText ?? "";
+	}
+	if (state.view.kind === "note") {
+		if (state.view.optionValue) {
+			return (
+				getOptionNote(state, state.view.questionId, state.view.optionValue) ??
+				""
+			);
+		}
+		return getQuestionNote(state, state.view.questionId) ?? "";
+	}
+	return "";
+}
+
+export function saveEditorDraft(state: AskState, text: string): AskState {
+	if (state.view.kind === "input") {
+		return saveCustomAnswer(state, text);
+	}
+	if (state.view.kind === "note") {
+		return saveNote(state, text);
+	}
+	return state;
+}
+
+export function submitEditorDraft(state: AskState, text: string): AskState {
+	if (state.view.kind === "input") {
+		return submitCustomAnswer(state, text);
+	}
+	if (state.view.kind === "note") {
+		return saveNote(state, text);
+	}
+	return state;
+}
+
+export function syncStateToSelection(state: AskState): AskState {
+	if (isEditingView(state) || isSubmitTab(state)) {
+		return state;
+	}
+
+	const question = getCurrentQuestion(state);
+	const option = getCurrentOption(state);
+	if (!(question && option?.isCustomOption)) {
+		return state;
+	}
+
+	if (getAnswer(state, question.id)?.customText?.trim()) {
+		return state;
+	}
+
+	return enterInputMode(state, question.id);
+}

package/src/state/navigation.ts

@@ -0,0 +1,86 @@
+import { clamp } from "../math.ts";
+import type { AskState } from "../types.ts";
+import {
+	getCurrentQuestion,
+	getRenderableOptions,
+	isSubmitTab,
+} from "./selectors.ts";
+import { isEditingView, navigateView, submitView } from "./view.ts";
+
+const SUBMIT_ACTION_COUNT = 3;
+
+export function createInitialState(params: {
+	title?: string;
+	questions: AskState["questions"];
+}): AskState {
+	return {
+		title: params.title,
+		questions: params.questions,
+		activeTabIndex: 0,
+		activeOptionIndex: 0,
+		activeSubmitActionIndex: 0,
+		view: navigateView(),
+		answers: {},
+		completed: false,
+		cancelled: false,
+		mode: "submit",
+	};
+}
+
+export function moveTab(state: AskState, delta: number): AskState {
+	const normalizedDelta = delta < 0 ? -1 : 1;
+	const totalTabs = state.questions.length + 1;
+	const activeTabIndex =
+		(state.activeTabIndex + normalizedDelta + totalTabs) % totalTabs;
+	return {
+		...state,
+		activeTabIndex,
+		activeOptionIndex: 0,
+		activeSubmitActionIndex: 0,
+		view:
+			activeTabIndex >= state.questions.length ? submitView() : navigateView(),
+	};
+}
+
+export function moveOption(state: AskState, delta: number): AskState {
+	const normalizedDelta = delta < 0 ? -1 : 1;
+	if (isSubmitTab(state)) {
+		return {
+			...state,
+			activeSubmitActionIndex: clamp(
+				state.activeSubmitActionIndex + normalizedDelta,
+				0,
+				SUBMIT_ACTION_COUNT - 1
+			),
+		};
+	}
+
+	const options = getRenderableOptions(getCurrentQuestion(state));
+	return {
+		...state,
+		activeOptionIndex: clamp(
+			state.activeOptionIndex + normalizedDelta,
+			0,
+			Math.max(0, options.length - 1)
+		),
+	};
+}
+
+export function cancelFlow(state: AskState): AskState {
+	if (isEditingView(state)) {
+		return {
+			...state,
+			view: isSubmitTab(state) ? submitView() : navigateView(),
+		};
+	}
+	return {
+		...state,
+		cancelled: true,
+		completed: true,
+	};
+}
+
+export function dismissFlow(state: AskState): AskState {
+	const nextState = cancelFlow(state);
+	return nextState.completed ? nextState : cancelFlow(nextState);
+}