@softize/opus 8.6.6

package/src/ui/components/patterns/list.tsx

@@ -0,0 +1,1488 @@
+/**
+ * <ActionList action input /> — a listagem padronizada de uma ListAction do Opus.
+ *
+ * DECLARATIVO PELO CONTRATO (a diagramação da casa): o contrato descreve e a UI deriva —
+ * - `columns` (ListColumnSpec) → tabela com tipos (text/number/date/badge), `fit`,
+ *   `hidden` e headers ordenáveis (`sortable` → `sort: '<key>:<dir>'` no input; o
+ *   handler implementa o orderBy). Células custom entram por cima via `cells`.
+ * - `filters` (FilterSpec) → toolbar: os não-avançados inline; os `advanced: true` no
+ *   modal "Filtros" (contador de ativos no botão). Aplicados viram CHIPS removíveis.
+ * - `text` → caixa de busca (convenção: param `q` no input).
+ * - `sort.default` → ordenação inicial.
+ *
+ * Estado da toolbar: interno por padrão; controlado via `state`/`onStateChange` (pra
+ * quem embala sincronizar com a URL). O `input` da prop é o ESCOPO BASE (ex.:
+ * { workspaceId }) — a toolbar soma por cima e nunca o sobrescreve.
+ *
+ * Modos de render: tabela derivada (default) · `columns` prop (tabela explícita,
+ * legado) · children `(items, refetch) => nó` (layout livre; a toolbar continua).
+ * Empty/loading/error padronizados. `data-action` na raiz (selector E2E).
+ */
+
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { ArrowDown, ArrowUp, ArrowUpDown, Calendar as CalendarIcon, ChevronLeft, ChevronRight, Eraser, RefreshCw, Settings2, SlidersHorizontal, Table2, X } from 'lucide-react'
+import type {
+  ActionDef,
+  FilterSpec,
+  Paginated,
+  PeriodSpec,
+  ListAction,
+  ListColumnSpec,
+  SortSpec,
+} from '../../../core/index.ts'
+import { useDicts, useListAction, useLookupAction, type DictLike } from '../../drivers/react.tsx'
+import { cn } from '../../lib/cn.ts'
+import { Badge } from '../primitives/badge.tsx'
+import { Button } from '../primitives/button.tsx'
+import { Calendar } from '../primitives/calendar.tsx'
+import { Checkbox } from '../primitives/checkbox.tsx'
+import { Popover, PopoverContent, PopoverTrigger } from '../primitives/popover.tsx'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../primitives/dialog.tsx'
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '../primitives/alert-dialog.tsx'
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '../primitives/input-group.tsx'
+import { Separator } from '../primitives/separator.tsx'
+import { Label } from '../primitives/label.tsx'
+import { Search } from 'lucide-react'
+import { Select, type SelectOption } from '../primitives/select.tsx'
+import { Skeleton } from '../primitives/skeleton.tsx'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../primitives/table.tsx'
+import { ToggleGroup, ToggleGroupItem } from '../primitives/toggle-group.tsx'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** I18nRef ({ key, default }) | string → texto. */
+function text(m: unknown, fallback = ''): string {
+  if (typeof m === 'string') return m
+  if (m !== null && typeof m === 'object' && 'default' in m) {
+    const d = (m as { default: unknown }).default
+    if (typeof d === 'string') return d
+  }
+  return fallback
+}
+
+function isEmptyValue(v: unknown): boolean {
+  return v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0)
+}
+
+// =============================================================================
+// Tipos públicos
+// =============================================================================
+
+export interface ActionListColumn<TItem> {
+  /** Identifica a coluna (usado como key React). */
+  key: string
+  /** Cabeçalho da coluna. */
+  header: string
+  /** Renderiza o conteúdo da célula a partir do item. */
+  cell: (item: TItem) => ReactNode
+  /** Largura opcional (CSS class). */
+  className?: string
+  /** Header clicável (asc ↔ desc) — escreve `sort` no input. */
+  sortable?: boolean
+}
+
+/** Estado da toolbar (busca + sort + filtros + período + view + colunas visíveis).
+ *  Controlável de fora pra URL sync — ver listParamsToState/listStateToParams. */
+export interface ActionListState {
+  q: string
+  sort: SortSpec | null
+  filters: Record<string, unknown>
+  /** Período ativo: o value de um preset do contrato, ou 'custom'. null = o DEFAULT do
+   *  contrato (período é recorte obrigatório — não existe "sem período" quando o
+   *  contrato declara `periods`). Preset fica RELATIVO na URL; materializa no fetch. */
+  period: string | null
+  /** Range do período 'custom' (YYYY-MM-DD). */
+  from: string | null
+  to: string | null
+  /** View ativa ('table' ou uma chave de `views`). null = a default. */
+  view: string | null
+  /** Colunas visíveis (config de exibição). null = o default do contrato (não-hidden). */
+  columns: string[] | null
+  /** Itens por página (config de exibição). null = o `pageSize` do caller. */
+  limit: number | null
+  /** Página atual (1-based). Mudar filtro/busca/sort/período volta pra 1. */
+  page: number
+}
+
+/** Um estado vazio/default — útil pra montar o inicial em quem controla. */
+export function emptyListState(): ActionListState {
+  return { q: '', sort: null, filters: {}, period: null, from: null, to: null, view: null, columns: null, limit: null, page: 1 }
+}
+
+/** Presets de período que o pattern sabe COMPUTAR (o contrato escolhe quais oferecer
+ *  via `periods`; o valor materializa em `from`/`to` — YYYY-MM-DD — no fetch). */
+export function presetRange(preset: string, now = new Date()): { from: string; to: string } | null {
+  const iso = (d: Date): string =>
+    `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+  const shift = (days: number): Date => new Date(now.getFullYear(), now.getMonth(), now.getDate() + days)
+  switch (preset) {
+    case 'today':
+      return { from: iso(shift(0)), to: iso(shift(0)) }
+    case 'yesterday':
+      return { from: iso(shift(-1)), to: iso(shift(-1)) }
+    case 'last7':
+      return { from: iso(shift(-6)), to: iso(shift(0)) }
+    case 'last30':
+      return { from: iso(shift(-29)), to: iso(shift(0)) }
+    case 'thisMonth':
+      return { from: iso(new Date(now.getFullYear(), now.getMonth(), 1)), to: iso(shift(0)) }
+    case 'lastMonth':
+      return {
+        from: iso(new Date(now.getFullYear(), now.getMonth() - 1, 1)),
+        to: iso(new Date(now.getFullYear(), now.getMonth(), 0)),
+      }
+    default:
+      return null
+  }
+}
+
+/** Estrutural de propósito (como o useListAction): aceita o CONTRATO compartilhado
+ *  (sem handler) e a action completa — só o que a UI deriva importa aqui. */
+export interface ListActionLike {
+  name: string
+  kind: 'list'
+  columns?: ListColumnSpec[] | undefined
+  filters?: Record<string, FilterSpec> | undefined
+  sort?: { fields: string[]; default?: SortSpec[] } | undefined
+  text?: { fields: string[]; placeholder?: unknown } | undefined
+  periods?: PeriodSpec[] | undefined
+}
+
+/** Uma view alternativa da MESMA listagem (board, galeria, lista, calendário…). A
+ *  apresentação é de quem chama; o pattern dá o segment, o estado e os dados. */
+export interface ActionListView<TItem> {
+  label: string
+  /** Ícone do segment (icon-only, com o label em title/aria). Sem ele, o label vira texto. */
+  icon?: ReactNode
+  render: (items: TItem[], refetch: () => Promise<void>) => ReactNode
+}
+
+/** Ação em lote sobre os selecionados. `can` é a FONTE ÚNICA de elegibilidade: governa
+ *  o checkbox da linha, a coluna de seleção inteira e o que chega no `run` (só os
+ *  elegíveis). Sem `can` = todo item é elegível. */
+export interface ActionListBatchAction<TItem> {
+  label: string
+  /** Elegibilidade por item. */
+  can?: (item: TItem) => boolean
+  /** Roda sobre os selecionados ELEGÍVEIS; ao resolver, a seleção limpa e a lista refaz. */
+  run: (items: TItem[]) => Promise<void> | void
+  /** Confirmação antes de rodar. */
+  confirm?: { title: string; message?: string }
+  destructive?: boolean
+}
+
+export interface ActionListProps<TInput, TItem> {
+  action: ListActionLike
+  /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
+  input: TInput
+  /** Tabela explícita — sobrepõe as colunas do contrato. */
+  columns?: ActionListColumn<TItem>[]
+  /** Células custom POR CIMA das colunas do contrato (chave = column.key). */
+  cells?: Record<string, (item: TItem) => ReactNode>
+  /** Opções de runtime pros filtros select/lookup (chave = nome do filtro). */
+  filterOptions?: Record<string, SelectOption[]>
+  /** Views alternativas da mesma listagem — o segment na toolbar alterna entre a
+   *  tabela ('table', quando há columns) e estas. Ex.: { board: { label, render } }. */
+  views?: Record<string, ActionListView<TItem>>
+  /** Ações em lote (multi-seleção com `can`) — liga a coluna de checkbox na tabela. */
+  batch?: ActionListBatchAction<TItem>[]
+  /** Identidade da linha pra seleção. Default: `item.id`. */
+  rowId?: (item: TItem) => string
+  /** Itens por página (o pattern manda `limit` e `page` no input; o handler implementa
+   *  o OFFSET e devolve `total`). O rodapé mostra o total e o pager quando transborda. */
+  pageSize?: number
+  /** Mensagem de empty state. Default: "Nenhum resultado." */
+  emptyMessage?: string
+  /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto conta
+   *  como conteúdo, então os children devem renderizar mesmo com a lista vazia. */
+  empty?: (items: TItem[]) => boolean
+  /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
+  loading?: boolean
+  /** Click handler por linha (ex: navegar pro detalhe) — só na tabela. */
+  onRowClick?: (item: TItem) => void
+  /** Ações POR LINHA (coluna final, alinhada à direita) — apresentação de quem chama,
+   *  como `cells`. Cliques ali não disparam o onRowClick. Só na tabela. */
+  rowActions?: (item: TItem) => ReactNode
+  /** Modo COMPOSIÇÃO: layout livre ÚNICO (sem segment); toolbar e estados seguem. */
+  children?: (items: TItem[], refetch: () => Promise<void>) => ReactNode
+  /** Estado da toolbar CONTROLADO (URL sync de quem embala). Default: interno. */
+  state?: ActionListState
+  onStateChange?: (next: ActionListState) => void
+}
+
+// =============================================================================
+// Filtro (leaf) — um campo da toolbar/modal, derivado do FilterSpec
+// =============================================================================
+
+function optionsFor(name: string, spec: FilterSpec, runtime?: Record<string, SelectOption[]>): SelectOption[] {
+  const fromRuntime = runtime?.[name]
+  if (fromRuntime !== undefined) return fromRuntime
+  if (spec.options?.kind === 'static') {
+    return spec.options.items.map((i) => ({ value: i.value, label: text(i.label, i.value) }))
+  }
+  return []
+}
+
+/** Opções de `options: { kind: 'dictionary', ref }` via dicts do provider. */
+function dictOptionsFor(spec: FilterSpec, dicts: Record<string, DictLike>): SelectOption[] {
+  if (spec.options?.kind !== 'dictionary') return []
+  const dict = dicts[spec.options.ref]
+  if (dict === undefined) return []
+  return dict.options().map((o) => ({ value: o.value, label: o.label }))
+}
+
+/** Opções vindas de uma action de lookup (`options.kind: 'lookup'`): o Select chama
+ *  `onSearch` (debounced) e a action `source` devolve itens `{ value, label }` — a
+ *  convenção do lookup declarativo. Os `depends` entram no input da busca. */
+function useLookupOptions(
+  spec: FilterSpec,
+  allValues: Record<string, unknown>,
+): { options: SelectOption[]; loading: boolean; onSearch?: (q: string) => void } {
+  const lookup = spec.options?.kind === 'lookup' ? spec.options : undefined
+  const search = useLookupAction<Record<string, unknown>, SelectOption>(
+    { name: lookup?.source ?? 'noop', kind: 'list' } as unknown as ActionDef,
+  )
+  if (lookup === undefined) return { options: [], loading: false }
+  const depInput: Record<string, unknown> = {}
+  for (const d of lookup.depends ?? []) {
+    if (!isEmptyValue(allValues[d])) depInput[d] = allValues[d]
+  }
+  return {
+    options: (search.items ?? []).map((i) => ({ value: i.value, label: i.label })),
+    loading: search.isLoading,
+    onSearch: (q: string) => {
+      void search.run({ ...(q !== '' ? { q } : {}), ...depInput })
+    },
+  }
+}
+
+function FilterField({
+  name,
+  spec,
+  value,
+  onChange,
+  options,
+  allValues,
+  className,
+}: {
+  name: string
+  spec: FilterSpec
+  value: unknown
+  onChange: (v: unknown) => void
+  options: SelectOption[]
+  /** Todos os valores de filtro vigentes — habilita `depends` e alimenta o lookup. */
+  allValues: Record<string, unknown>
+  /** Largura do contexto: a toolbar usa os defaults compactos; o modal manda w-full. */
+  className?: string
+}): React.ReactElement {
+  const label = text(spec.label, name)
+  const placeholder = text(spec.placeholder, label)
+  // Dependência não satisfeita = controle desabilitado (o valor cascateia fora no pai).
+  const enabled = (spec.depends ?? []).every((d) => !isEmptyValue(allValues[d]))
+  const lookup = useLookupOptions(spec, allValues)
+  const dicts = useDicts()
+  // Precedência: runtime/estáticas (prop `options`) > dictionary do provider;
+  // sem nenhuma, as do lookup (server-side).
+  const base = options.length > 0 ? options : dictOptionsFor(spec, dicts)
+  const effOptions = base.length > 0 ? base : lookup.options
+
+  if (spec.multiple === true) {
+    return (
+      <Select
+        multiple
+        searchable
+        clearable
+        id={`filter-${name}`}
+        value={(value as string[] | undefined) ?? []}
+        onChange={(v) => onChange(v)}
+        options={effOptions}
+        placeholder={placeholder}
+        className={cn('min-w-44', className)}
+        disabled={!enabled}
+        {...(lookup.onSearch !== undefined ? { onSearch: lookup.onSearch, loading: lookup.loading } : {})}
+      />
+    )
+  }
+  if (spec.type === 'lookup') {
+    // Lookup é typeahead por natureza: Select searchable single (server-side quando a origem
+    // é uma action; client quando as opções vieram estáticas/de runtime).
+    return (
+      <Select
+        searchable
+        clearable
+        id={`filter-${name}`}
+        value={(value as string | undefined) ?? ''}
+        onChange={(v) => onChange(v)}
+        options={effOptions}
+        placeholder={placeholder}
+        className={cn('min-w-44', className)}
+        disabled={!enabled}
+        {...(lookup.onSearch !== undefined ? { onSearch: lookup.onSearch, loading: lookup.loading } : {})}
+      />
+    )
+  }
+  if (spec.type === 'select') {
+    // "Todos" é o valor-vazio EXPLÍCITO (limpa o filtro por dentro, sem chip); o
+    // `clearable` dá o mesmo destino num clique, sem abrir a lista.
+    const ALL = '__all__'
+    return (
+      <Select
+        clearable
+        id={`filter-${name}`}
+        value={((value as string | undefined) ?? '') === '' ? ALL : (value as string)}
+        onChange={(v) => onChange(v === ALL ? '' : v)}
+        options={[{ value: ALL, label: text(spec.placeholder, 'Todos') }, ...base]}
+        disabled={!enabled}
+        className={cn('min-w-36', className)}
+      />
+    )
+  }
+  // text · number · date: aplica no blur/Enter (texto) ou no change (date).
+  const type = spec.type === 'number' ? 'number' : spec.type === 'date' ? 'date' : 'text'
+  return (
+    <ClearableInput
+      id={`filter-${name}`}
+      type={type}
+      applied={(value as string | undefined) ?? ''}
+      placeholder={placeholder}
+      className={cn('w-40', className)}
+      disabled={!enabled}
+      onApply={(v) => onChange(v)}
+    />
+  )
+}
+
+/** Input com limpar (a receita clearable dos textos): Input/InputGroup são locked, o X
+ *  entra por composição — addon à direita, visível só com texto. Uncontrolled (aplica
+ *  no blur/Enter, como a busca); o X zera o campo E aplica o vazio. */
+function ClearableInput({
+  id,
+  type,
+  applied,
+  placeholder,
+  className,
+  leading,
+  disabled,
+  onApply,
+}: {
+  id?: string
+  type?: string
+  applied: string
+  placeholder?: string
+  className?: string
+  /** Addon à esquerda (ex.: a lupa da busca). */
+  leading?: ReactNode
+  disabled?: boolean
+  onApply: (v: string) => void
+}): React.ReactElement {
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const [hasText, setHasText] = useState(applied !== '')
+  // Valor aplicado mudou por fora (chip removido, URL) → re-sincroniza o campo.
+  useEffect(() => {
+    if (inputRef.current !== null && inputRef.current.value !== applied) inputRef.current.value = applied
+    setHasText(applied !== '')
+  }, [applied])
+  return (
+    <InputGroup className={className}>
+      {leading !== undefined && <InputGroupAddon>{leading}</InputGroupAddon>}
+      <InputGroupInput
+        ref={inputRef}
+        id={id}
+        type={type}
+        className="h-full"
+        disabled={disabled}
+        defaultValue={applied}
+        placeholder={placeholder}
+        onChange={(e) => setHasText(e.target.value !== '')}
+        onBlur={(e) => {
+          if (e.target.value !== applied) onApply(e.target.value)
+        }}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            e.preventDefault()
+            onApply((e.target as HTMLInputElement).value)
+          }
+        }}
+      />
+      {hasText && (
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton
+            aria-label="Limpar"
+            onClick={() => {
+              if (inputRef.current !== null) inputRef.current.value = ''
+              setHasText(false)
+              onApply('')
+            }}
+          >
+            <X className="size-3.5" />
+          </InputGroupButton>
+        </InputGroupAddon>
+      )}
+    </InputGroup>
+  )
+}
+
+/** Janela de páginas do pager: vizinhas da atual + pontas, com reticências nos vãos. */
+function pageWindow(current: number, pages: number): Array<number | '…'> {
+  if (pages <= 7) return Array.from({ length: pages }, (_, i) => i + 1)
+  const wanted = new Set<number>([1, 2, 3, current - 1, current, current + 1, pages])
+  const nums = Array.from(wanted)
+    .filter((n) => n >= 1 && n <= pages)
+    .sort((a, b) => a - b)
+  const out: Array<number | '…'> = []
+  for (const [i, n] of nums.entries()) {
+    if (i > 0 && n - (nums[i - 1] as number) > 1) out.push('…')
+    out.push(n)
+  }
+  return out
+}
+
+/** Label pequena ACIMA do controle — o estilo da toolbar (Período, Status, …). */
+function Labeled({
+  label,
+  children,
+  slot,
+}: {
+  label: string
+  children: ReactNode
+  /** data-slot do wrapper (ex.: marca os filtros inline pro overflow responsivo). */
+  slot?: string
+}): React.ReactElement {
+  return (
+    <div data-slot={slot} className="flex shrink-0 flex-col gap-1">
+      <span className="px-0.5 text-xs font-medium text-muted-foreground">{label}</span>
+      {children}
+    </div>
+  )
+}
+
+// =============================================================================
+// Período — o campo dinâmico: presets num popover; "Personalizado" abre o calendário
+// de range ali mesmo. Fica INLINE na toolbar (não é filtro avançado).
+// =============================================================================
+
+function fmtDay(isoDay: string): string {
+  const [y, m, d] = isoDay.split('-')
+  return `${d}/${m}/${y?.slice(2)}`
+}
+
+function PeriodControl({
+  periods,
+  period,
+  from,
+  to,
+  onChange,
+}: {
+  periods: PeriodSpec[]
+  period: string | null
+  from: string | null
+  to: string | null
+  onChange: (next: { period: string | null; from: string | null; to: string | null }) => void
+}): React.ReactElement {
+  const [open, setOpen] = useState(false)
+  const [showCalendar, setShowCalendar] = useState(period === 'custom')
+  // Seleção em duas pontas na MÃO (onDayClick), fora da lógica de range do
+  // react-day-picker: com o range vigente pré-selecionado, o RDP estenderia a
+  // seleção antiga em vez de começar outra — e ele devolve from E to já no
+  // primeiro clique. Sem draft = mostra o range vigente; o primeiro clique
+  // abre a ponta inicial; o segundo completa, aplica e fecha.
+  const [draft, setDraft] = useState<{ from: Date | undefined; to?: Date | undefined } | undefined>(undefined)
+
+  const label =
+    period === 'custom'
+      ? from !== null && to !== null
+        ? `${fmtDay(from)} – ${fmtDay(to)}`
+        : 'Personalizado'
+      : text(periods.find((p) => p.value === period)?.label, period ?? '')
+
+  const parseDay = (v: string | null): Date | undefined => {
+    if (v === null) return undefined
+    const [y, m, d] = v.split('-').map(Number)
+    return new Date(y ?? 0, (m ?? 1) - 1, d ?? 1)
+  }
+  const toDay = (d: Date): string =>
+    `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(o) => {
+        setOpen(o)
+        if (o) {
+          setShowCalendar(period === 'custom')
+          setDraft(undefined)
+        }
+      }}
+    >
+      <PopoverTrigger asChild>
+        <Button variant="outline" data-slot="action-list-period">
+          <CalendarIcon className="h-3.5 w-3.5" />
+          {label}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-auto p-0">
+        <div className="flex">
+          <div className={cn('flex min-w-36 flex-col gap-0.5 p-2', showCalendar && 'border-r border-border')}>
+            {periods.map((p) => (
+              <Button
+                key={p.value}
+                size="sm"
+                variant={period === p.value ? 'secondary' : 'ghost'}
+                className="justify-start"
+                onClick={() => {
+                  onChange({ period: p.value, from: null, to: null })
+                  setOpen(false)
+                }}
+              >
+                {text(p.label, p.value)}
+              </Button>
+            ))}
+            <Button
+              size="sm"
+              variant={period === 'custom' ? 'secondary' : 'ghost'}
+              className="justify-start"
+              onClick={() => {
+                setShowCalendar(true)
+                setDraft(undefined)
+              }}
+            >
+              Personalizado
+            </Button>
+          </div>
+          {showCalendar && (
+            <Calendar
+              mode="range"
+              numberOfMonths={1}
+              defaultMonth={parseDay(from)}
+              selected={draft ?? { from: parseDay(from), to: parseDay(to) }}
+              // No-op de propósito: com onSelect o RDP fica CONTROLADO (renderiza o
+              // nosso `selected`); sem ele, mantém seleção interna e mostra o range
+              // antigo estendido no meio da escolha.
+              onSelect={() => undefined}
+              onDayClick={(day) => {
+                if (draft?.from !== undefined && draft.to === undefined) {
+                  // Segunda ponta (qualquer ordem): completa, aplica e fecha.
+                  const [a, b] = day < draft.from ? [day, draft.from] : [draft.from, day]
+                  onChange({ period: 'custom', from: toDay(a), to: toDay(b) })
+                  setOpen(false)
+                } else {
+                  setDraft({ from: day, to: undefined })
+                }
+              }}
+            />
+          )}
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+// =============================================================================
+// Modal de filtros avançados — draft local; Aplicar/Limpar
+// =============================================================================
+
+function AdvancedFiltersDialog({
+  open,
+  onOpenChange,
+  specs,
+  values,
+  onApply,
+  filterOptions,
+  cascade,
+}: {
+  open: boolean
+  onOpenChange: (o: boolean) => void
+  specs: Array<[string, FilterSpec]>
+  values: Record<string, unknown>
+  onApply: (next: Record<string, unknown>) => void
+  filterOptions?: Record<string, SelectOption[]> | undefined
+  /** A cascata do `depends` do pai — mudar um campo limpa os dependentes no draft. */
+  cascade: (changed: string, next: Record<string, unknown>) => Record<string, unknown>
+}): React.ReactElement {
+  const [draft, setDraft] = useState<Record<string, unknown>>(values)
+  // Reabriu → re-sincroniza o draft com o aplicado.
+  useEffect(() => {
+    if (open) setDraft(values)
+  }, [open, values])
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      {/* Estreito de propósito (form de filtros, campos em coluna full width); sem
+          subtítulo — o título basta (aria-describedby explícito cala o aviso do Radix). */}
+      <DialogContent className="sm:max-w-sm" aria-describedby={undefined}>
+        <DialogHeader>
+          <DialogTitle>Filtros</DialogTitle>
+        </DialogHeader>
+        <DialogBody className="space-y-4">
+          {specs.map(([name, spec]) => (
+            <div key={name} className="space-y-2">
+              <Label htmlFor={`filter-${name}`}>{text(spec.label, name)}</Label>
+              <FilterField
+                name={name}
+                spec={spec}
+                value={draft[name]}
+                allValues={draft}
+                className="w-full"
+                onChange={(v) => setDraft((d) => cascade(name, { ...d, [name]: v }))}
+                options={optionsFor(name, spec, filterOptions)}
+              />
+            </div>
+          ))}
+        </DialogBody>
+        <DialogFooter>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => {
+              const cleared = { ...draft }
+              for (const [name] of specs) delete cleared[name]
+              onApply(cleared)
+              onOpenChange(false)
+            }}
+          >
+            Limpar
+          </Button>
+          <Button
+            size="sm"
+            onClick={() => {
+              onApply(draft)
+              onOpenChange(false)
+            }}
+          >
+            Aplicar
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+// =============================================================================
+// ActionList
+// =============================================================================
+
+export function ActionList<TInput, TItem>({
+  action,
+  input,
+  columns,
+  cells,
+  filterOptions,
+  views,
+  batch,
+  rowId = (item: TItem) => String((item as { id?: unknown }).id ?? ''),
+  pageSize = 50,
+  emptyMessage = 'Nenhum resultado.',
+  empty,
+  loading: extraLoading,
+  onRowClick,
+  rowActions,
+  children,
+  state: controlledState,
+  onStateChange,
+}: ActionListProps<TInput, TItem>) {
+  // Query-backed (useListAction): busca declarativa por [name, input] E refetch
+  // automático quando um form/trigger invalida a action (`invalidates: ['x.list']`).
+  // O input efetivo é computado abaixo; o hook re-busca quando ele muda.
+  const hasTable = columns !== undefined || action.columns !== undefined
+  if (children === undefined && !hasTable && views === undefined) {
+    throw new Error('ActionList precisa de children (composição), columns (prop/contrato) ou views.')
+  }
+
+  // — Estado da toolbar (interno ou controlado) —
+  const defaultSort = action.sort?.default?.[0] ?? null
+  const [internal, setInternal] = useState<ActionListState>({ ...emptyListState(), sort: defaultSort })
+  // Dicts do provider — labels de filtro dictionary nos CHIPS (o FilterField resolve os seus).
+  const dicts = useDicts()
+  // Normaliza estado externo montado à mão (chaves novas ausentes = null/default).
+  const raw = controlledState ?? internal
+  const state: ActionListState = {
+    ...raw,
+    period: raw.period ?? null,
+    from: raw.from ?? null,
+    to: raw.to ?? null,
+    view: raw.view ?? null,
+    columns: raw.columns ?? null,
+    limit: raw.limit ?? null,
+    page: raw.page ?? 1,
+  }
+  const setState = (next: ActionListState): void => {
+    if (onStateChange !== undefined) onStateChange(next)
+    if (controlledState === undefined) setInternal(next)
+  }
+  // Mudou o RECORTE (filtro/busca/sort/período), a página volta pra 1.
+  const setStateResetPage = (next: ActionListState): void => setState({ ...next, page: 1 })
+
+  const filterSpecs = Object.entries(action.filters ?? {})
+  // Mudou um filtro → limpa (em cascata) todo filtro que declara `depends` nele:
+  // o recorte dependente perde o sentido quando o pai muda.
+  const cascadeClear = (changed: string, next: Record<string, unknown>): Record<string, unknown> => {
+    for (const [n, sp] of filterSpecs) {
+      if (sp.depends?.includes(changed) === true && !isEmptyValue(next[n])) {
+        delete next[n]
+        cascadeClear(n, next)
+      }
+    }
+    return next
+  }
+  const inlineSpecs = filterSpecs.filter(([, s]) => s.advanced !== true)
+  const hasSearch = (action.text?.fields.length ?? 0) > 0
+  const [advancedOpen, setAdvancedOpen] = useState(false)
+
+  // — Overflow responsivo: filtro inline que NÃO CABE na linha vai pro modal (com os
+  //   advanced). Medição real: esconde do fim pro começo até a linha parar de
+  //   transbordar (useLayoutEffect = antes do paint, sem piscar) e re-mede no resize.
+  const toolbarRowRef = useRef<HTMLDivElement | null>(null)
+  const [inlineFit, setInlineFit] = useState(Number.POSITIVE_INFINITY)
+  useLayoutEffect(() => {
+    const row = toolbarRowRef.current
+    if (row === null) return
+    // Transborda de dois jeitos: a linha estoura (scrollWidth) OU um filho flexível
+    // (o grupo da direita, min-w-0) encolhe abaixo do conteúdo e vaza por cima dos
+    // vizinhos — esse segundo caso não mexe no scrollWidth da linha.
+    const overflowing = (): boolean =>
+      row.scrollWidth > row.clientWidth + 1 ||
+      Array.from(row.children).some((c) => c.scrollWidth > c.clientWidth + 1)
+    const compute = (): void => {
+      // Medição sempre em linha única; o wrap é o último recurso (re-avaliado abaixo).
+      row.classList.remove('flex-wrap')
+      const nodes = Array.from(row.querySelectorAll<HTMLElement>('[data-slot="action-list-inline-filter"]'))
+      for (const n of nodes) n.style.removeProperty('display')
+      let count = nodes.length
+      while (count > 0 && overflowing()) {
+        count -= 1
+        const node = nodes[count]
+        if (node !== undefined) node.style.display = 'none'
+      }
+      // Esgotou (zero filtros na linha) e AINDA não cabe → quebra a linha em vez de
+      // recortar controle (busca no mínimo + segment + botões > largura disponível).
+      if (count === 0 && overflowing()) row.classList.add('flex-wrap')
+      setInlineFit(count >= nodes.length ? Number.POSITIVE_INFINITY : count)
+    }
+    compute()
+    const ro = new ResizeObserver(compute)
+    ro.observe(row)
+    return () => ro.disconnect()
+    // inlineFit na dep: o setInlineFit pode fazer o botão "Filtros" aparecer e
+    // mudar a medida — o compute é idempotente, então re-rodar converge (sem loop).
+  }, [inlineSpecs.length, state.filters, inlineFit])
+  const overflowSpecs = Number.isFinite(inlineFit) ? inlineSpecs.slice(inlineFit) : []
+  // O modal recebe os advanced + os inline que transbordaram (ordem do contrato).
+  const modalSpecs = filterSpecs.filter(
+    ([name, s]) => s.advanced === true || overflowSpecs.some(([n]) => n === name),
+  )
+  const modalActive = modalSpecs.filter(([name]) => !isEmptyValue(state.filters[name])).length
+
+  // — Views: 'table' (quando há colunas) + as nomeadas. O segment só existe com 2+. —
+  const viewEntries: Array<[string, string, ReactNode?]> = [
+    ...(hasTable ? ([['table', 'Tabela', <Table2 key="t" />]] as Array<[string, string, ReactNode?]>) : []),
+    ...Object.entries(views ?? {}).map(([key, v]) => [key, v.label, v.icon] as [string, string, ReactNode?]),
+  ]
+  const activeView = state.view ?? viewEntries[0]?.[0] ?? 'table'
+  const hasSegment = children === undefined && viewEntries.length > 1
+  const periods = action.periods ?? []
+  // Período é recorte obrigatório: o default é o preset marcado (ou o primeiro).
+  const defaultPeriod = periods.find((p) => p.default === true)?.value ?? periods[0]?.value ?? null
+  const activePeriod = state.period ?? defaultPeriod
+  const hasToolbar = hasSearch || filterSpecs.length > 0 || periods.length > 0 || hasSegment || hasTable
+
+  // — Input efetivo: escopo base + filtros preenchidos + período (→ from/to) + q + sort —
+  const effectiveInput = useMemo(() => {
+    const filled: Record<string, unknown> = {}
+    for (const [name, v] of Object.entries(state.filters)) {
+      if (!isEmptyValue(v)) filled[name] = v
+    }
+    // Período: preset materializa AQUI (a URL guarda o preset relativo); custom usa o
+    // range. state.period null = o default do contrato (sempre aplicado).
+    const effectivePeriod = state.period ?? (action.periods?.find((p) => p.default === true)?.value ?? action.periods?.[0]?.value ?? null)
+    let range: { from: string; to: string } | null = null
+    if (effectivePeriod === 'custom' && state.from !== null && state.to !== null) {
+      range = { from: state.from, to: state.to }
+    } else if (effectivePeriod !== null && effectivePeriod !== 'custom') {
+      range = presetRange(effectivePeriod)
+    }
+    return {
+      ...(input as Record<string, unknown>),
+      ...filled,
+      ...(range !== null ? range : {}),
+      ...(state.q.trim() !== '' ? { q: state.q.trim() } : {}),
+      ...(state.sort !== null ? { sort: `${state.sort.field}:${state.sort.dir}` } : {}),
+      // Paginação server-driven: o handler implementa OFFSET e devolve `total`.
+      limit: state.limit ?? pageSize,
+      page: state.page,
+    } as TInput
+  }, [input, state, pageSize])
+
+  const inputKey = JSON.stringify(effectiveInput)
+  const { items, total, isLoading, isFetching, isError, error, refetch } = useListAction<
+    TItem,
+    Record<string, unknown>
+  >(action as unknown as { name: string; kind: 'list' }, effectiveInput as Record<string, unknown>)
+  // — Colunas: prop explícita > derivadas do contrato (+ células custom). O column
+  //   picker (state.columns) escolhe o subconjunto visível; null = o default (!hidden).
+  const visibleKeys = state.columns
+  const derived: Array<ActionListColumn<TItem> & { spec?: ListColumnSpec }> = useMemo(() => {
+    if (columns !== undefined) return columns
+    return (action.columns ?? [])
+      .filter((c) => (visibleKeys !== null ? visibleKeys.includes(c.key) : c.hidden !== true))
+      .map((c) => ({
+        key: c.key,
+        header: text(c.label, c.key),
+        sortable: c.sortable === true,
+        spec: c,
+        className: cn(
+          c.fit === true && 'w-px whitespace-nowrap',
+          c.type === 'number' && 'text-right tabular-nums',
+        ),
+        cell:
+          cells?.[c.key] ??
+          ((item: TItem): ReactNode => {
+            const v = (item as Record<string, unknown>)[c.key]
+            if (v === null || v === undefined || v === '') return null
+            if (c.type === 'date') {
+              // Date-only ('YYYY-MM-DD') parseia LOCAL — new Date() iria pra meia-noite
+              // UTC e deslocaria um dia no fuso; ISO completo segue no caminho normal.
+              const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(v))
+              const d = m !== null
+                ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
+                : new Date(String(v))
+              return new Intl.DateTimeFormat('pt-BR', c.dateFormat ?? { dateStyle: 'short' }).format(d)
+            }
+            if (c.type === 'badge') return <Badge variant="outline">{String(v)}</Badge>
+            return typeof v === 'object' ? null : String(v)
+          }),
+      }))
+  }, [columns, action.columns, cells, visibleKeys])
+
+  // — Column picker: só faz sentido na tabela derivada do contrato —
+  const pickerColumns = columns === undefined ? (action.columns ?? []) : []
+  const defaultVisible = pickerColumns.filter((c) => c.hidden !== true).map((c) => c.key)
+  const toggleColumn = (key: string): void => {
+    const current = state.columns ?? defaultVisible
+    const next = current.includes(key) ? current.filter((k) => k !== key) : [...current, key]
+    // Voltou ao default → null (URL limpa).
+    const isDefault = next.length === defaultVisible.length && defaultVisible.every((k) => next.includes(k))
+    setState({ ...state, columns: isDefault ? null : next })
+  }
+
+  const toggleSort = (key: string): void => {
+    const dir = state.sort?.field === key && state.sort.dir === 'asc' ? 'desc' : 'asc'
+    setStateResetPage({ ...state, sort: { field: key, dir } })
+  }
+
+  // — Multi-seleção (batch): `can` de QUALQUER ação torna a linha marcável; nenhuma
+  //   elegível na página → a coluna de checkbox nem aparece. Seleção é transitória
+  //   (não vai pra URL) e limpa quando o recorte/página muda ou um batch roda.
+  const batchActions = batch ?? []
+  const [selected, setSelected] = useState<Set<string>>(new Set())
+  const [running, setRunning] = useState<string | null>(null)
+  const [confirming, setConfirming] = useState<ActionListBatchAction<TItem> | null>(null)
+  const selectable = (item: TItem): boolean => batchActions.some((a) => a.can?.(item) ?? true)
+  const selectableItems = batchActions.length > 0 ? items.filter(selectable) : []
+  const hasSelection = batchActions.length > 0 && selectableItems.length > 0 && activeView === 'table'
+  useEffect(() => {
+    // Página/recorte novo → seleção limpa (os ids podem nem estar mais na tela).
+    setSelected(new Set())
+  }, [inputKey])
+  const selectedItems = items.filter((it) => selected.has(rowId(it)))
+  const eligibleFor = (a: ActionListBatchAction<TItem>): TItem[] =>
+    selectedItems.filter((it) => a.can?.(it) ?? true)
+  const runBatch = async (a: ActionListBatchAction<TItem>): Promise<void> => {
+    setRunning(a.label)
+    try {
+      await a.run(eligibleFor(a))
+      setSelected(new Set())
+      await refetch()
+    } finally {
+      setRunning(null)
+    }
+  }
+
+  // — Chips: só dos filtros DO MODAL (advanced + inline transbordado): os inline
+  //   visíveis mostram o próprio estado; os do modal ficariam invisíveis sem isto —
+  const chips = modalSpecs
+    .filter(([name]) => !isEmptyValue(state.filters[name]))
+    .map(([name, spec]) => {
+      const raw = state.filters[name]
+      // Mesma precedência do FilterField: runtime/estáticas > dictionary do provider.
+      const fromProps = optionsFor(name, spec, filterOptions)
+      const opts = fromProps.length > 0 ? fromProps : dictOptionsFor(spec, dicts)
+      const display = (v: unknown): string => opts.find((o) => o.value === v)?.label ?? String(v)
+      const value = Array.isArray(raw) ? raw.map(display).join(', ') : display(raw)
+      return { name, label: text(spec.label, name), value }
+    })
+  const clearFilter = (name: string): void => {
+    const next = { ...state.filters }
+    delete next[name]
+    setStateResetPage({ ...state, filters: next })
+  }
+
+  // A busca abre a linha SÓ quando é a única forma de recorte; com período ou
+  // filtros no contrato, o período abre e a busca fica no grupo da direita.
+  const searchFirst = hasSearch && periods.length === 0 && filterSpecs.length === 0
+  // Largura AUTO (todos os controles em default h-9, alinham nativamente):
+  // 64 com folga, encolhe até 36 no aperto — é o item flexível da linha.
+  const searchBox = hasSearch ? (
+    <ClearableInput
+      className="w-64 min-w-36"
+      leading={<Search />}
+      applied={state.q}
+      placeholder={text(action.text?.placeholder, 'Buscar…')}
+      onApply={(v) => {
+        if (v !== state.q) setStateResetPage({ ...state, q: v })
+      }}
+    />
+  ) : null
+
+  const toolbar = hasToolbar ? (
+    <div data-slot="action-list-toolbar" className="space-y-2">
+      {/* Linha única (sem wrap): a busca encolhe primeiro; depois os filtros inline
+          transbordam pro modal (medição no useLayoutEffect acima). */}
+      <div ref={toolbarRowRef} className="flex items-end gap-3">
+        {searchFirst && searchBox}
+        {periods.length > 0 && (
+          <Labeled label="Período">
+            <PeriodControl
+              periods={periods}
+              period={activePeriod}
+              from={state.from}
+              to={state.to}
+              onChange={(next) =>
+                setStateResetPage({
+                  ...state,
+                  ...next,
+                  period: next.period === defaultPeriod ? null : next.period,
+                })
+              }
+            />
+          </Labeled>
+        )}
+        {inlineSpecs.map(([name, spec]) => (
+          <Labeled key={name} label={text(spec.label, name)} slot="action-list-inline-filter">
+            <FilterField
+              name={name}
+              spec={spec}
+              value={state.filters[name]}
+              allValues={state.filters}
+              onChange={(v) =>
+                setStateResetPage({ ...state, filters: cascadeClear(name, { ...state.filters, [name]: v }) })
+              }
+              options={optionsFor(name, spec, filterOptions)}
+            />
+          </Labeled>
+        ))}
+        {modalSpecs.length > 0 && (
+          <Button variant="outline" className="shrink-0" onClick={() => setAdvancedOpen(true)}>
+            <SlidersHorizontal className="h-3.5 w-3.5" />
+            Filtros
+            {modalActive > 0 && (
+              <Badge variant="secondary" className="ml-1 h-5 min-w-5 px-1">
+                {modalActive}
+              </Badge>
+            )}
+          </Button>
+        )}
+        {/* O grupo da direita cede por min-w-0 (sem justify-end: o vazamento no
+            aperto cai pra DIREITA, onde o scrollWidth da detecção enxerga); a busca
+            aqui dentro é o item flexível — encolhe antes de filtro migrar pro modal. */}
+        <div className="ml-auto flex min-w-0 items-center gap-2">
+          {!searchFirst && searchBox}
+          {hasSegment && (
+            <ToggleGroup
+              type="single"
+              variant="outline"
+              data-slot="action-list-views"
+              className="shrink-0"
+              value={activeView}
+              onValueChange={(key) => {
+                // No single o Radix DESMARCA ao clicar no ativo (chega '') — o segment
+                // de views sempre tem uma ativa, então o vazio não passa.
+                if (key !== '') setState({ ...state, view: key === viewEntries[0]?.[0] ? null : key })
+              }}
+            >
+              {viewEntries.map(([key, label, icon]) => (
+                <Tooltip key={key}>
+                  <TooltipTrigger asChild>
+                    <ToggleGroupItem value={key} aria-label={label}>
+                      {icon ?? label}
+                    </ToggleGroupItem>
+                  </TooltipTrigger>
+                  <TooltipContent>{label}</TooltipContent>
+                </Tooltip>
+              ))}
+            </ToggleGroup>
+          )}
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="outline"
+                className="shrink-0"
+                aria-label="Recarregar"
+                onClick={() => void refetch()}
+                disabled={isLoading}
+              >
+                <RefreshCw className={cn('h-3.5 w-3.5', isLoading && 'animate-spin')} />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Recarregar</TooltipContent>
+          </Tooltip>
+          {/* Configuração de EXIBIÇÃO — sempre presente (em qualquer view): colunas quando a
+              tabela está ativa, itens por página sempre, e o que vier depois. */}
+          <Popover>
+            {/* Tooltip e PopoverTrigger compõem via asChild aninhado no MESMO botão. */}
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <PopoverTrigger asChild>
+                  <Button variant="outline" className="shrink-0" aria-label="Exibição">
+                    <Settings2 className="h-3.5 w-3.5" />
+                  </Button>
+                </PopoverTrigger>
+              </TooltipTrigger>
+              <TooltipContent>Exibição</TooltipContent>
+            </Tooltip>
+            <PopoverContent align="end" className="w-60 p-3" data-slot="action-list-display">
+              <div className="space-y-3">
+                {activeView === 'table' && pickerColumns.length > 0 && (
+                  <>
+                    <div className="space-y-2">
+                      <div className="flex items-center justify-between">
+                        <span className="text-xs font-medium text-muted-foreground">Colunas</span>
+                        {state.columns !== null && (
+                          <button
+                            type="button"
+                            onClick={() => setState({ ...state, columns: null })}
+                            className="inline-flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
+                          >
+                            <Eraser className="size-3" />
+                            Padrão
+                          </button>
+                        )}
+                      </div>
+                      <div className="space-y-1.5">
+                        {pickerColumns.map((c) => (
+                          <label key={c.key} className="flex items-center gap-2 text-sm">
+                            <Checkbox
+                              checked={(state.columns ?? defaultVisible).includes(c.key)}
+                              onCheckedChange={() => toggleColumn(c.key)}
+                            />
+                            {text(c.label, c.key)}
+                          </label>
+                        ))}
+                      </div>
+                    </div>
+                    <Separator />
+                  </>
+                )}
+                <div className="space-y-2">
+                  <span className="text-xs font-medium text-muted-foreground">Itens por página</span>
+                  <Select
+                    size="sm"
+                    className="w-full"
+                    value={String(state.limit ?? pageSize)}
+                    onChange={(v) => {
+                      const n = Number(v)
+                      // O default do caller fica FORA da URL (limit null).
+                      setState({ ...state, limit: n === pageSize ? null : n, page: 1 })
+                    }}
+                    options={Array.from(new Set([10, 25, 50, 100, pageSize]))
+                      .sort((a, b) => a - b)
+                      .map((n) => ({ value: String(n), label: String(n) }))}
+                  />
+                </div>
+              </div>
+            </PopoverContent>
+          </Popover>
+        </div>
+      </div>
+      {chips.length > 0 && (
+        <div data-slot="action-list-chips" className="flex flex-wrap items-center gap-1.5">
+          {chips.map((chip) => (
+            <Badge key={chip.name} variant="secondary" className="gap-1 pr-1">
+              <span className="text-muted-foreground">{chip.label}:</span> {chip.value}
+              <button
+                type="button"
+                aria-label={`Remover filtro ${chip.label}`}
+                onClick={() => clearFilter(chip.name)}
+                className="rounded-sm text-muted-foreground hover:text-foreground"
+              >
+                <X className="size-3" />
+              </button>
+            </Badge>
+          ))}
+        </div>
+      )}
+      {modalSpecs.length > 0 && (
+        <AdvancedFiltersDialog
+          open={advancedOpen}
+          onOpenChange={setAdvancedOpen}
+          specs={modalSpecs}
+          values={state.filters}
+          cascade={cascadeClear}
+          onApply={(next) => setStateResetPage({ ...state, filters: next })}
+          filterOptions={filterOptions}
+        />
+      )}
+    </div>
+  ) : null
+
+  // — Estados de carga —
+  const busy = isFetching || extraLoading === true
+  const isEmpty = empty !== undefined ? empty(items) : items.length === 0
+  let body: ReactNode
+  if (busy && items.length === 0 && !(empty !== undefined && !isEmpty)) {
+    body = (
+      <div className="space-y-2">
+        <Skeleton className="h-10 w-full" />
+        <Skeleton className="h-10 w-full" />
+        <Skeleton className="h-10 w-full" />
+      </div>
+    )
+  } else if (isError && error !== undefined) {
+    body = (
+      <div className="rounded-md border border-destructive/50 bg-destructive/10 p-4 text-sm space-y-3">
+        <div>
+          <strong className="text-destructive">{error.code}</strong>
+          <p className="text-destructive">{error.message}</p>
+        </div>
+        <Button variant="outline" size="sm" onClick={() => void refetch()}>
+          Tentar de novo
+        </Button>
+      </div>
+    )
+  } else if (isEmpty) {
+    body = (
+      <div className="rounded-md border border-dashed p-8 text-center text-sm text-muted-foreground">
+        {emptyMessage}
+      </div>
+    )
+  } else if (children !== undefined) {
+    // Modo COMPOSIÇÃO: o layout é de quem compõe; a toolbar e os estados seguem daqui.
+    body = children(items, () => refetch())
+  } else if (activeView !== 'table' && views?.[activeView] !== undefined) {
+    // View alternativa (board/galeria/…): mesma fonte e toolbar, outro renderer.
+    body = views[activeView].render(items, () => refetch())
+  } else {
+    body = (
+      // Moldura da casa (igual à listagem de workspaces): quadro arredondado com o
+      // scroll horizontal contido; a última linha fica sem borda pelo TableBody.
+      <div className="overflow-hidden rounded-lg border border-border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              {hasSelection && (
+                <TableHead className="w-px">
+                  <Checkbox
+                    aria-label="Selecionar todos os elegíveis"
+                    checked={selectableItems.length > 0 && selectableItems.every((it) => selected.has(rowId(it)))}
+                    onCheckedChange={(v) =>
+                      setSelected(v === true ? new Set(selectableItems.map(rowId)) : new Set())
+                    }
+                  />
+                </TableHead>
+              )}
+              {derived.map((col) => (
+                <TableHead key={col.key} className={col.className}>
+                  {col.sortable === true ? (
+                    <button
+                      type="button"
+                      onClick={() => toggleSort(col.key)}
+                      className="inline-flex items-center gap-1 hover:text-foreground"
+                    >
+                      {col.header}
+                      {state.sort?.field === col.key ? (
+                        state.sort.dir === 'asc' ? (
+                          <ArrowUp className="size-3.5" />
+                        ) : (
+                          <ArrowDown className="size-3.5" />
+                        )
+                      ) : (
+                        <ArrowUpDown className="size-3.5 opacity-40" />
+                      )}
+                    </button>
+                  ) : (
+                    col.header
+                  )}
+                </TableHead>
+              ))}
+              {rowActions !== undefined && <TableHead className="w-px" />}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {items.map((item, idx) => (
+              <TableRow
+                // eslint-disable-next-line react/no-array-index-key
+                key={idx}
+                className={onRowClick !== undefined ? 'cursor-pointer' : undefined}
+                onClick={onRowClick !== undefined ? () => onRowClick(item) : undefined}
+              >
+                {hasSelection && (
+                  <TableCell className="w-px" onClick={(e) => e.stopPropagation()}>
+                    <Checkbox
+                      aria-label="Selecionar linha"
+                      disabled={!selectable(item)}
+                      checked={selected.has(rowId(item))}
+                      onCheckedChange={(v) => {
+                        const next = new Set(selected)
+                        if (v === true) next.add(rowId(item))
+                        else next.delete(rowId(item))
+                        setSelected(next)
+                      }}
+                    />
+                  </TableCell>
+                )}
+                {derived.map((col) => (
+                  <TableCell key={col.key} className={col.className}>
+                    {col.cell(item)}
+                  </TableCell>
+                ))}
+                {rowActions !== undefined && (
+                  <TableCell className="w-px whitespace-nowrap text-right" onClick={(e) => e.stopPropagation()}>
+                    {rowActions(item)}
+                  </TableCell>
+                )}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+    )
+  }
+
+  // — Barra de seleção (batch): aparece só com itens marcados —
+  const selectionBar =
+    hasSelection && selected.size > 0 ? (
+      <div
+        data-slot="action-list-selection"
+        className="flex flex-wrap items-center gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm"
+      >
+        <span>
+          {selected.size} {selected.size === 1 ? 'selecionado' : 'selecionados'}
+        </span>
+        <Button size="sm" variant="ghost" onClick={() => setSelected(new Set())}>
+          Limpar
+        </Button>
+        <div className="ml-auto flex items-center gap-2">
+          {batchActions.map((a) => {
+            const eligible = eligibleFor(a).length
+            return (
+              <Button
+                key={a.label}
+                size="sm"
+                variant={a.destructive === true ? 'destructive' : 'outline'}
+                disabled={eligible === 0}
+                busy={running === a.label}
+                onClick={() => {
+                  if (a.confirm !== undefined) setConfirming(a)
+                  else void runBatch(a)
+                }}
+              >
+                {a.label}
+                {eligible > 0 && eligible < selected.size ? ` (${eligible})` : ''}
+              </Button>
+            )
+          })}
+        </div>
+      </div>
+    ) : null
+
+  // — Rodapé (o estilo da casa): Página X de Y à esquerda · pager CENTRALIZADO ·
+  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico) —
+  const pages = total !== undefined ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize))) : 1
+  const goTo = (page: number): void => setState({ ...state, page })
+  const footer =
+    total !== undefined && !isError ? (
+      <div
+        data-slot="action-list-footer"
+        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 px-3 py-1.5 text-xs text-muted-foreground"
+      >
+        <span>
+          Página {state.page} de {pages}
+        </span>
+        {pages > 1 && (
+          <div className="flex items-center gap-0.5">
+            <Button
+              size="sm"
+              variant="ghost"
+              className="size-7 p-0"
+              aria-label="Página anterior"
+              disabled={state.page <= 1}
+              onClick={() => goTo(state.page - 1)}
+            >
+              <ChevronLeft className="size-3.5" />
+            </Button>
+            {pageWindow(state.page, pages).map((n, i) =>
+              n === '…' ? (
+                // eslint-disable-next-line react/no-array-index-key
+                <span key={`e${i}`} className="px-1">
+                  …
+                </span>
+              ) : (
+                <Button
+                  key={n}
+                  size="sm"
+                  variant={n === state.page ? 'secondary' : 'ghost'}
+                  className="size-7 p-0"
+                  aria-current={n === state.page ? 'page' : undefined}
+                  onClick={() => goTo(n)}
+                >
+                  {n}
+                </Button>
+              ),
+            )}
+            <Button
+              size="sm"
+              variant="ghost"
+              className="size-7 p-0"
+              aria-label="Próxima página"
+              disabled={state.page >= pages}
+              onClick={() => goTo(state.page + 1)}
+            >
+              <ChevronRight className="size-3.5" />
+            </Button>
+          </div>
+        )}
+        {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
+        {pages <= 1 && <span />}
+        <span className="justify-self-end">
+          {total} {total === 1 ? 'item' : 'itens'} no total
+        </span>
+      </div>
+    ) : null
+
+  return (
+    <TooltipProvider>
+    <div data-action={action.name} className="space-y-3">
+      {toolbar}
+      {selectionBar}
+      {/* Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
+      <div aria-busy={busy} className={cn(busy && items.length > 0 && 'pointer-events-none opacity-60')}>
+        {body}
+      </div>
+      {footer}
+      {confirming !== null && (
+        <AlertDialog
+          open
+          onOpenChange={(o) => {
+            if (!o) setConfirming(null)
+          }}
+        >
+          <AlertDialogContent>
+            <AlertDialogHeader>
+              <AlertDialogTitle>{confirming.confirm?.title ?? confirming.label}</AlertDialogTitle>
+              {confirming.confirm?.message !== undefined && (
+                <AlertDialogDescription>{confirming.confirm.message}</AlertDialogDescription>
+              )}
+            </AlertDialogHeader>
+            <AlertDialogFooter>
+              <Button variant="outline" size="sm" onClick={() => setConfirming(null)}>
+                Cancelar
+              </Button>
+              <Button
+                size="sm"
+                variant={confirming.destructive === true ? 'destructive' : 'default'}
+                onClick={() => {
+                  const a = confirming
+                  setConfirming(null)
+                  void runBatch(a)
+                }}
+              >
+                {confirming.label}
+              </Button>
+            </AlertDialogFooter>
+          </AlertDialogContent>
+        </AlertDialog>
+      )}
+    </div>
+    </TooltipProvider>
+  )
+}
+
+// =============================================================================
+// URL sync — a serialização padrão do estado da toolbar (querystring compacta)
+// =============================================================================
+//
+// Convenção: `q` · `sort=chave:dir` (omitido quando é o default do contrato) ·
+// `period=preset` relativo ou `period=from..to` (o custom é implícito; default
+// omitido) · `view` (omitida quando é a primeira) · `cols=a,b,c` (omitida no
+// default) · filtros pelo PRÓPRIO nome (multiple → CSV). Quem embala liga:
+//   <ActionList state={listParamsToState(params, contract)}
+//                 onStateChange={(s) => navigate(`/rota${listStateToParams(s, contract)}`)} />
+
+/** URLSearchParams → estado da toolbar (lê a convenção acima). */
+export function listParamsToState(params: URLSearchParams, action: ListActionLike): ActionListState {
+  const defaultSort = action.sort?.default?.[0] ?? null
+  const sortParam = params.get('sort')
+  let sort: SortSpec | null = defaultSort
+  if (sortParam !== null) {
+    const [field, dir] = sortParam.split(':')
+    if (field !== undefined && field !== '') sort = { field, dir: dir === 'asc' ? 'asc' : 'desc' }
+  }
+  const filters: Record<string, unknown> = {}
+  for (const [name, spec] of Object.entries(action.filters ?? {})) {
+    const v = params.get(name)
+    if (v !== null && v !== '') filters[name] = spec.multiple === true ? v.split(',') : v
+  }
+  const cols = params.get('cols')
+  const limitParam = Number(params.get('limit') ?? '')
+  const page = Number(params.get('page') ?? '1')
+  // Range direto no param ('period=2026-07-01..2026-07-07') = custom implícito.
+  const periodParam = params.get('period')
+  const range = periodParam?.match(/^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/) ?? null
+  return {
+    q: params.get('q') ?? '',
+    sort,
+    filters,
+    period: range !== null ? 'custom' : periodParam,
+    from: range?.[1] ?? params.get('from'),
+    to: range?.[2] ?? params.get('to'),
+    view: params.get('view'),
+    columns: cols !== null && cols !== '' ? cols.split(',') : null,
+    limit: Number.isInteger(limitParam) && limitParam > 0 ? limitParam : null,
+    page: Number.isInteger(page) && page > 1 ? page : 1,
+  }
+}
+
+/** Estado da toolbar → querystring ('' ou '?…'), omitindo defaults (URL limpa). */
+export function listStateToParams(state: ActionListState, action: ListActionLike): string {
+  const qs = new URLSearchParams()
+  if (state.q.trim() !== '') qs.set('q', state.q.trim())
+  const d = action.sort?.default?.[0]
+  if (state.sort !== null && !(d !== undefined && state.sort.field === d.field && state.sort.dir === d.dir)) {
+    qs.set('sort', `${state.sort.field}:${state.sort.dir}`)
+  }
+  for (const [name, value] of Object.entries(state.filters)) {
+    if (isEmptyValue(value)) continue
+    qs.set(name, Array.isArray(value) ? value.join(',') : String(value))
+  }
+  if (state.period === 'custom') {
+    // O custom é implícito: o range vai direto no param ('period=from..to').
+    if (state.from !== null && state.to !== null) qs.set('period', `${state.from}..${state.to}`)
+  } else if (state.period !== null) {
+    // Preset é relativo (materializa no fetch).
+    qs.set('period', state.period)
+  }
+  if (state.view !== null) qs.set('view', state.view)
+  if (state.columns !== null) qs.set('cols', state.columns.join(','))
+  if (state.limit !== null) qs.set('limit', String(state.limit))
+  if (state.page > 1) qs.set('page', String(state.page))
+  const s = qs.toString()
+  return s === '' ? '' : `?${s}`
+}
+
+export type { Paginated, ListAction }