@ebay/skin 18.1.0 → 18.2.0

package/src/modules/menu-button.marko

@@ -0,0 +1,1069 @@
+<div id="menu-button">
+    <section-header metadata=input.metadata name=input.name/>
+
+    <p>
+        A menu button follows the principal of
+        <a href="https://en.wikipedia.org/wiki/Progressive_disclosure">
+            progressive disclosure
+        </a>
+        , it keeps secondary commands hidden from view until needed.
+    </p>
+    <p>
+        A menu is
+        <strong>not</strong>
+        ${" "}a form control. If you wish to submit form data natively, without JavaScript, please consider${" "}
+        <a href="#checkbox">
+            checkbox
+        </a>
+        ,
+        <a href="#combobox">
+            combobox
+        </a>
+        ,
+        <a href="#select">
+            select
+        </a>
+        , or
+        <a href="#radio">
+            radio
+        </a>
+         instead.
+    </p>
+    <p>
+        Selecting a menu item command should update the page
+        <strong>without</strong>
+        ${" "}a full page reload (i.e. acting similar to buttons, checkboxes or radios). If a full page load is required instead (i.e. acting like links), please refer to the${" "}
+        <a href="#menu-button-fake">
+            fake menu button
+        </a>
+        .
+    </p>
+
+    <h3 id="menu-button-default">
+        Default Menu Button
+    </h3>
+    <p>
+        The default menu button opens a
+        <em>stateless</em>
+         menu. Each item has a role of
+        <span class="highlight">
+            menuitem
+        </span>
+        .
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 1</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 2</span>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitem"
+                            aria-disabled="true"
+                        >
+                            <span>Menu Item 3</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 4</span>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 1</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 2</span>
+            </div>
+            <div class="menu-button__item" role="menuitem" aria-disabled="true">
+                <span>Menu Item 3</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 4</span>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <p>
+        For all menu buttons, the overlay becomes automatically scrollable when its height reaches 400px.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+
+                        <for|item,i| of=Array.from(Array(50))>
+                            <div class="menu-button__item" role="menuitem">
+                                <span>Menu item ${i}</span>
+                            </div>
+                        </for>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <h3 id="menu-button-radio">
+        Single-Select Menu Button
+    </h3>
+    <p>
+        For single-select state, use role
+        <span class="highlight">
+            menuitemradio
+        </span>
+         on each menu item.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            aria-checked="true"
+                            data-makeup-group="sort"
+                        >
+                            <span>Menu Item 1</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            aria-checked="false"
+                            data-makeup-group="sort"
+                        >
+                            <span>Menu Item 2</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            aria-checked="false"
+                            data-makeup-group="sort"
+                        >
+                            <span>Menu Item 3</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn--secondary" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitemradio" aria-checked="true">
+                <span>Menu Item 1</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemradio" aria-checked="false">
+                <span>Menu Item 2</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemradio" aria-checked="false">
+                <span>Menu Item 3</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <h3 id="menu-button-checkbox">
+        Multi-Select Menu Button
+    </h3>
+    <p>
+        For multi-select state, use role
+        <span class="highlight">
+            menuitemcheckbox
+        </span>
+         on each menu item.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div
+                            class="menu-button__item"
+                            role="menuitemcheckbox"
+                            aria-checked="true"
+                        >
+                            <span>Menu Item 1</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemcheckbox"
+                            aria-checked="true"
+                        >
+                            <span>Menu Item 2</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemcheckbox"
+                            aria-checked="false"
+                        >
+                            <span>Menu Item 3</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn--secondary" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitemcheckbox" aria-checked="true" height="10" width="14">
+                <span>Menu Item 1</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemcheckbox" aria-checked="true" height="10" width="14">
+                <span>Menu Item 2</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemcheckbox" aria-checked="false" height="10" width="14">
+                <span>Menu Item 3</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <div class="highlight">
+        <h3 id="menu-button-label">
+            Labelling a Menu Button
+        </h3>
+        <p>
+            By default, the text of any button acts as its accessible label. The accessible label must at${" "}
+            <strong>all times</strong>
+             reflect the
+            <em>purpose</em>
+             of the button. If the text only conveys a
+            <em>transient value</em>
+            , then the criteria would not be satisfied.
+        </p>
+
+        <h4 id="menu-button-label-fixed">
+            Fixed Label
+        </h4>
+        <p>
+            The simplest scenario in which to satisfy the criteria is a fixed label, i.e. the button text never changes. For example: "Menu", "Options", "Edit".
+        </p>
+
+        <h4 id="menu-button-label-compact">
+            Compact Label
+        </h4>
+        <p>
+            If a fixed label is not possible, the button's inner text can potentially be written as a key/value pair, where key denotes purpose and value repesents the current selection. This is most typical in a${" "}
+            <a href="#menu-button-radio">
+                single select menu button
+            </a>
+            . For example: "Sort: Price", "Color: Red". This technique is identical to the method used by${" "}
+            <a href="#listbox-button">
+                Listbox Button
+            </a>
+            .
+        </p>
+
+        <h4 id="menu-button-label-compound">
+            Compound Label
+        </h4>
+        <p>
+            Finally, we can also consider using
+            <span class="highlight">
+                aria-labelledby
+            </span>
+            ${" "}to stitch together an additional, external element - therefore creating a${" "}
+            <em>compound</em>
+             label.
+        </p>
+    </div>
+
+    <h3 id="menu-button-grouped">
+        Grouped Menu Button
+    </h3>
+    <p>
+        Menu button items can be separated into groups, using the
+        <span class="highlight">
+            hr
+        </span>
+         tag.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item A1</span>
+                        </div>
+
+                        <hr class="menu-button__separator" role="separator">
+
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            data-makeup-group="sort"
+                            aria-checked="true"
+                        >
+                            <span>Menu Item B1</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            data-makeup-group="sort"
+                            aria-checked="false"
+                        >
+                            <span>Menu Item B2</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemradio"
+                            data-makeup-group="sort"
+                            aria-checked="false"
+                        >
+                            <span>Menu Item B3</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+
+                        <hr class="menu-button__separator" role="separator">
+
+                        <div
+                            class="menu-button__item"
+                            role="menuitemcheckbox"
+                            data-makeup-group="filter"
+                            aria-checked="true"
+                        >
+                            <span>Menu Item C1</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                        <div
+                            class="menu-button__item"
+                            role="menuitemcheckbox"
+                            data-makeup-group="filter"
+                            aria-checked="true"
+                        >
+                            <span>Menu Item C2</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn-secondary" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item A1</span>
+            </div>
+
+            <hr class="menu-button__separator" role="separator" />
+
+            <div class="menu-button__item" role="menuitemradio" aria-checked="true">
+                <span>Menu Item B1</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemradio" aria-checked="false">
+                <span>Menu Item B2</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemradio" aria-checked="false">
+                <span>Menu Item B3</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+
+            <hr class="menu-button__separator" role="separator" />
+
+            <div class="menu-button__item" role="menuitemcheckbox" aria-checked="true">
+                <span>Menu Item C1</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+            <div class="menu-button__item" role="menuitemcheckbox" aria-checked="true">
+                <span>Menu Item C2</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <h3 id="menu-button-fake">
+        Fake Menu Button
+    </h3>
+    <p>
+        At first glance, a fake menu button
+        <em>appears</em>
+        ${" "}to be a normal menu button component, but it contains a list of hyperlinks and thus behaves more like a navigational component.
+    </p>
+    <p>
+        Use the
+        <span class="highlight">
+            aria-current
+        </span>
+        ${" "}attribute to denote the link that matches the current page URL (if applicable).
+    </p>
+    <p>
+        A valid
+        <span class="highlight">
+            href
+        </span>
+         attribute is
+        <strong>required</strong>
+         for all anchor tags (a value of "javascript" is
+        <strong>not</strong>
+         valid!) The
+        <span class="highlight">
+            button
+        </span>
+        ${" "}tag is also supported (as demonstrated in the following example) if JavaScript behaviour is required alongside items with navigation behaviour.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="fake-menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <ul class="fake-menu-button__menu">
+                    <li>
+                        <a
+                            class="fake-menu-button__item"
+                            href="https://www.ebay.com"
+                            aria-current="page"
+                        >
+                            <span>Link 1</span>
+                            <svg
+                                class="icon icon--16"
+                                height="10"
+                                width="14"
+                                aria-hidden="true"
+                            >
+                                <icon-symbol name="tick-16"/>
+                            </svg>
+                        </a>
+                    </li>
+                    <li>
+                        <a
+                            href="https://www.ebay.com"
+                            class="fake-menu-button__item"
+                        >
+                            <span>Link 2</span>
+                        </a>
+                    </li>
+                    <li>
+                        <button class="fake-menu-button__item" type="button">
+                            <span>Button 3</span>
+                        </button>
+                    </li>
+                    <li>
+                        <button class="fake-menu-button__item" type="button">
+                            <span>Button 4</span>
+                        </button>
+                    </li>
+                </ul>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="fake-menu-button">
+    <button class="btn btn--secondary" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <ul class="fake-menu-button__menu">
+        <li>
+            <a class="fake-menu-button__item" href="https://www.ebay.com" aria-current="page">
+                <span>Link 1</span>
+                <svg class="icon icon--16" height="10" width="14" aria-hidden="true">
+                    <use href="#icon-tick-16"></use>
+                </svg>
+            </a>
+        </li>
+        <li>
+            <a href="https://www.ebay.com" class="fake-menu-button__item">
+                <span>Link 2</span>
+            </a>
+        </li>
+        <li>
+            <button class="fake-menu-button__item" type="button">
+                <span>Button 3</span>
+            </button>
+        </li>
+        <li>
+            <button class="fake-menu-button__item" type="button">
+                <span>Button 4</span>
+            </button>
+        </li>
+    </ul>
+</span>
+    </highlight-code>
+
+    <h3 id="menu-button-fixed-width">
+        Fixed Width Menu Button
+    </h3>
+    <p>
+        Use the
+        <span class="highlight">
+            menu-button__menu--fix-width
+        </span>
+         or
+        <span class="highlight">
+            fake-menu-button__menu--fix-width
+        </span>
+        ${" "}element modifier to fix the width of any menu items to the button width. This is useful in cases where the menu overlay needs to be constrained to the button width, usually to accomodate spacing and layout.
+    </p>
+    <p>
+        <strong>NOTE: </strong>
+         Fixed width is currently only available on menu buttons that use a
+        <span class="highlight">
+            span
+        </span>
+         root tag.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--secondary"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu menu-button__menu--fix-width">
+                    <div class="menu-button__items" role="menu">
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 1 with a long string</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 2</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 3</span>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn--secondary" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu menu-button__menu--fix-width">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 1 with a long string</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 2</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 3</span>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <h3 id="menu-button-form">
+        Form-Themed Menu Button
+    </h3>
+    <p>
+        If placing a menu-button alongside a form control (e.g. textbox), you may wish to apply the${" "}
+        <span class="highlight">
+            btn--form
+        </span>
+         modifier, which better matches the look-and-feel of forms.
+    </p>
+    <p>
+        <strong>NOTE</strong>
+        : a menu-button is a good candidate for a dropdown of actions that make
+        <em>changes</em>
+         to a form, but it should
+        <strong>not</strong>
+         be used as a dropdown for selecting and storing form
+        <em>data</em>
+        . Please use
+        <a href="#button">
+            select
+        </a>
+         or
+        <a href="#button">
+            listbox-button
+        </a>
+         for that purpose instead.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--form"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 1</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 2</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 3</span>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn--form" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 1</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 2</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 3</span>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+
+    <h3 id="menu-button-borderless">
+        Borderless Menu Button
+    </h3>
+    <p>
+        Use the
+        <span class="highlight">
+            btn--borderless
+        </span>
+         modifier to create a minimal borderless button.
+    </p>
+
+    <div class="demo">
+        <div class="demo__inner">
+            <span class="menu-button">
+                <button
+                    class="btn btn--borderless"
+                    aria-expanded="false"
+                    aria-haspopup="true"
+                    type="button"
+                >
+                    <span class="btn__cell">
+                        <span class="btn__text">
+                            Button
+                        </span>
+                        <svg
+                            class="icon icon--12"
+                            height="10"
+                            width="14"
+                            aria-hidden="true"
+                        >
+                            <icon-symbol name="chevron-down-12"/>
+                        </svg>
+                    </span>
+                </button>
+                <div class="menu-button__menu">
+                    <div class="menu-button__items" role="menu">
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 1</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 2</span>
+                        </div>
+                        <div class="menu-button__item" role="menuitem">
+                            <span>Menu Item 3</span>
+                        </div>
+                    </div>
+                </div>
+            </span>
+        </div>
+    </div>
+
+    <highlight-code
+        type="html"
+        >
+<span class="menu-button">
+    <button class="btn btn--borderless" aria-expanded="false" aria-haspopup="true" type="button">
+        <span class="btn__cell">
+            <span class="btn__text">Button</span>
+            <svg class="icon icon--12" height="10" width="14" aria-hidden="true">
+                <use href="#icon-chevron-down-12"></use>
+            </svg>
+        </span>
+    </button>
+    <div class="menu-button__menu">
+        <div class="menu-button__items" role="menu">
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 1</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 2</span>
+            </div>
+            <div class="menu-button__item" role="menuitem">
+                <span>Menu Item 3</span>
+            </div>
+        </div>
+    </div>
+</span>
+    </highlight-code>
+</div>
+export const metadata = {
+    "ds-component": {
+        name: "dropdown",
+        version: 2.3,
+    },
+    submodules: ["button", "icon", "menu"],
+};