Swipe actions on Item system spec¶
{
"scope": "global",
"triggers": {
"public-api": [
"FR1",
"FR2",
"FR3",
"FR9",
"FR10",
"FR11",
"DEC-1",
"DEC-3",
"DEC-4",
"DEC-6",
"DEC-8",
"DEC-10"
],
"accessibility": ["AR1", "AR2", "AR3"],
"behavior": ["FR4", "FR5", "FR6", "FR7", "FR8", "DEC-2", "DEC-5", "DEC-9"]
}
}
{
"paths": [
"packages/core/src/Swipe/**",
"packages/core/src/privateAttributes/pressHeld.stylex.ts",
"packages/core/src/motion/uikit/swipeActions.ts",
"packages/cli/assets/codemods/transforms/next/migrate-item-swipe-actions-to-swipe.mjs",
"packages/cli/assets/codemods/transforms/next/__tests__/migrate-item-swipe-actions-to-swipe.test.mjs",
"packages/core/src/List/ListItem.swipeKey.test.tsx"
]
}
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | Item carries swipe actions for a finger, a pen, and a trackpad's horizontal scroll through one prop, swipe, whose value comes from createSwipe({leading?, trailing?, swipeBehavior?}) (DEC-8). Each side declares the verbs a sideways drag uncovers as SwipeAction[] — label, icon, onActivate, variant, hasRemoval — and Item renders the panel from them (DEC-1). swipeBehavior is reveal (rest open) or commit (fire on release) (DEC-2). The swipe's code lives in the constructor's module, so an app that never imports createSwipe ships none of it (FR10). The capability is Item's, available on any row whose role permits interactive descendants — a listitem, a role-less row — and out of scope where it does not (option, menuitem*, a radio) (DEC-3). No hover reveal and no mouse-drag swipe (DEC-4); a trackpad's horizontal scroll swipes as a finger does (DEC-7). No new DOM: the row's root translates and its panels counter-translate (DEC-5). |
| Behavior | A sideways drag by a finger or a pen, or a trackpad's horizontal scroll, moves the row; a mouse wheel's notches do not. It uncovers the side's panel. Under reveal (default) the row rests open so each action is tappable and a long drag fires the outermost; under commit the row slides out and the outermost fires; nothing rests. After an action fires the row returns, or holds out when the action has hasRemoval — one bit the component cannot infer, independent of the model. The component waits for nothing afterwards. A short release springs back under both. A mouse never starts the drag; a mostly vertical drag stays the scroller's; a pointer anywhere outside a resting row closes it. |
| End-user impact | A person on a phone gets the flick they expect on a mail row or a settings row, with the row's own look. A pen, or a trackpad's horizontal scroll, swipes the row the same way; a mouse drag, a keyboard, or a screen reader meets the row exactly as today. |
| Builder impact | One prop on Item (and so on ListItem), swipe={createSwipe({trailing: [{label: 'Archive', icon: <Icon icon={ArchiveIcon} />, onActivate: archive, hasRemoval: true}]})}; optionally swipeBehavior in the same options. Every field is known before the gesture begins, so the component paints the panel from data. The group around the rows clips in the inline axis — List does it; any other host does it once. The consumer documentation states that a verb reachable only by swipe is unreachable by keyboard. |
| Compatibility/readiness | swipe is absent by default; every row without it keeps its DOM and paint exactly. The released swipeActions and swipeBehavior props and the ItemSwipeAction and ItemSwipeActions types are deprecated in a patch with no runtime warning (DEP-0017). ItemSwipeActionVariant and ItemSwipeBehavior stay supported, and the new API reuses them. The deprecated ones keep working, with the behavior changes the changesets list (a deprecated row gets the new swipe behavior). They are removed in 0.8.0 (CLN-0025); the astryx upgrade codemod that rewrites them to swipe={createSwipe(…)} is an opt-in early migration from the deprecating patch on, and 0.8.0's upgrade runs it again with the removal. |
| Review checks | Reject a hover-revealed panel or a mouse drag that reveals one; swipe actions on a row whose role forbids interactive descendants; a model restricted by host; commit with several entries on a side and no warning; a panel exposed to the tree while closed; any element added to Item for the panels; overflow: hidden on the group where clip is meant; a row exit or enter animation introduced under this record; hasRemoval read as an obligation, a warning, or a timing rule; a second adaptive media query; swipe code in or reachable from Item or ListItem other than DEP-0017's deprecated path in Item (FR10's list), or any of it outside the deprecated path; a second way to configure swipe actions. |
| Governing rules | architecture:interaction-modality INV4, INV6, INV7; spec:AST-002 FR1, FR4, FR15, FR16, DEC-1; architecture:public-component-api INV2, INV3, INV5. |
This table is a review projection; the body below is authoritative.
Intent¶
On a phone, a person flicks a row sideways to get at a verb — archive,
delete, mark unread, select. Astryx rows do not flick. This record adds the gesture to Item, the row primitive, so a ListItem
and a bare Item in a product's own markup swipe the same way. The rule for where it is available is the row's role: a swipe panel's
controls are interactive descendants of the row, so swipe actions exist on
any row whose role permits them — a listitem, a row with no role at all —
and not on one whose role forbids them. That sorts the list row and the
standalone row in, and the option, menu-item and radio rows out, without
naming a component; a row type nobody has written yet sorts itself.
The gesture is an accelerator for a finger, a pen, and a trackpad: it adds a faster path to a verb under a finger, a pen, or a trackpad's horizontal scroll, and changes nothing for a mouse drag, hover, or the keyboard. Each side's verbs are declared as data — a label that names the state the verb reaches, an icon, a handler, how it looks, and whether the row holds out afterwards — so the component knows everything it needs before the finger moves: what to paint, what to fire, and where the row rests when it is done. The row's own root moves and its panels stay put, so no element is added to any row.
Ownership boundary¶
Owns
- The public shape of
Item's swipe actions: theswipeprop,createSwipeand its options,SwipeActionand its fields, the per-side arrays,swipeBehavior, and the opaqueSwipevalue. - Where the swipe's code lives: in the constructor's module, never in
ItemorListItem, except DEP-0017's deprecated path inItem— the released loader, the released row style, the role gate, thecommitwarning, the bridge the loaded layer fills, the key forwarder into that bridge, and the coexistence diagnostic — which serves the deprecated props only and leaves with CLN-0025 in 0.8.0. - The rule for where swipe actions are available: the row's role.
- The two models,
revealandcommit, meaning the same thing wherever swipe actions are available. - The finger and trackpad behavior: rest or fire, the accelerator, where the row rests after an action, one open row at a time, and how a row closes.
- The anatomy the gesture uses: two out-of-flow positions on
Item's existing root, the root's translation and the panels' counter-translation, and the group's inline clip. - The accessibility contract of the gesture itself: what the panel exposes while resting and while closed, and that a mouse drag and hover touch nothing.
Why no existing record can hold it
architecture:interaction-modalityiscurrentand owns the rule the gesture must respect — INV7 "essential actions remain reachable" — but owns no public API. A record carries oneauthorityvalue, so adding unapproved API claims to it would present them as approved (architecture:knowledge-contractsINV1, INV14).Itemhas no component record. This record is the first durable decision aboutItem's public surface;component:Item, when written, inherits these claims rather than re-deciding them. OfItem's seven in-core renderers, six give the row a role that forbids interactive descendants and are out of scope;ListItemand a bareItemin caller markup — which the system's own templates render inside aBottomSheetand on a page — are the rows this record serves: two real consumers, one home, and the prop stays on the primitive (DEC-3).component:Listiscurrentand owns List's geometry; it gains the inline clip and cites this record.spec:AST-002owns admission: the caller owns which verbs earn a gesture and which model fits them, and the component cannot derive either.
Non-goals¶
- What else the row offers. A row's visible controls — a menu or buttons
in
endContent, its own primary — areItem's existing composition and are not governed, paired, or checked here. The consumer documentation states the obligation; the component does not police it. - A hover-revealed action panel on a fine pointer (DEC-4).
- Animating a row's exit or enter. Not settled here: a row the caller
removes after an action unmounts as any row does today. When it is
settled, the likely form is imperative (
handleRef, asSelectorandMultiSelectorexpose open/close) so enter can be animated too.hasRemovalis not it: it says only where the row rests after an action, and a row that holds out and is never removed sits off-screen — the caller's bug, which that eventual API is what makes graceful. - A render prop for a custom panel. Deferred, not foreclosed: a
render*-shaped addition can land when a caller needs something the vocabulary cannot say (DEC-1). - Gesture tuning. Axis-lock distance, commit ratio, fling velocity,
resistance past the panel, and the slides and springs a swipe drives: behavior
constants in source, not public API and not design tokens (the same ruling the
touch press model received for its clocks). A close that a tap or Escape
starts plays the row's spring from rest (FR7,
spec:AST-094FR45). - Vertical swipes, and a swipe whose only
meaning is dismissal (Toast already has that in
useToastGesture). - Public out-of-flow slots on
Item. Deliberately not admitted: the panel positions are internal, rendered fromswipe. A second consumer — an accent bar, a slide-in checkbox, a drag handle — is acomponent:Itemanatomy record with its own admission argument. - Swipe actions on an element that is not an
Item.createSwipeconfiguresItem; attaching its result to any other element is not admitted. - A programmatic open or close. Not admitted: a swipe panel's open state
belongs to the gesture, and the one coordination case met in practice — a
resting row closing when a neighbour's drag starts — is already a pointer
outside the row (FR7). No product has asked, and the row this gesture was modelled on exposes no
such handle. If one ever does,
handleRefis the established pattern to add it with, asSelectorandMultiSelectorexpose open/close/toggle. - Rows whose role forbids interactive descendants. Swipe actions are
available on a row whose role permits interactive descendants, because a
swipe panel's controls are interactive descendants of the row; a
listitemand a role-lessItemqualify, and "it'll just work" there. A row whose role forbids them is out of scope as a consequence:option(inside alistbox),menuitem,menuitemcheckbox,menuitemradio, and a row that is the enlarged target of a native radio. This is a scope boundary, not a per-call or per-model restriction, soswipeBehaviormeans one thing everywhere swipe actions exist. In core today that excludesSelectorOption, the fourDropdownMenurows, andRadioListItem, and includesListItemand every bareItem. - Equivalent internal implementations remain valid when they satisfy this contract. Internal modules, files, function names, algorithms, data structures, storage layouts, manifests, journals, locks, transaction protocols, and CI job/workflow topology belong in architecture or implementation unless callers or interoperating systems intentionally depend on that exact mechanism as a public protocol.
Evidence: in the repository¶
| Where | What it shows |
|---|---|
Item's root: position: relative, borderRadius, paddingInline; no overflow, isolation, or z-index; the focus-within outline is painted on this root; themeProps('item') lands on it |
The root is already a containing block for absolutely positioned children, and transforming it moves its outline and its theme target with it — nothing on it fights a transform. Only the component that owns this element can translate it. |
Item's content: marker, a startContent span, the label element (a span, an anchor in href mode, a <button> in onClick mode), an endContent span — four siblings in every render mode |
Nothing can move four siblings as one unit except a common parent. The root is that parent already. |
ListItem renders <Item as="li"> directly under List's <ul role="list"> |
Any wrapper around the row is a non-li child of <ul>: invalid HTML and a broken "list, N items" announcement. The gesture has to live on Item. |
List's root sets no overflow |
A translated row paints past the list's inline edge unless the group clips. overflow-inline: clip clips without creating a scroll container; hidden would create one and fight the list's vertical scroller. |
useToastGesture drives Toast's slide by writing --_toast-swipe-y onto the root with style.setProperty; Toast's styles consume it in transform |
The in-core way a gesture moves a component without re-rendering it: a custom property on the root, read by CSS. |
The AppShell/Field ruling of 2026-09-04: a z-index adjustment stays local inside an isolation: isolate container |
The panel must paint above the root's background and below its content; isolation: isolate on the root with the panel at z-index: -1 does that without reaching outside the row. |
DropdownMenu.items, MoreMenu.items, DropdownMenuItemData |
Core already declares a verb as data — a label, an icon, a handler, isDisabled, a variant — and data mode "renders through DropdownMenuItem, so the two APIs describe the same thing". SwipeAction is that shape. |
useMenuPress.onActivate(row, release), useTreeFocus.onActivate, Selector and TreeList wiring |
Core's word for "this row's verb fired" when the path is a release, a key, or a pointer and not a click. A commit fires on release with no click at all. |
ProgressBar.variant defaults to 'accent' |
In-core precedent for accent as a variant word and as a default on a filled surface. |
hasSearch, hasCreate, hasPaging, hasHomeEnd vs isLoading, isOpen, isDisabled |
Core's two boolean prefixes: has* declares that a thing has a property; is* names a state it is currently in. Whether the row holds out after an action is a property of the action, so has*. |
Item consumers: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuSubMenu, SelectorOption, RadioListItem, ListItem |
Six of seven in-core renderers give the row a role that forbids interactive descendants (option from Selector's listbox, the three menuitem* roles, and RadioListItem's delegation to a native radio where the input is the option's sole focusable); they are out of scope. ListItem renders role="listitem" under role="list". The system's own templates render a bare Item with no role at all (a BottomSheet snap-point demo, a table-filter page, a hook demo), so the standalone row is a real consumer and sorts in by the same rule. |
Toast/useToastGesture.ts |
A shipped commit-only swipe whose one meaning is dismissal, with constants (SWIPE_DISMISS_RATIO) in source. |
| Real-device feedback on an earlier implementation of this gesture | On an iOS device the swipe required a press-and-hold before it would start, and the row background did not restore until release. Chromium evidence alone did not predict device behavior. |
| The product row this gesture was modelled on | Its panel names the state ("Unread") where a menu would name the sentence ("Mark as unread"). A toggle swipes back; a verb with no single instant (snooze) opens a chooser. |
Cases the contract serves¶
| Case | Served | How |
|---|---|---|
| Mail: archive and delete | Yes | Two entries in trailing, both hasRemoval, Delete variant: 'destructive'. Under reveal the panel rests open with both; a long drag fires the outermost; the row holds out and the caller removes it. |
| One destructive action | Yes | One entry with variant: 'destructive' and, if it removes the row, hasRemoval. Under commit the row slides out and it fires; it holds out or returns by the bit. |
| Reversible toggle (read/unread, pin/flag) | Yes | label names the state the verb reaches ("Unread"); no hasRemoval. Under reveal the row returns wearing it; under commit it slides out, fires, and returns wearing it. |
| Archive — removes the row but is not destructive | Yes | hasRemoval without variant: 'destructive'. The axes are independent: all four combinations occur (DEC-1). |
| Soft delete with Undo — destructive but row stays | Yes | variant: 'destructive' without hasRemoval: the row returns. |
| More than two actions | Yes | N entries on a side, outermost last. Under reveal each is a button. |
| An action that confirms or opens a chooser | Yes | No hasRemoval: the row returns and onActivate opens the dialog; the caller removes the row on confirmation. A verb with no single instant (snooze) commits to opening its chooser. |
| Rows in a virtualized list | Yes | Open state is the row's own; a row that unmounts takes it along. A mostly vertical drag stays the scroller's (FR6). |
Rows that are links (href) |
Yes | The axis lock separates the drag from the tap, and the click the browser synthesizes after a drag is swallowed (FR6). |
role="list" rows |
Yes | ListItem inherits the prop; arbitrary interactive children are valid. |
A bare Item outside a list (a sheet row, a card row) |
Yes | No role, so interactive descendants are permitted; the prop is Item's and the host clips its own group (FR9). |
A row whose role forbids interactive descendants (option, menuitem*, a radio target) |
No | Out of scope by the role rule (Non-goals). Not a model restriction — swipe actions are simply not available there. |
| A panel the vocabulary cannot draw | No | Not in this record. A render* addition is the deferred route (DEC-1). |
| Dismiss-only swipe (Toast) | No | Owned by useToastGesture; a different concept with one meaning per direction. |
Public API and concepts¶
| Concept | Closed values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
Item.swipe |
Swipe |
The row's swipe actions, configured by one createSwipe call. Inherited by ListItem and every host that renders an Item. Item reads the configuration and hands its root to the runtime the value carries; Item holds no swipe code of its own (FR10). The row keys the swipe on its actions' ids (FR11). |
absent | spec:AST-057 |
proposed |
createSwipe |
<const Id extends string>(options: CreateSwipeOptions<Id>) => Swipe<Id> |
Exported from @astryxdesign/core/Swipe and the package root. A plain function, not a hook, pure and cheap: callable at module scope, outside a render, and on the server, and doing no DOM work when imported or called. A caller defines the swipe once at module scope, or in useMemo when a handler needs component state. Its module carries the swipe's runtime (FR10). The swipe carries no built-in text: every name it exposes is a caller's label. |
— | spec:AST-057 |
proposed |
CreateSwipeOptions |
{leading?: readonly SwipeAction<Id>[]; trailing?: readonly SwipeAction<Id>[]; swipeBehavior?: ItemSwipeBehavior} |
The verbs a sideways drag uncovers on each side, outermost last, and what a swipe does on both sides. leading is uncovered by a drag toward the inline end, trailing by one toward the inline start. |
— | spec:AST-057 |
proposed |
Swipe |
opaque | The configured swipe actions. Callers create it only through createSwipe and pass it only to swipe; its contents are not public. Its type, Swipe<Id>, carries its actions' ids. |
— | spec:AST-057 |
proposed |
SwipeAction |
{id: Id; label: string; icon?: ReactNode; onActivate: (event: {id: Id; itemKey: string \| number \| undefined}) => void; isDisabled?: boolean; variant?: ItemSwipeActionVariant; hasRemoval?: boolean} |
One verb. Item renders it as a filled surface in its variant's colour with the icon above the label; label is the button's accessible name under reveal and names the state the verb reaches ("Unread"). id names the verb, and onActivate receives it with the row's itemKey. Every field is known before the gesture begins. |
— | spec:AST-057 |
proposed |
ItemSwipeActionVariant |
'neutral' | 'accent' | 'destructive' |
How the action looks: ordinary, the one you mean, the dangerous one. Not a status set — a verb is not a state. Minted here (DEC-6). | accent |
spec:AST-057 |
proposed |
hasRemoval |
false, true |
After this action activates, the row holds out rather than springing back. Only that: not a promise the caller removes the row, not an animation, not a timing rule. Independent of swipeBehavior and of variant; all combinations occur. |
false |
spec:AST-057 |
proposed |
onActivate |
called on tap of a resting panel, on the full-swipe accelerator, and on a commit release |
Core's word for a verb firing by any path. Not onClick: a commit fires with no click. Fires once the row's content has left its box (FR5). It receives {id, itemKey}: the action's id, and the ListItem's itemKey, undefined on a plain Item. |
— | spec:AST-057 |
proposed |
swipeBehavior (ItemSwipeBehavior) |
'reveal' | 'commit' |
Applies to both sides. reveal: a release opens or closes the row by its speed, then by half the panel's width, and the open row rests with every entry a real button; a full swipe fires the outermost (FR5). commit: a lift past the confirm point slides the row out and fires the outermost entry; nothing rests; the panel is presentational; valid for one entry per side, warns with more. A commit is not a removal: the row springs back unless the entry has hasRemoval. commit means the same on every row that has swipe actions. |
reveal |
spec:AST-057 |
proposed |
| the panels | two out-of-flow positions on Item's root |
Absolutely positioned children of the existing root at the inline start and end, painting above the root's background and below its content; present only when the side has entries. Internal anatomy with a theme target; not public slots. | — | spec:AST-057 |
proposed |
| the drag's travel | a private custom property on the row root | Written by the gesture during a drag. The root's transform reads it; each panel's transform reads its negation, so the row moves and the panel appears fixed in the space the row vacates. |
0px |
spec:AST-057 |
proposed |
| the group's clip | overflow-inline: clip on the element containing the rows |
A moving row paints past its group's inline edge unless the group clips. List sets it; a host that renders Items outside List sets it once. Item cannot clip itself: it is the thing moving. |
— | component:List / the host |
proposed |
| open state | closed, resting open | The row's own. A pointer landing anywhere outside a resting row closes it, which is also how a drag on a neighbour closes it; no group state exists. | closed | spec:AST-057 |
proposed |
| the modality split | internal | A mouse drag never starts the swipe; a finger's or a pen's pointer event or a horizontal wheel gesture does, read from the input event, not a prop or a media query (architecture:interaction-modality INV6). |
— | spec:AST-057 |
proposed |
Not public: axis-lock distance, commit ratio, fling velocity, durations, resistance, panel widths, the custom property's name. They are behavior constants.
Requirements¶
Behavioral contract¶
| ID | Invariant | Basis | Verification state |
|---|---|---|---|
| FR1 | Item MUST take its swipe actions as one prop, swipe, whose value is the Swipe<Id> that createSwipe<const Id extends string>(options) returns. options is {leading?: readonly SwipeAction<Id>[]; trailing?: readonly SwipeAction<Id>[]; swipeBehavior?: ItemSwipeBehavior}. SwipeAction<Id> is {id: Id, label: string, icon?: ReactNode, onActivate: (event: {id: Id; itemKey: string \| number \| undefined}) => void, isDisabled?, variant?: ItemSwipeActionVariant, hasRemoval?: boolean}, with variant defaulting to accent. createSwipe MUST infer the ids as literals, so an id the swipe lacks, a handler for fewer ids, or an action with no id fails to compile. onActivate MUST receive the action's id and the row's itemKey: the ListItem's, or undefined on a plain Item. An entry MUST NOT carry a node the component renders as the control. Swipe MUST be opaque, made only by createSwipe. ListItem MUST pass swipe to its Item with only its itemKey added. While the value and the key stay the same, it MUST hand the row the same value. The deprecated swipeActions and swipeBehavior props and the ItemSwipeAction and ItemSwipeActions types follow DEP-0017. |
DEC-1, DEC-8, DEC-10; DropdownMenu.items data mode |
Proposed |
| FR2 | Item MUST render each side's panel from its entries into an out-of-flow position on its existing root and MUST add no element to the row for it. The gesture MUST drive the row's travel by writing a custom property on the root; the root's transform MUST read it and each panel's transform its negation. |
DEC-5; useToastGesture |
Proposed; real-Chromium evidence required |
| FR3 | swipeBehavior MUST be one closed union, ItemSwipeBehavior, with the values reveal and commit, default reveal, applying to both sides. commit with more than one entry on a side MUST warn in development, because the other entries have no touch path. |
DEC-2 | Proposed |
| FR4 | A sideways drag by a finger or a pen, or a trackpad's horizontal scroll, MUST move the row and uncover the side's panel, showing each entry's label and icon as a filled surface in its variant's colour; while a full swipe is confirmed (FR5) the outermost entry alone MUST cover the uncovered space; the panel MUST NOT be visible at rest, by any pixel. A mouse wheel's notches MUST NOT move the row. |
Real-browser finding: a zero-width panel still paints its padding | Proposed; real-Chromium evidence required |
| FR5 | Under reveal, a release goes by its speed first: at the release speed or faster it opens the row while the row is opening and closes it while it is closing; a slower one opens the row past half the panel's width and closes it short of that. Speed alone MUST NOT fire an entry, and a flick never reaches the confirm point; on a side with two or more entries a full swipe confirms only as DEC-9 says. Dragged past the confirm point, the row MUST run ahead toward its far edge with the outermost entry covering its place while the finger stays down; a lift still past the confirm point MUST fire the outermost entry and no other, at any speed; a swipe that confirmed and came back short of the confirm point MUST close the row and fire nothing; a disabled outermost entry MUST NOT confirm. Under commit, only a lift past the confirm point MUST slide the row out and fire the outermost entry; every other release closes; nothing MUST rest. After any entry fires, under either model, the row MUST return unless the entry has hasRemoval, in which case it MUST hold out at the edge it travelled toward. When a swipe fired the entry, the return is gesture-driven and springs from the release velocity; when a tap on the entry fired it, the return plays the row's spring from rest, since a swipe row's main interaction is a gesture (spec:AST-094 FR45). That bit is the only thing an entry declares about the row; the component MUST NOT wait on, observe, or act on what the caller does next, and MUST NOT warn if a held-out row is never removed. A release short of the threshold MUST spring back under both models. Under reduced motion the slide out, the spring back, and the hold-out follow design:reduced-motion: the row reaches its resting place with no travel or spring and cross-fades (DR2) when a finger started the swipe, or, when a pen or a trackpad did, cross-fades on a coarse primary pointer (DR2) and arrives at once otherwise (DR3). onActivate MUST fire once the row's content has left its box, and may return a Promise. |
DEC-1, DEC-2; UIKit performsFirstActionWithFullSwipe |
Proposed; real-device evidence required |
| FR6 | The drag MUST decide its axis once, early, and a mostly vertical drag MUST stay the scroller's. A mouse MUST NOT start the drag. The click the browser synthesizes after a drag MUST NOT fire the row's primary action. | Press-model ORD1 | Proposed; real-device evidence required |
| FR7 | An open row (resting open, or settling open from the release that opened it) MUST close on a pointer landing anywhere outside it, on a touch tap on its own content, on a scroll of anything that holds it while focus is outside its open panel, on Escape with focus inside it, on firing an entry, and on unmount. That tap MUST activate nothing and paint no press, an exception to the cell press profile of spec:AST-094 FR11. Under a coarse primary pointer, a pen's or a mouse's press on the open row's content paints no press either; it still reaches the row. Because a drag on a neighbour is a pointer outside it, at most one row is open at a time without any shared state. A swipe row's main interaction is a gesture, so every close plays the row's spring (spec:AST-094 FR45): a close that a tap, a pointer outside, a scroll, Escape, a fired entry's tap or the program starts plays the same settle as a swipe close, from rest, and a close a swipe drives starts from the release velocity. |
DEC-3; SwiftUI swipeActionsContainer() for the outcome |
Proposed |
| FR8 | Directions MUST be logical: trailing is uncovered by a drag toward the inline start and sits at the inline end; leading the reverse; so the finger, the uncovered edge, and the panel agree under RTL. |
architecture:public-component-api INV2 (logical direction) |
Proposed |
| FR9 | The element containing swipe-capable rows MUST clip in the inline axis with overflow-inline: clip, never hidden. List MUST set it; Item's consumer documentation MUST state the obligation for any other host. |
DEC-5; List root styles |
Proposed |
| FR10 | The createSwipe module MUST import every module the swipe runs on — the shared gesture core, the animator, the panels' rendering, and the row's gesture code — statically. Item and ListItem MUST import none of these swipe modules and MUST NOT load them with import(); the touch modules Item uses for other jobs, such as press feedback, are outside this rule. DEP-0017 makes one exception, Item's deprecated path, which serves the deprecated props only and leaves with CLN-0025 in 0.8.0: the released loader, which loads the swipe code with import() the first time a row has swipeActions; the released row style Item applies from that row's first render; the released role gate and commit warning; the bridge the loaded layer fills and the key forwarder from the row's root into it; and the development-only coexistence diagnostic when swipe and a deprecated prop are both given. An app that never imports createSwipe therefore loads no swipe code unless a row uses the deprecated props, and a row given swipe is swipeable at its first paint. Importing or calling createSwipe MUST do no DOM work. |
DEC-8; architecture:public-component-api INV19; architecture:react-component-runtime INV13 |
Proposed |
| FR11 | createSwipe is pure and cheap. A caller defines the swipe once at module scope, or in useMemo when a handler needs component state, and MAY call it inline in a render. A row MUST key its swipe on its actions' ids. A new Swipe value with the same ids MUST NOT close an open row, restart a settle, or attach the gesture again. The row reads the latest value's entries and handlers, so a handler sees the caller's latest state, and a changed label repaints the panel. A new value with other ids MUST close an open row. |
DEC-8, DEC-10 | Proposed |
Accessibility contract¶
- AR1 — The panel is real while resting and absent while closed. Under
reveal, while the row rests open each entry MUST be a real, focusable<button>named bylabel, so a touch screen reader that lands on it can activate it; while closed the panel MUST be out of the accessibility tree and the tab order. Undercommitthe panel MUST be presentational (aria-hidden) at all times, because nothing in it is ever tappable. - AR2 — A mouse drag never swipes a row. A mouse drag and hover MUST NOT
uncover the panel, and on a pointer that can hover a closed row's
swipeMUST have no effect on the tab order, the accessible tree, or the row's paint. A pen's drag (spec:AST-094FR43) or a trackpad's horizontal scroll MAY uncover the panel (DEC-7), and a row it leaves resting open follows AR1; a mouse wheel's notches MUST NOT. - AR3 — The row's primary stays one tab stop.
swipeMUST NOT change the primary element's role or name, MUST NOT change its activation while the row is closed, and MUST add no stop while closed. While the row is open, a touch tap on its content closes it (FR7); keyboard activation is unchanged. - Stated in documentation, not enforced: a swipe is a touch accelerator,
so a verb reachable only by swipe is unreachable by keyboard and by a mouse
drag.
The consumer documentation of
swipeMUST say so and MUST show the verb also reachable through the row's own content. The component does not inspect what else the row offers.
Platform support¶
- Supported feature/engine floor: every supported renderer and browser.
A finger's or a pen's swipe is read from its pointer event; a
trackpad's from a horizontal
wheelgesture, which has no pointer type. A mouse wheel's notches never swipe (spec:AST-094FR43), and a mouse drag never swipes. - Unsupported behavior: a device with no touch screen, no pen, and no trackpad gets no swipe, and a mouse drag never swipes; nothing else changes.
- Browser evidence: FR2 and FR4–FR9 are paint and gesture claims. jsdom has neither; real-Chromium evidence with dispatched touch is required, and FR5/FR6 additionally need a physical touch device, because Chromium evidence for this gesture has not predicted device behavior.
Current-state impact¶
Itemgainsswipe, and Core exportscreateSwipewith the typesSwipeAction,CreateSwipeOptions, andSwipe, which reuseItemSwipeActionVariantandItemSwipeBehavior;Itemgains two out-of-flow panel positions on its root with a theme target, and the root and panel transforms. No new element, no gesture on any row that does not ask for it.component:Item, when written, inherits these claims.ListItempassesswipeto itsItem, and the releasedswipeActionsandswipeBehavior, deprecated by DEP-0017, through the same passthrough.- The drag uses FR2's single travel property, and the release settles on the compositor.
Swipe/SwipeActionsLayer.tsxrenders a row's two panels into the row's root and runs the row's gesture.createSwipeimports it, andItemloads it withimport()only for the deprecated props (FR10). No existing module can hold it:Itemstatically imports onlyswipeHost.tsand its styles, which hold no gesture, animation or rendering code, anduseSwipeAction.tsis the gesture alone.- Implementation gap (FR10):
Itemloads the deprecated swipe layer throughimport()for the deprecatedswipeActionsandswipeBehaviorprops; the gap closes when those props are removed. architecture:react-component-runtimeINV13 gains the constructor route for an opt-in touch behavior with a large resource cost:ItemandListItemimport none of the swipe modules, and its failure signal names DEP-0017's deprecated path inItem— the released loader, the released row style, the role gate, thecommitwarning, the bridge the loaded layer fills, the key forwarder into that bridge, and the coexistence diagnostic — as the only exception, on the deprecated path only, until CLN-0025.architecture:public-component-apiINV19 namesswipe={createSwipe(…)}as its plug-in example (DEC-8).component:Listgains the inline clip onList's root, citing this record.architecture:interaction-modalitygainsspec:AST-057in its deciding specs; no invariant changes.contributing:api-conventionsgains the rule this record relies on: a gesture is an accelerator and never a component's only path to its own behavior.spec:AST-058takes nodes where this record takes objects, on the shared principle in DEC-1: the picker places its actions;Itemrenders its panel.- No shipped public API changes on this record's own merge.
- While this record is
draftitsreview-applicability:v1block routes nothing: global routing loadscurrentclaims only (architecture:knowledge-contractsINV20).
Verification¶
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1, FR3 | Item and ListItem prop-surface suites plus exported-type checks |
One, two, and four entries per side; every variant × hasRemoval combination; commit with two entries on a side; Swipe built by hand |
A field with a node the row renders as the control, a silent multi-entry commit, a Swipe a caller can build without createSwipe, or ListItem changing the prop beyond adding its itemKey fails. |
| FR1 ids and keys | Type tests in the createSwipe suite, compiled by the repository's TypeScript in strict mode; Item and ListItem suites |
An id the swipe lacks; a handler typed for fewer ids; an action with no id; one definition at module scope on rows with a number key and a string key; a ListItem rendered again with the same value and key, then with another key |
Any of the three type cases that compiles, a handler that gets no id or another row's key, or a ListItem that keys the same value and key again fails. |
| FR2 | Item DOM snapshot suite plus real-Chromium evidence |
No swipe actions; one side; both sides; each render mode (onClick, href, delegation, parent role); mid-drag |
A new element in any row, a changed DOM on an existing row, a panel that moves with the row, or a panel painted under the root's background or over the content fails. |
| FR4–FR6, FR8 | Real-Chromium dispatched-touch evidence plus physical-device check; RTL via the direction provider | Rest; a slow release short of and past half the panel; a fast release opening and closing from a short drag; a confirmed full swipe lifted, backed out, and on a disabled outermost entry; a flick under commit; both models; both sides; hasRemoval and plain entries under each; vertical drag; mouse drag; RTL; a trackpad's horizontal scroll and a mouse's horizontal wheel; a mouse drag, which must not swipe; a pen drag |
A resting sliver, a fire from speed alone, a backed-out swipe that fires or rests open, a disabled outermost entry that confirms, a confirmed swipe whose outermost entry does not cover the row, onActivate before the row's content has left its box, a rest under commit, the wrong entry fired, a plain entry that holds out, a hasRemoval entry that springs back, a warning on a held-out row, or a mirrored panel fails. |
| FR7 | Item suite with two rows under one parent; the press controller's suite for a pen's and a mouse's press on a held row |
Open one, drag the other; outside tap; a touch tap on the open row's content; a tap while the row settles open; a scroll of the list and of the page with focus outside the open panel and with focus inside it; Escape; entry fired; unmount; a pen's or a mouse's press on the open row's content under a coarse primary pointer | Two rows open, a row that stays open after any closing event, a tap on an open row's content that activates the row or paints a press, a pen's or a mouse's press there that paints a press, a scroll that closes the row while focus is inside its open panel, a swipe close that starts from rest instead of the release velocity, or a tap, Escape or program close on a curve instead of the row's settle spring, fails. |
| FR9 | List style assertion plus real-Chromium evidence of a row dragged past the edge |
A row at the list's inline edge mid-drag; the list scrolled vertically | A horizontal scrollbar, the row painting past the list, or hidden where clip is specified fails. |
| FR10 | The touch-support bundle guard (main's checks plus one entry for createSwipe) and a module-attribution check: each public import built with the pull-request size report's esbuild options (minified ESM, code splitting, metafile), with every byte of the JavaScript the import loads eagerly — its entry output and the chunks it reaches by static import — attributed to its source module from the metafile's per-module bytes in output; the check lists those modules and their gzipped share, base against head |
Item alone; ListItem alone; Item with createSwipe; every public import that renders an Item row; a server import of createSwipe |
Any bytes in the eager output of Item alone or ListItem alone attributed to a swipe module — the gesture core, the animator, the panels' rendering, or the row's gesture code; a swipe module imported by Item or ListItem; an import() reachable from Item other than DEP-0017's released loader; swipe code in Item other than DEP-0017's deprecated path (FR10's list: the loader, the row style, the role gate, the commit warning, the bridge, the key forwarder, and the coexistence diagnostic) and the swipe handoff, which reads the value and hands the row's root to the runtime it carries, or any of the deprecated path outside the deprecated props; or DOM work on importing or calling createSwipe fails. Growth of Item alone or ListItem alone attributed to Item's own modules, from the deprecated path and the handoff, is reported and fails nothing; the released loader's import() target is a separate chunk outside the eager output. |
| FR11 | Item suite re-rendering with a new Swipe value |
Closed, resting open, and settling; the same ids with the same or a changed label; other ids; a changed handler | A new value with the same ids that closes the row, restarts the settle, or attaches the gesture again, a stale handler, a panel that keeps an old label, or an open row that stays open under other ids fails. |
| AR1–AR3 | Accessible-tree and tab-order assertions, open and closed, both models; hovering-pointer evidence | Closed; resting open; commit mid-drag; touch screen-reader cursor on an entry; keyboard activation of the primary while the row is open; hover and Tab on a fine pointer; a trackpad horizontal scroll that opens a row; a mouse drag |
A panel exposed while closed, a commit panel in the tree, an entry without a name while resting, a changed primary, a panel a mouse drag or hover uncovers, or any effect on a closed row under a hovering pointer fails. |
| Documentation | Consumer-doc check on swipe |
The prop's documentation | A doc that does not state the keyboard consequence or the group clip fails. |
Known verification gap: none of the suites above exist on main, and no
component implements the contract. This record is draft, does not govern
review, and names no implementation.
Decision log¶
Every decision below records the owner's direction; the record is draft
until approved_by is set.
DEC-1 — Swipe actions are declared as data¶
Reference: spec:AST-057/DEC-1
Decider: cixzhang, 2026-10-02
createSwipe's leading and trailing are SwipeAction[]: {id?, label,
icon?, onActivate, isDisabled?, variant?, hasRemoval?}. Item renders each entry —
under reveal as a real button, under commit as a presentational block —
and paints the panel during the drag from the data.
An object is needed where the component renders the thing; a node works where it only places it (spec:AST-058 DEC-1 draws the same line from the other side, and its picker-row actions are nodes because the picker only places them in a cell). Item paints and animates the panel, so every field is known before the gesture begins; a caller's own node could do neither without registering through a context, which splits the API into nodes that get the behavior and nodes that silently do not. Core already declares a verb as data
in DropdownMenu.items and MoreMenu.items, and two independent vibe-test recall probes — one for this record, one for
spec:AST-058 — found every builder reaching for exactly this array with no
prop names given, and none reaching for child components or a render prop.
The vocabulary: onActivate is core's word for a row's verb firing by a
path that is not a click (useMenuPress, useTreeFocus, Selector,
TreeList), and a commit fires on release with no click at all. variant is
'neutral' | 'accent' | 'destructive', with accent the default (DEC-6). label names the state the verb reaches ("Unread"), because the panel
shares one row width with the title it uncovers and the gesture already
supplies the verb. hasRemoval is one bit the component cannot infer: after
the action fires, does the row spring back or hold out? It is independent of
swipeBehavior — a commit is not a removal, and a tap on a resting "Archive"
is — and of variant, since Archive leaves without being destructive and a
soft Delete with Undo is destructive while the row stays. It takes has*
because it declares a property of the action, not a state the row is in. It
is nothing more than the resting position: not a promise the caller removes
the row, so no obligation and no warning; not an animation, so nothing
collapses or fades; not a timing rule, so onActivate still fires at
activation.
Composition is deferred, not lost: a render*-shaped addition for a panel
the vocabulary cannot draw can land when a caller needs it. How a held-out
row leaves, and how a kept row returns, is not this record's (Non-goals).
Rejected: nodes per side with a shipped SwipeAction component — it
needed context registration for commit, and left any caller-supplied node
silently without it. Rejected: one action per side with onAction and a four-tone tone — a
second verb vocabulary. Rejected: a wider hasRemoval that promised the caller would remove the row, owned the exit animation, and fired onActivate after it — it made a confirm-first delete an exception and tied the resting bit to
the unsettled exit animation. Rejected: isCommitExit — the bit applies under reveal too, so naming it after commit is wrong.
DEC-2 — Rest is the default; commit is a caller choice for one verb¶
Reference: spec:AST-057/DEC-2
Decider: cixzhang, 2026-10-02
swipeBehavior: 'reveal' | 'commit', default reveal. Under reveal the
row rests open and a long drag fires the outermost entry; under commit the row slides out and the outermost entry fires. The slide-out is the gesture's own confirmation; where the row rests afterwards is the entry's hasRemoval, not the model's — a commit is not a removal — and the component waits for nothing after firing. commit means the same on every row that has swipe actions; no host narrows it.
Where a platform offers both, the full swipe is defined over the resting
list — UIKit's flag is
performsFirstActionWithFullSwipe,
indexing the resting actions — so resting is the model that holds several
verbs and commit is the one that holds exactly one; the count and the rest
state are one question, which is why commit with several entries on a side
warns. A resting panel also gives a touch user something to see before a
destructive verb fires, which is why it is the default. Commit is kept because both models are wanted, and it is what the row this
gesture was modelled on uses for its one-verb rows.
Rejected: commit-only as the sole model — it cannot grow into resting
without a default change. Rejected: a boolean hasFullSwipe — under reveal the full swipe is already on and under commit it is the whole behavior, so a boolean gates the wrong axis. Rejected: a hasCommitAnimation flag — the slide-out is how a commit confirms and commit already decides it; a second switch for one thing is the boolean-plus-handler duplication rejected on hasCreate. Rejected: requiring the row to stay out after every commit (#6821) — a committed "Mark read" row is still there.
DEC-3 — The capability is Item's; where it is available follows the row's role¶
Reference: spec:AST-057/DEC-3
Decider: cixzhang, 2026-10-03
Item owns swipe. ListItem inherits it
through its existing passthrough and declares nothing of its own; a bare
Item in a product's own markup gets them the same way. Where swipe actions are available follows one rule: the row's role must
permit interactive descendants, because a swipe panel's controls are
interactive descendants of the row. A listitem and a role-less Item
qualify; option, the menuitem* roles, and a row that is the enlarged
target of a native radio do not, and are out of scope — not narrowed to one
model, not warned about per call, simply not served. A rule about the role
rather than a list of components means a row type nobody has written yet
sorts itself, and a scope boundary keeps swipeBehavior meaning one thing
everywhere it exists. Open state is the row's own: a pointer landing anywhere outside a
resting row closes it, and a drag on a neighbour is such a pointer, so one
row rests open at a time with no group state and no coordinating hook.
Only the component that owns the root can translate it, and a wrapper around
the row is ruled out by the HTML list content model — it would sit between
<ul> and <li> — so the gesture has to live where the root lives. Of Item's seven in-core renderers, six give the row a role that forbids
interactive descendants; the seventh is ListItem, and the system's own templates render a bare Item
outside any list, so the capability has two consumers rather than one, which is why it stays
on the primitive: list rows and standalone rows share one home, and the
excluded rows are excluded by their role, not by where the prop lives.
Rejected: moving the prop to ListItem now that six of Item's seven
in-core renderers are out of scope — it would put the prop only where it is
most used and take it from the standalone row, a real consumer the system's
own templates render. Rejected: deciding scope per model — permitting commit where reveal is
forbidden — because it couples a design choice (what the row does when
swiped) to a structural constraint (what the host may contain), so the same
prop value behaves differently by host. Rejected: a behavior hook that hosts
compose — one-open-at-a-time was its reason to exist as group state, and
outside-close gives the same outcome with nothing shared. Rejected: an
imperative or controlled open — nothing has asked, and the gesture already
owns the one coordination case.
DEC-4 — No hover reveal¶
Reference: spec:AST-057/DEC-4
Decider: cixzhang, 2026-10-02
A mouse drag and hover do nothing with swipe; horizontal wheel
input, a trackpad's scroll or a mouse's horizontal wheel, and a pen are the
non-finger inputs that swipe a row (DEC-7); what a row offers
a mouse or a keyboard is the row's own content, which this record does not
govern.
Rejected: a reveal axis that rendered the same actions as hover-revealed buttons on a fine pointer — a second surface for verbs the row's content can already carry. React Aria's iOS List example takes that route (a panel button in the tree, revealed on focus) and is the alternative this decision sets aside.
DEC-5 — The root translates and the panels counter-translate; no element is added¶
Reference: spec:AST-057/DEC-5
Decider: cixzhang, 2026-10-02
Item renders each side's panel as an absolutely positioned child of its
existing root, at the inline start or end, above the root's background and
below the content. The drag writes its travel as a custom property on the
root — the way useToastGesture writes --_toast-swipe-y — the root's
transform reads it, and each panel's transform reads its negation, so the
row moves and the panel appears fixed in the space the row vacates. Both are
compositor transforms and the cancellation is exact. No element is added to
any row. The group clips with overflow-inline: clip. The positions are
internal: no public slot is admitted for them.
Layering and translation are different problems and neither needs a new
element. Layering is absolute positioning inside a containing block the root
already provides, with isolation: isolate on the root so a negative
z-index on the panel stays local (the 2026-09-04 isolation ruling).
Translation is the root's own transform: the content is four siblings in
every render mode, and the root is already their common parent. The root's
own styles survive the transform — no overflow or contain on it, the
focus-within outline and the theme target ride it. The clip cannot be the
row's, because the row is the thing moving, so it is the group's; hidden
would create a scroll container and fight the list's vertical scroller.
Rejected: a wrapper element inside Item, conditional or not — a second
row shape for CSS and tests to straddle, for a problem the root's transform
already solves. Rejected: a clipping container around a new inner row — an element on
every swiping row. Rejected: panels as siblings at
the list level, positioned at each row's offset — a position-sync loop
against resize, reflow and virtualized mounts. Rejected: animating
padding-inline-start on the root — layout on every frame under a finger
instead of a compositor transform. Rejected: public beforeContent /
afterContent slots — nothing in this record needs them, and general
anatomy takes its own admission.
DEC-6 — The verb variant set is neutral | accent | destructive, minted knowingly¶
Reference: spec:AST-057/DEC-6
Decider: cixzhang, 2026-10-02
ItemSwipeActionVariant is 'neutral' | 'accent' | 'destructive': three
flavours of verb — ordinary, the one you mean, the dangerous one — and
accent is the default on a swipe panel, because the panel is a filled
surface that has to be some colour and ProgressBar already defaults a
filled surface to accent.
This is minted vocabulary, not reuse, and it was taken knowing that:
accent appears on no other variant enum in core except ProgressBar's
default, and Step.status carries it as a status. The shared status set —
success | warning | error across seven components — names states, and a
verb is not a state: "Archive" is not a success and "Delete" is not an
error. spec:AST-058 takes the same set for picker-row actions with
neutral as its default, so the vocabulary is one across the two surfaces
where a verb gets a colour.
Rejected: the status set — it would make a verb claim a state. Rejected: a tone: 'accent' | 'success' | 'warning' | 'error' — a status
set with one decorative member. Rejected: Badge's variant map — it carries
decorative colours (blue, cyan, …) that a verb slot must not admit.
Rejected: the menu row's two-value 'default' | 'destructive' — it has no
word for the one action a panel exists to offer.
DEC-7 — A trackpad swipes a row; a mouse drag does not¶
Reference: spec:AST-057/DEC-7
Decider: cixzhang, 2026-10-26
A trackpad's two-finger horizontal scroll is the same motion as a finger's
swipe and takes nothing else from the page, so it reveals and fires row
actions as a finger does (spec:AST-094 FR43). A mouse drag would take the
browser's text selection and native drag, so a mouse drag never swipes a row. A mouse's horizontal wheel sends the
same events as a trackpad and swipes the same way.
Rejected: keeping swipe actions touch-only.
Amended (consistency with spec:AST-094 FR43): a trackpad's horizontal scroll
MAY uncover the panel; a mouse wheel's notches don't.
DEC-8 — Swipe actions are configured through a constructor¶
Reference: spec:AST-057/DEC-8
Decider: cixzhang, 2026-11-01
Item takes one prop, swipe, whose value comes from
createSwipe(options). The options keep DEC-1's entries and DEC-2's
two models; one swipeBehavior governs both sides. All of the swipe's code —
the shared gesture core, the animator, the panels' rendering, and the row's
gesture code — lives in the constructor's module, which imports it
statically. Item carries none of it, so an app pays for the swipe only
when it imports createSwipe, the bundler drops it everywhere else,
and nothing loads at run time. This is the plug-in route
architecture:public-component-api INV19 gives a feature with a large
resource cost, and the shape CodeBlock already takes with
language={createCodeLanguage(…)}.
Rejected: loading the swipe code with import() the first time a row has
swipe actions, which makes the gesture live only after the row paints and
needs an exception to architecture:react-component-runtime INV13's static
imports. Rejected: keeping the data on Item's props with a static import,
which puts the gesture core in every import that renders a row.
Deprecation and cleanup descriptions¶
Consumer migration instructions belong in consumer docs and release notes.
DEP-0017 — Deprecate swipeActions and swipeBehavior¶
| Field | Value |
|---|---|
| id | DEP-0017 |
| cleanup | CLN-0025 |
| package | @astryxdesign/core |
| surface | The swipeActions and swipeBehavior props on Item and ListItem, and the types ItemSwipeAction and ItemSwipeActions. ItemSwipeActionVariant and ItemSwipeBehavior are kept: the new API reuses them |
| old contract | swipeActions: {leading?, trailing?} with ItemSwipeAction[] per side and swipeBehavior: 'reveal' \| 'commit', with FR2–FR9 and AR1–AR3's behavior; Item loads its swipe layer with import() the first time a row has swipe actions, so the gesture goes live a moment after the row paints |
| replacement | swipe={createSwipe({leading, trailing, swipeBehavior})} (FR1), with an id on each action. ItemSwipeAction maps to SwipeAction, whose id is required and whose onActivate receives {id, itemKey}; ItemSwipeActions maps to CreateSwipeOptions |
| direct authority | spec:AST-057 DEC-8. Owner: cixzhang |
| decider | cixzhang, 2026-11-10 (22:23 PT). The owner chose "Yes, new behavior" on the decision "Should rows using the deprecated swipe props get the new swipe behavior?", whose text states: "Your answer also confirms the deprecation of these six symbols: swipeActions, swipeBehavior, ItemSwipeAction, ItemSwipeActions, ItemSwipeActionVariant, ItemSwipeBehavior." This row's surface keeps ItemSwipeActionVariant and ItemSwipeBehavior because the new API reuses them. |
| warning | Static @deprecated metadata on the two props and the two types; consumer docs and the release notes name DEP-0017 and the replacement. No runtime warning (spec:AST-017 FR29, FR29a). When swipe and either deprecated prop are both given, swipe wins and the deprecated props are ignored; a development-only diagnostic names the ignored props (spec:AST-017 FR29's coexistence case) |
| compatibility | The deprecated props keep working, with the behavior changes the changesets list; owner confirmed 2026-11-10: deprecated rows take the new behavior (cixzhang). They run through Item's deprecated path: the released loader, which loads the swipe code with import() the first time a row has swipeActions; the released row style, which Item applies from that row's first render; the released role gate and commit warning; the bridge the loaded layer fills and the key forwarder from the row's root into it; and the development-only coexistence diagnostic this record adds for a row given swipe beside a deprecated prop. That path is the only swipe code in Item and FR10's only exception, it runs on the deprecated path only, the bundle guard names every part of it, and it leaves with CLN-0025 in 0.8.0 |
| migration | Mechanical. swipeActions={X} becomes swipe={createSwipe(X)}; with swipeBehavior={B} beside it, swipe={createSwipe({...X, swipeBehavior: B})}, and an inline object literal is merged in place. Each action needs an id; an entry with none takes one from its side and place, such as 'trailing-0'. A handler that takes nothing stays valid. The panel, the gesture, and every handler behave as before; the one observable difference is that the gesture is live at the row's first paint |
| codemod | An astryx upgrade codemod staged in packages/cli/assets/codemods/transforms/next/, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates the props. It is usable from that release as an opt-in early migration: a caller who runs astryx upgrade explicitly gets the rewrite before the removal, and a caller who does not keeps the deprecated props working until 0.8.0, whose upgrade runs the same rewrite with CLN-0025's removal. It rewrites static swipeActions and swipeBehavior on Item and ListItem where the value is an object literal whose entries are object literals. Each entry with no id takes one from its side and place ('trailing-0', 'trailing-1', and so on), which is stable and readable, so the output compiles. A handler that takes nothing stays valid. It adds the createSwipe import and removes a swipeBehavior="reveal" it would merge as the default. It leaves a site unchanged and reports it where it cannot see every entry: a name, a property, a computed value, a spread, or an entry that is not an object literal. It also reports JSX spreads that may carry the deprecated props (spec:AST-017 FR29c, FR29d). It leaves the ItemSwipe* types as they are |
| downstream | In the deprecating release, Core's docs, stories, templates, and examples teach only swipe (spec:AST-017 FR29b) |
| transition | no prior transition |
| state | proposed |
| target plan | CLN-0025 in 0.8.0, the next minor release |
CLN-0025 — Remove swipeActions and swipeBehavior¶
| Field | Value |
|---|---|
| id | CLN-0025 |
| lifecycle | DEP-0017 |
| delta | swipeActions, swipeBehavior, ItemSwipeAction, and ItemSwipeActions are removed from Item and ListItem, with Item's deprecated path (DEP-0017's compatibility list: the loader, the row style, the role gate, the commit warning, the bridge, the key forwarder, and the coexistence diagnostic); FR10 then holds with no exception |
| replacement | swipe={createSwipe(…)} (FR1) |
| codemod | 0.8.0's astryx upgrade runs DEP-0017's rewrite, the same codemod callers could already run early, over any remaining site and reports what it cannot prove |
| rollback | Restore the props, the types, and the loader from the final-patch baseline |
| state | pending — lands in 0.8.0, a declared minor, with its [breaking] Changeset |
DEC-9 — A flick reveals; only a deliberate drag fires¶
Reference: spec:AST-057/DEC-9
Decider: cixzhang, 2026-11-10
A flick never fires an entry. A short, fast swipe settles the row open at the revealed actions, as FR5's speed rule says; reaching the confirm point takes a deliberate drag, so a release whose travel came from the flick's speed rather than the finger's own distance does not confirm. On a side with two or more entries, a full swipe confirms only from a drag that starts on the outermost entry's revealed panel, or that reaches the confirm point from a resting open row; a swipe that starts on the row's content and flicks past the confirm point settles open instead. While the row is open or a full swipe is confirmed, each uncovered pixel shows the entry that owns it, so no other entry's colour shows behind or between entries. Firing an entry paints no intermediate frame: the panel and the row never flicker between the swipe and the entry's result.
The owner: "a small flick should at least stop around showing just the options then a longer more deliberate movement for performing the default action … if there are two options we avoid flick to activate and only active the swipe action if you deliberately start on the delete and swipe or flick". On the Delete action: "the flickeringb of the delete action is absolutely not acceptable".
Rejected: a velocity threshold that fires the outermost entry (a quick flick deletes by accident).
DEC-10 — Each action has an id, and its handler receives the id and the row's key¶
Reference: spec:AST-057/DEC-10
Decider: cixzhang, 2026-11-10
Each SwipeAction has a required id. createSwipe infers the ids as
literals, and the Swipe it returns carries them in its type. onActivate
receives the action's id and the row's itemKey: the itemKey of the
ListItem it fired on, or undefined on a plain Item. So one definition
serves every row. A caller defines it once at module scope, or in useMemo
when a handler needs component state. A row keys its swipe on the ids. A new
value with the same ids keeps the row as it is; one with other ids closes an
open row. The variant and behavior types keep their released names,
ItemSwipeActionVariant and ItemSwipeBehavior.
The owner: "Okay per action and allow it to be memoized somehow so we dont need to recreate createSwipe", and "the rowSwipe type should carry the ids of the swipe actions for onSwipeAction".
Rejected: a row-level onSwipeAction prop, a second handler path beside each
action's own. Rejected: a handler map keyed by id, a second place to keep in
step with the actions. Rejected: a value prop on the row; a swipe holds no
value.
Open questions¶
None.
Content boundary¶
The research that produced this record — the cross-library survey, the shapes weighed, and the vibe test's design and scores — is a report, not a contract, and lives outside it.
This record does not duplicate Item's or List's anatomy, prop tables,
theming targets, or geometry contracts; the modality invariants in
architecture:interaction-modality; the admission argument in
spec:AST-002; the press model in module:DropdownMenu/useMenuPress; or the
gesture constants an implementation will hold in source. It links their
canonical owners.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx