agentic-ds-kit 0.1.0

package/ui/Scorecard/Scorecard.module.css

@@ -0,0 +1,150 @@
+.card {
+  display: grid;
+  gap: var(--space-stack-sm);
+  width: min(100%, 16rem);
+  min-width: 0;
+  margin: 0;
+  padding: var(--space-inset-md);
+  border: var(--border-highlight) solid var(--border-faint);
+  border-radius: var(--radius-surface-md);
+  background: var(--surface-card);
+  font-family: var(--font-sans);
+  text-align: start;
+}
+
+.sm {
+  width: min(100%, 12.5rem);
+  gap: var(--space-stack-xs);
+  padding: var(--space-inset-sm);
+}
+
+.md {
+  width: min(100%, 16rem);
+}
+
+.lg {
+  width: min(100%, 20rem);
+  gap: var(--space-stack-md);
+  padding: var(--space-inset-lg);
+}
+
+.fill {
+  width: 100%;
+  max-width: none;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-inline-sm);
+  min-width: 0;
+}
+
+.badgeSlot {
+  flex-shrink: 0;
+  margin-inline-start: auto;
+}
+
+.label {
+  min-width: 0;
+  color: var(--text-secondary);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+}
+
+.value {
+  color: var(--text-primary);
+  font-size: var(--type-size-title);
+  font-weight: var(--type-weight-metric);
+  line-height: var(--type-line-heading);
+  font-variant-numeric: tabular-nums;
+  font-feature-settings: "tnum";
+}
+
+.sm .value {
+  font-size: var(--type-size-heading);
+}
+
+.lg .value {
+  font-size: var(--type-size-metric);
+}
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-inline-xs) var(--space-inline-sm);
+}
+
+.delta {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-inline-xs);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+}
+
+.icon {
+  display: block;
+  flex-shrink: 0;
+  width: 0.95rem;
+  height: 0.95rem;
+}
+
+.up {
+  color: var(--text-success);
+}
+
+.down {
+  color: var(--text-danger);
+}
+
+.flat,
+.neutral {
+  color: var(--text-secondary);
+}
+
+.hint {
+  color: var(--text-muted);
+  font-size: var(--type-size-caption);
+  font-weight: var(--type-weight-caption);
+  line-height: var(--type-line-body);
+}
+
+.interactive {
+  appearance: none;
+  font: inherit;
+  color: inherit;
+  text-align: start;
+  background: var(--surface-card);
+  cursor: pointer;
+  transition:
+    transform var(--motion-interaction-duration) var(--motion-interaction-easing),
+    border-color var(--motion-interaction-duration) var(--motion-interaction-easing);
+}
+
+.interactive:hover {
+  border-color: var(--border-strong);
+}
+
+.interactive:active {
+  transform: scale(0.98);
+}
+
+.interactive:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .interactive {
+    transition: none;
+  }
+
+  .interactive:active {
+    transform: none;
+  }
+}

