|
There is no SDK to install and no build step you are forced into. ProEssentialsJS is a set of static files that a browser fetches. A text editor and any web server are enough.
Two Tags
Every ProEssentialsJS page is two script tags, and that is the whole of the HTML. The first is the engine, one classic script. The second is your own code, as a module.
|
<script src="proessentials.iife.js"></script>
<script type="module" src="app.js"></script>
|
Inside app.js you import the property surface for the chart you want. That is an import in your own JavaScript, not another include, and it is what every JavaScript developer expects.
|
import { attachApi, Enums as E } from './pe-api-graph.js';
|
The others are pe-api-sgraph.js, pe-api-pie.js, pe-api-polar.js and pe-api-3d.js.
It cannot be one tag, and that is not a packaging shortcoming. The five property surfaces are real ES modules and a classic script cannot hold one. Charting libraries that ship both forms split on the same line.
There is no build step, no bundler, no import map and nothing to configure. No jsconfig.json, no tsconfig.json, no copying of assets, no path setting. The library resolves its own WebAssembly binary and its own built-in bitmaps against its own script URL rather than the page, so they are found wherever the library sits.
From A Repository
The starter repository is the shortest way in. The library is committed beside the page, so there is nothing to resolve and nothing to install.
|
git clone https://github.com/GigasoftInc/proessentials-js-starter.git
npm start
|
That is the whole procedure -- there is no npm install step, because the package has no dependencies -- the one script it defines runs a small static server so the page is served rather than opened from disk, which matters for the reason below.
Editor completion works with no configuration, because the TypeScript definitions sit next to the modules they describe. Nothing has to point at them.
From npm
In your own project the library comes from npm install and lives in node_modules, and nothing is committed.
|
npm install proessentials
|
The page is still two tags and one import. Installing from npm changes where they point, not how many there are.
|
<script src="./node_modules/proessentials/dist/proessentials.iife.js"></script>
<script type="module" src="app.js"></script>
|
|
import { attachApi, Enums as E }
from './node_modules/proessentials/dist/pe-api-graph.js';
|
Keep The Leading ./
This is the one mistake worth knowing before you make it, because it costs you the editor and nothing else. Both spellings run identically in the browser: the chart draws, nothing errors and nothing warns. Only completion goes quiet, which reads as though the package has no definitions rather than as a wrong path.
The import path |
In the editor |
'/node_modules/...' | Pego1 is any. No completions. |
'/node_modules/...' plus a jsconfig.json paths mapping | Still any. The obvious fix does not work -- paths is consulted for bare package names, not for something already read as an absolute path. |
'./node_modules/...' | Pego1 is the chart type, with full completion. |
A leading / is a perfectly good URL, which is why the page works. TypeScript reads it as a file system root and looks for the package at the root of the drive.
If dist Is Missing After Installing
Check which registry you installed from.
An install pointed somewhere unexpected can succeed, report that it added a package, and leave you a node_modules folder with no dist in it. Nothing fails, so the symptom appears later as two missing files on the page.
Correcting the registry alone does not recover it. A second npm install reports that you are up to date, because package-lock.json has recorded the address it resolved from and npm honours that. Install the version explicitly instead -- one command rewrites the dependency, the lock file and the installed files together.
|
npm install proessentials@11.0.0
|
Serve The Page. Do Not Open It From Disk.
A page opened with a file:// URL has no origin, and a browser will not fetch a WebAssembly module without one. Any static server will do; the starter includes one.
This catches people arriving from libraries that do work from disk. A plain script with no modules and no WebAssembly has nothing to fetch, so it opens happily. This one has both.
The one server setting that matters is that .wasm must be served as application/wasm. See Deployment.
What You Get
File |
Is |
proessentials.iife.js | The engine and the whole host library in one classic script -- drawing, menus, dialogs, scrollbars, tooltips and the 3D and WebGPU layers. This is the first of the two tags. |
proessentials.wasm | The engine itself. Fetched by the script above; never referenced from your page. |
pe-api-*.js | The property surface, one per chart object. This is where Pego, Pesgo, Pe3do, Pepco and Pepso get their properties and enumerations. Import the one you need. |
pe-api-*.d.ts | TypeScript definitions, generated from the same property model as the .NET assemblies and this help, with inline documentation. Nothing has to be configured for an editor to find them. |
bmps/ | The built-in bitmap resources, the same set the desktop engine carries. Located by the library itself. |
strings/ | Localized menu and dialog text, covering the same languages the desktop interfaces ship. |
See Deployment for what has to reach the browser and how large it is.
TypeScript
The definitions are generated from the same property model that produces the .NET assemblies and this help, so the names and the documentation agree by construction rather than by maintenance.
What the definitions declare is what is supported. The library puts other names on window; they are internal, and an editor will not offer them.
One Thing To Know About Colours
The engine takes a colour as 0xAABBGGRR -- red in the low byte. A colour copied across from a C# literal, which is ARGB, arrives with red and blue exchanged, and it does so silently: greys and any colour where red and blue happen to match look correct, so a palette can read two thirds right while being wrong.
Define one helper and never pack a colour by hand. The arguments are in the same order as .NET, so Color.FromArgb(60, 0, 180, 0) transliterates directly.
|
const PERGB = (a, r, g, b) =>
((r | (g << 8) | (b << 16) | (a << 24)) >>> 0);
|
Browser Requirements
WebAssembly and Canvas2D, which every current browser has. Nothing is required to be installed by the end user.
WebGPU is used where you ask for it, on one property. Set PeConfigure.RenderEngine to Direct3D and the control acquires a WebGPU device and composites a GPU layer into the chart. It is the same single property line the desktop uses, and it is not only for 3D:
| Lines |
A 2D Scientific Graph gets a GPU line layer. This is the path behind the large line-data speed records, and it is the common reason to set Direct3D. |
| Contours |
A contour plotting method gets a GPU contour layer. |
| Surfaces |
The 3D Scientific Graph gets a GPU surface layer. |
If the browser has no WebGPU device the control falls back to Direct2D and draws, rather than leaving you with bare axes. Everything else, Canvas2D, keeps working with no WebGPU at all.
Licensing
No license key is required to run any of this. There is no activation, no domain locking and no phone home. Nothing about installation differs between an evaluation and a purchased license. See ProEssentialsJS Licensing.
Next
ProEssentialsJS Walkthrough builds a chart from an empty page in ten steps. ProEssentialsJS Overview covers the object model and the four differences from .NET.
|
