@robr0/design-system 0.13.0 → 0.14.0

package/components/Gauge/Gauge.d.ts

@@ -15,9 +15,9 @@ type GaugeOwnProps = {
     /** Upper bound of the dial. */
     max?: number;
     /**
-     * Colour role for the value arc and reading. Ignored while a threshold
-     * matches — thresholds exist so the dial recolours itself as the reading
-     * crosses them.
+     * Colour role for the value arc. `accent` (the default) follows the chart
+     * palette's lead colour. Ignored while a threshold matches — thresholds
+     * exist so the dial recolours itself as the reading crosses them.
      */
     tone?: 'accent' | 'positive' | 'warning' | 'error' | 'neutral';
     /**
@@ -35,7 +35,13 @@ type GaugeOwnProps = {
      * accessible name, e.g. "CPU usage".
      */
     label?: string;
-    /** Rendered diameter in pixels. The arc geometry scales with it. */
+    /** Chart title, in the shared chart header. */
+    title?: string;
+    /** Description text below the title. */
+    subtitle?: string;
+    /** Strip the card chrome (border, padding, fill) when the chart sits inside another panel that supplies the surface */
+    bare?: boolean;
+    /** Rendered dial diameter in pixels. The arc geometry scales with it. */
     size?: number;
     /** Arc thickness in pixels. */
     strokeWidth?: number;
@@ -47,10 +53,12 @@ export interface GaugeProps extends GaugeOwnProps, Omit<React.ComponentPropsWith
 /**
  * Gauge — a radial dial for a single bounded reading: capacity, usage, a
  * score against a target. Pure SVG computed from props — no charting library,
- * no hooks — so it renders from a Server Component and drops straight into a
- * Panel or Stat row. Thresholds recolour the dial through the status roles as
- * the reading crosses them, and the arc animates between readings via a CSS
- * transition. Announced as a `meter` with the label as its accessible name.
+ * no hooks — so it renders from a Server Component. It wears the chart
+ * family's card chrome (title, subtitle, padding) and takes `bare` to drop
+ * it inside a Panel, like every other chart. Thresholds recolour the dial
+ * through the status roles as the reading crosses them, and the arc animates
+ * between readings via a CSS transition. The dial is announced as a `meter`
+ * with the label as its accessible name.
  */
 export declare const Gauge: React.ForwardRefExoticComponent<GaugeProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/components/Gauge/Gauge.js

@@ -1,5 +1,6 @@
 import { jsxs, jsx } from "react/jsx-runtime";
 import React from "react";
+import "../Chart/Chart.css";
 import "./Gauge.css";
 const SWEEP_UNITS = 75;
 const Gauge = React.forwardRef(
@@ -12,81 +13,96 @@ const Gauge = React.forwardRef(
     showValue = true,
     formatValue,
     label,
+    title,
+    subtitle,
+    bare = false,
     size = 120,
-    strokeWidth = 10,
+    strokeWidth = 12,
     className = "",
     ...rest
   }, ref) => {
     const baseClass = "ds-gauge";
+    const chartClass = "ds-chart";
     const range = max - min;
     const fraction = range > 0 ? Math.min(Math.max((value - min) / range, 0), 1) : 0;
     const activeThreshold = thresholds?.filter((t) => value >= t.value).sort((a, b) => b.value - a.value)[0];
     const resolvedTone = activeThreshold?.tone ?? tone;
-    const classes = [baseClass, `${baseClass}--${resolvedTone}`, className].filter(Boolean).join(" ");
+    const classes = [
+      chartClass,
+      bare && `${chartClass}--bare`,
+      baseClass,
+      `${baseClass}--${resolvedTone}`,
+      className
+    ].filter(Boolean).join(" ");
     const radius = (size - strokeWidth) / 2;
     const center = size / 2;
     const valueUnits = Math.round(SWEEP_UNITS * fraction * 100) / 100;
     const displayValue = formatValue ? formatValue(value) : String(Math.round(value));
-    return /* @__PURE__ */ jsxs(
-      "div",
-      {
-        ...rest,
-        ref,
-        className: classes,
-        style: { width: size, height: size, ...rest.style },
-        role: "meter",
-        "aria-valuenow": value,
-        "aria-valuemin": min,
-        "aria-valuemax": max,
-        "aria-valuetext": displayValue,
-        "aria-label": label ?? rest["aria-label"],
-        children: [
-          /* @__PURE__ */ jsxs(
-            "svg",
-            {
-              className: `${baseClass}__svg`,
-              viewBox: `0 0 ${size} ${size}`,
-              width: size,
-              height: size,
-              xmlns: "http://www.w3.org/2000/svg",
-              "aria-hidden": "true",
-              children: [
-                /* @__PURE__ */ jsx(
-                  "circle",
-                  {
-                    className: `${baseClass}__track`,
-                    cx: center,
-                    cy: center,
-                    r: radius,
-                    pathLength: 100,
-                    strokeWidth,
-                    strokeDasharray: `${SWEEP_UNITS} ${100 - SWEEP_UNITS}`,
-                    transform: `rotate(135 ${center} ${center})`
-                  }
-                ),
-                valueUnits > 0 && /* @__PURE__ */ jsx(
-                  "circle",
-                  {
-                    className: `${baseClass}__arc`,
-                    cx: center,
-                    cy: center,
-                    r: radius,
-                    pathLength: 100,
-                    strokeWidth,
-                    strokeDasharray: `${valueUnits} ${100 - valueUnits}`,
-                    transform: `rotate(135 ${center} ${center})`
-                  }
-                )
-              ]
-            }
-          ),
-          (showValue || label) && /* @__PURE__ */ jsxs("div", { className: `${baseClass}__center`, children: [
-            showValue && /* @__PURE__ */ jsx("span", { className: `${baseClass}__value`, children: displayValue }),
-            label && /* @__PURE__ */ jsx("span", { className: `${baseClass}__label`, children: label })
-          ] })
-        ]
-      }
-    );
+    const { "aria-label": restAriaLabel, ...restProps } = rest;
+    return /* @__PURE__ */ jsxs("div", { ...restProps, ref, className: classes, children: [
+      (title || subtitle) && /* @__PURE__ */ jsx("div", { className: `${chartClass}__header`, children: /* @__PURE__ */ jsxs("div", { className: `${chartClass}__header-text`, children: [
+        title && /* @__PURE__ */ jsx("h3", { className: `${chartClass}__title`, children: title }),
+        subtitle && /* @__PURE__ */ jsx("p", { className: `${chartClass}__subtitle`, children: subtitle })
+      ] }) }),
+      /* @__PURE__ */ jsx("div", { className: `${chartClass}__body ${baseClass}__body`, children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          className: `${baseClass}__dial`,
+          style: { width: size, height: size },
+          role: "meter",
+          "aria-valuenow": value,
+          "aria-valuemin": min,
+          "aria-valuemax": max,
+          "aria-valuetext": displayValue,
+          "aria-label": label ?? restAriaLabel,
+          children: [
+            /* @__PURE__ */ jsxs(
+              "svg",
+              {
+                className: `${baseClass}__svg`,
+                viewBox: `0 0 ${size} ${size}`,
+                width: size,
+                height: size,
+                xmlns: "http://www.w3.org/2000/svg",
+                "aria-hidden": "true",
+                children: [
+                  /* @__PURE__ */ jsx(
+                    "circle",
+                    {
+                      className: `${baseClass}__track`,
+                      cx: center,
+                      cy: center,
+                      r: radius,
+                      pathLength: 100,
+                      strokeWidth,
+                      strokeDasharray: `${SWEEP_UNITS} ${100 - SWEEP_UNITS}`,
+                      transform: `rotate(135 ${center} ${center})`
+                    }
+                  ),
+                  valueUnits > 0 && /* @__PURE__ */ jsx(
+                    "circle",
+                    {
+                      className: `${baseClass}__arc`,
+                      cx: center,
+                      cy: center,
+                      r: radius,
+                      pathLength: 100,
+                      strokeWidth,
+                      strokeDasharray: `${valueUnits} ${100 - valueUnits}`,
+                      transform: `rotate(135 ${center} ${center})`
+                    }
+                  )
+                ]
+              }
+            ),
+            (showValue || label) && /* @__PURE__ */ jsxs("div", { className: `${baseClass}__center`, children: [
+              showValue && /* @__PURE__ */ jsx("span", { className: `${baseClass}__value`, children: displayValue }),
+              label && /* @__PURE__ */ jsx("span", { className: `${baseClass}__label`, children: label })
+            ] })
+          ]
+        }
+      ) })
+    ] });
   }
 );
 Gauge.displayName = "Gauge";

