npm package: @hennge/ui-react
Description: A collection of highly accessible React components implementing the HENNGE One Design System.
Author: HENNGE
Latest version: 0.16.1

# @hennge/ui-react

> A collection of highly accessible React components implementing the HENNGE One Design System

[![npm Version](https://img.shields.io/npm/v/%40hennge%2Fui-react)](https://www.npmjs.com/package/@hennge/ui-react)
[![Storybook](https://cdn.jsdelivr.net/gh/storybookjs/brand@main/badge/badge-storybook.svg)](https://ssh.hennge.io/hennge-ui-react/dev/)
[![Figma](https://img.shields.io/badge/figma-%23F24E1E.svg?style=flat&logo=figma&logoColor=white)](https://www.figma.com/design/RHIqysg07r5f9iLvEBXjZf/Design-System)
[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)

## Features

- Fully accessible components following WAI-ARIA patterns
- Comprehensive theming support for HENNGE One products
- Responsive design and mobile-friendly components
- Built on top of React Aria Components for solid accessibility foundations
- Tailwind CSS integration (optional)

## Accessibility Foundation

HENNGE UI React is strategically built on industry-leading accessibility foundations:

- **React Aria Components by Adobe**: Provides comprehensive ARIA patterns, keyboard navigation, and screen reader support

This approach allows our library to deliver a polished visual layer atop these battle-tested accessibility implementations. By leveraging these foundations, HENNGE applications can more easily achieve WCAG 2.1 Level AA compliance.

Benefits of this architecture include:

- **Simplified development**: Core accessibility patterns have been thoroughly tested by the wider community
- **Reduced accessibility barriers**: Common accessibility issues are solved at the component level
- **Consistent behavior**: Interactions work predictably across different browsers and assistive technologies
- **Faster compliance**: Projects using this library inherit accessibility best practices automatically

## Installation

```sh
pnpm add @hennge/ui-react
```

## Usage

### Basic Setup

Import the CSS in your application entry point:

```tsx
import "@hennge/ui-react/css";
```

> Although this stylesheet is produced using Tailwind CSS, you **DO NOT** need Tailwind CSS in your project to use this library.

### Using Components

```tsx
import { Button } from "@hennge/ui-react";

function MyComponent() {
  return (
    <Button intent="primary" size="medium">
      Click Me
    </Button>
  );
}
```

## Tailwind CSS Integration

### Project Setup with Tailwind CSS V4

For projects using Tailwind CSS V4, you can integrate HENNGE UI React's styles:

```sh
pnpm add -D tailwindcss-react-aria-components
```

```css
@import "tailwindcss";
@import "@hennge/ui-react/tailwindcss";
@source "../node_modules/@hennge/ui-react";
```

> `@source` directive compiles HENNGE UI React with your project's Tailwind CSS for optimal bundle size.

### Modular Setup with Tailwind CSS V4

For more granular control, you can selectively import specific theme components:

```css
@import "tailwindcss";

/* Removes most colors shipped by Tailwind CSS */
@import "@hennge/ui-react/tailwindcss/unset-colors.css";

/* Imports the default HENNGE One Design System color theme, including fonts */
@import "@hennge/ui-react/tailwindcss/theme-hennge-default.css";

/* Imports the HENNGE One Identity Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-identity.css";

/* Imports the HENNGE One DLP Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-dlp.css";

/* Imports the HENNGE One Cybersecurity Edition color theme */
@import "@hennge/ui-react/tailwindcss/theme-hennge-cybersecurity.css";

/* Add utility classes used in HENNGE UI React */
@import "@hennge/ui-react/tailwindcss/utilities.css";

/* Add Tailwind CSS support for React Aria Components */
@plugin "tailwindcss-react-aria-components";

/* Compile Tailwind CSS classes used in HENNGE UI React */
@source "../node_modules/@hennge/ui-react";
```

## Font Setup

HENNGE UI React requires the following font packages for proper display:

```sh
pnpm add @fontsource-variable/noto-sans-jp @fontsource-variable/noto-sans-mono
```

Import the fonts in your application entry point:

```tsx
import "@fontsource-variable/noto-sans-jp";
import "@fontsource-variable/noto-sans-mono";
```

### Optional Chinese Language Support

For applications requiring Chinese language support:

```sh
# Traditional Chinese (zh-Hant-TW)
pnpm add @fontsource-variable/noto-sans-tc

# Simplified Chinese (zh-Hans-CN)
pnpm add @fontsource-variable/noto-sans-sc
```

And import in your application:

```tsx
import "@fontsource-variable/noto-sans-tc";
import "@fontsource-variable/noto-sans-sc";
```

## Documentation

Complete documentation of all components is available in Storybook:

- [Online Storybook](https://ssh.hennge.io/hennge-ui-react/dev/) (requires HENNGE organization account)
- Local development Storybook (see Development section)

## Development

### Prerequisites

- Node.js - Install the correct version using fnm:
  ```bash
  fnm install
  ```
  This uses the `.nvmrc` file in the project root.
- pnpm (used by the team for package management)

### Available Scripts

#### `pnpm build`

Builds the package for production, including JavaScript, CSS, and themes.

```bash
pnpm build
```

#### `pnpm dev`

Starts the development mode with file watching enabled.

```bash
pnpm dev
```

#### `pnpm typecheck`

Runs TypeScript's type checking to ensure there are no type errors.

```bash
pnpm typecheck
```

#### `pnpm lint`

Lints the codebase using Biome.

```bash
pnpm lint
```

#### `pnpm test`

Runs the test suite using Vitest.

```bash
pnpm test
```

#### `pnpm icons`

Compiles SVG files from the `/svg` folder into React components. This script automates the SVG-to-React conversion process, ensuring consistent and optimized icon components.

```bash
pnpm icons
```

##### Icon Workflow

The SVG icon workflow follows these steps:

1. SVG files are organized in the `/svg` directory with specific naming conventions:
   - Files should be placed in subdirectories that indicate their category (e.g., `/icon`, `/fileIcon`)
   - The subdirectory name becomes part of the component name
   - For example:
     - `/fileIcon/csv.svg` will be compiled to `/src/FileIconCsv.tsx`
     - `/icon/account.svg` will be compiled to `/src/IconAccount.tsx`

2. The compiler:
   - Transforms SVG files into React components
   - Applies proper naming conventions using PascalCase
   - Sets default props like size, color, and accessibility attributes
   - Optimizes the SVG code for React

3. Importing generated icons:
   ```tsx
   import { IconAccount } from "@hennge/ui-react";
   
   function App() {
     return <IconAccount />;
   }
   ```

##### Adding New Icons

New icons should be sourced from the HENNGE Design System Figma file:

1. Go to the [Design System Figma file](https://www.figma.com/design/RHIqysg07r5f9iLvEBXjZf/Design-System?node-id=34375-6082&t=ftXQfPGUiLghrtqf-4)
2. Navigate to the Icons section
3. Select the icons you need (be careful not to select text labels)
4. Export as SVG format from the Export panel
5. Place the exported files in the appropriate subdirectory under `/svg`
6. Run `pnpm icons` to generate the React components

#### `pnpm themes`

Converts color themes from hexadecimal format to P3 color space using OKLCH syntax. This script enhances color rendering on modern displays while maintaining backward compatibility.

```bash
pnpm themes
```

##### Theme Workflow

The theme workflow involves:

1. Theme source files are stored in `/src/themes-hex/` directory in standard hexadecimal format:
   - `theme-hennge-default.css`
   - `theme-hennge-identity.css`
   - `theme-hennge-dlp.css`
   - `theme-hennge-cybersecurity.css`

2. The compiler:
   - Reads these source files
   - Converts the hexadecimal colors to OKLCH color space with high precision (5 significant digits)
   - Outputs the processed files to `/src/themes/` directory
   - Preserves color fidelity while enabling better rendering on wide-gamut displays

3. Finally, during the build process:
   - Theme files are copied to the distribution package
   - Made available through various import paths for consumer applications

> This process is typically only needed when updating the design system colors or adding new themes. Most developers won't need to run this script regularly.

### Development Workflow

A typical development workflow for this package might look like this:

1. Start the development mode with file watching enabled:
   ```bash
   pnpm dev
   ```

2. Make changes to the source code in the `/src` directory

3. Verify type correctness:
   ```bash
   pnpm typecheck
   ```

4. Run tests to ensure functionality:
   ```bash
   pnpm test
   ```

5. Lint your code to ensure consistency:
   ```bash
   pnpm lint
   ```

6. Build the package for production:
   ```bash
   pnpm build
   ```

7. Create a tarball for testing with:
   ```bash
   pnpm pack
   ```
   This generates a `.tgz` file that can be installed in other projects to verify the package works correctly.

### Testing the Package in Other Projects

When testing in a monorepo setup, there are additional considerations for handling internal dependencies like `@hennge/ui-core`. [Yalc](https://github.com/wclr/yalc) provides an excellent solution for this scenario.

#### Using Yalc for Local Package Testing

Yalc acts as a local package repository, making it easy to share local packages across projects without publishing to a registry. It's especially useful for testing packages with internal dependencies like our monorepo structure.

1. **Installation**:
   ```bash
   # Install yalc globally
   pnpm add -g yalc
   ```

2. **Publishing and using packages**:
   ```bash
   # In ui-core directory
   pnpm build
   yalc publish  # Makes ui-core available in the local yalc store
   
   # In ui-react directory
   yalc add @hennge/ui-core  # Adds the local ui-core as a dependency
   pnpm install
   pnpm build
   yalc publish  # Makes ui-react available in the local yalc store
   
   # In your test project
   yalc add @hennge/ui-react  # Adds the local ui-react as a dependency
   pnpm install
   ```

3. **Updating packages during development**:
   ```bash
   # After making changes to ui-core
   pnpm build
   yalc push  # Updates all projects using this package
   
   # After making changes to ui-react
   pnpm build
   yalc push  # Updates all projects using this package
   ```

4. **Removing yalc dependencies when done**:
   ```bash
   # In your test project
   yalc remove --all
   pnpm install  # Restore regular dependencies
   ```

This workflow allows you to test your changes in a real application context without publishing to npm or dealing with complex manual extractions.

## License

Apache-2.0 - see [LICENSE](https://github.com/HENNGE/hennge-ui-react/blob/main/LICENSE) for details.