@stacksjs/components 0.2.3

package/src/composables/utilities/useLocalStorage.ts

@@ -0,0 +1,132 @@
+/**
+ * Reactive localStorage hook with cross-tab synchronization
+ *
+ * @example
+ * ```ts
+ * const { value, setValue, removeValue } = useLocalStorage('user', { name: 'John' })
+ *
+ * setValue({ name: 'Jane' })
+ * setValue(prev => ({ ...prev, age: 30 }))
+ * removeValue()
+ * ```
+ */
+
+/**
+ * Options for useLocalStorage hook
+ */
+export interface UseLocalStorageOptions<T> {
+  /** Custom serializer function (defaults to JSON.stringify) */
+  serializer?: (value: T) => string
+  /** Custom deserializer function (defaults to JSON.parse) */
+  deserializer?: (value: string) => T
+  /** Error handler function */
+  onError?: (error: Error) => void
+}
+
+/**
+ * Hook for reactive localStorage with cross-tab sync
+ *
+ * @param key - Storage key
+ * @param initialValue - Initial value if key doesn't exist
+ * @param options - Configuration options
+ * @returns Object with value, setValue, and removeValue
+ */
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T,
+  options: UseLocalStorageOptions<T> = {},
+): {
+    value: T
+    setValue: (newValue: T | ((prev: T) => T)) => void
+    removeValue: () => void
+  } {
+  const {
+    serializer = JSON.stringify,
+    deserializer = JSON.parse,
+    onError = console.error,
+  } = options
+
+  // Get initial value from storage
+  let storedValue: T = initialValue
+
+  try {
+    if (typeof window !== 'undefined') {
+      const item = window.localStorage.getItem(key)
+      if (item !== null) {
+        storedValue = deserializer(item)
+      }
+    }
+  }
+  catch (error) {
+    onError(error as Error)
+  }
+
+  let value = storedValue
+  const listeners = new Set<(newValue: T) => void>()
+
+  // Set value
+  function setValue(newValue: T | ((prev: T) => T)) {
+    try {
+      // Allow value to be a function for same API as useState
+      const valueToStore = typeof newValue === 'function' ? (newValue as (prev: T) => T)(value) : newValue
+
+      value = valueToStore
+
+      // Save to localStorage
+      if (typeof window !== 'undefined') {
+        window.localStorage.setItem(key, serializer(valueToStore))
+      }
+
+      // Notify listeners
+      listeners.forEach(listener => listener(valueToStore))
+    }
+    catch (error) {
+      onError(error as Error)
+    }
+  }
+
+  // Remove value
+  function removeValue() {
+    try {
+      value = initialValue
+
+      if (typeof window !== 'undefined') {
+        window.localStorage.removeItem(key)
+      }
+
+      // Notify listeners
+      listeners.forEach(listener => listener(initialValue))
+    }
+    catch (error) {
+      onError(error as Error)
+    }
+  }
+
+  // Listen for storage events (changes from other tabs/windows)
+  if (typeof window !== 'undefined') {
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === key && event.newValue !== null) {
+        try {
+          const newValue = deserializer(event.newValue)
+          value = newValue
+          listeners.forEach(listener => listener(newValue))
+        }
+        catch (error) {
+          onError(error as Error)
+        }
+      }
+      else if (event.key === key && event.newValue === null) {
+        value = initialValue
+        listeners.forEach(listener => listener(initialValue))
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+  }
+
+  return {
+    value,
+    setValue,
+    removeValue,
+  }
+}

package/src/composables/utilities/useMediaQuery.ts

@@ -0,0 +1,118 @@
+/**
+ * Hook for responsive media queries
+ *
+ * @example
+ * ```ts
+ * const { matches } = useMediaQuery('(min-width: 768px)')
+ * const { matches: isDark } = useIsDarkMode()
+ * const { matches: isMobile } = useIsMobile()
+ * ```
+ */
+
+/**
+ * Options for useMediaQuery hook
+ */
+export interface UseMediaQueryOptions {
+  /** Default value when window.matchMedia is not available */
+  defaultValue?: boolean
+}
+
+/**
+ * Hook for responsive media queries
+ *
+ * @param query - Media query string
+ * @param options - Configuration options
+ * @returns Object with matches boolean and updateMatches function
+ */
+export function useMediaQuery(
+  query: string,
+  options: UseMediaQueryOptions = {},
+): { matches: boolean, updateMatches: () => void } {
+  const { defaultValue = false } = options
+
+  let matches = defaultValue
+  let mediaQueryList: MediaQueryList | null = null
+
+  // Initialize
+  if (typeof window !== 'undefined' && 'matchMedia' in window) {
+    mediaQueryList = window.matchMedia(query)
+    matches = mediaQueryList.matches
+
+    // Listen for changes
+    const handleChange = (event: MediaQueryListEvent) => {
+      matches = event.matches
+    }
+
+    if (mediaQueryList.addEventListener) {
+      mediaQueryList.addEventListener('change', handleChange)
+    }
+    else {
+      // Fallback for older browsers
+      mediaQueryList.addListener(handleChange)
+    }
+  }
+
+  function updateMatches() {
+    if (mediaQueryList) {
+      matches = mediaQueryList.matches
+    }
+  }
+
+  return { matches, updateMatches }
+}
+
+/**
+ * Common responsive breakpoints
+ */
+export const Breakpoints = {
+  'xs': '(min-width: 320px)',
+  'sm': '(min-width: 640px)',
+  'md': '(min-width: 768px)',
+  'lg': '(min-width: 1024px)',
+  'xl': '(min-width: 1280px)',
+  '2xl': '(min-width: 1536px)',
+  'mobile': '(max-width: 767px)',
+  'tablet': '(min-width: 768px) and (max-width: 1023px)',
+  'desktop': '(min-width: 1024px)',
+  'dark': '(prefers-color-scheme: dark)',
+  'light': '(prefers-color-scheme: light)',
+  'reducedMotion': '(prefers-reduced-motion: reduce)',
+  'portrait': '(orientation: portrait)',
+  'landscape': '(orientation: landscape)',
+} as const
+
+/**
+ * Use a predefined breakpoint
+ * @param breakpoint - Breakpoint name from Breakpoints constant
+ */
+export function useBreakpoint(breakpoint: keyof typeof Breakpoints): { matches: boolean, updateMatches: () => void } {
+  return useMediaQuery(Breakpoints[breakpoint])
+}
+
+/**
+ * Check if viewport is mobile (max-width: 767px)
+ */
+export function useIsMobile(): { matches: boolean, updateMatches: () => void } {
+  return useMediaQuery(Breakpoints.mobile)
+}
+
+/**
+ * Check if viewport is desktop (min-width: 1024px)
+ */
+export function useIsDesktop(): { matches: boolean, updateMatches: () => void } {
+  return useMediaQuery(Breakpoints.desktop)
+}
+
+/**
+ * Check if user prefers dark color scheme
+ */
+export function useIsDarkMode(): { matches: boolean, updateMatches: () => void } {
+  return useMediaQuery(Breakpoints.dark)
+}
+
+/**
+ * Check if user prefers reduced motion
+ */
+export function usePrefersReducedMotion(): { matches: boolean, updateMatches: () => void } {
+  return useMediaQuery(Breakpoints.reducedMotion)
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+// Export shared components (these will be imported as .stx files)
+export { default as CodeBlock } from './components/CodeBlock.stx'
+
+export { default as Footer } from './components/Footer.stx'
+export { default as Hero } from './components/Hero.stx'
+export { default as Installation } from './components/Installation.stx'
+// Export composables
+export * from './composables'
+// Export UI components
+export * from './ui/accordion'
+export * from './ui/audio'
+export * from './ui/auth'
+export * from './ui/avatar'
+export * from './ui/badge'
+
+export * from './ui/breadcrumb'
+export * from './ui/button'
+export * from './ui/calendar'
+export * from './ui/card'
+
+export * from './ui/checkbox'
+export * from './ui/combobox'
+export * from './ui/command-palette'
+export * from './ui/dialog'
+export * from './ui/drawer'
+export * from './ui/dropdown'
+export * from './ui/form'
+export * from './ui/image'
+export * from './ui/input'
+export * from './ui/listbox'
+export * from './ui/navigator'
+export * from './ui/notification'
+export * from './ui/pagination'
+export * from './ui/payment'
+export * from './ui/popover'
+export * from './ui/portal'
+export * from './ui/progress'
+export * from './ui/radio'
+export * from './ui/radio-group'
+export * from './ui/select'
+export * from './ui/sidebar'
+export * from './ui/skeleton'
+export * from './ui/spinner'
+export * from './ui/stepper'
+export * from './ui/storage'
+export * from './ui/switch'
+export * from './ui/table'
+export * from './ui/tabs'
+export * from './ui/teleport'
+export * from './ui/textarea'
+export * from './ui/tooltip'
+export * from './ui/transition'
+export * from './ui/video'
+export * from './ui/virtual-list'
+export * from './ui/virtual-table'
+export * from './utils/accessibility'
+export * from './utils/animation'
+export * from './utils/error-handling'
+// Export utilities
+export * from './utils/highlighter'
+export * from './utils/i18n'
+export * from './utils/keep-alive'
+export * from './utils/lazy-loading'
+export * from './utils/prop-validation'
+export * from './utils/theme'
+
+// Types
+export interface ComponentProps {
+  className?: string
+  [key: string]: any
+}
+
+export interface CodeBlockProps extends ComponentProps {
+  code: string
+  language?: string
+  theme?: 'light' | 'dark' | 'auto'
+  lineNumbers?: boolean
+  copyable?: boolean
+}
+
+export interface HeroProps extends ComponentProps {
+  title?: string
+  description?: string
+  githubUrl?: string
+}
+
+export interface FooterProps extends ComponentProps {
+  author?: string
+  authorUrl?: string
+  project?: string
+  projectUrl?: string
+  twitterUrl?: string
+  sponsorUrl?: string
+  coffeeUrl?: string
+}
+
+export interface InstallationProps extends ComponentProps {
+  packageName?: string
+}

package/src/stx.d.ts

@@ -0,0 +1,4 @@
+declare module '*.stx' {
+  const component: any
+  export default component
+}

package/src/ui/accordion/Accordion.stx

@@ -0,0 +1,108 @@
+<script>
+export const items = $props.items || []
+export const allowMultiple = $props.allowMultiple || false
+export const defaultOpen = $props.defaultOpen || []
+export const className = $props.className || ''
+export const onChange = $props.onChange
+
+// Track which items are open
+let openItems = defaultOpen
+
+// Toggle an item
+function toggleItem(index) {
+  if (allowMultiple) {
+    // Multiple items can be open
+    if (openItems.includes(index)) {
+      openItems = openItems.filter(i => i !== index)
+    } else {
+      openItems = [...openItems, index]
+    }
+  } else {
+    // Only one item can be open
+    if (openItems.includes(index)) {
+      openItems = []
+    } else {
+      openItems = [index]
+    }
+  }
+
+  if (onChange) {
+    onChange(openItems)
+  }
+}
+
+// Check if item is open
+function isOpen(index) {
+  return openItems.includes(index)
+}
+
+export const accordionClasses = `divide-y divide-gray-200 dark:divide-gray-700 border border-gray-200 dark:border-gray-700 rounded-lg ${className}`.trim()
+export const itemClasses = ``.trim()
+export const headerClasses = `w-full flex items-center justify-between px-4 py-3 text-left font-medium text-gray-900 dark:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900`.trim()
+export const iconClasses = `w-5 h-5 text-gray-500 dark:text-gray-400 transition-transform duration-200`.trim()
+export const contentClasses = `px-4 py-3 text-gray-700 dark:text-gray-300`.trim()
+</script>
+
+<div class="{{ accordionClasses }}" role="region">
+  @foreach(item in items)
+    <div class="{{ itemClasses }}">
+      <button
+        type="button"
+        class="{{ headerClasses }}"
+        onclick="toggleItem({{ $loop.index }})"
+        aria-expanded="{{ isOpen($loop.index) ? 'true' : 'false' }}"
+        aria-controls="accordion-content-{{ $loop.index }}"
+      >
+        <span>{{ item.title }}</span>
+        <svg
+          class="{{ iconClasses }}"
+          style="transform: rotate({{ isOpen($loop.index) ? '180' : '0' }}deg)"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+        >
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+        </svg>
+      </button>
+
+      @if(isOpen($loop.index))
+        <div
+          id="accordion-content-{{ $loop.index }}"
+          class="{{ contentClasses }}"
+          role="region"
+        >
+          {!! item.content !!}
+        </div>
+      @endif
+    </div>
+  @endforeach
+</div>
+
+<script>
+// Keyboard navigation
+if (typeof window !== 'undefined') {
+  window.addEventListener('DOMContentLoaded', () => {
+    const buttons = document.querySelectorAll('[aria-expanded]')
+
+    buttons.forEach((button, index) => {
+      button.addEventListener('keydown', (event) => {
+        if (event.key === 'ArrowDown') {
+          event.preventDefault()
+          const nextButton = buttons[index + 1]
+          if (nextButton) nextButton.focus()
+        } else if (event.key === 'ArrowUp') {
+          event.preventDefault()
+          const prevButton = buttons[index - 1]
+          if (prevButton) prevButton.focus()
+        } else if (event.key === 'Home') {
+          event.preventDefault()
+          buttons[0].focus()
+        } else if (event.key === 'End') {
+          event.preventDefault()
+          buttons[buttons.length - 1].focus()
+        }
+      })
+    })
+  })
+}
+</script>

package/src/ui/accordion/index.ts

@@ -0,0 +1,14 @@
+export { default as Accordion } from './Accordion.stx'
+
+export interface AccordionItem {
+  title: string
+  content: string
+}
+
+export interface AccordionProps {
+  items: AccordionItem[]
+  allowMultiple?: boolean
+  defaultOpen?: number[]
+  onChange?: (openItems: number[]) => void
+  className?: string
+}

package/src/ui/audio/Audio.stx

@@ -0,0 +1,50 @@
+<script>
+export const src = $props.src || ''
+export const autoplay = $props.autoplay || false
+export const loop = $props.loop || false
+export const muted = $props.muted || false
+export const controls = $props.controls ?? true
+export const preload = $props.preload || 'metadata'
+export const className = $props.className || ''
+export const showWaveform = $props.showWaveform || false
+export const title = $props.title || ''
+
+export const containerClasses = `relative w-full ${className}`.trim()
+export const audioClasses = 'w-full rounded-md bg-gray-100 dark:bg-gray-800'
+</script>
+
+<div class="{{ containerClasses }}">
+  @if(title)
+    <div class="mb-2 px-1">
+      <h3 class="text-sm font-medium text-gray-900 dark:text-gray-100">
+        {{ title }}
+      </h3>
+    </div>
+  @endif
+
+  <audio
+    class="{{ audioClasses }}"
+    src="{{ src }}"
+    controls="{{ controls }}"
+    autoplay="{{ autoplay }}"
+    loop="{{ loop }}"
+    muted="{{ muted }}"
+    preload="{{ preload }}"
+  >
+    Your browser does not support the audio element.
+  </audio>
+
+  @if(showWaveform)
+    <div class="mt-2 h-16 bg-gray-100 dark:bg-gray-800 rounded-md flex items-center justify-center">
+      <svg class="w-full h-full px-4" viewBox="0 0 100 40" preserveAspectRatio="none">
+        <path
+          d="M 0,20 L 10,15 L 20,10 L 30,5 L 40,15 L 50,20 L 60,25 L 70,30 L 80,20 L 90,15 L 100,20"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          class="text-indigo-500 dark:text-indigo-400"
+        />
+      </svg>
+    </div>
+  @endif
+</div>

package/src/ui/audio/README.md

@@ -0,0 +1,42 @@
+# Audio Component
+
+A styled audio player with optional waveform visualization.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+```stx
+@component('Audio', {
+  src: '/audio/podcast.mp3',
+  title: 'Episode 42: Building with STX',
+  controls: true
+})
+@endcomponent
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | Audio file URL (required) |
+| `autoplay` | `boolean` | `false` | Auto-play on load |
+| `loop` | `boolean` | `false` | Loop playback |
+| `muted` | `boolean` | `false` | Start muted |
+| `controls` | `boolean` | `true` | Show native controls |
+| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | Preload strategy |
+| `className` | `string` | `''` | Additional CSS classes |
+| `showWaveform` | `boolean` | `false` | Show waveform visualization |
+| `title` | `string` | `''` | Optional title above player |
+
+## Features
+
+- **Native controls** - Uses browser's native audio controls
+- **Dark mode** - Styled for dark mode
+- **Waveform** - Optional visual waveform display
+- **Accessible** - Proper fallback text
+- **Responsive** - Full-width design

package/src/ui/audio/index.ts

@@ -0,0 +1,13 @@
+export { default as Audio } from './Audio.stx'
+
+export interface AudioProps {
+  src: string
+  autoplay?: boolean
+  loop?: boolean
+  muted?: boolean
+  controls?: boolean
+  preload?: 'none' | 'metadata' | 'auto'
+  className?: string
+  showWaveform?: boolean
+  title?: string
+}