{"id":13991755,"url":"https://github.com/ijprest/kle-serial","last_synced_at":"2025-07-26T13:35:28.684Z","repository":{"id":34986828,"uuid":"194447337","full_name":"ijprest/kle-serial","owner":"ijprest","description":"Serialization library for keyboard-layout-editor.com","archived":false,"fork":false,"pushed_at":"2023-01-04T03:30:57.000Z","size":74,"stargazers_count":83,"open_issues_count":12,"forks_count":27,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-06T12:05:48.299Z","etag":null,"topics":["json","keyboard-layout-editor","kle","serialization"],"latest_commit_sha":null,"homepage":"http://www.keyboard-layout-editor.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ijprest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-29T20:50:45.000Z","updated_at":"2025-05-31T01:44:45.000Z","dependencies_parsed_at":"2023-01-15T11:32:07.054Z","dependency_job_id":null,"html_url":"https://github.com/ijprest/kle-serial","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ijprest/kle-serial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijprest%2Fkle-serial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijprest%2Fkle-serial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijprest%2Fkle-serial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijprest%2Fkle-serial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ijprest","download_url":"https://codeload.github.com/ijprest/kle-serial/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijprest%2Fkle-serial/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267175326,"owners_count":24047822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","keyboard-layout-editor","kle","serialization"],"created_at":"2024-08-09T14:01:34.207Z","updated_at":"2025-07-26T13:35:28.635Z","avatar_url":"https://github.com/ijprest.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# kle-serial\n\n[![Build Status](https://travis-ci.org/ijprest/kle-serial.svg?branch=master)](https://travis-ci.org/ijprest/kle-serial)\n[![Coverage Status](https://coveralls.io/repos/github/ijprest/kle-serial/badge.svg?branch=master)](https://coveralls.io/github/ijprest/kle-serial?branch=master)\n[![npm version](https://badge.fury.io/js/%40ijprest%2Fkle-serial.svg)](https://badge.fury.io/js/%40ijprest%2Fkle-serial)\n[![Dependency Status](https://david-dm.org/ijprest/kle-serial.svg)](https://david-dm.org/ijprest/kle-serial)\n[![GitHub](https://img.shields.io/github/license/ijprest/kle-serial.svg)](LICENSE)\n\nThis is a [MIT-licensed](LICENSE) javascript library for parsing the serialized\nformat used on keyboard-layout-editor.com (KLE) and converting it into something\nthat is easier to understand and use in third-party applications.\n\nKLE is frequently used to prototype and generate a rough keyboard layout, that\nis then used by other applications to create plates, circuit boards, etc. These\nthird-party applications currently use their own parsing logic.\n\nUnfortunately, the KLE format was designed to be _compact_ (due to some original\nlimitations), and the format has evolved considerably from its original\nversions. As a result, third-party parsing implementations aren't always 100%\ncompatible with KLE itself, particularly with respect to certain corner-cases or\nolder / deprecated properties.\n\nThis library is the same code that KLE itself uses to parse serialized layouts,\nso by using it, you can be sure that you are 100% compatible with the editor.\n\n## Installation\n\nInstall the package via NPM:\n\n```bash\nnpm install @ijprest/kle-serial --save\n```\n\n## Usage\n\n```js\nvar kle = require(\"@ijprest/kle-serial\");\n\nvar keyboard = kle.Serial.deserialize([\n  { name: \"Sample\", author: \"Your Name\" },\n  [\"Q\", \"W\", \"E\", \"R\", \"T\", \"Y\"]\n]);\n\n// or\n\nvar keyboard = kle.Serial.parse(`[\n  { name: \"Sample\", author: \"Your Name\" },\n  [\"Q\", \"W\", \"E\", \"R\", \"T\", \"Y\"]\n]`);\n```\n\n## API\n\n```ts\nkle.Serial.deserialize(rows: Array\u003cany\u003e): Keyboard\n```\n\n- Given an array of keyboard rows, deserializes the result into a `Keyboard`\n  object.\n- The first entry is optionally a keyboard metadata object.\n\n```ts\nkle.Serial.parse(json5: string): Keyboard\n```\n\n- This function takes a JSON5-formatted string, parses it, then deserializes the\n  result into a `Keyboard` object.\n- [JSON5](https://json5.org/) is a simplified / lenient version of JSON that is\n  easier for humans to type; in particular, it doesn't require quotes around\n  property names. Any valid JSON string should also be a valid JSON5 string.\n\n### Keyboard Objects\n\n```ts\nclass Keyboard {\n  meta: KeyboardMetadata;\n  keys: Key[];\n}\n```\n\nA `Keyboard` is an object containg keyboard metadata (`meta`) and an array of\n`keys`.\n\n### Keyboard Metadata\n\nThe `meta` object contains several fields:\n\n```ts\nclass KeyboardMetadata {\n  author: string;\n  backcolor: string;\n  background: { name: string; style: string } | null;\n  name: string;\n  notes: string;\n  radii: string;\n  switchBrand: string;\n  switchMount: string;\n  switchType: string;\n}\n```\n\n- `author` — the name of the author\n- `backcolor` — the background color of the keyboard editor area (default\n  `#eeeeee`)\n- `background` (optional) — a background image that overrides `backcolor` if\n  specified.\n  - The `name` identifies it from the list of backgrounds in the editor; other\n    consumers can ignore this property.\n  - The `style` is some custom CSS that will override the background color; it\n    will have the form: `background-image: url(...)`\n- `name` — the name of the keyboard layout\n  - Appears in the editor, below the keyboard.\n  - Identifies the keyboard among your saved layouts.\n  - Used to generate a filename when downloading or rendering the keyboard.\n- `notes` — notes about the keyboard layout, in\n  [GitHub-flavored Markdown](https://github.github.com/gfm/).\n- `radii` — the radii of the keyboard corners, in\n  [CSS `border-radius` format](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius),\n  e.g., `20px`.\n- `switchBrand`, `switchMount`, `switchType` — the _default_ switch `mount`,\n  `brand`, and `type` of switches on your keyboard.\n  - Default can be overridden on individual keys.\n  - See known values here:\n    https://github.com/ijprest/keyboard-layout-editor/blob/master/switches.json\n\n### Keys\n\nEach key in the `keys` array contains the following data:\n\n```ts\nexport class Key {\n  color: string;\n  labels: string[];\n  textColor: Array\u003cstring | undefined\u003e;\n  textSize: Array\u003cnumber | undefined\u003e;\n  default: { textColor: string; textSize: number };\n\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n\n  x2: number;\n  y2: number;\n  width2: number;\n  height2: number;\n\n  rotation_x: number;\n  rotation_y: number;\n  rotation_angle: number;\n\n  decal: boolean;\n  ghost: boolean;\n  stepped: boolean;\n  nub: boolean;\n\n  profile: string;\n\n  sm: string; // switch mount\n  sb: string; // switch brand\n  st: string; // switch type\n}\n```\n\n- `color` — the keycap color, e.g., `\"#ff0000\"` for red.\n- `labels` — an array of up to 12 text labels (sometimes referred to as\n  'legends'):\n  - In reading order, i.e., left-to-right, top-to-bottom:\n    - ![label order illustration](images/label-order.png)\n  - The labels are user input, and may contain arbitrary HTML content; when\n    rendering, input sanitization is recommended for security purposes.\n- `textColor` — an array of up to 12 colors (e.g., `\"#ff0000\"`), to be used for\n  the text labels; if any entries are `null` or `undefined`, you should use the\n  `default.textColor`.\n- `textSize` — an array of up to 12 sizes (integers 1-9), to be used for the\n  text labels; if any entries are `null` or `undefined`, you should use the\n  `default.textSize`.\n  - Note that the sizes are relative and do not correspond to any fixed font\n    size.\n  - KLE uses the following formula when rendering on-screen:\n    - (6px + 2px \\* _textSize_)\n- `default.textColor` / `default.textSize` — the default text color / size.\n- `x` / `y` — the absolute position of the key in keyboard units (where _1u_ is\n  the size of a standard 1x1 keycap).\n- `width` / `height` — the size of the key, in keyboard units.\n- `x2` / `y2` / `width2` / `height2` — the size \u0026 position of the _second_\n  rectangle that is used to define oddly-shaped keys (like an\n  [ISO Enter or Big-ass Enter key](https://deskthority.net/wiki/Return_key) or\n  [stepped keys](https://deskthority.net/wiki/Keycap#Stepped_keycaps)).\n  - If the size is (0,0), then there is no second rectangle required.\n  - The position is relative to (`x`, `y`).\n  - The two rectangles can be thought of as overlapping, combining to create the\n    desired key shape.\n    - Note that labels are always positioned relative to the main rectangle.\n    - If a key is `stepped`, the second rectangle is the lower part.\n    - ![oddly-shapped key illustration](images/oddly-shaped.png)\n    - In this example, the second rectangle is shown on top of the original\n      rectangle, and (`x2`,`y2`) [`width` x `height`] = (-0.75, 1.0) [2.25 x\n      1.0].\n- `rotation_x` / `rotation_y` — defines the center of rotation for the key.\n- `rotation_angle` — specifies the angle the key is rotated (about the center of\n  rotation).\n- `decal` — specifies that the key is a 'decal', meaning that only the text\n  labels should be rendered, not the keycap borders.\n- `ghost` — specifies that key key is 'ghosted', meaning that it is to be\n  rendered unobtrusively; typically semi-transparent and without any labels.\n- `stepped` — specifies that the key is\n  [stepped](https://deskthority.net/wiki/Keycap#Stepped_keycaps).\n- `nub` — specifies that the key has a homing nub / bump / dish; the exact\n  rendering will depend on the key's `profile`.\n- `profile` — specifies the key's \"profile\" (and row, for those profiles that\n  vary depending on the row), e.g., \"`DCS R1`\" or \"`DSA`\".\n  - Currently supported / known profiles: `SA`, `DSA`, `DCS`, `OEM`, `CHICKLET`,\n    `FLAT`\n  - Currently supported / known rows: `R1`, `R2`, `R3`, `R4`, `R5`, `SPACE`\n- `sm` / `sb` / `st` — the switch _mount_, _brand_, and _type_, overriding the\n  default values specified in the keyboard metadata.\n\n## Future Work\n\nIn rough order of priority:\n\n1. This library is _based_ on the original KLE code, but it has been converted\n   to a TypeScript and modularized to make it convenient for others to consume;\n   the KLE site itself is not yet using this actual code.\n   - So the first order of business is to update KLE to use this exact NPM\n     module.\n   - That will ensure that the code is correct, and that nothing has been\n     missed, as well as guarantee that the two projects are kept in sync.\n2. This library currently only handles _deserialization_; the serialization code\n   still needs to be ported.\n3. More tests (particularly on the serialization side, once it's ported; it's\n   much more error-prone than deserialization).\n4. Migrate some of the supporting data from KLE to this project, so you don't\n   have to look it up elsewhere, e.g.:\n   - Switch mount / brand / type definitions.\n   - Color palettes.\n5. Migrate HTML key rendering templates (and supporting stylesheets) from KLE to\n   this project, so anyone can render a key identically to KLE.\n\n## Tests\n\n```bash\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fijprest%2Fkle-serial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fijprest%2Fkle-serial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fijprest%2Fkle-serial/lists"}