@talelk/newui-data 0.0.0-stage → 1.0.0

package/src/form/form.test.tsx

@@ -0,0 +1,102 @@
+import { render, screen, waitFor } from '@solidjs/testing-library'
+import userEvent from '@testing-library/user-event'
+import { untrack } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { createAppForm, Form, fieldError } from './form'
+
+function Harness(props: {
+  onSubmit: (value: { name: string }) => Promise<void>
+}): import('solid-js').JSX.Element {
+  const { form, submitting } = createAppForm({
+    defaultValues: { name: '' },
+    onSubmit: untrack(() => props.onSubmit),
+  })
+  return (
+    <Form form={form} class="flex flex-col gap-2">
+      <form.Field
+        name="name"
+        validators={{
+          onChange: ({ value }) =>
+            value.length < 3 ? 'Use at least 3 characters.' : undefined,
+          onSubmit: ({ value }) =>
+            value.length < 3 ? 'Use at least 3 characters.' : undefined,
+        }}
+      >
+        {(field) => (
+          <>
+            <input
+              aria-label="Name"
+              value={field().state.value}
+              onInput={(event) =>
+                field().handleChange(event.currentTarget.value)
+              }
+            />
+            <p role="alert">{fieldError(field())}</p>
+            <button type="submit" disabled={submitting()}>
+              Save
+            </button>
+          </>
+        )}
+      </form.Field>
+    </Form>
+  )
+}
+
+describe('createAppForm', () => {
+  it('submits a valid value and blocks an invalid one', async () => {
+    const onSubmit = vi.fn(async (_value: { name: string }) => {})
+    render(() => <Harness onSubmit={onSubmit} />)
+    const field = screen.getByRole('textbox', { name: 'Name' })
+
+    await userEvent.type(field, 'ab')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSubmit).not.toHaveBeenCalled()
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain(
+        'at least 3 characters',
+      ),
+    )
+
+    await userEvent.type(field, 'c')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    expect(onSubmit.mock.calls[0]?.[0]).toEqual({ name: 'abc' })
+  })
+
+  it('reports submitting while the handler is pending, and disables the button', async () => {
+    let finish!: () => void
+    const onSubmit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finish = resolve
+        }),
+    )
+    render(() => <Harness onSubmit={onSubmit} />)
+    await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'abc')
+    const button = screen.getByRole('button', { name: 'Save' })
+    await userEvent.click(button)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    await waitFor(() => expect(button).toBeDisabled())
+
+    finish()
+    await waitFor(() => expect(button).not.toBeDisabled())
+  })
+})
+
+describe('fieldError', () => {
+  it('turns TanStack’s error list into the single string a field takes', () => {
+    expect(fieldError({ state: { meta: { errors: [] } } })).toBeUndefined()
+    expect(fieldError({ state: { meta: { errors: ['Required.'] } } })).toBe(
+      'Required.',
+    )
+    expect(
+      fieldError({
+        state: { meta: { errors: [{ message: 'Required.' }, 'Too short.'] } },
+      }),
+    ).toBe('Required. Too short.')
+    // The same message from `onChange` and `onSubmit` is one sentence, not two.
+    expect(
+      fieldError({ state: { meta: { errors: ['Required.', 'Required.'] } } }),
+    ).toBe('Required.')
+  })
+})

package/src/form/form.tsx

