feat(emojis): show emoji shortcode in preview and keep frequently-used to one row

Polish two details of the built-in emoji picker:

- The footer preview now shows the emoji's `:shortcode:` beneath its name (the
  same token that drives `:` autocomplete), so the preview doubles as a hint.
- The "frequently used" section is capped to a single row: its ids are sliced
  to one row's worth (resolveFrequentlyUsedEmoji) and the frequent grid is
  pinned to a fixed column count, so it no longer wraps to extra rows as more
  emoji are used.

Also adds EmojiButton skin-tone tests documenting that skin tone applies only
to emoji that have skin variants (hands/people) — not the faces shown by
default — which is why changing the tone appears to have no effect there.

Author: oliverlaz

src/plugins/Emojis/components/EmojiPickerPanel.tsx

@@ -4,6 +4,7 @@ import { CategoryNav } from './CategoryNav';
 import { EmojiButton } from './EmojiButton';
 import { EmojiGrid, type EmojiGridHandle, type EmojiPickerCategory } from './EmojiGrid';
 import { EMOJI_CATEGORY_META } from './categories';
+import { resolveFrequentlyUsedEmoji } from './frequentlyUsed';
 import { EmptyResults } from './EmptyResults';
 import { PreviewPane } from './PreviewPane';
 import { SearchInput } from './SearchInput';
