@cranberry-money/shared-utils/README.md

Shared utility functions for Blueberry platform

# @myportfolio/shared-utils

Shared utility functions for the Blueberry platform, supporting both web (Blueberry) and mobile (Blackberry) applications.

## Installation

```bash
npm install @myportfolio/shared-utils
```

## Usage

```typescript
import { formatCurrency, formatDate, hasActiveFilters, truncateText } from '@myportfolio/shared-utils';

// Currency formatting
const amount = formatCurrency(1234.56); // "1,234.56"

// Date formatting
const date = formatDate('2024-01-15T10:30:00Z'); // "1/15/2024"

// Filter utilities
const hasFilters = hasActiveFilters({ name: 'Apple', category: '', page: 1 }); // true

// Text utilities
const short = truncateText('This is a very long text', 10); // "This is a..."
```

## Available Utilities

### Formatters

#### Currency (`formatters/currency.ts`)

- `formatCurrency(value)` - Format number with commas and 2 decimals
- `parseCurrencyInput(value)` - Parse currency string to number
- `formatCurrencyWithCode(value, code, locale, minDigits, maxDigits)` - Format with currency code
- `formatDefaultCurrency(value, minDigits, maxDigits)` - Format with default currency (AUD)

#### Dates (`formatters/dates.ts`)

- `formatDate(dateString, fallback)` - Format ISO date to localized date
- `formatShortDate(dateString, locale)` - Format to short date (e.g., "Jan 15")
- `formatTime(dateString, locale)` - Format to 24-hour time
- `formatDateTime(dateString, locale)` - Format to "Jan 15 14:30"

#### Numbers (`formatters/numbers.ts`)

- `formatShares(shares, locale)` - Format share quantities (no decimals)

### Helpers

#### Filters (`helpers/filters.ts`)

- `hasActiveFilters<T>(filters, excludeFields)` - Check if any filters are active
- `countActiveFilters<T>(filters, excludeFields)` - Count active filters
- `clearAllFilters<T>(filters, preserveFields)` - Clear all filter values
- `updateFilters<T>(currentFilters, updates)` - Type-safe filter updates

#### Text (`helpers/text.ts`)

- `truncateText(text, maxLength)` - Truncate text with ellipsis

## Platform Compatibility

This package is designed to work across:

- Web applications (React) - Direct use of utility functions
- Mobile applications (React Native) - Platform-agnostic implementations
- Node.js environments - For server-side utility needs

### Platform-Specific Considerations

#### Date Formatting

The date formatters use `Intl.DateTimeFormat` and `toLocaleDateString` which work consistently across web and React Native platforms.

#### Currency Formatting

Currency formatters use `Intl.NumberFormat` which provides consistent formatting across platforms with proper locale support.

#### Filter Utilities

Filter utilities are completely platform-agnostic and work with any TypeScript object structure.

## Examples

### Currency Formatting

```typescript
import { formatCurrency, formatCurrencyWithCode } from '@myportfolio/shared-utils';

// Basic formatting
formatCurrency(1234.56); // "1,234.56"
formatCurrency('1234.56'); // "1,234.56"

// With currency code
formatCurrencyWithCode(1234.56, 'USD', 'en-US', 2, 2); // "$1,234.56"
formatCurrencyWithCode(1234.56, 'AUD', 'en-AU', 0, 0); // "A$1,235"
```

### Filter Management

```typescript
import { hasActiveFilters, countActiveFilters, clearAllFilters } from '@myportfolio/shared-utils';

const filters = {
  searchQuery: 'apple',
  category: 'technology',
  minPrice: 100,
  maxPrice: null,
  tags: [],
};

// Check for active filters (excluding searchQuery by default)
hasActiveFilters(filters); // true (category and minPrice are active)

// Count active filters
countActiveFilters(filters); // 2 (category and minPrice)

// Clear all filters while preserving searchQuery
const cleared = clearAllFilters(filters, ['searchQuery']);
// Result: { searchQuery: 'apple' }
```

### Date Formatting

```typescript
import { formatDate, formatDateTime, formatShortDate } from '@myportfolio/shared-utils';

const isoDate = '2024-01-15T14:30:00Z';

formatDate(isoDate); // "1/15/2024"
formatShortDate(isoDate); // "Jan 15"
formatDateTime(isoDate); // "Jan 15 14:30"
```

## Development

```bash
# Build the package
npm run build

# Watch for changes
npm run dev

# Type check
npm run typecheck
```

## Dependencies

- `@myportfolio/shared-constants` - For currency and formatting constants

## License

MIT