@softize/opus 18.2.0 → 18.3.0

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

@@ -24,11 +24,11 @@ import {
   Fragment,
   isValidElement,
   useEffect,
-  useLayoutEffect,
   useId,
   useMemo,
   useRef,
   useState,
+  type ComponentProps,
   type ReactNode,
 } from "react";
 import {
@@ -36,6 +36,8 @@ import {
   ArrowUp,
   ArrowUpDown,
   Calendar as CalendarIcon,
+  Check,
+  ChevronDown,
   Eraser,
   Filter,
   RotateCw,
@@ -67,6 +69,7 @@ import { cn } from "../../lib/cn.ts";
 import { objectSchemaShape } from "../../lib/object-schema.ts";
 import { Badge } from "../primitives/badge.tsx";
 import { DictionaryValue } from "../primitives/dictionary-value.tsx";
+import { Dot } from "../primitives/dot.tsx";
 import { EmptyValue, isAbsentValue } from "../primitives/empty-value.tsx";
 import {
   Pagination,
@@ -81,6 +84,12 @@ import { Button } from "../primitives/button.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Calendar } from "../primitives/calendar.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
+import {
+  Command,
+  CommandGroup,
+  CommandItem,
+  CommandList,
+} from "../primitives/command.tsx";
 import {
   Popover,
   PopoverContent,
@@ -103,11 +112,7 @@ import {
 } from "../primitives/input-group.tsx";
 import { Separator } from "../primitives/separator.tsx";
 import { Label } from "../primitives/label.tsx";
-import {
-  FieldGroup,
-  FieldLegend,
-  FieldSet,
-} from "../primitives/field.tsx";
+import { FieldGroup, FieldLegend, FieldSet } from "../primitives/field.tsx";
 import { Search } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
 import {
@@ -273,20 +278,35 @@ export interface ActionFilterBarProps {
   state: ActionFilterState;
   onStateChange: (next: ActionFilterState) => void;
   filterOptions?: Record<string, SelectOption[]>;
+  /** Valor de repouso por filtro simples. O limpar só aparece fora desse estado e retorna a ele. */
+  filterDefaults?: Record<string, string>;
+  /** Ícone leading por filtro, projetado no controle derivado sem alterar o contrato. */
+  filterIcons?: Record<string, ReactNode>;
   /** Composição visual do diálogo de filtros avançados. A largura é derivada
    *  internamente do número de colunas. */
   advancedFilters?: AdvancedFiltersLayout;
   onRefresh?: () => Promise<void> | void;
   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 };
+  /** 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. */
   controls?: ReactNode;
   /** Ações do consumidor, separadas do grupo de controles. */
   actions?: ReactNode;
 }
 
+export interface PeriodLayout {
+  /** Nome do filtro inline que escolhe qual data o período recorta. */
+  basisFilter: string;
+}
+
 export interface AdvancedFiltersLayout {
   /** Número de colunas dos grupos de filtros. */
   columns?: 1 | 2 | 3;
+  /** Ícone de cada seção, indexado pelo mesmo rótulo declarado nos filtros. */
+  sectionIcons?: Record<string, ReactNode>;
 }
 
 /** Uma view alternativa da MESMA listagem (board, galeria, lista, calendário…). A
@@ -316,6 +336,8 @@ export interface ActionListProps<TInput, TItem> {
   action: ListActionLike;
   /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
   input: TInput;
+  /** `fill` ocupa a altura disponível e mantém a rolagem dentro da região de resultados. */
+  layout?: "flow" | "fill";
   /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
   toolbarActions?: ReactNode;
   /** Tabela explícita — sobrepõe as colunas do contrato. */
@@ -324,8 +346,16 @@ export interface ActionListProps<TInput, TItem> {
   cells?: Record<string, (item: TItem) => ReactNode>;
   /** Opções de runtime pros filtros select/lookup (chave = nome do filtro). */
   filterOptions?: Record<string, SelectOption[]>;
+  /** Valor de repouso por filtro simples. */
+  filterDefaults?: Record<string, string>;
+  /** Ícone leading por filtro, projetado no controle derivado sem alterar o contrato. */
+  filterIcons?: Record<string, ReactNode>;
   /** Composição visual do diálogo de filtros avançados. Default: uma coluna. */
   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 };
+  /** 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
    *  tabela ('table', quando há columns) e estas. Ex.: { board: { label, render } }. */
   views?: Record<string, ActionListView<TItem>>;
@@ -478,6 +508,9 @@ function FilterField({
   value,
   onChange,
   options,
+  icon,
+  embedded = false,
+  defaultValue = "",
   allValues,
   className,
 }: {
@@ -486,11 +519,16 @@ function FilterField({
   value: unknown;
   onChange: (v: unknown) => void;
   options: SelectOption[];
+  /** Ícone leading do controle, definido pela superfície consumidora. */
+  icon?: ReactNode;
+  /** Remove a casca própria quando o filtro participa de um controle composto. */
+  embedded?: boolean;
+  /** Valor ao qual a ação de limpar retorna. */
+  defaultValue?: string;
   /** Todos os valores de filtro vigentes — habilita `depends` e alimenta o lookup. */
   allValues: Record<string, unknown>;
-  /** Largura do contexto: inline, cada tipo tem largura fixa e previsível (select `w-40`,
-   *  lookup e múltiplo `w-52`, texto `w-40`); nunca cresce pelo conteúdo. O modal manda
-   *  `w-full`, que vence pelo merge de classes. */
+  /** Largura do contexto. Sem override, selects de valor único acompanham o valor dentro
+   *  de limites previsíveis; múltiplo e texto mantêm largura fixa. O modal manda `w-full`. */
   className?: string;
 }): React.ReactElement {
   const label = text(spec.label, name);
@@ -504,7 +542,21 @@ function FilterField({
   // 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;
+  const effOptions =
+    lookup.onSearch !== undefined && base.length > 0
+      ? [
+          ...base,
+          ...lookup.options.filter(
+            (candidate) =>
+              !base.some((option) => option.value === candidate.value),
+          ),
+        ]
+      : base.length > 0
+        ? base
+        : lookup.options;
+  const singleValue = (value as string | undefined) ?? defaultValue;
+  const changedFromDefault = singleValue !== defaultValue;
+  const acceptsEmptyValue = spec.allowEmpty !== false;
 
   if (spec.multiple === true) {
     return (
@@ -516,8 +568,9 @@ function FilterField({
         value={(value as string[] | undefined) ?? []}
         onChange={(v) => onChange(v)}
         options={effOptions}
+        icon={icon}
         placeholder={placeholder}
-        className={cn("w-52", className)}
+        className={className ?? "w-52"}
         disabled={!enabled}
         {...(lookup.onSearch !== undefined
           ? { onSearch: lookup.onSearch, loading: lookup.loading }
@@ -528,16 +581,24 @@ function FilterField({
   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).
+    const ALL = "__all__";
     return (
       <Select
         searchable
-        clearable
+        clearable={embedded ? false : changedFromDefault}
         id={`filter-${name}`}
-        value={(value as string | undefined) ?? ""}
-        onChange={(v) => onChange(v)}
-        options={effOptions}
+        value={singleValue === "" ? ALL : singleValue}
+        onChange={(v) => onChange(v === "" ? defaultValue : v === ALL ? "" : v)}
+        options={[
+          ...(acceptsEmptyValue
+            ? [{ value: ALL, label: text(spec.placeholder, "Todos") }]
+            : []),
+          ...effOptions.filter((option) => option.value !== ALL),
+        ]}
+        icon={icon}
+        variant={embedded ? "ghost" : "default"}
         placeholder={placeholder}
-        className={cn("w-52", className)}
+        className={className ?? "w-fit min-w-0 max-w-full"}
         disabled={!enabled}
         {...(lookup.onSearch !== undefined
           ? { onSearch: lookup.onSearch, loading: lookup.loading }
@@ -551,18 +612,21 @@ function FilterField({
     const ALL = "__all__";
     return (
       <Select
-        clearable
+        searchable={spec.searchable === true}
+        clearable={embedded ? false : changedFromDefault}
         id={`filter-${name}`}
-        value={
-          ((value as string | undefined) ?? "") === "" ? ALL : (value as string)
-        }
-        onChange={(v) => onChange(v === ALL ? "" : v)}
+        value={singleValue === "" ? ALL : singleValue}
+        onChange={(v) => onChange(v === "" ? defaultValue : v === ALL ? "" : v)}
         options={[
-          { value: ALL, label: text(spec.placeholder, "Todos") },
+          ...(acceptsEmptyValue
+            ? [{ value: ALL, label: text(spec.placeholder, "Todos") }]
+            : []),
           ...base,
         ]}
+        icon={icon}
+        variant={embedded ? "ghost" : "default"}
         disabled={!enabled}
-        className={cn("w-40", className)}
+        className={className ?? "w-fit min-w-0 max-w-full"}
       />
     );
   }
@@ -570,11 +634,11 @@ function FilterField({
     return (
       <DateFilterField
         id={`filter-${name}`}
-        value={(value as string | undefined) ?? ""}
+        value={singleValue}
         placeholder={placeholder}
         className={cn("w-40", className)}
         disabled={!enabled}
-        onChange={onChange}
+        onChange={(next) => onChange(next === "" ? defaultValue : next)}
       />
     );
   }
@@ -584,7 +648,8 @@ function FilterField({
     <ClearableInput
       id={`filter-${name}`}
       type={type}
-      applied={(value as string | undefined) ?? ""}
+      applied={singleValue}
+      clearValue={defaultValue}
       placeholder={placeholder}
       className={cn("w-40", className)}
       disabled={!enabled}
@@ -656,7 +721,12 @@ function DateFilterField({
           disabled={disabled}
         >
           <CalendarIcon className="h-3.5 w-3.5 shrink-0" />
-          <span className={cn("truncate", selected === undefined && "text-muted-foreground")}>
+          <span
+            className={cn(
+              "truncate",
+              selected === undefined && "text-muted-foreground",
+            )}
+          >
             {label}
           </span>
         </Button>
@@ -694,12 +764,14 @@ function DateFilterField({
 }
 
 /** 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. */
+ *  entra por composição — addon à direita, visível quando o valor diverge do repouso.
+ *  Uncontrolled (aplica no blur/Enter, como a busca); o X restaura e aplica o repouso. */
 function ClearableInput({
   id,
   type,
   applied,
+  clearValue = "",
+  shape = "default",
   placeholder,
   className,
   leading,
@@ -709,6 +781,10 @@ function ClearableInput({
   id?: string;
   type?: string;
   applied: string;
+  /** Valor restaurado pela ação de limpar. */
+  clearValue?: string;
+  /** Forma visual do grupo; a busca da toolbar usa pill. */
+  shape?: ComponentProps<typeof InputGroup>["shape"];
   placeholder?: string;
   className?: string;
   /** Addon à esquerda (ex.: a lupa da busca). */
@@ -717,15 +793,15 @@ function ClearableInput({
   onApply: (v: string) => void;
 }): React.ReactElement {
   const inputRef = useRef<HTMLInputElement | null>(null);
-  const [hasText, setHasText] = useState(applied !== "");
+  const [canClear, setCanClear] = useState(applied !== clearValue);
   // 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]);
+    setCanClear(applied !== clearValue);
+  }, [applied, clearValue]);
   return (
-    <InputGroup className={className}>
+    <InputGroup className={className} shape={shape}>
       {leading !== undefined && <InputGroupAddon>{leading}</InputGroupAddon>}
       <InputGroupInput
         ref={inputRef}
@@ -735,7 +811,7 @@ function ClearableInput({
         disabled={disabled}
         defaultValue={applied}
         placeholder={placeholder}
-        onChange={(e) => setHasText(e.target.value !== "")}
+        onChange={(e) => setCanClear(e.target.value !== clearValue)}
         onBlur={(e) => {
           if (e.target.value !== applied) onApply(e.target.value);
         }}
@@ -746,14 +822,17 @@ function ClearableInput({
           }
         }}
       />
-      {hasText && (
+      {canClear && (
         <InputGroupAddon align="inline-end">
           <InputGroupButton
+            size="icon-xs"
             aria-label="Limpar"
+            className="text-muted-foreground hover:text-foreground"
             onClick={() => {
-              if (inputRef.current !== null) inputRef.current.value = "";
-              setHasText(false);
-              onApply("");
+              if (inputRef.current !== null)
+                inputRef.current.value = clearValue;
+              setCanClear(false);
+              onApply(clearValue);
             }}
           >
             <X className="size-3.5" />
@@ -792,23 +871,34 @@ function Labeled({
   label,
   children,
   slot,
+  showLabel = true,
+  className,
 }: {
   label: string;
   children: ReactNode;
-  /** data-slot do wrapper (ex.: marca os filtros inline pro overflow responsivo). */
+  /** data-slot do wrapper (ex.: identifica os filtros inline na barra). */
   slot?: string;
+  /** Omite a label quando o controle é o único recorte inline da barra. */
+  showLabel?: boolean;
+  /** Limite externo do controle; o wrapper pode encolher junto com a toolbar. */
+  className?: string;
 }): React.ReactElement {
   return (
-    <div data-slot={slot} className="flex shrink-0 flex-col gap-1">
+    <div
+      data-slot={slot}
+      className={cn("flex min-w-0 shrink flex-col gap-1", className)}
+    >
       {/* w-0 + min-w-full: a label acompanha a largura do controle e nunca a dita —
           um rótulo longo trunca em vez de alargar o filtro. */}
-      <span
-        data-slot="action-filter-label"
-        title={label}
-        className="block w-0 min-w-full truncate px-0.5 text-xs font-medium text-muted-foreground"
-      >
-        {label}
-      </span>
+      {showLabel ? (
+        <span
+          data-slot="action-filter-label"
+          title={label}
+          className="block w-0 min-w-full truncate px-0.5 text-xs font-medium text-muted-foreground"
+        >
+          {label}
+        </span>
+      ) : null}
       {children}
     </div>
   );
@@ -829,12 +919,18 @@ function PeriodControl({
   period,
   from,
   to,
+  clearable,
+  embedded = false,
+  onClear,
   onChange,
 }: {
   periods: PeriodSpec[];
   period: string | null;
   from: string | null;
   to: string | null;
+  clearable: boolean;
+  embedded?: boolean;
+  onClear?: () => void;
   onChange: (next: {
     period: string | null;
     from: string | null;
@@ -878,48 +974,94 @@ function PeriodControl({
         }
       }}
     >
-      <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="relative w-fit min-w-0 max-w-full">
+        <PopoverTrigger asChild>
+          <Button
+            variant={embedded ? "ghost" : "outline"}
+            data-slot="action-list-period"
+            className={cn(
+              "max-w-full gap-1.5 overflow-hidden bg-muted/30 px-3 hover:bg-muted/30 hover:text-foreground dark:bg-input/30 dark:hover:bg-input/30",
+              clearable && "pr-10",
+              embedded &&
+                "gap-1 rounded-none border-0 bg-transparent pl-0 pr-0 font-normal shadow-none hover:bg-transparent focus-visible:ring-0 focus-visible:ring-offset-0 dark:bg-transparent dark:hover:bg-transparent",
+            )}
+          >
+            {embedded ? null : <CalendarIcon className="h-3.5 w-3.5" />}
+            <span className="min-w-0 truncate">{label}</span>
+            {embedded ? (
+              <span className="shrink-0 opacity-50">
+                <ChevronDown className="size-4" aria-hidden="true" />
+              </span>
+            ) : null}
+          </Button>
+        </PopoverTrigger>
+        {clearable ? (
+          <InputGroupButton
+            size="icon-xs"
+            aria-label="Limpar período"
+            className="absolute top-1/2 right-1.5 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+            onClick={() => {
+              setOpen(false);
+              setShowCalendar(false);
+              setDraft(undefined);
+              onClear?.();
+            }}
+          >
+            <X className="size-3.5" />
+          </InputGroupButton>
+        ) : null}
+      </div>
+      <PopoverContent
+        align="start"
+        className="w-auto min-w-(--radix-popover-trigger-width) p-0"
+      >
         <div className="flex">
-          <div
+          <Command
             className={cn(
-              "flex min-w-36 flex-col gap-0.5 p-2",
+              "h-auto min-w-40 rounded-none",
               showCalendar && "border-r border-border",
             )}
           >
-            {periods.map((p) => (
-              <Button
-                key={p.value}
-                size="sm"
-                context={period === p.value ? "primary" : "neutral"}
-                variant={period === p.value ? "solid" : "ghost"}
-                className="justify-start"
-                onClick={() => {
-                  onChange({ period: p.value, from: null, to: null });
-                  setOpen(false);
-                }}
-              >
-                {text(p.label, p.value)}
-              </Button>
-            ))}
-            <Button
-              size="sm"
-              context={period === "custom" ? "neutral" : "primary"}
-              variant={period === "custom" ? "solid" : "ghost"}
-              className="justify-start"
-              onClick={() => {
-                setShowCalendar(true);
-                setDraft(undefined);
-              }}
-            >
-              Personalizado
-            </Button>
-          </div>
+            <CommandList className="max-h-none">
+              <CommandGroup>
+                {periods.map((p) => (
+                  <CommandItem
+                    key={p.value}
+                    value={text(p.label, p.value)}
+                    onSelect={() => {
+                      onChange({ period: p.value, from: null, to: null });
+                      setOpen(false);
+                    }}
+                  >
+                    <span className="min-w-0 flex-1 truncate">
+                      {text(p.label, p.value)}
+                    </span>
+                    <Check
+                      className={cn(
+                        "ml-auto size-4",
+                        period === p.value ? "opacity-100" : "opacity-0",
+                      )}
+                    />
+                  </CommandItem>
+                ))}
+                <CommandItem
+                  value="Personalizado"
+                  onSelect={() => {
+                    setShowCalendar(true);
+                    setDraft(undefined);
+                  }}
+                >
+                  <span className="min-w-0 flex-1 truncate">Personalizado</span>
+                  <Check
+                    className={cn(
+                      "ml-auto size-4",
+                      period === "custom" ? "opacity-100" : "opacity-0",
+                    )}
+                  />
+                </CommandItem>
+              </CommandGroup>
+            </CommandList>
+          </Command>
           {showCalendar && (
             <Calendar
               mode="range"
@@ -960,6 +1102,9 @@ function AdvancedFiltersDialog({
   values,
   onApply,
   filterOptions,
+  filterDefaults,
+  filterIcons,
+  sectionIcons,
   cascade,
   columns = 1,
 }: {
@@ -969,6 +1114,9 @@ function AdvancedFiltersDialog({
   values: Record<string, unknown>;
   onApply: (next: Record<string, unknown>) => void;
   filterOptions?: Record<string, SelectOption[]> | undefined;
+  filterDefaults?: Record<string, string> | undefined;
+  filterIcons?: Record<string, ReactNode> | undefined;
+  sectionIcons?: Record<string, ReactNode> | undefined;
   columns?: 1 | 2 | 3;
   /** A cascata do `depends` do pai — mudar um campo limpa os dependentes no draft. */
   cascade: (
@@ -1015,13 +1163,19 @@ function AdvancedFiltersDialog({
         className="w-full"
         onChange={(v) => setDraft((d) => cascade(name, { ...d, [name]: v }))}
         options={optionsFor(name, spec, filterOptions)}
+        defaultValue={filterDefaults?.[name]}
+        icon={filterIcons?.[name]}
       />
     </div>
   );
 
   const clear = (): void => {
     const cleared = { ...draft };
-    for (const [name] of specs) delete cleared[name];
+    for (const [name] of specs) {
+      const defaultValue = filterDefaults?.[name];
+      if (defaultValue === undefined) delete cleared[name];
+      else cleared[name] = defaultValue;
+    }
     onApply(cleared);
     onOpenChange(false);
   };
@@ -1038,25 +1192,30 @@ function AdvancedFiltersDialog({
           <DialogTitle>Filtros</DialogTitle>
         </DialogHeader>
         <DialogBody className="space-y-4">
-          {sectioned
-            ? sections.map(([section, entries]) => (
-                <FieldSet key={section}>
-                  <FieldLegend variant="label">{section}</FieldLegend>
-                  <FieldGroup className={cn("grid gap-4", gridColumns)}>
-                    {entries.map(field)}
-                  </FieldGroup>
-                </FieldSet>
-              ))
-            : (
+          {sectioned ? (
+            sections.map(([section, entries]) => (
+              <FieldSet key={section} className="gap-0">
+                <FieldLegend variant="section" icon={sectionIcons?.[section]}>
+                  {section}
+                </FieldLegend>
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
-                  {specs.map(field)}
+                  {entries.map(field)}
                 </FieldGroup>
-              )}
+              </FieldSet>
+            ))
+          ) : (
+            <FieldGroup className={cn("grid gap-4", gridColumns)}>
+              {specs.map(field)}
+            </FieldGroup>
+          )}
         </DialogBody>
-        <DialogFooter>
-          <ButtonGroup mode="spaced" distribution="equal">
-            <Button variant="outline" onClick={clear}>
-              Limpar
+        <DialogFooter className="justify-between">
+          <Button variant="ghost" icon={<Eraser />} onClick={clear}>
+            Limpar
+          </Button>
+          <ButtonGroup mode="spaced">
+            <Button variant="ghost" onClick={() => onOpenChange(false)}>
+              Cancelar
             </Button>
             <Button onClick={apply}>Aplicar</Button>
           </ButtonGroup>
@@ -1072,9 +1231,13 @@ export function ActionFilterBar({
   state,
   onStateChange,
   filterOptions,
+  filterDefaults,
+  filterIcons,
   advancedFilters,
   onRefresh,
   refreshing = false,
+  periodPosition = "before",
+  period,
   controls,
   actions,
 }: ActionFilterBarProps): React.ReactElement {
@@ -1093,9 +1256,11 @@ export function ActionFilterBar({
     periods[0]?.value ??
     null;
   const activePeriod = state.period ?? defaultPeriod;
+  const periodBasisEntry =
+    periods.length > 0 && period !== undefined
+      ? inlineSpecs.find(([name]) => name === period.basisFilter)
+      : undefined;
   const [advancedOpen, setAdvancedOpen] = useState(false);
-  const toolbarRowRef = useRef<HTMLDivElement | null>(null);
-  const [inlineFit, setInlineFit] = useState(Number.POSITIVE_INFINITY);
 
   const cascadeClear = (
     changed: string,
@@ -1113,41 +1278,8 @@ export function ActionFilterBar({
     return next;
   };
 
-  useLayoutEffect(() => {
-    const row = toolbarRowRef.current;
-    if (row === null) return;
-    const overflowing = (): boolean =>
-      row.scrollWidth > row.clientWidth + 1 ||
-      Array.from(row.children).some(
-        (child) => child.scrollWidth > child.clientWidth + 1,
-      );
-    const compute = (): void => {
-      row.classList.remove("flex-wrap");
-      const nodes = Array.from(
-        row.querySelectorAll<HTMLElement>('[data-slot="action-filter-inline"]'),
-      );
-      for (const node of nodes) node.style.removeProperty("display");
-      let count = nodes.length;
-      while (count > 0 && overflowing()) {
-        count -= 1;
-        nodes[count]?.style.setProperty("display", "none");
-      }
-      if (count === 0 && overflowing()) row.classList.add("flex-wrap");
-      setInlineFit(count >= nodes.length ? Number.POSITIVE_INFINITY : count);
-    };
-    compute();
-    const observer = new ResizeObserver(compute);
-    observer.observe(row);
-    return () => observer.disconnect();
-  }, [inlineSpecs.length, state.filters, inlineFit]);
-
-  const overflowSpecs = Number.isFinite(inlineFit)
-    ? inlineSpecs.slice(inlineFit)
-    : [];
   const modalSpecs = visibleFilterSpecs.filter(
-    ([name, spec]) =>
-      filterPlacement(spec) === "advanced" ||
-      overflowSpecs.some(([overflowName]) => overflowName === name),
+    ([, spec]) => filterPlacement(spec) === "advanced",
   );
   const setFilter = (name: string, value: unknown): void => {
     onStateChange({
@@ -1156,7 +1288,10 @@ export function ActionFilterBar({
     });
   };
   const chips = modalSpecs
-    .filter(([name]) => !isEmptyValue(state.filters[name]))
+    .filter(([name]) => {
+      const value = state.filters[name] ?? filterDefaults?.[name] ?? "";
+      return !isEmptyValue(value) && value !== (filterDefaults?.[name] ?? "");
+    })
     .map(([name, spec]) => {
       const raw = state.filters[name];
       const fromProps = optionsFor(name, spec, filterOptions);
@@ -1170,76 +1305,227 @@ export function ActionFilterBar({
         value: Array.isArray(raw) ? raw.map(display).join(", ") : display(raw),
       };
     });
-  const searchFirst =
-    hasSearch && periods.length === 0 && visibleFilterSpecs.length === 0;
+  const inlineControlCount =
+    inlineSpecs.filter(([name]) => name !== periodBasisEntry?.[0]).length +
+    (periods.length > 0 ? 1 : 0) +
+    (hasSearch ? 1 : 0);
+  const showInlineLabels = inlineControlCount > 1;
+  const searchAtActionsEnd =
+    hasSearch && (inlineSpecs.length > 0 || periods.length > 0);
+  const periodAfterFilter =
+    typeof periodPosition === "object" ? periodPosition.afterFilter : null;
+  const anchoredPeriodExists = inlineSpecs.some(
+    ([name]) => name === periodAfterFilter,
+  );
+  const periodField =
+    periods.length > 0 ? (
+      <PeriodControl
+        periods={periods}
+        period={activePeriod}
+        from={state.from}
+        to={state.to}
+        clearable={state.period !== null}
+        onClear={() =>
+          onStateChange({
+            ...state,
+            period: null,
+            from: null,
+            to: null,
+          })
+        }
+        onChange={(next) =>
+          onStateChange({
+            ...state,
+            ...next,
+            period: next.period === defaultPeriod ? null : next.period,
+          })
+        }
+      />
+    ) : null;
+  const periodControl =
+    periodField === null || periodBasisEntry !== undefined ? null : (
+      <Labeled
+        label="Período"
+        showLabel={showInlineLabels}
+        className="max-w-80"
+      >
+        {periodField}
+      </Labeled>
+    );
+  const periodBasisDefault =
+    periodBasisEntry === undefined
+      ? ""
+      : (filterDefaults?.[periodBasisEntry[0]] ?? "");
+  const periodBasisValue =
+    periodBasisEntry === undefined
+      ? ""
+      : ((state.filters[periodBasisEntry[0]] as string | undefined) ??
+        periodBasisDefault);
+  const periodGroupClearable =
+    periodBasisEntry !== undefined &&
+    (state.period !== null || periodBasisValue !== periodBasisDefault);
   const searchBox = hasSearch ? (
-    <ClearableInput
-      className="w-64 min-w-36"
-      leading={<Search />}
-      applied={state.q}
-      placeholder={text(action.text?.placeholder, "Buscar…")}
-      onApply={(q) => q !== state.q && onStateChange({ ...state, q })}
-    />
+    <Labeled
+      label="Busca"
+      slot="action-filter-search"
+      showLabel={showInlineLabels}
+      className="w-[clamp(8rem,20vw,16rem)] max-w-64 basis-[clamp(8rem,20vw,16rem)]"
+    >
+      <ClearableInput
+        className="w-full min-w-0"
+        shape="pill"
+        leading={<Search />}
+        applied={state.q}
+        placeholder={text(action.text?.placeholder, "Buscar…")}
+        onApply={(q) => q !== state.q && onStateChange({ ...state, q })}
+      />
+    </Labeled>
   ) : null;
 
   return (
     <TooltipProvider>
       <div data-slot="action-filter-bar" className="space-y-2">
-        <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) =>
-                  onStateChange({
-                    ...state,
-                    ...next,
-                    period: next.period === defaultPeriod ? null : next.period,
-                  })
-                }
-              />
-            </Labeled>
-          )}
-          {inlineSpecs.map(([name, spec]) => (
-            <Labeled
-              key={name}
-              label={text(spec.label, name)}
-              slot="action-filter-inline"
-            >
-              <FilterField
-                name={name}
-                spec={spec}
-                value={state.filters[name]}
-                allValues={state.filters}
-                onChange={(value) => setFilter(name, value)}
-                options={optionsFor(name, spec, filterOptions)}
-              />
-            </Labeled>
-          ))}
-          {modalSpecs.length > 0 && (
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button
-                  variant="ghost"
-                  size="icon"
-                  className="shrink-0"
-                  aria-label="Filtros"
-                  onClick={() => setAdvancedOpen(true)}
+        <div className="flex min-w-0 items-end gap-3">
+          {periodPosition === "before" && periodControl}
+          {inlineSpecs.map(([name, spec]) => {
+            if (name === periodBasisEntry?.[0]) {
+              return (
+                <Labeled
+                  key={name}
+                  label="Período"
+                  showLabel={showInlineLabels}
+                  className="max-w-80"
                 >
-                  <Filter className="h-3.5 w-3.5" />
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent>Filtros</TooltipContent>
-            </Tooltip>
-          )}
-          <div className="ml-auto flex min-w-0 items-center gap-2">
-            {!searchFirst && searchBox}
-            {(onRefresh !== undefined || controls !== undefined) && (
+                  <div
+                    data-slot="action-filter-period-group"
+                    className={cn(
+                      "flex min-h-9 w-fit min-w-0 max-w-full items-center rounded-md border border-input bg-muted/30 text-foreground transition-[color,box-shadow] focus-within:border-ring focus-within:ring-[0.1875rem] focus-within:ring-ring/50 dark:bg-input/30",
+                      !periodGroupClearable && "pr-3",
+                    )}
+                  >
+                    <CalendarIcon
+                      className="ml-3 size-3.5 shrink-0 text-muted-foreground"
+                      aria-hidden="true"
+                    />
+                    <FilterField
+                      name={name}
+                      spec={spec}
+                      value={state.filters[name]}
+                      allValues={state.filters}
+                      onChange={(value) => setFilter(name, value)}
+                      options={optionsFor(name, spec, filterOptions)}
+                      defaultValue={filterDefaults?.[name]}
+                      embedded
+                      className="w-fit min-w-0 max-w-80 [&_[data-slot=select-control]]:gap-1 [&_[data-slot=select-control]]:rounded-none [&_[data-slot=select-control]]:bg-transparent [&_[data-slot=select-control]]:pl-2 [&_[data-slot=select-control]]:pr-0 [&_[data-slot=select-control]]:font-normal [&_[data-slot=select-control]]:text-foreground [&_[data-slot=select-control]]:shadow-none [&_[data-slot=select-control]:hover]:bg-transparent [&_[data-slot=select-control]:focus-within]:ring-0 [&_[data-slot=select-control]:focus-within]:ring-offset-0"
+                    />
+                    <Separator
+                      data-slot="action-filter-period-separator"
+                      orientation="vertical"
+                      className="ml-1.5 mr-2.5 h-4 shrink-0"
+                    />
+                    <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,
+                        })
+                      }
+                    />
+                    {periodGroupClearable ? (
+                      <InputGroupButton
+                        size="icon-xs"
+                        aria-label="Limpar período"
+                        className="ml-0.5 mr-1.5 shrink-0 text-muted-foreground hover:text-foreground"
+                        onClick={() => {
+                          const filters = { ...state.filters };
+                          if (periodBasisDefault === "") delete filters[name];
+                          else filters[name] = periodBasisDefault;
+                          onStateChange({
+                            ...state,
+                            filters: cascadeClear(name, filters),
+                            period: null,
+                            from: null,
+                            to: null,
+                          });
+                        }}
+                      >
+                        <X className="size-3.5" />
+                      </InputGroupButton>
+                    ) : null}
+                  </div>
+                </Labeled>
+              );
+            }
+            return (
+              <Fragment key={name}>
+                <Labeled
+                  label={text(spec.label, name)}
+                  slot="action-filter-inline"
+                  showLabel={showInlineLabels}
+                  className="max-w-80"
+                >
+                  <FilterField
+                    name={name}
+                    spec={spec}
+                    value={state.filters[name]}
+                    allValues={state.filters}
+                    onChange={(value) => setFilter(name, value)}
+                    options={optionsFor(name, spec, filterOptions)}
+                    defaultValue={filterDefaults?.[name]}
+                    icon={filterIcons?.[name]}
+                  />
+                </Labeled>
+                {periodAfterFilter === name && periodControl}
+              </Fragment>
+            );
+          })}
+          {(periodPosition === "after" ||
+            (periodAfterFilter !== null && !anchoredPeriodExists)) &&
+            periodControl}
+          {!searchAtActionsEnd && searchBox}
+          <div
+            data-slot="action-filter-actions"
+            className="ml-auto flex min-w-0 items-end gap-2"
+          >
+            {searchAtActionsEnd && searchBox}
+            {(modalSpecs.length > 0 ||
+              onRefresh !== undefined ||
+              controls !== undefined) && (
               <ButtonGroup mode="spaced">
+                {modalSpecs.length > 0 && (
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="relative shrink-0"
+                        aria-label="Filtros"
+                        onClick={() => setAdvancedOpen(true)}
+                      >
+                        <Filter className="h-3.5 w-3.5" />
+                        {chips.length > 0 && (
+                          <Dot
+                            context="primary"
+                            className="absolute top-1 right-1 ring-2 ring-background"
+                          />
+                        )}
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      {chips.length === 0
+                        ? "Filtros"
+                        : `${chips.length} ${chips.length === 1 ? "filtro aplicado" : "filtros aplicados"}`}
+                    </TooltipContent>
+                  </Tooltip>
+                )}
                 {onRefresh !== undefined && (
                   <Tooltip>
                     <TooltipTrigger asChild>
@@ -1307,7 +1593,10 @@ export function ActionFilterBar({
             cascade={cascadeClear}
             onApply={(filters) => onStateChange({ ...state, filters })}
             filterOptions={filterOptions}
+            filterDefaults={filterDefaults}
+            filterIcons={filterIcons}
             columns={advancedFilters?.columns}
+            sectionIcons={advancedFilters?.sectionIcons}
           />
         )}
       </div>
@@ -1347,11 +1636,16 @@ function RowActions({ children }: { children: ReactNode }) {
 export function ActionList<TInput, TItem>({
   action,
   input,
+  layout = "flow",
   toolbarActions,
   columns,
   cells,
   filterOptions,
+  filterDefaults,
+  filterIcons,
   advancedFilters,
+  periodPosition,
+  period,
   views,
   batch,
   rowId = (item: TItem) => String((item as { id?: unknown }).id ?? ""),
@@ -1434,7 +1728,10 @@ export function ActionList<TInput, TItem>({
   // — 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)) {
+    for (const [name, v] of Object.entries({
+      ...filterDefaults,
+      ...state.filters,
+    })) {
       if (isEmptyValue(v)) continue;
       const filter = action.filters?.[name];
       if (
@@ -1473,7 +1770,7 @@ export function ActionList<TInput, TItem>({
       limit: state.limit ?? pageSize,
       page: state.page,
     } as TInput;
-  }, [input, state, pageSize]);
+  }, [input, state, pageSize, filterDefaults]);
 
   const inputKey = JSON.stringify(effectiveInput);
   const { items, total, isLoading, isFetching, isError, error, refetch } =
@@ -1617,7 +1914,11 @@ export function ActionList<TInput, TItem>({
         state={state}
         onStateChange={(next) => setStateResetPage({ ...state, ...next })}
         filterOptions={filterOptions}
+        filterDefaults={filterDefaults}
+        filterIcons={filterIcons}
         advancedFilters={advancedFilters}
+        periodPosition={periodPosition}
+        period={period}
         onRefresh={() => refetch()}
         refreshing={isLoading}
         controls={
@@ -1751,6 +2052,55 @@ export function ActionList<TInput, TItem>({
   // — Estados de carga —
   const busy = isFetching || extraLoading === true;
   const isEmpty = empty !== undefined ? empty(items) : items.length === 0;
+  const initialLoading =
+    busy && items.length === 0 && !(empty !== undefined && !isEmpty);
+  const tableFillsAvailableHeight =
+    layout === "fill" && children === undefined && activeView === "table";
+  const tableStateActive =
+    tableFillsAvailableHeight && (initialLoading || isError || isEmpty);
+  const tableColumnCount = Math.max(
+    1,
+    derived.length +
+      (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>
+  ));
   let content: ReactNode;
   if (children !== undefined) {
     // Modo COMPOSIÇÃO: o layout é de quem compõe; a toolbar e os estados seguem daqui.
@@ -1760,8 +2110,22 @@ export function ActionList<TInput, TItem>({
     content = views[activeView].render(items, () => refetch());
   } else {
     content = (
-      <Table variant="framed">
-        <TableHeader>
+      <Table
+        variant="framed"
+        className={tableStateActive ? "h-full" : undefined}
+        containerClassName={
+          tableFillsAvailableHeight
+            ? "absolute inset-0 overflow-auto"
+            : undefined
+        }
+      >
+        <TableHeader
+          className={
+            tableFillsAvailableHeight
+              ? "sticky top-0 z-10 bg-muted/30 dark:bg-input/30"
+              : undefined
+          }
+        >
           <TableRow>
             {hasSelection && (
               <TableHead className="w-px">
@@ -1808,58 +2172,38 @@ export function ActionList<TInput, TItem>({
             {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
-              }
+        <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}
             >
-              {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>
-          ))}
+              {tableRows}
+            </DataState>
+          ) : (
+            tableRows
+          )}
         </TableBody>
       </Table>
     );
   }
-  const body = (
+  const body = tableFillsAvailableHeight ? (
+    content
+  ) : (
     <DataState
-      loading={busy && items.length === 0 && !(empty !== undefined && !isEmpty)}
+      loading={initialLoading}
       error={isError ? error : null}
       empty={isEmpty}
       emptyMessage={emptyMessage}
@@ -1982,7 +2326,15 @@ export function ActionList<TInput, TItem>({
 
   return (
     <TooltipProvider>
-      <div data-action={action.name} className="space-y-3">
+      <div
+        data-action={action.name}
+        data-layout={layout}
+        className={cn(
+          layout === "fill"
+            ? "flex h-full min-h-0 flex-1 flex-col gap-3"
+            : "space-y-3",
+        )}
+      >
         {toolbar}
         {beforeContent}
         {selectionBar}
@@ -1990,6 +2342,9 @@ export function ActionList<TInput, TItem>({
         <div
           aria-busy={busy}
           className={cn(
+            layout === "fill" && "relative flex min-h-0 flex-1 flex-col",
+            layout === "fill" &&
+              (tableFillsAvailableHeight ? "overflow-hidden" : "overflow-auto"),
             busy && items.length > 0 && "pointer-events-none opacity-60",
           )}
         >