create-freakpunch 0.0.0-stage → 0.2.0

package/template/src/core/components/confirm-dialog.tsx

@@ -0,0 +1,116 @@
+import { createContext, useCallback, useContext, useId, useRef, useState, type ReactNode } from 'react'
+import { Trans, useTranslation } from 'react-i18next'
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog'
+import { Field, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+
+type ConfirmOptions = {
+  title: string
+  description?: ReactNode
+  confirmLabel?: string
+  cancelLabel?: string
+  /** Red confirm button for irreversible actions. */
+  destructive?: boolean
+  /** Require typing this exact value (e.g. the company name) before confirming. */
+  typeToConfirm?: string
+}
+
+type Confirm = (options: ConfirmOptions) => Promise<boolean>
+
+const ConfirmContext = createContext<Confirm | null>(null)
+
+/**
+ * Promise-based confirm dialog:
+ *   const confirm = useConfirm()
+ *   if (await confirm({ title: t('…'), destructive: true })) …
+ */
+export function ConfirmProvider({ children }: { children: ReactNode }) {
+  const [options, setOptions] = useState<ConfirmOptions | null>(null)
+  const [open, setOpen] = useState(false)
+  const [typed, setTyped] = useState('')
+  const resolver = useRef<(value: boolean) => void>(undefined)
+  const inputId = useId()
+  const { t } = useTranslation()
+
+  const confirm = useCallback<Confirm>((opts) => {
+    setOptions(opts)
+    setTyped('')
+    setOpen(true)
+    return new Promise<boolean>((resolve) => {
+      resolver.current = resolve
+    })
+  }, [])
+
+  const settle = (value: boolean) => {
+    resolver.current?.(value)
+    resolver.current = undefined
+    setOpen(false)
+  }
+
+  const expected = options?.typeToConfirm
+  const blocked = expected !== undefined && typed.trim() !== expected
+
+  return (
+    <ConfirmContext value={confirm}>
+      {children}
+      <AlertDialog open={open} onOpenChange={(next) => !next && settle(false)}>
+        <AlertDialogContent size={expected ? 'default' : 'sm'}>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{options?.title}</AlertDialogTitle>
+            {options?.description && <AlertDialogDescription>{options.description}</AlertDialogDescription>}
+          </AlertDialogHeader>
+          {expected !== undefined && (
+            <Field>
+              <FieldLabel htmlFor={inputId} className="block font-normal text-muted-foreground">
+                <Trans
+                  t={t}
+                  i18nKey="confirm.typeToConfirm"
+                  values={{ value: expected }}
+                  components={{ b: <span className="tabular-nums font-medium text-foreground" /> }}
+                />
+              </FieldLabel>
+              <Input
+                id={inputId}
+                value={typed}
+                onChange={(e) => setTyped(e.target.value)}
+                autoComplete="off"
+                autoFocus
+                aria-label={t('confirm.typeToConfirmLabel')}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && !blocked) settle(true)
+                }}
+              />
+            </Field>
+          )}
+          <AlertDialogFooter>
+            <AlertDialogCancel>{options?.cancelLabel ?? t('actions.cancel')}</AlertDialogCancel>
+            <AlertDialogAction
+              variant={options?.destructive ? 'destructive' : 'default'}
+              disabled={blocked}
+              onClick={() => settle(true)}
+            >
+              {options?.confirmLabel ?? t('actions.confirm')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </ConfirmContext>
+  )
+}
+
+// eslint-disable-next-line react/only-export-components
+export function useConfirm() {
+  const ctx = useContext(ConfirmContext)
+  if (!ctx) throw new Error('useConfirm must be used within <ConfirmProvider>')
+  return ctx
+}

package/template/src/core/components/data-table/data-table.tsx

