LDN Viz Tools

This is a mono-repo containing several components:

• the @ldn-viz/charts package is in charts/ (CHANGELOG); it contains components for visualizing data
• the @ldn-viz/maps package is in maps/ (CHANGELOG); it contains components for rendering maps
• the @ldn-viz/tables package is in tables/ (CHANGELOG); it contains components for rendering tables
• the @ldn-viz/themes package is in theme/ (CHANGELOG); it contains CSS and design tokens that are used by other components
• the @ldn-viz/ui package is in ui/ (CHANGELOG); it contains general UI components like modals or sidebars
• the @ldn-viz/utils package is in utils/ (CHANGELOG); it contains utils functions (such as for constructing color scales)

These packages are intended primarily for use in projects created by Greater London Authority's City Intelligence Unit.

Tooling

The structure of this repo was initially based on Vercel's Turborepo & SvelteKit Starter template.

It uses:

• Turbo as an incremental bundler and build system
• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting
• Changesets to keep track of changes as they are made, and then automatically updating CHANGELOGfiles and version numbers in package.json files when releases are made

Developing with Storybook

There is a single storybook instance in apps/docs. Once installed run npm run storybook -w apps/docs from the repo root. This storybook instance draws stories from each of the packages - with a separate section for each.

Each package is structured so that components live next to their stories (and tests etc)

lib/
├─ src/
│ ├─ Button/
│ │ ├─ Button.svelte
│ │ ├─ Button.stories.svelte

Storybook needs to be restarted when adding a new story to allow it to index the new file.

You can preview the storybook by running npm run storybook -w apps/docs.

Contributing, and Publishing packages

Development should occur in feature branches that are branched off from the dev branch. The dev branch is periodically merged into the main branch, from which releases are made.

Following the recommendations of the Turbo project maintainers, we use changesets to keep track of changes.

Before merging a PR that adds a feature or fixes a bug, run the command npx changeset. This will prompt for a description of the changes, which will be saved as a markdown file in .changeset/. For more details, see the Adding a Changeset section of the changeset docs.

When writing changelog messages, consider the suggestions from keep a changelog.

When a release is made, changeset will add these descriptions of changes to a CHANGELONG.md file in the directory of the appropriate package; the version numbers in package.json files will also be updated appropriately.

Making releases/publishing packages

Rather than having a fixed release schedule, we make releases when someone wants to make use of unreleased code in the main branch.

The process for making a release is:

• check whether there are any open PRs that should be included in the release; if so, merge them first
• merge from the dev branch into the main branch, using the 'merge commit' option (this will mean that each commit made to the dev branch will be added to the main branch)
• manually trigger the publish-packages workflow in GitHub. This runs the publish-packages script defined in the top-level package.json file. It uses a token that was generated in NPM and saved as an Action secret in GitHub.
• make a Pull Request from the release-msg branch to main, merge it, then delete the branch (the action that generates the release notes can't push directly to the main branch because it is protected, and GitHub Actions can't push to protected branches)
• merge from the main branch to dev, using the 'merge commit' option

The version number badges on the README will update automatically.