@ossy/app 1.39.6 → 1.40.0

package/README.md

@@ -113,22 +113,25 @@ Build output: `build/.ossy/tasks.generated.json` — a registry of `[{ type, mod
 
 ## Components (`*.component.jsx`)
 
-Create `*.component.jsx` files in `src/` (or in any package dependency) to register slot-injectable components. The build discovers them automatically and bundles them separately — they are loaded on every page and slotted in by the layout when `metadata.id` matches the active page id.
+Register injectable UI via `*.component.jsx` in `src/` or feature packages. Components are bundled separately and resolved into slots at runtime.
 
-```jsx
-// src/workspace-users.component.jsx
-export const metadata = {
-  id: 'workspace/users', // rendered when pageId === 'workspace/users'
-}
+**Shell chrome** — the app assigns placement in `*.layout.jsx`:
 
-export default function WorkspaceUsersContent() {
-  return <div>Users content</div>
+```jsx
+export const slots = {
+  'shell:header': 'app-header',
+  'shell:sidebar': 'app-sidebar',
 }
 ```
 
-In your layout, use `<Slot name={app?.pageId} fallback={children} />` from `@ossy/design-system` to render the matching component (or fall back to the page's own output).
+**Resource / input UI** — feature packages use `metadata.id` as the slot key:
+
+```jsx
+export const metadata = { id: 'resource:booking/service/form' }
+export default function ServiceForm() { … }
+```
 
-See [`docs/component-primitive.md`](./docs/component-primitive.md) for the full contract, flow diagram, and examples.
+See [`docs/component-primitive.md`](./docs/component-primitive.md) and [design-system/docs/SLOTS.md](../design-system/docs/SLOTS.md).
 
 ## Port configuration
 

package/cli/build.task.js

@@ -22,10 +22,12 @@ import getPlatformFiles, {
   ACTION_FILE_PATTERN,
   E2E_FILE_PATTERN,
   LAYOUT_FILE_PATTERN,
+  TRANSLATIONS_FILE_PATTERN,
 } from './get-platform-files.task.js'
 import { manifestPlugin } from './manifest-plugin.js'
+import { mergeAndEmitTranslations } from './merge-translations.task.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, LAYOUT_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, TRANSLATIONS_FILE_PATTERN }
 
 // Generated entry stubs live under `build/.ossy/entries/`. Putting them
 // inside `build/` means they're cleaned automatically with every build,
@@ -137,14 +139,8 @@ function generateResourceStub ({ stubAbs, sourceAbs }) {
 }
 
 // Components are re-exported as-is — the manifest plugin reads `metadata.id`
-// and the optional `slot` export from the bundled output. Components don't get
-// route stubs or hydration bootstrapping; they're loaded on-demand at runtime.
-// The `slot` export (when present) identifies the named shell slot this
-// component fills automatically — see PlatformShell for the slot registry.
-// We use `export *` for named exports rather than an explicit list because
-// `slot` is optional: some components don't export it, and a static named
-// re-export of a binding that doesn't exist causes a Rollup MISSING_EXPORT
-// error at build time.
+// from the bundled output. Shell placement is app-controlled via `export const slots`
+// in `*.layout.jsx`, not `export const slot` on components.
 function generateComponentStub ({ stubAbs, sourceAbs }) {
   const importPath = relImport(stubAbs, sourceAbs)
   return [
@@ -191,13 +187,13 @@ function generateStartupStub ({ stubAbs, sourceAbs }) {
   ].join('\n')
 }
 
-// Emails are React components. The stub re-exports `id`, `subject`, and the
-// default component export so the manifest plugin can validate them.
+// Emails are React components. The stub re-exports `id` and the default component.
+// Optional `subject` may be resolved from translations at send time instead.
 function generateEmailStub ({ stubAbs, sourceAbs }) {
   const importPath = relImport(stubAbs, sourceAbs)
   return [
     '// Generated by @ossy/app — do not edit',
-    `export { id, subject, default } from '${importPath}'`,
+    `export { id, default } from '${importPath}'`,
     '',
   ].join('\n')
 }
@@ -261,6 +257,15 @@ async function loadConfig (configPath) {
   return mod.default || {}
 }
 
+function readAppPackageName (cwd) {
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'))
+    return typeof pkgJson.name === 'string' && pkgJson.name.trim() ? pkgJson.name : '@ossy/app'
+  } catch {
+    return '@ossy/app'
+  }
+}
+
 export async function build (cliArgs = []) {
   arg(
     {
@@ -317,6 +322,7 @@ export async function build (cliArgs = []) {
 
   const configPath = path.resolve(srcDir, 'config.js')
   const configValue = await loadConfig(configPath)
+  const appPackageName = readAppPackageName(cwd)
 
   const middlewareSrc = path.resolve(srcDir, 'middleware.js')
   if (fs.existsSync(middlewareSrc)) {
@@ -374,7 +380,9 @@ export async function build (cliArgs = []) {
         srcDir,
         staticOutDir,
         configValue,
+        appPackageName,
         manifestPath: path.join(buildPath, 'manifest.json'),
+        projectRoot: cwd,
       }),
     ],
   })
@@ -393,4 +401,12 @@ export async function build (cliArgs = []) {
     fs.cpSync(publicSrc, publicOutDir, { recursive: true, force: true })
   }
 
+  mergeAndEmitTranslations({
+    srcDir,
+    projectRoot: cwd,
+    publicOutDir,
+    manifestPath: path.join(buildPath, 'manifest.json'),
+    configValue,
+    warn: (message) => console.warn(message),
+  })
 }

package/cli/discover-translation-files.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {
+  discoverFilesByPattern,
+  TRANSLATIONS_FILE_PATTERN,
+} from './get-platform-files.task.js'
+import {
+  isValidLocaleCode,
+  parseLocaleFromTranslationFilename,
+} from '@ossy/locale'
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function collectNodeModulesDirs (projectRoot) {
+  const dirs = []
+  let current = projectRoot
+  while (true) {
+    const nm = path.join(current, 'node_modules')
+    if (fs.existsSync(nm) && fs.statSync(nm).isDirectory()) dirs.push(nm)
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return dirs
+}
+
+/**
+ * @typedef {import('@ossy/locale').TranslationSourceFile} TranslationSourceFile
+ */
+
+/**
+ * Discover `*.translations.json` from installed packages and app `src/`.
+ *
+ * @param {{ srcDir: string, projectRoot: string }} options
+ * @returns {TranslationSourceFile[]}
+ */
+export function discoverTranslationFiles ({ srcDir, projectRoot }) {
+  /** @type {TranslationSourceFile[]} */
+  const files = []
+  const seenPaths = new Set()
+
+  const nmDirs = collectNodeModulesDirs(projectRoot)
+  /** @type {Array<{ packageName: string, sourcePath: string }>} */
+  const packageFiles = []
+
+  const tryPackageDir = (pkgDir) => {
+    const real = fs.realpathSync(pkgDir)
+    const pkgJsonPath = path.join(real, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) return
+
+    let pkg
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+    } catch {
+      return
+    }
+    if (!pkg.ossy?.src) return
+
+    const packageSrcDir = path.resolve(real, pkg.ossy.src)
+    const matches = discoverFilesByPattern(packageSrcDir, TRANSLATIONS_FILE_PATTERN)
+    for (const sourcePath of matches) {
+      const stat = fs.statSync(sourcePath)
+      if (!stat.isFile() || stat.size === 0) continue
+      packageFiles.push({ packageName: pkg.name, sourcePath })
+    }
+  }
+
+  for (const nmDir of nmDirs) {
+    for (const entry of fs.readdirSync(nmDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+      if (entry.name.startsWith('@')) {
+        const scopeDir = path.join(nmDir, entry.name)
+        if (!fs.existsSync(scopeDir)) continue
+        for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+          if (scoped.isDirectory() || scoped.isSymbolicLink()) {
+            tryPackageDir(path.join(scopeDir, scoped.name))
+          }
+        }
+      } else {
+        tryPackageDir(path.join(nmDir, entry.name))
+      }
+    }
+  }
+
+  packageFiles.sort((a, b) => {
+    const byPackage = a.packageName.localeCompare(b.packageName)
+    if (byPackage !== 0) return byPackage
+    return a.sourcePath.localeCompare(b.sourcePath)
+  })
+
+  for (const { packageName, sourcePath } of packageFiles) {
+    if (seenPaths.has(sourcePath)) continue
+    seenPaths.add(sourcePath)
+    const locale = parseLocaleFromTranslationFilename(path.basename(sourcePath))
+    if (!locale) continue
+    files.push({
+      locale,
+      sourcePath,
+      tier: 'package',
+      packageName,
+      sortKey: `${packageName}:${sourcePath}`,
+    })
+  }
+
+  const appFiles = discoverFilesByPattern(srcDir, TRANSLATIONS_FILE_PATTERN).sort()
+  for (const sourcePath of appFiles) {
+    if (seenPaths.has(sourcePath)) continue
+    seenPaths.add(sourcePath)
+    const stat = fs.statSync(sourcePath)
+    if (!stat.isFile() || stat.size === 0) continue
+    const locale = parseLocaleFromTranslationFilename(path.basename(sourcePath))
+    if (!locale) continue
+    files.push({
+      locale,
+      sourcePath,
+      tier: 'app',
+      sortKey: sourcePath,
+    })
+  }
+
+  return files
+}
+
+/**
+ * @param {TranslationSourceFile[]} files
+ */
+export function validateTranslationLocales (files) {
+  for (const file of files) {
+    if (!isValidLocaleCode(file.locale)) {
+      throw new Error(
+        `[@ossy/app][build] Invalid locale "${file.locale}" in ${file.sourcePath}. ` +
+        'Expected ISO 639-1 code (e.g. en, sv).',
+      )
+    }
+  }
+}

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

@@ -13,6 +13,7 @@ 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?)$/
+export const TRANSLATIONS_FILE_PATTERN = /\.translations\.json$/
 
 /**
  * @typedef {'page' | 'api' | 'task' | 'resource' | 'component' | 'aggregate' | 'integration' | 'startup' | 'email' | 'action' | 'e2e' | 'layout'} EntryKind

package/cli/manifest-plugin.js

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.js'
+import { discoverPackageDefinitions } from '../src/manifest/discover-package-definitions.js'
 
 /**
  * @typedef {import('./get-platform-files.task.js').PlatformEntry} PlatformEntry
@@ -24,8 +25,13 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  *   The serializable config object (typically `src/config.js`'s default
  *   export). Inlined under `manifest.config` so the platform server doesn't
  *   need a runtime `import('./config.js')`.
+ * @property {string} appPackageName
+ *   npm package name of the app being built (e.g. `@ossy/app-test`). Used as
+ *   the `package` field on manifest entries that live in the app `src/` tree.
  * @property {string} manifestPath
  *   Absolute path to write the manifest to (typically `build/manifest.json`).
+ * @property {string} projectRoot
+ *   Absolute path to the consuming app root — used to discover package definitions.
  *
  * @typedef {'page' | 'api' | 'task'} ManifestEntryType
  *
@@ -41,12 +47,6 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @typedef {object} ComponentManifestEntry
  * @property {string} id      Unique component id (from `metadata.id`).
  * @property {string} entry   URL the platform serves the component bundle from.
- * @property {string} [slot]  Named shell slot this component fills (from `export const slot`).
- *
- * @typedef {object} SlotManifestEntry
- * @property {string} slot     Named shell slot (e.g. `'header'`, `'sidebar'`, `'resource:booking/service/form'`).
- * @property {string} entry    URL the platform serves the component bundle from.
- * @property {string} [package] npm package name that contributed this slot (from installed packages).
  *
  * @typedef {object} AggregateManifestEntry
  * @property {string} id     AggregateType string (e.g. `'User'`).
@@ -73,6 +73,8 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @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 {Record<string, string>} [slots]
+ *   App-controlled slot map (`slotName` → component `metadata.id`), from `export const slots` in `*.layout.jsx`.
  *
  * @typedef {object} E2eManifestEntry
  * @property {string} id       Unique test id (e.g. `'authentication/sign-in'`).
@@ -83,7 +85,6 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @typedef {object} Manifest
  * @property {ManifestEntry[]} entries              Flat, ordered list of every routable thing.
  * @property {ComponentManifestEntry[]} components  Discovered `*.component.*` entries, keyed by id.
- * @property {SlotManifestEntry[]} slots            Components that declare `export const slot` — auto-injected into shell slots.
  * @property {object[]} resourceTemplates           Each `*.resource.js` file's default-exported template object.
  * @property {AggregateManifestEntry[]} aggregates  Discovered `*.aggregate.js` entries from installed packages.
  * @property {IntegrationManifestEntry[]} integrations  Discovered `*.integration.js` entries.
@@ -91,8 +92,9 @@ 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 {LayoutManifestEntry[]} layouts        Discovered `*.layout.{jsx,tsx}` entries (includes app `slots` map).
  * @property {object} config                        Inlined `src/config.js` default export.
+ * @property {Record<string, object>} [definitions] Package Definition metadata keyed by slug.
  */
 
 /**
@@ -129,7 +131,11 @@ import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.
  * @param {ManifestPluginOptions} options
  * @returns {import('rollup').Plugin}
  */
-export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configValue, manifestPath }) {
+function entryPackage (entryInfo, appPackageName) {
+  return entryInfo.packageName || appPackageName
+}
+
+export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configValue, appPackageName = '@ossy/app', manifestPath, projectRoot }) {
   return {
     name: 'ossy-manifest',
     async writeBundle (_, bundle) {
@@ -156,8 +162,6 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       const seenStartupIds = new Set()
       const seenEmailIds = new Set()
       const seenActionIds = new Set()
-      /** @type {SlotManifestEntry[]} */
-      const slots = []
       /** @type {E2eManifestEntry[]} */
       const e2es = []
       const seenE2eIds = new Set()
@@ -213,7 +217,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate integration id "${integrationId}"`)
           }
           seenIntegrationIds.add(integrationId)
-          integrations.push({ id: integrationId, entry: url, credentials })
+          integrations.push({ id: integrationId, entry: url, credentials, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -236,7 +240,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate startup id "${startupId}"`)
           }
           seenStartupIds.add(startupId)
-          startups.push({ id: startupId, entry: url })
+          startups.push({ id: startupId, entry: url, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -260,7 +264,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate email id "${emailId}"`)
           }
           seenEmailIds.add(emailId)
-          emails.push({ id: emailId, entry: url })
+          emails.push({ id: emailId, entry: url, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -284,7 +288,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           }
           const access = mod.access ?? 'authenticated'
           seenActionIds.add(actionId)
-          actions.push({ id: actionId, entry: url, access })
+          actions.push({ id: actionId, entry: url, access, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -308,7 +312,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate aggregate id "${aggregateId}"`)
           }
           seenAggregateIds.add(aggregateId)
-          aggregates.push({ id: aggregateId, entry: url })
+          aggregates.push({ id: aggregateId, entry: url, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -341,6 +345,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             feature: typeof feature === 'string' ? feature : '',
             requires: Array.isArray(requires) ? requires : [],
             entry: url,
+            package: entryPackage(entryInfo, appPackageName),
           })
           continue
         }
