@talelk/newui-data 0.0.0-stage → 1.0.0

package/src/resource/useDoctype.ts

@@ -0,0 +1,128 @@
+import { type Accessor, createSignal } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type Resource, type ResourceFetcher } from './resource'
+
+/** A single doctype-level write action. */
+export interface DoctypeAction<TResult = unknown, TInput = unknown> {
+  data: Accessor<TResult | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  submit: (input: TInput) => Promise<TResult | null>
+  reset: () => void
+}
+
+/** Options for {@link useDoctype}. */
+export interface UseDoctypeOptions {
+  fetcher?: ResourceFetcher
+}
+
+/** Params for a document method. */
+export interface RunDocMethodInput {
+  name: string
+  method: string
+  params?: Record<string, unknown>
+}
+
+/** Params for a doctype-level method. */
+export interface RunMethodInput {
+  method: string
+  params?: Record<string, unknown>
+}
+
+/** The write actions {@link useDoctype} returns. */
+export interface UseDoctypeReturn<TDoc = Record<string, unknown>> {
+  insert: DoctypeAction<TDoc, Partial<TDoc>>
+  delete: DoctypeAction<unknown, string>
+  setValue: DoctypeAction<TDoc, Record<string, unknown> & { name: string }>
+  runDocMethod: DoctypeAction<unknown, RunDocMethodInput>
+  runMethod: DoctypeAction<unknown, RunMethodInput>
+}
+
+const INSERT_URL = 'frappe.client.insert'
+const SET_VALUE_URL = 'frappe.client.set_value'
+const DELETE_URL = 'frappe.client.delete'
+const RUN_DOC_METHOD_URL = 'run_doc_method'
+
+/**
+ * The signal-based replacement for frappe-ui's `useDoctype`: the doctype-level
+ * write actions (`insert`, `delete`, `setValue`, `runDocMethod`, `runMethod`),
+ * each an inert resource that fires on `submit`.
+ */
+export function useDoctype<TDoc = Record<string, unknown>>(
+  doctype: string,
+  options: UseDoctypeOptions = {},
+): UseDoctypeReturn<TDoc> {
+  const { fetcher } = options
+
+  const insertResource = createResource<TDoc, Partial<TDoc>>({
+    url: INSERT_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doc: { doctype, ...(input as Partial<TDoc>) } }),
+    fetcher,
+  })
+
+  const deleteResource = createResource<unknown, string>({
+    url: DELETE_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doctype, name: input }),
+    fetcher,
+  })
+
+  const setValueResource = createResource<
+    TDoc,
+    Record<string, unknown> & { name: string }
+  >({
+    url: SET_VALUE_URL,
+    method: 'POST',
+    makeParams: ({ name, ...values }) => ({ doctype, name, fieldname: values }),
+    fetcher,
+  })
+
+  const runDocMethodResource = createResource<unknown, RunDocMethodInput>({
+    url: RUN_DOC_METHOD_URL,
+    method: 'POST',
+    makeParams: ({ name, method, params }) => ({
+      dt: doctype,
+      dn: name,
+      method,
+      args: params ?? {},
+    }),
+    fetcher,
+  })
+
+  // `runMethod` POSTs to the method name itself, which is only known per call.
+  // `makeParams` runs before the URL is resolved (see `createResource`), so the
+  // signal it writes is already visible when the URL is read.
+  const [methodUrl, setMethodUrl] = createSignal('')
+  const runMethodResource = createResource<unknown, RunMethodInput>({
+    url: () => methodUrl(),
+    method: 'POST',
+    makeParams: ({ method, params }) => {
+      setMethodUrl(() => method)
+      return params ?? {}
+    },
+    fetcher,
+  })
+
+  function toAction<TResult, TInput>(
+    resource: Resource<TResult, TInput>,
+  ): DoctypeAction<TResult, TInput> {
+    return {
+      data: resource.data,
+      loading: resource.loading,
+      error: resource.error,
+      submit: (input: TInput) => resource.submit(input),
+      reset: resource.reset,
+    }
+  }
+
+  return {
+    insert: toAction<TDoc, Partial<TDoc>>(insertResource),
+    delete: toAction<unknown, string>(deleteResource),
+    setValue: toAction<TDoc, Record<string, unknown> & { name: string }>(
+      setValueResource,
+    ),
+    runDocMethod: toAction<unknown, RunDocMethodInput>(runDocMethodResource),
+    runMethod: toAction<unknown, RunMethodInput>(runMethodResource),
+  }
+}

