esri-gl 0.9.0 → 0.10.0

package/README.md

@@ -2,10 +2,19 @@
 
 A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS and Mapbox GL JS. It replicates Esri Leaflet's architecture patterns while being compatible with modern WebGL mapping libraries.
 
+> **🚧 Development Notice**
+> 
+> This project is currently under active development. APIs may change between releases and some features may not be fully stable. Please use with caution in production environments and check the [changelog](CHANGES.md) for breaking changes between versions.
+
 [![npm version](https://badge.fury.io/js/esri-gl.svg)](https://badge.fury.io/js/esri-gl)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## 🔗 Links
+
+- **📚 [Documentation](https://esri-gl.netlify.app/)** - Complete API reference and guides
+- **🎮 [Live Demos](https://esri-gl-demo.netlify.app/)** - Interactive examples and code samples
+
 **Note**: This library is compatible with both **MapLibre GL JS** and **Mapbox GL JS**.
 
 ## Features
@@ -28,7 +37,13 @@ A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS
 - **Layer Definitions** - Filter data server-side using SQL-like expressions
 - **Time-aware Services** - Support for temporal data visualization
 - **Attribution Management** - Automatic service attribution handling
+- **React Integration** - Hooks and components for React applications
+- **React Map GL Support** - Direct integration with react-map-gl
 - **TypeScript Support** - Full type safety with comprehensive interfaces
+- **ArcGIS Online (AGOL) Support** - Proper JSON error handling, token auth, and API key support
+- **Feature Editing** - Add, update, delete features and apply batch edits
+- **Attachments** - Query, add, and delete feature attachments
+- **Query Pagination** - Automatic pagination through large result sets
 
 ## Installation
 
@@ -37,30 +52,7 @@ A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS
 npm install esri-gl
 ```
 
-### Alpha/Beta Releases
-```bash
-# Latest alpha release (current: v0.1.0-alpha.2)
-npm install esri-gl@alpha
 
-# Specific alpha version
-npm install esri-gl@0.1.0-alpha.2
-
-# Latest beta release  
-npm install esri-gl@beta
-```
-
-### GitHub Packages (Alternative Registry)
-```bash
-# Configure npm to use GitHub Packages for @muimsd scope
-npm config set @muimsd:registry https://npm.pkg.github.com/
-
-# Install from GitHub Packages
-npm install @muimsd/esri-gl
-
-# Or use the setup script
-./scripts/github-packages.sh configure
-./scripts/github-packages.sh install
-```
 
 ## Quick Start
 
@@ -174,16 +166,60 @@ const service = new TiledMapService('source-id', map, {
 ```
 
 ### FeatureService
-Vector data with intelligent vector tile detection and automatic GeoJSON fallback.
+Efficient tile-based feature loading from ArcGIS FeatureServers with PBF (Protocol Buffer) support for minimal payload size.
 
 ```typescript
 const service = new FeatureService('source-id', map, {
   url: 'https://example.com/arcgis/rest/services/MyService/FeatureServer/0',
-  useVectorTiles: true, // Smart detection with fallback
-  useBoundingBox: true, // Viewport-based loading
   where: '1=1',
   outFields: '*',
-  maxRecordCount: 2000
+  // PBF options (requires ArcGIS Server 10.7+)
+  minZoom: 2, // Minimum zoom level for data requests
+  simplifyFactor: 0.3, // Geometry simplification (0-1)
+  precision: 8, // Coordinate decimal precision
+  useServiceBounds: true, // Limit requests to service extent
+  setAttributionFromService: true // Auto-set attribution
+});
+
+// Update filters dynamically
+service.setWhere("STATUS = 'Active'");
+service.setDate(new Date(), new Date('2024-01-01'));
+service.setToken('your-token');
+
+// Query features by location
+const features = await service.getFeaturesByLonLat({ lng: -118, lat: 34 }, 100);
+
+// Query by object IDs
+const specific = await service.getFeaturesByObjectIds([1, 2, 3], true);
+```
+
+#### Feature Editing (AGOL)
+
+```typescript
+// Edit features on an AGOL Feature Service
+const service = new FeatureService('editable-source', map, {
+  url: 'https://services.arcgis.com/.../FeatureServer/0',
+  token: 'your-agol-token'
+});
+
+// Add features
+const addResults = await service.addFeatures([
+  { type: 'Feature', geometry: { type: 'Point', coordinates: [-95, 37] }, properties: { name: 'New Point' } }
+]);
+
+// Update features
+const updateResults = await service.updateFeatures([
+  { type: 'Feature', geometry: { type: 'Point', coordinates: [-95, 37] }, properties: { OBJECTID: 1, name: 'Updated' } }
+]);
+
+// Delete features
+const deleteResults = await service.deleteFeatures({ objectIds: [1, 2, 3] });
+
+// Batch edits
+const batchResults = await service.applyEdits({
+  adds: [newFeature],
+  updates: [updatedFeature],
+  deletes: [4, 5]
 });
 ```
 
@@ -227,6 +263,15 @@ const service = new VectorBasemapStyle('source-id', map, {
 });
 ```
 
+```typescript
+// Custom portal item style
+const customBasemap = new VectorBasemapStyle('source-id', map, {
+  style: 'arcgis/streets',
+  itemId: 'your-portal-item-id',
+  token: 'your-token'
+});
+```
+
 ## Task-Based Operations
 
 Modeled after Esri Leaflet's chainable task pattern for querying and identifying features.
@@ -282,6 +327,252 @@ const results = await query({
 .run();
 ```
 
+```typescript
+// Automatic pagination through all results
+import { query } from 'esri-gl';
+
+const allResults = await query({
+  url: 'https://example.com/arcgis/rest/services/MyService/FeatureServer/0'
+})
+.where("STATE_NAME = 'California'")
+.runAll(); // Automatically paginates through all pages
+```
+
+## React Integration
+
+esri-gl provides first-class React.js support with comprehensive hooks, components, and seamless integration with **react-map-gl**. Whether you're building with vanilla React + MapLibre/Mapbox or using the react-map-gl wrapper, esri-gl has you covered.
+
+### Installation for React Projects
+
+```bash
+# Core library
+npm install esri-gl
+
+# For React hooks and components
+npm install react react-dom @types/react @types/react-dom
+
+# For react-map-gl integration (recommended)
+npm install react-map-gl mapbox-gl
+# OR for MapLibre
+npm install react-map-gl maplibre-gl
+```
+
+### React Hooks Pattern
+
+Perfect for custom React components with full control over map lifecycle:
+
+```typescript
+import React, { useState, useRef, useEffect } from 'react';
+import { Map } from 'maplibre-gl';
+import { useDynamicMapService, useIdentifyFeatures, useFeatureService } from 'esri-gl/react';
+
+function CustomMapComponent() {
+  const mapRef = useRef<HTMLDivElement>(null);
+  const [map, setMap] = useState<Map | null>(null);
+  
+  // Initialize MapLibre map
+  useEffect(() => {
+    if (!mapRef.current) return;
+    const mapInstance = new Map({
+      container: mapRef.current,
+      style: 'https://demotiles.maplibre.org/style.json',
+      center: [-95, 37],
+      zoom: 4
+    });
+    setMap(mapInstance);
+    return () => mapInstance.remove();
+  }, []);
+
+  // Use esri-gl React hooks
+  const { service: dynamicService, loading, error } = useDynamicMapService({
+    sourceId: 'usa-service',
+    map,
+    options: {
+      url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer',
+      layers: [0, 1, 2],
+      transparent: true
+    }
+  });
+
+  const { service: featureService } = useFeatureService({
+    sourceId: 'states-service',
+    map,
+    options: {
+      url: 'https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Census_States/FeatureServer/0',
+      useVectorTiles: true,
+      useBoundingBox: true
+    }
+  });
+
+  const { identify } = useIdentifyFeatures({
+    url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer',
+    tolerance: 3
+  });
+
+  // Handle map clicks for identify
+  useEffect(() => {
+    if (!map) return;
+    const handleClick = async (e: any) => {
+      const results = await identify({ lng: e.lngLat.lng, lat: e.lngLat.lat }, map);
+      console.log('Identify results:', results);
+    };
+    map.on('click', handleClick);
+    return () => map.off('click', handleClick);
+  }, [map, identify]);
+
+  return (
+    <div>
+      <div ref={mapRef} style={{ width: '100%', height: '500px' }} />
+      {loading && <div>Loading Esri services...</div>}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+### React Map GL Components (Recommended)
+
+For the smoothest React experience with declarative layer management:
+
+```typescript
+import React, { useState } from 'react';
+import { Map } from 'react-map-gl/mapbox';
+import { 
+  EsriDynamicLayer, 
+  EsriFeatureLayer, 
+  EsriVectorTileLayer,
+  EsriImageLayer 
+} from 'esri-gl/react-map-gl';
+
+function MapWithEsriLayers() {
+  const [viewState, setViewState] = useState({
+    longitude: -95,
+    latitude: 37,
+    zoom: 4
+  });
+
+  const [selectedStates, setSelectedStates] = useState<string[]>([]);
+
+  return (
+    <Map
+      {...viewState}
+      onMove={evt => setViewState(evt.viewState)}
+      mapStyle="mapbox://styles/mapbox/streets-v11"
+      style={{ width: '100%', height: '600px' }}
+    >
+      {/* Dynamic Map Service Layer */}
+      <EsriDynamicLayer
+        id="usa-demographics"
+        url="https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer"
+        layers={[0, 1, 2]}
+        layerDefs={{
+          0: "POP2000 > 100000",
+          1: "STATE_NAME IN ('California', 'Texas', 'New York')"
+        }}
+        opacity={0.8}
+        beforeId="waterway-label"
+      />
+
+      {/* Feature Service with Vector Tiles */}
+      <EsriFeatureLayer
+        id="us-states"
+        url="https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Census_States/FeatureServer/0"
+        useVectorTiles={true}
+        useBoundingBox={true}
+        where={selectedStates.length > 0 ? `STATE_NAME IN ('${selectedStates.join("','")}')` : undefined}
+        paint={{
+          'fill-color': [
+            'case',
+            ['in', ['get', 'STATE_NAME'], ['literal', selectedStates]],
+            '#ff6b6b',
+            '#627BC1'
+          ],
+          'fill-opacity': 0.6,
+          'fill-outline-color': '#ffffff'
+        }}
+        onClick={(feature) => {
+          const stateName = feature.properties?.STATE_NAME;
+          if (stateName) {
+            setSelectedStates(prev => 
+              prev.includes(stateName) 
+                ? prev.filter(s => s !== stateName)
+                : [...prev, stateName]
+            );
+          }
+        }}
+      />
+
+      {/* Vector Tile Service */}
+      <EsriVectorTileLayer
+        id="world-imagery-labels"
+        url="https://services.arcgisonline.com/arcgis/rest/services/World_Imagery/VectorTileServer"
+        beforeId="usa-demographics"
+      />
+
+      {/* Image Service for Analytical Data */}
+      <EsriImageLayer
+        id="elevation-hillshade"
+        url="https://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/ImageServer"
+        renderingRule={{
+          rasterFunction: "Hillshade",
+          rasterFunctionArguments: {
+            Azimuth: 315,
+            Altitude: 45
+          }
+        }}
+        opacity={0.5}
+      />
+    </Map>
+  );
+}
+```
+
+### Why Choose React Integration?
+
+#### React Hooks Benefits
+- **🎛️ Full Control** - Direct access to map instance and service lifecycle
+- **🔄 State Management** - Seamless integration with React state and effects
+- **🎯 Custom Logic** - Perfect for complex interactions and custom components
+- **📦 Lightweight** - Use only what you need
+
+#### React Map GL Benefits  
+- **📋 Declarative** - Define layers as JSX components
+- **🔄 Automatic Updates** - Props changes automatically update layers
+- **🎨 Built-in Styling** - Direct paint and layout prop support
+- **👆 Event Handling** - onClick, onHover events built-in
+- **🏗️ Component Ecosystem** - Works with all react-map-gl features
+
+### TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type { 
+  DynamicMapServiceOptions,
+  FeatureServiceOptions,
+  IdentifyResult,
+  EsriLayerProps 
+} from 'esri-gl';
+import type { MapRef } from 'react-map-gl/mapbox';
+
+// Fully typed component props
+interface MapComponentProps {
+  serviceUrl: string;
+  initialLayers?: number[];
+  onFeatureClick?: (feature: IdentifyResult) => void;
+}
+
+const TypedMapComponent: React.FC<MapComponentProps> = ({ 
+  serviceUrl, 
+  initialLayers = [0], 
+  onFeatureClick 
+}) => {
+  // Component implementation with full type safety
+};
+```
+
+See [REACT.md](REACT.md) for complete React integration documentation and advanced patterns.
+
 ## Advanced Features
 
 ### Dynamic Layer Management
@@ -332,14 +623,33 @@ const service = new FeatureService('optimized-source', map, {
 });
 ```
 
+### Authentication
+
+```typescript
+// Token-based authentication (URL parameter)
+const service = new DynamicMapService('secure-source', map, {
+  url: 'https://example.com/arcgis/rest/services/SecureService/MapServer',
+  token: 'your-auth-token'
+});
+
+// Update token dynamically
+service.setToken('new-token');
+
+// API Key authentication (X-Esri-Authorization header)
+const featureService = new FeatureService('api-key-source', map, {
+  url: 'https://services.arcgis.com/.../FeatureServer/0',
+  apiKey: 'your-api-key' // Sent as X-Esri-Authorization: Bearer header
+});
+```
+
 ## Development
 
 ### Build System
-- **Library Build**: Rollup with `@rollup/plugin-typescript` (UMD + ESM outputs)
-- **Type Declarations**: Consolidated in `dist/types/` directory
-- **Demo Development**: Vite dev server  
+- **Library Build**: Rollup with TypeScript, Babel, and Terser (UMD + ESM outputs)
+- **Type Declarations**: Generated with rollup-plugin-dts in `dist/` directory
+- **Demo Development**: Vite dev server with React and TypeScript
 - **Documentation**: Docusaurus build system
-- **Test Coverage**: 92.94% with 651 focused test cases
+- **Test Coverage**: 717 comprehensive test cases across 31 test suites
 
 ### Development Commands
 
@@ -391,9 +701,13 @@ src/
 └── types.ts           # TypeScript interfaces
 
 dist/
-├── types/             # Consolidated TypeScript declarations
-├── esri-gl.js         # UMD build
-├── esri-gl.esm.js     # ESM build  
+├── index.d.ts         # Main TypeScript declarations
+├── react.d.ts         # React integration declarations
+├── react-map-gl.d.ts  # React Map GL declarations
+├── index.js           # ESM build
+├── index.umd.js       # UMD build
+├── esri-gl.esm.js     # ESM build (legacy)
+├── esri-gl.js         # UMD build (legacy)
 └── esri-gl.min.js     # Minified UMD build
 ```
 
@@ -422,10 +736,12 @@ const options: FeatureServiceOptions = {
 };
 ```
 
-All type declarations are available in the `dist/types/` directory after building.
+All type declarations are available in the `dist/` directory after building.
 
 ## Contributing
 
+We welcome contributions! Please follow these steps:
+
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature/my-feature`
 3. Make changes and add tests
@@ -434,6 +750,17 @@ All type declarations are available in the `dist/types/` directory after buildin
 6. Push to branch: `git push origin feature/my-feature`
 7. Submit a pull request
 
+### Pre-commit Hooks
+
+This project uses [Husky](https://typicode.github.io/husky/) to automatically run quality checks before each commit:
+
+- **Formatting & Linting**: Automatically formats and lints staged files using Prettier and ESLint
+- **Testing**: Runs the full test suite to ensure no regressions
+
+The hooks are automatically installed when you run `npm install`. If you need to skip them (not recommended), you can use `git commit --no-verify`.
+
+For more details, see [.husky/README.md](.husky/README.md).
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
@@ -444,3 +771,16 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - **MapLibre GL JS** & **Mapbox GL JS** - Incredible WebGL mapping libraries
 - **Esri ArcGIS Platform** - Comprehensive GIS services and APIs
 - **[mapbox-gl-esri-sources](https://github.com/frontiersi/mapbox-gl-esri-sources/)** - Reference implementation for Esri service integration patterns
+- **[mapbox-gl-arcgis-featureserver](https://github.com/rowanwins/mapbox-gl-arcgis-featureserver)** by **Rowan Winsemius** - The FeatureService implementation with PBF support is based on this excellent library. It provides efficient tile-based feature loading with Protocol Buffer Format (PBF) support for minimal payload size.
+
+## Fork Notice
+
+This project originated as a fork of **[frontiersi/mapbox-gl-esri-sources](https://github.com/frontiersi/mapbox-gl-esri-sources/)**. It has been substantially refactored and expanded:
+
+- Migrated to a service + task architecture similar to Esri Leaflet
+- Added unified TypeScript typing and consolidated build outputs (ESM + UMD)
+- Introduced additional services (Dynamic, Image, Vector Basemap Styles, Identify / Query tasks, smart FeatureService vector tile detection, etc.)
+- Implemented a React/Vite demo suite and extended test coverage
+
+All original credit for the foundational concept and early integration patterns goes to the maintainers of the upstream repository. If you need the simpler original implementation, or want to compare behavior, please visit the upstream project.
+