Thanks for the bug report. Could you clarify something? In your steps to reproduce, in #1, you say to use the first config with the us file.

Then in step #4, you say to exit the file, but that is after logging out and back in, I assume kate was opened automatically on your system with that file?
Also, in step #4 you say "VariantList is set to custom" but I don't see that in the config you pasted.

Can you please paste the full text of what should be in ~/.config/xkb/symbols/us?
Also, can you attach a screenshot of it appearing in your keyboard layout list?

Thanks.

Sorry, there should be "Edit" instead of "Exit", my bad. Here are the files:

==== /home/damglador/.config/xkb/symbols/us ====
default partial alphanumeric_keys
xkb_symbols "custom" {
    include "us(basic)"
    name[Group1]= "English (Custom)";
    key <AE01>  {[               1,          exclam,    onesuperior                      ]};
    key <AE02>  {[               2,              at,    twosuperior,               U2019 ]};
    include "level3(ralt_switch)"
    
};

======== ~/.config/kxkbrc ========
[Layout]
CurrentLayout=2
DisplayNames=,
LayoutList=us,ua
LayoutLoopCount=2
Options=grp:shift_caps_toggle,grp:caps_toggle
ResetOldOptions=true
Use=true
VariantList=custom,custom


From my understanding, a file like /usr/share/X11/xkb/rules/evdev.extras.xml or /usr/share/X11/xkb/rules/evdev.xml might be required for it to show up in settings, but 
1. I don't think it reads ~/.config/xkb/rules/evdev.extras.xml, at least in my testing it didn't, maybe I did something wrong. 
2. Docs don't mention it https://community.kde.org/Plasma/Wayland#Custom_keyboard_maps_(XKB) 
3. Holy jeez it makes it so complicated. Would be much nicer if settings just picked up all these custom layouts and put them wherever in the list, and I think they should do that, because there is group named "A user-defined custom Layout", but it only contains one broken layout.

Created attachment 181086 [details]
A user-defined custom Layout

Created attachment 181087 [details]
Search for "Custom" layouts in the list

Here it should've found my two layouts, us(custom) and ua(custom) which are named name[Group1]= "English (Custom)"; and name[Group1]= "Ukrainian (Custom)"; respectively. But at the same time, these names are pulled by the language switcher tray and toast when these layouts are manually set in ~/.config/kxkbrc.

Thanks for clarifying and providing the file details. I am able to reproduce this behavior on git-master
1. The custom layout is listed as "A user-defined custom Layout" in Add Layout, and it isn't listed in the defined group
2. The error when trying to preview it

The keyboard geometry failed to load. This often indicates that the selected model does not support a specific layout or layout variant.... 

Keycodes above 256 (e.g. <I256>) are not supported by X and are ignored
Error:            Can't find file "custom" for symbols include
                  Exiting
                  Abandoning symbols file "(null)"

For me the "A user-defined custom Layout" is only one, when I have 2 custom layouts. It is also completely broken, if I add it to my keyboard layout list and apply, the tray icon for displaying current keyboard layout disappears and I can't switch keyboard layouts.

I've added custom layouts like this in the past and it worked, so either the specific way you're doing it isn't working in the KCM, or else your custom layout is broken.

- ~/.config/xkb/symbols/us replaces the *default* US layout, because 1) it has the same file name 2) of the “default” in “default partial alphanumeric_keys xkb_symbols "custom"”
- ~/.config/xkb/symbols/ua: same, but for the default Ukrainian layout

You do not see “English (Custom)” in the Plasma config because it loads the info from /usr/share/X11/xkb/rules/evdev.xml, unless you provided a custom ~/.config/xkb/rules/evdev.xml. The entry in the system XML file has label “English (US)”.

However, your config loads correctly: check that the layout switcher widget displays e.g. “English (Custom)”, because the switcher uses the data from the symbols files.

The “Custom” layout labelled as “A user-defined custom Layout” is yet another feature and uses  /usr/share/X11/xkb/symbols/custom, that *is not shipped* by xkeyboard-config. So if you did not created this file, it does not exist, and selecting this entry will break your config! Note that this feature is a hack aimed at X11 users. Under Wayland you should use the ~/.config/xkb files.

So in order to config your custom files and have them correctly labelled, you need:
1. Replace your ~/.config/xkb/symbols/us file (same for the ua) with:

// Required to fix https://github.com/xkbcommon/libxkbcommon/issues/726, unless using libxkbcommon 1.9+
default partial alphanumeric_keys xkb_symbols { include "us(basic)" };

partial alphanumeric_keys 
xkb_symbols "custom" {
    include "us(basic)"
    name[Group1]= "English (Custom)";
    key <AE01>	{[               1,          exclam,    onesuperior                      ]};
    key <AE02>	{[               2,              at,    twosuperior,               U2019 ]};
    include "level3(ralt_switch)"  
};

2. Add a ~/.config/xkb/rules/evdev.xml file following these instructions: https://xkbcommon.org/doc/current/user-configuration.html#discoverable-layouts for both your layouts:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
<xkbConfigRegistry version="1.1">
  <layoutList>
    <layout>
      <configItem>
        <name>us</name>
      </configItem>
      <variantList>
        <variant>
          <configItem>
            <name>custom</name>
            <shortDescription>us</shortDescription>
            <description>English (custom)</description>
          </configItem>
        </variant>
      </variantList>
    </layout>
    <layout>
      <configItem>
        <name>ua</name>
      </configItem>
      <variantList>
        <variant>
          <configItem>
            <name>custom</name>
            <shortDescription>ua</shortDescription>
            <description>Ukrainian (custom)</description>
          </configItem>
        </variant>
      </variantList>
    </layout>
  </layoutList>
</xkbConfigRegistry>


I added a link to the reference documentation of libxkbcommon in the KDE wiki.

Thanks so much for your exhaustive answer! I had a feeling it was a setup issue.

(In reply to Nate Graham from comment #9)
> Thanks so much for your exhaustive answer! I had a feeling it was a setup
> issue.

The wiki ought to be updated to include the step with the XML file (+ the issue I mentioned), so that the user can use the GUI to configure their keyboard config.

I.e. providing a *complete* example of a small variant of a standard layout (e.g. US for illustration), which is probably the most common scenario, like the current issue.

Is it possible to avoid the need of an xml file for keyboards to be discoverable?

(In reply to Damglador from comment #11)
> Is it possible to avoid the need of an xml file for keyboards to be
> discoverable?

No, it is mandatory to make it appear in the GUI for keyboard config. But it is not necessary if you use the same id of an exisiting variant. I do not advise it though, as this issue shows it is then confusing.