@forwardimpact/pathway 0.21.0 → 0.23.0

package/src/lib/state.js

@@ -1,21 +1,19 @@
 /**
  * Application state management
+ *
+ * Uses generic store from @forwardimpact/libui/state
+ * with Pathway-specific state shape and accessors.
  */
 
-/**
- * @typedef {Object} AppState
- * @property {Object} data - Loaded data from YAML files
- * @property {Object} ui - UI state
- */
+import { createStore } from "@forwardimpact/libui/state";
 
-/** @type {AppState} */
-const state = {
+const store = createStore({
   data: {
     skills: [],
     behaviours: [],
     disciplines: [],
     tracks: [],
-    grades: [],
+    levels: [],
     drivers: [],
     questions: {},
     capabilities: [],
@@ -31,52 +29,22 @@ const state = {
       behaviours: { search: "" },
       disciplines: { search: "" },
       tracks: { search: "" },
-      grades: { search: "" },
+      levels: { search: "" },
       drivers: { search: "" },
     },
   },
-};
-
-/** @type {Set<Function>} */
-const listeners = new Set();
-
-/**
- * Get the current state
- * @returns {AppState}
- */
-export function getState() {
-  return state;
-}
-
-/**
- * Get a specific path from state
- * @param {string} path - Dot-notation path (e.g., 'data.skills')
- * @returns {*}
- */
-export function getStatePath(path) {
-  return path.split(".").reduce((obj, key) => obj?.[key], state);
-}
+});
 
