@openspecui/web 0.9.0

package/src/components/tasks-view.tsx

@@ -0,0 +1,209 @@
+import { TocSection, type TocItem } from '@/components/toc'
+import { CheckCircle, Circle, Loader2 } from 'lucide-react'
+import { memo, useMemo } from 'react'
+
+/** Task item structure from @openspecui/core */
+export interface Task {
+  id: string
+  text: string
+  completed: boolean
+  section?: string
+}
+
+/** Group tasks by their section */
+interface TaskGroup {
+  section: string
+  tasks: Task[]
+  completed: number
+  total: number
+}
+
+/** Group tasks by section and calculate progress per group */
+function groupTasksBySection(tasks: Task[]): TaskGroup[] {
+  const groups = new Map<string, Task[]>()
+
+  for (const task of tasks) {
+    const section = task.section || 'General'
+    const existing = groups.get(section) || []
+    existing.push(task)
+    groups.set(section, existing)
+  }
+
+  return Array.from(groups.entries()).map(([section, sectionTasks]) => ({
+    section,
+    tasks: sectionTasks,
+    completed: sectionTasks.filter((t) => t.completed).length,
+    total: sectionTasks.length,
+  }))
+}
+
+/** Generate a stable ID for a section name */
+export function sectionToId(section: string): string {
+  return `section-${section
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')}`
+}
+
+/** Build ToC items for task sections */
+export function buildTaskTocItems(taskGroups: TaskGroup[]): TocItem[] {
+  return taskGroups.map((group) => ({
+    id: sectionToId(group.section),
+    label: `${group.section} (${group.completed}/${group.total})`,
+    level: 2,
+  }))
+}
+
+interface TaskItemProps {
+  task: Task
+  taskIndex: number
+  isToggling: boolean
+  onToggle?: (taskIndex: number, completed: boolean) => void
+  readonly?: boolean
+}
+
+const TaskItem = memo(
+  function TaskItem({ task, taskIndex, isToggling, onToggle, readonly }: TaskItemProps) {
+    const content = (
+      <>
+        {isToggling ? (
+          <Loader2 className="text-primary h-5 w-5 shrink-0 animate-spin" />
+        ) : task.completed ? (
+          <CheckCircle className="h-5 w-5 shrink-0 text-green-500" />
+        ) : (
+          <Circle className="text-muted-foreground group-hover:text-primary h-5 w-5 shrink-0" />
+        )}
+        <span className={`text-sm ${task.completed ? 'text-muted-foreground line-through' : ''}`}>
+          {task.text}
+        </span>
+      </>
+    )
+
+    if (readonly || !onToggle) {
+      return <div className="flex w-full items-center gap-3 p-3 text-left">{content}</div>
+    }
+
+    return (
+      <button
+        onClick={() => onToggle(taskIndex, !task.completed)}
+        className="hover:bg-muted/50 group flex w-full items-center gap-3 p-3 text-left transition-colors"
+      >
+        {content}
+      </button>
+    )
+  },
+  (prev, next) =>
+    prev.task.id === next.task.id &&
+    prev.task.text === next.task.text &&
+    prev.task.completed === next.task.completed &&
+    prev.isToggling === next.isToggling &&
+    prev.readonly === next.readonly
+)
+
+export interface TasksViewProps {
+  tasks: Task[]
+  progress: { total: number; completed: number }
+  /** Callback when a task is toggled. If not provided, tasks are readonly. */
+  onToggleTask?: (taskIndex: number, completed: boolean) => void
+  /** Index of the task currently being toggled (for loading state) */
+  togglingIndex?: number | null
+  /** Base index for TocSection (for proper ToC navigation) */
+  tocBaseIndex?: number
+  /** Whether to show as readonly (no interaction) */
+  readonly?: boolean
+}
+
+/**
+ * Unified Tasks view component.
+ * Used in both change-view (interactive) and archive-view (readonly).
+ */
+export function TasksView({
+  tasks,
+  progress,
+  onToggleTask,
+  togglingIndex = null,
+  tocBaseIndex = 0,
+  readonly = false,
+}: TasksViewProps) {
+  const taskGroups = useMemo(() => groupTasksBySection(tasks), [tasks])
+
+  const progressPercent =
+    progress.total > 0 ? Math.round((progress.completed / progress.total) * 100) : 0
+
+  // Calculate task index offset for each group (for toggle mutation)
+  const getTaskIndex = (groupIndex: number, taskIndexInGroup: number): number => {
+    let offset = 0
+    for (let i = 0; i < groupIndex; i++) {
+      offset += taskGroups[i].tasks.length
+    }
+    return offset + taskIndexInGroup + 1
+  }
+
+  return (
+    <TocSection id="tasks" index={tocBaseIndex}>
+      <div className="mb-3 flex items-center justify-between">
+        <h2 className="text-lg font-semibold">
+          Tasks ({progress.completed}/{progress.total})
+        </h2>
+        <span className="text-muted-foreground text-sm">{progressPercent}%</span>
+      </div>
+
+      <div className="bg-muted mb-4 h-2 w-full rounded-full">
+        <div
+          className="bg-primary h-2 rounded-full transition-all"
+          style={{ width: `${progressPercent}%` }}
+        />
+      </div>
+
+      {/* Grouped tasks by section */}
+      <div className="space-y-6">
+        {taskGroups.map((group, groupIndex) => {
+          const sectionId = sectionToId(group.section)
+          const sectionPercent =
+            group.total > 0 ? Math.round((group.completed / group.total) * 100) : 0
+
+          return (
+            <TocSection
+              key={group.section}
+              id={sectionId}
+              index={tocBaseIndex + 1 + groupIndex}
+              as="div"
+            >
+              <div className="mb-2 flex items-center justify-between">
+                <h3 className="text-foreground font-medium">{group.section}</h3>
+                <span className="text-muted-foreground text-xs">
+                  {group.completed}/{group.total} ({sectionPercent}%)
+                </span>
+              </div>
+              <div className="border-border divide-border divide-y rounded-lg border">
+                {group.tasks.map((task, taskIndexInGroup) => {
+                  const taskIndex = getTaskIndex(groupIndex, taskIndexInGroup)
+                  return (
+                    <TaskItem
+                      key={task.id}
+                      task={task}
+                      taskIndex={taskIndex}
+                      isToggling={togglingIndex === taskIndex}
+                      onToggle={onToggleTask}
+                      readonly={readonly}
+                    />
+                  )
+                })}
+              </div>
+            </TocSection>
+          )
+        })}
+        {taskGroups.length === 0 && (
+          <div className="text-muted-foreground border-border rounded-lg border p-4 text-center">
+            No tasks defined
+          </div>
+        )}
+      </div>
+    </TocSection>
+  )
+}
+
+/** Hook to get task groups for ToC building */
+export function useTaskGroups(tasks: Task[]) {
+  return useMemo(() => groupTasksBySection(tasks), [tasks])
+}

package/src/components/toc-context.tsx

@@ -0,0 +1,177 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import type { TocItem } from './toc'
+
+// ============================================================================
+// TocCollector - 收集 ToC items 的核心类
+// ============================================================================
+
+export class TocCollector {
+  private items: TocItem[] = []
+  private slugCount = new Map<string, number>()
+  private levelOffset: number
+
+  constructor(levelOffset = 0) {
+    this.levelOffset = levelOffset
+  }
+
+  /** 添加一个 ToC item，返回分配的 index */
+  add(label: string, level: number, fixedId?: string): { id: string; index: number } {
+    const adjustedLevel = Math.min(level + this.levelOffset, 6)
+    const baseSlug = fixedId ?? (slugify(label) || 'heading')
+
+    // 处理重复 id
+    const count = this.slugCount.get(baseSlug) ?? 0
+    this.slugCount.set(baseSlug, count + 1)
+    const id = count > 0 ? `${baseSlug}-${count + 1}` : baseSlug
+
+    const index = this.items.length
+    this.items.push({ id, label, level: adjustedLevel })
+
+    return { id, index }
+  }
+
+  /** 批量添加 items（用于嵌套 MarkdownViewer 合并） */
+  addAll(items: TocItem[]): number {
+    const startIndex = this.items.length
+    for (const item of items) {
+      const adjustedLevel = Math.min((item.level ?? 1) + this.levelOffset, 6)
+      this.items.push({ ...item, level: adjustedLevel })
+    }
+    return startIndex
+  }
+
+  /** 获取所有收集到的 items */
+  getItems(): TocItem[] {
+    return [...this.items]
+  }
+
+  /** 获取当前 item 数量（用于确定下一个 index） */
+  getNextIndex(): number {
+    return this.items.length
+  }
+
+  /** 重置收集器 */
+  reset(): void {
+    this.items = []
+    this.slugCount.clear()
+  }
+
+  /** 创建子 collector（用于 Section 内部，层级 +1） */
+  createChild(additionalOffset = 1): TocCollector {
+    return new TocCollector(this.levelOffset + additionalOffset)
+  }
+}
+
+// ============================================================================
+// Slugify - 生成 URL 友好的 id
+// ============================================================================
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+// ============================================================================
+// TocContext - React Context
+// ============================================================================
+
+interface TocContextValue {
+  /** 当前的 collector 实例（顶层创建，所有嵌套共享） */
+  collector: TocCollector
+  /** 当前层级偏移（Section 嵌套时累加） */
+  levelOffset: number
+  /** 是否是顶层（决定是否渲染 ToC sidebar） */
+  isRoot: boolean
+}
+
+const TocContext = createContext<TocContextValue | null>(null)
+
+/** 获取当前 TocContext，如果不存在返回 null */
+export function useTocContext(): TocContextValue | null {
+  return useContext(TocContext)
+}
+
+/** 获取当前 TocContext，如果不存在则抛出错误 */
+export function useTocContextRequired(): TocContextValue {
+  const ctx = useContext(TocContext)
+  if (!ctx) {
+    throw new Error('useTocContextRequired must be used within a TocProvider')
+  }
+  return ctx
+}
+
+// ============================================================================
+// TocProvider - 提供 TocContext
+// ============================================================================
+
+interface TocProviderProps {
+  children: ReactNode
+  /** collector 实例（顶层创建） */
+  collector: TocCollector
+  /** 当前层级偏移 */
+  levelOffset?: number
+  /** 是否是顶层 */
+  isRoot?: boolean
+}
+
+export function TocProvider({
+  children,
+  collector,
+  levelOffset = 0,
+  isRoot = true,
+}: TocProviderProps) {
+  const value = useMemo<TocContextValue>(
+    () => ({ collector, levelOffset, isRoot }),
+    [collector, levelOffset, isRoot]
+  )
+
+  return <TocContext.Provider value={value}>{children}</TocContext.Provider>
+}
+
+/** 创建一个新的层级 Context（用于 Section） */
+export function TocLevelProvider({
+  children,
+  additionalOffset = 1,
+}: {
+  children: ReactNode
+  additionalOffset?: number
+}) {
+  const parentCtx = useTocContext()
+  if (!parentCtx) {
+    // 没有父级 Context，直接渲染 children
+    return <>{children}</>
+  }
+
+  const value = useMemo<TocContextValue>(
+    () => ({
+      collector: parentCtx.collector,
+      levelOffset: parentCtx.levelOffset + additionalOffset,
+      isRoot: false,
+    }),
+    [parentCtx, additionalOffset]
+  )
+
+  return <TocContext.Provider value={value}>{children}</TocContext.Provider>
+}
+
+// ============================================================================
+// 从 markdown 字符串提取标题
+// ============================================================================
+
+export interface ExtractedHeading {
+  level: number
+  text: string
+}
+
+/** 从 markdown 字符串中提取标题 */
+export function extractHeadingsFromMarkdown(markdown: string): ExtractedHeading[] {
+  const regex = /^(#{1,6})\s+(.+)$/gm
+  const headings: ExtractedHeading[] = []
+  let match
+  while ((match = regex.exec(markdown)) !== null) {
+    headings.push({ level: match[1].length, text: match[2].trim() })
+  }
+  return headings
+}

package/src/components/toc.tsx

@@ -0,0 +1,290 @@
+import { ChevronDown, List } from 'lucide-react'
+import { useCallback, useMemo, useState } from 'react'
+
+export interface TocItem {
+  id: string
+  label: string
+  level?: number // 1 = h1, 2 = h2, etc. Default 1
+}
+
+/** 树形结构节点，用于嵌套渲染 */
+export interface TocNode {
+  item: TocItem
+  /** 原始 index，用于 CSS timeline binding */
+  index: number
+  children: TocNode[]
+}
+
+/**
+ * 将扁平的 TocItem[] 根据 level 构建为树形结构。
+ * level 更大的项成为前一个 level 更小项的子节点。
+ */
+export function buildTocTree(items: TocItem[]): TocNode[] {
+  const roots: TocNode[] = []
+  const stack: TocNode[] = []
+
+  items.forEach((item, index) => {
+    const node: TocNode = { item, index, children: [] }
+    const level = item.level ?? 1
+
+    // 找到合适的父节点：level 必须比当前小
+    while (stack.length > 0) {
+      const parent = stack[stack.length - 1]
+      const parentLevel = parent.item.level ?? 1
+      if (parentLevel < level) {
+        // 找到父节点
+        parent.children.push(node)
+        stack.push(node)
+        return
+      }
+      // 父节点 level >= 当前 level，弹出继续找
+      stack.pop()
+    }
+
+    // 没有合适的父节点，作为根节点
+    roots.push(node)
+    stack.push(node)
+  })
+
+  return roots
+}
+
+interface TocProps {
+  items: TocItem[]
+  /** Default collapsed state on mobile */
+  defaultCollapsed?: boolean
+  className?: string
+}
+
+/**
+ * Table of Contents component with CSS view-timeline scroll highlighting.
+ * Uses container queries for responsive layout.
+ *
+ * 支持树形嵌套结构：根据 TocItem.level 自动构建父子关系，
+ * 渲染为语义化的 `<ul><li>` 嵌套结构。
+ *
+ * Usage:
+ * 1. Pass tocItems to MarkdownViewer for timeline-scope binding
+ * 2. Use TocSection for each section to bind viewTimelineName
+ * 3. The ToC links will automatically highlight based on scroll position
+ */
+export function Toc({ items, defaultCollapsed = true, className = '' }: TocProps) {
+  const [collapsed, setCollapsed] = useState(defaultCollapsed)
+  const tree = useMemo(() => buildTocTree(items), [items])
+
+  // Return hidden placeholder when empty to keep React children stable
+  if (items.length === 0) {
+    return <aside className={`hidden ${className}`} />
+  }
+
+  return (
+    <aside
+      className={`toc-root scrollbar-none sticky top-0 z-10 max-h-[calc(100cqh-3rem)] self-start overflow-y-auto ${className}`}
+    >
+      <style>{tocStyles}</style>
+
+      {/* Narrow: collapsible */}
+      <div className="toc-narrow border-border bg-background overflow-hidden rounded border">
+        <button
+          onClick={() => setCollapsed(!collapsed)}
+          className={`text-foreground flex w-full items-center gap-2 px-3 py-2 ${collapsed ? '' : 'border-border border-b'}`}
+          aria-label={collapsed ? 'Show table of contents' : 'Hide table of contents'}
+        >
+          <List className="h-4 w-4" />
+          <span className="text-sm">Contents</span>
+          <ChevronDown
+            className={`ml-auto h-4 w-4 transition-transform ${collapsed ? '' : 'rotate-180'}`}
+          />
+        </button>
+        {!collapsed && <TocTree nodes={tree} />}
+      </div>
+
+      {/* Wide: always visible */}
+      <nav className="toc-wide flex flex-col">
+        <div className="text-muted-foreground flex items-center gap-2 px-3 py-2 text-xs font-medium uppercase tracking-wide">
+          <List className="h-3.5 w-3.5" />
+          <span>On this page</span>
+        </div>
+        <div className="scrollbar-thin scrollbar-track-transparent min-h-0 flex-1 overflow-y-auto p-2">
+          <TocTree nodes={tree} />
+        </div>
+      </nav>
+    </aside>
+  )
+}
+/**
+ * Find the nearest scrollable ancestor element.
+ */
+function findScrollableParent(element: HTMLElement): HTMLElement | null {
+  return element.closest('.toc-root') as HTMLElement
+}
+
+/**
+ * Scroll element into view within its scrollable container using scrollTo.
+ * NOTE: Cannot use scrollIntoView here because it triggers scroll on all ancestor
+ * scrollable containers, which interferes with the main content's smooth scrolling
+ * when user clicks a ToC link.
+ */
+function scrollIntoViewWithinContainer(element: HTMLElement) {
+  const container = findScrollableParent(element)
+  if (!container) return
+
+  // Use getBoundingClientRect to get positions relative to viewport,
+  // then calculate the relative position within container
+  const elementRect = element.getBoundingClientRect()
+  const containerRect = container.getBoundingClientRect()
+
+  // Element's position relative to container's visible area
+  const relativeTop = elementRect.top - containerRect.top
+  const relativeBottom = elementRect.bottom - containerRect.top
+
+  // Check if element is outside visible area
+  if (relativeTop < 0) {
+    // Element is above visible area
+    container.scrollTo({ top: container.scrollTop + relativeTop, behavior: 'smooth' })
+  } else if (relativeBottom > containerRect.height) {
+    // Element is below visible area
+    container.scrollTo({
+      top: container.scrollTop + relativeBottom - containerRect.height,
+      behavior: 'smooth',
+    })
+  }
+}
+
+/** 递归渲染树形 ToC 结构 */
+function TocTree({ nodes, depth = 0 }: { nodes: TocNode[]; depth?: number }) {
+  const handleAnimationStart = useCallback((e: React.AnimationEvent<HTMLAnchorElement>) => {
+    if (e.animationName === 'toc-activate') {
+      scrollIntoViewWithinContainer(e.currentTarget)
+    }
+  }, [])
+
+  if (nodes.length === 0) return null
+
+  return (
+    <ul className="toc-list">
+      {nodes.map((node) => (
+        <li key={node.item.id} className="toc-item">
+          <a
+            href={`#${node.item.id}`}
+            className={`toc-link text-muted-foreground hover:text-foreground block overflow-hidden text-ellipsis whitespace-nowrap border-l-2 border-transparent py-1 pr-3 ${
+              depth === 0
+                ? 'text-[13px]'
+                : depth === 1
+                  ? 'text-[12px]'
+                  : depth === 2
+                    ? 'text-[11px]'
+                    : 'text-[10px]'
+            }`}
+            style={
+              {
+                '--target': `--toc-${node.index}`,
+                paddingLeft: `${0.75 + depth * 0.5}rem`,
+              } as React.CSSProperties
+            }
+            title={node.item.label}
+            onAnimationStart={handleAnimationStart}
+          >
+            {node.item.label}
+          </a>
+          {node.children.length > 0 && <TocTree nodes={node.children} depth={depth + 1} />}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+const css = String.raw
+/** CSS for container queries and scroll-driven ToC highlighting */
+const tocStyles = css`
+  /* Default: narrow mode (collapsible) */
+  .toc-narrow {
+    display: block;
+  }
+  .toc-wide {
+    display: none;
+  }
+
+  /* Wide container: show sidebar mode */
+  @container (min-width: 768px) {
+    .toc-narrow {
+      display: none;
+    }
+    .toc-wide {
+      display: block;
+    }
+  }
+
+  /* Tree structure styling */
+  .toc-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  /* Scroll-driven ToC highlighting animation */
+  @keyframes toc-activate {
+    0%,
+    100% {
+      color: var(--muted-foreground);
+      border-left-color: transparent;
+    }
+    1%,
+    99% {
+      color: var(--foreground);
+      border-left-color: var(--primary);
+    }
+  }
+  .toc-link {
+    animation-timeline: var(--target);
+    animation-name: toc-activate;
+    animation-fill-mode: both;
+    animation-range: cover 0% cover 100%;
+  }
+`
+
+/**
+ * Generate the timeline-scope CSS value for the container.
+ * This should be applied to the common ancestor of both ToC and content.
+ */
+export function generateTimelineScope(items: TocItem[]): string {
+  return items.map((_, i) => `--toc-${i}`).join(', ')
+}
+
+/**
+ * 为 MarkdownViewer 外部的内容提供 ToC 滚动追踪绑定。
+ *
+ * 使用场景：当内容不在 MarkdownViewer 内部时（如独立的 TasksView 组件），
+ * 无法使用 Section + Heading 组件自动集成 ToC，需要手动使用 TocSection
+ * 绑定 viewTimelineName 以实现滚动高亮。
+ *
+ * 如果内容在 MarkdownViewer 内部，应优先使用 Section + H1-H6 组件，
+ * 它们会自动处理 ToC 注册和 viewTimelineName 绑定。
+ */
+interface TocSectionProps {
+  /** DOM id for anchor links */
+  id: string
+  /** Index in the ToC items array for CSS timeline binding */
+  index: number
+  children: React.ReactNode
+  className?: string
+  as?: 'section' | 'div' | 'article'
+}
+
+export function TocSection({
+  id,
+  index,
+  children,
+  className = '',
+  as: Tag = 'section',
+}: TocSectionProps) {
+  return (
+    <Tag
+      id={id}
+      className={className}
+      style={{ viewTimelineName: `--toc-${index}` } as React.CSSProperties}
+    >
+      {children}
+    </Tag>
+  )
+}