@lion/ui 0.22.0 → 0.23.0

package/README.md

@@ -112,6 +112,41 @@ They provide an unopinionated, white-label layer that can be extended to your ow
 npm i @lion/ui
 ```
 
+### Temporary phone-number metadata workaround
+
+We temporarily vendor `awesome-phonenumber@7.9.0-tlouisse.libphonenumber-9.0.41`,
+rebuilt from Google's **libphonenumber v9.0.41**, instead of the registry dependency.
+This includes updated phone-number metadata, such as the French Guiana premium-rate
+example `+594890123456`, which the previous `awesome-phonenumber@7.8.0` rejected.
+We keep this workaround until the next upstream awesome-phonenumber release
+incorporating the required metadata is available.
+
+The artifact lives in `packages/ui/vendor/awesome-phonenumber-7.9.0-tlouisse.libphonenumber-9.0.41.tgz`.
+`@lion/ui` uses a package-relative `file:vendor/...` dependency and bundles the
+installed `awesome-phonenumber` package when published. This preserves normal
+consumer installation and lazy imports without access to the Lion checkout.
+The private root also declares the same tarball as a development dependency so
+npm installs it during a clean workspace install rather than assuming the
+workspace already contains its bundled dependencies. The legacy docs dependency
+keeps its separate registry version.
+The temporary `prepack` helper verifies the checksum and installs only the tarball
+in an isolated temporary prefix using npm's offline mode (without running dependency
+scripts or writing a lockfile). It copies that installed package into the local
+bundle and removes the temporary prefix, because npm packing does not include
+hoisted workspace bundles. Other Lion dependencies remain unchanged.
+The original MIT license and Google's Apache-2.0 notices remain in the artifact
+and bundled package. See [vendor provenance](https://github.com/ing-bank/lion/blob/4649554021224763994601dd8d202c511d35013e/packages/ui/vendor/README.md) for the
+source commit, checksum, and reproducible packaging instructions.
+
+Once the next upstream awesome-phonenumber release includes the required
+metadata, restore the normal registry dependency in `packages/ui/package.json`,
+remove `awesome-phonenumber` from `bundledDependencies`, remove the vendor asset
+and its `files` entry, remove the root development dependency, and regenerate
+`package-lock.json`. Remove the temporary `prepack` lifecycle and
+`scripts/prepare-vendored-phone.js` helper as well. Keep the metadata
+regression test and rerun the phone tests, typechecks, and packed-consumer install
+check before removing this workaround documentation.
+
 ## How to use
 
 ### Extend a Web Component

package/components/combobox/src/LionCombobox.js

@@ -13,6 +13,10 @@ const matchA11ySpanReverseFns = new WeakMap();
 // TODO: make ListboxOverlayMixin that is shared between SelectRich and Combobox
 // TODO: extract option matching based on 'typed character cache' and share that logic
 // on Listbox or ListNavigationWithActiveDescendantMixin
+// TODO: this component inherits `multipleChoice` (ChoiceGroupMixin) and `rotateKeyboardNavigation`
+// (ListboxMixin) and reads both in many places. When those are renamed to `multiple` and `wrap`, move
+// these usages to the new names in the same release; the deprecated aliases only exist for consumers.
+// See the TODO at the top of ../../listbox/src/ListboxMixin.js.
 
 /**
  * @typedef {import('@lion/ui/listbox.js').LionOption} LionOption
@@ -1228,9 +1232,13 @@ export class LionCombobox extends LocalizeMixin(OverlayMixin(CustomChoiceGroupMi
    * @param {{phase?:string}} config
    * @protected
    */
-  // eslint-disable-next-line no-unused-vars
   _syncToTextboxCondition(modelValue, oldModelValue, { phase } = {}) {
-    return this.autocomplete === 'both' || this.autocomplete === 'inline' || !this.focused;
+    return (
+      phase === 'overlay-close' ||
+      this.autocomplete === 'both' ||
+      this.autocomplete === 'inline' ||
+      !this.focused
+    );
   }
 
   /**

package/components/combobox/test/lion-combobox.test.js

@@ -1392,6 +1392,37 @@ describe('lion-combobox', () => {
       expect(el.opened).to.equal(true);
     });
 
+    it('syncs a manually checked selection on overlay close while the input remains focused', async () => {
+      const el = /** @type {LionCombobox} */ (
+        await fixture(html`
+          <lion-combobox name="foo" autocomplete="list">
+            <lion-option .choiceValue="${'Artichoke'}">Artichoke</lion-option>
+            <lion-option .choiceValue="${'Chard'}">Chard</lion-option>
+          </lion-combobox>
+        `)
+      );
+      const { _inputNode } = getComboboxMembers(el);
+
+      _inputNode.focus();
+      el.opened = true;
+      await el.updateComplete;
+      expect(el.opened).to.equal(true);
+      expect(isActiveElement(_inputNode)).to.be.true;
+
+      el.setCheckedIndex(0);
+      await el.updateComplete;
+
+      expect(el.modelValue).to.equal('Artichoke');
+      expect(el.checkedIndex).to.equal(0);
+      expect(_inputNode.value).to.equal('');
+
+      el.opened = false;
+      await el.updateComplete;
+
+      expect(_inputNode.value).to.equal('Artichoke');
+      expect(isActiveElement(_inputNode)).to.be.true;
+    });
+
     it('hides (and clears) overlay on [Escape]', async () => {
       const el = /** @type {LionCombobox} */ (
         await fixture(html`

