@nvidia-elements/core 2.8.1 → 2.9.0

package/dist/internal/controllers/gesture.controller.d.ts

@@ -1,65 +1,145 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
-export interface GestureCapabilities {
-    readonly drag: boolean;
-    readonly pan: boolean;
-    readonly pinch: boolean;
-    readonly wheel: boolean;
+export interface PointerClaimOptions {
+    readonly kind?: 'drag' | 'pan';
+    readonly pinchCandidate?: boolean;
 }
-interface PointerMovementGesture {
+export interface PinchStartDecision<TContext> {
+    readonly context: TContext;
+}
+/** Coordinates and deltas use CSS pixels; movement is sample-relative and total displacement is start-relative. */
+export interface PointerMovementGesture {
     readonly event: PointerEvent;
+    readonly clientX: number;
+    readonly clientY: number;
     readonly movementX: number;
     readonly movementY: number;
+    readonly startClientX: number;
+    readonly startClientY: number;
+    readonly totalDisplacementX: number;
+    readonly totalDisplacementY: number;
+}
+export interface PinchStart {
+    readonly firstPointerId: number;
+    readonly firstPointerType: string;
+    readonly firstStartClientX: number;
+    readonly firstStartClientY: number;
+    readonly secondPointerId: number;
+    readonly secondPointerType: string;
+    readonly secondStartClientX: number;
+    readonly secondStartClientY: number;
+    readonly startCenterClientX: number;
+    readonly startCenterClientY: number;
+}
+export interface PinchGesture<TContext> extends PinchStart {
+    readonly kind: 'pinch';
+    readonly event: PointerEvent;
+    readonly context: TContext;
+    /** Current pointer distance divided by the starting pointer distance. */
+    readonly scale: number;
+    readonly centerClientX: number;
+    readonly centerClientY: number;
+}
+/**
+ * Per-event wheel input normalized to CSS pixels.
+ *
+ * Modifier-assisted trackpad pinch remains wheel input: consumers can classify it using the native event's
+ * `ctrlKey` or `metaKey` without conflating it with the start-relative lifecycle of a two-pointer pinch.
+ */
+export interface WheelGesture {
+    readonly kind: 'wheel';
+    readonly event: WheelEvent;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly deltaX: number;
+    readonly deltaY: number;
+}
+export type PointerEndReason = 'up' | 'cancel' | 'lost-capture' | 'buttons-released';
+export interface PointerEndGesture extends PointerMovementGesture {
+    readonly kind: 'pointerend';
+    /** Whether the pointer session ended without an observed physical release. */
+    readonly interrupted: boolean;
+    readonly reason: PointerEndReason;
 }
 export type Gesture<TPinchContext> = (PointerMovementGesture & {
     readonly kind: 'drag';
 }) | (PointerMovementGesture & {
     readonly kind: 'pan';
-}) | {
-    readonly context: TPinchContext;
-    readonly event: PointerEvent;
-    readonly kind: 'pinch';
-    readonly scale: number;
-} | {
-    readonly deltaPixels: number;
-    readonly event: WheelEvent;
-    readonly kind: 'wheel';
-};
-export type UnhandledPointerInput = {
-    readonly event: PointerEvent;
-    readonly kind: 'click';
-} | {
-    readonly event: PointerEvent;
-    readonly kind: 'lostpointercapture';
-} | {
-    readonly event: PointerEvent;
-    readonly kind: 'pointercancel';
-} | {
+}) | PinchGesture<TPinchContext>;
+export interface PointerDownInput {
     readonly event: PointerEvent;
     readonly kind: 'pointerdown';
-} | {
-    readonly event: PointerEvent;
-    readonly kind: 'pointermove';
-} | {
-    readonly event: PointerEvent;
-    readonly kind: 'pointerup';
-};
+    /**
+     * Claims this pointer sequence once during the synchronous input dispatch and suppresses native text selection for
+     * its lifetime; returns `false` after that window.
+     */
+    readonly claim: (options?: PointerClaimOptions) => boolean;
+}
+export interface WheelGestureInput extends WheelGesture {
+    /** Claims and prevents this wheel event during the synchronous input dispatch; returns `false` afterward. */
+    readonly claim: () => boolean;
+}
+/** Claimable starts, claimed pointer terminals, and normalized claimable wheel input. */
+export type GestureInput = PointerDownInput | PointerEndGesture | WheelGestureInput;
+/** Precedence policy for claims among nested GestureController targets. */
+export type GestureClaimPriority = 'self-first' | 'descendant-first';
 export interface GestureControllerOptions<TPinchContext = undefined> {
-    /** Creates a snapshot of caller state when a pinch begins. Omit this field to disable pinch recognition. */
-    readonly createPinchContext?: () => TPinchContext;
-    /** Returns the gesture kinds that the controller can recognize for the current input event. */
-    readonly getCapabilities: () => GestureCapabilities;
-    /** Updates caller state before the controller reads capabilities for a nonignored input event. */
-    readonly prepare?: () => void;
-    /** Returns whether the controller should skip an input event before preparing or recognizing it. */
-    readonly shouldIgnore?: (event: Event) => boolean;
+    /**
+     * Skips admission of a new pointer sequence or a stateless native event.
+     * The controller does not consult it again after a pointerdown claim.
+     */
+    readonly shouldIgnoreEvent?: (event: Event) => boolean;
+    /**
+     * Consulted once when the controller first observes two claimed pinch candidates.
+     * Returning `undefined` declines that pair; otherwise the controller retains the context for its pinch lifetime.
+     * The pair remains locked until fewer than two pinch candidates remain.
+     */
+    readonly beginPinch?: (start: PinchStart) => PinchStartDecision<TPinchContext> | undefined;
+    /** Consulted independently for each context-menu event. */
+    readonly shouldPreventContextMenu?: (event: MouseEvent) => boolean;
+    /**
+     * Determines precedence among nested GestureController targets.
+     *
+     * `self-first` is appropriate for a dedicated interaction surface.
+     * `descendant-first` lets nested controllers claim input before this controller.
+     *
+     * Defaults to `self-first`.
+     */
+    readonly claimPriority?: GestureClaimPriority;
+    /**
+     * Consulted during native pointerdown capture before descendant handlers.
+     *
+     * Returning true calls preventDefault() on the pointerdown, but does not
+     * claim the pointer, capture it, stop propagation, create pointer state,
+     * suppress selection, or start a gesture.
+     *
+     * This is meaningful with `claimPriority: 'descendant-first'`. It lets an
+     * activated higher-level interaction mode reserve a sequence for ordinary
+     * target-phase application code while preserving nested GestureController
+     * claim priority.
+     */
+    readonly shouldReservePointerDown?: (event: PointerEvent) => boolean;
+    /** Prevents native HTML drag competition on a dedicated interaction surface. */
+    readonly suppressNativeDrag?: boolean;
+    /**
+     * Inline `touch-action` for a dedicated interaction surface. The controller reevaluates a callback after host updates.
+     * Restores the target's prior inline value afterward.
+     * Avoid applying it to a general root that contains native interactive content.
+     */
+    readonly touchAction?: string | (() => string | undefined);
 }
 type GestureHost = EventTarget & ReactiveControllerHost;
