@azurioh/discord-kernel 0.1.0 → 1.0.0

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

@@ -0,0 +1,155 @@
+import { channelMention, roleMention, userMention } from "discord.js";
+import type { DeclarationControl } from "@/discord/components/settings-editor/from-declaration-controls";
+import {
+	choiceLabelKey,
+	isToggledOn,
+	secretStateKey,
+	storedIds,
+} from "@/discord/components/settings-editor/from-declaration-stored";
+import type { DeclarationSubject } from "@/discord/components/settings-editor/from-declaration-subject";
+import { truncateText } from "@/discord/ui/truncate-text";
+import type { TranslateKey } from "@/i18n/translator";
+import { formatDuration } from "@/settings/duration";
+import { SETTINGS_MESSAGES } from "@/settings/messages";
+
+/** The most characters a stored text shows on the screen before it is cut. */
+const MAX_TEXT_SHOWN = 100;
+
+/** Separates the items of a list, and the toggles that are on. */
+const ITEM_SEPARATOR = ", ";
+
+/** One control's entry kind, which decides how a picked id reads. */
+type EntryKind = DeclarationControl["entry"]["kind"];
+
+/**
+ * What a control currently holds, as the administrator reads it on the
+ * screen: a channel, role or member as the Discord mention that renders its
+ * name, an enum value or toggle as its translated label, a secret as whether
+ * it is set (never its value), a duration formatted, anything else as is.
+ * A stored id the guild no longer has reads as unavailable, a value left
+ * unset as "not set".
+ *
+ * @param params.control - the control shown.
+ * @param params.subject - the screen's current subject.
+ * @param params.translate - translates the texts shown in place of a value.
+ * @returns the text shown after the entry's "Current:" prefix. A searchable
+ * field shows its search's label of the value, or the value itself.
+ */
+export function controlDisplay(params: {
+	control: DeclarationControl;
+	subject: DeclarationSubject;
+	translate: TranslateKey;
+}): string {
+	const { control, subject, translate } = params;
+	const value = subject.values[control.fieldKey];
+	const { shape } = control;
+	// A secret reads as whether it is set, whatever it holds: never its value.
+	if ((value === undefined || value === null) && shape.kind !== "secret") {
+		return translate(SETTINGS_MESSAGES.valueNotSet);
+	}
+	switch (shape.kind) {
+		case "secret":
+			return translate(secretStateKey(value));
+		case "text":
+			return truncateText(String(value), MAX_TEXT_SHOWN);
+		case "number":
+			return String(value);
+		case "duration":
+			return typeof value === "number" ? formatDuration(value) : String(value);
+		case "lines":
+			return Array.isArray(value)
+				? truncateText(value.map(String).join(ITEM_SEPARATOR), MAX_TEXT_SHOWN)
+				: String(value);
+		case "boolean":
+			return translate(
+				value === true ? SETTINGS_MESSAGES.booleanTrue : SETTINGS_MESSAGES.booleanFalse,
+			);
+		case "single":
+		case "many":
+			return pickedDisplay({ control, subject, translate, value });
+		case "toggles":
+			return togglesDisplay({ control, translate, value, keys: shape.keys });
+		case "search":
+		case "other":
+			return truncateText(subject.labels[control.fieldKey] ?? String(value), MAX_TEXT_SHOWN);
+		default:
+			return shape satisfies never;
+	}
+}
+
+/** Each picked id or enum value as it reads, joined; "not set" for an empty list. */
+function pickedDisplay(params: {
+	control: DeclarationControl;
+	subject: DeclarationSubject;
+	translate: TranslateKey;
+	value: unknown;
+}): string {
+	const { control, subject, translate, value } = params;
+	const ids = storedIds(value);
+	if (ids.length === 0) {
+		return translate(SETTINGS_MESSAGES.valueNotSet);
+	}
+	const missing = subject.unavailable[control.fieldKey] ?? [];
+	return ids
+		.map((id) =>
+			missing.includes(id)
+				? translate(SETTINGS_MESSAGES.valueUnavailable)
+				: pickedItem({ control, translate, id }),
+		)
+		.join(ITEM_SEPARATOR);
+}
+
+/** One picked id as a mention, or one enum value as its choice label. */
+function pickedItem(params: {
+	control: DeclarationControl;
+	translate: TranslateKey;
+	id: string;
+}): string {
+	const { control, translate, id } = params;
+	const { entry } = control;
+	const kind: EntryKind = entry.kind;
+	switch (kind) {
+		case "channel":
+		case "category":
+			return channelMention(id);
+		case "role":
+			return roleMention(id);
+		case "user":
+			return userMention(id);
+		case "choice":
+			return translatedChoice({ control, translate, value: id });
+		case "text":
+		case "image":
+			return id;
+		default:
+			return kind satisfies never;
+	}
+}
+
+/** The translated labels of this control's toggles that are on, or "none". */
+function togglesDisplay(params: {
+	control: DeclarationControl;
+	translate: TranslateKey;
+	value: unknown;
+	keys: readonly string[];
+}): string {
+	const { control, translate, value, keys } = params;
+	const on = keys.filter((key) => isToggledOn({ value, key }));
+	if (on.length === 0) {
+		return translate(SETTINGS_MESSAGES.valueNone);
+	}
+	return on.map((key) => translatedChoice({ control, translate, value: key })).join(ITEM_SEPARATOR);
+}
+
+/** A choice control's value as its translated label, or the value itself when no choice offers it. */
+function translatedChoice(params: {
+	control: DeclarationControl;
+	translate: TranslateKey;
+	value: string;
+}): string {
+	const { control, translate, value } = params;
+	const { entry } = control;
+	const labelKey =
+		entry.kind === "choice" ? choiceLabelKey({ choices: entry.choices, value }) : undefined;
+	return labelKey === undefined ? value : translate(labelKey);
+}

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