@@ -0,0 +1,85 @@
+import { createForm } from '@tanstack/solid-form'
+import { type Accessor, type JSX, splitProps } from 'solid-js'
+
+/**
+ * The form surface: the kit's answer to "how does a page submit".
+ *
+ * TanStack Form stays the engine — validators, field state, reset. What this
+ * adds is the three things every page was writing by hand: a submit lifecycle
+ * the button can read, a `<form>` that never lets the browser's native
+ * validation paint first, and one place that turns a field's error list into the
+ * single `error` string the kit's `Field` contract takes.
+ */
+
+export interface AppFormOptions<T extends object> {
+  defaultValues: T
+  /**
+   * Runs on submit. While the returned promise is pending the form reports
+   * `submitting()`, which is what a submit button's `loading` reads.
+   */
+  onSubmit: (value: T, api: { reset: () => void }) => void | Promise<void>
+}
+
+/** The `error` prop of a field, from TanStack's error list. */
+export function fieldError(field: {
+  state: { meta: { errors: unknown[] } }
+}): string | undefined {
+  const { errors } = field.state.meta
+  if (errors.length === 0) return undefined
+  const messages = errors.map((error) =>
+    typeof error === 'string'
+      ? error
+      : error && typeof error === 'object' && 'message' in error
+        ? String((error as { message: unknown }).message)
+        : String(error),
+  )
+  // A field usually declares the same message for `onChange` and `onSubmit`
+  // (validate as you type, and again on the way out). TanStack keeps one entry
+  // per validator, so the naive join prints the sentence twice.
+  return [...new Set(messages)].join(' ')
+}
+
+export function createAppForm<T extends object>(options: AppFormOptions<T>) {
+  const form = createForm(() => ({
+    defaultValues: options.defaultValues,
+    onSubmit: async ({ value, formApi }) => {
+      await options.onSubmit(value as T, { reset: () => formApi.reset() })
+    },
+  }))
+  const submitting = form.useSelector((state) => state.isSubmitting)
+  return {
+    form,
+    /** True while the submit handler's promise is pending. */
+    submitting: submitting as Accessor<boolean>,
+  }
+}
+
+/**
+ * The `<form>` element, wired.
+ *
+ * `noValidate` because the kit's own field messages are the error UI; the native
+ * bubble would appear first, say less, and disappear on the next keystroke.
+ * `preventDefault` because this is a single-page app: a real submit would
+ * navigate.
+ */
+export function Form(props: {
+  form: { handleSubmit: () => unknown }
+  children: JSX.Element
+  class?: string
+}): JSX.Element {
+  const [local, rest] = splitProps(props, ['form', 'children', 'class'])
+  return (
+    <form
+      {...rest}
+      noValidate
+      class={local.class}
+      onSubmit={(event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        void local.form.handleSubmit()
+      }}
+    >
+      {local.children}
+    </form>
+  )
+}

package/src/form/index.ts

@@ -0,0 +1 @@
+export * from './form'

package/src/format.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { bytes, count, isEmail, usd, usdK } from './format'
+
+describe('format', () => {
+  it('formats money, counts and sizes the way the pages did', () => {
+    expect(usd(128430)).toBe('$128,430')
+    expect(usd(0)).toBe('$0')
+    expect(usdK(42500)).toBe('$43k')
+    expect(usdK(400)).toBe('$0k')
+    expect(count(128430)).toBe('128,430')
+    expect(bytes(512)).toBe('512 B')
+    expect(bytes(2048)).toBe('2.0 KB')
+    expect(bytes(5 * 1024 * 1024)).toBe('5.0 MB')
+  })
+
+  it('accepts ordinary addresses and rejects the rest', () => {
+    expect(isEmail('rhea@example.com')).toBe(true)
+    expect(isEmail('rhea@example')).toBe(false)
+    expect(isEmail('rhea kapoor@example.com')).toBe(false)
+    expect(isEmail('')).toBe(false)
+  })
+})

package/src/format.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared formatting: money, counts, sizes, addresses.
+ *
+ * Built once at module scope — an `Intl.NumberFormat` per render is the kind of
+ * cost that never shows in a profile and always shows in a list. The examples
+ * had four near-identical USD copies; this is the one.
+ */
+
+const usdFormat = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0,
+})
+
+/** Whole-dollar USD: `usd(128430)` → `$128,430`. */
+export const usd = (value: number): string => usdFormat.format(value)
+
+/** Compact axis form: `usdK(42500)` → `$43k`. */
+export const usdK = (value: number): string => `$${Math.round(value / 1000)}k`
+
+const countFormat = new Intl.NumberFormat('en-US')
+
+/** Grouped integer: `count(128430)` → `128,430`. */
+export const count = (value: number): string => countFormat.format(value)
+
+/** Human file size: `bytes(2048)` → `2.0 KB`. */
+export const bytes = (value: number): string =>
+  value < 1024
+    ? `${value} B`
+    : value < 1024 * 1024
+      ? `${(value / 1024).toFixed(1)} KB`
+      : `${(value / (1024 * 1024)).toFixed(1)} MB`
+
+/** The one address check every example form shares. */
+export const isEmail = (value: string): boolean =>
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './download'
+export * from './format'
+export * from './select'
+export * from './undo'

package/src/query/client.tsx

