Keymap-drawer

This is a release with minor external-facing changes, since most of them were internal tweaks to help downstream users like the web app.
I recently spent some time working on it at https://caksoylar.github.io/keymap-drawer and implemented a few improvements (and added sorely needed tooltips). If you haven't checked it out lately, you might want to have a look!

Also if you are a Kanata user, you can check out the work-in-progress Kanata config parser at https://github.com/caksoylar/keymap-drawer/tree/kanata and related issue #95.

Features

Drawing

- **Breaking change**: **Truncate legends** when they are too long:
- Number of lines in the `tap` field is truncated to at most 3; if >3, 3rd line will be replaced with `…`
- Length of each legend (in a single line) is truncated to `1.7 × draw_cfg.shrink_wide_legends` (by default `11`) chars. If longer than that, the last visible char will be replaced with `…`, similar to above

Fixes

- Fix parsing of devicetree arrays when they are split to multiple lines and multiple `<...>` blocks

Misc

- Add Ferris physical layout with rotated thumb keys, applying to all Ferris/Sweep variants
- This will be used by default; if you don't want this you can use [the original `info.json`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/ferris/sweep/info.json) with `keymap draw --qmk-info-json` argument, or the new "Layout Override" dialog in the web app
- Add Swoop physical layout
- Add support for generic physical layouts via `layout: {qmk_keyboard: generic/<layout_name>}`, which are specially fetched from https://github.com/qmk/qmk_firmware/tree/master/layouts/default/ (where `layout_name` is a subfolder name)

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.16.0...v0.17.0

This release contains two major new features: parsing of modifier functions and dark mode support! It also contains a couple of smaller breaking changes, so make sure to check them out below.

Features

