@jskit-ai/ui-generator 0.1.48 → 0.1.50

package/src/server/subcommands/outlet.js

@@ -1,20 +1,29 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
+  normalizePlacementOwnerId,
+  normalizePlacementSurfaceId,
+  normalizeSemanticPlacementId
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
+import {
+  PLACEMENT_TOPOLOGY_FILE,
+  appendTopologyBlockIfPlacementMissing,
   requireSinglePositionalTargetFile,
   rejectUnexpectedOptions,
   resolveOutletTargetId,
   resolvePathWithinApp,
   ensureTrailingNewline,
   insertImportIfMissing,
-  findScriptBlock,
+  findScriptSetupBlock,
+  insertScriptSetupBlock,
   parseTagAttributes,
   indentBlock
 } from "./support.js";
 
-const ROUTE_TAG_PATTERN = /<route\b[^>]*>[\s\S]*?<\/route>\s*/gi;
 const TEMPLATE_CLOSE_TAG_PATTERN = /<\/template>/gi;
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/gi;
+const TOPOLOGY_LAYOUT_CLASSES = Object.freeze(["compact", "medium", "expanded"]);
+const TOPOLOGY_KINDS = new Set(["component", "link"]);
 
 function hasShellOutletTarget(source = "", { target = "" } = {}) {
   const normalizedTarget = normalizeText(target);
@@ -35,21 +44,12 @@ function hasShellOutletTarget(source = "", { target = "" } = {}) {
 
 function applyScriptImports(source = "") {
   const sourceText = String(source || "");
-  const scriptBlock = findScriptBlock(sourceText);
+  const scriptBlock = findScriptSetupBlock(sourceText);
 
   const shellOutletImport = "import ShellOutlet from \"@jskit-ai/shell-web/client/components/ShellOutlet\";";
 
   if (!scriptBlock) {
-    const scriptSetupBlock = `<script setup>\n${shellOutletImport}\n</script>\n`;
-    let insertionIndex = 0;
-    for (const match of sourceText.matchAll(ROUTE_TAG_PATTERN)) {
-      insertionIndex = match.index + String(match[0] || "").length;
-    }
-    const separator = insertionIndex > 0 ? "\n" : "";
-    return {
-      changed: true,
-      content: `${sourceText.slice(0, insertionIndex)}${separator}${scriptSetupBlock}\n${sourceText.slice(insertionIndex)}`
-    };
+    return insertScriptSetupBlock(sourceText, shellOutletImport);
   }
 
   let nextScriptContent = scriptBlock.content;
@@ -75,6 +75,204 @@ function createOutletBlock({ target = "" } = {}) {
   return `<ShellOutlet target="${target}" />`;
 }
 
+function resolveOutletOwner(target = "") {
+  const normalizedTarget = normalizeText(target);
+  const separatorIndex = normalizedTarget.indexOf(":");
+  if (separatorIndex <= 0) {
+    return "";
+  }
+  return normalizedTarget.slice(0, separatorIndex);
+}
+
+function resolveSemanticPlacementOption(options = {}, { context = "ui-generator outlet" } = {}) {
+  const placementId = resolveOptionalSemanticPlacementOption(options, { context });
+  if (!placementId) {
+    throw new Error(`${context} requires --placement in semantic "area.slot" format.`);
+  }
+  return placementId;
+}
+
+function resolveOptionalSemanticPlacementOption(options = {}, { context = "ui-generator outlet" } = {}) {
+  const rawPlacement = normalizeText(options?.placement);
+  if (!rawPlacement) {
+    return "";
+  }
+  const placementId = normalizeSemanticPlacementId(rawPlacement);
+  if (!placementId) {
+    throw new Error(`${context} requires --placement in semantic "area.slot" format.`);
+  }
+  return placementId;
+}
+
+function resolveVariantOwners(variantTargets = {}) {
+  return [
+    ...new Set(
+      Object.values(variantTargets || {})
+        .map((target) => resolveOutletOwner(target))
+        .filter(Boolean)
+    )
+  ];
+}
+
+function resolveSemanticPlacementOwner({
+  placementId = "",
+  targetId = "",
+  variantTargets = null,
+  owner = "",
+  context = "ui-generator outlet"
+} = {}) {
+  const explicitOwner = normalizePlacementOwnerId(owner);
+  if (explicitOwner) {
+    return explicitOwner;
+  }
+  if (placementId.startsWith("page.") || placementId.startsWith("settings.")) {
+    const variantOwners = resolveVariantOwners(variantTargets);
+    if (variantOwners.length > 1) {
+      throw new Error(
+        `${context} requires --owner because semantic placement "${placementId}" maps to multiple outlet hosts: ${variantOwners.join(", ")}.`
+      );
+    }
+    if (variantOwners.length === 1) {
+      return variantOwners[0];
+    }
+    return resolveOutletOwner(targetId);
+  }
+  return "";
+}
+
+function resolveTopologyKind(options = {}, { context = "ui-generator outlet", defaultKind = "", required = false } = {}) {
+  const rawKind = normalizeText(options?.kind).toLowerCase();
+  if (!rawKind) {
+    if (defaultKind) {
+      return defaultKind;
+    }
+    if (required) {
+      throw new Error(`${context} requires --kind component or --kind link.`);
+    }
+    return "";
+  }
+  if (!TOPOLOGY_KINDS.has(rawKind)) {
+    throw new Error(`${context} option "kind" must be one of: component, link.`);
+  }
+  return rawKind;
+}
+
+function resolveTopologyVariantTargets(options = {}, { context = "ui-generator topology", fallbackTarget = "" } = {}) {
+  const fallback = normalizeText(options?.target) || normalizeText(fallbackTarget);
+  const rawTargets = {
+    compact: normalizeText(options?.["compact-target"]) || fallback,
+    medium: normalizeText(options?.["medium-target"]) || fallback,
+    expanded: normalizeText(options?.["expanded-target"]) || fallback
+  };
+  const missingLayouts = TOPOLOGY_LAYOUT_CLASSES.filter((layoutClass) => !rawTargets[layoutClass]);
+  if (missingLayouts.length > 0) {
+    throw new Error(
+      `${context} requires --target or all layout targets: --compact-target, --medium-target, --expanded-target. Missing: ${missingLayouts.join(", ")}.`
+    );
+  }
+
+  return Object.freeze(
+    Object.fromEntries(
+      TOPOLOGY_LAYOUT_CLASSES.map((layoutClass) => {
+        const target = resolveOutletTargetId(rawTargets[layoutClass], {
+          context,
+          optionName: `${layoutClass}-target`
+        });
+        return [layoutClass, target.id];
+      })
+    )
+  );
+}
+
+function hasTopologyOptions(options = {}) {
+  return [
+    "compact-target",
+    "medium-target",
+    "expanded-target",
+    "owner",
+    "surface",
+    "description",
+    "kind",
+    "link-renderer"
+  ].some((optionName) => normalizeText(options?.[optionName]));
+}
+
+function resolveTopologySurfaces(options = {}) {
+  const surface = normalizePlacementSurfaceId(options?.surface);
+  if (surface) {
+    return [surface];
+  }
+  return ["*"];
+}
+
+function renderTopologyOwnerLine(owner = "") {
+  if (!owner) {
+    return "";
+  }
+  return `  owner: "${owner}",\n`;
+}
+
+function renderLinkRendererBlock(rendererToken = "") {
+  const normalizedRendererToken = normalizeText(rendererToken) || "local.main.ui.surface-aware-menu-link-item";
+  return (
+    "      renderers: {\n" +
+    `        link: "${normalizedRendererToken}"\n` +
+    "      }\n"
+  );
+}
+
+function renderTopologyVariantBlock({ layoutClass = "", target = "", kind = "", rendererToken = "" } = {}) {
+  const rendererBlock = kind === "link" ? renderLinkRendererBlock(rendererToken) : "";
+  const outletSeparator = rendererBlock ? "," : "";
+  return (
+    `    ${layoutClass}: {\n` +
+    `      outlet: "${target}"${outletSeparator}\n` +
+    rendererBlock +
+    "    }"
+  );
+}
+
+function renderOutletTopologyBlock({
+  marker = "",
+  placementId = "",
+  owner = "",
+  surfaces = ["*"],
+  description = "",
+  target = "",
+  variantTargets = null,
+  kind = "link",
+  rendererToken = ""
+} = {}) {
+  const descriptionLine = normalizeText(description)
+    ? `  description: ${JSON.stringify(normalizeText(description))},\n`
+    : "";
+  const resolvedVariantTargets = variantTargets || Object.freeze({
+    compact: target,
+    medium: target,
+    expanded: target
+  });
+  const variantBlocks = TOPOLOGY_LAYOUT_CLASSES
+    .map((layoutClass) => renderTopologyVariantBlock({
+      layoutClass,
+      target: resolvedVariantTargets[layoutClass],
+      kind,
+      rendererToken
+    }))
+    .join(",\n");
+  return (
+    `// ${marker}\n` +
+    "addPlacementTopology({\n" +
+    `  id: "${placementId}",\n` +
+    renderTopologyOwnerLine(owner) +
+    descriptionLine +
+    `  surfaces: ${JSON.stringify(surfaces)},\n` +
+    "  variants: {\n" +
+    `${variantBlocks}\n` +
+    "  }\n" +
+    "});\n"
+  );
+}
+
 function findLastTemplateCloseTag(source = "") {
   const sourceText = String(source || "");
   let lastMatch = null;
@@ -119,19 +317,43 @@ async function runGeneratorSubcommand({
   dryRun = false
 } = {}) {
   const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand === "topology") {
+    return runTopologySubcommand({
+      appRoot,
+      options,
+      dryRun
+    });
+  }
   if (normalizedSubcommand !== "outlet") {
     throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
   }
   const targetFile = requireSinglePositionalTargetFile(args, { context: "ui-generator outlet" });
-  rejectUnexpectedOptions(options, ["target"], {
-    context: "ui-generator outlet"
-  });
+  rejectUnexpectedOptions(
+    options,
+    [
+      "target",
+      "placement",
+      "owner",
+      "surface",
+      "description",
+      "link-renderer",
+      "kind",
+      "compact-target",
+      "medium-target",
+      "expanded-target"
+    ],
+    { context: "ui-generator outlet" }
+  );
 
   const outletTarget = resolveOutletTargetId(options?.target, {
     context: "ui-generator outlet",
     optionName: "target"
   });
   const targetId = outletTarget.id;
+  const placementId = resolveOptionalSemanticPlacementOption(options);
+  if (!placementId && hasTopologyOptions(options)) {
+    throw new Error("ui-generator outlet requires --placement when topology options are provided.");
+  }
 
   const targetFilePath = resolvePathWithinApp(appRoot, targetFile, {
     context: "ui-generator outlet"
@@ -157,16 +379,173 @@ async function runGeneratorSubcommand({
     });
   const scriptApplied = applyScriptImports(templateApplied.content);
 
+  const topologyPath = resolvePathWithinApp(appRoot, PLACEMENT_TOPOLOGY_FILE, {
+    context: "ui-generator outlet"
+  });
+  const topologyApplied = placementId
+    ? await prepareTopologyBlock({
+      appRoot,
+      topologyPath,
+      context: "ui-generator outlet",
+      placementId,
+      owner: options?.owner,
+      surfaces: resolveTopologySurfaces(options),
+      description: options?.description,
+      target: targetId,
+      variantTargets: resolveTopologyVariantTargets(options, {
+        context: "ui-generator outlet",
+        fallbackTarget: targetId
+      }),
+      kind: resolveTopologyKind(options, {
+        context: "ui-generator outlet",
+        defaultKind: "link"
+      }),
+      rendererToken: options?.["link-renderer"]
+    })
+    : { changed: false, relativePath: topologyPath.relativePath };
+
   const changed = templateApplied.changed || scriptApplied.changed;
   if (changed && dryRun !== true) {
     await writeFile(targetFilePath.absolutePath, scriptApplied.content, "utf8");
   }
+  if (topologyApplied.changed && dryRun !== true) {
+    await writeFile(topologyApplied.absolutePath, topologyApplied.content, "utf8");
+  }
+
+  const touchedFiles = new Set();
+  if (changed) {
+    touchedFiles.add(targetFilePath.relativePath);
+  }
+  if (topologyApplied.changed) {
+    touchedFiles.add(topologyApplied.relativePath);
+  }
+
+  const actionSummary = [
+    changed ? `Injected outlet "${targetId}"` : "",
+    topologyApplied.changed && placementId
+      ? `mapped semantic placement "${placementId}"`
+      : ""
+  ].filter(Boolean).join(" and ");
+  return {
+    touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
+    summary: touchedFiles.size > 0
+      ? `${actionSummary || `Processed outlet "${targetId}"`}.`
+      : placementId
+        ? `Outlet "${targetId}" and semantic placement "${placementId}" are already present.`
+        : `Outlet "${targetId}" is already present.`
+  };
+}
+
+async function prepareTopologyBlock({
+  appRoot,
+  topologyPath = null,
+  context = "ui-generator topology",
+  placementId = "",
+  owner = "",
+  surfaces = ["*"],
+  description = "",
+  target = "",
+  variantTargets = null,
+  kind = "",
+  rendererToken = ""
+} = {}) {
+  const resolvedTopologyPath = topologyPath || resolvePathWithinApp(appRoot, PLACEMENT_TOPOLOGY_FILE, {
+    context
+  });
+  const resolvedOwner = resolveSemanticPlacementOwner({
+    placementId,
+    targetId: target,
+    variantTargets,
+    owner,
+    context
+  });
+  const topologyMarker = `jskit:ui-generator.topology:${placementId}:${resolvedOwner || "global"}`;
+  const topologySource = await readFile(resolvedTopologyPath.absolutePath, "utf8");
+  const topologyApplied = await appendTopologyBlockIfPlacementMissing({
+    topologyPath: resolvedTopologyPath,
+    source: topologySource,
+    marker: topologyMarker,
+    block: renderOutletTopologyBlock({
+      marker: topologyMarker,
+      placementId,
+      owner: resolvedOwner,
+      surfaces,
+      description,
+      target,
+      variantTargets,
+      kind,
+      rendererToken
+    }),
+    placementId,
+    owner: resolvedOwner,
+    variantTargets,
+    context
+  });
+  return {
+    changed: topologyApplied.changed,
+    content: topologyApplied.content,
+    absolutePath: resolvedTopologyPath.absolutePath,
+    relativePath: resolvedTopologyPath.relativePath,
+    owner: resolvedOwner
+  };
+}
+
+async function applyTopologyBlock(options = {}) {
+  const topologyApplied = await prepareTopologyBlock(options);
+  if (topologyApplied.changed && options?.dryRun !== true) {
+    await writeFile(topologyApplied.absolutePath, topologyApplied.content, "utf8");
+  }
+  return {
+    changed: topologyApplied.changed,
+    relativePath: topologyApplied.relativePath,
+    owner: topologyApplied.owner
+  };
+}
+
+async function runTopologySubcommand({
+  appRoot,
+  options = {},
+  dryRun = false
+} = {}) {
+  const context = "ui-generator topology";
+  rejectUnexpectedOptions(
+    options,
+    [
+      "target",
+      "compact-target",
+      "medium-target",
+      "expanded-target",
+      "placement",
+      "owner",
+      "surface",
+      "description",
+      "kind",
+      "link-renderer"
+    ],
+    { context }
+  );
+  const placementId = resolveSemanticPlacementOption(options, { context });
+  const variantTargets = resolveTopologyVariantTargets(options, { context });
+  const kind = resolveTopologyKind(options, { context, required: true });
+  const topologyApplied = await applyTopologyBlock({
+    appRoot,
+    context,
+    placementId,
+    owner: options?.owner,
+    surfaces: resolveTopologySurfaces(options),
+    description: options?.description,
+    target: variantTargets.compact,
+    variantTargets,
+    kind,
+    rendererToken: options?.["link-renderer"],
+    dryRun
+  });
 
   return {
-    touchedFiles: changed ? [targetFilePath.relativePath] : [],
-    summary: changed
-      ? `Injected outlet "${targetId}" into ${targetFilePath.relativePath}.`
-      : `Outlet "${targetId}" is already present in ${targetFilePath.relativePath}.`
+    touchedFiles: topologyApplied.changed ? [topologyApplied.relativePath] : [],
+    summary: topologyApplied.changed
+      ? `Mapped semantic placement "${placementId}"${topologyApplied.owner ? ` for owner "${topologyApplied.owner}"` : ""}.`
+      : `Semantic placement "${placementId}"${topologyApplied.owner ? ` for owner "${topologyApplied.owner}"` : ""} is already present.`
   };
 }
 

package/src/server/subcommands/page.js

@@ -1,7 +1,11 @@
 import path from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { buildUiPageTemplateContext } from "../buildTemplateContext.js";
+import {
+  buildUiPageTemplateContext,
+  resolveNavigationInferenceRoutePath,
+  shouldCreateNavigationLink
+} from "../buildTemplateContext.js";
 import {
   PLACEMENT_FILE,
   requireSinglePositionalTargetFile,
@@ -20,15 +24,20 @@ function renderPageLinkPlacementBlock({
   label = "",
   surface = ""
 } = {}) {
+  const componentTokenLine = context.__JSKIT_UI_LINK_COMPONENT_TOKEN__
+    ? `    componentToken: "${context.__JSKIT_UI_LINK_COMPONENT_TOKEN__}",\n`
+    : "";
   return (
     `// ${marker}\n` +
     "{\n" +
     "  addPlacement({\n" +
     `    id: "${context.__JSKIT_UI_LINK_PLACEMENT_ID__}",\n` +
     `    target: "${context.__JSKIT_UI_LINK_PLACEMENT_TARGET__}",\n` +
+    `${context.__JSKIT_UI_LINK_OWNER_LINE__}` +
+    `    kind: "link",\n` +
     `    surfaces: ["${surface}"],\n` +
     "    order: 155,\n" +
-    `    componentToken: "${context.__JSKIT_UI_LINK_COMPONENT_TOKEN__}",\n` +
+    componentTokenLine +
     "    props: {\n" +
     `      label: "${label}",\n` +
     `      icon: "${context.__JSKIT_UI_LINK_ICON__}",\n` +
@@ -56,7 +65,7 @@ async function runGeneratorSubcommand({
   const targetFile = requireSinglePositionalTargetFile(args, { context: "ui-generator page" });
   rejectUnexpectedOptions(
     options,
-    ["name", "link-placement", "link-component-token", "link-to", "force"],
+    ["name", "navigation-role", "link-placement", "link-to", "force"],
     { context: "ui-generator page" }
   );
 
@@ -71,6 +80,7 @@ async function runGeneratorSubcommand({
     : false;
   const pageFilePath = pageTarget.targetFilePath.absolutePath;
   const pageRelativePath = pageTarget.targetFilePath.relativePath;
+  const navigationInferenceRoutePath = resolveNavigationInferenceRoutePath(pageTarget);
 
   const touchedFiles = new Set();
   let pageAlreadyExisted = true;
@@ -86,31 +96,47 @@ async function runGeneratorSubcommand({
     );
   }
 
-  const placementContext = await buildUiPageTemplateContext({
-    appRoot: pageTarget.appRoot,
-    targetFile,
-    options
-  });
-  const placementPath = resolvePathWithinApp(pageTarget.appRoot, PLACEMENT_FILE, {
-    context: "ui-generator page"
+  const shouldCreateLink = shouldCreateNavigationLink(options, {
+    routePath: navigationInferenceRoutePath
   });
-  const placementSource = await readFile(placementPath.absolutePath, "utf8");
-  const placementMarker = `jskit:ui-generator.page.link:${pageTarget.surfaceId}:${pageTarget.routeUrlSuffix}`;
-  const placementApplied = appendBlockIfMarkerMissing(
-    placementSource,
-    placementMarker,
-    renderPageLinkPlacementBlock({
-      marker: placementMarker,
-      context: placementContext,
-      label: pageLabel,
-      surface: pageTarget.surfaceId
+  const placementContext = shouldCreateLink
+    ? await buildUiPageTemplateContext({
+      appRoot: pageTarget.appRoot,
+      targetFile,
+      options
     })
-  );
+    : null;
+  const placementPath = shouldCreateLink
+    ? resolvePathWithinApp(pageTarget.appRoot, PLACEMENT_FILE, {
+      context: "ui-generator page"
+    })
+    : null;
+  const placementSource = placementPath ? await readFile(placementPath.absolutePath, "utf8") : "";
+  const placementMarker = `jskit:ui-generator.page.link:${pageTarget.surfaceId}:${pageTarget.routeUrlSuffix}`;
+  const placementApplied = placementContext
+    ? appendBlockIfMarkerMissing(
+      placementSource,
+      placementMarker,
+      renderPageLinkPlacementBlock({
+        marker: placementMarker,
+        context: placementContext,
+        label: pageLabel,
+        surface: pageTarget.surfaceId
+      })
+    )
+    : { changed: false, content: placementSource };
 
   if (!pageAlreadyExisted || forceOverwrite) {
     if (dryRun !== true) {
       await mkdir(path.dirname(pageFilePath), { recursive: true });
-      await writeFile(pageFilePath, renderPlainPageSource(pageLabel), "utf8");
+      await writeFile(
+        pageFilePath,
+        renderPlainPageSource(pageLabel, {
+          surfaceId: pageTarget.surfaceId,
+          routePath: navigationInferenceRoutePath
+        }),
+        "utf8"
+      );
     }
     touchedFiles.add(pageRelativePath);
   }
@@ -124,7 +150,7 @@ async function runGeneratorSubcommand({
 
   const touchedFileList = [...touchedFiles].sort((left, right) => left.localeCompare(right));
   return {
-    placementComponentTokens: [String(placementContext.__JSKIT_UI_LINK_COMPONENT_TOKEN__ || "").trim()].filter(Boolean),
+    placementComponentTokens: [String(placementContext?.__JSKIT_UI_LINK_COMPONENT_TOKEN__ || "").trim()].filter(Boolean),
     touchedFiles: touchedFileList,
     summary: !pageAlreadyExisted
       ? `Generated UI page "${pageTarget.routeUrlSuffix}" at ${pageRelativePath}.`