@cesarfernandoig/alpine-responsive-plugin/README.md

A lightweight Alpine.js plugin that simplifies managing conditional attributes in responsive designs.

# Alpine.js Responsive Plugin
**Supercharge your Alpine.js apps with responsive superpowers! 🚀**

A lightweight [Alpine.js](https://alpinejs.dev/) plugin that simplifies managing responsive behaviors and conditional attributes. This plugin provides utilities to manage media query states and apply conditional attributes or values based on screen size.


## 🌟 Features
- **📱 Media Query State Management:** Instantly know if your user is on mobile or desktop.
- **✨ Magic Helpers:** Use `media` and `getMobileValue` to make your components smarter.
- **🎨 Custom Directive:** Dynamically add or remove attributes with `x-mobileattributes`.

## 🛠️ Installation
Getting started with Responsive is a breeze! With just a few lines of code, you'll unlock the power of responsive design in your [Alpine.js](https://alpinejs.dev/) projects.

### Via NPM
1. Install the plugin with npm:
```console
npm install @cesarfernandoig/alpine-responsive-plugin
```
2. Import and initialize the plugin in your project:
```javascript
import Alpine from 'alpinejs';
import responsive from '@cesarfernandoig/alpine-responsive-plugin';

Alpine.plugin(responsive);
Alpine.start();
```

### Via CDN
If you prefer using a CDN, simply include the following script tag in your HTML file, make sure to include it BEFORE Alpine's core JS file:
```html
<!-- Alpine Plugins -->
<script defer src="https://cdn.jsdelivr.net/npm/@cesarfernandoig/alpine-responsive-plugin@1.x.x/dist/responsive.min.js"></script>

<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
```

## 🎮 Usage
Now that the plugin is set up, let’s explore the magic! You can use the features provided by **`Responsive`** to make your site smarter and more responsive.

### 🪄 Magic: $media
The media magic helper gives you access to `isMobile` and `isDesktop` properties. You can use these properties anywhere in your Alpine.js components to apply logic based on screen size.

#### Example:
```html
<div x-data>
  <span x-text="$media.isMobile ? '📱 On Mobile!' : '🖥️ On Desktop!'"></span>
</div>
```
- `$media.isMobile` is `true` if the screen width is less than 768px.
- `$media.isDesktop` is `true` if the screen width is 768px or greater.

### 🪄 Magic: $getMobileValue
The `$getMobileValue` magic helper is your go-to for conditional values. It’s like having a chameleon that adapts to the device type! 🦎

#### Example:
```html
<div x-data>
  <span x-text="$getMobileValue('This is for mobile 🐳', 'This is for desktop 🦖')"></span>
</div>
```
- If the device is mobile, it returns `'This is for mobile 🐳'`.
- If the device is desktop, it returns `'This is for desktop 🦖'`.

### 🖌️ Directive: x-mobileattributes
Want to conditionally add/remove attributes based on screen size? Look no further than the `x-mobileattributes` directive! You can pass in a set of attributes and their values for mobile and desktop resolutions, and `Responsive` will handle the rest.

#### Example:
```html
<button
	type="button"
	x-mobileattributes="{
        title: ['Snake', 'Turtle'],
        'x-text': ['`🐍`', '`🐢`'],
        class: 'snake-class'
    }"
	>
</button>
```
- **Mobile:** Sets the `title` to `"Snake"`, `x-text` to `"🐍"`, and applies the `snake-class`.
- **Desktop:** Sets the `title` to `"Turtle"`, `x-text` to `"🐢"`, and removes the `class` attribute (since it doesn't have a desktop value — similar to writing `class: ['snake-class', null]`).

### 💡 Pro Tip:
By combining `Responsive` with Alpine’s built-in directives like `x-show`, `x-if`, or `x-transition`, you can create rich and highly dynamic UI elements tailored for different screen sizes.

## 🧑‍💻 API Reference
### 🪄 Magics

- **`$media`:** Returns a reactive object with `isMobile` and `isDesktop` properties.

```javascript
$media.isMobile; // true if mobile
$media.isDesktop; // true if desktop
```

- **`$getMobileValue(mobileValue, desktopValue)`:** Returns `mobileValue` if the device is mobile, otherwise returns `desktopValue`.

```javascript
getMobileValue('📱 Mobile', '🖥️ Desktop'); // '📱 Mobile' or '🖥️ Desktop'
```

### 🖌️ Directives
- **`x-mobileattributes`:** Applies or removes attributes conditionally.
```html
<div x-mobileattributes="{ 'attribute': [mobileValue, desktopValue] }"></div>
```

## 🤝 Contributing
We 💖 contributions! If you have an idea, found a bug, or just want to improve the plugin, feel free to jump in!
1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request.

## 📜 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments
A huge shoutout to [Alpine.js](https://alpinejs.dev/) for making JavaScript fun and simple!

## 🚀 Ready to Go Responsive?
With this plugin, handling responsiveness in your Alpine.js apps has never been easier. Install it today and start building smarter, more dynamic interfaces! 🎉