@jxsuite/studio 2.0.1 → 2.1.0

package/src/grid/grid-controller.ts

@@ -13,18 +13,21 @@
  */
 import { effect, onScopeDispose, reactive, toRaw } from "../reactivity";
 import { getPlatform } from "../platform";
+import { notify } from "../services/notify";
 import { setHistoryDelegate } from "../tabs/transact";
 import { isRecentLocal } from "../files/fs-events";
-import { statusMessage } from "../panels/statusbar";
 import { showConfirmDialog } from "../ui/layers";
 import { showProgressModal } from "../ui/progress-modal";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { createEditBuffer } from "./edit-buffer";
+import { cellToText } from "./schema-columns";
 import type { EditBuffer } from "./edit-buffer";
+import type { GridSortSpec } from "./grid-layout";
 import type {
   CommitResult,
   GridCellValue,
   GridColumn,
+  GridColumnKind,
   GridEditBatch,
   GridQuery,
   GridRow,
@@ -41,6 +44,21 @@ export interface GridControllerState {
   saving: boolean;
   error: string | null;
   query: GridQuery;
+  /**
+   * The field whose value gathers rows into contiguous groups, or null.
+   *
+   * Grouping is a ROW ORDER, not a second data set: {@link GridController.effectiveRows} emits the
+   * groups back to back in first-appearance order, so every layer above — the engine, the
+   * clipboard, Fill Down — sees one list and needs to know nothing about groups.
+   */
+  grouping: string | null;
+}
+
+/** One group of the current grouping, in the order {@link GridController.effectiveRows} emits them. */
+export interface GridGroup {
+  /** The group field's text value; `""` for rows where it is empty. */
+  value: string;
+  count: number;
 }
 
 /** What the engine wrapper exposes back to the controller for out-of-band data changes. */
@@ -60,6 +78,20 @@ export interface GridController {
   save: () => Promise<void>;
   /** Query change (connector paging/sorting) — reloads rows. */
   setQuery: (query: GridQuery) => Promise<void>;
+  /**
+   * Set (or clear) the row order.
+   *
+   * ONE sort contract for every source. `GridQuery.orderBy`/`dir` has always been the way a source
+   * is asked for an order, and a remote-sorting source still answers it by reloading; a source that
+   * does not sort remotely is now sorted here instead of the query being silently ignored, which is
+   * what let a saved view record a sort nothing applied. A header click in the engine is a
+   * separate, ad-hoc re-sort of what is already loaded and is deliberately not captured by a view.
+   */
+  setSort: (sort: GridSortSpec | null) => Promise<void>;
+  /** Group rows contiguously by a field's value, or ungroup with null. */
+  setGrouping: (field: string | null) => void;
+  /** The groups the current grouping produces, in emitted order. Empty when ungrouped. */
+  groups: () => GridGroup[];
   /** Plain row objects (committed + pending overlay + pending inserts) for the grid engine. */
   effectiveRows: () => Record<string, GridCellValue>[];
   /** Current file text including pending edits, for source-mode display (file grids only). */
@@ -91,6 +123,7 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
   const state: GridControllerState = reactive({
     columns: [] as GridColumn[],
     error: null as string | null,
+    grouping: null as string | null,
     loading: false,
     query: {} as GridQuery,
     rows: [] as GridRow[],
@@ -140,6 +173,64 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
     return { cells, deletes: [], inserts };
   };
 
+  // ─── Row order: grouping first, then sort ───────────────────────────────────
+
+  /** Whether a cell has nothing in it. Blanks sort LAST in both directions — a hole is not a value. */
+  const isBlank = (value: GridCellValue) =>
+    value === null || value === "" || (Array.isArray(value) && value.length === 0);
+
+  const compareCells = (a: GridCellValue, b: GridCellValue, kind: GridColumnKind | undefined) => {
+    if (kind === "number") {
+      return (typeof a === "number" ? a : 0) - (typeof b === "number" ? b : 0);
+    }
+    if (kind === "boolean") {
+      return (a === true ? 1 : 0) - (b === true ? 1 : 0);
+    }
+    return cellToText(a).localeCompare(cellToText(b));
+  };
+
+  /**
+   * Committed row keys in display order: grouped, then sorted within each group.
+   *
+   * Sorting is skipped for a source that sorts remotely — it already answered the query, and
+   * re-sorting its answer locally would reorder one PAGE of a result set by a rule the other pages
+   * were not subject to. Pending inserts are never in here: a row you just added stays at the
+   * bottom where you added it, rather than sorting itself out of sight while you are still typing
+   * into it.
+   */
+  const orderedKeys = (): string[] => {
+    let keys = state.rows.map((row) => row.key);
+    const { dir, orderBy } = state.query;
+    if (orderBy && !source.capabilities.remoteSort) {
+      const kind = state.columns.find((column) => column.field === orderBy)?.kind;
+      const sign = dir === "desc" ? -1 : 1;
+      keys = keys.toSorted((ka, kb) => {
+        const a = buffer.effectiveValue(ka, orderBy);
+        const b = buffer.effectiveValue(kb, orderBy);
+        if (isBlank(a) !== isBlank(b)) {
+          return isBlank(a) ? 1 : -1;
+        }
+        return sign * compareCells(a, b, kind);
+      });
+    }
+    return state.grouping ? [...groupBuckets(keys).values()].flat() : keys;
+  };
+
+  /** Group key → row keys, in first-appearance order. Called only when `state.grouping` is set. */
+  const groupBuckets = (keys: string[]): Map<string, string[]> => {
+    const buckets = new Map<string, string[]>();
+    for (const key of keys) {
+      const value = cellToText(buffer.effectiveValue(key, state.grouping!));
+      const bucket = buckets.get(value);
+      if (bucket) {
+        bucket.push(key);
+      } else {
+        buckets.set(value, [key]);
+      }
+    }
+    return buckets;
+  };
+
   let viewBinding: GridViewBinding | null = null;
   const syncView = () => viewBinding?.refreshData();
 
@@ -217,13 +308,23 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
         }
         return cells;
       };
-      const rows = state.rows.map((row) => rowObject(row.key));
+      const rows = orderedKeys().map((key) => rowObject(key));
       for (const [tempKey] of buffer.state.inserts) {
         rows.push(rowObject(tempKey));
       }
       return rows;
     },
 
