@seplan/diti-ds/README.md

Reusable UI component library developed by DITI (Technology and Innovation Directorate of SEPLAN PI) based on Mantine and Tailwind CSS

# @seplan/diti-ds

Reusable UI component library developed by DITI (Technology and Innovation Directorate of SEPLAN PI) based on Mantine and Tailwind CSS.

## Installation

```bash
npm install @seplan/diti-ds
# or
yarn add @seplan/diti-ds
# or
pnpm add @seplan/diti-ds
```

## Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install @mantine/core @mantine/hooks react react-dom
# or
yarn add @mantine/core @mantine/hooks react react-dom
# or
pnpm add @mantine/core @mantine/hooks react react-dom
```

## Usage

### Import all components

```tsx
import { Card, Button, SearchInput } from '@seplan/diti-ds'
```

### Import specific modules

```tsx
// Import only UI components
import { Card, Button } from '@seplan/diti-ds/ui'

// Import only hooks
import { useClipboard, useMediaQuery } from '@seplan/diti-ds/hooks'

// Import only utilities
import { cn, formatCurrency } from '@seplan/diti-ds/utils'

// Import only components (same as ui)
import { Card, Button } from '@seplan/diti-ds/components'
```

### Import styles

```tsx
import '@seplan/diti-ds/styles'
```

## Available Components

### Basic Components
- `AxisCard` - Card component with axis styling
- `BackButton` - Button for navigation back
- `Breadcrumbs` - Breadcrumb navigation component
- `Card` - Basic card component
- `EmptyState` - Empty state component
- `Label` - Label component
- `SearchInput` - Search input component

### Logo Components
- `Logo` - Logo component
- `LogoHorizontal` - Horizontal logo component

### Navigation Components
- `NavigationTabs` - Tab navigation component
- `BackButton` - Back navigation button

### Filter Components
- `AsyncFilter` - Asynchronous filter component
- `FilterManager` - Filter management component
- `FilterPopover` - Filter popover component
- `DateRangeFilter` - Date range filter
- `ValueRangeFilter` - Value range filter

### Data Display Components
- `DataList` - Data list component
- `SortableColumnHeader` - Sortable column header
- `PaginationFooter` - Pagination footer components

### Form Components
- `FormDrawer` - Form drawer component
- `RadioCard` - Radio card component
- `OptionalInputLabel` - Optional input label

### Utility Components
- `ClearFiltersButton` - Clear filters button
- `CounselorStatusBadge` - Counselor status badge
- `ImagePlaceholder` - Image placeholder
- `SeplanAppsBar` - SEPLAN apps bar

## Available Hooks

- `useClipboard` - Clipboard utility hook
- `useDownloadBlob` - Download blob hook
- `useMediaQuery` - Media query hook
- `usePaginationReset` - Pagination reset hook
- `useQRCodeGenerator` - QR code generator hook
- `useSortableColumn` - Sortable column hook
- `useFilters` - Filters hook
- `useSelectedItems` - Selected items hook

## Available Utilities

- `cn` - Class name utility (clsx + tailwind-merge)
- `formatCurrency` - Currency formatting utility
- `formatDate` - Date formatting utility
- `formatCPF` - CPF formatting utility
- `isValidCPF` - CPF validation utility
- `removeAccents` - Remove accents utility
- `normalizeForSearch` - Search normalization utility

## Examples

### Basic Card Usage

```tsx
import { Card } from '@seplan/diti-ds'

function MyComponent() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>My Card Title</Card.Title>
      </Card.Header>
      <Card.Content>
        <p>Card content goes here</p>
      </Card.Content>
    </Card>
  )
}
```

### Search Input Usage

```tsx
import { SearchInput } from '@seplan/diti-ds'

function MyComponent() {
  const handleSearch = (value: string) => {
    console.log('Searching for:', value)
  }

  return (
    <SearchInput
      placeholder="Search..."
      onSearch={handleSearch}
      debounceMs={300}
    />
  )
}
```

### Using Hooks

```tsx
import { useClipboard, useMediaQuery } from '@seplan/diti-ds'

function MyComponent() {
  const { copy, copied } = useClipboard()
  const isMobile = useMediaQuery('(max-width: 768px)')

  const handleCopy = () => {
    copy('Text to copy')
  }

  return (
    <div>
      <button onClick={handleCopy}>
        {copied ? 'Copied!' : 'Copy Text'}
      </button>
      {isMobile && <p>Mobile view</p>}
    </div>
  )
}
```

### Using Utilities

```tsx
import { cn, formatCurrency, formatDate } from '@seplan/diti-ds'

function MyComponent() {
  const className = cn(
    'base-class',
    'conditional-class',
    { 'active': true }
  )

  return (
    <div className={className}>
      <p>Price: {formatCurrency(1234.56)}</p>
      <p>Date: {formatDate(new Date())}</p>
    </div>
  )
}
```

## Development

### Setup

```bash
git clone <repository-url>
cd diti-ds
npm install
```

### Development Commands

```bash
# Start development server
npm run dev

# Build library
npm run build:lib

# Build types
npm run build:types

# Start Storybook
npm run storybook

# Build Storybook
npm run build-storybook

# Lint code
npm run lint

# Format code
npm run format
```

### Publishing

```bash
# Publish patch version
npm run publish:patch

# Publish minor version
npm run publish:minor

# Publish major version
npm run publish:major
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT