@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/discord/components/settings-editor/from-declaration-values.ts

@@ -0,0 +1,240 @@
+import type {
+	ControlShape,
+	DeclarationControl,
+} from "@/discord/components/settings-editor/from-declaration-controls";
+import {
+	isToggledOn,
+	secretStateKey,
+	storedIds,
+} from "@/discord/components/settings-editor/from-declaration-stored";
+import type { DeclarationSubject } from "@/discord/components/settings-editor/from-declaration-subject";
+import type { SettingsEditorGroupMemberSubmission } from "@/discord/components/settings-editor/settings-editor-field-modal";
+import {
+	pickedFieldValue,
+	textFieldValue,
+} from "@/discord/components/settings-editor/settings-editor-field-values";
+import {
+	isPickerField,
+	type SettingsEditorFieldValue,
+} from "@/discord/components/settings-editor/settings-editor-fields";
+import type { TranslateKey } from "@/i18n/translator";
+import { formatDuration } from "@/settings/duration";
+import { SETTINGS_MESSAGES } from "@/settings/messages";
+
+/** A decimal number as typed: optional sign, digits with an optional fraction, optional exponent. */
+const DECIMAL_PATTERN = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
+
+/** Separates the items of a list typed one per line. */
+const LINE_BREAK = /\r?\n/;
+
+/**
+ * What the modal of a control opens on: the stored value as text for a typed
+ * control, whether a secret is set (never its value), the picked ids for a
+ * picker, minus the entities the guild no longer has, which the text then
+ * reports as unavailable.
+ *
+ * @param params.control - the control being opened.
+ * @param params.subject - the screen's current subject.
+ * @param params.translate - translates the texts shown in place of a value.
+ * @returns the control's prefill.
+ */
+export function controlValue(params: {
+	control: DeclarationControl;
+	subject: DeclarationSubject;
+	translate: TranslateKey;
+}): SettingsEditorFieldValue {
+	const { control, subject, translate } = params;
+	const value = subject.values[control.fieldKey];
+	const { shape } = control;
+	switch (shape.kind) {
+		case "text":
+			return textFieldValue(typeof value === "string" ? value : null);
+		case "number":
+			return textFieldValue(typeof value === "number" ? String(value) : null);
+		case "duration":
+			return textFieldValue(typeof value === "number" ? formatDuration(value) : null);
+		case "secret":
+			return textFieldValue(translate(secretStateKey(value)));
+		case "lines":
+			return textFieldValue(Array.isArray(value) && value.length > 0 ? value.join("\n") : null);
+		case "boolean":
+			return pickedFieldValue(typeof value === "boolean" ? [String(value)] : []);
+		case "single":
+		case "many":
+			return pickedValue({ control, subject, translate });
+		case "toggles":
+			return pickedFieldValue(shape.keys.filter((key) => isToggledOn({ value, key })));
+		case "search":
+			return pickedFieldValue(
+				typeof value === "string" || typeof value === "number" ? [String(value)] : [],
+			);
+		case "other":
+			// Opens empty: the value it would repeat is already picked in the select beside it.
+			return textFieldValue(null);
+		default:
+			return shape satisfies never;
+	}
+}
+
+/** The picked ids the guild still has, with a notice when any stored one is gone. */
+function pickedValue(params: {
+	control: DeclarationControl;
+	subject: DeclarationSubject;
+	translate: TranslateKey;
+}): SettingsEditorFieldValue {
+	const { control, subject, translate } = params;
+	const stored = storedIds(subject.values[control.fieldKey]);
+	const missing = subject.unavailable[control.fieldKey] ?? [];
+	const picked = pickedFieldValue(stored.filter((id) => !missing.includes(id)));
+	if (missing.length === 0) {
+		return picked;
+	}
+	return { ...picked, text: translate(SETTINGS_MESSAGES.valueUnavailable) };
+}
+
+/**
+ * Whether a submission leaves a control as its modal opened: the same picked
+ * ids in the same order for a picker (whatever notice its text carries), the
+ * same text for a typed control (an empty box and no value alike).
+ *
+ * @param params.control - the control submitted.
+ * @param params.submission - what it came back with.
+ * @param params.current - what its modal opened on.
+ * @returns `true` when nothing was changed.
+ */
+export function isUnchanged(params: {
+	control: DeclarationControl;
+	submission: SettingsEditorGroupMemberSubmission;
+	current: SettingsEditorFieldValue;
+}): boolean {
+	const { control, submission, current } = params;
+	if (isPickerField(control.entry)) {
+		const ids = submission.ids ?? [];
+		return (
+			ids.length === current.picked.length && ids.every((id, index) => current.picked[index] === id)
+		);
+	}
+	return (submission.value ?? "") === (current.text ?? "");
+}
+
+/**
+ * Add what one control submitted to a settings patch, in the form the
+ * settings service takes: typed text converted to the value it denotes and
+ * left as text when it denotes none (the service then refuses it with the same
+ * issue as any surface), `null` for a cleared control, and a toggles select
+ * merged into the full record of its field.
+ *
+ * @param params.control - the control submitted.
+ * @param params.submission - what it came back with.
+ * @param params.subject - the screen's current subject, for the toggles the
+ * select does not show.
+ * @param params.patch - the patch built so far.
+ * @returns the patch with the control's value.
+ */
+export function withSubmission(params: {
+	control: DeclarationControl;
+	submission: SettingsEditorGroupMemberSubmission;
+	subject: DeclarationSubject;
+	patch: Readonly<Record<string, unknown>>;
+}): Readonly<Record<string, unknown>> {
+	const { control, submission, subject, patch } = params;
+	const { fieldKey, shape } = control;
+	const current = Object.hasOwn(patch, fieldKey) ? patch[fieldKey] : subject.values[fieldKey];
+	return { ...patch, [fieldKey]: submittedValue({ shape, submission, current }) };
+}
+
+/** What one control submitted, as the settings service takes it; `current` is its field's value so far. */
+function submittedValue(params: {
+	shape: ControlShape;
+	submission: SettingsEditorGroupMemberSubmission;
+	current: unknown;
+}): unknown {
+	const { shape, submission } = params;
+	const { value, ids } = submission;
+	switch (shape.kind) {
+		case "text":
+		case "duration":
+		case "secret":
+			return value;
+		case "number":
+			return value === null ? null : typedNumber(value);
+		case "lines":
+			return value === null ? null : typedLines({ text: value, numeric: shape.numeric });
+		case "boolean":
+			return ids === null || ids.length === 0 ? null : pickedBoolean(ids[0]);
+		case "single":
+			return ids === null || ids.length === 0 ? null : singleId(ids);
+		case "many":
+			return ids === null ? null : [...ids];
+		case "toggles":
+			return { ...toggleRecord(params.current), ...pickedToggles({ keys: shape.keys, ids }) };
+		case "search":
+			if (ids === null || ids.length === 0) {
+				return null;
+			}
+			return shape.numeric ? singleNumber(ids) : singleId(ids);
+		case "other":
+			if (value === null) {
+				return null;
+			}
+			return shape.numeric ? typedNumber(value) : value;
+		default:
+			return shape satisfies never;
+	}
+}
+
+/** The one number picked, from its option's value; anything else is left for the service to refuse. */
+function singleNumber(ids: readonly string[]): unknown {
+	const picked = singleId(ids);
+	return typeof picked === "string" ? typedNumber(picked) : picked;
+}
+
+/** A toggles value as a record, or an empty one when the field holds none. */
+function toggleRecord(value: unknown): Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null ? { ...value } : {};
+}
+
+/** Each key of one toggles select, on when picked. */
+function pickedToggles(params: {
+	keys: readonly string[];
+	ids: readonly string[] | null;
+}): Record<string, boolean> {
+	const picked = params.ids ?? [];
+	// A picked id the select does not offer is kept, for the service to refuse.
+	const keys = [...params.keys, ...picked.filter((id) => !params.keys.includes(id))];
+	return Object.fromEntries(keys.map((key) => [key, picked.includes(key)]));
+}
+
+/** The number typed, or the text itself when it is not one. */
+function typedNumber(text: string): number | string {
+	const trimmed = text.trim();
+	return DECIMAL_PATTERN.test(trimmed) ? Number(trimmed) : text;
+}
+
+/** Each non-empty trimmed line as one item; `null` when no line holds one. */
+function typedLines(params: { text: string; numeric: boolean }): unknown[] | null {
+	const lines = params.text
+		.split(LINE_BREAK)
+		.map((line) => line.trim())
+		.filter((line) => line !== "");
+	if (lines.length === 0) {
+		return null;
+	}
+	return params.numeric ? lines.map(typedNumber) : lines;
+}
+
+/** `true` and `false` from their options; any other id is left for the service to refuse. */
+function pickedBoolean(id: string | undefined): boolean | string | undefined {
+	if (id === String(true)) {
+		return true;
+	}
+	if (id === String(false)) {
+		return false;
+	}
+	return id;
+}
+
+/** The one id a single picker took; several are left as a list for the service to refuse. */
+function singleId(ids: readonly string[]): string | readonly string[] {
+	return ids.length === 1 && ids[0] !== undefined ? ids[0] : ids;
+}

