refactor(developer): .keyboard_info examples should use keys as a string

Fixes #9708. Matches the kmp.json format of keys string in the .keyboard_info schema and compiler, in order to reduce the number of formats we are working with. This same format may be used elsewhere in Keyman schemas in the future for sets of keys, for example, I hope we can use it in regression tests.
keymanapp · Oct 8, 2023 · cc5b8da · cc5b8da
1 parent 4004449
commit cc5b8da
Show file tree

Hide file tree

Showing 6 changed files with 22 additions and 57 deletions.
diff --git a/common/schemas/keyboard_info/README.md b/common/schemas/keyboard_info/README.md
@@ -12,7 +12,7 @@ Documentation at https://help.keyman.com/developer/cloud/keyboard_info
 # .keyboard_info version history
 
 ## 2023-08-11 2.0 stable
-* Removed legacyId, documentationFilename, documentationFileSize. Source vs distribution keyboard_info distinction is removed.
+* Removed legacyId, documentationFilename, documentationFileSize. Source vs distribution keyboard_info distinction is removed. Example key sequences are simplified.
 
 ## 2019-09-06 1.0.6 stable
 * No changes (see api.keyman.com#36 and api.keyman.com#59. Reverted in 2020-06-10.).

diff --git a/common/schemas/keyboard_info/keyboard_info.schema.json b/common/schemas/keyboard_info/keyboard_info.schema.json
@@ -75,30 +75,14 @@
     "KeyboardExampleInfo": {
       "type": "object",
       "properties": {
-        "keys": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/KeyboardExampleKeyInfo" }
-        },
+        "keys": { "type": "string" },
         "text": { "type": "string" },
         "note": { "type": "string" }
       },
       "required": ["keys", "text"],
       "additionalProperties": false
     },
 
-    "KeyboardExampleKeyInfo": {
-      "type": "object",
-      "properties": {
-        "key": { "type": "string" },
-        "modifiers": {
-          "type": "array",
-          "items": { "type": "string" }
-        }
-      },
-      "required": ["key"],
-      "additionalProperties": false
-    },
-
     "KeyboardPlatformInfo": {
       "type": "object",
       "patternProperties": {

diff --git a/developer/src/kmc-keyboard-info/src/example-keys.ts b/developer/src/kmc-keyboard-info/src/example-keys.ts
diff --git a/developer/src/kmc-keyboard-info/src/index.ts b/developer/src/kmc-keyboard-info/src/index.ts
@@ -12,7 +12,6 @@ import { validateMITLicense } from "@keymanapp/developer-utils";
 import { KmpCompiler } from "@keymanapp/kmc-package";
 
 import { SchemaValidators } from "@keymanapp/common-types";
-import { packageKeysExamplesToKeyboardInfo } from "./example-keys.js";
 
 const regionNames = new Intl.DisplayNames(['en'], { type: "region" });
 const scriptNames = new Intl.DisplayNames(['en'], { type: "script" });
@@ -288,7 +287,10 @@ export class KeyboardInfoCompiler {
     if(!SchemaValidators.default.keyboard_info(keyboard_info)) {
       // This is an internal fatal error; we should not be capable of producing
       // invalid output, so it is best to throw and die
-      throw new Error((<any>SchemaValidators.default.keyboard_info).errorsText());
+      throw new Error(JSON.stringify({
+        keyboard_info: keyboard_info,
+        error: SchemaValidators.default.keyboard_info.errors
+      }, null, 2));
     }
 
     return new TextEncoder().encode(jsonOutput);
@@ -390,7 +392,7 @@ export class KeyboardInfoCompiler {
         if(example.id == bcp47) {
           language.examples.push({
             // we don't copy over example.id
-            keys: packageKeysExamplesToKeyboardInfo(example.keys),
+            keys: example.keys,
             note: example.note,
             text: example.text
           });

diff --git a/developer/src/kmc-keyboard-info/src/keyboard-info-file.ts b/developer/src/kmc-keyboard-info/src/keyboard-info-file.ts
@@ -49,12 +49,20 @@ export interface KeyboardInfoFileLanguageFont {
 }
 
 export interface KeyboardInfoFileExample {
-  keys?: KeyboardInfoFileExampleKey[];
+  /**
+   * A space-separated list of keys.
+   * - modifiers indicated with "+"
+   * - spacebar is "space"
+   * - plus key is "shift+=" or "plus" on US English (all other punctuation as per key cap).
+   * - Hardware modifiers are: "shift", "ctrl", "alt", "left-ctrl",
+   *   "right-ctrl", "left-alt", "right-alt"
+   * - Key caps should generally be their character for desktop (Latin script
+   *   case insensitive), or the actual key cap for touch
+   * - Caps Lock should be indicated with "caps-on", "caps-off"
+   *
+   * e.g. "shift+a b right-alt+c space plus z z z" represents something like: "Ab{AltGr+C} +zzz"
+   */
+  keys?: string;
   text?: string;
   note?: string;
 }
-
-export interface KeyboardInfoFileExampleKey {
-  key: string;
-  modifiers?: string[];
-}
diff --git a/developer/src/kmc-keyboard-info/test/fixtures/khmer_angkor/build/khmer_angkor.keyboard_info b/developer/src/kmc-keyboard-info/test/fixtures/khmer_angkor/build/khmer_angkor.keyboard_info
@@ -15,13 +15,7 @@
         ]
       },
       "examples": [{
-        "keys": [
-          { "key": "x" },
-          { "key": "j" },
-          { "key": "m" },
-          { "key": "E" },
-          { "key": "r" }
-        ],
+        "keys": "x j m E r",
         "text": "\u1781\u17D2\u1798\u17C2\u179A",
         "note": "Name of language"
       }],