agentic-ds-kit 0.1.0

package/ui/AppNav/AppNav.module.css

@@ -0,0 +1,168 @@
+.nav {
+  width: 15rem;
+  flex-shrink: 0;
+  padding: var(--space-4);
+  background-color: var(--surface-card);
+  border: var(--border-width-thin) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+}
+
+.title {
+  margin: 0 0 var(--space-4);
+  padding: 0 var(--space-2);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-heading);
+  color: var(--text-primary);
+}
+
+.groupList {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+}
+
+.groupToggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  width: 100%;
+  margin: 0;
+  padding: var(--space-2) var(--space-3);
+  border: 0;
+  border-radius: var(--radius-control-sm);
+  background: transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  text-align: left;
+}
+
+.groupToggle:hover,
+.groupToggleOpen,
+.groupToggleActive {
+  color: var(--text-primary);
+}
+
+.groupToggle:hover {
+  background: var(--surface-muted);
+}
+
+.groupToggle:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.groupLabel {
+  font-family: var(--font-sans);
+  font-size: var(--type-size-overline);
+  font-weight: var(--type-weight-overline);
+  letter-spacing: var(--type-tracking-overline);
+  text-transform: uppercase;
+}
+
+.chevron {
+  flex-shrink: 0;
+  color: var(--icon-muted);
+  transition: transform var(--motion-expand-duration) var(--motion-ease-out);
+}
+
+.chevronOpen {
+  transform: rotate(90deg);
+  color: var(--icon-default);
+}
+
+.accordion {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.isOpen .accordion {
+  grid-template-rows: 1fr;
+}
+
+.accordionInner {
+  overflow: hidden;
+  min-height: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .accordion,
+  .chevron {
+    transition: none;
+  }
+}
+
+.list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.subgroupLabel {
+  padding: var(--space-2) var(--space-3);
+  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);
+}
+
+.subList {
+  margin: 0;
+  padding: 0 0 0 var(--space-2);
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.link {
+  display: block;
+  padding: var(--space-2) var(--space-3);
+  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);
+  text-decoration: none;
+  border-radius: var(--radius-control-md);
+  transition: background-color var(--motion-fast) ease, color var(--motion-fast) ease;
+}
+
+.linkNested {
+  padding-left: var(--space-4);
+}
+
+.link:hover {
+  background-color: var(--surface-muted);
+  color: var(--text-primary);
+}
+
+.link:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.active {
+  background-color: color-mix(in srgb, var(--action-primary) 10%, var(--surface-card));
+  color: var(--action-primary);
+}

