@stacksjs/stx 0.2.0 → 0.2.3

package/dist/composables/use-intersection-observer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Observe element intersection with viewport or container
+ */
+export declare function useIntersectionObserver(target: Element | (() => Element | null) | null, callback?: IntersectionCallback, options?: IntersectionObserverOptions): IntersectionObserverRef;
+/**
+ * Simple visibility check - returns true when element is in viewport
+ */
+export declare function useElementVisibility(target: Element | (() => Element | null) | null, options?: Omit<IntersectionObserverOptions, 'once'>): {
+  get: () => boolean
+  subscribe: (fn: (visible: boolean) => void) => () => void
+};
+/**
+ * Lazy load handler - triggers callback once when element becomes visible
+ */
+export declare function useLazyLoad(target: Element | (() => Element | null) | null, onVisible: () => void, options?: Omit<IntersectionObserverOptions, 'once'>): { stop: () => void };
+/**
+ * Infinite scroll handler - triggers callback when sentinel element is visible
+ */
+export declare function useInfiniteScroll(sentinel: Element | (() => Element | null) | null, loadMore: () => void | Promise<void>, options?: IntersectionObserverOptions & {
+    /** Debounce time in ms */
+    debounce?: number
+  }): {
+  stop: () => void
+  start: () => void
+  isLoading: () => boolean
+};
+/**
+ * Track multiple elements' visibility
+ */
+export declare function useIntersectionObserverMultiple(targets: Element[] | (() => Element[]), callback: (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void, options?: Omit<IntersectionObserverOptions, 'once'>): {
+  stop: () => void
+  start: () => void
+  observe: (element: Element) => void
+  unobserve: (element: Element) => void
+};
+/**
+ * useIntersectionObserver - Reactive Intersection Observer API
+ *
+ * Track element visibility for lazy loading, infinite scroll, and animations.
+ *
+ * @example
+ * ```ts
+ * // Basic visibility tracking
+ * const { isVisible, stop } = useIntersectionObserver(element)
+ *
+ * // Lazy loading images
+ * useIntersectionObserver(imgElement, (entry) => {
+ *   if (entry.isIntersecting) {
+ *     imgElement.src = imgElement.dataset.src
+ *   }
+ * }, { once: true })
+ *
+ * // Infinite scroll
+ * useIntersectionObserver(sentinelElement, () => {
+ *   loadMoreItems()
+ * }, { rootMargin: '100px' })
+ * ```
+ */
+export declare interface IntersectionObserverOptions {
+  root?: Element | Document | null
+  rootMargin?: string
+  threshold?: number | number[]
+  once?: boolean
+  immediate?: boolean
+}
+export declare interface IntersectionState {
+  isIntersecting: boolean
+  intersectionRatio: number
+  boundingClientRect: DOMRectReadOnly | null
+  intersectionRect: DOMRectReadOnly | null
+  isVisible: boolean
+  entry: IntersectionObserverEntry | null
+}
+export declare interface IntersectionObserverRef {
+  get: () => IntersectionState
+  subscribe: (fn: (state: IntersectionState) => void) => () => void
+  isVisible: () => boolean
+  stop: () => void
+  start: () => void
+}
+declare type IntersectionCallback = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void

package/dist/composables/use-keyboard.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Track keyboard state
+ */
+export declare function useKeyboard(options?: KeyboardOptions): KeyboardRef;
+/**
+ * Register a hotkey handler
+ */
+export declare function useHotkey(hotkey: string | string[], callback: HotkeyCallback, options?: HotkeyOptions): () => void;
+/**
+ * Check if a specific key is currently pressed
+ */
+export declare function useKeyPressed(key: string, options?: KeyboardOptions): {
+  get: () => boolean
+  subscribe: (fn: (pressed: boolean) => void) => () => void
+};
+/**
+ * Detect key sequences (like Konami code)
+ */
+export declare function useKeySequence(sequence: string[], callback: () => void, options?: { timeout?: number; target?: Window | HTMLElement | Document | null }): () => void;
+/**
+ * Common keyboard shortcuts helper
+ */
+export declare const shortcuts: {
+  save: 'ctrl+s';
+  undo: 'ctrl+z';
+  redo: 'ctrl+shift+z';
+  copy: 'ctrl+c';
+  paste: 'ctrl+v';
+  cut: 'ctrl+x';
+  selectAll: 'ctrl+a';
+  find: 'ctrl+f';
+  replace: 'ctrl+h';
+  newTab: 'ctrl+t';
+  closeTab: 'ctrl+w';
+  refresh: 'ctrl+r';
+  escape: 'escape';
+  enter: 'enter';
+  // Mac alternatives
+  saveMac: 'meta+s';
+  undoMac: 'meta+z';
+  redoMac: 'meta+shift+z';
+  copyMac: 'meta+c';
+  pasteMac: 'meta+v';
+  cutMac: 'meta+x'
+};
+/**
+ * useKeyboard - Reactive keyboard input tracking
+ *
+ * Track keyboard state, handle hotkeys, and manage keyboard shortcuts.
+ *
+ * @example
+ * ```ts
+ * // Track all keyboard state
+ * const keyboard = useKeyboard()
+ * keyboard.subscribe(state => {
+ *   if (state.ctrl && state.pressed.has('s')) {
+ *     console.log('Ctrl+S pressed!')
+ *   }
+ * })
+ *
+ * // Simple hotkey
+ * useHotkey('ctrl+s', (e) => {
+ *   e.preventDefault()
+ *   save()
+ * })
+ *
+ * // Check if specific key is pressed
+ * const isSpacePressed = useKeyPressed('Space')
+ * ```
+ */
+export declare interface KeyboardState {
+  pressed: Set<string>
+  lastKey: string | null
+  lastEvent: KeyboardEvent | null
+  ctrl: boolean
+  alt: boolean
+  shift: boolean
+  meta: boolean
+  timestamp: number
+}
+export declare interface KeyboardOptions {
+  target?: Window | HTMLElement | Document | null
+  capture?: boolean
+  passive?: boolean
+}
+export declare interface KeyboardRef {
+  get: () => KeyboardState
+  subscribe: (fn: (state: KeyboardState) => void) => () => void
+  isPressed: (key: string) => boolean
+  stop: () => void
+}
+export declare interface HotkeyOptions {
+  target?: Window | HTMLElement | Document | null
+  preventDefault?: boolean
+  stopPropagation?: boolean
+  ignoreRepeat?: boolean
+  keyup?: boolean
+  ignoreInputs?: boolean
+}
+declare type HotkeyCallback = (event: KeyboardEvent) => void

package/dist/composables/use-media-query.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Create a reactive media query
+ *
+ * @example
+ * ```ts
+ * const isDark = useMediaQuery('(prefers-color-scheme: dark)')
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ *
+ * isDark.subscribe((matches) => {
+ *   console.log('Dark mode:', matches)
+ * })
+ * ```
+ */
+export declare function useMediaQuery(query: string): MediaQueryRef;
+/**
+ * Reactive dark mode preference
+ */
+export declare function usePreferredDark(): MediaQueryRef;
+/**
+ * Reactive light mode preference
+ */
+export declare function usePreferredLight(): MediaQueryRef;
+/**
+ * Reactive reduced motion preference
+ */
+export declare function usePreferredReducedMotion(): MediaQueryRef;
+/**
+ * Reactive contrast preference
+ */
+export declare function usePreferredContrast(): MediaQueryRef;
+/**
+ * Reactive breakpoint helpers
+ */
+export declare function useBreakpoint(breakpoint: keyof typeof breakpoints): MediaQueryRef;
+export declare function useIsMobile(): MediaQueryRef;
+export declare function useIsTablet(): MediaQueryRef;
+export declare function useIsDesktop(): MediaQueryRef;
+/**
+ * Common breakpoints
+ */
+export declare const breakpoints: {
+  sm: '(min-width: 640px)';
+  md: '(min-width: 768px)';
+  lg: '(min-width: 1024px)';
+  xl: '(min-width: 1280px)';
+  '2xl': '(min-width: 1536px)'
+};
+/**
+ * useMediaQuery - Reactive media query composable
+ *
+ * Provides reactive tracking of CSS media queries.
+ */
+export declare interface MediaQueryRef {
+  matches: boolean
+  subscribe: (callback: (matches: boolean) => void) => () => void
+}

package/dist/composables/use-mouse.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Track mouse position globally or within a target
+ */
+export declare function useMouse(options?: MouseOptions): MouseRef;
+/**
+ * Track mouse position relative to an element
+ */
+export declare function useMouseInElement(element: HTMLElement | (() => HTMLElement | null) | null, options?: Omit<MouseOptions, 'target'>): ElementMouseRef;
+/**
+ * Track pointer (unified mouse + touch + pen)
+ */
+export declare function usePointer(options?: MouseOptions): MouseRef;
+/**
+ * useMouse - Reactive mouse/pointer position tracking
+ *
+ * Track mouse position, movement, and button states.
+ *
+ * @example
+ * ```ts
+ * const mouse = useMouse()
+ * mouse.subscribe(state => {
+ *   console.log(`Mouse at ${state.x}, ${state.y}`)
+ * })
+ *
+ * // Track within a specific element
+ * const elementMouse = useMouseInElement(myElement)
+ * ```
+ */
+export declare interface MouseState {
+  x: number
+  y: number
+  pageX: number
+  pageY: number
+  clientX: number
+  clientY: number
+  movementX: number
+  movementY: number
+  buttons: number
+  isPressed: boolean
+  isInside: boolean
+}
+export declare interface MouseOptions {
+  target?: Window | HTMLElement | null
+  touch?: boolean
+  resetOnLeave?: boolean
+  type?: 'page' | 'client' | 'screen' | 'movement'
+}
+export declare interface MouseRef {
+  get: () => MouseState
+  subscribe: (fn: (state: MouseState) => void) => () => void
+  stop: () => void
+}
+export declare interface ElementMouseState extends MouseState {
+  elementX: number
+  elementY: number
+  elementWidth: number
+  elementHeight: number
+  isOutside: boolean
+}
+export declare interface ElementMouseRef {
+  get: () => ElementMouseState
+  subscribe: (fn: (state: ElementMouseState) => void) => () => void
+  stop: () => void
+}

package/dist/composables/use-mutation-observer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Check if MutationObserver is supported
+ */
+export declare function isMutationObserverSupported(): boolean;
+/**
+ * Create a reactive mutation observer
+ *
+ * @example
+ * ```ts
+ * const observer = useMutationObserver({
+ *   attributes: true,
+ *   childList: true,
+ *   onMutate: (mutations) => {
+ *     mutations.forEach(m => console.log('Mutation:', m.type))
+ *   }
+ * })
+ *
+ * // Start observing an element
+ * observer.observe(document.getElementById('my-element'))
+ *
+ * // Subscribe to state changes
+ * observer.subscribe((state) => {
+ *   console.log('Latest mutations:', state.mutations)
+ * })
+ *
+ * // Stop observing
+ * observer.disconnect()
+ * ```
+ */
+export declare function useMutationObserver(options?: MutationObserverOptions): MutationObserverRef;
+/**
+ * Watch for attribute changes on an element
+ *
+ * @example
+ * ```ts
+ * useAttributeObserver(
+ *   document.getElementById('my-element'),
+ *   ['class', 'data-state'],
+ *   (attr, oldValue, newValue) => {
+ *     console.log(`${attr} changed from ${oldValue} to ${newValue}`)
+ *   }
+ * )
+ * ```
+ */
+export declare function useAttributeObserver(target: Element | null, attributeNames: string[], callback: (attributeName: string, oldValue: string | null, newValue: string | null) => void): () => void;
+/**
+ * Watch for child node changes
+ *
+ * @example
+ * ```ts
+ * useChildListObserver(
+ *   document.getElementById('container'),
+ *   (added, removed) => {
+ *     console.log('Added:', added.length, 'Removed:', removed.length)
+ *   }
+ * )
+ * ```
+ */
+export declare function useChildListObserver(target: Element | null, callback: (added: Node[], removed: Node[]) => void, options?: { subtree?: boolean }): () => void;
+/**
+ * Watch for text content changes
+ *
+ * @example
+ * ```ts
+ * useTextObserver(
+ *   document.getElementById('editable'),
+ *   (oldText, newText) => {
+ *     console.log(`Text changed from "${oldText}" to "${newText}"`)
+ *   }
+ * )
+ * ```
+ */
+export declare function useTextObserver(target: Element | null, callback: (oldText: string | null, newText: string) => void): () => void;
+/**
+ * Mutation Observer Composables
+ *
+ * Reactive utilities for observing DOM mutations.
+ */
+export declare interface MutationObserverState {
+  isSupported: boolean
+  isObserving: boolean
+  mutations: MutationRecord[]
+}
+export declare interface MutationObserverOptions {
+  attributes?: boolean
+  attributeFilter?: string[]
+  attributeOldValue?: boolean
+  characterData?: boolean
+  characterDataOldValue?: boolean
+  childList?: boolean
+  subtree?: boolean
+  onMutate?: (mutations: MutationRecord[]) => void
+}
+export declare interface MutationObserverRef {
+  get: () => MutationObserverState
+  subscribe: (fn: (state: MutationObserverState) => void) => () => void
+  observe: (target: Element | null) => void
+  disconnect: () => void
+  takeRecords: () => MutationRecord[]
+  isSupported: () => boolean
+}

package/dist/composables/use-network.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Create a reactive network status tracker
+ *
+ * @example
+ * ```ts
+ * const network = useNetwork()
+ *
+ * network.subscribe((state) => {
+ *   if (state.isOffline) {
+ *     showOfflineMessage()
+ *   }
+ * })
+ *
+ * if (network.effectiveType === '2g') {
+ *   loadLowQualityImages()
+ * }
+ * ```
+ */
+export declare function useNetwork(): NetworkRef;
+/**
+ * Simple online/offline tracker
+ */
+export declare function useOnline(): { isOnline: boolean; subscribe: (cb: (online: boolean) => void) => () => void };
+/**
+ * useNetwork - Reactive network status composables
+ *
+ * Provides reactive tracking of network connectivity and information.
+ */
+export declare interface NetworkState {
+  isOnline: boolean
+  isOffline: boolean
+  type: string | null
+  effectiveType: '2g' | '3g' | '4g' | 'slow-2g' | null
+  downlink: number | null
+  rtt: number | null
+  saveData: boolean
+}
+export declare interface NetworkRef extends NetworkState {
+  subscribe: (callback: (state: NetworkState) => void) => () => void
+}

package/dist/composables/use-notification.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Reactive notification controller
+ */
+export declare function useNotification(): NotificationRef;
+/**
+ * Simple notification helper
+ */
+export declare function notify(title: string, options?: NotificationOptions): Promise<Notification | null>;
+/**
+ * Check if notifications are supported and permitted
+ */
+export declare function canNotify(): boolean;
+/**
+ * Request notification permission
+ */
+export declare function requestNotificationPermission(): Promise<NotificationPermission>;
+/**
+ * Show notification with common patterns
+ */
+export declare const notifications: {
+  /** Success notification */
+  success: (message: string, options?: NotificationOptions) => unknown;
+  /** Error notification */
+  error: (message: string, options?: NotificationOptions) => unknown;
+  /** Warning notification */
+  warning: (message: string, options?: NotificationOptions) => unknown;
+  /** Info notification */
+  info: (message: string, options?: NotificationOptions) => unknown
+};
+export declare interface NotificationState {
+  permission: NotificationPermission
+  isSupported: boolean
+}
+export declare interface NotificationOptions {
+  body?: string
+  icon?: string
+  badge?: string
+  image?: string
+  tag?: string
+  requireInteraction?: boolean
+  renotify?: boolean
+  silent?: boolean
+  vibrate?: number | number[]
+  data?: unknown
+  autoClose?: number
+  dir?: 'auto' | 'ltr' | 'rtl'
+  lang?: string
+  actions?: NotificationAction[]
+  timestamp?: number
+}
+export declare interface NotificationAction {
+  action: string
+  title: string
+  icon?: string
+}
+export declare interface NotificationRef {
+  get: () => NotificationState
+  subscribe: (fn: (state: NotificationState) => void) => () => void
+  isSupported: () => boolean
+  permission: () => NotificationPermission
+  requestPermission: () => Promise<NotificationPermission>
+  show: (title: string, options?: NotificationOptions) => Notification | null
+  close: (tag: string) => void
+}
+/**
+ * useNotification - Web Notifications API wrapper
+ *
+ * Display native browser notifications with reactive permission state.
+ *
+ * @example
+ * ```ts
+ * const { permission, isSupported, show, requestPermission } = useNotification()
+ *
+ * // Request permission
+ * await requestPermission()
+ *
+ * // Show notification
+ * const notification = show('Hello!', {
+ *   body: 'This is a notification',
+ *   icon: '/icon.png',
+ * })
+ *
+ * // Handle click
+ * notification?.addEventListener('click', () => {
+ *   window.focus()
+ * })
+ * ```
+ */
+export type NotificationPermission = 'default' | 'granted' | 'denied'

package/dist/composables/use-permissions.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Query a single permission
+ */
+export declare function usePermission(name: PermissionName): PermissionRef;
+/**
+ * Query multiple permissions at once
+ */
+export declare function usePermissions(names: PermissionName[]): MultiPermissionRef;
+/**
+ * Check if a permission is granted
+ */
+export declare function isPermissionGranted(name: PermissionName): Promise<boolean>;
+/**
+ * Check if camera permission is granted
+ */
+export declare function hasCameraPermission(): Promise<boolean>;
+/**
+ * Check if microphone permission is granted
+ */
+export declare function hasMicrophonePermission(): Promise<boolean>;
+/**
+ * Check if geolocation permission is granted
+ */
+export declare function hasGeolocationPermission(): Promise<boolean>;
+/**
+ * Check if notifications permission is granted
+ */
+export declare function hasNotificationPermission(): Promise<boolean>;
+/**
+ * Request camera and microphone permissions by accessing media
+ */
+export declare function requestMediaPermissions(options?: { video?: boolean; audio?: boolean }): Promise<{ granted: boolean; stream?: MediaStream; error?: Error }>;
+/**
+ * Common permission groups
+ */
+export declare const permissionGroups: {
+  media: readonly ['camera', unknown];
+  location: readonly [unknown];
+  notifications: readonly ['notifications', unknown];
+  sensors: readonly ['accelerometer', 'gyroscope', unknown];
+  clipboard: readonly ['clipboard-read', unknown]
+};
+export declare interface PermissionStatus {
+  state: PermissionState
+  isGranted: boolean
+  isDenied: boolean
+  isPrompt: boolean
+}
+export declare interface PermissionRef {
+  get: () => PermissionStatus
+  subscribe: (fn: (status: PermissionStatus) => void) => () => void
+  query: () => Promise<PermissionStatus>
+  isSupported: () => boolean
+}
+export declare interface MultiPermissionRef {
+  get: () => Record<string, PermissionStatus>
+  subscribe: (fn: (states: Record<string, PermissionStatus>) => void) => () => void
+  queryAll: () => Promise<Record<string, PermissionStatus>>
+  isSupported: () => boolean
+}
+/**
+ * usePermissions - Permissions API wrapper
+ *
+ * Query and monitor browser permission states for various APIs.
+ *
+ * @example
+ * ```ts
+ * // Check camera permission
+ * const camera = usePermission('camera')
+ * camera.subscribe(state => {
+ *   console.log('Camera permission:', state.state) // 'granted', 'denied', 'prompt'
+ * })
+ *
+ * // Check multiple permissions
+ * const permissions = usePermissions(['camera', 'microphone', 'geolocation'])
+ * permissions.subscribe(states => {
+ *   console.log('Camera:', states.camera)
+ *   console.log('Microphone:', states.microphone)
+ * })
+ * ```
+ */
+export type PermissionName = | 'accelerometer'
+  | 'accessibility-events'
+  | 'ambient-light-sensor'
+  | 'background-fetch'
+  | 'background-sync'
+  | 'bluetooth'
+  | 'camera'
+  | 'clipboard-read'
+  | 'clipboard-write'
+  | 'device-info'
+  | 'display-capture'
+  | 'geolocation'
+  | 'gyroscope'
+  | 'magnetometer'
+  | 'microphone'
+  | 'midi'
+  | 'nfc'
+  | 'notifications'
+  | 'payment-handler'
+  | 'periodic-background-sync'
+  | 'persistent-storage'
+  | 'push'
+  | 'screen-wake-lock'
+  | 'speaker-selection'
+  | 'storage-access'
+  | 'window-management'
+  | 'xr-spatial-tracking'
+export type PermissionState = 'granted' | 'denied' | 'prompt'

package/dist/composables/use-resize-observer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Observe element size changes
+ */
+export declare function useResizeObserver(target: Element | (() => Element | null) | null, callback?: (entries: ResizeObserverEntry[]) => void, options?: ResizeObserverOptions): ResizeObserverRef;
+/**
+ * Observe multiple elements
+ */
+export declare function useResizeObserverMultiple(targets: Element[] | (() => Element[]), callback?: (entries: ResizeObserverEntry[]) => void, options?: ResizeObserverOptions): ResizeObserverRef & { states: () => Map<Element, ResizeObserverState> };
+/**
+ * Get element dimensions reactively
+ */
+export declare function useElementSize(target: Element | (() => Element | null) | null): {
+  get: () => { width: number; height: number }
+  subscribe: (fn: (size: { width: number; height: number }) => void) => () => void
+  isSupported: () => boolean
+};
+/**
+ * Check if ResizeObserver is supported (standalone function)
+ */
+export declare function hasResizeObserver(): boolean;
+/**
+ * useResizeObserver - Resize Observer API wrapper
+ *
+ * Monitor element size changes reactively.
+ *
+ * @example
+ * ```ts
+ * const observer = useResizeObserver(element)
+ * observer.subscribe(entries => {
+ *   console.log('Size changed:', entries[0].contentRect)
+ * })
+ *
+ * // With callback
+ * useResizeObserver(element, (entries) => {
+ *   console.log('Width:', entries[0].contentRect.width)
+ * })
+ * ```
+ */
+export declare interface ResizeObserverSize {
+  width: number
+  height: number
+  inlineSize: number
+  blockSize: number
+}
+export declare interface ResizeObserverState {
+  contentRect: DOMRectReadOnly | null
+  contentBoxSize: ResizeObserverSize | null
+  borderBoxSize: ResizeObserverSize | null
+  devicePixelContentBoxSize: ResizeObserverSize | null
+}
+export declare interface ResizeObserverOptions {
+  box?: 'content-box' | 'border-box' | 'device-pixel-content-box'
+}
+export declare interface ResizeObserverRef {
+  get: () => ResizeObserverState
+  subscribe: (fn: (entries: ResizeObserverEntry[]) => void) => () => void
+  observe: () => void
+  disconnect: () => void
+  isSupported: () => boolean
+}