-/** Recognizes drag, pan, pinch, and wheel input on a dynamically assigned target. */
+/**
+ * Normalizes claimable platform pointer and wheel input on a dynamically assigned target.
+ * A pointer claim owns native input competition for its lifetime: the controller prevents claimed movement and text
+ * selection, and can suppress native drag when configured.
+ */
 export declare class GestureController<TPinchContext = undefined> implements ReactiveController {
     #private;
     constructor(host: GestureHost, options: GestureControllerOptions<TPinchContext>);
+    getWheelZoomFactor(input: Pick<WheelGesture, 'deltaY' | 'event'>): number;
     set target(target: HTMLElement | undefined);
     hostConnected(): void;
     hostDisconnected(): void;
+    hostUpdated(): void;
 }
 export {};

package/dist/internal/controllers/gesture.controller.examples.js.map

@@ -1 +1 @@
-{"version":3,"file":"gesture.controller.examples.js","names":[],"sources":["../../../src/internal/controllers/gesture.controller.examples.ts"],"sourcesContent":["// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n// SPDX-License-Identifier: Apache-2.0\n\nimport { css, html, LitElement } from 'lit';\nimport { GestureController } from '@nvidia-elements/core/internal';\n\nexport default {\n  title: 'Internal/Controllers'\n};\n\nclass GestureDemoElement extends LitElement {\n  readonly #gestureController = new GestureController(this, {\n    getCapabilities: () => ({ drag: true, pan: false, pinch: false, wheel: false })\n  });\n\n  static styles = css`\n    :host {\n      cursor: grab;\n      display: grid;\n      height: 64px;\n      place-items: center;\n      width: 64px;\n    }\n\n    :host([data-active]) {\n      cursor: grabbing;\n    }\n  `;\n\n  constructor() {\n    super();\n    this.#gestureController.target = this;\n  }\n\n  render() {\n    return html`drag`;\n  }\n}\n\nif (!customElements.get('gesture-controller-demo-element')) {\n  customElements.define('gesture-controller-demo-element', GestureDemoElement);\n}\n\n/**\n * @summary Drag recognition delivered through gesture and unmatched pointer events. Use event details to move content and represent active pointer state.\n * @tags test-case\n */\nexport const Drag = {\n  render: () => html`\n<gesture-controller-demo-element></gesture-controller-demo-element>\n<script type=\"module\">\n  const element = document.querySelector('gesture-controller-demo-element');\n  let x = 0;\n  let y = 0;\n\n  element.addEventListener('nve-pointer-input', ({ detail }) => {\n    if (detail.kind === 'pointerdown') element.dataset.active = '';\n    if (detail.kind === 'pointerup' || detail.kind === 'pointercancel') delete element.dataset.active;\n  });\n\n  element.addEventListener('nve-gesture', ({ detail }) => {\n    if (detail.kind !== 'drag') return;\n    x += detail.movementX;\n    y += detail.movementY;\n    element.style.translate = x + 'px ' + y + 'px';\n  });\n</script>\n`\n};\n"],"mappings":";AAGA,IAAA,IAAc"}
+{"version":3,"file":"gesture.controller.examples.js","names":[],"sources":["../../../src/internal/controllers/gesture.controller.examples.ts"],"sourcesContent":["// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n// SPDX-License-Identifier: Apache-2.0\n\nimport { css, html, LitElement } from 'lit';\nimport { GestureController } from '@nvidia-elements/core/internal';\n\nexport default {\n  title: 'Internal/Controllers'\n};\n\nclass GestureDemoElement extends LitElement {\n  readonly #gestureController = new GestureController(this, {});\n\n  static styles = css`\n    :host {\n      cursor: grab;\n      display: grid;\n      height: 64px;\n      place-items: center;\n      width: 64px;\n    }\n\n    :host([data-active]) {\n      cursor: grabbing;\n    }\n  `;\n\n  constructor() {\n    super();\n    this.#gestureController.target = this;\n  }\n\n  render() {\n    return html`drag`;\n  }\n}\n\nif (!customElements.get('gesture-controller-demo-element')) {\n  customElements.define('gesture-controller-demo-element', GestureDemoElement);\n}\n\n/**\n * @summary Synchronously claimed pointer input produces drag gestures while preserving start and end input. Use this pattern when a control owns a pointer sequence.\n * @tags test-case\n */\nexport const Drag = {\n  render: () => html`\n<gesture-controller-demo-element></gesture-controller-demo-element>\n<script type=\"module\">\n  const element = document.querySelector('gesture-controller-demo-element');\n  let x = 0;\n  let y = 0;\n\n  element.addEventListener('nve-gesture-input', ({ detail }) => {\n    if (detail.kind === 'pointerdown' && detail.claim({ kind: 'drag' })) element.dataset.active = '';\n    if (detail.kind === 'pointerend') delete element.dataset.active;\n  });\n\n  element.addEventListener('nve-gesture', ({ detail }) => {\n    if (detail.kind !== 'drag') return;\n    x += detail.movementX;\n    y += detail.movementY;\n    element.style.translate = x + 'px ' + y + 'px';\n  });\n</script>\n`\n};\n"],"mappings":";AAGA,IAAA,IAAc"}

