feat: add external errors prop to TokenizedInput (#387)

Author: DenisVershkov

src/components/TokenizedInput/context/TokenizedInputContext.tsx

@@ -36,6 +36,7 @@ export function TokenizedInputContextProvider<T extends TokenValueBase>({
     defaultTokens,
     transformTokens,
     validateToken,
+    tokenErrors,
     formatToken,
     fields,
     placeholder,
@@ -56,6 +57,7 @@ export function TokenizedInputContextProvider<T extends TokenValueBase>({
         defaultTokens,
         transformTokens,
         validateToken,
+        tokenErrors,
         formatToken,
         fields,
         placeholder,

src/components/TokenizedInput/hooks/__tests__/useTokenizedInputInfo.test.ts

@@ -156,6 +156,127 @@ describe('useTokenizedInputInfo', () => {
         expect(mockOnChange).toHaveBeenCalledWith([]);
     });
 
+    describe('tokenErrors', () => {
+        it('should merge external errors with validateToken errors', () => {
+            const externalTokens = [{key: 'User', value: 'Ivan'}];
+            const validateToken = () => ({key: 'internal error'});
+            const tokenErrors = [{value: 'external error'}];
+
+            const {result} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken,
+                    tokenErrors,
+                }),
+            );
+
+            expect(result.current.state.tokens[0].errors).toEqual({
+                key: 'internal error',
+                value: 'external error',
+            });
+        });
+
+        it('should give external errors priority over validateToken for the same field', () => {
+            const externalTokens = [{key: 'User', value: 'Ivan'}];
+            const validateToken = () => ({key: 'internal'});
+            const tokenErrors = [{key: 'external'}];
+
+            const {result} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken,
+                    tokenErrors,
+                }),
+            );
+
+            expect(result.current.state.tokens[0].errors).toEqual({key: 'external'});
+        });
+
+        it('should not apply external errors to new tokens', () => {
+            const externalTokens = [{key: 'User', value: 'Ivan'}];
+            const tokenErrors = [undefined, {key: 'error'}];
+
+            const {result} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken: false,
+                    tokenErrors,
+                }),
+            );
+
+            act(() => {
+                result.current.callbacks.onChangeToken(1, {key: 'Status'});
+            });
+
+            expect(result.current.state.tokens[1].kind).toBe('new');
+            expect(result.current.state.tokens[1].errors).toBeUndefined();
+        });
+
+        it('should skip undefined entries in tokenErrors', () => {
+            const externalTokens = [
+                {key: 'User', value: 'Ivan'},
+                {key: 'Status', value: 'Active'},
+            ];
+            const tokenErrors = [undefined, {key: 'error'}];
+
+            const {result} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken: false,
+                    tokenErrors,
+                }),
+            );
+
+            expect(result.current.state.tokens[0].errors).toBeUndefined();
+            expect(result.current.state.tokens[1].errors).toEqual({key: 'error'});
+        });
+
+        it('should update displayed errors when tokenErrors prop changes', () => {
+            const externalTokens = [{key: 'User', value: 'Ivan'}];
+            let tokenErrors: ({key?: string} | undefined)[] = [{key: 'old error'}];
+
+            const {result, rerender} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken: false,
+                    tokenErrors,
+                }),
+            );
+
+            expect(result.current.state.tokens[0].errors).toEqual({key: 'old error'});
+
+            tokenErrors = [{key: 'new error'}];
+            rerender();
+
+            expect(result.current.state.tokens[0].errors).toEqual({key: 'new error'});
+        });
+
+        it('should show no errors when tokenErrors is undefined', () => {
+            const externalTokens = [{key: 'User', value: 'Ivan'}];
+
+            const {result} = renderHook(() =>
+                useTokenizedInputInfo({
+                    tokens: externalTokens,
+                    fields: mockFields,
+                    onChange: mockOnChange,
+                    validateToken: false,
+                }),
+            );
+
+            expect(result.current.state.tokens[0].errors).toBeUndefined();
+        });
+    });
+
     it('should handle undo and redo', () => {
         const externalTokens = [{key: 'User', value: 'Ivan'}];
 

src/components/TokenizedInput/hooks/useTokenizedInputInfo.ts

@@ -26,6 +26,7 @@ export const useTokenizedInputInfo = <T extends TokenValueBase>({
     validateToken = defaultValidateToken,
     formatToken,
     tokens: externalTokens,
+    tokenErrors,
     fields,
     placeholder,
     className,
@@ -186,10 +187,20 @@ export const useTokenizedInputInfo = <T extends TokenValueBase>({
         [isClearable, externalTokens.length, defaultTokens.length, isEditable],
     );
 
+    const displayedTokens = React.useMemo(() => {
+        if (!tokenErrors) return tokens;
+        return tokens.map((token, i) => {
+            if (token.kind === 'new') return token;
+            const externalError = tokenErrors[i];
+            if (!externalError) return token;
+            return {...token, errors: {...token.errors, ...externalError}};
+        });
+    }, [tokens, tokenErrors]);
+
     return React.useMemo(
         () => ({
             state: {
-                tokens,
+                tokens: displayedTokens,
                 wrapperRef,
                 defaultTokens,
                 fields,
@@ -209,7 +220,6 @@ export const useTokenizedInputInfo = <T extends TokenValueBase>({
             },
         }),
         [
-            tokens,
             defaultTokens,
             fields,
             isEditable,
@@ -223,6 +233,7 @@ export const useTokenizedInputInfo = <T extends TokenValueBase>({
             onClearInput,
             onUndo,
             onRedo,
+            displayedTokens,
         ],
     );
 };

src/components/TokenizedInput/types.ts

@@ -219,6 +219,8 @@ export interface TokenizedInputData<T extends TokenValueBase> {
     transformTokens?: (tokens: T[]) => Token<T>[];
     /** Validates a token */
     validateToken?: ((token: T) => Partial<Record<keyof T, string>> | undefined) | false;
+    /** External token errors — array parallel to tokens. Merged with validateToken errors per-field; on conflict the external error wins. */
+    tokenErrors?: (Partial<Record<keyof T, string>> | undefined)[];
     /** Formats a token value */
     formatToken?: (token: T) => T;
     /** Field definitions; order matches display order */