@stacksjs/components 0.2.3

package/src/composables/useSEO.ts

@@ -0,0 +1,229 @@
+/**
+ * SEO and meta tag utilities for STX components
+ */
+
+export interface SEOMetaOptions {
+  title?: string
+  description?: string
+  author?: string
+  keywords?: string[]
+  ogImage?: string
+  ogImageWidth?: string
+  ogImageHeight?: string
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  twitterSite?: string
+  twitterCreator?: string
+  canonical?: string
+}
+
+/**
+ * Set document title
+ */
+export function setTitle(title: string, template?: string): void {
+  if (typeof document === 'undefined')
+    return
+
+  document.title = template ? template.replace('%s', title) : title
+}
+
+/**
+ * Set meta tag
+ */
+export function setMeta(name: string, content: string, isProperty = false): void {
+  if (typeof document === 'undefined')
+    return
+
+  const attribute = isProperty ? 'property' : 'name'
+  let meta = document.querySelector(`meta[${attribute}="${name}"]`)
+
+  if (!meta) {
+    meta = document.createElement('meta')
+    meta.setAttribute(attribute, name)
+    document.head.appendChild(meta)
+  }
+
+  meta.setAttribute('content', content)
+}
+
+/**
+ * Set link tag
+ */
+export function setLink(rel: string, href: string): void {
+  if (typeof document === 'undefined')
+    return
+
+  let link = document.querySelector(`link[rel="${rel}"]`) as HTMLLinkElement
+
+  if (!link) {
+    link = document.createElement('link')
+    link.setAttribute('rel', rel)
+    document.head.appendChild(link)
+  }
+
+  link.setAttribute('href', href)
+}
+
+/**
+ * Use SEO meta tags
+ */
+export function useSEO(options: SEOMetaOptions): void {
+  const {
+    title,
+    description,
+    author,
+    keywords,
+    ogImage,
+    ogImageWidth,
+    ogImageHeight,
+    twitterCard = 'summary_large_image',
+    twitterSite,
+    twitterCreator,
+    canonical,
+  } = options
+
+  // Set title
+  if (title) {
+    setTitle(title)
+    setMeta('og:title', title, true)
+    setMeta('twitter:title', title)
+  }
+
+  // Set description
+  if (description) {
+    setMeta('description', description)
+    setMeta('og:description', description, true)
+    setMeta('twitter:description', description)
+  }
+
+  // Set author
+  if (author) {
+    setMeta('author', author)
+  }
+
+  // Set keywords
+  if (keywords && keywords.length > 0) {
+    setMeta('keywords', keywords.join(', '))
+  }
+
+  // Set Open Graph image
+  if (ogImage) {
+    setMeta('og:image', ogImage, true)
+    setMeta('twitter:image', ogImage)
+  }
+
+  if (ogImageWidth) {
+    setMeta('og:image:width', ogImageWidth, true)
+  }
+
+  if (ogImageHeight) {
+    setMeta('og:image:height', ogImageHeight, true)
+  }
+
+  // Set Twitter card
+  setMeta('twitter:card', twitterCard)
+
+  if (twitterSite) {
+    setMeta('twitter:site', twitterSite)
+  }
+
+  if (twitterCreator) {
+    setMeta('twitter:creator', twitterCreator)
+  }
+
+  // Set canonical URL
+  if (canonical) {
+    setLink('canonical', canonical)
+  }
+
+  // Set og:type
+  setMeta('og:type', 'website', true)
+
+  // Set og:url from current URL
+  if (typeof window !== 'undefined') {
+    setMeta('og:url', window.location.href, true)
+  }
+}
+
+/**
+ * Generate SEO meta tags as HTML string for server-side rendering
+ */
+export function generateSEOTags(options: SEOMetaOptions): string {
+  const tags: string[] = []
+
+  const {
+    title,
+    description,
+    author,
+    keywords,
+    ogImage,
+    ogImageWidth,
+    ogImageHeight,
+    twitterCard = 'summary_large_image',
+    twitterSite,
+    twitterCreator,
+    canonical,
+  } = options
+
+  if (title) {
+    tags.push(`<title>${escapeHtml(title)}</title>`)
+    tags.push(`<meta property="og:title" content="${escapeHtml(title)}" />`)
+    tags.push(`<meta name="twitter:title" content="${escapeHtml(title)}" />`)
+  }
+
+  if (description) {
+    tags.push(`<meta name="description" content="${escapeHtml(description)}" />`)
+    tags.push(`<meta property="og:description" content="${escapeHtml(description)}" />`)
+    tags.push(`<meta name="twitter:description" content="${escapeHtml(description)}" />`)
+  }
+
+  if (author) {
+    tags.push(`<meta name="author" content="${escapeHtml(author)}" />`)
+  }
+
+  if (keywords && keywords.length > 0) {
+    tags.push(`<meta name="keywords" content="${escapeHtml(keywords.join(', '))}" />`)
+  }
+
+  if (ogImage) {
+    tags.push(`<meta property="og:image" content="${escapeHtml(ogImage)}" />`)
+    tags.push(`<meta name="twitter:image" content="${escapeHtml(ogImage)}" />`)
+  }
+
+  if (ogImageWidth) {
+    tags.push(`<meta property="og:image:width" content="${escapeHtml(ogImageWidth)}" />`)
+  }
+
+  if (ogImageHeight) {
+    tags.push(`<meta property="og:image:height" content="${escapeHtml(ogImageHeight)}" />`)
+  }
+
+  tags.push(`<meta name="twitter:card" content="${escapeHtml(twitterCard)}" />`)
+
+  if (twitterSite) {
+    tags.push(`<meta name="twitter:site" content="${escapeHtml(twitterSite)}" />`)
+  }
+
+  if (twitterCreator) {
+    tags.push(`<meta name="twitter:creator" content="${escapeHtml(twitterCreator)}" />`)
+  }
+
+  if (canonical) {
+    tags.push(`<link rel="canonical" href="${escapeHtml(canonical)}" />`)
+  }
+
+  tags.push('<meta property="og:type" content="website" />')
+
+  return tags.join('\n')
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;')
+}

package/src/composables/utilities/index.ts

@@ -0,0 +1,7 @@
+// Composable utilities exports
+
+export * from './useClickOutside'
+export * from './useFocusTrap'
+export * from './useKeyboard'
+export * from './useLocalStorage'
+export * from './useMediaQuery'

package/src/composables/utilities/useClickOutside.ts

@@ -0,0 +1,72 @@
+/**
+ * Detects clicks outside a specified element
+ *
+ * @example
+ * ```ts
+ * const cleanup = useClickOutside(
+ *   modalRef,
+ *   () => closeModal(),
+ *   { enabled: isOpen, ignore: ['.tooltip'] }
+ * )
+ * ```
+ */
+
+/**
+ * Options for useClickOutside hook
+ */
+export interface UseClickOutsideOptions {
+  /** Whether the hook is enabled */
+  enabled?: boolean
+  /** CSS selectors to ignore (clicks on these elements won't trigger callback) */
+  ignore?: string[]
+}
+
+/**
+ * Hook to detect clicks outside an element
+ *
+ * @param elementRef - The element to detect clicks outside of
+ * @param callback - Function to call when click occurs outside element
+ * @param options - Configuration options
+ * @returns Cleanup function to remove event listeners
+ */
+export function useClickOutside(
+  elementRef: HTMLElement | null,
+  callback: (event: MouseEvent | TouchEvent) => void,
+  options: UseClickOutsideOptions = {},
+): () => void {
+  const { enabled = true, ignore = [] } = options
+
+  const handleClick = (event: MouseEvent | TouchEvent) => {
+    if (!enabled || !elementRef)
+      return
+
+    const target = event.target as Node
+
+    // Check if click is outside element
+    if (!elementRef.contains(target)) {
+      // Check if target matches any ignore selectors
+      const shouldIgnore = ignore.some((selector) => {
+        const elements = document.querySelectorAll(selector)
+        return Array.from(elements).some(el => el.contains(target))
+      })
+
+      if (!shouldIgnore) {
+        callback(event)
+      }
+    }
+  }
+
+  // Add event listeners
+  if (typeof document !== 'undefined') {
+    document.addEventListener('mousedown', handleClick)
+    document.addEventListener('touchstart', handleClick)
+  }
+
+  // Return cleanup function
+  return () => {
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('mousedown', handleClick)
+      document.removeEventListener('touchstart', handleClick)
+    }
+  }
+}

package/src/composables/utilities/useFocusTrap.ts

@@ -0,0 +1,159 @@
+/**
+ * Traps focus within a container element (useful for modals, dialogs, dropdowns)
+ *
+ * @example
+ * ```ts
+ * const { activate, deactivate } = useFocusTrap(modalRef, {
+ *   initialFocus: firstInputRef,
+ *   returnFocus: true
+ * })
+ *
+ * // When modal opens
+ * activate()
+ *
+ * // When modal closes
+ * deactivate()
+ * ```
+ */
+
+/**
+ * Options for useFocusTrap hook
+ */
+export interface UseFocusTrapOptions {
+  /** Whether the focus trap is enabled */
+  enabled?: boolean
+  /** Element to focus initially (defaults to first focusable element) */
+  initialFocus?: HTMLElement | null
+  /** Whether to return focus to previously focused element on deactivate */
+  returnFocus?: boolean
+  /** Fallback element to focus if no focusable elements found */
+  fallbackFocus?: HTMLElement | null
+}
+
+/**
+ * Hook to trap focus within an element
+ *
+ * @param containerRef - The container element to trap focus within
+ * @param options - Configuration options
+ * @returns Object with activate and deactivate functions
+ */
+export function useFocusTrap(
+  containerRef: HTMLElement | null,
+  options: UseFocusTrapOptions = {},
+): { activate: () => void, deactivate: () => void } {
+  const {
+    enabled = true,
+    initialFocus = null,
+    returnFocus = true,
+    fallbackFocus = null,
+  } = options
+
+  let previouslyFocusedElement: HTMLElement | null = null
+  let isActive = false
+
+  // Get all focusable elements within container
+  function getFocusableElements(): HTMLElement[] {
+    if (!containerRef)
+      return []
+
+    const focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'textarea:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+    ].join(',')
+
+    return Array.from(containerRef.querySelectorAll(focusableSelectors))
+  }
+
+  // Handle tab key
+  function handleTab(event: KeyboardEvent) {
+    if (!enabled || !isActive || !containerRef)
+      return
+
+    const focusableElements = getFocusableElements()
+
+    if (focusableElements.length === 0) {
+      event.preventDefault()
+      return
+    }
+
+    const firstElement = focusableElements[0]
+    const lastElement = focusableElements[focusableElements.length - 1]
+
+    if (event.shiftKey) {
+      // Shift + Tab
+      if (document.activeElement === firstElement || document.activeElement === containerRef) {
+        event.preventDefault()
+        lastElement.focus()
+      }
+    }
+    else {
+      // Tab
+      if (document.activeElement === lastElement) {
+        event.preventDefault()
+        firstElement.focus()
+      }
+    }
+  }
+
+  // Handle escape key
+  function handleEscape(event: KeyboardEvent) {
+    if (event.key === 'Escape' && enabled && isActive) {
+      deactivate()
+    }
+  }
+
+  // Activate focus trap
+  function activate() {
+    if (!enabled || !containerRef || isActive)
+      return
+
+    // Store previously focused element
+    previouslyFocusedElement = document.activeElement as HTMLElement
+
+    // Focus initial element
+    if (initialFocus) {
+      initialFocus.focus()
+    }
+    else {
+      const focusableElements = getFocusableElements()
+      if (focusableElements.length > 0) {
+        focusableElements[0].focus()
+      }
+      else if (fallbackFocus) {
+        fallbackFocus.focus()
+      }
+      else {
+        containerRef.focus()
+      }
+    }
+
+    // Add event listeners
+    document.addEventListener('keydown', handleTab)
+    document.addEventListener('keydown', handleEscape)
+
+    isActive = true
+  }
+
+  // Deactivate focus trap
+  function deactivate() {
+    if (!isActive)
+      return
+
+    // Remove event listeners
+    document.removeEventListener('keydown', handleTab)
+    document.removeEventListener('keydown', handleEscape)
+
+    // Return focus
+    if (returnFocus && previouslyFocusedElement) {
+      previouslyFocusedElement.focus()
+    }
+
+    isActive = false
+  }
+
+  return { activate, deactivate }
+}

