@openspecui/web 0.9.0

package/src/components/markdown-viewer.tsx

@@ -0,0 +1,415 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { MarkdownContent } from './markdown-content'
+import { generateTimelineScope, Toc, type TocItem } from './toc'
+import { slugify, TocCollector, TocLevelProvider, TocProvider, useTocContext } from './toc-context'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
+
+interface HeadingProps {
+  id?: string
+  children?: ReactNode
+  className?: string
+}
+
+type HeadingComponent = (props: HeadingProps) => ReactNode
+
+interface SectionProps {
+  children?: ReactNode
+  className?: string
+}
+
+type SectionComponent = (props: SectionProps) => ReactNode
+
+export interface BuilderComponents {
+  H1: HeadingComponent
+  H2: HeadingComponent
+  H3: HeadingComponent
+  H4: HeadingComponent
+  H5: HeadingComponent
+  H6: HeadingComponent
+  /** Section 会自动将内部内容的 ToC 层级 +1 */
+  Section: SectionComponent
+}
+
+export type MarkdownBuilderFn = (components: BuilderComponents) => ReactNode
+
+export interface MarkdownViewerProps {
+  /** Markdown 内容：字符串或 Builder 函数 */
+  markdown: string | MarkdownBuilderFn
+  className?: string
+  /** 渲染和 ToC 建立完成后回调（用于外层占位控制） */
+  onReady?: () => void
+}
+
+// ============================================================================
+// MarkdownViewer - 主组件
+// ============================================================================
+
+/**
+ * 统一的 Markdown 文档查看器，支持 ToC 侧边栏和嵌套。
+ *
+ * 两种使用模式：
+ * 1. 字符串模式：`<MarkdownViewer markdown="# Hello" />`
+ * 2. Builder 模式：`<MarkdownViewer markdown={({ H1, Section }) => <H1>Hello</H1>} />`
+ *
+ * 嵌套时自动检测父级 Context，只渲染内容不显示 ToC sidebar。
+ */
+export function MarkdownViewer({ markdown, className = '', onReady }: MarkdownViewerProps) {
+  const parentCtx = useTocContext()
+  const isNested = !!parentCtx
+
+  if (isNested) {
+    // 嵌套模式：只渲染内容，向父级贡献 ToC items
+    return <NestedMarkdownViewer markdown={markdown} className={className} />
+  }
+
+  // 顶层模式：渲染完整布局（content + ToC sidebar）
+  return <RootMarkdownViewer markdown={markdown} className={className} onReady={onReady} />
+}
+
+// ============================================================================
+// RootMarkdownViewer - 顶层模式
+// ============================================================================
+
+function RootMarkdownViewer({ markdown, className, onReady }: MarkdownViewerProps) {
+  const [tocItems, setTocItems] = useState<TocItem[]>([])
+  const collectorRef = useRef<TocCollector>(null!)
+  const readyCalledRef = useRef(false)
+
+  // 每次渲染前重置 collector
+  collectorRef.current = new TocCollector()
+  const collector = collectorRef.current
+
+  // 渲染后（首帧前）同步更新 tocItems，避免移动端 ToC 迟到导致的布局抖动
+  useLayoutEffect(() => {
+    const newItems = collectorRef.current.getItems()
+    setTocItems((prev) => {
+      if (arraysEqual(prev, newItems)) return prev
+      return newItems
+    })
+  })
+
+  // 通知外层：内容与 ToC 已经挂载（首个 effect 后触发一次）
+  useEffect(() => {
+    if (readyCalledRef.current) return
+    readyCalledRef.current = true
+    onReady?.()
+  }, [onReady, tocItems])
+
+  const timelineScope = useMemo(() => generateTimelineScope(tocItems), [tocItems])
+
+  // 渲染内容（在 TocProvider 内部，这样嵌套的 MarkdownViewer 能获取 Context）
+  const content =
+    typeof markdown === 'string' ? (
+      <StringMarkdownContent markdown={markdown} collector={collector} levelOffset={0} />
+    ) : (
+      <BuilderMarkdownContent builder={markdown} collector={collector} levelOffset={0} />
+    )
+
+  return (
+    <TocProvider collector={collector} levelOffset={0} isRoot>
+      <div className={`@container-[size] h-full ${className}`}>
+        <style>{viewerStyles}</style>
+        <MarkdownContainer className="viewer-layout gap-6" timelineScope={timelineScope}>
+          <Toc items={tocItems} className="viewer-toc" />
+          <div className="viewer-content min-w-0">{content}</div>
+        </MarkdownContainer>
+      </div>
+    </TocProvider>
+  )
+}
+
+// ============================================================================
+// NestedMarkdownViewer - 嵌套模式
+// ============================================================================
+
+function NestedMarkdownViewer({ markdown, className }: MarkdownViewerProps) {
+  const ctx = useTocContext()!
+  const { collector, levelOffset } = ctx
+
+  // 嵌套模式：使用父级的 collector，但应用当前的 levelOffset
+  return typeof markdown === 'string' ? (
+    <StringMarkdownContent
+      markdown={markdown}
+      className={className}
+      collector={collector}
+      levelOffset={levelOffset}
+    />
+  ) : (
+    <BuilderMarkdownContent
+      builder={markdown}
+      className={className}
+      collector={collector}
+      levelOffset={levelOffset}
+    />
+  )
+}
+
+// ============================================================================
+// StringMarkdownContent - 字符串模式内容
+// ============================================================================
+
+function StringMarkdownContent({
+  markdown,
+  collector,
+  levelOffset,
+  className,
+}: {
+  markdown: string
+  collector: TocCollector
+  levelOffset: number
+  className?: string
+}) {
+  // 为 markdown 中的标题创建自定义组件
+  const components = useMemo(() => {
+    const slugCount = new Map<string, number>()
+
+    const createHeading = (level: HeadingLevel) => {
+      return function Heading({ children }: { children?: ReactNode }) {
+        const text = extractTextFromChildren(children)
+        const baseSlug = slugify(text) || 'heading'
+
+        // 处理重复 id
+        const count = slugCount.get(baseSlug) ?? 0
+        slugCount.set(baseSlug, count + 1)
+        const id = count > 0 ? `${baseSlug}-${count + 1}` : baseSlug
+
+        // 应用层级偏移
+        const adjustedLevel = Math.min(level + levelOffset, 6) as HeadingLevel
+        const { index } = collector.add(text, adjustedLevel, id)
+
+        return (
+          <HeadingElement level={adjustedLevel} id={id} index={index}>
+            {children}
+          </HeadingElement>
+        )
+      }
+    }
+
+    return {
+      h1: createHeading(1),
+      h2: createHeading(2),
+      h3: createHeading(3),
+      h4: createHeading(4),
+      h5: createHeading(5),
+      h6: createHeading(6),
+    }
+  }, [collector, levelOffset])
+
+  return (
+    <MarkdownContent className={className} components={components}>
+      {markdown}
+    </MarkdownContent>
+  )
+}
+
+// ============================================================================
+// BuilderMarkdownContent - Builder 模式内容
+// ============================================================================
+
+function BuilderMarkdownContent({
+  builder,
+  collector,
+  levelOffset,
+  className,
+}: {
+  builder: MarkdownBuilderFn
+  collector: TocCollector
+  levelOffset: number
+  className?: string
+}) {
+  // 创建 Builder 组件
+  const components = useMemo<BuilderComponents>(() => {
+    const slugCount = new Map<string, number>()
+
+    const createHeading = (level: HeadingLevel): HeadingComponent => {
+      return function Heading({ id: fixedId, className, children }: HeadingProps) {
+        // 从 context 实时获取 levelOffset，支持 Section 嵌套
+        const ctx = useTocContext()
+        const currentLevelOffset = ctx?.levelOffset ?? levelOffset
+
+        const text = extractTextFromChildren(children)
+        const baseSlug = fixedId ?? (slugify(text) || 'heading')
+
+        // 处理重复 id
+        const count = slugCount.get(baseSlug) ?? 0
+        slugCount.set(baseSlug, count + 1)
+        const id = count > 0 ? `${baseSlug}-${count + 1}` : baseSlug
+
+        // 应用层级偏移
+        const adjustedLevel = Math.min(level + currentLevelOffset, 6) as HeadingLevel
+        const { index } = collector.add(text, adjustedLevel, id)
+
+        return (
+          <HeadingElement level={adjustedLevel} id={id} index={index} className={className}>
+            {children}
+          </HeadingElement>
+        )
+      }
+    }
+
+    const Section: SectionComponent = ({ children, className }) => {
+      // Section 通过 TocLevelProvider 提供层级 +1
+      return (
+        <TocLevelProvider additionalOffset={1}>
+          <section className={`markdown-section ${className}`}>{children}</section>
+        </TocLevelProvider>
+      )
+    }
+
+    return {
+      H1: createHeading(1),
+      H2: createHeading(2),
+      H3: createHeading(3),
+      H4: createHeading(4),
+      H5: createHeading(5),
+      H6: createHeading(6),
+      Section,
+    }
+  }, [collector, levelOffset])
+
+  return <div className={`markdown-content ${className}`}>{builder(components)}</div>
+}
+
+// ============================================================================
+// Helper Components
+// ============================================================================
+
+function HeadingElement({
+  level,
+  id,
+  index,
+  children,
+  className,
+}: {
+  level: HeadingLevel
+  id: string
+  index: number
+  children?: ReactNode
+  className?: string
+}) {
+  const style = { viewTimelineName: `--toc-${index}` }
+  switch (level) {
+    case 1:
+      return (
+        <h1 id={id} className={className} style={style}>
+          {children}
+        </h1>
+      )
+    case 2:
+      return (
+        <h2 id={id} className={className} style={style}>
+          {children}
+        </h2>
+      )
+    case 3:
+      return (
+        <h3 id={id} className={className} style={style}>
+          {children}
+        </h3>
+      )
+    case 4:
+      return (
+        <h4 id={id} className={className} style={style}>
+          {children}
+        </h4>
+      )
+    case 5:
+      return (
+        <h5 id={id} className={className} style={style}>
+          {children}
+        </h5>
+      )
+    case 6:
+      return (
+        <h6 id={id} className={className} style={style}>
+          {children}
+        </h6>
+      )
+  }
+}
+
+// ============================================================================
+// MarkdownContainer - 布局容器
+// ============================================================================
+
+interface MarkdownContainerProps {
+  children: ReactNode
+  className?: string
+  /** CSS timeline-scope value for ToC scroll tracking */
+  timelineScope?: string
+}
+
+/**
+ * Shared container for markdown-style content with consistent scrolling and padding.
+ */
+function MarkdownContainer({ children, className = '', timelineScope }: MarkdownContainerProps) {
+  return (
+    <div
+      className={`scrollbar-thin scrollbar-track-transparent h-full overflow-auto scroll-smooth p-4 ${className}`}
+      style={timelineScope ? ({ timelineScope } as React.CSSProperties) : undefined}
+    >
+      {children}
+    </div>
+  )
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/** 从 React children 中提取纯文本 */
+function extractTextFromChildren(children: ReactNode): string {
+  if (children == null || typeof children === 'boolean') return ''
+  if (typeof children === 'string' || typeof children === 'number') return String(children)
+  if (Array.isArray(children)) return children.map(extractTextFromChildren).join('')
+  if (typeof children === 'object' && 'props' in children) {
+    return extractTextFromChildren(
+      (children as { props?: { children?: ReactNode } }).props?.children
+    )
+  }
+  return ''
+}
+
+/** 比较两个 TocItem 数组是否相等 */
+function arraysEqual(a: TocItem[], b: TocItem[]): boolean {
+  if (a.length !== b.length) return false
+  return a.every(
+    (item, i) => item.id === b[i].id && item.label === b[i].label && item.level === b[i].level
+  )
+}
+
+// ============================================================================
+// Styles
+// ============================================================================
+
+const css = String.raw
+/** CSS for container queries layout */
+const viewerStyles = css`
+  /* Container query based layout */
+  .viewer-layout {
+    display: block;
+  }
+  .viewer-toc {
+    margin-bottom: 1rem;
+  }
+
+  /* Wide container: grid layout with ToC on right */
+  @container (min-width: 768px) {
+    .viewer-layout {
+      display: grid;
+      grid-template-columns: 1fr 180px;
+    }
+    .viewer-toc {
+      order: 2;
+      margin-bottom: 0;
+    }
+    .viewer-content {
+      order: 1;
+    }
+  }
+`

package/src/components/path-marquee.tsx

@@ -0,0 +1,104 @@
+import { Check, Copy } from 'lucide-react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+interface PathMarqueeProps {
+  /** The path to display */
+  children: string
+  /** Maximum width of the container (default: 300px) */
+  maxWidth?: number | string
+  /** Animation duration in seconds (default: 10) */
+  duration?: number
+  /** Gap between repeated content (default: 20px) */
+  gap?: number
+  /** Additional className for the container */
+  className?: string
+}
+
+/**
+ * A marquee component for displaying long paths with auto-scrolling animation.
+ * - Pure CSS animation using ::after pseudo-element
+ * - Pauses on hover
+ * - Click to copy path
+ * - Only animates when content overflows
+ */
+export function PathMarquee({
+  children: path,
+  maxWidth = 300,
+  duration = 10,
+  gap = 20,
+  className = '',
+}: PathMarqueeProps) {
+  const [copied, setCopied] = useState(false)
+  const [shouldAnimate, setShouldAnimate] = useState(false)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const contentRef = useRef<HTMLDivElement>(null)
+
+  // Check if content overflows and needs animation
+  useEffect(() => {
+    const checkOverflow = () => {
+      if (containerRef.current && contentRef.current) {
+        const containerWidth = containerRef.current.offsetWidth
+        const contentWidth = contentRef.current.scrollWidth
+        setShouldAnimate(contentWidth > containerWidth)
+      }
+    }
+
+    checkOverflow()
+    window.addEventListener('resize', checkOverflow)
+    return () => window.removeEventListener('resize', checkOverflow)
+  }, [path])
+
+  // Handle copy to clipboard
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(path)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy path:', err)
+    }
+  }, [path])
+
+  const maxWidthStyle = typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth
+
+  return (
+    <button
+      onClick={handleCopy}
+      className={`hover:bg-muted/50 group flex cursor-pointer items-center gap-1.5 rounded transition-colors ${className}`}
+      title={`${path}\n\nClick to copy`}
+    >
+      {/* Marquee container */}
+      <div
+        ref={containerRef}
+        className="relative overflow-hidden whitespace-nowrap"
+        style={{ maxWidth: maxWidthStyle }}
+      >
+        {/* Animated content */}
+        <div
+          ref={contentRef}
+          data-content={path}
+          className={`relative inline-block ${shouldAnimate ? 'animate-marquee group-hover:[animation-play-state:paused]!' : ''}`}
+          style={
+            shouldAnimate
+              ? ({
+                  '--marquee-duration': `${duration}s`,
+                  '--marquee-gap': `${gap}px`,
+                } as React.CSSProperties)
+              : undefined
+          }
+        >
+          {path}
+        </div>
+      </div>
+
+      {/* Copy indicator */}
+      <span className="text-muted-foreground group-hover:text-foreground shrink-0 transition-colors">
+        {copied ? (
+          <Check className="h-3.5 w-3.5 text-green-500" />
+        ) : (
+          <Copy className="h-3.5 w-3.5" />
+        )}
+      </span>
+    </button>
+  )
+}

