feat(components): add TagAutocomplete (DS-5069)

.storybook/components/Roadmap/data.ts

@@ -332,4 +332,10 @@ export const rows: Rows = [
     stage: '🔵 experimental',
     planned: 'Q2 2026',
   },
+  {
+    component: 'TagList',
+    status: '✅ Done',
+    stage: '🔵 experimental',
+    planned: 'Q2 2026',
+  },
 ];

packages/components/src/components/Form/Form.stories.tsx

@@ -1,4 +1,4 @@
-import { type FormEvent, useState } from 'react';
+import { type FormEvent, useRef, useState } from 'react';
 
 import type { Meta, StoryObj } from '@storybook/react';
 
@@ -10,12 +10,14 @@ import { CheckboxGroup } from '../CheckboxGroup';
 import { DatePicker } from '../DatePicker';
 import { FlexBox } from '../FlexBox';
 import { FormField } from '../FormField';
+import { useListData } from '../index';
 import { Input } from '../Input';
 import { InputNumber } from '../InputNumber';
 import { spacing } from '../layout';
 import { Radio, RadioGroup } from '../RadioGroup';
 import { SearchInput } from '../SearchInput';
 import { Select } from '../Select';
+import { TagInput } from '../TagInput';
 import { Textarea } from '../Textarea';
 import { TimePicker } from '../TimePicker';
 import { Typography } from '../Typography';
