Duolith docs

0121. on:swipe, and the gesture parts built on it

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-15
  • Decided by: domain E fixer (internal only), after the review of PR #36
  • Amends: 0108

Context

Decision 0108 cut PullToRefresh, swipe row actions, Drawer and DateRangePicker from the kit, because the language had no way to hear a swipe. The review asked for all four as real parts, and for the Pager to page on a swipe. Each needed one thing the language lacked: a quick move across an element, with its direction, heard the same way on the web and on a phone.

Decision

**on:swipe, an event on <view>.** It runs when a finger, or a mouse or pen held down, moves at least 40 px across the element, at least one and a half times as far along one axis as across it, and lifts within 800 ms. The handler receives { direction: "left" | "right" | "up" | "down" }.

  • A swipe down counts only from the top. While what scrolls around the element is scrolled at all, a swipe down is a scroll back up and is not reported. This is what lets PullToRefresh never refresh a feed that is being scrolled back up. On the web every scrolling ancestor and the page are checked; on native the nearest <screen> or <scroll> tells its children how far it is scrolled (a ScrollTop context, from each bindscroll).
  • A swipe is not also a press. On the web the click a mouse swipe ends with is swallowed, wherever it lands; a touch swipe makes none. On native Lynx sends no tap for a moved touch.
  • Where it is heard: on the web, touch events (which still end when the browser scrolls) and pointer events for a mouse or pen, ended on the window so a swipe may end off the element; the element keeps horizontal moves (touch-action: pan-y) and its text is not selected by a mouse swipe. On native, Lynx's bindtouchstart, bindtouchend and bindtouchcancel, joined with the view's press handlers so both hear a touch.
  • Never the only way. The spec says every swipe needs another way to do the same thing, and every kit part that uses one has it: a button, a key, or both.

The parts.

PartThe swipeThe other way
PagerLeft moves on, right backPrevious, Next and the dots
SwipeRowLeft shows the actions, right puts them awayIts More button (aria-expanded), then each action is a button
PullToRefreshDown from the top refreshesIts Refresh button; a spinner and a status say it is refreshing
DrawerLeft on the panel closes itEscape, the scrim, its Close button; it is a modal dialog overlay, so focus moves in, stays and returns
DateRangePickerNone: it is DatePicker's grid choosing a start, then an endEvery key DatePicker has

Alternatives considered

OptionWhy not
An on:refresh event on <scroll>, from overscrollLynx reports bindscrolltoupper only once at the top, not a pull; the browser reports no overscroll at all. A swipe down from the top is the same gesture, heard the same way on both.
A drag that follows the finger, with the offset as motionNeeds a per-frame position the language has no way to hand to a style; the sheet's drag (decision 0034) is built into its overlay kind. A swipe is enough for each part's job, and its result is animated by the part's own motion.
A drawer overlay kindA dialog overlay laid out as a row with the panel at its start does the same, and keeps the overlay kinds as they are.

Consequences

  • spec/language/elements.yaml lists on:swipe on <view>; the grammars and references are generated from it. The adapter gains SwipeEvent and ViewProps.onSwipe.
  • The web runtime ships web/swipe; the native one src/swipe.ts.
  • Right-to-left layouts are not mirrored yet: a Drawer stays on the left and closes on a swipe left, and SwipeRow's actions come from the right. Mirroring them needs the layout direction, which neither runtime reports to a page yet.
  • A real finger's fling, and how VoiceOver and TalkBack read the parts, are checked on a device (native/DEVICE-CHECKLIST.md); the browser tests drive the swipes with real touch events.