@nebula.js/sn-org-chart 1.8.0 → 1.10.0

package/README.md

@@ -13,20 +13,85 @@ You can also load through the script tag directly from [https://unpkg.com](https
 ## Usage
 
 ```js
-
-import { embed } from '@nebula.js/stardust';
-import org from '@nebula.js/sn-org-chart';
+import { embed } from "@nebula.js/stardust";
+import org from "@nebula.js/sn-org-chart";
 
 // 'app' is an enigma app model
 const nuked = embed(app, {
-  types: [{
-    name: 'orgchart',
-    load: () => Promise.resolve(org);
-  }]
+  types: [
+    {
+      name: "orgchart",
+      load: () => Promise.resolve(org),
+    },
+  ],
 });
 
-embed.render({
+nuked.render({
   element,
-  type: 'orgchart',
+  type: "orgchart",
+  fields: ["EmployeeID", "ManagerID"],
 });
 ```
+
+## Data requirements
+
+The chart needs exactly two dimensions and accepts one optional measure:
+
+| Position    | Role              | Notes                                                                         |
+| ----------- | ----------------- | ----------------------------------------------------------------------------- |
+| Dimension 1 | Node id           | Must be unique per node. Shown as the card title unless a label is provided.  |
+| Dimension 2 | Parent id         | Must match another row's node id. A non-matching value makes the node a root. |
+| Measure     | Value on the card | Optional. Rendered as `<measure title>: <value>`.                             |
+
+Extra content per node is added as attribute expressions on dimension 1, matched by `id`:
+
+| Attribute expression id | Shown as                                        |
+| ----------------------- | ----------------------------------------------- |
+| `labelExpression`       | Card title                                      |
+| `subLabelExpression`    | Card sub-title                                  |
+| `extraLabelExpression`  | Card description (only when no measure is used) |
+| `imageExpression`       | Image URL (`http`, `https` or `data:`)          |
+| `colorByExpression`     | Card background color                           |
+
+Multiple roots are grouped under a synthetic root node, and circular references are reported as a warning. See the [data model documentation](./docs/data-model.md) for details.
+
+## Development
+
+Requires Node.js 24 or later and pnpm.
+
+```bash
+pnpm install
+pnpm start        # dev server on http://localhost:8000
+pnpm test:unit    # vitest
+pnpm test:e2e     # playwright rendering tests
+```
+
+### Building
+
+`pnpm install` runs the `prepare` script, which generates translations and then runs `pnpm run generate` to generate the TypeSpec outputs, including the JSON Schema at `tsp-output/@typespec/json-schema/sn-org-chart.json`. These generated files are ignored by Git, so installation must complete before building, including in CI.
+
+Run `pnpm generate` again after changing the TypeSpec definitions. If installation was run with lifecycle scripts disabled (for example, `pnpm install --ignore-scripts`), run `pnpm run prepare` manually to generate both translations and TypeSpec outputs.
+
+Builds copy the existing schema without regenerating it. The build calls `copyJsonSchema()` from `tools/copy-json-schema.js` to copy it to `api-specifications/sn-org-chart.json` before bundling:
+
+```sh
+pnpm build
+```
+
+For a development build, run `pnpm build:dev`. To rebuild on changes, run `pnpm build:watch`.
+
+See [.github/CONTRIBUTION.md](./.github/CONTRIBUTION.md) for the contribution workflow.
+
+## Documentation
+
+Deeper documentation lives in [`docs/`](./docs/README.md):
+
+- [Data model](./docs/data-model.md) — hypercube setup and how rows become a tree
+- [Architecture](./docs/architecture.md) — modules, render lifecycle, property panel
+- [Layout and navigation](./docs/layout-and-navigation.md) — positioning, expand/collapse, zoom, selections, snapshots
+- [Styling and theming](./docs/styling-and-theming.md) — card styling model, colours, theme integration
+- [Development](./docs/development.md) — scripts, tests, CI and release
+
+## License
+
+[MIT](./LICENSE)

package/api-specifications/properties.json

@@ -3,7 +3,7 @@
   "info": {
     "name": "@nebula.js/sn-org-chart:properties",
     "description": "Org chart generic object definition",
-    "version": "1.8.0",
+    "version": "1.10.0",
     "license": "MIT",
     "stability": "experimental",
     "x-qlik-visibility": "public"