docs(pie-docs): DSW-2211 adding overview of web components (#1589)

* docs(pie-docs): DSW-2211 add tag shortcode to pie docs

This shortcode copy the web component variants. Can be removed once we are able to use our web
components in pie docs.

* docs(pie-docs): DSW-2211 adding overview of web components

Refactors some copy and adds a guide to choose waht component library to use.

* docs(pie-docs): DSW-2211 removes new lines and adds changeset file

* docs(pie-docs): DSW-2211 fix formatting in headings

* docs(pie-docs): DSW-2211 add missing route for testing

* docs(pie-docs): DSW-2211 updates README with config for running tests locally

* docs(pie-docs): DSW-2211 address PR comments

* docs(pie-docs): DSW-2211 address PR comments

Co-authored-by: Ashley Watson-Nolan <[email protected]>
Co-authored-by: Xander Marjoram <[email protected]>

* docs(pie-docs): DSW-2211 address PR comments

* docs(pie-docs): DSW-2211 pr comments - intro section and Next 13 copy

* Apply suggestions from code review

docs(pie-docs): DSW-2211 address PR comments

Co-authored-by: Xander Marjoram <[email protected]>

---------

Co-authored-by: Ashley Watson-Nolan <[email protected]>
Co-authored-by: Xander Marjoram <[email protected]>

.changeset/neat-lies-relax.md

@@ -0,0 +1,5 @@
+---
+"pie-docs": minor
+---
+
+[Changed] - Updates Engineering copy and adds new Web Components index guide to current documentation in Github Wiki.

apps/pie-docs/README.md

@@ -59,16 +59,23 @@ Our primary concerns are:
 4. Our shortcodes return the expected HTML
 
 ### Page testing
+
 We have route navigation tests that ensure all existing pages can be correctly navigated to. When you add new pages, these tests will fail as there are new unexpected pages (this is by design).
 
-In order to fix the tests, you will need to register the routes to your newly added pages by running from the root of the monorepo: `yarn test:generate-routes`. This will update the JSON file named `expected-routes.snapshot.json` with the URLs to your new page.
+Route tests need a production build so that they do not fail with `draft` page routes. For this, we recommend to:
+1. Stop any local instance of the doc site 
+2. Delete your `dist` folder 
+3. Create a production build with `yarn build --filter=pie-docs` 
 
+Once this is done, you can run the route tests with `yarn test --filter=pie-docs`.
 From here, we run navigation, accessibility and visual tests against each route.
 
-#### Running the route tests
-Route tests are ran as part of `yarn test`.
+#### Adding new routes
+
+In order to fix the tests, you will need to register the routes to your newly added pages by running the following command from the root of the monorepo: `yarn test:generate-routes`. This will update the JSON file named `expected-routes.snapshot.json` with the paths to your new pages.
+
+### Testing navigation responses
 
-#### Testing navigation responses
 Running `yarn test:browsers` will ensure that navigating to the routes stored in `expected-routes.snapshot.json` result in Status Code `200` responses.
 
 In order to run this command you will need the site to be served to localhost by running `yarn dev --filter=pie-docs` in another terminal.

apps/pie-docs/src/_11ty/shortcodes/index.js

@@ -11,6 +11,7 @@ const mediaElement = require('./mediaElementList');
 const notification = require('./notification');
 const resourceTable = require('./resourceTable');
 const simpleTable = require('./simpleTable');
+const tag = require('./tag');
 const termsAndDescriptions = require('./termsAndDescriptions');
 const tokensTable = require('./tokensTable');
 const usage = require('./usage');
@@ -36,8 +37,9 @@ const addAllShortCodes = (eleventyConfig) => {
     eleventyConfig.addShortcode('notification', (shortcodeArgs) => deindentHTML(notification(shortcodeArgs)));
     eleventyConfig.addShortcode('resourceTable', (shortcodeArgs) => deindentHTML(resourceTable(shortcodeArgs)));
     eleventyConfig.addShortcode('simpleTable', (shortcodeArgs) => deindentHTML(simpleTable(shortcodeArgs)));
-    eleventyConfig.addShortcode('tokensTable', (shortcodeArgs) => deindentHTML(tokensTable(shortcodeArgs)));
+    eleventyConfig.addShortcode('tag', (shortcodeArgs) => deindentHTML(tag(shortcodeArgs)));
     eleventyConfig.addShortcode('termsAndDescriptions', (shortcodeArgs) => deindentHTML(termsAndDescriptions(shortcodeArgs)));
+    eleventyConfig.addShortcode('tokensTable', (shortcodeArgs) => deindentHTML(tokensTable(shortcodeArgs)));
     eleventyConfig.addShortcode('usage', (shortcodeArgs) => deindentHTML(usage(shortcodeArgs)));
 };
 

apps/pie-docs/src/_11ty/shortcodes/tag.js

@@ -0,0 +1,13 @@
+// @TODO DSW-2258: be replaced once web components are integrated
+/**
+ * Generate an HTML tag component. It duplicates pie tag variants.
+ * Can be replaced by pie tag when we include pie web components
+ * @param {string} label - string that renders within the tag
+ * @param {string} variant - variant name: neutral, blue, green,
+ * yellow, red, brand, neutral-alternative, outline, ghost
+ * @returns {string}
+ */
+module.exports = ({
+    label,
+    variant,
+}) => `<span class="c-tag" variant="${variant}">${label}</span>`;

apps/pie-docs/src/assets/styles/_dependencies.scss

@@ -59,6 +59,7 @@
 @use 'components/simpleTable';
 @use 'components/table';
 @use 'components/tabs';
+@use 'components/tag';
 @use 'components/termsAndDescriptions';
 @use 'components/toggle';
 @use 'components/tokensTable';

apps/pie-docs/src/assets/styles/components/_tag.scss

@@ -0,0 +1,85 @@
+@use '@justeattakeaway/pie-css/scss/settings' as *;
+@use '@justeattakeaway/pie-css/scss' as p;
+
+.c-tag {
+    --tag-bg-color: var(--dt-color-container-strong);
+    --tag-color: var(--dt-color-content-default);
+    --tag-border-radius: var(--dt-radius-rounded-b);
+    --tag-padding-block: 2px;
+    --tag-padding-inline: var(--dt-spacing-b);
+    --tag-font-family: var(--dt-font-body-s-family);
+    --tag-font-weight: var(--dt-font-body-s-weight);
+    --tag-font-size: #{p.font-size(--dt-font-body-s-size)};
+    --tag-line-height: #{p.line-height(--dt-font-body-s-line-height)};
+
+    // transparent to variable to function properly in component tests
+    --tag-transparent-bg-color: transparent;
+
+    // Pie Webc Icon var that is used to ensure the correctly sized icon passed in a slot
+    --icon-display-override: block;
+    --icon-size-override: 16px;
+
+    display: inline-flex;
+    vertical-align: middle;
+    align-items: center;
+    justify-content: center;
+    gap: var(--dt-spacing-a);
+    padding: var(--tag-padding-block) var(--tag-padding-inline);
+    border-radius: var(--tag-border-radius);
+    background-color: var(--tag-bg-color);
+    color: var(--tag-color);
+    font-family: var(--tag-font-family);
+    font-weight: var(--tag-font-weight);
+    font-size: var(--tag-font-size);
+    line-height: var(--tag-line-height);
+
+
+    &[variant='neutral'] {
+        // same as default styles
+    }
+
+    &[variant='blue'] {
+        --tag-bg-color: var(--dt-color-support-info-02);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='green'] {
+        --tag-bg-color: var(--dt-color-support-positive-02);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='yellow'] {
+        --tag-bg-color: var(--dt-color-support-warning-02);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='red'] {
+        --tag-bg-color: var(--dt-color-support-error-02);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='brand'] {
+        --tag-bg-color: var(--dt-color-support-brand-02);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='neutral-alternative'] {
+        --tag-bg-color: var(--dt-color-container-default);
+        --tag-color: var(--dt-color-content-default);
+    }
+
+    &[variant='outline'] {
+        --tag-bg-color: var(--tag-transparent-bg-color);
+        --tag-color: var(--dt-color-content-default);
+
+        // the outline in design specs is part of the total component
+        // height calculation, thus, we use box-shadow to mimic borders
+        // and avoid the extra 2px from "border: 1px solid" as shadows are applied "internally"
+        box-shadow: 0 0 0 1px var(--dt-color-border-strong);
+    }
+
+    &[variant='ghost'] {
+        --tag-bg-color: var(--tag-transparent-bg-color);
+        --tag-color: var(--dt-color-content-default);
+    }
+}

apps/pie-docs/src/engineers/getting-started/overview.md

@@ -10,17 +10,11 @@ permalink: engineers/getting-started/
 
 One of the core aims of the **PIE Design System** is to provide engineers with a consistent set of components and best practices for creating and maintaining UIs across JET.
 
-If you're just starting out with PIE, here's a list of recommended resources to get you started.
-
----
-
-## Code and Project Structure
-
-All of our PIE components, tools and documentation (including this site) are maintained on the open-source [PIE Monorepo on Github](https://github.com/justeattakeaway/pie).
+We develop and maintain several component libraries that implement the PIE design language. Please follow [this guide](/engineers/getting-started/structure/#which-library-should-i-use) to find out which library to use based on your tech stack.
 
 For a more detailed look at the **component systems** the PIE team maintain, the PIE monorepo and how it’s structured, see the [structure section of our engineering docs](/engineers/getting-started/structure).
 
-We also help to maintain a number of other projects that incorporate the PIE Design Language (such as [Fozzie](https://github.com/justeattakeaway/fozzie-components) for **VueJS components**, or [Snacks](https://snacks.takeaway.com/) and [Skip PIE](https://github.com/justeat/pie-project) for **React components**).
+For a list of which components are supported in each of our libraries, please refer to the [Component Status page](/components/component-status/).
 
 ---
 
@@ -30,6 +24,11 @@ If you'd like to contribute to PIE, check out our [contributing guide](/engineer
 
 We also maintain **guides** for global front-end best practices across JET. These can be found in the [engineering guidelines section of our docs](/engineers/guidelines/).
 
+### Code and Project Structure
+
+PIE Web Components, tools and documentation (including this site) are maintained on the open-source [PIE Monorepo on Github](https://github.com/justeattakeaway/pie).
+
+We support and maintain a number of other projects that incorporate the PIE Design Language (such as [Fozzie](https://github.com/justeattakeaway/fozzie-components) for **VueJS components**, or [Snacks](https://snacks.takeaway.com/) and [Skip PIE](https://github.com/justeat/pie-project) for **React components**).
 
 <!-- N.B. for the future – we should include a components summary section here like this when we want to start advertising our components:
 

apps/pie-docs/src/engineers/getting-started/structure.md

@@ -4,6 +4,7 @@ eleventyNavigation:
     title: Structure
     parent: engineers-getting-started
     order: 2
+shouldShowContents: true
 ---
 
 ## PIE Component Systems
@@ -49,6 +50,95 @@ For more details on Fozzie, Snacks and Skip PIE, please check out the **document
 
 ---
 
+##  Which library should I use?
+
+### Latest tech stack and Vanilla JS
+
+{% contentLayout %}
+    {% tag {
+    label: "Next 14",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "React 18",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "Nuxt 3",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "Vue 3",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "Vanilla JS",
+    variant: "blue"
+    } %}
+{% endcontentLayout %}
+
+If you are working with latest stack both in React and Vue ecosystems, we recommend to go straight away with
+[PIE Web Components](/engineers/web-components/).
+
+### Next 13 and earlier versions 
+
+{% contentLayout %}
+    {% tag {
+    label: "Next 13",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "Next 10",
+    variant: "blue"
+    } %}
+{% endcontentLayout %}
+
+You can use [PIE Web Components](/engineers/web-components/) for Next 13 or earlier versions if you don't need SSR. 
+If you need to render components on the server (SSR), [Snacks](https://snacks.takeaway.com/portal/) is the best library for you.
+
+We recommend updating to Next 14 if you would like to use SSR with our new Web Components.
+
+### Vue and Nuxt 2
+
+{% contentLayout %}
+    {% tag {
+    label: "Vue 2",
+    variant: "blue"
+    } %}
+    {% tag {
+    label: "Nuxt 2",
+    variant: "blue"
+    } %}
+{% endcontentLayout %}
+
+Our [Fozzie](https://vue.pie.design/) library currently supports older versions of Vue. We recommend updating to the latest Vue ecosystem if possible.
+
+### What if I'm working on a greenfield project?
+
+We recommend using [PIE Web Components](/engineers/web-components/) as much as you can, if your tech stack is supported. This helps us test our new components and avoids any need for a future migration.
+
+### I can't find the web component I need
+
+**I need it right away**
+
+If you need the component right away, check our legacy libraries ([Snacks](https://snacks.takeaway.com/) and [Fozzie](https://vue.pie.design/)) in case a suitable component already exists.
+We also recommend to check with our team if you can use another existing component for your solution instead.
+
+If you can't wait and can't find the component in our libraries, please implement it yourself in your codebase.
+
+
+**I can wait for the component to be implemented**
+
+If you have some time before needing the component or are planning ahead, please reach out to us in **#help-designsystem** to check if we can include the component you need.
+
+In our current process it takes us around a month and a half to two months to have a new component ready from design to implementation, so keep this in mind.
+
+**I'd like to contribute to the component library**
+
+If you are willing and able to contribute to the web component library, we can prioritise an ad-hoc design audit, and have the designs ready for contribution in 2-4 weeks. We have processes in place to support you during your time working in our codebase and would greatly appreciate your contribution.
+
+___
+
 ## PIE project structure
 
 ### The PIE Monorepo
@@ -72,7 +162,7 @@ For instance, the code for the `pie.design` documentation site lives inside the
 
 The `/packages` folder contains all the shareable packages that can be installed and used by engineers across JET (available via NPM).
 
-This folder is currently split into two categories; **Components** and **Tools**.
+This folder is currently split into two categories: **Components** and **Tools**.
 
 The `/packages/components` directory is where our global PIE Web Component packages can be found, such as `pie-button`.
 

apps/pie-docs/src/engineers/web-components/overview.md

@@ -0,0 +1,49 @@
+---
+eleventyNavigation:
+    key: Overview
+    parent: engineers-web-components
+    order: 1
+permalink: engineers/web-components/
+---
+
+## Introduction
+
+[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) are a set of native browser technologies that allow us to build custom components. In other words, create custom HTML elements native to browsers. 
+
+Currently, this technology is supported by all browsers, making it possible to have one central library that will work with most frontend frameworks.
+
+The long-term aim will be to migrate JET teams over to this Web Component System, so we have one single source of truth for our global PIE components.
+
+---
+
+## Component status
+
+You can find the documentation for all of our components on this site in the **Components** section.
+
+For a list of which components are supported in each of our libraries, please refer to the [Component Status page](/components/component-status/).
+
+___
+
+## Getting started
+
+For every framework, you can start with our [Prerequisites Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
+
+For specific framework versions, please follow these guides:
+
+[Vue 3 Integration Guide](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Vue-Integration-Guide)
+
+[Nuxt 3 Integration Guide](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Nuxt-3)
+
+[Vue & Nuxt ‐ Known gotchas](https://github.com/justeattakeaway/pie/wiki/Vue-Nuxt-%E2%80%90-Known-gotchas)
+
+For existing users, you may be interested in our [Migration guide of Web Components to Lit 3](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Nuxt-2---Next-10---Vue-2-Integration). This guide also details some specific configurations for React, Next and Vue2.
+
+More guides coming soon! 🚀
+
+___
+
+## Usage
+
+The following guides are meant to support you while using our web components.
+
+For information about form elements and how to handle form data and validation, check out our [Form Usage Guide](https://github.com/justeattakeaway/pie/wiki/Form-Controls#pie-forms-usage).

apps/pie-docs/src/engineers/web-components/web-components.json

@@ -0,0 +1,5 @@
+{
+  "title": "Web Components",
+  "navKey": "engineers-web-components",
+  "description": "In this section you’ll find all the information you need to use our PIE Web Components library."
+}

apps/pie-docs/src/engineers/web-components/web-components.md

@@ -0,0 +1,9 @@
+---
+eleventyNavigation:
+    key: engineers-web-components
+    title: Web components
+    parent: engineers
+    order: 4
+    url: /engineers/web-components/
+permalink: false
+---

apps/pie-docs/test/snapshots/expected-routes.snapshot.json

@@ -90,6 +90,7 @@
     "engineers/getting-started/structure",
     "engineers/guidelines",
     "engineers/guidelines/browser-support",
+    "engineers/web-components",
     "foundations",
     "foundations/colour",
     "foundations/colour/tokens/alias/dark",