@open-mercato/ui 0.6.8-develop.6914.1.6c7a5dcb6b → 0.6.8-develop.6916.1.f04fff3436

package/dist/backend/perspectiveDirty.js

@@ -0,0 +1,55 @@
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+  return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+}
+function normalizeOrder(order, fallback) {
+  return Array.isArray(order) && order.length > 0 ? order : fallback;
+}
+function normalizeVisibility(visibility) {
+  if (!visibility) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(visibility)) {
+    if (value === false) result[key] = false;
+  }
+  return result;
+}
+function normalizeSizing(sizing) {
+  if (!sizing) return {};
+  const result = {};
+  for (const [key, value] of Object.entries(sizing)) {
+    if (typeof value === "number" && Number.isFinite(value)) result[key] = Math.round(value);
+  }
+  return result;
+}
+function normalizeSorting(sorting) {
+  if (!Array.isArray(sorting)) return [];
+  return sorting.map((entry) => ({ id: String(entry?.id ?? ""), desc: entry?.desc === true }));
+}
+function normalizeSearch(searchValue) {
+  return typeof searchValue === "string" ? searchValue.trim() : "";
+}
+function diffPerspectiveSettings(base, current, options) {
+  const baseSettings = base ?? {};
+  const currentSettings = current ?? {};
+  const defaultColumnOrder = options?.defaultColumnOrder ?? [];
+  const changed = [];
+  const baseOrder = normalizeOrder(baseSettings.columnOrder, defaultColumnOrder);
+  const currentOrder = normalizeOrder(currentSettings.columnOrder, defaultColumnOrder);
+  if (stableStringify(baseOrder) !== stableStringify(currentOrder)) changed.push("columnOrder");
+  if (stableStringify(normalizeVisibility(baseSettings.columnVisibility)) !== stableStringify(normalizeVisibility(currentSettings.columnVisibility))) changed.push("columnVisibility");
+  if (stableStringify(normalizeSizing(baseSettings.columnSizing)) !== stableStringify(normalizeSizing(currentSettings.columnSizing))) changed.push("columnSizing");
+  if (stableStringify(normalizeSorting(baseSettings.sorting)) !== stableStringify(normalizeSorting(currentSettings.sorting))) changed.push("sorting");
+  if (stableStringify(baseSettings.filters ?? null) !== stableStringify(currentSettings.filters ?? null)) {
+    changed.push("filters");
+  }
+  if (normalizeSearch(baseSettings.searchValue) !== normalizeSearch(currentSettings.searchValue)) {
+    changed.push("searchValue");
+  }
+  return changed;
+}
+export {
+  diffPerspectiveSettings
+};
+//# sourceMappingURL=perspectiveDirty.js.map

