@pageblock/utils/README.md

A modern utility library for PageBlock and Webflow, providing reusable components and utilities for web applications and Webflow sites

# PageBlock Utils

A modern utility library for PageBlock and Webflow, providing reusable components and utilities for web applications and Webflow sites.

[![npm version](https://badge.fury.io/js/%40pageblock%2Futils.svg)](https://www.npmjs.com/package/@pageblock/utils)
[![GitHub license](https://img.shields.io/github/license/Blackout-Media/pageblock-utils)](https://github.com/Blackout-Media/pageblock-utils/blob/main/LICENSE)

## Features

- 🚀 Modern JavaScript (ES6+)
- 📦 Tree-shakeable exports
- 🎨 SCSS styling with modern features
- 🔧 Built with Vite for optimal performance
- 📱 Responsive and accessible components
- 🌐 Cross-browser compatibility
- ⚡ Webflow-ready components

[View Demo](https://github.com/Blackout-Media/pageblock-utils/tree/main/examples) | [Report Bug](https://github.com/Blackout-Media/pageblock-utils/issues) | [Request Feature](https://github.com/Blackout-Media/pageblock-utils/issues)

## Installation

### NPM Installation (Recommended)

```bash
npm install @pageblock/utils
```

### Import Individual Components

```javascript
// Import specific components
import { Countdown } from '@pageblock/utils/countdown';
import '@pageblock/utils/style.css';

// Initialize components
const countdown = new Countdown();
```

### Import Complete Package

```javascript
// Import all components
import PageBlockUtils from '@pageblock/utils';
import '@pageblock/utils/style.css';

// Initialize components
const modal = new PageBlockUtils.Modal();
const countdown = new PageBlockUtils.Countdown();
```

### CDN Usage (For Webflow)

```html
<!-- Add to Head -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pageblock/utils@latest/dist/pageblock-utils.css">

<!-- Add before </body> -->
<script type="module">
  import { Countdown } from 'https://cdn.jsdelivr.net/npm/@pageblock/utils@latest/dist/countdown.js';
  const countdown = new Countdown();
</script>
```

## Components

### Countdown Component
[View Countdown Documentation](src/components/countdown/README.md)

### Modal Component

The modal component provides an accessible, customizable modal dialog system that can be used in various contexts:

- As an ES module in modern JavaScript applications
- As a direct script include for Webflow or other no-code platforms
- As part of the PageBlock Utils package

#### Features

- **Accessibility**: Full keyboard navigation, focus trapping, and proper ARIA attributes
- **Multiple animations**: Fade, zoom, slide-up, slide-down
- **Layout variants**: Standard modal, bottom sheet, side panels, full-screen mobile
- **Z-index management**: Automatically handles stacking of multiple modals
- **Event callbacks**: Hooks for open and close events
- **No dependencies**: Pure JavaScript with no external libraries required

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## Browser Support

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

## License

MIT License - see the [LICENSE](LICENSE) file for details.