@seekalfred/primitives 0.5.1 → 0.6.0

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

@@ -0,0 +1,81 @@
+import { ReactNode } from "react";
+//#region src/stat-card/stat-card.d.ts
+/**
+ * StatCard: one headline figure with its label and a line of context. A row
+ * of them is a dashboard's summary strip.
+ *
+ * It exists because a summary strip is on almost every overview screen, and
+ * without a shared card each screen picks its own label case, number size,
+ * colour and height, so the same figure looks different on two pages.
+ *
+ * Three rules it holds:
+ *
+ * - The label is ONE line. A long label is cut with an ellipsis and the full
+ *   text is on hover, so a row of cards keeps its numbers on one baseline
+ *   instead of one card's label wrapping and pushing its number down.
+ * - The number's colour comes from `tone`, a fixed set of meanings, never a
+ *   colour. `neutral` is the default and is right for any figure without a
+ *   verdict in it, including every zero.
+ * - Cards in a row are the same height (`h-full` in a grid or flex row).
+ *
+ * A card can be a link (`href`, React Aria Link, so a router provider routes
+ * it), a button (`onPress`), or a filter toggle (`isSelected` + `onPress`, a
+ * React Aria ToggleButton with `aria-pressed` and one shared selected look).
+ *
+ * Every string in the cva blocks below is a STATIC literal. Tailwind scans
+ * source text, so a class assembled at runtime is invisible to it and would
+ * simply never be emitted.
+ */
+export declare const statCardVariants: (props?: ({
+  selected?: boolean | null | undefined;
+  interactive?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const statCardLabelVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const statCardValueVariants: (props?: ({
+  tone?: "neutral" | "warning" | "positive" | "negative" | "attention" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const statCardSubVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export type StatCardTone = "neutral" | "positive" | "negative" | "warning" | "attention";
+export interface StatCardProps {
+  /** What the figure is. One line; cut with an ellipsis, full text on hover. */
+  label: string;
+  /** The figure itself, already formatted. */
+  value: ReactNode;
+  /** One line of context under the figure. */
+  sub?: ReactNode;
+  /**
+   * What the figure means: `neutral` (default, and right for every zero),
+   * `positive`, `negative`, `warning` (part-way or waiting) or `attention`
+   * (a person has to look).
+   */
+  tone?: StatCardTone;
+  /**
+   * The card is a filter, and this says whether it is the one applied.
+   * Renders a toggle button with `aria-pressed`. Pair with `onPress`.
+   */
+  isSelected?: boolean;
+  /** Renders the card as a link to this URL. */
+  href?: string;
+  /** Renders the card as a button (or, with `isSelected`, a toggle). */
+  onPress?: () => void;
+  /** Hover text for the whole card. */
+  description?: string;
+  /** Anything under the context line. */
+  children?: ReactNode;
+  /** Layout classes for the card (margins, grid placement). */
+  className?: string;
+  "aria-label"?: string;
+}
+/**
+ * One headline figure.
+ *
+ * @example
+ * <div className="grid gap-4 sm:grid-cols-3">
+ *   <StatCard label="Open" value="$12,400" sub="18 invoices" />
+ *   <StatCard label="Overdue" value="$3,100" sub="4 invoices" tone="negative" />
+ *   <StatCard label="Collected" value="$9,800" tone="positive" href="/payments" />
+ * </div>
+ */
+export declare const StatCard: import("react").ForwardRefExoticComponent<StatCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+//# sourceMappingURL=stat-card.d.ts.map

package/dist/stat-card/stat-card.js

@@ -0,0 +1,152 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { cva } from "class-variance-authority";
+import { forwardRef } from "react";
+import { Button, Link, ToggleButton } from "react-aria-components";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/stat-card/stat-card.tsx
+/**
+* StatCard: one headline figure with its label and a line of context. A row
+* of them is a dashboard's summary strip.
+*
+* It exists because a summary strip is on almost every overview screen, and
+* without a shared card each screen picks its own label case, number size,
+* colour and height, so the same figure looks different on two pages.
+*
+* Three rules it holds:
+*
+* - The label is ONE line. A long label is cut with an ellipsis and the full
+*   text is on hover, so a row of cards keeps its numbers on one baseline
+*   instead of one card's label wrapping and pushing its number down.
+* - The number's colour comes from `tone`, a fixed set of meanings, never a
+*   colour. `neutral` is the default and is right for any figure without a
+*   verdict in it, including every zero.
+* - Cards in a row are the same height (`h-full` in a grid or flex row).
+*
+* A card can be a link (`href`, React Aria Link, so a router provider routes
+* it), a button (`onPress`), or a filter toggle (`isSelected` + `onPress`, a
+* React Aria ToggleButton with `aria-pressed` and one shared selected look).
+*
+* Every string in the cva blocks below is a STATIC literal. Tailwind scans
+* source text, so a class assembled at runtime is invisible to it and would
+* simply never be emitted.
+*/
+const statCardVariants = cva([
+	"flex h-full min-w-0 flex-col p-4 text-start",
+	"rounded-lg border-(length:--border-width) bg-card text-card-foreground",
+	"box-border font-sans"
+], {
+	variants: {
+		/** A filter card that is the one applied. */
+		selected: {
+			true: "border-primary-strong",
+			false: "border-border"
+		},
+		/** Whether the card is a link or a button (hover and focus states). */
+		interactive: {
+			true: [
+				"cursor-pointer outline-none",
+				"data-[hovered]:not-data-[selected]:border-muted-foreground",
+				"data-[focus-visible]:outline-solid",
+				"data-[focus-visible]:outline-(length:--focus-ring-width)",
+				"data-[focus-visible]:outline-offset-(--focus-ring-offset)",
+				"data-[focus-visible]:outline-(--color-ring)"
+			],
+			false: ""
+		}
+	},
+	defaultVariants: {
+		selected: false,
+		interactive: false
+	}
+});
+const statCardLabelVariants = cva(["m-0 truncate text-2xs leading-(--leading-normal) font-medium tracking-wide uppercase", "text-muted-foreground"]);
+const statCardValueVariants = cva("m-0 mt-1 text-h4 leading-(--leading-snug) font-semibold tabular-nums break-words", {
+	variants: { 
+	/** What the number MEANS. Colour follows from it; it is never picked directly. */
+tone: {
+		neutral: "text-foreground",
+		positive: "text-success-strong",
+		negative: "text-destructive-strong",
+		warning: "text-warning-strong",
+		attention: "text-primary-strong"
+	} },
+	defaultVariants: { tone: "neutral" }
+});
+const statCardSubVariants = cva("m-0 mt-1 text-xs leading-(--leading-normal) text-muted-foreground");
+/**
+* One headline figure.
+*
+* @example
+* <div className="grid gap-4 sm:grid-cols-3">
+*   <StatCard label="Open" value="$12,400" sub="18 invoices" />
+*   <StatCard label="Overdue" value="$3,100" sub="4 invoices" tone="negative" />
+*   <StatCard label="Collected" value="$9,800" tone="positive" href="/payments" />
+* </div>
+*/
+const StatCard = forwardRef(function StatCard({ label, value, sub, tone, isSelected, href, onPress, description, children, className, ...rest }, ref) {
+	const body = /* @__PURE__ */ jsxs("span", {
+		className: "flex min-w-0 flex-1 flex-col",
+		title: description,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-card-label",
+				className: cn(statCardLabelVariants(), "block"),
+				title: label,
+				children: label
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-card-value",
+				"data-tone": tone ?? "neutral",
+				className: cn(statCardValueVariants({ tone }), "block"),
+				children: value
+			}),
+			sub === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-card-sub",
+				className: cn(statCardSubVariants(), "block"),
+				children: sub
+			}),
+			children
+		]
+	});
+	const classes = cn(statCardVariants({
+		selected: isSelected === true,
+		interactive: isSelected !== void 0 || onPress !== void 0 || href !== void 0
+	}), className);
+	const common = {
+		"data-slot": "stat-card",
+		"aria-label": rest["aria-label"]
+	};
+	if (isSelected !== void 0) return /* @__PURE__ */ jsx(ToggleButton, {
+		ref,
+		...common,
+		isSelected,
+		onChange: () => onPress?.(),
+		className: classes,
+		children: body
+	});
+	if (onPress) return /* @__PURE__ */ jsx(Button, {
+		ref,
+		...common,
+		onPress,
+		className: classes,
+		children: body
+	});
+	if (href !== void 0) return /* @__PURE__ */ jsx(Link, {
+		ref,
+		...common,
+		href,
+		className: classes,
+		children: body
+	});
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		...common,
+		className: classes,
+		children: body
+	});
+});
+//#endregion
+export { StatCard, statCardLabelVariants, statCardSubVariants, statCardValueVariants, statCardVariants };
+
+//# sourceMappingURL=stat-card.js.map

