@sabrenski/spire-ui 0.0.1

package/src/composables/useMagnetic.ts

@@ -0,0 +1,171 @@
+import { ref, watch, onUnmounted, type Ref } from 'vue'
+
+export interface UseMagneticOptions {
+  strength?: number
+  radius?: number
+  ease?: number
+}
+
+export interface UseMagneticReturn {
+  x: Ref<number>
+  y: Ref<number>
+  isHovering: Ref<boolean>
+  style: Ref<Record<string, string>>
+}
+
+/**
+ * Creates a magnetic hover effect where the element subtly follows the cursor.
+ * Handles deferred elements (tabs, v-if) by watching for target availability.
+ *
+ * @param target - Ref to the target element
+ * @param options - Configuration options
+ * @returns Reactive values for position and style
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const buttonRef = ref<HTMLElement | null>(null)
+ * const { style } = useMagnetic(buttonRef, { strength: 0.3 })
+ * </script>
+ *
+ * <template>
+ *   <button ref="buttonRef" :style="style">Magnetic Button</button>
+ * </template>
+ * ```
+ */
+export function useMagnetic(
+  target: Ref<HTMLElement | null>,
+  options: UseMagneticOptions = {}
+): UseMagneticReturn {
+  const { strength = 0.2, radius = 100, ease = 0.15 } = options
+
+  const x = ref(0)
+  const y = ref(0)
+  const isHovering = ref(false)
+  const style = ref<Record<string, string>>({})
+
+  let animationFrame: number | null = null
+  let targetX = 0
+  let targetY = 0
+  let currentX = 0
+  let currentY = 0
+  let isInitialized = false
+  let currentElement: HTMLElement | null = null
+
+  function lerp(start: number, end: number, factor: number): number {
+    return start + (end - start) * factor
+  }
+
+  function animate() {
+    currentX = lerp(currentX, targetX, ease)
+    currentY = lerp(currentY, targetY, ease)
+
+    const deltaX = Math.abs(currentX - targetX)
+    const deltaY = Math.abs(currentY - targetY)
+
+    if (deltaX < 0.01 && deltaY < 0.01) {
+      currentX = targetX
+      currentY = targetY
+    }
+
+    x.value = currentX
+    y.value = currentY
+    style.value = {
+      transform: `translate(${currentX}px, ${currentY}px)`,
+      transition: 'none'
+    }
+
+    if (isHovering.value || currentX !== 0 || currentY !== 0) {
+      animationFrame = requestAnimationFrame(animate)
+    } else {
+      animationFrame = null
+      style.value = {
+        transform: 'translate(0, 0)',
+        transition: 'transform var(--duration-normal, 200ms) var(--ease-out, ease-out)'
+      }
+    }
+  }
+
+  function handleMouseMove(event: MouseEvent) {
+    if (!target.value) return
+
+    const rect = target.value.getBoundingClientRect()
+    const centerX = rect.left + rect.width / 2
+    const centerY = rect.top + rect.height / 2
+
+    const distanceX = event.clientX - centerX
+    const distanceY = event.clientY - centerY
+    const distance = Math.sqrt(distanceX ** 2 + distanceY ** 2)
+
+    if (distance < radius) {
+      isHovering.value = true
+      const factor = 1 - distance / radius
+      targetX = distanceX * strength * factor
+      targetY = distanceY * strength * factor
+
+      if (!animationFrame) {
+        animationFrame = requestAnimationFrame(animate)
+      }
+    } else if (isHovering.value) {
+      handleMouseLeave()
+    }
+  }
+
+  function handleMouseLeave() {
+    isHovering.value = false
+    targetX = 0
+    targetY = 0
+
+    if (!animationFrame) {
+      animationFrame = requestAnimationFrame(animate)
+    }
+  }
+
+  function initialize(element: HTMLElement) {
+    if (isInitialized && currentElement === element) return
+
+    cleanup()
+
+    currentElement = element
+    isInitialized = true
+
+    document.addEventListener('mousemove', handleMouseMove)
+    element.addEventListener('mouseleave', handleMouseLeave)
+  }
+
+  function cleanup() {
+    document.removeEventListener('mousemove', handleMouseMove)
+    if (currentElement) {
+      currentElement.removeEventListener('mouseleave', handleMouseLeave)
+    }
+    if (animationFrame) {
+      cancelAnimationFrame(animationFrame)
+      animationFrame = null
+    }
+    isInitialized = false
+    currentElement = null
+  }
+
+  watch(
+    target,
+    (newTarget) => {
+      if (newTarget) {
+        initialize(newTarget)
+      } else {
+        cleanup()
+      }
+    },
+    { immediate: true }
+  )
+
+  onUnmounted(() => {
+    cleanup()
+  })
+
+  return {
+    x,
+    y,
+    isHovering,
+    style
+  }
+}

