@sabrenski/spire-ui 0.0.1

package/src/components/TreeView/TreeViewItem.vue

@@ -0,0 +1,288 @@
+<script setup lang="ts">
+import { computed, inject, provide, ref, watch, onMounted, Transition, type Component } from 'vue'
+import { TreeViewKey, TreeViewItemKey } from './keys'
+import type { TreeNode } from './keys'
+import { useInternalIcon } from '../../config/icons'
+
+export interface TreeViewItemProps {
+  /** Node data */
+  node: TreeNode
+}
+
+const props = defineProps<TreeViewItemProps>()
+
+const injectedTreeView = inject(TreeViewKey)
+const injectedParentContext = inject(TreeViewItemKey)
+
+if (!injectedTreeView || !injectedParentContext) {
+  throw new Error('TreeViewItem must be used within TreeView')
+}
+
+const treeView = injectedTreeView
+const parentContext = injectedParentContext
+
+const depth = parentContext.depth
+const parentId = parentContext.parentId
+
+const ExpandIcon = useInternalIcon('expand')
+const CollapseIcon = useInternalIcon('collapse')
+
+const localChildren = ref<TreeNode[] | undefined>(props.node.children)
+const isLoading = computed(() => treeView.loadingIds.value.has(props.node.id))
+
+const isSelected = computed(() => treeView.selectedIds.value.has(props.node.id))
+const isExpanded = computed(() => treeView.expandedIds.value.has(props.node.id))
+const isFocused = computed(() => treeView.focusedId.value === props.node.id)
+
+const hasChildren = computed(() => {
+  if (props.node.isLeaf) return false
+  if (localChildren.value && localChildren.value.length > 0) return true
+  if (treeView.loadChildren && !props.node.isLeaf) return true
+  return false
+})
+
+onMounted(() => {
+  treeView.registerNode(props.node.id, parentId, hasChildren.value)
+})
+
+watch(hasChildren, (val) => {
+  treeView.registerNode(props.node.id, parentId, val)
+})
+
+async function handleToggleExpand() {
+  if (!hasChildren.value) return
+
+  if (!isExpanded.value && treeView.loadChildren && !localChildren.value?.length) {
+    treeView.loadingIds.value.add(props.node.id)
+    try {
+      localChildren.value = await treeView.loadChildren(props.node)
+    } finally {
+      treeView.loadingIds.value.delete(props.node.id)
+    }
+  }
+
+  treeView.toggleExpand(props.node.id)
+}
+
+function handleSelect() {
+  if (props.node.disabled) return
+  treeView.selectNode(props.node.id)
+}
+
+function handleClick() {
+  treeView.setFocusedId(props.node.id)
+  handleSelect()
+}
+
+function handleChevronClick(event: Event) {
+  event.stopPropagation()
+  treeView.setFocusedId(props.node.id)
+  handleToggleExpand()
+}
+
+provide(TreeViewItemKey, {
+  depth: depth + 1,
+  parentId: props.node.id
+})
+
+const itemClasses = computed(() => [
+  'ui-treeview__item',
+  {
+    'ui-treeview__item--selected': isSelected.value,
+    'ui-treeview__item--focused': isFocused.value,
+    'ui-treeview__item--disabled': props.node.disabled,
+    'ui-treeview__item--loading': isLoading.value
+  }
+])
+
+const contentStyle = computed(() => ({
+  paddingLeft: `calc(var(--tree-indent) * ${depth})`
+}))
+</script>
+
+<template>
+  <div
+    :class="itemClasses"
+    role="treeitem"
+    :aria-selected="isSelected"
+    :aria-expanded="hasChildren ? isExpanded : undefined"
+    :aria-disabled="node.disabled"
+    :data-focused="isFocused"
+  >
+    <div
+      class="ui-treeview__content"
+      :style="contentStyle"
+      @click="handleClick"
+    >
+      <button
+        v-if="hasChildren"
+        class="ui-treeview__chevron"
+        :class="{ 'ui-treeview__chevron--expanded': isExpanded }"
+        type="button"
+        tabindex="-1"
+        :aria-label="isExpanded ? 'Collapse' : 'Expand'"
+        @click="handleChevronClick"
+      >
+        <component
+          :is="isExpanded ? CollapseIcon : ExpandIcon"
+          class="ui-treeview__chevron-icon"
+        />
+      </button>
+      <span v-else class="ui-treeview__chevron-placeholder" />
+
+      <span v-if="isLoading" class="ui-treeview__spinner" />
+
+      <component
+        v-if="node.icon && !isLoading"
+        :is="node.icon"
+        class="ui-treeview__icon"
+      />
+
+      <span class="ui-treeview__label">
+        <slot>{{ node.label }}</slot>
+      </span>
+    </div>
+
+    <Transition name="ui-treeview-expand">
+      <div
+        v-if="hasChildren && isExpanded && localChildren"
+        class="ui-treeview__children"
+        role="group"
+      >
+        <TreeViewItem
+          v-for="child in localChildren"
+          :key="child.id"
+          :node="child"
+        />
+      </div>
+    </Transition>
+  </div>
+</template>
+
+<style scoped>
+.ui-treeview__item {
+  user-select: none;
+}
+
+.ui-treeview__content {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+}
+
+.ui-treeview__content:hover {
+  background: var(--bg-tertiary);
+}
+
+.ui-treeview__item--selected > .ui-treeview__content {
+  background: var(--status-info-bg);
+}
+
+.ui-treeview__item--selected > .ui-treeview__content:hover {
+  background: var(--status-info-bg);
+}
+
+.ui-treeview__item--focused > .ui-treeview__content {
+  outline: 2px solid var(--ring-color);
+  outline-offset: -2px;
+}
+
+.ui-treeview__item--disabled > .ui-treeview__content {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.ui-treeview__chevron {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  color: var(--text-tertiary);
+  transition: color 0.15s ease, background-color 0.15s ease;
+}
+
+.ui-treeview__chevron:hover {
+  color: var(--text-primary);
+  background: var(--bg-secondary);
+}
+
+.ui-treeview__chevron-icon {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+  transition: transform 0.15s ease;
+}
+
+.ui-treeview__chevron--expanded .ui-treeview__chevron-icon {
+  transform: rotate(180deg);
+}
+
+.ui-treeview__chevron-placeholder {
+  width: 1.25rem;
+  height: 1.25rem;
+  flex-shrink: 0;
+}
+
+.ui-treeview__spinner {
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid var(--border-default);
+  border-top-color: var(--action-primary);
+  border-radius: var(--radius-full);
+  animation: spin 0.6s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.ui-treeview__icon {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+  color: var(--text-tertiary);
+}
+
+.ui-treeview__label {
+  flex: 1;
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.ui-treeview__children {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.ui-treeview-expand-enter-active,
+.ui-treeview-expand-leave-active {
+  transition: opacity 0.15s ease, transform 0.15s ease;
+  transform-origin: top;
+}
+
+.ui-treeview-expand-enter-from,
+.ui-treeview-expand-leave-to {
+  opacity: 0;
+  transform: scaleY(0.95) translateY(-4px);
+}
+
+.ui-treeview-expand-enter-to,
+.ui-treeview-expand-leave-from {
+  opacity: 1;
+  transform: scaleY(1) translateY(0);
+}
+</style>

package/src/components/TreeView/index.ts

@@ -0,0 +1,11 @@
+export { default as TreeView } from './TreeView.vue'
+export { default as TreeViewItem } from './TreeViewItem.vue'
+
+export type { TreeViewProps } from './TreeView.vue'
+export type { TreeViewItemProps } from './TreeViewItem.vue'
+export type {
+  TreeNode,
+  TreeViewContext,
+  TreeViewItemContext
+} from './keys'
+export { TreeViewKey, TreeViewItemKey } from './keys'

package/src/components/TreeView/keys.ts

@@ -0,0 +1,35 @@
+import type { InjectionKey, Ref, Component } from 'vue'
+
+export interface TreeNode {
+  id: string
+  label: string
+  icon?: Component
+  children?: TreeNode[]
+  disabled?: boolean
+  isLeaf?: boolean
+}
+
+export interface TreeViewContext {
+  selectedIds: Ref<Set<string>>
+  expandedIds: Ref<Set<string>>
+  focusedId: Ref<string | null>
+  multiSelect: Ref<boolean>
+  selectNode: (id: string) => void
+  toggleExpand: (id: string) => void
+  setFocusedId: (id: string | null) => void
+  loadChildren: ((node: TreeNode) => Promise<TreeNode[]>) | null
+  loadingIds: Ref<Set<string>>
+  registerNode: (id: string, parentId: string | null, hasChildren: boolean) => void
+  getVisibleNodes: () => string[]
+  getParentId: (id: string) => string | null
+  getChildIds: (id: string) => string[]
+  hasChildren: (id: string) => boolean
+}
+
+export interface TreeViewItemContext {
+  depth: number
+  parentId: string | null
+}
+
+export const TreeViewKey: InjectionKey<TreeViewContext> = Symbol('treeview')
+export const TreeViewItemKey: InjectionKey<TreeViewItemContext> = Symbol('treeview-item')

package/src/composables/index.ts

@@ -0,0 +1,12 @@
+export { useClickOutside } from './useClickOutside'
+export { useClipboard } from './useClipboard'
+export { useEventListener } from './useEventListener'
+export { useFocusTrap } from './useFocusTrap'
+export { useHoverReveal, type UseHoverRevealOptions } from './useHoverReveal'
+export { useId } from './useId'
+export { useMagnetic, type UseMagneticOptions, type UseMagneticReturn } from './useMagnetic'
+export { useRelativePosition, calculatePosition, type Placement, type PositionResult } from './useRelativePosition'
+export { useRipple, type UseRippleOptions } from './useRipple'
+export { useScrollLock } from './useScrollLock'
+export { useSpireConfig } from './useSpireConfig'
+export { useStagger, getStaggerStyle, type UseStaggerOptions, type UseStaggerReturn } from './useStagger'

package/src/composables/useClickOutside.ts

@@ -0,0 +1,36 @@
+import { onMounted, onUnmounted, type Ref } from 'vue'
+
+/**
+ * Detects clicks outside of a target element and executes a callback.
+ * Essential for modals, dropdowns, and popovers.
+ *
+ * @param el - Ref to the element to watch
+ * @param handler - Callback executed when click occurs outside
+ *
+ * Time Complexity: O(1) per event
+ * Space Complexity: O(1)
+ */
+export function useClickOutside(
+  el: Ref<HTMLElement | null>,
+  handler: () => void
+): void {
+  const listener = (event: MouseEvent | TouchEvent): void => {
+    const target = event.target as Node
+
+    if (!el.value || el.value.contains(target)) {
+      return
+    }
+
+    handler()
+  }
+
+  onMounted(() => {
+    document.addEventListener('mousedown', listener)
+    document.addEventListener('touchstart', listener)
+  })
+
+  onUnmounted(() => {
+    document.removeEventListener('mousedown', listener)
+    document.removeEventListener('touchstart', listener)
+  })
+}

package/src/composables/useClipboard.ts

@@ -0,0 +1,35 @@
+import { ref } from 'vue'
+
+/**
+ * Copy text to clipboard with success state tracking.
+ * @param timeout Reset duration for copied state (ms)
+ */
+export function useClipboard(timeout = 2000) {
+  const copied = ref(false)
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+  const copy = async (text: string): Promise<boolean> => {
+    if (!navigator?.clipboard) {
+      console.warn('Clipboard API not supported')
+      return false
+    }
+
+    try {
+      await navigator.clipboard.writeText(text)
+      copied.value = true
+
+      if (timeoutId) clearTimeout(timeoutId)
+      timeoutId = setTimeout(() => {
+        copied.value = false
+      }, timeout)
+
+      return true
+    } catch (e) {
+      console.error('Failed to copy:', e)
+      copied.value = false
+      return false
+    }
+  }
+
+  return { copy, copied }
+}

package/src/composables/useEventListener.ts

@@ -0,0 +1,48 @@
+import { onMounted, onUnmounted, unref, watch, isRef, type Ref } from 'vue'
+
+type EventTarget = Window | Document | HTMLElement | null
+type MaybeRef<T> = T | Ref<T>
+
+/**
+ * Attaches an event listener with automatic cleanup on unmount.
+ * Prevents memory leaks from forgotten removeEventListener calls.
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  target: MaybeRef<EventTarget>,
+  event: K,
+  callback: (e: WindowEventMap[K]) => void,
+  options?: AddEventListenerOptions
+): void
+
+export function useEventListener(
+  target: MaybeRef<EventTarget>,
+  event: string,
+  callback: (e: Event) => void,
+  options?: AddEventListenerOptions
+): void
+
+export function useEventListener(
+  target: MaybeRef<EventTarget>,
+  event: string,
+  callback: (e: Event) => void,
+  options?: AddEventListenerOptions
+) {
+  const attach = (el: EventTarget) => {
+    el?.addEventListener(event, callback, options)
+  }
+
+  const detach = (el: EventTarget) => {
+    el?.removeEventListener(event, callback, options)
+  }
+
+  if (isRef(target)) {
+    watch(target, (newEl, oldEl) => {
+      if (oldEl) detach(oldEl)
+      if (newEl) attach(newEl)
+    }, { immediate: true })
+  } else {
+    onMounted(() => attach(target))
+  }
+
+  onUnmounted(() => detach(unref(target)))
+}

package/src/composables/useFocusTrap.ts

@@ -0,0 +1,58 @@
+import { watch, nextTick, onUnmounted, type Ref } from 'vue'
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'textarea:not([disabled])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])'
+].join(', ')
+
+/**
+ * Traps focus within a container element when active.
+ * Tab cycles through focusable elements, never escaping the container.
+ * Critical for modal accessibility.
+ */
+export function useFocusTrap(
+  container: Ref<HTMLElement | null>,
+  isActive: Ref<boolean>
+) {
+  const trapFocus = (e: KeyboardEvent) => {
+    if (!isActive.value || !container.value) return
+    if (e.key !== 'Tab') return
+
+    const elements = container.value.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)
+    if (elements.length === 0) return
+
+    const first = elements[0]
+    const last = elements[elements.length - 1]
+
+    if (e.shiftKey) {
+      if (document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      }
+    } else {
+      if (document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+  }
+
+  watch(isActive, async (val) => {
+    if (val) {
+      await nextTick()
+      const first = container.value?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR)
+      first?.focus()
+      window.addEventListener('keydown', trapFocus)
+    } else {
+      window.removeEventListener('keydown', trapFocus)
+    }
+  })
+
+  onUnmounted(() => {
+    window.removeEventListener('keydown', trapFocus)
+  })
+}

package/src/composables/useHoverReveal.ts

@@ -0,0 +1,98 @@
+import { watch, onUnmounted, type Ref } from 'vue'
+
+export interface UseHoverRevealOptions {
+  size?: number
+  opacity?: number
+}
+
+/**
+ * Creates a radial gradient spotlight effect that follows the cursor on hover.
+ * 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 cardRef = ref<HTMLElement | null>(null)
+ * useHoverReveal(cardRef, { size: 200, opacity: 0.1 })
+ * </script>
+ *
+ * <template>
+ *   <div ref="cardRef" data-hover-reveal>Hover over me</div>
+ * </template>
+ * ```
+ */
+export function useHoverReveal(
+  target: Ref<HTMLElement | null>,
+  options: UseHoverRevealOptions = {}
+): void {
+  const { size, opacity } = options
+
+  let isInitialized = false
+  let currentElement: HTMLElement | null = null
+
+  function handleMouseMove(event: MouseEvent) {
+    if (!target.value) return
+
+    const rect = target.value.getBoundingClientRect()
+    const x = ((event.clientX - rect.left) / rect.width) * 100
+    const y = ((event.clientY - rect.top) / rect.height) * 100
+
+    target.value.style.setProperty('--mouse-x', `${x}%`)
+    target.value.style.setProperty('--mouse-y', `${y}%`)
+    if (size !== undefined) {
+      target.value.style.setProperty('--effect-hover-reveal-size', `${size}px`)
+    }
+    if (opacity !== undefined) {
+      target.value.style.setProperty('--effect-hover-reveal-opacity', `${opacity}`)
+    }
+  }
+
+  function handleMouseLeave() {
+    if (!target.value) return
+    target.value.style.removeProperty('--mouse-x')
+    target.value.style.removeProperty('--mouse-y')
+  }
+
+  function initialize(element: HTMLElement) {
+    if (isInitialized && currentElement === element) return
+
+    cleanup()
+
+    currentElement = element
+    isInitialized = true
+
+    element.setAttribute('data-hover-reveal', '')
+    element.addEventListener('mousemove', handleMouseMove)
+    element.addEventListener('mouseleave', handleMouseLeave)
+  }
+
+  function cleanup() {
+    if (currentElement) {
+      currentElement.removeEventListener('mousemove', handleMouseMove)
+      currentElement.removeEventListener('mouseleave', handleMouseLeave)
+      currentElement.style.removeProperty('--mouse-x')
+      currentElement.style.removeProperty('--mouse-y')
+    }
+    isInitialized = false
+    currentElement = null
+  }
+
+  watch(
+    target,
+    (newTarget) => {
+      if (newTarget) {
+        initialize(newTarget)
+      } else {
+        cleanup()
+      }
+    },
+    { immediate: true }
+  )
+
+  onUnmounted(() => {
+    cleanup()
+  })
+}

package/src/composables/useId.ts

@@ -0,0 +1,10 @@
+let count = 0
+
+/**
+ * Generates a unique ID for accessibility attributes.
+ * Links labels to inputs, aria-labelledby to modals, etc.
+ * @param prefix Optional prefix (default: 'ui')
+ */
+export function useId(prefix = 'ui'): string {
+  return `${prefix}-${++count}`
+}