semiotic 3.10.2 → 3.10.4
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.
- package/README.md +21 -26
- package/ai/artifact-surface-inventory.json +1 -1
- package/ai/behaviorContracts.cjs +15 -5
- package/ai/behaviorContracts.d.cts +3 -0
- package/ai/cli.js +17 -166
- package/ai/componentMetadata.cjs +68 -15
- package/ai/componentMetadata.d.cts +3 -0
- package/ai/dist/diagnose-operation.js +3 -0
- package/ai/dist/mcp-server.js +59 -59
- package/ai/reference.md +6 -6
- package/ai/schema.json +1 -1
- package/ai/surface-manifest.json +1 -1
- package/ai/system-prompt.md +2 -2
- package/ai/task-packets/compare-category-totals.json +7 -7
- package/ai/task-packets/compare-category-totals.md +3 -3
- package/ai/task-packets/correct-published-chart.json +7 -7
- package/ai/task-packets/correct-published-chart.md +3 -3
- package/ai/task-packets/index.json +6 -6
- package/ai/task-packets/update-live-chart.json +7 -7
- package/ai/task-packets/update-live-chart.md +3 -3
- package/dist/c-2MHSD3TN.min.js +209 -0
- package/dist/{c-PZ3NEGNG.min.js → c-6XGGN5OS.min.js} +1 -1
- package/dist/{c-FDUQDCBC.min.js → c-CO4NDAD6.min.js} +23 -23
- package/dist/c-EK6XI2U7.min.js +26 -0
- package/dist/c-FMCUQ6JX.min.js +1 -0
- package/dist/{c-C4KIXUWU.min.js → c-GK263BF4.min.js} +1 -1
- package/dist/{c-TTKWXGAI.min.js → c-HNHKIMIV.min.js} +3 -3
- package/dist/c-IJCZGUG6.min.js +31 -0
- package/dist/{c-4XLHPQTP.min.js → c-JBWPJNTJ.min.js} +1 -1
- package/dist/{c-4MD53L2J.min.js → c-JC76YAHB.min.js} +28 -28
- package/dist/{c-VXIYF7V2.min.js → c-JOPGDP6N.min.js} +1 -1
- package/dist/c-KWP4QTCM.min.js +4 -0
- package/dist/c-LRV7PO45.min.js +393 -0
- package/dist/c-LVHJJUOF.min.js +1 -0
- package/dist/c-M43PK7K4.min.js +1 -0
- package/dist/c-NUBZ63VU.min.js +1 -0
- package/dist/{c-7ASK4WBF.min.js → c-PITYSOPK.min.js} +1 -1
- package/dist/{c-2TW5H5PD.min.js → c-QPO24R7Q.min.js} +1 -1
- package/dist/{c-SG2Y7EBY.min.js → c-RWHLEUX6.min.js} +1 -1
- package/dist/{c-4JKDJUYD.min.js → c-S746GRV4.min.js} +1 -1
- package/dist/{c-KGROWFT2.min.js → c-SAP5KY6R.min.js} +2 -2
- package/dist/c-UMGHCBH5.min.js +114 -0
- package/dist/c-UQBWSYKI.min.js +41 -0
- package/dist/{c-6ZU3QVLB.min.js → c-VEMCBQZZ.min.js} +33 -33
- package/dist/{c-IPYGNVN6.min.js → c-WD2RL76M.min.js} +45 -45
- package/dist/{c-PQOZPM4G.min.js → c-YL7HJL5J.min.js} +1 -1
- package/dist/c-Z6GRGS53.min.js +1 -0
- package/dist/components/CategoryColors.d.ts +7 -0
- package/dist/components/LinkedCharts.d.ts +2 -1
- package/dist/components/ai/chartClinic.d.ts +1 -1
- package/dist/components/ai/chartClinicMetadata.generated.d.ts +2 -2
- package/dist/components/charts/shared/{chartDefinitionPilot.d.ts → chartDefinition.d.ts} +30 -34
- package/dist/components/charts/shared/chartDefinitions.d.ts +10 -0
- package/dist/components/charts/shared/chartDefinitionsNetwork.d.ts +17 -0
- package/dist/components/charts/shared/chartDefinitionsOrdinal.d.ts +23 -0
- package/dist/components/charts/shared/chartDefinitionsPhysics.d.ts +17 -0
- package/dist/components/charts/shared/chartDefinitionsRealtime.d.ts +12 -0
- package/dist/components/charts/shared/chartDefinitionsXY.d.ts +26 -0
- package/dist/components/charts/shared/useChartSetup.d.ts +1 -1
- package/dist/components/charts/shared/useNetworkChartSetup.d.ts +1 -1
- package/dist/components/data/transforms.d.ts +1 -0
- package/dist/components/server/serverChartConfigs.d.ts +36 -36
- package/dist/components/server/serverChartConfigsNetwork.generated.d.ts +17 -0
- package/dist/components/server/serverChartConfigsOrdinal.generated.d.ts +23 -0
- package/dist/components/server/serverChartConfigsPhysics.generated.d.ts +17 -0
- package/dist/components/server/serverChartConfigsRealtime.generated.d.ts +13 -0
- package/dist/components/server/serverChartConfigsXY.generated.d.ts +22 -0
- package/dist/components/stream/physics/PhysicsOptionalEngineAdapters.d.ts +5 -0
- package/dist/geo.min.js +3 -3
- package/dist/geo.module.min.js +10 -10
- package/dist/network.module.min.js +1 -1
- package/dist/ordinal.module.min.js +1 -1
- package/dist/physics-matter.min.js +4 -1
- package/dist/physics-matter.module.min.js +1 -1
- package/dist/physics-rapier.min.js +4 -1
- package/dist/physics-rapier.module.min.js +1 -1
- package/dist/physics.module.min.js +1 -1
- package/dist/physicsWorker.js +1 -1
- package/dist/semiotic-ai-core.min.js +3 -3
- package/dist/semiotic-ai-core.module.min.js +3 -3
- package/dist/semiotic-ai.module.min.js +7 -7
- package/dist/semiotic-artifact.min.js +1 -1
- package/dist/semiotic-artifact.module.min.js +1 -1
- package/dist/semiotic-atlas-selection.module.min.js +1 -1
- package/dist/semiotic-client-cjs-shared.min.js +903 -902
- package/dist/semiotic-data.min.js +1 -1
- package/dist/semiotic-data.module.min.js +1 -1
- package/dist/semiotic-experimental-auxiliary.module.min.js +3 -3
- package/dist/semiotic-experimental-node-auxiliary.module.min.js +3 -3
- package/dist/semiotic-experimental-vacp.module.min.js +1 -1
- package/dist/semiotic-line.module.min.js +1 -1
- package/dist/semiotic-realtime-core.module.min.js +1 -1
- package/dist/semiotic-recipes-core-cjs-base.min.js +1 -1
- package/dist/semiotic-recipes-core.module.min.js +13 -13
- package/dist/semiotic-server-edge-node.module.min.js +393 -391
- package/dist/semiotic-server-edge.min.js +393 -391
- package/dist/semiotic-server-edge.module.min.js +374 -372
- package/dist/semiotic-server-node.min.js +393 -391
- package/dist/semiotic-server-node.module.min.js +1 -1
- package/dist/semiotic-utils-core.min.js +1 -1
- package/dist/semiotic-utils-core.module.min.js +1 -1
- package/dist/semiotic.module.min.js +10 -10
- package/dist/server.min.js +393 -391
- package/dist/server.module.min.js +1 -1
- package/dist/xy.module.min.js +1 -1
- package/package.json +12 -8
- package/dist/c-3OFVBWQY.min.js +0 -1
- package/dist/c-6IVBV5NO.min.js +0 -1
- package/dist/c-72CBVNYX.min.js +0 -209
- package/dist/c-7LY46QUI.min.js +0 -41
- package/dist/c-AKLBQMQF.min.js +0 -391
- package/dist/c-F2GGJB2S.min.js +0 -31
- package/dist/c-G53AVC42.min.js +0 -113
- package/dist/c-HQ27AHMC.min.js +0 -1
- package/dist/c-IHWZ2C6D.min.js +0 -26
- package/dist/c-MOP2NGLH.min.js +0 -1
- package/dist/c-PKY4JFY5.min.js +0 -1
- package/dist/c-UBHICVSC.min.js +0 -1
package/README.md
CHANGED
|
@@ -26,24 +26,19 @@ evidence scope; source availability does not establish installed or deployed par
|
|
|
26
26
|
<img src="./docs/public/assets/img/semiotic-release-dashboard.svg" alt="Semiotic release dashboard showing chart count, bundle sizes, capability coverage, chart families, and documentation growth" width="100%">
|
|
27
27
|
<!-- semiotic-readme-dashboard:end -->
|
|
28
28
|
|
|
29
|
-
## What's New in 3.10.
|
|
29
|
+
## What's New in 3.10.4
|
|
30
30
|
|
|
31
|
-
3.10.
|
|
32
|
-
|
|
31
|
+
3.10.4 improves consumer bundler compatibility, optional physics engine loading,
|
|
32
|
+
and AI chart-data validation.
|
|
33
33
|
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
- LineChart direct labels share measured placement across browser and server
|
|
41
|
-
rendering; keyed path transitions preserve point identity during updates.
|
|
34
|
+
- Worker bundles and dynamic imports preserve the hints consumer bundlers need.
|
|
35
|
+
- Matter and Rapier optional peers use bundler-resolvable imports, and Rapier
|
|
36
|
+
initialization waits for its WASM runtime.
|
|
37
|
+
- AI validation distinguishes omitted push-mode data from invalid static data;
|
|
38
|
+
generated schemas retain nested constraints.
|
|
39
|
+
- A new compatibility gate checks packed installs in webpack, Rspack, and Vite.
|
|
42
40
|
|
|
43
|
-
|
|
44
|
-
`const { suggestions } = suggestStreamCharts(...)`.
|
|
45
|
-
|
|
46
|
-
See [the changelog](CHANGELOG.md#3102---2026-09-18) for details.
|
|
41
|
+
See [the changelog](CHANGELOG.md#3104---2026-09-22) for details.
|
|
47
42
|
|
|
48
43
|
## Why Semiotic
|
|
49
44
|
|
|
@@ -416,7 +411,7 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
|
|
|
416
411
|
| `semiotic/ordinal` | **128 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
|
|
417
412
|
| `semiotic/network` | **148 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
|
|
418
413
|
| `semiotic/geo` | **106 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
|
|
419
|
-
| `semiotic/realtime` | **
|
|
414
|
+
| `semiotic/realtime` | **164 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
|
|
420
415
|
| `semiotic/realtime/core` | **162 KB** | Streaming chart types, HOCs, and buffer helpers |
|
|
421
416
|
| `semiotic/realtime/react` | **1 KB** | Stream status and synced push hooks |
|
|
422
417
|
| `semiotic/server` | **243 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
|
|
@@ -431,7 +426,7 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
|
|
|
431
426
|
| `semiotic/themes` | **11 KB** | Theme presets only (tufte, carbon, etc.) |
|
|
432
427
|
| `semiotic/themes/core` | **11 KB** | Theme presets and token helpers |
|
|
433
428
|
| `semiotic/themes/react` | **6 KB** | ThemeProvider/useTheme and hooks |
|
|
434
|
-
| `semiotic/data` | **
|
|
429
|
+
| `semiotic/data` | **4 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
|
|
435
430
|
| `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
|
|
436
431
|
| `semiotic/physics` | **164 KB** | GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart |
|
|
437
432
|
| `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
|
|
@@ -465,9 +460,9 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
|
|
|
465
460
|
| `import { MotifBraidChart } from "semiotic/atlas"` | browser | **159.5 KiB** |
|
|
466
461
|
| `import { prepareNetworkAtlas } from "semiotic/atlas/core"` | browser | **6.2 KiB** |
|
|
467
462
|
| `import { LineChart } from "semiotic"` | browser | **145.1 KiB** |
|
|
468
|
-
| `import { LineChart } from "semiotic/xy"` | browser | **145.
|
|
469
|
-
| `import { LineChart } from "semiotic/line"` | browser | **145.
|
|
470
|
-
| `import { BarChart } from "semiotic/ordinal"` | browser | **133.
|
|
463
|
+
| `import { LineChart } from "semiotic/xy"` | browser | **145.6 KiB** |
|
|
464
|
+
| `import { LineChart } from "semiotic/line"` | browser | **145.4 KiB** |
|
|
465
|
+
| `import { BarChart } from "semiotic/ordinal"` | browser | **133.2 KiB** |
|
|
471
466
|
| `import { SankeyDiagram } from "semiotic/network"` | browser | **154.9 KiB** |
|
|
472
467
|
| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **147.9 KiB** |
|
|
473
468
|
| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **0.7 KiB** |
|
|
@@ -475,17 +470,17 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
|
|
|
475
470
|
| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **147.4 KiB** |
|
|
476
471
|
| `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.2 KiB** |
|
|
477
472
|
| `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** |
|
|
478
|
-
| `import { renderChart } from "semiotic/server"` | node | **277.
|
|
479
|
-
| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **
|
|
480
|
-
| `import { renderToImage } from "semiotic/server/node"` | node | **278.
|
|
481
|
-
| `import { suggestCharts } from "semiotic/ai"` | browser | **255.
|
|
473
|
+
| `import { renderChart } from "semiotic/server"` | node | **277.7 KiB** |
|
|
474
|
+
| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **141.0 KiB** |
|
|
475
|
+
| `import { renderToImage } from "semiotic/server/node"` | node | **278.5 KiB** |
|
|
476
|
+
| `import { suggestCharts } from "semiotic/ai"` | browser | **255.7 KiB** |
|
|
482
477
|
| `import { suggestCharts } from "semiotic/ai/core"` | browser | **39.1 KiB** |
|
|
483
478
|
| `import { buildArtifactContract } from "semiotic/artifact"` | browser | **13.0 KiB** |
|
|
484
479
|
| `import { ArtifactInspector } from "semiotic/artifact/react"` | browser | **3.8 KiB** |
|
|
485
480
|
| `import { createChartAccessContract } from "semiotic/access"` | browser | **27.0 KiB** |
|
|
486
481
|
| `import { toEvidenceEnvelope } from "semiotic/evidence"` | browser | **42.3 KiB** |
|
|
487
482
|
| `import { bin } from "semiotic/data"` | browser | **0.4 KiB** |
|
|
488
|
-
| `import { ChoroplethMap } from "semiotic/geo"` | browser | **
|
|
483
|
+
| `import { ChoroplethMap } from "semiotic/geo"` | browser | **116.0 KiB** |
|
|
489
484
|
| `import { usePretextAnnotations } from "semiotic/text"` | browser | **1.5 KiB** |
|
|
490
485
|
| `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.1 KiB** |
|
|
491
486
|
| `import { resolveThemePreset } from "semiotic/themes"` | browser | **2.6 KiB** |
|
|
@@ -500,7 +495,7 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
|
|
|
500
495
|
| `import { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** |
|
|
501
496
|
| `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.3 KiB** |
|
|
502
497
|
|
|
503
|
-
**Line-boundary interpretation:** the retained named import from `semiotic/line` emits 434.
|
|
498
|
+
**Line-boundary interpretation:** the retained named import from `semiotic/line` emits 434.7 KiB raw versus 434.7 KiB from `semiotic/xy`; gzip differs by 0.2 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat `semiotic/line` as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.
|
|
504
499
|
|
|
505
500
|
<!-- semiotic-cold-consumer:end -->
|
|
506
501
|
|
package/ai/behaviorContracts.cjs
CHANGED
|
@@ -113,7 +113,15 @@ const REQUIRED_COMBINATIONS = [
|
|
|
113
113
|
},
|
|
114
114
|
]
|
|
115
115
|
|
|
116
|
+
// Charts covered by the common omitted-data/ref contract. This is not the
|
|
117
|
+
// complete push-capability inventory: FlowMap, ProcessSankey, and BigNumber
|
|
118
|
+
// have their own input surfaces rather than a generic data prop.
|
|
116
119
|
const PUSH_MODE_COMPONENTS = [
|
|
120
|
+
"RealtimeLineChart",
|
|
121
|
+
"RealtimeHistogram",
|
|
122
|
+
"RealtimeSwarmChart",
|
|
123
|
+
"RealtimeWaterfallChart",
|
|
124
|
+
"RealtimeHeatmap",
|
|
117
125
|
"LineChart",
|
|
118
126
|
"AreaChart",
|
|
119
127
|
"StackedAreaChart",
|
|
@@ -122,6 +130,8 @@ const PUSH_MODE_COMPONENTS = [
|
|
|
122
130
|
"ConnectedScatterplot",
|
|
123
131
|
"CandlestickChart",
|
|
124
132
|
"MultiAxisLineChart",
|
|
133
|
+
"Heatmap",
|
|
134
|
+
"WaterfallChart",
|
|
125
135
|
"QuadrantChart",
|
|
126
136
|
"DifferenceChart",
|
|
127
137
|
"BarChart",
|
|
@@ -137,6 +147,8 @@ const PUSH_MODE_COMPONENTS = [
|
|
|
137
147
|
"DonutChart",
|
|
138
148
|
"LikertChart",
|
|
139
149
|
"SwimlaneChart",
|
|
150
|
+
"FunnelChart",
|
|
151
|
+
"RadarChart",
|
|
140
152
|
"ForceDirectedGraph",
|
|
141
153
|
"SankeyDiagram",
|
|
142
154
|
"ChordDiagram",
|
|
@@ -149,8 +161,6 @@ const PUSH_MODE_COMPONENTS = [
|
|
|
149
161
|
"PacketFlowChart",
|
|
150
162
|
"ProcessFlowChart",
|
|
151
163
|
"GauntletChart",
|
|
152
|
-
"CrucibleChart",
|
|
153
|
-
"ChainReactionChart",
|
|
154
164
|
]
|
|
155
165
|
|
|
156
166
|
const STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema()
|
|
@@ -196,7 +206,7 @@ const BEHAVIOR_CONTRACTS = [
|
|
|
196
206
|
appliesTo: {
|
|
197
207
|
propsAny: ["colorBy", "colorScheme"],
|
|
198
208
|
},
|
|
199
|
-
summary: "When colorBy is set, CategoryColorProvider
|
|
209
|
+
summary: "When colorBy is set, explicit CategoryColorProvider mappings, including those inherited through LinkedCharts, win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback. Generated LinkedCharts colors do not override a child's colorScheme.",
|
|
200
210
|
agentAction: "Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution.",
|
|
201
211
|
},
|
|
202
212
|
{
|
|
@@ -251,8 +261,8 @@ const BEHAVIOR_CONTRACTS = [
|
|
|
251
261
|
title: "renderChart uses static props only",
|
|
252
262
|
severity: "warning",
|
|
253
263
|
appliesTo: {},
|
|
254
|
-
summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot.
|
|
255
|
-
agentAction: "Use
|
|
264
|
+
summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot, never future ref pushes. semiotic/server accepts bounded data for realtime charts; MCP rendering excludes the five live Realtime components but includes TemporalHistogram.",
|
|
265
|
+
agentAction: "Use complete static data for snapshots. For a Realtime component snapshot, use semiotic/server directly; for live behavior, return React code with a ref and do not promise MCP-rendered output.",
|
|
256
266
|
},
|
|
257
267
|
{
|
|
258
268
|
id: "serialization.formatters-are-react-callbacks",
|
package/ai/cli.js
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
const fs = require("fs")
|
|
5
5
|
const path = require("path")
|
|
6
6
|
|
|
7
|
+
const { diagnoseChart } = require("./dist/diagnose-operation.js")
|
|
8
|
+
|
|
7
9
|
const pkgRoot = path.resolve(__dirname, "..")
|
|
8
10
|
const {
|
|
9
11
|
CATEGORY_ORDER,
|
|
@@ -20,7 +22,6 @@ const {
|
|
|
20
22
|
behaviorContractsFor,
|
|
21
23
|
dataRequiredForUsageMode,
|
|
22
24
|
formatDoctorBehaviorContracts,
|
|
23
|
-
normalizeUsageMode
|
|
24
25
|
} = require("./behaviorContracts.cjs")
|
|
25
26
|
|
|
26
27
|
const FILES = {
|
|
@@ -144,136 +145,15 @@ function printSingleComponentSchema(componentName) {
|
|
|
144
145
|
console.log(JSON.stringify(payload, null, 2))
|
|
145
146
|
}
|
|
146
147
|
|
|
147
|
-
// Both helpers are only called from `validatePropsWithSchema` below, which
|
|
148
|
-
// filters `undefined` / `null` out of `value` before reaching them — so
|
|
149
|
-
// neither guards null here. CodeQL flags the dead branches if they return.
|
|
150
|
-
|
|
151
|
-
function schemaTypeMatches(value, expectedType) {
|
|
152
|
-
const expectedTypes = Array.isArray(expectedType)
|
|
153
|
-
? expectedType
|
|
154
|
-
: [expectedType]
|
|
155
|
-
return expectedTypes.some((type) => {
|
|
156
|
-
if (type === "array") return Array.isArray(value)
|
|
157
|
-
if (type === "object")
|
|
158
|
-
return typeof value === "object" && !Array.isArray(value)
|
|
159
|
-
return typeof value === type
|
|
160
|
-
})
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
function describeActualType(value) {
|
|
164
|
-
if (Array.isArray(value)) return "array"
|
|
165
|
-
return typeof value
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
function shouldSkipMissingRequiredProp(componentName, propName, usageMode) {
|
|
169
|
-
return (
|
|
170
|
-
propName === "data" && !dataRequiredForUsageMode(componentName, usageMode)
|
|
171
|
-
)
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
function filterUsageModeErrors(componentName, errors, usageMode) {
|
|
175
|
-
if (dataRequiredForUsageMode(componentName, usageMode)) return errors
|
|
176
|
-
return errors.filter(
|
|
177
|
-
(err) => err !== `"data" is required for ${componentName}.`
|
|
178
|
-
)
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
function validatePropsWithSchema(componentName, props, usageMode = "static") {
|
|
182
|
-
const schema = loadSchema()
|
|
183
|
-
const component = findComponent(schema, componentName)
|
|
184
|
-
if (!component) {
|
|
185
|
-
const available = schemaEntries(schema)
|
|
186
|
-
.map((entry) => entry.name)
|
|
187
|
-
.sort()
|
|
188
|
-
.join(", ")
|
|
189
|
-
return {
|
|
190
|
-
valid: false,
|
|
191
|
-
errors: [
|
|
192
|
-
`Unknown component "${componentName}". Available components: ${available}`
|
|
193
|
-
]
|
|
194
|
-
}
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
const parameters = component.parameters || {}
|
|
198
|
-
const properties = parameters.properties || {}
|
|
199
|
-
const required = parameters.required || []
|
|
200
|
-
const errors = []
|
|
201
|
-
|
|
202
|
-
for (const propName of required) {
|
|
203
|
-
if (shouldSkipMissingRequiredProp(component.name, propName, usageMode))
|
|
204
|
-
continue
|
|
205
|
-
if (props[propName] === undefined || props[propName] === null) {
|
|
206
|
-
errors.push(`"${propName}" is required for ${component.name}.`)
|
|
207
|
-
}
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
// Array-shape charts that declare a `data` schema prop need it in static
|
|
211
|
-
// usage even when "data" isn't in `required` (those lists hold semantic
|
|
212
|
-
// accessors). Without this, --doctor passed dataless static CandlestickChart /
|
|
213
|
-
// MultiAxisLineChart / QuadrantChart / DifferenceChart / SwimlaneChart /
|
|
214
|
-
// LikertChart configs that render blank. dataRequiredForUsageMode is true for
|
|
215
|
-
// them in static and false in push, mirroring the MCP diagnoseConfig path.
|
|
216
|
-
if (
|
|
217
|
-
"data" in properties &&
|
|
218
|
-
!required.includes("data") &&
|
|
219
|
-
dataRequiredForUsageMode(component.name, usageMode) &&
|
|
220
|
-
(props.data === undefined || props.data === null)
|
|
221
|
-
) {
|
|
222
|
-
errors.push(`"data" is required for ${component.name}.`)
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
for (const [propName, value] of Object.entries(props)) {
|
|
226
|
-
if (value === undefined || value === null) continue
|
|
227
|
-
const propSchema = properties[propName]
|
|
228
|
-
if (!propSchema) {
|
|
229
|
-
errors.push(`Unknown prop "${propName}" for ${component.name}.`)
|
|
230
|
-
continue
|
|
231
|
-
}
|
|
232
|
-
|
|
233
|
-
// Prefer the full runtime type surface (`x-semiotic-runtime-types`, e.g.
|
|
234
|
-
// ["string","function"]) over the wire-only `type` ("string"), so a valid
|
|
235
|
-
// function value for a prop like `colorBy`/`onBrush` is still accepted. The
|
|
236
|
-
// wire `type` keyword is standards-valid JSON Schema and never lists
|
|
237
|
-
// "function"; the runtime extension carries it. Falls back to `type` for
|
|
238
|
-
// props with no runtime-only alternatives.
|
|
239
|
-
const effectiveType =
|
|
240
|
-
propSchema["x-semiotic-runtime-types"] || propSchema.type
|
|
241
|
-
if (effectiveType && !schemaTypeMatches(value, effectiveType)) {
|
|
242
|
-
const expected = Array.isArray(effectiveType)
|
|
243
|
-
? effectiveType.join(" | ")
|
|
244
|
-
: effectiveType
|
|
245
|
-
errors.push(
|
|
246
|
-
`"${propName}" should be ${expected}, got ${describeActualType(value)}.`
|
|
247
|
-
)
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
if (
|
|
251
|
-
propSchema.enum &&
|
|
252
|
-
typeof value === "string" &&
|
|
253
|
-
!propSchema.enum.includes(value)
|
|
254
|
-
) {
|
|
255
|
-
errors.push(
|
|
256
|
-
`"${propName}" value "${value}" is not valid. Expected one of: ${propSchema.enum.join(", ")}.`
|
|
257
|
-
)
|
|
258
|
-
}
|
|
259
|
-
}
|
|
260
|
-
|
|
261
|
-
return {
|
|
262
|
-
valid: errors.length === 0,
|
|
263
|
-
errors
|
|
264
|
-
}
|
|
265
|
-
}
|
|
266
|
-
|
|
267
148
|
// Returns true when the schema-only validation passed, so the caller can set
|
|
268
149
|
// the process exit code (nonzero on failure — this is a CI gate).
|
|
269
|
-
function printSchemaOnlyDoctorResult(component, props, usageMode) {
|
|
270
|
-
const result = validatePropsWithSchema(component, props, usageMode)
|
|
150
|
+
function printSchemaOnlyDoctorResult(component, props, usageMode, result) {
|
|
271
151
|
if (usageMode === "push") {
|
|
272
152
|
console.log(
|
|
273
153
|
` Usage mode: push (data prop may be omitted; use a ref to push data)`
|
|
274
154
|
)
|
|
275
155
|
}
|
|
276
|
-
if (result.
|
|
156
|
+
if (result.ok) {
|
|
277
157
|
console.log(`✓ ${component}: schema-only validation passed.`)
|
|
278
158
|
} else {
|
|
279
159
|
console.log(`✗ ${component}: schema-only validation failed.`)
|
|
@@ -282,7 +162,7 @@ function printSchemaOnlyDoctorResult(component, props, usageMode) {
|
|
|
282
162
|
}
|
|
283
163
|
}
|
|
284
164
|
printDoctorBehaviorContracts(component, props)
|
|
285
|
-
return result.
|
|
165
|
+
return result.ok
|
|
286
166
|
}
|
|
287
167
|
|
|
288
168
|
function printDoctorBehaviorContracts(component, props) {
|
|
@@ -541,7 +421,6 @@ if (flag === "--doctor") {
|
|
|
541
421
|
else console.error(msg)
|
|
542
422
|
process.exit(1)
|
|
543
423
|
}
|
|
544
|
-
const usageMode = normalizeUsageMode(rawUsageMode)
|
|
545
424
|
|
|
546
425
|
// Load diagnoseConfig from dist (falls back to validateProps, then schema.json)
|
|
547
426
|
const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
|
|
@@ -557,44 +436,18 @@ if (flag === "--doctor") {
|
|
|
557
436
|
// packaged schema so the CLI still catches basic agent mistakes.
|
|
558
437
|
}
|
|
559
438
|
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
const result = validatePropsWithSchema(component, props, usageMode)
|
|
567
|
-
ok = result.valid
|
|
568
|
-
console.log(
|
|
569
|
-
JSON.stringify(
|
|
570
|
-
{
|
|
571
|
-
component,
|
|
572
|
-
usageMode,
|
|
573
|
-
mode: "schema-only",
|
|
574
|
-
ok,
|
|
575
|
-
errors: result.errors
|
|
576
|
-
},
|
|
577
|
-
null,
|
|
578
|
-
2
|
|
579
|
-
)
|
|
580
|
-
)
|
|
581
|
-
} else {
|
|
582
|
-
ok = printSchemaOnlyDoctorResult(component, props, usageMode)
|
|
583
|
-
}
|
|
584
|
-
} else if (diagnoseConfig) {
|
|
585
|
-
// Use the full anti-pattern detector
|
|
586
|
-
const result = diagnoseConfig(component, props)
|
|
587
|
-
const diagnoses =
|
|
588
|
-
usageMode === "push"
|
|
589
|
-
? result.diagnoses.filter(
|
|
590
|
-
(d) =>
|
|
591
|
-
d.code !== "VALIDATION" ||
|
|
592
|
-
!shouldSkipMissingRequiredProp(component, "data", usageMode) ||
|
|
593
|
-
d.message !== `"data" is required for ${component}.`
|
|
594
|
-
)
|
|
595
|
-
: result.diagnoses
|
|
596
|
-
ok = diagnoses.every((d) => d.severity === "warning")
|
|
439
|
+
const report = diagnoseChart(
|
|
440
|
+
{ component, props, usageMode: rawUsageMode },
|
|
441
|
+
{ diagnoseConfig, validateProps },
|
|
442
|
+
loadSchema
|
|
443
|
+
)
|
|
444
|
+
const { usageMode, ok } = report
|
|
597
445
|
|
|
446
|
+
if (report.mode === "schema-only") {
|
|
447
|
+
if (asJson) console.log(JSON.stringify(report, null, 2))
|
|
448
|
+
else printSchemaOnlyDoctorResult(component, props, usageMode, report)
|
|
449
|
+
} else if (report.mode === "diagnose") {
|
|
450
|
+
const { diagnoses } = report
|
|
598
451
|
if (asJson) {
|
|
599
452
|
console.log(
|
|
600
453
|
JSON.stringify(
|
|
@@ -638,9 +491,7 @@ if (flag === "--doctor") {
|
|
|
638
491
|
}
|
|
639
492
|
} else {
|
|
640
493
|
// Fallback to validateProps only
|
|
641
|
-
const
|
|
642
|
-
const errors = filterUsageModeErrors(component, result.errors, usageMode)
|
|
643
|
-
ok = errors.length === 0
|
|
494
|
+
const { errors } = report
|
|
644
495
|
if (asJson) {
|
|
645
496
|
console.log(
|
|
646
497
|
JSON.stringify(
|
package/ai/componentMetadata.cjs
CHANGED
|
@@ -3,34 +3,86 @@
|
|
|
3
3
|
const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "physics", "value", "recipe"]
|
|
4
4
|
|
|
5
5
|
const COMPONENTS_BY_CATEGORY = {
|
|
6
|
+
// BEGIN GENERATED XY CHARTS
|
|
6
7
|
xy: [
|
|
7
|
-
"LineChart",
|
|
8
|
-
"
|
|
9
|
-
"
|
|
8
|
+
"LineChart",
|
|
9
|
+
"BumpChart",
|
|
10
|
+
"AreaChart",
|
|
11
|
+
"DifferenceChart",
|
|
12
|
+
"StackedAreaChart",
|
|
13
|
+
"Scatterplot",
|
|
14
|
+
"BubbleChart",
|
|
15
|
+
"Heatmap",
|
|
16
|
+
"QuadrantChart",
|
|
17
|
+
"MultiAxisLineChart",
|
|
18
|
+
"WaterfallChart",
|
|
19
|
+
"CandlestickChart",
|
|
20
|
+
"ConnectedScatterplot",
|
|
21
|
+
"ScatterplotMatrix",
|
|
22
|
+
"MinimapChart"
|
|
10
23
|
],
|
|
24
|
+
// END GENERATED XY CHARTS
|
|
25
|
+
// BEGIN GENERATED ORDINAL CHARTS
|
|
11
26
|
ordinal: [
|
|
12
|
-
"BarChart",
|
|
13
|
-
"
|
|
14
|
-
"
|
|
27
|
+
"BarChart",
|
|
28
|
+
"StackedBarChart",
|
|
29
|
+
"GroupedBarChart",
|
|
30
|
+
"SwarmPlot",
|
|
31
|
+
"BoxPlot",
|
|
32
|
+
"Histogram",
|
|
33
|
+
"ViolinPlot",
|
|
34
|
+
"RidgelinePlot",
|
|
35
|
+
"DotPlot",
|
|
36
|
+
"PieChart",
|
|
37
|
+
"DonutChart",
|
|
38
|
+
"GaugeChart",
|
|
39
|
+
"FunnelChart",
|
|
40
|
+
"RadarChart",
|
|
41
|
+
"SwimlaneChart",
|
|
42
|
+
"LikertChart"
|
|
15
43
|
],
|
|
44
|
+
// END GENERATED ORDINAL CHARTS
|
|
45
|
+
// BEGIN GENERATED NETWORK CHARTS
|
|
16
46
|
network: [
|
|
17
|
-
"MotifBraidChart",
|
|
18
|
-
"
|
|
19
|
-
"
|
|
47
|
+
"MotifBraidChart",
|
|
48
|
+
"DependencyForestChart",
|
|
49
|
+
"ForceDirectedGraph",
|
|
50
|
+
"SankeyDiagram",
|
|
51
|
+
"ProcessSankey",
|
|
52
|
+
"ChordDiagram",
|
|
53
|
+
"TreeDiagram",
|
|
54
|
+
"Treemap",
|
|
55
|
+
"CirclePack",
|
|
56
|
+
"OrbitDiagram"
|
|
20
57
|
],
|
|
58
|
+
// END GENERATED NETWORK CHARTS
|
|
21
59
|
geo: [
|
|
22
60
|
"ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram",
|
|
23
61
|
],
|
|
62
|
+
// BEGIN GENERATED REALTIME CHARTS
|
|
24
63
|
realtime: [
|
|
25
|
-
"RealtimeLineChart",
|
|
26
|
-
"
|
|
64
|
+
"RealtimeLineChart",
|
|
65
|
+
"RealtimeHistogram",
|
|
66
|
+
"TemporalHistogram",
|
|
67
|
+
"RealtimeSwarmChart",
|
|
68
|
+
"RealtimeWaterfallChart",
|
|
69
|
+
"RealtimeHeatmap"
|
|
27
70
|
],
|
|
71
|
+
// END GENERATED REALTIME CHARTS
|
|
72
|
+
// BEGIN GENERATED PHYSICS CHARTS
|
|
28
73
|
physics: [
|
|
29
74
|
"FlowCircuitChart",
|
|
30
|
-
"GaltonBoardChart",
|
|
31
|
-
"
|
|
32
|
-
"
|
|
75
|
+
"GaltonBoardChart",
|
|
76
|
+
"EventDropChart",
|
|
77
|
+
"UnitPileChart",
|
|
78
|
+
"CollisionSwarmChart",
|
|
79
|
+
"PacketFlowChart",
|
|
80
|
+
"ProcessFlowChart",
|
|
81
|
+
"GauntletChart",
|
|
82
|
+
"CrucibleChart",
|
|
83
|
+
"ChainReactionChart"
|
|
33
84
|
],
|
|
85
|
+
// END GENERATED PHYSICS CHARTS
|
|
34
86
|
value: [
|
|
35
87
|
"BigNumber",
|
|
36
88
|
],
|
|
@@ -83,7 +135,8 @@ function schemaResourceUriForComponent(name) {
|
|
|
83
135
|
function metadataForComponent(entryOrName) {
|
|
84
136
|
const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name
|
|
85
137
|
const category = categoryForComponent(name)
|
|
86
|
-
// Realtime
|
|
138
|
+
// MCP excludes the live Realtime charts. Their public server renderers
|
|
139
|
+
// separately accept bounded data snapshots.
|
|
87
140
|
// TemporalHistogram is the static-data sibling living in the
|
|
88
141
|
// "realtime" category for documentation grouping — it accepts a
|
|
89
142
|
// bounded data array and is renderable through the SSR path like
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
"use strict";var H=Object.create;var h=Object.defineProperty;var V=Object.getOwnPropertyDescriptor;var Y=Object.getOwnPropertyNames;var J=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var w=(e,t)=>()=>{try{return t||e((t={exports:{}}).exports,t),t.exports}catch(a){throw t=0,a}},W=(e,t)=>{for(var a in t)h(e,a,{get:t[a],enumerable:!0})},R=(e,t,a,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of Y(t))!K.call(e,o)&&o!==a&&h(e,o,{get:()=>t[o],enumerable:!(r=V(t,o))||r.enumerable});return e};var S=(e,t,a)=>(a=e!=null?H(J(e)):{},R(t||!e||!e.__esModule?h(a,"default",{value:e,enumerable:!0}):a,e)),X=e=>R(h({},"__esModule",{value:!0}),e);var O=w((Re,M)=>{"use strict";var P=require("path"),Q=require("fs"),k="<!-- semiotic-behavior-contracts:start -->",D="<!-- semiotic-behavior-contracts:end -->";function Z(){let e=[P.join(__dirname,"schema.json"),P.join(__dirname,"..","schema.json")];for(let t of e)try{let a=JSON.parse(Q.readFileSync(t,"utf8")),r=new Set;for(let o of a.tools||[])"data"in(o.function?.parameters?.properties||{})&&r.add(o.function.name);if(r.size>0)return r}catch{}return new Set}var g=[{component:"StackedAreaChart",required:["areaBy"],staticRequired:["data","areaBy"],pushRequired:["areaBy"],summary:"Stacked areas need a flat data array plus areaBy to identify the stacked series."},{component:"BubbleChart",required:["sizeBy"],staticRequired:["data","sizeBy"],pushRequired:["sizeBy"],summary:"Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size."},{component:"StackedBarChart",required:["stackBy"],staticRequired:["data","stackBy"],pushRequired:["stackBy"],summary:"Stacked bars need stackBy to split each category into stack segments."},{component:"GroupedBarChart",required:["groupBy"],staticRequired:["data","groupBy"],pushRequired:["groupBy"],summary:"Grouped bars need groupBy to split each category into side-by-side bars."},{component:"SwimlaneChart",required:["subcategoryAccessor"],staticRequired:["data","subcategoryAccessor"],pushRequired:["subcategoryAccessor"],summary:"Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided."},{component:"GaugeChart",required:["value"],staticRequired:["value"],pushRequired:[],summary:"GaugeChart is value-only. Its thresholds use { value, color, label? }; BigNumber thresholds use the distinct { at, level, color?, label? } vocabulary."},{component:"ForceDirectedGraph",required:["nodes","edges"],staticRequired:["nodes","edges"],pushRequired:["nodes","edges"],summary:"ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code."}],u=["RealtimeLineChart","RealtimeHistogram","RealtimeSwarmChart","RealtimeWaterfallChart","RealtimeHeatmap","LineChart","AreaChart","StackedAreaChart","Scatterplot","BubbleChart","ConnectedScatterplot","CandlestickChart","MultiAxisLineChart","Heatmap","WaterfallChart","QuadrantChart","DifferenceChart","BarChart","StackedBarChart","GroupedBarChart","SwarmPlot","BoxPlot","Histogram","ViolinPlot","RidgelinePlot","DotPlot","PieChart","DonutChart","LikertChart","SwimlaneChart","FunnelChart","RadarChart","ForceDirectedGraph","SankeyDiagram","ChordDiagram","ProportionalSymbolMap","DistanceCartogram","GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart","PacketFlowChart","ProcessFlowChart","GauntletChart"],x=Z(),C=[{id:"accessibility.description-props",category:"accessibility",title:"Accessible chart text uses direct chart props",severity:"warning",appliesTo:{},summary:"High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.",agentAction:'Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. If a consumer-owned role=img wraps the chart, use accessibleTable: { portalTarget: "element-id" } and render that target outside the image. For generated L1\u2013L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.'},{id:"interaction.cursor-is-presentation-only",category:"interaction",title:"Cursor styling does not create behavior",severity:"warning",appliesTo:{propsAny:["cursor"],propPathsAny:[["styleRules","*","style","cursor"]]},summary:"Cursor values in realtime props, retained mark styles, styleRules, and custom hit targets change pointer presentation only. They do not install click handlers, keyboard activation, observations, or accessibility semantics.",agentAction:"Use an actionable cursor only when the application separately supplies documented click or observation behavior and an accessible activation path. Treat cursor in serialized/static output as visual metadata, never as proof that a mark is interactive."},{id:"props.data-required-by-usage-mode",category:"required-props",title:"Data required by usage mode",severity:"error",appliesTo:{components:u},summary:"Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.",agentAction:'Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.'},{id:"color.category-precedence",category:"color",title:"Categorical color precedence",severity:"info",appliesTo:{propsAny:["colorBy","colorScheme"]},summary:"When colorBy is set, explicit CategoryColorProvider mappings, including those inherited through LinkedCharts, win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback. Generated LinkedCharts colors do not override a child's colorScheme.",agentAction:"Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution."},{id:"props.required-combinations",category:"required-props",title:"Required prop combinations",severity:"error",appliesTo:{components:g.map(e=>e.component)},summary:"Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.",agentAction:"Before returning code, check the selected component against the required combinations list. For push mode, omit data but keep semantic props such as areaBy, sizeBy, stackBy, and groupBy.",combinations:g},{id:"streaming.push-mode-data",category:"streaming",title:"Push mode omits data",severity:"warning",appliesTo:{components:u},summary:"HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.",agentAction:"For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later."},{id:"streaming.serialized-proposal-snapshot",category:"streaming",title:"Serialized proposals keep the initial snapshot",severity:"warning",appliesTo:{components:u},summary:"A JSON component/props proposal for MCP, SSR, or evaluation is a static snapshot even when the request mentions future pushes. Keep the supplied initial rows in the component's real data prop and do not invent pushRows, pushRequirement, ref, or method props.",agentAction:"Return renderable initial props in JSON. If the requested deliverable is React push code, separately omit the controlled data prop in JSX, attach a ref, and call the documented imperative method from an effect or event handler.",example:'JSON snapshot: { "component": "LineChart", "props": { "data": [{"week":1,"users":120}], "xAccessor":"week", "yAccessor":"users" } }. React push code instead omits data and calls ref.current?.push(row).'},{id:"streaming.ref-mutations-require-id-accessors",category:"streaming",title:"Ref mutations need stable IDs",severity:"warning",appliesTo:{components:u},summary:"push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.",agentAction:"When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field."},{id:"rendering.renderchart-static-props",category:"rendering",title:"renderChart uses static props only",severity:"warning",appliesTo:{},summary:"MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot, never future ref pushes. semiotic/server accepts bounded data for realtime charts; MCP rendering excludes the five live Realtime components but includes TemporalHistogram.",agentAction:"Use complete static data for snapshots. For a Realtime component snapshot, use semiotic/server directly; for live behavior, return React code with a ref and do not promise MCP-rendered output."},{id:"serialization.formatters-are-react-callbacks",category:"serialization",title:"Axis formatters are React callbacks",severity:"error",appliesTo:{propsAny:["xFormat","yFormat","categoryFormat","valueFormat"]},summary:"xFormat, yFormat, categoryFormat, and valueFormat are callback props, not d3 format strings or axis-title strings. They are intentionally absent from JSON/MCP schemas and string values fail validation.",agentAction:"In serialized props, omit formatter callbacks and use xLabel, yLabel, categoryLabel, or valueLabel for axis titles. In React JSX, pass a function such as xFormat={value => formatAxis(value)}.",example:'JSON: { "xLabel": "Payload (KB)", "yLabel": "Response time (ms)" }. React-only: xFormat={value => formatNumber(value, { maximumFractionDigits: 0 })}.'},{id:"value.bignumber-wire-contract",category:"value",title:"Value components do not inherit chart-HOC props",severity:"error",appliesTo:{components:["BigNumber"]},summary:"BigNumber is a value component, not a chart HOC, so it does not inherit the common chart-HOC prop list. It uses label as its visible heading and supports description and summary; title and accessibleTable are invalid. Its percent format expects a ratio such as 0.97 and renders it as 97%.",agentAction:'Validate BigNumber against its own prop schema and remove inherited chart-HOC props such as title and accessibleTable before returning a proposal. Use label, description, and summary for text. For a 97-of-100 KPI, either pass value={0.97} with format="percent" or pass value={97} with format="number" and suffix="%"; do not combine value={97} with format="percent".',example:'{ "component": "BigNumber", "props": { "value": 97, "label": "SLA attainment", "format": "number", "suffix": "%", "target": { "value": 99, "label": "target", "format": "number" } } }'},{id:"geo.proportional-symbol-wire-shape",category:"geo",title:"Proportional symbol maps use geographic props",severity:"error",appliesTo:{components:["ProportionalSymbolMap"]},summary:"ProportionalSymbolMap reads point rows from points, longitude from xAccessor (default lon), latitude from yAccessor (default lat), and radius from sizeBy. sizeRange is the two-number pixel-radius range.",agentAction:"Use points, xAccessor, yAccessor, and sizeBy. Do not rename points to data or sizeBy to valueAccessor merely because the map renders circles.",example:'{ "points": [{"city":"A","longitude":-122.4,"latitude":37.8,"incidents":18}], "xAccessor":"longitude", "yAccessor":"latitude", "sizeBy":"incidents", "sizeRange":[5,40] }'},{id:"physics.sample-and-mechanical-inputs",category:"physics",title:"Physics charts separate chart mode from simulation input",severity:"warning",appliesTo:{components:["GaltonBoardChart","UnitPileChart"]},summary:`Sample simulations use data plus the chart's accessors. Seeded no-data demonstrations use simulationMode="mechanical" (legacy mode="mechanical" remains accepted); mode otherwise carries chart display modes such as primary or sparkline.`,agentAction:"For observed Galton values pass data + valueAccessor. For unit piles pass data + categoryAccessor + valueAccessor. Use seed for reproducibility, bins for Galton columns, and unitValue for the amount represented by one full UnitPile circle; remainders use proportional area.",example:'{ "component": "GaltonBoardChart", "props": { "data": [{"id":"a","value":1}], "valueAccessor":"value", "bins":4, "seed":42 } }'},{id:"physics.push-uses-source-records",category:"physics",title:"Physics push methods ingest source records",severity:"error",appliesTo:{components:["GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart"]},summary:"Physics HOC refs push source records through the chart's accessors. pushRows and dataIdAccessor are not component props; stable source id fields are retained on spawned bodies without an invented accessor.",agentAction:"For React live code, call ref.current?.push(row) or pushMany(rows). For serialized snapshots, append the rows to data. Keep category/value/time accessors, but omit pushRows and dataIdAccessor.",example:'ref.current?.push({ id: "c", team: "Blue", value: 2 }); <UnitPileChart ref={ref} categoryAccessor="team" valueAccessor="value" unitValue={1} />'},{id:"physics.live-source-reconciliation",category:"physics",title:"Distribution physics charts update bodies and projections together",severity:"warning",appliesTo:{components:["GaltonBoardChart","UnitPileChart","CollisionSwarmChart","EventDropChart"]},summary:"Bodies, categories, domains, and totals update together without changing React keys. getData() returns source rows. New data replaces live rows; rerunMS restores the seed.",agentAction:"Omit data for push mode; data=[] stays empty and rejects pushes. Use stable IDs and remove for source edits; popBodies only removes marks. Set xExtent/valueExtent/timeExtent for stable domains.",example:'ref.current?.update("a", row => ({ ...row, value: 102 })); ref.current?.remove("b");'},{id:"physics.event-admission-history",category:"physics",title:"EventDrop distinguishes admission history from current closure",severity:"error",appliesTo:{components:["EventDropChart"]},summary:"Arrival order determines historical lateness with a delay/function watermark. Equal arrival times keep source order. A window is closed when its end is at or below the watermark; previously accepted events stay accepted as later events advance it. An explicit watermark.value instead tests one fixed policy.",agentAction:"Use watermark={{delay: n}} for arrival-ordered admission, or watermarkAtArrivalAccessor for recorded thresholds independent of current closure. Keep all times in the same units. The current board has solid lids: accepted history starts below them, late arrivals roll left. For a chronological demonstration, supply successive data/watermark states and coordinate source time with travel. timeScale does not replay lid changes. Source projection labels describe snapshot totals; readEventDropOccupancy(metadata, bodies) counts current containers and in-flight bodies independently of source flags.",example:'{ "data": [{"time":1,"arrivalTime":2,"admission":-3}], "watermarkAtArrivalAccessor":"admission", "watermark":{"value":100} }'}];function B(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function ee(e){return e&&typeof e=="object"&&!Array.isArray(e)?e:{}}function te(e,t){if(!t)return!e.appliesTo?.components;let a=e.appliesTo?.components;return!a||a.includes(t)}function ae(e,t){let a=e.appliesTo?.propsAny,r=e.appliesTo?.propPathsAny;return(!a||a.length===0)&&(!r||r.length===0)||a?.some(o=>B(t,o)&&t[o]!==void 0)?!0:r?.some(o=>y(t,o))??!1}function y(e,t){if(t.length===0)return e!==void 0;if(e===null||typeof e!="object")return!1;let[a,...r]=t;return a==="*"?Array.isArray(e)&&e.some(o=>y(o,r)):B(e,a)&&y(e[a],r)}function re({component:e,props:t}={}){let a=ee(t);return C.filter(r=>te(r,e)&&ae(r,a))}function T(e){return e==="push"?"push":"static"}function oe(e,t){return!(!x.has(e)||T(t)==="push"&&u.includes(e))}function se(e){return g.filter(t=>!e||t.component===e)}function q(e){let t=e.staticRequired||e.required,a=e.pushRequired||e.required.filter(o=>o!=="data"),r=a.length>0?a.join(" + "):"not supported";return`${e.component}: static ${t.join(" + ")}; push ${r}. ${e.summary}`}function ne(e){if(!e||e.length===0)return"";let t=["Behavior contracts:"];for(let a of e){if(t.push(` - [${a.id}] ${a.summary}`),a.combinations)for(let r of a.combinations)t.push(` ${q(r)}`);a.example&&t.push(` Example: ${a.example}`),t.push(` Action: ${a.agentAction}`)}return t.join(`
|
|
2
|
+
`)}function ie({compact:e=!1}={}){let t=[e?"## Behavior Contracts":"## AI Behavior Contracts","",k,"","These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.",""];for(let a of C){if(t.push(`- **${a.title}** (\`${a.id}\`): ${a.summary}`),e||t.push(` Agent action: ${a.agentAction}`),a.combinations){let r=a.combinations.map(q).join(" ");t.push(` Required combinations: ${r}`)}!e&&a.example&&t.push(` Example: \`${a.example}\``)}return t.push("",D),t.join(`
|
|
3
|
+
`)}M.exports={BEHAVIOR_CONTRACTS:C,DOC_MARKER_END:D,DOC_MARKER_START:k,PUSH_MODE_COMPONENTS:u,REQUIRED_COMBINATIONS:g,STATIC_DATA_COMPONENTS:x,behaviorContractsFor:re,dataRequiredForUsageMode:oe,formatBehaviorContractsMarkdown:ie,formatDoctorBehaviorContracts:ne,normalizeUsageMode:T,requiredCombinationsFor:se}});var L=w((Se,G)=>{"use strict";var F=["xy","ordinal","network","geo","realtime","physics","value","recipe"],E={xy:["LineChart","BumpChart","AreaChart","DifferenceChart","StackedAreaChart","Scatterplot","BubbleChart","Heatmap","QuadrantChart","MultiAxisLineChart","WaterfallChart","CandlestickChart","ConnectedScatterplot","ScatterplotMatrix","MinimapChart"],ordinal:["BarChart","StackedBarChart","GroupedBarChart","SwarmPlot","BoxPlot","Histogram","ViolinPlot","RidgelinePlot","DotPlot","PieChart","DonutChart","GaugeChart","FunnelChart","RadarChart","SwimlaneChart","LikertChart"],network:["MotifBraidChart","DependencyForestChart","ForceDirectedGraph","SankeyDiagram","ProcessSankey","ChordDiagram","TreeDiagram","Treemap","CirclePack","OrbitDiagram"],geo:["ChoroplethMap","ProportionalSymbolMap","FlowMap","DistanceCartogram"],realtime:["RealtimeLineChart","RealtimeHistogram","TemporalHistogram","RealtimeSwarmChart","RealtimeWaterfallChart","RealtimeHeatmap"],physics:["FlowCircuitChart","GaltonBoardChart","EventDropChart","UnitPileChart","CollisionSwarmChart","PacketFlowChart","ProcessFlowChart","GauntletChart","CrucibleChart","ChainReactionChart"],value:["BigNumber"],recipe:["ParallelCoordinatesRecipe","CalendarHeatmapRecipe"]},b=new Map;for(let[e,t]of Object.entries(E))for(let a of t)b.set(a,e);var ce={PhysicsCustomChart:"physics"};function v(e){return e.tools.map(t=>t.function)}function U(e){let t=b.get(e);if(!t)throw new Error(`No AI component metadata category for "${e}"`);return t}function de(e){return b.get(e)??ce[e]}function I(e){return e==="physics"?"semiotic/physics":e==="recipe"?"semiotic/ai":e==="geo"?"semiotic/geo":`semiotic/${e}`}function $(e){return`semiotic://schema/${encodeURIComponent(e)}`}function N(e){let t=typeof e=="string"?e:e.name,a=U(t),r=a==="realtime"&&t.startsWith("Realtime");return{name:t,category:a,importPath:["MotifBraidChart","DependencyForestChart","FlowCircuitChart"].includes(t)?"semiotic/atlas":I(a),schemaResourceUri:$(t),renderable:!r,requiresLiveData:r,description:typeof e=="string"?void 0:e.description}}function le(e,t){let a=v(e),r=a.find(n=>n.name===t);if(r)return r;let o=t.toLowerCase();return a.find(n=>n.name.toLowerCase()===o)}function pe(e){let t=v(e).map(N),a={};for(let r of F)a[r]=[];for(let r of t)a[r.category].push(r.name);for(let r of Object.values(a))r.sort();return{version:e.version,totalComponents:t.length,renderableComponents:t.filter(r=>r.renderable).length,browserOnlyComponents:t.filter(r=>!r.renderable).length,requiresLiveDataComponents:t.filter(r=>r.requiresLiveData).length,categories:a,components:t}}G.exports={CATEGORY_ORDER:F,COMPONENTS_BY_CATEGORY:E,categoryForComponent:U,categoryForAIExport:de,componentIndexFromSchema:pe,findComponent:le,importPathForCategory:I,metadataForComponent:N,schemaResourceUriForComponent:$,schemaEntries:v}});var Ae={};W(Ae,{diagnoseChart:()=>fe});module.exports=X(Ae);var z=S(O()),_=S(L()),{dataRequiredForUsageMode:A,normalizeUsageMode:ue}=z.default,{findComponent:me,schemaEntries:he,COMPONENTS_BY_CATEGORY:ge}=_.default;function fe(e,t,a){let{component:r,props:o}=e,n=ue(e.usageMode),m=ge.realtime.includes(r)&&(A(r,n)||o.data===null)&&o.data==null,p=`"data" is required for ${r}.`;if(t.diagnoseConfig){let i=t.diagnoseConfig(r,o),d=f(r,o,n)?i.diagnoses.filter(c=>c.code!=="VALIDATION"||c.message!==`"data" is required for ${r}.`):[...i.diagnoses];return m&&!d.some(({message:c})=>c===p)&&d.push({code:"VALIDATION",severity:"error",message:p,fix:"Provide bounded data for a static snapshot, or select push usage for React ref startup."}),{component:r,usageMode:n,mode:"diagnose",ok:d.every(({severity:c})=>c==="warning"),diagnoses:d}}let l=t.validateProps?"validate":"schema-only",s=t.validateProps?be(r,[...t.validateProps(r,o).errors],n,o):ve(r,o,n,a()).errors;return m&&!s.includes(p)&&s.push(p),A(r,"static")&&Array.isArray(o.data)&&o.data.length===0&&!s.includes(`${r}: No data provided. Pass a non-empty array to the data prop.`)&&s.push(`"data" must contain at least one observation for ${r}; an empty array is a static snapshot, not push startup.`),{component:r,usageMode:n,mode:l,ok:s.length===0,errors:s}}function ye(e,t){return(Array.isArray(t)?t:[t]).some(r=>r==="array"?Array.isArray(e):r==="object"?typeof e=="object"&&!Array.isArray(e):typeof e===r)}function Ce(e){return Array.isArray(e)?"array":typeof e}function f(e,t,a){return t.data===void 0&&!A(e,a)}function be(e,t,a,r){return f(e,r,a)?t.filter(o=>o!==`"data" is required for ${e}.`):t}function ve(e,t,a,r){let o=me(r,e);if(!o){let s=he(r).map(i=>i.name).sort().join(", ");return{valid:!1,errors:[`Unknown component "${e}". Available components: ${s}`]}}let n=o.parameters||{},m=n.properties||{},p=n.required||[],l=[];for(let s of p)s==="data"&&f(o.name,t,a)||(t[s]===void 0||t[s]===null)&&l.push(`"${s}" is required for ${o.name}.`);"data"in m&&!p.includes("data")&&!f(o.name,t,a)&&(t.data===void 0||t.data===null)&&l.push(`"data" is required for ${o.name}.`);for(let[s,i]of Object.entries(t)){if(i==null)continue;let d=m[s];if(!d){l.push(`Unknown prop "${s}" for ${o.name}.`);continue}let c=d["x-semiotic-runtime-types"]||d.type;if(c&&!ye(i,c)){let j=Array.isArray(c)?c.join(" | "):c;l.push(`"${s}" should be ${j}, got ${Ce(i)}.`)}d.enum&&typeof i=="string"&&!d.enum.includes(i)&&l.push(`"${s}" value "${i}" is not valid. Expected one of: ${d.enum.join(", ")}.`)}return{valid:l.length===0,errors:l}}0&&(module.exports={diagnoseChart});
|