@jskit-ai/kernel 0.1.65 → 0.1.67

package/shared/support/generatedUiContract.test.js

@@ -0,0 +1,208 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  GENERATED_UI_NAVIGATION_ROLE_OPTION,
+  GENERATED_UI_NAVIGATION_ROLE_VALUES,
+  GENERATED_UI_SURFACE_PROFILES,
+  assertGeneratedUiSourceContract,
+  buildGeneratedUiScreenClassName,
+  collectGeneratedUiSourceContractIssues,
+  inferGeneratedUiNavigationRole,
+  isGeneratedUiNoLinkNavigationRole,
+  normalizeGeneratedUiNavigationRole,
+  resolveGeneratedUiSurfaceProfile,
+  resolveGeneratedUiNavigationRoleLinkPlacement,
+  shouldCreateGeneratedUiNavigationLink
+} from "./generatedUiContract.js";
+
+test("generated UI navigation role metadata is descriptor-ready", () => {
+  assert.deepEqual(
+    GENERATED_UI_NAVIGATION_ROLE_VALUES,
+    ["primary", "secondary", "utility", "detail", "workflow", "none"]
+  );
+  assert.equal(GENERATED_UI_NAVIGATION_ROLE_OPTION.validationType, "enum");
+  assert.deepEqual(GENERATED_UI_NAVIGATION_ROLE_OPTION.allowedValues, GENERATED_UI_NAVIGATION_ROLE_VALUES);
+  assert.equal(GENERATED_UI_NAVIGATION_ROLE_OPTION.defaultValue, "");
+});
+
+test("generated UI surface profiles map app, operator, and settings density", () => {
+  assert.deepEqual(Object.keys(GENERATED_UI_SURFACE_PROFILES), ["task", "operator", "settings"]);
+  assert.equal(resolveGeneratedUiSurfaceProfile("").id, "task");
+  assert.equal(resolveGeneratedUiSurfaceProfile("operator").id, "operator");
+  assert.equal(resolveGeneratedUiSurfaceProfile("operator").density, "compact");
+  assert.equal(resolveGeneratedUiSurfaceProfile("settings").id, "settings");
+  assert.equal(
+    buildGeneratedUiScreenClassName("generated-page-screen d-flex", {
+      surfaceProfile: "operator"
+    }),
+    "generated-ui-screen generated-ui-screen--operator generated-page-screen d-flex"
+  );
+});
+
+test("normalizeGeneratedUiNavigationRole defaults and validates roles", () => {
+  assert.equal(normalizeGeneratedUiNavigationRole(""), "primary");
+  assert.equal(normalizeGeneratedUiNavigationRole(" Secondary "), "secondary");
+  assert.throws(
+    () => normalizeGeneratedUiNavigationRole("drawer"),
+    /navigation-role must be one of: primary, secondary, utility, detail, workflow, none/
+  );
+});
+
+test("generated UI navigation roles resolve semantic link placements", () => {
+  assert.equal(resolveGeneratedUiNavigationRoleLinkPlacement({}), "");
+  assert.equal(resolveGeneratedUiNavigationRoleLinkPlacement({ "navigation-role": "secondary" }), "shell.secondary-nav");
+  assert.equal(resolveGeneratedUiNavigationRoleLinkPlacement({ "navigation-role": "utility" }), "shell.global-actions");
+  assert.equal(
+    resolveGeneratedUiNavigationRoleLinkPlacement({
+      "navigation-role": "secondary",
+      "link-placement": "settings.sections"
+    }),
+    "settings.sections"
+  );
+});
+
+test("generated UI navigation role inference keeps detail and workflow routes out of primary nav", () => {
+  assert.equal(inferGeneratedUiNavigationRole({}, { routePath: "/reports" }), "primary");
+  assert.equal(inferGeneratedUiNavigationRole({}, { routePath: "/reports/[reportId]" }), "detail");
+  assert.equal(inferGeneratedUiNavigationRole({}, { routePath: "/reports/[reportId]/activity" }), "primary");
+  assert.equal(
+    inferGeneratedUiNavigationRole({}, {
+      dynamicRoutePolicy: "any",
+      routePath: "/reports/[reportId]/activity"
+    }),
+    "detail"
+  );
+  assert.equal(inferGeneratedUiNavigationRole({}, { routePath: "/reports/new" }), "workflow");
+  assert.equal(
+    inferGeneratedUiNavigationRole({ "navigation-role": "primary" }, { routePath: "/reports/[reportId]" }),
+    "primary"
+  );
+  assert.equal(
+    shouldCreateGeneratedUiNavigationLink({}, {
+      allowLinkTo: true,
+      routePath: "/reports/[reportId]"
+    }),
+    false
+  );
+  assert.equal(
+    shouldCreateGeneratedUiNavigationLink({ "navigation-role": "primary" }, {
+      allowLinkTo: true,
+      routePath: "/reports/[reportId]"
+    }),
+    true
+  );
+  assert.equal(
+    shouldCreateGeneratedUiNavigationLink({ "link-placement": "shell.secondary-nav" }, {
+      allowLinkTo: true,
+      routePath: "/reports/[reportId]"
+    }),
+    true
+  );
+});
+
+test("generated UI no-link roles reject conflicting link options", () => {
+  assert.equal(isGeneratedUiNoLinkNavigationRole("detail"), true);
+  assert.equal(shouldCreateGeneratedUiNavigationLink({ "navigation-role": "workflow" }), false);
+  assert.equal(shouldCreateGeneratedUiNavigationLink({ "navigation-role": "primary" }), true);
+  assert.throws(
+    () => shouldCreateGeneratedUiNavigationLink({
+      "navigation-role": "detail",
+      "link-placement": "shell.primary-nav"
+    }),
+    /navigation-role "detail" cannot be combined with --link-placement/
+  );
+  assert.throws(
+    () => shouldCreateGeneratedUiNavigationLink({
+      "navigation-role": "none",
+      "link-to": "./details"
+    }, {
+      allowLinkTo: true
+    }),
+    /navigation-role "none" cannot be combined with --link-placement or --link-to/
+  );
+});
+
+test("generated UI source contract flags placeholder copy and missing profile hooks", () => {
+  const issues = collectGeneratedUiSourceContractIssues(
+    `<template>
+  <section>
+    <v-card>Replace this content</v-card>
+  </section>
+</template>`,
+    {
+      profile: "page"
+    }
+  );
+
+  assert.deepEqual(
+    issues.map((issue) => issue.id),
+    [
+      "replace-this-copy",
+      "vuetify-card-shell",
+      "shared-screen-class",
+      "page-screen-title",
+      "page-empty-state-sheet",
+      "page-responsive-title-type",
+      "page-compact-rules"
+    ]
+  );
+});
+
+test("generated UI source contract accepts compact-first CRUD detail structure", () => {
+  assert.doesNotThrow(() => assertGeneratedUiSourceContract(
+    `<template>
+  <CrudAddEditScreen :screen="screen">
+    <template #fields="{ formState, addEdit, resolveFieldErrors }"></template>
+  </CrudAddEditScreen>
+</template>
+
+<script setup>
+const screen = useCrudAddEditScreen({
+  title: "New Customer",
+  resource: uiResource
+});
+</script>`,
+    {
+      profile: "crud-detail",
+      sourceName: "NewElement.vue"
+    }
+  ));
+});
+
+test("generated UI source contract accepts compact-first CRUD list structure", () => {
+  assert.doesNotThrow(() => assertGeneratedUiSourceContract(
+    `<template>
+  <CrudListScreen
+    :screen="screen"
+    empty-title="__JSKIT_UI_LIST_EMPTY_TITLE__"
+    load-error-title="__JSKIT_UI_LIST_LOAD_ERROR_TITLE__"
+  >
+    <template #card-fields="{ record, records, formatListCardValue }"></template>
+    <template #table-header></template>
+    <template #table-row="{ record, records }"></template>
+  </CrudListScreen>
+</template>
+
+<script setup>
+const screen = useCrudListScreen({
+  resource: uiResource,
+  listFilters,
+  listBulkActions
+});
+</script>`,
+    {
+      profile: "crud-list",
+      sourceName: "ListElement.vue"
+    }
+  ));
+});
+
+test("generated UI responsive smoke profile requires compact medium expanded checks", () => {
+  assert.throws(
+    () => assertGeneratedUiSourceContract("const width = 390; const selector = 'generated-ui-screen';", {
+      profile: "responsive-smoke",
+      sourceName: "tests/e2e/example.spec.ts"
+    }),
+    /missing:medium-viewport/
+  );
+});

