agentic-ds-kit 0.1.0

package/ui/Modal/Modal.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { ModalCard } from "../ModalCard";
+import type { ModalProps } from "./Modal.types";
+import styles from "./Modal.module.css";
+
+export type { ModalProps, ModalSize } from "./Modal.types";
+
+const FOCUSABLE = "a, button, input, select, textarea, [tabindex]:not([tabindex='-1'])";
+
+export function Modal({
+  open,
+  title,
+  description,
+  size = "md",
+  showClose = true,
+  onClose,
+  children,
+  footer,
+  contained = false,
+}: ModalProps) {
+  const cardRef = useRef<HTMLDivElement>(null);
+  const onCloseRef = useRef(onClose);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const [mounted, setMounted] = useState(false);
+
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+
+    previousFocusRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    const root = cardRef.current;
+    if (!root) return;
+
+    const getFocusable = () => Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE));
+    const firstFocusable = getFocusable()[0];
+    (firstFocusable ?? root).focus();
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        onCloseRef.current();
+        return;
+      }
+
+      if (event.key !== "Tab") return;
+
+      const items = getFocusable();
+      if (items.length === 0) return;
+
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      const inside = active instanceof Node && root.contains(active);
+
+      if (event.shiftKey) {
+        if (!inside || active === first) {
+          event.preventDefault();
+          last.focus();
+        }
+      } else if (!inside || active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    const previousOverflow = document.body.style.overflow;
+    if (!contained) {
+      document.body.style.overflow = "hidden";
+    }
+
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      if (!contained) {
+        document.body.style.overflow = previousOverflow;
+      }
+      previousFocusRef.current?.focus();
+    };
+  }, [open, contained, mounted]);
+
+  if (!open) return null;
+  if (!contained && !mounted) return null;
+
+  const node = (
+    <div className={`${styles.root} ${contained ? styles.contained : ""}`}>
+      <button type="button" className={styles.scrim} aria-label="Close dialog" onClick={onClose} />
+      <ModalCard
+        ref={cardRef}
+        role="dialog"
+        aria-modal="true"
+        tabIndex={-1}
+        title={title}
+        description={description}
+        size={size}
+        onClose={showClose ? onClose : undefined}
+        footer={footer}
+      >
+        {children}
+      </ModalCard>
+    </div>
+  );
+
+  if (contained) return node;
+  return createPortal(node, document.body);
+}

package/ui/Modal/Modal.types.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export type ModalSize = "sm" | "md" | "lg";
+
+export interface ModalProps {
+  open: boolean;
+  title: string;
+  description?: string;
+  size?: ModalSize;
+  showClose?: boolean;
+  onClose: () => void;
+  children: ReactNode;
+  footer?: ReactNode;
+  contained?: boolean;
+}

package/ui/Modal/index.ts

@@ -0,0 +1,2 @@
+export { Modal } from "./Modal";
+export type { ModalProps, ModalSize } from "./Modal.types";

package/ui/ModalCard/ModalCard.module.css

