@asteby/metacore-runtime-react 52.1.0 → 53.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/addon-loader.d.ts +22 -1
  3. package/dist/addon-loader.d.ts.map +1 -1
  4. package/dist/addon-loader.js +23 -5
  5. package/dist/addon-page-host.d.ts +80 -0
  6. package/dist/addon-page-host.d.ts.map +1 -0
  7. package/dist/addon-page-host.js +216 -0
  8. package/dist/addon-page-loader.d.ts +40 -0
  9. package/dist/addon-page-loader.d.ts.map +1 -0
  10. package/dist/addon-page-loader.js +87 -0
  11. package/dist/dynamic-view.d.ts +20 -1
  12. package/dist/dynamic-view.d.ts.map +1 -1
  13. package/dist/dynamic-view.js +26 -3
  14. package/dist/federated-error-boundary.d.ts +46 -0
  15. package/dist/federated-error-boundary.d.ts.map +1 -0
  16. package/dist/federated-error-boundary.js +55 -0
  17. package/dist/host-api.d.ts +22 -0
  18. package/dist/host-api.d.ts.map +1 -0
  19. package/dist/host-api.js +113 -0
  20. package/dist/index.d.ts +6 -1
  21. package/dist/index.d.ts.map +1 -1
  22. package/dist/index.js +8 -1
  23. package/dist/testing.d.ts +42 -0
  24. package/dist/testing.d.ts.map +1 -0
  25. package/dist/testing.js +53 -0
  26. package/dist/types.d.ts +13 -0
  27. package/dist/types.d.ts.map +1 -1
  28. package/dist/views/calendar-view.d.ts +23 -0
  29. package/dist/views/calendar-view.d.ts.map +1 -0
  30. package/dist/views/calendar-view.js +138 -0
  31. package/dist/views/chart-view.d.ts +14 -0
  32. package/dist/views/chart-view.d.ts.map +1 -0
  33. package/dist/views/chart-view.js +77 -0
  34. package/dist/views/data-source.d.ts +30 -0
  35. package/dist/views/data-source.d.ts.map +1 -0
  36. package/dist/views/data-source.js +103 -0
  37. package/dist/views/index.d.ts +4 -0
  38. package/dist/views/index.d.ts.map +1 -0
  39. package/dist/views/index.js +2 -0
  40. package/dist/views/map-view.d.ts +39 -0
  41. package/dist/views/map-view.d.ts.map +1 -0
  42. package/dist/views/map-view.js +143 -0
  43. package/dist/views/panels.d.ts +13 -0
  44. package/dist/views/panels.d.ts.map +1 -0
  45. package/dist/views/panels.js +119 -0
  46. package/dist/views/registry.d.ts +46 -0
  47. package/dist/views/registry.d.ts.map +1 -0
  48. package/dist/views/registry.js +139 -0
  49. package/dist/views/skeleton.d.ts +5 -0
  50. package/dist/views/skeleton.d.ts.map +1 -0
  51. package/dist/views/skeleton.js +6 -0
  52. package/dist/views/split-view.d.ts +6 -0
  53. package/dist/views/split-view.d.ts.map +1 -0
  54. package/dist/views/split-view.js +52 -0
  55. package/dist/views/timeline-view.d.ts +25 -0
  56. package/dist/views/timeline-view.d.ts.map +1 -0
  57. package/dist/views/timeline-view.js +130 -0
  58. package/dist/views/types.d.ts +87 -0
  59. package/dist/views/types.d.ts.map +1 -0
  60. package/dist/views/types.js +1 -0
  61. package/package.json +16 -4
  62. package/src/__tests__/addon-page-host.test.tsx +122 -0
  63. package/src/__tests__/addon-page-loader.test.tsx +201 -0
  64. package/src/__tests__/declarative-views.test.tsx +351 -0
  65. package/src/__tests__/host-api.test.ts +87 -0
  66. package/src/__tests__/index-static-graph.test.ts +18 -0
  67. package/src/addon-loader.tsx +51 -8
  68. package/src/addon-page-host.tsx +319 -0
  69. package/src/addon-page-loader.tsx +203 -0
  70. package/src/dynamic-view.tsx +61 -3
  71. package/src/federated-error-boundary.tsx +121 -0
  72. package/src/host-api.ts +143 -0
  73. package/src/index.ts +38 -0
  74. package/src/testing.tsx +108 -0
  75. package/src/types.ts +13 -0
  76. package/src/views/calendar-view.tsx +234 -0
  77. package/src/views/chart-view.tsx +122 -0
  78. package/src/views/data-source.ts +127 -0
  79. package/src/views/index.ts +37 -0
  80. package/src/views/map-view.tsx +217 -0
  81. package/src/views/panels.tsx +177 -0
  82. package/src/views/registry.tsx +202 -0
  83. package/src/views/skeleton.tsx +13 -0
  84. package/src/views/split-view.tsx +115 -0
  85. package/src/views/timeline-view.tsx +229 -0
  86. package/src/views/types.ts +105 -0
