@lion/ui 0.22.0 → 0.24.0

package/docs/components/input-tel-dropdown/use-cases.md

@@ -1,5 +1,5 @@
 ---
-title: 'Input Tel Dropdown: Use Cases'
+title: 'Use Cases'
 parts:
   - Input Tel Dropdown
   - Use Cases
@@ -10,7 +10,7 @@ eleventyNavigation:
   title: Use Cases
 ---
 
-# Input Tel Dropdown: Use Cases
+# Use Cases
 
 ```js script
 import { html } from '@mdjs/mdjs-preview';

package/docs/components/listbox/overview.md

@@ -1,5 +1,5 @@
 ---
-title: 'Listbox: Overview'
+title: 'Overview'
 parts:
   - Listbox
   - Overview
@@ -10,7 +10,7 @@ eleventyNavigation:
   title: Overview
 ---
 
-# Listbox: Overview
+# Overview
 
 A widget that presents a list of options and allows a user to select one or more of them.
 A listbox that allows a single option to be chosen is a `single-select listbox`; one that allows

package/docs/components/listbox/use-cases.md

@@ -1,5 +1,5 @@
 ---
-title: 'Listbox: Use Cases'
+title: 'Use Cases'
 parts:
   - Listbox
   - Use Cases
@@ -10,7 +10,7 @@ eleventyNavigation:
   title: Use Cases
 ---
 
-# Listbox: Use Cases
+# Use Cases
 
 ```js script
 import { html } from '@mdjs/mdjs-preview';
@@ -151,4 +151,4 @@ Navigation will skip over disabled options. Let's disable Artichoke and Brussel
 
 ## Validation
 
