@hcl-software/enchanted-react-components

中文文档
3.0.3发布于 2026/11/02Apache-2.0TypeScriptCommonJS构建来源已验证近 30 天下载 4845

Enchanted React Components is a collection of components that are used in HCL Software products.

原始使用文档
文档目录10 节
  1. Usage
  2. Development
  3. NPM targets
  4. Component structure
  5. Module exporting best practices
  6. Theming
  7. RTL support
  8. Tokenizing - Typographies and Colors
  9. Styling overrides
  10. Storybook

@hcl-software/enchanted-react-components

Enchanted React Components is a collection of ui components that are being used in HCL Software products. This package depends on the Material UI Component Library.

(C) 2024 HCL America Inc. Apache-2.0 license https://www.apache.org/licenses/LICENSE-2.0

npm

Usage

npm install @hcl-software/enchanted-react-components
import Button, { ButtonVariants } from '@hcl-software/enchanted-react-components/dist/Button/Button';

...

return (
  <Button
    id="button-id"
    variant={ButtonVariants.CONTAINED}
    onClick={() => {
      console.log('click');
    }}
  >
    Button
  </Button>,
);

Development

NPM targets

We provide the following utility development commands:

takscommanddescription
installnpm ciInitial installation of the project dependencies. Run this to get started.
cleanrm -rf node_modules and rm -rf distRemoves all node_modules etc
build libnpm run buildBuilds the package
lintnpm run lintRun the linting task
build storybooknpm run build-storybookBuilds a storybook
storybooknpm run storybookRuns a storybook instance
unit and integrationnpm run testRun unit and integration tests
storyshotsnpm run test-storyshotsRun storyshots test. The env parameter DONT_EXIT_ON_DIFF=true provides a feature that the tests are not failing if some deviations are detected.

Component structure

Atomic component

An atomic component is the smallest unit of a component. For example, a Button or Panel.

Composite component

A composite component is a combination of atomic components to create a bigger component. For example a specific Form.

Prerequisite component

A prerequisite component is a component which only exists to be consumed in higher level components. This component should not be used standalone.

Module exporting best practices

  • Each component folder structure has its own index.ts file acting as a local module which exports the default and named exports.
  • The src folder contains a global index.ts file which exports the components globally and points to each component folder's local index.ts file.
  • Ensure newly created components are exported globally for concise and readable exports when using the Enchanted React Component library across projects.

Theming

The library supports a LightNeutralGrey and LightCoolGrey theme. In the future a DarkNeutralGrey and DarkCoolGrey theme should also be supported. The LightNeutralGrey and LightCoolGrey theme can be create via the createEnchantedTheme() method.

// e.g.
createEnchantedTheme(ThemeDirectionType.RTL, ThemeModeType.LIGHT_COOL_GREY);
// or
createEnchantedTheme(ThemeDirectionType.LTR, ThemeModeType.LIGHT_NEUTRAL_GREY);

The ThemeProvider needs to be the first component in the component hierarchy.

import { ThemeProvider } from '@mui/material/styles';
import { ThemeDirectionType, ThemeModeType, createEnchantedTheme } from '@hcl-software/enchanted-react-components/dist/theme';

const enchantedTheme = createEnchantedTheme(ThemeDirectionType.LTR, ThemeModeType.LIGHT_NEUTRAL_GREY);

return (
  <ThemeProvider theme={enchantedTheme}>
    ...
  </ThemeProvider>
)

RTL support

The library fully supports a RTL mode. Each new implemented component also needs to support the RTL mode.


NOTE:

The library uses stylis-plugin-rtl and stylis to achieve RTL support. We have locked the dependency requirement of this library for stylis at 4.0.13 due to stylis's own maintenance issues. Please ensure that this is the deduped version of the dependency in your project's dependency tree.

  • To make sure your project's stylis version is at 4.0.13, first, run npm ls stylis to list down dependencies with a sub-dependency on stylis.
  • Next, uninstall and reinstall these dependencies one by one so that on reinstall, the package.json override config will tell npm to lock the dependency of stylis at 4.0.13. For example, for the dependency stylis-plugin-rtl with a subdependency on stylis, run npm uninstall stylis-plugin-rtl.
  • Then finally, run npm install stylis-plugin-rtl, to be safe, you may want to specify the semver here to the one in package.json npm install stylist-plugin-rtl@{insert-semantic-version-here}.

A ltr and rtl theme can be created via the createEnchantedTheme() method.

For 'rtl' support the DirectionStyleProvider is also needed. This component should wrap the ThemeProvider. Here is a short example, how this could look like:

import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

import DirectionStyleProvider from '@hcl-software/enchanted-react-components/dist/DirectionStyleProvider';
import { ThemeDirectionType, ThemeModeType, createEnchantedTheme } from '@hcl-software/enchanted-react-components/dist/theme';

const themeDirection = ThemeDirectionType.LTR;
const enchantedTheme = createEnchantedTheme(themeDirection, ThemeModeType.LIGHT_NEUTRAL_GREY);

return (
  <DirectionStyleProvider direction={themeDirection}>
    <ThemeProvider theme={enchantedTheme}>
      <div dir={themeDirection}>
        <CssBaseline />
        <App />
      </div>
    </ThemeProvider>
  </DirectionStyleProvider>
)

Note: <CssBaseline /> will inject some global styles into the page. If this is not desired, wrap your app in <ScopedCssBaseline> instead.
For example:

