@softize/opus 25.2.0 → 25.3.1

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

@@ -38,6 +38,7 @@ import {
   Calendar as CalendarIcon,
   Check,
   ChevronDown,
+  ChevronRight,
   Eraser,
   Filter,
   RotateCw,
@@ -65,6 +66,7 @@ import {
   useLookupAction,
   type DictLike,
 } from "../../drivers/react.tsx";
+import { useGroupedListAction } from "./grouped-list.ts";
 import { cn } from "../../lib/cn.ts";
 import { FillBoundary, useFillLeaf } from "./fill-region.ts";
 import { objectSchemaShape } from "../../lib/object-schema.ts";
@@ -82,6 +84,7 @@ import {
   PaginationPrevious,
 } from "../primitives/pagination.tsx";
 import { Button } from "../primitives/button.tsx";
+import { focusRing } from "../primitives/control.ts";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Calendar } from "../primitives/calendar.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
@@ -205,6 +208,8 @@ export interface ActionListState {
   limit: number | null;
   /** Página atual (1-based). Mudar filtro/busca/sort/período volta pra 1. */
   page: number;
+  /** Dimensão ativa de agrupamento. null mantém a listagem plana. */
+  groupBy?: string | null;
 }
 
 /** Um estado vazio/default — útil pra montar o inicial em quem controla. */
@@ -220,6 +225,7 @@ export function emptyListState(): ActionListState {
     columns: null,
     limit: null,
     page: 1,
+    groupBy: null,
   };
 }
 
@@ -270,6 +276,7 @@ export interface ListActionLike {
   sort?: { fields: string[]; default?: SortSpec[] } | undefined;
   text?: { fields: string[]; placeholder?: unknown } | undefined;
   periods?: PeriodSpec[] | undefined;
+  grouping?: { fields: string[] } | undefined;
 }
 
 /** Estado compartilhado pelos filtros declarativos, independente da listagem. */
