stacks-composables

# Stacks Composables 90+ reactive composables for STX templates. All are auto-imported in STX templates. ## Key Path - Core package: `storage/framework/core/composables/src/` ## Core Reactive Primitives ```typescript // From _shared.ts type MaybeRef<T> = T | Ref<T> type MaybeRefOrGetter<T> = T | Ref<T> | (() => T) unref(val) // unwrap Ref toValue(val) // unwrap Ref or getter isRef(val) // type guard ``` ## State & Reactivity - `useToggle(initial?)` → `[Ref<boolean>, toggle]` - `useCounter(initial?)` → `{ count, increment, decrement, set, reset }` - `useStepper(steps, initial?)` → step navigation - `usePrevious(value)` → previous value - `useCycleList(list)` → cycle through items ## Storage - `useStorage(key, defaultValue, storage?)` → persistent Ref - `useLocalStorage(key, defaultValue)` → localStorage-backed Ref - `useSessionStorage(key, defaultValue)` → sessionStorage-backed Ref ## Time & Date - `useNow(options?)` → `Ref<Date>` (auto-updating) - `useDateFormat(date, format)` → `Ref<string>` - `useTimeAgo(date)` → relative time string - `useTimestamp(options?)` → `Ref<number>` - `useInterval(fn, ms)` → interval control - `useIntervalFn(fn, ms)` → interval with pause/resume - `useTimeout(ms)` → timeout control - `useTimeoutFn(fn, ms)` → delayed execution ## DOM & Browser - `useWindowSize()` → `{ width, height }` - `useWindowScroll()` → `{ x, y }` - `useWindowFocus()` → `Ref<boolean>` - `useDocumentVisibility()` → `Ref<string>` - `useFullscreen(el?)` → `{ isFullscreen, enter, exit, toggle }` - `useTitle(title)` → document title binding - `useFavicon(url)` → favicon binding - `useCssVar(prop, el?)` → CSS variable binding - `useActiveElement()` → currently focused element - `useTextSelection()` → selected text - `useTextDirection()` → `Ref<'ltr' | 'rtl'>` - `useNavigatorLanguage()` → browser language ## Mouse & Touch - `useMouse()` → `{ x, y, sourceType }` - `useMouseInElement(el)` → mouse position relative to element - `useMousePressed()` → `{ pressed, sourceType }` - `usePointer()` → pointer events - `useSwipe(el)` → swipe detection - `usePointerSwipe(el)` → pointer swipe - `useDraggable(el)` → make element draggable - `useDropZone(el)` → drop zone detection - `onLongPress(el, handler)` → long press detection - `onClickOutside(el, handler)` → click outside detection ## Sensors - `useGeolocation()` → `{ coords, locatedAt, error }` - `useDeviceMotion()` → acceleration & rotation - `useDeviceOrientation()` → alpha, beta, gamma - `useBattery()` → `{ charging, chargingTime, level }` - `useDevicePixelRatio()` → `Ref<number>` - `useScreenSafeArea()` → safe area insets ## Observers - `useIntersectionObserver(el, callback)` → visibility detection - `useResizeObserver(el, callback)` → size changes - `useMutationObserver(el, callback)` → DOM mutations - `useElementBounding(el)` → `{ top, left, width, height }` - `useElementVisibility(el)` → `Ref<boolean>` - `useElementHover(el)` → `Ref<boolean>` ## Async - `useAsyncState(fn, initial)` → `{ state, isReady, isLoading, error, execute }` - `useAsyncQueue(tasks)` → sequential async execution - `computedAsync(fn)` → async computed value - `computedEager(fn)` → immediately evaluated computed ## Network - `useFetch(url, options?)` → fetch wrapper with reactive state - `useWebSocket(url)` → WebSocket connection - `useEventSource(url)` → SSE connection - `useOnline()` → `Ref<boolean>` (network status) ## Input & Focus - `useFocus(el)` → `{ focused, focus, blur }` - `useFocusWithin(el)` → any child focused - `useKeyModifier(key)` → modifier key state - `usePermission(name)` → permission state - `useShare(options)` → Web Share API ## Utilities - `useDebounceFn(fn, ms)` → debounced function - `useThrottleFn(fn, ms)` → throttled function - `useDebouncedRef(ref, ms)` → debounced ref updates - `useThrottledRef(ref, ms)` → throttled ref updates - `watchDebounced(source, callback, ms)` → debounced watcher - `watchThrottled(source, callback, ms)` → throttled watcher - `watchOnce(source, callback)` → one-time watcher - `whenever(source, callback)` → watch for truthy - `until(source).toBe(value)` → wait for value - `syncRef(refA, refB)` → bidirectional sync ## Dark Mode - `useDark()` → `Ref<boolean>` - `usePreferredDark()` → system preference - `usePreferredColorScheme()` → color scheme preference ## Media - `useMediaQuery(query)` → `Ref<boolean>` - `usePreferredContrast()` → contrast preference - `usePreferredLanguages()` → language preferences - `usePreferredReducedMotion()` → reduce motion preference ## State Patterns - `createEventHook()` → typed event hook - `createGlobalState(fn)` → shared state across components - `createSharedComposable(fn)` → shared composable instance - `refDefault(ref, defaultValue)` → ref with default - `refAutoReset(value, ms)` → auto-resetting ref - `makeDestructurable(obj, arr)` → support both destructuring styles - `useIdle(ms)` → user idle detection - `usePageLeave()` → detect page leave - `useFps()` → frames per second - `useMounted()` → `Ref<boolean>` mount state - `tryOnMounted(fn)` → safe onMounted - `useObjectUrl(blob)` → object URL with auto-cleanup ## Script & Style Injection - `useScriptTag(src, onLoaded?)` → inject `<script>` - `useStyleTag(css)` → inject `<style>` ## Math - `useAbs`, `useAverage`, `useCeil`, `useClamp`, `useFloor`, `useMax`, `useMin`, `usePrecision`, `useRound`, `useSum`, `useTrunc` - `and`, `or`, `logicNot`, `logicOr` ## Gotchas - All composables are auto-imported in STX templates — no import needed - NEVER use vanilla JS (`var`, `document.*`, `window.*`) in STX `<script>` tags - Only use stx-compatible code: signals, composables, directives - Auto-imports defined in `storage/framework/browser-auto-imports.json` - Many composables require a browser environment (won't work server-side) - `useStorage` persists to localStorage by default