package/src/composables/utilities/useKeyboard.ts

@@ -0,0 +1,124 @@
+/**
+ * Hook for keyboard event handling with support for shortcuts and modifiers
+ *
+ * @example
+ * ```ts
+ * useKeyboard([
+ *   { key: 'Escape', handler: () => closeModal() },
+ *   { key: 's', ctrl: true, handler: () => save() },
+ *   { key: ['ArrowUp', 'ArrowDown'], handler: (e) => navigate(e.key) }
+ * ])
+ * ```
+ */
+
+/**
+ * Options for useKeyboard hook
+ */
+export interface UseKeyboardOptions {
+  /** Whether the hook is enabled */
+  enabled?: boolean
+  /** Whether to prevent default browser behavior */
+  preventDefault?: boolean
+  /** Whether to stop event propagation */
+  stopPropagation?: boolean
+  /** Target element for event listener (defaults to document) */
+  target?: HTMLElement | Document | Window | null
+}
+
+/**
+ * Keyboard event handler configuration
+ */
+export interface KeyboardHandler {
+  /** Key or keys to listen for */
+  key: string | string[]
+  /** Handler function to execute */
+  handler: (event: KeyboardEvent) => void
+  /** Whether Ctrl key must be pressed */
+  ctrl?: boolean
+  /** Whether Shift key must be pressed */
+  shift?: boolean
+  /** Whether Alt key must be pressed */
+  alt?: boolean
+  /** Whether Meta (Command on Mac) key must be pressed */
+  meta?: boolean
+}
+
+/**
+ * Hook for keyboard event handling
+ *
+ * @param handlers - Single handler or array of keyboard handlers
+ * @param options - Configuration options
+ * @returns Cleanup function to remove event listeners
+ */
+export function useKeyboard(
+  handlers: KeyboardHandler | KeyboardHandler[],
+  options: UseKeyboardOptions = {},
+): () => void {
+  const {
+    enabled = true,
+    preventDefault = true,
+    stopPropagation = false,
+    target = typeof document !== 'undefined' ? document : null,
+  } = options
+
+  const handlerArray = Array.isArray(handlers) ? handlers : [handlers]
+
+  const handleKeydown = (event: KeyboardEvent) => {
+    if (!enabled)
+      return
+
+    handlerArray.forEach((handler) => {
+      const keys = Array.isArray(handler.key) ? handler.key : [handler.key]
+      const keyMatches = keys.some(k => k.toLowerCase() === event.key.toLowerCase())
+
+      if (!keyMatches)
+        return
+
+      // Check modifier keys
+      if (handler.ctrl !== undefined && handler.ctrl !== event.ctrlKey)
+        return
+      if (handler.shift !== undefined && handler.shift !== event.shiftKey)
+        return
+      if (handler.alt !== undefined && handler.alt !== event.altKey)
+        return
+      if (handler.meta !== undefined && handler.meta !== event.metaKey)
+        return
+
+      // Execute handler
+      if (preventDefault)
+        event.preventDefault()
+      if (stopPropagation)
+        event.stopPropagation()
+
+      handler.handler(event)
+    })
+  }
+
+  // Add event listener
+  if (target) {
+    target.addEventListener('keydown', handleKeydown as EventListener)
+  }
+
+  // Return cleanup function
+  return () => {
+    if (target) {
+      target.removeEventListener('keydown', handleKeydown as EventListener)
+    }
+  }
+}
+
+// Common keyboard shortcuts
+export const KeyboardShortcuts = {
+  ESCAPE: 'Escape',
+  ENTER: 'Enter',
+  SPACE: ' ',
+  TAB: 'Tab',
+  ARROW_UP: 'ArrowUp',
+  ARROW_DOWN: 'ArrowDown',
+  ARROW_LEFT: 'ArrowLeft',
+  ARROW_RIGHT: 'ArrowRight',
+  HOME: 'Home',
+  END: 'End',
+  PAGE_UP: 'PageUp',
+  PAGE_DOWN: 'PageDown',
+} as const