@waveso/ui 0.17.0 → 0.18.0

package/dist/styles.css

@@ -247,21 +247,21 @@
    * `--contrast`…).
    * ──────────────────────────────────────────────────────────────────────── */
 
-  /* Graphite — the mid-tone grey (default). Built around its card colour, the
-   * 900 (#2F3036): the page (950) and menus (800) one even contrast step
-   * either side, the steps above evenly spaced up to the text colour at the
-   * 50. One hue, 278.2; chroma arcs to 0.014 through the middle. */
-  --graphite-50:  oklch(0.964 0.001 278.2); /* #F3F3F4 */
-  --graphite-100: oklch(0.911 0.004 278.2); /* #E1E1E4 */
-  --graphite-200: oklch(0.840 0.007 278.2); /* #C9CACF */
-  --graphite-300: oklch(0.757 0.009 278.2); /* #AEB0B6 */
-  --graphite-400: oklch(0.678 0.011 278.2); /* #96979F */
-  --graphite-500: oklch(0.589 0.013 278.2); /* #7B7C85 */
-  --graphite-600: oklch(0.498 0.014 278.2); /* #61626B */
-  --graphite-700: oklch(0.415 0.013 278.2); /* #4A4B53 */
-  --graphite-800: oklch(0.348 0.012 278.2); /* #383940 */
-  --graphite-900: oklch(0.311 0.011 278.2); /* #2F3036 */
-  --graphite-950: oklch(0.268 0.009 278.2); /* #25262A */
+  /* Graphite — the mid-tone grey (default). Built around its original card
+   * colour, the 900 (#323339): the page (950) and menus (800) one 1.15
+   * contrast step either side, the steps above evenly spaced up to the text
+   * colour at the 50. One hue, 278.3; chroma arcs to 0.014 through the middle. */
+  --graphite-50:  oklch(0.964 0.001 278.3); /* #F3F3F4 */
+  --graphite-100: oklch(0.912 0.003 278.3); /* #E1E2E4 */
+  --graphite-200: oklch(0.842 0.007 278.3); /* #CACBD0 */
+  --graphite-300: oklch(0.761 0.009 278.3); /* #B0B1B7 */
+  --graphite-400: oklch(0.683 0.011 278.3); /* #9799A0 */
+  --graphite-500: oklch(0.595 0.013 278.3); /* #7D7E87 */
+  --graphite-600: oklch(0.506 0.014 278.3); /* #63646D */
+  --graphite-700: oklch(0.424 0.014 278.3); /* #4C4E56 */
+  --graphite-800: oklch(0.359 0.012 278.3); /* #3B3C43 */
+  --graphite-900: oklch(0.322 0.011 278.3); /* #323339 */
+  --graphite-950: oklch(0.283 0.009 278.3); /* #28292E */
 
   /* Ink — deep navy surfaces, neutral-cool structure (page #020812, surface #0B1627).
    * Graphite's even lightness steps between Ink's 50 and its page. Chroma fades
@@ -318,6 +318,11 @@
   /* Rings = brand themed */
   --focus: var(--primary);
 
+  /* Selected — chosen, current or on: the current tab, the sidebar's current
+   * page, a pressed toggle, a checked box, a selected row. Primary by default,
+   * so it looks as it always has; set it to restyle every chosen state at once. */
+  --selected: var(--primary);
+
   /* Scrim — the dim behind modal overlays (dialog / drawer / alert backdrop). */
   --scrim: oklch(0 0 0 / 0.1);
 
@@ -498,17 +503,17 @@
     --wave-teal-900: oklch(0.251 0.049 219.9);
     --wave-teal-950: oklch(0.197 0.037 222.5);
     /* Graphite */
