An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-057, Item): configure swipe through swipe={createSwipe(…)} (#9387)
Cindy Zhang054b23cdcbf3
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex cdf8b74f93..e74867486a 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -200,13 +200,14 @@ guidance owns the process used to propose and test APIs.picking a specific prop or label of a subcomponent). Build compositionsinstead. Compositions must follow the component's anatomy; never expose a wayto compose or render a slot not described in the anatomy; and slots must have- components. Config objects are fine: plain data that describes actions or options (for example `swipeActions`' array of `{label, icon, onActivate}`) is not a slot. 'Slots must have components' applies to rendered content slots, places that accept arbitrary nodes; such a slot must be a part named in the component's anatomy, and the caller fills it with a component. This extends INV3's rule that a parent does not duplicate a+ components. Config objects are fine: plain data that describes actions or options (for example the `{label, icon, onActivate}` entries passed to `createSwipe`) is not a slot. 'Slots must have components' applies to rendered content slots, places that accept arbitrary nodes; such a slot must be a part named in the component's anatomy, and the caller fills it with a component. This extends INV3's rule that a parent does not duplicate acomposed child's state; a slot's styling follows INV15 and`architecture:component-theming-surface`. See[Slots and composition](../contributing/api-conventions.md#slots-and-composition).- **INV19 — Resource cost is weighed against the feature.** Balance resource load against featurefunctionality and cross-platform concerns. If a feature has a large resource- cost, consider plugging the behavior in. Named props for features are also+ cost, consider plugging the behavior in, as `Item`'s swipe actions plug in+ through `swipe={createSwipe(…)}` (`spec:AST-057` DEC-8). Named props for features are alsofine (like `collapsible`).- **INV20 — Variants, not visual booleans.** Avoid boolean flags that only swap visuals; prefer variants. Thisapplies INV2's naming and INV4's caller-owned intent to visual choices; seediff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.mdindex 048fd73bcc..1ad8a9d1e4 100644--- a/docs/architecture/react-component-runtime.md+++ b/docs/architecture/react-component-runtime.md@@ -267,7 +267,22 @@ those contracts.(`design:reduced-motion` DR1–DR3); and the touch hit-area expansion.Components importthem statically, and the bundler- keeps one copy per page however many components use them. There is no+ keeps one copy per page however many components use them. A touch+ behavior that a caller opts into and that carries a large resource cost+ comes through a public constructor whose module statically imports the+ modules that behavior runs on; the component imports none of those, so+ only an app that imports the constructor ships them+ (`architecture:public-component-api` INV19). `Item`'s swipe actions come+ from `createSwipe` (`spec:AST-057` FR10): `Item` and `ListItem` import+ none of the swipe modules — the gesture core, the animator, the panels'+ rendering, and the row's gesture code — while `Item` keeps using the touch+ modules for its other jobs, such as press feedback. The only swipe code in+ `Item` is its deprecated path, serving its deprecated `swipeActions` and+ `swipeBehavior` props only until they leave in 0.8.0 (`spec:AST-057`+ DEP-0017, CLN-0025): the released loader, the one `import()` of swipe code;+ the released row style; the role gate and the `commit` warning; the bridge+ the loaded layer fills, the click guard, and the event forwarders into that+ bridge; and the coexistence diagnostic. There is noinstall call, no public entry, and no public installed check; tests resetthe modules through an internal hook only. A component's own touch logic issmall glue in its own build over these modules. The gesture host attaches for@@ -439,17 +454,17 @@ observable-behavior predicates require review or runtime evidence. Likewise, afocused test proves only its named behavior and mutation expectation; a greencomponent suite is not blanket conformance with every invariant.-| Invariant | Evidence | Failure signal |-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |-| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |-| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |-| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |-| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |-| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |-| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |-| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |-| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element other than a swap's one transient copy, that copy left after the swap ends, or an exported reporting function fails |-| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component, a public export or doc entry for the modules, an install call or installed check in the public API, a gesture listener in a component that uses no gesture, or an idle document listener outside a press other than the one shared press controller and the one stray-click swallower, an import of `@astryxdesign/core/internal/*` outside Core and Lab, a class outside the recognizer family, an `instanceof` check on a recognizer, an internal factory with a public factory's name, or a direct module import for a job the public layer covers fails |-| INV15 | Unit tests of the animator's value mode and real-browser proofs of its adopters | A value off its motion role, a count past the component's swap size, a count or cross-fade under reduced motion with a coarse or a fine pointer, an intermediate value announced, or a public export fails |-| INV16 | Review of each Core component that handles a concern Core owns in a shared hook or utility | A Core component that keeps its own effect, listener, or tracker for that concern fails, whether or not it also calls the hook or utility |+| Invariant | Evidence | Failure signal |+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |+| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |+| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |+| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |+| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |+| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |+| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |+| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |+| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element other than a swap's one transient copy, that copy left after the swap ends, or an exported reporting function fails |+| INV13 | Source boundary check plus bundle analysis of a page with several touch components, and real-browser tests on a throttled phone profile, under a fine pointer, and on a hybrid device | A second copy of a touch module on one page, a component bundling its own copy of a module's primitive, an `import()` of a module in a component other than `Item`'s released loader for its deprecated swipe props, a swipe module (the gesture core, the animator, the panels' rendering, the row's gesture code) imported by `Item` or `ListItem`, swipe code in `Item` other than its deprecated path (that loader, the released row style, the role gate, the `commit` warning, the bridge, the click guard, the event forwarders, and the coexistence diagnostic), or any of it outside the deprecated path, a public export or doc entry for the modules, an install call or installed check in the public API, a gesture listener in a component that uses no gesture, or an idle document listener outside a press other than the one shared press controller and the one stray-click swallower, an import of `@astryxdesign/core/internal/*` outside Core and Lab, a class outside the recognizer family, an `instanceof` check on a recognizer, an internal factory with a public factory's name, or a direct module import for a job the public layer covers fails |+| INV15 | Unit tests of the animator's value mode and real-browser proofs of its adopters | A value off its motion role, a count past the component's swap size, a count or cross-fade under reduced motion with a coarse or a fine pointer, an intermediate value announced, or a public export fails |+| INV16 | Review of each Core component that handles a concern Core owns in a shared hook or utility | A Core component that keeps its own effect, listener, or tracker for that concern fails, whether or not it also calls the hook or utility |diff --git a/docs/specs/AST-057-row-actions/spec.md b/docs/specs/AST-057-row-actions/spec.mdindex 1bdc6415f8..7564a73dc0 100644--- a/docs/specs/AST-057-row-actions/spec.md+++ b/docs/specs/AST-057-row-actions/spec.md@@ -11,7 +11,11 @@ approved_at: 2026-10-24phase: acceptedowners: [cixzhang]affects_architecture:- [architecture:interaction-modality, architecture:public-component-api]+ [+ architecture:interaction-modality,+ architecture:public-component-api,+ architecture:react-component-runtime,+ ]affects_families: []affects_contributing: [contributing:api-conventions]affects_consumer_docs: [Item, List, ListItem]@@ -31,10 +35,13 @@ review_triggers: [public-api, accessibility, behavior]"FR2","FR3","FR9",+ "FR10",+ "FR11","DEC-1","DEC-3","DEC-4",- "DEC-6"+ "DEC-6",+ "DEC-8"],"accessibility": ["AR1", "AR2", "AR3"],"behavior": ["FR4", "FR5", "FR6", "FR7", "FR8", "DEC-2", "DEC-5"]@@ -44,15 +51,15 @@ review_triggers: [public-api, accessibility, behavior]## Contract at a glance-| Area | Contract |-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | `Item` carries swipe actions for a finger, a pen, and horizontal wheel input. `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 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 horizontal wheel gesture, 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. 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`), `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 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. |-| 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. |+| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `Item` carries swipe actions for a finger, a pen, and horizontal wheel input 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 horizontal wheel gesture, 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. 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 their `ItemSwipe*` types are deprecated in a patch with no runtime warning (DEP-0017) and 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. Implementation gap: `swipe` and `createSwipe` are not built (Current-state impact). |+| 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`](../../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.@@ -80,8 +87,12 @@ and its panels stay put, so no element is added to any row.**Owns**-- The public shape of `Item`'s swipe actions: `ItemSwipeAction` and its- fields, the per-side arrays, and `swipeBehavior`.+- The public shape of `Item`'s swipe actions: the `swipe` prop,+ `createSwipe` and its options, `SwipeAction` and its fields, the+ per-side arrays, `swipeBehavior`, and the opaque `Swipe` value.+- Where the swipe's code lives: in the constructor's module, never in `Item`+ or `ListItem`, except DEP-0017's deprecated path in `Item` — the released loader, the released row style, the role gate, the `commit` warning, the bridge the loaded layer fills, the click guard, the event forwarders 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, `reveal` and `commit`, meaning the same thing whereverswipe actions are available.@@ -138,9 +149,12 @@ and its panels stay put, so no element is added to any row.- **Vertical swipes**, and a swipe whose onlymeaning 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+ panel positions are internal, rendered from `swipe`. A secondconsumer — an accent bar, a slide-in checkbox, a drag handle — is a`component:Item` anatomy record with its own admission argument.+- **Swipe actions on an element that is not an `Item`.** `createSwipe`+ configures `Item`; attaching its result to any other element is not+ admitted.- **A programmatic open or close.** Not admitted: a swipe panel's open statebelongs to the gesture, and the one coordination case met in practice — aresting row closing when a neighbour's drag starts — is already a pointer@@ -175,7 +189,7 @@ and its panels stay put, so no element is added to any row.| `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. |+| `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*`. |@@ -205,19 +219,22 @@ and its panels stay put, so no element is added to any row.## 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 once the row's content has left its box (FR5). | — | `spec:AST-057` | proposed |-| `Item.swipeBehavior` | `'reveal'` \| `'commit'` | `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 `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 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 |+| 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). | absent | `spec:AST-057` | proposed |+| `createSwipe` | `(options: CreateSwipeOptions) => Swipe` | Exported from `@astryxdesign/core/Swipe` and the package root. A plain function, not a hook: callable at module scope, outside a render, and on the server, and doing no DOM work when imported or called. 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[]; trailing?: readonly SwipeAction[]; swipeBehavior?: SwipeBehavior}` | 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. | — | `spec:AST-057` | proposed |+| `SwipeAction` | `{id?: string; label: string; icon?: ReactNode; onActivate: () => void \| Promise<void>; isDisabled?: boolean; variant?: SwipeActionVariant; 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 |+| `SwipeActionVariant` | `'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). | — | `spec:AST-057` | proposed |+| `swipeBehavior` (`SwipeBehavior`) | `'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 `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 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@@ -227,17 +244,19 @@ constants.### 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 by a finger or a pen, or a horizontal wheel gesture, 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. | 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. 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 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. 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. Because a drag on a neighbour is a pointer outside it, at most one row is 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. | `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 |+| ID | Invariant | Basis | Verification state |+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1 | `Item` MUST take its swipe actions as one prop, `swipe`, whose value is the `Swipe` that `createSwipe(options)` returns, where `options` is `{leading?: readonly SwipeAction[]; trailing?: readonly SwipeAction[]; swipeBehavior?: SwipeBehavior}` and `SwipeAction` 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. `Swipe` MUST be opaque, made only by `createSwipe`. `ListItem` MUST pass `swipe` through unchanged. The deprecated `swipeActions` and `swipeBehavior` props follow DEP-0017. | DEC-1, DEC-8; `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, `SwipeBehavior`, 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 horizontal wheel gesture, 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. | 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. 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 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. 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. Because a drag on a neighbour is a pointer outside it, at most one row is 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. | `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, the click guard that reads it, and the event forwarders 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 | A caller MAY call `createSwipe` inline in a render. A new `Swipe` value 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 entry list repaints the panel. | DEC-8 | Proposed |### Accessibility contract@@ -249,10 +268,10 @@ constants.(`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 NOTuncover the panel, and on a pointer that can hover a closed row's- `swipeActions` MUST have no effect on the tab order, the accessible tree, or+ `swipe` MUST have no effect on the tab order, the accessible tree, orthe row's paint. A pen's drag (`spec:AST-094` FR43), a trackpad's horizontal scroll swipe, or a mouse'shorizontal wheel, which sends the same events, MAY uncover the panel (DEC-7), and a row it leaves resting open follows AR1.-- **AR3 — The row's primary stays one tab stop.** `swipeActions` MUST NOT+- **AR3 — The row's primary stays one tab stop.** `swipe` MUST NOTchange the primary element's role or name, MUST NOT change its activationwhile the row is closed, and MUST add no stop while closed. While the row isopen, a touch tap on its content closes it (FR7); keyboard activation is@@ -260,7 +279,7 @@ constants.- **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 mousedrag.- The consumer documentation of `swipeActions` MUST say so and MUST show the+ The consumer documentation of `swipe` MUST say so and MUST show theverb also reachable through the row's own content. The component does notinspect what else the row offers.@@ -281,12 +300,28 @@ constants.## Current-state impact-- `Item` gains `swipeActions`, `swipeBehavior`, the exported types- `ItemSwipeAction` and `ItemSwipeActionVariant`, two out-of-flow panel+- Implementation gap: `swipe`, `createSwipe`, and the types+ `SwipeAction`, `SwipeActionVariant`, `SwipeBehavior`,+ `CreateSwipeOptions`, and `Swipe` are not built. `Item`+ takes the released `swipeActions` and `swipeBehavior` and 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.+- `Item` gains `swipe`, and Core exports `createSwipe` with the types+ `SwipeAction`, `SwipeActionVariant`, `SwipeBehavior`,+ `CreateSwipeOptions`, and `Swipe`; `Item` gains two out-of-flow panelpositions on its root with a theme target, and the root and paneltransforms. No new element, no gesture on any row that does not ask forit. `component:Item`, when written, inherits these claims.-- `ListItem` inherits both props through its existing `Item` passthrough.+- `ListItem` inherits the released `swipeActions` and `swipeBehavior`+ through its existing `Item` passthrough, deprecated by DEP-0017; the+ `swipe` prop is not built, on `Item` or on `ListItem`.+- `architecture:react-component-runtime` INV13 gains the constructor route+ for an opt-in touch behavior with a large resource cost: `Item` and+ `ListItem` import none of the swipe modules, and its failure signal names+ DEP-0017's deprecated path in `Item` — the released loader, the released row style, the role gate, the `commit` warning, the bridge the loaded layer fills, the click guard, the event forwarders into that bridge, and the coexistence diagnostic — as the only+ exception, on the deprecated path only, until CLN-0025.+- `architecture:public-component-api` INV19 names `swipe={createSwipe(…)}`+ as its plug-in example (DEC-8).- `component:List` gains the inline clip on `List`'s root, citing thisrecord.- `architecture:interaction-modality` gains `spec:AST-057` in its deciding@@ -303,15 +338,17 @@ constants.## 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; 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 | 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 | 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, or a scroll that closes the row while focus is inside its open panel, 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; 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 `swipeActions` | The prop's documentation | A doc that does not state the keyboard consequence or the group clip fails. |+| 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` 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; 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 | 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 | 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, or a scroll that closes the row while focus is inside its open panel, 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 click guard, the event forwarders, 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 entries; a changed entry list; a changed handler | A new value that closes the row, restarts the settle, or attaches the gesture again, a stale handler, or a panel that keeps the old entries 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 nocomponent implements the contract. This record is `draft`, does not govern@@ -327,7 +364,7 @@ until `approved_by` is set.**Reference:** `spec:AST-057/DEC-1`**Decider:** `cixzhang`, `2026-10-02`-`swipeActions.leading` and `.trailing` are `ItemSwipeAction[]`: `{id?, label,+`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.@@ -357,7 +394,7 @@ Composition is deferred, not lost: a `render*`-shaped addition for a panelthe vocabulary cannot draw can land when a caller needs it. How a held-outrow leaves, and how a kept row returns, is not this record's (Non-goals).-Rejected: nodes per side with a shipped `ItemSwipeAction` component — it+Rejected: nodes per side with a shipped `SwipeAction` component — itneeded context registration for `commit`, and left any caller-supplied nodesilently without it. Rejected: one action per side with `onAction` and a four-tone `tone` — asecond 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@@ -389,7 +426,7 @@ without a default change. Rejected: a boolean `hasFullSwipe` — under `reveal`**Reference:** `spec:AST-057/DEC-3`**Decider:** `cixzhang`, `2026-10-03`-`Item` owns `swipeActions` and `swipeBehavior`. `ListItem` inherits them+`Item` owns `swipe`. `ListItem` inherits itthrough 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 mustpermit interactive descendants, because a swipe panel's controls are@@ -428,7 +465,7 @@ owns the one coordination case.**Reference:** `spec:AST-057/DEC-4`**Decider:** `cixzhang`, `2026-10-02`-A mouse drag and hover do nothing with `swipeActions`; horizontal wheel+A mouse drag and hover do nothing with `swipe`; horizontal wheelinput, a trackpad's scroll or a mouse's horizontal wheel, and a pen are thenon-finger inputs that swipe a row (DEC-7); what a row offersa mouse or a keyboard is the row's own content, which this record does not@@ -482,7 +519,7 @@ anatomy takes its own admission.**Reference:** `spec:AST-057/DEC-6`**Decider:** `cixzhang`, `2026-10-02`-`ItemSwipeActionVariant` is `'neutral' | 'accent' | 'destructive'`: three+`SwipeActionVariant` is `'neutral' | 'accent' | 'destructive'`: threeflavours of verb — ordinary, the one you mean, the dangerous one — and`accent` is the default on a swipe panel, because the panel is a filledsurface that has to be some colour and `ProgressBar` already defaults a@@ -516,6 +553,65 @@ same events as a trackpad and swipes the same way.Rejected: keeping swipe actions touch-only.+### 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`, `ItemSwipeActions`, `ItemSwipeActionVariant`, and `ItemSwipeBehavior` |+| 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); the types map one to one: `ItemSwipeAction` to `SwipeAction`, `ItemSwipeActionVariant` to `SwipeActionVariant`, `ItemSwipeBehavior` to `SwipeBehavior`, and `ItemSwipeActions` to `CreateSwipeOptions` |+| direct authority | `spec:AST-057` DEC-8. Owner: `cixzhang` |+| warning | Static `@deprecated` metadata on the two props and the four 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 their released behavior 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, the click guard that reads it, and the event forwarders 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. 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`, adds the `createSwipe` import, renames the four types, removes a `swipeBehavior="reveal"` it would merge as the default, and reports JSX spreads that may carry the deprecated props and call sites that mutate a `leading` or `trailing` array of a value it retypes as `CreateSwipeOptions`, since those arrays are `readonly SwipeAction[]` (`spec:AST-017` FR29c, FR29d) |+| 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`, and the four `ItemSwipe*` types 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 click guard, the event forwarders, 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 |+## Open questionsNone.diff --git a/docs/specs/components/List/List.spec.md b/docs/specs/components/List/List.spec.mdindex c36e9f6e97..b0ae14cc3f 100644--- a/docs/specs/components/List/List.spec.md+++ b/docs/specs/components/List/List.spec.md@@ -210,8 +210,7 @@ Consumer migration instructions belong in consumer docs and release notes.entering, exiting, and crossing (FR12).- `spec:AST-057` owns swipe actions on `Item` and the rule that the elementcontaining swipe-capable rows clips in the inline axis; List carries that clip- (FR9) and `ListItem` passes `swipeActions` and `swipeBehavior` through to- `Item` unchanged. Static Markdown document lists follow DEC-5's narrow exception;+ (FR9) and `ListItem` passes `swipe` through to `Item` unchanged. Static Markdown document lists follow DEC-5's narrow exception;`spec:AST-061` FR11 owns their whole counters and cross-renderer indentation.- `spec:AST-094` owns the touch presentation gate (FR13), the press model(FR11), and motion roles (FR4); FR10 and FR11 apply the gate and the pressdiff --git a/docs/specs/components/List/ListItem.spec.md b/docs/specs/components/List/ListItem.spec.mdindex 55611c9316..7f99b78f3f 100644--- a/docs/specs/components/List/ListItem.spec.md+++ b/docs/specs/components/List/ListItem.spec.md@@ -34,15 +34,15 @@ system_specs: [spec:AST-057, spec:AST-103]## Contract at a glance-| Area | Contract |-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| Public contract | `ListItem` with `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, `xstyle`, `className`, `style`, and `ref`; the row carries `component:List`'s `list-item` target. `itemKey` (`spec:AST-103` DEC-4) is specified but not shipped. |-| Behavior | One `<li>` row rendered by `component:Item`, which receives every row prop. Inside a List the row takes the list's density, dividers, edge treatment, and marker; outside a List it uses Item's defaults and draws no marker. |-| End-user impact | Each list entry reads as one list item, with the list's bullet, number, or task checkbox before it and the same interaction Item gives any row. |-| Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact. |-| Review checks | Reject a row that is not an `<li>`, a ListItem-level edge, density, or divider prop, a marker drawn outside a marked List, or a dropped Item prop. |-| Governing rules | `component:Item` (`align` for start and end content); `component:List`; `family:navigation-destinations`; `spec:AST-057`; `spec:AST-103`; `architecture:component-theming-surface`; `architecture:component-style-authoring` INV7. |+| Area | Contract |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `ListItem` with `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipe`, `xstyle`, `className`, `style`, and `ref`, with the deprecated `swipeActions` and `swipeBehavior` until `spec:AST-057` CLN-0025; the row carries `component:List`'s `list-item` target. `itemKey` (`spec:AST-103` DEC-4) is specified but not shipped. |+| Behavior | One `<li>` row rendered by `component:Item`, which receives every row prop. Inside a List the row takes the list's density, dividers, edge treatment, and marker; outside a List it uses Item's defaults and draws no marker. |+| End-user impact | Each list entry reads as one list item, with the list's bullet, number, or task checkbox before it and the same interaction Item gives any row. |+| Builder impact | The deprecated `swipeActions` and `swipeBehavior` move to `swipe={createSwipe(…)}` under `spec:AST-057` DEP-0017; its `astryx upgrade` codemod is an opt-in early migration from the deprecating release and runs again in 0.8.0's upgrade with CLN-0025's removal. |+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps, listed under Current-state impact. |+| Review checks | Reject a row that is not an `<li>`, a ListItem-level edge, density, or divider prop, a marker drawn outside a marked List, or a dropped Item prop. |+| Governing rules | `component:Item` (`align` for start and end content); `component:List`; `family:navigation-destinations`; `spec:AST-057`; `spec:AST-103`; `architecture:component-theming-surface`; `architecture:component-style-authoring` INV7. |This table is a review projection; the body below is authoritative.@@ -59,7 +59,10 @@ from `component:Item`. Consumer usage lives in `ListItem.doc.mjs`.- Compatibility class: records shipped behavior; no public change- Controlled/uncontrolled behavior: not applicable; `isSelected` and`isDisabled` are caller-owned-- Migration decision: none+- Migration decision: `spec:AST-057` DEP-0017, whose `astryx upgrade` codemod+ rewrites `swipeActions` and `swipeBehavior` to `swipe={createSwipe(…)}`; it+ is an opt-in early migration from the deprecating release and runs again in 0.8.0's upgrade with+ `spec:AST-057` CLN-0025's removalConsumer migration instructions belong in consumer docs and release notes.@@ -73,6 +76,11 @@ Consumer migration instructions belong in consumer docs and release notes.- **ListItem has no `itemKey` yet.** `spec:AST-103` DEC-4 and `component:List`FR12 have each reorderable row name its item through an `itemKey` prop;ListItem does not accept one yet.+- **ListItem has no `swipe` yet.** `spec:AST-057` FR1 has ListItem pass+ `swipe` through to `Item`, which replaces the deprecated `swipeActions`+ and `swipeBehavior` (`spec:AST-057` DEP-0017); `swipe` is not built, so+ `ListItemProps` has no `swipe` yet and FR1's pass-through of it is not+ current source.## Ownership boundary@@ -109,7 +117,7 @@ No component-local concept beyond the consumer props; row props are| ID | Invariant | Basis || --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | ListItem renders `component:Item` as an `<li>` and passes `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, and `ref` to it unchanged, with other DOM and data props reaching the row. | Current source and tests |+| FR1 | ListItem renders `component:Item` as an `<li>` and passes `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipe`, the deprecated `swipeActions` and `swipeBehavior` (`spec:AST-057` DEP-0017), and `ref` to it unchanged, with other DOM and data props reaching the row. | Current source and tests || FR2 | Inside a List, the row takes the list's `density`, its `hasDividers` setting, which draws a divider between rows with no extra element and square corners, and its `edge` treatment. | Current source and tests || FR3 | Outside a List, the row uses `balanced` density, no dividers, the `padded` treatment, and no marker, keeping Item's inline inset. | Current source and tests || FR4 | In a List whose `listStyle` is `disc`, `circle`, or `decimal`, the row draws that marker before its content: a disc or circle shape, or a counter number. A task state set for the row draws a read-only, labelled checkbox in the marker's place. Each marker and the task checkbox sit on the label's first line. A List whose `listStyle` is `none` draws neither. Other markers, set internally for Markdown's nested lists, are uncontracted here. | Current source and tests |