@12-apps/ui 1.5.2 → 1.6.1

package/src/components/data-display/DataViews/data-views-server-query.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+import type { DataViewServer, DataViewState } from "./data-views-types";
+
+/**
+ * Server-mode wiring extracted from {@link useDataViewsState} (keeps it within
+ * the size/complexity budget): re-fetch on every effective-query change (page
+ * resets to 1) and expose `changePage` for the pagination control. Read the
+ * latest `state`/`server` at fire time so an inline `server` object per render
+ * doesn't loop the effect.
+ */
+export function useServerQuery(
+  server: DataViewServer | undefined,
+  state: DataViewState,
+  scope: string | undefined,
+): {
+  changePage: (page: number) => void;
+} {
+  const emit = (page: number): void => {
+    if (!server) return;
+    server.onQueryChange({
+      search: state.search,
+      pills: state.pills,
+      ranges: state.ranges ?? {},
+      sortBy: state.sortBy,
+      // Spread rather than `scope: scope`: a table declaring no scopes must emit
+      // a query with NO `scope` key at all, not one present-and-undefined that
+      // every host would then have to know to ignore.
+      ...(scope !== undefined ? { scope } : {}),
+      page,
+      pageSize: server.pageSize,
+    });
+  };
+  const queryKey = server
+    ? JSON.stringify({
+        q: state.search,
+        pills: state.pills,
+        ranges: state.ranges ?? {},
+        sort: state.sortBy,
+        // The RESOLVED scope, so a deep link naming a removed scope re-fetches
+        // once for the fallback rather than looping on the stored id.
+        scope,
+      })
+    : "";
+  const firstQuery = useRef(true);
+  useEffect(() => {
+    if (!server) return;
+    if (firstQuery.current) {
+      firstQuery.current = false;
+      return;
+    }
+    emit(1);
+    // Emit only when the query key changes; `emit` reads fresh state at fire time.
+  }, [queryKey]);
+  return { changePage: (page: number) => emit(page) };
+}
+
+/** The controller's server-mode derived fields (or client-mode defaults). */
+export function serverDerived(
+  server: DataViewServer | undefined,
+  fallbackCount: number,
+): { serverMode: boolean; serverPage: number; serverPageCount: number; serverTotalCount: number } {
+  if (!server) {
+    return { serverMode: false, serverPage: 1, serverPageCount: 1, serverTotalCount: fallbackCount };
+  }
+  return {
+    serverMode: true,
+    serverPage: server.page,
+    serverPageCount: Math.max(1, Math.ceil(server.totalCount / server.pageSize)),
+    serverTotalCount: server.totalCount,
+  };
+}
+

