@buoy-gg/shared-ui 7.0.4 → 7.0.5

package/lib/module/dataViewer/VirtualizedDataExplorer.js

@@ -7,9 +7,8 @@ import { gameUIColors } from "../ui/gameUI/index.js";
 import { CopyButton } from "../ui/components/CopyButton.js";
 import { ChevronRight } from "../icons/index.js";
 import { IndentGuidesOverlay } from "./IndentGuidesOverlay.js";
-
-// Stable constants to prevent re-renders [[memory:4875251]]
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Stable constants to prevent re-renders [[memory:4875251]]
 const HIT_SLOP_10 = {
   top: 10,
   bottom: 10,
@@ -22,6 +21,8 @@ const CHUNK_SIZE = 50; // Process data in chunks to avoid blocking UI
 const MAX_DEPTH_LIMIT = 15; // Prevent excessive nesting
 const MAX_ITEMS_PER_LEVEL = 500; // Limit items to prevent memory issues
 const LONG_KEY_THRESHOLD = 30; // Keys longer than this use vertical layout
+/** Two presses inside this window count as a double-tap (RN has no dblclick). */
+const DOUBLE_TAP_MS = 300;
 
 // Pre-computed indent styles (VS Code-style width)
 const INDENT_WIDTH = 16;
@@ -220,8 +221,48 @@ const STABLE_STYLES = StyleSheet.create({
   }
 });
 
+/**
+ * A tree row as the HOST sees it.
+ *
+ * `item.path` is addressed for the TREE, which is seeded with a synthetic
+ * "root" node wrapping the caller's data — so the top row is `["root"]` and its
+ * first child `["root", "0"]`. Ops address the DATA, where those are `[]` and
+ * `["0"]`. Dropping the first segment is what reconciles the two, and doing it
+ * in ONE place is what keeps selection, inline editing and ops all agreeing.
+ */
+function selectionOf(item) {
+  return {
+    path: item.path.slice(1),
+    value: item.value,
+    label: item.key
+  };
+}
+
 // Type definitions for flattened data structure
 
+/**
+ * Node count, capped at `limit`.
+ *
+ * Deliberately short-circuits: this runs on every render to decide which
+ * flattening path to take, so it must cost O(limit), never O(document).
+ */
+function countNodesUpTo(value, limit, seen = 0) {
+  if (seen >= limit) return seen;
+  let n = seen + 1;
+  if (Array.isArray(value)) {
+    for (const child of value) {
+      if (n >= limit) return n;
+      n = countNodesUpTo(child, limit, n);
+    }
+  } else if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) {
+      if (n >= limit) return n;
+      n = countNodesUpTo(child, limit, n);
+    }
+  }
+  return n;
+}
+
 // Enhanced type detection optimized for performance
 const getValueType = value => {
   if (value === null) return "null";
@@ -373,6 +414,16 @@ const useDataFlattening = (data, maxDepth = 10, autoExpandFirstLevel = false) =>
   // Store circular cache outside of re-renders to prevent reset
   const circularCacheRef = useRef(new WeakSet());
   const processingRef = useRef(false);
+  /**
+   * Monotonic token identifying the newest flatten run.
+   *
+   * WHY: a cancelled run used to `return` without clearing `isProcessing`, so
+   * whenever renders arrived faster than the 10ms debounce + flatten, every run
+   * was superseded before it finished and the spinner never came down — the
+   * viewer sat on "Processing data…" forever. Now each run checks it is still
+   * the current one, and the run that ends up last ALWAYS resolves the flag.
+   */
+  const runIdRef = useRef(0);
   const dataVersionRef = useRef(0);
   const lastActionRef = useRef(undefined);
 
@@ -502,14 +553,16 @@ const useDataFlattening = (data, maxDepth = 10, autoExpandFirstLevel = false) =>
     if (processingRef.current) {
       return;
     }
-    let isCancelled = false;
     let timeoutId;
+    const runId = ++runIdRef.current;
+    /** True while this run is still the newest one scheduled. */
+    const isCurrent = () => runIdRef.current === runId;
     processingRef.current = true;
     setIsProcessing(true);
     const processData = async () => {
       // Failsafe timeout to prevent stuck processing
       timeoutId = setTimeout(() => {
-        if (processingRef.current && !isCancelled) {
+        if (processingRef.current && isCurrent()) {
           setIsProcessing(false);
           processingRef.current = false;
         }
@@ -517,8 +570,10 @@ const useDataFlattening = (data, maxDepth = 10, autoExpandFirstLevel = false) =>
       // Small delay to debounce rapid changes
       // Small delay to batch rapid changes
       await new Promise(resolve => setTimeout(() => resolve(), 10));
-      if (isCancelled) {
-        processingRef.current = false;
+
+      // Superseded by a newer run — that run now owns `isProcessing`, so leave
+      // the flag alone and let it resolve.
+      if (!isCurrent()) {
         return;
       }
       try {
@@ -536,31 +591,26 @@ const useDataFlattening = (data, maxDepth = 10, autoExpandFirstLevel = false) =>
           });
         });
         flatDataMapRef.current = newMap;
-        if (!isCancelled) {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (isCurrent()) {
           setFlatData(newFlatData);
           setIsProcessing(false);
           processingRef.current = false;
-          if (timeoutId) clearTimeout(timeoutId);
-        } else {
-          if (timeoutId) clearTimeout(timeoutId);
         }
       } catch (error) {
         console.error(error);
         // Reset to empty data on error
-        if (!isCancelled) {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (isCurrent()) {
           setFlatData([]);
           flatDataMapRef.current = new Map();
           setIsProcessing(false);
           processingRef.current = false;
-          if (timeoutId) clearTimeout(timeoutId);
-        } else {
-          if (timeoutId) clearTimeout(timeoutId);
         }
       }
     };
     processData();
     return () => {
-      isCancelled = true;
       processingRef.current = false;
       if (timeoutId) clearTimeout(timeoutId);
     };
@@ -712,10 +762,50 @@ const useDataFlattening = (data, maxDepth = 10, autoExpandFirstLevel = false) =>
       return newSet;
     });
   }, [updateFlatDataIncremental]);