@@ -0,0 +1,319 @@
1
+ // AddonPageHost — what the host mounts around a federated page (embedded or
2
+ // full screen) so the remote can use host services without importing host
3
+ // code and without ever touching credentials.
4
+ //
5
+ // Host side (ops FederatedPageHost, starter-core):
6
+ //
7
+ // const chrome = useMemo(createPageChromeStore, [])
8
+ // <AddonPageHost
9
+ // host={hostContext} // org, user, branch, locale…
10
+ // api={hostApi} // createHostApi(axios)
11
+ // basePath="/a/shipping/control-tower"
12
+ // location={{ pathname, search }} // from the host router
13
+ // navigate={(to, o) => router.navigate({ to, replace: o?.replace })}
14
+ // chrome={chrome} // header reads it
15
+ // >
16
+ // <Page … />
17
+ // </AddonPageHost>
18
+ //
19
+ // // header: const { title, actions, focus, breadcrumbs } = usePageChromeState(chrome)
20
+ //
21
+ // Remote side (inside the page):
22
+ //
23
+ // const api = useHostApi()
24
+ // const { org, user, locale } = useHostContext()
25
+ // const navigate = useAddonNavigate() // relative to basePath
26
+ // const [params, setParams] = useAddonSearchParams()
27
+ // useBreadcrumbs([{ title: t('shipping.nav.group'), url: '/m/Shipment' }])
28
+ // usePageChrome({ title: t('shipping.pages.control_tower'), focus: true })
29
+ import {
30
+ createContext,
31
+ useCallback,
32
+ useContext,
33
+ useEffect,
34
+ useMemo,
35
+ useRef,
36
+ useSyncExternalStore,
37
+ type ReactNode,
38
+ } from 'react'
39
+ import type {
40
+ AddonHostContext,
41
+ Breadcrumb,
42
+ HostApi,
43
+ PageChrome,
44
+ } from '@asteby/metacore-sdk'
45
+
46
+ // ---------------------------------------------------------------------------
47
+ // Chrome store: page → host header. A tiny external store so the header (above
48
+ // the page in the tree) re-renders without a provider re-render cascade.
49
+ // ---------------------------------------------------------------------------
50
+
51
+ export interface PageChromeState extends PageChrome {
52
+ breadcrumbs: Breadcrumb[]
53
+ }
54
+
55
+ export interface PageChromeStore {
56
+ get(): PageChromeState
57
+ subscribe(listener: () => void): () => void
58
+ /** Merge a partial update (page side). */
59
+ set(patch: Partial<PageChromeState>): void
60
+ /** Back to empty (page unmounted). */
61
+ reset(): void
62
+ }
63
+
64
+ const EMPTY_CHROME: PageChromeState = Object.freeze({ breadcrumbs: [] }) as PageChromeState
65
+
66
+ export function createPageChromeStore(initial?: Partial<PageChromeState>): PageChromeStore {
67
+ let state: PageChromeState = { ...EMPTY_CHROME, ...initial }
68
+ const listeners = new Set<() => void>()
69
+ const emit = () => listeners.forEach((l) => l())
70
+ return {
71
+ get: () => state,
72
+ subscribe(listener) {
73
+ listeners.add(listener)
74
+ return () => listeners.delete(listener)
75
+ },
76
+ set(patch) {
77
+ state = { ...state, ...patch }
78
+ emit()
79
+ },
80
+ reset() {
81
+ state = { ...EMPTY_CHROME, ...initial }
82
+ emit()
83
+ },
84
+ }
85
+ }
86
+
87
+ /** Host side: subscribe the header to what the page declared. */
88
+ export function usePageChromeState(store: PageChromeStore): PageChromeState {
89
+ return useSyncExternalStore(store.subscribe, store.get, store.get)
90
+ }
91
+
92
+ // ---------------------------------------------------------------------------
93
+ // Context
94
+ // ---------------------------------------------------------------------------
95
+
96
+ export interface AddonNavigateOptions {
97
+ replace?: boolean
98
+ }
99
+
100
+ /** Location of the host router, as plain strings (router-agnostic). */
101
+ export interface AddonPageLocation {
102
+ pathname: string
103
+ search: string
104
+ }
105
+
106
+ export interface AddonPageHostValue {
107
+ host: AddonHostContext
108
+ api: HostApi
109
+ basePath: string
110
+ location: AddonPageLocation
111
+ navigate: (to: string, opts?: AddonNavigateOptions) => void
112
+ chrome?: PageChromeStore
113
+ }
114
+
115
+ const AddonPageHostContext = createContext<AddonPageHostValue | null>(null)
116
+
117
+ export interface AddonPageHostProps extends Omit<AddonPageHostValue, 'basePath'> {
118
+ basePath: string
119
+ children: ReactNode
120
+ }
121
+
122
+ export function AddonPageHost({
123
+ host,
124
+ api,
125
+ basePath,
126
+ location,
127
+ navigate,
128
+ chrome,
129
+ children,
130
+ }: AddonPageHostProps) {
131
+ const base = normalizeBase(basePath)
132
+ const value = useMemo<AddonPageHostValue>(
133
+ () => ({ host, api, basePath: base, location, navigate, chrome }),
134
+ [host, api, base, location, navigate, chrome],
135
+ )
136
+ // The chrome belongs to the page: clear it when the page goes away so the
137
+ // next screen does not inherit a stale title or header buttons.
138
+ useEffect(() => () => chrome?.reset(), [chrome])
139
+ return <AddonPageHostContext.Provider value={value}>{children}</AddonPageHostContext.Provider>
140
+ }
141
+
142
+ function usePageHost(hook: string): AddonPageHostValue {
143
+ const ctx = useContext(AddonPageHostContext)
144
+ if (!ctx) {
145
+ throw new Error(
146
+ `${hook}() must run inside <AddonPageHost>. Hosts mount it around every federated page; ` +
147
+ 'in tests use renderWithHost() from @asteby/metacore-runtime-react/testing.',
148
+ )
149
+ }
150
+ return ctx
151
+ }
152
+
153
+ /** True when rendered inside a host page (lets shared components degrade). */
154
+ export function useIsInAddonPage(): boolean {
155
+ return useContext(AddonPageHostContext) !== null
156
+ }
157
+
158
+ // ---------------------------------------------------------------------------
159
+ // Remote-facing hooks
160
+ // ---------------------------------------------------------------------------
161
+
162
+ /** Org, user, branch, locale, installed addons and realtime of the host. */
163
+ export function useHostContext(): AddonHostContext {
164
+ return usePageHost('useHostContext').host
165
+ }
166
+
167
+ /** Authenticated API client provided by the host (never exposes the token). */
168
+ export function useHostApi(): HostApi {
169
+ return usePageHost('useHostApi').api
170
+ }
171
+
172
+ function normalizeBase(base: string): string {
173
+ const b = `/${base.replace(/^\/+|\/+$/g, '')}`
174
+ return b === '/' ? '' : b
175
+ }
176
+
177
+ /**
178
+ * Resolve `to` inside the page. Plain paths are base-relative:
179
+ * `"shipments/42"` and `"/shipments/42"` both land on `<base>/shipments/42`.
180
+ * `"./x"` and `"../x"` resolve against the current sub-path (like URLs), and
181
+ * `".."` never climbs above the base. `""` / `"?q=1"` keep the current path.
182
+ * A `?query` / `#hash` is kept.
183
+ */
184
+ export function resolveAddonPath(basePath: string, currentSubpath: string, to: string): string {
185
+ const base = normalizeBase(basePath)
186
+ const m = /^([^?#]*)(.*)$/.exec(to)
187
+ const pathPart = m ? m[1] : to
188
+ const suffix = m ? m[2] : ''
189
+ const current = currentSubpath.split('/').filter(Boolean)
190
+ let segs: string[]
191
+ if (pathPart === '') {
192
+ segs = current
193
+ } else if (pathPart.startsWith('./') || pathPart.startsWith('../') || pathPart === '.' || pathPart === '..') {
194
+ // Relative to the current "directory" (drop the last segment, like URLs).
195
+ segs = current.slice(0, -1)
196
+ } else {
197
+ segs = []
198
+ }
199
+ for (const seg of pathPart.split('/')) {
200
+ if (!seg || seg === '.') continue
201
+ if (seg === '..') segs.pop()
202
+ else segs.push(seg)
203
+ }
204
+ const rest = segs.join('/')
205
+ return `${base}${rest ? `/${rest}` : ''}${suffix}` || '/'
206
+ }
207
+
208
+ /** Path below the page base (`"shipments/42"`), from the host location. */
209
+ export function addonSubpath(basePath: string, pathname: string): string {
210
+ const base = normalizeBase(basePath)
211
+ if (base && (pathname === base || pathname.startsWith(`${base}/`))) {
212
+ return pathname.slice(base.length).replace(/^\/+/, '')
213
+ }
214
+ return ''
215
+ }
216
+
217
+ /**
218
+ * Navigate inside the page. The host router does the work (no
219
+ * `window.location`), so history, guards and the shell stay intact.
220
+ * `navigate(-1)` goes back.
221
+ */
222
+ export function useAddonNavigate(): (to: string | number, opts?: AddonNavigateOptions) => void {
223
+ const { basePath, location, navigate } = usePageHost('useAddonNavigate')
224
+ const sub = addonSubpath(basePath, location.pathname)
225
+ return useCallback(
226
+ (to: string | number, opts?: AddonNavigateOptions) => {
227
+ if (typeof to === 'number') {
228
+ if (typeof window !== 'undefined') window.history.go(to)
229
+ return
230
+ }
231
+ navigate(resolveAddonPath(basePath, sub, to), opts)
232
+ },
233
+ [basePath, sub, navigate],
234
+ )
235
+ }
236
+
237
+ /** Location relative to the page: `{ path: "shipments/42", search: "?x=1" }`. */
238
+ export function useAddonLocation(): { path: string; search: string } {
239
+ const { basePath, location } = usePageHost('useAddonLocation')
240
+ return useMemo(
241
+ () => ({ path: addonSubpath(basePath, location.pathname), search: location.search }),
242
+ [basePath, location.pathname, location.search],
243
+ )
244
+ }
245
+
246
+ /** Search params of the page URL, with a setter that goes through the host router. */
247
+ export function useAddonSearchParams(): [
248
+ URLSearchParams,
249
+ (next: URLSearchParams | Record<string, string>, opts?: AddonNavigateOptions) => void,
250
+ ] {
251
+ const { basePath, location, navigate } = usePageHost('useAddonSearchParams')
252
+ const params = useMemo(() => new URLSearchParams(location.search), [location.search])
253
+ const set = useCallback(
254
+ (next: URLSearchParams | Record<string, string>, opts?: AddonNavigateOptions) => {
255
+ const qs = (next instanceof URLSearchParams ? next : new URLSearchParams(next)).toString()
256
+ const sub = addonSubpath(basePath, location.pathname)
257
+ navigate(`${normalizeBase(basePath)}${sub ? `/${sub}` : ''}${qs ? `?${qs}` : ''}`, {
258
+ replace: opts?.replace ?? true,
259
+ })
260
+ },
261
+ [basePath, location.pathname, navigate],
262
+ )
263
+ return [params, set]
264
+ }
265
+
266
+ function sameCrumbs(a: Breadcrumb[], b: Breadcrumb[]): boolean {
267
+ return a.length === b.length && a.every((c, i) => c.title === b[i].title && c.url === b[i].url)
268
+ }
269
+
270
+ /**
271
+ * Declare the page's breadcrumbs (shown by the host header before the page
272
+ * title). Cleared on unmount. No-op on hosts without a chrome store.
273
+ */
274
+ export function useBreadcrumbs(crumbs: Breadcrumb[]): void {
275
+ const { chrome } = usePageHost('useBreadcrumbs')
276
+ const last = useRef<Breadcrumb[] | null>(null)
277
+ useEffect(() => {
278
+ if (!chrome) return
279
+ if (last.current && sameCrumbs(last.current, crumbs)) return
280
+ last.current = crumbs
281
+ chrome.set({ breadcrumbs: crumbs })
282
+ })
283
+ useEffect(
284
+ () => () => {
285
+ last.current = null
286
+ chrome?.set({ breadcrumbs: [] })
287
+ },
288
+ [chrome],
289
+ )
290
+ }
291
+
292
+ /**
293
+ * Declare title, subtitle, header actions and focus mode. Values update on
294
+ * every render that changes them; everything is cleared on unmount.
295
+ */
296
+ export function usePageChrome(chrome: PageChrome): void {
297
+ const { chrome: store } = usePageHost('usePageChrome')
298
+ const { title, subtitle, actions, focus } = chrome
299
+ // Action handlers are usually inline closures: keep the latest in a ref so
300
+ // the store only changes when what the header SHOWS changes.
301
+ const handlers = useRef(new Map<string, () => void>())
302
+ handlers.current = new Map((actions ?? []).map((a) => [a.key, a.onSelect]))
303
+ const actionsSig = JSON.stringify(
304
+ (actions ?? []).map(({ onSelect: _onSelect, ...rest }) => rest),
305
+ )
306
+ useEffect(() => {
307
+ if (!store) return
308
+ const stable = (actions ?? []).map((a) => ({
309
+ ...a,
310
+ onSelect: () => handlers.current.get(a.key)?.(),
311
+ }))
312
+ store.set({ title, subtitle, actions: stable, focus })
313
+ // eslint-disable-next-line react-hooks/exhaustive-deps
314
+ }, [store, title, subtitle, actionsSig, focus])
315
+ useEffect(
316
+ () => () => store?.set({ title: undefined, subtitle: undefined, actions: undefined, focus: undefined }),
317
+ [store],
318
+ )
319
+ }
@@ -0,0 +1,203 @@
1
+ // AddonPageLoader — mounts one `frontend.pages[]` entry of a federated remote.
2
+ //
3
+ // The host has already decided WHERE (embedded `/a/…` or full screen
4
+ // `/addons/…`) and WHETHER (permission) from the manifest; this component
5
+ // downloads the page's expose, verifies the remote entry (SRI), and renders
6
+ // the page inside:
7
+ // FederatedErrorBoundary → a crashing page never takes the shell down
8
+ // AddonPageHost → useHostApi / useHostContext / useAddonNavigate…
9
+ // a sized container → `contain: layout paint` + `isolation: isolate`
10
+ // so the page cannot paint over the host chrome
11
+ //
12
+ // Load failures (network, 404 expose, integrity) are not render errors: they
13
+ // show `errorFallback` (default: the boundary's card) with a retry that
14
+ // re-runs the load. `timeoutMs` turns a hung remote into that same error.
15
+ import { useEffect, useState, type ComponentType, type ReactNode } from 'react'
16
+ import {
17
+ resolvePageModule,
18
+ type AddonHostContext,
19
+ type AddonPageProps,
20
+ type FrontendPage,
21
+ type HostApi,
22
+ } from '@asteby/metacore-sdk'
23
+ import { loadFederatedModule } from './addon-loader'
24
+ import { AddonPageHost, addonSubpath, type AddonPageHostProps, type PageChromeStore } from './addon-page-host'
25
+ import {
26
+ FederatedErrorBoundary,
27
+ type FederatedErrorBoundaryProps,
28
+ type FederatedErrorInfo,
29
+ } from './federated-error-boundary'
30
+
31
+ export interface AddonPageLoaderProps {
32
+ /** Federation container name (`metacore_shipping`). */
33
+ scope: string
34
+ /** remoteEntry.js URL (may carry the `?v=` cache-bust). */
35
+ url: string
36
+ /** `manifest.frontend.integrity`. */
37
+ integrity?: string
38
+ /** Addon key (incidents, data attributes). */
39
+ addonKey: string
40
+ /** The manifest page being mounted. */
41
+ page: FrontendPage
42
+ /** Absolute mount path (`pageMountPath(addonKey, page, frontend.layout)`). */
43
+ basePath: string
44
+ host: AddonHostContext
45
+ api: HostApi
46
+ location: AddonPageHostProps['location']
47
+ navigate: AddonPageHostProps['navigate']
48
+ chrome?: PageChromeStore
49
+ /** Extra route params the host router extracted. */
50
+ params?: Record<string, string>
51
+ /** Shown while the remote downloads (default: page skeleton). */
52
+ fallback?: ReactNode
53
+ /** Abort the load after this many ms (default 10 000; 0 disables). */
54
+ timeoutMs?: number
55
+ /** Load failure or render crash, for telemetry (reportFrontendIncident). */
56
+ onError?: (error: Error, info: FederatedErrorInfo & { phase: 'load' | 'render' }) => void
57
+ /** Override the error UI (load and render). */
58
+ errorFallback?: FederatedErrorBoundaryProps['fallback']
59
+ errorStrings?: FederatedErrorBoundaryProps['strings']
60
+ }
61
+
62
+ type LoadState =
63
+ | { status: 'loading' }
64
+ | { status: 'ready'; Page: ComponentType<AddonPageProps> }
65
+ | { status: 'error'; error: Error }
66
+
67
+ /** Page-sized skeleton: header line + content block, fixed heights (no layout shift). */
68
+ export function AddonPageSkeleton() {
69
+ return (
70
+ <div aria-busy="true" data-testid="addon-page-skeleton" className="flex flex-col gap-4 p-4">
71
+ <div className="h-7 w-56 animate-pulse rounded-md bg-muted" />
72
+ <div className="h-[60vh] w-full animate-pulse rounded-lg bg-muted/70" />
73
+ </div>
74
+ )
75
+ }
76
+
77
+ function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
78
+ if (!ms) return p
79
+ return new Promise<T>((resolve, reject) => {
80
+ const t = setTimeout(() => reject(new Error(`metacore: ${what} did not load within ${ms} ms`)), ms)
81
+ p.then(
82
+ (v) => {
83
+ clearTimeout(t)
84
+ resolve(v)
85
+ },
86
+ (e) => {
87
+ clearTimeout(t)
88
+ reject(e)
89
+ },
90
+ )
91
+ })
92
+ }
93
+
94
+ export function AddonPageLoader({
95
+ scope,
96
+ url,
97
+ integrity,
98
+ addonKey,
99
+ page,
100
+ basePath,
101
+ host,
102
+ api,
103
+ location,
104
+ navigate,
105
+ chrome,
106
+ params,
107
+ fallback,
108
+ timeoutMs = 10_000,
109
+ onError,
110
+ errorFallback,
111
+ errorStrings,
112
+ }: AddonPageLoaderProps) {
113
+ const [state, setState] = useState<LoadState>({ status: 'loading' })
114
+ const [attempt, setAttempt] = useState(0)
115
+
116
+ useEffect(() => {
117
+ let cancelled = false
118
+ setState({ status: 'loading' })
119
+ withTimeout(
120
+ loadFederatedModule(scope, url, page.expose, integrity),
121
+ timeoutMs,
122
+ `page "${page.expose}" of ${addonKey}`,
123
+ )
124
+ .then((mod) => {
125
+ if (cancelled) return
126
+ setState({ status: 'ready', Page: resolvePageModule(mod, page.expose) })
127
+ })
128
+ .catch((e: unknown) => {
129
+ if (cancelled) return
130
+ const error = e instanceof Error ? e : new Error(String(e))
131
+ setState({ status: 'error', error })
132
+ onError?.(error, { addonKey, expose: page.expose, phase: 'load' })
133
+ })
134
+ return () => {
135
+ cancelled = true
136
+ }
137
+ // onError identity is not part of the fiber identity.
138
+ // eslint-disable-next-line react-hooks/exhaustive-deps
139
+ }, [scope, url, page.expose, integrity, addonKey, timeoutMs, attempt])
140
+
141
+ const retry = () => {
142
+ setState({ status: 'loading' })
143
+ setAttempt((n) => n + 1)
144
+ }
145
+ const subpath = addonSubpath(basePath, location.pathname)
146
+
147
+ let body: ReactNode
148
+ if (state.status === 'loading') {
149
+ body = fallback ?? <AddonPageSkeleton />
150
+ } else if (state.status === 'error') {
151
+ // Reuse the boundary's UI for load failures so both look the same.
152
+ body = (
153
+ <FederatedErrorBoundary
154
+ addonKey={addonKey}
155
+ expose={page.expose}
156
+ fallback={errorFallback}
157
+ strings={errorStrings}
158
+ onReset={retry}
159
+ >
160
+ <ThrowError error={state.error} />
161
+ </FederatedErrorBoundary>
162
+ )
163
+ } else {
164
+ const { Page } = state
165
+ body = (
166
+ <FederatedErrorBoundary
167
+ addonKey={addonKey}
168
+ expose={page.expose}
169
+ resetKeys={[url, page.expose]}
170
+ fallback={errorFallback}
171
+ strings={errorStrings}
172
+ onError={(error, info) => onError?.(error, { ...info, phase: 'render' })}
173
+ >
174
+ <Page host={host} basePath={basePath} params={{ ...params, '*': subpath }} page={page} />
175
+ </FederatedErrorBoundary>
176
+ )
177
+ }
178
+
179
+ return (
180
+ <div
181
+ data-addon-page={`${addonKey}:${page.key}`}
182
+ className="relative min-h-0 w-full"
183
+ style={{ contain: 'layout paint', isolation: 'isolate' }}
184
+ >
185
+ <AddonPageHost
186
+ host={host}
187
+ api={api}
188
+ basePath={basePath}
189
+ location={location}
190
+ navigate={navigate}
191
+ chrome={chrome}
192
+ >
193
+ {body}
194
+ </AddonPageHost>
195
+ </div>
196
+ )
197
+ }
198
+
199
+ // Throws the load error during render so the boundary paints it; the
200
+ // boundary's retry (onReset) re-runs the load, not only the render.
201
+ function ThrowError({ error }: { error: Error }): null {
202
+ throw error
203
+ }
@@ -13,12 +13,15 @@
13
13
  // Both child components fetch their own metadata (cache-backed), so the extra
14
14
  // read this wrapper does to learn `view_type` is served from the same cache —
15
15
  // no duplicate network round-trip in practice.
16
- import { useEffect, useState } from 'react'
16
+ import { useEffect, useMemo, useState } from 'react'
17
17
  import { useApi } from './api-context'
18
18
  import { useMetadataCache } from './metadata-cache'
19
19
  import { DynamicTable, type DynamicTableProps } from './dynamic-table'
20
20
  import { DynamicKanban, type DynamicKanbanProps } from './dynamic-kanban'
21
21
  import type { TableMetadata, ApiResponse } from './types'
22
+ import { DeclarativeView, isDeclarativeViewType } from './views/registry'
23
+ import { createApiViewDataSource } from './views/data-source'
24
+ import type { ViewDataSource } from './views/types'
22
25
 
23
26
  /**
24
27
  * Pure routing decision: which renderer a `view_type` maps onto. Exported so a
@@ -30,6 +33,23 @@ export function resolveViewRenderer(
30
33
  return viewType === 'kanban' ? 'kanban' : 'table'
31
34
  }
32
35
 
36
+ /**
37
+ * Full routing decision including the declarative views: `'declarative'`
38
+ * when the type is map/timeline/calendar/chart/split AND the metadata carries
39
+ * its `view` block; otherwise the same table/kanban rule as
40
+ * {@link resolveViewRenderer} (a host that does not serve `view` keeps the
41
+ * table, exactly like before).
42
+ */
43
+ export function resolveViewKind(
44
+ viewType: string | undefined,
45
+ meta: Pick<TableMetadata, 'view'> | null | undefined,
46
+ ): 'declarative' | 'kanban' | 'table' {
47
+ if (isDeclarativeViewType(viewType) && meta?.view && (meta.view as Record<string, unknown>)[viewType]) {
48
+ return 'declarative'
49
+ }
50
+ return resolveViewRenderer(viewType)
51
+ }
52
+
33
53
  /**
34
54
  * Reads the `view` selector out of a URL search string (`?view=kanban`, a bare
35
55
  * `view=kanban`, or a full href). Returns `undefined` when absent. The query is
@@ -76,14 +96,32 @@ export interface DynamicViewProps extends DynamicTableProps {
76
96
  * kanban-only extras (e.g. `onCardClick`, `pageSize`).
77
97
  */
78
98
  kanbanProps?: Partial<Omit<DynamicKanbanProps, 'model' | 'endpoint'>>
99
+ /**
100
+ * Data source for declarative views (map/timeline/calendar/chart/split).
101
+ * Default: {@link createApiViewDataSource} over the injected ApiClient.
102
+ */
103
+ viewDataSource?: ViewDataSource
104
+ /** Open a record from a declarative view (host detail route or drawer). */
105
+ onOpenRecord?: (row: Record<string, unknown>) => void
106
+ /** BCP-47 locale for declarative views. */
107
+ locale?: string
79
108
  }
