@stacksjs/stx 0.2.0 → 0.2.3

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

@@ -0,0 +1,70 @@
+/**
+ * Reactive share composable
+ */
+export declare function useShare(): ShareRef;
+/**
+ * Simple share helper
+ */
+export declare function share(data: ShareData): Promise<ShareResult>;
+/**
+ * Share a URL with optional title and text
+ */
+export declare function shareURL(url: string, title?: string, text?: string): Promise<ShareResult>;
+/**
+ * Share text content
+ */
+export declare function shareText(text: string, title?: string): Promise<ShareResult>;
+/**
+ * Share files
+ */
+export declare function shareFiles(files: File[], title?: string, text?: string): Promise<ShareResult>;
+/**
+ * Create a shareable file from a blob
+ */
+export declare function createShareableFile(blob: Blob, filename: string, mimeType?: string): File;
+/**
+ * Share current page
+ */
+export declare function shareCurrentPage(text?: string): Promise<ShareResult>;
+/**
+ * Copy to clipboard as fallback when share is not supported
+ */
+export declare function shareWithFallback(data: ShareData, fallbackMessage?: string): Promise<ShareResult & { usedFallback?: boolean }>;
+/**
+ * useShare - Web Share API wrapper
+ *
+ * Share content using the native share dialog on supported devices.
+ *
+ * @example
+ * ```ts
+ * const { isSupported, share, canShare } = useShare()
+ *
+ * // Share text
+ * await share({ title: 'Check this out!', text: 'Amazing content', url: 'https://example.com' })
+ *
+ * // Share files
+ * await share({ files: [imageFile] })
+ *
+ * // Check if specific content can be shared
+ * if (canShare({ files: [pdfFile] })) {
+ *   await share({ files: [pdfFile] })
+ * }
+ * ```
+ */
+export declare interface ShareData {
+  title?: string
+  text?: string
+  url?: string
+  files?: File[]
+}
+export declare interface ShareResult {
+  success: boolean
+  error?: Error
+  cancelled?: boolean
+}
+export declare interface ShareRef {
+  isSupported: () => boolean
+  isFileShareSupported: () => boolean
+  canShare: (data?: ShareData) => boolean
+  share: (data: ShareData) => Promise<ShareResult>
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Check if Speech Recognition is supported
+ */
+export declare function isSpeechRecognitionSupported(): boolean;
+/**
+ * Create a speech recognition composable
+ */
+export declare function useSpeechRecognition(options?: SpeechRecognitionOptions): SpeechRecognitionRef;
+/**
+ * Check if Speech Synthesis is supported
+ */
+export declare function isSpeechSynthesisSupported(): boolean;
+/**
+ * Create a speech synthesis composable
+ */
+export declare function useSpeechSynthesis(defaultOptions?: SpeechSynthesisOptions): SpeechSynthesisRef;
+/**
+ * Simple speak function
+ */
+export declare function speak(text: string, options?: SpeechSynthesisOptions): void;
+/**
+ * Stop all speech
+ */
+export declare function stopSpeaking(): void;
+/**
+ * Get available voices
+ */
+export declare function getVoices(): SpeechSynthesisVoice[];
+/**
+ * useSpeech - Web Speech API wrappers
+ *
+ * Speech recognition and synthesis for voice-enabled applications.
+ *
+ * @example
+ * ```ts
+ * // Speech Recognition
+ * const recognition = useSpeechRecognition({
+ *   continuous: false,
+ *   interimResults: true,
+ *   lang: 'en-US'
+ * })
+ *
+ * recognition.subscribe(state => {
+ *   console.log('Transcript:', state.transcript)
+ *   console.log('Is listening:', state.isListening)
+ * })
+ *
+ * recognition.start()
+ *
+ * // Speech Synthesis
+ * const speech = useSpeechSynthesis()
+ * speech.speak('Hello, world!')
+ * ```
+ */
+// ============================================================================
+// Speech Recognition
+// ============================================================================
+export declare interface SpeechRecognitionOptions {
+  continuous?: boolean
+  interimResults?: boolean
+  lang?: string
+  maxAlternatives?: number
+  grammars?: SpeechGrammarList
+}
+export declare interface SpeechRecognitionState {
+  isListening: boolean
+  transcript: string
+  finalTranscript: string
+  interimTranscript: string
+  confidence: number
+  isSupported: boolean
+  error: string | null
+}
+export declare interface SpeechRecognitionResult {
+  transcript: string
+  confidence: number
+  isFinal: boolean
+}
+export declare interface SpeechRecognitionRef {
+  get: () => SpeechRecognitionState
+  subscribe: (fn: (state: SpeechRecognitionState) => void) => () => void
+  start: () => void
+  stop: () => void
+  abort: () => void
+  toggle: () => void
+  isSupported: () => boolean
+  on: (event: 'result' | 'error' | 'start' | 'end', callback: (data?: any) => void) => () => void
+}
+// ============================================================================
+// Speech Synthesis
+// ============================================================================
+export declare interface SpeechSynthesisOptions {
+  voice?: string | number
+  rate?: number
+  pitch?: number
+  volume?: number
+  lang?: string
+}
+export declare interface SpeechSynthesisState {
+  isSpeaking: boolean
+  isPaused: boolean
+  isSupported: boolean
+  voices: SpeechSynthesisVoice[]
+  currentText: string
+}
+export declare interface SpeechSynthesisRef {
+  get: () => SpeechSynthesisState
+  subscribe: (fn: (state: SpeechSynthesisState) => void) => () => void
+  speak: (text: string, options?: SpeechSynthesisOptions) => void
+  stop: () => void
+  pause: () => void
+  resume: () => void
+  toggle: () => void
+  getVoices: () => SpeechSynthesisVoice[]
+  isSupported: () => boolean
+  on: (event: 'start' | 'end' | 'pause' | 'resume' | 'error', callback: (data?: any) => void) => () => void
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Create a reactive storage reference
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const theme = useStorage('theme', 'light')
+ * theme.value = 'dark' // Automatically persists
+ *
+ * // With options
+ * const user = useStorage<User>('user', null, {
+ *   storage: 'session',
+ *   mergeDefaults: true
+ * })
+ *
+ * // Subscribe to changes
+ * theme.subscribe((newValue) => console.log('Theme changed:', newValue))
+ * ```
+ */
+export declare function useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>;
+/**
+ * Shorthand for useStorage with localStorage
+ */
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
+/**
+ * Shorthand for useStorage with sessionStorage
+ */
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
+/**
+ * Clear all items from storage
+ */
+export declare function clearStorage(type?: StorageType): void;
+/**
+ * Get all keys from storage
+ */
+export declare function getStorageKeys(type?: StorageType): string[];
+/**
+ * Get storage size in bytes (approximate)
+ */
+export declare function getStorageSize(type?: StorageType): number;
+export declare interface UseStorageOptions<T> {
+  storage?: StorageType
+  default?: T
+  serializer?: {
+    read: (value: string) => T
+    write: (value: T) => string
+  }
+  mergeDefaults?: boolean
+  listenToStorageChanges?: boolean
+}
+export declare interface StorageRef<T> {
+  value: T
+  get: () => T
+  set: (value: T) => void
+  remove: () => void
+  subscribe: (callback: (value: T, prev: T | undefined) => void) => () => void
+}
+/**
+ * useStorage - Reactive localStorage/sessionStorage composable
+ *
+ * Similar to Nuxt's useStorage but for STX applications.
+ * Provides a reactive, type-safe wrapper around Web Storage APIs.
+ */
+export type StorageType = 'local' | 'session'

package/dist/composables/use-text-selection.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Create a reactive text selection tracker
+ *
+ * @example
+ * ```ts
+ * const selection = useTextSelection({
+ *   onSelect: (state) => {
+ *     console.log('Selected text:', state.text)
+ *   }
+ * })
+ *
+ * // Subscribe to selection changes
+ * selection.subscribe((state) => {
+ *   if (state.text) {
+ *     showTooltip(state.rects[0], state.text)
+ *   }
+ * })
+ *
+ * // Get currently selected text
+ * const text = selection.getText()
+ *
+ * // Clear selection
+ * selection.clear()
+ * ```
+ */
+export declare function useTextSelection(options?: TextSelectionOptions): TextSelectionRef;
+/**
+ * Track text selection within a specific element
+ *
+ * @example
+ * ```ts
+ * const selection = useElementTextSelection(editorRef)
+ *
+ * selection.subscribe((text) => {
+ *   console.log('Selected in editor:', text)
+ * })
+ * ```
+ */
+export declare function useElementTextSelection(element: Element | null): void;
+/**
+ * Create a selection popup that appears when text is selected
+ *
+ * @example
+ * ```ts
+ * const popup = useSelectionPopup({
+ *   onShow: (text, position) => {
+ *     showPopup(position.x, position.y, text)
+ *   },
+ *   onHide: () => {
+ *     hidePopup()
+ *   }
+ * })
+ * ```
+ */
+export declare function useSelectionPopup(options: {
+  onShow?: (text: string, position: { x: number, y: number }) => void
+  onHide?: () => void
+  minLength?: number
+}): void;
+/**
+ * Copy selected text to clipboard with custom formatting
+ *
+ * @example
+ * ```ts
+ * const copy = useCopySelection()
+ *
+ * // Copy with markdown formatting
+ * copy.copyAsMarkdown()
+ *
+ * // Copy with custom prefix
+ * copy.copyWithPrefix('> ')
+ * ```
+ */
+export declare function useCopySelection(): void;
+/**
+ * Text Selection Composables
+ *
+ * Reactive utilities for tracking and manipulating text selection.
+ */
+export declare interface TextSelectionState {
+  text: string
+  rects: DOMRect[]
+  ranges: Range[]
+  isCollapsed: boolean
+}
+export declare interface TextSelectionOptions {
+  onSelect?: (state: TextSelectionState) => void
+  onClear?: () => void
+}
+export declare interface TextSelectionRef {
+  get: () => TextSelectionState
+  subscribe: (fn: (state: TextSelectionState) => void) => () => void
+  getText: () => string
+  clear: () => void
+  selectAll: (element?: Element) => void
+  getRects: () => DOMRect[]
+}

package/dist/composables/use-wake-lock.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Check if Wake Lock API is supported
+ */
+export declare function isWakeLockSupported(): boolean;
+/**
+ * Create a reactive wake lock controller
+ *
+ * The Screen Wake Lock API prevents the screen from dimming or locking
+ * while your application is active. Useful for video players, presentation
+ * apps, or any application where the user needs to see the screen without
+ * interacting with it.
+ *
+ * @example
+ * ```ts
+ * const wakeLock = useWakeLock()
+ *
+ * // Request wake lock
+ * await wakeLock.request()
+ *
+ * // Subscribe to state changes
+ * wakeLock.subscribe((state) => {
+ *   console.log('Wake lock active:', state.isActive)
+ * })
+ *
+ * // Release when done
+ * await wakeLock.release()
+ *
+ * // Or toggle
+ * await wakeLock.toggle()
+ * ```
+ */
+export declare function useWakeLock(): WakeLockRef;
+/**
+ * Auto-acquire wake lock while component is mounted
+ *
+ * @example
+ * ```ts
+ * // In a video player component
+ * const wakeLock = useAutoWakeLock()
+ *
+ * wakeLock.subscribe((isActive) => {
+ *   console.log('Screen wake lock:', isActive ? 'on' : 'off')
+ * })
+ * ```
+ */
+export declare function useAutoWakeLock(): void;
+/**
+ * Wake lock that only activates while a condition is true
+ *
+ * @example
+ * ```ts
+ * const isPlaying = { value: false }
+ *
+ * const wakeLock = useConditionalWakeLock(() => isPlaying.value)
+ *
+ * // When video starts playing
+ * isPlaying.value = true
+ * wakeLock.check() // Acquires wake lock
+ *
+ * // When video pauses
+ * isPlaying.value = false
+ * wakeLock.check() // Releases wake lock
+ * ```
+ */
+export declare function useConditionalWakeLock(condition: () => boolean): void;
+/**
+ * Wake Lock Composables
+ *
+ * Reactive utilities for the Screen Wake Lock API to prevent devices from sleeping.
+ */
+export declare interface WakeLockState {
+  isSupported: boolean
+  isActive: boolean
+  type: 'screen' | null
+  error: Error | null
+}
+export declare interface WakeLockRef {
+  get: () => WakeLockState
+  subscribe: (fn: (state: WakeLockState) => void) => () => void
+  request: () => Promise<boolean>
+  release: () => Promise<void>
+  toggle: () => Promise<boolean>
+  isSupported: () => boolean
+  isActive: () => boolean
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Check if WebSocket is supported
+ */
+export declare function isWebSocketSupported(): boolean;
+/**
+ * Create a reactive WebSocket connection
+ *
+ * @example
+ * ```ts
+ * const ws = useWebSocket('wss://echo.websocket.org', {
+ *   autoReconnect: true,
+ *   onMessage: (event) => console.log('Received:', event.data),
+ * })
+ *
+ * // Subscribe to state changes
+ * ws.subscribe((state) => {
+ *   console.log('Status:', state.status)
+ *   console.log('Last data:', state.data)
+ * })
+ *
+ * // Send a message
+ * ws.send('Hello!')
+ *
+ * // Close connection
+ * ws.close()
+ * ```
+ */
+export declare function useWebSocket<T = unknown>(url: string | URL, options?: WebSocketOptions): WebSocketRef<T> & { on: (event: WebSocketEventType, callback: WebSocketEventCallback) => () => void };
+export declare interface WebSocketState<T = unknown> {
+  status: WebSocketStatus
+  data: T | null
+  error: Event | null
+  ws: WebSocket | null
+}
+export declare interface WebSocketOptions {
+  protocols?: string | string[]
+  autoReconnect?: boolean | {
+    retries?: number
+    delay?: number
+    maxDelay?: number
+    onFailed?: () => void
+  }
+  heartbeat?: boolean | {
+    message?: string | ArrayBuffer | Blob
+    interval?: number
+    pongTimeout?: number
+  }
+  immediate?: boolean
+  onOpen?: (event: Event) => void
+  onMessage?: (event: MessageEvent) => void
+  onClose?: (event: CloseEvent) => void
+  onError?: (event: Event) => void
+}
+export declare interface WebSocketRef<T = unknown> {
+  get: () => WebSocketState<T>
+  subscribe: (fn: (state: WebSocketState<T>) => void) => () => void
+  send: (data: string | ArrayBuffer | Blob) => boolean
+  open: () => void
+  close: (code?: number, reason?: string) => void
+  ws: () => WebSocket | null
+}
+/**
+ * WebSocket Composables
+ *
+ * Reactive utilities for WebSocket communication with auto-reconnect support.
+ */
+export type WebSocketStatus = 'connecting' | 'open' | 'closing' | 'closed'
+declare type WebSocketEventType = 'open' | 'message' | 'close' | 'error'
+declare type WebSocketEventCallback = (event: Event | MessageEvent | CloseEvent) => void

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

@@ -0,0 +1,84 @@
+/**
+ * Track window size reactively
+ *
+ * @example
+ * ```ts
+ * const size = useWindowSize()
+ * console.log(size.width, size.height)
+ *
+ * size.subscribe(({ width, height }) => {
+ *   console.log('Window resized:', width, height)
+ * })
+ * ```
+ */
+export declare function useWindowSize(): WindowSizeRef;
+/**
+ * Track scroll position reactively
+ *
+ * @example
+ * ```ts
+ * const scroll = useScroll()
+ * console.log(scroll.x, scroll.y)
+ *
+ * scroll.subscribe(({ y }) => {
+ *   if (y > 100) showBackToTop()
+ * })
+ *
+ * scroll.scrollToTop()
+ * ```
+ */
+export declare function useScroll(): ScrollRef;
+/**
+ * Track document visibility
+ *
+ * @example
+ * ```ts
+ * const visibility = useVisibility()
+ *
+ * visibility.subscribe((visible) => {
+ *   if (!visible) pauseVideo()
+ *   else resumeVideo()
+ * })
+ * ```
+ */
+export declare function useVisibility(): VisibilityRef;
+/**
+ * Reactive document title
+ *
+ * @example
+ * ```ts
+ * const title = useTitle('My App')
+ * title.value = 'New Page - My App'
+ * ```
+ */
+export declare function useTitle(initialTitle?: string): { value: string; set: (title: string) => void };
+/**
+ * Reactive favicon
+ */
+export declare function useFavicon(href?: string): { value: string; set: (href: string) => void };
+/**
+ * useWindow - Reactive window properties composables
+ *
+ * Provides reactive tracking of window size, scroll position, visibility, etc.
+ */
+export declare interface WindowSize {
+  width: number
+  height: number
+}
+export declare interface ScrollPosition {
+  x: number
+  y: number
+}
+export declare interface WindowSizeRef extends WindowSize {
+  subscribe: (callback: (size: WindowSize) => void) => () => void
+}
+export declare interface ScrollRef extends ScrollPosition {
+  subscribe: (callback: (position: ScrollPosition) => void) => () => void
+  scrollTo: (options: ScrollToOptions | number, y?: number) => void
+  scrollToTop: () => void
+  scrollToBottom: () => void
+}
+export declare interface VisibilityRef {
+  isVisible: boolean
+  subscribe: (callback: (visible: boolean) => void) => () => void
+}