Docs and emoji tagged template literal function

Author: dahlia

CHANGES.md

@@ -25,6 +25,7 @@ To be released.
 
      -  Added `Emoji` type.
      -  Added `isEmoji()` predicate function.
+     -  Added `emoji()` tagged template literal function.
      -  Added `Message.react()` method.
      -  Added `Reaction` interface.
      -  Added `AuthorizedReaction` interface.

docs/concepts/message.md

@@ -535,6 +535,59 @@ await like.unlike();  // [!code highlight]
 ~~~~
 
 
+Reacting to a message with an emoji
+-----------------------------------
+
+*This API is available since BotKit 0.2.0.*
+
+You can react to a message with an emoji by calling the `~Message.react()`
+method:
+
+~~~~ typescript
+const message = await session.publish(
+  text`This message will be reacted to with an emoji.`
+);
+await message.react(emoji`👍`);  // [!code highlight]
+~~~~
+
+> [!NOTE]
+> The tagged template literal function `emoji()` takes a string and returns
+> an `Emoji` value, which is a brand of `string`.  If it takes anything other
+> than a single emoji, it will throw a `TypeError` at runtime.
+
+Or you can use the `~Message.react()` method with a custom emoji.  You need to
+define custom emojis in advance by calling the `Bot.addCustomEmojis()` method:
+
+~~~~ typescript
+const emojis = bot.addCustomEmojis({
+  // Use a remote image URL:
+  yesBlob: {
+    url: "https://cdn3.emoji.gg/emojis/68238-yesblob.png",
+    mediaType: "image/png",
+  },
+  // Use a local image file:
+  noBlob: {
+    file: `${import.meta.dirname}/emojis/no_blob.png`,
+    mediaType: "image/webp",
+  },
+});
+~~~~
+
+Then you can use the custom emojis in the `~Message.react()` method:
+
+~~~~ typescript
+await message.react(emojis.yesBlob);
+~~~~
+
+If you need to undo the reaction, you can call
+the `~AuthorizedReaction.unreact()` method:
+
+~~~~ typescript
+const reaction = await message.react(emojis.noBlob);
+await reaction.unreact();  // [!code highlight]
+~~~~
+
+
 Replying to a message
 ---------------------
 

src/emoji.test.ts

@@ -15,7 +15,7 @@
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 import { assert } from "@std/assert/assert";
 import { assertFalse } from "@std/assert/false";
