@stacksjs/stx 0.2.176 → 0.2.177

package/stx.d.ts

@@ -199,11 +199,42 @@ declare function useSearchParams(): {
 // Data fetching
 // ============================================================================
 
-interface StxQueryResult<T> {
+/** How one run of a request should behave. */
+interface StxRefetchOptions {
+  /**
+   * Refresh without touching `loading` or clearing the current error.
+   *
+   * A poll refreshes data that is already on screen, so driving the first-load
+   * state from it puts a spinner over a populated view on every tick — the
+   * reason a polling view could not use these primitives at all (#1929). Bind
+   * `isFetching` for a subtle in-flight indicator instead.
+   */
+  background?: boolean
+}
+
+interface StxFetchResult<T> {
   data: StxSignal<T | null>
+  /** True while a first-load request is in flight. A background one leaves it alone. */
   loading: StxSignal<boolean>
+  /** True while ANY request is in flight, background ones included. */
+  isFetching: StxSignal<boolean>
   error: StxSignal<Error | null>
-  refetch: () => Promise<void>
+  refetch: (_options?: StxRefetchOptions) => Promise<void>
+}
+
+/*
+ * `useQuery` returns more than `useFetch` does, and declaring one shape for
+ * both hid it: `isStale` and `invalidate` existed at runtime and were invisible
+ * to the type, so reading either was an error on a value that was really there
+ * (#1929). Extending rather than widening the shared interface, because the
+ * inverse mistake is worse — declaring `invalidate` on `useFetch` would
+ * type-check a call to something that is undefined at runtime.
+ */
+interface StxQueryResult<T> extends StxFetchResult<T> {
+  /** True when cached data is on screen while a revalidation runs. */
+  isStale: StxSignal<boolean>
+  /** Drop this key from the cache and refetch. */
+  invalidate: (_options?: StxRefetchOptions) => Promise<void>
 }
 
 interface StxMutationResult<T> {
@@ -213,7 +244,7 @@ interface StxMutationResult<T> {
   mutate: (body?: unknown) => Promise<T>
 }
 
-declare function useFetch<T = any>(_url: string, _options?: any): StxQueryResult<T>
+declare function useFetch<T = any>(_url: string, _options?: any): StxFetchResult<T>
 declare function useQuery<T = any>(_url: string, _options?: any): StxQueryResult<T>
 declare function useMutation<T = any>(_url: string, _options?: any): StxMutationResult<T>
 
@@ -271,17 +302,45 @@ declare function useOptimistic<T = any, A = any>(
 // DOM utilities
 // ============================================================================
 
+/**
+ * Options the runtime reads, including the target it binds to.
+ *
+ * The target travels HERE rather than in a leading parameter, because that is
+ * what the implementation does: `var target = (options && options.target) || window`.
+ */
+interface StxEventListenerOptions {
+  /** Element, selector, or document/window. Defaults to `window`. */
+  target?: Window | Document | HTMLElement | string | null
+  capture?: boolean
+  passive?: boolean
+  once?: boolean
+}
+
+/*
+ * Event first, then handler, then options (stacksjs/stx#1923).
+ *
+ * This was declared target-first while the runtime has always been
+ * event-first, so the two disagreed in the worst possible direction: `_target`
+ * accepted `string`, so the CORRECT call got as far as reading 'keydown' as a
+ * selector before failing on the handler, and an author who trusted the type
+ * and added a target wrote `useEventListener(window, 'keydown', fn)` — which
+ * binds an event named "window" with the string 'keydown' as its handler, and
+ * silently attaches nothing.
+ *
+ * `browser-composables.ts` had it right all along; the package shipped two
+ * declarations of one name with different arities and the registry got the
+ * wrong one. Same shape as the `reactive` split: one name, two conventions, and
+ * no way for the call site to tell which it has.
+ */
 declare function useEventListener<K extends keyof WindowEventMap>(
-  _target: Window | Document | HTMLElement | string | null,
   _event: K,
   _handler: (event: WindowEventMap[K]) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useEventListener(
-  _target: Window | Document | HTMLElement | string | null,
   _event: string,
   _handler: (event: Event) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useScrollLock(
   _target?: HTMLElement | null | { current?: HTMLElement | null, value?: HTMLElement | null } | (() => HTMLElement | null | undefined),