npm package: @ktnpm_devops/react-component
Description: Kenmei Technologies React Component Library
Latest version: 0.4.1

# @ktnpm_devops/react-component

Kenmei's Orbit design system as a tree-shakeable React component library with CSS Modules, full dark mode support, and Storybook documentation.

## Installation

```bash
pnpm add @ktnpm_devops/react-component
```

### Peer Dependencies

Required:

```bash
pnpm add react react-dom
```

Optional (only needed for chart/table components):

```bash
pnpm add echarts echarts-for-react    # Chart components
pnpm add @tanstack/react-table        # Advanced table features
pnpm add lucide-react                 # Icon components
```

## Setup

Import the design tokens in your app entry point:

```tsx
// main.tsx or App.tsx
import '@ktnpm_devops/react-component/tokens';
```

## Quick Start

```tsx
import { Button, Card, CardHeader, CardContent, Badge } from '@ktnpm_devops/react-component';

function App() {
  return (
    <Card>
      <CardHeader>
        <h2>Dashboard</h2>
        <Badge variant="success">Active</Badge>
      </CardHeader>
      <CardContent>
        <Button variant="primary" onClick={() => alert('Hello!')}>
          Click Me
        </Button>
      </CardContent>
    </Card>
  );
}
```

## Dark Mode

Set `data-theme="dark"` on your root element:

```tsx
document.documentElement.setAttribute('data-theme', 'dark');
```

All components automatically adapt — no additional configuration needed.

## Components

### Primitives

| Component | Description |
|-----------|-------------|
| `Button` | Variants: primary, secondary, outline, ghost, danger. Sizes: sm, md, lg |
| `Badge` | Status indicator: success, warning, danger, info |
| `Input` | Text input with focus ring |
| `Textarea` | Multi-line text input |
| `Select` | Native select dropdown |
| `Card` | Compound: Card + CardHeader + CardContent + CardFooter |
| `Table` | TableContainer + Table with styled headers/rows |
| `Modal` | Dialog overlay with portal, ESC-to-close, focus management |
| `Avatar` | Initials-based avatar with gradient background |

### Composites

| Component | Description |
|-----------|-------------|
| `MultiSelectDropdown` | Multi-select with search, select/deselect all, pending apply/cancel |
| `SingleSelectDropdown` | Single-select with search and optional clear button |
| `CustomRangePicker` | Date range picker with preset ranges and custom selection |
| `ResizableSplitPanel` | Draggable split layout with keyboard support |
| `ChartExpandModal` | Full-screen modal for expanded chart views, portal-based with resize |
| `ContextMenu` | Right-click context menu with keyboard navigation, portal-based |

### Hooks

| Hook | Description |
|------|-------------|
| `useClickOutside` | Detect clicks outside a referenced element |
| `useEscapeKey` | Listen for Escape key press |
| `useResizeObserver` | Track element dimensions |

### Utilities

| Utility | Description |
|---------|-------------|
| `formatNumber` | Locale-aware number formatting |
| `formatBytes` | Human-readable byte sizes |
| `formatDataTimestamp` | Timezone-aware date formatting |
| `exportTableToCsv` | Export table data as CSV |
| `sanitizeFilename` | Safe filename generation |

## Development

```bash
pnpm install       # Install dependencies
pnpm dev           # Start Storybook (port 6006)
pnpm test          # Run tests
pnpm build         # Build library
pnpm lint          # Lint code
pnpm typecheck     # Type check
```

## OpenSpec + Changelog Workflow

This project uses [OpenSpec](https://github.com/kenmeitechnologies/openspec) for spec-driven development and [Changesets](https://github.com/changesets/changesets) for versioning.

**OpenSpec does not update the changelog.** After completing and archiving a change, manually sync both:

1. **Create a changeset** for the automated release pipeline:
   ```bash
   pnpm changeset
   ```
   Or create the file directly in `.changeset/<change-name>.md`:
   ```md
   ---
   "@ktnpm_devops/react-component": patch
   ---

   Description of what changed.
   ```
   Use `patch` for docs/stories/fixes, `minor` for new components/features, `major` for breaking changes.

2. **Update CHANGELOG.md** — add a `### Added` or `### Enhanced` entry under `[Unreleased]` and update the Status Board table if component status changed.

3. **On release**, Changesets consumes the `.changeset/` files and versions the package:
   ```bash
   pnpm changeset version   # Bumps version, updates CHANGELOG
   pnpm build && pnpm publish
   ```

## License

MIT