agentic-ds-kit 0.1.0

package/ui/PageHeader/PageHeader.module.css

@@ -0,0 +1,57 @@
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  width: 100%;
+}
+
+.trail {
+  min-width: 0;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+}
+
+.content {
+  flex: 1;
+  min-width: 0;
+}
+
+.eyebrow {
+  margin: 0 0 var(--space-2);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-label);
+  font-weight: var(--type-weight-label);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+}
+
+.title {
+  margin: 0 0 var(--space-2);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-title);
+  font-weight: var(--type-weight-title);
+  line-height: var(--type-line-heading);
+  color: var(--text-primary);
+}
+
+.subtitle {
+  margin: 0;
+  max-width: 36rem;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body);
+  line-height: var(--type-line-body);
+  color: var(--text-secondary);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+}

package/ui/PageHeader/PageHeader.tsx

@@ -0,0 +1,39 @@
+import { Breadcrumb } from "../Breadcrumb";
+import type { PageHeaderProps } from "./PageHeader.types";
+import styles from "./PageHeader.module.css";
+
+export type { PageHeaderProps } from "./PageHeader.types";
+
+export function PageHeader({
+  title,
+  subtitle,
+  eyebrow,
+  actions,
+  breadcrumbs,
+  breadcrumbSeparator,
+  breadcrumbMaxItems,
+}: PageHeaderProps) {
+  const trail = breadcrumbs && breadcrumbs.length >= 2 ? breadcrumbs : undefined;
+
+  return (
+    <header className={styles.header}>
+      {trail ? (
+        <div className={styles.trail}>
+          <Breadcrumb
+            items={trail}
+            separator={breadcrumbSeparator}
+            maxItems={breadcrumbMaxItems}
+          />
+        </div>
+      ) : null}
+      <div className={styles.row}>
+        <div className={styles.content}>
+          {eyebrow ? <p className={styles.eyebrow}>{eyebrow}</p> : null}
+          <h1 className={styles.title}>{title}</h1>
+          {subtitle ? <p className={styles.subtitle}>{subtitle}</p> : null}
+        </div>
+        {actions ? <div className={styles.actions}>{actions}</div> : null}
+      </div>
+    </header>
+  );
+}

package/ui/PageHeader/PageHeader.types.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+import type { BreadcrumbItem, BreadcrumbSeparator } from "../Breadcrumb";
+
+export interface PageHeaderProps {
+  title: string;
+  subtitle?: string;
+  eyebrow?: string;
+  actions?: ReactNode;
+  breadcrumbs?: BreadcrumbItem[];
+  breadcrumbSeparator?: BreadcrumbSeparator;
+  breadcrumbMaxItems?: number;
+}

package/ui/PageHeader/index.ts

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

package/ui/Pagination/Pagination.module.css

@@ -0,0 +1,19 @@
+.nav {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-1);
+}
+
+.page {
+  display: inline-flex;
+}
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-inline-size: var(--space-8);
+  color: var(--icon-muted);
+}

