Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ijprest/kle-serial
Serialization library for keyboard-layout-editor.com
https://github.com/ijprest/kle-serial
json keyboard-layout-editor kle serialization
Last synced: 2 months ago
JSON representation
Serialization library for keyboard-layout-editor.com
- Host: GitHub
- URL: https://github.com/ijprest/kle-serial
- Owner: ijprest
- License: mit
- Created: 2019-06-29T20:50:45.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T03:30:57.000Z (about 2 years ago)
- Last Synced: 2024-10-16T15:08:47.155Z (3 months ago)
- Topics: json, keyboard-layout-editor, kle, serialization
- Language: JavaScript
- Homepage: http://www.keyboard-layout-editor.com/
- Size: 72.3 KB
- Stars: 75
- Watchers: 2
- Forks: 27
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# kle-serial
[](https://travis-ci.org/ijprest/kle-serial)
[](https://coveralls.io/github/ijprest/kle-serial?branch=master)
[](https://badge.fury.io/js/%40ijprest%2Fkle-serial)
[](https://david-dm.org/ijprest/kle-serial)
[](LICENSE)
This is a [MIT-licensed](LICENSE) 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:
```bash
npm install @ijprest/kle-serial --save
```
## Usage
```js
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
```ts
kle.Serial.deserialize(rows: Array): Keyboard
```
- Given an array of keyboard rows, deserializes the result into a `Keyboard`
object.
- The first entry is optionally a keyboard metadata object.
```ts
kle.Serial.parse(json5: string): Keyboard
```
- This function takes a JSON5-formatted string, parses it, then deserializes the
result into a `Keyboard` object.
- [JSON5](https://json5.org/) 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
```ts
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:
```ts
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](https://github.github.com/gfm/).
- `radii` — the radii of the keyboard corners, in
[CSS `border-radius` format](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius),
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:
```ts
export class Key {
color: string;
labels: string[];
textColor: Array;
textSize: Array;
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](https://deskthority.net/wiki/Return_key) or
[stepped keys](https://deskthority.net/wiki/Keycap#Stepped_keycaps)).
- 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](https://deskthority.net/wiki/Keycap#Stepped_keycaps).
- `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
```bash
npm test
```