agentic-ds-kit 0.1.0

package/ui/shared/ChartFrame.module.css

@@ -0,0 +1,295 @@
+.frame {
+  display: grid;
+  gap: var(--space-4);
+  margin: 0;
+  padding: var(--space-6);
+  width: 100%;
+  min-width: 0;
+  box-sizing: border-box;
+  border: var(--border-width-thin) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  background: var(--surface-card);
+  box-shadow: var(--shadow-sm);
+  color: var(--text-primary);
+}
+
+.header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.heading {
+  display: grid;
+  gap: var(--space-1);
+  min-width: 0;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-heading-sm);
+  font-weight: var(--type-weight-heading);
+  line-height: var(--type-line-heading);
+  color: var(--text-primary);
+}
+
+.description {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  line-height: var(--type-line-body);
+  color: var(--text-secondary);
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+.toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width-thin) solid var(--border-faint);
+  border-radius: var(--radius-control-sm);
+  background: var(--surface-card);
+  color: var(--text-secondary);
+  cursor: pointer;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-label);
+  transition:
+    color var(--motion-interaction-duration) var(--motion-interaction-easing),
+    border-color var(--motion-interaction-duration) var(--motion-interaction-easing);
+}
+
+.toggle:hover {
+  border-color: var(--border-strong);
+  color: var(--text-primary);
+}
+
+.toggle:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.body {
+  min-width: 0;
+  overflow: visible;
+}
+
+.loading {
+  opacity: 0.6;
+  transition: opacity var(--motion-interaction-duration) var(--motion-interaction-easing);
+}
+
+.empty {
+  display: grid;
+  place-items: center;
+  min-height: 15rem;
+  margin: 0;
+  padding-inline: var(--space-4);
+  text-align: center;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  color: var(--text-muted);
+}
+
+.footnote {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  color: var(--text-muted);
+}
+
+.legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2) var(--space-4);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.legendInteractive > li {
+  display: contents;
+}
+
+.legendVertical {
+  display: grid;
+  gap: var(--space-2);
+  align-content: center;
+}
+
+.legendItem {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  color: var(--text-secondary);
+}
+
+.legendVertical .legendItem {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  column-gap: var(--space-2);
+  width: 100%;
+}
+
+.legendButton {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  font: inherit;
+  color: inherit;
+  text-align: inherit;
+  cursor: pointer;
+  border-radius: var(--radius-control-sm);
+  transition: opacity 0.56s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.legendButton:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.legendItemDimmed {
+  opacity: 0.45;
+}
+
+.legendSwatch {
+  width: 0.625rem;
+  height: 0.625rem;
+  border-radius: var(--radius-control-sm);
+  flex: none;
+}
+
+.legendSwatchPill {
+  width: 0.5rem;
+  height: 0.375rem;
+  border-radius: var(--radius-pill);
+}
+
+.legendSwatchLine {
+  width: 0.75rem;
+  height: 0.156rem;
+  border-radius: var(--radius-pill);
+}
+
+.legendMeta {
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.legendPercent {
+  color: var(--text-primary);
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--type-weight-label);
+  text-align: end;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .legendButton {
+    transition: none;
+  }
+}
+
+.tableScroll {
+  overflow-x: auto;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  line-height: var(--type-line-body);
+}
+
+.table th,
+.table td {
+  padding: var(--space-1) var(--space-2);
+  border-bottom: var(--border-width-thin) solid var(--border-faint);
+  text-align: start;
+  background-color: var(--surface-card);
+}
+
+.table thead th {
+  color: var(--text-secondary);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-label);
+  white-space: nowrap;
+}
+
+.table tbody th {
+  color: var(--text-primary);
+  font-weight: var(--type-weight-label);
+}
+
+.table td {
+  color: var(--text-primary);
+  font-variant-numeric: tabular-nums;
+  text-align: end;
+}
+
+.tooltip {
+  position: absolute;
+  z-index: var(--z-tooltip);
+  min-width: 9.5rem;
+  padding: var(--space-2) var(--space-3);
+  border: var(--border-width-thin) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  background: var(--surface-card);
+  box-shadow: var(--shadow-md);
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  pointer-events: none;
+  transform: translate(0.5rem, -50%);
+}
+
+.tooltipFlip {
+  transform: translate(calc(-100% - 0.5rem), -50%);
+}
+
+.tooltipTitle {
+  margin: 0;
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-label);
+  color: var(--text-primary);
+}
+
+.tooltipRow {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin-top: var(--space-1);
+  font-size: var(--type-size-caption);
+  color: var(--text-secondary);
+}
+
+.tooltipKey {
+  width: 0.5rem;
+  height: 0.375rem;
+  border-radius: var(--radius-pill);
+  flex: none;
+}
+
+.tooltipShare {
+  flex: 1;
+  min-width: 0;
+}
+
+.tooltipValue {
+  color: var(--text-primary);
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--type-weight-label);
+}