@@ -0,0 +1,247 @@
+import {
+	type DeclarationControl,
+	isFreeEntry,
+} from "@/discord/components/settings-editor/from-declaration-controls";
+import type { SettingsEditorLevel } from "@/discord/components/settings-editor/navigation";
+import { MAX_CARD_LEVEL_ENTRIES } from "@/discord/components/settings-editor/settings-editor-card.view";
+import {
+	MAX_MODAL_COMPONENTS,
+	type SettingsEditorField,
+} from "@/discord/components/settings-editor/settings-editor-fields";
+import { SETTINGS_EDITOR_MESSAGES } from "@/discord/i18n";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+
+/** Separates a generated entry key from its number. */
+const KEY_SEPARATOR = "#";
+
+/** Prefix of the key of every level the layout nests. */
+const LEVEL_KEY_PREFIX = "level";
+
+/** Suffix of the key of the modal a non-strict searchable field outside any group opens. */
+const SEARCH_ENTRY_SUFFIX = "search";
+
+/** The screen of a declaration: its root entries, its nested levels, and what each group entry saves. */
+export interface DeclarationLayout {
+	readonly fields: readonly SettingsEditorField<string>[];
+	readonly levels: readonly SettingsEditorLevel<string>[];
+	/** The controls of each group entry, by the entry's key. */
+	readonly groups: ReadonlyMap<string, readonly DeclarationControl[]>;
+}
+
+/**
+ * One place on a level, in declared order: a control of its own, or a
+ * declared group already split into modals of at most
+ * {@link MAX_MODAL_COMPONENTS} controls.
+ */
+type Section =
+	| { readonly kind: "control"; readonly control: DeclarationControl }
+	| {
+			readonly kind: "group";
+			readonly labelKey: string;
+			readonly hintKey: string;
+			readonly chunks: readonly SettingsEditorField<string>[];
+	  };
+
+/**
+ * Lay the controls of a declaration out on the screen, keeping their order
+ * (the display order of `@/settings/field-order`): a control outside any group is an entry of its own; a group stands
+ * where its first control stands, split into entries of at most
+ * {@link MAX_MODAL_COMPONENTS} controls (one modal each). A level holds at
+ * most {@link MAX_CARD_LEVEL_ENTRIES} entries: past that, a group split over
+ * several entries moves into a level of its own, then the entries past the
+ * last that fits move behind a "more settings" level.
+ *
+ * A non-strict searchable field's select and its free entry are never split:
+ * outside any group they form a modal of their own, named after the field;
+ * inside a group they share one of its modals.
+ *
+ * @param params.declaration - the module's settings declaration, for its groups.
+ * @param params.controls - the controls of the declaration, in declared order.
+ * @returns the root entries, the nested levels and each group entry's controls.
+ */
+export function layoutDeclaration(params: {
+	declaration: SettingsDeclaration;
+	controls: readonly DeclarationControl[];
+}): DeclarationLayout {
+	const groups = new Map<string, readonly DeclarationControl[]>();
+	const sections = declarationSections({ ...params, groups });
+	const levels: SettingsEditorLevel<string>[] = [];
+	const flat = sections.flatMap(sectionEntries);
+	const fields =
+		flat.length <= MAX_CARD_LEVEL_ENTRIES
+			? flat
+			: paged({
+					entries: sections.flatMap((section) => foldedEntries({ section, levels })),
+					levels,
+				});
+	return { fields, levels, groups };
+}
+
+/** The sections of the root level, recording each group entry's controls in `groups`. */
+function declarationSections(params: {
+	declaration: SettingsDeclaration;
+	controls: readonly DeclarationControl[];
+	groups: Map<string, readonly DeclarationControl[]>;
+}): Section[] {
+	const { declaration, controls, groups } = params;
+	const sections: Section[] = [];
+	const seenGroups = new Set<string>();
+	const units = controlUnits(controls);
+	for (const unit of units) {
+		const [first] = unit;
+		if (first === undefined) {
+			continue;
+		}
+		const { groupId } = first;
+		if (groupId === undefined) {
+			sections.push(
+				unit.length === 1 ? { kind: "control", control: first } : searchSection({ unit, groups }),
+			);
+		} else if (!seenGroups.has(groupId)) {
+			seenGroups.add(groupId);
+			sections.push(groupSection({ declaration, units, groups, groupId }));
+		}
+	}
+	return sections;
+}
+
+/**
+ * The controls in order, a non-strict searchable field's select and free
+ * entry kept together as one unit, every other control a unit of its own.
+ */
+function controlUnits(controls: readonly DeclarationControl[]): DeclarationControl[][] {
+	const units: DeclarationControl[][] = [];
+	for (const control of controls) {
+		const last = units.at(-1);
+		if (isFreeEntry(control) && last?.[0]?.fieldKey === control.fieldKey) {
+			last.push(control);
+		} else {
+			units.push([control]);
+		}
+	}
+	return units;
+}
+
+/** A non-strict searchable field outside any group: one modal holding its select and free entry. */
+function searchSection(params: {
+	unit: readonly DeclarationControl[];
+	groups: Map<string, readonly DeclarationControl[]>;
+}): Section {
+	const { unit, groups } = params;
+	const [{ entry, fieldKey }] = unit as [DeclarationControl];
+	const key = `${fieldKey}${KEY_SEPARATOR}${SEARCH_ENTRY_SUFFIX}`;
+	groups.set(key, unit);
+	const { labelKey, hintKey } = entry;
+	return {
+		kind: "group",
+		labelKey,
+		hintKey,
+		chunks: [{ kind: "group", key, labelKey, hintKey, fields: unit.map(controlEntry) }],
+	};
+}
+
+/** A declared group split into entries of at most {@link MAX_MODAL_COMPONENTS} controls, no unit split. */
+function groupSection(params: {
+	declaration: SettingsDeclaration;
+	units: readonly (readonly DeclarationControl[])[];
+	groups: Map<string, readonly DeclarationControl[]>;
+	groupId: string;
+}): Section {
+	const { declaration, units, groups, groupId } = params;
+	const group = declaration.groups?.[groupId];
+	const labelKey = group?.label ?? groupId;
+	const hintKey = group?.description ?? SETTINGS_EDITOR_MESSAGES.entryHint;
+	const members = units.filter((unit) => unit[0]?.groupId === groupId);
+	const chunks: SettingsEditorField<string>[] = [];
+	for (const [index, chunk] of packed(members, MAX_MODAL_COMPONENTS).entries()) {
+		const key = `${groupId}${KEY_SEPARATOR}${index + 1}`;
+		groups.set(key, chunk);
+		chunks.push({ kind: "group", key, labelKey, hintKey, fields: chunk.map(controlEntry) });
+	}
+	return { kind: "group", labelKey, hintKey, chunks };
+}
+
+/**
+ * `units` packed in order into chunks of at most `size` controls, a unit
+ * never split: one that does not fit starts the next chunk.
+ */
+function packed(
+	units: readonly (readonly DeclarationControl[])[],
+	size: number,
+): DeclarationControl[][] {
+	const chunks: DeclarationControl[][] = [];
+	for (const unit of units) {
+		const last = chunks.at(-1);
+		if (last !== undefined && last.length + unit.length <= size) {
+			last.push(...unit);
+		} else {
+			chunks.push([...unit]);
+		}
+	}
+	return chunks;
+}
+
+function controlEntry(control: DeclarationControl): DeclarationControl["entry"] {
+	return control.entry;
+}
+
+/** The entries a section stands for on a level of its own. */
+function sectionEntries(section: Section): readonly SettingsEditorField<string>[] {
+	return section.kind === "control" ? [section.control.entry] : section.chunks;
+}
+
+/** A section's entries once a group split over several entries moves into a level of its own. */
+function foldedEntries(params: {
+	section: Section;
+	levels: SettingsEditorLevel<string>[];
+}): readonly SettingsEditorField<string>[] {
+	const { section, levels } = params;
+	if (section.kind === "control" || section.chunks.length === 1) {
+		return sectionEntries(section);
+	}
+	return [
+		nestedLevel({
+			labelKey: section.labelKey,
+			hintKey: section.hintKey,
+			entries: section.chunks,
+			levels,
+		}),
+	];
+}
+
+/**
+ * `entries` within {@link MAX_CARD_LEVEL_ENTRIES}: all of them when they fit,
+ * otherwise those before the last place, then a "more settings" level holding
+ * the rest.
+ */
+function paged(params: {
+	entries: readonly SettingsEditorField<string>[];
+	levels: SettingsEditorLevel<string>[];
+}): readonly SettingsEditorField<string>[] {
+	const { entries, levels } = params;
+	if (entries.length <= MAX_CARD_LEVEL_ENTRIES) {
+		return entries;
+	}
+	const kept = MAX_CARD_LEVEL_ENTRIES - 1;
+	const more = nestedLevel({
+		labelKey: SETTINGS_EDITOR_MESSAGES.moreEntries,
+		hintKey: SETTINGS_EDITOR_MESSAGES.moreEntriesHint,
+		entries: entries.slice(kept),
+		levels,
+	});
+	return [...entries.slice(0, kept), more];
+}
+
+/** Add a level holding `entries` (paged to fit) and return the entry that opens it. */
+function nestedLevel(params: {
+	labelKey: string;
+	hintKey: string;
+	entries: readonly SettingsEditorField<string>[];
+	levels: SettingsEditorLevel<string>[];
+}): SettingsEditorField<string> {
+	const { labelKey, hintKey, levels } = params;
+	const fields = paged({ entries: params.entries, levels });
+	const key = `${LEVEL_KEY_PREFIX}${KEY_SEPARATOR}${levels.length + 1}`;
+	levels.push({ key, titleKey: labelKey, fields });
+	return { kind: "level", key, levelKey: key, labelKey, hintKey };
+}

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

