@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/gestures/nativeScroll.ts

@@ -0,0 +1,277 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file nativeScroll.ts
+ * @input An element a touch landed on
+ * @output Exports createNativeScrollProbe (the NativeScrollProbe a host gives
+ *   each touch) and parseTouchAction
+ * @position DOM half of the scroll coordination in packages/core/src/gestures
+ *
+ * Answers one question for a recognizer without letting it touch the DOM:
+ * would the browser scroll something if this finger moved that way?
+ *
+ * The browser scrolls the innermost scroller that has room, then chains
+ * outward, so the answer is "yes" while ANY scroller under the touch can
+ * still move in that direction, with three narrowings that match the
+ * browser's own:
+ *
+ * - `touch-action` between the touch target and a scroller must allow the
+ *   axis, or the browser will not pan that scroller with a finger;
+ * - an `overscroll-behavior` other than `auto` on the axis stops the chain at
+ *   that scroller (a sheet body with `contain` never scrolls the page);
+ * - a finger moving down scrolls content toward its START (scrollTop
+ *   decreasing), and horizontally the range follows the writing direction
+ *   (RTL `scrollLeft` runs from minus the overflow to zero).
+ *
+ * Styles are read once per touch, on the first question; scroll offsets are
+ * read fresh on every question, since a native scroll moves them.
+ */
+
+import type {NativeScrollProbe} from './types';
+
+export interface AllowedPans {
+  readonly x: boolean;
+  readonly y: boolean;
+}
+
+/** Which pans a `touch-action` value lets the browser perform. */
+export function parseTouchAction(value: string): AllowedPans {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.includes('auto') || tokens.includes('manipulation')) {
+    return {x: true, y: true};
+  }
+  if (tokens.includes('none')) {
+    return {x: false, y: false};
+  }
+  return {
+    x: tokens.some(
+      token =>
+        token === 'pan-x' || token === 'pan-left' || token === 'pan-right',
+    ),
+    y: tokens.some(
+      token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down',
+    ),
+  };
+}
+
+interface ChainEntry {
+  readonly element: Element;
+  readonly x: boolean;
+  readonly y: boolean;
+  readonly isRtl: boolean;
+  readonly stopsX: boolean;
+  readonly stopsY: boolean;
+  /**
+   * The scroller sits beyond a `position: fixed` ancestor of the touch: it
+   * still scrolls under the finger, but it does not carry the touched
+   * element, so the element is not inside a scroll view (spec:AST-094 FR11).
+   */
+  readonly isBeyondFixed: boolean;
+}
+
+const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);
+const EDGE_TOLERANCE = 1;
+
+/**
+ * The node's parent in the flat tree: a slotted node's slot, then out of
+ * shadow roots to their hosts, so a scroller inside a shadow tree around the
+ * slot is found.
+ */
+export function parentAcrossShadow(node: Node): Node | null {
+  const slot =
+    node instanceof Element || node instanceof Text ? node.assignedSlot : null;
+  if (slot != null) {
+    return slot;
+  }
+  if (node.parentNode != null) {
+    return node.parentNode instanceof ShadowRoot
+      ? node.parentNode.host
+      : node.parentNode;
+  }
+  return null;
+}
+
+interface Chain {
+  readonly entries: ChainEntry[];
+  /** touch-action allows some pan all the way up. */
+  readonly allowsPan: boolean;
+}
+
+function buildChain(target: Element): Chain {
+  const doc = target.ownerDocument;
+  const view = doc.defaultView;
+  if (view == null) {
+    return {entries: [], allowsPan: false};
+  }
+  const root = doc.scrollingElement ?? doc.documentElement;
+  const chain: ChainEntry[] = [];
+  let allowX = true;
+  let allowY = true;
+  let reachedRoot = false;
+  let isBeyondFixed = false;
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    if (!(node instanceof Element)) {
+      continue;
+    }
+    const style = view.getComputedStyle(node);
+    const pans = parseTouchAction(style.touchAction || 'auto');
+    allowX &&= pans.x;
+    allowY &&= pans.y;
+    const isRoot = node === root || node === doc.documentElement;
+    if (isRoot) {
+      reachedRoot = true;
+    }
+    const overflowX = isRoot ? rootOverflow(doc, 'x') : style.overflowX;
+    const overflowY = isRoot ? rootOverflow(doc, 'y') : style.overflowY;
+    const scrollsX = SCROLLABLE.has(overflowX);
+    const scrollsY = SCROLLABLE.has(overflowY);
+    if (scrollsX || scrollsY) {
+      const element = isRoot ? root : node;
+      const [behaviorX, behaviorY] = overscrollBehavior(style);
+      chain.push({
+        element,
+        x: scrollsX && allowX,
+        y: scrollsY && allowY,
+        isRtl: style.direction === 'rtl',
+        stopsX: behaviorX !== 'auto',
+        stopsY: behaviorY !== 'auto',
+        isBeyondFixed,
+      });
+    }
+    if (isRoot) {
+      break;
+    }
+    if (style.position === 'fixed') {
+      isBeyondFixed = true;
+    }
+  }
+  if (!reachedRoot && root instanceof Element) {
+    chain.push({
+      element: root,
+      x: allowX && SCROLLABLE.has(rootOverflow(doc, 'x')),
+      y: allowY && SCROLLABLE.has(rootOverflow(doc, 'y')),
+      isRtl: false,
+      stopsX: false,
+      stopsY: false,
+      isBeyondFixed,
+    });
+  }
+  return {entries: chain, allowsPan: allowX || allowY};
+}
+
+/** `overscroll-behavior` per axis, from the longhands or the shorthand. */
+function overscrollBehavior(style: CSSStyleDeclaration): [string, string] {
+  const x = style.overscrollBehaviorX;
+  const y = style.overscrollBehaviorY;
+  if (x !== '' && y !== '' && x != null && y != null) {
+    return [x, y];
+  }
+  const [first = 'auto', second = first] = (
+    style.getPropertyValue('overscroll-behavior') || 'auto'
+  )
+    .trim()
+    .split(/\s+/);
+  return [x || first, y || second];
+}
+
+/**
+ * The viewport scrolls unless the root or the body clips it (a scroll lock
+ * sets `overflow: hidden` on one of them).
+ */
+function rootOverflow(doc: Document, axis: 'x' | 'y'): string {
+  const view = doc.defaultView;
+  if (view == null) {
+    return 'hidden';
+  }
+  for (const element of [doc.documentElement, doc.body]) {
+    if (element == null) {
+      continue;
+    }
+    const style = view.getComputedStyle(element);
+    const value = axis === 'x' ? style.overflowX : style.overflowY;
+    if (value === 'hidden' || value === 'clip') {
+      return 'hidden';
+    }
+  }
+  return 'auto';
+}
+
+function canMoveY(element: Element, dy: number): boolean {
+  if (element.scrollHeight - element.clientHeight <= EDGE_TOLERANCE) {
+    return false;
+  }
+  return dy > 0
+    ? element.scrollTop > EDGE_TOLERANCE - 0.5
+    : element.scrollTop <
+        element.scrollHeight - element.clientHeight - EDGE_TOLERANCE + 0.5;
+}
+
+function canMoveX(entry: ChainEntry, dx: number): boolean {
+  const {element} = entry;
+  const overflow = element.scrollWidth - element.clientWidth;
+  if (overflow <= EDGE_TOLERANCE) {
+    return false;
+  }
+  const min = entry.isRtl ? -overflow : 0;
+  const max = entry.isRtl ? 0 : overflow;
+  // A finger moving right drags the content right: scrollLeft decreases.
+  return dx > 0
+    ? element.scrollLeft > min + EDGE_TOLERANCE - 0.5
+    : element.scrollLeft < max - EDGE_TOLERANCE + 0.5;
+}
+
+/** A probe of the native scrollers under `target`. */
+export function createNativeScrollProbe(target: unknown): NativeScrollProbe {
+  let chain: Chain | null = null;
+  const getChain = (): ChainEntry[] => {
+    chain ??=
+      target instanceof Element
+        ? buildChain(target)
+        : {entries: [], allowsPan: false};
+    return chain.entries;
+  };
+  return {
+    canScroll(dx: number, dy: number): boolean {
+      const ax = Math.abs(dx);
+      const ay = Math.abs(dy);
+      // The minor axis of a mostly-straight drag is the hand's wobble, not
+      // a direction: the browser locks to the major one.
+      const considerX = ax > 0 && ax >= ay / 2;
+      const considerY = ay > 0 && ay >= ax / 2;
+      for (const entry of getChain()) {
+        if (considerY && entry.y && canMoveY(entry.element, dy)) {
+          return true;
+        }
+        if (considerX && entry.x && canMoveX(entry, dx)) {
+          return true;
+        }
+        const stops =
+          (!considerX || entry.stopsX) && (!considerY || entry.stopsY);
+        if (stops && (entry.stopsX || entry.stopsY)) {
+          return false;
+        }
+      }
+      return false;
+    },
+    get allowsNativePan(): boolean {
+      getChain();
+      return chain?.allowsPan === true;
+    },
+    get isInsideScroller(): boolean {
+      return getChain().some(
+        entry =>
+          !entry.isBeyondFixed &&
+          ((entry.y &&
+            entry.element.scrollHeight - entry.element.clientHeight >
+              EDGE_TOLERANCE) ||
+            (entry.x &&
+              entry.element.scrollWidth - entry.element.clientWidth >
+                EDGE_TOLERANCE)),
+      );
+    },
+  };
+}