package/components/HoverCard/HoverCard.css

@@ -0,0 +1,97 @@
+/* ============================================
+   HOVER CARD COMPONENT
+   Rich preview panel on hover / focus
+   ============================================ */
+
+.ds-hover-card {
+  position: relative;
+  display: inline-flex;
+}
+
+/* ============================================
+   PANEL
+   Dresses like the other floating panels:
+   page-primary fill, hairline, radius-sm,
+   floating shadow (see Popover).
+   ============================================ */
+
+.ds-hover-card__panel {
+  /* Rendered as a <span> so the card survives inside a <p>; absolute
+     positioning already computes display to block, stated here anyway. */
+  display: block;
+  position: absolute;
+  z-index: 50;
+  min-width: 240px;
+  max-width: 320px;
+  padding: var(--padding-md);
+  border-radius: var(--radius-sm);
+  background-color: var(--color-bg-page-primary);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  box-shadow: var(--shadow-floating);
+  color: var(--color-text-primary);
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  /* visibility keeps the hidden panel out of the accessibility tree and
+     tab order; opacity + transform carry the entrance. */
+  visibility: hidden;
+  opacity: 0;
+  transition:
+    opacity var(--motion-duration-fast) var(--motion-ease-standard),
+    transform var(--motion-duration-fast) var(--motion-ease-standard),
+    visibility var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-hover-card__panel--visible {
+  visibility: visible;
+  opacity: 1;
+}
+
+/* ============================================
+   POSITIONS
+   ============================================ */
+
+.ds-hover-card__panel--top {
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%) translateY(4px);
+  margin-bottom: var(--gap-xs);
+}
+
+.ds-hover-card__panel--top.ds-hover-card__panel--visible {
+  transform: translateX(-50%) translateY(0);
+}
+
+.ds-hover-card__panel--bottom {
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%) translateY(-4px);
+  margin-top: var(--gap-xs);
+}
+
+.ds-hover-card__panel--bottom.ds-hover-card__panel--visible {
+  transform: translateX(-50%) translateY(0);
+}
+
+.ds-hover-card__panel--left {
+  right: 100%;
+  top: 50%;
+  transform: translateY(-50%) translateX(4px);
+  margin-right: var(--gap-xs);
+}
+
+.ds-hover-card__panel--left.ds-hover-card__panel--visible {
+  transform: translateY(-50%) translateX(0);
+}
+
+.ds-hover-card__panel--right {
+  left: 100%;
+  top: 50%;
+  transform: translateY(-50%) translateX(-4px);
+  margin-left: var(--gap-xs);
+}
+
+.ds-hover-card__panel--right.ds-hover-card__panel--visible {
+  transform: translateY(-50%) translateX(0);
+}

