sb-floating-panel-vue 0.1.5

package/README.md

@@ -0,0 +1,158 @@
+# sb-floating-panel-vue
+[![npm](https://img.shields.io/npm/v/sb-floating-panel-vue.svg)](https://www.npmjs.com/package/sb-floating-panel-vue)
+[![license](https://img.shields.io/npm/l/sb-floating-panel-vue.svg)](https://github.com/stefanobiddau/sb-floating-panel-vue/blob/main/LICENSE)
+
+> A lightweight Vue 3 composable hook built on top of [@floating-ui/vue](https://github.com/floating-ui/floating-ui) to manage floating panels with arrow and resize support.
+
+---
+
+## ✨ Features
+
+- 📦 Minimal and composable API
+- 🎯 Precise floating panel positioning via `@floating-ui/vue`
+- 🎈 Optional arrow positioning
+- 📏 Auto-resize support
+- 🧠 TypeScript-first
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install sb-floating-panel-vue
+# or
+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/dist/index.d.ts

@@ -0,0 +1 @@
+export { useSbFloatingPanel } from './use-sb-floating-panel/useSbFloatingPanel';

package/dist/sb-floating-panel.es.js

@@ -0,0 +1,45 @@
+import { useFloating as m, autoUpdate as d, offset as w, flip as b, shift as y, arrow as z } from "@floating-ui/vue";
+import { ref as t, watch as f, onMounted as O, onUnmounted as R, nextTick as g } from "vue";
+function F(a) {
+  const l = t(null), n = t(null), u = t(null), r = t(!1), o = t(null);
+  let i = !1;
+  const { floatingStyles: c, placement: v, middlewareData: p } = m(l, n, {
+    open: r,
+    placement: a.placement,
+    strategy: a.strategy,
+    transform: !1,
+    middleware: [
+      w(a.offsetValue),
+      b(),
+      y(),
+      ...a.hasArrow ? [z({ element: u })] : []
+    ],
+    whileElementsMounted: d
+  }), h = (e) => {
+    r.value = e;
+  }, s = () => {
+    n.value && l.value && (n.value.style.width = `${l.value.offsetWidth}px`);
+  };
+  return f(r, async (e) => {
+    e && a.hasResize && i && (await g(), s());
+  }), f(l, (e) => {
+    e && a.hasResize && !i && (i = !0, o.value = new ResizeObserver(s), o.value.observe(e));
+  }), O(() => {
+    a.hasResize && l.value && (i = !0, o.value = new ResizeObserver(s), o.value.observe(l.value));
+  }), R(() => {
+    var e;
+    a.hasResize && ((e = o.value) == null || e.disconnect());
+  }), {
+    reference: l,
+    floating: n,
+    popperArrow: u,
+    isOpen: r,
+    floatingPosition: v,
+    floatingStyles: c,
+    floatingArrowStyles: p,
+    changeFloatingVisibility: h
+  };
+}
+export {
+  F as useSbFloatingPanel
+};

package/dist/sb-floating-panel.umd.js

@@ -0,0 +1 @@
+(function(i,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("@floating-ui/vue"),require("vue")):typeof define=="function"&&define.amd?define(["exports","@floating-ui/vue","vue"],e):(i=typeof globalThis<"u"?globalThis:i||self,e(i.SbFloatingPanel={},i.FloatingUIVue,i.Vue))})(this,function(i,e,n){"use strict";function d(o){const a=n.ref(null),r=n.ref(null),c=n.ref(null),s=n.ref(!1),l=n.ref(null);let f=!1;const{floatingStyles:p,placement:h,middlewareData:m}=e.useFloating(a,r,{open:s,placement:o.placement,strategy:o.strategy,transform:!1,middleware:[e.offset(o.offsetValue),e.flip(),e.shift(),...o.hasArrow?[e.arrow({element:c})]:[]],whileElementsMounted:e.autoUpdate}),w=t=>{s.value=t},u=()=>{r.value&&a.value&&(r.value.style.width=`${a.value.offsetWidth}px`)};return n.watch(s,async t=>{t&&o.hasResize&&f&&(await n.nextTick(),u())}),n.watch(a,t=>{t&&o.hasResize&&!f&&(f=!0,l.value=new ResizeObserver(u),l.value.observe(t))}),n.onMounted(()=>{o.hasResize&&a.value&&(f=!0,l.value=new ResizeObserver(u),l.value.observe(a.value))}),n.onUnmounted(()=>{var t;o.hasResize&&((t=l.value)==null||t.disconnect())}),{reference:a,floating:r,popperArrow:c,isOpen:s,floatingPosition:h,floatingStyles:p,floatingArrowStyles:m,changeFloatingVisibility:w}}i.useSbFloatingPanel=d,Object.defineProperty(i,Symbol.toStringTag,{value:"Module"})});

package/dist/use-sb-floating-panel/useSbFloatingPanel.d.ts

@@ -0,0 +1,31 @@
+import { Placement, Strategy } from '@floating-ui/vue';
+interface FloatingSettings {
+    placement: Placement;
+    strategy: Strategy;
+    offsetValue: number;
+    hasArrow?: boolean;
+    hasResize?: boolean;
+}
+export declare function useSbFloatingPanel(settings: FloatingSettings): {
+    reference: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+    floating: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+    popperArrow: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+    isOpen: import('vue').Ref<boolean, boolean>;
+    floatingPosition: Readonly<import('vue').Ref<Placement, Placement>>;
+    floatingStyles: Readonly<import('vue').Ref<{
+        position: Strategy;
+        top: string;
+        left: string;
+        transform?: string;
+        willChange?: string;
+    }, {
+        position: Strategy;
+        top: string;
+        left: string;
+        transform?: string;
+        willChange?: string;
+    }>>;
+    floatingArrowStyles: Readonly<import('vue').Ref<import('@floating-ui/core').MiddlewareData, import('@floating-ui/core').MiddlewareData>>;
+    changeFloatingVisibility: (newState: boolean) => void;
+};
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "sb-floating-panel-vue",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/sb-floating-panel.es.js",
+      "require": "./dist/sb-floating-panel.umd.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint . --ext .ts",
+    "check": "vue-tsc --noEmit"
+  },
+  "keywords": [
+    "vue",
+    "floating-ui",
+    "hook",
+    "composable",
+    "floating panel"
+  ],
+  "author": "Stefano Biddau",
+  "license": "MIT",
+  "peerDependencies": {
+    "vue": "^3.5.13"
+  },
+  "dependencies": {
+    "@floating-ui/vue": "^1.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.17",
+    "@typescript-eslint/eslint-plugin": "^8.32.0",
+    "@typescript-eslint/parser": "^8.32.0",
+    "@vitejs/plugin-vue": "^5.2.4",
+    "eslint": "^9.26.0",
+    "eslint-plugin-prettier": "^5.4.0",
+    "eslint-plugin-vue": "^10.1.0",
+    "prettier": "^3.5.3",
+    "typescript": "~5.7.2",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.3",
+    "vue-tsc": "^2.2.10"
+  }
+}