npm package: @hyddenlabs/hydn-ui
Description: A modern React component library built with TypeScript and Tailwind CSS
Latest version: 0.3.19

# HYDN UI

A modern React component library built with TypeScript, Tailwind CSS, and optimized with Vite.

## Overview

HYDN UI is a comprehensive design system and component library that provides a collection of reusable, accessible, and customizable React components. The library includes everything from basic form elements to complex data visualization components.

## Features

- 🎨 **Modern Design System** - Clean, consistent, and professional UI components
- ⚡ **Built with Vite** - Fast builds and optimal bundle size
- 🎯 **TypeScript** - Full type safety and excellent developer experience
- 🎨 **Tailwind CSS** - Utility-first CSS framework for rapid styling
- ♿ **Accessible** - Components built with accessibility in mind
- 🧪 **Well Tested** - Comprehensive test suite with Vitest
- 📱 **Responsive** - Mobile-first responsive design
- 🌲 **Tree-Shakeable** - Only bundle what you use

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [Component Categories](#component-categories)
- [Tree-Shaking](#tree-shaking)
- [Development](#development)
- [Publishing](#publishing)
- [CSS Class Validation](#css-class-validation)
- [Tech Stack](#tech-stack)
- [Contributing](#contributing)

## Installation

```bash
npm install @hyddenlabs/hydn-ui
# or
yarn add @hyddenlabs/hydn-ui
# or
pnpm add @hyddenlabs/hydn-ui
```

## Quick Start

### Basic Setup

```tsx
import { ThemeProvider } from '@hyddenlabs/hydn-ui';
import '@hyddenlabs/hydn-ui/styles.css';

function App() {
  return (
    <ThemeProvider>
      <Card>
        <h1>Hello World</h1>
        <Input placeholder="Enter your name" />
        <Button>Submit</Button>
      </Card>
    </ThemeProvider>
  );
}
```

**Note:** The styles are automatically included when you import any component. You only need to ensure your bundler (Vite, Webpack, etc.) is configured to handle CSS imports.

## Usage Examples

### Forms

```tsx
import { Button, Input, FormField, Card } from '@hyddenlabs/hydn-ui';

function LoginForm() {
  return (
    <Card>
      <FormField label="Email" required>
        <Input type="email" placeholder="Enter your email" />
      </FormField>

      <FormField label="Password" required>
        <Input type="password" placeholder="Enter your password" />
      </FormField>

      <Button variant="primary" fullWidth>
        Sign In
      </Button>
    </Card>
  );
}
```

### Data Tables

```tsx
import { DataTable } from '@hyddenlabs/hydn-ui';

const columns = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'status', header: 'Status' }
];

const data = [
  { name: 'John Doe', email: 'john@example.com', status: 'active' },
  { name: 'Jane Smith', email: 'jane@example.com', status: 'inactive' }
];

function UserTable() {
  return <DataTable columns={columns} data={data} />;
}
```

### Layouts

```tsx
import { Container, Grid, Card, Heading } from '@hyddenlabs/hydn-ui';

function Dashboard() {
  return (
    <Container>
      <Heading level={1}>Dashboard</Heading>

      <Grid cols={3} gap="lg">
        <Card>
          <Heading level={3}>Total Users</Heading>
          <p>1,234</p>
        </Card>

        <Card>
          <Heading level={3}>Revenue</Heading>
          <p>$45,678</p>
        </Card>

        <Card>
          <Heading level={3}>Orders</Heading>
          <p>890</p>
        </Card>
      </Grid>
    </Container>
  );
}
```

### Theme Customization

```tsx
import { ThemeProvider, ColorModeToggle } from '@hyddenlabs/hydn-ui';

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <header>
        <ColorModeToggle />
      </header>
      {/* Your app content */}
    </ThemeProvider>
  );
}
```

### TypeScript Support

All components are fully typed. Import types directly:

```tsx
import type { ButtonProps, InputProps, CardProps } from '@hyddenlabs/hydn-ui';

const customButton: ButtonProps = {
  variant: 'primary',
  size: 'lg',
  onClick: () => console.log('clicked')
};
```

## Component Categories

### Forms & Inputs

- Button, Button Group
- Input, Input Group, Textarea
- Select, Radio, Radio Group, Checkbox
- Slider, Switch, Calendar
- Form, Form Field, Fieldset

### Data Display

- Avatar, Badge, Chip
- Table, Data Table, List
- Timeline, Code Block
- Empty State

### Layout

- Card, Container, Grid
- Accordion, Drawer, Divider
- Page, Page Header, Section
- Hero, Feature Section, Footer
- Stack

### Navigation

- Navbar, Nav, Sidebar
- Breadcrumbs, Dropdown
- Pagination, Stepper, Tabs

### Feedback

- Alert, Dialog, Modal
- Toast, Tooltip, Popover
- Progress Bar, Spinner, Skeleton

### Typography

- Heading, Text, Link, Code

### System

- Theme Provider, Color Mode Toggle

## Tree-Shaking

The library is built with full tree-shaking support. Modern bundlers (Vite, Webpack 5, Rollup) will automatically eliminate unused components:

```tsx
// Only Button and its dependencies are bundled (~6KB)
import { Button } from '@hyddenlabs/hydn-ui';

// Multiple imports are also tree-shaken
import { Button, Input, Card } from '@hyddenlabs/hydn-ui';
```

### Benefits

- ✅ Only pay for what you use
- ✅ Automatic dead code elimination with ESM
- ✅ Unminified source for better bundler optimization
- ✅ Modern tooling compatible

### How It Works

The library is optimized for tree-shaking:

- **ESM format** - Modern bundlers can analyze and eliminate dead code
- **Unminified** - Preserves original code structure for better analysis
- **sideEffects field** - Tells bundlers what's safe to remove (CSS only)
- **Named exports** - Each component is individually importable
- **No global side effects** - Components don't execute code on import

### Verification

To verify tree-shaking works:

1. Create a test project with Vite:

```bash
npm create vite@latest my-test -- --template react-ts
cd my-test
npm install @hyddenlabs/hydn-ui
```

2. Import a single component:

```tsx
import { Button } from '@hyddenlabs/hydn-ui';
```

3. Build and check bundle size:

```bash
npm run build
```

You should see only ~6-8KB for Button, not the entire 118KB library.

## Development

This repository contains both the component library and a showcase/documentation SPA.

### Prerequisites

- Node.js (v18 or higher)
- npm, yarn, or pnpm

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com/hydn-co/hydn-ui.git
cd hydn-ui

# Install dependencies
npm install

# Start the development server (runs the showcase SPA)
npm run dev

# Run tests
npm test

# Build the library for publishing
npm run build

# Lint code
npm run lint

# Format code
npm run format
```

### Scripts

| Command | Purpose |
| --- | --- |
| `npm run dev` | Start the showcase SPA (development server) |
| `npm run build` | Build the library (ESM), CSS, and types |
| `npm test` | Run the test suite (Vitest) |
| `npm run lint` | Lint source and tests (ESLint) |
| `npm run lint:fix` | Lint with auto-fix |
| `npm run format` | Format code with Prettier |
| `npm run format:check` | Check formatting (used in CI) |

See `package.json` for the full list of scripts.

### Project Structure

```
src/
├── components/          # Reusable UI components (library)
│   ├── data-display/   # Data visualization components
│   ├── feedback/       # User feedback components
│   ├── forms/          # Form-related components
│   ├── layout/         # Layout and structural components
│   ├── navigation/     # Navigation components
│   ├── system/         # System-level components
│   └── typography/     # Text and typography components
├── showcase/            # Showcase/documentation SPA (not published)
│   ├── pages/          # Demo and application pages
│   └── ...
├── theme/               # Theme configuration and tokens
└── index.ts             # Main library entry (consumers import from here)
```

## Publishing

### Build the Library

```bash
npm run build
```

The library is **ESM-only**. The build generates:

- `dist/index.js` - ESM entry (tree-shakeable; additional modules under `dist/` for tree-shaking)
- `dist/index.d.ts` - TypeScript declarations
- `dist/style.css` - Compiled Tailwind CSS styles
- Source maps for debugging

### Publishing Process

1. **Update Version**

```bash
# Using npm version command (recommended)
npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0
```

2. **Verify Build Output**

Check the `dist/` folder contains all required files.

3. **Test Locally (Optional)**

```bash
# In hydn-ui directory
npm link

# In your test project
npm link @hyddenlabs/hydn-ui
```

Or create a tarball:

```bash
npm pack
# This creates hyddenlabs-hydn-ui-x.x.x.tgz
```

4. **Publish to npm**

```bash
# Dry run (recommended first)
npm publish --dry-run

# Publish (public package)
npm publish --access public

# Or publish with a specific tag
npm publish --tag beta --access public
```

5. **Verify Publication**

- Check the package page: https://www.npmjs.com/package/@hyddenlabs/hydn-ui
- Test installation: `npm install @hyddenlabs/hydn-ui`

### Automated Publishing (CI/CD)

The repository uses GitHub Actions (`.github/workflows/publish.yml`):

1. Set the version manually in `package.json`
2. Commit and push your changes
3. Run **Actions → Publish Package → Run workflow**

The workflow runs CI checks, reads the version from `package.json`, tags the commit, and publishes to npm.

### Troubleshooting

**Build Fails:**

```bash
rm -rf dist node_modules
npm install
npm run build
```

**Permission Denied:**

```bash
npm whoami
npm access ls-packages @hyddenlabs
```

### Post-Publish Checklist

- [ ] Verify package appears on npm
- [ ] Test installation in a fresh project
- [ ] Update CHANGELOG.md
- [ ] Create GitHub release with notes
- [ ] Announce release (if applicable)

## CSS Class Validation

HYDN UI includes comprehensive CSS validation tools to ensure all Tailwind classes used in components are properly generated in the output CSS.

### Why This Matters

When building a component library with Tailwind CSS, it's critical to ensure that:

- All classes used in components are actually generated in the final CSS
- No classes are accidentally misspelled or reference non-existent theme tokens
- The generated CSS file contains everything consumers need

### Validation Methods

#### 1. Automated Audit Script (Recommended)

Run the comprehensive audit to check all components:

```bash
npm run audit:css
```

This script:

- ✅ Extracts all className usages from your components
- ✅ Validates them against the generated `dist/style.css`
- ✅ Reports missing classes with file locations
- ✅ Identifies dynamic/computed classes (like `z-[999]`)
- ✅ Filters out template literals and conditional logic

**Example Output:**

```
🔍 Auditing CSS classes...

📁 Found 90 component files
📄 CSS file size: 69.41 KB

🎨 Total unique classes found: 177

⚠️  Dynamic/computed classes (2):
   - z-[999]
   - min-w-[180px]

✅ All classes found in generated CSS!
✅ 176 classes validated successfully
```

#### 2. CSS Validation Tests

Run only the CSS validation tests:

```bash
npm run test:css
```

This runs `tests/css-validation.test.ts` which:

- ✅ Checks for critical component classes
- ✅ Validates theme tokens (CSS custom properties)
- ✅ Ensures CSS file is not empty
- ✅ Integrates with CI/CD pipelines

#### 3. Full Test Suite

All component tests also implicitly validate CSS classes:

```bash
npm test
```

Since tests check for specific classes (e.g., `expect(button).toHaveClass('rounded-lg')`), they will fail if classes aren't generated.

### Best Practices

**Run audit before publishing:**

```bash
npm run audit:css && npm run build && npm test
```

**Avoid dynamic class construction:**

```tsx
// ❌ Bad - class might not be generated
const sizeClass = `w-${size}`;
<div className={sizeClass} />;

// ✅ Good - explicit mapping
const sizeClasses = {
  sm: 'w-4',
  md: 'w-6',
  lg: 'w-8'
};
<div className={sizeClasses[size]} />;
```

**CI/CD integration** - The GitHub Actions workflows automatically run CSS validation on every push and before publishing.

### Validation Commands Summary

| Command             | Purpose                               |
| ------------------- | ------------------------------------- |
| `npm run audit:css` | Comprehensive class validation        |
| `npm run test:css`  | Quick CSS validation tests            |
| `npm test`          | Full test suite (includes CSS checks) |

## Tech Stack

- **React 19** - UI library
- **TypeScript** - Type safety
- **Vite** - Library build and development server
- **Tailwind CSS** - Styling
- **React Router** - Client-side routing (showcase only)
- **Vitest** - Testing framework
- **Testing Library** - Component testing utilities
- **Tabler Icons** - Icon library

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to run the repo, run tests, and submit changes. In short:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is private and proprietary to HYDN Co.

## Support

For questions and support, please contact the HYDN development team.