package/src/composables/useRelativePosition.ts

@@ -0,0 +1,127 @@
+import { ref, onMounted, onUnmounted, type Ref } from 'vue'
+
+export type Placement = 'top' | 'bottom' | 'left' | 'right'
+
+export interface PositionResult {
+  top: number
+  left: number
+  actualPlacement: Placement
+}
+
+/**
+ * Pure calculation function - no reactive dependencies.
+ * Can be called synchronously before first paint.
+ */
+export function calculatePosition(
+  triggerEl: HTMLElement,
+  contentEl: HTMLElement,
+  desiredPlacement: Placement,
+  offset: number
+): PositionResult {
+  const triggerRect = triggerEl.getBoundingClientRect()
+
+  // Use offsetWidth/Height for content - not affected by CSS transforms (scale)
+  const contentWidth = contentEl.offsetWidth
+  const contentHeight = contentEl.offsetHeight
+
+  const viewport = {
+    width: window.innerWidth || 1024,
+    height: window.innerHeight || 768
+  }
+
+  const triggerCenterX = triggerRect.left + triggerRect.width / 2
+  const triggerCenterY = triggerRect.top + triggerRect.height / 2
+
+  function calcPosition(p: Placement): { top: number; left: number } {
+    switch (p) {
+      case 'top':
+        return {
+          top: triggerRect.top - contentHeight - offset,
+          left: triggerCenterX - contentWidth / 2
+        }
+      case 'bottom':
+        return {
+          top: triggerRect.bottom + offset,
+          left: triggerCenterX - contentWidth / 2
+        }
+      case 'left':
+        return {
+          top: triggerCenterY - contentHeight / 2,
+          left: triggerRect.left - contentWidth - offset
+        }
+      case 'right':
+        return {
+          top: triggerCenterY - contentHeight / 2,
+          left: triggerRect.right + offset
+        }
+    }
+  }
+
+  const opposites: Record<Placement, Placement> = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left'
+  }
+
+  let currentPlacement = desiredPlacement
+  let pos = calcPosition(currentPlacement)
+
+  const overflows = {
+    top: pos.top < 0,
+    bottom: pos.top + contentHeight > viewport.height,
+    left: pos.left < 0,
+    right: pos.left + contentWidth > viewport.width
+  }
+
+  if (
+    (currentPlacement === 'top' && overflows.top) ||
+    (currentPlacement === 'bottom' && overflows.bottom) ||
+    (currentPlacement === 'left' && overflows.left) ||
+    (currentPlacement === 'right' && overflows.right)
+  ) {
+    currentPlacement = opposites[currentPlacement]
+    pos = calcPosition(currentPlacement)
+  }
+
+  const top = Math.max(offset, Math.min(pos.top, viewport.height - contentHeight - offset))
+  const left = Math.max(offset, Math.min(pos.left, viewport.width - contentWidth - offset))
+
+  return { top, left, actualPlacement: currentPlacement }
+}
+
+/**
+ * Composable for positioning floating elements relative to a trigger.
+ * Includes collision detection to flip placement when near viewport edges.
+ */
+export function useRelativePosition(
+  trigger: Ref<HTMLElement | null>,
+  content: Ref<HTMLElement | null>,
+  placement: Ref<Placement> | Placement | (() => Placement) = 'top',
+  offset = 8
+) {
+  const coords = ref<PositionResult>({ top: 0, left: 0, actualPlacement: 'top' })
+
+  function getPlacement(): Placement {
+    if (typeof placement === 'string') return placement
+    if (typeof placement === 'function') return placement()
+    return placement.value
+  }
+
+  function updatePosition() {
+    if (!trigger.value || !content.value) return
+    coords.value = calculatePosition(trigger.value, content.value, getPlacement(), offset)
+  }
+
+  onMounted(() => {
+    window.addEventListener('resize', updatePosition)
+    window.addEventListener('scroll', updatePosition, true)
+  })
+
+  onUnmounted(() => {
+    window.removeEventListener('resize', updatePosition)
+    window.removeEventListener('scroll', updatePosition, true)
+  })
+
+  return { coords, updatePosition, getPlacement }
+}

