@decocms/blocks 7.9.0 → 7.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.9.0",
+  "version": "7.11.0",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {

package/src/cms/client.ts

@@ -51,13 +51,22 @@ export {
 } from "./registry";
 export type { SectionLoaderFn } from "./sectionLoaders";
 export { compose, withDevice, withMobile, withSearchParam, withSectionLoader } from "./sectionMixins";
-export type { ActionConfig, LoaderConfig, MatcherConfig, MetaResponse } from "./schema";
+export type {
+  ActionConfig,
+  AppSchemas,
+  BlockPropsSchema,
+  LoaderConfig,
+  MatcherConfig,
+  MetaResponse,
+} from "./schema";
 export {
   composeMeta,
   getRegisteredLoaders,
   getRegisteredMatchers,
+  inferLoaderTags,
   registerActionSchema,
   registerActionSchemas,
+  registerAppSchemas,
   registerLoaderSchema,
   registerLoaderSchemas,
   registerMatcherSchema,

package/src/cms/index.ts

@@ -100,13 +100,22 @@ export {
 } from "./sectionMixins";
 export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
 export { applySectionConventions } from "./applySectionConventions";
-export type { ActionConfig, LoaderConfig, MatcherConfig, MetaResponse } from "./schema";
+export type {
+  ActionConfig,
+  AppSchemas,
+  BlockPropsSchema,
+  LoaderConfig,
+  MatcherConfig,
+  MetaResponse,
+} from "./schema";
 export {
   composeMeta,
   getRegisteredLoaders,
   getRegisteredMatchers,
+  inferLoaderTags,
   registerActionSchema,
   registerActionSchemas,
+  registerAppSchemas,
   registerLoaderSchema,
   registerLoaderSchemas,
   registerMatcherSchema,

package/src/cms/resolve.ts

@@ -1,5 +1,6 @@
 import {
   type ActionConfig,
+  inferLoaderTags,
   type LoaderConfig,
   registerActionSchemas,
   registerLoaderSchemas,
@@ -456,6 +457,9 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
 
   // Auto-register loader + action schemas for the admin manifest.
   // Separate actions (keys containing "/actions/") from loaders.
+  // These are stub registrations (isStub) — a real schema for the same key
+  // (registered via registerAppSchemas from an app's schemas.gen.ts) always
+  // wins, no matter which side registers first.
   const loaderConfigs: LoaderConfig[] = [];
   const actionConfigs: ActionConfig[] = [];
 
@@ -464,7 +468,7 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
     const schema = { type: "object" as const, additionalProperties: true };
 
     if (key.includes("/actions/")) {
-      actionConfigs.push({ key, title: key, namespace, propsSchema: schema });
+      actionConfigs.push({ key, title: key, namespace, propsSchema: schema, isStub: true });
     } else {
       loaderConfigs.push({
         key,
@@ -472,6 +476,7 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
         namespace,
         propsSchema: schema,
         tags: inferLoaderTags(key),
+        isStub: true,
       });
     }
   }
@@ -480,18 +485,6 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
   registerActionSchemas(actionConfigs);
 }
 
-function inferLoaderTags(key: string): string[] {
-  if (
-    key.includes("productList") ||
-    key.includes("ProductList") ||
-    key.includes("ProductShelf") ||
-    key.includes("SearchResult")
-  ) {
-    return ["product-list"];
-  }
-  return [];
-}
-
 /** Delete a single commerce loader by key. No-op if key is absent. */
 export function unregisterCommerceLoader(key: string): void {
   delete commerceLoaders[key];

package/src/cms/schema.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Tests for the schema registry's real-over-stub precedence and the
+ * definition builders' additionalProperties preservation.
+ *
+ * Background: registerCommerceLoaders() auto-registers a
+ * `{ type: "object", additionalProperties: true }` stub for every commerce
+ * loader/action key. App packages register REAL props schemas (from their
+ * build-time schemas.gen.ts) via registerAppSchemas(). The published meta
+ * must contain the real schema no matter which side registered first, and
+ * the stub's additionalProperties flag must survive into the definition so
+ * the Studio can tell "props unknown — edit as JSON" apart from "takes no
+ * input".
+ *
+ * NOTE: the registries are module-global singletons — every test uses its own
+ * unique keys instead of resetting shared state.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  composeMeta,
+  getRegisteredLoaders,
+  type MetaResponse,
+  registerActionSchema,
+  registerAppSchemas,
+  registerLoaderSchema,
+} from "./schema";
+
+const b64 = (s: string) => Buffer.from(s).toString("base64");
+
+const emptySiteMeta = (): MetaResponse => ({
+  major: 1,
+  version: "1.0.0",
+  namespace: "site",
+  site: "test",
+  manifest: { blocks: {} },
+  schema: { definitions: {}, root: {} },
+});
+
+const STUB_SCHEMA = { type: "object" as const, additionalProperties: true };
+
+function stubLoader(key: string) {
+  registerLoaderSchema({
+    key,
+    title: key,
+    namespace: "vtex",
+    propsSchema: STUB_SCHEMA,
+    isStub: true,
+  });
+}
+
+const REAL_PLP_PROPS = {
+  type: "object" as const,
+  properties: {
+    sort: {
+      type: "string",
+      enum: ["OrderByPriceDESC", "OrderByPriceASC", "OrderByTopSaleDESC"],
+    },
+    count: { type: "number" },
+    fq: { type: "string" },
+  },
+  required: ["count"],
+};
+
+function realLoader(key: string) {
+  registerAppSchemas({ namespace: "vtex", loaders: { [key]: REAL_PLP_PROPS } });
+}
+
+function definitionFor(key: string) {
+  return composeMeta(emptySiteMeta()).schema.definitions[b64(key)];
+}
+
+describe("real-over-stub precedence", () => {
+  it("keeps the real schema when the stub registers afterwards (loaders)", () => {
+    const key = "vtex/loaders/test/realThenStub.ts";
+    realLoader(key);
+    stubLoader(key);
+
+    const def = definitionFor(key);
+    expect(def.properties.sort.enum).toEqual([
+      "OrderByPriceDESC",
+      "OrderByPriceASC",
+      "OrderByTopSaleDESC",
+    ]);
+    expect(def.required).toEqual(["__resolveType", "count"]);
+    expect(def.additionalProperties).toBeUndefined();
+  });
+
+  it("replaces the stub when the real schema registers afterwards (loaders)", () => {
+    const key = "vtex/loaders/test/stubThenReal.ts";
+    stubLoader(key);
+    realLoader(key);
+
+    const def = definitionFor(key);
+    expect(def.properties.count).toEqual({ type: "number" });
+    expect(def.additionalProperties).toBeUndefined();
+  });
+
+  it("applies the same precedence to actions", () => {
+    const key = "vtex/actions/test/addCoupon.ts";
+    registerAppSchemas({
+      namespace: "vtex",
+      actions: {
+        [key]: {
+          type: "object",
+          properties: { coupon: { type: "string" } },
+          required: ["coupon"],
+        },
+      },
+    });
+    registerActionSchema({
+      key,
+      title: key,
+      namespace: "vtex",
+      propsSchema: STUB_SCHEMA,
+      isStub: true,
+    });
+
+    const def = definitionFor(key);
+    expect(def.properties.coupon).toEqual({ type: "string" });
+    expect(def.required).toEqual(["__resolveType", "coupon"]);
+    expect(def.additionalProperties).toBeUndefined();
+  });
+
+  it("lets a later stub replace an earlier stub (hot-reload re-registration)", () => {
+    const key = "vtex/loaders/test/stubTwice.ts";
+    stubLoader(key);
+    stubLoader(key);
+    expect(definitionFor(key).additionalProperties).toBe(true);
+  });
+
+  it("lets a later real schema replace an earlier real schema", () => {
+    const key = "vtex/loaders/test/realTwice.ts";
+    realLoader(key);
+    registerAppSchemas({
+      namespace: "vtex",
+      loaders: {
+        [key]: { type: "object", properties: { slug: { type: "string" } } },
+      },
+    });
+    const def = definitionFor(key);
+    expect(def.properties.slug).toEqual({ type: "string" });
+    expect(def.properties.sort).toBeUndefined();
+  });
+});
+
+describe("additionalProperties preservation in definitions", () => {
+  it("emits additionalProperties: true for stub-only keys (props unknown → JSON editor)", () => {
+    const key = "vtex/loaders/test/stubOnly.ts";
+    stubLoader(key);
+
+    const def = definitionFor(key);
+    expect(def.additionalProperties).toBe(true);
+    expect(Object.keys(def.properties)).toEqual(["__resolveType"]);
+  });
+
+  it("emits NO additionalProperties for a real schema without props (takes no input)", () => {
+    const key = "vtex/loaders/test/noInput.ts";
+    registerAppSchemas({
+      namespace: "vtex",
+      loaders: { [key]: { type: "object", properties: {} } },
+    });
+
+    const def = definitionFor(key);
+    expect(def.additionalProperties).toBeUndefined();
+    expect(Object.keys(def.properties)).toEqual(["__resolveType"]);
+  });
+});
+
+describe("registerAppSchemas", () => {
+  it("registers every key form present in the artifact (bare and .ts)", () => {
+    const bare = "vtex/loaders/test/aliased";
+    registerAppSchemas({
+      namespace: "vtex",
+      loaders: {
+        [bare]: REAL_PLP_PROPS,
+        [`${bare}.ts`]: REAL_PLP_PROPS,
+      },
+    });
+
+    const meta = composeMeta(emptySiteMeta());
+    for (const key of [bare, `${bare}.ts`]) {
+      const def = meta.schema.definitions[b64(key)];
+      expect(def.properties.sort.enum).toContain("OrderByPriceDESC");
+      expect(def.properties.__resolveType.enum).toEqual([key]);
+      expect(meta.manifest.blocks.loaders[key]).toEqual({
+        $ref: `#/definitions/${b64(key)}`,
+        namespace: "vtex",
+      });
+    }
+  });
+
+  it("propagates schema title/description into the definition", () => {
+    const key = "vtex/loaders/test/titled.ts";
+    registerAppSchemas({
+      namespace: "vtex",
+      loaders: {
+        [key]: {
+          type: "object",
+          title: "Product Listing Page",
+          description: "Fetches a PLP",
+          properties: { term: { type: "string" } },
+        },
+      },
+    });
+
+    const def = definitionFor(key);
+    expect(def.title).toBe("Product Listing Page");
+    expect(def.description).toBe("Fetches a PLP");
+  });
+
+  it("infers the product-list tag for loader keys, matching the stub inference", () => {
+    const key = "vtex/loaders/test/productListShelf.ts";
+    registerAppSchemas({
+      namespace: "vtex",
+      loaders: { [key]: { type: "object", properties: {} } },
+    });
+
+    const registered = getRegisteredLoaders().find((l) => l.key === key);
+    expect(registered?.tags).toEqual(["product-list"]);
+  });
+});

package/src/cms/schema.ts

@@ -68,6 +68,12 @@ export interface LoaderConfig {
   propsSchema: Record<string, any>;
   /** Tags for property matching (e.g., "product-list" enables injection into Product[] props). */
   tags?: string[];
+  /**
+   * Auto-registered placeholder with no real props (see registerCommerceLoaders).
+   * A stub never overwrites a real schema for the same key, regardless of
+   * registration order.
+   */
+  isStub?: boolean;
 }
 
 const loaderRegistry: LoaderConfig[] = [];
@@ -76,6 +82,7 @@ const loaderRegistry: LoaderConfig[] = [];
 export function registerLoaderSchema(config: LoaderConfig) {
   const idx = loaderRegistry.findIndex((l) => l.key === config.key);
   if (idx >= 0) {
+    if (config.isStub && !loaderRegistry[idx].isStub) return;
     loaderRegistry[idx] = config;
   } else {
     loaderRegistry.push(config);
@@ -107,6 +114,8 @@ export interface ActionConfig {
   description?: string;
   icon?: string;
   propsSchema: Record<string, any>;
+  /** Auto-registered placeholder — never overwrites a real schema. See LoaderConfig.isStub. */
+  isStub?: boolean;
 }
 
 const actionRegistry: ActionConfig[] = [];
@@ -115,6 +124,7 @@ const actionRegistry: ActionConfig[] = [];
 export function registerActionSchema(config: ActionConfig) {
   const idx = actionRegistry.findIndex((a) => a.key === config.key);
   if (idx >= 0) {
+    if (config.isStub && !actionRegistry[idx].isStub) return;
     actionRegistry[idx] = config;
   } else {
     actionRegistry.push(config);
@@ -126,6 +136,74 @@ export function registerActionSchemas(configs: ActionConfig[]) {
   for (const config of configs) registerActionSchema(config);
 }
 
+// ---------------------------------------------------------------------------
+// App block schemas — real props generated at app build time
+// ---------------------------------------------------------------------------
+
+/**
+ * Loader keys matching these substrings return product lists — the admin uses
+ * the "product-list" tag to offer them as loader pickers on Product[] props.
+ */
+export function inferLoaderTags(key: string): string[] {
+  if (
+    key.includes("productList") ||
+    key.includes("ProductList") ||
+    key.includes("ProductShelf") ||
+    key.includes("SearchResult")
+  ) {
+    return ["product-list"];
+  }
+  return [];
+}
+
+/**
+ * Props schema of a single loader/action as emitted by blocks-cli's
+ * generate-app-schemas.ts into an app package's src/schemas.gen.ts.
+ * Same shape generate-schema.ts produces for site loaders.
+ */
+export interface BlockPropsSchema {
+  type?: "object";
+  title?: string;
+  description?: string;
+  properties?: Record<string, any>;
+  required?: string[];
+  additionalProperties?: boolean;
+  /** Any other JSON Schema keyword or JSDoc passthrough tag (nullable, …). */
+  [keyword: string]: any;
+}
+
+export interface AppSchemas {
+  namespace: string;
+  loaders?: Record<string, BlockPropsSchema>;
+  actions?: Record<string, BlockPropsSchema>;
+}
+
+/**
+ * Register the real loader/action props schemas an app package generated at
+ * build time (src/schemas.gen.ts). These take precedence over the
+ * `__resolveType`-only stubs auto-registered by registerCommerceLoaders(),
+ * regardless of which side registers first.
+ */
+export function registerAppSchemas(app: AppSchemas): void {
+  const loaderConfigs: LoaderConfig[] = Object.entries(app.loaders ?? {}).map(([key, schema]) => ({
+    key,
+    title: schema.title || key,
+    namespace: app.namespace,
+    ...(schema.description ? { description: schema.description } : {}),
+    propsSchema: schema,
+    tags: inferLoaderTags(key),
+  }));
+  const actionConfigs: ActionConfig[] = Object.entries(app.actions ?? {}).map(([key, schema]) => ({
+    key,
+    title: schema.title || key,
+    namespace: app.namespace,
+    ...(schema.description ? { description: schema.description } : {}),
+    propsSchema: schema,
+  }));
+  registerLoaderSchemas(loaderConfigs);
+  registerActionSchemas(actionConfigs);
+}
+
 function buildActionDefinitions() {
   const definitions: Record<string, any> = {};
   const manifestBlocks: Record<string, any> = {};
@@ -134,7 +212,7 @@ function buildActionDefinitions() {
     const defKey = toBase64(action.key);
 
     definitions[defKey] = {
-      title: action.key,
+      title: action.title || action.key,
       ...(action.description ? { description: action.description } : {}),
       ...(action.icon ? { icon: action.icon } : {}),
       type: "object",
@@ -147,6 +225,9 @@ function buildActionDefinitions() {
         },
         ...(action.propsSchema?.properties || {}),
       },
+      // Preserved so the admin can tell "props unknown — edit as JSON" (stub)
+      // apart from "takes no input" (real schema without the flag).
+      ...(action.propsSchema?.additionalProperties === true ? { additionalProperties: true } : {}),
     };
 
     manifestBlocks[action.key] = {
@@ -493,7 +574,7 @@ function buildLoaderDefinitions() {
     const defKey = toBase64(loader.key);
 
     definitions[defKey] = {
-      title: loader.key,
+      title: loader.title || loader.key,
       ...(loader.description ? { description: loader.description } : {}),
       ...(loader.icon ? { icon: loader.icon } : {}),
       type: "object",
@@ -506,6 +587,9 @@ function buildLoaderDefinitions() {
         },
         ...(loader.propsSchema?.properties || {}),
       },
+      // Preserved so the admin can tell "props unknown — edit as JSON" (stub)
+      // apart from "takes no input" (real schema without the flag).
+      ...(loader.propsSchema?.additionalProperties === true ? { additionalProperties: true } : {}),
     };
 
     manifestBlocks[loader.key] = {
@@ -544,6 +628,7 @@ function buildMatcherDefinitions() {
         },
         ...(matcher.propsSchema?.properties || {}),
       },
+      ...(matcher.propsSchema?.additionalProperties === true ? { additionalProperties: true } : {}),
     };
     manifestBlocks[matcher.key] = {
       $ref: `#/definitions/${defKey}`,