agentic-ds-kit 0.1.0

package/ui/ShimmerText/ShimmerText.tsx

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+import type { ShimmerTextProps, ShimmerTextSpeed } from "./ShimmerText.types";
+import styles from "./ShimmerText.module.css";
+
+export type { ShimmerTextProps, ShimmerTextSize, ShimmerTextSpeed } from "./ShimmerText.types";
+
+const NAMED_SPEED_FACTORS: Record<Exclude<ShimmerTextSpeed, number>, number> = {
+  slow: 6,
+  normal: 4,
+  fast: 3,
+};
+
+function getDurationFactor(speed: ShimmerTextSpeed): number {
+  if (typeof speed === "number") return speed;
+  return NAMED_SPEED_FACTORS[speed];
+}
+
+export function ShimmerText({
+  children,
+  size = "md",
+  speed = "normal",
+  className = "",
+  style,
+}: ShimmerTextProps) {
+  const text = String(children);
+  const characters = Array.from(text);
+  const phaseSpan = Math.max(characters.length - 1, 1);
+  const cssVars = {
+    "--shimmer-duration-factor": getDurationFactor(speed),
+    ...style,
+  } as CSSProperties;
+
+  return (
+    <span className={`${styles.root} ${styles[size]} ${className}`.trim()} style={cssVars} aria-label={text}>
+      <span className={styles.content} aria-hidden="true">
+        {characters.map((character, index) => (
+          <span
+            className={styles.character}
+            style={{ "--shimmer-phase": 1 - index / phaseSpan } as CSSProperties}
+            key={`${character}-${index}`}
+          >
+            {character}
+          </span>
+        ))}
+      </span>
+    </span>
+  );
+}

package/ui/ShimmerText/ShimmerText.types.ts

@@ -0,0 +1,12 @@
+import type { CSSProperties, ReactNode } from "react";
+
+export type ShimmerTextSize = "sm" | "md" | "lg";
+export type ShimmerTextSpeed = number | "slow" | "normal" | "fast";
+
+export interface ShimmerTextProps {
+  children: ReactNode;
+  size?: ShimmerTextSize;
+  speed?: ShimmerTextSpeed;
+  className?: string;
+  style?: CSSProperties;
+}

package/ui/ShimmerText/index.ts

@@ -0,0 +1,2 @@
+export { ShimmerText } from "./ShimmerText";
+export type { ShimmerTextProps, ShimmerTextSize, ShimmerTextSpeed } from "./ShimmerText.types";

package/ui/SideNav/SideNav.module.css

