pi-roundtable 0.19.2 → 0.20.0

package/src/core/discord/owner-card-questionnaire.ts

@@ -0,0 +1,281 @@
+import {
+	ActionRowBuilder,
+	AttachmentBuilder,
+	ButtonBuilder,
+	ButtonStyle,
+	ContainerBuilder,
+	LabelBuilder,
+	MessageFlags,
+	ModalBuilder,
+	StringSelectMenuBuilder,
+	TextDisplayBuilder,
+	TextInputBuilder,
+	TextInputStyle,
+} from "discord.js";
+import { messages } from "../i18n/index.ts";
+import {
+	type OwnerQuestion,
+	QUESTIONNAIRE_LIMITS,
+	type Questionnaire,
+	type QuestionnaireAnswer,
+} from "../interactions/questionnaire.ts";
+import { CARD_PREFIX } from "./owner-card-rows.ts";
+import type { CardPayload } from "./owner-card-types.ts";
+import { ephemeralPanel, ownerPanels, plain } from "./owner-panel.ts";
+import { clip } from "./utf16.ts";
+
+/** What has been chosen and written on a questionnaire card so far; one per card, shared by all who may answer. */
+export interface Draft {
+	choices: string[][];
+	texts: (string | undefined)[];
+	note?: string;
+}
+
+/** A card's questionnaire with its draft. */
+export interface QuestionnaireForm {
+	questionnaire: Questionnaire;
+	draft: Draft;
+}
+
+export const newDraft = (questions: number): Draft => ({
+	choices: Array.from({ length: questions }, () => []),
+	texts: Array.from({ length: questions }, () => undefined),
+});
+
+const cut = (text: string, max: number) => clip(text, max, true);
+
+const text = (content: string) => new TextDisplayBuilder().setContent(content);
+
+/** Whether the question takes text of its own: it has no options, or allows an answer besides them. */
+export const takesText = (question: OwnerQuestion) =>
+	question.allowOther || question.options.length === 0;
+
+const given = (draft: Draft, i: number) =>
+	(draft.choices[i]?.length ?? 0) > 0 || draft.texts[i] !== undefined;
+
+export const answeredCount = (draft: Draft) =>
+	draft.choices.filter((_, i) => given(draft, i)).length;
+
+/** The draft as an answer: a blank question is undefined, a blank note is left out. */
+export function answerOf(draft: Draft): QuestionnaireAnswer {
+	const note = draft.note?.trim();
+	return {
+		answers: draft.choices.map((choices, i) => {
+			const own = draft.texts[i]?.trim();
+			return choices.length > 0 || own
+				? { choices: [...choices], ...(own ? { text: own } : {}) }
+				: undefined;
+		}),
+		...(note ? { note } : {}),
+	};
+}
+
+/** One question's draft as a line: what is chosen and written, or that it is not answered. */
+function lineOf(draft: Draft, i: number): string {
+	if (!given(draft, i)) return messages().cardUnanswered;
+	const own = draft.texts[i];
+	return messages().cardAnswered([
+		...(draft.choices[i] ?? []).map(plain),
+		...(own !== undefined ? [messages().cardQuote(plain(own))] : []),
+	]);
+}
+
+/** A question's name: its header, else its text cut short. */
+const nameOf = (question: OwnerQuestion) =>
+	plain(question.header ?? cut(question.question, 80));
+
+function select(
+	id: string,
+	i: number,
+	question: OwnerQuestion,
+	draft: Draft,
+	disabled: boolean,
+) {
+	const chosen = draft.choices[i] ?? [];
+	return new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(
+		new StringSelectMenuBuilder()
+			.setCustomId(`${CARD_PREFIX}${id}:qpick:${i}`)
+			.setPlaceholder(
+				question.multi
+					? messages().cardPickManyPlaceholder
+					: messages().cardPickOnePlaceholder,
+			)
+			.setMinValues(0)
+			.setMaxValues(question.multi ? question.options.length : 1)
+			.addOptions(
+				question.options.map((option, n) => ({
+					label: clip(option.label, 100),
+					value: String(n),
+					default: chosen.includes(option.label),
+					...(option.description
+						? { description: clip(option.description, 100) }
+						: {}),
+				})),
+			)
+			.setDisabled(disabled),
+	);
+}
+
+function buttons(id: string, form: QuestionnaireForm, disabled: boolean) {
+	const { questions } = form.questionnaire;
+	const row = new ActionRowBuilder<ButtonBuilder>();
+	const button = (action: string, label: string, style: ButtonStyle) =>
+		new ButtonBuilder()
+			.setCustomId(`${CARD_PREFIX}${id}:${action}`)
+			.setLabel(label)
+			.setStyle(style)
+			.setDisabled(disabled);
+	row.addComponents(
+		button("submit", messages().cardSubmitLabel, ButtonStyle.Primary),
+		button("notes", messages().cardWriteLabel, ButtonStyle.Secondary),
+	);
+	if (questions.some((q) => q.options.some((o) => o.preview !== undefined)))
+		row.addComponents(
+			button("previews", messages().cardPreviewsLabel, ButtonStyle.Secondary),
+		);
+	return row.components.length > 0 ? [row] : [];
+}
+
+/**
+ * A questionnaire card as one message. Discord lets a container hold ten children, so the
+ * heading, the four questions' texts and menus, and the button row fill it; the footer is a
+ * top-level text beneath it. Open, each question shows its text and menu; ended, its name and
+ * what was chosen, with the controls disabled.
+ */
+export function questionnaireCard(args: {
+	id: string;
+	title: string;
+	/** The audience's note, shown with the heading; empty for none. */
+	note: string;
+	form: QuestionnaireForm;
+	disabled: boolean;
+	/** How the card ended, shown as its footer; ignored while it is open. */
+	footer: string;
+}): CardPayload {
+	const { id, form, disabled } = args;
+	const { draft } = form;
+	const { questions } = form.questionnaire;
+	const container = new ContainerBuilder().addTextDisplayComponents(
+		text([`### ${args.title}`, ...(args.note ? [args.note] : [])].join("\n")),
+	);
+	for (const [i, question] of questions.entries()) {
+		const heading =
+			questions.length === 1
+				? undefined
+				: `**${i + 1}${question.header ? ` · ${plain(question.header)}` : ""}**`;
+		const body = disabled
+			? `${heading ?? `**${nameOf(question)}**`}\n${lineOf(draft, i)}`
+			: [heading, question.question].filter(Boolean).join("\n");
+		container.addTextDisplayComponents(text(body));
+		if (question.options.length > 0)
+			container.addActionRowComponents(
+				select(id, i, question, draft, disabled),
+			);
+	}
+	container.addActionRowComponents(...buttons(id, form, disabled));
+	const footer = disabled
+		? args.footer
+		: messages().cardQuestionnaireFooter(
+				answeredCount(draft),
+				questions.length,
+			);
+	return {
+		components: [container, ...(footer ? [text(`-# ${footer}`)] : [])],
+		flags: MessageFlags.IsComponentsV2,
+		allowedMentions: { parse: [] },
+	};
+}
+
+/** The form for what the menus cannot take: each question's own answer, and the note. */
+export function questionnaireModal(id: string, form: QuestionnaireForm) {
+	const { questions } = form.questionnaire;
+	const labelled = (
+		label: string,
+		field: string,
+		value: string | undefined,
+		description?: string,
+	) => {
+		const input = new TextInputBuilder()
+			.setCustomId(field)
+			.setStyle(TextInputStyle.Paragraph)
+			.setRequired(false)
+			.setMaxLength(QUESTIONNAIRE_LIMITS.answerChars);
+		// Discord refuses an empty prefill and an empty description.
+		if (value) input.setValue(value);
+		const labelled = new LabelBuilder()
+			.setLabel(cut(label, 45))
+			.setTextInputComponent(input);
+		return description
+			? labelled.setDescription(cut(description, 100))
+			: labelled;
+	};
+	const modal = new ModalBuilder()
+		.setCustomId(`${CARD_PREFIX}${id}:qtext`)
+		.setTitle(messages().cardModalTitle);
+	for (const [i, question] of questions.entries()) {
+		if (!takesText(question)) continue;
+		const label =
+			questions.length === 1
+				? messages().cardModalField
+				: `${i + 1}. ${question.header ?? messages().cardQuestionName(i + 1)}`;
+		const field = labelled(
+			label,
+			`t${i}`,
+			form.draft.texts[i],
+			question.question,
+		);
+		modal.addLabelComponents(field);
+	}
+	return modal.addLabelComponents(
+		labelled(messages().cardNoteField, "note", form.draft.note),
+	);
+}
+
+/** The text fields a submitted form carries, by question index; `note` is the note. */
+export function formFields(
+	form: QuestionnaireForm,
+	read: (field: string) => string,
+): { texts: Map<number, string>; note: string } {
+	const texts = new Map<number, string>();
+	for (const [i, question] of form.questionnaire.questions.entries())
+		if (takesText(question)) texts.set(i, read(`t${i}`));
+	return { texts, note: read("note") };
+}
+
+/** Every option's preview, question by question, as an ephemeral reply and follow-ups; a file when a preview holds a code fence. */
+export function previewReplies(questionnaire: Questionnaire) {
+	const sections = questionnaire.questions.flatMap((question, i) => {
+		const shown = question.options.filter((o) => o.preview !== undefined);
+		if (shown.length === 0) return [];
+		return [
+			`**${i + 1}. ${nameOf(question)}**`,
+			...shown.map(
+				(o) => `**${plain(o.label)}**\n\`\`\`\n${o.preview}\n\`\`\``,
+			),
+		];
+	});
+	const raw = questionnaire.questions
+		.flatMap((question, i) =>
+			question.options
+				.filter((o) => o.preview !== undefined)
+				.map((o) => `## ${i + 1}. ${o.label}\n\n${o.preview}`),
+		)
+		.join("\n\n");
+	if (raw.includes("```"))
+		return [
+			{
+				content: messages().cardPreviewsFile,
+				files: [
+					new AttachmentBuilder(Buffer.from(raw, "utf8"), {
+						name: "previews.md",
+					}),
+				],
+				flags: MessageFlags.Ephemeral as const,
+				allowedMentions: { parse: [] as never[] },
+			},
+		];
+	return ownerPanels({
+		title: messages().cardPreviewsLabel,
+		sections,
+	}).map(ephemeralPanel);
+}

package/src/core/discord/owner-card-rows.ts

@@ -15,6 +15,7 @@ import {
 	withdrawalNote,
 } from "../interactions/prompts.ts";
 import { type ownerPanel, plain } from "./owner-panel.ts";
+import { clip } from "./utf16.ts";
 
 /** The prefix of every card control's custom id. */
 export const CARD_PREFIX = "roundtable:card:";
@@ -41,39 +42,60 @@ export function askRows(
 					.setDisabled(disabled),
 			),
 		];
-	// Discord menus take 25 options; "Other…" takes the last place when the options fill it.
-	const options = question.options
-		.slice(0, question.allowOther ? 24 : 25)
-		.map((option, i) => ({
-			label: option.label.slice(0, 100),
+	// Discord menus take 25 options. With 24 or fewer, "Other…" is the last entry; with 25 it
+	// would push one out, so the menu keeps all of them and "Answer…" opens the form instead.
+	const roomForOther = question.allowOther && question.options.length < 25;
+	const options: { label: string; value: string; description?: string }[] =
+		question.options.map((option, i) => ({
+			label: clip(option.label, 100),
 			value: String(i),
 			...(option.description
-				? { description: option.description.slice(0, 100) }
+				? { description: clip(option.description, 100) }
 				: {}),
 		}));
-	if (question.allowOther)
+	if (roomForOther)
 		options.push({
 			label: messages().cardOtherLabel,
 			value: OTHER,
 			description: messages().cardOtherDescription,
 		});
+	const menu = new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(
+		new StringSelectMenuBuilder()
+			.setCustomId(`${CARD_PREFIX}${id}:pick`)
+			.setPlaceholder(
+				question.multi
+					? messages().cardPickManyPlaceholder
+					: messages().cardPickOnePlaceholder,
+			)
+			.setMinValues(1)
+			.setMaxValues(question.multi ? options.length : 1)
+			.addOptions(options)
+			.setDisabled(disabled),
+	);
+	if (!question.allowOther || roomForOther) return [menu];
 	return [
-		new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(
-			new StringSelectMenuBuilder()
-				.setCustomId(`${CARD_PREFIX}${id}:pick`)
-				.setPlaceholder(
-					question.multi
-						? messages().cardPickManyPlaceholder
-						: messages().cardPickOnePlaceholder,
-				)
-				.setMinValues(1)
-				.setMaxValues(question.multi ? options.length : 1)
-				.addOptions(options)
+		menu,
+		new ActionRowBuilder<ButtonBuilder>().addComponents(
+			new ButtonBuilder()
+				.setCustomId(`${CARD_PREFIX}${id}:write`)
+				.setLabel(messages().cardAnswerLabel)
+				.setStyle(ButtonStyle.Secondary)
 				.setDisabled(disabled),
 		),
 	];
 }
 
+/** The Previews button of a single-question card: it shows the options' previews and answers nothing. */
+export function previewsRow(id: string, disabled: boolean) {
+	return new ActionRowBuilder<ButtonBuilder>().addComponents(
+		new ButtonBuilder()
+			.setCustomId(`${CARD_PREFIX}${id}:previews`)
+			.setLabel(messages().cardPreviewsLabel)
+			.setStyle(ButtonStyle.Secondary)
+			.setDisabled(disabled),
+	);
+}
+
 export function answerModal(id: string): ModalBuilder {
 	return new ModalBuilder()
 		.setCustomId(`${CARD_PREFIX}${id}:text`)

package/src/core/discord/owner-card-types.ts

@@ -1,7 +1,13 @@
 import type { TextDisplayBuilder } from "discord.js";
-import type { ApprovedBy, OwnerQuestion } from "../interactions/prompts.ts";
+import type {
+	ApprovedBy,
+	OwnerQuestion,
+	PromptWait,
+} from "../interactions/prompts.ts";
+import type { Questionnaire } from "../interactions/questionnaire.ts";
 import type { Audience } from "./card-audience.ts";
 import type { DiscordUser } from "./discord-owners.ts";
+import type { QuestionnaireForm } from "./owner-card-questionnaire.ts";
 import type { Rows } from "./owner-card-rows.ts";
 import type { ownerPanel } from "./owner-panel.ts";
 
@@ -54,10 +60,12 @@ export interface Answerer {
 
 /** One open card: how it looks, and how it ends. */
 export interface OpenCard {
-	title: string;
-	sections: string[];
-	/** The card's controls, disabled once it has ended. */
-	rows(disabled: boolean): Rows;
+	/** The card as it looks now: open, or ended with `footer` and its controls disabled. */
+	view(footer: string, disabled?: boolean): CardPayload;
+	/** Restarts the grace period of a turn that waits on the card; a draft edit is someone at work on it. */
+	touch(): void;
+	/** Whether the card is still open: not answered, stopped or withdrawn. */
+	isOpen(): boolean;
 	/**
 	 * Ends the card with its answer; the answering interaction shows the outcome. A card whose
 	 * turn stopped waiting starts a turn with the answer instead. False when the card had ended
@@ -65,6 +73,10 @@ export interface OpenCard {
 	 */
 	end(value: unknown, by: Answerer): boolean;
 	question?: OwnerQuestion;
+	/** A questionnaire card's questions and its shared draft. */
+	form?: QuestionnaireForm;
+	/** The questions whose previews the Previews button shows, on a card that is not a questionnaire card. */
+	previews?: Questionnaire;
 	/** Options chosen together with "Other…", kept while its form is open. */
 	picked?: string[];
 	/** Posted in a thread, so it leads with the mention of who may answer. */
@@ -72,3 +84,40 @@ export interface OpenCard {
 	/** Who may answer, and what to tell someone else who presses it. */
 	audience: Audience;
 }
+
+/** What `#post` needs to post one card; `T` is what the card resolves with. */
+export interface CardSpec<T> {
+	audience: Audience;
+	title: string;
+	sections: string[];
+	/** The text behind the card's copy button, kept under the card's id. */
+	copy?: string;
+	/** Closes the card, also after its turn stopped waiting, when it aborts; see `ApprovalOptions.supersede`. */
+	supersede?: AbortSignal;
+	question?: OwnerQuestion;
+	form?: QuestionnaireForm;
+	previews?: Questionnaire;
+	/** Draws the card itself, as a questionnaire does; without it the card is the title, sections and rows. */
+	build?(id: string, footer: string, disabled: boolean): CardPayload;
+	rows?(id: string, disabled: boolean): Rows;
+	footer: string;
+	wait?: {
+		pending: T;
+		late(
+			value: unknown,
+			by: Answerer,
+			prompt: string,
+		): ReturnType<PromptWait["late"]>;
+	};
+	/** Hears who approved the card, before it resolves approved in its turn. */
+	approved?(by: Answerer, prompt: string): void;
+}
+
+/** Posts a card and resolves with its answer; see `OwnerCards`. */
+export type PostCard = <T>(
+	channelId: string,
+	signal: AbortSignal | undefined,
+	unposted: T,
+	cancelled: T,
+	card: CardSpec<T>,
+) => Promise<T>;

package/src/core/discord/owner-cards-fixture.ts

@@ -12,9 +12,12 @@ export const json = (payload: CardPayload | undefined) =>
 export function fakeChannel(thread = false) {
 	const sent: CardPayload[] = [];
 	const edits: CardPayload[] = [];
+	/** The index in `sent` of the card each edit changed. */
+	const edited: number[] = [];
 	return {
 		sent,
 		edits,
+		edited,
 		/** The id of the latest card sent. */
 		cardId: () =>
 			json(sent.at(-1)).match(new RegExp(`${CARD_PREFIX}([0-9a-f-]+):`))?.[1] ??
@@ -23,9 +26,11 @@ export function fakeChannel(thread = false) {
 			thread,
 			send: async (payload: CardPayload) => {
 				sent.push(payload);
+				const index = sent.length - 1;
 				return {
 					edit: async (change: CardPayload) => {
 						edits.push(change);
+						edited.push(index);
 					},
 				};
 			},
@@ -44,6 +49,10 @@ export function press(
 		roles?: string[];
 		values?: string[];
 		text?: string;
+		/** A form's fields by custom id; when given, a field not named reads empty. */
+		fields?: Record<string, string>;
+		/** Holds `deferUpdate` until it resolves, so the card can change while the press is in flight. */
+		gate?: Promise<void>;
 	} = {},
 ) {
 	const replies: string[] = [];
@@ -51,6 +60,10 @@ export function press(
 	const replied: { files?: unknown[]; flags?: unknown }[] = [];
 	const updates: CardPayload[] = [];
 	const modals: unknown[] = [];
+	/** What the press answered after deferring: edits of the card, and follow-ups. */
+	const edited: CardPayload[] = [];
+	const followUps: { content?: string; flags?: unknown }[] = [];
+	const deferred: string[] = [];
 	// SAFETY: the cards read only these members of an interaction.
 	const interaction = {
 		isButton: () => kind === "button",
@@ -66,7 +79,10 @@ export function press(
 			roles: { cache: new Map((options.roles ?? []).map((r) => [r, r])) },
 		},
 		values: options.values ?? [],
-		fields: { getTextInputValue: () => options.text ?? "" },
+		fields: {
+			getTextInputValue: (name: string) =>
+				options.fields ? (options.fields[name] ?? "") : (options.text ?? ""),
+		},
 		reply: async (answer: {
 			content: string;
 			files?: unknown[];
@@ -81,9 +97,27 @@ export function press(
 		showModal: async (modal: unknown) => {
 			modals.push(modal);
 		},
-		deferUpdate: async () => undefined,
+		deferUpdate: async () => {
+			await options.gate;
+			deferred.push("update");
+		},
+		editReply: async (payload: CardPayload) => {
+			edited.push(payload);
+		},
+		followUp: async (answer: { content?: string; flags?: unknown }) => {
+			followUps.push(answer);
+		},
 	} as unknown as Interaction;
-	return { interaction, replies, replied, updates, modals };
+	return {
+		interaction,
+		replies,
+		replied,
+		updates,
+		modals,
+		edited,
+		followUps,
+		deferred,
+	};
 }
 
 /** Lets a posted card settle. */