package/components/HoverCard/HoverCard.d.ts

@@ -0,0 +1,29 @@
+import { default as React } from 'react';
+type HoverCardOwnProps = {
+    /** Trigger element */
+    children?: React.ReactNode;
+    /** Panel content — arbitrary elements, unlike Tooltip's plain text. In running text inside a `<p>`, keep it phrasing-level (spans): a block element would end the paragraph mid-parse. */
+    content: React.ReactNode;
+    /** Preferred position */
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Delay before showing (in ms) */
+    showDelay?: number;
+    /** Delay before hiding (in ms) */
+    hideDelay?: number;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface HoverCardProps extends HoverCardOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof HoverCardOwnProps> {
+}
+/**
+ * Rich preview panel that opens from hover or focus — a profile card behind
+ * a username, a component summary behind a link. Where Tooltip names a
+ * control in a line of text, HoverCard previews a destination; its panel is
+ * interactive, stays open while the pointer is inside it, and dresses like
+ * the other floating panels (Popover, the menus).
+ *
+ * The hidden panel is `visibility: hidden`, so it stays out of the
+ * accessibility tree and tab order until shown. Escape dismisses it.
+ */
+export declare const HoverCard: React.ForwardRefExoticComponent<HoverCardProps & React.RefAttributes<HTMLSpanElement>>;
+export {};

package/components/HoverCard/HoverCard.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import React, { useState, useRef, useId, useEffect } from "react";
+import "./HoverCard.css";
+import { MOTION_HOVER_SHOW_DELAY_MS, MOTION_HOVER_HIDE_DELAY_MS } from "../../tokens/motion.js";
+const HoverCard = React.forwardRef(
+  ({
+    children,
+    content,
+    position = "bottom",
+    showDelay = MOTION_HOVER_SHOW_DELAY_MS,
+    hideDelay = MOTION_HOVER_HIDE_DELAY_MS,
+    className = "",
+    ...rest
+  }, ref) => {
+    const [visible, setVisible] = useState(false);
+    const showTimeoutRef = useRef(void 0);
+    const hideTimeoutRef = useRef(void 0);
+    const panelId = useId();
+    const baseClass = "ds-hover-card";
+    const show = () => {
+      clearTimeout(hideTimeoutRef.current);
+      showTimeoutRef.current = setTimeout(() => setVisible(true), showDelay);
+    };
+    const hide = () => {
+      clearTimeout(showTimeoutRef.current);
+      hideTimeoutRef.current = setTimeout(() => setVisible(false), hideDelay);
+    };
+    useEffect(() => {
+      return () => {
+        clearTimeout(showTimeoutRef.current);
+        clearTimeout(hideTimeoutRef.current);
+      };
+    }, []);
+    useEffect(() => {
+      if (!visible) return;
+      const onKeyDown = (e) => {
+        if (e.key === "Escape") {
+          clearTimeout(showTimeoutRef.current);
+          clearTimeout(hideTimeoutRef.current);
+          setVisible(false);
+        }
+      };
+      document.addEventListener("keydown", onKeyDown);
+      return () => document.removeEventListener("keydown", onKeyDown);
+    }, [visible]);
+    const handleBlur = (event) => {
+      if (!event.currentTarget.contains(event.relatedTarget)) {
+        hide();
+      }
+    };
+    const trigger = React.isValidElement(children) ? React.cloneElement(children, {
+      "aria-expanded": visible,
+      "aria-controls": visible ? panelId : void 0
+    }) : children;
+    const containerClasses = [baseClass, className].filter(Boolean).join(" ");
+    const panelClasses = [
+      `${baseClass}__panel`,
+      `${baseClass}__panel--${position}`,
+      visible ? `${baseClass}__panel--visible` : ""
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs(
+      "span",
+      {
+        ...rest,
+        ref,
+        className: containerClasses,
+        onMouseEnter: show,
+        onMouseLeave: hide,
+        onFocus: show,
+        onBlur: handleBlur,
+        children: [
+          trigger,
+          /* @__PURE__ */ jsx("span", { className: panelClasses, id: panelId, children: content })
+        ]
+      }
+    );
+  }
+);
+HoverCard.displayName = "HoverCard";
+export {
+  HoverCard
+};

package/components/ImageCompare/ImageCompare.css

@@ -0,0 +1,112 @@
+/* ============================================
+   IMAGE COMPARE COMPONENT
+   Before-and-after images behind one divider
+   ============================================ */
+
+.ds-image-compare {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--radius-lg);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  background-color: var(--color-bg-container-secondary);
+  /* pan-y keeps the page scrollable over the frame on touch; horizontal
+     drags stay with the slider. */
+  touch-action: pan-y;
+  user-select: none;
+  cursor: col-resize;
+}
+
+/* ============================================
+   IMAGES
+   ============================================ */
+
+.ds-image-compare__after,
+.ds-image-compare__before {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+/* The before layer sits on top at full frame size and is clipped to the
+   left of the divider. clip-path leaves the image's own geometry alone,
+   so the two layers stay pixel-aligned as the split moves. */
+.ds-image-compare__before-clip {
+  position: absolute;
+  inset: 0;
+  clip-path: inset(0 calc(100% - var(--ds-image-compare-position, 50%)) 0 0);
+}
+
+/* ============================================
+   LABELS
+   ============================================ */
+
+.ds-image-compare__label {
+  position: absolute;
+  top: var(--gap-md);
+  z-index: 2;
+  padding: var(--padding-xxxs) var(--padding-sm);
+  border-radius: var(--radius-full);
+  background-color: var(--color-bg-container-inverse);
+  color: var(--color-text-on-inverse);
+  font-family: var(--font-paragraph-sm-em-family);
+  font-size: var(--font-paragraph-sm-em-size);
+  font-weight: var(--font-paragraph-sm-em-weight);
+  line-height: var(--font-paragraph-sm-em-line-height);
+  pointer-events: none;
+}
+
+.ds-image-compare__label--before {
+  left: var(--gap-md);
+}
+
+.ds-image-compare__label--after {
+  right: var(--gap-md);
+}
+
+/* ============================================
+   DIVIDER + HANDLE
+   ============================================ */
+
+.ds-image-compare__divider {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: var(--ds-image-compare-position);
+  width: var(--border-md);
+  transform: translateX(-50%);
+  background-color: var(--color-bg-page-primary);
+  z-index: 1;
+  pointer-events: none;
+}
+
+.ds-image-compare__handle {
+  position: absolute;
+  top: 50%;
+  left: var(--ds-image-compare-position);
+  transform: translate(-50%, -50%);
+  z-index: 3;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius-full);
+  background-color: var(--color-bg-page-primary);
+  color: var(--color-icon-primary);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  box-shadow: var(--shadow-floating);
+  cursor: col-resize;
+}
+
+.ds-image-compare__handle .material-symbols-rounded {
+  --icon-size: var(--icon-size-sm);
+}
+
+.ds-image-compare__handle:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: 2px;
+}

