Docs collection (#2051)

* update collection docs, update existing examples, add grid example, add styling examples

* use demo state and design tokens

* add theming example to collection docs

* add theming example and update styling examples

* use design tokens and typo corrections

* correct typo in docs

Co-authored-by: Jacob Logan <[email protected]>

Author: jacoblogan

docs/src/pages/[platform]/components/collection/CollectionPropControls.tsx

@@ -0,0 +1,64 @@
+import {
+  CollectionProps,
+  FlexProps,
+  Flex,
+  SelectField,
+  TextField,
+} from '@aws-amplify/ui-react';
+import React from 'react';
+
+export type CollectionPropControlsProps = Omit<
+  CollectionProps<[]>,
+  'type' | 'children' | 'items'
+> &
+  FlexProps & {
+    setDirection: (value: React.SetStateAction<FlexProps['direction']>) => void;
+    setGap: (value: React.SetStateAction<FlexProps['gap']>) => void;
+    setWrap: (value: React.SetStateAction<FlexProps['wrap']>) => void;
+  };
+
+interface CollectionPropControlsInterface {
+  (props: CollectionPropControlsProps): JSX.Element;
+}
+
+export const CollectionPropControls: CollectionPropControlsInterface = ({
+  direction,
+  setDirection,
+  gap,
+  setGap,
+  wrap,
+  setWrap,
+}) => {
+  return (
+    <Flex direction="column">
+      <SelectField
+        name="direction"
+        id="direction"
+        label="direction"
+        value={direction as string}
+        onChange={(event) => setDirection(event.target.value)}
+      >
+        <option value="row">row</option>
+        <option value="column">column</option>
+      </SelectField>
+
+      <TextField
+        label="Gap"
+        value={gap as string}
+        onChange={(event) => setGap(event.target.value)}
+      />
+
+      <SelectField
+        name="wrap"
+        id="wrap"
+        label="Wrap"
+        value={wrap as string}
+        onChange={(event) => setWrap(event.target.value)}
+      >
+        <option value="nowrap">nowrap</option>
+        <option value="wrap">wrap</option>
+        <option value="wrap-reverse">wrap-reverse</option>
+      </SelectField>
+    </Flex>
+  );
+};

docs/src/pages/[platform]/components/collection/demo.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import {
   Card,
-  Text,
   View,
   Image,
   Badge,
@@ -11,46 +10,55 @@ import {
   Heading,
   Collection,
   FlexContainerStyleProps,
+  useTheme,
 } from '@aws-amplify/ui-react';
 
-import { Example } from '@/components/Example';
-import { GetFieldControls } from '../shared/GetFieldControls';
-import { useFlexContainerStyleProps } from '../shared/useFlexContainerStyleProps';
+import { Demo } from '@/components/Demo';
+import { demoState } from '@/utils/demoState';
+import { CollectionPropControls } from './CollectionPropControls';
+import { useCollectionProps } from './useCollectionProps';
+import {
+  filterDemoProps,
+  getDemoProps,
+  objectEntriesToPropString,
+} from '../utils/demoProps';
+
+const propsToCode = (props) => {
+  const filteredProps = filterDemoProps(props);
+  return `
+<Collection
+  type='list'
+${objectEntriesToPropString(Object.entries(filteredProps))}
+>
+  {collectionItems}
+</Collection>`;
+};
 
 export const CollectionDemo = () => {
-  const flexStyleProps = useFlexContainerStyleProps({
-    alignItems: 'normal',
-    alignContent: 'start',
+  const defaultValues = {
     direction: 'row',
     gap: '20px',
-    justifyContent: 'space-between',
     wrap: 'nowrap',
-  });
-  const PropControls = GetFieldControls({
-    typeName: 'Collection List (Flex)',
-    fields: flexStyleProps,
-  });
-  const [
-    [alignItems],
-    [alignContent],
-    [direction],
-    [gap],
-    [justifyContent],
-    [wrap],
-  ] = flexStyleProps;
+  };
+
+  const { tokens } = useTheme();
+
+  const collectionProps = useCollectionProps(
+    demoState.get(Collection.displayName) || defaultValues
+  );
+  const demoProps = ['alignContent', 'alignItems', 'direction', 'gap', 'wrap'];
+  const collectionDemoProps = getDemoProps(collectionProps, demoProps);
 
   const list = [
     {
-      title: 'Milford Sound - Room #1',
+      title: 'Milford - Room #1',
       imageSrc: '/road-to-milford-new-zealand-800w.jpg',
       imageAlt:
         'Glittering stream with old log, snowy mountain peaks tower over a green field.',
-      description:
-        'Join us on this beautiful outdoor adventure through the glittering rivers through the snowy peaks on New Zealand.',
       badges: [
         {
           color: 'lightblue',
-          text: 'Waterfront View',
+          text: 'Waterfront',
         },
         {
           color: 'lightgreen',
@@ -59,16 +67,14 @@ export const CollectionDemo = () => {
       ],
     },
     {
-      title: 'Milford Sound - Room #2',
+      title: 'Milford - Room #2',
       imageSrc: '/road-to-milford-new-zealand-800w.jpg',
       imageAlt:
         'Glittering stream with old log, snowy mountain peaks tower over a green field.',
-      description:
-        'Join us on this beautiful outdoor adventure through the glittering rivers through the snowy peaks on New Zealand.',
       badges: [
         {
-          color: 'lightyellow',
-          text: 'Mountain View',
+          color: tokens.colors.yellow[60].value,
+          text: 'Mountain',
         },
         {
           color: 'lightgreen',
@@ -79,42 +85,51 @@ export const CollectionDemo = () => {
   ];
 
   return (
-    <View width="100%">
-      {PropControls}
-      <Divider margin="0.5rem 0.5rem" />
-      <Example>
+    <Demo
+      code={propsToCode(collectionDemoProps)}
+      propControls={<CollectionPropControls {...collectionProps} />}
+    >
+      <View
+        backgroundColor={tokens.colors.background.secondary}
+        padding={tokens.space.medium}
+      >
         <Collection
           items={list}
           type="list"
-          alignContent={alignContent as FlexContainerStyleProps['alignContent']}
-          alignItems={alignItems as FlexContainerStyleProps['alignItems']}
-          direction={direction as FlexContainerStyleProps['direction']}
-          gap={gap as FlexContainerStyleProps['gap']}
-          justifyContent={
-            justifyContent as FlexContainerStyleProps['justifyContent']
+          direction={
+            collectionProps.direction as FlexContainerStyleProps['direction']
           }
-          wrap={wrap as FlexContainerStyleProps['wrap']}
+          gap={collectionProps.gap as FlexContainerStyleProps['gap']}
+          wrap={collectionProps.wrap as FlexContainerStyleProps['wrap']}
         >
           {(item, index) => (
-            <Card key={index}>
+            <Card
+              key={index}
+              maxWidth="20rem"
+              variation="outlined"
+              borderRadius="5px"
+            >
               <Image src={item.imageSrc} alt={item.imageAlt} />
-              <View padding="1rem">
+              <View padding={tokens.space.xs}>
                 <Flex>
                   {item.badges.map((badge) => (
                     <Badge key={badge.text} backgroundColor={badge.color}>
                       {badge.text}
                     </Badge>
                   ))}
                 </Flex>
-                <Divider padding="1rem 0 0 0" />
-                <Heading level={3}>{item.title}</Heading>
-                <Text padding="0 0 1rem 0">{item.description}</Text>
-                <Button isFullWidth={true}>Book it</Button>
+                <Divider padding={`${tokens.space.xxxs} 0`} />
+                <Heading level={6} padding={tokens.space.xxxs}>
+                  {item.title}
+                </Heading>
+                <Button isFullWidth={true} variation="primary">
+                  Book it
+                </Button>
               </View>
             </Card>
           )}
         </Collection>
-      </Example>
-    </View>
+      </View>
+    </Demo>
   );
 };

docs/src/pages/[platform]/components/collection/examples/CollectionStylePropExample.tsx

@@ -0,0 +1,29 @@
+import { Collection, Button, useTheme } from '@aws-amplify/ui-react';
+import { countries } from 'countries-list';
+
+export const CollectionStylePropExample = () => {
+  const { tokens } = useTheme();
+  const items = Object.values(countries)
+    .map(({ name, emoji }) => ({
+      name,
+      emoji,
+    }))
+    .splice(0, 20);
+  return (
+    <Collection
+      type="list"
+      border={`${tokens.borderWidths.medium} solid ${tokens.colors.red[60]}`}
+      direction="row"
+      wrap="wrap"
+      padding="5px"
+      gap="20px"
+      items={items}
+    >
+      {(regions, index) => (
+        <Button grow="1" key={index}>
+          {regions.emoji}
+        </Button>
+      )}
+    </Collection>
+  );
+};

docs/src/pages/[platform]/components/collection/examples/CollectionThemeExample.tsx

@@ -0,0 +1,61 @@
+import {
+  Button,
+  Collection,
+  defaultDarkModeOverride,
+  ThemeProvider,
+  Theme,
+} from '@aws-amplify/ui-react';
+import { countries } from 'countries-list';
+
+export const CollectionThemeExample = () => {
+  const theme: Theme = {
+    name: 'collection-theme',
+    tokens: {
+      components: {
+        collection: {
+          search: {
+            button: {
+              color: { value: '{colors.brand.secondary.40}' },
+              _active: {
+                backgroundColor: { value: '{colors.brand.primary.80}' },
+              },
+              _focus: {
+                backgroundColor: { value: '{colors.brand.primary.80}' },
+              },
+              _hover: {
+                backgroundColor: { value: '{colors.brand.primary.80}' },
+              },
+            },
+          },
+        },
+      },
+    },
+    overrides: [defaultDarkModeOverride],
+  };
+  return (
+    <ThemeProvider theme={theme} colorMode="system">
+      <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={(regions, keyword) =>
+          (regions as any).name.toLowerCase().startsWith(keyword.toLowerCase())
+        }
+      >
+        {(regions, index) => (
+          <Button grow="1" key={index}>
+            {regions.emoji} {regions.name}
+          </Button>
+        )}
+      </Collection>
+    </ThemeProvider>
+  );
+};

docs/src/pages/[platform]/components/collection/examples/DefaultCollectionExample.tsx

@@ -0,0 +1,34 @@
+import { Collection, Card, Heading, Text } from '@aws-amplify/ui-react';
+
+export const DefaultCollectionExample = () => {
+  return (
+    <Collection
+      type="list"
+      items={[
+        {
+          title: 'Fiordland National Park',
+          description:
+            'This national park includes the famous fjords of Milford, Dusky and Doubtful Sounds.',
+        },
+        {
+          title: 'Bay of Islands, North Island',
+          description:
+            'Three hours north of Auckland, this area features over 144 islands to explore.',
+        },
+        {
+          title: 'Queenstown, South Island',
+          description:
+            "This hopping town is New Zealand's adventure capital and is located right on Lake Wakatipu.",
+        },
+      ]}
+      gap="1.5rem"
+    >
+      {(item, index) => (
+        <Card key={index} padding="1rem">
+          <Heading level={4}>{item.title}</Heading>
+          <Text>{item.description}</Text>
+        </Card>
+      )}
+    </Collection>
+  );
+};