Repository navigation
Add a style playground to the docs - #965
Open
digitaltom wants to merge 1 commit into
Open
digitaltom wants to merge 1 commit into
digitaltom wants to merge 1 commit into
Conversation
The style spec doc page now shows each GeoJSON style attribute with a live map preview. StyleSpec parses the attributes from the bullets of geojson_style_spec.md. The preview map loads in an iframe from /docs/style_preview and gets features by postMessage. Tutorial.render can render inline Markdown, and the spec now names the property description.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The marker-size test incorrectly expects 6 instead of the documented default of 5, and unresolved preview-loading, geometry-validation, and style-example defects affect functionality.
6 open issues
Correct the default marker-size expectation · New Validate geometry coordinates before updating the preview · New Complete example properties and tilt extrusion previews · New Preserve preview GeoJSON across basemap reloads · New Use the parsed description key · New List only supported marker-size values · New
What changed in this PR
Adds an interactive styling playground to the documentation, using the existing map renderer to preview GeoJSON edits and Markdown-derived property information.
Changes:
- Adds a GeoJSON editor, presets, property cards, filtering, and share links.
- Introduces an unsaved iframe preview map updated through
postMessage. - Adds parser, request, and browser coverage, plus playground styles and translation entries.
| File | Description |
|---|---|
spec/requests/docs_controller_spec.rb |
Covers playground, Markdown, and preview responses. |
spec/models/style_spec_spec.rb |
Tests parsed properties, defaults, values, and examples. |
spec/features/docs_style_playground_spec.rb |
Covers preview updates, presets, icons, and filtering. |
locale/de/app.po |
Adds German translation entries for playground text. |
locale/app.pot |
Updates translation messages and source references. |
docs/tutorials/geojson_style_spec.md |
Formats enumerated values as code spans. |
config/routes.rb |
Adds the style-preview endpoint. |
app/views/docs/styling.haml |
Builds the editor, preview, and property-card interface. |
app/views/docs/style_pictures/_zoom_range.haml |
Illustrates zoom limits. |
app/views/docs/style_pictures/_stroke_dasharray.haml |
Illustrates solid and dashed strokes. |
app/views/docs/style_pictures/_show_desc.haml |
Illustrates description-banner shapes. |
app/views/docs/style_pictures/_marker_shape.haml |
Illustrates marker shapes. |
app/views/docs/style_pictures/_label_color.haml |
Illustrates label colors. |
app/views/docs/style_pictures/_label_background.haml |
Illustrates badge and shadow backgrounds. |
app/views/docs/style_pictures/_label_anchor.haml |
Illustrates label-anchor positions. |
app/views/docs/style_pictures/_fill_pattern.haml |
Adds SVG fill-pattern samples. |
app/views/docs/style_pictures/_fill_extrusion_height.haml |
Illustrates extrusion height. |
app/models/tutorial.rb |
Extracts reusable Markdown rendering with inline support. |
app/models/style_spec.rb |
Parses property metadata and supplies example values. |
app/javascript/maplibre/layers/layers.js |
Recognizes embedded preview-layer data. |
app/javascript/controllers/style_playground_controller.js |
Handles editing, presets, property controls, sharing, and filtering. |
app/javascript/controllers/map_controller.js |
Receives preview features and signals map readiness. |
app/controllers/docs_controller.rb |
Serves the playground and unsaved preview map. |
app/assets/stylesheets/docs.css |
Styles the responsive playground and property illustrations. |
Review effort: Balanced
| expect(properties["label-anchor"][:geometries]["All"][:default]).to eq("top") | ||
| expect(properties["label-color"][:geometries]["All"][:default]).to eq("#000000") | ||
| expect(properties["label-size"][:geometries]["All"][:default]).to eq("16") | ||
| expect(properties["marker-size"][:geometries]["Point"][:default]).to eq("6") |
| edit (fit = false) { | ||
| try { | ||
| const feature = JSON.parse(this.editorTarget.value) | ||
| if (feature?.type !== 'Feature' || !feature.geometry?.type) { throw new Error(window.__('Not a GeoJSON feature')) } |
| if (!property.geometries.All && !property.geometries[this.geometryType()]) { | ||
| this.loadPreset({ params: { preset: GEOMETRY_PRESETS[Object.keys(property.geometries)[0]] } }) | ||
| } | ||
| this.setProperty(name, property.example) |
| layers = data.layers.map(l => createLayerInstance(l)) | ||
| layers.forEach(l => { | ||
| // Only the style preview map carries its features in the definition, it has no layer url | ||
| if (l.layer.geojson) { l.localData = true } |
| VALUE = /\A[a-z#][\w#.-]*\z/i | ||
| # Values for the properties that have no default and no value list in the markdown | ||
| EXAMPLES = { "label" => "Stadtpark", "label-title" => "Park", "label-font" => [ "SUSE" ], "label-offset" => [ 0, 1 ], | ||
| "min-zoom" => 10, "max-zoom" => 17, "level" => "0", "title" => "Stadtpark", "desc" => "Open **9 to 17**", |
| name, text = match.captures | ||
| entry = entries[name] ||= { name: name, group: group(name), geometries: {}, values: [] } | ||
| entry[:geometries][geometry] = { html: Tutorial.render(text, inline: true), default: default(text) } | ||
| entry[:values] |= text.scan(/`([^`]+)`/).flatten.grep(VALUE) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


The style spec doc page now shows each GeoJSON style attribute with a live map preview.
StyleSpec parses the attributes from the bullets of geojson_style_spec.md.
The preview map loads in an iframe from /docs/style_preview and gets features by postMessage.
Tutorial.render can render inline Markdown, and the spec now names the property description.