agentic-ds-kit 0.1.0

package/ui/ProgressSteps/ProgressSteps.tsx

@@ -0,0 +1,105 @@
+import { Check, X } from "lucide-react";
+import type { ProgressStepsItem, ProgressStepsProps, ProgressStepsStatus } from "./ProgressSteps.types";
+import styles from "./ProgressSteps.module.css";
+
+export type {
+  ProgressStepsItem,
+  ProgressStepsOrientation,
+  ProgressStepsProps,
+  ProgressStepsSize,
+  ProgressStepsStatus,
+} from "./ProgressSteps.types";
+
+const ICON_SIZE = { sm: 12, md: 14 } as const;
+const STATUSES: readonly ProgressStepsStatus[] = ["complete", "current", "upcoming", "error"];
+
+function clampCurrent(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.round(value));
+}
+
+function isStatus(value: ProgressStepsStatus | undefined): value is ProgressStepsStatus {
+  return Boolean(value && STATUSES.includes(value));
+}
+
+function resolveStatus(step: ProgressStepsItem, index: number, current: number): ProgressStepsStatus {
+  if (isStatus(step.status)) return step.status;
+  if (index < current) return "complete";
+  if (index === current) return "current";
+  return "upcoming";
+}
+
+function statusPhrase(status: ProgressStepsStatus): string {
+  if (status === "complete") return "Completed";
+  if (status === "current") return "Current";
+  if (status === "error") return "Error";
+  return "Upcoming";
+}
+
+export function ProgressSteps({
+  steps,
+  current = 0,
+  orientation = "horizontal",
+  size = "md",
+  ariaLabel = "Progress",
+  className = "",
+}: ProgressStepsProps) {
+  if (!steps.length) return null;
+
+  const currentIndex = clampCurrent(current);
+  const iconPx = ICON_SIZE[size];
+  const statuses = steps.map((step, index) => resolveStatus(step, index, currentIndex));
+
+  return (
+    <nav aria-label={ariaLabel} className={`${styles.root} ${styles[orientation]} ${styles[size]} ${className}`.trim()}>
+      <ol className={styles.list}>
+        {steps.map((step, index) => {
+          const status = statuses[index];
+          const prevComplete = index > 0 && statuses[index - 1] === "complete";
+          const thisComplete = status === "complete";
+          const lineStartClass = `${styles.line} ${styles.lineStart} ${prevComplete ? styles.lineComplete : ""}`.trim();
+          const lineEndClass = `${styles.line} ${styles.lineEnd} ${thisComplete ? styles.lineComplete : ""}`.trim();
+          const marker = (
+            <span className={styles.marker}>
+              {status === "complete" ? (
+                <Check size={iconPx} strokeWidth={2.5} color="currentColor" aria-hidden />
+              ) : status === "error" ? (
+                <X size={iconPx} strokeWidth={2.5} color="currentColor" aria-hidden />
+              ) : (
+                <span className={styles.number}>{index + 1}</span>
+              )}
+            </span>
+          );
+
+          return (
+            <li
+              key={step.id}
+              className={`${styles.step} ${styles[status]}`}
+              aria-current={status === "current" ? "step" : undefined}
+            >
+              <span className={styles.srOnly}>
+                {`${statusPhrase(status)}, step ${index + 1} of ${steps.length}`}
+              </span>
+              {orientation === "horizontal" ? (
+                <div className={styles.markerRow} aria-hidden="true">
+                  <span className={lineStartClass} />
+                  {marker}
+                  <span className={lineEndClass} />
+                </div>
+              ) : (
+                <span className={styles.rail} aria-hidden="true">
+                  {marker}
+                  {index < steps.length - 1 ? <span className={lineEndClass} /> : null}
+                </span>
+              )}
+              <div className={styles.copy}>
+                <span className={styles.label}>{step.label}</span>
+                {step.description ? <span className={styles.description}>{step.description}</span> : null}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/ui/ProgressSteps/ProgressSteps.types.ts

@@ -0,0 +1,19 @@
+export type ProgressStepsOrientation = "horizontal" | "vertical";
+export type ProgressStepsSize = "sm" | "md";
+export type ProgressStepsStatus = "complete" | "current" | "upcoming" | "error";
+
+export interface ProgressStepsItem {
+  id: string;
+  label: string;
+  description?: string;
+  status?: ProgressStepsStatus;
+}
+
+export interface ProgressStepsProps {
+  steps: ProgressStepsItem[];
+  current?: number;
+  orientation?: ProgressStepsOrientation;
+  size?: ProgressStepsSize;
+  ariaLabel?: string;
+  className?: string;
+}

package/ui/ProgressSteps/index.ts

@@ -0,0 +1,8 @@
+export { ProgressSteps } from "./ProgressSteps";
+export type {
+  ProgressStepsItem,
+  ProgressStepsOrientation,
+  ProgressStepsProps,
+  ProgressStepsSize,
+  ProgressStepsStatus,
+} from "./ProgressSteps.types";

package/ui/RadioGroup/RadioGroup.module.css

@@ -0,0 +1,284 @@
+.group {
+  display: grid;
+  gap: var(--space-stack-md);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  min-inline-size: 0;
+}
+
+.legend {
+  float: left;
+  width: 100%;
+  padding: 0;
+  margin: 0 0 var(--space-stack-sm);
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-label);
+  font-weight: var(--type-weight-label);
+  line-height: var(--type-line-body);
+}
+
+.options {
+  display: grid;
+  gap: var(--space-stack-md);
+  clear: both;
+}
+
+.horizontal {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-inline-lg);
+}
+
+.message {
+  clear: both;
+  margin: 0;
+  color: var(--text-muted);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+}
+
+.messageError {
+  color: var(--text-danger);
+}
+
+.radio {
+  --radio-size: 1.15rem;
+  --radio-dot: 0.6rem;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-inline-sm);
+  cursor: pointer;
+}
+
+.input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.control {
+  position: relative;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--radio-size);
+  height: var(--radio-size);
+  border: var(--border-control) solid var(--border-strong);
+  border-radius: var(--radius-pill);
+  background: var(--surface-page);
+  transition:
+    border-color var(--motion-interaction-duration) var(--motion-interaction-easing),
+    background-color var(--motion-interaction-duration) var(--motion-interaction-easing);
+}
+
+.dot {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: var(--radio-dot);
+  height: var(--radio-dot);
+  border-radius: var(--radius-pill);
+  background: var(--action-primary);
+  transform: translate(-50%, -50%) scale(0);
+  opacity: 0;
+  transition:
+    transform var(--motion-expand-duration) var(--motion-ease-spring),
+    opacity var(--motion-expand-duration) var(--motion-ease-spring);
+}
+
+.radio[data-checked] .control {
+  border-color: var(--action-primary);
+  background: var(--surface-page);
+}
+
+.radio[data-checked] .dot {
+  transform: translate(-50%, -50%) scale(1);
+  opacity: 1;
+}
+
+.groupError .radio:not([data-checked]) .control {
+  border-color: var(--status-danger);
+}
+
+.groupError .radio[data-checked] .control {
+  border-color: var(--action-danger);
+  background: var(--surface-page);
+}
+
+.groupError .radio[data-checked] .dot {
+  background: var(--action-danger);
+}
+
+.groupError .radio[data-checked]:hover:not([data-disabled]) .control {
+  border-color: var(--action-danger-hover);
+}
+
+.groupError .radio[data-checked]:hover:not([data-disabled]) .dot {
+  background: var(--action-danger-hover);
+}
+
+.label {
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-label);
+  font-weight: var(--type-weight-label);
+  line-height: var(--type-line-body);
+}
+
+.radio:hover:not([data-disabled]) .control {
+  border-color: var(--border-strong);
+}
+
+.radio[data-checked]:hover:not([data-disabled]) .control {
+  border-color: var(--action-primary-hover);
+  background: var(--surface-page);
+}
+
+.radio[data-checked]:hover:not([data-disabled]) .dot {
+  background: var(--action-primary-hover);
+}
+
+.radio:has(.input:focus-visible) .control {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.radio[data-disabled] {
+  cursor: not-allowed;
+}
+
+.radio[data-disabled] .control {
+  opacity: var(--opacity-disabled);
+}
+
+.radio[data-disabled] .label {
+  color: var(--text-disabled);
+}
+
+.group:disabled .radio {
+  cursor: not-allowed;
+}
+
+.sm,
+.sm .options {
+  gap: var(--space-stack-sm);
+}
+
+.sm .radio {
+  --radio-size: 0.95rem;
+  --radio-dot: 0.48rem;
+  gap: var(--space-inline-xs);
+}
+
+.sm .label,
+.sm .legend {
+  font-size: var(--type-size-caption);
+}
+
+.sm .legend {
+  margin-bottom: var(--space-stack-xs);
+}
+
+.lg {
+  gap: var(--space-stack-lg);
+}
+
+.lg .legend {
+  margin-bottom: var(--space-stack-md);
+}
+
+.lg .options {
+  gap: var(--space-stack-lg);
+}
+
+.lg .radio {
+  --radio-size: 1.35rem;
+  --radio-dot: 0.72rem;
+  gap: var(--space-inline-md);
+}
+
+.lg .label {
+  font-size: var(--type-size-body-sm);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .control,
+  .dot,
+  .message {
+    transition: none;
+    animation: none;
+  }
+}
+
+.legendHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.card {
+  gap: var(--space-stack-sm);
+}
+
+.card .options {
+  display: grid;
+  gap: var(--space-3);
+}
+
+.card .radio {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  width: 100%;
+  margin: 0;
+  padding: var(--space-4);
+  border: var(--border-highlight) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  background: var(--surface-card);
+  box-sizing: border-box;
+}
+
+.card .copy {
+  display: grid;
+  gap: var(--space-1);
+  min-width: 0;
+  flex: 1;
+}
+
+.card .titleRow {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.card .label {
+  font-size: var(--type-size-body);
+  font-weight: var(--type-weight-heading);
+}
+
+.card .description {
+  color: var(--text-muted);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+}
+

package/ui/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import { useId, useState } from "react";
+import { Badge } from "../Badge";
+import type { RadioGroupProps } from "./RadioGroup.types";
+import styles from "./RadioGroup.module.css";
+
+export type {
+  RadioGroupProps,
+  RadioGroupOption,
+  RadioGroupOrientation,
+  RadioGroupSize,
+  RadioGroupLayout,
+} from "./RadioGroup.types";
+
+export function RadioGroup({
+  name,
+  legend,
+  hideLegend = false,
+  size = "md",
+  orientation = "vertical",
+  layout = "list",
+  options,
+  defaultValue,
+  value: valueProp,
+  onChange,
+  disabled = false,
+  error,
+  hint,
+}: RadioGroupProps) {
+  const uid = useId();
+  const isControlled = valueProp !== undefined;
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const value = isControlled ? valueProp : uncontrolled;
+  const message = error || hint;
+  const messageId = message ? `${uid}-message` : undefined;
+
+  function emit(next: string) {
+    if (disabled) return;
+    if (!isControlled) setUncontrolled(next);
+    onChange?.(next);
+  }
+
+  return (
+    <fieldset
+      className={`${styles.group} ${styles[size]} ${layout === "card" ? styles.card : ""}${error ? ` ${styles.groupError}` : ""}`}
+      disabled={disabled}
+      aria-invalid={error ? true : undefined}
+      aria-describedby={messageId}
+    >
+      <legend className={hideLegend ? styles.legendHidden : styles.legend}>{legend}</legend>
+      <div
+        className={`${styles.options} ${orientation === "horizontal" && layout !== "card" ? styles.horizontal : ""}`}
+      >
+        {options.map((option) => {
+          const optionId = `${uid}-${option.value || "empty"}`;
+          const optionDisabled = Boolean(disabled || option.disabled);
+          const checked = value === option.value;
+          return (
+            <label
+              key={option.value}
+              className={styles.radio}
+              htmlFor={optionId}
+              data-checked={checked || undefined}
+              data-disabled={optionDisabled || undefined}
+            >
+              <input
+                id={optionId}
+                className={styles.input}
+                type="radio"
+                name={name}
+                value={option.value}
+                checked={checked}
+                disabled={optionDisabled}
+                aria-invalid={error ? true : undefined}
+                onChange={() => emit(option.value)}
+              />
+              {layout === "card" ? (
+                <span className={styles.copy}>
+                  <span className={styles.titleRow}>
+                    <span className={styles.label}>{option.label}</span>
+                    {option.badge ? (
+                      <Badge size="sm" tone={option.badgeTone ?? "neutral"}>
+                        {option.badge}
+                      </Badge>
+                    ) : null}
+                  </span>
+                  {option.description ? (
+                    <span className={styles.description}>{option.description}</span>
+                  ) : null}
+                </span>
+              ) : (
+                <>
+                  <span className={styles.control} aria-hidden>
+                    <span className={styles.dot} />
+                  </span>
+                  <span className={styles.label}>{option.label}</span>
+                </>
+              )}
+              {layout === "card" ? (
+                <span className={styles.control} aria-hidden>
+                  <span className={styles.dot} />
+                </span>
+              ) : null}
+            </label>
+          );
+        })}
+      </div>
+      {message ? (
+        <p id={messageId} className={`${styles.message}${error ? ` ${styles.messageError}` : ""}`}>
+          {message}
+        </p>
+      ) : null}
+    </fieldset>
+  );
+}

package/ui/RadioGroup/RadioGroup.types.ts

@@ -0,0 +1,30 @@
+import type { BadgeTone } from "../Badge/Badge.types";
+
+export type RadioGroupSize = "sm" | "md" | "lg";
+export type RadioGroupOrientation = "vertical" | "horizontal";
+export type RadioGroupLayout = "list" | "card";
+
+export interface RadioGroupOption {
+  value: string;
+  label: string;
+  description?: string;
+  badge?: string;
+  badgeTone?: BadgeTone;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  name: string;
+  legend: string;
+  hideLegend?: boolean;
+  size?: RadioGroupSize;
+  orientation?: RadioGroupOrientation;
+  layout?: RadioGroupLayout;
+  options: RadioGroupOption[];
+  defaultValue?: string;
+  value?: string;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+  error?: string;
+  hint?: string;
+}

package/ui/RadioGroup/index.ts

@@ -0,0 +1,8 @@
+export { RadioGroup } from "./RadioGroup";
+export type {
+  RadioGroupProps,
+  RadioGroupOption,
+  RadioGroupOrientation,
+  RadioGroupSize,
+  RadioGroupLayout,
+} from "./RadioGroup.types";

package/ui/Scoreboard/Scoreboard.module.css

@@ -0,0 +1,53 @@
+.scoreboard {
+  width: 100%;
+  min-width: 0;
+  container-type: inline-size;
+  container-name: scoreboard;
+}
+
+.grid {
+  display: grid;
+  gap: var(--space-4);
+  width: 100%;
+  min-width: 0;
+  align-items: stretch;
+}
+
+.count1 {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+.count2,
+.count4 {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.count3 {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+@container scoreboard (max-width: calc(2 * var(--layout-metrics-min) + var(--space-4))) {
+  .count2,
+  .count4 {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+@container scoreboard (max-width: calc(3 * var(--layout-metrics-min) + 2 * var(--space-4))) {
+  .count3 {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+@container scoreboard (min-width: calc(4 * var(--layout-metrics-min) + 3 * var(--space-4))) {
+  .count4 {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+
+.overflow {
+  width: 100%;
+  min-width: 0;
+  padding-inline: var(--space-12);
+  box-sizing: border-box;
+}

package/ui/Scoreboard/Scoreboard.tsx

@@ -0,0 +1,41 @@
+import { Carousel } from "../Carousel";
+import { Scorecard } from "../Scorecard";
+import type { ScoreboardProps } from "./Scoreboard.types";
+import styles from "./Scoreboard.module.css";
+
+export type { ScoreboardProps } from "./Scoreboard.types";
+
+const STRIP_MAX = 4;
+
+export function Scoreboard({
+  items,
+  "aria-label": ariaLabel = "Key metrics",
+  className = "",
+}: ScoreboardProps) {
+  const cards = items.map((item) => (
+    <Scorecard key={item.label} {...item} fill />
+  ));
+
+  if (items.length > STRIP_MAX) {
+    return (
+      <div className={`${styles.overflow} ${className}`.trim()}>
+        <Carousel items={cards} slidesPerView={4} ariaLabel={ariaLabel} />
+      </div>
+    );
+  }
+
+  const countClass =
+    items.length <= 1
+      ? styles.count1
+      : items.length === 2
+        ? styles.count2
+        : items.length === 3
+          ? styles.count3
+          : styles.count4;
+
+  return (
+    <section className={styles.scoreboard} aria-label={ariaLabel}>
+      <div className={`${styles.grid} ${countClass} ${className}`.trim()}>{cards}</div>
+    </section>
+  );
+}

package/ui/Scoreboard/Scoreboard.types.ts

@@ -0,0 +1,7 @@
+import type { ScorecardProps } from "../Scorecard/Scorecard.types";
+
+export interface ScoreboardProps {
+  items: ScorecardProps[];
+  "aria-label"?: string;
+  className?: string;
+}

package/ui/Scoreboard/index.ts

@@ -0,0 +1,2 @@
+export { Scoreboard } from "./Scoreboard";
+export type { ScoreboardProps } from "./Scoreboard.types";