package/ui/Scorecard/Scorecard.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useId } from "react";
+import { Badge } from "../Badge";
+import { LucideByName } from "../Button/lucideName";
+import type { ScorecardProps, ScorecardTrend } from "./Scorecard.types";
+import styles from "./Scorecard.module.css";
+
+export type { ScorecardProps, ScorecardTrend, ScorecardSize } from "./Scorecard.types";
+
+const TREND_ICON: Record<ScorecardTrend, string> = {
+  up: "TrendingUp",
+  down: "TrendingDown",
+  flat: "Minus",
+  neutral: "Minus",
+};
+
+const TREND_CLASS: Record<ScorecardTrend, string> = {
+  up: styles.up,
+  down: styles.down,
+  flat: styles.flat,
+  neutral: styles.neutral,
+};
+
+export function Scorecard({
+  label,
+  value,
+  delta,
+  trend = "neutral",
+  hint,
+  size = "md",
+  badge,
+  badgeTone = "neutral",
+  onClick,
+  fill = false,
+}: ScorecardProps) {
+  const labelId = useId();
+  const valueId = useId();
+  const labelledBy = label ? `${labelId} ${valueId}` : valueId;
+  const className = [styles.card, styles[size], fill ? styles.fill : "", onClick ? styles.interactive : ""]
+    .filter(Boolean)
+    .join(" ");
+
+  const body = (
+    <>
+      {label || badge ? (
+        <span className={styles.header}>
+          {label ? (
+            <span id={labelId} className={styles.label}>
+              {label}
+            </span>
+          ) : null}
+          {badge ? (
+            <span className={styles.badgeSlot}>
+              <Badge size="sm" tone={badgeTone}>
+                {badge}
+              </Badge>
+            </span>
+          ) : null}
+        </span>
+      ) : null}
+      <span id={valueId} className={styles.value}>
+        {value}
+      </span>
+      {delta || hint ? (
+        <span className={styles.footer}>
+          {delta ? (
+            <span className={`${styles.delta} ${TREND_CLASS[trend]}`}>
+              <LucideByName name={TREND_ICON[trend]} size={15} className={styles.icon} />
+              {delta}
+            </span>
+          ) : null}
+          {hint ? <span className={styles.hint}>{hint}</span> : null}
+        </span>
+      ) : null}
+    </>
+  );
+
+  if (onClick) {
+    return (
+      <button type="button" className={className} onClick={onClick} aria-labelledby={labelledBy}>
+        {body}
+      </button>
+    );
+  }
+
+  return (
+    <article className={className} aria-labelledby={labelledBy}>
+      {body}
+    </article>
+  );
+}

package/ui/Scorecard/Scorecard.types.ts

@@ -0,0 +1,18 @@
+import type { BadgeTone } from "../Badge/Badge.types";
+
+export type ScorecardTrend = "up" | "down" | "flat" | "neutral";
+
+export type ScorecardSize = "sm" | "md" | "lg";
+
+export interface ScorecardProps {
+  label: string;
+  value: string;
+  delta?: string;
+  trend?: ScorecardTrend;
+  hint?: string;
+  size?: ScorecardSize;
+  badge?: string;
+  badgeTone?: BadgeTone;
+  onClick?: () => void;
+  fill?: boolean;
+}

package/ui/Scorecard/index.ts

@@ -0,0 +1,2 @@
+export { Scorecard } from "./Scorecard";
+export type { ScorecardProps, ScorecardTrend, ScorecardSize } from "./Scorecard.types";

package/ui/Section/Section.module.css

@@ -0,0 +1,104 @@
+.section {
+  --section-space: var(--space-section-md);
+  --section-header-gap: var(--space-stack-sm);
+  width: 100%;
+  min-width: 0;
+  margin: 0 0 var(--section-space);
+}
+
+.sm {
+  --section-space: var(--space-section-sm);
+  --section-header-gap: var(--space-stack-sm);
+}
+
+.md {
+  --section-space: var(--space-section-md);
+  --section-header-gap: var(--space-stack-md);
+}
+
+.lg {
+  --section-space: var(--space-section-lg);
+  --section-header-gap: var(--space-stack-lg);
+}
+
+.header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-inline-sm) var(--space-inline-lg);
+  margin: 0;
+  padding-bottom: var(--section-header-gap);
+}
+
+.collapsible:has(> .body[hidden]) .header {
+  padding-bottom: 0;
+}
+
+.heading {
+  display: grid;
+  gap: var(--space-stack-xs);
+  min-width: 0;
+  flex: 1;
+}
+
+.title {
+  margin: 0;
+  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);
+}
+
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  max-width: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+}
+
+.trigger:focus-visible {
+  outline: var(--border-focus-width) solid var(--focus-ring);
+  outline-offset: var(--space-inset-2xs);
+  border-radius: var(--radius-control-sm);
+}
+
+.chevron {
+  flex-shrink: 0;
+  color: var(--icon-muted);
+}
+
+.collapsible .description {
+  padding-inline-start: calc(18px + var(--space-2));
+}
+
+.description {
+  margin: 0;
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body-sm);
+  line-height: var(--type-line-body);
+  color: var(--text-secondary);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-inline-sm);
+  flex-shrink: 0;
+}
+
+.body {
+  width: 100%;
+  min-width: 0;
+}
+

