@quitscope/discord-welcomecard 0.2.0 → 0.2.1

package/README.md

@@ -1,102 +1,112 @@
-# @quitscope/discord-welcomecard
-
-Render Discord welcome cards as static **PNG** or animated **GIF** from one builder.
-
-![centered preset](examples/centered.png)
-
-- **One API, two outputs** — the same builder renders `.toPNG()` and `.toGIF()`.
-- **Animated GIFs** — background sheen, text fade-in, pulsing avatar glow. Autoplays in Discord.
-- **No compile pain** — built on `@napi-rs/canvas` (prebuilt binaries, no node-gyp).
-- **Bundled font** — cards look the same on every server.
-- **TypeScript** — full types, ESM + CJS.
-
-## Install
-
-```bash
-npm install @quitscope/discord-welcomecard
-```
-
-## Usage
-
-```ts
-import { WelcomeCard } from '@quitscope/discord-welcomecard';
-import { toAttachment } from '@quitscope/discord-welcomecard/discord';
-
-const card = new WelcomeCard()
-  .setPreset('centered')
-  .setUsername('Quit')
-  .setAvatar('https://cdn.discordapp.com/avatars/.../avatar.png')
-  .setSubtitle('Welcome to the server!')
-  .setMemberCount(1234)
-  .setTheme('dark')
-  .setAnimations(['background', 'text', 'avatar']);
-
-const png = await card.toPNG();
-const gif = await card.toGIF();
-
-// discord.js
-channel.send({ files: [toAttachment(gif, 'welcome.gif')] });
-```
-
-### With discord.js events
-
-```ts
-client.on('guildMemberAdd', async (member) => {
-  const gif = await new WelcomeCard()
-    .setUsername(member.user.displayName)
-    .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 256 }))
-    .setSubtitle(`Welcome to ${member.guild.name}!`)
-    .setMemberCount(member.guild.memberCount)
-    .setAnimations(['text', 'avatar'])
-    .toGIF();
-
-  const channel = member.guild.systemChannel;
-  channel?.send({ files: [toAttachment(gif, 'welcome.gif')] });
-});
-```
-
-## Presets
-
-| `centered` (default) | `neon` |
-| --- | --- |
-| ![centered](examples/centered.png) | ![neon](examples/neon.png) |
-
-| `minimal` | `hero` |
-| --- | --- |
-| ![minimal](examples/minimal.png) | ![hero](examples/hero.png) |
-
-## Animated
-
-`setAnimations([...])` + `toGIF()` — background sheen, text fade-in, avatar glow:
-
-![animated](examples/animated.gif)
-
-## API
-
-| Method | Description |
-| --- | --- |
-| `setPreset(name)` | `'centered'` (default), `'neon'`, `'minimal'`, `'hero'` |
-| `setUsername(name)` | Main text (required) |
-| `setAvatar(urlOrBuffer)` | Avatar image; falls back to a colored circle if it fails to load |
-| `setSubtitle(text)` | Secondary line, e.g. "Welcome to the server!" |
-| `setMemberCount(n)` | Renders "MEMBER #n" — optional, omit to hide |
-| `setMemberCountPosition(pos)` | 3×3 grid: `'top-left'`, `'top-center'`, `'top-right'`, `'center-left'`, `'center'`, `'center-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`. `'corner'` is an alias for `'bottom-right'`. Defaults: `'bottom-center'` in the centered presets, `'bottom-right'` in `hero`. |
-| `setBackground(value)` | Hex color (`#1e1e2e`) or image URL |
-| `setTheme(theme)` | `'dark'` (default) or `'light'` |
-| `setFont({ family, color, size })` | Override the bundled font settings |
-| `setAnimations(list)` | Any of `'background'`, `'text'`, `'avatar'` — used by `toGIF()` |
-| `toPNG()` | `Promise<Buffer>` — static card |
-| `toGIF()` | `Promise<Buffer>` — animated card |
-
-The `toAttachment(buffer, name?)` helper lives in `@quitscope/discord-welcomecard/discord` and requires
-`discord.js` (optional peer dependency). The core package works without it.
-
-Only `setUsername()` is required — everything else has sensible defaults or fallbacks.
-
-## Requirements
-
-- Node.js ≥ 18
-
-## License
-
-MIT. Font: [Poppins](https://fonts.google.com/specimen/Poppins) (SIL Open Font License, bundled).
+# @quitscope/discord-welcomecard
+
+Render Discord welcome cards as static **PNG** or animated **GIF** from one builder.
+
+![centered preset](examples/centered.png)
+
+- **One API, two outputs** — the same builder renders `.toPNG()` and `.toGIF()`.
+- **Animated GIFs** — background sheen, text fade-in, avatar glow/bounce, rainbow ring, slide-in. Autoplays in Discord.
+- **No compile pain** — built on `@napi-rs/canvas` (prebuilt binaries, no node-gyp).
+- **Bundled font** — cards look the same on every server.
+- **TypeScript** — full types, ESM + CJS.
+
+## Install
+
+```bash
+npm install @quitscope/discord-welcomecard
+```
+
+## Usage
+
+```ts
+import { WelcomeCard } from '@quitscope/discord-welcomecard';
+import { toAttachment } from '@quitscope/discord-welcomecard/discord';
+
+const card = new WelcomeCard()
+  .setPreset('centered')
+  .setUsername('Quit')
+  .setAvatar('https://cdn.discordapp.com/avatars/.../avatar.png')
+  .setSubtitle('Welcome to the server!')
+  .setMemberCount(1234)
+  .setTheme('dark')
+  .setAnimations(['background', 'text', 'avatar']);
+
+const png = await card.toPNG();
+const gif = await card.toGIF();
+
+// discord.js
+channel.send({ files: [toAttachment(gif, 'welcome.gif')] });
+```
+
+### With discord.js events
+
+```ts
+client.on('guildMemberAdd', async (member) => {
+  const gif = await new WelcomeCard()
+    .setUsername(member.user.displayName)
+    .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 256 }))
+    .setSubtitle(`Welcome to ${member.guild.name}!`)
+    .setMemberCount(member.guild.memberCount)
+    .setAnimations(['text', 'avatar'])
+    .toGIF();
+
+  const channel = member.guild.systemChannel;
+  channel?.send({ files: [toAttachment(gif, 'welcome.gif')] });
+});
+```
+
+## Presets
+
+| `centered` (default) | `neon` |
+| --- | --- |
+| ![centered](examples/centered.png) | ![neon](examples/neon.png) |
+
+| `minimal` | `hero` |
+| --- | --- |
+| ![minimal](examples/minimal.png) | ![hero](examples/hero.png) |
+
+## Animated
+
+`setAnimations([...])` + `toGIF()` — combine any of the 6 animation types:
+
+| Type | Effect |
+| --- | --- |
+| `'background'` | Diagonal sheen sweeps across the card |
+| `'text'` | Text fades in (ease-out reveal) |
+| `'avatar'` | Avatar ring pulses with a glow |
+| `'ring'` | Ring color cycles through the full color wheel |
+| `'slide'` | Text slides up into position from below |
+| `'bounce'` | Avatar bounces up and down |
+
+![animated](examples/animated.gif)
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `setPreset(name)` | `'centered'` (default), `'neon'`, `'minimal'`, `'hero'` |
+| `setUsername(name)` | Main text (required) |
+| `setAvatar(urlOrBuffer)` | Avatar image; falls back to a colored circle if it fails to load |
+| `setSubtitle(text)` | Secondary line, e.g. "Welcome to the server!" |
+| `setMemberCount(n)` | Renders "MEMBER #n" — optional, omit to hide |
+| `setMemberCountPosition(pos)` | 3×3 grid: `'top-left'`, `'top-center'`, `'top-right'`, `'center-left'`, `'center'`, `'center-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`. `'corner'` is an alias for `'bottom-right'`. Defaults: `'bottom-center'` in the centered presets, `'bottom-right'` in `hero`. |
+| `setBackground(value)` | Hex color (`#1e1e2e`), image URL, or `Buffer` |
+| `setRingColor(hex)` | Override the avatar ring / glow color |
+| `setTheme(theme)` | `'dark'` (default) or `'light'` |
+| `setFont({ family, color, usernameColor, size, subtitleSize })` | Override font settings; `usernameColor` applies only to the username line |
+| `setAnimations(list)` | Any of `'background'`, `'text'`, `'avatar'`, `'ring'`, `'slide'`, `'bounce'` — used by `toGIF()` |
+| `toPNG()` | `Promise<Buffer>` — static card |
+| `toGIF()` | `Promise<Buffer>` — animated card |
+
+The `toAttachment(buffer, name?)` helper lives in `@quitscope/discord-welcomecard/discord` and requires
+`discord.js` (optional peer dependency). The core package works without it.
+
+Only `setUsername()` is required — everything else has sensible defaults or fallbacks.
+
+## Requirements
+
+- Node.js ≥ 18
+
+## License
+
+MIT. Font: [Poppins](https://fonts.google.com/specimen/Poppins) (SIL Open Font License, bundled).

package/dist/index.cjs

@@ -34,7 +34,7 @@ var CARD_WIDTH = 840;
 var CARD_HEIGHT = 420;
 var GIF_FRAMES = 30;
 var GIF_DELAY_MS = 50;
-var GIF_SCALE = 0.5;
+var GIF_SCALE = 1;
 var DEFAULT_OPTIONS = {
   preset: "centered",
   theme: "dark",
@@ -106,6 +106,7 @@ function centeredLayout(opts) {
     opts.theme === "dark" ? "#1e1e2e" : "#eff1f5"
   );
   const textColor = opts.font.color ?? (opts.theme === "dark" ? "#ffffff" : "#11111b");
+  const usernameColor = opts.font.usernameColor ?? textColor;
   const family = opts.font.family ?? DEFAULT_FONT_FAMILY;
   const avatarSize = 170;
   const avatarY = 56;
@@ -118,7 +119,7 @@ function centeredLayout(opts) {
       x: width / 2 - avatarSize / 2,
       y: avatarY,
       size: avatarSize,
-      ringColor: accent,
+      ringColor: opts.ringColor ?? accent,
       source: opts.avatar
     },
     username: {
@@ -126,7 +127,7 @@ function centeredLayout(opts) {
       x: width / 2,
       y: avatarY + avatarSize + 66,
       size: opts.font.size ?? 56,
-      color: textColor,
+      color: usernameColor,
       family,
       align: "center"
     },
@@ -263,16 +264,75 @@ async function loadImageOrFallback(source, fallbackColor, w = 256, h = 256) {
   }
 }
 
+// src/assets/colorUtils.ts
+function hexToHsl(hex) {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  switch (max) {
+    case r:
+      h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+      break;
+    case g:
+      h = ((b - r) / d + 2) / 6;
+      break;
+    default:
+      h = ((r - g) / d + 4) / 6;
+  }
+  return [h, s, l];
+}
+function hslToHex(h, s, l) {
+  const hue2rgb = (p, q2, t) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q2 - p) * 6 * t;
+    if (t < 1 / 2) return q2;
+    if (t < 2 / 3) return p + (q2 - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  let r, g, b;
+  if (s === 0) {
+    r = g = b = l;
+  } else {
+    const q2 = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q2;
+    r = hue2rgb(p, q2, h + 1 / 3);
+    g = hue2rgb(p, q2, h);
+    b = hue2rgb(p, q2, h - 1 / 3);
+  }
+  const hex = (x) => Math.round(x * 255).toString(16).padStart(2, "0");
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+function rotateHue(hexColor, amount) {
+  const [h, s, l] = hexToHsl(hexColor);
+  return hslToHex((h + amount + 1) % 1, s, l);
+}
+
 // src/render/drawFrame.ts
-var STATIC_FRAME = { textAlpha: 1, avatarGlow: 1, backgroundShift: 0 };
-function drawText(ctx, box, alpha) {
+var STATIC_FRAME = {
+  textAlpha: 1,
+  avatarGlow: 1,
+  backgroundShift: 0,
+  ringShift: 0,
+  textSlide: 1,
+  avatarBounce: 0
+};
+var BOUNCE_AMPLITUDE = 10;
+function drawText(ctx, box, alpha, slideOffset) {
   ctx.save();
   ctx.globalAlpha = alpha;
   ctx.fillStyle = box.color;
   ctx.textAlign = box.align;
   ctx.textBaseline = "alphabetic";
   ctx.font = `${box.size}px ${box.family}`;
-  ctx.fillText(box.text, box.x, box.y);
+  ctx.fillText(box.text, box.x, box.y + slideOffset);
   ctx.restore();
 }
 async function drawFrame(ctx, l, state) {
@@ -292,13 +352,15 @@ async function drawFrame(ctx, l, state) {
     ctx.fillRect(0, 0, l.width, l.height);
   }
   const { x, y, size, ringColor } = l.avatar;
+  const animatedRingColor = state.ringShift > 0 ? rotateHue(ringColor, state.ringShift) : ringColor;
+  const bounceOffset = state.avatarBounce * BOUNCE_AMPLITUDE;
   const cx = x + size / 2;
-  const cy = y + size / 2;
+  const cy = y + size / 2 + bounceOffset;
   ctx.save();
-  ctx.shadowColor = ringColor;
+  ctx.shadowColor = animatedRingColor;
   ctx.shadowBlur = 10 + state.avatarGlow * 25;
   ctx.lineWidth = 6;
-  ctx.strokeStyle = ringColor;
+  ctx.strokeStyle = animatedRingColor;
   ctx.beginPath();
   ctx.arc(cx, cy, size / 2 + 3, 0, Math.PI * 2);
   ctx.stroke();
@@ -308,11 +370,12 @@ async function drawFrame(ctx, l, state) {
   ctx.beginPath();
   ctx.arc(cx, cy, size / 2, 0, Math.PI * 2);
   ctx.clip();
-  ctx.drawImage(avatarImg, x, y, size, size);
+  ctx.drawImage(avatarImg, x, y + bounceOffset, size, size);
   ctx.restore();
-  drawText(ctx, l.username, state.textAlpha);
-  if (l.subtitle) drawText(ctx, l.subtitle, state.textAlpha);
-  if (l.memberCount) drawText(ctx, l.memberCount, state.textAlpha);
+  const slideOffset = (1 - state.textSlide) * l.height;
+  drawText(ctx, l.username, state.textAlpha, slideOffset);
+  if (l.subtitle) drawText(ctx, l.subtitle, state.textAlpha, slideOffset);
+  if (l.memberCount) drawText(ctx, l.memberCount, state.textAlpha, slideOffset);
 }
 
 // src/render/toPNG.ts
@@ -691,12 +754,31 @@ function backgroundShift(progress) {
   return progress;
 }
 
+// src/animate/ring.ts
+function ringShift(progress) {
+  return progress;
+}
+
+// src/animate/slide.ts
+function textSlide(progress) {
+  const p = Math.min(progress / 0.8, 1);
+  return p < 0.5 ? 2 * p * p : 1 - Math.pow(-2 * p + 2, 2) / 2;
+}
+
+// src/animate/bounce.ts
+function avatarBounce(progress) {
+  return Math.sin(progress * Math.PI * 2);
+}
+
 // src/animate/index.ts
 function frameStateFor(animations, progress) {
   return {
     textAlpha: animations.includes("text") ? textAlpha(progress) : 1,
     avatarGlow: animations.includes("avatar") ? avatarGlow(progress) : 1,
-    backgroundShift: animations.includes("background") ? backgroundShift(progress) : 0
+    backgroundShift: animations.includes("background") ? backgroundShift(progress) : 0,
+    ringShift: animations.includes("ring") ? ringShift(progress) : 0,
+    textSlide: animations.includes("slide") ? textSlide(progress) : 1,
+    avatarBounce: animations.includes("bounce") ? avatarBounce(progress) : 0
   };
 }
 
@@ -769,6 +851,10 @@ var WelcomeCard = class {
     this.opts.background = background;
     return this;
   }
+  setRingColor(color) {
+    this.opts.ringColor = color;
+    return this;
+  }
   setTheme(theme) {
     this.opts.theme = theme;
     return this;