-/**
- * Update state at a specific path
- * @param {string} path - Dot-notation path
- * @param {*} value - New value
- */
-export function updateState(path, value) {
-  const keys = path.split(".");
-  const lastKey = keys.pop();
-  const target = keys.reduce((obj, key) => obj[key], state);
-  target[lastKey] = value;
-  notifyListeners();
-}
+export const { getState, getStatePath, updateState, subscribe } = store;
 
 /**
  * Merge data into state
  * @param {Object} data - Data to merge
  */
 export function setData(data) {
+  const state = getState();
   Object.assign(state.data, data, { loaded: true, error: null });
-  notifyListeners();
+  updateState("data", state.data);
 }
 
 /**
@@ -84,25 +52,7 @@ export function setData(data) {
  * @param {Error} error
  */
 export function setError(error) {
-  state.data.error = error.message;
-  notifyListeners();
-}
-
-/**
- * Subscribe to state changes
- * @param {Function} listener
- * @returns {Function} Unsubscribe function
- */
-export function subscribe(listener) {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-/**
- * Notify all listeners of state change
- */
-function notifyListeners() {
-  listeners.forEach((listener) => listener(state));
+  updateState("data.error", error.message);
 }
 
 /**
@@ -112,9 +62,10 @@ function notifyListeners() {
  * @param {*} value - Filter value
  */
 export function setFilter(entity, filterKey, value) {
+  const state = getState();
   if (state.ui.filters[entity]) {
     state.ui.filters[entity][filterKey] = value;
-    notifyListeners();
+    updateState("ui.filters", state.ui.filters);
   }
 }
 
@@ -124,7 +75,7 @@ export function setFilter(entity, filterKey, value) {
  * @returns {Object}
  */
 export function getFilters(entity) {
-  return state.ui.filters[entity] || {};
+  return getState().ui.filters[entity] || {};
 }
 
 /**
@@ -140,7 +91,7 @@ export function getFilters(entity) {
  * @returns {Branding}
  */
 export function getBranding() {
-  const { framework } = state.data;
+  const { framework } = getState().data;
   return {
     title: framework.title || "Engineering Pathway",
     tag: framework.tag || "#BenchTools",

package/src/lib/utils.js

@@ -1,14 +1,7 @@
 /**
  * General utility functions
+ *
+ * Re-exports from @forwardimpact/libui/utils.
  */
 
-/**
- * Get an array of items by their IDs
- * @param {Array} items - Array of items with id property
- * @param {string[]} ids - Array of IDs to find
- * @returns {Array} - Found items, filtered to remove nulls
- */
-export function getItemsByIds(items, ids) {
-  if (!ids) return [];
-  return ids.map((id) => items.find((item) => item.id === id)).filter(Boolean);
-}
+export { getItemsByIds } from "@forwardimpact/libui/utils";

package/src/lib/yaml-loader.js

@@ -1,56 +1,21 @@
 /**
  * Browser-compatible YAML loading
  *
- * Uses _index.yaml files to discover files in directory structures.
- * These index files are auto-generated by the CLI (npx pathway --generate-index).
+ * Generic utilities from @forwardimpact/libui/yaml-loader,
+ * plus Pathway-specific entity loaders.
  */
 
-import { parse as parseYaml } from "https://cdn.jsdelivr.net/npm/yaml@2.3.4/+esm";
+export {
+  loadYamlFile,
+  tryLoadYamlFile,
+  loadDirIndex,
+} from "@forwardimpact/libui/yaml-loader";
 
-/**
- * Load and parse a YAML file
- * @param {string} path - Path to the YAML file
- * @returns {Promise<*>}
- */
-export async function loadYamlFile(path) {
-  const response = await fetch(path);
-  if (!response.ok) {
-    throw new Error(
-      `Failed to load ${path}: ${response.status} ${response.statusText}`,
-    );
-  }
-  const text = await response.text();
-  return parseYaml(text);
-}
-
-/**
- * Try to load a YAML file, return null if not found
- * @param {string} path - Path to the YAML file
- * @returns {Promise<*|null>}
- */
-async function tryLoadYamlFile(path) {
-  const response = await fetch(path);
-  if (response.status === 404) {
-    return null;
-  }
-  if (!response.ok) {
-    throw new Error(
-      `Failed to load ${path}: ${response.status} ${response.statusText}`,
-    );
-  }
-  const text = await response.text();
-  return parseYaml(text);
-}
-
-/**
- * Load directory index (list of file IDs)
- * @param {string} dir - Directory path
- * @returns {Promise<string[]>} Array of file IDs
- */
-async function loadDirIndex(dir) {
-  const index = await loadYamlFile(`${dir}/_index.yaml`);
-  return index.files || [];
-}
+import {
+  loadYamlFile,
+  tryLoadYamlFile,
+  loadDirIndex,
+} from "@forwardimpact/libui/yaml-loader";
 
 /**
  * Load skills from capability files
@@ -86,7 +51,7 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           name,
           capability: capabilityId, // Add capability from parent
           description: human.description,
-          levelDescriptions: human.levelDescriptions,
+          proficiencyDescriptions: human.proficiencyDescriptions,
           // Include isHumanOnly flag for agent filtering (defaults to false)
           ...(isHumanOnly && { isHumanOnly }),
           ...(agent && { agent }),
@@ -115,23 +80,18 @@ async function loadDisciplinesFromDir(disciplinesDir) {
   const disciplines = await Promise.all(
     disciplineIds.map(async (id) => {
       const content = await loadYamlFile(`${disciplinesDir}/${id}.yaml`);
-      // Shared content at top level, role summaries under human:
       const {
         specialization,
         roleTitle,
-        // Track constraints
         isProfessional,
         isManagement,
         validTracks,
-        minGrade,
-        // Shared content - now at root level
+        minLevel,
         description,
-        // Structural properties (derivation inputs)
         coreSkills,
         supportingSkills,
         broadSkills,
         behaviourModifiers,
-        // Presentation sections
         human,
         agent,
       } = content;
@@ -139,19 +99,15 @@ async function loadDisciplinesFromDir(disciplinesDir) {
         id,
         specialization,
         roleTitle,
-        // Track constraints
         isProfessional,
         isManagement,
         validTracks,
-        minGrade,
-        // Shared content at top level
+        minLevel,
         description,
-        // Structural properties
         coreSkills,
         supportingSkills,
         broadSkills,
         behaviourModifiers,
-        // Human presentation content (role summaries only)
         ...human,
         ...(agent && { agent }),
       };
@@ -171,31 +127,25 @@ async function loadTracksFromDir(tracksDir) {
   const tracks = await Promise.all(
     trackIds.map(async (id) => {
       const content = await loadYamlFile(`${tracksDir}/${id}.yaml`);
-      // Shared content at top level (no human section for tracks anymore)
       const {
         name,
-        // Shared content - now at root level
         description,
         roleContext,
-        // Structural properties (derivation inputs)
         skillModifiers,
         behaviourModifiers,
         matchingWeights,
-        minGrade,
-        // Agent section (no human section anymore for tracks)
+        minLevel,
         agent,
       } = content;
       return {
         id,
         name,
-        // Shared content at top level
         description,
         roleContext,
-        // Structural properties
         skillModifiers,
         behaviourModifiers,
         matchingWeights,
-        minGrade,
+        minLevel,
         ...(agent && { agent }),
       };
     }),
@@ -214,7 +164,6 @@ async function loadBehavioursFromDir(behavioursDir) {
   const behaviours = await Promise.all(
     behaviourIds.map(async (id) => {
       const content = await loadYamlFile(`${behavioursDir}/${id}.yaml`);
-      // Flatten human properties to top level (behaviours use human: section in YAML)
       const { name, human, agent } = content;
       return {
         id,
@@ -285,7 +234,7 @@ async function loadQuestionFolder(
   );
 
   return {
-    skillLevels: Object.fromEntries(skillEntries),
+    skillProficiencies: Object.fromEntries(skillEntries),
     behaviourMaturities: Object.fromEntries(behaviourEntries),
     capabilityLevels: Object.fromEntries(capabilityEntries),
   };
@@ -297,25 +246,20 @@ async function loadQuestionFolder(
  * @returns {Promise<Object>}
  */
 export async function loadAllData(dataDir = "./data") {
-  // Load capabilities first (skills are embedded in capabilities)
   const capabilities = await loadCapabilitiesFromDir(`${dataDir}/capabilities`);
-
-  // Extract skills from capabilities
   const skills = await loadSkillsFromCapabilities(`${dataDir}/capabilities`);
 
-  // Load remaining core data in parallel (using _index.yaml for discovery)
-  const [drivers, behaviours, disciplines, tracks, grades, stages, framework] =
+  const [drivers, behaviours, disciplines, tracks, levels, stages, framework] =
     await Promise.all([
       loadYamlFile(`${dataDir}/drivers.yaml`),
       loadBehavioursFromDir(`${dataDir}/behaviours`),
       loadDisciplinesFromDir(`${dataDir}/disciplines`),
       loadTracksFromDir(`${dataDir}/tracks`),
-      loadYamlFile(`${dataDir}/grades.yaml`),
+      loadYamlFile(`${dataDir}/levels.yaml`),
       loadYamlFile(`${dataDir}/stages.yaml`),
       loadYamlFile(`${dataDir}/framework.yaml`),
     ]);
 
-  // Load questions using skill/behaviour/capability IDs
   const questions = await loadQuestionFolder(
     `${dataDir}/questions`,
     skills,
@@ -329,7 +273,7 @@ export async function loadAllData(dataDir = "./data") {
     skills,
     disciplines,
     tracks,
-    grades,
+    levels,
     questions,
     capabilities,
     stages,
@@ -339,9 +283,8 @@ export async function loadAllData(dataDir = "./data") {
 
 /**
  * Load agent-specific data for browser-based agent generation
- * Uses co-located files where agent sections are embedded in entity files
  * @param {string} [dataDir='./data'] - Path to data directory
- * @returns {Promise<Object>} Agent data including disciplines, tracks, behaviours, vscodeSettings, devcontainer, copilotSetupSteps
+ * @returns {Promise<Object>}
  */
 export async function loadAgentDataBrowser(dataDir = "./data") {
   const [
@@ -360,7 +303,6 @@ export async function loadAgentDataBrowser(dataDir = "./data") {
     tryLoadYamlFile(`${dataDir}/copilot-setup-steps.yaml`),
   ]);
 
-  // Extract agent sections from co-located files
   return {
     disciplines: disciplines
       .filter((d) => d.agent)

package/src/main.js

@@ -25,7 +25,7 @@ import {
   renderDisciplineDetail,
 } from "./pages/discipline.js";
 import { renderTracksList, renderTrackDetail } from "./pages/track.js";
-import { renderGradesList, renderGradeDetail } from "./pages/grade.js";
+import { renderLevelsList, renderLevelDetail } from "./pages/level.js";
 import { renderDriversList, renderDriverDetail } from "./pages/driver.js";
 import { renderStagesList, renderStageDetail } from "./pages/stage.js";
 import { renderToolsList } from "./pages/tool.js";
@@ -99,9 +99,9 @@ function setupRoutes() {
   router.on("/track", renderTracksList);
   router.on("/track/:id", renderTrackDetail);
 
-  // Grade
-  router.on("/grade", renderGradesList);
-  router.on("/grade/:id", renderGradeDetail);
+  // Level
+  router.on("/level", renderLevelsList);
+  router.on("/level/:id", renderLevelDetail);
 
   // Driver
   router.on("/driver", renderDriversList);
@@ -116,18 +116,18 @@ function setupRoutes() {
 
   // Job builder
   router.on("/job-builder", renderJobBuilder);
-  router.on("/job/:discipline/:grade/:track", renderJobDetail);
-  router.on("/job/:discipline/:grade", renderJobDetail);
+  router.on("/job/:discipline/:level/:track", renderJobDetail);
+  router.on("/job/:discipline/:level", renderJobDetail);
 
   // Interview prep
   router.on("/interview-prep", renderInterviewPrep);
-  router.on("/interview/:discipline/:grade/:track", renderInterviewDetail);
-  router.on("/interview/:discipline/:grade", renderInterviewDetail);
+  router.on("/interview/:discipline/:level/:track", renderInterviewDetail);
+  router.on("/interview/:discipline/:level", renderInterviewDetail);
 
   // Career progress
   router.on("/career-progress", renderCareerProgress);
-  router.on("/progress/:discipline/:grade/:track", renderProgressDetail);
-  router.on("/progress/:discipline/:grade", renderProgressDetail);
+  router.on("/progress/:discipline/:level/:track", renderProgressDetail);
+  router.on("/progress/:discipline/:level", renderProgressDetail);
 
   // Self-assessment
   router.on("/self-assessment", renderSelfAssessment);

package/src/pages/agent-builder.js

@@ -26,10 +26,10 @@ import {
   deriveStageAgent,
   generateSkillMarkdown,
   deriveAgentSkills,
-  deriveReferenceGrade,
+  deriveReferenceLevel,
   deriveToolkit,
   buildAgentIndex,
-} from "@forwardimpact/libpathway";
+} from "@forwardimpact/libskill";
 import {
   createSelectWithValue,
   createDisciplineSelect,
@@ -256,8 +256,8 @@ export async function renderAgentBuilder() {
       return;
     }
 
-    // Get reference grade for derivation
-    const grade = deriveReferenceGrade(data.grades);
+    // Get reference level for derivation
+    const level = deriveReferenceLevel(data.levels);
 
     // Build agent index for all valid combinations
     const agentIndex = buildAgentIndex({
@@ -274,7 +274,7 @@ export async function renderAgentBuilder() {
       humanTrack,
       agentDiscipline,
       agentTrack,
-      grade,
+      level,
       stages,
       skills: data.skills,
       behaviours: data.behaviours,
@@ -451,7 +451,7 @@ function createAllStagesPreview(context) {
     humanTrack,
     agentDiscipline,
     agentTrack,
-    grade,
+    level,
     stages,
     skills,
     behaviours,
@@ -468,7 +468,7 @@ function createAllStagesPreview(context) {
       discipline: humanDiscipline,
       track: humanTrack,
       stage,
-      grade,
+      level,
       skills,
       behaviours,
       agentBehaviours,
@@ -481,7 +481,7 @@ function createAllStagesPreview(context) {
       discipline: humanDiscipline,
       track: humanTrack,
       stage,
-      grade,
+      level,
       skills,
       behaviours,
       agentBehaviours,
@@ -498,7 +498,7 @@ function createAllStagesPreview(context) {
   const derivedSkills = deriveAgentSkills({
     discipline: humanDiscipline,
     track: humanTrack,
-    grade,
+    level,
     skills,
   });
 
@@ -594,7 +594,7 @@ function createSingleStagePreview(context, stage) {
     humanTrack,
     agentDiscipline,
     agentTrack,
-    grade,
+    level,
     skills,
     behaviours,
     agentBehaviours,
@@ -609,7 +609,7 @@ function createSingleStagePreview(context, stage) {
     discipline: humanDiscipline,
     track: humanTrack,
     stage,
-    grade,
+    level,
     skills,
     behaviours,
     agentBehaviours,
@@ -623,7 +623,7 @@ function createSingleStagePreview(context, stage) {
   const derivedSkills = deriveAgentSkills({
     discipline: humanDiscipline,
     track: humanTrack,
-    grade,
+    level,
     skills,
   });
 

package/src/pages/assessment-results.js

@@ -19,7 +19,7 @@ import { getState } from "../lib/state.js";
 import { createBadge } from "../components/card.js";
 import { formatLevel } from "../lib/render.js";
 import { getAssessmentState, resetAssessment } from "./self-assessment.js";
-import { findRealisticMatches } from "@forwardimpact/libpathway/matching";
+import { findRealisticMatches } from "@forwardimpact/libskill/matching";
 
 /**
  * Render the assessment results page
@@ -45,14 +45,14 @@ export function renderAssessmentResults() {
   };
 
   // Find matching jobs with realistic scoring
-  const { matches, matchesByTier, estimatedGrade } = findRealisticMatches({
+  const { matches, matchesByTier, estimatedLevel } = findRealisticMatches({
     selfAssessment,
     disciplines: data.disciplines,
-    grades: data.grades,
+    levels: data.levels,
     tracks: data.tracks,
     skills: data.skills,
     behaviours: data.behaviours,
-    filterByGrade: false, // Show all grades but group by tier
+    filterByLevel: false, // Show all levels but group by tier
     topN: 20,
   });
 
@@ -73,7 +73,7 @@ export function renderAssessmentResults() {
     ),
 
     // Summary stats
-    createSummaryStats(assessmentState, data, estimatedGrade),
+    createSummaryStats(assessmentState, data, estimatedLevel),
 
     // Top matches grouped by tier
     createMatchesSection(matches, matchesByTier, selfAssessment, data),
@@ -139,28 +139,28 @@ function renderNoAssessment() {
  * Create summary statistics section
  * @param {Object} assessmentState - Current assessment state
  * @param {Object} data - App data
- * @param {{grade: Object, confidence: number}} estimatedGrade - Estimated best-fit grade
+ * @param {{level: Object, confidence: number}} estimatedLevel - Estimated best-fit level
  * @returns {HTMLElement}
  */
-function createSummaryStats(assessmentState, data, estimatedGrade) {
+function createSummaryStats(assessmentState, data, estimatedLevel) {
   const skillCount = Object.keys(assessmentState.skills).length;
   const behaviourCount = Object.keys(assessmentState.behaviours).length;
 
   // Calculate average levels
-  const avgSkillLevel = calculateAverageLevel(
+  const avgSkillProficiency = calculateAverageLevel(
     Object.values(assessmentState.skills),
     ["awareness", "foundational", "working", "practitioner", "expert"],
   );
 
-  // Get grade name based on track (default to professional)
-  const gradeName =
-    estimatedGrade.grade.professionalTitle ||
-    estimatedGrade.grade.name ||
-    estimatedGrade.grade.id;
+  // Get level name based on track (default to professional)
+  const levelName =
+    estimatedLevel.level.professionalTitle ||
+    estimatedLevel.level.name ||
+    estimatedLevel.level.id;
   const confidenceLabel =
-    estimatedGrade.confidence >= 0.7
+    estimatedLevel.confidence >= 0.7
       ? "High"
-      : estimatedGrade.confidence >= 0.4
+      : estimatedLevel.confidence >= 0.4
         ? "Medium"
         : "Low";
 
@@ -179,8 +179,12 @@ function createSummaryStats(assessmentState, data, estimatedGrade) {
         `of ${data.behaviours.length} Behaviours`,
         "🧠",
       ),
-      createStatBox(formatLevel(avgSkillLevel), "Avg Skill Level", "💡"),
-      createStatBox(gradeName, `Estimated Level (${confidenceLabel})`, "🎯"),
+      createStatBox(
+        formatLevel(avgSkillProficiency),
+        "Avg Skill Proficiency",
+        "💡",
+      ),
+      createStatBox(levelName, `Estimated Level (${confidenceLabel})`, "🎯"),
     ),
   );
 }
@@ -380,8 +384,8 @@ function createMatchCard(match, _index, _selfAssessment, _data) {
           a(
             {
               href: job.track
-                ? `#/job/${job.discipline.id}/${job.grade.id}/${job.track.id}`
-                : `#/job/${job.discipline.id}/${job.grade.id}`,
+                ? `#/job/${job.discipline.id}/${job.level.id}/${job.track.id}`
+                : `#/job/${job.discipline.id}/${job.level.id}`,
             },
             job.title,
           ),
@@ -389,7 +393,7 @@ function createMatchCard(match, _index, _selfAssessment, _data) {
         div(
           { className: "match-badges" },
           createBadge(job.discipline.name, "default"),
-          createBadge(job.grade.name, "secondary"),
+          createBadge(job.level.name, "secondary"),
           job.track && createBadge(job.track.name, "broad"),
         ),
       ),
@@ -440,8 +444,8 @@ function createMatchCard(match, _index, _selfAssessment, _data) {
       a(
         {
           href: job.track
-            ? `#/job/${job.discipline.id}/${job.grade.id}/${job.track.id}`
-            : `#/job/${job.discipline.id}/${job.grade.id}`,
+            ? `#/job/${job.discipline.id}/${job.level.id}/${job.track.id}`
+            : `#/job/${job.discipline.id}/${job.level.id}`,
           className: "btn btn-secondary btn-sm",
         },
         "View Job Details",
@@ -449,8 +453,8 @@ function createMatchCard(match, _index, _selfAssessment, _data) {
       a(
         {
           href: job.track
-            ? `#/interview/${job.discipline.id}/${job.grade.id}/${job.track.id}`
-            : `#/interview/${job.discipline.id}/${job.grade.id}`,
+            ? `#/interview/${job.discipline.id}/${job.level.id}/${job.track.id}`
+            : `#/interview/${job.discipline.id}/${job.level.id}`,
           className: "btn btn-secondary btn-sm",
         },
         "Interview Prep",