agentic-ds-kit 0.1.0

package/ui/Carousel/Carousel.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import useEmblaCarousel from "embla-carousel-react";
+import { Button } from "../Button";
+import type { CarouselProps } from "./Carousel.types";
+import styles from "./Carousel.module.css";
+
+export type {
+  CarouselProps,
+  CarouselOrientation,
+  CarouselAlign,
+  CarouselSlidesPerView,
+} from "./Carousel.types";
+
+export function Carousel({
+  items,
+  orientation = "horizontal",
+  loop = false,
+  align = "start",
+  slidesPerView = 1,
+  showControls = true,
+  showIndex = false,
+  onIndexChange,
+  ariaLabel = "Carousel",
+}: CarouselProps) {
+  const emblaOptions = useMemo(
+    () => ({
+      axis: (orientation === "vertical" ? "y" : "x") as "x" | "y",
+      loop,
+      align,
+    }),
+    [orientation, loop, align],
+  );
+  const [viewportRef, emblaApi] = useEmblaCarousel(emblaOptions);
+
+  const [canScrollPrev, setCanScrollPrev] = useState(false);
+  const [canScrollNext, setCanScrollNext] = useState(false);
+  const [index, setIndex] = useState(0);
+  const [snapCount, setSnapCount] = useState(Math.max(items.length, 1));
+  const onIndexChangeRef = useRef(onIndexChange);
+  onIndexChangeRef.current = onIndexChange;
+
+  const sync = useCallback(() => {
+    if (!emblaApi) return;
+    const nextIndex = emblaApi.selectedScrollSnap();
+    setCanScrollPrev(emblaApi.canScrollPrev());
+    setCanScrollNext(emblaApi.canScrollNext());
+    setIndex(nextIndex);
+    setSnapCount(emblaApi.scrollSnapList().length);
+    onIndexChangeRef.current?.(nextIndex);
+  }, [emblaApi]);
+
+  useEffect(() => {
+    if (!emblaApi) return;
+    sync();
+    emblaApi.on("select", sync);
+    emblaApi.on("reInit", sync);
+    return () => {
+      emblaApi.off("select", sync);
+      emblaApi.off("reInit", sync);
+    };
+  }, [emblaApi, sync]);
+
+  useEffect(() => {
+    emblaApi?.reInit();
+  }, [emblaApi, items.length, slidesPerView]);
+
+  function scrollPrev() {
+    emblaApi?.scrollPrev();
+  }
+
+  function scrollNext() {
+    emblaApi?.scrollNext();
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const prevKey = orientation === "vertical" ? "ArrowUp" : "ArrowLeft";
+    const nextKey = orientation === "vertical" ? "ArrowDown" : "ArrowRight";
+    if (event.key === prevKey) {
+      event.preventDefault();
+      scrollPrev();
+    } else if (event.key === nextKey) {
+      event.preventDefault();
+      scrollNext();
+    }
+  }
+
+  const count = snapCount || Math.max(items.length, 1);
+  const prevIcon = orientation === "vertical" ? "ChevronUp" : "ChevronLeft";
+  const nextIcon = orientation === "vertical" ? "ChevronDown" : "ChevronRight";
+  const perClass =
+    slidesPerView === 2 ? styles.per2 : slidesPerView === 3 ? styles.per3 : slidesPerView === 4 ? styles.per4 : "";
+
+  return (
+    <div
+      className={`${styles.root} ${styles[orientation]} ${perClass}`}
+      role="region"
+      aria-roledescription="carousel"
+      aria-label={ariaLabel}
+      tabIndex={0}
+      onKeyDown={onKeyDown}
+    >
+      <div className={styles.stage}>
+        <div className={styles.viewport} ref={viewportRef}>
+          <div className={styles.track}>
+            {items.map((item, i) => (
+              <div
+                key={i}
+                className={styles.slide}
+                role="group"
+                aria-roledescription="slide"
+                aria-label={`Slide ${i + 1} of ${items.length}`}
+              >
+                {item}
+              </div>
+            ))}
+          </div>
+        </div>
+        {showControls ? (
+          <>
+            <div className={styles.prev}>
+              <Button
+                variant="secondary"
+                size="sm"
+                iconStart={prevIcon}
+                ariaLabel="Previous slide"
+                disabled={!canScrollPrev}
+                onClick={scrollPrev}
+              />
+            </div>
+            <div className={styles.next}>
+              <Button
+                variant="secondary"
+                size="sm"
+                iconStart={nextIcon}
+                ariaLabel="Next slide"
+                disabled={!canScrollNext}
+                onClick={scrollNext}
+              />
+            </div>
+          </>
+        ) : null}
+      </div>
+      {showIndex ? (
+        <p className={styles.index} aria-live="polite">
+          {`Slide ${index + 1} of ${count}`}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/ui/Carousel/Carousel.types.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+export type CarouselOrientation = "horizontal" | "vertical";
+export type CarouselAlign = "start" | "center";
+export type CarouselSlidesPerView = 1 | 2 | 3 | 4;
+
+export interface CarouselProps {
+  items: ReactNode[];
+  orientation?: CarouselOrientation;
+  loop?: boolean;
+  align?: CarouselAlign;
+  slidesPerView?: CarouselSlidesPerView;
+  showControls?: boolean;
+  showIndex?: boolean;
+  onIndexChange?: (index: number) => void;
+  ariaLabel?: string;
+}

package/ui/Carousel/index.ts

@@ -0,0 +1,7 @@
+export { Carousel } from "./Carousel";
+export type {
+  CarouselProps,
+  CarouselOrientation,
+  CarouselAlign,
+  CarouselSlidesPerView,
+} from "./Carousel.types";

package/ui/Cell/Cell.module.css

@@ -0,0 +1,133 @@
+.cell {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  min-width: 0;
+  max-width: 100%;
+  width: 100%;
+  background-color: transparent;
+}
+
+.sm {
+  min-height: 3rem;
+  padding: var(--space-2) var(--space-4);
+  gap: var(--space-3);
+}
+
+.md {
+  min-height: 3.5rem;
+  padding: var(--space-3) var(--space-6);
+  gap: var(--space-3);
+}
+
+.visual {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  min-width: 0;
+}
+
+.copy {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  min-width: 0;
+  gap: 0;
+}
+
+.label {
+  min-width: 0;
+  font-family: var(--font-sans);
+  line-height: var(--type-line-body);
+  color: var(--text-primary);
+  overflow-wrap: anywhere;
+}
+
+.copy .label {
+  font-weight: var(--type-weight-label);
+  line-height: var(--type-line-heading);
+}
+
+.support {
+  min-width: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-body);
+  line-height: var(--type-line-heading);
+  color: var(--text-secondary);
+  overflow-wrap: anywhere;
+}
+
+.sm .label,
+.md .label {
+  font-size: var(--type-size-body-sm);
+}
+
+.icon {
+  flex-shrink: 0;
+  color: var(--icon-muted);
+}
+
+.trend {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.trendPositive {
+  color: var(--status-success);
+}
+
+.trendNegative {
+  color: var(--status-danger);
+}
+
+.trend .label {
+  color: inherit;
+}
+
+.badges {
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+  min-width: 0;
+}
+
+.selectWrap {
+  display: block;
+  width: 10rem;
+  max-width: 100%;
+}
+
+.progressWrap {
+  display: block;
+  width: 8rem;
+  max-width: 100%;
+}
+
+.rating {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+.starOn {
+  color: var(--icon-warning);
+  fill: currentColor;
+}
+
+.starOff {
+  color: var(--icon-muted);
+}
+
+.actionIcons {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+.actionMenu {
+  justify-content: center;
+}

package/ui/Cell/Cell.tsx

@@ -0,0 +1,300 @@
+"use client";
+
+import { useId, type ReactNode } from "react";
+import { Avatar } from "../Avatar";
+import { AvatarGroup } from "../AvatarGroup";
+import { Badge } from "../Badge";
+import { Button } from "../Button";
+import { DropdownMenu } from "../DropdownMenu";
+import { Progress } from "../Progress";
+import { ButtonGroup } from "../ButtonGroup";
+import { Checkbox } from "../Checkbox";
+import { Select } from "../Select";
+import { LucideByName } from "../Button/lucideName";
+import type { CellProps, CellType } from "./Cell.types";
+import styles from "./Cell.module.css";
+
+export type {
+  CellProps,
+  CellValue,
+  CellType,
+  CellSize,
+  CellPerson,
+  CellBadgeItem,
+  CellOption,
+  CellAction,
+} from "./Cell.types";
+
+const ICON_PX = { sm: 14, md: 16 } as const;
+const STAR_COUNT = 5;
+const NO_SIDE_LABEL = new Set<CellType>([
+  "badge",
+  "badges",
+  "select",
+  "rating",
+  "actions",
+  "actionIcons",
+  "actionMenu",
+]);
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, n));
+}
+
+function toPercent(value?: string | number): number {
+  if (value === undefined || value === "") return 0;
+  const n = typeof value === "number" ? value : parseFloat(String(value).replace("%", ""));
+  if (Number.isNaN(n)) return 0;
+  return clamp(n, 0, 100);
+}
+
+function toRating(value?: string | number): number {
+  if (value === undefined || value === "") return 0;
+  const n = typeof value === "number" ? value : parseFloat(String(value));
+  if (Number.isNaN(n)) return 0;
+  return clamp(Math.round(n), 0, STAR_COUNT);
+}
+
+function sideLabelText(
+  type: CellType,
+  label?: string,
+  name?: string,
+  value?: string | number,
+): string {
+  if (NO_SIDE_LABEL.has(type)) return "";
+  if (type === "progress") {
+    if (label) return label;
+    return `${Math.round(toPercent(value))}%`;
+  }
+  if (type === "trendPositive" || type === "trendNegative") {
+    if (label) return label;
+    if (value !== undefined) return String(value);
+    return "";
+  }
+  if (label) return label;
+  if (type === "avatar" || type === "avatarGroup") return name ?? "";
+  return "";
+}
+
+function trendAria(direction: "Up" | "Down", value?: string | number): string {
+  if (value === undefined || value === "") return direction;
+  return `${direction} ${value}`;
+}
+
+export function Cell({
+  type = "text",
+  size = "md",
+  text = true,
+  checkbox = false,
+  label,
+  name,
+  src,
+  initials,
+  people,
+  icon,
+  tone = "neutral",
+  badges,
+  value,
+  options,
+  actions,
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  id,
+}: CellProps) {
+  const generatedId = useId();
+  const checkboxId = id ?? generatedId;
+  const selectId = `${generatedId}-select`;
+  const iconPx = ICON_PX[size];
+  const personName = name || label || "";
+  const shown = sideLabelText(type, label, name, value);
+  const selectName = label || name || "row";
+  const buttonSize = size === "sm" ? "sm" : "sm";
+
+  let rootAria: string | undefined;
+  if (!text) {
+    if (type === "file" || type === "payment") {
+      rootAria = label || name;
+    } else if (type === "trendPositive") {
+      rootAria = trendAria("Up", value);
+    } else if (type === "trendNegative") {
+      rootAria = trendAria("Down", value);
+    } else if (type === "rating") {
+      rootAria = `${toRating(value)} of ${STAR_COUNT}`;
+    }
+  }
+
+  let visual: ReactNode = null;
+  if (type === "avatar") {
+    visual = <Avatar name={personName} src={src} initials={initials} size={size} />;
+  } else if (type === "avatarGroup" && people && people.length > 0) {
+    visual = <AvatarGroup items={people} size={size} max={3} ariaLabel={label} />;
+  } else if (type === "file") {
+    visual = <LucideByName name={icon || "File"} size={iconPx} className={styles.icon} />;
+  } else if (type === "payment") {
+    visual = <LucideByName name={icon || "CreditCard"} size={iconPx} className={styles.icon} />;
+  } else if (type === "badge") {
+    visual = (
+      <Badge tone={tone} size={size}>
+        {label || ""}
+      </Badge>
+    );
+  } else if (type === "badges") {
+    visual = (
+      <span className={styles.badges}>
+        {(badges ?? []).slice(0, 3).map((item, index) => (
+          <Badge key={`${item.label}-${index}`} tone={item.tone ?? "neutral"} size={size}>
+            {item.label}
+          </Badge>
+        ))}
+      </span>
+    );
+  } else if (type === "trendPositive" || type === "trendNegative") {
+    const positive = type === "trendPositive";
+    visual = (
+      <span className={`${styles.trend} ${positive ? styles.trendPositive : styles.trendNegative}`}>
+        <LucideByName name={positive ? "ChevronUp" : "ChevronDown"} size={iconPx} />
+        {text && shown ? <span className={styles.label}>{shown}</span> : null}
+      </span>
+    );
+  } else if (type === "select" && options && options.length > 0) {
+    const selected = value !== undefined && value !== "" ? String(value) : options[0].value;
+    visual = (
+      <span className={styles.selectWrap}>
+        <Select
+          id={selectId}
+          size="sm"
+          options={options}
+          defaultValue={selected}
+          ariaLabel={label || "Select"}
+        />
+      </span>
+    );
+  } else if (type === "progress") {
+    const percent = toPercent(value);
+    visual = (
+      <span className={styles.progressWrap}>
+        <Progress
+          value={percent}
+          size={size}
+          ariaLabel={label || `${Math.round(percent)}%`}
+        />
+      </span>
+    );
+  } else if (type === "rating") {
+    const score = toRating(value);
+    visual = (
+      <span className={styles.rating} role="img" aria-label={label || `${score} of ${STAR_COUNT}`}>
+        {Array.from({ length: STAR_COUNT }, (_, index) => (
+          <LucideByName
+            key={index}
+            name="Star"
+            size={iconPx}
+            className={index < score ? styles.starOn : styles.starOff}
+          />
+        ))}
+      </span>
+    );
+  } else if (type === "actions") {
+    const items = (actions ?? []).slice(0, 3);
+    if (items.length > 0) {
+      visual = (
+        <ButtonGroup ariaLabel={label || "Row actions"}>
+          {items.map((item, index) => (
+            <Button
+              key={`${item.label || item.icon || "action"}-${index}`}
+              size={buttonSize}
+              variant={item.variant ?? (index === 0 ? "secondary" : "tertiary")}
+              iconStart={item.icon}
+              ariaLabel={item.ariaLabel}
+              onClick={item.onClick}
+            >
+              {item.label}
+            </Button>
+          ))}
+        </ButtonGroup>
+      );
+    }
+  } else if (type === "actionIcons") {
+    const items = (actions ?? []).slice(0, 3);
+    if (items.length > 0) {
+      visual = (
+        <span className={styles.actionIcons} role="group" aria-label={label || "Row actions"}>
+          {items.map((item, index) => (
+            <Button
+              key={`${item.icon || item.label || "icon"}-${index}`}
+              size={buttonSize}
+              variant={item.variant ?? "tertiary"}
+              iconStart={item.icon}
+              ariaLabel={item.ariaLabel || item.label || "Action"}
+              onClick={item.onClick}
+            />
+          ))}
+        </span>
+      );
+    }
+  } else if (type === "actionMenu") {
+    const menuItems = (actions ?? []).map((item, index) => ({
+      id: item.label || item.ariaLabel || item.icon || `action-${index}`,
+      label: item.label || item.ariaLabel || "Action",
+      icon: item.icon,
+      danger: item.variant === "danger",
+    }));
+    visual = (
+      <DropdownMenu
+        iconStart={icon || "Ellipsis"}
+        ariaLabel={label || "Row actions"}
+        variant="tertiary"
+        size={buttonSize}
+        align="end"
+        groups={[{ items: menuItems }]}
+        onSelect={(id) => {
+          const hit = (actions ?? []).find(
+            (item, index) => (item.label || item.ariaLabel || item.icon || `action-${index}`) === id,
+          );
+          hit?.onClick?.();
+        }}
+      />
+    );
+  }
+
+  const avatarSupport = type === "avatar" && name && label && label !== name ? label : "";
+  const showAvatarCopy = type === "avatar" && text && Boolean(personName);
+  const showSideLabel =
+    text &&
+    shown &&
+    type !== "trendPositive" &&
+    type !== "trendNegative" &&
+    type !== "avatar";
+  const empty = !checkbox && !visual && !showSideLabel && !showAvatarCopy;
+
+  const actionMenu = type === "actionMenu";
+
+  return (
+    <span
+      className={`${styles.cell} ${styles[size]}${actionMenu ? ` ${styles.actionMenu}` : ""}`}
+      aria-label={rootAria}
+    >
+      {checkbox ? (
+        <Checkbox
+          id={checkboxId}
+          size="sm"
+          ariaLabel={`Select ${selectName}`}
+          checked={checked}
+          defaultChecked={defaultChecked}
+          onChange={onCheckedChange}
+        />
+      ) : null}
+      {visual ? <span className={styles.visual}>{visual}</span> : null}
+      {showAvatarCopy ? (
+        <span className={styles.copy}>
+          <span className={styles.label}>{personName}</span>
+          {avatarSupport ? <span className={styles.support}>{avatarSupport}</span> : null}
+        </span>
+      ) : showSideLabel ? (
+        <span className={styles.label}>{shown}</span>
+      ) : null}
+      {empty ? "\u00a0" : null}
+    </span>
+  );
+}

package/ui/Cell/Cell.types.ts

@@ -0,0 +1,69 @@
+import type { BadgeTone } from "../Badge/Badge.types";
+import type { ButtonVariant } from "../Button/Button.types";
+
+export type CellType =
+  | "text"
+  | "avatar"
+  | "file"
+  | "payment"
+  | "badge"
+  | "badges"
+  | "trendPositive"
+  | "trendNegative"
+  | "avatarGroup"
+  | "select"
+  | "progress"
+  | "rating"
+  | "actions"
+  | "actionIcons"
+  | "actionMenu";
+
+export type CellSize = "sm" | "md";
+
+export interface CellPerson {
+  name: string;
+  src?: string;
+  initials?: string;
+}
+
+export interface CellBadgeItem {
+  label: string;
+  tone?: BadgeTone;
+}
+
+export interface CellOption {
+  value: string;
+  label: string;
+}
+
+export interface CellAction {
+  label?: string;
+  icon?: string;
+  ariaLabel?: string;
+  variant?: ButtonVariant;
+  onClick?: () => void;
+}
+
+export interface CellProps {
+  type?: CellType;
+  size?: CellSize;
+  text?: boolean;
+  checkbox?: boolean;
+  label?: string;
+  name?: string;
+  src?: string;
+  initials?: string;
+  people?: CellPerson[];
+  icon?: string;
+  tone?: BadgeTone;
+  badges?: CellBadgeItem[];
+  value?: string | number;
+  options?: CellOption[];
+  actions?: CellAction[];
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  id?: string;
+}
+
+export type CellValue = CellProps;

package/ui/Cell/index.ts

@@ -0,0 +1,11 @@
+export { Cell } from "./Cell";
+export type {
+  CellProps,
+  CellValue,
+  CellType,
+  CellSize,
+  CellPerson,
+  CellBadgeItem,
+  CellOption,
+  CellAction,
+} from "./Cell.types";