@@ -0,0 +1,77 @@
+import type { SearchOptions } from "@/discord/components/settings-editor/from-declaration-controls";
+import type { DeclarationSubject } from "@/discord/components/settings-editor/from-declaration-subject";
+import {
+	MAX_SELECT_OPTION_TEXT,
+	MAX_SELECT_OPTIONS,
+} from "@/discord/components/settings-editor/settings-editor.view";
+import type { SettingsEditorChoice } from "@/discord/components/settings-editor/settings-editor-fields";
+import { SETTINGS_EDITOR_MESSAGES } from "@/discord/i18n";
+import { truncateText } from "@/discord/ui/truncate-text";
+import type { Choice } from "@/settings/choice";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import { fieldSearch } from "@/settings/field-search";
+import type { RequestContext, SettingsService } from "@/settings/settings-service";
+
+/**
+ * What each searchable field's select offers on the Discord screen (FR-026a):
+ * the first {@link MAX_SELECT_OPTIONS} results of its search for an empty
+ * query, since a select cannot be searched as it is typed. The field's
+ * current value leads the list when the results miss it, so a modal opened
+ * and sent back unchanged keeps it. A field whose search offered nothing
+ * (it failed or timed out, logged by the service) has no entry: the screen
+ * types it instead.
+ *
+ * @param params.declaration - the module's settings declaration.
+ * @param params.service - the settings service the searches run through.
+ * @param params.ctx - the guild, the administrator and their locale.
+ * @param params.subject - the screen's subject: the values searches see, and
+ * the current values' labels.
+ * @returns the options of each searchable field that has any, by field key.
+ */
+export async function loadSearchOptions(params: {
+	declaration: SettingsDeclaration;
+	service: SettingsService;
+	ctx: RequestContext;
+	subject: DeclarationSubject;
+}): Promise<SearchOptions> {
+	const { declaration, service, ctx, subject } = params;
+	const searched = await Promise.all(
+		Object.entries(declaration.fields)
+			.filter(([, declared]) => fieldSearch(declared.spec) !== undefined)
+			.map(async ([key]) => {
+				const results = await service.suggest(declaration, key, "", {
+					...ctx,
+					values: subject.values,
+				});
+				const options = withCurrent({ results, key, subject }).map(toEditorChoice);
+				return [key, options.slice(0, MAX_SELECT_OPTIONS)] as const;
+			}),
+	);
+	return new Map(searched.filter(([, options]) => options.length > 0));
+}
+
+/** The results with the field's current value first when they miss it. */
+function withCurrent(params: {
+	results: readonly Choice[];
+	key: string;
+	subject: DeclarationSubject;
+}): readonly Choice[] {
+	const { results, key, subject } = params;
+	const value = subject.values[key];
+	if (results.length === 0 || (typeof value !== "string" && typeof value !== "number")) {
+		return results;
+	}
+	if (results.some((choice) => String(choice.value) === String(value))) {
+		return results;
+	}
+	return [{ name: subject.labels[key] ?? String(value), value }, ...results];
+}
+
+/** A search result as a select option: its name shown as is, cut to what an option shows. */
+function toEditorChoice(choice: Choice): SettingsEditorChoice {
+	return {
+		value: String(choice.value),
+		labelKey: SETTINGS_EDITOR_MESSAGES.choiceLabel,
+		labelParams: { label: truncateText(choice.name, MAX_SELECT_OPTION_TEXT) },
+	};
+}

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

