@fengwk/kchart 0.0.0-stage → 0.1.1
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/CHANGELOG.md +17 -0
- package/LICENSE +21 -0
- package/NOTICE.md +11 -0
- package/README.md +68 -2
- package/README.zh-CN.md +69 -0
- package/dist/LICENSE +21 -0
- package/dist/NOTICE.md +11 -0
- package/dist/assets/ICONS-LICENSE.txt +53 -0
- package/dist/assets/maps/LICENSE.md +75 -0
- package/dist/assets/maps/METADATA.md +9 -0
- package/dist/assets/maps/REGIONS.md +28 -0
- package/dist/assets/maps/us-states.geojson +1 -0
- package/dist/assets/maps/world.geojson +1 -0
- package/dist/esm/_virtual/_kchart-families.js +48 -0
- package/dist/esm/_virtual/_rolldown/runtime.js +12 -0
- package/dist/esm/assets/icons.js +11 -0
- package/dist/esm/assets/maps/us-states.js +3 -0
- package/dist/esm/assets/maps/world.js +3 -0
- package/dist/esm/assets/themes/claude.js +69 -0
- package/dist/esm/assets/themes/cloudmusic.js +62 -0
- package/dist/esm/assets/themes/kanagawa.js +67 -0
- package/dist/esm/assets/themes/obsidian.js +67 -0
- package/dist/esm/assets/themes/paper.js +61 -0
- package/dist/esm/assets/themes/terminal.js +60 -0
- package/dist/esm/assets/themes/tokyo.js +62 -0
- package/dist/esm/chart/basic.js +1313 -0
- package/dist/esm/chart/catalog.js +476 -0
- package/dist/esm/chart/composition.js +844 -0
- package/dist/esm/chart/context.js +189 -0
- package/dist/esm/chart/distribution.js +442 -0
- package/dist/esm/chart/fields.js +67 -0
- package/dist/esm/chart/maps.js +563 -0
- package/dist/esm/chart/mindmap.js +629 -0
- package/dist/esm/chart/multivariate.js +1229 -0
- package/dist/esm/chart/registry.js +108 -0
- package/dist/esm/chart/relations.js +949 -0
- package/dist/esm/chart/spec.js +1415 -0
- package/dist/esm/chart/stat-compare.js +302 -0
- package/dist/esm/chart/stat-trend.js +181 -0
- package/dist/esm/chart/statistics.js +1007 -0
- package/dist/esm/chart/unit-variants.js +645 -0
- package/dist/esm/chart/variants.js +552 -0
- package/dist/esm/core/color.js +197 -0
- package/dist/esm/core/context.js +256 -0
- package/dist/esm/core/diagnostics.js +23 -0
- package/dist/esm/core/format.js +167 -0
- package/dist/esm/core/geometry.js +130 -0
- package/dist/esm/core/icon-data.js +5 -0
- package/dist/esm/core/icons.js +173 -0
- package/dist/esm/core/scale.js +112 -0
- package/dist/esm/core/scene.js +234 -0
- package/dist/esm/core/svg.js +89 -0
- package/dist/esm/core/text.js +184 -0
- package/dist/esm/core/theme.js +318 -0
- package/dist/esm/diagram/agentflow.js +596 -0
- package/dist/esm/diagram/architecture.js +729 -0
- package/dist/esm/diagram/block.js +988 -0
- package/dist/esm/diagram/blocks.js +687 -0
- package/dist/esm/diagram/c4.js +1002 -0
- package/dist/esm/diagram/class.js +1158 -0
- package/dist/esm/diagram/cynefin.js +749 -0
- package/dist/esm/diagram/emphasis.js +7 -0
- package/dist/esm/diagram/er.js +657 -0
- package/dist/esm/diagram/eventmodeling.js +948 -0
- package/dist/esm/diagram/gantt-date.js +323 -0
- package/dist/esm/diagram/gantt.js +661 -0
- package/dist/esm/diagram/gitgraph.js +472 -0
- package/dist/esm/diagram/graph-layout.js +4046 -0
- package/dist/esm/diagram/graph-parse.js +1366 -0
- package/dist/esm/diagram/graph-route.js +490 -0
- package/dist/esm/diagram/graph.js +553 -0
- package/dist/esm/diagram/ishikawa.js +496 -0
- package/dist/esm/diagram/journey.js +512 -0
- package/dist/esm/diagram/kanban.js +280 -0
- package/dist/esm/diagram/label.js +56 -0
- package/dist/esm/diagram/layers.js +385 -0
- package/dist/esm/diagram/map-label.js +44 -0
- package/dist/esm/diagram/mindmap.js +277 -0
- package/dist/esm/diagram/numeric-composition.js +78 -0
- package/dist/esm/diagram/numeric-model.js +86 -0
- package/dist/esm/diagram/numeric-parse.js +205 -0
- package/dist/esm/diagram/numeric-radar.js +355 -0
- package/dist/esm/diagram/numeric-sankey.js +201 -0
- package/dist/esm/diagram/numeric-xy.js +422 -0
- package/dist/esm/diagram/packet.js +175 -0
- package/dist/esm/diagram/presentation.js +252 -0
- package/dist/esm/diagram/quadrant.js +297 -0
- package/dist/esm/diagram/railroad-parse.js +465 -0
- package/dist/esm/diagram/railroad.js +294 -0
- package/dist/esm/diagram/registry.js +296 -0
- package/dist/esm/diagram/relations.js +966 -0
- package/dist/esm/diagram/requirement.js +341 -0
- package/dist/esm/diagram/sequence.js +1228 -0
- package/dist/esm/diagram/shapes.js +366 -0
- package/dist/esm/diagram/source.js +538 -0
- package/dist/esm/diagram/support.js +153 -0
- package/dist/esm/diagram/swimlane-mermaid.js +140 -0
- package/dist/esm/diagram/swimlane.js +1186 -0
- package/dist/esm/diagram/time.js +748 -0
- package/dist/esm/diagram/timeline.js +376 -0
- package/dist/esm/diagram/tree-family-icon.js +22 -0
- package/dist/esm/diagram/treeview.js +293 -0
- package/dist/esm/diagram/usecase.js +852 -0
- package/dist/esm/diagram/venn.js +1038 -0
- package/dist/esm/diagram/wardley.js +838 -0
- package/dist/esm/index.d.ts +133 -0
- package/dist/esm/index.js +92 -0
- package/dist/esm/interaction.js +561 -0
- package/dist/esm/mermaid.d.ts +28 -0
- package/dist/esm/mermaid.js +70 -0
- package/dist/esm/node.d.ts +68 -0
- package/dist/esm/node.js +373 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/page-api.js +65 -0
- package/dist/esm/runtime.js +352 -0
- package/dist/esm/src/families.js +209 -0
- package/dist/page-api.js +1 -0
- package/dist/units/chart/basic.js +1 -0
- package/dist/units/chart/catalog.js +1 -0
- package/dist/units/chart/composition.js +1 -0
- package/dist/units/chart/context.js +1 -0
- package/dist/units/chart/distribution.js +1 -0
- package/dist/units/chart/fields.js +1 -0
- package/dist/units/chart/maps.js +1 -0
- package/dist/units/chart/mindmap.js +1 -0
- package/dist/units/chart/multivariate.js +1 -0
- package/dist/units/chart/registry.js +1 -0
- package/dist/units/chart/relations.js +1 -0
- package/dist/units/chart/spec.js +3 -0
- package/dist/units/chart/stat-compare.js +1 -0
- package/dist/units/chart/stat-trend.js +1 -0
- package/dist/units/chart/statistics.js +1 -0
- package/dist/units/chart/unit-variants.js +1 -0
- package/dist/units/chart/variants.js +1 -0
- package/dist/units/core/color.js +1 -0
- package/dist/units/core/context.js +1 -0
- package/dist/units/core/diagnostics.js +1 -0
- package/dist/units/core/format.js +1 -0
- package/dist/units/core/geometry.js +1 -0
- package/dist/units/core/icon-data.js +1 -0
- package/dist/units/core/icons.js +1 -0
- package/dist/units/core/scale.js +1 -0
- package/dist/units/core/scene.js +1 -0
- package/dist/units/core/svg.js +1 -0
- package/dist/units/core/text.js +2 -0
- package/dist/units/core/theme.js +1 -0
- package/dist/units/diagram/agentflow.js +12 -0
- package/dist/units/diagram/architecture.js +4 -0
- package/dist/units/diagram/block.js +2 -0
- package/dist/units/diagram/blocks.js +2 -0
- package/dist/units/diagram/c4.js +6 -0
- package/dist/units/diagram/class.js +5 -0
- package/dist/units/diagram/cynefin.js +4 -0
- package/dist/units/diagram/emphasis.js +1 -0
- package/dist/units/diagram/er.js +9 -0
- package/dist/units/diagram/eventmodeling.js +5 -0
- package/dist/units/diagram/gantt-date.js +1 -0
- package/dist/units/diagram/gantt.js +3 -0
- package/dist/units/diagram/gitgraph.js +2 -0
- package/dist/units/diagram/graph-layout.js +4 -0
- package/dist/units/diagram/graph-parse.js +9 -0
- package/dist/units/diagram/graph-route.js +1 -0
- package/dist/units/diagram/graph.js +1 -0
- package/dist/units/diagram/ishikawa.js +2 -0
- package/dist/units/diagram/journey.js +5 -0
- package/dist/units/diagram/kanban.js +2 -0
- package/dist/units/diagram/label.js +4 -0
- package/dist/units/diagram/layers.js +1 -0
- package/dist/units/diagram/map-label.js +1 -0
- package/dist/units/diagram/mindmap.js +2 -0
- package/dist/units/diagram/numeric-composition.js +1 -0
- package/dist/units/diagram/numeric-model.js +1 -0
- package/dist/units/diagram/numeric-parse.js +2 -0
- package/dist/units/diagram/numeric-radar.js +3 -0
- package/dist/units/diagram/numeric-sankey.js +2 -0
- package/dist/units/diagram/numeric-xy.js +2 -0
- package/dist/units/diagram/packet.js +2 -0
- package/dist/units/diagram/presentation.js +2 -0
- package/dist/units/diagram/quadrant.js +2 -0
- package/dist/units/diagram/railroad-parse.js +4 -0
- package/dist/units/diagram/railroad.js +1 -0
- package/dist/units/diagram/registry.js +2 -0
- package/dist/units/diagram/relations.js +3 -0
- package/dist/units/diagram/requirement.js +3 -0
- package/dist/units/diagram/sequence.js +2 -0
- package/dist/units/diagram/shapes.js +60 -0
- package/dist/units/diagram/source.js +20 -0
- package/dist/units/diagram/support.js +3 -0
- package/dist/units/diagram/swimlane-mermaid.js +3 -0
- package/dist/units/diagram/swimlane.js +2 -0
- package/dist/units/diagram/time.js +3 -0
- package/dist/units/diagram/timeline.js +2 -0
- package/dist/units/diagram/tree-family-icon.js +1 -0
- package/dist/units/diagram/treeview.js +2 -0
- package/dist/units/diagram/usecase.js +3 -0
- package/dist/units/diagram/venn.js +2 -0
- package/dist/units/diagram/wardley.js +4 -0
- package/dist/units/interaction.js +1 -0
- package/dist/units/runtime.js +1 -0
- package/dist/units.json +712 -0
- package/package.json +30 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Center the title and payload together both horizontally and vertically inside Event Modeling frames. Keep the payload rows left-aligned within that block.
|
|
6
|
+
- Draw Venn labels directly on the set and intersection fills, without label backplates or halos. Keep text clear of ring outlines and move labels below the diagram only when they cannot fit.
|
|
7
|
+
- Keep lines and points above columns in combo charts and Mermaid XY charts. Add a thin outline only where a line overlaps a low-contrast column.
|
|
8
|
+
- Raise warning-label contrast in the Cloud Music theme.
|
|
9
|
+
- Report an invalid top-level chart `id` once, while continuing to support row identifiers through `encode.id`.
|
|
10
|
+
|
|
11
|
+
## 0.1.0
|
|
12
|
+
|
|
13
|
+
- First npm release with an asynchronous browser/Node ESM API, on-demand chart and diagram families, and separately loaded built-in maps.
|
|
14
|
+
- Added Mermaid 12.3.0 core compatibility, verified on 525 examples at 800 px and 360 px with geometry checks. Each core diagram's canonical name is the keyword Mermaid 12.3.0 parses, such as `architecture-beta`; other accepted spellings are aliases. The external ZenUML plugin is not supported.
|
|
15
|
+
- Added the Mermaid-style `initialize`, `render`, `parse`, and `detectType` facade, as named exports and as a default export like Mermaid's own. Mermaid settings are checked like the diagram's front-matter config, which overrides them: supported settings such as `c4.c4ShapeInRow` apply, runtime settings such as `startOnLoad` pass silently, and the rest, such as `themeVariables` or the theme name `dark`, produce one `IGNORED_CONFIG` warning. Diagram diagnostics distinguish blocking errors from non-blocking warnings.
|
|
16
|
+
- Added theme-based style colors, safe links without callback execution, and support for host-registered Iconify icon sets.
|
|
17
|
+
- Exposed the synchronous Node API at `@fengwk/kchart/node`; all three entry points ship TypeScript declarations.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 fengwk
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/NOTICE.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Third-party notices · 第三方资产说明
|
|
2
|
+
|
|
3
|
+
KChart's own source code and documentation are under the [MIT License](LICENSE). The bundled third-party assets below keep their own licenses and trademark notes. In the npm package, the files linked here are under `dist/`.
|
|
4
|
+
|
|
5
|
+
- Icons: a curated subset of Tabler Icons v3.46.0 (MIT) and Simple Icons 16.28.0 (CC0 1.0, with brand trademark notes). See [assets/ICONS-LICENSE.txt](assets/ICONS-LICENSE.txt). The package ships the subset compiled into its icon module; the source data is `packages/kchart/assets/icons.json` in the repository.
|
|
6
|
+
- Maps: world and US state boundaries from Natural Earth, in the public domain. See the [map license](assets/maps/LICENSE.md), [display conditions](assets/maps/METADATA.md) and [region keys](assets/maps/REGIONS.md). No approved China boundary data is included.
|
|
7
|
+
|
|
8
|
+
KChart 自有源码与文档遵循 [MIT License](LICENSE)。下列随包附带的第三方资产仍适用各自的原许可与商标说明。npm 包中,这里链接的文件位于 `dist/` 下。
|
|
9
|
+
|
|
10
|
+
- 图标:Tabler Icons v3.46.0(MIT)与 Simple Icons 16.28.0(CC0 1.0,另附品牌商标说明)的受控子集,见 [assets/ICONS-LICENSE.txt](assets/ICONS-LICENSE.txt)。npm 包中的子集已编译进图标模块,源数据是仓库中的 `packages/kchart/assets/icons.json`。
|
|
11
|
+
- 地图:Natural Earth 世界与美国州界,公有领域。见[地图许可](assets/maps/LICENSE.md)、[显示条件](assets/maps/METADATA.md)和[地区键](assets/maps/REGIONS.md)。不包含中国审定边界数据。
|
package/README.md
CHANGED
|
@@ -1,3 +1,69 @@
|
|
|
1
|
-
#
|
|
1
|
+
# KChart
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[简体中文](README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
KChart renders declarative charts and diagrams to deterministic SVG without a DOM, a runtime dependency, or a remote rendering service. Install with `npm install @fengwk/kchart`. Node.js consumers need Node 22.12 or later; all entries are ESM and include TypeScript declarations.
|
|
6
|
+
|
|
7
|
+
## Mermaid compatibility
|
|
8
|
+
|
|
9
|
+
All 525 core examples accepted by Mermaid 12.3.0 in the [conformance corpus](https://github.com/fengwk/html-view-skill/tree/main/packages/kchart/tests/conformance) render at both 800 px and 360 px without error diagnostics and pass the geometry checks. KChart uses its own layout and theme: supported style colors map by hue to theme status colors; unsupported presentation is not reproduced. Safe links are kept, but callbacks are not executed. ZenUML is an external Mermaid plugin and is not supported; the legacy `zenuml` reader only handles simple call diagrams.
|
|
10
|
+
|
|
11
|
+
## Browser and async Node API
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
// Keep this import inside a lazy Markdown renderer (or the handler that needs it).
|
|
15
|
+
const { diagram, render } = await import('@fengwk/kchart');
|
|
16
|
+
const flow = await diagram('flowchart LR\nA --> B', { width: 480, prefix: 'flow-1' });
|
|
17
|
+
const bars = await render({
|
|
18
|
+
chart: 'bar',
|
|
19
|
+
data: [{ region: 'East', orders: 120 }, { region: 'South', orders: 85 }],
|
|
20
|
+
encode: { category: 'region', value: 'orders' },
|
|
21
|
+
}, { theme: 'paper', prefix: 'bars-1' });
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`render(spec, options?)` and `diagram(source, options?)` resolve to `{ svg, scene, diagnostics }`. For invalid input or a layout that cannot be rendered, `svg` and `scene` are `null`; unexpected failures reject. Each diagram diagnostic has `severity`: an `error` blocks rendering, while a `warning` (for example, a skipped callback or a suggestion to split a large diagram) accompanies a rendered SVG. `check(source, { syntax, lang }?)` resolves to the parse/validation diagnostics, warnings included, without laying out the diagram. The diagram syntax defaults to `mermaid`; use `layers`, `blocks`, or `swimlane` for native diagrams. `catalog` and `diagramTypes` expose the supported types and diagram aliases synchronously.
|
|
25
|
+
|
|
26
|
+
Render options include `width`, `lang`, `theme`, `media`, `frame`, `prefix`, and `measure(text, size, weight, fontFamily)`. Set `frame: false` if your host already supplies a figure frame. Give each inline SVG a unique `prefix`; allow horizontal scrolling if a diagram needs more room than the requested width.
|
|
27
|
+
|
|
28
|
+
If `lang` is omitted, diagrams infer English or Chinese from the source: English when there are at least twice as many English words as CJK characters and at least one English word; otherwise Chinese. Set `lang` explicitly to override this.
|
|
29
|
+
|
|
30
|
+
A production Vite build splits chart and diagram families at dynamic imports. Make the Markdown component itself a dynamic import (for example with `React.lazy`) to defer the facade as well. Shared dependencies can be reused between families. For a map chart, only the requested built-in map (`world` or `us-states`) is loaded; `options.assets` can supply your own map data instead. The renderer needs no network service at runtime; serve the JavaScript chunks and map assets locally for offline use. In a hosted browser build on-demand imports may still load chunks from your own host.
|
|
31
|
+
|
|
32
|
+
## Synchronous Node API
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
import { diagram, schema } from '@fengwk/kchart/node';
|
|
36
|
+
console.log(diagram('flowchart LR\nA --> B').svg);
|
|
37
|
+
console.log(schema('bar'));
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The Node entry provides synchronous `render`, `diagram`, `check`, `parse`, `validate`, `schema`, and `dataTable`. Use `createRenderer({ specs })` to select families for a set of declarations, or `createRenderer({ sources })` for a diagram-only renderer. `browserSource(specs)` (or a renderer's `bundleSource()`) generates a classic script for offline pages, exposing `globalThis.KChart`. For that classic script, supply map data via `options.assets`; the synchronous Node renderer reads built-in maps from disk. `runtimeSource()` supplies the optional offline page runtime.
|
|
41
|
+
|
|
42
|
+
## Mermaid-style facade
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
import mermaid from '@fengwk/kchart/mermaid';
|
|
46
|
+
|
|
47
|
+
mermaid.initialize({ theme: 'paper' });
|
|
48
|
+
const { svg, diagramType, diagnostics } = await mermaid.render('preview-1', 'graph LR\nA --> B');
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The default export holds the same functions as the named exports, so code written as `import mermaid from 'mermaid'` only needs its import changed; `await import('@fengwk/kchart/mermaid')` loads it on demand. `initialize(config)` sets the defaults for later calls, and per-call options override them. KChart's own options control the render: `width`, `lang`, `media`, `frame`, `prefix`, `measure`, and `theme` when it is a KChart theme ID such as `paper` or a theme object. Every other setting is checked like a `config` in the diagram's front matter, which overrides it. Settings the diagram type supports, such as `c4: { c4ShapeInRow: 1 }`, take effect. Runtime settings such as `startOnLoad` and `securityLevel` are accepted silently, as are `fontFamily` and `fontSize`, because fonts come from the KChart theme. Anything else, including `themeVariables` and Mermaid theme names such as `dark` (KChart then draws its default theme), is reported in one `IGNORED_CONFIG` warning; Mermaid's `default` theme needs none. The render ID supplies the SVG prefix unless a per-call prefix is provided. `render(id, text, options?)` rejects invalid diagrams with an `Error` carrying `diagnostics`; warnings never reject. `parse(text, { suppressErrors }?)` resolves to `{ diagramType, diagnostics }` (warnings only), or to `false` for invalid input when suppression is enabled; otherwise it rejects with diagnostics. Synchronous `detectType(text)` returns the canonical type for a recognized Mermaid header, without validating the body, and throws for unknown types.
|
|
52
|
+
|
|
53
|
+
This is a Mermaid-style facade, not the entire Mermaid API. It does not run callbacks or return DOM binding functions. Successful `parse` does not guarantee that a diagram can be laid out.
|
|
54
|
+
|
|
55
|
+
## Diagnostics and icons
|
|
56
|
+
|
|
57
|
+
Diagram diagnostics carry a `code`, `severity`, `line`, `column`, `message`, `fix`, and `topic`. Diagram warnings include `IGNORED_CONFIG` (unused settings), `IGNORED_STYLE` (unused CSS), `IGNORED_INTERACTION` (callbacks or unsafe links), `IGNORED_ASSET` (such as an unknown icon or a remote image), `LARGE_DIAGRAM` (consider splitting the figure), and `DIAGRAM_HINT` (type-specific advice).
|
|
58
|
+
|
|
59
|
+
Both the async and Node entries export `registerIcons({ prefix, icons, width?, height? })` for an Iconify-style icon set. Each entry in `icons` has an SVG `body` and optional `width` and `height`; KChart normalizes the geometry. Registered icons are shared across renders in the same process (or browser context) and referenced as `prefix:name` wherever the diagram accepts icons. Built-in icons work without registration; unresolved icons warn rather than blocking render.
|
|
60
|
+
|
|
61
|
+
## Themes and supported types
|
|
62
|
+
|
|
63
|
+
`themes` lists the built-in palettes; `theme('paper')` returns a reusable snapshot. Pass a built-in ID or a snapshot as `options.theme`, and use `media: 'print'` for print colors. The Node entry also exposes `resolveThemeConfig(config)` for inherited custom themes.
|
|
64
|
+
|
|
65
|
+
See [chart declarations](https://github.com/fengwk/html-view-skill/blob/main/packages/kchart/docs/declaring-charts.md) and [diagram references (Chinese)](https://github.com/fengwk/html-view-skill/tree/main/skills/html-view/references/diagrams) for inputs, supported types, and Mermaid limitations.
|
|
66
|
+
|
|
67
|
+
KChart is [MIT licensed](LICENSE). See [NOTICE](NOTICE.md) for asset sources and licenses.
|
|
68
|
+
|
|
69
|
+
From a source checkout, run `npm ci && npm run build` in `packages/kchart` before `npm pack`. See the [changelog](CHANGELOG.md) for release notes.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# KChart
|
|
2
|
+
|
|
3
|
+
[English](README.md)
|
|
4
|
+
|
|
5
|
+
KChart 将声明式图表和结构图渲染为确定性的 SVG,不依赖 DOM、运行时依赖或远程渲染服务。使用 `npm install @fengwk/kchart` 安装。Node.js 需要 22.12 或更高版本;所有入口均为 ESM,并带有 TypeScript 声明。
|
|
6
|
+
|
|
7
|
+
## Mermaid 兼容性
|
|
8
|
+
|
|
9
|
+
[兼容性语料](https://github.com/fengwk/html-view-skill/tree/main/packages/kchart/tests/conformance)中 Mermaid 12.3.0 接受的 525 个核心示例,均能在 800 px 和 360 px 下无错误诊断地渲染,并通过图形几何检查。KChart 使用自己的布局与主题:可识别的样式颜色按色相映射为主题状态色,不复刻不支持的外观。安全链接会保留,回调不会执行。ZenUML 是 Mermaid 外部插件,KChart 不支持该插件;仅保留 `zenuml` 简单调用图的旧版读法。
|
|
10
|
+
|
|
11
|
+
## 浏览器和 Node 异步 API
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
// 在懒加载的 Markdown 渲染器中导入,或在真正需要时导入。
|
|
15
|
+
const { diagram, render } = await import('@fengwk/kchart');
|
|
16
|
+
const flow = await diagram('flowchart LR\nA --> B', { width: 480, prefix: 'flow-1' });
|
|
17
|
+
const bars = await render({
|
|
18
|
+
chart: 'bar',
|
|
19
|
+
data: [{ region: '华东', orders: 120 }, { region: '华南', orders: 85 }],
|
|
20
|
+
encode: { category: 'region', value: 'orders' },
|
|
21
|
+
}, { theme: 'paper', prefix: 'bars-1' });
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`render(spec, options?)` 和 `diagram(source, options?)` 返回 Promise,结果为 `{ svg, scene, diagnostics }`。输入无效或无法布局时,`svg` 和 `scene` 均为 `null`;意外错误会拒绝 Promise。每条结构图诊断带 `severity`:`error` 阻止渲染;`warning` 会随 SVG 一起返回,例如跳过回调或建议拆分大图。`check(source, { syntax, lang }?)` 仅解析和校验,不执行布局,异步返回含警告在内的诊断数组。结构图默认使用 `mermaid` 语法,原生结构图使用 `layers`、`blocks` 或 `swimlane`。`catalog` 和 `diagramTypes` 可同步查询支持的图型及结构图别名。
|
|
25
|
+
|
|
26
|
+
渲染选项包括 `width`、`lang`、`theme`、`media`、`frame`、`prefix` 和 `measure(text, size, weight, fontFamily)`。宿主已有图框时可设置 `frame: false`。每个内联 SVG 应使用不同的 `prefix`;结构图可能宽于请求值,建议让容器可以横向滚动。
|
|
27
|
+
|
|
28
|
+
不传 `lang` 时,结构图会根据源码推断语言:英文词至少有一个,且数量不少于中日韩字符的两倍时用英文,否则用中文。显式指定 `lang` 可覆盖推断结果。
|
|
29
|
+
|
|
30
|
+
在 Vite 生产构建中,数据图和结构图的各个族通过动态导入拆分。如果也要延迟加载适配器,请动态导入 Markdown 组件(例如使用 `React.lazy`)。不同族可复用公共依赖。地图只在地图图表需要时加载相应的内置数据(`world` 或 `us-states`),也可通过 `options.assets` 注入自有地图。渲染不依赖在线服务;将 JavaScript 分块和地图资源放在本地即可离线使用。浏览器部署时,动态导入仍可能从宿主加载分块。
|
|
31
|
+
|
|
32
|
+
## Node 同步 API
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
import { diagram, schema } from '@fengwk/kchart/node';
|
|
36
|
+
console.log(diagram('flowchart LR\nA --> B').svg);
|
|
37
|
+
console.log(schema('bar'));
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Node 入口提供同步的 `render`、`diagram`、`check`、`parse`、`validate`、`schema` 和 `dataTable`。使用 `createRenderer({ specs })` 按声明选取图族,或使用 `createRenderer({ sources })` 创建只含结构图的渲染器。`browserSource(specs)` 或渲染器的 `bundleSource()` 为离线页面生成暴露 `globalThis.KChart` 的普通脚本。该脚本需要通过 `options.assets` 注入地图,同步 Node 渲染器则从本地磁盘读取内置地图。`runtimeSource()` 提供可选的离线页面运行时。
|
|
41
|
+
|
|
42
|
+
## Mermaid 风格适配器
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
import mermaid from '@fengwk/kchart/mermaid';
|
|
46
|
+
|
|
47
|
+
mermaid.initialize({ theme: 'paper' });
|
|
48
|
+
const { svg, diagramType, diagnostics } = await mermaid.render('preview-1', 'graph LR\nA --> B');
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
默认导出与具名导出是同一组函数,原来写成 `import mermaid from 'mermaid'` 的代码只需改导入路径;也可以用 `await import('@fengwk/kchart/mermaid')` 按需加载。`initialize(config)` 设置之后各次调用的默认值,单次调用的选项优先。KChart 自己的选项直接控制渲染:`width`、`lang`、`media`、`frame`、`prefix`、`measure`,以及取 KChart 主题 ID(如 `paper`)或主题对象的 `theme`。其余设置都按图内前言的 `config` 检查,图内配置优先:图型支持的设置(如 `c4: { c4ShapeInRow: 1 }`)生效;`startOnLoad`、`securityLevel` 等运行设置静默接受,`fontFamily`、`fontSize` 也静默接受,字体由 KChart 主题决定;其他设置,包括 `themeVariables` 和 `dark` 等 Mermaid 主题名(此时改用 KChart 默认主题),合并报一条 `IGNORED_CONFIG` 警告;Mermaid 的 `default` 主题不报。`render(id, text, options?)` 默认用 `id` 作为 SVG 前缀,可通过单次调用的 `prefix` 覆盖;遇到无效图时以带 `diagnostics` 的 `Error` 拒绝,警告不会导致拒绝。`parse(text, { suppressErrors }?)` 成功时返回 `{ diagramType, diagnostics }`(只含警告),无效输入在启用抑制时返回 `false`,否则以带诊断的错误拒绝。同步的 `detectType(text)` 根据首行图型声明返回标准图型名,不校验正文;图型未知时抛出异常。
|
|
52
|
+
|
|
53
|
+
这是 Mermaid 风格的适配器,不是完整的 Mermaid API;不执行回调,也不返回 DOM 绑定函数。`parse` 成功不保证图可以完成布局。
|
|
54
|
+
|
|
55
|
+
## 诊断与图标
|
|
56
|
+
|
|
57
|
+
结构图诊断含 `code`、`severity`、`line`、`column`、`message`、`fix` 和 `topic`。警告码包括 `IGNORED_CONFIG`(未采用的配置)、`IGNORED_STYLE`(未采用的 CSS)、`IGNORED_INTERACTION`(回调或不安全的链接)、`IGNORED_ASSET`(如未知图标或远程图片)、`LARGE_DIAGRAM`(建议拆图)和 `DIAGRAM_HINT`(图型专用提示)。
|
|
58
|
+
|
|
59
|
+
异步入口和 Node 入口均导出 `registerIcons({ prefix, icons, width?, height? })`,用于注册 Iconify 格式的图标集。`icons` 中每项包含 SVG `body`,可选 `width` 和 `height`;KChart 会规范化图形。已注册的图标在同一进程(或浏览器上下文)的渲染间共享,在图型支持图标的位置使用 `prefix:name` 引用。内置图标无需注册;无法解析的图标只告警,不阻止渲染。
|
|
60
|
+
|
|
61
|
+
## 主题和支持的图型
|
|
62
|
+
|
|
63
|
+
`themes` 列出内置主题;`theme('paper')` 返回可复用的快照。`options.theme` 接受内置主题 ID 或快照,`media: 'print'` 使用打印配色。Node 入口还提供 `resolveThemeConfig(config)` 解析继承式自定义主题。
|
|
64
|
+
|
|
65
|
+
具体输入、支持的图型和 Mermaid 限制见[数据图声明](https://github.com/fengwk/html-view-skill/blob/main/packages/kchart/docs/declaring-charts.md)和[结构图参考](https://github.com/fengwk/html-view-skill/tree/main/skills/html-view/references/diagrams)。
|
|
66
|
+
|
|
67
|
+
KChart 采用 [MIT 许可](LICENSE),资产来源和许可见 [NOTICE](NOTICE.md)。
|
|
68
|
+
|
|
69
|
+
从源码打包时,请先在 `packages/kchart` 运行 `npm ci && npm run build`,再运行 `npm pack`。版本变更见[更新日志](CHANGELOG.md)。
|
package/dist/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 fengwk
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/dist/NOTICE.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Third-party notices · 第三方资产说明
|
|
2
|
+
|
|
3
|
+
KChart's own source code and documentation are under the [MIT License](LICENSE). The bundled third-party assets below keep their own licenses and trademark notes. In the npm package, the files linked here are under `dist/`.
|
|
4
|
+
|
|
5
|
+
- Icons: a curated subset of Tabler Icons v3.46.0 (MIT) and Simple Icons 16.28.0 (CC0 1.0, with brand trademark notes). See [assets/ICONS-LICENSE.txt](assets/ICONS-LICENSE.txt). The package ships the subset compiled into its icon module; the source data is `packages/kchart/assets/icons.json` in the repository.
|
|
6
|
+
- Maps: world and US state boundaries from Natural Earth, in the public domain. See the [map license](assets/maps/LICENSE.md), [display conditions](assets/maps/METADATA.md) and [region keys](assets/maps/REGIONS.md). No approved China boundary data is included.
|
|
7
|
+
|
|
8
|
+
KChart 自有源码与文档遵循 [MIT License](LICENSE)。下列随包附带的第三方资产仍适用各自的原许可与商标说明。npm 包中,这里链接的文件位于 `dist/` 下。
|
|
9
|
+
|
|
10
|
+
- 图标:Tabler Icons v3.46.0(MIT)与 Simple Icons 16.28.0(CC0 1.0,另附品牌商标说明)的受控子集,见 [assets/ICONS-LICENSE.txt](assets/ICONS-LICENSE.txt)。npm 包中的子集已编译进图标模块,源数据是仓库中的 `packages/kchart/assets/icons.json`。
|
|
11
|
+
- 地图:Natural Earth 世界与美国州界,公有领域。见[地图许可](assets/maps/LICENSE.md)、[显示条件](assets/maps/METADATA.md)和[地区键](assets/maps/REGIONS.md)。不包含中国审定边界数据。
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
图标子集许可与商标说明
|
|
2
|
+
========================
|
|
3
|
+
|
|
4
|
+
本文件随 KChart 的受控图标子集发布。子集基于下列上游版本,
|
|
5
|
+
不包含全库,使用时无需另装图标库。
|
|
6
|
+
|
|
7
|
+
来源与范围
|
|
8
|
+
----------
|
|
9
|
+
|
|
10
|
+
- 通用图标:Tabler Icons outline,上游 Tabler Icons v3.46.0
|
|
11
|
+
(https://github.com/tabler/tabler-icons/releases/tag/v3.46.0,
|
|
12
|
+
commit 8ac7d81b72ece11072ef25ea9fd92e80c6f3c9fc)。
|
|
13
|
+
- 品牌图标:Simple Icons 16.28.0
|
|
14
|
+
(https://github.com/simple-icons/simple-icons/releases/tag/16.28.0,
|
|
15
|
+
commit fc91ef03ec113d06627b2d47c1f9644ca202b6f9)。
|
|
16
|
+
- 处理:只保留 path、circle、ellipse、rect、line、polyline、polygon 的几何属性;
|
|
17
|
+
去掉注释、标题、尺寸和原有颜色,绘制时继承 currentColor。
|
|
18
|
+
|
|
19
|
+
Tabler Icons — MIT License
|
|
20
|
+
--------------------------
|
|
21
|
+
|
|
22
|
+
Copyright (c) 2020-2026 Paweł Kuna
|
|
23
|
+
|
|
24
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
25
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
26
|
+
in the Software without restriction, including without limitation the rights
|
|
27
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
28
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
29
|
+
furnished to do so, subject to the following conditions:
|
|
30
|
+
|
|
31
|
+
The above copyright notice and this permission notice shall be included in all
|
|
32
|
+
copies or substantial portions of the Software.
|
|
33
|
+
|
|
34
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
35
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
36
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
37
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
38
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
39
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
40
|
+
SOFTWARE.
|
|
41
|
+
|
|
42
|
+
Simple Icons — CC0 与商标
|
|
43
|
+
-------------------------
|
|
44
|
+
|
|
45
|
+
Simple Icons 项目以 CC0 1.0 发布
|
|
46
|
+
(https://github.com/simple-icons/simple-icons/blob/16.28.0/LICENSE.md)。
|
|
47
|
+
CC0 不表示每一个品牌标志本身都是 CC0。品牌标志可能另有许可、使用规范或商标限制。
|
|
48
|
+
使用前应核对当前 Simple Icons 元数据、品牌方规范和上游声明
|
|
49
|
+
(https://github.com/simple-icons/simple-icons/blob/16.28.0/DISCLAIMER.md)。
|
|
50
|
+
|
|
51
|
+
CC0 和收录在本子集中都不授予商标许可。品牌名称与标志归各自权利人所有;
|
|
52
|
+
本子集只提供单色几何形状,用于说明架构或技术栈,不表示背书、合作或授权关系。
|
|
53
|
+
不要把这些标志用于暗示官方身份、重新着色后冒充品牌,或违反品牌使用规范的场合。
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Everything here is public domain.
|
|
2
|
+
|
|
3
|
+
[Full terms of service »](http://www.naturalearthdata.com/about/terms-of-use/)
|
|
4
|
+
|
|
5
|
+
All versions of Natural Earth raster + vector map data found on this website are in the public domain. You may use the maps in any manner, including modifying the content and design, electronic dissemination, and offset printing. The primary authors, _Tom Patterson_ and _Nathaniel Vaughn Kelso_, and all other contributors renounce all financial claim to the maps and invites you to use them for personal, educational, and commercial purposes.
|
|
6
|
+
|
|
7
|
+
# Credits
|
|
8
|
+
|
|
9
|
+
No permission is needed to use Natural Earth. Crediting the authors is unnecessary.
|
|
10
|
+
|
|
11
|
+
However, if you wish to cite the map data, simply use one of the following.
|
|
12
|
+
|
|
13
|
+
Short text: Made with Natural Earth.
|
|
14
|
+
|
|
15
|
+
Long text: Made with Natural Earth. Free vector and raster map data @ naturalearthdata.com.
|
|
16
|
+
|
|
17
|
+
Three logo options:
|
|
18
|
+
|
|
19
|
+

|
|
20
|
+
|
|
21
|
+
[Download Large Transparent PNG](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV-Logo-color.png)
|
|
22
|
+
[Download EPS](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV%20Logo%20color.zip)
|
|
23
|
+
|
|
24
|
+

|
|
25
|
+
|
|
26
|
+
[Download Large Transparent PNG](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV-Logo-Black.png)
|
|
27
|
+
[Download EPS](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV%20Logo%20Black.zip)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
[Download Large Transparent PNG](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV-Logo-White.png)
|
|
33
|
+
[Download EPS](http://www.naturalearthdata.com/wp-content/uploads/2009/08/NEV%20Logo%20White.zip)
|
|
34
|
+
|
|
35
|
+
# Your due diligence
|
|
36
|
+
|
|
37
|
+
All users of Natural Earth are highly encouraged to read about data sources and manipulation in the [Data Creation](http://www.naturalearthdata.com/about/data-creation/) section.
|
|
38
|
+
|
|
39
|
+
The authors provide Natural Earth as a public service and are not responsible for any problems relating to accuracy, content, design, and how it is used. If you find an error or omission, please [report it](http://www.naturalearthdata.com/corrections/index.php?a=add) for future updates.
|
|
40
|
+
|
|
41
|
+
# Releases
|
|
42
|
+
|
|
43
|
+
The authors used data from The Washington Post, here is their release:
|
|
44
|
+
|
|
45
|
+
Natural Earth is hereby granted a non-exclusive license to use the data being
|
|
46
|
+
provided by The Washington Post for the sole purpose of creating a world base map.
|
|
47
|
+
The Washington Post makes no claims as to the completeness, accuracy or content of
|
|
48
|
+
the data, and makes no representation of any kind, including, but not limited to,
|
|
49
|
+
any warranty as to the accuracy or fitness of the data for a particular use (nor
|
|
50
|
+
shall the act of distribution constitute any such warranty). No responsibility is
|
|
51
|
+
assumed by The Washington Post for any claims arising out of Natural Earth’s use
|
|
52
|
+
of the data.
|
|
53
|
+
|
|
54
|
+
The author’s used river and lake data (for Europe only) from the European Commission, Joint Research Centre, Institute for Environment and Sustainability, here is their release:
|
|
55
|
+
|
|
56
|
+
Natural Earth is hereby granted a non-exclusive license to use the data being
|
|
57
|
+
provided by European Commission, Joint Research Centre, Institute for Environment
|
|
58
|
+
and Sustainability (JRC IES) for the sole purpose of creating a world base map. The
|
|
59
|
+
EC JRC IES makes no claims as to the completeness, accuracy or content of the data,
|
|
60
|
+
and makes no representation of any kind, including, but not limited to, any warranty
|
|
61
|
+
as to the accuracy or fitness of the data for a particular use (nor shall the act of
|
|
62
|
+
distribution constitute any such warranty). No responsibility is assumed by EC JRC
|
|
63
|
+
IES for any claims arising out of Natural Earth’s use of the data.
|
|
64
|
+
|
|
65
|
+
The author’s used road transportation data (for North America only) from XNR Productions, here is their release:
|
|
66
|
+
|
|
67
|
+
Natural Earth is hereby granted a non-exclusive license to use the data being
|
|
68
|
+
provided by XNR Productions for the sole purpose of creating a world base map.
|
|
69
|
+
XNR makes no claims as to the completeness, accuracy or content of the data, and
|
|
70
|
+
makes no representation of any kind, including, but not limited to, any warranty
|
|
71
|
+
as to the accuracy or fitness of the data for a particular use (nor shall the act
|
|
72
|
+
of distribution constitute any such warranty). No responsibility is assumed by XNR
|
|
73
|
+
for any claims arising out of Natural Earth’s use of the data.
|
|
74
|
+
|
|
75
|
+
Happy mapping!
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Map display metadata
|
|
2
|
+
|
|
3
|
+
## Source and visibility
|
|
4
|
+
|
|
5
|
+
The bundled `world.geojson` and `us-states.geojson` are Natural Earth political-boundary data. Rendered map scenes include a visible Natural Earth source credit and a brief political-boundary disclaimer. If a host supplies an external GeoJSON collection, the renderer labels its source as supplied GeoJSON rather than claiming Natural Earth provenance; the host remains responsible for showing the collection's actual source and attribution where applicable.
|
|
6
|
+
|
|
7
|
+
## Political-boundary display condition
|
|
8
|
+
|
|
9
|
+
Political boundaries are shown for neutral geographic visualization only. Their inclusion, names, lines, and omissions are not a statement, recognition, endorsement, or position on sovereignty, jurisdiction, or border delimitation. Rendering reflects the source data and scale and must not be treated as political or legal authority. Public-domain copyright status only addresses permission to use and redistribute the data; it does not establish political-display approval, regional compliance, or suitability for any particular jurisdiction. China-specific maps are not implemented.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Offline map assets
|
|
2
|
+
|
|
3
|
+
`world.geojson` (242 features) and `us-states.geojson` (50 features) are copied from the verified Natural Earth data bundle. Both are GeoJSON FeatureCollections containing Polygon/MultiPolygon geometries. The choropleth renderer uses each bundled feature's exact `properties.id` as its join key; it does not infer a key from the feature name. Hosts load these files as needed and inject the parsed collections as `ctx.assets.world` / `ctx.assets['us-states']`. The default projection is equirectangular; a host may select Mercator by injecting `ctx.assets.projection: 'mercator'`. Core map code never reads files or performs network requests.
|
|
4
|
+
|
|
5
|
+
## License, provenance, and display condition
|
|
6
|
+
|
|
7
|
+
These political boundaries are for neutral geographic visualization only. They are not a statement, recognition, endorsement, or position on sovereignty or border delimitation; representations and omissions follow the source data and scale. Hosts must keep the rendered source/disclaimer visible. Public-domain status concerns copyright permission only and does not imply political-display approval or regional compliance. China-specific maps are intentionally not included. See [`METADATA.md`](METADATA.md) for full display conditions and source visibility requirements.
|
|
8
|
+
|
|
9
|
+
The complete source `LICENSE.md` is retained alongside the data. Natural Earth states its map data is public domain and that use/redistribution is permitted. Suggested attribution: “Made with Natural Earth.” The bundled source also contains upstream credits/disclaimers; see the complete license text.
|
|
10
|
+
|
|
11
|
+
## Region code directory
|
|
12
|
+
|
|
13
|
+
The world layer's `properties.id` values are the exact identifiers in this asset, not a claim that every feature has an ISO code. Source `properties.code_source` counts are: `ISO_A3` 234, `ISO_A3_EH` 2, and `ADM0_A3` 6. The non-`ISO_A3` entries are:
|
|
14
|
+
|
|
15
|
+
| Exact `id` | Feature name | Source |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| `SOL` | Somaliland | `ADM0_A3` |
|
|
18
|
+
| `NOR` | Norway | `ISO_A3_EH` |
|
|
19
|
+
| `KOS` | Kosovo | `ADM0_A3` |
|
|
20
|
+
| `FRA` | France | `ISO_A3_EH` |
|
|
21
|
+
| `CYN` | Northern Cyprus | `ADM0_A3` |
|
|
22
|
+
| `IOA` | Indian Ocean Territories | `ADM0_A3` |
|
|
23
|
+
| `ATC` | Ashmore and Cartier Islands | `ADM0_A3` |
|
|
24
|
+
| `KAS` | Siachen Glacier | `ADM0_A3` |
|
|
25
|
+
|
|
26
|
+
All other world ids are the dataset's `ISO_A3` values. The states layer contains exactly 50 features and its exact `properties.id` values are `US-AK`, `US-AL`, `US-AR`, `US-AZ`, `US-CA`, `US-CO`, `US-CT`, `US-DE`, `US-FL`, `US-GA`, `US-HI`, `US-IA`, `US-ID`, `US-IL`, `US-IN`, `US-KS`, `US-KY`, `US-LA`, `US-MA`, `US-MD`, `US-ME`, `US-MI`, `US-MN`, `US-MO`, `US-MS`, `US-MT`, `US-NC`, `US-ND`, `US-NE`, `US-NH`, `US-NJ`, `US-NM`, `US-NV`, `US-NY`, `US-OH`, `US-OK`, `US-OR`, `US-PA`, `US-RI`, `US-SC`, `US-SD`, `US-TN`, `US-TX`, `US-UT`, `US-VA`, `US-VT`, `US-WA`, `US-WI`, `US-WV`, `US-WY`. This source does not include Washington, D.C.
|
|
27
|
+
|
|
28
|
+
Names in this directory are descriptive only; joins must use the exact `id` property. Do not derive codes from names.
|