package/src/composables/useRipple.ts

@@ -0,0 +1,146 @@
+import { watch, onUnmounted, type Ref } from 'vue'
+
+export interface UseRippleOptions {
+  color?: string
+  opacity?: number
+  duration?: number
+  disabled?: Ref<boolean> | boolean
+}
+
+/**
+ * Creates a ripple effect on click for interactive elements.
+ * Handles deferred elements (tabs, v-if) by watching for target availability.
+ *
+ * @param target - Ref to the target element
+ * @param options - Configuration options
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const buttonRef = ref<HTMLElement | null>(null)
+ * useRipple(buttonRef, { color: 'white', opacity: 0.3 })
+ * </script>
+ *
+ * <template>
+ *   <button ref="buttonRef" data-ripple>Click me</button>
+ * </template>
+ * ```
+ */
+export function useRipple(
+  target: Ref<HTMLElement | null>,
+  options: UseRippleOptions = {}
+): void {
+  const {
+    color = 'var(--effect-ripple-color, white)',
+    opacity = 0.25,
+    duration = 800,
+    disabled = false
+  } = options
+
+  let isInitialized = false
+  let currentElement: HTMLElement | null = null
+  let styleElement: HTMLStyleElement | null = null
+
+  function isDisabled(): boolean {
+    if (typeof disabled === 'boolean') return disabled
+    return disabled.value
+  }
+
+  function ensureKeyframes(): void {
+    if (document.querySelector('style[data-ripple-keyframes]')) return
+
+    styleElement = document.createElement('style')
+    styleElement.setAttribute('data-ripple-keyframes', '')
+    styleElement.textContent = `
+      @keyframes ui-ripple-expand {
+        0% {
+          opacity: 0;
+          transform: scale(0);
+        }
+        15% {
+          opacity: var(--ripple-opacity, 0.25);
+        }
+        100% {
+          transform: scale(2.5);
+          opacity: 0;
+        }
+      }
+    `
+    document.head.appendChild(styleElement)
+  }
+
+  function createRipple(event: MouseEvent) {
+    if (!target.value || isDisabled()) return
+
+    const element = target.value
+    const rect = element.getBoundingClientRect()
+
+    const x = event.clientX - rect.left
+    const y = event.clientY - rect.top
+
+    const size = Math.max(rect.width, rect.height) * 2
+
+    const ripple = document.createElement('span')
+    ripple.className = 'ui-ripple'
+    ripple.style.cssText = `
+      position: absolute;
+      left: ${x - size / 2}px;
+      top: ${y - size / 2}px;
+      width: ${size}px;
+      height: ${size}px;
+      border-radius: 50%;
+      background: ${color};
+      --ripple-opacity: ${opacity};
+      opacity: 0;
+      transform: scale(0);
+      pointer-events: none;
+      animation: ui-ripple-expand ${duration}ms cubic-bezier(0.4, 0, 0.2, 1) forwards;
+    `
+
+    element.style.position = element.style.position || 'relative'
+    element.style.overflow = 'hidden'
+
+    element.appendChild(ripple)
+
+    ripple.addEventListener('animationend', () => {
+      ripple.remove()
+    })
+  }
+
+  function initialize(element: HTMLElement) {
+    if (isInitialized && currentElement === element) return
+
+    cleanup()
+
+    currentElement = element
+    isInitialized = true
+
+    ensureKeyframes()
+    element.addEventListener('click', createRipple)
+    element.setAttribute('data-ripple', '')
+  }
+
+  function cleanup() {
+    if (currentElement) {
+      currentElement.removeEventListener('click', createRipple)
+    }
+    isInitialized = false
+    currentElement = null
+  }
+
+  watch(
+    target,
+    (newTarget) => {
+      if (newTarget) {
+        initialize(newTarget)
+      } else {
+        cleanup()
+      }
+    },
+    { immediate: true }
+  )
+
+  onUnmounted(() => {
+    cleanup()
+  })
+}

package/src/composables/useScrollLock.ts

@@ -0,0 +1,25 @@
+import { onUnmounted, watch, type Ref } from 'vue'
+
+/**
+ * Locks body scroll when active, preventing background scrolling.
+ * Compensates for scrollbar width to prevent layout shift.
+ */
+export function useScrollLock(isLocked: Ref<boolean>) {
+  const lock = () => {
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth
+    document.body.style.paddingRight = `${scrollbarWidth}px`
+    document.body.style.overflow = 'hidden'
+  }
+
+  const unlock = () => {
+    document.body.style.paddingRight = ''
+    document.body.style.overflow = ''
+  }
+
+  watch(isLocked, (val) => {
+    if (val) lock()
+    else unlock()
+  })
+
+  onUnmounted(() => unlock())
+}

package/src/composables/useSpireConfig.ts

@@ -0,0 +1,27 @@
+import { inject, type ComputedRef } from 'vue'
+import { spireConfigKey, type SpireConfig } from '../components/SpireProvider/SpireProvider.vue'
+
+/**
+ * Access the current Spire UI configuration from a parent SpireProvider.
+ *
+ * @returns The current theme configuration, or undefined if no provider exists
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useSpireConfig } from 'spire-ui'
+ *
+ * const config = useSpireConfig()
+ * // config?.theme, config?.mood, config?.depth, config?.motion
+ * </script>
+ *
+ * <template>
+ *   <div v-if="config">
+ *     Current mood: {{ config.mood }}
+ *   </div>
+ * </template>
+ * ```
+ */
+export function useSpireConfig(): ComputedRef<SpireConfig> | undefined {
+  return inject(spireConfigKey, undefined)
+}

package/src/composables/useStagger.ts

