@opencosmos/ui 1.3.1

package/src/components/data-display/Text.tsx

@@ -0,0 +1,144 @@
+import React from 'react';
+
+export interface TextProps {
+  /**
+   * Text content
+   */
+  children: React.ReactNode;
+
+  /**
+   * Semantic variant determines both color and meaning
+   * @default 'primary'
+   */
+  variant?: 'primary' | 'secondary' | 'muted';
+
+  /**
+   * Text size
+   * @default 'base'
+   */
+  size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl';
+
+  /**
+   * Font weight
+   * @default 'normal'
+   */
+  weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+
+  /**
+   * HTML element to render as
+   * @default 'p'
+   */
+  as?: 'p' | 'span' | 'div' | 'label' | 'time';
+
+  /**
+   * Additional className for customization
+   */
+  className?: string;
+}
+
+/**
+ * Text Component
+ *
+ * Semantic text with automatic token-based styling.
+ * No need to manually apply CSS variable text color classes.
+ *
+ * **What it handles automatically:**
+ * - Theme-aware text colors
+ * - Semantic color variants (primary, secondary, muted)
+ * - Consistent sizing
+ * - Dark mode support
+ *
+ * **Variants:**
+ * - `primary`: Main content text (`--color-text-primary`)
+ * - `secondary`: Supporting text (`--color-text-secondary`)
+ * - `muted`: De-emphasized text (`--color-text-muted`)
+ *
+ * Usage:
+ * ```tsx
+ * // Primary content text
+ * <Text>Main paragraph content</Text>
+ *
+ * // Secondary supporting text
+ * <Text variant="secondary">Helper text or description</Text>
+ *
+ * // Muted text (least emphasis)
+ * <Text variant="muted">Footnote or metadata</Text>
+ *
+ * // Different sizes
+ * <Text size="lg">Large text</Text>
+ * <Text size="sm">Small text</Text>
+ *
+ * // As different element
+ * <Text as="span">Inline text</Text>
+ * <Text as="label">Form label</Text>
+ * ```
+ */
+export const Text: React.FC<TextProps & { ref?: React.Ref<HTMLElement> }> = (
+  {
+    ref,
+    children,
+    variant = 'primary',
+    size = 'base',
+    weight = 'normal',
+    as: Component = 'p',
+    className = ''
+  }: TextProps & {
+    ref?: React.Ref<HTMLElement>;
+  }
+) => {
+  const variantStyles = {
+    primary: 'text-[var(--color-text-primary)]',
+    secondary: 'text-[var(--color-text-secondary)]',
+    muted: 'text-[var(--color-text-muted)]',
+  };
+
+  const variantInlineStyles: Record<string, React.CSSProperties> = {
+    primary: { color: 'var(--color-text-primary, #212121)' },
+    secondary: { color: 'var(--color-text-secondary, #5D5D5D)' },
+    muted: { color: 'var(--color-text-muted, #8891A7)' },
+  };
+
+  const sizeStyles = {
+    xs: 'text-xs',    // 12px
+    sm: 'text-sm',    // 14px
+    base: 'text-base', // 16px
+    lg: 'text-lg',    // 18px
+    xl: 'text-xl',    // 20px
+  };
+
+  const sizeInlineStyles: Record<string, React.CSSProperties> = {
+    xs: { fontSize: '0.75rem', lineHeight: String(1 / 0.75) },
+    sm: { fontSize: '0.875rem', lineHeight: String(1.25 / 0.875) },
+    base: { fontSize: '1rem', lineHeight: '1.5' },
+    lg: { fontSize: '1.125rem', lineHeight: String(1.75 / 1.125) },
+    xl: { fontSize: '1.25rem', lineHeight: String(1.75 / 1.25) },
+  };
+
+  const weightStyles = {
+    normal: 'font-normal',
+    medium: 'font-medium',
+    semibold: 'font-semibold',
+    bold: 'font-bold',
+  };
+
+  const weightInlineStyles: Record<string, React.CSSProperties> = {
+    normal: { fontWeight: 400 },
+    medium: { fontWeight: 500 },
+    semibold: { fontWeight: 600 },
+    bold: { fontWeight: 700 },
+  };
+
+  return React.createElement(
+    Component,
+    {
+      ref,
+      className: `${variantStyles[variant]} ${sizeStyles[size]} ${weightStyles[weight]} ${className}`,
+      style: {
+        ...variantInlineStyles[variant],
+        ...sizeInlineStyles[size],
+        ...weightInlineStyles[weight],
+      },
+    },
+    children
+  );
+};

package/src/components/data-display/Timeline.tsx

