@topogram/cli 0.3.47 → 0.3.49

package/src/import/core/runner.js

@@ -2,6 +2,9 @@ import { IMPORT_TRACKS } from "./contracts.js";
 import { dedupeCandidateRecords, ensureTrailingNewline, idHintify, makeCandidateRecord } from "./shared.js";
 import { createImportContext } from "./context.js";
 import { getEnrichersForTrack, getExtractorsForTrack } from "./registry.js";
+import {
+  collectionPatternFromPresentations
+} from "../../ui/taxonomy.js";
 
 function parseImportTracks(fromValue) {
   if (!fromValue) {
@@ -95,25 +98,6 @@ function selectDetectionsForTrack(track, detections) {
   return detections;
 }
 
-function collectionPatternFromPresentations(presentations) {
-  if (presentations.includes("data_grid")) return "data_grid_view";
-  if (presentations.includes("table")) return "resource_table";
-  if (presentations.includes("cards")) return "resource_cards";
-  if (presentations.includes("board")) return "board_view";
-  if (presentations.includes("calendar")) return "calendar_view";
-  if (presentations.includes("gallery")) return "resource_cards";
-  return "search_results";
-}
-
-function presentationFromPattern(pattern) {
-  if (pattern === "data_grid_view") return "data_grid";
-  if (pattern === "resource_table") return "table";
-  if (pattern === "resource_cards") return "cards";
-  if (pattern === "board_view") return "board";
-  if (pattern === "calendar_view") return "calendar";
-  return "list";
-}
-
 function importedApiCapabilityIds(allCandidates) {
   return [...(allCandidates?.api?.capabilities || [])]
     .map((capability) => capability.id_hint)
@@ -181,6 +165,17 @@ function deriveUiComponentCandidates(candidates) {
       pattern,
       data_prop: "rows",
       data_source: loadCapability,
+      inferred_props: [{ name: "rows", type: "array", required: true, source: loadCapability }],
+      inferred_events: [],
+      inferred_region: "results",
+      inferred_pattern: pattern,
+      evidence: screen.provenance || [],
+      missing_decisions: [
+        "confirm component reuse boundary",
+        "confirm prop names and data source",
+        "confirm events and behavior",
+        "confirm supported regions and patterns"
+      ],
       notes: [
         "Imported component candidates are review-only.",
         "Confirm props, behavior, events, and reuse before adoption."
@@ -294,8 +289,11 @@ function reportMarkdown(track, candidates) {
     );
   }
   if (track === "ui") {
+    const componentLines = (candidates.components || []).map((component) =>
+      `- \`${component.id_hint}\` confidence ${component.confidence || "unknown"} pattern \`${component.pattern || component.inferred_pattern || "unknown"}\` region \`${component.region || component.inferred_region || "unknown"}\` evidence ${(component.evidence || component.provenance || []).length} missing decisions ${(component.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Component Candidates\n\n${componentLines.length ? componentLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topogram/candidates/app/ui/drafts/components/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram component check <path>\`, and \`topogram component behavior <path>\`.\n`
     );
   }
   if (track === "verification") {
@@ -327,7 +325,15 @@ function componentCandidateFileName(component) {
 }
 
 function renderComponentCandidate(component) {
+  const evidenceCount = (component.evidence || component.provenance || []).length;
+  const missingDecisions = component.missing_decisions || [
+    "confirm component reuse boundary",
+    "confirm prop names and data source",
+    "confirm events and behavior"
+  ];
   return `component ${component.id_hint} {
+  # Import metadata: confidence ${component.confidence || "unknown"}; evidence ${evidenceCount}; inferred pattern ${component.pattern || component.inferred_pattern || "search_results"}; inferred region ${component.region || component.inferred_region || "results"}.
+  # Missing decisions: ${missingDecisions.join("; ")}.
   name "${component.label || component.id_hint}"
   description "Candidate reusable component inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."
   category collection
@@ -353,6 +359,26 @@ function uiComponentLinesForCandidates(componentCandidates, allCandidates) {
     });
 }
 
+function enrichUiComponentDataSources(uiCandidates, allCandidates) {
+  if (!uiCandidates || !Array.isArray(uiCandidates.components)) {
+    return uiCandidates;
+  }
+  return {
+    ...uiCandidates,
+    components: uiCandidates.components.map((component) => {
+      const dataSource = inferredDataSourceForComponent(component, allCandidates);
+      const dataProp = component.data_prop || "rows";
+      return {
+        ...component,
+        data_source: component.data_source || dataSource,
+        inferred_props: (component.inferred_props || []).map((prop) =>
+          prop.name === dataProp ? { ...prop, source: prop.source || dataSource } : prop
+        )
+      };
+    })
+  };
+}
+
 function draftUiProjectionFiles(context, candidates, allCandidates = {}) {
   const ui = candidates || { screens: [], routes: [], actions: [], stacks: [] };
   const screens = [...(ui.screens || [])].sort((a, b) => String(a.route_path || "").localeCompare(String(b.route_path || "")) || a.id_hint.localeCompare(b.id_hint));
@@ -477,6 +503,20 @@ ${capabilityHints.length > 0 ? capabilityHints.map((hint) => `    ${hint}`).join
     shell ${shell}
 ${presentations.includes("search") ? "    global_search true\n" : ""}${presentations.includes("multi_window") ? "    windowing multi_window\n" : ""}  }
 
+  ui_design {
+    density comfortable
+    tone operational
+    radius_scale medium
+    color_role primary accent
+    color_role danger critical
+    typography_role body readable
+    typography_role heading prominent
+    action_role primary prominent
+    action_role destructive danger
+    accessibility contrast aa
+    accessibility focus visible
+  }
+
   ui_screens {
 ${uiScreensBlock}
   }
@@ -616,6 +656,9 @@ export function runImportApp(inputPath, options = {}) {
   }
 
   if (candidates.ui) {
+    candidates.ui = enrichUiComponentDataSources(candidates.ui, candidates);
+    files["candidates/app/ui/candidates.json"] = `${JSON.stringify(candidates.ui, null, 2)}\n`;
+    files["candidates/app/ui/report.md"] = reportMarkdown("ui", candidates.ui);
     Object.assign(files, draftUiProjectionFiles(context, candidates.ui, candidates));
   }
 

package/src/realization/ui/build-ui-shared-realization.js

@@ -1,5 +1,6 @@
 import { getProjection, uiProjectionCandidates } from "../../generator/surfaces/shared.js";
 import { buildComponentBehaviorRealizations } from "../../component-behavior.js";
+import { defaultPatternForScreen } from "../../ui/taxonomy.js";
 
 function toBooleanFlag(value, fallback = false) {
   if (value === "true") return true;
@@ -47,21 +48,6 @@ function ownershipFieldByCapability(graph) {
   return output;
 }
 
-function deriveDefaultPattern(screen, collectionEntries) {
-  if (screen.kind === "detail") return "detail_panel";
-  if (screen.kind === "form") return "edit_form";
-  if (screen.kind === "board") return "board_view";
-  if (screen.kind === "calendar") return "calendar_view";
-  if (screen.kind === "dashboard" || screen.kind === "analytics" || screen.kind === "report") return "summary_stats";
-  if (screen.kind === "feed" || screen.kind === "inbox") return "activity_feed";
-  const view = collectionEntries.find((entry) => entry.operation === "view")?.value;
-  if (view === "data_grid") return "data_grid_view";
-  if (view === "table") return "resource_table";
-  if (view === "cards" || view === "gallery") return "resource_cards";
-  if (screen.kind === "list") return "resource_table";
-  return null;
-}
-
 function componentById(graph, componentId) {
   return (graph.byKind.component || []).find((component) => component.id === componentId) || null;
 }
@@ -88,6 +74,50 @@ function regionContractFor(regionEntries, regionName) {
   return (regionEntries || []).find((entry) => entry.region === regionName) || null;
 }
 
+function buildDesignIntentContract(projection) {
+  const design = {
+    density: "comfortable",
+    tone: "operational",
+    radiusScale: "medium",
+    colorRoles: {},
+    typographyRoles: {},
+    actionRoles: {},
+    accessibility: {}
+  };
+
+  for (const entry of projection.uiDesign || []) {
+    if (entry.key === "density" && entry.role) {
+      design.density = entry.role;
+      continue;
+    }
+    if (entry.key === "tone" && entry.role) {
+      design.tone = entry.role;
+      continue;
+    }
+    if (entry.key === "radius_scale" && entry.role) {
+      design.radiusScale = entry.role;
+      continue;
+    }
+    if (entry.key === "color_role" && entry.role && entry.value) {
+      design.colorRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "typography_role" && entry.role && entry.value) {
+      design.typographyRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "action_role" && entry.role && entry.value) {
+      design.actionRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "accessibility" && entry.role && entry.value) {
+      design.accessibility[entry.role] = entry.value;
+    }
+  }
+
+  return design;
+}
+
 export function buildComponentUsageContract(graph, entry, options = {}) {
   const componentId = entry.component?.id || null;
   const contract = componentId ? componentContractFor(graph, componentId) : null;
@@ -184,7 +214,7 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
   );
   const visibilityEntries = (projection.uiVisibility || []).filter((entry) => screenActionIds.has(entry.capability?.id));
   const patterns = new Set(regionEntries.map((entry) => entry.pattern).filter(Boolean));
-  const derivedDefaultPattern = deriveDefaultPattern(screen, collectionEntries);
+  const derivedDefaultPattern = defaultPatternForScreen(screen, collectionEntries);
   if (derivedDefaultPattern) {
     patterns.add(derivedDefaultPattern);
   }
@@ -286,6 +316,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens
@@ -305,6 +336,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens

package/src/realization/ui/build-web-realization.js

@@ -1,8 +1,6 @@
 import { buildApiRealization } from "../api/index.js";
 import { generatorDefaultsMap, getProjection, sharedUiProjectionForWeb } from "../../generator/surfaces/shared.js";
 import {
-  buildComponentContractMap,
-  buildComponentUsageContract,
   buildUiSharedRealization
 } from "./build-ui-shared-realization.js";
 
@@ -38,6 +36,7 @@ export function buildWebRealization(graph, options = {}) {
         realizes: [],
         outputs: [],
         components: {},
+        design: null,
         screens: []
       };
   const concreteContract = buildUiSharedRealization(graph, { projectionId: projection.id });
@@ -70,30 +69,15 @@ export function buildWebRealization(graph, options = {}) {
     screenMap.set(screen.id, {
       ...existing,
       ...screen,
-      components: [...(existing.components || []), ...(screen.components || [])],
+      components: [...(existing.components || [])],
       regions: mergeByKey(existing.regions || [], screen.regions || [], (entry) => entry.region),
       patterns: [...new Set([...(existing.patterns || []), ...(screen.patterns || [])])]
     });
   }
-  for (const entry of projection.uiComponents || []) {
-    if (!screenMap.has(entry.screenId)) {
-      continue;
-    }
-    const screen = screenMap.get(entry.screenId);
-    if ((screen.components || []).some((usage) => componentUsageFingerprint(usage) === componentUsageFingerprintFromEntry(entry))) {
-      continue;
-    }
-    screen.components = [...(screen.components || []), buildComponentUsageContract(graph, entry, {
-      region: (screen.regions || []).find((region) => region.region === entry.region) || null
-    })];
-  }
 
   const appShell = projection.uiAppShell?.length || !sharedProjection ? concreteContract.appShell : sharedContract.appShell;
   const navigation = projection.uiNavigation?.length || !sharedProjection ? concreteContract.navigation : sharedContract.navigation;
-  const componentContracts = {
-    ...(sharedContract.components || {}),
-    ...buildComponentContractMap(graph, projection.uiComponents || [])
-  };
+  const design = projection.uiDesign?.length || !sharedProjection ? concreteContract.design : sharedContract.design;
 
   const contract = {
     projection: {
@@ -109,7 +93,8 @@ export function buildWebRealization(graph, options = {}) {
       : null,
     generatorDefaults: generatorDefaultsMap(projection),
     outputs: projection.outputs,
-    components: componentContracts,
+    components: sharedProjection ? (sharedContract.components || {}) : (concreteContract.components || {}),
+    design: design || null,
     appShell: appShell || null,
     navigation: {
       groups: navigation?.groups || [],
@@ -171,21 +156,3 @@ function mergeByKey(left, right, keyFn) {
   for (const entry of right) output.set(keyFn(entry), { ...(output.get(keyFn(entry)) || {}), ...entry });
   return [...output.values()];
 }
-
-function componentUsageFingerprint(usage) {
-  return [
-    usage?.region || "",
-    usage?.component?.id || "",
-    ...(usage?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(usage?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}
-
-function componentUsageFingerprintFromEntry(entry) {
-  return [
-    entry?.region || "",
-    entry?.component?.id || "",
-    ...(entry?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(entry?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}

package/src/resolver/index.js

@@ -503,6 +503,7 @@ function buildProjectionPlan(statement) {
     uiVisibility: statement.uiVisibility,
     uiRoutes: statement.uiRoutes,
     uiWeb: statement.uiWeb,
+    uiDesign: statement.uiDesign,
     uiComponents: statement.uiComponents,
     dbTables: statement.dbTables,
     dbColumns: statement.dbColumns,
@@ -1269,6 +1270,17 @@ function parseProjectionUiAppShellBlock(statement) {
   }));
 }
 
+function parseProjectionUiDesignBlock(statement) {
+  return blockEntries(getFieldValue(statement, "ui_design")).map((entry) => ({
+    type: "ui_design_token",
+    key: tokenValue(entry.items[0]) || null,
+    role: tokenValue(entry.items[1]) || null,
+    value: tokenValue(entry.items[2]) || null,
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}
+
 function parseProjectionUiNavigationBlock(statement) {
   return blockEntries(getFieldValue(statement, "ui_navigation")).map((entry) => {
     const directives = {};
@@ -1869,6 +1881,7 @@ export function normalizeStatement(statement, registry) {
         uiWeb: parseProjectionUiWebBlock(statement, registry),
         uiIos: parseProjectionUiIosBlock(statement, registry),
         uiAppShell: parseProjectionUiAppShellBlock(statement),
+        uiDesign: parseProjectionUiDesignBlock(statement),
         uiNavigation: parseProjectionUiNavigationBlock(statement),
         uiScreenRegions: parseProjectionUiScreenRegionsBlock(statement),
         uiComponents: parseProjectionUiComponentsBlock(statement, registry),

package/src/ui/taxonomy.js

@@ -0,0 +1,201 @@
+// @ts-check
+
+export const UI_APP_SHELL_KINDS = new Set([
+  "topbar",
+  "sidebar",
+  "dual_nav",
+  "workspace",
+  "wizard",
+  "bottom_tabs",
+  "split_view",
+  "menu_bar"
+]);
+
+export const UI_WINDOWING_MODES = new Set(["single_window", "multi_window"]);
+
+export const UI_SCREEN_KINDS = new Set([
+  "list",
+  "detail",
+  "form",
+  "dashboard",
+  "job_status",
+  "board",
+  "calendar",
+  "feed",
+  "inbox",
+  "settings",
+  "wizard",
+  "report",
+  "analytics"
+]);
+
+export const UI_COLLECTION_PRESENTATIONS = new Set([
+  "table",
+  "data_grid",
+  "cards",
+  "list",
+  "board",
+  "calendar",
+  "gallery"
+]);
+
+export const UI_NAVIGATION_PATTERNS = new Set([
+  "primary",
+  "tabs",
+  "stack_navigation",
+  "bottom_tabs",
+  "segmented_control",
+  "command_palette",
+  "split_view",
+  "navigation_rail"
+]);
+
+export const UI_REGION_KINDS = new Set([
+  "hero",
+  "toolbar",
+  "filters",
+  "search",
+  "results",
+  "summary",
+  "metadata",
+  "aside",
+  "related",
+  "activity",
+  "comments",
+  "timeline",
+  "tabs",
+  "bulk_actions",
+  "footer_actions"
+]);
+
+export const UI_PATTERN_KINDS = new Set([
+  "resource_table",
+  "data_grid_view",
+  "resource_cards",
+  "detail_panel",
+  "edit_form",
+  "lookup_select",
+  "action_bar",
+  "status_badge",
+  "summary_stats",
+  "activity_feed",
+  "comment_thread",
+  "timeline_view",
+  "board_view",
+  "calendar_view",
+  "settings_section",
+  "wizard_stepper",
+  "audit_log",
+  "search_results",
+  "empty_state_panel",
+  "inspector_pane",
+  "master_detail"
+]);
+
+export const UI_ACTION_PRESENTATIONS = new Set([
+  "button",
+  "menu_item",
+  "split_button",
+  "bulk_action",
+  "modal",
+  "drawer",
+  "inline_confirm",
+  "sheet",
+  "bottom_sheet",
+  "fab",
+  "popover"
+]);
+
+export const UI_STATE_KINDS = new Set([
+  "loading",
+  "empty",
+  "error",
+  "unauthorized",
+  "not_found",
+  "success"
+]);
+
+export const UI_PLATFORM_PATTERNS = new Set([
+  "bottom_tabs",
+  "stack_navigation",
+  "split_view",
+  "master_detail",
+  "navigation_rail",
+  "fab",
+  "sheet",
+  "bottom_sheet",
+  "pull_to_refresh",
+  "segmented_control",
+  "command_palette",
+  "inspector_pane",
+  "multi_pane_layout",
+  "resizable_split",
+  "menu_bar",
+  "multi_window"
+]);
+
+export const UI_DESIGN_DENSITIES = new Set(["compact", "comfortable", "spacious"]);
+export const UI_DESIGN_TONES = new Set(["operational", "neutral", "editorial", "playful"]);
+export const UI_DESIGN_RADIUS_SCALES = new Set(["none", "small", "medium", "large"]);
+export const UI_DESIGN_COLOR_ROLES = new Set(["primary", "secondary", "surface", "text", "muted", "danger", "success", "warning", "info"]);
+export const UI_DESIGN_TYPOGRAPHY_ROLES = new Set(["body", "heading", "label", "mono", "numeric"]);
+export const UI_DESIGN_ACTION_ROLES = new Set(["primary", "secondary", "destructive", "contextual", "bulk"]);
+export const UI_DESIGN_ACCESSIBILITY_VALUES = {
+  contrast: new Set(["aa", "aaa", "high"]),
+  motion: new Set(["standard", "reduced"]),
+  focus: new Set(["visible", "required"]),
+  min_touch_target: new Set(["compact", "comfortable"])
+};
+
+export const UI_GENERATOR_RENDERED_COMPONENT_PATTERNS = new Set([
+  "summary_stats",
+  "board_view",
+  "calendar_view",
+  "resource_table",
+  "data_grid_view"
+]);
+
+/**
+ * @param {string[]} presentations
+ * @returns {string}
+ */
+export function collectionPatternFromPresentations(presentations = []) {
+  if (presentations.includes("data_grid")) return "data_grid_view";
+  if (presentations.includes("table")) return "resource_table";
+  if (presentations.includes("cards")) return "resource_cards";
+  if (presentations.includes("board")) return "board_view";
+  if (presentations.includes("calendar")) return "calendar_view";
+  if (presentations.includes("gallery")) return "resource_cards";
+  return "search_results";
+}
+
+/**
+ * @param {string|null|undefined} pattern
+ * @returns {string}
+ */
+export function presentationFromPattern(pattern) {
+  if (pattern === "data_grid_view") return "data_grid";
+  if (pattern === "resource_table") return "table";
+  if (pattern === "resource_cards") return "cards";
+  if (pattern === "board_view") return "board";
+  if (pattern === "calendar_view") return "calendar";
+  return "list";
+}
+
+/**
+ * @param {{ kind?: string|null }} screen
+ * @param {{ operation?: string|null, value?: string|null }[]} collectionEntries
+ * @returns {string|null}
+ */
+export function defaultPatternForScreen(screen, collectionEntries = []) {
+  if (screen.kind === "detail") return "detail_panel";
+  if (screen.kind === "form") return "edit_form";
+  if (screen.kind === "board") return "board_view";
+  if (screen.kind === "calendar") return "calendar_view";
+  if (screen.kind === "dashboard" || screen.kind === "analytics" || screen.kind === "report") return "summary_stats";
+  if (screen.kind === "feed" || screen.kind === "inbox") return "activity_feed";
+  const view = collectionEntries.find((entry) => entry.operation === "view")?.value;
+  if (view) return collectionPatternFromPresentations([view]);
+  if (screen.kind === "list") return "resource_table";
+  return null;
+}