Building the components locally

1. Run npm install inside the root directory.
2. Run npm run sandbox. This will run the sandbox environment located in src/sandbox, where you can import and test all of the components (the source code for all components is located in src/components).
3. Optionally, you can run npm run documentation to view the current documentation for existing components and use it for testing purposes.

Running the components in Portal

1. Navigate to the root directory.
2. Run npm install.
3. Run npm run build.
4. Run npm link.
5. Go to Portal.Web.Frontend directory.
6. Add the following prop in the vite.config.mts file under defineConfig:

optimizeDeps: {
    exclude: ['@talxis/react-components']
}

7. Delete node_modules
8. Run npm install
9. Run npm link @talxis/react-components
10. Run npm start

These steps only need to be done once. If you want to see any future changes you made in Base Control package, you need to run npm run build in Base Control root directory and Portal will automatically reload with your changes applied.

NOTE: If Portal starts to complain that there is a mismatch in React versions, you need to delete the react and react-dom packages from the node_modules folder in Base Controls

Don't forget to revert the vite.config.mts file to the original version before pushing any changes to the Portal repo!

Developing new component

Every newly created component should respect the Fluent UI design pattern. However, not all Fluent UI components are unified in their looks and functionality (for example error messages). To overcome this, we have created a separate interface for each core component functionality. Each interface has a guideline on how it's look and functionality should be implemented. Please familiarize yourself with the guidelines (also look at existing components that implement them) and follow them.

Guidelines

There are few guidelines that need to be followed when developing new components:

Code Structure

1. All the code for the newly developed component has to be located in the src/components/component_name folder.
2. The component_name folder should contain the following files: index.tsx, styles.ts (optional). The index.tsx file should contain the component's code. The styles.ts file should contain component's styling using the mergeStyles library. This is currently the only supported styling approach for scoping reasons.
3. While writing the styles, keep in mind that all classes should be prefixed with the component's name eg .TALXIS__textfield. Any other classes within the component should follow the same prefix, eg .TALXIS__textfield__button. As for naming conventions, we are using the BEM Naming System.

Visuals and functionality

A newly developed component should, apart from the new features specific to itself also include basic features and looks that are already implemented in the existing components. For example, while developing a component that has some input as it's base, the component should also have a borderless and read only variant (and also few other functionalities). To make the implementation easier, each component can decide which features it wants to include by implementing corresponding interfaces. Currently, we support these interfaces:

1. IDisabled - for components that can be disabled, meaning that they can't be interacted with.

2. IReadOnly - for components that have a read only variant. The read only mode should disable any attempts to change the component's value, but any action buttons present (apart for buttons that change the component's value) should be enabled.

3. IPrefix - for components, that can have an N number of action buttons before component's main content. These buttons should be active by default in read only mode and disabled while the component is in disabled state. Please refer to the TextField component for guidance on how to implement this interface.

4. ISuffix - for components, that can have an N number of action buttons after component's main content. These buttons should be active by default in read only mode and disabled while the component is in disabled state Please refer to the TextField component for guidance on how to implement this interface.

5. ICopyButton - for components that have a copy button. The copy button should be active by default in read only mode and disabled while the component is in disabled state. Also, the copy button should only be visible when the component's value is not empty (eg, if there is something to copy). If used along with the ISuffix interface, the copy button should be a part of the suffix items.

6. IDeleteButton - for components that have a delete button. The delete button should not be visible when the component's value is empty (eg, if there is nothing to delete) or the component is in the read only mode. The button should also appear disabled while the component is in disabled state. If used along with the ISuffix interface, the delete button should be a part of the suffix items. It should also be the last item. Remember that all buttons (this includes IPrefix, ISuffix, ICopyButton and IDeleteButton) should have a fade in animation if the showOnlyOnHover prop is set to true!

7. IErrorMessage - for components that can show an error message. You can you the predefined <ErrorMessage> component to make this implementation easier. The component should also have a red border around it if possible (even in disabled state).

Since we often have to create customer specific CSS, we should always mention the component's state in the root CSS class in situations where it makes sense. For example, we might encounter a situation where we want to change the border color of a component when it's disabled. In this case, we should generate the following CSS class: .TALXIS__textfield--disabled when the component is disabled and so on. Please refer to existing components to see the class generation logic for different states.

NOTE: You can also refer the state within the data-attribute of the root element, eg. data-disabled={true}.

Of course, not every component has to implement all of the interfaces. That's why It's ideal to consult the component's functionality with other guys (Zdenek Srejber, Tomas Prokop, Jan Hajek, Dominik Brych) in the team to see which functionalitites are needed and which ones are not.

Documentation

Every new developed component has to have a documentation page. The documentation page should describe the component's functionality and how to use it. The documentation is handled by a framework called Storybook. While creating a documentation for your component, you should refer to their documentation as well as to our documentation for existing components.

Notes

Full docs can be found here. If you encounter any problems or bugs in the existing components, please refer to Dominik Brych.