+    groups() {
+      if (!state.grouping) {
+        return [];
+      }
+      return [...groupBuckets(orderedKeys())].map(([value, keys]) => ({
+        count: keys.length,
+        value,
+      }));
+    },
+
     async load() {
       state.loading = true;
       state.error = null;
@@ -261,13 +362,17 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
       const batch = buffer.buildBatch();
       const changeCount = batch.cells.length + batch.inserts.length + batch.deletes.length;
       if (changeCount === 0) {
-        statusMessage("No grid changes to save");
+        notify.info("No grid changes to save.", { key: "grid.save" });
         return;
       }
       const violations = requiredViolations(batch);
       if (violations) {
         buffer.applyCommitResult(violations);
-        statusMessage("Required cells are empty — fix the marked rows and save again", 5000);
+        notify.warn("Required cells are empty — fix the marked rows, then save again.", {
+          key: "grid.save",
+          source: "Data",
+          tier: "problem",
+        });
         return;
       }
       if (batch.deletes.length > 0) {
@@ -316,14 +421,22 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
         const failed = changeCount - okCount;
         const staleCount =
           result.cells.filter((r) => r.stale).length + result.deletes.filter((r) => r.stale).length;
-        statusMessage(
-          failed === 0
-            ? `Saved ${okCount} change(s)`
-            : `Saved ${okCount} · ${failed} failed${staleCount ? ` (${staleCount} stale)` : ""} — kept pending`,
-          failed === 0 ? 3000 : 6000,
-        );
+        if (failed === 0) {
+          notify.success(`Saved ${okCount} change(s).`, { key: "grid.save" });
+        } else {
+          // A partial commit leaves rows pending on disk: a state to fix, not a line to read.
+          notify.error(
+            `Saved ${okCount} · ${failed} failed${staleCount ? ` (${staleCount} stale)` : ""} — kept pending.`,
+            { action: "file.save", key: "grid.save", source: "Data" },
+          );
+        }
       } catch (error) {
-        statusMessage(`Save error: ${errorMessage(error)}`, 6000);
+        notify.error("Could not save the grid.", {
+          action: "file.save",
+          detail: errorMessage(error),
+          key: "grid.save",
+          source: "Data",
+        });
       } finally {
         state.saving = false;
         progress?.done();
@@ -351,6 +464,30 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
       syncView();
     },
 
+    setGrouping(field: string | null) {
+      state.grouping = field;
+      syncView();
+    },
+
+    async setSort(sort: GridSortSpec | null) {
+      const query: GridQuery = { ...state.query };
+      if (sort) {
+        query.orderBy = sort.field;
+        query.dir = sort.dir;
+      } else {
+        delete query.orderBy;
+        delete query.dir;
+      }
+      // A local sort is a reordering of rows already in hand: reloading would re-walk a directory
+      // Or re-parse a file to receive the same rows back in the same order.
+      if (!source.capabilities.remoteSort) {
+        state.query = query;
+        syncView();
+        return;
+      }
+      await this.setQuery(query);
+    },
+
     source,
     state,
     tab,
@@ -396,7 +533,10 @@ export function createGridController(tab: Tab, source: GridSource): GridControll
         if (buffer.isDirty()) {
           const keys = hitKeys.has("*") ? state.rows.map((row) => row.key) : [...hitKeys];
           buffer.markStale(keys);
-          statusMessage("Grid rows changed on disk — marked stale (refresh to reload)", 5000);
+          notify.warn("Grid rows changed on disk — marked stale; refresh to reload.", {
+            key: "grid.stale",
+            source: "Data",
+          });
           syncView();
         } else {
           void controller.refresh();

package/src/grid/grid-layout.ts

@@ -1,19 +1,71 @@
 /**
- * Grid column-layout persistence — widths and order, per grid id, in localStorage.
+ * Grid view state — column layout, filter, sort, grouping — and the NAMED views that snapshot it.
  *
- * Pure besides the storage read/write: applyGridLayout reorders/undoes nothing destructive, it just
- * returns a new column-def array with saved widths applied and saved order first (columns unknown
- * to the saved layout keep their relative position at the end; saved fields that no longer exist
- * are ignored — schemas drift).
+ * One store, not two. Column widths and order have persisted per grid id in `localStorage` since
+ * the grid shipped; a saved view is the same record with three more facets and a name, written to
+ * the same key. The alternative — a second `jx-grid-views:` store beside this one — is how a grid
+ * ends up with a column order that a view cannot capture and a view that a resize does not update,
+ * which is the class of bug plan §12 P7.2 asks this item to avoid by construction.
+ *
+ * **The working layout is the truth; a view is a copy of it.** Every control writes the working
+ * layout (`saveGridLayout`), so a grid remembers how you left it whether or not you ever name a
+ * view. {@link saveViewAs} copies the working layout under a name; {@link applySavedView} copies it
+ * back and records which name is applied. That is why {@link activeViewModified} can answer
+ * honestly — the applied name is a bookmark, not a mode, and a resize after applying one leaves the
+ * two legitimately different rather than silently rewriting the view.
+ *
+ * **Per collection, for free.** The key is the grid id, and a grid id IS
+ * `makeGridTabId({kind:"collection", name})` for a collection, the file path for a CSV, and
+ * `grid://redirects` for the redirect table. Nothing here knows what a collection is.
+ *
+ * Pure besides the storage read/write. {@link applyGridLayout} returns a new column-def array with
+ * saved widths applied, hidden fields withheld, and saved order first (columns unknown to the saved
+ * layout keep their relative position at the end; saved fields that no longer exist are ignored —
+ * schemas drift).
  */
 
+/** One sort, as a saved view records it. The grid is single-key sorted; a second key is not saved. */
+export interface GridSortSpec {
+  field: string;
+  dir: "asc" | "desc";
+}
+
+/**
+ * The view state of one grid.
+ *
+ * Every field is optional and `undefined` means "leave this facet alone" on the way into
+ * {@link saveGridLayout}. `sort` and `groupBy` clear with an explicit `null`, because "no sort" is a
+ * choice a view must be able to record and `undefined` already means something else.
+ */
 export interface GridLayout {
   /** Column order as field names, leftmost first. */
   order?: string[];
   /** Field → width in px. */
   widths?: Record<string, number>;
+  /** Fields withheld from the table. The DATA still loads — only the column is not drawn. */
+  hidden?: string[];
+  /** Row order, applied by the controller (see `grid-controller.ts`), or null for source order. */
+  sort?: GridSortSpec | null;
+  /** Field whose value gathers rows into contiguous groups, or null for ungrouped. */
+  groupBy?: string | null;
+  /** The toolbar's text filter. */
+  filter?: string;
+}
+
+/** A named snapshot of {@link GridLayout}. The name is its identity within one grid. */
+export interface SavedGridView extends GridLayout {
+  name: string;
 }
 
+/** What one grid id holds in storage: its working layout, its named views, and which one is on. */
+interface GridLayoutRecord extends GridLayout {
+  views?: SavedGridView[];
+  active?: string | null;
+}
+
+/** The facets a view captures, in a fixed order — the comparison and the copy both walk this. */
+const FACETS = ["order", "widths", "hidden", "sort", "groupBy", "filter"] as const;
+
 const STORAGE_PREFIX = "jx-grid-layout:";
 
 function storage(): Storage | null {
@@ -24,50 +76,203 @@ function storage(): Storage | null {
   }
 }
 
-/** The saved layout for a grid id, or null. */
-export function loadGridLayout(gridId: string): GridLayout | null {
+/** The whole stored record for a grid id, or null. */
+function readRecord(gridId: string): GridLayoutRecord | null {
   const raw = storage()?.getItem(STORAGE_PREFIX + gridId);
   if (!raw) {
     return null;
   }
   try {
-    const parsed = JSON.parse(raw) as GridLayout;
+    const parsed = JSON.parse(raw) as GridLayoutRecord;
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
   }
 }
 
-/** Merge a partial layout change into the saved layout for a grid id. */
+function writeRecord(gridId: string, record: GridLayoutRecord): void {
+  storage()?.setItem(STORAGE_PREFIX + gridId, JSON.stringify(record));
+}
+
+/** Just the view-state facets of a record — what a view copies and what a comparison compares. */
+function facetsOf(source: GridLayout): GridLayout {
+  const out: GridLayout = {};
+  for (const facet of FACETS) {
+    if (source[facet] !== undefined) {
+      Object.assign(out, { [facet]: source[facet] });
+    }
+  }
+  return out;
+}
+
+/** Comparable rendering of a layout's facets — key order is fixed by {@link FACETS}. */
+function facetKey(layout: GridLayout): string {
+  return JSON.stringify(FACETS.map((facet) => layout[facet] ?? null));
+}
+
+/** The working layout for a grid id, or null when nothing is stored. */
+export function loadGridLayout(gridId: string): GridLayout | null {
+  const record = readRecord(gridId);
+  return record ? facetsOf(record) : null;
+}
+
+/**
+ * Merge a partial view-state change into the working layout for a grid id.
+ *
+ * Widths MERGE (one column resize must not forget the other nine); every other facet is replaced
+ * when present. Named views and the active name are untouched.
+ */
 export function saveGridLayout(gridId: string, change: GridLayout): void {
   const store = storage();
   if (!store) {
     return;
   }
-  const current = loadGridLayout(gridId) ?? {};
-  const next: GridLayout = {
-    ...((change.order ?? current.order) ? { order: change.order ?? current.order } : {}),
-    widths: { ...current.widths, ...change.widths },
-  };
-  store.setItem(STORAGE_PREFIX + gridId, JSON.stringify(next));
+  const record = readRecord(gridId) ?? {};
+  const next: GridLayoutRecord = { ...record, widths: { ...record.widths, ...change.widths } };
+  for (const facet of FACETS) {
+    if (facet !== "widths" && change[facet] !== undefined) {
+      Object.assign(next, { [facet]: change[facet] });
+    }
+  }
+  writeRecord(gridId, next);
 }
 
-/** Drop the saved layout for a grid id. */
+/** Drop everything stored for a grid id — working layout AND its named views. */
 export function clearGridLayout(gridId: string): void {
   storage()?.removeItem(STORAGE_PREFIX + gridId);
 }
 
-/** Apply a saved layout to column defs: saved widths win; saved order leads, unknowns follow. */
+/**
+ * Drop the working layout, keeping the named views.
+ *
+ * The "Reset" verb. Deleting the views too would make Reset a destructive action wearing the label
+ * of a harmless one — the author asked to see the grid as it comes, not to lose four saved views.
+ */
+export function resetGridLayout(gridId: string): void {
+  const record = readRecord(gridId);
+  if (!record) {
+    return;
+  }
+  writeRecord(gridId, { active: null, ...(record.views ? { views: record.views } : {}) });
+}
+
+// ─── Named views ──────────────────────────────────────────────────────────────
+
+/** The named views for a grid id, in save order. */
+export function listSavedViews(gridId: string): SavedGridView[] {
+  const views = readRecord(gridId)?.views;
+  return Array.isArray(views) ? views.filter((view) => typeof view?.name === "string") : [];
+}
+
+/** The name of the view last applied to this grid, or null when the layout is unnamed. */
+export function activeViewName(gridId: string): string | null {
+  return readRecord(gridId)?.active ?? null;
+}
+
+/**
+ * Whether the working layout has drifted from the view whose name it carries.
+ *
+ * False when no view is applied — an unnamed layout cannot be modified relative to anything. This
+ * is what lets the toolbar print "Recent posts •" instead of pretending the applied view already
+ * holds a column the author has since hidden.
+ */
+export function activeViewModified(gridId: string): boolean {
+  const record = readRecord(gridId);
+  const name = record?.active;
+  if (!record || !name) {
+    return false;
+  }
+  const view = listSavedViews(gridId).find((candidate) => candidate.name === name);
+  return view ? facetKey(facetsOf(view)) !== facetKey(facetsOf(record)) : false;
+}
+
+/**
+ * Snapshot the working layout under a name, replacing a view of the same name.
+ *
+ * Replacing rather than refusing is what makes this both "Save as…" and "Update": the author who
+ * types an existing name means the second one, and a confirmation for overwriting a view you can
+ * re-save in one click is chrome for its own sake. Returns null when the name is blank or storage
+ * is unavailable — the caller has nothing to select and must not pretend otherwise.
+ */
+export function saveViewAs(gridId: string, name: string): SavedGridView | null {
+  const trimmed = name.trim();
+  const store = storage();
+  if (trimmed === "" || !store) {
+    return null;
+  }
+  const record = readRecord(gridId) ?? {};
+  const view: SavedGridView = { name: trimmed, ...facetsOf(record) };
+  const views = listSavedViews(gridId).filter((candidate) => candidate.name !== trimmed);
+  views.push(view);
+  writeRecord(gridId, { ...record, active: trimmed, views });
+  return view;
+}
+
+/**
+ * Copy a named view onto the working layout and record it as active.
+ *
+ * Returns the applied layout so the caller can drive the surfaces (the engine remount, the sort,
+ * the grouping) from one value, or null when no view of that name exists.
+ */
+export function applySavedView(gridId: string, name: string): GridLayout | null {
+  const view = listSavedViews(gridId).find((candidate) => candidate.name === name);
+  if (!view || !storage()) {
+    return null;
+  }
+  const record = readRecord(gridId) ?? {};
+  const layout = facetsOf(view);
+  writeRecord(gridId, { active: view.name, views: record.views ?? [], ...layout });
+  return layout;
+}
+
+/**
+ * Delete a named view. Clears the active name when it was the one deleted. Returns whether it was
+ * there.
+ */
+export function deleteSavedView(gridId: string, name: string): boolean {
+  const record = readRecord(gridId);
+  if (!record || !storage()) {
+    return false;
+  }
+  const views = listSavedViews(gridId);
+  const kept = views.filter((candidate) => candidate.name !== name);
+  if (kept.length === views.length) {
+    return false;
+  }
+  writeRecord(gridId, {
+    ...record,
+    active: record.active === name ? null : (record.active ?? null),
+    views: kept,
+  });
+  return true;
+}
+
+// ─── Applying a layout to column definitions ──────────────────────────────────
+
+/**
+ * Apply a saved layout to column defs: hidden fields are withheld, saved widths win, saved order
+ * leads and unknowns follow.
+ *
+ * Hidden columns are DROPPED rather than flagged, because the engine wrapper is the only consumer
+ * and a column it never receives is one it cannot draw, size or move. The row objects still carry
+ * every field, so the toolbar's text filter — which reads the controller's columns, not these defs
+ * — keeps matching on a hidden column's value.
+ */
 export function applyGridLayout<
   T extends { field?: string | undefined; width?: number | undefined },
 >(defs: T[], layout: GridLayout | null): T[] {
   if (!layout) {
     return defs;
   }
-  const widened = defs.map((def) => {
+  const hidden = new Set(layout.hidden);
+  const widened: T[] = [];
+  for (const def of defs) {
+    if (def.field !== undefined && hidden.has(def.field)) {
+      continue;
+    }
     const width = def.field ? layout.widths?.[def.field] : undefined;
-    return width ? { ...def, width } : def;
-  });
+    widened.push(width ? { ...def, width } : def);
+  }
   if (!layout.order?.length) {
     return widened;
   }