package/src/components/data-display/DataViews/data-views-shell-toolbar.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * The toolbar band, fed from the controller — ~25 props of pure forwarding and
+ * nothing else, which is why it lives in its own file rather than in the shell.
+ */
+import { type ColumnVisibilityOption } from "../../layout/ContentToolbar";
+
+import type { DisplayPanelView } from "./data-views-display-panel";
+import type { DataViewExport } from "./data-views-export";
+import { GridToolbar } from "./data-views-toolbar";
+import type { RowAction } from "./data-views-types";
+import type { DataViewsController } from "./use-data-views-state";
+
+/**
+ * The toolbar band, fed from the controller. Split out of `GridShell` for that
+ * function's size budget — it is ~25 props of pure forwarding and nothing else.
+ */
+export function ShellToolbar<T extends Record<string, unknown>>({
+  c,
+  rows,
+  testIdPrefix,
+  rowActions,
+  bulkActions,
+  toolbarRightSlot,
+  showInline,
+  compactControls,
+  sortKinds,
+  displayView,
+  exportConfig,
+  filterControls,
+  barRef,
+}: {
+  c: DataViewsController<T>;
+  rows: T[];
+  testIdPrefix: string;
+  sortKinds?: Record<string, string>;
+  displayView?: DisplayPanelView;
+  exportConfig?: DataViewExport;
+  rowActions?: RowAction<T>[];
+  bulkActions?: (selectedRows: T[], clearSelection: () => void) => React.ReactNode;
+  toolbarRightSlot?: React.ReactNode;
+  /** Search + filters, rendered on the toolbar line (see `GridToolbar`). */
+  filterControls?: React.ReactNode;
+  barRef?: React.Ref<HTMLDivElement>;
+  showInline: boolean;
+  /** Step 2 of the ladder: Exibir/Exportar as icons only. */
+  compactControls?: boolean;
+}): React.JSX.Element {
+  const columnOptions: ColumnVisibilityOption[] = c.hideableColumns.map((col) => ({
+    id: col.id,
+    label: col.label,
+    visible: c.state.visibleColumns.includes(col.id),
+  }));
+  return (
+    <GridToolbar
+      c={c}
+      sortKinds={sortKinds}
+      displayView={displayView}
+      exportConfig={exportConfig}
+      filterControls={filterControls}
+      barRef={barRef}
+      compactControls={compactControls}
+      testIdPrefix={testIdPrefix}
+      selectedRows={c.selectedRows}
+      selectAll={c.selectAll}
+      clearSelection={c.clearSelection}
+      rowActions={rowActions}
+      bulkActions={bulkActions}
+      sortFields={c.resolvedSortFields}
+      activeSortField={c.activeSortField}
+      activeSortOrder={c.activeSortOrder}
+      onChangeSort={(field, order) => c.patch({ sortBy: [{ id: field, dir: order }] })}
+      matchedCount={c.matched.length}
+      totalCount={c.serverMode ? c.serverTotalCount : rows.length}
+      toolbarRightSlot={toolbarRightSlot}
+      columnOptions={columnOptions}
+      onToggleColumn={c.toggleColumn}
+      filterOpen={c.filterOpen}
+      setFilterOpen={c.setFilterOpen}
+      activeFilterCount={c.activeFilterCount}
+      showFilterTrigger={!showInline}
+    />
+  );
+}
+
+/** Wires the controller into the shared toolbar + filter panel + grid/cards body. */

package/src/components/data-display/DataViews/data-views-table-parts.tsx

