@asteby/metacore-runtime-react 52.0.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 (101) hide show
  1. package/CHANGELOG.md +26 -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 +8 -2
  21. package/dist/index.d.ts.map +1 -1
  22. package/dist/index.js +12 -2
  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/dist/widgets/charts.d.ts +9 -0
  62. package/dist/widgets/charts.d.ts.map +1 -0
  63. package/dist/widgets/charts.js +55 -0
  64. package/dist/widgets/lazy-charts.d.ts +10 -0
  65. package/dist/widgets/lazy-charts.d.ts.map +1 -0
  66. package/dist/widgets/lazy-charts.js +30 -0
  67. package/dist/widgets/renderers.d.ts +5 -5
  68. package/dist/widgets/renderers.d.ts.map +1 -1
  69. package/dist/widgets/renderers.js +3 -53
  70. package/dist/widgets/widget-renderer.d.ts.map +1 -1
  71. package/dist/widgets/widget-renderer.js +2 -1
  72. package/package.json +21 -5
  73. package/src/__tests__/addon-page-host.test.tsx +122 -0
  74. package/src/__tests__/addon-page-loader.test.tsx +201 -0
  75. package/src/__tests__/declarative-views.test.tsx +351 -0
  76. package/src/__tests__/host-api.test.ts +87 -0
  77. package/src/__tests__/index-static-graph.test.ts +83 -0
  78. package/src/addon-loader.tsx +51 -8
  79. package/src/addon-page-host.tsx +319 -0
  80. package/src/addon-page-loader.tsx +203 -0
  81. package/src/dynamic-view.tsx +61 -3
  82. package/src/federated-error-boundary.tsx +121 -0
  83. package/src/host-api.ts +143 -0
  84. package/src/index.ts +47 -4
  85. package/src/testing.tsx +108 -0
  86. package/src/types.ts +13 -0
  87. package/src/views/calendar-view.tsx +234 -0
  88. package/src/views/chart-view.tsx +122 -0
  89. package/src/views/data-source.ts +127 -0
  90. package/src/views/index.ts +37 -0
  91. package/src/views/map-view.tsx +217 -0
  92. package/src/views/panels.tsx +177 -0
  93. package/src/views/registry.tsx +202 -0
  94. package/src/views/skeleton.tsx +13 -0
  95. package/src/views/split-view.tsx +115 -0
  96. package/src/views/timeline-view.tsx +229 -0
  97. package/src/views/types.ts +105 -0
  98. package/src/widgets/charts.tsx +225 -0
  99. package/src/widgets/lazy-charts.tsx +51 -0
  100. package/src/widgets/renderers.tsx +5 -210
  101. package/src/widgets/widget-renderer.tsx +6 -4
