@opencosmos/ui 1.3.1

package/src/components/data-display/Card.test.tsx

@@ -0,0 +1,92 @@
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { createRef } from 'react'
+import { Card, CardHeader, CardTitle, CardContent, CardFooter } from './Card'
+
+describe('Card', () => {
+  it('renders with children', () => {
+    render(<Card>Card content</Card>)
+    expect(screen.getByText('Card content')).toBeInTheDocument()
+  })
+
+  it('renders CardHeader, CardTitle, CardContent, and CardFooter', () => {
+    render(
+      <Card>
+        <CardHeader>
+          <CardTitle>My Title</CardTitle>
+        </CardHeader>
+        <CardContent>Body text</CardContent>
+        <CardFooter>Footer text</CardFooter>
+      </Card>
+    )
+
+    expect(screen.getByText('My Title')).toBeInTheDocument()
+    expect(screen.getByText('Body text')).toBeInTheDocument()
+    expect(screen.getByText('Footer text')).toBeInTheDocument()
+  })
+
+  it('renders CardTitle as an h3 element', () => {
+    render(<CardTitle>Heading</CardTitle>)
+    const heading = screen.getByRole('heading', { level: 3 })
+    expect(heading).toBeInTheDocument()
+    expect(heading).toHaveTextContent('Heading')
+  })
+
+  it('applies default variant classes', () => {
+    const { container } = render(<Card>Default</Card>)
+    const card = container.firstChild as HTMLElement
+    expect(card).toHaveClass('bg-surface')
+    expect(card).toHaveClass('border-border')
+  })
+
+  it('applies glass variant classes', () => {
+    const { container } = render(<Card variant="glass">Glass</Card>)
+    const card = container.firstChild as HTMLElement
+    expect(card).toHaveClass('bg-glass')
+    expect(card).toHaveClass('backdrop-blur-md')
+  })
+
+  it('applies outline variant classes', () => {
+    const { container } = render(<Card variant="outline">Outline</Card>)
+    const card = container.firstChild as HTMLElement
+    expect(card).toHaveClass('bg-transparent')
+    expect(card).toHaveClass('border-border')
+  })
+
+  it('applies hover effect classes when hoverEffect is true', () => {
+    const { container } = render(<Card hoverEffect>Hover</Card>)
+    const card = container.firstChild as HTMLElement
+    expect(card).toHaveClass('hover:shadow-lg')
+    expect(card).toHaveClass('hover:-translate-y-1')
+  })
+
+  it('forwards ref', () => {
+    const ref = createRef<HTMLDivElement>()
+    render(<Card ref={ref}>Ref Card</Card>)
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+
+  it('applies custom className', () => {
+    const { container } = render(<Card className="my-custom">Custom</Card>)
+    const card = container.firstChild as HTMLElement
+    expect(card).toHaveClass('my-custom')
+  })
+
+  it('forwards ref on CardHeader', () => {
+    const ref = createRef<HTMLDivElement>()
+    render(<CardHeader ref={ref}>Header</CardHeader>)
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+
+  it('forwards ref on CardContent', () => {
+    const ref = createRef<HTMLDivElement>()
+    render(<CardContent ref={ref}>Content</CardContent>)
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+
+  it('forwards ref on CardFooter', () => {
+    const ref = createRef<HTMLDivElement>()
+    render(<CardFooter ref={ref}>Footer</CardFooter>)
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+})

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

@@ -0,0 +1,115 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../../lib/utils"
+
+const cardVariants = cva(
+    "rounded-2xl border bg-surface text-foreground shadow-xs",
+    {
+        variants: {
+            hoverEffect: {
+                true: "transition-all duration-300 hover:shadow-lg hover:-translate-y-1 hover:border-primary",
+                false: "",
+            },
+            variant: {
+                default: "bg-surface border-border",
+                glass: "bg-glass border-glass-border backdrop-blur-md",
+                outline: "bg-transparent border-border",
+            }
+        },
+        defaultVariants: {
+            variant: "default",
+            hoverEffect: false,
+        },
+    }
+)
+
+export interface CardProps
+    extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof cardVariants> { }
+
+const Card = (
+    {
+        ref,
+        className,
+        variant,
+        hoverEffect,
+        ...props
+    }: CardProps & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn(cardVariants({ variant, hoverEffect, className }))}
+    {...props}
+/>)
+
+const CardHeader = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn("flex flex-col space-y-1.5 p-6", className)}
+    {...props}
+/>)
+
+const CardTitle = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLHeadingElement> & {
+        ref?: React.Ref<HTMLParagraphElement>;
+    }
+) => (<h3
+    ref={ref}
+    className={cn(
+        "text-2xl font-semibold leading-none tracking-tight font-heading",
+        className
+    )}
+    {...props}
+/>)
+
+const CardDescription = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLParagraphElement> & {
+        ref?: React.Ref<HTMLParagraphElement>;
+    }
+) => (<p
+    ref={ref}
+    className={cn("text-sm text-foreground-secondary", className)}
+    {...props}
+/>)
+
+const CardContent = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div ref={ref} className={cn("p-6 pt-0", className)} {...props} />)
+
+const CardFooter = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+/>)
+
+export { Card, cardVariants, CardHeader, CardFooter, CardTitle, CardDescription, CardContent }

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

@@ -0,0 +1,210 @@
+'use client';
+
+import { ReactNode, useState, useMemo } from 'react';
+import type { SyntaxType } from '../../lib/syntax-parser';
+import { parseCode } from '../../lib/syntax-parser';
+
+export interface CodeProps {
+  /** The code content to display */
+  children: ReactNode;
+  /** Optional syntax highlighting type */
+  syntax?: SyntaxType;
+  /** Whether to render as inline code (default) or block */
+  inline?: boolean;
+  /** Show copy button for block code (default: true) */
+  showCopy?: boolean;
+  /** Additional className for custom styling */
+  className?: string;
+}
+
+/**
+ * Code Atom
+ *
+ * A semantic code wrapper with automatic syntax highlighting and enhanced visual styling.
+ * Features distinct treatments for inline vs block code, with copy-on-hover for blocks.
+ *
+ * **Visual Design:**
+ * - Inline: Pale amber background (#FEF3E7 light / #252525 dark) with subtle border
+ * - Block: Cool gray background (#F8F9FA light / #1E1E1E dark) with generous padding
+ * - Copy button appears on hover for block code with tooltip feedback
+ * - Accessible contrast ratios (WCAG AA 4.5:1)
+ *
+ * @example
+ * ```tsx
+ * // Inline code - perfect for text snippets
+ * <Code>example</Code>
+ * <Code syntax="keyword">const</Code>
+ * <Code syntax="function">useState()</Code>
+ *
+ * // Block code - for larger code examples
+ * <Code inline={false}>const example = "value";</Code>
+ * <Code inline={false} syntax="keyword" showCopy={false}>
+ *   const greeting = "Hello World";
+ * </Code>
+ * ```
+ */
+export function Code({
+  children,
+  syntax = 'plain',
+  inline = true,
+  showCopy = true,
+  className = '',
+}: CodeProps) {
+  const [copied, setCopied] = useState(false);
+  const [showTooltip, setShowTooltip] = useState(false);
+
+  // Auto-parse code for block syntax highlighting
+  const tokens = useMemo(() => {
+    if (!inline && typeof children === 'string') {
+      return parseCode(children);
+    }
+    return null;
+  }, [children, inline]);
+
+  // Handle copy to clipboard for block code
+  const handleCopy = async () => {
+    const text = typeof children === 'string' ? children : String(children);
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error('Failed to copy code:', err);
+    }
+  };
+
+  // Inline code - subtle, integrated into text
+  if (inline) {
+    return (
+      <code
+        className={`font-mono text-[0.875em] px-[0.375rem] py-[0.125rem] rounded border ${className}`}
+        style={{
+          backgroundColor: 'var(--code-inline-bg)',
+          borderColor: 'var(--code-border)',
+          color: `var(--syntax-${syntax})`,
+        }}
+      >
+        {children}
+      </code>
+    );
+  }
+
+  // Block code - prominent with copy button on hover
+  return (
+    <div className={`relative group ${className}`}>
+      <pre
+        className="font-mono text-sm p-6 rounded-lg border overflow-x-auto"
+        style={{
+          backgroundColor: 'var(--code-block-bg)',
+          borderColor: 'var(--code-border)',
+        }}
+      >
+        <code>
+          {tokens ? (
+            // Automatic syntax highlighting with parsed tokens
+            tokens.map((token, index) => (
+              <span
+                key={index}
+                style={{
+                  color: `var(--syntax-${token.type})`,
+                }}
+              >
+                {token.text}
+              </span>
+            ))
+          ) : (
+            // Fallback to single color for non-string children
+            <span
+              style={{
+                color: `var(--syntax-${syntax})`,
+              }}
+            >
+              {children}
+            </span>
+          )}
+        </code>
+      </pre>
+
+      {/* Copy Button - appears on hover for block code */}
+      {showCopy && (
+        <div className="absolute top-3 right-3 opacity-0 group-hover:opacity-100 transition-opacity duration-200">
+          <div className="relative">
+            <button
+              onClick={handleCopy}
+              onMouseEnter={() => setShowTooltip(true)}
+              onMouseLeave={() => setShowTooltip(false)}
+              className="flex items-center gap-2 px-3 py-2 text-xs rounded-md transition-all duration-200 border"
+              style={{
+                backgroundColor: 'var(--color-surface)',
+                borderColor: 'var(--color-border)',
+                color: 'var(--color-text-primary)',
+              }}
+              aria-label={copied ? 'Copied!' : 'Copy code'}
+            >
+              {copied ? (
+                <>
+                  <svg
+                    className="w-3.5 h-3.5"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                    aria-hidden="true"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M5 13l4 4L19 7"
+                    />
+                  </svg>
+                  <span>Copied!</span>
+                </>
+              ) : (
+                <>
+                  <svg
+                    className="w-3.5 h-3.5"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                    aria-hidden="true"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2 2v8a2 2 0 002 2z"
+                    />
+                  </svg>
+                  <span>Copy</span>
+                </>
+              )}
+            </button>
+
+            {/* Tooltip */}
+            {showTooltip && !copied && (
+              <div
+                role="tooltip"
+                className="absolute bottom-full right-0 mb-2 px-2 py-1 text-xs rounded whitespace-nowrap pointer-events-none"
+                style={{
+                  backgroundColor: 'var(--color-text-primary)',
+                  color: 'var(--color-background)',
+                }}
+              >
+                Copy code
+                {/* Arrow */}
+                <div
+                  className="absolute top-full right-4 w-0 h-0"
+                  style={{
+                    borderLeft: '4px solid transparent',
+                    borderRight: '4px solid transparent',
+                    borderTop: '4px solid var(--color-text-primary)',
+                  }}
+                />
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,238 @@
+'use client';
+
+import { useState, useMemo } from 'react';
+import { useTheme } from '../../hooks/useTheme';
+import { syntaxColors } from '@thesage/tokens';
+import { parseCode, type SyntaxToken } from '../../lib/syntax-parser';
+
+export interface CollapsibleCodeBlockProps {
+  /** Unique identifier for the code block (required for animation) */
+  id: string;
+  /** Title/label for the code block */
+  title?: string;
+  /** Code to display - can be string or array of syntax tokens */
+  code: string | SyntaxToken[];
+  /** Language identifier (e.g., 'typescript', 'css', 'html') */
+  language?: string;
+  /** Initial collapsed state */
+  defaultCollapsed?: boolean;
+  /** Show copy button */
+  showCopy?: boolean;
+  /** Custom className for container */
+  className?: string;
+}
+
+/**
+ * CollapsibleCodeBlock Organism
+ *
+ * A reusable code block component with:
+ * - Smooth spring animation for expand/collapse
+ * - Syntax highlighting with light/dark theme support
+ * - Copy to clipboard functionality
+ * - Preview mode showing first 3 lines
+ * - Gradient overlay in collapsed state
+ *
+ * @example
+ * ```tsx
+ * <CollapsibleCodeBlock
+ *   id="example-code"
+ *   title="TypeScript Example"
+ *   code={[
+ *     { text: 'const', type: 'keyword' },
+ *     { text: ' example ', type: 'plain' },
+ *     { text: '=', type: 'operator' },
+ *     { text: ' "Hello"', type: 'string' },
+ *   ]}
+ *   language="typescript"
+ * />
+ * ```
+ */
+export function CollapsibleCodeBlock({
+  id,
+  title,
+  code,
+  language,
+  defaultCollapsed = true,
+  showCopy = true,
+  className = '',
+}: CollapsibleCodeBlockProps) {
+  const [isCollapsed, setIsCollapsed] = useState(defaultCollapsed);
+  const [copySuccess, setCopySuccess] = useState(false);
+  const { mode } = useTheme();
+
+  // Get the appropriate color scheme based on current theme mode
+  const colors = mode === 'dark' ? syntaxColors.dark : syntaxColors.light;
+
+  // Auto-tokenize string code for syntax highlighting
+  const tokens = useMemo(() => {
+    return typeof code === 'string' ? parseCode(code) : code;
+  }, [code]);
+
+  // Convert tokens to string for copying
+  const codeString = tokens.map(token => token.text).join('');
+
+  // Handle copy to clipboard
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(codeString);
+      setCopySuccess(true);
+      setTimeout(() => setCopySuccess(false), 2000);
+    } catch (err) {
+      console.error('Failed to copy:', err);
+    }
+  };
+
+  // Handle toggle animation
+  const handleToggle = () => {
+    const preview = document.getElementById(`${id}-preview`);
+    const codeBlock = document.getElementById(`${id}-code`);
+    const icon = document.getElementById(`${id}-icon`);
+
+    if (preview && codeBlock && icon) {
+      const isHidden = codeBlock.classList.contains('hidden');
+
+      if (isHidden) {
+        // Opening: start at preview height, expand to full
+        preview.classList.add('hidden');
+        codeBlock.classList.remove('hidden');
+        codeBlock.style.maxHeight = '6.6rem'; // Match preview height (3 lines)
+        void codeBlock.offsetHeight; // Force reflow
+        codeBlock.style.maxHeight = codeBlock.scrollHeight + 'px';
+      } else {
+        // Closing: collapse to preview height, then swap
+        codeBlock.style.maxHeight = '6.6rem';
+        setTimeout(() => {
+          codeBlock.classList.add('hidden');
+          preview.classList.remove('hidden');
+        }, 500);
+      }
+
+      icon.classList.toggle('rotate-90');
+      setIsCollapsed(!isCollapsed);
+    }
+  };
+
+  // Render syntax-highlighted code with inline colors from tokens
+  const renderCode = (tokensToRender: SyntaxToken[]) => {
+    return tokensToRender.map((token, index) => {
+      // Get color from syntax tokens based on token type
+      const color = token.type ? colors[token.type] : colors.plain;
+
+      return (
+        <span
+          key={index}
+          style={{ color }}
+        >
+          {token.text}
+        </span>
+      );
+    });
+  };
+
+  // Get preview tokens (first ~3 lines worth)
+  const previewTokens = useMemo(() => {
+    // Count characters to approximate 3 lines (~120 chars)
+    let charCount = 0;
+    const maxChars = 120;
+    const preview: SyntaxToken[] = [];
+
+    for (const token of tokens) {
+      if (charCount >= maxChars) break;
+      preview.push(token);
+      charCount += token.text.length;
+    }
+
+    return preview;
+  }, [tokens]);
+
+  return (
+    <div className={`w-full min-w-0 ${className}`}>
+      {/* Title */}
+      {title && (
+        <h3 className="text-lg font-semibold mb-3 text-[var(--color-text-primary)]">
+          {title}
+        </h3>
+      )}
+
+      {/* Action Buttons */}
+      <div className="flex gap-2 mb-4">
+        <button
+          onClick={handleToggle}
+          className="flex items-center gap-2 px-3 py-2 text-xs text-[var(--color-text-primary)] bg-[var(--color-surface)] hover:bg-[var(--color-primary)] hover:text-[var(--color-primary-foreground)] hover:scale-105 hover:shadow-lg active:scale-95 border border-[var(--color-border)] rounded-md transition-all duration-200"
+          aria-expanded={!isCollapsed}
+          aria-controls={`${id}-code`}
+          aria-label={isCollapsed ? 'Show code' : 'Hide code'}
+        >
+          <svg
+            id={`${id}-icon`}
+            className="w-3 h-3 transition-transform duration-200"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M9 5l7 7-7 7"
+            />
+          </svg>
+          {isCollapsed ? 'Show Code' : 'Hide Code'}
+        </button>
+
+        {showCopy && (
+          <button
+            onClick={handleCopy}
+            aria-label={copySuccess ? 'Copied to clipboard' : 'Copy code to clipboard'}
+            className="flex items-center gap-2 px-3 py-2 text-xs text-[var(--color-text-primary)] bg-[var(--color-surface)] hover:bg-[var(--color-primary)] hover:text-[var(--color-primary-foreground)] hover:scale-105 hover:shadow-lg active:scale-95 border border-[var(--color-border)] rounded-md transition-all duration-200"
+          >
+            {copySuccess ? (
+              <>
+                <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+                </svg>
+                Copied!
+              </>
+            ) : (
+              <>
+                <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012-2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+                </svg>
+                Copy
+              </>
+            )}
+          </button>
+        )}
+      </div>
+
+      {/* Code Preview (visible when collapsed) */}
+      <div
+        id={`${id}-preview`}
+        className={`bg-[var(--color-background)] p-4 rounded border border-[var(--color-border)] overflow-hidden mb-4 w-full max-w-full ${isCollapsed ? '' : 'hidden'}`}
+        style={{ height: '6.6rem' }}
+      >
+        <div className="relative w-full max-w-full min-w-0">
+          <pre className="text-sm font-mono overflow-x-auto w-full max-w-full whitespace-pre">
+            <code>{renderCode(previewTokens)}</code>
+          </pre>
+          <div className="absolute inset-x-0 bottom-0 h-6 bg-gradient-to-t from-[var(--color-background)] to-transparent pointer-events-none" />
+        </div>
+      </div>
+
+      {/* Full Code (hidden by default) */}
+      <div
+        id={`${id}-code`}
+        className={`transition-all duration-500 ease-out overflow-hidden bg-[var(--color-background)] p-4 rounded border border-[var(--color-border)] w-full max-w-full ${isCollapsed ? 'hidden' : ''}`}
+        style={{
+          maxHeight: isCollapsed ? '0px' : 'none',
+          transition: 'max-height 0.5s cubic-bezier(0.34, 1.56, 0.64, 1)',
+        }}
+      >
+        <pre className="text-sm font-mono overflow-x-auto w-full max-w-full whitespace-pre">
+          <code>{renderCode(tokens)}</code>
+        </pre>
+      </div>
+    </div>
+  );
+}