feat(design-system): FileExplorer

npm/design-system/.mocharc.json

@@ -0,0 +1,8 @@
+{
+  "watch-ignore": [
+    "./test/_test-output",
+    "node_modules"
+  ],
+  "require": "ts-node/register",
+  "exit": true
+}

npm/design-system/package.json

@@ -21,6 +21,8 @@
     "@fortawesome/free-brands-svg-icons": "5.15.2",
     "@fortawesome/free-solid-svg-icons": "5.15.2",
     "@fortawesome/react-fontawesome": "0.1.14",
+    "@iconify/icons-vscode-icons": "1.1.1",
+    "@iconify/react": "1.0.0",
     "classnames": "2.2.6",
     "debug": "4.3.2"
   },
@@ -41,6 +43,7 @@
     "babel-loader": "8.0.6",
     "css-loader": "2.1.1",
     "cypress": "0.0.0-development",
+    "mocha": "^7.0.1",
     "react": "16.8.6",
     "react-dom": "16.8.6",
     "rollup": "^2.38.5",

npm/design-system/src/components/FileExplorer/FileExplorer.module.scss

@@ -0,0 +1,48 @@
+@use '../../index.scss' as *;
+
+.nav {
+  user-select: none;
+  white-space: nowrap;
+}
+
+.ul {
+  margin-block-start: 0;
+  margin-block-end: 0;
+  margin-inline-start: 0;
+  margin-inline-end: 0;
+  padding-inline-start: 0;
+  &:before {
+    display: none;
+  }
+}
+
+.li.li {
+  padding-left: 20px;
+}
+
+
+.ul, .li {
+  position: relative;
+  list-style: none;
+  font-size: $text-s;
+  line-height: 1.6;
+}
+
+.a {
+  position: relative;
+  color: unset;
+  text-decoration: none;
+  display: inline-block;
+  width: 100%;
+  &:hover {
+    cursor: pointer;
+  }
+}
+
+.ul .ul {
+  margin-inline-start: $text-xs;
+}
+
+.isSelected, .isSelected:hover {
+  text-decoration: underline;
+}

npm/design-system/src/components/FileExplorer/FileExplorer.spec.tsx

@@ -0,0 +1,130 @@
+import { mount } from '@cypress/react'
+import React from 'react'
+import { FileExplorer, FileComponentProps, FolderComponentProps } from './FileExplorer'
+import { FileNode, makeFileHierarchy, TreeNode } from './helpers/makeFileHierarchy'
+
+import styles from './FileExplorer.module.scss'
+
+const specs: Cypress.Cypress['spec'][] = [
+  {
+    relative: 'foo/bar/foo.spec.js',
+    absolute: 'Users/code/foo/bar/foo.spec.js',
+    name: 'foo/bar/foo.spec.js',
+  },
+  {
+    relative: 'bar/foo.spec.tsx',
+    absolute: 'bar/foo.spec.tsx',
+    name: 'bar/foo.spec.tsx',
+  },
+  {
+    relative: 'merp/map.spec.ts',
+    absolute: 'merp/map.spec.ts',
+    name: 'merp/map.spec.ts',
+  },
+]
+
+interface FileExplorerTestProps {
+  clickFileStub: typeof cy.stub
+  clickFolderStub: typeof cy.stub
+}
+
+function createFileExplorer (testProps: FileExplorerTestProps): React.FC {
+  return () => {
+    const [selectedFile, setSelectedFile] = React.useState<string>()
+
+    const onFileClick = (file: FileNode) => {
+      setSelectedFile(file.absolute)
+    }
+
+    const files = makeFileHierarchy(specs.map((spec) => spec.relative))
+
+    const FileComponent: React.FC<FileComponentProps> = (props) => {
+      return (
+        <div onClick={() => {
+          testProps.clickFileStub(props.item)
+          props.onClick(props.item)
+        }}>
+          {props.item.name}
+        </div>
+      )
+    }
+
+    const FolderComponent: React.FC<FolderComponentProps> = (props) => {
+      return (
+        <div onClick={() => {
+          testProps.clickFolderStub()
+          props.onClick()
+        }}>
+          {props.item.name}
+        </div>
+      )
+    }
+
+    return (
+      <FileExplorer
+        files={files}
+        cssModule={styles}
+        selectedFile={selectedFile}
+        fileComponent={FileComponent}
+        folderComponent={FolderComponent}
+        onFileClick={onFileClick}
+      />
+    )
+  }
+}
+
+describe('FileExplorer', () => {
+  it('basic usage', () => {
+    const files: TreeNode[] = [
+      {
+        type: 'folder',
+        name: 'foo',
+        absolute: 'foo',
+        files: [
+          {
+            type: 'file',
+            name: 'bar.js',
+            absolute: 'foo/bar.js',
+          },
+        ],
+      },
+    ]
+
+    const FileComponent: React.FC<FileComponentProps> = (props) => <div>{props.item.name}</div>
+    const FolderComponent: React.FC<FolderComponentProps> = (props) => <div>{props.item.name}</div>
+
+    mount(
+      <FileExplorer
+        files={files}
+        selectedFile={undefined}
+        fileComponent={FileComponent}
+        folderComponent={FolderComponent}
+        onFileClick={() => {}}
+      />,
+    )
+  })
+
+  it('clicks file and folders', () => {
+    const clickFolderStub = cy.stub()
+    const clickFileStub = cy.stub()
+
+    const Wrapper = createFileExplorer({
+      clickFolderStub,
+      clickFileStub,
+    })
+
+    mount(<Wrapper />)
+
+    cy.get('div').contains('bar').click().then(() => {
+      expect(clickFolderStub).to.have.been.calledWith()
+    })
+
+    cy.get('div').contains('map.spec.ts').click().then(() => {
+      expect(clickFileStub).to.have.been.calledWith({
+        type: 'file',
+        absolute: 'merp/map.spec.ts',
+        name: 'map.spec.ts',
+      })
+    })
+  })
+})