@@ -101,7 +102,9 @@ export const EmojiPickerPanel = ({
   const categories = useMemo<EmojiPickerCategory[]>(() => {
     if (!data || !frequentlyUsedIds.length) return baseCategories;
     const frequent: EmojiPickerCategory = {
-      emojis: frequentlyUsedIds.map((id) => data.emojis[id]).filter(Boolean),
+      // Capped to a single row (see resolveFrequentlyUsedEmoji + the frequent-section
+      // CSS) so the section never grows to multiple rows as more emoji are used.
+      emojis: resolveFrequentlyUsedEmoji(data, frequentlyUsedIds),
       id: 'frequent',
       label: t(EMOJI_CATEGORY_META.frequent.labelKey),
     };

src/plugins/Emojis/components/PreviewPane.tsx

@@ -7,8 +7,9 @@ export type PreviewPaneProps = {
 };
 
 /**
- * Footer preview of the hovered/focused emoji: a large glyph plus its name. Falls back
- * to a "Pick an emoji…" placeholder (like emoji-mart) so the footer is never empty.
+ * Footer preview of the hovered/focused emoji: a large glyph, its name, and its
+ * `:shortcode:` (so users learn the token that drives `:` autocomplete). Falls back to
+ * a "Pick an emoji…" placeholder (like emoji-mart) so the footer is never empty.
  * Receives the previewed emoji as a prop (kept out of context) so hovering does not
  * re-render the emoji grid.
  */
@@ -23,8 +24,13 @@ export const PreviewPane = ({ emoji }: PreviewPaneProps) => {
           ? (emoji.skins[skinToneIndex]?.native ?? emoji.skins[0]?.native ?? '')
           : '☝️'}
       </span>
-      <span className='str-chat__emoji-picker__preview-name'>
-        {emoji ? emoji.name : t('Pick an emoji…')}
+      <span className='str-chat__emoji-picker__preview-text'>
+        <span className='str-chat__emoji-picker__preview-name'>
+          {emoji ? emoji.name : t('Pick an emoji…')}
+        </span>
+        {emoji ? (
+          <span className='str-chat__emoji-picker__preview-shortcode'>{`:${emoji.id}:`}</span>
+        ) : null}
       </span>
     </div>
   );

src/plugins/Emojis/components/__tests__/EmojiButton.test.tsx

@@ -0,0 +1,71 @@
+import { render, screen } from '@testing-library/react';
+import { EmojiButton } from '../EmojiButton';
+import { EmojiPickerProvider } from '../../context/EmojiPickerContext';
+import type { EmojiDataEmoji } from '../../data';
+
+// A skin-tone-capable emoji (6 skins) and a plain one (1 skin) — mirrors the dataset,
+// where only ~305 of ~1870 emoji have skin variants.
+const wave: EmojiDataEmoji = {
+  id: 'wave',
+  keywords: ['hand'],
+  name: 'Waving Hand',
+  skins: [
+    { native: '👋', unified: '1f44b' },
+    { native: '👋🏻', unified: '1f44b-1f3fb' },
+    { native: '👋🏼', unified: '1f44b-1f3fc' },
+    { native: '👋🏽', unified: '1f44b-1f3fd' },
+    { native: '👋🏾', unified: '1f44b-1f3fe' },
+    { native: '👋🏿', unified: '1f44b-1f3ff' },
+  ],
+  version: 1,
+};
+
+const grinning: EmojiDataEmoji = {
+  id: 'grinning',
+  keywords: ['face'],
+  name: 'Grinning',
+  skins: [{ native: '😀', unified: '1f600' }],
+  version: 1,
+};
+
+const renderButton = (emoji: EmojiDataEmoji, skinToneIndex: number) =>
+  render(
+    <EmojiPickerProvider
+      value={{ onSelectEmoji: vi.fn(), setPreviewedEmoji: vi.fn(), skinToneIndex }}
+    >
+      <EmojiButton emoji={emoji} />
+    </EmojiPickerProvider>,
+  );
+
+describe('EmojiButton skin tone', () => {
+  it('renders the default glyph at skin tone 0', () => {
+    renderButton(wave, 0);
+    expect(screen.getByRole('button', { name: 'Waving Hand' })).toHaveTextContent('👋');
+  });
+
+  it('renders the toned glyph for a skin-tone-capable emoji', () => {
+    renderButton(wave, 5);
+    expect(screen.getByRole('button', { name: 'Waving Hand' })).toHaveTextContent('👋🏿');
+  });
+
+  it('updates the glyph when the active skin tone changes (memo does not block context)', () => {
+    const { rerender } = renderButton(wave, 0);
+    expect(screen.getByRole('button', { name: 'Waving Hand' })).toHaveTextContent('👋');
+
+    rerender(
+      <EmojiPickerProvider
+        value={{ onSelectEmoji: vi.fn(), setPreviewedEmoji: vi.fn(), skinToneIndex: 3 }}
+      >
+        <EmojiButton emoji={wave} />
+      </EmojiPickerProvider>,
+    );
+    expect(screen.getByRole('button', { name: 'Waving Hand' })).toHaveTextContent('👋🏽');
+  });
+
+  it('leaves an emoji with no skin variants unchanged at any tone (why smileys never change)', () => {
+    renderButton(grinning, 5);
+    // Falls back to skins[0] — this is why changing skin tone has no visible effect on
+    // the faces shown by default; only hand/person emoji carry skin variants.
+    expect(screen.getByRole('button', { name: 'Grinning' })).toHaveTextContent('😀');
+  });
+});

src/plugins/Emojis/components/__tests__/PreviewPane.test.tsx

@@ -0,0 +1,43 @@
+import { render, screen } from '@testing-library/react';
+
+vi.mock('../../../../context', () => ({
+  useTranslationContext: () => ({ t: (key: string) => key }),
+}));
+
+import { PreviewPane } from '../PreviewPane';
+import { EmojiPickerProvider } from '../../context/EmojiPickerContext';
+import type { EmojiDataEmoji } from '../../data';
+
+const smile: EmojiDataEmoji = {
+  id: 'smile',
+  keywords: ['happy'],
+  name: 'Smiling Face',
+  skins: [{ native: '😄', unified: '1f604' }],
+  version: 1,
+};
+
+const renderPreview = (emoji: EmojiDataEmoji | null, skinToneIndex = 0) =>
+  render(
+    <EmojiPickerProvider
+      value={{ onSelectEmoji: vi.fn(), setPreviewedEmoji: vi.fn(), skinToneIndex }}
+    >
+      <PreviewPane emoji={emoji} />
+    </EmojiPickerProvider>,
+  );
+
+describe('PreviewPane', () => {
+  it('shows the emoji name and its shortcode when an emoji is previewed', () => {
+    renderPreview(smile);
+
+    expect(screen.getByText('Smiling Face')).toBeInTheDocument();
+    // The shortcode (`:id:`) must be visible so users learn the autocomplete token.
+    expect(screen.getByText(':smile:')).toBeInTheDocument();
+  });
+
+  it('shows the placeholder and no shortcode when nothing is previewed', () => {
+    renderPreview(null);
+
+    expect(screen.getByText('Pick an emoji…')).toBeInTheDocument();
+    expect(screen.queryByText(/^:.+:$/)).not.toBeInTheDocument();
+  });
+});

src/plugins/Emojis/components/__tests__/frequentlyUsed.test.ts

@@ -0,0 +1,39 @@
+import { FREQUENTLY_USED_LIMIT, resolveFrequentlyUsedEmoji } from '../frequentlyUsed';
+import type { EmojiData, EmojiDataEmoji } from '../../data';
+
+const makeEmoji = (id: string): EmojiDataEmoji => ({
+  id,
+  keywords: [],
+  name: id,
+  skins: [{ native: id, unified: id }],
+  version: 1,
+});
+
+const data = {
+  aliases: {},
+  categories: [],
+  emojis: Object.fromEntries(
+    Array.from({ length: 30 }, (_, i) => `e${i}`).map((id) => [id, makeEmoji(id)]),
+  ),
+} as unknown as EmojiData;
+
+describe('resolveFrequentlyUsedEmoji', () => {
+  it('caps the frequently-used list to a single row so it never wraps', () => {
+    const ids = Array.from({ length: 30 }, (_, i) => `e${i}`);
+    const result = resolveFrequentlyUsedEmoji(data, ids);
+
+    expect(result).toHaveLength(FREQUENTLY_USED_LIMIT);
+  });
+
+  it('preserves most-recent-first order', () => {
+    const result = resolveFrequentlyUsedEmoji(data, ['e2', 'e0', 'e1']);
+
+    expect(result.map((emoji) => emoji.id)).toEqual(['e2', 'e0', 'e1']);
+  });
+
+  it('drops ids missing from the dataset', () => {
+    const result = resolveFrequentlyUsedEmoji(data, ['e0', 'does-not-exist', 'e1']);
+
+    expect(result.map((emoji) => emoji.id)).toEqual(['e0', 'e1']);
+  });
+});

src/plugins/Emojis/components/frequentlyUsed.ts

@@ -0,0 +1,27 @@
+import type { EmojiData, EmojiDataEmoji } from '../data';
+
+/**
+ * How many recently-used emoji the "frequently used" section shows. Matches the
+ * default grid's column count, so the section stays a single row.
+ *
+ * Kept in sync with the fixed column count in EmojiPicker.scss
+ * (`[data-category-id='frequent'] .str-chat__emoji-picker__category-emojis`): the
+ * slice caps the item count and the CSS pins the columns, together guaranteeing one
+ * row regardless of how many emoji have been used.
+ */
+export const FREQUENTLY_USED_LIMIT = 9;
+
+/**
+ * Resolves an ordered (most-recent-first) list of emoji ids to dataset entries for the
+ * "frequently used" section: drops ids missing from the dataset and caps the result to
+ * a single row (`FREQUENTLY_USED_LIMIT`).
+ */
+export const resolveFrequentlyUsedEmoji = (
+  data: EmojiData,
+  frequentlyUsedIds: string[],
+  limit = FREQUENTLY_USED_LIMIT,
+): EmojiDataEmoji[] =>
+  frequentlyUsedIds
+    .map((id) => data.emojis[id])
+    .filter(Boolean)
+    .slice(0, limit);

src/plugins/Emojis/styling/EmojiPicker.scss

@@ -188,6 +188,15 @@ $emoji-picker-border-radius: 12px;
         gap: var(--str-chat__spacing-xs);
         padding-block-end: var(--str-chat__spacing-xs);
       }
+
+      // Pin the "frequently used" section to a single row. The panel caps its ids to
+      // FREQUENTLY_USED_LIMIT (see frequentlyUsed.ts) and these fixed columns match the
+      // default grid width, so it fills one aligned row and never wraps to a second as
+      // more emoji are used. (Uses the literal child class, not `&-emojis`, so the
+      // combinator doesn't re-expand the whole parent chain.)
+      &[data-category-id='frequent'] > .str-chat__emoji-picker__category-emojis {
+        grid-template-columns: repeat(9, minmax(0, 1fr));
+      }
     }
 
     &__emoji {
@@ -228,15 +237,32 @@ $emoji-picker-border-radius: 12px;
       min-inline-size: 0;
 
       &-emoji {
+        flex: none;
         font-size: 1.5rem;
         line-height: 1;
       }
 
+      // Name (prominent) stacked over the `:shortcode:` (muted), both truncated.
+      &-text {
+        display: flex;
+        flex-direction: column;
+        min-inline-size: 0;
+        line-height: 1.2;
+      }
+
       &-name {
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        font-size: 0.875rem;
+      }
+
+      &-shortcode {
         overflow: hidden;
         color: var(--str-chat__emoji-picker-secondary-text-color);
         white-space: nowrap;
         text-overflow: ellipsis;
+        font-size: 0.8125rem;
       }
     }