-import { isEmoji } from "./emoji.ts";
+import { emoji, isEmoji } from "./emoji.ts";
 
 Deno.test("isEmoji() with valid emojis", () => {
   const validEmojis = [
@@ -112,3 +112,47 @@ Deno.test("isEmoji() with tricky invalid inputs", () => {
     );
   }
 });
+Deno.test("emoji() tagged template function with valid emojis", () => {
+  const validEmojis = [
+    emoji`😀`, // simple emoji
+    emoji`👍`, // thumbs up
+    emoji`🚀`, // rocket
+    emoji`🏳️‍🌈`, // pride flag
+    emoji`👨‍👩‍👧‍👦`, // family
+    emoji`👩🏽‍🔬`, // woman scientist with medium skin tone
+    emoji`🧘🏻‍♀️`, // woman in lotus position
+    emoji`🇯🇵`, // flag
+  ];
+
+  for (const emojiValue of validEmojis) {
+    assert(isEmoji(emojiValue));
+  }
+});
+
+Deno.test("emoji() tagged template function with interpolation", () => {
+  const rocket = "🚀";
+  const result = emoji`${rocket}`;
+  assert(isEmoji(result));
+  assert(result === "🚀");
+});
+
+Deno.test("emoji() throws with invalid inputs", () => {
+  const invalidInputs = [
+    () => emoji`😀😀`, // multiple emojis
+    () => emoji`hi😀`, // mixed content
+    () => emoji`👍awesome`, // mixed content
+    () => emoji` 😀`, // emoji with leading space
+    () => emoji`😀 `, // emoji with trailing space
+    () => emoji``, // empty string
+  ];
+
+  for (const fn of invalidInputs) {
+    try {
+      fn();
+      assert(false, "Expected function to throw TypeError");
+    } catch (error) {
+      assert(error instanceof TypeError);
+      assert(error.message.startsWith("Invalid emoji:"));
+    }
+  }
+});

src/emoji.ts

@@ -46,6 +46,27 @@ export function isEmoji(value: unknown): value is Emoji {
   return /\p{Emoji}/u.test(segments[0].segment);
 }
 
+/**
+ * A tagged template literal function that creates an {@link Emoji} from
+ * a string.  It is a simple wrapper around the `String.raw` function,
+ * but it also checks if the resulting string is a valid emoji.
+ * @param strings The template strings.
+ * @param values The values to interpolate into the template strings.
+ * @returns The resulting {@link Emoji} value.
+ * @throws {TypeError} If the resulting string is not a valid emoji.
+ * @since 0.2.0
+ */
+export function emoji(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): Emoji {
+  const result = String.raw(strings, ...values);
+  if (!isEmoji(result)) {
+    throw new TypeError(`Invalid emoji: ${result}`);
+  }
+  return result;
+}
+
 /**
  * The common interface for defining custom emojis.
  * @since 0.2.0

src/message-impl.test.ts

@@ -39,7 +39,7 @@ import { assertEquals } from "@std/assert/equals";
 import { assertInstanceOf } from "@std/assert/instance-of";
 import { assertRejects } from "@std/assert/rejects";
 import { BotImpl } from "./bot-impl.ts";
-import { type DeferredCustomEmoji, isEmoji } from "./emoji.ts";
+import { type DeferredCustomEmoji, emoji } from "./emoji.ts";
 import {
   createMessage,
   getMessageClass,
@@ -609,9 +609,7 @@ Deno.test("MessageImpl.react()", async (t) => {
 
   await t.step("react() with string emoji", async () => {
     ctx.sentActivities = []; // Clear previous activities
-    const emoji = "👍";
-    assert(isEmoji(emoji));
-    const reaction = await message.react(emoji);
+    const reaction = await message.react(emoji`👍`);
     assertEquals(ctx.sentActivities.length, 2);
     const { recipients, activity } = ctx.sentActivities[0];
     assertEquals(recipients, "followers");
@@ -629,7 +627,7 @@ Deno.test("MessageImpl.react()", async (t) => {
     assertEquals(reaction.raw, activity);
     assertEquals(reaction.id, activity.id);
     assertEquals(reaction.message, message);
-    assertEquals(reaction.emoji, emoji);
+    assertEquals(reaction.emoji, emoji`👍`);
 
     // Test unreact
     ctx.sentActivities = [];

src/message-impl.ts

@@ -22,7 +22,7 @@ import {
   Create,
   Delete,
   Document,
-  Emoji as CustomEmoji,
+  type Emoji as CustomEmoji,
   EmojiReact,
   Hashtag,
   isActor,
@@ -41,7 +41,7 @@ import type { LanguageTag } from "@phensley/language-tag";
 import { unescape } from "@std/html/entities";
 import { generate as uuidv7 } from "@std/uuid/unstable-v7";
 import { FilterXSS, getDefaultWhiteList } from "xss";
-import { DeferredCustomEmoji, Emoji } from "./emoji.ts";
+import type { DeferredCustomEmoji, Emoji } from "./emoji.ts";
 import type {
   AuthorizedMessage,
   AuthorizedSharedMessage,

src/message.ts

@@ -25,7 +25,7 @@ import type {
   Question,
 } from "@fedify/fedify/vocab";
 import type { LanguageTag } from "@phensley/language-tag";
-import { DeferredCustomEmoji, Emoji } from "./emoji.ts";
+import type { DeferredCustomEmoji, Emoji } from "./emoji.ts";
 import type { AuthorizedLike, AuthorizedReaction } from "./reaction.ts";
 import type {
   SessionPublishOptions,

src/mod.ts

@@ -36,6 +36,7 @@ export {
   type CustomEmoji,
   type DeferredCustomEmoji,
   type Emoji,
+  emoji,
   isEmoji,
 } from "./emoji.ts";
 export type * from "./events.ts";

src/reaction.ts

@@ -21,7 +21,7 @@ import type {
 } from "@fedify/fedify/vocab";
 import type { Emoji } from "./emoji.ts";
 import type { Message, MessageClass } from "./message.ts";
-export { type Actor, Like as RawLike } from "@fedify/fedify/vocab";
+export { type Actor, EmojiReact, Like as RawLike } from "@fedify/fedify/vocab";
 
 /**
  * A like of a message.  It is a thin wrapper around a `Like`, which is