npm/design-system/src/components/FileExplorer/FileExplorer.tsx

@@ -0,0 +1,177 @@
+import React from 'react'
+import cs from 'classnames'
+import { FileNode, FolderNode, TreeNode } from './helpers/makeFileHierarchy'
+
+export interface FolderComponentProps {
+  item: FolderNode
+  depth: number
+  isOpen: boolean
+  onClick: () => void
+}
+
+export interface FileComponentProps {
+  item: FileNode
+  depth: number
+  onClick: (file: FileNode) => void
+}
+
+export interface FileExplorerProps extends React.HTMLAttributes<HTMLDivElement> {
+  files: TreeNode[]
+  fileComponent: React.FC<FileComponentProps>
+  folderComponent: React.FC<FolderComponentProps>
+  selectedFile?: string
+  onFileClick: (file: FileNode) => void
+
+  // Styles. They should be a *.module.scss.
+  // TODO: Can we type these? Do we want to couple to CSS modules?
+  cssModule?: {
+    nav: any
+    ul: any
+    li: any
+    a: any
+    isSelected: any
+  }
+}
+
+export interface FileTreeProps extends FileExplorerProps {
+  depth: number
+  openFolders: Record<string, boolean>
+  style?: React.CSSProperties
+  setSelectedFile: (absolute: string) => void
+}
+
+export const FileExplorer: React.FC<FileExplorerProps> = (props) => {
+  /**
+   * Whether a folder is open or not is a **UI** concern.
+   * From a file system point of view, there is no such concept as "open" or "closed",
+   * only from a user's point of view.
+   * For this reason we save the open state as part of the UI component. The easiest
+   * way to do this is a key/value pair, mapping the absolute path of a directory to a boolean
+   *
+   * {
+   *   'foo': true,
+   *   'foo/bar': true
+   *   'foo/bar/qux': false
+   * }
+   *
+   * Every directory is set to open by default. When you add a new directory
+   * or file via your file system (eg mkdir foo/bar && touch foo/bar/hello.js) it will be added
+   * without losing the current state of open/closed directories.
+   */
+  const [openFolders, setOpenFolders] = React.useState<Record<string, boolean>>({})
+
+  React.useEffect(() => {
+    function walk (nodes: TreeNode[]) {
+      for (const node of nodes) {
+        if (node.type === 'folder') {
+          if (!(node.absolute in openFolders)) {
+            setOpenFolders({ ...openFolders, [node.absolute]: true })
+          }
+
+          walk(node.files)
+        }
+      }
+    }
+
+    walk(props.files)
+  }, [props.files, openFolders])
+
+  const setSelectedFile = (absolute: string) => {
+    setOpenFolders({ ...openFolders, [absolute]: !openFolders[absolute] })
+  }
+
+  return (
+    <nav className={cs(props.className, props.cssModule.nav)}>
+      <FileTree
+        {...props}
+        setSelectedFile={setSelectedFile}
+        openFolders={openFolders}
+        depth={0}
+      />
+    </nav>
+  )
+}
+
+export const FileTree: React.FC<FileTreeProps> = (props) => {
+  // Negative margins let the <a> tag take full width (a11y)
+  // while the <li> tag with text content can be positioned relatively
+  // This gives us HTML + cssModule-only highlight and click handling
+  const inlineStyles = {
+    a: {
+      marginLeft: `calc(-20px * ${props.depth})`,
+      width: `calc(100% + (20px * ${props.depth}))`,
+    },
+    li: {
+      marginLeft: `calc(20px * ${props.depth})`,
+    },
+  }
+
+  const fileTree = (item: TreeNode) => {
+    if (item.type !== 'folder') {
+      return
+    }
+
+    return (
+      <FileTree
+        fileComponent={props.fileComponent}
+        folderComponent={props.folderComponent}
+        openFolders={props.openFolders}
+        setSelectedFile={props.setSelectedFile}
+        onFileClick={props.onFileClick}
+        selectedFile={props.selectedFile}
+        depth={props.depth + 1}
+        cssModule={props.cssModule}
+        files={props.openFolders[item.absolute] ? item.files : []}
+      />
+    )
+  }
+
+  const renderFolder = (item: FolderNode) => {
+    return (
+      <props.folderComponent
+        depth={props.depth}
+        item={item}
+        isOpen={props.openFolders[item.absolute]}
+        onClick={() => props.setSelectedFile(item.absolute)}
+      />
+    )
+  }
+
+  const renderFile = (item: FileNode) => {
+    return (
+      <props.fileComponent
+        depth={props.depth}
+        item={item}
+        onClick={props.onFileClick}
+      />
+    )
+  }
+
+  return (
+    <ul className={props.cssModule.ul}>
+      {
+        props.files.map((item) => {
+          return (
+            <React.Fragment key={item.absolute}>
+              <a
+                style={inlineStyles.a}
+                className={cs(props.cssModule.a, {
+                  [props.cssModule.isSelected]: props.selectedFile === item.absolute,
+                })}
+                tabIndex={0}
+              >
+                <li
+                  style={{ ...props.style, ...inlineStyles.li }}
+                  className={props.cssModule.li}>
+                  {item.type === 'folder' && renderFolder(item)}
+                  {item.type === 'file' && renderFile(item)}
+                </li>
+              </a>
+              {fileTree(item)}
+            </React.Fragment>
+          )
+        })
+      }
+    </ul>
+  )
+}