@chartguard/config-highcharts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChartGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @chartguard/config-highcharts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Highcharts configuration validator. **Partial coverage**: a clean result means no confirmed error was found, not that the configuration is complete or correct (read `status`).
+
+**Status:** pre-release (0.x). Coverage is partial, and the API and settings may still change between minor versions.
+
+This package does **not** ship a schema derived from Highcharts. The Highcharts license does not clear redistributing option metadata derived from its declarations, so the full schema is generated on your machine from your own installed `highcharts`, under your own license.
+
+## Two ways to validate
+
+```ts
+import { readFileSync } from "node:fs";
+import { createValidator, validate } from "@chartguard/config-highcharts";
+
+// 1. A small hand-written subset, always available.
+validate(config);
+
+// 2. The full option set of your installed version, from a locally generated schema artifact.
+const validateFull = createValidator(JSON.parse(readFileSync(artifactPath, "utf8")));
+validateFull(config, { libraryVersion: "13.1.1" });
+```
+
+`createValidator` throws for a malformed artifact or one generated for another library.
+
+A series type added by a plugin is an unknown variant (a warning); describe it to have it checked: `createValidator(artifact, { extensions: [{ id: "flame3d", variants: { "highcharts.series": { flame3d: s.object({ depth: s.number() }) } } }] })` (`s` from `@chartguard/config-core`). A variant may extend a built-in series and add its own options (`{ flame3d: { extends: "line", schema: s.object({ depth: s.number() }) } }`); `chart.type: "flame3d"` then selects it for series without `type`. A built-in type cannot be replaced; a refused extension throws `ExtensionError`. A series without `type` is checked as the type the runtime gives it: `chart.type`, else `line` (the runtime's default); when `chart.type` cannot be read without running code, or names no known or described series type, the series is inconclusive (`CFG_AMBIGUOUS`), never checked against a guessed type.
+
+Generate the artifact from your installed `highcharts` with `npx chartguard schema build --library highcharts` (or `buildLocalSchema` from `@chartguard/schema-generator`); it is written to `node_modules/.cache/chartguard/highcharts-<version>.json`, which `chartguard validate --library highcharts` reads. Inside the ChartGuard repository, `npm run build` writes it there too.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type Extension, type SchemaManifest } from '@chartguard/config-core';
+import type { ConfigValidator, ValidationOptions, ValidationResult } from '@chartguard/core';
+export { type Extension, ExtensionError } from '@chartguard/config-core';
+/**
+ * The hand-written starter subset of the Highcharts options (partial coverage): no Highcharts-derived
+ * schema ships with this package. Union-typed fields stay open.
+ */
+export declare const manifest: SchemaManifest;
+/** Validates Highcharts options against the curated subset `manifest`; `createValidator` checks the full schema. */
+export declare function validate(input: unknown, options?: ValidationOptions): ValidationResult;
+/**
+ * A validator for a schema artifact generated from the caller's own installed `highcharts`
+ * (`chartguard schema build --library highcharts`, written to `node_modules/.cache/chartguard/`). This package never ships a Highcharts-derived schema: the
+ * Highcharts license does not clear redistributing it (CG-01-05). `extensions` add plugin series to
+ * the `highcharts.series` registry (CG-02-05). Throws for a malformed artifact, one generated for
+ * another library, or a refused extension (`ExtensionError`).
+ */
+export declare function createValidator(artifact: unknown, { extensions }?: {
+    readonly extensions?: readonly Extension[];
+}): ConfigValidator;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EAGd,KAAK,cAAc,EAGnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EAAE,KAAK,SAAS,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA6BzE;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,cAqBtB,CAAC;AAEF,oHAAoH;AACpH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAEtF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,OAAO,EACjB,EAAE,UAAe,EAAE,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;CAAO,GACtE,eAAe,CAMjB"}

package/dist/index.js

