From 082226919a648a98916ad4265d1cc4a26d6e52c0 Mon Sep 17 00:00:00 2001 From: m1-dev <=> Date: Mon, 6 Nov 2023 16:06:09 +0200 Subject: [PATCH 1/2] docs: update ButtonKit & fix documentation for signals --- apps/docs/pages/docs/buttonkit.mdx | 9 +- apps/docs/pages/docs/using-signals.mdx | 215 +++++++++++++------------ 2 files changed, 119 insertions(+), 105 deletions(-) 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..7178b1d 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, disposeValue] = 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 subscribers + disposeValue(); ``` ```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, disposeValue] = 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 subscribers + disposeValue(); ``` ```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, disposeValue] = 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 subscribers + disposeValue(); ``` @@ -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, disposeValue] = 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 subscribers + disposeValue(); - 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, disposeValue] = 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 subscribers + disposeValue(); - 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, disposeValue] = 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 subscribers + disposeValue(); - 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, disposeCount] = 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 + disposeCount(); - // 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, disposeCount] = 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 + disposeCount(); - // 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, disposeCount] = 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 + disposeCount(); - // finally acknowledge the interaction + // And finally: acknowledge the interaction await interaction.update({ content: 'Finished counting!', components: [disposed], From bd531428dbe97f2f149901c0ee0cab9246a5d6e6 Mon Sep 17 00:00:00 2001 From: m1-dev <=> Date: Thu, 9 Nov 2023 22:07:29 +0200 Subject: [PATCH 2/2] chore(docs/signals): use more descriptive names --- apps/docs/pages/docs/using-signals.mdx | 54 +++++++++---------- .../commandkit/tests/commands/misc/count.ts | 5 +- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/apps/docs/pages/docs/using-signals.mdx b/apps/docs/pages/docs/using-signals.mdx index 7178b1d..54cb40e 100644 --- a/apps/docs/pages/docs/using-signals.mdx +++ b/apps/docs/pages/docs/using-signals.mdx @@ -19,7 +19,7 @@ Creating a signal is simple, you just need to call the `createSignal` function f const { createSignal } = require('commandkit'); // createValue accepts one param (the initial value) - const [value, setValue, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // Log the initial value console.log(value()); // -> 0 @@ -30,8 +30,8 @@ Creating a signal is simple, you just need to call the `createSignal` function f // Log the new value console.log(value()); // -> 1 - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); ``` @@ -39,7 +39,7 @@ Creating a signal is simple, you just need to call the `createSignal` function f import { createSignal } from 'commandkit'; // createValue accepts one param (the initial value) - const [value, setValue, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // Log the initial value console.log(value()); // -> 0 @@ -50,8 +50,8 @@ Creating a signal is simple, you just need to call the `createSignal` function f // Log the new value console.log(value()); // -> 1 - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); ``` @@ -59,7 +59,7 @@ Creating a signal is simple, you just need to call the `createSignal` function f import { createSignal } from 'commandkit'; // createValue accepts one param (the initial value) - const [value, setValue, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // Log the initial value console.log(value()); // -> 0 @@ -70,8 +70,8 @@ Creating a signal is simple, you just need to call the `createSignal` function f // Log the new value console.log(value()); // -> 1 - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); ``` @@ -86,7 +86,7 @@ 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, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { @@ -96,8 +96,8 @@ You can also handle side effects with signals, by using the `createEffect` funct setValue(1); // Logs "Current value is 1" setValue(2); // Logs "Current value is 2" - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); // Logs nothing because subscribers were disposed setValue(3); @@ -107,7 +107,7 @@ You can also handle side effects with signals, by using the `createEffect` funct ```js filename="signal.js" copy import { createSignal, createEffect } from 'commandkit'; - const [value, setValue, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { @@ -117,8 +117,8 @@ You can also handle side effects with signals, by using the `createEffect` funct setValue(1); // Logs "Current value is 1" setValue(2); // Logs "Current value is 2" - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); // Logs nothing because subscribers were disposed setValue(3); @@ -128,7 +128,7 @@ You can also handle side effects with signals, by using the `createEffect` funct ```ts filename="signal.ts" copy import { createSignal, createEffect } from 'commandkit'; - const [value, setValue, disposeValue] = createSignal(0); + const [value, setValue, disposeValueSubscribers] = createSignal(0); // This will run every time the value changes createEffect(() => { @@ -138,8 +138,8 @@ You can also handle side effects with signals, by using the `createEffect` funct setValue(1); // Logs "Current value is 1" setValue(2); // Logs "Current value is 2" - // Dispose subscribers - disposeValue(); + // Dispose the value's subscribers + disposeValueSubscribers(); // Logs nothing because subscribers were disposed setValue(3); @@ -199,7 +199,7 @@ You can also handle side effects with signals, by using the `createEffect` funct exports.run = async ({ interaction }) => { // Create the signal & buttons - const [count, setCount, disposeCount] = createSignal(0); + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); // Temporary variable to hold button interactions @@ -250,8 +250,8 @@ You can also handle side effects with signals, by using the `createEffect` funct }), ); - // Dispose the signal - disposeCount(); + // Dispose the signal's subscribers + disposeCountSubscribers(); // And finally: acknowledge the interaction await interaction.update({ @@ -311,7 +311,7 @@ You can also handle side effects with signals, by using the `createEffect` funct export const run = async ({ interaction }) => { // Create the signal & buttons - const [count, setCount, disposeCount] = createSignal(0); + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); // Temporary variable to hold button interactions @@ -362,8 +362,8 @@ You can also handle side effects with signals, by using the `createEffect` funct }), ); - // Dispose the signal - disposeCount(); + // Dispose the signal's subscribers + disposeCountSubscribers(); // And finally: acknowledge the interaction await interaction.update({ @@ -424,7 +424,7 @@ You can also handle side effects with signals, by using the `createEffect` funct export const run = async ({ interaction }: SlashCommandProps) => { // Create the signal & buttons - const [count, setCount, disposeCount] = createSignal(0); + const [count, setCount, disposeCountSubscribers] = createSignal(0); const { dec, reset, inc, trash, row } = getButtons(); // Temporary variable to hold button interactions @@ -475,8 +475,8 @@ You can also handle side effects with signals, by using the `createEffect` funct }), ); - // Dispose the signal - disposeCount(); + // Dispose the signal's subscribers + disposeCountSubscribers(); // And finally: acknowledge the interaction await interaction.update({ 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!',