package/ui/Section/Section.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { useId, useState } from "react";
+import { LucideByName } from "../Button/lucideName";
+import type { SectionProps } from "./Section.types";
+import styles from "./Section.module.css";
+
+export type { SectionProps, SectionSize } from "./Section.types";
+
+export function Section({
+  title,
+  description,
+  size = "md",
+  actions,
+  children,
+  collapsible = true,
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange,
+}: SectionProps) {
+  const headingId = useId();
+  const panelId = useId();
+  const canCollapse = Boolean(collapsible && title);
+  const isControlled = typeof openProp === "boolean";
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const open = canCollapse ? (isControlled ? openProp : uncontrolledOpen) : true;
+
+  function setOpen(next: boolean) {
+    if (!isControlled) setUncontrolledOpen(next);
+    onOpenChange?.(next);
+  }
+
+  const showHeader = Boolean(title || description || actions);
+
+  return (
+    <section
+      className={`${styles.section} ${styles[size]}${canCollapse ? ` ${styles.collapsible}` : ""}`}
+      aria-labelledby={title ? headingId : undefined}
+    >
+      {showHeader ? (
+        <header className={styles.header}>
+          <div className={styles.heading}>
+            {title ? (
+              <h2 id={headingId} className={styles.title}>
+                {canCollapse ? (
+                  <button
+                    type="button"
+                    className={styles.trigger}
+                    aria-expanded={open}
+                    aria-controls={panelId}
+                    onClick={() => setOpen(!open)}
+                  >
+                    <LucideByName
+                      name={open ? "ChevronDown" : "ChevronRight"}
+                      size={18}
+                      className={styles.chevron}
+                    />
+                    {title}
+                  </button>
+                ) : (
+                  title
+                )}
+              </h2>
+            ) : null}
+            {description ? <p className={styles.description}>{description}</p> : null}
+          </div>
+          {actions ? <div className={styles.actions}>{actions}</div> : null}
+        </header>
+      ) : null}
+      <div id={canCollapse ? panelId : undefined} className={styles.body} hidden={canCollapse ? !open : undefined}>
+        {children}
+      </div>
+    </section>
+  );
+}

package/ui/Section/Section.types.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export type SectionSize = "sm" | "md" | "lg";
+
+export interface SectionProps {
+  title?: string;
+  description?: string;
+  size?: SectionSize;
+  actions?: ReactNode;
+  children: ReactNode;
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}

package/ui/Section/index.ts

@@ -0,0 +1,2 @@
+export { Section } from "./Section";
+export type { SectionProps, SectionSize } from "./Section.types";

package/ui/Select/Select.module.css

@@ -0,0 +1,7 @@
+.select {
+  cursor: pointer;
+}
+
+.select:disabled {
+  cursor: not-allowed;
+}

