@forwardimpact/pathway 0.21.0 → 0.22.0

package/src/formatters/job/markdown.js

@@ -9,7 +9,7 @@ import {
 } from "../shared.js";
 import { formatLevel } from "../../lib/render.js";
 import { formatJobDescription } from "./description.js";
-import { SKILL_LEVEL_ORDER } from "@forwardimpact/map/levels";
+import { SKILL_PROFICIENCY_ORDER } from "@forwardimpact/map/levels";
 import { toolkitToMarkdown } from "../toolkit/markdown.js";
 
 /**
@@ -23,7 +23,7 @@ export function jobToMarkdown(view, entities = {}, jobTemplate) {
   const lines = [
     `# ${view.title}`,
     "",
-    `${view.disciplineName} × ${view.gradeId} × ${view.trackName}`,
+    `${view.disciplineName} × ${view.levelId} × ${view.trackName}`,
     "",
   ];
 
@@ -46,8 +46,8 @@ export function jobToMarkdown(view, entities = {}, jobTemplate) {
   // Skill Matrix - sorted by level descending
   lines.push("## Skill Matrix", "");
   const sortedSkills = [...view.skillMatrix].sort((a, b) => {
-    const levelA = SKILL_LEVEL_ORDER.indexOf(a.level);
-    const levelB = SKILL_LEVEL_ORDER.indexOf(b.level);
+    const levelA = SKILL_PROFICIENCY_ORDER.indexOf(a.level);
+    const levelB = SKILL_PROFICIENCY_ORDER.indexOf(b.level);
     if (levelB !== levelA) {
       return levelB - levelA;
     }
@@ -55,7 +55,7 @@ export function jobToMarkdown(view, entities = {}, jobTemplate) {
   });
   const skillRows = sortedSkills.map((s) => [
     s.skillName,
-    formatLevel(s.level),
+    formatLevel(s.proficiency),
   ]);
   lines.push(tableToMarkdown(["Skill", "Level"], skillRows));
   lines.push("");
@@ -86,7 +86,7 @@ export function jobToMarkdown(view, entities = {}, jobTemplate) {
   }
 
   // Job Description (copyable markdown)
-  if (entities.discipline && entities.grade && jobTemplate) {
+  if (entities.discipline && entities.level && jobTemplate) {
     lines.push("---", "");
     lines.push("## Job Description", "");
     lines.push("```markdown");
@@ -101,7 +101,7 @@ export function jobToMarkdown(view, entities = {}, jobTemplate) {
             derivedResponsibilities: view.derivedResponsibilities,
           },
           discipline: entities.discipline,
-          grade: entities.grade,
+          level: entities.level,
           track: entities.track,
         },
         jobTemplate,

package/src/formatters/json-ld.js

@@ -51,13 +51,13 @@ export function skillToJsonLd(skill, { capabilities = [] } = {}) {
     capability: skill.capability,
     ...(capability && { capabilityName: capability.name }),
     ...(skill.isHumanOnly && { isHumanOnly: true }),
-    levelDescriptions: Object.entries(skill.levelDescriptions || {}).map(
-      ([level, description]) => ({
-        "@type": "SkillLevelDescription",
-        level: `${VOCAB_BASE}${level}`,
-        description,
-      }),
-    ),
+    proficiencyDescriptions: Object.entries(
+      skill.proficiencyDescriptions || {},
+    ).map(([level, description]) => ({
+      "@type": "SkillProficiencyDescription",
+      level: `${VOCAB_BASE}${level}`,
+      description,
+    })),
   };
 }
 
@@ -147,29 +147,29 @@ export function trackToJsonLd(track) {
 }
 
 /**
- * Generate JSON-LD for a grade entity
- * @param {Object} grade - Raw grade entity
+ * Generate JSON-LD for a level entity
+ * @param {Object} level - Raw level entity
  * @returns {Object}
  */