package/ui/Pagination/Pagination.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "../Button";
+import { LucideByName } from "../Button/lucideName";
+import type { PaginationProps } from "./Pagination.types";
+import styles from "./Pagination.module.css";
+
+export type { PaginationProps, PaginationSize } from "./Pagination.types";
+
+const ICON_SIZE = { sm: 14, md: 16 } as const;
+
+function clampCount(value: number): number {
+  if (!Number.isFinite(value) || value < 1) return 1;
+  return Math.floor(value);
+}
+
+function clampPage(value: number, count: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.min(count, Math.max(1, Math.round(value)));
+}
+
+type WindowNode = { kind: "page"; page: number } | { kind: "ellipsis"; id: string };
+
+function pageWindow(current: number, count: number): WindowNode[] {
+  if (count <= 7) {
+    return Array.from({ length: count }, (_, i) => ({ kind: "page" as const, page: i + 1 }));
+  }
+
+  const pages = new Set<number>([1, count, current]);
+  if (current - 1 >= 1) pages.add(current - 1);
+  if (current + 1 <= count) pages.add(current + 1);
+
+  const sorted = [...pages].sort((a, b) => a - b);
+  const nodes: WindowNode[] = [];
+  for (let i = 0; i < sorted.length; i += 1) {
+    const page = sorted[i];
+    if (i > 0 && page - sorted[i - 1] > 1) {
+      nodes.push({ kind: "ellipsis", id: `gap-${sorted[i - 1]}-${page}` });
+    }
+    nodes.push({ kind: "page", page });
+  }
+  return nodes;
+}
+
+export function Pagination({
+  page,
+  defaultPage = 1,
+  pageCount,
+  onPageChange,
+  showPages = true,
+  showLabels = true,
+  showPreviousNext = true,
+  size = "md",
+}: PaginationProps) {
+  const count = clampCount(pageCount);
+  const isControlled = typeof page === "number";
+  const [uncontrolled, setUncontrolled] = useState(() => clampPage(defaultPage, count));
+  const current = clampPage(isControlled ? page : uncontrolled, count);
+  const iconPx = ICON_SIZE[size];
+
+  function go(next: number) {
+    const nextPage = clampPage(next, count);
+    if (nextPage === current) return;
+    if (!isControlled) setUncontrolled(nextPage);
+    onPageChange?.(nextPage);
+  }
+
+  return (
+    <nav aria-label="Pagination" className={styles.nav}>
+      {showPreviousNext ? (
+        showLabels ? (
+          <Button
+            size={size}
+            variant="tertiary"
+            iconStart="ChevronLeft"
+            disabled={current <= 1}
+            onClick={() => go(current - 1)}
+          >
+            Previous
+          </Button>
+        ) : (
+          <Button
+            size={size}
+            variant="tertiary"
+            iconStart="ChevronLeft"
+            ariaLabel="Previous"
+            disabled={current <= 1}
+            onClick={() => go(current - 1)}
+          />
+        )
+      ) : null}
+
+      {showPages
+        ? pageWindow(current, count).map((node) => {
+            if (node.kind === "ellipsis") {
+              return (
+                <span key={node.id} className={styles.ellipsis} aria-hidden>
+                  <LucideByName name="Ellipsis" size={iconPx} />
+                </span>
+              );
+            }
+
+            const isCurrent = node.page === current;
+            return (
+              <span
+                key={node.page}
+                className={styles.page}
+                aria-current={isCurrent ? "page" : undefined}
+              >
+                <Button
+                  size={size}
+                  variant={isCurrent ? "secondary" : "tertiary"}
+                  onClick={() => go(node.page)}
+                >
+                  {String(node.page)}
+                </Button>
+              </span>
+            );
+          })
+        : null}
+
+      {showPreviousNext ? (
+        showLabels ? (
+          <Button
+            size={size}
+            variant="tertiary"
+            iconEnd="ChevronRight"
+            disabled={current >= count}
+            onClick={() => go(current + 1)}
+          >
+            Next
+          </Button>
+        ) : (
+          <Button
+            size={size}
+            variant="tertiary"
+            iconStart="ChevronRight"
+            ariaLabel="Next"
+            disabled={current >= count}
+            onClick={() => go(current + 1)}
+          />
+        )
+      ) : null}
+    </nav>
+  );
+}

package/ui/Pagination/Pagination.types.ts

@@ -0,0 +1,12 @@
+export type PaginationSize = "sm" | "md";
+
+export interface PaginationProps {
+  page?: number;
+  defaultPage?: number;
+  pageCount: number;
+  onPageChange?: (page: number) => void;
+  showPages?: boolean;
+  showLabels?: boolean;
+  showPreviousNext?: boolean;
+  size?: PaginationSize;
+}

package/ui/Pagination/index.ts

@@ -0,0 +1,2 @@
+export { Pagination } from "./Pagination";
+export type { PaginationProps, PaginationSize } from "./Pagination.types";

