sdtk-design-kit 0.1.1 → 0.2.0

package/src/lib/screen-briefs.js

@@ -0,0 +1,340 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { describeDesignPaths } = require("./design-paths");
+const { ValidationError } = require("./errors");
+
+function escapeMarkdown(value) {
+  return String(value || "").replace(/\r?\n/g, " ").trim();
+}
+
+function toScreenBriefFileName(screenId) {
+  return `${String(screenId || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")}_DESIGN_BRIEF.md`;
+}
+
+function toJsonFileName(screenId) {
+  return `${String(screenId || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")}.json`;
+}
+
+function cleanArray(values) {
+  return Array.isArray(values)
+    ? values.map((item) => String(item || "").trim()).filter(Boolean)
+    : [];
+}
+
+function uniqueStrings(values) {
+  return Array.from(new Set(cleanArray(values)));
+}
+
+function needs(marker) {
+  return `NEEDS_${marker}`;
+}
+
+function listOrNeeds(values, marker) {
+  const items = cleanArray(values);
+  if (items.length > 0) {
+    return items.map((item) => `- ${escapeMarkdown(item)}`).join("\n");
+  }
+  return `- ${needs(marker)}`;
+}
+
+function tokenUsageOrDefault(value) {
+  const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const tokenUsage = {
+    palette_keys: cleanArray(payload.palette_keys || payload.paletteKeys),
+    typography_keys: cleanArray(payload.typography_keys || payload.typographyKeys),
+    spacing_keys: cleanArray(payload.spacing_keys || payload.spacingKeys),
+    radius_keys: cleanArray(payload.radius_keys || payload.radiusKeys),
+  };
+  if (
+    tokenUsage.palette_keys.length === 0 &&
+    tokenUsage.typography_keys.length === 0 &&
+    tokenUsage.spacing_keys.length === 0 &&
+    tokenUsage.radius_keys.length === 0
+  ) {
+    return {
+      palette_keys: ["color.surface", "color.textPrimary", "color.accentPrimary"],
+      typography_keys: ["typography.fontFamily", "typography.uiWeight"],
+      spacing_keys: ["spacing.md", "spacing.lg", "spacing.sectionGap"],
+      radius_keys: ["radius.card", "radius.control"],
+    };
+  }
+  return tokenUsage;
+}
+
+function tokenUsageMarkdown(tokenUsage) {
+  return [
+    `- Palette keys: ${tokenUsage.palette_keys.length > 0 ? tokenUsage.palette_keys.join(", ") : needs("PALETTE_KEYS")}`,
+    `- Typography keys: ${tokenUsage.typography_keys.length > 0 ? tokenUsage.typography_keys.join(", ") : needs("TYPOGRAPHY_KEYS")}`,
+    `- Spacing keys: ${tokenUsage.spacing_keys.length > 0 ? tokenUsage.spacing_keys.join(", ") : needs("SPACING_KEYS")}`,
+    `- Radius keys: ${tokenUsage.radius_keys.length > 0 ? tokenUsage.radius_keys.join(", ") : needs("RADIUS_KEYS")}`,
+  ].join("\n");
+}
+
+function layoutModelForRole(templateRole) {
+  const models = {
+    home: "hero-catalog-support",
+    category: "filter-and-results",
+    "product-detail": "split-detail-with-purchase-panel",
+    search: "search-toolbar-results",
+    cart: "line-item-table-with-summary",
+    checkout: "stepper-with-order-summary",
+    "order-history": "table-list-with-filters",
+    "order-detail": "timeline-detail-summary",
+    "account-info": "sidebar-form-shell",
+    "configurator-bom": "wizard-with-preview-and-table",
+  };
+  return models[templateRole] || null;
+}
+
+function densityForRole(templateRole) {
+  const highDensityRoles = new Set(["checkout", "cart", "configurator-bom", "order-detail"]);
+  const mediumDensityRoles = new Set(["product-detail", "category", "search", "order-history", "account-info"]);
+  if (highDensityRoles.has(templateRole)) return "high";
+  if (mediumDensityRoles.has(templateRole)) return "medium";
+  return null;
+}
+
+function sectionMarkdown(sections) {
+  if (!Array.isArray(sections) || sections.length === 0) {
+    return `- ${needs("SECTIONS")}`;
+  }
+  return sections
+    .map((section, index) => {
+      const title = escapeMarkdown(section.title || `Section ${index + 1}`);
+      const details = [];
+      if (section.purpose) details.push(`purpose=${escapeMarkdown(section.purpose)}`);
+      if (Array.isArray(section.components) && section.components.length > 0) {
+        details.push(`components=${section.components.map(escapeMarkdown).join(", ")}`);
+      }
+      if (Array.isArray(section.data_slots) && section.data_slots.length > 0) {
+        details.push(`data=${section.data_slots.map(escapeMarkdown).join(", ")}`);
+      }
+      if (Array.isArray(section.states) && section.states.length > 0) {
+        details.push(`states=${section.states.map(escapeMarkdown).join(", ")}`);
+      }
+      return `- ${title}${details.length > 0 ? ` (${details.join("; ")})` : ""}`;
+    })
+    .join("\n");
+}
+
+function flattenSectionValues(sections, key) {
+  if (!Array.isArray(sections)) {
+    return [];
+  }
+  return uniqueStrings(sections.flatMap((section) => cleanArray(section && section[key])));
+}
+
+function profileRoleHints(profilePrimitives, templateRole, screenId) {
+  if (!profilePrimitives || !profilePrimitives.screenRoleHints) {
+    return [];
+  }
+  const hints = profilePrimitives.screenRoleHints[screenId] || profilePrimitives.screenRoleHints[templateRole];
+  return cleanArray(hints);
+}
+
+function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceArtifacts }) {
+  const templateRole = screen.templateRole || "generic";
+  const sections = Array.isArray(screen.sections) ? screen.sections : [];
+  const sectionComponents = flattenSectionValues(sections, "components");
+  const sectionStates = flattenSectionValues(sections, "states");
+  const sectionInteractions = flattenSectionValues(sections, "interactions");
+  const sectionDataSlots = flattenSectionValues(sections, "data_slots");
+  const componentHints = profileRoleHints(profilePrimitives, templateRole, screen.screenId);
+  const components = uniqueStrings([...(screen.requiredComponents || []), ...sectionComponents, ...componentHints]);
+  const states = uniqueStrings([...(screen.requiredStates || []), ...sectionStates]);
+  const interactions = uniqueStrings([
+    ...(screen.interactions || []),
+    ...sectionInteractions,
+    ...(screen.primaryAction ? [`Primary action: ${screen.primaryAction}`] : []),
+  ]);
+  const dataSlots = uniqueStrings([...(screen.dataSlots || []), ...sectionDataSlots]);
+  const sourceEvidence = screen.sourceEvidence || {};
+  const supportingArtifacts = cleanArray(sourceArtifacts);
+  const model = {
+    schema: "sdtk.design.screen-brief.v2",
+    screen_id: screen.screenId,
+    screen_title: screen.title,
+    purpose: screen.purpose || needs("SCREEN_PURPOSE"),
+    user_intent: screen.userIntent || needs("USER_INTENT"),
+    route: screen.route || needs("ROUTE"),
+    sections,
+    section_titles: sections.map((section) => section.title).filter(Boolean),
+    layout_model: screen.layoutModel || layoutModelForRole(templateRole) || needs("LAYOUT_MODEL"),
+    density: screen.density || densityForRole(templateRole) || needs("DENSITY"),
+    components: components.length > 0 ? components : [needs("COMPONENTS")],
+    states: states.length > 0 ? states : [needs("STATES")],
+    interactions: interactions.length > 0 ? interactions : [needs("INTERACTIONS")],
+    data_slots: dataSlots.length > 0 ? dataSlots : [needs("DATA_SLOTS")],
+    accessibility_notes:
+      cleanArray(screen.accessibilityNotes).length > 0
+        ? cleanArray(screen.accessibilityNotes)
+        : [
+            "Use one screen-level heading before nested section headings.",
+            "Expose keyboard focus order for navigation, filters, forms, and primary actions.",
+            "Keep contrast and touch target sizing aligned with DESIGN_TOKENS guidance.",
+          ],
+    visual_token_usage: tokenUsageOrDefault(screen.visualTokenUsage),
+    acceptance_criteria:
+      cleanArray(screen.acceptanceCriteria).length > 0
+        ? cleanArray(screen.acceptanceCriteria)
+        : [needs("ACCEPTANCE_CRITERIA")],
+    template_role: templateRole,
+    source_evidence: {
+      source_artifact: sourceEvidence.source_artifact || screen.sourceArtifact || null,
+      source_status: sourceEvidence.source_status || screen.sourceStatus || "explicit",
+      source_quote: sourceEvidence.source_quote || needs("SOURCE_QUOTE"),
+      source_line_range: Array.isArray(sourceEvidence.source_line_range)
+        ? sourceEvidence.source_line_range
+        : null,
+      supporting_artifacts: supportingArtifacts,
+    },
+    profile: profileSelection || "generic",
+    confidence: screen.confidence || "low",
+  };
+  model.gaps = [
+    model.purpose,
+    model.user_intent,
+    model.route,
+    model.layout_model,
+    model.density,
+    ...model.components,
+    ...model.states,
+    ...model.interactions,
+    ...model.data_slots,
+    ...model.acceptance_criteria,
+    model.source_evidence.source_quote,
+  ].filter((value) => String(value).startsWith("NEEDS_"));
+  return model;
+}
+
+function renderScreenBrief({ screen, profileSelection, profilePrimitives, sourceArtifacts }) {
+  const model = buildBriefModel({ screen, profileSelection, profilePrimitives, sourceArtifacts });
+
+  return `# Screen Design Brief: ${escapeMarkdown(screen.title)}
+
+## Screen Meta
+- Screen ID: ${escapeMarkdown(screen.screenId)}
+- Template role: ${escapeMarkdown(model.template_role)}
+- Profile: ${escapeMarkdown(profileSelection || "none")}
+- Confidence: ${escapeMarkdown(model.confidence)}
+
+## Screen Purpose And User Intent
+- Purpose: ${escapeMarkdown(model.purpose)}
+- User intent: ${escapeMarkdown(model.user_intent)}
+
+## Route
+- Route: ${escapeMarkdown(model.route)}
+
+## Required Sections Top To Bottom
+${sectionMarkdown(model.sections)}
+
+## Layout Model And Density
+- Layout model: ${escapeMarkdown(model.layout_model)}
+- Density: ${escapeMarkdown(model.density)}
+- Navigation: preserve deterministic route and section order from explicit screen model.
+
+## Component Requirements
+${listOrNeeds(model.components, "COMPONENTS")}
+
+## State Requirements
+${listOrNeeds(model.states, "STATES")}
+
+## Interaction Notes
+${listOrNeeds(model.interactions, "INTERACTIONS")}
+
+## Data / Content Slots
+${listOrNeeds(model.data_slots, "DATA_SLOTS")}
+
+## Visual Token Usage
+${tokenUsageMarkdown(model.visual_token_usage)}
+
+## Accessibility Notes
+${listOrNeeds(model.accessibility_notes, "ACCESSIBILITY_NOTES")}
+
+## Acceptance Criteria
+${listOrNeeds(model.acceptance_criteria, "ACCEPTANCE_CRITERIA")}
+
+## Source Evidence / Confidence
+- Source artifact: ${escapeMarkdown(model.source_evidence.source_artifact || needs("SOURCE_ARTIFACT"))}
+- Source status: ${escapeMarkdown(model.source_evidence.source_status)}
+- Source quote: ${escapeMarkdown(model.source_evidence.source_quote)}
+- Source line range: ${Array.isArray(model.source_evidence.source_line_range) ? model.source_evidence.source_line_range.join("-") : needs("SOURCE_LINE_RANGE")}
+- Confidence level: ${escapeMarkdown(model.confidence)}
+- Supporting explicit artifacts:
+${model.source_evidence.supporting_artifacts.length > 0 ? model.source_evidence.supporting_artifacts.map((item) => `  - ${escapeMarkdown(item)}`).join("\n") : `  - ${needs("SUPPORTING_ARTIFACTS")}`}
+`;
+}
+
+function writeScreenBriefArtifacts(projectPath, inputContractState) {
+  const paths = describeDesignPaths(projectPath);
+  if (
+    !inputContractState ||
+    inputContractState.analysisStatus !== "INPUT_CONTRACT_READY" ||
+    !inputContractState.screenModel ||
+    !Array.isArray(inputContractState.screenModel.screens) ||
+    inputContractState.screenModel.screens.length === 0
+  ) {
+    throw new ValidationError(
+      "Screen brief generation requires INPUT_CONTRACT_READY with at least one explicit screen model entry."
+    );
+  }
+
+  fs.mkdirSync(paths.screensPath, { recursive: true });
+  fs.mkdirSync(paths.designScreenBriefsStatePath, { recursive: true });
+
+  const sourceArtifacts = Object.values(inputContractState.artifacts || {})
+    .filter((artifact) => artifact && artifact.found && artifact.relativeToSpecRoot)
+    .map((artifact) => artifact.relativeToSpecRoot);
+
+  const generated = [];
+  for (const screen of inputContractState.screenModel.screens) {
+    const mdFileName = toScreenBriefFileName(screen.screenId);
+    const jsonFileName = toJsonFileName(screen.screenId);
+    const markdownPath = path.join(paths.screensPath, mdFileName);
+    const sidecarPath = path.join(paths.designScreenBriefsStatePath, jsonFileName);
+    const markdown = renderScreenBrief({
+      screen,
+      profileSelection: inputContractState.profileSelection || null,
+      profilePrimitives: inputContractState.profilePrimitives || null,
+      sourceArtifacts,
+    });
+    const briefModel = buildBriefModel({
+      screen,
+      profileSelection: inputContractState.profileSelection || null,
+      profilePrimitives: inputContractState.profilePrimitives || null,
+      sourceArtifacts,
+    });
+    const sidecar = {
+      ...briefModel,
+      primary_action: screen.primaryAction || null,
+      required_states: briefModel.states,
+      major_sections: briefModel.section_titles,
+      profile: briefModel.profile,
+      confidence: briefModel.confidence,
+      source_artifact: screen.sourceArtifact || null,
+    };
+    fs.writeFileSync(markdownPath, `${markdown}\n`, "utf-8");
+    fs.writeFileSync(sidecarPath, `${JSON.stringify(sidecar, null, 2)}\n`, "utf-8");
+    generated.push({
+      screenId: screen.screenId,
+      markdownRelativePath: path.relative(projectPath, markdownPath).split(path.sep).join("/"),
+      sidecarRelativePath: path.relative(projectPath, sidecarPath).split(path.sep).join("/"),
+    });
+  }
+
+  return {
+    generatedCount: generated.length,
+    generated,
+  };
+}
+
+module.exports = {
+  buildBriefModel,
+  writeScreenBriefArtifacts,
+};