Keymap-drawer

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

This release introduces a few major drawing features, automated ZMK workflow improvements and a major internal refactor to improve the project structure.

Features
- **Multiple output columns!**
- Set the `draw_config.n_columns` variable to e.g. 3 to output with three layer columns


- **Separate combo diagrams!** For those of you who use thumb+alpha combos or steno-like keymaps, there is now the option
to draw each combo in a separate minified layer diagram, showing the output key and the triggering key positions.
- Set `draw_config.separate_combo_diagrams: true` to enable, and `draw_config.combo_diagrams_scale` to tweak the scaling factor (default `2`)
- Currently the `layers` property of the combos are ignored and not visualized, might be added in the future if there is a clean way to show it
- Key corner radii are currently not scaled, so the keys will look rounder for higher scale factors


- Add key sides to drawn keys to give a keycap "profile" appearance, by riccardoflp
- `draw_config.draw_key_sides: true` to enable, tweak the appearance via `draw_config.key_side_pars`
- Currently may not render well on Safari, looking into workarounds


Fixes
- Sort SVG glyph defs before writing to avoid non-deterministic output
- Tweak Tabler-related CSS to hide the outline boxes in Safari, by bryanforbes
- Fix font size issue in hold/shifted fields due to `draw_config.shrink_wide_legends`, by `inxi` (at MoErgo Discord)
- Fix issue creating unnecessarily long dendrons for certain combo types

ZMK drawing workflow
- Add option to amend the last commit and also commit parse output YAML, by minusfive
- Recursively checkout the repo to support git submodules like [zmk-nodefree-config](https://github.com/urob/zmk-nodefree-config), by shroomist

Misc
- Tweak classes for output SVG elements to allow for better customization via CSS
- Assign `key`/`combo` classes to rect+text elements for layout keys/combos
- Assign `keypos-N`/`combopos-N` classes to key/combo elts. to allow addressing via position index `N`
- Add a proper physical layout for `slicemk_ergodox`, by xudongzheng
- Round SVG coordinate/size values for better readability and smaller output size, by art4ride and me

Note that future updates might unfortunately include more CSS changes, such as converting to the descendants selector syntax, e.g. `.held rect { ... }` from `rect.held { ... }`. Thanks to the folks at LowProKB and MoErgo for helpful discussions.

I will also prioritize a better documentation organization in the short term, possibly hosted on Github pages.

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

This release adds support for parsing alternative matrix transforms in ZMK like `five_column_transform` for Corne variants and other improvements.

Also check out the new ["Community" section](https://github.com/caksoylar/keymap-drawer#community) for nice projects using `keymap-drawer` to get inspired from!

Features
- Add ability to **parse selected ZMK matrix transforms** in a `chosen` node and update [ZMK layout mappings](resources/zmk_keyboard_layouts.yaml) to support different matrix-transform-to-physical-layout mappings
- **Breaking change**: Convert `draw_config.arc_scale` config param to be a [per-combo setting](KEYMAP_SPEC.mdcombos) instead of a global parameter
- **Change the default styling of `ghost` keys** to have a dashed outline rather than a dark gray fill
- You can restore it to [the old style](https://github.com/caksoylar/keymap-drawer/blob/v0.9.0/keymap_drawer/config.py#L84) in `draw_config.svg_style` if needed
- Make params of `&bt` such as `BT_SEL` mappable in `parse_config.zmk_keycode_map` by minusfive in https://github.com/caksoylar/keymap-drawer/pull/28
- **Warning**: This will be refactored and these parameters will likely be supported under a different section soon, and `zmk_keycode_map` be reserved for keycodes only
- Add a new **`-g`/`--ghost-keys` option** to `keymap draw` to programmatically assign `type: ghost` to given key positions before drawing

Fixes
- Devicetree parser now uses the last value if a property is defined multiple times, like Zephyr
- Devicetree parser no longer fails with `parse_config.preprocess: false`

Misc
- The web app code is moved to a different project, https://github.com/caksoylar/keymap-drawer-web
- As a result the Streamlit URL changed as well; note that https://caksoylar.github.io/keymap-drawer will always redirect to the latest, so I encourage using that link
- Overhaul [examples](examples/) to use more combo-related features and SVG glyphs
- Add and use `lily58_rotated` physical layout with properly rotated thumb keys, by Nicell
- Default to `corne_rotated` physical layout for all Corne variants
- Add mappings for custom shields in https://github.com/JonMuller/gerbers, `lpgalaxy_war_driver`, `lpgalaxy_blank_slate`, `technikable` and a few more
- Improve physical layouts coverage for boards/shields in the ZMK repo

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.9.0...v0.10.0