@@ -0,0 +1,137 @@
+.card {
+  display: grid;
+  gap: var(--space-stack-xs);
+  width: min(100%, 28rem);
+  min-width: 0;
+  padding: var(--space-inset-lg);
+  overflow: auto;
+  background-color: var(--surface-page);
+  border: none;
+  border-radius: var(--radius-control-lg);
+  box-shadow: var(--shadow-modal);
+  outline: none;
+}
+
+.sm {
+  width: min(100%, 22rem);
+  padding: var(--space-inset-md);
+}
+
+.md {
+  width: min(100%, 28rem);
+  padding: var(--space-inset-lg);
+}
+
+.lg {
+  width: min(100%, 36rem);
+  padding: var(--space-inset-xl);
+}
+
+.card[role="dialog"] {
+  max-height: min(90vh, 40rem, 100%);
+  min-height: 0;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  overflow: hidden;
+  animation: cardEnter var(--motion-modal-duration) var(--motion-modal-easing);
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-inline-sm);
+  min-width: 0;
+}
+
+.copy {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-stack-xs);
+  min-width: 0;
+  flex: 1;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body);
+  font-weight: var(--type-weight-heading);
+  line-height: var(--type-line-heading);
+  color: var(--text-primary);
+}
+
+.sm .title {
+  font-size: var(--type-size-body-sm);
+}
+
+.md .title {
+  font-size: var(--type-size-body);
+}
+
+.lg .title {
+  font-size: var(--type-size-heading);
+}
+
+.description {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  line-height: var(--type-line-body);
+  color: var(--text-muted);
+}
+
+.close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 2rem;
+  height: 2rem;
+  margin: 0;
+  padding: 0;
+  color: var(--icon-muted);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-control-sm);
+  cursor: pointer;
+}
+
+.close:hover {
+  background-color: var(--surface-muted);
+  color: var(--icon-primary);
+}
+
+.close:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.body {
+  min-width: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body);
+  line-height: var(--type-line-body);
+  color: var(--text-primary);
+}
+
+.card[role="dialog"] .body {
+  min-height: 0;
+  overflow: auto;
+}
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--space-inline-sm);
+  min-width: 0;
+}
+
+@keyframes cardEnter {
+  from {
+    opacity: var(--opacity-0);
+  }
+  to {
+    opacity: var(--opacity-full);
+  }
+}

package/ui/ModalCard/ModalCard.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { forwardRef, useId } from "react";
+import { LucideByName } from "../Button/lucideName";
+import type { ModalCardProps } from "./ModalCard.types";
+import styles from "./ModalCard.module.css";
+
+export type { ModalCardProps, ModalCardSize } from "./ModalCard.types";
+
+export const ModalCard = forwardRef<HTMLDivElement, ModalCardProps>(function ModalCard(
+  {
+    title,
+    description,
+    size = "md",
+    onClose,
+    children,
+    footer,
+    role = "group",
+    tabIndex,
+    "aria-modal": ariaModal,
+  },
+  ref,
+) {
+  const titleId = useId();
+  const descriptionId = useId();
+
+  return (
+    <div
+      ref={ref}
+      role={role}
+      tabIndex={tabIndex}
+      aria-modal={ariaModal}
+      aria-labelledby={titleId}
+      aria-describedby={description ? descriptionId : undefined}
+      className={`${styles.card} ${styles[size]}`}
+    >
+      <header className={styles.header}>
+        <div className={styles.copy}>
+          <h2 id={titleId} className={styles.title}>
+            {title}
+          </h2>
+          {description ? (
+            <p id={descriptionId} className={styles.description}>
+              {description}
+            </p>
+          ) : null}
+        </div>
+        {onClose ? (
+          <button type="button" className={styles.close} onClick={onClose} aria-label="Close">
+            <LucideByName name="X" size={16} />
+          </button>
+        ) : null}
+      </header>
+      {children ? <div className={styles.body}>{children}</div> : null}
+      {footer ? <div className={styles.footer}>{footer}</div> : null}
+    </div>
+  );
+});

package/ui/ModalCard/ModalCard.types.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export type ModalCardSize = "sm" | "md" | "lg";
+
+export interface ModalCardProps {
+  title: string;
+  description?: string;
+  size?: ModalCardSize;
+  onClose?: () => void;
+  children?: ReactNode;
+  footer?: ReactNode;
+  role?: string;
+  tabIndex?: number;
+  "aria-modal"?: boolean | "true" | "false";
+}

package/ui/ModalCard/index.ts

@@ -0,0 +1,2 @@
+export { ModalCard } from "./ModalCard";
+export type { ModalCardProps, ModalCardSize } from "./ModalCard.types";

package/ui/NavigationMenu/NavigationMenu.module.css

@@ -0,0 +1,31 @@
+.root {
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  flex-wrap: wrap;
+}
+
+.link {
+  display: inline-flex;
+  align-items: center;
+  height: 2.25rem;
+  padding-inline: var(--space-3);
+  border-radius: var(--radius-control-md);
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-label);
+  line-height: var(--type-line-body);
+  text-decoration: none;
+  white-space: nowrap;
+}
+
+.link:hover,
+.linkActive {
+  background-color: var(--surface-muted);
+}
+
+.link:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}

