@nnc-digital/nnc-design-system 1.0.0-beta19 → 1.0.0-beta20

package/README.md

@@ -1,209 +1,191 @@
-# 🎨 North Northants Design Sytem
+# 🎨 North Northants Design System
 
-[![Netlify Status](https://api.netlify.com/api/v1/badges/19c44b04-97ec-4066-84f8-fd7106d00996/deploy-status)](https://app.netlify.com/sites/elated-pasteur-e85c66/deploys)
+Design system for North Northamptonshire.
 
-👉 **[You can view the design system here](https://northants-design-system.netlify.app)**
+## Quick overview
 
-The design system for North Northamptonshire & West Northamptonshire, two brand new unitary councils encompassing Wellingborough, Corby, Daventry, East Northants, Kettering, Northampton, Northamptonshire County and South Northants.
+- Storybook: v10 (Vite builder)
+- Bundler: Rollup for library artifacts
+- Types: TypeScript
+- Tests: Vitest with Storybook addon
 
 ## Requirements
 
-Requires node v18 for Storybook v7. If you have nvm installed then you can run `nvm use` and it will autodetect the correct version of node to use.
+Node 20 is recommended. Use `nvm use 20` or your preferred Node manager.
 
-## Installation
+## Development
 
-### Installation and development of the Design System
+Prerequisites: `node` and `npm` installed.
 
-You need `node` and `npm` installed.
+1. Clone the repo
+2. Install dependencies:
 
-1. Clone the repo and `npm i`
-2. `npm run dev` will start up the Storybook playground and start `rollup` watching for changes.
-
-### Installation using docker
-
-This option is recommended if your using a windows machine
-
-```sh
-// build with no cache
-docker-compose build --no-cache
-
-// start the services
-docker-compose up
-
-// list the services
-docker-compose ps
-
-// list the containers
-docker ps
-
-// stop services
-docker-compose stop
+```bash
+npm ci
 ```
 
-## Documentation
+3. Start Storybook locally:
 
-This design system is made up from a combination of these libraries:
-
-- [Rollup](https://github.com/rollup/rollup)
-- [Storybook](https://storybook.js.org/) to help you create and show off your components
-- [TypeScript](https://www.typescriptlang.org/)
-- [Jest](https://jestjs.io/) and [React Testing Library](https://github.com/testing-library/react-testing-library) enabling testing of the components
-
-## Examples
-
-👉 **[You can view the design system here](https://northants-design-system.netlify.app)**
-
-This is a living documentation powered by [Storybook](https://storybook.js.org/), where you can see all the available components, their variations and documentation.
-
-### Using the design system in your project
+```bash
+npm run storybook -- --no-open
+```
 
-You can find the design system [here on NPM](https://www.npmjs.com/package/northants-design-system).
+4. Run component tests:
 
+```bash
+npm run storybook:test
 ```
-npm install nnc-design-system
 
-// Install peer dependencies
-npm install react react-dom styled-components @reach/router
-```
+5. Build the component library:
 
-This design system uses theming - **it will not work without a theme wrapped around the components** - to use a theme you will need to include a `ThemeProvider` from styled components, [you can find out more about how this works here](https://styled-components.com/docs/advanced#theming). Then you will need to import one of the three themes from the design system, or create your own. The three avaliable are `GDS_theme` (a basic style based on the [GDS design system](https://design-system.service.gov.uk/)), `west_theme` and `north_theme` (themes for North and West Northamptonshire styled components).
+```bash
+npm run build
+npm run postbuild
+```
 
-This `ThemeProvider` can be wrapped around the entire app, or around a single component
+5. Export static Storybook (used by CI and publishing):
 
+```bash
+npm run storybook:export
 ```
-import { ThemeProvider } from 'styled-components';
-import { GDS_theme } from "nnc-design-system";
 
-```
+Notes:
+- Storybook now uses the Vite builder (`@storybook/react-vite`) — we no longer use webpack or `@storybook/react-webpack5`.
+- The MDX runtime integration (`@storybook/mdx2-csf`) was removed in favor of Storybook v10 built-in MDX handling.
 
-Import the components you'd like to use into your app. For example:
+## Using the design system in your project
 
-```
-import React from "react"
-import { Button } from "nnc-design-system"
+Install from npm:
 
-const MyComponent = () =>
-    <Button text="Button Label" />
+```bash
+npm install nnc-design-system
 ```
 
-Each component has documentation in the design system explaining the avaliable props, how to use it, and any guidance on using it.
+Install peer deps (example):
 
-We are also using a [CSS reset](http://meyerweb.com/eric/tools/css/reset/) which you should add to your frontend when using this design system, to ensure the styles are correct.
+```bash
+npm install react react-dom styled-components
+```
 
-### Putting it all together
+This design system uses theming — wrap components with a `ThemeProvider` from `styled-components` and pass a theme (e.g., `GDS_theme`, `north_theme`, `west_theme`).
 
-```
-import React from "react"
-import { Button } from "nnc-design-system"
+```tsx
 import { ThemeProvider } from 'styled-components';
-import { GDS_theme } from "nnc-design-system";
+import { GDS_theme, Button } from 'nnc-design-system';
 
-const MyComponent = () =>
+const MyComponent = () => (
   <ThemeProvider theme={GDS_theme}>
     <Button text="Button Label" />
   </ThemeProvider>
+);
 ```
 
-## Documentation
-
-### Creating and generating new components
+## Configuration
 
-There is a util file under `util` called `create-component.js`. Instead of copy pasting components to create a new component, you can just run this command to generate all the files you need to start building out a new component. To use it:
+This design system requires configuration for API endpoints and keys. Wrap your app with `DesignSystemProvider` and pass a config object:
 
-```
-npm run generate NewComponentName
-```
+```tsx
+import { ThemeProvider } from 'styled-components';
+import { DesignSystemProvider, GDS_theme, Button } from 'nnc-design-system';
 
-This will generate:
+const config = {
+  postcodeSearchApiUrl: 'https://api.example.com/postcode/',
+  binCollectionApiBaseUrl: 'https://api.example.com/bin/',
+  googleMapsApiKey: 'your-api-key',
+};
 
+const MyApp = () => (
+  <DesignSystemProvider config={config}>
+    <ThemeProvider theme={GDS_theme}>
+      <Button text="Button Label" />
+    </ThemeProvider>
+  </DesignSystemProvider>
+);
 ```
-/src
-  /NewComponentName
-    NewComponentName.tsx
-    NewComponentName.stories.tsx
-    NewComponentName.test.tsx
-    NewComponentName.types.ts
-    NewComponentName.styles.ts
-```
-
-The default templates for each file can be modified under `util/templates`.
-
-Don't forget to add the component to your `index.ts` exports if you want the library to export the component.
-
-### How to publish a new version to NPM
-
-First, make sure you have an NPM account and are [logged into NPM using the `npm login` command.](https://docs.npmjs.com/creating-a-new-npm-user-account)
-
-1. **information about testing needed here**
-2. If tests pass...
-2. Increment the next version number in the `package.json` file.
-3. `npm publish`. This will:
-    - Run the tests
-    - Bundle and transpile the code
-    - Create and publish a tarball to NPM
-4. If you are wanting to utilise the updated design system you will then need to update the version number of the design system in the `package.json` file within that repo.
-
-### Installing component library locally for IE11 (or other uses) but this is easier and less buggy
 
-https://www.viget.com/articles/how-to-use-local-unpublished-node-packages-as-project-dependencies/
+## Creating and generating new components
 
-Good article on this can be found [here](https://www.viget.com/articles/how-to-use-local-unpublished-node-packages-as-project-dependencies/)
+Use the generator:
 
-Install yalc **globally**
-Using NPM: `npm i yalc -g`
-Using Yarn: `yarn global add yalc`
-
-In the **nnc-design-system**  
-You will need node v14.17.3 > to build on windows
+```bash
+npm run generate NewComponentName
+```
 
-run `yalc publish`
+It scaffolds component source, stories, tests and types under `src/`.
 
-In **your other repository**  
-run `yalc add nnc-design-system` then run `npm install` or `yarn`
+## Publishing
 
-Then run `npm run start` to run the application.
+1. Run tests and build locally:
 
-You will need node v14.17.3 > to build on windows
+```bash
+npm run storybook:test
+npm test
+npm run build
+npm run storybook:export
+```
 
-Install yalc 
-Using NPM:
+2. Update the `version` in `package.json` and publish:
 
-`npm i yalc -g`
+```bash
+npm publish
+```
 
-Using Yarn:
+The CI will also produce a static Storybook artifact.
 
-`yarn global add yalc`
+## Local development tips
 
-run `yalc publish` in the design system folder
+- If you need to work with an unpublished local copy, prefer tarball install or `npm link` (instructions below).
+- For older Windows builds you may need a specific Node version; prefer Docker if you hit native build issues.
 
-run `yalc add nnc-design-system` in ie11-test-folder
+## Migration notes
 
-`npm install`
+- We migrated Storybook to v10 with built-in MDX handling. During the migration we:
+  - removed runtime `mdx2-csf` integration
+  - aligned `@mdx-js/*` packages
+  - removed `@storybook/react-webpack5` usage and moved to `@storybook/react` + Vite builder
+- Added Vitest with Storybook addon for component testing in browser mode using Playwright.
 
-to make changes and update them 
+### How to publish a new version to NPM
 
-in design system `yalc push` (this automatically updates all dependencies on all yalc files)
+First, make sure you have an NPM account and are [logged into NPM using the `npm login` command.](https://docs.npmjs.com/creating-a-new-npm-user-account)
 
-or `yalc publish` in design system and `yalc update` in your projects repo
+1. Test locally before publishing (recommended)
 
-### Installing Component Library Locally
+```bash
+# build the library and create a tarball
+npm run build && npm pack
+# example tarball: nnc-digital-nnc-design-system-1.0.0-beta18.tgz
+```
 
-Let's say you have another project (`test-app`) on your machine that you want to try installing the component library into without having to first publish the component library. In the `test-app` directory, you can run:
+- Install the tarball into a local frontend project to verify integration:
 
+```bash
+# from your frontend project root
+npm install /absolute/path/to/nnc-digital-nnc-design-system-1.0.0-beta18.tgz
+# or with yarn
+yarn add file:/absolute/path/to/nnc-digital-nnc-design-system-1.0.0-beta18.tgz
 ```
-npm i --save ../react-component-library
-```
 
-which will install the local component library as a dependency in `test-app`. It'll then appear as a dependency in `package.json` like:
+- Start the frontend dev server (`npm start` / `npm run dev`) and verify:
+  - The app builds without errors.
+  - Components import from `@nnc-digital/nnc-design-system` and render correctly.
+  - Styles and theming are applied (wrap with `ThemeProvider` if needed).
+  - No unresolved peer dependency warnings (install matching versions of `react`, `react-dom`, etc. if required).
+
+- Iterative alternatives for development without re-packing:
+  - `npm link` — link the library into your frontend for live changes:
 
-```JSON
-  ...
-  "dependencies": {
-    ...
-    "react-component-library": "file:../react-component-library",
-    ...
-  },
-  ...
+```bash
+# in the design system root
+npm link
+# in the frontend project
+npm link @nnc-digital/nnc-design-system
 ```
 
-Your components can then be imported and used in that project.
+2. If tests pass and local verification is successful
+3. Increment the next version number in the `package.json` file.
+4. `npm publish`. This will:
+    - Run the tests
+    - Bundle and transpile the code
+    - Create and publish a tarball to NPM
+5. If you are wanting to utilise the updated design system you will then need to update the version number of the design system in the `package.json` file within that repo.

package/build/index.d.ts

@@ -13,7 +13,8 @@ import DropDownFilter from './library/components/DropDownFilter/DropDownFilter';
 import PromotedLinks from './library/components/PromotedLinks/PromotedLinks';
 import StaticMap from './library/components/StaticMap/StaticMap';
 import TextInput from './library/components/TextInput/TextInput';
-export { Autocomplete, BackToTop, Button, BinCollection, DynamicIcon, Heading, HeadingWithIcon, Map, MapMarker, Pagination, CheckboxListFilter, DropDownFilter, PromotedLinks, StaticMap, TextInput, };
+import { DesignSystemProvider } from './library/contexts/ConfigContext/ConfigContext';
+export { Autocomplete, BackToTop, Button, BinCollection, DynamicIcon, Heading, HeadingWithIcon, Map, MapMarker, Pagination, CheckboxListFilter, DropDownFilter, PromotedLinks, StaticMap, TextInput, DesignSystemProvider, };
 import Accordion from './library/slices/Accordion/Accordion';
 import BlockQuote from './library/slices/BlockQuote/BlockQuote';
 import CallToAction from './library/slices/CallToAction/CallToAction';
@@ -41,5 +42,6 @@ import DirectoryShortList from './library/directory/DirectoryShortList/Directory
 import { DirectoryShortListProvider, useDirectoryShortListContext } from './library/contexts/DirectoryShortListProvider/DirectoryShortListProvider';
 import DirectoryDocumentList from './library/directory/DirectoryDocumentList/DirectoryDocumentList';
 export { DirectoryService, DirectoryServiceList, DirectoryShortList, DirectoryShortListProvider, useDirectoryShortListContext, DirectoryDocumentList, };
+export type { DirectoryCategory } from './library/directory/DirectoryServiceList/DirectoryServiceList.types';
 export * from './library/events';
 export { EventPage } from './library/pages/EventPage';