@azurioh/discord-kernel 0.1.0 → 1.0.0

package/dist/settings/field-order.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.displayOrder = displayOrder;
+/** Rank of an item no hint places: after every ranked one. */
+const UNRANKED = Number.MAX_SAFE_INTEGER;
+/**
+ * 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.
+ */
+function displayOrder(declaration) {
+    const fieldKeys = Object.keys(declaration.fields);
+    const slots = [];
+    const firstField = new Map();
+    const members = new Map();
+    const loose = [];
+    fieldKeys.forEach((key, index) => {
+        const ui = declaration.fields[key]?.ui;
+        const ranked = { 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) => {
+        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) {
+    const { declaration, firstField, fieldCount } = params;
+    const groupOrder = declaration.ui?.groupOrder ?? [];
+    const ranked = Object.entries(declaration.groups ?? {}).map(([id, group], index) => {
+        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(ranked) {
+    return [...ranked].sort(compareRanked).map((entry) => entry.item);
+}
+function compareRanked(left, right) {
+    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) {
+    throw new Error(`Unhandled display slot: ${String(slot)}`);
+}
+//# sourceMappingURL=field-order.js.map

package/dist/settings/field-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-order.js","sourceRoot":"","sources":["../../src/settings/field-order.ts"],"names":[],"mappings":"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"}

package/dist/settings/field-search.d.ts

@@ -0,0 +1,10 @@
+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 declare function fieldSearch(spec: FieldSpec): DynamicSuggestions<unknown> | undefined;
+//# sourceMappingURL=field-search.d.ts.map

package/dist/settings/field-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-search.d.ts","sourceRoot":"","sources":["../../src/settings/field-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,SAAS,CAMpF"}

package/dist/settings/field-search.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldSearch = fieldSearch;
+/**
+ * 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.
+ */
+function fieldSearch(spec) {
+    if (spec.kind !== "integer" && spec.kind !== "text") {
+        return undefined;
+    }
+    const { suggest } = spec;
+    return suggest === undefined || "choices" in suggest ? undefined : suggest;
+}
+//# sourceMappingURL=field-search.js.map

package/dist/settings/field-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-search.js","sourceRoot":"","sources":["../../src/settings/field-search.ts"],"names":[],"mappings":";;AASA,kCAMC;AAbD;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,IAAe;IAC1C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACrD,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACzB,OAAO,OAAO,KAAK,SAAS,IAAI,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC5E,CAAC"}

package/dist/settings/fields/builders.d.ts

@@ -0,0 +1,41 @@
+import type { BoundsOptions, ChannelOptions, EnumOptions, Field, FieldOptions, 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">;
+}
+/**
+ * Builders for every setting kind. Channel, role and user values are
+ * snowflake strings; texts in the options are catalog keys.
+ */
+export declare const field: FieldBuilders;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/settings/fields/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/settings/fields/builders.ts"],"names":[],"mappings":"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"}

package/dist/settings/fields/builders.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.field = void 0;
+/**
+ * Assemble a field from its constraints and common options. The presence is
+ * `never` here: the builder overloads narrow it from the options.
+ */
+function createField(spec, options) {
+    return { ...options, spec, required: options.required ?? false };
+}
+function channelField(options = {}) {
+    const { types, ...common } = options;
+    return createField({ kind: "channel", types }, common);
+}
+function roleField(options = {}) {
+    return createField({ kind: "role" }, options);
+}
+function userField(options = {}) {
+    return createField({ kind: "user" }, options);
+}
+function colorField(options = {}) {
+    return createField({ kind: "color" }, options);
+}
+function durationField(options = {}) {
+    const { min, max, ...common } = options;
+    return createField({ kind: "duration", min, max }, common);
+}
+function enumField(options) {
+    const { choices, ...common } = options;
+    return createField({ kind: "enum", choices }, common);
+}
+function integerField(options = {}) {
+    const { min, max, suggest, ...common } = options;
+    return createField({ kind: "integer", min, max, suggest }, common);
+}
+function numberField(options = {}) {
+    const { min, max, ...common } = options;
+    return createField({ kind: "number", min, max }, common);
+}
+function textField(options = {}) {
+    const { minLength, maxLength, suggest, ...common } = options;
+    return createField({ kind: "text", minLength, maxLength, suggest }, common);
+}
+function booleanField(options = {}) {
+    return createField({ kind: "boolean" }, options);
+}
+function secretField(options = {}) {
+    return { ...options, spec: { kind: "secret" }, required: options.required ?? false };
+}
+function listField(item, options = {}) {
+    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(options) {
+    const { keys, keyLabels, default: defaults, ...common } = options;
+    const off = Object.fromEntries(keys.map((key) => [key, false]));
+    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.
+ */
+exports.field = {
+    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,
+};
+//# sourceMappingURL=builders.js.map

package/dist/settings/fields/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/settings/fields/builders.ts"],"names":[],"mappings":";;;AA4DA;;;GAGG;AACH,SAAS,WAAW,CAAI,IAAe,EAAE,OAAwB;IAChE,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,YAAY,CAAC,UAAiD,EAAE;IACxE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACrC,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,SAAS,CAAC,UAAgC,EAAE;IACpD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,UAAgC,EAAE;IACpD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,UAAU,CAAC,UAAgC,EAAE;IACrD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,UAAgD,EAAE;IACxE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACxC,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,SAAS,CAAmB,OAAyC;IAC7E,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACvC,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,YAAY,CAAC,UAAiD,EAAE;IACxE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACjD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,WAAW,CAAC,UAAgD,EAAE;IACtE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACxC,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,SAAS,CAAC,UAA8C,EAAE;IAClE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAC7D,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,YAAY,CAAC,UAAiC,EAAE;IACxD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,WAAW,CAAC,UAAyB,EAAE;IAC/C,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;AACtF,CAAC;AAED,SAAS,SAAS,CACjB,IAAc,EACd,UAAoD,EAAE;IAEtD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAClD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CACpB,OAA0B;IAE1B,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAuB,CAAC;IACtF,OAAO,WAAW,CACjB,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,EACpC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,GAAG,QAAQ,EAAE,EAAE,CAC/C,CAAC;AACH,CAAC;AAED;;;GAGG;AACU,QAAA,KAAK,GAAkB;IACnC,OAAO,EAAE,YAAY;IACrB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,YAAY;CACrB,CAAC"}

package/dist/settings/fields/field.d.ts

@@ -0,0 +1,199 @@
+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 declare const FIELD_LIMITS: {
+    /** Longest text a Discord text input accepts. */
+    readonly textMaxLength: 4000;
+    /** Most items a list field may hold (one select menu). */
+    readonly listMaxItems: 25;
+    /** Most static choices an enum or a suggestion list may declare (one select menu). */
+    readonly staticChoices: 25;
+};
+/** Kinds a list field may hold. */
+export declare const LIST_ITEM_KINDS: readonly FieldKind[];
+/**
+ * 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 declare function unhandledFieldKind(spec: never): never;
+export {};
+//# sourceMappingURL=field.d.ts.map

package/dist/settings/fields/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/settings/fields/field.ts"],"names":[],"mappings":"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"}

package/dist/settings/fields/field.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_ITEM_KINDS = exports.FIELD_LIMITS = void 0;
+exports.unhandledFieldKind = unhandledFieldKind;
+/** Discord's hard limits that a declaration must stay within. */
+exports.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,
+};
+/** Kinds a list field may hold. */
+exports.LIST_ITEM_KINDS = [
+    "channel",
+    "role",
+    "user",
+    "enum",
+    "integer",
+    "text",
+];
+/**
+ * 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.
+ */
+function unhandledFieldKind(spec) {
+    throw new Error(`Unhandled field kind: ${spec.kind}`);
+}
+//# sourceMappingURL=field.js.map

package/dist/settings/fields/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../../../src/settings/fields/field.ts"],"names":[],"mappings":";;;AA0MA,gDAEC;AAzMD,iEAAiE;AACpD,QAAA,YAAY,GAAG;IAC3B,iDAAiD;IACjD,aAAa,EAAE,IAAI;IACnB,0DAA0D;IAC1D,YAAY,EAAE,EAAE;IAChB,sFAAsF;IACtF,aAAa,EAAE,EAAE;CACR,CAAC;AAEX,mCAAmC;AACtB,QAAA,eAAe,GAAyB;IACpD,SAAS;IACT,MAAM;IACN,MAAM;IACN,MAAM;IACN,SAAS;IACT,MAAM;CACN,CAAC;AA8KF;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,IAAW;IAC7C,MAAM,IAAI,KAAK,CAAC,yBAA0B,IAAkB,CAAC,IAAI,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/settings/fields/zod-schema.d.ts

@@ -0,0 +1,67 @@
+import { type AnyField } from "../../settings/fields/field";
+import type { SettingsIssueCode } from "../../settings/settings-validation-error";
+/** Why one value failed its field's own validation, before any guild check. */
+export interface FieldValueIssue {
+    /**
+     * Path inside the value: `[]` for the value, `[i]` for a list item, `[key]`
+     * for a toggle.
+     */
+    readonly path: readonly (number | string)[];
+    readonly code: SettingsIssueCode;
+    /** `{ min }` or `{ max }` for bound codes, empty otherwise. */
+    readonly params: Readonly<Record<string, number>>;
+}
+/** Outcome of {@link parseFieldValue}: the stored form of the value, or its issues. */
+export type FieldParseResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly issues: readonly FieldValueIssue[];
+};
+/**
+ * Check a value against its field's kind and constraints (kind, bounds,
+ * lengths, list size, duplicates, enum membership, toggle keys) and turn it
+ * into its stored form: a colour becomes `#rrggbb`, a duration whole seconds,
+ * toggles a boolean for every declared key (a missing key takes its default).
+ *
+ * @param params.field - the field the value belongs to.
+ * @param params.value - the raw value, of any type.
+ * @returns the stored value, or every issue found.
+ */
+export declare function parseFieldValue(params: {
+    field: AnyField;
+    value: unknown;
+}): FieldParseResult;
+/**
+ * Drop from a stored value what its field no longer declares, so it reads as
+ * if the key had never been stored (FR-017): a toggle whose key left `keys`.
+ * Any other value is returned as is. Submissions skip this step, so an
+ * undeclared toggle there stays `unknownChoice`.
+ *
+ * @param params.field - the field the stored value belongs to.
+ * @param params.value - the value as read from storage, of any type.
+ * @returns the value without its undeclared toggles.
+ */
+export declare function pruneStoredValue(params: {
+    field: AnyField;
+    value: unknown;
+}): unknown;
+/** One JSON Schema object, open to in-place annotation. */
+export type JsonSchemaNode = Record<string, unknown>;
+/**
+ * Describe the stored values of a set of fields as a JSON Schema draft 2020-12
+ * object: each field's kind and constraints, a field without `required` being
+ * optional, and no undeclared key. The field's own texts and hints are added
+ * by `annotate`, called once for each field and each list item on the schema
+ * that describes it.
+ *
+ * @param params.fields - the fields, by key.
+ * @param params.annotate - adds a field's annotations to its schema, in place.
+ * @returns the JSON Schema document, with `$schema`.
+ */
+export declare function fieldsJsonSchema(params: {
+    fields: Readonly<Record<string, AnyField>>;
+    annotate: (field: AnyField, schema: JsonSchemaNode) => void;
+}): JsonSchemaNode;
+//# sourceMappingURL=zod-schema.d.ts.map

package/dist/settings/fields/zod-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-schema.d.ts","sourceRoot":"","sources":["../../../src/settings/fields/zod-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,KAAK,QAAQ,EAKb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAW9E,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,CAAC;AAIvE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,CAM7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAOrF;AAED,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACxC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3C,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5D,GAAG,cAAc,CAyBjB"}