package/ui/shared/ChartFrame.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import { BarChart3, Table2 } from "lucide-react";
+import { useId, useState, type ReactNode } from "react";
+import styles from "./ChartFrame.module.css";
+
+export interface ChartFrameProps {
+  title?: string;
+  description?: string;
+  legend?: ReactNode;
+  children: ReactNode;
+  table?: ReactNode;
+  footnote?: string;
+  isEmpty?: boolean;
+  emptyLabel?: string;
+  isLoading?: boolean;
+  className?: string;
+}
+
+export function ChartFrame({
+  title,
+  description,
+  legend,
+  children,
+  table,
+  footnote,
+  isEmpty = false,
+  emptyLabel = "No data for this range",
+  isLoading = false,
+  className = "",
+}: ChartFrameProps) {
+  const [view, setView] = useState<"chart" | "table">("chart");
+  const titleId = useId();
+  const descriptionId = useId();
+  const panelId = useId();
+  const showTable = view === "table" && Boolean(table);
+
+  return (
+    <figure
+      className={`${styles.frame} ${className}`.trim()}
+      aria-labelledby={title ? titleId : undefined}
+      aria-describedby={description ? descriptionId : undefined}
+    >
+      {title || table ? (
+        <figcaption className={styles.header}>
+          <div className={styles.heading}>
+            {title ? (
+              <h3 id={titleId} className={styles.title}>
+                {title}
+              </h3>
+            ) : null}
+            {description ? (
+              <p id={descriptionId} className={styles.description}>
+                {description}
+              </p>
+            ) : null}
+          </div>
+          {table ? (
+            <div className={styles.actions}>
+              <button
+                type="button"
+                className={styles.toggle}
+                onClick={() => setView(showTable ? "chart" : "table")}
+                aria-expanded={showTable}
+                aria-controls={panelId}
+              >
+                {showTable ? <BarChart3 aria-hidden="true" size={14} /> : <Table2 aria-hidden="true" size={14} />}
+                <span>{showTable ? "Chart" : "Table"}</span>
+              </button>
+            </div>
+          ) : null}
+        </figcaption>
+      ) : null}
+
+      {legend}
+
+      <div
+        id={panelId}
+        className={`${styles.body}${isLoading ? ` ${styles.loading}` : ""}`}
+      >
+        {isEmpty ? <p className={styles.empty}>{emptyLabel}</p> : showTable ? table : children}
+      </div>
+
+      {footnote ? <p className={styles.footnote}>{footnote}</p> : null}
+    </figure>
+  );
+}

package/ui/shared/chartMath.ts

