seedcord 0.14.0 → 0.15.0-next.0

package/dist/index.cjs

@@ -467,7 +467,7 @@ function AutocompleteRoute(...routes) {
 * @example
 * ```typescript
 * \@SelectMenuRoute(SelectMenuKind.User, AssignId)
-* class AssignSelect extends SelectHandler<SelectMenuKind.User, [typeof AssignId]> {
+* class AssignSelect extends SelectMenuHandler<SelectMenuKind.User, [typeof AssignId]> {
 *   // handles user select menus minted from AssignId
 * }
 * ```
@@ -1675,9 +1675,8 @@ var ReplySender = class {
 	async dispatch(response, ephemeral) {
 		if (this.interaction.replied) return await this.interaction.followUp(this.replyOptions(response, ephemeral));
 		if (this.interaction.deferred) {
-			const message = await this.interaction.followUp(this.replyOptions(response, ephemeral));
-			if (!this.interaction.isMessageComponent() && !this.interaction.isModalSubmit()) await this.clearStaleDefer();
-			return message;
+			if (this.interaction.ephemeral === null) return await this.interaction.followUp(this.replyOptions(response, ephemeral));
+			return await this.interaction.editReply(this.editBody(response));
 		}
 		await this.interaction.reply(this.replyOptions(response, ephemeral));
 		return await this.interaction.fetchReply();
@@ -1698,13 +1697,6 @@ var ReplySender = class {
 			...response.files && { files: response.files }
 		};
 	}
-	async clearStaleDefer() {
-		try {
-			await this.interaction.deleteReply();
-		} catch (error) {
-			this.logSwallowed("clear stale defer", error);
-		}
-	}
 	logSwallowed(action, error) {
 		if (error instanceof discord_js.DiscordAPIError && HARMLESS_API_CODES.has(error.code)) {
 			this.logger.debug(`reply ${action} hit harmless code ${error.code}`);
@@ -1939,7 +1931,7 @@ var InteractionMiddleware = class extends BaseHandler {
 * Shared base the typed interaction handlers extend.
 *
 * Not a public entry point. You should be using {@link SlashHandler}, {@link ButtonHandler}, {@link ModalHandler},
-* or {@link SelectHandler} instead. This class only carries the repliable-event plumbing those bases share,
+* or {@link SelectMenuHandler} instead. This class only carries the repliable-event plumbing those bases share,
 * so DO NOT use it directly.
 *
 * @typeParam Repliable - The interaction type this handler processes
@@ -2160,7 +2152,7 @@ var AutocompleteHandler = class extends BaseHandler {
 /**
 * Shared base the customId-routed component handlers extend.
 *
-* Not a public entry point. You should be using {@link ButtonHandler}, {@link SelectHandler}, or
+* Not a public entry point. You should be using {@link ButtonHandler}, {@link SelectMenuHandler}, or
 * {@link ModalHandler} instead. This class only carries the customId decode and route-matching plumbing
 * those bases share, so DO NOT use it directly.
 *
@@ -2276,7 +2268,7 @@ var ButtonHandler = class extends ComponentHandler {};
 var ModalHandler = class extends ComponentHandler {};
 
 //#endregion
-//#region src/handlers/interaction/components/SelectHandler.ts
+//#region src/handlers/interaction/components/SelectMenuHandler.ts
 /**
 * Base class for a select menu handler.
 *
@@ -2291,7 +2283,7 @@ var ModalHandler = class extends ComponentHandler {};
 * @example
 * ```ts
 * \@SelectMenuRoute(SelectMenuKind.User, AssignId)
-* class AssignSelect extends SelectHandler<SelectMenuKind.User, [typeof AssignId]> {
+* class AssignSelect extends SelectMenuHandler<SelectMenuKind.User, [typeof AssignId]> {
 *     async execute() {
 *         const { roleId } = this.params;
 *         await this.event.reply(`assigning ${this.event.values.length} member(s) to <@&${roleId}>`);
@@ -2299,7 +2291,7 @@ var ModalHandler = class extends ComponentHandler {};
 * }
 * ```
 */
-var SelectHandler = class extends ComponentHandler {};
+var SelectMenuHandler = class extends ComponentHandler {};
 
 //#endregion
 //#region src/handlers/event/EventHandler.ts
@@ -2395,6 +2387,239 @@ var EventMiddleware = class extends BaseHandler {
 	}
 };
 
+//#endregion
+//#region src/pagination/controls.ts
+const DEFAULT_LABEL = {
+	first: "First",
+	prev: "Prev",
+	indicator: "",
+	next: "Next",
+	last: "Last"
+};
+const CONTROL_SLOT = {
+	first: 0,
+	prev: 1,
+	indicator: 2,
+	next: 3,
+	last: 4
+};
+const MAX_BUTTONS_PER_ROW = 5;
+var Controls = class {
+	cursor;
+	view;
+	constructor(cursor, view) {
+		this.cursor = cursor;
+		this.view = view;
+	}
+	button(key, cosmetics) {
+		const { target, disabled } = this.navState(key);
+		const defaultLabel = key === "indicator" ? this.indicatorText() : DEFAULT_LABEL[key];
+		const label = cosmetics?.label ?? (key === "indicator" || !cosmetics?.emoji ? defaultLabel : void 0);
+		const button = new discord_js.ButtonBuilder().setCustomId(this.cursor.encode({
+			page: Math.min(Math.max(0, target), _seedcord_kit_internal.PAGE_MAX),
+			slot: CONTROL_SLOT[key]
+		})).setStyle(cosmetics?.style ?? discord_js.ButtonStyle.Secondary).setDisabled(disabled);
+		if (label !== void 0) button.setLabel(label);
+		if (cosmetics?.emoji) button.setEmoji(cosmetics.emoji);
+		return button;
+	}
+	navState(key) {
+		const { page, totalPages, hasPrev, hasNext } = this.view;
+		const knownTotal = totalPages !== void 0;
+		return {
+			target: {
+				first: 0,
+				prev: page - 1,
+				indicator: page,
+				next: page + 1,
+				last: knownTotal ? totalPages - 1 : page
+			}[key],
+			disabled: {
+				first: !hasPrev,
+				prev: !hasPrev,
+				indicator: true,
+				next: !hasNext || page + 1 > _seedcord_kit_internal.PAGE_MAX,
+				last: !hasNext || !knownTotal || totalPages - 1 > _seedcord_kit_internal.PAGE_MAX
+			}[key]
+		};
+	}
+	row(...keys) {
+		if (keys.length < 1) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationEmptyControls);
+		if (keys.length > MAX_BUTTONS_PER_ROW) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationTooManyControls, [keys.length]);
+		const seen = /* @__PURE__ */ new Set();
+		for (const key of keys) {
+			if (seen.has(key)) throw new _seedcord_errors_internal.SeedcordTypeError(_seedcord_errors.SeedcordErrorCode.PaginationDuplicateControls, [key]);
+			seen.add(key);
+		}
+		return new discord_js.ActionRowBuilder().addComponents(keys.map((key) => this.button(key)));
+	}
+	indicatorText() {
+		const { page, totalPages } = this.view;
+		return totalPages === void 0 ? `Page ${page + 1}` : `Page ${page + 1} of ${totalPages}`;
+	}
+};
+
+//#endregion
+//#region src/pagination/render.ts
+var PageContainer = class extends _seedcord_kit.BuilderComponent {
+	constructor(view, renderItem, controlRow) {
+		super("container");
+		const base = view.page * view.perPage;
+		let lines = [];
+		const flush = () => {
+			if (lines.length === 0) return;
+			this.instance.addTextDisplayComponents(new discord_js.TextDisplayBuilder().setContent(lines.join("\n")));
+			lines = [];
+		};
+		view.items.forEach((item, offset) => {
+			const rendered = renderItem(item, base + offset);
+			if (typeof rendered === "string") {
+				lines.push(rendered);
+				return;
+			}
+			flush();
+			this.instance.addSectionComponents(rendered.component);
+		});
+		flush();
+		this.instance.addActionRowComponents(controlRow);
+	}
+};
+function toReplyResponse(renderable) {
+	if (typeof renderable === "string") return { components: [new discord_js.TextDisplayBuilder().setContent(renderable)] };
+	if (Array.isArray(renderable)) return { components: renderable };
+	return renderable;
+}
+const ARRAY_KEYS = [
+	"first",
+	"prev",
+	"indicator",
+	"next",
+	"last"
+];
+const CURSOR_KEYS = [
+	"prev",
+	"indicator",
+	"next"
+];
+/**
+* Build a page's V2 reply. A `render` override builds the whole tree, otherwise the default container lists
+* the items and appends the controls (all five for a known total, prev/indicator/next for a cursor source).
+*/
+function renderPage(view, cursor, config) {
+	const controls = new Controls(cursor, view);
+	if (config.render) return toReplyResponse(config.render(view, controls));
+	return { components: [new PageContainer(view, config.renderItem ?? ((item) => String(item)), controls.row(...view.totalPages === void 0 ? CURSOR_KEYS : ARRAY_KEYS)).component] };
+}
+
+//#endregion
+//#region src/pagination/Paginator.ts
+function contextOf(interaction, core) {
+	return {
+		interaction,
+		user: interaction.user,
+		guild: interaction.guild,
+		...core && { core }
+	};
+}
+/**
+* A restart-proof paginator. Each nav button's customId encodes its full target page, so clicks are
+* idempotent and survive a restart. A persistent `@ButtonRoute` on `Handler` dispatches the clicks.
+*
+* @typeParam Item - The item type, inferred from the source.
+* @typeParam Prefix - The route prefix, inferred from `config.prefix`.
+*
+* @example
+* ```ts
+* export const Bans = new Paginator({
+*     prefix: 'bans',
+*     source: new ArraySource((ctx) => ctx.guild.bans.fetch().then((b) => [...b.values()]), { perPage: 10 }),
+*     renderItem: (ban) => ban.user.tag
+* });
+*
+* \@ButtonRoute(Bans.cursor)
+* export class BansNav extends Bans.Handler {}
+* ```
+*/
+var Paginator = class {
+	/** The page cursor, pass it to your `@ButtonRoute`. */
+	cursor;
+	/** The nav handler base. Extend it with an empty body and decorate it, `@ButtonRoute(p.cursor)`. */
+	Handler;
+	config;
+	constructor(config) {
+		this.cursor = (0, _seedcord_kit_internal.pageCursor)(config.prefix);
+		this.config = config;
+		const loadPage = (ctx, n) => this.page(ctx, n);
+		this.Handler = class Nav extends ButtonHandler {
+			async execute() {
+				await this.event.deferUpdate();
+				const response = await loadPage(contextOf(this.event, this.core), this.params.page);
+				await new ReplySender(this.event).edit(this.event.message, response);
+			}
+		};
+	}
+	/** Render page 0 and send it, picking reply or followUp from the interaction's state. */
+	async start(interaction, core) {
+		const response = await this.page(contextOf(interaction, core), 0);
+		return new ReplySender(interaction).send(response, this.config.ephemeral ?? false);
+	}
+	/** Render a page as a {@link ReplyResponse}. To post it elsewhere, add `flags: MessageFlags.IsComponentsV2`. */
+	async page(ctx, n) {
+		return renderPage(await this.config.source.page(ctx, n), this.cursor, this.config);
+	}
+};
+
+//#endregion
+//#region src/pagination/sources.ts
+const DEFAULT_PER_PAGE = 10;
+/**
+* A source for a bounded list you can load whole. It loads the full list on every click, then slices the
+* page via {@link paginate}, so the real total is known (a real last button, "Page X of Y"). Cache inside
+* your loader if the load is expensive.
+*
+* @typeParam Item - The item type, inferred from the loader's return.
+*/
+var ArraySource = class {
+	load;
+	perPage;
+	constructor(load, opts) {
+		this.load = load;
+		this.perPage = opts?.perPage ?? DEFAULT_PER_PAGE;
+		if (!Number.isInteger(this.perPage) || this.perPage <= 0) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationInvalidPerPage, [this.perPage]);
+	}
+	async page(ctx, n) {
+		return (0, _seedcord_kit.paginate)(await this.load(ctx), n, this.perPage);
+	}
+};
+/**
+* A source for a large or unknown-length set you fetch one page at a time (SQL LIMIT/OFFSET, a paged API).
+* The fetcher receives the page index and the page size and reports whether a next page exists. A cursor
+* source has no cheap total, so `totalPages` is undefined, the last button is omitted, and the indicator
+* reads "Page X".
+*
+* @typeParam Item - The item type, inferred from the fetcher's slice.
+*/
+var CursorSource = class {
+	fetch;
+	perPage;
+	constructor(fetch, opts) {
+		this.fetch = fetch;
+		this.perPage = opts?.perPage ?? DEFAULT_PER_PAGE;
+		if (!Number.isInteger(this.perPage) || this.perPage <= 0) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationInvalidPerPage, [this.perPage]);
+	}
+	async page(ctx, n) {
+		const page = Math.max(0, Math.trunc(n));
+		const { items, hasNext } = await this.fetch(ctx, page, this.perPage);
+		return {
+			items: [...items],
+			page,
+			perPage: this.perPage,
+			hasPrev: page > 0,
+			hasNext
+		};
+	}
+};
+
 //#endregion
 //#region src/subscribers/Subscriber.ts
 /**
@@ -4125,9 +4350,10 @@ var Seedcord = class Seedcord extends Pluggable {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.14.0";
+const version = "0.15.0-next.0";
 
 //#endregion
+exports.ArraySource = ArraySource;
 exports.AutocompleteHandler = AutocompleteHandler;
 exports.AutocompleteRoute = AutocompleteRoute;
 exports.ButtonHandler = ButtonHandler;
@@ -4136,6 +4362,7 @@ exports.CommandMentions = CommandMentions;
 exports.ContextMenuHandler = ContextMenuHandler;
 exports.ContextMenuRoute = ContextMenuRoute;
 exports.Cooldown = Cooldown;
+exports.CursorSource = CursorSource;
 exports.DmOnly = DmOnly;
 exports.Emojis = Emojis;
 exports.EventHandler = EventHandler;
@@ -4152,6 +4379,7 @@ exports.ModalHandler = ModalHandler;
 exports.ModalRoute = ModalRoute;
 exports.Nsfw = Nsfw;
 exports.OwnerOnly = OwnerOnly;
+exports.Paginator = Paginator;
 exports.Pluggable = Pluggable;
 exports.Plugin = Plugin;
 exports.RegisterCommand = RegisterCommand;
@@ -4161,7 +4389,7 @@ exports.RequireBotPermissions = RequireBotPermissions;
 exports.RequirePermissions = RequirePermissions;
 exports.RequireRole = RequireRole;
 exports.Seedcord = Seedcord;
-exports.SelectHandler = SelectHandler;
+exports.SelectMenuHandler = SelectMenuHandler;
 exports.SelectMenuKind = SelectMenuKind;
 exports.SelectMenuRoute = SelectMenuRoute;
 exports.SlashHandler = SlashHandler;