package/components/ImageCompare/ImageCompare.d.ts

@@ -0,0 +1,40 @@
+import { default as React } from 'react';
+/** Props owned by ImageCompare itself — everything else falls through to the root node. */
+type ImageCompareOwnProps = {
+    /** Source of the image revealed on the left of the divider */
+    beforeSrc: string;
+    /** Source of the image revealed on the right of the divider */
+    afterSrc: string;
+    /** Alt text for the before image */
+    beforeAlt: string;
+    /** Alt text for the after image */
+    afterAlt: string;
+    /** Corner label over the before side */
+    beforeLabel?: string;
+    /** Corner label over the after side */
+    afterLabel?: string;
+    /** Whether the corner labels render */
+    showLabels?: boolean;
+    /** Divider position as a percentage from the left (controlled) */
+    position?: number;
+    /** Initial divider position for uncontrolled use */
+    defaultPosition?: number;
+    /** Convenience callback receiving the divider position on every change */
+    onPositionChange?: (position: number) => void;
+    /** CSS aspect-ratio of the frame (both images are sized to cover it) */
+    aspectRatio?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface ImageCompareProps extends ImageCompareOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof ImageCompareOwnProps> {
+}
+/**
+ * Before-and-after comparison of two images sharing one frame. Dragging the
+ * divider (or clicking anywhere in the frame) sweeps the split; the handle is
+ * a `role="slider"` with arrow-key, Home/End and PageUp/PageDown control, so
+ * the comparison works without a pointer.
+ *
+ * Forwards a ref to the root element and spreads unrecognised props onto it.
+ */
+export declare const ImageCompare: React.ForwardRefExoticComponent<ImageCompareProps & React.RefAttributes<HTMLDivElement>>;
+export {};