-    --graphite-50:  oklch(0.964 0.001 278.2);
-    --graphite-100: oklch(0.911 0.004 278.2);
-    --graphite-200: oklch(0.840 0.007 278.2);
-    --graphite-300: oklch(0.757 0.009 278.2);
-    --graphite-400: oklch(0.678 0.011 278.2);
-    --graphite-500: oklch(0.589 0.013 278.2);
-    --graphite-600: oklch(0.498 0.014 278.2);
-    --graphite-700: oklch(0.415 0.013 278.2);
-    --graphite-800: oklch(0.348 0.012 278.2);
-    --graphite-900: oklch(0.311 0.011 278.2);
-    --graphite-950: oklch(0.268 0.009 278.2);
+    --graphite-50:  oklch(0.964 0.001 278.3);
+    --graphite-100: oklch(0.912 0.003 278.3);
+    --graphite-200: oklch(0.842 0.007 278.3);
+    --graphite-300: oklch(0.761 0.009 278.3);
+    --graphite-400: oklch(0.683 0.011 278.3);
+    --graphite-500: oklch(0.595 0.013 278.3);
+    --graphite-600: oklch(0.506 0.014 278.3);
+    --graphite-700: oklch(0.424 0.014 278.3);
+    --graphite-800: oklch(0.359 0.012 278.3);
+    --graphite-900: oklch(0.322 0.011 278.3);
+    --graphite-950: oklch(0.283 0.009 278.3);
     /* Ink */
     --ink-50:  oklch(0.966 0.003 248);
     --ink-100: oklch(0.906 0.007 265);
@@ -546,8 +551,8 @@
  * dark system as on a light one. A pinned theme class still beats both.
  *
  * The page and popups are white; cards and the sidebar sit on the 50, a faint
- * warm tint, so the contour does most of the separating. The marks are its
- * text colour, the 950, made translucent, as in every theme.
+ * warm tint, so their edge does most of the separating. Lines and fills are
+ * its text colour, the 950, made translucent, as in every theme.
  * ------------------------------------------------------------------------- */
 :where(:root),
 .paper {
@@ -556,11 +561,13 @@
   --elevated: white;
   --contrast: var(--paper-950);
   --muted: var(--paper-600);
-  --soft: var(--paper-500);
+  --subtle: var(--paper-500);
   --secondary: var(--paper-100);
-  --contour: color-mix(in srgb, var(--paper-950) 5%, transparent);
-  --highlight: color-mix(in srgb, var(--paper-950) 10%, transparent);
-  --shade: color-mix(in srgb, var(--paper-950) 15%, transparent);
+  --line: color-mix(in srgb, var(--paper-950) 5%, transparent);
+  --edge: color-mix(in srgb, var(--paper-950) 10%, transparent);
+  --contour: color-mix(in srgb, var(--paper-950) 15%, transparent);
+  --highlighted: color-mix(in srgb, var(--paper-950) 10%, transparent);
+  --neutral: color-mix(in srgb, var(--paper-950) 15%, transparent);
   --shadow-strength: 0.055;
   --danger: var(--wave-red-500);
   --danger-text: var(--wave-red-600);
@@ -589,20 +596,22 @@
     --elevated: var(--graphite-800);
     --contrast: var(--graphite-50);
     --muted: var(--graphite-300);
-    --soft: var(--graphite-500);
+    --subtle: var(--graphite-500);
     --secondary: var(--graphite-700);
-    --contour: color-mix(in srgb, var(--graphite-50) 5%, transparent);
-    --highlight: color-mix(in srgb, var(--graphite-50) 10%, transparent);
-    --shade: color-mix(in srgb, var(--graphite-50) 15%, transparent);
+    --line: color-mix(in srgb, var(--graphite-50) 5%, transparent);
+    --edge: color-mix(in srgb, var(--graphite-50) 10%, transparent);
+    --contour: color-mix(in srgb, var(--graphite-50) 15%, transparent);
+    --highlighted: color-mix(in srgb, var(--graphite-50) 10%, transparent);
+    --neutral: color-mix(in srgb, var(--graphite-50) 15%, transparent);
     --shadow-strength: 0.045;
     --danger: var(--wave-red-500);
-    --danger-text: oklch(0.738 0.158 16.8); /* #FE7C86, see below */
+    --danger-text: oklch(0.749 0.152 16.8); /* #FF828B, see below */
     --success: var(--wave-green-500);
-    --success-text: oklch(0.700 0.155 160); /* #14BB7C, see below */
+    --success-text: oklch(0.712 0.161 160); /* #00C07E, see below */
     --warning: var(--wave-orange-500);
-    --warning-text: oklch(0.732 0.173 57.3); /* #F78711, see below */
+    --warning-text: oklch(0.745 0.179 57.3); /* #FE8A04, see below */
     --info: var(--wave-blue-500);
-    --info-text: oklch(0.717 0.150 250.4); /* #52A8FD, see below */
+    --info-text: oklch(0.730 0.145 250.4); /* #5AADFF, see below */
   }
 }
 
