Keymap-drawer

The highlights in this release are an experimental parser for Kanata configurations and ability to specify combos via contents/legends of the triggering keys.

Features

- Add an _experimental_ parser for [Kanata](https://github.com/jtroo/kanata/) configuration files (#95)
- Currently supports `defsrc`, layers via `deflayer`, combos via `defchordsv2`, and `include`/`defvar`/`defalias`
- Physical layouts are automatically selected depending on keys used in `defsrc`, ranging from a 60% to a full size layout
- Output legends can only be customized via [`raw_binding_map`](https://github.com/caksoylar/keymap-drawer/blob/v0.21.0/CONFIGURATION.md#raw_binding_map)
- Feel free to open a new [discussion](https://github.com/caksoylar/keymap-drawer/discussions/new?category=kanata) for any feedback, it'd help me prioritize any future improvements

- Add a new way to specify [combo](https://github.com/caksoylar/keymap-drawer/blob/v0.21.0/KEYMAP_SPEC.md#combos) positions: using `trigger_keys`/`tk`. This lets you do QMK-like combo specs, where you list the legends for the keys that would be used to trigger a combo
- By default a full match for the legend will be searched for, but it will fall back to matching only the center/tap legends if not found
- Example:

yaml
layers:
base:
- { h: Ctrl, t: J }
- { h: Alt, t: K }
...
combos:
below are all equivalent
- { p: [0, 1], k: Esc }
- { tk: [{ h: Ctrl, t: J }, { h: Alt, t: K }], k: Esc }
- { tk: [J, K], k: Esc }


- Add a new physical layout spec: `zmk_keyboard`. This typically corresponds to ZMK keyboard name used in `<keyboard>.keymap`, such as `zmk_keyboard: corne`
- Internally this is used as an alias to map to other physical layout types; see the new [physical layouts documentation](https://github.com/caksoylar/keymap-drawer/blob/v0.21.0/PHYSICAL_LAYOUTS.md#keyboard-aliases) for details
- `keymap parse` will output this spec by default after parsing ZMK keymaps

New layouts

- Add `tsuru` physical layout
- Add corrected `lotus58` layout for its ZMK definition
- Add support for Corne v4 layouts with extra keys to `corne_rotated` (161)

ZMK drawing workflow

- Optimize fetching modules from `west.yml` and turn it on by default
- Excludes fetching ZMK and Zephyr, aiming to only get user-specified extra modules
- Improve behavior when there are errors in the parse/draw, specifically when `fail_on_error` isn't set
- Now the workflow will show as failed when there are any errors, but commit/upload will happen for successful operations if `fail_on_error` is not set
- Add a `debug_mode` flag that sets `keymap` CLI's `--debug` flag and echoes the commands run inside the actions
- Add `install_version` input that lets you specify `keymap-drawer` version to use. Ignored if `install_branch` is set

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.20.0...v0.21.0

This release fixes the package installation issue due to breaking changes in Poetry 2.0. (If you really need a backport of the fix to previous versions, let me know.)

Features

- Add a logging mechanism and a debug flag `keymap -d` to the CLI, where it prints debug-level logs to the stderr by default

Drawing

- Add `left` and `right` key fields, to draw on left and right side of the key.
- Also add new aliases `top` and `bottom` for `shifted` and `held` respectively.
- Initial implementation contributed by magicDGS
- Add automatic line breaking based on word boundaries
- Line breaking using spaces is still respected, but additional line breaks can be added if line is too long
- Desired line length is controlled by `draw_config.shrink_wide_legends`, set to 0 to disable

Parsing

- Support `zmk,physical-layout` selections in ZMK keymaps' `chosen` nodes, similar to `zmk,matrix-transform`

Fixes

- Fix package installation bug due to breaking change in Poetry 2.0, where `resources` files weren't installed when installing from a wheel (e.g. using `pip install`)
- Fix validation of `draw_config` field in keymap YAML files

Misc

- Add `forager` physical layout

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.19.0...v0.20.0

This release updates ZMK parsing to use a tree-sitter-based parser and adds support for ZMK physical layouts in devicetree format (used by Studio), among other improvements.

The new parsing implementation results in speed improvements that range from 10% shorter runtime to 7x, with a median speed-up of ~2x in my test cases.
If you encounter any new problems with parsing your keymaps, please open an issue!

Features

Drawing

- Add [`dts_layout` option](https://github.com/caksoylar/keymap-drawer/blob/v0.19.0/KEYMAP_SPEC.md#zmk-physical-layout-specification) for physical layouts, and corresponding `--dts-layout` CLI arg.
- This is analogous to `qmk_info_json` field pointing to a file path, except the file should contain ZMK's physical layout nodes in devicetree
- **Deprecated** `qmk_layout` field in physical layout definitions, and corresponding`--qmk-layout` CLI arg.
Use `layout_name` instead, which also works with `dts_layout` above

Parsing

- Add [`parse_config.layer_legend_map`](https://github.com/caksoylar/keymap-drawer/blob/v0.19.0/CONFIGURATION.md#layer_legend_map) which can be used to customize how layer names are represented in the keymap
- This is similar to how e.g. `zmk_keycode_map` is used to change keycode representations, but applied to layer names instead
- Switch to a [`tree-sitter-devicetree`](https://pypi.org/project/tree-sitter-devicetree/)-based parser for ZMK, from the old `pyparsing`-based one
- Add `--virtual-layers` CLI argument to `keymap parse`
- This appends empty "virtual" layers at the end of the keymap; this can be used for assigning combos etc. to show them on a separate diagram
- Also look-up behavior prefixes in `raw_binding_map`
- For example match entries like `&td` for ZMK behavior bindings like `&td 0` to fix for behaviors nested in hold-taps

Fixes

- Ignore "reserved" ZMK layers while parsing, used for ZMK Studio
- Better support for Studio-related ZMK updates to come, see 125
- Switch to using Github raw URL for `mdi` glyphs, by magicDGS in 132
- The old unpkg URL was unreliable and seems to have eventually disappeared
- Add retries and a more generous timeout for fetching SVG glyphs from remote URLs
- More correctly center/normalize QMK physical layouts when there are rotated keys

ZMK drawing workflow

- Use pipx for installs in draw-zmk.yml (PEP 668) by janwvjaarsveld in 118
- Enable extended globbing for pattern matching by thazhemadam in 121

New Contributors
* janwvjaarsveld made their first contribution in 118
* thazhemadam made their first contribution in 121
* dhruvinsh made their first contribution in 126
* magicDGS made their first contribution in 132

**Full Changelog**: https://github.com/caksoylar/keymap-drawer/compare/v0.18.1...v0.19.0

This release contains a couple bug fixes.

- Avoid newlines between 2 tspan elements by wouterj in https://github.com/caksoylar/keymap-drawer/pull/114. This fixes the annoying horizontal mis-alignment when the tap legend had 3+lines.
- Add an additional `u` alias for key width in json-format `qmk_keyboard`. This is sometimes emitted by https://nickcoutsos.github.io/keymap-layout-tools after importing e.g. Kicad PCB files.

This release adds support for parsing ZMK configs that use modules like [zmk-helpers](https://github.com/urob/zmk-helpers/) with additional config options, along with adding special styling to layer key legends and making them clickable.

Edit: `zmk-helpers` now have [docs](https://github.com/urob/zmk-helpers/blob/main/docs/keymap_drawer.md) on using `keymap-drawer` with it using below changes.

Features

Drawing

- **Breaking change:** Add new config option [`draw_config.style_layer_activators`](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/CONFIGURATION.md#style_layer_activators) which defaults to true. This marks layer activators legends by adding a link that goes to the corresponding layer (might not work for embedded SVGs), and adding an underline by default.
- If you want to restore the old behavior, this setting can be disabled in the config file: `draw_config: { style_layer_activators: false }`
- You can change the styling, e.g. if you want italic instead of underlined:
yaml
draw_config:
svg_extra_style: |
text.layer-activator { text-decoration: none; font-style: italic }

- Add a new CSS class `alternate` so you can define separate styling for extra activators marked by the [`parse_config.mark_alternate_layer_activators` config](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/CONFIGURATION.md#mark_alternate_layer_activators) (no styling defined by default) (98)
- Example:
yaml
parse_config:
mark_alternate_layer_activators: true
draw_config:
svg_extra_style: |
rect.held.alternate { fill: 478583; }
media (prefers-color-scheme: dark) { rect.held.alternate { fill: 478583; } } some other color here

- Add `hidden` property to the [combo spec](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/KEYMAP_SPEC.md#combos), so you can avoid drawing certain combos that the parser outputs by adding `hidden: true` (for instance through [`parse_config.zmk_combos`](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/CONFIGURATION.md#zmk_combos)) (104)
- Example:
yaml
parse_config:
zmk_combos:
combo_esc: { hidden: true }

- Support using underscore instead of space as split separator for the [cols+thumbs notation](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/KEYMAP_SPEC.md#colsthumbs-notation-specification) spec in order to reduce command line quoting issues
- Example: `keymap draw -n 33333+2_3+233331 my_asymmetric_keymap.yaml`

- Implement support for [`layout_aliases`](https://docs.qmk.fm/reference_info_json#layouts) in `qmk_keyboard` physical layout definitions

Parsing

- Add [`parse_config.zmk_additional_includes`](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/CONFIGURATION.md#zmk_additional_includes) to augment the preprocessor include path (105)
- This can be used to be able to parse keymaps using `zmk-helpers` using the module functionality, since `include`s aren't using relative paths in that case. Example:
yaml
parse_config:
zmk_additional_includes: [ "zmk-helpers/include" ]

- If you want to use it in the automated ZMK drawing workflow, use the new `west_config_path` argument to the workflow (107) so that the modules defined in the `west.yml` file are automatically fetched. (You still need the above value in the config.) Example:
yaml
jobs:
draw:
uses: caksoylar/keymap-drawer/.github/workflows/draw-zmk.ymlmain
permissions:
contents: write allow workflow to commit to the repo
with:
[...]
west_config_path: 'config' this folder contains west.yml with module definitions

- Module fetching is not (yet) supported in the ZMK URL parse option of the [web app](https://caksoylar.github.io/keymap-drawer/)
- Add [`parse_config.zmk_preamble`](https://github.com/caksoylar/keymap-drawer/blob/v0.18.0/CONFIGURATION.md#zmk_preamble) config option which is text inserted at the beginning of the keymap, usually used to modify preprocessor behavior. It defaults to `define KEYMAP_DRAWER` (103)
- The default value exposes the existing behavior which was being defined internally before this change
- Restore support for using modified keycodes like `LC(LEFT)` in `parse_config.*_keycode_map` that was removed in v0.16 (106)

Fixes

- More robust devicetree parsing because of a few fixes involving parsing phandle arrays, such as when elements can have commas or split to multiple `<...>, <...>;` blocks (102)
- More robust QMK keymap.json parsing, for cases where the keycodes can contain extra spaces

Misc

- Add a physical layout definition for `hummingbird` keyboard
- For unibody keyboards like `fingerpunch/ffkb` and `rufous`, change the default physical layout to avoid all keys being rotated. This should improve readability by sacrificing faithfulness to the actual layout
- The older rotated versions are available using `fingerpunch/ffkb_rotated` and `rufous_rotated`

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

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