agentic-ds-kit 0.1.0

package/ui/Calendar/Calendar.tsx

@@ -0,0 +1,296 @@
+"use client";
+
+import { useId, useLayoutEffect, useRef, useState, type KeyboardEvent } from "react";
+import { Button } from "../Button";
+import type { CalendarProps } from "./Calendar.types";
+import styles from "./Calendar.module.css";
+
+export type { CalendarProps, CalendarSize } from "./Calendar.types";
+
+const WEEKDAYS = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"] as const;
+
+function parseISODate(iso?: string): Date | null {
+  if (!iso) return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  const date = new Date(year, month, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month || date.getDate() !== day) {
+    return null;
+  }
+  return date;
+}
+
+function toISODate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function startOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+
+function addDays(date: Date, delta: number): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + delta);
+}
+
+function addMonths(date: Date, delta: number): Date {
+  const nextMonth = new Date(date.getFullYear(), date.getMonth() + delta, 1);
+  const lastDay = new Date(nextMonth.getFullYear(), nextMonth.getMonth() + 1, 0).getDate();
+  return new Date(nextMonth.getFullYear(), nextMonth.getMonth(), Math.min(date.getDate(), lastDay));
+}
+
+function monthFromISO(iso?: string): Date {
+  const parsed = parseISODate(iso);
+  const base = parsed ?? new Date();
+  return startOfMonth(base);
+}
+
+function buildWeeks(view: Date): Date[][] {
+  const first = new Date(view.getFullYear(), view.getMonth(), 1);
+  const start = new Date(view.getFullYear(), view.getMonth(), 1 - first.getDay());
+  const weeks: Date[][] = [];
+  for (let weekIndex = 0; weekIndex < 6; weekIndex += 1) {
+    const week: Date[] = [];
+    for (let dayIndex = 0; dayIndex < 7; dayIndex += 1) {
+      week.push(addDays(start, weekIndex * 7 + dayIndex));
+    }
+    weeks.push(week);
+  }
+  return weeks;
+}
+
+function isSameDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+function dayIsDisabled(date: Date, minDate?: string, maxDate?: string, calendarDisabled?: boolean): boolean {
+  if (calendarDisabled) return true;
+  const iso = toISODate(date);
+  if (minDate && iso < minDate) return true;
+  if (maxDate && iso > maxDate) return true;
+  return false;
+}
+
+function dayName(date: Date, isToday: boolean, isSelected: boolean): string {
+  const label = date.toLocaleDateString("en-US", {
+    weekday: "long",
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+  });
+  const extras = [label];
+  if (isToday) extras.push("today");
+  if (isSelected) extras.push("selected");
+  return extras.join(", ");
+}
+
+export function Calendar({
+  value,
+  defaultValue,
+  onValueChange,
+  size = "md",
+  disabled = false,
+  minDate,
+  maxDate,
+}: CalendarProps) {
+  const headingId = useId();
+  const isControlled = value !== undefined;
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+  const selectedISO = isControlled ? value : uncontrolledValue;
+  const selectedDate = parseISODate(selectedISO);
+
+  const [view, setView] = useState(() => monthFromISO(selectedISO ?? defaultValue));
+  const [focusedISO, setFocusedISO] = useState(
+    () => selectedISO ?? toISODate(new Date()),
+  );
+  const [seenValue, setSeenValue] = useState(value);
+
+  if (isControlled && value !== seenValue) {
+    setSeenValue(value);
+    const next = parseISODate(value);
+    if (next) {
+      if (view.getFullYear() !== next.getFullYear() || view.getMonth() !== next.getMonth()) {
+        setView(startOfMonth(next));
+      }
+      setFocusedISO(value);
+    }
+  }
+
+  const dayRefs = useRef<Map<string, HTMLButtonElement>>(new Map());
+  const moveFocusRef = useRef(false);
+
+  const today = new Date();
+  const todayISO = toISODate(today);
+  const weeks = buildWeeks(view);
+  const monthLabel = view.toLocaleString("en-US", { month: "long", year: "numeric" });
+
+  const lastPrev = new Date(view.getFullYear(), view.getMonth(), 0);
+  const firstNext = new Date(view.getFullYear(), view.getMonth() + 1, 1);
+  const prevDisabled = disabled || Boolean(minDate && toISODate(lastPrev) < minDate);
+  const nextDisabled = disabled || Boolean(maxDate && toISODate(firstNext) > maxDate);
+
+  useLayoutEffect(() => {
+    if (!moveFocusRef.current) return;
+    moveFocusRef.current = false;
+    dayRefs.current.get(focusedISO)?.focus();
+  }, [focusedISO, view]);
+
+  function commit(date: Date) {
+    if (dayIsDisabled(date, minDate, maxDate, disabled)) return;
+    const iso = toISODate(date);
+    if (!isControlled) setUncontrolledValue(iso);
+    onValueChange?.(iso);
+    setView(startOfMonth(date));
+    setFocusedISO(iso);
+  }
+
+  function goMonth(delta: number) {
+    const next = startOfMonth(addMonths(view, delta));
+    const from = parseISODate(focusedISO) ?? view;
+    const last = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate();
+    const day = Math.min(from.getDate(), last);
+    setView(next);
+    setFocusedISO(toISODate(new Date(next.getFullYear(), next.getMonth(), day)));
+  }
+
+  function moveTo(date: Date) {
+    moveFocusRef.current = true;
+    setFocusedISO(toISODate(date));
+    setView(startOfMonth(date));
+  }
+
+  function onGridKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const current = parseISODate(focusedISO) ?? today;
+    let next: Date | null = null;
+
+    switch (event.key) {
+      case "ArrowLeft":
+        next = addDays(current, -1);
+        break;
+      case "ArrowRight":
+        next = addDays(current, 1);
+        break;
+      case "ArrowUp":
+        next = addDays(current, -7);
+        break;
+      case "ArrowDown":
+        next = addDays(current, 7);
+        break;
+      case "Home":
+        next = addDays(current, -current.getDay());
+        break;
+      case "End":
+        next = addDays(current, 6 - current.getDay());
+        break;
+      case "PageUp":
+        next = addMonths(current, -1);
+        break;
+      case "PageDown":
+        next = addMonths(current, 1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        commit(current);
+        return;
+      default:
+        return;
+    }
+
+    event.preventDefault();
+    if (next) moveTo(next);
+  }
+
+  return (
+    <div
+      className={`${styles.calendar} ${styles[size]}`}
+      data-disabled={disabled || undefined}
+    >
+      <div className={styles.header}>
+        <Button
+          variant="tertiary"
+          size="sm"
+          iconStart="ChevronLeft"
+          ariaLabel="Previous month"
+          disabled={prevDisabled}
+          onClick={() => goMonth(-1)}
+        />
+        <div className={styles.heading} id={headingId} role="heading" aria-level={2} aria-live="polite">
+          {monthLabel}
+        </div>
+        <Button
+          variant="tertiary"
+          size="sm"
+          iconStart="ChevronRight"
+          ariaLabel="Next month"
+          disabled={nextDisabled}
+          onClick={() => goMonth(1)}
+        />
+      </div>
+      <div
+        className={styles.grid}
+        role="grid"
+        aria-labelledby={headingId}
+        aria-disabled={disabled || undefined}
+        onKeyDown={onGridKeyDown}
+      >
+        <div role="row" className={styles.weekdays}>
+          {WEEKDAYS.map((label) => (
+            <div key={label} role="columnheader" className={styles.weekday}>
+              {label}
+            </div>
+          ))}
+        </div>
+        {weeks.map((week, weekIndex) => (
+          <div key={weekIndex} role="row" className={styles.row}>
+            {week.map((date) => {
+              const iso = toISODate(date);
+              const outside = date.getMonth() !== view.getMonth();
+              const isToday = iso === todayISO;
+              const isSelected = Boolean(selectedDate && isSameDay(date, selectedDate));
+              const isFocused = iso === focusedISO;
+              const dayDisabled = dayIsDisabled(date, minDate, maxDate, disabled);
+
+              return (
+                <div
+                  key={iso}
+                  role="gridcell"
+                  className={styles.cell}
+                  aria-selected={isSelected || undefined}
+                >
+                  <button
+                    ref={(node) => {
+                      if (node) dayRefs.current.set(iso, node);
+                      else dayRefs.current.delete(iso);
+                    }}
+                    type="button"
+                    className={styles.day}
+                    tabIndex={isFocused ? 0 : -1}
+                    aria-label={dayName(date, isToday, isSelected)}
+                    aria-disabled={dayDisabled || undefined}
+                    data-outside={outside || undefined}
+                    data-today={isToday || undefined}
+                    data-selected={isSelected || undefined}
+                    onClick={() => commit(date)}
+                    onFocus={() => setFocusedISO(iso)}
+                  >
+                    {date.getDate()}
+                  </button>
+                </div>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/ui/Calendar/Calendar.types.ts

@@ -0,0 +1,11 @@
+export type CalendarSize = "sm" | "md" | "lg";
+
+export interface CalendarProps {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (date: string) => void;
+  size?: CalendarSize;
+  disabled?: boolean;
+  minDate?: string;
+  maxDate?: string;
+}

package/ui/Calendar/index.ts

@@ -0,0 +1,2 @@
+export { Calendar } from "./Calendar";
+export type { CalendarProps, CalendarSize } from "./Calendar.types";

package/ui/Card/Card.module.css

@@ -0,0 +1,95 @@
+.card {
+  --card-spacing: var(--space-6);
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+  background-color: var(--surface-card);
+  border: 1px solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  box-shadow: var(--shadow-sm);
+}
+
+.sm {
+  --card-spacing: var(--space-4);
+  max-width: 24rem;
+  margin-inline: auto;
+}
+
+.image {
+  display: block;
+  width: 100%;
+  height: 10rem;
+  object-fit: cover;
+  border-top-left-radius: var(--radius-surface-md);
+  border-top-right-radius: var(--radius-surface-md);
+}
+
+.sm .image {
+  height: 8rem;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--card-spacing);
+  padding: var(--card-spacing);
+  min-width: 0;
+}
+
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: var(--space-4);
+}
+
+.copy {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+  min-width: 0;
+  flex: 1;
+}
+
+.title {
+  margin: 0;
+  overflow-wrap: anywhere;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-heading);
+  font-weight: var(--type-weight-heading);
+  line-height: var(--type-line-heading);
+  color: var(--text-primary);
+}
+
+.sm .title {
+  font-size: var(--type-size-body);
+  line-height: var(--type-line-body);
+}
+
+.description {
+  margin: 0;
+  overflow-wrap: anywhere;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  line-height: var(--type-line-body);
+  color: var(--text-secondary);
+}
+
+.body {
+  display: grid;
+  gap: var(--space-4);
+  min-width: 0;
+}
+
+.footer {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: var(--space-2);
+}
+
+.footer button {
+  width: 100%;
+}

package/ui/Card/Card.tsx

@@ -0,0 +1,69 @@
+import { useId } from "react";
+import { Button } from "../Button";
+import type { CardProps } from "./Card.types";
+import styles from "./Card.module.css";
+
+export type { CardProps, CardSize, CardAction, CardActionVariant } from "./Card.types";
+
+export function Card({
+  title,
+  description,
+  children,
+  size = "md",
+  actions,
+  headerAction,
+  imageSrc,
+  imageAlt,
+}: CardProps) {
+  const titleId = useId();
+  const footerActions = (actions ?? []).slice(0, 2);
+
+  return (
+    <article
+      className={[styles.card, styles[size]].filter(Boolean).join(" ")}
+      aria-labelledby={title ? titleId : undefined}
+    >
+      {imageSrc ? (
+        <img className={styles.image} src={imageSrc} alt={imageAlt ?? ""} />
+      ) : null}
+      <div className={styles.content}>
+        {title || description || headerAction ? (
+          <header className={styles.header}>
+            <div className={styles.copy}>
+              {title ? (
+                <h2 id={titleId} className={styles.title}>
+                  {title}
+                </h2>
+              ) : null}
+              {description ? <p className={styles.description}>{description}</p> : null}
+            </div>
+            {headerAction ? (
+              <Button
+                variant={headerAction.variant ?? "tertiary"}
+                size="sm"
+                onClick={headerAction.onClick}
+              >
+                {headerAction.label}
+              </Button>
+            ) : null}
+          </header>
+        ) : null}
+        <div className={styles.body}>{children}</div>
+        {footerActions.length > 0 ? (
+          <footer className={styles.footer}>
+            {footerActions.map((action) => (
+              <Button
+                key={action.label}
+                variant={action.variant}
+                size="md"
+                onClick={action.onClick}
+              >
+                {action.label}
+              </Button>
+            ))}
+          </footer>
+        ) : null}
+      </div>
+    </article>
+  );
+}

package/ui/Card/Card.types.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { ButtonVariant } from "../Button";
+
+export type CardSize = "sm" | "md";
+export type CardActionVariant = ButtonVariant;
+
+export interface CardAction {
+  label: string;
+  variant?: CardActionVariant;
+  onClick?: () => void;
+}
+
+export interface CardProps {
+  title?: string;
+  description?: string;
+  children: ReactNode;
+  size?: CardSize;
+  actions?: CardAction[];
+  headerAction?: CardAction;
+  imageSrc?: string;
+  /** Required when imageSrc is set. */
+  imageAlt?: string;
+}

package/ui/Card/index.ts

@@ -0,0 +1,2 @@
+export { Card } from "./Card";
+export type { CardProps, CardSize, CardAction, CardActionVariant } from "./Card.types";

package/ui/Carousel/Carousel.module.css

@@ -0,0 +1,114 @@
+.root {
+  width: 100%;
+  min-width: 0;
+  outline: none;
+}
+
+.root:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.horizontal,
+.vertical {
+  min-width: 0;
+}
+
+.stage {
+  position: relative;
+}
+
+.viewport {
+  overflow: hidden;
+}
+
+.vertical .viewport {
+  block-size: 12.5rem;
+}
+
+.track {
+  display: flex;
+  align-items: stretch;
+  margin-inline-start: calc(-1 * var(--space-4));
+}
+
+.vertical .track {
+  flex-direction: column;
+  height: 100%;
+  margin-inline-start: 0;
+  margin-block-start: calc(-1 * var(--space-4));
+}
+
+.slide {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  flex-grow: 0;
+  flex-shrink: 0;
+  flex-basis: 100%;
+  padding-inline-start: var(--space-4);
+}
+
+.slide > * {
+  flex: 1 1 auto;
+  width: 100%;
+  min-width: 0;
+}
+
+.vertical .slide {
+  padding-inline-start: 0;
+  padding-block-start: var(--space-4);
+}
+
+.per2 .slide {
+  flex-basis: 50%;
+}
+
+.per3 .slide {
+  flex-basis: calc(100% / 3);
+}
+
+.per4 .slide {
+  flex-basis: 25%;
+}
+
+.prev,
+.next {
+  position: absolute;
+  z-index: 1;
+}
+
+.horizontal .prev {
+  inset-block-start: 50%;
+  inset-inline-start: calc(-1 * var(--space-12));
+  transform: translateY(-50%);
+}
+
+.horizontal .next {
+  inset-block-start: 50%;
+  inset-inline-end: calc(-1 * var(--space-12));
+  transform: translateY(-50%);
+}
+
+.vertical .prev {
+  inset-block-start: calc(-1 * var(--space-12));
+  inset-inline-start: 50%;
+  transform: translateX(-50%);
+}
+
+.vertical .next {
+  inset-block-end: calc(-1 * var(--space-12));
+  inset-inline-start: 50%;
+  transform: translateX(-50%);
+}
+
+.index {
+  margin: var(--space-3) 0 0;
+  text-align: center;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+  color: var(--text-muted);
+}