@ossy/app 1.37.1 → 1.37.2

package/cli/build.task.js

@@ -21,10 +21,11 @@ import getPlatformFiles, {
   EMAIL_FILE_PATTERN,
   ACTION_FILE_PATTERN,
   E2E_FILE_PATTERN,
+  LAYOUT_FILE_PATTERN,
 } from './get-platform-files.task.js'
 import { manifestPlugin } from './manifest-plugin.js'
 
-export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, RESOURCE_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN }
+export { PAGE_FILE_PATTERN, API_FILE_PATTERN, TASK_FILE_PATTERN, RESOURCE_FILE_PATTERN, COMPONENT_FILE_PATTERN, AGGREGATE_FILE_PATTERN, INTEGRATION_FILE_PATTERN, STARTUP_FILE_PATTERN, EMAIL_FILE_PATTERN, ACTION_FILE_PATTERN, E2E_FILE_PATTERN, LAYOUT_FILE_PATTERN }
 
 // Generated entry stubs live under `build/.ossy/entries/`. Putting them
 // inside `build/` means they're cleaned automatically with every build,
@@ -74,7 +75,7 @@ function entryNameFromSource (sourcePath, srcDir, packageName) {
 }
 
 function stubFileNameFor (kind, sourcePath, srcDir, packageName) {
-  const ext = (kind === 'page' || kind === 'component' || kind === 'email') ? '.entry.jsx' : '.entry.js'
+  const ext = (kind === 'page' || kind === 'component' || kind === 'email' || kind === 'layout') ? '.entry.jsx' : '.entry.js'
   return entryNameFromSource(sourcePath, srcDir, packageName) + ext
 }
 
