@zeyos/zx 2.3.0 → 4.0.0

package/src/components/tooltip/tooltip.js

@@ -4,7 +4,10 @@ import { position } from '../../core/position.js';
 import { uid } from '../../core/util.js';
 
 /** Placements accepted by the option and understood by `position()`. */
-const PLACEMENTS = new Set(['top', 'bottom', 'top-start', 'top-end', 'bottom-start', 'bottom-end']);
+const PLACEMENTS = new Set([
+  'top', 'bottom', 'top-start', 'top-end', 'bottom-start', 'bottom-end',
+  'left', 'right', 'left-start', 'left-end', 'right-start', 'right-end'
+]);
 /** Trigger modes. `manual` installs no listeners at all. */
 const TRIGGERS = new Set(['hover', 'focus', 'both', 'manual']);
 
@@ -21,7 +24,7 @@ const TRIGGERS = new Set(['hover', 'focus', 'both', 'manual']);
 /**
  * @typedef {Object} TooltipOptions
  * @property {TooltipContent} [content=''] Bubble content, re-evaluated on each open when a function.
- * @property {'top'|'bottom'|'top-start'|'top-end'|'bottom-start'|'bottom-end'} [placement='top'] Preferred side; flips when it would overflow.
+ * @property {'top'|'bottom'|'top-start'|'top-end'|'bottom-start'|'bottom-end'|'left'|'right'|'left-start'|'left-end'|'right-start'|'right-end'} [placement='top'] Preferred side; flips when it would overflow.
  * @property {number} [offset=6] Gap between anchor and bubble in pixels.
  * @property {number} [delay=400] Delay before a hover opens the tooltip, in milliseconds.
  * @property {number} [hideDelay=80] Delay before a leave or blur closes it, in milliseconds.

package/src/components/value-list/value-list.js

@@ -10,6 +10,9 @@ import { uid } from '../../core/util.js';
  * @property {boolean} [sortable=true] Whether values can be reordered.
  * @property {boolean} [unique=true] Whether duplicate strings are rejected.
  * @property {((value: string) => boolean|string)|null} [validate=null] Value validator.
+ * @property {(event: CustomEvent<{values: string[]}>) => void} [onchange] Values change listener.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onadd] Value added listener.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onremove] Value removed listener.
  */
 
 /**
@@ -320,17 +323,17 @@ function normalizeValues(values, unique) {
 /**
  * Values changed event.
  * @event ValueList#change
- * @type {CustomEvent<{values: string[]}>
+ * @type {CustomEvent<{values: string[]}>}
  */
 
 /**
  * Value added event.
  * @event ValueList#add
- * @type {CustomEvent<{value: string}>
+ * @type {CustomEvent<{value: string}>}
  */
 
 /**
  * Value removed event.
  * @event ValueList#remove
- * @type {CustomEvent<{value: string}>
+ * @type {CustomEvent<{value: string}>}
  */

package/src/core/dom.js

@@ -3,6 +3,7 @@ import { escapeRegExp, isElement } from './util.js';
 
 /** @typedef {{toElement: () => Node|null}} ElementProvider */
 /** @typedef {Node|string|number|ElementProvider|null|undefined|Array<DomChild>} DomChild */
+/** @typedef {Record<string, any>} DomBuilderProperties */
 /**
  * @typedef {Object} HProps
  * @property {string|string[]} [class] Class name or names.
@@ -14,6 +15,193 @@ import { escapeRegExp, isElement } from './util.js';
 /** @type {Record<string, Element>|null} */
 let activeRefs = null;
 
