@ynmstudio/utils/README.md

YNM Utilities for Angular

# YNM Utils

A comprehensive Angular utility library providing a wide range of helpers, pipes, directives, and services to accelerate your development.

## Features

### Helper Functions (`helpers`)

Reusable utility functions for type checking, string/array/object manipulation, and more. Examples:

- `isUndefined`, `isNull`, `isNumber`, `isString`, `isArray`, `isObject`, `isFunction`, `isNil`
- `toDecimal`, `upperFirst`, `leftPad`, `rightPad`, `pad`, `flatten`, `getProperty`, `sum`, `shuffle`, `deepEqual`, etc.

### Pipes (`pipes`)

- **fileSize**: Formats a number of bytes as a human-readable string (e.g., `1.5 MB`).
- **join**: Joins array elements into a string with a custom separator.
- **joinIntl**: Joins array elements using `Intl.ListFormat` for locale-aware lists.
- **pluck**: Extracts a property from each object in an array.
- **safe**: Bypasses Angular's security to safely bind HTML, style, script, URL, or resource URL.
- **focalPoint**: Converts a focal point array (e.g., `[0.5, 0.5]`) to a CSS background-position string (e.g., `50% 50%`).

### Directives

- **InViewportDirective (`snInViewport`)**: Detects when an element enters or leaves the viewport. Adds `sn-viewport--in`/`sn-viewport--out` classes and emits events.
- **SmoothHeightDirective (`smoothHeight`)**: Animates height changes smoothly for dynamic content.
- **DynamicHeadingDirective (`dynamicHeading`)**: Automatically manages heading levels (h1-h6) for accessibility and semantic structure. Supports debug mode and custom hierarchy resets.
- **DrawBlurhash (`drawBlurhash`)**: Renders a BlurHash placeholder on a canvas element for progressive image loading.

### Modules

- **ScrollSpyModule**: Automatically updates navigation links to indicate the currently active section in the viewport. Includes directives for scroll spy, section, and item.

### Services

- **LoadingBarService**: Manages a global or scoped loading bar/progress indicator. Includes RxJS-based state management and HTTP interceptor for automatic progress indication.
- **YnmUtilsService**: Base injectable service for general utilities.

### Interceptors

- **CraftIframeResizerInterceptor**: Dynamically loads iframe resizer for Craft CMS live preview in iframes.
- **CraftPreviewInterceptor**: Injects preview tokens for Craft CMS live preview and prevents caching in preview mode.
- **CraftPreviewPreventIsrCacheInterceptor**: Prevents ISR cache in projects for Craft CMS live
- **CraftSecurityInterceptor**: Adds security headers to HTTP requests for Craft CMS APIs.
- **LoadingBarInterceptor**: Integrates with Angular's HTTP client to show/hide the loading bar automatically during HTTP requests.

### Signals

- **toSignalWithError**: Converts an RxJS Observable to Angular Signals, exposing both value and error as signals for reactive error handling.

## Installation

```bash
npm install @ynmstudio/utils
```

## Usage

Import only the features you need. Example for a pipe:

```typescript
import { FileSizePipe } from "@ynmstudio/utils/pipes/file-size";
```

For directives:

```typescript
import { InViewportDirective } from "@ynmstudio/utils/inviewport";
```

For services:

```typescript
import { LoadingBarService } from "@ynmstudio/utils/loading-bar";
```

## Development

- Build: `ng build ynm-utils`
- Test: `ng test ynm-utils`
- Publish: `npm publish` from `dist/ynm-utils`

## License

MIT