@@ -0,0 +1,297 @@
+import { useMemo, type ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import {
+  createColumnHelper,
+  useTable,
+  type OnChangeFn,
+  type PaginationState,
+  type RowData,
+  type RowSelectionState,
+  type SortingState,
+} from '@tanstack/react-table'
+import { ArrowDown, ArrowUp, ChevronLeft, ChevronRight, ChevronsUpDown } from 'lucide-react'
+
+import { Button } from '@/components/ui/button'
+import { Checkbox } from '@/components/ui/checkbox'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Skeleton } from '@/components/ui/skeleton'
+import { Table, TableBody, TableCell, TableHeader, TableRow } from '@/components/ui/table'
+import { EmptyState, ErrorState } from '@/core/components/states'
+import { useFormat } from '@/core/i18n/use-format'
+import { cn } from '@/lib/utils'
+import { dataTableFeatures, type DataTableColumn, type DataTableFeatures } from './features'
+import { TableHeaderCell } from './table-header-cell'
+
+const PAGE_SIZES = [10, 20, 50]
+const EMPTY: never[] = []
+const NO_SELECTION: RowSelectionState = {}
+
+/** Row checkboxes plus a bar with bulk actions. Selection is by row id, so it survives paging. */
+export type DataTableSelection = {
+  value: RowSelectionState
+  onChange: OnChangeFn<RowSelectionState>
+  /** Shown while rows are selected, e.g. a delete button. */
+  actions?: ReactNode
+}
+
+type DataTableProps<TData extends RowData> = {
+  columns: DataTableColumn<TData>[]
+  data: TData[] | undefined
+  /** Total rows on the server (for page count). */
+  total: number
+  pagination: PaginationState
+  onPaginationChange: OnChangeFn<PaginationState>
+  sorting: SortingState
+  onSortingChange: OnChangeFn<SortingState>
+  getRowId: (row: TData) => string
+  isLoading?: boolean
+  isFetching?: boolean
+  error?: unknown
+  onRetry?: () => void
+  /** Rendered above the table: search, filters, bulk actions. */
+  toolbar?: ReactNode
+  empty?: ReactNode
+  /** Translated row label for the footer counter, e.g. "products". */
+  noun?: string
+  selection?: DataTableSelection
+}
+
+/**
+ * Server-driven table: sorting and pagination are controlled from outside
+ * (usually URL state via useListUrlState) and sent to the service layer.
+ */
+export function DataTable<TData extends RowData>({
+  columns,
+  data,
+  total,
+  pagination,
+  onPaginationChange,
+  sorting,
+  onSortingChange,
+  getRowId,
+  isLoading,
+  isFetching,
+  error,
+  onRetry,
+  toolbar,
+  empty,
+  noun,
+  selection,
+}: DataTableProps<TData>) {
+  const { t } = useTranslation()
+  const fmt = useFormat()
+  const selectable = Boolean(selection)
+
+  const allColumns = useMemo<DataTableColumn<TData>[]>(() => {
+    if (!selectable) return columns
+    const helper = createColumnHelper<DataTableFeatures, TData>()
+    return [
+      helper.display({
+        id: 'select',
+        meta: { className: 'w-10' },
+        header: ({ table }) => (
+          <Checkbox
+            aria-label={t('table.selectAll')}
+            checked={table.getIsAllPageRowsSelected()}
+            indeterminate={table.getIsSomePageRowsSelected()}
+            onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
+          />
+        ),
+        cell: ({ row }) => (
+          <Checkbox
+            aria-label={t('table.selectRow')}
+            checked={row.getIsSelected()}
+            onCheckedChange={(checked) => row.toggleSelected(checked)}
+          />
+        ),
+      }),
+      ...columns,
+    ]
+  }, [columns, selectable, t])
+
+  const table = useTable({
+    features: dataTableFeatures,
+    columns: allColumns,
+    data: data ?? EMPTY,
+    getRowId,
+    rowCount: total,
+    state: { pagination, sorting, rowSelection: selection?.value ?? NO_SELECTION },
+    onPaginationChange,
+    onSortingChange,
+    onRowSelectionChange: selection?.onChange,
+    enableRowSelection: selectable,
+    manualPagination: true,
+    manualSorting: true,
+    enableSortingRemoval: true,
+  })
+
+  const rows = table.getRowModel().rows
+  const pageCount = Math.max(1, table.getPageCount())
+  const from = total === 0 ? 0 : pagination.pageIndex * pagination.pageSize + 1
+  const to = Math.min(total, (pagination.pageIndex + 1) * pagination.pageSize)
+  const colCount = allColumns.length
+  const selectedCount = Object.values(selection?.value ?? NO_SELECTION).filter(Boolean).length
+
+  return (
+    <div className="flex flex-col overflow-hidden rounded-xl border bg-card shadow-(--shadow-card)">
+      {toolbar && <div className="flex flex-wrap items-center gap-2 border-b p-3">{toolbar}</div>}
+      {selectedCount > 0 && (
+        <div className="flex flex-wrap items-center gap-2 border-b bg-fill-1 px-4 py-2 text-sm">
+          <span className="font-medium tabular-nums">{t('table.selected', { count: selectedCount })}</span>
+          <Button variant="ghost" size="sm" onClick={() => selection?.onChange({})}>
+            {t('table.clearSelection')}
+          </Button>
+          <div className="ml-auto flex flex-wrap items-center gap-2">{selection?.actions}</div>
+        </div>
+      )}
+
+      <div className={cn('relative transition-opacity', isFetching && !isLoading && 'opacity-60')} aria-busy={isFetching}>
+        <Table>
+          <TableHeader>
+            {table.getHeaderGroups().map((group) => (
+              <TableRow key={group.id} className="hover:bg-transparent">
+                {group.headers.map((header) => {
+                  const meta = header.column.columnDef.meta
+                  const sorted = header.column.getIsSorted()
+                  return (
+                    <TableHeaderCell
+                      key={header.id}
+                      aria-sort={sorted ? (sorted === 'asc' ? 'ascending' : 'descending') : undefined}
+                      className={cn(
+                        meta?.align === 'right' && 'text-right',
+                        meta?.hideOnMobile && 'hidden sm:table-cell',
+                        meta?.className,
+                      )}
+                    >
+                      {header.isPlaceholder ? null : header.column.getCanSort() ? (
+                        <button
+                          type="button"
+                          onClick={header.column.getToggleSortingHandler()}
+                          className={cn(
+                            '-mx-1.5 inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 uppercase outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/40',
+                            sorted && 'text-foreground',
+                            meta?.align === 'right' && 'flex-row-reverse',
+                          )}
+                        >
+                          <table.FlexRender header={header} />
+                          {sorted === 'asc' ? (
+                            <ArrowUp className="size-3" />
+                          ) : sorted === 'desc' ? (
+                            <ArrowDown className="size-3" />
+                          ) : (
+                            <ChevronsUpDown className="size-3 opacity-50" />
+                          )}
+                        </button>
+                      ) : (
+                        <table.FlexRender header={header} />
+                      )}
+                    </TableHeaderCell>
+                  )
+                })}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              Array.from({ length: Math.min(pagination.pageSize, 8) }, (_, i) => (
+                <TableRow key={i} className="hover:bg-transparent">
+                  {Array.from({ length: colCount }, (_, j) => (
+                    <TableCell key={j} className="h-12 first:pl-4 last:pr-4">
+                      <Skeleton className="h-4 w-full max-w-32" />
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : error ? (
+              <TableRow className="hover:bg-transparent">
+                <TableCell colSpan={colCount}>
+                  <ErrorState error={error} onRetry={onRetry} />
+                </TableCell>
+              </TableRow>
+            ) : rows.length === 0 ? (
+              <TableRow className="hover:bg-transparent">
+                <TableCell colSpan={colCount}>{empty ?? <EmptyState title={t('table.noResults')} />}</TableCell>
+              </TableRow>
+            ) : (
+              rows.map((row) => (
+                <TableRow key={row.id} data-state={row.getIsSelected() ? 'selected' : undefined}>
+                  {row.getAllCells().map((cell) => {
+                    const meta = cell.column.columnDef.meta
+                    return (
+                      <TableCell
+                        key={cell.id}
+                        className={cn(
+                          'h-12 first:pl-4 last:pr-4',
+                          meta?.align === 'right' && 'text-right tabular-nums',
+                          meta?.hideOnMobile && 'hidden sm:table-cell',
+                          meta?.className,
+                        )}
+                      >
+                        <table.FlexRender cell={cell} />
+                      </TableCell>
+                    )
+                  })}
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-between gap-3 border-t px-4 py-2.5 text-xs text-muted-foreground">
+        <span className="tabular-nums">
+          {t('table.range', {
+            from: fmt.number(from),
+            to: fmt.number(to),
+            total: fmt.number(total),
+            noun: noun ?? t('table.results'),
+          })}
+        </span>
+        <div className="flex items-center gap-3">
+          <div className="hidden items-center gap-2 sm:flex">
+            <span>{t('table.rows')}</span>
+            <Select
+              items={PAGE_SIZES.map((n) => ({ value: n, label: String(n) }))}
+              value={pagination.pageSize}
+              onValueChange={(value) => value != null && table.setPageSize(Number(value))}
+            >
+              <SelectTrigger size="sm" aria-label={t('table.rowsPerPage')}>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {PAGE_SIZES.map((n) => (
+                  <SelectItem key={n} value={n}>
+                    {n}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <span className="tabular-nums">
+            {t('table.page', { page: pagination.pageIndex + 1, count: pageCount })}
+          </span>
+          <div className="flex items-center gap-1">
+            <Button
+              variant="outline"
+              size="icon-sm"
+              aria-label={t('table.previousPage')}
+              disabled={!table.getCanPreviousPage()}
+              onClick={() => table.previousPage()}
+            >
+              <ChevronLeft />
+            </Button>
+            <Button
+              variant="outline"
+              size="icon-sm"
+              aria-label={t('table.nextPage')}
+              disabled={!table.getCanNextPage()}
+              onClick={() => table.nextPage()}
+            >
+              <ChevronRight />
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/template/src/core/components/data-table/features.ts

@@ -0,0 +1,24 @@
+import {
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+  type ColumnDef,
+  type RowData,
+} from '@tanstack/react-table'
+
+/** Features every DataTable registers. Build module columns with this type. */
+export const dataTableFeatures = tableFeatures({ rowSortingFeature, rowPaginationFeature, rowSelectionFeature })
+export type DataTableFeatures = typeof dataTableFeatures
+
+export type DataTableColumn<TData extends RowData> = ColumnDef<DataTableFeatures, TData, any> // eslint-disable-line @typescript-eslint/no-explicit-any
+
+declare module '@tanstack/react-table' {
+  // Per-column layout hints read by DataTable.
+  interface ColumnMeta<TFeatures, TData, TValue> {
+    align?: 'left' | 'right'
+    className?: string
+    /** Hide below the sm breakpoint. */
+    hideOnMobile?: boolean
+  }
+}

package/template/src/core/components/data-table/table-header-cell.tsx

@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react'
+
+import { TableHead } from '@/components/ui/table'
+import { cn } from '@/lib/utils'
+
+/**
+ * Header cell in the shared table style: small uppercase label on a subtle
+ * fill, with the outer cells aligned to the card padding. Used by DataTable
+ * and by small static tables (roles matrix, sign-in history).
+ */
+export function TableHeaderCell({ className, ...props }: ComponentProps<typeof TableHead>) {
+  return <TableHead className={cn('label-caps h-10 bg-fill-1 first:pl-4 last:pr-4', className)} {...props} />
+}

package/template/src/core/components/data-table/toolbar.tsx

@@ -0,0 +1,100 @@
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Search, X } from 'lucide-react'
+
+import { Button } from '@/components/ui/button'
+import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/ui/input-group'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+
+/** Debounced search box. Keeps typing snappy while the URL/query updates lazily. */
+export function TableSearch({
+  value,
+  onChange,
+  placeholder,
+}: {
+  value: string
+  onChange: (value: string) => void
+  placeholder?: string
+}) {
+  const { t } = useTranslation()
+  const label = placeholder ?? t('table.search')
+  const [draft, setDraft] = useState(value)
+  const [synced, setSynced] = useState(value)
+
+  // Adopt outside changes (e.g. "Clear filters") without an effect.
+  if (value !== synced) {
+    setSynced(value)
+    setDraft(value)
+  }
+
+  useEffect(() => {
+    if (draft === value) return
+    const t = setTimeout(() => onChange(draft), 300)
+    return () => clearTimeout(t)
+  }, [draft, value, onChange])
+
+  return (
+    <InputGroup className="w-full sm:w-64">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput
+        type="search"
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        placeholder={label}
+        aria-label={label}
+      />
+    </InputGroup>
+  )
+}
+
+export type FilterOption = { value: string; label: string }
+
+/** Single-value filter. Selecting the "All …" entry clears the filter. */
+export function FilterSelect({
+  label,
+  allLabel,
+  value,
+  options,
+  onChange,
+}: {
+  /** Accessible name, e.g. "Status". */
+  label: string
+  /** First entry, clears the filter, e.g. "All statuses". */
+  allLabel: string
+  value: string | undefined
+  options: FilterOption[]
+  onChange: (value: string | undefined) => void
+}) {
+  const ALL = '__all'
+  const items = [{ value: ALL, label: allLabel }, ...options]
+  return (
+    <Select
+      items={items}
+      value={value ?? ALL}
+      onValueChange={(next) => onChange(next === ALL || next == null ? undefined : String(next))}
+    >
+      <SelectTrigger aria-label={label} className="min-w-36">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {items.map((o) => (
+          <SelectItem key={o.value} value={o.value}>
+            {o.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  )
+}
+
+export function ClearFiltersButton({ onClick }: { onClick: () => void }) {
+  const { t } = useTranslation()
+  return (
+    <Button variant="ghost" onClick={onClick}>
+      <X data-icon="inline-start" />
+      {t('actions.clear')}
+    </Button>
+  )
+}

package/template/src/core/components/data-table/use-list-url-state.ts

@@ -0,0 +1,108 @@
+import { useCallback, useMemo } from 'react'
+import { useSearchParams } from 'react-router'
+import type { OnChangeFn, PaginationState, SortingState, Updater } from '@tanstack/react-table'
+
+import type { ListParams } from '@/core/api/types'
+
+const resolve = <T,>(updater: Updater<T>, prev: T): T =>
+  typeof updater === 'function' ? (updater as (p: T) => T)(prev) : updater
+
+/**
+ * Keeps list state (page, size, sort, search, filters) in the URL so lists are
+ * shareable, survive refresh and work with the browser back button.
+ *   ?page=2&size=20&sort=price.desc&q=lamp&status=active
+ */
+export function useListUrlState<TFilterKey extends string>({
+  filterKeys,
+  defaultPageSize = 10,
+  defaultSort,
+}: {
+  filterKeys: readonly TFilterKey[]
+  defaultPageSize?: number
+  defaultSort?: SortingState[number]
+}) {
+  const [params, setParams] = useSearchParams()
+
+  const page = Math.max(1, Number(params.get('page')) || 1)
+  const pageSize = Number(params.get('size')) || defaultPageSize
+  const search = params.get('q') ?? ''
+  const sortParam = params.get('sort')
+
+  const pagination = useMemo<PaginationState>(() => ({ pageIndex: page - 1, pageSize }), [page, pageSize])
+
+  const sorting = useMemo<SortingState>(() => {
+    if (sortParam === '') return []
+    if (!sortParam) return defaultSort ? [defaultSort] : []
+    const [id, dir] = sortParam.split('.')
+    return id ? [{ id, desc: dir === 'desc' }] : []
+  }, [sortParam, defaultSort])
+
+  const filterString = filterKeys.map((k) => params.get(k) ?? '').join('|')
+  const filters = useMemo(() => {
+    const values = filterString.split('|')
+    return Object.fromEntries(filterKeys.map((k, i) => [k, values[i] || undefined])) as Record<
+      TFilterKey,
+      string | undefined
+    >
+  }, [filterString, filterKeys])
+
+  const update = useCallback(
+    (patch: Record<string, string | number | undefined>, resetPage = true) => {
+      setParams(
+        (prev) => {
+          const next = new URLSearchParams(prev)
+          for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined || value === '') next.delete(key)
+            else next.set(key, String(value))
+          }
+          if (resetPage && !('page' in patch)) next.delete('page')
+          return next
+        },
+        { replace: true },
+      )
+    },
+    [setParams],
+  )
+
+  const onPaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    const next = resolve(updater, pagination)
+    update(
+      {
+        page: next.pageIndex > 0 ? next.pageIndex + 1 : undefined,
+        size: next.pageSize !== defaultPageSize ? next.pageSize : undefined,
+      },
+      next.pageSize !== pagination.pageSize,
+    )
+  }
+
+  const onSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const [first] = resolve(updater, sorting)
+    // '' = explicitly unsorted (distinct from "use the default sort").
+    update({ sort: first ? `${first.id}.${first.desc ? 'desc' : 'asc'}` : '' })
+  }
+
+  const listParams = useMemo<ListParams<Record<TFilterKey, string | undefined>>>(
+    () => ({
+      page,
+      pageSize,
+      search: search || undefined,
+      sort: sorting[0] ? { field: sorting[0].id, direction: sorting[0].desc ? 'desc' : 'asc' } : undefined,
+      filters,
+    }),
+    [page, pageSize, search, sorting, filters],
+  )
+
+  return {
+    pagination,
+    sorting,
+    search,
+    filters,
+    listParams,
+    onPaginationChange,
+    onSortingChange,
+    setSearch: (q: string) => update({ q }),
+    setFilter: (key: TFilterKey, value: string | undefined) => update({ [key]: value }),
+    clearAll: () => update({ q: undefined, sort: undefined, ...Object.fromEntries(filterKeys.map((k) => [k, undefined])) }),
+    hasActiveFilters: Boolean(search) || Object.values(filters).some(Boolean),
+  }
+}