@madgex/design-system 12.0.2 → 13.0.0

package/README.md

@@ -22,6 +22,8 @@ if you want to use the default styling set in the design system, you can use the
 
 ## Working with [hapi.js](https://hapijs.com/), [vision](https://github.com/hapijs/vision) and [Nunjucks](https://mozilla.github.io/nunjucks/)
 
+### Nunjucks
+
 If you're wanting to use the Madgex DS components from a hapi.js+vision+Nunjucks setup you'll need to include the Madgex DS in the Nunjucks pathing:
 
 ```js
@@ -72,6 +74,47 @@ Then you should be able to use components as such:
 
 Note you'll need the CSS for the component styles.
 
+### Serving Design System assets - Hapi
+
+We want to serve the whole `dist` folder of the design system package, rather than just singular files. This will enable relative ESM imports which `index.js` does, where it will try to include additional js files relative to itself.
+
+Be sure to pevent URL attacks by confining to this dist directory. Inert `directory` handler does this by default.
+
+```js
+const mdsDistFolderPath = path.join(
+  path.dirname(fileURLToPath(import.meta.resolve('@madgex/design-system/package.json'))),
+  'dist',
+);
+export default [
+  {
+    path: `/_/jobseekers-frontend/public/design-system/{path*}`,
+    handler: {
+      directory: {
+        // using `directory` should mean we are using inert's 'confine' automatically, to prevent URL attacks e.g. `/_/jobseekers-frontend/public/design-system/..%2F..%2F..%2F..%2F/package.json`
+        path: [mdsDistFolderPath],
+      },
+    },
+    options: {
+      id: 'public.assets.design-system',
+      description: 'public assets route design system, allows relative ESM imports against whole MDS dist folder',
+      validate: {
+        params: {
+          path: Joi.string().max(200).required(),
+        },
+      },
+    },
+  },
+];
+```
+
+consuming the `index.js` file is all that is needed, relative ESM imports will automatically happen.
+
+```twig
+<link rel="stylesheet" href="{{- getRoute('public.assets.design-system', { path: 'css/index.css' }, { v: designSystemVersion }) -}}">
+<script type="module" src="{{- getRoute('public.assets.design-system', {  path: 'js/index.js' }, { v: designSystemVersion }) -}}"></script>
+{# index.js also import `./components/mds-dropdown-nav.js` etc, which is why we serve the whole `dist` folder on `public.assets.design-system` route #}
+```
+
 ## Releases
 
 With every commit to `master` the build server attempts to create a new version using [semantic-release](https://semantic-release.gitbook.io/semantic-release/) and deploys to [npm](https://npmjs.org) as [@madgex/design-system](https://www.npmjs.com/package/@madgex/design-system).
@@ -140,7 +183,7 @@ await cleanTempFiles();
 
 ### Web Components
 
-Web components are built into the main JS bundle.
+Web components are included via the main JS bundle, using ESM relative imports.
 
 Seperate web component files are also available in `@madgex/design-system/dist/components/{component-name}.js`. e.g. `@madgex/design-system/dist/components/mds-dropdown-nav.js`.