README.md

kle-serial

This is a MIT-licensed javascript library for parsing the serialized format used on keyboard-layout-editor.com (KLE) and converting it into something that is easier to understand and use in third-party applications.

KLE is frequently used to prototype and generate a rough keyboard layout, that is then used by other applications to create plates, circuit boards, etc. These third-party applications currently use their own parsing logic.

Unfortunately, the KLE format was designed to be compact (due to some original limitations), and the format has evolved considerably from its original versions. As a result, third-party parsing implementations aren't always 100% compatible with KLE itself, particularly with respect to certain corner-cases or older / deprecated properties.

This library is the same code that KLE itself uses to parse serialized layouts, so by using it, you can be sure that you are 100% compatible with the editor.

Installation

Install the package via NPM:

npm install @ijprest/kle-serial --save

Usage

var kle = require("@ijprest/kle-serial");

var keyboard = kle.Serial.deserialize([
  { name: "Sample", author: "Your Name" },
  ["Q", "W", "E", "R", "T", "Y"]
]);

// or

var keyboard = kle.Serial.parse(`[
  { name: "Sample", author: "Your Name" },
  ["Q", "W", "E", "R", "T", "Y"]
]`);

API

kle.Serial.deserialize(rows: Array<any>): Keyboard

• Given an array of keyboard rows, deserializes the result into a Keyboard object.
• The first entry is optionally a keyboard metadata object.

kle.Serial.parse(json5: string): Keyboard

• This function takes a JSON5-formatted string, parses it, then deserializes the result into a Keyboard object.
• JSON5 is a simplified / lenient version of JSON that is easier for humans to type; in particular, it doesn't require quotes around property names. Any valid JSON string should also be a valid JSON5 string.

Keyboard Objects

class Keyboard {
  meta: KeyboardMetadata;
  keys: Key[];
}

A Keyboard is an object containg keyboard metadata (meta) and an array of keys.

Keyboard Metadata

The meta object contains several fields:

class KeyboardMetadata {
  author: string;
  backcolor: string;
  background: { name: string; style: string } | null;
  name: string;
  notes: string;
  radii: string;
  switchBrand: string;
  switchMount: string;
  switchType: string;
}

• author — the name of the author
• backcolor — the background color of the keyboard editor area (default #eeeeee)
• background (optional) — a background image that overrides backcolor if specified.
  • The name identifies it from the list of backgrounds in the editor; other consumers can ignore this property.
  • The style is some custom CSS that will override the background color; it will have the form: background-image: url(...)
• name — the name of the keyboard layout
  • Appears in the editor, below the keyboard.
  • Identifies the keyboard among your saved layouts.
  • Used to generate a filename when downloading or rendering the keyboard.
• notes — notes about the keyboard layout, in GitHub-flavored Markdown.
• radii — the radii of the keyboard corners, in CSS border-radius format, e.g., 20px.
• switchBrand, switchMount, switchType — the default switch mount, brand, and type of switches on your keyboard.
  • Default can be overridden on individual keys.
  • See known values here: https://github.com/ijprest/keyboard-layout-editor/blob/master/switches.json

Keys

Each key in the keys array contains the following data:

export class Key {
  color: string;
  labels: string[];
  textColor: Array<string | undefined>;
  textSize: Array<number | undefined>;
  default: { textColor: string; textSize: number };

  x: number;
  y: number;
  width: number;
  height: number;

  x2: number;
  y2: number;
  width2: number;
  height2: number;

  rotation_x: number;
  rotation_y: number;
  rotation_angle: number;

  decal: boolean;
  ghost: boolean;
  stepped: boolean;
  nub: boolean;

  profile: string;

  sm: string; // switch mount
  sb: string; // switch brand
  st: string; // switch type
}

• color — the keycap color, e.g., "#ff0000" for red.
• labels — an array of up to 12 text labels (sometimes referred to as 'legends'):
  • In reading order, i.e., left-to-right, top-to-bottom:
    • 
  • The labels are user input, and may contain arbitrary HTML content; when rendering, input sanitization is recommended for security purposes.
• textColor — an array of up to 12 colors (e.g., "#ff0000"), to be used for the text labels; if any entries are null or undefined, you should use the default.textColor.
• textSize — an array of up to 12 sizes (integers 1-9), to be used for the text labels; if any entries are null or undefined, you should use the default.textSize.
  • Note that the sizes are relative and do not correspond to any fixed font size.
  • KLE uses the following formula when rendering on-screen:
    • (6px + 2px * textSize)
• default.textColor / default.textSize — the default text color / size.
• x / y — the absolute position of the key in keyboard units (where 1u is the size of a standard 1x1 keycap).
• width / height — the size of the key, in keyboard units.
• x2 / y2 / width2 / height2 — the size & position of the second rectangle that is used to define oddly-shaped keys (like an ISO Enter or Big-ass Enter key or stepped keys).
  • If the size is (0,0), then there is no second rectangle required.
  • The position is relative to (x, y).
  • The two rectangles can be thought of as overlapping, combining to create the desired key shape.
    • Note that labels are always positioned relative to the main rectangle.
    • If a key is stepped, the second rectangle is the lower part.
    • 
    • In this example, the second rectangle is shown on top of the original rectangle, and (x2,y2) [width x height] = (-0.75, 1.0) [2.25 x 1.0].
• rotation_x / rotation_y — defines the center of rotation for the key.
• rotation_angle — specifies the angle the key is rotated (about the center of rotation).
• decal — specifies that the key is a 'decal', meaning that only the text labels should be rendered, not the keycap borders.
• ghost — specifies that key key is 'ghosted', meaning that it is to be rendered unobtrusively; typically semi-transparent and without any labels.
• stepped — specifies that the key is stepped.
• nub — specifies that the key has a homing nub / bump / dish; the exact rendering will depend on the key's profile.
• profile — specifies the key's "profile" (and row, for those profiles that vary depending on the row), e.g., "DCS R1" or "DSA".
  • Currently supported / known profiles: SA, DSA, DCS, OEM, CHICKLET, FLAT
  • Currently supported / known rows: R1, R2, R3, R4, R5, SPACE
• sm / sb / st — the switch mount, brand, and type, overriding the default values specified in the keyboard metadata.

Future Work

In rough order of priority:

1. This library is based on the original KLE code, but it has been converted to a TypeScript and modularized to make it convenient for others to consume; the KLE site itself is not yet using this actual code.
   • So the first order of business is to update KLE to use this exact NPM module.
   • That will ensure that the code is correct, and that nothing has been missed, as well as guarantee that the two projects are kept in sync.
2. This library currently only handles deserialization; the serialization code still needs to be ported.
3. More tests (particularly on the serialization side, once it's ported; it's much more error-prone than deserialization).
4. Migrate some of the supporting data from KLE to this project, so you don't have to look it up elsewhere, e.g.:
   • Switch mount / brand / type definitions.
   • Color palettes.
5. Migrate HTML key rendering templates (and supporting stylesheets) from KLE to this project, so anyone can render a key identically to KLE.

Tests

npm test