@contractspec/example.learning-journey-registry 1.44.0

package/src/docs/learning-journey-registry.docblock.ts

@@ -0,0 +1,36 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const registryDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.registry',
+    title: 'Learning Journey — Example Track Registry',
+    summary:
+      'Aggregates learning journey example tracks (Studio onboarding, Platform tour, CRM first win, Drills, Ambient Coach, Quest challenges).',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/learning-journey/registry',
+    tags: ['learning', 'registry', 'onboarding'],
+    body: `## Tracks
+- \`studio_getting_started\` (Studio onboarding)
+- \`platform_primitives_tour\` (Platform primitives)
+- \`crm_first_win\` (CRM pipeline onboarding)
+- \`drills_language_basics\` (Drills & SRS)
+- \`money_ambient_coach\`, \`coliving_ambient_coach\` (Ambient tips)
+- \`money_reset_7day\` (Quest/challenge)
+
+## Exports
+- \`learningJourneyTracks\` — raw specs
+- \`onboardingTrackCatalog\` — DTOs aligned with onboarding API
+- \`mapTrackSpecToDto\` — helper to map individual tracks
+
+## Wiring
+- Use with onboarding API contracts:
+  - \`learning.onboarding.listTracks\`
+  - \`learning.onboarding.getProgress\`
+  - \`learning.onboarding.recordEvent\`
+- Intended for registry/adapters in Studio UI or services that surface tracks.`,
+  },
+];
+
+registerDocBlocks(registryDocBlocks);

package/src/example.ts

@@ -0,0 +1,24 @@
+const example = {
+  id: 'learning-journey-registry',
+  title: 'Learning Journey Registry',
+  summary:
+    'Registry of learning journey tracks + presentations + UI mini-app bindings.',
+  tags: ['learning', 'journey', 'registry'],
+  kind: 'library',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-registry',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-registry',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;

package/src/index.ts

@@ -0,0 +1,8 @@
+import './docs';
+
+export * from './tracks';
+export * from './api';
+export * from './presentations';
+export * from './learning-journey-registry.feature';
+export * from './ui';
+export { default as example } from './example';

package/src/learning-journey-registry.feature.ts

@@ -0,0 +1,64 @@
+/**
+ * Learning Journey Registry Feature Module Specification
+ *
+ * Defines the feature module for the learning journey registry.
+ */
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+
+/**
+ * Learning Journey Registry feature module that bundles
+ * the shared presentations for learning journey tracks.
+ */
+export const LearningJourneyRegistryFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'learning-journey-registry',
+    version: 1,
+    title: 'Learning Journey Registry',
+    description:
+      'Shared registry and presentations for learning journey tracks',
+    domain: 'learning-journey',
+    owners: ['@learning-team'],
+    tags: ['learning', 'journey', 'onboarding', 'registry'],
+    stability: 'experimental',
+  },
+
+  // No operations in the registry - it's presentation-only
+  operations: [],
+
+  // Events emitted by this feature
+  events: [],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'learning.journey.track_list', version: 1 },
+    { key: 'learning.journey.track_detail', version: 1 },
+    { key: 'learning.journey.progress_widget', version: 1 },
+  ],
+
+  // No op to presentation links for registry
+  opToPresentation: [],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    {
+      key: 'learning.journey.track_list',
+      version: 1,
+      targets: ['react', 'markdown'],
+    },
+    {
+      key: 'learning.journey.track_detail',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'learning.journey.progress_widget',
+      version: 1,
+      targets: ['react'],
+    },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [{ key: 'identity', version: 1 }],
+  },
+};

package/src/presentations/index.ts

@@ -0,0 +1,69 @@
+import type {
+  PresentationSpecMeta,
+  PresentationSpec,
+} from '@contractspec/lib.contracts';
+import { StabilityEnum } from '@contractspec/lib.contracts';
+
+const baseMeta: Pick<
+  PresentationSpecMeta,
+  'domain' | 'owners' | 'tags' | 'title' | 'stability' | 'goal' | 'context'
+> = {
+  domain: 'learning-journey',
+  title: 'Learning Journey',
+  owners: ['@learning-team'] as string[],
+  tags: ['learning', 'journey', 'onboarding'] as string[],
+  stability: StabilityEnum.Experimental,
+  goal: 'Progress through learning tracks',
+  context: 'Learning journey section',
+};
+
+export const LearningTrackListPresentation: PresentationSpec = {
+  meta: {
+    key: 'learning.journey.track_list',
+    version: 1,
+    description: 'List of learning journeys available to the learner.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackList',
+  },
+  targets: ['react', 'markdown'],
+};
+
+export const LearningTrackDetailPresentation: PresentationSpec = {
+  meta: {
+    key: 'learning.journey.track_detail',
+    version: 1,
+    description: 'Track detail with steps and progress state.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackDetail',
+  },
+  targets: ['react', 'markdown', 'application/json'],
+};
+
+export const LearningTrackProgressWidgetPresentation: PresentationSpec = {
+  meta: {
+    key: 'learning.journey.progress_widget',
+    version: 1,
+    description: 'Compact widget showing progress for active track.',
+    ...baseMeta,
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'LearningTrackProgressWidget',
+  },
+  targets: ['react'],
+};
+
+export const learningJourneyPresentations = [
+  LearningTrackListPresentation,
+  LearningTrackDetailPresentation,
+  LearningTrackProgressWidgetPresentation,
+];