@@ -127,7 +127,12 @@ export function ViewDialogs<T extends Record<string, unknown>>({
 }: ViewDialogsProps<T>): React.JSX.Element {
   return (
     <>
+      {/* Keyed by the view being edited: the form seeds its fields with
+          `useState`, which only runs on MOUNT, so a modal that stayed mounted
+          from a previous open reused those values — "Renomear e editar" opened
+          with an empty Nome once "Salvar visão" had been opened first. */}
       <SaveViewModal<T>
+        key={editing ? `edit-${editing.id}` : "create"}
         open={saveOpen}
         onClose={onCloseSave}
         currentState={currentState}

package/src/components/data-display/DataViews/data-views-toolbar.tsx

@@ -1,23 +1,21 @@
 "use client";
 
-import CollapseIcon from '@mui/icons-material/ExpandLess';
-import ExpandIcon from '@mui/icons-material/ExpandMore';
-import { IconButton, Tooltip } from "@mui/material";
+import { Divider } from "@mui/material";
 
 import {
-  ColumnsMenu,
   ContentToolbar,
   FilterTrigger,
-  SortByDropdown,
   type ColumnVisibilityOption,
   type SortFieldDefinition,
 } from "../../layout/ContentToolbar";
 import { Box } from "../../../mui/Box";
 import { Text } from "../../typography/Text";
 
-import { DataViewsLayoutToggle, DataViewsZoomSlider } from "./data-views-layout-context";
+import { DataViewsDisplayPanel, type DisplayPanelView } from "./data-views-display-panel";
+import { DataViewsExportMenu, type DataViewExport } from "./data-views-export";
 import { renderBulkActions } from "./data-views-grid-helpers";
 import type { RowAction } from "./data-views-types";
+import type { DataViewsController } from "./use-data-views-state";
 
 export interface GridToolbarProps<T extends Record<string, unknown>> {
   testIdPrefix: string;
@@ -40,49 +38,74 @@ export interface GridToolbarProps<T extends Record<string, unknown>> {
   activeFilterCount: number;
   /** Hide the "Filtros" slide-in trigger (compact layout shows filters inline). */
   showFilterTrigger?: boolean;
-  /** Show the ∧/∨ toggle that collapses/expands the inline filter row. */
-  showFiltersToggle?: boolean;
-  /** Whether the inline filter row is currently hidden. */
-  filtersHidden?: boolean;
-  /** Toggle the inline filter row's visibility. */
-  onToggleFilters?: () => void;
+  /**
+   * Search + filter controls, rendered ON the toolbar line rather than on a row
+   * beneath it. Absent ⇒ the toolbar keeps its plain two-cluster shape.
+   */
+  filterControls?: React.ReactNode;
+  /** Measures the toolbar ROW for the filter overflow — see `useFilterOverflow`. */
+  barRef?: React.Ref<HTMLDivElement>;
+  /** The controller, so "Exibir" can drive sort, columns, order and format. */
+  c: DataViewsController<T>;
+  /** Per-sort-field value kind, so directions read in the column's own terms. */
+  sortKinds?: Record<string, string>;
+  /** The saved-view chrome bracketing the Exibir panel, when the host has views. */
+  displayView?: DisplayPanelView;
+  /** Injected export. Absent ⇒ no Exportar control. */
+  exportConfig?: DataViewExport;
+  /**
+   * Step 2 of the degradation ladder: Exibir/Exportar as icons only.
+   * MEASURED upstream (see `useFilterOverflow`) rather than switched at a
+   * breakpoint, so a two-filter page keeps its labels where a five-filter one
+   * has already given them up.
+   */
+  compactControls?: boolean;
 }
 
 /** The right-aligned toolbar controls: Sort By, the counter, zoom/layout/columns, filters. */
 function ToolbarRightControls<T extends Record<string, unknown>>(props: GridToolbarProps<T>): React.JSX.Element {
-  const { testIdPrefix, sortFields, matchedCount, totalCount, filterOpen, setFilterOpen } = props;
+  const { testIdPrefix, matchedCount, totalCount, filterOpen, setFilterOpen } = props;
   return (
     <>
-      {sortFields.length > 0 && (
-        <SortByDropdown
-          fields={sortFields}
-          activeField={props.activeSortField}
-          activeOrder={props.activeSortOrder}
-          onFieldChange={(field) => props.onChangeSort(field, "asc")}
-          onOrderChange={(order) => props.onChangeSort(props.activeSortField, order === "desc" ? "desc" : "asc")}
-          data-testid={`${testIdPrefix}-sort-trigger`}
-        />
-      )}
       <Text variant="caption" as="span">
-        {/* The "N de N" counter is hidden on mobile to keep the toolbar one line. */}
+        {/* Always rendered, never breakpointed: `RESERVED.counter` already
+            prices it into the collapse ladder, so hiding it at `md` was the
+            ladder and a breakpoint disagreeing about the same pixels — which
+            is what broke the row at exactly 900px. */}
         <Box
           component="span"
           data-testid={`${testIdPrefix}-counter`}
-          sx={{ whiteSpace: "nowrap", display: { xs: "none", md: "inline" } }}
+          sx={{ whiteSpace: "nowrap" }}
         >
-          Exibindo {matchedCount} de {totalCount}
+          {matchedCount} de {totalCount}
         </Box>
       </Text>
+      {/* Divides the READING of the list from the controls that change it —
+          the counter states what is on screen, everything right of here acts
+          on it. */}
+      <Divider
+        orientation="vertical"
+        flexItem
+        sx={{ height: 20, alignSelf: "center", mx: 0.5 }}
+      />
       {props.toolbarRightSlot}
-      <DataViewsZoomSlider testIdPrefix={testIdPrefix} />
-      <DataViewsLayoutToggle testIdPrefix={testIdPrefix} />
-      {props.columnOptions.length > 0 && (
-        <ColumnsMenu
-          columns={props.columnOptions}
-          onToggle={props.onToggleColumn}
-          title="Colunas"
-          ariaLabel="Exibir colunas"
-          data-testid={`${testIdPrefix}-columns-toggle`}
+      {/* Sort + columns + format, in ONE control — see DataViewsDisplayPanel. */}
+      <DataViewsDisplayPanel
+        c={props.c}
+        testIdPrefix={testIdPrefix}
+        sortKinds={props.sortKinds}
+        view={props.displayView}
+        compact={props.compactControls}
+      />
+      {props.exportConfig && (
+        <DataViewsExportMenu
+          config={props.exportConfig}
+          query={props.c.currentQuery}
+          totalCount={props.totalCount}
+          selectedIds={[...props.c.selectedIds]}
+          columns={props.columnOptions.filter((col) => col.visible).map((col) => ({ id: col.id, label: col.label }))}
+          testIdPrefix={testIdPrefix}
+          compact={props.compactControls}
         />
       )}
       {props.showFilterTrigger !== false && (
@@ -93,19 +116,6 @@ function ToolbarRightControls<T extends Record<string, unknown>>(props: GridTool
           data-testid={`${testIdPrefix}-filters-toggle`}
         />
       )}
-      {props.showFiltersToggle && (
-        <Tooltip title={props.filtersHidden ? "Mostrar filtros" : "Ocultar filtros"}>
-          <IconButton
-            size="small"
-            onClick={props.onToggleFilters}
-            aria-label={props.filtersHidden ? "Mostrar filtros" : "Ocultar filtros"}
-            aria-expanded={!props.filtersHidden}
-            data-testid={`${testIdPrefix}-filters-collapse`}
-          >
-            {props.filtersHidden ? <ExpandIcon fontSize="small" /> : <CollapseIcon fontSize="small" />}
-          </IconButton>
-        </Tooltip>
-      )}
     </>
   );
 }
@@ -119,6 +129,7 @@ export function GridToolbar<T extends Record<string, unknown>>(props: GridToolba
   const { testIdPrefix, selectedRows } = props;
   return (
     <Box
+      ref={props.barRef}
       sx={{
         borderTop: 1,
         borderBottom: 1,
@@ -142,6 +153,10 @@ export function GridToolbar<T extends Record<string, unknown>>(props: GridToolba
           clearSelection: props.clearSelection,
           testIdPrefix,
         })}
+        leadingControls={props.filterControls}
+        // Selection takes the whole line: no Select All while browsing, and no
+        // search/filters/Exibir/Exportar once a row is ticked.
+        exclusiveSelection
         rightControls={<ToolbarRightControls {...props} />}
       />
     </Box>

package/src/components/data-display/DataViews/data-views-types.ts

@@ -164,6 +164,14 @@ export interface DataViewColumn<T extends Record<string, unknown>> extends GridC
   hideable?: boolean;
 }
 
+/**
+ * The DataViews layout (view type): the dense "Tabela" grid, the "Grade" of
+ * cards, the "Lista" of full-width rows, or the "Quadro" board of state columns.
+ * Lives with the state types rather than with the toggle because a saved view
+ * CAPTURES it — see {@link DataViewState.layout}.
+ */
+export type DataViewsLayout = "cards" | "list" | "board" | "table";
+
 /** The full, serializable state a view captures. */
 export interface DataViewState {
   /** Free text matched across every `searchable` column. */
@@ -175,6 +183,36 @@ export interface DataViewState {
   sortBy: GridSort[];
   /** Column ids kept visible; a hideable column not listed here is hidden. */
   visibleColumns: string[];
+  /**
+   * Column ids in READING ORDER. Absent ⇒ the order the table declared them in.
+   *
+   * Order is view state for the same reason visibility is: reordering columns is
+   * an operator deciding what to read FIRST, and a saved view that restored the
+   * columns but not their order would restore half a decision. Ids the table no
+   * longer declares are ignored at render, and ids missing from a stale list
+   * fall in after it — so a column added since the view was saved appears rather
+   * than disappearing.
+   */
+  order?: string[];
+  /**
+   * The active SCOPE id — the page-level partition the scope tabs select (see
+   * `ScopeConfig`). Optional, so a table that declares no scopes is untouched
+   * and no view persisted before scopes existed breaks.
+   *
+   * Stored raw and RESOLVED at read time: the declared scopes change underneath
+   * a saved view, and a view naming a scope that has since been removed must
+   * fall back at render rather than break.
+   */
+  scope?: string;
+  /**
+   * The layout the view was saved in. Optional — absent means "whatever the user
+   * is currently using", which is the pre-existing behaviour.
+   *
+   * A LAYOUT FALLBACK IS NOT A LAYOUT CHANGE: a table rendered as stacked rows
+   * on a phone still has `"table"` stored here, so the view round-trips the
+   * stored layout regardless of the device that opened it.
+   */
+  layout?: DataViewsLayout;
 }
 
 /** A pristine view state showing every given column and no filters/sort. */
@@ -190,7 +228,10 @@ export function emptyViewState(visibleColumns: string[]): DataViewState {
  * over the current state so a user's show/hide column choices are preserved —
  * unlike `appliedState`, which fully replaces the state to apply a saved view.
  */
-export type DataViewSyncState = Pick<DataViewState, "search" | "pills" | "ranges" | "sortBy">;
+export type DataViewSyncState = Pick<
+  DataViewState,
+  "search" | "pills" | "ranges" | "sortBy" | "scope"
+>;
 
 /**
  * The query a SERVER-mode table emits whenever its filter/sort/page changes
@@ -204,6 +245,16 @@ export interface DataViewQuery {
   pills: Record<string, string[]>;
   ranges: Record<string, RangeValue>;
   sortBy: GridSort[];
+  /**
+   * The RESOLVED active scope (see `resolveScope`), when the table declares
+   * scopes. The KEY IS ABSENT for a table that declares none — not present-and-
+   * undefined — so a host that never opted in sees a byte-identical query.
+   *
+   * It carries the resolved id, never the stored one: a deep link or a saved
+   * view naming a scope the table no longer declares must not put that id on the
+   * wire, where the backend would reject it and replace the page with an error.
+   */
+  scope?: string;
   page: number;
   pageSize: number;
 }
@@ -225,6 +276,20 @@ export interface DataViewServer {
   pageSize: number;
   /** Fired when the effective query changes; the host re-fetches the page. */
   onQueryChange: (query: DataViewQuery) => void;
+  /**
+   * Per-scope totals for the scope tabs: `scopeId → count`. THE ONLY PIECE OF
+   * THIS CONTRACT THAT CANNOT BE DONE CLIENT-SIDE — a count computed from the
+   * loaded page is wrong the moment there is a second page, which is the
+   * concrete bug scopes exist to fix.
+   *
+   * Compute it over search + pills + ranges while IGNORING the active scope.
+   * Computed WITH the scope applied, every inactive tab reads zero, which is
+   * worse than no counts at all.
+   *
+   * Omit it and the tabs render with no numbers. Nothing is ever invented from
+   * the loaded rows to fill the gap.
+   */
+  scopeCounts?: Record<string, number>;
 }
 
 /**
@@ -236,19 +301,33 @@ export function coerceViewState(raw: unknown, allColumnIds: string[]): DataViewS
   const value = (raw ?? {}) as Partial<DataViewState>;
   return {
     search: typeof value.search === "string" ? value.search : "",
-    pills:
-      value.pills && typeof value.pills === "object"
-        ? (value.pills as Record<string, string[]>)
-        : {},
-    ranges:
-      value.ranges && typeof value.ranges === "object"
-        ? (value.ranges as Record<string, RangeValue>)
-        : {},
+    pills: asRecord<string[]>(value.pills),
+    ranges: asRecord<RangeValue>(value.ranges),
     sortBy: Array.isArray(value.sortBy) ? value.sortBy : [],
     visibleColumns: Array.isArray(value.visibleColumns) ? value.visibleColumns : allColumnIds,
+    order: Array.isArray(value.order) ? value.order : undefined,
+    // Carried through UNVALIDATED against the declared scopes on purpose: a view
+    // written before scopes existed has none (⇒ undefined ⇒ the first declared
+    // scope at render), and one naming a since-removed scope keeps its stored id
+    // here and falls back at READ time. Resolving here would rewrite the view.
+    scope: typeof value.scope === "string" ? value.scope : undefined,
+    layout: isLayout(value.layout) ? value.layout : undefined,
   };
 }
 
+/** Every layout this build knows how to render — the guard's single source. */
+export const DATA_VIEWS_LAYOUTS: readonly DataViewsLayout[] = ["cards", "list", "board", "table"];
+
+/** Is this a layout this build knows how to render? Guards persisted JSON. */
+function isLayout(value: unknown): value is DataViewsLayout {
+  return DATA_VIEWS_LAYOUTS.includes(value as DataViewsLayout);
+}
+
+/** A persisted map, or an empty one — persisted JSON can hold anything. */
+function asRecord<V>(value: unknown): Record<string, V> {
+  return value !== null && typeof value === "object" ? (value as Record<string, V>) : {};
+}
+
 /** A saved view as consumed by the DataViews UI (FUT-89), with ownership flag. */
 export interface SavedViewSummary {
   id: string;