package/ui/NavigationMenu/NavigationMenu.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { useState } from "react";
+import { DropdownMenu } from "../DropdownMenu";
+import type {
+  NavigationMenuDropdownItem,
+  NavigationMenuItem,
+  NavigationMenuProps,
+} from "./NavigationMenu.types";
+import styles from "./NavigationMenu.module.css";
+
+export type {
+  NavigationMenuDropdownItem,
+  NavigationMenuItem,
+  NavigationMenuLinkItem,
+  NavigationMenuProps,
+} from "./NavigationMenu.types";
+
+function isDropdown(item: NavigationMenuItem): item is NavigationMenuDropdownItem {
+  return "groups" in item && Array.isArray((item as NavigationMenuDropdownItem).groups);
+}
+
+export function NavigationMenu({ items, onSelect }: NavigationMenuProps) {
+  const [openId, setOpenId] = useState<string | null>(null);
+
+  return (
+    <nav className={styles.root} aria-label="Site">
+      {items.map((item) => {
+        if (isDropdown(item)) {
+          return (
+            <DropdownMenu
+              key={item.id}
+              trigger={item.label}
+              triggerStyle="nav"
+              groups={item.groups}
+              columns={item.columns}
+              open={openId === item.id}
+              onOpenChange={(next) => setOpenId(next ? item.id : null)}
+              onSelect={onSelect}
+            />
+          );
+        }
+        return (
+          <a
+            key={item.id}
+            href={item.href}
+            className={`${styles.link}${item.active ? ` ${styles.linkActive}` : ""}`}
+            aria-current={item.active ? "page" : undefined}
+            onClick={() => onSelect?.(item.id)}
+          >
+            {item.label}
+          </a>
+        );
+      })}
+    </nav>
+  );
+}

package/ui/NavigationMenu/NavigationMenu.types.ts

@@ -0,0 +1,22 @@
+import type { DropdownMenuGroup } from "../DropdownMenu/DropdownMenu.types";
+
+export interface NavigationMenuLinkItem {
+  id: string;
+  label: string;
+  href: string;
+  active?: boolean;
+}
+
+export interface NavigationMenuDropdownItem {
+  id: string;
+  label: string;
+  groups: DropdownMenuGroup[];
+  columns?: 1 | 2;
+}
+
+export type NavigationMenuItem = NavigationMenuLinkItem | NavigationMenuDropdownItem;
+
+export interface NavigationMenuProps {
+  items: NavigationMenuItem[];
+  onSelect?: (id: string) => void;
+}

package/ui/NavigationMenu/index.ts

@@ -0,0 +1,7 @@
+export { NavigationMenu } from "./NavigationMenu";
+export type {
+  NavigationMenuProps,
+  NavigationMenuItem,
+  NavigationMenuLinkItem,
+  NavigationMenuDropdownItem,
+} from "./NavigationMenu.types";

package/ui/NumberTransition/NumberTransition.module.css