package/src/progress-store.ts

@@ -0,0 +1,39 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+import type { TrackProgress } from './api-types';
+
+export const progressStore = new Map<string, Map<string, TrackProgress>>();
+
+export const getTrackResolver =
+  (tracks: LearningJourneyTrackSpec[]) =>
+  (trackId: string): LearningJourneyTrackSpec | undefined =>
+    tracks.find((t) => t.id === trackId);
+
+export const getLearnerTracks = (learnerId: string) => {
+  const existing = progressStore.get(learnerId);
+  if (existing) return existing;
+  const map = new Map<string, TrackProgress>();
+  progressStore.set(learnerId, map);
+  return map;
+};
+
+export const initProgress = (
+  learnerId: string,
+  track: LearningJourneyTrackSpec
+): TrackProgress => ({
+  learnerId,
+  trackId: track.id,
+  progress: 0,
+  isCompleted: false,
+  xpEarned: 0,
+  steps: track.steps.map((step) => ({
+    id: step.id,
+    status: 'PENDING',
+    xpEarned: 0,
+    occurrences: 0,
+    masteryCount: 0,
+  })),
+  startedAt: undefined,
+  completedAt: undefined,
+  lastActivityAt: undefined,
+});

package/src/tracks.ts

@@ -0,0 +1,91 @@
+import type {
+  LearningJourneyStepSpec,
+  LearningJourneyTrackSpec,
+  StepAvailabilitySpec,
+  StepCompletionConditionSpec,
+} from '@contractspec/module.learning-journey/track-spec';
+import { crmLearningTracks } from '@contractspec/example.learning-journey-crm-onboarding/track';
+import { drillTracks } from '@contractspec/example.learning-journey-duo-drills/track';
+import { ambientCoachTracks } from '@contractspec/example.learning-journey-ambient-coach/track';
+import { questTracks } from '@contractspec/example.learning-journey-quest-challenges/track';
+import { platformLearningTracks } from '@contractspec/example.learning-journey-platform-tour/track';
+import { studioLearningTracks } from '@contractspec/example.learning-journey-studio-onboarding/track';
+
+export interface OnboardingStepDto {
+  id: string;
+  title: string;
+  description?: string;
+  completionEvent: string;
+  completionCondition?: StepCompletionConditionSpec;
+  xpReward?: number;
+  isRequired?: boolean;
+  canSkip?: boolean;
+  actionUrl?: string;
+  actionLabel?: string;
+  availability?: StepAvailabilitySpec;
+  metadata?: Record<string, unknown>;
+}
+
+export interface OnboardingTrackDto {
+  id: string;
+  name: string;
+  description?: string;
+  productId?: string;
+  targetUserSegment?: string;
+  targetRole?: string;
+  totalXp?: number;
+  streakRule?: LearningJourneyTrackSpec['streakRule'];
+  completionRewards?: LearningJourneyTrackSpec['completionRewards'];
+  steps: OnboardingStepDto[];
+  metadata?: Record<string, unknown>;
+}
+
+const mapStep = (step: LearningJourneyStepSpec): OnboardingStepDto => ({
+  id: step.id,
+  title: step.title,
+  description: step.description,
+  completionEvent: step.completion.eventName,
+  completionCondition: step.completion,
+  xpReward: step.xpReward,
+  isRequired: step.isRequired,
+  canSkip: step.canSkip,
+  actionUrl: step.actionUrl,
+  actionLabel: step.actionLabel,
+  availability: step.availability,
+  metadata: step.metadata,
+});
+
+export const mapTrackSpecToDto = (
+  track: LearningJourneyTrackSpec
+): OnboardingTrackDto => ({
+  id: track.id,
+  name: track.name,
+  description: track.description,
+  productId: track.productId,
+  targetUserSegment: track.targetUserSegment,
+  targetRole: track.targetRole,
+  totalXp: track.totalXp,
+  streakRule: track.streakRule,
+  completionRewards: track.completionRewards,
+  steps: track.steps.map(mapStep),
+  metadata: track.metadata,
+});
+
+export const learningJourneyTracks: LearningJourneyTrackSpec[] = [
+  ...studioLearningTracks,
+  ...platformLearningTracks,
+  ...crmLearningTracks,
+  ...drillTracks,
+  ...ambientCoachTracks,
+  ...questTracks,
+];
+
+export const onboardingTrackCatalog: OnboardingTrackDto[] =
+  learningJourneyTracks.map(mapTrackSpecToDto);
+
+export {
+  studioLearningTracks,
+  platformLearningTracks,
+  crmLearningTracks,
+  mapStep,
+};