package/components/form-core/src/choice-group/ChoiceGroupMixin.js

@@ -30,6 +30,13 @@ const ChoiceGroupMixinImplementation = /** @type {ChoiceGroupMixin} */ (supercla
     /** @type {any} */
     static get properties() {
       return {
+        // TODO: rename to `multiple` (the platform name, `<select multiple>`) so it matches the
+        // vocabulary the menu's InteractiveListMixin uses. Must be non-breaking for the released
+        // components that inherit it (listbox/select-rich/combobox, radio-group/checkbox-group): add
+        // `multiple` with its own attribute, keep `multipleChoice`/`multiple-choice` as a deprecated
+        // alias that delegates to it (dev-only deprecation warning) for a release, mark it
+        // `@deprecated` only then and remove the alias in the next major. Coordinate with the TODOs in
+        // packages/ui/components/listbox/src/ListboxMixin.js and combobox/src/LionCombobox.js.
         multipleChoice: { type: Boolean, attribute: 'multiple-choice' },
       };
     }

package/components/form-core/types/choice-group/ChoiceGroupMixinTypes.ts

@@ -7,6 +7,11 @@ import { FormRegistrarHost } from '../registration/FormRegistrarMixinTypes.js';
 import { ChoiceInputHost } from './ChoiceInputMixinTypes.js';
 
 export declare class ChoiceGroupHost extends FormControlHost {
+  /**
+   * TODO: rename to `multiple` (the platform name, `<select multiple>`), non-breaking: keep this
+   * property and the `multiple-choice` attribute as a deprecated alias for a release before removing
+   * them in a major. See the TODO in src/choice-group/ChoiceGroupMixin.js.
+   */
   multipleChoice: boolean;
   get serializedValue(): string;
   set serializedValue(value: string);

package/components/input-amount/src/LionInputAmount.js

@@ -7,7 +7,7 @@ import { parseAmount } from './parsers.js';
 
 /**
  * @typedef {import('../../form-core/types/FormatMixinTypes.js').FormatOptions} FormatOptions
- * @typedef {FormatOptions & {locale?:string;currency:string|undefined}} AmountFormatOptions
+ * @typedef {FormatOptions & {locale?:string;currency:string|undefined;currencySymbol:string|undefined;}} AmountFormatOptions
  */
 
 /**
@@ -25,6 +25,10 @@ export class LionInputAmount extends LocalizeMixin(LionInput) {
        * reader users
        */
       currency: String,
+      currencyLabel: {
+        type: String,
+        attribute: 'currency-label',
+      },
       /**
        * @desc the modelValue of the input-amount has the 'Number' type. This allows
        * Application Developers to easily read from and write to this input or write custom
@@ -71,6 +75,7 @@ export class LionInputAmount extends LocalizeMixin(LionInput) {
     this.formatter = formatAmount;
     /** @type {string | undefined} */
     this.currency = undefined;
+    this.currencyLabel = '';
     /** @type {string | undefined} */
     this.locale = undefined;
     this.__currencyDisplayNodeIsConnected = true;
@@ -201,19 +206,25 @@ export class LionInputAmount extends LocalizeMixin(LionInput) {
 
   /** @private */
   __setCurrencyDisplayLabel() {
-    // TODO: (@erikkroes) for optimal a11y, abbreviations should be part of aria-label
-    // example, for a language switch with text 'en', an aria-label of 'english' is not
-    // sufficient, it should also contain the abbreviation.
     if (this.__currencyDisplayNode) {
+      const label = this.currencyLabel || this.currency || '';
+      let currencyName = '';
+      if (this.currency) {
+        currencyName = getCurrencyName(this.currency, {});
+      }
       this.__currencyDisplayNode.setAttribute(
         'aria-label',
-        this.currency ? getCurrencyName(this.currency, {}) : '',
+        `${label} ${currencyName ? `(${currencyName})` : ''}`,
       );
     }
   }
 
   get __currencyLabel() {
-    return this.currency ? formatCurrencyLabel(this.currency, this._localizeManager.locale) : '';
+    let label = this.currencyLabel || '';
+    if (!label && this.currency) {
+      label = formatCurrencyLabel(this.currency, this._localizeManager.locale);
+    }
+    return label;
   }
 
   __reformat() {

package/components/input-amount/src/formatters.js

@@ -5,17 +5,18 @@ import {
 } from '@lion/ui/localize-no-side-effects.js';
 
 /**
- * @typedef {import('../../localize/types/LocalizeMixinTypes.js').FormatNumberOptions} FormatOptions
+ * @typedef {import('../../localize/types/LocalizeMixinTypes.js').FormatNumberOptions} FormatNumberOptions
+ * @typedef {import('../../localize/types/LocalizeMixinTypes.js').FormatNumberPart} FormatNumberPart
  */
 
 /**
  * Formats a number considering the default fraction digits provided by Intl.
  *
  * @param {number} modelValue Number to format
- * @param {FormatOptions} [givenOptions]
+ * @param {FormatNumberOptions} [givenOptions]
  */
 export function formatAmount(modelValue, givenOptions) {
-  /** @type {FormatOptions} */
+  /** @type {FormatNumberOptions} */
   const options = {
     currency: 'EUR',
     ...givenOptions,
@@ -40,5 +41,6 @@ export function formatCurrencyLabel(currency, locale) {
   if (currency === '') {
     return '';
   }
+
   return normalizeCurrencyLabel(currency, locale);
 }

package/components/input-amount/test/formatters.test.js

@@ -3,86 +3,100 @@ import { getLocalizeManager } from '@lion/ui/localize-no-side-effects.js';
 import { localizeTearDown } from '@lion/ui/localize-test-helpers.js';
 
 import { formatAmount } from '@lion/ui/input-amount.js';
+import { formatCurrencyLabel } from '../src/formatters.js';
 
-describe('formatAmount()', () => {
-  const localizeManager = getLocalizeManager();
+describe('formatters', () => {
+  describe('formatAmount()', () => {
+    const localizeManager = getLocalizeManager();
 
-  afterEach(() => {
-    localizeTearDown();
-  });
+    afterEach(() => {
+      localizeTearDown();
+    });
 
-  it('formats number with options', async () => {
-    expect(
-      formatAmount(12.345678, {
-        locale: 'en-GB',
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
-      }),
-    ).to.equal('12.35');
-    expect(
-      formatAmount(12.345678, {
-        locale: 'nl-NL',
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
-      }),
-    ).to.equal('12,35');
-    expect(
-      formatAmount(12345678, {
-        locale: 'en-GB',
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
-      }),
-    ).to.equal('12,345,678.00');
-    expect(
-      formatAmount(12345678, {
-        locale: 'nl-NL',
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
-      }),
-    ).to.equal('12.345.678,00');
-    expect(
-      formatAmount(12.345678, {
-        locale: 'en-GB',
-        minimumFractionDigits: 0,
-        maximumFractionDigits: 1,
-      }),
-    ).to.equal('12.3');
-    expect(
-      formatAmount(12.345678, {
-        locale: 'en-GB',
-        minimumFractionDigits: 3,
-        maximumFractionDigits: 3,
-      }),
-    ).to.equal('12.346');
-    expect(
-      formatAmount(-12.345678, {
-        locale: 'en-GB',
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
-      }),
-    ).to.equal('−12.35');
-  });
+    it('formats number with options', async () => {
+      expect(
+        formatAmount(12.345678, {
+          locale: 'en-GB',
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }),
+      ).to.equal('12.35');
+      expect(
+        formatAmount(12.345678, {
+          locale: 'nl-NL',
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }),
+      ).to.equal('12,35');
+      expect(
+        formatAmount(12345678, {
+          locale: 'en-GB',
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }),
+      ).to.equal('12,345,678.00');
+      expect(
+        formatAmount(12345678, {
+          locale: 'nl-NL',
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }),
+      ).to.equal('12.345.678,00');
+      expect(
+        formatAmount(12.345678, {
+          locale: 'en-GB',
+          minimumFractionDigits: 0,
+          maximumFractionDigits: 1,
+        }),
+      ).to.equal('12.3');
+      expect(
+        formatAmount(12.345678, {
+          locale: 'en-GB',
+          minimumFractionDigits: 3,
+          maximumFractionDigits: 3,
+        }),
+      ).to.equal('12.346');
+      expect(
+        formatAmount(-12.345678, {
+          locale: 'en-GB',
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }),
+      ).to.equal('−12.35');
+    });
 
-  it('formats the right amount of fraction digits for a certain currency', async () => {
-    expect(formatAmount(123456.78, { locale: 'en-GB', currency: 'EUR' })).to.equal('123,456.78');
-    expect(formatAmount(123456.78, { locale: 'en-GB', currency: 'JOD' })).to.equal('123,456.780');
-  });
+    it('formats the right amount of fraction digits for a certain currency', async () => {
+      expect(formatAmount(123456.78, { locale: 'en-GB', currency: 'EUR' })).to.equal('123,456.78');
+      expect(formatAmount(123456.78, { locale: 'en-GB', currency: 'JOD' })).to.equal('123,456.780');
+    });
 
-  it('fallbacks to global locale and EUR by default', async () => {
-    localizeManager.locale = 'en-GB';
-    expect(formatAmount(12345678)).to.equal('12,345,678.00');
-    localizeManager.locale = 'nl-NL';
-    expect(formatAmount(12345678)).to.equal('12.345.678,00');
+    it('fallbacks to global locale and EUR by default', async () => {
+      localizeManager.locale = 'en-GB';
+      expect(formatAmount(12345678)).to.equal('12,345,678.00');
+      localizeManager.locale = 'nl-NL';
+      expect(formatAmount(12345678)).to.equal('12.345.678,00');
+    });
+
+    // TODO: make it work with big numbers, e.g. make use of BigInt
+    it.skip('rounds up big numbers', async () => {
+      expect(formatAmount(1e21, { locale: 'en-GB', currency: 'EUR' })).to.equal(
+        '1,000,000,000,000,000,000,000.00',
+      );
+      // eslint-disable-next-line no-loss-of-precision
+      expect(formatAmount(12345678987654321.42, { locale: 'en-GB', currency: 'EUR' })).to.equal(
+        '12,345,678,987,654,321.42',
+      );
+    });
   });
 
-  // TODO: make it work with big numbers, e.g. make use of BigInt
-  it.skip('rounds up big numbers', async () => {
-    expect(formatAmount(1e21, { locale: 'en-GB', currency: 'EUR' })).to.equal(
-      '1,000,000,000,000,000,000,000.00',
-    );
-    // eslint-disable-next-line no-loss-of-precision
-    expect(formatAmount(12345678987654321.42, { locale: 'en-GB', currency: 'EUR' })).to.equal(
-      '12,345,678,987,654,321.42',
-    );
+  describe('formatCurrencyLabel()', () => {
+    it('gives back the correct currency label', async () => {
+      expect(formatCurrencyLabel('EUR', 'en-GB')).to.equal('EUR');
+      expect(formatCurrencyLabel('USD', 'en-GB')).to.equal('USD');
+    });
+
+    it('gives nothing back if no currency has been provided', async () => {
+      expect(formatCurrencyLabel('', 'en-GB')).to.equal('');
+    });
   });
 });

package/components/input-amount/test/lion-input-amount.test.js

@@ -225,42 +225,57 @@ describe('<lion-input-amount>', () => {
     expect(_inputNode.type).to.equal('text');
   });
 
-  it('shows no currency by default', async () => {
-    const el = await fixture(`<lion-input-amount></lion-input-amount>`);
-    expect(Array.from(el.children).find(child => child.slot === 'after')).to.be.undefined;
-  });
+  describe('currencyLabel', async () => {
+    it('shows no currency by default', async () => {
+      const el = await fixture(`<lion-input-amount></lion-input-amount>`);
+      expect(Array.from(el.children).find(child => child.slot === 'after')).to.be.undefined;
+    });
 
-  it('displays currency if provided', async () => {
-    const el = /** @type {LionInputAmount} */ (
-      await fixture(`<lion-input-amount currency="EUR"></lion-input-amount>`)
-    );
-    expect(
-      /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
-        ?.innerText,
-    ).to.equal('EUR');
-  });
+    it('displays currency if provided', async () => {
+      const el = /** @type {LionInputAmount} */ (
+        await fixture(`<lion-input-amount currency="EUR"></lion-input-amount>`)
+      );
+      expect(
+        /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
+          ?.innerText,
+      ).to.equal('EUR');
+    });
 
-  it('displays correct currency for TRY if locale is tr-TR', async () => {
-    localize.locale = 'tr-TR';
-    const el = /** @type {LionInputAmount} */ (
-      await fixture(`<lion-input-amount currency="TRY"></lion-input-amount>`)
-    );
-    expect(
-      /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
-        ?.innerText,
-    ).to.equal('TL');
-  });
+    it('displays correct currency for TRY if locale is tr-TR', async () => {
+      localize.locale = 'tr-TR';
+      const el = /** @type {LionInputAmount} */ (
+        await fixture(`<lion-input-amount currency="TRY"></lion-input-amount>`)
+      );
+      expect(
+        /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
+          ?.innerText,
+      ).to.equal('TL');
+    });
 
-  it('can update currency', async () => {
-    const el = /** @type {LionInputAmount} */ (
-      await fixture(`<lion-input-amount currency="EUR"></lion-input-amount>`)
-    );
-    el.currency = 'USD';
-    await el.updateComplete;
-    expect(
-      /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
-        ?.innerText,
-    ).to.equal('USD');
+    it('displays currency symbol if provided via formatOptions', async () => {
+      const el = /** @type {LionInputAmount} */ (
+        await fixture(
+          html`<lion-input-amount currency="EUR" currency-label="€"></lion-input-amount>`,
+        )
+      );
+      const currLabel = /** @type {HTMLElement[]} */ (Array.from(el.children)).find(
+        child => child.slot === 'after',
+      );
+      expect(currLabel?.innerText).to.equal('€');
+      expect(currLabel?.getAttribute('aria-label')).to.equal('€ (euros)');
+    });
+
+    it('can update currency', async () => {
+      const el = /** @type {LionInputAmount} */ (
+        await fixture(`<lion-input-amount currency="EUR"></lion-input-amount>`)
+      );
+      el.currency = 'USD';
+      await el.updateComplete;
+      expect(
+        /** @type {HTMLElement[]} */ (Array.from(el.children)).find(child => child.slot === 'after')
+          ?.innerText,
+      ).to.equal('USD');
+    });
   });
 
   it('reformats on locale changes', async () => {
@@ -311,7 +326,7 @@ describe('<lion-input-amount>', () => {
       child => child.slot === 'after',
     );
     expect(currLabel?.innerText).to.equal('EUR');
-    expect(currLabel?.getAttribute('aria-label')).to.equal('euros');
+    expect(currLabel?.getAttribute('aria-label')).to.equal('EUR (euros)');
   });
 
   it('sets currency label on the after element', async () => {
@@ -416,10 +431,10 @@ describe('<lion-input-amount>', () => {
       const label = /** @type {HTMLElement[]} */ (Array.from(el.children)).find(
         child => child.slot === 'after',
       );
-      expect(label?.getAttribute('aria-label')).to.equal('euros');
+      expect(label?.getAttribute('aria-label')).to.equal('EUR (euros)');
       el.currency = 'USD';
       await el.updateComplete;
-      expect(label?.getAttribute('aria-label')).to.equal('US dollars');
+      expect(label?.getAttribute('aria-label')).to.equal('USD (US dollars)');
       el.currency = 'PHP';
       await el.updateComplete;
       // TODO: Chrome Intl now thinks this should be pesos instead of pisos. They're probably right.

package/components/input-tel/test/validators.test.js

@@ -46,6 +46,15 @@ describe('PhoneNumber validation', () => {
     expect(validator.execute('+31612345678', 'NL')).to.be.false;
   });
 
+  it('accepts the French Guiana premium-rate example from libphonenumber v9.0.41', () => {
+    const validator = new PhoneNumber();
+    expect(validator.execute('+594890123456', 'GF')).to.be.false;
+    const parsed = PhoneUtilManager.PhoneUtil.parsePhoneNumber('+594890123456');
+    expect(parsed.valid).to.be.true;
+    expect(parsed.type).to.equal('premium-rate');
+    expect(parsed.regionCode).to.equal('GF');
+  });
+
   it('handles validation via awesome-phonenumber', () => {
     const validator = new PhoneNumber();
     // @ts-ignore

package/components/listbox/src/ListboxMixin.js

@@ -6,9 +6,21 @@ import { ScopedElementsMixin } from '../../core/src/ScopedElementsMixin.js';
 import { LionOptions } from './LionOptions.js';
 import { moveUserProvidedDefaultSlottablesToTarget } from '../../core/src/SlotMixin.js';
 
-// TODO: extract ListNavigationWithActiveDescendantMixin that can be reused in [role="menu"]
-// having children with [role="menuitem|menuitemcheckbox|menuitemradio|option"] and
-// list items that can be found via MutationObserver or registration (.formElements)
+// TODO: make this mixin reuse the interactive-list implementation instead of its own copy of the
+// navigation logic. The extraction this TODO used to ask for ("ListNavigationWithActiveDescendantMixin
+// that can be reused in [role="menu"]") now exists as `InteractiveListMixin`, the base of the menu
+// components (packages/ui/components/menu). Rebasing this mixin on it is also what makes the next step
+// possible, without breaking consumers in between:
+//   - rename the api to the focusgroup/platform vocabulary the menu already speaks:
+//     `orientation` ('vertical'/'horizontal') -> `axis` ('block'/'inline'),
+//     `rotateKeyboardNavigation` -> `wrap`, `multipleChoice` -> `multiple`
+//   - map the new axis values to the ARIA ones where `aria-orientation` is set (block -> vertical,
+//     inline -> horizontal); ARIA does not know the focusgroup tokens
+//   - keep the old properties and attributes working in the same release: add the new property with
+//     its own attribute, turn the old one into a deprecated alias that delegates to it (with a
+//     dev-only deprecation warning) and mark it `@deprecated` in ListboxMixinTypes, then remove the
+//     aliases in the next major
+//   - `hasNoDefaultSelected` and `selectionFollowsFocus` can stay: the menu uses those names too
 
 /**
  * @typedef {import('../../form-core/types/FormControlMixinTypes.js').HTMLElementWithValue} HTMLElementWithValue
@@ -34,11 +46,15 @@ const ListboxMixinImplementation = /** @type {ListboxMixin} */ (superclass =>
     /** @type {any} */
     static get properties() {
       return {
+        // TODO: rename to `axis` with the values 'block'|'inline' (see the TODO at the top of this
+        // file); keep `orientation`/`orientation="vertical"|"horizontal"` working as a deprecated alias
         orientation: String,
         selectionFollowsFocus: {
           type: Boolean,
           attribute: 'selection-follows-focus',
         },
+        // TODO: rename to `wrap` (see the TODO at the top of this file); keep the old property and
+        // attribute working as a deprecated alias
         rotateKeyboardNavigation: {
           type: Boolean,
           attribute: 'rotate-keyboard-navigation',

package/components/listbox/types/ListboxMixinTypes.ts

@@ -25,7 +25,13 @@ export declare class ListboxHost {
   public rotateKeyboardNavigation: Boolean;
   /**
    * Informs screen reader and affects keyboard navigation.
-   * By default 'vertical'
+   * By default 'vertical'.
+   *
+   * TODO: rename to `axis: 'inline' | 'block'` (the vocabulary the menu's `InteractiveListMixin` uses),
+   * together with `rotateKeyboardNavigation` -> `wrap` and `multipleChoice` -> `multiple`. Must be
+   * non-breaking: the old properties and their attributes stay available as deprecated aliases for a
+   * release (dev-only deprecation warning), and only then get `@deprecated` here and disappear in a
+   * major. See the TODO at the top of src/ListboxMixin.js.
    */
   public orientation: 'vertical' | 'horizontal';