Merge pull request #9711 from keymanapp/refactor/developer/9708-keybo…

…ard_info-example-keys-as-string refactor(developer): .keyboard_info examples should use keys as a string 🎺
keymanapp · Oct 11, 2023 · d217b46 · d217b46
2 parents 7585a11 + cc5b8da
commit d217b46
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"
       }],