package/src/ui/LearningMiniApp.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+import { useMemo } from 'react';
+import { GamifiedMiniApp } from '@contractspec/example.learning-journey-ui-gamified';
+import { OnboardingMiniApp } from '@contractspec/example.learning-journey-ui-onboarding';
+import { CoachingMiniApp } from '@contractspec/example.learning-journey-ui-coaching';
+import type { LearningView } from '@contractspec/example.learning-journey-ui-shared';
+import { learningJourneyTracks } from '../tracks';
+
+/** Template IDs that map to learning journey tracks */
+type LearningTemplateId =
+  | 'learning-journey-duo-drills'
+  | 'learning-journey-quest-challenges'
+  | 'learning-journey-studio-onboarding'
+  | 'learning-journey-platform-tour'
+  | 'learning-journey-ambient-coach'
+  | 'learning-journey-crm-onboarding';
+
+/** Map template IDs to track IDs */
+const TEMPLATE_TO_TRACK: Record<LearningTemplateId, string> = {
+  'learning-journey-duo-drills': 'drills_language_basics',
+  'learning-journey-quest-challenges': 'money_reset_7day',
+  'learning-journey-studio-onboarding': 'studio_getting_started',
+  'learning-journey-platform-tour': 'platform_tour',
+  'learning-journey-ambient-coach': 'money_ambient_coach',
+  'learning-journey-crm-onboarding': 'crm_first_win',
+};
+
+/** Map template IDs to mini-app type */
+const TEMPLATE_TO_APP_TYPE: Record<
+  LearningTemplateId,
+  'gamified' | 'onboarding' | 'coaching'
+> = {
+  'learning-journey-duo-drills': 'gamified',
+  'learning-journey-quest-challenges': 'gamified',
+  'learning-journey-studio-onboarding': 'onboarding',
+  'learning-journey-platform-tour': 'onboarding',
+  'learning-journey-ambient-coach': 'coaching',
+  'learning-journey-crm-onboarding': 'coaching',
+};
+
+interface LearningMiniAppProps {
+  templateId: string;
+  initialView?: LearningView;
+  onViewChange?: (view: LearningView) => void;
+}
+
+/** Router component that picks the correct mini-app based on template ID */
+export function LearningMiniApp({
+  templateId,
+  initialView = 'overview',
+  onViewChange,
+}: LearningMiniAppProps) {
+  // Find the track for this template
+  const track = useMemo(() => {
+    const trackId = TEMPLATE_TO_TRACK[templateId as LearningTemplateId];
+    if (!trackId) return null;
+    return learningJourneyTracks.find((t) => t.id === trackId);
+  }, [templateId]);
+
+  // Determine app type
+  const appType = TEMPLATE_TO_APP_TYPE[templateId as LearningTemplateId];
+
+  if (!track) {
+    return (
+      <div className="rounded-lg border border-amber-500/50 bg-amber-500/10 p-6 text-center">
+        <p className="text-amber-500">
+          Unknown learning template: {templateId}
+        </p>
+      </div>
+    );
+  }
+
+  // Render the appropriate mini-app
+  switch (appType) {
+    case 'gamified':
+      return (
+        <GamifiedMiniApp
+          track={track}
+          initialView={initialView}
+          onViewChange={onViewChange}
+        />
+      );
+    case 'onboarding':
+      return (
+        <OnboardingMiniApp
+          track={track}
+          initialView={initialView}
+          onViewChange={onViewChange}
+        />
+      );
+    case 'coaching':
+      return (
+        <CoachingMiniApp
+          track={track}
+          initialView={initialView}
+          onViewChange={onViewChange}
+        />
+      );
+    default:
+      return (
+        <div className="rounded-lg border border-red-500/50 bg-red-500/10 p-6 text-center">
+          <p className="text-red-500">
+            Unknown app type for template: {templateId}
+          </p>
+        </div>
+      );
+  }
+}
+
+/** Check if a template ID is a learning journey template */
+export function isLearningTemplate(
+  templateId: string
+): templateId is LearningTemplateId {
+  return templateId in TEMPLATE_TO_TRACK;
+}
+
+/** Get all learning template IDs */
+export function getLearningTemplateIds(): LearningTemplateId[] {
+  return Object.keys(TEMPLATE_TO_TRACK) as LearningTemplateId[];
+}

package/src/ui/index.ts

@@ -0,0 +1,5 @@
+export {
+  LearningMiniApp,
+  isLearningTemplate,
+  getLearningTemplateIds,
+} from './LearningMiniApp';

package/tsconfig.json

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