semiotic 3.9.0 → 3.9.2
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 +102 -90
- package/agent-skill/semiotic-charts/SKILL.md +14 -10
- package/ai/componentMetadata.cjs +13 -3
- package/ai/dist/mcp-server.js +140 -36407
- package/ai/examples.md +109 -6
- package/ai/reference.md +55 -18
- package/ai/schema.json +5964 -1190
- package/ai/surface-manifest.json +51 -7
- package/ai/system-prompt.md +16 -3
- package/dist/c-3SCUN5HI.min.js +1 -0
- package/dist/c-3VVKFA4M.min.js +1 -0
- package/dist/c-43TJZS3F.min.js +1 -0
- package/dist/c-4DTZPSUD.min.js +1 -0
- package/dist/c-4ES5367Y.min.js +1 -0
- package/dist/c-54IRWOGM.min.js +1 -0
- package/dist/c-5D2S4RMI.min.js +1 -0
- package/dist/c-5JWCTX3G.min.js +1 -0
- package/dist/c-6CMMSN6N.min.js +1 -0
- package/dist/c-6HRB2L7H.min.js +1 -0
- package/dist/c-7W4SV36A.min.js +1 -0
- package/dist/c-A4WRGZFX.min.js +1 -0
- package/dist/c-AG7WWVIH.min.js +1 -0
- package/dist/c-AH6J4MTN.min.js +1 -0
- package/dist/c-ALYR5LKK.min.js +1 -0
- package/dist/c-BYDPC44I.min.js +1 -0
- package/dist/c-CFFIU2MW.min.js +1 -0
- package/dist/c-CGNHBHCE.min.js +1 -0
- package/dist/c-CJYSXIFV.min.js +1 -0
- package/dist/c-CKLIFCGN.min.js +1 -0
- package/dist/c-CZF7MV67.min.js +1 -0
- package/dist/c-D53OKBSY.min.js +1 -0
- package/dist/c-DBQ2V7CH.min.js +1 -0
- package/dist/c-DPMVAUAW.min.js +1 -0
- package/dist/c-ECJCKLYY.min.js +1 -0
- package/dist/c-EGATGOWJ.min.js +1 -0
- package/dist/c-EGR6VYBW.min.js +1 -0
- package/dist/c-ENF72HU5.min.js +1 -0
- package/dist/c-ESNR43AN.min.js +1 -0
- package/dist/c-F3LIKINL.min.js +1 -0
- package/dist/c-F5ZB5GJ6.min.js +1 -0
- package/dist/c-G3VYMHKE.min.js +1 -0
- package/dist/c-GR6MOEQC.min.js +1 -0
- package/dist/c-GSVCN34B.min.js +1 -0
- package/dist/c-GYOQCEFP.min.js +1 -0
- package/dist/c-H3DNMTCC.min.js +1 -0
- package/dist/c-I6J3FEZE.min.js +1 -0
- package/dist/c-IGH6MGJ5.min.js +1 -0
- package/dist/c-II2EEAJN.min.js +1 -0
- package/dist/c-J6M4JHRS.min.js +1 -0
- package/dist/c-JM3MGLQV.min.js +1 -0
- package/dist/c-KM3N7F7R.min.js +1 -0
- package/dist/c-LF5BZFNC.min.js +1 -0
- package/dist/c-LKBSGFQC.min.js +1 -0
- package/dist/c-NDJADPIF.min.js +1 -0
- package/dist/c-NVPQCIL5.min.js +1 -0
- package/dist/c-OFWJBEE5.min.js +1 -0
- package/dist/c-OYFHP5F5.min.js +1 -0
- package/dist/c-PGKQGGQ2.min.js +1 -0
- package/dist/c-Q2IPZ3MU.min.js +1 -0
- package/dist/c-QKHMBE2E.min.js +1 -0
- package/dist/c-QMVM3AY6.min.js +1 -0
- package/dist/c-QSGWX53A.min.js +1 -0
- package/dist/c-RJKEKZOO.min.js +1 -0
- package/dist/c-SFDIIU5G.min.js +1 -0
- package/dist/c-SRTBCRVE.min.js +1 -0
- package/dist/c-T6UAIKBH.min.js +1 -0
- package/dist/c-TMCTEVVW.min.js +1 -0
- package/dist/c-TMOSJLT3.min.js +1 -0
- package/dist/c-U6ESPM7V.min.js +1 -0
- package/dist/c-UC5PTTFI.min.js +1 -0
- package/dist/c-VGKUEZBC.min.js +1 -0
- package/dist/c-VN2HG5BS.min.js +1 -0
- package/dist/{c-J5G56TUH.min.js → c-VPZDY5Q4.min.js} +1 -1
- package/dist/c-VRXUB2F2.min.js +1 -0
- package/dist/c-VUBQNQJH.min.js +1 -0
- package/dist/c-VUH4PGZY.min.js +1 -0
- package/dist/c-XDRV7RKW.min.js +1 -0
- package/dist/c-YGZHURXZ.min.js +1 -0
- package/dist/components/Annotation.d.ts +1 -1
- package/dist/components/access/chartAccessCapabilities.generated.d.ts +14 -0
- package/dist/components/access/chartAccessContract.d.ts +90 -0
- package/dist/components/access/chartAccessContractFixtures.d.ts +11 -0
- package/dist/components/ai/aestheticProfileTypes.d.ts +35 -0
- package/dist/components/ai/annotationProvenance.d.ts +2 -7
- package/dist/components/ai/auditVisualHierarchy.d.ts +49 -0
- package/dist/components/ai/builtInChartRecipeLayouts.d.ts +2 -0
- package/dist/components/ai/builtInChartRecipePublic.d.ts +4 -0
- package/dist/components/ai/builtInChartRecipes.d.ts +26 -0
- package/dist/components/ai/chartCapabilities.d.ts +3 -1
- package/dist/components/ai/chartRecipeRegistry.d.ts +2 -1
- package/dist/components/ai/chartRecipes.d.ts +6 -0
- package/dist/components/ai/colorEvidence.d.ts +12 -0
- package/dist/components/ai/evaluateAesthetics.d.ts +47 -0
- package/dist/components/ai/geoNavigation.d.ts +4 -0
- package/dist/components/ai/hierarchyNavigation.d.ts +4 -0
- package/dist/components/ai/navigationTree.d.ts +7 -1
- package/dist/components/ai/qualityFixtures.d.ts +8 -0
- package/dist/components/ai/suggestionPropContracts.d.ts +1 -1
- package/dist/components/ai/useNavigationSync.d.ts +3 -3
- package/dist/components/charts/index.d.ts +4 -0
- package/dist/components/charts/network/ChordDiagram.d.ts +5 -1
- package/dist/components/charts/network/CirclePack.d.ts +8 -1
- package/dist/components/charts/network/OrbitDiagram.d.ts +9 -0
- package/dist/components/charts/network/TreeDiagram.d.ts +8 -1
- package/dist/components/charts/network/Treemap.d.ts +8 -1
- package/dist/components/charts/ordinal/BarChart.d.ts +6 -0
- package/dist/components/charts/ordinal/BoxPlot.d.ts +3 -0
- package/dist/components/charts/ordinal/DonutChart.d.ts +3 -0
- package/dist/components/charts/ordinal/DotPlot.d.ts +3 -0
- package/dist/components/charts/ordinal/FunnelChart.d.ts +3 -0
- package/dist/components/charts/ordinal/GaugeChart.d.ts +3 -0
- package/dist/components/charts/ordinal/Histogram.d.ts +3 -0
- package/dist/components/charts/ordinal/LikertChart.d.ts +3 -0
- package/dist/components/charts/ordinal/PieChart.d.ts +3 -0
- package/dist/components/charts/ordinal/RadarChart.capability.d.ts +2 -0
- package/dist/components/charts/ordinal/RadarChart.d.ts +75 -0
- package/dist/components/charts/ordinal/RidgelinePlot.d.ts +3 -0
- package/dist/components/charts/ordinal/SwarmPlot.d.ts +3 -0
- package/dist/components/charts/ordinal/SwimlaneChart.d.ts +3 -0
- package/dist/components/charts/ordinal/ViolinPlot.d.ts +3 -0
- package/dist/components/charts/physics/GauntletChart.d.ts +1 -5
- package/dist/components/charts/physics/chainReactionTypes.d.ts +3 -0
- package/dist/components/charts/physics/gauntletPhysics.d.ts +1 -0
- package/dist/components/charts/physics/physicsHocUtils.d.ts +7 -1
- package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +10 -1
- package/dist/components/charts/realtime/RealtimeHistogram.d.ts +11 -1
- package/dist/components/charts/realtime/RealtimeLineChart.d.ts +14 -5
- package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +7 -1
- package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +7 -1
- package/dist/components/charts/realtime/aggregate.d.ts +12 -1
- package/dist/components/charts/realtime/realtimeChartRuntime.d.ts +4 -2
- package/dist/components/charts/realtime/realtimeStyleRules.d.ts +4 -0
- package/dist/components/charts/shared/annotationStatusFilter.d.ts +18 -0
- package/dist/components/charts/shared/chartDefinitionPilot.d.ts +5 -4
- package/dist/components/charts/shared/chartSpecCore.d.ts +2 -2
- package/dist/components/charts/shared/heatmapStyleRules.d.ts +13 -0
- package/dist/components/charts/shared/knownChartComponents.d.ts +1 -1
- package/dist/components/charts/shared/networkUtils.d.ts +14 -0
- package/dist/components/charts/shared/selectionUtils.d.ts +3 -1
- package/dist/components/charts/shared/types.d.ts +4 -2
- package/dist/components/charts/shared/useChartLegend.d.ts +2 -1
- package/dist/components/charts/shared/useLikertAggregation.d.ts +8 -2
- package/dist/components/charts/shared/useNetworkChartSetup.d.ts +9 -5
- package/dist/components/charts/shared/useOrdinalPieceStyle.d.ts +1 -1
- package/dist/components/charts/shared/useXYBrush.d.ts +24 -0
- package/dist/components/charts/xy/Heatmap.d.ts +16 -0
- package/dist/components/charts/xy/LineChart.d.ts +9 -0
- package/dist/components/charts/xy/Scatterplot.d.ts +7 -0
- package/dist/components/charts/xy/WaterfallChart.capability.d.ts +2 -0
- package/dist/components/charts/xy/WaterfallChart.d.ts +68 -0
- package/dist/components/evidence/chartEvidenceEnvelope.d.ts +146 -0
- package/dist/components/evidence/evidenceGate.d.ts +28 -0
- package/dist/components/realtime/BinAccumulator.d.ts +5 -1
- package/dist/components/realtime/types.d.ts +16 -7
- package/dist/components/recipes/adjacencyFlow.d.ts +12 -0
- package/dist/components/recipes/adjacencyFlowAggregation.d.ts +72 -0
- package/dist/components/recipes/adjacencyFlowGeometry.d.ts +79 -0
- package/dist/components/recipes/lineageDag.d.ts +17 -0
- package/dist/components/recipes/lineageDagHulls.d.ts +22 -0
- package/dist/components/recipes/transitDiagram.d.ts +75 -0
- package/dist/components/recipes/transitDiagramGeometry.d.ts +47 -0
- package/dist/components/semiotic-access.d.ts +9 -0
- package/dist/components/semiotic-ai-audits.d.ts +17 -0
- package/dist/components/semiotic-ai-core.d.ts +9 -0
- package/dist/components/semiotic-ai.d.ts +5 -17
- package/dist/components/semiotic-evidence.d.ts +10 -0
- package/dist/components/semiotic-line.d.ts +9 -0
- package/dist/components/semiotic-network.d.ts +3 -0
- package/dist/components/semiotic-ordinal.d.ts +2 -0
- package/dist/components/semiotic-realtime-core.d.ts +3 -2
- package/dist/components/semiotic-recipes-core.d.ts +6 -0
- package/dist/components/semiotic-themes-core.d.ts +3 -0
- package/dist/components/semiotic-utils-core.d.ts +5 -0
- package/dist/components/semiotic-utils.d.ts +1 -1
- package/dist/components/semiotic-xy.d.ts +3 -0
- package/dist/components/semiotic.d.ts +9 -3
- package/dist/components/server/renderDashboard.d.ts +37 -0
- package/dist/components/server/renderEvidence.d.ts +27 -0
- package/dist/components/server/renderToStaticSVG.d.ts +2 -30
- package/dist/components/server/serverChartConfigShared.d.ts +13 -0
- package/dist/components/server/serverChartConfigs.d.ts +9 -0
- package/dist/components/server/serverChartConfigsComposite.d.ts +4 -0
- package/dist/components/server/serverChartConfigsCustom.d.ts +2 -0
- package/dist/components/server/serverChartConfigsGeo.d.ts +1 -0
- package/dist/components/server/serverChartConfigsOrdinal.d.ts +3 -2
- package/dist/components/server/serverChartConfigsXY.d.ts +1 -0
- package/dist/components/server/serverChartConfigsXYExtra.d.ts +3 -0
- package/dist/components/server/serverCompositeChainReaction.d.ts +3 -0
- package/dist/components/server/serverOrdinalGauge.d.ts +3 -0
- package/dist/components/server/serverOrdinalLikert.d.ts +2 -0
- package/dist/components/store/selectionProvenance.d.ts +8 -0
- package/dist/components/store/themeCore.d.ts +5 -1
- package/dist/components/stream/GeoPipelineStore.d.ts +1 -1
- package/dist/components/stream/MarginalGraphics.d.ts +3 -3
- package/dist/components/stream/MarginalGraphicsLazy.d.ts +22 -0
- package/dist/components/stream/NetworkPipelineStore.d.ts +2 -0
- package/dist/components/stream/OrdinalPipelineStore.d.ts +1 -1
- package/dist/components/stream/PipelineStore.d.ts +1 -1
- package/dist/components/stream/SceneToSVG.d.ts +1 -1
- package/dist/components/stream/canvasSetup.d.ts +8 -2
- package/dist/components/stream/customLayoutAttempt.d.ts +21 -0
- package/dist/components/stream/geoTypes.d.ts +1 -1
- package/dist/components/stream/isServerEnvironment.d.ts +6 -0
- package/dist/components/stream/layouts/forceLayoutNodeSize.d.ts +12 -0
- package/dist/components/stream/layouts/forceLayoutPlugin.d.ts +2 -9
- package/dist/components/stream/layouts/forceLayoutWorkerClient.d.ts +2 -21
- package/dist/components/stream/layouts/forceLayoutWorkerPolicy.d.ts +21 -0
- package/dist/components/stream/layouts/index.d.ts +6 -12
- package/dist/components/stream/layouts/missingPlugin.d.ts +7 -0
- package/dist/components/stream/layouts/registerBuiltIn.d.ts +1 -0
- package/dist/components/stream/layouts/registry.d.ts +12 -0
- package/dist/components/stream/marginalConfig.d.ts +3 -0
- package/dist/components/stream/networkCustomLayout.d.ts +7 -0
- package/dist/components/stream/networkCustomLayoutOutput.d.ts +13 -0
- package/dist/components/stream/networkCustomLayoutRunner.d.ts +1 -1
- package/dist/components/stream/networkTypes.d.ts +5 -1
- package/dist/components/stream/ordinalTypes.d.ts +1 -1
- package/dist/components/stream/physics/StreamPhysicsTypes.d.ts +1 -1
- package/dist/components/stream/pipelineDomainResolution.d.ts +6 -0
- package/dist/components/stream/renderers/pointCanvasRenderer.d.ts +4 -0
- package/dist/components/stream/renderers/resolveCSSColor.d.ts +4 -4
- package/dist/components/stream/types.d.ts +8 -1
- package/dist/components/stream/useEnsureCustomXYRenderers.d.ts +18 -0
- package/dist/components/stream/useMarginalValues.d.ts +13 -0
- package/dist/components/stream/xyCanvasRenderers.d.ts +4 -4
- package/dist/components/stream/xyPlugins/areaPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/barPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/candlestickPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/customPlugin.d.ts +6 -0
- package/dist/components/stream/xyPlugins/heatmapPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/lineFamily.d.ts +5 -0
- package/dist/components/stream/xyPlugins/linePlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/missingPlugin.d.ts +7 -0
- package/dist/components/stream/xyPlugins/mixedPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/pointPlugin.d.ts +3 -0
- package/dist/components/stream/xyPlugins/registerBuiltIn.d.ts +1 -0
- package/dist/components/stream/xyPlugins/registry.d.ts +31 -0
- package/dist/components/stream/xyPlugins/stackedAreaPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/swarmPlugin.d.ts +2 -0
- package/dist/components/stream/xyPlugins/waterfallPlugin.d.ts +2 -0
- package/dist/forceLayoutWorker.js +1 -1
- package/dist/geo.min.js +1 -1
- package/dist/geo.module.min.js +1 -1
- package/dist/network.module.min.js +1 -1
- package/dist/ordinal.module.min.js +1 -1
- package/dist/physics.module.min.js +1 -1
- package/dist/rough.module.min.js +1 -1
- package/dist/semiotic-access.d.ts +9 -0
- package/dist/semiotic-access.min.js +2 -0
- package/dist/semiotic-access.module.min.js +2 -0
- package/dist/semiotic-ai-core.d.ts +9 -0
- package/dist/semiotic-ai-core.min.js +1 -1
- package/dist/semiotic-ai-core.module.min.js +1 -1
- package/dist/semiotic-ai.d.ts +5 -17
- package/dist/semiotic-ai.module.min.js +1 -1
- package/dist/semiotic-client-cjs-shared.min.js +1 -1
- package/dist/semiotic-client-shared.module.min.js +1 -1
- package/dist/semiotic-evidence.d.ts +10 -0
- package/dist/semiotic-evidence.min.js +1 -0
- package/dist/semiotic-evidence.module.min.js +1 -0
- package/dist/semiotic-experimental-auxiliary.module.min.js +1 -1
- package/dist/semiotic-experimental-node-auxiliary.module.min.js +1 -1
- package/dist/semiotic-experimental-react-shared.module.min.js +1 -1
- package/dist/semiotic-experimental-vacp.min.js +1 -1
- package/dist/semiotic-experimental-vacp.module.min.js +1 -1
- package/dist/semiotic-line.d.ts +9 -0
- package/dist/semiotic-line.min.js +2 -0
- package/dist/semiotic-line.module.min.js +2 -0
- package/dist/semiotic-network.d.ts +3 -0
- package/dist/semiotic-ordinal.d.ts +2 -0
- package/dist/semiotic-realtime-core.d.ts +3 -2
- 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.d.ts +6 -0
- package/dist/semiotic-recipes-core.module.min.js +1 -1
- package/dist/semiotic-server-edge-node.module.min.js +1 -1
- package/dist/semiotic-server-edge.min.js +1 -1
- package/dist/semiotic-server-edge.module.min.js +1 -1
- package/dist/semiotic-server-node.min.js +1 -1
- package/dist/semiotic-server-node.module.min.js +1 -1
- package/dist/semiotic-themes-core.d.ts +3 -0
- package/dist/semiotic-themes-core.min.js +1 -1
- package/dist/semiotic-themes-core.module.min.js +1 -1
- package/dist/semiotic-themes.min.js +1 -1
- package/dist/semiotic-themes.module.min.js +1 -1
- package/dist/semiotic-utils-core.d.ts +5 -0
- package/dist/semiotic-utils-core.min.js +1 -1
- package/dist/semiotic-utils-core.module.min.js +1 -1
- package/dist/semiotic-utils.d.ts +1 -1
- package/dist/semiotic-utils.module.min.js +1 -1
- package/dist/semiotic-xy.d.ts +3 -0
- package/dist/semiotic.d.ts +9 -3
- package/dist/semiotic.module.min.js +1 -1
- package/dist/server.min.js +1 -1
- package/dist/server.module.min.js +1 -1
- package/dist/xy.module.min.js +1 -1
- package/package.json +39 -60
- package/dist/c-3KZD6AXJ.min.js +0 -1
- package/dist/c-4TWEX5HG.min.js +0 -1
- package/dist/c-5YCIX3VZ.min.js +0 -1
- package/dist/c-6FEKTA3U.min.js +0 -1
- package/dist/c-74HEEZGK.min.js +0 -1
- package/dist/c-BWNB6USU.min.js +0 -1
- package/dist/c-C25ENHIK.min.js +0 -1
- package/dist/c-CDR5AO3R.min.js +0 -1
- package/dist/c-E3JFRRMI.min.js +0 -1
- package/dist/c-EBFPQHHO.min.js +0 -1
- package/dist/c-GIKRQI4X.min.js +0 -1
- package/dist/c-GPYOFETM.min.js +0 -1
- package/dist/c-IDUHYYSI.min.js +0 -1
- package/dist/c-JAZ73J32.min.js +0 -1
- package/dist/c-KG3NXHAL.min.js +0 -1
- package/dist/c-KII3PLZE.min.js +0 -1
- package/dist/c-LIXGXMNS.min.js +0 -1
- package/dist/c-LVEY6D6B.min.js +0 -1
- package/dist/c-M4Y3BHFR.min.js +0 -1
- package/dist/c-MAIICR2Z.min.js +0 -1
- package/dist/c-MG5DM6VE.min.js +0 -1
- package/dist/c-O6U6K4CW.min.js +0 -1
- package/dist/c-OQ7M4AGV.min.js +0 -1
- package/dist/c-OXYMVK7Q.min.js +0 -1
- package/dist/c-QHF5YON3.min.js +0 -1
- package/dist/c-RR3GO5SW.min.js +0 -1
- package/dist/c-S2BXNNJN.min.js +0 -1
- package/dist/c-SUILCHWU.min.js +0 -1
- package/dist/c-US5ZFT6E.min.js +0 -1
- package/dist/c-UUKVD4WB.min.js +0 -1
- package/dist/c-WJCD5EUY.min.js +0 -1
- package/dist/c-YDAY2WFR.min.js +0 -1
- package/dist/c-ZOWWU34K.min.js +0 -1
- /package/dist/{c-COHXCW3Q.min.js → c-YZVRZGX2.min.js} +0 -0
package/ai/examples.md
CHANGED
|
@@ -12,7 +12,7 @@ the schema is authoritative when prose drifts.
|
|
|
12
12
|
### LineChart (single line)
|
|
13
13
|
|
|
14
14
|
```jsx
|
|
15
|
-
import { LineChart } from "semiotic/
|
|
15
|
+
import { LineChart } from "semiotic/line"
|
|
16
16
|
|
|
17
17
|
const data = [
|
|
18
18
|
{ month: "Jan", revenue: 4200 },
|
|
@@ -37,7 +37,7 @@ Key props: `xAccessor`, `yAccessor`, `curve`, `showPoints`, `fillArea`
|
|
|
37
37
|
### LineChart (multi-line)
|
|
38
38
|
|
|
39
39
|
```jsx
|
|
40
|
-
import { LineChart } from "semiotic/
|
|
40
|
+
import { LineChart } from "semiotic/line"
|
|
41
41
|
|
|
42
42
|
const data = [
|
|
43
43
|
{ quarter: 1, sales: 120, region: "East" },
|
|
@@ -67,7 +67,7 @@ instead of forcing the value through a single field name. This is especially
|
|
|
67
67
|
useful for multi-line data with a different metric per series.
|
|
68
68
|
|
|
69
69
|
```jsx
|
|
70
|
-
import { LineChart } from "semiotic/
|
|
70
|
+
import { LineChart } from "semiotic/line"
|
|
71
71
|
|
|
72
72
|
const data = [
|
|
73
73
|
{ timestamp: 1, metricLabel: "valueA", valueA: 12, valueB: 60 },
|
|
@@ -160,6 +160,30 @@ import { Heatmap } from "semiotic/xy"
|
|
|
160
160
|
|
|
161
161
|
Key props: `showLegend` enables gradient legend, `legendPosition` ("right"|"left"|"top"|"bottom")
|
|
162
162
|
|
|
163
|
+
### WaterfallChart
|
|
164
|
+
|
|
165
|
+
```jsx
|
|
166
|
+
import { WaterfallChart } from "semiotic/xy"
|
|
167
|
+
|
|
168
|
+
const data = [
|
|
169
|
+
{ step: "Opening", value: 120 },
|
|
170
|
+
{ step: "New sales", value: 45 },
|
|
171
|
+
{ step: "Returns", value: -18 },
|
|
172
|
+
{ step: "Discounts", value: -12 },
|
|
173
|
+
{ step: "Other", value: 8 }
|
|
174
|
+
]
|
|
175
|
+
|
|
176
|
+
<WaterfallChart
|
|
177
|
+
data={data}
|
|
178
|
+
xAccessor="step"
|
|
179
|
+
yAccessor="value"
|
|
180
|
+
xLabel="Step"
|
|
181
|
+
yLabel="Change"
|
|
182
|
+
/>
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Key props: `yAccessor` is a **signed delta** per row, not a running total. Categorical `xAccessor` values are plotted by index. Use `RealtimeWaterfallChart` for a push-driven window.
|
|
186
|
+
|
|
163
187
|
### AreaChart
|
|
164
188
|
|
|
165
189
|
```jsx
|
|
@@ -502,7 +526,7 @@ const data = [
|
|
|
502
526
|
/>
|
|
503
527
|
```
|
|
504
528
|
|
|
505
|
-
Key props: `bins` (default 25), `relative` (normalize per-category)
|
|
529
|
+
Key props: `bins` (default 25), `relative` (normalize per-category), `brush`
|
|
506
530
|
|
|
507
531
|
### ViolinPlot
|
|
508
532
|
|
|
@@ -533,6 +557,32 @@ const data = [
|
|
|
533
557
|
|
|
534
558
|
Key props: `bins`, `curve` (default "catmullRom"), `showIQR` (default true)
|
|
535
559
|
|
|
560
|
+
### RadarChart
|
|
561
|
+
|
|
562
|
+
```jsx
|
|
563
|
+
import { RadarChart } from "semiotic/ordinal"
|
|
564
|
+
|
|
565
|
+
const data = [
|
|
566
|
+
{ name: "Alpha", attribute: "speed", value: 80 },
|
|
567
|
+
{ name: "Alpha", attribute: "power", value: 55 },
|
|
568
|
+
{ name: "Alpha", attribute: "range", value: 40 },
|
|
569
|
+
{ name: "Beta", attribute: "speed", value: 45 },
|
|
570
|
+
{ name: "Beta", attribute: "power", value: 75 },
|
|
571
|
+
{ name: "Beta", attribute: "range", value: 60 }
|
|
572
|
+
]
|
|
573
|
+
|
|
574
|
+
<RadarChart
|
|
575
|
+
data={data}
|
|
576
|
+
categoryAccessor="attribute"
|
|
577
|
+
valueAccessor="value"
|
|
578
|
+
seriesAccessor="name"
|
|
579
|
+
colorBy="name"
|
|
580
|
+
showLegend
|
|
581
|
+
/>
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
Key props: `categoryAccessor` (radial axes), `valueAccessor` (magnitude), `seriesAccessor` (polygon identity). Use only when the axes are comparable magnitudes.
|
|
585
|
+
|
|
536
586
|
---
|
|
537
587
|
|
|
538
588
|
## Hierarchical Data — Single Root Object
|
|
@@ -1222,7 +1272,7 @@ Key props: `onClick` receives the original datum and pixel coordinates. Works on
|
|
|
1222
1272
|
### Synced crosshair across time-series charts
|
|
1223
1273
|
|
|
1224
1274
|
```jsx
|
|
1225
|
-
import { LineChart } from "semiotic/
|
|
1275
|
+
import { LineChart } from "semiotic/line"
|
|
1226
1276
|
import { LinkedCharts } from "semiotic/ai"
|
|
1227
1277
|
|
|
1228
1278
|
<LinkedCharts>
|
|
@@ -1289,6 +1339,59 @@ Key props: `y-threshold` works on vertical ordinal charts. `category-highlight`
|
|
|
1289
1339
|
|
|
1290
1340
|
## Recipe Layouts — Explicit Semantics Without Bespoke Geometry
|
|
1291
1341
|
|
|
1342
|
+
### ParallelCoordinatesRecipe (schema-backed portable recipe)
|
|
1343
|
+
|
|
1344
|
+
```jsx
|
|
1345
|
+
import { ChartRecipe } from "semiotic/ai"
|
|
1346
|
+
|
|
1347
|
+
const vehicles = [
|
|
1348
|
+
{ id: "compact", mpg: 32, power: 88, weight: 2100, origin: "EU" },
|
|
1349
|
+
{ id: "sedan", mpg: 25, power: 132, weight: 2900, origin: "US" },
|
|
1350
|
+
{ id: "sport", mpg: 18, power: 280, weight: 2600, origin: "JP" },
|
|
1351
|
+
]
|
|
1352
|
+
|
|
1353
|
+
<ChartRecipe
|
|
1354
|
+
recipeId="ParallelCoordinatesRecipe"
|
|
1355
|
+
data={vehicles}
|
|
1356
|
+
layoutConfig={{
|
|
1357
|
+
fields: ["mpg", "power", "weight"],
|
|
1358
|
+
colorBy: "origin",
|
|
1359
|
+
showPoints: true,
|
|
1360
|
+
}}
|
|
1361
|
+
title="Vehicle profiles"
|
|
1362
|
+
description="Vehicle profiles compared across independently scaled measures."
|
|
1363
|
+
summary="Power increases as fuel economy falls in this sample."
|
|
1364
|
+
accessibleTable
|
|
1365
|
+
/>
|
|
1366
|
+
```
|
|
1367
|
+
|
|
1368
|
+
The serialized/MCP/server component name is `ParallelCoordinatesRecipe` with
|
|
1369
|
+
the same props. The schema requires two to twelve unique numeric field names.
|
|
1370
|
+
|
|
1371
|
+
### CalendarHeatmapRecipe (schema-backed portable recipe)
|
|
1372
|
+
|
|
1373
|
+
```jsx
|
|
1374
|
+
import { ChartRecipe } from "semiotic/ai"
|
|
1375
|
+
|
|
1376
|
+
<ChartRecipe
|
|
1377
|
+
recipeId="CalendarHeatmapRecipe"
|
|
1378
|
+
data={[
|
|
1379
|
+
{ date: "2026-01-01", count: 4 },
|
|
1380
|
+
{ date: "2026-01-02", count: 9 },
|
|
1381
|
+
{ date: "2026-01-03", count: 2 },
|
|
1382
|
+
]}
|
|
1383
|
+
layoutConfig={{ dateAccessor: "date", valueAccessor: "count", year: 2026 }}
|
|
1384
|
+
title="Daily activity"
|
|
1385
|
+
description="Daily activity positioned by calendar week and weekday."
|
|
1386
|
+
summary="January 2 has the highest value in this sample."
|
|
1387
|
+
accessibleTable
|
|
1388
|
+
/>
|
|
1389
|
+
```
|
|
1390
|
+
|
|
1391
|
+
The serialized/MCP/server component name is `CalendarHeatmapRecipe`. Keep one
|
|
1392
|
+
calendar year per chart; use the raw layouts from `semiotic/recipes` when a
|
|
1393
|
+
local React callback or custom frame behavior is necessary.
|
|
1394
|
+
|
|
1292
1395
|
### Word Trails (source-aware color + progressive reveal)
|
|
1293
1396
|
|
|
1294
1397
|
```jsx
|
|
@@ -1749,7 +1852,7 @@ Key props: `value` (the focal number), `label` (the visible heading), `descripti
|
|
|
1749
1852
|
|
|
1750
1853
|
```jsx
|
|
1751
1854
|
import { BigNumber } from "semiotic/value"
|
|
1752
|
-
import { LineChart } from "semiotic/
|
|
1855
|
+
import { LineChart } from "semiotic/line"
|
|
1753
1856
|
|
|
1754
1857
|
<BigNumber
|
|
1755
1858
|
value={1284900}
|
package/ai/reference.md
CHANGED
|
@@ -10,7 +10,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
|
|
|
10
10
|
- Install: `npm install semiotic`
|
|
11
11
|
<!-- semiotic-bundle-sizes:start -->
|
|
12
12
|
<!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
|
|
13
|
-
- **Use sub-path imports** — `semiotic/xy` (
|
|
13
|
+
- **Use sub-path imports** — `semiotic/access` (35KB gz), `semiotic/evidence` (50KB gz), `semiotic/line` (135KB gz), `semiotic/xy` (166KB gz), `semiotic/ordinal` (130KB gz), `semiotic/network` (157KB gz), `semiotic/geo` (113KB gz), `semiotic/realtime` (162KB gz), `semiotic/realtime/core` (161KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (216KB gz), `semiotic/server/node` (216KB gz), `semiotic/server/edge` (222KB gz), `semiotic/utils` (103KB gz), `semiotic/utils/core` (95KB gz), `semiotic/utils/react` (7KB gz), `semiotic/recipes` (100KB gz), `semiotic/recipes/core` (92KB gz), `semiotic/recipes/react` (8KB gz), `semiotic/themes` (12KB gz), `semiotic/themes/core` (12KB gz), `semiotic/themes/react` (7KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (168KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (553KB gz), `semiotic/ai/core` (101KB gz), `semiotic/controls` (11KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 360KB gz.
|
|
14
14
|
<!-- semiotic-bundle-sizes:end -->
|
|
15
15
|
- CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y|--evaluate]` · MCP: `npx semiotic-mcp`
|
|
16
16
|
|
|
@@ -18,7 +18,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
|
|
|
18
18
|
HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless you need control they don't expose. Stream Frames pass `RealtimeNode`/`RealtimeEdge` wrappers in callbacks, not your data. Every HOC accepts `frameProps`, has an error boundary + dev-mode validation. TypeScript `strict: true`.
|
|
19
19
|
|
|
20
20
|
## Common Props (chart HOCs only)
|
|
21
|
-
`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke`, `strokeWidth`, `opacity`, `enableHover` (true), `tooltip` (boolean | "multi" | function | config), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading`, `loadingContent` (ReactNode; `false` suppresses), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations`, `accessibleTable` (true; use `{ portalTarget: "element-id" }` to portal its interactive UI outside a consumer-owned `role="img"`), `hoverHighlight` (requires `colorBy`), `hoverRadius` (30), `animate` (boolean | {duration?, easing?, intro?}), `axisExtent` ("nice"|"exact" — pins first/last tick to data min/max; XY x/y + ordinal value axis only; override per XY axis with `frameProps.axes[i].extent`), `maxDevicePixelRatio` (canvas backing-store cap; defaults 3 desktop / 2 coarse-pointer or narrow viewports; canvases repaint on browser zoom / display-density changes).
|
|
21
|
+
`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke`, `strokeWidth`, `opacity`, `enableHover` (true), `tooltip` (boolean | "multi" | function | config), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading`, `loadingContent` (ReactNode; `false` suppresses), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations`, `accessibleTable` (true; use `{ portalTarget: "element-id" }` to portal its interactive UI outside a consumer-owned `role="img"`), `hoverHighlight` (requires `colorBy`), `hoverRadius` (30), `animate` (boolean | {duration?, easing?, intro?}), `axisExtent` ("nice"|"exact" — pins first/last tick to data min/max; XY x/y + ordinal value axis only; override per XY axis with `frameProps.axes[i].extent`), `maxDevicePixelRatio` (canvas backing-store cap; defaults 3 desktop / 2 coarse-pointer or narrow viewports; very large canvases are further capped to an 8-megapixel, 16K-side backing-store budget; canvases repaint on browser zoom / display-density changes).
|
|
22
22
|
|
|
23
23
|
This list is not global. Plain value components do not inherit chart-HOC props and must be
|
|
24
24
|
validated against their own schema. In particular, `BigNumber` uses `label`, `description`, and
|
|
@@ -31,42 +31,44 @@ validated against their own schema. In particular, `BigNumber` uses `label`, `de
|
|
|
31
31
|
|
|
32
32
|
## XY Charts (`semiotic/xy`)
|
|
33
33
|
|
|
34
|
-
**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `band` ({y0Accessor, y1Accessor, style?, perSeries?, interactive?} or array for fan charts; participates in yExtent; non-interactive by default), `directLabel`, `gapStrategy`, `xScaleType` ("linear"|"log"|"time"), `yScaleType` ("linear"|"log"|"symlog"), `styleRules` (per-series), `tooltip="multi"` for hover-anywhere
|
|
34
|
+
**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `band` ({y0Accessor, y1Accessor, style?, perSeries?, interactive?} or array for fan charts; participates in yExtent; non-interactive by default), `directLabel`, `gapStrategy`, `xScaleType` ("linear"|"log"|"time"), `yScaleType` ("linear"|"log"|"symlog"), `styleRules` (per-series), `brush` (x-axis overlay; also enabled by `linkedBrush`), `tooltip="multi"` for hover-anywhere
|
|
35
35
|
**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `semanticGradient` (`{stops: [{offset: 0–1, color?, opacity?}]}`; offset follows the resolved y-domain), `semanticLine` (true with semanticGradient; false keeps the normal stroke/lineGradient), `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
|
|
36
36
|
**DifferenceChart** — Two-series A/B. Fills between with `seriesAColor` where A>B, `seriesBColor` where B>A; crossovers interpolated. `data`, `xAccessor`, `seriesAAccessor` ("a"), `seriesBAccessor` ("b"), `seriesALabel`/`seriesBLabel`, `seriesAColor` (var(--semiotic-danger))/`seriesBColor` (var(--semiotic-info)), `showLines` (true), `lineWidth` (1.5), `showPoints` (false), `pointRadius` (3), `curve` ("linear"), `areaOpacity` (0.6), `gradientFill`, `xExtent`/`yExtent`, `pointIdAccessor`, `windowSize`. Push via `ref.push({x,a,b})`. Accessor outputs coerce through `toNumber`.
|
|
37
37
|
**BumpChart** — Ranking-over-x. Each x-column ranks series by `yAccessor`; rank is vertical position. `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy` ("series"), `rankDirection` ("descending"|"ascending"), `ribbon` (false — encode magnitude as true perpendicular-offset ribbon width instead of fixed-width lines; line↔ribbon share centerline geometry so `animate` tweens width only), `curve` ("smooth"|"linear"), `ribbonSizeRange` ([4,28]), `samplesPerSegment` (12), `lineWidth` (3), `highlightTop` (color only the N best series by mean rank; the rest share `neutralColor`), `neutralColor`, `styleRules` (per-series; resolve against each series' first observation), `showPoints`, `showLabels` (true|"start"|"end"|"both"|"auto"; endpoint collisions are shed deterministically), `labelPriorityAccessor` / `maxLabels` (prioritize and cap labels under `showLabels="auto"`), `hoverHighlight`, `annotations` (x may use original x values incl. `Date`). Wraps XYCustomChart.
|
|
38
38
|
**StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` ("zero"|"wiggle" streamgraph|"silhouette" centered), `stackOrder` ("key"|"insideOut"|"asc"|"desc"). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`. `tooltip="multi"` interpolates between samples.
|
|
39
|
-
**Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `symbolBy` (categorical field → glyph **shape**: each mark becomes a d3-shape glyph; size still tracks `sizeBy`/`pointRadius`), `symbolMap` ({category → shape}; unmapped auto-assign — pass it for legend-matchable shapes), `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `styleRules` (per-point; `axis:"x"`/`"y"` thresholds), `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
|
|
39
|
+
**Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `symbolBy` (categorical field → glyph **shape**: each mark becomes a d3-shape glyph; size still tracks `sizeBy`/`pointRadius`), `symbolMap` ({category → shape}; unmapped auto-assign — pass it for legend-matchable shapes), `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `styleRules` (per-point; `axis:"x"`/`"y"` thresholds), `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay), `brush` (xy overlay; also enabled by `linkedBrush`)
|
|
40
40
|
**BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
|
|
41
41
|
**ConnectedScatterplot** — + `orderAccessor`, `regression`
|
|
42
42
|
**QuadrantChart** — Scatterplot + `quadrants`, `xCenter`, `yCenter`
|
|
43
43
|
**MultiAxisLineChart** — Dual Y-axis. `series` (`[{yAccessor, label?, color?, format?, extent?}]`). Falls back to multi-line if ≠ 2 series.
|
|
44
|
-
**Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `customColorScale`, `showValues`, `cellBorderColor`
|
|
45
|
-
**ScatterplotMatrix** — `fields` (numeric field names)
|
|
46
|
-
**MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart.
|
|
44
|
+
**Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `customColorScale`, `showValues`, `cellBorderColor`, `styleRules` (displayed cells; aggregate cells expose `count`, `sum`, `agg`, bin centers, and the displayed aggregate as `ctx.value`)
|
|
45
|
+
**ScatterplotMatrix** — `fields` (numeric field names). `renderChart()` emits one standalone composite SVG containing every off-diagonal scatter scene, diagonal distribution, field label, and categorical legend; interactive brushing/hover remains a browser affordance.
|
|
46
|
+
**MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart. `renderChart()` preserves both scenes and paints a supplied `brushExtent` into the overview, so the standalone snapshot retains the selected-detail/context relationship.
|
|
47
47
|
**CandlestickChart** — `xAccessor`, `highAccessor` (req), `lowAccessor` (req), `openAccessor`+`closeAccessor` (optional → OHLC; high/low only → range). `candlestickStyle` ({upColor, downColor, wickColor, rangeColor, bodyWidth, wickWidth}). Honors `mode`.
|
|
48
|
+
**WaterfallChart** — cumulative signed steps as floating bars. `xAccessor` ("x"), `yAccessor` ("y" — each row is a **delta**, not a running total), `positiveColor`, `negativeColor`, `connectorStroke`, `connectorWidth`, `gap`. String/categorical x values are plotted by index. Live window: `RealtimeWaterfallChart`.
|
|
48
49
|
|
|
49
50
|
## Ordinal Charts (`semiotic/ordinal`)
|
|
50
51
|
|
|
51
|
-
**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`
|
|
52
|
+
**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`, `brush` (value-axis overlay; `onBrush` / `linkedBrush`)
|
|
52
53
|
**StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order), `styleRules`
|
|
53
54
|
**GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default), `styleRules`
|
|
54
55
|
**SwarmPlot** — `colorBy`, `sizeBy`, `symbolBy` (categorical field → glyph shape, like Scatterplot), `symbolMap`, `pointRadius`, `pointOpacity`
|
|
55
56
|
**BoxPlot** — + `showOutliers`, `outlierRadius`
|
|
56
|
-
**Histogram** — + `bins` (25), `relative
|
|
57
|
+
**Histogram** — + `bins` (25), `relative`, `brush` (value-axis overlay; `onBrush` / `linkedBrush`). Always horizontal.
|
|
57
58
|
**ViolinPlot** — + `bins`, `curve`, `showIQR`
|
|
58
59
|
**RidgelinePlot** — + `bins`, `amplitude` (1.5)
|
|
59
60
|
**DotPlot** — + `sort` ("auto"), `dotRadius`, `showGrid` (true default), `regression`
|
|
60
61
|
**PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
|
|
61
62
|
**DonutChart** — PieChart + `innerRadius` (60), `centerContent`
|
|
62
63
|
**FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor?`, `connectorOpacity`, `orientation`
|
|
64
|
+
**RadarChart** — multivariate comparison on a shared radial axis. Long-form rows: one observation per series × attribute. `categoryAccessor` ("attribute"), `valueAccessor` ("value"), `seriesAccessor` (defaults to `colorBy`), `pointRadius` (4), `valueExtent` (`[0, data-max]` default). Axes must be comparable magnitudes.
|
|
63
65
|
**SwimlaneChart** — `categoryAccessor`, `subcategoryAccessor` (req), `valueAccessor`, `colorBy` (defaults to subcategoryAccessor), `orientation`, `roundedTop` (pixel radius on outer ends of each lane; middles stay square; single-segment lanes round all four)
|
|
64
66
|
**LikertChart** — `categoryAccessor`, `valueAccessor`|`levelAccessor`+`countAccessor`, `levels?`, `orientation`, `colorScheme`
|
|
65
67
|
**GaugeChart** — `value` (req), `min`, `max`, `thresholds`, `arcWidth`, `cornerRadius` (rounded segment ends), `sweep`, `fillZones`, `showNeedle`, `centerContent`
|
|
66
68
|
|
|
67
|
-
All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true).
|
|
69
|
+
All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `showCategoryTicks` (true), `styleRules`. Raw-mark charts use `valueAccessor`; box/violin/ridgeline use the rendered category median and expose `n`/`min`/`q1`/`median`/`q3`/`max`/`mean`; Histogram uses displayed bin count and exposes `bin`/`count`/`range`/`category`; Pie/Donut use absolute wedge magnitude; Likert uses displayed signed percentage; Gauge rules see synthetic zone segments (`category`, proportional `value`, `_zone`, `_isFill`).
|
|
68
70
|
|
|
69
|
-
**`styleRules`** (declarative threshold-aware styling — **every chart family**) — an ordered `StyleRule[]` where each `{ when, style }` matching a mark contributes its style, merged in list order so **the last applicable rule wins per property** (CSS-cascade model). Wired on: **ordinal
|
|
71
|
+
**`styleRules`** (declarative threshold-aware styling — **every chart family**) — an ordered `StyleRule[]` where each `{ when, style }` matching a mark contributes its style, merged in list order so **the last applicable rule wins per property** (CSS-cascade model). Wired on: **all 16 ordinal HOCs**; **XY** LineChart/AreaChart/StackedAreaChart/BumpChart (per-series), Scatterplot/BubbleChart/QuadrantChart/ConnectedScatterplot (per-point), and Heatmap (displayed cells); **network** ForceDirectedGraph/SankeyDiagram/ProcessSankey/ChordDiagram plus Tree/Treemap/CirclePack/Orbit (authored nodes); **realtime** Line/Histogram/TemporalHistogram/Swarm/Waterfall/Heatmap; **geo** ChoroplethMap (features) plus ProportionalSymbolMap/DistanceCartogram (symbols); **physics** GaltonBoard/UnitPile/CollisionSwarm/EventDrop/PacketFlow (particles or packets). `when` = predicate `(datum, ctx) => boolean`, a declarative threshold (`{ axis?: "x"|"y"|"value", field?, gt, gte, lt, lte, eq, ne, within:[min,max], outside, in:[...] }`), or `true`/omitted (always). `ctx` channels are host-resolved: ordinal `{ value, category }`; XY `{ value(=y), x, y }`; node/feature/particle families `{ value, category }`; aggregate Heatmap/Histogram forms use the displayed aggregate and retain fields such as `count`, `sum`, `agg`, and `range`. A rule's style may include `cursor` plus normal fill/stroke/opacity fields; `style.fill` may be a color string or a **`HatchFill`** descriptor (`{ type:"hatch", background?, stroke?, spacing?, angle?, lineWidth?, lineOpacity? }`) resolving to a `CanvasPattern` on canvas and an SVG `<pattern>` in SSR. Precedence: top-level primitives > per-mark style fn (`pieceStyle`/`pointStyle`/`nodeStyle`) > `styleRules` > base `colorBy`/`color`/theme. Works through `renderChart`/MCP for every SSR-capable wired form (use declarative thresholds, not predicates, across JSON boundaries). Caveats: line/area rules resolve per-series, not per-vertex; MultiAxisLineChart, MinimapChart, CandlestickChart, DifferenceChart, WaterfallChart, and ScatterplotMatrix are not wired. Exported from `semiotic` + each family entry + `semiotic/utils`: `StyleRule`, `resolveStyleRules`, `matchesThreshold`, `makeRuleValueResolver`, `makeXYRuleContext`, `makeNodeRuleContext`, `composeStyleRules`, `HatchFill`, `isHatchFill`. See `/features/style-rules`.
|
|
70
72
|
|
|
71
73
|
## Network Charts (`semiotic/network`)
|
|
72
74
|
|
|
@@ -104,11 +106,11 @@ Process/arrival/distribution charts backed by `StreamPhysicsFrame`. The settled
|
|
|
104
106
|
**ProcessFlowChart** — multi-body workflow lane. `data`, `stages` (required: `[{id, label?, force?, damping?, capacity?, pressure?, portal?, absorb?, share?}]`), `stageAccessor` ("stage"), `idAccessor`, `groupBy` (optional feature key; completion when all members hit an absorb stage), `groupLabelAccessor`, `workAccessor`, `radiusAccessor`, `ballRadius` (6), `colorBy`, `groupCompletion` ("allAbsorbed"|"none"), `groupAnchorAlong` (0.55), `showProjection` (true), `showChrome` (true — processChrome kit), `liveCapacity` (true — FIFO queues at `unitsPerSecond`), `onCapacityChange` (queue depth / processed), `bodyLimit` (soft stream budget + oldest eviction), `bodyMark` ("circle"|"halo"|"faceted"|"pill"|"diamond"|"square" or per-row `datum.__physicsMark`), `selection`, `settle`, `seed`, `size`, `paused`, `frameProps`. Settled projection is stage occupancy + capacity badges; use for review queues / triage / merge pipelines. Prefer **GauntletChart** for one compound plan with timed gate effects.
|
|
105
107
|
**Stage geography kit** (`semiotic/physics` + `semiotic/recipes`) — `physicsStageGeography({size, flow ("down"|"right"), destinations (count | [{id,label}]), padding, chargeExtent, destinationExtent, projectionExtent, channelRatio})` → `{charge, apparatus, destinations: [{id,label,order,centerX,centerY,…}], projection}`. The shared **charge → apparatus → destinations** vocabulary every physics chart re-invented locally (Gauntlet `startX`/`socketX`/`graveyardX`, Crucible `chamber`/`mouth`/`outlets`, Galton bins and Pile tubes writing the *same* lane formula). Companions: `physicsStageColliders` (floor + one divider per interior boundary, so bodies land in the bin the data says), `physicsChargePoint` (spread a burst across the entry zone instead of co-locating it), `physicsDestination(geo, id)`, `describePhysicsStageGeography` (one-sentence reading protocol for a11y/agent grounding). Authoring vocabulary for a **new** chart or `PhysicsCustomChart` layout — shipped charts keep their own layouts; a test pins the builder to their lane math.
|
|
106
108
|
**Terminal state (event-tape charts)** — a tape-driven physics chart's end state must be computable from authored inputs with no simulation, because that pure result is what reduced motion, SSR, snapshot export, and `describeChart` receive. `CrucibleChart`: `compileCruciblePlan(...)` → `plan.initialState`/`plan.terminalState`/`plan.terminalSpawns`. `ChainReactionChart`: `initialRuntime(machine, mode, currentTime, true)`. `GauntletChart`: **`resolveGauntletTerminalStates({projects, events, layout, positiveProperties, negativeProperties, viability?, outcome?})`** (also `resolveGauntletTerminalState` for one project) — folds the authored tape, mirroring the live tick's effect order. Caveat: with Gauntlet's `crashDetection` armed (default), physics can still override the outcome to `bad_design_crash`, which no pure fold can predict; the pure result is "what the plan earns on paper". Pass `crashDetection={false}` for a fully authored reading. **Design test for a new physics metaphor:** can you state its ledger in one sentence (else it's an animation), does its terminal state exist without simulating (else it's a movie), would a naive reader guess the reading protocol from the apparatus (else the name is wrong)?
|
|
107
|
-
**Physics family contracts** (every physics HOC) — `seed` (deterministic; an explicit `frameProps.config.kernel.seed` still wins), `rerunMS` (settle → delay → deterministic replay; `null`/omitted = single run), `showProjection`, `paused`, and `selection` + `linkedHover`. `selection` accepts **either** a `{ name }` `SelectionConfig` — joining the shared selection store so physics bodies cross-highlight inside `LinkedCharts` like every other family — **or** a resolved `{ isActive, predicate }` `PhysicsBodySelection` body predicate as the escape hatch. The store's datum predicate is lifted over `body.datum`, so chrome bodies (walls, pegs, tubes) never match a data selection. Under `prefers-reduced-motion` the frame settles to the true end state in one pass: paced arrivals (`initialSpawnPacing`, per-datum `spawnAt`) are all admitted and elapsed-time event tapes run to completion, so the settled projection reports the outcome rather than the authored start.
|
|
109
|
+
**Physics family contracts** (every physics HOC) — `seed` (deterministic; an explicit `frameProps.config.kernel.seed` still wins), `rerunMS` (settle → delay → deterministic replay; `null`/omitted = single run), `onSimulationStateChange(state, previousState)` (public running/settled readiness without reaching into `frameProps.config`), `showProjection`, `paused`, and `selection` + `linkedHover`. `selection` accepts **either** a `{ name }` `SelectionConfig` — joining the shared selection store so physics bodies cross-highlight inside `LinkedCharts` like every other family — **or** a resolved `{ isActive, predicate }` `PhysicsBodySelection` body predicate as the escape hatch. The store's datum predicate is lifted over `body.datum`, so chrome bodies (walls, pegs, tubes) never match a data selection. Under `prefers-reduced-motion` the frame settles to the true end state in one pass: paced arrivals (`initialSpawnPacing`, per-datum `spawnAt`) are all admitted and elapsed-time event tapes run to completion, so the settled projection reports the outcome rather than the authored start.
|
|
108
110
|
**Physics controllers** (`createCapacityQueueController`, `createPortalController`, `composePhysicsControllers`) — process plugins via `controllers`. Capacity `getSnapshot()` → queueDepth/processedCount; emit `physics-capacity-processed`. **processChrome** (`semiotic/physics` / `semiotic/recipes`) — stage bays, capacity badges, feature sockets (theme: `--semiotic-process-*`). `PhysicsCustomChart`: `layout()` may return `regionEffects`, `controllers`, `bodyForces`; `layoutConfig` hot path without re-enqueue. Guide: `/features/physics-process-guide`. Contracts: `PhysicsContracts.test.tsx`.
|
|
109
111
|
**GauntletChart** — compound project core + tethered positive/negative property bodies + timed gate events. `positiveProperties`/`negativeProperties` (req), `gates`, `events`, `showChrome` (true), `showProjection` (true — viability/outcome strip), `showTethers` (true), `onStateChange`, `frameProps`. Bodies clamp inside walls (`clampGauntletPoint`). Not for multi-item factory floors (use ProcessFlowChart).
|
|
110
112
|
**CrucibleChart** — bounded peer components undergo authored `phases` and `events`, form declared `products`, and settle into reason-labelled `outlets` with source lineage. The ledger/projection is authoritative; motion never infers classification, timing, membership, loss, or routing. `buildCrucibleProductEvents({productId, form, contributions?, complete})` is pure authoring sugar for `combine → contribute* → complete-product`; every source/relation id, event position, reason, and outlet remains caller-supplied. The ref handle's `replay()` atomically restarts the deterministic tape even mid-run (`reset()` restores-and-pauses; `rerunMS` repeats after settlement). `playbackRate` changes presentation only. No push/live-event API.
|
|
111
|
-
**ChainReactionChart** — dependency chain reaction. `data`, `taskIDAccessor`, `labelAccessor`, `laneAccessor`, `dependencyAccessor` (all required — edges are never inferred), plus optional `startAccessor`/`endAccessor`/`progressAccessor`/`statusAccessor`/`completionTimeAccessor`/`blockerAccessor`/`milestoneAccessor`. Tasks place by workstream lane × dependency depth; a completed task releases one delivery ball per outgoing edge and a downstream task arms only once every prerequisite ball arrives, so a blocked task's *reach* is the reading. `mode` ("snapshot" derives the settled state at `currentTime` with no simulation | "replay" animates deliveries over that same derived state | "mechanical"), `insight` ("blocker-amplification" reports unfinished downstream tasks + affected lanes), `controls` (play/pause/step/reset/settle), `selectedTaskIDs`/`onSelectionChange`, `reducedMotion: "settle"`, `seed`. Ref handle: `play`/`pause`/`step`/`reset`/`settle`, `previewResolve(taskID)`/`clearPreview` (ask "what would resolving this blocker unlock?" without editing data), `completeTask`/`blockTask`/`unblockTask`, `getAmplification`, `getMachineState`. Task completion is always an explicit data event — the simulation delivers prerequisites, it never decides done.
|
|
113
|
+
**ChainReactionChart** — dependency chain reaction. `data`, `taskIDAccessor`, `labelAccessor`, `laneAccessor`, `dependencyAccessor` (all required — edges are never inferred), plus optional `startAccessor`/`endAccessor`/`progressAccessor`/`statusAccessor`/`completionTimeAccessor`/`blockerAccessor`/`milestoneAccessor`. Tasks place by workstream lane × dependency depth; a completed task releases one delivery ball per outgoing edge and a downstream task arms only once every prerequisite ball arrives, so a blocked task's *reach* is the reading. `mode` ("snapshot" derives the settled state at `currentTime` with no simulation | "replay" animates deliveries over that same derived state | "mechanical"), `insight` ("blocker-amplification" reports unfinished downstream tasks + affected lanes), `controls` (play/pause/step/reset/settle), `selectedTaskIDs`/`onSelectionChange`, `reducedMotion: "settle"`, `seed`. Ref handle: `play`/`pause`/`step`/`reset`/`settle`, `previewResolve(taskID)`/`clearPreview` (ask "what would resolving this blocker unlock?" without editing data), `completeTask`/`blockTask`/`unblockTask`, `getAmplification`, `getMachineState`. Task completion is always an explicit data event — the simulation delivers prerequisites, it never decides done. `renderChart()` emits the authored task/dependency projection at `currentTime`, including blocker reach and selection; it deliberately omits arbitrary in-flight delivery-ball positions because those are replay state, not the chart's ledger.
|
|
112
114
|
**Pop (body-removal burst)** — every physics HOC ref is a `PhysicsFrameHandle` (extends the shared push handle) exposing **`popBodies(ids, options?)`** (`StreamPhysicsPopOptions` = `{ color?, durationMs?, radius? }`): removes the bodies and plays a burst — expanding ring + inner glow + radial sparks fading over `durationMs` (`drawPopAnimations`) — returning the removed ids. It reads as a *departure*, the physics/exit-emphasis counterpart to realtime **`pulse`**'s data-*arrival* glow (the same transient-emphasis metaphor on opposite ends of a datum's life). GauntletChart also fires it internally on gate-driven property removal; `/examples/nimby` (civic-value balloons) and `/examples/merge-pressure` (merge-risk traits) drive it that way.
|
|
113
115
|
|
|
114
116
|
## Value Charts (`semiotic/value`)
|
|
@@ -135,7 +137,7 @@ Helpers exported: `buildFormatter`, `formatSignedDelta`, `formatDeltaPercent`, `
|
|
|
135
137
|
|
|
136
138
|
Push API: `ref.current.push({time, value})`. All pushed data must include a time field.
|
|
137
139
|
|
|
138
|
-
**RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`; **stacked** via `categoryAccessor` + `colors` — bars sum by category within each bin; **mirrored/diverging** via `direction="down"` flipping the value domain — pair two halves with a shared `timeExtent`/`valueExtent` for an up/down detail view, and overlay extra instances on the same extent for layered envelopes), **TemporalHistogram** (static sibling — same props minus `windowSize`/`windowMode`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap** (+ sequential `colorScheme`; use `colorScheme="custom"` with `customColorScale(value)` for a custom ramp), **Streaming Sankey** (StreamNetworkFrame + `showParticles`).
|
|
140
|
+
**RealtimeLineChart**, **RealtimeHistogram** (+ `brush`, `onBrush`, `linkedBrush`, `direction`; **stacked** via `categoryAccessor` + `colors` — bars sum by category within each bin; **mirrored/diverging** via `direction="down"` flipping the value domain — pair two halves with a shared `timeExtent`/`valueExtent` for an up/down detail view, and overlay extra instances on the same extent for layered envelopes), **TemporalHistogram** (static sibling — same props minus `windowSize`/`windowMode`), **RealtimeSwarmChart**, **RealtimeWaterfallChart**, **RealtimeHeatmap** (+ sequential `colorScheme`; use `colorScheme="custom"` with `customColorScale(value)` for a custom ramp), **Streaming Sankey** (StreamNetworkFrame + `showParticles`). All six named realtime chart forms expose `styleRules`; aggregate histogram/heatmap rules resolve against displayed bins/cells rather than arbitrary source rows.
|
|
139
141
|
|
|
140
142
|
All five realtime wrappers accept a top-level `cursor` as a presentation-only default for retained marks; `RealtimeSwarmChart.pointStyle` can override it per datum. Pair actionable cursors with explicit click or observation behavior.
|
|
141
143
|
|
|
@@ -147,6 +149,7 @@ Encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely.
|
|
|
147
149
|
|
|
148
150
|
### Push API on HOC charts
|
|
149
151
|
Most HOCs support push via `forwardRef`. **Omit** `data` — do NOT pass `data={[]}`.
|
|
152
|
+
TypeScript: `RealtimeFrameHandle<TDatum, TReadDatum = TDatum>` preserves the authored row through `push`, `pushMany`, `remove`, `update`, and `getData`; omitting parameters retains the loose 3.x `Datum` contract. RealtimeLineChart aggregate mode accepts source `TDatum` but materializes `AggregatedRealtimeDatum`, exposed through `RealtimeLineChartHandle<TDatum, AggregatedRealtimeDatum>`.
|
|
150
153
|
```jsx
|
|
151
154
|
const ref = useRef()
|
|
152
155
|
ref.current.push({ id: "p1", x: 1, y: 2 })
|
|
@@ -173,12 +176,44 @@ When the catalog doesn't fit, four HOCs take a layout function emitting scene pr
|
|
|
173
176
|
- **`NetworkCustomChart`** (`semiotic/network`) — flextree, dagre, custom force/radial, packed-cluster beeswarm matrix
|
|
174
177
|
- **`GeoCustomChart`** (`semiotic/geo`) — isometric landmark boards, custom geographic tessellations
|
|
175
178
|
|
|
179
|
+
### Built-in portable recipes
|
|
180
|
+
|
|
181
|
+
`ParallelCoordinatesRecipe` and `CalendarHeatmapRecipe` are the first custom
|
|
182
|
+
forms promoted into the serialized catalog. They are discoverable through
|
|
183
|
+
`suggestCharts`, `getSchema`, the CLI/MCP schema index, and the server renderer.
|
|
184
|
+
Their component names are serialization and rendering identifiers; React uses
|
|
185
|
+
the generic host rather than one-off HOCs:
|
|
186
|
+
|
|
187
|
+
```jsx
|
|
188
|
+
import { ChartRecipe } from "semiotic/ai"
|
|
189
|
+
|
|
190
|
+
<ChartRecipe
|
|
191
|
+
recipeId="ParallelCoordinatesRecipe"
|
|
192
|
+
data={rows}
|
|
193
|
+
layoutConfig={{ fields: ["mpg", "power", "weight"], colorBy: "origin" }}
|
|
194
|
+
title="Vehicle profiles"
|
|
195
|
+
description="Vehicle profiles across independently scaled measures."
|
|
196
|
+
summary="No vehicle dominates every measure."
|
|
197
|
+
accessibleTable
|
|
198
|
+
/>
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
The serialized equivalent is
|
|
202
|
+
`{ component: "ParallelCoordinatesRecipe", props: { data, layoutConfig,
|
|
203
|
+
title, description, summary, accessibleTable: true } }`; substitute
|
|
204
|
+
`CalendarHeatmapRecipe` with `layoutConfig: { dateAccessor, valueAccessor,
|
|
205
|
+
year? }` for the calendar form. Both names work with `renderChart` and
|
|
206
|
+
`renderChartWithEvidence`. Import the raw `parallelCoordinatesLayout` or
|
|
207
|
+
`calendarLayout` from `semiotic/recipes` only for React-only callbacks or
|
|
208
|
+
bespoke frame control. `semiotic/ai/core` exposes their manifests and discovery
|
|
209
|
+
metadata without importing the chart renderer or layouts.
|
|
210
|
+
|
|
176
211
|
Layout signature differs by family:
|
|
177
212
|
- **XY/Ordinal**: `layout: (ctx) => { nodes, overlays? }`. `ctx`: `data`, `scales` ({x,y} XY | {o,r,projection} ordinal), `dimensions` (plot rect — center-anchored for radial ordinal, top-left otherwise), `theme`, `resolveColor(key)`, `config`.
|
|
178
|
-
- **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays?, htmlMarks? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc/**symbol**/**glyph** nodes; line/bezier/curved edges). The `symbol` node is the per-datum **shape** channel — a `d3-shape` glyph (`circle`/`square`/`triangle`/`diamond`/`star`/`cross`/`wye`/`chevron`, or a custom `path`) sized by `size` (area), rendered on canvas + SVG/SSR and hit-tested + keyboard-navigated as a unit. **The `symbol` mark is cross-pipeline**: XY and ordinal custom layouts emit it too (`{type:"symbol", x, y, size, symbolType}` — note `x`/`y`, vs the network variant's `cx`/`cy`), and Scatterplot/SwarmPlot expose it as the `symbolBy` encoding. One shared `symbolPath` implementation backs canvas/SVG/hit-test across all three families.
|
|
213
|
+
- **Network**: `layout: (ctx) => { backgrounds?, sceneNodes?, sceneEdges?, labels?, overlays?, htmlMarks? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). `backgrounds` is plot-space SVG painted below the canvas/static scene (for fitted regions and enclosures); `overlays` paints above it. Both are included in SSR/static SVG and do not add hit targets. Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc/**symbol**/**glyph** nodes; line/bezier/curved edges). The `symbol` node is the per-datum **shape** channel — a `d3-shape` glyph (`circle`/`square`/`triangle`/`diamond`/`star`/`cross`/`wye`/`chevron`, or a custom `path`) sized by `size` (area), rendered on canvas + SVG/SSR and hit-tested + keyboard-navigated as a unit. **The `symbol` mark is cross-pipeline**: XY and ordinal custom layouts emit it too (`{type:"symbol", x, y, size, symbolType}` — note `x`/`y`, vs the network variant's `cx`/`cy`), and Scatterplot/SwarmPlot expose it as the `symbolBy` encoding. One shared `symbolPath` implementation backs canvas/SVG/hit-test across all three families.
|
|
179
214
|
- **The `glyph` node — composite pictograms (ALL FOUR families incl. geo)**: where `symbol` is one path, `glyph` stamps a multi-part vector pictogram — a `GlyphDef` (`{viewBox?, anchor?, parts: [{d, fill?, stroke?, strokeWidth?, opacity?}]}`) whose parts declare **role paints** (`"color"`/`"accent"`/literal) resolved per node (`color`/`accent` props), so one definition recolors per category like a pictogram plate reused in many inks. `{type:"glyph", x, y, size, glyph, color?, accent?, fraction?, fractionStart?, fractionDirection?, ghostColor?, rotation?, style, datum, pointId?}` (network variant uses `cx`/`cy` + `id`/`label`). `size` = rendered **height** px (width follows viewBox aspect); `anchor: [0.5, 1]` stands a sign's feet on a baseline/terrain. **Partial fills**: `fraction`/`fractionStart` clip a `[start, end]` window (horizontal or bottom-up vertical) with an optional full-extent `ghostColor` silhouette — the ISOTYPE partial-symbol convention, fed directly by `unitize`. Full pipeline citizen: canvas + SVG/SSR, hit-test + keyboard nav over the drawn bounds, `pointId`/`id` annotation anchoring, and enter/move/exit transition identity (which `symbol` lacks). Datum-less glyph nodes (`datum: null`) paint but don't hit-test/navigate — use one `hitTarget` per logical mark under a multi-sign tally. `<Glyph def size color …/>` (from `semiotic/recipes`) renders the same definition as React SVG for overlays/legends/decoration; `glyphPlacement`/`glyphExtent` expose its geometry for layout math.
|
|
180
215
|
- **Geo**: `layout: (ctx) => { nodes?, overlays? }`. `ctx`: `areas`, `points`, `lines`, fitted `GeoScales`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection`. Emit `geoarea`/`point`/`line`/`glyph` nodes; use overlays for labels and sprites.
|
|
181
|
-
- **`htmlMarks`** (network only): `NetworkHtmlMark[]` = `{ id, x, y, width, height, content: ReactNode }`, positioned in the **same plot space as `sceneNodes`** and rendered into one real-DOM layer the framework places **above the canvas and SVG `overlays`** (stack: canvas → `overlays` → `htmlMarks`). Reach for it over an SVG `<foreignObject>` when a mark is **text-heavy/rich and dims or animates on hover** — a real `<div>` composites `opacity`/`transform`/`visibility` changes instead of re-rasterizing text (the `foreignObject` stall on large graphs). Framework owns the margin (and future zoom/pan) transform so marks stay pixel-aligned; each mark is its own element, keyed by `id` (position-only re-runs reposition without remounting). `pointer-events: none` by default — keep a transparent hit-rect `sceneNode` per mark so canvas hit-testing/`onObservation` stays authoritative. Mark `content` can read `useCustomLayoutSelection()` to dim on shared selection without a relayout. Additive: omit it and no extra DOM renders. Class hooks: `.semiotic-network-html-marks` (layer) / `.semiotic-network-html-mark` (each).
|
|
216
|
+
- **`htmlMarks`** (network only): `NetworkHtmlMark[]` = `{ id, x, y, width, height, content: ReactNode }`, positioned in the **same plot space as `sceneNodes`** and rendered into one real-DOM layer the framework places **above the canvas and SVG `overlays`** (stack: `backgrounds` → canvas → `overlays` → `htmlMarks`). Reach for it over an SVG `<foreignObject>` when a mark is **text-heavy/rich and dims or animates on hover** — a real `<div>` composites `opacity`/`transform`/`visibility` changes instead of re-rasterizing text (the `foreignObject` stall on large graphs). Framework owns the margin (and future zoom/pan) transform so marks stay pixel-aligned; each mark is its own element, keyed by `id` (position-only re-runs reposition without remounting). `pointer-events: none` by default — keep a transparent hit-rect `sceneNode` per mark so canvas hit-testing/`onObservation` stays authoritative. Mark `content` can read `useCustomLayoutSelection()` to dim on shared selection without a relayout. Additive: omit it and no extra DOM renders. Class hooks: `.semiotic-network-html-marks` (layer) / `.semiotic-network-html-mark` (each).
|
|
182
217
|
|
|
183
218
|
**Custom-chart authoring kit** (`semiotic/recipes`; `hitTarget*` also from `semiotic/xy`/`ordinal`/`network`). The shape every hand-built custom chart converges on — draw real marks in `overlays`, emit a **transparent scene node per mark** for interaction — is first-class:
|
|
184
219
|
- **`hitTargetPoint`/`hitTargetRect`** (XY/ordinal) + **`networkHitTarget`** (circle or rect) + **`geoHitTarget`** (geo — same transparent `PointSceneNode`; project lon/lat via `ctx.scales.projectedPoint` first): a zero-opacity, fully-transparent, hit-tested node from `{x, y, (r|width,height), datum, id, cursor?}`. The optional CSS `cursor` reaches the retained canvas and SVG/static output; it is presentation only, so pair `cursor:"pointer"` with the frame's click/observation API when the mark activates something. The `id` becomes the node's `pointId`/`id` (annotation anchor + nav-tree leaf) **and** its transition key. This is how a custom chart inherits **accessibility** (keyboard nav, focus ring, data table), **annotation** anchoring, **AI**/`onObservation` + shared selection, and **chart-mode** transitions for free — replaces the `rgba(0,0,0,0)`+`opacity:0`+`pointId`+`_transitionKey` boilerplate. The visible glyph lives in `overlays`; the focus ring still draws on the invisible target. A keyboard-focused **geoarea** outlines its polygon (a shape focus ring) rather than a centroid dot.
|
|
@@ -196,6 +231,8 @@ Layout signature differs by family:
|
|
|
196
231
|
|
|
197
232
|
`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `intervalLanesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`, `netEnsembleLayout`, `axisFixedForceLayout`, `packedClusterMatrix`, `isometricLandmarkLayout`, `forceLayout`, `arcLayout`, `adjacencyMatrix`, `circularLayout`). **Network-analysis kit** (`semiotic/recipes`, pure graph algorithms): `buildAdjacency`, `bfsDistances`, `shortestPath`, `egoNetwork`, `degree`/`betweenness`(Brandes)/`closeness`/`clustering` (+ `normalizeScores`), `analyzeNetEnsemble` (the headless net census — see `netEnsembleLayout` below), and `proximityProblem` — the "spatial problem" layout diagnostic that flags nodes drawn closer than their graph distance warrants. Pair with network charts to size by centrality, highlight an ego network on hover, trace a shortest path, or diagnose a misleading layout. `forceLayout(nodes, edges, {seed})` is a **seeded, deterministic** positioner returning normalized `{id:{x,y}}` for `NetworkCustomChart` (same seed ⇒ same layout; re-seed for a "re-run the layout" interaction); `forceLayoutAsync(nodes, edges, {execution?, workerThreshold?, signal?})` is its Promise sibling that runs large layouts in a short-lived module Web Worker (identical deterministic output; graceful sync fallback), and `useForceLayout(nodes, edges, options)` → `{positions, status, error}` is the React wrapper — SSR and first hydration stay synchronous for markup parity, client graph changes go async while previous positions stay visible, and settled positions are memoized by node/edge array identity + options so remounting the same module-constant graph is "ready" immediately (no loading flash). `arcLayout`/`adjacencyMatrix`/`circularLayout` (+ `orderByGroupDegree`, `arcPath`) are the classic physics-free network forms. `allocateCells` is the largest-remainder grid allocator behind `waffleLayout` (turn `{key, weight}[]` + a cell count into integer cells with no rounding drift; `minPerCategory` keeps small categories visible) — reusable for any feature-mix / proportional waffle. **`unitize(value, {unit, maxUnits?, minFraction?})` / `unitizeRange(value, rangeValue, opts)`** is the counting sibling: the pictogram/tally allocator (value → repeated unit signs with a fractional final sign — ISOTYPE: symbols repeat, they never grow). Returns `{units: [{index, fraction, start, end, value}], total, shown, overflow}` — `maxUnits` caps with an `overflow` flag, `minFraction` drops trailing slivers while `total` vs `shown` keeps the ledger honest; `unitizeRange` extends the tally to a projected/scenario endpoint (`rangeUnits` drawn hatched), sharing a mid-sign boundary exactly via `startFraction`. Feeds `glyph`-node `fraction`s directly (unit charts, sign stacks, arrow bundles; `allocateCells` divides fixed cells, `unitize` counts). **Tokenized reasoning helpers**: `generateTokens(input, tokenEncoding)` wraps `unitize` plus `actual`, `fixed-denominator`, `quantile`, `posterior-sample`/`sample`, and seeded `random-sample` strategies with explicit `tokenType` (`dot`/`icon`/`glyph`), `tokenSemantics` (`observed-unit`, `unitized-measure`, `risk-case`, `possible-outcome`, etc.), and `countStrategy`; `{ value, rangeValue }` yields `rangeTokens` for scenario/projection tallies. `layoutTokenGrid` places the resulting tokens for icon/glyph arrays; `normalizeTokenEncoding` keeps legacy `token`/`unit` aliases working while canonical configs use `icon`/`unitValue`; `diagnoseTokenEncoding`, `suggestTokenEncoding`, and `tokenTaskIntentToCapabilityIntents` expose IDID-style warnings, task-aware defaults, and a bridge to `suggestCharts` intents. Built-in token glyph names include `person`, `server`, `chip`, `bolt`, and `bus`. `intervalLanesLayout` (ordinal) packs concurrent `{start,end,lane}` records into stacked Gantt sub-tracks per lane with period bands + lane labels + a time axis — packing runs in rendered-pixel space and honors `minBarWidth` (2) so zero/short-duration events stay visible without overlapping same-track neighbors; `axisFixedForceLayout` (network) pins one axis from a field and settles the other (rect-aware collision). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `packedClusterMatrix` (network) bins records into a column×row matrix of **densely-packed beeswarm clusters** (deterministic self-contained packing, geometry cached) and emits **multi-channel glyphs** — hue (`colorAccessor`/`colorMap`), size (`sizeAccessor`, area), shade (`shadeAccessor`, CIELAB lightness), plus EITHER shape-encoding (`symbolAccessor`/`symbolMap` — the base mark becomes that shape) OR the **composite-glyph** model (`iconAccessor`/`iconMap` — base is a filled circle, only mapped values get a stroked inner icon). `rowMode:"banded"` (default) gives aligned global orbit-bands (row labels align, one enclosure spans the columns per band, columns vary in height) vs `"stacked"` (per-column cell heights ∝ count). `callouts:[{field,value,label}]` draws leader lines to named marks. `cellSizing:"proportional"` makes area ∝ count. **Recipe decoration kit** (exported from `semiotic/recipes`, for any custom-layout's `overlays`): `roundedEnclosure`/`boundsOf` (group/band borders), `bandLabel` (overflow-aware axis/band labels), `markCallout` (leader-line callout to a mark), `readField` (`node.data`-wrapper reader), `groupBy`, `dimFor` (the highlight/dim opacity rule — `{predicate?, highlight?, baseOpacity?, dimOpacity?, brighten?}`; `matchesHighlight` is its `{field,value}[]` matcher), `signatureKey`/`LayoutCache` (content-signature geometry cache so re-styling never re-runs an expensive layout — key by *content*, never by `ctx.nodes` identity), `legendGroupsFrom` (`{colorMap|keys, symbolMap?, sizeStops?}` → `LegendGroup[]` for `frameProps.legend`), `shade`/`makeShade`, `symbolPathString`/`symbolRadius`/`symbolExtent`/`SYMBOL_SEQUENCE`, and the small numeric/color one-liners every layout re-declares — `clamp`, `mean`, `withAlpha`, `nonNegativeFinite` (hex→`rgba()` so a hover-dim can ride a recipe's `resolveColor` callback). (`bandLabel`/`dimFor` are adopted by marimekko/bullet/parallelCoordinates/packedClusterMatrix.) `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip decoration in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`). `netEnsembleLayout` (network) is the complement — for **ensembles of disconnected/trivially-connected DAGs** (a "bag of little graphs" force layout scatters and dagre/flextree can't place). It splits into weakly-connected components, tests each for **directedness** (borrowing the mathematical *net*/directed-set idea: for a weakly-connected DAG, a single sink ⟹ everything converges to one limit; ≥2 sinks ⟹ it branches), fingerprints components with Weisfeiler–Leman refinement so **order-isomorphic motifs** group together, lays each out converging toward its sink(s) at the bottom, and arranges the ensemble as small multiples in motif bands (collapsing to one census glyph per component when cells get tiny). Config: `colorMode` (`"directedness"|"motif"|"category"`), `groupByMotif`, `sort`, `fingerprintRounds`, `minCellForFull`. `analyzeNetEnsemble(nodes, edges)` is the pure headless census (per-component `directed`/sink/source counts + motif classes) with no rendering. Demo + lay explanation at `/recipes/net-ensemble`.
|
|
198
233
|
|
|
234
|
+
For fitted lineage regions, set `lineageDagLayout`'s `hullGroupAccessor` (for example, `"subtopologyId"`). It emits one sorted, deterministic convex hull per present group through `NetworkLayoutResult.backgrounds`, behind edges/nodes in live and static SVG. Optional controls: `hullColors`, `hullPadding` (16), `hullRadius` (12), `hullFillOpacity` (0.08), `hullStrokeOpacity` (0.4), and `hullLabel`. Omitting `hullGroupAccessor` emits no background layer.
|
|
235
|
+
|
|
199
236
|
`tokenLayer({input, encoding, options})` is the high-level tokenized-rendering helper for custom layouts: it runs `generateTokens`, applies row/column/grid/waffle/dotplot/bar-segment/quantile-strip placement (or `positionToken` for scale/map-driven placement), and returns ordinary dot/symbol/glyph scene nodes with `pointId`/transition identity. Use it for ISOTYPE, icon arrays, risk grids, quantile dotplots, strips, and hybrid token overlays; pass `includeRange` to render `rangeTokens`; drop down to `generateTokens` when a bespoke layout only needs records.
|
|
200
237
|
|
|
201
238
|
**Decoration (labels/axes/legends): the recipe owns it.** Recipes emit own decoration via `overlays` return field (ReactNode painted on top). Built-in axes via `showAxes` on the HOC work for layouts respecting the standard scale. Recipe convention: `showXxx` boolean toggles, `xxxFormat` callbacks. Shipped recipes' toggles: marimekko `showCategoryLabels`, bullet `showLabels`+`showTicks`, parallelCoordinates `showAxes`, flextree/dagre `showLabels`, waffle/calendar none.
|
|
@@ -417,9 +454,9 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
|
|
|
417
454
|
|
|
418
455
|
**Agent-reader grounding**: `buildReaderGrounding(component, props, { capability?, audience?, includeStructure? })` (from `semiotic/ai` or `semiotic/utils`) → `{ description (L1–L3), intent (act + L4 sentence), structure (nav tree), text }` — the single payload an LLM reads to interpret a chart faithfully (the reader-side complement to a capability descriptor). MCP: `groundChart` tool.
|
|
419
456
|
|
|
420
|
-
**Structured navigation** (Olli/Data-Navigator model): `buildNavigationTree(component, props, { maxLeaves?, locale? })` (from `semiotic/ai` or `semiotic/utils`) → a `NavTreeNode` tree (chart → axis/series → datum), labels composed via describeChart. When `props.annotations` is present it appends an **Annotations** branch (`role: "annotation"`) so a reader encounters author notes during traversal — provenance + M7 editorial `status` surfaced inline, retracted and superseded notes skipped
|
|
457
|
+
**Structured navigation** (Olli/Data-Navigator model): `buildNavigationTree(component, props, { maxLeaves?, locale? })` (from `semiotic/ai` or `semiotic/utils`) → a `NavTreeNode` tree (chart → axis/series → datum), labels composed via describeChart. Complex families retain their reading structure: network nodes are grouped with link/flow branches; hierarchy parents announce direct children, total descendants, leaf counts, and leaf-value rollups (including zero/negative values); ChoroplethMap announces numeric coverage/range/average/total and then groups ranked regions into equal-width highest/middle/lowest thirds of the observed numeric range plus a no-value branch; other geo forms separate locations from routes. Empty thirds are omitted and all-equal metrics receive one explicit branch. Caps produce branch-local omission nodes rather than silently truncating. When `props.annotations` is present it appends an **Annotations** branch (`role: "annotation"`) so a reader encounters author notes during traversal — provenance + M7 editorial `status` surfaced inline, retracted and superseded notes skipped. `describeChart` also leads its text with an annotation sentence when annotations are present. `AccessibleNavTree` (from `semiotic` or `semiotic/ai`) renders it as a WAI-ARIA `tree` widget (arrows/Enter/Home/End, roving tabindex, `onActiveChange`, controlled `activeId` auto-expands to the node, `chartId` for telemetry), sr-only by default. With the conversation-arc store enabled it emits `nav-node-focused`/`nav-branch-expanded` reception events on genuine traversal (not on canvas-driven `activeId` changes). `<ChartContainer navigable chartConfig={...}>` mounts it (`navigable={{ visible?, maxLeaves? }}`). Audit's `compromising.navigable-structure` passes when `navigable` is on (incl. hierarchy charts). Audit options: `auditAccessibility(component, props, { inChartContainer?, describe?, navigable? })`.
|
|
421
458
|
|
|
422
|
-
**Bidirectional sync**: `useNavigationSync({ tree, chartId?, matchFields?, selectionName?, annotations? })` (from `semiotic` or `semiotic/ai`) → `{ activeId, onActiveChange, selection, annotatedIds, focusAnnotation }`. Tree→canvas highlights the matching mark (field-value selection); canvas→tree maps the hovered/clicked datum back to
|
|
459
|
+
**Bidirectional sync**: `useNavigationSync({ tree, chartId?, matchFields?, selectionName?, annotations? })` (from `semiotic` or `semiotic/ai`) → `{ activeId, onActiveChange, selection, annotatedIds, focusAnnotation }`. Tree→canvas highlights the matching mark (field-value selection); canvas→tree maps the hovered/clicked datum back to any semantic node carrying that authored datum, including hierarchy parents. GeoJSON `properties` are normalized to the direct-field shape emitted by StreamGeoFrame, so region sync works without nested-path configuration. Rides the module-global selection + observation stores — **no provider needed**: give the chart `chartId` + `selection={sync.selection}`, give `AccessibleNavTree` `activeId`/`onActiveChange`. **Annotation anchors**: pass the chart's `annotations` and an anchored annotation (carrying the datum's `matchFields`) resolves to a datum node — `annotatedIds` are the node ids with a note; `focusAnnotation(annotation | index)` jumps the tree + canvas to the anchored point so a non-visual reader can reach an AI's anchored note.
|
|
423
460
|
|
|
424
461
|
## Usage Notes
|
|
425
462
|
|