npm package: @sewalusteven/ui-framework
Description: Govnet UI Framework - Reusable Vue 3 component library for Govnet Services. Requires TailwindCSS v4.x.
Author: Govnet Services
Latest version: 0.1.4

# Govnet UI Framework

A comprehensive, production-ready Vue 3 component library built with TypeScript and TailwindCSS v4. Designed specifically for Govnet Services to provide consistent, accessible, and customizable UI components across all projects.

[![npm version](https://img.shields.io/npm/v/@sewalusteven/ui-framework.svg)](https://www.npmjs.com/package/@sewalusteven/ui-framework)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- ✨ **15+ Production-Ready Components** - Form inputs, data display, and navigation components
- 🎨 **TailwindCSS v4** - Modern utility-first styling with customizable themes
- 📱 **Fully Responsive** - Mobile-first design approach
- ♿ **Accessible** - Built with HeadlessUI for WCAG compliance
- 🔧 **TypeScript First** - Full type safety and IntelliSense support
- 🎯 **Tree Shakeable** - Import only what you need
- 📚 **Comprehensive Documentation** - Detailed examples and Storybook stories
- ✅ **Well Tested** - 400+ unit tests with Vitest
- 🎭 **Multiple Variants** - Size, color, and style variations for each component

## Installation

```bash
npm install @sewalusteven/ui-framework
```

### ⚠️ Required Peer Dependencies

This library **requires TailwindCSS v4.x** to be installed in your project:

```bash
# Install required dependencies
npm install vue@^3.5.0 vue-router@^4.5.0
npm install tailwindcss@^4.0.0 @tailwindcss/vite@^4.0.0
```

**Important**: The library does NOT bundle CSS. It uses Tailwind utility classes that must be generated by your project's TailwindCSS installation.

## Quick Start

### 1. Configure TailwindCSS v4

In your `vite.config.js`:

```javascript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
})
```

In your main CSS file (e.g., `src/assets/main.css`):

```css
@import "tailwindcss";
```

### 2. Use Components

```vue
<script setup lang="ts">
import { Button, TextInput, GovTabs } from '@sewalusteven/ui-framework'
import type { TabItem } from '@sewalusteven/ui-framework'

const tabs: TabItem[] = [
  { label: 'Profile', content: '<p>Profile content</p>' },
  { label: 'Settings', content: '<p>Settings content</p>' }
]
</script>

<template>
  <div>
    <TextInput
      label="Email"
      placeholder="Enter your email"
      type="email"
    />

    <Button variant="primary" size="md">
      Submit
    </Button>

    <GovTabs :tabs="tabs" variant="rounded" />
  </div>
</template>
```

## Available Components

### Form Components

#### Button
Multi-variant button component with icons, loading states, and size options.

```vue
<Button
  variant="primary"
  size="md"
  :loading="false"
  :disabled="false"
>
  Click Me
</Button>
```

**Variants**: `primary`, `secondary`, `tertiary`, `danger`, `outline`, `ghost`, `link`
**Sizes**: `xs`, `sm`, `base`, `md`, `lg`, `xl`

#### TextInput
Text input with label, validation, and icon support.

```vue
<TextInput
  v-model="email"
  label="Email Address"
  type="email"
  placeholder="you@example.com"
  :required="true"
/>
```

**Types**: `text`, `email`, `password`, `number`, `tel`, `url`, `search`

#### TextArea
Multi-line text input with auto-resize option.

```vue
<TextArea
  v-model="description"
  label="Description"
  :rows="4"
  placeholder="Enter description..."
/>
```

#### CheckBox
Checkbox input with label and indeterminate state.

```vue
<CheckBox
  v-model="accepted"
  label="I agree to the terms"
/>
```

#### Switch
Toggle switch for boolean values.

```vue
<Switch
  v-model="enabled"
  label="Enable notifications"
/>
```

#### RadioButton
Radio button group with custom options.

```vue
<script setup>
const options = [
  { value: 'option1', label: 'Option 1' },
  { value: 'option2', label: 'Option 2' }
]
</script>

<template>
  <RadioButton
    v-model="selected"
    :options="options"
    label="Choose an option"
  />
</template>
```

#### Dropdown
Searchable dropdown with single/multiple selection.

```vue
<script setup>
const options = [
  { value: '1', label: 'Option 1' },
  { value: '2', label: 'Option 2' }
]
</script>

<template>
  <Dropdown
    v-model="selected"
    :options="options"
    label="Select item"
    :searchable="true"
  />
</template>
```

#### FileInput
File upload input with drag-and-drop support.

```vue
<FileInput
  v-model="file"
  label="Upload document"
  accept=".pdf,.doc,.docx"
/>
```

#### PhoneInput
Phone number input with country code selection.

```vue
<PhoneInput
  v-model="phone"
  label="Phone Number"
/>
```

#### DateRange
Date range picker with calendar interface.

```vue
<DateRange
  v-model="dateRange"
  label="Select dates"
/>
```

### Data Display Components

#### GovTable
Comprehensive table component with two usage modes.

**Data-Driven Mode:**
```vue
<script setup>
const columns = [
  { key: 'id', label: 'ID' },
  { key: 'name', label: 'Name' },
  { key: 'email', label: 'Email' }
]

const data = [
  { id: 1, name: 'John Doe', email: 'john@example.com' },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]
</script>

<template>
  <GovTable
    :columns="columns"
    :data="data"
    :stickyHeader="true"
  />
</template>
```

**Manual Mode:**
```vue
<GovTable theme="default">
  <GovHead>
    <GovRow header>
      <GovCol header>ID</GovCol>
      <GovCol header>Name</GovCol>
      <GovCol header>Email</GovCol>
    </GovRow>
  </GovHead>
  <GovBody>
    <GovRow v-for="item in data" :key="item.id">
      <GovCol>{{ item.id }}</GovCol>
      <GovCol>{{ item.name }}</GovCol>
      <GovCol>{{ item.email }}</GovCol>
    </GovRow>
  </GovBody>
</GovTable>
```

**Features**: Sticky headers, sticky columns, sorting, themes, action slots

### Navigation Components

#### GovTabs
Tabbed interface with multiple style variants and orientations.

```vue
<script setup>
const tabs = [
  { label: 'Profile', content: '<p>Profile content</p>' },
  { label: 'Settings', content: '<p>Settings content</p>' },
  { label: 'Billing', content: '<p>Billing content</p>' }
]
</script>

<template>
  <GovTabs
    :tabs="tabs"
    variant="rounded"
    orientation="horizontal"
    size="base"
    @change="handleTabChange"
  />
</template>
```

**Variants**: `underline`, `rounded`, `pills`, `boxed`
**Orientations**: `horizontal`, `vertical`
**Sizes**: `xs`, `sm`, `base`, `md`, `lg`, `xl`

## Component Exports

### Components
```typescript
import {
  // Form Components
  Button,
  TextInput,
  TextArea,
  CheckBox,
  Switch,
  RadioButton,
  Dropdown,
  FileInput,
  PhoneInput,
  DateRange,

  // Table Components
  GovTable,
  GovHead,
  GovBody,
  GovRow,
  GovCol,

  // Navigation Components
  GovTabs,
  TabContent
} from '@sewalusteven/ui-framework'
```

### Types
```typescript
import type {
  // Core Types
  Theme,
  Size,
  ButtonType,
  ButtonVariant,
  InputType,

  // Component-Specific Types
  DropdownOption,
  RadioOption,
  TableColumn,
  TabItem
} from '@sewalusteven/ui-framework'
```

### Composables
```typescript
import { useGlobalStyles } from '@sewalusteven/ui-framework'
```

## TypeScript Support

Full TypeScript support with exported types for all components:

```typescript
import type { TabItem, TableColumn, DropdownOption } from '@sewalusteven/ui-framework'

const tabs: TabItem[] = [
  { label: 'Home', content: '<p>Home</p>' }
]

const columns: TableColumn[] = [
  { key: 'id', label: 'ID', sortable: true }
]

const options: DropdownOption[] = [
  { value: '1', label: 'Option 1' }
]
```

## Customization

### Theme Customization

The library uses TailwindCSS v4. You can customize the theme by extending your `tailwind.config.js`:

```javascript
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          // ... your custom colors
          900: '#0c4a6e',
        }
      }
    }
  }
}
```

### Size Variants

Most components support multiple size variants:
- `xs` - Extra small
- `sm` - Small
- `base` - Base (default)
- `md` - Medium
- `lg` - Large
- `xl` - Extra large

### Custom Colors

Many components accept custom color props:

```vue
<GovTabs
  :tabs="tabs"
  activeColor="text-purple-600"
  inactiveColor="text-gray-500"
  activeBgColor="bg-purple-50"
/>

<Button
  bgColor="bg-emerald-600"
  textColor="text-white"
>
  Custom Colors
</Button>
```

## Testing

The library includes comprehensive unit tests:

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui
```

**Test Coverage**: 400+ tests across all components

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run Storybook
npm run storybook

# Build library
npm run build:lib

# Run tests
npm test
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Dependencies

### Core Dependencies
- Vue 3.5+
- Vue Router 4.5+
- TailwindCSS 4.x
- HeadlessUI Vue
- Iconify Vue

### Icons

The library uses Iconify for icons. You can use any icon from the [Iconify library](https://icon-sets.iconify.design/):

```vue
<Button icon="material-symbols:add">
  Add Item
</Button>
```

## Contributing

We welcome contributions! Please see our contributing guidelines for more details.

## License

MIT © Govnet Services

## Links

- [npm Package](https://www.npmjs.com/package/@sewalusteven/ui-framework)
- [GitHub Repository](https://github.com/govnet/ui-framework-v1)
- [Documentation](https://govnet.github.io/ui-framework-v1)
- [Storybook](https://govnet.github.io/ui-framework-v1/storybook)

## Support

For issues, questions, or feature requests, please [open an issue](https://github.com/govnet/ui-framework-v1/issues) on GitHub.

---

Made with ❤️ by Govnet Services