@seekalfred/primitives 0.5.1 → 0.7.1

package/dist/card/card.js

@@ -1,7 +1,7 @@
 "use client";
-import { cn } from "../lib/cn.js";
+import { cn, cnAll } from "../lib/cn.js";
 import { cva } from "class-variance-authority";
-import { forwardRef } from "react";
+import { forwardRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/card/card.tsx
 /**
@@ -34,7 +34,7 @@ import { jsx } from "react/jsx-runtime";
 */
 const cardVariants = cva([
 	"flex flex-col gap-6",
-	"rounded-xl border-(length:--border-width) border-border py-6",
+	"rounded-panel border-(length:--border-width) border-border py-6",
 	"bg-card text-card-foreground shadow-surface",
 	"box-border font-sans"
 ]);
@@ -50,12 +50,23 @@ const cardTitleVariants = cva(["text-base leading-(--leading-none) font-semibold
 const cardDescriptionVariants = cva(["text-sm leading-(--leading-normal) text-muted-foreground"]);
 const cardContentVariants = cva("px-6");
 const cardFooterVariants = cva("flex items-center px-6");
-const Card = forwardRef(function Card({ className, ...props }, ref) {
+const Card = forwardRef(function Card({ className, interactive = false, onPointerEnter, onPointerLeave, ...props }, ref) {
+	const [pointed, setPointed] = useState(false);
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		...props,
 		"data-slot": "card",
-		className: cn(cardVariants(), className)
+		"data-interactive": interactive || void 0,
+		"data-pointed": interactive && pointed || void 0,
+		onPointerEnter: (event) => {
+			onPointerEnter?.(event);
+			if (interactive && event.pointerType !== "touch") setPointed(true);
+		},
+		onPointerLeave: (event) => {
+			onPointerLeave?.(event);
+			setPointed(false);
+		},
+		className: cnAll(cardVariants(), interactive && "card-lift", className)
 	});
 });
 const CardHeader = forwardRef(function CardHeader({ className, ...props }, ref) {

package/dist/card/card.js.map

@@ -1 +1 @@
-{"version":3,"file":"card.js","names":[],"sources":["../../src/card/card.tsx"],"sourcesContent":["\"use client\";\n\nimport { cva } from \"class-variance-authority\";\nimport { forwardRef, type ComponentPropsWithoutRef } from \"react\";\n\nimport { cn } from \"../lib/cn.js\";\n\n/**\n * Card, ported from the legacy shadcn component.\n *\n * Presentational, so there is no React Aria base -- React Aria ships no card,\n * and a container that is not focusable, selectable or interactive needs no\n * behaviour to inherit.\n *\n * Five parts, from six. The census (24 consumer files, the most-used\n * container in the app) reads: Card 55, CardContent 40, CardHeader 21,\n * CardTitle 19, CardDescription 8, CardFooter 2, **CardAction 0**.\n *\n * Dropping `CardAction` takes three things with it, which is most of the\n * legacy header's complexity: the `grid`, the `grid-rows-[auto_auto]`, and\n * the `has-data-[slot=card-action]:grid-cols-[1fr_auto]` rule that existed\n * only to reserve a column for it. With no action to place, a header is a\n * stack.\n *\n * Two more legacy rules are gone. `[.border-b]:pb-6` and `[.border-t]:pt-6`\n * added padding when the CONSUMER happened to add a border class -- clever,\n * but action at a distance through a class name we do not own, and the census\n * found zero application call sites relying on it (one call site passes\n * `border-b-0`, which removes a border it never had). `@container/card-header`\n * named a container nothing queried.\n *\n * Every string in the cva blocks below is a STATIC literal. Tailwind scans\n * source text, so a class assembled at runtime is invisible to it and would\n * simply never be emitted.\n */\nexport const cardVariants = cva([\n  \"flex flex-col gap-6\",\n  \"rounded-xl border-(length:--border-width) border-border py-6\",\n  \"bg-card text-card-foreground shadow-surface\",\n\n  // box-border and font-sans are not boilerplate. The reset in\n  // @seekalfred/styles is OPT-IN, so a consumer may load none: content-box\n  // would add the padding to any width they set (the Alert shipped\n  // overflowing its container by 46px), and an unstyled document renders\n  // text in a serif (the Accordion shipped its panel that way). Declaring\n  // the family HERE rather than on each part means one declaration covers\n  // the whole subtree by inheritance.\n  \"box-border font-sans\",\n]);\n\n/**\n * Padding is inline-only on the sections and block-only on the shell.\n *\n * That split is load-bearing rather than stylistic: it is what lets a\n * consumer run a divider or a full-bleed image edge to edge, which a single\n * `p-6` on the shell would make impossible.\n */\nexport const cardHeaderVariants = cva(\"flex flex-col gap-1.5 px-6\");\n\nexport const cardTitleVariants = cva([\n  // leading-* AFTER text-*: tailwind-merge treats a later text-* as owning\n  // line-height and silently strips a leading-* that precedes it.\n  \"text-base leading-(--leading-none) font-semibold\",\n  // The user-agent <h3> ships a 1em block margin and font-size 1.17em. The\n  // legacy component was a <div> and never met either.\n  \"m-0\",\n]);\n\nexport const cardDescriptionVariants = cva([\n  \"text-sm leading-(--leading-normal) text-muted-foreground\",\n]);\n\nexport const cardContentVariants = cva(\"px-6\");\n\nexport const cardFooterVariants = cva(\"flex items-center px-6\");\n\n/**\n * A content container.\n *\n * @example\n * <Card>\n *   <CardHeader>\n *     <CardTitle>Learning Progress</CardTitle>\n *     <CardDescription>Across all active courses.</CardDescription>\n *   </CardHeader>\n *   <CardContent>Twelve of eighteen modules complete.</CardContent>\n * </Card>\n */\nexport type CardProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const Card = forwardRef<HTMLDivElement, CardProps>(function Card(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div ref={ref} {...props} data-slot=\"card\" className={cn(cardVariants(), className)} />\n  );\n});\n\n/** Title and description, stacked. */\nexport type CardHeaderProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(function CardHeader(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-header\"\n      className={cn(cardHeaderVariants(), className)}\n    />\n  );\n});\n\n/**\n * The card's heading.\n *\n * A REAL heading, unlike the legacy `<div class=\"font-semibold\">`. None of\n * the 19 legacy call sites wrapped one, so 19 card titles were invisible to\n * screen-reader heading navigation -- the same shape of finding as the Avatar\n * port's missing `alt`, and the migration is when it gets answered.\n */\nexport interface CardTitleProps extends ComponentPropsWithoutRef<\"h3\"> {\n  /**\n   * Heading level.\n   *\n   * `3` by default, because a card almost always sits under a section\n   * heading. It is a prop rather than a constant because the correct level\n   * is a fact about the PAGE, and a fixed one would be wrong somewhere; the\n   * level changes semantics only, never the rendered size.\n   *\n   * @default 3\n   */\n  level?: 1 | 2 | 3 | 4 | 5 | 6;\n}\n\nexport const CardTitle = forwardRef<HTMLHeadingElement, CardTitleProps>(function CardTitle(\n  { className, level = 3, ...props },\n  ref,\n) {\n  // Static union, not a template literal: `h${level}` is a string React\n  // accepts but TypeScript cannot narrow to an intrinsic element, and the\n  // cast that silences it would also accept `h7`.\n  const Heading = ({ 1: \"h1\", 2: \"h2\", 3: \"h3\", 4: \"h4\", 5: \"h5\", 6: \"h6\" } as const)[level];\n\n  return (\n    <Heading\n      ref={ref}\n      {...props}\n      data-slot=\"card-title\"\n      className={cn(cardTitleVariants(), className)}\n    />\n  );\n});\n\n/** Secondary text under the title. */\nexport type CardDescriptionProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardDescription = forwardRef<HTMLDivElement, CardDescriptionProps>(\n  function CardDescription({ className, ...props }, ref) {\n    return (\n      <div\n        ref={ref}\n        {...props}\n        data-slot=\"card-description\"\n        className={cn(cardDescriptionVariants(), className)}\n      />\n    );\n  },\n);\n\n/** The card's body. */\nexport type CardContentProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardContent = forwardRef<HTMLDivElement, CardContentProps>(function CardContent(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-content\"\n      className={cn(cardContentVariants(), className)}\n    />\n  );\n});\n\n/** Actions or metadata at the foot of the card. */\nexport type CardFooterProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(function CardFooter(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-footer\"\n      className={cn(cardFooterVariants(), className)}\n    />\n  );\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,eAAe,IAAI;CAC9B;CACA;CACA;CASA;AACF,CAAC;;;;;;;;AASD,MAAa,qBAAqB,IAAI,4BAA4B;AAElE,MAAa,oBAAoB,IAAI,CAGnC,oDAGA,KACF,CAAC;AAED,MAAa,0BAA0B,IAAI,CACzC,0DACF,CAAC;AAED,MAAa,sBAAsB,IAAI,MAAM;AAE7C,MAAa,qBAAqB,IAAI,wBAAwB;AAgB9D,MAAa,OAAO,WAAsC,SAAS,KACjE,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EAAU;EAAK,GAAI;EAAO,aAAU;EAAO,WAAW,GAAG,aAAa,GAAG,SAAS;CAAI,CAAA;AAE1F,CAAC;AAKD,MAAa,aAAa,WAA4C,SAAS,WAC7E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,mBAAmB,GAAG,SAAS;CAC9C,CAAA;AAEL,CAAC;AAwBD,MAAa,YAAY,WAA+C,SAAS,UAC/E,EAAE,WAAW,QAAQ,GAAG,GAAG,SAC3B,KACA;CAIA,MAAM,UAAW;EAAE,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;CAAK,EAAY;CAEpF,OACE,oBAAC,SAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,kBAAkB,GAAG,SAAS;CAC7C,CAAA;AAEL,CAAC;AAKD,MAAa,kBAAkB,WAC7B,SAAS,gBAAgB,EAAE,WAAW,GAAG,SAAS,KAAK;CACrD,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,wBAAwB,GAAG,SAAS;CACnD,CAAA;AAEL,CACF;AAKA,MAAa,cAAc,WAA6C,SAAS,YAC/E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,oBAAoB,GAAG,SAAS;CAC/C,CAAA;AAEL,CAAC;AAKD,MAAa,aAAa,WAA4C,SAAS,WAC7E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,mBAAmB,GAAG,SAAS;CAC9C,CAAA;AAEL,CAAC"}
+{"version":3,"file":"card.js","names":[],"sources":["../../src/card/card.tsx"],"sourcesContent":["\"use client\";\n\nimport { cva } from \"class-variance-authority\";\nimport { forwardRef, useState, type ComponentPropsWithoutRef } from \"react\";\n\nimport { cn, cnAll } from \"../lib/cn.js\";\n\n/**\n * Card, ported from the legacy shadcn component.\n *\n * Presentational, so there is no React Aria base -- React Aria ships no card,\n * and a container that is not focusable, selectable or interactive needs no\n * behaviour to inherit.\n *\n * Five parts, from six. The census (24 consumer files, the most-used\n * container in the app) reads: Card 55, CardContent 40, CardHeader 21,\n * CardTitle 19, CardDescription 8, CardFooter 2, **CardAction 0**.\n *\n * Dropping `CardAction` takes three things with it, which is most of the\n * legacy header's complexity: the `grid`, the `grid-rows-[auto_auto]`, and\n * the `has-data-[slot=card-action]:grid-cols-[1fr_auto]` rule that existed\n * only to reserve a column for it. With no action to place, a header is a\n * stack.\n *\n * Two more legacy rules are gone. `[.border-b]:pb-6` and `[.border-t]:pt-6`\n * added padding when the CONSUMER happened to add a border class -- clever,\n * but action at a distance through a class name we do not own, and the census\n * found zero application call sites relying on it (one call site passes\n * `border-b-0`, which removes a border it never had). `@container/card-header`\n * named a container nothing queried.\n *\n * Every string in the cva blocks below is a STATIC literal. Tailwind scans\n * source text, so a class assembled at runtime is invisible to it and would\n * simply never be emitted.\n */\nexport const cardVariants = cva([\n  \"flex flex-col gap-6\",\n  \"rounded-panel border-(length:--border-width) border-border py-6\",\n  \"bg-card text-card-foreground shadow-surface\",\n\n  // box-border and font-sans are not boilerplate. The reset in\n  // @seekalfred/styles is OPT-IN, so a consumer may load none: content-box\n  // would add the padding to any width they set (the Alert shipped\n  // overflowing its container by 46px), and an unstyled document renders\n  // text in a serif (the Accordion shipped its panel that way). Declaring\n  // the family HERE rather than on each part means one declaration covers\n  // the whole subtree by inheritance.\n  \"box-border font-sans\",\n]);\n\n/**\n * Padding is inline-only on the sections and block-only on the shell.\n *\n * That split is load-bearing rather than stylistic: it is what lets a\n * consumer run a divider or a full-bleed image edge to edge, which a single\n * `p-6` on the shell would make impossible.\n */\nexport const cardHeaderVariants = cva(\"flex flex-col gap-1.5 px-6\");\n\nexport const cardTitleVariants = cva([\n  // leading-* AFTER text-*: tailwind-merge treats a later text-* as owning\n  // line-height and silently strips a leading-* that precedes it.\n  \"text-base leading-(--leading-none) font-semibold\",\n  // The user-agent <h3> ships a 1em block margin and font-size 1.17em. The\n  // legacy component was a <div> and never met either.\n  \"m-0\",\n]);\n\nexport const cardDescriptionVariants = cva([\n  \"text-sm leading-(--leading-normal) text-muted-foreground\",\n]);\n\nexport const cardContentVariants = cva(\"px-6\");\n\nexport const cardFooterVariants = cva(\"flex items-center px-6\");\n\n/**\n * A content container.\n *\n * @example\n * <Card>\n *   <CardHeader>\n *     <CardTitle>Learning Progress</CardTitle>\n *     <CardDescription>Across all active courses.</CardDescription>\n *   </CardHeader>\n *   <CardContent>Twelve of eighteen modules complete.</CardContent>\n * </Card>\n */\nexport interface CardProps extends ComponentPropsWithoutRef<\"div\"> {\n  /**\n   * Make the card respond to a pointer: it floats 2px on a spring while it is pointed\n   * at, its border darkens and its shadow deepens. Mouse and pen only; touch never lifts.\n   * Leave it off for a card that is not a target: a static card should not move.\n   */\n  interactive?: boolean;\n}\n\nexport const Card = forwardRef<HTMLDivElement, CardProps>(function Card(\n  { className, interactive = false, onPointerEnter, onPointerLeave, ...props },\n  ref,\n) {\n  // Pointed at by a mouse or pen. Touch never lifts, so it is read from the pointer, not :hover (which a tap leaves stuck).\n  const [pointed, setPointed] = useState(false);\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card\"\n      data-interactive={interactive || undefined}\n      data-pointed={(interactive && pointed) || undefined}\n      onPointerEnter={(event) => {\n        onPointerEnter?.(event);\n        if (interactive && event.pointerType !== \"touch\") setPointed(true);\n      }}\n      onPointerLeave={(event) => {\n        onPointerLeave?.(event);\n        setPointed(false);\n      }}\n      className={cnAll(cardVariants(), interactive && \"card-lift\", className)}\n    />\n  );\n});\n\n/** Title and description, stacked. */\nexport type CardHeaderProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(function CardHeader(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-header\"\n      className={cn(cardHeaderVariants(), className)}\n    />\n  );\n});\n\n/**\n * The card's heading.\n *\n * A REAL heading, unlike the legacy `<div class=\"font-semibold\">`. None of\n * the 19 legacy call sites wrapped one, so 19 card titles were invisible to\n * screen-reader heading navigation -- the same shape of finding as the Avatar\n * port's missing `alt`, and the migration is when it gets answered.\n */\nexport interface CardTitleProps extends ComponentPropsWithoutRef<\"h3\"> {\n  /**\n   * Heading level.\n   *\n   * `3` by default, because a card almost always sits under a section\n   * heading. It is a prop rather than a constant because the correct level\n   * is a fact about the PAGE, and a fixed one would be wrong somewhere; the\n   * level changes semantics only, never the rendered size.\n   *\n   * @default 3\n   */\n  level?: 1 | 2 | 3 | 4 | 5 | 6;\n}\n\nexport const CardTitle = forwardRef<HTMLHeadingElement, CardTitleProps>(function CardTitle(\n  { className, level = 3, ...props },\n  ref,\n) {\n  // Static union, not a template literal: `h${level}` is a string React\n  // accepts but TypeScript cannot narrow to an intrinsic element, and the\n  // cast that silences it would also accept `h7`.\n  const Heading = ({ 1: \"h1\", 2: \"h2\", 3: \"h3\", 4: \"h4\", 5: \"h5\", 6: \"h6\" } as const)[level];\n\n  return (\n    <Heading\n      ref={ref}\n      {...props}\n      data-slot=\"card-title\"\n      className={cn(cardTitleVariants(), className)}\n    />\n  );\n});\n\n/** Secondary text under the title. */\nexport type CardDescriptionProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardDescription = forwardRef<HTMLDivElement, CardDescriptionProps>(\n  function CardDescription({ className, ...props }, ref) {\n    return (\n      <div\n        ref={ref}\n        {...props}\n        data-slot=\"card-description\"\n        className={cn(cardDescriptionVariants(), className)}\n      />\n    );\n  },\n);\n\n/** The card's body. */\nexport type CardContentProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardContent = forwardRef<HTMLDivElement, CardContentProps>(function CardContent(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-content\"\n      className={cn(cardContentVariants(), className)}\n    />\n  );\n});\n\n/** Actions or metadata at the foot of the card. */\nexport type CardFooterProps = ComponentPropsWithoutRef<\"div\">;\n\nexport const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(function CardFooter(\n  { className, ...props },\n  ref,\n) {\n  return (\n    <div\n      ref={ref}\n      {...props}\n      data-slot=\"card-footer\"\n      className={cn(cardFooterVariants(), className)}\n    />\n  );\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,eAAe,IAAI;CAC9B;CACA;CACA;CASA;AACF,CAAC;;;;;;;;AASD,MAAa,qBAAqB,IAAI,4BAA4B;AAElE,MAAa,oBAAoB,IAAI,CAGnC,oDAGA,KACF,CAAC;AAED,MAAa,0BAA0B,IAAI,CACzC,0DACF,CAAC;AAED,MAAa,sBAAsB,IAAI,MAAM;AAE7C,MAAa,qBAAqB,IAAI,wBAAwB;AAuB9D,MAAa,OAAO,WAAsC,SAAS,KACjE,EAAE,WAAW,cAAc,OAAO,gBAAgB,gBAAgB,GAAG,SACrE,KACA;CAEA,MAAM,CAAC,SAAS,cAAc,SAAS,KAAK;CAC5C,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,oBAAkB,eAAe,KAAA;EACjC,gBAAe,eAAe,WAAY,KAAA;EAC1C,iBAAiB,UAAU;GACzB,iBAAiB,KAAK;GACtB,IAAI,eAAe,MAAM,gBAAgB,SAAS,WAAW,IAAI;EACnE;EACA,iBAAiB,UAAU;GACzB,iBAAiB,KAAK;GACtB,WAAW,KAAK;EAClB;EACA,WAAW,MAAM,aAAa,GAAG,eAAe,aAAa,SAAS;CACvE,CAAA;AAEL,CAAC;AAKD,MAAa,aAAa,WAA4C,SAAS,WAC7E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,mBAAmB,GAAG,SAAS;CAC9C,CAAA;AAEL,CAAC;AAwBD,MAAa,YAAY,WAA+C,SAAS,UAC/E,EAAE,WAAW,QAAQ,GAAG,GAAG,SAC3B,KACA;CAIA,MAAM,UAAW;EAAE,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;EAAM,GAAG;CAAK,EAAY;CAEpF,OACE,oBAAC,SAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,kBAAkB,GAAG,SAAS;CAC7C,CAAA;AAEL,CAAC;AAKD,MAAa,kBAAkB,WAC7B,SAAS,gBAAgB,EAAE,WAAW,GAAG,SAAS,KAAK;CACrD,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,wBAAwB,GAAG,SAAS;CACnD,CAAA;AAEL,CACF;AAKA,MAAa,cAAc,WAA6C,SAAS,YAC/E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,oBAAoB,GAAG,SAAS;CAC/C,CAAA;AAEL,CAAC;AAKD,MAAa,aAAa,WAA4C,SAAS,WAC7E,EAAE,WAAW,GAAG,SAChB,KACA;CACA,OACE,oBAAC,OAAD;EACO;EACL,GAAI;EACJ,aAAU;EACV,WAAW,GAAG,mBAAmB,GAAG,SAAS;CAC9C,CAAA;AAEL,CAAC"}

package/dist/card-stack/card-stack.d.ts

@@ -0,0 +1,54 @@
+import { ReactNode } from "react";
+//#region src/card-stack/card-stack.d.ts
+export type CardDecision = "left" | "right";
+/**
+ * CardStack: a deck of cards reviewed one at a time. Drag or flick the top card
+ * left or right, or use the buttons and the arrow keys. The cards behind peek
+ * out below it and rise as it leaves; a card in the hand tips the way it is
+ * moving and shows a stamp (the action it will take); let go early and it springs
+ * home, let go far enough, or fast enough, and it is thrown. Undo brings the
+ * last card back from where it left, and Start over deals the deck again.
+ *
+ * Use it for quick triage where each item deserves a moment of attention:
+ * shortlisting destinations, candidates or design options. Use a list or a
+ * table when people need to compare items side by side.
+ *
+ * Keyboard: the stack takes one tab stop; Left and Right decide the top card,
+ * Backspace (or Ctrl or Cmd with Z) undoes. Every decision is announced politely
+ * and the buttons do the same, so nothing needs a drag. Reduced motion fades the
+ * card out and back instead of throwing it.
+ */
+export interface CardStackProps<T> {
+  items: T[];
+  /** A stable key for an item. */
+  getKey: (item: T) => string;
+  /** A short name for the card, used in its accessible label and announcements, such as "Lisbon". */
+  getLabel: (item: T) => string;
+  /** The card's content. It fills the card, whose size the stack sets. */
+  renderCard: (item: T) => ReactNode;
+  /** Called when a card is decided. */
+  onDecide?: (item: T, decision: CardDecision) => void;
+  /** Called when a decision is undone. */
+  onUndo?: (item: T, decision: CardDecision) => void;
+  /** Called when the deck is dealt again. */
+  onReset?: () => void;
+  /** Action names for each side, used on the buttons and the stamps that appear while dragging. @default { left: "Pass", right: "Keep" } */
+  labels?: {
+    left: string;
+    right: string;
+  };
+  /** Past tense of each action for announcements, such as "skipped" and "shortlisted". Without it a decision reads "Lisbon: Keep". */
+  outcomes?: {
+    left: string;
+    right: string;
+  };
+  /** Accessible name for the stack. @default "Cards" */
+  label?: string;
+  /** Shown once every card has been decided. Receives a function that brings all cards back. */
+  renderEmpty?: (reset: () => void) => ReactNode;
+  /** Extra classes for the stack. Merged last. */
+  className?: string;
+}
+export declare function CardStack<T>({ items, getKey, getLabel, renderCard, onDecide, onUndo, onReset, labels, outcomes, label, renderEmpty, className }: CardStackProps<T>): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=card-stack.d.ts.map

package/dist/card-stack/card-stack.js

@@ -0,0 +1,492 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { prefersReducedMotion, useExitBackstop, useIsomorphicLayoutEffect } from "../lib/motion.js";
+import { Button } from "../button/button.js";
+import { useCallback, useId, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+//#region src/card-stack/card-stack.tsx
+/** Cards rendered in the stack. The last one waits invisibly one step behind and fades in as it rises. */
+const VISIBLE = 4;
+/** Degrees of rotation per pixel of horizontal travel. */
+const ROTATE = .065;
+/** A release faster than this (px/s) throws the card even when it has only moved a little. */
+const FLICK = 500;
+/** Drag distance at which the cards behind have fully risen. */
+const LIFT_DISTANCE = 160;
+/** Vertical travel is not a decision, so past a small free zone it resists like a rubber band. */
+const FREE_Y = 48;
+const STRETCH_Y = 140;
+/** The stamp is fully shown at 96px of travel and starts at 16px. */
+const STAMP_FROM = 16;
+/** A thrown card is gone this long after it starts (the fade finishes well before); the backstop for a transition that never ends. */
+const FLIGHT_BACKSTOP_MS = 1500;
+const resistY = (raw) => {
+	const distance = Math.abs(raw);
+	return distance <= FREE_Y ? raw : Math.sign(raw) * (FREE_Y + (1 - 1 / ((distance - FREE_Y) * .55 / STRETCH_Y + 1)) * STRETCH_Y);
+};
+const unresistY = (shown) => {
+	const distance = Math.abs(shown);
+	if (distance <= FREE_Y) return shown;
+	const stretch = Math.min(distance - FREE_Y, 139);
+	return Math.sign(shown) * (FREE_Y + (1 / (1 - stretch / STRETCH_Y) - 1) * STRETCH_Y / .55);
+};
+const clampUnit = (value) => Math.min(1, Math.max(0, value));
+/** Where the card is now, mid-flight included: the computed translate, in px. */
+function readOffset(el) {
+	const value = getComputedStyle(el).translate;
+	if (!value || value === "none") return {
+		x: 0,
+		y: 0
+	};
+	const [x, y] = value.split(" ").map(parseFloat);
+	return {
+		x: x || 0,
+		y: y || 0
+	};
+}
+function velocityOf(samples, now) {
+	const recent = samples.filter((sample) => now - sample.t <= 80);
+	const first = recent[0];
+	const last = recent[recent.length - 1];
+	if (!first || !last || first === last || now - last.t > 60) return {
+		x: 0,
+		y: 0
+	};
+	const seconds = (last.t - first.t) / 1e3;
+	return {
+		x: (last.x - first.x) / seconds,
+		y: (last.y - first.y) / seconds
+	};
+}
+const iconProps = {
+	width: 16,
+	height: 16,
+	viewBox: "0 0 24 24",
+	fill: "none",
+	stroke: "currentColor",
+	strokeWidth: 1.75,
+	strokeLinecap: "round",
+	strokeLinejoin: "round",
+	"aria-hidden": true
+};
+const CheckIcon = () => /* @__PURE__ */ jsx("svg", {
+	...iconProps,
+	children: /* @__PURE__ */ jsx("path", { d: "M5 12.5 10 17.5 19 7" })
+});
+const CloseIcon = () => /* @__PURE__ */ jsx("svg", {
+	...iconProps,
+	children: /* @__PURE__ */ jsx("path", { d: "M6 6l12 12M18 6 6 18" })
+});
+const UndoIcon = () => /* @__PURE__ */ jsx("svg", {
+	...iconProps,
+	children: /* @__PURE__ */ jsx("path", { d: "M4 12a8 8 0 1 0 2.5-5.8M4 4v4.5h4.5" })
+});
+/**
+* A control that stays focusable when it has nothing to do: React Aria drops `aria-disabled` and a disabled button would
+* drop focus to the page when the stack runs out, so the attribute is set by hand and the press is guarded.
+*/
+function Control({ disabled, onPress, ...rest }) {
+	const ref = useRef(null);
+	useIsomorphicLayoutEffect(() => {
+		if (disabled) ref.current?.setAttribute("aria-disabled", "true");
+		else ref.current?.removeAttribute("aria-disabled");
+	}, [disabled]);
+	return /* @__PURE__ */ jsx(Button, {
+		...rest,
+		ref,
+		className: "aria-disabled:cursor-default aria-disabled:opacity-40",
+		onPress: () => {
+			if (!disabled) onPress();
+		}
+	});
+}
+/** Renders a custom empty state; the reset handler travels as a prop so render never touches the stack's refs. */
+function EmptySlot({ render, onReset }) {
+	return /* @__PURE__ */ jsx(Fragment$1, { children: render(onReset) });
+}
+const HOME_TRANSITION = (delay) => `translate var(--duration-smooth) var(--ease-smooth) ${delay}ms, rotate var(--duration-smooth) var(--ease-smooth) ${delay}ms, opacity var(--duration-quick) var(--ease-enter) ${delay}ms`;
+const SPRING_BACK = "translate var(--duration-morph) var(--ease-morph), rotate var(--duration-morph) var(--ease-morph)";
+const THROW = "translate var(--duration-calm) var(--ease-calm), rotate var(--duration-calm) var(--ease-calm), opacity 220ms var(--ease-settle) 120ms";
+const REDUCED_FADE = "opacity 150ms linear";
+function StackCard({ id, depth, decision, returnFrom, interactive, zIndex, label, labels, stage, fling, onRelease, onThrown, onGone, children }) {
+	const card = useRef(null);
+	const tilt = useRef(returnFrom?.tilt ?? 1);
+	const drag = useRef(null);
+	const settled = useRef(!returnFrom);
+	const wasDecided = useRef(false);
+	const lift = (value) => stage.current?.style.setProperty("--lift", String(value));
+	/** Writes the card's place and what follows from it (its tilt and its stamps) straight to the DOM: a drag never re-renders. */
+	const place = (el, x, y) => {
+		el.style.translate = `${x}px ${y}px`;
+		el.style.rotate = `${x * ROTATE * tilt.current}deg`;
+		el.style.setProperty("--keep", String(clampUnit((x - STAMP_FROM) / 80)));
+		el.style.setProperty("--pass", String(clampUnit((-16 - x) / 80)));
+	};
+	useIsomorphicLayoutEffect(() => {
+		const el = card.current;
+		if (!el) return;
+		const reduced = prefersReducedMotion();
+		if (decision) {
+			drag.current = null;
+			el.removeAttribute("data-dragging");
+			wasDecided.current = true;
+			const direction = decision === "right" ? 1 : -1;
+			const { x: cx, y: cy } = readOffset(el);
+			const velocity = fling(id) ?? {
+				x: direction * 900,
+				y: -120
+			};
+			const speed = Math.hypot(velocity.x, velocity.y);
+			let ux = velocity.x;
+			let uy = velocity.y;
+			if (speed < 200 || Math.sign(ux) !== direction) {
+				ux = Math.abs(cx) > 8 ? cx : direction;
+				uy = Math.abs(cx) > 8 ? cy * .5 : -.12;
+			}
+			const length = Math.hypot(ux, uy) || 1;
+			ux /= length;
+			uy /= length;
+			if (Math.abs(ux) < .45) {
+				ux = direction * .45;
+				uy = Math.sign(uy || -1) * Math.sqrt(.7975);
+			}
+			const reach = el.offsetWidth * 1.6;
+			const exit = {
+				x: cx + ux * reach,
+				y: cy + uy * reach,
+				tilt: tilt.current
+			};
+			onThrown(id, exit);
+			el.style.setProperty(direction > 0 ? "--keep" : "--pass", "1");
+			if (reduced) el.style.transition = REDUCED_FADE;
+			else {
+				el.style.transition = THROW;
+				place(el, exit.x, exit.y);
+			}
+			el.style.opacity = "0";
+			return;
+		}
+		if (!wasDecided.current && settled.current) return;
+		wasDecided.current = false;
+		const delay = returnFrom?.delay ?? 0;
+		if (!settled.current && !reduced && returnFrom) {
+			el.style.transition = "none";
+			place(el, returnFrom.x, returnFrom.y);
+			el.style.opacity = "0";
+			el.offsetWidth;
+		}
+		settled.current = true;
+		if (reduced) {
+			el.style.transition = `${REDUCED_FADE} ${delay}ms`;
+			place(el, 0, 0);
+		} else {
+			el.style.transition = HOME_TRANSITION(delay);
+			place(el, 0, 0);
+		}
+		el.style.opacity = "1";
+	}, [decision]);
+	const gone = useCallback(() => onGone(id), [onGone, id]);
+	useExitBackstop(decision !== null, gone, FLIGHT_BACKSTOP_MS);
+	function down(event) {
+		if (!interactive || event.button !== 0 || !event.isPrimary) return;
+		if (event.target instanceof Element && event.target.closest("button, a, input, select, textarea, [role='button']")) return;
+		const el = event.currentTarget;
+		const now = readOffset(el);
+		el.style.transition = "none";
+		if (Math.abs(now.x) < 2) {
+			const rect = el.getBoundingClientRect();
+			tilt.current = event.clientY < rect.top + rect.height / 2 ? 1 : -1;
+		}
+		place(el, now.x, now.y);
+		drag.current = {
+			ox: event.clientX - now.x,
+			oy: event.clientY - unresistY(now.y),
+			samples: [{
+				t: event.timeStamp,
+				x: event.clientX,
+				y: event.clientY
+			}]
+		};
+		try {
+			el.setPointerCapture(event.pointerId);
+		} catch {}
+		el.setAttribute("data-dragging", "");
+	}
+	function move(event) {
+		const state = drag.current;
+		if (!state || !interactive) return;
+		const x = event.clientX - state.ox;
+		const y = resistY(event.clientY - state.oy);
+		place(event.currentTarget, x, y);
+		lift(clampUnit(Math.hypot(x, y * .5) / LIFT_DISTANCE));
+		state.samples.push({
+			t: event.timeStamp,
+			x: event.clientX,
+			y: event.clientY
+		});
+		if (state.samples.length > 12) state.samples.shift();
+	}
+	function up(event) {
+		const state = drag.current;
+		drag.current = null;
+		const el = event.currentTarget;
+		el.removeAttribute("data-dragging");
+		if (el.hasPointerCapture(event.pointerId)) el.releasePointerCapture(event.pointerId);
+		if (!state || !interactive) return;
+		const velocity = event.type === "pointercancel" ? {
+			x: 0,
+			y: 0
+		} : velocityOf(state.samples, event.timeStamp);
+		if (onRelease(id, readOffset(el), velocity, el.offsetWidth)) return;
+		el.style.transition = prefersReducedMotion() ? "none" : SPRING_BACK;
+		place(el, 0, 0);
+		lift(0);
+	}
+	return /* @__PURE__ */ jsx("div", {
+		className: "card-stack-slot",
+		style: {
+			"--depth": depth,
+			zIndex
+		},
+		"aria-hidden": interactive ? void 0 : true,
+		ref: (node) => {
+			if (!node) return;
+			if (interactive) node.removeAttribute("inert");
+			else node.setAttribute("inert", "");
+		},
+		children: /* @__PURE__ */ jsxs("div", {
+			ref: card,
+			className: "card-stack-card",
+			"data-top": interactive ? "" : void 0,
+			"data-flying": decision ? "" : void 0,
+			role: interactive ? "group" : void 0,
+			"aria-label": interactive ? label : void 0,
+			onPointerDown: down,
+			onPointerMove: move,
+			onPointerUp: up,
+			onPointerCancel: up,
+			onTransitionEnd: (event) => {
+				if (decision && event.target === event.currentTarget && event.propertyName === "opacity") gone();
+			},
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "card-stack-face",
+					children: [children, /* @__PURE__ */ jsx("span", {
+						className: "card-stack-shade",
+						"aria-hidden": "true"
+					})]
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: "card-stack-stamp",
+					"data-side": "right",
+					"aria-hidden": "true",
+					children: [/* @__PURE__ */ jsx(CheckIcon, {}), labels.right]
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: "card-stack-stamp",
+					"data-side": "left",
+					"aria-hidden": "true",
+					children: [/* @__PURE__ */ jsx(CloseIcon, {}), labels.left]
+				})
+			]
+		})
+	});
+}
+function CardStack({ items, getKey, getLabel, renderCard, onDecide, onUndo, onReset, labels = {
+	left: "Pass",
+	right: "Keep"
+}, outcomes, label = "Cards", renderEmpty, className }) {
+	const hintId = useId();
+	const stage = useRef(null);
+	const [position, setPosition] = useState(0);
+	const [history, setHistory] = useState([]);
+	const [flying, setFlying] = useState([]);
+	const [returning, setReturning] = useState({});
+	const [message, setMessage] = useState("");
+	const exits = useRef({});
+	const flings = useRef(/* @__PURE__ */ new Map());
+	const top = items[position];
+	const remaining = Math.max(0, items.length - position);
+	function decide(decision) {
+		if (!top) return;
+		const key = getKey(top);
+		stage.current?.style.setProperty("--lift", "0");
+		setPosition(position + 1);
+		setHistory([...history, {
+			key,
+			decision
+		}]);
+		setFlying((current) => [...current, key]);
+		setReturning({});
+		const left = remaining - 1;
+		setMessage(`${getLabel(top)}${outcomes ? ` ${outcomes[decision]}` : `: ${labels[decision]}`}. ${left ? `${left} left.` : "All cards reviewed."}`);
+		onDecide?.(top, decision);
+	}
+	function undo() {
+		const last = history[history.length - 1];
+		const item = last && items.find((entry) => getKey(entry) === last.key);
+		if (!last || !item) return;
+		const exit = exits.current[last.key];
+		setPosition(position - 1);
+		setHistory(history.slice(0, -1));
+		setFlying((current) => current.filter((key) => key !== last.key));
+		setReturning(exit ? { [last.key]: {
+			...exit,
+			delay: 0
+		} } : {});
+		setMessage(`${getLabel(item)} restored.`);
+		onUndo?.(item, last.decision);
+	}
+	function reset() {
+		if (!history.length) return;
+		const count = Math.min(VISIBLE, items.length);
+		const back = {};
+		items.slice(0, count).forEach((item, index) => {
+			const key = getKey(item);
+			const exit = exits.current[key];
+			if (exit && index < position) back[key] = {
+				...exit,
+				delay: (count - 1 - index) * 60
+			};
+		});
+		setPosition(0);
+		setHistory([]);
+		setFlying([]);
+		setReturning(back);
+		setMessage("All cards are back in the stack.");
+		onReset?.();
+	}
+	function release(key, offset, velocity, width) {
+		const direction = Math.sign(offset.x);
+		if (!direction || !top || getKey(top) !== key) return false;
+		const flick = Math.abs(velocity.x) > FLICK && Math.sign(velocity.x) === direction && Math.abs(offset.x) > 12;
+		const far = Math.abs(offset.x) > Math.min(width * .35, 140) && !(Math.sign(velocity.x) === -direction && Math.abs(velocity.x) > 300);
+		if (!flick && !far) return false;
+		flings.current.set(key, velocity);
+		decide(direction > 0 ? "right" : "left");
+		return true;
+	}
+	function onKeyDown(event) {
+		if (event.target !== event.currentTarget) return;
+		if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+			event.preventDefault();
+			decide(event.key === "ArrowRight" ? "right" : "left");
+		} else if (event.key === "Backspace" || (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "z") {
+			event.preventDefault();
+			undo();
+		}
+	}
+	const decided = new Map(history.map((entry) => [entry.key, entry.decision]));
+	const windowKeys = new Set(items.slice(position, position + VISIBLE).map(getKey));
+	const rendered = items.filter((item) => windowKeys.has(getKey(item)) || flying.includes(getKey(item)));
+	const empty = position >= items.length && flying.length === 0;
+	const takeFling = useCallback((key) => {
+		const velocity = flings.current.get(key);
+		flings.current.delete(key);
+		return velocity;
+	}, []);
+	const recordExit = useCallback((key, exit) => {
+		exits.current[key] = exit;
+	}, []);
+	const finish = useCallback((key) => setFlying((current) => current.filter((entry) => entry !== key)), []);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "card-stack",
+		className: cn("card-stack", className),
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				ref: stage,
+				className: "card-stack-stage",
+				role: "application",
+				"aria-roledescription": "card stack",
+				"aria-label": label,
+				"aria-describedby": hintId,
+				tabIndex: 0,
+				onKeyDown,
+				children: [rendered.map((item) => {
+					const id = getKey(item);
+					const index = items.indexOf(item);
+					const decision = decided.get(id) ?? null;
+					const depth = decision ? 0 : index - position;
+					return /* @__PURE__ */ jsx(StackCard, {
+						id,
+						depth,
+						decision,
+						returnFrom: returning[id],
+						interactive: !decision && depth === 0,
+						zIndex: decision ? 20 + flying.indexOf(id) : VISIBLE - depth,
+						label: `${getLabel(item)}, ${index + 1} of ${items.length}`,
+						labels,
+						stage,
+						fling: takeFling,
+						onRelease: release,
+						onThrown: recordExit,
+						onGone: finish,
+						children: renderCard(item)
+					}, id);
+				}), empty ? /* @__PURE__ */ jsx("div", {
+					className: "card-stack-empty",
+					children: renderEmpty ? /* @__PURE__ */ jsx(EmptySlot, {
+						render: renderEmpty,
+						onReset: reset
+					}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("p", {
+						className: "m-0 text-base font-medium",
+						children: "All cards reviewed"
+					}), /* @__PURE__ */ jsx(Button, {
+						variant: "outline",
+						onPress: reset,
+						startIcon: /* @__PURE__ */ jsx(UndoIcon, {}),
+						children: "Start over"
+					})] })
+				}) : null]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-wrap justify-center gap-2",
+				children: [
+					/* @__PURE__ */ jsx(Control, {
+						variant: "outline",
+						disabled: !top,
+						onPress: () => decide("left"),
+						startIcon: /* @__PURE__ */ jsx(CloseIcon, {}),
+						children: labels.left
+					}),
+					/* @__PURE__ */ jsx(Control, {
+						variant: "ghost",
+						disabled: !history.length,
+						onPress: undo,
+						startIcon: /* @__PURE__ */ jsx(UndoIcon, {}),
+						children: "Undo"
+					}),
+					/* @__PURE__ */ jsx(Control, {
+						variant: "primary",
+						disabled: !top,
+						onPress: () => decide("right"),
+						startIcon: /* @__PURE__ */ jsx(CheckIcon, {}),
+						children: labels.right
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("p", {
+				id: hintId,
+				className: "sr-only",
+				children: [
+					"Drag the top card, or use the left and right arrow keys to ",
+					labels.left.toLowerCase(),
+					" or",
+					" ",
+					labels.right.toLowerCase(),
+					" it. Backspace undoes the last decision."
+				]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "sr-only",
+				role: "status",
+				"aria-live": "polite",
+				children: message
+			})
+		]
+	});
+}
+//#endregion
+export { CardStack };
+
+//# sourceMappingURL=card-stack.js.map