@@ -0,0 +1,347 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  align-self: stretch;
+  width: var(--layout-sidebar);
+  max-width: var(--layout-sidebar);
+  min-height: 0;
+  overflow: hidden;
+  border: var(--border-surface) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  background: var(--surface-card);
+  color: var(--text-primary);
+  transition:
+    width var(--motion-expand-duration) var(--motion-expand-easing),
+    max-width var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.radiusNone {
+  border-radius: var(--radius-0);
+}
+
+.rootClosed {
+  width: var(--layout-sidebar-compact);
+  max-width: var(--layout-sidebar-compact);
+}
+
+.header {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--space-inline-md);
+  flex-shrink: 0;
+  min-width: 0;
+  padding: var(--space-inset-md) var(--space-inset-lg);
+  border-bottom: var(--border-divider) solid var(--border-subtle);
+  overflow: hidden;
+  transition: padding var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.rootClosed .header {
+  justify-content: center;
+  gap: 0;
+  padding: var(--space-inset-sm);
+}
+
+.mark {
+  display: grid;
+  place-items: center;
+  flex-shrink: 0;
+  width: var(--space-inset-2xl);
+  height: var(--space-inset-2xl);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-control-md);
+  background: var(--fill-brand);
+  color: var(--brand-on-brand);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-label);
+  font-weight: var(--type-weight-label);
+  line-height: 1;
+}
+
+.markButton {
+  appearance: none;
+  cursor: pointer;
+}
+
+.markButton:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.title {
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  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);
+  transition: opacity var(--motion-overlay-duration) var(--motion-overlay-easing);
+}
+
+.rootClosed .title {
+  flex: 0 0 0;
+  width: 0;
+  min-width: 0;
+  max-width: 0;
+  height: 0;
+  margin: 0;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+}
+
+.close {
+  margin-inline-start: auto;
+  flex-shrink: 0;
+  transition: opacity var(--motion-overlay-duration) var(--motion-overlay-easing);
+}
+
+.nav {
+  flex: 1;
+  display: grid;
+  align-content: start;
+  gap: var(--space-stack-md);
+  min-height: 0;
+  padding: var(--space-inset-md) var(--space-inset-lg);
+  overflow-x: hidden;
+  overflow-y: auto;
+  scrollbar-width: none;
+  transition: padding var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.nav::-webkit-scrollbar {
+  display: none;
+}
+
+.rootClosed .nav {
+  padding: var(--space-inset-sm);
+}
+
+.section {
+  position: relative;
+  display: grid;
+  gap: var(--space-stack-xs);
+  min-width: 0;
+}
+
+.sectionLabel {
+  margin: 0;
+  padding-inline: var(--space-inset-md);
+  overflow: hidden;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  color: var(--text-secondary);
+  max-height: 2rem;
+  transition:
+    opacity var(--motion-overlay-duration) var(--motion-overlay-easing),
+    max-height var(--motion-expand-duration) var(--motion-expand-easing),
+    padding var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.rootClosed .sectionLabel {
+  opacity: 0;
+  max-height: 0;
+  padding: 0;
+  pointer-events: none;
+}
+
+.list {
+  display: grid;
+  gap: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.entry {
+  display: grid;
+  min-width: 0;
+}
+
+.item {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--space-inline-md);
+  width: 100%;
+  margin: 0;
+  padding: var(--space-inset-sm) var(--space-inset-md);
+  appearance: none;
+  border: 0;
+  border-radius: var(--radius-control-md);
+  background: transparent;
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  font-weight: var(--type-weight-body);
+  line-height: var(--type-line-body);
+  text-align: start;
+  text-decoration: none;
+  cursor: pointer;
+  transition: padding var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.rootClosed .item {
+  width: auto;
+  justify-self: center;
+  justify-content: center;
+  gap: 0;
+  padding: var(--space-inset-sm);
+  aspect-ratio: 1;
+  line-height: 1;
+  overflow: hidden;
+}
+
+.item:hover:not(:disabled):not(.itemDisabled) {
+  background: var(--surface-muted);
+  color: var(--text-primary);
+}
+
+.itemActive,
+.itemActive:hover:not(:disabled):not(.itemDisabled) {
+  background: var(--surface-brand-subtle);
+  color: var(--text-brand);
+}
+
+.item:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+.item:disabled,
+.itemDisabled {
+  background: var(--surface-disabled);
+  color: var(--text-disabled);
+  cursor: not-allowed;
+}
+
+.icon {
+  display: grid;
+  place-items: center;
+  flex-shrink: 0;
+  width: var(--space-inset-lg);
+  height: var(--space-inset-lg);
+  color: var(--icon-secondary);
+}
+
+.itemActive .icon {
+  color: var(--icon-brand);
+}
+
+.item:disabled .icon,
+.itemDisabled .icon {
+  color: var(--text-disabled);
+}
+
+.label {
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  transition: opacity var(--motion-overlay-duration) var(--motion-overlay-easing);
+}
+
+.rootClosed .label,
+.rootClosed .meta {
+  flex: 0 0 0;
+  width: 0;
+  min-width: 0;
+  max-width: 0;
+  height: 0;
+  margin: 0;
+  padding: 0;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+}
+
+.meta {
+  display: flex;
+  align-items: center;
+  gap: var(--space-inline-xs);
+  margin-inline-start: auto;
+  flex-shrink: 0;
+  overflow: hidden;
+  transition: opacity var(--motion-overlay-duration) var(--motion-overlay-easing);
+}
+
+.badge {
+  padding: var(--space-inset-2xs) var(--space-inset-xs);
+  border-radius: var(--radius-pill);
+  background: var(--surface-muted);
+  color: var(--text-secondary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: 1;
+}
+
+.itemActive .badge {
+  background: var(--surface-brand-subtle);
+  color: var(--text-brand);
+}
+
+.chevron {
+  display: grid;
+  place-items: center;
+  flex-shrink: 0;
+  color: var(--icon-muted);
+  transition: transform var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.chevronOpen {
+  transform: rotate(90deg);
+}
+
+.submenu {
+  display: grid;
+  margin: 0;
+  margin-inline-start: var(--space-inset-lg);
+  padding: 0;
+  padding-inline-start: var(--space-inset-xs);
+  list-style: none;
+  border-inline-start: var(--border-divider) solid var(--border-faint);
+}
+
+.rootClosed .submenu {
+  margin-inline-start: 0;
+  padding-inline-start: 0;
+  border-inline-start: 0;
+}
+
+.footer {
+  flex-shrink: 0;
+  padding: var(--space-inset-md) var(--space-inset-lg);
+  border-top: var(--border-divider) solid var(--border-subtle);
+  transition: padding var(--motion-expand-duration) var(--motion-expand-easing);
+}
+
+.rootClosed .footer {
+  padding: var(--space-inset-sm);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .root,
+  .header,
+  .nav,
+  .footer,
+  .item,
+  .title,
+  .label,
+  .sectionLabel,
+  .meta,
+  .close,
+  .chevron {
+    transition: none;
+  }
+}

package/ui/SideNav/SideNav.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import { useId, useState } from "react";
+import { Button } from "../Button";
+import { LucideByName } from "../Button/lucideName";
+import type { SideNavItem, SideNavProps } from "./SideNav.types";
+import styles from "./SideNav.module.css";
+
+export type {
+  SideNavGroup,
+  SideNavItem,
+  SideNavProps,
+  SideNavRadius,
+  SideNavSide,
+} from "./SideNav.types";
+
+const ICON_SIZE = 16;
+
+function ItemBody({
+  item,
+  expanded,
+}: {
+  item: SideNavItem;
+  expanded?: boolean;
+}) {
+  const nested = Boolean(item.items && item.items.length > 0);
+
+  return (
+    <>
+      {item.icon ? (
+        <span className={styles.icon} aria-hidden>
+          <LucideByName name={item.icon} size={ICON_SIZE} />
+        </span>
+      ) : null}
+      <span className={styles.label}>{item.label}</span>
+      {item.badge || nested ? (
+        <span className={styles.meta}>
+          {item.badge ? <span className={styles.badge}>{item.badge}</span> : null}
+          {nested ? (
+            <span className={`${styles.chevron} ${expanded ? styles.chevronOpen : ""}`}>
+              <LucideByName name="ChevronRight" size={ICON_SIZE} />
+            </span>
+          ) : null}
+        </span>
+      ) : null}
+    </>
+  );
+}
+
+function NavItem({ item, rail }: { item: SideNavItem; rail: boolean }) {
+  const nested = Boolean(item.items && item.items.length > 0);
+  const submenuId = useId();
+  const [expanded, setExpanded] = useState(nested);
+
+  const className = [
+    styles.item,
+    item.active ? styles.itemActive : "",
+    item.disabled ? styles.itemDisabled : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  if (nested) {
+    return (
+      <li className={styles.entry}>
+        <button
+          type="button"
+          className={className}
+          disabled={item.disabled}
+          aria-expanded={expanded}
+          aria-controls={submenuId}
+          aria-current={item.active ? "page" : undefined}
+          onClick={() => {
+            if (!rail) setExpanded((current) => !current);
+          }}
+        >
+          <ItemBody item={item} expanded={expanded} />
+        </button>
+        {expanded && !rail ? (
+          <ul className={styles.submenu} id={submenuId}>
+            {item.items!.map((child) => (
+              <NavItem key={child.id} item={child} rail={rail} />
+            ))}
+          </ul>
+        ) : null}
+      </li>
+    );
+  }
+
+  if (item.onClick && !item.disabled) {
+    return (
+      <li className={styles.entry}>
+        <button
+          type="button"
+          className={className}
+          aria-current={item.active ? "page" : undefined}
+          onClick={item.onClick}
+        >
+          <ItemBody item={item} />
+        </button>
+      </li>
+    );
+  }
+
+  if (item.href && !item.disabled) {
+    return (
+      <li className={styles.entry}>
+        <a
+          href={item.href}
+          className={className}
+          aria-current={item.active ? "page" : undefined}
+        >
+          <ItemBody item={item} />
+        </a>
+      </li>
+    );
+  }
+
+  return (
+    <li className={styles.entry}>
+      <button
+        type="button"
+        className={className}
+        disabled={item.disabled}
+        aria-current={item.active ? "page" : undefined}
+      >
+        <ItemBody item={item} />
+      </button>
+    </li>
+  );
+}
+
+function NavList({ items, rail }: { items: SideNavItem[]; rail: boolean }) {
+  return (
+    <ul className={styles.list}>
+      {items.map((item) => (
+        <NavItem key={item.id} item={item} rail={rail} />
+      ))}
+    </ul>
+  );
+}
+
+export function SideNav({
+  title,
+  mark,
+  showHeader = true,
+  radius = "md",
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  side = "left",
+  groups,
+  items = [],
+  footer,
+}: SideNavProps) {
+  const isControlled = typeof openProp === "boolean";
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const expanded = showHeader ? (isControlled ? openProp : uncontrolledOpen) : true;
+  const useGroups = Boolean(groups && groups.length > 0);
+  const markLetter = (mark && mark.length > 0 ? mark : title.charAt(0)) || "·";
+
+  function setOpen(next: boolean) {
+    if (!isControlled) setUncontrolledOpen(next);
+    onOpenChange?.(next);
+  }
+
+  return (
+    <aside
+      className={`${styles.root} ${radius === "none" ? styles.radiusNone : ""} ${expanded ? "" : styles.rootClosed}`.trim()}
+      aria-label={title}
+      data-side={side}
+    >
+      {showHeader ? (
+        <header className={styles.header}>
+          {expanded ? (
+            <span className={styles.mark} aria-hidden>
+              {markLetter}
+            </span>
+          ) : (
+            <button
+              type="button"
+              className={`${styles.mark} ${styles.markButton}`}
+              aria-label="Open"
+              onClick={() => setOpen(true)}
+            >
+              {markLetter}
+            </button>
+          )}
+          <p className={styles.title}>{title}</p>
+          {expanded ? (
+            <span className={styles.close}>
+              <Button
+                variant="tertiary"
+                size="sm"
+                iconStart={side === "right" ? "PanelRightClose" : "PanelLeftClose"}
+                ariaLabel="Close"
+                onClick={() => setOpen(false)}
+              />
+            </span>
+          ) : null}
+        </header>
+      ) : null}
+
+      <nav className={styles.nav} aria-label={title}>
+        {useGroups
+          ? groups!.map((group) => (
+              <div key={group.label} className={styles.section}>
+                <p className={styles.sectionLabel}>{group.label}</p>
+                <NavList items={group.items} rail={!expanded} />
+              </div>
+            ))
+          : <NavList items={items} rail={!expanded} />}
+      </nav>
+
+      {footer ? (
+        <div className={styles.footer}>
+          <NavList items={Array.isArray(footer) ? footer : [footer]} rail={!expanded} />
+        </div>
+      ) : null}
+    </aside>
+  );
+}

package/ui/SideNav/SideNav.types.ts

@@ -0,0 +1,42 @@
+export type SideNavSide = "left" | "right";
+
+export type SideNavRadius = "md" | "none";
+
+export interface SideNavItem {
+  id: string;
+  label: string;
+  href?: string;
+  /** In-app select. When set, the leaf is a button and href is not used. */
+  onClick?: () => void;
+  /** Lucide name, via LucideByName from @/ui/Button/lucideName */
+  icon?: string;
+  active?: boolean;
+  disabled?: boolean;
+  badge?: string;
+  /** One nested submenu level. */
+  items?: SideNavItem[];
+}
+
+export interface SideNavGroup {
+  label: string;
+  items: SideNavItem[];
+}
+
+export interface SideNavProps {
+  title: string;
+  /** Brand letter; default first char of title. */
+  mark?: string;
+  /** Brand header and close. Default true. Set false when AppHeader already provides brand. */
+  showHeader?: boolean;
+  /** Rail corners. Default md. Use none when SideNav is flush in an app shell. */
+  radius?: SideNavRadius;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  side?: SideNavSide;
+  groups?: SideNavGroup[];
+  /** Flat list if no groups. */
+  items?: SideNavItem[];
+  /** Footer rows. One or many. */
+  footer?: SideNavItem | SideNavItem[];
+}

package/ui/SideNav/index.ts

@@ -0,0 +1,8 @@
+export { SideNav } from "./SideNav";
+export type {
+  SideNavProps,
+  SideNavRadius,
+  SideNavSide,
+  SideNavItem,
+  SideNavGroup,
+} from "./SideNav.types";