SYN-library

⭐ Getting started

This project uses node 20

Run npm ci to set up the packages required.

Run npm run build to build the project.

Run npm run storybook to view the UI libraries Storybook documentation.

🦋 Changesets

This project uses changesets to manage the changelog, versioning and publishing to npm. A changeset is a small file that records a change and helps automate versioning.

To create a changeset, run npx changeset after making a change.

This will prompt you to specify the type of change (follow semantic versioning):

• Patch: For backwards compatible bug fixes
• Minor: For adding functionality in a backwards compatible manner
• Major: For incompatible API changes (breaking changes)

You will then be asked for a summary that will be included in the changelog. This should include the Jira reference with the following structure:
[[ABC-123](https://synanetics.atlassian.net/browse/ABC-123)] Description of change

A changeset file will be created within the .changeset directory. Ensure that this file is committed and pushed as part of your PR.

Versioning and Publishing

The SYN-library is published to the @synanetics npm repo.

1. When a PR with a changeset is merged into the main branch, the GitHub release workflow automatically creates a new PR titled "Version Packages". This PR will:
   • Remove processed changeset files
   • Update the changelog
   • Bump the package version based on the changes
2. Once the 'Version Packages' PR is merged, the GitHub release workflow will run again, which publishes the new package version to npm automatically.

🌀 Publishing to Chromatic

The storybook is published on Chromatic

This should be done as part of the chore task that updates the published version so that the published storybook matches the current npm package.

You can redeploy locally or in CI with npm run chromatic.

ℹ The project token was added to the script via the --project-token flag. If you're running Chromatic via continuous integration, we recommend setting the CHROMATIC_PROJECT_TOKEN environment variable in your CI environment. You can then remove the --project-token from your package.json script.

We should perhaps do this!

🖼️ Icons

The library's icons predominantly come from Google's Material Symbols and Icons.

Adding a new icon

1. Ensure the icon has been added to the SYN Library's Figma Icon's.
2. On Figma, right click the icon you want to add. You should see a purple 20 x 20 bounding box appear around it.
3. Select Copy as > Copy as SVG.
4. Create a file in the src/icons folder with your new icon name. It should follow the existing file name convention, [Name]Icon.tsx.
5. A standard icon should receive at least one prop, size. This number will dictate the height and width of the icon.

Use the following template to structure your icon:

import React from "react"

import { IconProps } from "./IconProps"

export const MyIcon = ({ size = 20 }: IconProps) => {
  return (
    <svg fill="none" height={size} viewBox="0 0 20 20" width={size} xmlns="http://www.w3.org/2000/svg">
      {*/ <mask> */}
      {*/ <g> */}
    </svg>
  )
}

6. Your <svg> will likely have a <path> tag within it, with the fill attribute having a hardcoded hex value (likely to be #1E2428). Change this to fill="currentColor".
7. Export your new icon from the icon folder's barrel file, src/icons/index.ts
8. Viewing the Icons story on Storybook should show all icons, including your new one.
9. Scroll to the bottom of the icon's Storybook page and change the color value using the colour wheel. Your icon should change colour.

💻 Local Project Development

You can simultaneously develop this library alongside another local project.

1. Navigate to the root directory of this UI library and run npm link.
2. Go to the root directory of your local project and run npm link @synanetics/syn-library.
3. Remember to run npm run build in the library if you make any changes, to ensure your project is using the latest version. Updates should be reflected in your local project immediately.

You will need to re-link the packages if you install other dependencies at any point during local development.

You want to unlink the local instance of the package via:

npm unlink --no-save @synanetics/syn-library

If you have made changes to the UI library and errors occur similar to the following:

SyntaxError: The requested module ABC does not provide an export named 'xyz'

Restarting WSL and VS Code will likely resolve this issue.

🧪 Testing

React Testing Library, Jest & Axe

Each component has a corresponding [Name].test.tsx within it's folder.

React Testing Library is combined with jest-axe to run unit tests and prevent accessibility errors.

To manually run all tests, run npm run test:unit.

Playwright

Playwright is used for integration tests.

Running Playwright tests

Run npm run test:integration

⚙️ Installing and Usage

1. Install via npm i @synanetics/syn-library
2. At your applications root scss file, import the core SCSS file via @use "@synanetics/syn-library/core";
3. Import the desired theme SCSS file using one of the following:

Synanetics: @use "@synanetics/syn-library/synanetics" BCU: @use "@synanetics/syn-library/bcu" Interweave: @use "@synanetics/syn-library/interweave" NHS (WIP): @use "@synanetics/syn-library/nhs" SORA: @use "@synanetics/syn-library/sora"

4. Ensure the fonts are installed for each theme by adding the correct link to the html head.

Synanetics: Zilla Slab, Nirmit BCU: Calibri Interweave: Nunito, Open sans NHS (WIP): Arial SORA: Roboto, Poppins

5. Then, anywhere in your application, you can import the required components e.g. import { Button } from "@synanetics/syn-library";