@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/formatters/index.js

@@ -2,11 +2,12 @@
  * Formatter Layer
  *
  * Export all formatters for easy importing.
- * Formatters transform presenter output into specific formats (DOM, markdown)
+ * Formatters transform presenter output into specific formats (DOM, markdown, microdata)
  */
 
 // Shared utilities
 export * from "./shared.js";
+export * from "./microdata-shared.js";
 
 // Job formatters
 export { jobToMarkdown } from "./job/markdown.js";
@@ -22,10 +23,15 @@ export { progressToDOM } from "./progress/dom.js";
 
 // Driver formatters
 export { driverToDOM } from "./driver/dom.js";
+export {
+  driverListToMicrodata,
+  driverToMicrodata,
+} from "./driver/microdata.js";
 
 // Skill formatters
 export { skillListToMarkdown, skillToMarkdown } from "./skill/markdown.js";
 export { skillToDOM } from "./skill/dom.js";
+export { skillListToMicrodata, skillToMicrodata } from "./skill/microdata.js";
 
 // Behaviour formatters
 export {
@@ -33,6 +39,10 @@ export {
   behaviourToMarkdown,
 } from "./behaviour/markdown.js";
 export { behaviourToDOM } from "./behaviour/dom.js";
+export {
+  behaviourListToMicrodata,
+  behaviourToMicrodata,
+} from "./behaviour/microdata.js";
 
 // Discipline formatters
 export {
@@ -40,11 +50,32 @@ export {
   disciplineToMarkdown,
 } from "./discipline/markdown.js";
 export { disciplineToDOM } from "./discipline/dom.js";
+export {
+  disciplineListToMicrodata,
+  disciplineToMicrodata,
+} from "./discipline/microdata.js";
 
 // Grade formatters
 export { gradeListToMarkdown, gradeToMarkdown } from "./grade/markdown.js";
 export { gradeToDOM } from "./grade/dom.js";
+export { gradeListToMicrodata, gradeToMicrodata } from "./grade/microdata.js";
 
 // Track formatters
 export { trackListToMarkdown, trackToMarkdown } from "./track/markdown.js";
 export { trackToDOM } from "./track/dom.js";
+export { trackListToMicrodata, trackToMicrodata } from "./track/microdata.js";
+
+// Stage formatters
+export { stageListToMicrodata, stageToMicrodata } from "./stage/microdata.js";
+
+// JSON-LD formatters
+export {
+  createJsonLdScript,
+  skillToJsonLd,
+  behaviourToJsonLd,
+  disciplineToJsonLd,
+  trackToJsonLd,
+  gradeToJsonLd,
+  driverToJsonLd,
+  stageToJsonLd,
+} from "./json-ld.js";

package/app/formatters/interview/shared.js

@@ -116,7 +116,7 @@ export function prepareInterviewDetail({
   questions,
   interviewType = "full",
 }) {
-  if (!discipline || !grade || !track) return null;
+  if (!discipline || !grade) return null;
 
   const job = getOrCreateJob({
     discipline,
@@ -171,8 +171,8 @@ export function prepareInterviewDetail({
     disciplineId: discipline.id,
     disciplineName: discipline.specialization || discipline.name,
     gradeId: grade.id,
-    trackId: track.id,
-    trackName: track.name,
+    trackId: track?.id || null,
+    trackName: track?.name || null,
     sections: allSections,
     totalQuestions,
     expectedDurationMinutes: typeConfig.expectedDurationMinutes,
@@ -206,7 +206,8 @@ export function prepareInterviewBuilderPreview({
   behaviourCount,
   grades,
 }) {
-  if (!discipline || !grade || !track) {
+  // Track is optional (null = generalist)
+  if (!discipline || !grade) {
     return {
       isValid: false,
       title: null,
@@ -224,12 +225,15 @@ export function prepareInterviewBuilderPreview({
   });
 
   if (!validCombination) {
+    const reason = track
+      ? `The ${track.name} track is not available for ${discipline.specialization}.`
+      : `${discipline.specialization} requires a track specialization.`;
     return {
       isValid: false,
       title: null,
       totalSkills: 0,
       totalBehaviours: 0,
-      invalidReason: `The ${track.name} track is not available for ${discipline.specialization}.`,
+      invalidReason: reason,
     };
   }
 
@@ -275,7 +279,8 @@ export function prepareAllInterviews({
   behaviours,
   questions,
 }) {
-  if (!discipline || !grade || !track) return null;
+  // Track is optional (null = generalist)
+  if (!discipline || !grade) return null;
 
   const job = getOrCreateJob({
     discipline,
@@ -313,8 +318,8 @@ export function prepareAllInterviews({
     disciplineId: discipline.id,
     disciplineName: discipline.specialization || discipline.name,
     gradeId: grade.id,
-    trackId: track.id,
-    trackName: track.name,
+    trackId: track?.id || null,
+    trackName: track?.name || null,
     interviews: {
       short: {
         ...shortInterview,

package/app/formatters/job/description.js

@@ -29,7 +29,9 @@ export function formatJobDescription({ job, discipline, grade, track }) {
   // Meta information
   lines.push(`- **Level:** ${grade.id}`);
   lines.push(`- **Experience:** ${grade.typicalExperienceRange}`);
-  lines.push(`- **Track:** ${track.name}`);
+  if (track) {
+    lines.push(`- **Track:** ${track.name}`);
+  }
   lines.push("");
 
   // Role Summary
@@ -37,7 +39,7 @@ export function formatJobDescription({ job, discipline, grade, track }) {
   lines.push("");
 
   // Build role summary from discipline - use manager version if applicable
-  const isManagement = track.isManagement === true;
+  const isManagement = discipline.isManagement === true;
   let roleSummary =
     isManagement && discipline.managementRoleSummary
       ? discipline.managementRoleSummary
@@ -50,7 +52,7 @@ export function formatJobDescription({ job, discipline, grade, track }) {
   lines.push("");
 
   // Add track context
-  if (track.roleContext) {
+  if (track?.roleContext) {
     lines.push(track.roleContext);
     lines.push("");
   }

package/app/formatters/json-ld.js

@@ -0,0 +1,242 @@
+/**
+ * JSON-LD structured data generation
+ *
+ * Generates JSON-LD for entity pages to enable machine-readable data.
+ * Aligns with the RDF schema at https://schema.forwardimpact.team/rdf/
+ */
+
+const VOCAB_BASE = "https://schema.forwardimpact.team/rdf/";
+
+/**
+ * Create a JSON-LD script element
+ * @param {Object} data - JSON-LD data object
+ * @returns {HTMLScriptElement}
+ */
+export function createJsonLdScript(data) {
+  const script = document.createElement("script");
+  script.type = "application/ld+json";
+  script.textContent = JSON.stringify(data, null, 2);
+  return script;
+}
+
+/**
+ * Build base JSON-LD context and type
+ * @param {string} type - Entity type (without vocab prefix)
+ * @param {string} id - Entity ID
+ * @returns {Object}
+ */
+function baseJsonLd(type, id) {
+  return {
+    "@context": VOCAB_BASE,
+    "@type": type,
+    "@id": `${VOCAB_BASE}${type}/${id}`,
+  };
+}
+
+/**
+ * Generate JSON-LD for a skill entity
+ * @param {Object} skill - Raw skill entity
+ * @param {Object} context - Additional context
+ * @param {Array} [context.capabilities] - Capability entities
+ * @returns {Object}
+ */
+export function skillToJsonLd(skill, { capabilities = [] } = {}) {
+  const capability = capabilities.find((c) => c.id === skill.capability);
+
+  return {
+    ...baseJsonLd("Skill", skill.id),
+    identifier: skill.id,
+    name: skill.name,
+    description: skill.description,
+    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,
+      }),
+    ),
+  };
+}
+
+/**
+ * Generate JSON-LD for a behaviour entity
+ * @param {Object} behaviour - Raw behaviour entity
+ * @returns {Object}
+ */
+export function behaviourToJsonLd(behaviour) {
+  return {
+    ...baseJsonLd("Behaviour", behaviour.id),
+    identifier: behaviour.id,
+    name: behaviour.name,
+    description: behaviour.description,
+    maturityDescriptions: Object.entries(
+      behaviour.maturityDescriptions || {},
+    ).map(([maturity, description]) => ({
+      "@type": "BehaviourMaturityDescription",
+      maturity: `${VOCAB_BASE}${maturity}`,
+      description,
+    })),
+  };
+}
+
+/**
+ * Generate JSON-LD for a discipline entity
+ * @param {Object} discipline - Raw discipline entity
+ * @param {Object} context - Additional context
+ * @param {Array} [context.skills] - All skills
+ * @returns {Object}
+ */
+export function disciplineToJsonLd(discipline, { skills = [] } = {}) {
+  const resolveSkillNames = (skillIds) =>
+    (skillIds || [])
+      .map((id) => {
+        const skill = skills.find((s) => s.id === id);
+        return skill
+          ? { "@id": `${VOCAB_BASE}Skill/${id}`, name: skill.name }
+          : null;
+      })
+      .filter(Boolean);
+
+  return {
+    ...baseJsonLd("Discipline", discipline.id),
+    identifier: discipline.id,
+    name: discipline.name,
+    ...(discipline.specialization && {
+      specialization: discipline.specialization,
+    }),
+    description: discipline.description,
+    coreSkills: resolveSkillNames(discipline.coreSkills),
+    supportingSkills: resolveSkillNames(discipline.supportingSkills),
+    broadSkills: resolveSkillNames(discipline.broadSkills),
+  };
+}
+
+/**
+ * Generate JSON-LD for a track entity
+ * @param {Object} track - Raw track entity
+ * @returns {Object}
+ */
+export function trackToJsonLd(track) {
+  return {
+    ...baseJsonLd("Track", track.id),
+    identifier: track.id,
+    name: track.name,
+    description: track.description,
+    ...(track.skillModifiers && {
+      skillModifiers: Object.entries(track.skillModifiers).map(
+        ([capability, modifier]) => ({
+          "@type": "SkillModifier",
+          capability,
+          modifier,
+        }),
+      ),
+    }),
+    ...(track.behaviourModifiers && {
+      behaviourModifiers: Object.entries(track.behaviourModifiers).map(
+        ([behaviour, modifier]) => ({
+          "@type": "BehaviourModifier",
+          behaviour,
+          modifier,
+        }),
+      ),
+    }),
+  };
+}
+
+/**
+ * Generate JSON-LD for a grade entity
+ * @param {Object} grade - Raw grade entity
+ * @returns {Object}
+ */
+export function gradeToJsonLd(grade) {
+  return {
+    ...baseJsonLd("Grade", grade.id),
+    identifier: grade.id,
+    name: grade.displayName || grade.name,
+    ...(grade.ordinalRank && { ordinalRank: grade.ordinalRank }),
+    ...(grade.typicalExperienceRange && {
+      typicalExperienceRange: grade.typicalExperienceRange,
+    }),
+    ...(grade.baseSkillLevels && {
+      baseSkillLevels: {
+        "@type": "BaseSkillLevels",
+        primary: `${VOCAB_BASE}${grade.baseSkillLevels.primary}`,
+        secondary: `${VOCAB_BASE}${grade.baseSkillLevels.secondary}`,
+        broad: `${VOCAB_BASE}${grade.baseSkillLevels.broad}`,
+      },
+    }),
+    ...(grade.baseBehaviourMaturity && {
+      baseBehaviourMaturity: `${VOCAB_BASE}${grade.baseBehaviourMaturity}`,
+    }),
+  };
+}
+
+/**
+ * Generate JSON-LD for a driver entity
+ * @param {Object} driver - Raw driver entity
+ * @param {Object} context - Additional context
+ * @param {Array} [context.skills] - All skills
+ * @param {Array} [context.behaviours] - All behaviours
+ * @returns {Object}
+ */
+export function driverToJsonLd(driver, { skills = [], behaviours = [] } = {}) {
+  const resolveSkills = (skillIds) =>
+    (skillIds || [])
+      .map((id) => {
+        const skill = skills.find((s) => s.id === id);
+        return skill
+          ? { "@id": `${VOCAB_BASE}Skill/${id}`, name: skill.name }
+          : null;
+      })
+      .filter(Boolean);
+
+  const resolveBehaviours = (behaviourIds) =>
+    (behaviourIds || [])
+      .map((id) => {
+        const behaviour = behaviours.find((b) => b.id === id);
+        return behaviour
+          ? { "@id": `${VOCAB_BASE}Behaviour/${id}`, name: behaviour.name }
+          : null;
+      })
+      .filter(Boolean);
+
+  return {
+    ...baseJsonLd("Driver", driver.id),
+    identifier: driver.id,
+    name: driver.name,
+    description: driver.description,
+    ...(driver.contributingSkills?.length > 0 && {
+      contributingSkills: resolveSkills(driver.contributingSkills),
+    }),
+    ...(driver.contributingBehaviours?.length > 0 && {
+      contributingBehaviours: resolveBehaviours(driver.contributingBehaviours),
+    }),
+  };
+}
+
+/**
+ * Generate JSON-LD for a stage entity
+ * @param {Object} stage - Raw stage entity
+ * @returns {Object}
+ */
+export function stageToJsonLd(stage) {
+  return {
+    ...baseJsonLd("Stage", stage.id),
+    identifier: stage.id,
+    name: stage.name,
+    description: stage.description,
+    ...(stage.emoji && { emoji: stage.emoji }),
+    ...(stage.tools?.length > 0 && { tools: stage.tools }),
+    ...(stage.constraints?.length > 0 && { constraints: stage.constraints }),
+    ...(stage.handoffs && {
+      handoffs: Object.entries(stage.handoffs).map(([targetStage, config]) => ({
+        "@type": "StageHandoff",
+        targetStage: `${VOCAB_BASE}Stage/${targetStage}`,
+        ...(config.prompt && { prompt: config.prompt }),
+      })),
+    }),
+  };
+}

package/app/formatters/microdata-shared.js

@@ -0,0 +1,184 @@
+/**
+ * Shared microdata HTML utilities
+ *
+ * Helper functions for generating clean, class-less HTML with microdata attributes
+ * aligned with the RDF schema at https://schema.forwardimpact.team/rdf/
+ */
+
+const VOCAB_BASE = "https://schema.forwardimpact.team/rdf/";
+
+/**
+ * Create an opening tag with microdata attributes
+ * @param {string} tag - HTML tag name
+ * @param {Object} [attrs] - Optional attributes
+ * @param {string} [attrs.itemtype] - Microdata type (without vocab prefix)
+ * @param {string} [attrs.itemprop] - Microdata property name
+ * @param {string} [attrs.itemid] - Microdata item ID
+ * @returns {string}
+ */
+export function openTag(tag, attrs = {}) {
+  const parts = [tag];
+
+  if (attrs.itemtype) {
+    parts.push(`itemscope`);
+    parts.push(`itemtype="${VOCAB_BASE}${attrs.itemtype}"`);
+  }
+
+  if (attrs.itemprop) {
+    parts.push(`itemprop="${attrs.itemprop}"`);
+  }
+
+  if (attrs.itemid) {
+    parts.push(`itemid="${attrs.itemid}"`);
+  }
+
+  return `<${parts.join(" ")}>`;
+}
+
+/**
+ * Create a self-closing meta element with microdata
+ * @param {string} itemprop - Property name
+ * @param {string} content - Content value
+ * @returns {string}
+ */
+export function metaTag(itemprop, content) {
+  return `<meta itemprop="${itemprop}" content="${escapeAttr(content)}">`;
+}
+
+/**
+ * Create a link element with microdata
+ * @param {string} itemprop - Property name
+ * @param {string} href - Link target
+ * @returns {string}
+ */
+export function linkTag(itemprop, href) {
+  return `<link itemprop="${itemprop}" href="${escapeAttr(href)}">`;
+}
+
+/**
+ * Wrap content in an element with itemprop
+ * @param {string} tag - HTML tag name
+ * @param {string} itemprop - Property name
+ * @param {string} content - Content to wrap
+ * @returns {string}
+ */
+export function prop(tag, itemprop, content) {
+  return `<${tag} itemprop="${itemprop}">${escapeHtml(content)}</${tag}>`;
+}
+
+/**
+ * Wrap raw HTML content in an element with itemprop (no escaping)
+ * @param {string} tag - HTML tag name
+ * @param {string} itemprop - Property name
+ * @param {string} html - HTML content to wrap
+ * @returns {string}
+ */
+export function propRaw(tag, itemprop, html) {
+  return `<${tag} itemprop="${itemprop}">${html}</${tag}>`;
+}
+
+/**
+ * Create a section with optional heading
+ * @param {string} heading - Section heading text
+ * @param {string} content - Section content
+ * @param {number} [level=2] - Heading level (2-6)
+ * @returns {string}
+ */
+export function section(heading, content, level = 2) {
+  const hTag = `h${Math.min(Math.max(level, 1), 6)}`;
+  return `<section>
+<${hTag}>${escapeHtml(heading)}</${hTag}>
+${content}
+</section>`;
+}
+
+/**
+ * Create an unordered list
+ * @param {string[]} items - List items (already HTML)
+ * @param {string} [itemprop] - Optional property for list items
+ * @returns {string}
+ */
+export function ul(items, itemprop) {
+  if (!items.length) return "";
+  const lis = items
+    .map((item) =>
+      itemprop ? `<li itemprop="${itemprop}">${item}</li>` : `<li>${item}</li>`,
+    )
+    .join("\n");
+  return `<ul>\n${lis}\n</ul>`;
+}
+
+/**
+ * Create a definition list from key-value pairs
+ * @param {Array<{term: string, definition: string, itemprop?: string}>} pairs
+ * @returns {string}
+ */
+export function dl(pairs) {
+  if (!pairs.length) return "";
+  const content = pairs
+    .map(({ term, definition, itemprop }) => {
+      const dd = itemprop
+        ? `<dd itemprop="${itemprop}">${escapeHtml(definition)}</dd>`
+        : `<dd>${escapeHtml(definition)}</dd>`;
+      return `<dt>${escapeHtml(term)}</dt>\n${dd}`;
+    })
+    .join("\n");
+  return `<dl>\n${content}\n</dl>`;
+}
+
+/**
+ * Escape HTML special characters
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+  if (str == null) return "";
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Escape attribute value
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeAttr(str) {
+  if (str == null) return "";
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Format level name for display (capitalize, replace underscores)
+ * @param {string} level
+ * @returns {string}
+ */
+export function formatLevelName(level) {
+  if (!level) return "";
+  return level.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Generate a full microdata HTML document
+ * @param {string} title - Document title
+ * @param {string} body - Body content
+ * @returns {string}
+ */
+export function htmlDocument(title, body) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}

package/app/formatters/progress/shared.js

@@ -67,7 +67,7 @@ export function prepareCurrentJob({
   behaviours,
   capabilities,
 }) {
-  if (!discipline || !grade || !track) return null;
+  if (!discipline || !grade) return null;
 
   const job = getOrCreateJob({
     discipline,
@@ -117,7 +117,8 @@ export function prepareCareerProgressPreview({
   grades,
   tracks,
 }) {
-  if (!discipline || !grade || !track) {
+  // Track is optional (null = generalist)
+  if (!discipline || !grade) {
     return {
       isValid: false,
       title: null,
@@ -135,12 +136,13 @@ export function prepareCareerProgressPreview({
   });
 
   if (!validCombination) {
+    const reason = track
+      ? `The ${track.name} track is not available for ${discipline.specialization}.`
+      : `${discipline.specialization} requires a track specialization.`;
     return {
       isValid: false,
       title: null,
-      invalidReason: track.validDisciplines
-        ? `The ${track.name} track is only available for certain disciplines.`
-        : "This combination is not valid.",
+      invalidReason: reason,
       nextGrade: null,
       validTracks: [],
     };
@@ -149,10 +151,10 @@ export function prepareCareerProgressPreview({
   const title = generateJobTitle(discipline, grade, track);
   const nextGrade = getNextGrade(grade, grades);
 
-  // Find other valid tracks for comparison
+  // Find other valid tracks for comparison (exclude current track if any)
   const validTracks = tracks.filter(
     (t) =>
-      t.id !== track.id &&
+      (!track || t.id !== track.id) &&
       isValidJobCombination({ discipline, grade, track: t, grades }),
   );
 
@@ -203,8 +205,9 @@ export function prepareProgressDetail({
   behaviours,
   capabilities,
 }) {
-  if (!fromDiscipline || !fromGrade || !fromTrack) return null;
-  if (!toDiscipline || !toGrade || !toTrack) return null;
+  // Track is optional (null = generalist)
+  if (!fromDiscipline || !fromGrade) return null;
+  if (!toDiscipline || !toGrade) return null;
 
   const fromJob = getOrCreateJob({
     discipline: fromDiscipline,
@@ -263,12 +266,12 @@ export function prepareProgressDetail({
     fromJob: {
       disciplineId: fromDiscipline.id,
       gradeId: fromGrade.id,
-      trackId: fromTrack.id,
+      trackId: fromTrack?.id || null,
     },
     toJob: {
       disciplineId: toDiscipline.id,
       gradeId: toGrade.id,
-      trackId: toTrack.id,
+      trackId: toTrack?.id || null,
     },
     skillChanges,
     behaviourChanges,

package/app/formatters/skill/dom.js

@@ -20,6 +20,7 @@ import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
 import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
 import { prepareSkillDetail, formatCapability } from "./shared.js";
+import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
 
 /**
  * Format skill detail as DOM elements
@@ -44,6 +45,8 @@ export function skillToDOM(
   });
   return div(
     { className: "detail-page skill-detail" },
+    // JSON-LD structured data
+    createJsonLdScript(skillToJsonLd(skill, { capabilities })),
     // Header
     div(
       { className: "page-header" },