Skip to content

Add a style playground to the docs - #965

Open
digitaltom wants to merge 1 commit into
mainfrom
geojson_attributes_playground
Open

digitaltom wants to merge 1 commit into
mainfrom
geojson_attributes_playground

Conversation

@digitaltom

Copy link
Copy Markdown
Collaborator

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.

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.
Copilot AI balanced review requested due to automatic review settings November 15, 2026 22:45

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
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 }
Comment thread app/models/style_spec.rb
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**",
Comment thread app/models/style_spec.rb
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants