Merge pull request #40 from underctrl-io/buttonkit-feat

Add `onEnd` to ButtonKit

Author: twlite

apps/docs/pages/guide/buttonkit.mdx

@@ -6,7 +6,7 @@ ButtonKit is an enhanced version of the native Discord.js [`ButtonBuilder`](http
 
 It is not recommended to use this to listen for button clicks forever since it creates collectors. For that purpose, it's recommended to use a regular "interactionCreate" event listener.
 
-## Usage
+## Handle button clicks
 
 <Tabs items={['CommonJS', 'ESM', 'TypeScript']}>
     <Tabs.Tab>
@@ -98,7 +98,7 @@ In the above example, you may notice how similar `ButtonKit` is to the native Di
 
 Here's an empty `onClick` method without any arguments:
 
-```js
+```js copy
 const myButton = new ButtonKit()
     .setCustomId('custom_button')
     .setLabel('Click me!')
@@ -109,15 +109,15 @@ myButton.onClick();
 
 The first argument required by this function is your handler function which will acknowledge button clicks (interactions) handled by ButtonKit. You can handle them like so:
 
-```js
+```js copy
 myButton.onClick((buttonInteraction) => {
     buttonInteraction.reply('You clicked a button!');
 });
 ```
 
-However, the code above won't actually work since ButtonKit doesn't have any idea where it's supposed to specifically listen button clicks from. To fix that, you need to pass in a second argument which houses all the collector options. The `message` property is the message that ButtonKit will use to listen for button clicks.
+However, the code above won't actually work since ButtonKit doesn't have any idea where it's supposed to specifically listen button clicks from. To fix that, you need to pass in a second argument, also known as your [options](/guide/buttonkit#buttonkit-onclick-options) which houses all the collector configuration. The `message` property is the message that ButtonKit will use to listen for button clicks.
 
-```js
+```js copy
 const row = new ActionRowBuilder().addComponents(myButton);
 const message = await channel.send({ components: [row] });
 
@@ -131,7 +131,7 @@ myButton.onClick(
 
 This also works with interaction replies. Just ensure you pass `fetchReply` alongside your components:
 
-```js
+```js copy
 const row = new ActionRowBuilder().addComponents(myButton);
 const message = await interaction.reply({ components: [row], fetchReply: true });
 
@@ -143,7 +143,7 @@ myButton.onClick(
 );
 ```
 
-## ButtonKit options
+## ButtonKit `onClick` options
 
 ### `message`
 
@@ -154,6 +154,7 @@ The message object that ButtonKit uses to listen for button clicks (interactions
 ### `time` (optional)
 
 -   Type: `number`
+-   Default: `86400000`
 
 The duration (in ms) the collector should run for and listen for button clicks.
 
@@ -166,3 +167,36 @@ Whether or not the collector should automatically reset the timer when a button
 ### Additional optional options
 
 -   Type: [`InteractionCollectorOptions`](https://old.discordjs.dev/#/docs/discord.js/main/typedef/InteractionCollectorOptions)
+
+## Handle collector end
+
+<Callout type="warning">
+    This feature is currently only available in the [development
+    version](/guide/installation#development-version)
+</Callout>
+
+When setting up an `onClick()` method using ButtonKit, you may also want to run some code after the collector ends running. The default timeout is 1 day, but you can modify this in [onClickOptions#time](/guide/buttonkit#time-optional). To handle when the collector ends, you can setup an `onEnd()` method like this:
+
+```js copy {16-21}
+const myButton = new ButtonKit()
+    .setCustomId('custom_button')
+    .setLabel('Click me!')
+    .setStyle(ButtonStyle.Primary);
+
+const row = new ActionRowBuilder().addComponents(myButton);
+const message = await interaction.reply({ components: [row], fetchReply: true });
+
+myButton
+    .onClick(
+        (buttonInteraction) => {
+            buttonInteraction.reply('You clicked a button!');
+        },
+        { message },
+    )
+    .onEnd(() => {
+        console.log('Button collector ended.');
+
+        myButton.setDisabled(true);
+        message.edit({ components: [row] });
+    });
+```

packages/commandkit/src/components/ButtonKit.ts

@@ -15,9 +15,11 @@ import {
  * If the first argument is null, it means that the interaction collector has been destroyed.
  */
 export type CommandKitButtonBuilderInteractionCollectorDispatch = (
-    interaction: ButtonInteraction | null,
+    interaction: ButtonInteraction,
 ) => Awaitable<void>;
 
+export type CommandKitButtonBuilderOnEnd = () => Awaitable<void>;
+
 export type CommandKitButtonBuilderInteractionCollectorDispatchContextData = {
     /**
      * The message to listen for button interactions on.
@@ -35,6 +37,7 @@ export type CommandKitButtonBuilderInteractionCollectorDispatchContextData = {
 
 export class ButtonKit extends ButtonBuilder {
     #onClickHandler: CommandKitButtonBuilderInteractionCollectorDispatch | null = null;
+    #onEndHandler: CommandKitButtonBuilderOnEnd | null = null;
     #contextData: CommandKitButtonBuilderInteractionCollectorDispatchContextData | null = null;
     #collector: InteractionCollector<ButtonInteraction> | null = null;
 
@@ -63,29 +66,38 @@ export class ButtonKit extends ButtonBuilder {
      * button.onClick(null);
      * ```
      */
-    public onClick(handler: null): this;
     public onClick(
         handler: CommandKitButtonBuilderInteractionCollectorDispatch,
-        data: CommandKitButtonBuilderInteractionCollectorDispatchContextData,
-    ): this;
-    public onClick(
-        handler: CommandKitButtonBuilderInteractionCollectorDispatch | null,
         data?: CommandKitButtonBuilderInteractionCollectorDispatchContextData,
     ): this {
         if (this.data.style === ButtonStyle.Link) {
             throw new TypeError('Cannot setup "onClick" handler on link buttons.');
         }
 
+        if (!handler) {
+            throw new TypeError('Cannot setup "onClick" without a handler function parameter.');
+        }
+
         this.#destroyCollector();
 
         this.#onClickHandler = handler;
-        if (handler && data) this.#contextData = data;
+        if (data) this.#contextData = data;
 
         this.#setupInteractionCollector();
 
         return this;
     }
 
+    public onEnd(handler: CommandKitButtonBuilderOnEnd): this {
+        if (!handler) {
+            throw new TypeError('Cannot setup "onEnd" without a handler function parameter.');
+        }
+
+        this.#onEndHandler = handler;
+
+        return this;
+    }
+
     #setupInteractionCollector() {
         if (!this.#contextData || !this.#onClickHandler) return;
 
@@ -133,11 +145,11 @@ export class ButtonKit extends ButtonBuilder {
 
         this.#collector.on('end', () => {
             this.#destroyCollector();
+            this.#onEndHandler?.();
         });
     }
 
     #destroyCollector() {
-        this.#onClickHandler?.(null);
         this.#collector?.stop('end');
         this.#collector?.removeAllListeners();
         this.#collector = null;

packages/commandkit/tests/src/commands/misc/ping.ts

@@ -28,6 +28,7 @@ const tests = Array.from({ length: 10 }, (_, i) => ({
 
 export async function autocomplete({ interaction }: AutocompleteProps) {
     const arg = interaction.options.getString('test', false);
+    console.log(arg);
     if (!arg) return interaction.respond(tests);
 
     const filtered = tests.filter((test) => test.name.toLowerCase().includes(arg.toLowerCase()));
@@ -51,30 +52,26 @@ export async function run({ interaction, client }: SlashCommandProps) {
         fetchReply: true,
     });
 
-    button.onClick(
-        (inter) => {
-            if (!inter) {
-                button.setDisabled(true);
-                message.edit({
-                    components: [row],
-                });
-                return;
-            }
+    button
+        .onClick(
+            (inter) => {
+                console.log('onClick called');
 
-            inter.reply({
-                content: 'You clicked the ping button!',
-                ephemeral: true,
-            });
-        },
-        { message, time: 10_000, autoReset: true },
-    );
+                inter.reply({
+                    content: 'You clicked the ping button!',
+                    ephemeral: true,
+                });
+            },
+            { message, time: 10_000, autoReset: true },
+        )
+        .onEnd(() => {
+            console.log('onEnd called');
 
-    // interaction.reply(`:ping_pong: Pong! \`${client.ws.ping}ms\``);
+            button.setDisabled(true);
+            message.edit({ components: [row] });
+        });
 }
 
 export const options: CommandOptions = {
     devOnly: true,
-
-    // Test deprecation warning.
-    guildOnly: true,
 };

packages/commandkit/tests/src/index.ts

@@ -1,8 +1,6 @@
 import { CommandKit } from '../../src/index';
 import { Client } from 'discord.js';
 
-require('dotenv/config');
-
 const client = new Client({
     intents: ['Guilds', 'GuildMembers', 'GuildMessages', 'MessageContent'],
 });

packages/commandkit/tests/src/validations/devOnly.ts

@@ -2,8 +2,8 @@ import type { ValidationProps } from '../../../src';
 
 export default function ({ interaction, commandObj, handler }: ValidationProps) {
     if (interaction.isAutocomplete()) return;
-    if (commandObj.data.name === 'ping') {
-        interaction.reply('blocked...');
-        return true;
-    }
+    // if (commandObj.data.name === 'ping') {
+    //     interaction.reply('blocked...');
+    //     return true;
+    // }
 }