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

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

@@ -0,0 +1,17 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.learning-journey-ui-shared',
+    title: 'Learning Journey UI — Shared',
+    summary: 'Shared UI components and hooks for learning journey mini-apps.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/learning-journey-ui-shared',
+    tags: ['learning', 'ui', 'shared'],
+    body: `## Includes\n- Hooks: useLearningProgress\n- Components: XpBar, StreakCounter, BadgeDisplay, ViewTabs\n\n## Notes\n- Keep components accessible (labels, focus, contrast).\n- Prefer design-system tokens and components.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,23 @@
+const example = {
+  id: 'learning-journey-ui-shared',
+  title: 'Learning Journey UI — Shared',
+  summary: 'Shared UI components and hooks for learning journey mini-apps.',
+  tags: ['learning', 'ui', 'shared'],
+  kind: 'ui',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-ui-shared',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-ui-shared',
+    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/hooks/index.ts

@@ -0,0 +1 @@
+export { useLearningProgress } from './useLearningProgress';

package/src/hooks/useLearningProgress.ts

@@ -0,0 +1,101 @@
+'use client';
+
+import { useState, useCallback, useMemo } from 'react';
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+import type { LearningProgressState } from '../types';
+
+/** Default progress state for a new track */
+function createDefaultProgress(trackId: string): LearningProgressState {
+  return {
+    trackId,
+    completedStepIds: [],
+    currentStepId: null,
+    xpEarned: 0,
+    streakDays: 0,
+    lastActivityDate: null,
+    badges: [],
+  };
+}
+
+/** Hook for managing learning progress state */
+export function useLearningProgress(track: LearningJourneyTrackSpec) {
+  const [progress, setProgress] = useState<LearningProgressState>(() =>
+    createDefaultProgress(track.id)
+  );
+
+  const completeStep = useCallback(
+    (stepId: string) => {
+      const step = track.steps.find((s) => s.id === stepId);
+      if (!step || progress.completedStepIds.includes(stepId)) return;
+
+      setProgress((prev) => {
+        const newCompletedIds = [...prev.completedStepIds, stepId];
+        const xpReward = step.xpReward ?? 0;
+
+        // Find next incomplete step
+        const nextStep = track.steps.find(
+          (s) => !newCompletedIds.includes(s.id)
+        );
+
+        // Check if track is complete
+        const isTrackComplete = newCompletedIds.length === track.steps.length;
+        const completionBonus = isTrackComplete
+          ? (track.completionRewards?.xpBonus ?? 0)
+          : 0;
+
+        return {
+          ...prev,
+          completedStepIds: newCompletedIds,
+          currentStepId: nextStep?.id ?? null,
+          xpEarned: prev.xpEarned + xpReward + completionBonus,
+          lastActivityDate: new Date().toISOString(),
+          badges:
+            isTrackComplete && track.completionRewards?.badgeKey
+              ? [...prev.badges, track.completionRewards.badgeKey]
+              : prev.badges,
+        };
+      });
+    },
+    [track, progress.completedStepIds]
+  );
+
+  const resetProgress = useCallback(() => {
+    setProgress(createDefaultProgress(track.id));
+  }, [track.id]);
+
+  const incrementStreak = useCallback(() => {
+    setProgress((prev) => ({
+      ...prev,
+      streakDays: prev.streakDays + 1,
+      lastActivityDate: new Date().toISOString(),
+    }));
+  }, []);
+
+  const stats = useMemo(() => {
+    const totalSteps = track.steps.length;
+    const completedSteps = progress.completedStepIds.length;
+    const percentComplete =
+      totalSteps > 0 ? Math.round((completedSteps / totalSteps) * 100) : 0;
+    const totalXp =
+      track.totalXp ??
+      track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0) +
+        (track.completionRewards?.xpBonus ?? 0);
+
+    return {
+      totalSteps,
+      completedSteps,
+      remainingSteps: totalSteps - completedSteps,
+      percentComplete,
+      totalXp,
+      isComplete: completedSteps === totalSteps,
+    };
+  }, [track, progress.completedStepIds]);
+
+  return {
+    progress,
+    stats,
+    completeStep,
+    resetProgress,
+    incrementStreak,
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// Hooks
+export { useLearningProgress } from './hooks';
+
+// Components
+export { XpBar, StreakCounter, BadgeDisplay, ViewTabs } from './components';
+
+// Types
+export type {
+  LearningView,
+  LearningProgressState,
+  LearningMiniAppProps,
+  LearningViewProps,
+  XpBarProps,
+  StreakCounterProps,
+  BadgeDisplayProps,
+  ViewTabsProps,
+} from './types';
+
+export { default as example } from './example';
+import './docs';

package/src/types.ts

@@ -0,0 +1,61 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+/** View types for learning mini-apps */
+export type LearningView = 'overview' | 'steps' | 'progress' | 'timeline';
+
+/** Progress state for a learning track */
+export interface LearningProgressState {
+  trackId: string;
+  completedStepIds: string[];
+  currentStepId: string | null;
+  xpEarned: number;
+  streakDays: number;
+  lastActivityDate: string | null;
+  badges: string[];
+}
+
+/** Props for mini-app components */
+export interface LearningMiniAppProps {
+  track: LearningJourneyTrackSpec;
+  progress: LearningProgressState;
+  onStepComplete?: (stepId: string) => void;
+  onViewChange?: (view: LearningView) => void;
+  initialView?: LearningView;
+}
+
+/** Props for view components */
+export interface LearningViewProps {
+  track: LearningJourneyTrackSpec;
+  progress: LearningProgressState;
+  onStepComplete?: (stepId: string) => void;
+}
+
+/** XP bar props */
+export interface XpBarProps {
+  current: number;
+  max: number;
+  level?: number;
+  showLabel?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/** Streak counter props */
+export interface StreakCounterProps {
+  days: number;
+  isActive?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/** Badge display props */
+export interface BadgeDisplayProps {
+  badges: string[];
+  maxVisible?: number;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/** View tabs props */
+export interface ViewTabsProps {
+  currentView: LearningView;
+  onViewChange: (view: LearningView) => void;
+  availableViews?: LearningView[];
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}