diff --git a/apps/docs/pages/docs/buttonkit.mdx b/apps/docs/pages/docs/buttonkit.mdx index a637910..c36ab2d 100644 --- a/apps/docs/pages/docs/buttonkit.mdx +++ b/apps/docs/pages/docs/buttonkit.mdx @@ -59,17 +59,16 @@ ButtonKit is a class that allows you to use buttons easily by extending native [ import { ButtonKit } from 'commandkit'; import { ButtonStyle, ButtonInteraction } from 'discord.js'; - // create a button + // Create a button const button = new ButtonKit() .setEmoji('👍') .setStyle(ButtonStyle.Primary) - // custom id is required to use onClick - .setCustomId('button'); + .setCustomId('button'); // Required to use onClick - // listen to the button interaction right away + // Listen to the button interaction right away button.onClick( (interaction: ButtonInteraction) => { - // reply to the interaction + // Reply to the interaction interaction.reply('You clicked the button!'); }, { message }, diff --git a/apps/docs/pages/docs/using-signals.mdx b/apps/docs/pages/docs/using-signals.mdx index dc730b7..54cb40e 100644 --- a/apps/docs/pages/docs/using-signals.mdx +++ b/apps/docs/pages/docs/using-signals.mdx @@ -18,45 +18,60 @@ Creating a signal is simple, you just need to call the `createSignal` function f ```js filename="signal.js" copy const { createSignal } = require('commandkit'); - const [value, setValue, dispose] = createSignal(0); + // createValue accepts one param (the initial value) + const [value, setValue, disposeValueSubscribers] = createSignal(0); - console.log(value()); // 0 + // Log the initial value + console.log(value()); // -> 0 + // Update the value setValue(1); - console.log(value()); // 1 + // Log the new value + console.log(value()); // -> 1 - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); ``` ```js filename="signal.js" copy import { createSignal } from 'commandkit'; - const [value, setValue, dispose] = createSignal(0); + // createValue accepts one param (the initial value) + const [value, setValue, disposeValueSubscribers] = createSignal(0); - console.log(value()); // 0 + // Log the initial value + console.log(value()); // -> 0 + // Update the value setValue(1); - console.log(value()); // 1 + // Log the new value + console.log(value()); // -> 1 - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); ``` ```ts filename="signal.ts" copy import { createSignal } from 'commandkit'; - const [value, setValue, dispose] = createSignal(0); + // createValue accepts one param (the initial value) + const [value, setValue, disposeValueSubscribers] = createSignal(0); - console.log(value()); // 0 + // Log the initial value + console.log(value()); // -> 0 + // Update the value setValue(1); - console.log(value()); // 1 + // Log the new value + console.log(value()); // -> 1 - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); ``` @@ -71,57 +86,63 @@ You can also handle side effects with signals, by using the `createEffect` funct ```js filename="signal.js" copy const { createSignal, createEffect } = require('commandkit'); - const [value, setValue, dispose] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { console.log(`Current value is ${value()}`); }); - setValue(1); // This will log "Current value is 1" - setValue(2); // This will log "Current value is 2" + setValue(1); // Logs "Current value is 1" + setValue(2); // Logs "Current value is 2" - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); - setValue(3); // This will not log anything because we disposed the subscribers + // Logs nothing because subscribers were disposed + setValue(3); ``` ```js filename="signal.js" copy import { createSignal, createEffect } from 'commandkit'; - const [value, setValue, dispose] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { console.log(`Current value is ${value()}`); }); - setValue(1); // This will log "Current value is 1" - setValue(2); // This will log "Current value is 2" + setValue(1); // Logs "Current value is 1" + setValue(2); // Logs "Current value is 2" - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); - setValue(3); // This will not log anything because we disposed the subscribers + // Logs nothing because subscribers were disposed + setValue(3); ``` ```ts filename="signal.ts" copy import { createSignal, createEffect } from 'commandkit'; - const [value, setValue, dispose] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { console.log(`Current value is ${value()}`); }); - setValue(1); // This will log "Current value is 1" - setValue(2); // This will log "Current value is 2" + setValue(1); // Logs "Current value is 1" + setValue(2); // Logs "Current value is 2" - dispose(); // dispose subscribers + // Dispose the value's subscribers + disposeValueSubscribers(); - setValue(3); // This will not log anything because we disposed the subscribers + // Logs nothing because subscribers were disposed + setValue(3); ``` @@ -134,59 +155,57 @@ You can also handle side effects with signals, by using the `createEffect` funct ```js filename="commands/counter.js" copy const { createSignal, - createEffect. + createEffect, ButtonKit } = require('commandkit'); const { ButtonStyle, ActionRowBuilder } = require('discord.js'); - export const data = { + exports.data = { name: 'counter', description: 'A simple counter command', }; - // get the buttons function getButtons() { - // decrement button + // Decrement button const dec = new ButtonKit() .setEmoji('➖') .setStyle(ButtonStyle.Primary) .setCustomId('decrement'); - // reset button + // Reset button const reset = new ButtonKit() .setEmoji('0️⃣') .setStyle(ButtonStyle.Primary) .setCustomId('reset'); - // increment button + // Increment button const inc = new ButtonKit() .setEmoji('➕') .setStyle(ButtonStyle.Primary) .setCustomId('increment'); - // dispose button + // Disposal button const trash = new ButtonKit() .setEmoji('🗑️') .setStyle(ButtonStyle.Danger) .setCustomId('trash'); - // action row - const row = new ActionRowBuilder() + // Create an action row + const row = new ActionRowBuilder() .addComponents(dec, reset, inc, trash); return { dec, reset, inc, trash, row }; } - export const run = async ({ interaction }) => { - // create the signal - const [count, setCount, dispose] = createSignal(0); - // create the buttons + exports.run = async ({ interaction }) => { + // Create the signal & buttons + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); - // temporary variable to hold button interactions + // Temporary variable to hold button interactions let inter; - // send the initial message with the buttons + // Send the initial message with the buttons const message = await interaction.reply({ content: `Count is ${count()}`, components: [row], @@ -195,46 +214,46 @@ You can also handle side effects with signals, by using the `createEffect` funct // Now, we subscribe to count signal and update the message every time the count changes createEffect(() => { - // make sure to "always" call the value function inside createEffect, else subscription will not occur + // Make sure to "always" call the value function inside createEffect, otherwise the subscription will not occur const value = count(); - // update the message + // Now udate the original message inter?.update(`Count is ${value}`); }); - // let's add a handler to decrement the count + // Handler to decrement the count dec.onClick((interaction) => { inter = interaction; setCount((prev) => prev - 1); }, { message }); - // let's add a handler to reset the count + // Handler to reset the count reset.onClick((interaction) => { inter = interaction; setCount(0); }, { message }); - // let's add a handler to increment the count + // Handler to increment the count inc.onClick((interaction) => { inter = interaction; setCount((prev) => prev + 1); }, { message }); - // let's add a handler to dispose the buttons and the signal + // Disposal handler trash.onClick(async (interaction) => { const disposed = row.setComponents( row.components.map((button) => { - // remove 'onClick' handler and disable the button + // Remove the 'onClick' handler and disable the button return button .onClick(null) .setDisabled(true); }), ); - // dispose the signal - dispose(); + // Dispose the signal's subscribers + disposeCountSubscribers(); - // finally acknowledge the interaction + // And finally: acknowledge the interaction await interaction.update({ content: 'Finished counting!', components: [disposed], @@ -258,49 +277,47 @@ You can also handle side effects with signals, by using the `createEffect` funct description: 'A simple counter command', }; - // get the buttons function getButtons() { - // decrement button + // Decrement button const dec = new ButtonKit() .setEmoji('➖') .setStyle(ButtonStyle.Primary) .setCustomId('decrement'); - // reset button + // Reset button const reset = new ButtonKit() .setEmoji('0️⃣') .setStyle(ButtonStyle.Primary) .setCustomId('reset'); - // increment button + // Increment button const inc = new ButtonKit() .setEmoji('➕') .setStyle(ButtonStyle.Primary) .setCustomId('increment'); - // dispose button + // Disposal button const trash = new ButtonKit() .setEmoji('🗑️') .setStyle(ButtonStyle.Danger) .setCustomId('trash'); - // action row - const row = new ActionRowBuilder() + // Create an action row + const row = new ActionRowBuilder() .addComponents(dec, reset, inc, trash); return { dec, reset, inc, trash, row }; } export const run = async ({ interaction }) => { - // create the signal - const [count, setCount, dispose] = createSignal(0); - // create the buttons + // Create the signal & buttons + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); - // temporary variable to hold button interactions + // Temporary variable to hold button interactions let inter; - // send the initial message with the buttons + // Send the initial message with the buttons const message = await interaction.reply({ content: `Count is ${count()}`, components: [row], @@ -309,46 +326,46 @@ You can also handle side effects with signals, by using the `createEffect` funct // Now, we subscribe to count signal and update the message every time the count changes createEffect(() => { - // make sure to "always" call the value function inside createEffect, else subscription will not occur + // Make sure to "always" call the value function inside createEffect, otherwise the subscription will not occur const value = count(); - // update the message + // Now udate the original message inter?.update(`Count is ${value}`); }); - // let's add a handler to decrement the count + // Handler to decrement the count dec.onClick((interaction) => { inter = interaction; setCount((prev) => prev - 1); }, { message }); - // let's add a handler to reset the count + // Handler to reset the count reset.onClick((interaction) => { inter = interaction; setCount(0); }, { message }); - // let's add a handler to increment the count + // Handler to increment the count inc.onClick((interaction) => { inter = interaction; setCount((prev) => prev + 1); }, { message }); - // let's add a handler to dispose the buttons and the signal + // Disposal handler trash.onClick(async (interaction) => { const disposed = row.setComponents( row.components.map((button) => { - // remove 'onClick' handler and disable the button + // Remove the 'onClick' handler and disable the button return button .onClick(null) .setDisabled(true); }), ); - // dispose the signal - dispose(); + // Dispose the signal's subscribers + disposeCountSubscribers(); - // finally acknowledge the interaction + // And finally: acknowledge the interaction await interaction.update({ content: 'Finished counting!', components: [disposed], @@ -359,47 +376,46 @@ You can also handle side effects with signals, by using the `createEffect` funct - ```js filename="commands/counter.ts" copy + ```ts filename="commands/counter.ts" copy import { + type SlashCommandProps, createSignal, createEffect, - ButtonKit, - type SlashCommandProps + ButtonKit } from 'commandkit'; - import { ButtonStyle, ActionRowBuilder, type ButtonInteraction } from 'discord.js'; + import { ButtonStyle, ActionRowBuilder } from 'discord.js'; export const data = { name: 'counter', description: 'A simple counter command', }; - // get the buttons function getButtons() { - // decrement button + // Decrement button const dec = new ButtonKit() .setEmoji('➖') .setStyle(ButtonStyle.Primary) .setCustomId('decrement'); - // reset button + // Reset button const reset = new ButtonKit() .setEmoji('0️⃣') .setStyle(ButtonStyle.Primary) .setCustomId('reset'); - // increment button + // Increment button const inc = new ButtonKit() .setEmoji('➕') .setStyle(ButtonStyle.Primary) .setCustomId('increment'); - // dispose button + // Disposal button const trash = new ButtonKit() .setEmoji('🗑️') .setStyle(ButtonStyle.Danger) .setCustomId('trash'); - // action row + // Create an action row const row = new ActionRowBuilder() .addComponents(dec, reset, inc, trash); @@ -407,15 +423,14 @@ You can also handle side effects with signals, by using the `createEffect` funct } export const run = async ({ interaction }: SlashCommandProps) => { - // create the signal - const [count, setCount, dispose] = createSignal(0); - // create the buttons + // Create the signal & buttons + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); - // temporary variable to hold button interactions - let inter: ButtonInteraction; + // Temporary variable to hold button interactions + let inter; - // send the initial message with the buttons + // Send the initial message with the buttons const message = await interaction.reply({ content: `Count is ${count()}`, components: [row], @@ -424,46 +439,46 @@ You can also handle side effects with signals, by using the `createEffect` funct // Now, we subscribe to count signal and update the message every time the count changes createEffect(() => { - // make sure to "always" call the value function inside createEffect, else subscription will not occur + // Make sure to "always" call the value function inside createEffect, otherwise the subscription will not occur const value = count(); - // update the message + // Now udate the original message inter?.update(`Count is ${value}`); }); - // let's add a handler to decrement the count + // Handler to decrement the count dec.onClick((interaction) => { inter = interaction; setCount((prev) => prev - 1); }, { message }); - // let's add a handler to reset the count + // Handler to reset the count reset.onClick((interaction) => { inter = interaction; setCount(0); }, { message }); - // let's add a handler to increment the count + // Handler to increment the count inc.onClick((interaction) => { inter = interaction; setCount((prev) => prev + 1); }, { message }); - // let's add a handler to dispose the buttons and the signal + // Disposal handler trash.onClick(async (interaction) => { const disposed = row.setComponents( row.components.map((button) => { - // remove 'onClick' handler and disable the button + // Remove the 'onClick' handler and disable the button return button .onClick(null) .setDisabled(true); }), ); - // dispose the signal - dispose(); + // Dispose the signal's subscribers + disposeCountSubscribers(); - // finally acknowledge the interaction + // And finally: acknowledge the interaction await interaction.update({ content: 'Finished counting!', components: [disposed], diff --git a/packages/commandkit/tests/commands/misc/count.ts b/packages/commandkit/tests/commands/misc/count.ts index 9971248..9a58841 100644 --- a/packages/commandkit/tests/commands/misc/count.ts +++ b/packages/commandkit/tests/commands/misc/count.ts @@ -40,7 +40,7 @@ function getButtons() { } export async function run({ interaction }: SlashCommandProps) { - const [count, setCount, dispose] = createSignal(0); + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); let inter: ButtonInteraction; @@ -81,7 +81,8 @@ export async function run({ interaction }: SlashCommandProps) { row.components.map((button) => button.onClick(null).setDisabled(true)), ); - dispose(); + // Dispose the count's subscribers + disposeCountSubscribers(); await interaction.update({ content: 'Finished counting!',