<Collection> improvements: isPagination/isSearchable

docs/package.json

@@ -22,6 +22,7 @@
     "aws-amplify-react": "latest",
     "aws-amplify": "latest",
     "classnames": "^2.3.1",
+    "countries-list": "^2.6.1",
     "gray-matter": "^4.0.3",
     "lodash": "^4.17.21",
     "mdx-prism": "^0.3.3",

docs/src/pages/ui/primitives/collection/react.mdx

@@ -1,8 +1,17 @@
-import { Card, Collection, View, Text, Heading } from '@aws-amplify/ui-react';
+import {
+  Button,
+  Card,
+  Collection,
+  Flex,
+  View,
+  Text,
+  Heading,
+} from '@aws-amplify/ui-react';
+import { countries } from 'countries-list';
 import { CollectionDemo, ListCollectionExample } from './demo';
 import { Example } from '@/components/Example';
 
-A Collection wraps Flex and Grid components, and provides a way to display items in a collection from a data source. They come in `paginated` and `infiniteScrolling` versions. Both versions need paginated data.
+A Collection wraps Flex and Grid components, and provides a way to display items in a collection from a data source.
 
 ## Demo
 
@@ -74,11 +83,11 @@ const visitNewZealand = [
   </Collection>
 </Example>
 
-### Collection types
+## Collection types
 
 Collection `type` options include `list`, `grid`, and `table`.
 
-**List collection type**
+### List
 
 The `list` collection type can be customized with any of following Flex props: `alignItems`, `alignContent`, `direction`, `gap`, `justifyContent`, `wrap`.
 
@@ -133,10 +142,78 @@ The `list` collection type can be customized with any of following Flex props: `
   </Collection>
 </Example>
 
-#### Grid collection type
+## Pagination
 
-TBD
+A Collection can be paginated, adding a special `isPaginated` property. Change the page size passing a `itemsPerPage` property (default: 10).
 
-#### Table collection type
+```jsx
+<Collection type="list" items={countries} isPaginated itemsPerPage={12}>
+  {(country) => (
+    <Button>
+      {country.emoji} {country.name}
+    </Button>
+  )}
+</Collection>
+```
+
+<Example>
+  <Collection
+    type="list"
+    direction="row"
+    wrap="wrap"
+    items={Object.values(countries).map(({ name, emoji }) => ({ name, emoji }))}
+    isPaginated
+    itemsPerPage={12}
+  >
+    {(country) => (
+      <Button grow="1">
+        {country.emoji} {country.name}
+      </Button>
+    )}
+  </Collection>
+</Example>
+
+## Search
 
-TBD
+Collections can also be filtered, adding a `isSearchable` property. Pass a custom `searchFilter` function to enhance your search experience.
+
+```jsx
+const startsWith = (country, keyword) => country.name.startsWith(keyword)
+
+<Collection
+  type="grid"
+  items={countries}
+  itemsPerPage={9}
+  isSearchable
+  searchFilter={startsWith}
+  searchPlaceholder="Type to search..."
+>
+  {(country) => (
+    <Button grow="1">
+      {country.emoji} {country.name}
+    </Button>
+  )}
+</Collection>
+```
+
+<Example>
+  <Collection
+    type="grid"
+    templateColumns="1fr 1fr 1fr"
+    gap="15px"
+    items={Object.values(countries).map(({ name, emoji }) => ({ name, emoji }))}
+    isSearchable
+    isPaginated
+    itemsPerPage={9}
+    searchPlaceholder="Type to search..."
+    searchFilter={(country, keyword) =>
+      country.name.toLowerCase().startsWith(keyword.toLowerCase())
+    }
+  >
+    {(country) => (
+      <Button grow="1">
+        {country.emoji} {country.name}
+      </Button>
+    )}
+  </Collection>
+</Example>

packages/react/__tests__/exports.ts

@@ -18,7 +18,6 @@ describe('@aws-amplify/ui-react', () => {
           "Card",
           "CheckboxField",
           "Collection",
-          "CollectionTypeMap",
           "ComponentClassNames",
           "ComponentPropsToStylePropsMap",
           "ComponentPropsToStylePropsMapKeys",

packages/react/src/primitives/Collection/Collection.tsx

@@ -1,18 +1,101 @@
-import * as React from 'react';
-import { CollectionProps } from '../types';
+import debounce from 'lodash/debounce';
+import { useCallback, useState } from 'react';
 import { Flex } from '../Flex';
+import { Grid } from '../Grid';
+import { Pagination, usePagination } from '../Pagination';
+import { SearchField } from '../SearchField';
+import { strHasLength } from '../shared/utils';
+import {
+  CollectionProps,
+  GridCollectionProps,
+  ListCollectionProps,
+} from '../types';
+import { getItemsAtPage, itemHasText } from './utils';
 
-export const Collection = <CollectionItemType,>({
+const DEFAULT_PAGE_SIZE = 10;
+const TYPEAHEAD_DELAY_MS = 300;
+
+const ListCollection = <Item,>({
+  children,
   items,
+  ...rest
+}: ListCollectionProps<Item>) => (
+  <Flex {...rest}>{Array.isArray(items) && items.map(children)}</Flex>
+);
+
+const GridCollection = <Item,>({
   children,
-  className,
-  direction = 'column',
+  items,
+  ...rest
+}: GridCollectionProps<Item>) => (
+  <Grid {...rest}>{Array.isArray(items) && items.map(children)}</Grid>
+);
+
+export const Collection = <Item,>({
+  isSearchable,
+  isPaginated,
+  items,
+  itemsPerPage = DEFAULT_PAGE_SIZE,
+  searchFilter = itemHasText,
+  searchPlaceholder,
   type = 'list',
   ...rest
-}: CollectionProps<CollectionItemType>): JSX.Element => {
+}: CollectionProps<Item>): JSX.Element => {
+  const [searchText, setSearchText] = useState<string>();
+
+  const onSearch = useCallback(debounce(setSearchText, TYPEAHEAD_DELAY_MS), [
+    setSearchText,
+  ]);
+
+  // Make sure that items are iterable
+  items = Array.isArray(items) ? items : [];
+
+  // Filter items by text
+  if (isSearchable && strHasLength(searchText)) {
+    items = items.filter((item) => searchFilter(item, searchText));
+  }
+
+  // Pagination
+  const pagination = usePagination({
+    totalPages: Math.floor(items.length / itemsPerPage),
+  });
+
+  if (isPaginated) {
+    items = getItemsAtPage(items, pagination.currentPage, itemsPerPage);
+  }
+
+  const collection =
+    type === 'list' ? (
+      <ListCollection items={items} {...rest} />
+    ) : type === 'grid' ? (
+      <GridCollection items={items} {...rest} />
+    ) : null;
+
+  if (!isSearchable && !isPaginated) {
+    return collection;
+  }
+
   return (
-    <Flex direction={direction} className={className} {...rest}>
-      {Array.isArray(items) && items.map(children)}
+    <Flex direction="column">
+      {isSearchable && (
+        <Flex direction="row" justifyContent="center">
+          <SearchField
+            size="small"
+            label="Search"
+            placeholder={searchPlaceholder}
+            onChange={(e) => onSearch(e.target.value)}
+            onClear={() => setSearchText('')}
+          />
+        </Flex>
+      )}
+
+      {collection}
+
+      {isPaginated && (
+        <Flex justifyContent="center">
+          <Pagination {...pagination} />
+        </Flex>
+      )}
     </Flex>
   );
 };

packages/react/src/primitives/Collection/__tests__/Collection.test.tsx

@@ -3,6 +3,7 @@ import { kebabCase } from 'lodash';
 
 import { Collection } from '../Collection';
 import { ComponentPropsToStylePropsMap } from '../../types';
+import { ComponentClassNames } from '../../shared/constants';
 
 const emojis = [
   {
@@ -22,9 +23,52 @@ const emojis = [
 describe('Collection component', () => {
   const testList = 'testList';
 
+  it('should render a Search box when isSearchable is true', async () => {
+    render(
+      <Collection testId={testList} type="list" items={emojis} isSearchable>
+        {(item, index) => (
+          <div key={index} aria-label={item.title}>
+            {item.emoji}
+          </div>
+        )}
+      </Collection>
+    );
+
+    const searchField = await screen.findByRole('searchbox');
+    expect(searchField).not.toBe(undefined);
+  });
+
+  it('should render pagination when isPaginated is true', async () => {
+    render(
+      <Collection
+        testId={testList}
+        type="list"
+        items={emojis}
+        isPaginated
+        itemsPerPage={1}
+      >
+        {(item, index) => (
+          <div key={index} aria-label={item.title}>
+            {item.emoji}
+          </div>
+        )}
+      </Collection>
+    );
+
+    const navigation = await screen.findByRole('navigation');
+
+    expect(navigation.classList).toContain(ComponentClassNames.Pagination);
+    expect(navigation).not.toBe(undefined);
+  });
+
   it('should render Flex when rendering list collection', async () => {
     render(
-      <Collection testId={testList} type="list" items={emojis}>
+      <Collection
+        testId={testList}
+        type="list"
+        direction="column"
+        items={emojis}
+      >
         {(item, index) => (
           <div key={index} aria-label={item.title}>
             {item.emoji}

packages/react/src/primitives/Collection/utils.ts

@@ -0,0 +1,28 @@
+import { strHasLength } from '../shared/utils';
+
+/**
+ * Slice a collection based on page index (starting at 1)
+ */
+export const getItemsAtPage = <T>(
+  items: T[],
+  page: number,
+  itemsPerPage: number
+) => {
+  const startIndex = (page - 1) * itemsPerPage;
+  return items.slice(startIndex, startIndex + itemsPerPage);
+};
+
+/**
+ * Recursively find a keyword within an object (case insensitive)
+ */
+export const itemHasText = (item: unknown, text: string): boolean => {
+  if (strHasLength(item)) {
+    return item.toLowerCase().includes(text.toLowerCase());
+  }
+
+  if (typeof item === 'object') {
+    return Object.values(item).some((subItem) => itemHasText(subItem, text));
+  }
+
+  return false;
+};

packages/react/src/primitives/Pagination/Pagination.tsx

@@ -16,6 +16,7 @@ export const Pagination: React.FC<PaginationProps> = (props) => {
     onNext,
     onPrevious,
     onChange,
+    role = 'navigation',
     ...rest
   } = props;
 
@@ -31,6 +32,7 @@ export const Pagination: React.FC<PaginationProps> = (props) => {
   return (
     <View
       as="nav"
+      role={role}
       className={classNames(ComponentClassNames.Pagination, className)}
       {...rest}
     >

packages/react/src/primitives/Pagination/usePagination.ts

@@ -1,21 +1,23 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 
 import { UsePaginationProps, UsePaginationResult } from '../types/pagination';
 
 export const usePagination = (
   props: UsePaginationProps
 ): UsePaginationResult => {
-  let { currentPage: initialPage, totalPages, siblingCount = 1 } = props;
+  let { currentPage: initialPage = 1, totalPages, siblingCount = 1 } = props;
 
   // The current page should not be less than 1
   initialPage = Math.max(initialPage, 1);
   // The sibling count should not be less than 1
   siblingCount = Math.max(siblingCount, 1);
   // The total pages should be always greater than current page
   totalPages = Math.max(initialPage, totalPages);
-
   const [currentPage, setCurrentPage] = useState(initialPage);
 
+  // Reset current page if initialPage or totalPages changes
+  useEffect(() => setCurrentPage(initialPage), [initialPage, totalPages]);
+
   const onNext = useCallback(() => {
     if (currentPage < totalPages) {
       setCurrentPage(currentPage + 1);