@@ -612,20 +621,22 @@
   --elevated: var(--graphite-800);
   --contrast: var(--graphite-50);
   --muted: var(--graphite-300);
-  --soft: var(--graphite-500);
+  --subtle: var(--graphite-500);
   --secondary: var(--graphite-700);
-  --contour: color-mix(in srgb, var(--graphite-50) 5%, transparent);
-  --highlight: color-mix(in srgb, var(--graphite-50) 10%, transparent);
-  --shade: color-mix(in srgb, var(--graphite-50) 15%, transparent);
+  --line: color-mix(in srgb, var(--graphite-50) 5%, transparent);
+  --edge: color-mix(in srgb, var(--graphite-50) 10%, transparent);
+  --contour: color-mix(in srgb, var(--graphite-50) 15%, transparent);
+  --highlighted: color-mix(in srgb, var(--graphite-50) 10%, transparent);
+  --neutral: color-mix(in srgb, var(--graphite-50) 15%, transparent);
   --shadow-strength: 0.045;
   --danger: var(--wave-red-500);
-  --danger-text: oklch(0.738 0.158 16.8); /* #FE7C86, see below */
+  --danger-text: oklch(0.749 0.152 16.8); /* #FF828B, see below */
   --success: var(--wave-green-500);
-  --success-text: oklch(0.700 0.155 160); /* #14BB7C, see below */
+  --success-text: oklch(0.712 0.161 160); /* #00C07E, see below */
   --warning: var(--wave-orange-500);
-  --warning-text: oklch(0.732 0.173 57.3); /* #F78711, see below */
+  --warning-text: oklch(0.745 0.179 57.3); /* #FE8A04, see below */
   --info: var(--wave-blue-500);
-  --info-text: oklch(0.717 0.150 250.4); /* #52A8FD, see below */
+  --info-text: oklch(0.730 0.145 250.4); /* #5AADFF, see below */
 }
 
 /* Graphite's status text. Its mid-tone menus need each status a touch lighter
@@ -636,19 +647,19 @@
  * palette steps. */
 @media (color-gamut: p3) {
   .graphite {
-    --danger-text: oklch(0.743 0.198 16.8);
-    --success-text: oklch(0.693 0.212 160);
-    --warning-text: oklch(0.734 0.198 57.3);
-    --info-text: oklch(0.717 0.162 250.4);
+    --danger-text: oklch(0.755 0.190 16.8);
+    --success-text: oklch(0.705 0.219 160);
+    --warning-text: oklch(0.748 0.205 57.3);
+    --info-text: oklch(0.730 0.157 250.4);
   }
 }
 
 @media (prefers-color-scheme: dark) and (color-gamut: p3) {
   :where(:root:not(.paper):not(.graphite):not(.ink)) {
-    --danger-text: oklch(0.743 0.198 16.8);
-    --success-text: oklch(0.693 0.212 160);
-    --warning-text: oklch(0.734 0.198 57.3);
-    --info-text: oklch(0.717 0.162 250.4);
+    --danger-text: oklch(0.755 0.190 16.8);
+    --success-text: oklch(0.705 0.219 160);
+    --warning-text: oklch(0.748 0.205 57.3);
+    --info-text: oklch(0.730 0.157 250.4);
   }
 }
 
@@ -664,11 +675,13 @@
   --elevated: var(--ink-800);
   --contrast: var(--ink-50);
   --muted: var(--ink-400);
-  --soft: var(--ink-600);
+  --subtle: var(--ink-600);
   --secondary: var(--ink-700);
-  --contour: color-mix(in srgb, var(--ink-50) 5%, transparent);
-  --highlight: color-mix(in srgb, var(--ink-50) 10%, transparent);
-  --shade: color-mix(in srgb, var(--ink-50) 15%, transparent);
+  --line: color-mix(in srgb, var(--ink-50) 5%, transparent);
+  --edge: color-mix(in srgb, var(--ink-50) 10%, transparent);
+  --contour: color-mix(in srgb, var(--ink-50) 15%, transparent);
+  --highlighted: color-mix(in srgb, var(--ink-50) 10%, transparent);
+  --neutral: color-mix(in srgb, var(--ink-50) 15%, transparent);
   --shadow-strength: 0.045;
   --danger: var(--wave-red-500);
   --danger-text: var(--wave-red-400);
