create-simone-app 0.1.0

package/templates/fe/base/src/features/users/UsersPage.tsx

@@ -0,0 +1,58 @@
+import { getRouteApi } from '@tanstack/react-router'
+
+import { EmptyState } from '@/components/shared/EmptyState'
+import { ErrorState } from '@/components/shared/ErrorState'
+import { PageHeader } from '@/components/shared/PageHeader'
+
+import { UserSearch } from './UserSearch'
+import { UsersTable } from './UsersTable'
+import { UsersTableSkeleton } from './UsersTableSkeleton'
+import { useUsers } from './useUsers'
+import type { UsersQuery } from './users.schema'
+
+// getRouteApi avoids the route ↔ page circular import.
+const routeApi = getRouteApi('/users/')
+
+export function UsersPage() {
+  const search = routeApi.useSearch()
+  const navigate = routeApi.useNavigate()
+  const { data, isPending, isError, error, isFetching, refetch } =
+    useUsers(search)
+
+  const update = (patch: Partial<UsersQuery>) =>
+    void navigate({ to: '/users', search: (prev) => ({ ...prev, ...patch }) })
+
+  return (
+    <section aria-busy={isFetching} data-testid="users-page">
+      <PageHeader
+        title="Utenti"
+        description="Ricerca, ordinamento e paginazione lato server."
+      />
+      <UserSearch value={search.q} onChange={(q) => update({ q, page: 1 })} />
+      {isPending ? (
+        <UsersTableSkeleton />
+      ) : isError ? (
+        <ErrorState
+          message={error.message}
+          onRetry={() => void refetch()}
+          testId="users-error-state"
+        />
+      ) : data.total === 0 ? (
+        <EmptyState
+          title="Nessun utente trovato"
+          description={
+            search.q ? `Nessun risultato per “${search.q}”.` : undefined
+          }
+          testId="users-empty-state"
+        />
+      ) : (
+        <UsersTable
+          users={data.data}
+          total={data.total}
+          query={search}
+          onQueryChange={update}
+        />
+      )}
+    </section>
+  )
+}

package/templates/fe/base/src/features/users/UsersTable.tsx

