startupjs 0.61.10 → 0.61.12

package/app.js

@@ -0,0 +1,75 @@
+/**
+ * COMPAT-ONLY legacy entrypoint for old LMS code which still imports helpers from
+ * `startupjs/app`.
+ *
+ * Purpose:
+ * - preserve the old import surface while the app is being migrated to the newer
+ *   router/runtime APIs
+ * - reduce mechanical diffs against older codebases which historically depended on
+ *   `startupjs/app`
+ *
+ * Contract in this compat file:
+ * - `pathFor(name, params)` delegates to an application-registered implementation
+ * - `useHistory()` exposes the old imperative navigation shape on top of an
+ *   application-registered `useRouter` implementation
+ *
+ * Explicit limitations:
+ * - this file is internal compat support and is intentionally not part of the
+ *   main documented Startupjs API surface
+ * - it does NOT try to reintroduce the full historic `startupjs/app` package
+ * - only the exports needed by the LMS migration are provided here
+ * - `pathFor` must be initialized by the host app via `__setCompatPathFor()`
+ * - `useHistory` must be initialized by the host app via `__setCompatUseRouter()`
+ * - server-side `@startupjs/app/server` and the old default `App` export are out of
+ *   scope for this package and must be handled separately if needed
+ */
+
+let compatPathFor
+let compatUseRouter
+
+export function __setCompatPathFor (fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('[startupjs/app] __setCompatPathFor expects a function')
+  }
+  compatPathFor = fn
+}
+
+export function __setCompatUseRouter (fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('[startupjs/app] __setCompatUseRouter expects a function')
+  }
+  compatUseRouter = fn
+}
+
+export function __resetCompatPathForForTests () {
+  compatPathFor = undefined
+  compatUseRouter = undefined
+}
+
+export function pathFor (...args) {
+  if (typeof compatPathFor !== 'function') {
+    throw new Error(
+      '[startupjs/app] pathFor is not initialized. ' +
+      'The host app must register a compat implementation via __setCompatPathFor().'
+    )
+  }
+  return compatPathFor(...args)
+}
+
+export function useHistory () {
+  if (typeof compatUseRouter !== 'function') {
+    throw new Error(
+      '[startupjs/app] useHistory is not initialized. ' +
+      'The host app must register a compat useRouter implementation via __setCompatUseRouter().'
+    )
+  }
+  const router = compatUseRouter()
+  return {
+    push: (url, ...args) => router.navigate(url, ...args),
+    replace: (url, ...args) => router.replace(url, ...args),
+    goBack: (...args) => {
+      if (typeof router.back === 'function') return router.back(...args)
+      return router.navigate('..')
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "startupjs",
   "type": "module",
-  "version": "0.61.10",
+  "version": "0.61.12",
   "engines": {
     "node": ">= 14"
   },
@@ -9,6 +9,7 @@
   "main": "index.js",
   "exports": {
     ".": "./index.js",
+    "./app": "./app.js",
     "./auth": "./auth.js",
     "./server": "./server.js",
     "./schema": "./schema.js",
@@ -31,7 +32,7 @@
   "dependencies": {
     "@startupjs/auth": "^0.61.2",
     "@startupjs/bundler": "^0.61.7",
-    "@startupjs/cli": "^0.61.10",
+    "@startupjs/cli": "^0.61.11",
     "@startupjs/hooks": "^0.61.0",
     "@startupjs/isomorphic-helpers": "^0.61.0",
     "@startupjs/registry": "^0.61.0",
@@ -55,5 +56,8 @@
       "optional": true
     }
   },
-  "gitHead": "7d2fe3104f2ebbc6934e269513c40b91c2616b05"
+  "scripts": {
+    "test": "node --experimental-specifier-resolution=node --test"
+  },
+  "gitHead": "39c6a5418b6752b31752981900257b4d84edd68f"
 }

package/test/app.test.js

@@ -0,0 +1,99 @@
+import React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import RouterContext from '@startupjs/utils/RouterContext'
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+  __setCompatPathFor,
+  __setCompatUseRouter,
+  __resetCompatPathForForTests,
+  pathFor,
+  useHistory
+} from '../app.js'
+
+test.afterEach(() => {
+  __resetCompatPathForForTests()
+})
+
+test('pathFor throws a clear error until compat implementation is registered', () => {
+  assert.throws(
+    () => pathFor('admin:users'),
+    /pathFor is not initialized/
+  )
+})
+
+test('pathFor delegates to registered compat implementation', () => {
+  __setCompatPathFor((name, params = {}) => `/route/${name}/${params.id || ''}`)
+  assert.equal(pathFor('admin:tenant', { id: '42' }), '/route/admin:tenant/42')
+})
+
+test('useHistory maps push/replace/goBack to the router contract', () => {
+  const calls = []
+  const router = {
+    navigate: (...args) => calls.push(['navigate', ...args]),
+    replace: (...args) => calls.push(['replace', ...args]),
+    back: (...args) => calls.push(['back', ...args])
+  }
+  __setCompatUseRouter(() => router)
+
+  function Probe () {
+    const history = useHistory()
+    history.push('/one', { a: 1 })
+    history.replace('/two')
+    history.goBack()
+    return React.createElement('div')
+  }
+
+  renderToStaticMarkup(
+    React.createElement(
+      RouterContext.Provider,
+      { value: router },
+      React.createElement(Probe)
+    )
+  )
+
+  assert.deepEqual(calls, [
+    ['navigate', '/one', { a: 1 }],
+    ['replace', '/two'],
+    ['back']
+  ])
+})
+
+test('useHistory falls back to navigate("..") when router.back is missing', () => {
+  const calls = []
+  const router = {
+    navigate: (...args) => calls.push(['navigate', ...args]),
+    replace: (...args) => calls.push(['replace', ...args])
+  }
+  __setCompatUseRouter(() => router)
+
+  function Probe () {
+    const history = useHistory()
+    history.goBack()
+    return React.createElement('div')
+  }
+
+  renderToStaticMarkup(
+    React.createElement(
+      RouterContext.Provider,
+      { value: router },
+      React.createElement(Probe)
+    )
+  )
+
+  assert.deepEqual(calls, [
+    ['navigate', '..']
+  ])
+})
+
+test('useHistory throws a clear error until compat useRouter is registered', () => {
+  function Probe () {
+    useHistory()
+    return React.createElement('div')
+  }
+
+  assert.throws(
+    () => renderToStaticMarkup(React.createElement(Probe)),
+    /useHistory is not initialized/
+  )
+})