Implement PlaceholderHelp component across various forms for enhanced user guidance

- Integrated PlaceholderHelp component into multiple forms including WelcomeForm, TagsManager, and StatsForm to provide contextual hints for available placeholders. - Updated DiscordEmbedBuilder to support placeholder presets, improving user experience when creating embeds. - Enhanced localization files to include new placeholder descriptions, ensuring clarity in both English and German. - Refactored related components to maintain consistency in placeholder handling across the application.
2026-07-22 22:07:08 +02:00
parent 55a4f7bf09
commit 8cfb149a18
21 changed files with 583 additions and 98 deletions
--- a/apps/webui/src/components/modules/birthdays-form.tsx
+++ b/apps/webui/src/components/modules/birthdays-form.tsx
@@ -9,6 +9,7 @@ import { DiscordChannelSelect } from '@/components/ui/discord-channel-select';
 import { DiscordRoleSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import type { SettingsSaveResult } from '@/components/settings/settings-form';
@@ -87,6 +88,7 @@ export function BirthdaysForm({ guildId, initialValue }: BirthdaysFormProps) {
            <div className="space-y-2">
              <Label>{t('modulePages.birthdays.message')}</Label>
              <Textarea value={value.message ?? ''} onChange={(event) => setValue((prev) => ({ ...prev, message: event.target.value || null }))} placeholder={t('modulePages.birthdays.messagePlaceholder')} />
+              <PlaceholderHelp preset="birthdays" />
            </div>
            </FieldAnchor>
          </CardContent>
--- a/apps/webui/src/components/modules/feeds-manager.tsx
+++ b/apps/webui/src/components/modules/feeds-manager.tsx
@@ -12,6 +12,7 @@ import { DiscordChannelSelect } from '@/components/ui/discord-channel-select';
 import { DiscordRoleSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';

@@ -206,6 +207,7 @@ export function FeedsManager({ guildId, initialFeeds }: FeedsManagerProps) {
                onChange={(event) => setDraft((prev) => ({ ...prev, template: event.target.value }))}
                placeholder={t('modulePages.feeds.templatePlaceholder')}
              />
+              <PlaceholderHelp preset="feeds" />
            </div>
          </div>
          <Button type="button" variant="outline" onClick={handleCreate} disabled={creating}>
--- a/apps/webui/src/components/modules/leveling-form.tsx
+++ b/apps/webui/src/components/modules/leveling-form.tsx
@@ -14,6 +14,7 @@ import {
 import { DiscordRoleMultiSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
@@ -250,6 +251,7 @@ export function LevelingForm({ guildId, initialValue }: LevelingFormProps) {
                  onChange={(event) => setValue((prev) => ({ ...prev, levelUpMessage: event.target.value || null }))}
                  placeholder="Congrats {user}, you reached level {level}!"
                />
+                <PlaceholderHelp preset="leveling" />
              </div>
              <FieldAnchor id="field-leveling-stack">
              <div className="flex items-center justify-between rounded-md border border-border p-4">
--- a/apps/webui/src/components/modules/logging-form.tsx
+++ b/apps/webui/src/components/modules/logging-form.tsx
@@ -2,15 +2,16 @@

 import type { LogChannelMapping, LogEventTypeDashboard, LoggingConfigDashboard } from '@nexumi/shared';
 import { Plus, Trash2 } from 'lucide-react';
+import { useMemo } from 'react';
 import { FieldAnchor } from '@/components/layout/field-anchor';
 import { useTranslations } from '@/components/locale-provider';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { DiscordChannelMultiSelect, DiscordChannelSelect } from '@/components/ui/discord-channel-select';
+import { DiscordResourceMultiSelect } from '@/components/ui/discord-resource-multi-select';
 import { DiscordRoleMultiSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
 import type { SettingsSaveResult } from '@/components/settings/settings-form';
 import { SettingsForm } from '@/components/settings/settings-form';
@@ -44,8 +45,10 @@ const LOG_EVENT_TYPES: LogEventTypeDashboard[] = [
  'MOD_ACTION'
 ];

-interface LocalLogChannel extends LogChannelMapping {
+interface LocalLogChannelGroup {
  clientKey: string;
+  channelId: string;
+  eventTypes: LogEventTypeDashboard[];
 }

 interface LocalLoggingValue {
@@ -54,37 +57,78 @@ interface LocalLoggingValue {
  ignoredChannelIds: string[];
  ignoredRoleIds: string[];
  retentionDays: number;
-  logChannels: LocalLogChannel[];
+  logChannels: LocalLogChannelGroup[];
 }

 function toLocal(config: LoggingConfigDashboard): LocalLoggingValue {
+  const byChannel = new Map<string, LogEventTypeDashboard[]>();
+  for (const mapping of config.logChannels) {
+    const existing = byChannel.get(mapping.channelId) ?? [];
+    existing.push(mapping.eventType);
+    byChannel.set(mapping.channelId, existing);
+  }
+
+  const logChannels: LocalLogChannelGroup[] = [...byChannel.entries()].map(([channelId, eventTypes], index) => ({
+    clientKey: `${channelId}-${index}`,
+    channelId,
+    eventTypes: [...new Set(eventTypes)]
+  }));
+
  return {
    enabled: config.enabled,
    ignoreBots: config.ignoreBots,
    ignoredChannelIds: config.ignoredChannelIds,
    ignoredRoleIds: config.ignoredRoleIds,
    retentionDays: config.retentionDays,
-    logChannels: config.logChannels.map((mapping, index) => ({ ...mapping, clientKey: `${mapping.eventType}-${index}` }))
+    logChannels
  };
 }

-function toRemote(value: LocalLoggingValue): LoggingConfigDashboard {
+function toRemote(value: LocalLoggingValue): { ok: true; value: LoggingConfigDashboard } | { ok: false; error: string } {
+  const mappings: LogChannelMapping[] = [];
+  const seenEventTypes = new Set<LogEventTypeDashboard>();
+
+  for (const group of value.logChannels) {
+    if (!group.channelId.trim() || group.eventTypes.length === 0) {
+      continue;
+    }
+    for (const eventType of group.eventTypes) {
+      if (seenEventTypes.has(eventType)) {
+        return { ok: false, error: 'duplicateEventType' };
+      }
+      seenEventTypes.add(eventType);
+      mappings.push({ eventType, channelId: group.channelId });
+    }
+  }
+
  return {
-    enabled: value.enabled,
-    ignoreBots: value.ignoreBots,
-    ignoredChannelIds: value.ignoredChannelIds,
-    ignoredRoleIds: value.ignoredRoleIds,
-    retentionDays: value.retentionDays,
-    logChannels: value.logChannels.map(({ clientKey: _clientKey, ...rest }) => rest)
+    ok: true,
+    value: {
+      enabled: value.enabled,
+      ignoreBots: value.ignoreBots,
+      ignoredChannelIds: value.ignoredChannelIds,
+      ignoredRoleIds: value.ignoredRoleIds,
+      retentionDays: value.retentionDays,
+      logChannels: mappings
+    }
  };
 }

-async function saveLogging(guildId: string, value: LocalLoggingValue): Promise<SettingsSaveResult> {
+async function saveLogging(
+  guildId: string,
+  value: LocalLoggingValue,
+  t: (key: string) => string
+): Promise<SettingsSaveResult> {
+  const remote = toRemote(value);
+  if (!remote.ok) {
+    return { ok: false, error: t(`modulePages.logging.errors.${remote.error}`) };
+  }
+
  try {
    const response = await fetch(`/api/guilds/${guildId}/logging`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(toRemote(value))
+      body: JSON.stringify(remote.value)
    });
    if (!response.ok) {
      const body = (await response.json().catch(() => null)) as { error?: string } | null;
@@ -104,10 +148,19 @@ interface LoggingFormProps {
 export function LoggingForm({ guildId, initialValue }: LoggingFormProps) {
  const t = useTranslations();

+  const eventOptions = useMemo(
+    () =>
+      LOG_EVENT_TYPES.map((eventType) => ({
+        id: eventType,
+        name: t(`modulePages.logging.eventTypes.${eventType}`)
+      })),
+    [t]
+  );
+
  return (
    <SettingsForm<LocalLoggingValue>
      initialValue={toLocal(initialValue)}
-      onSave={(value) => saveLogging(guildId, value)}
+      onSave={(value) => saveLogging(guildId, value, t)}
    >
      {({ value, setValue }) => (
        <div className="space-y-6">
@@ -186,63 +239,63 @@ export function LoggingForm({ guildId, initialValue }: LoggingFormProps) {
                <p className="text-sm text-muted-foreground">{t('modulePages.logging.channelsEmpty')}</p>
              )}
              {value.logChannels.map((mapping) => (
-                <div key={mapping.clientKey} className="flex flex-wrap items-end gap-3 rounded-md border border-border p-3">
-                  <div className="space-y-2">
-                    <Label>{t('modulePages.logging.eventType')}</Label>
-                    <Select
-                      value={mapping.eventType}
-                      onValueChange={(eventType) =>
+                <div key={mapping.clientKey} className="space-y-3 rounded-md border border-border p-3">
+                  <div className="flex flex-wrap items-end gap-3">
+                    <div className="min-w-[14rem] flex-1 space-y-2">
+                      <Label>{t('modulePages.logging.channelId')}</Label>
+                      <DiscordChannelSelect
+                        guildId={guildId}
+                        value={mapping.channelId}
+                        onChange={(channelId) =>
+                          setValue((prev) => ({
+                            ...prev,
+                            logChannels: prev.logChannels.map((entry) =>
+                              entry.clientKey === mapping.clientKey ? { ...entry, channelId } : entry
+                            )
+                          }))
+                        }
+                      />
+                    </div>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon"
+                      aria-label={t('common.remove')}
+                      onClick={() =>
                        setValue((prev) => ({
                          ...prev,
-                          logChannels: prev.logChannels.map((entry) =>
-                            entry.clientKey === mapping.clientKey
-                              ? { ...entry, eventType: eventType as LogEventTypeDashboard }
-                              : entry
-                          )
+                          logChannels: prev.logChannels.filter((entry) => entry.clientKey !== mapping.clientKey)
                        }))
                      }
                    >
-                      <SelectTrigger className="w-56">
-                        <SelectValue />
-                      </SelectTrigger>
-                      <SelectContent>
-                        {LOG_EVENT_TYPES.map((eventType) => (
-                          <SelectItem key={eventType} value={eventType}>
-                            {eventType}
-                          </SelectItem>
-                        ))}
-                      </SelectContent>
-                    </Select>
+                      <Trash2 className="size-4" />
+                    </Button>
                  </div>
-                  <div className="flex-1 space-y-2">
-                    <Label>{t('modulePages.logging.channelId')}</Label>
-                    <DiscordChannelSelect
-                      guildId={guildId}
-                      value={mapping.channelId}
-                      onChange={(channelId) =>
+                  <div className="space-y-2">
+                    <Label>{t('modulePages.logging.eventTypesLabel')}</Label>
+                    <DiscordResourceMultiSelect
+                      options={eventOptions}
+                      value={mapping.eventTypes}
+                      showIdHint={false}
+                      placeholder={t('modulePages.logging.eventTypesPlaceholder')}
+                      onChange={(nextIds) => {
+                        const eventTypes = nextIds as LogEventTypeDashboard[];
                        setValue((prev) => ({
                          ...prev,
-                          logChannels: prev.logChannels.map((entry) =>
-                            entry.clientKey === mapping.clientKey ? { ...entry, channelId } : entry
-                          )
-                        }))
-                      }
+                          logChannels: prev.logChannels.map((entry) => {
+                            if (entry.clientKey === mapping.clientKey) {
+                              return { ...entry, eventTypes };
+                            }
+                            // Each event type can only map to one channel (DB unique).
+                            return {
+                              ...entry,
+                              eventTypes: entry.eventTypes.filter((eventType) => !eventTypes.includes(eventType))
+                            };
+                          })
+                        }));
+                      }}
                    />
                  </div>
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    size="icon"
-                    aria-label={t('common.remove')}
-                    onClick={() =>
-                      setValue((prev) => ({
-                        ...prev,
-                        logChannels: prev.logChannels.filter((entry) => entry.clientKey !== mapping.clientKey)
-                      }))
-                    }
-                  >
-                    <Trash2 className="size-4" />
-                  </Button>
                </div>
              ))}
              <Button
@@ -253,7 +306,7 @@ export function LoggingForm({ guildId, initialValue }: LoggingFormProps) {
                    ...prev,
                    logChannels: [
                      ...prev.logChannels,
-                      { clientKey: `new-${Date.now()}`, eventType: 'MOD_ACTION', channelId: '' }
+                      { clientKey: `new-${Date.now()}`, channelId: '', eventTypes: [] }
                    ]
                  }))
                }
@@ -261,6 +314,7 @@ export function LoggingForm({ guildId, initialValue }: LoggingFormProps) {
                <Plus className="size-4" />
                {t('modulePages.logging.addMapping')}
              </Button>
+              <p className="text-xs text-muted-foreground">{t('modulePages.logging.channelsHint')}</p>
            </CardContent>
          </Card>
          </FieldAnchor>
--- a/apps/webui/src/components/modules/scheduler-manager.tsx
+++ b/apps/webui/src/components/modules/scheduler-manager.tsx
@@ -13,6 +13,7 @@ import { DiscordEmbedBuilder, normalizeEmbed } from '@/components/ui/discord-emb
 import { DiscordRoleSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Textarea } from '@/components/ui/textarea';

 const EMPTY_DRAFT = {
@@ -168,10 +169,15 @@ export function SchedulerManager({ guildId, initialSchedules }: SchedulerManager
              onChange={(event) => setDraft((prev) => ({ ...prev, content: event.target.value }))}
              rows={3}
            />
+            <PlaceholderHelp preset="scheduler" />
          </div>
          <div className="space-y-2">
            <Label>{t('modulePages.scheduler.embed')}</Label>
-            <DiscordEmbedBuilder value={draft.embed} onChange={(embed) => setDraft((prev) => ({ ...prev, embed }))} />
+            <DiscordEmbedBuilder
+              value={draft.embed}
+              onChange={(embed) => setDraft((prev) => ({ ...prev, embed }))}
+              placeholderPreset="scheduler"
+            />
          </div>
          <p className="text-xs text-muted-foreground">{t('modulePages.scheduler.cronHint')}</p>
          <Button type="button" onClick={handleCreate} disabled={creating}>
--- a/apps/webui/src/components/modules/stats-form.tsx
+++ b/apps/webui/src/components/modules/stats-form.tsx
@@ -8,6 +8,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { DiscordChannelSelect } from '@/components/ui/discord-channel-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Switch } from '@/components/ui/switch';
 import type { SettingsSaveResult } from '@/components/settings/settings-form';
 import { SettingsForm } from '@/components/settings/settings-form';
@@ -102,7 +103,7 @@ export function StatsForm({ guildId, initialValue }: StatsFormProps) {
                <Input id={boostsTemplateId} value={value.boostsTemplate} onChange={(event) => setValue((prev) => ({ ...prev, boostsTemplate: event.target.value }))} />
              </div>
            </div>
-            <p className="text-xs text-muted-foreground">{t('modulePages.stats.templateHint')}</p>
+            <PlaceholderHelp preset="stats" />
          </CardContent>
        </Card>
      )}
--- a/apps/webui/src/components/modules/tags-manager.tsx
+++ b/apps/webui/src/components/modules/tags-manager.tsx
@@ -1,6 +1,6 @@
 'use client';

-import type { TagDashboard, TagResponseType } from '@nexumi/shared';
+import type { TagDashboard, TagResponseType, WelcomeEmbed } from '@nexumi/shared';
 import { Plus, Trash2 } from 'lucide-react';
 import { useState } from 'react';
 import { toast } from 'sonner';
@@ -9,9 +9,11 @@ import { useTranslations } from '@/components/locale-provider';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { DiscordChannelMultiSelect } from '@/components/ui/discord-channel-select';
+import { DiscordEmbedBuilder, normalizeEmbed } from '@/components/ui/discord-embed-builder';
 import { DiscordRoleMultiSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Textarea } from '@/components/ui/textarea';

@@ -25,6 +27,7 @@ interface LocalTag extends TagDashboard {
 const EMPTY_DRAFT = {
  name: '',
  content: '',
+  embed: null as WelcomeEmbed | null,
  responseType: 'TEXT' as TagResponseType,
  triggerWord: '',
  allowedRoleIds: [] as string[],
@@ -41,6 +44,7 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
  const [tags, setTags] = useState<LocalTag[]>(
    initialTags.map((tag, index) => ({
      ...tag,
+      embed: tag.embed ?? null,
      clientKey: tag.id ?? `existing-${index}`
    }))
  );
@@ -52,6 +56,11 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
      toast.error(t('modulePages.tags.nameRequired'));
      return;
    }
+    const embed = draft.responseType === 'EMBED' ? normalizeEmbed(draft.embed) : null;
+    if (draft.responseType === 'EMBED' && !embed?.title && !embed?.description) {
+      toast.error(t('modulePages.tags.embedRequired'));
+      return;
+    }
    setCreating(true);
    try {
      const response = await fetch(`/api/guilds/${guildId}/tags`, {
@@ -60,6 +69,7 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
        body: JSON.stringify({
          name: draft.name.trim(),
          content: draft.content.trim() || null,
+          embed,
          responseType: draft.responseType,
          triggerWord: draft.triggerWord.trim() || null,
          allowedRoleIds: draft.allowedRoleIds,
@@ -88,6 +98,11 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
  }

  async function handleSave(tag: LocalTag) {
+    const embed = tag.responseType === 'EMBED' ? normalizeEmbed(tag.embed ?? null) : null;
+    if (tag.responseType === 'EMBED' && !embed?.title && !embed?.description) {
+      toast.error(t('modulePages.tags.embedRequired'));
+      return;
+    }
    setTags((prev) => prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, saving: true } : entry)));
    try {
      const response = await fetch(`/api/guilds/${guildId}/tags/${tag.id}`, {
@@ -96,6 +111,7 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
        body: JSON.stringify({
          name: tag.name,
          content: tag.content,
+          embed,
          responseType: tag.responseType,
          triggerWord: tag.triggerWord,
          allowedRoleIds: tag.allowedRoleIds,
@@ -105,12 +121,19 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
      const body = (await response.json().catch(() => null)) as (TagDashboard & { error?: string }) | null;
      if (!response.ok || !body) {
        toast.error(body?.error ?? t('common.saveError'));
+        setTags((prev) =>
+          prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, saving: false } : entry))
+        );
        return;
      }
+      setTags((prev) =>
+        prev.map((entry) =>
+          entry.clientKey === tag.clientKey ? { ...entry, ...body, clientKey: entry.clientKey, saving: false } : entry
+        )
+      );
      toast.success(t('common.saveSuccess'));
    } catch {
      toast.error(t('common.saveError'));
-    } finally {
      setTags((prev) => prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, saving: false } : entry)));
    }
  }
@@ -166,10 +189,22 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
              <Input value={draft.triggerWord} onChange={(event) => setDraft((prev) => ({ ...prev, triggerWord: event.target.value }))} placeholder={t('common.optional')} />
            </div>
          </div>
-          <div className="space-y-2">
-            <Label>{t('modulePages.tags.content')}</Label>
-            <Textarea rows={3} value={draft.content} onChange={(event) => setDraft((prev) => ({ ...prev, content: event.target.value }))} />
-          </div>
+          {draft.responseType === 'TEXT' ? (
+            <div className="space-y-2">
+              <Label>{t('modulePages.tags.content')}</Label>
+              <Textarea rows={3} value={draft.content} onChange={(event) => setDraft((prev) => ({ ...prev, content: event.target.value }))} />
+              <PlaceholderHelp preset="tags" />
+            </div>
+          ) : (
+            <div className="space-y-2">
+              <Label>{t('modulePages.tags.embed')}</Label>
+              <DiscordEmbedBuilder
+                value={draft.embed}
+                onChange={(embed) => setDraft((prev) => ({ ...prev, embed }))}
+                placeholderPreset="tags"
+              />
+            </div>
+          )}
          <div className="grid gap-4 sm:grid-cols-2">
            <div className="space-y-2">
              <Label>{t('modulePages.tags.allowedRoleIds')}</Label>
@@ -197,7 +232,6 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
      </FieldAnchor>

      <FieldAnchor id="field-tags-list">
-
      <Card>
        <CardHeader>
          <CardTitle>{t('modulePages.tags.listTitle')}</CardTitle>
@@ -232,10 +266,26 @@ export function TagsManager({ guildId, initialTags }: TagsManagerProps) {
                  <Input value={tag.triggerWord ?? ''} onChange={(event) => setTags((prev) => prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, triggerWord: event.target.value || null } : entry)))} />
                </div>
              </div>
-              <div className="space-y-2">
-                <Label>{t('modulePages.tags.content')}</Label>
-                <Textarea rows={3} value={tag.content ?? ''} onChange={(event) => setTags((prev) => prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, content: event.target.value } : entry)))} />
-              </div>
+              {tag.responseType === 'TEXT' ? (
+                <div className="space-y-2">
+                  <Label>{t('modulePages.tags.content')}</Label>
+                  <Textarea rows={3} value={tag.content ?? ''} onChange={(event) => setTags((prev) => prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, content: event.target.value } : entry)))} />
+                  <PlaceholderHelp preset="tags" />
+                </div>
+              ) : (
+                <div className="space-y-2">
+                  <Label>{t('modulePages.tags.embed')}</Label>
+                  <DiscordEmbedBuilder
+                    value={tag.embed ?? null}
+                    onChange={(embed) =>
+                      setTags((prev) =>
+                        prev.map((entry) => (entry.clientKey === tag.clientKey ? { ...entry, embed } : entry))
+                      )
+                    }
+                    placeholderPreset="tags"
+                  />
+                </div>
+              )}
              <div className="grid gap-3 sm:grid-cols-2">
                <div className="space-y-2">
                  <Label>{t('modulePages.tags.allowedRoleIds')}</Label>
--- a/apps/webui/src/components/modules/tempvoice-form.tsx
+++ b/apps/webui/src/components/modules/tempvoice-form.tsx
@@ -8,6 +8,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { DiscordChannelSelect } from '@/components/ui/discord-channel-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Switch } from '@/components/ui/switch';
 import type { SettingsSaveResult } from '@/components/settings/settings-form';
 import { SettingsForm } from '@/components/settings/settings-form';
@@ -81,6 +82,7 @@ export function TempVoiceForm({ guildId, initialValue }: TempVoiceFormProps) {
              <div className="space-y-2">
                <Label htmlFor={nameId}>{t('modulePages.tempvoice.defaultName')}</Label>
                <Input id={nameId} value={value.defaultName} onChange={(event) => setValue((prev) => ({ ...prev, defaultName: event.target.value }))} placeholder="{user}'s Channel" />
+                <PlaceholderHelp preset="tempvoice" />
              </div>
              </FieldAnchor>
              <FieldAnchor id="field-tempvoice-limit">
--- a/apps/webui/src/components/modules/welcome-form.tsx
+++ b/apps/webui/src/components/modules/welcome-form.tsx
@@ -13,6 +13,7 @@ import {
 import { DiscordRoleMultiSelect } from '@/components/ui/discord-role-select';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
@@ -131,7 +132,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                  onChange={(event) => setValue((prev) => ({ ...prev, welcomeContent: event.target.value || null }))}
                  placeholder={t('modulePages.welcome.contentPlaceholder')}
                />
-                <p className="text-xs text-muted-foreground">{t('modulePages.welcome.placeholdersHint')}</p>
+                <PlaceholderHelp preset="welcome" />
              </div>
              </FieldAnchor>
              <FieldAnchor id="field-welcome-embed">
@@ -141,6 +142,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                  value={value.welcomeEmbed}
                  onChange={(welcomeEmbed) => setValue((prev) => ({ ...prev, welcomeEmbed }))}
                  previewVars={WELCOME_PREVIEW_VARS}
+                  placeholderPreset="welcome"
                />
              </div>
              </FieldAnchor>
@@ -158,6 +160,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                  onChange={(event) => setValue((prev) => ({ ...prev, welcomeDmContent: event.target.value || null }))}
                  placeholder={t('modulePages.welcome.dmContentPlaceholder')}
                />
+                <PlaceholderHelp preset="welcomeDm" />
              </div>
              </FieldAnchor>
              <FieldAnchor id="field-welcome-user-autoroles">
@@ -200,6 +203,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                </div>
                </FieldAnchor>
              </div>
+              <PlaceholderHelp preset="welcome" />
            </CardContent>
          </Card>

@@ -236,6 +240,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                  onChange={(event) => setValue((prev) => ({ ...prev, leaveContent: event.target.value || null }))}
                  placeholder={t('modulePages.welcome.contentPlaceholder')}
                />
+                <PlaceholderHelp preset="welcome" />
              </div>
              </FieldAnchor>
              <FieldAnchor id="field-leave-embed">
@@ -245,6 +250,7 @@ export function WelcomeForm({ guildId, initialValue }: WelcomeFormProps) {
                  value={value.leaveEmbed}
                  onChange={(leaveEmbed) => setValue((prev) => ({ ...prev, leaveEmbed }))}
                  previewVars={WELCOME_PREVIEW_VARS}
+                  placeholderPreset="welcome"
                />
              </div>
              </FieldAnchor>
--- a/apps/webui/src/components/ui/discord-embed-builder.tsx
+++ b/apps/webui/src/components/ui/discord-embed-builder.tsx
@@ -4,7 +4,9 @@ import type { WelcomeEmbed } from '@nexumi/shared';
 import { useTranslations } from '@/components/locale-provider';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PlaceholderHelp } from '@/components/ui/placeholder-help';
 import { Textarea } from '@/components/ui/textarea';
+import type { PlaceholderPresetId } from '@/lib/placeholder-presets';
 import { cn } from '@/lib/utils';

 export const DEFAULT_EMBED_COLOR = 0x6366f1;
@@ -54,10 +56,12 @@ function hexToColor(hex: string): number {
 }

 function applyPreviewVars(template: string, vars: Record<string, string>): string {
-  return Object.entries(vars).reduce(
+  const withVars = Object.entries(vars).reduce(
    (acc, [key, value]) => acc.replaceAll(`{${key}}`, value),
    template
  );
+  // Show bracket channel mentions as #id in the dashboard preview.
+  return withVars.replace(/\["(\d{17,20})"\]/g, '#$1').replace(/<#(\d{17,20})>/g, '#$1');
 }

 interface DiscordEmbedBuilderProps {
@@ -67,6 +71,8 @@ interface DiscordEmbedBuilderProps {
  /** Sample values for preview placeholder substitution (e.g. user → @Alex). */
  previewVars?: Record<string, string>;
  showClearHint?: boolean;
+  /** Which placeholders apply to this embed context. */
+  placeholderPreset?: PlaceholderPresetId;
 }

 export function DiscordEmbedBuilder({
@@ -74,7 +80,8 @@ export function DiscordEmbedBuilder({
  onChange,
  className,
  previewVars,
-  showClearHint = true
+  showClearHint = true,
+  placeholderPreset = 'welcome'
 }: DiscordEmbedBuilderProps) {
  const t = useTranslations();
  const draft = value ?? emptyEmbed();
@@ -146,6 +153,7 @@ export function DiscordEmbedBuilder({
        {showClearHint ? (
          <p className="text-xs text-muted-foreground">{t('embedBuilder.clearHint')}</p>
        ) : null}
+        <PlaceholderHelp preset={placeholderPreset} />
        <button
          type="button"
          className="text-xs text-muted-foreground underline-offset-2 hover:underline"
--- a/apps/webui/src/components/ui/discord-resource-multi-select.tsx
+++ b/apps/webui/src/components/ui/discord-resource-multi-select.tsx
@@ -29,6 +29,8 @@ interface DiscordResourceMultiSelectProps {
  placeholder?: string;
  disabled?: boolean;
  emptyLabel?: string;
+  /** Show a truncated id hint in the dropdown (useful for Discord snowflakes). */
+  showIdHint?: boolean;
 }

 export function DiscordResourceMultiSelect({
@@ -37,7 +39,8 @@ export function DiscordResourceMultiSelect({
  onChange,
  placeholder,
  disabled = false,
-  emptyLabel
+  emptyLabel,
+  showIdHint = true
 }: DiscordResourceMultiSelectProps) {
  const t = useTranslations();
  const [open, setOpen] = useState(false);
@@ -96,9 +99,11 @@ export function DiscordResourceMultiSelect({
                        {option.prefix ?? ''}
                        {option.name}
                      </span>
-                      <span className="ml-auto font-mono text-[10px] text-muted-foreground">
-                        {option.id.slice(-6)}
-                      </span>
+                      {showIdHint ? (
+                        <span className="ml-auto font-mono text-[10px] text-muted-foreground">
+                          {option.id.slice(-6)}
+                        </span>
+                      ) : null}
                    </CommandItem>
                  );
                })}
--- a/apps/webui/src/components/ui/placeholder-help.tsx
+++ b/apps/webui/src/components/ui/placeholder-help.tsx
@@ -0,0 +1,96 @@
+'use client';
+
+import { Check, ChevronDown, Copy } from 'lucide-react';
+import { useId, useState } from 'react';
+import { toast } from 'sonner';
+import { useTranslations } from '@/components/locale-provider';
+import { Button } from '@/components/ui/button';
+import {
+  PLACEHOLDER_PRESETS,
+  type PlaceholderDefinition,
+  type PlaceholderPresetId
+} from '@/lib/placeholder-presets';
+import { cn } from '@/lib/utils';
+
+interface PlaceholderHelpProps {
+  preset: PlaceholderPresetId;
+  /** Optional extra tokens for one-off fields. */
+  extra?: PlaceholderDefinition[];
+  className?: string;
+  /** Start expanded (default: collapsed). */
+  defaultOpen?: boolean;
+}
+
+export function PlaceholderHelp({
+  preset,
+  extra = [],
+  className,
+  defaultOpen = false
+}: PlaceholderHelpProps) {
+  const t = useTranslations();
+  const panelId = useId();
+  const [open, setOpen] = useState(defaultOpen);
+  const [copiedToken, setCopiedToken] = useState<string | null>(null);
+
+  const items = [...PLACEHOLDER_PRESETS[preset], ...extra];
+  if (items.length === 0) {
+    return null;
+  }
+
+  async function copyToken(token: string) {
+    try {
+      await navigator.clipboard.writeText(token);
+      setCopiedToken(token);
+      toast.success(t('placeholders.copied'));
+      window.setTimeout(() => setCopiedToken((current) => (current === token ? null : current)), 1500);
+    } catch {
+      toast.error(t('placeholders.copyFailed'));
+    }
+  }
+
+  return (
+    <div className={cn('rounded-md border border-border bg-muted/30', className)}>
+      <button
+        type="button"
+        className="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-xs font-medium text-muted-foreground hover:text-foreground"
+        aria-expanded={open}
+        aria-controls={panelId}
+        onClick={() => setOpen((prev) => !prev)}
+      >
+        <span>{t('placeholders.toggle')}</span>
+        <ChevronDown className={cn('size-4 shrink-0 transition-transform', open && 'rotate-180')} />
+      </button>
+      {open ? (
+        <div id={panelId} className="space-y-2 border-t border-border px-3 py-2">
+          <p className="text-xs text-muted-foreground">{t('placeholders.hint')}</p>
+          <ul className="space-y-1.5">
+            {items.map((item) => {
+              const isCopied = copiedToken === item.token;
+              return (
+                <li
+                  key={item.token}
+                  className="flex items-start gap-2 rounded-md border border-transparent px-1 py-0.5 hover:border-border hover:bg-background/60"
+                >
+                  <div className="min-w-0 flex-1">
+                    <code className="break-all font-mono text-xs text-foreground">{item.token}</code>
+                    <p className="text-[11px] leading-snug text-muted-foreground">{t(item.descriptionKey)}</p>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon"
+                    className="size-7 shrink-0"
+                    aria-label={t('placeholders.copy')}
+                    onClick={() => void copyToken(item.token)}
+                  >
+                    {isCopied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+                  </Button>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  );
+}