package/ui/PieChart/PieChart.module.css

@@ -0,0 +1,116 @@
+.root {
+  container-type: inline-size;
+  overflow: visible;
+}
+
+.stackPlot {
+  display: grid;
+  place-items: center;
+}
+
+.split {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--space-6);
+  width: fit-content;
+  margin-inline: auto;
+}
+
+.plot {
+  position: relative;
+  flex: none;
+  overflow: visible;
+}
+
+.chart {
+  display: block;
+  overflow: visible;
+}
+
+.slice {
+  transform-box: view-box;
+  transform-origin: center;
+  transition:
+    transform 0.56s cubic-bezier(0.22, 1, 0.36, 1),
+    opacity 0.56s cubic-bezier(0.22, 1, 0.36, 1),
+    filter 0.56s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.sliceActive {
+  transform: scale(1.015);
+}
+
+.sliceDimmed {
+  opacity: 0.45;
+  filter: blur(1.5px);
+}
+
+.glow {
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.56s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.sliceActive .glow {
+  opacity: 0.38;
+}
+
+.mark {
+  pointer-events: none;
+}
+
+.hit {
+  fill: transparent;
+  cursor: pointer;
+  outline: none;
+}
+
+.hit:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.center {
+  pointer-events: none;
+}
+
+.centerValue {
+  fill: var(--text-primary);
+  font-family: var(--font-sans);
+  font-weight: var(--type-weight-heading);
+  font-variant-numeric: tabular-nums;
+}
+
+.centerLabel {
+  fill: var(--text-muted);
+  font-family: var(--font-sans);
+  font-weight: var(--type-weight-caption);
+}
+
+
+@container (max-width: 30rem) {
+  .split {
+    flex-direction: column;
+    align-items: center;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .slice,
+  .glow {
+    transition: opacity var(--motion-interaction-duration) var(--motion-interaction-easing);
+  }
+
+  .sliceActive {
+    transform: none;
+  }
+
+  .sliceDimmed {
+    filter: none;
+  }
+
+  .sliceActive .glow {
+    opacity: 0;
+  }
+}

package/ui/PieChart/PieChart.tsx

@@ -0,0 +1,293 @@
+"use client";
+
+import { useId, useMemo, useState } from "react";
+import { ChartFrame } from "../shared/ChartFrame";
+import frameStyles from "../shared/ChartFrame.module.css";
+import {
+  formatValue,
+  pointOnCircle,
+  prepareSegments,
+  ringPath,
+  TAU,
+  wedgePath,
+  type PreparedSegment,
+} from "../shared/chartMath";
+import type { PieChartProps } from "./PieChart.types";
+import styles from "./PieChart.module.css";
+
+export type { PieChartLayout, PieChartProps, PieChartVariant } from "./PieChart.types";
+
+type SliceGeom = PreparedSegment & {
+  path: string;
+  midX: number;
+  midY: number;
+  percent: number;
+};
+
+function ChartTable({ segments, total }: { segments: PreparedSegment[]; total: number }) {
+  return (
+    <div className={frameStyles.tableScroll}>
+      <table className={frameStyles.table}>
+        <thead>
+          <tr>
+            <th scope="col">Segment</th>
+            <th scope="col">Value</th>
+            <th scope="col">Share</th>
+          </tr>
+        </thead>
+        <tbody>
+          {segments.map((segment) => (
+            <tr key={segment.label}>
+              <th scope="row">{segment.label}</th>
+              <td>{formatValue(segment.value)}</td>
+              <td>{`${Math.round(segment.share * 100)}%`}</td>
+            </tr>
+          ))}
+          <tr>
+            <th scope="row">Total</th>
+            <td>{formatValue(total)}</td>
+            <td>100%</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function Legend({
+  segments,
+  active,
+  orientation,
+  onActivate,
+  onClear,
+}: {
+  segments: PreparedSegment[];
+  active: string | null;
+  orientation: "vertical" | "horizontal";
+  onActivate: (label: string) => void;
+  onClear: () => void;
+}) {
+  return (
+    <ul
+      className={`${frameStyles.legend} ${frameStyles.legendInteractive}${orientation === "vertical" ? ` ${frameStyles.legendVertical}` : ""}`}
+    >
+      {segments.map((segment) => {
+        const dimmed = Boolean(active) && active !== segment.label;
+        const percent = `${Math.round(segment.share * 100)}%`;
+        return (
+          <li key={segment.label}>
+            <button
+              type="button"
+              className={`${frameStyles.legendItem} ${frameStyles.legendButton}${dimmed ? ` ${frameStyles.legendItemDimmed}` : ""}`}
+              onMouseEnter={() => onActivate(segment.label)}
+              onMouseLeave={onClear}
+              onFocus={() => onActivate(segment.label)}
+              onBlur={onClear}
+            >
+              <span
+                className={`${frameStyles.legendSwatch} ${frameStyles.legendSwatchPill}`}
+                style={{ background: segment.color }}
+                aria-hidden
+              />
+              <span>{segment.label}</span>
+              <span className={orientation === "vertical" ? frameStyles.legendPercent : frameStyles.legendMeta}>
+                {percent}
+              </span>
+            </button>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+export function PieChart({
+  data = [],
+  title,
+  description,
+  variant = "donut",
+  layout = "split",
+  size = 240,
+  maxSegments = 6,
+  sort = true,
+  otherLabel = "Other",
+  centerLabel = "Total",
+  showCenterTotal = true,
+  showTable = true,
+  emptyLabel = "No data for this range",
+  isLoading = false,
+  className = "",
+}: PieChartProps) {
+  const [active, setActive] = useState<string | null>(null);
+  const rawId = useId();
+  const glowId = `pie-glow-${rawId.replace(/:/g, "")}`;
+  const isDonut = variant === "donut";
+  const isSplit = layout === "split";
+
+  const segments = useMemo(
+    () => prepareSegments(data, { maxSegments, sort, otherLabel }),
+    [data, maxSegments, sort, otherLabel],
+  );
+
+  const total = useMemo(() => segments.reduce((sum, entry) => sum + entry.value, 0), [segments]);
+  const isEmpty = !segments.length || total <= 0;
+
+  const geometry = useMemo(() => {
+    const cx = size / 2;
+    const cy = size / 2;
+    const pad = 4;
+    const outerRadius = size / 2 - pad;
+    const thickness = isDonut ? outerRadius * 0.34 : 0;
+    const innerRadius = isDonut ? Math.max(0, outerRadius - thickness) : 0;
+    const midRadius = isDonut ? (innerRadius + outerRadius) / 2 : outerRadius * 0.55;
+
+    if (isEmpty) {
+      return { cx, cy, slices: [] as SliceGeom[] };
+    }
+
+    let cursor = 0;
+    const slices: SliceGeom[] = segments.map((segment) => {
+      const sweep = segment.share * TAU;
+      const start = cursor;
+      const end = cursor + sweep;
+      cursor = end;
+      const mid = (start + end) / 2;
+      const point = pointOnCircle(cx, cy, midRadius, mid);
+      return {
+        ...segment,
+        path: isDonut
+          ? ringPath({ cx, cy, innerRadius, outerRadius, startAngle: start, endAngle: end })
+          : wedgePath({ cx, cy, radius: outerRadius, startAngle: start, endAngle: end }),
+        midX: point.x,
+        midY: point.y,
+        percent: Math.round(segment.share * 100),
+      };
+    });
+
+    return { cx, cy, slices };
+  }, [isDonut, isEmpty, segments, size]);
+
+  const activeSlice = geometry.slices.find((slice) => slice.label === active) ?? null;
+  const compactTotal = formatValue(total);
+  const valueSize = size * 0.14;
+  const labelSize = size * 0.07;
+
+  const legend = !isEmpty ? (
+    <Legend
+      segments={segments}
+      active={active}
+      orientation={isSplit ? "vertical" : "horizontal"}
+      onActivate={setActive}
+      onClear={() => setActive(null)}
+    />
+  ) : undefined;
+
+  const plot = (
+    <div className={styles.plot} style={{ width: size, height: size }}>
+      <svg
+        className={styles.chart}
+        width={size}
+        height={size}
+        viewBox={`0 0 ${size} ${size}`}
+        overflow="visible"
+      >
+        <defs>
+          <filter id={glowId} x="-40%" y="-40%" width="180%" height="180%">
+            <feGaussianBlur stdDeviation="2.2" />
+          </filter>
+        </defs>
+        {geometry.slices.map((slice) => {
+          const isActive = active === slice.label;
+          const isDimmed = Boolean(active) && !isActive;
+          return (
+            <g
+              key={slice.label}
+              className={`${styles.slice}${isActive ? ` ${styles.sliceActive}` : ""}${isDimmed ? ` ${styles.sliceDimmed}` : ""}`}
+            >
+              <path
+                className={styles.glow}
+                d={slice.path}
+                fill={slice.color}
+                filter={`url(#${glowId})`}
+              />
+              <path className={styles.mark} d={slice.path} fill={slice.color} />
+            </g>
+          );
+        })}
+        {isDonut && showCenterTotal && !isEmpty ? (
+          <text className={styles.center} textAnchor="middle">
+            <tspan
+              className={styles.centerValue}
+              x={geometry.cx}
+              y={geometry.cy}
+              dy="-0.15em"
+              fontSize={valueSize}
+            >
+              {compactTotal}
+            </tspan>
+            <tspan
+              className={styles.centerLabel}
+              x={geometry.cx}
+              dy="1.45em"
+              fontSize={labelSize}
+            >
+              {centerLabel}
+            </tspan>
+          </text>
+        ) : null}
+        {geometry.slices.map((slice) => (
+          <path
+            key={`hit-${slice.label}`}
+            className={styles.hit}
+            d={slice.path}
+            fill="transparent"
+            tabIndex={0}
+            role="button"
+            aria-label={`${slice.label}: ${formatValue(slice.value)}, ${slice.percent} percent`}
+            onMouseEnter={() => setActive(slice.label)}
+            onMouseLeave={() => setActive(null)}
+            onFocus={() => setActive(slice.label)}
+            onBlur={() => setActive(null)}
+          />
+        ))}
+      </svg>
+      {activeSlice ? (
+        <div
+          className={`${frameStyles.tooltip}${activeSlice.midX > size * 0.6 ? ` ${frameStyles.tooltipFlip}` : ""}`}
+          style={{ left: activeSlice.midX, top: activeSlice.midY }}
+          role="status"
+          aria-live="polite"
+        >
+          <p className={frameStyles.tooltipTitle}>{activeSlice.label}</p>
+          <div className={frameStyles.tooltipRow}>
+            <span className={frameStyles.tooltipKey} style={{ background: activeSlice.color }} aria-hidden />
+            <span className={frameStyles.tooltipShare}>{`${activeSlice.percent}% of ${compactTotal}`}</span>
+            <span className={frameStyles.tooltipValue}>{formatValue(activeSlice.value)}</span>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+
+  return (
+    <ChartFrame
+      title={title}
+      description={description}
+      legend={!isSplit ? legend : undefined}
+      table={showTable ? <ChartTable segments={segments} total={total} /> : undefined}
+      isEmpty={isEmpty}
+      emptyLabel={emptyLabel}
+      isLoading={isLoading}
+      className={`pie-chart pie-chart--${layout} ${styles.root} ${className}`.trim()}
+    >
+      {isSplit ? (
+        <div className={styles.split}>
+          {plot}
+          {legend}
+        </div>
+      ) : (
+        <div className={styles.stackPlot}>{plot}</div>
+      )}
+    </ChartFrame>
+  );
+}