@@ -0,0 +1,70 @@
+import { manifestFromArtifact, s, validateConfig, withExtensions } from '@chartguard/config-core';
+export { ExtensionError } from '@chartguard/config-core';
+/**
+ * Highcharts reads its options with `pick()`, which skips `null` like `undefined`
+ * (highcharts@13.1.1 highcharts.src.js `if (typeof arg !== 'undefined' && arg !== null) {`): a `null`
+ * option is unset, as in the generated schema. `title.text: null` is how a title is hidden (K12).
+ */
+const object = (properties) => ({
+    ...s.object(properties),
+    nullAsAbsent: true
+});
+const toggle = object({ enabled: s.boolean() });
+const text = object({ text: s.string() });
+/**
+ * Union-typed upstream fields stay open in this hand-written subset: a hand-written union would be a
+ * guess narrower than the declarations and could reject valid configs. The generated schema
+ * (`createValidator`) checks them.
+ */
+const union = s.any;
+const series = object({
+    type: s.string(),
+    name: s.string(),
+    data: s.array(s.any()),
+    color: union() // ColorString | GradientColorObject | PatternObject
+});
+/**
+ * The hand-written starter subset of the Highcharts options (partial coverage): no Highcharts-derived
+ * schema ships with this package. Union-typed fields stay open.
+ */
+export const manifest = {
+    library: 'highcharts',
+    version: '13.x (starter subset)',
+    coverage: 'partial',
+    source: 'manually curated; field types checked against highcharts@13.1.1 TypeScript declarations',
+    root: object({
+        chart: object({
+            type: s.string(),
+            height: union(), // number | string | null
+            width: union(), // number | string | null
+            zooming: s.any()
+        }),
+        title: text,
+        subtitle: text,
+        xAxis: union(), // XAxisOptions | XAxisOptions[]
+        yAxis: union(), // YAxisOptions | YAxisOptions[]
+        series: s.array(series),
+        legend: toggle,
+        credits: toggle,
+        tooltip: toggle
+    })
+};
+/** Validates Highcharts options against the curated subset `manifest`; `createValidator` checks the full schema. */
+export function validate(input, options) {
+    return validateConfig(input, manifest, options);
+}
+/**
+ * A validator for a schema artifact generated from the caller's own installed `highcharts`
+ * (`chartguard schema build --library highcharts`, written to `node_modules/.cache/chartguard/`). This package never ships a Highcharts-derived schema: the
+ * Highcharts license does not clear redistributing it (CG-01-05). `extensions` add plugin series to
+ * the `highcharts.series` registry (CG-02-05). Throws for a malformed artifact, one generated for
+ * another library, or a refused extension (`ExtensionError`).
+ */
+export function createValidator(artifact, { extensions = [] } = {}) {
+    const generated = manifestFromArtifact(artifact);
+    if (generated.library !== 'highcharts')
+        throw new Error(`Expected a highcharts schema artifact, got one for ${generated.library}.`);
+    const extended = extensions.length === 0 ? generated : withExtensions(generated, extensions);
+    return (input, options) => validateConfig(input, extended, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,oBAAoB,EACpB,CAAC,EAED,cAAc,EACd,cAAc,EACd,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAkB,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,GAAG,CAAC,UAA0C,EAA+B,EAAE,CAAC,CAAC;IAC5F,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,EAAE,IAAI;CAClB,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC;AAEpB,MAAM,MAAM,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,EAAE,CAAC,oDAAoD;CACnE,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACvC,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,uBAAuB;IAChC,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,yFAAyF;IACjG,IAAI,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;YACb,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,MAAM,EAAE,KAAK,EAAE,EAAE,yBAAyB;YAC1C,KAAK,EAAE,KAAK,EAAE,EAAE,yBAAyB;YACzC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE;SAChB,CAAC;QACF,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,KAAK,EAAE,EAAE,gCAAgC;QAChD,KAAK,EAAE,KAAK,EAAE,EAAE,gCAAgC;QAChD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,MAAM;KACf,CAAC;CACF,CAAC;AAEF,oHAAoH;AACpH,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,OAA2B;IACnE,OAAO,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC9B,QAAiB,EACjB,EAAE,UAAU,GAAG,EAAE,KAAqD,EAAE;IAExE,MAAM,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,SAAS,CAAC,OAAO,KAAK,YAAY;QACrC,MAAM,IAAI,KAAK,CAAC,sDAAsD,SAAS,CAAC,OAAO,GAAG,CAAC,CAAC;IAC7F,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC7F,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "@chartguard/config-highcharts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@chartguard/config-highcharts",
+	"version": "0.1.0",
+	"description": "Highcharts configuration validator (partial, explicit coverage)",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dovicsin/chartguard.git",
+		"directory": "packages/config/highcharts"
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"files": [
+		"dist/",
+		"README.md"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "node --test tests/*.test.mjs"
+	},
+	"dependencies": {
+		"@chartguard/core": "0.1.0",
+		"@chartguard/config-core": "0.1.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}