@@ -0,0 +1,39 @@
+import type { SettingsEditorChoice } from "@/discord/components/settings-editor/settings-editor-fields";
+import { SETTINGS_MESSAGES } from "@/settings/messages";
+
+/**
+ * How the settings screen reads a value the settings service returned, shared
+ * by what a modal opens on, what the screen shows, and which stored ids the
+ * guild still has.
+ */
+
+/** The ids a stored picker value holds: none, one, or a list's. */
+export function storedIds(value: unknown): readonly string[] {
+	if (typeof value === "string") {
+		return [value];
+	}
+	if (Array.isArray(value)) {
+		return value.filter((item): item is string => typeof item === "string");
+	}
+	return [];
+}
+
+/** `set` for a secret the surface reads as set, `not set` otherwise. */
+export function secretStateKey(value: unknown): string {
+	const isSet = typeof value === "object" && value !== null && "isSet" in value && value.isSet;
+	return isSet === true ? SETTINGS_MESSAGES.secretSet : SETTINGS_MESSAGES.secretNotSet;
+}
+
+/** Whether `key` is on in a toggles value. */
+export function isToggledOn(params: { value: unknown; key: string }): boolean {
+	const { value, key } = params;
+	return typeof value === "object" && value !== null && Reflect.get(value, key) === true;
+}
+
+/** The catalog key of the choice offering `value`, or `undefined` when none does. */
+export function choiceLabelKey(params: {
+	choices: readonly SettingsEditorChoice[];
+	value: string;
+}): string | undefined {
+	return params.choices.find((choice) => choice.value === params.value)?.labelKey;
+}

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

