sb-floating-panel-vue 0.1.5 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stefano Biddau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,158 +1,228 @@
 # 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)
+[![license](https://img.shields.io/npm/l/sb-floating-panel-vue.svg)](https://github.com/stefanBid/sb-floating-panel-vue/blob/main/LICENSE)
+[![Vue 3](https://img.shields.io/badge/vue-3.x-brightgreen.svg)](https://vuejs.org)
+[![build](https://img.shields.io/badge/build-passing-brightgreen.svg)](#)
+
+## 🔥 Features
+
+- 🧩 Floating panel positioning with arrow and smart shifting
+- ⚡ Built on top of [`@floating-ui/vue`](https://floating-ui.com/)
+- 🎯 Support for resize syncing and animated transitions
+- 🧪 Dual usage: composable or plug-and-play components
+
+---
+
+## 👤 Author
 
-> 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.
+Created with ❤️ by [Stefano Biddau](https://www.stefano-biddau.com/)
 
 ---
 
-## ✨ Features
+## ❓ Why This Library?
 
-- 📦 Minimal and composable API
-- 🎯 Precise floating panel positioning via `@floating-ui/vue`
-- 🎈 Optional arrow positioning
-- 📏 Auto-resize support
-- 🧠 TypeScript-first
+`sb-floating-panel-vue` was designed to make it extremely easy to implement dropdowns, tooltips, and floating panels in Vue 3, without worrying about placement logic, arrow positioning, or responsive syncing. It wraps `@floating-ui/vue` into a more ergonomic composable or ready-to-use components.
 
 ---
 
-## 🚀 Installation
+## 📦 Installation
 
 ```bash
+# npm
 npm install sb-floating-panel-vue
-# or
+
+# yarn
 yarn add sb-floating-panel-vue
+
+# pnpm
+pnpm add sb-floating-panel-vue
 ```
 
 ---
 
-## 🧩 Usage
+## 🧠 Composable Usage
 
-The `useSbFloatingPanel` composable provides an easy-to-integrate API to handle floating panels, such as tooltips, popovers, dropdowns, and other UI overlays.
+Use the composable `useSbFloatingPanel()` for complete control.
 
-### Importing
+### Options
+
+
+| Option      | Type       | Required | Default | Description                                      |
+|------------|------------|----------|---------|--------------------------------------------------|
+| placement  | `Placement` | Yes     | —       | Placement of the floating panel                 |
+| strategy   | `'absolute'` \| `'fixed'` | Yes | —       | CSS positioning strategy                        |
+| offsetValue| `number`    | Yes     | —       | Offset between reference and floating           |
+| hasArrow   | `boolean`   | No      | `false` | Whether to render arrow                         |
+| hasResize  | `boolean`   | No      | `false` | Sync width of floating to reference             |
+
+### Return Values
+
+| Property              | Type                                 | Description                            |
+|-----------------------|--------------------------------------|----------------------------------------|
+| reference             | `Ref<HTMLElement \| null>`           | Ref for the trigger element            |
+| floating              | `Ref<FloatingElement \| null>`       | Ref for the floating panel             |
+| floatingArrow         | `Ref<HTMLElement \| null>`           | Ref for the arrow element              |
+| floatingPlacement     | `Ref<Placement>`                     | The actual resolved placement          |
+| floatingStyle         | `ComputedRef<CSSProperties>`         | Style for the floating panel           |
+| floatingArrowStyle    | `ComputedRef<CSSProperties>`         | Style for the arrow                    |
+| isOpen                | `Ref<boolean>`                       | Panel visibility                       |
+| toggle / open / close | `() => void`                         | Control methods to toggle visibility   |
 
-```ts
-import { useSbFloatingPanel } from 'sb-floating-panel-vue';
-```
 
-### 🧠 API
+### Example
+In your Vue component, you can use the composable like this:
 
+In your script tag, import the composable and use it:
 ```ts
+import { useSbFloatingPanel } from 'sb-floating-panel-vue';
+
 const {
   reference,
   floating,
-  popperArrow,
+  floatingArrow,
+  floatingStyle,
+  floatingArrowStyle,
   isOpen,
-  floatingPosition,
-  floatingStyles,
-  floatingArrowStyles,
-  changeFloatingVisibility,
-} = useSbFloatingPanel(settings);
+  toggle,
+} = useSbFloatingPanel({
+  placement: 'bottom-start',
+  strategy: 'absolute',
+  offsetValue: 12,
+  hasArrow: true,
+});
 ```
+In your template, you can bind the refs and styles:
+```html
+<template>
+  <button ref="reference" @click="toggle()">Open Panel</button>
+  <div v-if="isOpen" ref="floating" :style="floatingStyle">
+    Panel
+    <div ref="floatingArrow" :style="floatingArrowStyle" />
+  </div>
+</template>
+```
+
+---
 
-### Parameters
+## 🧱 Component-Based Usage
 
-The composable takes a `settings` object:
+### Import the style
+
+If you use components, you **must** import styles in `main.ts`:
 
 ```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
-}
+import 'sb-floating-panel-vue/style.css';
 ```
 
----
+### Available Components
 
-## 🔍 Computed Values Explained
+#### `<SbContainer>`
 
-### `floatingStyles`
+Wraps everything and provides the context.
 
-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.
+| Prop        | Type                      | Default         | Description                                                                 |
+|-------------|---------------------------|-----------------|-----------------------------------------------------------------------------|
+| placement   | `Placement`               | `'bottom-start'`| Placement of the floating panel relative to the reference element          |
+| strategy    | `'absolute' \| 'fixed'`   | `'absolute'`    | CSS positioning strategy for the floating panel                            |
+| offsetValue | `number`                  | `15`            | Offset in pixels between reference and floating panel                      |
+| hasArrow    | `boolean`                 | `false`         | Whether to render an arrow pointing to the reference                       |
+| hasResize   | `boolean`                 | `false`         | Whether the floating panel should sync its width with the reference        |
 
-### `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`
+#### `<SbReference>`
 
-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.
+Trigger element
 
----
+| Prop         | Type                              | Default      | Description                                                                  |
+|--------------|-----------------------------------|--------------|------------------------------------------------------------------------------|
+| referenceRef | `Ref<HTMLElement \| null>`        | **required** | Reference element to which the floating panel is attached                   |
+| as           | `'button' \| 'div' \| 'span' \| etc.` | `'button'`   | HTML tag to render. Defaults to `<button>` for accessibility                |
+| onClick      | `() => void`                      | —            | Optional click handler, often used to toggle the floating panel visibility  |
 
-## 🧪 Example
 
-```ts
-<script setup lang="ts">
-import { ref } from 'vue';
-import { useSbFloatingPanel } from 'sb-floating-panel-vue';
+#### `<SbFloating>`
 
-const {
-  reference,
-  floating,
-  popperArrow,
-  isOpen,
-  floatingStyles,
-  floatingArrowStyles,
-  changeFloatingVisibility,
-} = useSbFloatingPanel({
-  placement: 'bottom',
-  strategy: 'absolute',
-  offsetValue: 8,
-  hasArrow: true,
-  hasResize: true,
-});
+Floating panel
+
+| Prop                | Type                                         | Default         | Description                                                                 |
+|---------------------|----------------------------------------------|-----------------|-----------------------------------------------------------------------------|
+| floatingRef         | `Ref<HTMLElement \| null>`                   | **required**    | The target element for the floating panel (popover, tooltip, etc.)         |
+| floatingArrowRef    | `Ref<HTMLElement \| null>`                   | optional        | The element used as the floating arrow                                     |
+| isOpen              | `boolean`                                    | **required**    | Controls visibility of the floating panel                                  |
+| floatingPlacement   | `Placement`                                  | **required**    | Current placement as resolved by `@floating-ui/vue`                        |
+| floatingStyle       | `CSSProperties`                              | **required**    | Inline style object applied to the floating panel                          |
+| floatingArrowStyle  | `CSSProperties`                              | optional        | Inline style object applied to the arrow element                           |
+| arrowDimensions     | `number`                                     | optional        | Size (width/height) of the arrow in pixels                                 |
+| zIndex              | `number`                                     | `undefined`     | Custom z-index applied to the floating and arrow elements                  |
+| animation           | `'fade' \| 'scale-fade' \| 'none'`           | `'scale-fade'`  | Defines the animation style for enter/leave transitions                    |
+| duration            | `number`                                     | `300`           | Duration in ms for the transition animations                               |
+
+
+---
+
+### 🧪 Component Usage Example
 
-const togglePanel = () => {
-  changeFloatingVisibility(!isOpen.value);
-};
-</script>
+In your project, you can use the components like this:
+
+In your script tag, import the components:
+```ts
+import { SbContainer, SbFloating, SbReference } from 'sb-floating-panel-vue';
 ```
 
-```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>
+In your template, you can use the components as follows:
+```html
+<SbContainer :has-arrow="true" strategy="fixed">
+  <template #default="{
+    reference,
+    floating,
+    floatingArrow,
+    floatingPlacement,
+    floatingStyle,
+    floatingArrowStyle,
+    isOpen,
+    toggle
+  }">
+    <SbReference :reference-ref="reference" :onClick="toggle">Toggle</SbReference>
+    <SbFloating
+      :is-open="isOpen.value"
+      :floating-ref="floating"
+      :floating-arrow-ref="floatingArrow"
+      :floating-placement="floatingPlacement.value"
+      :floating-style="floatingStyle.value"
+      :floating-arrow-style="floatingArrowStyle.value"
+      :arrow-dimensions="12"
+      :z-index="200"
+    >
+      Hello Panel!
+    </SbFloating>
+  </template>
+</SbContainer>
 ```
 
 ---
 
-## 🎨 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;
-}
+## ⚠️ Directive Note (Teleport Limitation)
+
+Due to `<teleport>` in `<SbFloating>`, if you apply custom directives directly to the component, Vue will warn:
+
+```
+[Vue warn]: Extraneous non-props attributes ([directive-name]) were passed to component but could not be automatically inherited because component renders fragment or text or teleport root nodes.
+```
+
+**Solution**: Move the directive to an inner element using the slot.
+
+### Example Fix
+
+```vue
+<SbFloating ...>
+  <div v-click-outside>...</div>
+</SbFloating>
 ```
 
 ---
 
 ## 📄 License
 
-MIT © [Stefano Biddau](https://github.com/stefanobiddau)
+[MIT License](https://github.com/stefanBid/sb-floating-panel-vue/blob/main/LICENSE) © [Stefano Biddau](https://www.stefano-biddau.com/)

package/dist/components/SbContainer.vue.d.ts

@@ -0,0 +1,66 @@
+import { Placement, Strategy } from '@floating-ui/vue';
+/**
+ * Props for the SbContainer component.
+ * Serves as a controller and provider for the floating panel system.
+ */
+interface SbContainerProps {
+    /**
+     * Placement of the floating panel relative to the reference.
+     * @default 'bottom-start'
+     */
+    placement?: Placement;
+    /**
+     * Positioning strategy to use ('absolute' or 'fixed').
+     * @default 'absolute'
+     */
+    strategy?: Strategy;
+    /**
+     * Pixel offset between the reference and floating panel.
+     * @default 15
+     */
+    offsetValue?: number;
+    /**
+     * Whether to render an arrow pointing toward the reference element.
+     * @default false
+     */
+    hasArrow?: boolean;
+    /**
+     * When true, syncs the floating panel width to the reference width.
+     * @default false
+     */
+    hasResize?: boolean;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {
+            reference: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+            floating: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+            floatingArrow: import('vue').Ref<HTMLElement | null, HTMLElement | null>;
+            floatingPlacement: import('vue').Ref<Placement, Placement>;
+            floatingStyle: import('vue').ComputedRef<import('vue').CSSProperties>;
+            floatingArrowStyle: import('vue').ComputedRef<import('vue').CSSProperties>;
+            isOpen: import('vue').Ref<boolean, boolean>;
+            toggle: () => void;
+            open: () => void;
+            close: () => void;
+        }): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<SbContainerProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<SbContainerProps> & Readonly<{}>, {
+    placement: Placement;
+    strategy: Strategy;
+    offsetValue: number;
+    hasArrow: boolean;
+    hasResize: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/SbFloating.vue.d.ts

@@ -0,0 +1,76 @@
+import { Placement } from '@floating-ui/vue';
+import { CSSProperties, Ref } from 'vue';
+/**
+ * Props for the SbFloating component.
+ * This component renders the floating panel and (optionally) its arrow using teleport.
+ */
+interface SbFloatingProps {
+    /**
+     * The ref to bind to the floating panel element.
+     */
+    floatingRef: Ref<HTMLElement | null>;
+    /**
+     * Optional ref to bind to the floating arrow element.
+     */
+    floatingArrowRef?: Ref<HTMLElement | null>;
+    /**
+     * Whether the floating panel is open (visible).
+     */
+    isOpen: boolean;
+    /**
+     * The final placement resolved by Floating UI (e.g., 'bottom-start').
+     */
+    floatingPlacement: Placement;
+    /**
+     * Computed inline styles for the floating panel.
+     */
+    floatingStyle: CSSProperties;
+    /**
+     * Computed inline styles for the floating arrow (optional).
+     */
+    floatingArrowStyle?: CSSProperties;
+    /**
+     * Optional dimension (width & height) of the floating arrow.
+     * If provided, will override default arrow size.
+     */
+    arrowDimensions?: number;
+    /**
+     * Optional z-index to apply to the floating panel and arrow.
+     */
+    zIndex?: number;
+    /**
+     * Animation name used in Vue <transition>.
+     * Supported values: 'fade', 'scale-fade', 'none'.
+     * @default 'scale-fade'
+     */
+    animation?: 'fade' | 'scale-fade' | 'none';
+    /**
+     * Duration of the transition animation in milliseconds.
+     * @default 300
+     */
+    duration?: number;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<SbFloatingProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<SbFloatingProps> & Readonly<{}>, {
+    floatingArrowStyle: CSSProperties;
+    floatingArrowRef: Ref<HTMLElement | null>;
+    arrowDimensions: number;
+    zIndex: number;
+    animation: "fade" | "scale-fade" | "none";
+    duration: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/SbReference.vue.d.ts

@@ -0,0 +1,41 @@
+import { Ref } from 'vue';
+/**
+ * Props for the SbReference component.
+ * Renders the reference element for the floating panel system.
+ */
+interface SbReferenceProps {
+    /**
+     * The ref to bind to the reference DOM element.
+     */
+    referenceRef: Ref<HTMLElement | null>;
+    /**
+     * HTML tag to render as the reference.
+     * Useful for accessibility and customization.
+     * @default 'button'
+     */
+    as?: 'button' | 'a' | 'div' | 'span';
+    /**
+     * Optional click handler for toggling the floating panel.
+     */
+    onClick?: () => void;
+}
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<SbReferenceProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<SbReferenceProps> & Readonly<{}>, {
+    onClick: () => void;
+    as: "button" | "a" | "div" | "span";
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/composables/useSbFloatingPanel.d.ts

@@ -0,0 +1,81 @@
+import { FloatingElement, Placement, Strategy } from '@floating-ui/vue';
+import { CSSProperties, Ref, ComputedRef } from 'vue';
+/**
+ * Configuration options for the `useSbFloatingPanel` composable.
+ */
+interface FloatingSettings {
+    /**
+     * Defines the preferred placement of the floating element relative to the reference.
+     * Example: 'top', 'bottom-start', 'right-end', etc.
+     */
+    placement: Placement;
+    /**
+     * Determines the positioning strategy for the floating element.
+     * Can be either 'absolute' or 'fixed'.
+     */
+    strategy: Strategy;
+    /**
+     * Specifies the distance (in pixels) between the reference and floating elements.
+     */
+    offsetValue: number;
+    /**
+     * Enables the use of a directional arrow pointing from the floating element to the reference.
+     */
+    hasArrow?: boolean;
+    /**
+     * When enabled, synchronizes the width of the floating element to match the reference element.
+     * Useful for dropdowns or inputs.
+     */
+    hasResize?: boolean;
+}
+/**
+ * `useSbFloatingPanel` is a composable that wraps Floating UI logic to manage
+ * floating elements with optional arrow and dynamic width support.
+ *
+ * It provides bindings and style objects ready to apply to your `ref` elements in Vue templates.
+ *
+ * @param settings - Configuration options for placement, offset, and behavior.
+ * @returns Bindings and utility functions to control the floating panel.
+ *
+ * @example
+ * ```ts
+ * const {
+ *   reference,
+ *   floating,
+ *   floatingArrow,
+ *   floatingPlacement,
+ *   floatingStyle,
+ *   floatingArrowStyle,
+ *   isOpen,
+ *   toggle,
+ *   open,
+ *   close
+ * } = useSbFloatingPanel({
+ *   placement: 'bottom',
+ *   strategy: 'absolute',
+ *   offsetValue: 10,
+ *   hasArrow: true,
+ *   hasResize: false
+ * });
+ * ```
+ *
+ * @example
+ * ```html
+ * <div ref="reference">Anchor</div>
+ * <div ref="floating" v-if="isOpen">Panel</div>
+ * <div ref="floatingArrow" v-if="isOpen">Arrow</div>
+ * ```
+ */
+export declare function useSbFloatingPanel(settings: FloatingSettings): {
+    reference: Ref<HTMLElement | null>;
+    floating: Ref<FloatingElement | null>;
+    floatingArrow: Ref<HTMLElement | null>;
+    floatingPlacement: Ref<Placement>;
+    floatingStyle: ComputedRef<CSSProperties>;
+    floatingArrowStyle: ComputedRef<CSSProperties>;
+    isOpen: Ref<boolean>;
+    toggle: () => void;
+    open: () => void;
+    close: () => void;
+};
+export {};

package/dist/index.d.ts

@@ -1 +1,4 @@
-export { useSbFloatingPanel } from './use-sb-floating-panel/useSbFloatingPanel';
+export { useSbFloatingPanel } from './composables/useSbFloatingPanel';
+export { default as SbContainer } from './components/SbContainer.vue';
+export { default as SbReference } from './components/SbReference.vue';
+export { default as SbFloating } from './components/SbFloating.vue';

package/dist/sb-floating-panel-vue.css

@@ -0,0 +1 @@
+.floating-container[data-v-33e40585]{width:fit-content;height:fit-content}.fade-enter-active[data-v-366682ad],.fade-leave-active[data-v-366682ad]{transition:opacity var(--sb-transition-duration) ease-in-out}.fade-enter-from[data-v-366682ad],.fade-leave-to[data-v-366682ad]{opacity:0}.fade-enter-to[data-v-366682ad],.fade-leave-from[data-v-366682ad]{opacity:1}.scale-fade-enter-active[data-v-366682ad],.scale-fade-leave-active[data-v-366682ad]{transition:opacity var(--sb-transition-duration) ease-in-out,transform var(--sb-transition-duration) ease-in-out}.scale-fade-enter-from[data-v-366682ad],.scale-fade-leave-to[data-v-366682ad]{opacity:0;transform:scale(.95)}.scale-fade-enter-to[data-v-366682ad],.scale-fade-leave-from[data-v-366682ad]{opacity:1;transform:scale(1)}

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

@@ -1,45 +1,219 @@
-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,
+import { useFloating as V, autoUpdate as B, offset as M, flip as T, shift as W, arrow as D } from "@floating-ui/vue";
+import { ref as c, computed as u, watch as S, onMounted as E, onUnmounted as K, nextTick as N, defineComponent as k, createElementBlock as x, openBlock as v, renderSlot as z, normalizeProps as U, guardReactiveProps as j, createBlock as A, resolveDynamicComponent as q, mergeProps as $, withKeys as _, withModifiers as w, withCtx as C, useAttrs as G, Teleport as H, createVNode as J, Transition as L, createCommentVNode as R, unref as Q, normalizeStyle as X } from "vue";
+function Y(a) {
+  const e = c(null), l = c(null), r = c(null), o = c(!1), s = c(null);
+  let t = !1;
+  const { floatingStyles: f, placement: i, middlewareData: m } = V(e, l, {
+    open: o,
     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());
+    middleware: [M(a.offsetValue), T(), W(), D({ element: r })],
+    whileElementsMounted: B
+  }), d = (n) => {
+    o.value = n;
+  }, b = () => d(!0), y = () => d(!1), h = () => d(!o.value), g = () => {
+    l.value && e.value && (l.value.style.width = `${e.value.offsetWidth}px`);
+  }, O = u(() => ({
+    ...f.value
+  })), P = u(() => {
+    const n = m.value.arrow, F = i.value.split("-")[0], p = {
+      position: "absolute",
+      transform: "rotate(45deg)",
+      background: "inherit",
+      width: "8px",
+      height: "8px",
+      left: (n == null ? void 0 : n.x) != null ? `${n.x}px` : "",
+      top: (n == null ? void 0 : n.y) != null ? `${n.y}px` : ""
+    };
+    switch (F) {
+      case "top":
+        p.bottom = "-4px";
+        break;
+      case "bottom":
+        p.top = "-4px";
+        break;
+      case "left":
+        p.right = "-4px";
+        break;
+      case "right":
+        p.left = "-4px";
+        break;
+    }
+    return p;
+  });
+  return S(o, async (n) => {
+    n && a.hasResize && t && (await N(), g());
+  }), S(e, (n) => {
+    n && a.hasResize && !t && (t = !0, s.value = new ResizeObserver(g), s.value.observe(n));
+  }), E(() => {
+    a.hasResize && e.value && (t = !0, s.value = new ResizeObserver(g), s.value.observe(e.value));
+  }), K(() => {
+    var n;
+    a.hasResize && ((n = s.value) == null || n.disconnect());
   }), {
-    reference: l,
-    floating: n,
-    popperArrow: u,
-    isOpen: r,
-    floatingPosition: v,
-    floatingStyles: c,
-    floatingArrowStyles: p,
-    changeFloatingVisibility: h
+    reference: e,
+    floating: l,
+    floatingArrow: r,
+    floatingPlacement: i,
+    floatingStyle: O,
+    floatingArrowStyle: P,
+    isOpen: o,
+    toggle: h,
+    open: b,
+    close: y
   };
 }
+const Z = { class: "floating-container" }, ee = /* @__PURE__ */ k({
+  __name: "SbContainer",
+  props: {
+    placement: { default: "bottom-start" },
+    strategy: { default: "absolute" },
+    offsetValue: { default: 15 },
+    hasArrow: { type: Boolean, default: !1 },
+    hasResize: { type: Boolean, default: !1 }
+  },
+  setup(a) {
+    const e = a, {
+      isOpen: l,
+      reference: r,
+      floating: o,
+      floatingArrow: s,
+      floatingPlacement: t,
+      floatingStyle: f,
+      floatingArrowStyle: i,
+      toggle: m,
+      open: d,
+      close: b
+    } = Y({
+      placement: e.placement,
+      strategy: e.strategy,
+      offsetValue: e.offsetValue,
+      hasArrow: e.hasArrow,
+      hasResize: e.hasResize
+    }), y = {
+      reference: r,
+      floating: o,
+      floatingArrow: s,
+      floatingPlacement: t,
+      floatingStyle: f,
+      floatingArrowStyle: i,
+      isOpen: l,
+      toggle: m,
+      open: d,
+      close: b
+    };
+    return (h, g) => (v(), x("div", Z, [
+      z(h.$slots, "default", U(j(y)), void 0, !0)
+    ]));
+  }
+}), I = (a, e) => {
+  const l = a.__vccOpts || a;
+  for (const [r, o] of e)
+    l[r] = o;
+  return l;
+}, ae = /* @__PURE__ */ I(ee, [["__scopeId", "data-v-33e40585"]]), le = /* @__PURE__ */ k({
+  __name: "SbReference",
+  props: {
+    referenceRef: {},
+    as: { default: "button" },
+    onClick: { type: Function, default: void 0 }
+  },
+  setup(a) {
+    const e = a, l = u(() => e.as === "button" || e.as === "a");
+    return (r, o) => (v(), A(q(e.as), $(r.$attrs, {
+      ref: e.referenceRef,
+      role: l.value ? "button" : void 0,
+      tabindex: l.value ? 0 : void 0,
+      onClick: o[0] || (o[0] = w((s) => {
+        var t;
+        return (t = e.onClick) == null ? void 0 : t.call(e);
+      }, ["stop"])),
+      onKeydown: [
+        o[1] || (o[1] = _(w((s) => {
+          var t;
+          return l.value && ((t = e.onClick) == null ? void 0 : t.call(e));
+        }, ["prevent", "stop"]), ["space"])),
+        o[2] || (o[2] = _(w((s) => {
+          var t;
+          return l.value && ((t = e.onClick) == null ? void 0 : t.call(e));
+        }, ["prevent", "stop"]), ["enter"]))
+      ]
+    }), {
+      default: C(() => [
+        z(r.$slots, "default")
+      ]),
+      _: 3
+    }, 16, ["role", "tabindex"]));
+  }
+}), te = /* @__PURE__ */ k({
+  inheritAttrs: !1,
+  __name: "SbFloating",
+  props: {
+    floatingRef: {},
+    floatingArrowRef: { default: () => c(null) },
+    isOpen: { type: Boolean },
+    floatingPlacement: {},
+    floatingStyle: {},
+    floatingArrowStyle: { default: void 0 },
+    arrowDimensions: { default: void 0 },
+    zIndex: { default: void 0 },
+    animation: { default: "scale-fade" },
+    duration: { default: 300 }
+  },
+  setup(a) {
+    const e = a, l = G(), r = u(() => {
+      const t = {
+        ...e.floatingStyle,
+        "--sb-transition-duration": e.duration + "ms"
+      };
+      return e.zIndex !== void 0 && (t.zIndex = e.zIndex), t;
+    }), o = u(() => {
+      const t = { ...e.floatingArrowStyle || {} };
+      if (e.arrowDimensions) {
+        const f = e.arrowDimensions, i = `-${f / 2}px`;
+        switch (e.floatingPlacement.split("-")[0]) {
+          case "top":
+            t.bottom = i;
+            break;
+          case "bottom":
+            t.top = i;
+            break;
+          case "left":
+            t.right = i;
+            break;
+          case "right":
+            t.left = i;
+            break;
+        }
+        t.width = `${f}px`, t.height = `${f}px`;
+      }
+      return e.zIndex !== void 0 && (t.zIndex = e.zIndex), t;
+    }), s = u(() => e.animation === "fade" ? "fade" : e.animation === "scale-fade" ? "scale-fade" : "");
+    return (t, f) => (v(), A(H, { to: "body" }, [
+      J(L, { name: s.value }, {
+        default: C(() => [
+          e.isOpen ? (v(), x("div", $({
+            key: 0,
+            ref: e.floatingRef,
+            style: r.value
+          }, Q(l)), [
+            z(t.$slots, "default", {}, void 0, !0),
+            e.floatingArrowRef ? (v(), x("div", {
+              key: 0,
+              ref: e.floatingArrowRef,
+              style: X(o.value)
+            }, null, 4)) : R("", !0)
+          ], 16)) : R("", !0)
+        ]),
+        _: 3
+      }, 8, ["name"])
+    ]));
+  }
+}), se = /* @__PURE__ */ I(te, [["__scopeId", "data-v-366682ad"]]);
 export {
-  F as useSbFloatingPanel
+  ae as SbContainer,
+  se as SbFloating,
+  le as SbReference,
+  Y as useSbFloatingPanel
 };

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

@@ -1 +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"})});
+(function(s,c){typeof exports=="object"&&typeof module<"u"?c(exports,require("@floating-ui/vue"),require("vue")):typeof define=="function"&&define.amd?define(["exports","@floating-ui/vue","vue"],c):(s=typeof globalThis<"u"?globalThis:s||self,c(s.SbFloatingPanelVue={},s.FloatingUIVue,s.Vue))})(this,function(s,c,e){"use strict";function k(l){const t=e.ref(null),i=e.ref(null),f=e.ref(null),n=e.ref(!1),r=e.ref(null);let o=!1;const{floatingStyles:p,placement:d,middlewareData:g}=c.useFloating(t,i,{open:n,placement:l.placement,strategy:l.strategy,transform:!1,middleware:[c.offset(l.offsetValue),c.flip(),c.shift(),c.arrow({element:f})],whileElementsMounted:c.autoUpdate}),u=a=>{n.value=a},h=()=>u(!0),y=()=>u(!1),w=()=>u(!n.value),b=()=>{i.value&&t.value&&(i.value.style.width=`${t.value.offsetWidth}px`)},C=e.computed(()=>({...p.value})),B=e.computed(()=>{const a=g.value.arrow,P=d.value.split("-")[0],m={position:"absolute",transform:"rotate(45deg)",background:"inherit",width:"8px",height:"8px",left:(a==null?void 0:a.x)!=null?`${a.x}px`:"",top:(a==null?void 0:a.y)!=null?`${a.y}px`:""};switch(P){case"top":m.bottom="-4px";break;case"bottom":m.top="-4px";break;case"left":m.right="-4px";break;case"right":m.left="-4px";break}return m});return e.watch(n,async a=>{a&&l.hasResize&&o&&(await e.nextTick(),b())}),e.watch(t,a=>{a&&l.hasResize&&!o&&(o=!0,r.value=new ResizeObserver(b),r.value.observe(a))}),e.onMounted(()=>{l.hasResize&&t.value&&(o=!0,r.value=new ResizeObserver(b),r.value.observe(t.value))}),e.onUnmounted(()=>{var a;l.hasResize&&((a=r.value)==null||a.disconnect())}),{reference:t,floating:i,floatingArrow:f,floatingPlacement:d,floatingStyle:C,floatingArrowStyle:B,isOpen:n,toggle:w,open:h,close:y}}const x={class:"floating-container"},_=e.defineComponent({__name:"SbContainer",props:{placement:{default:"bottom-start"},strategy:{default:"absolute"},offsetValue:{default:15},hasArrow:{type:Boolean,default:!1},hasResize:{type:Boolean,default:!1}},setup(l){const t=l,{isOpen:i,reference:f,floating:n,floatingArrow:r,floatingPlacement:o,floatingStyle:p,floatingArrowStyle:d,toggle:g,open:u,close:h}=k({placement:t.placement,strategy:t.strategy,offsetValue:t.offsetValue,hasArrow:t.hasArrow,hasResize:t.hasResize}),y={reference:f,floating:n,floatingArrow:r,floatingPlacement:o,floatingStyle:p,floatingArrowStyle:d,isOpen:i,toggle:g,open:u,close:h};return(w,b)=>(e.openBlock(),e.createElementBlock("div",x,[e.renderSlot(w.$slots,"default",e.normalizeProps(e.guardReactiveProps(y)),void 0,!0)]))}}),S=(l,t)=>{const i=l.__vccOpts||l;for(const[f,n]of t)i[f]=n;return i},z=S(_,[["__scopeId","data-v-33e40585"]]),R=e.defineComponent({__name:"SbReference",props:{referenceRef:{},as:{default:"button"},onClick:{type:Function,default:void 0}},setup(l){const t=l,i=e.computed(()=>t.as==="button"||t.as==="a");return(f,n)=>(e.openBlock(),e.createBlock(e.resolveDynamicComponent(t.as),e.mergeProps(f.$attrs,{ref:t.referenceRef,role:i.value?"button":void 0,tabindex:i.value?0:void 0,onClick:n[0]||(n[0]=e.withModifiers(r=>{var o;return(o=t.onClick)==null?void 0:o.call(t)},["stop"])),onKeydown:[n[1]||(n[1]=e.withKeys(e.withModifiers(r=>{var o;return i.value&&((o=t.onClick)==null?void 0:o.call(t))},["prevent","stop"]),["space"])),n[2]||(n[2]=e.withKeys(e.withModifiers(r=>{var o;return i.value&&((o=t.onClick)==null?void 0:o.call(t))},["prevent","stop"]),["enter"]))]}),{default:e.withCtx(()=>[e.renderSlot(f.$slots,"default")]),_:3},16,["role","tabindex"]))}}),A=S(e.defineComponent({inheritAttrs:!1,__name:"SbFloating",props:{floatingRef:{},floatingArrowRef:{default:()=>e.ref(null)},isOpen:{type:Boolean},floatingPlacement:{},floatingStyle:{},floatingArrowStyle:{default:void 0},arrowDimensions:{default:void 0},zIndex:{default:void 0},animation:{default:"scale-fade"},duration:{default:300}},setup(l){const t=l,i=e.useAttrs(),f=e.computed(()=>{const o={...t.floatingStyle,"--sb-transition-duration":t.duration+"ms"};return t.zIndex!==void 0&&(o.zIndex=t.zIndex),o}),n=e.computed(()=>{const o={...t.floatingArrowStyle||{}};if(t.arrowDimensions){const p=t.arrowDimensions,d=`-${p/2}px`;switch(t.floatingPlacement.split("-")[0]){case"top":o.bottom=d;break;case"bottom":o.top=d;break;case"left":o.right=d;break;case"right":o.left=d;break}o.width=`${p}px`,o.height=`${p}px`}return t.zIndex!==void 0&&(o.zIndex=t.zIndex),o}),r=e.computed(()=>t.animation==="fade"?"fade":t.animation==="scale-fade"?"scale-fade":"");return(o,p)=>(e.openBlock(),e.createBlock(e.Teleport,{to:"body"},[e.createVNode(e.Transition,{name:r.value},{default:e.withCtx(()=>[t.isOpen?(e.openBlock(),e.createElementBlock("div",e.mergeProps({key:0,ref:t.floatingRef,style:f.value},e.unref(i)),[e.renderSlot(o.$slots,"default",{},void 0,!0),t.floatingArrowRef?(e.openBlock(),e.createElementBlock("div",{key:0,ref:t.floatingArrowRef,style:e.normalizeStyle(n.value)},null,4)):e.createCommentVNode("",!0)],16)):e.createCommentVNode("",!0)]),_:3},8,["name"])]))}}),[["__scopeId","data-v-366682ad"]]);s.SbContainer=z,s.SbFloating=A,s.SbReference=R,s.useSbFloatingPanel=k,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -1,7 +1,38 @@
 {
   "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.",
+  "version": "1.0.0",
+  "description": "A flexible and lightweight Vue 3 floating panel system powered by @floating-ui/vue — includes composable hooks and plug-and-play components with arrow and resize support.",
+  "keywords": [
+    "vue",
+    "vue3",
+    "floating-ui",
+    "floating panel",
+    "tooltip",
+    "popover",
+    "dropdown",
+    "floating",
+    "positioning",
+    "arrow",
+    "teleport",
+    "resize",
+    "resize-observer",
+    "vue-components",
+    "composable",
+    "vue-library"
+  ],
+  "author": {
+    "name": "Stefano Biddau",
+    "url": "https://www.stefano-biddau.com"
+  },
+  "license": "MIT",
+    "repository": {
+    "type": "git",
+    "url": "https://github.com/stefanBid/sb-floating-panel-vue"
+  },
+  "bugs": {
+    "url": "https://github.com/stefanBid/sb-floating-panel-vue/issues"
+  },
+  "homepage": "https://github.com/stefanBid/sb-floating-panel-vue#readme",
   "main": "dist/sb-floating-panel.umd.js",
   "module": "dist/sb-floating-panel.es.js",
   "types": "dist/index.d.ts",
@@ -10,26 +41,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/sb-floating-panel.es.js",
       "require": "./dist/sb-floating-panel.umd.js"
+    },
+    "./style.css": {
+      "default": "./dist/sb-floating-panel-vue.css"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": ["dist/index.d.ts"]
     }
   },
   "files": [
     "dist"
   ],
+  "sideEffects": false,
   "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"
   },
@@ -37,13 +68,14 @@
     "@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",
+    "@types/node": "^22.15.18",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
     "@vitejs/plugin-vue": "^5.2.4",
     "eslint": "^9.26.0",
     "eslint-plugin-prettier": "^5.4.0",
     "eslint-plugin-vue": "^10.1.0",
+    "vue-eslint-parser": "10.1.3",
     "prettier": "^3.5.3",
     "typescript": "~5.7.2",
     "vite": "^6.3.5",

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

@@ -1,31 +0,0 @@
-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 {};