@buoy-gg/shared-ui 7.0.4 → 7.0.6

package/lib/commonjs/dataViewer/jsonOps.js

@@ -0,0 +1,320 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyJsonOp = applyJsonOp;
+exports.getAtPath = getAtPath;
+exports.isEditableContainer = isEditableContainer;
+exports.isRebuildableObject = isRebuildableObject;
+exports.selectionPathAfterOp = selectionPathAfterOp;
+exports.suggestedNewValue = suggestedNewValue;
+/**
+ * Structural edits to a JSON value, addressed by path.
+ *
+ * Why an op vocabulary instead of "here's the new value": editing a container
+ * as text is fine for a three-item array and miserable for a fifty-item one.
+ * Every real JSON editor — React DevTools, TanStack Query's explorer,
+ * josdejong's JSON Editor — instead exposes per-node actions, and they all
+ * converge on the same primitives because JSON Patch (RFC 6902) already
+ * standardized them: add / remove / replace / move / copy, addressed by a
+ * pointer into the document.
+ *
+ * This is that set, named for humans and specialized for a UI:
+ *   - array-shaped ops carry the intent ("append", "insert at 3") rather than
+ *     making the caller compute the resulting array
+ *   - `renameKey` preserves key ORDER, which a naive delete-then-add loses and
+ *     which readers notice immediately
+ *
+ * Ops are pure and immutable: `applyJsonOp` returns a new root and never
+ * mutates the input, so callers can diff, undo, or discard freely.
+ *
+ * A `path` is the same `string[]` the data explorer already flattens rows with
+ * (a JSON Pointer in disguise). `[]` addresses the root. Array indices are
+ * their decimal string, matching how the explorer emits them.
+ *
+ * Scope: plain arrays and plain objects. Anything else at a path (Map, Set,
+ * class instances) is returned untouched — those can't round-trip through JSON
+ * anyway, and silently rebuilding one as a plain object would lose more than
+ * it fixed.
+ */
+
+/** A structural edit. `path` addresses the node the verb reads naturally against. */
+
+/**
+ * Objects this module is willing to REBUILD with a spread.
+ *
+ * Deliberately stricter than `isPlainObject` in `types/types`: that one is a
+ * denylist (not a Date, Map, Set, …) and so admits class instances, which is
+ * right for rendering but wrong here — `{ ...instance }` silently drops the
+ * prototype and hands back something that no longer behaves like the original.
+ * A prototype check is the only way to know a spread round-trips.
+ */
+function isRebuildableObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Where the selection should sit after `op` is applied.
+ *
+ * An op reshapes the document, so the path the user had selected may now name a
+ * DIFFERENT node — move item 3 to slot 2 and path `3` is whatever got displaced,
+ * not the thing you just moved. Following the edit is what makes the highlight
+ * mean "the node I acted on" rather than "the slot I acted from".
+ *
+ * Returns `undefined` to leave the selection alone, `null` to clear it.
+ */
+function selectionPathAfterOp(op) {
+  switch (op.kind) {
+    // Follow the node to its new slot.
+    case "move":
+      return [...op.path.slice(0, -1), String(op.toIndex)];
+    // The copy lands directly after the original, and is the thing you meant.
+    case "duplicate":
+      {
+        const last = op.path[op.path.length - 1];
+        const index = Number(last);
+        return Number.isInteger(index) ? [...op.path.slice(0, -1), String(index + 1)] : undefined;
+      }
+    // The selected node no longer exists.
+    case "remove":
+      return null;
+    default:
+      return undefined;
+  }
+}
+
+/** True when a path addresses a container this module can edit. */
+function isEditableContainer(value) {
+  return Array.isArray(value) || isRebuildableObject(value);
+}
+
+/** Read the value at `path`, or undefined if the path doesn't resolve. */
+function getAtPath(root, path) {
+  let node = root;
+  for (const segment of path) {
+    if (Array.isArray(node)) {
+      node = node[Number(segment)];
+    } else if (isRebuildableObject(node)) {
+      node = node[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return node;
+}
+
+/**
+ * Rebuild `root` with the container at `path` replaced by `updater`'s result.
+ *
+ * Everything else is expressed through this: an op on an entry is an op on its
+ * PARENT container, which is also why removal and rename are possible at all —
+ * they change the shape of the parent, not the value of the child.
+ */
+function updateContainer(root, path, updater) {
+  if (path.length === 0) return updater(root);
+  const [head, ...rest] = path;
+  if (Array.isArray(root)) {
+    const index = Number(head);
+    if (!Number.isInteger(index) || index < 0 || index >= root.length) {
+      return root;
+    }
+    const next = [...root];
+    next[index] = updateContainer(next[index], rest, updater);
+    return next;
+  }
+  if (isRebuildableObject(root)) {
+    if (!(head in root)) return root;
+    return {
+      ...root,
+      [head]: updateContainer(root[head], rest, updater)
+    };
+  }
+
+  // Path runs past something we don't edit — leave the document alone.
+  return root;
+}
+
+/** Split a path into its parent path and final segment. */
+function splitPath(path) {
+  if (path.length === 0) return null;
+  return {
+    parent: path.slice(0, -1),
+    last: path[path.length - 1]
+  };
+}
+
+/**
+ * Apply `op` to `root`, returning a new value.
+ *
+ * Never throws and never mutates: an op that doesn't apply (bad path, wrong
+ * container type, index out of range) returns `root` unchanged, so a stale
+ * click from a tree that re-rendered underneath the user is a no-op rather
+ * than a corrupted document.
+ */
+function applyJsonOp(root, op) {
+  switch (op.kind) {
+    case "replace":
+      return updateContainer(root, op.path, () => op.value);
+    case "clear":
+      return updateContainer(root, op.path, container => {
+        if (Array.isArray(container)) return [];
+        if (isRebuildableObject(container)) return {};
+        return container;
+      });
+    case "append":
+      return updateContainer(root, op.path, container => Array.isArray(container) ? [...container, op.value] : container);
+    case "insert":
+      return updateContainer(root, op.path, container => {
+        if (!Array.isArray(container)) return container;
+        const at = clamp(op.index, 0, container.length);
+        return [...container.slice(0, at), op.value, ...container.slice(at)];
+      });
+    case "addKey":
+      return updateContainer(root, op.path, container => {
+        if (!isRebuildableObject(container)) return container;
+        // Refuse to clobber: "add" that silently overwrote an existing key
+        // would lose data the user never saw.
+        if (op.key in container) return container;
+        return {
+          ...container,
+          [op.key]: op.value
+        };
+      });
+    case "remove":
+      {
+        const split = splitPath(op.path);
+        if (!split) return root; // Removing the root is meaningless.
+        return updateContainer(root, split.parent, container => removeEntry(container, split.last));
+      }
+    case "duplicate":
+      {
+        const split = splitPath(op.path);
+        if (!split) return root;
+        return updateContainer(root, split.parent, container => duplicateEntry(container, split.last));
+      }
+    case "move":
+      {
+        const split = splitPath(op.path);
+        if (!split) return root;
+        return updateContainer(root, split.parent, container => {
+          if (!Array.isArray(container)) return container;
+          const from = Number(split.last);
+          if (!Number.isInteger(from) || from < 0 || from >= container.length) {
+            return container;
+          }
+          const to = clamp(op.toIndex, 0, container.length - 1);
+          if (to === from) return container;
+          const next = [...container];
+          const [item] = next.splice(from, 1);
+          next.splice(to, 0, item);
+          return next;
+        });
+      }
+    case "renameKey":
+      {
+        const split = splitPath(op.path);
+        if (!split) return root;
+        return updateContainer(root, split.parent, container => renameEntry(container, split.last, op.key));
+      }
+    default:
+      return root;
+  }
+}
+function removeEntry(container, segment) {
+  if (Array.isArray(container)) {
+    const index = Number(segment);
+    if (!Number.isInteger(index) || index < 0 || index >= container.length) {
+      return container;
+    }
+    return container.filter((_, i) => i !== index);
+  }
+  if (isRebuildableObject(container)) {
+    if (!(segment in container)) return container;
+    const next = {};
+    for (const key of Object.keys(container)) {
+      if (key !== segment) next[key] = container[key];
+    }
+    return next;
+  }
+  return container;
+}
+function duplicateEntry(container, segment) {
+  if (Array.isArray(container)) {
+    const index = Number(segment);
+    if (!Number.isInteger(index) || index < 0 || index >= container.length) {
+      return container;
+    }
+    return [...container.slice(0, index + 1), clone(container[index]), ...container.slice(index + 1)];
+  }
+  if (isRebuildableObject(container)) {
+    if (!(segment in container)) return container;
+    // Objects have no "next to" — mint a non-colliding key and keep position.
+    const copyKey = uniqueKey(container, `${segment} copy`);
+    const next = {};
+    for (const key of Object.keys(container)) {
+      next[key] = container[key];
+      if (key === segment) next[copyKey] = clone(container[key]);
+    }
+    return next;
+  }
+  return container;
+}
+
+/**
+ * Rename in place. Rebuilt key-by-key rather than delete-then-assign so the
+ * entry keeps its position — an object whose keys reshuffle on every rename
+ * reads as though the edit did something it didn't.
+ */
+function renameEntry(container, segment, nextKey) {
+  if (!isRebuildableObject(container)) return container;
+  if (!(segment in container)) return container;
+  if (nextKey === segment) return container;
+  if (nextKey in container) return container; // Would clobber a sibling.
+
+  const next = {};
+  for (const key of Object.keys(container)) {
+    if (key === segment) next[nextKey] = container[key];else next[key] = container[key];
+  }
+  return next;
+}
+
+/** `base`, `base 2`, `base 3`… until it doesn't collide. */
+function uniqueKey(container, base) {
+  if (!(base in container)) return base;
+  let n = 2;
+  while (`${base} ${n}` in container) n++;
+  return `${base} ${n}`;
+}
+
+/** Structural copy, so a duplicated container isn't shared with its original. */
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (isRebuildableObject(value)) {
+    const next = {};
+    for (const key of Object.keys(value)) next[key] = clone(value[key]);
+    return next;
+  }
+  return value;
+}
+function clamp(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+/**
+ * A sensible starting value when adding an entry, matching the container's
+ * existing items so "append" to an array of numbers doesn't hand back a string.
+ */
+function suggestedNewValue(container) {
+  const samples = Array.isArray(container) ? container : isRebuildableObject(container) ? Object.values(container) : [];
+  const last = samples[samples.length - 1];
+  if (typeof last === "number") return 0;
+  if (typeof last === "boolean") return false;
+  if (Array.isArray(last)) return [];
+  if (isRebuildableObject(last)) return {};
+  return "";
+}