@neuravision/construct 2.0.3 → 2.1.1

package/behaviors/toggle-group.js

@@ -0,0 +1,234 @@
+import {
+  assertChoice,
+  assertDescendants,
+  assertElement,
+  assertElements,
+  assertFunction,
+  assertUniqueElements,
+  boundaryEnabledIndex,
+  createAttributeStore,
+  createControllerLifecycle,
+  createDisposables,
+  dispatch,
+  focusElement,
+  getItemValue,
+  isDisabled,
+  nextEnabledIndex,
+  orientationDelta,
+} from './internal/dom.js';
+
+const controllers = new WeakMap();
+
+function isNativeButton(element) {
+  return element.tagName === 'BUTTON' || (element.tagName === 'INPUT' && ['button', 'submit', 'reset'].includes(element.type));
+}
+
+function normalizeMultipleValue(value, name) {
+  if (value == null) return [];
+  if (typeof value === 'string' || typeof value[Symbol.iterator] !== 'function') {
+    throw new TypeError(`${name} must be a non-string iterable for a multiple toggle group.`);
+  }
+  return Array.from(value, String);
+}
+
+/**
+ * Creates a single- or multiple-value toggle group with roving tabindex.
+ */
+export function createToggleGroupController(options) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('Toggle group controller options are required.');
+  }
+
+  const root = assertElement(options.root, 'options.root');
+  const existing = controllers.get(root);
+  if (existing) return existing;
+
+  const items = options.items == null
+    ? [...root.querySelectorAll('[data-ct-toggle], .ct-toggle-group__item')]
+    : assertElements(options.items, 'options.items');
+  if (!items.length) throw new TypeError('Toggle group controller requires at least one item.');
+  assertUniqueElements(items, 'options.items');
+  assertDescendants(items, root, 'options.items');
+
+  const type = assertChoice(options.type ?? 'single', ['single', 'multiple'], 'options.type');
+  const orientation = assertChoice(
+    options.orientation ?? root.getAttribute('aria-orientation') ?? 'horizontal',
+    ['horizontal', 'vertical'],
+    'options.orientation',
+  );
+  assertFunction(options.onValueChange, 'options.onValueChange');
+
+  const attributes = createAttributeStore();
+  const lifecycle = createControllerLifecycle('Toggle group');
+  const disposables = createDisposables();
+  const values = items.map(getItemValue);
+  if (new Set(values).size !== values.length) {
+    throw new TypeError('Toggle group item values must be unique.');
+  }
+
+  const loop = options.loop !== false;
+  const allowEmpty = options.allowEmpty !== false;
+  let selected = new Set();
+
+  if (options.value != null) {
+    const requested = type === 'multiple'
+      ? new Set(normalizeMultipleValue(options.value, 'options.value'))
+      : new Set([String(options.value)]);
+    requested.forEach((value) => {
+      if (!values.includes(value)) throw new RangeError(`Unknown toggle group value: ${value}.`);
+      selected.add(value);
+    });
+  } else {
+    items.forEach((item, index) => {
+      if (item.getAttribute('aria-pressed') === 'true' || item.getAttribute('aria-checked') === 'true') {
+        if (type === 'multiple' || selected.size === 0) selected.add(values[index]);
+      }
+    });
+  }
+
+  let focusIndex = items.findIndex((item, index) => selected.has(values[index]) && !isDisabled(item));
+  if (focusIndex < 0) focusIndex = boundaryEnabledIndex(items);
+  if (focusIndex < 0) throw new TypeError('Toggle group controller requires at least one enabled item.');
+  if (!allowEmpty && selected.size === 0) selected.add(values[focusIndex]);
+
+  const rootRole = root.getAttribute('role') ?? 'group';
+  attributes.set(root, 'role', rootRole);
+  attributes.set(root, 'data-orientation', orientation);
+  if (rootRole === 'toolbar') attributes.set(root, 'aria-orientation', orientation);
+  items.forEach((item) => {
+    if (!isNativeButton(item)) attributes.set(item, 'role', 'button');
+  });
+
+  function currentValue() {
+    if (type === 'multiple') return values.filter((value) => selected.has(value));
+    return values.find((value) => selected.has(value)) ?? null;
+  }
+
+  function sync() {
+    items.forEach((item, index) => {
+      const pressed = selected.has(values[index]);
+      attributes.set(item, 'aria-pressed', String(pressed));
+      attributes.set(item, 'data-state', pressed ? 'on' : 'off');
+      attributes.set(item, 'tabindex', index === focusIndex && !isDisabled(item) ? '0' : '-1');
+    });
+  }
+
+  function commit(nextSelected, reason, item = null) {
+    return lifecycle.run('value change', (checkpoint) => {
+      const previous = currentValue();
+      const next = type === 'multiple'
+        ? values.filter((value) => nextSelected.has(value))
+        : values.find((value) => nextSelected.has(value)) ?? null;
+      if (JSON.stringify(previous) === JSON.stringify(next)) return false;
+
+      const detail = { controller, item, previousValue: previous, reason, value: next };
+      const allowed = dispatch(root, 'ct:beforevaluechange', detail, true);
+      checkpoint();
+      if (!allowed) return false;
+
+      selected = nextSelected;
+      sync();
+      options.onValueChange?.(detail);
+      checkpoint();
+      dispatch(root, 'ct:valuechange', detail);
+      checkpoint();
+      return true;
+    });
+  }
+
+  function toggle(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('Toggle target is not managed by this controller.');
+    }
+    const item = items[index];
+    if (isDisabled(item)) return false;
+
+    const value = values[index];
+    const next = new Set(selected);
+    if (type === 'multiple') {
+      if (next.has(value)) next.delete(value);
+      else next.add(value);
+    } else if (next.has(value)) {
+      if (!allowEmpty) return false;
+      next.clear();
+    } else {
+      next.clear();
+      next.add(value);
+    }
+
+    return commit(next, reason, item);
+  }
+
+  function setValue(value, reason = 'programmatic') {
+    lifecycle.assertAlive();
+    const requested = type === 'multiple'
+      ? new Set(normalizeMultipleValue(value, 'value'))
+      : new Set(value == null ? [] : [String(value)]);
+    requested.forEach((entry) => {
+      if (!values.includes(entry)) throw new RangeError(`Unknown toggle group value: ${entry}.`);
+    });
+    if (!allowEmpty && requested.size === 0) return false;
+    return commit(requested, reason);
+  }
+
+  function onKeyDown(event, index) {
+    const delta = orientationDelta(event.key, orientation, root);
+    let nextIndex = -1;
+    if (delta) nextIndex = nextEnabledIndex(items, index, delta, loop);
+    else if (event.key === 'Home' || event.key === 'End') {
+      nextIndex = boundaryEnabledIndex(items, event.key === 'End');
+    }
+
+    if (nextIndex >= 0) {
+      event.preventDefault();
+      focusIndex = nextIndex;
+      sync();
+      focusElement(items[nextIndex]);
+      return;
+    }
+
+    if (!isNativeButton(items[index]) && (event.key === 'Enter' || event.key === ' ')) {
+      event.preventDefault();
+      toggle(index, 'keyboard');
+    }
+  }
+
+  items.forEach((item, index) => {
+    disposables.listen(item, 'click', (event) => {
+      event.preventDefault();
+      if (!isDisabled(item)) toggle(index, 'pointer');
+    });
+    disposables.listen(item, 'focus', () => {
+      if (isDisabled(item)) return;
+      focusIndex = index;
+      sync();
+    });
+    disposables.listen(item, 'keydown', (event) => onKeyDown(event, index));
+  });
+
+  const controller = Object.freeze({
+    get root() {
+      return root;
+    },
+    get items() {
+      return [...items];
+    },
+    get value() {
+      return currentValue();
+    },
+    toggle,
+    setValue,
+    destroy() {
+      if (!lifecycle.destroy()) return;
+      disposables.dispose();
+      attributes.restore();
+      controllers.delete(root);
+    },
+  });
+
+  controllers.set(root, controller);
+  sync();
+  return controller;
+}

