@fiscozen/composables 0.1.38 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscozen/composables",
-  "version": "0.1.38",
+  "version": "1.0.0",
   "description": "Design System utility composables",
   "main": "src/index.ts",
   "type": "module",
@@ -28,9 +28,9 @@
     "vite": "^5.0.10",
     "vitest": "^1.2.0",
     "vue-tsc": "^1.8.25",
+    "@fiscozen/prettier-config": "^0.1.0",
     "@fiscozen/tsconfig": "^0.1.0",
-    "@fiscozen/eslint-config": "^0.1.0",
-    "@fiscozen/prettier-config": "^0.1.0"
+    "@fiscozen/eslint-config": "^0.1.0"
   },
   "license": "ISC",
   "scripts": {

package/src/FzFloating.vue

@@ -1,5 +1,32 @@
 <script lang="ts" setup>
-import { ref, useSlots, watch, toRef, computed, onBeforeUnmount, toRefs, defineExpose } from 'vue'
+/**
+ * FzFloating Component
+ * 
+ * A floating container that positions itself relative to an opener element.
+ * Supports automatic repositioning on scroll, resize, and content changes.
+ * 
+ * ## Features
+ * - 12 positioning options (top/bottom/left/right with start/center/end alignment)
+ * - Auto-positioning based on available viewport space  
+ * - Reactive repositioning via ResizeObserver
+ * - Teleport support for z-index stacking context issues
+ * - Automatic margin based on resolved position direction
+ * 
+ * ## Slots
+ * - `opener`: The element that triggers/anchors the floating content
+ * - `default`: The floating content to display
+ * 
+ * ## Example
+ * ```vue
+ * <FzFloating position="bottom-start" :isOpen="showMenu">
+ *   <template #opener>
+ *     <button @click="showMenu = !showMenu">Menu</button>
+ *   </template>
+ *   <div>Menu content here</div>
+ * </FzFloating>
+ * ```
+ */
+import { ref, useSlots, watch, toRef, computed, onBeforeUnmount, onMounted, toRefs } from 'vue'
 import { useFloating } from './composables'
 import { FzFloatingProps, FzUseFloatingArgs } from './types'
 import { useMediaQuery } from './composables'
@@ -21,6 +48,11 @@ const slots = useSlots()
 const xs = useMediaQuery(`(max-width: ${breakpoints.xs})`)
 
 let scheduledAnimationFrame = false
+let isMounted = false
+
+// Observers for reactive repositioning
+let resizeObserver: ResizeObserver | null = null
+let openerResizeObserver: ResizeObserver | null = null
 
 const useFloatingOpts: FzUseFloatingArgs = {
   position: props.position,
@@ -52,17 +84,72 @@ if (slots.opener) {
 const floating = useFloating(dynamicOpts)
 
 const setPositionWhenOpen = () => {
-  if (scheduledAnimationFrame) {
+  if (scheduledAnimationFrame || !isMounted) {
     return
   }
 
   scheduledAnimationFrame = true
   requestAnimationFrame(() => {
-    props.isOpen && floating.setPosition()
+    if (isMounted && props.isOpen) {
+      floating.setPosition()
+    }
     scheduledAnimationFrame = false
   })
 }
 
+onMounted(() => {
+  isMounted = true
+})
+
+// Scroll handler that catches scroll events on any scrollable parent
+const handleScroll = () => {
+  setPositionWhenOpen()
+}
+
+// Window resize handler
+const handleResize = () => {
+  setPositionWhenOpen()
+}
+
+// Setup all event listeners and observers
+const setupEventListeners = () => {
+  // Window scroll and resize
+  window.addEventListener('scroll', handleScroll, true) // capture phase for nested scrollables
+  window.addEventListener('resize', handleResize)
+
+  // ResizeObserver for floating content (handles content size changes)
+  if (content.value && !resizeObserver) {
+    resizeObserver = new ResizeObserver(() => {
+      setPositionWhenOpen()
+    })
+    resizeObserver.observe(content.value)
+  }
+
+  // ResizeObserver for opener (handles opener size/position changes)
+  if (opener.value && !openerResizeObserver) {
+    openerResizeObserver = new ResizeObserver(() => {
+      setPositionWhenOpen()
+    })
+    openerResizeObserver.observe(opener.value)
+  }
+}
+
+// Cleanup all event listeners and observers
+const cleanupEventListeners = () => {
+  window.removeEventListener('scroll', handleScroll, true)
+  window.removeEventListener('resize', handleResize)
+
+  if (resizeObserver) {
+    resizeObserver.disconnect()
+    resizeObserver = null
+  }
+
+  if (openerResizeObserver) {
+    openerResizeObserver.disconnect()
+    openerResizeObserver = null
+  }
+}
+
 watch(
   () => props.position,
   () => setPositionWhenOpen()
@@ -70,11 +157,13 @@ watch(
 watch(
   () => props.isOpen,
   (newVal) => {
-    if (!newVal || !content.value) {
-      window.removeEventListener('scroll', setPositionWhenOpen)
+    if (!newVal || !content.value || !isMounted) {
+      cleanupEventListeners()
       return
     }
-    window.addEventListener('scroll', setPositionWhenOpen)
+    
+    setupEventListeners()
+    
     const openerRect = opener.value?.getBoundingClientRect()
     // CRITICAL: Set position fixed immediately to prevent layout shift
     content.value.style.position = 'fixed'
@@ -98,8 +187,26 @@ watch(
     }
   }
 )
+
 onBeforeUnmount(() => {
-  window.removeEventListener('scroll', setPositionWhenOpen)
+  isMounted = false
+  cleanupEventListeners()
+})
+
+// Helper function to get margin class from position
+const getMarginClassForPosition = (position: string): string => {
+  if (position.startsWith('bottom')) return 'mt-4' // margin-top only
+  if (position.startsWith('top')) return 'mb-4'    // margin-bottom only
+  if (position.startsWith('left')) return 'mr-4'   // margin-right only
+  if (position.startsWith('right')) return 'ml-4'  // margin-left only
+  return 'mt-4' // default fallback
+}
+
+// Computed margin class based on resolved position
+// Uses actualPosition for auto positions, falls back to props.position for explicit
+const resolvedMarginClass = computed(() => {
+  const effectivePosition = floating.actualPosition?.value ?? props.position
+  return getMarginClassForPosition(effectivePosition)
 })
 
 const contentClass = computed(() => {
@@ -107,7 +214,7 @@ const contentClass = computed(() => {
     return props.contentClass
   }
 
-  return ['bg-core-white fixed p-4', props.contentClass]
+  return ['bg-core-white fixed', resolvedMarginClass.value, props.contentClass]
 })
 
 defineExpose({

package/src/composables/useCurrency.ts

@@ -1,119 +1,13 @@
-import { Ref, watch, getCurrentInstance, computed, ref, nextTick } from 'vue'
 import { FzUseCurrencyOptions } from '../types'
-import { format as formatNumber, parse, roundTo } from '../utils'
-
-export const useCurrency = (options: FzUseCurrencyOptions) => {
-  const inputRef: Ref<HTMLInputElement | null | undefined> = ref(null)
-  const vm = getCurrentInstance()
-
-  const computedModel = computed<number | null>(() => vm?.props.amount as number | null)
-  const internalVal = ref<number | null>()
-
-  const format = formatNumber(options)
-
-  const emitAmount = (val: number | null) => {
-    if (Number.isNaN(val)) {
-      return
-    }
-    if (vm) {
-      internalVal.value = val
-      if (vm.props.nullOnEmpty && !val) {
-        vm.emit('update:amount', null)
-        return
-      }
-      vm.emit('update:amount', val)
-    }
-  }
-
-  const setValue = (val: string) => {
-    // nextTick doesn't seem to work
-    setTimeout(() => {
-      if (!inputRef.value) {
-        return
-      }
-      inputRef.value.value = val
-    }, 0)
-  }
-
-  const onInput = (el: HTMLInputElement) => (e: Event) => {
-    if (!inputRef.value || !e.target) {
-      return
-    }
-    let { value } = el
-    value = value.replace(/[^0-9,.-]/g, '')
-    const parsed: number = parse(value);
-
-    setValue(value)
-    const numberValue = vm?.props.nullOnEmpty && value === '' ? null : parsed
-    emitAmount(Number.isNaN(numberValue) ? 0 : numberValue)
-  }
-
-  const onBlur = (e: FocusEvent) => {
-    if (!inputRef.value || !e.target) {
-      return
-    }
-    const rawValue = (e.target as HTMLInputElement).value.replace(/,/g, '.')
-    let number: number | null
-
-    if (rawValue === '' && vm?.props.nullOnEmpty) {
-      number = null
-    } else {
-      number = parse(rawValue)
-      if (Number.isNaN(number)) {
-        number = 0
-      }
-      if (options.step && vm?.props.forceStep) {
-        number = roundTo(options.step, number)
-      }
-      if (options.min && options.min > number) {
-        number = options.min
-      }
-      if (options.max && options.max < number) {
-        number = options.max
-      }
-    }
-    const text = format(number)
-    setValue(text)
-    emitAmount(parse(text))
-  }
-
-  watch(inputRef, (newVal, oldVal) => {
-    if (!newVal) {
-      return
-    }
-
-    if (oldVal) {
-      oldVal?.removeEventListener('input', onInput(newVal))
-      oldVal?.removeEventListener('blur', onBlur)
-    }
-    newVal.addEventListener('input', onInput(newVal))
-    newVal.addEventListener('blur', onBlur)
-
-    if (vm?.props.amount) {
-      newVal.value = format(computedModel.value)
-    }
-  })
-
-  watch(computedModel, (newVal) => {
-    nextTick(() => {
-      if (!inputRef.value || newVal === null || newVal === undefined) {
-        return
-      }
-      // we need to format here only if someone externally set the
-      // value of the amount model
-      if (internalVal.value !== newVal) {
-        const formatted = format(newVal)
-        inputRef.value.value = formatted
-        internalVal.value = newVal
-      }
-    })
-  })
+import { format, parse } from '../utils'
 
+/**
+ * @deprecated This composable is deprecated.
+ * You can use `format` and `parse` directly from `composables/utils`.
+ */
+export const useCurrency = (_options: FzUseCurrencyOptions) => {
   return {
-    inputRef,
-    parse,
     format,
-    emitAmount,
-    setValue
+    parse
   }
 }

package/src/composables/useFloating.ts

@@ -1,391 +1,580 @@
-import { FzFloatingPosition, FzRect, FzUseFloatingArgs } from '../types'
+/**
+ * @module useFloating
+ * @description Composable for managing floating/popover element positioning
+ * 
+ * ## Why This Refactoring?
+ * 
+ * The previous implementation had several issues:
+ * 
+ * 1. **Monolithic function**: All positioning logic was in a single function
+ *    making it hard to test individual positioning strategies
+ * 
+ * 2. **Inconsistent margin handling**: Margins were calculated differently for
+ *    different positions, leading to visual inconsistencies
+ * 
+ * 3. **No reactive repositioning**: The floating element didn't respond to
+ *    opener/content size changes or scroll events
+ * 
+ * 4. **Layout shift on open**: The floating element was added to document flow
+ *    before positioning, causing visual jumps
+ * 
+ * ## Architecture
+ * 
+ * The new implementation uses:
+ * 
+ * - **Pure position calculators**: Each position (top, bottom, left, right and
+ *   their variants) has a dedicated calculator function stored in lookup tables
+ * 
+ * - **Lookup tables**: `positionCalculators` (with opener) and 
+ *   `containerPositionCalculators` (without opener) provide O(1) access
+ * 
+ * - **Immediate fixed positioning**: Elements are set to `position: fixed`
+ *   immediately to prevent layout shift
+ * 
+ * - **Reactive repositioning**: ResizeObserver and scroll/resize event listeners
+ *   ensure the floating stays positioned correctly during dynamic changes
+ * 
+ * ## Usage
+ * 
+ * ```typescript
+ * const { float, setPosition, actualPosition } = useFloating({
+ *   element: toRef(props, 'element'),
+ *   opener: toRef(props, 'opener'),
+ *   position: toRef(props, 'position'),
+ *   container: toRef(props, 'container')
+ * })
+ * 
+ * // Position is set automatically, or call manually:
+ * await setPosition()
+ * 
+ * // Access computed position values:
+ * console.log(float.position.x, float.position.y)
+ * console.log(actualPosition.value) // Resolved position for 'auto' modes
+ * ```
+ * 
+ * ## Position Types
+ * 
+ * - Explicit: top, bottom, left, right and variants (-start, -end)
+ * - Auto: auto, auto-vertical, auto-start, auto-end, etc.
+ * 
+ * Auto positions are resolved based on available space around the opener
+ * 
+ * @see FzFloating.vue - The component that uses this composable
+ */
+
+import { FzFloatingPosition, FzRect, FzUseFloatingArgs, FzAbsolutePosition } from '../types'
 import { ref, reactive, onUnmounted, Ref, nextTick, ToRefs } from 'vue'
 import { calcRealPos, getHighestAvailableSpacePos } from '../utils'
 
-export const useFloating = (
-  args: ToRefs<FzUseFloatingArgs>
-): {
-  float: FzRect
-  rect: Ref<DOMRect | undefined>
-  setPosition: (ignoreCallback?: boolean) => Promise<void>
-  position: Ref<FzFloatingPosition>
-  actualPosition?: Ref<FzFloatingPosition | undefined>
-  openerRect: Ref<DOMRect | undefined>
-  containerRect: Ref<DOMRect | undefined>
-} => {
-  const safeElementDomRef = ref<HTMLElement | null>(null)
-  const safeContainerDomRef = ref<HTMLElement | null>(null)
-  const safeOpenerDomRef = ref<HTMLElement | null>(null)
-  const openerRect = ref<DOMRect | undefined>()
-  const containerRect = ref<DOMRect | undefined>()
-  const position = ref<FzFloatingPosition>('auto')
-  const rect = ref<DOMRect | undefined>()
-  const float = reactive<FzRect>({
-    position: { x: 0, y: 0 }
-  })
-  const options: IntersectionObserverInit = {
-    root: null,
-    rootMargin: '0px',
-    threshold: 1.0,
-    ...args.element.value.intersectionOptions
-  }
+// ============================================================================
+// Types
+// ============================================================================
 
-  const handleIntersect = (
-    entries: IntersectionObserverEntry[],
-    observer: IntersectionObserver
-  ) => {}
+interface DOMRefs {
+  element: HTMLElement
+  container: HTMLElement
+  opener: HTMLElement | null
+}
 
-  const floatObserver = ref(new IntersectionObserver(handleIntersect, options))
-  const actualPosition = ref<FzFloatingPosition>()
+interface Rects {
+  element: DOMRect
+  container: DOMRect
+  opener: DOMRect | null
+}
 
-  // Helper: Resolve DOM references
-  const resolveDomReferences = () => {
-    safeElementDomRef.value = (
-      typeof args.element.value.domRef.value === 'string'
-        ? document.querySelector(args.element.value.domRef.value)
-        : args.element.value.domRef.value
-    ) as HTMLElement
-
-    if (!args.container?.value) {
-      safeContainerDomRef.value = document.body
-    } else {
-      safeContainerDomRef.value = (
-        typeof args.container.value?.domRef.value === 'string'
-          ? document.querySelector(args.container.value.domRef.value)
-          : args.container.value?.domRef.value
-      ) as HTMLElement
-      safeContainerDomRef.value ??= document.body
-    }
+interface Margins {
+  left: number
+  right: number
+  top: number
+  bottom: number
+}
 
-    if (!safeElementDomRef.value) {
-      throw new Error('missing reference element for floating behavior')
-    }
+interface Transform {
+  x: number
+  y: number
+}
 
-    if (args.opener?.value) {
-      safeOpenerDomRef.value = (
-        typeof args.opener.value?.domRef.value === 'string'
-          ? document.querySelector(args.opener.value.domRef.value)
-          : args.opener.value?.domRef.value
-      ) as HTMLElement
-    }
+interface PositionResult {
+  position: FzAbsolutePosition
+  transform: Transform
+}
 
-    rect.value = safeElementDomRef.value.getBoundingClientRect()
-    openerRect.value = safeOpenerDomRef.value?.getBoundingClientRect()
-    containerRect.value = safeContainerDomRef.value.getBoundingClientRect()
-  }
+type PositionCalculator = (opener: DOMRect, margins: Margins) => PositionResult
+
+// ============================================================================
+// Pure Functions - DOM Reference Resolution
+// ============================================================================
+
+const resolveElement = (domRef: string | HTMLElement | null): HTMLElement | null =>
+  typeof domRef === 'string' ? document.querySelector(domRef) : domRef
+
+const getMargins = (style: CSSStyleDeclaration): Margins => ({
+  left: parseFloat(style.marginLeft),
+  right: parseFloat(style.marginRight),
+  top: parseFloat(style.marginTop),
+  bottom: parseFloat(style.marginBottom)
+})
+
+// ============================================================================
+// Position Calculators WITH Opener - Lookup Table
+// Each calculator receives opener rect and element margins for consistent spacing
+// ============================================================================
+
+const positionCalculators: Record<string, PositionCalculator> = {
+  // Bottom positions - content below opener
+  'bottom': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.left + opener.width / 2,
+      y: opener.bottom
+    },
+    transform: { x: -50, y: 0 }
+  }),
+
+  'bottom-start': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.left,
+      y: opener.bottom
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'bottom-end': (opener, margins) => ({
+    position: {
+      x: opener.right + margins.right,
+      y: opener.bottom
+    },
+    transform: { x: -100, y: 0 }
+  }),
+
+  // Top positions - content above opener
+  'top': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.left + opener.width / 2,
+      y: opener.top - margins.bottom
+    },
+    transform: { x: -50, y: -100 }
+  }),
+
+  'top-start': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.left,
+      y: opener.top - margins.bottom
+    },
+    transform: { x: 0, y: -100 }
+  }),
+
+  'top-end': (opener, margins) => ({
+    position: {
+      x: opener.right + margins.right,
+      y: opener.top - margins.bottom
+    },
+    transform: { x: -100, y: -100 }
+  }),
+
+  // Left positions - content to left of opener
+  'left': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.right,
+      y: opener.top - margins.top + opener.height / 2
+    },
+    transform: { x: -100, y: -50 }
+  }),
+
+  'left-start': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.right,
+      y: opener.top - margins.top
+    },
+    transform: { x: -100, y: 0 }
+  }),
+
+  'left-end': (opener, margins) => ({
+    position: {
+      x: opener.left - margins.right,
+      y: opener.bottom + margins.bottom
+    },
+    transform: { x: -100, y: -100 }
+  }),
+
+  // Right positions - content to right of opener
+  'right': (opener, margins) => ({
+    position: {
+      x: opener.right + margins.left,
+      y: opener.top - margins.top + opener.height / 2
+    },
+    transform: { x: 0, y: -50 }
+  }),
+
+  'right-start': (opener, margins) => ({
+    position: {
+      x: opener.right + margins.left,
+      y: opener.top - margins.top
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'right-end': (opener, margins) => ({
+    position: {
+      x: opener.right + margins.left,
+      y: opener.bottom + margins.bottom
+    },
+    transform: { x: 0, y: -100 }
+  })
+}
 
-  // Helper: Resolve auto position to actual position
-  const resolveAutoPositionValue = () => {
-    if (!args.opener?.value || !safeOpenerDomRef.value) return
+const calculatePositionWithOpener = (
+  position: FzFloatingPosition,
+  opener: DOMRect,
+  margins: Margins
+): PositionResult => {
+  const calculator = positionCalculators[position]
+  return calculator
+    ? calculator(opener, margins)
+    : { position: { x: 0, y: 0 }, transform: { x: 0, y: 0 } }
+}
 
-    switch (actualPosition.value) {
-      case 'auto':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement
-        )
-        break
-      case 'auto-vertical':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement,
-          undefined,
-          true
-        )
-        break
-      case 'auto-start':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement,
-          'start'
-        )
-        break
-      case 'auto-vertical-start':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement,
-          'start',
-          true
-        )
-        break
-      case 'auto-end':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement,
-          'end'
-        )
-        break
-      case 'auto-vertical-end':
-        actualPosition.value = getHighestAvailableSpacePos(
-          args.useViewport?.value ? null : (safeContainerDomRef.value as HTMLElement),
-          safeElementDomRef.value as HTMLElement,
-          safeOpenerDomRef.value as HTMLElement,
-          'end',
-          true
-        )
-        break
-      default:
-        break
-    }
+// ============================================================================
+// Position Calculators WITHOUT Opener - Lookup Table
+// ============================================================================
+
+type ContainerPositionCalculator = (container: DOMRect, element: DOMRect) => PositionResult
+
+const containerPositionCalculators: Record<string, ContainerPositionCalculator> = {
+  'bottom': (container, element) => ({
+    position: { 
+      x: container.left + container.width / 2, 
+      y: container.bottom - element.height 
+    },
+    transform: { x: -50, y: 0 }
+  }),
+
+  'bottom-start': (container, element) => ({
+    position: { 
+      x: container.left, 
+      y: container.bottom - element.height 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'bottom-end': (container, element) => ({
+    position: { 
+      x: container.right - element.width, 
+      y: container.bottom - element.height 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'top': (container) => ({
+    position: { 
+      x: container.left + container.width / 2, 
+      y: container.top 
+    },
+    transform: { x: -50, y: 0 }
+  }),
+
+  'top-start': (container) => ({
+    position: { 
+      x: container.left, 
+      y: container.top 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'top-end': (container, element) => ({
+    position: { 
+      x: container.right - element.width, 
+      y: container.top 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'left': (container, element) => ({
+    position: { 
+      x: container.left, 
+      y: container.top + (container.height - element.height) / 2 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'left-start': (container) => ({
+    position: { 
+      x: container.left, 
+      y: container.top 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'left-end': (container, element) => ({
+    position: { 
+      x: container.left, 
+      y: container.bottom - element.height 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'right': (container, element) => ({
+    position: { 
+      x: container.right - element.width, 
+      y: container.top + (container.height - element.height) / 2 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'right-start': (container, element) => ({
+    position: { 
+      x: container.right - element.width, 
+      y: container.top 
+    },
+    transform: { x: 0, y: 0 }
+  }),
+
+  'right-end': (container, element) => ({
+    position: { 
+      x: container.right - element.width, 
+      y: container.bottom - element.height 
+    },
+    transform: { x: 0, y: 0 }
+  })
+}
+
+const calculatePositionWithoutOpener = (
+  position: FzFloatingPosition,
+  container: DOMRect,
+  element: DOMRect
+): PositionResult => {
+  const calculator = containerPositionCalculators[position]
+  return calculator 
+    ? calculator(container, element)
+    : { position: { x: 0, y: 0 }, transform: { x: 0, y: 0 } }
+}
+
+// ============================================================================
+// Boundary Correction - Pure Function
+// ============================================================================
+
+const applyBoundaryCorrections = (
+  realPosition: FzAbsolutePosition,
+  element: DOMRect,
+  container: DOMRect,
+  transform: Transform
+): { position: FzAbsolutePosition; transform: Transform } => {
+  const correctedPosition = { ...realPosition }
+  const correctedTransform = { ...transform }
+
+  // Left boundary
+  if (realPosition.x < container.left) {
+    correctedPosition.x = container.left
+    correctedTransform.x = 0
   }
 
-  // Helper: Calculate position with opener
-  const calculatePositionWithOpener = (
-    elStyle: CSSStyleDeclaration,
-    translateX: { value: number },
-    translateY: { value: number }
-  ) => {
-    if (!openerRect.value) return
-
-    const leftWithoutXMargin =
-      openerRect.value.left - parseFloat(elStyle.marginLeft) - parseFloat(elStyle.marginRight)
-    const leftWithoutLeftMargin = openerRect.value.left - parseFloat(elStyle.marginLeft)
-    const topWithoutYMargin =
-      openerRect.value.top - parseFloat(elStyle.marginTop) - parseFloat(elStyle.marginBottom)
-    const topWithoutTopMargin = openerRect.value.top - parseFloat(elStyle.marginTop)
-
-    switch (actualPosition.value) {
-      case 'bottom':
-        float.position.y = openerRect.value.bottom
-        float.position.x = leftWithoutLeftMargin + openerRect.value.width / 2
-        translateX.value = -50
-        translateY.value = 0
-        break
-      case 'bottom-start':
-        float.position.y = openerRect.value.bottom
-        float.position.x = leftWithoutXMargin
-        translateX.value = 0
-        translateY.value = 0
-        break
-      case 'bottom-end':
-        float.position.y = openerRect.value.bottom
-        float.position.x = openerRect.value.right
-        translateX.value = -100
-        translateY.value = 0
-        break
-      case 'left-start':
-        float.position.y = topWithoutYMargin
-        float.position.x = leftWithoutXMargin
-        translateX.value = -100
-        translateY.value = 0
-        break
-      case 'left':
-        float.position.y = topWithoutTopMargin + openerRect.value.height / 2
-        float.position.x = leftWithoutXMargin
-        translateY.value = -50
-        translateX.value = -100
-        break
-      case 'left-end':
-        float.position.y = openerRect.value.bottom
-        float.position.x = leftWithoutXMargin
-        translateY.value = -100
-        translateX.value = -100
-        break
-      case 'top-start':
-        float.position.y = topWithoutYMargin
-        float.position.x = leftWithoutXMargin
-        translateY.value = -100
-        translateX.value = 0
-        break
-      case 'top':
-        float.position.y = topWithoutYMargin
-        float.position.x = leftWithoutLeftMargin + openerRect.value.width / 2
-        translateX.value = -50
-        translateY.value = -100
-        break
-      case 'top-end':
-        float.position.y = topWithoutYMargin
-        float.position.x = openerRect.value.right
-        translateX.value = -100
-        translateY.value = -100
-        break
-      case 'right-start':
-        float.position.y = topWithoutYMargin
-        float.position.x = openerRect.value.right
-        translateX.value = 0
-        translateY.value = 0
-        break
-      case 'right':
-        float.position.y = topWithoutTopMargin + openerRect.value.height / 2
-        float.position.x = openerRect.value.right
-        translateY.value = -50
-        translateX.value = 0
-        break
-      case 'right-end':
-        float.position.y = openerRect.value.bottom
-        float.position.x = openerRect.value.right
-        translateY.value = -100
-        translateX.value = 0
-        break
-      default:
-        break
+  // Right boundary
+  if (realPosition.x + element.width > container.right) {
+    const fixedX = container.right - element.width
+    if (fixedX > 0) {
+      correctedPosition.x = fixedX
     }
+    correctedTransform.x = 0
   }
 
-  // Helper: Calculate position without opener
-  const calculatePositionWithoutOpener = (translateX: { value: number }) => {
-    if (!containerRect.value || !rect.value) return
-
-    switch (actualPosition.value) {
-      case 'bottom':
-        float.position.y = containerRect.value.bottom - rect.value.height
-        float.position.x = containerRect.value.left + containerRect.value.width / 2
-        translateX.value = -50
-        break
-      case 'left-end':
-      case 'bottom-start':
-        float.position.y = containerRect.value.bottom - rect.value.height
-        float.position.x = containerRect.value.left
-        break
-      case 'right-end':
-      case 'bottom-end':
-        float.position.y = containerRect.value.bottom - rect.value.height
-        float.position.x = containerRect.value.right - rect.value.width
-        break
-      case 'left':
-        float.position.y =
-          containerRect.value.top + (containerRect.value.height - rect.value.height) / 2
-        float.position.x = containerRect.value.left
-        break
-      case 'top-start':
-      case 'left-start':
-        float.position.y = containerRect.value.top
-        float.position.x = containerRect.value.left
-        break
-      case 'top':
-        float.position.y = containerRect.value.top
-        float.position.x =
-          containerRect.value.left + (containerRect.value.width - rect.value.width) / 2
-        break
-      case 'top-end':
-      case 'right-start':
-        float.position.y = containerRect.value.top
-        float.position.x = containerRect.value.right - rect.value.width
-        break
-      case 'right':
-        float.position.y =
-          containerRect.value.top + (containerRect.value.height - rect.value.height) / 2
-        float.position.x = containerRect.value.right - rect.value.width
-        break
-      default:
-        break
-    }
+  // Top boundary
+  if (realPosition.y < container.top) {
+    correctedPosition.y = container.top
+    correctedTransform.y = 0
   }
 
-  // Helper: Apply boundary corrections
-  const applyBoundaryCorrections = (
-    realPos: { x: number; y: number },
-    translateX: { value: number },
-    translateY: { value: number }
-  ) => {
-    if (!containerRect.value || !rect.value) return
-
-    if (realPos.x < containerRect.value.left) {
-      float.position.x = containerRect.value.left
-      translateX.value = 0
+  // Bottom boundary
+  if (realPosition.y + element.height > container.bottom) {
+    const fixedY = container.bottom - element.height
+    if (fixedY > 0) {
+      correctedPosition.y = fixedY
     }
+    correctedTransform.y = 0
+  }
 
-    if (realPos.x + rect.value.width > containerRect.value.right) {
-      const fixVal = containerRect.value.right - rect.value.width
-      if (fixVal > 0) {
-        float.position.x = fixVal
-      }
-      translateX.value = 0
-    }
+  return { position: correctedPosition, transform: correctedTransform }
+}
 
-    if (realPos.y < containerRect.value.top) {
-      float.position.y = containerRect.value.top
-      translateY.value = 0
-    }
+// ============================================================================
+// Auto Position Resolution - Pure Function
+// ============================================================================
 
-    if (realPos.y + rect.value.height > containerRect.value.bottom) {
-      const fixVal = containerRect.value.bottom - rect.value.height
-      if (fixVal > 0) {
-        float.position.y = fixVal
-      }
-      translateY.value = 0
-    }
-  }
+type AutoPositionType = 'auto' | 'auto-vertical' | 'auto-start' | 'auto-vertical-start' | 'auto-end' | 'auto-vertical-end'
 
-  // Helper: Apply element styles
-  const applyElementStyles = () => {
-    if (!safeElementDomRef.value) return
+const resolveAutoPosition = (
+  autoType: AutoPositionType,
+  container: HTMLElement | null,
+  element: HTMLElement,
+  opener: HTMLElement,
+  useViewport: boolean
+): FzFloatingPosition => {
+  const containerEl = useViewport ? null : container
 
-    safeElementDomRef.value.style.top = `${float.position.y}px`
-    safeElementDomRef.value.style.left = `${float.position.x}px`
-    safeElementDomRef.value.style.position = 'fixed'
-    safeElementDomRef.value.style.display = 'flex'
-  }
+  switch (autoType) {
+    case 'auto':
+      return getHighestAvailableSpacePos(containerEl, element, opener)
 
-  const setPosition = (ignoreCallback: boolean = false) =>
-    nextTick(() => {
-      actualPosition.value = args.position ? args.position.value : 'auto'
+    case 'auto-vertical':
+      return getHighestAvailableSpacePos(containerEl, element, opener, undefined, true)
 
-      // Step 1: Resolve DOM references
-      resolveDomReferences()
+    case 'auto-start':
+      return getHighestAvailableSpacePos(containerEl, element, opener, 'start')
 
-      // Step 1.5: CRITICAL - Remove element from document flow immediately
-      // This prevents the floating element from pushing the opener and causing layout shift
-      if (safeElementDomRef.value) {
-        safeElementDomRef.value.style.position = 'fixed'
-        safeElementDomRef.value.style.top = '0px'
-        safeElementDomRef.value.style.left = '0px'
-      }
+    case 'auto-vertical-start':
+      return getHighestAvailableSpacePos(containerEl, element, opener, 'start', true)
 
-      // Recalculate all rects after content is rendered
-      rect.value = safeElementDomRef.value!.getBoundingClientRect()
-      openerRect.value = safeOpenerDomRef.value?.getBoundingClientRect()
-      containerRect.value = safeContainerDomRef.value!.getBoundingClientRect()
+    case 'auto-end':
+      return getHighestAvailableSpacePos(containerEl, element, opener, 'end')
 
-      const elStyle = window.getComputedStyle(safeElementDomRef.value as HTMLElement)
+    case 'auto-vertical-end':
+      return getHighestAvailableSpacePos(containerEl, element, opener, 'end', true)
 
-      // Step 2: Setup intersection observer
-      floatObserver.value.observe(safeElementDomRef.value as HTMLElement)
-      floatObserver.value.observe(safeContainerDomRef.value as HTMLElement)
+    default:
+      return 'bottom-start'
+  }
+}
 
-      // Step 3: Resolve auto positions
-      resolveAutoPositionValue()
+const isAutoPosition = (position: FzFloatingPosition): position is AutoPositionType =>
+  position.startsWith('auto')
 
-      // Step 4: Calculate position based on opener presence
-      const translate = { x: { value: 0 }, y: { value: 0 } }
+// ============================================================================
+// Main Composable
+// ============================================================================
 
-      if (args.opener?.value && safeOpenerDomRef.value && openerRect?.value) {
-        calculatePositionWithOpener(elStyle, translate.x, translate.y)
-      } else {
-        calculatePositionWithoutOpener(translate.x)
-      }
+export const useFloating = (
+  args: ToRefs<FzUseFloatingArgs>
+): {
+  float: FzRect
+  rect: Ref<DOMRect | undefined>
+  setPosition: (ignoreCallback?: boolean) => Promise<void>
+  position: Ref<FzFloatingPosition>
+  actualPosition?: Ref<FzFloatingPosition | undefined>
+  openerRect: Ref<DOMRect | undefined>
+  containerRect: Ref<DOMRect | undefined>
+} => {
+  // State
+  const position = ref<FzFloatingPosition>('auto')
+  const actualPosition = ref<FzFloatingPosition>()
+  const rect = ref<DOMRect>()
+  const openerRect = ref<DOMRect>()
+  const containerRect = ref<DOMRect>()
+  const float = reactive<FzRect>({ position: { x: 0, y: 0 } })
 
-      // Step 5: Calculate real position and apply boundary corrections
-      if (rect.value) {
-        const realPos = calcRealPos(
-          rect.value,
-          float.position,
-          translate.x.value,
-          translate.y.value
-        )
-        float.position.x = realPos.x
-        float.position.y = realPos.y
+  // Intersection Observer
+  const observerOptions: IntersectionObserverInit = {
+    root: null,
+    rootMargin: '0px',
+    threshold: 1.0,
+    ...args.element.value.intersectionOptions
+  }
+  const floatObserver = ref(new IntersectionObserver(() => {}, observerOptions))
 
-        applyBoundaryCorrections(realPos, translate.x, translate.y)
-      }
+  // DOM Reference Resolution
+  const resolveDOMRefs = (): DOMRefs | null => {
+    const element = resolveElement(args.element.value.domRef.value)
+    if (!element) {
+      throw new Error('missing reference element for floating behavior')
+    }
+
+    const container = args.container?.value
+      ? resolveElement(args.container.value.domRef.value) ?? document.body
+      : document.body
 
-      // Step 6: Apply styles to element
-      applyElementStyles()
+    const opener = args.opener?.value
+      ? resolveElement(args.opener.value.domRef.value)
+      : null
 
-      // Step 7: Update rect after positioning
-      rect.value = safeElementDomRef.value!.getBoundingClientRect()
+    return { element, container, opener }
+  }
+
+  const getRects = (refs: DOMRefs): Rects => ({
+    element: refs.element.getBoundingClientRect(),
+    container: refs.container.getBoundingClientRect(),
+    opener: refs.opener?.getBoundingClientRect() ?? null
+  })
+
+  // Main positioning function
+  const setPosition = (ignoreCallback: boolean = false) =>
+    nextTick(() => {
+      // Step 1: Initialize position from args
+      actualPosition.value = args.position?.value ?? 'auto'
+
+      // Step 2: Resolve DOM references
+      const refs = resolveDOMRefs()
+      if (!refs) return
+
+      // Step 3: Set fixed positioning immediately to prevent layout shift
+      Object.assign(refs.element.style, {
+        position: 'fixed',
+        top: '0px',
+        left: '0px'
+      })
+
+      // Step 4: Get all bounding rects
+      const rects = getRects(refs)
+      rect.value = rects.element
+      openerRect.value = rects.opener ?? undefined
+      containerRect.value = rects.container
+
+      // Step 5: Setup observers
+      floatObserver.value.observe(refs.element)
+      floatObserver.value.observe(refs.container)
+
+      // Step 6: Resolve auto position if needed
+      if (isAutoPosition(actualPosition.value) && refs.opener) {
+        actualPosition.value = resolveAutoPosition(
+          actualPosition.value,
+          refs.container,
+          refs.element,
+          refs.opener,
+          args.useViewport?.value ?? false
+        )
+      }
 
-      // Step 8: Trigger callback if provided
+      // Step 7: Calculate position
+      const margins = getMargins(window.getComputedStyle(refs.element))
+      
+      const positionResult = refs.opener && rects.opener
+        ? calculatePositionWithOpener(actualPosition.value!, rects.opener, margins)
+        : calculatePositionWithoutOpener(actualPosition.value!, rects.container, rects.element)
+
+      // Step 8: Apply transform to get real position
+      const realPosition = calcRealPos(
+        rects.element,
+        positionResult.position,
+        positionResult.transform.x,
+        positionResult.transform.y
+      )
+
+      // Step 9: Apply boundary corrections
+      const corrected = applyBoundaryCorrections(
+        realPosition,
+        rects.element,
+        rects.container,
+        positionResult.transform
+      )
+
+      // Step 10: Update float state
+      float.position.x = corrected.position.x
+      float.position.y = corrected.position.y
+
+      // Step 11: Apply final styles
+      Object.assign(refs.element.style, {
+        top: `${float.position.y}px`,
+        left: `${float.position.x}px`,
+        position: 'fixed',
+        display: 'flex'
+      })
+
+      // Step 12: Update rect after final positioning
+      rect.value = refs.element.getBoundingClientRect()
+
+      // Step 13: Trigger callback if provided
       if (args.callback?.value && !ignoreCallback) {
         args.callback.value(rect, openerRect, containerRect, position, actualPosition)
       }
     })
 
+  // Cleanup
   onUnmounted(() => {
     floatObserver.value.disconnect()
   })

package/src/utils/number/index.ts

@@ -1,21 +1,74 @@
-import { FzUseCurrencyOptions } from '../../types'
+/**
+ * Truncates a number to the specified maximum decimal places (without rounding)
+ *
+ * @param value - Number to truncate
+ * @param maxDecimals - Maximum number of decimal places
+ * @returns Truncated number
+ */
+export const truncateDecimals = (value: number, maxDecimals: number): number => {
+  const factor = Math.pow(10, maxDecimals);
+  return Math.trunc(value * factor) / factor;
+};
 
-export const format = (options: FzUseCurrencyOptions) => (input: number | null) => {
-  if (input === null) {
-    return ''
-  }
-  const safeOptions: FzUseCurrencyOptions = {
-    maximumFractionDigits: options.maximumFractionDigits || 2,
-    minimumFractionDigits: options.minimumFractionDigits,
-    useGrouping: options.useGrouping || false
+/**
+ * Formats a number value using provided options
+ *
+ * Uses Italian locale format (comma as decimal separator, point as thousand separator).
+ * Can truncate (not round) decimal places to maximumFractionDigits before formatting
+ * based on roundDecimals option.
+ *
+ * @param value - Number value to format
+ * @param options - Formatting options
+ * @param options.minimumFractionDigits - Minimum decimal places (default: 0)
+ * @param options.maximumFractionDigits - Maximum decimal places (default: 2)
+ * @param options.roundDecimals - If true, rounds decimals; if false, truncates (default: true)
+ * @param options.useGrouping - Whether to use thousand separators (default: true)
+ * @returns Formatted string (e.g., "1.234,56")
+ */
+export const format = (
+  value: number | null | undefined,
+  {
+    minimumFractionDigits = 0,
+    maximumFractionDigits = 2,
+    roundDecimals = true,
+    useGrouping = true,
+  } = {}
+): string => {
+  if (
+    value === undefined ||
+    value === null ||
+    isNaN(value) ||
+    !isFinite(value)
+  ) {
+    return "";
   }
 
-  return input.toLocaleString('it-IT', safeOptions)
-}
+  // Truncate decimals if roundDecimals is false, otherwise use value as-is (toLocaleString will round)
+  const processedValue = roundDecimals
+    ? value
+    : truncateDecimals(value, maximumFractionDigits);
+
+  return processedValue.toLocaleString("it-IT", {
+    minimumFractionDigits: minimumFractionDigits,
+    maximumFractionDigits: maximumFractionDigits,
+    useGrouping: useGrouping,
+  });
+};
 
 export const parse = (text: string): number => {
-  // strip currency, handle edge cases...
-  return parseFloat(text.replace(/,/g, '.'))
+  if (!text || typeof text !== 'string') {
+    return NaN
+  }
+
+  let normalized = text.trim()
+
+  // Handle Italian format: "1.234,56" (points = thousands, comma = decimal)
+  if (normalized.includes(',')) {
+    normalized = normalized.replace(/\./g, '')
+    normalized = normalized.replace(',', '.')
+  }
+
+  return parseFloat(normalized)
 }
 
 export const roundTo = (step: number, val: number) => {
@@ -26,4 +79,8 @@ export const roundTo = (step: number, val: number) => {
     result = Math.abs(remainder) >= step / 2 ? val + safeStep - remainder : val - remainder
   }
   return result
+}
+
+export const clamp = (min: number, value: number, max: number): number => {
+  return Math.max(min, Math.min(value, max))
 }