feat: overhaul preset definitions

[Julusian]

see bitfocus/companion-module-base#182

Allows for:

Screencast.From.2026-02-01.21-41-17.mp4

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dnmeid]

Maybe a good moment to bring back two long standing feature requests about presets:

1. Having a sort-name property, that is used for alphabetical sorting first if present. Could be string or number and if two presets have the same sortName the name is the second sorting criterium.
2. Possibility of organizing feedbacks hierachically. This request was partly solved with the text presets definition, but text presets are only able to provide headers and sections, not a real (collapsible) hierarchy.
   The idea is to make the category property more powerful. If it is a regular string this is the name of the category. If it is an object like {name: 'Category Name', description: 'In this category are only important presets', sortName: '1'}, this will be the category but with additional metadata. If it is an array like ['Category Level 1', 'Category Name'], the preset will be in a folder named "Category Name" which itself is in a folder named "Category Level 1". Each folder/category can have subfolders/subcategories and presets. If the array contains objets like ['Category Level 1', {name: 'Category Name', description: 'In this category are only important presets', sortName: '1'}], the logic is like before. But since every preset could possibly declare competing metadata for the same category name, only the latest declared value will win.

So both of those changes would be completely backwards compatible and give a very easy upgrade path for module developers if they want to enhance preset organization. This would also bring the regular button presets to the same level of text presets but with less effort at declaration.

[Julusian]

Having a sort-name property, that is used for alphabetical sorting first if present.

With this change, it goes back to relying on the order the presets/sections/groups are provided in

Possibility of organizing feedbacks hierachically. This request was partly solved with the text presets definition, but text presets are only able to provide headers and sections, not a real (collapsible) hierarchy.

This adds a single additonal level of groups, replacing the current text definiiton with the name+descritpion of a group.

I realised that the text definition type needs to go away for searching to be sane, otherwise we will need to either discard the text nodes early (loosing the context), or many searches will be left with just the text nodes.

Each folder/category can have subfolders/subcategories and presets.

I almost did do an unlimited depth for these, but I dont think we actually want that from a UX perspective. I'm not sure that even the groups I have added would want to collapse, but maybe they could (perhaps automatically when they grow above some threshold of number of contents). I dont think that going further than that will be nice to use.

So both of those changes would be completely backwards compatible

This is a decision to make here; Do we want something backwards compatible but harder to interpret and understand (both on companion and module dev side), or a breaking change that gives a chance to clean it up?

The other idea I had was to basically don't touch the current structure (other than require an unique id on each preset), but to have a second optional parameter that defines the new structure, referencing the array of presets by id.
But I also think that will be pretty tedious to construct safely (very easy to misuse ids).
This would have a different benefit of allowing the same preset to be shown at multiple points in the structure though, without being redefined, but I'm not sure that is worth the worse DX

Personally, I think that a bit of a breaking change would be beneficial. My hope is that by forcing devs to review their preset code a little, they are more likely to update it to newer functionality. Like the matrix group; which will cut down the volume of presets many provide dramatically.
And encourage them to consider if local variables could be used now that we are letting them do that.

A good example of why is there was an issue a couple of years back with bmd-videohub where it kept crashing for 288x288 videohubs, because of the volume of presets. It was trying to produce 288x288x3. All those could now be replaced with just a handful