maplibre-preview 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a995cfb9db9269d680e9e479fa85baf0581c6e2425eb03d00a233715ce06aa
-  data.tar.gz: c9735545dca13f01336ac4f53c5193053bfdb86d628798b4713cb0c0e2b53399
+  metadata.gz: df12e7c5527319ba509cd5640dd3af10977259fcfc1272aeb53511d298670caa
+  data.tar.gz: eb0ef8cf653b812c7b29c99cbf69848b7f1ab71d34ba5718da5bf84ac0c6b9f1
 SHA512:
-  metadata.gz: c7d3f4d15e5ff4f04100de5c8c7bebb591a8600082b035a7276a7aed179d346206749c04c09e9155e6eb71ad16ca6c0c1514d858409a1c720125a7602d7e3fef
-  data.tar.gz: 5eb357401784c1174cc384c351b5af172945d985eb1141e4058381a15276720d003fb2fa52b97b82e73afb40c3a7655a9b254f6772fec8582f0fd78628d70bf7
+  metadata.gz: e7a98ded840731605fd20f1dd17fff9d0d2957f70c5f08aa24fd3cb4aa6b790f9b37445e23bb44096d85c2dfd6e77c5715c532dfb10332f1d0370273667bab9c
+  data.tar.gz: e51939f434f6535a0ba22226fd9b3721cc3b953353d0401b87aab2536c6a059cfa95f1997f2be79cfeccc2e52b020f6c9f80504e0ec1dfbf9835d29b6fabade2

data/.github/workflows/release.yml

@@ -0,0 +1,16 @@
+on: { push: { branches: [master,main] } }
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: '3.3.1' }
+      - run: |
+          mkdir -p ~/.gem && touch ~/.gem/credentials && chmod 0600 ~/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${API_KEY}\n" > ~/.gem/credentials
+          bundle install && rake push
+        env:
+          API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+          GITHUB_RUN_NUMBER: ${{ github.run_number }}

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--warnings

data/.rubocop.yml