@@ -0,0 +1,53 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
+import { type JSX, onCleanup, untrack } from 'solid-js'
+
+/**
+ * The query client an app boots with.
+ *
+ * The defaults are the kit's opinion, stated once: local data is not a
+ * dashboard (no refetch on window focus), a transient failure is worth one retry,
+ * and an error is data the page renders rather than an exception that tears the
+ * tree down. A page overrides any of them per query.
+ */
+export interface DataClientOptions {
+  /** How long a list is fresh. Default `30_000`. */
+  staleTime?: number
+  /** Retries after the first failure. Default `1`. */
+  retry?: number
+}
+
+export function createDataClient(options: DataClientOptions = {}): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: options.staleTime ?? 30_000,
+        retry: options.retry ?? 1,
+        refetchOnWindowFocus: false,
+        throwOnError: false,
+      },
+      mutations: { retry: 0 },
+    },
+  })
+}
+
+/**
+ * The provider a page wraps its workspace in.
+ *
+ * Pass `client` to share one (a workspace with several panes shares its cache);
+ * omit it and the provider owns a client and clears it on unmount, so a route
+ * change never leaves timers or caches behind.
+ */
+export function DataProvider(props: {
+  client?: QueryClient
+  options?: DataClientOptions
+  children: JSX.Element
+}): JSX.Element {
+  // Chosen once, by design: swapping a provider's client mid-tree would orphan
+  // the cache every consumer is reading from.
+  const provided = untrack(() => props.client)
+  const client = provided ?? createDataClient(untrack(() => props.options))
+  if (!provided) onCleanup(() => client.clear())
+  return (
+    <QueryClientProvider client={client}>{props.children}</QueryClientProvider>
+  )
+}

package/src/query/collection.test.tsx

@@ -0,0 +1,151 @@
+import { render, screen, waitFor } from '@solidjs/testing-library'
+import { For, type JSX, untrack } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { DataProvider } from './client'
+import { type Collection, createCollection } from './collection'
+import type { Repository } from './repository'
+
+interface Row {
+  id: string
+  title: string
+}
+
+interface Deferred<T> {
+  promise: Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+}
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((ok, fail) => {
+    resolve = ok
+    reject = fail
+  })
+  return { promise, resolve, reject }
+}
+
+function makeRepository(initial: Row[]) {
+  let rows = [...initial]
+  const repository: Repository<Row, { title: string }> = {
+    list: async () => [...rows],
+    create: async (input) => {
+      const row = { id: `R-${rows.length + 1}`, title: input.title }
+      rows = [row, ...rows]
+      return row
+    },
+    update: vi.fn(async (id, patch) => {
+      rows = rows.map((row) => (row.id === id ? { ...row, ...patch } : row))
+      return rows.find((row) => row.id === id) as Row
+    }),
+    remove: async (ids) => {
+      const gone = new Set(ids)
+      rows = rows.filter((row) => !gone.has(row.id))
+    },
+  }
+  return { repository, rows: () => rows }
+}
+
+function Harness(props: {
+  repository: Repository<Row, { title: string }>
+  ready: (collection: Collection<Row, { title: string }>) => void
+}): JSX.Element {
+  const collection = createCollection(() => ({
+    key: ['rows'],
+    repository: props.repository,
+    retry: false,
+  }))
+  untrack(() => props.ready(collection))
+  return (
+    <ul>
+      <For each={collection.query.rows()}>{(row) => <li>{row.title}</li>}</For>
+    </ul>
+  )
+}
+
+function mount(repository: Repository<Row, { title: string }>) {
+  let collection!: Collection<Row, { title: string }>
+  render(() => (
+    <DataProvider>
+      <Harness
+        repository={repository}
+        ready={(value) => (collection = value)}
+      />
+    </DataProvider>
+  ))
+  return () => collection
+}
+
+describe('createCollection', () => {
+  it('loads the list and reports its pending and error states', async () => {
+    const failing = deferred<Row[]>()
+    const { repository } = makeRepository([{ id: '1', title: 'One' }])
+    const broken: Repository<Row, { title: string }> = {
+      ...repository,
+      list: () => failing.promise,
+    }
+    const collection = mount(broken)
+    expect(collection().query.isPending()).toBe(true)
+
+    failing.reject(new Error('The service is down'))
+    await waitFor(() => expect(collection().query.isError()).toBe(true))
+    expect(collection().query.error()?.message).toBe('The service is down')
+  })
+
+  it('patches optimistically and restores the list when the request fails', async () => {
+    const gate = deferred<Row>()
+    const { repository } = makeRepository([
+      { id: '1', title: 'One' },
+      { id: '2', title: 'Two' },
+    ])
+    const gated: Repository<Row, { title: string }> = {
+      ...repository,
+      update: (id, patch) => {
+        gate.promise.then(
+          () => repository.update(id, patch),
+          () => {},
+        )
+        return gate.promise
+      },
+    }
+    const collection = mount(gated)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    collection().update.mutate({ id: '1', patch: { title: 'Changed' } })
+    // On screen before the request settles — that is the point of optimistic.
+    await waitFor(() => expect(screen.getByText('Changed')).toBeTruthy())
+
+    gate.reject(new Error('nope'))
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+    expect(screen.queryByText('Changed')).toBeNull()
+  })
+
+  it('creates through the repository and refreshes the list', async () => {
+    const { repository, rows } = makeRepository([{ id: '1', title: 'One' }])
+    const collection = mount(repository)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    await collection().create.mutateAsync({ title: 'New' })
+    expect(rows()[0]?.title).toBe('New')
+    await waitFor(() => expect(screen.getByText('New')).toBeTruthy())
+  })
+
+  it('completes many at once and removes through the same seam', async () => {
+    const { repository } = makeRepository([
+      { id: '1', title: 'One' },
+      { id: '2', title: 'Two' },
+    ])
+    const collection = mount(repository)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    await collection().updateMany.mutateAsync({
+      ids: ['1', '2'],
+      patch: { title: 'Done' },
+    })
+    await waitFor(() => expect(screen.getAllByText('Done')).toHaveLength(2))
+
+    await collection().remove.mutateAsync({ ids: ['1', '2'] })
+    await waitFor(() => expect(screen.queryByText('Done')).toBeNull())
+  })
+})