package/shared/support/shellLayoutTargets.js

@@ -5,6 +5,8 @@ import {
 
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/g;
 const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+const PLACEMENT_LAYOUT_CLASSES = Object.freeze(["compact", "medium", "expanded"]);
+const WEB_PLACEMENT_SURFACE_ANY = "*";
 
 function parseTagAttributes(attributesSource = "") {
   const attributes = {};
@@ -43,6 +45,211 @@ function normalizeShellOutletTargetId(value = "") {
   return `${host}:${position}`;
 }
 
+function normalizeSemanticPlacementId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue || normalizedValue.includes(":") || !normalizedValue.includes(".")) {
+    return "";
+  }
+
+  const segments = normalizedValue.split(".");
+  if (segments.length < 2) {
+    return "";
+  }
+
+  const normalizedSegments = [];
+  for (const segment of segments) {
+    const normalizedSegment = normalizeText(segment);
+    if (!/^[a-z0-9]+(?:[_-][a-z0-9]+)*$/.test(normalizedSegment)) {
+      return "";
+    }
+    normalizedSegments.push(normalizedSegment);
+  }
+
+  return normalizedSegments.join(".");
+}
+
+function normalizePlacementOwnerId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue) {
+    return "";
+  }
+  if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalizedValue)) {
+    return "";
+  }
+  return normalizedValue;
+}
+
+function normalizePlacementLayoutClass(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (PLACEMENT_LAYOUT_CLASSES.includes(normalizedValue)) {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementKind(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (normalizedValue === "link" || normalizedValue === "component") {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementSurfaceId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue) {
+    return "";
+  }
+  if (normalizedValue === WEB_PLACEMENT_SURFACE_ANY) {
+    return WEB_PLACEMENT_SURFACE_ANY;
+  }
+  if (/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalizedValue)) {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementSurfaces(value) {
+  const candidates = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  if (candidates.length < 1) {
+    return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const surface = normalizePlacementSurfaceId(candidate);
+    if (!surface || seen.has(surface)) {
+      continue;
+    }
+    if (surface === WEB_PLACEMENT_SURFACE_ANY) {
+      return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+    }
+    seen.add(surface);
+    normalized.push(surface);
+  }
+
+  if (normalized.length < 1) {
+    return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolvePlacementTargetReference(value = "") {
+  const semanticId = normalizeSemanticPlacementId(value);
+  if (semanticId) {
+    return Object.freeze({
+      id: semanticId,
+      type: "semantic"
+    });
+  }
+
+  const concreteId = normalizeShellOutletTargetId(value);
+  if (concreteId) {
+    return Object.freeze({
+      id: concreteId,
+      type: "concrete"
+    });
+  }
+
+  return null;
+}
+
+function normalizePlacementRenderers(value = {}) {
+  const record = normalizeObject(value);
+  const renderers = {};
+  for (const [key, rendererToken] of Object.entries(record)) {
+    const kind = normalizePlacementKind(key);
+    const token = normalizeText(rendererToken);
+    if (!kind || !token) {
+      continue;
+    }
+    renderers[kind] = token;
+  }
+  return Object.freeze(renderers);
+}
+
+function normalizePlacementTopologyVariant(
+  value = {},
+  {
+    context = "placement topology variant"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const outlet = normalizeShellOutletTargetId(record.outlet || record.target);
+  if (!outlet) {
+    throw new Error(`${normalizeText(context) || "placement topology variant"} requires outlet in "host:position" format.`);
+  }
+
+  return Object.freeze({
+    outlet,
+    renderers: normalizePlacementRenderers(record.renderers)
+  });
+}
+
+function normalizePlacementTopologyEntry(
+  value = {},
+  {
+    context = "placement topology"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const resolvedContext = normalizeText(context) || "placement topology";
+  const id = normalizeSemanticPlacementId(record.id || record.target);
+  if (!id) {
+    throw new Error(`${resolvedContext} requires semantic placement id in "area.slot" format.`);
+  }
+
+  const owner = normalizePlacementOwnerId(record.owner);
+  const surfaces = normalizePlacementSurfaces(record.surfaces);
+  const variantsRecord = normalizeObject(record.variants);
+  const variants = {};
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const variant = variantsRecord[layoutClass];
+    if (!variant) {
+      throw new Error(`${resolvedContext} "${id}" requires ${layoutClass} topology variant.`);
+    }
+    variants[layoutClass] = normalizePlacementTopologyVariant(variant, {
+      context: `${resolvedContext} "${id}" ${layoutClass}`
+    });
+  }
+
+  return Object.freeze({
+    id,
+    owner,
+    description: normalizeText(record.description),
+    surfaces,
+    default: record.default === true,
+    variants: Object.freeze(variants)
+  });
+}
+
+function normalizePlacementTopologyDefinition(
+  value = {},
+  {
+    context = "placement topology"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const entries = Array.isArray(record.placements) ? record.placements : Array.isArray(value) ? value : [];
+  const normalized = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const placement = normalizePlacementTopologyEntry(entry, { context });
+    const key = `${placement.id}::${placement.owner || ""}`;
+    if (seen.has(key)) {
+      throw new Error(`${normalizeText(context) || "placement topology"} contains duplicate semantic placement "${placement.id}"${placement.owner ? ` for owner "${placement.owner}"` : ""}.`);
+    }
+    seen.add(key);
+    normalized.push(placement);
+  }
+
+  return Object.freeze({
+    placements: Object.freeze(normalized)
+  });
+}
+
 function resolveShellOutletTargetParts(
   {
     target = ""
@@ -117,14 +324,17 @@ function normalizeShellOutletTargetRecord(
     ...targetParts,
     default:
       Object.hasOwn(record, "default") &&
-      isDefaultAttributeEnabled(record.default),
-    defaultLinkComponentToken:
-      normalizeText(record.defaultLinkComponentToken) ||
-      normalizeText(record["default-link-component-token"])
+      isDefaultAttributeEnabled(record.default)
   });
 }
 
-function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
+function discoverShellOutletTargetsFromVueSource(
+  source = "",
+  {
+    context = "shell layout",
+    enforceSingleDefault = true
+  } = {}
+) {
   const sourceText = String(source || "");
   const resolvedContext = normalizeText(context) || "shell layout";
   const targetById = new Map();
@@ -143,12 +353,14 @@ function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell
     }
 
     if (normalizedTarget.default) {
-      if (defaultTargetId) {
+      if (enforceSingleDefault === true && defaultTargetId) {
         throw new Error(
           `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
         );
       }
-      defaultTargetId = normalizedTarget.id;
+      if (!defaultTargetId) {
+        defaultTargetId = normalizedTarget.id;
+      }
     }
 
     targetById.set(normalizedTarget.id, normalizedTarget);
@@ -161,10 +373,21 @@ function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell
 }
 
 export {
+  PLACEMENT_LAYOUT_CLASSES,
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
+  normalizePlacementKind,
+  normalizePlacementLayoutClass,
+  normalizePlacementOwnerId,
+  normalizePlacementSurfaceId,
+  normalizePlacementSurfaces,
+  normalizePlacementTopologyDefinition,
+  normalizePlacementTopologyEntry,
+  normalizePlacementTopologyVariant,
+  normalizeSemanticPlacementId,
   normalizeShellOutletTargetId,
   normalizeShellOutletTargetRecord,
+  resolvePlacementTargetReference,
   resolveShellOutletTargetParts
 };

package/shared/support/shellLayoutTargets.test.js

@@ -22,7 +22,6 @@ test("discoverShellOutletTargetsFromVueSource resolves legal targets and one def
       <ShellOutlet
         target="shell-layout:primary-menu"
         default
-        default-link-component-token="local.main.ui.surface-aware-menu-link-item"
       />
       <ShellOutlet target="shell-layout:secondary-menu" />
     </template>
@@ -37,7 +36,6 @@ test("discoverShellOutletTargetsFromVueSource resolves legal targets and one def
     discovered.targets.map((entry) => entry.id),
     ["shell-layout:top-left", "shell-layout:primary-menu", "shell-layout:secondary-menu"]
   );
-  assert.equal(discovered.targets[1].defaultLinkComponentToken, "local.main.ui.surface-aware-menu-link-item");
   assert.equal(
     describeShellOutletTargets(discovered.targets),
     "shell-layout:top-left, shell-layout:primary-menu, shell-layout:secondary-menu"
@@ -76,6 +74,26 @@ test("discoverShellOutletTargetsFromVueSource throws for multiple defaults", ()
   );
 });
 
+test("discoverShellOutletTargetsFromVueSource can collect source hints without enforcing one default", () => {
+  const source = `
+    <template>
+      <ShellOutlet target="shell-layout:primary-menu" default />
+      <ShellOutlet target="shell-layout:primary-bottom-nav" default />
+    </template>
+  `;
+
+  const discovered = discoverShellOutletTargetsFromVueSource(source, {
+    context: "ShellLayout.vue",
+    enforceSingleDefault: false
+  });
+
+  assert.equal(discovered.defaultTargetId, "shell-layout:primary-menu");
+  assert.deepEqual(
+    discovered.targets.map((entry) => entry.id),
+    ["shell-layout:primary-menu", "shell-layout:primary-bottom-nav"]
+  );
+});
+
 test("discoverShellOutletTargetsFromVueSource ignores disabled default markers", () => {
   const source = `
     <template>