panelui-native 0.53.0 → 0.54.0

package/README.md

@@ -1,7 +1,7 @@
 # PanelUI — React Native UI components for Expo, styled with Tailwind CSS
 
 **PanelUI** (`panelui-native`) is an accessible, high-performance React Native component
-library for Expo apps. 94 typed components — buttons, bottom sheets, dialogs, selects,
+library for Expo apps. 96 typed components — buttons, bottom sheets, dialogs, selects,
 toasts, forms — styled with Tailwind CSS v4 and animated on the UI thread with Reanimated.
 Zero native code, so it runs in Expo Go.
 
@@ -177,6 +177,7 @@ you are done. Unstyled text on a white screen means the styles are not reaching
 | `Button` | Pressable action with variants, sizes, loading state and icon slots |
 | `ButtonGroup` | Several buttons drawn as one control |
 | `Calendar` | A month of days, for picking one, several, or a range |
+| `CandlestickChart` | Open, high, low and close for a period, drawn as one mark |
 | `Card` | Content surface with header, body and footer |
 | `Carousel` | A run of slides, one at a time, dragged with a finger |
 | `Checkbox` | Animated checkbox, as a row or a selectable card |
@@ -248,6 +249,7 @@ you are done. Unstyled text on a white screen means the styles are not reaching
 | `Switch` | Animated on/off toggle |
 | `Table` | Rows and columns that stay lined up, with sortable headers |
 | `Tabs` | Segmented navigation with an animated indicator |
+| `TagInput` | A field whose value is a list of tokens rather than a string |
 | `Task` | A step an agent is working through, with its files |
 | `TextAnimation` | Five ways a piece of text or a number arrives |
 | `Textarea` | Multi-line text field that can grow with its content |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panelui-native",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "High-performance React Native UI components for Expo. Semantic design tokens, powered by Uniwind (Tailwind v4) and Reanimated.",
   "main": "./lib/module/index.js",
   "module": "./lib/module/index.js",

package/src/components/combobox/index.tsx