package/ui/Select/Select.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { useState } from "react";
+import { DropdownMenu } from "../DropdownMenu";
+import type { SelectProps } from "./Select.types";
+
+export type { SelectProps, SelectOption, SelectSize, SelectItemCheck } from "./Select.types";
+
+function optionId(value: string): string {
+  return value === "" ? "__empty" : value;
+}
+
+function asList(value: string | string[] | undefined): string[] {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) return value;
+  return [value];
+}
+
+function initialValue(
+  multiple: boolean,
+  placeholder: string | undefined,
+  defaultValue: string | string[] | undefined,
+  first: string | undefined,
+): string | string[] {
+  if (defaultValue !== undefined) return defaultValue;
+  if (multiple) return [];
+  if (placeholder) return "";
+  return first ?? "";
+}
+
+export function Select({
+  id,
+  size = "md",
+  options,
+  disabled = false,
+  error = false,
+  multiple = false,
+  itemCheck = "check",
+  maxVisible,
+  searchable = false,
+  placeholder,
+  defaultValue,
+  value: valueProp,
+  onChange,
+  name,
+  ariaLabel,
+  describedBy,
+}: SelectProps) {
+  const [uncontrolled, setUncontrolled] = useState<string | string[]>(() =>
+    initialValue(multiple, placeholder, defaultValue, options[0]?.value),
+  );
+  const isControlled = valueProp !== undefined;
+  const raw = isControlled ? valueProp : uncontrolled;
+  const values = asList(raw);
+  const selectedOptions = options.filter((option) => values.includes(option.value));
+  const overflow =
+    multiple && maxVisible !== undefined && selectedOptions.length > maxVisible
+      ? selectedOptions.length - maxVisible
+      : 0;
+  const shown = overflow > 0 ? selectedOptions.slice(0, maxVisible) : selectedOptions;
+  const trigger =
+    shown.length > 0 ? shown.map((option) => option.label).join(", ") : placeholder || "Select";
+  const muted = selectedOptions.length === 0;
+  const useCheckbox = multiple && itemCheck === "checkbox";
+
+  function emit(next: string | string[]) {
+    if (!isControlled) setUncontrolled(next);
+    onChange?.(next);
+  }
+
+  return (
+    <>
+      {name ? (
+        <input type="hidden" name={name} value={multiple ? values.join(",") : (values[0] ?? "")} />
+      ) : null}
+      <DropdownMenu
+        id={id}
+        triggerStyle="field"
+        trigger={trigger}
+        triggerMuted={muted}
+        triggerBadge={overflow > 0 ? `+${overflow}` : undefined}
+        iconEnd="ChevronsUpDown"
+        size={size === "sm" ? "sm" : "md"}
+        disabled={disabled}
+        error={error}
+        describedBy={describedBy}
+        ariaLabel={ariaLabel}
+        closeOnSelect={!multiple}
+        searchable={searchable}
+        groups={[
+          {
+            items: options.map((option) => ({
+              id: optionId(option.value),
+              label: option.label,
+              selected: values.includes(option.value),
+              checkbox: useCheckbox || undefined,
+            })),
+          },
+        ]}
+        onSelect={(next) => {
+          const match = options.find((option) => optionId(option.value) === next);
+          if (!match) return;
+          if (multiple) {
+            const has = values.includes(match.value);
+            emit(has ? values.filter((value) => value !== match.value) : [...values, match.value]);
+            return;
+          }
+          emit(match.value);
+        }}
+      />
+    </>
+  );
+}

package/ui/Select/Select.types.ts

@@ -0,0 +1,26 @@
+export type SelectSize = "sm" | "md";
+export type SelectItemCheck = "check" | "checkbox";
+
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+export interface SelectProps {
+  id: string;
+  size?: SelectSize;
+  options: SelectOption[];
+  disabled?: boolean;
+  error?: boolean;
+  multiple?: boolean;
+  itemCheck?: SelectItemCheck;
+  maxVisible?: number;
+  searchable?: boolean;
+  placeholder?: string;
+  defaultValue?: string | string[];
+  value?: string | string[];
+  onChange?: (value: string | string[]) => void;
+  name?: string;
+  ariaLabel?: string;
+  describedBy?: string;
+}

package/ui/Select/index.ts

@@ -0,0 +1,2 @@
+export { Select } from "./Select";
+export type { SelectProps, SelectOption, SelectSize, SelectItemCheck } from "./Select.types";

package/ui/ShimmerText/ShimmerText.module.css

@@ -0,0 +1,46 @@
+.root {
+  --shimmer-text-duration: calc(var(--motion-modal-duration) * var(--shimmer-duration-factor, 4));
+  display: inline-block;
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--type-size-body);
+  line-height: var(--type-line-body);
+}
+
+.content {
+  white-space: pre-wrap;
+}
+
+.character {
+  display: inline-block;
+  opacity: 0.45;
+  animation: shimmer-wave var(--shimmer-text-duration) var(--motion-expand-easing) infinite;
+  animation-delay: calc(var(--shimmer-text-duration) * var(--shimmer-phase) * -1);
+}
+
+.sm {
+  font-size: var(--type-size-body-sm);
+}
+
+.lg {
+  font-size: var(--type-size-heading-sm);
+  font-weight: var(--type-weight-heading);
+}
+
+@keyframes shimmer-wave {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+
+  50% {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .character {
+    opacity: 1;
+    animation: none;
+  }
+}