Theme definition

[DeaconDesperado]

Draft implementation of the specification laid out in #2297. Would love feedback on this!

Rough outline of the changes:

• Introduces a new struct, Styling, and the necessary protobuf records to match the spec from [Proposal] New theme definition spec #2297
• Implements KDL deserialization for Styling
• Provides bidirectional conversion for Styling <-> Palette in order to preserve backward compatibility for themes:
  • Assignment of colors from the old palette to the new spec was reconstructed gradually by manual comparison.
  • In some instances the same older named color may be used in multiple places (the new specification is more flexible and has more assignable styles, this only affects the default where user still has a Palette in their config).
• Preserve backward compatibility for plugins:
  • Styling -> Palette conversion is performed in the plugin_api layer, so the older message format is still propagated to plugins.
• Replace all references to named colors with style specifications

Open questions / notes

client_id_to_colors

This function is used to colorize pane frames and cursors in multi-user sessions. While mentioned in some of the comments, the proposed specification in #2297 didn't explicitly lay these colors out, and there are (presently) 10 of them (larger in number than the other specs). We could consider adding a separate style block for these, repurposing some of the emphases from frame_unselected, or using some sane defaults? This draft presently sets them to values from crate::shared::colors for the time being.

Configuration shape

KDL prohibits anonymous nodes, and lists are represented as sequential values after the node name. In order to support all three representations of color presently used (single digit, 3 digit rgb, hex) the style specifications all are named individually, and macros from the original Palette are reused to deserialize the color, EG:

text_unselected {
  base "#DCD7BA"
  emphasis_1 "#ACD7CD"
  emphasis_2 "#DCD8DD"
  emphasis_3 "#DCD899"
  emphasis_4 "#ACD7CD"
  background "#16161D"
}

It's arguably a bit redundant to have these indexes named sequentially this way? It might be possible to consolidate all the emphases to one list, but then that one node would need to be extracted into all 4 indexes somehow, which presents the prospect of mixing the EightBit/RGB/Hex representations... WDYT?

Currently, Styling's members are stored as fixed length arrays: it felt like a reasonable way to preserve the ability to add more colors in the future if needed. An alternative could be this structure though.

UI Components

Given that I'm only just getting familiar with the codebase, I opted to make these changes in place without also doing a migration of plugins to the various UI components 😅 . The coloration should be consistent however, only preserving differences where they are an artifact of the present implementation.

An example: When using simplified_ui, the ribbon implemented directly in the status-bar plugin uses alternating background colors to differentiate "tabs", whereas the UI component (eg in session-manager) uses divider spacers colored to match the terminal background. Where encountered, these kinds of differences are preserved (for now).

ThemeHue + PaletteSource

The swap of foreground/background based on ThemeHue is preserved only when converting a Palette to a Styling. The only place I could find this value to be set was in this function, which doesn't seem to be called anywhere. Perhaps it's leftover from an earlier implementation? I seemed to uncover similar for PaletteSource. Not sure if I'm missing something here...

Strider

I was unfortunately unable to do as much vetting of strider specifically, encountered #3064 when trying to test it out. Might require some help with this.

Still TODO

In addition to incorporating any feedback, still need to:

• Update test suites that use snapshot assertion (temporarily ignored here)
• Investigate any e2e test suites that need to be updated
• Document the new theme KDL and update the examples
• Rebase and clean up commit messages
• Might make sense to extend the zellij convert-theme utility to migrate existing configurations to the new format?

Screenshots

Comparison of default theme (left new, right old)

Welcome screen

Frameless layout

Run pane exit codes

Simplified UI (no arrow fonts)

Compact layout

[imsnif]

I'm very excited to see this happening!!

Just a heads up: I'm in the process of wrapping up v0.40.0 in the next week or so, so it will take me a short while to get to this. But rest assured, I will! I ask for your patience and thank you again for what seems like a tremendous amount of work!

[glenn-lytx]

Is there a full config example for this? I'd like to grab this and compile it locally to test it out ..

[imsnif]

Hey @DeaconDesperado - amazing and very thorough work here! Thank you for your patience and apologies for taking so long to give you an initial review. I'll try to be faster from now on so we can iterate over this quickly.

If it's alright with you, I prefer to go over the actual code changes once the product side (API, config, spec, behaviour, etc.) has been finalized. I think it'll save both of us some work, because changes in that area can cause sweeping changes in its implementation.

So to your questions:

Open questions / notes

client_id_to_colors

Good catch, we didn't account for these. Perhaps we can add a multiplayer_user_ids section to the theme definition?

Configuration shape

It's arguably a bit redundant to have these indexes named sequentially this way? It might be possible to consolidate all the emphases to one list, but then that one node would need to be extracted into all 4 indexes somehow, which presents the prospect of mixing the EightBit/RGB/Hex representations... WDYT?

I actually like it this way. I understand it can seem a bit redundant, but I think in the context of a theme configuration this is much clearer than emphasis <color_1> <color_2> <color_3> <color_4> - especially considering the different color formatting as you mentioned.

Currently, Styling's members are stored as fixed length arrays: it felt like a reasonable way to preserve the ability to add more colors in the future if needed. An alternative could be this structure though.

I don't have a strong opinion here, so up to you. A few considerations:

1. Performance (unless I'm wildly missing something) is not an issue for this feature whatsoever. So there's no need to be very cognizant of memory copying/cloning (in the context of the fixed-size arrays). Parsing the configuration is an order of magnitude slower, serializing the struct across the wasm boundary is an order of magnitude slower and otherwise sending it between threads is something that happens only on application startup (or configuration change) in which cases there are much slower things that happen as part of the process (eg. loading plugins, rendering, etc.)
2. If you decide to go with fixed-size arrays after all, I'd rather not have them in a public interface, and care needs to be taken in their setters so as not to crash ever if they overflow.
3. I usually prefer to be verbose in these sorts of things. If it were me I'd have a specialized struct similar to the one you mentioned with emphasis_1, emphasis_2, etc. as explicit members. But really - up to you.

UI Components

Given that I'm only just getting familiar with the codebase, I opted to make these changes in place without also doing a migration of plugins to the various UI components 😅 . The coloration should be consistent however, only preserving differences where they are an artifact of the present implementation.

Legit! Let's keep things simple.

ThemeHue + PaletteSource

The swap of foreground/background based on ThemeHue is preserved only when converting a Palette to a Styling. The only place I could find this value to be set was in this function, which doesn't seem to be called anywhere. Perhaps it's leftover from an earlier implementation? I seemed to uncover similar for PaletteSource. Not sure if I'm missing something here...

Yes, these are legacies! It's totally fine to remove them if you want.

Strider

These issues were fixed in v0.40.0 and iirc I even moved lots of stuff to UI components, so I hope this will make things easier!

Anything else I can do to help move this along?

[DeaconDesperado]

@imsnif Thanks for the thorough answers! Will incorporate this feedback and have another go at Strider.

[DeaconDesperado]

@glenn-lytx below is a sample of the themes block I've been using locally (also used in the screenshots), just need to change theme_name to suit:

themes {
  theme_name {
     styling {
          text_unselected {
              base "#DCD7BA"
              emphasis_1 "#ACD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#16161D"
          }
          text_selected {
              base "#16161D"
              emphasis_1 "#ffa066"
              emphasis_2 "#16161D"
              emphasis_3 "#16161D"
              emphasis_4 "#16161D"
              background "#9CABCA"
          }
          ribbon_unselected     {
              base "#DCD7BA"
              emphasis_1 "#9CABCA"
              emphasis_2 "#7AA89F"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
              background "#363646"
          }
          ribbon_selected {
              base "#16161D"
              emphasis_1 "#ffa066"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#76946A"
          }
          table_title {
              base "#DCD7BA"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
              background "#252535"
          }
          table_cell_unselected {
              base "#DCD7BA"
              emphasis_1 "#DCD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#1F1F28"
          }
          table_cell_selected {
              base "#16161D"
              emphasis_1 "#181820"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#76946A"
          }
          list_unselected {
              base "#DCD7BA"
              emphasis_1 "#DCD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#1F1F28"
          }
          list_selected {
              base "#16161D"
              emphasis_1 "#181820"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#76946A"
          }
          frame_unselected {
              base "#DCD8DD"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
          }
          frame_selected {
              base "#76946A"
              emphasis_1 "#C34043"
              emphasis_2 "#C8C093"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
          }
          exit_code_success {
              base "#76946A"
              emphasis_1 "#A3D5D5"
              emphasis_2 "#76946A"
              emphasis_3 "#76946A"
              emphasis_4 "#76946A"
          }
          exit_code_error {
              base "#C34043"
              emphasis_1 "#DCD819"
              emphasis_2 "#C34043"
              emphasis_3 "#C34043"
              emphasis_4  "#C34043"
          }
    }
  }
}

[glenn-lytx]

@glenn-lytx below is a sample of the themes block I've been using locally (also used in the screenshots), just need to change theme_name to suit:

Awesome, thanks! I'll give it a try

[DeaconDesperado]

Revised this quite heavily with the suggested changes:

• Changed to an explicit struct, StyleDeclaration, in lieu of fixed size arrays + position indexing.
• Introduced a new type MultiplayerColors and handling for multi-user sessions.
• Corrected handling of styles in UI components (previous draft did not properly style tables and lists independent of styling in text).

To validate the behavior of the UI components, I set up a very simple toy example based on rust-plugin-example that just renders all the elements in various states (with silly, but noticeable color differences between states)

Let me know if the high level approach here now looks sound, and then I'll proceed with improving the test coverage for backward compatiblity and the aforementioned product stuff to support migration (docs, possible script to migrate old palette to new themes). Also LMK if we prefer that in a separate PR. Thanks!

[imsnif]

Hey @DeaconDesperado - I'm happy to see the work going on. Kudos on your perseverance and consistency, this looks like quite a great effort!

I'm sorry it's taking me a bit of time to get to this, but rest assured - I plan to ASAP! I have not forgotten nor do I mean to let your work go to waste.

[imsnif]

Hey @DeaconDesperado - this sounds good (though I will as mentioned wait with going over the exact code until we finalize the product stuff).

Including a conversion script is a very nice touch, but assuming we preserve backward compatibility and the existing themes will continue working as expected, I think it's alright. This is mostly meant to allow people to more easily create new themes with greater flexibility.

For the interests of efficiency, I have put aside some time every week on Friday morning CEST to go over this PR. So that you'll know when I'll do the next round and are able to prepare for it. I'll try to be available for quick questions in between so that we can get this going.

What else do you need from me for the time being?

[DeaconDesperado]

@imsnif I didn't find time to put a cap on the sole failing integration test this week, but I was wondering what would be the best way to confirm the outstanding product related points? Would you prefer a description incorporating any changes to what was discussed in #2297 here in the comments, or a separate PR to website repo that includes the user-facing documentation?

In the interest of providing something in time for the Friday review bandwidth you carved out for me (thanks!) I'll try to preemptively give the former here, updated to incorporate all the discussions we've had (this is also what's presently working):

Updated Spec

Wherever colors are specified, they use the existing definition prior to this change, using any of:

• A hexadecimal string
• A triplet of u8 for TrueColor
• A single u8 for a 256 terminal color

A theme consists of a styling block, containing:

StyleDeclarations to configure UI components. Each accepts 6 colors:

• A base color
• 4 emphasis colors (emphasis_1,emphasis_2,emphasis_3,emphasis_4)
• A background color.

Any omitted declarations default to the same fixed colors they would prior to this change (constructed from reverse engineering what named fixed colors mapped to what parts of the UX). In order to make sure the theme is coherent, these declarations cannot be partially defined: if they are specified at all, all 6 colors must be set in them (or return an error at startup). They are:

• text_unselected
• text_selected
• ribbon_unselected
• ribbon_selected
• table_title
• table_cell_unselected
• table_cell_selected
• list_unselected
• list_selected

The following additional StyleDeclarations configure elements of the Zellij UI that are apart from the reusable components. These are distinct from the above only in that they do not accept a background (since for all of them, the text_unselected background would apply). As with above, these default to their existing fixed colors if left undefined, and if they are defined, all colors they expect must be included. They are:

• frame_unselected: Colors the stroke around inactive panes
• frame_selected: Colors the stroke around active panes
• exit_code_success: Colors successful messages for panes started with zellij run
• exit_code_error: Colors error messages for panes started with zellij run

And finally, a key multiplayer_user_colors, which defines ten colors player_1, player_2, player_3 ... player_10. This specification, and the colors within it, are optional. Any omitted will default to the same fixed colors used prior to this change.

Complete example configuration for a named theme

themes {
  my_test_theme {
     styling {
          text_unselected {
              base "#DCD7BA"
              emphasis_1 "#ACD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#16161D"
          }
          text_selected {
              base "#16161D"
              emphasis_1 "#ffa066"
              emphasis_2 "#16161D"
              emphasis_3 "#16161D"
              emphasis_4 "#16161D"
              background "#9CABCA"
          }
          ribbon_unselected     {
              base "#DCD7BA"
              emphasis_1 "#9CABCA"
              emphasis_2 "#7AA89F"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
              background "#363646"
          }
          ribbon_selected {
              base "#16161D"
              emphasis_1 "#ffa066"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#76946A"
          }
          table_title {
              base "#DCD7BA"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
              background "#252535"
          }
          table_cell_unselected {
              base "#DCD7BA"
              emphasis_1 "#DCD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#1F1F28"
          }
          table_cell_selected {
              base "#16161D"
              emphasis_1 "#181820"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#363636"
          }
          list_unselected {
              base "#23CF6D"
              emphasis_1 "#eb34ab"
              emphasis_2 "#eb99ab"
              emphasis_3 "#ebbbab"
              emphasis_4 "#ebddcb"
              background "#1F1F99"
          }
          list_selected {
              base "#ebae34"
              emphasis_1 "#ebcc66"
              emphasis_2 "#fcdd77"
              emphasis_3 "#fddd99"
              emphasis_4 "#ffffff"
              background "#353830"
          }
          frame_unselected {
              base "#DCD8DD"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
          }
          frame_selected {
              base "#76946A"
              emphasis_1 "#C34043"
              emphasis_2 "#C8C093"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
          }
          exit_code_success {
              base "#76946A"
              emphasis_1 "#A3D5D5"
              emphasis_2 "#76946A"
              emphasis_3 "#76946A"
              emphasis_4 "#76946A"
          }
          exit_code_error {
              base "#C34043"
              emphasis_1 "#DCD819"
              emphasis_2 "#C34043"
              emphasis_3 "#C34043"
              emphasis_4  "#C34043"
          }
          multiplayer_user_colors {
              player_1 "#C34043"
              player_2 "#C34043"
              player_3 "#C34043"
              player_4 "#C34043"
              player_5 "#C34043"
              player_6 "#C34043"
              player_7 "#C34043"
              player_8 "#C34043"
              player_9 "#C34043"
              player_10 "#C34043"
          }
    }
  }
}

[imsnif]

Hey @DeaconDesperado - thanks for putting this together. This is great and really helps me reviewing this PR quickly. I appreciate the clear communication and your meticulousness!

This looks really good to me and I hardly have any comments. Just a few things:

Any omitted declarations default to the #2297 (comment) (constructed from reverse engineering what named fixed colors mapped to what parts of the UX). In order to make sure the theme is coherent, these declarations cannot be partially defined: if they are specified at all, all 6 colors must be set in them (or return an error at startup).

To make sure I understand this correctly: an entire component can be omitted from the styling (eg. ribbon_unselected), but if a component is declared, all of its colors need to be set otherwise we get an error, right? (if I got this right - this is perfect).

text_selected

Could we make this apply to the mouse-selection and search results too? These happen here: https://github.com/zellij-org/zellij/blob/main/zellij-server/src/panes/grid.rs#L1088 (and a few lines below in the same function)

frame_selected

Could we also add a frame_secondary (I'm open to suggestions for a better name for this one). This is the color the frame changes to when we are in non-normal/locked mode (eg. pane, tab etc.) to let the user know their keyboard input will not be sent to the terminal pane in this mode. This will also in the future be the color of the frame under the mouse when we add mouse movement event tracking (it'll be something like: the frame under the mouse cursor will be this color, and you'll be able to select it and make it focused with a click and maybe do some other stuff like shift-click for multi-select and whatnot).

Otherwise - this looks very good and I'm happy to go forward with this and start reviewing the implementation once you're ready. Fair warning: I'm in the process of revamping the UI of the status-bar to solve the colliding keybindings issue, so I imagine I'm going to create some chaos there for you. I'll do my best to make it minimal and help with the merge afterwards.

Amazing work! Looking forward to iterating more and getting this merged.

ADDENDUM: I realized I didn't see any reference to this, so just to make sure: the old themes will still work, right? We have to remain backwards compatible (I'm even in favor of allowing theme authors to mix the new component declarations into the old color themes if they want, but this is not a must IMO).

[DeaconDesperado]

@imsnif

To make sure I understand this correctly: an entire component can be omitted from the styling (eg. ribbon_unselected), but if a component is declared, all of its colors need to be set otherwise we get an error, right? (if I got this right - this is perfect).

That's correct. I think it makes the most sense to have theme authors always provide a declaration in full or not at all, since partial application of defaults could lead to weird text / background mismatches.

Could we make this apply to the mouse-selection and search results too?

Could we also add a frame_secondary (I'm open to suggestions for a better name for this one).

I'll add these to the punchlist 😄.

I realized I didn't see any reference to this, so just to make sure: the old themes will still work, right?

Yes, there is a From<Palettte> impl that applies the members of Palette retroactively to all the declarations they would have for a Styling. It runs during configuration bootstrapping in the case that the palette key is in the kdl. The plugin integration is via the protobufs, where a new field was added for these declarations, and another set of bidirectional mappings so that plugins are also kept backward compatible.

Edit: As it is currently, the new vs old styles can't be mixed together and are configured disjointly. If your named theme includes a styling node, it uses the new configuration, then fallback to palette, then to absent.

[imsnif]

Yes, there is a From<Palettte> impl that applies the members of Palette retroactively to all the declarations they would have for a Styling. It runs during configuration bootstrapping in the case that the palette key is in the kdl. The plugin integration is via the protobufs, where a new field was added for these declarations, and another set of bidirectional mappings so that plugins are also kept backward compatible.

Edit: As it is currently, the new vs old styles can't be mixed together and are configured disjointly. If your named theme includes a styling node, it uses the new configuration, then fallback to palette, then to absent.

Hey, I couldn't find the declaration in the link and I'm still not up to speed on the implementation details - so just to make sure (because this is a showstopper and I don't want to needlessly add work for you in the end): if I have an arbitrary file (not included in the Zellij repo) that has the old theme declaration with colors, that works now - will it continue working after this?

It's totally fine if we can't mix these declarations, but if that is the case, let's error if they are mixed.

[DeaconDesperado]

Hmm the link does seem to be broken when highlighting the lines.

Yes, they will continue to work without problem. The old format is just mapped into the new one in memory and at runtime when configuration loads.

[DeaconDesperado]

I believe this should now be ready for review. I added a few test cases to validate the configuration works as expected (and errors under the right conditions).

Per our separate discussion in Discord, I removed any commits I had made to the e2e tests in an effort to get them to work with my local setup (we ran into OSX environment-specific issues). Will rely on the CI/CD feedback for these.

[imsnif]

Hey @DeaconDesperado - first off: fantastic work once again! I had a list of things to check on the compatibility/API level and this implementation passed them with flying colors. The [deprecated] annotation for the protobuffers is a really nice touch (I didn't know such a thing existed).

This looks great all in all - I have a first round of rejects. Let's iterate over this a bit and once we're satisfied I'll do a deeper dive into the code

1. Regarding the styling node in the theme definition

I'm not sure if we discussed this before, but would it be possible to get rid of it and have everything flat? I think it'll be nicer for defining themes, eg.:

  my_test_theme {
    text_unselected {
        base "#DCD7BA"
        emphasis_1 "#ACD7CD"
        emphasis_2 "#DCD8DD"
        emphasis_3 "#DCD899"
        emphasis_4 "#ACD7CD"
        background "#16161D"
    }
    text_selected {
        base "#16161D"
        emphasis_1 "#ffa066"
        emphasis_2 "#16161D"
        emphasis_3 "#16161D"
        emphasis_4 "#16161D"
        background "#9CABCA"
    }
}

2. The tab-bar active tab appears wrong

Using the provided theme example from above, I start Zellij and open a new tab.

3. The new "keygroup separator" needs to be themed as well

Might be able to fold it in to one of the existing theme definitions? Otherwise maybe we can add a separate definition for it. You're more in the weeds on this one, so maybe you have an idea? (the orange ribbon in this screenshot). This screenshot is from when the default_mode is locked, but it will now also show every time you enter a mode that is not "normal" or "locked" with the default settings.

4. The session-manager "New Session" Screen appears wrong

This is a screenshot from the test-theme, notice that the up/down arrows do not appear on the selected row, and also the text is not readable (though the latter might be a specific issue with this theme definition?)

5. The session-manager "Resurrect Session" Screen appears wrong

This might be the same issue as 4, but just wanted to mention it here.

Also, there appears to be a separator between table columns (both in a selected and non-selected row). Can we remove it?

Conclusion

I'm very excited to see this moving forward so consistently. The example theme also looks amazing. Looking forward to the next iteration.

[DeaconDesperado]

Thanks! Once I managed to understand how the plugin API works it felt a bit natural to anticipate certain backward compatibility needs there (it's very nicely designed!)

1

We can remove this, yeah. The thought behind it had been that perhaps there could be a separate node colors where named aliases for colors could be declared to be used instead of repeatedly listing the color codes in for each declaration. Since KDL's schema definition doesn't presently support union types, it also felt maybe a bit more future proof to map a single node directly to a struct in case we ever wanted to do KDL schema validation for the configs and need to add other stuff that's configurable via a theme.

2

Pushed two commits to fix this, quick oversight on my part to not backport the same fix from the UI ribbon component into its separate implementations in tab-bar + compact-bar .

3

This presently uses one of the emphasis colors that would map for orange from the older theme definition: ribbon_selected.emphasis_2. Since it has only a single color with no text overlaid, and is active when a mode is selected, I thought maybe we reuse one of the already existing emphases colors since it's semantically close?

4/5

I suspect the disappearing text is in fact the test theme, if you're testing with the one I pasted in the comment earlier I had to rearrange a few definitions. I'll paste a new one in a following comment.

Will definitely look to collapse that extra space between cells as well.

One other thing: in testing some of the existing themes as-is (dracula) I'm noticing that by prohibiting partial application of colors, we might make it impossible to make some elements keep transparency? EG you must provide a background attribute for table_cell_unselectednow, whereas the preceding designs keep this transparent. The difference is more pronouced when using a terminal with background opacity set < 100%:

Dracula original:

Dracula now:

Perhaps it makes sense to make background optional?

[DeaconDesperado]

Updated test theme

themes {
  test_theme {
     styling {
          text_unselected {
              base "#DCD7BA"
              emphasis_1 "#ACD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#16161D"
          }
          text_selected {
              base "#16161D"
              emphasis_1 "#ffa066"
              emphasis_2 "#16161D"
              emphasis_3 "#16161D"
              emphasis_4 "#16161D"
              background "#9CABCA"
          }
          ribbon_unselected     {
              base "#DCD7BA"
              emphasis_1 "#9CABCA"
              emphasis_2 "#7AA89F"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
              background "#363646"
          }
          ribbon_selected {
              base "#16161D"
              emphasis_1 "#ff0066"
              emphasis_2 "#ffa066"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#76946A"
          }
          table_title {
              base "#DCD7BA"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
              background "#252535"
          }
          table_cell_unselected {
              base "#DCD7BA"
              emphasis_1 "#DCD7CD"
              emphasis_2 "#DCD8DD"
              emphasis_3 "#DCD899"
              emphasis_4 "#ACD7CD"
              background "#1F1F28"
          }
          table_cell_selected {
              base "#16161D"
              emphasis_1 "#181820"
              emphasis_2 "#1A1A22"
              emphasis_3 "#2A2A37"
              emphasis_4 "#363646"
              background "#DCD7BA"
          }
          list_unselected {
              base "#23CF6D"
              emphasis_1 "#eb34ab"
              emphasis_2 "#eb99ab"
              emphasis_3 "#ebbbab"
              emphasis_4 "#ebddcb"
              background "#1F1F99"
          }
          list_selected {
              base "#ebae34"
              emphasis_1 "#ebcc66"
              emphasis_2 "#fcdd77"
              emphasis_3 "#fddd99"
              emphasis_4 "#ffffff"
              background "#353830"
          }
          frame_unselected {
              base "#DCD8DD"
              emphasis_1 "#7FB4CA"
              emphasis_2 "#A3D4D5"
              emphasis_3 "#7AA89F"
              emphasis_4 "#DCD819"
          }
          frame_selected {
              base "#76946A"
              emphasis_1 "#C34043"
              emphasis_2 "#C8C093"
              emphasis_3 "#ACD7CD"
              emphasis_4 "#DCD819"
          }
          frame_highlight {
              base "#DCD819"
              emphasis_1 "#DCD819"
              emphasis_2 "#DCD819"
              emphasis_3 "#DCD819"
              emphasis_4 "#DCD819"
          }
          exit_code_success {
              base "#76946A"
              emphasis_1 "#A3D5D5"
              emphasis_2 "#76946A"
              emphasis_3 "#76946A"
              emphasis_4 "#76946A"
          }
          exit_code_error {
              base "#C34043"
              emphasis_1 "#DCD819"
              emphasis_2 "#C34043"
              emphasis_3 "#C34043"
              emphasis_4  "#C34043"
          }
          multiplayer_user_colors {
              player_1 "#C34043"
              player_2 "#C34043"
              player_3 "#C34043"
              player_4 "#C34043"
              player_5 "#C34043"
              player_6 "#C34043"
              player_7 "#C34043"
              player_8 "#C34043"
              player_9 "#C34043"
              player_10 "#C34043"
          }
    }
  }
}

[imsnif]

Hey, took this for another spin and all the issues seem good to me! I replied in-line to the frame-highlight issue. Otherwise, I ran the CI again and if all is well I'm going to give this another week to see if we get any comments from @dj95 (no pressure at all!!) and then I'm happy to merge.

After this is merged, I'll write up some documentation for this and would be happy to get your input if you'd be up for it.

EDIT: seems like we have another snapshot to update: https://github.com/zellij-org/zellij/actions/runs/13020325545/job/36471935504?pr=3242#step:11:2117

[dj95]

Hi, first of all, thanks a lot for asking me for feedback. I really appreciate that. It's one of the favorite features, I wish for a long time for. It looks awesome and I had a lot of fun tinkering around with the theme spec while testing it.

In the first tests, I've tested zjstatus (my status bar plugin with some custom rendering), which works totally fine. No issues at all.

However, I've found some smaller issues within the ui components. If there's something I did wrong on my end, please don't hesitate to point it out. I can also provide the code for testing it, in case you are interested.

.opaque() is not working properly

UI components implement a .opaque() function, to explicitly draw the background explicitly. This will help with terminals, that draw the background when it's set, as some behave different when the background color is the same as the transparent background color of the terminal. More details can be found it the following pr: #3681 .

With the new theme spec pull request, some of the ui components do not draw the opaque background anymore. I've used my default zellij config (with a modified gruvbox theme) and the dracula theme spec from within this pull request. Both produced the issue.

On the left side is the new version from this pull request, on the right side the current zellij release.

Ribbons do not seem to render properly

As the screenshot also depicts, ribbons do not seem to render correctly with the ui components. The orange foreground in ribbon 2 is due to my theme change, so that's not an issue :D it's just that the end-chars of the power line arrows do not seem to render correctly. The last arrow also somehow got extended by another empty space.

Table rows without any style have another color

This one might not be an issue, but a good behavior change. I just want to mention it because I've noticed, that it differs from the current behavior of the main branch. The first row of the table in the screenshot on the left now uses the foreground color instead of the orange (or green from the default theme).

---

For reference, here's the config and the code:

config.kdl

theme "test_theme"
themes {
  test_theme {
    fg 235 219 178
    bg "#504945"
    black "#3c3836"
    red "#cc241d"
    green "#d79921"
    yellow "#d79921"
    blue "#458588"
    magenta "#b16286"
    cyan "#689d6a"
    white "#fbf1c7"
    orange "#d79921"

    // text_unselected {
    //         base 255 255 255
    //         background 0 0 0
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     text_selected {
    //         base 255 255 255
    //         background 40 42 54
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     ribbon_selected {
    //         base 0 0 0
    //         background 80 250 123
    //         emphasis_0 255 85 85
    //         emphasis_1 255 184 108
    //         emphasis_2 255 121 198
    //         emphasis_3 98 114 164
    //     }
    //     ribbon_unselected {
    //         base 0 0 0
    //         background 248 248 242
    //         emphasis_0 255 85 85
    //         emphasis_1 255 255 255
    //         emphasis_2 98 114 164
    //         emphasis_3 255 121 198
    //     }
    //     table_title {
    //         base 80 250 123
    //         background 0
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     table_cell_selected {
    //         base 255 255 255
    //         background 40 42 54
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     table_cell_unselected {
    //         base 255 255 255
    //         background 0 0 0
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     list_selected {
    //         base 255 255 255
    //         background 40 42 54
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     list_unselected {
    //         base 255 255 255
    //         background 40 42 54
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 80 250 123
    //         emphasis_3 255 121 198
    //     }
    //     frame_selected {
    //         base 80 250 123
    //         background 0
    //         emphasis_0 255 184 108
    //         emphasis_1 139 233 253
    //         emphasis_2 255 121 198
    //         emphasis_3 0
    //     }
    //     frame_unselected {
    //         base 7
    //         background 0
    //         emphasis_0 0
    //         emphasis_1 0
    //         emphasis_2 0
    //         emphasis_3 0 0 0
    //     }
    //     frame_highlight {
    //         base 255 184 108
    //         background 0
    //         emphasis_0 255 184 108
    //         emphasis_1 255 184 108
    //         emphasis_2 255 184 108
    //         emphasis_3 255 184 108
    //     }
    //     exit_code_success {
    //         base 80 250 123
    //         background 0
    //         emphasis_0 139 233 253
    //         emphasis_1 0 0 0
    //         emphasis_2 255 121 198
    //         emphasis_3 98 114 164
    //     }
    //     exit_code_error {
    //         base 255 85 85
    //         background 0
    //         emphasis_0 241 250 140
    //         emphasis_1 0
    //         emphasis_2 0
    //         emphasis_3 0
    //     }
    //     multiplayer_user_colors {
    //         player_1 255 121 198
    //         player_2 98 114 164
    //         player_3 0
    //         player_4 241 250 140
    //         player_5 139 233 253
    //         player_6 0
    //         player_7 255 85 85
    //         player_8 0
    //         player_9 0
    //         player_10 0
    //     }
    }
}

session_serialization false
serialization_interval 1

keybinds {
  tmux {
    bind "Ctrl a" { Write 1; SwitchToMode "Normal"; }
    bind "[" { SwitchToMode "Scroll"; }
    bind "-" { NewPane "Down"; SwitchToMode "Normal"; }
    bind "|" { NewPane "Right"; SwitchToMode "Normal"; }
    bind "1" { GoToTab 1; SwitchToMode "Normal"; }
    bind "2" { GoToTab 2; SwitchToMode "Normal"; }
    bind "3" { GoToTab 3; SwitchToMode "Normal"; }
    bind "4" { GoToTab 4; SwitchToMode "Normal"; }
    bind "5" { GoToTab 5; SwitchToMode "Normal"; }
    bind "6" { GoToTab 6; SwitchToMode "Normal"; }
    bind "7" { GoToTab 7; SwitchToMode "Normal"; }
    bind "8" { GoToTab 8; SwitchToMode "Normal"; }
    bind "9" { GoToTab 9; SwitchToMode "Normal"; }
    bind "0" { GoToTab 10; SwitchToMode "Normal"; }
  }
  shared_except "tmux" "locked" {
    bind "Ctrl a" { SwitchToMode "Tmux"; }
  }
}


plugins {
  zjstatus location="file:/Users/daniel/Developer/Rust/zjstatus/target/wasm32-wasip1/release/zjstatus.wasm" {
    hide_frame_for_single_pane "true"

    // catppuccin
    color_bg     "#0e0801"
    color_fg     "#9399B2"
    color_fg_dim "#6C7086"
    color_blue   "#89b4fa"
    color_orange "#ffc387"

    // gruvbox-dark
    color_bg     "#1d2021"
    color_fg     "#ebdbb2"
    color_fg_dim "#928374"
    color_orange "#fe8019"

    // rose-pine
    // color_bg     "#33362E"
    // color_fg     "#9ccfd8"
    // color_fg_dim "#56949f"
    // color_blue   "#31748f"
    // color_orange "#f6c177"

    format_left  "#[fg=$fg,bg=$bg,bold] {session}#[bg=$bg] {tabs}"
    format_right "{notifications}{command_aws}{command_kubectx}{command_kubens}{datetime}"
    format_space "#[bg=$bg]"

    notification_format_unread           "#[fg=$blue,bg=$bg,blink]  #[fg=$blue,bg=$bg] {message} "
    notification_format_no_notifications ""
    notification_show_interval           "10"

    mode_normal          "#[bg=$blue] "
    mode_tmux            "#[bg=$orange] "
    mode_default_to_mode "tmux"

    tab_normal               "#[fg=$fg_dim,bg=$bg] {index} {name} {fullscreen_indicator}{sync_indicator}{floating_indicator}"
    tab_active               "#[fg=$fg,bg=$bg,bold] {index} {name} {fullscreen_indicator}{sync_indicator}{floating_indicator}"
    tab_sync_indicator       " "
    tab_fullscreen_indicator "󰊓 "
    tab_floating_indicator   "󰹙 "

    command_kubectx_command  "${pkgs.kubectx}/bin/kubectx -c"
    command_kubectx_format   "#[fg=$fg_dim,bg=$bg,italic]{stdout}#[fg=#424554,bg=$bg]::"
    command_kubectx_interval "2"

    command_kubens_command  "${pkgs.kubectx}/bin/kubens -c"
    command_kubens_format   "#[fg=$fg_dim,bg=$bg]{stdout} "
    command_kubens_interval "2"

    command_aws_command    "${pkgs.fish}/bin/fish -c 'if test $AWS_PROFILE; echo -n \"#[fg=#928374,bg=#1d2021,italic]aws#[fg=#424554,bg=#1d2021]::#[fg=#928374,bg=#1d2021]$AWS_PROFILE  \"; end'"
    command_aws_format     "{stdout}"
    command_aws_interval   "2"
    command_aws_rendermode "dynamic"

    datetime          "#[fg=$fg,bg=$bg] {format} "
    datetime_format   "%A, %d %b %Y %H:%M"
    datetime_timezone "Europe/Berlin"
  }
}

main.rs of the test plugin

use zellij_tile::prelude::*;

use serde::{Deserialize, Serialize};
use std::{collections::BTreeMap, path::Path};

register_plugin!(State);
register_worker!(Worker, test_worker, WORKER_NAME);

#[derive(Default, Serialize, Deserialize)]
struct Worker {}

impl ZellijWorker<'_> for Worker {
    fn on_message(&mut self, message: String, payload: String) {
        eprintln!("message!! {message} {payload}");
    }
}

#[derive(Default)]
struct State {
    hidden: bool,
}

impl ZellijPlugin for State {
    fn pipe(&mut self, pipe_message: PipeMessage) -> bool {
        eprintln!("{pipe_message:?}");
        false
    }
    fn load(&mut self, _configuration: BTreeMap<String, String>) {
        request_permission(&[
            PermissionType::ReadApplicationState,
            PermissionType::ChangeApplicationState,
            PermissionType::MessageAndLaunchOtherPlugins,
            PermissionType::ReadCliPipes,
        ]);
        subscribe(&[EventType::PermissionRequestResult, EventType::Key]);

        self.hidden = false;
    }

    fn update(&mut self, event: Event) -> bool {
        match event {
            _ => {}
        }
        true
    }

    fn render(&mut self, _rows: usize, _cols: usize) {
         let table = Table::new()
             .add_row(vec!["title1", "title2", "title3"])
             .add_styled_row(vec![
                 Text::new("cell").color_range(0, 1..5),
                 Text::new("cell").color_range(2, ..),
                 Text::new("cell"),
             ])
             .add_styled_row(vec![
                 Text::new("cell.opaque()").opaque(),
                 Text::new("cell.selected()").selected(),
                 Text::new("cell.selected().opaque()").selected().opaque(),
             ]);
         print_table(table);
        
         print_ribbon_with_coordinates(
             Text::new("ribbon 1").color_range(0, 1..5),
             0,
             5,
             Some(12),
             None,
         );
         print_ribbon_with_coordinates(
             Text::new("ribbon 2").color_range(1, 1..5).selected(),
             12,
             5,
             Some(12),
             None,
         );
         print_ribbon_with_coordinates(
             Text::new("ribbon 3").color_range(2, 1..5),
             24,
             5,
             Some(12),
             None,
         );
         print_ribbon_with_coordinates(
             Text::new("ribbon 4").color_range(3, 1..5),
             36,
             5,
             Some(12),
             None,
         );
        
         print_nested_list_with_coordinates(
             vec![
                 NestedListItem::new("item")
                     .indent(1)
                     .color_range(0, 1..15)
                     .color_indices(1, vec![8]),
                 NestedListItem::new("item.opaque()")
                     .color_range(1, ..)
                     .color_range(3, 10..25)
                     .color_indices(1, vec![8])
                     .opaque(),
                 NestedListItem::new("item.selected()")
                     .color_range(2, ..)
                     .color_range(3, 5..20)
                     .color_indices(1, vec![8])
                     .selected(),
                 NestedListItem::new("item.selected().opaque()")
                     .indent(1)
                     .color_range(0, ..)
                     .color_range(1, 1..15)
                     .color_indices(1, vec![8])
                     .selected()
                     .opaque(),
             ],
             1,
             7,
             None,
             None,
         );
        
         let text = Text::new("text")
             .color_range(0, 0..=2)
             .color_range(1, 3..=5)
             .color_range(2, 7..=9);
         print_text_with_coordinates(text, 0, 13, None, None);
        
         let text = Text::new("text.opaque()")
             .color_range(0, 0..=2)
             .color_range(1, 3..=5)
             .color_range(2, 7..=9)
             .opaque();
         print_text_with_coordinates(text, 0, 14, None, None);
        
         let text = Text::new("text.selected()")
             .color_range(0, 0..=2)
             .color_range(1, 3..=5)
             .color_range(2, 7..=9)
             .selected();
         print_text_with_coordinates(text, 0, 15, None, None);
        
         let text = Text::new("text.selected().opaque() # should default to selected")
             .color_range(0, 0..=2)
             .color_range(1, 3..=5)
             .color_range(2, 7..=9)
             .selected();
         print_text_with_coordinates(text, 0, 16, None, None);
    }
}

---

Thanks again for your awesome work on this pull request! Feel free to ask any questions in case you need any further details.

[DeaconDesperado]

EDIT: seems like we have another snapshot to update: https://github.com/zellij-org/zellij/actions/runs/13020325545/job/36471935504?pr=3242#step:11:2117

Yes looks like this is during the e2e test suite... I've only been triggering tests with cargo xtask test. I think awhile back I had some issues running the e2e tests on OSX, will give another try else manually update the snapshot.

[imsnif]

No worries @DeaconDesperado - please don't update the snapshots manually, it's a lot of needless meticulous work. If it comes to it I'll do it.

If you could take a look at the issues @dj95 found though, that would be great.

[DeaconDesperado]

Hey @dj95 I really appreciate you giving this a go and for the kind words on the implementation 😄

1. I have pushed up a fix for this. It was a combination of a wrong translation of a color (bg -> black for tables and lists in unselected mode) and a missing branch for handling opaque in table specifically. Thanks for that catch!
2. I added a fix for this as well... just needed to correct the padding to get explicit widths set right.
3. This is by design, as the first row is styled with table_title. When using an older theme definition, this should use the color specified as green in the config for the text color. This is to match the existing implementation. It looks like in your custom theme you have this color set equivalently to yellow + orange?

With fixes + demo for ribbon positioning using your plugin source code:

Screenshot

@imsnif I didn't manage to get the e2e tests running to generate that specific insta snapshot. Would def appreciate if you could add that commit for me... I looked through the others in there and it seemed to be just that one test that logs out the Palette.

[dj95]

Awesome! Thanks a lot for your quick fix @DeaconDesperado . Now it looks exactly the same.

[DeaconDesperado]

Pushed up a fix for the optional styling of frame_unselected. I also wanted to leave a quick note on the second new commit above, as it resulted from @dj95's feedback, and I believe it may resolve an existing ambiguity in the API?

When setting an explicit width for a ribbon with print_ribbon_with_coordinates, the width value is now inclusive of any padding added (whitespace + arrow chars if enabled). This has the effect that width dictates the total width of the element and not just the text within it, so the existing fixture with value of 10 would wrap too early and cut off the 1 in ribbon 1 (and so has been corrected to be wider).

I think this is the correct behavior, matching also what @dj95 as a user expected. But it bears mention there's nowhere I could find in the zellij codebase where the explicit width setting is used. It did seem that for several components though, there is a habit of adding 4 to y offsets to accommodate for the extra characters, which would match in terms of intention (2 chars of padding on either side, 1 whitespace and 1 of either whitespace or arrows depending on the --simplified-ui setting). This also renders consistently when arrow chars are enabled or disabled, and matches the existing behaviors for ribbons in the configuration plugin for both of those settings in the current version of Zellij.

[dj95]

Im not sure if I understood your comment 100%. But in the plugin code, I set the width to 12, which includes the chars for the arrow itself, as the string "ribbon 1" contains 8 chars und you then need 1 for spacing and 1 for the arrow on each side.

But I agree, that it's much more intuitive, when you just need to specify the text width and do not keep the 4 extra chars for the arrow around it in mind. Although this would impose a breaking change in the behavior of the UI components.