package/ui/AppNav/AppNav.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { ChevronRight } from "lucide-react";
+import type { AppNavGroup, AppNavItem, AppNavLeaf, AppNavProps } from "./AppNav.types";
+import styles from "./AppNav.module.css";
+
+export type { AppNavProps, AppNavItem, AppNavLeaf, AppNavGroup } from "./AppNav.types";
+
+function navKey(item: AppNavLeaf, index: number): string {
+  return `${item.href}::${item.label}::${index}`;
+}
+
+function groupHasActive(group: AppNavGroup): boolean {
+  return group.items.some((item) => item.active || item.items?.some((child) => child.active));
+}
+
+function NavLink({ href, label, active, nested }: AppNavLeaf & { nested?: boolean }) {
+  return (
+    <Link
+      href={href}
+      className={`${styles.link} ${nested ? styles.linkNested : ""} ${active ? styles.active : ""}`}
+      aria-current={active ? "page" : undefined}
+      onClick={(event) => {
+        const [path, fragment] = href.split("#");
+        if (!fragment) return;
+        const here = window.location.pathname;
+        if (path && path !== here) return;
+        event.preventDefault();
+        window.location.hash = fragment;
+        window.dispatchEvent(new HashChangeEvent("hashchange"));
+      }}
+    >
+      {label}
+    </Link>
+  );
+}
+
+function NavItem({ item }: { item: AppNavItem }) {
+  if (item.items && item.items.length > 0) {
+    return (
+      <li className={styles.item}>
+        <span className={styles.subgroupLabel}>{item.label}</span>
+        <ul className={styles.subList}>
+          {item.items.map((child, index) => (
+            <li key={navKey(child, index)}>
+              <NavLink {...child} nested />
+            </li>
+          ))}
+        </ul>
+      </li>
+    );
+  }
+
+  return (
+    <li className={styles.item}>
+      <NavLink {...item} />
+    </li>
+  );
+}
+
+function NavGroup({
+  group,
+  open,
+  onToggle,
+}: {
+  group: AppNavGroup;
+  open: boolean;
+  onToggle: () => void;
+}) {
+  const groupId = `nav-group-${group.label.replace(/\s+/g, "-").toLowerCase()}`;
+  const hasActive = groupHasActive(group);
+
+  return (
+    <li className={`${styles.group} ${open ? styles.isOpen : ""}`}>
+      <button
+        type="button"
+        className={`${styles.groupToggle} ${open ? styles.groupToggleOpen : ""} ${hasActive ? styles.groupToggleActive : ""}`}
+        aria-expanded={open}
+        aria-controls={groupId}
+        onClick={onToggle}
+      >
+        <span className={styles.groupLabel}>{group.label}</span>
+        <ChevronRight className={`${styles.chevron} ${open ? styles.chevronOpen : ""}`} size={14} strokeWidth={2} aria-hidden />
+      </button>
+      <div className={styles.accordion} id={groupId} aria-hidden={!open} inert={open ? undefined : true}>
+        <div className={styles.accordionInner}>
+          <ul className={styles.list}>
+            {group.items.map((item, index) => (
+              <NavItem key={navKey(item, index)} item={item} />
+            ))}
+          </ul>
+        </div>
+      </div>
+    </li>
+  );
+}
+
+export function AppNav({ title, items = [], groups }: AppNavProps) {
+  const useGroups = Boolean(groups && groups.length > 0);
+  const activeLabel = useGroups ? groups!.find(groupHasActive)?.label ?? null : null;
+  const fallbackLabel = useGroups
+    ? groups!.find((group) => group.defaultOpen !== false)?.label ?? groups![0].label
+    : null;
+  const [openLabel, setOpenLabel] = useState<string | null>(activeLabel ?? fallbackLabel);
+
+  useEffect(() => {
+    if (activeLabel) setOpenLabel(activeLabel);
+  }, [activeLabel]);
+
+  const resolvedOpen = openLabel ?? activeLabel ?? fallbackLabel;
+
+  return (
+    <nav className={styles.nav} aria-label="Application">
+      {title ? <p className={styles.title}>{title}</p> : null}
+      {useGroups ? (
+        <ul className={styles.groupList}>
+          {groups!.map((group) => (
+            <NavGroup
+              key={group.label}
+              group={group}
+              open={resolvedOpen === group.label}
+              onToggle={() => setOpenLabel((current) => (current === group.label ? null : group.label))}
+            />
+          ))}
+        </ul>
+      ) : (
+        <ul className={styles.list}>
+          {items.map((item, index) => (
+            <NavItem key={navKey(item, index)} item={item} />
+          ))}
+        </ul>
+      )}
+    </nav>
+  );
+}

package/ui/AppNav/AppNav.types.ts

@@ -0,0 +1,24 @@
+export interface AppNavLeaf {
+  href: string;
+  label: string;
+  active?: boolean;
+}
+
+/** A nav link, optionally with one nested subgroup of leaves. */
+export interface AppNavItem extends AppNavLeaf {
+  items?: AppNavLeaf[];
+}
+
+export interface AppNavGroup {
+  label: string;
+  defaultOpen?: boolean;
+  items: AppNavItem[];
+}
+
+export interface AppNavProps {
+  title?: string;
+  /** Flat list for simple shells (e.g. list-detail). Ignored when `groups` is provided. */
+  items?: AppNavItem[];
+  /** Grouped catalog nav for docs/playground shells. Takes precedence over `items`. */
+  groups?: AppNavGroup[];
+}

package/ui/AppNav/index.ts

@@ -0,0 +1,2 @@
+export { AppNav } from "./AppNav";
+export type { AppNavProps, AppNavItem, AppNavLeaf, AppNavGroup } from "./AppNav.types";

package/ui/Avatar/Avatar.module.css

@@ -0,0 +1,52 @@
+.avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  flex-shrink: 0;
+  align-self: center;
+  aspect-ratio: 1 / 1;
+  border-radius: var(--radius-pill);
+  font-family: var(--font-sans);
+  font-weight: var(--type-weight-heading);
+  line-height: 1;
+  user-select: none;
+}
+
+.fallback {
+  background: var(--surface-muted);
+  color: var(--text-primary);
+}
+
+.sm {
+  width: var(--space-8);
+  height: var(--space-8);
+  font-size: var(--type-size-caption);
+}
+
+.md {
+  width: var(--space-10);
+  height: var(--space-10);
+  font-size: var(--type-size-body-sm);
+}
+
+.lg {
+  width: var(--space-12);
+  height: var(--space-12);
+  font-size: var(--type-size-body);
+}
+
+.image {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: center 20%;
+  aspect-ratio: 1 / 1;
+}
+
+.icon {
+  width: 50%;
+  height: 50%;
+  color: inherit;
+}

