npm package: @pos-360/horizon
Description: POS-360 unified component library - the horizon all apps look toward
Latest version: 0.30.0

# @pos-360/horizon

Unified UI component library for the POS-360 software ecosystem. Built with React, TypeScript, and Tailwind CSS.

## Installation

```bash
npm install @pos-360/horizon
# or
pnpm add @pos-360/horizon
# or
yarn add @pos-360/horizon
```

### Peer Dependencies

Ensure you have the following peer dependencies installed:

```bash
npm install react react-dom tailwindcss clsx tailwind-merge class-variance-authority
# For enhanced components
npm install framer-motion lucide-react @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-popover @radix-ui/react-select @radix-ui/react-tabs
```

## Setup

### Tailwind Configuration

Extend your `tailwind.config.js` with the Horizon preset:

```js
const horizonPreset = require("@pos-360/horizon/tailwind");

module.exports = {
  presets: [horizonPreset],
  content: [
    // ... your content paths
    "./node_modules/@pos-360/horizon/**/*.{js,ts,jsx,tsx}",
  ],
  // ... rest of your config
};
```

## Usage

### Importing Components

```tsx
// Import specific components
import { Button, Card, Badge } from "@pos-360/horizon";

// Or import from specific entry points for better tree-shaking
import { Button, Badge } from "@pos-360/horizon/primitives";
import { Input, Toast } from "@pos-360/horizon/enhanced";
import { useToast } from "@pos-360/horizon/hooks";
```

### Basic Example

```tsx
import { Button, Card, CardHeader, CardTitle, CardContent } from "@pos-360/horizon";

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="default">Click me</Button>
      </CardContent>
    </Card>
  );
}
```

### Using Toast Notifications

```tsx
import { Toast, useToast } from "@pos-360/horizon";

function MyComponent() {
  const { toast, showSuccess, showError } = useToast();

  return (
    <div>
      <button onClick={() => showSuccess("Operation completed!")}>
        Show Success
      </button>
      <button onClick={() => showError("Something went wrong")}>
        Show Error
      </button>
      {toast && <Toast {...toast} />}
    </div>
  );
}
```

## Components

### Primitives

Core UI building blocks based on shadcn/ui patterns:

| Component | Description |
|-----------|-------------|
| `Button` | Versatile button with variants (default, destructive, outline, secondary, ghost, link) |
| `Badge` | Status indicators with variants (default, secondary, destructive, outline, success, warning, info) |
| `Card` | Container with header, title, description, content, and footer subcomponents |
| `Checkbox` | Accessible checkbox built on Radix UI |
| `Dialog` | Modal dialog with overlay, header, footer, title, and description |
| `DropdownMenu` | Full-featured dropdown menu system |
| `Popover` | Floating content container |
| `Select` | Accessible select/dropdown built on Radix UI |
| `Skeleton` | Loading state placeholders (text, title, avatar, card, table rows) |
| `Table` | Full table system with header, body, row, cell components |
| `Tabs` | Tab navigation built on Radix UI |
| `Textarea` | Multi-line text input |

### Enhanced

Feature-rich components with advanced behaviors:

| Component | Description |
|-----------|-------------|
| `AnimatedButton` | Framer Motion powered button with hover/tap animations |
| `Input` | Full-featured input with icons, decorators, number controls, select mode, and mobile formatting |
| `TextButton` | Text-style button with leading/trailing decorators |
| `Toast` | Animated toast notifications with progress bar |

### Hooks

| Hook | Description |
|------|-------------|
| `useToast` | Toast notification state management |

### Utilities

| Utility | Description |
|---------|-------------|
| `cn` | Class name merger (clsx + tailwind-merge) |

## Design Tokens

The Horizon Tailwind preset includes POS-360 design tokens:

### Colors

- Primary: `primary-50` through `primary-950`
- Semantic: `background`, `foreground`, `card`, `popover`, `muted`, `accent`, `destructive`
- Border and input colors with dark mode support

### Animations

- `accordion-down` / `accordion-up`
- `pulse-slow` (slower pulse for skeletons)

## Development

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch mode
pnpm dev
```

## Package Exports

```json
{
  ".": "./dist/index.js",
  "./primitives": "./dist/primitives.js",
  "./enhanced": "./dist/enhanced.js",
  "./hooks": "./dist/hooks.js",
  "./tailwind": "./dist/tailwind.js"
}
```

## License

MIT - POS-360