Parsing
- Added support for **parsing modifier functions** like `LC(V)` in ZMK and `LCTL(KC_V)` in QMK, used for sending modified keycodes like <kbd>ctrl</kbd>+<kbd>v</kbd> events with one key press
- By default these will be converted to `Ctl+ V` representation, this is configurable via the new [`parse_config.modifier_fn_map` setting](https://github.com/caksoylar/keymap-drawer/blob/v0.16.0/CONFIGURATION.md#modifier_fn_map)
- You can also assign special names to specific mod combinations, like `Hyper+ X` for `LC(LS(LG(LA(X))))`
- **Breaking change:** If you were using entries like `LC(V): Paste` in `parse_config.zmk_keycode_map` or `C(V): Paste` in `qmk_keycode_map`, they will no longer work because `LC` and `V` parts are processed separately. If you want to preserve the mapping, instead define them in `raw_binding_map` like `&kp LC(V): Paste` for ZMK or `C(KC_V): Paste` for QMK.
- Added parsing for QMK tap-toggle layers `TT(LAYER)` by m-demare in https://github.com/caksoylar/keymap-drawer/pull/87

Drawing
- Added **dark mode support**, by snoyer!
- This is implemented as a special set of [CSS overrides](https://github.com/caksoylar/keymap-drawer/blob/v0.16.0/CONFIGURATION.md#svg_style_dark1) that get added to the final CSS if the new `draw_config.dark_mode` setting is on, or added under `media (prefers-color-scheme: dark)` when set to `"auto"` to fit the web page or OS light/dark setting.
- The default is `false` which means light mode only, so this is not a breaking change for CLI users. The [web app](https://caksoylar.github.io/keymap-drawer/) overrides it to `"auto"`.

| `dark_mode: false` | `dark_mode: true` | `dark_mode: auto` |
| - | - | - |
|  |  |  |

- Added support for **appending footer text** to produced SVGs using [`draw_config.footer_text`](https://github.com/caksoylar/keymap-drawer/blob/v0.16.0/CONFIGURATION.md#footer_text)
- The value goes into a `<text>` element but it isn't escaped, so you can add e.g. links using `<a>` tags
- The default value is empty so this isn't a breaking change for CLI users. The [web app](https://caksoylar.github.io/keymap-drawer/) overrides it to "<text>Created with <a href="https://github.com/caksoylar/keymap-drawer">keymap-drawer</a></text>"

- Added support for **using [Phosphor Icons](https://phosphoricons.com)**, check out how to use them in [the README section](https://github.com/caksoylar/keymap-drawer/blob/v0.16.0/README.md#custom-svg-glyphs)

CLI

- Added `-o`/`--output` parameter to all `keymap` subcommands, to write their output to the given path rather than stdout
- Using these parameters are recommended if you are running the CLI on Windows, since they ensure the outputs are written with `utf-8` encoding rather than the locale-specific one (which can break many things). This release also incorporates a couple fixes that ensure operation in Windows (tested in powershell)
- **Breaking change:** `keymap draw --ortho-layout` no longer supports the `-o` short form since that is taken over by the output parameter

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.15.0...v0.16.0

This is a smaller release with a couple of features that I wanted to release quickly: Automatic QMK keyboard mappings and changes to the config dumping.

Features

- **Breaking change**: Added a [new mapping layer](https://github.com/caksoylar/keymap-drawer/commit/e20025afef2230dca5aad6ac098337247b73e1cf#diff-06c2dc3fe896463bff49cceaf51980c3c9133d9384f855beb2ef3477da23e372) for QMK keyboard names
- This allows us to map given QMK keyboard name prefixes to other keyboard names during drawing
- It is currently used to map Corne, Lily58, Sofle and Kyria variants to the versions with rotated keys in [`qmk_layouts` folder](https://github.com/caksoylar/keymap-drawer/tree/main/resources/qmk_layouts)
- This is a breaking change if you were using e.g. `qmk_keyboard: crkbd/rev1` rather than `qmk_keyboard: corne_rotated` -- there is no way to prevent this mapping right now, so let me know if you really want the old behavior instead
- **Breaking change**: Config dumps via `keymap dump-config` no longer include certain "internal" draw config options, namely `svg_style`, `glyph_urls` and `use_local_cache`
- The rationale is that these shouldn't typically touched by users, and having them be present in all configs creates issues when default values change (such as when 78 is fixed)
- You can still override them in your config by manually including the keys, the functionality didn't change

Fixes

- Specially parse `0xff` as a special value in the `layers` property of the combo spec in ZMK keymaps, to mean all layers. This is used by [nodefree-config](https://github.com/urob/zmk-nodefree-config/blob/973f717/helper.h#L65)

Misc

- Add Kyria physical layout with rotated keys, by micampe
- Log what config args are used during ZMK drawing workflow

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.14.1...v0.15.0

It has been some time since the last release so this release is mostly a collection of smaller improvements, a lot of them contributed by the community (thanks!).

You might have noticed we also have a logo now, itself generated in `keymap-drawer`![^1]

Features

Parsing
- Support parsing of overridden node properties with `&nodelabel { prop = "new_value"; };` syntax (66)

Drawing
- Add a new way to specify physical layouts: "Cols+Thumbs" notation! This generates layouts with only non-rotated 1u keys, but it is significantly more flexible than `ortho_layout`. It supports columns with arbitrary number of keys, moving the thumb clusters left/right, asymmetric and 2+ number of split keyboard parts.
See the [documentation in the keymap spec](https://github.com/caksoylar/keymap-drawer/blob/v0.14.0/KEYMAP_SPEC.md#colsthumbs-notation-specification) to start using.
- Assign `key.type` to the CSS class of combos by englmaxi in https://github.com/caksoylar/keymap-drawer/pull/73
- Add a thin gray outline to combo boxes, to be consistent with key styling and look better

ZMK workflow
- Add workflow input for base path for `<keymap>.json` layout files by michaelrommel in https://github.com/caksoylar/keymap-drawer/pull/71
- Add published artifacts as a destination option by michaelrommel in https://github.com/caksoylar/keymap-drawer/pull/72
- Add a workflow input to fail GitHub action on parse/draw errors by englmaxi in https://github.com/caksoylar/keymap-drawer/pull/74

Fixes
- Update Tabler glyphs url that changed (again) by thebino in https://github.com/caksoylar/keymap-drawer/pull/79
- `v0.14.1`: Fix parsing for Tabler glyphs by SethMilliken in 82
- Use bounding boxes of combo boxes to properly calculate layer heights, to fix rendering issues with small `draw_config.outer_pad_h` values (70)
- Disallow using unrecognized fields in layer key specs or combo specs in keymap YAMLs

Misc
- Add kilipan/zilpzalp keyboard by kilipan in https://github.com/caksoylar/keymap-drawer/pull/68
- Add BastardKB boards by finrod09 in https://github.com/caksoylar/keymap-drawer/pull/76
- Add ZSA Voyager layout by stasmarkin in https://github.com/caksoylar/keymap-drawer/pull/75
- Upgrade Pydantic to version 2.x, along with other dev dependencies

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.13.4...v0.14.0

---

[^1]:
Here is the source keymap YAML for posterity:
yaml
draw_config:
append_colon_to_layer_header: false
svg_extra_style: "text.key { font-weight: bold; font-size: 16px; }"
glyph_tap_size: 16
layers:
" ": [keymap, drawer]
combos:
- {p: [0, 1], k: $$mdi:keyboard$$, a: bottom, o: 0.15, arc_scale: 1.2}
- {p: [0, 1], k: $$mdi:pencil-ruler$$, a: top, o: -0.15, d: false}

And layout json:
json
[
{ "x": 0, "y": 0, "w": 1.2, "h": 1.2, "r": 15, "rx": 1.2, "ry": 0 },
{ "x": 1.2, "y": 0, "w": 1.2, "h": 1.2, "r": -15, "rx": 1.2, "ry": 0 }
]

This release has a few fixes, adds more combo options to customize drawing and new ways to customize the ZMK parsing behavior.

Features

Parsing
- Add **parsing for toggled keys**, i.e.. `&tog`, `&to`, `&kt` for ZMK, `TG`, `TO`, `DF` for QMK
- The added label can be customized via [`parse_config.toggle_label`](https://github.com/caksoylar/keymap-drawer/blob/main/CONFIGURATION.md#toggle_label)
- Add a way to customize how keymap-drawer parses ZMK keymaps, via the **`KEYMAP_DRAWER` define**
- The ZMK parser now defines this symbol before parsing
- You can use it to add keymap-drawer-specific defines without affecting the ZMK build via `ifdef KEYMAP_DRAWER ... endif` guards
- You can use it to have keymap-drawer ignore certain parts without affecting the ZMK build via `ifndef KEYMAP_DRAWER ... endif` guards
- Add a way to **specify prefixes to be removed from keycodes** before further processing, via [`parse_config.qmk_remove_keycode_prefix`](https://github.com/caksoylar/keymap-drawer/blob/main/CONFIGURATION.md#qmk_remove_keycode_prefix) and [`parse_config.zmk_remove_keycode_prefix`](https://github.com/caksoylar/keymap-drawer/blob/main/CONFIGURATION.md#zmk_remove_keycode_prefix)
- See example in https://github.com/caksoylar/keymap-drawer/issues/50#issuecomment-1822111558 on how to combine above these two features to better handle locale headers like the ones generated via [`zmk-locale-generator`](https://github.com/joelspadin/zmk-locale-generator)
- This feature broke `parse_config.trans_legend` in v0.13.0, fixed in v0.13.1 (62)

Drawing
- Add **`rotation (r)` field** to the [combo spec](https://github.com/caksoylar/keymap-drawer/blob/main/KEYMAP_SPEC.md#combos) so you can individually rotate combo boxes -- this is in addition to `width`, `height` properties from [v0.12.0](https://github.com/caksoylar/keymap-drawer/releases/tag/v0.12.0)
- Also add **`draw_separate` field** to the combo spec to let you decide whether you want a combo to be drawn on the layers, or using a separate diagram for that combo
- [`draw_config.separate_combo_diagrams`](https://github.com/caksoylar/keymap-drawer/blob/main/CONFIGURATION.md#separate_combo_diagrams) setting introduced in [v0.11.0](https://github.com/caksoylar/keymap-drawer/releases/tag/v0.11.0) now sets the default behavior for combos if `draw_separate` isn't specified

Fixes
- Add support for using [`display-name`](https://github.com/zmkfirmware/zmk/commit/d4e8dee) in addition to `label` for figuring out ZMK layer names
- Calculate the total layer height (which can be increased due to combo boxes) in the correct way, rather than doing a rough approximation
- Fix bug during glyph aspect ratio calculation which led to small glyphs for `$$material:...$$` SVGs -- thanks to dhruvinsh for the bringing up the issue (and sorry for the late fix)
- Fix `APOS`/`APOSTROPHE` mapping in default `zmk_keycode_map`
- Update Tabler template URL to fetch SVGs from using `$$tabler:...$$` in v0.13.2, since the previous one doesn't seem to work anymore

Misc
- Added user friendly(-er) **configuration reference** at [CONFIGURATION.md](https://github.com/caksoylar/keymap-drawer/blob/main/CONFIGURATION.md)
- Fix layout mapping for [`luna` keyboard](https://github.com/mindhatch/keyboards#%E3%83%AB%E3%83%8A-luna) and make it use the splayed Hummingbird variant
- Add layouts for BastardKB Dilemma v2 and MAX, overriding the defaults when used with `qmk_keyboard: bastardkb/dilemma/3x5_3` and `qmk_keyboard: bastardkb/dilemma/4x6_4`, by casuanoob
- Add layout mapping for [`wizza`](https://github.com/AlaaSaadAbdo/battoota#wizza)

Looking forward

One feature that I have been working on some time is parsing for modified keys, to automatically convert keycodes like `&kp LC(LS(A))` to strings like `Ctrl+Shift+A`. While the implementation is complete and the end result is [configurable](https://github.com/caksoylar/keymap-drawer/blob/dev/CONFIGURATION.md#modifier_fn_map), I still haven't reached a decision on the default configuration for how to do the conversion so I haven't merged it to the `main` branch. I iterated through a few variations, e.g.
- `Ctrl+Shift+ A` resulting in `A` rendered on a separate line (default in the implementation)
- Also automatically uses `Hyper` and `Meh` for the appropriate mod combinations
- `CS+A`
- `C-S-A`
- Using Mac-like symbols like `⎈⇧A`

You can test this feature in the [`dev` branch](https://github.com/caksoylar/keymap-drawer/tree/dev) (also deployed to [streamlit](https://keymap-drawer-dev.streamlit.app)) and let me know your opinions/suggestions in the discussion linked to this release.

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.12.1...v0.13.1

This release contains a couple minor features, a few fixes and some physical layout updates for ZMK keyboards.

Features
- Add per-combo `width (w)` and `height (h)` field support. Defaults to `draw_config.combo_w`/`draw_config.combo_h` if they aren't specified or are null
- Add `draw_config.svg_extra_style` config that gets appended to `draw_config.svg_style`. This way you don't need to duplicate and modify `draw_config.svg_style` in your configuration and can simply add your overrides to `draw_config.svg_extra_style`

Fixes
- Fix invalid SVG error when using special char in layer labels by HelloThisIsFlo in https://github.com/caksoylar/keymap-drawer/pull/55
- Move workflow write permission field from workflow file to usage example

Misc
- Add a Sofle layout with rotated thumb keys by YellowAfterlife in https://github.com/caksoylar/keymap-drawer/pull/46
- Fix FFKB coordinates order by jaeyounglee978 in https://github.com/caksoylar/keymap-drawer/pull/52
- Add physical layouts support for keyboards designed by hazels-garage and cyril279
- Fix Glove80 thumb cluster layout
- Key ordering broken in v0.12.0 and then fixed in v0.12.1
- Add support for a few new ZMK shields: `microdox_v2`, `reviung34`, `reviung53`, fixed `tidbit`

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.11.0...v0.12.1