Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve ChatTokenizedText docs and block examples (#1856)

Kenton Quatman825b934328cb
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.doc.mjs b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.doc.mjs
new file mode 100644
index 0000000000..83ecd2ad4a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatTokenizedText — Colors',
+ description: 'Tokens with different color variants to distinguish mentions, bugs, and features. Use variant colors to create a visual taxonomy — blue for people, red for bugs, green for features.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ChatTokenizedText', 'Chat'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.tsx b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.tsx
new file mode 100644
index 0000000000..6e75294a23
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextColors.tsx
@@ -0,0 +1,28 @@
+'use client';
+
+import {
+ XDSChatTokenizedText,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatMessageList,
+} from '@xds/core/Chat';
+
+const mixedTokens = [
+ {value: '@cindy', label: '@Cindy', variant: 'blue' as const},
+ {value: '#bug', label: '#bug', variant: 'red' as const},
+ {value: '#feat', label: '#feature', variant: 'green' as const},
+];
+
+export default function ChatTokenizedTextColors() {
+ return (
+ <XDSChatMessageList>
+ <XDSChatMessage sender="system">
+ <XDSChatMessageBubble>
+ <XDSChatTokenizedText tokens={mixedTokens}>
+ @cindy filed #bug and #feat for the sprint
+ </XDSChatTokenizedText>
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.doc.mjs b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.doc.mjs
deleted file mode 100644
index 323c0136cc..0000000000
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatTokenizedText — Mixed Variants',
- description:
- 'Message with tokens using different color variants for mentions, bugs, and features.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatTokenizedText', 'Chat'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.tsx b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.tsx
deleted file mode 100644
index ec45b1c373..0000000000
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMixedVariantTokens.tsx
+++ /dev/null
@@ -1,25 +0,0 @@
-'use client';
-
-import {
- XDSChatTokenizedText,
- XDSChatMessage,
- XDSChatMessageBubble,
-} from '@xds/core/Chat';
-
-const tokens = [
- {value: '@cindy', label: '@Cindy', variant: 'blue' as const},
- {value: '#bug', label: '#bug', variant: 'red' as const},
- {value: '#feat', label: '#feature', variant: 'green' as const},
-];
-
-export default function ChatTokenizedTextMixedVariantTokens() {
- return (
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- <XDSChatTokenizedText tokens={tokens}>
- @cindy filed #bug and #feat for the sprint
- </XDSChatTokenizedText>
- </XDSChatMessageBubble>
- </XDSChatMessage>
- );
-}
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.doc.mjs b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.doc.mjs
index 9404756a9c..e96f7c62dc 100644
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'ChatTokenizedText — Multiple Mentions',
- description:
- 'Message with multiple @mention tokens resolved to display names inline.',
+ name: 'ChatTokenizedText — Multiple Tokens',
+ description: 'A message with several @mention tokens. Each matching pattern is independently replaced with its display name badge, so multiple people can be referenced in a single message.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['ChatTokenizedText', 'Chat'],
};
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.tsx b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.tsx
index 8cfcf31696..80aa777226 100644
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.tsx
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextMultipleMentions.tsx
@@ -4,22 +4,25 @@ import {
XDSChatTokenizedText,
XDSChatMessage,
XDSChatMessageBubble,
+ XDSChatMessageList,
} from '@xds/core/Chat';
const tokens = [
{value: '@cindy', label: '@Cindy Zhang', variant: 'blue' as const},
- {value: '@navi', label: '@Navi', variant: 'blue' as const},
+ {value: '@agent', label: '@Agent', variant: 'blue' as const},
{value: '@alex', label: '@Alex Rivera', variant: 'blue' as const},
];
export default function ChatTokenizedTextMultipleMentions() {
return (
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- <XDSChatTokenizedText tokens={tokens}>
- @cindy and @alex can @navi help with the review?
- </XDSChatTokenizedText>
- </XDSChatMessageBubble>
- </XDSChatMessage>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ <XDSChatTokenizedText tokens={tokens}>
+ @cindy and @alex can @agent help with the review?
+ </XDSChatTokenizedText>
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.doc.mjs
index 7516c642b1..10d983b266 100644
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'ChatTokenizedText',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.tsx b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.tsx
index c104bb2bba..63aa887c6c 100644
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextShowcase.tsx
@@ -4,20 +4,25 @@ import {
XDSChatTokenizedText,
XDSChatMessage,
XDSChatMessageBubble,
+ XDSChatMessageList,
} from '@xds/core/Chat';
-const tokens = [
- {value: '@cindy', label: '@Cindy Zhang', variant: 'blue' as const},
+const mixedTokens = [
+ {value: '@cindy', label: '@Cindy', variant: 'blue' as const},
+ {value: '#bug', label: '#bug', variant: 'red' as const},
+ {value: '#feat', label: '#feature', variant: 'green' as const},
];
export default function ChatTokenizedTextShowcase() {
return (
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- <XDSChatTokenizedText tokens={tokens}>
- Hey @cindy can you review this?
- </XDSChatTokenizedText>
- </XDSChatMessageBubble>
- </XDSChatMessage>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="system">
+ <XDSChatMessageBubble>
+ <XDSChatTokenizedText tokens={mixedTokens}>
+ @cindy filed #bug and #feat for the sprint
+ </XDSChatTokenizedText>
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.doc.mjs b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.doc.mjs
deleted file mode 100644
index 0d3a8bc305..0000000000
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatTokenizedText — Single Mention',
- description:
- 'Message with a single @mention token highlighted inline.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatTokenizedText', 'Chat'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.tsx b/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.tsx
deleted file mode 100644
index fe7a98516f..0000000000
--- a/packages/cli/templates/blocks/components/ChatTokenizedText/ChatTokenizedTextSingleMention.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-'use client';
-
-import {
- XDSChatTokenizedText,
- XDSChatMessage,
- XDSChatMessageBubble,
-} from '@xds/core/Chat';
-
-const tokens = [
- {value: '@cindy', label: '@Cindy Zhang', variant: 'blue' as const},
-];
-
-export default function ChatTokenizedTextSingleMention() {
- return (
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- <XDSChatTokenizedText tokens={tokens}>
- Hey @cindy can you review this?
- </XDSChatTokenizedText>
- </XDSChatMessageBubble>
- </XDSChatMessage>
- );
-}
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index b1223094bf..0ea487e699 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -159,10 +159,10 @@ export const docs = {
},
{
name: 'XDSChatTokenizedText',
- description: 'Renders text with token patterns replaced by inline XDSBadge components. Use inside XDSChatMessageBubble to display @mentions or other tokens as styled badges.',
+ description: 'Renders a text string with token patterns replaced by inline XDSBadge components. Wrap any message body inside XDSChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is — so you can use ChatTokenizedText unconditionally on every message.',
props: [
- {name: 'children', type: 'string', description: 'The message text containing token patterns.', required: true},
- {name: 'tokens', type: 'XDSChatMessageTokenConfig[]', description: 'Token definitions. Each has pattern (string to match), label (display text), and optional variant.'},
+ {name: 'children', type: 'string', description: 'The plain text message containing serialized token values. Patterns matching a token\'s value are replaced with badge components inline.', required: true},
+ {name: 'tokens', type: 'XDSChatComposerToken[]', description: 'Token definitions — same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.'},
],
},
],
@@ -354,8 +354,8 @@ export const docsZh = {
{
name: 'XDSChatTokenizedText',
description:
- '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,以徽章样式显示 @提及或其他标记。',
- propDescriptions: {children: '包含标记模式的消息文本。', tokens: '标记定义。每个包含 pattern(匹配字符串)、label(显示文本)和可选 variant。'},
+ '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,将 @提及、#标签或 /命令显示为样式化徽章。未提供标记时以纯文本渲染,因此可以无条件使用。',
+ propDescriptions: {children: '包含序列化标记值的纯文本消息。匹配标记值的模式将被替换为内联徽章组件。', tokens: '标记定义 — 与触发器 onSelect 返回的类型相同。每个包含 value(匹配字符串)、label(显示文本)以及可选的 variant 和 icon。'},
},
{
name: 'XDSChatLayout',
@@ -520,11 +520,11 @@ export const docsDense = {
},
},
{
-name: 'XDSChatTokenizedText',
- description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions',
+ name: 'XDSChatTokenizedText',
+ description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions, #tags, /commands; degrades to plain text when no tokens match',
propDescriptions: {
- children: 'msg text w/ token patterns',
- tokens: 'token defs: pattern+label+variant',
+ children: 'plain text msg w/ serialized token values; matching patterns become inline badges',
+ tokens: 'token defs (same type as composer input): value+label+variant+icon',
},
},
{