@pearson-ux/list NPM

Project Documentation

This document provides information on how to install dependencies, edit token styles, use the pearson-list component, fire functions on button clicks, and create a new release of the project.

Installing Dependencies

Before you begin, make sure you have the following installed:

Node.js and npm: Ensure Node.js and npm are installed on your machine. You can verify this by running:
```
node -v
npm -v
```
npm Account: Ensure you have an npm account and are logged in. You can log in using:
```
npm login
```

Once these prerequisites are met, install the project dependencies by running:

npm install

This command will install all necessary packages as defined in the package.json file.

Editing Token Styles

The pearson-list component uses token styles that are defined in the @pearson-ux/master-tokens package. However, customizations and overrides are done via the customTokens.js file.

To modify these styles:

Open the customTokens.js file located in the project directory.
The getCustomTokens function returns an object containing the styles used by the component. You can modify the values in this object to change the appearance of the component.

Example of `customTokens.js`:

export const getCustomTokens = (tokenModule = {}, isDarkMode = false) => {
    return {
        listItemBackground: isDarkMode
            ? tokenModule.TokenColorUi04
            : tokenModule.TokenColorUi02,
        listItemTextColor: isDarkMode
            ? tokenModule.TokenColorTextPrimaryInverse
            : tokenModule.TokenColorTextPrimary,
        listItemButtonHover: isDarkMode
            ? tokenModule.TokenColorInteractiveSecondaryInverseHover
            : tokenModule.TokenColorInteractiveSecondaryHover,
        listItemButtonHoverText: isDarkMode
            ? tokenModule.TokenColorInteractiveFocusField
            : tokenModule.TokenColorTextPrimaryInverse,
        listItemButtonBackground: tokenModule.TokenColorInteractiveSecondary,
        listItemButtonTextColor: tokenModule.TokenColorTextPrimaryInverse,
        listItemButtonDisabled: tokenModule.TokenColorInteractive01Disabled,
        listItemButtonDisabledText: tokenModule.TokenColorInteractive03Disabled,
        listItemBoxShadow: '0',
        spacingExtraSmall: '4px',
        spacingSmall: '8px',
        spacingMedium: '12px',
        spacingLarge: '24px',
        fontFamilyOpenSans: `'Open Sans', sans-serif`,
        fontWeightNormal: 400,
        lineHeightSmall: '22px',
        lineHeightMedium: '24px',
        lineHeightLarge: '28px',

        listItemBorderColor: isDarkMode
            ? tokenModule.TokenColorUiBorder02
            : tokenModule.TokenColorUiBorder01,

        listItemTitleFontSize: '18px',
        listItemTitleFontWeight: 700,
        listItemTitleLineHeight: '28px',

        listItemDescriptionFontSize: '14px',
        listItemDescriptionFontWeight: 400,
        listItemDescriptionLineHeight: '22px',

        listItemButtonFontSize: '16px',
        listItemButtonFontWeight: 400,
        listItemButtonLineHeight: '20px',
    };
};

By modifying the properties in the customTokens.js file, you can control the styling of the pearson-list component.

Usage

The pearson-list component allows you to create a list with different themes and custom content. The component requires a theme property to be specified, with three available themes to choose from:

ELL
p-com
p-plus

Example Usage:

<pearson-list theme="p-plus">
    <div label="Label 1" description="Description 1" button-text="Button"></div>
    <div label="Label 2" description="Description 2" button-text="Button"></div>
</pearson-list>

Changing the Labels and Buttons

Each list item can have custom labels and button text by using the label, description, and button-text attributes on the child div elements.

Example:

<pearson-list theme="p-plus">
    <div label="Custom Label 1" description="Custom Description 1" button-text="Custom Button 1"></div>
    <div label="Custom Label 2" description="Custom Description 2" button-text="Custom Button 2"></div>
</pearson-list>

In this example, the labels and buttons of the list items will be customized as per the provided attributes.

Handling Button Clicks

You can assign functions to handle button clicks within the pearson-list component by setting a function on the element instance. This is useful when you have multiple lists on the same page and need different behaviors for each.

Example of Assigning a Function:

<pearson-list theme="ell" id="ellList">
    <div label="Label 1" description="Description 1" button-text="Button"></div>
</pearson-list>

<pearson-list theme="p-com" id="pcomList">
    <div label="Label 1" description="Description 1" button-text="Button"></div>
    <div label="Label 2" description="Description 2" button-text="Button"></div>
</pearson-list>

<script>
    // Assign a function to handle clicks for the ELL Theme list
    document.getElementById('ellList').onButtonClick = function(index) {
        console.log('ELL Theme: Button clicked at index', index);
        // Additional logic for ELL Theme
    };

    // Assign a function to handle clicks for the P-com Theme list
    document.getElementById('pcomList').onButtonClick = function(index) {
        console.log('P-com Theme: Button clicked at index', index);
        // Additional logic for P-com Theme
    };
</script>

Explanation:

The onButtonClick function is assigned to each pearson-list instance, allowing you to handle button clicks individually for each list.

Steps to Release

Update the Version Number

The release process starts by updating the version number in package.json. This is done automatically by the release script. You must specify the new version number as an argument when running the script.

Example: To release version 1.0.1, run:

node release.js 1.0.1

Run the Release Script

The release script will:

Update the package.json version.
Create a release directory.
Modify and copy necessary files (list.js, customTokens.js, README.md, tokenHelper.js, package.json).
Update paths in list.js and tokenHelper.js.
Copy the @pearson-ux directory from node_modules.
Publish the release directory to npm.
Clean up the release directory after publishing.

Example command:

node release.js 1.0.1

Publish the Release to npm

The script will automatically publish the contents of the release directory to npm. Ensure you are logged in to npm before running the script.

If you need to manually publish, you can run:

cd release
npm publish

Clean Up

After a successful release, the release directory is automatically deleted by the script. If needed, you can manually delete it using:

rm -rf release

Troubleshooting

npm publish failed:
- If the npm publish command fails, check the error message for details. Common issues include incorrect npm credentials or network problems.
Version Conflict:
- If the specified version already exists on npm, you will need to increment the version number and try again.

Contributing

Please follow the established guidelines for contributing to the project. Before creating a pull request, ensure all tests pass and the code is formatted correctly.