@lion/ui 0.22.0 → 0.23.0

package/components/menu/types/InteractiveListMixinTypes.ts

@@ -0,0 +1,126 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { SlotHost } from '../../core/types/SlotMixinTypes.js';
+import { DisabledHost } from '../../core/types/DisabledMixinTypes.js';
+
+export type InteractiveListItemRole =
+  | 'menuitem'
+  | 'menuitemcheckbox'
+  | 'menuitemradio'
+  | 'option'
+  | 'treeitem'
+  | 'radio'
+  | 'checkbox';
+
+export declare class InteractiveListHost extends LitElement {
+  /**
+   * When true, will synchronize activedescendant and selected element on
+   * arrow key navigation.
+   * This behavior can usually be seen on <select> on the Windows platform.
+   * Note that this behavior cannot be used when `multiple` is true.
+   * "Selection follows focus" is the ARIA APG term for this behaviour, see
+   * https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ (the same property exists on
+   * `ListboxMixin`).
+   */
+  public selectionFollowsFocus: Boolean;
+  /**
+   * Whether arrow key navigation wraps around at the first/last item: the `wrap` modifier of the
+   * [focusgroup](https://open-ui.org/components/focusgroup.explainer/) api.
+   */
+  public wrap: Boolean;
+  /**
+   * The axis arrow keys navigate along, in the vocabulary of the
+   * [focusgroup](https://open-ui.org/components/focusgroup.explainer/) api: `'block'`
+   * (default: up/down) or `'inline'` (left/right). Informs screen reader and affects keyboard
+   * navigation.
+   */
+  public axis: 'inline' | 'block';
+
+  /** Whether more than one item can be checked (the platform name in `<select multiple>`) */
+  public multiple: Boolean;
+
+  /** Whether items that do not fit are moved into a 'more' menu (see MoreButtonMenuMixin) */
+  public itemWrap: Boolean;
+
+  /**
+   * When true, no option is selected on initial render (`checkedIndex` stays -1). Named the same as
+   * on `ListboxMixin`; the platform calls the initial selectedness "default selected".
+   */
+  /** The item that currently has the active state */
+  public get activeItem(): HTMLElement;
+
+  public set activeItem(item: HTMLElement);
+
+  /** Element members the mixin body uses on itself (restated: `this` is resolved through this host) */
+  children: HTMLCollection;
+  shadowRoot: ShadowRoot;
+  childNodes: NodeListOf<ChildNode>;
+  localName: string;
+  disabled: boolean;
+
+  public hasNoDefaultSelected: boolean;
+
+  public singleOption: boolean;
+
+  public get checkedIndex(): number | number[];
+
+  public set checkedIndex(index: number | number[]);
+
+  public get activeIndex(): number;
+
+  public set activeIndex(index: number);
+
+  public get listItems(): HTMLElement[];
+
+  public setCheckedIndex(index: number): void;
+
+  protected get _scrollTargetNode(): HTMLElement;
+
+  protected get _invokerNode(): HTMLElement | null | undefined;
+
+  protected set _invokerNode(invokerNode: HTMLElement | null | undefined);
+
+  protected get _listNode(): HTMLElement;
+
+  /** One of 'activedescendant', 'roving-tabindex', 'tabbable-disclosure' or 'none' */
+  protected _activeMode: string;
+
+  /** The role put on the list node: 'menu' | 'menubar' | 'listbox' | 'tree' | 'toolbar' */
+  protected _listRole: string;
+
+  protected _initListItems(newItems: Element[]): void;
+
+  protected _syncCurrentPageWithLocationHref(location: Location): void;
+
+  // private __setupListboxNode(): void;
+
+  protected _getPreviousEnabledOption(currentIndex: number, offset?: number): number;
+
+  protected _getNextEnabledOption(currentIndex: number, offset?: number): number;
+
+  protected _onListKeyDown(ev: KeyboardEvent): void;
+
+  protected _onListKeyUp(ev: KeyboardEvent): void;
+
+  // protected _setupListboxNode(): void;
+
+  // protected _teardownListboxNode(): void;
+
+  protected _onListClick(ev: MouseEvent): void;
+
+  // protected _setupListboxInteractions(): void;
+
+  // protected _onChildActiveChanged(ev: Event): void;
+}
+
+export declare function InteractiveListMixinImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<InteractiveListHost> &
+  Pick<typeof InteractiveListHost, keyof typeof InteractiveListHost> &
+  Constructor<DisabledHost> &
+  Pick<typeof DisabledHost, keyof typeof DisabledHost> &
+  Constructor<SlotHost> &
+  Pick<typeof SlotHost, keyof typeof SlotHost>;
+
+export type InteractiveListMixin = typeof InteractiveListMixinImplementation;

