Skip to content

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

TypeScript

tokenizer truncation behavior (#880)

Andrey Godera53a99a7c4ab
diff --git a/apps/storybook/stories/PowerSearch.stories.tsx b/apps/storybook/stories/PowerSearch.stories.tsx
index ef0d13b1e1..18948a3b48 100644
--- a/apps/storybook/stories/PowerSearch.stories.tsx
+++ b/apps/storybook/stories/PowerSearch.stories.tsx
@@ -962,3 +962,80 @@ export const WithEndContentPowerSearch: Story = {
},
name: 'With End Content and Result Count',
};
+
+const overflowFilters: PowerSearchFilter[] = [
+ {
+ field: 'status',
+ operator: 'any_of',
+ value: {type: 'enum_list', value: ['open', 'in_progress']},
+ },
+ {field: 'priority', operator: 'is', value: {type: 'enum', value: 'p1'}},
+ {
+ field: 'title',
+ operator: 'contains',
+ value: {type: 'string', value: 'login'},
+ },
+ {
+ field: 'assignee',
+ operator: 'any_of',
+ value: {
+ type: 'entity_list',
+ value: [{id: 'user-1', label: 'Alice Johnson'}],
+ },
+ },
+ {
+ field: 'tags',
+ operator: 'include',
+ value: {type: 'enum_list', value: ['bug']},
+ },
+];
+
+export const OverflowInline: Story = {
+ render: args => {
+ const [filters, setFilters] =
+ useState<PowerSearchFilter[]>(overflowFilters);
+ return (
+ <div>
+ <XDSPowerSearch
+ {...args}
+ config={fullConfig}
+ filters={filters}
+ onChange={newFilters => setFilters([...newFilters])}
+ tokenOverflowBehavior="unfocusedInline"
+ />
+ <p style={{marginTop: 8}}>
+ This text will shift down when the search bar expands on focus.
+ </p>
+ </div>
+ );
+ },
+ args: {
+ placeholder: 'Add more filters...',
+ },
+ name: 'Overflow Inline',
+};
+
+export const OverflowLayer: Story = {
+ render: args => {
+ const [filters, setFilters] =
+ useState<PowerSearchFilter[]>(overflowFilters);
+ return (
+ <div>
+ <XDSPowerSearch
+ {...args}
+ config={fullConfig}
+ filters={filters}
+ onChange={newFilters => setFilters([...newFilters])}
+ tokenOverflowBehavior="unfocusedLayer"
+ />
+ <p style={{marginTop: 8}}>
+ This text should not shift when the search bar expands on focus.
+ </p>
+ </div>
+ );
+ },
+ args: {
+ placeholder: 'Add more filters...',
+ },
+ name: 'Overflow Layer',
+};
diff --git a/apps/storybook/stories/Tokenizer.stories.tsx b/apps/storybook/stories/Tokenizer.stories.tsx
index 97ad9089ce..d3192563e4 100644
--- a/apps/storybook/stories/Tokenizer.stories.tsx
+++ b/apps/storybook/stories/Tokenizer.stories.tsx
@@ -209,6 +209,70 @@ export const WithEntriesOnFocus: Story = {
name: 'With Entries On Focus',
};
+export const OverflowInline: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSSearchableItem[]>([
+ users[0],
+ users[1],
+ users[2],
+ users[3],
+ users[4],
+ users[5],
+ ]);
+ return (
+ <div>
+ <XDSTokenizer
+ {...args}
+ searchSource={userSource}
+ value={value}
+ onChange={items => setValue(items)}
+ tokenOverflowBehavior="unfocusedInline"
+ />
+ <p style={{marginTop: 8}}>
+ This text will shift down when the tokenizer expands on focus.
+ </p>
+ </div>
+ );
+ },
+ args: {
+ label: 'Team Members',
+ placeholder: 'Add more...',
+ },
+ name: 'Overflow Inline',
+};
+
+export const OverflowLayer: Story = {
+ render: args => {
+ const [value, setValue] = useState<XDSSearchableItem[]>([
+ users[0],
+ users[1],
+ users[2],
+ users[3],
+ users[4],
+ users[5],
+ ]);
+ return (
+ <div>
+ <XDSTokenizer
+ {...args}
+ searchSource={userSource}
+ value={value}
+ onChange={items => setValue(items)}
+ tokenOverflowBehavior="unfocusedLayer"
+ />
+ <p style={{marginTop: 8}}>
+ This text should not shift when the tokenizer expands on focus.
+ </p>
+ </div>
+ );
+ },
+ args: {
+ label: 'Team Members',
+ placeholder: 'Add more...',
+ },
+ name: 'Overflow Layer',
+};
+
export const WithEndContent: Story = {
render: args => {
const [value, setValue] = useState<XDSSearchableItem[]>([
diff --git a/packages/core/src/PowerSearch/XDSPowerSearch.tsx b/packages/core/src/PowerSearch/XDSPowerSearch.tsx
index e524a7fab7..b6c9f4ae66 100644
--- a/packages/core/src/PowerSearch/XDSPowerSearch.tsx
+++ b/packages/core/src/PowerSearch/XDSPowerSearch.tsx
@@ -11,7 +11,6 @@
* - /packages/core/src/PowerSearch/XDSPowerSearch.doc.mjs
*/
-
import React, {
useCallback,
useImperativeHandle,
@@ -21,7 +20,11 @@ import React, {
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
-import {XDSTokenizer, type XDSTokenizerHandle} from '../Tokenizer';
+import {
+ XDSTokenizer,
+ type XDSTokenizerHandle,
+ type XDSTokenizerOverflowBehavior,
+} from '../Tokenizer';
import {XDSTypeaheadItem} from '../Typeahead/XDSTypeaheadItem';
import {XDSToken} from '../Token';
import {XDSIcon} from '../Icon';
@@ -355,6 +358,12 @@ export interface XDSPowerSearchProps {
popoverSaveButtonLabel?: string;
/** Timezone ID for date formatting. */
timezoneID?: string;
+ /**
+ * Controls how tokens overflow when the container is too narrow.
+ * Forwarded to XDSTokenizer.
+ * @default 'none'
+ */
+ tokenOverflowBehavior?: XDSTokenizerOverflowBehavior;
/**
* Content to display at the end of the input row.
* Useful for action buttons or other controls.
@@ -457,6 +466,7 @@ export function XDSPowerSearch({
maxTokenLength = 40,
popoverSaveButtonLabel = 'Apply',
timezoneID,
+ tokenOverflowBehavior,
endContent,
resultCount,
ref,
@@ -787,6 +797,7 @@ export function XDSPowerSearch({
startIcon={startIcon}
endContent={combinedEndContent}
isDisabled={isDisabled}
+ tokenOverflowBehavior={tokenOverflowBehavior}
hasEntriesOnFocus
debounceMs={0}
status={status}
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
index 58314259cb..f350c7d6ca 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
@@ -18,8 +18,17 @@ const originalMatches = HTMLElement.prototype.matches;
// Track popover open state per element
const popoverOpenState = new WeakMap<HTMLElement, boolean>();
+// Mock ResizeObserver for jsdom
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
// Mock Popover API for jsdom
beforeAll(() => {
+ globalThis.ResizeObserver =
+ MockResizeObserver as unknown as typeof ResizeObserver;
HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
popoverOpenState.set(this, true);
const event = new Event('toggle');
@@ -312,4 +321,99 @@ describe('XDSTokenizer', () => {
const tokenElements = wrapper.querySelectorAll(':scope > span');
expect(tokenElements.length).toBeGreaterThanOrEqual(2);
});
+
+ describe('tokenOverflowBehavior', () => {
+ it('none: renders all tokens directly without XDSOverflowList', () => {
+ const {container} = render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="none"
+ data-testid="tokenizer"
+ />,
+ );
+ expect(screen.getByText('Alice')).toBeInTheDocument();
+ expect(screen.getByText('Bob')).toBeInTheDocument();
+ // Should not have overflow list measurement containers
+ expect(
+ container.querySelector('[data-overflow-list]'),
+ ).not.toBeInTheDocument();
+ });
+
+ it('unfocusedInline: renders XDSOverflowList when blurred', () => {
+ render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1], users[2]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedInline"
+ data-testid="tokenizer"
+ />,
+ );
+ // XDSOverflowList renders a hidden measurement container plus visible items,
+ // so tokens appear multiple times in the DOM
+ expect(screen.getAllByText('Alice').length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('unfocusedInline: removes truncation on focus', () => {
+ render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1], users[2]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedInline"
+ data-testid="tokenizer"
+ />,
+ );
+ const wrapper = screen.getByTestId('tokenizer');
+ // Focus the wrapper (simulates focusing the input within)
+ fireEvent.focusIn(wrapper);
+ // All tokens should be directly rendered (no overflow list)
+ expect(screen.getByText('Alice')).toBeInTheDocument();
+ expect(screen.getByText('Bob')).toBeInTheDocument();
+ expect(screen.getByText('Charlie')).toBeInTheDocument();
+ });
+
+ it('unfocusedLayer: renders layer wrapper divs', () => {
+ const {container} = render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedLayer"
+ data-testid="tokenizer"
+ />,
+ );
+ const wrapper = screen.getByTestId('tokenizer');
+ // The wrapper should be inside a layer structure (inner > outer)
+ const layerInner = wrapper.parentElement;
+ const layerOuter = layerInner?.parentElement;
+ // Layer outer should have position: relative
+ expect(layerOuter).toBeInTheDocument();
+ expect(layerInner).toBeInTheDocument();
+ // Verify the layer structure exists (inner is absolute positioned)
+ expect(container.querySelectorAll('[role="group"]').length).toBe(1);
+ });
+
+ it('unfocusedInline: does not truncate when no tokens', () => {
+ render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedInline"
+ data-testid="tokenizer"
+ />,
+ );
+ // With no tokens, should not be in truncated state
+ const wrapper = screen.getByTestId('tokenizer');
+ expect(wrapper).toBeInTheDocument();
+ });
+ });
});
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.tsx b/packages/core/src/Tokenizer/XDSTokenizer.tsx
index 04cd8949c9..b365ab43ae 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.tsx
@@ -18,6 +18,7 @@ import React, {
useImperativeHandle,
useMemo,
useRef,
+ useState,
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
@@ -34,11 +35,13 @@ import {
import {XDSToken} from '../Token';
import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
+import {XDSOverflowList} from '../OverflowList';
import {
colorVars,
spacingVars,
radiusVars,
sizeVars,
+ typeScaleVars,
} from '../theme/tokens.stylex';
import type {XDSSearchableItem, XDSSearchSource} from '../Typeahead/types';
import {xdsClassName, mergeProps} from '../utils';
@@ -63,6 +66,17 @@ export type XDSTokenizerChange<T extends XDSSearchableItem> =
export type XDSTokenizerSize = 'sm' | 'md';
+/**
+ * Controls overflow behavior when tokens exceed the available width.
+ * - `'none'`: All tokens wrap normally (default).
+ * - `'unfocusedInline'`: Shows a single line with "+ N more" when unfocused, expands inline on focus.
+ * - `'unfocusedLayer'`: Shows a single line with "+ N more" when unfocused, expands as an overlay on focus.
+ */
+export type XDSTokenizerOverflowBehavior =
+ | 'none'
+ | 'unfocusedInline'
+ | 'unfocusedLayer';
+
/**
* Imperative handle for XDSTokenizer.
*/
@@ -126,6 +140,14 @@ export interface XDSTokenizerProps<T extends XDSSearchableItem> {
hasAutoFocus?: boolean;
/** Input size. @default 'md' */
size?: XDSTokenizerSize;
+ /**
+ * Controls how tokens overflow when the container is too narrow.
+ * - `'none'`: Tokens wrap to multiple lines (default).
+ * - `'unfocusedInline'`: Single line with "+ N more" when unfocused; expands inline on focus.
+ * - `'unfocusedLayer'`: Single line with "+ N more" when unfocused; expands as overlay on focus.
+ * @default 'none'
+ */
+ tokenOverflowBehavior?: XDSTokenizerOverflowBehavior;
/**
* Debounce delay in ms before triggering search after typing.
* Set to 0 for synchronous/local search sources that don't need debouncing.
@@ -229,6 +251,40 @@ const styles = stylex.create({
// wrapper padding is reduced for border concentricity.
paddingInlineStart: `calc(${spacingVars['--spacing-2']} - ${spacingVars['--spacing-1']} + 1px)`,
},
+ truncatedWrapper: {
+ flexWrap: 'nowrap',
+ overflow: 'hidden',
+ },
+ truncatedSm: {
+ height: sizeVars['--size-sm'],
+ },
+ truncatedMd: {
+ height: sizeVars['--size-md'],
+ },
+ layerOuter: {
+ position: 'relative',
+ zIndex: 1,
+ },
+ layerOuterSm: {
+ height: sizeVars['--size-sm'],
+ },
+ layerOuterMd: {
+ height: sizeVars['--size-md'],
+ },
+ layerInner: {
+ position: 'absolute',
+ top: 0,
+ insetInlineStart: 0,
+ insetInlineEnd: 0,
+ zIndex: 1,
+ },
+ overflowText: {
+ flexShrink: 0,
+ whiteSpace: 'nowrap',
+ fontSize: typeScaleVars['--text-supporting-size'],
+ color: colorVars['--color-text-secondary'],
+ paddingInline: spacingVars['--spacing-1'],
+ },
});
// =============================================================================
@@ -295,6 +351,7 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
endContent,
hasAutoFocus,
size = 'md',
+ tokenOverflowBehavior = 'none',
debounceMs,
onChangeQuery,
xstyle,
@@ -318,6 +375,29 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
},
}));
+ // Focus-within state for overflow truncation
+ const [isFocusedWithin, setIsFocusedWithin] = useState(false);
+ const isTruncated =
+ !isFocusedWithin && tokenOverflowBehavior !== 'none' && value.length > 0;
+
+ const handleFocusCapture = useCallback((e: React.FocusEvent) => {
+ setIsFocusedWithin(true);
+ // When focus enters from outside, redirect to the input so the user
+ // doesn't have to tab through every token remove button.
+ const comingFromOutside = !wrapperRef.current?.contains(
+ e.relatedTarget as Node,
+ );
+ if (comingFromOutside && e.target !== inputRef.current) {
+ inputRef.current?.focus();
+ }
+ }, []);
+
+ const handleBlurCapture = useCallback((e: React.FocusEvent) => {
+ if (!wrapperRef.current?.contains(e.relatedTarget as Node)) {
+ setIsFocusedWithin(false);
+ }
+ }, []);
+
const isAtMax = maxEntries != null && value.length >= maxEntries;
// Filter out already-selected items from search results
@@ -459,71 +539,109 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
xstyle={xstyle}
className={className}
style={style}>
- <div
- ref={wrapperRef}
- role="group"
- aria-label={label}
- onClick={handleWrapperClick}
- data-testid={testId}
- {...mergeProps(
- xdsClassName('tokenizer', {size}),
- stylex.props(
- inputWrapperStyles.base,
- styles.wrapper,
- value.length > 0 && styles.wrapperWithTokens,
- sizeStyle,
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- ),
- )}>
- {startIcon && <XDSIcon icon={startIcon} size="sm" color="primary" />}
- {tokens}
- <XDSBaseTypeahead
- ref={inputRef}
- searchSource={isAtMax ? emptySource : filteredSource}
- value={null}
- onChange={handleAdd}
- renderItem={renderItem}
- placeholder={value.length === 0 ? placeholder : ''}
- hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
- maxMenuItems={maxMenuItems}
- emptySearchResultsText={emptySearchResultsText}
- isDisabled={isDisabled}
- hasAutoFocus={hasAutoFocus}
- inputId={inputId}
- ariaDescribedBy={ariaDescribedBy}
- onChangeQuery={onChangeQuery}
- debounceMs={debounceMs}
- onKeyDown={handleKeyDown}
- anchorRef={wrapperRef}
- inputXStyle={
- isAtMax
- ? styles.inputAtMax
- : value.length > 0
- ? styles.inputCompact
- : undefined
- }
- />
- {(endContent || (hasClear && value.length > 0 && !isDisabled)) && (
- <div {...stylex.props(styles.endSection)}>
- {endContent}
- {hasClear && value.length > 0 && !isDisabled && (
- <button
- type="button"
- aria-label="Clear all"
- onClick={e => {
- e.stopPropagation();
- handleClearAll();
- }}
- {...stylex.props(styles.clearAllButton)}>
- <XDSIcon icon="close" size="sm" />
- </button>
+ {(() => {
+ const wrapperContent = (
+ <div
+ ref={wrapperRef}
+ role="group"
+ aria-label={label}
+ onClick={handleWrapperClick}
+ onFocusCapture={handleFocusCapture}
+ onBlurCapture={handleBlurCapture}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('tokenizer', {size}),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.wrapper,
+ value.length > 0 && styles.wrapperWithTokens,
+ isTruncated
+ ? size === 'sm'
+ ? styles.truncatedSm
+ : styles.truncatedMd
+ : sizeStyle,
+ isTruncated && styles.truncatedWrapper,
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ ),
+ )}>
+ {startIcon && (
+ <XDSIcon icon={startIcon} size="sm" color="primary" />
+ )}
+ {isTruncated ? (
+ <XDSOverflowList
+ gap={1}
+ behavior="observeParent"
+ overflowRenderer={items => (
+ <span {...stylex.props(styles.overflowText)}>
+ +{items.length} more
+ </span>
+ )}>
+ {tokens}
+ </XDSOverflowList>
+ ) : (
+ tokens
+ )}
+ <XDSBaseTypeahead
+ ref={inputRef}
+ searchSource={isAtMax ? emptySource : filteredSource}
+ value={null}
+ onChange={handleAdd}
+ renderItem={renderItem}
+ placeholder={value.length === 0 ? placeholder : ''}
+ hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
+ maxMenuItems={maxMenuItems}
+ emptySearchResultsText={emptySearchResultsText}
+ isDisabled={isDisabled}
+ hasAutoFocus={hasAutoFocus}
+ inputId={inputId}
+ ariaDescribedBy={ariaDescribedBy}
+ onChangeQuery={onChangeQuery}
+ debounceMs={debounceMs}
+ onKeyDown={handleKeyDown}
+ anchorRef={wrapperRef}
+ inputXStyle={
+ isAtMax || isTruncated
+ ? styles.inputAtMax
+ : value.length > 0
+ ? styles.inputCompact
+ : undefined
+ }
+ />
+ {(endContent || (hasClear && value.length > 0 && !isDisabled)) && (
+ <div {...stylex.props(styles.endSection)}>
+ {endContent}
+ {hasClear && value.length > 0 && !isDisabled && (
+ <button
+ type="button"
+ aria-label="Clear all"
+ onClick={e => {
+ e.stopPropagation();
+ handleClearAll();
+ }}
+ {...stylex.props(styles.clearAllButton)}>
+ <XDSIcon icon="close" size="sm" />
+ </button>
+ )}
+ </div>
)}
</div>
- )}
- </div>
+ );
+
+ if (tokenOverflowBehavior === 'unfocusedLayer') {
+ const layerOuterSizeStyle =
+ size === 'sm' ? styles.layerOuterSm : styles.layerOuterMd;
+ return (
+ <div {...stylex.props(styles.layerOuter, layerOuterSizeStyle)}>
+ <div {...stylex.props(styles.layerInner)}>{wrapperContent}</div>
+ </div>
+ );
+ }
+
+ return wrapperContent;
+ })()}
</XDSField>
);
}
diff --git a/packages/core/src/Tokenizer/index.ts b/packages/core/src/Tokenizer/index.ts
index 61444e5add..d7ae75fc5b 100644
--- a/packages/core/src/Tokenizer/index.ts
+++ b/packages/core/src/Tokenizer/index.ts
@@ -13,6 +13,7 @@ export {XDSTokenizer} from './XDSTokenizer';
export type {
XDSTokenizerProps,
XDSTokenizerSize,
+ XDSTokenizerOverflowBehavior,
XDSTokenizerChange,
XDSTokenizerHandle,
XDSTokenizerStatus,