-A validator can be used to make it e.g. `required`. If you want to know how to do that, please take a look at our [validation examples](https://github.com/ing-bank/lion/blob/1e44a873eb492168e7e3d2f5c120371d950b9e03/docs/fundamentals/systems/form/validate.md).
+A validator can be used to make it e.g. `required`. If you want to know how to do that, please take a look at our [validation examples](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/fundamentals/systems/form/validate.md).

package/docs/components/menu/api-table.md

@@ -0,0 +1,44 @@
+---
+parts:
+  - API Table
+  - Menu
+title: 'Menu: API Table'
+eleventyNavigation:
+  key: API Table >> Menu
+  title: API Table
+  order: 90
+  parent: Menu
+---
+# Menu: API Table
+ 
+
+## class: `LionMenu`, `lion-menu`
+
+### Fields
+
+| Name                    | Privacy   | Type                      | Default        | Description                                                                  | Inherited From |
+| ----------------------- | --------- | ------------------------- | -------------- | ---------------------------------------------------------------------------- | -------------- |
+| `bar`                   | public    | `boolean`                 | `false`        | Enable bar to use \[role="menubar"] and horizontal navigation                | LionMenuCore   |
+| `behaveAsAccordion`     | public    | `boolean`                 | `true`         |                                                                              | LionMenuCore   |
+| `invokerInteraction`    | public    | `string`                  | `'click'`      |                                                                              | LionMenuCore   |
+| `openableMode`          | public    | `'disclosure'\|'overlay'` | `'disclosure'` | Terminology aligned with https\://open-ui.org/components/openable.explainer/ |                |
+| `_activateOnTypedChars` | protected | `boolean`                 | `true`         |                                                                              | LionMenuCore   |
+| `_listRole`             | protected | `string`                  | `'menu'`       |                                                                              | LionMenuCore   |
+| `_shouldSetupOverlay`   | protected | `boolean`                 | `false`        |                                                                              |                |
+
+### Methods
+
+| Name                   | Privacy   | Description                                                                                                     | Parameters      | Return          | Inherited From |
+| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | --------------- | --------------- | -------------- |
+| `setCheckedIndex`      | public    | Allows groups within one level. In case we deal with menuitemcheckbox,
we treat it as multiple choice group | `index: number` |                 | LionMenuCore   |
+| `_defineOverlayConfig` | protected |                                                                                                                 |                 | `OverlayConfig` |                |
+| `_onListKeyUp`         | protected |                                                                                                                 | `ev: *`         |                 |                |
+
+### Attributes
+
+| Name            | Field        | Inherited From |
+| --------------- | ------------ | -------------- |
+| `openable-mode` | openableMode |                |
+| `bar`           | bar          | LionMenuCore   |
+
+<hr/>

package/docs/components/menu/applyMenuDemoStyles.js

@@ -0,0 +1,173 @@
+import { html, render } from 'lit';
+
+function renderLitAsNode(tpl) {
+  const container = document.createElement('div');
+  render(tpl, container);
+  return container.firstElementChild;
+}
+
+let isApplied = false;
+
+export function applyMenuDemoStyles() {
+  if (isApplied) {
+    return;
+  }
+
+  const fontAwesome = html`<link
+    rel="stylesheet"
+    href="https://use.fontawesome.com/releases/v5.1.0/css/all.css"
+    integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt"
+    crossorigin="anonymous"
+  />`;
+  document.head.appendChild(renderLitAsNode(fontAwesome));
+
+  const styles = html` <style>
+    [role='menu']:focus {
+      outline: none;
+    }
+
+    [role='toolbar'],
+    [role='tree'],
+    [role='menubar'],
+    [role='menu'] {
+      background: white;
+      font-family: sans-serif;
+      font-size: 12px;
+    }
+
+    [level] > [role='menu'] {
+      border: 1px solid black;
+    }
+
+    [role='treeitem']:not([aria-expanded]),
+    [role='treeitem'][aria-expanded],
+    [role^='menuitem']:not([aria-expanded]),
+    [role^='menuitem'][aria-expanded] {
+      all: unset;
+      display: block;
+      width: 100%;
+      position: relative;
+      box-sizing: border-box;
+      padding: 4px 24px 4px 8px;
+    }
+
+    [role='treeitem']:not([aria-expanded]),
+    [role='treeitem'][aria-expanded] {
+      padding-left: 16px;
+    }
+
+    [role='treeitem'][active]:not([aria-expanded]),
+    [role='treeitem'][active][aria-expanded],
+    [role^='menuitem'][active]:not([aria-expanded]),
+    [role^='menuitem'][active][aria-expanded] {
+      background: lightgrey;
+    }
+
+    [role^='menuitem'][checked]:not([aria-expanded]),
+    [role^='menuitem'][checked][aria-expanded] {
+      background: #eee;
+    }
+
+    [role='treeitem'],
+    [role^='menuitem'] {
+      position: relative;
+      cursor: default;
+    }
+
+    [role='treeitem']::after,
+    [role^='menuitem']::after {
+      position: absolute;
+      top: 5px;
+      font-size: 10px;
+    }
+
+    [role^='menuitem']::after {
+      right: 4px;
+    }
+
+    [role^='treeitem']::after {
+      left: 4px;
+    }
+
+    [role^='menuitem'][aria-expanded]::after {
+      content: '▶';
+    }
+
+    [role^='menuitem'][aria-expanded='true']::after {
+      content: '▼';
+    }
+
+    [axis='inline'] [role^='menuitem'][aria-expanded]::after {
+      content: '▼';
+    }
+
+    [role='menuitemcheckbox'][aria-checked='true']::after {
+      content: '🗹';
+    }
+
+    [role='menuitemradio'][aria-checked='true']::after {
+      content: '◉';
+    }
+
+    [role='separator'] {
+      border-bottom: 1px solid gray;
+    }
+
+    [role='treeitem'][aria-expanded]::after {
+      content: '+';
+    }
+
+    demo-tree[level='1'] [role='treeitem']:not([aria-expanded]),
+    demo-tree[level='1'] [role='treeitem'][aria-expanded] {
+      padding-left: 24px;
+    }
+
+    lion-menu[level='1'] [role^='menuitem']:not([aria-expanded]),
+    lion-menu[level='1'] [role^='menuitem'][aria-expanded] {
+      padding-left: 16px;
+    }
+
+    demo-tree[level='2'] [role='treeitem']:not([aria-expanded]),
+    demo-tree[level='2'] [role='treeitem'][aria-expanded] {
+      padding-left: 32px;
+    }
+    lion-menu[level='2'] [role^='menuitem']:not([aria-expanded]),
+    lion-menu[level='2'] [role^='menuitem'][aria-expanded] {
+      padding-left: 24px;
+    }
+
+    [role='toolbar'] {
+      padding: 8px;
+      background: #eee;
+    }
+    [role='toolbar'] button {
+      background: none;
+      padding: 4px 8px;
+      border: 1px transparent;
+    }
+    [role='toolbar'] button[aria-pressed='true'],
+    [role='toolbar'] button[aria-checked='true'] {
+      background: white;
+      border: 1px black;
+    }
+
+    [role='toolbar'] > div[role='separator'] {
+      margin-left: 8px;
+      margin-right: 8px;
+      border-left: 1px solid lightgray;
+    }
+
+    button[slot='invoker'] {
+      background: none;
+      color: inherit;
+      border: none;
+      padding: 0;
+      font: inherit;
+      display: block;
+      width: 100%;
+      text-align: left;
+    }
+  </style>`;
+  document.head.appendChild(renderLitAsNode(styles));
+  isApplied = true;
+}

package/docs/components/menu/extensions.md

@@ -0,0 +1,262 @@
+---
+title: 'Extensions'
+parts:
+  - Menu
+  - Extensions
+eleventyNavigation:
+  key: 'Menu: Extensions'
+  order: 10
+  parent: Menu
+  title: Extensions
+---
+
+# Extensions
+
+```js script
+import { html } from 'lit';
+import './src/DemoNavigationBar.js';
+
+// N.B. data structure designed to be compatible with existing extension layer
+// TODO: maybe refactor api and bridge
+
+const menuData = [
+  {
+    title: 'Products',
+    link: 'products',
+    sub: [
+      {
+        title: 'Payments',
+        link: 'payments-collections',
+        sub: [
+          { title: 'Payments & Collections', link: '#' },
+          { title: 'Merchant Commerce Solutions', link: 'merchant-commerce-solutions' },
+          { title: 'Instant Payments', link: 'instant-payments' },
+          { title: 'SEPA Direct Debit', link: 'SEPA-direct-debit' },
+          { title: 'SEPA Credit Transfer', link: 'SEPA-credit-transfer' },
+          { title: 'International Credit Transfer', link: 'international-credit-transfer' },
+          { title: 'Account Reporting', link: 'account-deporting' },
+        ],
+      },
+      {
+        title: 'Savings',
+        link: 'savings-collection',
+        sub: [
+          { title: 'Liquidity & Cash Management', link: 'liquidity-cash-management' },
+          { title: 'Physcial Cash Management', link: 'physcial-cash-management' },
+          { title: 'Notional Cash Management', link: 'notional-cash-management' },
+          { title: 'Virtual Cash Management', link: 'virtual-cash-management' },
+          { title: 'Liquidity Management', link: 'liquidity-management' },
+          { title: 'Excess Cash', link: 'excess-cash' },
+        ],
+      },
+      {
+        title: 'Investing',
+        link: 'investing-collection',
+        sub: [
+          { title: 'Digital Banking Services', link: 'home' },
+          { title: 'InsideBusiness', link: 'home' },
+          { title: 'Connectivity Solutions', link: 'connectivity-solutions' },
+        ],
+      },
+      {
+        title: 'Mortgages',
+        link: 'mortgages-collections',
+        sub: [
+          { title: 'Payments & Collections', link: '#' },
+          { title: 'Merchant Commerce Solutions', link: 'merchant-commerce-solutions' },
+          { title: 'Instant Payments', link: 'instant-payments' },
+          { title: 'SEPA Direct Debit', link: 'SEPA-direct-debit' },
+          { title: 'SEPA Credit Transfer', link: 'SEPA-credit-transfer' },
+          { title: 'International Credit Transfer', link: 'international-credit-transfer' },
+          { title: 'Account Reporting', link: 'account-deporting' },
+        ],
+      },
+      {
+        title: 'Loans',
+        link: 'loans-collection',
+        sub: [
+          { title: 'Liquidity & Cash Management', link: 'liquidity-cash-management' },
+          { title: 'Physcial Cash Management', link: 'physcial-cash-management' },
+          { title: 'Notional Cash Management', link: 'notional-cash-management' },
+          { title: 'Virtual Cash Management', link: 'virtual-cash-management' },
+          { title: 'Liquidity Management', link: 'liquidity-management' },
+          { title: 'Excess Cash', link: 'excess-cash' },
+        ],
+      },
+      {
+        title: 'Insurances',
+        link: 'insurances-collection',
+        sub: [
+          { title: 'Digital Banking Services', link: 'home' },
+          { title: 'InsideBusiness', link: 'home' },
+          { title: 'Connectivity Solutions', link: 'connectivity-solutions' },
+        ],
+      },
+      {
+        title: 'Digital banking',
+        link: 'digital-banking',
+      },
+    ],
+  },
+  {
+    title: "Who it's for",
+    link: 'who',
+    sub: [
+      {
+        title: 'Parents & kids',
+        link: 'parents-kids',
+        sub: [
+          { title: 'Child current account', link: '#child-current' },
+          { title: 'Youth current account', link: '#youth-current' },
+          { title: 'Child savings account', link: '#child-savings' },
+        ],
+      },
+      {
+        title: 'Students',
+        link: 'students',
+        sub: [
+          { title: 'Student account', link: '#student-account' },
+          { title: 'Smart payments', link: '#smart-payments' },
+          { title: 'Smart savings', link: '#smart-savings' },
+          { title: 'Smart banking', link: '#smart-banking' },
+          { title: 'Smart for now', link: '#smart-for-now' },
+          { title: 'Smart for later', link: '#smart-for-later' },
+        ],
+      },
+      {
+        title: "I'm an expat",
+        link: 'expat',
+        sub: [
+          { title: 'Open a Dutch banking account', link: '#open' },
+          { title: 'Investments', link: '#investments' },
+          { title: 'Mortgage', link: '#mortgage' },
+          { title: 'Health insurance', link: '#insurance' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Themes',
+    link: 'themes',
+    sub: [
+      {
+        title: 'Living',
+        link: 'living-collections',
+        sub: [
+          { title: 'Payments & Collections', link: '#' },
+          { title: 'Merchant Commerce Solutions', link: 'merchant-commerce-solutions' },
+          { title: 'Instant Payments', link: 'instant-payments' },
+          { title: 'SEPA Direct Debit', link: 'SEPA-direct-debit' },
+          { title: 'SEPA Credit Transfer', link: 'SEPA-credit-transfer' },
+          { title: 'International Credit Transfer', link: 'international-credit-transfer' },
+          { title: 'Account Reporting', link: 'account-deporting' },
+        ],
+      },
+      {
+        title: 'Wealth',
+        link: 'wealth-collections',
+        sub: [
+          { title: 'Liquidity & Cash Management', link: 'liquidity-cash-management' },
+          { title: 'Physcial Cash Management', link: 'physcial-cash-management' },
+          { title: 'Notional Cash Management', link: 'notional-cash-management' },
+          { title: 'Virtual Cash Management', link: 'virtual-cash-management' },
+          { title: 'Liquidity Management', link: 'liquidity-management' },
+          { title: 'Excess Cash', link: 'excess-cash' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Loyalty shop',
+    link: '#points',
+  },
+  {
+    title: 'Make an appointment',
+    link: '#appointment',
+  },
+  {
+    title: 'Products 2',
+    link: 'products-2',
+    sub: [
+      {
+        title: 'Payments',
+        link: 'payments-collections',
+        sub: [
+          { title: 'Payments & Collections', link: '#' },
+          { title: 'Merchant Commerce Solutions', link: 'merchant-commerce-solutions' },
+          { title: 'Instant Payments', link: 'instant-payments' },
+          { title: 'SEPA Direct Debit', link: 'SEPA-direct-debit' },
+          { title: 'SEPA Credit Transfer', link: 'SEPA-credit-transfer' },
+          { title: 'International Credit Transfer', link: 'international-credit-transfer' },
+          { title: 'Account Reporting', link: 'account-deporting' },
+        ],
+      },
+    ],
+  },
+
+  {
+    title: 'Products 3',
+    sub: [
+      {
+        title: 'Payments',
+        link: 'payments-collections',
+        sub: [
+          { title: 'Payments & Collections', link: '#' },
+          { title: 'Merchant Commerce Solutions', link: 'merchant-commerce-solutions' },
+          { title: 'Instant Payments', link: 'instant-payments' },
+          { title: 'SEPA Direct Debit', link: 'SEPA-direct-debit' },
+          { title: 'SEPA Credit Transfer', link: 'SEPA-credit-transfer' },
+          { title: 'International Credit Transfer', link: 'international-credit-transfer' },
+          { title: 'Account Reporting', link: 'account-deporting' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Loyalty shop 2',
+    link: '#points',
+  },
+  {
+    title: 'Make an appointment 2',
+    link: '#appointment',
+  },
+];
+
+const secondaryMenu = [
+  {
+    title: 'Back to old website',
+    link: 'https://www.ingwb.com',
+    target: '_self',
+    trackid: 'backToOldWebsite',
+  },
+];
+
+const ctaPrimary = {
+  id: 'cta-primary',
+  label: 'Log in',
+  href: '#login',
+};
+
+const ctaSecondary = {
+  id: 'cta-secondary',
+  label: 'Open an account',
+  href: '#open-account',
+};
+
+// N.B. these should be provided via api call
+const suggestions = ['A', 'B', 'C', 'D'];
+```
+
+```js preview-story
+export const navigationBar = () => {
+  return html`<demo-navigation-bar
+    .menuItems="${menuData}"
+    .menuSupportItems="${secondaryMenu}"
+    .ctaPrimary="${ctaPrimary}"
+    .ctaSecondary="${ctaSecondary}"
+    .suggestions="${suggestions}"
+  >
+    .prefilledSuggestion="${suggestions[0]}"</demo-navigation-bar
+  >`;
+};
+```

package/docs/components/menu/index.md

@@ -0,0 +1,13 @@
+---
+title: Menu
+parts:
+  - Menu
+eleventyNavigation:
+  key: Menu
+  order: 20
+  title: Menu
+---
+
+# Menu
+
+-> go to Overview

package/docs/components/menu/migration.md

@@ -0,0 +1,129 @@
+---
+title: 'Migration from the prerelease'
+parts:
+  - Menu
+  - Migration
+eleventyNavigation:
+  key: 'Menu: Migration'
+  order: 30
+  parent: Menu
+  title: Migration
+---
+
+# Migration from the prerelease
+
+The menu shipped as prereleases of `@lion/ui` (dist-tag `menu-system`, driven by the
+`.changeset/pre.json` pre-mode of the same name): `0.16.1-menu-system.N` from the 2021 branch and
+`0.21.1-menu-system.0`, the latest one published from this work in progress. It now lands as a regular
+minor of `@lion/ui`: pre-mode is left behind and `@lion/menu` (the `0.0.0` scratch manifest of the 2021
+branch) is gone. Everything below is about moving an implementation from those prereleases to this
+version.
+
+## 1. Package and entry points
+
+| prerelease                                                                            | now                                                                                                                                             |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@lion/ui@0.16.1-menu-system.N` ... `@lion/ui@0.21.1-menu-system.0`                   | the released `@lion/ui` minor                                                                                                                   |
+| `@lion/ui/exports/menu.js`                                                            | same path; exports `LionMenu`, `LionItem`, `LionMenuitem`                                                                                       |
+| `@lion/ui/define/lion-menu.js`                                                        | unchanged                                                                                                                                       |
+| `@lion/ui/define/lion-item.js`                                                        | unchanged                                                                                                                                       |
+| `@lion/ui/define/lion-menuitem.js`                                                    | new entry (see 3)                                                                                                                               |
+| `@lion/ui/define/lion-menu-overlay.js`, `.../lion-toolbar.js`, `.../lion-tree.js`     | removed                                                                                                                                         |
+| `@lion/ui/exports/menu-test-suites.js`                                                | same path; exports `runInteractiveListMixinSuite`, `runMultiLevelListMixinSuite`, `runLionMenuInteractionsSuite` (was `runLionMenuHybridSuite`) |
+| `@lion/ui/components/menu/index.js`, `.../menu/lion-menu.js`, `.../menu/package.json` | removed                                                                                                                                         |
+
+Only `@lion/ui/exports/*` and `@lion/ui/define/*` are in the package `exports` map, so the
+component paths (`@lion/ui/components/...`) were never importable — that has not changed.
+
+## 2. Components that left the package
+
+| prerelease          | now                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `LionMenuOverlay`   | the overlay integration (`OverlayWithListInvokerMixin`) lives on `LionMenu` itself: `openable-mode="overlay"` |
+| `LionMenuHybrid`    | same as above; `openable-mode="disclosure"` (the default) is the old disclosure behaviour                     |
+| `LionToolbar`       | `docs/components/menu/src/DemoToolbar.js` (`<demo-toolbar>`, a `LionMenu` with `bar`)                         |
+| `LionTree`          | `docs/components/menu/src/DemoTree.js` (`<demo-tree>`, a `MultiLevelListMixin` host with `role="tree"`)       |
+| `LionSpinbutton`    | `docs/components/menu/src/DemoSpinButton.js` (`<demo-spin-button>`)                                           |
+| `LionNavigationBar` | `docs/components/menu/src/DemoNavigationBar.js` (`<demo-navigation-bar>`)                                     |
+
+The tags `lion-tree`, `lion-toolbar`, `lion-spinbutton`, `lion-menu-overlay` and
+`lion-navigation-bar` are no longer registered anywhere. If you used one of those elements, either
+copy the demo implementation into your project (they are configuration on top of the same mixins) or
+configure the mixin yourself (`_listRole`, `_activeMode`, `bar`).
+
+## 3. Element definitions
+
+- `<lion-menu>`, `<lion-item>` and `<lion-menuitem>` keep their tag names.
+- `lion-menuitem` now has its own define entry. Before, importing
+  `components/menu/src/InteractiveListMixin.js` registered it as a side effect; importing the mixin no
+  longer defines any element.
+- Put your `customElements.define` calls (or the `@lion/ui/define/*` imports) in one place, as
+  before: the package's `sideEffects` list only covers the define entries.
+
+## 4. Api that did not change
+
+`LionMenu`, `LionItem` and `LionMenuitem` keep their tag names and the following properties, so
+implementations that only read or set those keep working: `selectionFollowsFocus` (the ARIA APG
+term, as on `ListboxMixin`), `itemWrap`, `activeIndex`, `checkedIndex`, `listItems`, `_activeMode`,
+`_listRole` (all from `InteractiveListMixin`), plus `bar` and `openableMode` on `LionMenu`.
+
+## 5. Renamed api: this component now speaks the focusgroup vocabulary
+
+The old names came from the 2021 branch; they are replaced by the
+[focusgroup](https://open-ui.org/components/focusgroup.explainer/) vocabulary, so implementations
+that follow the platform proposal find the same names here. This is a hard rename: the old names are
+gone.
+
+| prerelease                                            | now                              | note                                                                                                                                                          |
+| ----------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation="vertical"` / `orientation="horizontal"` | `axis="block"` / `axis="inline"` | `block` is the default; the attribute reflects                                                                                                                |
+| `rotateKeyboardNavigation`                            | `wrap`                           | the focusgroup axis/wrap modifiers                                                                                                                            |
+| `multipleChoice`                                      | `multiple`                       | the platform name (`<select multiple>`)                                                                                                                       |
+| `noPreselect`                                         | `hasNoDefaultSelected`           | the initial selectedness the platform calls "default selected" (`HTMLOptionElement.defaultSelected`); the same property and attribute exist on `ListboxMixin` |
+
+```html
+<lion-menu axis="inline" wrap multiple>
+  <lion-menuitem>Item 1</lion-menuitem>
+  <lion-menuitem>Item 2</lion-menuitem>
+</lion-menu>
+```
+
+Tokens of the focusgroup _attribute_ that are not part of this api: the behavior token (`menu`,
+`menubar`, `toolbar`, `listbox`, `tablist`, ...) is the role/active mode configuration
+(`_listRole`/`_activeMode`), `nomemory` has no counterpart (there is no focus-memory api here), and
+`focusgroupstart` / `focusgroup="none"` are not mapped. The platform attribute itself is not read by
+this component: on Chrome 150 and newer the browser acts on it when it is present in the dom, so do
+not put it on a lion element together with the properties below (native focusgroup behavior and this
+mixin's keyboard handling would both apply).
+
+## 6. Api that is new
+
+| api                            | change                                                                                                                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OverlayConfig`                | accepts `placementMode: 'custom'`, `syncChildrenCloseState`, `elementToFocusOnShow`, `isActivated`, `requireConnectedNodes`                                                            |
+| `@lion/ui/exports/overlays.js` | exports `withClickInteraction` and `withHoverInteraction`                                                                                                                              |
+| types                          | `components/menu/types/*` are emitted `.ts` now; in the prerelease `InteractiveListMixinTypes.d.ts` was an input file that never reached `dist-types`, so editors could not resolve it |
+
+## 7. Migration checklist
+
+1. Replace the prerelease dependency with the released `@lion/ui` version and drop any
+   `menu-system` dist-tag pin (`0.16.1-menu-system.N` up to `0.21.1-menu-system.0`).
+2. Keep the `@lion/ui/exports/menu.js` and `@lion/ui/define/*` imports; no element was renamed.
+3. Rename the properties: `orientation` -> `axis` (value `vertical` -> `block`, `horizontal` ->
+   `inline`), `rotateKeyboardNavigation` -> `wrap`, `multipleChoice` -> `multiple`. The attribute
+   names follow the property names.
+4. Replace `LionMenuHybrid`/`LionMenuOverlay` usage with `LionMenu` + `openable-mode`, and
+   `LionToolbar`/`LionTree`/`LionSpinbutton`/`LionNavigationBar` with your own copy of the demo
+   implementations.
+5. Import `@lion/ui/define/lion-menuitem.js` if you relied on the side-effect definition of
+   `lion-menuitem`.
+6. If you called `runLionMenuHybridSuite`, call `runLionMenuInteractionsSuite` instead.
+
+## 8. Not covered yet
+
+- The mixins themselves (`InteractiveListMixin`, `MultiLevelListMixin`, `MoreButtonMenuMixin`,
+  `OverlayWithListInvokerMixin`) are not re-exported from `@lion/ui/exports/menu.js`, and deep
+  component paths are not in the package `exports` map. If you extend one of them, the test suites in
+  `@lion/ui/exports/menu-test-suites.js` are the supported surface; your own copy of the mixin is the
+  workaround until that is decided.
+- The `MoreButtonMenuMixin` item-wrap strategy is still "more-menu" only (`itemWrap`).