@@ -683,7 +696,7 @@
 /* ---------------------------------------------------------------------------
  * Tailwind v4 theme mapping — maps CSS variables to Tailwind color tokens.
  * Consumers MUST include this for Tailwind classes like `bg-primary`,
- * `text-muted`, `border-contour` etc. to work.
+ * `text-muted`, `border-line` etc. to work.
  * ------------------------------------------------------------------------- */
 
 @theme inline {
@@ -692,10 +705,10 @@
   --color-surface: var(--surface);
   --color-elevated: var(--elevated);
 
-  /* Contrast / text — `contrast` (highest emphasis) → `muted` → `soft`. */
+  /* Contrast / text, strongest to faintest — `contrast` → `muted` → `subtle`. */
   --color-contrast: var(--contrast);
   --color-muted: var(--muted);
-  --color-soft: var(--soft);
+  --color-subtle: var(--subtle);
 
   /* Inverse — maps the `:root` inverse aliases to utilities. */
   --color-surface-inverse: var(--surface-inverse);
@@ -706,20 +719,27 @@
   --color-primary: var(--primary);
   --color-secondary: var(--secondary);
   --color-accent: var(--accent);
-
-  /* Form — the theme's foreground (its text colour) made translucent, at
-   * three strengths, the way a form is drawn: `contour` marks where a shape
-   * ends: hairline borders and separators. `highlight` marks where attention
-   * lands: hovered, keyboard-highlighted and open items. `shade` gives a
-   * control its body: field and track fills and outline-control borders.
-   * Every theme uses the same strengths: contour 5%, highlight 10%, shade
-   * 15% of its text colour (Graphite's and Ink's 50, Paper's 950).
-   * All three are translucent, so each reads the same on any surface beneath
-   * it, and `shade` doubles as the intense border (layout regions, control
-   * outlines). `focus` is the brand-themed ring (= primary). */
+  --color-selected: var(--selected);
+
+  /* Lines and fills — the theme's text colour made translucent (Graphite's
+   * and Ink's 50, Paper's 950), so each reads the same on any surface beneath
+   * it. Every theme uses the same strengths.
+   * Lines, one job each: `line` (5%) divides: separators, table rows,
+   * hairlines. `edge` (10%) bounds a surface: cards, dialogs, popups, toasts,
+   * always as a border (rings are kept for focus and invalid halos).
+   * `contour` (15%) outlines a control or a region: outline buttons, badges,
+   * toggles, the slider thumb, menubars.
+   * Fills, one job each: `highlighted` (10%) marks where attention lands:
+   * hovered, keyboard-highlighted and open items. `neutral` (15%) gives a
+   * control its body, its look before anything is chosen: field and track
+   * fills, unchecked boxes. (Tailwind's own `neutral-50` … `neutral-950`
+   * greys are a separate palette Wave doesn't use.) `focus` is the
+   * brand-themed ring (= primary). */
+  --color-line: var(--line);
+  --color-edge: var(--edge);
   --color-contour: var(--contour);
-  --color-highlight: var(--highlight);
-  --color-shade: var(--shade);
+  --color-highlighted: var(--highlighted);
+  --color-neutral: var(--neutral);
   --color-focus: var(--focus);
   --color-scrim: var(--scrim);
 
@@ -813,6 +833,81 @@
   }
 }
 