package/components/menu/types/MoreButtonMenuMixinTypes.ts

@@ -0,0 +1,51 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { InteractiveListHost } from './InteractiveListMixinTypes.js';
+
+/**
+ * The 'more' button pattern: items that do not fit are moved into a sub menu behind a more
+ * button. See `MoreButtonMenuMixin`.
+ */
+export declare class MoreButtonMenuHost extends InteractiveListHost {
+  protected _initMoreButtonMenu(): void;
+
+  protected _getDeepActiveElement(): Element | null;
+
+  protected _createMoreButtonWrapper(): void;
+
+  getMoreButtonSlotProjection(): Element | null;
+
+  getMoreButtonMenu(): Element | null;
+
+  getMoreButtonMenuWrapper(): Element | null;
+
+  displayMoreButton(): void;
+
+  hideMoreButton(): void;
+
+  doItemsFit(): boolean;
+
+  getListItems(): Element[];
+
+  moveItemToMoreButtonMenuFromMainMenu(params: {
+    moreButtonMenuElement: HTMLElement;
+    listItem: HTMLElement;
+  }): void;
+
+  moveAllItemsToMainMenuFromMoreButtonMenu(): void;
+
+  renderAllItemsInMainMenu(): void;
+
+  hideItemsOneByOneInMainMenuUntilTheyFit(): void;
+
+  moveHiddenItemsFromMainMenuToMoreButtonMenu(hiddenItemsCount: number): void;
+}
+
+export declare function MoreButtonMenuImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<MoreButtonMenuHost> &
+  Pick<typeof MoreButtonMenuHost, keyof typeof MoreButtonMenuHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type MoreButtonMenuMixin = typeof MoreButtonMenuImplementation;

package/components/menu/types/MultiLevelListMixinTypes.ts

@@ -0,0 +1,28 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { InteractiveListHost } from './InteractiveListMixinTypes.js';
+
+/** Multiple nested, collapsible levels on top of an interactive list (see `MultiLevelListMixin`) */
+export declare class MultiLevelListHost extends InteractiveListHost {
+  /** The nesting level of this list; 1 for the top level list */
+  level: number;
+
+  protected _subListMap: Map<Element, MultiLevelListHost>;
+
+  protected get _invokerNode(): HTMLElement | null | undefined;
+
+  protected set _invokerNode(invokerNode: HTMLElement | null | undefined);
+
+  protected get _contentNode(): HTMLElement;
+
+  toggle(ev: Event): void;
+}
+
+export declare function MultiLevelListImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<MultiLevelListHost> &
+  Pick<typeof MultiLevelListHost, keyof typeof MultiLevelListHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type MultiLevelListMixin = typeof MultiLevelListImplementation;

package/components/menu/types/OverlayWithListInvokerMixinTypes.ts

@@ -0,0 +1,61 @@
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { LitElement } from 'lit';
+import { OverlayConfig } from '../../overlays/types/OverlayConfig.js';
+import { DefineOverlayConfig } from '../../overlays/types/OverlayMixinTypes.js';
+import { OverlayController } from '../../overlays/src/OverlayController.js';
+import { InteractiveListHost } from './InteractiveListMixinTypes.js';
+
+/**
+ * The overlay side of a list host: the members `OverlayMixin` declares, on top of the list host
+ * (`OverlayWithListInvokerMixin`, used by `LionMenu`).
+ */
+export declare class OverlayWithListInvokerHost extends InteractiveListHost {
+  opened: Boolean;
+
+  get config(): Partial<OverlayConfig>;
+
+  set config(value: Partial<OverlayConfig>);
+
+  open(): Promise<void>;
+
+  close(): Promise<void>;
+
+  toggle(): Promise<void>;
+
+  repositionOverlay(): void;
+
+  _onOverlayShow(): void;
+
+  protected _overlayCtrl: OverlayController;
+
+  protected get _overlayInvokerNode(): HTMLElement;
+
+  protected get _overlayBackdropNode(): HTMLElement;
+
+  protected get _overlayContentNode(): HTMLElement;
+
+  protected get _overlayContentWrapperNode(): HTMLElement;
+
+  protected _defineOverlay(config: DefineOverlayConfig): OverlayController;
+
+  protected _defineOverlayConfig(): OverlayConfig;
+
+  protected _setupOpenCloseListeners(): void;
+
+  protected _teardownOpenCloseListeners(): void;
+
+  protected _setupOverlayCtrl(): void;
+
+  protected _teardownOverlayCtrl(): void;
+
+  protected _setOpenedWithoutPropertyEffects(newOpened: Boolean): Promise<undefined>;
+}
+
+export declare function OverlayWithListInvokerImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<OverlayWithListInvokerHost> &
+  Pick<typeof OverlayWithListInvokerHost, keyof typeof OverlayWithListInvokerHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type OverlayWithListInvokerMixin = typeof OverlayWithListInvokerImplementation;