@@ -366,7 +371,38 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate layout id "${layoutId}"`)
           }
           seenLayoutIds.add(layoutId)
-          layouts.push({ id: layoutId, entry: url })
+          /** @type {Record<string, string> | undefined} */
+          let layoutSlots
+          const rawSlots = mod.slots
+          if (rawSlots != null) {
+            if (typeof rawSlots !== 'object' || Array.isArray(rawSlots)) {
+              this.error(
+                `[@ossy/app][build] layout entry ${entryInfo.sourcePath} must export \`slots\` as a plain object (slot name → component id)`,
+              )
+            }
+            layoutSlots = {}
+            for (const [slotKey, componentId] of Object.entries(rawSlots)) {
+              if (typeof slotKey !== 'string' || typeof componentId !== 'string') {
+                this.error(
+                  `[@ossy/app][build] layout slots in ${entryInfo.sourcePath} must map string slot names to string component ids`,
+                )
+              }
+              const sk = slotKey.trim()
+              const cid = componentId.trim()
+              if (!sk || !cid) {
+                this.error(
+                  `[@ossy/app][build] layout slots in ${entryInfo.sourcePath} must use non-empty slot names and component ids`,
+                )
+              }
+              layoutSlots[sk] = cid
+            }
+          }
+          layouts.push({
+            id: layoutId,
+            entry: url,
+            package: entryPackage(entryInfo, appPackageName),
+            ...(layoutSlots && Object.keys(layoutSlots).length > 0 ? { slots: layoutSlots } : {}),
+          })
           continue
         }
 
