gbs-add-block 1.2.15 → 1.2.17

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.15)
+# 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.15)
+## What's New 🎉 (Ver 1.2.17)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -2,6 +2,7 @@
 
 const fs = require("fs-extra");
 const path = require("path");
+const crypto = require("crypto");
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
 const readline = require("readline");
@@ -50,7 +51,18 @@ const CONFIG = {
     "Checkbox",
     "Tabs",
     "Spinner",
+    "Menu",
+    "Tooltip",
+    "Popover",
+    "Card",
+    "Skeleton",
   ],
+  // Beta folder names that are not simply the lowercased component name.
+  betaFolders: {
+    DataGrid: "data-grid",
+    DatePicker: "date-picker",
+    FileUploader: "file-uploader",
+  },
   // Define component dependencies
   dependencies: {
     FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker"],
@@ -62,6 +74,24 @@ const SOURCE_PATH = path.join(__dirname, "source", "components");
 const BETA_SOURCE_PATH = path.join(__dirname, "source", "beta-components");
 const DEFAULT_DEST_PATH = path.join(process.cwd(), "component-lib");
 
+/**
+ * Every beta component imports its shared helpers from `../../shared`, so this
+ * folder is installed alongside whatever the user picked. It is not a component
+ * and never appears in the component list.
+ */
+const SHARED_DIR = "shared";
+const MANIFEST_FILE = ".install-manifest.json";
+
+/**
+ * Tests belong to this repo, not to the projects we install into: they import
+ * vitest, which the project has no reason to have, and the shared folder's
+ * boundary tests would run against whatever else is in the user's
+ * component-lib.
+ */
+const TESTS_DIR = "__tests__";
+const isTestPath = (filePath) =>
+  filePath.split(/[\\/]/).includes(TESTS_DIR);
+
 const normalizeComponent = (component, availableComponents) =>
   availableComponents.find(
     (available) => available.toLowerCase() === component.toLowerCase(),
@@ -72,6 +102,10 @@ const getAvailableComponents = (beta = false) =>
 
 const getSourcePath = (beta = false) => (beta ? BETA_SOURCE_PATH : SOURCE_PATH);
 
+/** The folder a component lives in, which is not always its lowercased name. */
+const folderFor = (component, beta = false) =>
+  (beta && CONFIG.betaFolders[component]) || component.toLowerCase();
+
 const copyCommonFiles = async (destPath) => {
   const commonFiles = [
     { src: ["..", "utils.ts"], dest: "utils.ts" },
@@ -88,18 +122,171 @@ const copyCommonFiles = async (destPath) => {
   }
 };
 
-const checkComponentExists = (component, destPath) => {
-  const componentPath = path.join(destPath, component.toLowerCase());
+/* ------------------------------------------------------------ shared folder */
+
+const sha256 = (filePath) =>
+  crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+
+/** Every file under a directory, relative to it, with "/" separators. */
+const listFiles = (dir, prefix = "") =>
+  fs
+    .readdirSync(path.join(dir, prefix), { withFileTypes: true })
+    .flatMap((entry) => {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.name === MANIFEST_FILE || entry.name === TESTS_DIR) return [];
+      return entry.isDirectory() ? listFiles(dir, relative) : [relative];
+    });
+
+/** -1, 0 or 1, comparing dotted numeric versions such as "1.2.0". */
+const compareVersions = (a, b) => {
+  const left = String(a).split(".").map(Number);
+  const right = String(b).split(".").map(Number);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+};
+
+const readJson = (filePath, fallback = null) => {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+};
+
+/** Files the manifest says we wrote, whose contents have since changed. */
+const locallyEdited = (dest, manifest) =>
+  !manifest
+    ? []
+    : Object.keys(manifest.files).filter((file) => {
+        const target = path.join(dest, file);
+        return fs.existsSync(target) && manifest.files[file] !== sha256(target);
+      });
+
+/**
+ * Installs or updates `shared/`.
+ *
+ * Because components are copied into a project one at a time, a project can end
+ * up with components built against different versions of this folder. The rules
+ * are that `shared/` only ever moves forward, and that a file the user has
+ * edited since we wrote it is never replaced without `--force`.
+ */
+const installShared = async (destPath, { force = false } = {}) => {
+  const src = path.join(BETA_SOURCE_PATH, SHARED_DIR);
+  const dest = path.join(destPath, SHARED_DIR);
+
+  if (!fs.existsSync(src)) {
+    throw new Error(
+      `The shared folder is missing from ${BETA_SOURCE_PATH}. Beta components cannot be installed without it.`,
+    );
+  }
+
+  const srcVersion =
+    (readJson(path.join(src, "version.json"), {}) || {}).version || "0.0.0";
+  const manifest = readJson(path.join(dest, MANIFEST_FILE));
+  const installedVersion = manifest ? manifest.version : null;
+  const edited = locallyEdited(dest, manifest);
+
+  if (installedVersion && !force) {
+    const order = compareVersions(installedVersion, srcVersion);
+
+    if (order > 0) {
+      console.error(
+        `\n✗ This project has shared v${installedVersion}, newer than the v${srcVersion} in this installer.`,
+      );
+      console.error(
+        "  Installing it would downgrade the folder and break the components already here.",
+      );
+      console.error("  Update the CLI, or re-run with --force to overwrite it anyway.");
+      process.exit(1);
+    }
+
+    if (order === 0) {
+      console.log(
+        edited.length > 0
+          ? `✓ shared v${installedVersion} is already installed (keeping your ${edited.length} edited file(s))`
+          : `✓ shared v${installedVersion} is already installed`,
+      );
+      return;
+    }
+  }
+
+  if (edited.length > 0 && !force) {
+    console.error(
+      `\n✗ These files in component-lib/${SHARED_DIR} have local changes:`,
+    );
+    edited.forEach((file) => console.error(`  - ${file}`));
+    console.error(
+      "\n  Updating shared/ would replace them. Re-run with --force to do that, or move",
+    );
+    console.error(
+      "  your changes into your own module first: components are yours to edit,",
+    );
+    console.error("  shared/ is replaced on every update.");
+    process.exit(1);
+  }
+
+  const files = listFiles(src);
+  for (const file of files) {
+    await fs.copy(path.join(src, file), path.join(dest, file), { overwrite: true });
+  }
+
+  // Remove what an older version left behind, but only files we installed and
+  // the user has not since changed.
+  if (manifest) {
+    const removed = Object.keys(manifest.files).filter((file) => !files.includes(file));
+    for (const file of removed) {
+      const target = path.join(dest, file);
+      if (fs.existsSync(target) && (force || manifest.files[file] === sha256(target))) {
+        await fs.remove(target);
+      }
+    }
+  }
+
+  fs.writeJsonSync(
+    path.join(dest, MANIFEST_FILE),
+    {
+      version: srcVersion,
+      installedAt: new Date().toISOString(),
+      files: Object.fromEntries(
+        files.map((file) => [file, sha256(path.join(src, file))]),
+      ),
+    },
+    { spaces: 2 },
+  );
+
+  console.log(
+    installedVersion
+      ? `✓ shared updated ${installedVersion} → ${srcVersion}`
+      : `✓ shared v${srcVersion} installed`,
+  );
+};
+
+/** The files a component needs beside it, which differ between the two sets. */
+const copySupportFiles = async (destPath, beta, options) => {
+  if (beta) {
+    await installShared(destPath, options);
+    return;
+  }
+  // The legacy components' common files. Beta components use none of them.
+  if (!fs.existsSync(path.join(destPath, "utils.ts"))) {
+    await copyCommonFiles(destPath);
+  }
+};
+
+/* -------------------------------------------------------------- components */
+
+const checkComponentExists = (component, destPath, beta = false) => {
+  const componentPath = path.join(destPath, folderFor(component, beta));
   return fs.existsSync(componentPath);
 };
 
 const copyComponent = async (component, destPath, beta = false) => {
   try {
-    const componentSrc = path.join(
-      getSourcePath(beta),
-      component.toLowerCase(),
-    );
-    const componentDest = path.join(destPath, component.toLowerCase());
+    const componentSrc = path.join(getSourcePath(beta), folderFor(component, beta));
+    const componentDest = path.join(destPath, folderFor(component, beta));
 
     if (!fs.existsSync(componentSrc)) {
       throw new Error(
@@ -107,7 +294,10 @@ const copyComponent = async (component, destPath, beta = false) => {
       );
     }
 
-    await fs.copy(componentSrc, componentDest, { overwrite: true });
+    await fs.copy(componentSrc, componentDest, {
+      overwrite: true,
+      filter: (source) => !isTestPath(path.relative(componentSrc, source)),
+    });
     console.log(
       `✓ Component ${component} installed successfully ${
         component === "Grid"
@@ -134,7 +324,7 @@ const installComponentWithDependencies = async (
   const pendingInstalls = beta
     ? Array.from(componentsToInstall)
     : Array.from(componentsToInstall).filter(
-        (comp) => !checkComponentExists(comp, destPath),
+        (comp) => !checkComponentExists(comp, destPath, beta),
       );
 
   if (pendingInstalls.length === 0) {
@@ -177,7 +367,7 @@ const installMultipleComponents = async (
   const pendingInstalls = beta
     ? Array.from(allComponentsToInstall)
     : Array.from(allComponentsToInstall).filter(
-        (comp) => !checkComponentExists(comp, destPath),
+        (comp) => !checkComponentExists(comp, destPath, beta),
       );
 
   if (pendingInstalls.length === 0) {
@@ -254,11 +444,11 @@ const interactiveComponentSelector = async (beta = false) => {
 
     const handleKeyPress = (key) => {
       switch (key) {
-        case "\u001b[A": // Up arrow
+        case "": // Up arrow
           currentIndex = Math.max(0, currentIndex - 1);
           renderMenu();
           break;
-        case "\u001b[B": // Down arrow
+        case "": // Down arrow
           currentIndex = Math.min(
             getAvailableComponents(beta).length - 1,
             currentIndex + 1,
@@ -315,6 +505,11 @@ const validateComponents = (components, beta = false) => {
     (comp) => !availableComponents.includes(comp),
   );
   if (invalidComponents.length > 0) {
+    if (invalidComponents.some((comp) => comp.toLowerCase() === SHARED_DIR)) {
+      console.error(
+        "`shared` is not a component: it is installed automatically with any beta component.",
+      );
+    }
     console.error(`Invalid components: ${invalidComponents.join(", ")}`);
     console.log(`\nAvailable ${beta ? "beta " : ""}components:`);
     availableComponents.forEach((comp) => console.log(`- ${comp}`));
@@ -353,6 +548,11 @@ const main = async () => {
       type: "boolean",
       default: false,
     })
+    .option("force", {
+      describe: "Replace files in shared/ that you have edited locally",
+      type: "boolean",
+      default: false,
+    })
     .example("$0 -a Button", "Install a single component")
     .example("$0 -a Button,Card,Modal", "Install multiple components")
     .example("$0 -a DataGrid -beta", "Install the redesigned beta DataGrid")
@@ -370,7 +570,11 @@ const main = async () => {
         : "";
       console.log(`- ${comp}${deps}`);
     });
-    if (!argv.beta) {
+    if (argv.beta) {
+      console.log(
+        `\nEvery beta component also installs component-lib/${SHARED_DIR}, which they all import.`,
+      );
+    } else {
       console.log("\nRedesigned beta components (install with -beta):");
       CONFIG.betaComponents.forEach((comp) => console.log(`- ${comp}`));
     }
@@ -391,10 +595,7 @@ const main = async () => {
     const destPath = DEFAULT_DEST_PATH;
     await fs.ensureDir(destPath);
 
-    // Copy common files if they don't exist
-    if (!fs.existsSync(path.join(destPath, "utils.ts"))) {
-      await copyCommonFiles(destPath);
-    }
+    await copySupportFiles(destPath, argv.beta, { force: argv.force });
 
     // Install selected components
     await installMultipleComponents(selectedComponents, destPath, argv.beta);
@@ -425,10 +626,7 @@ const main = async () => {
   const destPath = DEFAULT_DEST_PATH;
   await fs.ensureDir(destPath);
 
-  // Copy common files if they don't exist
-  if (!fs.existsSync(path.join(destPath, "utils.ts"))) {
-    await copyCommonFiles(destPath);
-  }
+  await copySupportFiles(destPath, argv.beta, { force: argv.force });
 
   // Install components
   if (components.length === 1) {

package/package.json

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

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

@@ -10,5 +10,5 @@ export interface BreadcrumbLinkProps {
   onClick?: MouseEventHandler<HTMLAnchorElement>;
 }
 
-export const cx = (...names: (string | false | null | undefined)[]) =>
-  names.filter(Boolean).join(" ");
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/beta-components/breadcrumb/styles.css

@@ -1,20 +1,20 @@
 /*
  * Breadcrumb styles.
  *
- * Tokens read the DataGrid's --dg-* variables when they are set on an ancestor
- * (set them on :root to share one theme) and fall back to the same palette
- * otherwise. Rules live in the `components` layer, so utility classes passed
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules live in the `components` layer, so utility classes passed
  * through `className` / `classNames` override them.
  */
 @layer theme, base, components, utilities;
 
 @layer components {
   .bc-root {
-    --bc-fg: var(--dg-fg, light-dark(#18181b, #f4f4f5));
-    --bc-muted: var(--dg-muted, light-dark(#71717a, #a1a1aa));
-    --bc-hover: var(--dg-hover, light-dark(#f4f4f5, #1f1f23));
-    --bc-focus: var(--dg-focus, light-dark(#2563eb, #60a5fa));
-    --bc-font-size: var(--dg-font-size, 13px);
+    --bc-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --bc-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --bc-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --bc-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --bc-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
     /* Long labels are cut with an ellipsis; the full text is in the tooltip. */
     --bc-max-label: 24ch;
 

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

@@ -19,5 +19,5 @@ export interface ButtonRenderProps {
   [attribute: string]: unknown;
 }
 
-export const cx = (...names: (string | false | null | undefined)[]) =>
-  names.filter(Boolean).join(" ");
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/beta-components/button/styles.css

@@ -1,27 +1,27 @@
 /*
  * Button styles.
  *
- * Tokens read the DataGrid's --dg-* variables when they are set on an ancestor
- * (set them on :root to share one theme) and fall back to the same palette
- * otherwise. Rules live in the `components` layer, so utility classes passed
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules live in the `components` layer, so utility classes passed
  * through `className` / `classNames` override them.
  */
 @layer theme, base, components, utilities;
 
 @layer components {
   .bt-root {
-    --bt-bg: var(--dg-bg, light-dark(#ffffff, #0b0b0e));
-    --bt-fg: var(--dg-fg, light-dark(#18181b, #f4f4f5));
-    --bt-border: var(--dg-border, light-dark(#e4e4e7, #27272a));
-    --bt-hover: var(--dg-hover, light-dark(#f4f4f5, #1f1f23));
-    --bt-subtle: light-dark(#f4f4f5, #1c1c20);
-    --bt-accent: var(--dg-accent, light-dark(#2563eb, #60a5fa));
-    --bt-accent-fg: var(--dg-accent-fg, light-dark(#ffffff, #0b1220));
-    --bt-danger: var(--dg-danger, light-dark(#dc2626, #f87171));
-    --bt-danger-fg: light-dark(#ffffff, #1c0606);
-    --bt-focus: var(--dg-focus, light-dark(#2563eb, #60a5fa));
-    --bt-radius: var(--dg-radius, 8px);
-    --bt-font-size: var(--dg-font-size, 13px);
+    --bt-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+    --bt-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --bt-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --bt-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --bt-subtle: var(--gbs-subtle, light-dark(#f4f4f5, #1c1c20));
+    --bt-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+    --bt-accent-fg: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+    --bt-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --bt-danger-fg: var(--gbs-danger-fg, light-dark(#ffffff, #1c0606));
+    --bt-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --bt-radius: var(--gbs-radius, var(--dg-radius, 8px));
+    --bt-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
     --bt-height: 36px;
     --bt-px: 14px;
     --bt-gap: 8px;

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";