package/components/overlays/NEXT.md

@@ -0,0 +1,49 @@
+- Redesign goals OverlayController
+  - Simplicity
+    - One primitive to (controller to) rule them all
+      - Aligned api with all disclosure mechanisms (openables: <https://open-ui.org/components/openable.explainer/>)
+      - Aligned with platform overlay primitives (popover, dialog and tooltip)
+    - Controller will be elegantly aligned with host
+      - Controller props will be mapped to a host via a mixin, w/o requiring lots of boilerplate
+      - No race conditions due to unaligned heart beats: both hook in to the same "tick": the reactive update cycle of lit (which can theoretically be swapped by other cycles, see <https://lit.dev/docs/frameworks/react/#usecontroller>)
+        - In general, all property effects / events / reactivity should be aligned as much as possible with the update cycle (for predictability and perf. We only need
+    - All components will just be configuration (no need to redefine a lot of logic)
+    - OverlayController (or OpenableController, or DisclosureController, or VisitibilityToggleController) will be the biggest common denominator. Having all logic in one place, makes it a lot easier to erase about then having it scattered across many mixin and/or controller levels
+    - Even though the amount of logic is large (and might feel a bit monolithic), this is just needed when we want to have a stable, battle tested abstraction around all edge cases that building accessible disclosures should handle
+      - However, this does not come at an extra performance cost (see performance, you will only load what you need)
+    - The current OverlayController is a long file that can benefit from some modularity and cleanup
+      - Every overlay feature can be provided in a separate file with knowledge about the overlay lifecycle
+      - We can provide/reuse some utils like Resettable from VisibilityToggleCtrl ()
+  - Flexibility
+    - Re-use your markup for different screen sizes and/or devices (that may have different appearances, but the same functionality/semantics)
+      - Think of:
+        - a datepicker that opens as dropdown on desktop and as centered modal dialog on mobile
+        - a menubutton that opens as dropdown on desktop and as bottomsheet
+        - A menu that opens as dropdown on desktop and a collapsible (or even a plain list) on mobile
+    - As explained above, controllers are the most re-usable primitives, as a web component/mixin does not always provide the flexibility we need
+      - Controllers can be easliy mapped to directives (giving the same flexibility as "platform attributes" like popover). Forward compatible with <https://github.com/WICG/webcomponents/issues/1029>
+      - Controllers can be easily mapped to web components or mixins
+      - Contrary to mixins, it’s easy to conditionally load a controller
+      - Contrary to mixins, it’s easy to “undo” a controller (which is helpful in edge cases)
+  - Performance
+    - Will leverage the platform where possible:
+      - Use popover
+  - Forward compatibility
+    - Aligns as much as possible with (future) platform apis
+      - This leverages existing dev knowledge (api familiarity)
+      - This allows to build drop in replacements
+      - This allows to rely on the platform (reducing maintenance costs, increasing performance)
+  - Completeness
+    - Supports all use cases to build every UI thinkable:
+      - Will have optional dependency to menu controllers and interactive list controllers
+      - Supports visually hidden scenarios, hides
+  - Backward compatibility
+    - Since the amount of consumers of our overlay system (directly or indirectly) is large, we should provide a compatibility mechanism where possible. At the same time, we want to create an api as clean/aligned/forward compatible as possible. We could consider an optional compat-layer (a global import at the top of an app extending OverlayController prototype). Think of:
+      - Mapping popper api to popover concepts
+      -
+
+# Why start with OverlayController?
+
+- there is a lot of value in cleaning it up as there are many platform improvements
+- it's used by many
+- It is already a controller (we created it before Lit controllers existed) and therefore impact is minimal