Relax requirement for glyphs when using text-field (#1068)

* Relaxed requirement for glyphs when using text-field

Also clarified the interpretation of text-font when glyphs is set versus unset.

* Updated changelog

* Added compatibility table for omitting glyphs

* add sdk-support table to main topics

---------

Co-authored-by: Bart Louwers <[email protected]>

Author: 1ec5

CHANGELOG.md

@@ -1,7 +1,7 @@
 ## main
 
 ### ✨ Features and improvements
-- _...Add new stuff here..._
+- `glyphs` is now optional even if a symbol layer specifies `text-field`; if it is unset, `text-font` is interpreted as a fallback font list ([#1068](https://github.com/maplibre/maplibre-style-spec/pull/1068))
 
 ### 🐞 Bug fixes
 - Fix RuntimeError class, make it inherited from Error ([#983](https://github.com/maplibre/maplibre-style-spec/issues/983))

build/generate-docs.ts

@@ -534,6 +534,11 @@ function createMainTopics() {
                 content += convertPropertyToMarkdown(subKey, subValue as JsonObject);
             }
         }
+        if (value['sdk-support']) {
+            content += '\n---\n';
+            content += sdkSupportToMarkdown(value['sdk-support']);
+        }
+
         fs.writeFileSync(`${BASE_PATH}/${key}.md`, content);
     }
 }

src/reference/v8.json

@@ -183,8 +183,20 @@
     },
     "glyphs": {
       "type": "string",
-      "doc": "A URL template for loading signed-distance-field glyph sets in PBF format. \n\nThe URL must include:\n\n - `{fontstack}` - When requesting glyphs, this token is replaced with a comma separated list of fonts from a font stack specified in the text-font property of a symbol layer. \n\n - `{range}` - When requesting glyphs, this token is replaced with a range of 256 Unicode code points. For example, to load glyphs for the Unicode Basic Latin and Basic Latin-1 Supplement blocks, the range would be 0-255. The actual ranges that are loaded are determined at runtime based on what text needs to be displayed.\n\nThis property is required if any layer uses the `text-field` layout property. The URL must be absolute, containing the [scheme, authority and path components](https://en.wikipedia.org/wiki/URL#Syntax).",
-      "example": "https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf"
+      "doc": "A URL template for loading signed-distance-field glyph sets in PBF format.\n\nIf this property is set, any text in the `text-field` layout property is displayed in the font stack named by the `text-font` layout property based on glyphs located at the URL specified by this property. Otherwise, font faces will be determined by the `text-font` property based on the local environment.\n\nThe URL must include:\n\n - `{fontstack}` - When requesting glyphs, this token is replaced with a comma separated list of fonts from a font stack specified in the `text-font` property of a symbol layer. \n\n - `{range}` - When requesting glyphs, this token is replaced with a range of 256 Unicode code points. For example, to load glyphs for the Unicode Basic Latin and Basic Latin-1 Supplement blocks, the range would be 0-255. The actual ranges that are loaded are determined at runtime based on what text needs to be displayed.\n\nThe URL must be absolute, containing the [scheme, authority and path components](https://en.wikipedia.org/wiki/URL#Syntax).",
+      "example": "https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf",
+      "sdk-support": {
+        "basic functionality": {
+          "js": "0.0.16",
+          "android": "0.1.1",
+          "ios": "0.1.0"
+        },
+        "omit to use local fonts": {
+          "js": "https://github.com/maplibre/maplibre-gl-js/issues/3302",
+          "android": "https://github.com/maplibre/maplibre-native/issues/165",
+          "ios": "https://github.com/maplibre/maplibre-native/issues/165"
+        }
+      }
     },
     "transition": {
       "type": "transition",
@@ -1889,7 +1901,7 @@
         "Open Sans Regular",
         "Arial Unicode MS Regular"
       ],
-      "doc": "Font stack to use for displaying text.",
+      "doc": "Fonts to use for displaying text. If the `glyphs` root property is specified, this array is joined together and interpreted as a font stack name. Otherwise, it is interpreted as a cascading fallback list of local font names.",
       "requires": [
         "text-field"
       ],
@@ -1903,6 +1915,11 @@
           "js": "0.43.0",
           "android": "6.0.0",
           "ios": "4.0.0"
+        },
+        "local fonts": {
+          "js": "https://github.com/maplibre/maplibre-gl-js/issues/3302",
+          "android": "https://github.com/maplibre/maplibre-native/issues/165",
+          "ios": "https://github.com/maplibre/maplibre-native/issues/165"
         }
       },
       "expression": {