package/src/discord/components/settings-editor/from-declaration.ts

@@ -0,0 +1,218 @@
+import {
+	type DeclarationControl,
+	declarationControls,
+	isFreeEntry,
+	type SearchOptions,
+} from "@/discord/components/settings-editor/from-declaration-controls";
+import { controlDisplay } from "@/discord/components/settings-editor/from-declaration-display";
+import { layoutDeclaration } from "@/discord/components/settings-editor/from-declaration-layout";
+import { loadSearchOptions } from "@/discord/components/settings-editor/from-declaration-search";
+import {
+	type DeclarationSubject,
+	loadDeclarationSubject,
+} from "@/discord/components/settings-editor/from-declaration-subject";
+import {
+	controlValue,
+	isUnchanged,
+	withSubmission,
+} from "@/discord/components/settings-editor/from-declaration-values";
+import type {
+	SettingsEditorOptions,
+	SettingsEditorWrite,
+} from "@/discord/components/settings-editor/mount-settings-editor";
+import type {
+	SettingsEditorGroupMemberSubmission,
+	SettingsEditorGroupSubmission,
+	SettingsEditorSubmission,
+} from "@/discord/components/settings-editor/settings-editor-field-modal";
+import { NotFoundError } from "@/errors/business-error";
+import type { Locale } from "@/i18n/locale";
+import type { TranslateKey, Translator } from "@/i18n/translator";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import { displayOrder } from "@/settings/field-order";
+import type { RequestContext, SettingsService } from "@/settings/settings-service";
+
+/** What the adapter hands `mountSettingsEditor`; the caller adds its own ids, chrome, clock and logger. */
+type DeclarationEditorOptions = Pick<
+	SettingsEditorOptions<unknown, never, string>,
+	"fields" | "levels" | "initial" | "currentValue" | "displayValue" | "save" | "saveGroup" | "reset"
+>;
+
+/** A settings patch, keyed by field. */
+type Patch = Readonly<Record<string, unknown>>;
+
+/** What every hook of one screen reads and writes through. */
+interface AdapterScope {
+	readonly declaration: SettingsDeclaration;
+	readonly service: SettingsService;
+	readonly ctx: RequestContext;
+	readonly translate: TranslateKey;
+	readonly controls: ReadonlyMap<string, DeclarationControl>;
+	readonly groups: ReadonlyMap<string, readonly DeclarationControl[]>;
+}
+
+/**
+ * Build the settings-editor options of a declaration for one guild: its
+ * fields and levels, the subject it opens on, and the hooks that read and
+ * write through the settings service. The caller spreads the result into
+ * `mountSettingsEditor` with its own `ids`, `chrome`, `clock` and `logger`.
+ *
+ * Every write goes through `service.set` as the administrator, so the screen
+ * accepts and refuses exactly what every other surface does; a group's modal
+ * is one write carrying only the members the administrator changed.
+ *
+ * A searchable field (FR-026a) is a select of the first 25 results of its
+ * search for an empty query, read when the screen opens, and shows its
+ * search's label as its current value. A non-strict one also gets an "Other
+ * value" text entry in the same modal: a value typed there replaces the pick
+ * and is validated on save like any other. A field whose search offered
+ * nothing is typed instead.
+ *
+ * @param declaration - the module's settings declaration.
+ * @param service - the settings service the screen reads and writes through.
+ * @param context - the guild, the administrator, their locale and the
+ * translator of the texts shown in place of a value.
+ * @returns the editor options, the initial subject read from the service.
+ * @throws SettingsDeclarationError when a list holds an item kind lists cannot hold.
+ */
+export async function settingsEditorFromDeclaration<D extends SettingsDeclaration>(
+	declaration: D,
+	service: SettingsService,
+	context: {
+		readonly guildId: string;
+		readonly userId: string;
+		readonly locale: Locale;
+		readonly translator: Translator;
+	},
+): Promise<DeclarationEditorOptions> {
+	const { guildId, userId, locale, translator } = context;
+	const ctx: RequestContext = { guildId, userId, locale };
+	const subject = await loadDeclarationSubject({ declaration, service, ctx });
+	const searchOptions = await loadSearchOptions({ declaration, service, ctx, subject });
+	const controls = displayedControls(declaration, searchOptions);
+	const layout = layoutDeclaration({ declaration, controls });
+	const scope: AdapterScope = {
+		declaration,
+		service,
+		ctx,
+		translate: (key) => translator.translate(locale, key),
+		controls: new Map(controls.map((control) => [control.entry.key, control])),
+		groups: layout.groups,
+	};
+	return {
+		fields: layout.fields,
+		levels: layout.levels,
+		initial: { subject, assets: [] },
+		currentValue: (subject: DeclarationSubject, key: string) =>
+			controlValue({ translate: scope.translate, subject, control: controlAt({ scope, key }) }),
+		displayValue: (subject: DeclarationSubject, key: string) => {
+			const control = controlAt({ scope, key });
+			// The free entry holds nothing of its own: its field shows beside the select.
+			return isFreeEntry(control)
+				? null
+				: controlDisplay({ translate: scope.translate, subject, control });
+		},
+		save: (subject: DeclarationSubject, key: string, submission: SettingsEditorSubmission) =>
+			saveControl({ scope, subject, control: controlAt({ scope, key }), submission }),
+		saveGroup: (
+			subject: DeclarationSubject,
+			groupKey: string,
+			submissions: SettingsEditorGroupSubmission<string>,
+		) => saveGroupControls({ scope, subject, groupKey, submissions }),
+		reset: async () => {
+			await service.reset(declaration, guildId, "all", scope.ctx);
+			return reload(scope);
+		},
+	};
+}
+
+/** The controls of a declaration in its display order, the one every surface shows. */
+function displayedControls(
+	declaration: SettingsDeclaration,
+	searchOptions: SearchOptions,
+): DeclarationControl[] {
+	const rank = new Map(
+		displayOrder(declaration)
+			.entries.flatMap((entry) => (entry.kind === "field" ? [entry.key] : entry.fields))
+			.map((key, index) => [key, index]),
+	);
+	const place = (control: DeclarationControl): number => rank.get(control.fieldKey) ?? rank.size;
+	return declarationControls(declaration, searchOptions).sort(
+		(left, right) => place(left) - place(right),
+	);
+}
+
+/** The screen's subject, read back from the service. */
+async function reload(
+	scope: AdapterScope,
+): Promise<SettingsEditorWrite<DeclarationSubject, never>> {
+	const { declaration, service, ctx } = scope;
+	return { subject: await loadDeclarationSubject({ declaration, service, ctx }), assets: [] };
+}
+
+/** Write `patch` in one `service.set` (nothing when it is empty), then read the screen back. */
+async function write(params: {
+	scope: AdapterScope;
+	patch: Patch;
+}): Promise<SettingsEditorWrite<DeclarationSubject, never>> {
+	const { scope, patch } = params;
+	if (Object.keys(patch).length > 0) {
+		await scope.service.set(scope.declaration, scope.ctx.guildId, patch, scope.ctx);
+	}
+	return reload(scope);
+}
+
+function controlAt(params: { scope: AdapterScope; key: string }): DeclarationControl {
+	const { scope, key } = params;
+	const control = scope.controls.get(key);
+	if (control === undefined) {
+		throw new NotFoundError(`Settings screen of "${scope.declaration.id}" has no field "${key}"`);
+	}
+	return control;
+}
+
+/**
+ * Save one entry as submitted. A secret opens on whether it is set, not on
+ * its value: sent back untouched, that text must not replace the secret.
+ */
+function saveControl(params: {
+	scope: AdapterScope;
+	subject: DeclarationSubject;
+	control: DeclarationControl;
+	submission: SettingsEditorSubmission;
+}): Promise<SettingsEditorWrite<DeclarationSubject, never>> {
+	const { scope, subject, control, submission } = params;
+	const untouchedSecret =
+		control.shape.kind === "secret" &&
+		isUnchanged({
+			control,
+			submission,
+			current: controlValue({ translate: scope.translate, subject, control }),
+		});
+	const patch = untouchedSecret ? {} : withSubmission({ control, submission, subject, patch: {} });
+	return write({ scope, patch });
+}
+
+/**
+ * Save a group's modal in one write carrying only the members changed from
+ * what the modal opened on: a picker whose stored entity is gone, or a
+ * secret showing whether it is set, left untouched keeps its stored value.
+ */
+function saveGroupControls(params: {
+	scope: AdapterScope;
+	subject: DeclarationSubject;
+	groupKey: string;
+	submissions: SettingsEditorGroupSubmission<string>;
+}): Promise<SettingsEditorWrite<DeclarationSubject, never>> {
+	const { scope, subject, groupKey, submissions } = params;
+	let patch: Patch = {};
+	for (const control of scope.groups.get(groupKey) ?? []) {
+		const submission: SettingsEditorGroupMemberSubmission | undefined =
+			submissions[control.entry.key];
+		const current = controlValue({ translate: scope.translate, subject, control });
+		if (submission !== undefined && !isUnchanged({ control, submission, current })) {
+			patch = withSubmission({ control, submission, subject, patch });
+		}
+	}
+	return write({ scope, patch });
+}