@@ -0,0 +1,110 @@
+import { storedIds } from "@/discord/components/settings-editor/from-declaration-stored";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import { fieldSearch } from "@/settings/field-search";
+import type { AnyField } from "@/settings/fields/field";
+import type { RequestContext, SettingsService } from "@/settings/settings-service";
+import type { SettingsIssueCode } from "@/settings/settings-validation-error";
+
+/**
+ * What the settings screen shows for one guild: every declared field as a
+ * surface reads it (a secret as whether it is set), the stored channels,
+ * roles and members the guild no longer has, and the label a searchable
+ * field's search gives its value.
+ */
+export interface DeclarationSubject {
+	readonly values: Readonly<Record<string, unknown>>;
+	/** Per field key, the stored ids the guild no longer offers. */
+	readonly unavailable: Readonly<Record<string, readonly string[]>>;
+	/** Per searchable field key, its search's label of the value, when it has one. */
+	readonly labels: Readonly<Record<string, string>>;
+}
+
+/** The issues that say a stored id no longer names a usable entity of the guild. */
+const UNAVAILABLE_CODES: ReadonlySet<SettingsIssueCode> = new Set(["notFound", "channelType"]);
+
+/**
+ * Read the guild's settings of a declaration for the screen, and find which
+ * stored entities it no longer has by asking the service's own validator
+ * about each one, so the screen and every other surface agree on it.
+ * A searchable field's value is labelled through `service.label`.
+ *
+ * @param params.declaration - the module's settings declaration.
+ * @param params.service - the settings service the screen reads through.
+ * @param params.ctx - the guild, the administrator and their locale.
+ * @returns the screen's subject.
+ */
+export async function loadDeclarationSubject(params: {
+	declaration: SettingsDeclaration;
+	service: SettingsService;
+	ctx: RequestContext;
+}): Promise<DeclarationSubject> {
+	const { declaration, service, ctx } = params;
+	const values: Readonly<Record<string, unknown>> = await service.getForSurface(
+		declaration,
+		ctx.guildId,
+	);
+	const checked = await Promise.all(
+		Object.entries(declaration.fields).map(async ([key, declared]) => {
+			const missing = await unavailableIds({ ...params, key, declared, value: values[key] });
+			return [key, missing] as const;
+		}),
+	);
+	const labelled = await Promise.all(
+		Object.entries(declaration.fields).map(async ([key, declared]) => {
+			const value = values[key];
+			if (value === undefined || fieldSearch(declared.spec) === undefined) {
+				return [];
+			}
+			const label = await service.label(declaration, key, value, ctx);
+			return label === undefined ? [] : [[key, label] as const];
+		}),
+	);
+	return {
+		values,
+		unavailable: Object.fromEntries(checked.filter(hasMissingIds)),
+		labels: Object.fromEntries(labelled.flat()),
+	};
+}
+
+function hasMissingIds(entry: readonly [string, readonly string[]]): boolean {
+	return entry[1].length > 0;
+}
+
+/** The ids a field stores that the guild no longer offers. */
+async function unavailableIds(params: {
+	declaration: SettingsDeclaration;
+	service: SettingsService;
+	ctx: RequestContext;
+	key: string;
+	declared: AnyField;
+	value: unknown;
+}): Promise<readonly string[]> {
+	const { declaration, service, ctx, key, declared, value } = params;
+	const isList = declared.spec.kind === "list";
+	if (!isEntityKind(itemKind(declared))) {
+		return [];
+	}
+	const ids = storedIds(value);
+	const usable = await Promise.all(
+		ids.map(async (id) => {
+			const result = await service.validate(
+				declaration,
+				ctx.guildId,
+				{ [key]: isList ? [id] : id },
+				ctx,
+			);
+			return result.ok || !result.issues.some((issue) => UNAVAILABLE_CODES.has(issue.code));
+		}),
+	);
+	return ids.filter((_, index) => usable[index] === false);
+}
+
+/** The kind of a list's items, or of the field itself when it is not a list. */
+function itemKind(declared: AnyField): string {
+	return declared.spec.kind === "list" ? declared.spec.item.spec.kind : declared.spec.kind;
+}
+
+/** Whether a field of this kind references a channel, a role or a member of the guild. */
+function isEntityKind(kind: string): boolean {
+	return kind === "channel" || kind === "role" || kind === "user";
+}