+
+  /**
+   * Small documents flatten SYNCHRONOUSLY, during render.
+   *
+   * The chunked effect above exists so a 500-node payload can't block a frame,
+   * and it pays for that with an async, multi-commit rebuild every time `data`
+   * changes identity. Editing is immutable, so that's every single op — which
+   * made a three-item array rebuild itself in stages on every tap, visibly, for
+   * machinery it never needed. Below the chunk threshold the entire flatten is
+   * cheaper than one of those commits, so derive it inline and let React
+   * reconcile the rows normally. The chunked path is untouched above that size.
+   */
+  const isSmallDocument = countNodesUpTo(data, CHUNK_SIZE, 0) < CHUNK_SIZE;
+  const syncFlatData = useMemo(() => {
+    if (!isSmallDocument) return null;
+    return flattenDataStable(data, expandedItems, new WeakSet(), "root", 0, undefined, [], 0, 1, []);
+  }, [isSmallDocument, data, expandedItems, flattenDataStable]);
+
+  /**
+   * Expand a set of ancestor ids so a node deeper in the tree becomes visible.
+   *
+   * Needed because a host can relocate the selection to a node the user never
+   * expanded their way to — append into a collapsed array and the new entry is
+   * selected but off-tree, which reads as "nothing happened". Unlike
+   * `toggleExpanded` this doesn't patch `flatData` incrementally; the full
+   * flatten effect already re-runs on `expandedItems`, and a reveal is rare
+   * enough that the extra pass isn't worth a second incremental code path.
+   */
+  const revealPath = useCallback(ancestorIds => {
+    if (ancestorIds.length === 0) return;
+    setExpandedItems(prev => {
+      if (ancestorIds.every(id => prev.has(id))) return prev;
+      const next = new Set(prev);
+      for (const id of ancestorIds) next.add(id);
+      return next;
+    });
+  }, []);
   return {
-    flatData,
-    isProcessing,
-    toggleExpanded
+    flatData: syncFlatData ?? flatData,
+    // A synchronous list is never "processing" — the spinner would flash on
+    // every keystroke otherwise.
+    isProcessing: syncFlatData ? false : isProcessing,
+    toggleExpanded,
+    revealPath
   };
 };
 