package/ui/Avatar/Avatar.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { User } from "lucide-react";
+import type { AvatarProps } from "./Avatar.types";
+import styles from "./Avatar.module.css";
+
+export type { AvatarProps, AvatarSize } from "./Avatar.types";
+
+function lettersOf(value: string): string {
+  return Array.from(value)
+    .filter((ch) => /\p{L}/u.test(ch))
+    .join("");
+}
+
+function deriveInitials(name: string): string {
+  const words = name
+    .trim()
+    .split(/\s+/)
+    .map(lettersOf)
+    .filter(Boolean);
+
+  if (words.length === 0) return "";
+  if (words.length === 1) return words[0].slice(0, 2).toUpperCase();
+
+  const first = words[0][0];
+  const last = words[words.length - 1][0];
+  return `${first}${last}`.toUpperCase();
+}
+
+function resolveInitials(name: string, initials?: string): string {
+  if (initials !== undefined) {
+    const override = lettersOf(initials).slice(0, 2).toUpperCase();
+    if (override) return override;
+  }
+  return deriveInitials(name);
+}
+
+export function Avatar({ name, src, initials, size = "md" }: AvatarProps) {
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    setFailed(false);
+  }, [src]);
+
+  const label = resolveInitials(name, initials);
+  const showImage = Boolean(src) && !failed;
+
+  if (showImage) {
+    return (
+      <span className={`${styles.avatar} ${styles[size]}`}>
+        <img className={styles.image} src={src} alt={name} onError={() => setFailed(true)} />
+      </span>
+    );
+  }
+
+  return (
+    <span className={`${styles.avatar} ${styles[size]} ${styles.fallback}`} role="img" aria-label={name}>
+      {label ? label : <User className={styles.icon} aria-hidden />}
+    </span>
+  );
+}

package/ui/Avatar/Avatar.types.ts

@@ -0,0 +1,8 @@
+export type AvatarSize = "sm" | "md" | "lg";
+
+export interface AvatarProps {
+  name: string;
+  src?: string;
+  initials?: string;
+  size?: AvatarSize;
+}

package/ui/Avatar/index.ts

@@ -0,0 +1,2 @@
+export { Avatar } from "./Avatar";
+export type { AvatarProps, AvatarSize } from "./Avatar.types";

package/ui/AvatarGroup/AvatarGroup.module.css

@@ -0,0 +1,49 @@
+.group {
+  display: inline-flex;
+  align-items: center;
+}
+
+.item {
+  display: inline-flex;
+  position: relative;
+  flex-shrink: 0;
+  border-radius: var(--radius-pill);
+  box-shadow: 0 0 0 var(--space-px) var(--surface-page);
+}
+
+.item:not(:first-child) {
+  margin-inline-start: calc(-1 * var(--space-2));
+}
+
+.count {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  flex-shrink: 0;
+  border-radius: var(--radius-pill);
+  font-family: var(--font-sans);
+  font-weight: var(--type-weight-heading);
+  line-height: 1;
+  user-select: none;
+  background: var(--surface-muted);
+  color: var(--text-secondary);
+}
+
+.sm {
+  width: var(--space-8);
+  height: var(--space-8);
+  font-size: var(--type-size-caption);
+}
+
+.md {
+  width: var(--space-10);
+  height: var(--space-10);
+  font-size: var(--type-size-body-sm);
+}
+
+.lg {
+  width: var(--space-12);
+  height: var(--space-12);
+  font-size: var(--type-size-body);
+}

package/ui/AvatarGroup/AvatarGroup.tsx

