gbs-add-block 1.2.16 → 1.2.17

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.16)
+# GBS Building Blocks 2.0 (v1.2.17)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -10,7 +10,7 @@ For detailed documentation on usage and props, Please visit: [Building Block Doc
 
 New Beta Components are avilable for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app/2.0.0-beta)
 
-## What's New 🎉 (Ver 1.2.16)
+## What's New 🎉 (Ver 1.2.17)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -51,6 +51,11 @@ const CONFIG = {
     "Checkbox",
     "Tabs",
     "Spinner",
+    "Menu",
+    "Tooltip",
+    "Popover",
+    "Card",
+    "Skeleton",
   ],
   // Beta folder names that are not simply the lowercased component name.
   betaFolders: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.16",
+  "version": "1.2.17",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/card/README.md

@@ -0,0 +1,60 @@
+# Card
+
+A surface that groups related content, plus `Stat` for a single figure. For
+React 19, with no runtime dependencies besides React.
+
+```ts
+import { Card, CardHeader, CardBody, CardFooter, Stat, trendDirection } from "@/components/card";
+import "@/components/card/styles.css";
+```
+
+```tsx
+<Card>
+  <CardHeader title={<h3>Revenue</h3>} actions={<Menu trigger={<Button variant="ghost">…</Button>}>…</Menu>} />
+  <CardBody>
+    <Stat
+      label="This month"
+      value="£48,120"
+      trend={{ direction: trendDirection(12.4), label: "12.4%", description: "vs last month" }}
+    />
+  </CardBody>
+</Card>
+```
+
+## Card
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `variant` | `outlined` | `outlined`, `elevated` or `plain`. |
+| `padding` | `md` | `none`, `sm`, `md` or `lg`. |
+| `href` / `target` / `rel` | — | Makes the whole card a link. |
+| `interactive` | `false` | Hover and focus styles for a card clickable another way. |
+| `className`, `classNames`, `style` | — | Slots: `root`, `header`, `title`, `description`, `actions`, `body`, `footer`. |
+
+`CardHeader` takes `title`, `description` and `actions`. Pass your own heading
+element as the title — `<h3>Revenue</h3>` — so the page decides the level; a card
+is not always at the same depth in the outline.
+
+When `href` is set the card renders as an `<a>`, so keep other links and buttons
+out of it: nesting interactive elements is not valid HTML and traps the
+keyboard. Use `interactive` with your own handler instead.
+
+## Stat
+
+| Prop | Description |
+| --- | --- |
+| `label` / `value` | Always both: a number on its own means nothing. |
+| `trend` | `{ direction, label, invert?, description? }`. |
+| `help` | A note under the figure. |
+| `icon` | Drawn beside the label. |
+| `loading` | Placeholder bars, announced as "Loading". |
+
+`trend.invert` is for figures where down is the good outcome, such as churn or
+error rates: it changes the colour, and the arrow still points the way the
+number actually moved. The direction is also written out for screen readers, so
+the meaning never rests on colour alone.
+
+`trendDirection(change, threshold?)`, `isPositive(direction, invert?)` and
+`percentChange(from, to)` are framework-free helpers in `core/trend.ts`.
+`percentChange` returns `null` when the starting value is zero, because growth
+from nothing is not a percentage.

package/source/beta-components/card/__tests__/core.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { isPositive, percentChange, trendDirection } from "../core/trend";
+
+describe("trendDirection", () => {
+  it("reads the sign of the change", () => {
+    expect(trendDirection(4.2)).toBe("up");
+    expect(trendDirection(-0.3)).toBe("down");
+    expect(trendDirection(0)).toBe("flat");
+  });
+
+  it("treats movement under the threshold as flat", () => {
+    expect(trendDirection(0.4, 0.5)).toBe("flat");
+    expect(trendDirection(-0.4, 0.5)).toBe("flat");
+    expect(trendDirection(0.6, 0.5)).toBe("up");
+  });
+
+  it("is flat for a value that is not a number", () => {
+    expect(trendDirection(Number.NaN)).toBe("flat");
+    expect(trendDirection(Number.POSITIVE_INFINITY)).toBe("flat");
+  });
+});
+
+describe("isPositive", () => {
+  it("treats up as good by default", () => {
+    expect(isPositive("up")).toBe(true);
+    expect(isPositive("down")).toBe(false);
+  });
+
+  it("flips for figures where down is the good outcome, such as churn", () => {
+    expect(isPositive("up", true)).toBe(false);
+    expect(isPositive("down", true)).toBe(true);
+  });
+
+  it("is null when nothing moved, so no colour is applied", () => {
+    expect(isPositive("flat")).toBeNull();
+    expect(isPositive("flat", true)).toBeNull();
+  });
+});
+
+describe("percentChange", () => {
+  it("is the change as a share of where it started", () => {
+    expect(percentChange(200, 250)).toBe(25);
+    expect(percentChange(200, 150)).toBe(-25);
+  });
+
+  it("measures against the size of a negative start", () => {
+    expect(percentChange(-200, -150)).toBe(25);
+  });
+
+  it("is null from zero, which has no percentage", () => {
+    expect(percentChange(0, 10)).toBeNull();
+  });
+
+  it("is null for values that are not numbers", () => {
+    expect(percentChange(Number.NaN, 10)).toBeNull();
+  });
+});

