visualifyjs 2.5.3 → 3.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 (252) hide show
  1. package/.claude/mem/TIMELINE.md +36 -0
  2. package/.claude/mem/notes/2026-02-11-3d-visualization-docs-fix-external-script-solution.md +24 -0
  3. package/.claude/mem/notes/2026-02-11-3d-visualization-docs-fix-session-summary.md +43 -0
  4. package/.claude/mem/notes/2026-02-11-cli-fix-editor-command-alias.md +26 -0
  5. package/.claude/mem/notes/2026-02-11-phase-3-developer-experience-completed.md +51 -0
  6. package/.claude/mem/notes/2026-02-11-phase-4-web-workers-implementation-complete.md +59 -0
  7. package/.claude/mem/notes/2026-02-11-visualify-phase-2-3d-visualization-complete.md +50 -0
  8. package/.claude/mem/notes/2026-02-11-visualify-phase-2-committed-ready-for-phase-3.md +33 -0
  9. package/.claude/mem/notes/2026-02-11-visualify-phase-3-complete-developer-experience.md +52 -0
  10. package/.claude/mem/notes/2026-02-11-visualify-repository-cleanup-complete.md +28 -0
  11. package/.claude/mem/notes/2026-02-18-codebase-cleanup-docsify-plugin-documentation.md +37 -0
  12. package/.claude/mem/notes/2026-02-19-css-grid-layout-fix-displaycontents-on-vcontroller.md +18 -0
  13. package/.claude/mem/notes/2026-02-19-docsify-plugin-fixes-latex-and-visualify-code-bloc.md +26 -0
  14. package/.claude/mem/notes/2026-02-19-page-mode-docs-update-decisions.md +23 -0
  15. package/.claude/mem/notes/2026-02-19-react-context-infinite-re-render-loop-fix-pattern.md +31 -0
  16. package/.claude/mem/notes/2026-02-19-version-300-bump-and-build-fixes.md +32 -0
  17. package/.claude/mem/notes/2026-02-19-visualify-build-deployment-architecture-bug-fixes.md +25 -0
  18. package/.claude/mem/notes/2026-02-19-visualify-dist-iife-self-contained-build-config.md +30 -0
  19. package/.claude/mem/notes/2026-02-19-visualify-infinite-loop-i18n-fixes.md +31 -0
  20. package/.claude/mem/notes/2026-02-19-visualify-v3-bundle-splitting-docs-restructuring.md +32 -0
  21. package/.claude/mem/notes/2026-02-20-bundle-externalization-final-architecture.md +29 -0
  22. package/.claude/mem/notes/2026-02-20-chromium-page-fix-unstable-keys-and-double-event-b.md +27 -0
  23. package/.claude/mem/notes/2026-02-20-console-cleanup-bundle-optimization-commit.md +20 -0
  24. package/.claude/mem/notes/2026-02-20-dotbio-dot-plot-fix-useeffect-dependency.md +21 -0
  25. package/.claude/mem/notes/2026-02-20-public-folder-cleanup-and-readme-rewrite.md +25 -0
  26. package/.claude/mem/notes/2026-02-20-v300-release-and-beta-channel-strategy.md +29 -0
  27. package/.claude/mem/notes/2026-02-20-visium-background-image-unknown-legend-fix.md +19 -0
  28. package/.claude/mem/notes/2026-02-20-visualify-cdn-loader-bundle-externalization.md +34 -0
  29. package/.claude/mem/sessions/session-2026-02-20-031524.md +54 -0
  30. package/.claude/settings.local.json +21 -0
  31. package/.github/workflows/static.yml.bak +51 -51
  32. package/.sisyphus/boulder.json +65 -0
  33. package/.sisyphus/plans/phase-4-advanced-optimizations.md +217 -0
  34. package/LICENSE +674 -674
  35. package/README.md +94 -59
  36. package/config-overrides.js +31 -31
  37. package/dist/stats.html +4949 -0
  38. package/dist/visualify-3d.esm.js +1 -0
  39. package/dist/visualify-3d.js +1 -0
  40. package/dist/visualify-core.esm.js +1 -0
  41. package/dist/visualify-core.js +1 -0
  42. package/dist/visualify-docs.esm.js +1 -0
  43. package/dist/visualify-docs.js +1 -0
  44. package/dist/visualify-loader.js +1 -0
  45. package/dist/visualify-pages.esm.js +1 -0
  46. package/dist/visualify-pages.js +1 -0
  47. package/dist/visualify-portal.esm.js +1 -0
  48. package/dist/visualify-portal.js +1 -0
  49. package/dist/visualify-shared.js +26571 -0
  50. package/dist/visualify.js +1 -188
  51. package/docs/CHANGELOG.md +148 -0
  52. package/docs/cli/commands.md +513 -0
  53. package/docs/configuration/visualify-json.md +474 -0
  54. package/docs/docs/3d-visualization.md +374 -0
  55. package/docs/docs/CLI.md +303 -34
  56. package/docs/docs/README.md +65 -65
  57. package/docs/docs/Rechart/bar.md +190 -190
  58. package/docs/docs/Rechart/funnel.md +241 -193
  59. package/docs/docs/Rechart/line.md +355 -355
  60. package/docs/docs/Rechart/pie.md +225 -225
  61. package/docs/docs/Rechart/radar.md +253 -253
  62. package/docs/docs/Rechart/scatter.md +298 -0
  63. package/docs/docs/_404.md +51 -51
  64. package/docs/docs/_coverpage.md +11 -11
  65. package/docs/docs/_sidebar.md +54 -43
  66. package/docs/docs/components/dotBio.md +87 -34
  67. package/docs/docs/components/echart.md +171 -82
  68. package/docs/docs/components/html.md +61 -34
  69. package/docs/docs/components/macaron.md +156 -145
  70. package/docs/docs/components/markdown.md +42 -0
  71. package/docs/docs/components/more.md +183 -142
  72. package/docs/docs/components/plotly.md +132 -62
  73. package/docs/docs/components/scatterL.md +171 -70
  74. package/docs/docs/components/visium.md +112 -57
  75. package/docs/docs/configuration.md +121 -123
  76. package/docs/docs/deploy.md +31 -31
  77. package/docs/docs/docsify-plugin.md +655 -0
  78. package/docs/docs/hmr.md +165 -0
  79. package/docs/docs/i18n.md +332 -0
  80. package/docs/docs/log.md +30 -1
  81. package/docs/docs/more-pages.md +23 -23
  82. package/docs/docs/quickstart.md +148 -119
  83. package/docs/docs/rechart-attributes.md +74 -74
  84. package/docs/docs/rechart-basic-usage.md +160 -162
  85. package/docs/docs/theme.md +5 -5
  86. package/docs/docs/typescript.md +306 -0
  87. package/docs/docs/visual-editor.md +359 -0
  88. package/docs/index.html +85 -71
  89. package/docs/manifest.json +23 -23
  90. package/docs/migration/v3-migration.md +392 -0
  91. package/docs/static/css/fluff-stuff.css +169 -169
  92. package/docs/static/css/font-awesome.min.css +4 -4
  93. package/docs/static/css/visualify.css +6 -25
  94. package/docs/static/js/3d-viz-examples.js +181 -0
  95. package/docs/static/js/configuration.js +630 -448
  96. package/docs/static/js/visualify.js +1 -188
  97. package/package.json +106 -84
  98. package/rollup.config.mjs +766 -76
  99. package/src/_css/404.css +115 -115
  100. package/src/_css/App.css +37 -37
  101. package/src/_css/autoSuggestion.css +26 -26
  102. package/src/_css/circular-progress.css +32 -32
  103. package/src/_css/index.css +36 -36
  104. package/src/_css/modern.css +350 -25
  105. package/src/_media/corner.svg +8 -8
  106. package/src/_media/download.svg +3 -3
  107. package/src/_media/logo.svg +14 -14
  108. package/src/_test/App.test.js +15 -15
  109. package/src/_utils/reportWebVitals.js +13 -13
  110. package/src/a11y/README.md +177 -0
  111. package/src/a11y/aria-labels.js +339 -0
  112. package/src/a11y/color-contrast.js +535 -0
  113. package/src/a11y/index.js +197 -0
  114. package/src/a11y/keyboard-nav.js +523 -0
  115. package/src/a11y/styles.css +165 -0
  116. package/src/cli/commands/dev.js +214 -0
  117. package/src/cli/commands/docs.js +521 -0
  118. package/src/cli/commands/edit.js +379 -0
  119. package/src/cli/commands/init.js +213 -0
  120. package/src/cli/commands/portal.js +236 -0
  121. package/src/cli/dev-server.js +530 -0
  122. package/src/cli/hmr.js +456 -0
  123. package/src/cli/index.js +180 -0
  124. package/src/cli/utils/config.js +207 -0
  125. package/src/cli/utils/logger.js +241 -0
  126. package/src/config/defaults.ts +122 -0
  127. package/src/config/index.ts +72 -0
  128. package/src/config/loader.ts +478 -0
  129. package/src/config/schema.ts +227 -0
  130. package/src/config/validator.ts +337 -0
  131. package/src/core/appContext.js +34 -27
  132. package/src/core/components/Bar.js +383 -0
  133. package/src/core/components/Bar3D.js +473 -0
  134. package/src/core/components/LargeDatasetChart.js +296 -0
  135. package/src/core/components/Line3D.js +310 -0
  136. package/src/core/components/Scatter.js +392 -188
  137. package/src/core/components/Scatter3D.js +455 -0
  138. package/src/core/components/ScatterBio.js +601 -572
  139. package/src/core/components/Surface3D.js +326 -0
  140. package/src/core/components/ThreeCustom.js +648 -0
  141. package/src/core/components/ThreeScene.js +459 -0
  142. package/src/core/components/VisiumPlot.js +191 -165
  143. package/src/core/components/browser.js +42 -42
  144. package/src/core/components/dotplot.js +413 -413
  145. package/src/core/components/html.js +29 -29
  146. package/src/core/components/list.js +178 -178
  147. package/src/core/components/macaron.js +206 -201
  148. package/src/core/components/markdown.js +56 -56
  149. package/src/core/components/parser.scatterBio.js +582 -579
  150. package/src/core/components/ratio.js +82 -80
  151. package/src/core/components/scatterL.js +206 -173
  152. package/src/core/components/searchbar.js +156 -131
  153. package/src/core/components/selection.js +310 -193
  154. package/src/core/components/timeline.js +236 -281
  155. package/src/core/components/visium.js +114 -97
  156. package/src/core/data-processor.js +413 -0
  157. package/src/core/fetch/condfetch.js +82 -82
  158. package/src/core/fetch/fetch.js +92 -92
  159. package/src/core/fetch/json.js +29 -29
  160. package/src/core/fetch/vfetch.js +42 -42
  161. package/src/core/hmr-client.js +724 -0
  162. package/src/core/liveEditor.js +44 -44
  163. package/src/core/modules/codeEditorWithPreview.js +104 -104
  164. package/src/core/modules/echarts/common.js +20 -20
  165. package/src/core/modules/echarts/gl.js +228 -0
  166. package/src/core/modules/echarts/presetHandler.js +41 -41
  167. package/src/core/modules/echarts/presets/esodev.chromium.js +172 -172
  168. package/src/core/modules/echarts/presets/esodev.codex.js +130 -130
  169. package/src/core/modules/echarts/presets/esodev.visium.js +123 -123
  170. package/src/core/modules/echarts/presets/mmtrbc.js +186 -186
  171. package/src/core/modules/echarts.js +70 -71
  172. package/src/core/modules/echartsUtils.js +43 -43
  173. package/src/core/modules/echartswitcher.js +227 -152
  174. package/src/core/modules/replotly/presetHandler.js +24 -24
  175. package/src/core/modules/replotly/presets/minimum.js +18 -18
  176. package/src/core/modules/replotly/presets/mmtrbc.dot.js +114 -114
  177. package/src/core/modules/replotly/presets/mmtrbc.violin.js +100 -100
  178. package/src/core/modules/replotly.js +74 -71
  179. package/src/core/modules/threejs/Camera.js +373 -0
  180. package/src/core/modules/threejs/Lighting.js +459 -0
  181. package/src/core/modules/threejs/Renderer.js +364 -0
  182. package/src/core/modules/threejs/Scene.js +266 -0
  183. package/src/core/modules/threejs/index.js +155 -0
  184. package/src/core/pages/404.js +50 -50
  185. package/src/core/pages/error.js +27 -27
  186. package/src/core/pages/jsonPage.js +62 -62
  187. package/src/core/pages/loading.js +44 -44
  188. package/src/core/parser/echart.data.js +204 -183
  189. package/src/core/parser/echart.features.js +125 -125
  190. package/src/core/parser/echart.general.js +147 -143
  191. package/src/core/parser/echart.hilbert.js +57 -57
  192. package/src/core/parser/echart.parser.js +210 -210
  193. package/src/core/parser/echart.series.js +67 -67
  194. package/src/core/parser/echart.types.js +76 -76
  195. package/src/core/parser/plotly.config.js +10 -10
  196. package/src/core/parser/plotly.data.js +132 -132
  197. package/src/core/parser/plotly.layout.js +9 -9
  198. package/src/core/parser/plotly.violin.js +18 -18
  199. package/src/core/recharts.js +361 -62
  200. package/src/core/router/alias.js +49 -49
  201. package/src/core/router/jsonRouter.js +31 -31
  202. package/src/core/themes/modern.js +32 -32
  203. package/src/core/themes/themeSelector.js +33 -33
  204. package/src/core/visualify.js +213 -47
  205. package/src/core/widgets/circularProgress.js +23 -23
  206. package/src/core/widgets/controller.js +116 -83
  207. package/src/core/widgets/errorBoundary.js +36 -36
  208. package/src/core/widgets/footer.js +185 -177
  209. package/src/core/widgets/header.js +238 -234
  210. package/src/core/widgets/layout/Grid.js +31 -31
  211. package/src/core/widgets/layout.js +36 -36
  212. package/src/core/widgets/mapping.js +56 -42
  213. package/src/core/workers/data-worker.js +349 -0
  214. package/src/core/workers/worker-pool.js +396 -0
  215. package/src/docsify/bundle.js +215 -0
  216. package/src/docsify/markdown.js +271 -0
  217. package/src/docsify/plugin.js +268 -0
  218. package/src/editor/README.md +172 -0
  219. package/src/editor/components/ChartBuilder.jsx +341 -0
  220. package/src/editor/components/ChartTypeSidebar.jsx +91 -0
  221. package/src/editor/components/Editor.jsx +367 -0
  222. package/src/editor/components/Preview.jsx +446 -0
  223. package/src/editor/components/PropertyPanel.jsx +468 -0
  224. package/src/editor/components/StatusBar.jsx +85 -0
  225. package/src/editor/context/EditorContext.js +248 -0
  226. package/src/editor/hooks/useDebounce.js +32 -0
  227. package/src/editor/index.js +315 -0
  228. package/src/editor/styles/editor.css +637 -0
  229. package/src/editor/utils/chartValidator.js +263 -0
  230. package/src/entries/charts3d.js +70 -0
  231. package/src/entries/core.js +78 -0
  232. package/src/entries/docs.js +154 -0
  233. package/src/entries/pages.js +93 -0
  234. package/src/entries/portal.js +204 -0
  235. package/src/entries/shared.js +50 -0
  236. package/src/i18n/formatters.js +455 -0
  237. package/src/i18n/index.js +169 -0
  238. package/src/i18n/locales/ar.json +137 -0
  239. package/src/i18n/locales/de.json +137 -0
  240. package/src/i18n/locales/en.json +137 -0
  241. package/src/i18n/locales/es.json +137 -0
  242. package/src/i18n/locales/he.json +137 -0
  243. package/src/i18n/locales/zh.json +137 -0
  244. package/src/i18n/rtl.css +183 -0
  245. package/src/index.js +82 -62
  246. package/src/loader.js +103 -0
  247. package/src/setupTests.js +5 -5
  248. package/tsconfig.json +51 -0
  249. package/types/charts.d.ts +569 -0
  250. package/types/components.d.ts +441 -0
  251. package/types/config.d.ts +199 -0
  252. package/types/index.d.ts +353 -0