80
109
 
81
- export function DynamicView({ view, kanbanProps, ...tableProps }: DynamicViewProps) {
110
+ export function DynamicView({
111
+ view,
112
+ kanbanProps,
113
+ viewDataSource,
114
+ onOpenRecord,
115
+ locale,
116
+ ...tableProps
117
+ }: DynamicViewProps) {
82
118
  const { model, endpoint, refreshTrigger, timeZone, currency } = tableProps
83
119
  const api = useApi()
84
120
  const cached = useMetadataCache((s) => s.getMetadata(model))
85
121
  const setMeta = useMetadataCache((s) => s.setMetadata)
86
122
  const [viewType, setViewType] = useState<string | undefined>(cached?.view_type)
123
+ const [meta, setMetaState] = useState<TableMetadata | null>(cached ?? null)
124
+ const dataSource = useMemo(() => viewDataSource ?? createApiViewDataSource(api), [viewDataSource, api])
87
125
  const [resolved, setResolved] = useState<boolean>(!!cached)
88
126
 
89
127
  useEffect(() => {
@@ -91,6 +129,7 @@ export function DynamicView({ view, kanbanProps, ...tableProps }: DynamicViewPro
91
129
  const c = useMetadataCache.getState().getMetadata(model)
92
130
  if (c) {
93
131
  setViewType(c.view_type)
132
+ setMetaState(c)
94
133
  setResolved(true)
95
134
  }
96
135
  api
@@ -101,6 +140,7 @@ export function DynamicView({ view, kanbanProps, ...tableProps }: DynamicViewPro
101
140
  const meta = body?.success ? body.data : (res.data as TableMetadata)
102
141
  if (meta) {
103
142
  setViewType(meta.view_type)
143
+ setMetaState(meta)
104
144
  setMeta(model, meta)
105
145
  }
106
146
  })
@@ -129,7 +169,25 @@ export function DynamicView({ view, kanbanProps, ...tableProps }: DynamicViewPro
129
169
  if (!resolved && !cached && view === undefined && !readViewFromSearch(search))
130
170
  return null
131
171
 
132
- if (resolveViewRenderer(effectiveView) === 'kanban') {
172
+ const kind = resolveViewKind(effectiveView, meta)
173
+ if (kind === 'declarative' && effectiveView) {
174
+ return (
175
+ <DeclarativeView
176
+ viewType={effectiveView}
177
+ view={meta?.view}
178
+ model={model}
179
+ metadata={meta}
180
+ data={dataSource}
181
+ onOpenRecord={onOpenRecord}
182
+ locale={locale}
183
+ currency={currency}
184
+ timeZone={timeZone}
185
+ fallback={<DynamicTable {...tableProps} />}
186
+ />
187
+ )
188
+ }
189
+
190
+ if (kind === 'kanban') {
133
191
  return (
134
192
  <DynamicKanban
135
193
  model={model}