@@ -489,6 +489,15 @@ function ComboboxRoot<Mode extends ComboboxMode = 'single'>({
   const [internalQuery, setInternalQuery] = useState(defaultInputValue);
   const query = inputValue !== undefined ? inputValue : internalQuery;
 
+  /*
+   * Which chip a second backspace would take, in `multiple` mode. A held
+   * backspace repeats, and a field that removed on the first one would empty
+   * itself in the time it takes to notice — the mark is the beat that lets you
+   * stop. It is an index rather than a value because the same label can appear
+   * twice once the caller allows a custom value that matches an option.
+   */
+  const [marked, setMarked] = useState<number | null>(null);
+
   /** The selection as a list, which is the shape everything downstream wants. */
   const values = useMemo(() => {
     if (selection == null) return [];
@@ -742,12 +751,38 @@ function ComboboxRoot<Mode extends ComboboxMode = 'single'>({
     [selection, commit]
   );
 
+  /**
+   * Removal by position, which is what the backspace mark holds. Removing by
+   * value would take both of a repeated label rather than the marked one.
+   */
+  const removeAt = useCallback(
+    (index: number) => {
+      const current = Array.isArray(selection) ? selection : [];
+      if (index < 0 || index >= current.length) return;
+      commit(
+        current.filter((_, position) => position !== index) as ComboboxSelection[Mode]
+      );
+    },
+    [selection, commit]
+  );
+
   const clear = useCallback(() => {
     setQuery('');
+    setMarked(null);
     commit((multiple ? [] : undefined) as ComboboxSelection[Mode]);
     inputRef.current?.focus();
   }, [setQuery, commit, multiple]);
 
+  /*
+   * The chips can also change from outside — a form reset, a pick undone in the
+   * list — which would leave the mark pointing past the end of them. A stale
+   * mark is a chip deleted by a backspace meant for the one that used to be
+   * there.
+   */
+  useEffect(() => {
+    if (marked !== null && marked >= values.length) setMarked(null);
+  }, [marked, values.length]);
+
   const context = useMemo<ComboboxContextValue>(
     () => ({ values, onSelect: (next) => select(next) }),
     [values, select]
@@ -847,10 +882,14 @@ function ComboboxRoot<Mode extends ComboboxMode = 'single'>({
     >
       <View className={slots.fieldContent()}>
         {multiple
-          ? values.map((entry) => (
+          ? values.map((entry, index) => (
               <Chip
                 key={entry}
                 size="sm"
+                // The marked chip turns destructive rather than growing an
+                // outline: it is about to be deleted, and that is the one
+                // colour in the theme that already means exactly that.
+                variant={marked === index ? 'destructive' : 'default'}
                 // A chip is `self-start` by default, which overrides the row's
                 // `items-center` and leaves it riding high against the input.
                 // Inside a field it is one of several things sharing a line.
@@ -867,6 +906,9 @@ function ComboboxRoot<Mode extends ComboboxMode = 'single'>({
           className={slots.input()}
           value={query}
           onChangeText={(next) => {
+            // Typing takes the mark off: the backspace that would have removed
+            // a chip has been overtaken by a new query.
+            setMarked(null);
             setQuery(next);
             if (!open) openList();
           }}
@@ -874,20 +916,31 @@ function ComboboxRoot<Mode extends ComboboxMode = 'single'>({
             setFocused(true);
             if (openOnFocus) openList();
           }}
-          onBlur={() => setFocused(false)}
+          onBlur={() => {
+            setFocused(false);
+            setMarked(null);
+          }}
           onSubmitEditing={submit}
           onKeyPress={({ nativeEvent }) => {
-            // Backspace on an empty field takes the last chip back — the same
-            // reflex that deletes a character, extended to the thing in front
-            // of the cursor when there is no character left to delete.
-            if (
-              multiple &&
-              nativeEvent.key === 'Backspace' &&
-              query.length === 0 &&
-              values.length > 0
-            ) {
-              remove(values[values.length - 1]!);
+            if (!multiple) return;
+            if (nativeEvent.key !== 'Backspace') {
+              setMarked(null);
+              return;
+            }
+            // There is still a character in front of the cursor: backspace
+            // means what it always means, and the chips are none of its
+            // business.
+            if (query.length > 0 || values.length === 0) return;
+
+            // Backspace on an empty field reaches the thing in front of the
+            // cursor when there is no character left to delete — but it marks
+            // that chip first, and only the next one takes it.
+            if (marked !== null && marked < values.length) {
+              removeAt(marked);
+              setMarked(null);
+              return;
             }
+            setMarked(values.length - 1);
           }}
           editable={!disabled}
           // Android lays a single-line input's text against the top of its box

package/src/components/sortable/index.tsx

@@ -583,18 +583,32 @@ function SortableRoot({
 
   const indexOf = useCallback((id: string) => indices.get(id) ?? -1, [indices]);
 
+  /*
+   * Both maps are accumulated in a ref and then published, rather than built by
+   * reading the shared value back and spreading it. Every row reports its
+   * layout in the same batch on mount, and a write to `.value` is not visible
+   * to the next read in that batch — so a read-modify-write there has all the
+   * rows spreading the same empty map and only the last one surviving. A list
+   * that knows one row's height puts every slot a gap apart, and the first
+   * drag drops the row at the end of the list.
+   */
+  const measuredHeights = useRef<Record<string, number>>({});
+  const pinnedFlags = useRef<Record<string, boolean>>({});
+
   const measured = useCallback(
     (id: string, height: number) => {
-      if (heights.value[id] === height) return;
-      heights.value = { ...heights.value, [id]: height };
+      if (measuredHeights.current[id] === height) return;
+      measuredHeights.current = { ...measuredHeights.current, [id]: height };
+      heights.value = measuredHeights.current;
     },
     [heights]
   );
 
   const setPinned = useCallback(
     (id: string, next: boolean) => {
-      if (Boolean(pinned.value[id]) === next) return;
-      pinned.value = { ...pinned.value, [id]: next };
+      if (Boolean(pinnedFlags.current[id]) === next) return;
+      pinnedFlags.current = { ...pinnedFlags.current, [id]: next };
+      pinned.value = pinnedFlags.current;
     },
     [pinned]
   );
@@ -1031,10 +1045,15 @@ function SortableItem({
          * drop unreported; `seq` is what tells the two cases apart, because
          * the only interruption that should be ignored is the row being picked
          * up again.
+         *
+         * `activeId` is checked as well as `seq` because reporting the drop is
+         * itself what interrupts the spring: the caller applies the reorder,
+         * and the reset that follows puts `translate` back to rest, which ends
+         * the animation and calls this a second time under the same `seq`.
          */
         const land = () => {
           'worklet';
-          if (dragSeq.value !== seq) return;
+          if (dragSeq.value !== seq || activeId.value === null) return;
           activeId.value = null;
           runOnJS(notifySettled)(id);
         };
@@ -1142,17 +1161,27 @@ function SortableItem({
    * no way to discover it from the row. Moving by whole slots is published as
    * an accessibility action instead, which is the only path to reordering for
    * someone who is not dragging anything.
+   *
+   * The actions sit wherever the drag does. A handle list keeps them on the
+   * grip, which is an element in its own right; put here they would never be
+   * offered, because the actions of a view that is not itself an accessibility
+   * element are not reachable, and a row full of text is not one. A long-press
+   * list has no grip and gives the whole row to the drag, so the row becomes
+   * the element — which is what a screen reader wants from a row in any case.
    */
-  const a11y = locked
-    ? undefined
-    : [
+  const carriesActions = activation === 'longPress' && !locked;
+
+  const a11y = carriesActions
+    ? [
         { name: 'moveUp', label: 'Move up' },
         { name: 'moveDown', label: 'Move down' },
-      ];
+      ]
+    : undefined;
 
   const row = (
     <Animated.View
       onLayout={onLayout}
+      accessible={carriesActions}
       accessibilityActions={a11y}
       onAccessibilityAction={(event) => {
         if (event.nativeEvent.actionName === 'moveUp') step(id, -1);
@@ -1224,7 +1253,7 @@ function SortableHandle({
   accessibilityLabel = 'Drag to reorder',
   ...props
 }: SortableHandleProps) {
-  const { activation, disabled: rootDisabled } = useSortableRoot('Sortable.Handle');
+  const { activation, disabled: rootDisabled, step } = useSortableRoot('Sortable.Handle');
   const item = useContext(SortableItemContext);
 
   /*
@@ -1235,17 +1264,44 @@ function SortableHandle({
   const muted = useCSSVariable('--color-muted-foreground');
   const tint = typeof muted === 'string' ? muted : undefined;
 
+  const locked = rootDisabled || item?.disabled;
+
+  /*
+   * `adjustable` promises an element that answers a swipe up or down, and the
+   * promise was never kept: the grip published the role and nothing else, so
+   * the one part of a row a screen reader could reach did nothing at all.
+   * Moving by whole slots is what it was always meant to do. The same move is
+   * offered as a named action too, because a swipe says nothing about which
+   * way the row is going to travel.
+   */
+  const move = (delta: number) => {
+    if (locked || !item) return;
+    step(item.id, delta);
+  };
+
   const glyph = (
     <View
       accessible
       accessibilityRole="adjustable"
       accessibilityLabel={accessibilityLabel}
-      accessibilityState={{ disabled: rootDisabled || item?.disabled }}
-      className={cn(
-        'items-center justify-center px-2 py-1.5',
-        (rootDisabled || item?.disabled) && 'opacity-40',
-        className
-      )}
+      accessibilityState={{ disabled: locked }}
+      accessibilityValue={item ? { text: `Position ${item.index + 1}` } : undefined}
+      accessibilityActions={
+        locked
+          ? undefined
+          : [
+              { name: 'increment' },
+              { name: 'decrement' },
+              { name: 'moveUp', label: 'Move up' },
+              { name: 'moveDown', label: 'Move down' },
+            ]
+      }
+      onAccessibilityAction={(event) => {
+        const action = event.nativeEvent.actionName;
+        if (action === 'increment' || action === 'moveUp') move(-1);
+        if (action === 'decrement' || action === 'moveDown') move(1);
+      }}
+      className={cn('items-center justify-center px-2 py-1.5', locked && 'opacity-40', className)}
       {...props}
     >
       <IconColorProvider color={tint}>

package/src/components/tag-input/index.tsx

@@ -0,0 +1,619 @@
+/**
+ * TagInput — a field whose value is a list of tokens rather than a string.
+ *
+ * The value is whatever gets typed. That is the whole distinction from a
+ * `Combobox` in `multiple` mode: a Combobox picks from a set of options you
+ * supply, so it needs a list, a filter and a surface to float that list on. A
+ * tag field has no options and no list — labels on a task, recipients on a
+ * message, keywords on a post — so it carries none of that machinery and never
+ * opens a portal.
+ *
+ * ```tsx
+ * <TagInput
+ *   label="Topics"
+ *   defaultValue={['expo', 'reanimated']}
+ *   placeholder="Add a topic"
+ * />
+ * ```
+ *
+ * ## Three ways a tag gets committed
+ *
+ * Return commits what has been typed. So does any of `delimiters` — a comma by
+ * default — which is what makes pasting `design, research, ops` land as three
+ * tags instead of one long one. And `blurBehavior` decides what a field that
+ * loses focus mid-word does with the leftover.
+ *
+ * ## Backspace asks first
+ *
+ * Backspace on an empty field marks the last tag rather than taking it: the
+ * tag turns destructive, and a second backspace removes it. A held backspace
+ * repeats, and a field that deleted on the first one would empty itself in the
+ * time it takes to notice — the mark is the beat that lets you stop.
+ */
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  Pressable,
+  TextInput,
+  View,
+  type NativeSyntheticEvent,
+  type TextInputKeyPressEventData,
+  type TextInputProps,
+} from 'react-native';
+import Animated, {
+  FadeIn,
+  FadeOut,
+  LinearTransition,
+  interpolateColor,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { XIcon } from '../../icons';
+import { Text } from '../../primitives/text';
+import { selectionTick } from '../../utils/haptics';
+import { Chip, type ChipSize, type ChipVariant } from '../chip';
+import { Label } from '../label';
+
+/** Matches Input and Combobox, so the three read as the same control focused. */
+const FOCUS_DURATION = 150;
+/** Long enough to see a tag arrive or leave, short enough not to queue up. */
+const ENTER_DURATION = 140;
+const EXIT_DURATION = 120;
+const REFLOW_DURATION = 180;
+
+const tagInputVariants = tv({
+  slots: {
+    container: 'w-full gap-1.5',
+    /*
+     * The border colour is animated between the resting and focused tokens, so
+     * it is deliberately absent from the class. `flex-wrap` is the load-bearing
+     * part: a tag field grows down, because the alternative is a row that
+     * scrolls sideways and hides the tags you just added.
+     */
+    field: 'w-full flex-row flex-wrap items-center rounded-lg border',
+    /*
+     * A length rather than a `text-*` step, for the reason Input gives: a step
+     * sets a size and a line height together, and the extra leading lands above
+     * the glyphs, so in a box of fixed height the text sits below the tags it
+     * is supposed to be level with.
+     */
+    input: 'min-w-24 flex-1 py-0 font-normal text-foreground',
+    clear: 'items-center justify-center rounded-full',
+    description: 'text-sm text-muted-foreground',
+    error: 'text-sm text-destructive',
+    count: 'text-xs text-muted-foreground',
+  },
+  variants: {
+    variant: {
+      outline: { field: 'bg-background' },
+      filled: { field: 'bg-muted' },
+    },
+    size: {
+      sm: {
+        field: 'gap-1 px-2.5 py-1.5',
+        input: 'h-7 text-[14px]',
+        clear: 'h-5 w-5',
+      },
+      md: {
+        field: 'gap-1.5 px-3 py-2',
+        input: 'h-8 text-[16px]',
+        clear: 'h-6 w-6',
+      },
+      lg: {
+        field: 'gap-2 px-3.5 py-2.5',
+        input: 'h-10 text-[16px]',
+        clear: 'h-7 w-7',
+      },
+    },
+    disabled: {
+      true: { field: 'opacity-[0.64]' },
+    },
+  },
+  defaultVariants: {
+    variant: 'outline',
+    size: 'md',
+  },
+});
+
+type TagInputVariantProps = VariantProps<typeof tagInputVariants>;
+export type TagInputVariant = NonNullable<TagInputVariantProps['variant']>;
+export type TagInputSize = NonNullable<TagInputVariantProps['size']>;
+
+/** A tag sits inside the field, so it is a step smaller than the field is. */
+const CHIP_SIZE: Record<TagInputSize, ChipSize> = {
+  sm: 'sm',
+  md: 'sm',
+  lg: 'md',
+};
+
+/** Why a tag was turned away, for a caller that wants to say so. */
+export type TagRejection = 'duplicate' | 'max' | 'invalid';
+
+/** What a field that loses focus mid-word does with the leftover text. */
+export type TagBlurBehavior = 'add' | 'clear' | 'keep';
+
+/**
+ * Splitting without a regex, so a delimiter never has to be escaped — `.` and
+ * `|` are ordinary characters to someone listing the separators they use.
+ */
+function splitOn(text: string, delimiters: string[]): string[] {
+  let parts = [text];
+  for (const delimiter of delimiters) {
+    if (!delimiter) continue;
+    parts = parts.flatMap((part) => part.split(delimiter));
+  }
+  return parts;
+}
+
+export interface TagInputProps
+  extends Omit<
+      TextInputProps,
+      | 'value'
+      | 'defaultValue'
+      | 'onChangeText'
+      | 'editable'
+      | 'multiline'
+      | 'children'
+    >,
+    Omit<TagInputVariantProps, 'disabled'> {
+  /** Classes for the field box — the bordered container the tags sit in. */
+  className?: string;
+  /** Classes for the outer column that also holds the label and the error. */
+  containerClassName?: string;
+  /** The tags, controlled. Pair it with `onValueChange`. */
+  value?: string[];
+  /** The tags to start with, when the field keeps its own value. */
+  defaultValue?: string[];
+  /** Called with the whole list whenever a tag is added or removed. */
+  onValueChange?: (tags: string[]) => void;
+  /**
+   * The text being typed, controlled. Only needed to drive the draft from
+   * outside — the tags themselves are `value`.
+   */
+  inputValue?: string;
+  /** Called as the draft text changes, before it becomes a tag. */
+  onInputValueChange?: (text: string) => void;
+  /** The label above the field, and what the input is announced as. */
+  label?: string;
+  /** A line under the field, replaced by `errorMessage` when there is one. */
+  description?: string;
+  /** Error message. When set, the field renders in its invalid state. */
+  errorMessage?: string;
+  /** Marks the field required — an asterisk on the label, and the a11y state. */
+  isRequired?: boolean;
+  /** Dims the field and stops it being reached at all. */
+  disabled?: boolean;
+  /** Shows the tags but takes away the input and the ✕ on each one. */
+  readOnly?: boolean;
+  /**
+   * The most tags the field accepts. Past it nothing more is committed and
+   * `onReject` is called with `'max'`, unless `allowOverflow` is set.
+   */
+  max?: number;
+  /**
+   * Let the list go past `max` anyway. The field reports itself invalid while
+   * it is over, which is the point: some forms want the count shown as wrong
+   * rather than the typing refused.
+   */
+  allowOverflow?: boolean;
+  /** Accept a tag the list already holds. Off by default. */
+  allowDuplicates?: boolean;
+  /**
+   * Characters that end a tag as they are typed. A comma by default, which is
+   * what makes a pasted `a, b, c` land as three tags rather than one.
+   */
+  delimiters?: string[];
+  /**
+   * What happens to text still in the field when it loses focus. `add` commits
+   * it and clears it if it was accepted, leaving it in place if it was not, so
+   * a rejected word is still there to fix. `clear` drops it. `keep` leaves it
+   * exactly as typed.
+   */
+  blurBehavior?: TagBlurBehavior;
+  /**
+   * Decide whether a tag may be added, given the list it would join. Return
+   * `false` to turn it away — `onReject` is then called with `'invalid'`.
+   */
+  validate?: (tag: string, tags: string[]) => boolean;
+  /** Called when a tag was turned away, with the reason it was. */
+  onReject?: (tag: string, reason: TagRejection) => void;
+  /** Which Chip variant the tags are drawn as. */
+  chipVariant?: ChipVariant;
+  /** Draw the tag yourself — an avatar before the label, a count after it. */
+  renderTag?: (tag: string, index: number) => ReactNode;
+  /** A ✕ at the end of the field that empties it. */
+  clearable?: boolean;
+  /** Shows `3 / 8` under the field. Needs `max`. */
+  showCount?: boolean;
+  /**
+   * A tick under the finger as a tag lands or leaves. Off by default — needs
+   * the optional `expo-haptics`, and is silent without it.
+   */
+  haptics?: boolean;
+}
+
+export const TagInput = forwardRef<TextInput, TagInputProps>(
+  (
+    {
+      className,
+      containerClassName,
+      value,
+      defaultValue,
+      onValueChange,
+      inputValue,
+      onInputValueChange,
+      label,
+      description,
+      errorMessage,
+      isRequired,
+      disabled = false,
+      readOnly = false,
+      max,
+      allowOverflow = false,
+      allowDuplicates = false,
+      delimiters = [','],
+      blurBehavior = 'add',
+      validate,
+      onReject,
+      chipVariant = 'default',
+      renderTag,
+      clearable = false,
+      showCount = false,
+      haptics = false,
+      variant,
+      size = 'md',
+      placeholder,
+      onFocus,
+      onBlur,
+      onKeyPress,
+      onSubmitEditing,
+      accessibilityLabel,
+      ...props
+    },
+    ref
+  ) => {
+    const inputRef = useRef<TextInput>(null);
+    useImperativeHandle(ref, () => inputRef.current as TextInput);
+
+    const [ownTags, setOwnTags] = useState<string[]>(defaultValue ?? []);
+    const tags = value ?? ownTags;
+
+    const [ownText, setOwnText] = useState('');
+    const text = inputValue ?? ownText;
+
+    const [focused, setFocused] = useState(false);
+    /*
+     * Which tag a second backspace would take. An index rather than the tag
+     * itself, because with `allowDuplicates` two tags can read the same and
+     * marking "the last one" has to mean the last one.
+     */
+    const [marked, setMarked] = useState<number | null>(null);
+
+    const overflowing = max !== undefined && tags.length > max;
+    const invalid = !!errorMessage || overflowing;
+    const interactive = !disabled && !readOnly;
+
+    // The list can be emptied from outside, which would leave the mark pointing
+    // past the end of it — and a stale mark is a tag deleted by a backspace
+    // meant for the one that used to be there.
+    useEffect(() => {
+      if (marked !== null && marked >= tags.length) setMarked(null);
+    }, [marked, tags.length]);
+
+    const setText = useCallback(
+      (next: string) => {
+        if (inputValue === undefined) setOwnText(next);
+        onInputValueChange?.(next);
+      },
+      [inputValue, onInputValueChange]
+    );
+
+    const commit = useCallback(
+      (next: string[]) => {
+        if (value === undefined) setOwnTags(next);
+        onValueChange?.(next);
+      },
+      [value, onValueChange]
+    );
+
+    /**
+     * Adds every candidate that survives the rules, in order, and reports the
+     * ones that do not. Returns whether anything was actually taken, which is
+     * what tells the caller whether the draft text has been consumed.
+     */
+    const addTags = useCallback(
+      (candidates: string[]) => {
+        const incoming = candidates
+          .map((entry) => entry.trim())
+          .filter((entry) => entry.length > 0);
+        if (incoming.length === 0) return false;
+
+        const next = [...tags];
+        let added = false;
+
+        for (const tag of incoming) {
+          if (!allowDuplicates && next.includes(tag)) {
+            onReject?.(tag, 'duplicate');
+            continue;
+          }
+          if (max !== undefined && next.length >= max && !allowOverflow) {
+            onReject?.(tag, 'max');
+            continue;
+          }
+          if (validate && !validate(tag, next)) {
+            onReject?.(tag, 'invalid');
+            continue;
+          }
+          next.push(tag);
+          added = true;
+        }
+
+        if (!added) return false;
+        if (haptics) selectionTick();
+        commit(next);
+        return true;
+      },
+      [tags, allowDuplicates, max, allowOverflow, validate, onReject, haptics, commit]
+    );
+
+    const removeAt = useCallback(
+      (index: number) => {
+        if (index < 0 || index >= tags.length) return;
+        if (haptics) selectionTick();
+        commit(tags.filter((_, position) => position !== index));
+      },
+      [tags, haptics, commit]
+    );
+
+    const handleChangeText = useCallback(
+      (next: string) => {
+        // Any typing at all takes the mark off: the backspace that would have
+        // removed a tag has been overtaken by a new word.
+        setMarked(null);
+
+        if (delimiters.length > 0 && delimiters.some((entry) => next.includes(entry))) {
+          const parts = splitOn(next, delimiters);
+          // The last piece is what comes *after* the final delimiter — still
+          // being typed, so it stays in the field rather than becoming a tag.
+          const trailing = parts.pop() ?? '';
+          addTags(parts);
+          setText(trailing);
+          return;
+        }
+
+        setText(next);
+      },
+      [delimiters, addTags, setText]
+    );
+
+    const handleSubmit = useCallback<
+      NonNullable<TextInputProps['onSubmitEditing']>
+    >(
+      (event) => {
+        if (addTags([text])) setText('');
+        onSubmitEditing?.(event);
+      },
+      [addTags, text, setText, onSubmitEditing]
+    );
+
+    const handleKeyPress = useCallback(
+      (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+        onKeyPress?.(event);
+        if (event.nativeEvent.key !== 'Backspace') {
+          setMarked(null);
+          return;
+        }
+        // There is still a character in front of the cursor: backspace means
+        // what it always means, and the tags are none of its business.
+        if (text.length > 0 || tags.length === 0) return;
+
+        if (marked !== null && marked < tags.length) {
+          removeAt(marked);
+          setMarked(null);
+          return;
+        }
+        setMarked(tags.length - 1);
+      },
+      [onKeyPress, text.length, tags.length, marked, removeAt]
+    );
+
+    const handleFocus = useCallback<NonNullable<TextInputProps['onFocus']>>(
+      (event) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus]
+    );
+
+    const handleBlur = useCallback<NonNullable<TextInputProps['onBlur']>>(
+      (event) => {
+        setFocused(false);
+        setMarked(null);
+
+        if (blurBehavior === 'clear') {
+          setText('');
+        } else if (blurBehavior === 'add') {
+          // Only cleared when it was taken. Text that was refused stays in the
+          // field, because a word that vanishes on blur looks like it was
+          // accepted and a rejected tag has to remain visible to be fixed.
+          if (addTags([text])) setText('');
+        }
+
+        onBlur?.(event);
+      },
+      [blurBehavior, setText, addTags, text, onBlur]
+    );
+
+    const focusField = useCallback(() => {
+      inputRef.current?.focus();
+    }, []);
+
+    const clear = useCallback(() => {
+      setText('');
+      setMarked(null);
+      commit([]);
+      inputRef.current?.focus();
+    }, [setText, commit]);
+
+    const slots = tagInputVariants({ variant, size, disabled });
+
+    const placeholderColor = useCSSVariable('--color-muted-foreground');
+    const restColor = useCSSVariable('--color-input');
+    const focusColor = useCSSVariable('--color-ring');
+    const errorColor = useCSSVariable('--color-destructive');
+    const mutedColor =
+      typeof placeholderColor === 'string' ? placeholderColor : '#737373';
+
+    /*
+     * One 0..1 value rather than a class per state: Uniwind can only swap a
+     * class wholesale, which is the snap this is here to avoid, and a shared
+     * value crosses between the two colours on the UI thread without a
+     * re-render for every frame of it.
+     */
+    const focus = useSharedValue(0);
+    useEffect(() => {
+      focus.value = withTiming(focused ? 1 : 0, { duration: FOCUS_DURATION });
+    }, [focused, focus]);
+
+    const resting = typeof restColor === 'string' ? restColor : '#e5e5e5';
+    const active = invalid
+      ? typeof errorColor === 'string'
+        ? errorColor
+        : '#ef4444'
+      : typeof focusColor === 'string'
+        ? focusColor
+        : '#a3a3a3';
+    // An invalid field is tinted at rest too — the error is a fact about the
+    // value, not about whether the field happens to be focused.
+    const idle = invalid ? active : resting;
+
+    const borderStyle = useAnimatedStyle(() => ({
+      borderColor: interpolateColor(focus.value, [0, 1], [idle, active]),
+    }));
+
+    const hasContent = tags.length > 0 || text.length > 0;
+    const fieldLabel = accessibilityLabel ?? label ?? placeholder;
+
+    const countLine = useMemo(() => {
+      if (!showCount || max === undefined) return null;
+      return `${tags.length} / ${max}`;
+    }, [showCount, max, tags.length]);
+
+    return (
+      <View className={slots.container({ className: containerClassName })}>
+        {label ? (
+          <Label isRequired={isRequired} isInvalid={invalid} isDisabled={disabled}>
+            {label}
+          </Label>
+        ) : null}
+
+        <Pressable
+          onPress={focusField}
+          disabled={!interactive}
+          // The box is a way to reach the input, not a control of its own — the
+          // input below it already carries the label and the state.
+          accessible={false}
+        >
+          <Animated.View style={borderStyle} className={slots.field({ className })}>
+            {tags.map((tag, index) => (
+              <Animated.View
+                key={`${tag}-${index}`}
+                entering={FadeIn.duration(ENTER_DURATION)}
+                exiting={FadeOut.duration(EXIT_DURATION)}
+                layout={LinearTransition.duration(REFLOW_DURATION)}
+              >
+                {renderTag ? (
+                  renderTag(tag, index)
+                ) : (
+                  <Chip
+                    size={CHIP_SIZE[size]}
+                    // The marked tag turns destructive rather than growing an
+                    // outline: it is about to be deleted, and that is the one
+                    // colour in the theme that already means exactly that.
+                    variant={marked === index ? 'destructive' : chipVariant}
+                    onClose={interactive ? () => removeAt(index) : undefined}
+                    closeLabel={`Remove ${tag}`}
+                    haptics={haptics}
+                  >
+                    {tag}
+                  </Chip>
+                )}
+              </Animated.View>
+            ))}
+
+            {readOnly ? null : (
+              <TextInput
+                ref={inputRef}
+                value={text}
+                onChangeText={handleChangeText}
+                onFocus={handleFocus}
+                onBlur={handleBlur}
+                onKeyPress={handleKeyPress}
+                onSubmitEditing={handleSubmit}
+                editable={!disabled}
+                // Return commits a tag and the field stays open for the next
+                // one — dismissing the keyboard after every tag would make
+                // adding three of them three separate visits to the field.
+                submitBehavior="submit"
+                returnKeyType="done"
+                // Android lays a single-line input's text against the top of
+                // its box unless told otherwise; iOS centres it. Without this
+                // the text sits above the tags on one platform and level with
+                // them on the other.
+                textAlignVertical="center"
+                placeholder={tags.length > 0 ? undefined : placeholder}
+                placeholderTextColor={mutedColor}
+                autoCapitalize="none"
+                autoCorrect={false}
+                autoComplete="off"
+                accessibilityLabel={fieldLabel}
+                accessibilityState={{ disabled }}
+                aria-required={isRequired}
+                aria-invalid={invalid}
+                className={slots.input()}
+                {...props}
+              />
+            )}
+
+            {clearable && hasContent && interactive ? (
+              <Pressable
+                accessibilityRole="button"
+                accessibilityLabel="Clear all tags"
+                hitSlop={8}
+                onPress={clear}
+                className={slots.clear()}
+              >
+                <XIcon size={16} color={mutedColor} />
+              </Pressable>
+            ) : null}
+          </Animated.View>
+        </Pressable>
+
+        {errorMessage ? (
+          <Text className={slots.error()}>{errorMessage}</Text>
+        ) : description ? (
+          <Text className={slots.description()}>{description}</Text>
+        ) : null}
+
+        {countLine ? (
+          <Text className={slots.count({ className: overflowing ? 'text-destructive' : undefined })}>
+            {countLine}
+          </Text>
+        ) : null}
+      </View>
+    );
+  }
+);
+
+TagInput.displayName = 'TagInput';

package/src/index.ts

@@ -514,6 +514,14 @@ export {
   type PieDatum,
 } from './components/pie-chart';
 export { Textarea, type TextareaProps } from './components/textarea';
+export {
+  TagInput,
+  type TagInputProps,
+  type TagInputVariant,
+  type TagInputSize,
+  type TagBlurBehavior,
+  type TagRejection,
+} from './components/tag-input';
 export {
   Item,
   type ItemProps,