@simpleview/cms-component-library

CMS Component Library

Simpleview CMS Component Library

Quick Start

1. Install NodeJS

   For Powershell: Download the Windows installer (LTS version)

   For WSL/Ubuntu: Run the commands below

   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

2. Fork this repository

   Click the "Fork" button at the top right of this page

3. Clone your fork to your local machine

   git clone ...
   cd cms-component-library
   

4. Install Dependencies

   npm install
   

5. Configure VS Code

   Download the ESLint extension for VS Code.

   Open your command palette (Ctrl+Shift+P on Windows and Cmd+Shift+P on Mac) and search for settings. Select the "Preferences: Open Settings (JSON)" option.

   Add the following JSON block to your settings.json file:

   "eslint.validate": [
       "javascript",
       "javascriptreact",
       "typescript",
       "typescriptreact",
     ],
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true,
     },
   

6. Start Storybook

   npm run storybook
   

   Visit http://localhost:6006 on your local machine

NPM Scripts

• storybook: Starts up Storybook
• build-storybook: Builds storybook for production (GitHub Pages)
• code-quality: Run type-check, lint, and prettier
• type-check: Run TypeScript against all code to check for type errors
• lint: Lint all code, fix anything that can be fixed by eslint in the process
• prettier: Format all code, overwrite files
• test: Run all tests
• build: Build NPM Package to dist folder
• publish: Publish NPM release

Structure

• .storybook: Configuration for Storybook
• __MOCKS__: Jest mocks, used to stub out API or filesystem calls - Learn More
• src: Main source code path
  • index.tsx: Main export for NPM package, if a component is not exported here, it won't be in the NPM package (More on NPM below)
  • components: React components and their corresponding CSS files
    • ComponentName/ComponetName.spec.tsx: Tests for ComponentName component (More on tests below)
    • ComponentName/ComponentName.stories.tsx: Stories for ComponentName componet. (More on stories below)
    • ComponentName.module.css: CSS styles for ComponentName
  • styles: Global CSS files
    • reboot.css: Cross-browser default styles reboot
    • swatches.css: Global CSS variables (formerly variables.css)
  • hooks: Path for all custom hooks
  • types: Path for all shared types
  • lib: Old SV libraries converted to TypeScript
  • utils: Generic re-usable utilities
• .eslintrc.yml: ESLint configuration
• .prettierrc: Prettier configuration
• jest.config.ts: Jest configuration
• jest.setup.ts: Jest setup (runs before all tests)

Unit Testing

We use Jest and React Testing Library to unit test every component.

As an example of a basic test, here we are testing the Link component using the getByText query:

import React from 'react';
import { render } from '@testing-library/react'; // react-testing-library
// We do not need to import Jest, when we run tests
// it is Jest that runs these files, so all Jest
// functions are implicit

import Link from '../Link'; // This is the component we are testing

// We start with `describe`, we are describing our Link component
describe('Link Component', () => {
	// We expect that `it` `Renders Correctly`, you can have
	// multiple `it` blocks if your component is more complex
	// and requires testing different scenarios
	it('Renders Correctly', () => {
		// Here we are defining some variables to use as props
		// for the component
		const to = {
			url: 'https://simplevieweinc.com/',
			target: '_blank',
		};
		const childText = 'test text';
		// This is an extra prop, we also want to make sure they are tested,
		// check the Link component to see where the extra props are passed
		const rel = 'noopener noreferrer';

		// We get any queries we want to use (`getByText` here) from the 
		// `render` function of react-testing-library, and pass in our
		// component with the mock data above, check the documentation
		// for react-testing-library for more available queries
		const { getByText } = render(
			<Link
				to={to}
				rel={rel}
			>
				{childText}
			</Link>,
		);

		// We should see the test within `childText` in the rendered component
		const linkElement = getByText(childText);

		// We expect to have found the element rendered by our component
		expect(linkElement).toBeDefined();
        
		// We expect the `target`, `href`, and `rel` attributes to be
		// added to the element as defined by the Link component. Check
		// the Jest documentation for more on `expect` Matchers.
		expect(linkElement).toHaveProperty('target', to.target);
		expect(linkElement).toHaveProperty('href', to.url);
		expect(linkElement).toHaveProperty('rel', rel);
	});
});

Stories

Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation.

Here is an example of a story for our Link component:

import React from 'react';
import { Link } from '../components';

// The title here translates to the story `Link` in the accordion `Atoms`
export default {
	title: 'Atoms/Link',
	component: Link,
};

// Render the Link component
function Story(props) {
	return <Link {...props}>click me</Link>;
}

// `Primary` is a layout displayed in Storybook,
// we can define multiple layouts if needed.
// The args passed to primary are the props
// that the rendered component will receive.
export const Primary = Story.bind({});
Primary.args = {
	to: {
		url: 'https://google.com/',
		target: '_blank',
	},
};

NPM Package

See the NPM Release Documentation for instructions on deploying new versions to NPM.

Refernces

• Jest
  • Matchers
  • Mocks
• React Testing Library
  • API
  • Queries Cheatsheet
  • React Cheatsheet
• Storybook
  • Concept
  • How to write stories