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

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@contractspec/example.learning-journey-ui-coaching",
+  "version": "1.44.0",
+  "description": "Contextual coaching UI with tip cards and engagement tracking.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./CoachingMiniApp": "./dist/CoachingMiniApp.js",
+    "./components": "./dist/components/index.js",
+    "./components/EngagementMeter": "./dist/components/EngagementMeter.js",
+    "./components/TipCard": "./dist/components/TipCard.js",
+    "./components/TipFeed": "./dist/components/TipFeed.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/learning-journey-ui-coaching.docblock": "./dist/docs/learning-journey-ui-coaching.docblock.js",
+    "./example": "./dist/example.js",
+    "./views": "./dist/views/index.js",
+    "./views/Overview": "./dist/views/Overview.js",
+    "./views/Progress": "./dist/views/Progress.js",
+    "./views/Steps": "./dist/views/Steps.js",
+    "./views/Timeline": "./dist/views/Timeline.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/lib.schema": "1.44.0",
+    "@contractspec/lib.contracts": "1.44.0",
+    "@contractspec/example.learning-journey-ui-shared": "1.44.0",
+    "@contractspec/example.learning-journey-ambient-coach": "1.44.0",
+    "@contractspec/example.learning-journey-crm-onboarding": "1.44.0",
+    "@contractspec/module.learning-journey": "1.44.0",
+    "@contractspec/lib.design-system": "1.44.0",
+    "@contractspec/lib.ui-kit-web": "1.44.0",
+    "react": "19.2.3"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.44.0",
+    "@contractspec/tool.typescript": "1.44.0",
+    "@types/react": "^19.1.6",
+    "tsdown": "^0.18.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3"
+  },
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./example": "./dist/example.js",
+      "./docs": "./dist/docs/index.js",
+      "./views": "./dist/views/index.js",
+      "./components": "./dist/components/index.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/learning-journey-ui-coaching"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/CoachingMiniApp.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import { useState, useCallback } from 'react';
+import { Card, CardContent } from '@contractspec/lib.ui-kit-web/ui/card';
+import {
+  ViewTabs,
+  useLearningProgress,
+  type LearningView,
+  type LearningMiniAppProps,
+} from '@contractspec/example.learning-journey-ui-shared';
+import { Overview } from './views/Overview';
+import { Steps } from './views/Steps';
+import { Progress } from './views/Progress';
+import { Timeline } from './views/Timeline';
+
+type CoachingMiniAppProps = Omit<LearningMiniAppProps, 'progress'> & {
+  progress?: LearningMiniAppProps['progress'];
+};
+
+export function CoachingMiniApp({
+  track,
+  progress: externalProgress,
+  onStepComplete: externalOnStepComplete,
+  onViewChange,
+  initialView = 'overview',
+}: CoachingMiniAppProps) {
+  const [currentView, setCurrentView] = useState<LearningView>(initialView);
+
+  // Use internal progress if not provided externally
+  const { progress: internalProgress, completeStep: internalCompleteStep } =
+    useLearningProgress(track);
+
+  const progress = externalProgress ?? internalProgress;
+
+  const handleViewChange = useCallback(
+    (view: LearningView) => {
+      setCurrentView(view);
+      onViewChange?.(view);
+    },
+    [onViewChange]
+  );
+
+  const handleStepComplete = useCallback(
+    (stepId: string) => {
+      if (externalOnStepComplete) {
+        externalOnStepComplete(stepId);
+      } else {
+        internalCompleteStep(stepId);
+      }
+    },
+    [externalOnStepComplete, internalCompleteStep]
+  );
+
+  const handleStartFromOverview = useCallback(() => {
+    setCurrentView('steps');
+    onViewChange?.('steps');
+  }, [onViewChange]);
+
+  const renderView = () => {
+    const viewProps = {
+      track,
+      progress,
+      onStepComplete: handleStepComplete,
+    };
+
+    switch (currentView) {
+      case 'overview':
+        return <Overview {...viewProps} onStart={handleStartFromOverview} />;
+      case 'steps':
+        return <Steps {...viewProps} />;
+      case 'progress':
+        return <Progress {...viewProps} />;
+      case 'timeline':
+        return <Timeline {...viewProps} />;
+      default:
+        return <Overview {...viewProps} onStart={handleStartFromOverview} />;
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Navigation */}
+      <Card>
+        <CardContent className="p-4">
+          <ViewTabs currentView={currentView} onViewChange={handleViewChange} />
+        </CardContent>
+      </Card>
+
+      {/* Current View */}
+      {renderView()}
+    </div>
+  );
+}

