Set Up

#

Clone repository, install dependencies, and run the dev script to start the docs and playroom sites.

gh repo clone @ensdomains/thorin
yarn
yarn dev

Component Groups

#

Components are organized in folders according to the Atomic Design Methodology.

Atoms serve as the foundational building blocks that comprise all our user interfaces. These atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional.

Molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule.

Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms. These organisms form distinct sections of an interface.

Adding Components

#

Adding a component requires adding and modifying several files. The different steps to adding a component are:

The react component should be named using pascal case convention (e.g. PascalCase). The react component file should use the component name with a .tsx file extension. It should be added to a folder named as the component name and nested in the Component Group folder at components/src/components.

The react component test file should have the same name as the component a .test.tsx file extension. It should be located in the same directory as the component file.

The react component and type should be exported in an index file in the same directory as the component file. If a generic Props type was used, export it using an alias.

export { ComponentName } from './ComponentName'
export type { Props as ComponentNameProps } from './ComponentName'

The react component should be added to the list of exports in the index file located in the Component Group folder in components/src/components. Only the react component needs to be exported.

The component mdx file should have the same name as the react component with a .docs.mdx file extension. It should be added to the Component Group folder in docs/src/reference/mdx.

The component snippets file should have the same name as the react component with a .snippets.tsx file extension. It should be added to the Component Group folder in docs/src/reference/snippets.

Add the component to the module export test located at components/src/index.test.tsx.

Scaffolding Components

#

A generator script is available that will perform items 1 - 6 of Adding Components. Adding the component to the module export test must be done manually. Access the script using:

yarn gen:component

Style Guidelines

#

Use functional components with hooks and avoid using inline styles.

Add displayName to component. This is neccessary for playroom to generate snippets from code.

const Component = () => <div />

Component.displayName = 'Component'

When using styled components prefix property names with $ to avoid passing component props directly to styled components.

const Container = styled.div<{
  $property: string
}>`
  ${({ $property }) => ``}
`

Playroom uses react-element-to-jsx-string to convert a react component into a string which can be used by playroom. In certain situations it is not able to accurately convert the element, such as if the components' children includes a function.

If you are having problems with your snippet in playroom, convert your snippet code to a single line string. Do not use backslash to break the string into multiple lines.

export const snippets: Snippet[] = [
  {
    name: 'Basic',
    code: '<FileInput>{(context) => context.name ? <div>{context.name}</div> : <div>Attach a file</div>}</FileInput>',
  },
]

When you need to import a component within the docs/ folder, link to components from @ensdomains/thorin.

import { Field } from '@ensdomains/thorin'

For updates to components to appear in files in the docs/ folder, you will first need to build the components using:

yarn build:components

Adding Icons

#

Add a .svg file in pascal case to the icons folder and run:

yarn gen:icons

All files in the icons directory are automatically converted to React components and exported for use. Generated icons should follow a 24x24 bounding box.

Test

#

yarn test

Build

#

To build the comopnents in the components library use:

yarn build:components

To build the entire project use:

yarn build

Publishing New Versions

#

Create a new release on GitHub with a tag that follows semantic versioning. Publishing a release triggers a workflow for building, testing, and pushing to npm.

Common Issues

#

Update the component using yarn build:component and reload the page after the script has completed.

Check if displayName has been added to component. If not, then you may need to conver the snippet to a string. See the snippets section for more details.

Check if the module or component has been exported in docs/src/playroom/components.ts.

Check that the component or module is included in the scope property of the LiveProvider component in docs/src/components/CodePreview/CodePreview.tsx.

You can customize the format of the type value by adding conditions to the function formatPropType in docs/src/components/PropsTable.tsx.