import ScopedCssBaseline from '@mui/material/ScopedCssBaseline';
...
  <DirectionStyleProvider direction={themeDirection}>
    <ThemeProvider theme={enchantedTheme}>
      <div dir={themeDirection}>
        <ScopedCssBaseline>
          <App />
        </ScopedCssBaseline>
      </div>
    </ThemeProvider>
  </DirectionStyleProvider>

Tokenizing - Typographies and Colors

Typographies

The default Material UI Typography variant was extend with four additional variants. The typography variants names are aligned with the design typography names.

Default Material UI variants:

  • h1
  • h2
  • h3
  • h4
  • h5
  • h6
  • subtitle1
  • subtitle2
  • body1
  • body1bold
  • body1italic
  • body2
  • body2bold
  • body2italic
  • caption

Extended variants:

  • body1bold
  • body1italic
  • body2bold
  • body2italic

The Inter, sans-serif is currently configured as the default font family for all typographies.

Colors

All used colors have been tokenized with a specific name. Those color tokens are aligned with the design color tokens.

Styling overrides

Material UI offers four different ways to override component specific stylings:

Within the enchanted react component library we limit those options to the following three:

  • One-off customization > sx prop
  • Reusable component
  • Global theme override

The preferred and mandatory method for CSS customization is the Global theme override. The alternatives shall only be used if the Global theme override is not working for the specific problem.

One-off customization

More information about the sx prop can be found here.

Reusable component

More information about the styled() method can be found here.

export const StyledInputLabel = styled(MuiInputLabel)((theme) => {
  return {
    ...theme.theme.typography.subtitle2,
    color: theme.theme.palette.text.secondary,
    margin: '0px',
    span: {
      paddingRight: '4px',
    },
    ...
  };
});

Global theme override

More information about the theme components override can be found here.

The basic idea is to add to each component a specific method (getMui<COMP-NAME>ThemeOverrides) which is collecting all needed CSS adjustments. This method should have this logic:

/**
 * Override out of the box styling from mui to align with designer theme
 * @returns override <COMP-NAME> component styles and prop
 */
export const getMui<COMP-NAME>ThemeOverrides = (): Components<Omit<Theme, 'components'>> => {
  return {
    Mui<COMP-NAME>: {
      styleOverrides: {
        root: ({ ownerState, theme }) => {
          return ({
            backgroundColor: 'red', // this is only an example
          });
        },
      },
    },
  };
};

The output can than be added to the components attribute of the ThemeOptions like that.

  const themeOptions: ThemeOptions = {
    components: {
      ...getMui<COMP-NAME>ThemeOverrides(),
    },
    ...
  };

NOTE: Each MUI component can only be one time declared due to the fact that the Global Theme Override accepts one key-value per MUI component.

Storybook

For isolated building of the enchanted react components library we are using Storybook. Storybook helps us to provide, testing, documentation, and review the enchanted components in an industrial standard way. Storybook is open source and free and is it used by thousands of teams.

Currently we have grouped our components in five different section. Under each group the component are placed.

  • Navigation
  • Feedback
  • Inputs
  • Data Display
  • Surfaces

A Introduction page is also part of each storybook instance.

Each component should have two specific component examples:

  • Interactive Example > The controls section are enabled and the components can be tested in different variations/permutations.
  • Visual test > The controls section are disabled. This example is only used by the visual test (storyshots), to identify styling changes. This example provide the majority of reasonable variations/permutations of a component on a single page.

Visual testing (snapshot testing)

This process is detecting some UI diviations and it will create some comparison screenshots.

Run it locally
  • Clean the storyshots image folder ./src/__tests__/unit/__image_snapshots__

  • Run storybook locally.

    npm run storybook
    
  • Create the baseline set. All images will be stored under the folder ./src/__tests__/unit/__image_snapshots__

    npm run test-storyshots
    
  • Do some UI changes, like: adjust the primary color or increase the size of border, padding, marging.

  • Run the test-storyshots command again to get all UI diviations. The detected diviations will be store under the folder ./src/__tests__/unit/__image_snapshots__/__diff_output__

    npm run test-storyshots
    

版本与发布记录

@hcl-software/enchanted-react-components 共发布 26 个版本,首次发布于 2024/04/22;过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.0.3latest2026/11/0215 天前
3.0.22026/10/091 个月前
3.0.12026/10/071 个月前
3.0.02026/09/241 个月前
2.10.22026/09/231 个月前
2.10.12026/09/072 个月前

关于 @hcl-software/enchanted-react-components 的常见问题

@hcl-software/enchanted-react-components 是什么?

Enchanted React Components is a collection of components that are used in HCL Software products.

如何安装 @hcl-software/enchanted-react-components?

在项目目录运行 npm install @hcl-software/enchanted-react-components,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.2.7)、react-dom(^19.2.7)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hcl-software/enchanted-react-components 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hcl-software/enchanted-react-components 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@hcl-software/enchanted-react-components 可以商用吗?

@hcl-software/enchanted-react-components 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@hcl-software/enchanted-react-components 的下载量有多少?

根据 npm 官方下载统计,@hcl-software/enchanted-react-components 在 2026/10/18 – 2026/11/16 这 30 天内被下载 4,845 次,日均约 162 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hcl-software/enchanted-react-components 还在维护吗?

最新版本 3.0.3 发布于 2026/11/02(15 天前);至今共发布 26 个版本,其中过去 12 个月发布了 16 个;首次发布于 2024/04/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。