gbs-add-block 1.2.15 → 1.2.17

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

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

@@ -0,0 +1,231 @@
+/*
+ * Card and Stat styles.
+ *
+ * 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 {
+  .cd-root,
+  .st-root {
+    --cd-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+    --cd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --cd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --cd-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --cd-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --cd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --cd-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+    --cd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --cd-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+    --cd-radius: var(--gbs-radius, var(--dg-radius, 8px));
+    --cd-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+    --cd-px: 16px;
+
+    color-scheme: inherit;
+    font-size: var(--cd-font-size);
+    line-height: 1.5;
+    color: var(--cd-fg);
+  }
+
+  :where(.dark, [data-theme="dark"]) :is(.cd-root, .st-root) {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) :is(.cd-root, .st-root) {
+    color-scheme: light;
+  }
+
+  :where(.cd-root, .st-root) *,
+  :where(.cd-root, .st-root) *::before,
+  :where(.cd-root, .st-root) *::after {
+    box-sizing: border-box;
+  }
+
+  /* ---------------------------------------------------------------- card */
+
+  .cd-root {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    border-radius: var(--cd-radius);
+    background: var(--cd-bg);
+    text-decoration: none;
+  }
+  .cd-root[data-variant="outlined"] {
+    border: 1px solid var(--cd-border);
+  }
+  .cd-root[data-variant="elevated"] {
+    border: 1px solid transparent;
+    box-shadow: var(--cd-shadow);
+  }
+  .cd-root[data-variant="plain"] {
+    background: transparent;
+  }
+
+  .cd-root[data-padding="none"] {
+    --cd-px: 0px;
+  }
+  .cd-root[data-padding="sm"] {
+    --cd-px: 12px;
+  }
+  .cd-root[data-padding="lg"] {
+    --cd-px: 24px;
+  }
+
+  .cd-root[data-interactive] {
+    cursor: pointer;
+    transition:
+      background-color 120ms ease,
+      box-shadow 120ms ease,
+      translate 120ms ease;
+  }
+  .cd-root[data-interactive]:hover {
+    background: var(--cd-hover);
+  }
+  .cd-root[data-variant="elevated"][data-interactive]:hover {
+    translate: 0 -1px;
+  }
+  .cd-root[data-interactive]:focus-visible {
+    outline: 2px solid var(--cd-focus);
+    outline-offset: 2px;
+  }
+
+  .cd-header {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    padding: var(--cd-px) var(--cd-px) 0;
+  }
+  .cd-heading {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+  .cd-title {
+    font-size: 1.05em;
+    font-weight: 600;
+    line-height: 1.35;
+  }
+  .cd-description {
+    margin-top: 2px;
+    color: var(--cd-muted);
+  }
+  .cd-actions {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: 4px;
+  }
+
+  .cd-body {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: var(--cd-px);
+  }
+  /* The header already spaces the top, so the body should not double it. */
+  .cd-header + .cd-body {
+    padding-top: 12px;
+  }
+
+  .cd-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px;
+    padding: 12px var(--cd-px);
+    border-top: 1px solid var(--cd-border);
+  }
+
+  /* ---------------------------------------------------------------- stat */
+
+  .st-root {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+  }
+  .st-head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .st-label {
+    flex: 1 1 auto;
+    min-width: 0;
+    color: var(--cd-muted);
+    font-weight: 500;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .st-icon {
+    display: inline-flex;
+    flex: none;
+    color: var(--cd-muted);
+  }
+  .st-value {
+    font-size: 1.9em;
+    font-weight: 650;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.15;
+    letter-spacing: -0.01em;
+  }
+
+  .st-trend {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    color: var(--cd-muted);
+  }
+  /* Colour is a second signal: the arrow and the visually hidden word carry
+     the direction on their own. */
+  .st-trend[data-positive="true"] {
+    color: var(--cd-success);
+  }
+  .st-trend[data-positive="false"] {
+    color: var(--cd-danger);
+  }
+  .st-trend-label {
+    font-variant-numeric: tabular-nums;
+    font-weight: 500;
+  }
+  .st-trend-description {
+    color: var(--cd-muted);
+  }
+
+  .st-help {
+    color: var(--cd-muted);
+  }
+
+  .st-placeholder {
+    border-radius: 4px;
+    background: var(--cd-hover);
+  }
+  .st-placeholder-value {
+    width: 5ch;
+    height: 1.9em;
+  }
+  .st-placeholder-help {
+    width: 10ch;
+    height: 1em;
+  }
+
+  .st-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    border: 0;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @media (forced-colors: active) {
+    .cd-root[data-variant="elevated"] {
+      border-color: CanvasText;
+    }
+  }
+}