@@ -0,0 +1,228 @@
+export interface ChartDatum {
+  label: string;
+  value: number;
+  color?: string;
+}
+
+export interface ChartSeries {
+  label: string;
+  data: number[];
+  color?: string;
+}
+
+export const CHART_COLORS = [
+  "var(--fill-brand)",
+  "var(--fill-success)",
+  "var(--fill-warning)",
+  "var(--fill-danger)",
+  "var(--fill-info)",
+] as const;
+
+export function formatValue(value: number): string {
+  if (!Number.isFinite(value)) return "—";
+  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(1)}k`;
+  if (Number.isInteger(value)) return value.toLocaleString("en-US");
+  return value.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+
+export function formatAxisTick(value: number): string {
+  if (!Number.isFinite(value)) return "";
+  if (Math.abs(value) >= 1_000_000) return `${value / 1_000_000}M`;
+  if (Math.abs(value) >= 1_000) return `${value / 1_000}k`;
+  return String(value);
+}
+
+export function colorAt(index: number, override?: string): string {
+  return override ?? CHART_COLORS[index % CHART_COLORS.length];
+}
+
+export interface PreparedSegment extends ChartDatum {
+  share: number;
+  color: string;
+}
+
+export function prepareSegments(
+  data: ChartDatum[],
+  options: { maxSegments?: number; sort?: boolean; otherLabel?: string } = {},
+): PreparedSegment[] {
+  const { maxSegments = 6, sort = true, otherLabel = "Other" } = options;
+  const cleaned = data.filter((entry) => Number.isFinite(entry.value) && entry.value > 0);
+  const ordered = sort ? [...cleaned].sort((a, b) => b.value - a.value) : [...cleaned];
+  const visible = ordered.slice(0, maxSegments);
+  const remainder = ordered.slice(maxSegments);
+  const remainderTotal = remainder.reduce((sum, entry) => sum + entry.value, 0);
+  if (remainderTotal > 0) {
+    visible.push({ label: otherLabel, value: remainderTotal });
+  }
+  const total = visible.reduce((sum, entry) => sum + entry.value, 0);
+  return visible.map((entry, index) => ({
+    ...entry,
+    color: colorAt(index, entry.color),
+    share: total > 0 ? entry.value / total : 0,
+  }));
+}
+
+export function normalizeBarInput(input: {
+  data?: ChartDatum[];
+  categories?: string[];
+  series?: ChartSeries[];
+}): { categories: string[]; series: ChartSeries[] } {
+  if (input.categories?.length && input.series?.length) {
+    return {
+      categories: input.categories,
+      series: input.series.map((entry, index) => ({
+        ...entry,
+        color: colorAt(index, entry.color),
+      })),
+    };
+  }
+  const data = input.data ?? [];
+  return {
+    categories: data.map((entry) => entry.label),
+    series: [
+      {
+        label: "Value",
+        data: data.map((entry) => entry.value),
+        color: CHART_COLORS[0],
+      },
+    ],
+  };
+}
+
+export function normalizeLineInput(input: {
+  data?: ChartDatum[];
+  labels?: string[];
+  series?: ChartSeries[];
+}): { labels: string[]; series: ChartSeries[] } {
+  if (input.labels?.length && input.series?.length) {
+    return {
+      labels: input.labels,
+      series: input.series.map((entry, index) => ({
+        ...entry,
+        color: colorAt(index, entry.color),
+      })),
+    };
+  }
+  const data = input.data ?? [];
+  return {
+    labels: data.map((entry) => entry.label),
+    series: [
+      {
+        label: "Value",
+        data: data.map((entry) => entry.value),
+        color: CHART_COLORS[0],
+      },
+    ],
+  };
+}
+
+export function seriesExtent(
+  series: ChartSeries[],
+  options: { includeZero?: boolean } = {},
+): [number, number] {
+  const values = series.flatMap((entry) => entry.data).filter((value) => Number.isFinite(value));
+  if (!values.length) return [0, 1];
+  let min = Math.min(...values);
+  let max = Math.max(...values);
+  if (options.includeZero) {
+    min = Math.min(min, 0);
+    max = Math.max(max, 0);
+  }
+  if (min === max) {
+    return min === 0 ? [0, 1] : [min * 0.9, max * 1.1];
+  }
+  return [min, max];
+}
+
+export function niceTicks(min: number, max: number, count = 5): { ticks: number[]; min: number; max: number } {
+  const range = niceNum(max - min, false);
+  const step = niceNum(range / Math.max(count - 1, 1), true);
+  const niceMin = Math.floor(min / step) * step;
+  const niceMax = Math.ceil(max / step) * step;
+  const ticks: number[] = [];
+  for (let tick = niceMin; tick <= niceMax + step / 2; tick += step) {
+    ticks.push(Number(tick.toFixed(10)));
+  }
+  return { ticks, min: niceMin, max: niceMax };
+}
+
+function niceNum(value: number, round: boolean): number {
+  const exponent = Math.floor(Math.log10(Math.abs(value) || 1));
+  const fraction = value / 10 ** exponent;
+  let niceFraction: number;
+  if (round) {
+    if (fraction < 1.5) niceFraction = 1;
+    else if (fraction < 3) niceFraction = 2;
+    else if (fraction < 7) niceFraction = 5;
+    else niceFraction = 10;
+  } else if (fraction <= 1) niceFraction = 1;
+  else if (fraction <= 2) niceFraction = 2;
+  else if (fraction <= 5) niceFraction = 5;
+  else niceFraction = 10;
+  return niceFraction * 10 ** exponent;
+}
+
+export function linearScale(domain: [number, number], range: [number, number]) {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const span = d1 - d0 || 1;
+  return (value: number) => r0 + ((value - d0) / span) * (r1 - r0);
+}
+
+export const CHART_MARGINS = { top: 12, right: 12, bottom: 36, left: 44 } as const;
+
+export const TAU = Math.PI * 2;
+
+export function polarToCartesian(cx: number, cy: number, radius: number, angle: number) {
+  return {
+    x: cx + radius * Math.cos(angle - Math.PI / 2),
+    y: cy + radius * Math.sin(angle - Math.PI / 2),
+  };
+}
+
+export function pointOnCircle(cx: number, cy: number, radius: number, angle: number) {
+  return polarToCartesian(cx, cy, radius, angle);
+}
+
+export function wedgePath(options: {
+  cx: number;
+  cy: number;
+  radius: number;
+  startAngle: number;
+  endAngle: number;
+}): string {
+  const { cx, cy, radius, startAngle, endAngle } = options;
+  const start = polarToCartesian(cx, cy, radius, endAngle);
+  const end = polarToCartesian(cx, cy, radius, startAngle);
+  const largeArc = endAngle - startAngle > Math.PI ? 1 : 0;
+  return [
+    `M ${cx} ${cy}`,
+    `L ${start.x} ${start.y}`,
+    `A ${radius} ${radius} 0 ${largeArc} 0 ${end.x} ${end.y}`,
+    "Z",
+  ].join(" ");
+}
+
+export function ringPath(options: {
+  cx: number;
+  cy: number;
+  innerRadius: number;
+  outerRadius: number;
+  startAngle: number;
+  endAngle: number;
+}): string {
+  const { cx, cy, innerRadius, outerRadius, startAngle, endAngle } = options;
+  const outerStart = polarToCartesian(cx, cy, outerRadius, endAngle);
+  const outerEnd = polarToCartesian(cx, cy, outerRadius, startAngle);
+  const innerStart = polarToCartesian(cx, cy, innerRadius, startAngle);
+  const innerEnd = polarToCartesian(cx, cy, innerRadius, endAngle);
+  const largeArc = endAngle - startAngle > Math.PI ? 1 : 0;
+  return [
+    `M ${outerStart.x} ${outerStart.y}`,
+    `A ${outerRadius} ${outerRadius} 0 ${largeArc} 0 ${outerEnd.x} ${outerEnd.y}`,
+    `L ${innerStart.x} ${innerStart.y}`,
+    `A ${innerRadius} ${innerRadius} 0 ${largeArc} 1 ${innerEnd.x} ${innerEnd.y}`,
+    "Z",
+  ].join(" ");
+}

package/ui/shared/controls.module.css

@@ -0,0 +1,48 @@
+.control {
+  display: block;
+  width: 100%;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-body);
+  line-height: var(--type-line-body);
+  color: var(--text-primary);
+  background-color: var(--surface-card);
+  border: var(--border-width-thin) solid var(--border-faint);
+  border-radius: var(--radius-control-md);
+  transition: border-color var(--motion-fast) ease, outline-color var(--motion-fast) ease;
+}
+
+.control:focus {
+  border-color: var(--border-focus);
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.control:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  background-color: var(--surface-muted);
+}
+
+.controlLg {
+  padding: var(--space-3) var(--space-4);
+  font-size: var(--type-size-body);
+}
+
+.controlMd {
+  padding: var(--space-2) var(--space-3);
+}
+
+.controlSm {
+  padding: var(--space-1) var(--space-2);
+  font-size: var(--type-size-label);
+}
+
+.controlError {
+  border-color: var(--status-danger);
+}
+
+.controlError:focus {
+  border-color: var(--status-danger);
+  outline-color: var(--status-danger);
+}

package/ui/shared/useChartSize.ts

@@ -0,0 +1,22 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+export function useChartSize(fallbackHeight: number) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return undefined;
+
+    const update = () => setWidth(node.clientWidth);
+    update();
+
+    const observer = new ResizeObserver(update);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  return { ref, width, height: fallbackHeight };
+}