frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/src/composables/useScrollContainer.ts

@@ -0,0 +1,108 @@
+import {
+  computed,
+  onBeforeUnmount,
+  ref,
+  watch,
+  type ComputedRef,
+} from 'vue'
+
+/**
+ * Module-level registry connecting an app's shell to its scroll element across
+ * the component tree — the shell that owns the scroll region and a routed page
+ * that wants to read/drive it aren't ancestor and descendant.
+ *
+ * A stack (not a single ref) so that a desktop <-> mobile layout swap hands the
+ * active container over cleanly regardless of mount/unmount order, mirroring the
+ * PageHeader target registry (`components/PageHeader/target.ts`).
+ */
+const containers = ref<HTMLElement[]>([])
+
+/** The current scroll container — the most recently registered one. */
+export const activeScrollContainer: ComputedRef<HTMLElement | null> = computed(
+  () => containers.value[containers.value.length - 1] ?? null,
+)
+
+/** Register a shell's scroll element. Called by the shell, not by app code. */
+export function registerScrollContainer(el: HTMLElement) {
+  containers.value = [...containers.value, el]
+}
+
+/** Remove a previously registered scroll element. */
+export function unregisterScrollContainer(el: HTMLElement) {
+  containers.value = containers.value.filter((c) => c !== el)
+}
+
+/**
+ * Plain (non-hook) accessor for the active scroll container. Usable outside a
+ * component `setup()` — e.g. inside a vue-router `scrollBehavior` or navigation
+ * guard, where composables can't run. Returns `null` if no shell is mounted.
+ */
+export function getScrollContainer(): HTMLElement | null {
+  return activeScrollContainer.value
+}
+
+/** Scroll the active container. No-op when none is registered. */
+export function scrollTo(options: ScrollToOptions = {}) {
+  activeScrollContainer.value?.scrollTo(options)
+}
+
+/** Smooth-scroll the active container to the top. No-op when none is registered. */
+export function scrollToTop() {
+  activeScrollContainer.value?.scrollTo({ top: 0, behavior: 'smooth' })
+}
+
+export interface UseScrollContainerOptions {
+  /** Scroll offset (px) past which `isScrolled` flips to true. Default 200. */
+  threshold?: number
+}
+
+export interface UseScrollContainer {
+  /** The live scroll element — read `scrollTop`/`scrollHeight` or call `scrollBy` on it. */
+  el: ComputedRef<HTMLElement | null>
+  /** Scroll the active container. */
+  scrollTo: (options?: ScrollToOptions) => void
+  /** Smooth-scroll to the top. */
+  scrollToTop: () => void
+  /** Reactive: is the container scrolled past `threshold`. */
+  isScrolled: ComputedRef<boolean>
+}
+
+/**
+ * Reactive access to the app shell's scroll container.
+ *
+ * `isScrolled` tracks the *active* container and re-binds automatically across a
+ * layout swap, so it stays correct when desktop and mobile shells hand over.
+ */
+export function useScrollContainer(
+  options: UseScrollContainerOptions = {},
+): UseScrollContainer {
+  const { threshold = 200 } = options
+  const scrollTop = ref(0)
+
+  const onScroll = () => {
+    scrollTop.value = activeScrollContainer.value?.scrollTop ?? 0
+  }
+
+  // Follow the active container as it changes (layout swap): detach from the
+  // previous element, attach to the new one, and re-read immediately.
+  watch(
+    activeScrollContainer,
+    (el, prev) => {
+      prev?.removeEventListener('scroll', onScroll)
+      el?.addEventListener('scroll', onScroll, { passive: true })
+      onScroll()
+    },
+    { immediate: true },
+  )
+
+  onBeforeUnmount(() => {
+    activeScrollContainer.value?.removeEventListener('scroll', onScroll)
+  })
+
+  return {
+    el: activeScrollContainer,
+    scrollTo,
+    scrollToTop,
+    isScrolled: computed(() => scrollTop.value > threshold),
+  }
+}

package/src/composables/useShortcut.ts