+/** Properties the ZeyOS builder historically assigns through the DOM property rather than an attribute. */
+const DOM_BUILDER_PROPERTIES = new Set([
+  'href', 'id', 'lang', 'name', 'rel', 'src', 'target', 'title', 'value'
+]);
+
+/** @type {WeakMap<EventTarget, Map<string, {handlers: Function[], listener: EventListener}>>} */
+const compactEvents = new WeakMap();
+
+/**
+ * @typedef {Object} CompactTag
+ * @property {string} tag Element tag, defaulting to `div`.
+ * @property {string} id Element id.
+ * @property {string} className Space-delimited class string.
+ */
+
+/**
+ * Parses the compact ZeyOS builder grammar: `tag#id.class names`. The order intentionally matches
+ * the established function—class text begins at the first dot, then id is read from the remaining
+ * tag portion—so thousands of existing call sites retain the same meaning.
+ * @param {string} compact Compact element description.
+ * @returns {CompactTag}
+ */
+export function parseCompactTag(compact) {
+  if (typeof compact !== 'string') throw new TypeError('DOM builder tag must be a string');
+  let tag = compact;
+  let className = '';
+  let id = '';
+  let index = tag.indexOf('.');
+  if (index !== -1) {
+    className = tag.slice(index + 1);
+    tag = tag.slice(0, index);
+  }
+  index = tag.indexOf('#');
+  if (index !== -1) {
+    id = tag.slice(index + 1);
+    tag = tag.slice(0, index);
+  }
+  return { tag: tag || 'div', id, className };
+}
+
+/**
+ * ZeyOS's compact DOM builder, now a first-class Zx primitive. Primitive content is assigned as
+ * text and object content is appended as a Node; HTML strings are never parsed.
+ *
+ * Existing syntax is preserved (`__('button.primary', {Daction: 'save'}, 'Save')`). Zx components
+ * exposing `toElement()` are the one additive extension, so a component may replace a UI factory
+ * without changing the surrounding builder call.
+ * @param {string} compact `tag#id.class names`; an omitted tag creates a `div`.
+ * @param {DomBuilderProperties|null} [properties=null] ZeyOS builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {HTMLElement}
+ */
+export function compactElement(compact, properties = null, content = null) {
+  const description = parseCompactTag(compact);
+  const element = document.createElement(description.tag);
+  if (description.id) element.id = description.id;
+  if (description.className) element.className = description.className;
+
+  if (description.tag === 'a') {
+    const anchor = /** @type {HTMLAnchorElement} */ (element);
+    anchor.rel = 'noopener';
+    anchor.tabIndex = -1;
+  } else if (description.tag === 'button') {
+    /** @type {HTMLButtonElement} */ (element).type = 'button';
+  } else if (description.tag === 'input' || description.tag === 'textarea') {
+    const control = /** @type {any} */ (element);
+    control.autocapitalize = 'none';
+    control.autocomplete = 'off';
+    control.autocorrect = 'off';
+    control.spellcheck = false;
+  }
+
+  if (properties) applyCompactProperties(element, properties);
+  setCompactContent(element, content);
+  return element;
+}
+
+/** Exact migration-facing alias retained for existing ZeyOS builder calls. */
+export const __ = compactElement;
+
+/**
+ * Returns a trimmed native-link destination unless its parsed scheme can execute document code.
+ * Relative URLs, fragments, and ordinary application protocols remain valid; malformed and
+ * control-obfuscated script/data schemes are rejected.
+ * @param {unknown} value Candidate href.
+ * @returns {string|null}
+ */
+export function safeHref(value) {
+  if (typeof value !== 'string') return null;
+  const href = value.trim();
+  if (!href) return null;
+  try {
+    const protocol = new URL(href, globalThis.location?.href ?? 'https://zx.invalid/').protocol;
+    if (['javascript:', 'data:', 'vbscript:'].includes(protocol.toLowerCase())) return null;
+  } catch {
+    return null;
+  }
+  return href;
+}
+
+/**
+ * Applies the established ZeyOS property rules to an existing element:
+ * `Dname` → `data-name`, `SfontSize` → `style.fontSize`, `on*` → a legacy-compatible listener,
+ * booleans/built-ins → DOM properties, and everything else → attributes.
+ * @param {HTMLElement} element Target element.
+ * @param {DomBuilderProperties} properties Properties to apply.
+ * @returns {HTMLElement} The target, for chaining.
+ */
+export function applyCompactProperties(element, properties) {
+  // `for…in` is intentional: the established builder also applies enumerable properties inherited
+  // from a shared descriptor prototype. Changing that during migration would silently drop them.
+  for (const name in properties ?? {}) {
+    const value = properties[name];
+    if (value == null) continue;
+    if (name[0] === 'D') {
+      element.setAttribute(`data-${name.slice(1)}`, String(value));
+    } else if (name[0] === 'S') {
+      element.style[name.slice(1)] = value;
+    } else if (name.startsWith('on')) {
+      if (typeof value !== 'function') {
+        throw new TypeError(`Compact DOM event ${name} must be a function`);
+      }
+      onCompactEvent(element, name.slice(2), value);
+    } else if (typeof value === 'boolean' || DOM_BUILDER_PROPERTIES.has(name)) {
+      element[name] = value;
+    } else {
+      element.setAttribute(name, String(value));
+    }
+  }
+  return element;
+}
+
+/**
+ * Appends one child and returns the parent: the pure-function equivalent of `parent._(child)`.
+ * Primitive values become text; a component exposing `toElement()` is accepted additively.
+ * @param {Node} parent Parent node.
+ * @param {unknown} child Child content.
+ * @returns {Node}
+ */
+export function appendContent(parent, child) {
+  if (child == null) return parent;
+  const resolved = resolveCompactProvider(child);
+  if (resolved == null) return parent;
+  if (typeof resolved === 'object') parent.appendChild(/** @type {Node} */ (resolved));
+  else parent.appendChild(document.createTextNode(String(resolved)));
+  return parent;
+}
+
+/**
+ * Creates and appends a compact element, returning the parent: the pure equivalent of `parent.__`.
+ * @param {Node} parent Parent node.
+ * @param {string} compact Compact element description.
+ * @param {DomBuilderProperties|null} [properties=null] Builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {Node}
+ */
+export function appendCompact(parent, compact, properties = null, content = null) {
+  parent.appendChild(compactElement(compact, properties, content));
+  return parent;
+}
+
+/**
+ * Creates and appends a compact element, returning the child: the pure equivalent of `parent.$__`.
+ * @param {Node} parent Parent node.
+ * @param {string} compact Compact element description.
+ * @param {DomBuilderProperties|null} [properties=null] Builder properties.
+ * @param {unknown} [content=null] Text-safe content.
+ * @returns {HTMLElement}
+ */
+export function appendCompactChild(parent, compact, properties = null, content = null) {
+  const child = compactElement(compact, properties, content);
+  parent.appendChild(child);
+  return child;
+}
+
+/**
+ * Creates a document fragment with normalized modern Zx children. Unlike the exact compact
+ * builder, this convenience accepts arrays and flattens them like `h()`.
+ * @param {...(DomChild|boolean)} children Fragment children.
+ * @returns {DocumentFragment}
+ */
+export function fragment(...children) {
+  const result = document.createDocumentFragment();
+  appendChildren(result, /** @type {DomChild[]} */ (children));
+  return result;
+}
+
 /**
  * Creates an element and appends normalized children.
  * @param {string} tag Element tag name.
@@ -258,3 +446,137 @@ function appendChildren(parent, children) {
     }
   }
 }
+
+/**
+ * Applies the compact builder's exact single-content contract. Objects are passed to native
+ * `appendChild`, while primitives replace textContent. Providers are the explicit Zx extension.
+ * @param {HTMLElement} element Target element.
+ * @param {unknown} content Builder content.
+ * @returns {void}
+ */
+function setCompactContent(element, content) {
+  if (content == null) return;
+  const resolved = resolveCompactProvider(content);
+  if (resolved == null) return;
+  if (typeof resolved === 'object') element.appendChild(/** @type {Node} */ (resolved));
+  else element.textContent = String(resolved);
+}
+
+/**
+ * Resolves the one additive component-provider extension without normalizing any other object.
+ * Arrays and plain objects therefore retain the native `appendChild` failure contract.
+ * @param {unknown} value Candidate content.
+ * @returns {unknown}
+ */
+function resolveCompactProvider(value) {
+  if (value && typeof value === 'object') {
+    // A native Node always wins, even if application code attached a `toElement()` method to it.
+    // Classic passes every object straight to appendChild; provider resolution is additive only
+    // for component-like objects that are not already DOM nodes.
+    if (typeof (/** @type {any} */ (value)).nodeType === 'number') return value;
+    if (typeof (/** @type {any} */ (value)).toElement === 'function') {
+      return (/** @type {ElementProvider} */ (value)).toElement();
+    }
+  }
+  return value;
+}
+
+/**
+ * Registers an event with the established ZeyOS callback contract: handlers run newest-first,
+ * receive `(event, event.target)` (or the key code for keyboard events), and may return false to
+ * prevent the default action. This exported registry is shared by compact properties, removal,
+ * and synthetic firing so the legacy `DOM` facade can delegate all three operations to it.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Function} handler Listener.
+ * @param {boolean} [passive=false] Native passive-listener hint.
+ * @returns {EventTarget}
+ */
+export function onCompactEvent(target, type, handler, passive = false) {
+  if (typeof handler !== 'function') throw new TypeError('Compact DOM event handler must be a function');
+  const eventType = String(type);
+  let events = compactEvents.get(target);
+  if (!events) {
+    events = new Map();
+    compactEvents.set(target, events);
+  }
+  const registered = events.get(eventType);
+  if (registered) {
+    registered.handlers.push(handler);
+    return target;
+  }
+  const handlers = [handler];
+  /** @type {EventListener} */
+  const listener = (event) => dispatchCompactEvent(target, handlers, event);
+  events.set(eventType, { handlers, listener });
+  try {
+    target.addEventListener(eventType, listener, { passive });
+  } catch {
+    target.addEventListener(eventType, listener);
+  }
+  return target;
+}
+
+/**
+ * Removes one registered handler, matching the established duplicate-registration behavior.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Function} handler Handler to remove.
+ * @returns {EventTarget}
+ */
+export function offCompactEvent(target, type, handler) {
+  const eventType = String(type);
+  const events = compactEvents.get(target);
+  const registered = events?.get(eventType);
+  if (!registered) return target;
+  const index = registered.handlers.indexOf(handler);
+  if (index === -1) return target;
+  registered.handlers.splice(index, 1);
+  if (registered.handlers.length === 0) {
+    target.removeEventListener(eventType, registered.listener);
+    events.delete(eventType);
+    if (events.size === 0) compactEvents.delete(target);
+  }
+  return target;
+}
+
+/**
+ * Invokes compact handlers without dispatching unrelated native listeners.
+ * @param {EventTarget} target Event target.
+ * @param {string} type Event name.
+ * @param {Event|Record<string, any>|null} [event=null] Event-like object.
+ * @returns {EventTarget}
+ */
+export function fireCompactEvent(target, type, event = null) {
+  const eventType = String(type);
+  const events = compactEvents.get(target);
+  // Match DOM.fireEvt's guard: a requested type must be registered before an event is considered.
+  if (!events?.has(eventType)) return target;
+  const actual = event ?? compactSyntheticEvent(target, eventType);
+  // DOM.handleEvt then dispatches by the supplied event's own type. This distinction matters for
+  // hand-built event objects even though normal ZeyOS callers omit the optional event argument.
+  const registered = events.get(String((/** @type {any} */ (actual)).type));
+  if (registered) dispatchCompactEvent(target, registered.handlers, actual);
+  return target;
+}
+
+/** @param {EventTarget} target @param {Function[]} handlers @param {Event|Record<string, any>} event */
+function dispatchCompactEvent(target, handlers, event) {
+  const value = /** @type {any} */ (event);
+  const secondary = String(value.type).startsWith('key') ? value.which : value.target;
+  for (let index = handlers.length - 1; index >= 0; index -= 1) {
+    if (handlers[index].call(target, event, secondary) === false) value.preventDefault();
+  }
+}
+
+/** @param {EventTarget} target @param {string} type @returns {Record<string, any>} */
+function compactSyntheticEvent(target, type) {
+  const event = {
+    target,
+    type,
+    which: -1,
+    defaultPrevented: false,
+    preventDefault() { event.defaultPrevented = true; }
+  };
+  return event;
+}