package/src/discord/components/settings-editor/index.ts

@@ -1,3 +1,4 @@
+export { settingsEditorFromDeclaration } from "@/discord/components/settings-editor/from-declaration";
 export {
 	mountSettingsEditor,
 	type SettingsEditorOptions,
@@ -27,15 +28,17 @@ export type {
 	SettingsEditorGroupSubmission,
 	SettingsEditorSubmission,
 } from "@/discord/components/settings-editor/settings-editor-field-modal";
+export {
+	pickedFieldValue,
+	textFieldValue,
+} from "@/discord/components/settings-editor/settings-editor-field-values";
 export {
 	MAX_MODAL_COMPONENTS,
 	MAX_MODAL_INPUT_LENGTH,
-	pickedFieldValue,
 	type SettingsEditorChoice,
 	type SettingsEditorField,
 	type SettingsEditorFieldValue,
 	type SettingsEditorGroupField,
 	type SettingsEditorPickerField,
 	type SettingsEditorValueField,
-	textFieldValue,
 } from "@/discord/components/settings-editor/settings-editor-fields";

package/src/discord/components/settings-editor/mount-settings-editor.ts

@@ -4,14 +4,14 @@ import type {
 	ModalMessageModalSubmitInteraction,
 } from "discord.js";
 import type { Clock } from "@/clock";
-import {
-	type InteractiveMessageHandle,
-	type InteractiveSelect,
-	type InteractiveView,
-	mountInteractiveMessage,
-	type StateStore,
-	toMessageEditOptions,
-} from "@/discord/components/interactive-message";
+import type {
+	InteractiveMessageHandle,
+	InteractiveSelect,
+	InteractiveView,
+} from "@/discord/components/interactive-message/interactive-message-collector";
+import { toMessageEditOptions } from "@/discord/components/interactive-message/message-edit-options";
+import { mountInteractiveMessage } from "@/discord/components/interactive-message/mount-interactive-message";
+import type { StateStore } from "@/discord/components/interactive-message/state-store";
 import {
 	popLevel,
 	pushLevel,
@@ -50,8 +50,11 @@ import {
 } from "@/discord/components/settings-editor/settings-editor-fields";
 import { SETTINGS_EDITOR_MESSAGES } from "@/discord/i18n";
 import { type Button, type ComponentContext, createButton } from "@/discord/interaction/button";
-import { BusinessError, describeError } from "@/errors";
-import { type Locale, resolveBusinessMessage, type Translator } from "@/i18n";
+import { BusinessError } from "@/errors/business-error";
+import { describeError } from "@/errors/describe-error";
+import { resolveBusinessMessage } from "@/i18n/business-message";
+import type { Locale } from "@/i18n/locale";
+import type { Translator } from "@/i18n/translator";
 import type { Logger } from "@/logger";
 
 /**
@@ -83,6 +86,18 @@ export interface SettingsEditorOptions<S, A, F extends string> {
 	readonly initial: SettingsEditorWrite<S, A>;
 	/** What the modal for `field` opens on. */
 	currentValue(subject: S, field: F): SettingsEditorFieldValue;
+	/**
+	 * What `field` currently holds, already translated, shown on the card under
+	 * the entry's hint as "Current: …" so an administrator reads it without
+	 * opening the modal. Rendered from the state's subject, so it follows every
+	 * write. `null` shows no line for that field; a group shows one
+	 * `label: value` per member answering one; a level shows nothing. A long
+	 * value is cut with an ellipsis.
+	 *
+	 * Read by the card layout only: the embeds layout ignores it. Left out, the
+	 * card renders exactly as it did without it.
+	 */
+	displayValue?(subject: S, field: F): string | null;
 	/**
 	 * Persist one field — its typed value, its upload, or what a picker's select
 	 * came back with, whichever `submission` carries.
@@ -574,6 +589,9 @@ export async function mountSettingsEditor<S, A, F extends string>(
 			translator,
 			locale,
 			dressing,
+			options.displayValue === undefined
+				? undefined
+				: (subject, field) => options.displayValue?.(subject, field) ?? null,
 		);
 	} else {
 		view = createEditorView(

package/src/discord/components/settings-editor/navigation.ts

@@ -65,3 +65,44 @@ export function pushLevel(path: SettingsEditorPath, key: string): SettingsEditor
 export function popLevel(path: SettingsEditorPath): SettingsEditorPath {
 	return canReturn(path) ? path.slice(0, -1) : path;
 }
+
+/** Separates the levels in a screen's heading trail. */
+const BREADCRUMB_SEPARATOR = " › ";
+
+/** Every level a screen declares, root first, and how to find one by key. */
+export interface SettingsEditorLevels<F extends string> {
+	readonly all: readonly SettingsEditorLevel<F>[];
+	/**
+	 * The level `key` names. A path entry naming no declared level cannot happen
+	 * — only a level field puts one there — but falling back to the root keeps a
+	 * corrupted state showing a usable screen rather than an empty one.
+	 */
+	at(key: string): SettingsEditorLevel<F>;
+}
+
+/**
+ * Index a screen's levels. The root is a level like any other, named after the
+ * screen itself, so rendering never special-cases "no depth declared".
+ */
+export function indexLevels<F extends string>(
+	root: SettingsEditorLevel<F>,
+	levels: readonly SettingsEditorLevel<F>[] | undefined,
+): SettingsEditorLevels<F> {
+	const all = [root, ...(levels ?? [])];
+	return {
+		all,
+		at: (key) => all.find((level) => level.key === key) ?? root,
+	};
+}
+
+/**
+ * Where the reader is, as a trail rather than only the current name: a level
+ * called "Roles" says nothing on its own about which type it belongs to.
+ */
+export function levelTrail<F extends string>(
+	path: SettingsEditorPath,
+	levels: SettingsEditorLevels<F>,
+	titleOf: (level: SettingsEditorLevel<F>) => string,
+): string {
+	return path.map((key) => titleOf(levels.at(key))).join(BREADCRUMB_SEPARATOR);
+}