package/dist/internal/controllers/gesture.controller.examples.json

@@ -4,8 +4,8 @@
     {
       "id": "internal-controllers-gesture.controller-drag",
       "name": "Drag",
-      "template": "<gesture-controller-demo-element></gesture-controller-demo-element>\n<script type=\"module\">\n  const element = document.querySelector(\"gesture-controller-demo-element\");\n  let x = 0;\n  let y = 0;\n  element.addEventListener(\"nve-pointer-input\", ({ detail }) => {\n    if (detail.kind === \"pointerdown\") element.dataset.active = \"\";\n    if (detail.kind === \"pointerup\" || detail.kind === \"pointercancel\") delete element.dataset.active;\n  });\n  element.addEventListener(\"nve-gesture\", ({ detail }) => {\n    if (detail.kind !== \"drag\") return;\n    x += detail.movementX;\n    y += detail.movementY;\n    element.style.translate = x + \"px \" + y + \"px\";\n  });\n</script>\n",
-      "summary": "Drag recognition delivered through gesture and unmatched pointer events. Use event details to move content and represent active pointer state.",
+      "template": "<gesture-controller-demo-element></gesture-controller-demo-element>\n<script type=\"module\">\n  const element = document.querySelector(\"gesture-controller-demo-element\");\n  let x = 0;\n  let y = 0;\n  element.addEventListener(\"nve-gesture-input\", ({ detail }) => {\n    if (detail.kind === \"pointerdown\" && detail.claim({ kind: \"drag\" })) element.dataset.active = \"\";\n    if (detail.kind === \"pointerend\") delete element.dataset.active;\n  });\n  element.addEventListener(\"nve-gesture\", ({ detail }) => {\n    if (detail.kind !== \"drag\") return;\n    x += detail.movementX;\n    y += detail.movementY;\n    element.style.translate = x + \"px \" + y + \"px\";\n  });\n</script>\n",
+      "summary": "Synchronously claimed pointer input produces drag gestures while preserving start and end input. Use this pattern when a control owns a pointer sequence.",
       "description": "",
       "composition": false,
       "tags": [