package/source/beta-components/card/core/index.ts

@@ -0,0 +1,4 @@
+// Framework-free: what counts as a rise or a fall.
+export { isPositive, percentChange, trendDirection } from "./trend";
+export type { TrendDirection } from "./trend";
+export type * from "./types";

package/source/beta-components/card/core/trend.ts

@@ -0,0 +1,32 @@
+export type TrendDirection = "up" | "down" | "flat";
+
+/** Whether a change counts as a rise, a fall, or no real movement. */
+export function trendDirection(change: number, threshold = 0): TrendDirection {
+  if (!Number.isFinite(change)) return "flat";
+  if (change > threshold) return "up";
+  if (change < -threshold) return "down";
+  return "flat";
+}
+
+/**
+ * Whether a direction should be drawn as good news.
+ *
+ * Up is usually good, but not for churn, refunds or error rates, so `invert`
+ * flips it. Colour alone never carries the meaning: the arrow and the label do
+ * too.
+ */
+export function isPositive(direction: TrendDirection, invert = false): boolean | null {
+  if (direction === "flat") return null;
+  return invert ? direction === "down" : direction === "up";
+}
+
+/**
+ * A change as a percentage of where it started.
+ *
+ * Returns null when there is nothing to compare against: growth from zero is
+ * not "infinite percent", it is simply not a percentage.
+ */
+export function percentChange(from: number, to: number): number | null {
+  if (!Number.isFinite(from) || !Number.isFinite(to) || from === 0) return null;
+  return ((to - from) / Math.abs(from)) * 100;
+}

package/source/beta-components/card/core/types.ts

@@ -0,0 +1,5 @@
+export type CardVariant = "outlined" | "elevated" | "plain";
+export type CardPadding = "none" | "sm" | "md" | "lg";
+
+export type CardSlot = "root" | "header" | "title" | "description" | "actions" | "body" | "footer";
+export type StatSlot = "root" | "label" | "value" | "trend" | "help" | "icon";

package/source/beta-components/card/index.ts

@@ -0,0 +1,5 @@
+export { Card, CardBody, CardFooter, CardHeader } from "./react/Card";
+export type { CardHeaderProps, CardProps } from "./react/Card";
+export { Stat } from "./react/Stat";
+export type { StatProps, StatTrend } from "./react/Stat";
+export * from "./core";

