@toolr/ui-design 0.1.0

package/components/diagrams/diagram-utils.tsx

@@ -0,0 +1,908 @@
+/* eslint-disable react-refresh/only-export-components */
+/**
+ * Shared Motion + Visx utilities for diagram components.
+ *
+ * Replaces the per-file CSS keyframe animations, `useDelayedMount`, and
+ * `DiagramWrapper` boilerplate with declarative Motion variants.
+ *
+ * Usage:
+ *   import { DiagramWrapper, stagger, item, dashItem, MAnimatedPath } from './diagram-utils'
+ *
+ *   <DiagramWrapper>
+ *     <svg ...>
+ *       <motion.g variants={stagger()}>
+ *         <motion.g variants={item}>...</motion.g>
+ *         <motion.g variants={item}>...</motion.g>
+ *       </motion.g>
+ *     </svg>
+ *   </DiagramWrapper>
+ */
+
+import type { ReactNode } from 'react'
+import { motion, type Variants } from 'motion/react'
+
+// ============================================================================
+// Design Tokens – single source of truth for all diagram dimensions & styles
+// ============================================================================
+
+/** Standard viewBox width for all diagrams. */
+const VB_W = 420
+
+/** ViewBox height tiers. Pick the smallest that fits your content. */
+const VB_H = { compact: 200, standard: 240, tall: 280, extended: 340, large: 420, xlarge: 520, xxlarge: 580 } as const
+
+/** Pre-built viewBox strings: `"0 0 420 <height>"` */
+export const viewBox = {
+  compact: `0 0 ${VB_W} ${VB_H.compact}`,
+  standard: `0 0 ${VB_W} ${VB_H.standard}`,
+  tall: `0 0 ${VB_W} ${VB_H.tall}`,
+  extended: `0 0 ${VB_W} ${VB_H.extended}`,
+  large: `0 0 ${VB_W} ${VB_H.large}`,
+  xlarge: `0 0 ${VB_W} ${VB_H.xlarge}`,
+  xxlarge: `0 0 ${VB_W} ${VB_H.xxlarge}`,
+} as const
+
+/** Font size tiers (SVG units). 1 SVG unit ≈ 3px at max-width 1260px (3×420). */
+export const font = {
+  icon: 10, // 30px at 3× scale – decorative icon-text inside circles
+  primary: 5.33, // 16px at 3× scale
+  secondary: 4.67, // 14px at 3× scale
+  small: 4, // 12px at 3× scale
+  micro: 3, // 9px at 3× scale – constrained layouts (multi-line in tiny boxes)
+} as const
+
+/** Standard box dimensions [width, height] by role. */
+export const box = {
+  nodeMain: { w: 120, h: 55 },
+  nodeCard: { w: 95, h: 50 },
+  nodeSmall: { w: 80, h: 32 },
+  infoBox: { w: 360, h: 28 },
+  codeBlock: { w: 360, h: 28 },
+} as const
+
+/** Spacing constants (SVG units). */
+export const spacing = {
+  margin: 20,
+  gapSm: 10,
+  gapMd: 20,
+  gapLg: 35,
+  centerX: 210,
+  titleY: 18,
+} as const
+
+/** Border radius tiers. */
+export const radius = { lg: 8, md: 6, sm: 4 } as const
+
+/** Stroke width tiers. */
+export const stroke = {
+  bold: 2,
+  normal: 1.5,
+  thin: 1,
+  hairline: 0.5,
+} as const
+
+/** Semantic text colors. */
+export const color = {
+  textBright: '#e5e7eb',
+  textMedium: '#9ca3af',
+  textDim: '#6b7280',
+  bgDark: '#1f2937',
+  bgDarker: '#0f172a',
+  border: '#374151',
+} as const
+
+/** Dark tint backgrounds for colored overlays (use with fillOpacity). */
+export const tint = {
+  red: '#7f1d1d',
+  emerald: '#064e3b',
+  blue: '#1e3a5f',
+} as const
+
+/** Accent palette – pick by semantic intent, not by hue. */
+export const accent = {
+  cyan: '#22d3ee',
+  teal: '#2dd4bf',
+  blue: '#60a5fa',
+  purple: '#a78bfa',
+  violet: '#c084fc',
+  green: '#34d399',
+  lime: '#4ade80',
+  yellow: '#fbbf24',
+  orange: '#fb923c',
+  red: '#ef4444',
+  redLight: '#f87171',
+  pink: '#f472b6',
+  pinkLight: '#fda4af',
+  indigo: '#a5b4fc',
+  emerald: '#10b981',
+  amber: '#f59e0b',
+  fuchsia: '#d946ef',
+  rose: '#fb7185',
+  sky: '#38bdf8',
+} as const
+
+/**
+ * Convenience bundle for imports:
+ *   import { D } from './diagram-utils'
+ *   <rect rx={D.radius.md} strokeWidth={D.stroke.normal} />
+ */
+export const D = {
+  viewBox,
+  font,
+  box,
+  spacing,
+  radius,
+  stroke,
+  color,
+  tint,
+  accent,
+} as const
+
+// ============================================================================
+// DiagramWrapper – fade-in container (replaces per-file DiagramWrapper + <style>)
+// ============================================================================
+
+export function DiagramWrapper({ children }: { children: ReactNode; sourceUrl?: string }) {
+  return (
+    <motion.div
+      className="relative flex flex-col h-full"
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: 0.3, ease: 'easeOut' }}
+    >
+      <div className="flex-1 max-w-[1260px] mx-auto w-full">
+        {children}
+      </div>
+    </motion.div>
+  )
+}
+
+// ============================================================================
+// Variants – declarative stagger & item animations
+// ============================================================================
+
+/**
+ * Container variant that staggers children.
+ * @param staggerDelay – seconds between each child (default 0.05)
+ * @param delayStart  – initial delay before first child (default 0)
+ */
+export function stagger(staggerDelay = 0.05, delayStart = 0): Variants {
+  return {
+    hidden: {},
+    visible: {
+      transition: {
+        delayChildren: delayStart,
+        staggerChildren: staggerDelay,
+      },
+    },
+  }
+}
+
+/** Standard fade-in-up item variant (replaces all FADE_IN_UP_* constants). */
+export const item: Variants = {
+  hidden: { opacity: 0, y: 8 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: { duration: 0.35, ease: 'easeOut' },
+  },
+}
+
+/** Slide-in from left variant. */
+export const slideInItem: Variants = {
+  hidden: { opacity: 0, x: -10 },
+  visible: {
+    opacity: 1,
+    x: 0,
+    transition: { duration: 0.35, ease: 'easeOut' },
+  },
+}
+
+/** Scale-in item variant (good for circles / icons). */
+export const scaleItem: Variants = {
+  hidden: { opacity: 0, scale: 0.85 },
+  visible: {
+    opacity: 1,
+    scale: 1,
+    transition: { duration: 0.3, ease: 'easeOut' },
+  },
+}
+
+// ============================================================================
+// Animated SVG dash path – replaces manual <animate> elements
+// ============================================================================
+
+/**
+ * An SVG <path> with an infinite animated dash offset.
+ * Replaces:
+ *   <path strokeDasharray="4 3">
+ *     <animate attributeName="stroke-dashoffset" values="0;-14" dur="1.2s" ... />
+ *   </path>
+ */
+export function AnimatedDashPath({
+  d,
+  stroke,
+  strokeWidth = 1.5,
+  dashArray = '4 3',
+  opacity = 0.6,
+  duration = 1.2,
+  delay = 0,
+}: {
+  d: string
+  stroke: string
+  strokeWidth?: number
+  dashArray?: string
+  opacity?: number
+  duration?: number
+  delay?: number
+}) {
+  return (
+    <motion.path
+      d={d}
+      stroke={stroke}
+      strokeWidth={strokeWidth}
+      strokeDasharray={dashArray}
+      opacity={opacity}
+      fill="none"
+      initial={{ strokeDashoffset: 0 }}
+      animate={{ strokeDashoffset: -14 }}
+      transition={{
+        duration,
+        delay,
+        ease: 'linear',
+        repeat: Infinity,
+      }}
+    />
+  )
+}
+
+// ============================================================================
+// Reusable Diagram Primitives
+// ============================================================================
+
+/**
+ * Standard diagram title text rendered at top center.
+ * Every diagram should have exactly one of these.
+ */
+export function DiagramTitle({ children, y = spacing.titleY }: { children: string; y?: number }) {
+  return (
+    <text
+      x={spacing.centerX}
+      y={y}
+      fill={color.textDim}
+      fontSize={font.primary}
+      textAnchor="middle"
+      fontWeight="600"
+      letterSpacing="0.5"
+    >
+      {children}
+    </text>
+  )
+}
+
+/**
+ * A rounded rectangle node with a heading and optional body text.
+ * Renders a filled rect with border, centered heading, and up to two body lines.
+ *
+ * Use explicit `headingY` / `bodyY` / `body2Y` to match hand-positioned layouts.
+ * When omitted, text positions are calculated from the box dimensions.
+ */
+export function DiagramNode({
+  x,
+  y,
+  width,
+  height,
+  heading,
+  body,
+  body2,
+  accentColor,
+  rx = radius.md,
+  fill: bgFill = color.bgDark,
+  strokeWidth: sw = stroke.normal,
+  headingWeight = '600',
+  headingColor,
+  bodyColor = color.textDim,
+  headingY: explicitHeadingY,
+  bodyY: explicitBodyY,
+  body2Y: explicitBody2Y,
+}: {
+  x: number
+  y: number
+  width: number
+  height: number
+  heading: string
+  body?: string
+  body2?: string
+  accentColor: string
+  rx?: number
+  fill?: string
+  strokeWidth?: number
+  headingWeight?: string
+  headingColor?: string
+  bodyColor?: string
+  headingY?: number
+  bodyY?: number
+  body2Y?: number
+}) {
+  const cx = x + width / 2
+  const hasBody2 = body2 != null
+  const hasBody = body != null
+  const headingY = explicitHeadingY ?? (hasBody ? y + height * 0.38 : y + height / 2 + font.primary / 3)
+  const bodyY = explicitBodyY ?? (hasBody2 ? y + height * 0.6 : y + height * 0.7)
+  const body2Y = explicitBody2Y ?? y + height * 0.82
+
+  return (
+    <>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={rx}
+        fill={bgFill}
+        stroke={accentColor}
+        strokeWidth={sw}
+      />
+      <text
+        x={cx}
+        y={headingY}
+        fill={headingColor ?? accentColor}
+        fontSize={font.primary}
+        textAnchor="middle"
+        fontWeight={headingWeight}
+      >
+        {heading}
+      </text>
+      {hasBody && (
+        <text x={cx} y={bodyY} fill={bodyColor} fontSize={font.secondary} textAnchor="middle">
+          {body}
+        </text>
+      )}
+      {hasBody2 && (
+        <text x={cx} y={body2Y} fill={bodyColor} fontSize={font.small} textAnchor="middle">
+          {body2}
+        </text>
+      )}
+    </>
+  )
+}
+
+/**
+ * Full-width info strip at the bottom of a diagram.
+ * Renders a rect with one or more centered text lines inside.
+ */
+export function DiagramInfoBox({
+  y,
+  height = box.infoBox.h,
+  children,
+  borderColor = color.border,
+  fill: bgFill = color.bgDark,
+  rx = radius.md,
+}: {
+  y: number
+  height?: number
+  children: ReactNode
+  borderColor?: string
+  fill?: string
+  rx?: number
+}) {
+  return (
+    <>
+      <rect
+        x="30"
+        y={y}
+        width={box.infoBox.w}
+        height={height}
+        rx={rx}
+        fill={bgFill}
+        stroke={borderColor}
+        strokeWidth={stroke.thin}
+      />
+      {children}
+    </>
+  )
+}
+
+/**
+ * Full-width code display box with a dark background.
+ * Children should be <text> elements with monospace font.
+ */
+export function DiagramCodeBlock({
+  x = 30,
+  y,
+  width = box.codeBlock.w,
+  height = box.codeBlock.h,
+  children,
+  borderColor = color.border,
+  rx = radius.sm,
+}: {
+  x?: number
+  y: number
+  width?: number
+  height?: number
+  children?: ReactNode
+  borderColor?: string
+  rx?: number
+}) {
+  return (
+    <>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={rx}
+        fill={color.bgDarker}
+        stroke={borderColor}
+        strokeWidth={stroke.thin}
+      />
+      {children}
+    </>
+  )
+}
+
+/**
+ * Small text badge/pill with tinted background.
+ */
+export function DiagramBadge({
+  x,
+  y,
+  width,
+  height = 14,
+  label,
+  accentColor,
+  fillOpacity = 0.1,
+  rx = radius.sm,
+}: {
+  x: number
+  y: number
+  width: number
+  height?: number
+  label: string
+  accentColor: string
+  fillOpacity?: number
+  rx?: number
+}) {
+  return (
+    <>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={rx}
+        fill={accentColor}
+        fillOpacity={fillOpacity}
+        stroke={accentColor}
+        strokeWidth={stroke.hairline}
+      />
+      <text
+        x={x + width / 2}
+        y={y + height / 2 + font.small / 3}
+        fill={accentColor}
+        fontSize={font.small}
+        textAnchor="middle"
+      >
+        {label}
+      </text>
+    </>
+  )
+}
+
+// ============================================================================
+// StepMarker – numbered circle with optional connector line
+// ============================================================================
+
+export function StepMarker({
+  cx,
+  cy,
+  n,
+  accentColor,
+  connectorToY,
+  r = 10,
+}: {
+  cx: number
+  cy: number
+  n: number
+  accentColor: string
+  connectorToY?: number
+  r?: number
+}) {
+  return (
+    <>
+      <circle
+        cx={cx}
+        cy={cy}
+        r={r}
+        fill={accentColor}
+        fillOpacity={0.15}
+        stroke={accentColor}
+        strokeWidth={stroke.thin}
+      />
+      <text
+        x={cx}
+        y={cy + font.primary / 3}
+        fill={accentColor}
+        fontSize={font.primary}
+        textAnchor="middle"
+        fontWeight="600"
+      >
+        {n}
+      </text>
+      {connectorToY != null && (
+        <line
+          x1={cx}
+          y1={cy + r + 2}
+          x2={cx}
+          y2={connectorToY}
+          stroke={color.border}
+          strokeWidth={stroke.thin}
+          strokeDasharray="3 3"
+        />
+      )}
+    </>
+  )
+}
+
+// ============================================================================
+// ArrowMarker – reusable SVG <marker> for ArrowPath
+// ============================================================================
+
+export function ArrowMarker({
+  id,
+  color: fill,
+  opacity = 0.7,
+}: {
+  id: string
+  color: string
+  opacity?: number
+}) {
+  return (
+    <marker
+      id={id}
+      markerWidth="5"
+      markerHeight="4"
+      refX="4"
+      refY="2"
+      orient="auto"
+    >
+      <path d="M 0 0 L 5 2 L 0 4 Z" fill={fill} fillOpacity={opacity} />
+    </marker>
+  )
+}
+
+// ============================================================================
+// ArrowPath – line with arrowhead marker
+// ============================================================================
+
+export function ArrowPath({
+  d,
+  color: strokeColor,
+  dashed = false,
+  strokeWidth: sw = stroke.normal,
+  markerEnd,
+  opacity: op = 1,
+}: {
+  d: string
+  color: string
+  dashed?: boolean
+  strokeWidth?: number
+  markerEnd?: string
+  opacity?: number
+}) {
+  return (
+    <path
+      d={d}
+      stroke={strokeColor}
+      strokeWidth={sw}
+      fill="none"
+      opacity={op}
+      {...(dashed ? { strokeDasharray: '4 3' } : {})}
+      {...(markerEnd ? { markerEnd: `url(#${markerEnd})` } : {})}
+    />
+  )
+}
+
+// ============================================================================
+// LayerBar – horizontal bar with colored left accent stripe
+// ============================================================================
+
+export function LayerBar({
+  x,
+  y,
+  width,
+  label,
+  detail,
+  accentColor,
+  opacity: op = 1,
+  height = 30,
+}: {
+  x: number
+  y: number
+  width: number
+  label: string
+  detail?: string
+  accentColor: string
+  opacity?: number
+  height?: number
+}) {
+  return (
+    <>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={radius.md}
+        fill={color.bgDark}
+        stroke={accentColor}
+        strokeWidth={stroke.normal}
+        opacity={op}
+      />
+      <rect
+        x={x}
+        y={y}
+        width={5}
+        height={height}
+        rx={2}
+        fill={accentColor}
+        opacity={op}
+      />
+      <text
+        x={x + 15}
+        y={y + (detail ? height * 0.42 : height / 2 + font.primary / 3)}
+        fill={accentColor}
+        fontSize={font.primary}
+        fontWeight="600"
+        opacity={op}
+      >
+        {label}
+      </text>
+      {detail && (
+        <text
+          x={x + 15}
+          y={y + height * 0.78}
+          fill={color.textDim}
+          fontSize={font.small}
+          opacity={op}
+        >
+          {detail}
+        </text>
+      )}
+    </>
+  )
+}
+
+// ============================================================================
+// GridCard – card with icon circle, label, description, code hint
+// ============================================================================
+
+export function GridCard({
+  x,
+  y,
+  width,
+  icon,
+  label,
+  desc,
+  codeHint,
+  accentColor,
+}: {
+  x: number
+  y: number
+  width: number
+  icon: string
+  label: string
+  desc?: string
+  codeHint?: string
+  accentColor: string
+}) {
+  const height = codeHint ? 48 : 38
+  return (
+    <>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={radius.md}
+        fill={color.bgDark}
+        stroke={accentColor}
+        strokeWidth={stroke.normal}
+      />
+      <circle
+        cx={x + 22}
+        cy={y + 18}
+        r={10}
+        fill={accentColor}
+        fillOpacity={0.15}
+        stroke={accentColor}
+        strokeWidth={stroke.hairline}
+      />
+      <text
+        x={x + 22}
+        y={y + 22}
+        fill={accentColor}
+        fontSize={font.primary}
+        textAnchor="middle"
+        fontWeight="600"
+      >
+        {icon}
+      </text>
+      <text
+        x={x + 42}
+        y={y + 16}
+        fill={color.textBright}
+        fontSize={font.primary}
+        fontWeight="500"
+      >
+        {label}
+      </text>
+      {desc && (
+        <text x={x + 42} y={y + 28} fill={color.textDim} fontSize={font.small}>
+          {desc}
+        </text>
+      )}
+      {codeHint && (
+        <>
+          <rect
+            x={x + 8}
+            y={y + 34}
+            width={width - 16}
+            height={10}
+            rx={2}
+            fill={color.bgDarker}
+          />
+          <text
+            x={x + width / 2}
+            y={y + 42}
+            fill={accentColor}
+            fontSize={font.small}
+            textAnchor="middle"
+            fontFamily="monospace"
+            opacity={0.7}
+          >
+            {codeHint}
+          </text>
+        </>
+      )}
+    </>
+  )
+}
+
+// ============================================================================
+// ActorNode – circle with icon text and external label
+// ============================================================================
+
+export function ActorNode({
+  cx,
+  cy,
+  r = 12,
+  label,
+  labelPos = 'below',
+  accentColor,
+}: {
+  cx: number
+  cy: number
+  r?: number
+  label: string
+  labelPos?: 'above' | 'below' | 'left' | 'right'
+  accentColor: string
+}) {
+  const labelOffset = r + 8
+  const labelProps = {
+    above: { x: cx, y: cy - labelOffset, textAnchor: 'middle' as const },
+    below: { x: cx, y: cy + labelOffset, textAnchor: 'middle' as const },
+    left: { x: cx - labelOffset, y: cy + font.small / 3, textAnchor: 'end' as const },
+    right: { x: cx + labelOffset, y: cy + font.small / 3, textAnchor: 'start' as const },
+  }[labelPos]
+
+  return (
+    <>
+      <circle
+        cx={cx}
+        cy={cy}
+        r={r}
+        fill={accentColor}
+        fillOpacity={0.15}
+        stroke={accentColor}
+        strokeWidth={stroke.normal}
+      />
+      <text
+        {...labelProps}
+        fill={accentColor}
+        fontSize={font.small}
+        fontWeight="500"
+      >
+        {label}
+      </text>
+    </>
+  )
+}
+
+// ============================================================================
+// KeyValueRow – monospace key-value pair for code displays
+// ============================================================================
+
+export function KeyValueRow({
+  x,
+  y,
+  field,
+  value,
+  fieldColor,
+}: {
+  x: number
+  y: number
+  field: string
+  value: string
+  fieldColor: string
+}) {
+  return (
+    <>
+      <text
+        x={x}
+        y={y}
+        fill={fieldColor}
+        fontSize={font.secondary}
+        fontFamily="monospace"
+      >
+        {field}
+      </text>
+      <text
+        x={x + field.length * 4.2}
+        y={y}
+        fill={color.textDim}
+        fontSize={font.secondary}
+        fontFamily="monospace"
+      >
+        {value}
+      </text>
+    </>
+  )
+}
+
+// ============================================================================
+// WarningIndicator – triangle icon for warnings
+// ============================================================================
+
+export function WarningIndicator({
+  cx,
+  cy,
+  color: fillColor,
+  size = 10,
+}: {
+  cx: number
+  cy: number
+  color: string
+  size?: number
+}) {
+  const half = size / 2
+  const top = cy - half
+  const bottom = cy + half
+  return (
+    <>
+      <path
+        d={`M ${cx} ${top} L ${cx + half} ${bottom} L ${cx - half} ${bottom} Z`}
+        fill="none"
+        stroke={fillColor}
+        strokeWidth={stroke.normal}
+      />
+      <text
+        x={cx}
+        y={bottom - 2}
+        fill={fillColor}
+        fontSize={font.primary}
+        textAnchor="middle"
+        fontWeight="700"
+      >
+        !
+      </text>
+    </>
+  )
+}
+
+// ============================================================================
+// Re-exports for convenience
+// ============================================================================
+
+export { motion }
+export type { Variants }