npm package: @pantograph/utils
Description: A comprehensive utility library providing essential helper functions for Vue 3 applications and component development.
Author: sedmedgh
Latest version: 0.0.36

# @pantograph/utils

A comprehensive utility library providing essential helper functions for Vue 3 applications and component development.

## Features

- **BEM Class Generation**: Generate consistent BEM (Block Element Modifier) class names
- **Class Normalization**: Merge and normalize class names with `class-variance-authority` and `tailwind-merge`
- **Validation Utilities**: Check for empty values and validate numbers
- **Size Utilities**: Convert numbers to pixel strings and extract values
- **Component Utilities**: Generate component names and options
- **ID Generation**: Create unique IDs with optional prefixes
- **Style Utilities**: Convert style strings to objects
- **Option Handling**: Create flexible option getter functions
- **TypeScript Support**: Full TypeScript definitions included

## Quick Start

```bash
# Installation
npm install @pantograph/utils

# Basic usage
import { getBemBlock, normCls, isEmptyLikeLodash } from '@pantograph/utils'

const blockClass = getBemBlock('button') // 'pc_button'
const className = normCls('base-class', { 'active': true }, 'base-class') // 'base-class active'
const isEmpty = isEmptyLikeLodash('') // true
```

## Documentation

📖 **[Getting Started Guide](./GETTINGSTARTED.md)** - Complete guide with installation, API reference, and usage examples.

## API Overview

### BEM Utilities
- `getBemBlock()` - Generate BEM block classes
- `getBemElement()` - Generate BEM element classes  
- `getBemModifier()` - Generate BEM modifier classes
- `generateVariantClassList()` - Generate variant class lists
- `normCls()` - Normalize and merge class names

### Validation Utilities
- `isEmptyLikeLodash()` - Check if value is empty
- `getValidNumber()` - Extract valid numbers
- `getPxSize()` - Convert to pixel strings
- `extractFromPxSize()` - Extract numbers from pixel strings

### Component Utilities
- `getComponentName()` - Generate component names
- `getComponentOptions()` - Generate component options
- `usePCId()` - Generate unique IDs
- `getComponentStyleId()` - Generate style IDs

### Style Utilities
- `getStyleObject()` - Convert style strings to objects

### Option Handling
- `createOptionGetterFunc()` - Create option getter functions

## Usage Examples

### Vue Component with BEM
```vue
<template>
  <button :class="buttonClasses">
    <span :class="iconClasses">Icon</span>
    <span :class="textClasses">Text</span>
  </button>
</template>

<script setup>
import { getBemBlock, getBemElement, getBemModifier, normCls } from '@pantograph/utils'

const blockClass = getBemBlock('button')
const iconClass = getBemElement(blockClass, 'icon')
const textClass = getBemElement(blockClass, 'text')

const buttonClasses = normCls(
  blockClass,
  getBemModifier(blockClass, 'primary'),
  getBemModifier(blockClass, 'md')
)
</script>
```

### Form Validation
```typescript
import { getValidNumber, isEmptyLikeLodash } from '@pantograph/utils'

const validateInput = (value: string) => {
  if (isEmptyLikeLodash(value)) return 'Required'
  const number = getValidNumber(value)
  if (number === undefined) return 'Invalid number'
  return null
}
```

## TypeScript Support

Full TypeScript definitions are included with JSDoc comments for better IDE support.

```typescript
import type { ClassValue } from 'clsx'

const className: string = normCls('base', 'conditional')
const isValid: boolean = isEmptyLikeLodash('')
```

## Dependencies

- `class-variance-authority` - Class variant management
- `tailwind-merge` - Class merging
- `es-toolkit` - Utility functions
- `@pantograph/tokens` - Design system integration

## License

This package is part of the Pantograph design system and follows the same licensing terms.