@stacksjs/stx 0.2.0 → 0.2.3

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

@@ -0,0 +1,70 @@
+/**
+ * Parse all cookies from document.cookie
+ */
+export declare function parseCookies(): Record<string, string>;
+/**
+ * Get a specific cookie value
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Set a cookie
+ */
+export declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/**
+ * Remove a cookie
+ */
+export declare function removeCookie(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * Create a reactive cookie reference
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const token = useCookie<string>('auth_token')
+ * token.value = 'abc123' // Automatically persists
+ *
+ * // With options
+ * const session = useCookie<SessionData>('session', {
+ *   maxAge: 60 * 60 * 24 * 7, // 7 days
+ *   secure: true,
+ *   sameSite: 'strict'
+ * })
+ *
+ * // Subscribe to changes
+ * token.subscribe((newValue) => console.log('Token changed:', newValue))
+ * ```
+ */
+export declare function useCookie<T = string>(name: string, options?: CookieOptions): CookieRef<T>;
+/**
+ * Get all cookies as an object
+ */
+export declare function useCookies(): Record<string, string>;
+/**
+ * Clear all cookies (that are accessible)
+ */
+export declare function clearCookies(options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * useCookie - Reactive cookie composable
+ *
+ * Similar to Nuxt's useCookie but for STX applications.
+ * Provides a reactive, type-safe wrapper around document.cookie.
+ */
+export declare interface CookieOptions {
+  maxAge?: number
+  expires?: Date | number | string
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+  default?: unknown
+  encode?: (value: string) => string
+  decode?: (value: string) => string
+}
+export declare interface CookieRef<T> {
+  value: T | null
+  get: () => T | null
+  set: (value: T, options?: CookieOptions) => void
+  remove: () => void
+  subscribe: (callback: (value: T | null, prev: T | null) => void) => () => void
+}

package/dist/composables/use-device-orientation.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Check if DeviceOrientation is supported
+ */
+export declare function isDeviceOrientationSupported(): boolean;
+/**
+ * Check if DeviceMotion is supported
+ */
+export declare function isDeviceMotionSupported(): boolean;
+/**
+ * Request permission for device orientation (required on iOS 13+)
+ */
+export declare function requestOrientationPermission(): Promise<boolean>;
+/**
+ * Request permission for device motion (required on iOS 13+)
+ */
+export declare function requestMotionPermission(): Promise<boolean>;
+/**
+ * Create a reactive device orientation tracker
+ *
+ * @example
+ * ```ts
+ * const orientation = useDeviceOrientation()
+ *
+ * // Request permission first (required on iOS)
+ * await orientation.requestPermission()
+ *
+ * // Subscribe to orientation changes
+ * orientation.subscribe((state) => {
+ *   console.log('Alpha (compass):', state.alpha)
+ *   console.log('Beta (front/back):', state.beta)
+ *   console.log('Gamma (left/right):', state.gamma)
+ * })
+ * ```
+ */
+export declare function useDeviceOrientation(): DeviceOrientationRef;
+/**
+ * Create a reactive device motion tracker
+ *
+ * @example
+ * ```ts
+ * const motion = useDeviceMotion()
+ *
+ * // Request permission first (required on iOS)
+ * await motion.requestPermission()
+ *
+ * // Subscribe to motion changes
+ * motion.subscribe((state) => {
+ *   console.log('Acceleration:', state.acceleration)
+ *   console.log('Rotation rate:', state.rotationRate)
+ * })
+ * ```
+ */
+export declare function useDeviceMotion(): DeviceMotionRef;
+/**
+ * Simple tilt detection for parallax effects
+ *
+ * @example
+ * ```ts
+ * const tilt = useParallax()
+ *
+ * tilt.subscribe(({ x, y }) => {
+ *   element.style.transform = `translate(${x * 10}px, ${y * 10}px)`
+ * })
+ * ```
+ */
+export declare function useParallax(): void;
+/**
+ * Device Orientation & Motion Composables
+ *
+ * Reactive utilities for device orientation and motion sensors.
+ */
+export declare interface DeviceOrientationState {
+  isSupported: boolean
+  isAbsolute: boolean
+  alpha: number | null
+  beta: number | null
+  gamma: number | null
+}
+export declare interface DeviceMotionState {
+  isSupported: boolean
+  acceleration: {
+    x: number | null
+    y: number | null
+    z: number | null
+  }
+  accelerationIncludingGravity: {
+    x: number | null
+    y: number | null
+    z: number | null
+  }
+  rotationRate: {
+    alpha: number | null
+    beta: number | null
+    gamma: number | null
+  }
+  interval: number
+}
+export declare interface DeviceOrientationRef {
+  get: () => DeviceOrientationState
+  subscribe: (fn: (state: DeviceOrientationState) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}
+export declare interface DeviceMotionRef {
+  get: () => DeviceMotionState
+  subscribe: (fn: (state: DeviceMotionState) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}

package/dist/composables/use-event-source.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Check if EventSource is supported
+ */
+export declare function isEventSourceSupported(): boolean;
+/**
+ * Create a reactive Server-Sent Events connection
+ *
+ * @example
+ * ```ts
+ * const sse = useEventSource('/api/events', {
+ *   events: ['notification', 'update'],
+ *   onMessage: (event) => console.log('Message:', event.data),
+ * })
+ *
+ * // Subscribe to state changes
+ * sse.subscribe((state) => {
+ *   console.log('Status:', state.status)
+ *   console.log('Last data:', state.data)
+ * })
+ *
+ * // Listen to specific events
+ * sse.on('notification', (event) => {
+ *   console.log('Notification:', event.data)
+ * })
+ *
+ * // Close connection
+ * sse.close()
+ * ```
+ */
+export declare function useEventSource<T = unknown>(url: string | URL, options?: EventSourceOptions): EventSourceRef<T>;
+/**
+ * Simple SSE connection for receiving JSON data
+ *
+ * @example
+ * ```ts
+ * const { data, status, close } = useSSE<{ count: number }>('/api/counter')
+ *
+ * data.subscribe((value) => {
+ *   console.log('Count:', value?.count)
+ * })
+ * ```
+ */
+export declare function useSSE<T = unknown>(url: string): void;
+export declare interface EventSourceState<T = unknown> {
+  status: EventSourceStatus
+  data: T | null
+  event: string | null
+  lastEventId: string | null
+  error: Event | null
+}
+export declare interface EventSourceOptions {
+  withCredentials?: boolean
+  autoReconnect?: boolean | {
+    retries?: number
+    delay?: number
+    onFailed?: () => void
+  }
+  immediate?: boolean
+  events?: string[]
+  onOpen?: (event: Event) => void
+  onMessage?: (event: MessageEvent) => void
+  onError?: (event: Event) => void
+}
+export declare interface EventSourceRef<T = unknown> {
+  get: () => EventSourceState<T>
+  subscribe: (fn: (state: EventSourceState<T>) => void) => () => void
+  open: () => void
+  close: () => void
+  eventSource: () => EventSource | null
+  on: (eventName: string, callback: (event: MessageEvent) => void) => () => void
+}
+/**
+ * Event Source (SSE) Composables
+ *
+ * Reactive utilities for Server-Sent Events.
+ */
+export type EventSourceStatus = 'connecting' | 'open' | 'closed' | 'error'

package/dist/composables/use-eye-dropper.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Check if EyeDropper API is supported
+ */
+export declare function isEyeDropperSupported(): boolean;
+/**
+ * Create a reactive eye dropper color picker
+ *
+ * The EyeDropper API allows users to pick colors from anywhere on their
+ * screen, not just within the browser window. Great for design tools,
+ * color pickers, and accessibility features.
+ *
+ * @example
+ * ```ts
+ * const eyeDropper = useEyeDropper({
+ *   onPick: (color) => {
+ *     console.log('Picked color:', color) // e.g., "#ff6188"
+ *   }
+ * })
+ *
+ * // Subscribe to state changes
+ * eyeDropper.subscribe((state) => {
+ *   if (state.sRGBHex) {
+ *     document.body.style.backgroundColor = state.sRGBHex
+ *   }
+ * })
+ *
+ * // Open the color picker
+ * const color = await eyeDropper.open()
+ * ```
+ */
+export declare function useEyeDropper(options?: EyeDropperOptions): EyeDropperRef;
+/**
+ * Simple color picker that returns the color
+ *
+ * @example
+ * ```ts
+ * const color = await pickColor()
+ * if (color) {
+ *   console.log('Picked:', color)
+ * }
+ * ```
+ */
+export declare function pickColor(): Promise<string | null>;
+/**
+ * Convert hex color to RGB values
+ */
+export declare function hexToRgb(hex: string): { r: number, g: number, b: number } | null;
+/**
+ * Convert hex color to HSL values
+ */
+export declare function hexToHsl(hex: string): { h: number, s: number, l: number } | null;
+/**
+ * Pick a color with history tracking
+ *
+ * @example
+ * ```ts
+ * const colorPicker = useColorHistory({
+ *   maxHistory: 10
+ * })
+ *
+ * await colorPicker.pick()
+ *
+ * colorPicker.subscribe((state) => {
+ *   console.log('History:', state.history)
+ *   console.log('Current:', state.current)
+ * })
+ * ```
+ */
+export declare function useColorHistory(options?: {
+  maxHistory?: number
+  onPick?: (color: string) => void
+}): void;
+/**
+ * EyeDropper Composables
+ *
+ * Reactive utilities for the EyeDropper API to pick colors from the screen.
+ */
+export declare interface EyeDropperState {
+  isSupported: boolean
+  isOpen: boolean
+  sRGBHex: string | null
+  error: Error | null
+}
+export declare interface EyeDropperResult {
+  sRGBHex: string
+}
+export declare interface EyeDropperOptions {
+  onPick?: (color: string) => void
+  onAbort?: () => void
+  onError?: (error: Error) => void
+}
+export declare interface EyeDropperRef {
+  get: () => EyeDropperState
+  subscribe: (fn: (state: EyeDropperState) => void) => () => void
+  open: () => Promise<string | null>
+  isSupported: () => boolean
+}
+declare interface EyeDropperConstructor {
+  new (): {
+    open: (options?: { signal?: AbortSignal }) => Promise<EyeDropperResult>
+  }
+}
+declare namespace global {
+  interface Window {
+  EyeDropper?: EyeDropperConstructor
+}
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Reactive fetch with loading/error states
+ */
+export declare function useFetch<T = unknown>(url: string | (() => string), options?: FetchOptions<T>): FetchRef<T>;
+/**
+ * Generic async data fetcher
+ */
+export declare function useAsyncData<T>(fetcher: () => Promise<T>, options?: {
+    immediate?: boolean
+    transform?: (data: T) => T
+    default?: T
+    key?: string
+    cacheTime?: number
+  }): FetchRef<T>;
+/**
+ * POST request helper
+ */
+export declare function usePost<T = unknown, B = unknown>(url: string, options?: Omit<FetchOptions<T>, 'method' | 'body'>): {
+  execute: (body?: B) => Promise<T | null>
+  state: FetchRef<T>
+};
+/**
+ * Clear fetch cache
+ */
+export declare function clearFetchCache(key?: string): void;
+/**
+ * Prefetch data into cache
+ */
+export declare function prefetch<T>(url: string, options?: FetchOptions<T>): Promise<void>;
+/**
+ * useFetch - Reactive data fetching with loading/error states
+ *
+ * Provides a streamlined API for fetching data with automatic state management.
+ *
+ * @example
+ * ```ts
+ * // Basic fetch
+ * const { data, loading, error, refresh } = useFetch('/api/users')
+ *
+ * // With options
+ * const { data } = useFetch('/api/users', {
+ *   method: 'POST',
+ *   body: { name: 'John' },
+ *   immediate: false, // Don't fetch immediately
+ * })
+ *
+ * // Async data with transform
+ * const { data } = useAsyncData(
+ *   () => fetch('/api/users').then(r => r.json()),
+ *   { transform: (data) => data.users }
+ * )
+ * ```
+ */
+export declare interface FetchOptions<T = unknown> extends Omit<RequestInit, 'body'> {
+  body?: BodyInit | Record<string, unknown> | null
+  baseURL?: string
+  query?: Record<string, string | number | boolean | undefined>
+  immediate?: boolean
+  transform?: (data: unknown) => T
+  parseResponse?: (response: Response) => Promise<unknown>
+  timeout?: number
+  retry?: number
+  retryDelay?: number
+  key?: string
+  cacheTime?: number
+  refetchOnFocus?: boolean
+  refetchInterval?: number
+  default?: T
+}
+export declare interface FetchState<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
+  status: number | null
+  statusText: string | null
+}
+export declare interface FetchRef<T> {
+  get: () => FetchState<T>
+  subscribe: (fn: (state: FetchState<T>) => void) => () => void
+  refresh: () => Promise<void>
+  execute: () => Promise<void>
+  abort: () => void
+  isLoading: () => boolean
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Reactive fullscreen controller
+ */
+export declare function useFullscreen(target?: Element | (() => Element | null) | null, options?: FullscreenOptions): FullscreenRef;
+/**
+ * Simple fullscreen toggle for document
+ */
+export declare function toggleFullscreen(): Promise<void>;
+/**
+ * Check if currently in fullscreen mode
+ */
+export declare function isInFullscreen(): boolean;
+/**
+ * useFullscreen - Reactive Fullscreen API wrapper
+ *
+ * Control fullscreen mode for elements or the entire document.
+ *
+ * @example
+ * ```ts
+ * // Document fullscreen
+ * const { isFullscreen, toggle, enter, exit } = useFullscreen()
+ *
+ * // Element fullscreen
+ * const { isFullscreen, toggle } = useFullscreen(videoElement)
+ *
+ * // With keyboard shortcut
+ * useHotkey('f', () => toggle())
+ * ```
+ */
+export declare interface FullscreenState {
+  isFullscreen: boolean
+  isSupported: boolean
+  element: Element | null
+}
+export declare interface FullscreenOptions {
+  navigationUI?: 'auto' | 'hide' | 'show'
+  autoExit?: boolean
+}
+export declare interface FullscreenRef {
+  get: () => FullscreenState
+  subscribe: (fn: (state: FullscreenState) => void) => () => void
+  isFullscreen: () => boolean
+  isSupported: () => boolean
+  enter: () => Promise<void>
+  exit: () => Promise<void>
+  toggle: () => Promise<void>
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Get current position as a Promise
+ */
+export declare function getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
+/**
+ * Calculate distance between two coordinates (Haversine formula)
+ * @returns Distance in meters
+ */
+export declare function calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Reactive geolocation composable with watch support
+ */
+export declare function useGeolocation(options?: GeolocationOptions): GeolocationRef;
+/**
+ * Watch position changes (alias for useGeolocation with watch)
+ */
+export declare function useGeolocationWatch(options?: GeolocationOptions): GeolocationRef;
+/**
+ * useGeolocation - Reactive Geolocation API wrapper
+ *
+ * Provides easy access to the browser's Geolocation API with reactive state.
+ *
+ * @example
+ * ```ts
+ * const geo = useGeolocation()
+ * geo.subscribe(state => {
+ *   console.log(state.coords?.latitude, state.coords?.longitude)
+ * })
+ *
+ * // Or get current position once
+ * const position = await getCurrentPosition()
+ * ```
+ */
+export declare interface GeolocationCoords {
+  latitude: number
+  longitude: number
+  altitude: number | null
+  accuracy: number
+  altitudeAccuracy: number | null
+  heading: number | null
+  speed: number | null
+}
+export declare interface GeolocationState {
+  coords: GeolocationCoords | null
+  timestamp: number | null
+  error: GeolocationPositionError | null
+  loading: boolean
+  supported: boolean
+}
+export declare interface GeolocationOptions {
+  enableHighAccuracy?: boolean
+  timeout?: number
+  maximumAge?: number
+  immediate?: boolean
+}
+export declare interface GeolocationRef {
+  get: () => GeolocationState
+  subscribe: (fn: (state: GeolocationState) => void) => () => void
+  refresh: () => void
+  pause: () => void
+  resume: () => void
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Create a reactive idle detector
+ *
+ * @example
+ * ```ts
+ * const idle = useIdle({
+ *   timeout: 30000, // 30 seconds
+ *   onIdle: () => console.log('User is idle'),
+ *   onActive: () => console.log('User is active'),
+ * })
+ *
+ * // Subscribe to idle state changes
+ * idle.subscribe((state) => {
+ *   console.log('Is idle:', state.isIdle)
+ *   console.log('Idle for:', state.idleTime, 'ms')
+ * })
+ *
+ * // Manually reset the idle timer
+ * idle.reset()
+ * ```
+ */
+export declare function useIdle(options?: IdleOptions): IdleRef;
+/**
+ * Simple boolean idle state
+ *
+ * @example
+ * ```ts
+ * const isIdle = useIdleState(30000) // 30 seconds
+ *
+ * isIdle.subscribe((idle) => {
+ *   console.log('User idle:', idle)
+ * })
+ * ```
+ */
+export declare function useIdleState(timeout?: any): void;
+/**
+ * Track user's last active timestamp
+ *
+ * @example
+ * ```ts
+ * const lastActive = useLastActive()
+ *
+ * lastActive.subscribe((timestamp) => {
+ *   console.log('Last active:', new Date(timestamp))
+ * })
+ * ```
+ */
+export declare function useLastActive(): void;
+/**
+ * Auto-logout after idle timeout
+ *
+ * @example
+ * ```ts
+ * useAutoLogout(5 * 60 * 1000, () => {
+ *   // Logout user after 5 minutes of inactivity
+ *   window.location.href = '/logout'
+ * })
+ * ```
+ */
+export declare function useAutoLogout(timeout: number, onLogout: () => void, options?: { warningTime?: number, onWarning?: (remainingTime: number) => void }): void;
+/**
+ * Idle Detection Composables
+ *
+ * Reactive utilities for detecting user idle state and activity.
+ */
+export declare interface IdleState {
+  isIdle: boolean
+  lastActive: number
+  idleTime: number
+}
+export declare interface IdleOptions {
+  timeout?: number
+  events?: string[]
+  listenTo?: EventTarget
+  initialState?: boolean
+  onIdle?: () => void
+  onActive?: () => void
+}
+export declare interface IdleRef {
+  get: () => IdleState
+  subscribe: (fn: (state: IdleState) => void) => () => void
+  reset: () => void
+  isIdle: () => boolean
+}