@@ -0,0 +1,260 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  # TargetRubyVersion: 3.1.2 read from .ruby-version
+  NewCops: enable
+  Exclude:
+    - benchmarks/*.rb
+    - "*.gemspec"
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: false
+
+Layout/SpaceInLambdaLiteral:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: true
+  EnforcedStyle: no_space
+  EnforcedStyleForEmptyBraces: no_space
+
+Layout/LineLength:
+  Max: 100
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/AmbiguousBlockAssociation:
+  Enabled: true
+  # because 'expect { foo }.to change { bar }' is fine
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/BooleanSymbol:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/RaiseException:
+  Enabled: false
+
+Lint/StructNewOverride:
+  Enabled: false
+
+Lint/SuppressedException:
+  Exclude:
+    - "spec/spec_helper.rb"
+
+Lint/LiteralAsCondition:
+  Exclude:
+    - "spec/**/*.rb"
+
+Naming/PredicateName:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - "lib/*-*.rb"
+
+Naming/MethodName:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Enabled: true
+  Max: 12
+
+Style/ExponentialNotation:
+  Enabled: false
+
+Style/HashEachMethods:
+  Enabled: false
+
+Style/HashTransformKeys:
+  Enabled: false
+
+Style/HashTransformValues:
+  Enabled: false
+
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+Style/Alias:
+  Enabled: true
+  EnforcedStyle: prefer_alias_method
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Exclude:
+    - "spec/**/*.rb"
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/DateTime:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/EachWithObject:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+Style/LambdaCall:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/StabbyLambdaParentheses:
+  Enabled: false
+
+#Style/StringLiterals:
+#  Enabled: true
+#  EnforcedStyle: double_quotes
+#  ConsistentQuotesInMultiline: false
+#
+#Style/StringLiteralsInInterpolation:
+#  Enabled: true
+#  EnforcedStyle: double_quotes
+
+Style/SymbolArray:
+  Exclude:
+    - "spec/**/*.rb"
+
+Style/TrailingUnderscoreVariable:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: false
+
+Style/Next:
+  Enabled: false
+
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/EmptyLiteral:
+  Enabled: false
+
+Style/Semicolon:
+  Exclude:
+    - "spec/**/*.rb"
+
+Style/HashAsLastArrayItem:
+  Exclude:
+    - "spec/**/*.rb"
+
+Style/CaseEquality:
+  Exclude:
+    - "lib/dry/monads/**/*.rb"
+    - "lib/dry/struct/**/*.rb"
+    - "lib/dry/types/**/*.rb"
+    - "spec/**/*.rb"
+
+Style/ExplicitBlockArgument:
+  Exclude:
+    - "lib/dry/types/**/*.rb"
+
+Style/CombinableLoops:
+  Enabled: false
+
+Style/EmptyElse:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/NumberedParametersLimit:
+  Max: 2
+
+Lint/UnusedBlockArgument:
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/Debugger:
+  Exclude:
+    - "bin/console"
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Exclude:
+    - "spec/**/*.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/EmptyBlock:
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/UselessMethodDefinition:
+  Exclude:
+    - "spec/**/*.rb"
+
+Lint/SelfAssignment:
+  Enabled: false
+
+Lint/EmptyClass:
+  Enabled: false
+
+Naming/ConstantName:
+  Exclude:
+    - "spec/**/*.rb"
+
+Naming/VariableNumber:
+  Exclude:
+    - "spec/**/*.rb"
+
+Naming/BinaryOperatorParameterName:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [1.0.0] - 2025-09-29
+
+### Added
+- **Extracted MapLibre development tools** from existing tiles-proxy-cache project
+- **Sinatra extension** for easy integration into existing applications
+- **StaticMiddleware** for serving gem assets (JS files) without conflicts
+- **Helper methods** for rendering map development interface
+- **Standalone application** for testing and development purposes
+
+### Extracted Features
+- **Advanced layer filtering** with metadata support (from `filters.js`)
+- **Terrain visualization** and elevation profiles (from `contour.js`)
+- **Performance monitoring** and metrics display
+- **Interactive style debugging** tools
+- **Contour line generation** for terrain data using MapLibre Contour
+- **Hover and click modes** for feature inspection
+- **MapLibre GL JS integration** with version 5.7.3
+
+### Refactored Components
+- **Slim templates** (`map.slim`, `map_layout.slim`) adapted for gem structure
+- **JavaScript modules** (`filters.js`, `contour.js`) preserved with original functionality
+- **View rendering** with dynamic path resolution for gem integration
+- **Configuration system** with sensible defaults for MapLibre development
+
+### Technical Implementation
+- **Ruby >= 2.7.0** support with modern gem structure
+- **Sinatra 2.1+** compatibility and extension system
+- **Rack middleware** for asset serving without path conflicts
+- **Comprehensive test suite** with RSpec for all components
+- **Clean gem structure** optimized for integration use cases
+
+### Migration Notes
+This gem extracts the MapLibre development tools that were previously embedded in the tiles-proxy-cache project, making them reusable across different Sinatra applications. The original functionality has been preserved while adding proper gem structure and integration capabilities.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandr Ludov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,312 @@
+# MapLibre Preview
+
+A Ruby gem providing development tools for MapLibre GL JS styles with advanced filtering, terrain visualization, and performance monitoring capabilities. Designed for seamless integration into Sinatra applications.
+
+[![Ruby](https://img.shields.io/badge/ruby-2.7+-red.svg)](https://ruby-lang.org)
+[![Sinatra](https://img.shields.io/badge/sinatra-web_framework-lightgrey.svg)](http://sinatrarb.com/)
+[![MapLibre](https://img.shields.io/badge/maplibre-gl_js-blue.svg)](https://maplibre.org/)
+[![Русский](https://img.shields.io/badge/русский-документация-orange.svg)](docs/README_RU.md)
+
+## Key Features
+
+- **Advanced Layer Filtering**: Metadata-driven layer filtering with support for complex filter expressions
+- **Terrain Visualization**: Full terrain support with elevation profiles and contour line generation
+- **Performance Monitoring**: Real-time FPS, memory usage, and tile loading metrics
+- **Interactive Debugging**: Hover and click modes for feature inspection
+- **Sinatra Integration**: Seamless integration as Sinatra extension with helper methods
+- **Static Asset Serving**: Built-in middleware for serving JavaScript modules without conflicts
+
+## Architecture Overview
+
+The gem consists of several integrated components:
+
+### Core Components
+
+- **[Main Module](lib/maplibre-preview.rb)** - Core gem functionality including Sinatra extension, Rack middleware, helper methods, and standalone application
+- **[Slim Templates](lib/maplibre-preview/views/)** - HTML templates for map interface
+- **[JavaScript Modules](lib/maplibre-preview/public/js/)** - Client-side filtering and terrain logic
+
+### Data Flow
+
+1. **Sinatra Integration** → Register extension → Configure options → Use helpers
+2. **Asset Serving** → StaticMiddleware intercepts `/js/*` requests → Serves from gem
+3. **Map Rendering** → Helper methods render Slim templates → Include external dependencies
+4. **Client Interaction** → JavaScript modules handle filtering and terrain features
+
+## Quick Start
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'maplibre-preview'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Basic Integration
+
+```ruby
+require 'maplibre-preview'
+
+class MyApp < Sinatra::Base
+  register MapLibrePreview::Extension
+  
+  get '/map' do
+    render_maplibre_preview
+  end
+end
+```
+
+### Passing Style URL
+
+There are several ways to pass a style URL to the map:
+
+**1. Via URL parameter:**
+```
+http://localhost:9292/map?style_url=https://example.com/style.json
+```
+
+**2. Via route parameter:**
+```ruby
+get '/map' do
+  params[:style_url] = 'https://example.com/style.json'
+  render_maplibre_preview
+end
+```
+
+**3. Via source parameter:**
+```
+http://localhost:9292/map?source=Example_Style
+```
+
+### Standalone Development Server
+
+The gem includes a complete Sinatra application for testing and development:
+
+```ruby
+require 'maplibre-preview'
+
+# Run standalone development server
+MapLibrePreview::App.run!
+```
+
+This starts a complete web server with:
+- Map interface at `http://localhost:4567/map`
+- JavaScript assets served from `/js/*`
+- All gem functionality available out of the box
+
+**How to use with a style:**
+- Pass style URL as parameter: `http://localhost:4567/map?style_url=https://example.com/style.json`
+
+**Without a style:**
+- Shows only basemap tiles (OpenStreetMap)
+- Useful for testing basic functionality
+- No custom layers or styling
+
+**Use cases:**
+- Quick testing of gem functionality
+- Development and debugging
+- Demonstrating capabilities
+
+## Configuration
+
+The gem uses fixed configurations for optimal compatibility:
+
+- **Map Center**: `[35.15, 47.41]`
+- **Initial Zoom**: `2`
+- **Basemap**: OpenStreetMap tiles with 0.8 opacity
+- **Library Versions**: MapLibre GL JS 5.7.3, MapLibre Contour 0.1.0, D3.js 7
+
+**Style URL**: Pass via URL parameter `?style_url=https://example.com/style.json`
+
+## API Reference
+
+### Sinatra Extension
+
+```ruby
+# Register the extension
+register MapLibrePreview::Extension
+```
+
+### Helper Methods
+
+| Method | Description | Parameters |
+|--------|-------------|------------|
+| `render_maplibre_preview` | Render complete map development interface | None |
+| `render_map_layout` | Render map layout only | None |
+| `style_url` | Get current style URL from params | None |
+| `should_show_map?` | Check if map should be displayed | None |
+
+### Standalone Application
+
+```ruby
+# Available routes
+GET /map          # Main map development interface
+GET /js/:file     # JavaScript asset serving
+```
+
+## Style Metadata Support
+
+The gem supports advanced filtering through style metadata:
+
+```json
+{
+  "metadata": {
+    "filters": {
+      "buildings": [
+        {
+          "id": "residential",
+          "filter": ["==", ["get", "type"], "residential"]
+        },
+        {
+          "id": "commercial", 
+          "filter": ["==", ["get", "type"], "commercial"]
+        }
+      ]
+    },
+    "locale": {
+      "en": {
+        "buildings": "Buildings",
+        "residential": "Residential",
+        "commercial": "Commercial"
+      }
+    }
+  }
+}
+```
+
+## Terrain Support
+
+For terrain visualization, add terrain configuration to your style:
+
+```json
+{
+  "terrain": {
+    "source": "terrain-source"
+  },
+  "sources": {
+    "terrain-source": {
+      "type": "raster-dem",
+      "tiles": ["https://your-terrain-tiles/{z}/{x}/{y}.png"],
+      "encoding": "terrarium"
+    }
+  }
+}
+```
+
+## Performance Monitoring
+
+The gem includes real-time performance monitoring:
+
+- **FPS and Frame Time**: Real-time rendering performance
+- **Memory Usage**: JavaScript heap memory monitoring
+- **Tile Loading**: Active tile count and loading status
+- **Layer Management**: Active layer count and visibility
+- **Zoom Level**: Current map zoom level
+- **Terrain Status**: Terrain data availability
+
+## File Structure
+
+```
+lib/
+├── maplibre-preview.rb          # Main gem module and Sinatra integration
+└── maplibre-preview/
+    ├── version.rb                # Gem version
+    ├── views/                    # Slim templates
+    │   ├── map.slim             # Main map interface
+    │   └── map_layout.slim      # HTML layout
+    └── public/js/               # JavaScript modules
+        ├── filters.js           # Layer filtering logic
+        └── contour.js           # Terrain and contour features
+```
+
+## Development
+
+### Prerequisites
+
+- Ruby 2.7+
+- Sinatra 2.1+
+- Slim 4.1+
+- Rack 2.0+
+
+### Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run RuboCop
+bundle exec rubocop
+
+# Build gem
+gem build maplibre-preview.gemspec
+```
+
+### Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/maplibre_preview_spec.rb
+```
+
+## Integration Examples
+
+### Basic Map Integration
+
+```ruby
+class MyApp < Sinatra::Base
+  register MapLibrePreview::Extension
+  
+  get '/map' do
+    render_maplibre_preview
+  end
+end
+```
+
+### Style URL Integration
+
+```ruby
+class MyApp < Sinatra::Base
+  register MapLibrePreview::Extension
+  
+  get '/map' do
+    # Style URL passed via params[:style_url]
+    render_maplibre_preview
+  end
+end
+```
+
+### Multiple Map Routes
+
+```ruby
+class MyApp < Sinatra::Base
+  register MapLibrePreview::Extension
+  
+  get '/map' do
+    # Uses params[:style_url] if provided
+    render_maplibre_preview
+  end
+  
+  get '/terrain' do
+    # Set style URL via params
+    params[:style_url] = 'https://example.com/terrain-style.json'
+    render_maplibre_preview
+  end
+end
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.