@leanspec/ui 0.2.3 → 0.2.4

package/dist/standalone/packages/web/src/components/spec-detail-client.tsx

@@ -0,0 +1,372 @@
+/**
+ * Client component for spec detail page with SWR caching and instant sub-spec navigation
+ * Phase 2: Tier 2 - Hybrid Rendering
+ */
+
+'use client';
+
+import * as React from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import useSWR from 'swr';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeSlug from 'rehype-slug';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { SpecTimeline } from '@/components/spec-timeline';
+import { StatusBadge } from '@/components/status-badge';
+import { PriorityBadge } from '@/components/priority-badge';
+import { MarkdownLink } from '@/components/markdown-link';
+import { TableOfContents } from '@/components/table-of-contents';
+import { BackToTop } from '@/components/back-to-top';
+import { SpecDependencyGraph } from '@/components/spec-dependency-graph';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import { extractH1Title, cn } from '@/lib/utils';
+import { formatRelativeTime } from '@/lib/date-utils';
+import type { SpecWithMetadata } from '@/types/specs';
+import { 
+  FileText, 
+  Palette, 
+  Code, 
+  TestTube, 
+  CheckSquare, 
+  Wrench, 
+  Map, 
+  GitBranch, 
+  Home,
+  TrendingUp,
+  Clock,
+  Maximize2
+} from 'lucide-react';
+import type { Plugin } from 'unified';
+import { visit } from 'unist-util-visit';
+import type { Html, Root } from 'mdast';
+
+const remarkStripHtmlComments: Plugin<[], Root> = () => (tree: Root) => {
+  visit(tree, 'html', (node: Html) => {
+    if (typeof node.value === 'string' && node.value.trim().startsWith('<!--')) {
+      node.value = '';
+    }
+  });
+};
+
+// Icon mapping for sub-specs
+const SUB_SPEC_ICONS: Record<string, React.ComponentType<{ className?: string }>> = {
+  'FileText': FileText,
+  'Palette': Palette,
+  'Code': Code,
+  'TestTube': TestTube,
+  'CheckSquare': CheckSquare,
+  'Wrench': Wrench,
+  'Map': Map,
+  'GitBranch': GitBranch,
+  'Home': Home,
+  'TrendingUp': TrendingUp,
+};
+
+interface SpecDetailClientProps {
+  initialSpec: SpecWithMetadata;
+  initialSubSpec?: string;
+}
+
+// SWR fetcher with error handling
+const fetcher = (url: string) => fetch(url).then((res) => {
+  if (!res.ok) {
+    throw new Error(`HTTP error! status: ${res.status}`);
+  }
+  return res.json();
+});
+
+export function SpecDetailClient({ initialSpec, initialSubSpec }: SpecDetailClientProps) {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const currentSubSpec = searchParams.get('subspec') || initialSubSpec;
+  const [timelineDialogOpen, setTimelineDialogOpen] = React.useState(false);
+  const [dependenciesDialogOpen, setDependenciesDialogOpen] = React.useState(false);
+  
+  // Use SWR for client-side caching with the initial spec as fallback
+  const { data: specData, error, isLoading } = useSWR<{ spec: SpecWithMetadata }>(
+    `/api/specs/${initialSpec.specNumber || initialSpec.id}`,
+    fetcher,
+    {
+      fallbackData: { spec: initialSpec },
+      revalidateOnFocus: false,
+      dedupingInterval: 5000, // Don't refetch within 5 seconds
+    }
+  );
+
+  // Fetch complete dependency graph when dialog opens
+  const { data: dependencyGraphData } = useSWR<{
+    current: any;
+    dependsOn: any[];
+    requiredBy: any[];
+    related: any[];
+  }>(
+    dependenciesDialogOpen ? `/api/specs/${initialSpec.specNumber || initialSpec.id}/dependency-graph` : null,
+    fetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 60000, // Cache for 1 minute
+    }
+  );
+
+  const spec = specData?.spec || initialSpec;
+  const tags = spec.tags || [];
+  const updatedRelative = spec.updatedAt ? formatRelativeTime(spec.updatedAt) : 'N/A';
+  const relationships = spec.relationships;
+  
+  // Use complete graph if available, otherwise fall back to basic relationships
+  const completeRelationships = dependencyGraphData
+    ? {
+        dependsOn: dependencyGraphData.dependsOn.map(s => s.specName),
+        requiredBy: dependencyGraphData.requiredBy.map(s => s.specName),
+        related: dependencyGraphData.related.map(s => s.specName),
+      }
+    : relationships;
+  
+  const hasRelationships = Boolean(
+    relationships && ((relationships.dependsOn?.length ?? 0) > 0 || (relationships.related?.length ?? 0) > 0)
+  );
+
+  React.useEffect(() => {
+    if (!hasRelationships) {
+      setDependenciesDialogOpen(false);
+    }
+  }, [hasRelationships]);
+
+  // Extract H1 title from markdown content
+  const h1Title = extractH1Title(spec.contentMd);
+  const displayTitle = h1Title || spec.title || spec.specName;
+  
+  // Get content to display (main or sub-spec)
+  let displayContent = spec.contentMd;
+  
+  if (currentSubSpec && spec.subSpecs) {
+    const subSpecData = spec.subSpecs.find(s => s.file === currentSubSpec);
+    if (subSpecData) {
+      displayContent = subSpecData.content;
+    }
+  }
+
+  // Format dates
+  const formatDate = (date: Date | string | number | null) => {
+    if (!date) return 'N/A';
+    return new Date(date).toLocaleDateString('en-US', { 
+      year: 'numeric', 
+      month: 'short', 
+      day: 'numeric' 
+    });
+  };
+
+  // Handle sub-spec switching with optimistic UI (instant, no network)
+  const handleSubSpecSwitch = (file: string | null) => {
+    const newUrl = file 
+      ? `/specs/${spec.specNumber || spec.id}?subspec=${file}`
+      : `/specs/${spec.specNumber || spec.id}`;
+    
+    // Use shallow routing to avoid full page reload
+    router.push(newUrl, { scroll: false });
+  };
+
+  return (
+    <>
+      {/* Compact Header - sticky on desktop, static on mobile */}
+      <header className="lg:sticky lg:top-14 lg:z-20 border-b bg-card">
+        <div className="px-3 sm:px-6 py-3 sm:py-4">
+          {/* Line 1: Spec number + H1 Title */}
+          <h1 className="text-xl sm:text-2xl font-bold tracking-tight mb-2 sm:mb-3">
+            {spec.specNumber && (
+              <span className="text-muted-foreground">#{spec.specNumber.toString().padStart(3, '0')} </span>
+            )}
+            {displayTitle}
+          </h1>
+          
+          {/* Line 2: Status, Priority, Tags, Actions */}
+          <div className="flex flex-wrap items-center gap-2">
+            <StatusBadge status={spec.status || 'planned'} />
+            <PriorityBadge priority={spec.priority || 'medium'} />
+            
+            {tags.length > 0 && (
+              <>
+                <div className="h-4 w-px bg-border mx-1 hidden sm:block" />
+                <div className="flex flex-wrap gap-1">
+                  {tags.slice(0, 5).map((tag: string) => (
+                    <Badge key={tag} variant="secondary" className="text-xs">
+                      {tag}
+                    </Badge>
+                  ))}
+                  {tags.length > 5 && (
+                    <Badge variant="secondary" className="text-xs">
+                      +{tags.length - 5} more
+                    </Badge>
+                  )}
+                </div>
+              </>
+            )}
+          </div>
+
+          {/* Line 3: Small metadata row */}
+          <div className="flex flex-wrap gap-2 sm:gap-4 text-xs text-muted-foreground mt-2 sm:mt-3">
+            <span className="hidden sm:inline">Created: {formatDate(spec.createdAt)}</span>
+            <span className="hidden sm:inline">•</span>
+            <span>
+              Updated: {formatDate(spec.updatedAt)}
+              {spec.updatedAt && (
+                <span className="ml-1 text-[11px] text-muted-foreground/80">({updatedRelative})</span>
+              )}
+            </span>
+            <span className="hidden sm:inline">•</span>
+            <span className="hidden md:inline">Name: {spec.specName}</span>
+            {spec.assignee && (
+              <>
+                <span className="hidden sm:inline">•</span>
+                <span className="hidden sm:inline">Assignee: {spec.assignee}</span>
+              </>
+            )}
+          </div>
+
+          <div className="flex flex-wrap items-center gap-2 mt-3">
+            <Dialog open={timelineDialogOpen} onOpenChange={setTimelineDialogOpen}>
+              <DialogTrigger asChild>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  className="h-8 rounded-full border px-3 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+                >
+                  <Clock className="mr-1.5 h-3.5 w-3.5" />
+                  View Timeline
+                  <Maximize2 className="ml-1.5 h-3.5 w-3.5" />
+                </Button>
+              </DialogTrigger>
+              <DialogContent className="w-[min(900px,90vw)] max-w-3xl max-h-[90vh] overflow-y-auto">
+                <DialogHeader>
+                  <DialogTitle>Spec Timeline</DialogTitle>
+                  <DialogDescription>Created, updated, and completion milestones.</DialogDescription>
+                </DialogHeader>
+                <div className="rounded-xl border border-border bg-muted/30 p-4">
+                  <SpecTimeline
+                    createdAt={spec.createdAt}
+                    updatedAt={spec.updatedAt}
+                    completedAt={spec.completedAt}
+                    status={spec.status || 'planned'}
+                  />
+                </div>
+              </DialogContent>
+            </Dialog>
+
+            <Dialog open={dependenciesDialogOpen} onOpenChange={setDependenciesDialogOpen}>
+              <DialogTrigger asChild>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  disabled={!hasRelationships}
+                  className={cn(
+                    'h-8 rounded-full border px-3 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground',
+                    !hasRelationships && 'cursor-not-allowed opacity-50'
+                  )}
+                >
+                  <GitBranch className="mr-1.5 h-3.5 w-3.5" />
+                  View Dependencies
+                  <Maximize2 className="ml-1.5 h-3.5 w-3.5" />
+                </Button>
+              </DialogTrigger>
+              <DialogContent className="flex h-[85vh] w-[min(1200px,95vw)] max-w-6xl flex-col gap-4 overflow-hidden">
+                <DialogHeader>
+                  <DialogTitle>Dependency Graph</DialogTitle>
+                  <DialogDescription>
+                    Precedence requirements and connected specs rendered with automatic layout.
+                  </DialogDescription>
+                </DialogHeader>
+                <div className="min-h-0 flex-1">
+                  {completeRelationships && (
+                    <SpecDependencyGraph
+                      relationships={completeRelationships}
+                      specNumber={spec.specNumber}
+                      specTitle={displayTitle}
+                    />
+                  )}
+                </div>
+              </DialogContent>
+            </Dialog>
+          </div>
+        </div>
+
+        {/* Horizontal Tabs for Sub-specs (only if sub-specs exist) */}
+        {spec.subSpecs && spec.subSpecs.length > 0 && (
+          <div className="border-t bg-muted/30">
+            <div className="px-3 sm:px-6 overflow-x-auto">
+              <div className="flex gap-1 py-2 min-w-max">
+                {/* Overview tab (README.md) */}
+                <button
+                  onClick={() => handleSubSpecSwitch(null)}
+                  className={`flex items-center gap-2 px-3 sm:px-4 py-2 text-xs sm:text-sm font-medium rounded-md whitespace-nowrap transition-colors ${
+                    !currentSubSpec
+                      ? 'bg-background text-foreground shadow-sm'
+                      : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
+                  }`}
+                >
+                  <Home className="h-4 w-4" />
+                  <span className="hidden sm:inline">Overview</span>
+                </button>
+
+                
+                {/* Sub-spec tabs */}
+                {spec.subSpecs.map((subSpec) => {
+                  const Icon = SUB_SPEC_ICONS[subSpec.iconName] || FileText;
+                  return (
+                    <button
+                      key={subSpec.file}
+                      onClick={() => handleSubSpecSwitch(subSpec.file)}
+                      className={`flex items-center gap-2 px-3 sm:px-4 py-2 text-xs sm:text-sm font-medium rounded-md whitespace-nowrap transition-colors ${
+                        currentSubSpec === subSpec.file
+                          ? 'bg-background text-foreground shadow-sm'
+                          : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
+                      }`}
+                    >
+                      <Icon className={`h-4 w-4 ${subSpec.color}`} />
+                      <span className="hidden sm:inline">{subSpec.name}</span>
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+          </div>
+        )}
+      </header>
+
+      {/* Main content (full width) */}
+      <main className="px-3 sm:px-6 py-4 sm:py-8">
+        <div className="space-y-6">
+          {isLoading && <div className="text-sm text-muted-foreground">Loading...</div>}
+          {error && <div className="text-sm text-destructive">Error loading spec</div>}
+
+          <article className="prose prose-slate dark:prose-invert max-w-none prose-sm sm:prose-base">
+            <ReactMarkdown
+              remarkPlugins={[remarkGfm, remarkStripHtmlComments]}
+              rehypePlugins={[rehypeHighlight, rehypeSlug]}
+              components={{
+                a: (props) => <MarkdownLink {...props} currentSpecNumber={spec.specNumber || undefined} />,
+              }}
+            >
+              {displayContent}
+            </ReactMarkdown>
+          </article>
+        </div>
+      </main>
+
+      {/* Floating action buttons */}
+      <TableOfContents content={displayContent} />
+      <BackToTop />
+    </>
+  );
+}

package/dist/standalone/packages/web/src/components/spec-detail-loading-shell.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { SpecsNavSidebar } from '@/components/specs-nav-sidebar';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useSpecsSidebarState } from '@/lib/stores/specs-sidebar-store';
+
+export function SpecDetailLoadingShell() {
+  const sidebarState = useSpecsSidebarState();
+  const cachedSpecs = sidebarState.specs;
+  const activeSpecId = sidebarState.activeSpecId || '';
+
+  return (
+    <div className="flex min-h-[calc(100vh-3.5rem)] w-full min-w-0">
+      <SpecsNavSidebar initialSpecs={cachedSpecs} currentSpecId={activeSpecId} />
+
+      <div className="flex-1 min-w-0 px-4 py-6 sm:px-8 sm:py-10">
+        <div className="space-y-6">
+          <div className="space-y-3">
+            <Skeleton className="h-7 w-56" />
+            <div className="flex flex-wrap gap-3">
+              <Skeleton className="h-6 w-24" />
+              <Skeleton className="h-6 w-24" />
+              <Skeleton className="h-6 w-20" />
+            </div>
+            <Skeleton className="h-4 w-64" />
+          </div>
+
+          <div className="space-y-4">
+            <Skeleton className="h-5 w-40" />
+            <Skeleton className="h-32 w-full" />
+          </div>
+
+          <div className="space-y-4">
+            {[...Array(6)].map((_, idx) => (
+              <Skeleton key={idx} className="h-4 w-full" />
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/dist/standalone/packages/web/src/components/spec-detail-wrapper.tsx

@@ -0,0 +1,70 @@
+/**
+ * Client wrapper for spec detail page with prefetching support
+ * Phase 2: Tier 2 - Hybrid Rendering
+ */
+
+'use client';
+
+import * as React from 'react';
+import { SpecsNavSidebar } from '@/components/specs-nav-sidebar';
+import { SpecDetailClient } from '@/components/spec-detail-client';
+import { primeSpecsSidebar, setActiveSidebarSpec } from '@/lib/stores/specs-sidebar-store';
+import type { SpecWithMetadata, SidebarSpec } from '@/types/specs';
+import type { ParsedSpec } from '@/lib/db/service-queries';
+
+interface SpecDetailWrapperProps {
+  spec: SpecWithMetadata;
+  allSpecs: ParsedSpec[];
+  currentSubSpec?: string;
+}
+
+export function SpecDetailWrapper({ spec, allSpecs, currentSubSpec }: SpecDetailWrapperProps) {
+  const sidebarSpecs = React.useMemo<SidebarSpec[]>(() => (
+    allSpecs.map((item) => ({
+      id: item.id,
+      specNumber: item.specNumber,
+      title: item.title,
+      specName: item.specName,
+      status: item.status,
+      priority: item.priority,
+      tags: item.tags,
+      contentMd: item.contentMd,
+      updatedAt: item.updatedAt,
+      subSpecsCount: ('subSpecsCount' in item) ? (item as any).subSpecsCount : undefined,
+    }))
+  ), [allSpecs]);
+
+  // Prime sidebar store with latest metadata (only publishes when signature changes)
+  React.useEffect(() => {
+    primeSpecsSidebar(sidebarSpecs);
+  }, [sidebarSpecs]);
+
+  React.useEffect(() => {
+    setActiveSidebarSpec(spec.id);
+  }, [spec.id]);
+
+  // Prefetch spec data on hover
+  const handleSpecPrefetch = React.useCallback((specId: string) => {
+    fetch(`/api/specs/${specId}`).catch(() => {
+      // Prefetch is opportunistic, ignore failures
+    });
+  }, []);
+
+  return (
+    <div className="flex min-h-[calc(100vh-3.5rem)] w-full min-w-0">
+      <SpecsNavSidebar 
+        initialSpecs={sidebarSpecs}
+        currentSpecId={spec.id}
+        currentSubSpec={currentSubSpec}
+        onSpecHover={handleSpecPrefetch}
+      />
+
+      <div className="flex-1 min-w-0">
+        <SpecDetailClient 
+          initialSpec={spec}
+          initialSubSpec={currentSubSpec}
+        />
+      </div>
+    </div>
+  );
+}

package/dist/standalone/packages/web/src/components/spec-metadata.tsx

@@ -0,0 +1,136 @@
+/**
+ * Metadata card component with icons for spec details
+ */
+
+import { Calendar, User, Tag, GitBranch, ExternalLink } from 'lucide-react';
+import { Card, CardContent } from '@/components/ui/card';
+import { Badge } from '@/components/ui/badge';
+import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { StatusBadge } from '@/components/status-badge';
+import { PriorityBadge } from '@/components/priority-badge';
+import { formatDate, formatRelativeTime } from '@/lib/date-utils';
+import type { Spec } from '@/lib/db/schema';
+
+interface SpecMetadataProps {
+  spec: Spec & { tags: string[] | null };
+}
+
+export function SpecMetadata({ spec }: SpecMetadataProps) {
+  return (
+    <Card>
+      <CardContent className="pt-6">
+        <dl className="grid grid-cols-2 gap-4">
+          {/* Status */}
+          <div>
+            <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+              Status
+            </dt>
+            <dd>
+              <StatusBadge status={spec.status || 'planned'} />
+            </dd>
+          </div>
+
+          {/* Priority */}
+          <div>
+            <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+              Priority
+            </dt>
+            <dd>
+              <PriorityBadge priority={spec.priority || 'medium'} />
+            </dd>
+          </div>
+
+          {/* Created */}
+          <div>
+            <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+              <Calendar className="h-4 w-4" />
+              Created
+            </dt>
+            <dd className="text-sm">
+              {formatDate(spec.createdAt)}
+              {spec.createdAt && (
+                <span className="text-muted-foreground ml-1">
+                  ({formatRelativeTime(spec.createdAt)})
+                </span>
+              )}
+            </dd>
+          </div>
+
+          {/* Updated */}
+          <div>
+            <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+              <Calendar className="h-4 w-4" />
+              Updated
+            </dt>
+            <dd className="text-sm">
+              {formatDate(spec.updatedAt)}
+              {spec.updatedAt && (
+                <span className="text-muted-foreground ml-1">
+                  ({formatRelativeTime(spec.updatedAt)})
+                </span>
+              )}
+            </dd>
+          </div>
+
+          {/* Assignee */}
+          {spec.assignee && (
+            <div>
+              <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+                <User className="h-4 w-4" />
+                Assignee
+              </dt>
+              <dd>
+                <div className="flex items-center gap-2">
+                  <Avatar className="h-6 w-6">
+                    <AvatarFallback className="text-xs">
+                      {spec.assignee.substring(0, 2).toUpperCase()}
+                    </AvatarFallback>
+                  </Avatar>
+                  <span className="text-sm">{spec.assignee}</span>
+                </div>
+              </dd>
+            </div>
+          )}
+
+          {/* Tags */}
+          {spec.tags && spec.tags.length > 0 && (
+            <div className={spec.assignee ? '' : 'col-span-2'}>
+              <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+                <Tag className="h-4 w-4" />
+                Tags
+              </dt>
+              <dd className="flex gap-1 flex-wrap">
+                {spec.tags.map((tag) => (
+                  <Badge key={tag} variant="outline" className="text-xs">
+                    {tag}
+                  </Badge>
+                ))}
+              </dd>
+            </div>
+          )}
+
+          {/* GitHub URL */}
+          {spec.githubUrl && (
+            <div className="col-span-2">
+              <dt className="text-sm font-medium text-muted-foreground flex items-center gap-1.5 mb-1">
+                <GitBranch className="h-4 w-4" />
+                Source
+              </dt>
+              <dd>
+                <a
+                  href={spec.githubUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-sm text-primary hover:underline flex items-center gap-1"
+                >
+                  View on GitHub
+                  <ExternalLink className="h-3.5 w-3.5" />
+                </a>
+              </dd>
+            </div>
+          )}
+        </dl>
+      </CardContent>
+    </Card>
+  );
+}