package/src/resource/useList.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useList } from './useList'
+
+function mockResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('useList', () => {
+  it('delegates to the list resource', async () => {
+    const mock = vi.fn(async () => mockResponse({ message: [{ name: 'T-1' }] }))
+    vi.stubGlobal('fetch', mock)
+
+    const list = useList<{ name: string }>({ doctype: 'Task' })
+    const rows = await list.reload()
+
+    expect(rows).toEqual([{ name: 'T-1' }])
+    expect(mock).toHaveBeenCalledWith(
+      '/api/method/frappe.client.get_list',
+      expect.objectContaining({ method: 'POST' }),
+    )
+  })
+})

package/src/resource/useList.ts

@@ -0,0 +1,22 @@
+import {
+  createListResource,
+  type ListResource,
+  type ListResourceOptions,
+} from './list'
+
+/** Options for {@link useList}. */
+export type UseListOptions<TRow = Record<string, unknown>> =
+  ListResourceOptions<TRow>
+
+/** The signal-based surface {@link useList} returns. */
+export type UseListReturn<TRow = Record<string, unknown>> = ListResource<TRow>
+
+/**
+ * A thin composable over {@link createListResource}: a paginated, filterable
+ * list read through signals.
+ */
+export function useList<TRow = Record<string, unknown>>(
+  options: ListResourceOptions<TRow>,
+): ListResource<TRow> {
+  return createListResource(options)
+}

package/src/resource/useNewDoc.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useNewDoc } from './useNewDoc'
+
+function mockResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+interface FetchCall {
+  mock: { calls: Array<[string, RequestInit]> }
+}
+
+function stubFetch(...responses: Response[]): FetchCall {
+  const mock = vi.fn()
+  for (const response of responses) mock.mockResolvedValueOnce(response)
+  vi.stubGlobal('fetch', mock)
+  return mock as unknown as FetchCall
+}
+
+function urlAt(mock: FetchCall, index = 0): string {
+  return mock.mock.calls[index]?.[0] ?? ''
+}
+
+function bodyAt(mock: FetchCall, index = 0): Record<string, unknown> {
+  const call = mock.mock.calls[index]
+  return JSON.parse(String(call?.[1]?.body)) as Record<string, unknown>
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('useNewDoc', () => {
+  it('builds a doc and inserts it', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-9' } }))
+    const newDoc = useNewDoc<{ name: string; subject: string }>('Task', {
+      subject: 'Hi',
+    })
+
+    expect(newDoc.doc()).toEqual({ subject: 'Hi' })
+    newDoc.setDoc((doc) => ({ ...doc, subject: 'Bye' }))
+
+    const created = await newDoc.submit()
+
+    expect(created).toEqual({ name: 'T-9' })
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.insert')
+    expect(bodyAt(fetchMock)).toEqual({
+      doc: { doctype: 'Task', subject: 'Bye' },
+    })
+  })
+
+  it('reset clears the draft', async () => {
+    stubFetch(mockResponse({ message: { name: 'T-9' } }))
+    const newDoc = useNewDoc<{ subject: string }>('Task', { subject: 'Hi' })
+
+    newDoc.setDoc({ subject: 'Bye' })
+    newDoc.reset()
+
+    expect(newDoc.doc()).toEqual({ subject: 'Hi' })
+    expect(newDoc.data()).toBe(null)
+  })
+})

package/src/resource/useNewDoc.ts

@@ -0,0 +1,78 @@
+import { type Accessor, createSignal } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type ResourceFetcher } from './resource'
+
+/** Options for {@link useNewDoc}. */
+export interface UseNewDocOptions {
+  onSuccess?: (doc: Record<string, unknown>) => void
+  onError?: (error: RequestError) => void
+  fetcher?: ResourceFetcher
+}
+
+/** The signal-based surface {@link useNewDoc} returns. */
+export interface UseNewDocReturn<TDoc = Record<string, unknown>> {
+  /** The document being built, edited through {@link UseNewDocReturn.setDoc}. */
+  doc: Accessor<Partial<TDoc>>
+  setDoc: (
+    values: Partial<TDoc> | ((current: Partial<TDoc>) => Partial<TDoc>),
+  ) => void
+  /** The created document, once `submit` resolves. */
+  data: Accessor<TDoc | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  /** Insert the document (`frappe.client.insert`). */
+  submit: () => Promise<TDoc | null>
+  reset: () => void
+}
+
+const INSERT_URL = 'frappe.client.insert'
+
+/**
+ * The signal-based replacement for frappe-ui's `useNewDoc`: build a document
+ * locally, then insert it.
+ */
+export function useNewDoc<TDoc extends object = Record<string, unknown>>(
+  doctype: string,
+  initialValues: Partial<TDoc> = {},
+  options: UseNewDocOptions = {},
+): UseNewDocReturn<TDoc> {
+  const [doc, setDocSignal] = createSignal<Partial<TDoc>>({ ...initialValues })
+
+  const resource = createResource<TDoc, Record<string, unknown>>({
+    url: INSERT_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doc: { doctype, ...input } }),
+    fetcher: options.fetcher,
+    onSuccess: (data) => options.onSuccess?.(data as Record<string, unknown>),
+    onError: options.onError,
+  })
+
+  function setDoc(
+    next: Partial<TDoc> | ((current: Partial<TDoc>) => Partial<TDoc>),
+  ): void {
+    if (typeof next === 'function') {
+      setDocSignal((current) => next(current))
+      return
+    }
+    setDocSignal(() => next)
+  }
+
+  function submit(): Promise<TDoc | null> {
+    return resource.submit(doc() as Record<string, unknown>)
+  }
+
+  function reset(): void {
+    setDocSignal(() => ({ ...initialValues }))
+    resource.reset()
+  }
+
+  return {
+    doc,
+    setDoc,
+    data: resource.data,
+    loading: resource.loading,
+    error: resource.error,
+    submit,
+    reset,
+  }
+}