@@ -390,7 +426,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate resource template id "${template.id}"`)
           }
           seenResourceIds.add(template.id)
-          resourceTemplates.push(template)
+          resourceTemplates.push({ ...template, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -405,12 +441,13 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
         seenIds[entryInfo.kind].add(id)
 
         if (entryInfo.kind === 'component') {
-          const slotName = typeof mod.slot === 'string' && mod.slot.trim() ? mod.slot.trim() : undefined
-          components.push({ id, entry: url, ...(slotName ? { slot: slotName } : {}) })
-          if (slotName) {
-            const packageName = entryInfo.packageName
-            slots.push({ slot: slotName, entry: url, ...(packageName ? { package: packageName } : {}) })
+          if (mod.slot != null) {
+            this.error(
+              `[@ossy/app][build] component ${entryInfo.sourcePath} must not export \`slot\`. ` +
+              'Assign components to shell slots in `*.layout.jsx` via `export const slots`.',
+            )
           }
+          components.push({ id, entry: url, package: entryPackage(entryInfo, appPackageName) })
           continue
         }
 
@@ -422,6 +459,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             path: pagePath,
             title: rawMeta.title,
             entry: url,
+            package: entryPackage(entryInfo, appPackageName),
           })
         } else if (entryInfo.kind === 'api') {
           // APIs have no sensible default route (unlike pages where we can
@@ -435,9 +473,9 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
               `Add a \`path\` to the metadata or default-export object (e.g. \`path: '/api/${id}'\`).`,
             )
           }
-          entries.push({ type: 'api', id, path: rawMeta.path, entry: url })
+          entries.push({ type: 'api', id, path: rawMeta.path, entry: url, package: entryPackage(entryInfo, appPackageName) })
         } else {
-          entries.push({ type: 'task', id, entry: url })
+          entries.push({ type: 'task', id, entry: url, package: entryPackage(entryInfo, appPackageName) })
         }
       }
 
@@ -449,7 +487,24 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       }
 
       /** @type {Manifest} */
-      const manifest = { entries, components, slots, resourceTemplates, aggregates, integrations, startups, emails, actions, e2es, layouts, config: configValue || {} }
+      const definitions = projectRoot
+        ? await discoverPackageDefinitions(projectRoot)
+        : {}
+
+      const manifest = {
+        entries,
+        components,
+        resourceTemplates,
+        aggregates,
+        integrations,
+        startups,
+        emails,
+        actions,
+        e2es,
+        layouts,
+        definitions,
+        config: configValue || {},
+      }
       fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
       fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
     },