package/src/core/drag-axis.js

@@ -0,0 +1,203 @@
+// @ts-check
+
+/** Pixels an arrow key moves a handle. */
+export const STEP = 16;
+/** Pixels a shifted arrow key moves a handle. */
+export const STEP_LARGE = 64;
+
+/**
+ * @typedef {Object} DragAxisOptions
+ * @property {'horizontal'|'vertical'} orientation Axis the handle moves along. `horizontal` reads
+ *   `clientX`, `vertical` reads `clientY`.
+ * @property {(event: PointerEvent) => boolean|void} [onStart] Called on pointer-down before the
+ *   drag begins. Return `false` to refuse it — the usual reason being that there is nothing to
+ *   resize on either side of the handle.
+ * @property {(delta: number) => void} onMove Called at most once per frame with the signed pixel
+ *   distance travelled along the axis since pointer-down.
+ * @property {(delta: number, moved: boolean) => void} [onEnd] Called once the pointer is released.
+ *   `moved` is false for a press that never travelled, which is a click rather than a drag.
+ * @property {(direction: -1|1, large: boolean) => void} [onStep] Called for an arrow key along the
+ *   axis. `large` is true while Shift is held.
+ * @property {(edge: 'min'|'max') => void} [onJump] Called for Home and End.
+ * @property {() => void} [onActivate] Called for Enter and Space, which components use for the
+ *   collapse affordance a splitter is expected to offer.
+ * @property {() => boolean} [disabled] Consulted before every interaction.
+ */
+
+/**
+ * @typedef {Object} DragAxisController
+ * @property {() => boolean} isDragging Whether a drag is in flight.
+ * @property {() => void} cancel Ends any drag in flight without reporting it.
+ * @property {() => void} destroy Removes listeners and cancels any drag in flight.
+ */
+
+/**
+ * Pointer and keyboard mechanics for anything dragged along one axis — a split divider, a dock
+ * divider, the resizable edge of a sheet.
+ *
+ * Deliberately knows nothing about sizes. It reports the signed distance travelled and leaves
+ * every consumer to do its own arithmetic, because the three that need it disagree about what a
+ * drag means: a split view moves one boundary, a dock moves size between two neighbours, and a
+ * sheet grows in the opposite direction depending on which edge it is attached to. What they do
+ * share is the fiddly part — pointer capture that survives the pointer leaving the handle, one
+ * write per frame however fast the pointer reports, telling a click apart from a zero-distance
+ * drag, and the WAI-ARIA keyboard map.
+ *
+ * @param {Element} handle Element the pointer grabs; also the keyboard target.
+ * @param {DragAxisOptions} options Axis and callbacks.
+ * @returns {DragAxisController}
+ */
+export function dragAxis(handle, options) {
+  if (!handle) throw new TypeError('dragAxis requires a handle element');
+  if (typeof options?.onMove !== 'function') throw new TypeError('dragAxis requires an onMove callback');
+
+  const vertical = options.orientation === 'vertical';
+  const controller = new AbortController();
+  const { signal } = controller;
+
+  let dragging = false;
+  /** @type {number|null} */
+  let pointerId = null;
+  let startClient = 0;
+  let client = 0;
+  let moved = false;
+  /** Handle of the frame a pending update is scheduled in; `0` if none. */
+  let frame = 0;
+
+  /** @param {PointerEvent} event @returns {number} */
+  const axis = (event) => (vertical ? event.clientY : event.clientX);
+
+  /** @returns {boolean} */
+  const blocked = () => Boolean(options.disabled?.());
+
+  /** @returns {void} */
+  const releasePointer = () => {
+    const id = pointerId;
+    pointerId = null;
+    if (id === null) return;
+    try {
+      /** @type {HTMLElement} */ (handle).releasePointerCapture(id);
+    } catch {
+      // The capture is already gone once the pointer was cancelled or the node was detached.
+    }
+  };
+
+  /** @returns {void} */
+  const cancelFrame = () => {
+    if (frame === 0) return;
+    cancelAnimationFrame(frame);
+    frame = 0;
+  };
+
+  /** @returns {void} */
+  const finish = () => {
+    dragging = false;
+    moved = false;
+    cancelFrame();
+    releasePointer();
+  };
+
+  handle.addEventListener('pointerdown', (event) => {
+    const pointer = /** @type {PointerEvent} */ (event);
+    if (blocked() || dragging || pointer.button !== 0) return;
+    if (options.onStart?.(pointer) === false) return;
+    /*
+     * No preventDefault(): cancelling pointerdown suppresses the compatibility mouse events a
+     * double-click reset is built on. Handles set `user-select: none` in CSS to stop the text
+     * selection this would otherwise be guarding against.
+     */
+    dragging = true;
+    pointerId = pointer.pointerId;
+    startClient = axis(pointer);
+    client = startClient;
+    moved = false;
+    try {
+      /** @type {HTMLElement} */ (handle).setPointerCapture(pointer.pointerId);
+    } catch {
+      // A pointer that ended between the event and this call cannot be captured; the drag simply
+      // finishes on the next pointerup.
+    }
+  }, { signal });
+
+  handle.addEventListener('pointermove', (event) => {
+    const pointer = /** @type {PointerEvent} */ (event);
+    if (!dragging || pointer.pointerId !== pointerId) return;
+    client = axis(pointer);
+    if (client !== startClient) moved = true;
+    if (frame !== 0) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      if (dragging) options.onMove(client - startClient);
+    });
+  }, { signal });
+
+  /** @param {Event} event @returns {void} */
+  const end = (event) => {
+    const pointer = /** @type {PointerEvent} */ (event);
+    if (!dragging || pointer.pointerId !== pointerId) return;
+    cancelFrame();
+    client = axis(pointer);
+    const travelled = moved;
+    const delta = client - startClient;
+    finish();
+    options.onEnd?.(delta, travelled);
+  };
+  handle.addEventListener('pointerup', end, { signal });
+  handle.addEventListener('pointercancel', end, { signal });
+
+  handle.addEventListener('keydown', (event) => {
+    const key = /** @type {KeyboardEvent} */ (event);
+    if (blocked()) return;
+    if ((key.key === 'Enter' || key.key === ' ') && options.onActivate) {
+      key.preventDefault();
+      options.onActivate();
+      return;
+    }
+    if (key.key === 'Home' || key.key === 'End') {
+      if (!options.onJump) return;
+      key.preventDefault();
+      options.onJump(key.key === 'Home' ? 'min' : 'max');
+      return;
+    }
+    const decrease = vertical ? 'ArrowUp' : 'ArrowLeft';
+    const increase = vertical ? 'ArrowDown' : 'ArrowRight';
+    if (key.key !== decrease && key.key !== increase) return;
+    if (!options.onStep) return;
+    key.preventDefault();
+    options.onStep(key.key === increase ? 1 : -1, key.shiftKey);
+  }, { signal });
+
+  return {
+    isDragging: () => dragging,
+    cancel() {
+      if (!dragging) return;
+      finish();
+    },
+    destroy() {
+      finish();
+      controller.abort();
+    }
+  };
+}
+
+/**
+ * Resolves a size option to pixels without touching the DOM.
+ *
+ * Numbers, bare numeric strings, and `px` lengths are pixels; a percentage resolves against
+ * `total`. Every other CSS length — `rem`, `vh`, `calc()` — needs the browser, so it returns `NaN`
+ * and the caller hands the value to CSS instead of guessing at it.
+ * @param {number|string} value Size option.
+ * @param {number} total Container size along the split axis, in pixels.
+ * @returns {number} Pixels, or `NaN` when only the browser can resolve the value.
+ */
+export function resolveSize(value, total) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : Number.NaN;
+  if (typeof value !== 'string') return Number.NaN;
+  const match = /^([+-]?(?:\d+\.?\d*|\.\d+))(px|%)?$/i.exec(value.trim());
+  if (!match) return Number.NaN;
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount)) return Number.NaN;
+  if ((match[2] ?? '').toLowerCase() !== '%') return amount;
+  const span = Number(total);
+  return Number.isFinite(span) ? (amount / 100) * span : Number.NaN;
+}