@contractspec/example.learning-journey-ui-onboarding 1.44.0

package/src/components/CodeSnippet.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { useState } from 'react';
+import { Button } from '@contractspec/lib.design-system';
+
+interface CodeSnippetProps {
+  code: string;
+  language?: string;
+  title?: string;
+}
+
+export function CodeSnippet({
+  code,
+  language = 'typescript',
+  title,
+}: CodeSnippetProps) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div className="bg-muted/50 overflow-hidden rounded-lg border">
+      {/* Header */}
+      <div className="bg-muted flex items-center justify-between border-b px-4 py-2">
+        <div className="flex items-center gap-2">
+          <span className="text-muted-foreground text-xs font-medium uppercase">
+            {language}
+          </span>
+          {title && (
+            <>
+              <span className="text-muted-foreground">•</span>
+              <span className="text-sm">{title}</span>
+            </>
+          )}
+        </div>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={handleCopy}
+          className="h-7 text-xs"
+        >
+          {copied ? '✓ Copied' : 'Copy'}
+        </Button>
+      </div>
+
+      {/* Code */}
+      <pre className="overflow-x-auto p-4">
+        <code className="text-sm">{code}</code>
+      </pre>
+    </div>
+  );
+}

package/src/components/JourneyMap.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { LearningJourneyStepSpec } from '@contractspec/module.learning-journey/track-spec';
+
+interface JourneyMapProps {
+  steps: LearningJourneyStepSpec[];
+  completedStepIds: string[];
+  currentStepId?: string | null;
+}
+
+const SURFACE_ICONS: Record<string, string> = {
+  templates: '📋',
+  'spec-editor': '✏️',
+  regenerator: '🔄',
+  playground: '🎮',
+  evolution: '🤖',
+  dashboard: '📊',
+  settings: '⚙️',
+  default: '📍',
+};
+
+export function JourneyMap({
+  steps,
+  completedStepIds,
+  currentStepId,
+}: JourneyMapProps) {
+  return (
+    <div className="relative overflow-x-auto pb-4">
+      <div className="flex min-w-max items-center gap-2">
+        {steps.map((step, index) => {
+          const isCompleted = completedStepIds.includes(step.id);
+          const isCurrent = step.id === currentStepId;
+          const surface = (step.metadata?.surface as string) ?? 'default';
+          const icon = SURFACE_ICONS[surface] ?? SURFACE_ICONS.default;
+
+          return (
+            <div key={step.id} className="flex items-center">
+              {/* Node */}
+              <div className="flex flex-col items-center gap-2">
+                <div
+                  className={cn(
+                    'flex h-14 w-14 items-center justify-center rounded-2xl border-2 text-2xl transition-all',
+                    isCompleted && 'border-green-500 bg-green-500/10',
+                    isCurrent &&
+                      !isCompleted &&
+                      'border-violet-500 bg-violet-500/10 ring-4 ring-violet-500/20',
+                    !isCompleted && !isCurrent && 'border-muted bg-muted/50'
+                  )}
+                >
+                  {isCompleted ? '✓' : icon}
+                </div>
+                <div className="text-center">
+                  <p
+                    className={cn(
+                      'max-w-[100px] truncate text-xs font-medium',
+                      isCompleted && 'text-green-500',
+                      isCurrent && !isCompleted && 'text-violet-500',
+                      !isCompleted && !isCurrent && 'text-muted-foreground'
+                    )}
+                  >
+                    {step.title}
+                  </p>
+                </div>
+              </div>
+
+              {/* Connector */}
+              {index < steps.length - 1 && (
+                <div
+                  className={cn(
+                    'mx-2 h-1 w-8 rounded-full transition-colors',
+                    completedStepIds.includes(steps[index + 1]?.id ?? '')
+                      ? 'bg-green-500'
+                      : isCompleted
+                        ? 'bg-green-500/50'
+                        : 'bg-muted'
+                  )}
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/components/StepChecklist.tsx

@@ -0,0 +1,136 @@
+'use client';
+
+import { Button } from '@contractspec/lib.design-system';
+import { cn } from '@contractspec/lib.ui-kit-core';
+import type { LearningJourneyStepSpec } from '@contractspec/module.learning-journey/track-spec';
+
+interface StepChecklistProps {
+  step: LearningJourneyStepSpec;
+  stepNumber: number;
+  isCompleted: boolean;
+  isCurrent: boolean;
+  isExpanded: boolean;
+  onToggle: () => void;
+  onComplete?: () => void;
+}
+
+export function StepChecklist({
+  step,
+  stepNumber,
+  isCompleted,
+  isCurrent,
+  isExpanded,
+  onToggle,
+  onComplete,
+}: StepChecklistProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-xl border transition-all',
+        isCompleted && 'border-green-500/50 bg-green-500/5',
+        isCurrent && !isCompleted && 'border-violet-500 bg-violet-500/5',
+        !isCompleted && !isCurrent && 'border-border'
+      )}
+    >
+      {/* Header */}
+      <button
+        type="button"
+        className="flex w-full items-center gap-4 p-4 text-left"
+        onClick={onToggle}
+      >
+        {/* Checkbox/Number */}
+        <div
+          className={cn(
+            'flex h-8 w-8 shrink-0 items-center justify-center rounded-full border-2 text-sm font-semibold transition-colors',
+            isCompleted && 'border-green-500 bg-green-500 text-white',
+            isCurrent && !isCompleted && 'border-violet-500 text-violet-500',
+            !isCompleted &&
+              !isCurrent &&
+              'border-muted-foreground text-muted-foreground'
+          )}
+        >
+          {isCompleted ? '✓' : stepNumber}
+        </div>
+
+        {/* Title & Description */}
+        <div className="min-w-0 flex-1">
+          <h4
+            className={cn(
+              'font-semibold',
+              isCompleted && 'text-green-500',
+              isCurrent && !isCompleted && 'text-foreground',
+              !isCompleted && !isCurrent && 'text-muted-foreground'
+            )}
+          >
+            {step.title}
+          </h4>
+          {!isExpanded && step.description && (
+            <p className="text-muted-foreground truncate text-sm">
+              {step.description}
+            </p>
+          )}
+        </div>
+
+        {/* XP Badge */}
+        {step.xpReward && (
+          <span
+            className={cn(
+              'shrink-0 rounded-full px-2 py-1 text-xs font-semibold',
+              isCompleted
+                ? 'bg-green-500/10 text-green-500'
+                : 'bg-muted text-muted-foreground'
+            )}
+          >
+            +{step.xpReward} XP
+          </span>
+        )}
+
+        {/* Expand indicator */}
+        <span
+          className={cn(
+            'shrink-0 transition-transform',
+            isExpanded && 'rotate-180'
+          )}
+        >
+          ▼
+        </span>
+      </button>
+
+      {/* Expanded Content */}
+      {isExpanded && (
+        <div className="border-t px-4 py-4">
+          {step.description && (
+            <p className="text-muted-foreground mb-4">{step.description}</p>
+          )}
+
+          {step.instructions && (
+            <div className="bg-muted mb-4 rounded-lg p-4">
+              <p className="mb-2 text-sm font-medium">Instructions:</p>
+              <p className="text-muted-foreground text-sm">
+                {step.instructions}
+              </p>
+            </div>
+          )}
+
+          {/* Action buttons */}
+          <div className="flex flex-wrap gap-2">
+            {step.actionUrl && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => window.open(step.actionUrl, '_blank')}
+              >
+                {step.actionLabel ?? 'Try it'}
+              </Button>
+            )}
+            {!isCompleted && (
+              <Button size="sm" onClick={onComplete}>
+                Mark as Complete
+              </Button>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export { StepChecklist } from './StepChecklist';
+export { CodeSnippet } from './CodeSnippet';
+export { JourneyMap } from './JourneyMap';

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './learning-journey-ui-onboarding.docblock';

package/src/docs/learning-journey-ui-onboarding.docblock.ts

@@ -0,0 +1,18 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.learning-journey-ui-onboarding',
+    title: 'Learning Journey UI — Onboarding',
+    summary:
+      'UI mini-app components for onboarding: checklists, snippets, and journey mapping.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/learning-journey-ui-onboarding',
+    tags: ['learning', 'ui', 'onboarding'],
+    body: `## Includes\n- Onboarding mini-app shell\n- Views: overview, steps, progress, timeline\n- Components: step checklist, code snippet, journey map\n\n## Notes\n- Compose with design system components.\n- Ensure accessible labels and keyboard navigation.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,24 @@
+const example = {
+  id: 'learning-journey-ui-onboarding',
+  title: 'Learning Journey UI — Onboarding',
+  summary:
+    'UI mini-app for onboarding patterns: checklists, code snippets, journey map.',
+  tags: ['learning', 'ui', 'onboarding'],
+  kind: 'ui',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-ui-onboarding',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-ui-onboarding',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;

package/src/index.ts

@@ -0,0 +1,10 @@
+// Main mini-app
+export { OnboardingMiniApp } from './OnboardingMiniApp';
+
+// Views
+export { Overview, Steps, Progress, Timeline } from './views';
+
+// Components
+export { StepChecklist, CodeSnippet, JourneyMap } from './components';
+export { default as example } from './example';
+import './docs';

package/src/views/Overview.tsx

@@ -0,0 +1,204 @@
+'use client';
+
+import { Button } from '@contractspec/lib.design-system';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from '@contractspec/lib.ui-kit-web/ui/card';
+import { Progress } from '@contractspec/lib.ui-kit-web/ui/progress';
+import { XpBar } from '@contractspec/example.learning-journey-ui-shared';
+import type { LearningViewProps } from '@contractspec/example.learning-journey-ui-shared';
+
+interface OnboardingOverviewProps extends LearningViewProps {
+  onStart?: () => void;
+}
+
+export function Overview({
+  track,
+  progress,
+  onStart,
+}: OnboardingOverviewProps) {
+  const totalSteps = track.steps.length;
+  const completedSteps = progress.completedStepIds.length;
+  const percentComplete =
+    totalSteps > 0 ? (completedSteps / totalSteps) * 100 : 0;
+  const isComplete = completedSteps === totalSteps;
+
+  // Estimate time remaining (rough: 5 min per step)
+  const remainingSteps = totalSteps - completedSteps;
+  const estimatedMinutes = remainingSteps * 5;
+
+  const totalXp =
+    track.totalXp ??
+    track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) +
+      (track.completionRewards?.xpBonus ?? 0);
+
+  return (
+    <div className="space-y-6">
+      {/* Welcome Banner */}
+      <Card className="overflow-hidden bg-gradient-to-r from-blue-500/10 via-violet-500/10 to-purple-500/10">
+        <CardContent className="p-8">
+          <div className="flex flex-col items-center gap-6 text-center md:flex-row md:text-left">
+            <div className="flex h-20 w-20 items-center justify-center rounded-2xl bg-gradient-to-br from-blue-500 to-violet-600 text-4xl shadow-lg">
+              {isComplete ? '🎉' : '🚀'}
+            </div>
+            <div className="flex-1">
+              <h1 className="text-2xl font-bold">{track.name}</h1>
+              <p className="text-muted-foreground mt-1 max-w-2xl">
+                {track.description}
+              </p>
+              {!isComplete && (
+                <p className="text-muted-foreground mt-3 text-sm">
+                  ⏱️ Estimated time:{' '}
+                  {estimatedMinutes > 0
+                    ? `~${estimatedMinutes} minutes`
+                    : 'Less than a minute'}
+                </p>
+              )}
+            </div>
+            {!isComplete && (
+              <Button size="lg" onClick={onStart}>
+                {completedSteps > 0 ? 'Continue' : 'Get Started'}
+              </Button>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Progress Overview */}
+      <div className="grid gap-4 md:grid-cols-3">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              Progress
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold">
+              {Math.round(percentComplete)}%
+            </div>
+            <Progress value={percentComplete} className="mt-2 h-2" />
+            <p className="text-muted-foreground mt-2 text-sm">
+              {completedSteps} of {totalSteps} steps completed
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              XP Earned
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold text-blue-500">
+              {progress.xpEarned}
+            </div>
+            <XpBar
+              current={progress.xpEarned}
+              max={totalXp}
+              showLabel={false}
+              size="sm"
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              Time Remaining
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold">
+              {isComplete ? '✓' : `~${estimatedMinutes}m`}
+            </div>
+            <p className="text-muted-foreground mt-2 text-sm">
+              {isComplete ? 'All done!' : `${remainingSteps} steps to go`}
+            </p>
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Step Preview */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <span>📋</span>
+            <span>Your Journey</span>
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-3">
+            {track.steps.map((step, index) => {
+              const isStepCompleted = progress.completedStepIds.includes(
+                step.id
+              );
+              const isCurrent =
+                !isStepCompleted &&
+                track.steps
+                  .slice(0, index)
+                  .every((s) => progress.completedStepIds.includes(s.id));
+
+              return (
+                <div
+                  key={step.id}
+                  className="flex items-center gap-4 rounded-lg border p-3"
+                >
+                  <div
+                    className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-full text-sm font-semibold ${
+                      isStepCompleted
+                        ? 'bg-green-500 text-white'
+                        : isCurrent
+                          ? 'bg-blue-500 text-white'
+                          : 'bg-muted text-muted-foreground'
+                    }`}
+                  >
+                    {isStepCompleted ? '✓' : index + 1}
+                  </div>
+                  <div className="min-w-0 flex-1">
+                    <p
+                      className={`font-medium ${
+                        isStepCompleted
+                          ? 'text-green-500'
+                          : isCurrent
+                            ? 'text-foreground'
+                            : 'text-muted-foreground'
+                      }`}
+                    >
+                      {step.title}
+                    </p>
+                  </div>
+                  {step.xpReward && (
+                    <span className="text-muted-foreground text-sm">
+                      +{step.xpReward} XP
+                    </span>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Completion Message */}
+      {isComplete && (
+        <Card className="border-green-500/50 bg-green-500/5">
+          <CardContent className="flex items-center gap-4 p-6">
+            <div className="text-4xl">🎉</div>
+            <div>
+              <h3 className="text-lg font-semibold text-green-500">
+                Onboarding Complete!
+              </h3>
+              <p className="text-muted-foreground">
+                You've completed all {totalSteps} steps. Welcome aboard!
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}