@@ -0,0 +1,245 @@
+import {
+  type SortingState,
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  useReactTable,
+} from '@tanstack/react-table'
+
+import { ArrowDown, ArrowUp, ArrowUpDown } from 'lucide-react'
+
+import { Button } from '@/components/ui/button'
+import {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { useTableDensity } from '@/stores'
+
+import {
+  USER_SORT_FIELDS,
+  type User,
+  type UserSortField,
+  type UsersQuery,
+} from './users.schema'
+
+interface UsersTableProps {
+  users: User[]
+  total: number
+  query: UsersQuery
+  onQueryChange: (patch: Partial<UsersQuery>) => void
+}
+
+const columnHelper = createColumnHelper<User>()
+const dateFormatter = new Intl.DateTimeFormat('it-IT', { dateStyle: 'medium' })
+
+const columns = [
+  columnHelper.accessor('name', { header: 'Nome' }),
+  columnHelper.accessor('email', { header: 'Email' }),
+  columnHelper.accessor('role', {
+    header: 'Ruolo',
+    cell: (info) => (
+      <span
+        className="rounded-md bg-muted px-2 py-0.5 text-xs font-medium capitalize"
+        data-testid={`user-role-badge-${info.row.original.id}`}
+      >
+        {info.getValue()}
+      </span>
+    ),
+  }),
+  columnHelper.accessor('createdAt', {
+    header: 'Creato il',
+    cell: (info) => dateFormatter.format(new Date(info.getValue())),
+  }),
+]
+
+const isSortField = (id: string): id is UserSortField =>
+  (USER_SORT_FIELDS as readonly string[]).includes(id)
+
+/** Server-side table (tanstack §3.4): sorting/pagination live in the route search params. */
+export function UsersTable({
+  users,
+  total,
+  query,
+  onQueryChange,
+}: UsersTableProps) {
+  const { density, cellClass, toggle: toggleDensity } = useTableDensity()
+  const sorting: SortingState = [
+    { id: query.sort, desc: query.order === 'desc' },
+  ]
+  const pageCount = Math.max(1, Math.ceil(total / query.limit))
+
+  const table = useReactTable({
+    data: users,
+    columns,
+    rowCount: total,
+    state: {
+      sorting,
+      pagination: { pageIndex: query.page - 1, pageSize: query.limit },
+    },
+    manualSorting: true,
+    manualPagination: true,
+    enableSortingRemoval: false,
+    onSortingChange: (updater) => {
+      const next = typeof updater === 'function' ? updater(sorting) : updater
+      const first = next[0]
+      if (first && isSortField(first.id)) {
+        onQueryChange({
+          sort: first.id,
+          order: first.desc ? 'desc' : 'asc',
+          page: 1,
+        })
+      }
+    },
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  // ponytail: all page buttons rendered; add a window when a list exceeds ~10 pages.
+  const pages = Array.from({ length: pageCount }, (_, i) => i + 1)
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex justify-end">
+        <Button
+          variant="outline"
+          size="sm"
+          aria-pressed={density === 'compact'}
+          onClick={toggleDensity}
+          data-testid="users-density-button"
+        >
+          Vista compatta
+        </Button>
+      </div>
+
+      <Table data-testid="users-table">
+        <TableCaption className="sr-only">
+          Elenco utenti: {total} risultati, pagina {query.page} di {pageCount}
+        </TableCaption>
+        <TableHeader>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <TableRow key={headerGroup.id}>
+              {headerGroup.headers.map((header) => {
+                const sorted = header.column.getIsSorted()
+                const label = String(header.column.columnDef.header)
+                return (
+                  <TableHead
+                    key={header.id}
+                    scope="col"
+                    aria-sort={
+                      sorted === 'asc'
+                        ? 'ascending'
+                        : sorted === 'desc'
+                          ? 'descending'
+                          : 'none'
+                    }
+                    className={cellClass}
+                  >
+                    <button
+                      type="button"
+                      onClick={header.column.getToggleSortingHandler()}
+                      aria-label={
+                        sorted === 'asc'
+                          ? `Ordinato per ${label} crescente. Premere per invertire.`
+                          : sorted === 'desc'
+                            ? `Ordinato per ${label} decrescente. Premere per invertire.`
+                            : `Ordina per ${label}`
+                      }
+                      className="flex items-center gap-1 font-medium"
+                      data-testid={`users-table-sort-${header.column.id}`}
+                    >
+                      {flexRender(
+                        header.column.columnDef.header,
+                        header.getContext(),
+                      )}
+                      {sorted === 'asc' && (
+                        <ArrowUp aria-hidden="true" className="size-4" />
+                      )}
+                      {sorted === 'desc' && (
+                        <ArrowDown aria-hidden="true" className="size-4" />
+                      )}
+                      {!sorted && (
+                        <ArrowUpDown
+                          aria-hidden="true"
+                          className="size-4 opacity-50"
+                        />
+                      )}
+                    </button>
+                  </TableHead>
+                )
+              })}
+            </TableRow>
+          ))}
+        </TableHeader>
+        <TableBody>
+          {table.getRowModel().rows.map((row) => (
+            <TableRow key={row.id} data-testid={`user-row-${row.original.id}`}>
+              {row.getVisibleCells().map((cell) => (
+                <TableCell key={cell.id} className={cellClass}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+
+      <nav
+        aria-label="Paginazione utenti"
+        className="flex flex-wrap items-center justify-between gap-3"
+        data-testid="users-pagination"
+      >
+        <p
+          className="text-sm text-muted-foreground"
+          aria-live="polite"
+          data-testid="users-pagination-status"
+        >
+          Pagina {query.page} di {pageCount} · {total} utenti
+        </p>
+        <ul className="flex items-center gap-1">
+          <li>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={query.page <= 1}
+              onClick={() => onQueryChange({ page: query.page - 1 })}
+              aria-label="Pagina precedente"
+              data-testid="users-pagination-prev-button"
+            >
+              Precedente
+            </Button>
+          </li>
+          {pages.map((page) => (
+            <li key={page}>
+              <Button
+                variant={page === query.page ? 'default' : 'outline'}
+                size="sm"
+                aria-current={page === query.page ? 'page' : undefined}
+                aria-label={`Pagina ${page}${page === query.page ? ', corrente' : ''}`}
+                onClick={() => onQueryChange({ page })}
+                data-testid={`users-pagination-page-${page}`}
+              >
+                {page}
+              </Button>
+            </li>
+          ))}
+          <li>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={query.page >= pageCount}
+              onClick={() => onQueryChange({ page: query.page + 1 })}
+              aria-label="Pagina successiva"
+              data-testid="users-pagination-next-button"
+            >
+              Successiva
+            </Button>
+          </li>
+        </ul>
+      </nav>
+    </div>
+  )
+}

package/templates/fe/base/src/features/users/UsersTableSkeleton.tsx

@@ -0,0 +1,16 @@
+import { Skeleton } from '@/components/ui/skeleton'
+
+export function UsersTableSkeleton({ rows = 8 }: { rows?: number }) {
+  return (
+    <div
+      role="status"
+      aria-label="Caricamento utenti"
+      className="flex flex-col gap-2"
+      data-testid="users-table-skeleton"
+    >
+      {Array.from({ length: rows }, (_, i) => (
+        <Skeleton key={i} className="h-10 w-full" />
+      ))}
+    </div>
+  )
+}

package/templates/fe/base/src/features/users/__tests__/UserSearch.test.tsx

@@ -0,0 +1,30 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { UserSearch } from '../UserSearch'
+
+describe('UserSearch', () => {
+  it('has an associated label and debounces keystrokes into one onChange', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<UserSearch value="" onChange={onChange} delay={50} />)
+
+    const input = screen.getByLabelText('Cerca')
+    expect(input).toBe(screen.getByTestId('users-search-input'))
+
+    await user.type(input, ' mar ')
+    expect(onChange).not.toHaveBeenCalled()
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith('mar'))
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('adopts an external value change', () => {
+    const { rerender } = render(
+      <UserSearch value="a" onChange={() => undefined} />,
+    )
+    expect(screen.getByTestId('users-search-input')).toHaveValue('a')
+    rerender(<UserSearch value="b" onChange={() => undefined} />)
+    expect(screen.getByTestId('users-search-input')).toHaveValue('b')
+  })
+})

package/templates/fe/base/src/features/users/__tests__/UsersPage.test.tsx

@@ -0,0 +1,69 @@
+import { screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+
+import { apiMock } from '@/test/api-mock'
+import { renderApp } from '@/test/render'
+
+describe('/users page', () => {
+  it('shows the skeleton, then the rows', async () => {
+    renderApp('/users')
+    expect(
+      await screen.findByTestId('users-table-skeleton'),
+    ).toBeInTheDocument()
+    expect(await screen.findByTestId('user-row-u-001')).toBeInTheDocument()
+    expect(screen.queryByTestId('users-table-skeleton')).not.toBeInTheDocument()
+    expect(screen.getAllByTestId(/^user-row-/)).toHaveLength(20)
+  })
+
+  it('reads page/sort/order from the URL and updates aria-sort on header click', async () => {
+    const user = userEvent.setup()
+    const { router } = renderApp('/users?page=2&sort=email&order=desc')
+    expect(await screen.findByTestId('user-row-u-025')).toBeInTheDocument()
+    expect(screen.getByTestId('users-pagination-page-2')).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    const emailHeader = screen
+      .getByTestId('users-table-sort-email')
+      .closest('th')
+    expect(emailHeader).toHaveAttribute('aria-sort', 'descending')
+
+    await user.click(screen.getByTestId('users-table-sort-name'))
+    // sort=name/order=asc/page=1 are defaults → stripSearchParams leaves a clean URL
+    await waitFor(() => expect(router.state.location.search).toEqual({}))
+    expect(await screen.findByTestId('user-row-u-001')).toBeInTheDocument()
+    expect(
+      screen.getByTestId('users-table-sort-name').closest('th'),
+    ).toHaveAttribute('aria-sort', 'ascending')
+  })
+
+  it('falls back to defaults on garbage search params', async () => {
+    const { router } = renderApp(
+      '/users?page=-3&limit=999&sort=password&order=sideways',
+    )
+    expect(await screen.findByTestId('user-row-u-001')).toBeInTheDocument()
+    expect(router.state.location.search).toEqual({})
+  })
+
+  it('shows the empty state when the search has no match', async () => {
+    const user = userEvent.setup()
+    const { router } = renderApp('/users')
+    await screen.findByTestId('user-row-u-001')
+    await user.type(screen.getByTestId('users-search-input'), 'zzz-nope')
+    expect(await screen.findByTestId('users-empty-state')).toHaveTextContent(
+      'Nessun risultato per “zzz-nope”',
+    )
+    expect(router.state.location.search).toEqual({ q: 'zzz-nope' })
+  })
+
+  it('shows the error state with a working retry', async () => {
+    const user = userEvent.setup()
+    apiMock.failOnce(503, { error: 'Upstream down' })
+    renderApp('/users')
+    const error = await screen.findByTestId('users-error-state')
+    expect(error).toHaveTextContent('Upstream down')
+    await user.click(screen.getByTestId('users-error-state-retry-button'))
+    expect(await screen.findByTestId('user-row-u-001')).toBeInTheDocument()
+  })
+})

package/templates/fe/base/src/features/users/__tests__/UsersTable.test.tsx

@@ -0,0 +1,120 @@
+import { screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+
+import { mockUsers } from '@/test/fixtures/users'
+import { renderWithQuery } from '@/test/render'
+
+import { UsersTable } from '../UsersTable'
+import { DEFAULT_USERS_QUERY } from '../users.schema'
+
+const users = mockUsers.slice(0, 20)
+
+describe('UsersTable', () => {
+  it('renders caption, one row per user, sortable headers with aria-sort', () => {
+    renderWithQuery(
+      <UsersTable
+        users={users}
+        total={45}
+        query={DEFAULT_USERS_QUERY}
+        onQueryChange={vi.fn()}
+      />,
+    )
+    const table = screen.getByTestId('users-table')
+    expect(
+      within(table).getByText(/Elenco utenti: 45 risultati, pagina 1 di 3/),
+    ).toBeInTheDocument()
+    expect(screen.getAllByTestId(/^user-row-/)).toHaveLength(20)
+    expect(screen.getByTestId('user-row-u-001')).toBeInTheDocument()
+    const headers = within(table).getAllByRole('columnheader')
+    expect(headers).toHaveLength(4)
+    expect(headers[0]).toHaveAttribute('aria-sort', 'ascending')
+    expect(headers[1]).toHaveAttribute('aria-sort', 'none')
+  })
+
+  it('toggles sort direction through the search params', async () => {
+    const user = userEvent.setup()
+    const onQueryChange = vi.fn()
+    renderWithQuery(
+      <UsersTable
+        users={users}
+        total={45}
+        query={DEFAULT_USERS_QUERY}
+        onQueryChange={onQueryChange}
+      />,
+    )
+    await user.click(screen.getByTestId('users-table-sort-name'))
+    expect(onQueryChange).toHaveBeenCalledWith({
+      sort: 'name',
+      order: 'desc',
+      page: 1,
+    })
+    await user.click(screen.getByTestId('users-table-sort-email'))
+    expect(onQueryChange).toHaveBeenLastCalledWith({
+      sort: 'email',
+      order: 'asc',
+      page: 1,
+    })
+  })
+
+  it('paginates with prev/next/page buttons and aria-current', async () => {
+    const user = userEvent.setup()
+    const onQueryChange = vi.fn()
+    renderWithQuery(
+      <UsersTable
+        users={users}
+        total={45}
+        query={{ ...DEFAULT_USERS_QUERY, page: 2 }}
+        onQueryChange={onQueryChange}
+      />,
+    )
+    expect(screen.getByTestId('users-pagination-page-2')).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    expect(screen.getByTestId('users-pagination-status')).toHaveTextContent(
+      'Pagina 2 di 3 · 45 utenti',
+    )
+    await user.click(screen.getByTestId('users-pagination-next-button'))
+    expect(onQueryChange).toHaveBeenLastCalledWith({ page: 3 })
+    await user.click(screen.getByTestId('users-pagination-prev-button'))
+    expect(onQueryChange).toHaveBeenLastCalledWith({ page: 1 })
+    await user.click(screen.getByTestId('users-pagination-page-3'))
+    expect(onQueryChange).toHaveBeenLastCalledWith({ page: 3 })
+  })
+
+  it('disables prev on the first page and next on the last', () => {
+    renderWithQuery(
+      <UsersTable
+        users={users}
+        total={20}
+        query={DEFAULT_USERS_QUERY}
+        onQueryChange={vi.fn()}
+      />,
+    )
+    expect(screen.getByTestId('users-pagination-prev-button')).toBeDisabled()
+    expect(screen.getByTestId('users-pagination-next-button')).toBeDisabled()
+  })
+
+  it('switches cell density via the Jotai atom', async () => {
+    const user = userEvent.setup()
+    renderWithQuery(
+      <UsersTable
+        users={users}
+        total={45}
+        query={DEFAULT_USERS_QUERY}
+        onQueryChange={vi.fn()}
+      />,
+    )
+    const cell = within(screen.getByTestId('user-row-u-001')).getAllByRole(
+      'cell',
+    )[0]
+    expect(cell).toHaveClass('px-4', 'py-3')
+    await user.click(screen.getByTestId('users-density-button'))
+    expect(screen.getByTestId('users-density-button')).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    )
+    expect(cell).toHaveClass('px-2', 'py-1')
+  })
+})

package/templates/fe/base/src/features/users/__tests__/useUsers.test.tsx

@@ -0,0 +1,62 @@
+import { waitFor } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { ApiError } from '@/lib/apiClient'
+import { apiMock } from '@/test/api-mock'
+import { renderHookWithQuery } from '@/test/render'
+
+import { useUsers, userKeys } from '../useUsers'
+import { DEFAULT_USERS_QUERY } from '../users.schema'
+
+describe('useUsers', () => {
+  it('loads the first page', async () => {
+    const { result } = renderHookWithQuery(() => useUsers(DEFAULT_USERS_QUERY))
+    expect(result.current.isPending).toBe(true)
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(result.current.data).toMatchObject({ page: 1, limit: 20, total: 45 })
+    expect(result.current.data?.data).toHaveLength(20)
+  })
+
+  it('sends q and sort=-field to the API', async () => {
+    const { result } = renderHookWithQuery(() =>
+      useUsers({
+        ...DEFAULT_USERS_QUERY,
+        q: 'user 04',
+        sort: 'name',
+        order: 'desc',
+      }),
+    )
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    const names = result.current.data?.data.map((u) => u.name) ?? []
+    expect(names).toEqual([
+      'User 045',
+      'User 044',
+      'User 043',
+      'User 042',
+      'User 041',
+      'User 040',
+    ])
+  })
+
+  it('surfaces API failures as ApiError', async () => {
+    apiMock.failOnce(500, { error: 'boom' })
+    const { result } = renderHookWithQuery(() => useUsers(DEFAULT_USERS_QUERY))
+    await waitFor(() => expect(result.current.isError).toBe(true))
+    expect(result.current.error).toBeInstanceOf(ApiError)
+    expect(result.current.error).toMatchObject({ status: 500, message: 'boom' })
+  })
+
+  it('rejects a malformed payload', async () => {
+    apiMock.respondOnce({ rows: [] })
+    const { result } = renderHookWithQuery(() => useUsers(DEFAULT_USERS_QUERY))
+    await waitFor(() => expect(result.current.isError).toBe(true))
+  })
+
+  it('keys include the full query', () => {
+    expect(userKeys.list(DEFAULT_USERS_QUERY)).toEqual([
+      'users',
+      'list',
+      DEFAULT_USERS_QUERY,
+    ])
+  })
+})

package/templates/fe/base/src/features/users/useUsers.ts

@@ -0,0 +1,22 @@
+import { keepPreviousData, queryOptions, useQuery } from '@tanstack/react-query'
+
+import { getUserList } from './users.api'
+import type { UsersQuery } from './users.schema'
+
+// tanstack §2.2: key factory + queryOptions factory, never inline in components.
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (query: UsersQuery) => [...userKeys.lists(), query] as const,
+}
+
+export const usersQueryOptions = (query: UsersQuery) =>
+  queryOptions({
+    queryKey: userKeys.list(query),
+    queryFn: () => getUserList(query),
+    placeholderData: keepPreviousData,
+    staleTime: 2 * 60 * 1000,
+  })
+
+export const useUsers = (query: UsersQuery) =>
+  useQuery(usersQueryOptions(query))

package/templates/fe/base/src/features/users/users.api.ts

@@ -0,0 +1,22 @@
+import { apiClient } from '@/lib/apiClient'
+
+import {
+  type UsersQuery,
+  type UsersResponse,
+  UsersResponseSchema,
+} from './users.schema'
+
+/** GET /users — maps `{ sort, order }` to the API's `sort=-field` convention. */
+export const getUserList = async (
+  query: UsersQuery,
+): Promise<UsersResponse> => {
+  const response = await apiClient.get<unknown>('/users', {
+    params: {
+      page: query.page,
+      limit: query.limit,
+      q: query.q || undefined,
+      sort: query.order === 'desc' ? `-${query.sort}` : query.sort,
+    },
+  })
+  return UsersResponseSchema.parse(response.data)
+}