@nexusmods/ui-components v4.0.0

@nexus-js/ui-components

Contents

1. Installation
2. Usage
3. Storybook
4. Contributing
5. License

Installation

This repository is currently hosted through a private Gitlab registry, and can only be installed by Nexus Mods Gitlab users. To configure your local environment to use this library, please see the link below:

Configuration guide for Gitlab package registry

After configuring your environment, you can add the library to your project using npm/yarn with the following commands

npm install @nexus-js/ui-components

OR

yarn add @nexus-js/ui-components

Usage

The library consists of a number of exported files:

• The JavaScript package is exported as a common-js module with both a development and a production build. To use suppress any development-only logging messages, set your NODE_ENV environment variable to 'production';
• The library is written in TypeScript, so there's no need for a separate @types module;
• We also provide a CSS bundle for styling. Our CSS is written using Tailwind, so for convenience we provide a number of exported bundle formats: unprocessed.css: includes the CSS before Tailwind processing, to allow for config customisation - recommended if you're using Tailwind and have custom config you want to use; processed.css: includes the CSS after Tailwind processing, ready to include in any project using our preset styles; styles/index.scss: contains some SCSS variables used to define the CSS Custom Properties used by our Tailwind Config; tailwind.config.js: a Tailwind Preset with our configuration that you can use in the presets value of your own Tailwind config - recommended if you're using unprocessed.css;

An example of using our unprocessed CSS would be as follows:

/**
 * App.tsx
 */
import React, { FunctionComponent } from 'react';

// Import components from our library
import { Button } from '@nexus-js/ui-components';

// Import our SCSS variables to define the CSS Custom Properties required by our Tailwind config preset
import '@nexus-js/ui-components/dist/styles/index.scss';

// Import styles which will include our style bundle (see below)
import './styles.css';

const Example: FunctionComponent = () => {
  return <Button>Click me</Button>
};

/**
 * styles.css
 */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

// Import unprocessed CSS which will be processed by Tailwind by your build job
@import "@nexus-js/ui-components/dist/unprocessed.css";

/**
 * tailwind.config.js
 */
module.exports = {
  // Use our config as a preset to access our predefined styles - requires Tailwind 1.9 or greater
  presets: [require('@nexus-js/ui-components/dist/tailwind.config.js')],
};

AbstractIconProvider

This library exports a component called AbstractIconProvider. By itself, it doesn't do anything, but it can be wrapped to provide a generic icon component with a set of expected behaviours. An example wrapper can be found in .storybook/helpers/mdi-icon-provider.helper.ts, which uses the @mdi/js and @mdi/react libraries to serve a set of icons.

A number of components exported by this library make us of the useIconContext hook to retrieve the Icon component passed to this provider, so you should be sure to wrap your application in an implementation of this icon provider. Our Storybook uses the MdiIconProvider to give an example of how this system should work, and any stories being written can use this icon set, as there is a global decorator set up to wrap all stories in the MdiIconProvider.

Storybook

You can see examples of the style and functionality of all of our components in our Storybook (currently only exposed through the Nexus Mods VPN).

Contributing

To contribute to this project, clone via git@gitlab.nexdev.uk:nexus-js/ui-components.git. The structure of the repostory is as follows:

• .storybook: contains Storybook configuration - stories are colocated with components;
• deploy: contains .sh files used in the build process;
• src: all code is kept here using the following format:
  • components: components are kept in folders here, alongside their tests, stories and styles - folder format will be described below;
  • hooks: any hooks that aren't associated with a context or a component live here;
  • providers: context providers live here, following the same folder pattern as components;
  • styles: top-level CSS files, including the SCSS used to define CSS Custom Properties;
  • utils: shared utilities that don't belong to any one component, hook or provider;
  • index.ts: top-level file that re-exports all components and types required by consumers of the library;
• tailwind: tailwind config files, split out to be more readable;
• types: custom types or type extensions for external libraries or file formats.

Component folders

Any new component must use the following folder structure, using a fictional component as an example:

<Generic>
  <SubGeneric/>
</Generic>

generic.component.tsx     // [REQUIRED] The main component file containing primarily any hook and/or api logic and can also contain the view
generic.stories.tsx       // [REQUIRED] The Storybook stories - can be moved to a /stories folder if this file gets too big
generic.tests.jsx         // [REQUIRED] The test file - we use .jsx for tests to avoid any type errors with mocks
generic.styles.css        // Custom styles, using Tailwind @apply syntax where possible, to adhere to our Tailwind config variables
generic.presentation.tsx  // Having trouble testing or faking hooks/api? House the JSX here with just the UI logic to make testing the component logic simpler

sub-components/           // Contains all isolated sub-components used the root the same structure as above excluding the index.ts. these do not need to be exported in the `main.ts`

index.ts                  // Should re-export the component to prevent long-winded imports in other files

Merge Requests

When submitting a merge request, please use the Default Merge Request Template. This will provide a checklist of tasks that you should look over before submitting. Assign the MR to yourself, choose a reviewer, and be sure to add the Stage::Review label.

License

GNU GPL-3.0-or-later © themagickoala