mapshaper 0.7.0 → 0.7.2

package/www/llms.txt

@@ -0,0 +1,55 @@
+# Mapshaper
+
+> Mapshaper is a command-line tool and in-browser editor for geographic vector data. It reads and writes Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML/KMZ, CSV/TSV, DBF, JSON records and SVG, and can simplify, clip, dissolve, join, project and otherwise transform layers. The CLI and web app share the same command language, so commands written interactively in the browser console run unchanged in scripts.
+
+These docs cover the same material in two forms:
+
+- **Markdown mirrors** of every page (this file links to them) for use by language models and other tools.
+- **HTML pages** at the same paths without the trailing `.md`, with navigation, search and syntax highlighting, intended for humans.
+
+When in doubt about a command's behavior, the [command reference](https://mapshaper.org/docs/reference.html.md) is the source of truth. The Node.js source code lives at <https://github.com/mbloch/mapshaper>.
+
+## Getting started
+
+- [The command-line tool](https://mapshaper.org/docs/essentials/command-line.html.md): Install the mapshaper CLI, run your first commands and learn how Mapshaper organizes data into layers.
+- [The web app](https://mapshaper.org/docs/essentials/web-app.html.md): A tour of Mapshaper's web interface, including loading data, the console, the right-click menu, snapshots, browser support and running it locally.
+
+## Guides
+
+- [Simplification](https://mapshaper.org/docs/guides/simplification.html.md): How to choose between Visvalingam and Douglas-Peucker, and tips for getting good-looking results from polygon and polyline simplification.
+- [JavaScript expressions](https://mapshaper.org/docs/guides/expressions.html.md): Reference for the JS expressions used in -each, -filter, -calc, -where, -sort, -if, -run and other Mapshaper commands.
+- [Projections](https://mapshaper.org/docs/guides/projections.html.md): How to reproject geographic data with Mapshaper, including CRS notation, built-in aliases, and the albersusa composite projection.
+- [Topology and cleaning](https://mapshaper.org/docs/guides/topology.html.md): How Mapshaper detects shared boundaries between features, and how to fix the common topology errors that creep into Shapefile and GeoJSON datasets.
+- [Combining two layers](https://mapshaper.org/docs/guides/combining-layers.html.md): A step-by-step walkthrough of combining and pruning two boundary layers to produce a custom GeoJSON basemap.
+- [Using Mapshaper from Node.js](https://mapshaper.org/docs/guides/programmatic.html.md): Integrating Mapshaper into JavaScript builds and applications via its Node.js API.
+
+## Formats
+
+- [Shapefile](https://mapshaper.org/docs/formats/shapefile.html.md): How Mapshaper reads and writes ESRI Shapefiles, including encoding and field-name notes.
+- [GeoJSON](https://mapshaper.org/docs/formats/geojson.html.md): How Mapshaper reads and writes GeoJSON, including precision, ndjson and RFC 7946 options.
+- [TopoJSON](https://mapshaper.org/docs/formats/topojson.html.md): How Mapshaper reads and writes TopoJSON, including quantization and multi-layer output.
+- [GeoPackage](https://mapshaper.org/docs/formats/geopackage.html.md): How Mapshaper reads and writes GeoPackage (.gpkg), the OGC's SQLite-based GIS container.
+- [FlatGeobuf](https://mapshaper.org/docs/formats/flatgeobuf.html.md): How Mapshaper reads and writes FlatGeobuf (.fgb), a streamable binary vector format.
+- [KML / KMZ](https://mapshaper.org/docs/formats/kml.html.md): How Mapshaper reads and writes KML and KMZ files for use with Google Earth and similar tools.
+- [CSV / TSV](https://mapshaper.org/docs/formats/csv.html.md): How Mapshaper reads and writes CSV/TSV, including encoding, type hints and large-file handling.
+- [DBF](https://mapshaper.org/docs/formats/dbf.html.md): How Mapshaper reads and writes standalone DBF files, the tabular component of Shapefile.
+- [JSON records](https://mapshaper.org/docs/formats/json.html.md): How Mapshaper reads and writes plain JSON arrays of objects (no geometry), useful for tabular data exchange.
+- [SVG](https://mapshaper.org/docs/formats/svg.html.md): How Mapshaper exports vector data as SVG, including width, scale, bounding-box and per-feature data attributes.
+- [Mapshaper snapshot](https://mapshaper.org/docs/formats/snapshot.html.md): A single-file binary snapshot of a Mapshaper session, used to save work in progress and share reproducible projects.
+
+## Examples
+
+- [Basics](https://mapshaper.org/docs/examples/basics.html.md): A scannable collection of short Mapshaper recipes for common GIS tasks — format conversion, joins, simplification, dissolves, projection, classification, web export and more.
+- [Globe](https://mapshaper.org/docs/examples/globe.html.md): A simple locator map in the shape of a globe.
+- [U.S. state map](https://mapshaper.org/docs/examples/us-states.html.md): Simple U.S. state map with random, non-adjacent colors
+
+## Command reference
+
+- [Command reference](https://mapshaper.org/docs/reference.html.md): Exhaustive reference for every mapshaper command and its options, with short examples.
+
+## Optional
+
+- [Home](https://mapshaper.org/docs/index.html.md): Documentation for mapshaper, the command-line tool and web app for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data.
+- [What's new](https://mapshaper.org/docs/whats-new.html.md): A curated log of recently added user-visible features in Mapshaper, with links into the rest of the docs.
+- [Gallery](https://mapshaper.org/docs/gallery/index.html.md): Example maps made with Mapshaper, with full source data and reproduction steps for each.
+- [Formats overview](https://mapshaper.org/docs/formats/overview.html.md): A quick comparison of every file format Mapshaper can read and write, with links to per-format details.

package/www/mapshaper-gui.js

@@ -4000,7 +4000,8 @@
     var historyId = 0;
     var _isOpen = false;
     var btn = gui.container.findChild('.console-btn').on('click', toggle);
-    var globals = {}; // share user-defined globals between runs
+    var globals = {}; // share user-defined globals (job.defs) between runs
+    var sharedVars = {}; // share -vars / -defaults templating scope between runs
 
     // expose this function, so other components can run commands (e.g. box tool)
     this.runMapshaperCommands = runMapshaperCommands;
@@ -4404,6 +4405,7 @@
           job = new internal.Job(model);
 
       job.defs = globals; // share globals between runs
+      job.vars = sharedVars; // share templating scope between runs
       internal.runParsedCommands(commands, job, function(err) {
         var flags = getCommandFlags(commands),
             active2 = model.getActiveLayer(),
@@ -5653,6 +5655,56 @@
     }
   }
 
+  // Hamburger menu in the top-right of the header. After the user starts
+  // editing, the splash bar (Docs / GitHub / Survey / Sponsor) is hidden by
+  // gui.mjs; this menu is the post-edit replacement, exposing the same links
+  // from a single button so the editing controls don't have to share the row.
+
+
+  function HeaderMenu() {
+    var btn = El('#header-menu-btn');
+    var dropdown = El('#header-menu-dropdown');
+    if (!btn.node() || !dropdown.node()) return; // markup missing; nothing to do
+
+    var open = false;
+
+    function setOpen(state) {
+      if (state === open) return;
+      open = state;
+      dropdown.classed('hidden', !open);
+      btn.attr('aria-expanded', open ? 'true' : 'false');
+    }
+
+    btn.on('click', function(e) {
+      e.stopPropagation();
+      setOpen(!open);
+    });
+
+    // Keyboard activation matches button semantics for the role="button" span.
+    btn.on('keydown', function(e) {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        setOpen(!open);
+      }
+    });
+
+    // Outside click closes the menu. Clicks on menu items also close it (they
+    // navigate or open in a new tab; either way the menu shouldn't linger).
+    document.addEventListener('click', function(e) {
+      if (!open) return;
+      var target = e.target;
+      if (btn.node().contains(target)) return;
+      setOpen(false);
+    });
+
+    document.addEventListener('keydown', function(e) {
+      if (open && e.key === 'Escape') {
+        setOpen(false);
+        btn.node().focus();
+      }
+    });
+  }
+
   function SessionHistory(gui) {
     var commands = [];
     // index of first command after the last "save" boundary; commands at indices
@@ -5991,6 +6043,15 @@
 
     this.clear = function() {
       reset();
+      fireHistoryChange();
+    };
+
+    this.canUndo = function() {
+      return history.length - offset > 0;
+    };
+
+    this.canRedo = function() {
+      return offset > 0;
     };
 
     function addHistoryState(undo, redo) {
@@ -5999,6 +6060,14 @@
         offset = 0;
       }
       history.push({undo, redo});
+      fireHistoryChange();
+    }
+
+    function fireHistoryChange() {
+      gui.dispatchEvent('history_change', {
+        canUndo: history.length - offset > 0,
+        canRedo: offset > 0
+      });
     }
 
     this.undo = function() {
@@ -6011,6 +6080,7 @@
         item.undo();
         gui.dispatchEvent('undo_redo_post', {type: 'undo'});
         gui.dispatchEvent('map-needs-refresh');
+        fireHistoryChange();
       }
     };
 
@@ -6022,6 +6092,7 @@
       item.redo();
       gui.dispatchEvent('undo_redo_post', {type: 'redo'});
       gui.dispatchEvent('map-needs-refresh');
+      fireHistoryChange();
     };
 
     function getHistoryItem() {
@@ -6335,6 +6406,10 @@
       return ['info', 'selection', 'data', 'box', 'labels', 'edit_points', 'rectangles'].includes(mode);
     };
 
+    this.modeSupportsUndo = function(mode) {
+      return ['data', 'labels', 'edit_points', 'edit_lines', 'edit_polygons', 'vertices', 'rectangles'].includes(mode);
+    };
+
     this.getMode = getInteractionMode;
 
     this.setMode = function(mode) {
@@ -6477,6 +6552,214 @@
     }
   }
 
+  // A reusable floating toolbar anchored at the bottom-center of the map area.
+  //
+  // Multiple toolbars stack vertically inside a shared container, so additional
+  // per-mode toolbars (e.g. feature styling) can coexist with the edit toolbar.
+  //
+  // The DOM is structured to leave room for a future drag handle without
+  // requiring rework: the toolbar element is a flex row with a content slot,
+  // and a sibling drag-handle slot can be added later.
+  //
+  // Constructor options:
+  //   name:       optional CSS class added to the toolbar element
+  //   transition: ms for the show/hide transition (default 150)
+  //
+  // API:
+  //   toolbar.addButton(iconRef, opts) -> ToolbarButton
+  //   toolbar.addSeparator()
+  //   toolbar.show()
+  //   toolbar.hide()
+  //   toolbar.visible()
+  //   toolbar.node()
+
+  function FloatingToolbar(gui, opts) {
+    opts = opts || {};
+    var transitionMs = opts.transition || 150;
+    var root = gui.container.findChild('.mshp-main-map');
+    var stack = root.findChild('.floating-toolbar-stack');
+    if (!stack) {
+      stack = El('div').addClass('floating-toolbar-stack').appendTo(root);
+    }
+    var el = El('div').addClass('floating-toolbar');
+    if (opts.name) el.addClass(opts.name);
+    var content = El('div').addClass('floating-toolbar-content').appendTo(el);
+    var visible = false;
+    var hideTimer = null;
+
+    el.appendTo(stack);
+    el.css('display', 'none');
+
+    // Hide when this gui instance becomes inactive (e.g. multi-instance mode)
+    gui.on('active', updateVisibility);
+    gui.on('inactive', updateVisibility);
+
+    this.addButton = function(iconRef, btnOpts) {
+      return new ToolbarButton(content, iconRef, btnOpts || {});
+    };
+
+    this.addSeparator = function() {
+      return El('div').addClass('floating-toolbar-separator').appendTo(content);
+    };
+
+    this.show = function() {
+      if (visible) return;
+      visible = true;
+      updateVisibility();
+    };
+
+    this.hide = function() {
+      if (!visible) return;
+      visible = false;
+      updateVisibility();
+    };
+
+    this.visible = function() {
+      return visible;
+    };
+
+    this.node = function() {
+      return el.node();
+    };
+
+    function updateVisibility() {
+      var shouldShow = visible && GUI.isActiveInstance(gui);
+      if (shouldShow) {
+        clearTimeout(hideTimer);
+        hideTimer = null;
+        el.css('display', 'flex');
+        // wait one frame so the browser registers the initial state before
+        // the transition kicks in
+        requestAnimationFrame(function() {
+          el.addClass('visible');
+        });
+      } else {
+        el.removeClass('visible');
+        // wait for the transition to finish before hiding completely
+        clearTimeout(hideTimer);
+        hideTimer = setTimeout(function() {
+          if (!(visible && GUI.isActiveInstance(gui))) {
+            el.css('display', 'none');
+          }
+        }, transitionMs);
+      }
+    }
+  }
+
+  function ToolbarButton(parent, iconRef, opts) {
+    var btn = El('div').addClass('floating-toolbar-btn').appendTo(parent);
+    if (iconRef) {
+      var iconNode = El('body').findChild(iconRef);
+      if (iconNode) {
+        var icon = iconNode.node().cloneNode(true);
+        if (icon.hasAttribute('id')) icon.removeAttribute('id');
+        btn.node().appendChild(icon);
+      }
+    }
+    var enabled = true;
+    var clickHandlers = [];
+
+    if (opts.tooltip) setTooltip(opts.tooltip);
+
+    // Block native dblclick to avoid the map's double-click zoom
+    btn.on('dblclick', function(e) { e.stopPropagation(); });
+
+    btn.on('click', function(e) {
+      if (!enabled) return;
+      for (var i = 0; i < clickHandlers.length; i++) {
+        clickHandlers[i](e);
+      }
+    });
+
+    this.on = function(event, fn) {
+      if (event == 'click') {
+        clickHandlers.push(fn);
+      } else {
+        btn.on(event, fn);
+      }
+      return this;
+    };
+
+    this.enable = function() { return this.setEnabled(true); };
+    this.disable = function() { return this.setEnabled(false); };
+
+    this.setEnabled = function(b) {
+      enabled = !!b;
+      btn.classed('disabled', !enabled);
+      return this;
+    };
+
+    this.setTooltip = setTooltip;
+
+    this.node = function() {
+      return btn.node();
+    };
+
+    function setTooltip(text) {
+      btn.attr('data-tooltip', text);
+    }
+  }
+
+  // Floating toolbar that exposes undo/redo while the user is in an editing
+  // interaction mode. The toolbar is the first consumer of FloatingToolbar;
+  // future per-mode toolbars (e.g. feature styling) can follow the same pattern.
+
+  function EditToolbar(gui) {
+    var toolbar = new FloatingToolbar(gui, { name: 'edit-toolbar' });
+    var isMac = navigator.userAgent.includes('Mac');
+    var modKey = isMac ? '\u2318' : 'Ctrl+';
+    var shiftKey = isMac ? '\u21e7' : 'Shift+';
+
+    var undoBtn = toolbar.addButton('#undo-icon', {
+      tooltip: 'Undo (' + modKey + 'Z)'
+    }).on('click', function() {
+      gui.undo.undo();
+    });
+
+    var redoBtn = toolbar.addButton('#redo-icon', {
+      tooltip: 'Redo (' + shiftKey + modKey + 'Z)'
+    }).on('click', function() {
+      gui.undo.redo();
+    });
+
+    updateButtons();
+
+    gui.on('interaction_mode_change', function() {
+      updateVisibility();
+      // history is cleared on mode change; refresh button states next tick
+      updateButtons();
+    });
+
+    gui.on('history_change', function(e) {
+      undoBtn.setEnabled(!!e.canUndo);
+      redoBtn.setEnabled(!!e.canRedo);
+      // Visibility may also depend on history (e.g. attribute edits via popup
+      // happen in modes that don't otherwise support undo).
+      updateVisibility();
+    });
+
+    updateVisibility();
+
+    function updateVisibility() {
+      if (!gui.interaction) {
+        toolbar.hide();
+        return;
+      }
+      var mode = gui.interaction.getMode();
+      var hasHistory = gui.undo.canUndo() || gui.undo.canRedo();
+      if (gui.interaction.modeSupportsUndo(mode) || hasHistory) {
+        toolbar.show();
+      } else {
+        toolbar.hide();
+      }
+    }
+
+    function updateButtons() {
+      undoBtn.setEnabled(gui.undo.canUndo());
+      redoBtn.setEnabled(gui.undo.canRedo());
+    }
+  }
+
   function Model(gui) {
     var self = new internal.Catalog();
     var deleteLayer = self.deleteLayer;
@@ -6609,6 +6892,10 @@
     LOGGING = true;
   }
 
+  function disableLogging() {
+    LOGGING = false;
+  }
+
   function loggingEnabled() {
     return !!LOGGING;
   }
@@ -9570,6 +9857,10 @@
 
     box.setDataCoords = function(bbox) {
       boxCoords = bbox;
+      // Box is being placed programmatically (e.g. around a pinned rectangle);
+      // enable pointer events on the handles so they can be dragged. Without
+      // this, mousedowns fall through to the map and trigger pan.
+      el.classed('hittable', true);
       redraw();
     };
 
@@ -9593,6 +9884,7 @@
     // remove the current box (if any)
     box.hide = function() {
       el.hide();
+      el.classed('hittable', false);
       boxCoords = null;
       _visible = false;
       clickStartPoint = null;
@@ -10943,8 +11235,8 @@
     function showInstructions() {
       var isMac = navigator.userAgent.includes('Mac');
       var symbol = isMac ? '⌘' : '^';
-      var msg = `Instructions: Click on the map to add points. Move points by dragging. Type ${symbol}Z/${symbol}Y to undo/redo.`;
-      alert = showPopupAlert(msg, null, { non_blocking: true, max_width: '360px'});
+      var msg = `Instructions: click on the map to add points. Move points by dragging.`;
+      alert = showPopupAlert(msg, null, { non_blocking: true, max_width: '290px'});
     }
 
     gui.on('interaction_mode_change', function(e) {
@@ -11161,9 +11453,9 @@
     function showInstructions() {
       var isMac = navigator.userAgent.includes('Mac');
       var undoKey = isMac ? '⌘' : '^';
-      var msg = `Instructions: click to start a path, click or drag to keep drawing. Drag vertices to reshape a path. Type ${undoKey}Z/${undoKey}Y to undo/redo.`;
+      var msg = `Instructions: click to start a path, click or drag to keep drawing. Drag vertices to reshape a path.`;
         alert = showPopupAlert(msg, null, {
-          non_blocking: true, max_width: '388px'});
+          non_blocking: true, max_width: '350px'});
     }
 
     function hideInstructions() {
@@ -14625,6 +14917,7 @@ GUI and setting the size and crop of SVG output.</p><div><input type="text" clas
       new SessionSnapshots(gui);
     }
     gui.interaction = new InteractionMode(gui);
+    gui.editToolbar = new EditToolbar(gui);
 
     gui.showProgressMessage = function(msg) {
       if (!gui.progressMessage) {
@@ -14749,6 +15042,7 @@ GUI and setting the size and crop of SVG output.</p><div><input type="text" clas
     new ImportControl(gui, importOpts);
     new ExportControl(gui);
     new LayerControl(gui);
+    HeaderMenu();
     gui.console = new Console(gui);
 
     startEditing = function() {};