+/* `scroll-fade` — fades the edges of anything that scrolls, where there is
+ * more to scroll. It's a mask, so the content itself turns transparent and
+ * whatever is behind shows through: no colour to match, in any theme. Each
+ * fade grows with the first 2.5rem of scroll and shrinks over the last, so it
+ * never pops in. Two things drive it, so it works on any scroller:
+ * - the element's own scroll position, through scroll-driven animations
+ *   (Chrome, Edge, Safari 26+): a Combobox list, a plain `overflow-auto` box;
+ * - ScrollArea, which reports how far each edge is (`--scroll-area-overflow-*`),
+ *   so its viewport fades in every browser, Firefox included.
+ * A plain scroller in a browser without scroll-driven animations (Firefox,
+ * for now) simply doesn't fade. `--scroll-fade-size` sets the length, up to a
+ * quarter of the box; the horizontal fade follows the text direction. */
+@property --scroll-fade-top { syntax: "<length>"; inherits: false; initial-value: 0px; }
+@property --scroll-fade-bottom { syntax: "<length>"; inherits: false; initial-value: 0px; }
+@property --scroll-fade-start { syntax: "<length>"; inherits: false; initial-value: 0px; }
+@property --scroll-fade-end { syntax: "<length>"; inherits: false; initial-value: 0px; }
+@utility scroll-fade {
+  --scroll-fade-x: to right;
+  --scroll-fade-top: min(var(--scroll-fade-size, 2.5rem), var(--scroll-area-overflow-y-start, 0px));
+  --scroll-fade-bottom: min(var(--scroll-fade-size, 2.5rem), var(--scroll-area-overflow-y-end, 0px));
+  --scroll-fade-start: min(var(--scroll-fade-size, 2.5rem), var(--scroll-area-overflow-x-start, 0px));
+  --scroll-fade-end: min(var(--scroll-fade-size, 2.5rem), var(--scroll-area-overflow-x-end, 0px));
+  /* Controls laid over an edge (Select's scroll arrows) set
+   * `--scroll-fade-inset` to their height: the fade then starts where they
+   * end, only while that edge is fading. */
+  --scroll-fade-inset-top: min(var(--scroll-fade-inset, 0px), var(--scroll-fade-top) * 1000);
+  --scroll-fade-inset-bottom: min(var(--scroll-fade-inset, 0px), var(--scroll-fade-bottom) * 1000);
+  /* Each fade at most a quarter of the box, so a short list still keeps a
+   * row clear between its two fades. */
+  --scroll-fade-top-size: min(var(--scroll-fade-top), 25%);
+  --scroll-fade-bottom-size: min(var(--scroll-fade-bottom), 25%);
+  --scroll-fade-start-size: min(var(--scroll-fade-start), 25%);
+  --scroll-fade-end-size: min(var(--scroll-fade-end), 25%);
+  mask-image:
+    linear-gradient(to bottom, transparent var(--scroll-fade-inset-top), #000 calc(var(--scroll-fade-inset-top) + var(--scroll-fade-top-size)), #000 calc(100% - var(--scroll-fade-inset-bottom) - var(--scroll-fade-bottom-size)), transparent calc(100% - var(--scroll-fade-inset-bottom))),
+    linear-gradient(var(--scroll-fade-x), transparent, #000 var(--scroll-fade-start-size), #000 calc(100% - var(--scroll-fade-end-size)), transparent);
+  mask-composite: intersect;
+  /* What's scrolled into view (an option picked with the arrow keys) stops
+   * clear of whatever is faded at that moment, and nowhere is padded where
+   * nothing fades (Firefox's plain lists, an edge scrolled to its end). */
+  scroll-padding-block:
+    calc(var(--scroll-fade-inset-top) + var(--scroll-fade-top-size))
+    calc(var(--scroll-fade-inset-bottom) + var(--scroll-fade-bottom-size));
+  @variant rtl {
+    --scroll-fade-x: to left;
+  }
+  @supports (animation-timeline: scroll()) {
+    animation-name: scroll-fade-top, scroll-fade-bottom, scroll-fade-start, scroll-fade-end;
+    animation-timing-function: linear;
+    animation-fill-mode: both;
+    animation-timeline: scroll(self block), scroll(self block), scroll(self inline), scroll(self inline);
+    animation-range:
+      0 var(--scroll-fade-size, 2.5rem),
+      calc(100% - var(--scroll-fade-size, 2.5rem)) 100%,
+      0 var(--scroll-fade-size, 2.5rem),
+      calc(100% - var(--scroll-fade-size, 2.5rem)) 100%;
+  }
+}
+@keyframes scroll-fade-top {
+  from { --scroll-fade-top: 0px; }
+  to { --scroll-fade-top: var(--scroll-fade-size, 2.5rem); }
+}
+@keyframes scroll-fade-bottom {
+  from { --scroll-fade-bottom: var(--scroll-fade-size, 2.5rem); }
+  to { --scroll-fade-bottom: 0px; }
+}
+@keyframes scroll-fade-start {
+  from { --scroll-fade-start: 0px; }
+  to { --scroll-fade-start: var(--scroll-fade-size, 2.5rem); }
+}
+@keyframes scroll-fade-end {
+  from { --scroll-fade-end: var(--scroll-fade-size, 2.5rem); }
+  to { --scroll-fade-end: 0px; }
+}
+
 /* `motion-color` — interaction-state transition for controls: smoothly
  * animates color / background / border / ring (box-shadow) / backdrop blur on hover, focus,
  * pressed, checked, etc. Runs at the `sm` tier (controls are small + fast). A
@@ -1160,3 +1255,22 @@
   0%, 70%, 100% { opacity: 1; }
   20%, 50% { opacity: 0; }
 }
+
+/* ---------------------------------------------------------------------------
+ * SwipeDeck — the numbers each card works out its place from change every
+ * frame of a drag (the cards behind lift toward the front). Unregistered,
+ * custom properties inherit, so each change would restyle everything inside
+ * the cards in sight; registered as not inheriting, it stops at the card.
+ * Measured with heavy cards: about 2.5x less style work in Chromium, and
+ * WebKit back to 60 fps from about 30. The card's public hooks
+ * (`--swipe-deck-progress`, `-movement-x`/`-y`, `-place`, `-index`) still
+ * inherit, so what's inside a card can read them. */
+@property --swipe-deck-lift { syntax: "*"; inherits: false; }
+@property --swipe-deck-slot { syntax: "*"; inherits: false; }
+@property --swipe-deck-layout-slot { syntax: "*"; inherits: false; }
+@property --swipe-deck-layout-x { syntax: "*"; inherits: false; }
+@property --swipe-deck-layout-y { syntax: "*"; inherits: false; }
+@property --swipe-deck-layout-rotate { syntax: "*"; inherits: false; }
+@property --swipe-deck-layout-scale { syntax: "*"; inherits: false; }
+@property --swipe-deck-enter-scale { syntax: "*"; inherits: false; }
+@property --swipe-deck-pose { syntax: "*"; inherits: false; }

package/dist/swipe-deck.d.ts

@@ -1,28 +1,66 @@
 import { ButtonProps } from "./button.js";
 import * as React from "react";
 //#region src/swipe-deck.d.ts
-type SwipeDirection = "left" | "right" | "up" | "down";
+type SwipeDeckDirection = "left" | "right" | "up" | "down";
 type SwipeDeckLayout = "stack" | "fan" | "cascade" | "pile";
 interface SwipeDeckSwipeDetails {
-  /** The `value` of the card that left. */
+  /** The `value` of the card. */
   value: string;
-  /** The direction it left in. */
-  direction: SwipeDirection;
+  /** The direction it leaves in. */
+  direction: SwipeDeckDirection;
 }
+/** What sent a card off: a drag or throw, an arrow key, or a `SwipeDeckAction`. */
+type SwipeDeckSwipeEventReason = SwipeDeckSwipeCause["reason"];
+type SwipeDeckSwipeCause = {
+  reason: "swipe";
+  event: PointerEvent;
+} | {
+  reason: "keyboard";
+  event: KeyboardEvent;
+} | {
+  reason: "action-press";
+  event: MouseEvent;
+};
+/**
+ * `onSwipe`'s second argument: the reason and native event behind a swipe, and
+ * a way to cancel it. The parts of Base UI's own event details that apply.
+ */
+type SwipeDeckSwipeEventDetails = SwipeDeckSwipeCause & {
+  /**
+   * Keeps the card in front: a dragged card springs back, and a key or
+   * action does nothing.
+   */
+  cancel: () => void;
+  /** Whether `cancel` has been called. */
+  readonly isCanceled: boolean;
+};
 type SwipeDeckProps = React.ComponentProps<"div"> & {
   /**
-   * Called once a card has left the deck. Remove it from your list to discard
-   * it, or move it to the end of your list to cycle it to the back.
+   * Called the moment a card is sent off, before it leaves: count it here, or
+   * call `eventDetails.cancel()` to keep it in front. To cycle the deck, move
+   * the card to the end of your list here, and it slides back under the pile.
+   * Don't remove it here: it would vanish mid-exit, and `onSwipeComplete`
+   * would never come.
    */
-  onSwipe?: (details: SwipeDeckSwipeDetails) => void;
+  onSwipe?: (details: SwipeDeckSwipeDetails, eventDetails: SwipeDeckSwipeEventDetails) => void;
+  /**
+   * Called once a card is done leaving: faded out, or (moved to the back in
+   * `onSwipe`) on its way under the pile. Remove it from your list here; a
+   * card your list keeps comes back, in front or wherever you moved it.
+   * Return a promise, such as a save, to keep a faded card out until it
+   * settles; a card sliding under the pile is back already.
+   */
+  onSwipeComplete?: (details: SwipeDeckSwipeDetails) => void | Promise<unknown>;
   /** The directions a card can leave in. Defaults to left and right. */
-  directions?: readonly SwipeDirection[];
+  directions?: readonly SwipeDeckDirection[];
   /** Stops cards leaving by pointer, keyboard or action. */
   disabled?: boolean;
   /**
    * How the cards behind the front one sit: `stack` peeks them above it, `fan`
    * turns them out like a hand of cards, `cascade` steps them up and to the
-   * side, and `pile` scatters them. Defaults to `stack`.
+   * side, and `pile` scatters them. Defaults to `fan`. `fan` and `cascade`
+   * open toward the end of the line: right in left-to-right text, left in
+   * right-to-left.
    */
   layout?: SwipeDeckLayout;
   /** How far the cards behind spread out, from 0 (not at all) to 2. Defaults to 0.5. */
@@ -33,49 +71,67 @@ type SwipeDeckProps = React.ComponentProps<"div"> & {
   visible?: number;
 };
 type SwipeDeckItemProps = React.ComponentProps<"div"> & {
-  /** Names the card in `onSwipe`. Use the same id as its `key`. */
+  /**
+   * Names the card in `onSwipe`. Use the same id as its `key`, unique among
+   * the deck's cards, those still leaving included: a card dealt again is a
+   * new card and needs a new value.
+   */
   value: string;
 };
 type SwipeDeckEmptyProps = React.ComponentProps<"div">;
 type SwipeDeckActionProps = ButtonProps & {
   /** The direction the front card leaves in when pressed. */
-  direction: SwipeDirection;
+  direction: SwipeDeckDirection;
 };
 /**
  * A pile of cards people swipe away: drag or throw the front card, press an
  * arrow key while the deck is focused, or use a `SwipeDeckAction`. A let-go
- * card whose position and throw carry it past a quarter of its width leaves:
- * it slides out the way it is heading until clear of the stack, held by a
+ * card whose position and throw carry it past a quarter of its width (or of
+ * its height, up and down) leaves:
+ * it slides out the way it is heading until clear of the pile, held by a
  * spring that a hard throw runs out against, then fades. Short of that, it
- * springs back. Your list stays the source of truth — `onSwipe` tells you
- * which card left and which way, and you remove it or move it to the back.
+ * springs back. Pressed, a card lifts under the pointer; dragged, it tilts
+ * with the throw.
+ *
+ * Your list stays the source of truth. `onSwipe` comes the moment a card is
+ * sent off: count it there, or cancel to keep it. `onSwipeComplete` comes once
+ * it has gone: remove it from your list then, not in `onSwipe`, where removing
+ * it would cut its exit short. To cycle the deck instead, move the card to
+ * the end of your list in `onSwipe`, and it slides back under the pile. To
+ * undo a swipe, put the card back at the start of your list.
+ *
+ * The cards are the deck's own children, in your list's order. A long list
+ * needn't be rendered whole: the deck shows `visible` cards, so the next few
+ * dozen are plenty.
  *
  * End the deck with a `SwipeDeckEmpty`: it lies under the last card, so
- * dragging that card shows what comes next. The deck carries `data-empty`
- * once no card is in front (the last one leaving, or none left), for styles
- * of your own.
+ * dragging that card shows what comes next.
+ *
+ * Styling hooks: `data-layout`, `data-disabled`, and `data-empty` once no
+ * card is in front (the last one leaving, or none left). CSS variables:
+ * `--swipe-deck-card-width` / `-height`, the size of the largest card.
  *
  * Give the deck an `aria-label`. Screen readers hear the next card after each
  * swipe: its `aria-label` when it has one, otherwise all of its text.
  */
-declare function SwipeDeck({ onSwipe, directions, disabled, layout, spread, depth, visible, className, style, onKeyDown, children, ref, ...props }: SwipeDeckProps): React.JSX.Element;
+declare function SwipeDeck({ onSwipe, onSwipeComplete, directions, disabled, layout, spread, depth, visible, className, style, onKeyDown, children, ref, ...props }: SwipeDeckProps): React.JSX.Element;
 /**
- * One card in the deck. It sits in the deck's first grid cell with every other
- * card, so the deck takes the size of its largest card.
+ * One card in the deck, a direct child of it. It sits in the deck's first grid
+ * cell with every other card, so the deck takes the size of its largest card.
  *
  * Styling hooks: `data-front` on the top card, `data-swiping` while it is
- * dragged, `data-leaving` from the moment it leaves, `data-ending-style` once
- * it is clear of the stack and fading (the `motion-fade-lg` recipe), and
- * `data-swipe-direction` for the way it leans or leaves. CSS variables:
- * `--swipe-deck-index` (its place in the pile, 0 at the front),
- * `--swipe-deck-place` (that place as it springs from one to the next, less
- * the lift while the front card is dragged out, as `--swipe-deck-slot`),
+ * dragged, `data-leaving` from the moment it leaves, `data-starting-style`
+ * while it comes in and `data-ending-style` once it is clear of the pile and
+ * fading (the `motion-fade-lg` recipe), and `data-swipe-direction` for the
+ * way it leans or leaves. CSS variables, which what's inside the card can
+ * read too: `--swipe-deck-index` (its place in the pile, 0 at the front),
+ * `--swipe-deck-place` (that place as it springs from one to the next),
  * `--swipe-deck-movement-x` / `-y` in px, and `--swipe-deck-progress` from 0
  * at rest to 1 where letting go makes the card leave.
  *
- * The card owns its translate, rotate and scale, so its motion recipe can only
- * be a `motion-fade-*` one: a recipe that transitions those would lag every
- * drag.
+ * The card owns its translate, rotate, scale and transform, so its motion
+ * recipe can only be a `motion-fade-*` one: a recipe that transitions those
+ * would lag every drag.
  */
 declare function SwipeDeckItem({ value, className, style, ref, onPointerDown, onClickCapture, onDragStart, ...props }: SwipeDeckItemProps): React.JSX.Element;
 /**
@@ -84,15 +140,15 @@ declare function SwipeDeckItem({ value, className, style, ref, onPointerDown, on
  * their size, inside a dashed outline of their shape (`data-slot`
  * `swipe-deck-empty-outline`, to restyle or hide). It is drawn as soon as one
  * card is left and has come to rest, under that card, so dragging it shows
- * what comes next; it
- * can be reached (Tab, clicks) and screen readers hear it (its `aria-label`,
- * or its text) once that last card has gone too.
+ * what comes next; it can be reached (Tab, clicks) and screen readers hear it
+ * (its `aria-label`, or its text) once that last card has gone too.
  */
 declare function SwipeDeckEmpty({ className, children, ref, ...props }: SwipeDeckEmptyProps): React.JSX.Element;
 /**
  * A button that sends the front card off in `direction`: the way to swipe
- * without dragging. Disabled when the deck is empty or can't go that way.
+ * without dragging. Disabled (and still focusable) when the deck is disabled,
+ * has no card in front, or can't go that way.
  */
-declare function SwipeDeckAction({ direction, disabled, onClick, ...props }: SwipeDeckActionProps): React.JSX.Element;
+declare function SwipeDeckAction({ direction, disabled, onClick, onKeyDown, ...props }: SwipeDeckActionProps): React.JSX.Element;
 //#endregion
-export { SwipeDeck, SwipeDeckAction, type SwipeDeckActionProps, SwipeDeckEmpty, type SwipeDeckEmptyProps, SwipeDeckItem, type SwipeDeckItemProps, type SwipeDeckLayout, type SwipeDeckProps, type SwipeDeckSwipeDetails, type SwipeDirection };
+export { SwipeDeck, SwipeDeckAction, type SwipeDeckActionProps, type SwipeDeckDirection, SwipeDeckEmpty, type SwipeDeckEmptyProps, SwipeDeckItem, type SwipeDeckItemProps, type SwipeDeckLayout, type SwipeDeckProps, type SwipeDeckSwipeDetails, type SwipeDeckSwipeEventDetails, type SwipeDeckSwipeEventReason };