Mapped option closeOnEscape doesn't work as expected

which was incorrectly mapped to the "modal" option

Why is it "incorrect"?

Instead of being ignored, the "backdrop" option from theme config should be mapped to the "backdrop" pass-through options.

I'm still not following. How does "theme config" make its way into this scenario? This file is the modal.jquery.ui.bridge.js code. Meaning that it's only intent is to map jQuery UI options (e.g. options.modal) to the supported Bootstrap options (e.g. mappedOptions.backdrop). There is no options.backdrop, or at least there shouldn't be.

If whatever code that implements said jQuery UI dialog options doesn't explicitly provide the modal option, then it falls back to what the theme config specifies.

If anything, I think the real "issue" here is that there needs to be a disclaimer stating something to the effect of: "Note: these settings may be manually overridden depending on which options were explicitly specified by the code from core/contrib and then mapped using the jQuery UI Bridge."

I think you're missing the point...

If options.modal is provided at all, it is an explicit override. jQuery UI doesn't have the concept of a "static" backdrop. Thus, whatever was set in via the theme settings is irrelevant.

Or, why does "closeOnEscape" have special treatment for the "modal" option, but not vice versa?

Because, "static" really only comes into play when the closeOnEscape jQuery UI dialog option is explicitly specified.

As you can see, it explicitly sets options.modal to static which is later mapped again:

if (!options.closeOnEscape && options.modal) {
  mappedOptions.backdrop = options.modal = 'static';
}

This is because jQuery UI's "modals" can, by default, be closed by clicking on the backdrop. The default functionality is not the same as Bootstrap's. The reason this doesn't just assume "static" is that the modal itself may not be constructed (from code/dialog options) to include a closing mechanism of some sort. Thus, the only way to actually "close" the modal is to click the backdrop.

If you want to ensure that that the modal is truly "static", add the following attribute data-dialog-options="{"closeOnEscape":false}" so it triggers the above code the way it was designed.

I'm not saying this is 100% "perfect" or "ideal", but there are simply limitations to bridges. This is one of them.

Furthermore, it is a bridge that is specifically designed to ensure that jQuery UI's dialog options are accounted for, not Bootstraps.

I'm already using that option and it's always subsequently overwritten by the "modal" option case handling.

No, it's not "overwritten". They're the same. Please re-read my previous comment and the if statement logic.

That... shouldn't be happening.

Core uses jQuery's data method to parse the options:
http://cgit.drupalcode.org/drupal/tree/core/misc/ajax.js#n129

And as you can see here, it's parsed as a boolean, not a string:
https://codepen.io/markcarver/pen/zaEmKo?editors=1011

I'm experiencing the same issue using a Bootstrap sub theme.

#12 still allows closing by clicking on the backdrop:

data-dialog-options="{"closeOnEscape":false}"

#17 prevents modal from being closed by clicking on the backdrop:

data-dialog-options="{"closeOnEscape":""}"

This option also hides the close button "X" in the top right, which may be normal behaviour but I was hoping to keep it.

In case it matters how the link is generated:

      $build['modal_link'] = [
        '#type' => 'inline_template',
        '#template' => '{{ mytemplate|raw }}',
        '#context' => [
          'mytemplate' => '<a class="btn btn-primary use-ajax" data-dialog-options="{&quot;dialogClass&quot;:&quot;my-class&quot;,&quot;title&quot;:&quot;Modal Title&quot,&quot;closeOnEscape&quot;:&quot;&quot;}" data-dialog-type="modal" href="/my/path">Modal Link</a>',
        ]
      ];

First... why would you create a link like that?! That is a horrible way to do that.

Inline templates are only meant for user (GUI) based templates (think views field rewrites). They're not intended to be a replacement for actual Twig templates. Also, you're already in PHP, where you can use the proper #type:

  $dialogOptions = [
    'dialogClass' => 'my-class', // Deprecated BTW, really shouldn't be using it.
    'title' => t('Modal Title'),
    'closeOnEscape' => FALSE,
  ];

  $build['modal_link'] = [
    '#type' => 'link',
    '#title' => t('Modal Link'),
    '#url' => Url::fromUserInput('/my/path'),
    '#attributes' => [
      'class' => ['btn', 'btn-primary', 'use-ajax'],
      'data-dialog-options' => Json::encode($dialogOptions),
      'data-dialog-type' => 'modal',
    ],
  ];

Second... the primary issue, in this issue, is that setting closeOnEscape to an actual false boolean doesn't work. I've determined that this is actually a legitimate core bug: #3014136: Opening dialog via AJAX casts dialogOptions values to strings.

I'm leaving this issue open, however, because I still think some general verbiage needs to be added to better explain how options are mapped.

Yeah it's not pretty. It's actually mixed up with some Vuejs, which could also be extracted.

Thanks for the update, I'll check out the core issue.

I've been going over the code (and previous examples given) and think there could be a little better support while waiting on #3014136: Opening dialog via AJAX casts dialogOptions values to strings.