@@ -0,0 +1,194 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../../lib/utils"
+
+const timelineVariants = cva("relative", {
+  variants: {
+    orientation: {
+      vertical: "flex flex-col",
+      horizontal: "flex flex-row overflow-x-auto",
+    },
+  },
+  defaultVariants: {
+    orientation: "vertical",
+  },
+})
+
+const timelineItemStatusVariants = cva(
+  "flex items-center justify-center rounded-full border-2 shrink-0",
+  {
+    variants: {
+      status: {
+        pending: "border-border bg-muted text-foreground-secondary",
+        active: "border-primary bg-primary text-primary-foreground",
+        completed: "border-primary bg-primary text-primary-foreground",
+        error: "border-destructive bg-destructive text-destructive-foreground",
+      },
+      size: {
+        sm: "h-6 w-6 [&>svg]:h-3 [&>svg]:w-3",
+        default: "h-8 w-8 [&>svg]:h-4 [&>svg]:w-4",
+        lg: "h-10 w-10 [&>svg]:h-5 [&>svg]:w-5",
+      },
+    },
+    defaultVariants: {
+      status: "pending",
+      size: "default",
+    },
+  }
+)
+
+export interface TimelineProps
+  extends React.HTMLAttributes<HTMLOListElement>,
+    VariantProps<typeof timelineVariants> {}
+
+export interface TimelineItemProps
+  extends React.HTMLAttributes<HTMLLIElement> {
+  /** Event title */
+  title: string
+  /** Event description */
+  description?: string
+  /** Timestamp text */
+  timestamp?: string
+  /** Custom icon for the indicator */
+  icon?: React.ReactNode
+  /** Status of this event */
+  status?: "pending" | "active" | "completed" | "error"
+  /** Whether this is the last item (hides connector) */
+  isLast?: boolean
+  /** Size variant */
+  size?: "sm" | "default" | "lg"
+}
+
+const CheckIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <polyline points="20 6 9 17 4 12" />
+  </svg>
+)
+
+const XIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <line x1="18" y1="6" x2="6" y2="18" />
+    <line x1="6" y1="6" x2="18" y2="18" />
+  </svg>
+)
+
+const CircleIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="8"
+    height="8"
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    aria-hidden="true"
+  >
+    <circle cx="12" cy="12" r="6" />
+  </svg>
+)
+
+function Timeline({
+  className,
+  orientation = "vertical",
+  children,
+  ...props
+}: TimelineProps) {
+  return (
+    <ol
+      data-slot="timeline"
+      className={cn(timelineVariants({ orientation }), className)}
+      {...props}
+    >
+      {children}
+    </ol>
+  )
+}
+
+function TimelineItem({
+  className,
+  title,
+  description,
+  timestamp,
+  icon,
+  status = "pending",
+  isLast = false,
+  size = "default",
+  ...props
+}: TimelineItemProps) {
+  const defaultIcon = (() => {
+    switch (status) {
+      case "completed":
+        return <CheckIcon />
+      case "error":
+        return <XIcon />
+      case "active":
+        return <CircleIcon />
+      default:
+        return <CircleIcon />
+    }
+  })()
+
+  return (
+    <li
+      data-slot="timeline-item"
+      className={cn("relative flex gap-4", className)}
+      aria-current={status === "active" ? "step" : undefined}
+      {...props}
+    >
+      {/* Indicator column */}
+      <div className="flex flex-col items-center">
+        <div
+          data-slot="timeline-icon"
+          className={cn(timelineItemStatusVariants({ status, size }))}
+          aria-hidden="true"
+        >
+          {icon ?? defaultIcon}
+        </div>
+        {!isLast && (
+          <div
+            data-slot="timeline-connector"
+            className={cn(
+              "w-0.5 grow bg-border",
+              size === "sm" ? "min-h-4" : size === "lg" ? "min-h-8" : "min-h-6"
+            )}
+          />
+        )}
+      </div>
+
+      {/* Content column */}
+      <div className={cn("pb-6", isLast && "pb-0")}>
+        <div className="flex items-center gap-2">
+          <p className="font-medium text-foreground leading-none">{title}</p>
+          {timestamp && (
+            <time className="text-xs text-foreground-secondary">{timestamp}</time>
+          )}
+        </div>
+        {description && (
+          <p className="mt-1 text-sm text-foreground-secondary">{description}</p>
+        )}
+      </div>
+    </li>
+  )
+}
+
+export { Timeline, TimelineItem, timelineVariants }

package/src/components/data-display/TreeView.tsx