package/src/components/EngagementMeter.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+interface EngagementMeterProps {
+  acknowledged: number;
+  actioned: number;
+  pending: number;
+  streak?: number;
+}
+
+export function EngagementMeter({
+  acknowledged,
+  actioned,
+  pending,
+  streak = 0,
+}: EngagementMeterProps) {
+  const total = acknowledged + actioned + pending;
+  const actionedPercent = total > 0 ? (actioned / total) * 100 : 0;
+  const acknowledgedPercent = total > 0 ? (acknowledged / total) * 100 : 0;
+
+  return (
+    <div className="space-y-4">
+      {/* Donut chart */}
+      <div className="flex items-center justify-center">
+        <div className="relative h-32 w-32">
+          <svg className="h-full w-full -rotate-90" viewBox="0 0 100 100">
+            {/* Background */}
+            <circle
+              cx="50"
+              cy="50"
+              r="40"
+              fill="none"
+              strokeWidth="12"
+              className="stroke-muted"
+            />
+            {/* Actioned (green) */}
+            <circle
+              cx="50"
+              cy="50"
+              r="40"
+              fill="none"
+              strokeWidth="12"
+              strokeLinecap="round"
+              strokeDasharray={`${actionedPercent * 2.51} 251`}
+              className="stroke-green-500 transition-all duration-500"
+            />
+            {/* Acknowledged (amber) - offset by actioned */}
+            <circle
+              cx="50"
+              cy="50"
+              r="40"
+              fill="none"
+              strokeWidth="12"
+              strokeLinecap="round"
+              strokeDasharray={`${acknowledgedPercent * 2.51} 251`}
+              strokeDashoffset={`${-actionedPercent * 2.51}`}
+              className="stroke-amber-500 transition-all duration-500"
+            />
+          </svg>
+          <div className="absolute inset-0 flex flex-col items-center justify-center">
+            <span className="text-2xl font-bold">{total}</span>
+            <span className="text-muted-foreground text-xs">tips</span>
+          </div>
+        </div>
+      </div>
+
+      {/* Legend */}
+      <div className="flex justify-center gap-4 text-sm">
+        <div className="flex items-center gap-1.5">
+          <div className="h-3 w-3 rounded-full bg-green-500" />
+          <span>Actioned ({actioned})</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <div className="h-3 w-3 rounded-full bg-amber-500" />
+          <span>Acknowledged ({acknowledged})</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <div className="bg-muted h-3 w-3 rounded-full" />
+          <span>Pending ({pending})</span>
+        </div>
+      </div>
+
+      {/* Streak */}
+      {streak > 0 && (
+        <div className="flex items-center justify-center gap-2 rounded-lg bg-orange-500/10 px-4 py-2">
+          <span className="text-xl">🔥</span>
+          <span className="font-semibold text-orange-500">
+            {streak} day engagement streak!
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/TipCard.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+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 TipCardProps {
+  step: LearningJourneyStepSpec;
+  isCompleted: boolean;
+  isCurrent: boolean;
+  onComplete?: () => void;
+  onDismiss?: () => void;
+}
+
+const TIP_ICONS: Record<string, string> = {
+  cash_buffer_too_high: '💰',
+  no_savings_goal: '🎯',
+  irregular_savings: '📅',
+  noise_late_evening: '🔇',
+  guest_frequency_high: '👥',
+  shared_space_conflicts: '🏠',
+  default: '💡',
+};
+
+export function TipCard({
+  step,
+  isCompleted,
+  isCurrent,
+  onComplete,
+  onDismiss,
+}: TipCardProps) {
+  const tipId = (step.metadata?.tipId as string) ?? 'default';
+  const icon = TIP_ICONS[tipId] ?? TIP_ICONS.default;
+
+  return (
+    <Card
+      className={cn(
+        'transition-all',
+        isCompleted && 'opacity-60',
+        isCurrent && 'ring-2 ring-amber-500'
+      )}
+    >
+      <CardContent className="p-4">
+        <div className="flex gap-4">
+          {/* Icon */}
+          <div
+            className={cn(
+              'flex h-12 w-12 shrink-0 items-center justify-center rounded-xl text-2xl',
+              isCompleted
+                ? 'bg-green-500/10'
+                : isCurrent
+                  ? 'bg-amber-500/10'
+                  : 'bg-muted'
+            )}
+          >
+            {isCompleted ? '✓' : icon}
+          </div>
+
+          {/* Content */}
+          <div className="min-w-0 flex-1">
+            <div className="flex items-start justify-between gap-2">
+              <h4 className="font-semibold">{step.title}</h4>
+              {step.xpReward && (
+                <span
+                  className={cn(
+                    'shrink-0 rounded-full px-2 py-0.5 text-xs font-semibold',
+                    isCompleted
+                      ? 'bg-green-500/10 text-green-500'
+                      : 'bg-amber-500/10 text-amber-500'
+                  )}
+                >
+                  +{step.xpReward} XP
+                </span>
+              )}
+            </div>
+            <p className="text-muted-foreground mt-1 text-sm">
+              {step.description}
+            </p>
+
+            {/* Actions */}
+            {!isCompleted && (
+              <div className="mt-3 flex flex-wrap gap-2">
+                <Button size="sm" onClick={onComplete}>
+                  Take Action
+                </Button>
+                <Button variant="outline" size="sm" onClick={onDismiss}>
+                  Dismiss
+                </Button>
+              </div>
+            )}
+
+            {isCompleted && (
+              <p className="mt-2 text-sm text-green-500">✓ Tip acknowledged</p>
+            )}
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/TipFeed.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+import { cn } from '@contractspec/lib.ui-kit-web/ui/utils';
+import type { LearningJourneyStepSpec } from '@contractspec/module.learning-journey/track-spec';
+
+interface TipFeedItem {
+  step: LearningJourneyStepSpec;
+  isCompleted: boolean;
+  completedAt?: string;
+}
+
+interface TipFeedProps {
+  items: TipFeedItem[];
+}
+
+const TIP_ICONS: Record<string, string> = {
+  cash_buffer_too_high: '💰',
+  no_savings_goal: '🎯',
+  irregular_savings: '📅',
+  noise_late_evening: '🔇',
+  guest_frequency_high: '👥',
+  shared_space_conflicts: '🏠',
+  default: '💡',
+};
+
+export function TipFeed({ items }: TipFeedProps) {
+  if (items.length === 0) {
+    return (
+      <div className="text-muted-foreground py-8 text-center">
+        No tips yet. Start engaging with coaching tips!
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative">
+      {/* Timeline line */}
+      <div className="bg-border absolute top-0 left-4 h-full w-0.5" />
+
+      {/* Feed items */}
+      <div className="space-y-4">
+        {items.map((item) => {
+          const tipId = (item.step.metadata?.tipId as string) ?? 'default';
+          const icon = TIP_ICONS[tipId] ?? TIP_ICONS.default;
+
+          return (
+            <div key={item.step.id} className="relative flex gap-4 pl-2">
+              {/* Node */}
+              <div
+                className={cn(
+                  'relative z-10 flex h-8 w-8 shrink-0 items-center justify-center rounded-full text-sm',
+                  item.isCompleted
+                    ? 'bg-green-500 text-white'
+                    : 'bg-muted text-muted-foreground'
+                )}
+              >
+                {item.isCompleted ? '✓' : icon}
+              </div>
+
+              {/* Content */}
+              <div className="bg-card flex-1 rounded-lg border p-3">
+                <div className="flex items-start justify-between gap-2">
+                  <div>
+                    <p className="font-medium">{item.step.title}</p>
+                    <p className="text-muted-foreground mt-0.5 text-sm">
+                      {item.step.description}
+                    </p>
+                  </div>
+                  {item.step.xpReward && (
+                    <span
+                      className={cn(
+                        'shrink-0 text-xs font-medium',
+                        item.isCompleted
+                          ? 'text-green-500'
+                          : 'text-muted-foreground'
+                      )}
+                    >
+                      +{item.step.xpReward} XP
+                    </span>
+                  )}
+                </div>
+
+                {/* Timestamp */}
+                <div className="text-muted-foreground mt-2 flex items-center gap-2 text-xs">
+                  {item.isCompleted ? (
+                    <span className="text-green-500">
+                      ✓ Completed
+                      {item.completedAt && ` • ${item.completedAt}`}
+                    </span>
+                  ) : (
+                    <span>Pending action</span>
+                  )}
+                </div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export { TipCard } from './TipCard';
+export { EngagementMeter } from './EngagementMeter';
+export { TipFeed } from './TipFeed';

package/src/docs/index.ts

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

package/src/docs/learning-journey-ui-coaching.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-coaching',
+    title: 'Learning Journey UI — Coaching',
+    summary: 'UI mini-app components for coaching: tips, engagement, progress.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/learning-journey-ui-coaching',
+    tags: ['learning', 'ui', 'coaching'],
+    body: `## Includes\n- Coaching mini-app shell\n- Views: overview, steps, progress, timeline\n- Components: tip card, engagement meter, tip feed\n\n## Notes\n- Compose using design system components.\n- Keep accessibility and mobile-friendly tap targets.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,24 @@
+const example = {
+  id: 'learning-journey-ui-coaching',
+  title: 'Learning Journey UI — Coaching',
+  summary:
+    'UI mini-app for coaching patterns: tips, engagement meter, progress.',
+  tags: ['learning', 'ui', 'coaching'],
+  kind: 'ui',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-ui-coaching',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-ui-coaching',
+    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 { CoachingMiniApp } from './CoachingMiniApp';
+
+// Views
+export { Overview, Steps, Progress, Timeline } from './views';
+
+// Components
+export { TipCard, EngagementMeter, TipFeed } from './components';
+export { default as example } from './example';
+import './docs';

package/src/views/Overview.tsx

@@ -0,0 +1,157 @@
+'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,
+} from '@contractspec/example.learning-journey-ui-shared';
+import { TipCard } from '../components/TipCard';
+import type { LearningViewProps } from '@contractspec/example.learning-journey-ui-shared';
+
+interface CoachingOverviewProps extends LearningViewProps {
+  onStart?: () => void;
+}
+
+export function Overview({
+  track,
+  progress,
+  onStepComplete,
+  onStart,
+}: CoachingOverviewProps) {
+  const totalXp =
+    track.totalXp ?? track.steps.reduce((sum, s) => sum + (s.xpReward ?? 0), 0);
+
+  const completedSteps = progress.completedStepIds.length;
+  const totalSteps = track.steps.length;
+  const pendingSteps = totalSteps - completedSteps;
+
+  // Get active tips (incomplete ones)
+  const activeTips = track.steps
+    .filter((s) => !progress.completedStepIds.includes(s.id))
+    .slice(0, 3);
+
+  return (
+    <div className="space-y-6">
+      {/* Header Card */}
+      <Card className="overflow-hidden bg-gradient-to-br from-amber-500/10 via-orange-500/10 to-red-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-16 w-16 items-center justify-center rounded-2xl bg-gradient-to-br from-amber-500 to-orange-600 text-3xl shadow-lg">
+              💡
+            </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-4">
+              <StreakCounter days={progress.streakDays} size="lg" />
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Quick Stats */}
+      <div className="grid gap-4 md:grid-cols-3">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              Active Tips
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold text-amber-500">
+              {pendingSteps}
+            </div>
+            <p className="text-muted-foreground text-sm">tips for you today</p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-muted-foreground text-sm font-medium">
+              Tips Actioned
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="text-3xl font-bold text-green-500">
+              {completedSteps}
+            </div>
+            <p className="text-muted-foreground text-sm">
+              out of {totalSteps} total
+            </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-orange-500">
+              {progress.xpEarned}
+            </div>
+            <XpBar
+              current={progress.xpEarned}
+              max={totalXp}
+              showLabel={false}
+              size="sm"
+            />
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Active Tips Preview */}
+      {activeTips.length > 0 && (
+        <Card>
+          <CardHeader className="flex flex-row items-center justify-between">
+            <CardTitle className="flex items-center gap-2">
+              <span>💡</span>
+              <span>Tips for You</span>
+            </CardTitle>
+            {activeTips.length < pendingSteps && (
+              <Button variant="outline" size="sm" onClick={onStart}>
+                View All ({pendingSteps})
+              </Button>
+            )}
+          </CardHeader>
+          <CardContent className="space-y-3">
+            {activeTips.map((step) => (
+              <TipCard
+                key={step.id}
+                step={step}
+                isCompleted={false}
+                isCurrent={step.id === activeTips[0]?.id}
+                onComplete={() => onStepComplete?.(step.id)}
+              />
+            ))}
+          </CardContent>
+        </Card>
+      )}
+
+      {/* All Complete */}
+      {pendingSteps === 0 && (
+        <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">
+                All Tips Actioned!
+              </h3>
+              <p className="text-muted-foreground">
+                Great job! You've addressed all {totalSteps} coaching tips.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}