@xsolla/xui-tag 0.222.0 → 0.224.0

package/README.md

@@ -1,6 +1,6 @@
 # Tag
 
-A cross-platform React tag component for displaying labels, categories, and removable chips. Supports multiple tones, solid/outlined types, and optional left/right icons.
+A cross-platform React tag component for displaying labels, categories, and removable chips. Supports multiple tones, solid/outlined types, and optional left/right icons. The package also ships `TagInput`, a text field that turns typed values into removable chips.
 <!-- BEGIN:xui-mcp-instructions:tag -->
 A compact label chip used to categorise, classify, or annotate content. Renders as a pill-shaped container with a text label and optional leading and trailing icons. Supports two visual types (solid fill and outlined), seven semantic tones, and five sizes. Used in lists, cards, table cells, filters, and any context where a short categorical attribute needs to be visually marked.
 
@@ -36,7 +36,7 @@ A compact label chip used to categorise, classify, or annotate content. Renders
 - Do not rely on Tone (colour) alone to communicate meaning — the label text or icon must also be present (WCAG 1.4.1 Use of Colour). For icon-only tags, provide aria-label on the element.
 - Removable tags: the remove button (Icon right) must have aria-label=*"Remove [tag name]"* so screen readers can announce which tag is being removed. The button must be focusable and respond to Enter / Space.
 - When tags are inside a list, wrap them in a <ul> with <li> elements and an aria-label on the list describing the group — e.g. aria-label=*"Product tags"*.
-- Ensure sufficient colour contrast between the tag label text and the tag background in both Solid and Outlined variants, for all tones, meeting WCAG AA (4.5:1 for small text at XS/S sizes).
+- Ensure sufficient colour contrast between the tag label text and the tag background in both Solid and Outlined variants, for all tones, meeting WCAG AA (4.5:1 for small text at XS/S sizes).
 <!-- END:xui-mcp-instructions:tag -->
 
 ## Installation
@@ -208,7 +208,8 @@ import { Tag } from "@xsolla/xui-tag";
   type="solid" // Solid or outlined
   iconLeft={<Icon />} // Optional leading icon
   iconRight={<Icon />} // Optional trailing icon
-  onRemove={handleRemove} // Makes tag removable (renders X icon)
+  onRemove={handleRemove} // Makes tag removable (renders an X button)
+  removeLabel="Remove brand" // Optional accessible name for the X button
 >
   Tag Label
 </Tag>;
