# sn-org-chart

Organizational chart for use with Qlik's Analytics Platform.

![Org chart](./assets/preview.png)

## Installing

Install as npm package: `npm install @nebula.js/sn-org-chart`.

You can also load through the script tag directly from [https://unpkg.com](https://unpkg.com/@nebula.js/sn-org-chart).

## Usage

```js
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),
    },
  ],
});

nuked.render({
  element,
  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)
