@neuravision/construct 2.0.2 → 2.1.1

package/behaviors/dropdown.js

@@ -0,0 +1,296 @@
+import {
+  assertDescendants,
+  assertElement,
+  assertElements,
+  assertFunction,
+  assertSameDocument,
+  assertUniqueElements,
+  boundaryEnabledIndex,
+  createAttributeStore,
+  createControllerLifecycle,
+  createDisposables,
+  createTypeahead,
+  dispatch,
+  focusElement,
+  getItemValue,
+  isDisabled,
+  nextEnabledIndex,
+} from './internal/dom.js';
+import { createPopupLayer } from './internal/popup-layer.js';
+
+const controllers = new WeakMap();
+
+const MENU_ITEM_SELECTOR = [
+  '[role="menuitem"]',
+  '[role="menuitemcheckbox"]',
+  '[role="menuitemradio"]',
+  '[data-ct-menu-item]',
+].join(',');
+
+/**
+ * Creates a menu-button controller with roving focus, typeahead, dismissal, and selection events.
+ */
+export function createDropdownController(options) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('Dropdown controller options are required.');
+  }
+
+  const trigger = assertElement(options.trigger, 'options.trigger');
+  const existing = controllers.get(trigger);
+  if (existing) return existing;
+  const menu = assertElement(options.menu, 'options.menu');
+  const root = assertElement(options.root ?? menu.closest('.ct-dropdown') ?? menu, 'options.root');
+  const items = options.items == null
+    ? [...menu.querySelectorAll(MENU_ITEM_SELECTOR)]
+    : assertElements(options.items, 'options.items');
+  if (!items.length) throw new TypeError('Dropdown controller requires at least one menu item.');
+  if (trigger.ownerDocument !== menu.ownerDocument) {
+    throw new TypeError('Dropdown trigger and menu must belong to the same document.');
+  }
+  assertSameDocument([root], trigger.ownerDocument, 'options.root');
+  assertUniqueElements(items, 'options.items');
+  assertSameDocument(items, trigger.ownerDocument, 'options.items');
+  assertDescendants(items, menu, 'options.items');
+  assertFunction(options.onSelect, 'options.onSelect');
+  assertFunction(options.onOpen, 'options.onOpen');
+  assertFunction(options.onClose, 'options.onClose');
+
+  const attributes = createAttributeStore();
+  const lifecycle = createControllerLifecycle('Dropdown');
+  const disposables = createDisposables();
+  const typeahead = createTypeahead({ timeout: options.typeaheadTimeout });
+  let controller;
+  let focusIndex = -1;
+  let pendingFocus = 'first';
+
+  attributes.set(menu, 'role', 'menu');
+  if (trigger.tagName === 'BUTTON' && !trigger.hasAttribute('type')) {
+    attributes.set(trigger, 'type', 'button');
+  }
+  items.forEach((item) => {
+    if (!item.hasAttribute('role')) attributes.set(item, 'role', 'menuitem');
+    attributes.set(item, 'tabindex', '-1');
+  });
+
+  function enabledBoundary(fromEnd = false) {
+    return boundaryEnabledIndex(items, fromEnd);
+  }
+
+  function setHighlighted(index, { focus = true } = {}) {
+    if (index < 0 || index >= items.length || isDisabled(items[index])) return false;
+    focusIndex = index;
+    items.forEach((item, itemIndex) => {
+      attributes.set(item, 'data-highlighted', itemIndex === index ? '' : null);
+    });
+    if (focus) focusElement(items[index]);
+    return true;
+  }
+
+  function clearHighlight() {
+    focusIndex = -1;
+    items.forEach((item) => attributes.set(item, 'data-highlighted', null));
+    typeahead.reset();
+  }
+
+  const layer = createPopupLayer({
+    attributes,
+    closeOnEscape: options.closeOnEscape !== false,
+    closeOnFocusOutside: true,
+    closeOnOutside: options.closeOnOutside !== false,
+    disposables,
+    getController: () => controller,
+    hasPopup: 'menu',
+    handlesTab: true,
+    idPrefix: 'ct-dropdown-menu',
+    initialOpen: !isDisabled(trigger) && (options.open ?? root.getAttribute('data-state') === 'open'),
+    popup: menu,
+    stateElement: root,
+    trigger,
+    onOpen(detail, checkpoint) {
+      const index = pendingFocus === 'last' ? enabledBoundary(true) : enabledBoundary();
+      if (index >= 0) setHighlighted(index);
+      checkpoint();
+      options.onOpen?.(detail);
+    },
+    onClose(detail) {
+      clearHighlight();
+      options.onClose?.(detail);
+    },
+  });
+
+  function open(reason = 'programmatic', { focus = 'first' } = {}) {
+    return lifecycle.run('open', (checkpoint) => {
+      if (!['first', 'last'].includes(focus)) {
+        throw new TypeError("focus must be 'first' or 'last'.");
+      }
+      if (isDisabled(trigger)) return false;
+      pendingFocus = focus;
+      const changed = layer.open(reason);
+      checkpoint();
+      if (!changed && layer.isOpen) {
+        const index = focus === 'last' ? enabledBoundary(true) : enabledBoundary();
+        if (index >= 0) setHighlighted(index);
+      }
+      return changed;
+    });
+  }
+
+  function selectItem(index, reason) {
+    return lifecycle.run('select', (checkpoint) => {
+      const item = items[index];
+      if (!item || isDisabled(item)) return false;
+
+      const detail = {
+        controller,
+        index,
+        item,
+        reason,
+        value: getItemValue(item, index),
+      };
+      const allowed = dispatch(menu, 'ct:beforeselect', detail, true);
+      checkpoint();
+      if (!allowed) return false;
+
+      const role = item.getAttribute('role');
+      if (role === 'menuitemcheckbox') {
+        attributes.set(item, 'aria-checked', String(item.getAttribute('aria-checked') !== 'true'));
+      } else if (role === 'menuitemradio') {
+        const group = item.closest('[role="group"]') ?? menu;
+        items.forEach((candidate) => {
+          if (
+            candidate.getAttribute('role') === 'menuitemradio' &&
+            (candidate.closest('[role="group"]') ?? menu) === group
+          ) {
+            attributes.set(candidate, 'aria-checked', String(candidate === item));
+          }
+        });
+      }
+
+      options.onSelect?.(detail);
+      checkpoint();
+      dispatch(menu, 'ct:select', detail);
+      checkpoint();
+      const keepOpen = item.hasAttribute('data-ct-keep-open');
+      const defaultClose = role !== 'menuitemcheckbox';
+      if (!keepOpen && (options.closeOnSelect ?? defaultClose)) layer.close('select');
+      return true;
+    });
+  }
+
+  function onMenuKeyDown(event) {
+    const current = items.indexOf(event.target);
+    if (current < 0) return;
+
+    if (event.key === 'Tab') {
+      close('tab');
+      return;
+    }
+
+    let next = -1;
+    if (event.key === 'ArrowDown') next = nextEnabledIndex(items, current, 1, true);
+    else if (event.key === 'ArrowUp') next = nextEnabledIndex(items, current, -1, true);
+    else if (event.key === 'Home' || event.key === 'End') {
+      next = enabledBoundary(event.key === 'End');
+    } else if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      selectItem(current, 'keyboard');
+      return;
+    } else {
+      next = typeahead.find(event, items, current);
+    }
+
+    if (next >= 0) {
+      event.preventDefault();
+      setHighlighted(next);
+    }
+  }
+
+  function close(reason = 'programmatic', closeOptions) {
+    return lifecycle.run('close', (checkpoint) => {
+      const changed = layer.close(reason, closeOptions);
+      checkpoint();
+      return changed;
+    });
+  }
+
+  function toggle(reason = 'programmatic') {
+    return lifecycle.run('toggle', (checkpoint) => {
+      if (isDisabled(trigger)) return false;
+      const changed = layer.toggle(reason);
+      checkpoint();
+      return changed;
+    });
+  }
+
+  disposables.listen(trigger, 'click', (event) => {
+    event.preventDefault();
+    if (isDisabled(trigger)) return;
+    pendingFocus = 'first';
+    toggle('trigger');
+  });
+  disposables.listen(trigger, 'keydown', (event) => {
+    if (isDisabled(trigger)) {
+      if (['ArrowDown', 'ArrowUp', 'Enter', ' '].includes(event.key)) event.preventDefault();
+      return;
+    }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      open('keyboard', { focus: event.key === 'ArrowUp' ? 'last' : 'first' });
+    } else if ((event.key === 'Enter' || event.key === ' ') && !layer.isOpen) {
+      event.preventDefault();
+      open('keyboard');
+    }
+  });
+  disposables.listen(menu, 'keydown', onMenuKeyDown);
+  items.forEach((item, index) => {
+    disposables.listen(item, 'focus', () => setHighlighted(index, { focus: false }));
+    disposables.listen(item, 'click', (event) => {
+      if (isDisabled(item)) {
+        event.preventDefault();
+        return;
+      }
+      selectItem(index, 'pointer');
+    });
+  });
+
+  controller = Object.freeze({
+    get trigger() {
+      return trigger;
+    },
+    get root() {
+      return root;
+    },
+    get menu() {
+      return menu;
+    },
+    get items() {
+      return [...items];
+    },
+    get isOpen() {
+      return layer.isOpen;
+    },
+    open,
+    close,
+    toggle,
+    select(target, reason = 'programmatic') {
+      lifecycle.assertAlive();
+      const index = typeof target === 'number' ? target : items.indexOf(target);
+      if (!Number.isInteger(index) || index < 0 || index >= items.length) {
+        throw new RangeError('Menu item is not managed by this controller.');
+      }
+      return selectItem(index, reason);
+    },
+    destroy() {
+      if (!lifecycle.destroy()) return;
+      layer.destroy();
+      typeahead.reset();
+      disposables.dispose();
+      attributes.restore();
+      controllers.delete(trigger);
+    },
+  });
+
+  controllers.set(trigger, controller);
+  layer.activateInitialOpen();
+  return controller;
+}

