Skip to content

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

TypeScript

feat(Tokenizer): use top layer for unfocusedLayer overflow (#983)

Cindy Zhang3d57625f74ec
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
index f350c7d6ca..3a7f98a011 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
@@ -8,7 +8,7 @@
*/
import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
import {XDSTokenizer} from './XDSTokenizer';
import type {XDSSearchSource, XDSSearchableItem} from '../Typeahead/types';
@@ -378,7 +378,7 @@ describe('XDSTokenizer', () => {
expect(screen.getByText('Charlie')).toBeInTheDocument();
});
- it('unfocusedLayer: renders layer wrapper divs', () => {
+ it('unfocusedLayer: renders placeholder and top-layer popover', () => {
const {container} = render(
<XDSTokenizer
label="Members"
@@ -389,17 +389,68 @@ describe('XDSTokenizer', () => {
data-testid="tokenizer"
/>,
);
+ // The wrapper should be rendered inside the placeholder (truncated view in-flow)
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(wrapper).toBeInTheDocument();
+ // A popover element should exist for the top-layer expanded content
+ const popover = container.querySelector('[popover]');
+ expect(popover).toBeInTheDocument();
+ // Only one group role (the wrapper)
expect(container.querySelectorAll('[role="group"]').length).toBe(1);
});
+ it('unfocusedLayer: shows expanded content in popover on focus', () => {
+ render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1], users[2]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedLayer"
+ data-testid="tokenizer"
+ />,
+ );
+ const wrapper = screen.getByTestId('tokenizer');
+ // Focus the wrapper to expand
+ fireEvent.focusIn(wrapper);
+ // showPopover should have been called
+ expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+ // All tokens should be visible
+ expect(screen.getByText('Alice')).toBeInTheDocument();
+ expect(screen.getByText('Bob')).toBeInTheDocument();
+ expect(screen.getByText('Charlie')).toBeInTheDocument();
+ });
+
+ it('unfocusedLayer: collapses on blur', () => {
+ const {container} = render(
+ <XDSTokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[users[0], users[1], users[2]]}
+ onChange={() => {}}
+ tokenOverflowBehavior="unfocusedLayer"
+ data-testid="tokenizer"
+ />,
+ );
+ const wrapper = screen.getByTestId('tokenizer');
+ // Focus to expand — fires on wrapper in the placeholder
+ act(() => {
+ fireEvent.focusIn(wrapper);
+ });
+ // After focus, content moves to the popover. We need to blur
+ // from the popover content, not the original wrapper.
+ // Get the popover element and blur from it.
+ const popover = container.querySelector('[popover]');
+ expect(popover).toBeInTheDocument();
+ // Find the wrapper again (it may have moved into the popover)
+ const expandedWrapper = screen.getByTestId('tokenizer');
+ act(() => {
+ fireEvent.focusOut(expandedWrapper, {relatedTarget: document.body});
+ });
+ // hidePopover should have been called
+ expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+ });
+
it('unfocusedInline: does not truncate when no tokens', () => {
render(
<XDSTokenizer
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.tsx b/packages/core/src/Tokenizer/XDSTokenizer.tsx
index 3f7bca5738..9b607d7b1e 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.tsx
@@ -36,6 +36,7 @@ import {XDSToken} from '../Token';
import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
import {XDSOverflowList} from '../OverflowList';
+import {useXDSLayer} from '../Layer/useXDSLayer';
import {
colorVars,
spacingVars,
@@ -261,22 +262,17 @@ const styles = stylex.create({
truncatedMd: {
height: sizeVars['--size-element-md'],
},
- layerOuter: {
- position: 'relative',
- zIndex: 1,
- },
- layerOuterSm: {
+ layerPlaceholderSm: {
height: sizeVars['--size-element-sm'],
},
- layerOuterMd: {
+ layerPlaceholderMd: {
height: sizeVars['--size-element-md'],
},
- layerInner: {
- position: 'absolute',
- top: 0,
- insetInlineStart: 0,
- insetInlineEnd: 0,
- zIndex: 1,
+ layerPopover: {
+ // Top-layer popover: match the anchor width exactly so the expanded
+ // tokenizer looks like an in-place expansion, overlapping the
+ // placeholder from its top edge.
+ width: 'anchor-size(width)',
},
overflowText: {
flexShrink: 0,
@@ -380,23 +376,64 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
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();
- }
- }, []);
+ // Layer for unfocusedLayer mode — promotes expanded content to the top layer
+ // so it isn't clipped by ancestor overflow.
+ const isLayerMode = tokenOverflowBehavior === 'unfocusedLayer';
+ const layer = useXDSLayer({mode: 'context'});
+ const layerContentRef = useRef<HTMLDivElement>(null);
+
+ // Anchor the layer to the placeholder element
+ const placeholderRef = useCallback(
+ (el: HTMLElement | null) => {
+ if (isLayerMode) {
+ layer.ref(el);
+ }
+ },
+ [isLayerMode, layer],
+ );
- const handleBlurCapture = useCallback((e: React.FocusEvent) => {
- if (!wrapperRef.current?.contains(e.relatedTarget as Node)) {
- setIsFocusedWithin(false);
- }
- }, []);
+ // For the layer variant, focus can be in either the placeholder or the
+ // popover content. We track both to decide when focus has truly left.
+ const isFocusInTokenizer = useCallback(
+ (target: Node | null): boolean => {
+ if (!target) return false;
+ if (wrapperRef.current?.contains(target)) return true;
+ if (layerContentRef.current?.contains(target)) return true;
+ // Also check the popover element itself (the layer wrapper)
+ const popoverEl = document.getElementById(layer.id);
+ if (popoverEl?.contains(target)) return true;
+ return false;
+ },
+ [layer.id],
+ );
+
+ const handleFocusCapture = useCallback(
+ (e: React.FocusEvent) => {
+ setIsFocusedWithin(true);
+ if (isLayerMode) {
+ layer.show();
+ }
+ // When focus enters from outside, redirect to the input so the user
+ // doesn't have to tab through every token remove button.
+ const comingFromOutside = !isFocusInTokenizer(e.relatedTarget as Node);
+ if (comingFromOutside && e.target !== inputRef.current) {
+ inputRef.current?.focus();
+ }
+ },
+ [isLayerMode, layer, isFocusInTokenizer],
+ );
+
+ const handleBlurCapture = useCallback(
+ (e: React.FocusEvent) => {
+ if (!isFocusInTokenizer(e.relatedTarget as Node)) {
+ setIsFocusedWithin(false);
+ if (isLayerMode) {
+ layer.hide();
+ }
+ }
+ },
+ [isLayerMode, layer, isFocusInTokenizer],
+ );
const isAtMax = maxEntries != null && value.length >= maxEntries;
@@ -479,9 +516,18 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
// Click wrapper to focus input
const handleWrapperClick = useCallback(() => {
if (!isDisabled) {
- inputRef.current?.focus();
+ if (isLayerMode) {
+ // The input always lives in the popover. Show it and focus.
+ layer.show();
+ setIsFocusedWithin(true);
+ // The input is already mounted in the popover (not conditional),
+ // so we can focus it directly.
+ inputRef.current?.focus();
+ } else {
+ inputRef.current?.focus();
+ }
}
- }, [isDisabled]);
+ }, [isDisabled, isLayerMode, layer]);
const ariaDescribedBy =
[
@@ -631,13 +677,76 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
</div>
);
- if (tokenOverflowBehavior === 'unfocusedLayer') {
- const layerOuterSizeStyle =
- size === 'sm' ? styles.layerOuterSm : styles.layerOuterMd;
+ if (isLayerMode) {
+ const placeholderSizeStyle =
+ size === 'sm'
+ ? styles.layerPlaceholderSm
+ : styles.layerPlaceholderMd;
return (
- <div {...stylex.props(styles.layerOuter, layerOuterSizeStyle)}>
- <div {...stylex.props(styles.layerInner)}>{wrapperContent}</div>
- </div>
+ <>
+ {/* Placeholder preserves layout height, acts as the CSS
+ anchor, and shows the collapsed overflow summary.
+ Clicking it opens the popover and focuses the input. */}
+ <div
+ ref={placeholderRef}
+ onClick={handleWrapperClick}
+ {...mergeProps(
+ xdsClassName('tokenizer', {size}),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.wrapper,
+ value.length > 0 && styles.wrapperWithTokens,
+ placeholderSizeStyle,
+ isTruncated && styles.truncatedWrapper,
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ ),
+ )}>
+ {isTruncated && (
+ <>
+ {startIcon && (
+ <XDSIcon icon={startIcon} size="sm" color="primary" />
+ )}
+ <XDSOverflowList
+ gap={1}
+ behavior="observeParent"
+ overflowRenderer={items => (
+ <span {...stylex.props(styles.overflowText)}>
+ +{items.length} more
+ </span>
+ )}>
+ {tokens}
+ </XDSOverflowList>
+ </>
+ )}
+ </div>
+ {/* Expanded content always lives in the top layer so the
+ input/tokens never unmount during the focus transition.
+ The popover is shown/hidden via layer.show()/hide(). */}
+ {layer.render(
+ <div
+ ref={layerContentRef}
+ onFocusCapture={handleFocusCapture}
+ onBlurCapture={handleBlurCapture}>
+ {wrapperContent}
+ </div>,
+ {
+ placement: 'below',
+ alignment: 'start',
+ xstyle: styles.layerPopover,
+ // Override position-area to overlap the anchor from its
+ // top edge rather than sitting below it.
+ style: {
+ positionArea: undefined,
+ positionTryFallbacks: undefined,
+ top: 'anchor(top)',
+ left: 'anchor(start)',
+ } as React.CSSProperties,
+ },
+ )}
+ </>
);
}