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.tsxindex 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.tsxindex 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.tsxindex 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}hasEntriesOnFocusdebounceMs={0}status={status}diff --git a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx b/packages/core/src/Tokenizer/XDSTokenizer.test.tsxindex 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 elementconst popoverOpenState = new WeakMap<HTMLElement, boolean>();+// Mock ResizeObserver for jsdom+class MockResizeObserver {+ observe() {}+ unobserve() {}+ disconnect() {}+}+// Mock Popover API for jsdombeforeAll(() => {+ 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.tsxindex 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.tsindex 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,