package/src/select.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+import { first, optionsOf } from './select'
+
+describe('select', () => {
+  it('mirrors values into options and unwraps with a fallback', () => {
+    expect(optionsOf(['Name', 'Size'])).toEqual([
+      { label: 'Name', value: 'Name' },
+      { label: 'Size', value: 'Size' },
+    ])
+    expect(first(['Size'], 'Name')).toBe('Size')
+    expect(first([], 'Name')).toBe('Name')
+  })
+})

package/src/select.ts

@@ -0,0 +1,19 @@
+/**
+ * Select plumbing: a string list to options, and the chosen value back.
+ *
+ * Every page turned a list into `{ label, value }` inline and unwrapped the
+ * single-value array the same way. Two spellings, once.
+ */
+
+export interface SelectOption {
+  label: string
+  value: string
+}
+
+/** `['Name', 'Size']` → `[{ label: 'Name', value: 'Name' }, …]`. */
+export const optionsOf = (values: readonly string[]): SelectOption[] =>
+  values.map((value) => ({ label: value, value }))
+
+/** The chosen value, or `fallback` when the selection is empty. */
+export const first = (value: string[], fallback: string): string =>
+  value[0] ?? fallback

package/src/undo.test.ts

@@ -0,0 +1,24 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it } from 'vitest'
+import { createUndo } from './undo'
+
+describe('undo', () => {
+  it('captures, restores once, then reports nothing left', () => {
+    createRoot((dispose) => {
+      const undo = createUndo<number[]>()
+      expect(undo.snapshot()).toBeUndefined()
+      expect(undo.undo(() => {})).toBe(false)
+
+      undo.capture([1, 2])
+      const restored: number[][] = []
+      expect(undo.undo((value) => restored.push(value))).toBe(true)
+      expect(restored).toEqual([[1, 2]])
+      expect(undo.snapshot()).toBeUndefined()
+
+      undo.capture([3])
+      undo.clear()
+      expect(undo.snapshot()).toBeUndefined()
+      dispose()
+    })
+  })
+})

package/src/undo.ts

@@ -0,0 +1,37 @@
+import { type Accessor, createSignal } from 'solid-js'
+
+/**
+ * One-step undo.
+ *
+ * A snapshot signal, captured before a mutation, restored once. The page keeps
+ * owning its data and its notice copy; this owns the signal.
+ */
+export interface Undo<T> {
+  /** The captured value, or `undefined` when there is nothing to undo. */
+  snapshot: Accessor<T | undefined>
+  /** Remember `value` as the state an undo returns to. */
+  capture: (value: T) => void
+  /**
+   * Hand the snapshot back to `restore` and clear it. Returns whether a
+   * snapshot existed, so the caller can word its notice either way.
+   */
+  undo: (restore: (value: T) => void) => boolean
+  /** Drop the snapshot without restoring. */
+  clear: () => void
+}
+
+export function createUndo<T>(): Undo<T> {
+  const [snapshot, setSnapshot] = createSignal<T | undefined>(undefined)
+  return {
+    snapshot,
+    capture: (value) => setSnapshot(() => value),
+    undo: (restore) => {
+      const previous = snapshot()
+      if (previous === undefined) return false
+      restore(previous)
+      setSnapshot(undefined)
+      return true
+    },
+    clear: () => setSnapshot(undefined),
+  }
+}