@contractspec/example.learning-journey-ui-shared 0.0.0-canary-20260113170453

package/src/components/StreakCounter.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { StreakCounterProps } from '../types';
+
+const sizeStyles = {
+  sm: {
+    container: 'gap-1 px-2 py-1',
+    icon: 'text-base',
+    text: 'text-xs',
+  },
+  md: {
+    container: 'gap-1.5 px-3 py-1.5',
+    icon: 'text-lg',
+    text: 'text-sm',
+  },
+  lg: {
+    container: 'gap-2 px-4 py-2',
+    icon: 'text-xl',
+    text: 'text-base',
+  },
+};
+
+export function StreakCounter({
+  days,
+  isActive = true,
+  size = 'md',
+}: StreakCounterProps) {
+  const styles = sizeStyles[size];
+
+  return (
+    <div
+      className={cn(
+        'inline-flex items-center rounded-full font-semibold',
+        styles.container,
+        isActive
+          ? 'bg-orange-500/10 text-orange-500'
+          : 'bg-muted text-muted-foreground'
+      )}
+    >
+      <span className={styles.icon} role="img" aria-label="streak">
+        🔥
+      </span>
+      <span className={styles.text}>
+        {days} {days === 1 ? 'day' : 'days'}
+      </span>
+    </div>
+  );
+}

package/src/components/ViewTabs.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { Button } from '@contractspec/lib.design-system';
+import type { ViewTabsProps, LearningView } from '../types';
+
+const VIEW_LABELS: Record<LearningView, { label: string; icon: string }> = {
+  overview: { label: 'Overview', icon: '📊' },
+  steps: { label: 'Steps', icon: '📝' },
+  progress: { label: 'Progress', icon: '📈' },
+  timeline: { label: 'Timeline', icon: '📅' },
+};
+
+const DEFAULT_VIEWS: LearningView[] = [
+  'overview',
+  'steps',
+  'progress',
+  'timeline',
+];
+
+export function ViewTabs({
+  currentView,
+  onViewChange,
+  availableViews = DEFAULT_VIEWS,
+}: ViewTabsProps) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      {availableViews.map((view) => {
+        const { label, icon } = VIEW_LABELS[view];
+        const isActive = currentView === view;
+
+        return (
+          <Button
+            key={view}
+            variant={isActive ? 'default' : 'outline'}
+            size="sm"
+            onClick={() => onViewChange(view)}
+            className="gap-1.5"
+          >
+            <span>{icon}</span>
+            <span>{label}</span>
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/XpBar.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { Progress } from '@contractspec/lib.ui-kit-web/ui/progress';
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { XpBarProps } from '../types';
+
+const sizeStyles = {
+  sm: 'h-2',
+  md: 'h-3',
+  lg: 'h-4',
+};
+
+const labelSizeStyles = {
+  sm: 'text-xs',
+  md: 'text-sm',
+  lg: 'text-base',
+};
+
+export function XpBar({
+  current,
+  max,
+  level,
+  showLabel = true,
+  size = 'md',
+}: XpBarProps) {
+  const percentage = max > 0 ? Math.min((current / max) * 100, 100) : 0;
+
+  return (
+    <div className="w-full space-y-1">
+      {showLabel && (
+        <div
+          className={cn(
+            'flex items-center justify-between',
+            labelSizeStyles[size]
+          )}
+        >
+          <span className="text-muted-foreground font-medium">
+            {level !== undefined && (
+              <span className="text-primary mr-1">Lvl {level}</span>
+            )}
+            XP
+          </span>
+          <span className="font-semibold">
+            {current.toLocaleString()} / {max.toLocaleString()}
+          </span>
+        </div>
+      )}
+      <Progress
+        value={percentage}
+        className={cn('bg-muted', sizeStyles[size])}
+      />
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { XpBar } from './XpBar';
+export { StreakCounter } from './StreakCounter';
+export { BadgeDisplay } from './BadgeDisplay';
+export { ViewTabs } from './ViewTabs';

package/src/docs/index.ts

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

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,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-ui-shared',
+    version: '1.0.0',
+    title: 'Learning Journey UI — Shared',
+    description:
+      'Shared UI components and hooks for learning journey mini-apps.',
+    kind: 'ui',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'ui', 'shared'],
+  },
+  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 },
+  },
+});
+
+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"
+  }
+}