@hyddenlabs/hydn-ui 0.0.1-alpha.34

package/README.md

@@ -0,0 +1,569 @@
+# HYDN UI
+
+A modern React component library built with TypeScript, Tailwind CSS, and optimized with tsup.
+
+## 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 tsup** - 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)
+- [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';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Card>
+        <h1>Hello World</h1>
+        <Input placeholder="Enter your name" />
+        <Button>Submit</Button>
+      </Card>
+    </ThemeProvider>
+  );
+}
+```
+
+### Import Styles
+
+The library styles are built with Tailwind CSS. Import the stylesheet in your main entry file:
+
+```tsx
+// In your main entry file (e.g., main.tsx or App.tsx)
+import '@hyddenlabs/hydn-ui/styles';
+```
+
+Alternatively, if you're using Tailwind in your project, you can configure it to include the library's components in your own Tailwind build.
+
+## 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
+- Price Display, Pricing
+- 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
+```
+
+### Project Structure
+
+```
+src/
+├── components/          # Reusable UI components
+│   ├── 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
+├── pages/              # Demo and application pages
+├── theme/              # Theme configuration and tokens
+└── index.ts            # Main library export
+```
+
+## Publishing
+
+### Build the Library
+
+```bash
+npm run build
+```
+
+This generates:
+
+- `dist/index.js` - ESM bundle (tree-shakeable)
+- `dist/index.cjs` - CommonJS bundle
+- `dist/index.d.ts` - TypeScript declarations (ESM)
+- `dist/index.d.cts` - TypeScript declarations (CJS)
+- `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 has a GitHub Actions workflow (`.github/workflows/publish.yml`) that handles:
+
+1. Running tests
+2. Building the library
+3. Versioning with GitVersion
+4. Publishing to npm
+5. Tagging releases
+
+To trigger automated publishing, use the GitHub UI: **Actions → Publish → Run workflow**
+
+### 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 the test suite that validates critical classes:
+
+```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
+- **tsup** - Library bundler
+- **Vite** - 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
+
+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.