@@ -0,0 +1,122 @@
1
+ // @vitest-environment happy-dom
2
+ import { afterEach, describe, expect, it, vi } from 'vitest'
3
+ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
4
+ import {
5
+ addonSubpath,
6
+ createPageChromeStore,
7
+ resolveAddonPath,
8
+ useAddonLocation,
9
+ useAddonNavigate,
10
+ useAddonSearchParams,
11
+ useBreadcrumbs,
12
+ useHostApi,
13
+ useHostContext,
14
+ usePageChrome,
15
+ } from '../addon-page-host'
16
+ import { createMockHostApi, renderWithHost } from '../testing'
17
+
18
+ afterEach(cleanup)
19
+
20
+ describe('resolveAddonPath', () => {
21
+ const base = '/a/shipping/control-tower'
22
+ it('plain paths are base-relative and cannot escape the base', () => {
23
+ expect(resolveAddonPath(base, 'shipments/1', 'shipments/42')).toBe(`${base}/shipments/42`)
24
+ expect(resolveAddonPath(base, 'x', '/shipments/42')).toBe(`${base}/shipments/42`)
25
+ expect(resolveAddonPath(base, 'x', '../../../admin')).toBe(`${base}/admin`)
26
+ })
27
+ it('./ and ../ resolve against the current sub-path', () => {
28
+ expect(resolveAddonPath(base, 'shipments/1', './2')).toBe(`${base}/shipments/2`)
29
+ expect(resolveAddonPath(base, 'shipments/1/events', '../edit')).toBe(`${base}/shipments/edit`)
30
+ })
31
+ it('keeps query/hash and the current path for "?…"', () => {
32
+ expect(resolveAddonPath(base, 'shipments', '?carrier=dhl')).toBe(`${base}/shipments?carrier=dhl`)
33
+ expect(resolveAddonPath(base, '', '')).toBe(base)
34
+ expect(resolveAddonPath('/', '', 'x')).toBe('/x')
35
+ })
36
+ it('addonSubpath strips the base', () => {
37
+ expect(addonSubpath(base, `${base}/shipments/42`)).toBe('shipments/42')
38
+ expect(addonSubpath(base, base)).toBe('')
39
+ expect(addonSubpath(base, '/other')).toBe('')
40
+ })
41
+ })
42
+
43
+ function Probe() {
44
+ const api = useHostApi()
45
+ const ctx = useHostContext()
46
+ const navigate = useAddonNavigate()
47
+ const loc = useAddonLocation()
48
+ const [params, setParams] = useAddonSearchParams()
49
+ useBreadcrumbs([{ title: 'Envíos', url: '/m/Shipment' }])
50
+ usePageChrome({
51
+ title: 'Torre de envíos',
52
+ focus: true,
53
+ actions: [{ key: 'refresh', label: 'Actualizar', onSelect: () => navigate('?refreshed=1') }],
54
+ })
55
+ return (
56
+ <div>
57
+ <span data-testid="org">{ctx.org?.name}</span>
58
+ <span data-testid="path">{loc.path}</span>
59
+ <span data-testid="carrier">{params.get('carrier')}</span>
60
+ <span data-testid="has-get">{typeof api.get}</span>
61
+ <button onClick={() => navigate('shipments/42')}>go</button>
62
+ <button onClick={() => setParams({ carrier: 'fedex' })}>filter</button>
63
+ </div>
64
+ )
65
+ }
66
+
67
+ describe('AddonPageHost hooks', () => {
68
+ it('expose host context, location and navigation through the host router', () => {
69
+ const r = renderWithHost(<Probe />, {
70
+ basePath: '/a/shipping/control-tower',
71
+ pathname: '/a/shipping/control-tower/shipments',
72
+ search: '?carrier=dhl',
73
+ })
74
+ expect(screen.getByTestId('org').textContent).toBe('Org de prueba')
75
+ expect(screen.getByTestId('path').textContent).toBe('shipments')
76
+ expect(screen.getByTestId('carrier').textContent).toBe('dhl')
77
+ expect(screen.getByTestId('has-get').textContent).toBe('function')
78
+ fireEvent.click(screen.getByText('go'))
79
+ fireEvent.click(screen.getByText('filter'))
80
+ expect(r.navigate.calls).toEqual([
81
+ ['/a/shipping/control-tower/shipments/42', undefined],
82
+ ['/a/shipping/control-tower/shipments?carrier=fedex', { replace: true }],
83
+ ])
84
+ })
85
+
86
+ it('publishes chrome and breadcrumbs, with stable action handlers, and clears them on unmount', () => {
87
+ const r = renderWithHost(<Probe />)
88
+ const state = r.chrome.get()
89
+ expect(state.title).toBe('Torre de envíos')
90
+ expect(state.focus).toBe(true)
91
+ expect(state.breadcrumbs).toEqual([{ title: 'Envíos', url: '/m/Shipment' }])
92
+ act(() => state.actions![0].onSelect())
93
+ expect(r.navigate.calls.at(-1)?.[0]).toBe('/a/test/page?refreshed=1')
94
+ r.unmount()
95
+ expect(r.chrome.get().title).toBeUndefined()
96
+ expect(r.chrome.get().breadcrumbs).toEqual([])
97
+ })
98
+
99
+ it('hooks fail loudly outside a host', () => {
100
+ const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
101
+ expect(() => render(<Probe />)).toThrow(/inside <AddonPageHost>/)
102
+ spy.mockRestore()
103
+ })
104
+
105
+ it('mock host api records calls and 404s unknown routes', async () => {
106
+ const api = createMockHostApi({ get: { '/data/Shipment': { success: true, data: [] } } })
107
+ await expect(api.get('/data/Shipment?f_x=1')).resolves.toEqual({ success: true, data: [] })
108
+ await expect(api.get('/nope')).rejects.toMatchObject({ status: 404 })
109
+ expect(api.calls[0]).toEqual(['get', '/data/Shipment?f_x=1', undefined])
110
+ })
111
+
112
+ it('chrome store notifies subscribers', () => {
113
+ const store = createPageChromeStore()
114
+ let n = 0
115
+ const off = store.subscribe(() => n++)
116
+ store.set({ title: 'x' })
117
+ off()
118
+ store.set({ title: 'y' })
119
+ expect(n).toBe(1)
120
+ })
121
+ })
122
+
@@ -0,0 +1,201 @@
1
+ // @vitest-environment happy-dom
2
+ //
3
+ // AddonPageLoader + FederatedErrorBoundary: the page's expose is loaded through
4
+ // the MF runtime (mocked), SRI mismatches fail without retries, render crashes
5
+ // stay inside the boundary and the shell around them keeps rendering.
6
+ import { createHash } from 'node:crypto'
7
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
8
+ import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
9
+ import { __resetRemoteIntegrityCache, definePage, type FrontendPage } from '@asteby/metacore-sdk'
10
+
11
+ const mf = vi.hoisted(() => ({
12
+ registerRemotes: vi.fn(),
13
+ loadRemote: vi.fn(),
14
+ }))
15
+ vi.mock('@module-federation/runtime', () => mf)
16
+
17
+ import { AddonPageLoader } from '../addon-page-loader'
18
+ import { FederatedErrorBoundary } from '../federated-error-boundary'
19
+ import { useHostApi, usePageChrome } from '../addon-page-host'
20
+ import { createMockHostApi } from '../testing'
21
+
22
+ const page: FrontendPage = {
23
+ key: 'control_tower',
24
+ path: 'control-tower',
25
+ expose: './pages/control-tower',
26
+ title: 'shipping.pages.control_tower',
27
+ }
28
+
29
+ let quiet: ReturnType<typeof vi.spyOn>
30
+ beforeEach(() => {
31
+ mf.registerRemotes.mockReset()
32
+ mf.loadRemote.mockReset()
33
+ __resetRemoteIntegrityCache()
34
+ quiet = vi.spyOn(console, 'error').mockImplementation(() => {})
35
+ })
36
+ afterEach(() => {
37
+ cleanup()
38
+ quiet.mockRestore()
39
+ vi.unstubAllGlobals()
40
+ })
41
+
42
+ let n = 0
43
+ function mount(extra: Partial<React.ComponentProps<typeof AddonPageLoader>> = {}) {
44
+ n += 1
45
+ const onError = vi.fn()
46
+ const utils = render(
47
+ <div>
48
+ <nav data-testid="shell-sidebar">sidebar</nav>
49
+ <AddonPageLoader
50
+ scope={`metacore_shipping_${n}`}
51
+ url={`/api/metacore/addons/shipping/frontend/remoteEntry.js?v=${n}`}
52
+ addonKey="shipping"
53
+ page={page}
54
+ basePath="/a/shipping/control-tower"
55
+ host={{ locale: 'es-MX' }}
56
+ api={createMockHostApi()}
57
+ location={{ pathname: '/a/shipping/control-tower/shipments/42', search: '' }}
58
+ navigate={() => {}}
59
+ onError={onError}
60
+ {...extra}
61
+ />
62
+ </div>,
63
+ )
64
+ return { ...utils, onError }
65
+ }
66
+
67
+ describe('AddonPageLoader', () => {
68
+ it('loads the page expose and renders it with AddonPageProps + host hooks', async () => {
69
+ const Tower = definePage(({ basePath, params, page: p }) => {
70
+ const api = useHostApi()
71
+ usePageChrome({ title: 'Torre' })
72
+ return (
73
+ <p data-testid="page">
74
+ {basePath}|{params['*']}|{p.key}|{typeof api.capability}
75
+ </p>
76
+ )
77
+ })
78
+ mf.loadRemote.mockResolvedValue({ default: Tower })
79
+ mount()
80
+ expect(screen.getByTestId('addon-page-skeleton')).toBeTruthy()
81
+ await waitFor(() => expect(screen.getByTestId('page')).toBeTruthy())
82
+ expect(screen.getByTestId('page').textContent).toBe(
83
+ '/a/shipping/control-tower|shipments/42|control_tower|function',
84
+ )
85
+ expect(mf.registerRemotes).toHaveBeenCalledTimes(1)
86
+ expect(mf.loadRemote.mock.calls[0][0]).toMatch(/^metacore_shipping_\d+\/pages\/control-tower$/)
87
+ })
88
+
89
+ it('contains a crashing page: the shell stays, the incident is reported, retry re-renders', async () => {
90
+ let crash = true
91
+ const Boom = definePage(() => {
92
+ if (crash) throw new Error('kaboom')
93
+ return <p data-testid="recovered">ok</p>
94
+ })
95
+ mf.loadRemote.mockResolvedValue({ default: Boom })
96
+ const { onError } = mount()
97
+ await waitFor(() => expect(screen.getByTestId('federated-error')).toBeTruthy())
98
+ expect(screen.getByTestId('shell-sidebar')).toBeTruthy()
99
+ expect(onError).toHaveBeenCalledWith(
100
+ expect.objectContaining({ message: 'kaboom' }),
101
+ expect.objectContaining({ addonKey: 'shipping', expose: './pages/control-tower', phase: 'render' }),
102
+ )
103
+ crash = false
104
+ fireEvent.click(screen.getByText('Reintentar'))
105
+ await waitFor(() => expect(screen.getByTestId('recovered')).toBeTruthy())
106
+ })
107
+
108
+ it('a module without a default page shows the load error and retry reloads', async () => {
109
+ mf.loadRemote.mockResolvedValueOnce({ notAPage: 1 })
110
+ const { onError } = mount()
111
+ await waitFor(() => expect(screen.getByTestId('federated-error')).toBeTruthy())
112
+ expect(onError.mock.calls[0][1]).toMatchObject({ phase: 'load' })
113
+ mf.loadRemote.mockResolvedValueOnce({ default: definePage(() => <p data-testid="page">ok</p>) })
114
+ fireEvent.click(screen.getByText('Reintentar'))
115
+ await waitFor(() => expect(screen.getByTestId('page')).toBeTruthy())
116
+ })
117
+
118
+ it('refuses a remote whose bytes do not match frontend.integrity (no MF import, no retries)', async () => {
119
+ const genuine = 'export const init = () => {}'
120
+ const integrity = `sha384-${createHash('sha384').update(genuine).digest('base64')}`
121
+ const fetchMock = vi.fn(async () => new Response('alert("tampered")'))
122
+ vi.stubGlobal('fetch', fetchMock)
123
+ // The browser would reject the modulepreload on the hash mismatch.
124
+ const append = document.head.appendChild.bind(document.head)
125
+ const spy = vi.spyOn(document.head, 'appendChild').mockImplementation((node: Node) => {
126
+ const out = append(node)
127
+ if (node instanceof HTMLLinkElement && node.rel === 'modulepreload') {
128
+ expect(node.integrity).toBe(integrity)
129
+ setTimeout(() => node.onerror?.(new Event('error')), 0)
130
+ }
131
+ return out
132
+ })
133
+ mf.loadRemote.mockResolvedValue({ default: definePage(() => <p>never</p>) })
134
+ const { onError } = mount({ integrity })
135
+ await waitFor(() => expect(onError).toHaveBeenCalled())
136
+ expect(onError.mock.calls[0][0].name).toBe('RemoteIntegrityError')
137
+ expect(mf.registerRemotes).not.toHaveBeenCalled()
138
+ expect(mf.loadRemote).not.toHaveBeenCalled()
139
+ // modulepreload is attempted first; on its failure one diagnostic fetch.
140
+ expect(fetchMock).toHaveBeenCalledTimes(1)
141
+ spy.mockRestore()
142
+ })
143
+
144
+ it('mounts a remote whose modulepreload passed the integrity check', async () => {
145
+ const fetchMock = vi.fn()
146
+ vi.stubGlobal('fetch', fetchMock)
147
+ const append = document.head.appendChild.bind(document.head)
148
+ const spy = vi.spyOn(document.head, 'appendChild').mockImplementation((node: Node) => {
149
+ const out = append(node)
150
+ if (node instanceof HTMLLinkElement && node.rel === 'modulepreload') {
151
+ setTimeout(() => node.onload?.(new Event('load')), 0)
152
+ }
153
+ return out
154
+ })
155
+ mf.loadRemote.mockResolvedValue({ default: definePage(() => <p data-testid="page">ok</p>) })
156
+ mount({ integrity: 'sha384-AAAA' })
157
+ await waitFor(() => expect(screen.getByTestId('page')).toBeTruthy())
158
+ expect(fetchMock).not.toHaveBeenCalled()
159
+ spy.mockRestore()
160
+ })
161
+
162
+ it('times out a hung remote', async () => {
163
+ mf.loadRemote.mockReturnValue(new Promise(() => {}))
164
+ const { onError } = mount({ timeoutMs: 30 })
165
+ await waitFor(() => expect(onError).toHaveBeenCalled())
166
+ expect(onError.mock.calls[0][0].message).toMatch(/did not load within 30 ms/)
167
+ })
168
+ })
169
+
170
+ describe('FederatedErrorBoundary', () => {
171
+ it('resets when resetKeys change and survives a throwing reporter', () => {
172
+ const Boom = ({ fail }: { fail: boolean }) => {
173
+ if (fail) throw new Error('x')
174
+ return <p data-testid="fine">fine</p>
175
+ }
176
+ const { rerender } = render(
177
+ <FederatedErrorBoundary resetKeys={['v1']} onError={() => { throw new Error('reporter down') }}>
178
+ <Boom fail />
179
+ </FederatedErrorBoundary>,
180
+ )
181
+ expect(screen.getByRole('alert')).toBeTruthy()
182
+ rerender(
183
+ <FederatedErrorBoundary resetKeys={['v2']}>
184
+ <Boom fail={false} />
185
+ </FederatedErrorBoundary>,
186
+ )
187
+ expect(screen.getByTestId('fine')).toBeTruthy()
188
+ })
189
+
190
+ it('accepts a custom fallback', () => {
191
+ const Boom = () => {
192
+ throw new Error('bad')
193
+ }
194
+ render(
195
+ <FederatedErrorBoundary fallback={({ error }) => <span data-testid="custom">{error.message}</span>}>
196
+ <Boom />
197
+ </FederatedErrorBoundary>,
198
+ )
199
+ expect(screen.getByTestId('custom').textContent).toBe('bad')
200
+ })
201
+ })
@@ -0,0 +1,351 @@
1
+ // @vitest-environment happy-dom
2
+ //
3
+ // Declarative views (view_type map/timeline/calendar/chart/split) and detail
4
+ // panels: registry by type (lazy), pure mappers each renderer uses, and real
5
+ // renders against an in-memory ViewDataSource. Manifest fragments come from the
6
+ // kernel example (docs/spec/v3/examples/addon-ui-example.json, shipping).
7
+ import { afterEach, describe, expect, it, vi } from 'vitest'
8
+ import { cleanup, render, screen, waitFor } from '@testing-library/react'
9
+ import type { DetailPanel, NavView } from '@asteby/metacore-sdk'
10
+
11
+ vi.mock('react-i18next', () => ({
12
+ useTranslation: () => ({
13
+ t: (k: string, d?: unknown, o?: Record<string, unknown>) => {
14
+ const s = typeof d === 'string' ? d : k
15
+ const vars = (typeof d === 'object' ? d : o) as Record<string, unknown> | undefined
16
+ return s.replace(/\{\{(\w+)\}\}/g, (_, v) => String(vars?.[v] ?? ''))
17
+ },
18
+ }),
19
+ }))
20
+
21
+ class ResizeObserverStub {
22
+ observe() {}
23
+ unobserve() {}
24
+ disconnect() {}
25
+ }
26
+ ;(globalThis as any).ResizeObserver = (globalThis as any).ResizeObserver ?? ResizeObserverStub
27
+
28
+ import {
29
+ DeclarativeView,
30
+ DetailPanels,
31
+ hasViewRenderer,
32
+ isDeclarativeViewType,
33
+ preloadViewRenderer,
34
+ registerPanelRenderer,
35
+ registerViewRenderer,
36
+ } from '../views/registry'
37
+ import { createApiViewDataSource, pickItems, resolveCapabilityInput } from '../views/data-source'
38
+ import type { ViewDataSource, ViewRendererProps } from '../views/types'
39
+ import { toTimelineEntries } from '../views/timeline-view'
40
+ import { bucketByDay, monthRange, toCalendarEntries } from '../views/calendar-view'
41
+ import { openInMapHref, rowCoordinates, toMapFeatures, toRoutePoints } from '../views/map-view'
42
+ import { formatStat } from '../views/panels'
43
+ import { hiddenColumnsFor } from '../views/split-view'
44
+ import { resolveViewKind } from '../dynamic-view'
45
+ import type { TableMetadata } from '../types'
46
+
47
+ afterEach(cleanup)
48
+
49
+ const shipments = [
50
+ { id: 's1', tracking_number: 'TRK-1', carrier: 'dhl', status: 'in_transit', eta: '2026-10-20', dest_lat: 19.43, dest_lng: -99.13 },
51
+ { id: 's2', tracking_number: 'TRK-2', carrier: 'fedex', status: 'delivered', eta: '2026-10-18', dest_lat: '20.67', dest_lng: '-103.35' },
52
+ { id: 's3', tracking_number: 'TRK-3', carrier: 'dhl', status: 'created', eta: null, dest_lat: null, dest_lng: null },
53
+ ]
54
+ const events = [
55
+ { id: 'e1', shipment_id: 's1', at: '2026-10-16T10:00:00Z', status: 'picked_up', description: 'Recolectado', lat: 19.4, lng: -99.1 },
56
+ { id: 'e2', shipment_id: 's1', at: '2026-10-17T09:00:00Z', status: 'in_transit', description: 'En tránsito', lat: 19.9, lng: -100.2 },
57
+ ]
58
+
59
+ function memorySource(over: Partial<ViewDataSource> = {}): ViewDataSource & { list: ReturnType<typeof vi.fn> } {
60
+ const list = vi.fn(async (model: string) => {
61
+ if (model === 'ShipmentEvent') return { rows: events, total: events.length }
62
+ return { rows: shipments, total: shipments.length }
63
+ })
64
+ return {
65
+ list,
66
+ record: vi.fn(async (_m: string, id: string) => shipments.find((s) => s.id === id) ?? null),
67
+ chart: vi.fn(async () => ({ series: [{ key: 'dhl', label: 'DHL', value: 2 }] })),
68
+ capability: vi.fn(async () => ({ status: 'in_transit', events })),
69
+ ...over,
70
+ } as ViewDataSource & { list: ReturnType<typeof vi.fn> }
71
+ }
72
+
73
+ const metadata = {
74
+ title: 'Envíos',
75
+ columns: [
76
+ { key: 'tracking_number', label: 'Guía' },
77
+ { key: 'carrier', label: 'Paquetería' },
78
+ { key: 'status', label: 'Estado' },
79
+ { key: 'eta', label: 'ETA' },
80
+ { key: 'cost', label: 'Costo' },
81
+ ],
82
+ relations: [{ name: 'events', kind: 'one_to_many', through: 'ShipmentEvent', foreign_key: 'shipment_id' }],
83
+ } as unknown as TableMetadata
84
+
85
+ describe('registry', () => {
86
+ it('knows the declarative types; table/kanban stay with DynamicView', () => {
87
+ for (const t of ['map', 'timeline', 'calendar', 'chart', 'split']) {
88
+ expect(isDeclarativeViewType(t)).toBe(true)
89
+ expect(hasViewRenderer(t)).toBe(true)
90
+ }
91
+ expect(isDeclarativeViewType('table')).toBe(false)
92
+ expect(isDeclarativeViewType('kanban')).toBe(false)
93
+ })
94
+
95
+ it('resolveViewKind needs the view block (hosts that do not serve it keep the table)', () => {
96
+ expect(resolveViewKind('map', { view: { map: { point: { lat: 'a', lng: 'b' } } } })).toBe('declarative')
97
+ expect(resolveViewKind('map', {})).toBe('table')
98
+ expect(resolveViewKind('kanban', null)).toBe('kanban')
99
+ expect(resolveViewKind(undefined, null)).toBe('table')
100
+ })
101
+
102
+ it('preloads a renderer chunk by type and reports unknown ones', async () => {
103
+ await expect(preloadViewRenderer('timeline')).resolves.toBe(true)
104
+ await expect(preloadViewRenderer('gantt')).resolves.toBe(false)
105
+ })
106
+
107
+ it('a maps package can replace the map renderer; restore brings the fallback back', async () => {
108
+ function FakeMap(p: ViewRendererProps<'map'>) {
109
+ return <div data-testid="real-map">{p.model}</div>
110
+ }
111
+ const restore = registerViewRenderer('map', async () => ({ default: FakeMap }))
112
+ const view: NavView = { map: { point: { lat: 'dest_lat', lng: 'dest_lng' } } }
113
+ render(<DeclarativeView viewType="map" view={view} model="Shipment" data={memorySource()} />)
114
+ await waitFor(() => expect(screen.getByTestId('real-map').textContent).toBe('Shipment'))
115
+ restore()
116
+ cleanup()
117
+ render(<DeclarativeView viewType="map" view={view} model="Shipment" data={memorySource()} />)
118
+ await waitFor(() => expect(screen.getByTestId('map-view-fallback')).toBeTruthy())
119
+ })
120
+
121
+ it('unknown type or missing block renders the fallback', () => {
122
+ render(
123
+ <DeclarativeView
124
+ viewType="gantt"
125
+ view={{}}
126
+ model="Shipment"
127
+ data={memorySource()}
128
+ fallback={<p data-testid="table">table</p>}
129
+ />,
130
+ )
131
+ expect(screen.getByTestId('table')).toBeTruthy()
132
+ })
133
+ })
134
+
135
+ describe('data source helpers', () => {
136
+ it('maps capability input from the record (record.<col> | const:<lit>)', () => {
137
+ expect(
138
+ resolveCapabilityInput({ tracking_number: 'record.tracking_number', carrier: 'const:dhl' }, shipments[0]),
139
+ ).toEqual({ tracking_number: 'TRK-1', carrier: 'dhl' })
140
+ expect(() => resolveCapabilityInput({ x: '$record.y' }, {})).toThrow(/unsupported reference/)
141
+ })
142
+
143
+ it('picks the items array by dot path', () => {
144
+ expect(pickItems({ data: { events } }, 'data.events')).toHaveLength(2)
145
+ expect(pickItems({ events: 'nope' }, 'events')).toEqual([])
146
+ })
147
+
148
+ it('default api source speaks the kernel list syntax and the host chart endpoint', async () => {
149
+ const api = {
150
+ get: vi.fn(async () => ({ data: { success: true, data: shipments, meta: { total: 3 } } })),
151
+ post: vi.fn(async () => ({ data: { success: true, data: { value: 3 } } })),
152
+ put: vi.fn(),
153
+ delete: vi.fn(),
154
+ }
155
+ const ds = createApiViewDataSource(api)
156
+ await expect(ds.list('Shipment', { per_page: 5 })).resolves.toEqual({ rows: shipments, total: 3 })
157
+ expect(api.get).toHaveBeenCalledWith('/data/Shipment', { params: { per_page: 5 } })
158
+ await ds.chart({ model: 'Shipment', query: { model: 'Shipment', group_by: 'carrier' } })
159
+ expect(api.post).toHaveBeenCalledWith('/views/chart', expect.objectContaining({ model: 'Shipment' }))
160
+ })
161
+ })
162
+
163
+ describe('pure mappers', () => {
164
+ it('timeline: newest first, status/description/group', () => {
165
+ const entries = toTimelineEntries(events, {
166
+ date_field: 'at',
167
+ title_field: 'description',
168
+ status_field: 'status',
169
+ group_by: 'shipment_id',
170
+ })
171
+ expect(entries.map((e) => e.title)).toEqual(['En tránsito', 'Recolectado'])
172
+ expect(entries[0].status).toBe('in_transit')
173
+ expect(entries[0].group).toBe('s1')
174
+ })
175
+
176
+ it('calendar: month range, entries without start dropped, multi-day spans', () => {
177
+ expect(monthRange(new Date(2026, 1, 10))).toEqual({ first: '2026-02-01', last: '2026-02-28' })
178
+ const entries = toCalendarEntries(
179
+ [...shipments, { id: 'x', tracking_number: 'TRK-X', eta: '2026-10-21', end: '2026-10-23' }],
180
+ { start_field: 'eta', end_field: 'end', title_field: 'tracking_number', color_by: 'status' },
181
+ )
182
+ expect(entries.map((e) => e.title)).toEqual(['TRK-1', 'TRK-2', 'TRK-X'])
183
+ expect(entries[0].allDay).toBe(true)
184
+ const days = bucketByDay(entries)
185
+ expect(days.get('2026-10-22')?.map((e) => e.title)).toEqual(['TRK-X'])
186
+ expect(days.get('2026-10-20')?.[0].color).toBe('in_transit')
187
+ })
188
+
189
+ it('map: numeric/string coords, invalid rows skipped, GeoJSON points, routes in order', () => {
190
+ const features = toMapFeatures(shipments, {
191
+ point: { lat: 'dest_lat', lng: 'dest_lng' },
192
+ color_by: 'status',
193
+ popup: ['tracking_number', 'carrier'],
194
+ })
195
+ expect(features.map((f) => f.key)).toEqual(['s1', 's2'])
196
+ expect(features[1]).toMatchObject({ lat: 20.67, lng: -103.35, color: 'delivered' })
197
+ expect(features[0].popup).toEqual([
198
+ { field: 'tracking_number', value: 'TRK-1' },
199
+ { field: 'carrier', value: 'dhl' },
200
+ ])
201
+ expect(rowCoordinates({ g: '{"type":"Point","coordinates":[-99.1,19.4]}' }, undefined, 'g')).toEqual({ lat: 19.4, lng: -99.1 })
202
+ expect(rowCoordinates({ a: 95, b: 0 }, { lat: 'a', lng: 'b' }, undefined)).toBeNull()
203
+ expect(
204
+ toRoutePoints([events[1], events[0]], { relation: 'events', point: { lat: 'lat', lng: 'lng' }, order_by: 'at' }),
205
+ ).toEqual([{ lat: 19.4, lng: -99.1 }, { lat: 19.9, lng: -100.2 }])
206
+ expect(openInMapHref(19.4, -99.1)).toContain('mlat=19.4&mlon=-99.1')
207
+ })
208
+
209
+ it('stats: format without computing business values', () => {
210
+ const now = new Date('2026-10-17T12:00:00Z')
211
+ expect(formatStat(1234.5, 'currency', { locale: 'es-MX', currency: 'MXN' })).toMatch(/1,234\.50/)
212
+ expect(formatStat(0.25, 'percent', { locale: 'en-US' })).toBe('25%')
213
+ expect(formatStat('2026-10-20T12:00:00Z', 'relative_date', { locale: 'en-US', now })).toBe('in 3 days')
214
+ expect(formatStat(null, 'number')).toBe('—')
215
+ expect(formatStat('abc', 'number')).toBe('abc')
216
+ })
217
+
218
+ it('split: hides every metadata column not listed', () => {
219
+ expect(hiddenColumnsFor(['a', 'b', 'c'], ['b'])).toEqual(['a', 'c'])
220
+ expect(hiddenColumnsFor(['a', 'b'], undefined)).toEqual([])
221
+ })
222
+ })
223
+
224
+ describe('renderers', () => {
225
+ it('timeline view lists the model rows newest first', async () => {
226
+ const data = memorySource()
227
+ render(
228
+ <DeclarativeView
229
+ viewType="timeline"
230
+ view={{ timeline: { date_field: 'at', title_field: 'description', status_field: 'status' } }}
231
+ model="ShipmentEvent"
232
+ data={data}
233
+ locale="es-MX"
234
+ />,
235
+ )
236
+ await waitFor(() => expect(screen.getByTestId('timeline')).toBeTruthy())
237
+ expect(screen.getAllByRole('listitem').map((li) => li.textContent)).toEqual([
238
+ expect.stringContaining('En tránsito'),
239
+ expect.stringContaining('Recolectado'),
240
+ ])
241
+ expect(data.list).toHaveBeenCalledWith('ShipmentEvent', expect.objectContaining({ sortBy: 'at', order: 'desc' }))
242
+ })
243
+
244
+ it('calendar view requests one month with the RANGE filter', async () => {
245
+ const data = memorySource()
246
+ render(
247
+ <DeclarativeView
248
+ viewType="calendar"
249
+ view={{ calendar: { start_field: 'eta', title_field: 'tracking_number' } }}
250
+ model="Shipment"
251
+ data={data}
252
+ />,
253
+ )
254
+ await waitFor(() => expect(screen.getByRole('grid')).toBeTruthy())
255
+ const params = data.list.mock.calls[0][1] as Record<string, string>
256
+ expect(params.f_eta).toMatch(/^RANGE:\d{4}-\d{2}-01,\d{4}-\d{2}-\d{2}$/)
257
+ })
258
+
259
+ it('chart view asks the host for the declared query and paints the widget card', async () => {
260
+ const data = memorySource()
261
+ render(
262
+ <DeclarativeView
263
+ viewType="chart"
264
+ view={{ chart: { kind: 'bar', query: { model: 'Shipment', group_by: 'carrier', range: 'last_30_days' } } }}
265
+ model="Shipment"
266
+ metadata={metadata}
267
+ data={data}
268
+ />,
269
+ )
270
+ await waitFor(() => expect(screen.getByTestId('chart-view').getAttribute('data-kind')).toBe('bar'))
271
+ expect(data.chart).toHaveBeenCalledWith({
272
+ model: 'Shipment',
273
+ query: { model: 'Shipment', group_by: 'carrier', range: 'last_30_days' },
274
+ })
275
+ expect(screen.getByText('Envíos')).toBeTruthy()
276
+ })
277
+
278
+ it('detail panels: stats, relation and capability timeline, each lazy and isolated', async () => {
279
+ const data = memorySource()
280
+ const panels: DetailPanel[] = [
281
+ { key: 'figures', kind: 'stats', title: 'shipping.panel.figures', stats: { items: [{ field: 'carrier' }, { field: 'cost', format: 'currency' }] } },
282
+ { key: 'history', kind: 'relation', title: 'shipping.panel.history', relation: { name: 'events', columns: ['status'], limit: 5 } },
283
+ {
284
+ key: 'tracking',
285
+ kind: 'timeline',
286
+ title: 'shipping.panel.tracking',
287
+ span: 'half',
288
+ timeline: {
289
+ date_field: 'at',
290
+ title_field: 'description',
291
+ source: {
292
+ capability: 'commerce.shipping.track',
293
+ input: { tracking_number: 'record.tracking_number', carrier: 'record.carrier' },
294
+ items: 'events',
295
+ },
296
+ },
297
+ },
298
+ { key: 'mystery', kind: 'custom', title: 'x', expose: './panels/x' },
299
+ ]
300
+ render(<DetailPanels model="Shipment" panels={panels} record={shipments[0]} metadata={metadata} data={data} />)
301
+ await waitFor(() => expect(screen.getByTestId('stats-panel')).toBeTruthy())
302
+ await waitFor(() => expect(screen.getByTestId('relation-panel')).toBeTruthy())
303
+ await waitFor(() => expect(screen.getByTestId('timeline')).toBeTruthy())
304
+ expect(screen.getByText('Paquetería')).toBeTruthy()
305
+ expect(data.capability).toHaveBeenCalledWith('commerce.shipping.track', { tracking_number: 'TRK-1', carrier: 'dhl' })
306
+ expect(data.list).toHaveBeenCalledWith('ShipmentEvent', { f_shipment_id: 'eq:s1', per_page: 5 })
307
+ // `custom` has no built-in renderer until the host registers one.
308
+ expect(screen.getByTestId('panel-unsupported').textContent).toBe('custom')
309
+ })
310
+
311
+ it('a host-registered custom panel renders; a crashing panel stays contained', async () => {
312
+ const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
313
+ const restoreCustom = registerPanelRenderer('custom', async () => ({
314
+ default: ({ panel }) => <p data-testid="custom-panel">{panel.expose}</p>,
315
+ }))
316
+ const restoreStats = registerPanelRenderer('stats', async () => ({
317
+ default: () => {
318
+ throw new Error('boom')
319
+ },
320
+ }))
321
+ render(
322
+ <DetailPanels
323
+ model="Shipment"
324
+ panels={[
325
+ { key: 'c', kind: 'custom', title: 'c', expose: './panels/route-planner' },
326
+ { key: 's', kind: 'stats', title: 's', stats: { items: [{ field: 'cost' }] } },
327
+ ]}
328
+ record={shipments[0]}
329
+ data={memorySource()}
330
+ />,
331
+ )
332
+ await waitFor(() => expect(screen.getByTestId('custom-panel').textContent).toBe('./panels/route-planner'))
333
+ await waitFor(() => expect(screen.getByTestId('federated-error')).toBeTruthy())
334
+ restoreCustom()
335
+ restoreStats()
336
+ spy.mockRestore()
337
+ })
338
+
339
+ it('panel permission hides the panel', () => {
340
+ render(
341
+ <DetailPanels
342
+ model="Shipment"
343
+ panels={[{ key: 's', kind: 'stats', title: 'secret', permission: 'shipping.cost.read', stats: { items: [{ field: 'cost' }] } }]}
344
+ record={shipments[0]}
345
+ data={memorySource()}
346
+ can={() => false}
347
+ />,
348
+ )
349
+ expect(screen.queryByText('secret')).toBeNull()
350
+ })
351
+ })