@robr0/design-system 0.12.0 → 0.14.0

package/components/Gauge/Gauge.css

@@ -0,0 +1,110 @@
+/* ============================================
+   GAUGE COMPONENT
+   Radial dial for a single bounded reading.
+   Card chrome, header, and padding come from
+   the shared chart styles (Chart.css) — this
+   file owns the dial alone. Colour flows
+   through `color`: the value arc draws with
+   currentColor, so a tone is one custom
+   property swap.
+   ============================================ */
+
+/* Base — the dial centres in the shared chart body */
+
+.ds-gauge__body {
+  display: flex;
+  justify-content: center;
+}
+
+/* Unlike the fluid recharts bodies, the dial has intrinsic size — a bare
+   gauge shrink-wraps it so it sits inline in a Stat row or tile. */
+.ds-gauge.ds-chart--bare {
+  width: auto;
+  display: inline-flex;
+}
+
+.ds-gauge__dial {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.ds-gauge__svg {
+  display: block;
+}
+
+/* Parts */
+
+.ds-gauge__track {
+  fill: none;
+  stroke: var(--color-bg-container-secondary);
+  stroke-linecap: round;
+}
+
+.ds-gauge__arc {
+  fill: none;
+  stroke: currentColor;
+  stroke-linecap: round;
+  transition: stroke-dasharray var(--motion-duration-slow) var(--motion-ease-emphasized);
+}
+
+.ds-gauge__center {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--gap-xxs);
+  text-align: center;
+  pointer-events: none;
+}
+
+/* The centre pair mirrors the chart family's radial centre label:
+   a light sub-display numeral over a caption. */
+
+.ds-gauge__value {
+  font-family: var(--font-sub-display-family);
+  font-size: var(--font-sub-display-size);
+  font-weight: var(--font-sub-display-weight);
+  line-height: var(--font-sub-display-line-height);
+  letter-spacing: var(--font-sub-display-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+.ds-gauge__label {
+  font-family: var(--font-caption-family);
+  font-size: var(--font-caption-size);
+  font-weight: var(--font-caption-weight);
+  line-height: var(--font-caption-line-height);
+  letter-spacing: var(--font-caption-letter-spacing);
+  color: var(--color-text-secondary);
+}
+
+/* Tones */
+
+.ds-gauge--accent {
+  color: var(--color-chart-series-1);
+}
+
+/* The status hues come from the border tokens, not the text tokens: the
+   border set is stable across themes, while the dark-mode text tints are
+   near-white and would wash three tones into one. */
+
+.ds-gauge--positive {
+  color: var(--color-status-positive-border);
+}
+
+.ds-gauge--warning {
+  color: var(--color-status-warning-border);
+}
+
+.ds-gauge--error {
+  color: var(--color-status-error-border);
+}
+
+.ds-gauge--neutral {
+  color: var(--color-text-secondary);
+}

package/components/Gauge/Gauge.d.ts

@@ -0,0 +1,64 @@
+import { default as React } from 'react';
+/** One colour switch point: at or above `value`, the dial takes `tone`. */
+export interface GaugeThreshold {
+    /** Reading at which this tone takes over. */
+    value: number;
+    /** Tone applied from this reading upward. */
+    tone: 'accent' | 'positive' | 'warning' | 'error' | 'neutral';
+}
+/** Props owned by Gauge itself — everything else falls through to the root div. */
+type GaugeOwnProps = {
+    /** Current reading. Clamped into the `min`–`max` range for drawing. */
+    value: number;
+    /** Lower bound of the dial. */
+    min?: number;
+    /** Upper bound of the dial. */
+    max?: number;
+    /**
+     * 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';
+    /**
+     * Colour switch points, e.g. warning at 70 and error at 90. The highest
+     * threshold at or below the current reading wins; below them all, the
+     * `tone` prop applies.
+     */
+    thresholds?: GaugeThreshold[];
+    /** Shows the reading in the centre of the dial. */
+    showValue?: boolean;
+    /** Formats the centre reading — for units, precision, or locale. */
+    formatValue?: (value: number) => string;
+    /**
+     * What the reading measures, shown as a caption under it and used as the
+     * accessible name, e.g. "CPU usage".
+     */
+    label?: string;
+    /** 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;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface GaugeProps extends GaugeOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof GaugeOwnProps | 'children'> {
+}
+/**
+ * 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. 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

@@ -0,0 +1,111 @@
+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(
+  ({
+    value,
+    min = 0,
+    max = 100,
+    tone = "accent",
+    thresholds,
+    showValue = true,
+    formatValue,
+    label,
+    title,
+    subtitle,
+    bare = false,
+    size = 120,
+    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 = [
+      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));
+    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";
+export {
+  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 {};