@justeattakeaway/pie-webc 0.8.5 → 0.8.6

package/docs/browser-support.md

@@ -0,0 +1,58 @@
+# Browser support
+
+Users have access to hundreds of versions of browsers, so instead of assessing them all individually, we've come up with a rating system that defines different levels of browser support and the testing requirements for each level. We've assigned the highest ratings to the browsers that are most commonly used by our customers.
+
+> This list needs to be reviewed often to stay up to date with the browsers chosen by our users.
+
+## Table of Contents
+
+- [Priority definitions](#priority-definitions)
+- [Browsers and their ratings](#browsers-and-their-ratings)
+    - [Desktop](#desktop)
+    - [Mobile](#mobile)
+- [Devices](#devices)
+
+
+## Priority definitions
+
+| Priority Level | Description |
+|----------------|-------------|
+| **A** – Fully Supported | - Testing is required<br/>- All content must be available<br/>- Layout must comply with the design, unless technical needs prevent this<br/>- All functionality must be available and work as required |
+| **B** – Mostly Supported | - Testing is required<br/>- User should be able to place an order or carry out the main function of the page<br/>- Layout doesn't have to be identical to the design, but should retain its functionality |
+| **C** – Not Supported | - Testing is not required<br/>- Browsers rated at B or C may have a better user experience than expected |
+
+> A good example of this would be users browsing using Opera. The reason we don't "Fully Support" this browser is simply down to user metrics, not the quality of the browser. We'd actually expect most functionality to work with no real issues, although we don't officially test in this browser.
+
+## Browsers and their ratings
+
+### Desktop
+
+| Browser | Grading |
+|---------|---------|
+| Chrome, last 3 versions (MacOS & Windows) | A |
+| Edge, last 3 versions (Windows) | A |
+| Firefox, last 3 versions (MacOS & Windows) | A |
+| Safari (MacOS), last 3 versions | A |
+| All other browsers & versions | C |
+
+### Mobile
+
+| Browser | Grading |
+|---------|---------|
+| Safari (iPhone), last 3 versions | A |
+| Safari (iPad), last 3 versions | A |
+| Chrome (Mobile), last 3 versions | A |
+| Samsung Internet, last 3 versions | B |
+| All other browsers & versions | C |
+
+## Devices
+
+To give an idea of what devices are worth testing on, these are the current recommended device types based on our analytics:
+
+| Device | Models |
+|--------|--------|
+| iPhone | Xs to latest (all variants such as SE Gen 2, Pro and Mini) |
+| iPad / iPad mini | iPad Air (Gen 3) to latest (all variants such as Mini & Pro) |
+| Samsung Galaxy | S21 FE to latest |
+| Samsung Galaxy Tab | S8 to latest |
+| Google Pixel | 5a, 7 |

package/docs/component-versions.md

@@ -0,0 +1,42 @@
+# Component Versions
+
+An important feature of web components is that they must be registered in the DOM before they can be used. This tells the browser what component to use when it tries to parse a particular selector such as `<pie-button>`.
+
+## Table of Contents
+- [How we register components](#how-we-register-components)
+- [Version mismatch issues](#version-mismatch-issues)
+- [The `v` attribute](#the-v-attribute)
+
+## How we register components
+PIE web **components will register themselves automatically** when they are imported into the DOM. An illustration of what this looks like under the hood is like this:
+
+```js
+class MyComponent extends HTMLElement {
+    // Logic omitted for simplicity
+}
+
+// Register the component as a custom element. This tells the browser to use this class when it encounters the <my-component> tag in the DOM.
+customElements.define('my-component', MyComponent);
+```
+We have some safeguarding in place to ensure this registration only happens once. If you import the same component multiple times (which can easily happen in a complex application), you may see a warning in development mode stating that the component has already been registered.
+
+Consumers of PIE web components will never have to perform this step themselves, as it is handled automatically by the component library.
+
+## Version mismatch issues
+
+One possible issue when using PIE web components is when multiple versions of the same component are registered in the DOM. This can happen if you have multiple versions of the component library installed, or if you import the same component multiple times in your application.
+This most often occurs in **micro-frontend applications**, where multiple teams are working on different parts of the application and may not be aware of each other's dependencies.
+
+When this happens, you may see a registration warning as previously mentioned. However our built-in safeguarding will not prevent you from potentially using a component version you were not expecting, as it depends which version was registered first. This could mean the component behaves differently than you expect, or even fails to render at all if the version is incompatible with your application.
+
+To avoid this issue, we recommend that teams working on different parts of the application coordinate on which versions of the component library they are using.
+
+## The `v` attribute
+
+All of our web components have a `v` attribute that indicates the version of the component. This can be particularly useful when debugging issues related to version mismatches. Simply inspect the component in the browser's developer tools and look for the `v` attribute to see which version of the component is being used.
+
+This attribute is automatically set by the component library during build. It should be compatible with server-side rendering, so it should be visible in the HTML returned from the server.
+
+```html
+<pie-button v="1.0.0"></pie-button>
+```

package/docs/css-setup.md

@@ -0,0 +1,117 @@
+# CSS setup
+[Source code](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css) | [NPM package](https://www.npmjs.com/package/@justeattakeaway/pie-css)
+
+In order for our components to render correctly, you will need to install our base CSS package, `@justeattakeaway/pie-css`. This package contains all the CSS variables and base styles required for our components to work correctly.
+Most of these CSS variables are what are known as [Design Tokens](https://pie.design/foundations/design-tokens/). They are a vital part of our design system, and are used to ensure consistency across all of our components.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [JS or Framework import (via bundler)](#js-or-framework-import-via-bundler)
+    - [React](#react)
+    - [Vue](#vue)
+    - [Nuxt](#nuxt)
+- [SCSS](#scss)
+- [CDN](#cdn)
+- [TypeScript usage](#typescript-usage)
+
+
+## Installation
+
+Simply install the package using your preferred package manager:
+
+**Using Yarn:**
+
+```bash
+yarn add @justeattakeaway/pie-css
+```
+
+**Using NPM:**
+
+```bash
+npm install @justeattakeaway/pie-css
+```
+
+## Usage
+
+How you include these styles will largely depend on the type of application you are building (and your own preference), but here are a few examples:
+
+### JS or Framework import (via bundler)
+```javascript
+// This is ensure the index.css file is included in your bundle
+import '@justeattakeaway/pie-css';
+```
+
+#### React
+In React (or NextJS), you could add the import to your `App.js` file:
+
+```javascript
+import '@justeattakeaway/pie-css';
+
+function App () {
+    return (
+        …
+    );
+}
+
+export default App;
+```
+
+#### Vue
+
+Similarly, in Vue 3, you will likely include it as part of your `/src/main.ts` file:
+
+```javascript
+import { createApp } from 'vue';
+import '@justeattakeaway/pie-css';
+import App from './App.vue';
+
+createApp(App).mount('#app');
+```
+
+#### Nuxt
+
+If you are using Nuxt, you can import the CSS into your `nuxt.config.js` file.
+
+```javascript
+// Nuxt v3
+export default defineNuxtConfig({
+    css: ['@justeattakeaway/pie-css'],
+    …
+});
+```
+
+```javascript
+export default {
+    css: [
+        '@justeattakeaway/pie-css',
+    ],
+    …
+}
+```
+
+### SCSS
+If you are using Sass, you could import the CSS file as part of your styles directly.
+
+```css
+@use 'node_modules/@justeattakeaway/pie-css/dist/index.css';
+```
+
+### CDN
+We also provide a CDN version of the CSS file, which you can include in your HTML file. However we would suggest avoiding this approach and favour package installation instead. If you do want to use the CDN, you must ensure you keep the version in the link up to date.
+
+```html
+<link rel="stylesheet" href="https://pie-design-system-cdn.production.jet-external.com/pie-css/v0.16.0/index.css">
+```
+
+### TypeScript usage
+If you are using TypeScript, you may need to add a declaration file to your project to avoid TypeScript errors when importing the CSS file. How you do this will depend on your project setup, but one way could be to create a types file (e.g. `src/types/pie-css.d.ts`) with the following content:
+
+```ts
+declare module '*.css';
+declare module '@justeattakeaway/pie-css';
+```
+---
+
+For more information on what styles are included in the CSS package, please refer to the [package readme](https://www.npmjs.com/package/@justeattakeaway/pie-css).

package/docs/css-variables.md

@@ -0,0 +1,49 @@
+# CSS variables
+
+In order to enable a degree of visual customisation, PIE web components expose a set of CSS variables.
+
+The main purpose of using CSS variables is to provide a straightforward mechanism for consumers to style and adapt PIE web components to their specific needs.
+
+It provides an abstraction layer that allows users to customise the appearance of components. Instead of requiring to resort to complex CSS selectors to override styles in the Shadow DOM, these variables can be used to control components visual aspects.
+
+## Usage benefits
+
+- **Easy customisation**: Consumers can easily modify the appearance of the components by simply redefining the CSS variables that were exposed. CSS variables offer a well-defined public API for styling, allowing controlled access to visual aspects of the component without risking breaking the internal structure.
+
+- **Readability and maintainability**: Descriptive variable names such as `--toast-provider-z-index` are easy to understand and maintain.
+
+- **Dynamic styling with JavaScript**: CSS variables can be easily manipulated via JavaScript. This creates possibilities for updating values depending on the application state or other specific conditions.
+
+## Examples
+
+CSS variables provided by the component can be overridden using standard CSS techniques.
+
+Inline style:
+
+```html
+ <pie-toast-provider style="--toast-provider-z-index: 7000;"></pie-toast-provider>
+```
+
+CSS selector:
+
+```html
+ <pie-toast-provider class="toast-override"></pie-toast-provider>
+```
+
+```css
+.toast-override {
+  --toast-provider-z-index: 7000;
+}
+```
+
+## How to start using CSS variables
+
+In the first place, it is necessary to verify if the component exposes any CSS variables. If that is the case, the component documentation will provide a section with a list of available CSS variables.
+
+Alternatively, the "Styles" tab in Dev Tools can show the component CSS variables that are available. These should be listed under the `:host` selector.
+
+```css
+:host {
+  --toast-provider-z-index: var(--dt-z-index-toast);
+}
+```

package/docs/customising-components.md

@@ -0,0 +1,117 @@
+# Customising components
+Sometimes there is a need to customise a component's styling more than can be achieved with props or CSS variable overrides. Whilst these situations are uncommon, we recognise that components have to be flexible enough to allow people to do this.
+
+> If a component provides CSS parts to override, you will find them in the component readme file or overview page in Storybook.
+
+**Warning!** Customising components is not a recommended pattern. It should be used sparingly, and is always worth discussing with the Design System team first. When you customise the component styles, **you must take responsibility for ensuring future updates to the component do not regress your customised styles**.
+
+## Table of Contents
+- [CSS Parts](#css-parts)
+- [Writing custom styles](#writing-custom-styles)
+  - [Example of risky CSS](#example-of-risky-css)
+  - [The problem](#the-problem)
+  - [The solution: all: initial](#the-solution-all-initial)
+- [Warning](#warning)
+
+## CSS Parts
+CSS Parts are a way to expose areas of a component's template for consumers to apply their own CSS to.
+
+An example of this is our Tag component. As you can see, we can fully customise how the component looks by writing our own CSS to be used in the `::part(body)` and `::part(icon)`.
+
+Not all components provide parts. If you feel your use-case requires them, please reach out to the team to discuss.
+
+## Writing custom styles
+One risk with writing your own styles is that, if you are not careful, you might write some CSS that the base component styles could override in future updates.
+
+### Example of risky CSS
+Let's imagine our component `<example-component>` has the following structure:
+
+```html
+<div class="c-exampleComponent">
+  <span part="primary" class="c-exampleComponent__box c-exampleComponent__box--primary">
+    <slot name="primary"></slot>
+  </span>
+  <span part="secondary" class="c-exampleComponent__box c-exampleComponent__box--secondary">
+    <slot name="secondary"></slot>
+  </span>
+</div>
+```
+
+And this is our CSS:
+
+```css
+.c-exampleComponent {
+  background-color: lightgreen;
+  padding: 1.5rem;
+  /* Other styles skipped */
+}
+
+.c-exampleComponent__box {
+  padding: 1rem;
+  border-radius: 4px;
+  font-family: sans-serif;
+  /* Other styles skipped */
+}
+
+.c-exampleComponent__box--primary {
+  background-color: coral;
+  /* Other styles skipped */
+}
+
+.c-exampleComponent__box--secondary {
+  background-color: lightblue;
+  /* Other styles skipped */
+}
+```
+
+We are happy with the default padding around the primary box. It matches our design requirements. However, we need more padding on the secondary box. So we use the exposed CSS part to modify it:
+
+```css
+example-component::part(secondary) {
+  padding: 2rem;
+}
+```
+
+Now our secondary box has larger padding. Excellent!
+
+### The problem
+There is a risk with our strategy. Let's imagine that six months later, our team releases a new version of the component library. We've decided to add a border to all boxes.
+
+The base CSS for `.c-exampleComponent__box` is now:
+
+```css
+.c-exampleComponent__box {
+  padding: 1rem;
+  border-radius: 4px;
+  font-family: sans-serif;
+  border: 3px solid rgba(0,0,0,0.5); /* <-- New style! */
+}
+```
+
+Because our custom CSS for `::part(secondary)` only overrides the padding, it inherits the new border property from the base styles. This was not part of our original design and is an unintended regression.
+
+### The solution: `all: initial`
+To protect your custom styles from being affected by future changes to the component's base styles, you should take full control of the part's styling.
+
+You can do this by using `all: initial` to reset all of the component's base styles on that part. This creates a clean slate, ensuring that only the CSS you explicitly define is applied.
+
+Here is the safe way to write the custom styles for our secondary part:
+
+```css
+example-component::part(secondary) {
+  /* 1. Reset all base styles from the component */
+  all: initial;
+
+  /* 2. Now, re-apply ALL styles needed for your design */
+  background-color: lightblue;
+  padding: 2rem;
+  border-radius: 4px;
+  font-family: sans-serif;
+}
+```
+
+By doing this, you are no longer inheriting any styles from `.c-exampleComponent__box`. When the component library is updated with the new border, your custom-styled part will be completely unaffected, looking exactly as you designed it.
+
+## Warning
+
+Remember that when you use `all: initial`, you lose **all** base styles from the component. You are responsible for re-applying every style needed. This approach is safer for long-term maintenance but requires more upfront work.

package/docs/events.md

@@ -0,0 +1,116 @@
+# Events
+Some of our web components emit custom events that can be listened to by the application. These events are used to communicate changes in the component's state or to notify the application of user interactions.
+We use events because they are a browser-native way to communicate between components and applications. They allow for a decoupled architecture, where components can emit events without needing to know who is listening to them.
+This makes it easier to build modular and reusable components that can be used in different contexts.
+
+> If a component emits its own events, they will be documented in the components documentation - look for the "Events" section in the component's README or Overview page in Storybook.
+
+## Table of Contents
+
+- [Naming convention](#naming-convention)
+- [Listening to custom events](#listening-to-custom-events)
+    - [Vanilla JS](#custom-events-in-vanilla-js)
+    - [Vue](#custom-events-in-vue)
+    - [React](#custom-events-in-react)
+- [Listening to native events](#listening-to-native-events)
+    - [Vanilla JS](#native-events-in-vanilla-js)
+    - [Vue](#native-events-in-vue)
+    - [React](#native-events-in-react)
+
+## Naming convention
+The events dispatched by PIE web components are named using `pie-<component-name>-<event-name>`. For example, `pie-modal-leading-action-click` is dispatched when the leading action button in a modal is clicked.
+We follow this naming convention to ensure that events are unique and easily identifiable.
+
+> Sometimes components can simply emit native events, such as `input` or `change`. In these cases, there is no need to create a custom event. The native event will bubble up from the component and can be listened to like any other event.
+
+## Listening to custom events
+Listening to custom events is similar to listening to native events and can be achieved in a number of ways depending on the application framework you are using. Below are some examples of how to listen to events in different frameworks.
+
+### Custom events in Vanilla JS
+```js
+const modal = document.querySelector('pie-modal');
+modal.addEventListener('pie-modal-leading-action-click', (e) => {
+    console.log('Leading action clicked!', e);
+});
+```
+### Custom events in Vue
+```html
+<template>
+    <pie-modal @pie-modal-leading-action-click="handleClick"></pie-modal>
+</template>
+<script>
+export default {
+    methods: {
+        handleClick(event) {
+            console.log('Leading action clicked!', event);
+        }
+    }
+}
+</script>
+```
+
+### Custom events in React
+
+React is a little different to other frameworks, because a common pattern is to pass callback functions as props rather than using event listeners.
+To enable this, we provide a React-specific wrapper for each component that allows engineers to pass callback functions as props.
+The naming convention for these props is `on<EventName>` (camel case). For example, `onPieModalLeadingActionClick` is the prop that can be used to listen to the `pie-modal-leading-action-click` event.
+
+> It is vital that you import the component from the `react` entrypoint.
+
+```jsx
+// Please note the import path for React components
+import { PieModal } from '@justeattakeaway/pie-webc/react/modal.js';
+
+function App() {
+    const handleClick = (event) => {
+        console.log('Leading action clicked!', event);
+    };
+
+    return (
+        <PieModal onPieModalLeadingActionClick={handleClick}></PieModal>
+    );
+}
+```
+## Listening to native events
+You can still attach event listeners to native events that are emitted by the component. These events are not prefixed with `pie-` and can be listened to like any other native event on an HTML element.
+
+### Native events in Vanilla JS
+
+```js
+const divider = document.querySelector('pie-divider');
+divider.addEventListener('click', (e) => {
+    console.log('Divider clicked!', e);
+});
+```
+
+### Native events in Vue
+
+```html
+<template>
+    <pie-divider @click="handleClick"></pie-divider>
+</template>
+<script>
+export default {
+    methods: {
+        handleClick(event) {
+            console.log('Divider clicked!', event);
+        }
+    }
+}
+</script>
+```
+
+### Native events in React
+```jsx
+// Please note the import path for React components
+import { PieDivider } from '@justeattakeaway/pie-webc/react/divider.js';
+function App() {
+    const handleClick = (event) => {
+        console.log('Divider clicked!', event);
+    };
+
+    return (
+        <PieDivider onClick={handleClick}></PieDivider>
+    );
+}
+```

package/docs/framework-integration-guides/nextjs-14.md

@@ -0,0 +1,74 @@
+# Next.js 14
+
+This guide will show you how to set up the PIE Web Components in a Next.js 14 applications.
+
+> This guide assumes you have first followed the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs), [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) guides.
+> Please make sure to follow them before continuing with this guide.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Next.js config](#nextjs-config)
+- [Usage](#usage)
+
+
+## Dependencies
+The first step is to install some React and Next.js specific dependencies:
+
+**Using Yarn:**
+
+```bash
+yarn add @lit-labs/nextjs @lit/react
+```
+
+**Using NPM:**
+
+```bash
+npm install @lit-labs/nextjs @lit/react
+```
+
+## Next.js config
+
+We need to update our `next.config.js` file to enable server-side rendering (SSR).
+
+Example minimal config file:
+
+```js
+// Example - ./next.config.js
+const withLitSSR = require('@lit-labs/nextjs')();
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    reactStrictMode: true,
+    swcMinify: true,
+}
+
+module.exports = withLitSSR(nextConfig);
+```
+
+## Usage
+
+> If you are using the app router structure, please ensure you add `use client` to the top of the files that directly import the PIE components. This does **not** prevent SSR, it just means that PIE components cannot be used directly in React server-components. These client components can then be imported into RSCs.
+
+For React-based applications, there is a `/react/` entry point in both `@justeattakeaway/pie-webc` and `@justeattakeaway/pie-icons-webc` as shown in the example code below:
+
+```jsx
+"use client"
+
+import { PieButton } from "@justeattakeaway/pie-webc/react/button.js";
+import { PieLink } from "@justeattakeaway/pie-webc/react/link.js";
+import { IconCamera } from "@justeattakeaway/pie-icons-webc/dist/react/IconCamera";
+
+export default function SomeComponent() {
+    return (
+        <div>
+            <PieButton size="small-productive" iconPlacement="leading">
+                <IconCamera slot="icon"></IconCamera>
+                Camera Button
+            </PieButton>
+        </div>
+    );
+}
+```
+
+You should now be able to use any components you need in your Next.js application!

package/docs/framework-integration-guides/no-framework.md

@@ -0,0 +1,49 @@
+# No framework
+
+This guide will show you how to set up the PIE Web Components in a web application without any specific framework.
+
+> This guide assumes you have first followed the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs), [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) guides.
+> Please make sure to follow them before continuing with this guide.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Usage](#usage)
+
+## Dependencies
+Please refer to the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) guide for the dependencies required to use PIE Web Components in your application.
+
+## Usage
+Please ensure that you import the components **without any destructuring**. Simply import the package.
+
+```ts
+import '@justeattakeaway/pie-webc/components/button.js';
+import '@justeattakeaway/pie-webc/components/icon-button.js';
+import '@justeattakeaway/pie-icons-webc/dist/IconClose.js';
+import '@justeattakeaway/pie-css';
+
+document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
+    <div class="card">
+        <pie-button id="counter" type="button">count is 0</pie-button>
+        <pie-icon-button>
+            <icon-close></icon-close>
+        </pie-icon-button>
+    </div>
+`;
+
+function setupCounter(button: HTMLElement) {
+    let counter = 0;
+    const updateText = () => {
+        button.textContent = `count is ${counter}`;
+    };
+    button.addEventListener('click', () => {
+        counter++;
+        updateText();
+    });
+    updateText();
+}
+
+setupCounter(document.querySelector<HTMLElement>('#counter')!);
+```
+
+You should now be able to use any components you need in your application!

package/docs/framework-integration-guides/nuxt-3.md

@@ -0,0 +1,119 @@
+# Nuxt 3
+
+This guide will show you how to set up the PIE Web Components in a Nuxt 3 application.
+
+> This guide assumes you have first followed the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs), [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) guides.
+> Please make sure to follow them before continuing with this guide.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Nuxt config](#nuxt-config)
+- [Usage](#usage)
+
+
+## Dependencies
+The first step is to install some React and Next.js specific dependencies:
+
+**Using Yarn:**
+
+```bash
+yarn add nuxt-ssr-lit
+```
+
+**Using NPM:**
+
+```bash
+npm install nuxt-ssr-lit
+```
+
+## Nuxt config
+
+To get our components working, ensure you are applying the following rules to your `nuxt.config.ts` file:
+
+```js
+export default defineNuxtConfig({
+    ssr: true,
+
+    nitro: {
+        moduleSideEffects: [
+            '@justeattakeaway/pie-icons-webc',
+            '@justeattakeaway/pie-webc',
+        ],
+    },
+
+    modules: [['nuxt-ssr-lit', { litElementPrefix: ['pie-', 'icon-'] }]],
+
+    imports: {
+        transform: {
+            exclude: [/\bpie-\b/, /\bicon-\b/],
+        },
+    },
+
+    css: ['@justeattakeaway/pie-css'],
+    devtools: { enabled: true },
+
+    devServer: {
+        port: 3002,
+    },
+
+    compatibilityDate: '2024-07-23',
+});
+```
+
+### Nuxt Configuration Breakdown
+
+#### 1. **Server-Side Rendering**
+- **`ssr: true`**
+  Enables **Server-Side Rendering (SSR)** for improved SEO and faster initial page loads by rendering pages on the server.
+
+#### 2. **Nitro Configuration**
+- **`moduleSideEffects`**
+    Includes the following modules during the build to ensure side effects like custom element registration:
+    - `@justeattakeaway/pie-icons-webc`
+    - `@justeattakeaway/pie-webc`
+
+#### 3. **Modules**
+- Adds the **`nuxt-ssr-lit`** module to enable SSR compatibility for Lit web components.
+- **`litElementPrefix`** specifies the prefixes for custom elements to be treated as Lit elements:
+    - `pie-`
+    - `icon-`
+
+#### 4. **Imports**
+- **`imports.transform.exclude`**
+    Prevents Nuxt from automatically transforming imports matching these patterns:
+    - `pie-`
+    - `icon-`
+
+#### 5. **Global CSS**
+- Includes global styles from the `@justeattakeaway/pie-css` package for styling custom components.
+
+#### 6. **Compatibility Date**
+- **`compatibilityDate: '2024-07-23'`**
+    Ensures behaviour aligns with Nuxt's functionality as of the specified date, preventing breaking changes introduced after this date.
+
+
+## Usage
+
+It is recommended to import all components from [@justeattakeaway/pie-webc](https://www.npmjs.com/package/@justeattakeaway/pie-webc).
+
+In your components, you should be able to render components like so:
+
+```html
+<script setup>
+// No need to destructure any imports - just directly import the js file
+import '@justeattakeaway/pie-webc/components/button.js';
+import '@justeattakeaway/pie-icons-webc/dist/IconCamera.js';
+</script>
+
+<template>
+    <div>
+        <pie-button size="small-productive" iconPlacement="leading">
+        <icon-camera slot="icon"></icon-camera>
+        hello, world
+        </pie-button>
+    </div>
+</template>
+```
+
+You should now be able to use any components you need in your Nuxt application!

package/docs/framework-integration-guides/react-19.md

@@ -0,0 +1,62 @@
+# React 19
+
+This guide will show you how to set up the PIE Web Components in a React 19 application.
+
+> This guide assumes you have first followed the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs), [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) guides.
+> Please make sure to follow them before continuing with this guide.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Usage](#usage)
+
+## Dependencies
+The first step is to install the React specific dependency:
+
+**Using Yarn:**
+
+```bash
+yarn add @lit/react
+```
+
+**Using NPM:**
+
+```bash
+npm install @lit/react
+```
+
+## Usage
+
+For React-based applications, there is a `/react/` entry point in both `@justeattakeaway/pie-webc` and `@justeattakeaway/pie-icons-webc` as shown in the example code below:
+
+```tsx
+import { useState } from 'react';
+import { PieButton } from '@justeattakeaway/pie-webc/react/button.js';
+import { PieIconButton } from '@justeattakeaway/pie-webc/react/icon-button.js';
+import { IconClose } from '@justeattakeaway/pie-icons-webc/dist/react/IconClose.js';
+
+import './App.css';
+import '@justeattakeaway/pie-css';
+
+function App() {
+    const [count, setCount] = useState(0);
+
+    return (
+        <>
+        <div className="card">
+            <PieButton onClick={() => setCount((count) => count + 1)}>
+            count is {count}
+            </PieButton>
+
+            <PieIconButton>
+                <IconClose></IconClose>
+            </PieIconButton>
+        </div>
+        </>
+    );
+}
+
+export default App;
+```
+
+You should now be able to use any components you need in your React application!

package/docs/framework-integration-guides/vue-3.md

@@ -0,0 +1,44 @@
+# Vue 3
+
+This guide will show you how to set up the PIE Web Components in a Vue 3 application.
+
+> This guide assumes you have first followed the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs), [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) guides.
+> Please make sure to follow them before continuing with this guide.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Usage](#usage)
+
+## Dependencies
+There are no vue-specific dependencies required. Please refer to the [Getting started](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) guide for the dependencies required to use PIE Web Components in your application.
+
+## Usage
+Please ensure that you import the components **without any destructuring**. Simply import the package.
+
+```html
+<script setup lang="ts">
+import { ref } from 'vue';
+import '@justeattakeaway/pie-webc/components/button.js';
+import '@justeattakeaway/pie-webc/components/icon-button.js';
+import '@justeattakeaway/pie-icons-webc/dist/IconClose.js';
+
+import '@justeattakeaway/pie-css';
+</script>
+
+<template>
+    <div class="card">
+        <pie-button @click="count++"> count is {{ count }} </pie-button>
+
+        <pie-icon-button>
+            <icon-close></icon-close>
+        </pie-icon-button>
+    </div>
+</template>
+
+<script lang="ts">
+const count = ref(0);
+</script>
+```
+
+You should now be able to use any components you need in your Vue application!

package/docs/getting-started.md

@@ -0,0 +1,36 @@
+# PIE Web Components
+[Source code](https://github.com/justeattakeaway/pie) | [Design Documentation](https://pie.design/)
+
+PIE Web Components is the web variant of the Just Eat Takeaway.com (JET) Design System, PIE. It is built using native web components to provide a consistent, accessible, and reusable set of components for building UIs across different products and applications.
+
+## `@justeattakeaway/pie-webc`
+
+`@justeattakeaway/pie-webc` is the web implementation of [JET's PIE Design system](https://pie.design/), built using [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Using Web Components allows us to build our components once and use them across all of our web UIs, regardless of the framework they have been built with. Our source code is open source, and can be found on [Github](https://github.com/justeattakeaway/pie).
+
+### Getting Started
+
+Setting up our web components differs slightly depending on your framework. However, regardless of your tech stack, the **first step** is to install our core packages:
+
+- The core component library: [@justeattakeaway/pie-webc](https://www.npmjs.com/package/@justeattakeaway/pie-webc)
+- Base styles used by the components: [@justeattakeaway/pie-css](https://www.npmjs.com/package/@justeattakeaway/pie-css)
+- Icons used by some of the components: [@justeattakeaway/pie-icons-webc](https://www.npmjs.com/package/@justeattakeaway/pie-icons-webc)
+
+> 💡 While components are also available as individual packages, we recommend using `@justeattakeaway/pie-webc` as the **single entry point**. This approach is the easiest way to get started with and ensures you stay up to date.
+
+**Using Yarn:**
+
+```bash
+yarn add @justeattakeaway/pie-webc @justeattakeaway/pie-css @justeattakeaway/pie-icons-webc
+```
+
+**Using NPM:**
+
+```bash
+npm install @justeattakeaway/pie-webc @justeattakeaway/pie-css @justeattakeaway/pie-icons-webc
+```
+
+From here, you will need to set up Typography and base CSS styles. Please read the [Typography](https://webc.pie.design/?path=/docs/introduction-typography--docs) and [CSS setup](https://webc.pie.design/?path=/docs/introduction-css-setup--docs) pages for more information.
+
+### What components can I use?
+
+We keep an up to date list of component statuses on the PIE Storybook. Anything in `Beta` or `Stable` is ready to use in your project!

package/docs/typescript-usage.md

@@ -0,0 +1,113 @@
+# TypeScript usage
+Using TypeScript with our components is straightforward. Each component package exports its types, which can be imported and used in your application where needed.
+Below are examples of how to use the types in different frameworks and are all fairly similar.
+
+Our published components contain `index.d.ts` and `react.d.ts` files that contain the types for the component and its props. These files are automatically generated during the build process and are used by the TypeScript compiler to provide type checking and intellisense in your IDE. You should not need to import or interact with these files. They can be viewed in the `dist` directory of the component packages.
+
+> Note that the examples below are using the `PieSelect` component, but the same principles apply to all components in the PIE web components library.
+> Also please bear in mind that these are minimal examples to demonstrate how to use the types, and you will likely need to adapt them to your specific use case. Simply reusing the example code in your application is unlikely to work as-is.
+
+---
+
+### React
+Import any types you want to use from the component file. Please note the **react** entry point in the path.
+It is important to specify the `type` keyword when importing types as this will ensure the TypeScript compiler will not try to compile the types into JavaScript code.
+
+```tsx
+import { PieSelect, type SelectProps } from "@justeattakeaway/pie-webc/react/select.js";
+
+export default function Select() {
+    const options: SelectProps['options'] = [
+        {
+            tag: 'optgroup',
+            label: 'Animals',
+            options: [
+                {
+                    tag: 'option',
+                    text: 'Cat',
+                    value: 'cat',
+                },
+                {
+                    tag: 'option',
+                    text: 'Dog',
+                    value: 'dog',
+                },
+            ],
+        },
+    ];
+
+    return (
+        <PieSelect options={options} />
+    );
+}
+```
+
+### Vue
+
+```html
+<template>
+    <pie-select :options="options"></pie-select>
+</template>
+
+<script setup lang="ts">
+import '@justeattakeaway/pie-webc/components/select.js';
+import type { SelectProps } from '@justeattakeaway/pie-webc/components/select.js';
+
+const options: SelectProps['options'] = [
+    {
+        tag: 'optgroup',
+        label: 'Animal',
+        options: [
+            {
+                tag: 'option',
+                text: 'Cat',
+                value: 'cat',
+            },
+            {
+                tag: 'option',
+                text: 'Dog',
+                value: 'dog',
+            },
+        ],
+    },
+];
+</script>
+```
+
+### Plain TypeScript
+
+```html
+<pie-select id="mySelect"></pie-select>
+
+<script type="module" src="./main.ts"></script>
+```
+
+```ts
+// main.ts
+import '@justeattakeaway/pie-webc/components/select.js';
+import type { SelectProps, PieSelect } from '@justeattakeaway/pie-webc/components/select.js';
+
+const options: SelectProps['options'] = [
+    {
+        tag: 'optgroup',
+        label: 'Animal',
+        options: [
+        {
+            tag: 'option',
+            text: 'Cat',
+            value: 'cat',
+        },
+        {
+            tag: 'option',
+            text: 'Dog',
+            value: 'dog',
+        },
+        ],
+    },
+];
+
+// Using type casting here just to specify the element cannot be null. This is not always a good practice.
+const pieSelect = document.querySelector('pie-select') as PieSelect;
+
+pieSelect.options = options;
+```

package/docs/typography.md

@@ -0,0 +1,120 @@
+# Typography
+In order for our components to look and feel like the rest of the Just Eat Takeaway.com family, we need to ensure that we are using the correct typography and styles. This document will cover how to set up typography in your application.
+
+## Table of Contents
+
+- [The JETSansDigital Variable Font](#the-jetsansdigital-variable-font)
+- [Font Loading](#font-loading)
+- [Italic Font Usage](#italic-font-usage)
+- [Font Optimisation (subsetting)](#font-optimisation-subsetting)
+
+## The JETSansDigital Variable Font
+
+`JETSansDigital` is a variable font (VF) containing all font weights and styles in a single file.
+
+The font is available in two versions via our CDN:
+
+| Version      | URL                                                                                                                                                      | Recommended Use                                                                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Base**     | [JETSansDigital-VF-opt.woff2](https://pie-design-system-cdn.production.jet-external.com/fonts/JETSansDigital-VF-opt.woff2)                               | Default choice. Includes Latin characters and supports common European languages (English, French, Spanish, German, etc.).                         |
+| **Extended** | [JETSansDigital-VF-optimised-extended.woff2](https://pie-design-system-cdn.production.jet-external.com/fonts/JETSansDigital-VF-optimised-extended.woff2) | Use when your app supports additional languages such as Hebrew, Bulgarian, or other Cyrillic-based languages. This version is larger in file size. |
+
+## Font Loading
+
+Add the following code into the `<head>` of your application:
+
+```html
+<link rel="preload" href="https://pie-design-system-cdn.production.jet-external.com/fonts/JETSansDigital-VF-opt.woff2" as="font" type="font/woff2" crossorigin>
+<style>
+@font-face {
+    font-family: JETSansDigital;
+    src: url('https://pie-design-system-cdn.production.jet-external.com/fonts/JETSansDigital-VF-opt.woff2') format("woff2");
+    font-weight: 100 1000;
+    font-stretch: 25% 151%;
+    font-style: oblique 0deg 20deg;
+    font-display: swap;
+}
+body {
+    font-feature-settings: "tnum"; /* Enable tabular numbers */
+}
+</style>
+```
+
+- The first link tag will load in the `JETSansDigital` font file. The `rel=preload` attribute tells the browser to download and cache it as soon as possible.
+
+- The `@font-face` declaration is then to apply the `JETSansDigital` font as soon as it's available (and as it's inline in the head of the page, it won't wait for the rest of the CSS to be parsed until it renders the font).
+
+```shell
+# If your application needs extended language support, replace the font URL with the extended version.
+https://pie-design-system-cdn.production.jet-external.com/fonts/JETSansDigital-VF-optimised-extended.woff2
+```
+
+## Italic Font Usage
+
+Safari has a known issue with variable fonts that use the `oblique` angle range syntax in `@font-face` declarations. When applying `font-style: italic`, Safari doesn't properly apply the slant axis and may create a synthetic italic that appears incorrectly rendered or "double bold."
+
+To fix this, you must include `font-variation-settings: "slnt" -20` alongside `font-style: italic` when styling it:
+
+```css
+.italic-text {
+    font-style: italic;
+    font-variation-settings: "slnt" -20;
+}
+```
+
+## Font Optimisation (subsetting)
+
+The standard fontset comes with a huge number of glyphs and layout features that aren't required for use on the web. Therefore we optimise this fontset using a process called font-subsetting. Subsetting is the process of removing parts of the base fontset, to leave only the glyphs and features that you require.
+
+### How to subset a font
+
+To subset a base font like the one we use, you will need to use a command line tool called `pyftsubset` which is available as part of the fonttools library. For more information on installing `pyftsubset`, see this blog post which explains how to do that and covers any associated dependencies you'll also need (such as `pip`).
+
+Once you have `pyftsubset` installed you can optimise your font!
+
+For `JETSansDigital`, we subset `JETSansDigital-VF.ttf` with the following rules:
+
+```shell
+# JETSansDigital-VF
+pyftsubset "JETSansDigital-VF.ttf" --output-file="JETSansDigital-VF-opt.woff2" --flavor=woff2 --layout-features=ccmp,locl,mark,mkmk,kern,dnom,numr,frac,tnum --unicodes=U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD
+```
+
+and for our extended subset, we use the following extended unicode settings:
+
+```shell
+# JETSansDigital-VF-optimised-extended
+pyftsubset "JETSansDigital-VF.ttf" --output-file="JETSansDigital-VF-optimised-extended.woff2" --flavor=woff2 --layout-features=ccmp,locl,mark,mkmk,kern,dnom,numr,frac,tnum --unicodes=U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD,U+0100-017F,U+0400-04FF,U+0401,U+0451,U+0404,U+0454,U+0406,U+0456,U+0407,U+0457,U+040D,U+045D,U+040E,U+045E,U+0490,U+0491,U+0590-05FF
+```
+
+### Breaking the command down
+
+So what do the above commands actually do and what does each setting mean?
+
+Let's break it down step-by-step:
+
+- `pyftsubset "JETSansDigital-VF.ttf" --output-file="JETSansDigital-VF-opt.woff2"`
+
+This runs the pyftsubset tool on the `JETSansDigital-VF.ttf` file and outputs the results file as `JETSansDigital-VF-opt.woff2`.
+
+- `--flavor=woff2`
+
+Optimise the file in `woff2` format (can be set to `woff` to output the file as a woff, as well as needing to change the `--output-file` value).
+
+- `--layout-features=ccmp,locl,mark,mkmk,kern,dnom,numr,frac,tnum`
+
+Keeps the specified layout features as part of the sub-setted font. For more details on each of these layout features, check out the following resources:
+
+- [`ccmp`](https://docs.microsoft.com/en-us/typography/opentype/spec/features_ae#ccmp) – This feature permits composition/decompostion of glyphs.
+- [`locl`](https://www.preusstype.com/techdata/otf_locl.php) – Allow localised variants of specific letters/glyphs.
+- [`mark`](https://docs.microsoft.com/en-us/typography/opentype/spec/features_ko#tag-mark) – Positions mark glyphs with respect to base glyphs.
+- [`mkmk`](https://docs.microsoft.com/en-us/typography/opentype/spec/features_ko#tag-mkmk) – Positions mark glyphs with respect to other marks.
+- [`kern`](https://www.preusstype.com/techdata/otf_kern.php) – Adjusts the amount of space between glyphs, generally to provide optically consistent spacing between glyphs.
+- [`dnom`](https://www.preusstype.com/techdata/otf_dnom.php) – Short for denominators, this replaces selected figures which follow a slash with denominator figures.
+- [`numr`](https://www.preusstype.com/techdata/otf_numr.php) – Short for numerators, this replaces selected figures which precede a slash with numerator figures, and replaces the typographic slash with the fraction slash.
+- [`frac`](https://www.preusstype.com/techdata/otf_frac.php) – Short for fractions, this replaces figures separated by a slash with 'common' (diagonal) fractions.
+- [`tnum`](https://www.fonts.com/content/learning/fontology/level-3/numbers/proportional-vs-tabular-figures) – Short for tabular figures, this deals with number spacing.
+
+
+- `--unicodes=U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD`
+
+Specifies which characters to include as part of our optimised set. This character set is the same as those specified by Google font sets – more information on which [can be found in this blog post](https://markoskon.com/creating-font-subsets/#characters).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-webc",
   "description": "Component bundle containing all PIE web components",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/justeattakeaway/pie",
@@ -11,7 +11,8 @@
   "type": "module",
   "files": [
     "**/*.js",
-    "**/*.d.ts"
+    "**/*.d.ts",
+    "docs/**/*.md"
   ],
   "exports": {
     "./components/assistive-text.js": {
@@ -811,36 +812,36 @@
     "chalk": "5.3.0"
   },
   "dependencies": {
-    "@justeattakeaway/pie-assistive-text": "0.11.15",
-    "@justeattakeaway/pie-avatar": "0.4.16",
-    "@justeattakeaway/pie-breadcrumb": "0.7.18",
-    "@justeattakeaway/pie-button": "1.12.3",
-    "@justeattakeaway/pie-card": "0.26.12",
-    "@justeattakeaway/pie-checkbox": "1.0.8",
-    "@justeattakeaway/pie-checkbox-group": "1.0.8",
-    "@justeattakeaway/pie-chip": "0.15.13",
-    "@justeattakeaway/pie-cookie-banner": "1.7.9",
-    "@justeattakeaway/pie-data-table": "0.3.3",
-    "@justeattakeaway/pie-divider": "1.5.10",
-    "@justeattakeaway/pie-form-label": "0.18.11",
-    "@justeattakeaway/pie-icon-button": "2.6.4",
-    "@justeattakeaway/pie-link": "1.3.13",
-    "@justeattakeaway/pie-list": "0.0.15",
-    "@justeattakeaway/pie-lottie-player": "0.3.5",
-    "@justeattakeaway/pie-modal": "1.25.1",
-    "@justeattakeaway/pie-notification": "0.21.9",
-    "@justeattakeaway/pie-radio": "1.1.0",
-    "@justeattakeaway/pie-radio-group": "1.0.8",
-    "@justeattakeaway/pie-select": "0.8.16",
-    "@justeattakeaway/pie-spinner": "1.4.3",
-    "@justeattakeaway/pie-switch": "2.3.15",
-    "@justeattakeaway/pie-tabs": "0.1.11",
-    "@justeattakeaway/pie-tag": "0.22.7",
-    "@justeattakeaway/pie-text-input": "0.29.16",
-    "@justeattakeaway/pie-textarea": "0.17.15",
-    "@justeattakeaway/pie-thumbnail": "0.8.16",
-    "@justeattakeaway/pie-toast": "0.12.24",
-    "@justeattakeaway/pie-toast-provider": "0.7.25"
+    "@justeattakeaway/pie-assistive-text": "0.11.16",
+    "@justeattakeaway/pie-avatar": "0.4.17",
+    "@justeattakeaway/pie-breadcrumb": "0.7.19",
+    "@justeattakeaway/pie-button": "1.12.4",
+    "@justeattakeaway/pie-card": "0.26.13",
+    "@justeattakeaway/pie-checkbox": "1.0.9",
+    "@justeattakeaway/pie-checkbox-group": "1.0.9",
+    "@justeattakeaway/pie-chip": "0.15.14",
+    "@justeattakeaway/pie-cookie-banner": "1.7.10",
+    "@justeattakeaway/pie-data-table": "0.3.4",
+    "@justeattakeaway/pie-divider": "1.5.11",
+    "@justeattakeaway/pie-form-label": "0.18.12",
+    "@justeattakeaway/pie-icon-button": "2.6.5",
+    "@justeattakeaway/pie-link": "1.3.14",
+    "@justeattakeaway/pie-list": "0.0.16",
+    "@justeattakeaway/pie-lottie-player": "0.3.6",
+    "@justeattakeaway/pie-modal": "1.25.2",
+    "@justeattakeaway/pie-notification": "0.21.10",
+    "@justeattakeaway/pie-radio": "1.1.1",
+    "@justeattakeaway/pie-radio-group": "1.0.9",
+    "@justeattakeaway/pie-select": "0.8.17",
+    "@justeattakeaway/pie-spinner": "1.4.4",
+    "@justeattakeaway/pie-switch": "2.3.16",
+    "@justeattakeaway/pie-tabs": "0.1.12",
+    "@justeattakeaway/pie-tag": "0.22.8",
+    "@justeattakeaway/pie-text-input": "0.29.17",
+    "@justeattakeaway/pie-textarea": "0.17.16",
+    "@justeattakeaway/pie-thumbnail": "0.8.17",
+    "@justeattakeaway/pie-toast": "0.12.25",
+    "@justeattakeaway/pie-toast-provider": "0.7.26"
   },
   "volta": {
     "extends": "../../../package.json"