@robr0/design-system 0.12.0 → 0.13.0

package/components/Gauge/Gauge.css

@@ -0,0 +1,93 @@
+/* ============================================
+   GAUGE COMPONENT
+   Radial dial for a single bounded reading.
+   Colour flows through `color` — the value arc
+   and reading draw with currentColor, so a tone
+   is one custom property swap.
+   ============================================ */
+
+/* Base */
+
+.ds-gauge {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: var(--color-action-primary-bg);
+}
+
+.ds-gauge__svg {
+  display: block;
+}
+
+/* Parts */
+
+.ds-gauge__track {
+  fill: none;
+  stroke: var(--color-bg-container-tertiary);
+  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;
+}
+
+.ds-gauge__value {
+  font-family: var(--font-heading-3-family);
+  font-size: var(--font-heading-3-size);
+  font-weight: var(--font-heading-3-weight);
+  line-height: var(--font-heading-3-line-height);
+  letter-spacing: var(--font-heading-3-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-action-primary-bg);
+}
+
+/* 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,56 @@
+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 and reading. 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;
+    /** Rendered 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 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.
+ */
+export declare const Gauge: React.ForwardRefExoticComponent<GaugeProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/Gauge/Gauge.js

@@ -0,0 +1,95 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import React from "react";
+import "./Gauge.css";
+const SWEEP_UNITS = 75;
+const Gauge = React.forwardRef(
+  ({
+    value,
+    min = 0,
+    max = 100,
+    tone = "accent",
+    thresholds,
+    showValue = true,
+    formatValue,
+    label,
+    size = 120,
+    strokeWidth = 10,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-gauge";
+    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 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 })
+          ] })
+        ]
+      }
+    );
+  }
+);
+Gauge.displayName = "Gauge";
+export {
+  Gauge
+};

package/components/SplitPane/SplitPane.css