package/source/beta-components/card/react/Card.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import type { AnchorHTMLAttributes, CSSProperties, HTMLAttributes, ReactNode, Ref } from "react";
+import type { CardPadding, CardSlot, CardVariant } from "../core/types";
+import { cx } from "./props";
+
+export interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  children?: ReactNode;
+  /** Default `outlined`. */
+  variant?: CardVariant;
+  /** Padding applied to the header, body and footer. Default `md`. */
+  padding?: CardPadding;
+  /**
+   * Makes the whole card a link. The card becomes an `<a>`, so keep any other
+   * interactive content out of it — nested links and buttons are not valid.
+   */
+  href?: string;
+  /** Passed through when `href` is set. */
+  target?: AnchorHTMLAttributes<HTMLAnchorElement>["target"];
+  rel?: string;
+  /** Lifts the card on hover, for a card that is clickable by other means. */
+  interactive?: boolean;
+  className?: string;
+  classNames?: Partial<Record<CardSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLElement>;
+}
+
+/**
+ * A surface that groups related content, with optional header, body and footer.
+ *
+ * Give it a heading through `CardHeader` rather than a bare `title` prop, so the
+ * page decides the heading level: a card is not always at the same depth.
+ */
+export function Card(props: CardProps) {
+  const {
+    ref,
+    children,
+    variant = "outlined",
+    padding = "md",
+    href,
+    target,
+    rel,
+    interactive = false,
+    className,
+    classNames,
+    style,
+    ...rest
+  } = props;
+
+  const shared = {
+    className: cx("cd-root", classNames?.root, className),
+    style,
+    "data-variant": variant,
+    "data-padding": padding,
+    "data-interactive": (interactive || href !== undefined) || undefined,
+    ...rest,
+  };
+
+  if (href !== undefined) {
+    return (
+      <a
+        {...shared}
+        ref={ref as Ref<HTMLAnchorElement>}
+        href={href}
+        target={target}
+        // Anything opening a new tab gets the safe default unless told otherwise.
+        rel={rel ?? (target === "_blank" ? "noreferrer" : undefined)}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <div {...shared} ref={ref as Ref<HTMLDivElement>}>
+      {children}
+    </div>
+  );
+}
+
+export interface CardHeaderProps {
+  /** The heading. Wrap it in your own `h2`/`h3` to set the level. */
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Buttons or a menu, aligned to the end of the header. */
+  actions?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+  classNames?: Partial<Record<CardSlot, string>>;
+}
+
+export function CardHeader({
+  title,
+  description,
+  actions,
+  children,
+  className,
+  classNames,
+}: CardHeaderProps) {
+  return (
+    <div className={cx("cd-header", classNames?.header, className)}>
+      <div className="cd-heading">
+        {title && <div className={cx("cd-title", classNames?.title)}>{title}</div>}
+        {description && (
+          <div className={cx("cd-description", classNames?.description)}>{description}</div>
+        )}
+        {children}
+      </div>
+      {actions && <div className={cx("cd-actions", classNames?.actions)}>{actions}</div>}
+    </div>
+  );
+}
+
+export function CardBody({
+  children,
+  className,
+}: {
+  children?: ReactNode;
+  className?: string;
+}) {
+  return <div className={cx("cd-body", className)}>{children}</div>;
+}
+
+export function CardFooter({
+  children,
+  className,
+}: {
+  children?: ReactNode;
+  className?: string;
+}) {
+  return <div className={cx("cd-footer", className)}>{children}</div>;
+}

package/source/beta-components/card/react/Stat.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { useId, type CSSProperties, type ReactNode } from "react";
+import { isPositive, type TrendDirection } from "../core/trend";
+import type { StatSlot } from "../core/types";
+import { cx } from "./props";
+
+export interface StatTrend {
+  /** `up`, `down` or `flat`. `trendDirection(change)` works this out for you. */
+  direction: TrendDirection;
+  /** What is shown beside the arrow, already formatted, e.g. "12.4%". */
+  label: ReactNode;
+  /**
+   * Down is the good outcome for this figure, as with churn or error rates.
+   * Only changes the colour; the arrow still points the way the number moved.
+   */
+  invert?: boolean;
+  /** Read out after the change, e.g. "since last month". */
+  description?: ReactNode;
+}
+
+export interface StatProps {
+  /** What the figure is. Always visible — a number alone means nothing. */
+  label: ReactNode;
+  value: ReactNode;
+  trend?: StatTrend;
+  /** A note under the figure. */
+  help?: ReactNode;
+  icon?: ReactNode;
+  /** Shows placeholder bars instead of the figure. */
+  loading?: boolean;
+  className?: string;
+  classNames?: Partial<Record<StatSlot, string>>;
+  style?: CSSProperties;
+}
+
+const ARROWS: Record<TrendDirection, string> = {
+  up: "M12 19V5M5 12l7-7 7 7",
+  down: "M12 5v14M19 12l-7 7-7-7",
+  flat: "M5 12h14",
+};
+
+/** The word behind the arrow, so the direction is not carried by colour alone. */
+const DIRECTION_TEXT: Record<TrendDirection, string> = {
+  up: "Up",
+  down: "Down",
+  flat: "No change",
+};
+
+/**
+ * A single figure with its label and, optionally, how it has changed.
+ *
+ * Put it inside a `Card` for a dashboard tile, or use it on its own in a row of
+ * summary numbers.
+ */
+export function Stat(props: StatProps) {
+  const { label, value, trend, help, icon, loading = false, className, classNames, style } = props;
+  const id = useId();
+  const positive = trend ? isPositive(trend.direction, trend.invert) : null;
+
+  return (
+    <div
+      className={cx("st-root", classNames?.root, className)}
+      style={style}
+      data-loading={loading || undefined}
+    >
+      <div className="st-head">
+        <span id={`${id}-label`} className={cx("st-label", classNames?.label)}>
+          {label}
+        </span>
+        {icon && (
+          <span className={cx("st-icon", classNames?.icon)} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+      </div>
+
+      {loading ? (
+        <>
+          <div className="st-placeholder st-placeholder-value" />
+          <div className="st-placeholder st-placeholder-help" />
+          <span className="st-sr-only">Loading</span>
+        </>
+      ) : (
+        <>
+          <div
+            className={cx("st-value", classNames?.value)}
+            aria-labelledby={`${id}-label`}
+            role="figure"
+          >
+            {value}
+          </div>
+
+          {trend && (
+            <div
+              className={cx("st-trend", classNames?.trend)}
+              data-direction={trend.direction}
+              data-positive={positive === null ? undefined : positive}
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+                focusable="false"
+              >
+                <path d={ARROWS[trend.direction]} />
+              </svg>
+              <span className="st-sr-only">{DIRECTION_TEXT[trend.direction]}</span>
+              <span className="st-trend-label">{trend.label}</span>
+              {trend.description && (
+                <span className="st-trend-description">{trend.description}</span>
+              )}
+            </div>
+          )}
+
+          {help && <div className={cx("st-help", classNames?.help)}>{help}</div>}
+        </>
+      )}
+    </div>
+  );
+}

package/source/beta-components/card/react/props.ts

@@ -0,0 +1,4 @@
+export type { CardSlot, StatSlot } from "../core/types";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";