Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(components): CardStack shows the next card whole, adds exits and a fan

okanasld756fae3e4f7
diff --git a/packages/components/src/card-stack/index.test.ts b/packages/components/src/card-stack/index.test.ts
index 11dcd6ba..ed21bdc5 100644
--- a/packages/components/src/card-stack/index.test.ts
+++ b/packages/components/src/card-stack/index.test.ts
@@ -74,4 +74,63 @@ describe("CardStack", () => {
);
expect(st.cues.changes.map((c) => c.index)).toEqual([1, 2, 3]);
});
+
+ it("shows the next card whole as soon as the front one starts leaving", () => {
+ const st = make()({ id: "s", cards, every: 40, tilt: false });
+ const clip = find(st, "s-card-1-clip");
+ const strip = valueAt(clip, "height", 0) as number;
+ expect(strip).toBeLessThan(60);
+ // Whole (the card's height) from the frame after the move starts.
+ expect(valueAt(clip, "height", 41)).toBe(400);
+ expect(valueAt(clip, "height", 60)).toBe(400);
+ });
+
+ it("leaves by flying, dropping, zooming or flipping", () => {
+ const at = (leave: "fly" | "drop" | "zoom" | "flip", prop: string) => {
+ const st = make()({ id: "s", cards, every: 40, tilt: false, leave });
+ const card = find(st, "s-card-0");
+ const y0 = valueAt(card, prop, 0) as number;
+ const keys =
+ card?.animation?.tracks.find((t) => t.prop === prop)?.keyframes ?? [];
+ // The furthest it gets from rest during its exit.
+ return Math.max(
+ ...keys
+ .filter((k) => k.frame > 40 && k.frame < 80)
+ .map((k) => k.value - y0),
+ );
+ };
+ expect(at("drop", "y")).toBeGreaterThan(100);
+ expect(at("zoom", "scale")).toBeGreaterThan(0.15);
+ expect(at("flip", "rotateX")).toBeGreaterThan(80);
+ expect(at("fly", "x")).toBeLessThanOrEqual(0); // flies left
+ });
+
+ it("fans out into a hand and gathers again", () => {
+ const st = make()({ id: "s", cards, mode: "fan", every: 40, tilt: false });
+ expect(st.cues.changes.map((c) => c.frame)).toEqual([40, 80]);
+ const spread = 75;
+ const xs = cards.map(
+ (_, c) => valueAt(find(st, `s-card-${c}`), "x", spread) as number,
+ );
+ for (let c = 1; c < xs.length; c++)
+ expect(xs[c]).toBeGreaterThan(xs[c - 1] as number);
+ const rot = (c: number, f: number) =>
+ valueAt(find(st, `s-card-${c}`), "rotation", f) as number;
+ expect(rot(0, spread)).toBeLessThan(0);
+ expect(rot(3, spread)).toBeGreaterThan(0);
+ // Every card shows in the fan, even past `visible`.
+ const many = make()({
+ id: "m",
+ cards: [...cards, ...cards],
+ mode: "fan",
+ every: 40,
+ visible: 2,
+ });
+ expect(valueAt(find(many, "m-card-7"), "opacity", 79)).toBe(1);
+ // Gathered: back to the stack.
+ expect(valueAt(find(st, "s-card-2"), "x", 200)).toBe(
+ valueAt(find(st, "s-card-2"), "x", 0) ?? xs[2],
+ );
+ expect(rot(3, 200)).toBe(0);
+ });
});
diff --git a/packages/components/src/card-stack/index.ts b/packages/components/src/card-stack/index.ts
index f9c8f30b..79175365 100644
--- a/packages/components/src/card-stack/index.ts
+++ b/packages/components/src/card-stack/index.ts
@@ -1,13 +1,16 @@
/**
* CardStack: cards in a depth stack that shuffle. In `cycle` the front card
- * flies off and returns to the back while the rest step forward; in `deal`
- * cards land one at a time on top of the pile.
+ * leaves (flies, drops, zooms or flips away) and returns to the back while
+ * the rest step forward; in `deal` cards land one at a time on top of the
+ * pile; in `fan` the stack spreads into a hand and gathers again.
*
* Draw order is fixed by the tree (the renderer has no animated z-order), so
* in `cycle` every card sits in a clip that shows only the strip peeking out
* above the card in front of it: whichever card is drawn later, a card
* behind can never paint over one in front. The leaving card flies sideways,
- * clear of the stack, before it slots in at the back.
+ * clear of the stack, before it slots in at the back. The card coming to the
+ * front shows whole at once: everything drawn after it is either the card
+ * leaving (in front of it anyway) or a card already clipped at the back.
*/
import {
type KeyframeTuple,
@@ -52,13 +55,18 @@ export const cardStack = /* @__PURE__ */ defineComponent({
]),
)
.min(2),
- mode: z.enum(["cycle", "deal"]).default("cycle"),
+ mode: z.enum(["cycle", "deal", "fan"]).default("cycle"),
/** Frames between moves. Default 1.5 seconds. */
every: z.number().int().positive().optional(),
cycles: z.number().int().positive().default(1),
/** Cards shown behind the front one. */
visible: z.number().int().min(0).max(8).default(3),
+ /** How the front card leaves in `cycle`. */
+ leave: z.enum(["fly", "drop", "zoom", "flip"]).default("fly"),
+ /** Where `fly` sends the card, and which way `drop` tips it. */
flyTo: z.enum(["up", "left", "right"]).default("left"),
+ /** Degrees between neighbouring cards in `fan`. */
+ fanAngle: z.number().min(0).max(30).default(8),
cardWidth: z.number().positive().optional(),
cardHeight: z.number().positive().optional(),
tilt: z
@@ -86,7 +94,15 @@ export const cardStack = /* @__PURE__ */ defineComponent({
const ease = theme.motion.ease.move;
const step = 26 * s;
const depth = Math.min(props.visible, n - 1);
- const W = ctx.requested.width ?? cw * 1.5;
+ const fan = props.mode === "fan";
+ // In a fan, cards shrink a little and overlap by this much of their width.
+ const fanScale = 0.82;
+ const fanStep = cw * fanScale * 0.42;
+ const W =
+ ctx.requested.width ??
+ (fan
+ ? Math.max(cw * 1.5, cw * fanScale + fanStep * (n - 1) + cw * 0.3)
+ : cw * 1.5);
const H = ctx.requested.height ?? ch + step * depth + ch * 0.4;
const front = { x: (W - cw) / 2, y: H - ch - ch * 0.2 };
const pose = (k: number) => {
@@ -103,19 +119,66 @@ export const cardStack = /* @__PURE__ */ defineComponent({
// ── Timeline: each card's slot at each move ──────────────────────
const cycle = props.mode === "cycle";
- const moves = cycle ? n * props.cycles : n - 1;
+ const deal = props.mode === "deal";
+ // A fan spreads and gathers once per cycle.
+ const moves = cycle ? n * props.cycles : fan ? 2 * props.cycles : n - 1;
const changes = Array.from({ length: moves }, (_, m) => ({
frame: (m + 1) * every,
- index: cycle ? (m + 1) % n : m + 1,
+ index: cycle ? (m + 1) % n : fan ? 0 : m + 1,
}));
- const fly =
- props.flyTo === "up"
- ? { x: 0, y: -ch * 1.3, rotation: -4 }
- : {
- x: (props.flyTo === "left" ? -1 : 1) * cw * 1.1,
- y: -ch * 0.15,
- rotation: props.flyTo === "left" ? -10 : 10,
- };
+ const side = props.flyTo === "right" ? 1 : -1;
+ // Where the leaving card ends (relative to the front slot), how, and
+ // how much of the move it takes.
+ const leave: {
+ to: Partial<Record<"x" | "y" | "rotation" | "rotateX" | "scale", number>>;
+ ease: string;
+ share: number;
+ /** Share of its exit it stays opaque, so the next card doesn't ghost through. */
+ solid: number;
+ } = {
+ fly: {
+ to:
+ props.flyTo === "up"
+ ? { y: -ch * 1.3, rotation: -4 }
+ : { x: side * cw * 1.1, y: -ch * 0.15, rotation: side * 10 },
+ ease: "power2.in",
+ share: 0.55,
+ solid: 0.5,
+ },
+ // Falls out of the bottom, tipping toward `flyTo`.
+ drop: {
+ to: { x: side * cw * 0.12, y: ch * 1.1, rotation: side * 14 },
+ ease: "power2.in",
+ share: 0.6,
+ solid: 0.55,
+ },
+ // Toward the viewer, fading as it passes.
+ zoom: {
+ to: { y: ch * 0.06, scale: 1.22 },
+ ease: "power2.out",
+ share: 0.45,
+ solid: 0,
+ },
+ // Folds back over its top edge.
+ flip: {
+ to: { y: -ch * 0.04, rotateX: 90, scale: 0.96 },
+ ease: "sine.in",
+ share: 0.55,
+ solid: 0.9,
+ },
+ }[props.leave];
+ // The fan: an arc, centred, outer cards turned and lowered.
+ const fanPose = (c: number) => {
+ const off = c - (n - 1) / 2;
+ return {
+ x: front.x + off * fanStep,
+ y: front.y + ch * 0.06 + Math.abs(off) ** 2 * ch * 0.02,
+ rotation: off * props.fanAngle,
+ scale: fanScale,
+ dim: 0,
+ opacity: 1,
+ };
+ };
const parts: Record<string, Animatable<LayoutNode>> = {};
const nodes: LayoutNode[] = [];
@@ -125,6 +188,7 @@ export const cardStack = /* @__PURE__ */ defineComponent({
y: [] as KeyframeTuple[],
scale: [] as KeyframeTuple[],
rotation: [] as KeyframeTuple[],
+ rotateX: [] as KeyframeTuple[],
opacity: [] as KeyframeTuple[],
dim: [] as KeyframeTuple[],
clip: [] as KeyframeTuple[],
@@ -141,6 +205,7 @@ export const cardStack = /* @__PURE__ */ defineComponent({
y: p.y,
scale: p.scale,
rotation: 0,
+ rotateX: 0,
opacity: p.opacity,
dim: p.dim,
clip: p.clip,
@@ -154,23 +219,42 @@ export const cardStack = /* @__PURE__ */ defineComponent({
changes.forEach(({ frame: t }, m) => {
const k = (((c - m) % n) + n) % n;
if (k === 0) {
- // Leaves: flies clear, then slots in at the back unseen and fades up.
- const away = t + Math.round(tr * 0.55);
+ // Leaves, then slots in at the back unseen and fades up.
+ const away = t + Math.round(tr * leave.share);
+ const to = leave.to;
put(t, 0);
- put(away, 0, "power2.in", {
- x: front.x + fly.x,
- y: front.y + fly.y,
- rotation: fly.rotation,
+ const solid = t + Math.round((away - t) * leave.solid);
+ if (solid > t) tracks.opacity.push([solid, 1]);
+ put(away, 0, leave.ease, {
+ x: front.x + (to.x ?? 0),
+ y: front.y + (to.y ?? 0),
+ rotation: to.rotation ?? 0,
+ rotateX: to.rotateX ?? 0,
+ scale: to.scale ?? 1,
opacity: 0,
});
put(away + 1, n - 1, "hold", { opacity: 0 });
put(t + tr, n - 1, "power2.out");
} else {
- // Steps forward once the leaving card is half way out.
- put(t + Math.round(tr * 0.3), k);
+ // Steps forward once the leaving card is under way. Coming to
+ // the front, it shows whole from the start.
+ const whole = k === 1 ? { clip: ch } : undefined;
+ put(t, k);
+ if (whole) tracks.clip.push([t + 1, ch, "hold"]);
+ put(t + Math.round(tr * 0.25), k, undefined, whole);
put(t + tr, k - 1, ease);
}
});
+ } else if (fan) {
+ put(0, c);
+ changes.forEach(({ frame: t }, m) => {
+ // Spreads on even moves, gathers on odd ones, the front card first.
+ const at = t + c * Math.round(fps * 0.04);
+ const spread = m % 2 === 0;
+ put(at, c, undefined, spread ? undefined : fanPose(c));
+ if (spread) put(at + tr, c, theme.motion.ease.snap, fanPose(c));
+ else put(at + tr, c, ease);
+ });
} else {
// Deal: card c lands on top at move c (card 0 is already down).
const landAt = c === 0 ? 0 : (changes[c - 1]?.frame as number);
@@ -239,6 +323,8 @@ export const cardStack = /* @__PURE__ */ defineComponent({
anim.keys("x", ascending(tracks.x));
if (tracks.rotation.some((k) => k[1] !== 0))
anim.keys("rotation", ascending(tracks.rotation));
+ if (tracks.rotateX.some((k) => k[1] !== 0))
+ anim.keys("rotateX", ascending(tracks.rotateX));
node.animate(anim);
host.style(node, {
dropShadow: {
@@ -253,8 +339,9 @@ export const cardStack = /* @__PURE__ */ defineComponent({
parts[`card-${c}-clip`] = clip;
nodes.push(node);
});
- // Front-most last: cycle starts with card 0 in front, deal ends with the last on top.
- const ordered = cycle ? [...nodes].reverse() : nodes;
+ // Front-most last: cycle and fan start with card 0 in front, deal ends
+ // with the last on top.
+ const ordered = deal ? nodes : [...nodes].reverse();
const children = props.tilt
? [
host.box({
diff --git a/packages/components/src/card-stack/meta.ts b/packages/components/src/card-stack/meta.ts
index 33e1b106..65cc6e26 100644
--- a/packages/components/src/card-stack/meta.ts
+++ b/packages/components/src/card-stack/meta.ts
@@ -3,12 +3,13 @@ import { defineMeta } from "../core/meta.js";
export default defineMeta({
name: "CardStack",
summary:
- "Cards in a depth stack that shuffle: the front card flies off and returns to the back, or cards are dealt onto the pile.",
+ "Cards in a depth stack that shuffle: the front card flies, drops, zooms or flips away and returns to the back; cards are dealt onto the pile; or the stack fans out into a hand.",
tags: [
"cards",
"stack",
"deck",
"carousel",
+ "fan",
"testimonials",
"features",
"3d",