package/dist/stat-card/stat-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat-card.js","names":["AriaToggleButton","AriaButton","AriaLink"],"sources":["../../src/stat-card/stat-card.tsx"],"sourcesContent":["\"use client\";\n\nimport { cva } from \"class-variance-authority\";\nimport { forwardRef, type ReactNode, type Ref } from \"react\";\nimport {\n  Button as AriaButton,\n  Link as AriaLink,\n  ToggleButton as AriaToggleButton,\n} from \"react-aria-components\";\n\nimport { cn } from \"../lib/cn.js\";\n\n/**\n * StatCard: one headline figure with its label and a line of context. A row\n * of them is a dashboard's summary strip.\n *\n * It exists because a summary strip is on almost every overview screen, and\n * without a shared card each screen picks its own label case, number size,\n * colour and height, so the same figure looks different on two pages.\n *\n * Three rules it holds:\n *\n * - The label is ONE line. A long label is cut with an ellipsis and the full\n *   text is on hover, so a row of cards keeps its numbers on one baseline\n *   instead of one card's label wrapping and pushing its number down.\n * - The number's colour comes from `tone`, a fixed set of meanings, never a\n *   colour. `neutral` is the default and is right for any figure without a\n *   verdict in it, including every zero.\n * - Cards in a row are the same height (`h-full` in a grid or flex row).\n *\n * A card can be a link (`href`, React Aria Link, so a router provider routes\n * it), a button (`onPress`), or a filter toggle (`isSelected` + `onPress`, a\n * React Aria ToggleButton with `aria-pressed` and one shared selected look).\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 statCardVariants = cva(\n  [\n    \"flex h-full min-w-0 flex-col p-4 text-start\",\n    \"rounded-lg border-(length:--border-width) bg-card text-card-foreground\",\n    // box-border and font-sans are not boilerplate: the reset in\n    // @seekalfred/styles is opt-in, so a consumer may load none.\n    \"box-border font-sans\",\n  ],\n  {\n    variants: {\n      /** A filter card that is the one applied. */\n      selected: {\n        true: \"border-primary-strong\",\n        false: \"border-border\",\n      },\n      /** Whether the card is a link or a button (hover and focus states). */\n      interactive: {\n        true: [\n          \"cursor-pointer outline-none\",\n          // A border, not a fill: a muted fill under the muted label fails contrast.\n          \"data-[hovered]:not-data-[selected]:border-muted-foreground\",\n          // outline-solid on the focus variant is load-bearing: outline-none\n          // sets the outline style the width utility resolves from.\n          \"data-[focus-visible]:outline-solid\",\n          \"data-[focus-visible]:outline-(length:--focus-ring-width)\",\n          \"data-[focus-visible]:outline-offset-(--focus-ring-offset)\",\n          \"data-[focus-visible]:outline-(--color-ring)\",\n        ],\n        false: \"\",\n      },\n    },\n    defaultVariants: { selected: false, interactive: false },\n  },\n);\n\nexport const statCardLabelVariants = cva([\n  \"m-0 truncate text-2xs leading-(--leading-normal) font-medium tracking-wide uppercase\",\n  \"text-muted-foreground\",\n]);\n\nexport const statCardValueVariants = 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  \"m-0 mt-1 text-h4 leading-(--leading-snug) font-semibold tabular-nums break-words\",\n  {\n    variants: {\n      /** What the number MEANS. Colour follows from it; it is never picked directly. */\n      tone: {\n        neutral: \"text-foreground\",\n        positive: \"text-success-strong\",\n        negative: \"text-destructive-strong\",\n        warning: \"text-warning-strong\",\n        attention: \"text-primary-strong\",\n      },\n    },\n    defaultVariants: { tone: \"neutral\" },\n  },\n);\n\nexport const statCardSubVariants = cva(\n  \"m-0 mt-1 text-xs leading-(--leading-normal) text-muted-foreground\",\n);\n\nexport type StatCardTone = \"neutral\" | \"positive\" | \"negative\" | \"warning\" | \"attention\";\n\nexport interface StatCardProps {\n  /** What the figure is. One line; cut with an ellipsis, full text on hover. */\n  label: string;\n  /** The figure itself, already formatted. */\n  value: ReactNode;\n  /** One line of context under the figure. */\n  sub?: ReactNode;\n  /**\n   * What the figure means: `neutral` (default, and right for every zero),\n   * `positive`, `negative`, `warning` (part-way or waiting) or `attention`\n   * (a person has to look).\n   */\n  tone?: StatCardTone;\n  /**\n   * The card is a filter, and this says whether it is the one applied.\n   * Renders a toggle button with `aria-pressed`. Pair with `onPress`.\n   */\n  isSelected?: boolean;\n  /** Renders the card as a link to this URL. */\n  href?: string;\n  /** Renders the card as a button (or, with `isSelected`, a toggle). */\n  onPress?: () => void;\n  /** Hover text for the whole card. */\n  description?: string;\n  /** Anything under the context line. */\n  children?: ReactNode;\n  /** Layout classes for the card (margins, grid placement). */\n  className?: string;\n  \"aria-label\"?: string;\n}\n\n/**\n * One headline figure.\n *\n * @example\n * <div className=\"grid gap-4 sm:grid-cols-3\">\n *   <StatCard label=\"Open\" value=\"$12,400\" sub=\"18 invoices\" />\n *   <StatCard label=\"Overdue\" value=\"$3,100\" sub=\"4 invoices\" tone=\"negative\" />\n *   <StatCard label=\"Collected\" value=\"$9,800\" tone=\"positive\" href=\"/payments\" />\n * </div>\n */\nexport const StatCard = forwardRef<HTMLElement, StatCardProps>(function StatCard(\n  { label, value, sub, tone, isSelected, href, onPress, description, children, className, ...rest },\n  ref,\n) {\n  const body = (\n    // The hover text sits on a box that fills the card: React Aria's Button\n    // does not pass a `title` through to the element it renders.\n    <span className=\"flex min-w-0 flex-1 flex-col\" title={description}>\n      <span\n        data-slot=\"stat-card-label\"\n        className={cn(statCardLabelVariants(), \"block\")}\n        title={label}\n      >\n        {label}\n      </span>\n      <span\n        data-slot=\"stat-card-value\"\n        data-tone={tone ?? \"neutral\"}\n        className={cn(statCardValueVariants({ tone }), \"block\")}\n      >\n        {value}\n      </span>\n      {sub === undefined ? null : (\n        <span data-slot=\"stat-card-sub\" className={cn(statCardSubVariants(), \"block\")}>\n          {sub}\n        </span>\n      )}\n      {children}\n    </span>\n  );\n  const interactive = isSelected !== undefined || onPress !== undefined || href !== undefined;\n  const classes = cn(statCardVariants({ selected: isSelected === true, interactive }), className);\n  const common = { \"data-slot\": \"stat-card\", \"aria-label\": rest[\"aria-label\"] };\n\n  if (isSelected !== undefined) {\n    return (\n      <AriaToggleButton\n        ref={ref as Ref<HTMLButtonElement>}\n        {...common}\n        isSelected={isSelected}\n        onChange={() => onPress?.()}\n        className={classes}\n      >\n        {body}\n      </AriaToggleButton>\n    );\n  }\n  if (onPress) {\n    return (\n      <AriaButton\n        ref={ref as Ref<HTMLButtonElement>}\n        {...common}\n        onPress={onPress}\n        className={classes}\n      >\n        {body}\n      </AriaButton>\n    );\n  }\n  if (href !== undefined) {\n    return (\n      <AriaLink ref={ref as Ref<HTMLAnchorElement>} {...common} href={href} className={classes}>\n        {body}\n      </AriaLink>\n    );\n  }\n  return (\n    <div ref={ref as Ref<HTMLDivElement>} {...common} className={classes}>\n      {body}\n    </div>\n  );\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,MAAa,mBAAmB,IAC9B;CACE;CACA;CAGA;AACF,GACA;CACE,UAAU;;EAER,UAAU;GACR,MAAM;GACN,OAAO;EACT;;EAEA,aAAa;GACX,MAAM;IACJ;IAEA;IAGA;IACA;IACA;IACA;GACF;GACA,OAAO;EACT;CACF;CACA,iBAAiB;EAAE,UAAU;EAAO,aAAa;CAAM;AACzD,CACF;AAEA,MAAa,wBAAwB,IAAI,CACvC,wFACA,uBACF,CAAC;AAED,MAAa,wBAAwB,IAGnC,oFACA;CACE,UAAU;;AAER,MAAM;EACJ,SAAS;EACT,UAAU;EACV,UAAU;EACV,SAAS;EACT,WAAW;CACb,EACF;CACA,iBAAiB,EAAE,MAAM,UAAU;AACrC,CACF;AAEA,MAAa,sBAAsB,IACjC,mEACF;;;;;;;;;;;AA6CA,MAAa,WAAW,WAAuC,SAAS,SACtE,EAAE,OAAO,OAAO,KAAK,MAAM,YAAY,MAAM,SAAS,aAAa,UAAU,WAAW,GAAG,QAC3F,KACA;CACA,MAAM,OAGJ,qBAAC,QAAD;EAAM,WAAU;EAA+B,OAAO;EAAtD,UAAA;GACE,oBAAC,QAAD;IACE,aAAU;IACV,WAAW,GAAG,sBAAsB,GAAG,OAAO;IAC9C,OAAO;IAEN,UAAA;GACG,CAAA;GACN,oBAAC,QAAD;IACE,aAAU;IACV,aAAW,QAAQ;IACnB,WAAW,GAAG,sBAAsB,EAAE,KAAK,CAAC,GAAG,OAAO;IAErD,UAAA;GACG,CAAA;GACL,QAAQ,KAAA,IAAY,OACnB,oBAAC,QAAD;IAAM,aAAU;IAAgB,WAAW,GAAG,oBAAoB,GAAG,OAAO;IACzE,UAAA;GACG,CAAA;GAEP;EACG;;CAGR,MAAM,UAAU,GAAG,iBAAiB;EAAE,UAAU,eAAe;EAAM,aADjD,eAAe,KAAA,KAAa,YAAY,KAAA,KAAa,SAAS,KAAA;CACD,CAAC,GAAG,SAAS;CAC9F,MAAM,SAAS;EAAE,aAAa;EAAa,cAAc,KAAK;CAAc;CAE5E,IAAI,eAAe,KAAA,GACjB,OACE,oBAACA,cAAD;EACO;EACL,GAAI;EACQ;EACZ,gBAAgB,UAAU;EAC1B,WAAW;EAEV,UAAA;CACe,CAAA;CAGtB,IAAI,SACF,OACE,oBAACC,QAAD;EACO;EACL,GAAI;EACK;EACT,WAAW;EAEV,UAAA;CACS,CAAA;CAGhB,IAAI,SAAS,KAAA,GACX,OACE,oBAACC,MAAD;EAAe;EAA+B,GAAI;EAAc;EAAM,WAAW;EAC9E,UAAA;CACO,CAAA;CAGd,OACE,oBAAC,OAAD;EAAU;EAA4B,GAAI;EAAQ,WAAW;EAC1D,UAAA;CACE,CAAA;AAET,CAAC"}