feat request: make `layer_legend_map` update layer headers

[urob]

• layer_legend_map doesn't update the layer headers, making them no longer match the key labels
• Relatedly, this is breaking the hyperlink (this might be automatic since there's no matching header)

Both are pretty minor but I think adding this would be a nice qol improvement

[caksoylar]

Hey, original request came from @thazhemadam and they were using SVG glyphs, which led me to think the layer headers maybe should stay as the original non-mapped variants.[^1] On second thought, I can see it going either way, with mapping them making a bit more sense. I think I was aware of hyperlink being broken when I implemented it but considered it low priority.

What do you (want to) use as the layer legend map? It'd be good to more example usages to decide which way makes more sense.

(As an aside, I think setting --layer-names in the CLI would achieve this, but it is a bit of an ugly solution to the problem.)

[^1]: It will be pretty hard to support SVG glyphs here, right now. So not sure what to do if we decide to map the header

[urob]

Good point about glyphs, I hadn't thought about those.

My use case is less relevant in comparison. I wanted to tweak the naming of layer names for the drawing and would have preferred to keep all of that in one place. But since I can also set display-name to the same effect (which I don't use for anything else), there's a simple workaround via the keymap.

Re: linking, maybe the more general solution here would be to allow for custom layer-activator maps. This could also be useful for things like num-word where there's no dedicated num label. Ideally, there would be a way for the map to be recognized both the linking and by by the layer-activators on the destination layer (even if the activator isn't a hold). Maybe something in that spirit:

custom_layer_activators:
  # Simple usage: 'layer-name: custom-activator-label'
  # Note: to fix the glyph issue, this should work regardless of how '&lt 1 X' is labeled
  Nav: '&lt 1 X'

  # Advanced usage: Additional config option so activator works also on taps
  Num: {'binding': '&numword', 'requires-hold': 'false'}

[caksoylar]

I guess using display-name works fine for that, yes. I'll try to find a solution to fixing links though. It should be supported with layer_legend_map by default, and this should be implementable with some more work.

Regarding custom behaviors, I see the point in letting them customize layer activators. While the recursive parsing logic works fine for built-in behaviors (i.e. anything that resolves down to &mo gets marked) it's hard to cover custom behaviors. It is also very painful to add layer activators after parsing, so a config-based solution there would be nice. Let me consider your suggestion with custom_layer_activators.

As an aside, if you have any custom behaviors that you'd prefer to convert the legends in a canonical way (like hold-taps resolving to {t: X, h: Y}) do let me know. I am not against adding parsing logic for those where it makes sense.

[caksoylar]

~~I started to actually implement this, and then realized the issue I was missing: the layer activator styling is happening in the draw phase, where we don't carry over any layer activation-related data from parsing (besides t: held parsing adds). Hence, the reason hyperlinking is dumb and only does a string comparison to determine layer activators right now. Similarly, layer_legend_map cannot be taken into account because it is used and resolved in the parse stage.~~

~~We can add custom_layer_activators in parse config and that can be used to assign additional held keys. But layer activator/hyperlinking won't work. An alternative is to add extra fields to LayoutKey in the keymap YAML, something like activates: layer_name [^1]. This would also remove the necessity of custom_layer_activators since you can add activates: in raw_binding_map or zmk_keycode_map.~~

~~I think we either accept hyperlinking not being robust and definecustom_layer_activators, or compromise on the simplicity of keymap YAML and add an extra layer-related field like activates. The latter also conflicts with the current held approach [^2], so could be considered a breaking change if we change how parse behaves.~~

[^1]: also, how would we specify held vs. tapped activation here? [^2]: which admittedly wasn't the most elegant either

Edit: This wasn't super well thought out, I will try to elaborate my thoughts better on #158

[peterjc]

Commenting here after realising that layer_legend_map only changes the names shown on the keys (useful if you need to abbreviate them to fit), while I wanted to change the big caption above the sub-figure for each layer.

In my case the ZMK configuration uses short names with ZMK Studio in mind, and I would like to expand on these in the figure (but am happy as things stand).