@waveso/ui 0.15.1 → 0.17.0

package/dist/swipe-deck.d.ts

@@ -0,0 +1,98 @@
+import { ButtonProps } from "./button.js";
+import * as React from "react";
+//#region src/swipe-deck.d.ts
+type SwipeDirection = "left" | "right" | "up" | "down";
+type SwipeDeckLayout = "stack" | "fan" | "cascade" | "pile";
+interface SwipeDeckSwipeDetails {
+  /** The `value` of the card that left. */
+  value: string;
+  /** The direction it left in. */
+  direction: SwipeDirection;
+}
+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.
+   */
+  onSwipe?: (details: SwipeDeckSwipeDetails) => void;
+  /** The directions a card can leave in. Defaults to left and right. */
+  directions?: readonly SwipeDirection[];
+  /** 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`.
+   */
+  layout?: SwipeDeckLayout;
+  /** How far the cards behind spread out, from 0 (not at all) to 2. Defaults to 0.5. */
+  spread?: number;
+  /** How much each card behind shrinks, from 0 (not at all) to 1. Defaults to 0.5. */
+  depth?: number;
+  /** How many cards show, the front one included; at least 1. Defaults to 4. */
+  visible?: number;
+};
+type SwipeDeckItemProps = React.ComponentProps<"div"> & {
+  /** Names the card in `onSwipe`. Use the same id as its `key`. */
+  value: string;
+};
+type SwipeDeckEmptyProps = React.ComponentProps<"div">;
+type SwipeDeckActionProps = ButtonProps & {
+  /** The direction the front card leaves in when pressed. */
+  direction: SwipeDirection;
+};
+/**
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * 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;
+/**
+ * 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.
+ *
+ * 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`),
+ * `--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.
+ */
+declare function SwipeDeckItem({ value, className, style, ref, onPointerDown, onClickCapture, onDragStart, ...props }: SwipeDeckItemProps): React.JSX.Element;
+/**
+ * What the deck shows once its cards run out: a message, an action (start
+ * over, carry on), anything you put in it. It sits where the cards sit, at
+ * 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.
+ */
+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.
+ */
+declare function SwipeDeckAction({ direction, disabled, onClick, ...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 };