@forwardimpact/pathway 0.1.0 → 0.3.0

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/shared.js

@@ -36,7 +36,7 @@ export function tableToMarkdown(headers, rows) {
 export function objectToMarkdownList(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
   return Object.entries(obj)
-    .map(([key, value]) => `${prefix}- **${key}**: ${value}`)
+    .map(([key, value]) => `${prefix}- **${capitalize(key)}**: ${value}`)
     .join("\n");
 }
 
@@ -51,12 +51,17 @@ export function formatPercent(value) {
 
 /**
  * Capitalize first letter of each word
+ * Handles both snake_case and camelCase
  * @param {string} str
  * @returns {string}
  */
 export function capitalize(str) {
   if (!str) return "";
-  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  // Insert space before uppercase letters (for camelCase), then handle snake_case
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /**

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" },

package/app/formatters/skill/microdata.js

@@ -0,0 +1,151 @@
+/**
+ * Skill formatting for microdata HTML output
+ *
+ * Generates clean, class-less HTML with microdata aligned with capability.schema.json
+ * RDF vocab: https://schema.forwardimpact.team/rdf/
+ */
+
+import {
+  openTag,
+  prop,
+  propRaw,
+  metaTag,
+  section,
+  dl,
+  ul,
+  escapeHtml,
+  formatLevelName,
+  htmlDocument,
+} from "../microdata-shared.js";
+import { prepareSkillsList, prepareSkillDetail } from "./shared.js";
+
+/**
+ * Format skill list as microdata HTML
+ * @param {Array} skills - Raw skill entities
+ * @param {Array} capabilities - Capability entities
+ * @returns {string} HTML with microdata
+ */
+export function skillListToMicrodata(skills, capabilities) {
+  const { groups, groupOrder } = prepareSkillsList(skills, capabilities);
+
+  const content = groupOrder
+    .map((capability) => {
+      const capabilitySkills = groups[capability];
+      const skillItems = capabilitySkills
+        .map(
+          (
+            skill,
+          ) => `${openTag("article", { itemtype: "Skill", itemid: `#${skill.id}` })}
+${prop("h3", "name", skill.name)}
+${prop("p", "description", skill.truncatedDescription)}
+${metaTag("capability", capability)}
+</article>`,
+        )
+        .join("\n");
+
+      return section(formatLevelName(capability), skillItems, 2);
+    })
+    .join("\n");
+
+  return htmlDocument(
+    "Skills",
+    `<main>
+<h1>Skills</h1>
+${content}
+</main>`,
+  );
+}
+
+/**
+ * Format skill detail as microdata HTML
+ * @param {Object} skill - Raw skill entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Array} context.tracks - All tracks
+ * @param {Array} context.drivers - All drivers
+ * @param {Array} context.capabilities - Capability entities
+ * @returns {string} HTML with microdata
+ */
+export function skillToMicrodata(
+  skill,
+  { disciplines, tracks, drivers, capabilities },
+) {
+  const view = prepareSkillDetail(skill, {
+    disciplines,
+    tracks,
+    drivers,
+    capabilities,
+  });
+
+  if (!view) return "";
+
+  const sections = [];
+
+  // Human-only badge
+  if (view.isHumanOnly) {
+    sections.push(`<p><strong>Human-Only</strong> — Requires interpersonal skills; excluded from agents</p>
+${metaTag("isHumanOnly", "true")}`);
+  }
+
+  // Level descriptions - uses LevelDescriptions itemtype
+  const levelPairs = Object.entries(view.levelDescriptions).map(
+    ([level, desc]) => ({
+      term: formatLevelName(level),
+      definition: desc,
+      itemprop: `${level}Description`,
+    }),
+  );
+  sections.push(
+    section(
+      "Level Descriptions",
+      `${openTag("div", { itemtype: "LevelDescriptions", itemprop: "levelDescriptions" })}
+${dl(levelPairs)}
+</div>`,
+      2,
+    ),
+  );
+
+  // Related disciplines
+  if (view.relatedDisciplines.length > 0) {
+    const disciplineItems = view.relatedDisciplines.map(
+      (d) =>
+        `<a href="#${escapeHtml(d.id)}">${escapeHtml(d.name)}</a> (${escapeHtml(d.skillType)})`,
+    );
+    sections.push(section("Used in Disciplines", ul(disciplineItems), 2));
+  }
+
+  // Related tracks with modifiers
+  if (view.relatedTracks.length > 0) {
+    const trackItems = view.relatedTracks.map((t) => {
+      const modifierStr = t.modifier > 0 ? `+${t.modifier}` : `${t.modifier}`;
+      return `<a href="#${escapeHtml(t.id)}">${escapeHtml(t.name)}</a>: ${modifierStr}`;
+    });
+    sections.push(section("Modified by Tracks", ul(trackItems), 2));
+  }
+
+  // Related drivers
+  if (view.relatedDrivers.length > 0) {
+    const driverItems = view.relatedDrivers.map(
+      (d) => `<a href="#${escapeHtml(d.id)}">${escapeHtml(d.name)}</a>`,
+    );
+    sections.push(section("Linked to Drivers", ul(driverItems), 2));
+  }
+
+  const body = `<main>
+${openTag("article", { itemtype: "Skill", itemid: `#${view.id}` })}
+${prop("h1", "name", view.name)}
+${metaTag("id", view.id)}
+${metaTag("capability", view.capability)}
+${propRaw(
+  "div",
+  "human",
+  `${openTag("div", { itemtype: "SkillHumanSection" })}
+${prop("p", "description", view.description)}
+${sections.join("\n")}
+</div>`,
+)}
+</article>
+</main>`;
+
+  return htmlDocument(view.name, body);
+}