@monkeyplus/flow 6.0.11 → 6.0.13

package/README.md

@@ -16,10 +16,26 @@
 
 El workspace consume la API fuente del root para mantener DX local, mientras que `dist/` genera un artefacto publicable con exports ya compilados.
 
+## Guia de uso
+
+La guia detallada de authoring vive en `docs/authoring.md` e incluye:
+
+- como registrar y configurar modulos
+- como definir paginas estaticas y dinamicas
+- como organizar templates, layouts y `*.context.ts`
+- como trabajar con `FlowIsland` y `client/islands/*`
+
+Documentacion complementaria:
+
+- `docs/modules.md`: referencia de modulos builtin
+- `docs/recipes.md`: recetas basadas en el playground actual
+
+Si vas a crear o mantener una app en Flow, ese archivo deberia ser el punto de entrada principal.
+
 ## API pública
 
 ```ts
-import { defineFlowConfig, definePage } from '@monkeyplus/flow';
+import { defineFlowConfig, defineLayoutContext, definePage } from '@monkeyplus/flow';
 import { FlowIsland } from '@monkeyplus/flow/components';
 import { getClientHead } from '@monkeyplus/flow/head';
 import sitemapModule from '@monkeyplus/flow/modules/sitemap';
@@ -29,6 +45,52 @@ import { createFlowViteConfig } from '@monkeyplus/flow/vite';
 import { installFlowVuePlugins } from '@monkeyplus/flow/vue';
 ```
 
+## Contexto de layout
+
+Los layouts pueden tener un handler de contexto colocalizado usando `views/layouts/<Layout>.context.ts`.
+
+Opcionalmente puedes definir `views/layouts/global.context.ts` para compartir datos entre todos los layouts. Flow fusiona primero el contexto global y luego el contexto especifico del layout, por lo que el layout especifico tiene prioridad si repite una clave.
+
+```ts
+import type { GlobalLayoutContextValue } from './global.context';
+// views/layouts/Default.context.ts
+import { defineLayoutContext } from '@monkeyplus/flow';
+
+const defaultLayoutContext = defineLayoutContext({
+  async setup(ctx) {
+    return {
+      menuName: 'main',
+      localeCode: ctx.locale.code,
+    };
+  },
+});
+
+export type DefaultLayoutContextValue = GlobalLayoutContextValue & Awaited<ReturnType<typeof defaultLayoutContext.setup>>;
+
+export default defaultLayoutContext;
+```
+
+Ese resultado se expone en el layout bajo `context.layout`.
+
+```vue
+<script setup lang="ts">
+import type { DefaultLayoutContextValue } from './Default.context';
+
+const props = defineProps<{
+  context?: {
+    layout?: DefaultLayoutContextValue
+  }
+}>();
+</script>
+
+<template>
+  <slot />
+  <small>{{ props.context?.layout?.menuName }}</small>
+</template>
+```
+
+Esto reemplaza el patrón anterior de `shared/contexts` para casos que pertenecen al layout. Si una lógica debe compartirse entre varios layouts, puedes ponerla en `views/layouts/global.context.ts` o extraerla a un helper `.ts` reutilizable y llamarlo desde cada `*.context.ts`.
+
 ## Playground
 
 La app de referencia vive en `playground/` y ya no en la raíz. Eso permite mantener el root enfocado en la distribución del paquete sin perder el flujo de desarrollo existente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monkeyplus/flow",
-  "version": "6.0.11",
+  "version": "6.0.13",
   "description": "@monkeyplus/flow package-first runtime with Vite, Nitro, Vue and a workspace playground.",
   "license": "MIT",
   "publishConfig": {

package/server/lib/pages.mjs

@@ -1,6 +1,8 @@
 import { createRequire } from "node:module";
+import layoutContexts from "virtual:flow/layout-contexts";
 import pageDefinitions from "virtual:flow/pages";
 import { getFlowImageRuntimeUtils } from "../../modules/images/runtime/server.mjs";
+import { mergeLayoutContextValues } from "../../src/runtime/layout-context.mjs";
 import { localizeRoutePattern, normalizePath, toPublicRoute } from "../../src/runtime/locale-routing.mjs";
 const dynamicRouteCache = /* @__PURE__ */ new Map();
 let runtimeConfigRequire;
@@ -88,6 +90,24 @@ function createContext(definition, locale, localePage, pathname, params, dynamic
     }
   };
 }