package/behaviors/index.d.ts

@@ -0,0 +1,333 @@
+export type ElementCollection = Element | Iterable<Element> | ArrayLike<Element>;
+export type ControllerReason = string;
+export type InitialFocus = Element | string | (() => Element | null) | null;
+
+export interface CloseOptions {
+  restoreFocus?: boolean;
+}
+
+export interface OpenCloseDetail<TController> {
+  controller: TController;
+  reason: ControllerReason;
+}
+
+export interface DialogController {
+  readonly container: Element;
+  readonly dialog: Element;
+  readonly trigger: Element | null;
+  readonly isOpen: boolean;
+  open(reason?: ControllerReason): boolean;
+  close(reason?: ControllerReason, options?: CloseOptions): boolean;
+  toggle(reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export interface DialogControllerOptions {
+  container: Element;
+  dialog?: Element;
+  trigger?: Element | null;
+  backdrop?: Element | false;
+  closeButtons?: ElementCollection;
+  initialFocus?: InitialFocus;
+  open?: boolean;
+  triggerAction?: 'open' | 'toggle';
+  closeOnEscape?: boolean;
+  closeOnBackdrop?: boolean;
+  trapFocus?: boolean;
+  returnFocus?: boolean;
+  lockScroll?: boolean;
+  onOpen?(detail: OpenCloseDetail<DialogController>): void;
+  onClose?(detail: OpenCloseDetail<DialogController>): void;
+}
+
+export function createModalController(options: DialogControllerOptions): DialogController;
+export function createDrawerController(options: DialogControllerOptions): DialogController;
+
+export interface TabsSelectDetail {
+  controller: TabsController;
+  index: number;
+  tab: Element;
+  panel: Element;
+  reason: ControllerReason;
+}
+
+export interface TabsControllerOptions {
+  tablist: Element;
+  tabs?: ElementCollection;
+  panels?: ElementCollection;
+  orientation?: 'horizontal' | 'vertical';
+  activation?: 'automatic' | 'manual';
+  loop?: boolean;
+  selectedIndex?: number;
+  onSelect?(detail: TabsSelectDetail): void;
+}
+
+export interface TabsController {
+  readonly tablist: Element;
+  readonly tabs: Element[];
+  readonly panels: Element[];
+  readonly selectedIndex: number;
+  select(
+    target: number | Element,
+    options?: { focus?: boolean; reason?: ControllerReason },
+  ): boolean;
+  destroy(): void;
+}
+
+export function createTabsController(options: TabsControllerOptions): TabsController;
+
+export interface ToggleGroupValueChangeDetail {
+  controller: ToggleGroupController;
+  item: Element | null;
+  previousValue: string | string[] | null;
+  value: string | string[] | null;
+  reason: ControllerReason;
+}
+
+export interface ToggleGroupControllerBaseOptions {
+  root: Element;
+  items?: ElementCollection;
+  orientation?: 'horizontal' | 'vertical';
+  loop?: boolean;
+  allowEmpty?: boolean;
+  onValueChange?(detail: ToggleGroupValueChangeDetail): void;
+}
+
+export interface SingleToggleGroupControllerOptions extends ToggleGroupControllerBaseOptions {
+  type?: 'single';
+  value?: string | number | null;
+}
+
+export interface MultipleToggleGroupControllerOptions extends ToggleGroupControllerBaseOptions {
+  type: 'multiple';
+  value?: Iterable<string | number> | null;
+}
+
+export type ToggleGroupControllerOptions =
+  | SingleToggleGroupControllerOptions
+  | MultipleToggleGroupControllerOptions;
+
+export interface ToggleGroupControllerBase {
+  readonly root: Element;
+  readonly items: Element[];
+  toggle(target: number | Element, reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export interface SingleToggleGroupController extends ToggleGroupControllerBase {
+  readonly value: string | null;
+  setValue(value: string | number | null, reason?: ControllerReason): boolean;
+}
+
+export interface MultipleToggleGroupController extends ToggleGroupControllerBase {
+  readonly value: string[];
+  setValue(value: Iterable<string | number> | null, reason?: ControllerReason): boolean;
+}
+
+export type ToggleGroupController = SingleToggleGroupController | MultipleToggleGroupController;
+
+export function createToggleGroupController(
+  options: MultipleToggleGroupControllerOptions,
+): MultipleToggleGroupController;
+export function createToggleGroupController(
+  options: SingleToggleGroupControllerOptions,
+): SingleToggleGroupController;
+
+export interface DropdownSelectDetail {
+  controller: DropdownController;
+  index: number;
+  item: Element;
+  value: string;
+  reason: ControllerReason;
+}
+
+export interface DropdownControllerOptions {
+  root?: Element;
+  trigger: Element;
+  menu: Element;
+  items?: ElementCollection;
+  open?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOutside?: boolean;
+  closeOnSelect?: boolean;
+  typeaheadTimeout?: number;
+  onOpen?(detail: OpenCloseDetail<DropdownController>): void;
+  onClose?(detail: OpenCloseDetail<DropdownController>): void;
+  onSelect?(detail: DropdownSelectDetail): void;
+}
+
+export interface DropdownController {
+  readonly root: Element;
+  readonly trigger: Element;
+  readonly menu: Element;
+  readonly items: Element[];
+  readonly isOpen: boolean;
+  open(reason?: ControllerReason, options?: { focus?: 'first' | 'last' }): boolean;
+  close(reason?: ControllerReason, options?: CloseOptions): boolean;
+  toggle(reason?: ControllerReason): boolean;
+  select(target: number | Element, reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export function createDropdownController(options: DropdownControllerOptions): DropdownController;
+
+export interface SelectMenuValueChangeDetail {
+  controller: SelectMenuController;
+  index: number;
+  option: Element;
+  previousValue: string | null;
+  value: string;
+  reason: ControllerReason;
+}
+
+export interface SelectMenuControllerOptions {
+  root?: Element;
+  trigger: Element;
+  listbox: Element;
+  options?: ElementCollection;
+  valueElement?: Element;
+  value?: string | number | null;
+  open?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOutside?: boolean;
+  typeaheadTimeout?: number;
+  getOptionLabel?(option: Element, index: number): string;
+  getOptionValue?(option: Element, index: number): string | number;
+  onOpen?(detail: OpenCloseDetail<SelectMenuController>): void;
+  onClose?(detail: OpenCloseDetail<SelectMenuController>): void;
+  onValueChange?(detail: SelectMenuValueChangeDetail): void;
+}
+
+export interface SelectMenuController {
+  readonly root: Element;
+  readonly trigger: Element;
+  readonly listbox: Element;
+  readonly options: Element[];
+  readonly isOpen: boolean;
+  readonly value: string | null;
+  open(reason?: ControllerReason): boolean;
+  close(reason?: ControllerReason, options?: CloseOptions): boolean;
+  toggle(reason?: ControllerReason): boolean;
+  select(target: number | Element, reason?: ControllerReason): boolean;
+  setValue(value: string | number, reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export function createSelectMenuController(
+  options: SelectMenuControllerOptions,
+): SelectMenuController;
+
+export interface ComboboxQueryChangeDetail {
+  controller: ComboboxController;
+  query: string;
+  results: Element[];
+}
+
+export interface ComboboxValueChangeDetail {
+  controller: ComboboxController;
+  index: number;
+  option: Element | null;
+  previousValue: string | null;
+  value: string | null;
+  reason: ControllerReason;
+}
+
+export interface ComboboxControllerOptions {
+  root?: Element;
+  input: HTMLInputElement | HTMLTextAreaElement;
+  listbox: Element;
+  toggleButton?: Element;
+  status?: Element;
+  options?: ElementCollection;
+  value?: string | number | null;
+  open?: boolean;
+  autocomplete?: 'list' | 'none';
+  filter?: boolean | ((option: Element, query: string, index: number) => boolean);
+  openOnFocus?: boolean;
+  openOnInput?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOutside?: boolean;
+  clearSelectionOnInput?: boolean;
+  setInputValue?: boolean;
+  getOptionLabel?(option: Element, index: number): string;
+  getOptionValue?(option: Element, index: number): string | number;
+  formatStatus?(count: number, query: string): string;
+  onOpen?(detail: OpenCloseDetail<ComboboxController>): void;
+  onClose?(detail: OpenCloseDetail<ComboboxController>): void;
+  onQueryChange?(detail: ComboboxQueryChangeDetail): void;
+  onValueChange?(detail: ComboboxValueChangeDetail): void;
+}
+
+export interface ComboboxController {
+  readonly root: Element;
+  readonly input: HTMLInputElement | HTMLTextAreaElement;
+  readonly listbox: Element;
+  readonly options: Element[];
+  readonly isOpen: boolean;
+  readonly query: string;
+  readonly value: string | null;
+  open(reason?: ControllerReason): boolean;
+  close(reason?: ControllerReason, options?: CloseOptions): boolean;
+  toggle(reason?: ControllerReason): boolean;
+  select(target: number | Element, reason?: ControllerReason): boolean;
+  setValue(value: string | number | null, reason?: ControllerReason): boolean;
+  refresh(): Element[];
+  destroy(): void;
+}
+
+export function createComboboxController(options: ComboboxControllerOptions): ComboboxController;
+
+export interface TooltipControllerOptions {
+  root?: Element;
+  trigger: Element;
+  tooltip: Element;
+  open?: boolean;
+  openDelay?: number;
+  closeDelay?: number;
+  onOpen?(detail: OpenCloseDetail<TooltipController>): void;
+  onClose?(detail: OpenCloseDetail<TooltipController>): void;
+}
+
+export interface TooltipController {
+  readonly root: Element;
+  readonly trigger: Element;
+  readonly tooltip: Element;
+  readonly isOpen: boolean;
+  open(reason?: ControllerReason): boolean;
+  close(reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export function createTooltipController(options: TooltipControllerOptions): TooltipController;
+
+export interface PopoverControllerOptions {
+  root?: Element;
+  trigger: Element;
+  popover: Element;
+  closeButtons?: ElementCollection;
+  initialFocus?: InitialFocus;
+  open?: boolean;
+  openOnFocus?: boolean;
+  openOnHover?: boolean;
+  focusOnOpen?: boolean;
+  openDelay?: number;
+  closeDelay?: number;
+  closeOnEscape?: boolean;
+  closeOnOutside?: boolean;
+  closeOnFocusOutside?: boolean;
+  onOpen?(detail: OpenCloseDetail<PopoverController>): void;
+  onClose?(detail: OpenCloseDetail<PopoverController>): void;
+}
+
+export interface PopoverController {
+  readonly root: Element;
+  readonly trigger: Element;
+  readonly popover: Element;
+  readonly isOpen: boolean;
+  open(reason?: ControllerReason, options?: { focus?: boolean }): boolean;
+  close(reason?: ControllerReason, options?: CloseOptions): boolean;
+  toggle(reason?: ControllerReason): boolean;
+  destroy(): void;
+}
+
+export function createPopoverController(options: PopoverControllerOptions): PopoverController;

package/behaviors/index.js

@@ -0,0 +1,9 @@
+export { createComboboxController } from './combobox.js';
+export { createDrawerController } from './drawer.js';
+export { createDropdownController } from './dropdown.js';
+export { createModalController } from './modal.js';
+export { createPopoverController } from './popover.js';
+export { createSelectMenuController } from './select-menu.js';
+export { createTabsController } from './tabs.js';
+export { createToggleGroupController } from './toggle-group.js';
+export { createTooltipController } from './tooltip.js';