Merge branch 'main' into dsw-2475-pie-toast-code-docs

justeattakeaway · Nov 15, 2024 · 85d26f6 · 85d26f6
2 parents 50e68b3 + a938db1
commit 85d26f6
Show file tree

Hide file tree

Showing 18 changed files with 283 additions and 35 deletions.
diff --git a/.changeset/empty-poets-carry.md b/.changeset/empty-poets-carry.md
diff --git a/.changeset/neat-ads-reflect.md b/.changeset/neat-ads-reflect.md
@@ -0,0 +1,5 @@
+---
+"pie-docs": minor
+---
+
+[Added] - NextJS 14 integration guide for web components
diff --git a/.changeset/neat-timers-compare.md b/.changeset/neat-timers-compare.md
diff --git a/.changeset/slimy-socks-switch.md b/.changeset/slimy-socks-switch.md
@@ -0,0 +1,5 @@
+---
+"pie-docs": minor
+---
+
+[Added] - Nuxt3 integration guide to docs site
diff --git a/.changeset/spotty-numbers-type.md b/.changeset/spotty-numbers-type.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.71.0
+
+### Minor Changes
+
+- [Removed] - @babel/traverse resolution to fix issue with pie-icons-webc build ([#2034](https://github.com/justeattakeaway/pie/pull/2034)) by [@siggerzz](https://github.com/siggerzz)
+
 ## 2.70.0
 
 ### Minor Changes

diff --git a/apps/pie-docs/CHANGELOG.md b/apps/pie-docs/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.18.0
+
+### Minor Changes
+
+- [Added] - Refactor to use @justeattakeaway/pie-monorepo-utils to import component statuses ([#2034](https://github.com/justeattakeaway/pie/pull/2034)) by [@siggerzz](https://github.com/siggerzz)
+
 ## 4.17.0
 
 ### Minor Changes

diff --git a/apps/pie-docs/package.json b/apps/pie-docs/package.json
@@ -2,7 +2,7 @@
   "name": "pie-docs",
   "private": true,
   "description": "Documentation website for the PIE design system",
-  "version": "4.17.0",
+  "version": "4.18.0",
   "main": "index.js",
   "keywords": [],
   "author": "Just Eat Takeaway.com - Design System Team",
@@ -31,7 +31,7 @@
   "devDependencies": {
     "@11ty/eleventy": "2.0.1",
     "@11ty/eleventy-navigation": "0.3.5",
-    "@justeattakeaway/pie-monorepo-utils": "0.0.0",
+    "@justeattakeaway/pie-monorepo-utils": "0.1.0",
     "eleventy-plugin-rev": "1.1.1",
     "eleventy-sass": "2.2.3",
     "markdown-it-attrs": "4.1.6"

diff --git a/apps/pie-docs/src/engineers/web-components/integration-guides/nextjs-14.md b/apps/pie-docs/src/engineers/web-components/integration-guides/nextjs-14.md
@@ -0,0 +1,92 @@
+---
+eleventyNavigation:
+    key: NextJS 14 Integration
+    parent: engineers-web-components
+    order: 3
+---
+
+## Installation
+Please install the following JET dependencies (examples use `yarn` but feel free to use `npm` if preferred):
+
+```bash
+yarn add @justeattakeaway/pie-css @justeattakeaway/pie-webc @justeattakeaway/pie-icons-webc
+```
+
+And the following third party dependencies:
+```bash
+yarn add @lit-labs/nextjs @lit/react
+```
+---
+
+## Setup
+
+### CSS and Design Token variables
+You should import [@justeattakeaway/pie-css](https://www.npmjs.com/package/@justeattakeaway/pie-css) into your root component file (or wherever you prefer) so that the variables it provides are globally available (some of these variables are used by the component styles):
+
+```js
+// Example - /src/app/layout.tsx
+import '@justeattakeaway/pie-css';
+```
+
+For more information on `pie-css` please take a look at the package [readme](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css)
+
+### Typography
+We have a [dedicated page](/foundations/typography/code/) which explains how to set up typography. In short, you need to install the JET fonts and set up the appropriate `font-face` CSS code.
+
+### NextJS 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
+
+{% notification {
+  type: "information",
+  message: "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."
+} %}
+
+It is recommended to import all components from [@justeattakeaway/pie-webc](https://www.npmjs.com/package/@justeattakeaway/pie-webc). For React-based applications, there is a `/react/` entry point 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>
+    );
+}
+```
+
+{% notification {
+  type: "information",
+  message: "Check individual component `code` pages on this website to see how to use them specifically in your application. Such as [PIE Button](/components/button/code/)."
+} %}
+
+You should now be able to use any components you need in your NextJS application!
+
+Please reach out to us if you have any troubles or spot any errors in our guide.
diff --git a/apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md b/apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md
@@ -0,0 +1,133 @@
+---
+eleventyNavigation:
+    key: Nuxt 3 Integration
+    parent: engineers-web-components
+    order: 2
+---
+
+## Installation
+Please install the following JET dependencies (examples use `yarn` but feel free to use `npm` if preferred):
+
+```bash
+yarn add @justeattakeaway/pie-css @justeattakeaway/pie-webc @justeattakeaway/pie-icons-webc
+```
+
+And the following third party dependencies:
+```bash
+yarn add nuxt-ssr-lit
+```
+
+## Setup
+
+### CSS and Design Token variables
+You should add [@justeattakeaway/pie-css](https://www.npmjs.com/package/@justeattakeaway/pie-css) into your Nuxt config file (or wherever you prefer) so that the variables it provides are globally available (some of these variables are used by the component styles):
+
+```js
+// Example Nuxt Config - most of the properties removed for demonstration.
+export default defineNuxtConfig({
+  css: ['@justeattakeaway/pie-css'],
+});
+```
+
+For more information on `pie-css` please take a look at the package [readme](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css)
+
+### Typography
+We have a [dedicated page](/foundations/typography/code/) which explains how to set up typography. In short, you need to install the JET fonts and set up the appropriate `font-face` CSS code.
+
+### Nuxt config
+
+To get our components working, ensure you are applying the following rules to your `nuxt.config.ts` file:
+
+```ts
+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>
+```
+
+{% notification {
+  type: "information",
+  message: "Check individual component \`code\` pages on this website to see how to use them specifically in your application. Such as [PIE Button](/components/button/code/)."
+} %}
+
+You should now be able to use any components you need in your Nuxt application!
+
+Please reach out to us if you have any troubles or spot any errors in our guide.
diff --git a/apps/pie-docs/src/engineers/web-components/overview.md b/apps/pie-docs/src/engineers/web-components/overview.md
@@ -8,7 +8,7 @@ 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. 
+[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.
 
@@ -28,13 +28,15 @@ ___
 
 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:
+### Integration Guides
+For integrating our components with specific frameworks, 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](/engineers/web-components/integration-guides/nuxt-3/)
 
-[Nuxt 3 Integration Guide](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Nuxt-3)
+- [NextJS 14](/engineers/web-components/integration-guides/nextjs-14/)
 
-[Vue & Nuxt ‐ Known gotchas](https://github.com/justeattakeaway/pie/wiki/Vue-Nuxt-%E2%80%90-Known-gotchas)
+### Other guides
+- [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.
 

diff --git a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json
@@ -96,6 +96,8 @@
     "engineers/guidelines",
     "engineers/guidelines/browser-support",
     "engineers/web-components",
+    "engineers/web-components/integration-guides/nextjs-14",
+    "engineers/web-components/integration-guides/nuxt-3",
     "foundations",
     "foundations/colour",
     "foundations/colour/tokens/alias/dark",

diff --git a/apps/pie-storybook/CHANGELOG.md b/apps/pie-storybook/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.15.0
+
+### Minor Changes
+
+- [Added] - Refactor to use @justeattakeaway/pie-monorepo-utils to import component statuses ([#2034](https://github.com/justeattakeaway/pie/pull/2034)) by [@siggerzz](https://github.com/siggerzz)
+
 ## 1.14.0
 
 ### Minor Changes

diff --git a/apps/pie-storybook/package.json b/apps/pie-storybook/package.json
@@ -1,6 +1,6 @@
 {
   "name": "pie-storybook",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "private": true,
   "description": "Storybook for PIE Design System components",
   "scripts": {
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@justeattakeaway/pie-icons-configs": "4.5.1",
-    "@justeattakeaway/pie-monorepo-utils": "0.0.0",
+    "@justeattakeaway/pie-monorepo-utils": "0.1.0",
     "@storybook/addon-a11y": "8.3.0",
     "@storybook/addon-designs": "8.0.3",
     "@storybook/addon-essentials": "8.3.0",

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "pie-monorepo",
   "description": "The home of Just Eat Takeaway.com's PIE Design System.",
-  "version": "2.70.0",
+  "version": "2.71.0",
   "keywords": [],
   "author": "Just Eat Takeaway.com - Design System Team",
   "license": "Apache-2.0",

diff --git a/packages/tools/pie-monorepo-utils/CHANGELOG.md b/packages/tools/pie-monorepo-utils/CHANGELOG.md
@@ -0,0 +1,12 @@
+# @justeattakeaway/pie-monorepo-utils
+
+## 0.1.0
+
+### Minor Changes
+
+- [Added] - Renamed `pie-git-hooks-scripts` to `pie-monorepo-utils` ([#2034](https://github.com/justeattakeaway/pie/pull/2034)) by [@siggerzz](https://github.com/siggerzz)
+
+  **Old Changelog entries from `pie-git-hooks-scripts`**
+
+  [Changed] - Exported files for use in consuming repos ([#1206](https://github.com/justeattakeaway/pie/pull/1206)) by [@siggerzz](https://github.com/siggerzz)
+  [Added] - scripts for verifying branch name and commit message format ([#625](https://github.com/justeattakeaway/pie/pull/625)) by [@fernandofranca](https://github.com/fernandofranca)