@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/settings/field-order.ts

@@ -0,0 +1,128 @@
+import type { SettingsDeclaration } from "@/settings/define-settings";
+
+/** Rank of an item no hint places: after every ranked one. */
+const UNRANKED = Number.MAX_SAFE_INTEGER;
+
+/** One place on a settings screen: a field of its own, or a group with its fields in order. */
+type DisplayEntry =
+	| { readonly kind: "field"; readonly key: string }
+	| { readonly kind: "group"; readonly id: string; readonly fields: readonly string[] };
+
+/** The display order of a declaration. */
+export interface DisplayOrder {
+	/** Every declared group, fields or not, ranked. */
+	readonly groups: readonly string[];
+	/** The screen's places, top to bottom: ungrouped fields and groups holding fields. */
+	readonly entries: readonly DisplayEntry[];
+}
+
+/** An item and the keys it sorts by, compared left to right. */
+interface Ranked<T> {
+	readonly item: T;
+	readonly keys: readonly number[];
+}
+
+/**
+ * The order every surface shows a declaration in.
+ *
+ * - Groups rank by their position in `ui.groupOrder` (unlisted ones after
+ *   listed ones), then by their own `order` (none after any), then by where
+ *   they stand in declared order: at their first field, or after every field
+ *   for a group with no field, in declaration order.
+ * - Fields rank within their group, and ungrouped fields among themselves,
+ *   by `ui.order` (none after any), then by declaration order.
+ * - On screen, each place is kept by its kind: a group stands where a group's
+ *   first field is declared and an ungrouped field where an ungrouped field
+ *   is declared, then the ranked groups fill the group places and the ranked
+ *   ungrouped fields the field places. With no hint this is declared order.
+ *
+ * @param declaration - the module's settings declaration; left untouched.
+ * @returns every declared group ranked, and the screen's places in order.
+ */
+export function displayOrder(declaration: SettingsDeclaration): DisplayOrder {
+	const fieldKeys = Object.keys(declaration.fields);
+	const slots: ("field" | "group")[] = [];
+	const firstField = new Map<string, number>();
+	const members = new Map<string, Ranked<string>[]>();
+	const loose: Ranked<string>[] = [];
+	fieldKeys.forEach((key, index) => {
+		const ui = declaration.fields[key]?.ui;
+		const ranked: Ranked<string> = { item: key, keys: [ui?.order ?? UNRANKED, index] };
+		const groupId = ui?.group;
+		if (groupId === undefined) {
+			slots.push("field");
+			loose.push(ranked);
+			return;
+		}
+		if (!firstField.has(groupId)) {
+			firstField.set(groupId, index);
+			slots.push("group");
+		}
+		members.set(groupId, [...(members.get(groupId) ?? []), ranked]);
+	});
+	const groups = rankedGroups({ declaration, firstField, fieldCount: fieldKeys.length });
+	const filledGroups = groups.filter((id) => members.has(id));
+	const fields = sortedItems(loose);
+	let nextGroup = 0;
+	let nextField = 0;
+	const entries = slots.map((slot): DisplayEntry => {
+		switch (slot) {
+			case "field": {
+				const key = fields[nextField] ?? "";
+				nextField += 1;
+				return { kind: "field", key };
+			}
+			case "group": {
+				const id = filledGroups[nextGroup] ?? "";
+				nextGroup += 1;
+				return { kind: "group", id, fields: sortedItems(members.get(id) ?? []) };
+			}
+			default:
+				return unhandledSlot(slot);
+		}
+	});
+	return { groups, entries };
+}
+
+/** Every declared group id, ranked. */
+function rankedGroups(params: {
+	declaration: SettingsDeclaration;
+	firstField: ReadonlyMap<string, number>;
+	fieldCount: number;
+}): string[] {
+	const { declaration, firstField, fieldCount } = params;
+	const groupOrder = declaration.ui?.groupOrder ?? [];
+	const ranked = Object.entries(declaration.groups ?? {}).map(
+		([id, group], index): Ranked<string> => {
+			const position = groupOrder.indexOf(id);
+			return {
+				item: id,
+				keys: [
+					position === -1 ? UNRANKED : position,
+					group.order ?? UNRANKED,
+					firstField.get(id) ?? fieldCount + index,
+				],
+			};
+		},
+	);
+	return sortedItems(ranked);
+}
+
+/** The items sorted by their keys, on a copy. */
+function sortedItems<T>(ranked: readonly Ranked<T>[]): T[] {
+	return [...ranked].sort(compareRanked).map((entry) => entry.item);
+}
+
+function compareRanked<T>(left: Ranked<T>, right: Ranked<T>): number {
+	for (const [index, key] of left.keys.entries()) {
+		const other = right.keys[index] ?? UNRANKED;
+		if (key !== other) {
+			return key < other ? -1 : 1;
+		}
+	}
+	return 0;
+}
+
+function unhandledSlot(slot: never): never {
+	throw new Error(`Unhandled display slot: ${String(slot)}`);
+}