@@ -0,0 +1,226 @@
+'use client'
+
+import * as React from "react"
+import { cva } from "class-variance-authority"
+import { cn } from "../../lib/utils"
+
+export interface TreeNode {
+  /** Unique identifier */
+  id: string
+  /** Display label */
+  label: string
+  /** Optional icon */
+  icon?: React.ReactNode
+  /** Child nodes */
+  children?: TreeNode[]
+  /** Whether the node is disabled */
+  disabled?: boolean
+}
+
+export interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Tree data structure */
+  nodes: TreeNode[]
+  /** Expanded node IDs (controlled) */
+  expanded?: string[]
+  /** Default expanded node IDs (uncontrolled) */
+  defaultExpanded?: string[]
+  /** Called when expanded state changes */
+  onExpandChange?: (expanded: string[]) => void
+  /** Currently selected node ID */
+  selected?: string
+  /** Called when selection changes */
+  onSelectChange?: (nodeId: string) => void
+}
+
+const treeNodeVariants = cva(
+  "flex items-center gap-2 py-1 px-2 rounded-md text-sm cursor-pointer select-none transition-colors",
+  {
+    variants: {
+      state: {
+        idle: "text-foreground hover:bg-muted",
+        selected: "text-foreground bg-primary/10 font-medium",
+        disabled: "text-foreground-secondary cursor-not-allowed opacity-60",
+      },
+    },
+    defaultVariants: {
+      state: "idle",
+    },
+  }
+)
+
+const ChevronIcon = ({ expanded }: { expanded: boolean }) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+    className={cn(
+      "shrink-0 transition-transform",
+      expanded ? "rotate-90" : "rotate-0"
+    )}
+  >
+    <polyline points="9 18 15 12 9 6" />
+  </svg>
+)
+
+interface TreeViewContextValue {
+  expanded: Set<string>
+  selected: string | null
+  toggleExpand: (nodeId: string) => void
+  selectNode: (nodeId: string) => void
+}
+
+const TreeViewContext = React.createContext<TreeViewContextValue>({
+  expanded: new Set(),
+  selected: null,
+  toggleExpand: () => {},
+  selectNode: () => {},
+})
+
+function TreeView({
+  className,
+  nodes,
+  expanded: controlledExpanded,
+  defaultExpanded = [],
+  onExpandChange,
+  selected: controlledSelected,
+  onSelectChange,
+  ...props
+}: TreeViewProps) {
+  const [internalExpanded, setInternalExpanded] = React.useState<Set<string>>(
+    new Set(defaultExpanded)
+  )
+  const [internalSelected, setInternalSelected] = React.useState<string | null>(null)
+
+  const isControlled = controlledExpanded !== undefined
+  const expanded = isControlled ? new Set(controlledExpanded) : internalExpanded
+  const selected = controlledSelected ?? internalSelected
+
+  const toggleExpand = React.useCallback(
+    (nodeId: string) => {
+      const newExpanded = new Set(expanded)
+      if (newExpanded.has(nodeId)) {
+        newExpanded.delete(nodeId)
+      } else {
+        newExpanded.add(nodeId)
+      }
+
+      if (!isControlled) {
+        setInternalExpanded(newExpanded)
+      }
+      onExpandChange?.(Array.from(newExpanded))
+    },
+    [expanded, isControlled, onExpandChange]
+  )
+
+  const selectNode = React.useCallback(
+    (nodeId: string) => {
+      if (controlledSelected === undefined) {
+        setInternalSelected(nodeId)
+      }
+      onSelectChange?.(nodeId)
+    },
+    [controlledSelected, onSelectChange]
+  )
+
+  return (
+    <TreeViewContext.Provider value={{ expanded, selected, toggleExpand, selectNode }}>
+      <div
+        data-slot="tree-view"
+        role="tree"
+        className={cn("space-y-0.5", className)}
+        {...props}
+      >
+        {nodes.map((node) => (
+          <TreeViewNodeComponent key={node.id} node={node} level={1} />
+        ))}
+      </div>
+    </TreeViewContext.Provider>
+  )
+}
+
+interface TreeViewNodeComponentProps {
+  node: TreeNode
+  level: number
+}
+
+function TreeViewNodeComponent({ node, level }: TreeViewNodeComponentProps) {
+  const { expanded, selected, toggleExpand, selectNode } = React.useContext(TreeViewContext)
+
+  const hasChildren = node.children && node.children.length > 0
+  const isExpanded = expanded.has(node.id)
+  const isSelected = selected === node.id
+
+  const state = node.disabled ? "disabled" : isSelected ? "selected" : "idle"
+
+  const handleClick = () => {
+    if (node.disabled) return
+    selectNode(node.id)
+    if (hasChildren) {
+      toggleExpand(node.id)
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (node.disabled) return
+
+    switch (e.key) {
+      case "Enter":
+      case " ":
+        e.preventDefault()
+        handleClick()
+        break
+      case "ArrowRight":
+        if (hasChildren && !isExpanded) {
+          e.preventDefault()
+          toggleExpand(node.id)
+        }
+        break
+      case "ArrowLeft":
+        if (hasChildren && isExpanded) {
+          e.preventDefault()
+          toggleExpand(node.id)
+        }
+        break
+    }
+  }
+
+  return (
+    <div data-slot="tree-view-node" role="treeitem" aria-expanded={hasChildren ? isExpanded : undefined} aria-level={level} aria-selected={isSelected}>
+      <div
+        className={cn(treeNodeVariants({ state }))}
+        style={{ paddingLeft: `${(level - 1) * 20 + 8}px` }}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        tabIndex={node.disabled ? -1 : 0}
+      >
+        {hasChildren ? (
+          <ChevronIcon expanded={isExpanded} />
+        ) : (
+          <span className="w-3.5 shrink-0" aria-hidden="true" />
+        )}
+        {node.icon && (
+          <span className="shrink-0 text-foreground-secondary" aria-hidden="true">
+            {node.icon}
+          </span>
+        )}
+        <span className="truncate">{node.label}</span>
+      </div>
+      {hasChildren && isExpanded && (
+        <div role="group">
+          {node.children!.map((child) => (
+            <TreeViewNodeComponent key={child.id} node={child} level={level + 1} />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export { TreeView, treeNodeVariants }

package/src/components/data-display/Typewriter.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { motion } from 'framer-motion';
+import { useEffect, useState } from 'react';
+import { cn } from '../../lib/utils';
+import { useMotionPreference } from '../../hooks/useMotionPreference';
+
+export interface TypewriterProps {
+    text: string | string[];
+    speed?: number;
+    delay?: number;
+    loop?: boolean;
+    loopDelay?: number;
+    cursor?: string;
+    showCursor?: boolean;
+    className?: string;
+    as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div';
+}
+
+export function Typewriter({
+    text,
+    speed = 0.05,
+    delay = 0,
+    loop = false,
+    loopDelay = 2,
+    cursor = '|',
+    showCursor = true,
+    className,
+    as: Component = 'span',
+}: TypewriterProps) {
+    const { shouldAnimate, scale } = useMotionPreference();
+    const [displayedText, setDisplayedText] = useState('');
+
+    // Flatten text to array for easier handling
+    const textArray = Array.isArray(text) ? text : [text];
+
+    useEffect(() => {
+        // If reduced motion, show full text immediately
+        if (!shouldAnimate) {
+            setDisplayedText(textArray[0]);
+            return;
+        }
+
+        let timeoutId: ReturnType<typeof setTimeout>;
+        let isCancelled = false;
+
+        // State pointers
+        let stringIndex = 0;
+        let charIndex = 0;
+        let isDeleting = false;
+
+        const type = () => {
+            if (isCancelled) return;
+
+            const currentString = textArray[stringIndex];
+            const currentSpeed = (isDeleting ? speed / 2 : speed) * (scale > 0 ? (5 / scale) : 1) * 1000;
+
+            if (isDeleting) {
+                // DELETING
+                if (charIndex > 0) {
+                    setDisplayedText(currentString.substring(0, charIndex - 1));
+                    charIndex--;
+                    timeoutId = setTimeout(type, currentSpeed);
+                } else {
+                    // Start typing next string
+                    isDeleting = false;
+                    stringIndex = (stringIndex + 1) % textArray.length;
+                    timeoutId = setTimeout(type, currentSpeed);
+                }
+            } else {
+                // TYPING
+                if (charIndex < currentString.length) {
+                    setDisplayedText(currentString.substring(0, charIndex + 1));
+                    charIndex++;
+                    timeoutId = setTimeout(type, currentSpeed);
+                } else {
+                    // FINISHED TYPING STRING
+                    if (loop) {
+                        isDeleting = true;
+                        timeoutId = setTimeout(type, loopDelay * 1000);
+                    } else if (stringIndex < textArray.length - 1) {
+                        // If we have more strings to type in sequence (and not just looping one)
+                        // Note: The original logic treated array as "loop through these options". 
+                        // To match previous behavior: array = specific sequence to loop? 
+                        // Usually typewriters with arrays toggle between them.
+                        isDeleting = true;
+                        timeoutId = setTimeout(type, loopDelay * 1000);
+                    }
+                }
+            }
+        };
+
+        // Initial Start Delay
+        timeoutId = setTimeout(() => {
+            type();
+        }, delay * 1000);
+
+        return () => {
+            isCancelled = true;
+            clearTimeout(timeoutId);
+        };
+    }, [text, speed, delay, loop, loopDelay, shouldAnimate, scale]); // Re-run effect if props change
+
+    return (
+        <Component className={cn("inline", className)}>
+            <span>{displayedText}</span>
+            {showCursor && (
+                <motion.span
+                    initial={{ opacity: 0 }}
+                    animate={{ opacity: 1 }}
+                    transition={{ duration: 0.5, repeat: Infinity, repeatType: "reverse" }}
+                    className="ml-0.5 text-[var(--color-primary)] font-light"
+                >
+                    {cursor}
+                </motion.span>
+            )}
+        </Component>
+    );
+}