package/src/query/collection.ts

@@ -0,0 +1,192 @@
+import {
+  createMutation,
+  createQuery,
+  type QueryKey,
+  useQueryClient,
+} from '@tanstack/solid-query'
+import type { Accessor } from 'solid-js'
+import type { NewRecord, Repository } from './repository'
+
+/**
+ * A list and the four things a page does to it.
+ *
+ * `createCollection` is the kit's answer to "how does a page hold its records":
+ * one query for the list, and mutations that are **optimistic and reversible** —
+ * a patch lands on screen immediately, and a failed request puts the previous
+ * list back. The page renders `isPending` / `error` and never touches the cache.
+ *
+ * The list is keyed by `key`, so two panes reading the same collection share one
+ * request and one update. The repository stays the only place that knows where
+ * the records come from.
+ */
+
+export interface ListQuery<T> {
+  /** The records; `[]` while the first request is in flight. */
+  rows: Accessor<T[]>
+  /** The first request has not settled. */
+  isPending: Accessor<boolean>
+  /** A request is in flight, first or refetch. */
+  isFetching: Accessor<boolean>
+  /** The last request failed; `error` says why. */
+  isError: Accessor<boolean>
+  error: Accessor<Error | undefined>
+  /** Re-run the list request (the "Try again" button). */
+  refetch: () => Promise<unknown>
+}
+
+export interface CollectionMutation<Input, Result> {
+  mutate: (input: Input) => void
+  /** Resolves when the mutation *and* the list refresh have settled. */
+  mutateAsync: (input: Input) => Promise<Result>
+  isPending: Accessor<boolean>
+  error: Accessor<Error | undefined>
+}
+
+export interface Collection<T extends { id: string }, New = NewRecord<T>> {
+  query: ListQuery<T>
+  create: CollectionMutation<New, T>
+  update: CollectionMutation<{ id: string; patch: Partial<T> }, T>
+  /** Patch many at once — the bulk action. */
+  updateMany: CollectionMutation<{ ids: string[]; patch: Partial<T> }, T[]>
+  remove: CollectionMutation<{ ids: string[] }, void>
+}
+
+export interface CollectionOptions<
+  T extends { id: string },
+  New = NewRecord<T>,
+> {
+  /** The cache identity. Same key = same collection. */
+  key: QueryKey
+  repository: Repository<T, New>
+  /** The list's freshness. Defaults to the client's. */
+  staleTime?: number
+  /** Retries after the first failure. Defaults to the client's. */
+  retry?: number | false
+  /** Every mutation reports here first, so a page can word one notice. */
+  onError?: (error: Error) => void
+}
+
+function asError(value: unknown): Error | undefined {
+  if (value === null || value === undefined) return undefined
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+export function createListQuery<T extends { id: string }>(
+  options: () => CollectionOptions<T, never>,
+): ListQuery<T> {
+  const query = createQuery(() => ({
+    queryKey: options().key,
+    queryFn: ({ signal }) => options().repository.list({ signal }),
+    staleTime: options().staleTime,
+    retry: options().retry,
+    throwOnError: false,
+  }))
+  return {
+    rows: () => query.data ?? [],
+    isPending: () => query.isPending,
+    isFetching: () => query.isFetching,
+    isError: () => query.isError,
+    error: () => asError(query.error),
+    refetch: () => query.refetch(),
+  }
+}
+
+export function createCollection<T extends { id: string }, New = NewRecord<T>>(
+  options: () => CollectionOptions<T, New>,
+): Collection<T, New> {
+  const queryClient = useQueryClient()
+  const key = () => options().key
+  const fail = (error: unknown) => {
+    const normalised = asError(error)
+    if (normalised) options().onError?.(normalised)
+    return normalised
+  }
+  const previous = () => queryClient.getQueryData<T[]>(key())
+  const restore = (snapshot: T[] | undefined) => {
+    if (snapshot) queryClient.setQueryData(key(), snapshot)
+  }
+  const patchRows = (ids: string[], patch: Partial<T>) => {
+    const wanted = new Set(ids)
+    queryClient.setQueryData<T[]>(key(), (rows = []) =>
+      rows.map((row) => (wanted.has(row.id) ? { ...row, ...patch } : row)),
+    )
+  }
+
+  const query = createListQuery(options)
+
+  const create = createMutation(() => ({
+    mutationFn: (input: New) => options().repository.create(input),
+    // Not optimistic: a new record's id and defaults are the repository's to
+    // decide, so guessing them would show a row that then changes identity.
+    onError: (error) => void fail(error),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const update = createMutation(() => ({
+    mutationFn: ({ id, patch }: { id: string; patch: Partial<T> }) =>
+      options().repository.update(id, patch),
+    onMutate: async ({ id, patch }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      patchRows([id], patch)
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const updateMany = createMutation(() => ({
+    mutationFn: async ({ ids, patch }: { ids: string[]; patch: Partial<T> }) =>
+      Promise.all(ids.map((id) => options().repository.update(id, patch))),
+    onMutate: async ({ ids, patch }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      patchRows(ids, patch)
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const remove = createMutation(() => ({
+    mutationFn: ({ ids }: { ids: string[] }) =>
+      options().repository.remove(ids),
+    onMutate: async ({ ids }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      const wanted = new Set(ids)
+      queryClient.setQueryData<T[]>(key(), (rows = []) =>
+        rows.filter((row) => !wanted.has(row.id)),
+      )
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const wrap = <Input, Result>(
+    mutation: ReturnType<typeof createMutation<Result, Error, Input>>,
+  ): CollectionMutation<Input, Result> => ({
+    mutate: (input: Input) => mutation.mutate(input),
+    mutateAsync: (input: Input) => mutation.mutateAsync(input),
+    isPending: () => mutation.isPending,
+    error: () => asError(mutation.error),
+  })
+
+  return {
+    query,
+    create: wrap(create),
+    update: wrap(update),
+    updateMany: wrap(updateMany),
+    remove: wrap(remove),
+  }
+}

package/src/query/index.ts

@@ -0,0 +1,3 @@
+export * from './client'
+export * from './collection'
+export * from './repository'

package/src/query/repository.ts

@@ -0,0 +1,30 @@
+/**
+ * A repository is the seam between a page and wherever its records live.
+ *
+ * It is deliberately small: `list`, `create`, `update`, `remove`. Domain verbs
+ * (`complete`, `archive`, `comment`) are `update(id, patch)` with a different
+ * name at the call site — a contract that grows a method per business action is
+ * a database, not a seam.
+ *
+ * `list` is the only read. A page that needs one record filters the list it
+ * already has; a remote adapter that wants a single request can still expose
+ * `list` and let the query cache hold the collection, which is what every local
+ * example does.
+ */
+export interface Repository<T extends { id: string }, New = NewRecord<T>> {
+  /** Every record, in the order the collection wants them shown. */
+  list(options?: { signal?: AbortSignal }): Promise<T[]>
+  /** Create one; resolves with the stored record (its real id included). */
+  create(input: New, options?: { signal?: AbortSignal }): Promise<T>
+  /** Patch one; resolves with the stored record. */
+  update(
+    id: string,
+    patch: Partial<T>,
+    options?: { signal?: AbortSignal },
+  ): Promise<T>
+  /** Delete many at once; resolves when they are gone. */
+  remove(ids: string[], options?: { signal?: AbortSignal }): Promise<void>
+}
+
+/** What a caller must supply to create a record: everything but the id it gets. */
+export type NewRecord<T> = Omit<T, 'id'> & { id?: string }