@@ -725,10 +815,28 @@ const VirtualizedItemComponent = ({
   onToggleExpanded,
   index,
   onSelect,
-  isSelected
+  isSelected,
+  selectable,
+  onRequestInlineEdit,
+  isInlineEditing,
+  inlineEditor
 }) => {
   const [isPressed, setIsPressed] = useState(false);
   const [showFullKey, setShowFullKey] = useState(false);
+  const canEdit = selectable === true;
+  const lastPressRef = useRef(0);
+
+  /**
+   * `item.path` is addressed for the TREE, which is seeded with a synthetic
+   * "root" node wrapping the caller's data — so the top row is `["root"]` and
+   * its first child `["root", "0"]`. Ops address the DATA, where those are `[]`
+   * and `["0"]`. Dropping the first segment is what reconciles the two.
+   *
+   * Worth stating plainly because getting it wrong fails silently: `applyJsonOp`
+   * treats an unresolvable path as a no-op, so every button would simply have
+   * done nothing rather than erroring.
+   */
+  const dataPath = item.path.slice(1);
 
   // Use pre-computed styles to avoid inline calculations [[memory:4875251]]
   const indentStyle = INDENT_STYLES[Math.min(item.depth, MAX_DEPTH_LIMIT)] || INDENT_STYLES[0];
@@ -738,11 +846,40 @@ const VirtualizedItemComponent = ({
   const isLongKey = false;
 
   // Use inline handler since component is already memoized [[memory:4875251]]
+
+  /**
+   * Row body. In editable mode this SELECTS only — pressing a container to see
+   * its actions would otherwise collapse the very subtree you're editing, and
+   * the expander already exists to do the toggling (the same split every tree
+   * view makes). Read-only mode keeps the original toggle-on-row-press.
+   */
   const handlePress = () => {
+    if (canEdit) {
+      // Double-tap opens the inline editor, matching the mockup's
+      // double-click. Detected by hand because RN has no dblclick: two presses
+      // inside DOUBLE_TAP_MS on an already-selected scalar row.
+      const now = Date.now();
+      const isDouble = now - lastPressRef.current < DOUBLE_TAP_MS;
+      lastPressRef.current = now;
+      if (isDouble && !item.isExpandable && onRequestInlineEdit) {
+        onRequestInlineEdit(item);
+        return;
+      }
+      onSelect(item);
+      return;
+    }
+    if (item.isExpandable) {
+      onToggleExpanded(item.id);
+    }
+    onSelect(item);
+  };
+
+  /** The chevron always toggles, in both modes. */
+  const handleExpanderPress = () => {
     if (item.isExpandable) {
       onToggleExpanded(item.id);
     }
-    onSelect(index);
+    onSelect(item);
   };
   const handleKeyPress = () => {};
 
@@ -759,11 +896,16 @@ const VirtualizedItemComponent = ({
       onPress: handlePress,
       onPressIn: () => setIsPressed(true),
       onPressOut: () => setIsPressed(false),
-      activeOpacity: item.isExpandable ? 0.7 : 1,
-      disabled: !item.isExpandable,
+      activeOpacity: item.isExpandable || canEdit ? 0.7 : 1
+      // A leaf row has nothing to expand, so it was left unpressable. In
+      // editable mode the press IS the selection that reveals this row's
+      // actions, so scalars — the ones you most want to edit — have to be
+      // pressable too.
+      ,
+      disabled: !item.isExpandable && !canEdit,
       children: [item.isExpandable ? /*#__PURE__*/_jsx(Expander, {
         expanded: item.isExpanded,
-        onPress: handlePress
+        onPress: handleExpanderPress
       }) : /*#__PURE__*/_jsx(View, {
         style: STABLE_STYLES.expanderContainer
       }), /*#__PURE__*/_jsxs(View, {
@@ -772,7 +914,7 @@ const VirtualizedItemComponent = ({
           style: STABLE_STYLES.labelText,
           numberOfLines: 1,
           children: [item.key, ":"]
-        }), item.isExpandable ? /*#__PURE__*/_jsxs(Text, {
+        }), isInlineEditing && inlineEditor ? inlineEditor : item.isExpandable ? /*#__PURE__*/_jsxs(Text, {
           style: [STABLE_STYLES.valueText, {
             color: gameUIColors.secondary
           }],
@@ -809,13 +951,19 @@ export const VirtualizedDataExplorer = ({
   rawMode = false,
   initialExpanded = false,
   // disableCopy is accepted for API compatibility but CopyButton handles Pro gating internally
-  disableCopy: _disableCopy = false
+  disableCopy: _disableCopy = false,
+  onSelectionChange,
+  onRequestInlineEdit,
+  inlineEditPath,
+  renderInlineEditor,
+  selectPath
 }) => {
   const [isExpanded, setIsExpanded] = useState(rawMode); // Auto-expand in raw mode
   const {
     flatData,
     isProcessing,
-    toggleExpanded
+    toggleExpanded,
+    revealPath
   } = useDataFlattening(data, maxDepth, initialExpanded);
 
   // Track visible range for overlay rendering
@@ -864,8 +1012,54 @@ export const VirtualizedDataExplorer = ({
   };
 
   // Stable renderItem using module-scope function [[memory:4875251]]
-  const [selectedIndex, setSelectedIndex] = useState(null);
-  const activeDepth = selectedIndex != null ? flatData[selectedIndex]?.depth : undefined;
+  /**
+   * Selection is tracked by the row's stable id (its path), NOT its index.
+   *
+   * An edit reshapes the list — removing item 1 slides everything up — so an
+   * index-based selection would silently start pointing at a different node
+   * and the action bar would operate on the wrong one. An id survives that, and
+   * resolves to nothing when the node it named is gone.
+   */
+  const [selectedId, setSelectedId] = useState(null);
+  const selectedItem = useMemo(() => selectedId == null ? undefined : flatData.find(it => it.id === selectedId), [flatData, selectedId]);
+  const activeDepth = selectedItem?.depth;
+
+  // Report the selection outward, re-emitting after each data change so the
+  // action bar is looking at the CURRENT value of the node it has selected.
+  useEffect(() => {
+    if (!onSelectionChange) return;
+    onSelectionChange(selectedItem ? selectionOf(selectedItem) : null);
+  }, [selectedItem, onSelectionChange]);
+
+  /** Tapping the selected row again clears it, so the bar can be dismissed. */
+  const handleSelect = useCallback(item => {
+    setSelectedId(prev => prev === item.id ? null : item.id);
+  }, []);
+
+  // Re-sync when the host relocates the selection. Keyed on the joined path so
+  // an unchanged array identity (a fresh render) doesn't clobber a user's tap.
+  const selectPathKey = selectPath === undefined ? undefined : selectPath === null ? "\u0000null" : selectPath.join(".");
+  const lastSelectPathKey = useRef(selectPathKey);
+  useEffect(() => {
+    if (selectPathKey === lastSelectPathKey.current) return;
+    lastSelectPathKey.current = selectPathKey;
+    if (selectPathKey === undefined) return;
+    if (selectPath == null) {
+      setSelectedId(null);
+      return;
+    }
+    // Reveal it first — a selection the user can't see reads as a no-op.
+    const ancestors = ["root"];
+    for (const segment of selectPath.slice(0, -1)) {
+      ancestors.push(`${ancestors[ancestors.length - 1]}.${segment}`);
+    }
+    revealPath(ancestors);
+    setSelectedId(["root", ...selectPath].join("."));
+  }, [selectPathKey, selectPath, revealPath]);
+  const handleRequestInlineEdit = useCallback(item => {
+    setSelectedId(item.id);
+    onRequestInlineEdit?.(selectionOf(item));
+  }, [onRequestInlineEdit]);
   const renderItem = ({
     item,
     index
@@ -873,8 +1067,12 @@ export const VirtualizedDataExplorer = ({
     item: item,
     index: index,
     onToggleExpanded: toggleExpanded,
-    onSelect: setSelectedIndex,
-    isSelected: selectedIndex === index
+    onSelect: handleSelect,
+    isSelected: selectedItem?.id === item.id,
+    selectable: onSelectionChange != null,
+    onRequestInlineEdit: handleRequestInlineEdit,
+    isInlineEditing: inlineEditPath != null && inlineEditPath.join(".") === item.path.slice(1).join("."),
+    inlineEditor: renderInlineEditor ? renderInlineEditor(selectionOf(item)) : null
   });
 
   // Uniform row height for crisp guide geometry

package/lib/module/dataViewer/index.js

@@ -9,9 +9,24 @@ export { IndentGuides } from "./IndentGuides.js";
 export { IndentGuidesOverlay } from "./IndentGuidesOverlay.js";
 export { default as TreeDiffViewer } from "./tree/TreeDiffViewer.js";
 
+// Structural edits by path — the vocabulary behind the explorer's per-node
+// actions (append / insert / remove / move / rename / …), modeled on JSON Patch.
+export { applyJsonOp, getAtPath, isEditableContainer, suggestedNewValue, selectionPathAfterOp } from "./jsonOps.js";
+
+// What the selected node can do, as data. One source so the dashboard's bar
+// and the phone's dock can't drift about what's legal.
+export { treeActionsFor, treeActionMap, breadcrumb, typeLabel } from "./treeActions.js";
+
+// Edit actions for the explorer's selected node. Rendered by the HOST, beside
+// its own actions — a 24px tree row can't hold a touch-sized button.
+export { DataTreeActionBar, DataTreeInlineEditor } from "./DataTreeActionBar.js";
+
+// The same six actions as a thumb-sized grid, for the phone's full-screen editor.
+export { DataTreeActionDock } from "./DataTreeActionDock.js";
+
 // Diff viewer components
 export { SplitDiffViewer } from "./SplitDiffViewer.js";
 export { DiffSummary } from "./DiffSummary.js";
 // Diff utilities and themes
-export { computeLineDiff, DiffType } from "./lineDiff.js";
+export { computeLineDiff, DiffType, ABSENT_VALUE, isAbsent } from "./lineDiff.js";
 export { diffThemes, gitClassicTheme, devToolsDefaultTheme } from "./diffThemes.js";