@@ -0,0 +1,224 @@
+import { ref, watch, nextTick, onUnmounted, type Ref } from 'vue'
+
+export interface UseStaggerOptions {
+  delay?: number
+  duration?: number
+  easing?: string
+  from?: {
+    opacity?: number
+    transform?: string
+  }
+  to?: {
+    opacity?: number
+    transform?: string
+  }
+  animateOnVisible?: boolean
+}
+
+export interface UseStaggerReturn {
+  isAnimating: Ref<boolean>
+  animate: () => Promise<void>
+  reset: () => void
+}
+
+/**
+ * Creates sequential stagger animations for list items.
+ * Handles deferred elements (tabs, v-if) by watching for container availability.
+ *
+ * @param container - Ref to the container element
+ * @param itemSelector - CSS selector for items to animate
+ * @param options - Animation configuration
+ * @returns Controls for the stagger animation
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const listRef = ref<HTMLElement | null>(null)
+ * const { animate } = useStagger(listRef, '.list-item', {
+ *   delay: 80,
+ *   from: { opacity: 0, transform: 'translateY(12px)' },
+ *   to: { opacity: 1, transform: 'translateY(0)' }
+ * })
+ *
+ * // Trigger manually when ready
+ * function onTabVisible() {
+ *   animate()
+ * }
+ * </script>
+ *
+ * <template>
+ *   <ul ref="listRef">
+ *     <li class="list-item" v-for="item in items" :key="item.id">{{ item.name }}</li>
+ *   </ul>
+ * </template>
+ * ```
+ */
+export function useStagger(
+  container: Ref<HTMLElement | null>,
+  itemSelector: string,
+  options: UseStaggerOptions = {}
+): UseStaggerReturn {
+  const {
+    delay = 80,
+    duration = 400,
+    easing = 'cubic-bezier(0.16, 1, 0.3, 1)',
+    from = { opacity: 0, transform: 'translateY(16px)' },
+    to = { opacity: 1, transform: 'translateY(0)' },
+    animateOnVisible = false
+  } = options
+
+  const isAnimating = ref(false)
+  let hasAnimatedOnce = false
+  let animationTimeout: ReturnType<typeof setTimeout> | null = null
+
+  function getItems(): HTMLElement[] {
+    if (!container.value) return []
+    return Array.from(container.value.querySelectorAll<HTMLElement>(itemSelector))
+  }
+
+  function forceReflow(element: HTMLElement): void {
+    void element.offsetHeight
+  }
+
+  function applyInitialStyles(items: HTMLElement[]): void {
+    items.forEach((item) => {
+      item.style.transition = 'none'
+      if (from.opacity !== undefined) {
+        item.style.opacity = String(from.opacity)
+      }
+      if (from.transform) {
+        item.style.transform = from.transform
+      }
+    })
+  }
+
+  async function animate(): Promise<void> {
+    await nextTick()
+
+    const items = getItems()
+    if (items.length === 0) return
+
+    if (isAnimating.value) return
+    isAnimating.value = true
+
+    applyInitialStyles(items)
+
+    if (items[0]) {
+      forceReflow(items[0])
+    }
+
+    await new Promise(resolve => requestAnimationFrame(resolve))
+
+    items.forEach((item, index) => {
+      const itemDelay = index * delay
+
+      item.style.transition = `opacity ${duration}ms ${easing} ${itemDelay}ms, transform ${duration}ms ${easing} ${itemDelay}ms`
+
+      if (to.opacity !== undefined) {
+        item.style.opacity = String(to.opacity)
+      }
+      if (to.transform) {
+        item.style.transform = to.transform
+      }
+    })
+
+    const totalDuration = (items.length - 1) * delay + duration
+
+    await new Promise<void>(resolve => {
+      if (animationTimeout) {
+        clearTimeout(animationTimeout)
+      }
+      animationTimeout = setTimeout(() => {
+        animationTimeout = null
+        isAnimating.value = false
+        items.forEach((item) => {
+          item.style.transition = ''
+        })
+        resolve()
+      }, totalDuration + 50)
+    })
+  }
+
+  function reset(): void {
+    const items = getItems()
+    items.forEach((item) => {
+      item.style.opacity = ''
+      item.style.transform = ''
+      item.style.transition = ''
+    })
+    isAnimating.value = false
+    hasAnimatedOnce = false
+  }
+
+  if (animateOnVisible) {
+    watch(
+      container,
+      async (newContainer) => {
+        if (newContainer && !hasAnimatedOnce) {
+          await nextTick()
+          const items = getItems()
+          if (items.length > 0) {
+            hasAnimatedOnce = true
+            animate()
+          }
+        }
+      },
+      { immediate: true }
+    )
+  }
+
+  onUnmounted(() => {
+    if (animationTimeout) {
+      clearTimeout(animationTimeout)
+      animationTimeout = null
+    }
+  })
+
+  return {
+    isAnimating,
+    animate,
+    reset
+  }
+}
+
+/**
+ * Convenience function to apply stagger animation styles directly via CSS.
+ * Returns a style object that can be applied to list items.
+ *
+ * @param index - Item index in the list
+ * @param options - Animation configuration
+ * @returns Style object with animation delay
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <ul>
+ *     <li
+ *       v-for="(item, index) in items"
+ *       :key="item.id"
+ *       :style="getStaggerStyle(index)"
+ *       class="stagger-item"
+ *     >
+ *       {{ item.name }}
+ *     </li>
+ *   </ul>
+ * </template>
+ *
+ * <style>
+ * .stagger-item {
+ *   animation: stagger-in var(--duration-normal) var(--ease-out) both;
+ *   animation-delay: var(--stagger-delay);
+ * }
+ * </style>
+ * ```
+ */
+export function getStaggerStyle(
+  index: number,
+  options: { delay?: number } = {}
+): Record<string, string> {
+  const { delay = 80 } = options
+  return {
+    '--stagger-delay': `${index * delay}ms`,
+    '--stagger-index': String(index)
+  }
+}