@@ -268,48 +269,33 @@ export default function StatusTags() {
 
 ### Tag Input
 
+Use `TagInput` to let users type free-form values that become removable chips inside the field. Chips wrap onto new lines as the list grows.
+
 ```tsx
 import * as React from "react";
-import { Tag } from "@xsolla/xui-tag";
-import { Input } from "@xsolla/xui-input";
+import { TagInput } from "@xsolla/xui-tag";
 
-export default function TagInput() {
-  const [tags, setTags] = React.useState(["react", "typescript"]);
-  const [inputValue, setInputValue] = React.useState("");
-
-  const addTag = () => {
-    if (inputValue.trim() && !tags.includes(inputValue.trim())) {
-      setTags([...tags, inputValue.trim()]);
-      setInputValue("");
-    }
-  };
+export default function ItemIdsField() {
+  const [ids, setIds] = React.useState<string[]>([]);
 
   return (
-    <div>
-      <div
-        style={{ display: "flex", gap: 8, flexWrap: "wrap", marginBottom: 8 }}
-      >
-        {tags.map((tag) => (
-          <Tag
-            key={tag}
-            tone="primary"
-            onRemove={() => setTags(tags.filter((t) => t !== tag))}
-          >
-            {tag}
-          </Tag>
-        ))}
-      </div>
-      <Input
-        value={inputValue}
-        onChangeText={setInputValue}
-        placeholder="Add a tag..."
-        onKeyDown={(e) => e.key === "Enter" && addTag()}
-      />
-    </div>
+    <TagInput
+      label="Epic Audience Item IDs"
+      value={ids}
+      onChange={setIds}
+      placeholder="Type an ID and press Enter"
+    />
   );
 }
 ```
 
+Behaviour:
+
+- **Enter** adds the typed text as a chip and does not submit the surrounding form. While an input method (IME) is composing, Enter confirms the composition instead.
+- **Leaving the field** adds the typed text too.
+- **Backspace** in an empty field removes the last chip.
+- Values are kept as typed — no trimming and no de-duplication. Empty input is ignored.
+
 ## API Reference
 
 ### Tag
@@ -318,16 +304,17 @@ A tag/chip component.
 
 **Tag Props:**
 
-| Prop      | Type                                                                                     | Default     | Description                                                                                                   |
-| :-------- | :--------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------ |
-| `testID`  | `string`                                                                                 | —           | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
-| children  | `ReactNode`                                                                              | -           | Tag content. Optional for icon-only tags.                                                                     |
-| size      | `"xl" \| "lg" \| "md" \| "sm" \| "xs"`                                                   | `"md"`      | Size of the tag.                                                                                              |
-| tone      | `"primary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral"` | `"primary"` | Color tone.                                                                                                   |
-| type      | `"solid" \| "outlined"`                                                                  | `"solid"`   | Visual type. Solid fills background; outlined uses a border with lighter background.                          |
-| iconLeft  | `ReactNode`                                                                              | -           | Leading icon.                                                                                                 |
-| iconRight | `ReactNode`                                                                              | -           | Trailing icon.                                                                                                |
-| onRemove  | `() => void`                                                                             | -           | Callback for remove button. Renders an X icon in the trailing position.                                       |
+| Prop        | Type                                                                                     | Default     | Description                                                                                                   |
+| :---------- | :--------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------ |
+| `testID`    | `string`                                                                                 | —           | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
+| children    | `ReactNode`                                                                              | -           | Tag content. Optional for icon-only tags.                                                                     |
+| size        | `"xl" \| "lg" \| "md" \| "sm" \| "xs"`                                                   | `"md"`      | Size of the tag.                                                                                              |
+| tone        | `"primary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral"` | `"primary"` | Color tone.                                                                                                   |
+| type        | `"solid" \| "outlined"`                                                                  | `"solid"`   | Visual type. Solid fills background; outlined uses a border with lighter background.                          |
+| iconLeft    | `ReactNode`                                                                              | -           | Leading icon.                                                                                                 |
+| iconRight   | `ReactNode`                                                                              | -           | Trailing icon.                                                                                                |
+| onRemove    | `() => void`                                                                             | -           | Callback for the remove button. Renders an X button in the trailing position.                                 |
+| removeLabel | `string`                                                                                 | -           | Accessible name of the remove button. Defaults to `"Remove {children}"` for text labels, otherwise `"Remove"`. |
 
 **Solid Tone Color Mapping:**
 
@@ -353,9 +340,32 @@ A tag/chip component.
 | alert      | Alert secondary      | Border alert      | Content alert primary      |
 | neutral    | Neutral secondary    | Border neutral    | Content neutral primary    |
 
+### TagInput
+
+A controlled text field that turns typed values into removable chips. The ref is forwarded to the text field.
+
+**TagInput Props:**
+
+| Prop           | Type                                   | Default | Description                                                                 |
+| :------------- | :------------------------------------- | :------ | :-------------------------------------------------------------------------- |
+| value          | `string[]`                             | —       | Current list of chip values. Required.                                      |
+| onChange       | `(value: string[]) => void`            | —       | Called with the next list when a chip is added or removed. Required.        |
+| placeholder    | `string`                               | -       | Placeholder shown while there are no chips.                                 |
+| size           | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"`  | Size of the field, matching `Input`. Chips are sized to fit inside it.      |
+| disabled       | `boolean`                              | `false` | Disables typing and hides the chip remove buttons.                          |
+| error          | `boolean`                              | -       | Highlights the field as invalid.                                            |
+| errorMessage   | `string`                               | -       | Error text below the field. Also highlights the field as invalid.           |
+| label          | `string`                               | -       | Visible label above the field.                                              |
+| `aria-label`   | `string`                               | -       | Accessible name for the text field when no `label` is set.                  |
+| id             | `string`                               | -       | Id of the text field. Generated when omitted.                               |
+| name           | `string`                               | -       | Name of the text field.                                                     |
+| onFocus        | `() => void`                           | -       | Called when the text field receives focus.                                  |
+| onBlur         | `() => void`                           | -       | Called when the text field loses focus, after any typed text is committed. |
+| `testID`       | `string`                               | -       | Test ID on the root element.                                                |
+
 ## Accessibility
 
-- Uses semantic elements for proper structure
-- Remove button includes accessible label
-- Keyboard accessible remove action
-- Focus indicator on interactive elements
+- The remove control is a native `<button type="button">`: it is reachable with Tab, activates on Enter / Space, and is announced as "Remove {label}" (override with `removeLabel`)
+- `TagInput` links its visible label via `aria-labelledby`, falls back to `aria-label`, and links `errorMessage` via `aria-describedby` with `aria-invalid`
+- `TagInput` chips use the same accessible remove button, labelled "Remove {value}"
+- Enter does not add a chip while an input method (IME) is composing

package/native/index.d.mts

@@ -14,12 +14,57 @@ interface TagProps extends ThemeOverrideProps {
     iconLeft?: ReactNode;
     /** Icon displayed on the right side of the label */
     iconRight?: ReactNode;
-    /** Callback when the remove (X) icon is clicked */
+    /** Callback when the remove (X) button is pressed */
     onRemove?: () => void;
+    /**
+     * Accessible name of the remove button. Defaults to "Remove {children}" when
+     * `children` is a string or number, otherwise "Remove".
+     */
+    removeLabel?: string;
     testID?: string;
     /** Extra styles merged onto the chip. Used for fills the tone tokens do not cover. */
     style?: React.CSSProperties;
 }
 declare const Tag: React.FC<TagProps>;
 
-export { Tag, type TagProps };
+type TagInputSize = "xl" | "lg" | "md" | "sm" | "xs";
+interface TagInputProps extends ThemeOverrideProps {
+    /** Current list of chip values (controlled). */
+    value: string[];
+    /** Called with the next list whenever a chip is added or removed. */
+    onChange: (value: string[]) => void;
+    /** Placeholder shown in the text field while no draft text is typed. */
+    placeholder?: string;
+    /** Size of the field. Chips are sized to fit inside it. */
+    size?: TagInputSize;
+    /** Disables typing and chip removal. */
+    disabled?: boolean;
+    /** Highlights the field as invalid. */
+    error?: boolean;
+    /** Error message rendered below the field. Also highlights the field as invalid. */
+    errorMessage?: string;
+    /** Visible label rendered above the field. */
+    label?: string;
+    /** Accessible label for the text field when no visible `label` is set. */
+    "aria-label"?: string;
+    /** Id of the text field. Generated when omitted. */
+    id?: string;
+    /** Name of the text field. */
+    name?: string;
+    /** Called when the text field receives focus. */
+    onFocus?: () => void;
+    /** Called when the text field loses focus (after any draft is committed). */
+    onBlur?: () => void;
+    testID?: string;
+}
+/**
+ * Text field that turns typed values into removable chips.
+ *
+ * - Enter adds the typed text as a chip and never submits the surrounding form.
+ * - Leaving the field adds the typed text too.
+ * - Backspace in an empty field removes the last chip.
+ * - Values are kept as typed: no trimming and no de-duplication.
+ */
+declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLInputElement>>;
+
+export { Tag, TagInput, type TagInputProps, type TagProps };

package/native/index.d.ts

@@ -14,12 +14,57 @@ interface TagProps extends ThemeOverrideProps {
     iconLeft?: ReactNode;
     /** Icon displayed on the right side of the label */
     iconRight?: ReactNode;
-    /** Callback when the remove (X) icon is clicked */
+    /** Callback when the remove (X) button is pressed */
     onRemove?: () => void;
+    /**
+     * Accessible name of the remove button. Defaults to "Remove {children}" when
+     * `children` is a string or number, otherwise "Remove".
+     */
+    removeLabel?: string;
     testID?: string;
     /** Extra styles merged onto the chip. Used for fills the tone tokens do not cover. */
     style?: React.CSSProperties;
 }
 declare const Tag: React.FC<TagProps>;
 
-export { Tag, type TagProps };
+type TagInputSize = "xl" | "lg" | "md" | "sm" | "xs";
+interface TagInputProps extends ThemeOverrideProps {
+    /** Current list of chip values (controlled). */
+    value: string[];
+    /** Called with the next list whenever a chip is added or removed. */
+    onChange: (value: string[]) => void;
+    /** Placeholder shown in the text field while no draft text is typed. */
+    placeholder?: string;
+    /** Size of the field. Chips are sized to fit inside it. */
+    size?: TagInputSize;
+    /** Disables typing and chip removal. */
+    disabled?: boolean;
+    /** Highlights the field as invalid. */
+    error?: boolean;
+    /** Error message rendered below the field. Also highlights the field as invalid. */
+    errorMessage?: string;
+    /** Visible label rendered above the field. */
+    label?: string;
+    /** Accessible label for the text field when no visible `label` is set. */
+    "aria-label"?: string;
+    /** Id of the text field. Generated when omitted. */
+    id?: string;
+    /** Name of the text field. */
+    name?: string;
+    /** Called when the text field receives focus. */
+    onFocus?: () => void;
+    /** Called when the text field loses focus (after any draft is committed). */
+    onBlur?: () => void;
+    testID?: string;
+}
+/**
+ * Text field that turns typed values into removable chips.
+ *
+ * - Enter adds the typed text as a chip and never submits the surrounding form.
+ * - Leaving the field adds the typed text too.
+ * - Backspace in an empty field removes the last chip.
+ * - Values are kept as typed: no trimming and no de-duplication.
+ */
+declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLInputElement>>;
+
+export { Tag, TagInput, type TagInputProps, type TagProps };