@@ -218,6 +219,20 @@ function generateE2eStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
+// Layouts are React components that wrap page renders. The stub re-exports
+// everything (including the optional `applies` glob and required `id`) plus the
+// default component so the manifest plugin can validate them and the server
+// can inject them at render time.
+function generateLayoutStub ({ stubAbs, sourceAbs }) {
+  const importPath = relImport(stubAbs, sourceAbs)
+  return [
+    '// Generated by @ossy/app — do not edit',
+    `export * from '${importPath}'`,
+    `export { default } from '${importPath}'`,
+    '',
+  ].join('\n')
+}
+
 function stubFor (kind, args) {
   if (kind === 'page') return generatePageStub(args)
   if (kind === 'api') return generateApiStub(args)
@@ -229,6 +244,7 @@ function stubFor (kind, args) {
   if (kind === 'email') return generateEmailStub(args)
   if (kind === 'action') return generateActionStub(args)
   if (kind === 'e2e') return generateE2eStub(args)
+  if (kind === 'layout') return generateLayoutStub(args)
   return generateTaskStub(args)
 }
 
@@ -276,6 +292,7 @@ export async function build (cliArgs = []) {
     ...platformFiles.emails,
     ...platformFiles.actions,
     ...platformFiles.e2es,
+    ...platformFiles.layouts,
   ]
 
   const entriesByStub = new Map()

package/cli/get-platform-files.task.js

@@ -12,9 +12,10 @@ export const STARTUP_FILE_PATTERN = /\.startup\.(mjs|cjs|js)$/
 export const EMAIL_FILE_PATTERN = /\.email\.(jsx?|tsx?)$/
 export const ACTION_FILE_PATTERN = /\.action\.(mjs|cjs|js)$/
 export const E2E_FILE_PATTERN = /\.e2e\.(mjs|cjs|js)$/
+export const LAYOUT_FILE_PATTERN = /\.layout\.(jsx?|tsx?)$/
 
 /**
- * @typedef {'page' | 'api' | 'task' | 'resource' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'e2e'} EntryKind
+ * @typedef {'page' | 'api' | 'task' | 'resource' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'e2e' | 'layout'} EntryKind
  *
  * @typedef {object} PlatformEntry
  * @property {EntryKind} kind          Which bucket this entry lives in.
@@ -34,6 +35,7 @@ export const E2E_FILE_PATTERN = /\.e2e\.(mjs|cjs|js)$/
  * @property {PlatformEntry[]} emails        Discovered `*.email.{jsx,tsx,...}` entries.
  * @property {PlatformEntry[]} actions       Discovered `*.action.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} e2es          Discovered `*.e2e.{js,mjs,cjs}` entries (installed packages only).
+ * @property {PlatformEntry[]} layouts       Discovered `*.layout.{jsx,tsx,...}` entries.
  */
 export function discoverFilesByPattern (srcDir, filePattern) {
   const dir = path.resolve(srcDir)
@@ -63,6 +65,7 @@ function classifyFile (absPath) {
   if (EMAIL_FILE_PATTERN.test(base)) return 'email'
   if (ACTION_FILE_PATTERN.test(base)) return 'action'
   if (E2E_FILE_PATTERN.test(base)) return 'e2e'
+  if (LAYOUT_FILE_PATTERN.test(base)) return 'layout'
   return null
 }
 
@@ -138,6 +141,7 @@ export function discoverInstalledPackageEntries (projectRoot) {
       ...discoverFilesByPattern(packageSrcDir, EMAIL_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, ACTION_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, E2E_FILE_PATTERN),
+      ...discoverFilesByPattern(packageSrcDir, LAYOUT_FILE_PATTERN),
     ]
     for (const sourcePath of files) {
       const stat = fs.statSync(sourcePath)
@@ -181,8 +185,8 @@ export function discoverInstalledPackageEntries (projectRoot) {
  * @returns {Promise<PlatformFiles>}
  */
 export default async function getPlatformFiles (srcDir) {
-  const out = { pages: [], apis: [], tasks: [], resources: [], components: [], aggregates: [], integrations: [], startups: [], emails: [], actions: [], e2es: [] }
-  const bucketByKind = { page: 'pages', api: 'apis', task: 'tasks', resource: 'resources', component: 'components', aggregate: 'aggregates', integration: 'integrations', startup: 'startups', email: 'emails', action: 'actions', e2e: 'e2es' }
+  const out = { pages: [], apis: [], tasks: [], resources: [], components: [], aggregates: [], integrations: [], startups: [], emails: [], actions: [], e2es: [], layouts: [] }
+  const bucketByKind = { page: 'pages', api: 'apis', task: 'tasks', resource: 'resources', component: 'components', aggregate: 'aggregates', integration: 'integrations', startup: 'startups', email: 'emails', action: 'actions', e2e: 'e2es', layout: 'layouts' }
 
   // Aggregates and e2e tests are only discovered from installed packages — never
   // from the local `src/` — to avoid pulling in per-project duplicates of the
@@ -198,6 +202,7 @@ export default async function getPlatformFiles (srcDir) {
     ...discoverFilesByPattern(srcDir, STARTUP_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, EMAIL_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, ACTION_FILE_PATTERN),
+    ...discoverFilesByPattern(srcDir, LAYOUT_FILE_PATTERN),
   ]
   for (const sourcePath of localFiles) {
     const stat = fs.statSync(sourcePath)

package/cli/manifest-plugin.js

@@ -64,6 +64,11 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @property {string} entry   URL the platform serves the action bundle from.
  * @property {string} access  Access level: `'public'` | `'authenticated'` | `'workspace'`.
  *
+ * @typedef {object} LayoutManifestEntry
+ * @property {string} id      Unique layout id (e.g. `'app-shell'`).
+ * @property {string} entry   URL the platform serves the layout bundle from.
+ * @property {string} [applies]  Optional glob pattern of page paths this layout applies to (default `'*'` = all pages).
+ *
  * @typedef {object} E2eManifestEntry
  * @property {string} id       Unique test id (e.g. `'authentication/sign-in'`).
  * @property {string} feature  Grouping label (e.g. `'authentication'`).
@@ -80,6 +85,7 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @property {EmailManifestEntry[]} emails          Discovered `*.email.{jsx,tsx}` entries.
  * @property {ActionManifestEntry[]} actions        Discovered `*.action.js` entries.
  * @property {E2eManifestEntry[]} e2es              Discovered `*.e2e.js` entries from installed packages.
+ * @property {LayoutManifestEntry[]} layouts        Discovered `*.layout.{jsx,tsx}` entries.
  * @property {object} config                        Inlined `src/config.js` default export.
  */
 
@@ -147,7 +153,9 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       /** @type {E2eManifestEntry[]} */
       const e2es = []
       const seenE2eIds = new Set()
-
+      /** @type {LayoutManifestEntry[]} */
+      const layouts = []
+      const seenLayoutIds = new Set()
       for (const fileName of Object.keys(bundle)) {
         const chunk = bundle[fileName]
         if (chunk.type !== 'chunk' || !chunk.isEntry) continue
@@ -329,6 +337,33 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           continue
         }
 
+        // Layouts wrap page renders automatically. The bundle exports `id`
+        // (a unique slug), an optional `applies` glob, and a default export
+        // (the React component). They don't produce routable entries; they
+        // accumulate into a separate `layouts` array so the server can
+        // match and inject them at render time.
+        if (entryInfo.kind === 'layout') {
+          const layoutId = mod && mod.id
+          const component = mod && mod.default
+          if (typeof layoutId !== 'string' || layoutId.trim() === '') {
+            this.error(
+              `[@ossy/app][build] layout entry ${entryInfo.sourcePath} must export a non-empty string "id"`,
+            )
+          }
+          if (typeof component !== 'function') {
+            this.error(
+              `[@ossy/app][build] layout entry ${entryInfo.sourcePath} must default-export a React component function`,
+            )
+          }
+          if (seenLayoutIds.has(layoutId)) {
+            this.error(`[@ossy/app][build] Duplicate layout id "${layoutId}"`)
+          }
+          seenLayoutIds.add(layoutId)
+          const applies = typeof mod.applies === 'string' ? mod.applies : '*'
+          layouts.push({ id: layoutId, entry: url, applies })
+          continue
+        }
+
         // Resources are pure data — the default export *is* the template.
         // They don't use `metadata`, don't need a derived id, and don't
         // produce a routable manifest entry; they accumulate into a separate
@@ -390,7 +425,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       }
 
       /** @type {Manifest} */
-      const manifest = { entries, components, resourceTemplates, aggregates, integrations, startups, emails, actions, e2es, config: configValue || {} }
+      const manifest = { entries, components, resourceTemplates, aggregates, integrations, startups, emails, actions, e2es, layouts, config: configValue || {} }
       fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
       fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "1.37.1",
+  "version": "1.37.2",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -38,14 +38,14 @@
     "@babel/eslint-parser": "^7.15.8",
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
-    "@ossy/design-system": "^1.37.1",
+    "@ossy/design-system": "^1.37.2",
     "@ossy/pages": "^1.23.0",
-    "@ossy/platform": "^1.36.1",
-    "@ossy/router": "^1.37.1",
-    "@ossy/router-react": "^1.37.1",
-    "@ossy/sdk": "^1.37.1",
-    "@ossy/sdk-react": "^1.37.1",
-    "@ossy/themes": "^1.37.1",
+    "@ossy/platform": "^1.36.2",
+    "@ossy/router": "^1.37.2",
+    "@ossy/router-react": "^1.37.2",
+    "@ossy/sdk": "^1.37.2",
+    "@ossy/sdk-react": "^1.37.2",
+    "@ossy/themes": "^1.37.2",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -79,5 +79,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "d5b71d16ec56c819401c7a74f95d12b2347ca3c4"
+  "gitHead": "723d9d35aba3cd43700ecd6e72a7e7de96acff65"
 }

package/runtime/page-runtime.js

@@ -26,8 +26,10 @@ export async function loadComponents (entries = []) {
   return map
 }
 
-function buildTree ({ Component, metadata, props }) {
+function buildTree ({ Component, Layout, metadata, props }) {
   const lang = props.htmlLang || props.defaultLanguage || 'en'
+  const pageEl = createElement(Component, props)
+  const contentEl = Layout ? createElement(Layout, props, pageEl) : pageEl
   return createElement(
     'html',
     { lang },
@@ -37,7 +39,7 @@ function buildTree ({ Component, metadata, props }) {
       createElement('meta', { charSet: 'utf-8' }),
       createElement('title', null, metadata.title || props.documentTitle || ''),
     ),
-    createElement(App, props, createElement(Component, props)),
+    createElement(App, props, contentEl),
   )
 }
 
@@ -75,9 +77,9 @@ export function createPageEntry (pageModule, options = {}) {
       import('node:stream'),
     ])
 
-    const { componentEntries = [], ...pageProps } = props
+    const { Layout = null, componentEntries = [], ...pageProps } = props
     const components = await loadComponents(componentEntries)
-    const tree = buildTree({ Component, metadata, props: { ...pageProps, components } })
+    const tree = buildTree({ Component, Layout, metadata, props: { ...pageProps, components } })
     const bootstrapUrl = toBootstrapUrl(entryUrl)
     const bootstrapModules = bootstrapUrl ? [bootstrapUrl] : []
     const bootstrapScriptContent =
@@ -109,12 +111,12 @@ export function createPageEntry (pageModule, options = {}) {
     if (typeof document === 'undefined' || typeof window === 'undefined') return
     hydrated = true
     const props = window.__OSSY__ || {}
-    const { componentEntries = [], ...pageProps } = props
+    const { Layout = null, componentEntries = [], ...pageProps } = props
     Promise.all([
       import('react-dom/client'),
       loadComponents(componentEntries),
     ]).then(([{ hydrateRoot }, components]) => {
-      hydrateRoot(document, buildTree({ Component, metadata, props: { ...pageProps, components } }))
+      hydrateRoot(document, buildTree({ Component, Layout, metadata, props: { ...pageProps, components } }))
     })
   }