Skip to content

A platform for community discussion. Free, open, simple.

UX: Add an optional footer slot to DMultiSelect (#45329)

Krzysztof Kotlarek6ce0725dcc87
diff --git a/app/assets/stylesheets/common/components/d-multi-select.scss b/app/assets/stylesheets/common/components/d-multi-select.scss
index 46ec8818fa2..b4356ec7c84 100644
--- a/app/assets/stylesheets/common/components/d-multi-select.scss
+++ b/app/assets/stylesheets/common/components/d-multi-select.scss
@@ -160,3 +160,33 @@
}
}
}
+
+.fk-d-menu.d-multi-select-menu--with-footer .fk-d-menu__inner-content {
+ overflow-x: clip;
+}
+
+.d-multi-select__content.--with-footer {
+ box-sizing: border-box;
+ min-width: 0;
+ max-width: 100%;
+ max-height: calc(100dvh - 2rem);
+ overflow: hidden;
+
+ .d-multi-select__search-results {
+ flex: 0 1 auto;
+ height: auto;
+ max-height: min(18rem, 40dvh);
+ min-height: 0;
+ overflow-y: auto;
+ overscroll-behavior: contain;
+
+ > .d-multi-select__result {
+ flex-shrink: 0;
+ }
+ }
+}
+
+.d-multi-select__footer {
+ background: var(--secondary);
+ flex-shrink: 0;
+}
diff --git a/docs/developer-guides/docs/03-code-internals/02-ui-kit.md b/docs/developer-guides/docs/03-code-internals/02-ui-kit.md
index b5030340f73..f01a87e471a 100644
--- a/docs/developer-guides/docs/03-code-internals/02-ui-kit.md
+++ b/docs/developer-guides/docs/03-code-internals/02-ui-kit.md
@@ -231,6 +231,29 @@ Every primitive is browsable at `/styleguide/<category>/<section>`, and the sect
A section should be designed, with multiple examples that each isolate one capability. `sections/molecules/drag-and-drop.gjs` is the model: it groups its examples with `StyleguideGroups`, and each `Example` carries a title, a `@kind`, a description of what the example demonstrates, a `@tryThis` prompt telling the reader what to do, an optional `@note` on the subtlety it exposes, and the source via `@code` so the reader can copy it. Aim for one example per argument or behaviour worth understanding (types, positions, disabled state, nesting, custom preview, and so on), rather than a single kitchen-sink demo.
+## DMultiSelect footer actions
+
+`DMultiSelect` accepts an optional `footer` block below the search results, including when
+there are no matching results. The block receives the menu API; await `menu.close()` before
+opening another dialog so focus moves to the new dialog. Without a footer block, no footer
+or divider is rendered. Set `@matchTriggerWidth={{true}}` when a caller needs the menu to
+match the trigger width; this is opt-in and independent of the footer.
+
+```hbs
+<DMultiSelect
+ @matchTriggerWidth={{true}}
+ @loadFn={{this.loadItems}}
+ @selection={{this.selection}}
+ @onChange={{this.selectItems}}
+>
+ <:selection as |item|>{{item.name}}</:selection>
+ <:result as |item|>{{item.name}}</:result>
+ <:footer as |menu|>
+ <DButton @action={{fn this.createItem menu}} @label="create" @icon="plus" />
+ </:footer>
+</DMultiSelect>
+```
+
# Related guides
- [FormKit](22-form-kit.md) for forms.
diff --git a/frontend/discourse/app/ui-kit/d-multi-select.gjs b/frontend/discourse/app/ui-kit/d-multi-select.gjs
index 7f830cd2a6c..273d79a68f3 100644
--- a/frontend/discourse/app/ui-kit/d-multi-select.gjs
+++ b/frontend/discourse/app/ui-kit/d-multi-select.gjs
@@ -236,6 +236,10 @@ export default class DMultiSelect extends Component {
<DMenu
...attributes
@allowedPlacements={{@allowedPlacements}}
+ @contentClass={{if
+ (has-block "footer")
+ "d-multi-select-menu--with-footer"
+ }}
@identifier="d-multi-select"
@matchTriggerMinWidth={{@matchTriggerMinWidth}}
@matchTriggerWidth={{@matchTriggerWidth}}
@@ -280,9 +284,13 @@ export default class DMultiSelect extends Component {
@icon="angle-down"
/>
</:trigger>
- <:content>
+ <:content as |menuApi|>
<DDropdownMenu
- class={{dConcatClass "d-multi-select__content" @contentClass}}
+ class={{dConcatClass
+ "d-multi-select__content"
+ (if (has-block "footer") "--with-footer")
+ @contentClass
+ }}
as |menu|
>
<menu.item class="d-multi-select__search-container">
@@ -340,6 +348,12 @@ export default class DMultiSelect extends Component {
</div>
{{/if}}
{{/if}}
+ {{#if (has-block "footer")}}
+ <menu.divider />
+ <menu.item class="d-multi-select__footer">
+ {{yield menuApi to="footer"}}
+ </menu.item>
+ {{/if}}
</DDropdownMenu>
</:content>
</DMenu>
diff --git a/frontend/discourse/tests/integration/ui-kit/d-multi-select-test.gjs b/frontend/discourse/tests/integration/ui-kit/d-multi-select-test.gjs
index 636125f63d9..ee7f7fe84fe 100644
--- a/frontend/discourse/tests/integration/ui-kit/d-multi-select-test.gjs
+++ b/frontend/discourse/tests/integration/ui-kit/d-multi-select-test.gjs
@@ -1,5 +1,6 @@
import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
+import { fn } from "@ember/helper";
import { action } from "@ember/object";
import {
click,
@@ -10,6 +11,7 @@ import {
} from "@ember/test-helpers";
import { module, test } from "qunit";
import { setupRenderingTest } from "discourse/tests/helpers/component-test";
+import DButton from "discourse/ui-kit/d-button";
import DMultiSelect from "discourse/ui-kit/d-multi-select";
class TestComponent extends Component {
@@ -48,10 +50,54 @@ class TestComponent extends Component {
module("Integration | ui-kit | DMultiSelect", function (hooks) {
setupRenderingTest(hooks);
+ test("optional footer remains available with no results and can close the menu", async function (assert) {
+ const load = async () => [];
+ let actions = 0;
+ const activate = async (menu) => {
+ await menu.close();
+ actions++;
+ };
+ await render(
+ <template>
+ <DMultiSelect @loadFn={{load}}>
+ <:selection as |item|>{{item.name}}</:selection>
+ <:result as |item|>{{item.name}}</:result>
+ <:footer as |menu|><DButton
+ data-test-footer-action
+ @action={{fn activate menu}}
+ @label="create"
+ /></:footer>
+ </DMultiSelect>
+ </template>
+ );
+ await click(".d-multi-select-trigger");
+ assert
+ .dom(".d-multi-select-menu--with-footer")
+ .exists("marks the menu for footer-specific styling");
+ await fillIn(".d-multi-select__search-input", "nothing");
+ assert
+ .dom(".d-multi-select__search-no-results")
+ .exists("shows empty results");
+ assert
+ .dom(".d-multi-select__footer [data-test-footer-action]")
+ .exists("keeps the footer available");
+ await click("[data-test-footer-action]");
+ assert.strictEqual(actions, 1, "invokes the footer action");
+ assert
+ .dom(".d-multi-select__content")
+ .doesNotExist("closes the picker before proceeding");
+ });
+
test("filter", async function (assert) {
await render(<template><TestComponent /></template>);
await click(".d-multi-select-trigger");
+ assert
+ .dom(".d-multi-select__footer")
+ .doesNotExist("omits the footer when no block is supplied");
+ assert
+ .dom(".d-multi-select-menu--with-footer")
+ .doesNotExist("does not apply footer styling without a footer block");
await fillIn(".d-multi-select__search-input", "bar");
assert.dom(".d-multi-select__result:nth-child(1)").hasText("bar");
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-empty.gjs b/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-empty.gjs
new file mode 100644
index 00000000000..4e530229ac0
--- /dev/null
+++ b/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-empty.gjs
@@ -0,0 +1,22 @@
+import DButton from "discourse/ui-kit/d-button";
+import DMultiSelect from "discourse/ui-kit/d-multi-select";
+import { i18n } from "discourse-i18n";
+
+const loadItems = async () => [];
+
+export default <template>
+ <DMultiSelect
+ @label={{i18n "styleguide.sections.multi_select.choose_item"}}
+ @loadFn={{loadItems}}
+ >
+ <:result as |item|>{{item.name}}</:result>
+ <:selection as |item|>{{item.name}}</:selection>
+ <:footer as |menu|>
+ <DButton
+ @action={{menu.close}}
+ @icon="plus"
+ @label="styleguide.sections.multi_select.create_item"
+ />
+ </:footer>
+ </DMultiSelect>
+</template>
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-scroll.gjs b/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-scroll.gjs
new file mode 100644
index 00000000000..ef1bd985560
--- /dev/null
+++ b/plugins/styleguide/assets/javascripts/discourse/components/examples/molecules/multi-select-footer-scroll.gjs
@@ -0,0 +1,45 @@
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { action } from "@ember/object";
+import DButton from "discourse/ui-kit/d-button";
+import DMultiSelect from "discourse/ui-kit/d-multi-select";
+import { i18n } from "discourse-i18n";
+
+const ITEMS = Array.from({ length: 40 }, (_, index) => ({
+ id: index + 1,
+ name: `Example item ${index + 1}`,
+}));
+
+export default class MultiSelectFooterScrollExample extends Component {
+ @tracked selection = [ITEMS[0]];
+
+ @action
+ async loadItems(filter) {
+ const query = filter.toLowerCase();
+ return ITEMS.filter((item) => item.name.toLowerCase().includes(query));
+ }
+
+ @action
+ selectItems(selection) {
+ this.selection = selection;
+ }
+
+ <template>
+ <DMultiSelect
+ @label={{i18n "styleguide.sections.multi_select.choose_item"}}
+ @loadFn={{this.loadItems}}
+ @onChange={{this.selectItems}}
+ @selection={{this.selection}}
+ >
+ <:result as |item|>{{item.name}}</:result>
+ <:selection as |item|>{{item.name}}</:selection>
+ <:footer as |menu|>
+ <DButton
+ @action={{menu.close}}
+ @icon="plus"
+ @label="styleguide.sections.multi_select.create_item"
+ />
+ </:footer>
+ </DMultiSelect>
+ </template>
+}
diff --git a/plugins/styleguide/assets/javascripts/discourse/components/sections/molecules/multi-select.gjs b/plugins/styleguide/assets/javascripts/discourse/components/sections/molecules/multi-select.gjs
index a033f10c19f..ac70aea91cf 100644
--- a/plugins/styleguide/assets/javascripts/discourse/components/sections/molecules/multi-select.gjs
+++ b/plugins/styleguide/assets/javascripts/discourse/components/sections/molecules/multi-select.gjs
@@ -1,5 +1,10 @@
+import { i18n } from "discourse-i18n";
import MultiSelectExample from "../../examples/molecules/multi-select.gjs";
import multiSelectSource from "../../examples/molecules/multi-select?source=file";
+import EmptyFooterExample from "../../examples/molecules/multi-select-footer-empty.gjs";
+import emptyFooterSource from "../../examples/molecules/multi-select-footer-empty?source=file";
+import ScrollFooterExample from "../../examples/molecules/multi-select-footer-scroll.gjs";
+import scrollFooterSource from "../../examples/molecules/multi-select-footer-scroll?source=file";
import StyleguideComponent from "../../styleguide/component.gjs";
import StyleguideExample from "../../styleguide-example.gjs";
@@ -11,4 +16,32 @@ export default <template>
</:sample>
</StyleguideComponent>
</StyleguideExample>
+ <StyleguideExample
+ @code={{emptyFooterSource}}
+ @description={{i18n
+ "styleguide.sections.multi_select.footer_empty_description"
+ }}
+ @title={{i18n "styleguide.sections.multi_select.footer_empty_title"}}
+ @tryThis={{i18n "styleguide.sections.multi_select.footer_empty_try_this"}}
+ >
+ <StyleguideComponent @tag="d-multi-select footer">
+ <:sample>
+ <EmptyFooterExample />
+ </:sample>
+ </StyleguideComponent>
+ </StyleguideExample>
+ <StyleguideExample
+ @code={{scrollFooterSource}}
+ @description={{i18n
+ "styleguide.sections.multi_select.footer_scroll_description"
+ }}
+ @title={{i18n "styleguide.sections.multi_select.footer_scroll_title"}}
+ @tryThis={{i18n "styleguide.sections.multi_select.footer_scroll_try_this"}}
+ >
+ <StyleguideComponent @tag="d-multi-select footer">
+ <:sample>
+ <ScrollFooterExample />
+ </:sample>
+ </StyleguideComponent>
+ </StyleguideExample>
</template>
diff --git a/plugins/styleguide/config/locales/client.en.yml b/plugins/styleguide/config/locales/client.en.yml
index 7d86ac5a892..3568ee5943f 100644
--- a/plugins/styleguide/config/locales/client.en.yml
+++ b/plugins/styleguide/config/locales/client.en.yml
@@ -61,6 +61,14 @@ en:
declined: "Last right-click: declined, the browser took it"
multi_select:
title: "Multi select"
+ choose_item: "Choose an item"
+ create_item: "Create an item"
+ footer_empty_title: "Footer with no results"
+ footer_empty_description: "The footer action remains available when there are no matching results."
+ footer_empty_try_this: "Open the menu and search for an item. The footer stays visible."
+ footer_scroll_title: "Footer with a long result list"
+ footer_scroll_description: "The result list scrolls independently from the footer action."
+ footer_scroll_try_this: "Open the menu and scroll the results. The footer remains in place."
reorderable_list:
title: "Reorderable list"
groups: