@vizhub/runtime 0.2.0 → 0.3.1

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 (285) hide show
  1. package/README.md +280 -128
  2. package/dist/buildHTML.d.ts +14 -0
  3. package/dist/buildHTML.js +67 -0
  4. package/dist/cjs/buildHTML.js +71 -0
  5. package/dist/cjs/common/packageJson.js +81 -0
  6. package/dist/cjs/common/packageJson.test.js +148 -0
  7. package/dist/cjs/common/sucrasePlugin.js +27 -0
  8. package/dist/cjs/common/virtualFileSystem.js +79 -0
  9. package/dist/cjs/determineRuntimeVersion.js +26 -0
  10. package/dist/cjs/determineRuntimeVersion.test.js +103 -0
  11. package/dist/cjs/index.js +9 -0
  12. package/dist/cjs/package.json +1 -0
  13. package/dist/cjs/test/fixtures/v1/basicHTML.js +18 -0
  14. package/dist/cjs/test/fixtures/v1/fetchProxy.js +15 -0
  15. package/dist/cjs/test/fixtures/v1/index.js +15 -0
  16. package/dist/cjs/test/fixtures/v1/jsScriptTag.js +12 -0
  17. package/dist/cjs/test/fixtures/v1/protocolTest.js +18 -0
  18. package/dist/cjs/test/fixtures/v1/styleTest.js +18 -0
  19. package/dist/cjs/test/fixtures/v1/xmlTest.js +22 -0
  20. package/dist/cjs/test/fixtures/v2/basicBundle.js +8 -0
  21. package/dist/cjs/test/fixtures/v2/basicBundleNoExtension.js +8 -0
  22. package/dist/cjs/test/fixtures/v2/d3Import.js +10 -0
  23. package/dist/cjs/test/fixtures/v2/d3ImportPkg.js +22 -0
  24. package/dist/cjs/test/fixtures/v2/d3RosettaImportPkg.js +22 -0
  25. package/dist/cjs/test/fixtures/v2/es6Preserve.js +9 -0
  26. package/dist/cjs/test/fixtures/v2/generatorSupport.js +9 -0
  27. package/dist/cjs/test/fixtures/v2/index.js +45 -0
  28. package/dist/cjs/test/fixtures/v2/jsxTranspile.js +9 -0
  29. package/dist/cjs/test/fixtures/v2/reactDomImport.js +11 -0
  30. package/dist/cjs/test/fixtures/v2/reactDomImportPkg.js +27 -0
  31. package/dist/cjs/test/fixtures/v2/reactImport.js +10 -0
  32. package/dist/cjs/test/fixtures/v2/reactImportPkg.js +20 -0
  33. package/dist/cjs/test/fixtures/v2/sourceMapErrorFixture.js +22 -0
  34. package/dist/cjs/test/fixtures/v2/unicodeSupport.js +9 -0
  35. package/dist/cjs/test/fixtures/v3/basicIndexJS.js +10 -0
  36. package/dist/cjs/test/fixtures/v3/cssImport.js +12 -0
  37. package/dist/cjs/test/fixtures/v3/csvImport.js +14 -0
  38. package/dist/cjs/test/fixtures/v3/csvStrangeChars.js +15 -0
  39. package/dist/cjs/test/fixtures/v3/index.js +25 -0
  40. package/dist/cjs/test/fixtures/v3/jsExport.js +13 -0
  41. package/dist/cjs/test/fixtures/v3/sourcemap.js +13 -0
  42. package/dist/cjs/test/fixtures/v3/svelte.js +21 -0
  43. package/dist/cjs/test/fixtures/v3/vizContent.js +14 -0
  44. package/dist/cjs/test/fixtures/v3/vizImport.js +88 -0
  45. package/dist/cjs/test/fixtures/v4/d3Usage.js +34 -0
  46. package/dist/cjs/test/fixtures/v4/esmBuild.js +21 -0
  47. package/dist/cjs/test/fixtures/v4/fetchInterception.js +21 -0
  48. package/dist/cjs/test/fixtures/v4/index.js +21 -0
  49. package/dist/cjs/test/fixtures/v4/jsScriptTagTypeModule.js +21 -0
  50. package/dist/cjs/test/fixtures/v4/jsScriptTagTypeModules.js +15 -0
  51. package/dist/cjs/test/fixtures/v4/reactHooks.js +50 -0
  52. package/dist/cjs/test/fixtures/v4/reactJsx.js +37 -0
  53. package/dist/cjs/test/fixtures/v4/threeJsUsage.js +27 -0
  54. package/dist/cjs/test/fixtures/v4/typeScriptSupport.js +32 -0
  55. package/dist/cjs/test/testInBrowser.js +50 -0
  56. package/dist/cjs/test/testStackTrace.js +58 -0
  57. package/dist/cjs/test/v1.test.js +70 -0
  58. package/dist/cjs/test/v2.test.js +124 -0
  59. package/dist/cjs/test/v3.test.js +119 -0
  60. package/dist/cjs/test/v4.test.js +105 -0
  61. package/dist/cjs/types.js +2 -0
  62. package/dist/cjs/utils/vizContentToFileCollection.js +23 -0
  63. package/dist/cjs/utils/vizContentToFileCollection.test.js +77 -0
  64. package/dist/cjs/v2/computeBundleJSV2.js +33 -0
  65. package/dist/cjs/v2/getComputedIndexHtml.js +86 -0
  66. package/dist/cjs/v2/getComputedIndexHtml.test.js +136 -0
  67. package/dist/cjs/v2/index.js +5 -0
  68. package/dist/cjs/v2/v2Build.js +15 -0
  69. package/dist/cjs/v3/cleanRollupErrorMessage.js +13 -0
  70. package/dist/cjs/v3/computeBundleJSV3.js +52 -0
  71. package/dist/cjs/v3/createVizContent.js +27 -0
  72. package/dist/cjs/v3/extractVizImport.js +27 -0
  73. package/dist/cjs/v3/extractVizImport.test.js +32 -0
  74. package/dist/cjs/v3/htmlTemplate.js +93 -0
  75. package/dist/cjs/v3/index.js +5 -0
  76. package/dist/cjs/v3/parseId.js +9 -0
  77. package/dist/cjs/v3/parseId.test.js +27 -0
  78. package/dist/cjs/v3/setupV3Runtime.js +345 -0
  79. package/dist/cjs/v3/slugCache.js +39 -0
  80. package/dist/cjs/v3/slugCache.test.js +107 -0
  81. package/dist/cjs/v3/transformDSV/dsvParseSrc.js +124 -0
  82. package/dist/cjs/v3/transformDSV/index.js +44 -0
  83. package/dist/cjs/v3/transformSvelte.js +81 -0
  84. package/dist/cjs/v3/types.js +2 -0
  85. package/dist/cjs/v3/v3Build.js +34 -0
  86. package/dist/cjs/v3/vizCache.js +40 -0
  87. package/dist/cjs/v3/vizCache.test.js +100 -0
  88. package/dist/cjs/v3/vizLoad.js +50 -0
  89. package/dist/cjs/v3/vizResolve.js +73 -0
  90. package/dist/cjs/v4/index.js +138 -0
  91. package/dist/common/packageJson.d.ts +1 -1
  92. package/dist/common/virtualFileSystem.d.ts +1 -1
  93. package/dist/determineRuntimeVersion.d.ts +2 -1
  94. package/dist/esm/buildHTML.js +67 -0
  95. package/dist/esm/common/packageJson.js +71 -0
  96. package/dist/esm/common/packageJson.test.js +146 -0
  97. package/dist/esm/common/sucrasePlugin.js +24 -0
  98. package/dist/esm/common/virtualFileSystem.js +75 -0
  99. package/dist/esm/determineRuntimeVersion.js +22 -0
  100. package/dist/esm/determineRuntimeVersion.test.js +101 -0
  101. package/dist/esm/index.js +3 -0
  102. package/dist/esm/test/fixtures/v1/basicHTML.js +15 -0
  103. package/dist/esm/test/fixtures/v1/fetchProxy.js +12 -0
  104. package/dist/esm/test/fixtures/v1/index.js +6 -0
  105. package/dist/esm/test/fixtures/v1/jsScriptTag.js +9 -0
  106. package/dist/esm/test/fixtures/v1/protocolTest.js +15 -0
  107. package/dist/esm/test/fixtures/v1/styleTest.js +15 -0
  108. package/dist/esm/test/fixtures/v1/xmlTest.js +19 -0
  109. package/dist/esm/test/fixtures/v2/basicBundle.js +5 -0
  110. package/dist/esm/test/fixtures/v2/basicBundleNoExtension.js +5 -0
  111. package/dist/esm/test/fixtures/v2/d3Import.js +7 -0
  112. package/dist/esm/test/fixtures/v2/d3ImportPkg.js +19 -0
  113. package/dist/esm/test/fixtures/v2/d3RosettaImportPkg.js +19 -0
  114. package/dist/esm/test/fixtures/v2/es6Preserve.js +6 -0
  115. package/dist/esm/test/fixtures/v2/generatorSupport.js +6 -0
  116. package/dist/esm/test/fixtures/v2/index.js +15 -0
  117. package/dist/esm/test/fixtures/v2/jsxTranspile.js +6 -0
  118. package/dist/esm/test/fixtures/v2/reactDomImport.js +8 -0
  119. package/dist/esm/test/fixtures/v2/reactDomImportPkg.js +24 -0
  120. package/dist/esm/test/fixtures/v2/reactImport.js +7 -0
  121. package/dist/esm/test/fixtures/v2/reactImportPkg.js +17 -0
  122. package/dist/esm/test/fixtures/v2/sourceMapErrorFixture.js +19 -0
  123. package/dist/esm/test/fixtures/v2/unicodeSupport.js +6 -0
  124. package/dist/esm/test/fixtures/v3/basicIndexJS.js +7 -0
  125. package/dist/esm/test/fixtures/v3/cssImport.js +9 -0
  126. package/dist/esm/test/fixtures/v3/csvImport.js +11 -0
  127. package/dist/esm/test/fixtures/v3/csvStrangeChars.js +12 -0
  128. package/dist/esm/test/fixtures/v3/index.js +9 -0
  129. package/dist/esm/test/fixtures/v3/jsExport.js +10 -0
  130. package/dist/esm/test/fixtures/v3/sourcemap.js +10 -0
  131. package/dist/esm/test/fixtures/v3/svelte.js +18 -0
  132. package/dist/esm/test/fixtures/v3/vizContent.js +11 -0
  133. package/dist/esm/test/fixtures/v3/vizImport.js +85 -0
  134. package/dist/esm/test/fixtures/v4/d3Usage.js +31 -0
  135. package/dist/esm/test/fixtures/v4/esmBuild.js +18 -0
  136. package/dist/esm/test/fixtures/v4/fetchInterception.js +18 -0
  137. package/dist/esm/test/fixtures/v4/index.js +9 -0
  138. package/dist/esm/test/fixtures/v4/jsScriptTagTypeModule.js +18 -0
  139. package/dist/esm/test/fixtures/v4/jsScriptTagTypeModules.js +12 -0
  140. package/dist/esm/test/fixtures/v4/reactHooks.js +47 -0
  141. package/dist/esm/test/fixtures/v4/reactJsx.js +34 -0
  142. package/dist/esm/test/fixtures/v4/threeJsUsage.js +24 -0
  143. package/dist/esm/test/fixtures/v4/typeScriptSupport.js +29 -0
  144. package/dist/esm/test/testInBrowser.js +47 -0
  145. package/dist/esm/test/testStackTrace.js +55 -0
  146. package/dist/esm/test/v1.test.js +65 -0
  147. package/dist/esm/test/v2.test.js +121 -0
  148. package/dist/esm/test/v3.test.js +114 -0
  149. package/dist/esm/test/v4.test.js +100 -0
  150. package/dist/esm/types.js +1 -0
  151. package/dist/esm/utils/vizContentToFileCollection.js +19 -0
  152. package/dist/esm/utils/vizContentToFileCollection.test.js +75 -0
  153. package/dist/esm/v2/computeBundleJSV2.js +29 -0
  154. package/dist/esm/v2/getComputedIndexHtml.js +81 -0
  155. package/dist/esm/v2/getComputedIndexHtml.test.js +134 -0
  156. package/dist/esm/v2/index.js +1 -0
  157. package/dist/esm/v2/v2Build.js +11 -0
  158. package/dist/esm/v3/cleanRollupErrorMessage.js +9 -0
  159. package/dist/esm/v3/computeBundleJSV3.js +48 -0
  160. package/dist/esm/v3/createVizContent.js +23 -0
  161. package/dist/esm/v3/extractVizImport.js +23 -0
  162. package/dist/esm/v3/extractVizImport.test.js +30 -0
  163. package/dist/esm/v3/htmlTemplate.js +89 -0
  164. package/dist/esm/v3/index.js +1 -0
  165. package/dist/esm/v3/parseId.js +5 -0
  166. package/dist/esm/v3/parseId.test.js +25 -0
  167. package/dist/esm/v3/setupV3Runtime.js +341 -0
  168. package/dist/esm/v3/slugCache.js +35 -0
  169. package/dist/esm/v3/slugCache.test.js +105 -0
  170. package/dist/esm/v3/transformDSV/dsvParseSrc.js +121 -0
  171. package/dist/esm/v3/transformDSV/index.js +40 -0
  172. package/dist/esm/v3/transformSvelte.js +77 -0
  173. package/dist/esm/v3/types.js +1 -0
  174. package/dist/esm/v3/v3Build.js +30 -0
  175. package/dist/esm/v3/vizCache.js +36 -0
  176. package/dist/esm/v3/vizCache.test.js +98 -0
  177. package/dist/esm/v3/vizLoad.js +46 -0
  178. package/dist/esm/v3/vizResolve.js +69 -0
  179. package/dist/esm/v4/index.js +134 -0
  180. package/dist/index.d.ts +3 -14
  181. package/dist/index.js +3 -67
  182. package/dist/test/testInBrowser.d.ts +1 -2
  183. package/dist/test/testStackTrace.d.ts +1 -1
  184. package/dist/types/buildHTML.d.ts +14 -0
  185. package/dist/types/common/packageJson.d.ts +39 -0
  186. package/dist/types/common/packageJson.test.d.ts +1 -0
  187. package/dist/types/common/sucrasePlugin.d.ts +2 -0
  188. package/dist/types/common/virtualFileSystem.d.ts +3 -0
  189. package/dist/types/determineRuntimeVersion.d.ts +3 -0
  190. package/dist/types/determineRuntimeVersion.test.d.ts +1 -0
  191. package/dist/types/index.d.ts +3 -0
  192. package/dist/types/test/fixtures/v1/basicHTML.d.ts +3 -0
  193. package/dist/types/test/fixtures/v1/fetchProxy.d.ts +5 -0
  194. package/dist/types/test/fixtures/v1/index.d.ts +6 -0
  195. package/dist/types/test/fixtures/v1/jsScriptTag.d.ts +4 -0
  196. package/dist/types/test/fixtures/v1/protocolTest.d.ts +3 -0
  197. package/dist/types/test/fixtures/v1/styleTest.d.ts +4 -0
  198. package/dist/types/test/fixtures/v1/xmlTest.d.ts +4 -0
  199. package/dist/types/test/fixtures/v2/basicBundle.d.ts +5 -0
  200. package/dist/types/test/fixtures/v2/basicBundleNoExtension.d.ts +5 -0
  201. package/dist/types/test/fixtures/v2/d3Import.d.ts +4 -0
  202. package/dist/types/test/fixtures/v2/d3ImportPkg.d.ts +5 -0
  203. package/dist/types/test/fixtures/v2/d3RosettaImportPkg.d.ts +5 -0
  204. package/dist/types/test/fixtures/v2/es6Preserve.d.ts +4 -0
  205. package/dist/types/test/fixtures/v2/generatorSupport.d.ts +4 -0
  206. package/dist/types/test/fixtures/v2/index.d.ts +14 -0
  207. package/dist/types/test/fixtures/v2/jsxTranspile.d.ts +4 -0
  208. package/dist/types/test/fixtures/v2/reactDomImport.d.ts +4 -0
  209. package/dist/types/test/fixtures/v2/reactDomImportPkg.d.ts +5 -0
  210. package/dist/types/test/fixtures/v2/reactImport.d.ts +4 -0
  211. package/dist/types/test/fixtures/v2/reactImportPkg.d.ts +5 -0
  212. package/dist/types/test/fixtures/v2/sourceMapErrorFixture.d.ts +5 -0
  213. package/dist/types/test/fixtures/v2/unicodeSupport.d.ts +4 -0
  214. package/dist/types/test/fixtures/v3/basicIndexJS.d.ts +3 -0
  215. package/dist/types/test/fixtures/v3/cssImport.d.ts +4 -0
  216. package/dist/types/test/fixtures/v3/csvImport.d.ts +4 -0
  217. package/dist/types/test/fixtures/v3/csvStrangeChars.d.ts +4 -0
  218. package/dist/types/test/fixtures/v3/index.d.ts +9 -0
  219. package/dist/types/test/fixtures/v3/jsExport.d.ts +4 -0
  220. package/dist/types/test/fixtures/v3/sourcemap.d.ts +3 -0
  221. package/dist/types/test/fixtures/v3/svelte.d.ts +4 -0
  222. package/dist/types/test/fixtures/v3/vizContent.d.ts +2 -0
  223. package/dist/types/test/fixtures/v3/vizImport.d.ts +6 -0
  224. package/dist/types/test/fixtures/v4/d3Usage.d.ts +5 -0
  225. package/dist/types/test/fixtures/v4/esmBuild.d.ts +5 -0
  226. package/dist/types/test/fixtures/v4/fetchInterception.d.ts +5 -0
  227. package/dist/types/test/fixtures/v4/index.d.ts +9 -0
  228. package/dist/types/test/fixtures/v4/jsScriptTagTypeModule.d.ts +4 -0
  229. package/dist/types/test/fixtures/v4/jsScriptTagTypeModules.d.ts +5 -0
  230. package/dist/types/test/fixtures/v4/reactHooks.d.ts +6 -0
  231. package/dist/types/test/fixtures/v4/reactJsx.d.ts +6 -0
  232. package/dist/types/test/fixtures/v4/threeJsUsage.d.ts +4 -0
  233. package/dist/types/test/fixtures/v4/typeScriptSupport.d.ts +5 -0
  234. package/dist/types/test/testInBrowser.d.ts +15 -0
  235. package/dist/types/test/testStackTrace.d.ts +9 -0
  236. package/dist/types/test/v1.test.d.ts +1 -0
  237. package/dist/types/test/v2.test.d.ts +1 -0
  238. package/dist/types/test/v3.test.d.ts +1 -0
  239. package/dist/types/test/v4.test.d.ts +1 -0
  240. package/dist/types/types.d.ts +1 -0
  241. package/dist/types/utils/vizContentToFileCollection.d.ts +7 -0
  242. package/dist/types/utils/vizContentToFileCollection.test.d.ts +1 -0
  243. package/dist/types/v2/computeBundleJSV2.d.ts +7 -0
  244. package/dist/types/v2/getComputedIndexHtml.d.ts +4 -0
  245. package/dist/types/v2/getComputedIndexHtml.test.d.ts +1 -0
  246. package/dist/types/v2/index.d.ts +1 -0
  247. package/dist/types/v2/v2Build.d.ts +7 -0
  248. package/dist/types/v3/cleanRollupErrorMessage.d.ts +4 -0
  249. package/dist/types/v3/computeBundleJSV3.d.ts +17 -0
  250. package/dist/types/v3/createVizContent.d.ts +8 -0
  251. package/dist/types/v3/extractVizImport.d.ts +6 -0
  252. package/dist/types/v3/extractVizImport.test.d.ts +1 -0
  253. package/dist/types/v3/htmlTemplate.d.ts +5 -0
  254. package/dist/types/v3/index.d.ts +1 -0
  255. package/dist/types/v3/parseId.d.ts +6 -0
  256. package/dist/types/v3/parseId.test.d.ts +1 -0
  257. package/dist/types/v3/setupV3Runtime.d.ts +15 -0
  258. package/dist/types/v3/slugCache.d.ts +11 -0
  259. package/dist/types/v3/slugCache.test.d.ts +1 -0
  260. package/dist/types/v3/transformDSV/dsvParseSrc.d.ts +1 -0
  261. package/dist/types/v3/transformDSV/index.d.ts +2 -0
  262. package/dist/types/v3/transformSvelte.d.ts +8 -0
  263. package/dist/types/v3/types.d.ts +65 -0
  264. package/dist/types/v3/v3Build.d.ts +14 -0
  265. package/dist/types/v3/vizCache.d.ts +10 -0
  266. package/dist/types/v3/vizCache.test.d.ts +1 -0
  267. package/dist/types/v3/vizLoad.d.ts +7 -0
  268. package/dist/types/v3/vizResolve.d.ts +7 -0
  269. package/dist/types/v4/index.d.ts +10 -0
  270. package/dist/types.d.ts +0 -1
  271. package/dist/utils/vizContentToFileCollection.d.ts +1 -2
  272. package/dist/v2/computeBundleJSV2.d.ts +1 -1
  273. package/dist/v2/getComputedIndexHtml.d.ts +1 -1
  274. package/dist/v2/v2Build.d.ts +1 -1
  275. package/dist/v3/cleanRollupErrorMessage.d.ts +4 -0
  276. package/dist/v3/cleanRollupErrorMessage.js +9 -0
  277. package/dist/v3/computeBundleJSV3.d.ts +1 -2
  278. package/dist/v3/createVizContent.d.ts +1 -2
  279. package/dist/v3/setupV3Runtime.d.ts +15 -0
  280. package/dist/v3/setupV3Runtime.js +341 -0
  281. package/dist/v3/v3Build.d.ts +1 -2
  282. package/dist/v3/v3Build.js +1 -1
  283. package/dist/v3/vizLoad.js +1 -1
  284. package/dist/v4/index.d.ts +1 -1
  285. package/package.json +25 -16