package/src/gestures/touchAction.ts

@@ -0,0 +1,191 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchAction.ts
+ * @input The recognizers attached to one element
+ * @output Exports deriveTouchAction (the element's `touch-action`),
+ *   gestureHostStyle (the inline style a host sets for its recognizers),
+ *   intersectTouchAction (what both a derived and a caller's value allow) and
+ *   holdSelectionStyle (the selection and callout lock for one held press)
+ * @position Browser negotiation of packages/core/src/gestures, pure so a
+ *   server render can emit the same style the client would set
+ *
+ * `touch-action` is decided when the finger lands and cannot change during
+ * the gesture, so it must say up front what the browser may still do: the
+ * intersection of what every recognizer on the element leaves it.
+ *
+ * - A tap or long press only removes double-tap zoom (`manipulation`): no
+ *   300 ms click delay, scrolling and pinch-zoom untouched.
+ * - A one-axis pan or swipe gives the browser the other axis.
+ * - A pan that coordinates with native scrolling (`scrollEdge`) keeps both
+ *   axes: who gets the drag is decided once, when it begins, and a drag the
+ *   browser began scrolling stays the browser's to the lift (`spec:AST-094`
+ *   FR14).
+ * - `pinch-zoom` stays in every value unless a pinch recognizer is attached,
+ *   so the page stays zoomable (WCAG 1.4.4).
+ *
+ * WebKit pans a drag with any vertical component even under `pan-y`, so the
+ * value alone does not protect a horizontal pan there: the host also cancels
+ * `touchmove` while a recognizer owns the touch (see GestureHost.ts).
+ */
+
+import type {GestureRecognizer, NativeTouchBehavior} from './GestureRecognizer';
+
+/** The intersection of what each touch recognizer leaves the browser. */
+export function combinedNativeBehavior(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): NativeTouchBehavior {
+  let panX = true;
+  let panY = true;
+  let pinchZoom = true;
+  let doubleTapZoom = true;
+  for (const recognizer of recognizers) {
+    if (!recognizer.acceptsTouchInput) {
+      continue;
+    }
+    const behavior = recognizer.nativeTouchBehavior;
+    panX &&= behavior.panX;
+    panY &&= behavior.panY;
+    pinchZoom &&= behavior.pinchZoom;
+    doubleTapZoom &&= behavior.doubleTapZoom;
+  }
+  return {panX, panY, pinchZoom, doubleTapZoom};
+}
+
+/** The `touch-action` value for a set of recognizers, or null for none needed. */
+export function deriveTouchAction(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): string | null {
+  const behavior = combinedNativeBehavior(recognizers);
+  if (
+    behavior.panX &&
+    behavior.panY &&
+    behavior.pinchZoom &&
+    behavior.doubleTapZoom
+  ) {
+    return null;
+  }
+  if (behavior.panX && behavior.panY && behavior.pinchZoom) {
+    return 'manipulation';
+  }
+  const tokens: string[] = [];
+  if (behavior.panX) {
+    tokens.push('pan-x');
+  }
+  if (behavior.panY) {
+    tokens.push('pan-y');
+  }
+  if (behavior.pinchZoom) {
+    tokens.push('pinch-zoom');
+  }
+  return tokens.length === 0 ? 'none' : tokens.join(' ');
+}
+
+export interface GestureHostStyle {
+  touchAction?: string;
+  WebkitTouchCallout?: string;
+  WebkitUserSelect?: string;
+  userSelect?: string;
+}
+
+/**
+ * The style a host sets for these recognizers while they are attached: the
+ * `touch-action`. Text selection is not locked here: a mouse, a keyboard and
+ * assistive technology keep selecting as they do today (spec:AST-017 FR59,
+ * spec:AST-094 FR41).
+ */
+export function gestureHostStyle(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): GestureHostStyle {
+  const style: GestureHostStyle = {};
+  const touchAction = deriveTouchAction(recognizers);
+  if (touchAction != null) {
+    style.touchAction = touchAction;
+  }
+  return style;
+}
+
+/** What a `touch-action` value lets the browser do, as tokens. */
+const ALL_PANS = [
+  'pan-left',
+  'pan-right',
+  'pan-up',
+  'pan-down',
+  'pinch-zoom',
+] as const;
+
+function touchActionTokens(value: string): Set<string> {
+  const parts = value
+    .trim()
+    .split(/\s+/)
+    .filter(part => part !== '');
+  const tokens = new Set<string>();
+  if (parts.length === 0) {
+    parts.push('auto');
+  }
+  for (const part of parts) {
+    if (part === 'auto') {
+      ALL_PANS.forEach(token => tokens.add(token));
+      tokens.add('double-tap-zoom');
+    } else if (part === 'manipulation') {
+      ALL_PANS.forEach(token => tokens.add(token));
+    } else if (part === 'pan-x') {
+      tokens.add('pan-left').add('pan-right');
+    } else if (part === 'pan-y') {
+      tokens.add('pan-up').add('pan-down');
+    } else if ((ALL_PANS as ReadonlyArray<string>).includes(part)) {
+      tokens.add(part);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * The `touch-action` that allows only what both values allow: the host's
+ * derived value never overrides a caller's narrower one.
+ */
+export function intersectTouchAction(derived: string, caller: string): string {
+  const own = touchActionTokens(caller);
+  const both = new Set(
+    [...touchActionTokens(derived)].filter(token => own.has(token)),
+  );
+  if (ALL_PANS.every(token => both.has(token))) {
+    return both.has('double-tap-zoom') ? 'auto' : 'manipulation';
+  }
+  const parts: string[] = [];
+  for (const [axis, start, end] of [
+    ['pan-x', 'pan-left', 'pan-right'],
+    ['pan-y', 'pan-up', 'pan-down'],
+  ] as const) {
+    if (both.has(start) && both.has(end)) {
+      parts.push(axis);
+    } else if (both.has(start)) {
+      parts.push(start);
+    } else if (both.has(end)) {
+      parts.push(end);
+    }
+  }
+  if (both.has('pinch-zoom')) {
+    parts.push('pinch-zoom');
+  }
+  return parts.length === 0 ? 'none' : parts.join(' ');
+}
+
+/**
+ * The lock a host applies for one press only, from touch-down to the lift or
+ * a cancel, on an element whose hold does something (a long press): no iOS
+ * callout and no text-selection start under the held finger, as a
+ * long-pressed row in UIKit selects no text (spec:AST-094 FR41). Null where
+ * the hold does nothing, so a long press there selects natively.
+ */
+export function holdSelectionStyle(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): GestureHostStyle | null {
+  const holds = recognizers.some(
+    recognizer =>
+      recognizer.kind === 'longPress' && recognizer.acceptsTouchInput,
+  );
+  return holds
+    ? {WebkitTouchCallout: 'none', WebkitUserSelect: 'none', userSelect: 'none'}
+    : null;
+}

package/src/gestures/touchActionRule.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchActionRule.ts
+ * @input An element and the touch-action its recognizers derive
+ * @output Exports markTouchAction and unmarkTouchAction: the element carries
+ *   the derived value in TOUCH_ACTION_ATTRIBUTE, and its document or shadow
+ *   root holds one zero-specificity rule per value in the first cascade
+ *   layer (`reset`), so any author rule, in any layer or none, or inline
+ *   value outranks the host's (`spec:AST-094` FR18, DEC-8); a root's rules
+ *   go with its last marked element (FR24)
+ * @position The gesture host's touch-action writer (GestureHost.ts)
+ *
+ * The mark is set as a recognizer attaches, so a subtree that mounts with
+ * it is styled once with its touch-action: a value written after that first
+ * styling restyles every descendant (each one's effective touch-action
+ * changes). Until the host reads the element's own value, the value in
+ * force is the author's where the author sets one, and the derived value
+ * elsewhere: never wider than the author's.
+ *
+ * SYNC: When modified, update GestureHost.ts.
+ */
+
+/** The attribute that carries the host's derived touch-action. */
+export const TOUCH_ACTION_ATTRIBUTE = 'data-astryx-touch-action';
+
+/**
+ * The cascade layer the rules sit in: the first in the order every package
+ * stylesheet declares (`spec:AST-080` FR3), so an author rule in any later
+ * layer, or in none, outranks them. Unlayered, they would outrank every
+ * layered author rule.
+ */
+const RULE_LAYER = 'reset';
+
+type RuleRoot = Document | ShadowRoot;
+
+/**
+ * Per document or shadow root: the values it has a rule for, their rules'
+ * text, where that text goes (an adopted sheet, or a style element where
+ * constructable sheets are missing), and the elements marked there. The
+ * rules go with the root's last marked element (`spec:AST-094` FR24).
+ */
+const sheets = new WeakMap<
+  RuleRoot,
+  {
+    readonly values: Set<string>;
+    readonly marked: Set<Element>;
+    css: string;
+    write(css: string): void;
+    remove(): void;
+  }
+>();
+
+/** Where each marked element's rule lives, for its unmark after it leaves. */
+const markedRoots = new WeakMap<Element, RuleRoot>();
+
+function sheetOf(root: RuleRoot) {
+  let entry = sheets.get(root);
+  if (entry == null) {
+    const doc = root.nodeType === 9 ? (root as Document) : root.ownerDocument;
+    let write: ((css: string) => void) | undefined;
+    let remove: (() => void) | undefined;
+    // A constructable sheet where the engine has one; a style element only
+    // where it has none, so any other error from a sheet is not hidden.
+    const Sheet = doc?.defaultView?.CSSStyleSheet;
+    if (
+      typeof Sheet === 'function' &&
+      'replaceSync' in Sheet.prototype &&
+      'adoptedStyleSheets' in root
+    ) {
+      const sheet = new Sheet();
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+      write = css => sheet.replaceSync(css);
+      remove = () => {
+        root.adoptedStyleSheets = root.adoptedStyleSheets.filter(
+          adopted => adopted !== sheet,
+        );
+      };
+    } else {
+      const style = doc?.createElement('style');
+      const parent =
+        root.nodeType === 9 ? (doc?.head ?? doc?.documentElement) : root;
+      if (style != null && parent != null) {
+        parent.append(style);
+        write = css => {
+          style.textContent = css;
+        };
+        remove = () => style.remove();
+      }
+    }
+    if (write == null || remove == null) {
+      return null;
+    }
+    entry = {values: new Set(), marked: new Set(), css: '', write, remove};
+    sheets.set(root, entry);
+  }
+  return entry;
+}
+
+/**
+ * Give `element` the derived touch-action under a rule any author rule
+ * outranks. Returns false where no rule can hold it (a detached element):
+ * the caller writes nothing until the element is in a document.
+ */
+export function markTouchAction(element: Element, value: string): boolean {
+  const root = element.getRootNode() as RuleRoot;
+  const entry =
+    element.isConnected && (root.nodeType === 9 || 'host' in root)
+      ? sheetOf(root)
+      : null;
+  if (entry == null) {
+    return false;
+  }
+  if (!entry.values.has(value)) {
+    entry.values.add(value);
+    entry.css += `:where([${TOUCH_ACTION_ATTRIBUTE}="${value}"]){touch-action:${value}}`;
+    entry.write(`@layer ${RULE_LAYER}{${entry.css}}`);
+  }
+  if (element.getAttribute(TOUCH_ACTION_ATTRIBUTE) !== value) {
+    element.setAttribute(TOUCH_ACTION_ATTRIBUTE, value);
+  }
+  const previous = markedRoots.get(element);
+  if (previous != null && previous !== root) {
+    // Moved to another root: the old one lets it go.
+    releaseMark(element, previous);
+  }
+  entry.marked.add(element);
+  markedRoots.set(element, root);
+  return true;
+}
+
+/** `root` no longer holds `element`'s mark; its last mark takes the rules. */
+function releaseMark(element: Element, root: RuleRoot): void {
+  const entry = sheets.get(root);
+  if (entry == null) {
+    return;
+  }
+  entry.marked.delete(element);
+  if (entry.marked.size === 0) {
+    entry.remove();
+    sheets.delete(root);
+  }
+}
+
+/**
+ * Remove the host's mark; the element's own touch-action stands. The last
+ * mark in a document or shadow root takes its rules with it.
+ */
+export function unmarkTouchAction(element: Element): void {
+  element.removeAttribute(TOUCH_ACTION_ATTRIBUTE);
+  const root = markedRoots.get(element);
+  if (root == null) {
+    return;
+  }
+  markedRoots.delete(element);
+  releaseMark(element, root);
+}

package/src/gestures/types.ts

@@ -46,13 +46,6 @@ export interface NativeScrollProbe {
    * lets the browser pan that axis).
    */
   canScroll(dx: number, dy: number): boolean;
-  /**
-   * How much further (px) the scroller that would move for a finger moving
-   * by (dx, dy) can scroll before it reaches its edge; 0 when none would.
-   * Lets a reader place the point where the content runs out between two
-   * samples instead of at the next one.
-   */
-  distanceToEdge?(dx: number, dy: number): number;
   /** Whether any element under the touch can scroll natively at all. */
   readonly isInsideScroller: boolean;
   /**
@@ -127,6 +120,17 @@ export interface GestureEventContext {
 export interface GestureEnvironment {
   viewportSize(): {readonly width: number; readonly height: number};
   isRtl(view: unknown): boolean;
+  /**
+   * The box of a recognizer's view in viewport coordinates, or null when it
+   * has none to measure. A screen-edge pan reads it to tell a view within
+   * its edge band from any other.
+   */
+  viewRect?(view: unknown): {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
 }
 
 export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
@@ -136,8 +140,18 @@ export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
     }
     return {width: window.innerWidth, height: window.innerHeight};
   },
-  isRtl() {
-    return false;
+  isRtl(view) {
+    if (typeof window === 'undefined' || !(view instanceof Element)) {
+      return false;
+    }
+    return window.getComputedStyle(view).direction === 'rtl';
+  },
+  viewRect(view) {
+    if (typeof Element === 'undefined' || !(view instanceof Element)) {
+      return null;
+    }
+    const {left, top, width, height} = view.getBoundingClientRect();
+    return {left, top, width, height};
   },
 };
 
@@ -158,4 +172,11 @@ export interface TouchConsumer {
    * (attached above this consumer) from beginning for a touch on it.
    */
   allowsAncestorRecognizer?(recognizer: unknown): boolean;
+  /**
+   * Whether the consumer takes touches now (a disabled control does not).
+   * The host listens only while something enabled is attached
+   * (`spec:AST-094` FR24); after this changes, call `host.update(element)`.
+   * @default true
+   */
+  isEnabled?(): boolean;
 }