@@ -0,0 +1,106 @@
+/* ============================================
+   SPLIT PANE COMPONENT
+   Two resizable regions with a draggable
+   divider. The split rides a custom property
+   set from JS; everything visual is tokens.
+   ============================================ */
+
+/* Base */
+
+.ds-split-pane {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+}
+
+.ds-split-pane--horizontal {
+  flex-direction: row;
+}
+
+.ds-split-pane--vertical {
+  flex-direction: column;
+}
+
+/* While dragging, suppress text selection everywhere in the container so a
+   fast drag doesn't paint selections through the panes. */
+.ds-split-pane--dragging {
+  user-select: none;
+}
+
+/* Panes clip; scrolling belongs to a consumer-owned container inside the
+   pane, which can then be focusable (a bare scrollable region fails the
+   axe scrollable-region-focusable rule, and a pane that is always a tab
+   stop would be worse). */
+
+.ds-split-pane__pane {
+  overflow: hidden;
+  min-width: 0;
+  min-height: 0;
+}
+
+.ds-split-pane__pane--first {
+  flex: 0 0 var(--ds-split-pane-split, 50%);
+}
+
+.ds-split-pane__pane--second {
+  flex: 1 1 0;
+}
+
+/* Separator */
+
+.ds-split-pane__separator {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: transparent;
+  touch-action: none;
+  transition: background-color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-split-pane--horizontal .ds-split-pane__separator {
+  width: var(--gap-sm);
+  cursor: col-resize;
+}
+
+.ds-split-pane--vertical .ds-split-pane__separator {
+  height: var(--gap-sm);
+  cursor: row-resize;
+}
+
+.ds-split-pane__separator:hover,
+.ds-split-pane--dragging .ds-split-pane__separator {
+  background-color: var(--color-bg-container-secondary);
+}
+
+.ds-split-pane__separator:focus-visible {
+  outline: var(--border-md) solid var(--color-action-primary-bg);
+  outline-offset: calc(var(--border-md) * -1);
+  border-radius: var(--radius-xxs);
+}
+
+/* Grip */
+
+.ds-split-pane__grip {
+  display: block;
+  border-radius: var(--radius-full);
+  background-color: var(--color-bg-container-border);
+  transition: background-color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-split-pane--horizontal .ds-split-pane__grip {
+  width: var(--gap-xxs);
+  height: var(--gap-xl);
+}
+
+.ds-split-pane--vertical .ds-split-pane__grip {
+  width: var(--gap-xl);
+  height: var(--gap-xxs);
+}
+
+.ds-split-pane__separator:hover .ds-split-pane__grip,
+.ds-split-pane--dragging .ds-split-pane__grip {
+  background-color: var(--color-icon-secondary);
+}

package/components/SplitPane/SplitPane.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+/** Props owned by SplitPane itself — everything else falls through to the root div. */
+type SplitPaneOwnProps = {
+    /** The two panes, in order. Children beyond the first two are ignored. */
+    children: React.ReactNode;
+    /** Which way the panes sit: side by side, or stacked. */
+    direction?: 'horizontal' | 'vertical';
+    /** First pane's share as a percentage (controlled). Pair with `onSplitChange`. */
+    split?: number;
+    /** First pane's share as a percentage (uncontrolled initial value). */
+    defaultSplit?: number;
+    /** Smallest share the first pane can be dragged to, as a percentage. */
+    minSplit?: number;
+    /** Largest share the first pane can be dragged to, as a percentage. */
+    maxSplit?: number;
+    /** Fires with the new percentage on every drag step or keyboard resize. */
+    onSplitChange?: (split: number) => void;
+    /** Accessible name for the resize handle. */
+    separatorLabel?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface SplitPaneProps extends SplitPaneOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof SplitPaneOwnProps> {
+}
+/**
+ * SplitPane — two resizable regions with a draggable divider: the sidebar
+ * and canvas, the list and detail, the editor and preview. The split is a
+ * percentage, so it survives container resizes. The divider is a real
+ * `separator`: focusable, arrow keys nudge it (Shift for big steps, Home/End
+ * to the limits), and pointer drags use capture so a fast drag can't escape
+ * it. Panes clip their content rather than growing the page; a region that
+ * should scroll brings its own focusable scroll container, so keyboard
+ * users can reach it.
+ */
+export declare const SplitPane: React.ForwardRefExoticComponent<SplitPaneProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/SplitPane/SplitPane.js

@@ -0,0 +1,130 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import React, { useState, useRef } from "react";
+import "./SplitPane.css";
+const KEY_STEP = 2;
+const KEY_STEP_LARGE = 10;
+const SplitPane = React.forwardRef(
+  ({
+    children,
+    direction = "horizontal",
+    split,
+    defaultSplit = 50,
+    minSplit = 10,
+    maxSplit = 90,
+    onSplitChange,
+    separatorLabel = "Resize panes",
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-split-pane";
+    const [uncontrolledSplit, setUncontrolledSplit] = useState(defaultSplit);
+    const [dragging, setDragging] = useState(false);
+    const draggingRef = useRef(false);
+    const internalRef = useRef(null);
+    const setRef = (node) => {
+      internalRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    };
+    const clamp = (value) => Math.min(Math.max(value, minSplit), maxSplit);
+    const currentSplit = clamp(split ?? uncontrolledSplit);
+    const applySplit = (value) => {
+      const next = clamp(value);
+      if (split === void 0) setUncontrolledSplit(next);
+      onSplitChange?.(next);
+    };
+    const splitFromPointer = (e) => {
+      const rect = internalRef.current?.getBoundingClientRect();
+      if (!rect) return;
+      const fraction = direction === "horizontal" ? (e.clientX - rect.left) / rect.width : (e.clientY - rect.top) / rect.height;
+      applySplit(fraction * 100);
+    };
+    const handlePointerDown = (e) => {
+      e.currentTarget.setPointerCapture(e.pointerId);
+      draggingRef.current = true;
+      setDragging(true);
+      splitFromPointer(e);
+    };
+    const handlePointerMove = (e) => {
+      if (!draggingRef.current) return;
+      splitFromPointer(e);
+    };
+    const handlePointerUp = (e) => {
+      if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+        e.currentTarget.releasePointerCapture(e.pointerId);
+      }
+      draggingRef.current = false;
+      setDragging(false);
+    };
+    const handleKeyDown = (e) => {
+      const step = e.shiftKey ? KEY_STEP_LARGE : KEY_STEP;
+      const shrinkKey = direction === "horizontal" ? "ArrowLeft" : "ArrowUp";
+      const growKey = direction === "horizontal" ? "ArrowRight" : "ArrowDown";
+      switch (e.key) {
+        case shrinkKey:
+          e.preventDefault();
+          applySplit(currentSplit - step);
+          break;
+        case growKey:
+          e.preventDefault();
+          applySplit(currentSplit + step);
+          break;
+        case "Home":
+          e.preventDefault();
+          applySplit(minSplit);
+          break;
+        case "End":
+          e.preventDefault();
+          applySplit(maxSplit);
+          break;
+      }
+    };
+    const classes = [
+      baseClass,
+      `${baseClass}--${direction}`,
+      dragging && `${baseClass}--dragging`,
+      className
+    ].filter(Boolean).join(" ");
+    const [first, second] = React.Children.toArray(children);
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...rest,
+        ref: setRef,
+        className: classes,
+        style: {
+          "--ds-split-pane-split": `${currentSplit}%`,
+          ...rest.style
+        },
+        children: [
+          /* @__PURE__ */ jsx("div", { className: `${baseClass}__pane ${baseClass}__pane--first`, children: first }),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: `${baseClass}__separator`,
+              role: "separator",
+              tabIndex: 0,
+              "aria-label": separatorLabel,
+              "aria-orientation": direction === "horizontal" ? "vertical" : "horizontal",
+              "aria-valuenow": Math.round(currentSplit),
+              "aria-valuemin": Math.round(minSplit),
+              "aria-valuemax": Math.round(maxSplit),
+              onPointerDown: handlePointerDown,
+              onPointerMove: handlePointerMove,
+              onPointerUp: handlePointerUp,
+              onPointerCancel: handlePointerUp,
+              onKeyDown: handleKeyDown,
+              children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__grip`, "aria-hidden": "true" })
+            }
+          ),
+          /* @__PURE__ */ jsx("div", { className: `${baseClass}__pane ${baseClass}__pane--second`, children: second })
+        ]
+      }
+    );
+  }
+);
+SplitPane.displayName = "SplitPane";
+export {
+  SplitPane
+};

package/components/StreamingText/StreamingText.css

@@ -0,0 +1,40 @@
+/* ============================================
+   STREAMING TEXT COMPONENT
+   Progressive reveal for text arriving in
+   chunks, with a blinking cursor. Inherits the
+   surrounding typography — the reveal is not a
+   text style of its own.
+   ============================================ */
+
+/* Base */
+
+.ds-streaming-text {
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+/* Cursor */
+
+.ds-streaming-text__cursor {
+  display: inline-block;
+  width: 0.55em;
+  height: 1em;
+  margin-left: 0.1em;
+  vertical-align: text-bottom;
+  border-radius: var(--radius-xxs);
+  background-color: currentColor;
+  animation: ds-streaming-text-blink var(--motion-duration-loop-spin) var(--motion-ease-standard)
+    infinite;
+}
+
+@keyframes ds-streaming-text-blink {
+  0%,
+  45% {
+    opacity: 1;
+  }
+
+  55%,
+  100% {
+    opacity: 0.15;
+  }
+}

package/components/StreamingText/StreamingText.d.ts

@@ -0,0 +1,44 @@
+import { default as React } from 'react';
+/** Props owned by StreamingText itself — everything else falls through to the root span. */
+type StreamingTextOwnProps = {
+    /**
+     * The text received so far. Grow it across renders as chunks arrive; the
+     * reveal animates through the appended part. A value that does not extend
+     * the previous one is treated as a new message and reveals from the start.
+     */
+    text: string;
+    /**
+     * Whether the source is still producing text. Keeps the cursor visible
+     * between chunks, when the reveal has caught up but more may arrive.
+     */
+    streaming?: boolean;
+    /**
+     * Milliseconds between reveal steps. The reveal adds more characters per
+     * step the further it falls behind, so a large chunk catches up instead of
+     * typing for seconds.
+     */
+    charIntervalMs?: number;
+    /** Shows the blinking cursor while streaming or revealing. */
+    cursor?: boolean;
+    /**
+     * Fires once when the reveal catches up with `text` after `streaming` has
+     * ended — the moment the message is fully on screen.
+     */
+    onRevealComplete?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface StreamingTextProps extends StreamingTextOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof StreamingTextOwnProps | 'children'> {
+}
+/**
+ * StreamingText — the reveal for text that arrives in chunks: an LLM
+ * response typing itself out, with a cursor that blinks while more is
+ * coming. Feed it the accumulated text on every render and it animates
+ * through what was appended, catching up faster the further behind it
+ * falls. Under `prefers-reduced-motion` the reveal is skipped and each
+ * chunk appears whole. Announcement is the container's job — pair it with
+ * an `aria-live` region when the surrounding UI does not already announce
+ * the message.
+ */
+export declare const StreamingText: React.ForwardRefExoticComponent<StreamingTextProps & React.RefAttributes<HTMLSpanElement>>;
+export {};

package/components/StreamingText/StreamingText.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import React, { useState, useRef, useEffect } from "react";
+import { MOTION_STREAM_CHAR_INTERVAL_MS } from "../../tokens/motion.js";
+import "./StreamingText.css";
+const StreamingText = React.forwardRef(
+  ({
+    text,
+    streaming = false,
+    charIntervalMs = MOTION_STREAM_CHAR_INTERVAL_MS,
+    cursor = true,
+    onRevealComplete,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-streaming-text";
+    const [revealed, setRevealed] = useState(text.length);
+    const previousText = useRef(text);
+    const completed = useRef(false);
+    useEffect(() => {
+      if (!text.startsWith(previousText.current)) {
+        setRevealed(0);
+        completed.current = false;
+      }
+      previousText.current = text;
+    }, [text]);
+    const caughtUp = revealed >= text.length;
+    useEffect(() => {
+      if (caughtUp) return;
+      completed.current = false;
+      if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+        setRevealed(text.length);
+        return;
+      }
+      const interval = setInterval(() => {
+        setRevealed((current) => {
+          const pending = text.length - current;
+          if (pending <= 0) return current;
+          return current + Math.max(1, Math.round(pending / 20));
+        });
+      }, charIntervalMs);
+      return () => clearInterval(interval);
+    }, [text, caughtUp, charIntervalMs]);
+    useEffect(() => {
+      if (caughtUp && !streaming && text.length > 0 && !completed.current) {
+        completed.current = true;
+        onRevealComplete?.();
+      }
+    }, [caughtUp, streaming, text, onRevealComplete]);
+    const showCursor = cursor && (streaming || !caughtUp);
+    const classes = [baseClass, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs("span", { ...rest, ref, className: classes, children: [
+      caughtUp ? text : text.slice(0, revealed),
+      showCursor && /* @__PURE__ */ jsx("span", { className: `${baseClass}__cursor`, "aria-hidden": "true" })
+    ] });
+  }
+);
+StreamingText.displayName = "StreamingText";
+export {
+  StreamingText
+};