package/src/settings/field-search.ts

@@ -0,0 +1,16 @@
+import type { DynamicSuggestions, FieldSpec } from "@/settings/fields/field";
+
+/**
+ * The server-side search a field declares, if any: only an integer or text
+ * field can declare one, as its `suggest` (static choices are not a search).
+ *
+ * @param spec - the field's kind and constraints.
+ * @returns the search, or `undefined` when the field has none.
+ */
+export function fieldSearch(spec: FieldSpec): DynamicSuggestions<unknown> | undefined {
+	if (spec.kind !== "integer" && spec.kind !== "text") {
+		return undefined;
+	}
+	const { suggest } = spec;
+	return suggest === undefined || "choices" in suggest ? undefined : suggest;
+}

package/src/settings/fields/builders.ts

@@ -0,0 +1,161 @@
+import type {
+	BoundsOptions,
+	ChannelOptions,
+	EnumOptions,
+	Field,
+	FieldOptions,
+	FieldSpec,
+	IntegerOptions,
+	ListOptions,
+	SecretField,
+	SecretOptions,
+	TextOptions,
+	TogglesOptions,
+	ToggleValues,
+} from "@/settings/fields/field";
+
+/** Options that make a field always have a value. */
+type Defined<T> = { readonly default: T };
+
+/** A builder whose result is `"defined"` when defaulted. */
+export interface FieldBuilder<T, X> {
+	(options: X & FieldOptions<T> & Defined<T>): Field<T, "defined">;
+	(options?: X & FieldOptions<T>): Field<T, "optional">;
+}
+
+/** The field builders of {@link field}. */
+export interface FieldBuilders {
+	readonly channel: FieldBuilder<string, ChannelOptions>;
+	readonly role: FieldBuilder<string, unknown>;
+	readonly user: FieldBuilder<string, unknown>;
+	/**
+	 * Stored as `#rrggbb`; accepts hex codes and the base colour names, never the
+	 * aliases a bot registers for its Discord inputs.
+	 */
+	readonly color: FieldBuilder<string, unknown>;
+	/** Stored as whole seconds; accepts `"15m"`, `"1h30m"`… Bounds are in seconds. */
+	readonly duration: FieldBuilder<number, BoundsOptions>;
+	enum<const V extends string>(
+		options: EnumOptions<V> & FieldOptions<NoInfer<V>> & Defined<NoInfer<V>>,
+	): Field<V, "defined">;
+	enum<const V extends string>(
+		options: EnumOptions<V> & FieldOptions<NoInfer<V>>,
+	): Field<V, "optional">;
+	readonly integer: FieldBuilder<number, IntegerOptions>;
+	readonly number: FieldBuilder<number, BoundsOptions>;
+	readonly text: FieldBuilder<string, TextOptions>;
+	readonly boolean: FieldBuilder<boolean, unknown>;
+	secret(options?: SecretOptions): SecretField<"optional">;
+	list<T>(
+		item: Field<T>,
+		options: ListOptions & FieldOptions<readonly T[]> & Defined<readonly T[]>,
+	): Field<readonly T[], "defined">;
+	list<T>(
+		item: Field<T>,
+		options?: ListOptions & FieldOptions<readonly T[]>,
+	): Field<readonly T[], "optional">;
+	/** A boolean per key, e.g. enabled modules; not allowed as a list item. */
+	toggles<const K extends string>(options: TogglesOptions<K>): Field<ToggleValues<K>, "defined">;
+}
+
+/**
+ * Assemble a field from its constraints and common options. The presence is
+ * `never` here: the builder overloads narrow it from the options.
+ */
+function createField<T>(spec: FieldSpec, options: FieldOptions<T>): Field<T, never> {
+	return { ...options, spec, required: options.required ?? false };
+}
+
+function channelField(options: ChannelOptions & FieldOptions<string> = {}): Field<string, never> {
+	const { types, ...common } = options;
+	return createField({ kind: "channel", types }, common);
+}
+
+function roleField(options: FieldOptions<string> = {}): Field<string, never> {
+	return createField({ kind: "role" }, options);
+}
+
+function userField(options: FieldOptions<string> = {}): Field<string, never> {
+	return createField({ kind: "user" }, options);
+}
+
+function colorField(options: FieldOptions<string> = {}): Field<string, never> {
+	return createField({ kind: "color" }, options);
+}
+
+function durationField(options: BoundsOptions & FieldOptions<number> = {}): Field<number, never> {
+	const { min, max, ...common } = options;
+	return createField({ kind: "duration", min, max }, common);
+}
+
+function enumField<V extends string>(options: EnumOptions<V> & FieldOptions<V>): Field<V, never> {
+	const { choices, ...common } = options;
+	return createField({ kind: "enum", choices }, common);
+}
+
+function integerField(options: IntegerOptions & FieldOptions<number> = {}): Field<number, never> {
+	const { min, max, suggest, ...common } = options;
+	return createField({ kind: "integer", min, max, suggest }, common);
+}
+
+function numberField(options: BoundsOptions & FieldOptions<number> = {}): Field<number, never> {
+	const { min, max, ...common } = options;
+	return createField({ kind: "number", min, max }, common);
+}
+
+function textField(options: TextOptions & FieldOptions<string> = {}): Field<string, never> {
+	const { minLength, maxLength, suggest, ...common } = options;
+	return createField({ kind: "text", minLength, maxLength, suggest }, common);
+}
+
+function booleanField(options: FieldOptions<boolean> = {}): Field<boolean, never> {
+	return createField({ kind: "boolean" }, options);
+}
+
+function secretField(options: SecretOptions = {}): SecretField<"optional"> {
+	return { ...options, spec: { kind: "secret" }, required: options.required ?? false };
+}
+
+function listField<T>(
+	item: Field<T>,
+	options: ListOptions & FieldOptions<readonly T[]> = {},
+): Field<readonly T[], never> {
+	const { minItems, maxItems, ...common } = options;
+	return createField({ kind: "list", item, minItems, maxItems }, common);
+}
+
+/**
+ * The declared keys all start `false`, then `default` sets its own; a key
+ * `default` names but `keys` lacks is kept, so the default fails its own field
+ * when the declaration is checked.
+ */
+function togglesField<K extends string>(
+	options: TogglesOptions<K>,
+): Field<ToggleValues<K>, "defined"> {
+	const { keys, keyLabels, default: defaults, ...common } = options;
+	const off = Object.fromEntries(keys.map((key) => [key, false])) as Record<K, boolean>;
+	return createField(
+		{ kind: "toggles", keys, keyLabels },
+		{ ...common, default: { ...off, ...defaults } },
+	);
+}
+
+/**
+ * Builders for every setting kind. Channel, role and user values are
+ * snowflake strings; texts in the options are catalog keys.
+ */
+export const field: FieldBuilders = {
+	channel: channelField,
+	role: roleField,
+	user: userField,
+	color: colorField,
+	duration: durationField,
+	enum: enumField,
+	integer: integerField,
+	number: numberField,
+	text: textField,
+	boolean: booleanField,
+	secret: secretField,
+	list: listField,
+	toggles: togglesField,
+};