package/README.md CHANGED
@@ -9,6 +9,252 @@ A powerful, flexible runtime environment for executing code sandboxes in the bro
9
9
 
10
10
  `@vizhub/runtime` intelligently detects the appropriate runtime version based on the provided files and generates executable HTML that can be used within an iframe's `srcdoc` attribute. It handles everything from simple HTML/JS/CSS combinations to complex module bundling, dependency resolution, and cross-viz imports.
11
11
 
12
+ ## Runtime Versions
13
+
14
+ The library automatically detects which runtime version to use based on the files provided:
15
+
16
+ - **v1**: When only `index.html` is present
17
+ - **v2**: When both `index.html` and `index.js` (or `index.jsx`) are present
18
+ - **v3**: When only `index.js` is present (no `index.html`)
19
+ - **v4**: When `index.html` contains ES module scripts with import maps
20
+
21
+ | Feature | **V1** | **V2** | **V3** | **V4** |
22
+ | --------------------- | ----------------- | ------------------------------ | --------------------------------- | ---------------------------- |
23
+ | **When Used** | Only `index.html` | `index.html` + `index.js/.jsx` | Only `index.js` (no `index.html`) | `index.html` with ES modules |
24
+ | **`index.html`** | User-provided | User-provided | Auto-generated | User-provided |
25
+ | **ES Modules** | ☐ | ✅ | ✅ | ✅ |
26
+ | **UMD Libraries** | ✅ | ✅ | ✅ | ☐ |
27
+ | **ESM Libraries** | ☐ | ☐ | ☐ | ✅ |
28
+ | **JSX Support** | ☐ | ✅ | ☐ | ✅ |
29
+ | **Svelte Support** | ☐ | ☐ | ✅ | ☐ |
30
+ | **Cross-Viz Imports** | ☐ | ☐ | ✅ | ☐ |
31
+ | **State Management** | ☐ | ☐ | ✅ | ☐ |
32
+ | **Import from CSV** | ☐ | ☐ | ✅ | ☐ |
33
+ | **`fetch` proxy** | ✅ | ✅ | ☐ | ✅ |
34
+ | **Best For** | Simple HTML demos | React with CDN deps | Svelte / reusable D3 | Modern module-based apps |
35
+
36
+ ## V1 Runtime
37
+
38
+ The V1 runtime is the simplest version, designed for basic HTML, CSS, and JavaScript projects. This runtime is automatically selected when your project contains only an `index.html` file.
39
+
40
+ ### How It Works
41
+
42
+ In V1 runtime:
43
+
44
+ - Your `index.html` file is executed directly in the browser
45
+ - You can include inline JavaScript and CSS within your HTML file
46
+ - The runtime provides fetch request proxying to handle cross-origin requests
47
+
48
+ ### Example Usage
49
+
50
+ As a VizHub user, you simply need to create an `index.html` file containing your entire project:
51
+
52
+ **index.html**
53
+
54
+ ```html
55
+ <!DOCTYPE html>
56
+ <html>
57
+ <head>
58
+ <style>
59
+ body {
60
+ font-family: sans-serif;
61
+ }
62
+ </style>
63
+ </head>
64
+ <body>
65
+ <h1>Hello World</h1>
66
+ <script>
67
+ console.log("Hello from V1 runtime!");
68
+ </script>
69
+ </body>
70
+ </html>
71
+ ```
72
+
73
+ V1 is ideal for simple demonstrations or when you want complete control over your HTML structure.
74
+
75
+ ## V2 Runtime
76
+
77
+ The V2 runtime introduces JavaScript bundling with Rollup, JSX support, and CDN-based dependency resolution. This runtime is automatically selected when your project contains both an `index.html` and an `index.js` (or `index.jsx`) file.
78
+
79
+ ### How It Works
80
+
81
+ In V2 runtime:
82
+
83
+ - Your JavaScript files are bundled together using Rollup
84
+ - Internally, a file named `bundle.js` is created
85
+ - The `index.html` file references this `bundle.js` file
86
+ - You can use ES6 modules to import/export code
87
+ - JSX syntax is supported for React development
88
+ - Dependencies listed in `package.json` are automatically resolved via CDNs (jsDelivr/unpkg)
89
+ - The bundled JavaScript is referenced in your HTML file
90
+
91
+ ### Example Usage
92
+
93
+ As a VizHub user, you'll typically create:
94
+
95
+ 1. An `index.html` file that references a `bundle.js` file
96
+ 2. An `index.js` (or `index.jsx`) file as your entry point
97
+ 3. Additional JavaScript modules as needed
98
+ 4. A `package.json` file to list dependencies
99
+
100
+ **index.html**
101
+
102
+ ```html
103
+ <!DOCTYPE html>
104
+ <html>
105
+ <body>
106
+ <div id="root"></div>
107
+ <script src="bundle.js"></script>
108
+ </body>
109
+ </html>
110
+ ```
111
+
112
+ **index.js**
113
+
114
+ ```javascript
115
+ import { render } from "./render";
116
+ render(document.getElementById("root"));
117
+ ```
118
+
119
+ **render.js**
120
+
121
+ ```javascript
122
+ export function render(element) {
123
+ element.innerHTML = "<h1>Hello from V2 runtime!</h1>";
124
+ }
125
+ ```
126
+
127
+ **package.json**
128
+
129
+ ```json
130
+ {
131
+ "dependencies": {
132
+ "d3": "7.8.5",
133
+ "react": "18.2.0",
134
+ "react-dom": "18.2.0"
135
+ }
136
+ }
137
+ ```
138
+
139
+ V2 is ideal for more complex projects that require modular JavaScript and external dependencies that provide UMD builds. Note that the V2 runtime does not support ESM builds for external dependencies (see V4 if you need this).
140
+
141
+ ## V3 Runtime
142
+
143
+ The V3 runtime provides advanced module bundling with Svelte support and cross-viz imports. This runtime is automatically selected when your project contains an `index.js` file but no `index.html` file.
144
+
145
+ ### How It Works
146
+
147
+ In V3 runtime:
148
+
149
+ - Your JavaScript modules are bundled together using Rollup
150
+ - A default HTML structure is automatically generated
151
+ - Svelte components are supported
152
+ - Cross-viz imports allow you to import code from other viz instances
153
+ - The runtime provides a built-in state management system
154
+
155
+ ### State Management in V3
156
+
157
+ V3 runtime includes a built-in state management system via the [unidirectional-data-flow](https://www.npmjs.com/package/unidirectional-data-flow) package ([GitHub](https://github.com/vizhub-core/unidirectional-data-flow)). This provides React-like state management capabilities with:
158
+
159
+ - A `main` entry point
160
+ - A minimal state management system based on `state` and `setState`
161
+ - Similar semantics to React's `useState` hook: `const [state, setState] = useState({})`
162
+ - Automatic re-rendering when state changes
163
+
164
+ ### The Problem: Re-using D3 Rendering Logic Across Frameworks
165
+
166
+ While frameworks like React, Svelte, Vue, and Angular offer state management and DOM manipulation solutions, D3 excels in data transformation and visualization, particularly with axes, transitions, and behaviors (e.g. zoom, drag, and brush). These D3 features require direct access to the DOM, making it challenging to replicate them effectively within frameworks.
167
+
168
+ ### The Solution: Unidirectional Data Flow
169
+
170
+ Unidirectional data flow is a pattern that can be cleanly invoked from multiple frameworks. In this paradigm, a single function is responsible for updating the DOM or rendering visuals based on a single, central state. As the state updates, the function re-renders the visualization in an idempotent manner, meaning it can run multiple times without causing side effects. Here's what the entry point function looks like for a D3-based visualization that uses unidirectional data flow:
171
+
172
+ **index.js**
173
+
174
+ ```js
175
+ export const main = (container, { state, setState }) => {
176
+ // Your reusable D3-based rendering logic goes here
177
+ };
178
+ ```
179
+
180
+ - **`container`**: A DOM element where the visualization will be rendered
181
+ - **`state`**: An object representing the current state of the application, initially empty
182
+ - **`setState`**: A function that updates the state using immutable update patterns
183
+
184
+ Whenever `setState` is invoked, `main` re-executes with the new state, ensuring that the rendering logic is both dynamic and responsive.
185
+
186
+ For cross-viz imports, you can reference other vizzes directly:
187
+
188
+ **example-with-import.js**
189
+
190
+ ```javascript
191
+ // Import from another viz using @username/vizIdOrSlug syntax
192
+ import { someFunction } from "@username/my-other-viz";
193
+ ```
194
+
195
+ V3 is ideal for modern JavaScript applications that benefit from automatic HTML structure generation and built-in state management. Additional features of V3 include:
196
+
197
+ - **Cross-Viz Imports**: Import code from other viz instances using `@username/vizIdOrSlug` syntax
198
+ - **Import from CSV**: Import CSV files directly into your viz
199
+
200
+ ## V4 Runtime
201
+
202
+ The V4 runtime leverages modern ES Modules with import maps for direct browser execution. This runtime is automatically selected when your project's `index.html` contains ES module scripts with import maps.
203
+
204
+ ### How It Works
205
+
206
+ In V4 runtime:
207
+
208
+ - Native browser ES modules are used without bundling
209
+ - Import maps allow you to specify module resolution directly in the browser
210
+ - Module paths can be aliased for cleaner imports
211
+ - External dependencies can be loaded directly from CDNs
212
+
213
+ ### Example Usage
214
+
215
+ As a VizHub user, you'll create an `index.html` file with import maps and ES module scripts:
216
+
217
+ **index.html**
218
+
219
+ ```html
220
+ <!DOCTYPE html>
221
+ <html>
222
+ <head>
223
+ <script type="importmap">
224
+ {
225
+ "imports": {
226
+ "utils": "./utils.js",
227
+ "d3": "https://cdn.jsdelivr.net/npm/d3@7.8.5/+esm"
228
+ }
229
+ }
230
+ </script>
231
+ </head>
232
+ <body>
233
+ <div id="app"></div>
234
+ <script type="module" src="index.js"></script>
235
+ </body>
236
+ </html>
237
+ ```
238
+
239
+ **index.js**
240
+
241
+ ```javascript
242
+ import { createApp } from "utils";
243
+ import * as d3 from "d3";
244
+
245
+ createApp(document.getElementById("app"));
246
+ ```
247
+
248
+ **utils.js**
249
+
250
+ ```javascript
251
+ export function createApp(element) {
252
+ element.innerHTML = "<h1>Hello from V4 runtime!</h1>";
253
+ }
254
+ ```
255
+
256
+ V4 is ideal for modern browsers with native ES module support and when you want direct control over module resolution.
257
+
12
258
  ## Key Features
13
259
 
14
260
  - **Multi-Version Runtime Support**
@@ -42,84 +288,87 @@ npm install @vizhub/runtime
42
288
  ### Basic Usage
43
289
 
44
290
  ```javascript
45
- import { buildHTML } from '@vizhub/runtime';
46
- import { rollup } from 'rollup';
291
+ import { buildHTML } from "@vizhub/runtime";
292
+ import { rollup } from "rollup";
47
293
 
48
294
  // Simple v1 runtime (HTML only)
49
295
  const html = await buildHTML({
50
296
  files: {
51
- 'index.html': '<html><body><h1>Hello World</h1></body></html>'
52
- }
297
+ "index.html":
298
+ "<html><body><h1>Hello World</h1></body></html>",
299
+ },
53
300
  });
54
301
 
55
302
  // v2 runtime with bundling
56
303
  const html = await buildHTML({
57
304
  files: {
58
- 'index.html': '<html><body><div id="root"></div><script src="bundle.js"></script></body></html>',
59
- 'index.js': 'import { message } from "./message"; console.log(message);',
60
- 'message.js': 'export const message = "Hello, bundled world!";'
305
+ "index.html":
306
+ '<html><body><div id="root"></div><script src="bundle.js"></script></body></html>',
307
+ "index.js":
308
+ 'import { message } from "./message"; console.log(message);',
309
+ "message.js":
310
+ 'export const message = "Hello, bundled world!";',
61
311
  },
62
- rollup
312
+ rollup,
63
313
  });
64
314
 
65
315
  // Use the generated HTML in an iframe
66
- const iframe = document.createElement('iframe');
316
+ const iframe = document.createElement("iframe");
67
317
  iframe.srcdoc = html;
68
318
  document.body.appendChild(iframe);
69
319
  ```
70
320
 
71
- ### Runtime Versions
72
-
73
- The library automatically detects which runtime version to use based on the files provided:
74
-
75
- - **v1**: When only `index.html` is present
76
- - **v2**: When both `index.html` and `index.js` (or `index.jsx`) are present
77
- - **v3**: When only `index.js` is present (no `index.html`)
78
- - **v4**: When `index.html` contains ES module scripts with import maps
79
-
80
321
  ### Advanced Usage: v3 Runtime with Cross-Viz Imports
81
322
 
82
323
  ```javascript
83
- import { buildHTML, createVizCache, createSlugCache } from '@vizhub/runtime';
84
- import { rollup } from 'rollup';
85
- import { compile } from 'svelte/compiler';
324
+ import {
325
+ buildHTML,
326
+ createVizCache,
327
+ createSlugCache,
328
+ } from "@vizhub/runtime";
329
+ import { rollup } from "rollup";
330
+ import { compile } from "svelte/compiler";
86
331
 
87
332
  // Create caches for viz content and slug resolution
88
333
  const vizCache = createVizCache({
89
334
  initialContents: [
90
335
  {
91
- id: 'viz-123',
336
+ id: "viz-123",
92
337
  files: {
93
- 'file1': { name: 'index.js', text: 'export const value = 42;' }
94
- }
95
- }
338
+ file1: {
339
+ name: "index.js",
340
+ text: "export const value = 42;",
341
+ },
342
+ },
343
+ },
96
344
  ],
97
345
  handleCacheMiss: async (vizId) => {
98
346
  // Fetch viz content from your backend
99
347
  return await fetchVizContent(vizId);
100
- }
348
+ },
101
349
  });
102
350
 
103
351
  const slugCache = createSlugCache({
104
352
  initialMappings: {
105
- 'username/my-viz': 'viz-123'
353
+ "username/my-viz": "viz-123",
106
354
  },
107
355
  handleCacheMiss: async (slug) => {
108
356
  // Resolve slug to vizId from your backend
109
357
  return await resolveSlug(slug);
110
- }
358
+ },
111
359
  });
112
360
 
113
361
  // Build HTML with cross-viz imports
114
362
  const html = await buildHTML({
115
363
  files: {
116
- 'index.js': 'import { value } from "@username/my-viz"; console.log(value);'
364
+ "index.js":
365
+ 'import { value } from "@username/my-viz"; console.log(value);',
117
366
  },
118
367
  rollup,
119
368
  vizCache,
120
- vizId: 'current-viz-id',
369
+ vizId: "current-viz-id",
121
370
  slugCache,
122
- getSvelteCompiler: async () => compile
371
+ getSvelteCompiler: async () => compile,
123
372
  });
124
373
  ```
125
374
 
@@ -157,103 +406,6 @@ Creates a cache for slug resolution.
157
406
  - **initialMappings**: `Record<string, string>` - Initial slug to vizId mappings
158
407
  - **handleCacheMiss**: `(slug: string) => Promise<string>` - Function to handle cache misses
159
408
 
160
- ## Examples
161
-
162
- ### v1: Simple HTML
163
-
164
- ```javascript
165
- const html = await buildHTML({
166
- files: {
167
- 'index.html': `
168
- <!DOCTYPE html>
169
- <html>
170
- <head>
171
- <style>
172
- body { font-family: sans-serif; }
173
- </style>
174
- </head>
175
- <body>
176
- <h1>Hello World</h1>
177
- <script>
178
- console.log('Hello from v1 runtime!');
179
- </script>
180
- </body>
181
- </html>
182
- `
183
- }
184
- });
185
- ```
186
-
187
- ### v2: Bundled JavaScript
188
-
189
- ```javascript
190
- const html = await buildHTML({
191
- files: {
192
- 'index.html': `
193
- <!DOCTYPE html>
194
- <html>
195
- <body>
196
- <div id="root"></div>
197
- <script src="bundle.js"></script>
198
- </body>
199
- </html>
200
- `,
201
- 'index.js': `
202
- import { render } from './render';
203
- render(document.getElementById('root'));
204
- `,
205
- 'render.js': `
206
- export function render(element) {
207
- element.innerHTML = '<h1>Hello from v2 runtime!</h1>';
208
- }
209
- `,
210
- 'package.json': JSON.stringify({
211
- dependencies: {
212
- 'd3': '7.8.5'
213
- }
214
- })
215
- },
216
- rollup
217
- });
218
- ```
219
-
220
- ### v4: ES Modules with Import Maps
221
-
222
- ```javascript
223
- const html = await buildHTML({
224
- files: {
225
- 'index.html': `
226
- <!DOCTYPE html>
227
- <html>
228
- <head>
229
- <script type="importmap">
230
- {
231
- "imports": {
232
- "utils": "./utils.js"
233
- }
234
- }
235
- </script>
236
- </head>
237
- <body>
238
- <div id="app"></div>
239
- <script type="module" src="index.js"></script>
240
- </body>
241
- </html>
242
- `,
243
- 'index.js': `
244
- import { createApp } from 'utils';
245
- createApp(document.getElementById('app'));
246
- `,
247
- 'utils.js': `
248
- export function createApp(element) {
249
- element.innerHTML = '<h1>Hello from v4 runtime!</h1>';
250
- }
251
- `
252
- },
253
- rollup
254
- });
255
- ```
256
-
257
409
  ## Development
258
410
 
259
411
  ### Setup
package/dist/buildHTML.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ import type { RollupBuild, RollupOptions } from "rollup";
2
+ import { VizCache } from "./v3/vizCache";
3
+ import { SlugCache } from "./v3/slugCache";
4
+ import { SvelteCompiler } from "./v3/transformSvelte";
5
+ import { FileCollection } from "@vizhub/viz-types";
6
+ export declare const buildHTML: ({ files, rollup, enableSourcemap, vizCache, vizId, slugCache, getSvelteCompiler, }: {
7
+ files?: FileCollection;
8
+ rollup?: (options: RollupOptions) => Promise<RollupBuild>;
9
+ enableSourcemap?: boolean;
10
+ vizCache?: VizCache;
11
+ vizId?: string;
12
+ slugCache?: SlugCache;
13
+ getSvelteCompiler?: () => Promise<SvelteCompiler>;
14
+ }) => Promise<string>;
package/dist/buildHTML.js ADDED
@@ -0,0 +1,67 @@
1
+ import { magicSandbox } from "magic-sandbox";
2
+ import { determineRuntimeVersion } from "./determineRuntimeVersion";
3
+ import { v2Build } from "./v2";
4
+ import { v3Build } from "./v3";
5
+ import { v4Build } from "./v4";
6
+ import { createVizCache } from "./v3/vizCache";
7
+ import { createVizContent } from "./v3/createVizContent";
8
+ import { vizContentToFileCollection } from "./utils/vizContentToFileCollection";
9
+ const DEBUG = false;
10
+ export const buildHTML = async ({ files, rollup, enableSourcemap = true, vizCache, vizId, slugCache, getSvelteCompiler, }) => {
11
+ if (!files && !vizCache) {
12
+ throw new Error("Either files or vizCache is required");
13
+ }
14
+ if (!files && vizCache && !vizId) {
15
+ throw new Error("vizId is required when using vizCache");
16
+ }
17
+ if (!files && vizCache && vizId) {
18
+ files = vizContentToFileCollection(await vizCache.get(vizId));
19
+ }
20
+ if (!files) {
21
+ throw new Error("Upable to extract viz files");
22
+ }
23
+ const version = determineRuntimeVersion(files);
24
+ DEBUG && console.log("[buildHTML] version:", version);
25
+ if (version === "v1") {
26
+ return magicSandbox(files);
27
+ }
28
+ if (version === "v2") {
29
+ if (!rollup) {
30
+ throw new Error("Rollup is required for v2 runtime");
31
+ }
32
+ return magicSandbox(await v2Build({ files, rollup, enableSourcemap }));
33
+ }
34
+ if (version === "v3") {
35
+ if (!rollup) {
36
+ throw new Error("Rollup is required for v3 runtime");
37
+ }
38
+ if (!vizCache && !vizId) {
39
+ const vizContent = createVizContent(files);
40
+ vizId = vizContent.id;
41
+ vizCache = createVizCache({
42
+ initialContents: [vizContent],
43
+ handleCacheMiss: async () => {
44
+ throw new Error("Cache miss handler not implemented");
45
+ },
46
+ });
47
+ }
48
+ if (!vizCache || !vizId) {
49
+ throw new Error("vizCache and vizId are required for v3 runtime");
50
+ }
51
+ return await v3Build({
52
+ files,
53
+ rollup,
54
+ vizCache,
55
+ vizId,
56
+ slugCache,
57
+ getSvelteCompiler,
58
+ });
59
+ }
60
+ if (version === "v4") {
61
+ if (!rollup) {
62
+ throw new Error("Rollup is required for v4 runtime");
63
+ }
64
+ return magicSandbox(await v4Build({ files, rollup, enableSourcemap }));
65
+ }
66
+ throw new Error(`Unsupported runtime version: ${version}`);
67
+ };
package/dist/cjs/buildHTML.js ADDED
@@ -0,0 +1,71 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.buildHTML = void 0;
4
+ const magic_sandbox_1 = require("magic-sandbox");
5
+ const determineRuntimeVersion_1 = require("./determineRuntimeVersion");
6
+ const v2_1 = require("./v2");
7
+ const v3_1 = require("./v3");
8
+ const v4_1 = require("./v4");
9
+ const vizCache_1 = require("./v3/vizCache");
10
+ const createVizContent_1 = require("./v3/createVizContent");
11
+ const vizContentToFileCollection_1 = require("./utils/vizContentToFileCollection");
12
+ const DEBUG = false;
13
+ const buildHTML = async ({ files, rollup, enableSourcemap = true, vizCache, vizId, slugCache, getSvelteCompiler, }) => {
14
+ if (!files && !vizCache) {
15
+ throw new Error("Either files or vizCache is required");
16
+ }
17
+ if (!files && vizCache && !vizId) {
18
+ throw new Error("vizId is required when using vizCache");
19
+ }
20
+ if (!files && vizCache && vizId) {
21
+ files = (0, vizContentToFileCollection_1.vizContentToFileCollection)(await vizCache.get(vizId));
22
+ }
23
+ if (!files) {
24
+ throw new Error("Upable to extract viz files");
25
+ }
26
+ const version = (0, determineRuntimeVersion_1.determineRuntimeVersion)(files);
27
+ DEBUG && console.log("[buildHTML] version:", version);
28
+ if (version === "v1") {
29
+ return (0, magic_sandbox_1.magicSandbox)(files);
30
+ }
31
+ if (version === "v2") {
32
+ if (!rollup) {
33
+ throw new Error("Rollup is required for v2 runtime");
34
+ }
35
+ return (0, magic_sandbox_1.magicSandbox)(await (0, v2_1.v2Build)({ files, rollup, enableSourcemap }));
36
+ }
37
+ if (version === "v3") {
38
+ if (!rollup) {
39
+ throw new Error("Rollup is required for v3 runtime");
40
+ }
41
+ if (!vizCache && !vizId) {
42
+ const vizContent = (0, createVizContent_1.createVizContent)(files);
43
+ vizId = vizContent.id;
44
+ vizCache = (0, vizCache_1.createVizCache)({
45
+ initialContents: [vizContent],
46
+ handleCacheMiss: async () => {
47
+ throw new Error("Cache miss handler not implemented");
48
+ },
49
+ });
50
+ }
51
+ if (!vizCache || !vizId) {
52
+ throw new Error("vizCache and vizId are required for v3 runtime");
53
+ }
54
+ return await (0, v3_1.v3Build)({
55
+ files,
56
+ rollup,
57
+ vizCache,
58
+ vizId,
59
+ slugCache,
60
+ getSvelteCompiler,
61
+ });
62
+ }
63
+ if (version === "v4") {
64
+ if (!rollup) {
65
+ throw new Error("Rollup is required for v4 runtime");
66
+ }
67
+ return (0, magic_sandbox_1.magicSandbox)(await (0, v4_1.v4Build)({ files, rollup, enableSourcemap }));
68
+ }
69
+ throw new Error(`Unsupported runtime version: ${version}`);
70
+ };
71
+ exports.buildHTML = buildHTML;