package/docs/migration/v3-migration.md ADDED
@@ -0,0 +1,392 @@
1
+ # Migration Guide: Visualify.js v3.0.0
2
+
3
+ This guide will help you migrate from Visualify.js v2.x to v3.0.0. Version 3.0.0 introduces significant improvements including a unified CLI, configuration file support, and a cleaner command structure.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Overview](#overview)
8
+ - [From `@visualify/cli`](#from-visualifycli)
9
+ - [From `window.$visualify`](#from-windowvisualify)
10
+ - [Breaking Changes](#breaking-changes)
11
+ - [Troubleshooting](#troubleshooting)
12
+
13
+ ---
14
+
15
+ ## Overview
16
+
17
+ ### What's Changing and Why
18
+
19
+ Visualify.js v3.0.0 represents a major architectural improvement focused on:
20
+
21
+ 1. **Unified Package**: The CLI has been merged into the core `visualifyjs` package. No more separate `@visualify/cli` installation.
22
+ 2. **Configuration File**: Support for `visualify.json` configuration file instead of inline JavaScript configuration.
23
+ 3. **Command Restructure**: Cleaner command namespace with `docs` and `portal` subcommands.
24
+ 4. **Auto-Detection**: The `visualify dev` command now auto-detects your project type.
25
+
26
+ ### Timeline and Deprecation Notice
27
+
28
+ | Version | Status | Notes |
29
+ |---------|--------|-------|
30
+ | v2.x | Maintenance mode | Bug fixes only until 2026-06-01 |
31
+ | v3.0.0 | Current | Active development |
32
+ | v2.x | End of life | 2026-12-01 - No more updates |
33
+
34
+ **Important**: The `@visualify/cli` package is now deprecated and will not receive updates after 2026-06-01.
35
+
36
+ ### Quick Start for New Users
37
+
38
+ If you're starting a new project:
39
+
40
+ ```bash
41
+ # Install the new unified package
42
+ npm i -g visualifyjs
43
+
44
+ # Initialize a new docs project
45
+ visualify init docs
46
+
47
+ # Or initialize a portal project
48
+ visualify init portal
49
+
50
+ # Start development server
51
+ visualify dev
52
+ ```
53
+
54
+ ---
55
+
56
+ ## From `@visualify/cli`
57
+
58
+ ### Installation Change
59
+
60
+ **Before (v2.x):**
61
+ ```bash
62
+ npm i -g @visualify/cli
63
+ ```
64
+
65
+ **After (v3.0.0):**
66
+ ```bash
67
+ npm i -g visualifyjs
68
+ ```
69
+
70
+ ### Command Mapping
71
+
72
+ | Old Command | New Command | Notes |
73
+ |-------------|-------------|-------|
74
+ | `visualify init [path]` | `visualify init docs [path]` or `visualify init portal [path]` | Must specify template type |
75
+ | `visualify serve [path]` | `visualify dev [path]` | Auto-detects mode |
76
+ | `visualify start [path]` | `visualify dev portal [path]` | Explicit portal mode |
77
+ | `visualify load-json <path>` | `visualify portal load-json <path>` | Now a subcommand |
78
+ | `visualify mapping [options] <path>` | `visualify portal mapping [options] <path>` | Now a subcommand |
79
+ | `visualify rtree2d [options] <path>` | `visualify portal rtree2d [options] <path>` | Now a subcommand |
80
+
81
+ ### Examples
82
+
83
+ #### Initializing a New Project
84
+
85
+ **Before:**
86
+ ```bash
87
+ visualify init ./my-project
88
+ ```
89
+
90
+ **After:**
91
+ ```bash
92
+ # For documentation projects
93
+ visualify init docs ./my-project
94
+
95
+ # For data portal projects
96
+ visualify init portal ./my-project
97
+
98
+ # For both
99
+ visualify init full ./my-project
100
+ ```
101
+
102
+ #### Running Development Server
103
+
104
+ **Before:**
105
+ ```bash
106
+ # For docs
107
+ visualify serve ./docs
108
+
109
+ # For portal
110
+ visualify start ./portal
111
+ ```
112
+
113
+ **After:**
114
+ ```bash
115
+ # Auto-detects mode from visualify.json or project structure
116
+ visualify dev
117
+
118
+ # Explicit docs mode
119
+ visualify dev docs
120
+
121
+ # Explicit portal mode
122
+ visualify dev portal
123
+ ```
124
+
125
+ #### Portal Data Commands
126
+
127
+ **Before:**
128
+ ```bash
129
+ visualify load-json ./data/points.json
130
+ visualify mapping --key id ./data/mapping.csv
131
+ visualify rtree2d --output ./rtree ./data/spatial.json
132
+ ```
133
+
134
+ **After:**
135
+ ```bash
136
+ visualify portal load-json ./data/points.json
137
+ visualify portal mapping --key id ./data/mapping.csv
138
+ visualify portal rtree2d --output ./rtree ./data/spatial.json
139
+ ```
140
+
141
+ ---
142
+
143
+ ## From `window.$visualify`
144
+
145
+ ### Configuration File Migration
146
+
147
+ **Before (inline HTML configuration):**
148
+ ```html
149
+ <!DOCTYPE html>
150
+ <html>
151
+ <head>
152
+ <meta charset="UTF-8">
153
+ <title>My Visualify Site</title>
154
+ </head>
155
+ <body>
156
+ <div id="root"></div>
157
+ <script>
158
+ window.$visualify = {
159
+ mode: 'pages',
160
+ el: '#root',
161
+ theme: 'modern',
162
+ homepage: 'home.json',
163
+ repo: 'https://github.com/username/repo',
164
+ alias: {
165
+ '/docsify': 'https://docsify.js.org/#/configuration?id=alias'
166
+ }
167
+ };
168
+ </script>
169
+ <script src="https://cdn.jsdelivr.net/npm/visualifyjs"></script>
170
+ </body>
171
+ </html>
172
+ ```
173
+
174
+ **After (visualify.json configuration):**
175
+ ```json
176
+ {
177
+ "version": "3.0.0",
178
+ "mode": "portal",
179
+ "el": "#root",
180
+ "portal": {
181
+ "homepage": "home.json",
182
+ "theme": "modern",
183
+ "repo": "https://github.com/username/repo",
184
+ "alias": {
185
+ "/docsify": "https://docsify.js.org/#/configuration?id=alias"
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ And your `index.html` becomes simpler:
192
+ ```html
193
+ <!DOCTYPE html>
194
+ <html>
195
+ <head>
196
+ <meta charset="UTF-8">
197
+ <title>My Visualify Site</title>
198
+ </head>
199
+ <body>
200
+ <div id="root"></div>
201
+ <script src="https://cdn.jsdelivr.net/npm/visualifyjs"></script>
202
+ </body>
203
+ </html>
204
+ ```
205
+
206
+ ### Mode Changes
207
+
208
+ | Old Mode | New Mode | Notes |
209
+ |----------|----------|-------|
210
+ | `pages` | `portal` | Renamed for clarity |
211
+ | `charts` | `docs` | Renamed to reflect documentation focus |
212
+
213
+ **Before:**
214
+ ```js
215
+ window.$visualify = {
216
+ mode: 'pages', // or 'charts'
217
+ // ...
218
+ };
219
+ ```
220
+
221
+ **After:**
222
+ ```json
223
+ {
224
+ "version": "3.0.0",
225
+ "mode": "portal"
226
+ }
227
+ ```
228
+
229
+ Or for documentation mode:
230
+ ```json
231
+ {
232
+ "version": "3.0.0",
233
+ "mode": "docs"
234
+ }
235
+ ```
236
+
237
+ ### Property Mapping
238
+
239
+ | Old Property | New Location | Notes |
240
+ |--------------|--------------|-------|
241
+ | `mode` | `mode` | Now uses `"portal"` or `"docs"` |
242
+ | `el` | `el` | Unchanged |
243
+ | `theme` | `portal.theme` / `docs.theme` | Mode-specific |
244
+ | `homepage` | `portal.homepage` / `docs.homepage` | Mode-specific |
245
+ | `repo` | `portal.repo` / `docs.repo` | Mode-specific |
246
+ | `alias` | `portal.alias` / `docs.alias` | Mode-specific |
247
+
248
+ ---
249
+
250
+ ## Breaking Changes
251
+
252
+ ### Critical (Will Break Your Build)
253
+
254
+ 1. **Package Name Change**
255
+ - Old: `@visualify/cli`
256
+ - New: `visualifyjs`
257
+ - Action: Uninstall old package, install new package
258
+
259
+ 2. **Mode Values Changed**
260
+ - Old: `mode: 'pages'` or `mode: 'charts'`
261
+ - New: `mode: 'portal'` or `mode: 'docs'`
262
+ - Action: Update your configuration
263
+
264
+ 3. **Command Structure**
265
+ - Portal commands now require `portal` prefix
266
+ - Action: Update your scripts and CI/CD pipelines
267
+
268
+ ### Major (Requires Code Changes)
269
+
270
+ 1. **Configuration Location**
271
+ - Old: Inline `window.$visualify` in HTML
272
+ - New: External `visualify.json` file
273
+ - Action: Extract configuration to JSON file
274
+
275
+ 2. **Init Command Requires Template**
276
+ - Old: `visualify init [path]`
277
+ - New: `visualify init <template> [path]`
278
+ - Action: Specify `docs`, `portal`, or `full` template
279
+
280
+ 3. **Serve/Start Commands Merged**
281
+ - Old: `visualify serve` and `visualify start`
282
+ - New: `visualify dev` with auto-detection or explicit mode
283
+ - Action: Update your npm scripts
284
+
285
+ ### Minor (Behavior Changes)
286
+
287
+ 1. **Default Port**
288
+ - The development server may use different default ports
289
+ - Use `--port` flag to specify explicitly
290
+
291
+ 2. **Build Output**
292
+ - Build output structure has changed for separate entry points
293
+ - Review your deployment configuration
294
+
295
+ ---
296
+
297
+ ## Troubleshooting
298
+
299
+ ### Common Migration Issues
300
+
301
+ #### Issue: "Command not found: visualify"
302
+
303
+ **Cause**: Old package still installed or not properly linked.
304
+
305
+ **Solution**:
306
+ ```bash
307
+ # Uninstall old package
308
+ npm uninstall -g @visualify/cli
309
+
310
+ # Clear npm cache
311
+ npm cache clean --force
312
+
313
+ # Install new package
314
+ npm i -g visualifyjs
315
+
316
+ # Verify installation
317
+ visualify --version
318
+ ```
319
+
320
+ #### Issue: "Cannot find module 'visualify.json'"
321
+
322
+ **Cause**: Configuration file is missing or in wrong location.
323
+
324
+ **Solution**:
325
+ Ensure `visualify.json` exists in your project root:
326
+ ```bash
327
+ ls visualify.json
328
+
329
+ # If missing, create one
330
+ echo '{"version": "3.0.0", "mode": "portal"}' > visualify.json
331
+ ```
332
+
333
+ #### Issue: "Invalid mode: 'pages'"
334
+
335
+ **Cause**: Using old mode values.
336
+
337
+ **Solution**:
338
+ Update your `visualify.json`:
339
+ ```json
340
+ {
341
+ "version": "3.0.0",
342
+ "mode": "portal"
343
+ }
344
+ ```
345
+
346
+ #### Issue: Portal commands not working
347
+
348
+ **Cause**: Missing `portal` prefix in commands.
349
+
350
+ **Solution**:
351
+ ```bash
352
+ # Wrong
353
+ visualify load-json ./data.json
354
+
355
+ # Correct
356
+ visualify portal load-json ./data.json
357
+ ```
358
+
359
+ #### Issue: "visualify dev" not detecting mode
360
+
361
+ **Cause**: Missing or invalid `visualify.json`.
362
+
363
+ **Solution**:
364
+ 1. Create a `visualify.json` with explicit mode
365
+ 2. Or specify mode explicitly: `visualify dev portal`
366
+
367
+ ### Getting Help
368
+
369
+ - **Documentation**: [https://visualify.pharmacy.arizona.edu](https://visualify.pharmacy.arizona.edu)
370
+ - **Issues**: [GitHub Issues](https://github.com/visualify/visualify.js/issues)
371
+ - **Discussions**: [GitHub Discussions](https://github.com/visualify/visualify.js/discussions)
372
+
373
+ ### Migration Checklist
374
+
375
+ - [ ] Uninstall `@visualify/cli` package
376
+ - [ ] Install `visualifyjs` package globally
377
+ - [ ] Create `visualify.json` configuration file
378
+ - [ ] Migrate `window.$visualify` settings to `visualify.json`
379
+ - [ ] Update mode values (`pages` → `portal`, `charts` → `docs`)
380
+ - [ ] Update npm scripts with new command syntax
381
+ - [ ] Update CI/CD pipelines with new commands
382
+ - [ ] Test `visualify dev` command
383
+ - [ ] Test portal subcommands (`visualify portal *`)
384
+ - [ ] Verify build output
385
+
386
+ ---
387
+
388
+ ## Additional Resources
389
+
390
+ - [Configuration Reference](../configuration/visualify-json.md)
391
+ - [CLI Command Reference](../cli/commands.md)
392
+ - [Full Documentation](https://visualify.pharmacy.arizona.edu)