package/src/settings/fields/field.ts

@@ -0,0 +1,205 @@
+import type { Choice } from "@/settings/choice";
+import type { ChannelKind } from "@/settings/ports/guild-directory";
+
+/** Discord's hard limits that a declaration must stay within. */
+export const FIELD_LIMITS = {
+	/** Longest text a Discord text input accepts. */
+	textMaxLength: 4000,
+	/** Most items a list field may hold (one select menu). */
+	listMaxItems: 25,
+	/** Most static choices an enum or a suggestion list may declare (one select menu). */
+	staticChoices: 25,
+} as const;
+
+/** Kinds a list field may hold. */
+export const LIST_ITEM_KINDS: readonly FieldKind[] = [
+	"channel",
+	"role",
+	"user",
+	"enum",
+	"integer",
+	"text",
+];
+
+/**
+ * Whether a field always has a value (`"defined"`: it has a default) or may be
+ * unset (`"optional"`: no default, even when required, since a guild may not
+ * have configured it yet). Drives the value type of {@link SettingsValues}.
+ */
+export type FieldPresence = "defined" | "optional";
+
+declare const presence: unique symbol;
+
+/** One labelled static choice: the stored value and the catalog key of its label. */
+export interface FieldChoice<V> {
+	readonly value: V;
+	readonly label: string;
+}
+
+/** What a suggestion search knows about the request. */
+export interface SuggestionContext {
+	readonly guildId: string;
+	readonly userId: string;
+	readonly locale: string;
+	/** The other values currently entered, possibly unsaved. */
+	readonly values: Readonly<Record<string, unknown>>;
+}
+
+/** A fixed list of suggested values (1 to 25). */
+export interface StaticSuggestions<T> {
+	readonly choices: readonly FieldChoice<T>[];
+}
+
+/** A server-side search. `strict` rejects values the search does not know. */
+export interface DynamicSuggestions<T> {
+	resolve(query: string, ctx: SuggestionContext): Promise<readonly Choice[]>;
+	label?(value: T, ctx: SuggestionContext): Promise<string | undefined>;
+	readonly strict?: boolean;
+}
+
+/** Suggestions offered while a value is typed. */
+export type Suggestions<T> = StaticSuggestions<T> | DynamicSuggestions<T>;
+
+/**
+ * Presentation hints (FR-020). They describe meaning, not layout; surfaces may
+ * ignore them.
+ */
+export interface FieldUi<T = unknown> {
+	/** Id of a group declared on the module. */
+	readonly group?: string;
+	readonly order?: number;
+	/** Preferred control, e.g. `"slider"`. */
+	readonly hint?: string;
+	readonly advanced?: boolean;
+	readonly examples?: readonly T[];
+}
+
+/** Options shared by every field kind. Texts are catalog keys. */
+export interface FieldOptions<T> {
+	/** Required on a module's fields; a list item needs none. */
+	readonly label?: string;
+	readonly description?: string;
+	readonly placeholder?: string;
+	readonly unit?: string;
+	/** Unset until an administrator sets it, unless it has a default. */
+	readonly required?: boolean;
+	readonly default?: T;
+	readonly ui?: FieldUi<T>;
+	/** Opaque access declaration: stored, never enforced here (FR-032). */
+	readonly access?: unknown;
+}
+
+/** Kind-specific constraints of a field. */
+export type FieldSpec =
+	| { readonly kind: "channel"; readonly types?: readonly ChannelKind[] }
+	| { readonly kind: "role" }
+	| { readonly kind: "user" }
+	| { readonly kind: "color" }
+	| { readonly kind: "duration"; readonly min?: number; readonly max?: number }
+	| { readonly kind: "enum"; readonly choices: readonly FieldChoice<string>[] }
+	| {
+			readonly kind: "integer";
+			readonly min?: number;
+			readonly max?: number;
+			readonly suggest?: Suggestions<number>;
+	  }
+	| { readonly kind: "number"; readonly min?: number; readonly max?: number }
+	| {
+			readonly kind: "text";
+			readonly minLength?: number;
+			readonly maxLength?: number;
+			readonly suggest?: Suggestions<string>;
+	  }
+	| { readonly kind: "boolean" }
+	| { readonly kind: "secret" }
+	| {
+			readonly kind: "list";
+			readonly item: AnyField;
+			readonly minItems?: number;
+			readonly maxItems?: number;
+	  }
+	| {
+			readonly kind: "toggles";
+			readonly keys: readonly string[];
+			/** Catalog key of each key's label, by key. */
+			readonly keyLabels?: Readonly<Partial<Record<string, string>>>;
+	  };
+
+/** Every field kind. */
+export type FieldKind = FieldSpec["kind"];
+
+/**
+ * A declared setting: its kind and constraints, its hints and its value type
+ * `T`. Built by the `field` builders; the validation schema behind it stays internal.
+ */
+export interface Field<T, P extends FieldPresence = FieldPresence> {
+	readonly spec: FieldSpec;
+	readonly label?: string;
+	readonly description?: string;
+	readonly placeholder?: string;
+	readonly unit?: string;
+	readonly required: boolean;
+	readonly default?: T;
+	readonly ui?: FieldUi<T>;
+	readonly access?: unknown;
+	/** Type-level only: never set at runtime. */
+	readonly [presence]?: P;
+}
+
+/** Any field, whatever its value type. */
+export type AnyField = Field<unknown>;
+
+/** A secret field: readable by module logic, write-only for surfaces. */
+export type SecretField<P extends FieldPresence = FieldPresence> = Field<string, P> & {
+	readonly spec: { readonly kind: "secret" };
+};
+
+/** Kind-specific options of a channel field. */
+export type ChannelOptions = { readonly types?: readonly ChannelKind[] };
+/** Inclusive numeric bounds of a duration, integer or number field. */
+export type BoundsOptions = { readonly min?: number; readonly max?: number };
+/** Kind-specific options of an integer field. */
+export type IntegerOptions = BoundsOptions & { readonly suggest?: Suggestions<number> };
+/** Kind-specific options of a text field. */
+export type TextOptions = {
+	readonly minLength?: number;
+	readonly maxLength?: number;
+	readonly suggest?: Suggestions<string>;
+};
+/** Kind-specific options of a list field. */
+export type ListOptions = { readonly minItems?: number; readonly maxItems?: number };
+/** Kind-specific options of an enum field. */
+export type EnumOptions<V> = { readonly choices: readonly FieldChoice<V>[] };
+
+/** The value of a toggles field: one boolean per declared key. */
+export type ToggleValues<K extends string> = Readonly<Record<K, boolean>>;
+
+/**
+ * Options of a toggles field. `default` sets some keys; every other key
+ * defaults to `false`, so the field always has a value. `keyLabels` are
+ * catalog keys.
+ */
+export type TogglesOptions<K extends string> = Omit<
+	FieldOptions<ToggleValues<K>>,
+	"default" | "required"
+> & {
+	readonly keys: readonly K[];
+	readonly keyLabels?: Readonly<Partial<Record<K, string>>>;
+	readonly default?: Readonly<Partial<Record<K, boolean>>>;
+};
+
+/** Options of a secret: no default, no examples. */
+export type SecretOptions = Omit<FieldOptions<string>, "default" | "ui"> & {
+	readonly ui?: Omit<FieldUi, "examples">;
+};
+
+/**
+ * The compile-time guard closing every `switch` on a field kind: a new kind
+ * left unhandled makes the call a type error instead of a silent fallthrough.
+ *
+ * @throws Error when reached at runtime, which only a spec built outside the
+ * type system can cause.
+ */
+export function unhandledFieldKind(spec: never): never {
+	throw new Error(`Unhandled field kind: ${(spec as FieldSpec).kind}`);
+}