From 0eae1679aad9b611edb02b568244d1df7efe405d Mon Sep 17 00:00:00 2001
From: Matt Dunn-Rankin <mattdunnrankin@khanacademy.org>
Date: Sat, 25 Apr 2020 23:51:07 -0700
Subject: [PATCH] refactor ItemList.js -> Item.js, cleanups & docs

---
 src/Item.js        | 231 +++++++++++++++++++++++++++++++++++++++++++++
 src/ItemList.js    | 176 ----------------------------------
 src/ItemsPanel.js  |   2 +-
 src/SearchPanel.js |   2 +-
 4 files changed, 233 insertions(+), 178 deletions(-)
 create mode 100644 src/Item.js
 delete mode 100644 src/ItemList.js

diff --git a/src/Item.js b/src/Item.js
new file mode 100644
index 0000000..b6199f4
--- /dev/null
+++ b/src/Item.js
@@ -0,0 +1,231 @@
+import React from "react";
+import { css, cx } from "emotion";
+import {
+  Box,
+  Flex,
+  IconButton,
+  Image,
+  Skeleton,
+  Tooltip,
+  useTheme,
+} from "@chakra-ui/core";
+
+/**
+ * Item show a basic summary of an item, in the context of the current outfit!
+ *
+ * It also responds to the focus state of an `input` as its previous sibling.
+ * This will be an invisible radio/checkbox that controls the actual wear
+ * state.
+ *
+ * In fact, this component can't trigger wear or unwear events! When you click
+ * it in the app, you're actually clicking a <label> that wraps the radio or
+ * checkbox. We _do_ control the Remove button in here, though!
+ */
+export function Item({ item, itemNameId, outfitState, dispatchToOutfit }) {
+  const { wornItemIds, allItemIds } = outfitState;
+  const isWorn = wornItemIds.includes(item.id);
+  const isInOutfit = allItemIds.includes(item.id);
+
+  return (
+    <ItemContainer>
+      <ItemThumbnail src={item.thumbnailUrl} isWorn={isWorn} />
+      <Box width="3" />
+      <ItemName id={itemNameId} isWorn={isWorn}>
+        {item.name}
+      </ItemName>
+      <Box flexGrow="1" />
+      {isInOutfit && (
+        <RemoveItemButton
+          onClick={() =>
+            dispatchToOutfit({ type: "removeItem", itemId: item.id })
+          }
+        />
+      )}
+    </ItemContainer>
+  );
+}
+
+/**
+ * ItemContainer is the outermost element of an `Item`.
+ *
+ * It provides spacing, but also is responsible for a number of hover/focus/etc
+ * styles - including for its children, who sometimes reference it as an
+ * .item-container parent!
+ */
+function ItemContainer({ children }) {
+  const theme = useTheme();
+
+  return (
+    <Box
+      p="1"
+      my="1"
+      rounded="lg"
+      d="flex"
+      alignItems="center"
+      cursor="pointer"
+      border="1px"
+      borderColor="transparent"
+      className={cx([
+        "item-container",
+        css`
+          &:hover,
+          input:focus + & {
+            background-color: ${theme.colors.gray["100"]};
+          }
+
+          input:active + & {
+            border-color: ${theme.colors.green["400"]};
+          }
+
+          input:checked:focus + & {
+            border-color: ${theme.colors.green["800"]};
+          }
+        `,
+      ])}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/**
+ * ItemThumbnail shows a small preview image for the item, including some
+ * hover/focus and worn/unworn states.
+ */
+function ItemThumbnail({ src, isWorn }) {
+  const theme = useTheme();
+  return (
+    <Box
+      rounded="lg"
+      boxShadow="md"
+      border="1px"
+      borderColor="green.700"
+      width="50px"
+      height="50px"
+      overflow="hidden"
+      transition="all 0.15s"
+      transformOrigin="center"
+      transform="scale(0.8)"
+      className={css([
+        !isWorn && {
+          [containerHasFocus]: {
+            opacity: "0.9",
+            transform: "scale(0.9)",
+            borderColor: theme.colors.green["600"],
+          },
+        },
+        isWorn && {
+          opacity: 1,
+          transform: "none",
+        },
+      ])}
+    >
+      <Image src={src} />
+    </Box>
+  );
+}
+
+/**
+ * ItemName shows the item's name, including some hover/focus and worn/unworn
+ * states.
+ */
+function ItemName({ children, ...props }) {
+  const theme = useTheme();
+
+  return (
+    <Box
+      fontSize="md"
+      color="green.800"
+      transition="all 0.15s"
+      className={css`
+        ${containerHasFocus} {
+          opacity: 0.9;
+          font-weight: ${theme.fontWeights.medium};
+        }
+
+        input:checked + .item-container & {
+          opacity: 1;
+          font-weight: ${theme.fontWeights.bold};
+        }
+      `}
+      {...props}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/**
+ * RemoveItemButton lets the user remove the item from the outfit altogether.
+ *
+ * This removes it from their "closet", which is even more severe than
+ * unwearing it: it disappears from your item list entirely, until you find it
+ * again via search!
+ */
+function RemoveItemButton({ onClick }) {
+  const theme = useTheme();
+
+  return (
+    <Tooltip label="Remove" placement="top">
+      <IconButton
+        icon="delete"
+        aria-label="Remove from outfit"
+        variant="ghost"
+        color="gray.400"
+        onClick={(e) => {
+          onClick();
+          e.preventDefault();
+        }}
+        className={css`
+          opacity: 0;
+          transition: all 0.2s;
+
+          ${containerHasFocus} {
+            opacity: 1;
+          }
+
+          &:focus,
+          &:hover {
+            opacity: 1;
+            background-color: ${theme.colors.gray["300"]};
+            color: ${theme.colors.gray["700"]};
+          }
+        `}
+      />
+    </Tooltip>
+  );
+}
+
+/**
+ * ItemListContainer is a container for Item components! Wrap your Item
+ * components in this to ensure a consistent list layout.
+ */
+export function ItemListContainer({ children }) {
+  return <Flex direction="column">{children}</Flex>;
+}
+
+/**
+ * ItemListSkeleton is a loading placeholder for an `ItemListContainer` and the
+ * `Item`s inside!
+ */
+export function ItemListSkeleton({ count }) {
+  return (
+    <ItemListContainer>
+      {Array.from({ length: count }).map((_, i) => (
+        <ItemContainer key={i}>
+          <Skeleton width="50px" height="50px" />
+          <Box width="3" />
+          <Skeleton height="1.5rem" width="12rem" />
+        </ItemContainer>
+      ))}
+    </ItemListContainer>
+  );
+}
+
+/**
+ * containerHasFocus is a common CSS selector, for the case where our parent
+ * .item-container is hovered or the adjacent hidden radio/checkbox is
+ * focused.
+ */
+const containerHasFocus =
+  ".item-container:hover &, input:focus + .item-container &";
diff --git a/src/ItemList.js b/src/ItemList.js
deleted file mode 100644
index 1d2da37..0000000
--- a/src/ItemList.js
+++ /dev/null
@@ -1,176 +0,0 @@
-import React from "react";
-import { css } from "emotion";
-import {
-  Box,
-  Flex,
-  IconButton,
-  Image,
-  Skeleton,
-  Tooltip,
-  useTheme,
-} from "@chakra-ui/core";
-
-export function ItemListContainer({ children }) {
-  return <Flex direction="column">{children}</Flex>;
-}
-
-export function ItemListSkeleton({ count }) {
-  return (
-    <Flex direction="column">
-      {Array.from({ length: count }).map((_, i) => (
-        <ItemSkeleton key={i} />
-      ))}
-    </Flex>
-  );
-}
-
-export function Item({ item, itemNameId, outfitState, dispatchToOutfit }) {
-  const { allItemIds } = outfitState;
-  const isInOutfit = allItemIds.includes(item.id);
-  const theme = useTheme();
-
-  return (
-    <ItemContainer>
-      <ItemThumbnail src={item.thumbnailUrl} />
-      <Box width="3" />
-      <ItemName id={itemNameId}>{item.name}</ItemName>
-      <Box flexGrow="1" />
-      {isInOutfit && (
-        <Tooltip label="Remove" placement="top">
-          <IconButton
-            icon="delete"
-            aria-label="Remove from outfit"
-            variant="ghost"
-            color="gray.400"
-            onClick={(e) => {
-              dispatchToOutfit({ type: "removeItem", itemId: item.id });
-              e.preventDefault();
-            }}
-            opacity="0"
-            transitionProperty="opacity color"
-            transitionDuration="0.2s"
-            className={css`
-              &:focus,
-              &:hover,
-              .item-container:hover &,
-              input:focus + .item-container & {
-                opacity: 1;
-              }
-
-              &:focus,
-              &:hover {
-                background-color: ${theme.colors.gray["300"]};
-                color: ${theme.colors.gray["700"]};
-              }
-            `}
-          />
-        </Tooltip>
-      )}
-    </ItemContainer>
-  );
-}
-
-function ItemSkeleton() {
-  return (
-    <ItemContainer>
-      <Box d="flex" alignItems="center">
-        <Skeleton width="50px" height="50px" />
-        <Box width="3" />
-        <Skeleton height="1.5rem" width="12rem" />
-      </Box>
-    </ItemContainer>
-  );
-}
-
-function ItemContainer({ children }) {
-  const theme = useTheme();
-
-  return (
-    <Box
-      p="1"
-      my="1"
-      rounded="lg"
-      d="flex"
-      alignItems="center"
-      cursor="pointer"
-      border="1px"
-      borderColor="transparent"
-      className={
-        "item-container " +
-        css`
-          &:hover,
-          input:focus + & {
-            background-color: ${theme.colors.gray["100"]};
-          }
-
-          input:active + & {
-            border-color: ${theme.colors.green["400"]};
-          }
-          input:checked:focus + & {
-            border-color: ${theme.colors.green["800"]};
-          }
-        `
-      }
-    >
-      {children}
-    </Box>
-  );
-}
-
-function ItemThumbnail({ src }) {
-  const theme = useTheme();
-  return (
-    <Box
-      rounded="lg"
-      boxShadow="md"
-      border="1px"
-      borderColor="green.700"
-      width="50px"
-      height="50px"
-      overflow="hidden"
-      transition="all 0.15s"
-      transformOrigin="center"
-      transform="scale(0.8)"
-      className={css`
-        .item-container:hover & {
-          opacity: 0.9;
-          transform: scale(0.9);
-          bordercolor: ${theme.colors.green["600"]};
-        }
-
-        input:checked + .item-container & {
-          opacity: 1;
-          transform: none;
-        }
-      `}
-    >
-      <Image src={src} />
-    </Box>
-  );
-}
-
-function ItemName({ children, ...props }) {
-  const theme = useTheme();
-
-  return (
-    <Box
-      fontSize="md"
-      color="green.800"
-      transition="all 0.15s"
-      className={css`
-        .item-container:hover & {
-          opacity: 0.9;
-          font-weight: ${theme.fontWeights.medium};
-        }
-
-        input:checked + .item-container & {
-          opacity: 1;
-          font-weight: ${theme.fontWeights.bold};
-        }
-      `}
-      {...props}
-    >
-      {children}
-    </Box>
-  );
-}
diff --git a/src/ItemsPanel.js b/src/ItemsPanel.js
index 40933b7..c9d2bad 100644
--- a/src/ItemsPanel.js
+++ b/src/ItemsPanel.js
@@ -14,7 +14,7 @@ import {
 import { CSSTransition, TransitionGroup } from "react-transition-group";
 
 import { Delay, Heading1, Heading2 } from "./util";
-import { ItemListContainer, Item, ItemListSkeleton } from "./ItemList";
+import { Item, ItemListContainer, ItemListSkeleton } from "./Item";
 
 function ItemsPanel({ outfitState, loading, dispatchToOutfit }) {
   const { zonesAndItems } = outfitState;
diff --git a/src/SearchPanel.js b/src/SearchPanel.js
index eb13865..a9cc440 100644
--- a/src/SearchPanel.js
+++ b/src/SearchPanel.js
@@ -4,7 +4,7 @@ import { Box, Text, VisuallyHidden } from "@chakra-ui/core";
 import { useQuery } from "@apollo/react-hooks";
 
 import { Delay, Heading1, useDebounce } from "./util";
-import { ItemListContainer, ItemListSkeleton, Item } from "./ItemList";
+import { Item, ItemListContainer, ItemListSkeleton } from "./Item";
 import { itemAppearanceFragment } from "./OutfitPreview";
 
 function SearchPanel({