Port official relay tutorial

rescript-relay-documentation/docs/tutorial/arrays-lists.md

@@ -0,0 +1,139 @@
+---
+id: tutorial-arrays-lists
+title: Arrays and Lists
+sidebar_label: Arrays and Lists
+---
+
+:::info
+This tutorial is forked from the [official Relay tutorial](https://relay.dev/docs/tutorial/intro/), and adapted to RescriptRelay. All the credit goes to the Relay team for writing the tutorial.
+:::
+
+# Arrays and Lists
+
+So far we’ve only dealt with components that have a single instance of the components they’re composed from. For example, we’re only showing a single Newsfeed story, and within that story there’s just a single author with a single profile picture. Let’s look at how to handle more than one of something.
+
+GraphQL includes support for arrays, which in GraphQL are called _lists._ A field can be not only a single scalar value but an array of them, or not only a single edge but an array of edges. The schema specifies whether each field is a list or not, but, oddly, the GraphQL query syntax doesn’t distinguish between selecting a singular field and selecting a list — a quirky exception to the design principle that a GraphQL response should have the same shape as the query.
+
+Request:
+
+```
+query MyQuery {
+  viewer {
+    contacts { // List of edges
+      id // field on a single item
+      name
+    }
+  }
+}
+```
+
+Response:
+
+```
+{
+  viewer: {
+    contacts: [ // array in response
+      {
+        id: "123",
+        name: "Chris",
+      },
+      {
+        id: "789",
+        name: "Sue",
+      }
+    ]
+  }
+}
+```
+
+As it happens, the schema in our example app has a `topStories` field that returns a list of Stories, as opposed to the `topStory` field we're currently using that returns just one.
+
+To show multiple stories on our newsfeed, we just need to modify `Newsfeed.res` to use `topStories`.
+
+### Step 1 — Select a list in the fragment
+
+Open `Newsfeed.res` and find `NewsfeedQuery`. Replace `topStory` with `topStories`.
+
+```rescript
+const NewsfeedQuery = graphql`
+  query NewsfeedQuery {
+    // change-line
+    topStories {
+      ...StoryFragment
+    }
+  }
+`;
+```
+
+### Step 2 — Map over the list in the component
+
+In the `Newsfeed` component, `data.topStories` will now be an array of fragment refs, each of which can be passed to a `Story` child component to render that story:
+
+```rescript
+@react.component
+let make = () => {
+  let data = NewsfeedQuery.use(~variables=(), ())
+
+  switch topStories {
+  | None => React.null
+  | Some(stories) =>
+    <div className="newsfeed">
+      {stories
+      ->Belt.Array.keepMap(x => x)
+      ->Belt.Array.map(story => <Story story={story.fragmentRefs} />)
+      ->React.array}
+    </div>
+  }
+}
+```
+
+### Step 3 — Add a React key based on the node ID
+
+At this point, you should see multiple stories on the screen! It's beginning to look like a proper newsfeed app.
+
+![Multiple stories](/img/docs/tutorial/arrays-top-stories-screenshot.png)
+
+However, we're also getting a React warning that we're rendering an array of components without [providing a key attribute](https://reactjs.org/docs/lists-and-keys.html).
+
+![React missing key warning](/img/docs/tutorial/arrays-keys-warning-screenshot.png)
+
+It's always important to heed this warning, and more specifically to base keys on the identity of the things being displayed, rather than simply their indices in the array. This allows React to handle reordering and deleting items from the list correctly, since it knows which items are which even if their order changes.
+
+Luckily, GraphQL nodes generally have IDs. We can simply select the `id` field of `story` and use it as a key:
+
+```rescript
+module NewsfeedQuery = %relay(`
+  query NewsfeedQuery {
+    topStories {
+      // change-line
+      id
+      ...StoryFragment
+    }
+  }
+`)
+
+@react.component
+let make = () => {
+  let {topStories} = NewsfeedQuery.use(~variables=(), ())
+
+  switch topStories {
+  | None => React.null
+  | Some(stories) =>
+    <div className="newsfeed">
+      {stories
+      ->Belt.Array.keepMap(x => x)
+      // change-line
+      ->Belt.Array.map(story => <Story key={story.id} story={story.fragmentRefs} />)
+      ->React.array}
+    </div>
+  }
+}
+```
+
+With that, we've got a collection of Stories on the screen. It's worth pointing out that here we're mixing individual fields with fragment spreads in the same place in our query. This means that Newsfeed can read the fields it cares about (directly from `Newsfeed.use`) while Story can read the fields it cares about (via `StoryFragment.use`). The _same object_ both contains Newsfeed's selected field `id` and is also a fragment key for `StoryFragment`.
+
+:::tip
+GraphQL Lists are only the most basic way of dealing with collections of things. We’ll build on them to do pagination and infinite scrolling later in the tutorial, using a special system called Connections. You’ll want to use Connections in most situations where you have a collection of items — although you’ll still use GraphQL Lists as a building block.
+:::
+
+Onward!