feat: create useTagGroup hook (#1665)

* migrate some utils to ts

* start useTagGroup

* docusaurus changes

* change some styles in docusaurus

* add focus

* focus, delete, add

* more updates on active and focus

* tests and some fixes

* improve styles

* improve types

* more tests

* ids

* move utils to ts

* fix build ts errors

* fix state change types in taggroup

* some more import fixes

* move test utils to __tests__

* add accessible description

* make coverage 100%

* change to listbox + tests

* cypress test

* fix rebase issue

* fix rebase issue

* improve types support

* improve environment type

* merge correctly legacy and generated types

* do not allow incorrect indeces

* remove rollup ts plugin

* fix rebase error

* export from ts file

* export useTagGroup type

* revert index

* add another docusaurus example

* change types export to modules again

* fix initial focus

* add onChange

* wip readme

* finish readme

* fix title

* fix example ts

* abstract focus into hook

* add migration guide

* readme typo and type move

* close menu on blur

Author: silviuaavram

cypress/e2e/useTagGroup.cy.js

@@ -0,0 +1,84 @@
+describe('useTagGroup', () => {
+  const colors = ['Black', 'Red', 'Green', 'Blue', 'Orange']
+
+  beforeEach(() => {
+    cy.visit('/useTagGroup')
+
+    // Ensure the listbox exists
+    cy.findByRole('listbox', {name: /colors example/i}).should('exist')
+
+    // Ensure it has 5 color tags
+    cy.findAllByRole('option').should('have.length', 5)
+  })
+
+  it('clicks a tag and navigates with circular arrow keys', () => {
+    // Click first tag ("Black")
+    cy.findByRole('option', {name: /Black/i}).click().should('have.focus')
+
+    // Arrow Right navigation through all tags
+    for (let index = 0; index < colors.length; index++) {
+      const nextIndex = (index + 1) % colors.length
+      cy.focused().trigger('keydown', {key: 'ArrowRight'})
+      cy.findByRole('option', {name: colors[nextIndex]}).should('have.focus')
+    }
+
+    // Arrow Left navigation through all tags (circular)
+    for (let index = colors.length - 1; index >= 0; index--) {
+      const prevIndex = (index + colors.length) % colors.length
+      cy.focused().trigger('keydown', {key: 'ArrowLeft'})
+      cy.findByRole('option', {name: colors[prevIndex]}).should('have.focus')
+    }
+
+    // Circular on the left.
+    cy.focused().trigger('keydown', {key: 'ArrowLeft'})
+    cy.findByRole('option', {name: colors[colors.length - 1]}).should(
+      'have.focus',
+    )
+  })
+
+  it('deletes a tag using Delete and Backspace', () => {
+    // Focus "Red"
+    cy.findByRole('option', {name: /Red/i}).click()
+
+    // Delete key
+    cy.focused().trigger('keydown', {key: 'Delete'})
+    cy.findAllByRole('option').should('have.length', 4)
+
+    // Next tag should be "Green"
+    cy.focused().should('contain.text', 'Green')
+
+    // Backspace key removes "Green"
+    cy.focused().trigger('keydown', {key: 'Backspace'})
+    cy.findAllByRole('option').should('have.length', 3)
+
+    // Focus should now be on "Blue"
+    cy.focused().should('contain.text', 'Blue')
+  })
+
+  it('removes a tag via remove button', () => {
+    // Remove "Blue" via its remove button
+    cy.findByRole('option', {name: /Blue/i}).within(() => {
+      cy.findByRole('button', {name: /remove/i}).click()
+    })
+
+    // Verify 4 tags remain
+    cy.findAllByRole('option').should('have.length', 4)
+
+    // Orange tag should have focus.
+    cy.findByRole('option', {name: /Orange/i}).should('have.focus')
+  })
+
+  it('adds a tag from the list', () => {
+    // Focus "Red"
+    cy.findByRole('option', {name: /Red/i}).click()
+
+    // Clicks the Lime option from the add tags list.
+    cy.findByRole('button', {name: /Lime/i}).click()
+
+    // Verify 6 tags are visible
+    cy.findAllByRole('option').should('have.length', 6)
+
+    cy.findByRole('option', {name: /Lime/i}).should('be.visible')
+    // Including the new option
+  })
+})

docusaurus.config.js

@@ -31,7 +31,7 @@ const config = {
         blog: false,
         pages: {
           path: 'docusaurus/pages',
-          include: ['**/*.{js,jsx}'],
+          include: ['**/*.{js,jsx,tsx}'],
         },
       }),
     ],

docusaurus/pages/index.js

@@ -20,6 +20,12 @@ export default function Docs() {
         <li>
           <a href="./combobox">Downshift</a>
         </li>
+        <li>
+          <a href="./useTagGroup">useTagGroup</a>
+        </li>
+        <li>
+          <a href="./useTagGroupCombobox">useTagGroupCombobox</a>
+        </li>
       </ul>
     </div>
   )

docusaurus/pages/useMultipleCombobox.js

