@weasel-js/gestures 1.11.0 → 1.12.0

package/dist/index.d.ts

@@ -81,10 +81,13 @@ type RoutePhase = 'initial' | 'engaged';
  *   argSlot     = '(' argValue ')'                     -- whitespace inside parens is significant
  *   targetSlot  = '=>' WS targetValue                  -- omitted slot defaults to '*' for hasTarget
  *   modSlot     = modAtom (WS modAtom)*
- *   modAtom     = sigil modName
+ *   modAtom     = sigil (modName | 'held')
  *   sigil       = '+' | '?'                            -- ! @ # $ % ^ & * reserved as id-prefix
  *   modName     = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
  *
+ * `held` is a pressed button, read as a modifier is: `?held` a button may be
+ * held, `+held` one must be, absent none may. Only `hover` takes it.
+ *
  * The truly-loose form (any channel, any phase) is `[*:*]`.
  *
  * Examples:
@@ -152,6 +155,9 @@ interface ParsedRoute {
     target: string | undefined;
     /** Structured modifier requirements; empty map = "no modifiers held". */
     modifiers: ParsedModifiers;
+    /** Whether a pressed button may or must be held. Absent, none may. Only on
+     *  `hover`. */
+    held?: ModRequirement;
 }
 /** Parse a route string into its slots, filling in the shorthand defaults the
  *  grammar defines (bare phases mean channel `&`; an omitted arg or target
@@ -338,7 +344,8 @@ interface PointerDownSpec {
 }
 /**
  * The pointer moving over the surface with no button pressed. Fires on every
- * such move; a held pointer's moves belong to its drag and fire nothing here.
+ * such move; a held pointer's moves belong to its drag and fire nothing here,
+ * unless `held` says otherwise.
  *
  * With `motion: 'leave'` it fires instead when the pointer passes out of what
  * the binding targets: onto something its `target` does not match, or off the
@@ -349,11 +356,16 @@ interface PointerDownSpec {
  * runs, not only the best one, and the move still reaches the hover-cursor
  * pump. There is no press to own, so bind an immediate action, not an ongoing
  * one. Its params carry `worldX` / `worldY`, `clientX` / `clientY`,
- * `affordance`, `bodyTarget`, and `mods`.
+ * `affordance`, `bodyTarget`, `mods`, and `held`.
  */
 interface HoverSpec {
     kind: 'hover';
     motion?: 'move' | 'leave';
+    /** Whether a pressed button may (`'optional'`) or must (`true`) be held, as
+     *  `mods` says of a modifier; omitted, a held pointer's moves are not hovers.
+     *  Such a binding still claims nothing, so the drag keeps its moves. Leaving
+     *  the surface is a leave whether or not a button is held. */
+    held?: true | 'optional';
     target?: TargetSpec;
     mods?: ModSpec;
     phase?: PhaseSpec;
@@ -410,10 +422,15 @@ interface DropSpec {
  * its moves update it, the release commits it, and leaving the surface or
  * canceling the press cancels it. An immediate action fires once, on the
  * release.
+ *
+ * `target` is matched against what is under the carry. With one, an ongoing
+ * action starts on the first step that is over its target, as the carry comes
+ * over or as it moves on, and an immediate action fires only on a release over it.
  */
 interface CarrySpec {
     kind: 'carry';
     types?: string[];
+    target?: TargetSpec;
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
@@ -795,6 +812,8 @@ interface HoverEvent extends EventModifiers {
     from?: HoverWhere;
     /** The pointer has left the surface. Where it is and what it is over are its last move's. */
     off?: boolean;
+    /** A button was held through this move. Never set on `off`. */
+    held?: boolean;
     /** World-space position of the pointer. */
     x: number;
     y: number;
@@ -899,6 +918,10 @@ interface CarryEvent extends EventModifiers {
     y: number;
     clientX: number;
     clientY: number;
+    /** What is under the carry, classified as a press there would be. */
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+    bodyKind?: BodyKind;
 }
 /** External content pasted from the system clipboard. Carries no point. */
 interface PasteEvent extends EventModifiers {
@@ -1141,15 +1164,31 @@ type ShortcutInput = MenuShortcut;
 interface FormatShortcutOptions {
     /** Defaults to the detected platform. */
     platform?: Platform;
+    /** {@link formatShortcutParts} only; {@link formatShortcut} picks its own. Defaults to `'auto'`. */
+    legend?: LegendStyle;
 }
-/** Format a shortcut as an array of display chips, one per key: the
- *  modifiers, then the key, each as the platform's keyboard prints it, so
- *  `mod` is `⌘` on macOS and `Ctrl` elsewhere. UIs that want a boxed per-key
- *  look render each chip in its own element. `shift: 'optional'` is treated
- *  as falsy. */
-declare function formatShortcutParts(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): readonly string[] | undefined;
+/** One keymap on the way to a key: its label, and the chips of the leader that opens it. */
+interface ShortcutLeaderStep {
+    label: string;
+    keys: readonly KeyLegend[];
+}
+/** A shortcut as display chips: {@link formatShortcutParts}'s result. */
+interface ShortcutParts {
+    /** The keymaps leading to the key, outermost first; empty for a key outside any keymap. */
+    leader: readonly ShortcutLeaderStep[];
+    /** The key's own chips: the modifiers, then the key. */
+    keys: readonly KeyLegend[];
+}
+/** What {@link formatShortcut} writes after each leader step's label: `Loupe ▸ 2`. */
+declare const SHORTCUT_LEADER_SEPARATOR = " \u25B8 ";
+/** Format a shortcut as display chips, one per key: the modifiers, then the
+ *  key, each as the platform's keyboard prints it, so `mod` is `⌘` on macOS
+ *  and `Ctrl` elsewhere, after the keymaps that lead to it (`Loupe ▸ 2`).
+ *  UIs that want a boxed per-key look render each chip in its own element.
+ *  `shift: 'optional'` gives an optional chip. */
+declare function formatShortcutParts(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): ShortcutParts | undefined;
 /** Format a shortcut as a single display string. Order: mod, shift, alt,
- *  key. On macOS the glyphs run together (`⌘⇧Z`); elsewhere the keys are
+ *  key, after each keymap that leads to it (`Loupe ▸ ⌘2`). On macOS the glyphs run together (`⌘⇧Z`); elsewhere the keys are
  *  spelled out and joined with `+` (`Ctrl+Shift+Z`). Returns `undefined` for
  *  `undefined` input so callers can `??` a fallback. When `key` is an array,
  *  the first element is used. `shift: 'optional'` is treated as falsy. */
@@ -1158,7 +1197,7 @@ declare function formatShortcut(b: ShortcutInput | undefined, opts?: FormatShort
 /**
  * A shortcut as key legends, one per key, as `@weasel-js/ui`'s `KeySequence` draws them: mod, shift, alt, then the
  * key, each in the platform's own legend (`⌘` on macOS, `Ctrl` elsewhere).
- * `formatShortcutParts` is these labels as strings. `shift: 'optional'`
+ * Only the key itself: `formatShortcutParts` adds the keymaps that lead to it. `shift: 'optional'`
  * becomes an optional key; a key list
  * renders its first key. Returns `undefined` for no shortcut.
  *
@@ -1168,6 +1207,32 @@ declare function formatShortcut(b: ShortcutInput | undefined, opts?: FormatShort
  */
 declare function keySpecsFromShortcut(shortcut: ShortcutInput | undefined, opts?: KeySpecsFromModsOptions): readonly KeyLegend[] | undefined;
 
+/**
+ * The legend of the physical key a `KeyboardEvent.code` names (`KeyA`, `ShiftLeft`, `ArrowUp`), as
+ * {@link keySpecFromKey} prints that key on the platform: `MetaLeft` is `⌘` on macOS and `⊞` on
+ * Windows. Letters and punctuation print as a US keyboard prints them. `opts.labels` answers by code
+ * first, then as it does for {@link keySpecFromKey} and {@link keySpecsFromMods}.
+ */
+declare function keySpecFromCode(code: string, opts?: KeySpecsFromModsOptions): KeyLegend;
+
+/** A keystroke in the `Mod+Shift+K` form. Modifiers are case-insensitive:
+ *  `Meta`/`Cmd`/`Command`, `Ctrl`/`Control`, `Alt`/`Option`, `Shift`, and
+ *  `Mod` for Cmd on Apple platforms and Ctrl elsewhere. */
+declare function key(shortcut: string): KeySpec;
+/** The same keystroke held down, as a `key-held` spec. */
+declare function held(shortcut: string): KeyHeldSpec;
+/** A binding override that removes the binding. */
+declare function unbound(): null;
+/** What a binding override is written as: a route string, a spec, or `null` to unbind. */
+type BindingOverrideInput = string | GestureSpec | null;
+/** Read a binding override into the spec it names, or `null`. */
+declare function bindingSpec(input: BindingOverrideInput): GestureSpec | null;
+/** A key spec as its route string — what `bindingSpec` reads back to an
+ *  equal spec — or `null` for a key the route grammar cannot spell (`?`,
+ *  `)`, `*`). A spec is plain JSON, so store that one as it is. A key list is
+ *  written as its first key. */
+declare function keySpecRoute(spec: KeySpec | KeyHeldSpec): string | null;
+
 /**
  * The nearest element `from` sits inside that can host a portalled overlay,
  * or `null` when there is none and the body is the only answer.
@@ -1356,6 +1421,13 @@ interface PointerSample extends EventModifiers, PointerSampleStylus {
     clientY: number;
     /** What the originating event was aimed at. */
     target?: unknown;
+    /**
+     * When the input happened, on the recognizer clock's timeline: a DOM event's
+     * `timeStamp` beside `performance.now()`. The windows between two inputs are
+     * measured on it, so a long task that delays an event's handling does not
+     * widen them. Read as the clock's `now()` when absent, 0, or ahead of it.
+     */
+    timeStamp?: number;
 }
 /** A pointer going down, with what the host found under it. */
 interface PressSample extends PointerSample {
@@ -1485,4 +1557,4 @@ declare function activatesFocusedControl(e: KeyboardEvent): boolean;
  */
 declare function focusedControlOwnsKey(e: KeyboardEvent): boolean;
 
-export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type CarryEvent, type CarrySpec, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickMemory, type ClickObserver, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickBody, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, type FormatShortcutOptions, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeyLabels, type KeyLegend, type KeySpec, type KeySpecsFromModsOptions, LONG_PRESS_MS, type LegendStyle, type LogicalMod, type LogicalModSpec, type LongPressEvent, type LongPressSpec, MODIFIER_LABELS, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchGeometry, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type Platform, type Point, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerRecognizer, type PointerRecognizerOptions, type PointerSample, type PointerSampleStylus, type PointerUpEvent, type PressFacts, type PressSample, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RecognizerClock, type RecognizerObserver, type RecognizerSink, type ReleaseFacts, type ReleaseOutcome, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, type ShortcutInput, TAP_THRESHOLD_PX, type TargetPredicate, type TargetSpec, type TargetSpecForm, UNKNOWN_MIME, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, detectPlatform, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, formatShortcut, formatShortcutParts, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, keySpecFromKey, keySpecsFromMods, keySpecsFromShortcut, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };
+export { ACTIVE_SIGILS, type BindingOverrideInput, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type CarryEvent, type CarrySpec, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickMemory, type ClickObserver, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickBody, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, type FormatShortcutOptions, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeyLabels, type KeyLegend, type KeySpec, type KeySpecsFromModsOptions, LONG_PRESS_MS, type LegendStyle, type LogicalMod, type LogicalModSpec, type LongPressEvent, type LongPressSpec, MODIFIER_LABELS, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchGeometry, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type Platform, type Point, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerRecognizer, type PointerRecognizerOptions, type PointerSample, type PointerSampleStylus, type PointerUpEvent, type PressFacts, type PressSample, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RecognizerClock, type RecognizerObserver, type RecognizerSink, type ReleaseFacts, type ReleaseOutcome, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, SHORTCUT_LEADER_SEPARATOR, type ShortcutInput, type ShortcutLeaderStep, type ShortcutParts, TAP_THRESHOLD_PX, type TargetPredicate, type TargetSpec, type TargetSpecForm, UNKNOWN_MIME, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, activatesFocusedControl, bindingSpec, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, detectPlatform, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, formatShortcut, formatShortcutParts, getGestureDescriptor, held, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, key, keyRouteToSpec, keySpecFromCode, keySpecFromKey, keySpecRoute, keySpecsFromMods, keySpecsFromShortcut, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf, unbound };