@@ -0,0 +1,110 @@
+.root {
+  --number-transition-duration: var(--motion-modal-duration);
+  display: inline-block;
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-heading-sm);
+  font-weight: var(--type-weight-heading);
+  line-height: var(--type-line-heading);
+  font-variant-numeric: tabular-nums;
+}
+
+.content {
+  display: inline-grid;
+  grid-auto-flow: column;
+}
+
+.cell {
+  display: inline-grid;
+  overflow: hidden;
+}
+
+.old,
+.new {
+  grid-area: 1 / 1;
+}
+
+.changing[data-direction="up"] .old {
+  animation: number-old-up var(--number-transition-duration) var(--motion-expand-easing) both;
+}
+
+.changing[data-direction="up"] .new {
+  animation: number-new-up var(--number-transition-duration) var(--motion-expand-easing) both;
+}
+
+.changing[data-direction="down"] .old {
+  animation: number-old-down var(--number-transition-duration) var(--motion-expand-easing) both;
+}
+
+.changing[data-direction="down"] .new {
+  animation: number-new-down var(--number-transition-duration) var(--motion-expand-easing) both;
+}
+
+.sm {
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-body);
+}
+
+.lg {
+  font-size: var(--type-size-heading);
+}
+
+@keyframes number-old-up {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  to {
+    opacity: 0;
+    transform: translateY(-100%);
+  }
+}
+
+@keyframes number-new-up {
+  from {
+    opacity: 0;
+    transform: translateY(100%);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes number-old-down {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  to {
+    opacity: 0;
+    transform: translateY(100%);
+  }
+}
+
+@keyframes number-new-down {
+  from {
+    opacity: 0;
+    transform: translateY(-100%);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .old {
+    display: none;
+  }
+
+  .new {
+    opacity: 1;
+    animation: none;
+    transform: none;
+  }
+}

package/ui/NumberTransition/NumberTransition.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { useLayoutEffect, useState } from "react";
+import type { NumberTransitionProps } from "./NumberTransition.types";
+import styles from "./NumberTransition.module.css";
+
+export type { NumberTransitionProps, NumberTransitionSize } from "./NumberTransition.types";
+
+function visibleCharacter(character: string): string {
+  return character === " " ? "\u00a0" : character;
+}
+
+export function NumberTransition({
+  value,
+  format,
+  size = "md",
+  label,
+  className = "",
+}: NumberTransitionProps) {
+  const formattedValue = String(format ? format(value) : value);
+  const numericValue = Number(value);
+  const [frame, setFrame] = useState(() => ({
+    previous: formattedValue,
+    current: formattedValue,
+    currentValue: numericValue,
+    direction: "up" as "up" | "down",
+    id: 0,
+  }));
+
+  useLayoutEffect(() => {
+    setFrame((current) => {
+      if (current.current === formattedValue) return current;
+      return {
+        previous: current.current,
+        current: formattedValue,
+        currentValue: numericValue,
+        direction:
+          Number.isFinite(numericValue) &&
+          Number.isFinite(current.currentValue) &&
+          numericValue < current.currentValue
+            ? "down"
+            : "up",
+        id: current.id + 1,
+      };
+    });
+  }, [formattedValue, numericValue]);
+
+  const length = Math.max(frame.previous.length, frame.current.length);
+  const previousCharacters = frame.previous.padStart(length, " ").split("");
+  const currentCharacters = frame.current.padStart(length, " ").split("");
+
+  return (
+    <span
+      className={`${styles.root} ${styles[size]} ${className}`.trim()}
+      aria-label={label ?? formattedValue}
+      aria-live="polite"
+    >
+      <span className={styles.content} aria-hidden="true">
+        {currentCharacters.map((character, index) => {
+          const previousCharacter = previousCharacters[index];
+          const changed = previousCharacter !== character;
+          return (
+            <span
+              className={`${styles.cell}${changed ? ` ${styles.changing}` : ""}`}
+              data-direction={frame.direction}
+              key={`${frame.id}-${index}`}
+            >
+              {changed ? (
+                <span className={styles.old}>{visibleCharacter(previousCharacter)}</span>
+              ) : null}
+              <span className={styles.new}>{visibleCharacter(character)}</span>
+            </span>
+          );
+        })}
+      </span>
+    </span>
+  );
+}

package/ui/NumberTransition/NumberTransition.types.ts

@@ -0,0 +1,9 @@
+export type NumberTransitionSize = "sm" | "md" | "lg";
+
+export interface NumberTransitionProps {
+  value: number | string;
+  format?: (value: number | string) => string;
+  size?: NumberTransitionSize;
+  label?: string;
+  className?: string;
+}

package/ui/NumberTransition/index.ts

@@ -0,0 +1,2 @@
+export { NumberTransition } from "./NumberTransition";
+export type { NumberTransitionProps, NumberTransitionSize } from "./NumberTransition.types";