@softize/opus 30.0.0 → 31.1.0

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

@@ -14,7 +14,7 @@
  * 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,
+ * Modos de render: itens por campos declarados · 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).
  */
@@ -63,7 +63,8 @@ import {
 import {
   useDicts,
   useGroupedListAction,
-  useListAction,
+  useListResource,
+  type ListDataSource,
   useLookupAction,
   type DictLike,
 } from "../../drivers/react.tsx";
@@ -123,6 +124,15 @@ import {
   type FieldSetVariant,
 } from "../primitives/field.tsx";
 import { Surface } from "./surface.tsx";
+import {
+  Item,
+  ItemGroup,
+  ItemHeader,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemSeparator,
+} from "../primitives/item.tsx";
 import { Search } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
 import {
@@ -266,6 +276,7 @@ export function presetRange(
 /** 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 {
+  paginate?: "cursor" | "offset" | false;
   name: string;
   kind: "list";
   /** Schema de saída (item). Coluna cujo campo carrega a meta de `t.dict` renderiza
@@ -304,6 +315,8 @@ export interface ActionFilterBarProps {
   refreshing?: boolean;
   /** Posição do período em relação aos filtros inline. Também pode ancorá-lo após um filtro. */
   periodPosition?: "before" | "after" | { afterFilter: string };
+  /** Substitui o seletor de período; estado e input temporal ficam com o consumidor. */
+  periodControl?: ReactNode;
   /** Composição do período com uma dimensão temporal declarada como filtro inline. */
   period?: PeriodLayout;
   /** Controles auxiliares, agrupados com o refresh em um ButtonGroup espaçado. */
@@ -349,8 +362,34 @@ export interface ActionListBatchAction<TItem> {
   destructive?: boolean;
 }
 
-export interface ActionListProps<TInput, TItem> {
-  action: ListActionLike;
+/** Campos da apresentação de itens; serializável sem callbacks ou JSX. */
+export interface ActionListItemSpec {
+  title: string;
+  description?: string;
+}
+
+export interface ActionListContext<TItem> {
+  items: TItem[];
+  total: number | undefined;
+  isFetching: boolean;
+  isError: boolean;
+  refetch: () => Promise<void>;
+}
+
+export type ActionListProps<TInput, TItem> = ActionListBaseProps<
+  TInput,
+  TItem
+> &
+  (
+    | { action: ListActionLike; source?: never }
+    | { source: ListDataSource<TItem>; action?: never }
+  );
+
+interface ActionListBaseProps<TInput, TItem> {
+  /** Título da coleção; as ações da toolbar acompanham seu cabeçalho. */
+  title?: string;
+  /** Apresenta itens conectados em uma moldura, em vez de colunas de tabela. */
+  item?: ActionListItemSpec;
   /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
   input: TInput;
   /**
@@ -360,8 +399,9 @@ export interface ActionListProps<TInput, TItem> {
    * `flow` nos demais casos (ADR 0024).
    */
   layout?: "flow" | "fill";
-  /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
-  toolbarActions?: ReactNode;
+  /** Ações da coleção (criar, importar, exportar) após os controles de exibição. */
+  toolbarActions?:
+    ReactNode | ((context: ActionListContext<TItem>) => ReactNode);
   /** Controles da visualização ativa, imediatamente após seu seletor. */
   viewControls?: ReactNode;
   /** Tabela explícita — sobrepõe as colunas do contrato. */
@@ -378,6 +418,8 @@ export interface ActionListProps<TInput, TItem> {
   advancedFilters?: AdvancedFiltersLayout;
   /** Posição do período em relação aos filtros inline. Também pode ancorá-lo após um filtro. */
   periodPosition?: "before" | "after" | { afterFilter: string };
+  /** Substitui o seletor de período; estado e input temporal ficam com o consumidor. */
+  periodControl?: ReactNode;
   /** Composição do período com uma dimensão temporal declarada como filtro inline. */
   period?: PeriodLayout;
   /** Views alternativas da mesma listagem — o segment na toolbar alterna entre a
@@ -404,8 +446,8 @@ export interface ActionListProps<TInput, TItem> {
   /** 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;
+   *  como `cells`. Cliques ali não disparam o onRowClick. Também aparece à direita dos itens. */
+  rowActions?: (item: TItem, context: ActionListContext<TItem>) => ReactNode;
   /**
    * Conteúdo entre a toolbar e o corpo da listagem — ex.: o resumo do recorte atual
    * ("12 itens, R$ 4.300 no período"), que precisa reagir ao filtro e por isso não cabe
@@ -415,7 +457,7 @@ export interface ActionListProps<TInput, TItem> {
    * enquanto viveu assim, todo bump do Opus o descartava em silêncio e o app parava de
    * compilar sem ninguém entender por quê. Subiu pra cá em 8.6.9.
    */
-  beforeContent?: ReactNode;
+  beforeContent?: ReactNode | ((input: TInput) => 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. */
@@ -1376,6 +1418,7 @@ export function ActionFilterBar({
   onRefresh,
   refreshing = false,
   periodPosition = "before",
+  periodControl: customPeriodControl,
   period,
   controls,
   actions,
@@ -1395,8 +1438,9 @@ export function ActionFilterBar({
     periods[0]?.value ??
     null;
   const activePeriod = state.period ?? defaultPeriod;
+  const hasPeriod = customPeriodControl != null || periods.length > 0;
   const periodBasisEntry =
-    periods.length > 0 && period !== undefined
+    hasPeriod && period !== undefined
       ? inlineSpecs.find(([name]) => name === period.basisFilter)
       : undefined;
   const [advancedOpen, setAdvancedOpen] = useState(false);
@@ -1446,18 +1490,18 @@ export function ActionFilterBar({
     });
   const inlineControlCount =
     inlineSpecs.filter(([name]) => name !== periodBasisEntry?.[0]).length +
-    (periods.length > 0 ? 1 : 0) +
+    (hasPeriod ? 1 : 0) +
     (hasSearch ? 1 : 0);
   const showInlineLabels = inlineControlCount > 1;
-  const searchAtActionsEnd =
-    hasSearch && (inlineSpecs.length > 0 || periods.length > 0);
+  const searchAtActionsEnd = hasSearch && (inlineSpecs.length > 0 || hasPeriod);
   const periodAfterFilter =
     typeof periodPosition === "object" ? periodPosition.afterFilter : null;
   const anchoredPeriodExists = inlineSpecs.some(
     ([name]) => name === periodAfterFilter,
   );
   const periodField =
-    periods.length > 0 ? (
+    customPeriodControl ??
+    (periods.length > 0 ? (
       <PeriodControl
         periods={periods}
         period={activePeriod}
@@ -1480,7 +1524,7 @@ export function ActionFilterBar({
           })
         }
       />
-    ) : null;
+    ) : null);
   const periodControl =
     periodField === null || periodBasisEntry !== undefined ? null : (
       <Labeled
@@ -1547,24 +1591,26 @@ export function ActionFilterBar({
                       aria-hidden="true"
                     />
                     <div className="pl-2">
-                      <PeriodControl
-                        periods={periods}
-                        period={activePeriod}
-                        from={state.from}
-                        to={state.to}
-                        clearable={false}
-                        embedded
-                        onChange={(next) =>
-                          onStateChange({
-                            ...state,
-                            ...next,
-                            period:
-                              next.period === defaultPeriod
-                                ? null
-                                : next.period,
-                          })
-                        }
-                      />
+                      {customPeriodControl ?? (
+                        <PeriodControl
+                          periods={periods}
+                          period={activePeriod}
+                          from={state.from}
+                          to={state.to}
+                          clearable={false}
+                          embedded
+                          onChange={(next) =>
+                            onStateChange({
+                              ...state,
+                              ...next,
+                              period:
+                                next.period === defaultPeriod
+                                  ? null
+                                  : next.period,
+                            })
+                          }
+                        />
+                      )}
                     </div>
                     <Separator
                       data-slot="action-filter-period-separator"
@@ -1778,7 +1824,10 @@ function RowActions({ children }: { children: ReactNode }) {
 }
 
 export function ActionList<TInput, TItem>({
-  action,
+  action: actionProp,
+  source,
+  title,
+  item: itemSpec,
   input,
   layout: layoutProp,
   toolbarActions,
@@ -1790,6 +1839,7 @@ export function ActionList<TInput, TItem>({
   filterIcons,
   advancedFilters,
   periodPosition,
+  periodControl,
   period,
   views,
   batch,
@@ -1807,16 +1857,40 @@ export function ActionList<TInput, TItem>({
   state: controlledState,
   onStateChange,
 }: ActionListProps<TInput, TItem>) {
+  if (source !== undefined && actionProp !== undefined)
+    throw new Error("ActionList aceita action ou source, nunca ambos.");
+  if (source !== undefined && source.key.length === 0)
+    throw new Error("A fonte de ActionList exige uma chave com escopo.");
+  if (
+    itemSpec !== undefined &&
+    (children !== undefined || views !== undefined || batch !== undefined)
+  )
+    throw new Error(
+      "ActionList em itens não combina children, views ou seleção em lote.",
+    );
+  const action: ListActionLike = actionProp ?? {
+    name: "external",
+    kind: "list",
+  };
+  const paginated = action.paginate !== false;
   const confirmBodyId = useId();
   const groupRegionId = useId();
+  const optionsPanelRef = useRef<HTMLDivElement>(null);
   const { layout, ref: rootRef } = useFillLeaf<HTMLDivElement>(layoutProp);
   // 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) {
+  const hasTable =
+    itemSpec === undefined &&
+    (columns !== undefined || action.columns !== undefined);
+  if (
+    itemSpec === undefined &&
+    children === undefined &&
+    !hasTable &&
+    views === undefined
+  ) {
     throw new Error(
-      "ActionList precisa de children (composição), columns (prop/contrato) ou views.",
+      "ActionList precisa de item, children (composição), columns (prop/contrato) ou views.",
     );
   }
 
@@ -1883,6 +1957,7 @@ export function ActionList<TInput, TItem>({
   });
   const requestedGroupBy = state.groupBy ?? null;
   const activeGroupBy =
+    itemSpec === undefined &&
     children === undefined &&
     activeView === "table" &&
     requestedGroupBy !== null &&
@@ -1893,62 +1968,29 @@ export function ActionList<TInput, TItem>({
     activeGroupBy === null
       ? null
       : text(action.filters?.[activeGroupBy]?.label, activeGroupBy);
-  const hasSegment = children === undefined && viewEntries.length > 1;
+  const hasSegment =
+    itemSpec === undefined && children === undefined && viewEntries.length > 1;
   const periods = action.periods ?? [];
   const hasToolbar =
     hasSearch ||
     filterSpecs.length > 0 ||
     periods.length > 0 ||
+    periodControl != null ||
     hasSegment ||
     viewControls != null ||
+    (title === undefined && toolbarActions != null) ||
     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({
-      ...filterDefaults,
-      ...state.filters,
-    })) {
-      if (isEmptyValue(v)) continue;
-      const filter = action.filters?.[name];
-      if (
-        filter?.type === "date" &&
-        !isValidDateFilterValue(v, filter.multiple === true)
-      )
-        continue;
-      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, filterDefaults]);
+  const effectiveInput = useMemo(
+    () =>
+      listStateToInput(state, action, {
+        input: input as Record<string, unknown>,
+        filterDefaults,
+        pageSize,
+        applyPeriod: periodControl == null,
+      }) as TInput,
+    [input, state, pageSize, filterDefaults, action, periodControl],
+  );
 
   const inputKey = JSON.stringify([effectiveInput, activeGroupBy]);
   const groupSpec =
@@ -1986,8 +2028,8 @@ export function ActionList<TInput, TItem>({
   }>({ key: "", values: new Set() });
   const collapsedGroups =
     groupCollapse.key === inputKey ? groupCollapse.values : new Set<string>();
-  const flat = useListAction<TItem, Record<string, unknown>>(
-    action as unknown as { name: string; kind: "list" },
+  const flat = useListResource<TItem, Record<string, unknown>>(
+    source ?? action,
     effectiveInput as Record<string, unknown>,
     { enabled: activeGroupBy === null },
   );
@@ -2050,6 +2092,17 @@ export function ActionList<TInput, TItem>({
     if (activeGroupBy === null) return flat.refetch();
     await Promise.all(grouped.map((group) => group.refetch()));
   };
+  const listContext: ActionListContext<TItem> = {
+    items,
+    total,
+    isFetching,
+    isError,
+    refetch,
+  };
+  const collectionActions =
+    typeof toolbarActions === "function"
+      ? toolbarActions(listContext)
+      : toolbarActions;
   // — 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;
@@ -2164,11 +2217,16 @@ export function ActionList<TInput, TItem>({
   const displayCustomized =
     activeGroupBy !== null ||
     state.columns !== null ||
-    state.limit !== null ||
+    (paginated && state.limit !== null) ||
     sortCustomized;
-  const displayLabel = displayCustomized
-    ? "Exibição personalizada"
-    : "Exibição";
+  const hasDisplayOptions =
+    paginated ||
+    (children === undefined &&
+      activeView === "table" &&
+      (sortableFields.length > 0 ||
+        availableGroupingFields.length > 0 ||
+        pickerColumns.length > 0));
+  const displayLabel = "Opções da lista";
 
   // — 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
@@ -2215,240 +2273,259 @@ export function ActionList<TInput, TItem>({
         filterIcons={filterIcons}
         advancedFilters={advancedFilters}
         periodPosition={periodPosition}
+        periodControl={periodControl}
         period={period}
-        onRefresh={() => refetch()}
-        refreshing={isLoading}
         controls={
           <>
-            {/* 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="ghost"
-                      size="icon"
-                      className="relative shrink-0"
-                      aria-label={displayLabel}
-                    >
-                      <Settings2 className="h-3.5 w-3.5" />
-                      {displayCustomized && (
-                        <Dot
-                          context="primary"
-                          className="absolute top-1 right-1 ring-2 ring-background"
-                        />
-                      )}
-                    </Button>
-                  </PopoverTrigger>
-                </TooltipTrigger>
-                <TooltipContent>{displayLabel}</TooltipContent>
-              </Tooltip>
-              <PopoverContent
-                align="end"
-                className="w-60 p-3"
-                data-slot="action-list-display"
-              >
-                <div className="space-y-3">
-                  {children === undefined &&
-                    activeView === "table" &&
-                    sortableFields.length > 0 && (
-                      <>
-                        <div className="space-y-2">
-                          <div className="flex items-center justify-between">
-                            <span className="text-xs font-medium text-muted-foreground">
-                              Ordenação
-                            </span>
-                            {sortCustomized && (
-                              <button
-                                type="button"
-                                onClick={() =>
-                                  setState({
-                                    ...state,
-                                    sort: defaultSort,
-                                    page: 1,
-                                  })
-                                }
-                                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>
-                          <Select
-                            aria-label="Ordenar por"
-                            size="sm"
-                            className="w-full"
-                            value={activeSort?.field ?? "__none__"}
-                            onChange={(field) =>
-                              setState({
-                                ...state,
-                                sort:
-                                  field === "__none__"
-                                    ? null
-                                    : {
-                                        field,
-                                        dir:
-                                          activeSort?.field === field
-                                            ? activeSort.dir
-                                            : "asc",
-                                      },
-                                page: 1,
-                              })
-                            }
-                            options={[
-                              ...(defaultSort === null
-                                ? [
-                                    {
-                                      value: "__none__",
-                                      label: "Sem ordenação",
-                                    },
-                                  ]
-                                : []),
-                              ...sortableFields,
-                            ]}
-                            trailing={
-                              activeSort !== null ? (
-                                <Button
+            {/* Opções da lista: preferências disponíveis para a visualização. */}
+            {hasDisplayOptions && (
+              <Popover>
+                {/* Tooltip e PopoverTrigger compõem via asChild aninhado no MESMO botão. */}
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <PopoverTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="relative shrink-0"
+                        aria-label={displayLabel}
+                      >
+                        <Settings2 className="h-3.5 w-3.5" />
+                        {displayCustomized && (
+                          <Dot
+                            context="primary"
+                            className="absolute top-1 right-1 ring-2 ring-background"
+                          />
+                        )}
+                      </Button>
+                    </PopoverTrigger>
+                  </TooltipTrigger>
+                  <TooltipContent>{displayLabel}</TooltipContent>
+                </Tooltip>
+                <PopoverContent
+                  ref={optionsPanelRef}
+                  tabIndex={-1}
+                  onOpenAutoFocus={(event) => {
+                    // O Select abre ao receber foco; entrar no painel não deve abrir suas opções.
+                    event.preventDefault();
+                    optionsPanelRef.current?.focus();
+                  }}
+                  align="end"
+                  className="w-60 p-3"
+                  data-slot="action-list-display"
+                >
+                  <div className="space-y-3">
+                    {children === undefined &&
+                      activeView === "table" &&
+                      sortableFields.length > 0 && (
+                        <>
+                          <div className="space-y-2">
+                            <div className="flex items-center justify-between">
+                              <span className="text-xs font-medium text-muted-foreground">
+                                Ordenação
+                              </span>
+                              {sortCustomized && (
+                                <button
                                   type="button"
-                                  variant="ghost"
-                                  size="icon-xs"
-                                  aria-label={
-                                    activeSort.dir === "asc"
-                                      ? "Ordem crescente. Alterar para decrescente"
-                                      : "Ordem decrescente. Alterar para crescente"
-                                  }
                                   onClick={() =>
                                     setState({
                                       ...state,
-                                      sort: {
-                                        ...activeSort,
-                                        dir:
-                                          activeSort.dir === "asc"
-                                            ? "desc"
-                                            : "asc",
-                                      },
+                                      sort: defaultSort,
                                       page: 1,
                                     })
                                   }
+                                  className="inline-flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
                                 >
-                                  {activeSort.dir === "asc" ? (
-                                    <ArrowUp aria-hidden="true" />
-                                  ) : (
-                                    <ArrowDown aria-hidden="true" />
-                                  )}
-                                </Button>
-                              ) : undefined
-                            }
-                          />
-                        </div>
-                        <Separator />
-                      </>
-                    )}
-                  {children === undefined &&
-                    activeView === "table" &&
-                    availableGroupingFields.length > 0 && (
+                                  <Eraser className="size-3" />
+                                  Padrão
+                                </button>
+                              )}
+                            </div>
+                            <Select
+                              aria-label="Ordenar por"
+                              size="sm"
+                              className="w-full"
+                              value={activeSort?.field ?? "__none__"}
+                              onChange={(field) =>
+                                setState({
+                                  ...state,
+                                  sort:
+                                    field === "__none__"
+                                      ? null
+                                      : {
+                                          field,
+                                          dir:
+                                            activeSort?.field === field
+                                              ? activeSort.dir
+                                              : "asc",
+                                        },
+                                  page: 1,
+                                })
+                              }
+                              options={[
+                                ...(defaultSort === null
+                                  ? [
+                                      {
+                                        value: "__none__",
+                                        label: "Sem ordenação",
+                                      },
+                                    ]
+                                  : []),
+                                ...sortableFields,
+                              ]}
+                              trailing={
+                                activeSort !== null ? (
+                                  <Button
+                                    type="button"
+                                    variant="ghost"
+                                    size="icon-xs"
+                                    aria-label={
+                                      activeSort.dir === "asc"
+                                        ? "Ordem crescente. Alterar para decrescente"
+                                        : "Ordem decrescente. Alterar para crescente"
+                                    }
+                                    onClick={() =>
+                                      setState({
+                                        ...state,
+                                        sort: {
+                                          ...activeSort,
+                                          dir:
+                                            activeSort.dir === "asc"
+                                              ? "desc"
+                                              : "asc",
+                                        },
+                                        page: 1,
+                                      })
+                                    }
+                                  >
+                                    {activeSort.dir === "asc" ? (
+                                      <ArrowUp aria-hidden="true" />
+                                    ) : (
+                                      <ArrowDown aria-hidden="true" />
+                                    )}
+                                  </Button>
+                                ) : undefined
+                              }
+                            />
+                          </div>
+                          <Separator className="last:hidden" />
+                        </>
+                      )}
+                    {children === undefined &&
+                      activeView === "table" &&
+                      availableGroupingFields.length > 0 && (
+                        <>
+                          <div className="space-y-2">
+                            <span className="text-xs font-medium text-muted-foreground">
+                              Agrupar por
+                            </span>
+                            <Select
+                              aria-label="Agrupar por"
+                              size="sm"
+                              className="w-full"
+                              value={activeGroupBy ?? "__none__"}
+                              onChange={(value) =>
+                                setState({
+                                  ...state,
+                                  groupBy: value === "__none__" ? null : value,
+                                  page: 1,
+                                })
+                              }
+                              options={[
+                                { value: "__none__", label: "Sem agrupamento" },
+                                ...availableGroupingFields.map((field) => ({
+                                  value: field,
+                                  label: text(
+                                    action.filters?.[field]?.label,
+                                    field,
+                                  ),
+                                })),
+                              ]}
+                            />
+                          </div>
+                          <Separator className="last:hidden" />
+                        </>
+                      )}
+                    {children === undefined &&
+                      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 className="last:hidden" />
+                        </>
+                      )}
+                    {paginated && (
                       <>
                         <div className="space-y-2">
                           <span className="text-xs font-medium text-muted-foreground">
-                            Agrupar por
+                            {activeGroupBy === null
+                              ? "Itens por página"
+                              : "Itens por grupo"}
                           </span>
                           <Select
-                            aria-label="Agrupar por"
                             size="sm"
                             className="w-full"
-                            value={activeGroupBy ?? "__none__"}
-                            onChange={(value) =>
+                            value={String(state.limit ?? pageSize)}
+                            onChange={(v) => {
+                              const n = Number(v);
+                              // O default do caller fica FORA da URL (limit null).
                               setState({
                                 ...state,
-                                groupBy: value === "__none__" ? null : value,
+                                limit: n === pageSize ? null : n,
                                 page: 1,
-                              })
-                            }
-                            options={[
-                              { value: "__none__", label: "Sem agrupamento" },
-                              ...availableGroupingFields.map((field) => ({
-                                value: field,
-                                label: text(
-                                  action.filters?.[field]?.label,
-                                  field,
-                                ),
-                              })),
-                            ]}
+                              });
+                            }}
+                            options={Array.from(
+                              new Set([10, 25, 50, 100, pageSize]),
+                            )
+                              .sort((a, b) => a - b)
+                              .map((n) => ({
+                                value: String(n),
+                                label: String(n),
+                              }))}
                           />
                         </div>
-                        <Separator />
+                        <Separator className="last:hidden" />
                       </>
                     )}
-                  {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">
-                      {activeGroupBy === null
-                        ? "Itens por página"
-                        : "Itens por grupo"}
-                    </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>
+                </PopoverContent>
+              </Popover>
+            )}
             {hasSegment && (
               <ToggleGroup
                 type="single"
@@ -2481,7 +2558,7 @@ export function ActionList<TInput, TItem>({
             {viewControls}
           </>
         }
-        actions={toolbarActions}
+        actions={title === undefined ? collectionActions : undefined}
       />
     </div>
   ) : null;
@@ -2492,7 +2569,10 @@ export function ActionList<TInput, TItem>({
   const initialLoading =
     busy && items.length === 0 && !(empty !== undefined && !isEmpty);
   const tableFillsAvailableHeight =
-    layout === "fill" && children === undefined && activeView === "table";
+    layout === "fill" &&
+    itemSpec === undefined &&
+    children === undefined &&
+    activeView === "table";
   const tableStateActive =
     tableFillsAvailableHeight && (initialLoading || isError || isEmpty);
   const tableColumnCount = Math.max(
@@ -2549,14 +2629,56 @@ export function ActionList<TInput, TItem>({
             className="w-px whitespace-nowrap text-right"
             onClick={(e) => e.stopPropagation()}
           >
-            <RowActions>{rowActions(item)}</RowActions>
+            <RowActions>{rowActions(item, listContext)}</RowActions>
           </TableCell>
         )}
       </TableRow>
     ));
-  const tableRows = renderTableRows(items);
+  const tableRows = itemSpec === undefined ? renderTableRows(items) : null;
   let content: ReactNode;
-  if (children !== undefined) {
+  if (itemSpec !== undefined) {
+    const fieldValue = (entry: TItem, field: string): ReactNode => {
+      const value =
+        entry !== null &&
+        typeof entry === "object" &&
+        Object.prototype.hasOwnProperty.call(entry, field)
+          ? (entry as Record<string, unknown>)[field]
+          : undefined;
+      return typeof value === "string" || typeof value === "number"
+        ? value
+        : null;
+    };
+    content = (
+      <ItemGroup variant="framed">
+        {items.map((entry, index) => {
+          const description =
+            itemSpec.description === undefined
+              ? null
+              : fieldValue(entry, itemSpec.description);
+          return (
+            <Fragment key={rowId(entry)}>
+              {index > 0 && <ItemSeparator />}
+              <Item>
+                <ItemHeader>
+                  <ItemTitle className="block w-full truncate">
+                    {fieldValue(entry, itemSpec.title) ?? <EmptyValue />}
+                  </ItemTitle>
+                  {description !== null && description !== "" && (
+                    <ItemDescription className="line-clamp-1 text-nowrap">
+                      {description}
+                    </ItemDescription>
+                  )}
+                </ItemHeader>
+                {rowActions !== undefined && (
+                  <ItemActions>{rowActions(entry, listContext)}</ItemActions>
+                )}
+              </Item>
+            </Fragment>
+          );
+        })}
+      </ItemGroup>
+    );
+  } else if (children !== undefined) {
     // Modo COMPOSIÇÃO: o layout é de quem compõe; a toolbar e os estados seguem daqui.
     content = children(items, () => refetch());
   } else if (activeView !== "table" && views?.[activeView] !== undefined) {
@@ -2887,95 +3009,126 @@ export function ActionList<TInput, TItem>({
         )}
       </span>
     ) : null;
-  const footer =
-    total !== undefined && !isError && activeGroupBy !== null ? (
-      <div
-        data-slot="action-list-footer"
-        className="flex min-h-10 flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-0.5 text-xs text-muted-foreground"
-      >
-        {displaySummary}
-        <span className={cn(displaySummary === null && "ml-auto")}>
-          {total} {total === 1 ? "item" : "itens"} no total
-        </span>
-      </div>
-    ) : total !== undefined && !isError ? (
-      <div
-        data-slot="action-list-footer"
-        className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-0.5 text-xs text-muted-foreground"
-      >
-        <span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
-          <span className="whitespace-nowrap">
-            Página {state.page} de {pages}
-          </span>
-          {displaySummary !== null && <span aria-hidden="true">·</span>}
-          {displaySummary}
-        </span>
-        {pages > 1 && (
-          // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
-          // números `sm` que crescem com os dígitos (5726 e 5727 não se colam).
-          <Pagination className="mx-0 w-auto">
-            <PaginationContent className="gap-0.5">
-              <PaginationItem>
-                <PaginationPrevious
-                  iconOnly
-                  size="icon-sm"
-                  disabled={state.page <= 1}
-                  onClick={() => goTo(state.page - 1)}
-                />
-              </PaginationItem>
-              {pageWindow(state.page, pages).map((n, i) =>
-                n === "…" ? (
-                  // eslint-disable-next-line react/no-array-index-key
-                  <PaginationItem key={`e${i}`}>
-                    <PaginationEllipsis size="icon-sm" />
-                  </PaginationItem>
-                ) : (
-                  <PaginationItem key={n}>
-                    <PaginationLink
-                      page={n}
-                      isActive={n === state.page}
-                      size="sm"
-                      className="text-xs"
-                      onClick={() => goTo(n)}
-                    />
-                  </PaginationItem>
-                ),
-              )}
-              <PaginationItem>
-                <PaginationNext
-                  iconOnly
-                  size="icon-sm"
-                  disabled={state.page >= pages}
-                  onClick={() => goTo(state.page + 1)}
-                />
-              </PaginationItem>
-            </PaginationContent>
-          </Pagination>
-        )}
-        {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
-        {pages <= 1 && <span />}
-        <span className="justify-self-end whitespace-nowrap">
-          {total} {total === 1 ? "item" : "itens"} no total
+  useEffect(() => {
+    if (
+      paginated &&
+      itemSpec !== undefined &&
+      !isLoading &&
+      !isFetching &&
+      !isError &&
+      total !== undefined &&
+      state.page > pages
+    )
+      setState({ ...state, page: pages });
+  }, [
+    paginated,
+    itemSpec,
+    isLoading,
+    isFetching,
+    isError,
+    total,
+    state.page,
+    pages,
+  ]);
+  // O piso soma os controles e o padding em rem; a compensação fixa cobre apenas a borda superior.
+  const footer = !paginated || total === 0 ? null : itemSpec !== undefined &&
+    pages <= 1 ? null : total !== undefined &&
+    !isError &&
+    activeGroupBy !== null ? (
+    <div
+      data-slot="action-list-footer"
+      className="flex min-h-[calc(3.5rem+1px)] flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-3 text-xs text-muted-foreground"
+    >
+      {displaySummary}
+      <span className={cn(displaySummary === null && "ml-auto")}>
+        {total} {total === 1 ? "item" : "itens"} no total
+      </span>
+    </div>
+  ) : total !== undefined && !isError ? (
+    <div
+      data-slot="action-list-footer"
+      className="grid min-h-[calc(3.5rem+1px)] grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-3 text-xs text-muted-foreground"
+    >
+      <span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+        <span className="whitespace-nowrap">
+          Página {state.page} de {pages}
         </span>
-      </div>
-    ) : null;
+        {displaySummary !== null && <span aria-hidden="true">·</span>}
+        {displaySummary}
+      </span>
+      {pages > 1 && (
+        // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
+        // números `sm` que crescem com os dígitos (5726 e 5727 não se colam).
+        <Pagination className="mx-0 w-auto">
+          <PaginationContent className="gap-0.5">
+            <PaginationItem>
+              <PaginationPrevious
+                iconOnly
+                size="icon-sm"
+                disabled={state.page <= 1}
+                onClick={() => goTo(state.page - 1)}
+              />
+            </PaginationItem>
+            {pageWindow(state.page, pages).map((n, i) =>
+              n === "…" ? (
+                // eslint-disable-next-line react/no-array-index-key
+                <PaginationItem key={`e${i}`}>
+                  <PaginationEllipsis size="icon-sm" />
+                </PaginationItem>
+              ) : (
+                <PaginationItem key={n}>
+                  <PaginationLink
+                    page={n}
+                    isActive={n === state.page}
+                    size="sm"
+                    className="text-xs"
+                    onClick={() => goTo(n)}
+                  />
+                </PaginationItem>
+              ),
+            )}
+            <PaginationItem>
+              <PaginationNext
+                iconOnly
+                size="icon-sm"
+                disabled={state.page >= pages}
+                onClick={() => goTo(state.page + 1)}
+              />
+            </PaginationItem>
+          </PaginationContent>
+        </Pagination>
+      )}
+      {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
+      {pages <= 1 && <span />}
+      <span className="justify-self-end whitespace-nowrap">
+        {total} {total === 1 ? "item" : "itens"} no total
+      </span>
+    </div>
+  ) : null;
 
   return (
     <TooltipProvider>
       <div
         ref={rootRef}
-        data-action={action.name}
+        data-slot="action-list"
+        data-action={actionProp?.name}
+        data-source={source === undefined ? undefined : "external"}
         data-layout={layout}
         className={cn(
           layout === "fill"
-            ? "flex h-full min-h-0 min-w-0 max-w-full flex-1 flex-col gap-3"
-            : "min-w-0 max-w-full space-y-3",
+            ? "flex h-full min-h-0 min-w-0 max-w-full flex-1 flex-col gap-4"
+            : "min-w-0 max-w-full space-y-4",
         )}
       >
         {/* A lista é a folha da cadeia de altura: o que ela hospeda decide a própria. */}
         <FillBoundary>
+          {title !== undefined && (
+            <Surface title={title} actions={collectionActions} />
+          )}
           {toolbar}
-          {beforeContent}
+          {typeof beforeContent === "function"
+            ? beforeContent(effectiveInput)
+            : beforeContent}
           {selectionBar}
           {/* Tabela e rodapé formam um bloco só: o `gap` da pilha separa a barra de
               ferramentas do conteúdo, nunca o conteúdo do seu próprio rodapé. Duas
@@ -3120,12 +3273,87 @@ export function listParamsToState(
     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,
+    limit:
+      action.paginate !== false &&
+      Number.isInteger(limitParam) &&
+      limitParam > 0
+        ? limitParam
+        : null,
+    page:
+      action.paginate !== false && Number.isInteger(page) && page > 1
+        ? page
+        : 1,
     groupBy,
   };
 }
 
+/** Materializa o mesmo recorte da coleção para consulta e hidratação de detalhes roteados. */
+export function listStateToInput(
+  state: ActionListState,
+  action: ListActionLike,
+  {
+    input = {},
+    filterDefaults,
+    pageSize = 50,
+    applyPeriod = true,
+  }: {
+    input?: Record<string, unknown>;
+    filterDefaults?: Record<string, string>;
+    pageSize?: number;
+    /** False quando o consumidor fornece integralmente o intervalo temporal em input. */
+    applyPeriod?: boolean;
+  } = {},
+): Record<string, unknown> {
+  const sort = state.sort ?? action.sort?.default?.[0] ?? null;
+  const filled: Record<string, unknown> = {};
+  for (const [name, v] of Object.entries({
+    ...filterDefaults,
+    ...state.filters,
+  })) {
+    if (isEmptyValue(v)) continue;
+    const filter = action.filters?.[name];
+    if (
+      filter?.type === "date" &&
+      !isValidDateFilterValue(v, filter.multiple === true)
+    )
+      continue;
+    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 = applyPeriod
+    ? (state.period ??
+      action.periods?.find((p) => p.default === true)?.value ??
+      action.periods?.[0]?.value ??
+      null)
+    : 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);
+  }
+  const result: Record<string, unknown> = {
+    ...input,
+    ...filled,
+    ...(range !== null ? range : {}),
+    ...(state.q.trim() !== "" ? { q: state.q.trim() } : {}),
+    ...(sort !== null ? { sort: `${sort.field}:${sort.dir}` } : {}),
+    // Paginação server-driven: o handler implementa OFFSET e devolve `total`.
+    limit: state.limit ?? pageSize,
+    page: state.page,
+  };
+  if (action.paginate === false) {
+    delete result.limit;
+    delete result.page;
+  }
+  return result;
+}
+
 /** Estado da toolbar → querystring ('' ou '?…'), omitindo defaults (URL limpa). */
 export function listStateToParams(
   state: ActionListState,
@@ -3164,8 +3392,10 @@ export function listStateToParams(
   }
   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));
+  if (action.paginate !== false && state.limit !== null)
+    qs.set("limit", String(state.limit));
+  if (action.paginate !== false && state.page > 1)
+    qs.set("page", String(state.page));
   if (
     state.groupBy !== undefined &&
     state.groupBy !== null &&