docs: update README with usage examples and API details

fix: bump version to 0.1.5 in package.json and package-lock.json

Author: stefanBid

README.md

@@ -21,4 +21,138 @@
 ```bash
 npm install sb-floating-panel-vue
 # or
-yarn add sb-floating-panel-vue
+yarn add sb-floating-panel-vue
+```
+
+---
+
+## 🧩 Usage
+
+The `useSbFloatingPanel` composable provides an easy-to-integrate API to handle floating panels, such as tooltips, popovers, dropdowns, and other UI overlays.
+
+### Importing
+
+```ts
+import { useSbFloatingPanel } from 'sb-floating-panel-vue';
+```
+
+### 🧠 API
+
+```ts
+const {
+  reference,
+  floating,
+  popperArrow,
+  isOpen,
+  floatingPosition,
+  floatingStyles,
+  floatingArrowStyles,
+  changeFloatingVisibility,
+} = useSbFloatingPanel(settings);
+```
+
+### Parameters
+
+The composable takes a `settings` object:
+
+```ts
+interface FloatingSettings {
+  placement: Placement; // e.g., 'bottom', 'top-start', etc.
+  strategy: Strategy; // 'absolute' | 'fixed'
+  offsetValue: number; // offset in pixels from the reference element
+  hasArrow?: boolean; // enable arrow positioning
+  hasResize?: boolean; // enable auto-resizing with anchor element
+}
+```
+
+---
+
+## 🔍 Computed Values Explained
+
+### `floatingStyles`
+
+A Vue `computed` value containing the CSS style object that must be applied to your floating panel. It is dynamically calculated by `@floating-ui/vue` to maintain optimal placement relative to the reference element.
+
+### `floatingPosition`
+
+The actual resolved placement string, e.g., `'bottom-start'`, useful for adding custom animations or behavior depending on where the panel is placed.
+
+### `floatingArrowStyles`
+
+An object that includes styles for positioning the optional arrow element (enabled via the `hasArrow` setting). You can directly bind this to the arrow’s `style` attribute.
+
+---
+
+## 🧪 Example
+
+```ts
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useSbFloatingPanel } from 'sb-floating-panel-vue';
+
+const {
+  reference,
+  floating,
+  popperArrow,
+  isOpen,
+  floatingStyles,
+  floatingArrowStyles,
+  changeFloatingVisibility,
+} = useSbFloatingPanel({
+  placement: 'bottom',
+  strategy: 'absolute',
+  offsetValue: 8,
+  hasArrow: true,
+  hasResize: true,
+});
+
+const togglePanel = () => {
+  changeFloatingVisibility(!isOpen.value);
+};
+</script>
+```
+
+```vue
+<template>
+  <button ref="reference" @click="togglePanel">Toggle Panel</button>
+  <div
+    v-if="isOpen"
+    ref="floating"
+    :style="floatingStyles"
+    class="popover"
+  >
+    I'm a floating panel!
+    <div ref="popperArrow" :style="floatingArrowStyles.arrow" class="arrow" />
+  </div>
+</template>
+```
+
+---
+
+## 🎨 Styling
+
+You can use your own CSS or utility classes (like Tailwind CSS) to style the panel and the arrow. Example:
+
+```css
+.popover {
+  background: white;
+  border: 1px solid #ccc;
+  padding: 0.75rem;
+  border-radius: 0.5rem;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+.arrow {
+  width: 10px;
+  height: 10px;
+  background: white;
+  transform: rotate(45deg);
+  position: absolute;
+}
+```
+
+---
+
+## 📄 License
+
+MIT © [Stefano Biddau](https://github.com/stefanobiddau)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "sb-floating-panel-vue",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A lightweight Vue 3 composable hook built on top of @floating-ui/vue to manage floating panels with arrow and resize support.",
   "main": "dist/sb-floating-panel.umd.js",
   "module": "dist/sb-floating-panel.es.js",