-export function gradeToJsonLd(grade) {
+export function levelToJsonLd(level) {
   return {
-    ...baseJsonLd("Grade", grade.id),
-    identifier: grade.id,
-    name: grade.displayName || grade.name,
-    ...(grade.ordinalRank && { ordinalRank: grade.ordinalRank }),
-    ...(grade.typicalExperienceRange && {
-      typicalExperienceRange: grade.typicalExperienceRange,
+    ...baseJsonLd("Level", level.id),
+    identifier: level.id,
+    name: level.displayName || level.name,
+    ...(level.ordinalRank && { ordinalRank: level.ordinalRank }),
+    ...(level.typicalExperienceRange && {
+      typicalExperienceRange: level.typicalExperienceRange,
     }),
-    ...(grade.baseSkillLevels && {
-      baseSkillLevels: {
-        "@type": "BaseSkillLevels",
-        primary: `${VOCAB_BASE}${grade.baseSkillLevels.primary}`,
-        secondary: `${VOCAB_BASE}${grade.baseSkillLevels.secondary}`,
-        broad: `${VOCAB_BASE}${grade.baseSkillLevels.broad}`,
+    ...(level.baseSkillProficiencies && {
+      baseSkillProficiencies: {
+        "@type": "BaseSkillProficiencies",
+        primary: `${VOCAB_BASE}${level.baseSkillProficiencies.primary}`,
+        secondary: `${VOCAB_BASE}${level.baseSkillProficiencies.secondary}`,
+        broad: `${VOCAB_BASE}${level.baseSkillProficiencies.broad}`,
       },
     }),
-    ...(grade.baseBehaviourMaturity && {
-      baseBehaviourMaturity: `${VOCAB_BASE}${grade.baseBehaviourMaturity}`,
+    ...(level.baseBehaviourMaturity && {
+      baseBehaviourMaturity: `${VOCAB_BASE}${level.baseBehaviourMaturity}`,
     }),
   };
 }

package/src/formatters/{grade → level}/dom.js

@@ -1,5 +1,5 @@
 /**
- * Grade formatting for DOM output
+ * Level formatting for DOM output
  */
 
 import {
@@ -19,33 +19,33 @@ import {
 import { createBackLink } from "../../components/nav.js";
 import { createLevelDots } from "../../components/detail.js";
 import {
-  SKILL_LEVEL_ORDER,
+  SKILL_PROFICIENCY_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
   getConceptEmoji,
 } from "@forwardimpact/map/levels";
 import { createJobBuilderButton } from "../../components/action-buttons.js";
-import { prepareGradeDetail } from "./shared.js";
-import { createJsonLdScript, gradeToJsonLd } from "../json-ld.js";
+import { prepareLevelDetail } from "./shared.js";
+import { createJsonLdScript, levelToJsonLd } from "../json-ld.js";
 
 /**
- * Format grade detail as DOM elements
- * @param {Object} grade - Raw grade entity
+ * Format level detail as DOM elements
+ * @param {Object} level - Raw level entity
  * @param {Object} options - Formatting options
  * @param {Object} [options.framework] - Framework config for emojis
  * @param {boolean} [options.showBackLink=true] - Whether to show back navigation link
  * @returns {HTMLElement}
  */
-export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
-  const view = prepareGradeDetail(grade);
-  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
+export function levelToDOM(level, { framework, showBackLink = true } = {}) {
+  const view = prepareLevelDetail(level);
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
   return div(
-    { className: "detail-page grade-detail" },
+    { className: "detail-page level-detail" },
     // JSON-LD structured data
-    createJsonLdScript(gradeToJsonLd(grade)),
+    createJsonLdScript(levelToJsonLd(level)),
     // Header
     div(
       { className: "page-header" },
-      showBackLink ? createBackLink("/grade", "← Back to Grades") : null,
+      showBackLink ? createBackLink("/level", "← Back to Levels") : null,
       heading1({ className: "page-title" }, `${emoji} `, view.displayName),
       div(
         { className: "page-meta" },
@@ -61,8 +61,8 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
         ? div(
             { className: "page-actions" },
             createJobBuilderButton({
-              paramName: "grade",
-              paramValue: grade.id,
+              paramName: "level",
+              paramValue: level.id,
             }),
           )
         : null,
@@ -111,15 +111,15 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
         )
       : null,
 
-    // Base Skill Levels and Base Behaviour Maturity in two columns
+    // Base Skill Proficiencies and Base Behaviour Maturity in two columns
     div(
       { className: "detail-section" },
       div(
         { className: "content-columns" },
-        // Base Skill Levels column
+        // Base Skill Proficiencies column
         div(
           { className: "column" },
-          heading2({ className: "section-title" }, "Base Skill Levels"),
+          heading2({ className: "section-title" }, "Base Skill Proficiencies"),
           table(
             { className: "level-table" },
             thead({}, tr({}, th({}, "Type"), th({}, "Level"))),
@@ -130,10 +130,12 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
                 td({}, span({ className: "badge badge-primary" }, "Primary")),
                 td(
                   {},
-                  view.baseSkillLevels?.primary
+                  view.baseSkillProficiencies?.primary
                     ? createLevelDots(
-                        SKILL_LEVEL_ORDER.indexOf(view.baseSkillLevels.primary),
-                        SKILL_LEVEL_ORDER.length,
+                        SKILL_PROFICIENCY_ORDER.indexOf(
+                          view.baseSkillProficiencies.primary,
+                        ),
+                        SKILL_PROFICIENCY_ORDER.length,
                       )
                     : span({ className: "text-muted" }, "—"),
                 ),
@@ -146,12 +148,12 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
                 ),
                 td(
                   {},
-                  view.baseSkillLevels?.secondary
+                  view.baseSkillProficiencies?.secondary
                     ? createLevelDots(
-                        SKILL_LEVEL_ORDER.indexOf(
-                          view.baseSkillLevels.secondary,
+                        SKILL_PROFICIENCY_ORDER.indexOf(
+                          view.baseSkillProficiencies.secondary,
                         ),
-                        SKILL_LEVEL_ORDER.length,
+                        SKILL_PROFICIENCY_ORDER.length,
                       )
                     : span({ className: "text-muted" }, "—"),
                 ),
@@ -161,10 +163,12 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
                 td({}, span({ className: "badge badge-broad" }, "Broad")),
                 td(
                   {},
-                  view.baseSkillLevels?.broad
+                  view.baseSkillProficiencies?.broad
                     ? createLevelDots(
-                        SKILL_LEVEL_ORDER.indexOf(view.baseSkillLevels.broad),
-                        SKILL_LEVEL_ORDER.length,
+                        SKILL_PROFICIENCY_ORDER.indexOf(
+                          view.baseSkillProficiencies.broad,
+                        ),
+                        SKILL_PROFICIENCY_ORDER.length,
                       )
                     : span({ className: "text-muted" }, "—"),
                 ),

package/src/formatters/{grade → level}/markdown.js

@@ -1,27 +1,27 @@
 /**
- * Grade formatting for markdown/CLI output
+ * Level formatting for markdown/CLI output
  */
 
 import { tableToMarkdown, capitalize } from "../shared.js";
-import { prepareGradesList, prepareGradeDetail } from "./shared.js";
+import { prepareLevelsList, prepareLevelDetail } from "./shared.js";
 import { getConceptEmoji } from "@forwardimpact/map/levels";
 
 /**
- * Format grade list as markdown
- * @param {Array} grades - Raw grade entities
+ * Format level list as markdown
+ * @param {Array} levels - Raw level entities
  * @param {Object} [framework] - Framework config for emojis
  * @returns {string}
  */
-export function gradeListToMarkdown(grades, framework) {
-  const { items } = prepareGradesList(grades);
-  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
-  const lines = [`# ${emoji} Grades`, ""];
+export function levelListToMarkdown(levels, framework) {
+  const { items } = prepareLevelsList(levels);
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
+  const lines = [`# ${emoji} Levels`, ""];
 
   const rows = items.map((g) => [
     g.id,
     g.displayName,
     g.typicalExperienceRange || "-",
-    capitalize(g.baseSkillLevels?.primary || "-"),
+    capitalize(g.baseSkillProficiencies?.primary || "-"),
   ]);
 
   lines.push(tableToMarkdown(["ID", "Name", "Years", "Primary Level"], rows));
@@ -31,14 +31,14 @@ export function gradeListToMarkdown(grades, framework) {
 }
 
 /**
- * Format grade detail as markdown
- * @param {Object} grade - Raw grade entity
+ * Format level detail as markdown
+ * @param {Object} level - Raw level entity
  * @param {Object} [framework] - Framework config for emojis
  * @returns {string}
  */
-export function gradeToMarkdown(grade, framework) {
-  const view = prepareGradeDetail(grade);
-  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
+export function levelToMarkdown(level, framework) {
+  const view = prepareLevelDetail(level);
+  const emoji = framework ? getConceptEmoji(framework, "level") : "📊";
   const lines = [`# ${emoji} ${view.displayName} (${view.id})`, ""];
 
   if (view.typicalExperienceRange) {
@@ -57,27 +57,18 @@ export function gradeToMarkdown(grade, framework) {
     lines.push("");
   }
 
-  // Base skill levels
-  lines.push("## Base Skill Levels", "");
-  const skillRows = Object.entries(view.baseSkillLevels).map(
+  // Base skill proficiencies
+  lines.push("## Base Skill Proficiencies", "");
+  const skillRows = Object.entries(view.baseSkillProficiencies).map(
     ([type, level]) => [capitalize(type), capitalize(level)],
   );
   lines.push(tableToMarkdown(["Skill Type", "Level"], skillRows));
   lines.push("");
 
   // Base behaviour maturity
-  if (
-    view.baseBehaviourMaturity &&
-    Object.keys(view.baseBehaviourMaturity).length > 0
-  ) {
+  if (view.baseBehaviourMaturity) {
     lines.push("## Base Behaviour Maturity", "");
-    const behaviourRows = Object.entries(view.baseBehaviourMaturity).map(
-      ([type, maturity]) => [
-        capitalize(type),
-        capitalize(maturity.replace(/_/g, " ")),
-      ],
-    );
-    lines.push(tableToMarkdown(["Type", "Maturity"], behaviourRows));
+    lines.push(capitalize(view.baseBehaviourMaturity.replace(/_/g, " ")));
     lines.push("");
   }
 

package/src/formatters/{grade → level}/microdata.js

@@ -1,7 +1,7 @@
 /**
- * Grade formatting for microdata HTML output
+ * Level formatting for microdata HTML output
  *
- * Generates clean, class-less HTML with microdata aligned with grades.schema.json
+ * Generates clean, class-less HTML with microdata aligned with levels.schema.json
  * RDF vocab: https://www.forwardimpact.team/schema/rdf/
  */
 
@@ -16,19 +16,19 @@ import {
   formatLevelName,
   htmlDocument,
 } from "../microdata-shared.js";
-import { prepareGradesList, prepareGradeDetail } from "./shared.js";
+import { prepareLevelsList, prepareLevelDetail } from "./shared.js";
 
 /**
- * Format grade list as microdata HTML
- * @param {Array} grades - Raw grade entities
+ * Format level list as microdata HTML
+ * @param {Array} levels - Raw level entities
  * @returns {string} HTML with microdata
  */
-export function gradeListToMicrodata(grades) {
-  const { items } = prepareGradesList(grades);
+export function levelListToMicrodata(levels) {
+  const { items } = prepareLevelsList(levels);
 
   const content = items
     .map(
-      (g) => `${openTag("article", { itemtype: "Grade", itemid: `#${g.id}` })}
+      (g) => `${openTag("article", { itemtype: "Level", itemid: `#${g.id}` })}
 ${prop("h2", "id", g.id)}
 <p>${escapeHtml(g.displayName)}</p>
 ${g.typicalExperienceRange ? prop("p", "typicalExperienceRange", g.typicalExperienceRange) : ""}
@@ -38,21 +38,21 @@ ${metaTag("ordinalRank", String(g.ordinalRank))}
     .join("\n");
 
   return htmlDocument(
-    "Grades",
+    "Levels",
     `<main>
-<h1>Grades</h1>
+<h1>Levels</h1>
 ${content}
 </main>`,
   );
 }
 
 /**
- * Format grade detail as microdata HTML
- * @param {Object} grade - Raw grade entity
+ * Format level detail as microdata HTML
+ * @param {Object} level - Raw level entity
  * @returns {string} HTML with microdata
  */
-export function gradeToMicrodata(grade) {
-  const view = prepareGradeDetail(grade);
+export function levelToMicrodata(level) {
+  const view = prepareLevelDetail(level);
 
   if (!view) return "";
 
@@ -78,9 +78,12 @@ export function gradeToMicrodata(grade) {
     sections.push(section("Titles", dl(titlePairs), 2));
   }
 
-  // Base skill levels - using BaseSkillLevels itemtype
-  if (view.baseSkillLevels && Object.keys(view.baseSkillLevels).length > 0) {
-    const levelPairs = Object.entries(view.baseSkillLevels).map(
+  // Base skill proficiencies - using BaseSkillProficiencies itemtype
+  if (
+    view.baseSkillProficiencies &&
+    Object.keys(view.baseSkillProficiencies).length > 0
+  ) {
+    const levelPairs = Object.entries(view.baseSkillProficiencies).map(
       ([type, level]) => ({
         term: formatLevelName(type),
         definition: formatLevelName(level),
@@ -89,8 +92,8 @@ export function gradeToMicrodata(grade) {
     );
     sections.push(
       section(
-        "Base Skill Levels",
-        `${openTag("div", { itemtype: "BaseSkillLevels", itemprop: "baseSkillLevels" })}
+        "Base Skill Proficiencies",
+        `${openTag("div", { itemtype: "BaseSkillProficiencies", itemprop: "baseSkillProficiencies" })}
 ${dl(levelPairs)}
 </div>`,
         2,
@@ -99,26 +102,13 @@ ${dl(levelPairs)}
   }
 
   // Base behaviour maturity - link to BehaviourMaturity
-  if (
-    view.baseBehaviourMaturity &&
-    Object.keys(view.baseBehaviourMaturity).length > 0
-  ) {
-    const maturityPairs = Object.entries(view.baseBehaviourMaturity).map(
-      ([type, maturity]) => ({
-        term: formatLevelName(type),
-        definition: formatLevelName(maturity),
-      }),
-    );
-    // Handle both single value and object cases
-    const maturityContent =
-      typeof grade.baseBehaviourMaturity === "string"
-        ? `${linkTag("baseBehaviourMaturity", `#${grade.baseBehaviourMaturity}`)}
-<p>${formatLevelName(grade.baseBehaviourMaturity)}</p>`
-        : dl(maturityPairs);
+  if (view.baseBehaviourMaturity) {
+    const maturityContent = `${linkTag("baseBehaviourMaturity", `#${level.baseBehaviourMaturity}`)}
+<p>${formatLevelName(level.baseBehaviourMaturity)}</p>`;
     sections.push(section("Base Behaviour Maturity", maturityContent, 2));
   }
 
-  // Expectations - using GradeExpectations itemtype
+  // Expectations - using LevelExpectations itemtype
   if (view.expectations && Object.keys(view.expectations).length > 0) {
     const expectationPairs = Object.entries(view.expectations).map(
       ([key, value]) => ({
@@ -130,7 +120,7 @@ ${dl(levelPairs)}
     sections.push(
       section(
         "Expectations",
-        `${openTag("div", { itemtype: "GradeExpectations", itemprop: "expectations" })}
+        `${openTag("div", { itemtype: "LevelExpectations", itemprop: "expectations" })}
 ${dl(expectationPairs)}
 </div>`,
         2,
@@ -139,7 +129,7 @@ ${dl(expectationPairs)}
   }
 
   const body = `<main>
-${openTag("article", { itemtype: "Grade", itemid: `#${view.id}` })}
+${openTag("article", { itemtype: "Level", itemid: `#${view.id}` })}
 <h1>${prop("span", "id", view.id)} — ${escapeHtml(view.displayName)}</h1>
 ${metaTag("ordinalRank", String(view.ordinalRank))}
 ${view.typicalExperienceRange ? prop("p", "typicalExperienceRange", `Experience: ${view.typicalExperienceRange}`) : ""}

package/src/formatters/level/shared.js

@@ -0,0 +1,86 @@
+/**
+ * Level presentation helpers
+ *
+ * Shared utilities for formatting level data across DOM and markdown outputs.
+ */
+
+/**
+ * Get level display name (shows both professional and management titles)
+ * @param {Object} level
+ * @returns {string}
+ */
+export function getLevelDisplayName(level) {
+  if (level.professionalTitle && level.managementTitle) {
+    if (level.professionalTitle === level.managementTitle) {
+      return level.professionalTitle;
+    }
+    return `${level.professionalTitle} / ${level.managementTitle}`;
+  }
+  return level.professionalTitle || level.managementTitle || level.id;
+}
+
+/**
+ * @typedef {Object} LevelListItem
+ * @property {string} id
+ * @property {string} displayName
+ * @property {number} ordinalRank
+ * @property {string|null} typicalExperienceRange
+ * @property {Object} baseSkillProficiencies
+ * @property {string|null} impactScope
+ */
+
+/**
+ * Transform levels for list view
+ * @param {Array} levels - Raw level entities
+ * @returns {{ items: LevelListItem[] }}
+ */
+export function prepareLevelsList(levels) {
+  const sortedLevels = [...levels].sort(
+    (a, b) => a.ordinalRank - b.ordinalRank,
+  );
+
+  const items = sortedLevels.map((level) => ({
+    id: level.id,
+    displayName: getLevelDisplayName(level),
+    ordinalRank: level.ordinalRank,
+    typicalExperienceRange: level.typicalExperienceRange || null,
+    baseSkillProficiencies: level.baseSkillProficiencies || {},
+    impactScope: level.expectations?.impactScope || null,
+  }));
+
+  return { items };
+}
+
+/**
+ * @typedef {Object} LevelDetailView
+ * @property {string} id
+ * @property {string} displayName
+ * @property {string} professionalTitle
+ * @property {string} managementTitle
+ * @property {number} ordinalRank
+ * @property {string|null} typicalExperienceRange
+ * @property {Object} baseSkillProficiencies
+ * @property {Object} baseBehaviourMaturity
+ * @property {Object} expectations
+ */
+
+/**
+ * Transform level for detail view
+ * @param {Object} level - Raw level entity
+ * @returns {LevelDetailView|null}
+ */
+export function prepareLevelDetail(level) {
+  if (!level) return null;
+
+  return {
+    id: level.id,
+    displayName: getLevelDisplayName(level),
+    professionalTitle: level.professionalTitle || null,
+    managementTitle: level.managementTitle || null,
+    ordinalRank: level.ordinalRank,
+    typicalExperienceRange: level.typicalExperienceRange || null,
+    baseSkillProficiencies: level.baseSkillProficiencies || {},
+    baseBehaviourMaturity: level.baseBehaviourMaturity || {},
+    expectations: level.expectations || {},
+  };
+}

package/src/formatters/progress/markdown.js

@@ -29,7 +29,7 @@ export function progressToMarkdown(view) {
 
   // Skill changes
   const skillsWithChanges = view.skillChanges.filter(
-    (s) => s.levelChange !== 0,
+    (s) => s.proficiencyChange !== 0,
   );
   if (skillsWithChanges.length > 0) {
     lines.push("## Skill Changes", "");
@@ -39,7 +39,7 @@ export function progressToMarkdown(view) {
       formatLevel(s.fromLevel || "-"),
       "→",
       formatLevel(s.toLevel),
-      formatChange(s.levelChange),
+      formatChange(s.proficiencyChange),
     ]);
     lines.push(
       tableToMarkdown(["Skill", "Type", "From", "", "To", "Change"], skillRows),