@@ -190,6 +190,9 @@ function globalKeyupHandler(e: KeyboardEvent) {
 }
 
 function attachGlobalListener() {
+  // No-op during SSR — registration still works, listeners attach on the
+  // first client-side useShortcut call.
+  if (typeof document === 'undefined') return
   if (listenerAttached) return
   listenerAttached = true
   document.addEventListener('keydown', globalKeydownHandler)

package/src/data-fetching/docStore.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @vitest-environment node
+ */
+import { computed, watchSyncEffect } from 'vue'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { docStore } from './docStore'
+import { idbStore } from './idbStore'
+
+const DOCTYPE = 'User'
+const identity = <T>(d: T): T => d
+
+function idbKey(name: string) {
+  return `doc:${DOCTYPE}/${name}`
+}
+
+/**
+ * Mirror useDoc's `doc` computed: it calls getDoc and dereferences the returned
+ * ref *without* optional chaining, so a getDoc that returns undefined throws.
+ * A synchronous watcher reproduces the in-browser render effect that re-runs
+ * this computed the instant setDoc assigns the ref — the trigger for the crash.
+ */
+function subscribeLikeUseDoc(name: string) {
+  const doc = computed(() => docStore.getDoc(DOCTYPE, name, identity).value)
+  const seen: unknown[] = []
+  const stop = watchSyncEffect(() => {
+    seen.push(doc.value)
+  })
+  return { doc, seen, stop }
+}
+
+describe('docStore', () => {
+  beforeEach(async () => {
+    await docStore.clearAll()
+  })
+  afterEach(async () => {
+    await docStore.clearAll()
+  })
+
+  it('first uncached load: setDoc does not crash a synchronously-tracked reader and keeps the IDB copy', async () => {
+    const name = 'user1'
+    const { doc, stop } = subscribeLikeUseDoc(name)
+    // Nothing cached yet.
+    expect(doc.value).toBe(null)
+
+    const record = { doctype: DOCTYPE, name, email: 'user1@example.com' }
+    // Regression: before the fix this rejects. Assigning docRef.value synchronously
+    // re-enters getDoc, which (lastFetched unset) saw the entry as stale, evicted
+    // the ref it had just created, and the reader dereferenced undefined.
+    await expect(docStore.setDoc({ ...record })).resolves.toBeUndefined()
+
+    expect(doc.value).toMatchObject(record)
+    // The IDB copy setDoc wrote must survive — no spurious stale-reload eviction.
+    expect(await idbStore.get(idbKey(name))).toMatchObject(record)
+    stop()
+  })
+
+  it('stale access: getDoc never returns undefined (no self-eviction under its caller)', async () => {
+    const name = 'user2'
+    const record = { doctype: DOCTYPE, name }
+    await docStore.setDoc({ ...record })
+
+    // Force the entry past the cache timeout, as a long-lived useDoc would be.
+    const key = `${DOCTYPE}/${name}`
+    ;(
+      docStore as unknown as { lastFetched: Map<string, number> }
+    ).lastFetched.set(key, Date.now() - 10 * 60 * 1000)
+
+    const ref = docStore.getDoc(DOCTYPE, name, identity, { staleOnError: true })
+    expect(ref).toBeDefined()
+    expect(() => ref.value).not.toThrow()
+    expect(ref.value).toMatchObject(record)
+    expect(await idbStore.get(idbKey(name))).toMatchObject(record)
+  })
+})

package/src/data-fetching/docStore.ts

@@ -38,11 +38,15 @@ class DocStore {
       if (!this.docs.has(key)) {
         this.docs.set(key, ref(null))
       }
+      // Mark fresh BEFORE assigning the ref. Assigning docRef.value synchronously
+      // re-runs any computed reading this doc (e.g. useDoc's `doc`), which calls
+      // getDoc again — if the entry still looked stale at that point it would kick
+      // off a needless reload that evicts the IDB copy we just wrote.
+      this.lastFetched.set(key, Date.now())
       const docRef = this.docs.get(key)
       if (docRef) {
         docRef.value = doc
       }
-      this.lastFetched.set(key, Date.now())
     } catch (error) {
       console.error('Failed to set doc in IDB:', error)
       throw error
@@ -52,9 +56,10 @@ class DocStore {
   getDoc(
     doctype: string,
     name: MaybeRefOrGetter<string>,
-    transform: (doc: Doc) => Doc,
+    transform?: (doc: Doc) => Doc,
+    options: { staleOnError?: boolean } = {},
   ): Ref<Doc | null> {
-    const nameStr = toValue(name)
+    const nameStr = toValue(name)?.trim()
     if (!doctype || !nameStr) {
       throw new Error('doctype and name are required')
     }
@@ -62,9 +67,9 @@ class DocStore {
 
     if (!this.docs.has(key)) {
       this.docs.set(key, ref(null))
-      this.loadDoc(key, true, transform)
+      this.loadDoc(key, true, transform, options)
     } else if (this.isStale(key)) {
-      this.loadDoc(key, false, transform)
+      this.loadDoc(key, false, transform, options)
     }
 
     return this.docs.get(key)!
@@ -73,11 +78,17 @@ class DocStore {
   private async loadDoc(
     key: DocKey,
     isFirstLoad: boolean,
-    transform: (doc: Doc) => Doc,
+    transform?: (doc: Doc) => Doc,
+    options: { staleOnError?: boolean } = {},
   ) {
     try {
       if (!isFirstLoad && this.isStale(key)) {
-        await this.cleanup(key)
+        this.lastFetched.delete(key)
+        if (!options.staleOnError) {
+          // Keep the IDB copy only when callers explicitly opt into stale
+          // read-only fallback, such as offline-capable routes.
+          await idbStore.delete(this.storePrefix + key)
+        }
       }
 
       const idbDoc = (await idbStore.get(this.storePrefix + key)) as Doc | null

package/src/data-fetching/useCall/types.ts

@@ -11,6 +11,7 @@ export interface UseCallOptions<
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
   params?: TParams | (() => TParams)
   cacheKey?: CacheKey
+  staleOnError?: boolean
   immediate?: boolean
   refetch?: boolean
   baseUrl?: string

package/src/data-fetching/useCall/useCall.test.ts

@@ -207,4 +207,47 @@ describe('useCall', () => {
     await waitUntilValueChanges(() => secondCall.data)
     expect(secondCall.data).toBe('pong')
   })
+
+  it('keeps cached data visible when a refetch fails', async () => {
+    const cacheKey = 'offline-ping'
+    const call = useCall({
+      url: url('/api/v2/method/ping'),
+      cacheKey,
+    })
+
+    await waitUntilValueChanges(() => call.data)
+    expect(call.data).toBe('pong')
+
+    const offlineCall = useCall({
+      url: url('/api/v2/method/network-error'),
+      cacheKey,
+      staleOnError: true,
+    })
+
+    await waitUntilValueChanges(() => offlineCall.data)
+    await waitUntilValueChanges(() => offlineCall.loading)
+
+    expect(offlineCall.error).toBeTruthy()
+    expect(offlineCall.data).toBe('pong')
+  })
+
+  it('does not parse empty network failures as Frappe errors', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const networkCall = useCall({
+      url: url('/api/v2/method/network-error'),
+      immediate: false,
+    })
+
+    networkCall.fetch()
+    await networkCall.promise.catch(() => {})
+    await waitUntilValueChanges(() => networkCall.loading)
+
+    expect(networkCall.error).toBeTruthy()
+    expect(logSpy).not.toHaveBeenCalledWith(
+      'Error parsing error response:',
+      expect.anything(),
+    )
+
+    logSpy.mockRestore()
+  })
 })

package/src/data-fetching/useCall/useCall.ts

@@ -1,6 +1,6 @@
 import { computed, reactive, readonly, ref, unref } from 'vue'
 import { AfterFetchContext, UseFetchOptions } from '@vueuse/core'
-import { useFrappeFetch } from '../useFrappeFetch'
+import { FrappeResponseError, useFrappeFetch } from '../useFrappeFetch'
 import { unrefObject, makeGetParams, normalizeCacheKey } from '../utils'
 import { idbStore } from '../idbStore'
 import { BasicParams, UseCallOptions } from './types'
@@ -17,6 +17,7 @@ export function useCall<TResponse, TParams extends BasicParams = undefined>(
     baseUrl = '',
     initialData,
     cacheKey,
+    staleOnError = false,
     transform,
     beforeSubmit,
     onSuccess,
@@ -177,7 +178,15 @@ export function useCall<TResponse, TParams extends BasicParams = undefined>(
   let cachedResponse = ref<TResponse | null>(null)
 
   const _data = computed(() => {
-    if (normalizedCacheKey && (out.loading || !out.isFinished)) {
+    if (
+      normalizedCacheKey &&
+      cachedResponse.value != null &&
+      canUseCachedFallback(error.value, staleOnError) &&
+      (out.loading ||
+        !out.isFinished ||
+        data.value?.data == null ||
+        error.value)
+    ) {
       let cachedData = cachedResponse.value as TResponse
       if (transform) {
         let returnValue = transform(cachedData)
@@ -219,7 +228,11 @@ export function useCall<TResponse, TParams extends BasicParams = undefined>(
 
   return out as Omit<typeof out, 'submit'> & {
     submit: TParams extends undefined
-      ? (params?: never) => Promise<void>
-      : (params: TParams) => Promise<void>
+      ? (params?: never) => Promise<TResponse | null>
+      : (params?: TParams) => Promise<TResponse | null>
   }
 }
+
+function canUseCachedFallback(error: unknown, staleOnError: boolean) {
+  return !error || (staleOnError && !(error instanceof FrappeResponseError))
+}

package/src/data-fetching/useDoc/useDoc.test.ts

@@ -4,6 +4,7 @@
 import { ref } from 'vue'
 import { baseUrl, waitUntilValueChanges } from '../../mocks/utils'
 import { useCall, useDoc } from '../index'
+import { docStore } from '../docStore'
 
 describe('useDoc', () => {
   it('it returns expected object', async () => {
@@ -104,7 +105,7 @@ describe('useDoc', () => {
     await waitUntilValueChanges(() => user.doc)
 
     // Initial email value
-    expect(user.doc.email).toBe('user1@example.com')
+    expect(user.doc!.email).toBe('user1@example.com')
 
     // Update email
     const newEmail = 'updated@example.com'
@@ -114,6 +115,64 @@ describe('useDoc', () => {
     await waitUntilValueChanges(() => user.doc)
 
     // Verify that the doc was updated
-    expect(user.doc.email).toBe(newEmail)
+    expect(user.doc!.email).toBe(newEmail)
+  })
+
+  it('does not bind or fetch while the name is empty', async () => {
+    interface User {
+      name: string
+      email: string
+    }
+
+    const user = useDoc<User>({
+      baseUrl,
+      doctype: 'User',
+      name: '',
+    })
+
+    // No name → nothing to bind and no request should fire.
+    expect(user.doc).toBe(null)
+    expect(user.loading).toBe(false)
+  })
+
+  it('binds to the doc once a late-resolving name is set', async () => {
+    interface User {
+      name: string
+      email: string
+      first_name: string
+      last_name: string
+    }
+
+    // Name is empty at setup (e.g. bound to a doc that is still loading).
+    const name = ref('')
+    const user = useDoc<User>({
+      baseUrl,
+      doctype: 'User',
+      name,
+    })
+
+    // Nothing fetched or bound yet.
+    expect(user.doc).toBe(null)
+    expect(user.loading).toBe(false)
+
+    // Name resolves after setup — the doc ref should re-point to the real slot.
+    name.value = 'user1'
+
+    await waitUntilValueChanges(() => user.loading, true)
+    await waitUntilValueChanges(() => user.loading, false)
+
+    expect(user.doc).toStrictEqual({
+      doctype: 'User',
+      name: 'user1',
+      email: 'user1@example.com',
+      first_name: 'User',
+      last_name: '1',
+    })
+  })
+
+  it('throws when getDoc is called with a whitespace-only name', () => {
+    expect(() => docStore.getDoc('User', '   ', (d) => d)).toThrow(
+      'doctype and name are required',
+    )
   })
 })

package/src/data-fetching/useDoc/useDoc.ts

@@ -24,8 +24,10 @@ type TransformMethods<T> = {
       : never
 }
 
-interface DocMethodOption<T = any>
-  extends Omit<UseCallOptions<T>, 'url' | 'baseUrl'> {
+interface DocMethodOption<T = any> extends Omit<
+  UseCallOptions<T>,
+  'url' | 'baseUrl'
+> {
   name: string
 }
 
@@ -36,6 +38,7 @@ interface UseDocOptions<TDoc> {
   url?: string
   methods?: Record<string, string | DocMethodOption>
   immediate?: boolean
+  staleOnError?: boolean
   transform?: (doc: TDoc & { doctype: string }) => TDoc & { doctype: string }
 }
 
@@ -49,6 +52,7 @@ export function useDoc<TDoc extends { name: string }, TMethods = {}>(
     url: customUrl = '',
     methods = {},
     immediate = true,
+    staleOnError = false,
     transform,
   } = options
 
@@ -72,7 +76,10 @@ export function useDoc<TDoc extends { name: string }, TMethods = {}>(
   }
 
   const fetchOptions: UseFetchOptions = {
-    immediate,
+    // Don't fire the initial GET while the name is still unresolved (it would
+    // hit the malformed `/api/v2/document/<doctype>/` URL). refetch:true makes
+    // the request fire automatically once the name resolves and the URL changes.
+    immediate: immediate && Boolean(toValue(name)?.trim()),
     refetch: true,
     afterFetch(ctx: AfterFetchContext<{ data: TDoc }>) {
       if (ctx.data) {
@@ -130,11 +137,10 @@ export function useDoc<TDoc extends { name: string }, TMethods = {}>(
     immediate: false,
     refetch: false,
     onSuccess(data) {
-      let docWithType = { ...data, doctype }
-      if (transform) {
-        docWithType = transform(docWithType)
-      }
-      docStore.setDoc(docWithType)
+      // Store the untransformed doc; the `doc` computed applies `transform` on
+      // read. Transforming here too would run it twice (a bug for any
+      // non-idempotent transform). Mirrors afterFetch.
+      docStore.setDoc({ ...data, doctype })
       listStore.updateRow(doctype, data)
     },
   })
@@ -152,14 +158,28 @@ export function useDoc<TDoc extends { name: string }, TMethods = {}>(
     },
   })
 
-  let doc = docStore.getDoc(doctype, name, transform) as Ref<TDoc | null>
-  if (doc.value && transform) {
-    try {
-      doc.value = transform(doc.value)
-    } catch (e) {
-      docStore.removeDoc(doctype, toValue(name))
+  // Bind reactively to the document keyed by the *current* name. Resolving the
+  // name once at setup would statically bind to whatever it was then — if the
+  // name resolves after setup (e.g. while the GET is still in flight) the ref
+  // would never re-point to the real cache slot. A computed re-evaluates when
+  // the name resolves and when the store ref is populated.
+  const doc = computed<TDoc | null>(() => {
+    const nameStr = toValue(name)?.trim()
+    if (!nameStr) return null
+    const storeRef = docStore.getDoc(doctype, nameStr, transform as any, {
+      staleOnError,
+    }) as Ref<TDoc | null>
+    let value = storeRef.value
+    if (value && transform) {
+      try {
+        value = transform(value as TDoc & { doctype: string })
+      } catch (e) {
+        docStore.removeDoc(doctype, nameStr)
+        return null
+      }
     }
-  }
+    return value
+  })
   let out = reactive({
     doc,
     error,

package/src/data-fetching/useDoctype/useDoctype.ts

@@ -7,7 +7,7 @@ interface UseDoctypeOptions {
   baseUrl?: string
 }
 
-export function useDoctype<T>(
+export function useDoctype<T extends Record<string, any>>(
   doctype: string,
   options: UseDoctypeOptions = {},
 ) {
@@ -37,7 +37,8 @@ function useInsert<T>(doctype: string, options: UseDoctypeOptions = {}) {
 
   return {
     ...out,
-    submit: (params: Partial<T>) => out.submit(params).then(() => out.data),
+    submit: (params: Partial<T>) =>
+      out.submit(params as any).then(() => out.data),
   }
 }
 
@@ -109,7 +110,7 @@ function useRunDocMethod(doctype: string, options: UseDoctypeOptions = {}) {
           validateError.value = null
         }
       }
-      return runDocMethod.submit(params)
+      return runDocMethod.submit(params as any)
     },
     isLoading: (name: string, method: string) => {
       return (
@@ -158,7 +159,7 @@ function useRunMethod(doctype: string, options: UseDoctypeOptions = {}) {
           validateError.value = null
         }
       }
-      return runMethod.submit(params)
+      return runMethod.submit(params as any)
     },
     isLoading: (method: string) => {
       return (
@@ -190,7 +191,7 @@ function useSetValue<T>(doctype: string, options: UseDoctypeOptions = {}) {
     ...setValue,
     submit: ({ name, ...values }: SetValueParams) => {
       url.value = `/api/v2/document/${doctype}/${name}`
-      return setValue.submit({ name, ...values })
+      return setValue.submit({ name, ...values } as any)
     },
   }
 }

package/src/data-fetching/useFrappeFetch.ts

@@ -25,8 +25,13 @@ export class FrappeResponseError extends Error {
     this.indicator = options.indicator
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, FrappeResponseError)
+    const captureStackTrace = (
+      Error as ErrorConstructor & {
+        captureStackTrace?: (target: object, constructor?: Function) => void
+      }
+    ).captureStackTrace
+    if (captureStackTrace) {
+      captureStackTrace(this, FrappeResponseError)
     }
   }
 }
@@ -77,9 +82,17 @@ export const useFrappeFetch = createFetch({
         indicator: string
       }
       try {
+        if (!ctx.data) {
+          return ctx
+        }
+
         let errorResponse = JSON.parse(ctx.data)
-        let errors: Array<FrappeError> = errorResponse.errors
-        let error = errors[0] // assuming only one error for now
+        let errors: Array<FrappeError> | undefined = errorResponse.errors
+        let error = errors?.[0] // assuming only one error for now
+        if (!error) {
+          return ctx
+        }
+
         let errorDescription = error.message
           ? `: ${error.message}`
           : error.exception

package/src/data-fetching/useList/types.ts

@@ -34,6 +34,7 @@ export interface UseListOptions<T> {
   parent?: string
   debug?: boolean
   cacheKey?: CacheKey
+  staleOnError?: boolean
   initialData?: T[]
   immediate?: boolean
   refetch?: boolean

package/src/data-fetching/useList/useList.test.ts

@@ -212,4 +212,44 @@ describe('useList', () => {
       { name: 'User2', email: 'user2@example.com' },
     ])
   })
+
+  it('keeps cached data visible when a refetch fails', async () => {
+    interface User {
+      name: string
+      email: string
+    }
+
+    const cacheKey = 'offline-users'
+    const cachedUsers = useList<User>({
+      baseUrl,
+      doctype: 'User',
+      fields: ['name', 'email'],
+      cacheKey,
+      limit: 2,
+    })
+
+    await waitUntilValueChanges(() => cachedUsers.data)
+    expect(cachedUsers.data).toStrictEqual([
+      { name: 'User1', email: 'user1@example.com' },
+      { name: 'User2', email: 'user2@example.com' },
+    ])
+
+    const offlineUsers = useList<User>({
+      baseUrl,
+      doctype: 'InvalidDoctype',
+      fields: ['name', 'email'],
+      cacheKey,
+      staleOnError: true,
+      limit: 2,
+    })
+
+    await waitUntilValueChanges(() => offlineUsers.data)
+    await waitUntilValueChanges(() => offlineUsers.loading)
+
+    expect(offlineUsers.error).toBeTruthy()
+    expect(offlineUsers.data).toStrictEqual([
+      { name: 'User1', email: 'user1@example.com' },
+      { name: 'User2', email: 'user2@example.com' },
+    ])
+  })
 })