@@ -0,0 +1,29 @@
+import { Avatar } from "../Avatar";
+import type { AvatarGroupProps } from "./AvatarGroup.types";
+import styles from "./AvatarGroup.module.css";
+
+export type { AvatarGroupItem, AvatarGroupProps, AvatarGroupSize } from "./AvatarGroup.types";
+
+export function AvatarGroup({ items, size = "md", max = 3, ariaLabel }: AvatarGroupProps) {
+  const visible = items.slice(0, max);
+  const leftover = items.length - max;
+
+  return (
+    <div className={styles.group} role="group" aria-label={ariaLabel}>
+      {visible.map((item, index) => (
+        <span key={`${item.name}-${index}`} className={styles.item} style={{ zIndex: index + 1 }}>
+          <Avatar name={item.name} src={item.src} initials={item.initials} size={size} />
+        </span>
+      ))}
+      {leftover > 0 ? (
+        <span
+          className={`${styles.item} ${styles.count} ${styles[size]}`}
+          style={{ zIndex: visible.length + 1 }}
+          aria-label={`${leftover} more`}
+        >
+          +{leftover}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/ui/AvatarGroup/AvatarGroup.types.ts

@@ -0,0 +1,16 @@
+import type { AvatarSize } from "../Avatar/Avatar.types";
+
+export type AvatarGroupSize = AvatarSize;
+
+export interface AvatarGroupItem {
+  name: string;
+  src?: string;
+  initials?: string;
+}
+
+export interface AvatarGroupProps {
+  items: AvatarGroupItem[];
+  size?: AvatarGroupSize;
+  max?: number;
+  ariaLabel?: string;
+}

package/ui/AvatarGroup/index.ts

@@ -0,0 +1,2 @@
+export { AvatarGroup } from "./AvatarGroup";
+export type { AvatarGroupItem, AvatarGroupProps, AvatarGroupSize } from "./AvatarGroup.types";

package/ui/Badge/Badge.module.css

@@ -0,0 +1,92 @@
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  border-radius: var(--radius-control-sm);
+  border: 1px solid transparent;
+  font-family: var(--font-sans);
+  font-weight: var(--type-weight-label);
+  white-space: nowrap;
+  line-height: 1.25;
+}
+
+.sm {
+  padding: var(--space-1) var(--space-2);
+  font-size: var(--type-size-caption);
+}
+
+.md {
+  padding: var(--space-1) var(--space-2);
+  font-size: var(--type-size-label);
+}
+
+.lg {
+  padding: var(--space-2) var(--space-3);
+  font-size: var(--type-size-body-sm);
+}
+
+.neutral {
+  background-color: var(--surface-muted);
+  color: var(--text-secondary);
+  border-color: var(--border-faint);
+}
+
+.brand {
+  background-color: color-mix(in srgb, var(--action-primary) 12%, var(--surface-card));
+  color: var(--action-primary);
+  border-color: color-mix(in srgb, var(--action-primary) 35%, var(--surface-card));
+}
+
+.success {
+  background-color: var(--status-success-subtle);
+  color: var(--status-success);
+  border-color: var(--status-success-border);
+}
+
+.warning {
+  background-color: var(--status-warning-subtle);
+  color: var(--status-warning);
+  border-color: var(--status-warning-border);
+}
+
+.danger {
+  background-color: var(--status-danger-subtle);
+  color: var(--status-danger);
+  border-color: var(--status-danger-border);
+}
+
+.info {
+  background-color: var(--status-info-subtle);
+  color: var(--status-info);
+  border-color: var(--status-info-border);
+}
+
+.disabled {
+  opacity: 0.5;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+
+.remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-control-sm);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  line-height: 0;
+  flex-shrink: 0;
+}
+
+.remove:disabled {
+  cursor: not-allowed;
+}
+
+.remove:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}

package/ui/Badge/Badge.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { X } from "lucide-react";
+import type { BadgeProps } from "./Badge.types";
+import styles from "./Badge.module.css";
+
+export type { BadgeProps, BadgeTone, BadgeSize } from "./Badge.types";
+
+const ICON_SIZE = { sm: 12, md: 14, lg: 16 } as const;
+
+export function Badge({
+  children,
+  tone = "neutral",
+  size = "md",
+  removable = false,
+  disabled = false,
+  onRemove,
+}: BadgeProps) {
+  const iconPx = ICON_SIZE[size];
+
+  return (
+    <span
+      className={`${styles.badge} ${styles[tone]} ${styles[size]}${disabled ? ` ${styles.disabled}` : ""}`}
+      aria-disabled={disabled || undefined}
+    >
+      {children}
+      {removable ? (
+        <button
+          type="button"
+          className={styles.remove}
+          aria-label={`Remove ${children}`}
+          disabled={disabled}
+          onClick={() => {
+            if (disabled) return;
+            onRemove?.();
+          }}
+        >
+          <X size={iconPx} color="currentColor" aria-hidden />
+        </button>
+      ) : null}
+    </span>
+  );
+}