An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-057): swipe actions on Item (#6908)
Cindy Zhang8962994b09ce
diff --git a/docs/specs/AST-057-row-actions/spec.md b/docs/specs/AST-057-row-actions/spec.mdnew file mode 100644index 0000000000..2fbcf10de9--- /dev/null+++ b/docs/specs/AST-057-row-actions/spec.md@@ -0,0 +1,528 @@+---+schema_version: 4+template_version: 1+kind: system-spec+id: spec:AST-057+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+phase: proposed+owners: [cixzhang]+affects_architecture:+ [architecture:interaction-modality, architecture:public-component-api]+affects_families: []+affects_contributing: [contributing:api-conventions]+affects_consumer_docs: [Item, List, ListItem]+review_triggers: [public-api, accessibility, behavior]+---++# Swipe actions on `Item` system spec++<!-- review-applicability:v1 -->++```json+{+ "scope": "global",+ "triggers": {+ "public-api": [+ "FR1",+ "FR2",+ "FR3",+ "FR9",+ "DEC-1",+ "DEC-3",+ "DEC-4",+ "DEC-6"+ ],+ "accessibility": ["AR1", "AR2", "AR3"],+ "behavior": ["FR4", "FR5", "FR6", "FR7", "FR8", "DEC-2", "DEC-5"]+ }+}+```++## Contract at a glance++| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `Item` carries touch swipe actions. `swipeActions` declares, per side, the verbs a sideways drag uncovers as `ItemSwipeAction[]` — `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 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 (DEC-4). No new DOM: the row's root translates and its panels counter-translate (DEC-5). |+| Behavior | On a coarse pointer a sideways drag moves the row and 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 springs back, 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. Nothing changes for anyone else: a mouse, a keyboard, or a screen reader meets the row exactly as today. |+| Builder impact | One prop on `Item` (and so on `ListItem`), `swipeActions={{trailing: [{label: 'Archive', icon: <Icon icon={ArchiveIcon} />, onActivate: archive, hasRemoval: true}]}}`; optionally `swipeBehavior`. 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 | Additive: both props are absent by default; every current row keeps its DOM and paint exactly. Authority: `draft`; `approved_by` is `null`. No owner question is open. |+| Review checks | Reject a hover-revealed panel; 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. |+| Governing rules | [`architecture:interaction-modality`](../../architecture/interaction-modality.md) INV4, INV6, INV7; [`spec:AST-002`](../AST-002/spec.md) FR1, FR4, FR15, FR16, `DEC-1`; [`architecture:public-component-api`](../../architecture/public-component-api.md) 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 touch-only and is an accelerator: it adds a faster path to a+verb on a coarse pointer and changes nothing on any other input. 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.++The trigger is [#6821](https://github.com/facebook/astryx/pull/6821), a port+of a shipping product's mail row. The owner's direction on reading it: swipe+actions only, scoped to mobile; both rest-open and fire-on-release; declared data rather than nodes; scope by the row's role, not by+model; no new container+DOM; no public slots; the+row's own end content is the row's business, not this record's.++## Ownership boundary++**Owns**++- The public shape of `Item`'s swipe actions: `ItemSwipeAction` and its+ fields, the per-side arrays, and `swipeBehavior`.+- The rule for where swipe actions are available: the row's role.+- The two models, `reveal` and `commit`, meaning the same thing wherever+ swipe actions are available.+- The coarse-pointer 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 the gesture touches nothing on a+ pointer that can hover.++**Why no existing record can hold it**++- [`architecture:interaction-modality`](../../architecture/interaction-modality.md)+ is `current` and owns the rule the gesture must respect — INV7 "essential+ actions remain reachable" — but owns no public API. A record carries one+ `authority` value, so adding unapproved API claims to it would present+ them as approved (`architecture:knowledge-contracts` INV1, INV14).+- `Item` has no component record. This record is the first durable decision+ about `Item`'s public surface; `component:Item`, when written, inherits+ these claims rather than re-deciding them. Of `Item`'s seven in-core renderers, six give the row a role that forbids+ interactive descendants and are out of scope; `ListItem` and a bare `Item` in caller markup — which the system's own+ templates render inside a `BottomSheet` and on a page — are the rows this+ record serves: two real consumers, one home, and the prop stays on the+ primitive (DEC-3).+- [`component:List`](../../../packages/core/src/List/List.spec.md) is+ `current` and owns List's geometry; it gains the inline clip and cites+ this record.+- [`spec:AST-002`](../AST-002/spec.md) owns 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 — are `Item`'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.** Deliberately parked, not open: a row+ the caller removes after an action unmounts as any row does today. The+ owner is not ready to settle the shape; the likely form is imperative+ (`handleRef`, as `Selector` and `MultiSelector` expose open/close) so enter+ can be animated too. `hasRemoval` is 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, slide+ and spring durations, resistance past the panel: behavior constants in+ source, not public API and not design tokens (the same ruling the touch+ press model received for its clocks).+- **Vertical swipes**, two-finger trackpad 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 from `swipeActions`. A second+ consumer — an accent bar, a slide-in checkbox, a drag handle — is a+ `component:Item` anatomy record with its own admission argument.+- **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; the source product exposes no+ such handle. If one ever does, `handleRef` is the established pattern to add+ it with, as `Selector` and `MultiSelector` expose 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+ `listitem` and a role-less `Item` qualify, and "it'll just work" there. A+ row whose role forbids them is out of scope as a consequence: `option`+ (inside a `listbox`), `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, so `swipeBehavior`+ means one thing everywhere swipe actions exist. In core today that+ excludes `SelectorOption`, the four `DropdownMenu` rows, and+ `RadioListItem`, and includes `ListItem` and every bare `Item`.+- 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". `ItemSwipeAction` 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. |+| #6821 real-device feedback | On an iOS device the swipe required a press-and-hold before it would start, and the row background did not restore until release. The gesture craft is not yet settled on a device. |+| The source product's row (#6821 is its port) | 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 springs back by the bit. |+| Reversible toggle (read/unread, pin/flag) | Yes | `label` names the state the verb reaches ("Unread"); no `hasRemoval`. Under `reveal` the row springs back wearing it; under `commit` it slides out, fires, and springs back 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 springs back. |+| 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 springs back 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.swipeActions` | `{leading?: ItemSwipeAction[]; trailing?: ItemSwipeAction[]}` | The verbs a sideways drag uncovers on each side, outermost last. `leading` is uncovered by a drag toward the inline end, `trailing` by one toward the inline start. Inherited by `ListItem` and every host that renders an `Item`. | absent | `spec:AST-057` | proposed |+| `ItemSwipeAction` | `{id?: string; label: string; icon?: ReactNode; onActivate: () => void \| Promise<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"). 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 at activation. | — | `spec:AST-057` | proposed |+| `Item.swipeBehavior` | `'reveal'` \| `'commit'` | `reveal`: past the panel's width the row rests open with every entry a real button; a long drag or fling fires the outermost. `commit`: a release past the commit 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 `Item`s 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 never starts the drag; a coarse pointer does. Read from the pointer 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 `swipeActions: {leading?: ItemSwipeAction[]; trailing?: ItemSwipeAction[]}`, where `ItemSwipeAction` is `{id?, label: string, icon?: ReactNode, onActivate, isDisabled?, variant?: 'neutral' \| 'accent' \| 'destructive', hasRemoval?: boolean}` with `variant` defaulting to `accent`. An entry MUST NOT carry a node the component renders as the control. `ListItem` MUST pass the prop through unchanged. | DEC-1; `DropdownMenuItemData`; `useMenuPress.onActivate`; `ProgressBar.variant` | Proposed; no evidence on `main` |+| 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 enum with the closed values `reveal` and `commit`, default `reveal`. `commit` with more than one entry on a side MUST warn in development, because the other entries have no touch path. | DEC-2; `spec:AST-002` FR15 | Proposed |+| FR4 | A sideways drag on a coarse pointer 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; the panel MUST NOT be visible at rest, by any pixel. | #6821 review (resting-panel sliver) | Proposed; real-Chromium evidence required |+| FR5 | Under `reveal`, a release past the panel's width MUST leave the row resting open with every entry tappable, and a drag past the commit point or a fling MUST fire the **outermost** entry and no other. Under `commit`, a release past the commit point or a fling MUST slide the row out and fire the outermost entry; nothing MUST rest. After any entry fires, under either model, the row MUST spring back unless the entry has `hasRemoval`, in which case it MUST hold out at the edge it travelled toward. 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. `onActivate` MUST fire at activation and may return a Promise. | DEC-1, DEC-2; UIKit `performsFirstActionWithFullSwipe`; source product | 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. | #6821's gesture; press-model ORD1 | Proposed; device feedback on #6821 shows the first is unsettled |+| FR7 | A resting row MUST close on a pointer landing anywhere outside it, on Escape with focus inside it, on firing an entry, and on unmount. Because a drag on a neighbour is a pointer outside it, at most one row rests open at a time without any shared state. | 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. | #6821; `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 |++### 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 by `label`, 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. Under `commit` the panel MUST be presentational+ (`aria-hidden`) at all times, because nothing in it is ever tappable.+- **AR2 — The gesture touches nothing on a pointer that can hover.**+ `swipeActions` MUST have no effect on the tab order, the accessible tree,+ or the row's paint on such a pointer. Hover MUST NOT uncover the panel.+- **AR3 — The row's primary stays one tab stop.** `swipeActions` MUST NOT+ change the primary element's role, name, or activation, and MUST add no+ stop while closed.+- **Stated in documentation, not enforced:** a swipe is a touch accelerator,+ so a verb reachable only by swipe is unreachable by keyboard and by mouse.+ The consumer documentation of `swipeActions` MUST 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.+ Pointer type is read from the pointer event.+- Unsupported behavior: a device that never produces a coarse pointer gets+ no swipe and 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 #6821's device+ feedback contradicts its Chromium evidence.++## Current-state impact++- `Item` gains `swipeActions`, `swipeBehavior`, the exported types+ `ItemSwipeAction` and `ItemSwipeActionVariant`, 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.+- `ListItem` inherits both props through its existing `Item` passthrough.+- `component:List` gains the inline clip on `List`'s root, citing this+ record.+- `architecture:interaction-modality` gains `spec:AST-057` in its deciding+ specs; no invariant changes.+- `contributing:api-conventions` gains the rule this record relies on: a+ gesture is an accelerator and never a component's only path to its own+ behavior.+- `spec:AST-058` ([#6910](https://github.com/facebook/astryx/pull/6910))+ takes nodes where this record takes objects, on the shared principle in+ DEC-1: the picker places its actions; `Item` renders its panel.+- [#6821](https://github.com/facebook/astryx/pull/6821) is superseded in+ shape by this record; its commit-only model survives as+ `swipeBehavior="commit"` and its gesture engineering — axis lock, logical+ directions, click suppression, reduced-motion handling, the Chromium+ harness — is the starting point for FR4–FR8 once the device findings are+ resolved. Its clipping container does not survive (DEC-5).+- No shipped public API changes on this record's own merge.+- While this record is `draft` its `review-applicability:v1` block routes+ nothing: global routing loads `current` claims only+ (`architecture:knowledge-contracts` INV20).++## 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 | A field with a node the row renders as the control, a silent multi-entry `commit`, or `ListItem` reshaping the prop 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; release short, past the panel, past the commit point, fling; both models; both sides; `hasRemoval` and plain entries under each; vertical drag; mouse drag; RTL | A resting sliver, an immediate fire under `reveal`, 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 | Open one, drag the other; outside tap; Escape; entry fired; unmount | Two rows resting open, or a row that stays open after any closing event, 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. |+| 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; hover and Tab on a fine pointer | A panel exposed while closed, a `commit` panel in the tree, an entry without a name while resting, a changed primary, or any effect on a fine pointer fails. |+| Documentation | Consumer-doc check on `swipeActions` | 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 is **proposed**. None has been ruled on; `approved_by`+is `null` and the record is `draft`.++### DEC-1 — Swipe actions are declared as data++**Reference:** `spec:AST-057/DEC-1`+**Decider:** `cixzhang`, `2026-10-02` (direction; record pending)++`swipeActions.leading` and `.trailing` are `ItemSwipeAction[]`: `{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 recall+probes found builders+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 `ItemSwipeAction` 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` (#6821) — 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 tangled the resting bit with the parked exit question. 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`, `<pending>`++`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`](https://developer.apple.com/documentation/uikit/uiswipeactionsconfiguration),+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 the owner asked for both models, and it is what the+source product chose for its one-verb rows.++Rejected: commit-only as the sole model (#6821) — 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 `swipeActions` and `swipeBehavior`. `ListItem` inherits them+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` (direction; record pending)++On a pointer that can hover, `swipeActions` does nothing. The gesture is a+touch accelerator and changes nothing on any other input; 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](https://react-aria.adobe.com/examples/ios-list)+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` (direction; record pending)++`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: #6821's clipping container around a new inner+row — the element the owner asked to avoid. 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:+#6821's `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.++## 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, linked from the pull request that+introduced the record.++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.