npm package: @omnifyjp/ui-components
Description: A comprehensive React UI component library built on [Shadcn UI](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/) + [Tailwind CSS v4](https://tailwindcss.com/). Provides 53 accessible primitives and 14 domain-specific components — all tree-s
Latest version: 0.5.3

# @omnifyjp/ui-components

A comprehensive React UI component library built on [Shadcn UI](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/) + [Tailwind CSS v4](https://tailwindcss.com/). Provides 53 accessible primitives and 14 domain-specific components — all tree-shakeable with per-component entry points.

## Installation

```bash
npm install @omnifyjp/ui-components
# or
pnpm add @omnifyjp/ui-components
```

### Peer Dependencies

```bash
npm install react react-dom
```

Optional peers (only needed if you use specific components):

| Peer | Required By |
|------|-------------|
| `date-fns` (>=3) | `calendar`, `date-picker` |
| `recharts` (>=2) | `chart` |
| `react-hook-form` (>=7) | `form` |

---

## Usage

### Import individual components (recommended)

```tsx
import { Button } from '@omnifyjp/ui-components/components/button';
import { Card, CardContent, CardHeader, CardTitle } from '@omnifyjp/ui-components/components/card';
import { Input } from '@omnifyjp/ui-components/components/input';
```

### Import from barrel (convenience)

```tsx
import { Button, Card, Input } from '@omnifyjp/ui-components';
```

### Import utilities

```tsx
import { cn } from '@omnifyjp/ui-components/lib/utils';
```

### Import hooks

```tsx
import { useIsMobile } from '@omnifyjp/ui-components/hooks/use-mobile';
```

### Import theme CSS

```css
@import '@omnifyjp/ui-components/styles';
```

---

## Components

### Shadcn UI Primitives (53)

All Shadcn primitives are included, fully accessible via Radix UI, with dark mode support.

| Category | Components |
|----------|-----------|
| **Layout** | `aspect-ratio`, `card`, `resizable`, `scroll-area`, `separator`, `skeleton` |
| **Navigation** | `breadcrumb`, `menubar`, `navigation-menu`, `pagination`, `tabs` |
| **Data Display** | `avatar`, `badge`, `calendar`, `carousel`, `chart`, `hover-card`, `progress`, `table`, `tooltip` |
| **Data Entry** | `button`, `checkbox`, `color-picker`, `combobox`, `date-picker`, `file-upload`, `form`, `input`, `input-otp`, `label`, `radio-group`, `rating`, `select`, `slider`, `switch`, `tag-input`, `textarea`, `time-picker`, `toggle`, `toggle-group` |
| **Feedback** | `alert`, `alert-dialog`, `sonner` (toast) |
| **Overlay** | `command`, `context-menu`, `dialog`, `drawer`, `dropdown-menu`, `popover`, `sheet` |
| **Composition** | `accordion`, `collapsible`, `sidebar` |

### Domain Components (14)

Shared business-logic components, locale-agnostic (accept `labels` prop with English defaults).

#### Calendar

| Component | Description |
|-----------|-------------|
| `CalendarMini` | Compact month calendar with event dots |
| `CalendarEventChip` | Colored event bar for calendar grids |
| `CalendarEventSheet` | Side panel for event details |
| `CalendarToolbar` | Date navigation with view switcher (month/week/day) |
| `CalendarCategoryBadge` | Colored category label |

#### Workflow

| Component | Description |
|-----------|-------------|
| `WorkflowStepper` | Multi-step progress indicator |
| `WorkflowDiagram` | Visual flow diagram with stages |
| `WorkflowStatusBadge` | Status indicator (active/draft/archived) |
| `WorkflowCategoryBadge` | Category badge for workflows |
| `StageTypeBadge` | Stage type indicator (approval/action/notification) |

#### RBAC

| Component | Description |
|-----------|-------------|
| `PermissionGrid` | Module x Action permission matrix with checkboxes |
| `ScopeTree` | Hierarchical scope selector with inheritance |
| `ScopeTypeBadge` | Scope level indicator (global/org/branch/team) |

#### Forms

| Component | Description |
|-----------|-------------|
| `SlugInput` | URL-friendly slug input with auto-generation |

---

## Theme & Styling

### CSS Design Tokens

The package ships a `theme.css` with a complete token system. Import it in your app:

```css
/* In your global CSS */
@import '@omnifyjp/ui-components/styles';
```

### Density Tokens

All spacing and sizing is controlled via CSS custom properties:

| Token | Value | Tailwind Class | Use For |
|-------|-------|----------------|---------|
| `--density-page` | 16px | `p-page` | Page padding |
| `--density-section` | 16px | `gap-section` | Section gaps |
| `--density-element` | 32px | `h-element` | Button/Input height |
| `--density-element-sm` | 28px | `h-element-sm` | Small inputs |
| `--density-element-lg` | 36px | `h-element-lg` | Large buttons |
| `--density-card` | 16px | `px-card`, `pt-card` | Card padding |
| `--density-dialog` | 20px | `p-dialog` | Dialog padding |
| `--header-height` | 48px | `h-header` | App header height |
| `--density-page-title` | 20px | `text-page-title` | Page title font size |

### Dark Mode

All components support dark mode via the `dark` class on `<html>`. Color tokens auto-switch:

```tsx
// Semantic tokens (auto dark mode)
<div className="bg-background text-foreground border-border">
  <p className="text-muted-foreground">Secondary text</p>
</div>

// Accent colors with dark variants
<Badge className="bg-red-50 dark:bg-red-500/15 text-red-600 dark:text-red-400">
  Urgent
</Badge>
```

---

## Utility: `cn()`

Class merging utility combining `clsx` + `tailwind-merge`:

```tsx
import { cn } from '@omnifyjp/ui-components/lib/utils';

<div className={cn('p-4 bg-card', isActive && 'ring-2 ring-primary', className)} />
```

---

## Tree Shaking

The package is fully tree-shakeable:

- **Per-component entry points**: `@omnifyjp/ui-components/components/button` only loads `button.js`
- **`sideEffects: false`**: Bundlers can safely eliminate unused code
- **ESM only**: Modern `import`/`export` for optimal bundling

---

## Package Exports

```
@omnifyjp/ui                    → all components (barrel)
@omnifyjp/ui-components/components/button  → Button, buttonVariants
@omnifyjp/ui-components/components/card    → Card, CardHeader, CardContent, ...
@omnifyjp/ui-components/components/*       → any component by name
@omnifyjp/ui-components/lib/utils          → cn()
@omnifyjp/ui-components/hooks/use-mobile   → useIsMobile()
@omnifyjp/ui-components/styles             → theme.css
```

---

## Tech Stack

- **React** 18+ with new JSX transform
- **TypeScript** (strict mode, full type definitions)
- **Tailwind CSS v4** with design tokens
- **Radix UI** for accessible primitives
- **class-variance-authority** for component variants
- **cmdk** for command palette
- **embla-carousel-react** for carousel
- **react-day-picker** for calendar/date-picker
- **react-resizable-panels** for resizable layouts
- **vaul** for drawer component
- **sonner** for toast notifications
- **lucide-react** for icons

---

## Related Packages

| Package | Description |
|---------|-------------|
| [`@omnifyjp/ui`](https://www.npmjs.com/package/@omnifyjp/ui) | App shell framework (sidebar, header, i18n, theming) — depends on this package |
| [`@omnifyjp/editor`](https://www.npmjs.com/package/@omnifyjp/editor) | Rich text editors (Tiptap + BlockNote) |

---

## License

MIT