add docs

README.md

@@ -2,4 +2,90 @@
 
 # Kirby Tailwind Merge
 
-Intelligently merge Tailwind classes without style conflicts in your Kirby templates
+Intelligently merge Tailwind classes without style conflicts in your Kirby templates.
+
+![Example for Tailwind Merge](.github/example.png)
+
+This plugin relies on [tailwind-merge-php by Sandro Gehri](https://github.com/gehrisandro/tailwind-merge-php) for merging classes and only adapts it to work in the "Kirby ecosystem". Any issues related to merging classes should probably reported over there.
+
+## Installation
+
+```
+composer require tobimori/kirby-tailwind-merge
+```
+
+#### Manual installation
+
+Download and copy this repository to `/site/plugins/kirby-tailwind-merge`, or apply this repository as Git submodule.
+
+## Usage
+
+This plugin provides two helper functions to use in your blueprints. Whether functions should be registered can be controlled in your `config.php`, see [Options](#options).
+
+### `attr()`
+
+This helper function works similar to the Kirby built-in `attr()` function and overwrites it to support Tailwind Merge behaviour for the `class` attribute.
+
+You'll need to disable the built-in `attr()` helper at the top-most location in your `index.php` file - before Kirby is loaded.
+
+```php
+define("KIRBY_HELPER_ATTR", false);
+```
+
+#### Example
+
+```php
+// site/snippets/component.php
+<div <?= attr(['class' => ['h-full w-full bg-neutral-100', $class], 'data-attr' => 'hello world!']) ?>>[...]</div>
+
+// site/templates/default.php
+<?php snippet('component', ['class' => 'w-1/2']) ?>
+
+// output
+<div class="h-full bg-neutral-100 w-1/2" data-attr="hello world!">[...]</div>
+```
+
+### `merge()`
+
+`merge()` applies Tailwind Merge behaviour and outputs a class attribute.
+
+#### Example
+
+```php
+// site/snippets/component.php
+<div <?= merge('h-full w-full bg-neutral-100', $class) ?>>[...]</div>
+
+// site/templates/default.php
+<?php snippet('component', ['class' => 'w-1/2']) ?>
+
+// output
+<div class="h-full bg-neutral-100 w-1/2">[...]</div>
+```
+
+## Options
+
+| Option          | Default | Description                            |
+| --------------- | ------- | -------------------------------------- |
+| `prefix`        | ``      | Set a prefix for your tailwind classes |
+| `helpers.attr`  | `true`  | Register the `attr()` helper function  |
+| `helpers.merge` | `true`  | Register the `merge()` helper function |
+
+Options allow you to fine tune the behaviour of the plugin. You can set them in your `config.php` file:
+
+```php
+return [
+    'tobimori.icon-field' => [
+        'cache' => true,
+        'folder' => 'assets/icon'
+    ],
+];
+```
+
+## Support
+
+> This plugin is provided free of charge & published under the permissive MIT License. If you use it in a commercial project, please consider to [sponsor me on GitHub](https://github.com/sponsors/tobimori) to support further development and continued maintenance of my plugins.
+
+## License
+
+[MIT License](./LICENSE)
+Copyright © 2023 Tobias Möritz

classes/TwMerge.php

@@ -31,8 +31,8 @@ public static function attr(
     return Html::attr($name, $value, $before, $after);
   }
 
-  public static function merge(string|array $classes): string
+  public static function merge(string|array $classes, ...$args): string
   {
-    return self::attr('class', $classes);
+    return self::attr('class', [$classes, ...$args]);
   }
 }

helpers.php

@@ -4,11 +4,7 @@
 
 if (option('tobimori.tailwind-merge.helpers.attr', true)) {
   /**
-   * Generates a list of HTML attributes, and intelligently merges classes with Tailwind merge.
-   *
-   * @param array|null $attr A list of attributes as key/value array
-   * @param string|null $before An optional string that will be prepended if the result is not empty
-   * @param string|null $after An optional string that will be appended if the result is not empty
+   * Generates a list of HTML attributes, and intelligently merges classes with Tailwind Merge.
    */
   function attr(
     array|null $attr = null,
@@ -21,11 +17,9 @@ function attr(
 
 if (option('tobimori.tailwind-merge.helpers.merge', true)) {
   /**
-   * Outputs the class html attribute and intelligently merges classes with Tailwind merge.
-   *
-   * @param string|array $classes A list of classes as string or array
+   * Outputs the class html attribute and intelligently merges classes with Tailwind Merge.
    */
-  function merge(string|array $classes): string
+  function merge(...$classes): string
   {
     return TwMerge::merge($classes);
   }