package/dist/backend/perspectiveDirty.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/backend/perspectiveDirty.ts"],
+  "sourcesContent": ["import type { PerspectiveSettings } from '@open-mercato/shared/modules/perspectives/types'\n\n/**\n * Setting groups the unsaved-changes comparison tracks.\n *\n * `pageSize` is deliberately absent: `DataTable` never emits it from\n * `getCurrentSettings()`, so comparing it would report a permanent\n * false-positive for every saved view that carries one.\n */\nexport type DataTableViewSettingKey =\n  | 'columnOrder'\n  | 'columnVisibility'\n  | 'columnSizing'\n  | 'sorting'\n  | 'filters'\n  | 'searchValue'\n\n/** Read-only view state handed to `DataTableProps.onColumnsDirtyChange`. */\nexport type DataTableViewDirtyState = {\n  /** True when the live table settings differ from the last applied/saved view. */\n  isDirty: boolean\n  /** Which setting groups differ, in a stable order. */\n  changedKeys: DataTableViewSettingKey[]\n  /** `changedKeys.length` \u2014 ready to render as a badge counter. */\n  changedCount: number\n  /** The currently applied perspective (personal or role), if any. */\n  activePerspectiveId: string | null\n  /**\n   * True when a save can target the active personal view without asking for a\n   * name. Role perspectives and \"No view\" both yield false \u2014 those need the\n   * views sidebar (or an explicit `name`) to save.\n   */\n  canSaveToActiveView: boolean\n}\n\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null)\n  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(',')}]`\n  const entries = Object.entries(value as Record<string, unknown>)\n    .filter(([, entryValue]) => entryValue !== undefined)\n    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))\n  return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(',')}}`\n}\n\nfunction normalizeOrder(order: string[] | undefined, fallback: string[]): string[] {\n  return Array.isArray(order) && order.length > 0 ? order : fallback\n}\n\n/**\n * `true` entries are equivalent to an absent entry: the column chooser deletes a\n * column's record when it is turned back on, so `{ name: true }` and `{}` both\n * mean \"name is visible\".\n */\nfunction normalizeVisibility(visibility: Record<string, boolean> | undefined): Record<string, boolean> {\n  if (!visibility) return {}\n  const result: Record<string, boolean> = {}\n  for (const [key, value] of Object.entries(visibility)) {\n    if (value === false) result[key] = false\n  }\n  return result\n}\n\nfunction normalizeSizing(sizing: Record<string, number> | undefined): Record<string, number> {\n  if (!sizing) return {}\n  const result: Record<string, number> = {}\n  for (const [key, value] of Object.entries(sizing)) {\n    if (typeof value === 'number' && Number.isFinite(value)) result[key] = Math.round(value)\n  }\n  return result\n}\n\nfunction normalizeSorting(sorting: PerspectiveSettings['sorting']): Array<{ id: string; desc: boolean }> {\n  if (!Array.isArray(sorting)) return []\n  return sorting.map((entry) => ({ id: String(entry?.id ?? ''), desc: entry?.desc === true }))\n}\n\nfunction normalizeSearch(searchValue: string | undefined): string {\n  return typeof searchValue === 'string' ? searchValue.trim() : ''\n}\n\nexport type DiffPerspectiveSettingsOptions = {\n  /**\n   * Column ids in their natural (unordered) sequence. Used as the baseline for\n   * `columnOrder` when neither side stored one, so a table that merely\n   * materialized its default order is not reported as dirty.\n   */\n  defaultColumnOrder?: string[]\n}\n\n/**\n * Compare the live table settings against the settings of the last applied or\n * saved view and return the setting groups that differ.\n *\n * Both sides are expected to be sanitized (`sanitizePerspectiveSettings`), and\n * the comparison is intentionally value-based rather than reference-based so a\n * re-render alone never flips the result.\n */\nexport function diffPerspectiveSettings(\n  base: PerspectiveSettings | null | undefined,\n  current: PerspectiveSettings | null | undefined,\n  options?: DiffPerspectiveSettingsOptions,\n): DataTableViewSettingKey[] {\n  const baseSettings = base ?? {}\n  const currentSettings = current ?? {}\n  const defaultColumnOrder = options?.defaultColumnOrder ?? []\n  const changed: DataTableViewSettingKey[] = []\n\n  const baseOrder = normalizeOrder(baseSettings.columnOrder, defaultColumnOrder)\n  const currentOrder = normalizeOrder(currentSettings.columnOrder, defaultColumnOrder)\n  if (stableStringify(baseOrder) !== stableStringify(currentOrder)) changed.push('columnOrder')\n\n  if (\n    stableStringify(normalizeVisibility(baseSettings.columnVisibility))\n    !== stableStringify(normalizeVisibility(currentSettings.columnVisibility))\n  ) changed.push('columnVisibility')\n\n  if (\n    stableStringify(normalizeSizing(baseSettings.columnSizing))\n    !== stableStringify(normalizeSizing(currentSettings.columnSizing))\n  ) changed.push('columnSizing')\n\n  if (\n    stableStringify(normalizeSorting(baseSettings.sorting))\n    !== stableStringify(normalizeSorting(currentSettings.sorting))\n  ) changed.push('sorting')\n\n  if (stableStringify(baseSettings.filters ?? null) !== stableStringify(currentSettings.filters ?? null)) {\n    changed.push('filters')\n  }\n\n  if (normalizeSearch(baseSettings.searchValue) !== normalizeSearch(currentSettings.searchValue)) {\n    changed.push('searchValue')\n  }\n\n  return changed\n}\n"],
+  "mappings": "AAmCA,SAAS,gBAAgB,OAAwB;AAC/C,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO,KAAK,UAAU,SAAS,IAAI;AACpF,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,IAAI,MAAM,IAAI,CAAC,UAAU,gBAAgB,KAAK,CAAC,EAAE,KAAK,GAAG,CAAC;AAC3F,QAAM,UAAU,OAAO,QAAQ,KAAgC,EAC5D,OAAO,CAAC,CAAC,EAAE,UAAU,MAAM,eAAe,MAAS,EACnD,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,MAAO,OAAO,QAAQ,KAAK,OAAO,QAAQ,IAAI,CAAE;AACvE,SAAO,IAAI,QAAQ,IAAI,CAAC,CAAC,KAAK,UAAU,MAAM,GAAG,KAAK,UAAU,GAAG,CAAC,IAAI,gBAAgB,UAAU,CAAC,EAAE,EAAE,KAAK,GAAG,CAAC;AAClH;AAEA,SAAS,eAAe,OAA6B,UAA8B;AACjF,SAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,IAAI,QAAQ;AAC5D;AAOA,SAAS,oBAAoB,YAA0E;AACrG,MAAI,CAAC,WAAY,QAAO,CAAC;AACzB,QAAM,SAAkC,CAAC;AACzC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,UAAU,GAAG;AACrD,QAAI,UAAU,MAAO,QAAO,GAAG,IAAI;AAAA,EACrC;AACA,SAAO;AACT;AAEA,SAAS,gBAAgB,QAAoE;AAC3F,MAAI,CAAC,OAAQ,QAAO,CAAC;AACrB,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,GAAG,IAAI,KAAK,MAAM,KAAK;AAAA,EACzF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,SAA+E;AACvG,MAAI,CAAC,MAAM,QAAQ,OAAO,EAAG,QAAO,CAAC;AACrC,SAAO,QAAQ,IAAI,CAAC,WAAW,EAAE,IAAI,OAAO,OAAO,MAAM,EAAE,GAAG,MAAM,OAAO,SAAS,KAAK,EAAE;AAC7F;AAEA,SAAS,gBAAgB,aAAyC;AAChE,SAAO,OAAO,gBAAgB,WAAW,YAAY,KAAK,IAAI;AAChE;AAmBO,SAAS,wBACd,MACA,SACA,SAC2B;AAC3B,QAAM,eAAe,QAAQ,CAAC;AAC9B,QAAM,kBAAkB,WAAW,CAAC;AACpC,QAAM,qBAAqB,SAAS,sBAAsB,CAAC;AAC3D,QAAM,UAAqC,CAAC;AAE5C,QAAM,YAAY,eAAe,aAAa,aAAa,kBAAkB;AAC7E,QAAM,eAAe,eAAe,gBAAgB,aAAa,kBAAkB;AACnF,MAAI,gBAAgB,SAAS,MAAM,gBAAgB,YAAY,EAAG,SAAQ,KAAK,aAAa;AAE5F,MACE,gBAAgB,oBAAoB,aAAa,gBAAgB,CAAC,MAC9D,gBAAgB,oBAAoB,gBAAgB,gBAAgB,CAAC,EACzE,SAAQ,KAAK,kBAAkB;AAEjC,MACE,gBAAgB,gBAAgB,aAAa,YAAY,CAAC,MACtD,gBAAgB,gBAAgB,gBAAgB,YAAY,CAAC,EACjE,SAAQ,KAAK,cAAc;AAE7B,MACE,gBAAgB,iBAAiB,aAAa,OAAO,CAAC,MAClD,gBAAgB,iBAAiB,gBAAgB,OAAO,CAAC,EAC7D,SAAQ,KAAK,SAAS;AAExB,MAAI,gBAAgB,aAAa,WAAW,IAAI,MAAM,gBAAgB,gBAAgB,WAAW,IAAI,GAAG;AACtG,YAAQ,KAAK,SAAS;AAAA,EACxB;AAEA,MAAI,gBAAgB,aAAa,WAAW,MAAM,gBAAgB,gBAAgB,WAAW,GAAG;AAC9F,YAAQ,KAAK,aAAa;AAAA,EAC5B;AAEA,SAAO;AACT;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.6.8-develop.6914.1.6c7a5dcb6b",
+  "version": "0.6.8-develop.6916.1.f04fff3436",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -155,14 +155,14 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6914.1.6c7a5dcb6b",
+    "@open-mercato/shared": "0.6.8-develop.6916.1.f04fff3436",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-is": ">=18.0.0"
   },
   "devDependencies": {
     "@figma/code-connect": "^1.3.4",
-    "@open-mercato/shared": "0.6.8-develop.6914.1.6c7a5dcb6b",
+    "@open-mercato/shared": "0.6.8-develop.6916.1.f04fff3436",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.1",

package/src/backend/DataTable.tsx

@@ -4,7 +4,7 @@ import { useRouter } from 'next/navigation'
 import { flexRender, type RowData, type SortingState, type ColumnVisibilityState as VisibilityState, type RowSelectionState } from '@tanstack/react-table'
 import { useLegacyTable, getCoreRowModel, getSortedRowModel, type LegacyColumnDef as ColumnDef, type LegacyColumn as TableColumn } from '@tanstack/react-table/legacy'
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { RefreshCw, Loader2, SlidersHorizontal, MoreHorizontal, Circle, Filter, Columns3, ChevronUp, ChevronDown, ChevronsUpDown, Check, Inbox } from 'lucide-react'
+import { RefreshCw, Loader2, SlidersHorizontal, MoreHorizontal, Circle, Filter, Columns3, ChevronUp, ChevronDown, ChevronsUpDown, Check, Inbox, Save } from 'lucide-react'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../primitives/table'
 import { Button } from '../primitives/button'
 import { Checkbox } from '../primitives/checkbox'
@@ -46,6 +46,7 @@ import { readVersionedPreference, writeVersionedPreference, clearVersionedPrefer
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { flash } from './FlashMessages'
 import { useConfirmDialog } from './confirm-dialog'
+import { surfaceRecordConflict } from './conflicts'
 import type {
   PerspectiveDto,
   RolePerspectiveDto,
@@ -97,10 +98,13 @@ import {
 import { CSS } from '@dnd-kit/utilities'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import { clearAllPerspectiveState, PERSPECTIVE_COOKIE_PREFIX, PERSPECTIVE_STORAGE_PREFIX } from './perspectiveState'
+import { diffPerspectiveSettings } from './perspectiveDirty'
+import type { DataTableViewDirtyState, DataTableViewSettingKey } from './perspectiveDirty'
 
 // Re-exported so `@open-mercato/ui/backend/DataTable` stays the published import
 // path for the purge (BACKWARD_COMPATIBILITY: import paths are a contract surface).
 export { clearAllPerspectiveState }
+export type { DataTableViewDirtyState, DataTableViewSettingKey }
 
 const logger = createLogger('ui').child({ component: 'DataTable' })
 
@@ -216,6 +220,61 @@ export type DataTablePerspectiveConfig = {
   }
 }
 
+/** Input for the imperative `saveCurrentView` action. */
+export type DataTableSaveViewInput = {
+  /**
+   * Name for the saved view. Optional when a personal view is active — the
+   * active view's own name is reused and the save updates it in place.
+   */
+  name?: string
+  /**
+   * Target view id. Defaults to the active personal view; pass `null` to force
+   * creating a new view (then `name` is required).
+   */
+  perspectiveId?: string | null
+  /** Marks the saved view as the user's default. Defaults to the target's current flag. */
+  isDefault?: boolean
+}
+
+/**
+ * Outcome of `saveCurrentView`. Returned rather than thrown so a host toolbar
+ * button can branch on `reason` (e.g. open the views sidebar to ask for a name)
+ * without wrapping every call in try/catch.
+ */
+export type DataTableSaveViewResult =
+  | { ok: true; perspectiveId: string | null }
+  | {
+      ok: false
+      /**
+       * `not-ready` — the perspectives permission check has not resolved yet.
+       * Nothing was saved and nothing is wrong: retry once the table has
+       * settled. Distinct from `perspectives-disabled`, which is a definitive
+       * "this user may not use views" and should be surfaced as such.
+       */
+      reason: 'perspectives-disabled' | 'not-ready' | 'name-required' | 'failed'
+      error?: unknown
+    }
+
+/**
+ * Imperative handle exposed through `DataTableProps.viewApiRef`, so a host app
+ * can build its own "Save view" affordance without patching this component.
+ */
+export type DataTableViewApi = {
+  /** The live table settings, in the shape a perspective persists. */
+  getCurrentSettings: () => PerspectiveSettings
+  /** The current unsaved-changes state — the pull counterpart of `onColumnsDirtyChange`. */
+  getDirtyState: () => DataTableViewDirtyState
+  /** Persists the live settings into a saved view. */
+  saveCurrentView: (input?: DataTableSaveViewInput) => Promise<DataTableSaveViewResult>
+  /**
+   * Opens the built-in views sidebar (where a new view can be named and saved).
+   * No-op for a user without the `perspectives.use` feature — the sidebar closes
+   * again on the next render — so a host offering this action should gate it on
+   * the same permission rather than expecting an error.
+   */
+  openViewsSidebar: () => void
+}
+
 export type BulkAction<T = Record<string, unknown>> = {
   id: string
   label: string
@@ -259,6 +318,26 @@ export type DataTableProps<T extends RowData> = {
   entityIds?: string[]
   exporter?: DataTableExportConfig | false
   perspective?: DataTablePerspectiveConfig
+  /**
+   * Notified whenever the unsaved-changes state of the current view changes.
+   * Read-only: it never alters the table's own behavior, it lets a host render
+   * its own indicator ("3 unsaved changes") next to a custom save affordance.
+   * Only fires for tables that wire `perspective`.
+   */
+  onColumnsDirtyChange?: (state: DataTableViewDirtyState) => void
+  /**
+   * Imperative handle for the view/perspective surface (`saveCurrentView`,
+   * `getDirtyState`, `getCurrentSettings`, `openViewsSidebar`). Pairs with
+   * `onColumnsDirtyChange` so a host can render a "Save view" button in its own
+   * toolbar instead of relying on the built-in one.
+   */
+  viewApiRef?: React.Ref<DataTableViewApi | null>
+  /**
+   * Renders the built-in "Save view" toolbar button next to the views switcher.
+   * Off by default — the perspectives sidebar stays the default save path, so
+   * existing call sites are unaffected. Requires `perspective`.
+   */
+  showSaveViewButton?: boolean
   embedded?: boolean
   onCustomFieldFilterFieldsetChange?: (fieldset: string | null, entityId?: string) => void
   customFieldFilterKeyExtras?: Array<string | number | boolean | null | undefined>
@@ -372,6 +451,8 @@ const EXPORT_LABELS: Record<DataTableExportFormat, string> = {
 }
 const EMPTY_FILTER_DEFS: FilterDef[] = []
 const EMPTY_FILTER_VALUES: FilterValues = Object.freeze({}) as FilterValues
+/** Stand-in for the live view settings on tables that never opt into the view API. */
+const EMPTY_VIEW_SETTINGS: PerspectiveSettings = Object.freeze({}) as PerspectiveSettings
 
 // Directional shadow utilities for sticky table cells. `border-collapse: collapse`
 // blocks `box-shadow` on `<td>`/`<th>`, so we paint the shadow as a pseudo-element
@@ -1146,6 +1227,9 @@ export function DataTable<T extends RowData>({
   entityIds,
   exporter,
   perspective,
+  onColumnsDirtyChange,
+  viewApiRef,
+  showSaveViewButton = false,
   embedded = false,
   onCustomFieldFilterFieldsetChange,
   customFieldFilterKeyExtras,
@@ -1239,8 +1323,16 @@ export function DataTable<T extends RowData>({
   // hydration mismatch. Initial render uses only props-derived state (identical on both sides).
   const initialSnapshotRef = React.useRef<PerspectiveSnapshot | null>(null)
   const snapshotHydratedTableRef = React.useRef<string | null>(null)
-  const initialSettingsFromConfig = sanitizePerspectiveSettings(perspectiveConfig?.initialState?.initialSettings ?? null)
-  const mergedInitialSettings = initialSettingsFromConfig
+  const initialSettingsSource = perspectiveConfig?.initialState?.initialSettings ?? null
+  // Memoized on the host's own object: `sanitizePerspectiveSettings` returns a
+  // fresh result on every call, so without this every effect keyed on the
+  // sanitized settings would re-run after every render — including the one that
+  // seeds the view baseline, which would then keep resetting an applied view's
+  // baseline back to the server-supplied initial settings.
+  const mergedInitialSettings = React.useMemo(
+    () => sanitizePerspectiveSettings(initialSettingsSource),
+    [initialSettingsSource],
+  )
   const initialActiveId = perspectiveConfig?.initialState?.activePerspectiveId ?? null
   const [isPerspectiveOpen, setPerspectiveOpen] = React.useState(false)
   const [isAdvancedFilterOpen, setAdvancedFilterOpen] = React.useState(false)
@@ -1255,6 +1347,22 @@ export function DataTable<T extends RowData>({
   const [deletingIds, setDeletingIds] = React.useState<string[]>([])
   const [roleClearingIds, setRoleClearingIds] = React.useState<string[]>([])
   const [perspectiveApiMissing, setPerspectiveApiMissing] = React.useState(false)
+  // Settings the current view was last applied from (mount-time snapshot restore,
+  // perspective activation, "No view" clear, successful save). The public
+  // dirty state is measured against this, so a table only reports unsaved
+  // changes once the user actually changes something after that point.
+  const [viewBaseline, setViewBaselineState] = React.useState<PerspectiveSettings>(() => mergedInitialSettings ?? {})
+  const viewBaselineInitializedRef = React.useRef(Boolean(mergedInitialSettings))
+  const setViewBaseline = React.useCallback((settings: PerspectiveSettings) => {
+    const initialized = viewBaselineInitializedRef.current
+    viewBaselineInitializedRef.current = true
+    // Compared by value, not by identity: the callers hand over freshly
+    // sanitized objects (a new one on every render), so storing them blindly
+    // would let an effect keyed on those settings re-trigger itself forever.
+    setViewBaselineState((previous) => (
+      initialized && diffPerspectiveSettings(previous, settings).length === 0 ? previous : settings
+    ))
+  }, [])
 
   const perspectiveFeatureQuery = useQuery<{ use: boolean; roleDefaults: boolean }>({
     queryKey: ['feature-check', 'perspectives'],
@@ -1304,9 +1412,16 @@ export function DataTable<T extends RowData>({
     }
   }, [canUsePerspectives, isPerspectiveOpen])
 
+  // Seeded once per table, like the localStorage hydration above. The server's
+  // initial settings describe the state the table mounts in, not a state to
+  // return to: re-running this after the user activates a view would overwrite
+  // that view's baseline and report changes nobody made.
+  const initialSettingsSeededTableRef = React.useRef<string | null>(null)
   React.useEffect(() => {
     if (!perspectiveTableId) return
     if (!mergedInitialSettings) return
+    if (initialSettingsSeededTableRef.current === perspectiveTableId) return
+    initialSettingsSeededTableRef.current = perspectiveTableId
     const snapshot: PerspectiveSnapshot = {
       perspectiveId: initialActiveId,
       settings: mergedInitialSettings,
@@ -1314,7 +1429,8 @@ export function DataTable<T extends RowData>({
     }
     writePerspectiveSnapshot(perspectiveTableId, snapshot)
     initialSnapshotRef.current = snapshot
-  }, [perspectiveTableId, mergedInitialSettings, initialActiveId])
+    setViewBaseline(mergedInitialSettings)
+  }, [perspectiveTableId, mergedInitialSettings, initialActiveId, setViewBaseline])
 
   const perspectiveQuery = useQuery<PerspectivesIndexResponse>({
     queryKey: ['table-perspectives', perspectiveTableId],
@@ -1777,6 +1893,15 @@ export function DataTable<T extends RowData>({
     },
   ) => {
     const normalized = sanitizePerspectiveSettings(settings) ?? {}
+    // `preserveAdvancedFilter` leaves the host's filter state untouched, so the
+    // applied settings' `filters` never become the live ones — keeping the live
+    // payload here is what stops the mount-time restore from reporting a
+    // filter change the user never made.
+    setViewBaseline(
+      options?.preserveAdvancedFilter
+        ? { ...normalized, filters: getCurrentSettings().filters }
+        : normalized,
+    )
     if (normalized.columnOrder && normalized.columnOrder.length) {
       setColumnOrder(normalized.columnOrder)
     } else {
@@ -1855,7 +1980,7 @@ export function DataTable<T extends RowData>({
         initialSnapshotRef.current = null
       }
     }
-  }, [onFiltersApply, onSearchChange, onSortingChange, perspectiveTableId, table, advancedFilter])
+  }, [onFiltersApply, onSearchChange, onSortingChange, perspectiveTableId, table, advancedFilter, getCurrentSettings, setViewBaseline])
 
   // Persist the current column widths into the local snapshot so they survive a
   // refresh even without saving a perspective (#1835). Widths are merged into the
@@ -2190,6 +2315,155 @@ export function DataTable<T extends RowData>({
     })
   }, [savePerspectiveMutation, activePersonalPerspectiveId])
 
+  const defaultColumnOrderIds = React.useMemo(
+    () => table.getAllLeafColumns().map((column) => column.id),
+    [table, mergedColumns],
+  )
+  // Nothing consumes the dirty state unless the host asked for it, and computing
+  // it is not free: `getCurrentSettings` serializes the advanced-filter tree and
+  // the diff runs six `stableStringify` passes. Tables that never opt in — every
+  // existing call site — must keep paying exactly what they paid before.
+  const viewApiRequested = Boolean(onColumnsDirtyChange || viewApiRef || showSaveViewButton)
+  const currentViewSettings = React.useMemo(
+    () => (viewApiRequested ? getCurrentSettings() : EMPTY_VIEW_SETTINGS),
+    [viewApiRequested, getCurrentSettings],
+  )
+
+  const viewDirtyState = React.useMemo<DataTableViewDirtyState>(() => {
+    // Before the baseline is established there is nothing to compare against, so
+    // the view is reported clean rather than flashing a spurious change. The
+    // active view id is still reported — a host rendering "Viewing: {name}" from
+    // this state should not see a null while only the baseline is pending.
+    if (!viewApiRequested || !perspectiveEnabled || !viewBaselineInitializedRef.current) {
+      return {
+        isDirty: false,
+        changedKeys: [],
+        changedCount: 0,
+        activePerspectiveId,
+        canSaveToActiveView: false,
+      }
+    }
+    const changedKeys = diffPerspectiveSettings(viewBaseline, currentViewSettings, {
+      defaultColumnOrder: defaultColumnOrderIds,
+    })
+    return {
+      isDirty: changedKeys.length > 0,
+      changedKeys,
+      changedCount: changedKeys.length,
+      activePerspectiveId,
+      canSaveToActiveView: Boolean(activePersonalPerspectiveId),
+    }
+  }, [
+    viewApiRequested,
+    perspectiveEnabled,
+    viewBaseline,
+    currentViewSettings,
+    defaultColumnOrderIds,
+    activePerspectiveId,
+    activePersonalPerspectiveId,
+  ])
+
+  // A page can hand the table its own starting point — default sorting, a search
+  // term hydrated from the URL — none of which is a user change. Whatever the
+  // table settled on before anything was applied is the baseline; the snapshot
+  // restore in `applyPerspectiveSettings` runs in a layout effect and claims the
+  // baseline first when it has one, so this never overwrites a restored view.
+  React.useEffect(() => {
+    if (!viewApiRequested || !perspectiveEnabled || viewBaselineInitializedRef.current) return
+    setViewBaseline(currentViewSettings)
+  }, [viewApiRequested, perspectiveEnabled, currentViewSettings, setViewBaseline])
+
+  // Mirrored in a layout effect rather than during render: a render React throws
+  // away must not leave these mirrors holding values that were never committed.
+  // Layout timing keeps them current for the imperative handle below, which is
+  // itself established in a layout effect declared after this one.
+  const viewDirtyStateRef = React.useRef(viewDirtyState)
+  const onColumnsDirtyChangeRef = React.useRef(onColumnsDirtyChange)
+  React.useLayoutEffect(() => {
+    viewDirtyStateRef.current = viewDirtyState
+    onColumnsDirtyChangeRef.current = onColumnsDirtyChange
+  }, [viewDirtyState, onColumnsDirtyChange])
+  const lastDirtySignatureRef = React.useRef<string | null>(null)
+  React.useEffect(() => {
+    const notify = onColumnsDirtyChangeRef.current
+    if (!notify || !perspectiveEnabled) return
+    // Compared by value, not by object identity: a host that recreates the
+    // callback (or receives a fresh state object each render) must not be able
+    // to turn its own setState into a notification loop.
+    const signature = JSON.stringify([
+      viewDirtyState.isDirty,
+      viewDirtyState.changedKeys,
+      viewDirtyState.activePerspectiveId,
+      viewDirtyState.canSaveToActiveView,
+    ])
+    if (lastDirtySignatureRef.current === signature) return
+    lastDirtySignatureRef.current = signature
+    notify(viewDirtyState)
+  }, [viewDirtyState, perspectiveEnabled])
+
+  const saveCurrentView = React.useCallback(async (
+    input?: DataTableSaveViewInput,
+  ): Promise<DataTableSaveViewResult> => {
+    if (!perspectiveTableId) return { ok: false, reason: 'perspectives-disabled' }
+    // The permission check is a query: until it resolves, "may this user save a
+    // view" is unknown rather than false. Reporting `perspectives-disabled` here
+    // would have a host tell the user views are off when they are merely slow.
+    if (perspectivePermissions === undefined) return { ok: false, reason: 'not-ready' }
+    if (!canUsePerspectives) return { ok: false, reason: 'perspectives-disabled' }
+    const targetId = input?.perspectiveId !== undefined ? input.perspectiveId : activePersonalPerspectiveId
+    const existing = targetId
+      ? perspectiveData?.perspectives.find((item) => item.id === targetId) ?? null
+      : null
+    const name = (input?.name ?? existing?.name ?? '').trim()
+    // Creating a view needs a name, and this API deliberately does not invent
+    // one — the host either supplies it or sends the user to the sidebar.
+    if (!name) return { ok: false, reason: 'name-required' }
+    try {
+      const saved = await savePerspectiveMutation.mutateAsync({
+        name,
+        isDefault: input?.isDefault ?? existing?.isDefault ?? false,
+        applyToRoles: [],
+        setRoleDefault: false,
+        perspectiveId: targetId ?? null,
+      })
+      return { ok: true, perspectiveId: saved?.perspective?.id ?? null }
+    } catch (error) {
+      return { ok: false, reason: 'failed', error }
+    }
+  }, [
+    canUsePerspectives,
+    perspectivePermissions,
+    perspectiveTableId,
+    activePersonalPerspectiveId,
+    perspectiveData,
+    savePerspectiveMutation,
+  ])
+
+  React.useImperativeHandle(viewApiRef, () => ({
+    getCurrentSettings: () => getCurrentSettings(),
+    getDirtyState: () => viewDirtyStateRef.current,
+    saveCurrentView,
+    openViewsSidebar: () => setPerspectiveOpen(true),
+  }), [getCurrentSettings, saveCurrentView])
+
+  const handleSaveViewClick = React.useCallback(async () => {
+    const result = await saveCurrentView()
+    if (result.ok) {
+      flash(t('ui.dataTable.saveView.success', 'View saved'), 'success')
+      return
+    }
+    if (result.reason === 'name-required') {
+      // No personal view is active, so the save needs a name: hand the user the
+      // existing sidebar flow rather than inventing one.
+      setPerspectiveOpen(true)
+      return
+    }
+    if (result.reason === 'failed') {
+      if (surfaceRecordConflict(result.error, t)) return
+      flash(t('ui.dataTable.saveView.error', 'Failed to save view'), 'error')
+    }
+  }, [saveCurrentView, t])
+
   const handlePerspectiveDelete = React.useCallback(async (perspectiveId: string) => {
     await deletePerspectiveMutation.mutateAsync({ perspectiveId })
   }, [deletePerspectiveMutation])
@@ -2767,10 +3041,34 @@ export function DataTable<T extends RowData>({
           </div>
         )
         : null
-    const leadingItems = advancedFilterButton || perspectiveButton ? (
+    const saveViewButton = showSaveViewButton && canUsePerspectives ? (
+      <Button
+        type="button"
+        variant="outline"
+        size="default"
+        disabled={!viewDirtyState.isDirty || savePerspectiveMutation.isPending}
+        onClick={() => { void handleSaveViewClick() }}
+        title={viewDirtyState.isDirty
+          ? t('ui.dataTable.saveView.title', 'Save the current view')
+          : t('ui.dataTable.saveView.noChanges', 'No unsaved changes')}
+        data-testid="save-view-trigger"
+      >
+        {savePerspectiveMutation.isPending
+          ? <Loader2 className="h-4 w-4 animate-spin" />
+          : <Save className="h-4 w-4" />}
+        <span>{t('ui.dataTable.saveView.button', 'Save view')}</span>
+        {viewDirtyState.changedCount > 0 ? (
+          <span className="ml-1 inline-flex h-5 min-w-5 px-1.5 items-center justify-center rounded-full bg-muted-foreground/30 text-background text-xs">
+            {viewDirtyState.changedCount}
+          </span>
+        ) : null}
+      </Button>
+    ) : null
+    const leadingItems = advancedFilterButton || perspectiveButton || saveViewButton ? (
       <div className="flex items-center gap-2">
         {advancedFilterButton}
         {perspectiveButton}
+        {saveViewButton}
       </div>
     ) : null
     const trailingItems = hasBulkButtons ? (
@@ -2869,6 +3167,11 @@ export function DataTable<T extends RowData>({
     advancedFilterRuleCount,
     isAdvancedFilterOpen,
     resolvedAdvancedFilterFields,
+    showSaveViewButton,
+    viewDirtyState,
+    savePerspectiveMutation.isPending,
+    handleSaveViewClick,
+    t,
   ])
 
   const hasTitle = title != null