package/behaviors/tooltip.js

@@ -0,0 +1,233 @@
+import {
+  assertElement,
+  assertFunction,
+  createAttributeStore,
+  createControllerLifecycle,
+  createDisposables,
+  dispatch,
+  ensureId,
+  eventTargetsOutside,
+} from './internal/dom.js';
+import { consumeTopOverlayEvent, pushOverlay } from './internal/overlay.js';
+
+const controllers = new WeakMap();
+
+/**
+ * Creates a tooltip controller that works with keyboard focus, hover-capable
+ * pointers, Escape, and touch without depending on sticky hover state.
+ */
+export function createTooltipController(options) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('Tooltip controller options are required.');
+  }
+
+  const trigger = assertElement(options.trigger, 'options.trigger');
+  const existing = controllers.get(trigger);
+  if (existing) return existing;
+  const tooltip = assertElement(options.tooltip, 'options.tooltip');
+  const root = assertElement(options.root ?? tooltip.closest('.ct-tooltip') ?? tooltip, 'options.root');
+  if (trigger.ownerDocument !== tooltip.ownerDocument || trigger.ownerDocument !== root.ownerDocument) {
+    throw new TypeError('Tooltip elements must belong to the same document.');
+  }
+  assertFunction(options.onOpen, 'options.onOpen');
+  assertFunction(options.onClose, 'options.onClose');
+
+  const attributes = createAttributeStore();
+  const lifecycle = createControllerLifecycle('Tooltip');
+  const disposables = createDisposables();
+  const document = trigger.ownerDocument;
+  const token = {};
+  const openDelay = options.openDelay ?? 400;
+  const closeDelay = options.closeDelay ?? 100;
+  if (!Number.isFinite(openDelay) || openDelay < 0 || !Number.isFinite(closeDelay) || closeDelay < 0) {
+    throw new RangeError('Tooltip delays must be non-negative finite numbers.');
+  }
+
+  let controller;
+  let open = options.open ?? root.getAttribute('data-state') === 'open';
+  let timer;
+  let removeFromStack = null;
+  let tooltipHovered = false;
+  let triggerHovered = false;
+  let focused = false;
+  let touchOpened = false;
+
+  const tooltipId = ensureId(tooltip, 'ct-tooltip', attributes);
+  const describedBy = new Set((trigger.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean));
+  describedBy.add(tooltipId);
+  attributes.set(trigger, 'aria-describedby', [...describedBy].join(' '));
+  attributes.set(tooltip, 'role', 'tooltip');
+
+  function sync() {
+    attributes.set(root, 'data-state', open ? 'open' : 'closed');
+    attributes.set(tooltip, 'hidden', open ? null : '');
+  }
+
+  function clearTimer() {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  }
+
+  function registerOverlay() {
+    return pushOverlay(document, token, {
+      focusScopes: [tooltip],
+      onOwnerClose: () => closeTooltip('owner-close'),
+      onOwnerDestroy: () => controller.destroy(),
+      trigger,
+    });
+  }
+
+  function openTooltip(reason = 'programmatic') {
+    return lifecycle.run('open', (checkpoint) => {
+      clearTimer();
+      if (open) return false;
+      const detail = { controller, reason };
+      const allowed = dispatch(tooltip, 'ct:beforeopen', detail, true);
+      checkpoint();
+      if (!allowed) return false;
+
+      open = true;
+      sync();
+      removeFromStack = registerOverlay();
+      try {
+        options.onOpen?.(detail);
+        checkpoint();
+      } catch (error) {
+        if (lifecycle.isAlive) {
+          open = false;
+          sync();
+          removeFromStack?.();
+          removeFromStack = null;
+        }
+        throw error;
+      }
+      dispatch(tooltip, 'ct:open', detail);
+      checkpoint();
+      return true;
+    });
+  }
+
+  function closeTooltip(reason = 'programmatic') {
+    return lifecycle.run('close', (checkpoint) => {
+      clearTimer();
+      if (!open) return false;
+      const detail = { controller, reason };
+      const allowed = dispatch(tooltip, 'ct:beforeclose', detail, true);
+      checkpoint();
+      if (!allowed) return false;
+
+      open = false;
+      touchOpened = false;
+      sync();
+      removeFromStack?.();
+      removeFromStack = null;
+      options.onClose?.(detail);
+      checkpoint();
+      dispatch(tooltip, 'ct:close', detail);
+      checkpoint();
+      return true;
+    });
+  }
+
+  function scheduleOpen(reason, delay = openDelay) {
+    clearTimer();
+    timer = setTimeout(() => openTooltip(reason), delay);
+  }
+
+  function scheduleClose(reason, delay = closeDelay) {
+    clearTimer();
+    timer = setTimeout(() => closeTooltip(reason), delay);
+  }
+
+  disposables.listen(trigger, 'pointerenter', (event) => {
+    if (event.pointerType !== 'touch') {
+      triggerHovered = true;
+      scheduleOpen('hover');
+    }
+  });
+  disposables.listen(trigger, 'pointerleave', (event) => {
+    if (event.pointerType !== 'touch') {
+      triggerHovered = false;
+      if (!tooltipHovered && !focused && !touchOpened) scheduleClose('hover');
+    }
+  });
+  disposables.listen(tooltip, 'pointerenter', (event) => {
+    if (event.pointerType !== 'touch') {
+      tooltipHovered = true;
+      clearTimer();
+    }
+  });
+  disposables.listen(tooltip, 'pointerleave', (event) => {
+    if (event.pointerType !== 'touch') {
+      tooltipHovered = false;
+      if (!triggerHovered && !focused && !touchOpened) scheduleClose('hover');
+    }
+  });
+  disposables.listen(trigger, 'focus', () => {
+    focused = true;
+    scheduleOpen('focus', 0);
+  });
+  disposables.listen(trigger, 'blur', () => {
+    focused = false;
+    if (!triggerHovered && !tooltipHovered && !touchOpened) scheduleClose('blur', 0);
+  });
+  disposables.listen(trigger, 'pointerdown', (event) => {
+    if (event.pointerType === 'touch') {
+      if (touchOpened || open) {
+        touchOpened = false;
+        closeTooltip('touch');
+      } else {
+        touchOpened = openTooltip('touch') || open;
+      }
+    }
+  });
+  disposables.listen(document, 'keydown', (event) => {
+    if (open && event.key === 'Escape' && consumeTopOverlayEvent(event, document, token)) {
+      event.preventDefault();
+      event.stopPropagation();
+      closeTooltip('escape');
+    }
+  }, true);
+  disposables.listen(document, 'pointerdown', (event) => {
+    if (
+      open &&
+      eventTargetsOutside(event, [trigger, tooltip]) &&
+      consumeTopOverlayEvent(event, document, token)
+    ) {
+      touchOpened = false;
+      closeTooltip('outside');
+    }
+  }, true);
+
+  controller = Object.freeze({
+    get root() {
+      return root;
+    },
+    get trigger() {
+      return trigger;
+    },
+    get tooltip() {
+      return tooltip;
+    },
+    get isOpen() {
+      return open;
+    },
+    open: openTooltip,
+    close: closeTooltip,
+    destroy() {
+      if (!lifecycle.destroy()) return;
+      open = false;
+      clearTimer();
+      removeFromStack?.();
+      removeFromStack = null;
+      disposables.dispose();
+      attributes.restore();
+      controllers.delete(trigger);
+    },
+  });
+
+  controllers.set(trigger, controller);
+  sync();
+  if (open) removeFromStack = registerOverlay();
+  return controller;
+}