@thatopen/services 0.0.3 → 0.0.5

package/src/built-in/CDEManager/examples/FolderManagement/example.ts

@@ -0,0 +1,230 @@
+/* MD
+  ## Folder management — create, rename, archive, and commit
+  ---
+  A project reaches the construction phase and the coordination team needs to
+  restructure the folder hierarchy: add a "Facades" discipline folder, rename
+  "Structural" to its official abbreviation, and archive two superseded folders that
+  have been merged. Doing these one at a time through separate API calls means the
+  folder tree flickers between invalid states as each change lands — a freshly created
+  folder appears before its sibling is renamed, and the archived folders briefly
+  disappear before the new one is visible.
+
+  CDEManager stages all folder changes in memory first. Adds, renames, and archives
+  accumulate in a `pendingChanges` list before anything is sent to the backend. The
+  full diff is readable from the machine state at any point, so the UI can preview
+  exactly what the folder tree will look like after the commit. Cancelling throws away
+  all staged changes in one step. Saving applies everything in the right dependency
+  order and fires a single completion event with the counts.
+
+  This tutorial covers entering folder edit mode; staging new folders with a temporary
+  ID that gets resolved to a real ID on save; staging renames and observing how
+  renaming back to the original value automatically removes the change; the
+  archive-folder toggle behavior, where sending the event a second time unstages the
+  archive; removing a staged temp folder and all its staged children in one event;
+  reverting all staged changes for a single folder; and committing the full batch.
+
+  By the end, you'll have a working demonstration of every folder-management state
+  machine flow — stage, inspect, revert, and commit — against mock data with no
+  backend connection needed for the staging sections.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+
+/* MD
+  ### 🛠️ Setting up
+  The save path requires a live client context — `_saveFolderChanges` returns early if
+  no context is set and the machine would stay stuck in `savingFolderChanges` forever.
+  We keep the mock context active throughout the entire example so the commit section
+  works correctly.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+let folderIdx = 0;
+const mockClient = {
+  checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+  getProjectData: async () => ({ project: { title: "" }, users: [] }),
+  listFolders: async () => [],
+  archiveFolder: async (_id: string) => ({}),
+  updateFolder: async (_id: string, _updates: any) => ({}),
+  createFolder: async (name: string, parentId?: string) => ({
+    _id: `created-${folderIdx++}`, name, parentId: parentId ?? null,
+  }),
+};
+
+cde.ctx = { client: mockClient as any, projectId: "mock" };
+await cde.loadFolders();
+
+const folders = [
+  { _id: "folder-str", name: "Structural", parentId: null },
+  { _id: "folder-arch", name: "Architecture", parentId: null },
+  { _id: "folder-mep", name: "MEP", parentId: "folder-arch" },
+];
+cde.folders = folders as any;
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+cde.onFolderChangesCompleted.add(({ created, renamed, archived }) =>
+  log(`  [onFolderChangesCompleted] created: ${created}, renamed: ${renamed}, archived: ${archived}`)
+);
+
+/* MD
+  ### 📁 Staging folder changes
+  New folders are added with a temporary ID assigned by the caller — the UI can use it
+  to identify the row in the pending list before the real ID arrives from the backend.
+  Renames and archives for existing folders are keyed by their real ID. All three
+  change kinds accumulate in the same `pendingChanges` array, so the UI can render a
+  single diff view for the whole operation.
+
+  Cancelling discards everything and returns to idle. Unlike file bulk editing, folder
+  editing has no concept of "return to previous selection" — it always returns to idle.
+*/
+
+log("\n--- stage changes and cancel ---");
+cde.sendMachineEvent({ type: "START_EDIT_FOLDERS" });
+
+// New root-level folder.
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_facades", name: "Facades", parentId: null });
+// New folder nested inside the temp folder above.
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_facades_sub", name: "Glazing", parentId: "temp_facades" });
+
+// Rename an existing folder.
+cde.sendMachineEvent({ type: "RENAME_FOLDER", folderId: "folder-str", name: "STR" });
+
+// Archive an existing folder.
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "folder-mep" });
+
+if (cde.machineState.kind === "editingFolders") {
+  const changes = cde.machineState.pendingChanges;
+  const creates = changes.filter(c => c.kind === "create").length;
+  const renames = changes.filter(c => c.kind === "rename").length;
+  const archives = changes.filter(c => c.kind === "archive").length;
+  log(`  pending: ${creates} create(s), ${renames} rename(s), ${archives} archive(s)`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_FOLDER_CHANGES" });
+log(`  state after cancel: ${cde.machineState.kind}`);
+log(`  folders unchanged: ${cde.folders.length}`);
+
+/* MD
+  ### 🔍 Smart rename diff and archive toggle
+  Renaming an existing folder back to its current name automatically removes the
+  rename change from the pending list — the same smart diffing used for file metadata.
+  This keeps the pending list clean so the commit only sends real changes to the
+  backend.
+
+  Archiving the same existing folder twice toggles the staged archive off. This is
+  different from the file-editing archive, which needs an explicit unarchive event to
+  remove the mark. For folders, sending the archive event again is the undo gesture.
+*/
+
+log("\n--- smart rename diff ---");
+cde.sendMachineEvent({ type: "START_EDIT_FOLDERS" });
+
+cde.sendMachineEvent({ type: "RENAME_FOLDER", folderId: "folder-str", name: "STR" });
+if (cde.machineState.kind === "editingFolders") {
+  log(`  after rename "STR": ${cde.machineState.pendingChanges.filter(c => c.kind === "rename").length} rename(s)`);
+}
+
+// Renaming back to the original name removes the change automatically.
+cde.sendMachineEvent({ type: "RENAME_FOLDER", folderId: "folder-str", name: "Structural" });
+if (cde.machineState.kind === "editingFolders") {
+  log(`  after revert to "Structural": ${cde.machineState.pendingChanges.filter(c => c.kind === "rename").length} rename(s)`);
+}
+
+log("\n--- archive toggle ---");
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "folder-arch" });
+if (cde.machineState.kind === "editingFolders") {
+  log(`  after first ARCHIVE_FOLDER: ${cde.machineState.pendingChanges.filter(c => c.kind === "archive").length} archive(s)`);
+}
+
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "folder-arch" });
+if (cde.machineState.kind === "editingFolders") {
+  log(`  after second ARCHIVE_FOLDER (toggle): ${cde.machineState.pendingChanges.filter(c => c.kind === "archive").length} archive(s)`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_FOLDER_CHANGES" });
+
+/* MD
+  ### 🗑️ Removing temp folders and reverting existing ones
+  When a staged new folder is archived or reset, it is removed from the pending list
+  entirely — there is nothing to archive on the backend yet because it was never
+  created. Any folders staged as children of the removed folder are removed along with
+  it, so the pending list never contains orphaned children.
+
+  For existing folders, a reset event clears all staged changes for that folder at
+  once — both a pending rename and a pending archive in the same step — without
+  affecting any other staged changes.
+*/
+
+log("\n--- remove temp folder cascade ---");
+cde.sendMachineEvent({ type: "START_EDIT_FOLDERS" });
+
+// Stage a temp parent with two children.
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_p", name: "Parent", parentId: null });
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_c1", name: "Child A", parentId: "temp_p" });
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_c2", name: "Child B", parentId: "temp_p" });
+
+if (cde.machineState.kind === "editingFolders") {
+  log(`  staged before archive: ${cde.machineState.pendingChanges.length} change(s)`);
+}
+
+// Archiving a temp folder removes it AND all its staged children.
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "temp_p" });
+
+if (cde.machineState.kind === "editingFolders") {
+  log(`  staged after archive temp parent: ${cde.machineState.pendingChanges.length} change(s)`);
+}
+
+log("\n--- reset existing folder ---");
+cde.sendMachineEvent({ type: "RENAME_FOLDER", folderId: "folder-str", name: "STR" });
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "folder-str" });
+
+if (cde.machineState.kind === "editingFolders") {
+  const changes = cde.machineState.pendingChanges;
+  log(`  before reset: ${changes.filter(c => c.kind === "rename" || c.kind === "archive").length} change(s) for folder-str`);
+}
+
+// RESET_FOLDER removes all staged changes for folder-str in one event.
+cde.sendMachineEvent({ type: "RESET_FOLDER", folderId: "folder-str" });
+
+if (cde.machineState.kind === "editingFolders") {
+  const changes = cde.machineState.pendingChanges;
+  log(`  after reset: ${changes.filter(c => c.kind === "rename" || c.kind === "archive").length} change(s) for folder-str`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_FOLDER_CHANGES" });
+
+/* MD
+  ### 💾 Committing folder changes
+  Saving applies all staged changes to the backend in the correct order: archives
+  first, then renames on folders that were not archived, then creates in parent-before-
+  child order so that nested new folders resolve to real IDs. After everything is
+  persisted, the folder list reloads from the backend and a single completion event
+  reports how many folders were created, renamed, and archived.
+*/
+
+log("\n--- commit ---");
+cde.sendMachineEvent({ type: "START_EDIT_FOLDERS" });
+
+cde.sendMachineEvent({ type: "ADD_FOLDER", tempId: "temp_facades", name: "Facades", parentId: null });
+cde.sendMachineEvent({ type: "RENAME_FOLDER", folderId: "folder-str", name: "STR" });
+cde.sendMachineEvent({ type: "ARCHIVE_FOLDER", folderId: "folder-mep" });
+
+if (cde.machineState.kind === "editingFolders") {
+  log(`  pending before save: ${cde.machineState.pendingChanges.length} change(s)`);
+}
+
+await new Promise<void>(resolve => {
+  cde.onFolderChangesCompleted.add(() => resolve());
+  cde.sendMachineEvent({ type: "SAVE_FOLDER_CHANGES" });
+});
+
+log(`  state after commit: ${cde.machineState.kind}`);

package/src/built-in/CDEManager/examples/MetadataSchema/example.ts

@@ -0,0 +1,230 @@
+/* MD
+  ## Metadata schema — define, stage, and publish field definitions
+  ---
+  Every project has its own vocabulary for describing files: discipline codes,
+  revision phases, area zones, review statuses. A metadata schema defines which
+  fields exist, what values they accept, and whether they are mandatory. Without a
+  structured schema, each user invents their own labels and the file list becomes
+  impossible to filter or report on consistently.
+
+  CDEManager stages schema changes in memory before anything is written. New fields
+  start with a placeholder name and get their permanent key from their label at save
+  time. Edits to existing fields are tracked per-key so the UI can show a diff, and
+  changes can be reverted field by field. Deletions are staged as null markers, which
+  lets the UI still show the field as "pending removal" rather than making it disappear
+  immediately.
+
+  This tutorial covers entering schema edit mode; adding new fields and updating their
+  definitions; observing that updating a field back to its original values removes it
+  from the pending list; staging a deletion and restoring it; and committing the full
+  batch, including how new field keys are derived from their label text.
+
+  By the end, you'll understand the full schema editing lifecycle and how the machine
+  state carries a complete diff — additions, updates, and deletions — before any
+  changes reach the backend.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEMetadataField } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  Schema editing is gated by the manage permission. We use the mock context pattern
+  to load permissions, then clear the context — schema staging is entirely in-memory
+  and does not need a backend connection. Saving without a context skips persistence
+  but still applies the changes locally, which is enough to verify the machine behavior.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+cde.ctx = {
+  client: {
+    checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+    getProjectData: async () => ({ project: { title: "" }, users: [] }),
+    listFolders: async () => [],
+  } as any,
+  projectId: "mock",
+};
+await cde.loadFolders();
+cde.ctx = undefined;
+
+// Seed an initial schema to work with.
+cde.metadataSchema = {
+  discipline: { label: "Discipline", type: "string", required: true },
+  phase:      { label: "Phase",      type: "string", required: false },
+};
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+
+/* MD
+  ### ➕ Adding and updating fields
+  New fields are added with a placeholder definition and a machine-generated temporary
+  key. The actual key is derived from the field label when the schema is saved, so the
+  caller only needs to set a meaningful label — not invent a key manually.
+
+  Any update to a field is stored as a replacement of the entire field definition under
+  that key. If all properties are changed back to the original values, the edit is
+  removed from the pending list automatically — no explicit undo step is needed.
+*/
+
+log("\n--- add and update ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_SCHEMA" });
+
+// New field starts as "New Field" with a temp key like "field_1234567890".
+cde.sendMachineEvent({ type: "ADD_METADATA_FIELD" });
+
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  const tempKey = Object.keys(cde.machineState.pendingEdits).find(k => k.startsWith("field_"))!;
+  log(`  new field temp key: ${tempKey.slice(0, 10)}…`);
+
+  // Give it a real label and type.
+  cde.sendMachineEvent({
+    type: "UPDATE_METADATA_FIELD",
+    key: tempKey,
+    value: { label: "Issue Phase", type: "list", required: false, options: [{ value: "open", label: "Open" }, { value: "closed", label: "Closed" }] },
+  });
+
+  const pending = Object.keys(cde.machineState.pendingEdits);
+  log(`  pending fields after update: ${pending.length}`);
+}
+
+// Update an existing field — changes are tracked separately from new ones.
+cde.sendMachineEvent({
+  type: "UPDATE_METADATA_FIELD",
+  key: "discipline",
+  value: { label: "Discipline", type: "string", required: false },
+});
+
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  discipline pending: ${Object.keys(cde.machineState.pendingEdits).includes("discipline")}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_CONFIGURE_METADATA_SCHEMA" });
+
+/* MD
+  ### 🔍 Smart update diff
+  Updating a field back to exactly its original values removes it from the pending
+  list. This keeps the diff clean — the UI doesn't need to track which changes were
+  reverted, it just reads the pending list.
+*/
+
+log("\n--- smart diff on update ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_SCHEMA" });
+
+// Change discipline's required flag.
+cde.sendMachineEvent({
+  type: "UPDATE_METADATA_FIELD",
+  key: "discipline",
+  value: { label: "Discipline", type: "string", required: false },
+});
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  discipline in pending: ${Object.keys(cde.machineState.pendingEdits).includes("discipline")}`);
+}
+
+// Revert to the original — removes it from the pending list automatically.
+cde.sendMachineEvent({
+  type: "UPDATE_METADATA_FIELD",
+  key: "discipline",
+  value: { label: "Discipline", type: "string", required: true },
+});
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  discipline in pending after revert: ${Object.keys(cde.machineState.pendingEdits).includes("discipline")}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_CONFIGURE_METADATA_SCHEMA" });
+
+/* MD
+  ### 🗑️ Deleting and restoring fields
+  Deleting an existing field marks it as null in the pending list rather than removing
+  it outright, so the UI can still show it as "pending deletion" and let the user
+  change their mind. Restoring removes the null marker — the field is back to its
+  current state as if it was never staged for deletion.
+
+  Deleting a field that was just added (and therefore does not yet exist in the schema)
+  removes it from the pending list entirely — there is nothing to mark for deletion
+  because there is nothing to undo.
+*/
+
+log("\n--- delete and restore ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_SCHEMA" });
+
+// Stage deletion of an existing field.
+cde.sendMachineEvent({ type: "DELETE_METADATA_FIELD", key: "phase" });
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  phase value in pending: ${JSON.stringify(cde.machineState.pendingEdits["phase"])}`);
+}
+
+// Restore it — null marker removed.
+cde.sendMachineEvent({ type: "RESTORE_METADATA_FIELD", key: "phase" });
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  phase in pending after restore: ${"phase" in cde.machineState.pendingEdits}`);
+}
+
+// Add a new field, then delete it — removes it entirely (no null marker needed).
+cde.sendMachineEvent({ type: "ADD_METADATA_FIELD" });
+const newTempKey = Object.keys(
+  (cde.machineState as any).pendingEdits
+).find((k: string) => k.startsWith("field_"))!;
+cde.sendMachineEvent({ type: "DELETE_METADATA_FIELD", key: newTempKey });
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  pending after deleting new field: ${Object.keys(cde.machineState.pendingEdits).length}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_CONFIGURE_METADATA_SCHEMA" });
+
+/* MD
+  ### 💾 Committing the schema
+  When the schema is saved, new fields get their permanent key derived from their label
+  — spaces become underscores, special characters are stripped. If the derived key
+  would collide with an existing one, a numeric suffix is appended automatically.
+  After the commit, the pending list is empty and the schema reflects all the staged
+  changes.
+*/
+
+log("\n--- commit ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_SCHEMA" });
+
+// Add a new field: label "Issue Phase" → key will become "issue_phase".
+cde.sendMachineEvent({ type: "ADD_METADATA_FIELD" });
+const commitTempKey = Object.keys(
+  (cde.machineState as any).pendingEdits
+).find((k: string) => k.startsWith("field_"))!;
+cde.sendMachineEvent({
+  type: "UPDATE_METADATA_FIELD",
+  key: commitTempKey,
+  value: { label: "Issue Phase", type: "string", required: false },
+});
+
+// Update an existing field.
+cde.sendMachineEvent({
+  type: "UPDATE_METADATA_FIELD",
+  key: "discipline",
+  value: { label: "Discipline", type: "string", required: false },
+});
+
+// Stage deletion of "phase".
+cde.sendMachineEvent({ type: "DELETE_METADATA_FIELD", key: "phase" });
+
+if (cde.machineState.kind === "configuringMetadataSchema") {
+  log(`  pending before save: ${Object.keys(cde.machineState.pendingEdits).length} change(s)`);
+}
+
+// Save applies changes locally even without a backend connection.
+await new Promise<void>(resolve => {
+  cde.onMachineStateChanged.add((s) => { if (s.kind === "idle") resolve(); });
+  cde.sendMachineEvent({ type: "SAVE_METADATA_SCHEMA" });
+});
+
+log(`  state after save: ${cde.machineState.kind}`);
+log(`  schema keys: [${Object.keys(cde.metadataSchema).join(", ")}]`);
+log(`  discipline.required: ${cde.metadataSchema["discipline"]?.required}`);
+log(`  issue_phase exists: ${"issue_phase" in cde.metadataSchema}`);
+log(`  phase removed: ${"phase" in cde.metadataSchema ? "no" : "yes"}`);

package/src/built-in/CDEManager/examples/MetadataViews/example.ts

@@ -0,0 +1,166 @@
+/* MD
+  ## Metadata views — organize fields into named table layouts
+  ---
+  A structural engineer and an MEP coordinator look at the same file list but care
+  about completely different metadata. Showing every field to everyone produces a
+  wide table that is hard to navigate. Metadata views let each role define which
+  fields appear in which order — saving the layout so the table opens correctly next
+  time without requiring a manual setup every session.
+
+  CDEManager stores a list of named views, each carrying an ordered set of field keys.
+  An active view filters both which columns are visible and which metadata groupings
+  appear in the sidebar. Changes to the view list are staged in memory first, just like
+  schema changes, and saved in one batch — so the user can add, rename, and remove
+  views without any partial state reaching the backend.
+
+  This tutorial covers initializing views from a saved configuration; switching the
+  active view and reading the result; adding, updating, and removing views in the
+  pending list; and committing the full batch, which saves to the user's personal
+  config and fires an event with the final view list.
+
+  By the end, you'll know how to load, display, edit, and persist named metadata
+  layouts through the state machine.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEMetadataView } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  Loading views from a saved config and switching the active view don't require
+  permissions. We still simulate the startup step to load permissions so the save
+  path works later, then clear the context — staging is in-memory only.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+cde.ctx = {
+  client: {
+    checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+    getProjectData: async () => ({ project: { title: "" }, users: [] }),
+    listFolders: async () => [],
+  } as any,
+  projectId: "mock",
+};
+await cde.loadFolders();
+cde.ctx = undefined;
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+cde.onMetadataViewsChanged.add((views) => log(`  [onMetadataViewsChanged] ${views.length} view(s)`));
+
+/* MD
+  ### 📋 Initializing views from config
+  After loading from the backend, views and the last active view ID are pushed into
+  CDEManager through `initMetadataViews`. This populates the internal view list and
+  fires the views-changed event so any subscribed component can render immediately.
+  The active view controls which fields `getSelectedFiles` uses for grouping when
+  metadata mode is on.
+*/
+
+log("\n--- init views ---");
+const savedViews: CDEMetadataView[] = [
+  { id: "view-str", name: "Structural", fields: ["discipline", "phase"] },
+  { id: "view-mep", name: "MEP", fields: ["discipline", "zone"] },
+];
+cde.initMetadataViews(savedViews, "view-str");
+
+log(`  metadataViews: ${cde.metadataViews.length}`);
+log(`  activeMetadataViewId: ${cde.activeMetadataViewId}`);
+log(`  activeMetadataView name: ${cde.activeMetadataView?.name}`);
+
+/* MD
+  ### 🔀 Switching the active view
+  The active view can be changed from idle, a selection, or while the viewer is open.
+  Switching resets the selected metadata group so the table doesn't show a stale
+  filter from the previous view's grouping. The transition doesn't change the machine
+  state kind — it's a targeted property update, not a full state change.
+*/
+
+log("\n--- switch active view ---");
+cde.sendMachineEvent({ type: "SET_ACTIVE_METADATA_VIEW", id: "view-mep" });
+log(`  active: ${cde.activeMetadataView?.name}`);
+
+cde.sendMachineEvent({ type: "SET_ACTIVE_METADATA_VIEW", id: "view-str" });
+log(`  active: ${cde.activeMetadataView?.name}`);
+
+/* MD
+  ### ✏️ Staging view changes
+  Adding, updating, and removing views all operate on the `pendingViews` list inside
+  the machine state. The committed view list is unchanged until the save fires. Adding
+  a view generates a stable random ID immediately, so the UI can reference it for
+  subsequent updates within the same session without waiting for a server response.
+*/
+
+log("\n--- stage: add, update, delete ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_VIEWS" });
+
+// Add a new view — gets a UUID immediately.
+cde.sendMachineEvent({ type: "ADD_METADATA_VIEW" });
+
+if (cde.machineState.kind === "configuringMetadataViews") {
+  const newView = cde.machineState.pendingViews.find(v => v.name === "New View")!;
+  log(`  new view id: ${newView.id.slice(0, 8)}…`);
+
+  // Name it and set its fields.
+  cde.sendMachineEvent({
+    type: "UPDATE_METADATA_VIEW",
+    id: newView.id,
+    view: { ...newView, name: "Civil", fields: ["discipline", "zone", "level"] },
+  });
+
+  log(`  views in pending: ${cde.machineState.pendingViews.length}`);
+  log(`  updated view name: ${cde.machineState.pendingViews.find(v => v.id === newView.id)?.name}`);
+}
+
+// Remove an existing view from the pending list.
+cde.sendMachineEvent({ type: "DELETE_METADATA_VIEW", id: "view-mep" });
+if (cde.machineState.kind === "configuringMetadataViews") {
+  log(`  views after delete: ${cde.machineState.pendingViews.length}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_CONFIGURE_METADATA_VIEWS" });
+// Cancelled — committed view list is unchanged.
+log(`  committed views after cancel: ${cde.metadataViews.length}`);
+
+/* MD
+  ### 💾 Committing views
+  Saving replaces the committed view list with the pending one and fires the views-
+  changed event. The user's personal config is updated at the same time if the account
+  has create permission — the same config that `loadUserConfig` reads back on the
+  next session load. Without a real user identity in the mock, the persistence step is
+  silently skipped but the local update still applies.
+*/
+
+log("\n--- commit ---");
+cde.sendMachineEvent({ type: "START_CONFIGURE_METADATA_VIEWS" });
+
+cde.sendMachineEvent({ type: "ADD_METADATA_VIEW" });
+if (cde.machineState.kind === "configuringMetadataViews") {
+  const civil = cde.machineState.pendingViews.find(v => v.name === "New View")!;
+  cde.sendMachineEvent({
+    type: "UPDATE_METADATA_VIEW",
+    id: civil.id,
+    view: { ...civil, name: "Civil", fields: ["discipline", "zone"] },
+  });
+}
+cde.sendMachineEvent({ type: "DELETE_METADATA_VIEW", id: "view-mep" });
+
+if (cde.machineState.kind === "configuringMetadataViews") {
+  log(`  pending: ${cde.machineState.pendingViews.length} view(s)`);
+}
+
+await new Promise<void>(resolve => {
+  cde.onMachineStateChanged.add((s) => { if (s.kind === "idle") resolve(); });
+  cde.sendMachineEvent({ type: "SAVE_METADATA_VIEWS" });
+});
+
+log(`  state after save: ${cde.machineState.kind}`);
+log(`  committed views: ${cde.metadataViews.map(v => v.name).join(", ")}`);