@decocms/start 0.30.4 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.30.4",
+  "version": "0.31.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/cms/index.ts

@@ -9,7 +9,7 @@ export {
   setBlocks,
   withBlocksOverride,
 } from "./loader";
-export type { SectionModule, SectionOptions } from "./registry";
+export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
 export {
   getResolvedComponent,
   getSection,
@@ -19,6 +19,7 @@ export {
   listRegisteredSections,
   preloadSectionComponents,
   preloadSectionModule,
+  registerOnBeforeResolveProps,
   registerSection,
   registerSections,
   registerSectionsSync,

package/src/cms/registry.ts

@@ -1,8 +1,13 @@
 import type { ComponentType } from "react";
 
+export type OnBeforeResolveProps = (
+  props: Record<string, unknown>,
+) => Record<string, unknown>;
+
 export type SectionModule = {
   default: ComponentType<any>;
   loader?: (props: any) => Promise<any> | any;
+  onBeforeResolveProps?: OnBeforeResolveProps;
   LoadingFallback?: ComponentType<any>;
   ErrorFallback?: ComponentType<{ error: Error }>;
 };
@@ -30,6 +35,8 @@ if (!G.__deco.sectionRegistry) G.__deco.sectionRegistry = {};
 if (!G.__deco.sectionOptions) G.__deco.sectionOptions = {};
 if (!G.__deco.resolvedComponents) G.__deco.resolvedComponents = {};
 if (!G.__deco.syncComponents) G.__deco.syncComponents = {};
+if (!G.__deco.onBeforeResolvePropsRegistry)
+  G.__deco.onBeforeResolvePropsRegistry = {};
 
 const registry: Record<string, RegistryEntry> = G.__deco.sectionRegistry;
 const sectionOptions: Record<string, SectionOptions> = G.__deco.sectionOptions;
@@ -46,6 +53,13 @@ const resolvedComponents: Record<string, ComponentType<any>> = G.__deco.resolved
 // These never need React.lazy/Suspense and render identically on SSR and hydration.
 const syncComponents: Record<string, ComponentType<any>> = G.__deco.syncComponents;
 
+// onBeforeResolveProps registry — functions that transform raw CMS props
+// BEFORE resolvables are resolved. Allows sections to extract data from
+// raw resolvable structures (e.g., collection IDs from loader refs) that
+// would be lost after resolution.
+const onBeforeResolvePropsRegistry: Record<string, OnBeforeResolveProps> =
+  G.__deco.onBeforeResolvePropsRegistry;
+
 export function registerSection(key: string, loader: RegistryEntry, options?: SectionOptions) {
   registry[key] = loader;
   if (options) sectionOptions[key] = options;
@@ -129,6 +143,9 @@ export async function preloadSectionComponents(keys: string[]): Promise<void> {
         if (mod?.default) {
           resolvedComponents[key] = mod.default;
         }
+        if (mod?.onBeforeResolveProps && !onBeforeResolvePropsRegistry[key]) {
+          onBeforeResolvePropsRegistry[key] = mod.onBeforeResolveProps;
+        }
         const opts: SectionOptions = { ...sectionOptions[key] };
         if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
         if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
@@ -206,6 +223,26 @@ export function getSyncComponent(key: string): ComponentType<any> | undefined {
   return syncComponents[key];
 }
 
+/**
+ * Register an onBeforeResolveProps function for a section.
+ * Called with raw CMS props (containing unresolved `__resolveType` references)
+ * BEFORE the resolution engine resolves them. Use to extract metadata from
+ * resolvable structures that would be lost after resolution.
+ */
+export function registerOnBeforeResolveProps(
+  sectionKey: string,
+  fn: OnBeforeResolveProps,
+): void {
+  onBeforeResolvePropsRegistry[sectionKey] = fn;
+}
+
+/** Get the registered onBeforeResolveProps for a section, if any. */
+export function getOnBeforeResolveProps(
+  sectionKey: string,
+): OnBeforeResolveProps | undefined {
+  return onBeforeResolvePropsRegistry[sectionKey];
+}
+
 export function listRegisteredSections(): string[] {
   return Object.keys(registry);
 }

package/src/cms/resolve.ts

@@ -1,5 +1,5 @@
 import { findPageByPath, loadBlocks } from "./loader";
-import { getSection } from "./registry";
+import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
 import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 
@@ -9,6 +9,30 @@ if (!G.__deco) G.__deco = {};
 if (!G.__deco.commerceLoaders) G.__deco.commerceLoaders = {};
 if (!G.__deco.customMatchers) G.__deco.customMatchers = {};
 
+// ---------------------------------------------------------------------------
+// onBeforeResolveProps helper — eagerly loads the section module if needed
+// ---------------------------------------------------------------------------
+
+async function applyOnBeforeResolveProps(
+  sectionType: string,
+  props: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  let fn = getOnBeforeResolveProps(sectionType);
+  if (!fn) {
+    const loader = getSection(sectionType);
+    if (loader) {
+      try {
+        const mod = await loader();
+        if (mod?.onBeforeResolveProps) {
+          registerOnBeforeResolveProps(sectionType, mod.onBeforeResolveProps);
+          fn = mod.onBeforeResolveProps;
+        }
+      } catch {}
+    }
+  }
+  return fn ? fn(props) : props;
+}
+
 // ---------------------------------------------------------------------------
 // Well-known resolve types — extracted as constants so they're searchable
 // and overridable. Consumers migrating from deco-cx/deco may have blocks
@@ -479,7 +503,13 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
 
   // Unknown type — resolve props but preserve __resolveType (it's a section)
   const { __resolveType: _, ...rest } = obj;
-  const resolvedRest = await resolveProps(rest, childCtx);
+
+  // onBeforeResolveProps: let sections transform raw props before resolution.
+  // This runs with unresolved props (containing __resolveType refs) so sections
+  // can extract metadata that would be lost after resolution (e.g., collection IDs).
+  const propsToResolve = await applyOnBeforeResolveProps(resolveType, rest);
+
+  const resolvedRest = await resolveProps(propsToResolve, childCtx);
   return { __resolveType: resolveType, ...resolvedRest };
 }
 
@@ -1383,7 +1413,10 @@ export async function resolveDeferredSection(
     depth: 0,
   };
 
-  const resolvedProps = await resolveProps(rawProps, rctx);
+  // onBeforeResolveProps: let sections transform raw props before resolution.
+  const propsToResolve = await applyOnBeforeResolveProps(component, rawProps);
+
+  const resolvedProps = await resolveProps(propsToResolve, rctx);
   const normalizedProps = normalizeNestedSections(resolvedProps) as Record<string, unknown>;
 
   return {