Copyedits, working with lists tutorial. (#849)

Author: Arthur Evans

packages/lit-dev-content/site/tutorials/content/working-with-lists/00.md

@@ -1,25 +1,25 @@
-This tutorial will be exploring different ways of rendering lists of items in
+This tutorial explores different ways of rendering lists of items in
 Lit!
 
-Lit makes it easy to render any lists of items. It has built-it support for
+Lit makes it easy to render any list of items. It has built-it support for
 iterables: pass an array (or other iterable) to a child expression and Lit will
 render each item in the array. This, combined with Lit's ability to render
 nested templates, and JavaScript patterns for transforming lists of data into
 lists of templates, allows for very flexible list handling.
 
 ## What you'll learn
-- Rendering lists with the `map()` directive
-- Transforming arrays into templates with array methods
-- Generating lists with the `range()` directive
-- Imperatively building arrays of items
-- Diffing lists of stateful elements with the `repeat()` directive
-- Using event listeners in a list
+- Rendering lists with the `map()` directive.
+- Transforming arrays into templates with array methods.
+- Generating lists with the `range()` directive.
+- Imperatively building arrays of items.
+- Diffing lists of stateful elements with the `repeat()` directive.
+- Using event listeners in a list.
 
 ## Previous knowledge
-It is recommended to have basic understandings of
+This tutorial assumes that you've completed the
+[Intro to Lit](/tutorials/intro-to-lit/) tutorial,
+or you're already familiar with some of the basics of Lit:
 [defining a component](/docs/components/defining/),
 [rendering](/docs/components/rendering/),
 [reactive properties](/docs/components/properties/), and
-[adding an event listener](/docs/components/events/#adding-event-listeners-in-the-element-template)
-before working on this tutorial. The [Intro to Lit](/tutorials/intro-to-lit/)
-tutorial is a great place to start.
+[adding an event listener](/docs/components/events/#adding-event-listeners-in-the-element-template).

packages/lit-dev-content/site/tutorials/content/working-with-lists/01.md

@@ -2,12 +2,12 @@ Lit supports rendering iterables of items directly in templates, but you often
 need to render a _template_ that uses the items, rather than the items directly.
 
 Lit provides a built-in `map()` directive that lets you transform the items in
-an iterable. The `map()` directive works with any iterables such as arrays,
-sets, maps, and even generators. It returns an iterable containing the result of
-calling the provided callback function on each item.
+an iterable. The `map()` directive works with all kinds of iterables, including
+arrays, sets, maps, and even generators. It returns an iterable containing the
+result of calling the provided callback function on each item.
 
-In this example, a custom element is presented with a state property named
-`items` that contains a set of strings.
+In this example, you're given a custom element with a state property named
+`items`, which contains a set of strings.
 
 Render each item in the set as a list item (`<li>`) containing that string.
 Begin by importing the `map()` directive.

packages/lit-dev-content/site/tutorials/content/working-with-lists/02.md

@@ -42,6 +42,6 @@ results to place in the component's template.
 
 {% endswitchable-sample %}
 
-Using array methods is helpful when chaining like this, but does require the
+Using array methods is helpful when chaining like this, but it does require the
 original source to be an array. Consider using the `map()` directive as shown in
 the previous step for any iterables that are not arrays.

packages/lit-dev-content/site/tutorials/content/working-with-lists/03.md

@@ -10,8 +10,7 @@ In this example, the component has the following state properties:
 Render a list item for each member but also include pets if `includePets` is
 `true`. The list item for the pet should include both the name and the species.
 
-Populate the `listItems` array conditionally based on the boolean state
-like shown below.
+Populate the `listItems` array conditionally based on the boolean state, as shown below.
 
 {% switchable-sample %}
 
@@ -83,7 +82,7 @@ Then add the `listItems` array to your element's template.
 
 Click the button to see if the conditional rendering is working properly.
 
-Extra Credit: Try refactoring the code to abstract out the logic from the
+Extra Credit: Try refactoring the code to abstract the logic out of the
 `render()` method into its own private method that returns the array of
-templates and invoke it within the template expression where `listItems`
-currently is.
+templates. Then invoke the new method inside the template expression
+(replacing `listItems`).

packages/lit-dev-content/site/tutorials/content/working-with-lists/04.md

@@ -4,7 +4,7 @@ board, for instance.
 The `range()` directive provides a simple way of creating an iterable of
 incrementing integers which can be used with the `map()` directive to
 programmatically render a list of templates in a convenient manner. Nesting this
-allows creation of multi-dimensional patterns.
+allows you to create multi-dimensional patterns.
 
 The example component already has some styles defined to create an 8 by 8 board
 to be filled with `<div>`s whose background color will be determined by adding
@@ -28,7 +28,7 @@ import {map} from 'lit/directives/map.js';
 
 {% endswitchable-sample %}
 
-Use these directives to create squares of black and white colors like a chess
+Use these directives to create black and white squares like a chess
 board.
 
 {% switchable-sample %}

packages/lit-dev-content/site/tutorials/content/working-with-lists/05.md

@@ -1,11 +1,11 @@
 When using the `map()` directive or just providing an iterable within the
 template, Lit creates a list of DOM nodes and updates them in the iteration
-order, efficiently reusing any previously rendered nodes. These techniques
-should only be used when Lit controls all of the rendered state as is commonly
-the case.
+order, efficiently reusing any previously rendered nodes. This technique
+should only be used when Lit controls all of the rendered state (as is commonly
+the case).
 
-However, when relying instead on the DOM nodes to maintain state that is not
-controlled by Lit, unexpected behavior can occur as the example below wil
+However, when relying instead on the DOM nodes to maintain state that **isn't**
+controlled by Lit, unexpected behavior can occur as the example below will
 demonstrate. In this case, use the `repeat()` directive instead.
 
 ## Example
@@ -92,15 +92,14 @@ template to render for each item.
 {% endswitchable-sample %}
 
 Confirm that this is working correctly by checking an item and changing the sort
-order. The check mark should now be moving to stay next to its original label.
+order. The check mark should now move to stay next to its original label.
 
 {% aside "positive" %}
 
 The key function provided must return a unique key for an item.
 
-A key function that simply returns the index (or omitting the key function)
-would have the same behavior as using `map()`. See the [repeat
-documentation](/docs/templates/directives/#repeat) for more details. Also see
+If you omit the key function—or provide a key function that simply returns the index—`repeat()` behaves exactly like `map()`. For more information, see the [repeat
+documentation](/docs/templates/directives/#repeat). Also see
 [When to use map or repeat](/docs/templates/lists/#when-to-use-map-or-repeat)
 for guidance on deciding when to use one or the other.
 

packages/lit-dev-content/site/tutorials/content/working-with-lists/06.md

@@ -1,13 +1,11 @@
-There are several ways of adding event listeners to list items getting rendered,
-but care must be taken to ensure the correct information is made available to
-the event handler. This step shows one way of achieving this.
+There are several ways of adding event listeners to list items in your template.
+You also need to make sure that the event handler can identify which item the event is related to. This step shows one way of achieving this.
 
-The example currently has an array of strings in the `things` state property
-that are being rendered as list items with a "Delete" button which does not do
-anything yet.
+The example currently has an array of strings in the `things` state property.
+Each string is rendered as a list item with a "Delete" button, but the button
+does not do anything yet.
 
-First, create a method that will be called when the button is clicked that will
-remove the item from the `things` array. It will take the item's index.
+First, create a method that will be called when the button is clicked. The method should take an item's index as a parameter, and remove that item from the `things` array.
 
 {% switchable-sample %}
 
@@ -41,8 +39,8 @@ The `filter()` array method returns a new array which is assigned to
 `this.things`. Since the reference stored in `this.things` changes, Lit will
 know to update the component when `_deleteThing()` is called. If the array is
 mutated instead with something like the `splice()` array method, an update must
-be manually requested. See [Mutating objects and array
-properties](/docs/components/properties/#mutating-properties) for details.
+be manually requested. For more information, see [Mutating objects and array
+properties](/docs/components/properties/#mutating-properties).
 
 {% endaside %}
 
@@ -94,19 +92,18 @@ mapped.
 {% endswitchable-sample %}
 
 Now clicking the delete button should remove the item. Note that an inline arrow
-function is used here to create closures such that each list item gets a
+function is used here to create a closure, so each list item gets a
 function that calls `_deleteThing` with its own index.
 
 {% aside "info" %}
 
-While closures will be fine for most cases, there are other ways to achieve this
+While closures are fine for most cases, there are other ways to achieve this
 behavior.
 
-For instance, a property or attribute can be left on the element with the
-listener which can then be accessed by the event handler via `event.target`.
-When listening to an event that bubbles, using event delegation can be a
-convenient way of handling it without attaching event listeners on every item.
-Read more about it in [Listening to events fired from repeated
-templates](/docs/components/events/#listening-to-events-fired-from-repeated-templates).
+For instance, you can add a property or attribute to the element that dispatches
+the event. The event handler can then access that data using `event.target`.
+When listening to an event that bubbles, you can use event delegation to avoid
+attaching event listeners on every item. For more information, see [Listening to
+events fired from repeated templates](/docs/components/events/#listening-to-events-fired-from-repeated-templates).
 
 {% endaside %}

packages/lit-dev-content/site/tutorials/content/working-with-lists/07.md

@@ -1,32 +1,36 @@
-Congratulations on completing the **Working with Lists** tutorial!
+Congratulations on completing the **Working with lists** tutorial!
 
 ## Takeaways
 
 - Lit has built-in support for rendering iterables! Just place arrays, sets,
   maps, or generators directly into the template expression.
 - Use the `map()` directive for a declarative way of taking an iterable and
-  transforming each item into some renderable template. Use it when all
-  necessary states are controlled by Lit.
-- For complex situations involving more logic, an array of renderables can be
-  manually built and placed into the component template. Consider using a
+  transforming each item into a renderable template. Use it when all
+  necessary state is controlled by Lit.
+- For complex situations involving more logic, you can build an array of
+  renderable imperatively using the `Array` methods. Consider using a
   separate private method to abstract the related logic out of the `render()`
   method.
-- Use the `repeat()` directive when relying on the DOM nodes for some state or
-  otherwise needing a tight coupling between the DOM and the list item. Provide
-  a key function that produces a unique key for each item of the iterable.
+- Use the `repeat()` directive when the rendered DOM nodes have state that
+  **isn't** controlled by Lit, or when updating the DOM nodes is more expensive
+  than moving them. Provide a key function that produces a unique key for each
+  item of the iterable.
 - Consider using the `range()` directive along with `map()` to programmatically
   generate a list. These can be nested to produce a multi-dimensional grid as
   well.
 - Lastly, when adding event listeners to items rendered from a list, make sure
   the handler has access to the data it needs that's specific to each item.
   Using an inline arrow function is often a good way to achieve this by creating
-  closures.
+  a closure for each item.
 
 ## Further learning
 
 Check out other [built-in directives](/docs/templates/directives/) besides
 `map()`, `repeat()`, and `range()` that are available, or learn how to make your
 very own [custom directive](/docs/templates/custom-directives/)!
 
+To learn more about reactive properties and the reactive update cycle that drives
+ Lit components, try the [Reactivity tutorial](/tutorials/reactivity/)
+
 <!-- TODO(augustinekim) Add callout to virtualizer for handling big lists
      when it lands -->