@@ -426,6 +428,25 @@ export const FormFields: Story = {
   },
   name: 'All form fields',
   render: function Render() {
+    const tags = useListData<{ id: string; name: string }>({
+      initialItems: [{ id: 'react', name: 'React' }],
+    });
+
+    const tagCounter = useRef(1);
+
+    const addTags = (values: string[]) => {
+      tags.append(
+        ...values.map((name) => {
+          tagCounter.current += 1;
+
+          return {
+            id: `tag-${tagCounter.current}-${name}`,
+            name,
+          };
+        })
+      );
+    };
+
     return (
       <Form
         labelPlacement={{ xs: 'top', m: 'side' }}
@@ -438,6 +459,15 @@ export const FormFields: Story = {
           <Select.Item key="3">Option 3</Select.Item>
         </Select>
         <Input label="Input" placeholder="Type a word..." />
+        <TagInput<{ id: string; name: string }>
+          label="Tag input"
+          placeholder="Type and press Enter"
+          items={tags.items}
+          onAdd={addTags}
+          onRemove={(keys) => tags.remove(...keys)}
+        >
+          {(item) => <TagInput.Tag key={item.id}>{item.name}</TagInput.Tag>}
+        </TagInput>
         <Textarea label="Textarea" placeholder="Type a word..." />
         <InputNumber label="InputNumber" placeholder="Type a number..." />
         <SearchInput label="SearchInput" placeholder="Type a word..." />

packages/components/src/components/TagAutocomplete/TagAutocomplete.mdx

@@ -0,0 +1,183 @@
+import {
+  Props,
+  Story,
+  Meta,
+  Status,
+} from '../../../../../.storybook/components';
+
+import * as Stories from './TagAutocomplete.stories';
+
+<Meta of={Stories} />
+
+# TagAutocomplete
+
+<Status variant="draft" />
+
+A multi-tag entry with autocomplete suggestions. It behaves like `TagInput`
+for free-form values and adds a combobox popover for selecting known items.
+
+## Import
+
+```tsx
+import { TagAutocomplete } from '@koobiq/react-components';
+```
+
+## Usage
+
+<Story of={Stories.Base} />
+
+## Props
+
+<Props of={Stories.Base} />
+
+## Addons
+
+You can add extra content using the `startAddon` and `endAddon` props.
+
+<Story of={Stories.Addons} />
+
+## Items
+
+The tag collection is **owned by the consumer**. `TagAutocomplete` renders
+selected tags from `items`, renders suggestions from `listItems`, and emits
+intent events through `onAdd` / `onRemove`.
+
+Use stable keys for both selected tags and suggestions:
+
+```tsx
+<TagAutocomplete
+  items={tags.items}
+  onRemove={(keys) => tags.remove(...keys)}
+  onAdd={(values, context) => {
+    if (context.source === 'suggestion') {
+      tags.append(context.suggestion);
+    } else {
+      tags.append(...values.map(createTag));
+    }
+  }}
+  listItems={suggestions}
+  renderListItem={(item) => (
+    <TagAutocomplete.ListItem key={item.id} textValue={item.name}>
+      {item.name}
+    </TagAutocomplete.ListItem>
+  )}
+>
+  {(item) => (
+    <TagAutocomplete.Tag key={item.id} textValue={item.name}>
+      {item.name}
+    </TagAutocomplete.Tag>
+  )}
+</TagAutocomplete>
+```
+
+`TagAutocomplete.ListItem` provides the suggestion key and `textValue` used
+for filtering, exclusion of already selected tags, and the suggestion context.
+
+## Suggestions
+
+Suggestions open when the input receives focus. `defaultFilter(textValue,
+inputValue)` filters the popover list, while selected tags are excluded
+automatically by key and normalized `textValue`.
+
+Selecting a suggestion calls `onAdd(values, context)` with
+`context.source === 'suggestion'` and exposes the original item as
+`context.suggestion`.
+
+## Adding tags
+
+Free-form entry keeps the same behavior as `TagInput`: press <kbd>Enter</kbd>,
+type a split character, paste a delimited string, or blur the field with a
+non-empty input value. In those cases, `context.source` is `'enter'`,
+`'separator'`, `'paste'`, or `'blur'`.
+
+To also split on `;` or whitespace, pass a custom `splitPattern`.
+
+<Story of={Stories.SplitPattern} />
+
+## Preventing duplicates
+
+Suggestions that are already selected are hidden automatically. Free-form
+values are passed to `onAdd` as-is, so apply your own duplicate policy in the
+handler:
+
+```tsx
+onAdd={(values, context) => {
+  if (context.source === 'suggestion') {
+    tags.append(context.suggestion);
+
+    return;
+  }
+
+  const existing = new Set(tags.items.map((item) => item.name.toLowerCase()));
+  const fresh = values.filter((value) => !existing.has(value.toLowerCase()));
+
+  if (fresh.length === 0) return;
+  tags.append(...fresh.map(createTag));
+}}
+```
+
+<Story of={Stories.PreventDuplicates} />
+
+## Variant
+
+<Story of={Stories.Variant} />
+
+## Form field
+
+`TagAutocomplete` is a full form-field on par with `TagInput`. It accepts a
+visible or hidden `label`, a helper `caption`, `errorMessage`, `isInvalid`,
+`isRequired`, `fullWidth`, `labelPlacement`, and `labelAlign`.
+
+<Story of={Stories.FormField} />
+
+## Disabled
+
+When `isDisabled` is set, the input is disabled, tags render in a disabled
+state, and suggestions cannot be selected.
+
+<Story of={Stories.Disabled} />
+
+## Read-only
+
+When `isReadOnly` is set, the input remains focusable for navigation but no
+modifications are allowed. Typing is blocked, suggestions cannot be selected,
+and remove buttons are not rendered.
+
+<Story of={Stories.ReadOnly} />
+
+## Cleaner
+
+Enable the cleaner button with `isClearable`. Pressing it removes all tags,
+clears the text input, calls `onClear`, and returns focus to the input.
+
+<Story of={Stories.Clearable} />
+
+## Inside a Form
+
+When wrapped in a `<Form>`, `TagAutocomplete` inherits `isDisabled`,
+`isReadOnly`, `labelPlacement`, and `labelAlign` from the form context.
+
+<Story of={Stories.InsideForm} />
+
+## Accessibility
+
+- The text input uses `role="combobox"` with `aria-autocomplete="list"`.
+- When the popover is open, the input points to the listbox via
+  `aria-controls` and tracks the focused option with `aria-activedescendant`.
+- DOM focus stays on the input while arrow keys move virtual focus through
+  suggestions.
+- Selected tags keep the same grid semantics as `TagInput`.
+
+## Keyboard
+
+Inside the text input:
+
+| Key                  | Behavior                                                                         |
+| -------------------- | -------------------------------------------------------------------------------- |
+| <kbd>ArrowDown</kbd> | Open suggestions and move virtual focus to the first option.                     |
+| <kbd>ArrowUp</kbd>   | Open suggestions and move virtual focus to the last option.                      |
+| <kbd>Enter</kbd>     | Select the focused suggestion, or commit the current input value as a new tag.   |
+| <kbd>Escape</kbd>    | Close the suggestion popover.                                                    |
+| <kbd>Backspace</kbd> | If the input is empty and there are tags, focus the last tag.                    |
+| _split character_    | Commit and reset the input — same effect as <kbd>Enter</kbd> for free-form text. |
+| <kbd>Tab</kbd>       | Move focus to the cleaner button (if visible) or out of the field.               |

packages/components/src/components/TagAutocomplete/TagAutocomplete.module.css

@@ -0,0 +1,18 @@
+.popover {
+  border-radius: var(--kbq-size-s);
+}
+
+.container {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 0;
+}
+
+.list {
+  overflow-y: auto;
+  max-block-size: inherit;
+}
+
+.list:empty {
+  display: none;
+}