@@ -1750,6 +1757,7 @@ export function ActionList<TInput, TItem>({
   onStateChange,
 }: ActionListProps<TInput, TItem>) {
   const confirmBodyId = useId();
+  const groupRegionId = useId();
   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']`).
@@ -1778,6 +1786,7 @@ export function ActionList<TInput, TItem>({
     columns: raw.columns ?? null,
     limit: raw.limit ?? null,
     page: raw.page ?? 1,
+    groupBy: raw.groupBy ?? null,
   };
   const setState = (next: ActionListState): void => {
     if (onStateChange !== undefined) onStateChange(next);
@@ -1804,6 +1813,34 @@ export function ActionList<TInput, TItem>({
     ),
   ];
   const activeView = state.view ?? viewEntries[0]?.[0] ?? "table";
+  const groupingFields = action.grouping?.fields ?? [];
+  const dicts = useDicts();
+  const availableGroupingFields = groupingFields.filter((field) => {
+    if (action.filters?.group !== undefined) return false;
+    const spec = action.filters?.[field];
+    if (
+      spec?.type !== "select" ||
+      (spec.options?.kind !== "static" && spec.options?.kind !== "dictionary")
+    )
+      return false;
+    const options = [
+      ...optionsFor(field, spec, filterOptions),
+      ...dictOptionsFor(spec, dicts),
+    ].filter(
+      (option, index, all) =>
+        all.findIndex((candidate) => candidate.value === option.value) ===
+        index,
+    );
+    return options.length > 0 && options.length <= 12;
+  });
+  const requestedGroupBy = state.groupBy ?? null;
+  const activeGroupBy =
+    children === undefined &&
+    activeView === "table" &&
+    requestedGroupBy !== null &&
+    availableGroupingFields.includes(requestedGroupBy)
+      ? requestedGroupBy
+      : null;
   const hasSegment = children === undefined && viewEntries.length > 1;
   const periods = action.periods ?? [];
   const hasToolbar =
@@ -1860,16 +1897,109 @@ export function ActionList<TInput, TItem>({
     } as TInput;
   }, [input, state, pageSize, filterDefaults]);
 
-  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>,
+  const inputKey = JSON.stringify([effectiveInput, activeGroupBy]);
+  const groupSpec =
+    activeGroupBy === null ? undefined : action.filters?.[activeGroupBy];
+  const declaredGroupOptions =
+    groupSpec === undefined
+      ? []
+      : [
+          ...optionsFor(activeGroupBy ?? "", groupSpec, filterOptions),
+          ...dictOptionsFor(groupSpec, dicts),
+        ].filter(
+          (option, index, all) =>
+            all.findIndex((candidate) => candidate.value === option.value) ===
+            index,
+        );
+  const selectedGroupFilter =
+    activeGroupBy === null
+      ? undefined
+      : (state.filters[activeGroupBy] ?? filterDefaults?.[activeGroupBy]);
+  const groupOptions = declaredGroupOptions.filter((option) =>
+    Array.isArray(selectedGroupFilter) && selectedGroupFilter.length > 0
+      ? selectedGroupFilter.includes(option.value)
+      : typeof selectedGroupFilter === "string" && selectedGroupFilter !== ""
+        ? selectedGroupFilter === option.value
+        : true,
+  );
+  const [groupPaging, setGroupPaging] = useState<{
+    key: string;
+    pages: Record<string, number>;
+  }>({ key: "", pages: {} });
+  const groupPages = groupPaging.key === inputKey ? groupPaging.pages : {};
+  const [groupCollapse, setGroupCollapse] = useState<{
+    key: string;
+    values: Set<string>;
+  }>({ 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" },
+    effectiveInput as Record<string, unknown>,
+    { enabled: activeGroupBy === null },
+  );
+  const grouped = useGroupedListAction<TItem, Record<string, unknown>>(
+    action as unknown as { name: string; kind: "list" },
+    effectiveInput as Record<string, unknown>,
+    activeGroupBy,
+    groupOptions.map((option) => option.value),
+    groupSpec?.multiple === true,
+    groupPages,
+    state.limit ?? pageSize,
+  );
+  const items =
+    activeGroupBy === null
+      ? flat.items
+      : grouped.flatMap((group) => group.items);
+  const visibleItems =
+    activeGroupBy === null
+      ? items
+      : grouped
+          .filter((group) => !collapsedGroups.has(group.value))
+          .flatMap((group) => group.items);
+  const total =
+    activeGroupBy === null
+      ? flat.total
+      : grouped.every((group) => group.total !== undefined)
+        ? grouped.reduce((sum, group) => sum + (group.total ?? 0), 0)
+        : undefined;
+  const isLoading =
+    activeGroupBy === null
+      ? flat.isLoading
+      : grouped.length > 0 && grouped.some((group) => group.isLoading);
+  const isFetching =
+    activeGroupBy === null
+      ? flat.isFetching
+      : grouped.some((group) => group.isFetching);
+  const missingGroupTotal =
+    activeGroupBy !== null &&
+    grouped.some(
+      (group) =>
+        !group.isLoading && !group.isError && group.total === undefined,
     );
+  const isError =
+    activeGroupBy === null
+      ? flat.isError
+      : missingGroupTotal || grouped.some((group) => group.isError);
+  const error =
+    activeGroupBy === null
+      ? flat.error
+      : missingGroupTotal
+        ? {
+            code: "action_list.grouping_total_missing",
+            category: "internal" as const,
+            message: "Não foi possível carregar os grupos desta lista.",
+            severity: "error" as const,
+            retriable: false,
+          }
+        : grouped.find((group) => group.error !== undefined)?.error;
+  const refetch = async (): Promise<void> => {
+    if (activeGroupBy === null) return flat.refetch();
+    await Promise.all(grouped.map((group) => group.refetch()));
+  };
   // — 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 dicts = useDicts();
   const derived: Array<ActionListColumn<TItem> & { spec?: ListColumnSpec }> =
     useMemo(() => {
       if (columns !== undefined) return columns;
@@ -1972,7 +2102,7 @@ export function ActionList<TInput, TItem>({
   const selectable = (item: TItem): boolean =>
     batchActions.some((a) => a.can?.(item) ?? true);
   const selectableItems =
-    batchActions.length > 0 ? items.filter(selectable) : [];
+    batchActions.length > 0 ? visibleItems.filter(selectable) : [];
   const hasSelection =
     batchActions.length > 0 &&
     selectableItems.length > 0 &&
@@ -1981,7 +2111,7 @@ export function ActionList<TInput, TItem>({
     // 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 selectedItems = visibleItems.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> => {
@@ -2065,6 +2195,41 @@ export function ActionList<TInput, TItem>({
                 data-slot="action-list-display"
               >
                 <div className="space-y-3">
+                  {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 />
+                      </>
+                    )}
                   {activeView === "table" && pickerColumns.length > 0 && (
                     <>
                       <div className="space-y-2">
@@ -2107,7 +2272,9 @@ export function ActionList<TInput, TItem>({
                   )}
                   <div className="space-y-2">
                     <span className="text-xs font-medium text-muted-foreground">
-                      Itens por página
+                      {activeGroupBy === null
+                        ? "Itens por página"
+                        : "Itens por grupo"}
                     </span>
                     <Select
                       size="sm"
@@ -2152,43 +2319,54 @@ export function ActionList<TInput, TItem>({
       (hasSelection ? 1 : 0) +
       (rowActions !== undefined ? 1 : 0),
   );
-  const tableRows = 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>{rowActions(item)}</RowActions>
-        </TableCell>
-      )}
-    </TableRow>
-  ));
+  const renderTableRows = (
+    rows: TItem[],
+    options?: { hidden?: boolean; idPrefix?: string },
+  ) =>
+    rows.map((item, idx) => (
+      <TableRow
+        // eslint-disable-next-line react/no-array-index-key
+        key={idx}
+        id={
+          options?.idPrefix === undefined
+            ? undefined
+            : `${options.idPrefix}-${idx}`
+        }
+        hidden={options?.hidden}
+        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>{rowActions(item)}</RowActions>
+          </TableCell>
+        )}
+      </TableRow>
+    ));
+  const tableRows = renderTableRows(items);
   let content: ReactNode;
   if (children !== undefined) {
     // Modo COMPOSIÇÃO: o layout é de quem compõe; a toolbar e os estados seguem daqui.
@@ -2263,14 +2441,33 @@ export function ActionList<TInput, TItem>({
             {rowActions !== undefined && <TableHead className="w-px" />}
           </TableRow>
         </TableHeader>
-        <TableBody
-          className={
-            tableStateActive
-              ? "h-full [&_[data-slot=data-state]]:h-full"
-              : undefined
-          }
-        >
-          {tableFillsAvailableHeight ? (
+        {activeGroupBy === null ? (
+          <TableBody
+            className={
+              tableStateActive
+                ? "h-full [&_[data-slot=data-state]]:h-full"
+                : undefined
+            }
+          >
+            {tableFillsAvailableHeight ? (
+              <DataState
+                loading={initialLoading}
+                error={isError ? error : null}
+                empty={isEmpty}
+                emptyMessage={emptyMessage}
+                {...(errorMessage !== undefined ? { errorMessage } : {})}
+                {...(retryLabel !== undefined ? { retryLabel } : {})}
+                onRetry={() => refetch()}
+                colSpan={tableColumnCount}
+              >
+                {tableRows}
+              </DataState>
+            ) : (
+              tableRows
+            )}
+          </TableBody>
+        ) : tableFillsAvailableHeight && tableStateActive ? (
+          <TableBody className="h-full [&_[data-slot=data-state]]:h-full">
             <DataState
               loading={initialLoading}
               error={isError ? error : null}
@@ -2281,12 +2478,127 @@ export function ActionList<TInput, TItem>({
               onRetry={() => refetch()}
               colSpan={tableColumnCount}
             >
-              {tableRows}
+              {null}
             </DataState>
-          ) : (
-            tableRows
-          )}
-        </TableBody>
+          </TableBody>
+        ) : (
+          grouped.map((group, groupIndex) => {
+            const option = groupOptions.find(
+              (candidate) => candidate.value === group.value,
+            );
+            const collapsed = collapsedGroups.has(group.value);
+            const loadedPages = groupPages[group.value] ?? 1;
+            const canLoadMore =
+              group.total !== undefined && group.items.length < group.total;
+            const groupLabel = option?.label ?? group.value;
+            const groupId = `${groupRegionId}-${groupIndex}-${group.value.replace(
+              /[^a-zA-Z0-9_-]/g,
+              "-",
+            )}`;
+            const bodyId = `${groupId}-body`;
+            const controlledIds = [
+              ...group.items.map((_, index) => `${bodyId}-${index}`),
+              ...(canLoadMore ? [`${bodyId}-load-more`] : []),
+            ];
+            return (
+              <TableBody
+                key={group.value}
+                data-group={group.value}
+                aria-labelledby={`${groupId}-label`}
+              >
+                <TableRow className="!bg-muted/40 hover:!bg-muted/60">
+                  <TableHead
+                    id={`${groupId}-label`}
+                    scope="rowgroup"
+                    colSpan={tableColumnCount}
+                    className="h-auto py-1.5 text-foreground"
+                  >
+                    <button
+                      type="button"
+                      aria-expanded={!collapsed}
+                      aria-controls={
+                        controlledIds.length > 0
+                          ? controlledIds.join(" ")
+                          : undefined
+                      }
+                      aria-label={`${groupLabel}, ${
+                        group.total === undefined
+                          ? "carregando"
+                          : `${group.total} ${group.total === 1 ? "item" : "itens"}`
+                      }`}
+                      className={cn(
+                        "flex w-full items-center gap-2 rounded-sm text-left font-medium outline-none",
+                        focusRing,
+                      )}
+                      onClick={() => {
+                        const next = new Set(collapsedGroups);
+                        if (collapsed) next.delete(group.value);
+                        else {
+                          next.add(group.value);
+                          const hidden = new Set(group.items.map(rowId));
+                          setSelected(
+                            new Set(
+                              [...selected].filter((id) => !hidden.has(id)),
+                            ),
+                          );
+                        }
+                        setGroupCollapse({ key: inputKey, values: next });
+                      }}
+                    >
+                      {collapsed ? (
+                        <ChevronRight className="size-4" />
+                      ) : (
+                        <ChevronDown className="size-4" />
+                      )}
+                      <span className="flex items-center gap-1.5">
+                        {option?.content ?? option?.label ?? group.value}
+                      </span>
+                      <span className="text-muted-foreground">
+                        {group.total ?? "…"}
+                      </span>
+                    </button>
+                  </TableHead>
+                </TableRow>
+                {renderTableRows(group.items, {
+                  hidden: collapsed,
+                  idPrefix: bodyId,
+                })}
+                {canLoadMore && (
+                  <TableRow
+                    id={`${bodyId}-load-more`}
+                    hidden={collapsed}
+                    className="hover:bg-transparent"
+                  >
+                    <TableCell
+                      colSpan={tableColumnCount}
+                      className="text-center"
+                    >
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        aria-label={`Carregar mais de ${groupLabel}`}
+                        busy={group.isFetching}
+                        onClick={() =>
+                          setGroupPaging((current) => ({
+                            key: inputKey,
+                            pages: {
+                              ...(current.key === inputKey
+                                ? current.pages
+                                : {}),
+                              [group.value]: loadedPages + 1,
+                            },
+                          }))
+                        }
+                      >
+                        Carregar mais
+                      </Button>
+                    </TableCell>
+                  </TableRow>
+                )}
+              </TableBody>
+            );
+          })
+        )}
       </Table>
     );
   }
@@ -2365,7 +2677,14 @@ export function ActionList<TInput, TItem>({
       : 1;
   const goTo = (page: number): void => setState({ ...state, page });
   const footer =
-    total !== undefined && !isError ? (
+    total !== undefined && !isError && activeGroupBy !== null ? (
+      <div
+        data-slot="action-list-footer"
+        className="flex min-h-10 items-center justify-end border-t border-border px-3 py-1 text-xs text-muted-foreground"
+      >
+        {total} {total === 1 ? "item" : "itens"} no total
+      </div>
+    ) : total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
         className="grid min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
@@ -2459,7 +2778,9 @@ export function ActionList<TInput, TItem>({
               className={cn(
                 "min-h-0",
                 layout === "fill" && "overflow-auto",
-                busy && items.length > 0 && "pointer-events-none opacity-60",
+                busy &&
+                  items.length > 0 &&
+                  "pointer-events-none opacity-60",
               )}
             >
               {body}
@@ -2568,6 +2889,11 @@ export function listParamsToState(
   const periodParam = params.get("period");
   const range =
     periodParam?.match(/^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/) ?? null;
+  const groupParam = params.get("group");
+  const groupBy =
+    groupParam !== null && (action.grouping?.fields ?? []).includes(groupParam)
+      ? groupParam
+      : null;
   return {
     q: params.get("q") ?? "",
     sort,
@@ -2579,6 +2905,7 @@ export function listParamsToState(
     columns: cols !== null && cols !== "" ? cols.split(",") : null,
     limit: Number.isInteger(limitParam) && limitParam > 0 ? limitParam : null,
     page: Number.isInteger(page) && page > 1 ? page : 1,
+    groupBy,
   };
 }
 
@@ -2622,6 +2949,13 @@ export function listStateToParams(
   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 (
+    state.groupBy !== undefined &&
+    state.groupBy !== null &&
+    (action.grouping?.fields ?? []).includes(state.groupBy)
+  ) {
+    qs.set("group", state.groupBy);
+  }
   const s = qs.toString();
   return s === "" ? "" : `?${s}`;
 }

package/src/ui/components/primitives/floating-layer.tsx

@@ -14,7 +14,9 @@ export interface FloatingLayerProps {
   /**
    * Esc enquanto a pessoa está na camada, com ou sem modal aberto. É chamado uma vez por tecla.
    * Nenhum modal fecha nesse caso, e o Opus não fecha a camada sozinho, porque o estado de aberto
-   * pertence ao consumidor.
+   * pertence ao consumidor. Sem o handler, o Esc com a pessoa na camada fecha o modal de trabalho
+   * aberto: passe `undefined` enquanto a camada não tiver o que fechar, como com o painel fechado e
+   * só o botão que o abre.
    */
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
 }
@@ -49,9 +51,7 @@ export function FloatingLayer({
     const element = document.createElement("div");
     element.setAttribute("data-slot", "floating-layer");
     document.body.appendChild(element);
-    const unregister = registerFloatingLayer(element, (event) =>
-      escapeRef.current?.(event),
-    );
+    const unregister = registerFloatingLayer(element, () => escapeRef.current);
     setHost(element);
     // Desfaz o registro, retira o hospedeiro e, se o foco estava nele com um modal aberto,
     // devolve o foco ao modal.