package/src/components/tabs.tsx

@@ -0,0 +1,151 @@
+import { Activity, useId, useMemo, useState, type ReactNode } from 'react'
+
+export interface Tab {
+  id: string
+  label: ReactNode
+  icon?: ReactNode
+  content: ReactNode
+  /** Unmount the tab content when hidden to avoid heavy components lingering (e.g., Monaco) */
+  unmountOnHide?: boolean
+}
+
+interface TabsProps {
+  tabs: Tab[]
+  /** Controlled selected tab id */
+  selectedTab?: string
+  onTabChange?: (id: string) => void
+  className?: string
+}
+
+const tabsStyle = (id: string) => {
+  const css = String.raw
+  const anchorName = `--tabs-button-${id}`
+  return (
+    <style>
+      {css`
+        #${id} {
+          .tabs-button {
+            anchor-name: ${anchorName};
+          }
+          .tabs-button::scroll-button(*) {
+            position-anchor: ${anchorName};
+          }
+        }
+      ` +
+        css`
+          #${id} {
+            .tabs-button {
+              overflow-x: auto;
+              scroll-behavior: smooth;
+              overscroll-behavior-x: contain;
+              scroll-snap-type: x mandatory;
+              position: relative;
+              background-image: linear-gradient(
+                to bottom,
+                transparent,
+                transparent calc(100% - 1px),
+                var(--border) calc(100% - 1px),
+                var(--border)
+              );
+              & > button {
+                scroll-snap-align: start;
+                text-align: center;
+                &.tab-selected {
+                  background-image: linear-gradient(
+                    to bottom,
+                    transparent,
+                    transparent calc(100% - 2px),
+                    var(--primary) calc(100% - 2px),
+                    var(--primary)
+                  );
+                }
+              }
+            }
+            .tabs-button::scroll-button(*) {
+              position: absolute;
+              align-self: anchor-center;
+              border: 0;
+              font-size: 1.2rem;
+              background: none;
+              z-index: 2;
+            }
+            .tabs-button::scroll-button(*):disabled {
+              opacity: 0;
+            }
+            .tabs-button::scroll-button(left) {
+              content: '◄';
+              right: calc(anchor(left) - 0.5rem);
+              transform: scaleX(0.5);
+            }
+
+            .tabs-button::scroll-button(right) {
+              content: '►';
+              left: calc(anchor(right) - 0.5rem);
+              transform: scaleX(0.5);
+            }
+          }
+        `}
+    </style>
+  )
+}
+
+/**
+ * Tabs component with React 19 Activity for state preservation.
+ * Hidden tabs are pre-rendered at lower priority and preserve their state.
+ * Supports both controlled and uncontrolled active tab.
+ */
+export function Tabs({ tabs, selectedTab: controlled, onTabChange, className = '' }: TabsProps) {
+  const [uncontrolled, setUncontrolled] = useState<string>(tabs[0]?.id ?? '')
+  const activeTab = controlled ?? uncontrolled
+
+  const handleChange = (id: string) => {
+    if (!controlled) {
+      setUncontrolled(id)
+    }
+    onTabChange?.(id)
+  }
+
+  if (tabs.length === 0) return null
+
+  const id = useId()
+
+  const style = useMemo(() => tabsStyle(id), [id])
+
+  return (
+    <div id={id} className={`flex min-h-0 flex-1 flex-col ${className}`}>
+      {style}
+      {/* Tab buttons */}
+      <div className="tabs-button z-2 bg-background oveflow-x-auto scrollbar-none sticky top-0 flex gap-1">
+        {tabs.map((tab) => (
+          <button
+            key={tab.id}
+            onClick={() => handleChange(tab.id)}
+            className={`m-0 flex h-full shrink-0 items-center gap-2 px-4 py-2 text-sm font-medium transition-colors ${
+              activeTab === tab.id
+                ? 'tab-selected text-foreground'
+                : 'text-muted-foreground hover:text-foreground'
+            }`}
+          >
+            {tab.icon}
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Tab content with Activity for state preservation */}
+      {tabs.map((tab) =>
+        tab.unmountOnHide ? (
+          activeTab === tab.id && (
+            <div key={tab.id} className="min-h-0 flex-1">
+              {tab.content}
+            </div>
+          )
+        ) : (
+          <Activity key={tab.id} mode={activeTab === tab.id ? 'visible' : 'hidden'}>
+            <div className="min-h-0 flex-1">{tab.content}</div>
+          </Activity>
+        )
+      )}
+    </div>
+  )
+}

package/src/components/tasks-view.test.tsx

@@ -0,0 +1,45 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { TasksView, type Task } from './tasks-view'
+
+function renderTasks(tasks: Task[]) {
+  const completed = tasks.filter((task) => task.completed).length
+  return render(
+    <TasksView tasks={tasks} progress={{ total: tasks.length, completed }} tocBaseIndex={0} />
+  )
+}
+
+describe('TasksView', () => {
+  it('updates text when task text changes', () => {
+    const tasks: Task[] = [
+      {
+        id: 'task-1',
+        text: 'Initial task text',
+        completed: false,
+        section: 'Setup',
+      },
+    ]
+
+    const { rerender } = renderTasks(tasks)
+
+    expect(screen.getByText('Initial task text')).toBeInTheDocument()
+
+    const updatedTasks: Task[] = [
+      {
+        ...tasks[0],
+        text: 'Updated task text',
+      },
+    ]
+
+    rerender(
+      <TasksView
+        tasks={updatedTasks}
+        progress={{ total: updatedTasks.length, completed: 0 }}
+        tocBaseIndex={0}
+      />
+    )
+
+    expect(screen.getByText('Updated task text')).toBeInTheDocument()
+    expect(screen.queryByText('Initial task text')).not.toBeInTheDocument()
+  })
+})