@@ -5,8 +5,8 @@ import {
   colors,
   containerStyles,
   menuStyles,
-  selectedItemsContainerSyles,
-  selectedItemStyles,
+  tagGroupSyles,
+  tagStyles,
 } from '../utils'
 
 const initialSelectedItems = [colors[0], colors[1]]
@@ -105,14 +105,14 @@ export default function DropdownMultipleCombobox() {
       >
         Choose an element:
       </label>
-      <div style={selectedItemsContainerSyles}>
+      <div style={tagGroupSyles}>
         {selectedItems.map(function renderSelectedItem(
           selectedItemForRender,
           index,
         ) {
           return (
             <span
-              style={selectedItemStyles}
+              style={tagStyles}
               key={`selected-item-${index}`}
               {...getSelectedItemProps({
                 selectedItem: selectedItemForRender,

docusaurus/pages/useMultipleSelect.js

@@ -5,8 +5,8 @@ import {
   colors,
   containerStyles,
   menuStyles,
-  selectedItemsContainerSyles,
-  selectedItemStyles,
+  tagGroupSyles,
+  tagStyles,
 } from '../utils'
 
 const initialSelectedItems = [colors[0], colors[1]]
@@ -76,14 +76,14 @@ export default function DropdownMultipleSelect() {
       >
         Choose an element:
       </label>
-      <div style={selectedItemsContainerSyles}>
+      <div style={tagGroupSyles}>
         {selectedItems.map(function renderSelectedItem(
           selectedItemForRender,
           index,
         ) {
           return (
             <span
-              style={selectedItemStyles}
+              style={tagStyles}
               key={`selected-item-${index}`}
               {...getSelectedItemProps({
                 selectedItem: selectedItemForRender,

docusaurus/pages/useTagGroup.css

@@ -0,0 +1,40 @@
+.tag-group {
+  display: inline-flex;
+  gap: 8px;
+  align-items: center;
+  flex-wrap: wrap;
+  padding: 6px;
+}
+
+.tag {
+  border: solid 1px darkgreen;
+  background-color: green;
+  padding: 0 6px;
+  margin: 0 2px;
+  border-radius: 10px;
+  cursor: default;
+}
+
+.tag:hover {
+  opacity: 0.5;
+}
+
+.tag:focus {
+  background-color: red;
+  border-color: darkred;
+}
+
+.tag-remove-button {
+  padding: 4px;
+  cursor: pointer;
+  border: none;
+  background-color: transparent;
+}
+
+.item-to-add {
+  cursor: pointer;
+}
+
+.selected-tag {
+  font-style: italic;
+}

docusaurus/pages/useTagGroup.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react'
+
+import {useTagGroup} from '../../src'
+import {colors} from '../utils'
+
+import './useTagGroup.css'
+
+export default function TagGroup() {
+  const initialItems = colors.slice(0, 5)
+  const {
+    addItem,
+    getTagProps,
+    getTagRemoveProps,
+    getTagGroupProps,
+    items,
+    activeIndex,
+  } = useTagGroup({initialItems})
+  const itemsToAdd = colors.filter(color => !items.includes(color))
+
+  return (
+    <div>
+      <div
+        {...getTagGroupProps({'aria-label': 'colors example'})}
+        className="tag-group"
+      >
+        {items.map((color, index) => (
+          <span
+            className={`${index === activeIndex ? 'selected-tag' : ''} tag`}
+            key={color}
+            {...getTagProps({index, 'aria-label': color})}
+          >
+            {color}
+            <button
+              className="tag-remove-button"
+              type="button"
+              {...getTagRemoveProps({index, 'aria-label': 'remove'})}
+            >
+              &#10005;
+            </button>
+          </span>
+        ))}
+      </div>
+      <div>Add more items:</div>
+      <ul>
+        {itemsToAdd.map(item => (
+          <li key={item}>
+            <button
+              className="item-to-add"
+              tabIndex={0}
+              onClick={() => {
+                addItem(item)
+              }}
+              onKeyDown={({key}) => {
+                key === 'Enter' && addItem(item)
+              }}
+            >
+              {item}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}

docusaurus/pages/useTagGroupCombobox.css

@@ -0,0 +1,54 @@
+.wrapper {
+  width: 18rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.wrapper label {
+  width: fit-content;
+}
+
+.input-wrapper {
+  display: flex;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+  background-color: white;
+  gap: 0.125rem;
+}
+
+.text-input {
+  width: 100%;
+  padding: 0.375rem;
+}
+
+.toggle-button {
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+
+.menu {
+  position: absolute;
+  width: 18rem;
+  background-color: white;
+  margin-top: 0.25rem;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  max-height: 20rem;
+  overflow-y: scroll;
+  padding: 0;
+  z-index: 10;
+}
+
+.menu.hidden {
+  display: none;
+}
+
+.menu-item {
+  padding: 0.5rem 0.75rem;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+  display: flex;
+  flex-direction: column;
+}
+
+.menu-item.highlighted {
+  background-color: #93c5fd;
+}