@12-apps/ui 1.5.2 → 1.6.1

package/src/components/data-display/DataViews/SaveViewModal.tsx

@@ -1,5 +1,8 @@
 "use client";
 
+import GroupOutlinedIcon from "@mui/icons-material/GroupOutlined";
+import PushPinOutlinedIcon from "@mui/icons-material/PushPinOutlined";
+import StarOutlineRoundedIcon from "@mui/icons-material/StarOutlineRounded";
 import { useState } from "react";
 
 import { Dialog, DialogContent } from "../../feedback/Dialog";
@@ -40,29 +43,6 @@ interface SaveViewModalProps<T extends Record<string, unknown>> {
   testIdPrefix?: string;
 }
 
-function PreviewList({ title, items, testId }: { title: string; items: string[]; testId: string }): React.JSX.Element {
-  return (
-    <Box data-testid={testId}>
-      <Text variant="caption" as="span" weight="semibold">
-        {title}
-      </Text>
-      {items.length === 0 ? (
-        <Text variant="caption" as="p" color="secondary">
-          —
-        </Text>
-      ) : (
-        <Stack component="ul" spacing={0.25} sx={{ m: 0, pl: 2 }}>
-          {items.map((item) => (
-            <Text key={item} variant="caption" as="li">
-              {item}
-            </Text>
-          ))}
-        </Stack>
-      )}
-    </Box>
-  );
-}
-
 interface FlagsSwitchesProps {
   pinned: boolean;
   shared: boolean;
@@ -73,6 +53,63 @@ interface FlagsSwitchesProps {
   testIdPrefix: string;
 }
 
+/**
+ * One flag: what it is, and what it DOES. A bare "Fixar na barra lateral"
+ * beside a switch asks the operator to guess where it appears and to whom —
+ * the sentence is the difference between a labelled toggle and an explained one.
+ */
+function FlagRow({
+  icon,
+  title,
+  description,
+  checked,
+  onChange,
+  testId,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  description: string;
+  checked: boolean;
+  onChange: (value: boolean) => void;
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="label"
+      sx={{
+        display: "flex",
+        alignItems: "flex-start",
+        gap: 1.5,
+        px: 1,
+        py: 1,
+        borderRadius: 1,
+        cursor: "pointer",
+        "&:hover": { bgcolor: "action.hover" },
+      }}
+    >
+      <Box sx={{ mt: 0.25, color: "text.disabled", display: "flex" }}>{icon}</Box>
+      <Box sx={{ minWidth: 0, flex: 1 }}>
+        <Text variant="body" as="span">
+          <Box component="span" sx={{ display: "block", fontSize: "0.875rem" }}>
+            {title}
+          </Box>
+        </Text>
+        <Text variant="caption" as="span">
+          <Box component="span" sx={{ display: "block", color: "text.secondary", lineHeight: 1.5 }}>
+            {description}
+          </Box>
+        </Text>
+      </Box>
+      <Switch
+        size="sm"
+        checked={checked}
+        onChange={(_event, value) => onChange(value)}
+        dataTestId={testId}
+      />
+    </Box>
+  );
+}
+
 function FlagsSwitches({
   pinned,
   shared,
@@ -83,27 +120,30 @@ function FlagsSwitches({
   testIdPrefix,
 }: FlagsSwitchesProps): React.JSX.Element {
   return (
-    <Stack spacing={0.5}>
-      <Switch
-        size="sm"
-        label="Fixar na barra lateral"
+    <Stack spacing={0}>
+      <FlagRow
+        icon={<PushPinOutlinedIcon fontSize="small" />}
+        title="Fixar na barra lateral"
+        description="Aparece como atalho no menu, abaixo desta tela."
         checked={pinned}
-        onChange={(_event, value) => setPinned(value)}
-        dataTestId={`${testIdPrefix}-save-pinned`}
+        onChange={setPinned}
+        testId={`${testIdPrefix}-save-pinned`}
       />
-      <Switch
-        size="sm"
-        label="Compartilhar com a equipe"
+      <FlagRow
+        icon={<GroupOutlinedIcon fontSize="small" />}
+        title="Compartilhar com a equipe"
+        description="Qualquer pessoa da loja poderá abrir e usar esta visão."
         checked={shared}
-        onChange={(_event, value) => setShared(value)}
-        dataTestId={`${testIdPrefix}-save-shared`}
+        onChange={setShared}
+        testId={`${testIdPrefix}-save-shared`}
       />
-      <Switch
-        size="sm"
-        label="Definir como padrão"
+      <FlagRow
+        icon={<StarOutlineRoundedIcon fontSize="small" />}
+        title="Definir como padrão"
+        description="Esta tela abre nesta visão em vez da Visão principal."
         checked={isDefault}
-        onChange={(_event, value) => setIsDefault(value)}
-        dataTestId={`${testIdPrefix}-save-default`}
+        onChange={setIsDefault}
+        testId={`${testIdPrefix}-save-default`}
       />
     </Stack>
   );
@@ -114,17 +154,61 @@ interface PreviewBoxProps {
   testIdPrefix: string;
 }
 
+/** One "label — value" line of the summary. */
+function SummaryRow({
+  label,
+  items,
+  testId,
+}: {
+  label: string;
+  items: string[];
+  testId: string;
+}): React.JSX.Element | null {
+  if (items.length === 0) return null;
+  return (
+    <Box sx={{ display: "flex", gap: 1.5 }} data-testid={testId}>
+      <Text variant="caption" as="span">
+        <Box component="span" sx={{ width: 116, flexShrink: 0, color: "text.secondary" }}>
+          {label}
+        </Box>
+      </Text>
+      <Text variant="caption" as="span">
+        <Box component="span" sx={{ minWidth: 0, flex: 1 }}>
+          {items.join(", ")}
+        </Box>
+      </Text>
+    </Box>
+  );
+}
+
 function PreviewBox({ preview, testIdPrefix }: PreviewBoxProps): React.JSX.Element {
+  const empty =
+    preview.filters.length === 0 && preview.columns.length === 0 && preview.sort.length === 0;
   return (
-    <Box sx={{ p: 1.5, borderRadius: 1, border: (theme) => `1px solid ${theme.palette.divider}` }}>
-      <Text variant="caption" as="p" weight="semibold">
-        Prévia
+    <Box sx={{ p: 1.5, borderRadius: 1.5, bgcolor: "action.hover", border: (theme) => `1px solid ${theme.palette.divider}` }}>
+      <Text variant="caption" as="p">
+        <Box
+          component="span"
+          sx={{ display: "block", mb: 1, textTransform: "uppercase", letterSpacing: 0.6, fontWeight: 600, color: "text.disabled" }}
+        >
+          O que esta visão guarda
+        </Box>
       </Text>
-      <Stack spacing={1} sx={{ mt: 0.5 }}>
-        <PreviewList title="Filtros" items={preview.filters} testId={`${testIdPrefix}-preview-filters`} />
-        <PreviewList title="Colunas" items={preview.columns} testId={`${testIdPrefix}-preview-columns`} />
-        <PreviewList title="Ordenação" items={preview.sort} testId={`${testIdPrefix}-preview-sort`} />
-      </Stack>
+      {empty ? (
+        // Saving is still allowed — an operator may be naming the default on
+        // purpose — but it should not be a surprise afterwards.
+        <Text variant="caption" as="p">
+          <Box component="span" sx={{ color: "warning.main", lineHeight: 1.6 }} data-testid={`${testIdPrefix}-preview-empty`}>
+            Nada foi alterado — esta visão ficará igual à Visão principal.
+          </Box>
+        </Text>
+      ) : (
+        <Stack spacing={0.75}>
+          <SummaryRow label="Filtros" items={preview.filters} testId={`${testIdPrefix}-preview-filters`} />
+          <SummaryRow label="Colunas ocultas" items={preview.columns} testId={`${testIdPrefix}-preview-columns`} />
+          <SummaryRow label="Ordenação" items={preview.sort} testId={`${testIdPrefix}-preview-sort`} />
+        </Stack>
+      )}
     </Box>
   );
 }
@@ -239,6 +323,7 @@ export function SaveViewModal<T extends Record<string, unknown>>({
             size="sm"
             fullWidth
             label="Nome"
+            placeholder="Ex.: Recusados no PIX desta semana"
             value={form.name}
             onChange={(event) => form.setName(event.target.value)}
             data-testid={`${testIdPrefix}-save-name`}
@@ -246,7 +331,8 @@ export function SaveViewModal<T extends Record<string, unknown>>({
           <Input
             size="sm"
             fullWidth
-            label="Descrição (opcional)"
+            label="Descrição — opcional"
+            placeholder="Para que serve esta visão"
             value={form.description}
             onChange={(event) => form.setDescription(event.target.value)}
             data-testid={`${testIdPrefix}-save-description`}
@@ -270,7 +356,12 @@ export function SaveViewModal<T extends Record<string, unknown>>({
             </Text>
           )}
 
-          <Stack direction="row" spacing={2}>
+          {/* Cancel first, primary last: the confirming action sits where the
+              eye lands at the end of the dialog, not before the way out. */}
+          <Stack direction="row" spacing={1.5} sx={{ justifyContent: "flex-end" }}>
+            <Button variant="text" color="neutral" onClick={onClose} dataTestId={`${testIdPrefix}-save-cancel`}>
+              Cancelar
+            </Button>
             <Button
               onClick={() => void form.submit()}
               disabled={!form.canSave}
@@ -278,9 +369,6 @@ export function SaveViewModal<T extends Record<string, unknown>>({
             >
               {editing ? "Salvar alterações" : "Salvar visão"}
             </Button>
-            <Button variant="text" onClick={onClose} dataTestId={`${testIdPrefix}-save-cancel`}>
-              Cancelar
-            </Button>
           </Stack>
         </Stack>
       </DialogContent>

package/src/components/data-display/DataViews/data-views-columns-tab.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import ArrowDownwardRoundedIcon from "@mui/icons-material/ArrowDownwardRounded";
+import ArrowUpwardRoundedIcon from "@mui/icons-material/ArrowUpwardRounded";
+import DragIndicatorRoundedIcon from "@mui/icons-material/DragIndicatorRounded";
+import { Checkbox } from "@mui/material";
+import { useState } from "react";
+
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+import type { HideableColumn } from "./data-views-columns";
+
+/* ── Colunas ─────────────────────────────────────────────────────────────── */
+
+interface ColumnsTabProps {
+  columns: HideableColumn[];
+  /** Every column id in the CURRENT order (including non-hideable ones). */
+  order: string[];
+  visibleColumns: string[];
+  onToggle: (id: string, visible: boolean) => void;
+  onReorder: (order: string[]) => void;
+  onShowAll: () => void;
+  onReset: () => void;
+  testIdPrefix: string;
+}
+
+/** Swap the column at `id` with its neighbour `delta` places away. */
+function moved(order: string[], id: string, delta: number): string[] {
+  const from = order.indexOf(id);
+  const to = from + delta;
+  if (from < 0 || to < 0 || to >= order.length) return order;
+  const next = [...order];
+  [next[from], next[to]] = [next[to]!, next[from]!];
+  return next;
+}
+
+/**
+ * Visibility AND order in one list, because they are the same decision: an
+ * operator reordering columns is deciding what to read first, and hiding one is
+ * deciding not to read it at all. Drag the grip, or use the arrows — the arrows
+ * exist because drag-and-drop is unusable by keyboard and awkward on a phone.
+ */
+export function ColumnsTab({
+  columns,
+  order,
+  visibleColumns,
+  onToggle,
+  onReorder,
+  onShowAll,
+  onReset,
+  testIdPrefix,
+}: ColumnsTabProps): React.JSX.Element {
+  const [dragId, setDragId] = useState<string | null>(null);
+  const byId = new Map(columns.map((column) => [column.id, column]));
+  const ordered = order.map((id) => byId.get(id)).filter((column): column is HideableColumn => Boolean(column));
+  // Counted against `columns`, which is the HIDEABLE set — `visibleColumns`
+  // also carries the locked ones (a `hideable: false` id like the row's
+  // identifier), and counting it whole reads "9 de 8 visíveis".
+  const visibleHideableCount = visibleColumns.filter((id) => byId.has(id)).length;
+
+  const dropOn = (id: string): void => {
+    if (!dragId || dragId === id) return;
+    const without = order.filter((key) => key !== dragId);
+    without.splice(without.indexOf(id), 0, dragId);
+    onReorder(without);
+    setDragId(null);
+  };
+
+  return (
+    <Box>
+      <Box sx={{ display: "flex", alignItems: "center", justifyContent: "space-between", px: 1.5, py: 1 }}>
+        <Text variant="caption" as="span">
+          <Box component="span" sx={{ color: "text.secondary" }} data-testid={`${testIdPrefix}-columns-count`}>
+            <strong>{visibleHideableCount}</strong> de {columns.length} visíveis
+          </Box>
+        </Text>
+        <Box sx={{ display: "flex", gap: 1 }}>
+          <LinkButton label="Mostrar todas" onClick={onShowAll} testId={`${testIdPrefix}-columns-show-all`} />
+          <LinkButton label="Padrão" onClick={onReset} testId={`${testIdPrefix}-columns-reset`} muted />
+        </Box>
+      </Box>
+      <Text variant="caption" as="p">
+        <Box component="span" sx={{ px: 1.5, pb: 0.5, display: "block", color: "text.disabled" }}>
+          Arraste para reordenar as colunas.
+        </Box>
+      </Text>
+      <Box sx={{ px: 0.75, pb: 0.75 }}>
+        {ordered.map((column) => (
+          <ColumnRow
+            key={column.id}
+            column={column}
+            visible={visibleColumns.includes(column.id)}
+            dragging={dragId === column.id}
+            onToggle={onToggle}
+            onDragStart={() => setDragId(column.id)}
+            onDragEnd={() => setDragId(null)}
+            onDrop={() => dropOn(column.id)}
+            onMove={(delta) => onReorder(moved(order, column.id, delta))}
+            testIdPrefix={testIdPrefix}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+/** A borderless text action, for the two column resets. */
+function LinkButton({
+  label,
+  onClick,
+  testId,
+  muted,
+}: {
+  label: string;
+  onClick: () => void;
+  testId: string;
+  muted?: boolean;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onClick}
+      data-testid={testId}
+      sx={{
+        border: 0,
+        background: "none",
+        cursor: "pointer",
+        font: "inherit",
+        fontSize: "0.75rem",
+        p: 0,
+        color: muted ? "text.secondary" : "primary.main",
+        "&:hover": { textDecoration: "underline" },
+      }}
+    >
+      {label}
+    </Box>
+  );
+}
+
+interface ColumnRowProps {
+  column: HideableColumn;
+  visible: boolean;
+  dragging: boolean;
+  onToggle: (id: string, visible: boolean) => void;
+  onDragStart: () => void;
+  onDragEnd: () => void;
+  onDrop: () => void;
+  onMove: (delta: number) => void;
+  testIdPrefix: string;
+}
+
+/** One column: grip, checkbox, label, and the keyboard-reachable move arrows. */
+function ColumnRow({
+  column,
+  visible,
+  dragging,
+  onToggle,
+  onDragStart,
+  onDragEnd,
+  onDrop,
+  onMove,
+  testIdPrefix,
+}: ColumnRowProps): React.JSX.Element {
+  return (
+    <Box
+      draggable
+      onDragStart={onDragStart}
+      onDragEnd={onDragEnd}
+      onDragOver={(event: React.DragEvent) => event.preventDefault()}
+      onDrop={onDrop}
+      data-testid={`${testIdPrefix}-column-row-${column.id}`}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 0.5,
+        px: 0.75,
+        py: 0.25,
+        borderRadius: 1,
+        opacity: dragging ? 0.4 : 1,
+        "&:hover": { bgcolor: "action.hover" },
+        "&:hover .dv-col-move": { opacity: 1 },
+      }}
+    >
+      <Box component="span" aria-hidden sx={{ display: "flex", color: "action.disabled", cursor: "grab" }}>
+        <DragIndicatorRoundedIcon fontSize="small" />
+      </Box>
+      <Checkbox
+        size="small"
+        checked={visible}
+        onChange={(event) => onToggle(column.id, event.target.checked)}
+        inputProps={{ "aria-label": column.label }}
+        data-testid={`${testIdPrefix}-column-toggle-${column.id}`}
+      />
+      <Text variant="caption" as="span">
+        <Box component="span" sx={{ flex: 1, color: visible ? "text.primary" : "text.disabled" }}>
+          {column.label}
+        </Box>
+      </Text>
+      <Box className="dv-col-move" sx={{ ml: "auto", display: "flex", opacity: 0, transition: "opacity .15s" }}>
+        <MoveButton label={`Mover ${column.label} para cima`} onClick={() => onMove(-1)} up />
+        <MoveButton label={`Mover ${column.label} para baixo`} onClick={() => onMove(1)} />
+      </Box>
+    </Box>
+  );
+}
+
+/** One of the two reorder arrows — the keyboard's path through the drag handle. */
+function MoveButton({
+  label,
+  onClick,
+  up,
+}: {
+  label: string;
+  onClick: () => void;
+  up?: boolean;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      aria-label={label}
+      onClick={onClick}
+      sx={{
+        display: "flex",
+        border: 0,
+        p: 0.25,
+        background: "none",
+        borderRadius: 0.5,
+        cursor: "pointer",
+        color: "text.secondary",
+        "&:hover": { bgcolor: "action.selected" },
+      }}
+    >
+      {up ? <ArrowUpwardRoundedIcon sx={{ fontSize: 14 }} /> : <ArrowDownwardRoundedIcon sx={{ fontSize: 14 }} />}
+    </Box>
+  );
+}
+

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

@@ -0,0 +1,129 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { type GridColumn } from "../DataGrid";
+
+import {
+  buildGridColumns,
+  buildRowActionsColumn,
+  isActionsColumn,
+} from "./data-views-grid-helpers";
+import type { DataViewColumn, RowAction } from "./data-views-types";
+
+/**
+ * Every column derivation the DataViews grid needs, in one place: the auto kebab
+ * actions column, the id list that seeds a pristine view state, what the grid
+ * actually renders once visibility is applied, and the show/hide menu's list.
+ */
+
+/** A column the user may show/hide via the toolbar's ColumnsMenu. */
+export interface HideableColumn {
+  id: string;
+  label: string;
+}
+
+/**
+ * The columns the user may show/hide: explicitly hideable (not `hideable:false`,
+ * which marks structural columns like the image thumbnail or actions kebab) and
+ * carrying a text header to label the checkbox.
+ */
+function computeHideableColumns<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+): HideableColumn[] {
+  return columns
+    .filter((col) => col.hideable !== false && typeof col.header === "string" && col.header !== "")
+    .map((col) => ({ id: col.id, label: col.header as string }));
+}
+
+/**
+ * Append the auto kebab actions column unless the page already defines one. The
+ * column is added when there are `rowActions` OR a bespoke `renderRowMenu` (an
+ * entity's self-contained menu that owns its own popups).
+ */
+function appendActionsColumn<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+  opts: {
+    rowActions?: RowAction<T>[];
+    rowActionsLeading?: (row: T) => React.ReactNode;
+    renderRowMenu?: (row: T) => React.ReactNode;
+    testIdPrefix: string;
+    getRowId: (row: T) => string | number;
+  },
+): DataViewColumn<T>[] {
+  const { rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId } = opts;
+  if ((!rowActions && !renderRowMenu) || columns.some(isActionsColumn)) return columns;
+  return [
+    ...columns,
+    buildRowActionsColumn({
+      rowActions: rowActions ?? [],
+      leading: rowActionsLeading,
+      testIdPrefix,
+      getRowId,
+      renderRowMenu,
+    }),
+  ];
+}
+
+/** Options {@link appendActionsColumn} needs to build the auto kebab column. */
+type ActionsColumnOpts<T extends Record<string, unknown>> = {
+  rowActions?: RowAction<T>[];
+  rowActionsLeading?: (row: T) => React.ReactNode;
+  renderRowMenu?: (row: T) => React.ReactNode;
+  testIdPrefix: string;
+  getRowId: (row: T) => string | number;
+};
+
+/**
+ * The declared columns plus the auto kebab column (unless the page defines its
+ * own), and every column id — which is what seeds a pristine view state's
+ * `visibleColumns`, so it is derived BEFORE the state exists.
+ */
+export function useColumnsWithActions<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+  opts: ActionsColumnOpts<T>,
+): { columnsWithActions: DataViewColumn<T>[]; allColumnIds: string[] } {
+  const { rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId } = opts;
+  const columnsWithActions = useMemo(
+    () =>
+      appendActionsColumn(columns, { rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId }),
+    [columns, rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId],
+  );
+  const allColumnIds = useMemo(() => columnsWithActions.map((col) => col.id), [columnsWithActions]);
+  return { columnsWithActions, allColumnIds };
+}
+
+/**
+ * Apply a stored column ORDER, tolerantly.
+ *
+ * A stored list goes stale in both directions and neither may lose a column: an
+ * id the table no longer declares is dropped, and a column the table declares
+ * but the list never mentioned (added since the view was saved) falls in AFTER
+ * the ordered ones rather than vanishing. Absent order ⇒ declaration order.
+ */
+function applyOrder<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+  order: string[] | undefined,
+): DataViewColumn<T>[] {
+  if (!order || order.length === 0) return columns;
+  const byId = new Map(columns.map((column) => [column.id, column]));
+  const ordered = order.map((id) => byId.get(id)).filter((c): c is DataViewColumn<T> => Boolean(c));
+  const seen = new Set(ordered.map((column) => column.id));
+  return [...ordered, ...columns.filter((column) => !seen.has(column.id))];
+}
+
+/** What the grid actually renders: order + visibility applied, plus the menu's list. */
+export function useRenderedColumns<T extends Record<string, unknown>>(
+  columnsWithActions: DataViewColumn<T>[],
+  visibleColumns: string[],
+  onRowClick: ((row: T) => void) | undefined,
+  order?: string[],
+): { gridColumns: GridColumn<T>[]; hideableColumns: HideableColumn[] } {
+  const gridColumns = useMemo(
+    () => buildGridColumns(applyOrder(columnsWithActions, order), visibleColumns, onRowClick),
+    [columnsWithActions, onRowClick, visibleColumns, order],
+  );
+  const hideableColumns = useMemo(() => computeHideableColumns(columnsWithActions), [columnsWithActions]);
+  return { gridColumns, hideableColumns };
+}
+

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

@@ -0,0 +1,62 @@
+import type { DataViewState, RangeValue } from "./data-views-types";
+
+/**
+ * A comparable key for a view state — the answer to "has anything changed?".
+ *
+ * `JSON.stringify(state)` is not that answer. Clearing a filter does not remove
+ * its entry, it leaves an EMPTY one (`pills: { pagamento: [] }`), and an emptied
+ * range leaves `{}` behind; both stringify differently from the state that never
+ * had them, so a filter applied and then removed left the view reading "unsaved
+ * changes" over a state identical to the one it started from. The only way back
+ * was "Redefinir", which is the operator undoing something they had already
+ * undone.
+ *
+ * So: drop what is empty, sort what is unordered, and keep what actually
+ * distinguishes one view from another.
+ */
+
+/** Is this range bounded at either end? An empty one is not a constraint. */
+function isSet(range: RangeValue | undefined): boolean {
+  return Boolean(range && (range.min !== undefined || range.max !== undefined));
+}
+
+/** Selected values, sorted — picking A then B is the same view as B then A. */
+function normalizePills(pills: Record<string, string[]> | undefined): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const key of Object.keys(pills ?? {}).sort()) {
+    const values = pills?.[key];
+    if (values && values.length > 0) out[key] = [...values].sort();
+  }
+  return out;
+}
+
+function normalizeRanges(
+  ranges: Record<string, RangeValue> | undefined,
+): Record<string, RangeValue> {
+  const out: Record<string, RangeValue> = {};
+  for (const key of Object.keys(ranges ?? {}).sort()) {
+    const range = ranges?.[key];
+    if (isSet(range)) out[key] = range as RangeValue;
+  }
+  return out;
+}
+
+/**
+ * Everything a saved view stores, in a stable shape.
+ *
+ * `visibleColumns` is SORTED — it is a set, and its array order carries no
+ * meaning (reading order lives in `order`). `order` is not sorted, for the
+ * opposite reason.
+ */
+export function viewStateKey(state: DataViewState): string {
+  return JSON.stringify({
+    search: state.search.trim(),
+    pills: normalizePills(state.pills),
+    ranges: normalizeRanges(state.ranges),
+    sortBy: state.sortBy ?? [],
+    visibleColumns: [...(state.visibleColumns ?? [])].sort(),
+    order: state.order ?? null,
+    scope: state.scope ?? null,
+    layout: state.layout ?? null,
+  });
+}