Definition of component groups

[Frizi]

The methods and constructors in the library are supposed to be grouped into categories, such that it is easier to search for them in the component browser. Currently, those component groups are defined as part of package.yaml file in each library module. For example, the Table module contains a definition like this:

component-groups:
  extends:
    - Standard.Base.Input:
        exports:
          - Standard.Table.Data.Table.Table.new
          - Standard.Table.Data.Table.Table.from_rows
          - Standard.Table.Data.Table.Table.from_objects
          - Standard.Table.Data.Column.Column.from_vector
    - Standard.Base.Select:
        exports:
          - Standard.Table.Data.Table.Table.at
          - Standard.Table.Data.Table.Table.get
          - Standard.Table.Data.Table.Table.select_columns
          - Standard.Table.Data.Table.Table.remove_columns
          - Standard.Table.Data.Table.Table.reorder_columns
          - Standard.Table.Data.Table.Table.sort_columns

The definition is supposed to contain a list of methods, and possibly a color that should be used for given group visually.

There are a few problems with this approach:

• The maitenance of this definition file is quite cumbersome. It is separate from the library code itself, so every time a method is created or moved around, the package.yaml file needs to be updated. It is also easy to forget a method on this list, or to figure out something is missing.
• There is a separate language server API needed to query that data, which is separated from the suggestion database. We end up having two sources of rougly related inforamtion, one is project-scoped, and another is per execution context. Given that now the graph nodes will need to query for a group of their main method to decide their color, it becomes an issue.
• The color definition itself is not really well suited for being defined in the library. It is not clear what colors are "safe" to use, since the IDE theme is dynamic (and will eventually be somewhat user-editable). Additionally, because group definitions can be repeated between modules (and their exports needs to be merged together), that color definition can be ambiguous when it is defined differently in many places.
• The order of exports is not strictly defined. While we have a known order in given file, it is not clear in which order should the export lists be combined when they appear in multiple modules.

Proposed change

I would like to propose a different approach to solve this. Instead of defining that information in separate file, we could annotate the methods themselves, similarly to how we deal with icons and aliases right now.

Assigning items to groups

Ideally, we would use method annotations for this, but that would require dealing with widget definitions slightly differently. In the long run we would probably want the definition to look something like this:

    ## UNSTABLE

       Returns the column with the given name.

       Arguments:
       - selector: The name or index of the column to get.
    @group Select
    @icon select_column
    @widget selector Widget_Helpers.make_column_name_selector
    at : Text | Integer -> Column ! No_Such_Column | Index_Out_Of_Bounds

Given that currently the annotations are always interpreted as widget for argument of given name, we can't use them for anything else without significant changes. I propose that we temporarily use the documentation tags to accomplish the same goal. When the time comes to move to actual annotations, the transition could be performed by an automated script.

    ## UNSTABLE
       GROUP Select
       ICON select_column

       Returns the column with the given name.

       Arguments:
       - selector: The name or index of the column to get.
    @selector Widget_Helpers.make_column_name_selector
    at : Text | Integer -> Column ! No_Such_Column | Index_Out_Of_Bounds

Order within groups

With current system, the order of items within the group is defined, as long as the group is defined only in a single module. When multiple libraries are using the same group, the order between them is not clear. Therefore I believe that splitting the group definition to be per-method doesn't really make this more complicated. We just have to define the desired behavior.

By default, we can sort the items alphabetically by their display name within each group. In case we would want to retain some forced ordering, we could add additional notion of "group priority". Items of higher priority would be presented at the start of each group, and the alphabetical order would be used as a secondary ordering method. It could be defined as part of the tag, for example like this:

         GROUP Select #10

Though the exact syntax is not really important at this stage, as long as the contept holds.

Group color

Given that there is now no central place where group properties could be defined, the library has no good place to assign a color to the group. Though given that the IDE theme can be modified, I believe that it wasn't a good place to defined it to begin with anyway. Instead we could use a combination of automatic color assignment based on group name, and then use the IDE theme system to allow overriding that.

• If a color for a group of given name is defined within the IDE theme, it is directly used. That way we would be able to declare the colors for our builtin groups however we like, by declaring them in the hardcoded IDE theme. Eventually, once the theme is modifiable and persisted through user settings, the users could tweak their own group colors however they like.
• When the theme doesn't contain the group, the default color would be autogenerated. It would be selected by the IDE purely based on the group's name, and potentially taking existing theme settings into account (e.g. to guarantee appropriate contrast). The exact method of selecting that is not really important, as long as it is a form of stable color hashing (same group name implies same color in given environment).
• Eventually, it could also be possible to use the package.yaml file in order to contribute the default theme values to the IDE project session, if we wish to allow the library to define the color in some way.

With all of the above changes, we could completely remove the executionContext/getComponentGroups API endpoint.

[farmaazon]

Bringing @wdanilo attention, as this affects the initial design

[Frizi]

@wdanilo the issues with group definitions (especially around colors and ordering) are a bit beyond the scope of what we discussed, as I found more issues when thinking about it. But the main idea of keeping it all within the method annotations/doctags still holds.

[wdanilo]

I will carefully think about it and propose something in the doc. I will ping you when that will be ready!

[jdunkerley]

The GROUP as a doc tag looks good to me.

We should not match the ordering and colour with the method tagging. The colouring also feels like a property of the IDE but I will wait for @wdanilo suggestion.

[wdanilo]

@jdunkerley @farmaazon @Frizi I added description of these things to the Component Browser update doc: https://github.com/enso-org/design/pull/56 . Could you look there as well, please? I think I merged the proposed changes from this thread there. Of course, this doc describes the approach we are heading for and I'm totally fine with keeping some things in docs instead of in pragmas for now in order to implement it faster.

[wdanilo]

@Frizi, regarding group colors, I believe that they should be defined within libraries that define the groups. People defining libraries might want to associate some of the groups with some colors. For example, network things probably should be in a bluish group, as the blue color is inherently connected with network and cloud in graphics design. Color is an important part of the design and should compliment the API design. So I believe that automatic color generation based on name would not work here. We also want to provide explicit colors for our groups in order to provide the user with the right feeling within the app.

[wdanilo]

Regarding group ordering – I think that group ordering is a pretty important things nad in most cases the library author would like to provide explicit group ordering. There is even a design created by James about what is the best ordering of our groups, you can see it here: https://jdunkerley.github.io/enso-react . Basically, I believe that having a single place in a library to define all groups, their ordering and colors is the best approach. It has also several benefits:

1. If we would like to add to GUI ability to define / reorder groups, it would be straightforward having them in package.yaml.
2. If someone mistypes the group name in pragma, like @group foo, if foo does not exist, a warning should be emitted. Otherwise it is too easy to create groups by accident.

[farmaazon]

I think one important thing is missing from the new design: namely, how the order of the groups (not their content) will be specified? For example, we always want to show Input/Output as the "nearest" group after opening CB.

[wdanilo]

It's proposed in my doc: https://github.com/enso-org/design/pull/56