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

package/src/components/DayCalendar.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+
+interface DayCalendarProps {
+  totalDays: number;
+  currentDay: number;
+  completedDays: number[];
+}
+
+export function DayCalendar({
+  totalDays,
+  currentDay,
+  completedDays,
+}: DayCalendarProps) {
+  const days = Array.from({ length: totalDays }, (_, i) => i + 1);
+
+  return (
+    <div className="grid grid-cols-7 gap-2">
+      {days.map((day) => {
+        const isCompleted = completedDays.includes(day);
+        const isCurrent = day === currentDay;
+        const isLocked = day > currentDay;
+
+        return (
+          <div
+            key={day}
+            className={cn(
+              'flex h-12 w-12 flex-col items-center justify-center rounded-lg border text-sm font-medium transition-all',
+              isCompleted && 'border-green-500 bg-green-500/10 text-green-500',
+              isCurrent &&
+                !isCompleted &&
+                'border-violet-500 bg-violet-500/10 text-violet-500 ring-2 ring-violet-500/50',
+              isLocked && 'border-muted bg-muted/50 text-muted-foreground',
+              !isCompleted && !isCurrent && !isLocked && 'border-border bg-card'
+            )}
+          >
+            {isCompleted ? (
+              <span className="text-lg">✓</span>
+            ) : isLocked ? (
+              <span className="text-lg">🔒</span>
+            ) : (
+              <>
+                <span className="text-muted-foreground text-xs">Day</span>
+                <span>{day}</span>
+              </>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/FlashCard.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useState } from 'react';
+import { Button } from '@contractspec/lib.design-system';
+import { Card, CardContent } from '@contractspec/lib.ui-kit-web/ui/card';
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { LearningJourneyStepSpec } from '@contractspec/module.learning-journey/track-spec';
+
+interface FlashCardProps {
+  step: LearningJourneyStepSpec;
+  isCompleted: boolean;
+  isCurrent: boolean;
+  onComplete?: () => void;
+}
+
+export function FlashCard({
+  step,
+  isCompleted,
+  isCurrent,
+  onComplete,
+}: FlashCardProps) {
+  const [isFlipped, setIsFlipped] = useState(false);
+
+  return (
+    <Card
+      className={cn(
+        'relative cursor-pointer overflow-hidden transition-all duration-300',
+        isCurrent && 'ring-primary ring-2',
+        isCompleted && 'opacity-60'
+      )}
+      onClick={() => !isCompleted && setIsFlipped(!isFlipped)}
+    >
+      <CardContent className="p-6">
+        {/* Front of card */}
+        <div
+          className={cn(
+            'space-y-4 transition-opacity duration-200',
+            isFlipped ? 'opacity-0' : 'opacity-100'
+          )}
+        >
+          <div className="flex items-start justify-between">
+            <div className="flex-1">
+              <h3 className="text-lg font-semibold">{step.title}</h3>
+              {step.description && (
+                <p className="text-muted-foreground mt-1 text-sm">
+                  {step.description}
+                </p>
+              )}
+            </div>
+            {step.xpReward && (
+              <span className="rounded-full bg-green-500/10 px-2 py-1 text-xs font-semibold text-green-500">
+                +{step.xpReward} XP
+              </span>
+            )}
+          </div>
+
+          {isCompleted && (
+            <div className="flex items-center gap-2 text-green-500">
+              <span>✓</span>
+              <span className="text-sm font-medium">Completed</span>
+            </div>
+          )}
+
+          {isCurrent && !isCompleted && (
+            <p className="text-muted-foreground text-xs">
+              Tap to reveal action
+            </p>
+          )}
+        </div>
+
+        {/* Back of card (action) */}
+        {isFlipped && !isCompleted && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 bg-gradient-to-br from-violet-500/10 to-violet-600/10 p-6">
+            <p className="text-center text-sm">
+              {step.instructions ?? 'Complete this step to earn XP'}
+            </p>
+            <div className="flex gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setIsFlipped(false)}
+              >
+                Back
+              </Button>
+              <Button
+                size="sm"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onComplete?.();
+                }}
+              >
+                Mark Complete
+              </Button>
+            </div>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/MasteryRing.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+
+interface MasteryRingProps {
+  label: string;
+  percentage: number;
+  size?: 'sm' | 'md' | 'lg';
+  color?: 'green' | 'blue' | 'violet' | 'orange';
+}
+
+const sizeStyles = {
+  sm: { container: 'h-16 w-16', text: 'text-xs', ring: 48, stroke: 4 },
+  md: { container: 'h-24 w-24', text: 'text-sm', ring: 72, stroke: 6 },
+  lg: { container: 'h-32 w-32', text: 'text-base', ring: 96, stroke: 8 },
+};
+
+const colorStyles = {
+  green: 'stroke-green-500',
+  blue: 'stroke-blue-500',
+  violet: 'stroke-violet-500',
+  orange: 'stroke-orange-500',
+};
+
+export function MasteryRing({
+  label,
+  percentage,
+  size = 'md',
+  color = 'violet',
+}: MasteryRingProps) {
+  const styles = sizeStyles[size];
+  const radius = (styles.ring - styles.stroke) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const strokeDashoffset = circumference - (percentage / 100) * circumference;
+
+  return (
+    <div
+      className={cn(
+        'relative flex flex-col items-center gap-1',
+        styles.container
+      )}
+    >
+      <svg
+        className="absolute -rotate-90"
+        width={styles.ring}
+        height={styles.ring}
+        viewBox={`0 0 ${styles.ring} ${styles.ring}`}
+      >
+        {/* Background ring */}
+        <circle
+          cx={styles.ring / 2}
+          cy={styles.ring / 2}
+          r={radius}
+          fill="none"
+          strokeWidth={styles.stroke}
+          className="stroke-muted"
+        />
+        {/* Progress ring */}
+        <circle
+          cx={styles.ring / 2}
+          cy={styles.ring / 2}
+          r={radius}
+          fill="none"
+          strokeWidth={styles.stroke}
+          strokeLinecap="round"
+          strokeDasharray={circumference}
+          strokeDashoffset={strokeDashoffset}
+          className={cn('transition-all duration-500', colorStyles[color])}
+        />
+      </svg>
+      <div className="flex h-full flex-col items-center justify-center">
+        <span className={cn('font-bold', styles.text)}>
+          {Math.round(percentage)}%
+        </span>
+      </div>
+      <span className={cn('text-muted-foreground mt-1 truncate', styles.text)}>
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export { FlashCard } from './FlashCard';
+export { MasteryRing } from './MasteryRing';
+export { DayCalendar } from './DayCalendar';

package/src/docs/index.ts

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

package/src/docs/learning-journey-ui-gamified.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-gamified',
+    title: 'Learning Journey UI — Gamified',
+    summary:
+      'UI mini-app components for gamified learning: flashcards, mastery, streak/calendar.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/learning-journey-ui-gamified',
+    tags: ['learning', 'ui', 'gamified'],
+    body: `## Includes\n- Gamified mini-app shell\n- Views: overview, steps, progress, timeline\n- Components: flash card, mastery ring, day calendar\n\n## Notes\n- Compose with design system components.\n- Respect prefers-reduced-motion; keep tap targets large.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,24 @@
+const example = {
+  id: 'learning-journey-ui-gamified',
+  title: 'Learning Journey UI — Gamified',
+  summary:
+    'UI mini-app for gamified learning: flashcards, mastery ring, calendar.',
+  tags: ['learning', 'ui', 'gamified'],
+  kind: 'ui',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-ui-gamified',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-ui-gamified',
+    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 { GamifiedMiniApp } from './GamifiedMiniApp';
+
+// Views
+export { Overview, Steps, Progress, Timeline } from './views';
+
+// Components
+export { FlashCard, MasteryRing, DayCalendar } from './components';
+export { default as example } from './example';
+import './docs';

package/src/views/Overview.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import { Button } from '@contractspec/lib.design-system';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from '@contractspec/lib.ui-kit-web/ui/card';
+import {
+  XpBar,
+  StreakCounter,
+  BadgeDisplay,
+} from '@contractspec/example.learning-journey-ui-shared';
+import type { LearningViewProps } from '@contractspec/example.learning-journey-ui-shared';
+
+interface GamifiedOverviewProps extends LearningViewProps {
+  onStart?: () => void;
+}
+
+export function Overview({ track, progress, onStart }: GamifiedOverviewProps) {
+  const totalXp =
+    track.totalXp ??
+    track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) +
+      (track.completionRewards?.xpBonus ?? 0);
+
+  const completedSteps = progress.completedStepIds.length;
+  const totalSteps = track.steps.length;
+  const isComplete = completedSteps === totalSteps;
+
+  return (
+    <div className="space-y-6">
+      {/* Hero Card */}
+      <Card className="overflow-hidden bg-gradient-to-br from-violet-500/10 via-purple-500/10 to-fuchsia-500/10">
+        <CardContent className="p-6">
+          <div className="flex flex-col items-center gap-4 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-violet-500 to-purple-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">{track.description}</p>
+            </div>
+            <div className="flex items-center gap-3">
+              <StreakCounter days={progress.streakDays} size="lg" />
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Stats Grid */}
+      <div className="grid gap-4 md:grid-cols-3">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              XP Progress
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold text-violet-500">
+              {progress.xpEarned.toLocaleString()}
+            </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">
+              Steps Completed
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold">
+              {completedSteps}{' '}
+              <span className="text-muted-foreground text-lg">
+                / {totalSteps}
+              </span>
+            </div>
+            <div className="bg-muted mt-2 h-2 w-full overflow-hidden rounded-full">
+              <div
+                className="h-full bg-green-500 transition-all duration-500"
+                style={{ width: `${(completedSteps / totalSteps) * 100}%` }}
+              />
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              Badges Earned
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <BadgeDisplay badges={progress.badges} size="lg" />
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Next Step Preview */}
+      {!isComplete && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">
+              <span>🎯</span>
+              <span>Next Challenge</span>
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            {(() => {
+              const nextStep = track.steps.find(
+                (s) => !progress.completedStepIds.includes(s.id)
+              );
+              if (!nextStep) return null;
+
+              return (
+                <div className="flex items-center justify-between gap-4">
+                  <div>
+                    <h3 className="font-semibold">{nextStep.title}</h3>
+                    <p className="text-muted-foreground text-sm">
+                      {nextStep.description}
+                    </p>
+                  </div>
+                  <div className="flex items-center gap-3">
+                    {nextStep.xpReward && (
+                      <span className="rounded-full bg-green-500/10 px-3 py-1 text-sm font-semibold text-green-500">
+                        +{nextStep.xpReward} XP
+                      </span>
+                    )}
+                    <Button onClick={onStart}>Start</Button>
+                  </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">
+                Track Complete!
+              </h3>
+              <p className="text-muted-foreground">
+                You've mastered all {totalSteps} challenges and earned{' '}
+                {progress.xpEarned} XP.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}

package/src/views/Progress.tsx

@@ -0,0 +1,183 @@
+'use client';
+
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from '@contractspec/lib.ui-kit-web/ui/card';
+import {
+  XpBar,
+  BadgeDisplay,
+} from '@contractspec/example.learning-journey-ui-shared';
+import { MasteryRing } from '../components/MasteryRing';
+import type { LearningViewProps } from '@contractspec/example.learning-journey-ui-shared';
+
+export function Progress({ track, progress }: LearningViewProps) {
+  const totalXp =
+    track.totalXp ??
+    track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) +
+      (track.completionRewards?.xpBonus ?? 0);
+
+  const completedSteps = progress.completedStepIds.length;
+  const totalSteps = track.steps.length;
+  const percentComplete =
+    totalSteps > 0 ? (completedSteps / totalSteps) * 100 : 0;
+
+  // Group steps by metadata surface for mastery rings
+  const surfaces = new Map<string, { total: number; completed: number }>();
+  track.steps.forEach((step) => {
+    const surface = (step.metadata?.surface as string) ?? 'general';
+    const current = surfaces.get(surface) ?? { total: 0, completed: 0 };
+    surfaces.set(surface, {
+      total: current.total + 1,
+      completed:
+        current.completed +
+        (progress.completedStepIds.includes(step.id) ? 1 : 0),
+    });
+  });
+
+  const surfaceColors: ('green' | 'blue' | 'violet' | 'orange')[] = [
+    'green',
+    'blue',
+    'violet',
+    'orange',
+  ];
+
+  return (
+    <div className="space-y-6">
+      {/* XP Progress */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <span>⚡</span>
+            <span>Experience Points</span>
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="flex items-baseline gap-2">
+            <span className="text-4xl font-bold text-violet-500">
+              {progress.xpEarned.toLocaleString()}
+            </span>
+            <span className="text-muted-foreground">
+              / {totalXp.toLocaleString()} XP
+            </span>
+          </div>
+          <XpBar
+            current={progress.xpEarned}
+            max={totalXp}
+            showLabel={false}
+            size="lg"
+          />
+
+          {track.completionRewards?.xpBonus && percentComplete < 100 && (
+            <p className="text-muted-foreground text-sm">
+              🎁 Complete all steps for a{' '}
+              <span className="font-semibold text-green-500">
+                +{track.completionRewards.xpBonus} XP
+              </span>{' '}
+              bonus!
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Mastery Rings */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <span>🎯</span>
+            <span>Skill Mastery</span>
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="flex flex-wrap justify-center gap-6">
+            {Array.from(surfaces.entries()).map(([surface, data], index) => (
+              <MasteryRing
+                key={surface}
+                label={surface.charAt(0).toUpperCase() + surface.slice(1)}
+                percentage={(data.completed / data.total) * 100}
+                color={surfaceColors[index % surfaceColors.length]}
+                size="lg"
+              />
+            ))}
+            <MasteryRing
+              label="Overall"
+              percentage={percentComplete}
+              color="violet"
+              size="lg"
+            />
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Badges */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <span>🏅</span>
+            <span>Badges Earned</span>
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <BadgeDisplay badges={progress.badges} size="lg" maxVisible={10} />
+          {progress.badges.length === 0 && (
+            <p className="text-muted-foreground text-sm">
+              Complete the track to earn your first badge!
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Step Breakdown */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <span>📊</span>
+            <span>Step Breakdown</span>
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="space-y-2">
+            {track.steps.map((step) => {
+              const isCompleted = progress.completedStepIds.includes(step.id);
+              return (
+                <div
+                  key={step.id}
+                  className="flex items-center justify-between rounded-lg border p-3"
+                >
+                  <div className="flex items-center gap-3">
+                    <span
+                      className={
+                        isCompleted ? 'text-green-500' : 'text-muted-foreground'
+                      }
+                    >
+                      {isCompleted ? '✓' : '○'}
+                    </span>
+                    <span
+                      className={
+                        isCompleted
+                          ? 'text-foreground'
+                          : 'text-muted-foreground'
+                      }
+                    >
+                      {step.title}
+                    </span>
+                  </div>
+                  {step.xpReward && (
+                    <span
+                      className={`text-sm font-medium ${isCompleted ? 'text-green-500' : 'text-muted-foreground'}`}
+                    >
+                      {isCompleted ? '+' : ''}
+                      {step.xpReward} XP
+                    </span>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}