+function asContextRecord(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+async function resolveLayoutContext(definition, ctx) {
+  const layoutKey = (definition.view.layout || "default").toLowerCase();
+  const globalLayoutContext = layoutContexts.global;
+  const layoutContext = layoutKey === "global" ? void 0 : layoutContexts[layoutKey];
+  const resolvedGlobalContext = globalLayoutContext?.setup ? asContextRecord(await globalLayoutContext.setup(ctx)) : void 0;
+  const resolvedLayoutContext = layoutContext?.setup ? asContextRecord(await layoutContext.setup(ctx)) : void 0;
+  return mergeLayoutContextValues(resolvedGlobalContext, resolvedLayoutContext);
+}
+function mergeResolvedContext(context, layoutContext, dynamic, assign) {
+  const resolvedContext = assign && dynamic?.context ? { ...context, [assign]: dynamic.context, dynamic } : dynamic ? { ...context, dynamic } : context;
+  return {
+    ...resolvedContext,
+    layout: layoutContext
+  };
+}
 function isDynamicPattern(pattern) {
   return pattern.includes("/:") || pattern.includes("/**");
 }
@@ -110,6 +130,26 @@ function replacePath(pattern, url) {
 function combineName(name, dynamicName) {
   return `${name.replace(/\/*$/, "")}/${dynamicName.replace(/^\/*/, "")}`;
 }
+function resolveUrlTarget(namePage, explicitDynamicName) {
+  if (explicitDynamicName || !namePage.includes("/")) {
+    return {
+      namePage,
+      dynamicName: explicitDynamicName
+    };
+  }
+  const match = pageDefinitions.filter((candidate) => candidate.name && namePage.startsWith(`${candidate.name}/`)).sort((left, right) => right.name.length - left.name.length)[0];
+  if (!match) {
+    return {
+      namePage,
+      dynamicName: explicitDynamicName
+    };
+  }
+  const dynamicName = namePage.slice(match.name.length + 1);
+  return {
+    namePage: match.name,
+    dynamicName: dynamicName || explicitDynamicName
+  };
+}
 function getEnabledLocaleCodes() {
   const runtimeConfig = getFlowRuntimeConfig();
   return runtimeConfig.flow?.locale?.locales || [];
@@ -143,8 +183,9 @@ export async function getUrl(namePage, localeCode, options = {}) {
   const enabledLocales = getEnabledLocaleCodes();
   const targetLocale = localeCode || enabledLocales[0];
   const runtimeConfig = getFlowRuntimeConfig();
+  const target = resolveUrlTarget(namePage, options.dynamicName);
   for (const definition of pageDefinitions) {
-    if (definition.name !== namePage) {
+    if (definition.name !== target.namePage) {
       continue;
     }
     const localeEntries = targetLocale ? [targetLocale] : Object.keys(definition.locales);
@@ -160,11 +201,11 @@ export async function getUrl(namePage, localeCode, options = {}) {
       if (options.params) {
         return replacePath(localizedRoute, options.params);
       }
-      if (localePage.dynamic && options.dynamicName) {
+      if (localePage.dynamic && target.dynamicName) {
         const locale = createLocale(code);
         const ctx = createContext(definition, locale, localePage, toPublicRoute(runtimeConfig.flow, code, localePage.url), {});
         const entries = await getDynamicEntries(definition, code, ctx);
-        const entry = entries.find((candidate) => candidate.name === options.dynamicName);
+        const entry = entries.find((candidate) => candidate.name === target.dynamicName);
         if (!entry) {
           return void 0;
         }
@@ -235,9 +276,10 @@ export async function resolvePage(pathname) {
     }
     const ctx = createContext(match.definition, locale, match.localePage, pathname, match.params, dynamic);
     const head = match.localePage.head ? await match.localePage.head(ctx) : match.localePage.seo ? await match.localePage.seo(ctx) : {};
+    const layoutContext = await resolveLayoutContext(match.definition, ctx);
     const context = match.localePage.context ? await match.localePage.context(ctx) : {};
     const assign = match.localePage.dynamic?.assign;
-    const resolvedContext = assign && dynamic?.context ? { ...context, [assign]: dynamic.context, dynamic } : dynamic ? { ...context, dynamic } : context;
+    const resolvedContext = mergeResolvedContext(context, layoutContext, dynamic, assign);
     return {
       definition: match.definition,
       locale,
@@ -268,6 +310,7 @@ export async function resolvePageByName(name, pathname) {
     const params = {};
     const ctx = createContext(definition, locale, localePage, pathname, params);
     const head = localePage.head ? await localePage.head(ctx) : localePage.seo ? await localePage.seo(ctx) : {};
+    const layoutContext = await resolveLayoutContext(definition, ctx);
     const context = localePage.context ? await localePage.context(ctx) : {};
     return {
       definition,
@@ -278,7 +321,7 @@ export async function resolvePageByName(name, pathname) {
       params,
       head,
       seo: head,
-      context
+      context: mergeResolvedContext(context, layoutContext)
     };
   }
   return void 0;

package/src/public/index.d.ts

@@ -2,6 +2,8 @@ export type { ContentDirectoryNode, ContentEntry, ContentFileNode, ContentTreeNo
 export type { FlowBootPayload } from '../runtime/boot.ts';
 export { defineFlowConfig, defineFlowModule, resolveFlowConfig } from '../runtime/config.ts';
 export type { FlowConfig, UserFlowConfig, } from '../runtime/config.ts';
+export { defineLayoutContext } from '../runtime/layout-context.ts';
+export type { LayoutContextDefinition, LayoutContextValue } from '../runtime/layout-context.ts';
 export { definePage } from '../runtime/pages.ts';
 export type { FlowHydrationMode, FlowLocale, HeadDefinition, PageContextInput, PageDefinition, PageLocaleDefinition, PageViewDefinition, } from '../runtime/pages.ts';
 export { queryContent } from './query-content.ts';

package/src/public/index.mjs

@@ -1,3 +1,4 @@
 export { defineFlowConfig, defineFlowModule, resolveFlowConfig } from "../runtime/config.mjs";
+export { defineLayoutContext } from "../runtime/layout-context.mjs";
 export { definePage } from "../runtime/pages.mjs";
 export { queryContent } from "./query-content.mjs";

package/src/public/nitro.mjs

@@ -6,6 +6,7 @@ import { createFlowBuildHooks } from "../runtime/ssg.mjs";
 import {
   createVirtualBaseTemplatesModule,
   createVirtualIslandsModule,
+  createVirtualLayoutContextsModule,
   createVirtualLayoutsModule,
   createVirtualPagesModule,
   createVirtualTemplatesModule
@@ -50,6 +51,7 @@ export function createFlowNitroConfig(options = {}) {
       "virtual:flow/islands": createVirtualIslandsModule(projectRoot),
       "virtual:flow/templates": createVirtualTemplatesModule(projectRoot),
       "virtual:flow/layouts": createVirtualLayoutsModule(projectRoot),
+      "virtual:flow/layout-contexts": createVirtualLayoutContextsModule(projectRoot),
       "virtual:flow/bases": createVirtualBaseTemplatesModule(projectRoot),
       ...flowModules.nitro.virtual
     },

package/src/public/vite.mjs

@@ -14,6 +14,7 @@ import {
   createVirtualClientPageAssetsModule,
   createVirtualClientPagesModule,
   createVirtualIslandsModule,
+  createVirtualLayoutContextsModule,
   createVirtualLayoutsModule,
   createVirtualPagesModule,
   createVirtualTemplatesModule
@@ -32,12 +33,14 @@ const flowRestartPatterns = [
 ];
 const flowFullReloadPatterns = [
   /^views\/.+\.vue$/,
+  /^views\/layouts\/.+\.context\.(ts|js|mjs|mts)$/,
   /^client\/pages\/.+\.ts$/,
   /^client\/islands\/.+\.ts$/
 ];
 const flowStructureReloadPatterns = [
   /^pages\/.+\.ts$/,
   /^views\/.+\.vue$/,
+  /^views\/layouts\/.+\.context\.(ts|js|mjs|mts)$/,
   /^views\/templates\/.+\.vue$/,
   /^views\/layouts\/.+\.vue$/,
   /^views\/base\/.+\.html$/,
@@ -57,6 +60,7 @@ function getVirtualModuleIdsForPath(projectPath) {
   }
   if (projectPath.startsWith("views/layouts/")) {
     ids.add("virtual:flow/layouts");
+    ids.add("virtual:flow/layout-contexts");
   }
   if (projectPath.startsWith("views/base/")) {
     ids.add("virtual:flow/bases");
@@ -179,6 +183,7 @@ function createFlowVirtualServerModules(projectRoot, flowConfig) {
     ["virtual:flow/islands", () => createVirtualIslandsModule(projectRoot)],
     ["virtual:flow/templates", () => createVirtualTemplatesModule(projectRoot)],
     ["virtual:flow/layouts", () => createVirtualLayoutsModule(projectRoot)],
+    ["virtual:flow/layout-contexts", () => createVirtualLayoutContextsModule(projectRoot)],
     ["virtual:flow/bases", () => createVirtualBaseTemplatesModule(projectRoot)]
   ]);
   return {

package/src/runtime/layout-context.d.ts

@@ -0,0 +1,7 @@
+import type { MaybePromise, PageContextInput } from './pages.ts';
+export interface LayoutContextDefinition {
+    setup: (ctx: PageContextInput) => MaybePromise<Record<string, unknown>>;
+}
+export type LayoutContextValue<T extends LayoutContextDefinition> = Awaited<ReturnType<T['setup']>>;
+export declare function defineLayoutContext(context: LayoutContextDefinition): LayoutContextDefinition;
+export declare function mergeLayoutContextValues(...contexts: Array<Record<string, unknown> | undefined>): Record<string, unknown>;

package/src/runtime/layout-context.mjs

@@ -0,0 +1,14 @@
+export function defineLayoutContext(context) {
+  return context;
+}
+export function mergeLayoutContextValues(...contexts) {
+  return contexts.reduce((result, context) => {
+    if (!context) {
+      return result;
+    }
+    return {
+      ...result,
+      ...context
+    };
+  }, {});
+}

package/src/runtime/page-discovery.mjs

@@ -53,6 +53,26 @@ function replacePath(pattern, url) {
 function combineName(name, dynamicName) {
   return `${name.replace(/\/*$/, "")}/${dynamicName.replace(/^\/*/, "")}`;
 }
+function resolveUrlTarget(definitions, namePage, explicitDynamicName) {
+  if (explicitDynamicName || !namePage.includes("/")) {
+    return {
+      namePage,
+      dynamicName: explicitDynamicName
+    };
+  }
+  const match = definitions.filter((candidate) => candidate.name && namePage.startsWith(`${candidate.name}/`)).sort((left, right) => right.name.length - left.name.length)[0];
+  if (!match) {
+    return {
+      namePage,
+      dynamicName: explicitDynamicName
+    };
+  }
+  const dynamicName = namePage.slice(match.name.length + 1);
+  return {
+    namePage: match.name,
+    dynamicName: dynamicName || explicitDynamicName
+  };
+}
 function createContext(definitions, flowConfig, definition, locale, localePage, pathname, params, dynamic) {
   return {
     dynamic,
@@ -111,7 +131,8 @@ export async function loadPageDefinitions(projectRoot, flowConfig) {
   return pages;
 }
 export async function getUrlFromDefinitions(definitions, flowConfig, namePage, localeCode = flowConfig.locale.locales[0], options = {}) {
-  const definition = definitions.find((candidate) => candidate.name === namePage);
+  const target = resolveUrlTarget(definitions, namePage, options.dynamicName);
+  const definition = definitions.find((candidate) => candidate.name === target.namePage);
   if (!definition) {
     return void 0;
   }
@@ -126,9 +147,9 @@ export async function getUrlFromDefinitions(definitions, flowConfig, namePage, l
   if (options.params) {
     return replacePath(localizedRoute, options.params);
   }
-  if (localePage.dynamic && options.dynamicName) {
+  if (localePage.dynamic && target.dynamicName) {
     const entries = await getDynamicEntries(definitions, flowConfig, definition, localeCode, localePage);
-    const entry = entries.find((candidate) => candidate.name === options.dynamicName);
+    const entry = entries.find((candidate) => candidate.name === target.dynamicName);
     if (!entry) {
       return void 0;
     }

package/src/runtime/virtual-pages.d.ts

@@ -2,6 +2,7 @@ import type { FlowConfig } from './config';
 export declare function createVirtualPagesModule(projectRoot: string, flowConfig: FlowConfig): string;
 export declare function createVirtualTemplatesModule(projectRoot: string): string;
 export declare function createVirtualLayoutsModule(projectRoot: string): string;
+export declare function createVirtualLayoutContextsModule(projectRoot: string): string;
 export declare function createVirtualBaseTemplatesModule(projectRoot: string): string;
 export declare function createVirtualIslandsModule(projectRoot: string): string;
 export declare function createVirtualClientPagesModule(projectRoot: string): string;

package/src/runtime/virtual-pages.mjs

@@ -89,6 +89,27 @@ export function createVirtualLayoutsModule(projectRoot) {
   const files = existsSync(layoutsDir) ? collectFiles(layoutsDir, [".vue"]) : [];
   return createVirtualVueModuleSource(files, "layouts");
 }
+export function createVirtualLayoutContextsModule(projectRoot) {
+  const layoutsDir = resolve(projectRoot, "views/layouts");
+  const files = existsSync(layoutsDir) ? collectFiles(layoutsDir, [".context.ts", ".context.js", ".context.mjs", ".context.mts"]) : [];
+  const imports = files.map((filePath, index) => {
+    return `import item_${index} from ${JSON.stringify(toAbsoluteImport(filePath))};`;
+  });
+  const entries = files.map((filePath, index) => {
+    const key = basename(filePath, extname(filePath)).replace(/\.context$/i, "").toLowerCase();
+    return `${JSON.stringify(key)}: item_${index}`;
+  });
+  return [
+    ...imports,
+    "",
+    "const layoutContexts = {",
+    ...entries.map((entry) => `  ${entry},`),
+    "};",
+    "",
+    "export default layoutContexts;",
+    ""
+  ].join("\n");
+}
 export function createVirtualBaseTemplatesModule(projectRoot) {
   const baseDir = resolve(projectRoot, "views/base");
   const files = existsSync(baseDir) ? collectFiles(baseDir, [".html"]) : [];

package/src/runtime/virtual.d.ts

@@ -113,6 +113,12 @@ declare module 'virtual:flow/layouts' {
   export default layouts;
 }
 
+declare module 'virtual:flow/layout-contexts' {
+  const layoutContexts: Record<string, import('./layout-context').LayoutContextDefinition>;
+
+  export default layoutContexts;
+}
+
 declare module 'virtual:flow/bases' {
   const bases: Record<string, string>;